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/.gitignore b/.gitignore
index 6c48782f9ac..d349da81db0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,5 @@ apps/web/src/components/__screenshots__
 __screenshots__/
 .tanstack
 squashfs-root/
+.vercel
+.claude/worktrees/
diff --git a/.plans/19-remote-endpoints-hosted-static.md b/.plans/19-remote-endpoints-hosted-static.md
new file mode 100644
index 00000000000..2fa0bc70211
--- /dev/null
+++ b/.plans/19-remote-endpoints-hosted-static.md
@@ -0,0 +1,350 @@
+# 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/REMOTE.md b/REMOTE.md
index c0389d235ba..cbe207823f1 100644
--- a/REMOTE.md
+++ b/REMOTE.md
@@ -28,9 +28,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.
@@ -53,14 +85,42 @@ 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.
+
 ## How Pairing Works
 
 The remote device does not need a long-lived secret up front.
@@ -73,6 +133,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.
@@ -90,4 +164,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/package.json b/apps/desktop/package.json
index 0be83f96dcf..9e4e5eec28c 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -15,21 +15,22 @@
     "smoke-test": "node scripts/smoke-test.mjs"
   },
   "dependencies": {
+    "@effect/platform-node": "catalog:",
     "effect": "catalog:",
-    "electron": "40.8.5",
+    "electron": "40.9.3",
     "electron-updater": "^6.6.2"
   },
   "devDependencies": {
+    "@t3tools/client-runtime": "workspace:*",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/shared": "workspace:*",
+    "@t3tools/ssh": "workspace:*",
+    "@t3tools/tailscale": "workspace:*",
     "@types/node": "catalog:",
     "effect-acp": "workspace:*",
     "tsdown": "catalog:",
     "typescript": "catalog:",
     "vitest": "catalog:"
   },
-  "productName": "T3 Code (Alpha)",
-  "trustedDependencies": [
-    "electron"
-  ]
+  "productName": "T3 Code (Alpha)"
 }
diff --git a/apps/desktop/src/clientPersistence.test.ts b/apps/desktop/src/clientPersistence.test.ts
index 192d7ac1064..d4c4768d2c8 100644
--- a/apps/desktop/src/clientPersistence.test.ts
+++ b/apps/desktop/src/clientPersistence.test.ts
@@ -52,8 +52,10 @@ const clientSettings: ClientSettings = {
   autoOpenPlanSidebar: false,
   confirmThreadArchive: true,
   confirmThreadDelete: false,
+  diffIgnoreWhitespace: true,
   diffWordWrap: true,
   favorites: [],
+  providerModelPreferences: {},
   sidebarProjectGroupingMode: "repository_path",
   sidebarProjectGroupingOverrides: {
     "environment-1:/tmp/project-a": "separate",
@@ -70,6 +72,12 @@ const savedRegistryRecord: PersistedSavedEnvironmentRecord = {
   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,
+  },
 };
 
 describe("clientPersistence", () => {
diff --git a/apps/desktop/src/clientPersistence.ts b/apps/desktop/src/clientPersistence.ts
index ad08a0036f1..09a3494dbc7 100644
--- a/apps/desktop/src/clientPersistence.ts
+++ b/apps/desktop/src/clientPersistence.ts
@@ -57,6 +57,12 @@ function isPersistedSavedEnvironmentStorageRecord(
     typeof value.wsBaseUrl === "string" &&
     typeof value.createdAt === "string" &&
     (value.lastConnectedAt === null || typeof value.lastConnectedAt === "string") &&
+    (value.desktopSsh === undefined ||
+      (Predicate.isObject(value.desktopSsh) &&
+        typeof value.desktopSsh.alias === "string" &&
+        typeof value.desktopSsh.hostname === "string" &&
+        (value.desktopSsh.username === null || typeof value.desktopSsh.username === "string") &&
+        (value.desktopSsh.port === null || typeof value.desktopSsh.port === "number"))) &&
     (value.encryptedBearerToken === undefined || typeof value.encryptedBearerToken === "string")
   );
 }
@@ -77,7 +83,7 @@ function readSavedEnvironmentRegistryDocument(filePath: string): SavedEnvironmen
 function toPersistedSavedEnvironmentRecord(
   record: PersistedSavedEnvironmentStorageRecord,
 ): PersistedSavedEnvironmentRecord {
-  return {
+  const nextRecord = {
     environmentId: record.environmentId,
     label: record.label,
     httpBaseUrl: record.httpBaseUrl,
@@ -85,6 +91,7 @@ function toPersistedSavedEnvironmentRecord(
     createdAt: record.createdAt,
     lastConnectedAt: record.lastConnectedAt,
   };
+  return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
 }
 
 export function readClientSettings(settingsPath: string): ClientSettings | null {
@@ -134,6 +141,7 @@ export function writeSavedEnvironmentRegistry(
             wsBaseUrl: record.wsBaseUrl,
             createdAt: record.createdAt,
             lastConnectedAt: record.lastConnectedAt,
+            ...(record.desktopSsh ? { desktopSsh: record.desktopSsh } : {}),
             encryptedBearerToken,
           }
         : record;
@@ -189,7 +197,7 @@ export function writeSavedEnvironmentSecret(input: {
       const encryptedBearerToken = input.secretStorage
         .encryptString(input.secret)
         .toString("base64");
-      return {
+      const nextRecord = {
         environmentId: record.environmentId,
         label: record.label,
         httpBaseUrl: record.httpBaseUrl,
@@ -197,7 +205,8 @@ export function writeSavedEnvironmentSecret(input: {
         createdAt: record.createdAt,
         lastConnectedAt: record.lastConnectedAt,
         encryptedBearerToken,
-      } satisfies PersistedSavedEnvironmentStorageRecord;
+      };
+      return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
     }),
   } satisfies SavedEnvironmentRegistryDocument);
   return found;
diff --git a/apps/desktop/src/desktopSettings.test.ts b/apps/desktop/src/desktopSettings.test.ts
index 9b467d22cab..cc58dc810ef 100644
--- a/apps/desktop/src/desktopSettings.test.ts
+++ b/apps/desktop/src/desktopSettings.test.ts
@@ -9,6 +9,7 @@ import {
   readDesktopSettings,
   resolveDefaultDesktopSettings,
   setDesktopServerExposurePreference,
+  setDesktopTailscaleServePreference,
   setDesktopUpdateChannelPreference,
   writeDesktopSettings,
 } from "./desktopSettings.ts";
@@ -35,6 +36,8 @@ describe("desktopSettings", () => {
   it("defaults packaged nightly builds to the nightly update channel", () => {
     expect(resolveDefaultDesktopSettings("0.0.17-nightly.20260415.1")).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "nightly",
       updateChannelConfiguredByUser: false,
     });
@@ -45,12 +48,16 @@ describe("desktopSettings", () => {
 
     writeDesktopSettings(settingsPath, {
       serverExposureMode: "network-accessible",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 8443,
       updateChannel: "latest",
       updateChannelConfiguredByUser: true,
     });
 
     expect(readDesktopSettings(settingsPath, "0.0.17")).toEqual({
       serverExposureMode: "network-accessible",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 8443,
       updateChannel: "latest",
       updateChannelConfiguredByUser: true,
     });
@@ -61,6 +68,8 @@ describe("desktopSettings", () => {
       setDesktopServerExposurePreference(
         {
           serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
           updateChannel: "latest",
           updateChannelConfiguredByUser: false,
         },
@@ -68,6 +77,50 @@ describe("desktopSettings", () => {
       ),
     ).toEqual({
       serverExposureMode: "network-accessible",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
+      updateChannel: "latest",
+      updateChannelConfiguredByUser: false,
+    });
+  });
+
+  it("persists the requested Tailscale Serve preference", () => {
+    expect(
+      setDesktopTailscaleServePreference(
+        {
+          serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: false,
+        },
+        { enabled: true, port: 8443 },
+      ),
+    ).toEqual({
+      serverExposureMode: "local-only",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 8443,
+      updateChannel: "latest",
+      updateChannelConfiguredByUser: false,
+    });
+  });
+
+  it("preserves the configured Tailscale Serve port when no new port is requested", () => {
+    expect(
+      setDesktopTailscaleServePreference(
+        {
+          serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 8443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: false,
+        },
+        { enabled: true },
+      ),
+    ).toEqual({
+      serverExposureMode: "local-only",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 8443,
       updateChannel: "latest",
       updateChannelConfiguredByUser: false,
     });
@@ -78,6 +131,8 @@ describe("desktopSettings", () => {
       setDesktopUpdateChannelPreference(
         {
           serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
           updateChannel: "latest",
           updateChannelConfiguredByUser: false,
         },
@@ -85,6 +140,8 @@ describe("desktopSettings", () => {
       ),
     ).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "nightly",
       updateChannelConfiguredByUser: true,
     });
@@ -103,6 +160,8 @@ describe("desktopSettings", () => {
 
     expect(readDesktopSettings(settingsPath, "0.0.17-nightly.20260415.1")).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "nightly",
       updateChannelConfiguredByUser: false,
     });
@@ -121,6 +180,8 @@ describe("desktopSettings", () => {
 
     expect(readDesktopSettings(settingsPath, "0.0.17-nightly.20260415.1")).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "nightly",
       updateChannelConfiguredByUser: false,
     });
@@ -140,8 +201,30 @@ describe("desktopSettings", () => {
 
     expect(readDesktopSettings(settingsPath, "0.0.17-nightly.20260415.1")).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "latest",
       updateChannelConfiguredByUser: true,
     });
   });
+
+  it("falls back to the default Tailscale Serve port when the persisted port is invalid", () => {
+    const settingsPath = makeSettingsPath();
+    fs.writeFileSync(
+      settingsPath,
+      JSON.stringify({
+        tailscaleServeEnabled: true,
+        tailscaleServePort: 0,
+      }),
+      "utf8",
+    );
+
+    expect(readDesktopSettings(settingsPath, "0.0.17")).toEqual({
+      serverExposureMode: "local-only",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 443,
+      updateChannel: "latest",
+      updateChannelConfiguredByUser: false,
+    });
+  });
 });
diff --git a/apps/desktop/src/desktopSettings.ts b/apps/desktop/src/desktopSettings.ts
index 6ece5189cce..5a61faef803 100644
--- a/apps/desktop/src/desktopSettings.ts
+++ b/apps/desktop/src/desktopSettings.ts
@@ -6,12 +6,18 @@ import { resolveDefaultDesktopUpdateChannel } from "./updateChannels.ts";
 
 export interface DesktopSettings {
   readonly serverExposureMode: DesktopServerExposureMode;
+  readonly tailscaleServeEnabled: boolean;
+  readonly tailscaleServePort: number;
   readonly updateChannel: DesktopUpdateChannel;
   readonly updateChannelConfiguredByUser: 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,
 };
@@ -35,6 +41,29 @@ export function setDesktopServerExposurePreference(
       };
 }
 
+export function setDesktopTailscaleServePreference(
+  settings: DesktopSettings,
+  input: { readonly enabled: boolean; readonly port?: number },
+): DesktopSettings {
+  const port =
+    input.port === undefined
+      ? settings.tailscaleServePort
+      : normalizeTailscaleServePort(input.port);
+  return settings.tailscaleServeEnabled === input.enabled && settings.tailscaleServePort === port
+    ? settings
+    : {
+        ...settings,
+        tailscaleServeEnabled: input.enabled,
+        tailscaleServePort: port,
+      };
+}
+
+export function normalizeTailscaleServePort(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65_535
+    ? value
+    : DEFAULT_TAILSCALE_SERVE_PORT;
+}
+
 export function setDesktopUpdateChannelPreference(
   settings: DesktopSettings,
   requestedChannel: DesktopUpdateChannel,
@@ -57,6 +86,8 @@ export function readDesktopSettings(settingsPath: string, appVersion: string): D
     const raw = FS.readFileSync(settingsPath, "utf8");
     const parsed = JSON.parse(raw) as {
       readonly serverExposureMode?: unknown;
+      readonly tailscaleServeEnabled?: unknown;
+      readonly tailscaleServePort?: unknown;
       readonly updateChannel?: unknown;
       readonly updateChannelConfiguredByUser?: unknown;
     };
@@ -72,6 +103,8 @@ export function readDesktopSettings(settingsPath: string, appVersion: string): D
     return {
       serverExposureMode:
         parsed.serverExposureMode === "network-accessible" ? "network-accessible" : "local-only",
+      tailscaleServeEnabled: parsed.tailscaleServeEnabled === true,
+      tailscaleServePort: normalizeTailscaleServePort(parsed.tailscaleServePort),
       updateChannel:
         updateChannelConfiguredByUser && parsedUpdateChannel !== null
           ? parsedUpdateChannel
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 5cf6a8fd152..78dc62e8885 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -36,11 +36,14 @@ import { autoUpdater } from "electron-updater";
 import type { ContextMenuItem } from "@t3tools/contracts";
 import { RotatingFileSink } from "@t3tools/shared/logging";
 import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
+import type { RemoteT3RunnerOptions } from "@t3tools/ssh/tunnel";
 import { DEFAULT_DESKTOP_BACKEND_PORT, resolveDesktopBackendPort } from "./backendPort.ts";
 import {
+  type DesktopSettings,
   DEFAULT_DESKTOP_SETTINGS,
   readDesktopSettings,
   setDesktopServerExposurePreference,
+  setDesktopTailscaleServePreference,
   setDesktopUpdateChannelPreference,
   writeDesktopSettings,
 } from "./desktopSettings.ts";
@@ -55,7 +58,11 @@ import {
 } from "./clientPersistence.ts";
 import { isBackendReadinessAborted, waitForHttpReady } from "./backendReadiness.ts";
 import { showDesktopConfirmDialog } from "./confirmDialog.ts";
-import { resolveDesktopServerExposure } from "./serverExposure.ts";
+import {
+  resolveDesktopCoreAdvertisedEndpoints,
+  resolveDesktopServerExposure,
+} from "./serverExposure.ts";
+import { DesktopSshEnvironmentBridge, resolveRemoteT3CliPackageSpec } from "./sshEnvironment.ts";
 import { syncShellEnvironment } from "./syncShellEnvironment.ts";
 import { waitForBackendStartupReady } from "./backendStartupReadiness.ts";
 import { getAutoUpdateDisabledReason, shouldBroadcastDownloadProgress } from "./updateState.ts";
@@ -76,6 +83,7 @@ import {
 import { isArm64HostRunningIntelBuild, resolveDesktopRuntimeInfo } from "./runtimeArch.ts";
 import { resolveDesktopAppBranding } from "./appBranding.ts";
 import { bindFirstRevealTrigger, type RevealSubscription } from "./windowReveal.ts";
+import { resolveTailscaleAdvertisedEndpoints } from "./tailscaleEndpointProvider.ts";
 
 syncShellEnvironment();
 
@@ -107,6 +115,8 @@ const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secr
 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 SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
+const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
 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");
@@ -115,6 +125,11 @@ const SAVED_ENVIRONMENT_REGISTRY_PATH = Path.join(STATE_DIR, "saved-environments
 const DESKTOP_SCHEME = "t3";
 const ROOT_DIR = Path.resolve(__dirname, "../../..");
 const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
+// Dev-only SSH launcher override. Set this to an absolute path on the SSH host
+// for a built server entry, for example:
+// "/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs"
+const DEV_REMOTE_T3_SERVER_ENTRY_PATH =
+  process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ?? "";
 const desktopAppBranding: DesktopAppBranding = resolveDesktopAppBranding({
   isDevelopment,
   appVersion: app.getVersion(),
@@ -302,6 +317,9 @@ function backendChildEnv(): NodeJS.ProcessEnv {
   delete env.T3CODE_DESKTOP_WS_URL;
   delete env.T3CODE_DESKTOP_LAN_ACCESS;
   delete env.T3CODE_DESKTOP_LAN_HOST;
+  delete env.T3CODE_DESKTOP_HTTPS_ENDPOINTS;
+  delete env.T3CODE_TAILSCALE_SERVE;
+  delete env.T3CODE_TAILSCALE_SERVE_PORT;
   return env;
 }
 
@@ -310,9 +328,32 @@ function getDesktopServerExposureState(): DesktopServerExposureState {
     mode: desktopServerExposureMode,
     endpointUrl: backendEndpointUrl,
     advertisedHost: backendAdvertisedHost,
+    tailscaleServeEnabled: desktopSettings.tailscaleServeEnabled,
+    tailscaleServePort: desktopSettings.tailscaleServePort,
   };
 }
 
+async function getDesktopAdvertisedEndpoints() {
+  const exposure = resolveDesktopServerExposure({
+    mode: desktopServerExposureMode,
+    port: backendPort,
+    networkInterfaces: OS.networkInterfaces(),
+    ...(backendAdvertisedHost ? { advertisedHostOverride: backendAdvertisedHost } : {}),
+  });
+  const coreEndpoints = resolveDesktopCoreAdvertisedEndpoints({
+    port: backendPort,
+    exposure,
+    customHttpsEndpointUrls: resolveCustomHttpsEndpointUrls(),
+  });
+  const tailscaleEndpoints = await resolveTailscaleAdvertisedEndpoints({
+    port: backendPort,
+    serveEnabled: desktopSettings.tailscaleServeEnabled,
+    servePort: desktopSettings.tailscaleServePort,
+    networkInterfaces: OS.networkInterfaces(),
+  });
+  return [...coreEndpoints, ...tailscaleEndpoints];
+}
+
 function getDesktopSecretStorage() {
   return {
     isEncryptionAvailable: () => safeStorage.isEncryptionAvailable(),
@@ -326,9 +367,19 @@ function resolveAdvertisedHostOverride(): string | undefined {
   return override && override.length > 0 ? override : undefined;
 }
 
+function resolveCustomHttpsEndpointUrls(): readonly string[] {
+  return (process.env.T3CODE_DESKTOP_HTTPS_ENDPOINTS ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
 async function applyDesktopServerExposureMode(
   mode: DesktopServerExposureMode,
-  options?: { readonly persist?: boolean; readonly rejectIfUnavailable?: boolean },
+  options?: {
+    readonly persist?: boolean;
+    readonly rejectIfUnavailable?: boolean;
+  },
 ): Promise<DesktopServerExposureState> {
   const advertisedHostOverride = resolveAdvertisedHostOverride();
   const requestedMode = mode;
@@ -366,6 +417,17 @@ async function applyDesktopServerExposureMode(
   return getDesktopServerExposureState();
 }
 
+async function applyDesktopTailscaleServeEnabled(
+  nextSettings: DesktopSettings,
+): Promise<DesktopServerExposureState> {
+  desktopSettings = nextSettings;
+  writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
+  relaunchDesktopApp(
+    desktopSettings.tailscaleServeEnabled ? "tailscale-serve-enabled" : "tailscale-serve-disabled",
+  );
+  return getDesktopServerExposureState();
+}
+
 function relaunchDesktopApp(reason: string): void {
   writeDesktopLogHeader(`desktop relaunch requested reason=${reason}`);
   setImmediate(() => {
@@ -378,6 +440,7 @@ function relaunchDesktopApp(reason: string): void {
           `desktop relaunch backend shutdown warning message=${formatErrorMessage(error)}`,
         );
       })
+      .then(() => desktopSshEnvironmentBridge.dispose().catch(() => undefined))
       .finally(() => {
         restoreStdIoCapture?.();
         if (isDevelopment) {
@@ -634,6 +697,22 @@ let updateInstallInFlight = false;
 let updaterConfigured = false;
 let updateState: DesktopUpdateState = initialUpdateState();
 
+const desktopSshEnvironmentBridge = new DesktopSshEnvironmentBridge({
+  getMainWindow: () => mainWindow,
+  resolveCliRunner: (): RemoteT3RunnerOptions => {
+    if (isDevelopment && DEV_REMOTE_T3_SERVER_ENTRY_PATH.length > 0) {
+      return { nodeScriptPath: DEV_REMOTE_T3_SERVER_ENTRY_PATH };
+    }
+    return {
+      packageSpec: resolveRemoteT3CliPackageSpec({
+        appVersion: app.getVersion(),
+        updateChannel: desktopSettings.updateChannel,
+        isDevelopment,
+      }),
+    };
+  },
+});
+
 function resolveUpdaterErrorContext(): DesktopUpdateErrorContext {
   if (updateInstallInFlight) return "install";
   if (updateDownloadInFlight) return "download";
@@ -1185,7 +1264,10 @@ async function checkForUpdates(reason: string): Promise<boolean> {
   }
 }
 
-async function downloadAvailableUpdate(): Promise<{ accepted: boolean; completed: boolean }> {
+async function downloadAvailableUpdate(): Promise<{
+  accepted: boolean;
+  completed: boolean;
+}> {
   if (!updaterConfigured || updateDownloadInFlight || updateState.status !== "available") {
     return { accepted: false, completed: false };
   }
@@ -1207,7 +1289,10 @@ async function downloadAvailableUpdate(): Promise<{ accepted: boolean; completed
   }
 }
 
-async function installDownloadedUpdate(): Promise<{ accepted: boolean; completed: boolean }> {
+async function installDownloadedUpdate(): Promise<{
+  accepted: boolean;
+  completed: boolean;
+}> {
   if (isQuitting || !updaterConfigured || updateState.status !== "downloaded") {
     return { accepted: false, completed: false };
   }
@@ -1393,6 +1478,8 @@ function startBackend(): void {
         t3Home: BASE_DIR,
         host: backendBindHost,
         desktopBootstrapToken: backendBootstrapToken,
+        tailscaleServeEnabled: desktopSettings.tailscaleServeEnabled,
+        tailscaleServePort: desktopSettings.tailscaleServePort,
         ...(backendObservabilitySettings.otlpTracesUrl
           ? { otlpTracesUrl: backendObservabilitySettings.otlpTracesUrl }
           : {}),
@@ -1638,6 +1725,8 @@ function registerIpcHandlers(): void {
     },
   );
 
+  desktopSshEnvironmentBridge.registerIpcHandlers(ipcMain);
+
   ipcMain.removeHandler(GET_SERVER_EXPOSURE_STATE_CHANNEL);
   ipcMain.handle(GET_SERVER_EXPOSURE_STATE_CHANNEL, async () => getDesktopServerExposureState());
 
@@ -1660,6 +1749,31 @@ function registerIpcHandlers(): void {
     return nextState;
   });
 
+  ipcMain.removeHandler(SET_TAILSCALE_SERVE_ENABLED_CHANNEL);
+  ipcMain.handle(SET_TAILSCALE_SERVE_ENABLED_CHANNEL, async (_event, rawInput: unknown) => {
+    if (typeof rawInput !== "object" || rawInput === null) {
+      throw new Error("Invalid Tailscale Serve input.");
+    }
+    const input = rawInput as {
+      readonly enabled?: unknown;
+      readonly port?: unknown;
+    };
+    if (typeof input.enabled !== "boolean") {
+      throw new Error("Invalid Tailscale Serve input.");
+    }
+    const nextSettings = setDesktopTailscaleServePreference(desktopSettings, {
+      enabled: input.enabled,
+      ...(typeof input.port === "number" ? { port: input.port } : {}),
+    });
+    if (nextSettings === desktopSettings) {
+      return getDesktopServerExposureState();
+    }
+    return applyDesktopTailscaleServeEnabled(nextSettings);
+  });
+
+  ipcMain.removeHandler(GET_ADVERTISED_ENDPOINTS_CHANNEL);
+  ipcMain.handle(GET_ADVERTISED_ENDPOINTS_CHANNEL, async () => getDesktopAdvertisedEndpoints());
+
   ipcMain.removeHandler(PICK_FOLDER_CHANNEL);
   ipcMain.handle(PICK_FOLDER_CHANNEL, async (_event, rawOptions: unknown) => {
     const owner = BrowserWindow.getFocusedWindow() ?? mainWindow;
@@ -1987,7 +2101,10 @@ function createWindow(): BrowserWindow {
     const externalUrl = getSafeExternalUrl(params.linkURL);
     if (externalUrl) {
       menuTemplate.push(
-        { label: "Copy Link", click: () => clipboard.writeText(params.linkURL) },
+        {
+          label: "Copy Link",
+          click: () => clipboard.writeText(params.linkURL),
+        },
         { type: "separator" },
       );
     }
@@ -2047,6 +2164,9 @@ function createWindow(): BrowserWindow {
   }
 
   window.on("closed", () => {
+    desktopSshEnvironmentBridge.cancelPendingPasswordPrompts(
+      "SSH authentication was cancelled because the app window closed.",
+    );
     if (mainWindow === window) {
       mainWindow = null;
     }
@@ -2137,6 +2257,7 @@ app.on("before-quit", () => {
   clearUpdatePollTimer();
   cancelBackendReadinessWait();
   stopBackend();
+  void desktopSshEnvironmentBridge.dispose().catch(() => undefined);
   restoreStdIoCapture?.();
 });
 
@@ -2186,6 +2307,7 @@ if (process.platform !== "win32") {
     clearUpdatePollTimer();
     cancelBackendReadinessWait();
     stopBackend();
+    void desktopSshEnvironmentBridge.dispose().catch(() => undefined);
     restoreStdIoCapture?.();
     app.quit();
   });
@@ -2196,6 +2318,7 @@ if (process.platform !== "win32") {
     writeDesktopLogHeader("SIGTERM received");
     clearUpdatePollTimer();
     stopBackend();
+    void desktopSshEnvironmentBridge.dispose().catch(() => undefined);
     restoreStdIoCapture?.();
     app.quit();
   });
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index 2e345b9e555..91e99ad5294 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -26,8 +26,36 @@ const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-re
 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 DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
+const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
+const DISCONNECT_SSH_ENVIRONMENT_CHANNEL = "desktop:disconnect-ssh-environment";
+const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
+const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
+const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
+const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
+const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
+const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
+const SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
+const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
+const SSH_PASSWORD_PROMPT_CANCELLED_RESULT = "ssh-password-prompt-cancelled";
+
+function unwrapEnsureSshEnvironmentResult(result: unknown) {
+  if (
+    typeof result === "object" &&
+    result !== null &&
+    "type" in result &&
+    result.type === 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: () => {
@@ -55,8 +83,39 @@ contextBridge.exposeInMainWorld("desktopBridge", {
     ipcRenderer.invoke(SET_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId, secret),
   removeSavedEnvironmentSecret: (environmentId) =>
     ipcRenderer.invoke(REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId),
+  discoverSshHosts: () => ipcRenderer.invoke(DISCOVER_SSH_HOSTS_CHANNEL),
+  ensureSshEnvironment: async (target, options) =>
+    unwrapEnsureSshEnvironmentResult(
+      await ipcRenderer.invoke(ENSURE_SSH_ENVIRONMENT_CHANNEL, target, options),
+    ),
+  disconnectSshEnvironment: (target) =>
+    ipcRenderer.invoke(DISCONNECT_SSH_ENVIRONMENT_CHANNEL, target),
+  fetchSshEnvironmentDescriptor: (httpBaseUrl) =>
+    ipcRenderer.invoke(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, httpBaseUrl),
+  bootstrapSshBearerSession: (httpBaseUrl, credential) =>
+    ipcRenderer.invoke(BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL, httpBaseUrl, credential),
+  fetchSshSessionState: (httpBaseUrl, bearerToken) =>
+    ipcRenderer.invoke(FETCH_SSH_SESSION_STATE_CHANNEL, httpBaseUrl, bearerToken),
+  issueSshWebSocketToken: (httpBaseUrl, bearerToken) =>
+    ipcRenderer.invoke(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(SSH_PASSWORD_PROMPT_CHANNEL, wrappedListener);
+    return () => {
+      ipcRenderer.removeListener(SSH_PASSWORD_PROMPT_CHANNEL, wrappedListener);
+    };
+  },
+  resolveSshPasswordPrompt: (requestId, password) =>
+    ipcRenderer.invoke(RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL, requestId, password),
   getServerExposureState: () => ipcRenderer.invoke(GET_SERVER_EXPOSURE_STATE_CHANNEL),
   setServerExposureMode: (mode) => ipcRenderer.invoke(SET_SERVER_EXPOSURE_MODE_CHANNEL, mode),
+  setTailscaleServeEnabled: (input) =>
+    ipcRenderer.invoke(SET_TAILSCALE_SERVE_ENABLED_CHANNEL, input),
+  getAdvertisedEndpoints: () => ipcRenderer.invoke(GET_ADVERTISED_ENDPOINTS_CHANNEL),
   pickFolder: (options) => ipcRenderer.invoke(PICK_FOLDER_CHANNEL, options),
   confirm: (message) => ipcRenderer.invoke(CONFIRM_CHANNEL, message),
   setTheme: (theme) => ipcRenderer.invoke(SET_THEME_CHANNEL, theme),
diff --git a/apps/desktop/src/serverExposure.test.ts b/apps/desktop/src/serverExposure.test.ts
index c83bbc210e0..4e284ef42bd 100644
--- a/apps/desktop/src/serverExposure.test.ts
+++ b/apps/desktop/src/serverExposure.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
-import { resolveDesktopServerExposure, resolveLanAdvertisedHost } from "./serverExposure.ts";
+import {
+  resolveDesktopCoreAdvertisedEndpoints,
+  resolveDesktopServerExposure,
+  resolveLanAdvertisedHost,
+} from "./serverExposure.ts";
 
 describe("resolveLanAdvertisedHost", () => {
   it("prefers an explicit host override", () => {
@@ -74,6 +78,121 @@ describe("resolveLanAdvertisedHost", () => {
   });
 });
 
+describe("resolveDesktopCoreAdvertisedEndpoints", () => {
+  it("advertises loopback and LAN endpoints without provider-specific assumptions", () => {
+    const exposure = 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",
+          },
+        ],
+      },
+    });
+
+    expect(
+      resolveDesktopCoreAdvertisedEndpoints({
+        port: 3773,
+        exposure,
+        customHttpsEndpointUrls: [
+          "https://desktop.example.ts.net",
+          "http://desktop.example.test:3773",
+          "not-a-url",
+        ],
+      }),
+    ).toEqual([
+      {
+        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.44:3773",
+        label: "Local network",
+        provider: {
+          id: "desktop-core",
+          label: "Desktop",
+          kind: "core",
+          isAddon: false,
+        },
+        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,
+        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.",
+      },
+    ]);
+  });
+});
+
 describe("resolveDesktopServerExposure", () => {
   it("keeps the desktop server loopback-only when local-only mode is selected", () => {
     expect(
diff --git a/apps/desktop/src/serverExposure.ts b/apps/desktop/src/serverExposure.ts
index 65c99b60e13..b73b850ad13 100644
--- a/apps/desktop/src/serverExposure.ts
+++ b/apps/desktop/src/serverExposure.ts
@@ -1,5 +1,13 @@
 import type { NetworkInterfaceInfo } from "node:os";
-import type { DesktopServerExposureMode } from "@t3tools/contracts";
+import {
+  createAdvertisedEndpoint,
+  type CreateAdvertisedEndpointInput,
+} from "@t3tools/client-runtime";
+import type {
+  AdvertisedEndpoint,
+  AdvertisedEndpointProvider,
+  DesktopServerExposureMode,
+} from "@t3tools/contracts";
 
 const DESKTOP_LOOPBACK_HOST = "127.0.0.1";
 const DESKTOP_LAN_BIND_HOST = "0.0.0.0";
@@ -13,6 +21,26 @@ export interface DesktopServerExposure {
   readonly advertisedHost: string | null;
 }
 
+export interface DesktopAdvertisedEndpointInput {
+  readonly port: number;
+  readonly exposure: DesktopServerExposure;
+  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;
@@ -21,6 +49,14 @@ const normalizeOptionalHost = (value: string | undefined): string | undefined =>
 const isUsableLanIpv4Address = (address: string): boolean =>
   !address.startsWith("127.") && !address.startsWith("169.254.");
 
+function isHttpsEndpointUrl(value: string): boolean {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
 export function resolveLanAdvertisedHost(
   networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>,
   explicitHost: string | undefined,
@@ -78,3 +114,75 @@ export function resolveDesktopServerExposure(input: {
     advertisedHost,
   };
 }
+
+function createDesktopEndpoint(
+  input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
+): AdvertisedEndpoint {
+  return createAdvertisedEndpoint({
+    ...input,
+    provider: DESKTOP_CORE_ENDPOINT_PROVIDER,
+    source: "desktop-core",
+  });
+}
+
+function createManualEndpoint(
+  input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
+): AdvertisedEndpoint {
+  return createAdvertisedEndpoint({
+    ...input,
+    provider: DESKTOP_MANUAL_ENDPOINT_PROVIDER,
+    source: "user",
+  });
+}
+
+export function 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;
+}
diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
new file mode 100644
index 00000000000..d22e09957d1
--- /dev/null
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -0,0 +1,98 @@
+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 { SshPasswordPromptError } from "@t3tools/ssh/errors";
+
+import { discoverDesktopSshHosts, isSshPasswordPromptCancellation } from "./sshEnvironment.ts";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of tempDirectories.splice(0)) {
+    FS.rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function makeTempHomeDir(): string {
+  const directory = FS.mkdtempSync(Path.join(OS.tmpdir(), "t3-ssh-env-test-"));
+  tempDirectories.push(directory);
+  return directory;
+}
+
+describe("sshEnvironment", () => {
+  it("treats password prompt timeouts as cancellable authentication prompts", () => {
+    expect(
+      isSshPasswordPromptCancellation(
+        new SshPasswordPromptError({
+          message: "SSH authentication timed out for devbox.",
+        }),
+      ),
+    ).toBe(true);
+  });
+
+  it("wires desktop host discovery through the ssh package runtime", async () => {
+    const homeDir = makeTempHomeDir();
+    const sshDir = Path.join(homeDir, ".ssh");
+    FS.mkdirSync(Path.join(sshDir, "config.d"), { recursive: true });
+    FS.writeFileSync(
+      Path.join(sshDir, "config"),
+      ["Host devbox", "  HostName devbox.example.com", "Include config.d/*.conf", ""].join("\n"),
+      "utf8",
+    );
+    FS.writeFileSync(
+      Path.join(sshDir, "config.d", "team.conf"),
+      [
+        "Host staging",
+        "  HostName staging.example.com",
+        "Host *",
+        "  ServerAliveInterval 30",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    FS.writeFileSync(
+      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"),
+      "utf8",
+    );
+
+    await expect(discoverDesktopSshHosts({ homeDir })).resolves.toEqual([
+      {
+        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",
+      },
+    ]);
+  });
+});
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
new file mode 100644
index 00000000000..e847e07d498
--- /dev/null
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -0,0 +1,420 @@
+import * as Crypto from "node:crypto";
+
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { NetService } from "@t3tools/shared/Net";
+import type {
+  AuthBearerBootstrapResult,
+  AuthSessionState,
+  AuthWebSocketTokenResult,
+  DesktopDiscoveredSshHost,
+  DesktopSshEnvironmentTarget,
+  DesktopSshPasswordPromptRequest,
+  ExecutionEnvironmentDescriptor,
+} from "@t3tools/contracts";
+import {
+  SshPasswordPrompt,
+  type SshPasswordPromptShape,
+  type SshPasswordRequest,
+} from "@t3tools/ssh/auth";
+import { discoverSshHosts } from "@t3tools/ssh/config";
+import { SshPasswordPromptError } from "@t3tools/ssh/errors";
+import {
+  fetchLoopbackSshJson,
+  SshEnvironmentManager,
+  type RemoteT3RunnerOptions,
+} from "@t3tools/ssh/tunnel";
+import { Effect, Exit, Layer, ManagedRuntime, Scope } from "effect";
+
+export { resolveRemoteT3CliPackageSpec } from "@t3tools/ssh/command";
+
+const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
+const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
+const DISCONNECT_SSH_ENVIRONMENT_CHANNEL = "desktop:disconnect-ssh-environment";
+const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
+const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
+const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
+const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
+const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
+const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
+const DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
+const SSH_PASSWORD_PROMPT_CANCELLED_RESULT = "ssh-password-prompt-cancelled";
+
+interface DesktopSshEnvironmentManagerOptions {
+  readonly passwordProvider?: (request: SshPasswordRequest) => Promise<string | null>;
+  readonly resolveCliPackageSpec?: () => string;
+  readonly resolveCliRunner?: () => RemoteT3RunnerOptions;
+}
+
+const sshRuntime = ManagedRuntime.make(
+  Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici, NetService.layer),
+);
+
+function createDesktopSshRuntime(
+  passwordPrompt: SshPasswordPromptShape,
+  scope: Scope.Scope,
+  options: DesktopSshEnvironmentManagerOptions,
+) {
+  return ManagedRuntime.make(
+    Layer.mergeAll(
+      NodeServices.layer,
+      NodeHttpClient.layerUndici,
+      NetService.layer,
+      Layer.succeed(Scope.Scope, scope),
+      Layer.succeed(SshPasswordPrompt, SshPasswordPrompt.of(passwordPrompt)),
+      SshEnvironmentManager.layer({
+        ...(options.resolveCliPackageSpec === undefined
+          ? {}
+          : { resolveCliPackageSpec: options.resolveCliPackageSpec }),
+        ...(options.resolveCliRunner === undefined
+          ? {}
+          : { resolveCliRunner: options.resolveCliRunner }),
+      }),
+    ),
+  );
+}
+
+export async function discoverDesktopSshHosts(input?: {
+  readonly homeDir?: string;
+}): Promise<readonly DesktopDiscoveredSshHost[]> {
+  return await sshRuntime.runPromise(discoverSshHosts(input ?? {}));
+}
+
+export class DesktopSshEnvironmentManager {
+  private readonly runtime: ReturnType<typeof createDesktopSshRuntime>;
+  private readonly scope: Scope.Scope;
+
+  constructor(options: DesktopSshEnvironmentManagerOptions = {}) {
+    const passwordPrompt: SshPasswordPromptShape = {
+      isAvailable: options.passwordProvider !== undefined,
+      request: (request) => {
+        const passwordProvider = options.passwordProvider;
+        if (!passwordProvider) {
+          return Effect.succeed(null);
+        }
+
+        return Effect.tryPromise({
+          try: () => passwordProvider(request),
+          catch: (cause) =>
+            new SshPasswordPromptError({
+              message: cause instanceof Error ? cause.message : "SSH password prompt failed.",
+              cause,
+            }),
+        });
+      },
+    };
+    this.scope = Effect.runSync(Scope.make());
+    this.runtime = createDesktopSshRuntime(passwordPrompt, this.scope, options);
+  }
+
+  async discoverHosts(): Promise<readonly DesktopDiscoveredSshHost[]> {
+    return await discoverDesktopSshHosts();
+  }
+
+  async ensureEnvironment(
+    target: DesktopSshEnvironmentTarget,
+    options?: { readonly issuePairingToken?: boolean },
+  ) {
+    return await this.runtime.runPromise(
+      Effect.service(SshEnvironmentManager).pipe(
+        Effect.flatMap((manager) => manager.ensureEnvironment(target, options)),
+      ),
+    );
+  }
+
+  async disconnectEnvironment(target: DesktopSshEnvironmentTarget): Promise<void> {
+    await this.runtime.runPromise(
+      Effect.service(SshEnvironmentManager).pipe(
+        Effect.flatMap((manager) => manager.disconnectEnvironment(target)),
+      ),
+    );
+  }
+
+  async dispose(): Promise<void> {
+    await this.runtime.runPromise(Scope.close(this.scope, Exit.void));
+    await this.runtime.dispose();
+  }
+}
+
+function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarget | null {
+  if (typeof rawTarget !== "object" || rawTarget === null) {
+    return null;
+  }
+
+  const target = rawTarget as Partial<DesktopSshEnvironmentTarget>;
+  if (typeof target.alias !== "string" || typeof target.hostname !== "string") {
+    return null;
+  }
+  if (
+    target.username !== null &&
+    target.username !== undefined &&
+    typeof target.username !== "string"
+  ) {
+    return null;
+  }
+  if (target.port !== null && target.port !== undefined && !Number.isInteger(target.port)) {
+    return null;
+  }
+
+  const alias = target.alias.trim();
+  const hostname = target.hostname.trim();
+  if (alias.length === 0 || hostname.length === 0) {
+    return null;
+  }
+
+  return {
+    alias,
+    hostname,
+    username: target.username?.trim() || null,
+    port: target.port ?? null,
+  };
+}
+
+/** Minimal subset of Electron's BrowserWindow used by the SSH bridge. */
+export interface DesktopSshBridgeWindow {
+  isDestroyed(): boolean;
+  isMinimized(): boolean;
+  restore(): void;
+  focus(): void;
+  readonly webContents: {
+    send(channel: string, ...args: readonly unknown[]): void;
+  };
+}
+
+/** Minimal subset of Electron's ipcMain used by the SSH bridge. */
+export interface DesktopSshBridgeIpcMain {
+  removeHandler(channel: string): void;
+  handle(
+    channel: string,
+    listener: (event: unknown, ...args: readonly unknown[]) => unknown | Promise<unknown>,
+  ): void;
+}
+
+export interface DesktopSshEnvironmentBridgeOptions {
+  readonly getMainWindow: () => DesktopSshBridgeWindow | null;
+  readonly resolveCliPackageSpec?: () => string;
+  readonly resolveCliRunner?: () => RemoteT3RunnerOptions;
+  readonly passwordPromptTimeoutMs?: number;
+}
+
+interface PendingSshPasswordPrompt {
+  readonly resolve: (password: string | null) => void;
+  readonly reject: (error: Error) => void;
+  readonly timeout: ReturnType<typeof setTimeout>;
+}
+
+export function isSshPasswordPromptCancellation(error: unknown): error is SshPasswordPromptError {
+  const message = error instanceof SshPasswordPromptError ? error.message.toLowerCase() : "";
+  return (
+    error instanceof SshPasswordPromptError &&
+    (message.includes("cancelled") || message.includes("timed out"))
+  );
+}
+
+/**
+ * Wires the SSH environment manager to Electron IPC, owning the renderer-facing
+ * password prompt state so `main.ts` only needs to register, cancel, and dispose.
+ */
+export class DesktopSshEnvironmentBridge {
+  private readonly options: DesktopSshEnvironmentBridgeOptions;
+  private readonly manager: DesktopSshEnvironmentManager;
+  private readonly pendingPrompts = new Map<string, PendingSshPasswordPrompt>();
+  private readonly passwordPromptTimeoutMs: number;
+
+  constructor(options: DesktopSshEnvironmentBridgeOptions) {
+    this.options = options;
+    this.passwordPromptTimeoutMs =
+      options.passwordPromptTimeoutMs ?? DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS;
+    this.manager = new DesktopSshEnvironmentManager({
+      passwordProvider: (request) => this.requestPasswordFromRenderer(request),
+      ...(options.resolveCliPackageSpec === undefined
+        ? {}
+        : { resolveCliPackageSpec: options.resolveCliPackageSpec }),
+      ...(options.resolveCliRunner === undefined
+        ? {}
+        : { resolveCliRunner: options.resolveCliRunner }),
+    });
+  }
+
+  registerIpcHandlers(ipcMain: DesktopSshBridgeIpcMain): void {
+    ipcMain.removeHandler(DISCOVER_SSH_HOSTS_CHANNEL);
+    ipcMain.handle(DISCOVER_SSH_HOSTS_CHANNEL, async () => this.manager.discoverHosts());
+
+    ipcMain.removeHandler(ENSURE_SSH_ENVIRONMENT_CHANNEL);
+    ipcMain.handle(ENSURE_SSH_ENVIRONMENT_CHANNEL, async (_event, rawTarget, rawOptions) => {
+      const target = getSafeDesktopSshTarget(rawTarget);
+      if (!target) {
+        throw new Error("Invalid desktop SSH target.");
+      }
+
+      const issuePairingToken =
+        typeof rawOptions === "object" &&
+        rawOptions !== null &&
+        "issuePairingToken" in rawOptions &&
+        (rawOptions as { issuePairingToken?: unknown }).issuePairingToken === true;
+
+      try {
+        return await this.manager.ensureEnvironment(target, {
+          issuePairingToken,
+        });
+      } catch (error) {
+        if (isSshPasswordPromptCancellation(error)) {
+          return {
+            type: SSH_PASSWORD_PROMPT_CANCELLED_RESULT,
+            message: error.message,
+          };
+        }
+        throw error;
+      }
+    });
+
+    ipcMain.removeHandler(DISCONNECT_SSH_ENVIRONMENT_CHANNEL);
+    ipcMain.handle(DISCONNECT_SSH_ENVIRONMENT_CHANNEL, async (_event, rawTarget) => {
+      const target = getSafeDesktopSshTarget(rawTarget);
+      if (!target) {
+        throw new Error("Invalid desktop SSH target.");
+      }
+
+      await this.manager.disconnectEnvironment(target);
+    });
+
+    ipcMain.removeHandler(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL);
+    ipcMain.handle(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, async (_event, rawHttpBaseUrl) =>
+      sshRuntime.runPromise(
+        fetchLoopbackSshJson<ExecutionEnvironmentDescriptor>({
+          httpBaseUrl: rawHttpBaseUrl,
+          pathname: "/.well-known/t3/environment",
+        }),
+      ),
+    );
+
+    ipcMain.removeHandler(BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL);
+    ipcMain.handle(
+      BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL,
+      async (_event, rawHttpBaseUrl, rawCredential) =>
+        sshRuntime.runPromise(
+          fetchLoopbackSshJson<AuthBearerBootstrapResult>({
+            httpBaseUrl: rawHttpBaseUrl,
+            pathname: "/api/auth/bootstrap/bearer",
+            method: "POST",
+            body: { credential: rawCredential },
+          }),
+        ),
+    );
+
+    ipcMain.removeHandler(FETCH_SSH_SESSION_STATE_CHANNEL);
+    ipcMain.handle(
+      FETCH_SSH_SESSION_STATE_CHANNEL,
+      async (_event, rawHttpBaseUrl, rawBearerToken) =>
+        sshRuntime.runPromise(
+          fetchLoopbackSshJson<AuthSessionState>({
+            httpBaseUrl: rawHttpBaseUrl,
+            pathname: "/api/auth/session",
+            bearerToken: rawBearerToken,
+          }),
+        ),
+    );
+
+    ipcMain.removeHandler(ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL);
+    ipcMain.handle(
+      ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL,
+      async (_event, rawHttpBaseUrl, rawBearerToken) =>
+        sshRuntime.runPromise(
+          fetchLoopbackSshJson<AuthWebSocketTokenResult>({
+            httpBaseUrl: rawHttpBaseUrl,
+            pathname: "/api/auth/ws-token",
+            method: "POST",
+            bearerToken: rawBearerToken,
+          }),
+        ),
+    );
+
+    ipcMain.removeHandler(RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL);
+    ipcMain.handle(
+      RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL,
+      async (_event, rawRequestId, rawPassword) => {
+        if (typeof rawRequestId !== "string" || rawRequestId.trim().length === 0) {
+          throw new Error("Invalid SSH password prompt id.");
+        }
+        if (rawPassword !== null && typeof rawPassword !== "string") {
+          throw new Error("Invalid SSH password prompt response.");
+        }
+
+        const pending = this.pendingPrompts.get(rawRequestId);
+        if (!pending) {
+          throw new Error("SSH password prompt expired. Try connecting again.");
+        }
+
+        clearTimeout(pending.timeout);
+        this.pendingPrompts.delete(rawRequestId);
+        pending.resolve(rawPassword);
+      },
+    );
+  }
+
+  cancelPendingPasswordPrompts(reason: string): void {
+    for (const [requestId, pending] of this.pendingPrompts) {
+      clearTimeout(pending.timeout);
+      this.pendingPrompts.delete(requestId);
+      pending.reject(new Error(reason));
+    }
+  }
+
+  async dispose(): Promise<void> {
+    this.cancelPendingPasswordPrompts("SSH environment bridge disposed.");
+    await this.manager.dispose();
+  }
+
+  private async requestPasswordFromRenderer(input: SshPasswordRequest): Promise<string | null> {
+    const window = this.options.getMainWindow();
+    if (!window || window.isDestroyed()) {
+      throw new Error("T3 Code window is not available for SSH authentication.");
+    }
+
+    const request: DesktopSshPasswordPromptRequest = {
+      requestId: Crypto.randomUUID(),
+      destination: input.destination,
+      username: input.username,
+      prompt: input.prompt,
+      expiresAt: new Date(Date.now() + this.passwordPromptTimeoutMs).toISOString(),
+    };
+
+    return await new Promise<string | null>((resolve, reject) => {
+      const rejectPrompt = (error: Error) => {
+        clearTimeout(timeout);
+        this.pendingPrompts.delete(request.requestId);
+        reject(error);
+      };
+      const timeout = setTimeout(() => {
+        this.pendingPrompts.delete(request.requestId);
+        reject(new Error(`SSH authentication timed out for ${input.destination}.`));
+      }, this.passwordPromptTimeoutMs);
+      timeout.unref();
+
+      this.pendingPrompts.set(request.requestId, { resolve, reject, timeout });
+
+      try {
+        if (window.isDestroyed()) {
+          throw new Error("T3 Code window is not available for SSH authentication.");
+        }
+        window.webContents.send(SSH_PASSWORD_PROMPT_CHANNEL, request);
+        if (window.isDestroyed()) {
+          throw new Error("T3 Code window is not available for SSH authentication.");
+        }
+        if (window.isMinimized()) {
+          window.restore();
+        }
+        if (window.isDestroyed()) {
+          throw new Error("T3 Code window is not available for SSH authentication.");
+        }
+        window.focus();
+      } catch (error) {
+        rejectPrompt(
+          error instanceof Error
+            ? error
+            : new Error("T3 Code window is not available for SSH authentication."),
+        );
+      }
+    });
+  }
+}
diff --git a/apps/desktop/src/tailscaleEndpointProvider.test.ts b/apps/desktop/src/tailscaleEndpointProvider.test.ts
new file mode 100644
index 00000000000..2e92b7ee5d3
--- /dev/null
+++ b/apps/desktop/src/tailscaleEndpointProvider.test.ts
@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import { Effect } from "effect";
+
+import {
+  isTailscaleIpv4Address,
+  parseTailscaleMagicDnsName,
+  resolveTailscaleAdvertisedEndpoints,
+} from "./tailscaleEndpointProvider.ts";
+
+describe("tailscale endpoint provider", () => {
+  it("detects Tailnet IPv4 addresses", () => {
+    expect(isTailscaleIpv4Address("100.64.0.1")).toBe(true);
+    expect(isTailscaleIpv4Address("100.127.255.254")).toBe(true);
+    expect(isTailscaleIpv4Address("100.128.0.1")).toBe(false);
+    expect(isTailscaleIpv4Address("192.168.1.44")).toBe(false);
+  });
+
+  it("parses MagicDNS names from tailscale status", async () => {
+    expect(
+      Effect.runSync(
+        parseTailscaleMagicDnsName(JSON.stringify({ Self: { DNSName: "desktop.tail.ts.net." } })),
+      ),
+    ).toBe("desktop.tail.ts.net");
+    expect(Effect.runSync(parseTailscaleMagicDnsName("{}"))).toBeNull();
+    await expect(Effect.runPromise(parseTailscaleMagicDnsName("not-json"))).rejects.toBeDefined();
+  });
+
+  it("resolves Tailscale endpoints as add-on advertised endpoints", async () => {
+    await expect(
+      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: JSON.stringify({ Self: { DNSName: "desktop.tail.ts.net." } }),
+      }),
+    ).resolves.toEqual([
+      {
+        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.",
+      },
+    ]);
+  });
+
+  it("marks the Tailscale HTTPS endpoint available after Serve is enabled and reachable", async () => {
+    await expect(
+      resolveTailscaleAdvertisedEndpoints({
+        port: 3773,
+        networkInterfaces: {},
+        statusJson: JSON.stringify({ Self: { DNSName: "desktop.tail.ts.net." } }),
+        serveEnabled: true,
+        probe: async () => true,
+      }),
+    ).resolves.toEqual([
+      {
+        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.",
+      },
+    ]);
+  });
+});
diff --git a/apps/desktop/src/tailscaleEndpointProvider.ts b/apps/desktop/src/tailscaleEndpointProvider.ts
new file mode 100644
index 00000000000..053eac5d442
--- /dev/null
+++ b/apps/desktop/src/tailscaleEndpointProvider.ts
@@ -0,0 +1,142 @@
+import type { NetworkInterfaceInfo } from "node:os";
+
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import {
+  createAdvertisedEndpoint,
+  type CreateAdvertisedEndpointInput,
+} from "@t3tools/client-runtime";
+import type { AdvertisedEndpoint, AdvertisedEndpointProvider } from "@t3tools/contracts";
+import {
+  buildTailscaleHttpsBaseUrl,
+  isTailscaleIpv4Address,
+  parseTailscaleMagicDnsName,
+  probeTailscaleHttpsEndpoint,
+  readTailscaleStatus,
+} from "@t3tools/tailscale";
+import { Effect, Layer } from "effect";
+
+export { isTailscaleIpv4Address, parseTailscaleMagicDnsName } from "@t3tools/tailscale";
+
+const TailscaleDesktopLayer = Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici);
+
+const TAILSCALE_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
+  id: "tailscale",
+  label: "Tailscale",
+  kind: "private-network",
+  isAddon: true,
+};
+
+function createTailscaleEndpoint(
+  input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
+): AdvertisedEndpoint {
+  return createAdvertisedEndpoint({
+    ...input,
+    provider: TAILSCALE_ENDPOINT_PROVIDER,
+    source: "desktop-addon",
+  });
+}
+
+export function resolveTailscaleIpAdvertisedEndpoints(input: {
+  readonly port: number;
+  readonly networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>;
+}): 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(
+        createTailscaleEndpoint({
+          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;
+}
+
+export async function resolveTailscaleMagicDnsAdvertisedEndpoint(input: {
+  readonly dnsName: string | null;
+  readonly serveEnabled: boolean;
+  readonly servePort?: number;
+  readonly probe?: (baseUrl: string) => Promise<boolean>;
+}): Promise<AdvertisedEndpoint | null> {
+  if (!input.dnsName) {
+    return null;
+  }
+
+  const httpBaseUrl = buildTailscaleHttpsBaseUrl({
+    magicDnsName: input.dnsName,
+    ...(input.servePort === undefined ? {} : { servePort: input.servePort }),
+  });
+  const isReachable = input.serveEnabled
+    ? await (input.probe?.(httpBaseUrl) ??
+        Effect.runPromise(
+          probeTailscaleHttpsEndpoint({ baseUrl: httpBaseUrl }).pipe(
+            Effect.provide(TailscaleDesktopLayer),
+          ),
+        ))
+    : false;
+
+  return createTailscaleEndpoint({
+    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 async function resolveTailscaleAdvertisedEndpoints(input: {
+  readonly port: number;
+  readonly serveEnabled?: boolean;
+  readonly servePort?: number;
+  readonly networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>;
+  readonly statusJson?: string | null;
+  readonly probe?: (baseUrl: string) => Promise<boolean>;
+}): Promise<readonly AdvertisedEndpoint[]> {
+  const ipEndpoints = resolveTailscaleIpAdvertisedEndpoints(input);
+  const dnsName =
+    input.statusJson === undefined
+      ? await Effect.runPromise(
+          readTailscaleStatus.pipe(
+            Effect.map((status) => status.magicDnsName),
+            Effect.catch(() => Effect.succeed(null)),
+            Effect.provide(TailscaleDesktopLayer),
+          ),
+        )
+      : input.statusJson
+        ? await Effect.runPromise(
+            parseTailscaleMagicDnsName(input.statusJson).pipe(
+              Effect.catch(() => Effect.succeed(null)),
+            ),
+          )
+        : null;
+  const magicDnsEndpoint = await resolveTailscaleMagicDnsAdvertisedEndpoint({
+    dnsName,
+    serveEnabled: input.serveEnabled === true,
+    ...(input.servePort === undefined ? {} : { servePort: input.servePort }),
+    ...(input.probe === undefined ? {} : { probe: input.probe }),
+  });
+
+  return magicDnsEndpoint ? [...ipEndpoints, magicDnsEndpoint] : ipEndpoints;
+}
diff --git a/apps/server/integration/OrchestrationEngineHarness.integration.ts b/apps/server/integration/OrchestrationEngineHarness.integration.ts
index 8f59fd3f46c..24c17561195 100644
--- a/apps/server/integration/OrchestrationEngineHarness.integration.ts
+++ b/apps/server/integration/OrchestrationEngineHarness.integration.ts
@@ -3,7 +3,8 @@ 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";
@@ -24,10 +25,7 @@ import {
 
 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 +34,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";
@@ -73,6 +74,11 @@ 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 GitVcsDriver from "../src/vcs/GitVcsDriver.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";
 
 function runGit(cwd: string, args: ReadonlyArray<string>) {
   return execFileSync("git", args, {
@@ -214,7 +220,7 @@ export interface OrchestrationIntegrationHarness {
 }
 
 interface MakeOrchestrationIntegrationHarnessOptions {
-  readonly provider?: ProviderKind;
+  readonly provider?: ProviderDriverKind;
   readonly realCodex?: boolean;
 }
 
@@ -225,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
@@ -233,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-",
@@ -264,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 = Schema.decodeSync(CodexSettings)({});
+        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,
@@ -307,31 +309,31 @@ export const makeOrchestrationIntegrationHarness = (
       Layer.provideMerge(runtimeServicesLayer),
       Layer.provideMerge(serverSettingsLayer),
     );
-    const gitCoreLayer = Layer.succeed(GitCore, {
-      renameBranch: (input: Parameters<GitCoreShape["renameBranch"]>[0]) =>
+    const gitWorkflowLayer = Layer.mock(GitWorkflowService)({
+      renameBranch: (input: Parameters<GitVcsDriver.GitVcsDriverShape["renameBranch"]>[0]) =>
         Effect.succeed({ branch: input.newBranch }),
-    } as unknown as GitCoreShape);
+    });
     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 },
             }),
@@ -342,11 +344,12 @@ 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),
diff --git a/apps/server/integration/TestProviderAdapter.integration.ts b/apps/server/integration/TestProviderAdapter.integration.ts
index 69a4d528cdd..3907e038be5 100644
--- a/apps/server/integration/TestProviderAdapter.integration.ts
+++ b/apps/server/integration/TestProviderAdapter.integration.ts
@@ -10,7 +10,7 @@ import {
   ProviderTurnStartResult,
   ThreadId,
   TurnId,
-  ProviderKind,
+  ProviderDriverKind,
 } from "@t3tools/contracts";
 import { Effect, Queue, Stream } from "effect";
 
@@ -24,7 +24,6 @@ import type {
   ProviderThreadSnapshot,
   ProviderThreadTurnSnapshot,
 } from "../src/provider/Services/ProviderAdapter.ts";
-import { getProviderCapabilities } from "../src/provider/Services/ProviderAdapter.ts";
 
 export interface TestTurnResponse {
   readonly events: ReadonlyArray<FixtureProviderRuntimeEvent>;
@@ -37,7 +36,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;
@@ -179,7 +178,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,
@@ -199,7 +198,7 @@ export interface TestProviderAdapterHarness {
 }
 
 interface MakeTestProviderAdapterHarnessOptions {
-  readonly provider?: ProviderKind;
+  readonly provider?: ProviderDriverKind;
 }
 
 function nowIso(): string {
@@ -207,7 +206,7 @@ function nowIso(): string {
 }
 
 function sessionNotFound(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   threadId: ThreadId,
 ): ProviderAdapterSessionNotFoundError {
   return new ProviderAdapterSessionNotFoundError({
@@ -217,7 +216,7 @@ function sessionNotFound(
 }
 
 function missingSessionEffect(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   threadId: ThreadId,
 ): Effect.Effect<never, ProviderAdapterError> {
   return Effect.fail(sessionNotFound(provider, threadId));
@@ -225,7 +224,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>();
@@ -258,6 +257,9 @@ export const makeTestProviderAdapterHarness = (options?: MakeTestProviderAdapter
 
         const session: ProviderSession = {
           provider,
+          ...(input.providerInstanceId !== undefined
+            ? { providerInstanceId: input.providerInstanceId }
+            : {}),
           status: "ready",
           runtimeMode: input.runtimeMode,
           threadId,
@@ -475,7 +477,7 @@ export const makeTestProviderAdapterHarness = (options?: MakeTestProviderAdapter
 
     const adapter: ProviderAdapterShape<ProviderAdapterError> = {
       provider,
-      capabilities: getProviderCapabilities(provider),
+      capabilities: { sessionModelSwitch: "in-session" },
       startSession,
       sendTurn,
       interruptTurn,
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 261bd11991c..6bd94819839 100644
--- a/apps/server/integration/orchestrationEngine.integration.test.ts
+++ b/apps/server/integration/orchestrationEngine.integration.test.ts
@@ -4,14 +4,17 @@ 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";
@@ -39,7 +42,9 @@ 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();
@@ -74,7 +79,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 +93,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 +106,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 +115,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 +126,7 @@ const seedProjectAndThread = (harness: OrchestrationIntegrationHarness) =>
       title: "Integration Project",
       workspaceRoot: harness.workspaceDir,
       defaultModelSelection: {
-        provider,
+        instanceId,
         model: defaultModel,
       },
       createdAt,
@@ -129,7 +139,7 @@ const seedProjectAndThread = (harness: OrchestrationIntegrationHarness) =>
       projectId: PROJECT_ID,
       title: "Integration Thread",
       modelSelection: {
-        provider,
+        instanceId,
         model: defaultModel,
       },
       interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -265,7 +275,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 +288,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 +506,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 +515,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);
 
@@ -744,18 +756,6 @@ it.live("reverts to an earlier checkpoint and trims checkpoint projections + git
         messageId: "msg-user-revert-1",
         text: "First edit",
       });
-      yield* harness.waitForReceipt(
-        (receipt): receipt is CheckpointDiffFinalizedReceipt =>
-          receipt.type === "checkpoint.diff.finalized" &&
-          receipt.threadId === THREAD_ID &&
-          receipt.checkpointTurnCount === 1,
-      );
-      yield* harness.waitForReceipt(
-        (receipt): receipt is TurnProcessingQuiescedReceipt =>
-          receipt.type === "turn.processing.quiesced" &&
-          receipt.threadId === THREAD_ID &&
-          receipt.checkpointTurnCount === 1,
-      );
 
       yield* harness.waitForThread(
         THREAD_ID,
@@ -814,18 +814,6 @@ it.live("reverts to an earlier checkpoint and trims checkpoint projections + git
         messageId: "msg-user-revert-2",
         text: "Second edit",
       });
-      yield* harness.waitForReceipt(
-        (receipt): receipt is CheckpointDiffFinalizedReceipt =>
-          receipt.type === "checkpoint.diff.finalized" &&
-          receipt.threadId === THREAD_ID &&
-          receipt.checkpointTurnCount === 2,
-      );
-      yield* harness.waitForReceipt(
-        (receipt): receipt is TurnProcessingQuiescedReceipt =>
-          receipt.type === "turn.processing.quiesced" &&
-          receipt.threadId === THREAD_ID &&
-          receipt.checkpointTurnCount === 2,
-      );
 
       yield* harness.waitForThread(
         THREAD_ID,
@@ -833,6 +821,7 @@ it.live("reverts to an earlier checkpoint and trims checkpoint projections + git
           entry.latestTurn?.turnId === "turn-2" &&
           entry.checkpoints.length === 2 &&
           entry.activities.some((activity) => activity.turnId === "turn-2"),
+        8000,
       );
 
       yield* harness.engine.dispatch({
@@ -935,20 +924,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",
@@ -962,7 +963,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",
           },
         });
@@ -978,119 +979,140 @@ it.live("starts a claudeAgent session on first turn when provider is requested",
         );
         assert.equal(thread.session?.providerName, "claudeAgent");
       }),
-    "claudeAgent",
+    CLAUDE_AGENT_PROVIDER,
   ),
 );
 
-// Skip: flaky timeout in CI after upstream sync — needs investigation
-it.live.skip(
-  "recovers claudeAgent sessions after provider stopAll using persisted resume state",
-  () =>
-    withHarness(
-      (harness) =>
-        Effect.gen(function* () {
-          yield* seedProjectAndThread(harness);
-
-          yield* harness.adapterHarness!.queueTurnResponseForNextSession({
-            events: [
-              {
-                type: "turn.started",
-                ...runtimeBase("evt-claude-recover-1", "2026-02-24T10:11:00.000Z", "claudeAgent"),
-                threadId: THREAD_ID,
-                turnId: FIXTURE_TURN_ID,
-              },
-              {
-                type: "message.delta",
-                ...runtimeBase("evt-claude-recover-2", "2026-02-24T10:11:00.050Z", "claudeAgent"),
-                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"),
-                threadId: THREAD_ID,
-                turnId: FIXTURE_TURN_ID,
-                status: "completed",
-              },
-            ],
-          });
-
-          yield* startTurn({
-            harness,
-            commandId: "cmd-turn-start-claude-recover-1",
-            messageId: "msg-user-claude-recover-1",
-            text: "Before restart",
-            modelSelection: {
-              provider: "claudeAgent",
-              model: "claude-sonnet-4-6",
+it.live("recovers claudeAgent sessions after provider stopAll using persisted resume state", () =>
+  withHarness(
+    (harness) =>
+      Effect.gen(function* () {
+        yield* seedProjectAndThread(harness);
+
+        yield* harness.adapterHarness!.queueTurnResponseForNextSession({
+          events: [
+            {
+              type: "turn.started",
+              ...runtimeBase(
+                "evt-claude-recover-1",
+                "2026-02-24T10:11:00.000Z",
+                CLAUDE_AGENT_PROVIDER,
+              ),
+              threadId: THREAD_ID,
+              turnId: FIXTURE_TURN_ID,
             },
-          });
-
-          yield* harness.waitForThread(
-            THREAD_ID,
-            (entry) =>
-              entry.latestTurn?.turnId === "turn-1" && entry.session?.threadId === "thread-1",
-          );
-
-          yield* harness.providerService.stopSession({ threadId: THREAD_ID });
-          yield* waitForSync(
-            () => harness.adapterHarness!.listActiveSessionIds(),
-            (sessionIds) => sessionIds.length === 0,
-            "provider stopSession",
-          );
-
-          yield* harness.adapterHarness!.queueTurnResponseForNextSession({
-            events: [
-              {
-                type: "turn.started",
-                ...runtimeBase("evt-claude-recover-4", "2026-02-24T10:11:01.000Z", "claudeAgent"),
-                threadId: THREAD_ID,
-                turnId: FIXTURE_TURN_ID,
-              },
-              {
-                type: "message.delta",
-                ...runtimeBase("evt-claude-recover-5", "2026-02-24T10:11:01.050Z", "claudeAgent"),
-                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"),
-                threadId: THREAD_ID,
-                turnId: FIXTURE_TURN_ID,
-                status: "completed",
-              },
-            ],
-          });
-
-          yield* startTurn({
-            harness,
-            commandId: "cmd-turn-start-claude-recover-2",
-            messageId: "msg-user-claude-recover-2",
-            text: "After restart",
-          });
-          yield* waitForSync(
-            () => harness.adapterHarness!.getStartCount(),
-            (count) => count === 2,
-            "claude provider recovery start",
-          );
-
-          const recoveredThread = yield* harness.waitForThread(
-            THREAD_ID,
-            (entry) =>
-              entry.session?.providerName === "claudeAgent" &&
-              entry.messages.some(
-                (message) => message.role === "user" && message.text === "After restart",
-              ) &&
-              !entry.activities.some((activity) => activity.kind === "provider.turn.start.failed"),
-          );
-          assert.equal(recoveredThread.session?.providerName, "claudeAgent");
-          assert.equal(recoveredThread.session?.threadId, "thread-1");
-        }),
-      "claudeAgent",
-    ),
+            {
+              type: "message.delta",
+              ...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",
+                CLAUDE_AGENT_PROVIDER,
+              ),
+              threadId: THREAD_ID,
+              turnId: FIXTURE_TURN_ID,
+              status: "completed",
+            },
+          ],
+        });
+
+        yield* startTurn({
+          harness,
+          commandId: "cmd-turn-start-claude-recover-1",
+          messageId: "msg-user-claude-recover-1",
+          text: "Before restart",
+          modelSelection: {
+            instanceId: ProviderInstanceId.make("claudeAgent"),
+            model: "claude-sonnet-4-6",
+          },
+        });
+
+        yield* harness.waitForThread(
+          THREAD_ID,
+          (entry) =>
+            entry.latestTurn?.turnId === "turn-1" && entry.session?.threadId === "thread-1",
+        );
+
+        yield* harness.adapterHarness!.adapter.stopAll();
+        yield* waitForSync(
+          () => harness.adapterHarness!.listActiveSessionIds(),
+          (sessionIds) => sessionIds.length === 0,
+          "provider stopAll",
+        );
+
+        yield* harness.adapterHarness!.queueTurnResponseForNextSession({
+          events: [
+            {
+              type: "turn.started",
+              ...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",
+                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",
+                CLAUDE_AGENT_PROVIDER,
+              ),
+              threadId: THREAD_ID,
+              turnId: FIXTURE_TURN_ID,
+              status: "completed",
+            },
+          ],
+        });
+
+        yield* startTurn({
+          harness,
+          commandId: "cmd-turn-start-claude-recover-2",
+          messageId: "msg-user-claude-recover-2",
+          text: "After restart",
+        });
+        yield* waitForSync(
+          () => harness.adapterHarness!.getStartCount(),
+          (count) => count === 2,
+          "claude provider recovery start",
+        );
+
+        const recoveredThread = yield* harness.waitForThread(
+          THREAD_ID,
+          (entry) =>
+            entry.session?.providerName === "claudeAgent" &&
+            entry.messages.some(
+              (message) => message.role === "user" && message.text === "After restart",
+            ) &&
+            !entry.activities.some((activity) => activity.kind === "provider.turn.start.failed"),
+        );
+        assert.equal(recoveredThread.session?.providerName, "claudeAgent");
+        assert.equal(recoveredThread.session?.threadId, "thread-1");
+      }),
+    CLAUDE_AGENT_PROVIDER,
+  ),
 );
 
 it.live("forwards claudeAgent approval responses to the provider session", () =>
@@ -1103,13 +1125,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,
@@ -1118,7 +1148,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",
@@ -1132,7 +1166,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",
           },
         });
@@ -1163,7 +1197,7 @@ it.live("forwards claudeAgent approval responses to the provider session", () =>
         );
         assert.equal(approvalResponses[0]?.decision, "accept");
       }),
-    "claudeAgent",
+    CLAUDE_AGENT_PROVIDER,
   ),
 );
 
@@ -1177,20 +1211,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",
@@ -1204,7 +1250,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",
           },
         });
@@ -1232,7 +1278,7 @@ it.live("forwards thread.turn.interrupt to claudeAgent provider sessions", () =>
         );
         assert.equal(interruptCalls.length, 1);
       }),
-    "claudeAgent",
+    CLAUDE_AGENT_PROVIDER,
   ),
 );
 
@@ -1246,20 +1292,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",
@@ -1277,7 +1335,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",
           },
         });
@@ -1292,20 +1350,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",
@@ -1356,6 +1426,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 3dd127a5564..0939e7ba385 100644
--- a/apps/server/integration/providerService.integration.test.ts
+++ b/apps/server/integration/providerService.integration.test.ts
@@ -1,13 +1,17 @@
 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 { 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 +33,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 +53,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 +66,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 +127,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 +146,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 +164,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 +201,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 +253,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 d9d84166b99..3f142bfc0d7 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -42,6 +42,7 @@
     "@effect/vitest": "catalog:",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/shared": "workspace:*",
+    "@t3tools/tailscale": "workspace:*",
     "@t3tools/web": "workspace:*",
     "@types/bun": "catalog:",
     "@types/node": "catalog:",
diff --git a/apps/server/src/ampServerManager.ts b/apps/server/src/ampServerManager.ts
index 46005126060..7acd8b77d4e 100644
--- a/apps/server/src/ampServerManager.ts
+++ b/apps/server/src/ampServerManager.ts
@@ -6,6 +6,7 @@ import readline from "node:readline";
 import {
   ApprovalRequestId,
   EventId,
+  ProviderDriverKind,
   RuntimeItemId,
   RuntimeTaskId,
   ThreadId,
@@ -24,9 +25,9 @@ import { createLogger } from "./logger.ts";
 
 // ── Constants ───────────────────────────────────────────────────────
 
-const PROVIDER = "amp" as const;
+const PROVIDER = ProviderDriverKind.make("amp");
 
-// ── Module-level usage tracking ──────────────────────────────────────
+// ── Per-instance usage tracking ──────────────────────────────────────
 
 interface AmpUsageAccumulator {
   inputTokens: number;
@@ -35,31 +36,6 @@ interface AmpUsageAccumulator {
   turnCount: number;
 }
 
-let _ampUsageAccumulator: AmpUsageAccumulator = {
-  inputTokens: 0,
-  outputTokens: 0,
-  cachedTokens: 0,
-  turnCount: 0,
-};
-
-export function fetchAmpUsage(): ProviderUsageResult {
-  const acc = _ampUsageAccumulator;
-  let sessionUsage: ProviderSessionUsage | undefined;
-  if (acc.turnCount > 0) {
-    sessionUsage = {
-      inputTokens: acc.inputTokens,
-      outputTokens: acc.outputTokens,
-      ...(acc.cachedTokens > 0 ? { cachedTokens: acc.cachedTokens } : {}),
-      totalTokens: acc.inputTokens + acc.outputTokens,
-      turnCount: acc.turnCount,
-    };
-  }
-  return {
-    provider: PROVIDER,
-    ...(sessionUsage ? { sessionUsage } : {}),
-  };
-}
-
 // ── Types ───────────────────────────────────────────────────────────
 
 type AmpProviderOptions = {
@@ -173,8 +149,38 @@ export class AmpServerManager extends EventEmitter<{
 }> {
   private readonly sessions = new Map<ThreadId, AmpSession>();
   private readonly logger = createLogger("amp");
+  private readonly usageAccumulator: AmpUsageAccumulator = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cachedTokens: 0,
+    turnCount: 0,
+  };
   binaryPath: string | undefined;
 
+  /**
+   * Snapshot the per-instance usage counters in the canonical
+   * `ProviderUsageResult` shape. Returns the manager-local accumulator —
+   * each `AmpServerManager` instance keeps its own counters so two
+   * concurrent Amp providers do not cross-contaminate usage stats.
+   */
+  fetchUsage(): ProviderUsageResult {
+    const acc = this.usageAccumulator;
+    let sessionUsage: ProviderSessionUsage | undefined;
+    if (acc.turnCount > 0) {
+      sessionUsage = {
+        inputTokens: acc.inputTokens,
+        outputTokens: acc.outputTokens,
+        ...(acc.cachedTokens > 0 ? { cachedTokens: acc.cachedTokens } : {}),
+        totalTokens: acc.inputTokens + acc.outputTokens,
+        turnCount: acc.turnCount,
+      };
+    }
+    return {
+      provider: PROVIDER,
+      ...(sessionUsage ? { sessionUsage } : {}),
+    };
+  }
+
   // ── Session lifecycle ───────────────────────────────────────────
 
   startSession(input: ProviderSessionStartInput): Promise<ProviderSession> {
@@ -563,9 +569,9 @@ export class AmpServerManager extends EventEmitter<{
     if (inner?.usage) {
       // Accumulate session-level usage
       if (typeof inner.usage.input_tokens === "number")
-        _ampUsageAccumulator.inputTokens += inner.usage.input_tokens;
+        this.usageAccumulator.inputTokens += inner.usage.input_tokens;
       if (typeof inner.usage.output_tokens === "number")
-        _ampUsageAccumulator.outputTokens += inner.usage.output_tokens;
+        this.usageAccumulator.outputTokens += inner.usage.output_tokens;
       const cached =
         (typeof inner.usage.cache_read_input_tokens === "number"
           ? inner.usage.cache_read_input_tokens
@@ -573,7 +579,7 @@ export class AmpServerManager extends EventEmitter<{
         (typeof inner.usage.cache_creation_input_tokens === "number"
           ? inner.usage.cache_creation_input_tokens
           : 0);
-      if (cached > 0) _ampUsageAccumulator.cachedTokens += cached;
+      if (cached > 0) this.usageAccumulator.cachedTokens += cached;
 
       this.emitEvent(threadId, session.activeTurnId, {
         type: "thread.token-usage.updated",
@@ -584,7 +590,7 @@ export class AmpServerManager extends EventEmitter<{
     // For persistent sessions, a turn completes when stop_reason is "end_turn".
     // Guard against duplicate turn.completed (handleResultMessage may also emit one).
     if (inner?.stop_reason === "end_turn" && session.activeTurnId && session.status !== "ready") {
-      _ampUsageAccumulator.turnCount++;
+      this.usageAccumulator.turnCount++;
       this.closeAllSubagentTasks(threadId, session);
       this.emitEvent(threadId, session.activeTurnId, {
         type: "turn.completed",
diff --git a/apps/server/src/checkpointing/Errors.ts b/apps/server/src/checkpointing/Errors.ts
index cb873559c16..c6875e585cf 100644
--- a/apps/server/src/checkpointing/Errors.ts
+++ b/apps/server/src/checkpointing/Errors.ts
@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 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 3f1da81106a..a76572c402f 100644
--- a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.test.ts
+++ b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.test.ts
@@ -48,6 +48,7 @@ describe("CheckpointDiffQueryLive", () => {
       readonly fromCheckpointRef: CheckpointRef;
       readonly toCheckpointRef: CheckpointRef;
       readonly cwd: string;
+      readonly ignoreWhitespace: boolean;
     }> = [];
 
     const threadCheckpointContext = makeThreadCheckpointContext({
@@ -68,9 +69,14 @@ describe("CheckpointDiffQueryLive", () => {
           return 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,
@@ -102,6 +108,7 @@ describe("CheckpointDiffQueryLive", () => {
           threadId,
           fromTurnCount: 0,
           toTurnCount: 1,
+          ignoreWhitespace: true,
         });
       }).pipe(Effect.provide(layer)),
     );
@@ -113,6 +120,7 @@ describe("CheckpointDiffQueryLive", () => {
         cwd: process.cwd(),
         fromCheckpointRef: expectedFromRef,
         toCheckpointRef,
+        ignoreWhitespace: true,
       },
     ]);
     expect(result).toEqual({
@@ -123,6 +131,67 @@ 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, {
+          getSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the full orchestration snapshot"),
+          getShellSnapshot: () =>
+            Effect.die("CheckpointDiffQuery should not request the orchestration shell snapshot"),
+          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)),
+          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("fails when the thread is missing from the snapshot", async () => {
     const threadId = ThreadId.make("thread-missing");
 
diff --git a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts
index 1c2edee469e..c6b15134711 100644
--- a/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts
+++ b/apps/server/src/checkpointing/Layers/CheckpointDiffQuery.ts
@@ -24,6 +24,7 @@ const make = Effect.gen(function* () {
   const getTurnDiff: CheckpointDiffQueryShape["getTurnDiff"] = Effect.fn("getTurnDiff")(
     function* (input) {
       const operation = "CheckpointDiffQuery.getTurnDiff";
+      const ignoreWhitespace = input.ignoreWhitespace ?? true;
 
       if (input.fromTurnCount === input.toTurnCount) {
         const emptyDiff: OrchestrationGetTurnDiffResultType = {
@@ -131,6 +132,7 @@ const make = Effect.gen(function* () {
         fromCheckpointRef,
         toCheckpointRef,
         fallbackFromToHead: false,
+        ignoreWhitespace,
       });
 
       const turnDiff: OrchestrationGetTurnDiffResultType = {
@@ -157,6 +159,7 @@ const make = Effect.gen(function* () {
       threadId: input.threadId,
       fromTurnCount: 0,
       toTurnCount: input.toTurnCount,
+      ignoreWhitespace: input.ignoreWhitespace ?? true,
     }).pipe(Effect.map((result): OrchestrationGetFullThreadDiffResult => result));
 
   return {
diff --git a/apps/server/src/checkpointing/Layers/CheckpointStore.test.ts b/apps/server/src/checkpointing/Layers/CheckpointStore.test.ts
index fe377eb1ec3..204fd565740 100644
--- a/apps/server/src/checkpointing/Layers/CheckpointStore.test.ts
+++ b/apps/server/src/checkpointing/Layers/CheckpointStore.test.ts
@@ -8,24 +8,27 @@ 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 +52,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 +70,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 +114,7 @@ it.layer(TestLayer)("CheckpointStoreLive", (it) => {
           cwd: tmp,
           fromCheckpointRef,
           toCheckpointRef,
+          ignoreWhitespace: true,
         });
 
         expect(diff).toContain("diff --git");
@@ -118,5 +122,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 211877e9b1a..7efe4cc0a56 100644
--- a/apps/server/src/checkpointing/Layers/CheckpointStore.ts
+++ b/apps/server/src/checkpointing/Layers/CheckpointStore.ts
@@ -14,8 +14,8 @@ import { randomUUID } from "node:crypto";
 import { Effect, Layer, FileSystem, Path } from "effect";
 
 import { CheckpointInvariantError } from "../Errors.ts";
-import { GitCommandError } from "@t3tools/contracts";
-import { GitCore } from "../../git/Services/GitCore.ts";
+import { VcsProcessExitError } from "@t3tools/contracts";
+import { VcsDriverRegistry } from "../../vcs/VcsDriverRegistry.ts";
 import { CheckpointStore, type CheckpointStoreShape } from "../Services/CheckpointStore.ts";
 import { CheckpointRef } from "@t3tools/contracts";
 
@@ -24,10 +24,26 @@ const CHECKPOINT_DIFF_MAX_OUTPUT_BYTES = 10_000_000;
 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
+  const vcsRegistry = yield* VcsDriverRegistry;
+  const vcs = {
+    execute: (input: {
+      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;
+    }) =>
+      vcsRegistry
+        .resolve({ cwd: input.cwd, requestedKind: "git" })
+        .pipe(Effect.flatMap((handle) => handle.driver.execute(input))),
+  };
+
+  const resolveHeadCommit = (cwd: string) =>
+    vcs
       .execute({
         operation: "CheckpointStore.resolveHeadCommit",
         cwd,
@@ -36,7 +52,7 @@ const makeCheckpointStore = Effect.gen(function* () {
       })
       .pipe(
         Effect.map((result) => {
-          if (result.code !== 0) {
+          if (result.exitCode !== 0) {
             return null;
           }
           const commit = result.stdout.trim();
@@ -44,21 +60,18 @@ const makeCheckpointStore = Effect.gen(function* () {
         }),
       );
 
-  const hasHeadCommit = (cwd: string): Effect.Effect<boolean, GitCommandError> =>
-    git
+  const hasHeadCommit = (cwd: string) =>
+    vcs
       .execute({
         operation: "CheckpointStore.hasHeadCommit",
         cwd,
         args: ["rev-parse", "--verify", "HEAD"],
         allowNonZeroExit: true,
       })
-      .pipe(Effect.map((result) => result.code === 0));
+      .pipe(Effect.map((result) => result.exitCode === 0));
 
-  const resolveCheckpointCommit = (
-    cwd: string,
-    checkpointRef: CheckpointRef,
-  ): Effect.Effect<string | null, GitCommandError> =>
-    git
+  const resolveCheckpointCommit = (cwd: string, checkpointRef: CheckpointRef) =>
+    vcs
       .execute({
         operation: "CheckpointStore.resolveCheckpointCommit",
         cwd,
@@ -67,7 +80,7 @@ const makeCheckpointStore = Effect.gen(function* () {
       })
       .pipe(
         Effect.map((result) => {
-          if (result.code !== 0) {
+          if (result.exitCode !== 0) {
             return null;
           }
           const commit = result.stdout.trim();
@@ -76,7 +89,7 @@ const makeCheckpointStore = Effect.gen(function* () {
       );
 
   const isGitRepository: CheckpointStoreShape["isGitRepository"] = (cwd) =>
-    git
+    vcs
       .execute({
         operation: "CheckpointStore.isGitRepository",
         cwd,
@@ -84,7 +97,7 @@ const makeCheckpointStore = Effect.gen(function* () {
         allowNonZeroExit: true,
       })
       .pipe(
-        Effect.map((result) => result.code === 0 && result.stdout.trim() === "true"),
+        Effect.map((result) => result.exitCode === 0 && result.stdout.trim() === "true"),
         Effect.catch(() => Effect.succeed(false)),
       );
 
@@ -108,7 +121,7 @@ const makeCheckpointStore = Effect.gen(function* () {
 
         const headExists = yield* hasHeadCommit(input.cwd);
         if (headExists) {
-          yield* git.execute({
+          yield* vcs.execute({
             operation,
             cwd: input.cwd,
             args: ["read-tree", "HEAD"],
@@ -116,14 +129,14 @@ const makeCheckpointStore = Effect.gen(function* () {
           });
         }
 
-        yield* git.execute({
+        yield* vcs.execute({
           operation,
           cwd: input.cwd,
           args: ["add", "-A", "--", "."],
           env: commitEnv,
         });
 
-        const writeTreeResult = yield* git.execute({
+        const writeTreeResult = yield* vcs.execute({
           operation,
           cwd: input.cwd,
           args: ["write-tree"],
@@ -131,16 +144,17 @@ const makeCheckpointStore = Effect.gen(function* () {
         });
         const treeOid = writeTreeResult.stdout.trim();
         if (treeOid.length === 0) {
-          return yield* new GitCommandError({
+          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* git.execute({
+        const commitTreeResult = yield* vcs.execute({
           operation,
           cwd: input.cwd,
           args: ["commit-tree", treeOid, "-m", message],
@@ -148,15 +162,16 @@ const makeCheckpointStore = Effect.gen(function* () {
         });
         const commitOid = commitTreeResult.stdout.trim();
         if (commitOid.length === 0) {
-          return yield* new GitCommandError({
+          return yield* new VcsProcessExitError({
             operation,
             command: "git commit-tree",
             cwd: input.cwd,
+            exitCode: 0,
             detail: "git commit-tree returned an empty commit oid.",
           });
         }
 
-        yield* git.execute({
+        yield* vcs.execute({
           operation,
           cwd: input.cwd,
           args: ["update-ref", input.checkpointRef, commitOid],
@@ -197,12 +212,12 @@ const makeCheckpointStore = Effect.gen(function* () {
       return false;
     }
 
-    yield* git.execute({
+    yield* vcs.execute({
       operation,
       cwd: input.cwd,
       args: ["restore", "--source", commitOid, "--worktree", "--staged", "--", "."],
     });
-    yield* git.execute({
+    yield* vcs.execute({
       operation,
       cwd: input.cwd,
       args: ["clean", "-fd", "--", "."],
@@ -210,7 +225,7 @@ const makeCheckpointStore = Effect.gen(function* () {
 
     const headExists = yield* hasHeadCommit(input.cwd);
     if (headExists) {
-      yield* git.execute({
+      yield* vcs.execute({
         operation,
         cwd: input.cwd,
         args: ["reset", "--quiet", "--", "."],
@@ -235,18 +250,29 @@ const makeCheckpointStore = Effect.gen(function* () {
       }
 
       if (!fromCommitOid || !toCommitOid) {
-        return yield* new GitCommandError({
+        return yield* new VcsProcessExitError({
           operation,
           command: "git diff",
           cwd: input.cwd,
+          exitCode: 1,
           detail: "Checkpoint ref is unavailable for diff operation.",
         });
       }
 
-      const result = yield* git.execute({
+      const diffArgs = [
+        "diff",
+        "--patch",
+        "--minimal",
+        "--no-color",
+        ...(input.ignoreWhitespace ? ["--ignore-all-space"] : []),
+        fromCommitOid,
+        toCommitOid,
+      ];
+
+      const result = yield* vcs.execute({
         operation,
         cwd: input.cwd,
-        args: ["diff", "--patch", "--minimal", "--no-color", fromCommitOid, toCommitOid],
+        args: diffArgs,
         maxOutputBytes: CHECKPOINT_DIFF_MAX_OUTPUT_BYTES,
       });
 
@@ -262,7 +288,7 @@ const makeCheckpointStore = Effect.gen(function* () {
     yield* Effect.forEach(
       input.checkpointRefs,
       (checkpointRef) =>
-        git.execute({
+        vcs.execute({
           operation,
           cwd: input.cwd,
           args: ["update-ref", "-d", checkpointRef],
diff --git a/apps/server/src/checkpointing/Services/CheckpointStore.ts b/apps/server/src/checkpointing/Services/CheckpointStore.ts
index d9a43fa4e95..be6bdbccfaa 100644
--- a/apps/server/src/checkpointing/Services/CheckpointStore.ts
+++ b/apps/server/src/checkpointing/Services/CheckpointStore.ts
@@ -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/cli-config.test.ts b/apps/server/src/cli-config.test.ts
index 5adece73020..2e13d33aabf 100644
--- a/apps/server/src/cli-config.test.ts
+++ b/apps/server/src/cli-config.test.ts
@@ -46,6 +46,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 +89,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -108,6 +112,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(
@@ -149,6 +155,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: true,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: true,
+        tailscaleServePort: 8443,
       });
     }),
   );
@@ -161,6 +169,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         noBrowser: true,
         autoBootstrapProjectFromCwd: true,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
       const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:4173"));
 
@@ -176,6 +186,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(
@@ -212,6 +224,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -229,6 +243,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         noBrowser: true,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
         otlpTracesUrl: "http://localhost:4318/v1/traces",
         otlpMetricsUrl: "http://localhost:4318/v1/metrics",
       });
@@ -246,6 +262,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(
@@ -281,6 +299,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
       assert.equal(join(baseDir, "dev"), resolved.stateDir);
     }),
@@ -305,6 +325,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(
@@ -346,6 +368,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         noBrowser: false,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
       const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:4173"));
 
@@ -361,6 +385,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(
@@ -399,6 +425,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: true,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -432,6 +460,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 +493,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -485,6 +517,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 +556,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.test.ts b/apps/server/src/cli.test.ts
index 7ebde01067a..3ef8c441959 100644
--- a/apps/server/src/cli.test.ts
+++ b/apps/server/src/cli.test.ts
@@ -76,6 +76,8 @@ const makeCliTestServerConfig = (baseDir: string) =>
       desktopBootstrapToken: undefined,
       autoBootstrapProjectFromCwd: false,
       logWebSocketEvents: false,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
     } satisfies ServerConfigShape;
   });
 
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts
index 4fc23a1ded0..bcf8bee861c 100644
--- a/apps/server/src/cli.ts
+++ b/apps/server/src/cli.ts
@@ -78,6 +78,8 @@ const BootstrapEnvelopeSchema = Schema.Struct({
   desktopBootstrapToken: Schema.optional(Schema.String),
   autoBootstrapProjectFromCwd: Schema.optional(Schema.Boolean),
   logWebSocketEvents: Schema.optional(Schema.Boolean),
+  tailscaleServeEnabled: Schema.optional(Schema.Boolean),
+  tailscaleServePort: Schema.optional(PortSchema),
   otlpTracesUrl: Schema.optional(Schema.String),
   otlpMetricsUrl: Schema.optional(Schema.String),
 });
@@ -126,6 +128,17 @@ const logWebSocketEventsFlag = Flag.boolean("log-websocket-events").pipe(
   Flag.withAlias("log-ws-events"),
   Flag.optional,
 );
+const tailscaleServeFlag = Flag.boolean("tailscale-serve").pipe(
+  Flag.withDescription(
+    "Configure Tailscale Serve to expose this backend over HTTPS on the Tailnet.",
+  ),
+  Flag.optional,
+);
+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")),
@@ -174,6 +187,14 @@ const EnvServerConfig = Config.all({
     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),
+  ),
 });
 
 interface CliServerFlags {
@@ -187,6 +208,8 @@ interface CliServerFlags {
   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>;
 }
 
 interface CliAuthLocationFlags {
@@ -233,6 +256,8 @@ export const resolveServerConfig = (
       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 =
@@ -323,6 +348,22 @@ export const resolveServerConfig = (
       ),
       () => 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(
@@ -365,6 +406,8 @@ export const resolveServerConfig = (
       desktopBootstrapToken,
       autoBootstrapProjectFromCwd,
       logWebSocketEvents,
+      tailscaleServeEnabled,
+      tailscaleServePort,
     };
 
     return config;
@@ -386,6 +429,8 @@ const resolveCliAuthConfig = (
       bootstrapFd: Option.none(),
       autoBootstrapProjectFromCwd: Option.none(),
       logWebSocketEvents: Option.none(),
+      tailscaleServeEnabled: Option.none(),
+      tailscaleServePort: Option.none(),
     },
     cliLogLevel,
   );
@@ -766,6 +811,8 @@ const sharedServerCommandFlags = {
   bootstrapFd: bootstrapFdFlag,
   autoBootstrapProjectFromCwd: autoBootstrapProjectFromCwdFlag,
   logWebSocketEvents: logWebSocketEventsFlag,
+  tailscaleServeEnabled: tailscaleServeFlag,
+  tailscaleServePort: tailscaleServePortFlag,
 } as const;
 
 const authLocationFlags = sharedServerLocationFlags;
diff --git a/apps/server/src/config.ts b/apps/server/src/config.ts
index 7840c761151..4d8e1cb7e79 100644
--- a/apps/server/src/config.ts
+++ b/apps/server/src/config.ts
@@ -65,6 +65,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* (
@@ -158,6 +160,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/environment/Layers/ServerEnvironment.test.ts b/apps/server/src/environment/Layers/ServerEnvironment.test.ts
index b899a4f9870..6b9ab90481c 100644
--- a/apps/server/src/environment/Layers/ServerEnvironment.test.ts
+++ b/apps/server/src/environment/Layers/ServerEnvironment.test.ts
@@ -30,6 +30,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/geminiCliServerManager.test.ts b/apps/server/src/geminiCliServerManager.test.ts
index 66193cefa3d..c934d1d99a1 100644
--- a/apps/server/src/geminiCliServerManager.test.ts
+++ b/apps/server/src/geminiCliServerManager.test.ts
@@ -1,6 +1,12 @@
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import type { PathLike } from "node:fs";
-import { ThreadId, TurnId, type ProviderRuntimeEvent } from "@t3tools/contracts";
+import {
+  ProviderDriverKind,
+  ProviderInstanceId,
+  ThreadId,
+  TurnId,
+  type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
 
 import {
   buildGeminiSpawnOptions,
@@ -95,10 +101,10 @@ describe("GeminiCliServerManager", () => {
       try {
         const session = await manager.startSession({
           threadId: asThreadId("thread-1"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
           cwd: "/tmp",
-          modelSelection: { provider: "geminiCli", model: "gemini-2.5-pro" },
+          modelSelection: { instanceId: ProviderInstanceId.make("geminiCli"), model: "gemini-2.5-pro" },
         });
 
         expect(session.provider).toBe("geminiCli");
@@ -116,7 +122,7 @@ describe("GeminiCliServerManager", () => {
       try {
         const session = await manager.startSession({
           threadId: asThreadId("thread-1"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
           resumeCursor: {
             sessionId: "gemini-session-123",
@@ -137,14 +143,14 @@ describe("GeminiCliServerManager", () => {
       try {
         await manager.startSession({
           threadId: asThreadId("thread-1"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
         });
 
         expect(() =>
           manager.startSession({
             threadId: asThreadId("thread-1"),
-            provider: "geminiCli",
+            provider: ProviderDriverKind.make("geminiCli"),
             runtimeMode: "full-access",
           }),
         ).toThrow("already exists");
@@ -161,7 +167,7 @@ describe("GeminiCliServerManager", () => {
       try {
         await manager.startSession({
           threadId: asThreadId("thread-1"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
         });
 
@@ -189,7 +195,7 @@ describe("GeminiCliServerManager", () => {
       const manager = new GeminiCliServerManager();
       await manager.startSession({
         threadId: asThreadId("thread-1"),
-        provider: "geminiCli",
+        provider: ProviderDriverKind.make("geminiCli"),
         runtimeMode: "full-access",
       });
 
@@ -213,7 +219,7 @@ describe("GeminiCliServerManager", () => {
       const manager = new GeminiCliServerManager();
       await manager.startSession({
         threadId: asThreadId("thread-1"),
-        provider: "geminiCli",
+        provider: ProviderDriverKind.make("geminiCli"),
         runtimeMode: "full-access",
       });
 
@@ -237,7 +243,7 @@ describe("GeminiCliServerManager", () => {
       try {
         await manager.startSession({
           threadId: asThreadId("thread-1"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
         });
 
@@ -259,7 +265,7 @@ describe("GeminiCliServerManager", () => {
       const manager = new GeminiCliServerManager();
       await manager.startSession({
         threadId: asThreadId("thread-1"),
-        provider: "geminiCli",
+        provider: ProviderDriverKind.make("geminiCli"),
         runtimeMode: "full-access",
       });
 
@@ -280,15 +286,15 @@ describe("GeminiCliServerManager", () => {
       try {
         await manager.startSession({
           threadId: asThreadId("thread-1"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
-          modelSelection: { provider: "geminiCli", model: "gemini-3-flash" },
+          modelSelection: { instanceId: ProviderInstanceId.make("geminiCli"), model: "gemini-3-flash" },
         });
         await manager.startSession({
           threadId: asThreadId("thread-2"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
-          modelSelection: { provider: "geminiCli", model: "gemini-2.5-pro" },
+          modelSelection: { instanceId: ProviderInstanceId.make("geminiCli"), model: "gemini-2.5-pro" },
         });
 
         const sessions = manager.listSessions();
@@ -309,7 +315,7 @@ describe("GeminiCliServerManager", () => {
       try {
         await manager.startSession({
           threadId: asThreadId("thread-1"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
         });
 
@@ -333,7 +339,7 @@ describe("GeminiCliServerManager", () => {
       try {
         await manager.startSession({
           threadId: asThreadId("thread-1"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
         });
 
@@ -371,9 +377,9 @@ describe("GeminiCliServerManager JSON event mapping", () => {
 
     await manager.startSession({
       threadId: asThreadId("thread-json"),
-      provider: "geminiCli",
+      provider: ProviderDriverKind.make("geminiCli"),
       runtimeMode: "full-access",
-      modelSelection: { provider: "geminiCli", model: "gemini-2.5-pro" },
+      modelSelection: { instanceId: ProviderInstanceId.make("geminiCli"), model: "gemini-2.5-pro" },
       cwd: "/tmp",
     });
 
@@ -709,9 +715,9 @@ describe.skipIf(!hasGemini || process.env.RUN_GEMINI_LIVE_TESTS !== "1")(
       try {
         await manager.startSession({
           threadId: asThreadId("live-thread"),
-          provider: "geminiCli",
+          provider: ProviderDriverKind.make("geminiCli"),
           runtimeMode: "full-access",
-          modelSelection: { provider: "geminiCli", model: "gemini-2.5-flash" },
+          modelSelection: { instanceId: ProviderInstanceId.make("geminiCli"), model: "gemini-2.5-flash" },
         });
 
         const result = await manager.sendTurn({
diff --git a/apps/server/src/geminiCliServerManager.ts b/apps/server/src/geminiCliServerManager.ts
index fb682a19ee3..5ab113f56d1 100644
--- a/apps/server/src/geminiCliServerManager.ts
+++ b/apps/server/src/geminiCliServerManager.ts
@@ -13,6 +13,7 @@ import readline from "node:readline";
 import {
   ApprovalRequestId,
   EventId,
+  ProviderDriverKind,
   RuntimeItemId,
   ThreadId,
   TurnId,
@@ -28,9 +29,9 @@ import type { ProviderSessionUsage, ProviderUsageResult } from "@t3tools/contrac
 import type { ProviderThreadSnapshot } from "./provider/Services/ProviderAdapter.ts";
 import { resolveCommandPath } from "./commandPath.ts";
 
-const PROVIDER = "geminiCli" as const;
+const PROVIDER = ProviderDriverKind.make("geminiCli");
 
-// ── Module-level usage tracking ──────────────────────────────────────
+// ── Per-instance usage tracking ──────────────────────────────────────
 
 interface GeminiUsageAccumulator {
   inputTokens: number;
@@ -40,29 +41,13 @@ interface GeminiUsageAccumulator {
   turnCount: number;
 }
 
-let _geminiUsageAccumulator: GeminiUsageAccumulator = {
-  inputTokens: 0,
-  outputTokens: 0,
-  cachedTokens: 0,
-  totalTokens: 0,
-  turnCount: 0,
-};
-
-export function fetchGeminiCliUsage(): ProviderUsageResult {
-  const acc = _geminiUsageAccumulator;
-  let sessionUsage: ProviderSessionUsage | undefined;
-  if (acc.turnCount > 0) {
-    sessionUsage = {
-      inputTokens: acc.inputTokens,
-      outputTokens: acc.outputTokens,
-      ...(acc.cachedTokens > 0 ? { cachedTokens: acc.cachedTokens } : {}),
-      totalTokens: acc.totalTokens,
-      turnCount: acc.turnCount,
-    };
-  }
+function emptyUsageAccumulator(): GeminiUsageAccumulator {
   return {
-    provider: PROVIDER,
-    ...(sessionUsage ? { sessionUsage } : {}),
+    inputTokens: 0,
+    outputTokens: 0,
+    cachedTokens: 0,
+    totalTokens: 0,
+    turnCount: 0,
   };
 }
 
@@ -343,8 +328,37 @@ export class GeminiCliServerManager extends EventEmitter<{
   event: [ProviderRuntimeEvent];
 }> {
   private readonly sessions = new Map<ThreadId, GeminiCliSession>();
+  private readonly usageAccumulator: GeminiUsageAccumulator = emptyUsageAccumulator();
   binaryPath: string | undefined;
 
+  constructor(options: { readonly binaryPath?: string | undefined } = {}) {
+    super();
+    this.binaryPath = options.binaryPath;
+  }
+
+  /**
+   * Per-instance usage snapshot. Replaces the old module-level
+   * `fetchGeminiCliUsage()` so two managers running side-by-side don't share
+   * an accumulator.
+   */
+  fetchUsage(): ProviderUsageResult {
+    const acc = this.usageAccumulator;
+    let sessionUsage: ProviderSessionUsage | undefined;
+    if (acc.turnCount > 0) {
+      sessionUsage = {
+        inputTokens: acc.inputTokens,
+        outputTokens: acc.outputTokens,
+        ...(acc.cachedTokens > 0 ? { cachedTokens: acc.cachedTokens } : {}),
+        totalTokens: acc.totalTokens,
+        turnCount: acc.turnCount,
+      };
+    }
+    return {
+      provider: PROVIDER,
+      ...(sessionUsage ? { sessionUsage } : {}),
+    };
+  }
+
   startSession(input: ProviderSessionStartInput): Promise<ProviderSession> {
     const threadId = input.threadId;
     if (this.sessions.has(threadId)) {
@@ -777,15 +791,15 @@ export class GeminiCliServerManager extends EventEmitter<{
 
         // Accumulate session-level usage
         if (usage) {
-          _geminiUsageAccumulator.turnCount++;
+          this.usageAccumulator.turnCount++;
           if (typeof usage.input_tokens === "number")
-            _geminiUsageAccumulator.inputTokens += usage.input_tokens;
+            this.usageAccumulator.inputTokens += usage.input_tokens;
           if (typeof usage.output_tokens === "number")
-            _geminiUsageAccumulator.outputTokens += usage.output_tokens;
+            this.usageAccumulator.outputTokens += usage.output_tokens;
           if (typeof usage.cached_tokens === "number")
-            _geminiUsageAccumulator.cachedTokens += usage.cached_tokens;
+            this.usageAccumulator.cachedTokens += usage.cached_tokens;
           if (typeof usage.total_tokens === "number")
-            _geminiUsageAccumulator.totalTokens += usage.total_tokens;
+            this.usageAccumulator.totalTokens += usage.total_tokens;
         }
 
         // Support both `error_message` (legacy) and `error.message` (0.32+).
diff --git a/apps/server/src/git/Layers/GitManager.test.ts b/apps/server/src/git/GitManager.test.ts
similarity index 89%
rename from apps/server/src/git/Layers/GitManager.test.ts
rename to apps/server/src/git/GitManager.test.ts
index dbbc821a088..844cbb47ae3 100644
--- a/apps/server/src/git/Layers/GitManager.test.ts
+++ b/apps/server/src/git/GitManager.test.ts
@@ -5,6 +5,7 @@ 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 { ChildProcessSpawner } from "effect/unstable/process";
 import { expect } from "vitest";
 import type {
   GitActionProgressEvent,
@@ -13,24 +14,27 @@ 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,
   type ProjectSetupScriptRunnerInput,
   type ProjectSetupScriptRunnerShape,
-} from "../../project/Services/ProjectSetupScriptRunner.ts";
+} from "../project/Services/ProjectSetupScriptRunner.ts";
 
 interface FakeGhScenario {
   prListSequence?: string[];
@@ -53,6 +57,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 +223,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 +252,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 +268,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 +282,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, [
@@ -379,24 +402,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 +422,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 +441,8 @@ function createGitHubCliWithFakeGh(scenario: FakeGhScenario = {}): {
                 }
               : {}),
           }) + "\n",
-        stderr: "",
-        code: 0,
-        signal: null,
-        timedOut: false,
-      });
+        ),
+      );
     }
 
     if (args[0] === "pr" && args[1] === "checkout") {
@@ -453,13 +464,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 +491,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 +580,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 +642,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 +670,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 +682,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),
 );
 
@@ -698,15 +716,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",
       });
     }),
@@ -743,8 +761,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",
       });
     }),
@@ -794,8 +812,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",
       });
     }),
@@ -843,8 +861,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 +877,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 +889,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         hasUpstream: false,
         aheadCount: 0,
         behindCount: 0,
+        aheadOfDefaultCount: 0,
         pr: null,
       });
     }),
@@ -888,9 +907,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 +919,7 @@ it.layer(GitManagerTestLayer)("GitManager", (it) => {
         hasUpstream: false,
         aheadCount: 0,
         behindCount: 0,
+        aheadOfDefaultCount: 0,
         pr: null,
       });
     }),
@@ -972,7 +992,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();
       }),
   );
@@ -1026,13 +1046,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(
@@ -1127,13 +1147,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(
@@ -1177,18 +1197,48 @@ 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: [
+            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-");
@@ -1224,13 +1274,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",
       });
     }),
@@ -1255,7 +1305,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();
     }),
   );
@@ -1633,6 +1683,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-");
@@ -1679,6 +1764,49 @@ 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: [
+            "[]",
+            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-");
@@ -2340,6 +2468,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-");
@@ -3094,7 +3329,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 84%
rename from apps/server/src/git/Layers/GitManager.ts
rename to apps/server/src/git/GitManager.ts
index dadf2f7e79b..b77ee5169b1 100644
--- a/apps/server/src/git/Layers/GitManager.ts
+++ b/apps/server/src/git/GitManager.ts
@@ -1,55 +1,96 @@
 import { randomUUID } from "node:crypto";
-import { realpathSync } from "node:fs";
 
 import {
+  Array as Arr,
   Cache,
+  Context,
+  DateTime,
   Duration,
   Effect,
   Exit,
   FileSystem,
   Layer,
   Option,
+  Order,
   Path,
   Ref,
-  Result,
 } from "effect";
 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 } from "../Services/GitCore.ts";
-import type { 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;
@@ -75,9 +116,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;
@@ -88,9 +134,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 {
@@ -256,7 +302,7 @@ function matchesBranchHeadContext(
   return true;
 }
 
-function toPullRequestInfo(summary: GitHubPullRequestSummary): PullRequestInfo {
+function toPullRequestInfo(summary: ChangeRequest): PullRequestInfo {
   return {
     number: summary.number,
     title: summary.title,
@@ -264,7 +310,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 }
       : {}),
@@ -311,13 +357,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));
   }
 
@@ -422,16 +469,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,
   };
 }
@@ -442,14 +489,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;
@@ -475,9 +514,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 } : {}),
@@ -491,10 +530,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 = (
@@ -527,11 +568,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,
       });
@@ -547,6 +604,11 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
         url: remoteUrl,
       });
 
+      yield* gitCore.fetchRemoteTrackingBranch({
+        cwd,
+        remoteName,
+        remoteBranch: pullRequest.headBranch,
+      });
       yield* gitCore.setBranchUpstream({
         cwd,
         branch: localBranch,
@@ -586,7 +648,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
         return;
       }
 
-      const cloneUrls = yield* gitHubCli.getRepositoryCloneUrls({
+      const cloneUrls = yield* (yield* sourceControlProvider(cwd)).getRepositoryCloneUrls({
         cwd,
         repository: repositoryNameWithOwner,
       });
@@ -635,7 +697,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,
@@ -647,6 +711,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
@@ -660,20 +725,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)
@@ -688,7 +755,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;
@@ -697,15 +770,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)));
@@ -722,7 +798,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* (
@@ -827,9 +903,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);
@@ -845,7 +922,7 @@ export const makeGitManager = Effect.fn("makeGitManager")(function* () {
           baseRefName: firstPullRequest.baseRefName,
           headRefName: firstPullRequest.headRefName,
           state: "open",
-          updatedAt: null,
+          updatedAt: Option.none(),
         } satisfies PullRequestInfo;
       }
     }
@@ -861,46 +938,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;
         }
@@ -908,11 +953,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) {
@@ -925,7 +966,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: {
@@ -990,7 +1035,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") &&
@@ -998,7 +1043,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 },
               }
             : {
@@ -1029,11 +1074,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";
@@ -1205,6 +1251,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) {
@@ -1241,7 +1289,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);
 
@@ -1266,12 +1314,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,
@@ -1299,11 +1347,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) {
@@ -1329,8 +1379,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),
         })
@@ -1363,15 +1413,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,
@@ -1413,33 +1463,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 &&
@@ -1467,7 +1519,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 &&
@@ -1489,7 +1541,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);
@@ -1497,7 +1549,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)));
@@ -1529,8 +1581,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 },
@@ -1564,12 +1616,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",
@@ -1633,6 +1679,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(
@@ -1670,7 +1722,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"))),
@@ -1731,4 +1783,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..dd7273b40c9
--- /dev/null
+++ b/apps/server/src/git/GitWorkflowService.test.ts
@@ -0,0 +1,132 @@
+import { assert, describe, it, vi } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+
+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..70ab6eecf1f
--- /dev/null
+++ b/apps/server/src/git/GitWorkflowService.ts
@@ -0,0 +1,314 @@
+import { Context, Effect, Layer } from "effect";
+
+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/CopilotTextGeneration.ts b/apps/server/src/git/Layers/CopilotTextGeneration.ts
deleted file mode 100644
index 8948c719896..00000000000
--- a/apps/server/src/git/Layers/CopilotTextGeneration.ts
+++ /dev/null
@@ -1,321 +0,0 @@
-import type {
-  CopilotClient as CopilotClientType,
-  CopilotClientOptions,
-  PermissionRequestResult,
-} from "@github/copilot-sdk";
-import { DEFAULT_MODEL_BY_PROVIDER } from "@t3tools/contracts";
-import { sanitizeFeatureBranchName } from "@t3tools/shared/git";
-import { Effect, Layer, Schema, SchemaIssue } from "effect";
-
-import {
-  normalizeCopilotCliPathOverride,
-  resolveBundledCopilotCliPath,
-} from "../../provider/Layers/copilotCliPath.ts";
-import { TextGenerationError } from "@t3tools/contracts";
-import {
-  CopilotTextGeneration,
-  type CopilotTextGenerationShape,
-} from "../Services/CopilotTextGeneration.ts";
-import type {
-  CommitMessageGenerationResult,
-  PrContentGenerationResult,
-} from "../Services/TextGeneration.ts";
-
-const COPILOT_TIMEOUT_MS = 180_000;
-const DENY_PERMISSION_RESULT: PermissionRequestResult = {
-  kind: "denied-interactively-by-user",
-};
-
-const CommitMessageResponseSchema = Schema.Struct({
-  subject: Schema.String,
-  body: Schema.String,
-  branch: Schema.optional(Schema.String),
-});
-
-const PrContentResponseSchema = Schema.Struct({
-  title: Schema.String,
-  body: Schema.String,
-});
-
-interface CopilotClientHandle {
-  createSession(
-    config: Parameters<CopilotClientType["createSession"]>[0],
-  ): Promise<CopilotSessionHandle>;
-  stop(): Promise<ReadonlyArray<Error>>;
-}
-
-interface CopilotSessionHandle {
-  destroy(): Promise<void>;
-  sendAndWait(
-    input: {
-      prompt: string;
-      mode: "immediate";
-    },
-    timeoutMs: number,
-  ): Promise<{
-    data?: {
-      content?: string;
-    };
-  }>;
-}
-
-export interface CopilotTextGenerationLiveOptions {
-  readonly cliPath?: string;
-  readonly clientFactory?: (options: CopilotClientOptions) => CopilotClientHandle;
-}
-
-function normalizeCopilotError(
-  operation: "generateCommitMessage" | "generatePrContent",
-  error: unknown,
-  fallback: string,
-): TextGenerationError {
-  if (Schema.is(TextGenerationError)(error)) {
-    return error;
-  }
-
-  if (error instanceof Error) {
-    const lower = error.message.toLowerCase();
-    if (lower.includes("enoent") || lower.includes("spawn")) {
-      return new TextGenerationError({
-        operation,
-        detail: "GitHub Copilot CLI is required but was not found.",
-        cause: error,
-      });
-    }
-    return new TextGenerationError({
-      operation,
-      detail: `${fallback}: ${error.message}`,
-      cause: error,
-    });
-  }
-
-  return new TextGenerationError({
-    operation,
-    detail: fallback,
-    cause: error,
-  });
-}
-
-function limitSection(value: string, maxChars: number): string {
-  if (value.length <= maxChars) return value;
-  return `${value.slice(0, maxChars)}\n\n[truncated]`;
-}
-
-function sanitizePrTitle(raw: string): string {
-  const singleLine = raw.trim().split(/\r?\n/g)[0]?.trim() ?? "";
-  return singleLine.length > 0 ? singleLine : "Update project changes";
-}
-
-function extractJsonObject(raw: string): string {
-  const trimmed = raw.trim();
-  if (trimmed.startsWith("```")) {
-    const fenced = trimmed.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "");
-    return fenced.trim();
-  }
-  const start = trimmed.indexOf("{");
-  const end = trimmed.lastIndexOf("}");
-  if (start !== -1 && end !== -1 && end > start) {
-    return trimmed.slice(start, end + 1);
-  }
-  return trimmed;
-}
-
-function decodeJsonResponse<S extends Schema.Top>(
-  operation: "generateCommitMessage" | "generatePrContent",
-  raw: string,
-  schema: S,
-): Effect.Effect<S["Type"], TextGenerationError, S["DecodingServices"]> {
-  return Effect.gen(function* () {
-    const jsonText = extractJsonObject(raw);
-    const parsed = yield* Effect.try({
-      try: () => JSON.parse(jsonText) as unknown,
-      catch: (cause) =>
-        normalizeCopilotError(operation, cause, "GitHub Copilot returned invalid JSON"),
-    });
-
-    return yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(
-      Effect.mapError(
-        (cause) =>
-          new TextGenerationError({
-            operation,
-            detail: `GitHub Copilot returned an unexpected payload: ${SchemaIssue.makeFormatterDefault()(cause.issue)}`,
-            cause,
-          }),
-      ),
-    );
-  });
-}
-
-export const makeCopilotTextGenerationLive = (options?: CopilotTextGenerationLiveOptions) =>
-  Layer.effect(
-    CopilotTextGeneration,
-    Effect.sync(() => {
-      const runCopilotJson = <S extends Schema.Top>({
-        operation,
-        prompt,
-        schema,
-      }: {
-        operation: "generateCommitMessage" | "generatePrContent";
-        prompt: string;
-        schema: S;
-      }): Effect.Effect<S["Type"], TextGenerationError, S["DecodingServices"]> =>
-        Effect.gen(function* () {
-          const cliPath =
-            normalizeCopilotCliPathOverride(options?.cliPath) ?? resolveBundledCopilotCliPath();
-          const model = DEFAULT_MODEL_BY_PROVIDER.copilot;
-          const clientOptions: CopilotClientOptions = {
-            ...(cliPath ? { cliPath } : {}),
-            logLevel: "error",
-          };
-          const { CopilotClient } = yield* Effect.promise(() => import("@github/copilot-sdk"));
-          const client =
-            options?.clientFactory?.(clientOptions) ?? new CopilotClient(clientOptions);
-          let session: CopilotSessionHandle | undefined;
-          const cleanup = Effect.promise(async () => {
-            if (session) {
-              await session.destroy().catch(() => undefined);
-            }
-            await client.stop().catch(() => []);
-          }).pipe(Effect.asVoid);
-
-          return yield* Effect.gen(function* () {
-            const createdSession = yield* Effect.tryPromise({
-              try: () =>
-                client.createSession({
-                  model,
-                  onPermissionRequest: () => DENY_PERMISSION_RESULT,
-                  systemMessage: {
-                    mode: "append",
-                    content:
-                      "Do not use tools, do not request permissions, and answer using only valid JSON with no markdown fences or prose.",
-                  },
-                }),
-              catch: (cause) =>
-                normalizeCopilotError(
-                  operation,
-                  cause,
-                  "Failed to start a GitHub Copilot text-generation session",
-                ),
-            });
-            session = createdSession;
-
-            const response = yield* Effect.tryPromise({
-              try: () =>
-                createdSession.sendAndWait({ prompt, mode: "immediate" }, COPILOT_TIMEOUT_MS),
-              catch: (cause) =>
-                normalizeCopilotError(
-                  operation,
-                  cause,
-                  "GitHub Copilot did not finish generating text",
-                ),
-            });
-
-            const responseContent =
-              response &&
-              typeof response === "object" &&
-              "data" in response &&
-              response.data &&
-              typeof response.data === "object" &&
-              "content" in response.data &&
-              typeof response.data.content === "string"
-                ? response.data.content
-                : null;
-
-            if (!responseContent) {
-              return yield* new TextGenerationError({
-                operation,
-                detail: "GitHub Copilot did not return any text.",
-              });
-            }
-
-            return yield* decodeJsonResponse(operation, responseContent, schema);
-          }).pipe(Effect.ensuring(cleanup));
-        });
-
-      const generateCommitMessage: CopilotTextGenerationShape["generateCommitMessage"] = (
-        input,
-      ) => {
-        const prompt = [
-          "You write concise git commit messages.",
-          input.includeBranch === true
-            ? "Return a JSON object with keys: subject, body, branch."
-            : "Return a JSON object with keys: subject, body.",
-          "Rules:",
-          "- subject must be imperative, <= 72 chars, and have no trailing period",
-          "- body can be an empty string or short bullet points",
-          ...(input.includeBranch === true
-            ? ["- branch must be a short semantic git branch fragment for this change"]
-            : []),
-          "- capture the primary user-visible or developer-visible change",
-          "",
-          `Branch: ${input.branch ?? "(detached)"}`,
-          "",
-          "Staged files:",
-          limitSection(input.stagedSummary, 6_000),
-          "",
-          "Staged patch:",
-          limitSection(input.stagedPatch, 40_000),
-        ].join("\n");
-
-        return runCopilotJson({
-          operation: "generateCommitMessage",
-          prompt,
-          schema: CommitMessageResponseSchema,
-        }).pipe(
-          Effect.map(
-            (generated) =>
-              ({
-                subject: generated.subject,
-                body: generated.body.trim(),
-                ...(generated.branch
-                  ? { branch: sanitizeFeatureBranchName(generated.branch) }
-                  : {}),
-              }) satisfies CommitMessageGenerationResult,
-          ),
-        );
-      };
-
-      const generatePrContent: CopilotTextGenerationShape["generatePrContent"] = (input) => {
-        const prompt = [
-          "You write GitHub pull request content.",
-          "Return a JSON object with keys: title, body.",
-          "Rules:",
-          "- title should be concise and specific",
-          "- body must be markdown and include headings '## Summary' and '## Testing'",
-          "- under Summary, provide short bullet points",
-          "- under Testing, mention concrete commands when available",
-          "",
-          `Base branch: ${input.baseBranch}`,
-          `Head branch: ${input.headBranch}`,
-          "",
-          "Commit summary:",
-          limitSection(input.commitSummary, 6_000),
-          "",
-          "Diff summary:",
-          limitSection(input.diffSummary, 8_000),
-          "",
-          "Diff patch:",
-          limitSection(input.diffPatch, 40_000),
-        ].join("\n");
-
-        return runCopilotJson({
-          operation: "generatePrContent",
-          prompt,
-          schema: PrContentResponseSchema,
-        }).pipe(
-          Effect.map(
-            (generated) =>
-              ({
-                title: sanitizePrTitle(generated.title),
-                body: generated.body.trim(),
-              }) satisfies PrContentGenerationResult,
-          ),
-        );
-      };
-
-      return {
-        generateCommitMessage,
-        generatePrContent,
-      } satisfies CopilotTextGenerationShape;
-    }),
-  );
diff --git a/apps/server/src/git/Layers/CursorTextGeneration.test.ts b/apps/server/src/git/Layers/CursorTextGeneration.test.ts
deleted file mode 100644
index e7bce113474..00000000000
--- a/apps/server/src/git/Layers/CursorTextGeneration.test.ts
+++ /dev/null
@@ -1,298 +0,0 @@
-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 { Effect, Layer } from "effect";
-import { expect } from "vitest";
-
-import { ServerSettingsError } from "@t3tools/contracts";
-
-import { ServerConfig } from "../../config.ts";
-import { TextGeneration } from "../Services/TextGeneration.ts";
-import { CursorTextGenerationLive } from "./CursorTextGeneration.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-
-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 = CursorTextGenerationLive.pipe(
-  Layer.provideMerge(ServerSettingsService.layerTest()),
-  Layer.provideMerge(
-    ServerConfig.layerTest(process.cwd(), {
-      prefix: "t3code-cursor-text-generation-test-",
-    }),
-  ),
-  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>,
-  effect: Effect.Effect<A, E, R>,
-): Effect.Effect<A, E | ServerSettingsError, R | ServerSettingsService> {
-  return Effect.gen(function* () {
-    const tempDir = mkdtempSync(path.join(os.tmpdir(), "t3code-cursor-text-acp-"));
-    const agentPath = makeAcpAgentWrapper(tempDir, env);
-    const serverSettings = yield* ServerSettingsService;
-    const previousSettings = yield* serverSettings.getSettings;
-
-    yield* serverSettings.updateSettings({
-      providers: {
-        cursor: {
-          binaryPath: agentPath,
-        },
-      },
-    });
-
-    return yield* effect.pipe(
-      Effect.ensuring(
-        serverSettings
-          .updateSettings({
-            providers: {
-              cursor: {
-                binaryPath: previousSettings.providers.cursor.binaryPath,
-              },
-            },
-          })
-          .pipe(
-            Effect.catch(() => Effect.void),
-            Effect.ensuring(
-              Effect.sync(() => {
-                rmSync(tempDir, { recursive: true, force: true });
-              }),
-            ),
-            Effect.asVoid,
-          ),
-      ),
-    );
-  });
-}
-
-function waitForFileContent(path: string): Effect.Effect<string> {
-  return Effect.promise(async () => {
-    const deadline = Date.now() + 5_000;
-    for (;;) {
-      try {
-        return readFileSync(path, "utf8");
-      } catch (error) {
-        if (Date.now() >= deadline) {
-          throw error instanceof Error ? error : new Error(String(error));
-        }
-      }
-      await new Promise((resolve) => setTimeout(resolve, 25));
-    }
-  });
-}
-
-it.layer(CursorTextGenerationTestLayer)("CursorTextGenerationLive", (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",
-        }),
-      },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateCommitMessage({
-          cwd: process.cwd(),
-          branch: "feature/cursor-text-generation",
-          stagedSummary: "M apps/server/src/git/Layers/CursorTextGeneration.ts",
-          stagedPatch:
-            "diff --git a/apps/server/src/git/Layers/CursorTextGeneration.ts b/apps/server/src/git/Layers/CursorTextGeneration.ts",
-          modelSelection: {
-            provider: "cursor",
-            model: "gpt-5.4",
-            options: {
-              reasoning: "xhigh",
-              fastMode: true,
-              contextWindow: "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.',
-      },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        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: {
-            provider: "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."',
-        }),
-      },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateThreadTitle({
-          cwd: process.cwd(),
-          message: "Fix the reconnect spinner after a resumed session.",
-          modelSelection: {
-            provider: "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: "",
-        }),
-      },
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        const generated = yield* textGeneration.generateCommitMessage({
-          cwd: process.cwd(),
-          branch: "feature/cursor-runtime-close",
-          stagedSummary: "M apps/server/src/git/Layers/CursorTextGeneration.ts",
-          stagedPatch:
-            "diff --git a/apps/server/src/git/Layers/CursorTextGeneration.ts b/apps/server/src/git/Layers/CursorTextGeneration.ts",
-          modelSelection: {
-            provider: "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/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 5a7b9cb8b1d..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.ts";
-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 e67e4966d9d..00000000000
--- a/apps/server/src/git/Layers/GitHubCli.ts
+++ /dev/null
@@ -1,241 +0,0 @@
-import { Effect, Layer, Result, Schema, SchemaIssue } from "effect";
-import { TrimmedNonEmptyString } from "@t3tools/contracts";
-
-import { runProcess } from "../../processRunner.ts";
-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,
-          ...(input.repository ? ["--repo", input.repository] : []),
-        ],
-      }).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/OpenCodeTextGeneration.test.ts b/apps/server/src/git/Layers/OpenCodeTextGeneration.test.ts
deleted file mode 100644
index 28ee0a3e6fe..00000000000
--- a/apps/server/src/git/Layers/OpenCodeTextGeneration.test.ts
+++ /dev/null
@@ -1,340 +0,0 @@
-import * as NodeServices from "@effect/platform-node/NodeServices";
-import { it } from "@effect/vitest";
-import { Duration, Effect, Layer } from "effect";
-import { TestClock } from "effect/testing";
-import { NetService } from "@t3tools/shared/Net";
-import { beforeEach, expect } from "vitest";
-
-import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import {
-  OpenCodeRuntime,
-  OpenCodeRuntimeError,
-  type OpenCodeRuntimeShape,
-} from "../../provider/opencodeRuntime.ts";
-import { TextGeneration } from "../Services/TextGeneration.ts";
-import { OpenCodeTextGenerationLive } 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 = {
-  provider: "opencode" as const,
-  model: "openai/gpt-5",
-};
-
-const OPENCODE_TEXT_GENERATION_IDLE_TTL_MS = 30_000;
-
-const OpenCodeTextGenerationTestLayer = OpenCodeTextGenerationLive.pipe(
-  Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
-  Layer.provideMerge(
-    ServerSettingsService.layerTest({
-      providers: {
-        opencode: {
-          binaryPath: "fake-opencode",
-        },
-      },
-    }),
-  ),
-  Layer.provideMerge(
-    ServerConfig.layerTest(process.cwd(), {
-      prefix: "t3code-opencode-text-generation-test-",
-    }),
-  ),
-  Layer.provideMerge(NetService.layer),
-  Layer.provideMerge(NodeServices.layer),
-);
-
-const OpenCodeTextGenerationExistingServerTestLayer = OpenCodeTextGenerationLive.pipe(
-  Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
-  Layer.provideMerge(
-    ServerSettingsService.layerTest({
-      providers: {
-        opencode: {
-          binaryPath: "fake-opencode",
-          serverUrl: "http://127.0.0.1:9999",
-          serverPassword: "secret-password",
-        },
-      },
-    }),
-  ),
-  Layer.provideMerge(
-    ServerConfig.layerTest(process.cwd(), {
-      prefix: "t3code-opencode-text-generation-existing-server-test-",
-    }),
-  ),
-  Layer.provideMerge(NetService.layer),
-  Layer.provideMerge(NodeServices.layer),
-);
-
-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)("OpenCodeTextGenerationLive", (it) => {
-  it.effect("reuses a warm server across back-to-back requests and closes it after idling", () =>
-    Effect.gen(function* () {
-      const textGeneration = yield* TextGeneration;
-
-      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", () =>
-    Effect.gen(function* () {
-      const textGeneration = yield* TextGeneration;
-
-      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", () =>
-    Effect.gen(function* () {
-      runtimeMock.state.promptResult = { data: {} };
-      const textGeneration = yield* TextGeneration;
-
-      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", () =>
-    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 textGeneration = yield* TextGeneration;
-
-      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", () =>
-    Effect.gen(function* () {
-      runtimeMock.state.promptResult = {
-        data: {
-          info: {
-            error: {
-              name: "StructuredOutputError",
-              data: {
-                message: "Model did not produce structured output",
-                retries: 2,
-              },
-            },
-          },
-        },
-      };
-      const textGeneration = yield* TextGeneration;
-
-      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)(
-  "OpenCodeTextGenerationLive with configured server URL",
-  (it) => {
-    it.effect("reuses a configured OpenCode server URL without spawning or applying idle TTL", () =>
-      Effect.gen(function* () {
-        const textGeneration = yield* TextGeneration;
-
-        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/git/Layers/RoutingTextGeneration.ts b/apps/server/src/git/Layers/RoutingTextGeneration.ts
deleted file mode 100644
index a4d8cc494f1..00000000000
--- a/apps/server/src/git/Layers/RoutingTextGeneration.ts
+++ /dev/null
@@ -1,151 +0,0 @@
-/**
- * RoutingTextGeneration – Dispatches text generation requests to the
- * appropriate CLI implementation based on the provider in each request input.
- *
- * Currently supported providers with dedicated layers:
- *  - `"claudeAgent"` → Claude CLI layer
- *  - `"copilot"`     → Copilot text-generation layer (partial – falls back to
- *                       codex for branch names / thread titles)
- *  - `"codex"`       → Codex CLI layer (also the default fallback)
- *  - `"cursor"`      → Cursor text-generation layer (ACP-based)
- *  - `"opencode"`    → OpenCode text-generation layer (SDK-based)
- *
- * Providers without a dedicated CLI text-generation layer (geminiCli, amp,
- * kilo) fall back to Codex.
- *
- * @module RoutingTextGeneration
- */
-import { Effect, Layer, Context } from "effect";
-
-import type { ProviderKind } from "@t3tools/contracts";
-import { TextGeneration, type TextGenerationShape } from "../Services/TextGeneration.ts";
-import {
-  CopilotTextGeneration,
-  type CopilotTextGenerationShape,
-} from "../Services/CopilotTextGeneration.ts";
-import { CodexTextGenerationLive } from "./CodexTextGeneration.ts";
-import { ClaudeTextGenerationLive } from "./ClaudeTextGeneration.ts";
-import { makeCopilotTextGenerationLive } from "./CopilotTextGeneration.ts";
-import { CursorTextGenerationLive } from "./CursorTextGeneration.ts";
-import { OpenCodeTextGenerationLive } from "./OpenCodeTextGeneration.ts";
-
-// ---------------------------------------------------------------------------
-// Supported git text-generation providers.  Providers not in this set fall
-// back to codex (the most broadly compatible CLI implementation).
-// ---------------------------------------------------------------------------
-
-const GIT_TEXT_GEN_PROVIDERS = new Set<ProviderKind>([
-  "codex",
-  "claudeAgent",
-  "copilot",
-  "cursor",
-  "opencode",
-]);
-
-class CodexTextGen extends Context.Service<CodexTextGen, TextGenerationShape>()(
-  "t3/git/Layers/RoutingTextGeneration/CodexTextGen",
-) {}
-
-class ClaudeTextGen extends Context.Service<ClaudeTextGen, TextGenerationShape>()(
-  "t3/git/Layers/RoutingTextGeneration/ClaudeTextGen",
-) {}
-
-class CopilotTextGen extends Context.Service<CopilotTextGen, CopilotTextGenerationShape>()(
-  "t3/git/Layers/RoutingTextGeneration/CopilotTextGen",
-) {}
-
-class CursorTextGen extends Context.Service<CursorTextGen, TextGenerationShape>()(
-  "t3/git/Layers/RoutingTextGeneration/CursorTextGen",
-) {}
-
-class OpenCodeTextGen extends Context.Service<OpenCodeTextGen, TextGenerationShape>()(
-  "t3/git/Layers/RoutingTextGeneration/OpenCodeTextGen",
-) {}
-
-// ---------------------------------------------------------------------------
-// Routing implementation
-// ---------------------------------------------------------------------------
-
-const makeRoutingTextGeneration = Effect.gen(function* () {
-  const codex = yield* CodexTextGen;
-  const claude = yield* ClaudeTextGen;
-  const copilot = yield* CopilotTextGen;
-  const cursor = yield* CursorTextGen;
-  const openCode = yield* OpenCodeTextGen;
-
-  const route = (provider?: ProviderKind): TextGenerationShape => {
-    if (!provider || !GIT_TEXT_GEN_PROVIDERS.has(provider)) return codex;
-    if (provider === "claudeAgent") return claude;
-    if (provider === "cursor") return cursor;
-    if (provider === "opencode") return openCode;
-    if (provider === "copilot") {
-      return {
-        generateCommitMessage: copilot.generateCommitMessage,
-        generatePrContent: copilot.generatePrContent,
-        // Copilot text generation doesn't support these yet; fall back to codex.
-        generateBranchName: codex.generateBranchName,
-        generateThreadTitle: codex.generateThreadTitle,
-      };
-    }
-    return 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));
-
-const InternalCopilotLayer = Layer.effect(
-  CopilotTextGen,
-  Effect.gen(function* () {
-    const svc = yield* CopilotTextGeneration;
-    return svc;
-  }),
-).pipe(Layer.provide(makeCopilotTextGenerationLive()));
-
-const InternalCursorLayer = Layer.effect(
-  CursorTextGen,
-  Effect.gen(function* () {
-    const svc = yield* TextGeneration;
-    return svc;
-  }),
-).pipe(Layer.provide(CursorTextGenerationLive));
-
-const InternalOpenCodeLayer = Layer.effect(
-  OpenCodeTextGen,
-  Effect.gen(function* () {
-    const svc = yield* TextGeneration;
-    return svc;
-  }),
-).pipe(Layer.provide(OpenCodeTextGenerationLive));
-
-export const RoutingTextGenerationLive = Layer.effect(
-  TextGeneration,
-  makeRoutingTextGeneration,
-).pipe(
-  Layer.provide(InternalCodexLayer),
-  Layer.provide(InternalClaudeLayer),
-  Layer.provide(InternalCopilotLayer),
-  Layer.provide(InternalCursorLayer),
-  Layer.provide(InternalOpenCodeLayer),
-);
diff --git a/apps/server/src/git/Layers/SessionTextGeneration.test.ts b/apps/server/src/git/Layers/SessionTextGeneration.test.ts
deleted file mode 100644
index b5dd2924486..00000000000
--- a/apps/server/src/git/Layers/SessionTextGeneration.test.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { SessionTextGenerationLive } from "./SessionTextGeneration.ts";
-
-describe("SessionTextGeneration", () => {
-  it("exports a valid Layer", () => {
-    expect(SessionTextGenerationLive).toBeDefined();
-  });
-});
diff --git a/apps/server/src/git/Layers/SessionTextGeneration.ts b/apps/server/src/git/Layers/SessionTextGeneration.ts
deleted file mode 100644
index 66c0dda9bf6..00000000000
--- a/apps/server/src/git/Layers/SessionTextGeneration.ts
+++ /dev/null
@@ -1,492 +0,0 @@
-import { randomUUID } from "node:crypto";
-
-import type { ProviderRuntimeEvent, ThreadId } from "@t3tools/contracts";
-import { Effect, Layer, Option, Queue, Schema, SchemaIssue, Stream } from "effect";
-import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
-import { resolveModelSlugForProvider } from "@t3tools/shared/model";
-
-import { ProviderService } from "../../provider/Services/ProviderService.ts";
-import { TextGenerationError } from "@t3tools/contracts";
-import {
-  type BranchNameGenerationInput,
-  type BranchNameGenerationResult,
-  type CommitMessageGenerationResult,
-  type PrContentGenerationResult,
-  type ThreadTitleGenerationInput,
-  type ThreadTitleGenerationResult,
-} from "../Services/TextGeneration.ts";
-import {
-  SessionTextGeneration,
-  type SessionTextGenerationShape,
-} from "../Services/SessionTextGeneration.ts";
-
-const PROVIDER_TEXT_GENERATION_TIMEOUT_MS = 180_000;
-
-function limitSection(value: string, maxChars: number): string {
-  if (value.length <= maxChars) return value;
-  return `${value.slice(0, maxChars)}\n\n[truncated]`;
-}
-
-function sanitizePrTitle(raw: string): string {
-  const singleLine = raw.trim().split(/\r?\n/g)[0]?.trim() ?? "";
-  return singleLine.length > 0 ? singleLine : "Update project changes";
-}
-
-function sanitizeThreadTitle(raw: string): string {
-  const singleLine = raw.trim().split(/\r?\n/g)[0]?.trim() ?? "";
-  return singleLine.length > 0 ? singleLine : "New thread";
-}
-
-function extractJsonObject(raw: string): string {
-  const trimmed = raw.trim();
-  if (trimmed.startsWith("```")) {
-    const fenced = trimmed.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "");
-    return fenced.trim();
-  }
-  const start = trimmed.indexOf("{");
-  const end = trimmed.lastIndexOf("}");
-  if (start !== -1 && end !== -1 && end > start) {
-    return trimmed.slice(start, end + 1);
-  }
-  return trimmed;
-}
-
-function toThreadId(value: string): ThreadId {
-  return value as ThreadId;
-}
-
-function normalizeProviderTextGenerationError(
-  operation:
-    | "generateCommitMessage"
-    | "generatePrContent"
-    | "generateBranchName"
-    | "generateThreadTitle",
-  error: unknown,
-  fallback: string,
-): TextGenerationError {
-  if (Schema.is(TextGenerationError)(error)) {
-    return error;
-  }
-
-  if (error instanceof Error) {
-    return new TextGenerationError({
-      operation,
-      detail: `${fallback}: ${error.message}`,
-      cause: error,
-    });
-  }
-
-  return new TextGenerationError({
-    operation,
-    detail: fallback,
-    cause: error,
-  });
-}
-
-function decodeJsonResponse<S extends Schema.Top>(
-  operation:
-    | "generateCommitMessage"
-    | "generatePrContent"
-    | "generateBranchName"
-    | "generateThreadTitle",
-  raw: string,
-  schema: S,
-): Effect.Effect<S["Type"], TextGenerationError, S["DecodingServices"]> {
-  return Effect.gen(function* () {
-    const jsonText = extractJsonObject(raw);
-    if (jsonText.length === 0) {
-      return yield* new TextGenerationError({
-        operation,
-        detail: "Provider returned an empty response.",
-      });
-    }
-
-    const parsed = yield* Effect.try({
-      try: () => JSON.parse(jsonText) as unknown,
-      catch: (cause) =>
-        normalizeProviderTextGenerationError(operation, cause, "Provider returned invalid JSON"),
-    });
-
-    return yield* Schema.decodeUnknownEffect(schema)(parsed).pipe(
-      Effect.mapError(
-        (cause) =>
-          new TextGenerationError({
-            operation,
-            detail: `Provider returned an unexpected payload: ${SchemaIssue.makeFormatterDefault()(cause.issue)}`,
-            cause,
-          }),
-      ),
-    );
-  });
-}
-
-function assistantMessageFromEvent(event: ProviderRuntimeEvent): string | null {
-  if (
-    event.type !== "item.completed" ||
-    event.payload.itemType !== "assistant_message" ||
-    typeof event.payload.detail !== "string"
-  ) {
-    return null;
-  }
-  const trimmed = event.payload.detail.trim();
-  return trimmed.length > 0 ? trimmed : null;
-}
-
-const makeSessionTextGeneration = Effect.gen(function* () {
-  const providerService = yield* ProviderService;
-
-  const runProviderJson = <S extends Schema.Top>({
-    operation,
-    cwd,
-    provider,
-    model,
-    prompt,
-    attachments,
-    schema,
-  }: {
-    operation:
-      | "generateCommitMessage"
-      | "generatePrContent"
-      | "generateBranchName"
-      | "generateThreadTitle";
-    cwd: string;
-    provider: BranchNameGenerationInput["provider"];
-    model: BranchNameGenerationInput["model"];
-    prompt: string;
-    attachments?: BranchNameGenerationInput["attachments"];
-    schema: S;
-  }): Effect.Effect<S["Type"], TextGenerationError, S["DecodingServices"]> =>
-    Effect.gen(function* () {
-      const resolvedProvider = provider ?? "codex";
-      const resolvedModel = resolveModelSlugForProvider(resolvedProvider, model);
-      const threadId = toThreadId(`git-textgen-${operation}-${randomUUID()}`);
-      const eventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
-
-      yield* Stream.runForEach(providerService.streamEvents, (event) => {
-        if (event.threadId !== threadId) {
-          return Effect.void;
-        }
-        return Queue.offer(eventQueue, event).pipe(Effect.asVoid);
-      }).pipe(Effect.forkScoped);
-
-      const cleanup = providerService.stopSession({ threadId }).pipe(
-        Effect.tapError((e) => Effect.logWarning("Failed to stop text generation session", e)),
-        Effect.orElseSucceed(() => undefined),
-        Effect.asVoid,
-      );
-
-      return yield* Effect.gen(function* () {
-        yield* providerService.startSession(threadId, {
-          threadId,
-          provider: resolvedProvider,
-          cwd,
-          ...(resolvedModel
-            ? { modelSelection: { provider: resolvedProvider, model: resolvedModel } as never }
-            : {}),
-          runtimeMode: "approval-required",
-        });
-
-        const turn = yield* providerService.sendTurn({
-          threadId,
-          input: prompt,
-          ...(resolvedModel
-            ? { modelSelection: { provider: resolvedProvider, model: resolvedModel } as never }
-            : {}),
-          ...(attachments && attachments.length > 0 ? { attachments } : {}),
-          interactionMode: "default",
-        });
-
-        let assistantText = "";
-        let fallbackAssistantMessage: string | null = null;
-
-        while (true) {
-          const event = yield* Queue.take(eventQueue);
-          if (event.turnId !== undefined && event.turnId !== turn.turnId) {
-            continue;
-          }
-
-          if (event.type === "content.delta" && event.payload.streamKind === "assistant_text") {
-            assistantText += event.payload.delta;
-            continue;
-          }
-
-          const assistantMessage = assistantMessageFromEvent(event);
-          if (assistantMessage && fallbackAssistantMessage === null) {
-            fallbackAssistantMessage = assistantMessage;
-            continue;
-          }
-
-          if (event.type === "request.opened") {
-            return yield* new TextGenerationError({
-              operation,
-              detail: `The ${resolvedProvider} provider requested '${event.payload.requestType}' while generating git text. Git text generation must run without tools or approvals.`,
-            });
-          }
-
-          if (event.type === "user-input.requested") {
-            return yield* new TextGenerationError({
-              operation,
-              detail: `The ${resolvedProvider} provider requested interactive input while generating git text.`,
-            });
-          }
-
-          if (event.type === "runtime.error") {
-            return yield* new TextGenerationError({
-              operation,
-              detail: `${resolvedProvider} provider runtime error: ${event.payload.message}`,
-            });
-          }
-
-          if (event.type === "session.exited") {
-            return yield* new TextGenerationError({
-              operation,
-              detail: `${resolvedProvider} provider session exited unexpectedly during text generation.`,
-            });
-          }
-
-          if (event.type === "turn.completed") {
-            if (event.payload.state !== "completed") {
-              return yield* new TextGenerationError({
-                operation,
-                detail:
-                  event.payload.errorMessage ??
-                  `${resolvedProvider} provider turn ended with state '${event.payload.state}'.`,
-              });
-            }
-
-            const responseText = assistantText.trim() || fallbackAssistantMessage?.trim() || "";
-            return yield* decodeJsonResponse(operation, responseText, schema);
-          }
-        }
-      }).pipe(
-        Effect.timeoutOption(PROVIDER_TEXT_GENERATION_TIMEOUT_MS),
-        Effect.flatMap(
-          Option.match({
-            onNone: () =>
-              Effect.fail(
-                new TextGenerationError({
-                  operation,
-                  detail: `${resolvedProvider} provider request timed out.`,
-                }),
-              ),
-            onSome: (result) => Effect.succeed(result),
-          }),
-        ),
-        Effect.ensuring(cleanup),
-        Effect.scoped,
-      );
-    }).pipe(
-      Effect.mapError((cause) =>
-        normalizeProviderTextGenerationError(
-          operation,
-          cause,
-          "Provider git text generation failed",
-        ),
-      ),
-    );
-
-  const generateCommitMessage: SessionTextGenerationShape["generateCommitMessage"] = (input) => {
-    const wantsBranch = input.includeBranch === true;
-    const prompt = [
-      "You write concise git commit messages.",
-      "Answer using only valid JSON. Do not use tools, do not ask for approvals, and do not add markdown fences or prose.",
-      wantsBranch
-        ? 'Return a JSON object with keys: "subject", "body", "branch".'
-        : 'Return a JSON object with keys: "subject", "body".',
-      "Rules:",
-      "- subject must be imperative, <= 72 chars, and have no trailing period",
-      "- body can be an empty string or short bullet points",
-      ...(wantsBranch
-        ? ["- branch must be a short semantic git branch fragment for this change"]
-        : []),
-      "- capture the primary user-visible or developer-visible change",
-      "",
-      `Branch: ${input.branch ?? "(detached)"}`,
-      "",
-      "Staged files:",
-      limitSection(input.stagedSummary, 6_000),
-      "",
-      "Staged patch:",
-      limitSection(input.stagedPatch, 40_000),
-    ].join("\n");
-
-    const schema = wantsBranch
-      ? Schema.Struct({
-          subject: Schema.String,
-          body: Schema.String,
-          branch: Schema.String,
-        })
-      : Schema.Struct({
-          subject: Schema.String,
-          body: Schema.String,
-        });
-
-    return runProviderJson({
-      operation: "generateCommitMessage",
-      cwd: input.cwd,
-      provider: input.provider,
-      model: input.model,
-      prompt,
-      schema,
-    }).pipe(
-      Effect.map(
-        (generated) =>
-          ({
-            subject: generated.subject,
-            body: generated.body.trim(),
-            ...("branch" in generated && typeof generated.branch === "string"
-              ? { branch: sanitizeFeatureBranchName(generated.branch) }
-              : {}),
-          }) satisfies CommitMessageGenerationResult,
-      ),
-    );
-  };
-
-  const generatePrContent: SessionTextGenerationShape["generatePrContent"] = (input) => {
-    const prompt = [
-      "You write GitHub pull request content.",
-      "Answer using only valid JSON. Do not use tools, do not ask for approvals, and do not add markdown fences or prose.",
-      'Return a JSON object with keys: "title", "body".',
-      "Rules:",
-      "- title should be concise and specific",
-      "- 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",
-      "",
-      `Base branch: ${input.baseBranch}`,
-      `Head branch: ${input.headBranch}`,
-      "",
-      "Commits:",
-      limitSection(input.commitSummary, 12_000),
-      "",
-      "Diff stat:",
-      limitSection(input.diffSummary, 12_000),
-      "",
-      "Diff patch:",
-      limitSection(input.diffPatch, 40_000),
-    ].join("\n");
-
-    return runProviderJson({
-      operation: "generatePrContent",
-      cwd: input.cwd,
-      provider: input.provider,
-      model: input.model,
-      prompt,
-      schema: Schema.Struct({
-        title: Schema.String,
-        body: Schema.String,
-      }),
-    }).pipe(
-      Effect.map(
-        (generated) =>
-          ({
-            title: sanitizePrTitle(generated.title),
-            body: generated.body.trim(),
-          }) satisfies PrContentGenerationResult,
-      ),
-    );
-  };
-
-  const generateBranchName: SessionTextGenerationShape["generateBranchName"] = (input) => {
-    const attachmentLines = (input.attachments ?? []).map(
-      (attachment) =>
-        `- ${attachment.name} (${attachment.mimeType}, ${attachment.sizeBytes} bytes)`,
-    );
-    const promptSections = [
-      "You generate concise git branch names.",
-      "Answer using only valid JSON. Do not use tools, do not ask for approvals, and do not add markdown fences or prose.",
-      'Return a JSON object with key: "branch".',
-      "Rules:",
-      "- Branch should describe the requested work from the user message.",
-      "- Keep it short and specific (2-6 words).",
-      "- Use plain words only, no issue prefixes and no punctuation-heavy text.",
-      "- If images are attached, use them as primary context for visual/UI issues.",
-      "",
-      "User message:",
-      limitSection(input.message, 8_000),
-    ];
-    if (attachmentLines.length > 0) {
-      promptSections.push(
-        "",
-        "Attachment metadata:",
-        limitSection(attachmentLines.join("\n"), 4_000),
-      );
-    }
-
-    return runProviderJson({
-      operation: "generateBranchName",
-      cwd: input.cwd,
-      provider: input.provider,
-      model: input.model,
-      prompt: promptSections.join("\n"),
-      attachments: input.attachments,
-      schema: Schema.Struct({
-        branch: Schema.String,
-      }),
-    }).pipe(
-      Effect.map(
-        (generated) =>
-          ({
-            branch: sanitizeBranchFragment(generated.branch),
-          }) satisfies BranchNameGenerationResult,
-      ),
-    );
-  };
-
-  const generateThreadTitle: SessionTextGenerationShape["generateThreadTitle"] = (input) => {
-    const attachmentLines = (input.attachments ?? []).map(
-      (attachment) =>
-        `- ${attachment.name} (${attachment.mimeType}, ${attachment.sizeBytes} bytes)`,
-    );
-    const promptSections = [
-      "You generate concise thread titles.",
-      "Answer using only valid JSON. Do not use tools, do not ask for approvals, and do not add markdown fences or prose.",
-      'Return a JSON object with key: "title".',
-      "Rules:",
-      "- Keep the title short and specific.",
-      "- Use the user's request as the main signal.",
-      "- If images are attached, use them as primary context for visual/UI issues.",
-      "",
-      "User message:",
-      limitSection(input.message, 8_000),
-    ];
-    if (attachmentLines.length > 0) {
-      promptSections.push(
-        "",
-        "Attachment metadata:",
-        limitSection(attachmentLines.join("\n"), 4_000),
-      );
-    }
-
-    return runProviderJson({
-      operation: "generateThreadTitle",
-      cwd: input.cwd,
-      provider: input.modelSelection.provider,
-      model: input.modelSelection.model,
-      prompt: promptSections.join("\n"),
-      attachments: input.attachments,
-      schema: Schema.Struct({
-        title: Schema.String,
-      }),
-    }).pipe(
-      Effect.map(
-        (generated) =>
-          ({
-            title: sanitizeThreadTitle(generated.title),
-          }) satisfies ThreadTitleGenerationResult,
-      ),
-    );
-  };
-
-  return {
-    generateCommitMessage,
-    generatePrContent,
-    generateBranchName,
-    generateThreadTitle,
-  } satisfies SessionTextGenerationShape;
-});
-
-export const SessionTextGenerationLive = Layer.effect(
-  SessionTextGeneration,
-  makeSessionTextGeneration,
-);
diff --git a/apps/server/src/git/Services/CopilotTextGeneration.ts b/apps/server/src/git/Services/CopilotTextGeneration.ts
deleted file mode 100644
index 45e2f117da1..00000000000
--- a/apps/server/src/git/Services/CopilotTextGeneration.ts
+++ /dev/null
@@ -1,24 +0,0 @@
-import { Context } from "effect";
-import type { Effect } from "effect";
-
-import type { TextGenerationError } from "@t3tools/contracts";
-import type {
-  CommitMessageGenerationInput,
-  CommitMessageGenerationResult,
-  PrContentGenerationInput,
-  PrContentGenerationResult,
-} from "./TextGeneration.ts";
-
-export interface CopilotTextGenerationShape {
-  readonly generateCommitMessage: (
-    input: CommitMessageGenerationInput,
-  ) => Effect.Effect<CommitMessageGenerationResult, TextGenerationError>;
-  readonly generatePrContent: (
-    input: PrContentGenerationInput,
-  ) => Effect.Effect<PrContentGenerationResult, TextGenerationError>;
-}
-
-export class CopilotTextGeneration extends Context.Service<
-  CopilotTextGeneration,
-  CopilotTextGenerationShape
->()("t3/git/Services/CopilotTextGeneration") {}
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 53138926629..00000000000
--- a/apps/server/src/git/Services/GitHubCli.ts
+++ /dev/null
@@ -1,104 +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.ts";
-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;
-    readonly repository?: 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/Services/SessionTextGeneration.ts b/apps/server/src/git/Services/SessionTextGeneration.ts
deleted file mode 100644
index 351f3fa3603..00000000000
--- a/apps/server/src/git/Services/SessionTextGeneration.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { Context } from "effect";
-
-import type { TextGenerationShape } from "./TextGeneration.ts";
-
-export interface SessionTextGenerationShape extends TextGenerationShape {}
-
-export class SessionTextGeneration extends Context.Service<
-  SessionTextGeneration,
-  SessionTextGenerationShape
->()("t3/git/Services/SessionTextGeneration") {}
diff --git a/apps/server/src/git/Utils.ts b/apps/server/src/git/Utils.ts
index 15015e8cda5..6faf3e99c77 100644
--- a/apps/server/src/git/Utils.ts
+++ b/apps/server/src/git/Utils.ts
@@ -1,171 +1,6 @@
-/**
- * Shared utilities for text generation layers (Codex, Claude, etc.).
- *
- * @module textGenerationUtils
- */
-import { Schema } from "effect";
-
-import { TextGenerationError } from "@t3tools/contracts";
-
 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]`;
-}
-
-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);
-}
-
-/** 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/keybindings.ts b/apps/server/src/keybindings.ts
index 9a29378a8a2..eec0f23e553 100644
--- a/apps/server/src/keybindings.ts
+++ b/apps/server/src/keybindings.ts
@@ -13,14 +13,10 @@ import {
   KeybindingShortcut,
   KeybindingWhenNode,
   MAX_KEYBINDINGS_COUNT,
-  MODEL_PICKER_JUMP_KEYBINDING_COMMANDS,
-  MAX_WHEN_EXPRESSION_DEPTH,
   ResolvedKeybindingRule,
   ResolvedKeybindingsConfig,
-  THREAD_JUMP_KEYBINDING_COMMANDS,
   type ServerConfigIssue,
 } from "@t3tools/contracts";
-import type { Mutable } from "effect/Types";
 import {
   Array,
   Cache,
@@ -48,278 +44,20 @@ import * as Semaphore from "effect/Semaphore";
 import { ServerConfig } from "./config.ts";
 import { writeFileStringAtomically } from "./atomicWrite.ts";
 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+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;
-}
-
-/** @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 {
+  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(
@@ -412,8 +150,6 @@ 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(
diff --git a/apps/server/src/kiloServerManager.test.ts b/apps/server/src/kiloServerManager.test.ts
index a863e7b9e28..aff45303f72 100644
--- a/apps/server/src/kiloServerManager.test.ts
+++ b/apps/server/src/kiloServerManager.test.ts
@@ -7,8 +7,22 @@ import {
   type KiloClient,
   type KiloProviderSession,
   type KiloSessionContext,
+  type SharedServerState,
 } from "./kilo/types.ts";
 
+vi.mock("./kilo/serverLifecycle.ts", async () => {
+  const actual =
+    await vi.importActual<typeof import("./kilo/serverLifecycle.ts")>(
+      "./kilo/serverLifecycle.ts",
+    );
+  return {
+    ...actual,
+    ensureServer: vi.fn(),
+  };
+});
+
+import * as ServerLifecycle from "./kilo/serverLifecycle.ts";
+
 class TestKiloServerManager extends KiloServerManager {
   seedSession(context: KiloSessionContext) {
     (this as unknown as { sessions: Map<ThreadId, KiloSessionContext> }).sessions.set(
@@ -139,3 +153,58 @@ describe("KiloServerManager.respondToRequest", () => {
     expect(context.activeTurnId).toBe(TurnId.make("turn-kilo"));
   });
 });
+
+describe("KiloServerManager.getOrStartServer", () => {
+  it("kills the spawned server child on stopAll (manager-owned lifecycle)", async () => {
+    // Regression: KiloTextGeneration previously called the standalone
+    // `ensureServer` helper directly and stored the returned server in a
+    // local closure variable, so the manager's `stopAll()` finalizer never
+    // killed the spawned child. Routing through `getOrStartServer` keeps the
+    // child owned by the manager.
+    const childKill = vi.fn();
+    const fakeServer = {
+      baseUrl: "http://127.0.0.1:1",
+      child: { kill: childKill, killed: false } as unknown,
+      authHeader: undefined,
+    } as unknown as SharedServerState;
+
+    const ensureServerMock = vi.mocked(ServerLifecycle.ensureServer);
+    ensureServerMock.mockReset();
+    ensureServerMock.mockResolvedValue({ state: fakeServer, serverPromise: undefined });
+
+    const manager = new KiloServerManager();
+    const server = await manager.getOrStartServer({ binaryPath: "kilo" });
+    expect(server).toBe(fakeServer);
+
+    manager.stopAll();
+    expect(childKill).toHaveBeenCalledTimes(1);
+  });
+
+  it("serializes concurrent starts so callers share one server", async () => {
+    let started = 0;
+    const ensureServerMock = vi.mocked(ServerLifecycle.ensureServer);
+    ensureServerMock.mockReset();
+    ensureServerMock.mockImplementation(async () => {
+      started += 1;
+      // Simulate an async start — both callers should see the same pending
+      // promise and end up with the same SharedServerState.
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      const fakeServer = {
+        baseUrl: `http://127.0.0.1:${started}`,
+        child: { kill: vi.fn(), killed: false } as unknown,
+        authHeader: undefined,
+      } as unknown as SharedServerState;
+      return { state: fakeServer, serverPromise: undefined };
+    });
+
+    const manager = new KiloServerManager();
+    const [a, b] = await Promise.all([
+      manager.getOrStartServer({ binaryPath: "kilo" }),
+      manager.getOrStartServer({ binaryPath: "kilo" }),
+    ]);
+    expect(started).toBe(1);
+    expect(a).toBe(b);
+
+    manager.stopAll();
+  });
+});
diff --git a/apps/server/src/kiloServerManager.ts b/apps/server/src/kiloServerManager.ts
index 728c5c048cb..d1537a3ad3c 100644
--- a/apps/server/src/kiloServerManager.ts
+++ b/apps/server/src/kiloServerManager.ts
@@ -552,6 +552,16 @@ export class KiloServerManager extends EventEmitter<KiloManagerEvents> {
     this.serverPromise = undefined;
   }
 
+  /**
+   * Returns the manager's shared Kilo server, starting it if needed. The child
+   * process is owned by this manager — `stopAll()` will kill it. Use this from
+   * callers (e.g. text generation) that need the server but don't want to
+   * register a full session on the manager.
+   */
+  async getOrStartServer(options?: KiloProviderOptions): Promise<SharedServerState> {
+    return this.ensureServer(options);
+  }
+
   private requireSession(threadId: ThreadId): KiloSessionContext {
     const context = this.sessions.get(threadId);
     if (!context) {
diff --git a/apps/server/src/observability/Metrics.test.ts b/apps/server/src/observability/Metrics.test.ts
index 4604f43b63a..b5eeedaaa43 100644
--- a/apps/server/src/observability/Metrics.test.ts
+++ b/apps/server/src/observability/Metrics.test.ts
@@ -1,4 +1,5 @@
 import { assert, describe, it } from "@effect/vitest";
+import { ProviderDriverKind } from "@t3tools/contracts";
 import { Effect, Metric } from "effect";
 
 import { withMetrics } from "./Metrics.ts";
@@ -75,10 +76,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 +95,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,7 +103,7 @@ describe("withMetrics", () => {
       );
       assert.equal(
         hasMetricSnapshot(snapshots, "with_metrics_lazy_duration", {
-          provider: "codex",
+          provider: lazyInittedProvider,
           operation: "lazy",
         }),
         true,
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
index 954c4d4726c..ad5fb59bd1e 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
@@ -3,7 +3,12 @@ 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,
@@ -19,8 +24,9 @@ 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";
@@ -50,7 +56,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,7 +70,7 @@ function createProviderServiceHarness(
   cwd: string,
   hasSession = true,
   sessionCwd = cwd,
-  providerName: ProviderSession["provider"] = "codex",
+  providerName: ProviderSession["provider"] = ProviderDriverKind.make("codex"),
 ) {
   const now = new Date().toISOString();
   const runtimeEventPubSub = Effect.runSync(PubSub.unbounded<ProviderRuntimeEvent>());
@@ -96,7 +102,18 @@ function createProviderServiceHarness(
     respondToUserInput: () => unsupported(),
     stopSession: () => unsupported(),
     listSessions,
-    getCapabilities: () => Effect.succeed({ sessionModelSwitch: "in-session" } as any),
+    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);
@@ -243,7 +260,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 +269,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),
@@ -266,7 +283,7 @@ describe("CheckpointReactor", () => {
     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 +291,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 },
           }),
@@ -289,11 +306,16 @@ describe("CheckpointReactor", () => {
       Layer.provideMerge(orchestrationLayer),
       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),
     );
@@ -315,7 +337,7 @@ describe("CheckpointReactor", () => {
         title: "Test Project",
         workspaceRoot: options?.projectWorkspaceRoot ?? cwd,
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -329,7 +351,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,
@@ -396,7 +418,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -411,7 +433,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -457,7 +479,7 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-refresh-local-status"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-refresh-local-status"),
@@ -494,7 +516,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -510,7 +532,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -526,7 +548,7 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-main"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
 
       createdAt: new Date().toISOString(),
       threadId: ThreadId.make("thread-1"),
@@ -544,7 +566,7 @@ 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();
 
@@ -569,7 +591,7 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.started",
       eventId: EventId.make("evt-turn-started-claude-1"),
-      provider: "claudeAgent",
+      provider: ProviderDriverKind.make("claudeAgent"),
       createdAt: new Date().toISOString(),
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-claude-1"),
@@ -583,7 +605,7 @@ describe("CheckpointReactor", () => {
     harness.provider.emit({
       type: "turn.completed",
       eventId: EventId.make("evt-turn-completed-claude-1"),
-      provider: "claudeAgent",
+      provider: ProviderDriverKind.make("claudeAgent"),
       createdAt: new Date().toISOString(),
       threadId: ThreadId.make("thread-1"),
       turnId: asTurnId("turn-claude-1"),
@@ -627,7 +649,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -716,7 +738,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -762,7 +784,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -812,7 +834,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -823,7 +845,7 @@ 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(),
       threadId: ThreadId.make("thread-1"),
@@ -918,7 +940,7 @@ describe("CheckpointReactor", () => {
   });
 
   it("executes provider revert and emits thread.reverted for claude sessions", async () => {
-    const harness = await createHarness({ providerName: "claudeAgent" });
+    const harness = await createHarness({ providerName: ProviderDriverKind.make("claudeAgent") });
     const createdAt = new Date().toISOString();
 
     await Effect.runPromise(
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
index 71445b4671d..e534f6851ae 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
@@ -24,7 +24,7 @@ import { RuntimeReceiptBus } from "../Services/RuntimeReceiptBus.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";
 
 type ReactorInput =
@@ -70,7 +70,7 @@ const make = Effect.gen(function* () {
   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;
@@ -237,6 +237,7 @@ const make = Effect.gen(function* () {
         fromCheckpointRef,
         toCheckpointRef: targetCheckpointRef,
         fallbackFromToHead: false,
+        ignoreWhitespace: false,
       })
       .pipe(
         Effect.map((diff) =>
@@ -508,7 +509,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,
diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
index b61664f1619..0af5b099a64 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
@@ -7,6 +7,7 @@ import {
   ThreadId,
   TurnId,
   type OrchestrationEvent,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
 import { Effect, Layer, ManagedRuntime, Metric, Option, Queue, Stream } from "effect";
 import { describe, expect, it } from "vitest";
@@ -104,7 +105,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 +120,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,
@@ -198,7 +199,7 @@ describe("OrchestrationEngine", () => {
         title: "Project 1",
         workspaceRoot: "/tmp/project-1",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -212,7 +213,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,
@@ -258,7 +259,7 @@ describe("OrchestrationEngine", () => {
         title: "Project Archive",
         workspaceRoot: "/tmp/project-archive",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -272,7 +273,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,
@@ -325,7 +326,7 @@ describe("OrchestrationEngine", () => {
         title: "Replay Project",
         workspaceRoot: "/tmp/project-replay",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -339,7 +340,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,
@@ -383,7 +384,7 @@ describe("OrchestrationEngine", () => {
         title: "Stream Project",
         workspaceRoot: "/tmp/project-stream",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -407,7 +408,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,
@@ -444,7 +445,7 @@ describe("OrchestrationEngine", () => {
         title: "Ack Project",
         workspaceRoot: "/tmp/project-ack",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -459,7 +460,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,
@@ -496,7 +497,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,
@@ -533,7 +534,7 @@ describe("OrchestrationEngine", () => {
         title: "Turn Diff Project",
         workspaceRoot: "/tmp/project-turn-diff",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -547,7 +548,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,
@@ -652,7 +653,7 @@ describe("OrchestrationEngine", () => {
         title: "Flaky Project",
         workspaceRoot: "/tmp/project-flaky",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -668,7 +669,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,
@@ -688,7 +689,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,
@@ -747,7 +748,7 @@ describe("OrchestrationEngine", () => {
         title: "Atomic Project",
         workspaceRoot: "/tmp/project-atomic",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -761,7 +762,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,
@@ -890,7 +891,7 @@ describe("OrchestrationEngine", () => {
         title: "Sync Project",
         workspaceRoot: "/tmp/project-sync",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -904,7 +905,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,
@@ -975,7 +976,7 @@ describe("OrchestrationEngine", () => {
         title: "Duplicate Project",
         workspaceRoot: "/tmp/project-duplicate",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -990,7 +991,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,
@@ -1010,7 +1011,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/ProjectionPipeline.test.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
index 7a08765647f..7f364c717a7 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
@@ -7,6 +7,7 @@ import {
   ProjectId,
   ThreadId,
   TurnId,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
@@ -92,7 +93,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",
@@ -364,7 +365,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",
@@ -492,7 +493,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",
@@ -640,7 +641,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",
@@ -769,7 +770,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",
@@ -977,7 +978,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",
@@ -1140,7 +1141,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",
@@ -1267,7 +1268,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 +1408,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",
@@ -1551,7 +1552,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
           projectId: ProjectId.make("project-stale-approval"),
           title: "Thread Stale Approval",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "approval-required",
@@ -1694,7 +1695,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
           projectId: ProjectId.make("project-nonstale-approval"),
           title: "Thread Non-Stale Approval",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           runtimeMode: "approval-required",
@@ -1874,7 +1875,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",
@@ -2195,7 +2196,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,
@@ -2233,7 +2234,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,
@@ -2253,7 +2254,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
           },
         ],
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
       });
@@ -2272,7 +2273,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 d981ae0da62..28a0208e75c 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
@@ -945,6 +945,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,
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
index 9f0d63545fc..cba5ce7e830 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
@@ -1,4 +1,12 @@
-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 SqlClient from "effect/unstable/sql/SqlClient";
@@ -252,7 +260,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           workspaceRoot: "/tmp/project-1",
           repositoryIdentity: null,
           defaultModelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           scripts: [
@@ -275,7 +283,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           projectId: asProjectId("project-1"),
           title: "Thread 1",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: "default",
@@ -363,7 +371,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           workspaceRoot: "/tmp/project-1",
           repositoryIdentity: null,
           defaultModelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           scripts: [
@@ -385,7 +393,7 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           projectId: asProjectId("project-1"),
           title: "Thread 1",
           modelSelection: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5-codex",
           },
           interactionMode: "default",
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
index ddcc99902b8..10639c1b42d 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
@@ -195,6 +195,7 @@ function mapSessionRow(
     threadId: row.threadId,
     status: row.status,
     providerName: row.providerName,
+    ...(row.providerInstanceId !== null ? { providerInstanceId: row.providerInstanceId } : {}),
     runtimeMode: row.runtimeMode,
     activeTurnId: row.activeTurnId,
     lastError: row.lastError,
@@ -351,6 +352,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",
@@ -609,6 +611,7 @@ const makeProjectionSnapshotQuery = 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",
@@ -880,6 +883,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,
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
index ce796de7842..09252571c37 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
@@ -2,7 +2,14 @@ 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,
@@ -26,25 +33,22 @@ import {
   ProviderService,
   type ProviderServiceShape,
 } from "../../provider/Services/ProviderService.ts";
-import { GitCore, type GitCoreShape } from "../../git/Services/GitCore.ts";
-import {
-  GitStatusBroadcaster,
-  type GitStatusBroadcasterShape,
-} from "../../git/Services/GitStatusBroadcaster.ts";
-import {
-  TextGeneration,
-  type TextGenerationShape,
-  type ThreadTitleGenerationResult,
-} 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 * as NodeServices from "@effect/platform-node/NodeServices";
 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);
@@ -101,6 +105,30 @@ 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;
@@ -115,7 +143,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) => {
@@ -131,8 +159,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" &&
@@ -147,7 +191,9 @@ describe("ProviderCommandReactor", () => {
         typeof input.cwd === "string"
           ? { cwd: input.cwd }
           : {}),
-        ...(modelSelection.model !== undefined ? { model: modelSelection.model } : {}),
+        ...((inputModelSelection?.model ?? modelSelection.model)
+          ? { model: inputModelSelection?.model ?? modelSelection.model }
+          : {}),
         threadId,
         resumeCursor: resumeCursor ?? { opaque: `resume-${sessionIndex}` },
         createdAt: now,
@@ -194,9 +240,9 @@ describe("ProviderCommandReactor", () => {
     const refreshStatus = vi.fn((_: string) =>
       Effect.succeed({
         isRepo: true,
-        hasOriginRemote: true,
-        isDefaultBranch: false,
-        branch: "renamed-branch",
+        hasPrimaryRemote: true,
+        isDefaultRef: false,
+        refName: "renamed-branch",
         hasWorkingTreeChanges: false,
         workingTree: {
           files: [],
@@ -217,14 +263,13 @@ describe("ProviderCommandReactor", () => {
         }),
       ),
     );
-    const generateThreadTitle = vi.fn(
-      (_input?: unknown): Effect.Effect<ThreadTitleGenerationResult, TextGenerationError> =>
-        Effect.fail(
-          new TextGenerationError({
-            operation: "generateThreadTitle",
-            detail: "disabled in test harness",
-          }),
-        ),
+    const generateThreadTitle = vi.fn<TextGenerationShape["generateThreadTitle"]>((_) =>
+      Effect.fail(
+        new TextGenerationError({
+          operation: "generateThreadTitle",
+          detail: "disabled in test harness",
+        }),
+      ),
     );
 
     const unsupported = () => Effect.die(new Error("Unsupported provider call in test")) as never;
@@ -239,14 +284,26 @@ describe("ProviderCommandReactor", () => {
       getCapabilities: (_provider) =>
         Effect.succeed({
           sessionModelSwitch: input?.sessionModelSwitch ?? "in-session",
-          transport: "app-server-json-rpc" as const,
-          modelDiscovery: "native" as const,
-          supportsModelDiscovery: true,
-          supportsResume: true,
-          supportsRollback: true,
-          supportsAttachments: true,
-          persistentRuntime: true,
         }),
+      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);
@@ -264,21 +321,25 @@ describe("ProviderCommandReactor", () => {
     const layer = ProviderCommandReactorLive.pipe(
       Layer.provideMerge(orchestrationLayer),
       Layer.provideMerge(Layer.succeed(ProviderService, service)),
-      Layer.provideMerge(Layer.succeed(GitCore, { renameBranch } as unknown as GitCoreShape)),
       Layer.provideMerge(
-        Layer.succeed(GitStatusBroadcaster, {
+        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"),
-        } satisfies GitStatusBroadcasterShape),
+        }),
       ),
       Layer.provideMerge(
         Layer.mock(TextGeneration, {
           generateBranchName,
           generateThreadTitle,
-        } as unknown as TextGenerationShape),
+        }),
       ),
       Layer.provideMerge(ServerSettingsService.layerTest()),
       Layer.provideMerge(ServerConfig.layerTest(process.cwd(), baseDir)),
@@ -331,6 +392,7 @@ describe("ProviderCommandReactor", () => {
       refreshStatus,
       generateBranchName,
       generateThreadTitle,
+      runtimeSessions,
       stateDir,
       drain,
     };
@@ -363,7 +425,7 @@ 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",
@@ -585,14 +647,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,
@@ -602,31 +660,26 @@ 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();
 
@@ -641,13 +694,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,
@@ -657,29 +708,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: "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();
 
@@ -694,13 +744,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,
@@ -710,23 +758,19 @@ 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 }],
+      ),
     });
   });
 
@@ -813,15 +857,15 @@ describe("ProviderCommandReactor", () => {
     expect(harness.sendTurn.mock.calls[1]?.[0]).toMatchObject({
       threadId: ThreadId.make("thread-1"),
       modelSelection: {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5-codex",
       },
     });
   });
 
-  it("rejects a first turn when requested provider conflicts with the thread model", async () => {
+  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();
 
@@ -837,7 +881,7 @@ describe("ProviderCommandReactor", () => {
           attachments: [],
         },
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -846,29 +890,25 @@ 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 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("reuses the same provider session when runtime mode is unchanged", async () => {
@@ -917,9 +957,147 @@ describe("ProviderCommandReactor", () => {
     expect(harness.stopSession.mock.calls.length).toBe(0);
   });
 
+  it("restarts an existing Codex thread on a compatible requested instance", async () => {
+    const harness = await createHarness();
+    const now = new Date().toISOString();
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-compatible-codex-1"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          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.sendTurn.mock.calls.length === 1);
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-compatible-codex-2"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          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: new Date().toISOString(),
+      }),
+    );
+
+    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 Effect.runPromise(harness.engine.getReadModel());
+    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 = new Date().toISOString();
+
+    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.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();
 
@@ -934,13 +1112,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,
@@ -961,13 +1137,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,
@@ -978,13 +1152,11 @@ 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" }],
+      ),
     });
   });
 
@@ -1075,7 +1247,10 @@ 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();
 
@@ -1111,7 +1286,7 @@ 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",
@@ -1219,7 +1394,7 @@ describe("ProviderCommandReactor", () => {
           attachments: [],
         },
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -1245,10 +1420,76 @@ describe("ProviderCommandReactor", () => {
     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");
+    expect(thread?.session?.runtimeMode).toBe("approval-required");
+    expect(
+      thread?.activities.find((activity) => activity.kind === "provider.turn.start.failed"),
+    ).toMatchObject({
+      payload: {
+        detail: expect.stringContaining("cannot switch to 'claudeAgent'"),
+      },
+    });
+  });
+
+  it("rejects cross-driver provider changes after the existing thread session has stopped", async () => {
+    const harness = await createHarness();
+    const now = new Date().toISOString();
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.session.set",
+        commandId: CommandId.make("cmd-session-set-stopped-provider-switch"),
+        threadId: ThreadId.make("thread-1"),
+        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,
+      }),
+    );
+
+    await Effect.runPromise(
+      harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-stopped-provider-switch"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-stopped-provider-switch"),
+          role: "user",
+          text: "continue with claude",
+          attachments: [],
+        },
+        modelSelection: {
+          instanceId: ProviderInstanceId.make("claudeAgent"),
+          model: "claude-opus-4-6",
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: now,
+      }),
+    );
+
+    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
+      );
+    });
+
+    expect(harness.startSession.mock.calls.length).toBe(0);
+    expect(harness.sendTurn.mock.calls.length).toBe(0);
+    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     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'"),
       },
@@ -1338,7 +1579,7 @@ describe("ProviderCommandReactor", () => {
     expect(harness.startSession.mock.calls[0]?.[1]).toMatchObject({
       threadId: ThreadId.make("thread-1"),
       modelSelection: {
-        provider: "codex",
+        instanceId: ProviderInstanceId.make("codex"),
         model: "gpt-5-codex",
       },
       runtimeMode: "approval-required",
@@ -1348,6 +1589,77 @@ describe("ProviderCommandReactor", () => {
     });
   });
 
+  it("rejects active runtime sessions that are missing provider instance ids", async () => {
+    const harness = await createHarness();
+    const now = new Date().toISOString();
+
+    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 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
+      );
+    });
+
+    expect(harness.startSession.mock.calls.length).toBe(0);
+    expect(harness.sendTurn.mock.calls.length).toBe(0);
+    const readModel = await Effect.runPromise(harness.engine.getReadModel());
+    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();
@@ -1440,7 +1752,7 @@ describe("ProviderCommandReactor", () => {
     harness.respondToRequest.mockImplementation(() =>
       Effect.fail(
         new ProviderAdapterRequestError({
-          provider: "cursor",
+          provider: ProviderDriverKind.make("codex"),
           method: "session/request_permission",
           detail: "Unknown pending permission request: approval-request-1",
         }),
@@ -1455,7 +1767,7 @@ describe("ProviderCommandReactor", () => {
         session: {
           threadId: ThreadId.make("thread-1"),
           status: "running",
-          providerName: "cursor",
+          providerName: "codex",
           runtimeMode: "approval-required",
           activeTurnId: null,
           lastError: null,
@@ -1535,7 +1847,7 @@ describe("ProviderCommandReactor", () => {
     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",
         }),
@@ -1651,6 +1963,7 @@ describe("ProviderCommandReactor", () => {
           threadId: ThreadId.make("thread-1"),
           status: "ready",
           providerName: "codex",
+          providerInstanceId: ProviderInstanceId.make("codex_work"),
           runtimeMode: "approval-required",
           activeTurnId: null,
           lastError: null,
@@ -1675,6 +1988,7 @@ describe("ProviderCommandReactor", () => {
     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 8a24c9538a0..998475f6118 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -4,7 +4,7 @@ import {
   EventId,
   type ModelSelection,
   type OrchestrationEvent,
-  ProviderKind,
+  ProviderDriverKind,
   type OrchestrationSession,
   ThreadId,
   type ProviderSession,
@@ -16,12 +16,10 @@ import { Cache, Cause, Duration, Effect, Equal, Layer, Option, Schema, Stream }
 import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
 
 import { resolveThreadWorkspaceCwd } from "../../checkpointing/Utils.ts";
-import { GitCore } from "../../git/Services/GitCore.ts";
-import { GitStatusBroadcaster } from "../../git/Services/GitStatusBroadcaster.ts";
 import { increment, orchestrationEventsProcessedTotal } from "../../observability/Metrics.ts";
 import { ProviderAdapterRequestError } from "../../provider/Errors.ts";
 import type { ProviderServiceError } from "../../provider/Errors.ts";
-import { TextGeneration } from "../../git/Services/TextGeneration.ts";
+import { TextGeneration } from "../../textGeneration/TextGeneration.ts";
 import { ProviderService } from "../../provider/Services/ProviderService.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
 import {
@@ -29,6 +27,8 @@ import {
   type ProviderCommandReactorShape,
 } from "../Services/ProviderCommandReactor.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
+import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
+import { GitWorkflowService } from "../../git/GitWorkflowService.ts";
 
 type ProviderIntentEvent = Extract<
   OrchestrationEvent,
@@ -77,6 +77,21 @@ const HANDLED_TURN_START_KEY_TTL = Duration.minutes(30);
 const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access";
 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) {
@@ -153,8 +168,8 @@ function buildGeneratedWorktreeBranchName(raw: string): string {
 const make = Effect.gen(function* () {
   const orchestrationEngine = yield* OrchestrationEngineService;
   const providerService = yield* ProviderService;
-  const git = yield* GitCore;
-  const gitStatusBroadcaster = yield* GitStatusBroadcaster;
+  const gitWorkflow = yield* GitWorkflowService;
+  const vcsStatusBroadcaster = yield* VcsStatusBroadcaster;
   const textGeneration = yield* TextGeneration;
   const serverSettingsService = yield* ServerSettingsService;
   const handledTurnStartKeys = yield* Cache.make<string, true>({
@@ -170,18 +185,7 @@ const make = Effect.gen(function* () {
       ),
     );
 
-  const threadModelSelections = new Map<ThreadId, ModelSelection>();
-  const getThreadModelSelection = (threadId: ThreadId) =>
-    Effect.sync(() => {
-      const modelSelection = threadModelSelections.get(threadId);
-      return modelSelection === undefined
-        ? Option.none<ModelSelection>()
-        : Option.some(modelSelection);
-    });
-  const setThreadModelSelection = (threadId: ThreadId, modelSelection: ModelSelection) =>
-    Effect.sync(() => {
-      threadModelSelections.set(threadId, modelSelection);
-    });
+  const threadModelSelections = new Map<string, ModelSelection>();
 
   const appendProviderFailureActivity = (input: {
     readonly threadId: ThreadId;
@@ -282,42 +286,108 @@ const make = Effect.gen(function* () {
     }
 
     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 = 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 (!Schema.is(ProviderDriverKind)(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 effectiveCwd = resolveThreadWorkspaceCwd({
       thread,
       projects: readModel.projects,
     });
 
-    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 } : {}),
@@ -325,46 +395,55 @@ 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 activeSession = yield* resolveActiveSession(threadId);
     const existingSessionThreadId =
       thread.session && thread.session.status !== "stopped" && activeSession ? thread.id : null;
     if (existingSessionThreadId) {
       const runtimeModeChanged = thread.runtimeMode !== thread.session?.runtimeMode;
       const cwdChanged = effectiveCwd !== activeSession?.cwd;
-      const sessionModelSwitch =
-        currentProvider === undefined
-          ? "in-session"
-          : (yield* providerService.getCapabilities(currentProvider)).sessionModelSwitch;
+      const sessionModelSwitch = (yield* providerService.getCapabilities(desiredInstanceId))
+        .sessionModelSwitch;
       const modelChanged =
         requestedModelSelection !== undefined &&
         requestedModelSelection.model !== activeSession?.model;
-      const shouldRestartForModelChange = modelChanged && sessionModelSwitch === "restart-session";
-      const previousModelSelection = Option.getOrUndefined(
-        yield* getThreadModelSelection(threadId),
-      );
+      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 &&
         !cwdChanged &&
+        !instanceChanged &&
         !shouldRestartForModelChange &&
         !shouldRestartForModelSelectionChange
       ) {
@@ -377,8 +456,10 @@ const make = Effect.gen(function* () {
       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,
@@ -386,6 +467,7 @@ const make = Effect.gen(function* () {
         desiredCwd: effectiveCwd,
         cwdChanged,
         modelChanged,
+        instanceChanged,
         shouldRestartForModelChange,
         shouldRestartForModelSelectionChange,
         hasResumeCursor: resumeCursor !== undefined,
@@ -430,7 +512,7 @@ const make = Effect.gen(function* () {
       input.modelSelection !== undefined ? { modelSelection: input.modelSelection } : {},
     );
     if (input.modelSelection !== undefined) {
-      yield* setThreadModelSelection(input.threadId, input.modelSelection);
+      threadModelSelections.set(input.threadId, input.modelSelection);
     }
     const normalizedInput = toNonEmptyProviderInput(input.messageText);
     const normalizedAttachments = input.attachments ?? [];
@@ -442,11 +524,16 @@ 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 ??
-      Option.getOrUndefined(yield* getThreadModelSelection(input.threadId)) ??
-      thread.modelSelection;
+      input.modelSelection ?? threadModelSelections.get(input.threadId) ?? thread.modelSelection;
     const modelForTurn =
       sessionModelSwitch === "unsupported" && input.modelSelection === undefined
         ? activeSession?.model !== undefined
@@ -500,7 +587,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"),
@@ -508,7 +595,7 @@ const make = Effect.gen(function* () {
         branch: renamed.branch,
         worktreePath: cwd,
       });
-      yield* gitStatusBroadcaster.refreshStatus(cwd).pipe(Effect.ignoreCause({ log: true }));
+      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", {
@@ -815,6 +902,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,
@@ -841,9 +931,7 @@ const make = Effect.gen(function* () {
         if (!thread?.session || thread.session.status === "stopped") {
           return;
         }
-        const cachedModelSelection = Option.getOrUndefined(
-          yield* getThreadModelSelection(event.payload.threadId),
-        );
+        const cachedModelSelection = threadModelSelections.get(event.payload.threadId);
         yield* ensureSessionForThread(
           event.payload.threadId,
           event.occurredAt,
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
index 6352428dac0..487d1a3aac7 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
@@ -2,10 +2,12 @@ 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,
@@ -29,7 +31,6 @@ import {
   ProviderService,
   type ProviderServiceShape,
 } from "../../provider/Services/ProviderService.ts";
-import { getProviderCapabilities } from "../../provider/Services/ProviderAdapter.ts";
 import { RepositoryIdentityResolverLive } from "../../project/Layers/RepositoryIdentityResolver.ts";
 import { OrchestrationEngineLive } from "./OrchestrationEngine.ts";
 import { OrchestrationProjectionPipelineLive } from "./ProjectionPipeline.ts";
@@ -98,7 +99,20 @@ function createProviderServiceHarness() {
     respondToUserInput: () => unsupported(),
     stopSession: () => unsupported(),
     listSessions: () => Effect.succeed([...runtimeSessions]),
-    getCapabilities: () => Effect.succeed(getProviderCapabilities("codex")),
+    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);
@@ -143,7 +157,7 @@ function createProviderServiceHarness() {
 async function waitForThread(
   engine: OrchestrationEngineShape,
   predicate: (thread: ProviderRuntimeTestThread) => boolean,
-  timeoutMs = 5000,
+  timeoutMs = 2000,
   threadId: ThreadId = asThreadId("thread-1"),
 ) {
   const deadline = Date.now() + timeoutMs;
@@ -233,7 +247,7 @@ describe("ProviderRuntimeIngestion", () => {
         title: "Provider Project",
         workspaceRoot,
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         createdAt,
@@ -247,7 +261,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,
@@ -275,7 +289,7 @@ describe("ProviderRuntimeIngestion", () => {
       }),
     );
     provider.setSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       status: "ready",
       runtimeMode: "approval-required",
       threadId: ThreadId.make("thread-1"),
@@ -298,7 +312,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -312,7 +326,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       threadId: asThreadId("thread-1"),
       createdAt: new Date().toISOString(),
       turnId: asTurnId("turn-1"),
@@ -340,7 +354,7 @@ describe("ProviderRuntimeIngestion", () => {
     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: {
@@ -359,7 +373,7 @@ 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(),
       payload: {
@@ -381,7 +395,7 @@ 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(),
       payload: {
@@ -402,7 +416,7 @@ 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(),
       payload: {
@@ -428,7 +442,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -444,14 +458,14 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "thread.started",
       eventId: asEventId("evt-thread-started-midturn-lifecycle"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
     });
     harness.emit({
       type: "session.started",
       eventId: asEventId("evt-session-started-midturn-lifecycle"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
     });
@@ -465,7 +479,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-midturn-lifecycle"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-midturn-lifecycle"),
@@ -503,7 +517,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-claude-placeholder"),
-      provider: "claudeAgent",
+      provider: ProviderDriverKind.make("claudeAgent"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-claude-placeholder"),
@@ -519,7 +533,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-claude-placeholder"),
-      provider: "claudeAgent",
+      provider: ProviderDriverKind.make("claudeAgent"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-claude-placeholder"),
@@ -536,31 +550,10 @@ describe("ProviderRuntimeIngestion", () => {
     const harness = await createHarness();
     const now = new Date().toISOString();
 
-    // Seed thread-2 so the auxiliary completion targets a real but different thread
-    harness.emit({
-      type: "turn.started",
-      eventId: asEventId("evt-turn-started-thread2-seed"),
-      provider: "codex",
-      createdAt: now,
-      threadId: asThreadId("thread-2"),
-      turnId: asTurnId("turn-thread2-seed"),
-    });
-
-    harness.emit({
-      type: "turn.completed",
-      eventId: asEventId("evt-turn-completed-thread2-seed"),
-      provider: "codex",
-      createdAt: now,
-      threadId: asThreadId("thread-2"),
-      turnId: asTurnId("turn-thread2-seed"),
-      status: "completed",
-    });
-
-    // Start primary turn on thread-1
     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"),
@@ -572,13 +565,12 @@ describe("ProviderRuntimeIngestion", () => {
         thread.session?.status === "running" && thread.session?.activeTurnId === "turn-primary",
     );
 
-    // Emit auxiliary turn.completed on thread-2 — should not affect thread-1
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-aux"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
-      threadId: asThreadId("thread-2"),
+      threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-aux"),
       status: "completed",
     });
@@ -592,7 +584,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-primary"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-primary"),
@@ -612,7 +604,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -628,7 +620,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-guarded-other"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-guarded-other"),
@@ -644,7 +636,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.completed",
       eventId: asEventId("evt-turn-completed-guarded-main"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-guarded-main"),
@@ -664,7 +656,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -677,7 +669,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"),
@@ -690,7 +682,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"),
@@ -721,7 +713,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -753,7 +745,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-tool-completed-with-data"),
-      provider: "cursor",
+      provider: ProviderDriverKind.make("cursor"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-tool-completed"),
@@ -809,7 +801,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-command-completed"),
-      provider: "cursor",
+      provider: ProviderDriverKind.make("cursor"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-command-completed"),
@@ -851,7 +843,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-read-path-completed"),
-      provider: "cursor",
+      provider: ProviderDriverKind.make("cursor"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-read-path"),
@@ -893,7 +885,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -932,7 +924,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Plan Source",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: "plan",
@@ -967,7 +959,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,
@@ -995,7 +987,7 @@ describe("ProviderRuntimeIngestion", () => {
       }),
     );
     harness.setProviderSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       status: "ready",
       runtimeMode: "approval-required",
       threadId: targetThreadId,
@@ -1007,7 +999,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,
@@ -1077,7 +1069,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-plan-target-started"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: targetThreadId,
       turnId: targetTurnId,
@@ -1119,7 +1111,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Plan Source",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: "plan",
@@ -1147,7 +1139,7 @@ describe("ProviderRuntimeIngestion", () => {
       }),
     );
     harness.setProviderSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       status: "running",
       runtimeMode: "approval-required",
       threadId: targetThreadId,
@@ -1159,7 +1151,7 @@ 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,
@@ -1176,7 +1168,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,
@@ -1229,7 +1221,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-stale-plan-implementation"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: targetThreadId,
       turnId: staleTurnId,
@@ -1272,7 +1264,7 @@ describe("ProviderRuntimeIngestion", () => {
         projectId: asProjectId("project-1"),
         title: "Plan Source",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: "plan",
@@ -1307,7 +1299,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,
@@ -1338,7 +1330,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,
@@ -1389,7 +1381,7 @@ describe("ProviderRuntimeIngestion", () => {
     );
 
     harness.setProviderSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       status: "running",
       runtimeMode: "approval-required",
       threadId: targetThreadId,
@@ -1401,7 +1393,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-unrelated-plan-implementation"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: targetThreadId,
       turnId: replayedTurnId,
@@ -1428,7 +1420,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -1443,7 +1435,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"),
@@ -1454,7 +1446,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"),
@@ -1465,7 +1457,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"),
@@ -1494,7 +1486,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -1508,7 +1500,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"),
@@ -1531,7 +1523,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"),
@@ -1555,15 +1547,14 @@ describe("ProviderRuntimeIngestion", () => {
     expect(message?.streaming).toBe(false);
   });
 
-  // TODO(upstream-sync): re-enable once assistant segmentation reconciled
-  it.skip("flushes and completes buffered assistant text when an approval request opens", async () => {
+  it("flushes and completes buffered assistant text when an approval request opens", async () => {
     const harness = await createHarness();
     const now = new Date().toISOString();
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-buffered-request-flush"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-request-flush"),
@@ -1578,7 +1569,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-buffered-request-flush"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-request-flush"),
@@ -1591,7 +1582,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "request.opened",
       eventId: asEventId("evt-request-opened-buffered-request-flush"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-request-flush"),
@@ -1616,15 +1607,14 @@ describe("ProviderRuntimeIngestion", () => {
     expect(message?.streaming).toBe(false);
   });
 
-  // TODO(upstream-sync): re-enable once assistant segmentation reconciled
-  it.skip("flushes and completes buffered assistant text when user input is requested", async () => {
+  it("flushes and completes buffered assistant text when user input is requested", async () => {
     const harness = await createHarness();
     const now = new Date().toISOString();
 
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-buffered-user-input-flush"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-user-input-flush"),
@@ -1639,7 +1629,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-buffered-user-input-flush"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-user-input-flush"),
@@ -1652,7 +1642,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "user-input.requested",
       eventId: asEventId("evt-user-input-requested-buffered-user-input-flush"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: now,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-user-input-flush"),
@@ -1692,7 +1682,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-buffered-whitespace-request"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: startedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-whitespace-request"),
@@ -1707,7 +1697,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-buffered-whitespace-request"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: startedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-whitespace-request"),
@@ -1720,7 +1710,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "request.opened",
       eventId: asEventId("evt-request-opened-buffered-whitespace-request"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: pausedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-whitespace-request"),
@@ -1744,8 +1734,7 @@ describe("ProviderRuntimeIngestion", () => {
     ).toBe(false);
   });
 
-  // TODO(upstream-sync): re-enable once assistant segmentation reconciled
-  it.skip("starts a new buffered assistant message segment after approval and completes without duplication", async () => {
+  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";
@@ -1755,7 +1744,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-buffered-request-append"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: startedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-request-append"),
@@ -1770,7 +1759,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-buffered-request-append-initial"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: startedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-request-append"),
@@ -1783,7 +1772,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "request.opened",
       eventId: asEventId("evt-request-opened-buffered-request-append"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: pausedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-request-append"),
@@ -1806,7 +1795,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-buffered-request-append-followup"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: resumedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-request-append"),
@@ -1819,7 +1808,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-message-completed-buffered-request-append"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: completedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-buffered-request-append"),
@@ -1877,8 +1866,7 @@ describe("ProviderRuntimeIngestion", () => {
     expect(assistantEvents[3]?.payload.text).toBe("");
   });
 
-  // TODO(upstream-sync): re-enable once assistant segmentation reconciled
-  it.skip("starts a new streaming assistant message segment after approval", async () => {
+  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";
@@ -1888,7 +1876,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "turn.started",
       eventId: asEventId("evt-turn-started-streaming-request-segment"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: startedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-streaming-request-segment"),
@@ -1903,7 +1891,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-streaming-request-segment-initial"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: startedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-streaming-request-segment"),
@@ -1916,7 +1904,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "request.opened",
       eventId: asEventId("evt-request-opened-streaming-request-segment"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: pausedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-streaming-request-segment"),
@@ -1939,7 +1927,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "content.delta",
       eventId: asEventId("evt-message-delta-streaming-request-segment-followup"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: resumedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-streaming-request-segment"),
@@ -1952,7 +1940,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "item.completed",
       eventId: asEventId("evt-message-completed-streaming-request-segment"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: completedAt,
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-streaming-request-segment"),
@@ -2010,7 +1998,7 @@ 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"),
@@ -2025,7 +2013,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"),
@@ -2052,7 +2040,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"),
@@ -2077,255 +2065,6 @@ describe("ProviderRuntimeIngestion", () => {
     expect(finalMessage?.streaming).toBe(false);
   });
 
-  it("completes streaming assistant messages even when read model lookup lags completion", async () => {
-    const harness = await createHarness({ serverSettings: { enableAssistantStreaming: true } });
-    const now = new Date().toISOString();
-
-    await Effect.runPromise(
-      harness.engine.dispatch({
-        type: "thread.turn.start",
-        commandId: CommandId.make("cmd-turn-start-streaming-lag"),
-        threadId: ThreadId.make("thread-1"),
-        message: {
-          messageId: asMessageId("message-streaming-lag"),
-          role: "user",
-          text: "stream with lag",
-          attachments: [],
-        },
-        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
-        runtimeMode: "approval-required",
-        createdAt: now,
-      }),
-    );
-    await Effect.runPromise(Effect.sleep("30 millis"));
-
-    harness.emit({
-      type: "turn.started",
-      eventId: asEventId("evt-turn-started-streaming-lag"),
-      provider: "codex",
-      createdAt: now,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-streaming-lag"),
-    });
-    await waitForThread(
-      harness.engine,
-      (thread) =>
-        thread.session?.status === "running" &&
-        thread.session?.activeTurnId === "turn-streaming-lag",
-    );
-
-    harness.emit({
-      type: "content.delta",
-      eventId: asEventId("evt-message-delta-streaming-lag"),
-      provider: "codex",
-      createdAt: now,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-streaming-lag"),
-      itemId: asItemId("item-streaming-lag"),
-      payload: {
-        streamKind: "assistant_text",
-        delta: "hello lagged",
-      },
-    });
-
-    const liveThread = await waitForThread(harness.engine, (entry) =>
-      entry.messages.some(
-        (message: ProviderRuntimeTestMessage) =>
-          message.id === "assistant:item-streaming-lag" &&
-          message.streaming &&
-          message.text === "hello lagged",
-      ),
-    );
-    const liveMessage = liveThread.messages.find(
-      (entry: ProviderRuntimeTestMessage) => entry.id === "assistant:item-streaming-lag",
-    );
-    expect(liveMessage?.streaming).toBe(true);
-
-    harness.emit({
-      type: "item.completed",
-      eventId: asEventId("evt-message-completed-streaming-lag"),
-      provider: "codex",
-      createdAt: now,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-streaming-lag"),
-      itemId: asItemId("item-streaming-lag"),
-      payload: {
-        itemType: "assistant_message",
-        status: "completed",
-      },
-    });
-
-    const finalThread = await waitForThread(harness.engine, (entry) =>
-      entry.messages.some(
-        (message: ProviderRuntimeTestMessage) =>
-          message.id === "assistant:item-streaming-lag" && !message.streaming,
-      ),
-    );
-    const finalMessage = finalThread.messages.find(
-      (entry: ProviderRuntimeTestMessage) => entry.id === "assistant:item-streaming-lag",
-    );
-    expect(finalMessage?.text).toBe("hello lagged");
-    expect(finalMessage?.streaming).toBe(false);
-  });
-
-  it.skip("splits streaming assistant text into separate messages around tool activity", async () => {
-    const harness = await createHarness({ serverSettings: { enableAssistantStreaming: true } });
-    const turnStartedAt = "2026-03-09T10:00:00.000Z";
-    const beforeToolAt = "2026-03-09T10:00:01.000Z";
-    const toolAt = "2026-03-09T10:00:02.000Z";
-    const afterToolAt = "2026-03-09T10:00:03.000Z";
-    const completedAt = "2026-03-09T10:00:04.000Z";
-
-    await Effect.runPromise(
-      harness.engine.dispatch({
-        type: "thread.turn.start",
-        commandId: CommandId.make("cmd-turn-start-interleaved-streaming"),
-        threadId: ThreadId.make("thread-1"),
-        message: {
-          messageId: asMessageId("message-interleaved-streaming"),
-          role: "user",
-          text: "show interleaving",
-          attachments: [],
-        },
-        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
-        runtimeMode: "approval-required",
-        createdAt: turnStartedAt,
-      }),
-    );
-    await Effect.runPromise(Effect.sleep("30 millis"));
-
-    harness.emit({
-      type: "turn.started",
-      eventId: asEventId("evt-turn-started-interleaved-streaming"),
-      provider: "codex",
-      createdAt: turnStartedAt,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-interleaved-streaming"),
-    });
-    await waitForThread(
-      harness.engine,
-      (thread) =>
-        thread.session?.status === "running" &&
-        thread.session?.activeTurnId === "turn-interleaved-streaming",
-    );
-
-    harness.emit({
-      type: "content.delta",
-      eventId: asEventId("evt-message-delta-before-tool"),
-      provider: "codex",
-      createdAt: beforeToolAt,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-interleaved-streaming"),
-      itemId: asItemId("item-interleaved-streaming"),
-      payload: {
-        streamKind: "assistant_text",
-        delta: "Before tool.",
-      },
-    });
-    await waitForThread(harness.engine, (thread) =>
-      thread.messages.some(
-        (message: ProviderRuntimeTestMessage) =>
-          message.id === "assistant:item-interleaved-streaming" &&
-          message.streaming &&
-          message.text === "Before tool.",
-      ),
-    );
-
-    harness.emit({
-      type: "item.updated",
-      eventId: asEventId("evt-tool-updated-interleaved-streaming"),
-      provider: "codex",
-      createdAt: toolAt,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-interleaved-streaming"),
-      itemId: asItemId("tool-interleaved-streaming"),
-      payload: {
-        itemType: "command_execution",
-        status: "in_progress",
-        title: "Run command",
-        detail: "pwd",
-      },
-    });
-    await waitForThread(
-      harness.engine,
-      (thread) =>
-        thread.messages.some(
-          (message: ProviderRuntimeTestMessage) =>
-            message.id === "assistant:item-interleaved-streaming" &&
-            !message.streaming &&
-            message.text === "Before tool.",
-        ) &&
-        thread.activities.some(
-          (activity: ProviderRuntimeTestActivity) =>
-            activity.id === "evt-tool-updated-interleaved-streaming" &&
-            activity.kind === "tool.updated",
-        ),
-    );
-
-    harness.emit({
-      type: "content.delta",
-      eventId: asEventId("evt-message-delta-after-tool"),
-      provider: "codex",
-      createdAt: afterToolAt,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-interleaved-streaming"),
-      itemId: asItemId("item-interleaved-streaming"),
-      payload: {
-        streamKind: "assistant_text",
-        delta: "After tool.",
-      },
-    });
-    await waitForThread(harness.engine, (thread) =>
-      thread.messages.some(
-        (message: ProviderRuntimeTestMessage) =>
-          message.id === "assistant:item-interleaved-streaming:segment:1" &&
-          message.streaming &&
-          message.text === "After tool.",
-      ),
-    );
-
-    harness.emit({
-      type: "item.completed",
-      eventId: asEventId("evt-message-completed-interleaved-streaming"),
-      provider: "codex",
-      createdAt: completedAt,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-interleaved-streaming"),
-      itemId: asItemId("item-interleaved-streaming"),
-      payload: {
-        itemType: "assistant_message",
-        status: "completed",
-      },
-    });
-
-    const thread = await waitForThread(harness.engine, (entry) =>
-      entry.messages.some(
-        (message: ProviderRuntimeTestMessage) =>
-          message.id === "assistant:item-interleaved-streaming:segment:1" && !message.streaming,
-      ),
-    );
-    expect(
-      thread.messages.map((message: ProviderRuntimeTestMessage) => ({
-        id: message.id,
-        text: message.text,
-        streaming: message.streaming,
-      })),
-    ).toEqual(
-      expect.arrayContaining([
-        {
-          id: "assistant:item-interleaved-streaming",
-          text: "Before tool.",
-          streaming: false,
-        },
-        {
-          id: "assistant:item-interleaved-streaming:segment:1",
-          text: "After tool.",
-          streaming: false,
-        },
-      ]),
-    );
-  });
-
   it("spills oversized buffered deltas and still finalizes full assistant text", async () => {
     const harness = await createHarness();
     const now = new Date().toISOString();
@@ -2334,7 +2073,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -2349,7 +2088,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"),
@@ -2362,7 +2101,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"),
@@ -2394,7 +2133,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -2410,7 +2149,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"),
@@ -2423,7 +2162,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"),
@@ -2436,7 +2175,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"),
@@ -2480,7 +2219,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -2493,7 +2232,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"),
@@ -2546,7 +2285,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -2573,7 +2312,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -2604,7 +2343,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -2614,7 +2353,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"),
@@ -2648,7 +2387,7 @@ describe("ProviderRuntimeIngestion", () => {
     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",
@@ -2656,14 +2395,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"),
@@ -2700,7 +2439,7 @@ describe("ProviderRuntimeIngestion", () => {
     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: {
@@ -2712,7 +2451,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"),
@@ -2728,7 +2467,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"),
@@ -2745,7 +2484,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"),
@@ -2758,7 +2497,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"),
@@ -2834,7 +2573,7 @@ describe("ProviderRuntimeIngestion", () => {
     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: {
@@ -2886,7 +2625,7 @@ describe("ProviderRuntimeIngestion", () => {
     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: {
@@ -2939,7 +2678,7 @@ describe("ProviderRuntimeIngestion", () => {
     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: {
@@ -2983,7 +2722,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -3013,7 +2752,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -3026,7 +2765,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"),
@@ -3040,7 +2779,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"),
@@ -3053,7 +2792,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"),
@@ -3116,7 +2855,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -3141,7 +2880,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "user-input.resolved",
       eventId: asEventId("evt-user-input-resolved"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-user-input"),
@@ -3189,7 +2928,7 @@ describe("ProviderRuntimeIngestion", () => {
     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"),
@@ -3203,7 +2942,7 @@ describe("ProviderRuntimeIngestion", () => {
     harness.emit({
       type: "runtime.error",
       eventId: asEventId("evt-runtime-error-after-failure"),
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       createdAt: new Date().toISOString(),
       threadId: asThreadId("thread-1"),
       turnId: asTurnId("turn-after-failure"),
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
index 7d98bbe0380..b7a4c195a5b 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
@@ -32,6 +32,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;
@@ -56,18 +62,6 @@ type RuntimeIngestionInput =
       event: TurnStartRequestedDomainEvent;
     };
 
-type AssistantSegmentState = {
-  baseMessageId: MessageId;
-  currentSegmentIndex: number | null;
-  nextSegmentIndex: number;
-};
-
-const assistantSegmentStateKey = (threadId: ThreadId, baseMessageId: MessageId) =>
-  `${threadId}:${baseMessageId}`;
-
-const assistantSegmentMessageId = (baseMessageId: MessageId, segmentIndex: number): MessageId =>
-  segmentIndex === 0 ? baseMessageId : MessageId.make(`${baseMessageId}:segment:${segmentIndex}`);
-
 function toTurnId(value: TurnId | string | undefined): TurnId | undefined {
   return value === undefined ? undefined : TurnId.make(String(value));
 }
@@ -95,6 +89,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}`;
 }
@@ -110,10 +108,15 @@ function proposedPlanIdFromEvent(event: ProviderRuntimeEvent, threadId: ThreadId
   return `plan:${threadId}:event:${event.eventId}`;
 }
 
-function asString(value: unknown): string | undefined {
-  return typeof value === "string" ? value : undefined;
+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 {
@@ -123,14 +126,6 @@ function buildContextWindowActivityPayload(
   return event.payload.usage;
 }
 
-function runtimePayloadRecord(event: ProviderRuntimeEvent): Record<string, unknown> | undefined {
-  const payload = (event as { payload?: unknown }).payload;
-  if (!payload || typeof payload !== "object") {
-    return undefined;
-  }
-  return payload as Record<string, unknown>;
-}
-
 function normalizeRuntimeTurnState(
   value: string | undefined,
 ): "completed" | "failed" | "interrupted" | "cancelled" {
@@ -145,38 +140,6 @@ function normalizeRuntimeTurnState(
   }
 }
 
-function runtimeTurnState(
-  event: ProviderRuntimeEvent,
-): "completed" | "failed" | "interrupted" | "cancelled" {
-  const payloadState = asString(runtimePayloadRecord(event)?.state);
-  return normalizeRuntimeTurnState(payloadState);
-}
-
-function runtimeTurnErrorMessage(event: ProviderRuntimeEvent): string | undefined {
-  const payloadErrorMessage = asString(runtimePayloadRecord(event)?.errorMessage);
-  return payloadErrorMessage;
-}
-
-function runtimeErrorMessageFromEvent(event: ProviderRuntimeEvent): string | undefined {
-  const payloadMessage = asString(runtimePayloadRecord(event)?.message);
-  return payloadMessage;
-}
-
-function runtimeErrorClassLabel(errorClass: string): string | undefined {
-  switch (errorClass) {
-    case "provider_error":
-      return "Provider error";
-    case "transport_error":
-      return "Connection error";
-    case "permission_error":
-      return "Permission error";
-    case "validation_error":
-      return "Validation error";
-    default:
-      return undefined;
-  }
-}
-
 function orchestrationSessionStatusFromRuntimeState(
   state: "starting" | "running" | "waiting" | "ready" | "interrupted" | "stopped" | "error",
 ): "starting" | "running" | "ready" | "interrupted" | "stopped" | "error" {
@@ -280,23 +243,15 @@ function runtimeEventToActivities(
     }
 
     case "runtime.error": {
-      const message = runtimeErrorMessageFromEvent(event);
-      if (!message) {
-        return [];
-      }
-      const errorClass = runtimePayloadRecord(event)?.class;
-      const errorClassLabel =
-        typeof errorClass === "string" ? runtimeErrorClassLabel(errorClass) : undefined;
       return [
         {
           id: event.eventId,
           createdAt: event.createdAt,
           tone: "error",
           kind: "runtime.error",
-          summary: errorClassLabel ?? "Runtime error",
+          summary: "Runtime error",
           payload: {
-            message: truncateDetail(message),
-            detail: truncateDetail(message),
+            message: truncateDetail(event.payload.message),
           },
           turnId: toTurnId(event.turnId) ?? null,
           ...maybeSequence,
@@ -565,7 +520,7 @@ function runtimeEventToActivities(
   return [];
 }
 
-const make = Effect.fn("make")(function* () {
+const make = Effect.gen(function* () {
   const orchestrationEngine = yield* OrchestrationEngineService;
   const providerService = yield* ProviderService;
   const projectionTurnRepository = yield* ProjectionTurnRepository;
@@ -577,19 +532,19 @@ const make = Effect.fn("make")(function* () {
     lookup: () => Effect.succeed(new Set<MessageId>()),
   });
 
-  const bufferedAssistantTextByMessageId = yield* Cache.make<
-    MessageId,
-    { text: string; createdAt: string }
-  >({
+  const bufferedAssistantTextByMessageId = yield* Cache.make<MessageId, string>({
     capacity: BUFFERED_MESSAGE_TEXT_BY_MESSAGE_ID_CACHE_CAPACITY,
     timeToLive: BUFFERED_MESSAGE_TEXT_BY_MESSAGE_ID_TTL,
-    lookup: () => Effect.succeed({ text: "", createdAt: "" }),
+    lookup: () => Effect.succeed(""),
   });
 
-  const assistantMessageSawDeltaByMessageId = yield* Cache.make<MessageId, boolean>({
-    capacity: BUFFERED_MESSAGE_TEXT_BY_MESSAGE_ID_CACHE_CAPACITY,
-    timeToLive: BUFFERED_MESSAGE_TEXT_BY_MESSAGE_ID_TTL,
-    lookup: () => Effect.succeed(false),
+  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 }>({
@@ -598,9 +553,6 @@ const make = Effect.fn("make")(function* () {
     lookup: () => Effect.succeed({ text: "", createdAt: "" }),
   });
 
-  const assistantSegmentStateByKey = new Map<string, AssistantSegmentState>();
-  const assistantSegmentKeysByTurnKey = new Map<string, Set<string>>();
-
   const isGitRepoForThread = Effect.fn("isGitRepoForThread")(function* (threadId: ThreadId) {
     const readModel = yield* orchestrationEngine.getReadModel();
     const thread = readModel.threads.find((entry) => entry.id === threadId);
@@ -662,39 +614,107 @@ const make = Effect.fn("make")(function* () {
   const clearAssistantMessageIdsForTurn = (threadId: ThreadId, turnId: TurnId) =>
     Cache.invalidate(turnMessageIdsByTurnKey, providerTurnKey(threadId, turnId));
 
-  const appendBufferedAssistantText = (messageId: MessageId, delta: string, createdAt: string) =>
+  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* (existing) {
-          const prev = Option.getOrUndefined(existing);
-          const nextText = `${prev?.text ?? ""}${delta}`;
-          const nextCreatedAt =
-            prev?.createdAt && prev.createdAt.length > 0 ? prev.createdAt : createdAt;
+      Effect.flatMap((existingText) =>
+        Effect.gen(function* () {
+          const nextText = Option.match(existingText, {
+            onNone: () => delta,
+            onSome: (text) => `${text}${delta}`,
+          });
           if (nextText.length <= MAX_BUFFERED_ASSISTANT_CHARS) {
-            yield* Cache.set(bufferedAssistantTextByMessageId, messageId, {
-              text: nextText,
-              createdAt: nextCreatedAt,
-            });
-            return { spillChunk: "", createdAt: nextCreatedAt };
+            yield* Cache.set(bufferedAssistantTextByMessageId, messageId, nextText);
+            return "";
           }
 
           // Safety valve: flush full buffered text as an assistant delta to cap memory.
           yield* Cache.invalidate(bufferedAssistantTextByMessageId, messageId);
-          return { spillChunk: nextText, createdAt: nextCreatedAt };
+          return nextText;
         }),
       ),
     );
 
   const takeBufferedAssistantText = (messageId: MessageId) =>
     Cache.getOption(bufferedAssistantTextByMessageId, messageId).pipe(
-      Effect.flatMap((existing) =>
+      Effect.flatMap((existingText) =>
         Cache.invalidate(bufferedAssistantTextByMessageId, messageId).pipe(
-          Effect.as(
-            Option.match(existing, {
-              onNone: () => ({ text: "", createdAt: "" }),
-              onSome: (entry) => entry,
-            }),
-          ),
+          Effect.as(Option.getOrElse(existingText, () => "")),
         ),
       ),
     );
@@ -702,18 +722,6 @@ const make = Effect.fn("make")(function* () {
   const clearBufferedAssistantText = (messageId: MessageId) =>
     Cache.invalidate(bufferedAssistantTextByMessageId, messageId);
 
-  const markAssistantMessageSawDelta = (messageId: MessageId) =>
-    Cache.set(assistantMessageSawDeltaByMessageId, messageId, true);
-
-  const takeAssistantMessageSawDelta = (messageId: MessageId) =>
-    Cache.getOption(assistantMessageSawDeltaByMessageId, messageId).pipe(
-      Effect.flatMap((existing) =>
-        Cache.invalidate(assistantMessageSawDeltaByMessageId, messageId).pipe(
-          Effect.as(Option.getOrElse(existing, () => false)),
-        ),
-      ),
-    );
-
   const appendBufferedProposedPlan = (planId: string, delta: string, createdAt: string) =>
     Cache.getOption(bufferedProposedPlanById, planId).pipe(
       Effect.flatMap((existingEntry) => {
@@ -738,169 +746,69 @@ const make = Effect.fn("make")(function* () {
   const clearBufferedProposedPlan = (planId: string) =>
     Cache.invalidate(bufferedProposedPlanById, planId);
 
-  const rememberAssistantSegmentKeyForTurn = (
-    threadId: ThreadId,
-    turnId: TurnId,
-    stateKey: string,
-  ): void => {
-    const turnKey = providerTurnKey(threadId, turnId);
-    const existing = assistantSegmentKeysByTurnKey.get(turnKey);
-    if (existing) {
-      existing.add(stateKey);
-      return;
-    }
-    assistantSegmentKeysByTurnKey.set(turnKey, new Set([stateKey]));
-  };
-
-  const clearAssistantSegmentsForTurn = (threadId: ThreadId, turnId: TurnId): void => {
-    const turnKey = providerTurnKey(threadId, turnId);
-    const stateKeys = assistantSegmentKeysByTurnKey.get(turnKey);
-    if (!stateKeys) {
-      return;
-    }
-    for (const stateKey of stateKeys) {
-      assistantSegmentStateByKey.delete(stateKey);
-    }
-    assistantSegmentKeysByTurnKey.delete(turnKey);
-  };
-
-  const clearAssistantSegment = (input: {
-    threadId: ThreadId;
-    baseMessageId: MessageId;
-    turnId?: TurnId;
-  }): void => {
-    const stateKey = assistantSegmentStateKey(input.threadId, input.baseMessageId);
-    assistantSegmentStateByKey.delete(stateKey);
-    if (!input.turnId) {
-      return;
-    }
-    const turnKey = providerTurnKey(input.threadId, input.turnId);
-    const stateKeys = assistantSegmentKeysByTurnKey.get(turnKey);
-    if (!stateKeys) {
-      return;
-    }
-    stateKeys.delete(stateKey);
-    if (stateKeys.size === 0) {
-      assistantSegmentKeysByTurnKey.delete(turnKey);
-    }
-  };
-
-  const clearAssistantSegmentsForThread = (threadId: ThreadId): void => {
-    const prefix = `${threadId}:`;
-    for (const key of assistantSegmentKeysByTurnKey.keys()) {
-      if (!key.startsWith(prefix)) {
-        continue;
-      }
-      const stateKeys = assistantSegmentKeysByTurnKey.get(key);
-      if (stateKeys) {
-        for (const stateKey of stateKeys) {
-          assistantSegmentStateByKey.delete(stateKey);
-        }
-      }
-      assistantSegmentKeysByTurnKey.delete(key);
-    }
-  };
+  const clearAssistantMessageState = (messageId: MessageId) =>
+    clearBufferedAssistantText(messageId);
 
-  const openAssistantSegment = (input: {
+  const flushBufferedAssistantMessage = (input: {
+    event: ProviderRuntimeEvent;
     threadId: ThreadId;
-    baseMessageId: MessageId;
+    messageId: MessageId;
     turnId?: TurnId;
-  }): MessageId => {
-    const stateKey = assistantSegmentStateKey(input.threadId, input.baseMessageId);
-    const existingState = assistantSegmentStateByKey.get(stateKey);
-    if (existingState && existingState.currentSegmentIndex !== null) {
-      if (input.turnId) {
-        rememberAssistantSegmentKeyForTurn(input.threadId, input.turnId, stateKey);
+    createdAt: string;
+    commandTag: string;
+  }) =>
+    Effect.gen(function* () {
+      const bufferedText = yield* takeBufferedAssistantText(input.messageId);
+      if (!hasRenderableAssistantText(bufferedText)) {
+        return false;
       }
-      return assistantSegmentMessageId(
-        existingState.baseMessageId,
-        existingState.currentSegmentIndex,
-      );
-    }
 
-    const segmentIndex = existingState?.nextSegmentIndex ?? 0;
-    assistantSegmentStateByKey.set(stateKey, {
-      baseMessageId: input.baseMessageId,
-      currentSegmentIndex: segmentIndex,
-      nextSegmentIndex: segmentIndex + 1,
+      yield* orchestrationEngine.dispatch({
+        type: "thread.message.assistant.delta",
+        commandId: providerCommandId(input.event, input.commandTag),
+        threadId: input.threadId,
+        messageId: input.messageId,
+        delta: bufferedText,
+        ...(input.turnId ? { turnId: input.turnId } : {}),
+        createdAt: input.createdAt,
+      });
+      return true;
     });
-    if (input.turnId) {
-      rememberAssistantSegmentKeyForTurn(input.threadId, input.turnId, stateKey);
-    }
-    return assistantSegmentMessageId(input.baseMessageId, segmentIndex);
-  };
 
-  const takeOpenAssistantSegmentMessageId = (input: {
-    threadId: ThreadId;
-    baseMessageId: MessageId;
-  }): { messageId: MessageId; hadAnySegment: boolean } | null => {
-    const stateKey = assistantSegmentStateKey(input.threadId, input.baseMessageId);
-    const state = assistantSegmentStateByKey.get(stateKey);
-    if (!state) {
-      return { messageId: input.baseMessageId, hadAnySegment: false };
-    }
-    if (state.currentSegmentIndex === null) {
-      return state.nextSegmentIndex > 0
-        ? null
-        : { messageId: input.baseMessageId, hadAnySegment: false };
-    }
-    return {
-      messageId: assistantSegmentMessageId(state.baseMessageId, state.currentSegmentIndex),
-      hadAnySegment: state.nextSegmentIndex > 0,
-    };
-  };
-
-  const closeOpenAssistantSegmentsForTurn = (input: {
+  const flushBufferedAssistantMessagesForTurn = (input: {
     event: ProviderRuntimeEvent;
     threadId: ThreadId;
     turnId: TurnId;
     createdAt: string;
-    existingAssistantMessageById: ReadonlyMap<
-      MessageId,
-      { readonly id: MessageId; readonly text: string; readonly streaming: boolean }
-    >;
+    commandTag: string;
   }) =>
     Effect.gen(function* () {
-      const turnKey = providerTurnKey(input.threadId, input.turnId);
-      const stateKeys = Array.from(assistantSegmentKeysByTurnKey.get(turnKey) ?? []);
+      const assistantMessageIds = yield* getAssistantMessageIdsForTurn(
+        input.threadId,
+        input.turnId,
+      );
+      const flushedMessageIds = new Set<MessageId>();
       yield* Effect.forEach(
-        stateKeys,
-        (stateKey) =>
-          Effect.gen(function* () {
-            const state = assistantSegmentStateByKey.get(stateKey);
-            if (!state || state.currentSegmentIndex === null) {
-              return;
-            }
-            const messageId = assistantSegmentMessageId(
-              state.baseMessageId,
-              state.currentSegmentIndex,
-            );
-            assistantSegmentStateByKey.set(stateKey, {
-              ...state,
-              currentSegmentIndex: null,
-            });
-            yield* finalizeAssistantMessage({
-              event: input.event,
-              threadId: input.threadId,
-              messageId,
-              turnId: input.turnId,
-              createdAt: input.createdAt,
-              commandTag: "assistant-complete-tool-boundary",
-              finalDeltaCommandTag: "assistant-delta-tool-boundary",
-              existingMessage: input.existingAssistantMessageById.get(messageId),
-            });
-          }),
+        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 clearAssistantMessageState = (messageId: MessageId) =>
-    Effect.all([
-      clearBufferedAssistantText(messageId),
-      Cache.invalidate(assistantMessageSawDeltaByMessageId, messageId),
-    ]).pipe(Effect.asVoid);
-
-  const finalizeAssistantMessage = Effect.fn("finalizeAssistantMessage")(function* (input: {
+  const finalizeAssistantMessage = (input: {
     event: ProviderRuntimeEvent;
     threadId: ThreadId;
     messageId: MessageId;
@@ -909,65 +817,86 @@ const make = Effect.fn("make")(function* () {
     commandTag: string;
     finalDeltaCommandTag: string;
     fallbackText?: string;
-    existingMessage?:
-      | {
-          readonly id: MessageId;
-          readonly text: string;
-          readonly streaming: boolean;
-        }
-      | undefined;
-  }) {
-    if (input.existingMessage && !input.existingMessage.streaming) {
-      yield* clearAssistantMessageState(input.messageId);
-      return;
-    }
-
-    const buffered = yield* takeBufferedAssistantText(input.messageId);
-    const bufferedText = buffered.text;
-
-    const sawDelta = yield* takeAssistantMessageSawDelta(input.messageId);
-    const text =
-      bufferedText.length > 0
-        ? bufferedText
-        : !sawDelta && (input.fallbackText?.trim().length ?? 0) > 0
-          ? input.fallbackText!
-          : "";
+    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 (text.length === 0 && !input.existingMessage) {
+      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);
-      return;
-    }
+    });
 
-    // Use the original timestamp from when the first delta arrived, not the
-    // finalization time.  This ensures assistant text messages are positioned
-    // chronologically relative to tool activities in the timeline instead of
-    // all appearing at the end when the turn completes.
-    const deltaCreatedAt = buffered.createdAt.length > 0 ? buffered.createdAt : input.createdAt;
+  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;
+      }
 
-    if (text.length > 0) {
-      yield* orchestrationEngine.dispatch({
-        type: "thread.message.assistant.delta",
-        commandId: providerCommandId(input.event, input.finalDeltaCommandTag),
+      yield* finalizeAssistantMessage({
+        event: input.event,
         threadId: input.threadId,
-        messageId: input.messageId,
-        delta: text,
-        ...(input.turnId ? { turnId: input.turnId } : {}),
-        createdAt: deltaCreatedAt,
+        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);
 
-    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 state = yield* getAssistantSegmentStateForTurn(input.threadId, input.turnId);
+      if (Option.isSome(state)) {
+        yield* setAssistantSegmentStateForTurn(input.threadId, input.turnId, {
+          ...state.value,
+          activeMessageId: null,
+        });
+      }
     });
-    yield* clearAssistantMessageState(input.messageId);
-  });
 
-  const upsertProposedPlan = Effect.fn("upsertProposedPlan")(function* (input: {
+  const upsertProposedPlan = (input: {
     event: ProviderRuntimeEvent;
     threadId: ThreadId;
     threadProposedPlans: ReadonlyArray<{
@@ -981,31 +910,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 = 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 finalizeBufferedProposedPlan = Effect.fn("finalizeBufferedProposedPlan")(function* (input: {
+  const finalizeBufferedProposedPlan = (input: {
     event: ProviderRuntimeEvent;
     threadId: ThreadId;
     threadProposedPlans: ReadonlyArray<{
@@ -1018,71 +948,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 messageIds = yield* Cache.getOption(turnMessageIdsByTurnKey, key);
-        if (Option.isSome(messageIds)) {
-          yield* Effect.forEach(messageIds.value, clearAssistantMessageState, {
-            concurrency: 1,
-          }).pipe(Effect.asVoid);
-        }
+  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;
+            }
 
-        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);
-    clearAssistantSegmentsForThread(threadId);
-  });
+            const messageIds = yield* Cache.getOption(turnMessageIdsByTurnKey, key);
+            if (Option.isSome(messageIds)) {
+              yield* Effect.forEach(messageIds.value, clearAssistantMessageState, {
+                concurrency: 1,
+              }).pipe(Effect.asVoid);
+            }
 
-  // Accumulate token usage from thread.token-usage.updated events so
-  // providers like Copilot and Amp (which emit usage separately from
-  // turn.completed) still get turn-level usage in the completion summary.
-  const pendingTokenUsageByThread = new Map<string, Record<string, unknown>>();
+            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",
@@ -1160,487 +1094,438 @@ const make = Effect.fn("make")(function* () {
     },
   );
 
-  const processRuntimeEvent = Effect.fn("processRuntimeEvent")(function* (
-    event: ProviderRuntimeEvent,
-  ) {
-    // Accumulate token usage events per thread
-    if (event.type === "thread.token-usage.updated") {
-      const payload = runtimePayloadRecord(event);
-      const raw = payload?.usage;
-      if (raw && typeof raw === "object") {
-        const prev = pendingTokenUsageByThread.get(event.threadId) ?? {};
-        const incoming = raw as Record<string, unknown>;
-        // Merge by summing numeric fields
-        const merged: Record<string, unknown> = { ...prev };
-        for (const [k, v] of Object.entries(incoming)) {
-          if (typeof v === "number" && typeof (prev[k] ?? 0) === "number") {
-            merged[k] = ((prev[k] as number) ?? 0) + v;
-          } else {
-            merged[k] = v;
-          }
-        }
-        pendingTokenUsageByThread.set(event.threadId, merged);
-      }
-    }
-
-    // Clear accumulated usage when a new turn starts
-    if (event.type === "turn.started") {
-      pendingTokenUsageByThread.delete(event.threadId);
-    }
-
-    const readModel = yield* orchestrationEngine.getReadModel();
-    const thread = readModel.threads.find((entry) => entry.id === event.threadId);
-    if (!thread) return;
-
-    const now = event.createdAt;
-    const eventTurnId = toTurnId(event.turnId);
-    const activeTurnId = thread.session?.activeTurnId ?? null;
-
-    const existingAssistantMessageById = new Map(
-      thread.messages.map((message) => [message.id, message] as const),
-    );
+  const processRuntimeEvent = (event: ProviderRuntimeEvent) =>
+    Effect.gen(function* () {
+      const readModel = yield* orchestrationEngine.getReadModel();
+      const thread = readModel.threads.find((entry) => entry.id === event.threadId);
+      if (!thread) return;
 
-    const assistantBaseMessageId =
-      event.type === "content.delta" ||
-      (event.type === "item.completed" && event.payload.itemType === "assistant_message")
-        ? MessageId.make(`assistant:${event.itemId ?? event.turnId ?? event.eventId}`)
-        : undefined;
+      const now = event.createdAt;
+      const eventTurnId = toTurnId(event.turnId);
+      const activeTurnId = thread.session?.activeTurnId ?? null;
 
-    const conflictsWithActiveTurn =
-      activeTurnId !== null && eventTurnId !== undefined && !sameId(activeTurnId, eventTurnId);
-    const missingTurnForActiveTurn = activeTurnId !== null && eventTurnId === undefined;
+      const conflictsWithActiveTurn =
+        activeTurnId !== null && eventTurnId !== undefined && !sameId(activeTurnId, eventTurnId);
+      const missingTurnForActiveTurn = activeTurnId !== null && eventTurnId === undefined;
 
-    const shouldApplyThreadLifecycle = (() => {
-      if (!STRICT_PROVIDER_LIFECYCLE_GUARD) {
-        return true;
-      }
-      switch (event.type) {
-        case "session.exited":
+      const shouldApplyThreadLifecycle = (() => {
+        if (!STRICT_PROVIDER_LIFECYCLE_GUARD) {
           return true;
-        case "session.started":
-        case "thread.started":
-          return true;
-        case "turn.started":
-          return !conflictsWithActiveTurn;
-        case "turn.completed":
-        case "turn.aborted":
-          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 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" ||
-      event.type === "turn.aborted"
-    ) {
-      const nextActiveTurnId =
-        event.type === "turn.started"
-          ? (eventTurnId ?? null)
-          : event.type === "turn.completed" ||
-              event.type === "turn.aborted" ||
-              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 runtimeTurnState(event) === "failed" ? "error" : "ready";
-          case "turn.aborted":
-            return "interrupted";
+            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" && runtimeTurnState(event) === "failed"
-            ? (runtimeTurnErrorMessage(event) ?? thread.session?.lastError ?? "Turn failed")
-            : status === "ready" || status === "interrupted"
+      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) {
-        const turnUsagePayload =
-          event.type === "turn.completed" ? runtimePayloadRecord(event) : undefined;
-        let turnUsage =
-          turnUsagePayload?.usage !== undefined &&
-          turnUsagePayload.usage !== null &&
-          typeof turnUsagePayload.usage === "object"
-            ? (turnUsagePayload.usage as Record<string, unknown>)
-            : undefined;
-
-        // Fall back to accumulated thread.token-usage.updated data
-        // for providers (Copilot, Amp) that emit usage separately.
-        if (!turnUsage && (event.type === "turn.completed" || event.type === "turn.aborted")) {
-          const pending = pendingTokenUsageByThread.get(event.threadId);
-          if (pending) {
-            turnUsage = pending;
+              : 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),
+                  },
+                ),
+              ),
+            );
           }
-        }
-        if (event.type === "turn.completed" || event.type === "turn.aborted") {
-          pendingTokenUsageByThread.delete(event.threadId);
-        }
-
-        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,
-          },
-          ...(turnUsage ? { turnUsage } : {}),
-          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 isToolLifecycleEvent =
-      eventTurnId !== undefined &&
-      ((event.type === "item.started" && isToolLifecycleItemType(event.payload.itemType)) ||
-        (event.type === "item.updated" && isToolLifecycleItemType(event.payload.itemType)) ||
-        (event.type === "item.completed" && isToolLifecycleItemType(event.payload.itemType)));
-    if (isToolLifecycleEvent) {
-      yield* closeOpenAssistantSegmentsForTurn({
-        event,
-        threadId: thread.id,
-        turnId: eventTurnId,
-        createdAt: now,
-        existingAssistantMessageById,
-      });
-    }
+      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);
-      }
-      yield* markAssistantMessageSawDelta(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 spillResult = yield* appendBufferedAssistantText(
-          assistantMessageId,
-          assistantDelta,
-          now,
+        const assistantDeliveryMode: AssistantDeliveryMode = yield* Effect.map(
+          serverSettingsService.getSettings,
+          (settings) => (settings.enableAssistantStreaming ? "streaming" : "buffered"),
         );
-        if (spillResult.spillChunk.length > 0) {
+        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: spillResult.spillChunk,
+            delta: assistantDelta,
             ...(turnId ? { turnId } : {}),
-            createdAt: spillResult.createdAt,
+            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 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: thread.messages.some(
+            (entry) =>
+              entry.role === "assistant" && entry.turnId === pauseForUserTurnId && entry.streaming,
+          ),
+          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 turnId = toTurnId(event.turnId);
+        const activeAssistantMessageId = turnId
+          ? yield* getActiveAssistantMessageIdForTurn(thread.id, turnId)
+          : Option.none<MessageId>();
+        const hasAssistantMessagesForTurn =
+          turnId !== undefined
+            ? thread.messages.some((entry) => entry.role === "assistant" && entry.turnId === turnId)
+            : false;
+        const assistantMessageId = Option.getOrElse(
+          activeAssistantMessageId,
+          () => assistantCompletion.messageId,
+        );
+        const existingAssistantMessage = thread.messages.find(
+          (entry) => entry.id === 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 turnId = toTurnId(event.turnId);
-      const assistantMessageId = assistantBaseMessageId
-        ? takeOpenAssistantSegmentMessageId({
+          yield* finalizeAssistantMessage({
+            event,
             threadId: thread.id,
-            baseMessageId: assistantBaseMessageId,
-          })?.messageId
-        : undefined;
-      if (!assistantMessageId) {
-        if (assistantBaseMessageId) {
-          clearAssistantSegment({
-            threadId: thread.id,
-            baseMessageId: assistantBaseMessageId,
+            messageId: assistantMessageId,
             ...(turnId ? { turnId } : {}),
+            createdAt: now,
+            commandTag: "assistant-complete",
+            finalDeltaCommandTag: "assistant-delta-finalize",
+            hasProjectedMessage: existingAssistantMessage !== undefined,
+            ...(assistantCompletion.fallbackText !== undefined && shouldApplyFallbackCompletionText
+              ? { fallbackText: assistantCompletion.fallbackText }
+              : {}),
           });
-        }
-      } else if (turnId) {
-        yield* rememberAssistantMessageId(thread.id, turnId, assistantMessageId);
-      }
 
-      if (assistantMessageId) {
-        // Avoid duplicating streamed text by checking the resolved
-        // segment message, not just the base message, for existing content.
-        const existingSegmentMessage =
-          existingAssistantMessageById.get(assistantMessageId) ??
-          thread.messages.find((entry) => entry.id === assistantMessageId);
-        const shouldApplyFallbackCompletionText =
-          !existingSegmentMessage || existingSegmentMessage.text.length === 0;
-
-        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 }
-            : {}),
-          existingMessage: existingAssistantMessageById.get(assistantMessageId),
-        });
-      }
+          if (turnId) {
+            yield* forgetAssistantMessageId(thread.id, turnId, assistantMessageId);
+          }
+        }
 
-      if (assistantBaseMessageId) {
-        clearAssistantSegment({
-          threadId: thread.id,
-          baseMessageId: assistantBaseMessageId,
-          ...(turnId ? { turnId } : {}),
-        });
-      }
-      if (turnId && assistantMessageId) {
-        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",
-              existingMessage: existingAssistantMessageById.get(assistantMessageId),
-            }),
-          { concurrency: 1 },
-        ).pipe(Effect.asVoid);
-        yield* clearAssistantMessageIdsForTurn(thread.id, turnId);
-        clearAssistantSegmentsForTurn(thread.id, turnId);
 
+      if (proposedPlanCompletion) {
         yield* finalizeBufferedProposedPlan({
           event,
           threadId: thread.id,
           threadProposedPlans: thread.proposedPlans,
-          planId: proposedPlanIdForTurn(thread.id, turnId),
-          turnId,
+          planId: proposedPlanCompletion.planId,
+          ...(proposedPlanCompletion.turnId ? { turnId: proposedPlanCompletion.turnId } : {}),
+          fallbackMarkdown: proposedPlanCompletion.planMarkdown,
           updatedAt: now,
         });
       }
-    }
 
-    if (event.type === "turn.aborted") {
-      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",
-              existingMessage: existingAssistantMessageById.get(assistantMessageId),
-            }),
-          { concurrency: 1 },
-        ).pipe(Effect.asVoid);
-        yield* clearAssistantMessageIdsForTurn(thread.id, turnId);
-        clearAssistantSegmentsForTurn(thread.id, turnId);
-      }
-    }
-
-    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 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: thread.messages.some(
+                  (entry) => entry.id === assistantMessageId,
+                ),
+              }),
+            { 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: thread.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);
+        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,
+            );
+            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: maxTurnCount + 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;
 
@@ -1664,21 +1549,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,
@@ -1688,5 +1574,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/commandInvariants.test.ts b/apps/server/src/orchestration/commandInvariants.test.ts
index a678bcea166..1e33a355d06 100644
--- a/apps/server/src/orchestration/commandInvariants.test.ts
+++ b/apps/server/src/orchestration/commandInvariants.test.ts
@@ -7,6 +7,7 @@ import {
   ThreadId,
   type OrchestrationCommand,
   type OrchestrationReadModel,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
 import { Effect } from "effect";
 
@@ -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/decider.delete.test.ts b/apps/server/src/orchestration/decider.delete.test.ts
index 2b323714932..548fcc0b68e 100644
--- a/apps/server/src/orchestration/decider.delete.test.ts
+++ b/apps/server/src/orchestration/decider.delete.test.ts
@@ -7,6 +7,7 @@ import {
   type OrchestrationCommand,
   type OrchestrationEvent,
   type OrchestrationReadModel,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
 import { Effect } from "effect";
 import { describe, expect, it } from "vitest";
@@ -63,7 +64,7 @@ async function seedReadModel(): Promise<OrchestrationReadModel> {
         projectId: asProjectId("project-delete"),
         title: "Thread Delete 1",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
@@ -93,7 +94,7 @@ async function seedReadModel(): Promise<OrchestrationReadModel> {
         projectId: asProjectId("project-delete"),
         title: "Thread Delete 2",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
diff --git a/apps/server/src/orchestration/decider.projectScripts.test.ts b/apps/server/src/orchestration/decider.projectScripts.test.ts
index a85e21c53f3..23566099196 100644
--- a/apps/server/src/orchestration/decider.projectScripts.test.ts
+++ b/apps/server/src/orchestration/decider.projectScripts.test.ts
@@ -5,7 +5,9 @@ import {
   MessageId,
   ProjectId,
   ThreadId,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
 import { describe, expect, it } from "vitest";
 import { Effect } from "effect";
 
@@ -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,14 +189,10 @@ 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",
     });
   });
@@ -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,
@@ -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/projector.test.ts b/apps/server/src/orchestration/projector.test.ts
index a61153bb529..b50bc2da598 100644
--- a/apps/server/src/orchestration/projector.test.ts
+++ b/apps/server/src/orchestration/projector.test.ts
@@ -2,6 +2,7 @@ import {
   CommandId,
   EventId,
   ProjectId,
+  ProviderDriverKind,
   ThreadId,
   type OrchestrationEvent,
 } from "@t3tools/contracts";
@@ -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",
@@ -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,
@@ -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",
@@ -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/redactEvent.ts b/apps/server/src/orchestration/redactEvent.ts
index e68e4e06a18..4625a1bfbc0 100644
--- a/apps/server/src/orchestration/redactEvent.ts
+++ b/apps/server/src/orchestration/redactEvent.ts
@@ -1,48 +1,18 @@
-import type {
-  OrchestrationEvent,
-  ProviderStartOptions,
-  ProviderStartOptionsRedacted,
-} from "@t3tools/contracts";
-
-/** Strip sensitive fields (username, password) from provider start options. */
-export function redactProviderStartOptions(
-  opts: ProviderStartOptions,
-): ProviderStartOptionsRedacted {
-  const redacted = { ...opts } as Record<string, unknown>;
-  if (opts.opencode) {
-    const { username: _u, password: _p, ...rest } = opts.opencode;
-    redacted.opencode = rest;
-  }
-  if (opts.kilo) {
-    const { username: _u, password: _p, ...rest } = opts.kilo;
-    redacted.kilo = rest;
-  }
-  return redacted as ProviderStartOptionsRedacted;
-}
+import type { OrchestrationEvent } from "@t3tools/contracts";
 
 /**
  * Redact sensitive fields from an orchestration event payload.
  *
- * Currently strips `username`/`password` from opencode and kilo provider
- * options on `thread.turn-start-requested` events. Use this at persistence
- * and client-broadcast boundaries so credentials never leave the server
- * runtime.
+ * Historically this stripped `username`/`password` from opencode and kilo
+ * provider options on `thread.turn-start-requested` events. The new
+ * orchestration contract no longer carries provider start options on
+ * orchestration events (model selection is communicated via `modelSelection`),
+ * so there is nothing to redact today. This function is kept as a stable
+ * boundary hook so future credential-bearing payloads can be scrubbed in
+ * a single place.
  */
 export function redactEventForBoundary<T extends Omit<OrchestrationEvent, "sequence">>(
   event: T,
 ): T {
-  if (event.type !== "thread.turn-start-requested") {
-    return event;
-  }
-  const payload = event.payload as Record<string, unknown>;
-  if (!payload.providerOptions) {
-    return event;
-  }
-  return {
-    ...event,
-    payload: {
-      ...payload,
-      providerOptions: redactProviderStartOptions(payload.providerOptions as ProviderStartOptions),
-    },
-  } as T;
+  return event;
 }
diff --git a/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts b/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
index 4255f770abe..7b0f718d9cb 100644
--- a/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
+++ b/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
@@ -1,4 +1,4 @@
-import { CommandId, EventId, ProjectId } from "@t3tools/contracts";
+import { CommandId, EventId, ProjectId, ProviderInstanceId } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
 import { Effect, Layer, Schema, Stream } from "effect";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
@@ -185,7 +185,7 @@ layer("OrchestrationEventStore", (it) => {
         return;
       }
       assert.deepStrictEqual(replayedEvent.payload.modelSelection, {
-        provider: "geminiCli",
+        instanceId: ProviderInstanceId.make("geminiCli"),
         model: "gemini-2.5-pro",
       });
     }),
diff --git a/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts b/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
index d42be699458..fc5f7a5c155 100644
--- a/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
+++ b/apps/server/src/persistence/Layers/ProjectionRepositories.test.ts
@@ -1,4 +1,4 @@
-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 SqlClient from "effect/unstable/sql/SqlClient";
@@ -28,7 +28,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: [],
@@ -52,7 +52,7 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
       assert.strictEqual(
         row.defaultModelSelection,
         JSON.stringify({
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5.4",
         }),
       );
@@ -61,7 +61,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 +77,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",
@@ -110,7 +110,7 @@ projectionRepositoriesLayer("Projection repositories", (it) => {
       assert.strictEqual(
         row.modelSelection,
         JSON.stringify({
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-6",
         }),
       );
@@ -119,7 +119,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/ProjectionThreadSessions.ts b/apps/server/src/persistence/Layers/ProjectionThreadSessions.ts
index 2499eba1967..80d241436f8 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreadSessions.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreadSessions.ts
@@ -23,6 +23,7 @@ const makeProjectionThreadSessionRepository = Effect.gen(function* () {
           thread_id,
           status,
           provider_name,
+          provider_instance_id,
           runtime_mode,
           active_turn_id,
           last_error,
@@ -32,6 +33,7 @@ const makeProjectionThreadSessionRepository = Effect.gen(function* () {
           ${row.threadId},
           ${row.status},
           ${row.providerName},
+          ${row.providerInstanceId},
           ${row.runtimeMode},
           ${row.activeTurnId},
           ${row.lastError},
@@ -41,6 +43,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 +60,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/ProviderSessionRuntime.ts b/apps/server/src/persistence/Layers/ProviderSessionRuntime.ts
index da3e8bce90a..778e0c6d2ee 100644
--- a/apps/server/src/persistence/Layers/ProviderSessionRuntime.ts
+++ b/apps/server/src/persistence/Layers/ProviderSessionRuntime.ts
@@ -46,6 +46,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 +57,7 @@ const makeProviderSessionRuntimeRepository = Effect.gen(function* () {
         VALUES (
           ${runtime.threadId},
           ${runtime.providerName},
+          ${runtime.providerInstanceId},
           ${runtime.adapterKey},
           ${runtime.runtimeMode},
           ${runtime.status},
@@ -66,6 +68,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 +86,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 +106,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/Migrations.ts b/apps/server/src/persistence/Migrations.ts
index d6158dd60d3..39773d760f7 100644
--- a/apps/server/src/persistence/Migrations.ts
+++ b/apps/server/src/persistence/Migrations.ts
@@ -35,11 +35,21 @@ 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";
+// Fork-only migrations (filenames re-use 020/021 prefixes; IDs 23/24 keep them
+// installed after the fork's first deployment).
 import Migration0023 from "./Migrations/020_NormalizeLegacyProviderKinds.ts";
 import Migration0024 from "./Migrations/021_RepairProjectionThreadProposedPlanImplementationColumns.ts";
+// Upstream migrations renumbered to sit after the fork's 23/24.
 import Migration0025 from "./Migrations/023_ProjectionThreadShellSummary.ts";
 import Migration0026 from "./Migrations/024_BackfillProjectionThreadShellSummary.ts";
 import Migration0027 from "./Migrations/025_CleanupInvalidProjectionPendingApprovals.ts";
+import Migration0028 from "./Migrations/026_CanonicalizeModelSelectionOptions.ts";
+import Migration0029 from "./Migrations/027_ProviderSessionRuntimeInstanceId.ts";
+import Migration0030 from "./Migrations/028_ProjectionThreadSessionInstanceId.ts";
+// Fork-only migration: backfills `provider_instance_id` for the four fork
+// drivers (amp/copilot/geminiCli/kilo) so existing rows resolve under the
+// new instance-based routing model introduced by upstream PR #2277.
+import Migration0031 from "./Migrations/029_BackfillForkProviderInstanceIds.ts";
 
 /**
  * Migration loader with all migrations defined inline.
@@ -79,6 +89,10 @@ export const migrationEntries = [
   [25, "ProjectionThreadShellSummary", Migration0025],
   [26, "BackfillProjectionThreadShellSummary", Migration0026],
   [27, "CleanupInvalidProjectionPendingApprovals", Migration0027],
+  [28, "CanonicalizeModelSelectionOptions", Migration0028],
+  [29, "ProviderSessionRuntimeInstanceId", Migration0029],
+  [30, "ProjectionThreadSessionInstanceId", Migration0030],
+  [31, "BackfillForkProviderInstanceIds", Migration0031],
 ] as const;
 
 export const makeMigrationLoader = (throughId?: number) =>
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..ffc42521c90
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/026_CanonicalizeModelSelectionOptions.test.ts
@@ -0,0 +1,450 @@
+import { assert, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+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..3233f5043af
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/027_028_ProviderInstanceIdColumns.test.ts
@@ -0,0 +1,74 @@
+import { assert, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+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_BackfillForkProviderInstanceIds.test.ts b/apps/server/src/persistence/Migrations/029_BackfillForkProviderInstanceIds.test.ts
new file mode 100644
index 00000000000..271459f4041
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/029_BackfillForkProviderInstanceIds.test.ts
@@ -0,0 +1,383 @@
+import { assert, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+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_BackfillForkProviderInstanceIds", (it) => {
+  it.effect(
+    "backfills provider_instance_id for fork drivers across both routing tables",
+    () =>
+      Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+
+        // Run all migrations up to (and including) 028 so the
+        // `provider_instance_id` column exists but is left NULL for
+        // historical rows.
+        yield* runMigrations({ toMigrationInclusive: 28 });
+
+        // Seed a project + thread for each fork driver to satisfy the
+        // foreign-key relationships used by the projection tables.
+        const forkKinds = ["amp", "copilot", "geminiCli", "kilo"] as const;
+        for (const kind of forkKinds) {
+          yield* sql`
+            INSERT INTO projection_projects (
+              project_id,
+              title,
+              workspace_root,
+              scripts_json,
+              created_at,
+              updated_at,
+              deleted_at,
+              default_model_selection_json
+            )
+            VALUES (
+              ${`project-${kind}`},
+              ${`Project ${kind}`},
+              ${`/tmp/project-${kind}`},
+              '[]',
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL,
+              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,
+              created_at,
+              updated_at,
+              archived_at,
+              deleted_at
+            )
+            VALUES (
+              ${`thread-${kind}`},
+              ${`project-${kind}`},
+              ${`Thread ${kind}`},
+              NULL,
+              'full-access',
+              'default',
+              NULL,
+              NULL,
+              NULL,
+              '2026-01-01T00:00:00.000Z',
+              '2026-01-01T00:00:00.000Z',
+              NULL,
+              NULL
+            )
+          `;
+
+          yield* sql`
+            INSERT INTO projection_thread_sessions (
+              thread_id,
+              status,
+              provider_name,
+              provider_session_id,
+              provider_thread_id,
+              active_turn_id,
+              last_error,
+              updated_at,
+              runtime_mode,
+              provider_instance_id
+            )
+            VALUES (
+              ${`thread-${kind}`},
+              'running',
+              ${kind},
+              NULL,
+              NULL,
+              NULL,
+              NULL,
+              '2026-01-01T00:00:00.000Z',
+              'full-access',
+              NULL
+            )
+          `;
+
+          yield* sql`
+            INSERT INTO provider_session_runtime (
+              thread_id,
+              provider_name,
+              adapter_key,
+              runtime_mode,
+              status,
+              last_seen_at,
+              resume_cursor_json,
+              runtime_payload_json,
+              provider_instance_id
+            )
+            VALUES (
+              ${`thread-${kind}`},
+              ${kind},
+              ${kind},
+              'full-access',
+              'running',
+              '2026-01-01T00:00:00.000Z',
+              NULL,
+              NULL,
+              NULL
+            )
+          `;
+        }
+
+        // Also seed a non-fork (upstream) driver row to verify the
+        // backfill leaves it untouched.
+        yield* sql`
+          INSERT INTO projection_projects (
+            project_id,
+            title,
+            workspace_root,
+            scripts_json,
+            created_at,
+            updated_at,
+            deleted_at,
+            default_model_selection_json
+          )
+          VALUES (
+            'project-claude',
+            'Project claude',
+            '/tmp/project-claude',
+            '[]',
+            '2026-01-01T00:00:00.000Z',
+            '2026-01-01T00:00:00.000Z',
+            NULL,
+            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,
+            created_at,
+            updated_at,
+            archived_at,
+            deleted_at
+          )
+          VALUES (
+            'thread-claude',
+            'project-claude',
+            'Thread claude',
+            NULL,
+            'full-access',
+            'default',
+            NULL,
+            NULL,
+            NULL,
+            '2026-01-01T00:00:00.000Z',
+            '2026-01-01T00:00:00.000Z',
+            NULL,
+            NULL
+          )
+        `;
+        yield* sql`
+          INSERT INTO projection_thread_sessions (
+            thread_id,
+            status,
+            provider_name,
+            provider_session_id,
+            provider_thread_id,
+            active_turn_id,
+            last_error,
+            updated_at,
+            runtime_mode,
+            provider_instance_id
+          )
+          VALUES (
+            'thread-claude',
+            'running',
+            'claudeAgent',
+            NULL,
+            NULL,
+            NULL,
+            NULL,
+            '2026-01-01T00:00:00.000Z',
+            'full-access',
+            NULL
+          )
+        `;
+        yield* sql`
+          INSERT INTO provider_session_runtime (
+            thread_id,
+            provider_name,
+            adapter_key,
+            runtime_mode,
+            status,
+            last_seen_at,
+            resume_cursor_json,
+            runtime_payload_json,
+            provider_instance_id
+          )
+          VALUES (
+            'thread-claude',
+            'claudeAgent',
+            'claudeAgent',
+            'full-access',
+            'running',
+            '2026-01-01T00:00:00.000Z',
+            NULL,
+            NULL,
+            NULL
+          )
+        `;
+
+        // Run migration 029.
+        yield* runMigrations({ toMigrationInclusive: 31 });
+
+        // Each fork row should now have its `provider_instance_id` set
+        // to the matching driver kind (the default instance id).
+        for (const kind of forkKinds) {
+          const sessionRows = yield* sql<{ readonly providerInstanceId: string }>`
+            SELECT provider_instance_id AS "providerInstanceId"
+            FROM projection_thread_sessions
+            WHERE thread_id = ${`thread-${kind}`}
+          `;
+          assert.deepStrictEqual(sessionRows, [{ providerInstanceId: kind }]);
+
+          const runtimeRows = yield* sql<{ readonly providerInstanceId: string }>`
+            SELECT provider_instance_id AS "providerInstanceId"
+            FROM provider_session_runtime
+            WHERE thread_id = ${`thread-${kind}`}
+          `;
+          assert.deepStrictEqual(runtimeRows, [{ providerInstanceId: kind }]);
+        }
+
+        // The upstream-driver row must be untouched (still NULL).
+        const claudeSession = yield* sql<{
+          readonly providerInstanceId: string | null;
+        }>`
+          SELECT provider_instance_id AS "providerInstanceId"
+          FROM projection_thread_sessions
+          WHERE thread_id = 'thread-claude'
+        `;
+        assert.deepStrictEqual(claudeSession, [{ providerInstanceId: null }]);
+
+        const claudeRuntime = yield* sql<{
+          readonly providerInstanceId: string | null;
+        }>`
+          SELECT provider_instance_id AS "providerInstanceId"
+          FROM provider_session_runtime
+          WHERE thread_id = 'thread-claude'
+        `;
+        assert.deepStrictEqual(claudeRuntime, [{ providerInstanceId: null }]);
+      }),
+  );
+
+  it.effect("is idempotent — re-running does not overwrite already-set ids", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+
+      yield* runMigrations({ toMigrationInclusive: 28 });
+
+      yield* sql`
+        INSERT INTO projection_projects (
+          project_id,
+          title,
+          workspace_root,
+          scripts_json,
+          created_at,
+          updated_at,
+          deleted_at,
+          default_model_selection_json
+        )
+        VALUES (
+          'project-amp-custom',
+          'Project amp custom',
+          '/tmp/project-amp-custom',
+          '[]',
+          '2026-01-01T00:00:00.000Z',
+          '2026-01-01T00:00:00.000Z',
+          NULL,
+          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,
+          created_at,
+          updated_at,
+          archived_at,
+          deleted_at
+        )
+        VALUES (
+          'thread-amp-custom',
+          'project-amp-custom',
+          'Thread amp custom',
+          NULL,
+          'full-access',
+          'default',
+          NULL,
+          NULL,
+          NULL,
+          '2026-01-01T00:00:00.000Z',
+          '2026-01-01T00:00:00.000Z',
+          NULL,
+          NULL
+        )
+      `;
+      // Pre-existing row already has a NON-DEFAULT instance id (e.g. user
+      // ran a future custom-instance migration before this one).
+      yield* sql`
+        INSERT INTO projection_thread_sessions (
+          thread_id,
+          status,
+          provider_name,
+          provider_session_id,
+          provider_thread_id,
+          active_turn_id,
+          last_error,
+          updated_at,
+          runtime_mode,
+          provider_instance_id
+        )
+        VALUES (
+          'thread-amp-custom',
+          'running',
+          'amp',
+          NULL,
+          NULL,
+          NULL,
+          NULL,
+          '2026-01-01T00:00:00.000Z',
+          'full-access',
+          'amp-custom'
+        )
+      `;
+
+      yield* runMigrations({ toMigrationInclusive: 31 });
+
+      const rows = yield* sql<{ readonly providerInstanceId: string }>`
+        SELECT provider_instance_id AS "providerInstanceId"
+        FROM projection_thread_sessions
+        WHERE thread_id = 'thread-amp-custom'
+      `;
+      assert.deepStrictEqual(rows, [{ providerInstanceId: "amp-custom" }]);
+    }),
+  );
+});
diff --git a/apps/server/src/persistence/Migrations/029_BackfillForkProviderInstanceIds.ts b/apps/server/src/persistence/Migrations/029_BackfillForkProviderInstanceIds.ts
new file mode 100644
index 00000000000..255eb2ddf7b
--- /dev/null
+++ b/apps/server/src/persistence/Migrations/029_BackfillForkProviderInstanceIds.ts
@@ -0,0 +1,45 @@
+/**
+ * Backfills `provider_instance_id` for fork-only provider drivers so existing
+ * rows resolve under the new instance-based routing model.
+ *
+ * Migrations 027/028 added the nullable `provider_instance_id` column to
+ * `provider_session_runtime` and `projection_thread_sessions` but
+ * intentionally left existing rows with `provider_instance_id IS NULL` —
+ * the upstream PR couldn't safely guess which configured instance owned
+ * each historical session for the four upstream drivers.
+ *
+ * For the fork's additional drivers (`amp`, `copilot`, `geminiCli`, `kilo`),
+ * the situation is simpler: every fork install runs at most one configured
+ * instance per driver kind, so we can safely backfill
+ * `provider_instance_id = '<driver_kind>'` (the default instance id used
+ * by built-in single-instance drivers — see `defaultInstanceIdForDriver`)
+ * for any row whose legacy `provider_name` matches one of the fork driver
+ * kinds and whose `provider_instance_id` is still null.
+ *
+ * Idempotent — re-running the migration is a no-op on already-backfilled
+ * rows because every UPDATE is guarded by `provider_instance_id IS NULL`.
+ */
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/unstable/sql/SqlClient";
+
+const FORK_DRIVER_KINDS = ["amp", "copilot", "geminiCli", "kilo"] as const;
+
+export default Effect.gen(function* () {
+  const sql = yield* SqlClient.SqlClient;
+
+  for (const driverKind of FORK_DRIVER_KINDS) {
+    yield* sql`
+      UPDATE provider_session_runtime
+      SET provider_instance_id = ${driverKind}
+      WHERE provider_name = ${driverKind}
+        AND provider_instance_id IS NULL
+    `;
+
+    yield* sql`
+      UPDATE projection_thread_sessions
+      SET provider_instance_id = ${driverKind}
+      WHERE provider_name = ${driverKind}
+        AND provider_instance_id IS NULL
+    `;
+  }
+});
diff --git a/apps/server/src/persistence/Services/ProjectionThreadSessions.ts b/apps/server/src/persistence/Services/ProjectionThreadSessions.ts
index fcd13f068da..5d2c3c87d1d 100644
--- a/apps/server/src/persistence/Services/ProjectionThreadSessions.ts
+++ b/apps/server/src/persistence/Services/ProjectionThreadSessions.ts
@@ -10,6 +10,7 @@ import {
   RuntimeMode,
   IsoDateTime,
   OrchestrationSessionStatus,
+  ProviderInstanceId,
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
@@ -22,6 +23,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/ProviderSessionRuntime.ts b/apps/server/src/persistence/Services/ProviderSessionRuntime.ts
index bf8e658e8a6..6ba15b32d96 100644
--- a/apps/server/src/persistence/Services/ProviderSessionRuntime.ts
+++ b/apps/server/src/persistence/Services/ProviderSessionRuntime.ts
@@ -7,6 +7,7 @@
  */
 import {
   IsoDateTime,
+  ProviderInstanceId,
   ProviderSessionRuntimeStatus,
   RuntimeMode,
   ThreadId,
@@ -19,6 +20,14 @@ 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/project/Layers/RepositoryIdentityResolver.ts b/apps/server/src/project/Layers/RepositoryIdentityResolver.ts
index 307123551bb..ae35c29ce21 100644
--- a/apps/server/src/project/Layers/RepositoryIdentityResolver.ts
+++ b/apps/server/src/project/Layers/RepositoryIdentityResolver.ts
@@ -1,6 +1,9 @@
 import type { RepositoryIdentity } from "@t3tools/contracts";
 import { Cache, Duration, Effect, Exit, Layer } from "effect";
-import { detectGitHostingProviderFromRemoteUrl, normalizeGitRemoteUrl } from "@t3tools/shared/git";
+import {
+  detectSourceControlProviderFromGitRemoteUrl,
+  normalizeGitRemoteUrl,
+} from "@t3tools/shared/git";
 
 import { runProcess } from "../../processRunner.ts";
 import {
@@ -45,7 +48,7 @@ function buildRepositoryIdentity(input: {
   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;
@@ -60,7 +63,7 @@ function buildRepositoryIdentity(input: {
     },
     rootPath: input.rootPath,
     ...(repositoryPath ? { displayName: repositoryPath } : {}),
-    ...(hostingProvider ? { provider: hostingProvider.kind } : {}),
+    ...(sourceControlProvider ? { provider: sourceControlProvider.kind } : {}),
     ...(owner ? { owner } : {}),
     ...(repositoryName ? { name: repositoryName } : {}),
   };
diff --git a/apps/server/src/provider/Drivers/AmpDriver.ts b/apps/server/src/provider/Drivers/AmpDriver.ts
new file mode 100644
index 00000000000..c0baed29d84
--- /dev/null
+++ b/apps/server/src/provider/Drivers/AmpDriver.ts
@@ -0,0 +1,133 @@
+/**
+ * AmpDriver — `ProviderDriver` for the Amp CLI runtime.
+ *
+ * Plain-value driver matching the Claude / OpenCode / Cursor pattern: the
+ * `create()` effect bundles a per-instance `snapshot`, `adapter`, and
+ * `textGeneration` triple, all scoped to the registry's lifecycle. Two
+ * concurrent Amp instances therefore have wholly independent
+ * `AmpServerManager` state and child processes.
+ *
+ * Amp's text-generation shape is the graceful "not supported" stub
+ * exported from `AmpTextGeneration` — the CLI doesn't currently expose a
+ * structured-output mode we can target.
+ *
+ * @module provider/Drivers/AmpDriver
+ */
+import {
+  GenericProviderSettings,
+  ProviderDriverKind,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { makeAmpTextGeneration } from "../../textGeneration/AmpTextGeneration.ts";
+import { ServerConfig } from "../../config.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { makeAmpAdapter } from "../Layers/AmpAdapter.ts";
+import { checkAmpStatus, makePendingAmpProvider } from "../Layers/AmpProvider.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";
+
+const DRIVER_KIND = ProviderDriverKind.make("amp");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+
+export type AmpDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | 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 AmpDriver: ProviderDriver<GenericProviderSettings, AmpDriverEnv> = {
+  driverKind: DRIVER_KIND,
+  metadata: {
+    displayName: "Amp",
+    supportsMultipleInstances: true,
+  },
+  configSchema: GenericProviderSettings,
+  defaultConfig: (): GenericProviderSettings => Schema.decodeSync(GenericProviderSettings)({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const path = yield* Path.Path;
+      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 GenericProviderSettings;
+
+      const adapter = yield* makeAmpAdapter(effectiveConfig, {
+        instanceId,
+        environment: processEnv,
+      });
+      const textGeneration = yield* makeAmpTextGeneration(effectiveConfig, processEnv);
+
+      const checkProvider = checkAmpStatus(effectiveConfig, processEnv).pipe(
+        Effect.map(stampIdentity),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+        Effect.provideService(Path.Path, path),
+      );
+
+      const snapshot = yield* makeManagedServerProvider<GenericProviderSettings>({
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) => stampIdentity(makePendingAmpProvider(settings)),
+        checkProvider,
+        refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: `Failed to build Amp 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/ClaudeDriver.ts b/apps/server/src/provider/Drivers/ClaudeDriver.ts
new file mode 100644
index 00000000000..311f4958651
--- /dev/null
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -0,0 +1,157 @@
+/**
+ * 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 { Cache, Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+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 { makeClaudeCapabilitiesCacheKey, makeClaudeContinuationGroupKey } from "./ClaudeHome.ts";
+
+const DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+const CAPABILITIES_PROBE_TTL = Duration.minutes(5);
+
+export type ClaudeDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | 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 => Schema.decodeSync(ClaudeSettings)({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const path = yield* Path.Path;
+      const eventLoggers = yield* ProviderEventLoggers;
+      const processEnv = mergeProviderInstanceEnvironment(environment);
+      const fallbackContinuationIdentity = defaultProviderContinuationIdentity({
+        driverKind: DRIVER_KIND,
+        instanceId,
+      });
+      const effectiveConfig = { ...config, enabled } satisfies ClaudeSettings;
+      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>({
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) => stampIdentity(makePendingClaudeProvider(settings)),
+        checkProvider,
+        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..84c9c331cc8
--- /dev/null
+++ b/apps/server/src/provider/Drivers/ClaudeHome.test.ts
@@ -0,0 +1,52 @@
+import * as NodeOS from "node:os";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Path } from "effect";
+
+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..c959096677e
--- /dev/null
+++ b/apps/server/src/provider/Drivers/ClaudeHome.ts
@@ -0,0 +1,43 @@
+import * as NodeOS from "node:os";
+
+import type { ClaudeSettings } from "@t3tools/contracts";
+import { Effect, Path } from "effect";
+
+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..26fffd5e213
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CodexDriver.ts
@@ -0,0 +1,171 @@
+/**
+ * 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 { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+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 {
+  codexContinuationIdentity,
+  materializeCodexShadowHome,
+  resolveCodexHomeLayout,
+} from "./CodexHomeLayout.ts";
+
+const DRIVER_KIND = ProviderDriverKind.make("codex");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+
+/**
+ * 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
+  | 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 => Schema.decodeSync(CodexSettings)({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      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;
+
+      // `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>({
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) => stampIdentity(makePendingCodexProvider(settings)),
+        checkProvider,
+        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..b84a43c4032
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
@@ -0,0 +1,209 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, FileSystem, Path, Schema } from "effect";
+
+import { CodexSettings } from "@t3tools/contracts";
+import {
+  CodexShadowHomeError,
+  materializeCodexShadowHome,
+  resolveCodexHomeLayout,
+} from "./CodexHomeLayout.ts";
+
+const decodeCodexSettings = (input: {
+  readonly enabled?: boolean;
+  readonly homePath?: string;
+  readonly shadowHomePath?: string;
+  readonly customModels?: readonly string[];
+  readonly binaryPath?: string;
+}): CodexSettings => Schema.decodeSync(CodexSettings)(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..0b6cd6b8918
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CodexHomeLayout.ts
@@ -0,0 +1,263 @@
+import * as NodeOS from "node:os";
+
+import { ProviderDriverKind, type CodexSettings } from "@t3tools/contracts";
+import { Effect, FileSystem, Path, Schema } from "effect";
+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;
+  }
+}
+
+type LinkState =
+  | {
+      readonly _tag: "Missing";
+    }
+  | {
+      readonly _tag: "NotSymlink";
+    }
+  | {
+      readonly _tag: "Symlink";
+      readonly target: string;
+    };
+
+function toShadowHomeError(cause: unknown): CodexShadowHomeError {
+  return Schema.is(CodexShadowHomeError)(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/CopilotDriver.ts b/apps/server/src/provider/Drivers/CopilotDriver.ts
new file mode 100644
index 00000000000..e6bb8b7bcbb
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CopilotDriver.ts
@@ -0,0 +1,140 @@
+/**
+ * CopilotDriver — `ProviderDriver` for the GitHub Copilot SDK runtime.
+ *
+ * Mirrors the Claude / OpenCode drivers: a plain value whose `create()`
+ * returns one `ProviderInstance` bundling `snapshot` / `adapter` /
+ * `textGeneration` closures captured over the per-instance
+ * `CopilotSettings`.
+ *
+ * Two driver instances therefore share zero mutable state — each owns its
+ * own session map, runtime event queue, approval resolvers, and turn
+ * tracker. Multiple GitHub accounts can be wired up by registering two
+ * driver instances against different `binaryPath`/`configDir` configs.
+ *
+ * Desktop-environment quirk: every spawn that ends up shelling out to the
+ * Copilot CLI flows through `withSanitizedCopilotDesktopEnv`, removing
+ * `ELECTRON_RUN_AS_NODE`, `ELECTRON_RENDERER_PORT`, and `CLAUDECODE` from
+ * the inherited environment so the spawned binary doesn't observe Electron
+ * host state. That helper lives in `copilotCliPath.ts` and is used inside
+ * the adapter, the snapshot probe, and the (optional) text-generation
+ * factory — there is no other place spawns happen for this driver.
+ *
+ * @module provider/Drivers/CopilotDriver
+ */
+import { ProviderDriverKind, type ServerProvider } from "@t3tools/contracts";
+import { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { ServerConfig } from "../../config.ts";
+import { makeCopilotTextGeneration } from "../../textGeneration/CopilotTextGeneration.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { makeCopilotAdapter } from "../Layers/CopilotAdapter.ts";
+import {
+  checkCopilotProviderStatus,
+  makePendingCopilotProvider,
+} from "../Layers/CopilotProvider.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 { CopilotSettings } from "./CopilotSettings.ts";
+
+const DRIVER_KIND = ProviderDriverKind.make("copilot");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+
+export type CopilotDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | 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 CopilotDriver: ProviderDriver<CopilotSettings, CopilotDriverEnv> = {
+  driverKind: DRIVER_KIND,
+  metadata: {
+    displayName: "GitHub Copilot",
+    supportsMultipleInstances: true,
+  },
+  configSchema: CopilotSettings,
+  defaultConfig: (): CopilotSettings => Schema.decodeSync(CopilotSettings)({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      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 CopilotSettings;
+
+      const adapter = yield* makeCopilotAdapter(effectiveConfig, {
+        instanceId,
+        ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
+      });
+      const textGeneration = yield* makeCopilotTextGeneration(effectiveConfig, processEnv);
+
+      const checkProvider = checkCopilotProviderStatus(effectiveConfig, processEnv).pipe(
+        Effect.map(stampIdentity),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+      );
+
+      const snapshot = yield* makeManagedServerProvider<CopilotSettings>({
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) => stampIdentity(makePendingCopilotProvider(settings)),
+        checkProvider,
+        refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: `Failed to build GitHub Copilot 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/CopilotSettings.ts b/apps/server/src/provider/Drivers/CopilotSettings.ts
new file mode 100644
index 00000000000..4c02e72c34b
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CopilotSettings.ts
@@ -0,0 +1,27 @@
+/**
+ * CopilotSettings — local typed config schema for the GitHub Copilot driver.
+ *
+ * This module owns the driver-side schema temporarily; the canonical home
+ * is `packages/contracts/src/settings.ts`, but until that lands the driver
+ * needs a typed `Schema.Codec<CopilotSettings, unknown>` for its
+ * `configSchema` SPI slot. The shape mirrors what we expect to publish in
+ * contracts (see `INTEGRATION_copilot.md`).
+ *
+ * Fields:
+ *   - `enabled`        — Master switch; default `true` (matches the legacy
+ *                         GenericProviderSettings entry).
+ *   - `binaryPath`     — Path to the Copilot CLI binary; empty defaults to
+ *                         the bundled CLI (see `copilotCliPath.ts`).
+ *   - `configDir`      — Optional override for the Copilot config dir.
+ *   - `customModels`   — User-added model slugs.
+ */
+import { Effect } from "effect";
+import * as Schema from "effect/Schema";
+
+export const CopilotSettings = Schema.Struct({
+  enabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+  binaryPath: Schema.Trim.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
+  configDir: Schema.Trim.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
+  customModels: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
+});
+export type CopilotSettings = typeof CopilotSettings.Type;
diff --git a/apps/server/src/provider/Drivers/CursorDriver.ts b/apps/server/src/provider/Drivers/CursorDriver.ts
new file mode 100644
index 00000000000..cd058800f29
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CursorDriver.ts
@@ -0,0 +1,148 @@
+/**
+ * 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 { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+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";
+
+const DRIVER_KIND = ProviderDriverKind.make("cursor");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+
+export type CursorDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | 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 => Schema.decodeSync(CursorSettings)({}),
+  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 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 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>({
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) => stampIdentity(buildInitialCursorProviderSnapshot(settings)),
+        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,
+            publishSnapshot,
+            stampIdentity,
+          }).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/GeminiCliDriver.ts b/apps/server/src/provider/Drivers/GeminiCliDriver.ts
new file mode 100644
index 00000000000..774883c14e7
--- /dev/null
+++ b/apps/server/src/provider/Drivers/GeminiCliDriver.ts
@@ -0,0 +1,138 @@
+/**
+ * GeminiCliDriver — `ProviderDriver` for the Google Gemini CLI runtime.
+ *
+ * Mirrors `ClaudeDriver` / `OpenCodeDriver`: a plain value whose `create()`
+ * returns one `ProviderInstance` bundling `snapshot` / `adapter` /
+ * `textGeneration` closures captured over the per-instance
+ * `GenericProviderSettings` payload (used as `GeminiCliSettings` until the
+ * settings schema is split out).
+ *
+ * Two instances with different `binaryPath`s spawn fully independent
+ * `gemini` subprocesses — there is no module-global session table or usage
+ * accumulator anymore.
+ *
+ * @module provider/Drivers/GeminiCliDriver
+ */
+import {
+  GenericProviderSettings,
+  ProviderDriverKind,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { ServerConfig } from "../../config.ts";
+import { makeGeminiCliTextGeneration } from "../../textGeneration/GeminiCliTextGeneration.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { makeGeminiCliAdapter } from "../Layers/GeminiCliAdapter.ts";
+import {
+  checkGeminiCliStatus,
+  makePendingGeminiCliProvider,
+} from "../Layers/GeminiCliProvider.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";
+
+const DRIVER_KIND = ProviderDriverKind.make("geminiCli");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+
+export type GeminiCliDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | 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 GeminiCliDriver: ProviderDriver<GenericProviderSettings, GeminiCliDriverEnv> = {
+  driverKind: DRIVER_KIND,
+  metadata: {
+    displayName: "Gemini CLI",
+    supportsMultipleInstances: true,
+  },
+  configSchema: GenericProviderSettings,
+  defaultConfig: (): GenericProviderSettings => Schema.decodeSync(GenericProviderSettings)({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const path = yield* Path.Path;
+      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 GenericProviderSettings;
+
+      const adapter = yield* makeGeminiCliAdapter(effectiveConfig, {
+        instanceId,
+        environment: processEnv,
+        ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
+      });
+      const textGeneration = yield* makeGeminiCliTextGeneration(effectiveConfig, processEnv);
+
+      const checkProvider = checkGeminiCliStatus(effectiveConfig, processEnv).pipe(
+        Effect.map(stampIdentity),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+        Effect.provideService(Path.Path, path),
+      );
+
+      const snapshot = yield* makeManagedServerProvider<GenericProviderSettings>({
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) => stampIdentity(makePendingGeminiCliProvider(settings)),
+        checkProvider,
+        refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: `Failed to build Gemini CLI 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/KiloDriver.ts b/apps/server/src/provider/Drivers/KiloDriver.ts
new file mode 100644
index 00000000000..dddba4ac28d
--- /dev/null
+++ b/apps/server/src/provider/Drivers/KiloDriver.ts
@@ -0,0 +1,133 @@
+/**
+ * KiloDriver — `ProviderDriver` for the Kilo Code runtime.
+ *
+ * Mirrors `OpenCodeDriver`: a plain value whose `create()` bundles
+ * `snapshot` / `adapter` / `textGeneration` closures over the per-instance
+ * `KiloSettings` (currently `GenericProviderSettings`). Every instance
+ * spins up its own `KiloServerManager`, so two Kilo instances never share
+ * server processes, sessions, or runtime event queues.
+ *
+ * @module provider/Drivers/KiloDriver
+ */
+import {
+  GenericProviderSettings,
+  ProviderDriverKind,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import { ServerConfig } from "../../config.ts";
+import { makeKiloTextGeneration } from "../../textGeneration/KiloTextGeneration.ts";
+import { ProviderDriverError } from "../Errors.ts";
+import { makeKiloAdapter } from "../Layers/KiloAdapter.ts";
+import {
+  checkKiloProviderStatus,
+  makePendingKiloProvider,
+  type KiloSettings,
+} from "../Layers/KiloProvider.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";
+
+const DRIVER_KIND = ProviderDriverKind.make("kilo");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+
+export type KiloDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | Path.Path
+  | 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 KiloDriver: ProviderDriver<KiloSettings, KiloDriverEnv> = {
+  driverKind: DRIVER_KIND,
+  metadata: {
+    displayName: "Kilo Code",
+    supportsMultipleInstances: true,
+  },
+  configSchema: GenericProviderSettings,
+  defaultConfig: (): KiloSettings => Schema.decodeSync(GenericProviderSettings)({}),
+  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 processEnv = mergeProviderInstanceEnvironment(environment);
+      const continuationIdentity = defaultProviderContinuationIdentity({
+        driverKind: DRIVER_KIND,
+        instanceId,
+      });
+      const stampIdentity = withInstanceIdentity({
+        instanceId,
+        displayName,
+        accentColor,
+        continuationGroupKey: continuationIdentity.continuationKey,
+      });
+      const effectiveConfig = { ...config, enabled } satisfies KiloSettings;
+
+      const adapter = yield* makeKiloAdapter(effectiveConfig, {
+        instanceId,
+        environment: processEnv,
+      });
+      const textGeneration = yield* makeKiloTextGeneration(effectiveConfig, processEnv);
+
+      const checkProvider = checkKiloProviderStatus(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<KiloSettings>({
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) => stampIdentity(makePendingKiloProvider(settings)),
+        checkProvider,
+        refreshInterval: SNAPSHOT_REFRESH_INTERVAL,
+      }).pipe(
+        Effect.mapError(
+          (cause) =>
+            new ProviderDriverError({
+              driver: DRIVER_KIND,
+              instanceId,
+              detail: `Failed to build Kilo 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..27f98a9830d
--- /dev/null
+++ b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
@@ -0,0 +1,135 @@
+/**
+ * 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 { Duration, Effect, FileSystem, Path, Schema, Stream } from "effect";
+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";
+
+const DRIVER_KIND = ProviderDriverKind.make("opencode");
+const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
+
+export type OpenCodeDriverEnv =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | 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 => Schema.decodeSync(OpenCodeSettings)({}),
+  create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
+    Effect.gen(function* () {
+      const openCodeRuntime = yield* OpenCodeRuntime;
+      const serverConfig = yield* ServerConfig;
+      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 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>({
+        getSettings: Effect.succeed(effectiveConfig),
+        streamSettings: Stream.never,
+        haveSettingsChanged: () => false,
+        initialSnapshot: (settings) => stampIdentity(makePendingOpenCodeProvider(settings)),
+        checkProvider,
+        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..2bd926512ed 100644
--- a/apps/server/src/provider/Errors.ts
+++ b/apps/server/src/provider/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/AmpAdapter.test.ts b/apps/server/src/provider/Layers/AmpAdapter.test.ts
index 447b04a449d..190b3b62960 100644
--- a/apps/server/src/provider/Layers/AmpAdapter.test.ts
+++ b/apps/server/src/provider/Layers/AmpAdapter.test.ts
@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import {
   ApprovalRequestId,
   EventId,
+  GenericProviderSettings,
   RuntimeItemId,
   ThreadId,
   TurnId,
@@ -13,12 +14,10 @@ import {
   type ProviderUserInputAnswers,
 } from "@t3tools/contracts";
 import { it, vi } from "@effect/vitest";
-import { Effect, Layer, Stream } from "effect";
+import { Effect, Schema, Stream } from "effect";
 
 import { AmpServerManager } from "../../ampServerManager.ts";
-import { AmpAdapter } from "../Services/AmpAdapter.ts";
-import { makeAmpAdapterLive } from "./AmpAdapter.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import { makeAmpAdapter } from "./AmpAdapter.ts";
 
 const asThreadId = (value: string): ThreadId => ThreadId.make(value);
 const asTurnId = (value: string): TurnId => TurnId.make(value);
@@ -105,81 +104,139 @@ class FakeAmpManager extends AmpServerManager {
   }
 }
 
-const manager = new FakeAmpManager();
-const layer = it.layer(
-  makeAmpAdapterLive({ manager }).pipe(Layer.provideMerge(ServerSettingsService.layerTest())),
+const enabledAmpSettings = Schema.decodeSync(GenericProviderSettings)({
+  enabled: true,
+  binaryPath: "",
+  configDir: "",
+  customModels: [],
+});
+
+const disabledAmpSettings = Schema.decodeSync(GenericProviderSettings)({
+  enabled: false,
+  binaryPath: "",
+  configDir: "",
+  customModels: [],
+});
+
+it.effect("AmpAdapter delegates session startup to the manager", () =>
+  Effect.gen(function* () {
+    const manager = new FakeAmpManager();
+    const adapter = yield* makeAmpAdapter(enabledAmpSettings, { manager });
+
+    const session = yield* adapter.startSession({
+      threadId: asThreadId("thread-1"),
+      runtimeMode: "full-access",
+    });
+
+    assert.equal(session.provider, "amp");
+    assert.equal(manager.startSessionImpl.mock.calls[0]?.[0], asThreadId("thread-1"));
+  }).pipe(Effect.scoped),
 );
 
-layer("AmpAdapterLive", (it) => {
-  it.effect("delegates session startup to the manager", () =>
-    Effect.gen(function* () {
-      manager.startSessionImpl.mockClear();
-      const adapter = yield* AmpAdapter;
+it.effect("AmpAdapter rejects startSession when provider is disabled", () =>
+  Effect.gen(function* () {
+    const manager = new FakeAmpManager();
+    const adapter = yield* makeAmpAdapter(disabledAmpSettings, { manager });
 
-      const session = yield* adapter.startSession({
-        threadId: asThreadId("thread-1"),
+    const result = yield* adapter
+      .startSession({
+        threadId: asThreadId("thread-disabled"),
         runtimeMode: "full-access",
-      });
+      })
+      .pipe(Effect.result);
+
+    assert.equal(result._tag, "Failure");
+    if (result._tag !== "Failure") {
+      return;
+    }
+    assert.equal(result.failure._tag, "ProviderAdapterValidationError");
+  }).pipe(Effect.scoped),
+);
 
-      assert.equal(session.provider, "amp");
-      assert.equal(manager.startSessionImpl.mock.calls[0]?.[0], asThreadId("thread-1"));
-    }),
-  );
+it.effect("AmpAdapter rejects attachments until AMP attachment wiring exists", () =>
+  Effect.gen(function* () {
+    const manager = new FakeAmpManager();
+    const adapter = yield* makeAmpAdapter(enabledAmpSettings, { manager });
+
+    const result = yield* adapter
+      .sendTurn({
+        threadId: asThreadId("thread-attachments"),
+        input: "hello",
+        attachments: [{ id: "attachment-1" }] as never,
+      })
+      .pipe(Effect.result);
+
+    assert.equal(result._tag, "Failure");
+    if (result._tag !== "Failure") {
+      return;
+    }
+    assert.equal(result.failure._tag, "ProviderAdapterValidationError");
+  }).pipe(Effect.scoped),
+);
 
-  it.effect("rejects attachments until AMP attachment wiring exists", () =>
-    Effect.gen(function* () {
-      const adapter = yield* AmpAdapter;
-      const result = yield* adapter
-        .sendTurn({
-          threadId: asThreadId("thread-attachments"),
-          input: "hello",
-          attachments: [{ id: "attachment-1" }] as never,
-        })
-        .pipe(Effect.result);
-
-      assert.equal(result._tag, "Failure");
-      if (result._tag !== "Failure") {
-        return;
-      }
-      assert.equal(result.failure._tag, "ProviderAdapterValidationError");
-    }),
-  );
+it.effect("AmpAdapter rejects rollbackThread with non-positive numTurns", () =>
+  Effect.gen(function* () {
+    const manager = new FakeAmpManager();
+    const adapter = yield* makeAmpAdapter(enabledAmpSettings, { manager });
+
+    const result = yield* adapter
+      .rollbackThread(asThreadId("thread-rollback"), 0)
+      .pipe(Effect.result);
+
+    assert.equal(result._tag, "Failure");
+    if (result._tag !== "Failure") {
+      return;
+    }
+    assert.equal(result.failure._tag, "ProviderAdapterValidationError");
+  }).pipe(Effect.scoped),
+);
 
-  it.effect("forwards manager runtime events through the adapter stream", () =>
-    Effect.gen(function* () {
-      const adapter = yield* AmpAdapter;
-
-      const event = {
-        type: "content.delta",
-        eventId: asEventId("evt-amp-delta"),
-        provider: "amp",
-        createdAt: new Date().toISOString(),
-        threadId: asThreadId("thread-1"),
-        turnId: asTurnId("turn-1"),
-        itemId: asItemId("item-1"),
-        payload: {
-          streamKind: "assistant_text",
-          delta: "hello",
-        },
-      } as unknown as ProviderRuntimeEvent;
-
-      // Emit first — the event is buffered in the unbounded queue via the
-      // listener that was registered during layer construction.
-      manager.emit("event", event);
-
-      // Now consume the head. Since the queue already has an item, this
-      // resolves immediately without a race condition.
-      const received = yield* Stream.runHead(adapter.streamEvents);
-
-      assert.equal(received._tag, "Some");
-      if (received._tag !== "Some") {
-        return;
-      }
-      assert.equal(received.value.type, "content.delta");
-      if (received.value.type !== "content.delta") {
-        return;
-      }
-      assert.equal(received.value.payload.delta, "hello");
-    }),
-  );
-});
+it.effect("AmpAdapter forwards interruptTurn calls to the manager", () =>
+  Effect.gen(function* () {
+    const manager = new FakeAmpManager();
+    const adapter = yield* makeAmpAdapter(enabledAmpSettings, { manager });
+
+    yield* adapter.interruptTurn(asThreadId("thread-interrupt"));
+
+    assert.equal(manager.interruptTurnImpl.mock.calls.length, 1);
+  }).pipe(Effect.scoped),
+);
+
+it.effect("AmpAdapter forwards manager runtime events through the adapter stream", () =>
+  Effect.gen(function* () {
+    const manager = new FakeAmpManager();
+    const adapter = yield* makeAmpAdapter(enabledAmpSettings, { manager });
+
+    const event = {
+      type: "content.delta",
+      eventId: asEventId("evt-amp-delta"),
+      provider: "amp",
+      createdAt: new Date().toISOString(),
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-1"),
+      itemId: asItemId("item-1"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: "hello",
+      },
+    } as unknown as ProviderRuntimeEvent;
+
+    // Emit first — the event is buffered in the unbounded queue via the
+    // listener that was registered during adapter construction.
+    manager.emit("event", event);
+
+    // Now consume the head. Since the queue already has an item, this
+    // resolves immediately without a race condition.
+    const received = yield* Stream.runHead(adapter.streamEvents);
+
+    assert.equal(received._tag, "Some");
+    if (received._tag !== "Some") {
+      return;
+    }
+    assert.equal(received.value.type, "content.delta");
+    if (received.value.type !== "content.delta") {
+      return;
+    }
+    assert.equal(received.value.payload.delta, "hello");
+  }).pipe(Effect.scoped),
+);
diff --git a/apps/server/src/provider/Layers/AmpAdapter.ts b/apps/server/src/provider/Layers/AmpAdapter.ts
index 5a703ccb8c5..4c46a4fda37 100644
--- a/apps/server/src/provider/Layers/AmpAdapter.ts
+++ b/apps/server/src/provider/Layers/AmpAdapter.ts
@@ -1,143 +1,150 @@
-import { type ProviderRuntimeEvent } from "@t3tools/contracts";
-import { Effect, Layer, Queue, Stream } from "effect";
+/**
+ * AmpAdapter — per-instance Amp provider adapter factory.
+ *
+ * Replaces the old `Layer.effect(AmpAdapter, ...)` singleton pattern with
+ * a `makeAmpAdapter(config, options)` factory that returns an
+ * `Effect<ProviderAdapterShape>` scoped to the caller. Each call yields an
+ * independent `AmpServerManager` whose lifetime is tied to the registry's
+ * scope; closing the scope tears down every spawned Amp child process.
+ *
+ * @module AmpAdapter
+ */
+import {
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type GenericProviderSettings,
+  type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { Effect, Queue, Stream } from "effect";
 
 import { AmpServerManager } from "../../ampServerManager.ts";
-import { ProviderAdapterProcessError, ProviderAdapterValidationError } from "../Errors.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
-import { AmpAdapter, type AmpAdapterShape } from "../Services/AmpAdapter.ts";
+import { ProviderAdapterValidationError, type ProviderAdapterError } from "../Errors.ts";
+import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
 import { makeErrorHelpers } from "./ProviderAdapterUtils.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
 
-const PROVIDER = "amp" as const;
-const { toRequestError } = makeErrorHelpers(PROVIDER);
+const PROVIDER = ProviderDriverKind.make("amp");
+const { toRequestError } = makeErrorHelpers("amp");
+
+export interface AmpAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {}
 
 export interface AmpAdapterLiveOptions {
+  readonly instanceId?: ProviderInstanceId;
+  readonly environment?: NodeJS.ProcessEnv;
+  /** Optional pre-built manager (used by tests). */
   readonly manager?: AmpServerManager;
+  /** Optional manager factory (used by tests). */
   readonly makeManager?: () => AmpServerManager;
 }
 
-export function makeAmpAdapterLive(options: AmpAdapterLiveOptions = {}) {
-  return Layer.effect(
-    AmpAdapter,
-    Effect.gen(function* () {
-      const manager = options.manager ?? options.makeManager?.() ?? new AmpServerManager();
-      const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
-      const serverSettingsService = yield* ServerSettingsService;
+export const makeAmpAdapter = Effect.fn("makeAmpAdapter")(function* (
+  ampSettings: GenericProviderSettings,
+  options?: AmpAdapterLiveOptions,
+) {
+  const manager = options?.manager ?? options?.makeManager?.() ?? new AmpServerManager();
+  const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
 
-      yield* Effect.acquireRelease(
-        Effect.sync(() => {
-          const listener = (event: ProviderRuntimeEvent) => {
-            Effect.runFork(Queue.offer(runtimeEventQueue, event).pipe(Effect.asVoid));
-          };
-          manager.on("event", listener);
-          return listener;
-        }),
-        (listener) =>
-          Effect.gen(function* () {
-            manager.off("event", listener);
-            manager.stopAll();
-            yield* Queue.shutdown(runtimeEventQueue);
-          }),
-      );
+  yield* Effect.acquireRelease(
+    Effect.sync(() => {
+      const listener = (event: ProviderRuntimeEvent) => {
+        Effect.runFork(Queue.offer(runtimeEventQueue, event).pipe(Effect.asVoid));
+      };
+      manager.on("event", listener);
+      return listener;
+    }),
+    (listener) =>
+      Effect.gen(function* () {
+        manager.off("event", listener);
+        manager.stopAll();
+        yield* Queue.shutdown(runtimeEventQueue);
+      }),
+  );
 
-      const service = {
-        provider: PROVIDER,
-        capabilities: getProviderCapabilities(PROVIDER),
-        startSession: (input) =>
-          Effect.gen(function* () {
-            const providerSettings = yield* serverSettingsService.getSettings.pipe(
-              Effect.map((s) => s.providers.amp),
-              Effect.mapError(
-                (error) =>
-                  new ProviderAdapterProcessError({
-                    provider: PROVIDER,
-                    threadId: input.threadId,
-                    detail: error.message,
-                    cause: error,
-                  }),
-              ),
-            );
-            if (!providerSettings.enabled) {
-              return yield* new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "startSession",
-                issue: "AMP provider is disabled in server settings.",
-              });
-            }
-            manager.binaryPath = providerSettings.binaryPath.trim() || undefined;
-            return yield* Effect.tryPromise({
-              try: () => manager.startSession(input),
-              catch: (cause) => toRequestError(input.threadId, "session/start", cause),
-            });
-          }),
-        sendTurn: (input) => {
-          if ((input.attachments?.length ?? 0) > 0) {
-            return Effect.fail(
-              new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "sendTurn",
-                issue: "AMP attachments are not supported yet.",
-              }),
-            );
-          }
+  // Configure the per-instance binary path on the manager up front. Settings
+  // are immutable for the lifetime of the instance — registries replace the
+  // instance whenever config changes.
+  manager.binaryPath = ampSettings.binaryPath.trim() || undefined;
 
-          return Effect.tryPromise({
-            try: () => manager.sendTurn(input),
-            catch: (cause) => toRequestError(input.threadId, "session/prompt", cause),
+  const service: AmpAdapterShape = {
+    provider: PROVIDER,
+    capabilities: { sessionModelSwitch: "in-session" },
+    startSession: (input) =>
+      Effect.gen(function* () {
+        if (!ampSettings.enabled) {
+          return yield* new ProviderAdapterValidationError({
+            provider: "amp",
+            operation: "startSession",
+            issue: "AMP provider is disabled in server settings.",
           });
-        },
-        interruptTurn: (threadId) =>
-          Effect.tryPromise({
-            try: () => manager.interruptTurn(threadId),
-            catch: (cause) => toRequestError(threadId, "session/interrupt", cause),
-          }),
-        respondToRequest: (threadId, requestId, decision) =>
-          Effect.tryPromise({
-            try: () => manager.respondToRequest(threadId, requestId, decision),
-            catch: (cause) => toRequestError(threadId, "permission/reply", cause),
-          }),
-        respondToUserInput: (threadId, requestId, answers) =>
-          Effect.tryPromise({
-            try: () => manager.respondToUserInput(threadId, requestId, answers),
-            catch: (cause) => toRequestError(threadId, "question/reply", cause),
+        }
+        return yield* Effect.tryPromise({
+          try: () => manager.startSession(input),
+          catch: (cause) => toRequestError(input.threadId, "session/start", cause),
+        });
+      }),
+    sendTurn: (input) => {
+      if ((input.attachments?.length ?? 0) > 0) {
+        return Effect.fail(
+          new ProviderAdapterValidationError({
+            provider: "amp",
+            operation: "sendTurn",
+            issue: "AMP attachments are not supported yet.",
           }),
-        stopSession: (threadId) =>
-          Effect.sync(() => {
-            manager.stopSession(threadId);
-          }),
-        listSessions: () => Effect.sync(() => manager.listSessions()),
-        hasSession: (threadId) => Effect.sync(() => manager.hasSession(threadId)),
-        readThread: (threadId) =>
-          Effect.tryPromise({
-            try: () => manager.readThread(threadId),
-            catch: (cause) => toRequestError(threadId, "session/messages", cause),
-          }),
-        rollbackThread: (threadId, numTurns) => {
-          if (!Number.isInteger(numTurns) || numTurns < 1) {
-            return Effect.fail(
-              new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "rollbackThread",
-                issue: "numTurns must be an integer >= 1.",
-              }),
-            );
-          }
+        );
+      }
 
-          return Effect.tryPromise({
-            try: () => manager.rollbackThread(threadId),
-            catch: (cause) => toRequestError(threadId, "session/revert", cause),
-          });
-        },
-        stopAll: () =>
-          Effect.sync(() => {
-            manager.stopAll();
+      return Effect.tryPromise({
+        try: () => manager.sendTurn(input),
+        catch: (cause) => toRequestError(input.threadId, "session/prompt", cause),
+      });
+    },
+    interruptTurn: (threadId) =>
+      Effect.tryPromise({
+        try: () => manager.interruptTurn(threadId),
+        catch: (cause) => toRequestError(threadId, "session/interrupt", cause),
+      }),
+    respondToRequest: (threadId, requestId, decision) =>
+      Effect.tryPromise({
+        try: () => manager.respondToRequest(threadId, requestId, decision),
+        catch: (cause) => toRequestError(threadId, "permission/reply", cause),
+      }),
+    respondToUserInput: (threadId, requestId, answers) =>
+      Effect.tryPromise({
+        try: () => manager.respondToUserInput(threadId, requestId, answers),
+        catch: (cause) => toRequestError(threadId, "question/reply", cause),
+      }),
+    stopSession: (threadId) =>
+      Effect.sync(() => {
+        manager.stopSession(threadId);
+      }),
+    listSessions: () => Effect.sync(() => manager.listSessions()),
+    hasSession: (threadId) => Effect.sync(() => manager.hasSession(threadId)),
+    readThread: (threadId) =>
+      Effect.tryPromise({
+        try: () => manager.readThread(threadId),
+        catch: (cause) => toRequestError(threadId, "session/messages", cause),
+      }),
+    rollbackThread: (threadId, numTurns) => {
+      if (!Number.isInteger(numTurns) || numTurns < 1) {
+        return Effect.fail(
+          new ProviderAdapterValidationError({
+            provider: "amp",
+            operation: "rollbackThread",
+            issue: "numTurns must be an integer >= 1.",
           }),
-        streamEvents: Stream.fromQueue(runtimeEventQueue),
-      } satisfies AmpAdapterShape;
+        );
+      }
 
-      return service;
-    }),
-  );
-}
+      return Effect.tryPromise({
+        try: () => manager.rollbackThread(threadId),
+        catch: (cause) => toRequestError(threadId, "session/revert", cause),
+      });
+    },
+    stopAll: () =>
+      Effect.sync(() => {
+        manager.stopAll();
+      }),
+    streamEvents: Stream.fromQueue(runtimeEventQueue),
+  };
 
-export const AmpAdapterLive = makeAmpAdapterLive();
+  return service;
+});
diff --git a/apps/server/src/provider/Layers/AmpProvider.ts b/apps/server/src/provider/Layers/AmpProvider.ts
new file mode 100644
index 00000000000..d6cf0ea94de
--- /dev/null
+++ b/apps/server/src/provider/Layers/AmpProvider.ts
@@ -0,0 +1,230 @@
+/**
+ * AmpProvider — snapshot probe for the Amp CLI provider.
+ *
+ * Mirrors the Claude / Cursor / OpenCode provider modules: exposes a
+ * `checkAmpStatus` effect that runs `amp --version` to detect the binary
+ * and a `makePendingAmpProvider` initial-snapshot helper for the loading
+ * state surfaced before the first probe completes.
+ *
+ * @module AmpProvider
+ */
+import {
+  ProviderDriverKind,
+  type GenericProviderSettings,
+  type ModelCapabilities,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
+import { Effect, Option, Path, Result } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { createModelCapabilities } from "@t3tools/shared/model";
+
+import {
+  buildSelectOptionDescriptor,
+  buildServerProvider,
+  DEFAULT_TIMEOUT_MS,
+  detailFromResult,
+  isCommandMissingCause,
+  parseGenericCliVersion,
+  providerModelsFromSettings,
+  spawnAndCollect,
+  type ServerProviderDraft,
+} from "../providerSnapshot.ts";
+
+const PROVIDER = ProviderDriverKind.make("amp");
+const AMP_PRESENTATION = {
+  displayName: "Amp",
+  showInteractionModeToggle: true,
+} as const;
+
+const DEFAULT_AMP_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
+
+const AMP_MODE_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [
+    buildSelectOptionDescriptor({
+      id: "mode",
+      label: "Mode",
+      options: [
+        { value: "smart", label: "Smart", isDefault: true },
+        { value: "rush", label: "Rush" },
+        { value: "deep", label: "Deep" },
+        { value: "free", label: "Free" },
+      ],
+    }),
+  ],
+});
+
+const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = [
+  {
+    slug: "smart",
+    name: "Amp Smart",
+    isCustom: false,
+    capabilities: AMP_MODE_CAPABILITIES,
+  },
+];
+
+function defaultBinaryPath(settings: GenericProviderSettings): string {
+  const trimmed = settings.binaryPath.trim();
+  return trimmed.length > 0 ? trimmed : "amp";
+}
+
+const runAmpCommand = Effect.fn("runAmpCommand")(function* (
+  ampSettings: GenericProviderSettings,
+  args: ReadonlyArray<string>,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const binaryPath = defaultBinaryPath(ampSettings);
+  const command = ChildProcess.make(binaryPath, [...args], {
+    env: environment,
+    shell: process.platform === "win32",
+  });
+  return yield* spawnAndCollect(binaryPath, command);
+});
+
+export const checkAmpStatus = Effect.fn("checkAmpStatus")(function* (
+  ampSettings: GenericProviderSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+): Effect.fn.Return<
+  ServerProviderDraft,
+  never,
+  ChildProcessSpawner.ChildProcessSpawner | Path.Path
+> {
+  const checkedAt = new Date().toISOString();
+  const allModels = providerModelsFromSettings(
+    BUILT_IN_MODELS,
+    PROVIDER,
+    ampSettings.customModels,
+    DEFAULT_AMP_MODEL_CAPABILITIES,
+  );
+
+  if (!ampSettings.enabled) {
+    return buildServerProvider({
+      presentation: AMP_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Amp is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  const versionProbe = yield* runAmpCommand(ampSettings, ["--version"], environment).pipe(
+    Effect.timeoutOption(DEFAULT_TIMEOUT_MS),
+    Effect.result,
+  );
+
+  if (Result.isFailure(versionProbe)) {
+    const error = versionProbe.failure;
+    return buildServerProvider({
+      presentation: AMP_PRESENTATION,
+      enabled: ampSettings.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: !isCommandMissingCause(error),
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: isCommandMissingCause(error)
+          ? "Amp CLI (`amp`) is not installed or not on PATH."
+          : `Failed to execute Amp CLI health check: ${error instanceof Error ? error.message : String(error)}.`,
+      },
+    });
+  }
+
+  if (Option.isNone(versionProbe.success)) {
+    return buildServerProvider({
+      presentation: AMP_PRESENTATION,
+      enabled: ampSettings.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: true,
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: "Amp CLI is installed but failed to run. Timed out while running command.",
+      },
+    });
+  }
+
+  const version = versionProbe.success.value;
+  const parsedVersion = parseGenericCliVersion(`${version.stdout}\n${version.stderr}`);
+  if (version.code !== 0) {
+    const detail = detailFromResult(version);
+    return buildServerProvider({
+      presentation: AMP_PRESENTATION,
+      enabled: ampSettings.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: true,
+        version: parsedVersion,
+        status: "error",
+        auth: { status: "unknown" },
+        message: detail
+          ? `Amp CLI is installed but failed to run. ${detail}`
+          : "Amp CLI is installed but failed to run.",
+      },
+    });
+  }
+
+  return buildServerProvider({
+    presentation: AMP_PRESENTATION,
+    enabled: ampSettings.enabled,
+    checkedAt,
+    models: allModels,
+    probe: {
+      installed: true,
+      version: parsedVersion,
+      status: "ready",
+      auth: { status: "unknown" },
+    },
+  });
+});
+
+export const makePendingAmpProvider = (ampSettings: GenericProviderSettings): ServerProviderDraft => {
+  const checkedAt = new Date().toISOString();
+  const models = providerModelsFromSettings(
+    BUILT_IN_MODELS,
+    PROVIDER,
+    ampSettings.customModels,
+    DEFAULT_AMP_MODEL_CAPABILITIES,
+  );
+
+  if (!ampSettings.enabled) {
+    return buildServerProvider({
+      presentation: AMP_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Amp is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  return buildServerProvider({
+    presentation: AMP_PRESENTATION,
+    enabled: true,
+    checkedAt,
+    models,
+    probe: {
+      installed: false,
+      version: null,
+      status: "warning",
+      auth: { status: "unknown" },
+      message: "Amp provider status has not been checked in this session yet.",
+    },
+  });
+};
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
index 2b53f21f1e2..4c71a016f32 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
@@ -12,20 +12,29 @@ 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 { Context, Effect, Fiber, Layer, Random, Schema, Stream } from "effect";
 
 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";
+
+// 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 +145,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 +157,7 @@ function makeHarness(config?: {
     | undefined;
 
   const adapterOptions: ClaudeAdapterLiveOptions = {
+    ...(config?.instanceId ? { instanceId: config.instanceId } : {}),
     createQuery: (input) => {
       createInput = input;
       return query;
@@ -163,7 +175,13 @@ function makeHarness(config?: {
   };
 
   return {
-    layer: makeClaudeAdapterLive(adapterOptions).pipe(
+    layer: Layer.effect(
+      ClaudeAdapter,
+      Effect.gen(function* () {
+        const claudeConfig = Schema.decodeSync(ClaudeSettings)(config?.claudeConfig ?? {});
+        return yield* makeClaudeAdapter(claudeConfig, adapterOptions);
+      }),
+    ).pipe(
       Layer.provideMerge(
         ServerConfig.layerTest(
           config?.cwd ?? "/tmp/claude-adapter-test",
@@ -209,11 +227,10 @@ async function readFirstPromptText(
   if (next.done) {
     return undefined;
   }
-  const msg = next.value.message as any;
-  if (typeof msg.content === "string") {
-    return msg.content;
+  if (typeof next.value.message.content === "string") {
+    return next.value.message.content;
   }
-  const content = msg.content[0];
+  const content = next.value.message.content[0];
   if (!content || content.type !== "text") {
     return undefined;
   }
@@ -247,7 +264,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");
@@ -257,7 +278,7 @@ describe("ClaudeAdapterLive", () => {
       assert.deepEqual(
         result.failure,
         new ProviderAdapterValidationError({
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "startSession",
           issue: "Expected provider 'claudeAgent' but received 'codex'.",
         }),
@@ -274,7 +295,7 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -294,7 +315,7 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -314,7 +335,7 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -333,14 +354,12 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-6",
-          options: {
-            effort: "max",
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+          [{ id: "effort", value: "max" }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -352,15 +371,37 @@ describe("ClaudeAdapterLive", () => {
     );
   });
 
+  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: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         modelSelection: {
-          provider: "claudeAgent",
+          instanceId: ProviderInstanceId.make("claudeAgent"),
           model: "claude-opus-4-7",
         },
         runtimeMode: "full-access",
@@ -380,14 +421,12 @@ describe("ClaudeAdapterLive", () => {
       const adapter = yield* ClaudeAdapter;
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
-        modelSelection: {
-          provider: "claudeAgent",
-          model: "claude-opus-4-7",
-          options: {
-            effort: "xhigh",
-          },
-        },
+        provider: ProviderDriverKind.make("claudeAgent"),
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-7",
+          [{ id: "effort", value: "xhigh" }],
+        ),
         runtimeMode: "full-access",
       });
 
@@ -405,14 +444,12 @@ describe("ClaudeAdapterLive", () => {
       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",
       });
 
@@ -430,14 +467,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",
       });
 
@@ -455,14 +490,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",
       });
 
@@ -482,14 +515,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",
       });
 
@@ -507,14 +538,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",
       });
 
@@ -534,14 +563,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",
       });
 
@@ -559,14 +586,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",
       });
 
@@ -574,13 +599,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();
@@ -625,7 +648,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -638,7 +661,7 @@ describe("ClaudeAdapterLive", () => {
       const createInput = harness.getLastCreateQueryInput();
       const promptMessage = yield* Effect.promise(() => readFirstPromptMessage(createInput));
       assert.isDefined(promptMessage);
-      assert.deepEqual((promptMessage?.message as any).content, [
+      assert.deepEqual(promptMessage?.message.content, [
         {
           type: "text",
           text: "What's in this image?",
@@ -670,9 +693,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",
@@ -847,7 +870,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1026,7 +1049,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1117,7 +1140,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1193,7 +1216,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1259,7 +1282,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1310,13 +1333,19 @@ describe("ClaudeAdapterLive", () => {
 
   it.effect("closes the previous session before replacing an existing thread session", () => {
     const queries: FakeClaudeQuery[] = [];
-    const layer = makeClaudeAdapterLive({
-      createQuery: () => {
-        const query = new FakeClaudeQuery();
-        queries.push(query);
-        return query;
-      },
-    }).pipe(
+    const layer = Layer.effect(
+      ClaudeAdapter,
+      Effect.gen(function* () {
+        const claudeConfig = Schema.decodeSync(ClaudeSettings)({});
+        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),
@@ -1332,13 +1361,13 @@ describe("ClaudeAdapterLive", () => {
 
       const firstSession = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
       const secondSession = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
         resumeCursor: firstSession.resumeCursor,
       });
@@ -1387,21 +1416,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 = Schema.decodeSync(ClaudeSettings)({});
+        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),
@@ -1419,7 +1454,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1456,7 +1491,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1503,7 +1538,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1557,7 +1592,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1624,7 +1659,7 @@ describe("ClaudeAdapterLive", () => {
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -1689,7 +1724,7 @@ describe("ClaudeAdapterLive", () => {
 
         yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           runtimeMode: "full-access",
         });
 
@@ -1770,7 +1805,7 @@ describe("ClaudeAdapterLive", () => {
 
         const session = yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           runtimeMode: "full-access",
         });
 
@@ -1861,7 +1896,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2027,7 +2062,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2096,7 +2131,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2318,7 +2353,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);
@@ -2391,7 +2426,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -2500,7 +2535,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -2573,7 +2608,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",
@@ -2601,6 +2636,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* () {
@@ -2608,7 +2733,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2642,7 +2767,7 @@ describe("ClaudeAdapterLive", () => {
 
         const session = yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           runtimeMode: "full-access",
         });
 
@@ -2722,14 +2847,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: [],
@@ -2742,6 +2867,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",
     () => {
@@ -2749,13 +2902,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",
         });
@@ -2788,27 +2941,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: [],
@@ -2828,7 +2979,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
       yield* adapter.sendTurn({
@@ -2858,7 +3009,7 @@ describe("ClaudeAdapterLive", () => {
 
         const session = yield* adapter.startSession({
           threadId: THREAD_ID,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           runtimeMode,
         });
 
@@ -2910,7 +3061,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
       yield* adapter.sendTurn({
@@ -2933,7 +3084,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -2999,7 +3150,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
 
@@ -3071,7 +3222,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",
       });
 
@@ -3145,6 +3296,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"),
       });
@@ -3179,6 +3333,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),
@@ -3194,7 +3376,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",
       });
 
@@ -3260,7 +3442,7 @@ describe("ClaudeAdapterLive", () => {
 
       const session = yield* adapter.startSession({
         threadId: THREAD_ID,
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "approval-required",
       });
 
@@ -3347,7 +3529,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 3b32646ec40..556504d6cf4 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.ts
@@ -17,88 +17,18 @@ import {
   type SDKResultMessage,
   type SettingSource,
   type SDKUserMessage,
+  type ModelUsage,
 } from "@anthropic-ai/claude-agent-sdk";
-
-/** Inline types from SDK — not yet re-exported from the public entry. */
-type ModelUsage = {
-  inputTokens: number;
-  outputTokens: number;
-  cacheReadInputTokens: number;
-  cacheCreationInputTokens: number;
-  webSearchRequests: number;
-  contextWindow: number;
-};
-type NonNullableUsage = Record<string, unknown>;
-
-/** Inline type aliases for SDK message subtypes that aren't re-exported publicly. */
-type SDKHookStartedMessage = {
-  type: "system";
-  subtype: "hook_started";
-  hook_id: string;
-  hook_name: string;
-  hook_event: string;
-  [k: string]: unknown;
-};
-type SDKHookProgressMessage = {
-  type: "system";
-  subtype: "hook_progress";
-  hook_id: string;
-  output: string;
-  stdout: string;
-  stderr: string;
-  [k: string]: unknown;
-};
-type SDKHookResponseMessage = {
-  type: "system";
-  subtype: "hook_response";
-  hook_id: string;
-  outcome: "error" | "cancelled" | "success";
-  output: string;
-  stdout: string;
-  stderr: string;
-  exit_code?: number;
-  [k: string]: unknown;
-};
-type SDKTaskStartedMessage = {
-  type: "system";
-  subtype: "task_started";
-  task_id: string;
-  description: string;
-  task_type?: string;
-  [k: string]: unknown;
-};
-type SDKTaskProgressMessage = {
-  type: "system";
-  subtype: "task_progress";
-  task_id: string;
-  description: string;
-  summary?: string;
-  usage?: Record<string, unknown>;
-  last_tool_name?: string;
-  [k: string]: unknown;
-};
-type SDKTaskNotificationMessage = {
-  type: "system";
-  subtype: "task_notification";
-  task_id: string;
-  status: "completed" | "failed" | "stopped";
-  summary?: string;
-  usage?: Record<string, unknown>;
-  [k: string]: unknown;
-};
-type SDKToolUseSummaryMessage = {
-  type: "tool_use_summary";
-  summary: string;
-  preceding_tool_use_ids?: readonly string[];
-  [k: string]: unknown;
-};
 import { parseCliArgs } from "@t3tools/shared/cliArgs";
 import {
   ApprovalRequestId,
   type CanonicalItemType,
   type CanonicalRequestType,
+  type ClaudeSettings,
   EventId,
   type ProviderApprovalDecision,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ProviderItemId,
   type ProviderRuntimeEvent,
   type ProviderRuntimeTurnStatus,
@@ -113,9 +43,14 @@ import {
   ThreadId,
   TurnId,
   type UserInputQuestion,
-  type ClaudeAgentEffort,
 } from "@t3tools/contracts";
-import { applyClaudePromptEffortPrefix, resolveEffort, trimOrNull } from "@t3tools/shared/model";
+import {
+  applyClaudePromptEffortPrefix,
+  getModelSelectionBooleanOptionValue,
+  getModelSelectionStringOptionValue,
+  getProviderOptionDescriptors,
+  resolvePromptInjectedEffort,
+} from "@t3tools/shared/model";
 import {
   Cause,
   DateTime,
@@ -124,7 +59,7 @@ import {
   Exit,
   FileSystem,
   Fiber,
-  Layer,
+  Path,
   Queue,
   Random,
   Ref,
@@ -133,8 +68,13 @@ import {
 
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { getClaudeModelCapabilities, resolveClaudeApiModelId } from "./ClaudeProvider.ts";
+import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
+import {
+  getClaudeModelCapabilities,
+  normalizeClaudeCliEffort,
+  resolveClaudeApiModelId,
+  resolveClaudeEffort,
+} from "./ClaudeProvider.ts";
 import {
   ProviderAdapterProcessError,
   ProviderAdapterRequestError,
@@ -143,11 +83,10 @@ import {
   ProviderAdapterValidationError,
   type ProviderAdapterError,
 } from "../Errors.ts";
-import { ClaudeAdapter, type ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
+import { type ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
 import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
 
-const PROVIDER = "claudeAgent" as const;
+const PROVIDER = ProviderDriverKind.make("claudeAgent");
 type ClaudeTextStreamKind = Extract<RuntimeContentStreamKind, "assistant_text" | "reasoning_text">;
 type ClaudeToolResultStreamKind = Extract<
   RuntimeContentStreamKind,
@@ -246,6 +185,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;
@@ -297,19 +238,9 @@ function normalizeClaudeStreamMessages(cause: Cause.Cause<Error>): ReadonlyArray
   return squashed.length > 0 ? [squashed] : [];
 }
 
-function getEffectiveClaudeAgentEffort(
-  effort: ClaudeAgentEffort | null | undefined,
-): ClaudeSdkEffort | null {
-  if (!effort) {
-    return null;
-  }
-  if (effort === "ultrathink") {
-    return null;
-  }
-  if (effort === "xhigh") {
-    return "max";
-  }
-  return effort;
+function getEffectiveClaudeAgentEffort(effort: string | null | undefined): ClaudeSdkEffort | null {
+  const normalized = normalizeClaudeCliEffort(effort);
+  return normalized ? (normalized as ClaudeSdkEffort) : null;
 }
 
 function isClaudeInterruptedMessage(message: string): boolean {
@@ -639,18 +570,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);
 }
 
@@ -663,7 +595,7 @@ function buildUserMessage(input: {
     parent_tool_use_id: null,
     message: {
       role: "user",
-      content: input.sdkContent as unknown as Array<Record<string, unknown>>,
+      content: input.sdkContent as unknown as SDKUserMessage["message"]["content"],
     },
   } as SDKUserMessage;
 }
@@ -687,9 +619,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) {
@@ -1039,11 +972,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
@@ -1065,7 +1004,6 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
 
   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));
@@ -1469,9 +1407,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     errorMessage?: string,
     result?: SDKResultMessage,
   ) {
-    const resultContextWindow = maxClaudeContextWindowFromModelUsage(
-      result?.modelUsage as Record<string, ModelUsage> | undefined,
-    );
+    const resultContextWindow = maxClaudeContextWindowFromModelUsage(result?.modelUsage);
     if (resultContextWindow !== undefined) {
       context.lastKnownContextWindow = resultContextWindow;
     }
@@ -1648,26 +1584,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       return;
     }
 
-    type StreamEvent = {
-      type: string;
-      delta: {
-        type: string;
-        text?: string;
-        thinking?: string;
-        partial_json?: string;
-        [k: string]: unknown;
-      };
-      index: number;
-      content_block?: {
-        type: string;
-        id?: string;
-        name?: string;
-        input?: unknown;
-        [k: string]: unknown;
-      };
-      [k: string]: unknown;
-    };
-    const { event } = message as { event: StreamEvent };
+    const { event } = message;
 
     if (event.type === "content_block_delta") {
       if (
@@ -1676,7 +1593,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       ) {
         const deltaText =
           event.delta.type === "text_delta"
-            ? (event.delta.text ?? "")
+            ? event.delta.text
             : typeof event.delta.thinking === "string"
               ? event.delta.thinking
               : "";
@@ -1823,9 +1740,6 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
 
     if (event.type === "content_block_start") {
       const { index, content_block: block } = event;
-      if (!block) {
-        return;
-      }
       if (block.type === "text") {
         yield* ensureAssistantTextBlock(context, index, {
           fallbackText: extractContentBlockText(block),
@@ -1840,13 +1754,13 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         return;
       }
 
-      const toolName = block.name ?? "unknown";
+      const toolName = block.name;
       const itemType = classifyToolItemType(toolName);
       const toolInput =
         typeof block.input === "object" && block.input !== null
           ? (block.input as Record<string, unknown>)
           : {};
-      const itemId = block.id ?? "";
+      const itemId = block.id;
       const detail = summarizeToolRequest(toolName, toolInput);
       const inputFingerprint =
         Object.keys(toolInput).length > 0 ? toolInputFingerprint(toolInput) : undefined;
@@ -2118,13 +2032,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     }
 
     const status = turnStatusFromResult(message);
-    const errors = (message as { errors?: unknown[] }).errors;
-    const errorMessage =
-      message.subtype === "success"
-        ? undefined
-        : typeof errors?.[0] === "string"
-          ? errors[0]
-          : undefined;
+    const errorMessage = message.subtype === "success" ? undefined : message.errors[0];
 
     if (status === "failed") {
       yield* emitRuntimeError(context, errorMessage ?? "Claude turn failed.");
@@ -2188,69 +2096,58 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           },
         });
         return;
-      case "hook_started": {
-        const hookStarted = message as SDKHookStartedMessage;
+      case "hook_started":
         yield* offerRuntimeEvent({
           ...base,
           type: "hook.started",
           payload: {
-            hookId: hookStarted.hook_id,
-            hookName: hookStarted.hook_name,
-            hookEvent: hookStarted.hook_event,
+            hookId: message.hook_id,
+            hookName: message.hook_name,
+            hookEvent: message.hook_event,
           },
         });
         return;
-      }
-      case "hook_progress": {
-        const hookProgress = message as SDKHookProgressMessage;
+      case "hook_progress":
         yield* offerRuntimeEvent({
           ...base,
           type: "hook.progress",
           payload: {
-            hookId: hookProgress.hook_id,
-            output: hookProgress.output,
-            stdout: hookProgress.stdout,
-            stderr: hookProgress.stderr,
+            hookId: message.hook_id,
+            output: message.output,
+            stdout: message.stdout,
+            stderr: message.stderr,
           },
         });
         return;
-      }
-      case "hook_response": {
-        const hookResponse = message as SDKHookResponseMessage;
+      case "hook_response":
         yield* offerRuntimeEvent({
           ...base,
           type: "hook.completed",
           payload: {
-            hookId: hookResponse.hook_id,
-            outcome: hookResponse.outcome,
-            output: hookResponse.output,
-            stdout: hookResponse.stdout,
-            stderr: hookResponse.stderr,
-            ...(typeof hookResponse.exit_code === "number"
-              ? { exitCode: hookResponse.exit_code }
-              : {}),
+            hookId: message.hook_id,
+            outcome: message.outcome,
+            output: message.output,
+            stdout: message.stdout,
+            stderr: message.stderr,
+            ...(typeof message.exit_code === "number" ? { exitCode: message.exit_code } : {}),
           },
         });
         return;
-      }
-      case "task_started": {
-        const taskStarted = message as SDKTaskStartedMessage;
+      case "task_started":
         yield* offerRuntimeEvent({
           ...base,
           type: "task.started",
           payload: {
-            taskId: RuntimeTaskId.make(taskStarted.task_id),
-            description: taskStarted.description,
-            ...(taskStarted.task_type ? { taskType: taskStarted.task_type } : {}),
+            taskId: RuntimeTaskId.make(message.task_id),
+            description: message.description,
+            ...(message.task_type ? { taskType: message.task_type } : {}),
           },
         });
         return;
-      }
-      case "task_progress": {
-        const taskProgress = message as SDKTaskProgressMessage;
-        if (taskProgress.usage) {
+      case "task_progress":
+        if (message.usage) {
           const normalizedUsage = normalizeClaudeTokenUsage(
-            taskProgress.usage,
+            message.usage,
             context.lastKnownContextWindow,
           );
           if (normalizedUsage) {
@@ -2271,20 +2168,18 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           ...base,
           type: "task.progress",
           payload: {
-            taskId: RuntimeTaskId.make(taskProgress.task_id),
-            description: taskProgress.description,
-            ...(taskProgress.summary ? { summary: taskProgress.summary } : {}),
-            ...(taskProgress.usage ? { usage: taskProgress.usage } : {}),
-            ...(taskProgress.last_tool_name ? { lastToolName: taskProgress.last_tool_name } : {}),
+            taskId: RuntimeTaskId.make(message.task_id),
+            description: message.description,
+            ...(message.summary ? { summary: message.summary } : {}),
+            ...(message.usage ? { usage: message.usage } : {}),
+            ...(message.last_tool_name ? { lastToolName: message.last_tool_name } : {}),
           },
         });
         return;
-      }
-      case "task_notification": {
-        const taskNotification = message as SDKTaskNotificationMessage;
-        if (taskNotification.usage) {
+      case "task_notification":
+        if (message.usage) {
           const normalizedUsage = normalizeClaudeTokenUsage(
-            taskNotification.usage,
+            message.usage,
             context.lastKnownContextWindow,
           );
           if (normalizedUsage) {
@@ -2305,14 +2200,13 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           ...base,
           type: "task.completed",
           payload: {
-            taskId: RuntimeTaskId.make(taskNotification.task_id),
-            status: taskNotification.status,
-            ...(taskNotification.summary ? { summary: taskNotification.summary } : {}),
-            ...(taskNotification.usage ? { usage: taskNotification.usage } : {}),
+            taskId: RuntimeTaskId.make(message.task_id),
+            status: message.status,
+            ...(message.summary ? { summary: message.summary } : {}),
+            ...(message.usage ? { usage: message.usage } : {}),
           },
         });
         return;
-      }
       case "files_persisted":
         yield* offerRuntimeEvent({
           ...base,
@@ -2380,14 +2274,15 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     }
 
     if (message.type === "tool_use_summary") {
-      const toolSummary = message as SDKToolUseSummaryMessage;
       yield* offerRuntimeEvent({
         ...base,
         type: "tool.summary",
         payload: {
-          summary: toolSummary.summary,
-          ...(toolSummary.preceding_tool_use_ids && toolSummary.preceding_tool_use_ids.length > 0
-            ? { precedingToolUseIds: toolSummary.preceding_tool_use_ids }
+          summary: message.summary,
+          ...(message.preceding_tool_use_ids.length > 0
+            ? {
+                precedingToolUseIds: message.preceding_tool_use_ids,
+              }
             : {}),
         },
       });
@@ -2395,19 +2290,13 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     }
 
     if (message.type === "auth_status") {
-      const authMsg = message as {
-        isAuthenticating?: boolean;
-        output?: string;
-        error?: string;
-        [k: string]: unknown;
-      };
       yield* offerRuntimeEvent({
         ...base,
         type: "auth.status",
         payload: {
-          isAuthenticating: authMsg.isAuthenticating,
-          ...(authMsg.output ? { output: [authMsg.output] } : {}),
-          ...(authMsg.error ? { error: authMsg.error } : {}),
+          isAuthenticating: message.isAuthenticating,
+          output: message.output,
+          ...(message.error ? { error: message.error } : {}),
         },
       });
       return;
@@ -2674,10 +2563,14 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         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)
@@ -2945,31 +2838,27 @@ 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 descriptors = getProviderOptionDescriptors({ caps });
       const apiModelId = modelSelection ? resolveClaudeApiModelId(modelSelection) : undefined;
-      const effort = (resolveEffort(caps, modelSelection?.options?.effort) ??
-        null) as ClaudeAgentEffort | null;
-      const fastMode = modelSelection?.options?.fastMode === true && caps.supportsFastMode;
-      const thinking =
-        typeof modelSelection?.options?.thinking === "boolean" && caps.supportsThinkingToggle
-          ? modelSelection.options.thinking
-          : 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",
@@ -2980,11 +2869,11 @@ 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],
         // The SDK type lags the CLI here: Opus 4.7 accepts `xhigh` even though
         // the published `Options["effort"]` union currently stops at `max`.
@@ -3002,7 +2891,7 @@ 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 } : {}),
       };
@@ -3027,8 +2916,8 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         "claude.query.include_partial_messages": true,
         "claude.query.additional_directories": input.cwd ? [input.cwd] : [],
         "claude.query.setting_sources": [...CLAUDE_SETTING_SOURCES],
-        "claude.query.settings_keys": Object.keys(settings).sort(),
-        "claude.query.extra_args_count": Object.keys(extraArgs).length,
+        "claude.query.settings_json": JSON.stringify(settings),
+        "claude.query.extra_args_json": JSON.stringify(extraArgs),
         "claude.query.path_to_executable": claudeBinaryPath,
       });
 
@@ -3050,6 +2939,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 } : {}),
@@ -3161,7 +3051,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
@@ -3235,6 +3127,7 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     const message = yield* buildUserMessageEffect(input, {
       fileSystem,
       attachmentsDir: serverConfig.attachmentsDir,
+      boundInstanceId,
     });
 
     yield* Queue.offer(context.promptQueue, {
@@ -3353,7 +3246,9 @@ const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
 
   return {
     provider: PROVIDER,
-    capabilities: getProviderCapabilities(PROVIDER),
+    capabilities: {
+      sessionModelSwitch: "in-session",
+    },
     startSession,
     sendTurn,
     interruptTurn,
@@ -3370,9 +3265,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/ClaudeProvider.ts b/apps/server/src/provider/Layers/ClaudeProvider.ts
index d50f9761730..43505967002 100644
--- a/apps/server/src/provider/Layers/ClaudeProvider.ts
+++ b/apps/server/src/provider/Layers/ClaudeProvider.ts
@@ -1,52 +1,45 @@
-import type {
-  ClaudeSettings,
-  ClaudeModelSelection,
-  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 { Effect, Option, Path, Result } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { decodeJsonResult } from "@t3tools/shared/schemaJson";
-import { query as claudeQuery, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
-
-/** Inline type — not yet re-exported from the public SDK entry. */
-type ClaudeSlashCommand = {
-  name: string;
-  description: string;
-  argumentHint: string;
-};
+import {
+  createModelCapabilities,
+  getModelSelectionStringOptionValue,
+  getProviderOptionCurrentValue,
+  getProviderOptionDescriptors,
+} from "@t3tools/shared/model";
+import {
+  query as claudeQuery,
+  type SlashCommand as ClaudeSlashCommand,
+  type SDKUserMessage,
+} from "@anthropic-ai/claude-agent-sdk";
 
 import {
+  buildBooleanOptionDescriptor,
+  buildSelectOptionDescriptor,
   buildServerProvider,
-  AUTH_PROBE_TIMEOUT_MS,
   DEFAULT_TIMEOUT_MS,
   detailFromResult,
-  extractAuthBoolean,
   isCommandMissingCause,
   parseGenericCliVersion,
   providerModelsFromSettings,
-  collectStreamAsString,
-  type CommandResult,
+  spawnAndCollect,
+  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
 import { compareCliVersions } from "../cliVersion.ts";
-import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
-import { ClaudeProvider } from "../Services/ClaudeProvider.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { ServerSettingsError } from "@t3tools/contracts";
-
-const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = {
-  reasoningEffortLevels: [],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-};
+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,
@@ -57,93 +50,128 @@ const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = [
     slug: "claude-opus-4-7",
     name: "Claude Opus 4.7",
     isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { 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" },
+    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" },
+          ],
+        }),
       ],
-      supportsFastMode: false,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [
-        { value: "200k", label: "200k", isDefault: true },
-        { value: "1m", label: "1M" },
-      ],
-      promptInjectedEffortLevels: ["ultrathink"],
-    } satisfies ModelCapabilities,
+    }),
   },
   {
     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" },
-      ],
-      promptInjectedEffortLevels: ["ultrathink"],
-    } satisfies ModelCapabilities,
+    }),
   },
   {
     slug: "claude-opus-4-5",
     name: "Claude Opus 4.5",
     isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [
-        { value: "low", label: "Low" },
-        { value: "medium", label: "Medium" },
-        { value: "high", label: "High", isDefault: true },
-        { value: "max", label: "Max" },
+    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",
+        }),
       ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    } 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" },
+    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" },
+          ],
+        }),
       ],
-      supportsFastMode: false,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [
-        { 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",
+        }),
+      ],
+    }),
   },
 ];
 
@@ -173,188 +201,46 @@ export function getClaudeModelCapabilities(model: string | null | undefined): Mo
   );
 }
 
-export function resolveClaudeApiModelId(modelSelection: ClaudeModelSelection): string {
-  switch (modelSelection.options?.contextWindow) {
-    case "1m":
-      return `${modelSelection.model}[1m]`;
-    default:
-      return modelSelection.model;
-  }
-}
-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 {
@@ -370,11 +256,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":
@@ -391,10 +293,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;
@@ -407,10 +332,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),
     };
   }
 
@@ -426,6 +350,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> {
@@ -437,9 +368,7 @@ function parseClaudeInitializationCommands(
       }
 
       const description = nonEmptyProbeString(command.description);
-      const argumentHint = command.argumentHint
-        ? nonEmptyProbeString(command.argumentHint)
-        : undefined;
+      const argumentHint = nonEmptyProbeString(command.argumentHint);
 
       return [
         {
@@ -513,34 +442,46 @@ function waitForAbortSignal(signal: AbortSignal): Promise<void> {
  * 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({
-      // 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: binaryPath,
-        // @ts-expect-error SDK 0.2.77 types diverge under exactOptionalPropertyTypes
-        abortController: abort,
-        settingSources: ["user", "project", "local"],
-        allowedTools: [],
-        stderr: () => {},
-      },
+  return Effect.gen(function* () {
+    const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+    return yield* Effect.tryPromise(async () => {
+      const q = claudeQuery({
+        // 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,
+          abortController: abort,
+          settingSources: ["user", "project", "local"],
+          allowedTools: [],
+          env: claudeEnvironment,
+          stderr: () => {},
+        },
+      });
+      const init = await q.initializationResult();
+      const account = init.account as
+        | {
+            readonly email?: string;
+            readonly subscriptionType?: string;
+            readonly tokenSource?: string;
+          }
+        | undefined;
+      return {
+        email: account?.email,
+        subscriptionType: account?.subscriptionType,
+        tokenSource: account?.tokenSource,
+        slashCommands: parseClaudeInitializationCommands(init.commands),
+      } satisfies ClaudeCapabilitiesProbe;
     });
-    const init = await q.initializationResult!();
-    const account = (init as { account?: { subscriptionType?: string } }).account;
-    return {
-      subscriptionType: account?.subscriptionType,
-      slashCommands: parseClaudeInitializationCommands(
-        init.commands as ClaudeSlashCommand[] | undefined,
-      ),
-    };
   }).pipe(
     Effect.ensuring(
       Effect.sync(() => {
@@ -556,44 +497,30 @@ const probeClaudeCapabilities = (binaryPath: string) => {
   );
 };
 
-const runClaudeCommand = (args: ReadonlyArray<string>) =>
-  Effect.gen(function* () {
-    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-    const claudeSettings = yield* Effect.service(ServerSettingsService).pipe(
-      Effect.flatMap((service) => service.getSettings),
-      Effect.map((settings) => settings.providers.claudeAgent),
-    );
-    const command = ChildProcess.make(claudeSettings.binaryPath.trim() || "claude", [...args], {
-      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 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 allModels = providerModelsFromSettings(
     BUILT_IN_MODELS,
@@ -604,7 +531,6 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
 
   if (!claudeSettings.enabled) {
     return buildServerProvider({
-      provider: PROVIDER,
       presentation: CLAUDE_PRESENTATION,
       enabled: false,
       checkedAt,
@@ -619,7 +545,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,
   );
@@ -627,7 +553,6 @@ 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,
@@ -646,7 +571,6 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
 
   if (Option.isNone(versionProbe.success)) {
     return buildServerProvider({
-      provider: PROVIDER,
       presentation: CLAUDE_PRESENTATION,
       enabled: claudeSettings.enabled,
       checkedAt,
@@ -667,7 +591,6 @@ 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,
@@ -694,66 +617,14 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
     ? undefined
     : formatClaudeOpus47UpgradeMessage(parsedVersion);
 
-  const slashCommands =
-    (resolveSlashCommands
-      ? yield* resolveSlashCommands(claudeSettings.binaryPath).pipe(
-          Effect.orElseSucceed(() => undefined),
-        )
-      : undefined) ?? [];
+  const capabilities = resolveCapabilities
+    ? yield* resolveCapabilities(claudeSettings).pipe(Effect.orElseSucceed(() => undefined))
+    : undefined;
+  const slashCommands = capabilities?.slashCommands ?? [];
   const dedupedSlashCommands = dedupeSlashCommands(slashCommands);
 
-  // ── Auth check + subscription detection ────────────────────────────
-
-  const authProbe = yield* runClaudeCommand(["auth", "status"]).pipe(
-    Effect.timeoutOption(AUTH_PROBE_TIMEOUT_MS),
-    Effect.result,
-  );
-
-  // 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,
-      presentation: CLAUDE_PRESENTATION,
-      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,
@@ -764,15 +635,16 @@ 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,
@@ -781,21 +653,18 @@ 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 }
-          : {}),
+      ...(opus47UpgradeMessage ? { message: opus47UpgradeMessage } : {}),
     },
   });
 });
 
-const makePendingClaudeProvider = (claudeSettings: ClaudeSettings): ServerProvider => {
+export const makePendingClaudeProvider = (claudeSettings: ClaudeSettings): ServerProviderDraft => {
   const checkedAt = new Date().toISOString();
   const models = providerModelsFromSettings(
     BUILT_IN_MODELS,
@@ -806,7 +675,6 @@ const makePendingClaudeProvider = (claudeSettings: ClaudeSettings): ServerProvid
 
   if (!claudeSettings.enabled) {
     return buildServerProvider({
-      provider: PROVIDER,
       presentation: CLAUDE_PRESENTATION,
       enabled: false,
       checkedAt,
@@ -822,7 +690,6 @@ const makePendingClaudeProvider = (claudeSettings: ClaudeSettings): ServerProvid
   }
 
   return buildServerProvider({
-    provider: PROVIDER,
     presentation: CLAUDE_PRESENTATION,
     enabled: true,
     checkedAt,
@@ -837,43 +704,4 @@ const makePendingClaudeProvider = (claudeSettings: ClaudeSettings): ServerProvid
   });
 };
 
-export const ClaudeProviderLive = Layer.effect(
-  ClaudeProvider,
-  Effect.gen(function* () {
-    const serverSettings = yield* ServerSettingsService;
-    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-
-    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),
-    );
-
-    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),
-      initialSnapshot: makePendingClaudeProvider,
-      checkProvider,
-    });
-  }),
-);
+export { probeClaudeCapabilities };
diff --git a/apps/server/src/provider/Layers/CodexAdapter.test.ts b/apps/server/src/provider/Layers/CodexAdapter.test.ts
index bd7b3bddaef..4df4fb5d32f 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.test.ts
@@ -4,7 +4,10 @@ import os from "node:os";
 import path from "node:path";
 import {
   ApprovalRequestId,
+  CodexSettings,
   EventId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ProviderItemId,
   type ProviderApprovalDecision,
   type ProviderEvent,
@@ -14,16 +17,17 @@ import {
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
+import { createModelSelection } from "@t3tools/shared/model";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it, vi } from "@effect/vitest";
 
-import { Effect, Exit, Fiber, Layer, Option, Queue, Scope, Stream } from "effect";
+import { Context, Effect, Exit, Fiber, Layer, Option, Queue, Schema, Scope, Stream } from "effect";
 import * as CodexErrors from "effect-codex-app-server/errors";
 
 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 {
   type CodexSessionRuntimeOptions,
@@ -31,7 +35,12 @@ import {
   type CodexSessionRuntimeShape,
   type CodexThreadSnapshot,
 } from "./CodexSessionRuntime.ts";
-import { fetchCodexUsage, makeCodexAdapterLive } from "./CodexAdapter.ts";
+import { makeCodexAdapter } from "./CodexAdapter.ts";
+
+// 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);
@@ -44,7 +53,7 @@ class FakeCodexRuntime implements CodexSessionRuntimeShape {
 
   public readonly startImpl = vi.fn(() =>
     Promise.resolve({
-      provider: "codex" as const,
+      provider: ProviderDriverKind.make("codex"),
       status: "ready" as const,
       runtimeMode: this.options.runtimeMode,
       threadId: this.options.threadId,
@@ -202,7 +211,15 @@ const providerSessionDirectoryTestLayer = Layer.succeed(ProviderSessionDirectory
 
 const validationRuntimeFactory = makeRuntimeFactory();
 const validationLayer = it.layer(
-  makeCodexAdapterLive({ makeRuntime: validationRuntimeFactory.factory }).pipe(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = Schema.decodeSync(CodexSettings)({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: validationRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(providerSessionDirectoryTestLayer),
@@ -216,7 +233,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",
         })
@@ -226,7 +243,7 @@ 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'.",
         }),
@@ -234,22 +251,17 @@ validationLayer("CodexAdapterLive validation", (it) => {
       assert.equal(validationRuntimeFactory.factory.mock.calls.length, 0);
     }),
   );
-
   it.effect("maps codex model options before starting a session", () =>
     Effect.gen(function* () {
       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",
       });
 
@@ -257,26 +269,26 @@ validationLayer("CodexAdapterLive validation", (it) => {
         binaryPath: "codex",
         cwd: process.cwd(),
         model: "gpt-5.3-codex",
+        providerInstanceId: ProviderInstanceId.make("codex"),
         serviceTier: "fast",
         threadId: asThreadId("thread-1"),
         runtimeMode: "full-access",
       });
     }),
   );
-
-  it.effect("fetchCodexUsage returns empty usage after manager removal", () =>
-    Effect.gen(function* () {
-      const usage = yield* Effect.promise(() => fetchCodexUsage());
-      assert.equal(usage.provider, "codex");
-      assert.equal(usage.quota, undefined);
-      assert.equal(usage.quotas, undefined);
-    }),
-  );
 });
 
 const sessionRuntimeFactory = makeRuntimeFactory();
 const sessionErrorLayer = it.layer(
-  makeCodexAdapterLive({ makeRuntime: sessionRuntimeFactory.factory }).pipe(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = Schema.decodeSync(CodexSettings)({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: sessionRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(providerSessionDirectoryTestLayer),
@@ -307,7 +319,7 @@ sessionErrorLayer("CodexAdapterLive session errors", (it) => {
     Effect.gen(function* () {
       const adapter = yield* CodexAdapter;
       yield* adapter.startSession({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("sess-missing"),
         runtimeMode: "full-access",
       });
@@ -319,14 +331,10 @@ sessionErrorLayer("CodexAdapterLive session errors", (it) => {
         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: [],
         }),
       );
@@ -339,11 +347,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 = Schema.decodeSync(CodexSettings)({});
+        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 lifecycleRuntimeFactory = makeRuntimeFactory();
 const lifecycleLayer = it.layer(
-  makeCodexAdapterLive({ makeRuntime: lifecycleRuntimeFactory.factory }).pipe(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = Schema.decodeSync(CodexSettings)({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: lifecycleRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(providerSessionDirectoryTestLayer),
@@ -355,7 +426,7 @@ function startLifecycleRuntime() {
   return Effect.gen(function* () {
     const adapter = yield* CodexAdapter;
     yield* adapter.startSession({
-      provider: "codex",
+      provider: ProviderDriverKind.make("codex"),
       threadId: asThreadId("thread-1"),
       runtimeMode: "full-access",
     });
@@ -374,7 +445,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       const event: ProviderEvent = {
         id: asEventId("evt-msg-complete"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         createdAt: new Date().toISOString(),
         method: "item/completed",
         threadId: asThreadId("thread-1"),
@@ -416,7 +487,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       const event: ProviderEvent = {
         id: asEventId("evt-plan-complete"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         createdAt: new Date().toISOString(),
         method: "item/completed",
         threadId: asThreadId("thread-1"),
@@ -457,7 +528,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       yield* runtime.emit({
         id: asEventId("evt-plan-delta"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         createdAt: new Date().toISOString(),
         method: "item/plan/delta",
         threadId: asThreadId("thread-1"),
@@ -494,7 +565,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       const event: ProviderEvent = {
         id: asEventId("evt-session-closed"),
         kind: "session",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
         createdAt: new Date().toISOString(),
         method: "session/closed",
@@ -525,7 +596,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       yield* runtime.emit({
         id: asEventId("evt-retryable-error"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
         createdAt: new Date().toISOString(),
         method: "error",
@@ -563,7 +634,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       yield* runtime.emit({
         id: asEventId("evt-process-stderr"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
         createdAt: new Date().toISOString(),
         method: "process/stderr",
@@ -597,7 +668,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       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(),
         method: "process/stderr",
@@ -633,7 +704,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       const event: ProviderEvent = {
         id: asEventId("evt-request-resolved"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-1"),
         createdAt: new Date().toISOString(),
         method: "serverRequest/resolved",
@@ -668,7 +739,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       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(),
         method: "serverRequest/resolved",
@@ -703,7 +774,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       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(),
         method: "item/tool/requestUserInput/answered",
@@ -743,7 +814,7 @@ 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(),
         method: "windowsSandbox/setupCompleted",
@@ -788,7 +859,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
         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(),
           method: "item/tool/requestUserInput",
@@ -815,7 +886,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
         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(),
           method: "item/tool/requestUserInput/answered",
@@ -855,7 +926,7 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
       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(),
@@ -914,7 +985,15 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
 
 const scopedLifecycleRuntimeFactory = makeScopedRuntimeFactory();
 const scopedLifecycleLayer = it.layer(
-  makeCodexAdapterLive({ makeRuntime: scopedLifecycleRuntimeFactory.factory }).pipe(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = Schema.decodeSync(CodexSettings)({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: scopedLifecycleRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(providerSessionDirectoryTestLayer),
@@ -929,7 +1008,7 @@ scopedLifecycleLayer("CodexAdapterLive scoped lifecycle", (it) => {
       const adapter = yield* CodexAdapter;
 
       yield* adapter.startSession({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-stop"),
         runtimeMode: "full-access",
       });
@@ -950,7 +1029,15 @@ scopedLifecycleLayer("CodexAdapterLive scoped lifecycle", (it) => {
 
 const scopedFailureRuntimeFactory = makeScopedRuntimeFactory({ failConstruction: true });
 const scopedFailureLayer = it.layer(
-  makeCodexAdapterLive({ makeRuntime: scopedFailureRuntimeFactory.factory }).pipe(
+  Layer.effect(
+    CodexAdapter,
+    Effect.gen(function* () {
+      const codexConfig = Schema.decodeSync(CodexSettings)({});
+      return yield* makeCodexAdapter(codexConfig, {
+        makeRuntime: scopedFailureRuntimeFactory.factory,
+      });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(providerSessionDirectoryTestLayer),
@@ -966,7 +1053,7 @@ scopedFailureLayer("CodexAdapterLive scoped startup failure", (it) => {
 
       const result = yield* adapter
         .startSession({
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           threadId: asThreadId("thread-fail"),
           runtimeMode: "full-access",
         })
@@ -991,10 +1078,16 @@ it.effect("flushes managed native logs when the adapter layer shuts down", () =>
     let scopeClosed = false;
 
     try {
-      const layer = makeCodexAdapterLive({
-        makeRuntime: runtimeFactory.factory,
-        nativeEventLogPath: basePath,
-      }).pipe(
+      const layer = Layer.effect(
+        CodexAdapter,
+        Effect.gen(function* () {
+          const codexConfig = Schema.decodeSync(CodexSettings)({});
+          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),
@@ -1004,7 +1097,7 @@ it.effect("flushes managed native logs when the adapter layer shuts down", () =>
       const adapter = yield* Effect.service(CodexAdapter).pipe(Effect.provide(context));
 
       yield* adapter.startSession({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-logger"),
         runtimeMode: "full-access",
       });
@@ -1016,7 +1109,7 @@ it.effect("flushes managed native logs when the adapter layer shuts down", () =>
       yield* runtime.emit({
         id: asEventId("evt-native-log"),
         kind: "notification",
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-logger"),
         createdAt: new Date().toISOString(),
         method: "process/stderr",
@@ -1030,7 +1123,7 @@ it.effect("flushes managed native logs when the adapter layer shuts down", () =>
       const threadLogPath = path.join(tempDir, "thread-logger.log");
       assert.equal(fs.existsSync(threadLogPath), true);
       const contents = fs.readFileSync(threadLogPath, "utf8");
-      assert.match(contents, /NATIVE: .*"message":"native flush test"/);
+      assert.match(contents, /NTIVE: .*"message":"native flush test"/);
     } finally {
       if (!scopeClosed) {
         yield* Scope.close(scope, Exit.void);
diff --git a/apps/server/src/provider/Layers/CodexAdapter.ts b/apps/server/src/provider/Layers/CodexAdapter.ts
index d65741e45f5..5186dc29627 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.ts
@@ -10,7 +10,10 @@
 import {
   type CanonicalItemType,
   type CanonicalRequestType,
+  type CodexSettings,
+  ProviderDriverKind,
   type ProviderEvent,
+  ProviderInstanceId,
   type ProviderRuntimeEvent,
   type ProviderRequestKind,
   type ThreadTokenUsageSnapshot,
@@ -21,11 +24,16 @@ import {
   ThreadId,
   ProviderSendTurnInput,
 } from "@t3tools/contracts";
-import { Effect, Exit, Fiber, FileSystem, Layer, Queue, Schema, Scope, Stream } from "effect";
+import { Effect, Exit, Fiber, FileSystem, Queue, Schema, Scope, Stream } from "effect";
 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 {
   ProviderAdapterRequestError,
   ProviderAdapterProcessError,
@@ -34,12 +42,9 @@ import {
   ProviderAdapterValidationError,
   type ProviderAdapterError,
 } from "../Errors.ts";
-import { CodexAdapter, type CodexAdapterShape } from "../Services/CodexAdapter.ts";
+import { type CodexAdapterShape } from "../Services/CodexAdapter.ts";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
-import type { ProviderUsageResult } from "@t3tools/contracts";
 import {
   CodexResumeCursorSchema,
   CodexSessionRuntimeThreadIdMissingError,
@@ -50,9 +55,11 @@ import {
 } from "./CodexSessionRuntime.ts";
 import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
 
-const PROVIDER = "codex" as const;
+const PROVIDER = ProviderDriverKind.make("codex");
 
 export interface CodexAdapterLiveOptions {
+  readonly instanceId?: ProviderInstanceId;
+  readonly environment?: NodeJS.ProcessEnv;
   readonly makeRuntime?: (
     options: CodexSessionRuntimeOptions,
   ) => Effect.Effect<
@@ -317,15 +324,11 @@ function toUserInputQuestions(questions: ReadonlyArray<CodexToolUserInputQuestio
         question.options
           ?.map((option) => {
             const label = trimText(option.label);
-            // Description is optional — keep label-only options rather than
-            // dropping them, otherwise Codex tool prompts that only provide
-            // labels (no per-option description) lose all choices and the
-            // surrounding `options.length === 0` guard rejects the question.
             const description = trimText(option.description);
-            if (!label) {
+            if (!label || !description) {
               return undefined;
             }
-            return description ? { label, description } : { label };
+            return { label, description };
           })
           .filter((option) => option !== undefined) ?? [];
 
@@ -1319,9 +1322,20 @@ 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);
@@ -1334,7 +1348,6 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
       : undefined);
   const managedNativeEventLogger =
     options?.nativeEventLogger === undefined ? nativeEventLogger : undefined;
-  const serverSettingsService = yield* ServerSettingsService;
   const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
   const sessions = new Map<ThreadId, CodexAdapterSessionContext>();
 
@@ -1354,31 +1367,22 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
           yield* Effect.suspend(() => stopSessionInternal(existing));
         }
 
-        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 runtimeInput: CodexSessionRuntimeOptions = {
           threadId: input.threadId,
+          providerInstanceId: boundInstanceId,
           cwd: input.cwd ?? process.cwd(),
-          binaryPath: codexSettings.binaryPath,
-          ...(codexSettings.homePath ? { homePath: codexSettings.homePath } : {}),
+          binaryPath: codexConfig.binaryPath,
+          ...(options?.environment ? { environment: options.environment } : {}),
+          ...(codexConfig.homePath ? { homePath: codexConfig.homePath } : {}),
           ...(Schema.is(CodexResumeCursorSchema)(input.resumeCursor)
             ? { resumeCursor: input.resumeCursor }
             : {}),
           runtimeMode: input.runtimeMode,
-          ...(input.modelSelection?.provider === "codex"
+          ...(input.modelSelection?.instanceId === boundInstanceId
             ? { model: input.modelSelection.model }
             : {}),
-          ...(input.modelSelection?.provider === "codex" && input.modelSelection.options?.fastMode
+          ...(input.modelSelection?.instanceId === boundInstanceId &&
+          getModelSelectionBooleanOptionValue(input.modelSelection, "fastMode") === true
             ? { serviceTier: "fast" }
             : {}),
         };
@@ -1402,10 +1406,6 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
           ),
         );
 
-        // Keep the Codex event pump in the session scope so it is
-        // interrupted automatically when the session's scope closes,
-        // rather than leaking into the surrounding `Effect.scoped` fiber
-        // which exits as soon as `startSession` returns.
         const eventFiber = yield* Stream.runForEach(runtime.events, (event) =>
           Effect.gen(function* () {
             yield* writeNativeEvent(event);
@@ -1421,7 +1421,7 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
             }
             yield* Queue.offerAll(runtimeEventQueue, runtimeEvents);
           }),
-        ).pipe(Effect.forkIn(sessionScope));
+        ).pipe(Effect.forkChild);
 
         const started = yield* runtime.start().pipe(
           Effect.mapError(
@@ -1495,19 +1495,26 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
     );
 
     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?.provider === "codex"
+        ...(input.modelSelection?.instanceId === boundInstanceId
           ? { 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" }
+        ...(reasoningEffort
+          ? {
+              effort: reasoningEffort as EffectCodexSchema.V2TurnStartParams__ReasoningEffort,
+            }
           : {}),
+        ...(fastMode === true ? { serviceTier: "fast" } : {}),
         ...(input.interactionMode !== undefined ? { interactionMode: input.interactionMode } : {}),
         ...(codexAttachments.length > 0 ? { attachments: codexAttachments } : {}),
       })
@@ -1653,7 +1660,9 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
 
   return {
     provider: PROVIDER,
-    capabilities: getProviderCapabilities(PROVIDER),
+    capabilities: {
+      sessionModelSwitch: "in-session",
+    },
     startSession,
     sendTurn,
     interruptTurn,
@@ -1671,18 +1680,9 @@ const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
   } satisfies CodexAdapterShape;
 });
 
-/**
- * Fetches Codex usage information. After upstream's effect-codex-app-server
- * refactor (PR #1942), the manager-based rate limit readout is no longer
- * available at the adapter layer. Returns an empty usage record until
- * rate-limit events are surfaced through the new session runtime.
- */
-export async function fetchCodexUsage(): Promise<ProviderUsageResult> {
-  return { provider: "codex" };
-}
-
-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 4dee22bdd3c..0917d842a6d 100644
--- a/apps/server/src/provider/Layers/CodexProvider.ts
+++ b/apps/server/src/provider/Layers/CodexProvider.ts
@@ -1,15 +1,4 @@
-import {
-  DateTime,
-  Duration,
-  Effect,
-  Equal,
-  Layer,
-  Option,
-  Result,
-  Schema,
-  Stream,
-  Types,
-} from "effect";
+import { DateTime, Duration, Effect, Layer, Option, Result, Schema, Types } from "effect";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import * as CodexClient from "effect-codex-app-server/client";
 import * as CodexSchema from "effect-codex-app-server/schema";
@@ -25,16 +14,18 @@ import type {
 } from "@t3tools/contracts";
 import { ServerSettingsError } from "@t3tools/contracts";
 
-import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
-import { buildServerProvider } from "../providerSnapshot.ts";
-import { CodexProvider } from "../Services/CodexProvider.ts";
-import { ServerConfig } from "../../config.ts";
+import { createModelCapabilities } from "@t3tools/shared/model";
+
+import { buildServerProvider, type ServerProviderDraft } from "../providerSnapshot.ts";
 import { expandHomePath } from "../../pathExpansion.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import { scopedSafeTeardown } from "./scopedSafeTeardown.ts";
 import packageJson from "../../../package.json" with { type: "json" };
 
-const PROVIDER = "codex" as const;
 const PROVIDER_PROBE_TIMEOUT_MS = 8_000;
+const CODEX_PRESENTATION = {
+  displayName: "Codex",
+  showInteractionModeToggle: true,
+} as const;
 
 export interface CodexAppServerProviderSnapshot {
   readonly account: CodexSchema.V2GetAccountResponse;
@@ -85,20 +76,52 @@ function codexAccountAuthLabel(account: CodexSchema.V2GetAccountResponse["accoun
   }
 }
 
+function codexAccountEmail(account: CodexSchema.V2GetAccountResponse["account"]) {
+  if (!account || account.type !== "chatgpt") return undefined;
+  return account.email;
+}
+
 function mapCodexModelCapabilities(
   model: CodexSchema.V2ModelListResponse__Model,
 ): ModelCapabilities {
-  return {
-    reasoningEffortLevels: model.supportedReasoningEfforts.map(({ reasoningEffort }) => ({
-      value: reasoningEffort,
-      label: REASONING_EFFORT_LABELS[reasoningEffort],
-      ...(reasoningEffort === model.defaultReasoningEffort ? { isDefault: true } : {}),
-    })),
-    supportsFastMode: (model.additionalSpeedTiers ?? []).includes("fast"),
-    supportsThinkingToggle: false,
-    contextWindowOptions: [],
-    promptInjectedEffortLevels: [],
-  };
+  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,
+            },
+          ]
+        : []),
+    ],
+  });
 }
 
 const toDisplayName = (model: CodexSchema.V2ModelListResponse__Model): string => {
@@ -213,18 +236,33 @@ export function buildCodexInitializeParams(): CodexSchema.V1InitializeParams {
   };
 }
 
+// Wrapped with `scopedSafeTeardown("codex-probe")` rather than the usual
+// `Effect.scoped` so that a defect from the `Layer.build` finalizer (e.g.
+// `ChildProcess.kill` throwing because the `codex app-server` child exited
+// early) cannot override a successful probe body. Without this guard the
+// defect bubbles past `Effect.result` in `checkCodexProviderStatus`, dies
+// `refreshOneSource`, and `providersRef` never receives the snapshot.
 const probeCodexAppServerProvider = Effect.fn("probeCodexAppServerProvider")(function* (input: {
   readonly binaryPath: string;
   readonly homePath?: string;
   readonly cwd: string;
   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,
-      ...(input.homePath ? { env: { CODEX_HOME: expandHomePath(input.homePath) } } : {}),
+      env: {
+        ...(input.environment ?? process.env),
+        ...(resolvedHomePath ? { CODEX_HOME: resolvedHomePath } : {}),
+      },
     }),
   );
   const client = yield* Effect.service(CodexClient.CodexAppServerClient).pipe(
@@ -273,7 +311,7 @@ const probeCodexAppServerProvider = Effect.fn("probeCodexAppServerProvider")(fun
     models: appendCustomCodexModels(models, input.customModels ?? []),
     skills: parseCodexSkillsListResponse(skillsResponse, input.cwd),
   } satisfies CodexAppServerProviderSnapshot;
-}, Effect.scoped);
+}, scopedSafeTeardown("codex-probe"));
 
 const emptyCodexModelsFromSettings = (codexSettings: CodexSettings): ServerProvider["models"] =>
   codexSettings.customModels
@@ -286,13 +324,13 @@ const emptyCodexModelsFromSettings = (codexSettings: CodexSettings): ServerProvi
       capabilities: null,
     }));
 
-const makePendingCodexProvider = (codexSettings: CodexSettings): ServerProvider => {
+const makePendingCodexProvider = (codexSettings: CodexSettings): ServerProviderDraft => {
   const checkedAt = new Date().toISOString();
   const models = emptyCodexModelsFromSettings(codexSettings);
 
   if (!codexSettings.enabled) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CODEX_PRESENTATION,
       enabled: false,
       checkedAt,
       models,
@@ -308,7 +346,7 @@ const makePendingCodexProvider = (codexSettings: CodexSettings): ServerProvider
   }
 
   return buildServerProvider({
-    provider: PROVIDER,
+    presentation: CODEX_PRESENTATION,
     enabled: true,
     checkedAt,
     models,
@@ -329,10 +367,12 @@ function accountProbeStatus(account: CodexAppServerProviderSnapshot["account"]):
   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) {
@@ -351,32 +391,30 @@ function accountProbeStatus(account: CodexAppServerProviderSnapshot["account"]):
 }
 
 export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(function* (
+  codexSettings: CodexSettings,
   probe: (input: {
     readonly binaryPath: string;
     readonly homePath?: string;
     readonly cwd: string;
     readonly customModels: ReadonlyArray<string>;
+    readonly environment?: NodeJS.ProcessEnv;
   }) => Effect.Effect<
     CodexAppServerProviderSnapshot,
     CodexErrors.CodexAppServerError,
     ChildProcessSpawner.ChildProcessSpawner
   > = probeCodexAppServerProvider,
+  environment: NodeJS.ProcessEnv = process.env,
 ): Effect.fn.Return<
-  ServerProvider,
+  ServerProviderDraft,
   ServerSettingsError,
-  ServerSettingsService | ServerConfig | ChildProcessSpawner.ChildProcessSpawner
+  ChildProcessSpawner.ChildProcessSpawner
 > {
-  const codexSettings = yield* Effect.service(ServerSettingsService).pipe(
-    Effect.flatMap((service) => service.getSettings),
-    Effect.map((settings) => settings.providers.codex),
-  );
-  const serverConfig = yield* Effect.service(ServerConfig);
   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: emptyModels,
@@ -394,15 +432,16 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
   const probeResult = yield* probe({
     binaryPath: codexSettings.binaryPath,
     homePath: codexSettings.homePath,
-    cwd: serverConfig.cwd,
+    cwd: process.cwd(),
     customModels: codexSettings.customModels,
+    environment,
   }).pipe(Effect.timeoutOption(Duration.millis(PROVIDER_PROBE_TIMEOUT_MS)), Effect.result);
 
   if (Result.isFailure(probeResult)) {
     const error = probeResult.failure;
     const installed = !Schema.is(CodexErrors.CodexAppServerSpawnError)(error);
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CODEX_PRESENTATION,
       enabled: codexSettings.enabled,
       checkedAt,
       models: emptyModels,
@@ -421,7 +460,7 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
 
   if (Option.isNone(probeResult.success)) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CODEX_PRESENTATION,
       enabled: codexSettings.enabled,
       checkedAt,
       models: emptyModels,
@@ -440,7 +479,7 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
   const accountStatus = accountProbeStatus(snapshot.account);
 
   return buildServerProvider({
-    provider: PROVIDER,
+    presentation: CODEX_PRESENTATION,
     enabled: codexSettings.enabled,
     checkedAt,
     models: snapshot.models,
@@ -455,30 +494,11 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
   });
 });
 
-export const CodexProviderLive = Layer.effect(
-  CodexProvider,
-  Effect.gen(function* () {
-    const serverSettings = yield* ServerSettingsService;
-    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-    const serverConfig = yield* Effect.service(ServerConfig);
-    const checkProvider = checkCodexProviderStatus().pipe(
-      Effect.provideService(ServerSettingsService, serverSettings),
-      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
-      Effect.provideService(ServerConfig, serverConfig),
-    );
-
-    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),
-      initialSnapshot: makePendingCodexProvider,
-      checkProvider,
-      refreshInterval: Duration.minutes(5),
-    });
-  }),
-);
+// 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.ts b/apps/server/src/provider/Layers/CodexSessionRuntime.ts
index e45e1825ee2..4f9011fba04 100644
--- a/apps/server/src/provider/Layers/CodexSessionRuntime.ts
+++ b/apps/server/src/provider/Layers/CodexSessionRuntime.ts
@@ -1,10 +1,10 @@
-import { randomUUID } from "node:crypto";
-
 import {
   ApprovalRequestId,
-  DEFAULT_MODEL_BY_PROVIDER,
+  DEFAULT_MODEL,
   EventId,
+  ProviderDriverKind,
   ProviderItemId,
+  type ProviderInstanceId,
   type ProviderApprovalDecision,
   type ProviderEvent,
   type ProviderInteractionMode,
@@ -17,7 +17,7 @@ import {
   TurnId,
 } from "@t3tools/contracts";
 import { normalizeModelSlug } from "@t3tools/shared/model";
-import { Deferred, Effect, Exit, Layer, Queue, Ref, Scope, Schema, Stream } from "effect";
+import { Deferred, Effect, Exit, Layer, Queue, Ref, Scope, Random, Schema, Stream } from "effect";
 import * as SchemaIssue from "effect/SchemaIssue";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import * as CodexClient from "effect-codex-app-server/client";
@@ -26,13 +26,13 @@ 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";
-import { expandHomePath } from "../../pathExpansion.ts";
 
-const PROVIDER = "codex" as const;
+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");
@@ -76,8 +76,10 @@ type CodexThreadItem =
 
 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;
@@ -87,7 +89,10 @@ export interface CodexSessionRuntimeOptions {
 
 export interface CodexSessionRuntimeSendTurnInput {
   readonly input?: string;
-  readonly attachments?: ReadonlyArray<{ readonly type: "image"; readonly url: string }>;
+  readonly attachments?: ReadonlyArray<{
+    readonly type: "image";
+    readonly url: string;
+  }>;
   readonly model?: string;
   readonly serviceTier?: EffectCodexSchema.V2TurnStartParams__ServiceTier | undefined;
   readonly effort?: EffectCodexSchema.V2TurnStartParams__ReasoningEffort | undefined;
@@ -303,7 +308,7 @@ function buildCodexCollaborationMode(input: {
   if (input.interactionMode === undefined) {
     return undefined;
   }
-  const model = normalizeCodexModelSlug(input.model) ?? DEFAULT_MODEL_BY_PROVIDER.codex;
+  const model = normalizeCodexModelSlug(input.model) ?? DEFAULT_MODEL;
   return {
     mode: input.interactionMode,
     settings: {
@@ -321,7 +326,10 @@ export function buildTurnStartParams(input: {
   readonly threadId: string;
   readonly runtimeMode: RuntimeMode;
   readonly prompt?: string;
-  readonly attachments?: ReadonlyArray<{ readonly type: "image"; readonly url: string }>;
+  readonly attachments?: ReadonlyArray<{
+    readonly type: "image";
+    readonly url: string;
+  }>;
   readonly model?: string;
   readonly serviceTier?: EffectCodexSchema.V2TurnStartParams__ServiceTier;
   readonly effort?: EffectCodexSchema.V2TurnStartParams__ReasoningEffort;
@@ -680,13 +688,19 @@ export const makeCodexSessionRuntime = (
     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,
-          ...(options.homePath
-            ? { env: { ...process.env, CODEX_HOME: expandHomePath(options.homePath) } }
-            : {}),
+          env,
           shell: process.platform === "win32",
         }),
       )
@@ -712,6 +726,7 @@ export const makeCodexSessionRuntime = (
 
     const initialSession = {
       provider: PROVIDER,
+      ...(options.providerInstanceId ? { providerInstanceId: options.providerInstanceId } : {}),
       status: "connecting",
       runtimeMode: options.runtimeMode,
       cwd: options.cwd,
@@ -725,13 +740,15 @@ export const makeCodexSessionRuntime = (
     const offerEvent = (event: ProviderEvent) => Queue.offer(events, event).pipe(Effect.asVoid);
 
     const emitEvent = (event: Omit<ProviderEvent, "id" | "provider" | "createdAt">) =>
-      offerEvent({
-        id: EventId.make(randomUUID()),
-        provider: PROVIDER,
-        createdAt: new Date().toISOString(),
-        ...event,
-      });
-
+      Effect.flatMap(Random.nextUUIDv4, (id) =>
+        offerEvent({
+          id: EventId.make(id),
+          provider: PROVIDER,
+          ...(options.providerInstanceId ? { providerInstanceId: options.providerInstanceId } : {}),
+          createdAt: new Date().toISOString(),
+          ...event,
+        }),
+      );
     const emitSessionEvent = (method: string, message: string) =>
       emitEvent({
         kind: "session",
@@ -891,7 +908,7 @@ export const makeCodexSessionRuntime = (
 
     yield* client.handleServerRequest("item/commandExecution/requestApproval", (payload) =>
       Effect.gen(function* () {
-        const requestId = ApprovalRequestId.make(randomUUID());
+        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>();
@@ -947,7 +964,7 @@ export const makeCodexSessionRuntime = (
 
     yield* client.handleServerRequest("item/fileChange/requestApproval", (payload) =>
       Effect.gen(function* () {
-        const requestId = ApprovalRequestId.make(randomUUID());
+        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>();
@@ -1003,7 +1020,7 @@ export const makeCodexSessionRuntime = (
 
     yield* client.handleServerRequest("item/tool/requestUserInput", (payload) =>
       Effect.gen(function* () {
-        const requestId = ApprovalRequestId.make(randomUUID());
+        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>();
diff --git a/apps/server/src/provider/Layers/CopilotAdapter.test.ts b/apps/server/src/provider/Layers/CopilotAdapter.test.ts
index 36fa447fcff..4216a516857 100644
--- a/apps/server/src/provider/Layers/CopilotAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CopilotAdapter.test.ts
@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 
-import { ThreadId } from "@t3tools/contracts";
+import { ProviderDriverKind, ThreadId } from "@t3tools/contracts";
 import { type SessionEvent } from "@github/copilot-sdk";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { afterAll, it, vi } from "@effect/vitest";
@@ -142,7 +142,7 @@ modeLayer("CopilotAdapterLive interaction mode", (it) => {
 
       const adapter = yield* CopilotAdapter;
       const session = yield* adapter.startSession({
-        provider: "copilot",
+        provider: ProviderDriverKind.make("copilot"),
         threadId: asThreadId("thread-mode"),
         runtimeMode: "full-access",
       });
@@ -196,7 +196,7 @@ planLayer("CopilotAdapterLive proposed plan events", (it) => {
 
       const adapter = yield* CopilotAdapter;
       const session = yield* adapter.startSession({
-        provider: "copilot",
+        provider: ProviderDriverKind.make("copilot"),
         threadId: asThreadId("thread-plan"),
         runtimeMode: "full-access",
       });
diff --git a/apps/server/src/provider/Layers/CopilotAdapter.ts b/apps/server/src/provider/Layers/CopilotAdapter.ts
index 5d00bf1e5a8..9195a936b0b 100644
--- a/apps/server/src/provider/Layers/CopilotAdapter.ts
+++ b/apps/server/src/provider/Layers/CopilotAdapter.ts
@@ -1,9 +1,36 @@
+/**
+ * CopilotAdapter — `ProviderAdapterShape` for the GitHub Copilot SDK runtime.
+ *
+ * Refactored from the legacy singleton-Layer adapter to the new
+ * `ProviderDriver` SPI. Exports `makeCopilotAdapter(config, options)`
+ * which returns an Effect that resolves to a fully-formed adapter shape
+ * ready for `ProviderInstance`. All per-session state, including turn
+ * tracking, lives inside this factory's closure — two instances of the
+ * Copilot driver therefore share zero mutable state.
+ *
+ * Two callers:
+ *   1. `CopilotDriver.create()` — production path; wraps the result into
+ *      a `ProviderInstance`.
+ *   2. `makeCopilotAdapterLive(options)` — back-compat Layer that binds the
+ *      adapter to the legacy `CopilotAdapter` Service tag for tests and
+ *      the conformance suite.
+ *
+ * Critical invariants preserved from the legacy implementation:
+ *   - Every spawn that may end up as a child process goes through
+ *     `withSanitizedCopilotDesktopEnv` so the Electron desktop env vars
+ *     (`ELECTRON_RUN_AS_NODE`, `ELECTRON_RENDERER_PORT`, `CLAUDECODE`)
+ *     never leak into the spawned binary.
+ *   - Per-session turn tracking (`currentTurnId`, `pendingCompletionTurnId`,
+ *     etc.) is owned per `ActiveCopilotSession`, which itself lives inside
+ *     the per-driver-instance `sessions` map.
+ */
 import { randomUUID } from "node:crypto";
 
 import {
-  type CodexReasoningEffort,
   EventId,
   type ProviderApprovalDecision,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ProviderItemId,
   type ProviderRuntimeEvent,
   type ProviderSession,
@@ -23,19 +50,24 @@ import type {
   PermissionRequestResult,
   SessionEvent,
 } from "@github/copilot-sdk";
+
+/**
+ * The Copilot SDK's `ReasoningEffort` literal union, redeclared locally
+ * because it's not re-exported from `@github/copilot-sdk`'s package root.
+ * Kept in sync with `dist/types.d.ts` (`"low" | "medium" | "high" | "xhigh"`).
+ */
+type CopilotReasoningEffort = "low" | "medium" | "high" | "xhigh";
 import { Effect, Layer, Queue, Stream } from "effect";
 
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
 import {
   ProviderAdapterProcessError,
   ProviderAdapterRequestError,
   ProviderAdapterSessionNotFoundError,
   ProviderAdapterValidationError,
 } from "../Errors.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
-import { type EventNdjsonLogger } from "./EventNdjsonLogger.ts";
+import type { EventNdjsonLogger } from "./EventNdjsonLogger.ts";
 import {
   assistantUsageFields,
   beginCopilotTurn,
@@ -46,19 +78,24 @@ import {
   recordTurnUsage,
   type CopilotTurnTrackingState,
 } from "./copilotTurnTracking.ts";
-import { resolveBundledCopilotCliPath, withSanitizedCopilotDesktopEnv } from "./copilotCliPath.ts";
+import {
+  resolveBundledCopilotCliPath,
+  withSanitizedCopilotDesktopEnv,
+} from "./copilotCliPath.ts";
 import { CopilotAdapter, type CopilotAdapterShape } from "../Services/CopilotAdapter.ts";
 import { toMessage } from "../toMessage.ts";
 import type {
   ProviderThreadSnapshot,
   ProviderThreadTurnSnapshot,
 } from "../Services/ProviderAdapter.ts";
+import type { CopilotSettings } from "../Drivers/CopilotSettings.ts";
 
-const PROVIDER = "copilot" as const;
+const PROVIDER = ProviderDriverKind.make("copilot");
 const USER_INPUT_QUESTION_ID = "answer";
 const USER_INPUT_QUESTION_HEADER = "Question";
 
 export interface CopilotAdapterLiveOptions {
+  readonly instanceId?: ProviderInstanceId;
   readonly nativeEventLogger?: EventNdjsonLogger;
   readonly clientFactory?: (options: CopilotClientOptions) => CopilotClientHandle;
 }
@@ -100,7 +137,7 @@ interface ActiveCopilotSession extends CopilotTurnTrackingState {
   cwd: string | undefined;
   configDir: string | undefined;
   model: string | undefined;
-  reasoningEffort: CodexReasoningEffort | undefined;
+  reasoningEffort: CopilotReasoningEffort | undefined;
   interactionMode: "default" | "plan" | undefined;
   updatedAt: string;
   lastError: string | undefined;
@@ -194,15 +231,36 @@ function mapSupportedModelsById(models: ReadonlyArray<ModelInfo>) {
   return new Map(models.map((model) => [model.id, model]));
 }
 
-function getCopilotReasoningEffort(modelOptions: unknown) {
-  const record = asRecord(modelOptions);
-  const copilot = asRecord(record?.copilot);
-  const reasoningEffort = normalizeString(copilot?.reasoningEffort);
-  return reasoningEffort === "low" ||
-    reasoningEffort === "medium" ||
-    reasoningEffort === "high" ||
-    reasoningEffort === "xhigh"
-    ? reasoningEffort
+/**
+ * Read the Copilot reasoning-effort selection from the model selection's
+ * options. Accepts the SDK's four legal values (`low`/`medium`/`high`/
+ * `xhigh`) and returns `undefined` for anything else.
+ */
+function getCopilotReasoningEffort(
+  modelOptions:
+    | ReadonlyArray<{ readonly id: string; readonly value: string | boolean }>
+    | undefined,
+): CopilotReasoningEffort | undefined {
+  if (!modelOptions) return undefined;
+  // Tolerate both shapes seen in the wild: a typed
+  // `ProviderOptionSelections` array (current) and an old
+  // `{ copilot: { reasoningEffort } }` envelope (legacy persisted state).
+  let raw: string | undefined;
+  for (const option of modelOptions) {
+    if (option.id === "reasoningEffort" && typeof option.value === "string") {
+      raw = option.value;
+      break;
+    }
+  }
+  if (!raw) {
+    // Legacy `{ copilot: { reasoningEffort } }` shape — only reachable if a
+    // caller hands us an unknown blob (not the typed contract).
+    const record = asRecord(modelOptions as unknown);
+    const copilot = asRecord(record?.copilot);
+    raw = normalizeString(copilot?.reasoningEffort);
+  }
+  return raw === "low" || raw === "medium" || raw === "high" || raw === "xhigh"
+    ? raw
     : undefined;
 }
 
@@ -413,7 +471,7 @@ function createSessionRecord(input: {
   readonly cwd: string | undefined;
   readonly configDir: string | undefined;
   readonly model: string | undefined;
-  readonly reasoningEffort: CodexReasoningEffort | undefined;
+  readonly reasoningEffort: CopilotReasoningEffort | undefined;
 }): ActiveCopilotSession {
   return {
     client: input.client,
@@ -441,914 +499,911 @@ function createSessionRecord(input: {
   };
 }
 
-const makeCopilotAdapter = (options?: CopilotAdapterLiveOptions) =>
-  Effect.gen(function* () {
-    const serverConfig = yield* ServerConfig;
-    const serverSettingsService = yield* ServerSettingsService;
-    const nativeEventLogger = options?.nativeEventLogger;
-    const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
-    const sessions = new Map<ThreadId, ActiveCopilotSession>();
-
-    const emitRuntimeEvents = (events: ReadonlyArray<ProviderRuntimeEvent>) =>
-      Effect.runPromise(Queue.offerAll(runtimeEventQueue, events).pipe(Effect.asVoid)).catch(
-        () => undefined,
-      );
-
-    const writeNativeEvent = (threadId: ThreadId, event: SessionEvent) => {
-      if (!nativeEventLogger) return Promise.resolve();
-      return Effect.runPromise(nativeEventLogger.write(event, threadId)).catch(() => undefined);
-    };
+/**
+ * Per-instance Copilot adapter factory.
+ *
+ * `copilotSettings` is the typed config decoded by the registry. Two
+ * instances of the Copilot driver pass two independent `copilotSettings`
+ * payloads here and get two adapter shapes that share no mutable state
+ * (sessions map, runtime event queue, approval resolvers, turn tracking).
+ */
+export const makeCopilotAdapter = Effect.fn("makeCopilotAdapter")(function* (
+  copilotSettings: CopilotSettings,
+  options?: CopilotAdapterLiveOptions,
+) {
+  const _boundInstanceId = options?.instanceId ?? ProviderInstanceId.make("copilot");
+  const serverConfig = yield* ServerConfig;
+  const nativeEventLogger = options?.nativeEventLogger;
+  const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
+  const sessions = new Map<ThreadId, ActiveCopilotSession>();
+
+  const emitRuntimeEvents = (events: ReadonlyArray<ProviderRuntimeEvent>) =>
+    Effect.runPromise(Queue.offerAll(runtimeEventQueue, events).pipe(Effect.asVoid)).catch(
+      () => undefined,
+    );
 
-    const currentSyntheticTurnId = (record: ActiveCopilotSession) =>
-      completionTurnRefs(record).turnId ?? record.currentTurnId;
+  const writeNativeEvent = (threadId: ThreadId, event: SessionEvent) => {
+    if (!nativeEventLogger) return Promise.resolve();
+    return Effect.runPromise(nativeEventLogger.write(event, threadId)).catch(() => undefined);
+  };
 
-    const syncInteractionMode = (
-      record: ActiveCopilotSession,
-      interactionMode: "default" | "plan",
-    ) => {
-      if (record.interactionMode === interactionMode) {
-        return Effect.void;
-      }
-      return Effect.tryPromise({
-        try: async () => {
-          await record.session.rpc.mode.set({
-            mode: toCopilotSessionMode(interactionMode),
-          });
-          record.interactionMode = interactionMode;
-        },
-        catch: (cause) =>
-          new ProviderAdapterRequestError({
-            provider: PROVIDER,
-            method: "session.mode.set",
-            detail: toMessage(cause, "Failed to switch GitHub Copilot interaction mode."),
-            cause,
-          }),
-      });
-    };
+  const currentSyntheticTurnId = (record: ActiveCopilotSession) =>
+    completionTurnRefs(record).turnId ?? record.currentTurnId;
 
-    const emitLatestProposedPlan = (record: ActiveCopilotSession) =>
-      Effect.tryPromise({
-        try: () => record.session.rpc.plan.read(),
-        catch: (cause) =>
-          new ProviderAdapterRequestError({
-            provider: PROVIDER,
-            method: "session.plan.read",
-            detail: toMessage(cause, "Failed to read the GitHub Copilot plan."),
-            cause,
-          }),
-      }).pipe(
-        Effect.flatMap((plan) => {
-          const planMarkdown = trimToUndefined(plan.content ?? undefined);
-          if (!plan.exists || !planMarkdown) {
-            return Effect.void;
-          }
-          return Queue.offer(
-            runtimeEventQueue,
-            makeSyntheticEvent(
-              record.threadId,
-              "turn.proposed.completed",
-              {
-                planMarkdown,
-              },
-              { turnId: currentSyntheticTurnId(record) },
-            ),
-          ).pipe(Effect.asVoid);
+  const syncInteractionMode = (
+    record: ActiveCopilotSession,
+    interactionMode: "default" | "plan",
+  ) => {
+    if (record.interactionMode === interactionMode) {
+      return Effect.void;
+    }
+    return Effect.tryPromise({
+      try: async () => {
+        await record.session.rpc.mode.set({
+          mode: toCopilotSessionMode(interactionMode),
+        });
+        record.interactionMode = interactionMode;
+      },
+      catch: (cause) =>
+        new ProviderAdapterRequestError({
+          provider: PROVIDER,
+          method: "session.mode.set",
+          detail: toMessage(cause, "Failed to switch GitHub Copilot interaction mode."),
+          cause,
         }),
-      );
+    });
+  };
 
-    const mapSessionEvent = (
-      record: ActiveCopilotSession,
-      event: SessionEvent,
-    ): ReadonlyArray<ProviderRuntimeEvent> => {
-      const currentTurnId = record.currentTurnId;
-      const currentProviderTurnId = record.currentProviderTurnId;
-      const resolveOrchestrationTurnId = (
-        providerTurnId: TurnId | undefined,
-      ): TurnId | undefined => {
-        if (providerTurnId && currentProviderTurnId && providerTurnId === currentProviderTurnId) {
-          return currentTurnId ?? providerTurnId;
+  const emitLatestProposedPlan = (record: ActiveCopilotSession) =>
+    Effect.tryPromise({
+      try: () => record.session.rpc.plan.read(),
+      catch: (cause) =>
+        new ProviderAdapterRequestError({
+          provider: PROVIDER,
+          method: "session.plan.read",
+          detail: toMessage(cause, "Failed to read the GitHub Copilot plan."),
+          cause,
+        }),
+    }).pipe(
+      Effect.flatMap((plan) => {
+        const planMarkdown = trimToUndefined(plan.content ?? undefined);
+        if (!plan.exists || !planMarkdown) {
+          return Effect.void;
         }
-        return currentTurnId ?? providerTurnId;
-      };
-      const base = (input?: {
-        readonly turnId?: TurnId | undefined;
-        readonly providerTurnId?: TurnId | undefined;
-        readonly itemId?: string | undefined;
-        readonly requestId?: string | undefined;
-      }) =>
-        withRefs({
-          threadId: record.threadId,
-          eventId: EventId.make(event.id),
-          createdAt: event.timestamp,
-          turnId: resolveOrchestrationTurnId(input?.providerTurnId ?? input?.turnId),
-          providerTurnId: input?.providerTurnId ?? input?.turnId,
-          itemId: input?.itemId,
-          requestId: input?.requestId,
-          rawMethod: event.type,
-          rawPayload: event,
-        });
-
-      switch (event.type) {
-        case "session.start":
-        case "session.resume":
-          return [
+        return Queue.offer(
+          runtimeEventQueue,
+          makeSyntheticEvent(
+            record.threadId,
+            "turn.proposed.completed",
             {
-              ...base(),
-              type: "session.started",
-              payload: {
-                message:
-                  event.type === "session.resume"
-                    ? "Resumed GitHub Copilot session"
-                    : "Started GitHub Copilot session",
-                resume: event.data,
-              },
+              planMarkdown,
             },
-            {
-              ...base(),
-              type: "thread.started",
-              payload: {
-                providerThreadId:
-                  event.type === "session.start" ? event.data.sessionId : record.session.sessionId,
-              },
+            { turnId: currentSyntheticTurnId(record) },
+          ),
+        ).pipe(Effect.asVoid);
+      }),
+    );
+
+  const mapSessionEvent = (
+    record: ActiveCopilotSession,
+    event: SessionEvent,
+  ): ReadonlyArray<ProviderRuntimeEvent> => {
+    const currentTurnId = record.currentTurnId;
+    const currentProviderTurnId = record.currentProviderTurnId;
+    const resolveOrchestrationTurnId = (
+      providerTurnId: TurnId | undefined,
+    ): TurnId | undefined => {
+      if (providerTurnId && currentProviderTurnId && providerTurnId === currentProviderTurnId) {
+        return currentTurnId ?? providerTurnId;
+      }
+      return currentTurnId ?? providerTurnId;
+    };
+    const base = (input?: {
+      readonly turnId?: TurnId | undefined;
+      readonly providerTurnId?: TurnId | undefined;
+      readonly itemId?: string | undefined;
+      readonly requestId?: string | undefined;
+    }) =>
+      withRefs({
+        threadId: record.threadId,
+        eventId: EventId.make(event.id),
+        createdAt: event.timestamp,
+        turnId: resolveOrchestrationTurnId(input?.providerTurnId ?? input?.turnId),
+        providerTurnId: input?.providerTurnId ?? input?.turnId,
+        itemId: input?.itemId,
+        requestId: input?.requestId,
+        rawMethod: event.type,
+        rawPayload: event,
+      });
+
+    switch (event.type) {
+      case "session.start":
+      case "session.resume":
+        return [
+          {
+            ...base(),
+            type: "session.started",
+            payload: {
+              message:
+                event.type === "session.resume"
+                  ? "Resumed GitHub Copilot session"
+                  : "Started GitHub Copilot session",
+              resume: event.data,
             },
-          ];
-        case "session.info":
-          return [
-            {
-              ...base(),
-              type: "runtime.warning",
-              payload: {
-                message: event.data.message,
-                detail: event.data,
-              },
+          },
+          {
+            ...base(),
+            type: "thread.started",
+            payload: {
+              providerThreadId:
+                event.type === "session.start" ? event.data.sessionId : record.session.sessionId,
             },
-          ];
-        case "session.warning":
-          return [
-            {
-              ...base(),
-              type: "runtime.warning",
-              payload: {
-                message: event.data.message,
-                detail: event.data,
-              },
+          },
+        ];
+      case "session.info":
+        return [
+          {
+            ...base(),
+            type: "runtime.warning",
+            payload: {
+              message: event.data.message,
+              detail: event.data,
             },
-          ];
-        case "session.error":
-          return [
-            {
-              ...base(),
-              type: "runtime.error",
-              payload: {
-                message: event.data.message,
-                class: "provider_error",
-                detail: event.data,
-              },
+          },
+        ];
+      case "session.warning":
+        return [
+          {
+            ...base(),
+            type: "runtime.warning",
+            payload: {
+              message: event.data.message,
+              detail: event.data,
             },
-            {
-              ...base(),
-              type: "session.state.changed",
-              payload: {
-                state: "error",
-                reason: "session.error",
-                detail: event.data,
-              },
+          },
+        ];
+      case "session.error":
+        return [
+          {
+            ...base(),
+            type: "runtime.error",
+            payload: {
+              message: event.data.message,
+              class: "provider_error",
+              detail: event.data,
             },
-          ];
-        case "session.idle": {
-          const idleCompletionRefs = completionTurnRefs(record);
-          const idleCompletionEvents: ProviderRuntimeEvent[] =
-            idleCompletionRefs.turnId || idleCompletionRefs.providerTurnId
-              ? [
-                  {
-                    ...base(idleCompletionRefs),
-                    type: "turn.completed",
-                    payload: {
-                      state: "completed",
-                      ...assistantUsageFields(record.pendingTurnUsage),
-                    },
-                  } satisfies ProviderRuntimeEvent,
-                ]
-              : [];
-          return [
-            ...idleCompletionEvents,
-            {
-              ...base(),
-              type: "session.state.changed",
-              payload: {
-                state: "ready",
-                reason: "session.idle",
-              },
+          },
+          {
+            ...base(),
+            type: "session.state.changed",
+            payload: {
+              state: "error",
+              reason: "session.error",
+              detail: event.data,
             },
-            {
-              ...base(),
-              type: "thread.state.changed",
-              payload: {
-                state: "idle",
-                detail: event.data,
-              },
+          },
+        ];
+      case "session.idle": {
+        const idleCompletionRefs = completionTurnRefs(record);
+        const idleCompletionEvents: ProviderRuntimeEvent[] =
+          idleCompletionRefs.turnId || idleCompletionRefs.providerTurnId
+            ? [
+                {
+                  ...base(idleCompletionRefs),
+                  type: "turn.completed",
+                  payload: {
+                    state: "completed",
+                    ...assistantUsageFields(record.pendingTurnUsage),
+                  },
+                } satisfies ProviderRuntimeEvent,
+              ]
+            : [];
+        return [
+          ...idleCompletionEvents,
+          {
+            ...base(),
+            type: "session.state.changed",
+            payload: {
+              state: "ready",
+              reason: "session.idle",
             },
-          ];
-        }
-        case "session.title_changed":
-          return [
-            {
-              ...base(),
-              type: "thread.metadata.updated",
-              payload: {
-                name: event.data.title,
-                metadata: event.data,
-              },
+          },
+          {
+            ...base(),
+            type: "thread.state.changed",
+            payload: {
+              state: "idle",
+              detail: event.data,
             },
-          ];
-        case "session.model_change":
-          return [
-            {
-              ...base(),
-              type: "model.rerouted",
-              payload: {
-                fromModel: event.data.previousModel ?? "unknown",
-                toModel: event.data.newModel,
-                reason: "session.model_change",
-              },
+          },
+        ];
+      }
+      case "session.title_changed":
+        return [
+          {
+            ...base(),
+            type: "thread.metadata.updated",
+            payload: {
+              name: event.data.title,
+              metadata: event.data,
             },
-          ];
-        case "session.plan_changed":
-          return [
-            {
-              ...base(),
-              type: "turn.plan.updated",
-              payload: {
-                explanation: `Plan ${event.data.operation}d`,
-                plan: [],
-              },
+          },
+        ];
+      case "session.model_change":
+        return [
+          {
+            ...base(),
+            type: "model.rerouted",
+            payload: {
+              fromModel: event.data.previousModel ?? "unknown",
+              toModel: event.data.newModel,
+              reason: "session.model_change",
             },
-          ];
-        case "session.workspace_file_changed":
-          return [
-            {
-              ...base(),
-              type: "files.persisted",
-              payload: {
-                files: [
-                  {
-                    filename: event.data.path,
-                    fileId: event.data.path,
-                  },
-                ],
-              },
+          },
+        ];
+      case "session.plan_changed":
+        return [
+          {
+            ...base(),
+            type: "turn.plan.updated",
+            payload: {
+              explanation: `Plan ${event.data.operation}d`,
+              plan: [],
             },
-          ];
-        case "session.context_changed":
-          return [
-            {
-              ...base(),
-              type: "thread.metadata.updated",
-              payload: {
-                metadata: event.data,
-              },
+          },
+        ];
+      case "session.workspace_file_changed":
+        return [
+          {
+            ...base(),
+            type: "files.persisted",
+            payload: {
+              files: [
+                {
+                  filename: event.data.path,
+                  fileId: event.data.path,
+                },
+              ],
             },
-          ];
-        case "session.usage_info":
-          return [
-            {
-              ...base(),
-              type: "thread.token-usage.updated",
-              payload: {
-                usage: event.data,
-              },
+          },
+        ];
+      case "session.context_changed":
+        return [
+          {
+            ...base(),
+            type: "thread.metadata.updated",
+            payload: {
+              metadata: event.data,
             },
-          ];
-        case "session.task_complete":
-          return [
-            {
-              ...base(),
-              type: "task.completed",
-              payload: {
-                taskId: toRuntimeTaskId(record.threadId) ?? RuntimeTaskId.make(record.threadId),
-                status: "completed",
-                ...(trimToUndefined(event.data.summary) ? { summary: event.data.summary } : {}),
+          },
+        ];
+      case "session.usage_info": {
+        const usedTokens = Math.max(0, Math.floor(event.data.currentTokens));
+        const tokenLimit = Math.floor(event.data.tokenLimit);
+        return [
+          {
+            ...base(),
+            type: "thread.token-usage.updated",
+            payload: {
+              usage: {
+                usedTokens,
+                ...(tokenLimit > 0 ? { maxTokens: tokenLimit } : {}),
               },
             },
-          ];
-        case "assistant.turn_start":
-          return [
-            {
-              ...base({ providerTurnId: toTurnId(event.data.turnId) }),
-              type: "turn.started",
-              payload: record.model ? { model: record.model } : {},
+          },
+        ];
+      }
+      case "session.task_complete":
+        return [
+          {
+            ...base(),
+            type: "task.completed",
+            payload: {
+              taskId: toRuntimeTaskId(record.threadId) ?? RuntimeTaskId.make(record.threadId),
+              status: "completed",
+              ...(trimToUndefined(event.data.summary) ? { summary: event.data.summary } : {}),
             },
-            {
-              ...base({ providerTurnId: toTurnId(event.data.turnId) }),
-              type: "session.state.changed",
-              payload: {
-                state: "running",
-                reason: "assistant.turn_start",
-              },
+          },
+        ];
+      case "assistant.turn_start":
+        return [
+          {
+            ...base({ providerTurnId: toTurnId(event.data.turnId) }),
+            type: "turn.started",
+            payload: record.model ? { model: record.model } : {},
+          },
+          {
+            ...base({ providerTurnId: toTurnId(event.data.turnId) }),
+            type: "session.state.changed",
+            payload: {
+              state: "running",
+              reason: "assistant.turn_start",
             },
-          ];
-        case "assistant.reasoning":
-          return [
-            {
-              ...base({ itemId: event.data.reasoningId }),
-              type: "item.completed",
-              payload: {
-                itemType: "reasoning",
-                status: "completed",
-                title: "Reasoning",
-                detail: trimToUndefined(event.data.content),
-                data: event.data,
-              },
+          },
+        ];
+      case "assistant.reasoning":
+        return [
+          {
+            ...base({ itemId: event.data.reasoningId }),
+            type: "item.completed",
+            payload: {
+              itemType: "reasoning",
+              status: "completed",
+              title: "Reasoning",
+              detail: trimToUndefined(event.data.content),
+              data: event.data,
             },
-          ];
-        case "assistant.reasoning_delta":
-          return [
-            {
-              ...base({ itemId: event.data.reasoningId }),
-              type: "content.delta",
-              payload: {
-                streamKind: "reasoning_text",
-                delta: event.data.deltaContent,
-              },
+          },
+        ];
+      case "assistant.reasoning_delta":
+        return [
+          {
+            ...base({ itemId: event.data.reasoningId }),
+            type: "content.delta",
+            payload: {
+              streamKind: "reasoning_text",
+              delta: event.data.deltaContent,
             },
-          ];
-        case "assistant.message":
-          return [
-            {
-              ...base({ itemId: event.data.messageId }),
-              type: "item.completed",
-              payload: {
-                itemType: "assistant_message",
-                status: "completed",
-                title: "Assistant message",
-                detail: trimToUndefined(event.data.content),
-                data: event.data,
-              },
+          },
+        ];
+      case "assistant.message":
+        return [
+          {
+            ...base({ itemId: event.data.messageId }),
+            type: "item.completed",
+            payload: {
+              itemType: "assistant_message",
+              status: "completed",
+              title: "Assistant message",
+              detail: trimToUndefined(event.data.content),
+              data: event.data,
             },
-          ];
-        case "assistant.message_delta":
-          return [
-            {
-              ...base({ itemId: event.data.messageId }),
-              type: "content.delta",
-              payload: {
-                streamKind: "assistant_text",
-                delta: event.data.deltaContent,
-              },
+          },
+        ];
+      case "assistant.message_delta":
+        return [
+          {
+            ...base({ itemId: event.data.messageId }),
+            type: "content.delta",
+            payload: {
+              streamKind: "assistant_text",
+              delta: event.data.deltaContent,
             },
-          ];
-        case "assistant.turn_end":
-          return [];
-        case "assistant.usage": {
-          const completionRefs = completionTurnRefs(record);
-          const completionBase =
-            completionRefs.turnId || completionRefs.providerTurnId ? base(completionRefs) : base();
-          return [
-            {
-              ...completionBase,
-              type: "thread.token-usage.updated",
-              payload: {
-                usage: event.data,
+          },
+        ];
+      case "assistant.turn_end":
+        return [];
+      case "assistant.usage": {
+        const completionRefs = completionTurnRefs(record);
+        const completionBase =
+          completionRefs.turnId || completionRefs.providerTurnId ? base(completionRefs) : base();
+        const inputTokens = event.data.inputTokens;
+        const outputTokens = event.data.outputTokens;
+        const cachedInputTokens = event.data.cacheReadTokens;
+        const durationMs =
+          event.data.duration !== undefined ? Math.max(0, Math.floor(event.data.duration)) : undefined;
+        const usedTokens = Math.max(0, (inputTokens ?? 0) + (outputTokens ?? 0));
+        return [
+          {
+            ...completionBase,
+            type: "thread.token-usage.updated",
+            payload: {
+              usage: {
+                usedTokens,
+                ...(inputTokens !== undefined ? { inputTokens } : {}),
+                ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+                ...(outputTokens !== undefined ? { outputTokens } : {}),
+                ...(usedTokens > 0 ? { lastUsedTokens: usedTokens } : {}),
+                ...(inputTokens !== undefined ? { lastInputTokens: inputTokens } : {}),
+                ...(cachedInputTokens !== undefined
+                  ? { lastCachedInputTokens: cachedInputTokens }
+                  : {}),
+                ...(outputTokens !== undefined ? { lastOutputTokens: outputTokens } : {}),
+                ...(durationMs !== undefined ? { durationMs } : {}),
               },
             },
-          ];
-        }
-        case "abort": {
-          const abortedTurnRefs = completionTurnRefs(record);
-          const abortedBase =
-            abortedTurnRefs.turnId || abortedTurnRefs.providerTurnId
-              ? base(abortedTurnRefs)
-              : base();
-          return [
-            {
-              ...abortedBase,
-              type: "turn.aborted",
-              payload: {
-                reason: event.data.reason,
-              },
+          },
+        ];
+      }
+      case "abort": {
+        const abortedTurnRefs = completionTurnRefs(record);
+        const abortedBase =
+          abortedTurnRefs.turnId || abortedTurnRefs.providerTurnId
+            ? base(abortedTurnRefs)
+            : base();
+        return [
+          {
+            ...abortedBase,
+            type: "turn.aborted",
+            payload: {
+              reason: event.data.reason,
             },
-          ];
-        }
-        case "tool.execution_start":
-          return [
-            {
-              ...base({ itemId: event.data.toolCallId }),
-              type: "item.started",
-              payload: {
-                itemType: itemTypeFromToolEvent(event),
-                status: "inProgress",
-                title: event.data.toolName ?? "Tool call",
-                ...(toolDetailFromEvent(event.data)
-                  ? { detail: toolDetailFromEvent(event.data) }
-                  : {}),
-                data: event.data,
-              },
+          },
+        ];
+      }
+      case "tool.execution_start":
+        return [
+          {
+            ...base({ itemId: event.data.toolCallId }),
+            type: "item.started",
+            payload: {
+              itemType: itemTypeFromToolEvent(event),
+              status: "inProgress",
+              title: event.data.toolName ?? "Tool call",
+              ...(toolDetailFromEvent(event.data)
+                ? { detail: toolDetailFromEvent(event.data) }
+                : {}),
+              data: event.data,
             },
-          ];
-        case "tool.execution_progress":
-          return [
-            {
-              ...base({ itemId: event.data.toolCallId }),
-              type: "tool.progress",
-              payload: {
-                toolUseId: event.data.toolCallId,
-                summary: event.data.progressMessage,
-              },
+          },
+        ];
+      case "tool.execution_progress":
+        return [
+          {
+            ...base({ itemId: event.data.toolCallId }),
+            type: "tool.progress",
+            payload: {
+              toolUseId: event.data.toolCallId,
+              summary: event.data.progressMessage,
             },
-          ];
-        case "tool.execution_partial_result":
-          return [
-            {
-              ...base({ itemId: event.data.toolCallId }),
-              type: "tool.progress",
-              payload: {
-                toolUseId: event.data.toolCallId,
-                summary: event.data.partialOutput,
-              },
+          },
+        ];
+      case "tool.execution_partial_result":
+        return [
+          {
+            ...base({ itemId: event.data.toolCallId }),
+            type: "tool.progress",
+            payload: {
+              toolUseId: event.data.toolCallId,
+              summary: event.data.partialOutput,
             },
-          ];
-        case "tool.execution_complete":
-          return [
-            {
-              ...base({ itemId: event.data.toolCallId }),
-              type: "item.completed",
-              payload: {
-                itemType: event.data.result?.contents?.some(
-                  (content: { type: string }) => content.type === "terminal",
-                )
-                  ? "command_execution"
-                  : "dynamic_tool_call",
-                status: event.data.success ? "completed" : "failed",
-                title: record.toolTitlesByCallId.get(event.data.toolCallId) ?? "Tool call",
-                ...(trimToUndefined(event.data.result?.content)
-                  ? { detail: event.data.result?.content }
-                  : {}),
-                data: event.data,
-              },
+          },
+        ];
+      case "tool.execution_complete":
+        return [
+          {
+            ...base({ itemId: event.data.toolCallId }),
+            type: "item.completed",
+            payload: {
+              itemType: event.data.result?.contents?.some(
+                (content: { type: string }) => content.type === "terminal",
+              )
+                ? "command_execution"
+                : "dynamic_tool_call",
+              status: event.data.success ? "completed" : "failed",
+              title: record.toolTitlesByCallId.get(event.data.toolCallId) ?? "Tool call",
+              ...(trimToUndefined(event.data.result?.content)
+                ? { detail: event.data.result?.content }
+                : {}),
+              data: event.data,
             },
-            ...(trimToUndefined(event.data.result?.content)
-              ? [
-                  {
-                    ...base({ itemId: event.data.toolCallId }),
-                    type: "tool.summary" as const,
-                    payload: {
-                      summary: event.data.result?.content ?? "",
-                      precedingToolUseIds: [event.data.toolCallId],
-                    },
+          },
+          ...(trimToUndefined(event.data.result?.content)
+            ? [
+                {
+                  ...base({ itemId: event.data.toolCallId }),
+                  type: "tool.summary" as const,
+                  payload: {
+                    summary: event.data.result?.content ?? "",
+                    precedingToolUseIds: [event.data.toolCallId],
                   },
-                ]
-              : []),
-          ];
-        case "skill.invoked":
-          return [
-            {
-              ...base(),
-              type: "task.progress",
-              payload: {
-                taskId: toRuntimeTaskId(event.data.name) ?? RuntimeTaskId.make(event.data.name),
-                description: `Invoked skill ${event.data.name}`,
-              },
+                },
+              ]
+            : []),
+        ];
+      case "skill.invoked":
+        return [
+          {
+            ...base(),
+            type: "task.progress",
+            payload: {
+              taskId: toRuntimeTaskId(event.data.name) ?? RuntimeTaskId.make(event.data.name),
+              description: `Invoked skill ${event.data.name}`,
             },
-          ];
-        case "subagent.started":
-          return [
-            {
-              ...base(),
-              type: "task.started",
-              payload: {
-                taskId:
-                  toRuntimeTaskId(event.data.toolCallId) ??
-                  RuntimeTaskId.make(event.data.toolCallId),
-                description: trimToUndefined(event.data.agentDescription),
-                taskType: "subagent",
-              },
+          },
+        ];
+      case "subagent.started":
+        return [
+          {
+            ...base(),
+            type: "task.started",
+            payload: {
+              taskId:
+                toRuntimeTaskId(event.data.toolCallId) ??
+                RuntimeTaskId.make(event.data.toolCallId),
+              description: trimToUndefined(event.data.agentDescription),
+              taskType: "subagent",
             },
-          ];
-        case "subagent.completed":
-          return [
-            {
-              ...base(),
-              type: "task.completed",
-              payload: {
-                taskId:
-                  toRuntimeTaskId(event.data.toolCallId) ??
-                  RuntimeTaskId.make(event.data.toolCallId),
-                status: "completed",
-                ...(trimToUndefined(event.data.agentDisplayName)
-                  ? { summary: event.data.agentDisplayName }
-                  : {}),
-              },
+          },
+        ];
+      case "subagent.completed":
+        return [
+          {
+            ...base(),
+            type: "task.completed",
+            payload: {
+              taskId:
+                toRuntimeTaskId(event.data.toolCallId) ??
+                RuntimeTaskId.make(event.data.toolCallId),
+              status: "completed",
+              ...(trimToUndefined(event.data.agentDisplayName)
+                ? { summary: event.data.agentDisplayName }
+                : {}),
             },
-          ];
-        case "subagent.failed":
-          return [
-            {
-              ...base(),
-              type: "task.completed",
-              payload: {
-                taskId:
-                  toRuntimeTaskId(event.data.toolCallId) ??
-                  RuntimeTaskId.make(event.data.toolCallId),
-                status: "failed",
-                ...(trimToUndefined(event.data.error) ? { summary: event.data.error } : {}),
-              },
+          },
+        ];
+      case "subagent.failed":
+        return [
+          {
+            ...base(),
+            type: "task.completed",
+            payload: {
+              taskId:
+                toRuntimeTaskId(event.data.toolCallId) ??
+                RuntimeTaskId.make(event.data.toolCallId),
+              status: "failed",
+              ...(trimToUndefined(event.data.error) ? { summary: event.data.error } : {}),
             },
-          ];
-        default:
-          return [];
-      }
-    };
+          },
+        ];
+      default:
+        return [];
+    }
+  };
 
-    const createInteractionHandlers = (
-      threadId: ThreadId,
-      getCurrentTurnId: () => TurnId | undefined,
-      getRuntimeMode: () => ProviderSession["runtimeMode"],
-      pendingApprovalResolvers: Map<string, PendingApprovalRequest>,
-      pendingUserInputResolvers: Map<string, PendingUserInputRequest>,
-    ) => {
-      const onPermissionRequest = (request: PermissionRequest) =>
-        getRuntimeMode() === "full-access"
-          ? Promise.resolve<PermissionRequestResult>({ kind: "approved" })
-          : new Promise<PermissionRequestResult>((resolve) => {
-              const requestId = `copilot-approval-${randomUUID()}`;
-              const turnId = getCurrentTurnId();
-              pendingApprovalResolvers.set(requestId, {
-                requestType: requestTypeFromPermissionRequest(request),
-                turnId,
-                resolve,
-              });
-              void emitRuntimeEvents([
-                makeSyntheticEvent(
-                  threadId,
-                  "request.opened",
-                  {
-                    requestType: requestTypeFromPermissionRequest(request),
-                    ...(requestDetailFromPermissionRequest(request)
-                      ? { detail: requestDetailFromPermissionRequest(request) }
-                      : {}),
-                    args: request,
-                  },
-                  { requestId, turnId },
-                ),
-              ]);
+  const createInteractionHandlers = (
+    threadId: ThreadId,
+    getCurrentTurnId: () => TurnId | undefined,
+    getRuntimeMode: () => ProviderSession["runtimeMode"],
+    pendingApprovalResolvers: Map<string, PendingApprovalRequest>,
+    pendingUserInputResolvers: Map<string, PendingUserInputRequest>,
+  ) => {
+    const onPermissionRequest = (request: PermissionRequest) =>
+      getRuntimeMode() === "full-access"
+        ? Promise.resolve<PermissionRequestResult>({ kind: "approved" })
+        : new Promise<PermissionRequestResult>((resolve) => {
+            const requestId = `copilot-approval-${randomUUID()}`;
+            const turnId = getCurrentTurnId();
+            pendingApprovalResolvers.set(requestId, {
+              requestType: requestTypeFromPermissionRequest(request),
+              turnId,
+              resolve,
             });
-
-      const onUserInputRequest = (request: CopilotUserInputRequest) =>
-        new Promise<CopilotUserInputResponse>((resolve) => {
-          const requestId = `copilot-user-input-${randomUUID()}`;
-          const turnId = getCurrentTurnId();
-          pendingUserInputResolvers.set(requestId, {
-            request,
-            turnId,
-            resolve,
+            void emitRuntimeEvents([
+              makeSyntheticEvent(
+                threadId,
+                "request.opened",
+                {
+                  requestType: requestTypeFromPermissionRequest(request),
+                  ...(requestDetailFromPermissionRequest(request)
+                    ? { detail: requestDetailFromPermissionRequest(request) }
+                    : {}),
+                  args: request,
+                },
+                { requestId, turnId },
+              ),
+            ]);
           });
-          void emitRuntimeEvents([
-            makeSyntheticEvent(
-              threadId,
-              "user-input.requested",
-              {
-                questions: [
-                  {
-                    id: USER_INPUT_QUESTION_ID,
-                    header: USER_INPUT_QUESTION_HEADER,
-                    question: request.question,
-                    options: (request.choices ?? []).map((choice: string) => ({
-                      label: choice,
-                      description: choice,
-                    })),
-                  },
-                ],
-              },
-              { requestId, turnId },
-            ),
-          ]);
+
+    const onUserInputRequest = (request: CopilotUserInputRequest) =>
+      new Promise<CopilotUserInputResponse>((resolve) => {
+        const requestId = `copilot-user-input-${randomUUID()}`;
+        const turnId = getCurrentTurnId();
+        pendingUserInputResolvers.set(requestId, {
+          request,
+          turnId,
+          resolve,
         });
+        void emitRuntimeEvents([
+          makeSyntheticEvent(
+            threadId,
+            "user-input.requested",
+            {
+              questions: [
+                {
+                  id: USER_INPUT_QUESTION_ID,
+                  header: USER_INPUT_QUESTION_HEADER,
+                  question: request.question,
+                  options: (request.choices ?? []).map((choice: string) => ({
+                    label: choice,
+                    description: choice,
+                  })),
+                },
+              ],
+            },
+            { requestId, turnId },
+          ),
+        ]);
+      });
 
-      return {
-        onPermissionRequest,
-        onUserInputRequest,
-      };
+    return {
+      onPermissionRequest,
+      onUserInputRequest,
     };
+  };
 
-    const validateSessionConfiguration = (input: {
-      readonly client: CopilotClientHandle;
-      readonly threadId: ThreadId;
-      readonly model: string | undefined;
-      readonly reasoningEffort: CodexReasoningEffort | undefined;
-    }) =>
-      Effect.gen(function* () {
-        if (!input.model && !input.reasoningEffort) {
-          return;
-        }
+  const validateSessionConfiguration = (input: {
+    readonly client: CopilotClientHandle;
+    readonly threadId: ThreadId;
+    readonly model: string | undefined;
+    readonly reasoningEffort: CopilotReasoningEffort | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!input.model && !input.reasoningEffort) {
+        return;
+      }
+
+      yield* Effect.tryPromise({
+        try: () => withSanitizedCopilotDesktopEnv(() => input.client.start()),
+        catch: (cause) =>
+          new ProviderAdapterProcessError({
+            provider: PROVIDER,
+            threadId: input.threadId,
+            detail: toMessage(cause, "Failed to start GitHub Copilot client."),
+            cause,
+          }),
+      });
 
+      const supportedModels = mapSupportedModelsById(
         yield* Effect.tryPromise({
-          try: () => withSanitizedCopilotDesktopEnv(() => input.client.start()),
+          try: () => withSanitizedCopilotDesktopEnv(() => input.client.listModels()),
           catch: (cause) =>
             new ProviderAdapterProcessError({
               provider: PROVIDER,
               threadId: input.threadId,
-              detail: toMessage(cause, "Failed to start GitHub Copilot client."),
+              detail: toMessage(cause, "Failed to load GitHub Copilot model metadata."),
               cause,
             }),
+        }),
+      );
+      const selectedModel = input.model ? supportedModels.get(input.model) : undefined;
+
+      if (input.model && !selectedModel) {
+        return yield* new ProviderAdapterValidationError({
+          provider: PROVIDER,
+          operation: "session.model",
+          issue: `GitHub Copilot model '${input.model}' is not available in the current Copilot runtime.`,
         });
+      }
 
-        const supportedModels = mapSupportedModelsById(
-          yield* Effect.tryPromise({
-            try: () => withSanitizedCopilotDesktopEnv(() => input.client.listModels()),
-            catch: (cause) =>
-              new ProviderAdapterProcessError({
-                provider: PROVIDER,
-                threadId: input.threadId,
-                detail: toMessage(cause, "Failed to load GitHub Copilot model metadata."),
-                cause,
-              }),
-          }),
-        );
-        const selectedModel = input.model ? supportedModels.get(input.model) : undefined;
+      if (!input.reasoningEffort) {
+        return;
+      }
 
-        if (input.model && !selectedModel) {
-          return yield* new ProviderAdapterValidationError({
-            provider: PROVIDER,
-            operation: "session.model",
-            issue: `GitHub Copilot model '${input.model}' is not available in the current Copilot runtime.`,
-          });
-        }
+      if (!selectedModel) {
+        return yield* new ProviderAdapterValidationError({
+          provider: PROVIDER,
+          operation: "session.reasoningEffort",
+          issue:
+            "GitHub Copilot reasoning effort requires an explicit supported model selection.",
+        });
+      }
 
-        if (!input.reasoningEffort) {
-          return;
-        }
+      const supportedReasoningEfforts = selectedModel.supportedReasoningEfforts ?? [];
+      if (supportedReasoningEfforts.length === 0) {
+        return yield* new ProviderAdapterValidationError({
+          provider: PROVIDER,
+          operation: "session.reasoningEffort",
+          issue: `GitHub Copilot model '${selectedModel.id}' does not support reasoning effort configuration.`,
+        });
+      }
 
-        if (!selectedModel) {
-          return yield* new ProviderAdapterValidationError({
-            provider: PROVIDER,
-            operation: "session.reasoningEffort",
-            issue:
-              "GitHub Copilot reasoning effort requires an explicit supported model selection.",
-          });
-        }
+      if (!supportedReasoningEfforts.includes(input.reasoningEffort)) {
+        return yield* new ProviderAdapterValidationError({
+          provider: PROVIDER,
+          operation: "session.reasoningEffort",
+          issue: `GitHub Copilot model '${selectedModel.id}' does not support reasoning effort '${input.reasoningEffort}'.`,
+        });
+      }
+    });
 
-        const supportedReasoningEfforts = selectedModel.supportedReasoningEfforts ?? [];
-        if (supportedReasoningEfforts.length === 0) {
-          return yield* new ProviderAdapterValidationError({
-            provider: PROVIDER,
-            operation: "session.reasoningEffort",
-            issue: `GitHub Copilot model '${selectedModel.id}' does not support reasoning effort configuration.`,
-          });
+  const reconfigureSession = (
+    record: ActiveCopilotSession,
+    input: {
+      readonly model: string | undefined;
+      readonly reasoningEffort: CopilotReasoningEffort | undefined;
+    },
+  ) =>
+    Effect.tryPromise({
+      try: async () => {
+        const sessionId = record.session.sessionId;
+        const previousSession = record.session;
+        const previousUnsubscribe = record.unsubscribe;
+        previousUnsubscribe();
+        // Best-effort teardown -- must not block new session creation
+        try {
+          await previousSession.destroy();
+        } catch {
+          // ignored
         }
 
-        if (!supportedReasoningEfforts.includes(input.reasoningEffort)) {
-          return yield* new ProviderAdapterValidationError({
-            provider: PROVIDER,
-            operation: "session.reasoningEffort",
-            issue: `GitHub Copilot model '${selectedModel.id}' does not support reasoning effort '${input.reasoningEffort}'.`,
-          });
-        }
-      });
+        const handlers = createInteractionHandlers(
+          record.threadId,
+          () => record.currentTurnId,
+          () => record.runtimeMode,
+          record.pendingApprovalResolvers,
+          record.pendingUserInputResolvers,
+        );
+        const nextSession = await withSanitizedCopilotDesktopEnv(() =>
+          record.client.resumeSession(sessionId, {
+            ...handlers,
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
+            ...(record.cwd ? { workingDirectory: record.cwd } : {}),
+            ...(record.configDir ? { configDir: record.configDir } : {}),
+            streaming: true,
+          }),
+        );
 
-    const reconfigureSession = (
-      record: ActiveCopilotSession,
-      input: {
-        readonly model: string | undefined;
-        readonly reasoningEffort: CodexReasoningEffort | undefined;
+        record.session = nextSession;
+        record.interactionMode = undefined;
+        record.model = input.model;
+        record.reasoningEffort = input.reasoningEffort;
+        record.updatedAt = new Date().toISOString();
+        record.unsubscribe = nextSession.on((event) => {
+          handleSessionEvent(record, event);
+        });
       },
-    ) =>
-      Effect.tryPromise({
-        try: async () => {
-          const sessionId = record.session.sessionId;
-          const previousSession = record.session;
-          const previousUnsubscribe = record.unsubscribe;
-          previousUnsubscribe();
-          // Best-effort teardown -- must not block new session creation
-          try {
-            await previousSession.destroy();
-          } catch {
-            // ignored
-          }
+      catch: (cause) =>
+        new ProviderAdapterRequestError({
+          provider: PROVIDER,
+          method: "session.reconfigure",
+          detail: toMessage(cause, "Failed to reconfigure GitHub Copilot session."),
+          cause,
+        }),
+    });
 
-          const handlers = createInteractionHandlers(
-            record.threadId,
-            () => record.currentTurnId,
-            () => record.runtimeMode,
-            record.pendingApprovalResolvers,
-            record.pendingUserInputResolvers,
-          );
-          const nextSession = await withSanitizedCopilotDesktopEnv(() =>
-            record.client.resumeSession(sessionId, {
-              ...handlers,
-              ...(input.model ? { model: input.model } : {}),
-              ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
-              ...(record.cwd ? { workingDirectory: record.cwd } : {}),
-              ...(record.configDir ? { configDir: record.configDir } : {}),
-              streaming: true,
-            }),
-          );
+  const handleSessionEvent = (record: ActiveCopilotSession, event: SessionEvent) => {
+    record.updatedAt = event.timestamp;
+    if (event.type === "assistant.turn_start") {
+      beginCopilotTurn(record, TurnId.make(event.data.turnId));
+    }
+    if (event.type === "assistant.usage") {
+      recordTurnUsage(record, event.data);
+    }
+    if (event.type === "session.error") {
+      record.lastError = event.data.message;
+    }
+    if (event.type === "session.model_change") {
+      record.model = event.data.newModel;
+    }
+    if (event.type === "session.mode_changed") {
+      record.interactionMode = toInteractionMode(event.data.newMode);
+    }
+    if (event.type === "tool.execution_start" && trimToUndefined(event.data.toolName)) {
+      record.toolTitlesByCallId.set(event.data.toolCallId, trimToUndefined(event.data.toolName)!);
+    }
 
-          record.session = nextSession;
-          record.interactionMode = undefined;
-          record.model = input.model;
-          record.reasoningEffort = input.reasoningEffort;
-          record.updatedAt = new Date().toISOString();
-          record.unsubscribe = nextSession.on((event) => {
-            handleSessionEvent(record, event);
-          });
-        },
-        catch: (cause) =>
-          new ProviderAdapterRequestError({
-            provider: PROVIDER,
-            method: "session.reconfigure",
-            detail: toMessage(cause, "Failed to reconfigure GitHub Copilot session."),
-            cause,
-          }),
+    void writeNativeEvent(record.threadId, event);
+    const runtimeEvents = mapSessionEvent(record, event);
+    if (runtimeEvents.length > 0) {
+      void emitRuntimeEvents(runtimeEvents);
+    }
+    if (event.type === "session.plan_changed" && event.data.operation !== "delete") {
+      void Effect.runPromise(emitLatestProposedPlan(record)).catch((cause) => {
+        void emitRuntimeEvents([
+          makeSyntheticEvent(
+            record.threadId,
+            "runtime.warning",
+            {
+              message: "Failed to read GitHub Copilot plan.",
+              detail: toMessage(cause, "Failed to read GitHub Copilot plan."),
+            },
+            { turnId: currentSyntheticTurnId(record) },
+          ),
+        ]);
       });
+    }
+    if (event.type === "tool.execution_complete") {
+      record.toolTitlesByCallId.delete(event.data.toolCallId);
+    }
+    if (event.type === "assistant.turn_end") {
+      markTurnAwaitingCompletion(record);
+    }
+    if (event.type === "abort" || event.type === "session.idle") {
+      clearTurnTracking(record);
+    }
+  };
 
-    const handleSessionEvent = (record: ActiveCopilotSession, event: SessionEvent) => {
-      record.updatedAt = event.timestamp;
-      if (event.type === "assistant.turn_start") {
-        beginCopilotTurn(record, TurnId.make(event.data.turnId));
-      }
-      if (event.type === "assistant.usage") {
-        recordTurnUsage(record, event.data);
-      }
-      if (event.type === "session.error") {
-        record.lastError = event.data.message;
-      }
-      if (event.type === "session.model_change") {
-        record.model = event.data.newModel;
-      }
-      if (event.type === "session.mode_changed") {
-        record.interactionMode = toInteractionMode(event.data.newMode);
-      }
-      if (event.type === "tool.execution_start" && trimToUndefined(event.data.toolName)) {
-        record.toolTitlesByCallId.set(event.data.toolCallId, trimToUndefined(event.data.toolName)!);
-      }
-
-      void writeNativeEvent(record.threadId, event);
-      const runtimeEvents = mapSessionEvent(record, event);
-      if (runtimeEvents.length > 0) {
-        void emitRuntimeEvents(runtimeEvents);
-      }
-      if (event.type === "session.plan_changed" && event.data.operation !== "delete") {
-        void Effect.runPromise(emitLatestProposedPlan(record)).catch((cause) => {
-          void emitRuntimeEvents([
-            makeSyntheticEvent(
-              record.threadId,
-              "runtime.warning",
-              {
-                message: "Failed to read GitHub Copilot plan.",
-                detail: toMessage(cause, "Failed to read GitHub Copilot plan."),
-              },
-              { turnId: currentSyntheticTurnId(record) },
-            ),
-          ]);
-        });
-      }
-      if (event.type === "tool.execution_complete") {
-        record.toolTitlesByCallId.delete(event.data.toolCallId);
-      }
-      if (event.type === "assistant.turn_end") {
-        markTurnAwaitingCompletion(record);
-      }
-      if (event.type === "abort" || event.type === "session.idle") {
-        clearTurnTracking(record);
-      }
-    };
+  const getSessionRecord = (threadId: ThreadId) => {
+    const record = sessions.get(threadId);
+    if (!record) {
+      return Effect.fail(
+        new ProviderAdapterSessionNotFoundError({ provider: PROVIDER, threadId }),
+      );
+    }
+    return Effect.succeed(record);
+  };
 
-    const getSessionRecord = (threadId: ThreadId) => {
-      const record = sessions.get(threadId);
-      if (!record) {
-        return Effect.fail(
-          new ProviderAdapterSessionNotFoundError({ provider: PROVIDER, threadId }),
-        );
-      }
-      return Effect.succeed(record);
-    };
+  const stopRecord = async (record: ActiveCopilotSession) => {
+    record.unsubscribe();
+    try {
+      await record.session.destroy();
+    } catch {
+      // best effort
+    }
+    try {
+      await record.client.stop();
+    } catch {
+      // best effort
+    }
+    void emitRuntimeEvents([
+      makeSyntheticEvent(record.threadId, "session.exited", {
+        reason: "Session stopped",
+        exitKind: "graceful",
+      }),
+    ]);
+    for (const pending of record.pendingApprovalResolvers.values()) {
+      pending.resolve({ kind: "denied-interactively-by-user" });
+    }
+    record.pendingApprovalResolvers.clear();
+    for (const pending of record.pendingUserInputResolvers.values()) {
+      pending.resolve({ answer: "", wasFreeform: true });
+    }
+    record.pendingUserInputResolvers.clear();
+    sessions.delete(record.threadId);
+  };
 
-    const stopRecord = async (record: ActiveCopilotSession) => {
-      record.unsubscribe();
-      try {
-        await record.session.destroy();
-      } catch {
-        // best effort
-      }
-      try {
-        await record.client.stop();
-      } catch {
-        // best effort
-      }
-      void emitRuntimeEvents([
-        makeSyntheticEvent(record.threadId, "session.exited", {
-          reason: "Session stopped",
-          exitKind: "graceful",
-        }),
-      ]);
-      for (const pending of record.pendingApprovalResolvers.values()) {
-        pending.resolve({ kind: "denied-interactively-by-user" });
+  const startSession: CopilotAdapterShape["startSession"] = (input) =>
+    Effect.gen(function* () {
+      const existing = sessions.get(input.threadId);
+      if (existing) {
+        return {
+          provider: PROVIDER,
+          status: "ready",
+          runtimeMode: existing.runtimeMode,
+          ...(existing.cwd ? { cwd: existing.cwd } : {}),
+          ...(existing.model ? { model: existing.model } : {}),
+          threadId: input.threadId,
+          resumeCursor: existing.session.sessionId,
+          createdAt: existing.createdAt,
+          updatedAt: existing.updatedAt,
+          ...(existing.lastError ? { lastError: existing.lastError } : {}),
+        } satisfies ProviderSession;
       }
-      record.pendingApprovalResolvers.clear();
-      for (const pending of record.pendingUserInputResolvers.values()) {
-        pending.resolve({ answer: "", wasFreeform: true });
+      if (!copilotSettings.enabled) {
+        return yield* new ProviderAdapterValidationError({
+          provider: PROVIDER,
+          operation: "startSession",
+          issue: "GitHub Copilot provider is disabled in server settings.",
+        });
       }
-      record.pendingUserInputResolvers.clear();
-      sessions.delete(record.threadId);
-    };
-
-    /** Resolved CLI path from server settings; updated on each startSession call. */
-    let resolvedCliPath: string | undefined;
-
-    const startSession: CopilotAdapterShape["startSession"] = (input) =>
-      Effect.gen(function* () {
-        if (input.provider !== undefined && input.provider !== PROVIDER) {
-          return yield* new ProviderAdapterValidationError({
-            provider: PROVIDER,
-            operation: "startSession",
-            issue: `Expected provider '${PROVIDER}', received '${input.provider}'.`,
-          });
-        }
-
-        const copilotSettings = yield* serverSettingsService.getSettings.pipe(
-          Effect.map((s) => s.providers.copilot),
-          Effect.mapError(
-            (error) =>
-              new ProviderAdapterProcessError({
-                provider: PROVIDER,
-                threadId: input.threadId,
-                detail: error.message,
-                cause: error,
-              }),
-          ),
-        );
-        const existing = sessions.get(input.threadId);
-        if (existing) {
-          return {
-            provider: PROVIDER,
-            status: "ready",
-            runtimeMode: existing.runtimeMode,
-            ...(existing.cwd ? { cwd: existing.cwd } : {}),
-            ...(existing.model ? { model: existing.model } : {}),
-            threadId: input.threadId,
-            resumeCursor: existing.session.sessionId,
-            createdAt: existing.createdAt,
-            updatedAt: existing.updatedAt,
-            ...(existing.lastError ? { lastError: existing.lastError } : {}),
-          } satisfies ProviderSession;
-        }
-        if (!copilotSettings.enabled) {
-          return yield* new ProviderAdapterValidationError({
-            provider: PROVIDER,
-            operation: "startSession",
-            issue: "Copilot provider is disabled in server settings.",
-          });
-        }
-        const settingsBinaryPath = copilotSettings.binaryPath.trim();
-        const cliPath = settingsBinaryPath || resolveBundledCopilotCliPath();
-        resolvedCliPath = cliPath;
-        const configDir = trimToUndefined(copilotSettings.configDir);
-        const resumeSessionId = extractResumeSessionId(input.resumeCursor);
-        const clientOptions: CopilotClientOptions = {
-          ...(cliPath ? { cliPath } : {}),
-          ...(input.cwd ? { cwd: input.cwd } : {}),
-          logLevel: "error",
-        };
-        const { CopilotClient } = yield* Effect.promise(() => import("@github/copilot-sdk"));
-        const client = options?.clientFactory?.(clientOptions) ?? new CopilotClient(clientOptions);
-        const pendingApprovalResolvers = new Map<string, PendingApprovalRequest>();
-        const pendingUserInputResolvers = new Map<string, PendingUserInputRequest>();
-        const copilotOptions =
-          input.modelSelection?.provider === "copilot" ? input.modelSelection.options : undefined;
-        const model = input.modelSelection?.model;
-        const reasoningEffort = getCopilotReasoningEffort(copilotOptions);
-        let sessionRecord: ActiveCopilotSession | undefined;
-        const handlers = createInteractionHandlers(
-          input.threadId,
-          () => sessionRecord?.currentTurnId,
-          () => sessionRecord?.runtimeMode ?? input.runtimeMode,
-          pendingApprovalResolvers,
-          pendingUserInputResolvers,
-        );
+      const settingsBinaryPath = copilotSettings.binaryPath.trim();
+      const cliPath = settingsBinaryPath || resolveBundledCopilotCliPath();
+      const configDir = trimToUndefined(copilotSettings.configDir);
+      const resumeSessionId = extractResumeSessionId(input.resumeCursor);
+      const clientOptions: CopilotClientOptions = {
+        ...(cliPath ? { cliPath } : {}),
+        ...(input.cwd ? { cwd: input.cwd } : {}),
+        logLevel: "error",
+      };
+      const { CopilotClient } = yield* Effect.promise(() => import("@github/copilot-sdk"));
+      const client = options?.clientFactory?.(clientOptions) ?? new CopilotClient(clientOptions);
+      const pendingApprovalResolvers = new Map<string, PendingApprovalRequest>();
+      const pendingUserInputResolvers = new Map<string, PendingUserInputRequest>();
+      const model = input.modelSelection?.model;
+      const reasoningEffort = getCopilotReasoningEffort(input.modelSelection?.options);
+      let sessionRecord: ActiveCopilotSession | undefined;
+      const handlers = createInteractionHandlers(
+        input.threadId,
+        () => sessionRecord?.currentTurnId,
+        () => sessionRecord?.runtimeMode ?? input.runtimeMode,
+        pendingApprovalResolvers,
+        pendingUserInputResolvers,
+      );
 
-        yield* validateSessionConfiguration({
-          client,
-          threadId: input.threadId,
-          model,
-          reasoningEffort,
-        });
+      yield* validateSessionConfiguration({
+        client,
+        threadId: input.threadId,
+        model,
+        reasoningEffort,
+      });
 
-        const session = yield* Effect.tryPromise({
-          try: async () => {
-            if (resumeSessionId) {
-              return withSanitizedCopilotDesktopEnv(() =>
-                client.resumeSession(resumeSessionId, {
-                  ...handlers,
-                  ...(model ? { model } : {}),
-                  ...(reasoningEffort ? { reasoningEffort } : {}),
-                  ...(input.cwd ? { workingDirectory: input.cwd } : {}),
-                  ...(configDir ? { configDir } : {}),
-                  streaming: true,
-                }),
-              );
-            }
+      const session = yield* Effect.tryPromise({
+        try: async () => {
+          if (resumeSessionId) {
             return withSanitizedCopilotDesktopEnv(() =>
-              client.createSession({
+              client.resumeSession(resumeSessionId, {
                 ...handlers,
                 ...(model ? { model } : {}),
                 ...(reasoningEffort ? { reasoningEffort } : {}),
@@ -1357,356 +1412,404 @@ const makeCopilotAdapter = (options?: CopilotAdapterLiveOptions) =>
                 streaming: true,
               }),
             );
-          },
-          catch: (cause) =>
-            new ProviderAdapterProcessError({
-              provider: PROVIDER,
-              threadId: input.threadId,
-              detail: toMessage(cause, "Failed to start GitHub Copilot session."),
-              cause,
-            }),
-        }).pipe(Effect.tapError(() => Effect.promise(() => client.stop().catch(() => undefined))));
-
-        const record = createSessionRecord({
-          threadId: input.threadId,
-          client,
-          session,
-          runtimeMode: input.runtimeMode,
-          pendingApprovalResolvers,
-          pendingUserInputResolvers,
-          cwd: input.cwd,
-          configDir,
-          model,
-          reasoningEffort,
-        });
-        const unsubscribe = session.on((event: unknown) => {
-          handleSessionEvent(record, event);
-        });
-        record.unsubscribe = unsubscribe;
-        sessionRecord = record;
-        sessions.set(input.threadId, record);
-
-        yield* Queue.offerAll(runtimeEventQueue, [
-          makeSyntheticEvent(input.threadId, "session.started", {
-            message: resumeSessionId
-              ? "Resumed GitHub Copilot session"
-              : "Started GitHub Copilot session",
-            resume: { sessionId: session.sessionId },
-          }),
-          makeSyntheticEvent(input.threadId, "session.configured", {
-            config: {
-              ...(input.cwd ? { cwd: input.cwd } : {}),
+          }
+          return withSanitizedCopilotDesktopEnv(() =>
+            client.createSession({
+              ...handlers,
               ...(model ? { model } : {}),
               ...(reasoningEffort ? { reasoningEffort } : {}),
+              ...(input.cwd ? { workingDirectory: input.cwd } : {}),
               ...(configDir ? { configDir } : {}),
               streaming: true,
-            },
-          }),
-          makeSyntheticEvent(input.threadId, "thread.started", {
-            providerThreadId: session.sessionId,
-          }),
-          makeSyntheticEvent(input.threadId, "session.state.changed", {
-            state: "ready",
-            reason: "session.started",
+            }),
+          );
+        },
+        catch: (cause) =>
+          new ProviderAdapterProcessError({
+            provider: PROVIDER,
+            threadId: input.threadId,
+            detail: toMessage(cause, "Failed to start GitHub Copilot session."),
+            cause,
           }),
-        ]);
-
-        return {
-          provider: PROVIDER,
-          status: "ready",
-          runtimeMode: input.runtimeMode,
-          ...(input.cwd ? { cwd: input.cwd } : {}),
-          ...(model ? { model } : {}),
-          threadId: input.threadId,
-          resumeCursor: session.sessionId,
-          createdAt: record.createdAt,
-          updatedAt: record.updatedAt,
-        } satisfies ProviderSession;
+      }).pipe(Effect.tapError(() => Effect.promise(() => client.stop().catch(() => undefined))));
+
+      const record = createSessionRecord({
+        threadId: input.threadId,
+        client,
+        session,
+        runtimeMode: input.runtimeMode,
+        pendingApprovalResolvers,
+        pendingUserInputResolvers,
+        cwd: input.cwd,
+        configDir,
+        model,
+        reasoningEffort,
       });
+      const unsubscribe = session.on((event: unknown) => {
+        handleSessionEvent(record, event as SessionEvent);
+      });
+      record.unsubscribe = unsubscribe;
+      sessionRecord = record;
+      sessions.set(input.threadId, record);
+
+      yield* Queue.offerAll(runtimeEventQueue, [
+        makeSyntheticEvent(input.threadId, "session.started", {
+          message: resumeSessionId
+            ? "Resumed GitHub Copilot session"
+            : "Started GitHub Copilot session",
+          resume: { sessionId: session.sessionId },
+        }),
+        makeSyntheticEvent(input.threadId, "session.configured", {
+          config: {
+            ...(input.cwd ? { cwd: input.cwd } : {}),
+            ...(model ? { model } : {}),
+            ...(reasoningEffort ? { reasoningEffort } : {}),
+            ...(configDir ? { configDir } : {}),
+            streaming: true,
+          },
+        }),
+        makeSyntheticEvent(input.threadId, "thread.started", {
+          providerThreadId: session.sessionId,
+        }),
+        makeSyntheticEvent(input.threadId, "session.state.changed", {
+          state: "ready",
+          reason: "session.started",
+        }),
+      ]);
 
-    const sendTurn: CopilotAdapterShape["sendTurn"] = (input) =>
-      Effect.gen(function* () {
-        const record = yield* getSessionRecord(input.threadId);
-        const turnCopilotOptions =
-          input.modelSelection?.provider === "copilot" ? input.modelSelection.options : undefined;
-        const turnModel = input.modelSelection?.model;
-        const explicitReasoningEffort = getCopilotReasoningEffort(turnCopilotOptions);
-        const nextModel = turnModel ?? record.model;
-        const nextReasoningEffort =
-          explicitReasoningEffort !== undefined
-            ? explicitReasoningEffort
-            : turnModel && turnModel !== record.model
-              ? undefined
-              : record.reasoningEffort;
-        const attachments = yield* Effect.forEach(input.attachments ?? [], (attachment) => {
-          const attachmentPath = resolveAttachmentPath({
-            attachmentsDir: serverConfig.attachmentsDir,
-            attachment,
-          });
-          if (!attachmentPath) {
-            return Effect.fail(
-              new ProviderAdapterRequestError({
-                provider: PROVIDER,
-                method: "session.send",
-                detail: `Invalid attachment id '${attachment.id}'.`,
-              }),
-            );
-          }
-          return Effect.succeed({
-            type: "file" as const,
-            path: attachmentPath,
-            displayName: attachment.name,
-          });
-        });
+      return {
+        provider: PROVIDER,
+        status: "ready",
+        runtimeMode: input.runtimeMode,
+        ...(input.cwd ? { cwd: input.cwd } : {}),
+        ...(model ? { model } : {}),
+        threadId: input.threadId,
+        resumeCursor: session.sessionId,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+      } satisfies ProviderSession;
+    });
 
-        yield* validateSessionConfiguration({
-          client: record.client,
-          threadId: input.threadId,
-          model: nextModel,
-          reasoningEffort: nextReasoningEffort,
+  const sendTurn: CopilotAdapterShape["sendTurn"] = (input) =>
+    Effect.gen(function* () {
+      const record = yield* getSessionRecord(input.threadId);
+      const turnModel = input.modelSelection?.model;
+      const explicitReasoningEffort = getCopilotReasoningEffort(input.modelSelection?.options);
+      const nextModel = turnModel ?? record.model;
+      const nextReasoningEffort =
+        explicitReasoningEffort !== undefined
+          ? explicitReasoningEffort
+          : turnModel && turnModel !== record.model
+            ? undefined
+            : record.reasoningEffort;
+      const attachments = yield* Effect.forEach(input.attachments ?? [], (attachment) => {
+        const attachmentPath = resolveAttachmentPath({
+          attachmentsDir: serverConfig.attachmentsDir,
+          attachment,
         });
-
-        if (nextModel !== record.model || nextReasoningEffort !== record.reasoningEffort) {
-          yield* reconfigureSession(record, {
-            model: nextModel,
-            reasoningEffort: nextReasoningEffort,
-          });
-        }
-
-        const interactionMode = input.interactionMode ?? record.interactionMode ?? "default";
-        yield* syncInteractionMode(record, interactionMode);
-
-        const turnId = TurnId.make(`copilot-turn-${randomUUID()}`);
-        record.pendingTurnIds.push(turnId);
-        record.currentTurnId = turnId;
-        record.currentProviderTurnId = undefined;
-
-        yield* Effect.tryPromise({
-          try: () =>
-            record.session.send({
-              prompt: input.input ?? "",
-              ...(attachments.length > 0 ? { attachments } : {}),
-              mode: "immediate",
-            }),
-          catch: (cause) =>
+        if (!attachmentPath) {
+          return Effect.fail(
             new ProviderAdapterRequestError({
               provider: PROVIDER,
               method: "session.send",
-              detail: toMessage(cause, "Failed to send GitHub Copilot turn."),
-              cause,
-            }),
-        }).pipe(
-          Effect.tapError(() =>
-            Effect.sync(() => {
-              record.pendingTurnIds = record.pendingTurnIds.filter(
-                (candidate) => candidate !== turnId,
-              );
-              if (record.currentTurnId === turnId) {
-                record.currentTurnId = undefined;
-              }
+              detail: `Invalid attachment id '${attachment.id}'.`,
             }),
-          ),
-        );
-
-        record.updatedAt = new Date().toISOString();
+          );
+        }
+        return Effect.succeed({
+          type: "file" as const,
+          path: attachmentPath,
+          displayName: attachment.name,
+        });
+      });
 
-        return {
-          threadId: input.threadId,
-          turnId,
-          resumeCursor: record.session.sessionId,
-        } satisfies ProviderTurnStartResult;
+      yield* validateSessionConfiguration({
+        client: record.client,
+        threadId: input.threadId,
+        model: nextModel,
+        reasoningEffort: nextReasoningEffort,
       });
 
-    const interruptTurn: CopilotAdapterShape["interruptTurn"] = (threadId) =>
-      Effect.gen(function* () {
-        const record = yield* getSessionRecord(threadId);
-        yield* Effect.tryPromise({
-          try: () => record.session.abort(),
-          catch: (cause) =>
-            new ProviderAdapterRequestError({
-              provider: PROVIDER,
-              method: "session.abort",
-              detail: toMessage(cause, "Failed to interrupt GitHub Copilot turn."),
-              cause,
-            }),
+      if (nextModel !== record.model || nextReasoningEffort !== record.reasoningEffort) {
+        yield* reconfigureSession(record, {
+          model: nextModel,
+          reasoningEffort: nextReasoningEffort,
         });
-      });
+      }
 
-    const respondToRequest: CopilotAdapterShape["respondToRequest"] = (
-      threadId,
-      requestId,
-      decision,
-    ) =>
-      Effect.gen(function* () {
-        const record = yield* getSessionRecord(threadId);
-        const pending = record.pendingApprovalResolvers.get(requestId);
-        if (!pending) {
-          return yield* new ProviderAdapterRequestError({
+      const interactionMode = input.interactionMode ?? record.interactionMode ?? "default";
+      yield* syncInteractionMode(record, interactionMode);
+
+      const turnId = TurnId.make(`copilot-turn-${randomUUID()}`);
+      record.pendingTurnIds.push(turnId);
+      record.currentTurnId = turnId;
+      record.currentProviderTurnId = undefined;
+
+      yield* Effect.tryPromise({
+        try: () =>
+          record.session.send({
+            prompt: input.input ?? "",
+            ...(attachments.length > 0 ? { attachments } : {}),
+            mode: "immediate",
+          }),
+        catch: (cause) =>
+          new ProviderAdapterRequestError({
             provider: PROVIDER,
-            method: "session.permission.respond",
-            detail: `Unknown pending GitHub Copilot approval request '${requestId}'.`,
-          });
-        }
-        record.pendingApprovalResolvers.delete(requestId);
-        pending.resolve(approvalDecisionToPermissionResult(decision));
-        yield* Queue.offer(
-          runtimeEventQueue,
-          makeSyntheticEvent(
-            threadId,
-            "request.resolved",
-            {
-              requestType: pending.requestType,
-              decision,
-              resolution: approvalDecisionToPermissionResult(decision),
-            },
-            { requestId, turnId: pending.turnId },
-          ),
-        );
-      });
+            method: "session.send",
+            detail: toMessage(cause, "Failed to send GitHub Copilot turn."),
+            cause,
+          }),
+      }).pipe(
+        Effect.tapError(() =>
+          Effect.sync(() => {
+            record.pendingTurnIds = record.pendingTurnIds.filter(
+              (candidate) => candidate !== turnId,
+            );
+            if (record.currentTurnId === turnId) {
+              record.currentTurnId = undefined;
+            }
+          }),
+        ),
+      );
 
-    const respondToUserInput: CopilotAdapterShape["respondToUserInput"] = (
-      threadId,
-      requestId,
-      answers,
-    ) =>
-      Effect.gen(function* () {
-        const record = yield* getSessionRecord(threadId);
-        const pending = record.pendingUserInputResolvers.get(requestId);
-        if (!pending) {
-          return yield* new ProviderAdapterRequestError({
+      record.updatedAt = new Date().toISOString();
+
+      return {
+        threadId: input.threadId,
+        turnId,
+        resumeCursor: record.session.sessionId,
+      } satisfies ProviderTurnStartResult;
+    });
+
+  const interruptTurn: CopilotAdapterShape["interruptTurn"] = (threadId) =>
+    Effect.gen(function* () {
+      const record = yield* getSessionRecord(threadId);
+      yield* Effect.tryPromise({
+        try: () => record.session.abort(),
+        catch: (cause) =>
+          new ProviderAdapterRequestError({
             provider: PROVIDER,
-            method: "session.userInput.respond",
-            detail: `Unknown pending GitHub Copilot user-input request '${requestId}'.`,
-          });
-        }
-        record.pendingUserInputResolvers.delete(requestId);
-        pending.resolve(resolveUserInputAnswer(pending, answers));
-        yield* Queue.offer(
-          runtimeEventQueue,
-          makeSyntheticEvent(
-            threadId,
-            "user-input.resolved",
-            {
-              answers,
-            },
-            { requestId, turnId: pending.turnId },
-          ),
-        );
+            method: "session.abort",
+            detail: toMessage(cause, "Failed to interrupt GitHub Copilot turn."),
+            cause,
+          }),
       });
+    });
 
-    const stopSession: CopilotAdapterShape["stopSession"] = (threadId) =>
-      Effect.gen(function* () {
-        const record = yield* getSessionRecord(threadId);
-        yield* Effect.tryPromise({
-          try: async () => {
-            await stopRecord(record);
-          },
-          catch: (cause) =>
-            new ProviderAdapterProcessError({
-              provider: PROVIDER,
-              threadId,
-              detail: toMessage(cause, "Failed to stop GitHub Copilot session."),
-              cause,
-            }),
+  const respondToRequest: CopilotAdapterShape["respondToRequest"] = (
+    threadId,
+    requestId,
+    decision,
+  ) =>
+    Effect.gen(function* () {
+      const record = yield* getSessionRecord(threadId);
+      const pending = record.pendingApprovalResolvers.get(requestId);
+      if (!pending) {
+        return yield* new ProviderAdapterRequestError({
+          provider: PROVIDER,
+          method: "session.permission.respond",
+          detail: `Unknown pending GitHub Copilot approval request '${requestId}'.`,
         });
-      });
-
-    const listSessions: CopilotAdapterShape["listSessions"] = () =>
-      Effect.sync(() =>
-        Array.from(sessions.values()).map((record) =>
-          Object.assign(
-            {
-              provider: PROVIDER,
-              status: record.currentTurnId ? "running" : "ready",
-              runtimeMode: record.runtimeMode,
-              threadId: record.threadId,
-              resumeCursor: record.session.sessionId,
-              createdAt: record.createdAt,
-              updatedAt: record.updatedAt,
-            } as ProviderSession,
-            record.cwd ? { cwd: record.cwd } : undefined,
-            record.model ? { model: record.model } : undefined,
-            record.currentTurnId ? { activeTurnId: record.currentTurnId } : undefined,
-            record.lastError ? { lastError: record.lastError } : undefined,
-          ),
+      }
+      record.pendingApprovalResolvers.delete(requestId);
+      pending.resolve(approvalDecisionToPermissionResult(decision));
+      yield* Queue.offer(
+        runtimeEventQueue,
+        makeSyntheticEvent(
+          threadId,
+          "request.resolved",
+          {
+            requestType: pending.requestType,
+            decision,
+            resolution: approvalDecisionToPermissionResult(decision),
+          },
+          { requestId, turnId: pending.turnId },
         ),
       );
+    });
 
-    const hasSession: CopilotAdapterShape["hasSession"] = (threadId) =>
-      Effect.sync(() => sessions.has(threadId));
-
-    const readThread: CopilotAdapterShape["readThread"] = (threadId) =>
-      Effect.gen(function* () {
-        const record = yield* getSessionRecord(threadId);
-        return yield* Effect.tryPromise({
-          try: async () => {
-            const messages = await record.session.getMessages();
-            return mapHistoryToTurns(threadId, messages);
-          },
-          catch: (cause) =>
-            new ProviderAdapterRequestError({
-              provider: PROVIDER,
-              method: "session.getMessages",
-              detail: toMessage(cause, "Failed to read GitHub Copilot thread history."),
-              cause,
-            }),
-        });
-      });
-
-    const rollbackThread: CopilotAdapterShape["rollbackThread"] = (_threadId) =>
-      Effect.fail(
-        new ProviderAdapterRequestError({
+  const respondToUserInput: CopilotAdapterShape["respondToUserInput"] = (
+    threadId,
+    requestId,
+    answers,
+  ) =>
+    Effect.gen(function* () {
+      const record = yield* getSessionRecord(threadId);
+      const pending = record.pendingUserInputResolvers.get(requestId);
+      if (!pending) {
+        return yield* new ProviderAdapterRequestError({
           provider: PROVIDER,
-          method: "thread.rollback",
-          detail:
-            "GitHub Copilot SDK does not expose a supported conversation rollback API for existing sessions.",
-        }),
+          method: "session.userInput.respond",
+          detail: `Unknown pending GitHub Copilot user-input request '${requestId}'.`,
+        });
+      }
+      record.pendingUserInputResolvers.delete(requestId);
+      pending.resolve(resolveUserInputAnswer(pending, answers));
+      yield* Queue.offer(
+        runtimeEventQueue,
+        makeSyntheticEvent(
+          threadId,
+          "user-input.resolved",
+          {
+            answers,
+          },
+          { requestId, turnId: pending.turnId },
+        ),
       );
+    });
 
-    const stopAll: CopilotAdapterShape["stopAll"] = () =>
-      Effect.tryPromise({
+  const stopSession: CopilotAdapterShape["stopSession"] = (threadId) =>
+    Effect.gen(function* () {
+      const record = yield* getSessionRecord(threadId);
+      yield* Effect.tryPromise({
         try: async () => {
-          await Promise.all(Array.from(sessions.values()).map((record) => stopRecord(record)));
+          await stopRecord(record);
         },
         catch: (cause) =>
           new ProviderAdapterProcessError({
             provider: PROVIDER,
-            threadId: ThreadId.make("_all"),
-            detail: toMessage(cause, "Failed to stop GitHub Copilot sessions."),
+            threadId,
+            detail: toMessage(cause, "Failed to stop GitHub Copilot session."),
             cause,
           }),
       });
+    });
 
-    yield* Effect.addFinalizer(() =>
-      Effect.forEach(
-        sessions,
-        ([, record]) => Effect.promise(() => stopRecord(record).catch(() => undefined)),
-        { discard: true },
-      ).pipe(Effect.tap(() => Queue.shutdown(runtimeEventQueue))),
+  const listSessions: CopilotAdapterShape["listSessions"] = () =>
+    Effect.sync(() =>
+      Array.from(sessions.values()).map((record) =>
+        Object.assign(
+          {
+            provider: PROVIDER,
+            status: record.currentTurnId ? "running" : "ready",
+            runtimeMode: record.runtimeMode,
+            threadId: record.threadId,
+            resumeCursor: record.session.sessionId,
+            createdAt: record.createdAt,
+            updatedAt: record.updatedAt,
+          } as ProviderSession,
+          record.cwd ? { cwd: record.cwd } : undefined,
+          record.model ? { model: record.model } : undefined,
+          record.currentTurnId ? { activeTurnId: record.currentTurnId } : undefined,
+          record.lastError ? { lastError: record.lastError } : undefined,
+        ),
+      ),
     );
 
-    return {
-      provider: PROVIDER,
-      capabilities: getProviderCapabilities(PROVIDER),
-      startSession,
-      sendTurn,
-      interruptTurn,
-      respondToRequest,
-      respondToUserInput,
-      stopSession,
-      listSessions,
-      hasSession,
-      readThread,
-      rollbackThread,
-      stopAll,
-      streamEvents: Stream.fromQueue(runtimeEventQueue),
-    } satisfies CopilotAdapterShape;
-  });
-
-export const CopilotAdapterLive = Layer.effect(CopilotAdapter, makeCopilotAdapter());
+  const hasSession: CopilotAdapterShape["hasSession"] = (threadId) =>
+    Effect.sync(() => sessions.has(threadId));
+
+  const readThread: CopilotAdapterShape["readThread"] = (threadId) =>
+    Effect.gen(function* () {
+      const record = yield* getSessionRecord(threadId);
+      return yield* Effect.tryPromise({
+        try: async () => {
+          const messages = await record.session.getMessages();
+          return mapHistoryToTurns(threadId, messages);
+        },
+        catch: (cause) =>
+          new ProviderAdapterRequestError({
+            provider: PROVIDER,
+            method: "session.getMessages",
+            detail: toMessage(cause, "Failed to read GitHub Copilot thread history."),
+            cause,
+          }),
+      });
+    });
+
+  const rollbackThread: CopilotAdapterShape["rollbackThread"] = (_threadId) =>
+    Effect.fail(
+      new ProviderAdapterRequestError({
+        provider: PROVIDER,
+        method: "thread.rollback",
+        detail:
+          "GitHub Copilot SDK does not expose a supported conversation rollback API for existing sessions.",
+      }),
+    );
+
+  const stopAll: CopilotAdapterShape["stopAll"] = () =>
+    Effect.tryPromise({
+      try: async () => {
+        await Promise.all(Array.from(sessions.values()).map((record) => stopRecord(record)));
+      },
+      catch: (cause) =>
+        new ProviderAdapterProcessError({
+          provider: PROVIDER,
+          threadId: ThreadId.make("_all"),
+          detail: toMessage(cause, "Failed to stop GitHub Copilot sessions."),
+          cause,
+        }),
+    });
 
+  yield* Effect.addFinalizer(() =>
+    Effect.forEach(
+      sessions,
+      ([, record]) => Effect.promise(() => stopRecord(record).catch(() => undefined)),
+      { discard: true },
+    ).pipe(Effect.tap(() => Queue.shutdown(runtimeEventQueue))),
+  );
+
+  return {
+    provider: PROVIDER,
+    capabilities: { sessionModelSwitch: "in-session" },
+    startSession,
+    sendTurn,
+    interruptTurn,
+    respondToRequest,
+    respondToUserInput,
+    stopSession,
+    listSessions,
+    hasSession,
+    readThread,
+    rollbackThread,
+    stopAll,
+    streamEvents: Stream.fromQueue(runtimeEventQueue),
+  } satisfies CopilotAdapterShape;
+});
+
+/**
+ * Back-compat Layer: binds `makeCopilotAdapter` to the legacy
+ * `CopilotAdapter` Service tag. Kept so the conformance test, the desktop
+ * boot graph, and any other consumers that still resolve adapters through
+ * Context can keep working until they migrate to driver-bundled instances.
+ *
+ * Reads `copilotSettings` from `ServerSettingsService` so the legacy
+ * single-instance path continues to follow the persisted server settings.
+ */
 export function makeCopilotAdapterLive(options?: CopilotAdapterLiveOptions) {
-  return Layer.effect(CopilotAdapter, makeCopilotAdapter(options));
+  return Layer.effect(
+    CopilotAdapter,
+    Effect.gen(function* () {
+      // Lazy-import to avoid a hard dependency on ServerSettingsService inside
+      // the per-instance `makeCopilotAdapter` factory (drivers pass typed
+      // config directly).
+      const { ServerSettingsService } = yield* Effect.promise(
+        () => import("../../serverSettings.ts"),
+      );
+      const serverSettingsService = yield* ServerSettingsService;
+      const settings = yield* serverSettingsService.getSettings.pipe(
+        Effect.map((s) => s.providers.copilot),
+        Effect.orElseSucceed(
+          () =>
+            ({
+              enabled: true,
+              binaryPath: "",
+              configDir: "",
+              customModels: [] as ReadonlyArray<string>,
+            }) as const,
+        ),
+      );
+      // The contracts schema is `GenericProviderSettings`; coerce its shape
+      // into our local `CopilotSettings` view (same fields).
+      const copilotSettings = {
+        enabled: settings.enabled,
+        binaryPath: settings.binaryPath,
+        configDir: settings.configDir,
+        customModels: settings.customModels,
+      } satisfies CopilotSettings;
+      return yield* makeCopilotAdapter(copilotSettings, options);
+    }),
+  );
 }
 
 // ── Dynamic model discovery & usage (consumed by wsServer) ─────────
@@ -1718,7 +1821,6 @@ export async function fetchCopilotModels(overrideCliPath?: string): Promise<Read
 }> | null> {
   try {
     const { CopilotClient } = await import("@github/copilot-sdk");
-    const { resolveBundledCopilotCliPath } = await import("./copilotCliPath.ts");
     const cliPath = overrideCliPath?.trim() || resolveBundledCopilotCliPath();
     const client = new CopilotClient({
       ...(cliPath ? { cliPath } : {}),
@@ -1756,7 +1858,6 @@ export async function fetchCopilotUsage(overrideCliPath?: string): Promise<{
 }> {
   try {
     const { CopilotClient } = await import("@github/copilot-sdk");
-    const { resolveBundledCopilotCliPath } = await import("./copilotCliPath.ts");
     const cliPath = overrideCliPath?.trim() || resolveBundledCopilotCliPath();
     const client = new CopilotClient({
       ...(cliPath ? { cliPath } : {}),
diff --git a/apps/server/src/provider/Layers/CopilotProvider.ts b/apps/server/src/provider/Layers/CopilotProvider.ts
new file mode 100644
index 00000000000..dc72eb4010a
--- /dev/null
+++ b/apps/server/src/provider/Layers/CopilotProvider.ts
@@ -0,0 +1,306 @@
+/**
+ * CopilotProvider — snapshot probe for the GitHub Copilot driver.
+ *
+ * Mirrors the shape of `ClaudeProvider` / `OpenCodeProvider`: exports a
+ * `checkCopilotProviderStatus` Effect that probes the resolved binary
+ * (version) and best-effort auth state via the Copilot SDK, plus a
+ * `makePendingCopilotProvider` snapshot used until the first probe lands.
+ *
+ * The probe purposefully tolerates failure — Copilot is often optional and
+ * a missing CLI / unauthenticated SDK should still produce a valid (but
+ * not-ready) snapshot rather than tear the driver down.
+ */
+import {
+  type ModelCapabilities,
+  ProviderDriverKind,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
+import { Data, Effect, Option, Result } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { createModelCapabilities } from "@t3tools/shared/model";
+
+import {
+  buildServerProvider,
+  DEFAULT_TIMEOUT_MS,
+  detailFromResult,
+  isCommandMissingCause,
+  parseGenericCliVersion,
+  providerModelsFromSettings,
+  spawnAndCollect,
+  type ServerProviderDraft,
+} from "../providerSnapshot.ts";
+import {
+  resolveBundledCopilotCliPath,
+  withSanitizedCopilotDesktopEnv,
+} from "./copilotCliPath.ts";
+import type { CopilotSettings } from "../Drivers/CopilotSettings.ts";
+
+const PROVIDER = ProviderDriverKind.make("copilot");
+
+const COPILOT_PRESENTATION = {
+  displayName: "GitHub Copilot",
+  showInteractionModeToggle: true,
+} as const;
+
+const DEFAULT_COPILOT_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
+
+/**
+ * Resolve the binary path the runtime would actually invoke for the given
+ * settings. An explicit `binaryPath` always wins; otherwise we fall back
+ * to the bundled CLI (Electron desktop builds ship one per platform).
+ */
+function resolveCopilotBinaryPath(settings: CopilotSettings): string | undefined {
+  const explicit = settings.binaryPath.trim();
+  if (explicit.length > 0) {
+    return explicit;
+  }
+  return resolveBundledCopilotCliPath();
+}
+
+const runCopilotVersionCommand = Effect.fn("runCopilotVersionCommand")(function* (
+  binaryPath: string,
+  environment: NodeJS.ProcessEnv,
+) {
+  const command = ChildProcess.make(binaryPath, ["--version"], {
+    env: environment,
+    shell: process.platform === "win32",
+  });
+  return yield* spawnAndCollect(binaryPath, command);
+});
+
+interface CopilotAuthProbeResult {
+  readonly authenticated: boolean;
+  readonly login?: string;
+  readonly detail?: string;
+}
+
+/**
+ * Best-effort SDK probe: starts a transient `CopilotClient` against the
+ * resolved binary just long enough to enumerate models. A non-empty model
+ * list implies an authenticated GitHub account; failure (any kind) is
+ * folded back into "unknown auth" without surfacing as a driver error.
+ *
+ * Uses `withSanitizedCopilotDesktopEnv` so the Electron host environment
+ * (`ELECTRON_RUN_AS_NODE` etc.) doesn't leak into the spawned binary.
+ */
+class CopilotAuthProbeError extends Data.TaggedError("CopilotAuthProbeError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+const probeCopilotAuth = (binaryPath: string | undefined): Effect.Effect<CopilotAuthProbeResult> =>
+  Effect.tryPromise({
+    try: async (): Promise<CopilotAuthProbeResult> => {
+      const { CopilotClient } = await import("@github/copilot-sdk");
+      const client = new CopilotClient({
+        ...(binaryPath ? { cliPath: binaryPath } : {}),
+        logLevel: "error",
+      });
+      try {
+        await withSanitizedCopilotDesktopEnv(() => client.start());
+        const models = await withSanitizedCopilotDesktopEnv(() =>
+          client.listModels().catch(() => undefined),
+        );
+        const authenticated = !!(models && models.length > 0);
+        return { authenticated };
+      } finally {
+        await client.stop().catch(() => undefined);
+      }
+    },
+    catch: (cause) =>
+      new CopilotAuthProbeError({
+        message: cause instanceof Error ? cause.message : String(cause),
+        cause,
+      }),
+  }).pipe(
+    Effect.timeoutOption("8 seconds"),
+    Effect.result,
+    Effect.map((result): CopilotAuthProbeResult => {
+      if (Result.isFailure(result)) {
+        return {
+          authenticated: false,
+          detail: result.failure.message,
+        };
+      }
+      return Option.isSome(result.success)
+        ? result.success.value
+        : { authenticated: false, detail: "Copilot SDK probe timed out." };
+    }),
+  );
+
+export const makePendingCopilotProvider = (settings: CopilotSettings): ServerProviderDraft => {
+  const checkedAt = new Date().toISOString();
+  const models = providerModelsFromSettings(
+    [],
+    PROVIDER,
+    settings.customModels,
+    DEFAULT_COPILOT_MODEL_CAPABILITIES,
+  );
+
+  if (!settings.enabled) {
+    return buildServerProvider({
+      presentation: COPILOT_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "GitHub Copilot is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  return buildServerProvider({
+    presentation: COPILOT_PRESENTATION,
+    enabled: true,
+    checkedAt,
+    models,
+    probe: {
+      installed: false,
+      version: null,
+      status: "warning",
+      auth: { status: "unknown" },
+      message: "GitHub Copilot status has not been checked in this session yet.",
+    },
+  });
+};
+
+export const checkCopilotProviderStatus = Effect.fn("checkCopilotProviderStatus")(function* (
+  settings: CopilotSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+): Effect.fn.Return<ServerProviderDraft, never, ChildProcessSpawner.ChildProcessSpawner> {
+  const checkedAt = new Date().toISOString();
+  const models = providerModelsFromSettings(
+    [],
+    PROVIDER,
+    settings.customModels,
+    DEFAULT_COPILOT_MODEL_CAPABILITIES,
+  );
+
+  if (!settings.enabled) {
+    return buildServerProvider({
+      presentation: COPILOT_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "GitHub Copilot is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  const binaryPath = resolveCopilotBinaryPath(settings);
+  if (!binaryPath) {
+    return buildServerProvider({
+      presentation: COPILOT_PRESENTATION,
+      enabled: true,
+      checkedAt,
+      models,
+      probe: {
+        installed: false,
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message:
+          "GitHub Copilot CLI is not installed and no binary path is configured. " +
+          "Install the GitHub Copilot CLI or set a binary path in settings.",
+      },
+    });
+  }
+
+  const versionProbe = yield* runCopilotVersionCommand(binaryPath, environment).pipe(
+    Effect.timeoutOption(DEFAULT_TIMEOUT_MS),
+    Effect.result,
+  );
+
+  if (Result.isFailure(versionProbe)) {
+    const error = versionProbe.failure;
+    return buildServerProvider({
+      presentation: COPILOT_PRESENTATION,
+      enabled: true,
+      checkedAt,
+      models,
+      probe: {
+        installed: !isCommandMissingCause(error),
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: isCommandMissingCause(error)
+          ? "GitHub Copilot CLI (`copilot`) is not installed or not on PATH."
+          : `Failed to execute GitHub Copilot CLI health check: ${error instanceof Error ? error.message : String(error)}.`,
+      },
+    });
+  }
+
+  if (Option.isNone(versionProbe.success)) {
+    return buildServerProvider({
+      presentation: COPILOT_PRESENTATION,
+      enabled: true,
+      checkedAt,
+      models,
+      probe: {
+        installed: true,
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: "GitHub Copilot CLI is installed but timed out while reporting its version.",
+      },
+    });
+  }
+
+  const versionResult = versionProbe.success.value;
+  const parsedVersion = parseGenericCliVersion(`${versionResult.stdout}\n${versionResult.stderr}`);
+  if (versionResult.code !== 0) {
+    const detail = detailFromResult(versionResult);
+    return buildServerProvider({
+      presentation: COPILOT_PRESENTATION,
+      enabled: true,
+      checkedAt,
+      models,
+      probe: {
+        installed: true,
+        version: parsedVersion,
+        status: "error",
+        auth: { status: "unknown" },
+        message: detail
+          ? `GitHub Copilot CLI is installed but failed to run. ${detail}`
+          : "GitHub Copilot CLI is installed but failed to run.",
+      },
+    });
+  }
+
+  const auth = yield* probeCopilotAuth(binaryPath);
+
+  return buildServerProvider({
+    presentation: COPILOT_PRESENTATION,
+    enabled: true,
+    checkedAt,
+    models,
+    probe: {
+      installed: true,
+      version: parsedVersion,
+      status: auth.authenticated ? "ready" : "warning",
+      auth: auth.authenticated
+        ? { status: "authenticated", type: "github" }
+        : { status: "unknown" },
+      ...(auth.authenticated
+        ? {}
+        : {
+            message:
+              auth.detail ??
+              "GitHub Copilot CLI is installed but no signed-in account was detected. Run `copilot auth login`.",
+          }),
+    },
+  });
+});
+
+export type { ServerProviderModel };
diff --git a/apps/server/src/provider/Layers/CursorAdapter.test.ts b/apps/server/src/provider/Layers/CursorAdapter.test.ts
index e6bbd7569a4..375eec049a2 100644
--- a/apps/server/src/provider/Layers/CursorAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CursorAdapter.test.ts
@@ -5,14 +5,27 @@ import { fileURLToPath } from "node:url";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
-import { Deferred, Effect, Fiber, Layer, Stream } from "effect";
-
-import { ApprovalRequestId, type ProviderRuntimeEvent, ThreadId } from "@t3tools/contracts";
+import { Context, Deferred, Effect, Fiber, Layer, Schema, Stream } from "effect";
+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 { CursorAdapter } from "../Services/CursorAdapter.ts";
-import { makeCursorAdapterLive } from "./CursorAdapter.ts";
+import type { CursorAdapterShape } from "../Services/CursorAdapter.ts";
+import { makeCursorAdapter } from "./CursorAdapter.ts";
+
+// 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");
@@ -90,8 +103,31 @@ async function waitForFileContent(filePath: string, attempts = 40) {
   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 serverSettings.getSettings.pipe(
+    Effect.map((snapshot) => snapshot.providers.cursor),
+    Effect.orDie,
+  );
+});
+
 const cursorAdapterTestLayer = it.layer(
-  makeCursorAdapterLive().pipe(
+  Layer.effect(
+    CursorAdapter,
+    Effect.gen(function* () {
+      const cursorConfig = Schema.decodeSync(CursorSettings)({});
+      const resolveSettings = yield* makeResolveCursorSettings;
+      return yield* makeCursorAdapter(cursorConfig, { resolveSettings });
+    }),
+  ).pipe(
     Layer.provideMerge(ServerSettingsService.layerTest()),
     Layer.provideMerge(
       ServerConfig.layerTest(process.cwd(), {
@@ -119,10 +155,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       const session = yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "default" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
       });
 
       assert.equal(session.provider, "cursor");
@@ -204,10 +240,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "default" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
       });
 
       yield* adapter.stopSession(threadId);
@@ -243,17 +279,17 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
           [
             adapter.startSession({
               threadId,
-              provider: "cursor",
+              provider: ProviderDriverKind.make("cursor"),
               cwd: process.cwd(),
               runtimeMode: "full-access",
-              modelSelection: { provider: "cursor", model: "default" },
+              modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
             }),
             adapter.startSession({
               threadId,
-              provider: "cursor",
+              provider: ProviderDriverKind.make("cursor"),
               cwd: process.cwd(),
               runtimeMode: "full-access",
-              modelSelection: { provider: "cursor", model: "default" },
+              modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
             }),
           ],
           { concurrency: "unbounded" },
@@ -275,7 +311,7 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
       const result = yield* adapter
         .startSession({
           threadId: ThreadId.make("bad-provider"),
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           cwd: process.cwd(),
           runtimeMode: "full-access",
         })
@@ -301,10 +337,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "composer-2" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "composer-2" },
       });
 
       yield* adapter.sendTurn({
@@ -357,19 +393,15 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
           providers: { cursor: { binaryPath: wrapperPath } },
         });
 
-        const modelSelection = {
-          provider: "cursor" as const,
-          model: "gpt-5.4",
-          options: {
-            reasoning: "xhigh" as const,
-            contextWindow: "1m",
-            fastMode: true,
-          },
-        };
+        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: "cursor",
+          provider: ProviderDriverKind.make("cursor"),
           cwd: process.cwd(),
           runtimeMode: "full-access",
           modelSelection,
@@ -463,10 +495,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
         const program = Effect.gen(function* () {
           yield* adapter.startSession({
             threadId,
-            provider: "cursor",
+            provider: ProviderDriverKind.make("cursor"),
             cwd: process.cwd(),
             runtimeMode: "approval-required",
-            modelSelection: { provider: "cursor", model: "default" },
+            modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
           });
 
           const turn = yield* adapter.sendTurn({
@@ -563,7 +595,14 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
         );
       }).pipe(
         Effect.provide(
-          makeCursorAdapterLive().pipe(
+          Layer.effect(
+            CursorAdapter,
+            Effect.gen(function* () {
+              const cursorConfig = Schema.decodeSync(CursorSettings)({});
+              const resolveSettings = yield* makeResolveCursorSettings;
+              return yield* makeCursorAdapter(cursorConfig, { resolveSettings });
+            }),
+          ).pipe(
             Layer.provideMerge(ServerSettingsService.layerTest()),
             Layer.provideMerge(
               ServerConfig.layerTest(process.cwd(), {
@@ -618,10 +657,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
         yield* adapter.startSession({
           threadId,
-          provider: "cursor",
+          provider: ProviderDriverKind.make("cursor"),
           cwd: process.cwd(),
           runtimeMode: "full-access",
-          modelSelection: { provider: "cursor", model: "default" },
+          modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
         });
 
         const turn = yield* adapter.sendTurn({
@@ -717,10 +756,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "default" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
       });
 
       const turn = yield* adapter.sendTurn({
@@ -839,10 +878,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "approval-required",
-        modelSelection: { provider: "cursor", model: "default" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
       });
 
       const sendTurnFiber = yield* adapter
@@ -909,10 +948,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "approval-required",
-        modelSelection: { provider: "cursor", model: "default" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
       });
 
       const sendTurnFiber = yield* adapter
@@ -952,10 +991,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "default" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
       });
 
       const sendTurnFiber = yield* adapter
@@ -995,10 +1034,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "default" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
       });
 
       const sendTurnFiber = yield* adapter
@@ -1038,10 +1077,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "default" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "default" },
       });
 
       const firstEvents = Array.from(yield* Fiber.join(firstConsumer));
@@ -1076,10 +1115,10 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "composer-2" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "composer-2" },
       });
 
       yield* adapter.sendTurn({
@@ -1092,7 +1131,9 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
         threadId,
         input: "second turn after switching model",
         attachments: [],
-        modelSelection: { provider: "cursor", model: "composer-2", options: { fastMode: true } },
+        modelSelection: createModelSelection(ProviderInstanceId.make("cursor"), "composer-2", [
+          { id: "fastMode", value: true },
+        ]),
       });
 
       const argvRuns = yield* Effect.promise(() => readArgvLog(argvLogPath));
@@ -1137,24 +1178,28 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
 
       yield* adapter.startSession({
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         cwd: process.cwd(),
         runtimeMode: "full-access",
-        modelSelection: { provider: "cursor", model: "composer-2" },
+        modelSelection: { instanceId: ProviderInstanceId.make("cursor"), model: "composer-2" },
       });
 
       yield* adapter.sendTurn({
         threadId,
         input: "first turn with fast mode",
         attachments: [],
-        modelSelection: { provider: "cursor", model: "composer-2", options: { fastMode: true } },
+        modelSelection: createModelSelection(ProviderInstanceId.make("cursor"), "composer-2", [
+          { id: "fastMode", value: true },
+        ]),
       });
 
       yield* adapter.sendTurn({
         threadId,
         input: "second turn without fast mode",
         attachments: [],
-        modelSelection: { provider: "cursor", model: "composer-2", options: { fastMode: false } },
+        modelSelection: createModelSelection(ProviderInstanceId.make("cursor"), "composer-2", [
+          { id: "fastMode", value: false },
+        ]),
       });
 
       const requests = yield* Effect.promise(() => readJsonLines(requestLogPath));
@@ -1171,4 +1216,91 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
       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 = Schema.decodeSync(CursorSettings)({});
+          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
index 03e12a174a1..34d1221b022 100644
--- a/apps/server/src/provider/Layers/CursorAdapter.ts
+++ b/apps/server/src/provider/Layers/CursorAdapter.ts
@@ -7,13 +7,16 @@ import * as nodePath from "node:path";
 
 import {
   ApprovalRequestId,
-  type CursorModelOptions,
+  type CursorSettings,
+  type ProviderOptionSelection,
   EventId,
   type ProviderApprovalDecision,
   type ProviderInteractionMode,
   type ProviderRuntimeEvent,
   type ProviderSession,
   type ProviderUserInputAnswers,
+  ProviderDriverKind,
+  ProviderInstanceId,
   RuntimeRequestId,
   type RuntimeMode,
   type ThreadId,
@@ -26,7 +29,6 @@ import {
   Exit,
   Fiber,
   FileSystem,
-  Layer,
   Option,
   PubSub,
   Random,
@@ -40,7 +42,6 @@ import type * as EffectAcpSchema from "effect-acp/schema";
 
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
 import {
   ProviderAdapterProcessError,
   ProviderAdapterRequestError,
@@ -72,20 +73,37 @@ import {
   extractPlanMarkdown,
   extractTodosAsPlan,
 } from "../acp/CursorAcpExtension.ts";
-import { CursorAdapter, type CursorAdapterShape } from "../Services/CursorAdapter.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
+import { type CursorAdapterShape } from "../Services/CursorAdapter.ts";
 import { resolveCursorAcpBaseModelId } from "./CursorProvider.ts";
 import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
 
-const PROVIDER = "cursor" as const;
+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"];
 
 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 {
@@ -223,7 +241,7 @@ function applyRequestedSessionConfiguration<E>(input: {
   readonly modelSelection:
     | {
         readonly model: string;
-        readonly options?: CursorModelOptions | null | undefined;
+        readonly options?: ReadonlyArray<ProviderOptionSelection> | null | undefined;
       }
     | undefined;
   readonly mapError: (context: {
@@ -236,7 +254,7 @@ function applyRequestedSessionConfiguration<E>(input: {
       yield* applyCursorAcpModelSelection({
         runtime: input.runtime,
         model: input.modelSelection.model,
-        modelOptions: input.modelSelection.options,
+        selections: input.modelSelection.options,
         mapError: ({ cause }) =>
           input.mapError({
             cause,
@@ -281,12 +299,15 @@ function selectAutoApprovedPermissionOption(
   return undefined;
 }
 
-function makeCursorAdapter(options?: CursorAdapterLiveOptions) {
+export function makeCursorAdapter(
+  cursorSettings: CursorSettings,
+  options?: CursorAdapterLiveOptions,
+) {
   return Effect.gen(function* () {
+    const boundInstanceId = options?.instanceId ?? ProviderInstanceId.make("cursor");
     const fileSystem = yield* FileSystem.FileSystem;
     const childProcessSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const serverConfig = yield* Effect.service(ServerConfig);
-    const serverSettingsService = yield* ServerSettingsService;
     const nativeEventLogger =
       options?.nativeEventLogger ??
       (options?.nativeEventLogPath !== undefined
@@ -441,25 +462,12 @@ function makeCursorAdapter(options?: CursorAdapterLiveOptions) {
 
           const cwd = nodePath.resolve(input.cwd.trim());
           const cursorModelSelection =
-            input.modelSelection?.provider === "cursor" ? input.modelSelection : undefined;
+            input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;
           const existing = sessions.get(input.threadId);
           if (existing && !existing.stopped) {
             yield* stopSessionInternal(existing);
           }
 
-          const cursorSettings = yield* serverSettingsService.getSettings.pipe(
-            Effect.map((settings) => settings.providers.cursor),
-            Effect.mapError(
-              (error) =>
-                new ProviderAdapterProcessError({
-                  provider: PROVIDER,
-                  threadId: input.threadId,
-                  detail: error.message,
-                  cause: error,
-                }),
-            ),
-          );
-
           const pendingApprovals = new Map<ApprovalRequestId, PendingApproval>();
           const pendingUserInputs = new Map<ApprovalRequestId, PendingUserInput>();
           const sessionScope = yield* Scope.make("sequential");
@@ -476,8 +484,21 @@ function makeCursorAdapter(options?: CursorAdapterLiveOptions) {
             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,
+            cursorSettings: effectiveCursorSettings,
+            ...(options?.environment ? { environment: options.environment } : {}),
             childProcessSpawner,
             cwd,
             ...(resumeSessionId ? { resumeSessionId } : {}),
@@ -667,6 +688,7 @@ function makeCursorAdapter(options?: CursorAdapterLiveOptions) {
           const now = yield* nowIso;
           const session: ProviderSession = {
             provider: PROVIDER,
+            providerInstanceId: boundInstanceId,
             status: "ready",
             runtimeMode: input.runtimeMode,
             cwd,
@@ -816,7 +838,7 @@ function makeCursorAdapter(options?: CursorAdapterLiveOptions) {
         const ctx = yield* requireSession(input.threadId);
         const turnId = TurnId.make(crypto.randomUUID());
         const turnModelSelection =
-          input.modelSelection?.provider === "cursor" ? input.modelSelection : undefined;
+          input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;
         const model = turnModelSelection?.model ?? ctx.session.model;
         const resolvedModel = resolveCursorAcpBaseModelId(model);
         yield* applyRequestedSessionConfiguration({
@@ -1034,7 +1056,7 @@ function makeCursorAdapter(options?: CursorAdapterLiveOptions) {
 
     return {
       provider: PROVIDER,
-      capabilities: getProviderCapabilities(PROVIDER),
+      capabilities: { sessionModelSwitch: "in-session" },
       startSession,
       sendTurn,
       interruptTurn,
@@ -1050,9 +1072,3 @@ function makeCursorAdapter(options?: CursorAdapterLiveOptions) {
     } satisfies CursorAdapterShape;
   });
 }
-
-export const CursorAdapterLive = Layer.effect(CursorAdapter, makeCursorAdapter());
-
-export function makeCursorAdapterLive(opts?: CursorAdapterLiveOptions) {
-  return Layer.effect(CursorAdapter, makeCursorAdapter(opts));
-}
diff --git a/apps/server/src/provider/Layers/CursorProvider.test.ts b/apps/server/src/provider/Layers/CursorProvider.test.ts
index 6cbfb1078b9..33ef20acf21 100644
--- a/apps/server/src/provider/Layers/CursorProvider.test.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.test.ts
@@ -1,18 +1,17 @@
-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 NodeOS from "node:os";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { Effect } from "effect";
+import { Effect, FileSystem, Path } from "effect";
 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,
@@ -24,11 +23,50 @@ import {
   resolveCursorAcpConfigUpdates,
 } from "./CursorProvider.ts";
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const mockAgentPath = path.join(__dirname, "../../../scripts/acp-mock-agent.ts");
+const runNode = <A, E>(
+  effect: Effect.Effect<A, E, FileSystem.FileSystem | Path.Path>,
+): Promise<A> => Effect.runPromise(effect.pipe(Effect.provide(NodeServices.layer)));
 
-async function makeMockAgentWrapper(extraEnv?: Record<string, string>) {
-  const dir = await mkdtemp(path.join(os.tmpdir(), "cursor-provider-mock-"));
+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");
   const envExports = Object.entries(extraEnv ?? {})
     .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
@@ -37,23 +75,80 @@ async function makeMockAgentWrapper(extraEnv?: Record<string, string>) {
 ${envExports}
 exec ${JSON.stringify("bun")} ${JSON.stringify(mockAgentPath)} "$@"
 `;
-  await writeFile(wrapperPath, script, "utf8");
-  await chmod(wrapperPath, 0o755);
+  yield* fileSystem.writeFileString(wrapperPath, script);
+  yield* fileSystem.chmod(wrapperPath, 0o755);
   return wrapperPath;
-}
+});
 
-async function waitForFileContent(filePath: string, attempts = 40): Promise<string> {
+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");
+  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 ${JSON.stringify("bun")} ${JSON.stringify(mockAgentPath)} "$@"
+`;
+  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) {
-    try {
-      const content = await readFile(filePath, "utf8");
+    const content = yield* fileSystem
+      .readFileString(filePath)
+      .pipe(Effect.catch(() => Effect.void));
+    if (content !== undefined) {
       if (content.trim().length > 0) {
         return content;
       }
-    } catch {}
-    await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    yield* Effect.sleep("50 millis");
   }
-  throw new Error(`Timed out waiting for file content at ${filePath}`);
-}
+  return yield* Effect.fail(new Error(`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 = [
   {
@@ -239,13 +334,7 @@ const baseCursorSettings: CursorSettings = {
   customModels: [],
 };
 
-const emptyCapabilities = {
-  reasoningEffortLevels: [],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-} as const;
+const emptyCapabilities = createModelCapabilities({ optionDescriptors: [] });
 
 describe("getCursorFallbackModels", () => {
   it("does not publish any built-in cursor models before ACP discovery", () => {
@@ -309,52 +398,57 @@ describe("buildCursorProviderSnapshot", () => {
 
 describe("buildCursorCapabilitiesFromConfigOptions", () => {
   it("derives model capabilities from parameterized Cursor ACP config options", () => {
-    expect(buildCursorCapabilitiesFromConfigOptions(parameterizedGpt54ConfigOptions)).toEqual({
-      reasoningEffortLevels: [
-        { value: "low", label: "Low" },
-        { value: "medium", label: "Medium", isDefault: true },
-        { value: "high", label: "High" },
-        { value: "xhigh", label: "Extra High" },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [
-        { value: "272k", label: "272K", isDefault: true },
-        { value: "1m", label: "1M" },
-      ],
-      promptInjectedEffortLevels: [],
-    });
+    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({
-      reasoningEffortLevels: [
-        { value: "low", label: "Low" },
-        { value: "medium", label: "Medium" },
-        { value: "high", label: "High", isDefault: true },
-      ],
-      supportsFastMode: false,
-      supportsThinkingToggle: true,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    });
+    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({
-      reasoningEffortLevels: [
-        { value: "low", label: "Low" },
-        { value: "medium", label: "Medium" },
-        { value: "high", label: "High" },
-        { value: "max", label: "Max", isDefault: true },
-      ],
-      supportsFastMode: true,
-      supportsThinkingToggle: true,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-    });
+    ).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),
+        ],
+      }),
+    );
   });
 });
 
@@ -365,81 +459,76 @@ describe("buildCursorDiscoveredModelsFromConfigOptions", () => {
         slug: "default",
         name: "Auto",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [],
-          supportsFastMode: false,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        capabilities: emptyCapabilities,
       },
       {
         slug: "composer-2",
         name: "Composer 2",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [],
-          supportsFastMode: true,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        capabilities: createModelCapabilities({
+          optionDescriptors: [booleanDescriptor("fastMode", "Fast", true)],
+        }),
       },
       {
         slug: "gpt-5.4",
         name: "GPT-5.4",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [],
-          supportsFastMode: false,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        capabilities: emptyCapabilities,
       },
       {
         slug: "claude-sonnet-4-6",
         name: "Sonnet 4.6",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [],
-          supportsFastMode: false,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        capabilities: emptyCapabilities,
       },
       {
         slug: "claude-opus-4-6",
         name: "Opus 4.6",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [],
-          supportsFastMode: false,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        capabilities: emptyCapabilities,
       },
       {
         slug: "gpt-5.3-codex-spark",
         name: "Codex 5.3 Spark",
         isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [],
-          supportsFastMode: false,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-        },
+        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 makeMockAgentWrapper();
+    const wrapperPath = await runNode(makeMockAgentWrapper());
 
     const models = await Effect.runPromise(
       discoverCursorModelsViaAcp({
@@ -459,11 +548,9 @@ describe("discoverCursorModelsViaAcp", () => {
   });
 
   it("closes the ACP probe runtime after discovery completes", async () => {
-    const tempDir = await mkdtemp(path.join(os.tmpdir(), "cursor-provider-exit-log-"));
-    const exitLogPath = path.join(tempDir, "exit.log");
-    const wrapperPath = await makeMockAgentWrapper({
-      T3_ACP_EXIT_LOG_PATH: exitLogPath,
-    });
+    const { exitLogPath, wrapperPath } = await runNode(
+      makeExitLogFixture("cursor-provider-exit-log-"),
+    );
 
     await Effect.runPromise(
       discoverCursorModelsViaAcp({
@@ -474,18 +561,16 @@ describe("discoverCursorModelsViaAcp", () => {
       }).pipe(Effect.provide(NodeServices.layer)),
     );
 
-    const exitLog = await waitForFileContent(exitLogPath);
+    const exitLog = await runNode(waitForFileContent(exitLogPath));
     expect(exitLog).toContain("SIGTERM");
   });
 });
 
 describe("discoverCursorModelCapabilitiesViaAcp", () => {
   it("closes all ACP probe runtimes after capability enrichment completes", async () => {
-    const tempDir = await mkdtemp(path.join(os.tmpdir(), "cursor-capabilities-exit-log-"));
-    const exitLogPath = path.join(tempDir, "exit.log");
-    const wrapperPath = await makeMockAgentWrapper({
-      T3_ACP_EXIT_LOG_PATH: exitLogPath,
-    });
+    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 },
@@ -517,7 +602,7 @@ describe("discoverCursorModelCapabilitiesViaAcp", () => {
       "claude-opus-4-6",
     ]);
 
-    const exitLog = await waitForFileContent(exitLogPath);
+    const exitLog = await runNode(waitForFileContent(exitLogPath));
     expect(exitLog.match(/SIGTERM/g)?.length ?? 0).toBe(4);
   });
 });
@@ -539,6 +624,7 @@ describe("parseCursorAboutOutput", () => {
       status: "ready",
       auth: {
         status: "authenticated",
+        email: "jmarminge@gmail.com",
         type: "Team",
         label: "Cursor Team Subscription",
       },
@@ -645,11 +731,11 @@ describe("resolveCursorAcpBaseModelId", () => {
 describe("resolveCursorAcpConfigUpdates", () => {
   it("maps Cursor model options onto separate ACP config option updates", () => {
     expect(
-      resolveCursorAcpConfigUpdates(parameterizedGpt54ConfigOptions, {
-        reasoning: "xhigh",
-        fastMode: true,
-        contextWindow: "1m",
-      }),
+      resolveCursorAcpConfigUpdates(parameterizedGpt54ConfigOptions, [
+        { id: "reasoning", value: "xhigh" },
+        { id: "fastMode", value: true },
+        { id: "contextWindow", value: "1m" },
+      ]),
     ).toEqual([
       { configId: "reasoning", value: "extra-high" },
       { configId: "context", value: "1m" },
@@ -659,28 +745,28 @@ describe("resolveCursorAcpConfigUpdates", () => {
 
   it("maps boolean thinking toggles when the model exposes them separately", () => {
     expect(
-      resolveCursorAcpConfigUpdates(parameterizedClaudeConfigOptions, {
-        thinking: false,
-      }),
+      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, {
-        fastMode: false,
-      }),
+      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, {
-        reasoning: "high",
-        thinking: false,
-      }),
+      resolveCursorAcpConfigUpdates(parameterizedClaudeModelOptionConfigOptions, [
+        { id: "reasoning", value: "max" },
+        { id: "thinking", value: false },
+      ]),
     ).toEqual([
-      { configId: "effort", value: "high" },
+      { 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
index 70d5656b3ec..ad52f63fbb2 100644
--- a/apps/server/src/provider/Layers/CursorProvider.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.ts
@@ -1,46 +1,49 @@
-import * as nodeFs from "node:fs";
 import * as nodeOs from "node:os";
-import * as nodePath from "node:path";
 
 import type {
-  CursorModelOptions,
   CursorSettings,
   ModelCapabilities,
+  ProviderOptionSelection,
   ServerProvider,
   ServerProviderAuth,
   ServerProviderModel,
   ServerProviderState,
-  ServerSettingsError,
 } from "@t3tools/contracts";
+import { ProviderDriverKind } from "@t3tools/contracts";
 import type * as EffectAcpSchema from "effect-acp/schema";
-import { Cause, Effect, Equal, Exit, Layer, Option, Result, Stream } from "effect";
+import { Cause, Effect, Exit, FileSystem, Layer, Option, Path, Result } from "effect";
 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 { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
-import { CursorProvider } from "../Services/CursorProvider.ts";
 import { AcpSessionRuntime } from "../acp/AcpSessionRuntime.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-
-const PROVIDER = "cursor" as const;
-const EMPTY_CAPABILITIES: ModelCapabilities = {
-  reasoningEffortLevels: [],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-};
+
+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_REFRESH_INTERVAL = "1 hour";
 const CURSOR_PARAMETERIZED_MODEL_PICKER_MIN_VERSION_DATE = 2026_04_08;
 export const CURSOR_PARAMETERIZED_MODEL_PICKER_CAPABILITIES = {
   _meta: {
@@ -48,13 +51,15 @@ export const CURSOR_PARAMETERIZED_MODEL_PICKER_CAPABILITIES = {
   },
 } satisfies NonNullable<EffectAcpSchema.InitializeRequest["clientCapabilities"]>;
 
-function buildInitialCursorProviderSnapshot(cursorSettings: CursorSettings): ServerProvider {
+export function buildInitialCursorProviderSnapshot(
+  cursorSettings: CursorSettings,
+): ServerProviderDraft {
   const checkedAt = new Date().toISOString();
   const models = getCursorFallbackModels(cursorSettings);
 
   if (!cursorSettings.enabled) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: CURSOR_PRESENTATION,
       enabled: false,
       checkedAt,
       models,
@@ -69,7 +74,7 @@ function buildInitialCursorProviderSnapshot(cursorSettings: CursorSettings): Ser
   }
 
   return buildServerProvider({
-    provider: PROVIDER,
+    presentation: CURSOR_PRESENTATION,
     enabled: true,
     checkedAt,
     models,
@@ -102,7 +107,12 @@ function flattenSessionConfigSelectOptions(
   }
   return configOption.options.flatMap((entry) =>
     "value" in entry
-      ? [{ value: entry.value.trim(), name: entry.name.trim() } satisfies CursorSessionSelectOption]
+      ? [
+          {
+            value: entry.value.trim(),
+            name: entry.name.trim(),
+          } satisfies CursorSessionSelectOption,
+        ]
       : entry.options.map(
           (option) =>
             ({
@@ -198,6 +208,28 @@ function isBooleanLikeConfigOption(option: EffectAcpSchema.SessionConfigOption):
   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 {
@@ -251,14 +283,60 @@ export function buildCursorCapabilitiesFromConfigOptions(
   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 {
-    reasoningEffortLevels,
-    supportsFastMode: fastOption ? isBooleanLikeConfigOption(fastOption) : false,
-    supportsThinkingToggle: thinkingOption ? isBooleanLikeConfigOption(thinkingOption) : false,
-    contextWindowOptions,
-    promptInjectedEffortLevels: [],
-  };
+  return createModelCapabilities({
+    optionDescriptors,
+  });
 }
 
 function buildCursorDiscoveredModels(
@@ -282,13 +360,7 @@ function buildCursorDiscoveredModels(
 }
 
 function hasCursorModelCapabilities(model: Pick<ServerProviderModel, "capabilities">): boolean {
-  return (
-    (model.capabilities?.reasoningEffortLevels.length ?? 0) > 0 ||
-    model.capabilities?.supportsFastMode === true ||
-    model.capabilities?.supportsThinkingToggle === true ||
-    (model.capabilities?.contextWindowOptions.length ?? 0) > 0 ||
-    (model.capabilities?.promptInjectedEffortLevels.length ?? 0) > 0
-  );
+  return (model.capabilities?.optionDescriptors?.length ?? 0) > 0;
 }
 
 export function buildCursorDiscoveredModelsFromConfigOptions(
@@ -320,7 +392,10 @@ export function buildCursorDiscoveredModelsFromConfigOptions(
   );
 }
 
-const makeCursorAcpProbeRuntime = (cursorSettings: CursorSettings) =>
+const makeCursorAcpProbeRuntime = (
+  cursorSettings: CursorSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
   Effect.gen(function* () {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const acpContext = yield* Layer.build(
@@ -332,6 +407,7 @@ const makeCursorAcpProbeRuntime = (cursorSettings: CursorSettings) =>
             "acp",
           ],
           cwd: process.cwd(),
+          env: environment,
         },
         cwd: process.cwd(),
         clientInfo: { name: "t3-code-provider-probe", version: "0.0.0" },
@@ -345,7 +421,12 @@ const makeCursorAcpProbeRuntime = (cursorSettings: CursorSettings) =>
 const withCursorAcpProbeRuntime = <A, E, R>(
   cursorSettings: CursorSettings,
   useRuntime: (acp: AcpSessionRuntime["Service"]) => Effect.Effect<A, E, R>,
-) => makeCursorAcpProbeRuntime(cursorSettings).pipe(Effect.flatMap(useRuntime), Effect.scoped);
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
+  makeCursorAcpProbeRuntime(cursorSettings, environment).pipe(
+    Effect.flatMap(useRuntime),
+    Effect.scoped,
+  );
 
 function normalizeCursorConfigOptionToken(value: string | null | undefined): string {
   return (
@@ -387,16 +468,24 @@ export function resolveCursorAcpBaseModelId(model: string | null | undefined): s
 
 export function resolveCursorAcpConfigUpdates(
   configOptions: ReadonlyArray<EffectAcpSchema.SessionConfigOption> | null | undefined,
-  modelOptions: CursorModelOptions | null | undefined,
-): ReadonlyArray<{ readonly configId: string; readonly value: string | boolean }> {
+  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 updates: Array<{
+    readonly configId: string;
+    readonly value: string | boolean;
+  }> = [];
 
   const reasoningOption = findCursorEffortConfigOption(configOptions);
-  const requestedReasoning = normalizeCursorReasoningValue(modelOptions?.reasoning);
+  const requestedReasoning = normalizeCursorReasoningValue(
+    getProviderOptionStringSelectionValue(selections, "reasoning"),
+  );
   if (reasoningOption && requestedReasoning) {
     const value = findCursorSelectOptionValue(reasoningOption, (option) => {
       const normalizedValue = normalizeCursorReasoningValue(option.value);
@@ -411,14 +500,15 @@ export function resolveCursorAcpConfigUpdates(
   const contextOption = configOptions.find(
     (option) => option.category === "model_config" && isCursorContextConfigOption(option),
   );
-  if (contextOption && modelOptions?.contextWindow) {
+  const requestedContextWindow = getProviderOptionStringSelectionValue(selections, "contextWindow");
+  if (contextOption && requestedContextWindow) {
     const value = findCursorSelectOptionValue(
       contextOption,
       (option) =>
         normalizeCursorConfigOptionToken(option.value) ===
-          normalizeCursorConfigOptionToken(modelOptions.contextWindow) ||
+          normalizeCursorConfigOptionToken(requestedContextWindow) ||
         normalizeCursorConfigOptionToken(option.name) ===
-          normalizeCursorConfigOptionToken(modelOptions.contextWindow),
+          normalizeCursorConfigOptionToken(requestedContextWindow),
     );
     if (value) {
       updates.push({ configId: contextOption.id, value });
@@ -428,8 +518,9 @@ export function resolveCursorAcpConfigUpdates(
   const fastOption = configOptions.find(
     (option) => option.category === "model_config" && isCursorFastConfigOption(option),
   );
-  if (fastOption && typeof modelOptions?.fastMode === "boolean") {
-    const value = findCursorBooleanConfigValue(fastOption, modelOptions.fastMode);
+  const requestedFastMode = getProviderOptionBooleanSelectionValue(selections, "fastMode");
+  if (fastOption && typeof requestedFastMode === "boolean") {
+    const value = findCursorBooleanConfigValue(fastOption, requestedFastMode);
     if (value !== undefined) {
       updates.push({ configId: fastOption.id, value });
     }
@@ -438,8 +529,9 @@ export function resolveCursorAcpConfigUpdates(
   const thinkingOption = configOptions.find(
     (option) => option.category === "model_config" && isCursorThinkingConfigOption(option),
   );
-  if (thinkingOption && typeof modelOptions?.thinking === "boolean") {
-    const value = findCursorBooleanConfigValue(thinkingOption, modelOptions.thinking);
+  const requestedThinking = getProviderOptionBooleanSelectionValue(selections, "thinking");
+  if (thinkingOption && typeof requestedThinking === "boolean") {
+    const value = findCursorBooleanConfigValue(thinkingOption, requestedThinking);
     if (value !== undefined) {
       updates.push({ configId: thinkingOption.id, value });
     }
@@ -448,43 +540,129 @@ export function resolveCursorAcpConfigUpdates(
   return updates;
 }
 
-export const discoverCursorModelsViaAcp = (cursorSettings: CursorSettings) =>
-  withCursorAcpProbeRuntime(cursorSettings, (acp) =>
-    Effect.map(acp.start(), (started) =>
-      buildCursorDiscoveredModelsFromConfigOptions(started.sessionSetupResult.configOptions ?? []),
-    ),
+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 [];
-      }
+  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 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]);
+        }
 
-      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(),
@@ -492,73 +670,8 @@ export const discoverCursorModelCapabilitiesViaAcp = (
             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;
-            }),
-          ).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", {})),
+      }).pipe(Effect.withSpan("cursor-acp-model-capability-discovery", {})),
+    environment,
   );
 
 export function getCursorFallbackModels(
@@ -606,10 +719,10 @@ export function buildCursorProviderSnapshot(input: {
   readonly parsed: CursorAboutResult;
   readonly discoveredModels?: ReadonlyArray<ServerProviderModel>;
   readonly discoveryWarning?: string;
-}): ServerProvider {
+}): ServerProviderDraft {
   const message = joinProviderMessages(input.parsed.message, input.discoveryWarning);
   return buildServerProvider({
-    provider: PROVIDER,
+    presentation: CURSOR_PRESENTATION,
     enabled: input.cursorSettings.enabled,
     checkedAt: input.checkedAt,
     models: providerModelsFromSettings(
@@ -733,14 +846,13 @@ function isCursorAboutJsonFormatUnsupported(result: CommandResult): boolean {
   );
 }
 
-function readCursorCliConfigChannel(): string | undefined {
-  try {
-    const configPath = nodePath.join(nodeOs.homedir(), ".cursor", "cli-config.json");
-    return parseCursorCliConfigChannel(nodeFs.readFileSync(configPath, "utf8"));
-  } catch {
-    return undefined;
-  }
-}
+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;
@@ -856,6 +968,7 @@ export function parseCursorAboutOutput(result: CommandResult): CursorAboutResult
       status: "ready",
       auth: {
         status: "authenticated",
+        email: userEmail,
         ...authMetadata,
       },
     };
@@ -911,17 +1024,22 @@ export function parseCursorAboutOutput(result: CommandResult): CursorAboutResult
   }
 
   // Any non-empty email value means authenticated.
-  return { version, status: "ready", auth: { status: "authenticated" } };
+  return {
+    version,
+    status: "ready",
+    auth: { status: "authenticated", email: userEmail },
+  };
 }
 
-const runCursorCommand = (args: ReadonlyArray<string>) =>
+const runCursorCommand = (
+  cursorSettings: CursorSettings,
+  args: ReadonlyArray<string>,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
   Effect.gen(function* () {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-    const cursorSettings = yield* Effect.service(ServerSettingsService).pipe(
-      Effect.flatMap((service) => service.getSettings),
-      Effect.map((settings) => settings.providers.cursor),
-    );
     const command = ChildProcess.make(cursorSettings.binaryPath, [...args], {
+      env: environment,
       shell: process.platform === "win32",
     });
 
@@ -938,199 +1056,202 @@ const runCursorCommand = (args: ReadonlyArray<string>) =>
     return { stdout, stderr, code: exitCode } satisfies CommandResult;
   }).pipe(Effect.scoped);
 
-const runCursorAboutCommand = Effect.gen(function* () {
-  const jsonResult = yield* runCursorCommand(["about", "--format", "json"]);
-  if (!isCursorAboutJsonFormatUnsupported(jsonResult)) {
-    return jsonResult;
-  }
-  return yield* runCursorCommand(["about"]);
-});
-
-export const checkCursorProviderStatus = Effect.fn("checkCursorProviderStatus")(
-  function* (): Effect.fn.Return<
-    ServerProvider,
-    ServerSettingsError,
-    ChildProcessSpawner.ChildProcessSpawner | ServerSettingsService
-  > {
-    const cursorSettings = yield* Effect.service(ServerSettingsService).pipe(
-      Effect.flatMap((service) => service.getSettings),
-      Effect.map((settings) => settings.providers.cursor),
+const runCursorAboutCommand = (
+  cursorSettings: CursorSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) =>
+  Effect.gen(function* () {
+    const jsonResult = yield* runCursorCommand(
+      cursorSettings,
+      ["about", "--format", "json"],
+      environment,
     );
-    const checkedAt = new Date().toISOString();
-    const fallbackModels = getCursorFallbackModels(cursorSettings);
-
-    if (!cursorSettings.enabled) {
-      return buildServerProvider({
-        provider: PROVIDER,
-        enabled: false,
-        checkedAt,
-        models: fallbackModels,
-        probe: {
-          installed: false,
-          version: null,
-          status: "warning",
-          auth: { status: "unknown" },
-          message: "Cursor is disabled in T3 Code settings.",
-        },
-      });
+    if (!isCursorAboutJsonFormatUnsupported(jsonResult)) {
+      return jsonResult;
     }
+    return yield* runCursorCommand(cursorSettings, ["about"], environment);
+  });
 
-    // Single `agent about` probe: returns version + auth status in one call.
-    const aboutProbe = yield* runCursorAboutCommand.pipe(
-      Effect.timeoutOption(ABOUT_TIMEOUT_MS),
-      Effect.result,
-    );
+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 = new Date().toISOString();
+  const fallbackModels = getCursorFallbackModels(cursorSettings);
 
-    if (Result.isFailure(aboutProbe)) {
-      const error = aboutProbe.failure;
-      return buildServerProvider({
-        provider: PROVIDER,
-        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 (!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.",
+      },
+    });
+  }
 
-    if (Option.isNone(aboutProbe.success)) {
-      return buildServerProvider({
-        provider: PROVIDER,
-        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`.",
-        },
-      });
-    }
+  // 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,
+  );
 
-    const parsed = parseCursorAboutOutput(aboutProbe.success.value);
-    const parameterizedModelPickerUnsupportedMessage =
-      getCursorParameterizedModelPickerUnsupportedMessage({
-        version: parsed.version,
-        channel: readCursorCliConfigChannel(),
-      });
-    if (parameterizedModelPickerUnsupportedMessage) {
-      return buildServerProvider({
-        provider: PROVIDER,
-        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).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({
+  if (Result.isFailure(aboutProbe)) {
+    const error = aboutProbe.failure;
+    return buildServerProvider({
+      presentation: CURSOR_PRESENTATION,
+      enabled: cursorSettings.enabled,
       checkedAt,
-      cursorSettings,
-      parsed,
-      discoveredModels: Option.getOrElse(
-        Option.filter(discoveredModels, (models) => models.length > 0),
-        () => [] as const,
-      ),
-      ...(discoveryWarning ? { discoveryWarning } : {}),
+      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)}.`,
+      },
     });
-  },
-);
+  }
 
-export const CursorProviderLive = Layer.effect(
-  CursorProvider,
-  Effect.gen(function* () {
-    const serverSettings = yield* ServerSettingsService;
-    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  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 checkProvider = checkCursorProviderStatus().pipe(
-      Effect.provideService(ServerSettingsService, serverSettings),
-      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+  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 } : {}),
+  });
+});
 
-    return yield* makeManagedServerProvider<CursorSettings>({
-      getSettings: serverSettings.getSettings.pipe(
-        Effect.map((settings) => settings.providers.cursor),
-        Effect.orDie,
-      ),
-      streamSettings: serverSettings.streamChanges.pipe(
-        Stream.map((settings) => settings.providers.cursor),
-      ),
-      haveSettingsChanged: (previous, next) => !Equal.equals(previous, next),
-      initialSnapshot: buildInitialCursorProviderSnapshot,
-      checkProvider,
-      enrichSnapshot: ({ settings, snapshot, publishSnapshot }) => {
-        if (
-          !settings.enabled ||
-          snapshot.auth.status === "unauthenticated" ||
-          !snapshot.models.some((model) => !model.isCustom && !hasCursorModelCapabilities(model))
-        ) {
-          return Effect.void;
-        }
+export function hasUncapturedCursorModels(snapshot: Pick<ServerProvider, "models">): boolean {
+  return snapshot.models.some((model) => !model.isCustom && !hasCursorModelCapabilities(model));
+}
 
-        return discoverCursorModelCapabilitiesViaAcp(settings, snapshot.models).pipe(
-          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
-          Effect.flatMap((discoveredModels) => {
-            if (discoveredModels.length === 0) {
-              return Effect.void;
-            }
+/**
+ * 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 publishSnapshot: (snapshot: ServerProvider) => Effect.Effect<void>;
+  readonly stampIdentity?: (snapshot: ServerProvider) => ServerProvider;
+}): Effect.Effect<void, never, ChildProcessSpawner.ChildProcessSpawner> => {
+  const { settings, snapshot, publishSnapshot } = input;
+  const stampIdentity = input.stampIdentity ?? ((value) => value);
 
-            return publishSnapshot({
-              ...snapshot,
-              models: providerModelsFromSettings(
-                discoveredModels,
-                PROVIDER,
-                settings.customModels,
-                EMPTY_CAPABILITIES,
-              ),
-            });
-          }),
-          Effect.catchCause((cause) =>
-            Effect.logWarning("Cursor ACP background capability enrichment failed", {
-              models: snapshot.models.map((model) => model.slug),
-              cause: Cause.pretty(cause),
-            }).pipe(Effect.asVoid),
+  if (
+    !settings.enabled ||
+    snapshot.auth.status === "unauthenticated" ||
+    !hasUncapturedCursorModels(snapshot)
+  ) {
+    return Effect.void;
+  }
+
+  return discoverCursorModelCapabilitiesViaAcp(settings, snapshot.models, input.environment).pipe(
+    Effect.flatMap((discoveredModels) => {
+      if (discoveredModels.length === 0) {
+        return Effect.void;
+      }
+      return publishSnapshot(
+        stampIdentity({
+          ...snapshot,
+          models: providerModelsFromSettings(
+            discoveredModels,
+            PROVIDER,
+            settings.customModels,
+            EMPTY_CAPABILITIES,
           ),
-        );
-      },
-      refreshInterval: CURSOR_REFRESH_INTERVAL,
-    });
-  }),
-);
+        }),
+      );
+    }),
+    Effect.catchCause((cause) =>
+      Effect.logWarning("Cursor ACP background capability enrichment failed", {
+        models: snapshot.models.map((model) => model.slug),
+        cause: Cause.pretty(cause),
+      }).pipe(Effect.asVoid),
+    ),
+  );
+};
diff --git a/apps/server/src/provider/Layers/GeminiCliAdapter.test.ts b/apps/server/src/provider/Layers/GeminiCliAdapter.test.ts
index ce0bdfa3014..e4d05de30cc 100644
--- a/apps/server/src/provider/Layers/GeminiCliAdapter.test.ts
+++ b/apps/server/src/provider/Layers/GeminiCliAdapter.test.ts
@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import {
   ApprovalRequestId,
   EventId,
+  GenericProviderSettings,
   RuntimeItemId,
   ThreadId,
   TurnId,
@@ -12,19 +13,28 @@ import {
   type ProviderTurnStartResult,
   type ProviderUserInputAnswers,
 } from "@t3tools/contracts";
-import { it, vi } from "@effect/vitest";
-import { Effect, Layer, Stream } from "effect";
+import { it } from "@effect/vitest";
+import { Context, Effect, Layer, Schema, Stream } from "effect";
+import { vi } from "vitest";
 
 import { GeminiCliServerManager } from "../../geminiCliServerManager.ts";
-import { GeminiCliAdapter } from "../Services/GeminiCliAdapter.ts";
-import { makeGeminiCliAdapterLive } from "./GeminiCliAdapter.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import {
+  makeGeminiCliAdapter,
+  type GeminiCliAdapterShape,
+} from "./GeminiCliAdapter.ts";
 
 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): RuntimeItemId => RuntimeItemId.make(value);
 
+// Test-local service tag mirroring the OpenCode/Claude adapter test pattern:
+// the new factory returns a shape directly, so tests inject it through a
+// throwaway Context.Service tag.
+class GeminiCliAdapter extends Context.Service<GeminiCliAdapter, GeminiCliAdapterShape>()(
+  "test/GeminiCliAdapter",
+) {}
+
 class FakeGeminiCliManager extends GeminiCliServerManager {
   public startSessionImpl = vi.fn(async (threadId: ThreadId): Promise<ProviderSession> => {
     const now = new Date().toISOString();
@@ -105,81 +115,103 @@ class FakeGeminiCliManager extends GeminiCliServerManager {
   }
 }
 
-const manager = new FakeGeminiCliManager();
-const layer = it.layer(
-  makeGeminiCliAdapterLive({ manager }).pipe(Layer.provideMerge(ServerSettingsService.layerTest())),
+const enabledConfig = Schema.decodeSync(GenericProviderSettings)({ enabled: true });
+const disabledConfig = Schema.decodeSync(GenericProviderSettings)({ enabled: false });
+
+const makeAdapterLayer = (manager: FakeGeminiCliManager, config = enabledConfig) =>
+  Layer.effect(GeminiCliAdapter, makeGeminiCliAdapter(config, { manager }));
+
+it.effect("delegates session startup to the manager", () =>
+  Effect.gen(function* () {
+    const manager = new FakeGeminiCliManager();
+    const adapter = yield* GeminiCliAdapter;
+
+    const session = yield* adapter.startSession({
+      threadId: asThreadId("thread-1"),
+      runtimeMode: "full-access",
+    });
+
+    assert.equal(session.provider, "geminiCli");
+    assert.equal(manager.startSessionImpl.mock.calls[0]?.[0], asThreadId("thread-1"));
+  }).pipe(Effect.provide(makeAdapterLayer(new FakeGeminiCliManager())), Effect.scoped),
 );
 
-layer("GeminiCliAdapterLive", (it) => {
-  it.effect("delegates session startup to the manager", () =>
-    Effect.gen(function* () {
-      manager.startSessionImpl.mockClear();
-      const adapter = yield* GeminiCliAdapter;
+it.effect("returns validation error when the provider is disabled", () =>
+  Effect.gen(function* () {
+    const adapter = yield* GeminiCliAdapter;
 
-      const session = yield* adapter.startSession({
-        threadId: asThreadId("thread-1"),
+    const result = yield* adapter
+      .startSession({
+        threadId: asThreadId("thread-disabled"),
         runtimeMode: "full-access",
-      });
+      })
+      .pipe(Effect.result);
+
+    assert.equal(result._tag, "Failure");
+    if (result._tag !== "Failure") return;
+    assert.equal(result.failure._tag, "ProviderAdapterValidationError");
+  }).pipe(
+    Effect.provide(makeAdapterLayer(new FakeGeminiCliManager(), disabledConfig)),
+    Effect.scoped,
+  ),
+);
 
-      assert.equal(session.provider, "geminiCli");
-      assert.equal(manager.startSessionImpl.mock.calls[0]?.[0], asThreadId("thread-1"));
-    }),
-  );
+it.effect("rejects attachments until Gemini CLI attachment wiring exists", () =>
+  Effect.gen(function* () {
+    const adapter = yield* GeminiCliAdapter;
+    const result = yield* adapter
+      .sendTurn({
+        threadId: asThreadId("thread-attachments"),
+        input: "hello",
+        attachments: [{ id: "attachment-1" }] as never,
+      })
+      .pipe(Effect.result);
+
+    assert.equal(result._tag, "Failure");
+    if (result._tag !== "Failure") {
+      return;
+    }
+    assert.equal(result.failure._tag, "ProviderAdapterValidationError");
+  }).pipe(Effect.provide(makeAdapterLayer(new FakeGeminiCliManager())), Effect.scoped),
+);
 
-  it.effect("rejects attachments until Gemini CLI attachment wiring exists", () =>
-    Effect.gen(function* () {
-      const adapter = yield* GeminiCliAdapter;
-      const result = yield* adapter
-        .sendTurn({
-          threadId: asThreadId("thread-attachments"),
-          input: "hello",
-          attachments: [{ id: "attachment-1" }] as never,
-        })
-        .pipe(Effect.result);
-
-      assert.equal(result._tag, "Failure");
-      if (result._tag !== "Failure") {
-        return;
-      }
-      assert.equal(result.failure._tag, "ProviderAdapterValidationError");
-    }),
-  );
+it.effect("forwards manager runtime events through the adapter stream", () =>
+  Effect.gen(function* () {
+    const manager = new FakeGeminiCliManager();
+    const layer = makeAdapterLayer(manager);
+    const adapter = yield* GeminiCliAdapter;
 
-  it.effect("forwards manager runtime events through the adapter stream", () =>
-    Effect.gen(function* () {
-      const adapter = yield* GeminiCliAdapter;
-
-      const event = {
-        type: "content.delta",
-        eventId: asEventId("evt-gemini-delta"),
-        provider: "geminiCli",
-        createdAt: new Date().toISOString(),
-        threadId: asThreadId("thread-1"),
-        turnId: asTurnId("turn-1"),
-        itemId: asItemId("item-1"),
-        payload: {
-          streamKind: "assistant_text",
-          delta: "hello",
-        },
-      } as unknown as ProviderRuntimeEvent;
-
-      // Emit first — the event is buffered in the unbounded queue via the
-      // listener that was registered during layer construction.
-      manager.emit("event", event);
-
-      // Now consume the head. Since the queue already has an item, this
-      // resolves immediately without a race condition.
-      const received = yield* Stream.runHead(adapter.streamEvents);
-
-      assert.equal(received._tag, "Some");
-      if (received._tag !== "Some") {
-        return;
-      }
-      assert.equal(received.value.type, "content.delta");
-      if (received.value.type !== "content.delta") {
-        return;
-      }
-      assert.equal(received.value.payload.delta, "hello");
-    }),
-  );
-});
+    const event = {
+      type: "content.delta",
+      eventId: asEventId("evt-gemini-delta"),
+      provider: "geminiCli",
+      createdAt: new Date().toISOString(),
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId("turn-1"),
+      itemId: asItemId("item-1"),
+      payload: {
+        streamKind: "assistant_text",
+        delta: "hello",
+      },
+    } as unknown as ProviderRuntimeEvent;
+
+    // Event must be emitted AFTER the listener is attached (i.e. after the
+    // layer is built and the adapter is yielded); the buffered queue then
+    // holds the event so the subsequent `runHead` resolves immediately.
+    manager.emit("event", event);
+
+    const received = yield* Stream.runHead(adapter.streamEvents);
+
+    assert.equal(received._tag, "Some");
+    if (received._tag !== "Some") {
+      return;
+    }
+    assert.equal(received.value.type, "content.delta");
+    if (received.value.type !== "content.delta") {
+      return;
+    }
+    assert.equal(received.value.payload.delta, "hello");
+
+    void layer; // keep ref so eslint doesn't complain
+  }).pipe(Effect.provide(makeAdapterLayer(new FakeGeminiCliManager())), Effect.scoped),
+);
diff --git a/apps/server/src/provider/Layers/GeminiCliAdapter.ts b/apps/server/src/provider/Layers/GeminiCliAdapter.ts
index 1c14bf9743b..a1804c80b56 100644
--- a/apps/server/src/provider/Layers/GeminiCliAdapter.ts
+++ b/apps/server/src/provider/Layers/GeminiCliAdapter.ts
@@ -1,145 +1,183 @@
-import { type ProviderRuntimeEvent } from "@t3tools/contracts";
-import { Effect, Layer, Queue, Stream } from "effect";
+/**
+ * GeminiCliAdapter — per-instance Gemini CLI provider adapter.
+ *
+ * Mirrors the Amp/Kilo pattern but exposes a `makeGeminiCliAdapter(config, options)`
+ * factory (instead of the old `Layer.effect` + service-tag setup) so the
+ * `GeminiCliDriver` can capture one adapter per instance.
+ *
+ * The underlying `GeminiCliServerManager` is a pure EventEmitter that owns
+ * all per-instance state — sessions, child processes, usage accumulator —
+ * so two `makeGeminiCliAdapter` calls with different configs produce two
+ * fully isolated adapters with no shared mutable state.
+ *
+ * @module provider/Layers/GeminiCliAdapter
+ */
+import {
+  type GenericProviderSettings,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { Effect, Queue, Stream } from "effect";
 
 import { GeminiCliServerManager } from "../../geminiCliServerManager.ts";
-import { ProviderAdapterProcessError, ProviderAdapterValidationError } from "../Errors.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
-import { GeminiCliAdapter, type GeminiCliAdapterShape } from "../Services/GeminiCliAdapter.ts";
+import {
+  ProviderAdapterValidationError,
+  type ProviderAdapterError,
+} from "../Errors.ts";
+import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
+import type { EventNdjsonLogger } from "./EventNdjsonLogger.ts";
 import { makeErrorHelpers } from "./ProviderAdapterUtils.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
 
-const PROVIDER = "geminiCli" as const;
-const { toRequestError } = makeErrorHelpers(PROVIDER, {
+const PROVIDER = ProviderDriverKind.make("geminiCli");
+const { toRequestError } = makeErrorHelpers("geminiCli", {
   sessionNotFoundHints: ["unknown gemini cli session", "unknown session"],
 });
 
-export interface GeminiCliAdapterLiveOptions {
+export interface GeminiCliAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {}
+
+export interface GeminiCliAdapterOptions {
+  readonly instanceId?: ProviderInstanceId;
+  readonly environment?: NodeJS.ProcessEnv;
+  readonly nativeEventLogger?: EventNdjsonLogger;
+  /**
+   * Inject a pre-built manager. Test-only — the driver always constructs its
+   * own. Mutually exclusive with `makeManager`.
+   */
   readonly manager?: GeminiCliServerManager;
+  /**
+   * Lazy manager factory used by tests that want a fresh manager but still
+   * want the adapter to call the constructor.
+   */
   readonly makeManager?: () => GeminiCliServerManager;
 }
 
-export function makeGeminiCliAdapterLive(options: GeminiCliAdapterLiveOptions = {}) {
-  return Layer.effect(
-    GeminiCliAdapter,
-    Effect.gen(function* () {
-      const manager = options.manager ?? options.makeManager?.() ?? new GeminiCliServerManager();
-      const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
-      const serverSettingsService = yield* ServerSettingsService;
+/**
+ * Build one Gemini CLI adapter bound to the given config and options.
+ *
+ * Closes over a private `GeminiCliServerManager` so that two instances of
+ * the same driver cannot reach into each other's session tables. Adds an
+ * Effect finalizer that detaches the manager event listener and stops every
+ * remaining session when the surrounding scope closes.
+ */
+export const makeGeminiCliAdapter = Effect.fn("makeGeminiCliAdapter")(function* (
+  config: GenericProviderSettings,
+  options: GeminiCliAdapterOptions = {},
+) {
+  const _boundInstanceId = options.instanceId ?? ProviderInstanceId.make("geminiCli");
+  const trimmedBinary = config.binaryPath.trim();
+  const manager =
+    options.manager ??
+    options.makeManager?.() ??
+    new GeminiCliServerManager({
+      ...(trimmedBinary.length > 0 ? { binaryPath: trimmedBinary } : {}),
+    });
+  // Keep the manager's binary path in sync with the latest config — drivers
+  // recreate the adapter when settings change, but tests may pass a manager
+  // with an empty default that should pick up the config value.
+  if (trimmedBinary.length > 0 && !manager.binaryPath) {
+    manager.binaryPath = trimmedBinary;
+  }
 
-      yield* Effect.acquireRelease(
-        Effect.sync(() => {
-          const listener = (event: ProviderRuntimeEvent) => {
-            Effect.runFork(Queue.offer(runtimeEventQueue, event).pipe(Effect.asVoid));
-          };
-          manager.on("event", listener);
-          return listener;
-        }),
-        (listener) =>
-          Effect.gen(function* () {
-            manager.off("event", listener);
-            manager.stopAll();
-            yield* Queue.shutdown(runtimeEventQueue);
-          }),
-      );
+  const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
 
-      const service = {
-        provider: PROVIDER,
-        capabilities: getProviderCapabilities(PROVIDER),
-        startSession: (input) =>
-          Effect.gen(function* () {
-            const providerSettings = yield* serverSettingsService.getSettings.pipe(
-              Effect.map((s) => s.providers.geminiCli),
-              Effect.mapError(
-                (error) =>
-                  new ProviderAdapterProcessError({
-                    provider: PROVIDER,
-                    threadId: input.threadId,
-                    detail: error.message,
-                    cause: error,
-                  }),
-              ),
-            );
-            if (!providerSettings.enabled) {
-              return yield* new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "startSession",
-                issue: "Gemini CLI provider is disabled in server settings.",
-              });
-            }
-            manager.binaryPath = providerSettings.binaryPath.trim() || undefined;
-            return yield* Effect.tryPromise({
-              try: () => manager.startSession(input),
-              catch: (cause) => toRequestError(input.threadId, "session/start", cause),
-            });
-          }),
-        sendTurn: (input) => {
-          if ((input.attachments?.length ?? 0) > 0) {
-            return Effect.fail(
-              new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "sendTurn",
-                issue: "Gemini CLI attachments are not supported yet.",
-              }),
-            );
-          }
+  yield* Effect.acquireRelease(
+    Effect.sync(() => {
+      const listener = (event: ProviderRuntimeEvent) => {
+        Effect.runFork(Queue.offer(runtimeEventQueue, event).pipe(Effect.asVoid));
+      };
+      manager.on("event", listener);
+      return listener;
+    }),
+    (listener) =>
+      Effect.gen(function* () {
+        manager.off("event", listener);
+        manager.stopAll();
+        yield* Queue.shutdown(runtimeEventQueue);
+      }),
+  );
 
-          return Effect.tryPromise({
-            try: () => manager.sendTurn(input),
-            catch: (cause) => toRequestError(input.threadId, "session/prompt", cause),
+  const adapter: GeminiCliAdapterShape = {
+    provider: PROVIDER,
+    capabilities: { sessionModelSwitch: "in-session" },
+    startSession: (input) =>
+      Effect.gen(function* () {
+        if (!config.enabled) {
+          return yield* new ProviderAdapterValidationError({
+            provider: "geminiCli",
+            operation: "startSession",
+            issue: "Gemini CLI provider is disabled in server settings.",
           });
-        },
-        interruptTurn: (threadId) =>
-          Effect.tryPromise({
-            try: () => manager.interruptTurn(threadId),
-            catch: (cause) => toRequestError(threadId, "session/interrupt", cause),
-          }),
-        respondToRequest: (threadId, requestId, decision) =>
-          Effect.tryPromise({
-            try: () => manager.respondToRequest(threadId, requestId, decision),
-            catch: (cause) => toRequestError(threadId, "permission/reply", cause),
-          }),
-        respondToUserInput: (threadId, requestId, answers) =>
-          Effect.tryPromise({
-            try: () => manager.respondToUserInput(threadId, requestId, answers),
-            catch: (cause) => toRequestError(threadId, "question/reply", cause),
+        }
+        return yield* Effect.tryPromise({
+          try: () => manager.startSession(input),
+          catch: (cause) => toRequestError(input.threadId, "session/start", cause),
+        });
+      }),
+    sendTurn: (input) => {
+      if ((input.attachments?.length ?? 0) > 0) {
+        return Effect.fail(
+          new ProviderAdapterValidationError({
+            provider: "geminiCli",
+            operation: "sendTurn",
+            issue: "Gemini CLI attachments are not supported yet.",
           }),
-        stopSession: (threadId) =>
-          Effect.sync(() => {
-            manager.stopSession(threadId);
-          }),
-        listSessions: () => Effect.sync(() => manager.listSessions()),
-        hasSession: (threadId) => Effect.sync(() => manager.hasSession(threadId)),
-        readThread: (threadId) =>
-          Effect.tryPromise({
-            try: () => manager.readThread(threadId),
-            catch: (cause) => toRequestError(threadId, "session/messages", cause),
-          }),
-        rollbackThread: (threadId, numTurns) => {
-          if (!Number.isInteger(numTurns) || numTurns < 1) {
-            return Effect.fail(
-              new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "rollbackThread",
-                issue: "numTurns must be an integer >= 1.",
-              }),
-            );
-          }
+        );
+      }
 
-          return Effect.tryPromise({
-            try: () => manager.rollbackThread(threadId),
-            catch: (cause) => toRequestError(threadId, "session/revert", cause),
-          });
-        },
-        stopAll: () =>
-          Effect.sync(() => {
-            manager.stopAll();
+      return Effect.tryPromise({
+        try: () => manager.sendTurn(input),
+        catch: (cause) => toRequestError(input.threadId, "session/prompt", cause),
+      });
+    },
+    interruptTurn: (threadId) =>
+      Effect.tryPromise({
+        try: () => manager.interruptTurn(threadId),
+        catch: (cause) => toRequestError(threadId, "session/interrupt", cause),
+      }),
+    respondToRequest: (threadId, requestId, decision) =>
+      Effect.tryPromise({
+        try: () => manager.respondToRequest(threadId, requestId, decision),
+        catch: (cause) => toRequestError(threadId, "permission/reply", cause),
+      }),
+    respondToUserInput: (threadId, requestId, answers) =>
+      Effect.tryPromise({
+        try: () => manager.respondToUserInput(threadId, requestId, answers),
+        catch: (cause) => toRequestError(threadId, "question/reply", cause),
+      }),
+    stopSession: (threadId) =>
+      Effect.sync(() => {
+        manager.stopSession(threadId);
+      }),
+    listSessions: () => Effect.sync(() => manager.listSessions()),
+    hasSession: (threadId) => Effect.sync(() => manager.hasSession(threadId)),
+    readThread: (threadId) =>
+      Effect.tryPromise({
+        try: () => manager.readThread(threadId),
+        catch: (cause) => toRequestError(threadId, "session/messages", cause),
+      }),
+    rollbackThread: (threadId, numTurns) => {
+      if (!Number.isInteger(numTurns) || numTurns < 1) {
+        return Effect.fail(
+          new ProviderAdapterValidationError({
+            provider: "geminiCli",
+            operation: "rollbackThread",
+            issue: "numTurns must be an integer >= 1.",
           }),
-        streamEvents: Stream.fromQueue(runtimeEventQueue),
-      } satisfies GeminiCliAdapterShape;
+        );
+      }
 
-      return service;
-    }),
-  );
-}
+      return Effect.tryPromise({
+        try: () => manager.rollbackThread(threadId),
+        catch: (cause) => toRequestError(threadId, "session/revert", cause),
+      });
+    },
+    stopAll: () =>
+      Effect.sync(() => {
+        manager.stopAll();
+      }),
+    streamEvents: Stream.fromQueue(runtimeEventQueue),
+  };
 
-export const GeminiCliAdapterLive = makeGeminiCliAdapterLive();
+  return adapter;
+});
diff --git a/apps/server/src/provider/Layers/GeminiCliProvider.ts b/apps/server/src/provider/Layers/GeminiCliProvider.ts
new file mode 100644
index 00000000000..30cc50405f9
--- /dev/null
+++ b/apps/server/src/provider/Layers/GeminiCliProvider.ts
@@ -0,0 +1,256 @@
+/**
+ * GeminiCliProvider — snapshot probe for the Gemini CLI provider.
+ *
+ * Mirrors `ClaudeProvider` / `OpenCodeProvider`: exposes
+ * `checkGeminiCliStatus(config, env)` which spawns `gemini --version` and
+ * returns a `ServerProviderDraft`, plus `makePendingGeminiCliProvider(config)`
+ * which returns the placeholder shape used before the first probe completes.
+ *
+ * Drivers stamp `instanceId` / `driver` / `displayName` onto the draft via
+ * `withInstanceIdentity` in `GeminiCliDriver`.
+ *
+ * @module provider/Layers/GeminiCliProvider
+ */
+import {
+  type GenericProviderSettings,
+  type ModelCapabilities,
+  ProviderDriverKind,
+  type ServerProviderModel,
+} from "@t3tools/contracts";
+import { Effect, Option, Path, Result } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { createModelCapabilities } from "@t3tools/shared/model";
+
+import {
+  buildSelectOptionDescriptor,
+  buildServerProvider,
+  DEFAULT_TIMEOUT_MS,
+  detailFromResult,
+  isCommandMissingCause,
+  parseGenericCliVersion,
+  providerModelsFromSettings,
+  spawnAndCollect,
+  type ServerProviderDraft,
+} from "../providerSnapshot.ts";
+
+const PROVIDER = ProviderDriverKind.make("geminiCli");
+const GEMINI_PRESENTATION = {
+  displayName: "Gemini CLI",
+  showInteractionModeToggle: true,
+} as const;
+
+/**
+ * Capabilities for known Gemini models. Includes a `thinkingBudget` selector
+ * (fork-only feature) — kept in this layer because the probe / adapter both
+ * need it.
+ */
+const THINKING_BUDGET_DESCRIPTOR = buildSelectOptionDescriptor({
+  id: "thinkingBudget",
+  label: "Thinking Budget",
+  options: [
+    { value: "auto", label: "Auto", isDefault: true },
+    { value: "low", label: "Low" },
+    { value: "medium", label: "Medium" },
+    { value: "high", label: "High" },
+  ],
+});
+
+const DEFAULT_GEMINI_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [THINKING_BUDGET_DESCRIPTOR],
+});
+
+const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = [
+  {
+    slug: "gemini-2.5-pro",
+    name: "Gemini 2.5 Pro",
+    isCustom: false,
+    capabilities: DEFAULT_GEMINI_MODEL_CAPABILITIES,
+  },
+  {
+    slug: "gemini-2.5-flash",
+    name: "Gemini 2.5 Flash",
+    isCustom: false,
+    capabilities: DEFAULT_GEMINI_MODEL_CAPABILITIES,
+  },
+  {
+    slug: "gemini-3-flash",
+    name: "Gemini 3 Flash",
+    isCustom: false,
+    capabilities: DEFAULT_GEMINI_MODEL_CAPABILITIES,
+  },
+];
+
+/** Resolve the configured binary path, or fall back to `"gemini"`. */
+function resolveBinary(config: GenericProviderSettings): string {
+  const trimmed = config.binaryPath.trim();
+  return trimmed.length > 0 ? trimmed : "gemini";
+}
+
+const runGeminiCommand = Effect.fn("runGeminiCommand")(function* (
+  config: GenericProviderSettings,
+  args: ReadonlyArray<string>,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const binaryPath = resolveBinary(config);
+  const command = ChildProcess.make(binaryPath, [...args], {
+    env: environment,
+    shell: process.platform === "win32",
+  });
+  return yield* spawnAndCollect(binaryPath, command);
+});
+
+export const checkGeminiCliStatus = Effect.fn("checkGeminiCliStatus")(function* (
+  config: GenericProviderSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+): Effect.fn.Return<
+  ServerProviderDraft,
+  never,
+  ChildProcessSpawner.ChildProcessSpawner | Path.Path
+> {
+  const checkedAt = new Date().toISOString();
+  const allModels = providerModelsFromSettings(
+    BUILT_IN_MODELS,
+    PROVIDER,
+    config.customModels,
+    DEFAULT_GEMINI_MODEL_CAPABILITIES,
+  );
+
+  if (!config.enabled) {
+    return buildServerProvider({
+      presentation: GEMINI_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Gemini CLI is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  const versionProbe = yield* runGeminiCommand(config, ["--version"], environment).pipe(
+    Effect.timeoutOption(DEFAULT_TIMEOUT_MS),
+    Effect.result,
+  );
+
+  if (Result.isFailure(versionProbe)) {
+    const error = versionProbe.failure;
+    return buildServerProvider({
+      presentation: GEMINI_PRESENTATION,
+      enabled: config.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: !isCommandMissingCause(error),
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: isCommandMissingCause(error)
+          ? "Gemini CLI (`gemini`) is not installed or not on PATH."
+          : `Failed to execute Gemini CLI health check: ${error instanceof Error ? error.message : String(error)}.`,
+      },
+    });
+  }
+
+  if (Option.isNone(versionProbe.success)) {
+    return buildServerProvider({
+      presentation: GEMINI_PRESENTATION,
+      enabled: config.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: true,
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: "Gemini CLI is installed but failed to run. Timed out while running command.",
+      },
+    });
+  }
+
+  const version = versionProbe.success.value;
+  const parsedVersion = parseGenericCliVersion(`${version.stdout}\n${version.stderr}`);
+  if (version.code !== 0) {
+    const detail = detailFromResult(version);
+    return buildServerProvider({
+      presentation: GEMINI_PRESENTATION,
+      enabled: config.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: true,
+        version: parsedVersion,
+        status: "error",
+        auth: { status: "unknown" },
+        message: detail
+          ? `Gemini CLI is installed but failed to run. ${detail}`
+          : "Gemini CLI is installed but failed to run.",
+      },
+    });
+  }
+
+  return buildServerProvider({
+    presentation: GEMINI_PRESENTATION,
+    enabled: config.enabled,
+    checkedAt,
+    models: allModels,
+    probe: {
+      installed: true,
+      version: parsedVersion,
+      status: "ready",
+      auth: {
+        status: "authenticated",
+        type: "geminiCli",
+        label: "Gemini CLI",
+      },
+    },
+  });
+});
+
+export const makePendingGeminiCliProvider = (
+  config: GenericProviderSettings,
+): ServerProviderDraft => {
+  const checkedAt = new Date().toISOString();
+  const models = providerModelsFromSettings(
+    BUILT_IN_MODELS,
+    PROVIDER,
+    config.customModels,
+    DEFAULT_GEMINI_MODEL_CAPABILITIES,
+  );
+
+  if (!config.enabled) {
+    return buildServerProvider({
+      presentation: GEMINI_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Gemini CLI is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  return buildServerProvider({
+    presentation: GEMINI_PRESENTATION,
+    enabled: true,
+    checkedAt,
+    models,
+    probe: {
+      installed: false,
+      version: null,
+      status: "warning",
+      auth: { status: "unknown" },
+      message: "Gemini CLI provider status has not been checked in this session yet.",
+    },
+  });
+};
+
+export { BUILT_IN_MODELS as GEMINI_BUILT_IN_MODELS, DEFAULT_GEMINI_MODEL_CAPABILITIES };
diff --git a/apps/server/src/provider/Layers/KiloAdapter.test.ts b/apps/server/src/provider/Layers/KiloAdapter.test.ts
index 227fd36a04b..b7a811613fe 100644
--- a/apps/server/src/provider/Layers/KiloAdapter.test.ts
+++ b/apps/server/src/provider/Layers/KiloAdapter.test.ts
@@ -1,24 +1,20 @@
 import assert from "node:assert/strict";
 
 import {
-  ApprovalRequestId,
   EventId,
   RuntimeItemId,
   ThreadId,
   TurnId,
-  type ProviderApprovalDecision,
   type ProviderRuntimeEvent,
   type ProviderSession,
   type ProviderTurnStartResult,
-  type ProviderUserInputAnswers,
 } from "@t3tools/contracts";
 import { it, vi } from "@effect/vitest";
-import { Effect, Layer, Stream } from "effect";
+import { Effect, Schema, Stream } from "effect";
+import { GenericProviderSettings } from "@t3tools/contracts";
 
 import { KiloServerManager } from "../../kiloServerManager.ts";
-import { KiloAdapter } from "../Services/KiloAdapter.ts";
-import { makeKiloAdapterLive } from "./KiloAdapter.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import { makeKiloAdapter } from "./KiloAdapter.ts";
 
 const asThreadId = (value: string): ThreadId => ThreadId.make(value);
 const asTurnId = (value: string): TurnId => TurnId.make(value);
@@ -47,13 +43,6 @@ class FakeKiloManager extends KiloServerManager {
     }),
   );
 
-  public interruptTurnImpl = vi.fn(async (): Promise<void> => undefined);
-  public respondToRequestImpl = vi.fn(async (): Promise<void> => undefined);
-  public respondToUserInputImpl = vi.fn(async (): Promise<void> => undefined);
-  public readThreadImpl = vi.fn(async (threadId: ThreadId) => ({ threadId, turns: [] }));
-  public rollbackThreadImpl = vi.fn(async (threadId: ThreadId) => ({ threadId, turns: [] }));
-  public stopAllImpl = vi.fn(() => undefined);
-
   override startSession(input: { threadId: ThreadId }): Promise<ProviderSession> {
     return this.startSessionImpl(input.threadId);
   }
@@ -63,31 +52,15 @@ class FakeKiloManager extends KiloServerManager {
   }
 
   override interruptTurn(_threadId: ThreadId): Promise<void> {
-    return this.interruptTurnImpl();
-  }
-
-  override respondToRequest(
-    _threadId: ThreadId,
-    _requestId: ApprovalRequestId,
-    _decision: ProviderApprovalDecision,
-  ): Promise<void> {
-    return this.respondToRequestImpl();
-  }
-
-  override respondToUserInput(
-    _threadId: ThreadId,
-    _requestId: ApprovalRequestId,
-    _answers: ProviderUserInputAnswers,
-  ): Promise<void> {
-    return this.respondToUserInputImpl();
+    return Promise.resolve();
   }
 
   override readThread(threadId: ThreadId) {
-    return this.readThreadImpl(threadId);
+    return Promise.resolve({ threadId, turns: [] });
   }
 
   override rollbackThread(threadId: ThreadId) {
-    return this.rollbackThreadImpl(threadId);
+    return Promise.resolve({ threadId, turns: [] });
   }
 
   override stopSession(_threadId: ThreadId): void {}
@@ -100,21 +73,16 @@ class FakeKiloManager extends KiloServerManager {
     return false;
   }
 
-  override stopAll(): void {
-    this.stopAllImpl();
-  }
+  override stopAll(): void {}
 }
 
-const manager = new FakeKiloManager();
-const layer = it.layer(
-  makeKiloAdapterLive({ manager }).pipe(Layer.provideMerge(ServerSettingsService.layerTest())),
-);
+const enabledSettings = Schema.decodeSync(GenericProviderSettings)({ enabled: true });
 
-layer("KiloAdapterLive", (it) => {
-  it.effect("delegates session startup to the manager", () =>
+it.effect("makeKiloAdapter delegates session startup to the manager", () =>
+  Effect.scoped(
     Effect.gen(function* () {
-      manager.startSessionImpl.mockClear();
-      const adapter = yield* KiloAdapter;
+      const manager = new FakeKiloManager();
+      const adapter = yield* makeKiloAdapter(enabledSettings, { manager });
 
       const session = yield* adapter.startSession({
         threadId: asThreadId("thread-1"),
@@ -124,11 +92,14 @@ layer("KiloAdapterLive", (it) => {
       assert.equal(session.provider, "kilo");
       assert.equal(manager.startSessionImpl.mock.calls[0]?.[0], asThreadId("thread-1"));
     }),
-  );
+  ),
+);
 
-  it.effect("rejects attachments until Kilo attachment wiring exists", () =>
+it.effect("makeKiloAdapter rejects attachments until Kilo wiring exists", () =>
+  Effect.scoped(
     Effect.gen(function* () {
-      const adapter = yield* KiloAdapter;
+      const adapter = yield* makeKiloAdapter(enabledSettings, { manager: new FakeKiloManager() });
+
       const result = yield* adapter
         .sendTurn({
           threadId: asThreadId("thread-attachments"),
@@ -143,11 +114,14 @@ layer("KiloAdapterLive", (it) => {
       }
       assert.equal(result.failure._tag, "ProviderAdapterValidationError");
     }),
-  );
+  ),
+);
 
-  it.effect("forwards manager runtime events through the adapter stream", () =>
+it.effect("makeKiloAdapter forwards manager runtime events through the stream", () =>
+  Effect.scoped(
     Effect.gen(function* () {
-      const adapter = yield* KiloAdapter;
+      const manager = new FakeKiloManager();
+      const adapter = yield* makeKiloAdapter(enabledSettings, { manager });
 
       const event = {
         type: "content.delta",
@@ -163,12 +137,8 @@ layer("KiloAdapterLive", (it) => {
         },
       } as unknown as ProviderRuntimeEvent;
 
-      // Emit first — the event is buffered in the unbounded queue via the
-      // listener that was registered during layer construction.
       manager.emit("event", event);
 
-      // Now consume the head. Since the queue already has an item, this
-      // resolves immediately without a race condition.
       const received = yield* Stream.runHead(adapter.streamEvents);
 
       assert.equal(received._tag, "Some");
@@ -181,5 +151,24 @@ layer("KiloAdapterLive", (it) => {
       }
       assert.equal(received.value.payload.delta, "hello");
     }),
-  );
-});
+  ),
+);
+
+it.effect("makeKiloAdapter rejects startSession when disabled", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const disabled = Schema.decodeSync(GenericProviderSettings)({ enabled: false });
+      const adapter = yield* makeKiloAdapter(disabled, { manager: new FakeKiloManager() });
+
+      const result = yield* adapter
+        .startSession({ threadId: asThreadId("thread-disabled"), runtimeMode: "full-access" })
+        .pipe(Effect.result);
+
+      assert.equal(result._tag, "Failure");
+      if (result._tag !== "Failure") {
+        return;
+      }
+      assert.equal(result.failure._tag, "ProviderAdapterValidationError");
+    }),
+  ),
+);
diff --git a/apps/server/src/provider/Layers/KiloAdapter.ts b/apps/server/src/provider/Layers/KiloAdapter.ts
index 88564676879..4a7e417a639 100644
--- a/apps/server/src/provider/Layers/KiloAdapter.ts
+++ b/apps/server/src/provider/Layers/KiloAdapter.ts
@@ -1,145 +1,170 @@
-import { type ProviderRuntimeEvent } from "@t3tools/contracts";
-import { Effect, Layer, Queue, Stream } from "effect";
+/**
+ * KiloAdapter — per-instance Kilo provider adapter.
+ *
+ * The adapter owns a fresh `KiloServerManager` per `ProviderInstance`, so two
+ * Kilo instances never share session state, server processes, or runtime
+ * event queues. The factory `makeKiloAdapter` is invoked from
+ * {@link ../Drivers/KiloDriver} inside the registry's per-instance scope; the
+ * scope finalizer registered here calls `manager.stopAll()` and shuts down
+ * the runtime event queue.
+ *
+ * @module provider/Layers/KiloAdapter
+ */
+import {
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ProviderRuntimeEvent,
+} from "@t3tools/contracts";
+import { Effect, Queue, Stream } from "effect";
 
 import { KiloServerManager } from "../../kiloServerManager.ts";
 import type { KiloSessionStartInput } from "../../kilo/types.ts";
-import { ProviderAdapterProcessError, ProviderAdapterValidationError } from "../Errors.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
-import { KiloAdapter, type KiloAdapterShape } from "../Services/KiloAdapter.ts";
+import type { OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
+import {
+  ProviderAdapterRequestError,
+  ProviderAdapterValidationError,
+} from "../Errors.ts";
 import { makeErrorHelpers } from "./ProviderAdapterUtils.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import type { KiloSettings } from "./KiloProvider.ts";
 
-const PROVIDER = "kilo" as const;
-const { toRequestError } = makeErrorHelpers(PROVIDER);
+const PROVIDER = ProviderDriverKind.make("kilo");
+const { toRequestError } = makeErrorHelpers("kilo");
 
-export interface KiloAdapterLiveOptions {
+export interface KiloAdapterOptions {
+  readonly instanceId?: ProviderInstanceId;
+  readonly environment?: NodeJS.ProcessEnv;
+  /** Optional injection point used by tests to swap in a fake manager. */
   readonly manager?: KiloServerManager;
   readonly makeManager?: () => KiloServerManager;
 }
 
-export function makeKiloAdapterLive(options: KiloAdapterLiveOptions = {}) {
-  return Layer.effect(
-    KiloAdapter,
-    Effect.gen(function* () {
-      const manager = options.manager ?? options.makeManager?.() ?? new KiloServerManager();
-      const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
-      const serverSettingsService = yield* ServerSettingsService;
+/**
+ * KiloAdapterShape — per-instance Kilo adapter contract. Reuses the
+ * OpenCode adapter shape (Kilo is API-compatible) and is keyed by the
+ * `kilo` driver kind.
+ */
+export interface KiloAdapterShape extends OpenCodeAdapterShape {}
 
-      yield* Effect.acquireRelease(
-        Effect.sync(() => {
-          const listener = (event: ProviderRuntimeEvent) => {
-            Effect.runFork(Queue.offer(runtimeEventQueue, event).pipe(Effect.asVoid));
-          };
-          manager.on("event", listener);
-          return listener;
-        }),
-        (listener) =>
-          Effect.gen(function* () {
-            manager.off("event", listener);
-            manager.stopAll();
-            yield* Queue.shutdown(runtimeEventQueue);
-          }),
-      );
+export const makeKiloAdapter = Effect.fn("makeKiloAdapter")(function* (
+  kiloSettings: KiloSettings,
+  options?: KiloAdapterOptions,
+) {
+  const _instanceId = options?.instanceId ?? ProviderInstanceId.make("kilo");
+  void _instanceId; // reserved for future per-instance tagging
+  const manager =
+    options?.manager ?? options?.makeManager?.() ?? new KiloServerManager();
+  const runtimeEventQueue = yield* Queue.unbounded<ProviderRuntimeEvent>();
 
-      const service = {
-        provider: PROVIDER,
-        capabilities: getProviderCapabilities(PROVIDER),
-        startSession: (input) =>
-          Effect.gen(function* () {
-            const providerSettings = yield* serverSettingsService.getSettings.pipe(
-              Effect.map((s) => s.providers.kilo),
-              Effect.mapError(
-                (error) =>
-                  new ProviderAdapterProcessError({
-                    provider: PROVIDER,
-                    threadId: input.threadId,
-                    detail: error.message,
-                    cause: error,
-                  }),
-              ),
-            );
-            if (!providerSettings.enabled) {
-              return yield* new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "startSession",
-                issue: "Kilo provider is disabled in server settings.",
-              });
-            }
-            const binaryPath = providerSettings.binaryPath.trim() || "kilo";
-            return yield* Effect.tryPromise({
-              try: () =>
-                manager.startSession({ ...input, kilo: { binaryPath } } as KiloSessionStartInput),
-              catch: (cause) => toRequestError(input.threadId, "session/start", cause),
-            });
-          }),
-        sendTurn: (input) => {
-          if ((input.attachments?.length ?? 0) > 0) {
-            return Effect.fail(
-              new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "sendTurn",
-                issue: "Kilo attachments are not wired yet.",
-              }),
-            );
-          }
+  // Acquire the manager event listener at scope start, release at scope close.
+  // Closing the registry-owned scope tears down sessions, the spawned Kilo
+  // server child process, and the runtime event queue exactly once.
+  yield* Effect.acquireRelease(
+    Effect.sync(() => {
+      const listener = (event: ProviderRuntimeEvent) => {
+        Effect.runFork(Queue.offer(runtimeEventQueue, event).pipe(Effect.asVoid));
+      };
+      manager.on("event", listener);
+      return listener;
+    }),
+    (listener) =>
+      Effect.gen(function* () {
+        manager.off("event", listener);
+        manager.stopAll();
+        yield* Queue.shutdown(runtimeEventQueue);
+      }),
+  );
 
-          return Effect.tryPromise({
-            try: () => manager.sendTurn(input),
-            catch: (cause) => toRequestError(input.threadId, "session/prompt_async", cause),
+  const resolveBinaryPath = (): string => kiloSettings.binaryPath.trim() || "kilo";
+
+  const service: KiloAdapterShape = {
+    provider: PROVIDER,
+    capabilities: { sessionModelSwitch: "in-session" },
+    startSession: (input) =>
+      Effect.gen(function* () {
+        if (!kiloSettings.enabled) {
+          return yield* new ProviderAdapterValidationError({
+            provider: PROVIDER,
+            operation: "startSession",
+            issue: "Kilo provider is disabled in server settings.",
           });
-        },
-        interruptTurn: (threadId) =>
-          Effect.tryPromise({
-            try: () => manager.interruptTurn(threadId),
-            catch: (cause) => toRequestError(threadId, "session/abort", cause),
-          }),
-        respondToRequest: (threadId, requestId, decision) =>
-          Effect.tryPromise({
-            try: () => manager.respondToRequest(threadId, requestId, decision),
-            catch: (cause) => toRequestError(threadId, "permission/reply", cause),
-          }),
-        respondToUserInput: (threadId, requestId, answers) =>
-          Effect.tryPromise({
-            try: () => manager.respondToUserInput(threadId, requestId, answers),
-            catch: (cause) => toRequestError(threadId, "question/reply", cause),
+        }
+        const binaryPath = resolveBinaryPath();
+        return yield* Effect.tryPromise({
+          try: () =>
+            manager.startSession({
+              ...input,
+              kilo: { binaryPath },
+            } as KiloSessionStartInput),
+          catch: (cause) => toRequestError(input.threadId, "session/start", cause),
+        });
+      }),
+    sendTurn: (input) => {
+      if ((input.attachments?.length ?? 0) > 0) {
+        return Effect.fail(
+          new ProviderAdapterValidationError({
+            provider: PROVIDER,
+            operation: "sendTurn",
+            issue: "Kilo attachments are not wired yet.",
           }),
-        stopSession: (threadId) =>
-          Effect.sync(() => {
-            manager.stopSession(threadId);
-          }),
-        listSessions: () => Effect.sync(() => manager.listSessions()),
-        hasSession: (threadId) => Effect.sync(() => manager.hasSession(threadId)),
-        readThread: (threadId) =>
-          Effect.tryPromise({
-            try: () => manager.readThread(threadId),
-            catch: (cause) => toRequestError(threadId, "session/messages", cause),
-          }),
-        rollbackThread: (threadId, numTurns) => {
-          if (!Number.isInteger(numTurns) || numTurns < 1) {
-            return Effect.fail(
-              new ProviderAdapterValidationError({
-                provider: PROVIDER,
-                operation: "rollbackThread",
-                issue: "numTurns must be an integer >= 1.",
-              }),
-            );
-          }
+        );
+      }
 
-          return Effect.tryPromise({
-            try: () => manager.rollbackThread(threadId),
-            catch: (cause) => toRequestError(threadId, "session/revert", cause),
-          });
-        },
-        stopAll: () =>
-          Effect.sync(() => {
-            manager.stopAll();
+      return Effect.tryPromise({
+        try: () => manager.sendTurn(input),
+        catch: (cause) => toRequestError(input.threadId, "session/prompt_async", cause),
+      });
+    },
+    interruptTurn: (threadId) =>
+      Effect.tryPromise({
+        try: () => manager.interruptTurn(threadId),
+        catch: (cause) => toRequestError(threadId, "session/abort", cause),
+      }),
+    respondToRequest: (threadId, requestId, decision) =>
+      Effect.tryPromise({
+        try: () => manager.respondToRequest(threadId, requestId, decision),
+        catch: (cause) => toRequestError(threadId, "permission/reply", cause),
+      }),
+    respondToUserInput: (threadId, requestId, answers) =>
+      Effect.tryPromise({
+        try: () => manager.respondToUserInput(threadId, requestId, answers),
+        catch: (cause) => toRequestError(threadId, "question/reply", cause),
+      }),
+    stopSession: (threadId) =>
+      Effect.sync(() => {
+        manager.stopSession(threadId);
+      }),
+    listSessions: () => Effect.sync(() => manager.listSessions()),
+    hasSession: (threadId) => Effect.sync(() => manager.hasSession(threadId)),
+    readThread: (threadId) =>
+      Effect.tryPromise({
+        try: () => manager.readThread(threadId),
+        catch: (cause) => toRequestError(threadId, "session/messages", cause),
+      }),
+    rollbackThread: (threadId, numTurns) => {
+      if (!Number.isInteger(numTurns) || numTurns < 1) {
+        return Effect.fail(
+          new ProviderAdapterValidationError({
+            provider: PROVIDER,
+            operation: "rollbackThread",
+            issue: "numTurns must be an integer >= 1.",
           }),
-        streamEvents: Stream.fromQueue(runtimeEventQueue),
-      } satisfies KiloAdapterShape;
+        );
+      }
 
-      return service;
-    }),
-  );
-}
+      return Effect.tryPromise({
+        try: () => manager.rollbackThread(threadId, numTurns),
+        catch: (cause) => toRequestError(threadId, "session/revert", cause),
+      });
+    },
+    stopAll: () =>
+      Effect.sync(() => {
+        manager.stopAll();
+      }),
+    streamEvents: Stream.fromQueue(runtimeEventQueue),
+  };
+
+  return service;
+});
 
-export const KiloAdapterLive = makeKiloAdapterLive();
+// Re-export so callers using the public symbol name still resolve.
+export { ProviderAdapterRequestError };
diff --git a/apps/server/src/provider/Layers/KiloProvider.ts b/apps/server/src/provider/Layers/KiloProvider.ts
new file mode 100644
index 00000000000..768297b54c3
--- /dev/null
+++ b/apps/server/src/provider/Layers/KiloProvider.ts
@@ -0,0 +1,215 @@
+/**
+ * KiloProvider — snapshot probe for the Kilo Code provider.
+ *
+ * Kilo is a fork of OpenCode and exposes the same HTTP+SSE API. The probe
+ * is per-instance: it uses the per-driver `KiloSettings` (currently
+ * `GenericProviderSettings`) to resolve `binaryPath`, then runs
+ * `kilo --version` to confirm the binary is installed. Authentication is
+ * not validated here — the Kilo server handles that lazily on first
+ * session. Custom models are surfaced via `customModels`.
+ *
+ * Two helpers are exported:
+ *   - `checkKiloProviderStatus`   — full probe used by the driver's
+ *     `makeManagedServerProvider` refresh.
+ *   - `makePendingKiloProvider`   — synchronous "checking…" snapshot that
+ *     `makeManagedServerProvider` publishes as the initial value.
+ *
+ * @module provider/Layers/KiloProvider
+ */
+import {
+  ProviderDriverKind,
+  type GenericProviderSettings,
+  type ModelCapabilities,
+} from "@t3tools/contracts";
+import { Effect, Option, Path, Result } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import { createModelCapabilities } from "@t3tools/shared/model";
+
+import {
+  buildServerProvider,
+  DEFAULT_TIMEOUT_MS,
+  detailFromResult,
+  isCommandMissingCause,
+  parseGenericCliVersion,
+  providerModelsFromSettings,
+  spawnAndCollect,
+  type ServerProviderDraft,
+} from "../providerSnapshot.ts";
+
+const PROVIDER = ProviderDriverKind.make("kilo");
+const KILO_PRESENTATION = {
+  displayName: "Kilo Code",
+  showInteractionModeToggle: true,
+} as const;
+
+const DEFAULT_KILO_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
+
+export type KiloSettings = GenericProviderSettings;
+
+const runKiloCommand = Effect.fn("runKiloCommand")(function* (
+  kiloSettings: KiloSettings,
+  args: ReadonlyArray<string>,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
+  const binaryPath = kiloSettings.binaryPath.trim() || "kilo";
+  const command = ChildProcess.make(binaryPath, [...args], {
+    env: environment,
+    shell: process.platform === "win32",
+  });
+  return yield* spawnAndCollect(binaryPath, command);
+});
+
+export const checkKiloProviderStatus = Effect.fn("checkKiloProviderStatus")(function* (
+  kiloSettings: KiloSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+): Effect.fn.Return<
+  ServerProviderDraft,
+  never,
+  ChildProcessSpawner.ChildProcessSpawner | Path.Path
+> {
+  const checkedAt = new Date().toISOString();
+  const allModels = providerModelsFromSettings(
+    [],
+    PROVIDER,
+    kiloSettings.customModels,
+    DEFAULT_KILO_MODEL_CAPABILITIES,
+  );
+
+  if (!kiloSettings.enabled) {
+    return buildServerProvider({
+      presentation: KILO_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Kilo is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  const versionProbe = yield* runKiloCommand(kiloSettings, ["--version"], environment).pipe(
+    Effect.timeoutOption(DEFAULT_TIMEOUT_MS),
+    Effect.result,
+  );
+
+  if (Result.isFailure(versionProbe)) {
+    const error = versionProbe.failure;
+    return buildServerProvider({
+      presentation: KILO_PRESENTATION,
+      enabled: kiloSettings.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: !isCommandMissingCause(error),
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: isCommandMissingCause(error)
+          ? "Kilo CLI (`kilo`) is not installed or not on PATH."
+          : `Failed to execute Kilo CLI health check: ${error instanceof Error ? error.message : String(error)}.`,
+      },
+    });
+  }
+
+  if (Option.isNone(versionProbe.success)) {
+    return buildServerProvider({
+      presentation: KILO_PRESENTATION,
+      enabled: kiloSettings.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: true,
+        version: null,
+        status: "error",
+        auth: { status: "unknown" },
+        message: "Kilo CLI is installed but failed to run. Timed out while running command.",
+      },
+    });
+  }
+
+  const version = versionProbe.success.value;
+  const parsedVersion = parseGenericCliVersion(`${version.stdout}\n${version.stderr}`);
+  if (version.code !== 0) {
+    const detail = detailFromResult(version);
+    return buildServerProvider({
+      presentation: KILO_PRESENTATION,
+      enabled: kiloSettings.enabled,
+      checkedAt,
+      models: allModels,
+      probe: {
+        installed: true,
+        version: parsedVersion,
+        status: "error",
+        auth: { status: "unknown" },
+        message: detail
+          ? `Kilo CLI is installed but failed to run. ${detail}`
+          : "Kilo CLI is installed but failed to run.",
+      },
+    });
+  }
+
+  return buildServerProvider({
+    presentation: KILO_PRESENTATION,
+    enabled: true,
+    checkedAt,
+    models: allModels,
+    probe: {
+      installed: true,
+      version: parsedVersion,
+      status: "ready",
+      auth: {
+        status: "authenticated",
+        type: "kilo",
+      },
+      message: parsedVersion
+        ? `Kilo v${parsedVersion} detected.`
+        : "Kilo CLI detected.",
+    },
+  });
+});
+
+export const makePendingKiloProvider = (kiloSettings: KiloSettings): ServerProviderDraft => {
+  const checkedAt = new Date().toISOString();
+  const models = providerModelsFromSettings(
+    [],
+    PROVIDER,
+    kiloSettings.customModels,
+    DEFAULT_KILO_MODEL_CAPABILITIES,
+  );
+
+  if (!kiloSettings.enabled) {
+    return buildServerProvider({
+      presentation: KILO_PRESENTATION,
+      enabled: false,
+      checkedAt,
+      models,
+      probe: {
+        installed: false,
+        version: null,
+        status: "warning",
+        auth: { status: "unknown" },
+        message: "Kilo is disabled in T3 Code settings.",
+      },
+    });
+  }
+
+  return buildServerProvider({
+    presentation: KILO_PRESENTATION,
+    enabled: true,
+    checkedAt,
+    models,
+    probe: {
+      installed: false,
+      version: null,
+      status: "warning",
+      auth: { status: "unknown" },
+      message: "Kilo provider status has not been checked in this session yet.",
+    },
+  });
+};
diff --git a/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
index 9a391b55394..370e5c028ff 100644
--- a/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
@@ -2,14 +2,20 @@ import assert from "node:assert/strict";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
-import { Effect, Layer, Option } from "effect";
+import { Context, Effect, Exit, Fiber, Layer, Option, Schema, Scope, Stream } from "effect";
 import { beforeEach } from "vitest";
 
-import { ThreadId } from "@t3tools/contracts";
+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 { OpenCodeAdapter } from "../Services/OpenCodeAdapter.ts";
+import type { OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
 import {
   OpenCodeRuntime,
   OpenCodeRuntimeError,
@@ -17,10 +23,15 @@ import {
 } from "../opencodeRuntime.ts";
 import {
   appendOpenCodeAssistantTextDelta,
-  makeOpenCodeAdapterLive,
+  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 = {
@@ -39,6 +50,7 @@ const runtimeMock = {
     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[],
@@ -51,6 +63,7 @@ const runtimeMock = {
     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 = [];
@@ -111,7 +124,8 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
         abort: async ({ sessionID }: { sessionID: string }) => {
           runtimeMock.state.abortCalls.push(sessionID);
         },
-        promptAsync: async () => {
+        promptAsync: async (input: unknown) => {
+          runtimeMock.state.promptCalls.push(input);
           if (runtimeMock.state.promptAsyncError) {
             throw runtimeMock.state.promptAsyncError;
           }
@@ -165,7 +179,24 @@ const providerSessionDirectoryTestLayer = Layer.succeed(ProviderSessionDirectory
   listBindings: () => Effect.succeed([]),
 });
 
-const OpenCodeAdapterTestLayer = makeOpenCodeAdapterLive().pipe(
+// 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,
+  Effect.gen(function* () {
+    return yield* makeOpenCodeAdapter(openCodeAdapterTestSettings);
+  }),
+).pipe(
   Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
   Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
   Layer.provideMerge(
@@ -196,7 +227,7 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
       const adapter = yield* OpenCodeAdapter;
 
       const session = yield* adapter.startSession({
-        provider: "opencode",
+        provider: ProviderDriverKind.make("opencode"),
         threadId: asThreadId("thread-opencode"),
         runtimeMode: "full-access",
       });
@@ -215,7 +246,7 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     Effect.gen(function* () {
       const adapter = yield* OpenCodeAdapter;
       yield* adapter.startSession({
-        provider: "opencode",
+        provider: ProviderDriverKind.make("opencode"),
         threadId: asThreadId("thread-opencode"),
         runtimeMode: "full-access",
       });
@@ -230,16 +261,42 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     }),
   );
 
+  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: "opencode",
+        provider: ProviderDriverKind.make("opencode"),
         threadId: asThreadId("thread-stop-all-a"),
         runtimeMode: "full-access",
       });
       yield* adapter.startSession({
-        provider: "opencode",
+        provider: ProviderDriverKind.make("opencode"),
         threadId: asThreadId("thread-stop-all-b"),
         runtimeMode: "full-access",
       });
@@ -261,11 +318,44 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     }),
   );
 
+  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: "opencode",
+        provider: ProviderDriverKind.make("opencode"),
         threadId: asThreadId("thread-send-turn-failure"),
         runtimeMode: "full-access",
       });
@@ -276,7 +366,7 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
           threadId: asThreadId("thread-send-turn-failure"),
           input: "Fix it",
           modelSelection: {
-            provider: "opencode",
+            instanceId: ProviderInstanceId.make("opencode"),
             model: "openai/gpt-5",
           },
         })
@@ -299,12 +389,158 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     }),
   );
 
+  it.effect("passes agent and variant options for the adapter's bound custom instance id", () => {
+    const customInstanceId = ProviderInstanceId.make("opencode_zen");
+    const adapterLayer = Layer.effect(
+      OpenCodeAdapter,
+      Effect.gen(function* () {
+        return yield* makeOpenCodeAdapter(openCodeAdapterTestSettings, {
+          instanceId: customInstanceId,
+        });
+      }),
+    ).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 customInstanceId = ProviderInstanceId.make("opencode_zen");
+    const adapterLayer = Layer.effect(
+      OpenCodeAdapter,
+      Effect.gen(function* () {
+        return yield* makeOpenCodeAdapter(openCodeAdapterTestSettings, {
+          instanceId: customInstanceId,
+        });
+      }),
+    ).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 customInstanceId = ProviderInstanceId.make("opencode_zen");
+    const adapterLayer = Layer.effect(
+      OpenCodeAdapter,
+      Effect.gen(function* () {
+        return yield* makeOpenCodeAdapter(openCodeAdapterTestSettings, {
+          instanceId: customInstanceId,
+        });
+      }),
+    ).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: "opencode",
+        provider: ProviderDriverKind.make("opencode"),
         threadId,
         runtimeMode: "full-access",
       });
@@ -396,9 +632,14 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
         close: () => Effect.void,
       };
 
-      const adapterLayer = makeOpenCodeAdapterLive({
-        nativeEventLogger,
-      }).pipe(
+      const adapterLayer = Layer.effect(
+        OpenCodeAdapter,
+        Effect.gen(function* () {
+          return yield* makeOpenCodeAdapter(openCodeAdapterTestSettings, {
+            nativeEventLogger,
+          });
+        }),
+      ).pipe(
         Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
         Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
         Layer.provideMerge(
@@ -419,7 +660,7 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
       const session = yield* Effect.gen(function* () {
         const adapter = yield* OpenCodeAdapter;
         const started = yield* adapter.startSession({
-          provider: "opencode",
+          provider: ProviderDriverKind.make("opencode"),
           threadId: asThreadId("thread-native-log"),
           runtimeMode: "full-access",
         });
@@ -475,9 +716,12 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
         close: () => Effect.void,
       };
 
-      const adapterLayer = makeOpenCodeAdapterLive({
-        nativeEventLogger,
-      }).pipe(
+      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(
@@ -504,7 +748,7 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
       const { sessions, closeCallsDuringRun } = yield* Effect.gen(function* () {
         const adapter = yield* OpenCodeAdapter;
         yield* adapter.startSession({
-          provider: "opencode",
+          provider: ProviderDriverKind.make("opencode"),
           threadId: asThreadId("thread-native-log-failure"),
           runtimeMode: "full-access",
         });
diff --git a/apps/server/src/provider/Layers/OpenCodeAdapter.ts b/apps/server/src/provider/Layers/OpenCodeAdapter.ts
index 9412146036b..a7b179ab1c3 100644
--- a/apps/server/src/provider/Layers/OpenCodeAdapter.ts
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.ts
@@ -1,7 +1,8 @@
-import { randomUUID } from "node:crypto";
-
 import {
   EventId,
+  type OpenCodeSettings,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ProviderRuntimeEvent,
   type ProviderSession,
   RuntimeItemId,
@@ -11,12 +12,12 @@ import {
   TurnId,
   type UserInputQuestion,
 } from "@t3tools/contracts";
-import { Cause, Effect, Exit, Layer, Queue, Ref, Scope, Stream } from "effect";
+import { Cause, Effect, Exit, Queue, Random, Ref, Scope, Stream } from "effect";
 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 { ServerSettingsService } from "../../serverSettings.ts";
 import { type EventNdjsonLogger, makeEventNdjsonLogger } from "./EventNdjsonLogger.ts";
 import {
   ProviderAdapterProcessError,
@@ -25,8 +26,7 @@ import {
   ProviderAdapterSessionNotFoundError,
   ProviderAdapterValidationError,
 } from "../Errors.ts";
-import { OpenCodeAdapter, type OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
+import { type OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
 import {
   buildOpenCodePermissionRules,
   OpenCodeRuntime,
@@ -41,7 +41,7 @@ import {
   type OpenCodeServerConnection,
 } from "../opencodeRuntime.ts";
 
-const PROVIDER = "opencode" as const;
+const PROVIDER = ProviderDriverKind.make("opencode");
 
 interface OpenCodeTurnSnapshot {
   readonly id: TurnId;
@@ -89,6 +89,8 @@ interface OpenCodeSessionContext {
 }
 
 export interface OpenCodeAdapterLiveOptions {
+  readonly instanceId?: ProviderInstanceId;
+  readonly environment?: NodeJS.ProcessEnv;
   readonly nativeEventLogPath?: string;
   readonly nativeEventLogger?: EventNdjsonLogger;
 }
@@ -125,35 +127,38 @@ const toProcessError = (threadId: ThreadId, cause: unknown): ProviderAdapterProc
     cause,
   });
 
-function buildEventBase(input: {
+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;
-}): Pick<
-  ProviderRuntimeEvent,
-  "eventId" | "provider" | "threadId" | "createdAt" | "turnId" | "itemId" | "requestId" | "raw"
-> {
-  return {
-    eventId: EventId.make(randomUUID()),
-    provider: PROVIDER,
-    threadId: input.threadId,
-    createdAt: input.createdAt ?? nowIso(),
-    ...(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,
-          },
-        }
-      : {}),
-  };
-}
+}): Effect.Effect<
+  Pick<
+    ProviderRuntimeEvent,
+    "eventId" | "provider" | "threadId" | "createdAt" | "turnId" | "itemId" | "requestId" | "raw"
+  >
+> =>
+  Random.nextUUIDv4.pipe(
+    Effect.map((uuid) => ({
+      eventId: EventId.make(uuid),
+      provider: PROVIDER,
+      threadId: input.threadId,
+      createdAt: input.createdAt ?? nowIso(),
+      ...(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();
@@ -245,13 +250,19 @@ function ensureSessionContext(
 ): OpenCodeSessionContext {
   const session = sessions.get(threadId);
   if (!session) {
-    throw new ProviderAdapterSessionNotFoundError({ provider: PROVIDER, threadId });
+    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 });
+    throw new ProviderAdapterSessionClosedError({
+      provider: PROVIDER,
+      threadId,
+    });
   }
   return session;
 }
@@ -419,7 +430,7 @@ const stopOpenCodeContext = Effect.fn("stopOpenCodeContext")(function* (
 ) {
   // Race-safe one-shot: first caller flips the flag, everyone else no-ops.
   if (yield* Ref.getAndSet(context.stopped, true)) {
-    return;
+    return false;
   }
 
   // Best-effort remote abort. The scope close below tears down the local
@@ -433,955 +444,990 @@ const stopOpenCodeContext = Effect.fn("stopOpenCodeContext")(function* (
   // 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 makeOpenCodeAdapterLive(options?: OpenCodeAdapterLiveOptions) {
-  return Layer.effect(
-    OpenCodeAdapter,
-    Effect.gen(function* () {
-      const serverConfig = yield* ServerConfig;
-      const serverSettings = yield* ServerSettingsService;
-      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();
-          }
-        }),
-      );
-
-      const emit = (event: ProviderRuntimeEvent) =>
-        Queue.offer(runtimeEvents, event).pipe(Effect.asVoid);
-      const writeNativeEvent = (
-        threadId: ThreadId,
-        event: {
-          readonly observedAt: string;
-          readonly event: Record<string, unknown>;
+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",
         },
-      ) => (nativeEventLogger ? nativeEventLogger.write(event, threadId) : Effect.void);
-      const writeNativeEventBestEffort = (
-        threadId: ThreadId,
-        event: {
-          readonly observedAt: string;
-          readonly event: Record<string, unknown>;
+      }).pipe(Effect.ignore);
+      yield* emit({
+        ...(yield* buildEventBase({
+          threadId: context.session.threadId,
+          turnId,
+        })),
+        type: "session.exited",
+        payload: {
+          reason: message,
+          recoverable: false,
+          exitKind: "error",
         },
-      ) => 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.
+      }).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({
-          ...buildEventBase({ threadId: context.session.threadId, turnId }),
-          type: "runtime.error",
+          ...(yield* buildEventBase({
+            threadId: context.session.threadId,
+            turnId,
+            itemId: part.id,
+            createdAt:
+              part.type === "text" || part.type === "reasoning"
+                ? isoFromEpochMs(part.time?.start)
+                : undefined,
+            raw,
+          })),
+          type: "content.delta",
           payload: {
-            message,
-            class: "transport_error",
+            streamKind: resolveTextStreamKind(part),
+            delta: deltaToEmit,
           },
-        }).pipe(Effect.ignore);
+        });
+      }
+
+      if (
+        part.type === "text" &&
+        part.time?.end !== undefined &&
+        !context.completedAssistantPartIds.has(part.id)
+      ) {
+        context.completedAssistantPartIds.add(part.id);
         yield* emit({
-          ...buildEventBase({ threadId: context.session.threadId, turnId }),
-          type: "session.exited",
+          ...(yield* buildEventBase({
+            threadId: context.session.threadId,
+            turnId,
+            itemId: part.id,
+            createdAt: isoFromEpochMs(part.time.end),
+            raw,
+          })),
+          type: "item.completed",
           payload: {
-            reason: message,
-            recoverable: false,
-            exitKind: "error",
+            itemType: "assistant_message",
+            status: "completed",
+            title: "Assistant message",
+            ...(latestText.length > 0 ? { detail: latestText } : {}),
           },
-        }).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);
+        });
+      }
+    });
+
+    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: nowIso(),
+        event: {
+          provider: PROVIDER,
+          threadId: context.session.threadId,
+          providerThreadId: context.openCodeSessionId,
+          type: event.type,
+          ...(turnId ? { turnId } : {}),
+          payload: event,
+        },
       });
 
-      /** 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;
+      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;
         }
-        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,
-          );
+
+        case "message.removed": {
+          context.messageRoleById.delete(event.properties.messageID);
+          break;
         }
-        if (deltaToEmit.length > 0) {
+
+        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({
-            ...buildEventBase({
+            ...(yield* buildEventBase({
               threadId: context.session.threadId,
               turnId,
-              itemId: part.id,
-              createdAt:
-                part.type === "text" || part.type === "reasoning"
-                  ? isoFromEpochMs(part.time?.start)
-                  : undefined,
-              raw,
-            }),
+              itemId: event.properties.partID,
+              raw: event,
+            })),
             type: "content.delta",
             payload: {
-              streamKind: resolveTextStreamKind(part),
+              streamKind,
               delta: deltaToEmit,
             },
           });
+          break;
         }
 
-        if (
-          part.type === "text" &&
-          part.time?.end !== undefined &&
-          !context.completedAssistantPartIds.has(part.id)
-        ) {
-          context.completedAssistantPartIds.add(part.id);
+        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({
-            ...buildEventBase({
+            ...(yield* buildEventBase({
               threadId: context.session.threadId,
               turnId,
-              itemId: part.id,
-              createdAt: isoFromEpochMs(part.time.end),
-              raw,
-            }),
-            type: "item.completed",
+              requestId: event.properties.id,
+              raw: event,
+            })),
+            type: "request.opened",
             payload: {
-              itemType: "assistant_message",
-              status: "completed",
-              title: "Assistant message",
-              ...(latestText.length > 0 ? { detail: latestText } : {}),
+              requestType: mapPermissionToRequestType(event.properties.permission),
+              detail:
+                event.properties.patterns.length > 0
+                  ? event.properties.patterns.join("\n")
+                  : event.properties.permission,
+              args: event.properties.metadata,
             },
           });
+          break;
         }
-      });
 
-      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;
+        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;
         }
 
-        const turnId = context.activeTurnId;
-        yield* writeNativeEventBestEffort(context.session.threadId, {
-          observedAt: nowIso(),
-          event: {
-            provider: PROVIDER,
-            threadId: context.session.threadId,
-            providerThreadId: context.openCodeSessionId,
-            type: event.type,
-            ...(turnId ? { turnId } : {}),
-            payload: event,
-          },
-        });
+        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;
+        }
 
-        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 "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 "message.removed": {
-            context.messageRoleById.delete(event.properties.messageID);
-            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 "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({
-              ...buildEventBase({
-                threadId: context.session.threadId,
-                turnId,
-                itemId: event.properties.partID,
-                raw: event,
-              }),
-              type: "content.delta",
-              payload: {
-                streamKind,
-                delta: deltaToEmit,
-              },
+        case "session.status": {
+          if (event.properties.status.type === "busy") {
+            updateProviderSession(context, {
+              status: "running",
+              activeTurnId: turnId,
             });
-            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 = {
-                ...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);
+          if (event.properties.status.type === "retry") {
             yield* emit({
-              ...buildEventBase({
+              ...(yield* buildEventBase({
                 threadId: context.session.threadId,
                 turnId,
-                requestId: event.properties.id,
                 raw: event,
-              }),
-              type: "request.opened",
+              })),
+              type: "runtime.warning",
               payload: {
-                requestType: mapPermissionToRequestType(event.properties.permission),
-                detail:
-                  event.properties.patterns.length > 0
-                    ? event.properties.patterns.join("\n")
-                    : event.properties.permission,
-                args: event.properties.metadata,
+                message: event.properties.status.message,
+                detail: event.properties.status,
               },
             });
             break;
           }
 
-          case "permission.replied": {
-            context.pendingPermissions.delete(event.properties.requestID);
+          if (event.properties.status.type === "idle" && turnId) {
+            context.activeTurnId = undefined;
+            updateProviderSession(context, { status: "ready" }, { clearActiveTurnId: true });
             yield* emit({
-              ...buildEventBase({
+              ...(yield* buildEventBase({
                 threadId: context.session.threadId,
                 turnId,
-                requestId: event.properties.requestID,
                 raw: event,
-              }),
-              type: "request.resolved",
+              })),
+              type: "turn.completed",
               payload: {
-                requestType: "unknown",
-                decision: mapPermissionDecision(event.properties.reply),
+                state: "completed",
               },
             });
-            break;
           }
+          break;
+        }
 
-          case "question.asked": {
-            context.pendingQuestions.set(event.properties.id, event.properties);
+        case "session.error": {
+          const message = sessionErrorMessage(event.properties.error);
+          const activeTurnId = context.activeTurnId;
+          context.activeTurnId = undefined;
+          updateProviderSession(
+            context,
+            {
+              status: "error",
+              lastError: message,
+            },
+            { clearActiveTurnId: true },
+          );
+          if (activeTurnId) {
             yield* emit({
-              ...buildEventBase({
+              ...(yield* buildEventBase({
                 threadId: context.session.threadId,
-                turnId,
-                requestId: event.properties.id,
+                turnId: activeTurnId,
                 raw: event,
-              }),
-              type: "user-input.requested",
+              })),
+              type: "turn.completed",
               payload: {
-                questions: normalizeQuestionRequest(event.properties),
+                state: "failed",
+                errorMessage: message,
               },
             });
-            break;
           }
+          yield* emit({
+            ...(yield* buildEventBase({
+              threadId: context.session.threadId,
+              raw: event,
+            })),
+            type: "runtime.error",
+            payload: {
+              message,
+              class: "provider_error",
+              detail: event.properties.error,
+            },
+          });
+          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({
-              ...buildEventBase({
-                threadId: context.session.threadId,
-                turnId,
-                requestId: event.properties.requestID,
-                raw: event,
-              }),
-              type: "user-input.resolved",
-              payload: { answers },
-            });
-            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()),
+      );
 
-          case "question.rejected": {
-            context.pendingQuestions.delete(event.properties.requestID);
-            yield* emit({
-              ...buildEventBase({
-                threadId: context.session.threadId,
-                turnId,
-                requestId: event.properties.requestID,
-                raw: event,
+      // 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,
               }),
-              type: "user-input.resolved",
-              payload: { answers: {} },
-            });
-            break;
-          }
-
-          case "session.status": {
-            if (event.properties.status.type === "busy") {
-              updateProviderSession(context, { status: "running", activeTurnId: turnId });
+          ).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 (event.properties.status.type === "retry") {
-              yield* emit({
-                ...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;
-              updateProviderSession(context, { status: "ready" }, { clearActiveTurnId: true });
-              yield* emit({
-                ...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;
-            updateProviderSession(
-              context,
-              {
-                status: "error",
-                lastError: message,
-              },
-              { clearActiveTurnId: true },
-            );
-            if (activeTurnId) {
-              yield* emit({
-                ...buildEventBase({
-                  threadId: context.session.threadId,
-                  turnId: activeTurnId,
-                  raw: event,
-                }),
-                type: "turn.completed",
-                payload: {
-                  state: "failed",
-                  errorMessage: message,
-                },
-              });
+            if (Exit.isFailure(exit)) {
+              yield* emitUnexpectedExit(
+                context,
+                openCodeRuntimeErrorDetail(Cause.squash(exit.cause)),
+              );
             }
-            yield* emit({
-              ...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()),
-        );
+          }),
+        ),
+        Effect.forkIn(context.sessionScope),
+      );
 
-        // 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) =>
+      if (!context.server.external && context.server.exitCode !== null) {
+        yield* context.server.exitCode.pipe(
+          Effect.flatMap((code) =>
             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))) {
+              if (yield* Ref.get(context.stopped)) {
                 return;
               }
-              if (Exit.isFailure(exit)) {
-                yield* emitUnexpectedExit(
-                  context,
-                  openCodeRuntimeErrorDetail(Cause.squash(exit.cause)),
-                );
-              }
+              yield* emitUnexpectedExit(context, `OpenCode server exited unexpectedly (${code}).`);
             }),
           ),
           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 startSession: OpenCodeAdapterShape["startSession"] = Effect.fn("startSession")(
-        function* (input) {
-          const settings = yield* serverSettings.getSettings.pipe(
-            Effect.mapError(
-              (cause) =>
-                new ProviderAdapterProcessError({
-                  provider: PROVIDER,
-                  threadId: input.threadId,
-                  detail: "Failed to read OpenCode settings.",
-                  cause,
+        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),
                 }),
-            ),
-          );
-          const binaryPath = settings.providers.opencode.binaryPath;
-          const serverUrl = settings.providers.opencode.serverUrl;
-          const serverPassword = settings.providers.opencode.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,
-                });
-                const client = openCodeRuntime.createOpenCodeSdkClient({
-                  baseUrl: server.url,
-                  directory,
-                  ...(server.external && serverPassword ? { serverPassword } : {}),
+              );
+              if (!openCodeSession.data) {
+                return yield* new OpenCodeRuntimeError({
+                  operation: "session.create",
+                  detail: "OpenCode session.create returned no session payload.",
                 });
-                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;
+              }
+              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;
+        });
 
-          const createdAt = nowIso();
-          const session: ProviderSession = {
-            provider: PROVIDER,
-            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({
-            ...buildEventBase({ threadId: input.threadId }),
-            type: "session.started",
-            payload: {
-              message: "OpenCode session started",
-            },
-          });
-          yield* emit({
-            ...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-${randomUUID()}`);
-        const modelSelection =
-          input.modelSelection ??
-          (context.session.model
-            ? { provider: PROVIDER, model: context.session.model }
-            : undefined);
-        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.",
-          });
+        // 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 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 createdAt = 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 agent =
-          input.modelSelection?.provider === PROVIDER
-            ? input.modelSelection.options?.agent
-            : undefined;
-        const variant =
-          input.modelSelection?.provider === PROVIDER
-            ? input.modelSelection.options?.variant
-            : undefined;
-
-        context.activeTurnId = turnId;
-        context.activeAgent = agent ?? (input.interactionMode === "plan" ? "plan" : undefined);
-        context.activeVariant = variant;
-        updateProviderSession(
-          context,
-          {
-            status: "running",
-            activeTurnId: turnId,
-            model: modelSelection?.model ?? context.session.model,
-          },
-          { clearLastError: true },
-        );
+        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({
-          ...buildEventBase({ threadId: input.threadId, turnId }),
-          type: "turn.started",
+          ...(yield* buildEventBase({ threadId: input.threadId })),
+          type: "session.started",
+          payload: {
+            message: "OpenCode session started",
+          },
+        });
+        yield* emit({
+          ...(yield* buildEventBase({ threadId: input.threadId })),
+          type: "thread.started",
           payload: {
-            model: modelSelection?.model ?? context.session.model,
-            ...(variant ? { effort: variant } : {}),
+            providerThreadId: started.openCodeSession.id,
           },
         });
 
-        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],
+        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,
           }),
-        ).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;
-              updateProviderSession(
-                context,
-                {
-                  status: "ready",
-                  model: modelSelection?.model ?? context.session.model,
-                  lastError: requestError.detail,
-                },
-                { clearActiveTurnId: true },
-              );
-              yield* emit({
-                ...buildEventBase({ threadId: input.threadId, turnId }),
-                type: "turn.aborted",
-                payload: {
-                  reason: requestError.detail,
-                },
-              });
-            }),
-          ),
-        );
+      });
+      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;
+      updateProviderSession(
+        context,
+        {
+          status: "running",
+          activeTurnId: turnId,
+          model: modelSelection?.model ?? context.session.model,
+        },
+        { clearLastError: true },
+      );
 
-        return {
-          threadId: input.threadId,
-          turnId,
-        };
+      yield* emit({
+        ...(yield* buildEventBase({ threadId: input.threadId, turnId })),
+        type: "turn.started",
+        payload: {
+          model: modelSelection?.model ?? context.session.model,
+          ...(variant ? { effort: variant } : {}),
+        },
       });
 
-      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* 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;
+            updateProviderSession(
+              context,
+              {
+                status: "ready",
+                model: modelSelection?.model ?? context.session.model,
+                lastError: requestError.detail,
+              },
+              { clearActiveTurnId: true },
+            );
             yield* emit({
-              ...buildEventBase({ threadId, turnId: turnId ?? context.activeTurnId }),
+              ...(yield* buildEventBase({
+                threadId: input.threadId,
+                turnId,
+              })),
               type: "turn.aborted",
               payload: {
-                reason: "Interrupted by user.",
+                reason: requestError.detail,
               },
             });
-          }
-        },
+          }),
+        ),
       );
 
-      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));
-      });
+      return {
+        threadId: input.threadId,
+        turnId,
+      };
+    });
 
-      const respondToUserInput: OpenCodeAdapterShape["respondToUserInput"] = Effect.fn(
-        "respondToUserInput",
-      )(function* (threadId, requestId, answers) {
+    const interruptTurn: OpenCodeAdapterShape["interruptTurn"] = Effect.fn("interruptTurn")(
+      function* (threadId, turnId) {
         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),
-          }),
+        yield* runOpenCodeSdk("session.abort", () =>
+          context.client.session.abort({ sessionID: context.openCodeSessionId }),
         ).pipe(Effect.mapError(toRequestError));
-      });
-
-      const stopSession: OpenCodeAdapterShape["stopSession"] = Effect.fn("stopSession")(
-        function* (threadId) {
-          const context = ensureSessionContext(sessions, threadId);
-          yield* stopOpenCodeContext(context);
-          sessions.delete(threadId);
+        if (turnId ?? context.activeTurnId) {
           yield* emit({
-            ...buildEventBase({ threadId }),
-            type: "session.exited",
+            ...(yield* buildEventBase({
+              threadId,
+              turnId: turnId ?? context.activeTurnId,
+            })),
+            type: "turn.aborted",
             payload: {
-              reason: "Session stopped.",
-              recoverable: false,
-              exitKind: "graceful",
+              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}`,
+        });
+      }
 
-      const listSessions: OpenCodeAdapterShape["listSessions"] = () =>
-        Effect.sync(() => [...sessions.values()].map((context) => context.session));
+      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 hasSession: OpenCodeAdapterShape["hasSession"] = (threadId) =>
-        Effect.sync(() => sessions.has(threadId));
+    const listSessions: OpenCodeAdapterShape["listSessions"] = () =>
+      Effect.sync(() => [...sessions.values()].map((context) => context.session));
 
-      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 hasSession: OpenCodeAdapterShape["hasSession"] = (threadId) =>
+      Effect.sync(() => sessions.has(threadId));
 
-          const turns = (messages.data ?? [])
-            .filter((entry) => entry.info.role === "assistant")
-            .map((entry) => ({
-              id: TurnId.make(entry.info.id),
-              items: [entry.info, ...entry.parts],
-            }));
+    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));
 
-          return {
-            threadId,
-            turns,
-          };
-        },
-      );
+        const turns = (messages.data ?? [])
+          .filter((entry) => entry.info.role === "assistant")
+          .map((entry) => ({
+            id: TurnId.make(entry.info.id),
+            items: [entry.info, ...entry.parts],
+          }));
 
-      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));
+        return {
+          threadId,
+          turns,
+        };
+      },
+    );
 
-          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));
+    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));
 
-          return yield* readThread(threadId);
-        },
-      );
+        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));
 
-      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 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: getProviderCapabilities(PROVIDER),
-        startSession,
-        sendTurn,
-        interruptTurn,
-        respondToRequest,
-        respondToUserInput,
-        stopSession,
-        listSessions,
-        hasSession,
-        readThread,
-        rollbackThread,
-        stopAll,
-        get streamEvents() {
-          return Stream.fromQueue(runtimeEvents);
-        },
-      } satisfies OpenCodeAdapterShape;
-    }),
-  );
+    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;
+  });
 }
-
-export const OpenCodeAdapterLive = makeOpenCodeAdapterLive();
diff --git a/apps/server/src/provider/Layers/OpenCodeProvider.test.ts b/apps/server/src/provider/Layers/OpenCodeProvider.test.ts
index ffce7084342..7abe0be9816 100644
--- a/apps/server/src/provider/Layers/OpenCodeProvider.test.ts
+++ b/apps/server/src/provider/Layers/OpenCodeProvider.test.ts
@@ -2,24 +2,36 @@ import assert from "node:assert/strict";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
-import { Effect, Layer } from "effect";
+import { Effect, Layer, Schema } from "effect";
 import { beforeEach } from "vitest";
 
+import { OpenCodeSettings } from "@t3tools/contracts";
 import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { OpenCodeProvider } from "../Services/OpenCodeProvider.ts";
 import {
   OpenCodeRuntime,
   OpenCodeRuntimeError,
   type OpenCodeRuntimeShape,
 } from "../opencodeRuntime.ts";
-import { OpenCodeProviderLive } from "./OpenCodeProvider.ts";
+import { checkOpenCodeProviderStatus } from "./OpenCodeProvider.ts";
 import type { OpenCodeInventory } from "../opencodeRuntime.ts";
 
+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[],
@@ -27,7 +39,9 @@ const runtimeMock = {
   },
   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[],
@@ -42,10 +56,19 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
       exitCode: Effect.never,
     }),
   connectToOpenCodeServer: ({ serverUrl }) =>
-    Effect.succeed({
-      url: serverUrl ?? "http://127.0.0.1:4301",
-      exitCode: null,
-      external: Boolean(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
@@ -56,7 +79,7 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
             cause: runtimeMock.state.runVersionError,
           }),
         )
-      : Effect.succeed({ stdout: "opencode 1.0.0\n", stderr: "", code: 0 }),
+      : Effect.succeed({ stdout: runtimeMock.state.versionStdout, stderr: "", code: 0 }),
   createOpenCodeSdkClient: () =>
     ({}) as unknown as ReturnType<OpenCodeRuntimeShape["createOpenCodeSdkClient"]>,
   loadOpenCodeInventory: () =>
@@ -75,20 +98,26 @@ beforeEach(() => {
   runtimeMock.reset();
 });
 
-const makeTestLayer = (settingsOverrides?: Parameters<typeof ServerSettingsService.layerTest>[0]) =>
-  OpenCodeProviderLive.pipe(
-    Layer.provideMerge(Layer.succeed(OpenCodeRuntime, OpenCodeRuntimeTestDouble)),
-    Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
-    Layer.provideMerge(ServerSettingsService.layerTest(settingsOverrides)),
-    Layer.provideMerge(NodeServices.layer),
-  );
-
-it.layer(makeTestLayer())("OpenCodeProviderLive", (it) => {
+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 =>
+  Schema.decodeSync(OpenCodeSettings)({
+    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 provider = yield* OpenCodeProvider;
-      const snapshot = yield* provider.refresh;
+      const snapshot = yield* checkOpenCodeProviderStatus(makeOpenCodeSettings(), process.cwd());
 
       assert.equal(snapshot.status, "error");
       assert.equal(snapshot.installed, false);
@@ -99,8 +128,7 @@ it.layer(makeTestLayer())("OpenCodeProviderLive", (it) => {
   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 provider = yield* OpenCodeProvider;
-      const snapshot = yield* provider.refresh;
+      const snapshot = yield* checkOpenCodeProviderStatus(makeOpenCodeSettings(), process.cwd());
 
       assert.equal(snapshot.status, "error");
       assert.equal(snapshot.installed, true);
@@ -140,38 +168,49 @@ it.layer(makeTestLayer())("OpenCodeProviderLive", (it) => {
         ],
       };
 
-      const provider = yield* OpenCodeProvider;
-      const snapshot = yield* provider.refresh;
+      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(
-        model.capabilities?.variantOptions?.find((option) => option.isDefault)?.value,
+        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(
-        model.capabilities?.agentOptions?.find((option) => option.isDefault)?.value,
+        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(
-  makeTestLayer({
-    providers: {
-      opencode: {
-        serverUrl: "http://127.0.0.1:9999",
-        serverPassword: "secret-password",
-      },
-    },
-  }),
-)("OpenCodeProviderLive with configured server URL", (it) => {
+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 provider = yield* OpenCodeProvider;
-      const snapshot = yield* provider.refresh;
+      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);
@@ -187,8 +226,13 @@ it.layer(
       runtimeMock.state.inventoryError = new Error(
         "fetch failed: connect ECONNREFUSED 127.0.0.1:9999",
       );
-      const provider = yield* OpenCodeProvider;
-      const snapshot = yield* provider.refresh;
+      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);
diff --git a/apps/server/src/provider/Layers/OpenCodeProvider.ts b/apps/server/src/provider/Layers/OpenCodeProvider.ts
index 5e51eae0282..c7487d7d526 100644
--- a/apps/server/src/provider/Layers/OpenCodeProvider.ts
+++ b/apps/server/src/provider/Layers/OpenCodeProvider.ts
@@ -1,20 +1,21 @@
-import type {
-  ModelCapabilities,
-  OpenCodeSettings,
-  ServerProvider,
-  ServerProviderModel,
+import {
+  ProviderDriverKind,
+  type ModelCapabilities,
+  type OpenCodeSettings,
+  type ServerProviderModel,
 } from "@t3tools/contracts";
-import { Cause, Data, Effect, Equal, Layer, Stream } from "effect";
+import { Cause, Data, Effect } from "effect";
+
+import { createModelCapabilities } from "@t3tools/shared/model";
 
-import { ServerConfig } from "../../config.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { makeManagedServerProvider } from "../makeManagedServerProvider.ts";
 import {
   buildServerProvider,
+  nonEmptyTrimmed,
   parseGenericCliVersion,
   providerModelsFromSettings,
+  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
-import { OpenCodeProvider } from "../Services/OpenCodeProvider.ts";
+import { compareCliVersions } from "../cliVersion.ts";
 import {
   OpenCodeRuntime,
   openCodeRuntimeErrorDetail,
@@ -22,7 +23,12 @@ import {
 } from "../opencodeRuntime.ts";
 import type { Agent, ProviderListResponse } from "@opencode-ai/sdk/v2";
 
-const PROVIDER = "opencode" as const;
+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;
@@ -156,13 +162,9 @@ 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 = {
-  reasoningEffortLevels: [],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-};
+const DEFAULT_OPENCODE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
 
 function openCodeCapabilitiesForModel(input: {
   readonly providerID: string;
@@ -171,27 +173,46 @@ function openCodeCapabilitiesForModel(input: {
 }): ModelCapabilities {
   const variantValues = Object.keys(input.model.variants ?? {});
   const defaultVariant = inferDefaultVariant(input.providerID, variantValues);
-  const variantOptions: ModelCapabilities["variantOptions"] = variantValues.map((value) =>
-    Object.assign(
-      { value, label: titleCaseSlug(value) },
-      defaultVariant === value ? { isDefault: true } : {},
-    ),
+  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: ModelCapabilities["agentOptions"] = primaryAgents.map((agent) =>
-    Object.assign(
-      { value: agent.name, label: titleCaseSlug(agent.name) },
-      defaultAgent === agent.name ? { isDefault: true } : {},
-    ),
+  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 {
-    ...DEFAULT_OPENCODE_MODEL_CAPABILITIES,
-    ...(variantOptions.length > 0 ? { variantOptions } : {}),
-    ...(agentOptions.length > 0 ? { agentOptions } : {}),
-  };
+  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> {
@@ -204,10 +225,16 @@ function flattenOpenCodeModels(input: OpenCodeInventory): ReadonlyArray<ServerPr
     }
 
     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: model.name,
-        subProvider: provider.name,
+        name,
+        ...(subProvider ? { subProvider } : {}),
         isCustom: false,
         capabilities: openCodeCapabilitiesForModel({
           providerID: provider.id,
@@ -221,7 +248,9 @@ function flattenOpenCodeModels(input: OpenCodeInventory): ReadonlyArray<ServerPr
   return models.toSorted((left, right) => left.name.localeCompare(right.name));
 }
 
-const makePendingOpenCodeProvider = (openCodeSettings: OpenCodeSettings): ServerProvider => {
+export const makePendingOpenCodeProvider = (
+  openCodeSettings: OpenCodeSettings,
+): ServerProviderDraft => {
   const checkedAt = new Date().toISOString();
   const models = providerModelsFromSettings(
     [],
@@ -232,7 +261,7 @@ const makePendingOpenCodeProvider = (openCodeSettings: OpenCodeSettings): Server
 
   if (!openCodeSettings.enabled) {
     return buildServerProvider({
-      provider: PROVIDER,
+      presentation: OPENCODE_PRESENTATION,
       enabled: false,
       checkedAt,
       models,
@@ -250,7 +279,7 @@ const makePendingOpenCodeProvider = (openCodeSettings: OpenCodeSettings): Server
   }
 
   return buildServerProvider({
-    provider: PROVIDER,
+    presentation: OPENCODE_PRESENTATION,
     enabled: true,
     checkedAt,
     models,
@@ -264,177 +293,179 @@ const makePendingOpenCodeProvider = (openCodeSettings: OpenCodeSettings): Server
   });
 };
 
-export const OpenCodeProviderLive = Layer.effect(
-  OpenCodeProvider,
-  Effect.gen(function* () {
-    const serverSettings = yield* ServerSettingsService;
-    const serverConfig = yield* ServerConfig;
-    const openCodeRuntime = yield* OpenCodeRuntime;
-
-    const checkOpenCodeProviderStatus = Effect.fn("checkOpenCodeProviderStatus")(function* (input: {
-      readonly settings: OpenCodeSettings;
-      readonly cwd: string;
-    }): Effect.fn.Return<ServerProvider, never> {
-      const checkedAt = new Date().toISOString();
-      const customModels = input.settings.customModels;
-      const isExternalServer = input.settings.serverUrl.trim().length > 0;
-
-      const fallback = (cause: unknown, version: string | null = null) => {
-        const failure = formatOpenCodeProbeError({
-          cause,
-          isExternalServer,
-          serverUrl: input.settings.serverUrl,
-        });
-        return buildServerProvider({
-          provider: PROVIDER,
-          enabled: input.settings.enabled,
-          checkedAt,
-          models: providerModelsFromSettings(
-            [],
-            PROVIDER,
-            customModels,
-            DEFAULT_OPENCODE_MODEL_CAPABILITIES,
-          ),
-          probe: {
-            installed: failure.installed,
-            version,
-            status: "error",
-            auth: { status: "unknown" },
-            message: failure.message,
-          },
-        });
-      };
-
-      if (!input.settings.enabled) {
-        return buildServerProvider({
-          provider: PROVIDER,
-          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: input.settings.binaryPath,
-              args: ["--version"],
-            })
-            .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;
-      }
-
-      const inventoryExit = yield* Effect.exit(
-        Effect.scoped(
-          Effect.gen(function* () {
-            const server = yield* openCodeRuntime
-              .connectToOpenCodeServer({
-                binaryPath: input.settings.binaryPath,
-                serverUrl: input.settings.serverUrl,
-              })
-              .pipe(
-                Effect.mapError(
-                  (cause) =>
-                    new OpenCodeProbeError({ cause, detail: openCodeRuntimeErrorDetail(cause) }),
-                ),
-              );
-            return yield* openCodeRuntime
-              .loadOpenCodeInventory(
-                openCodeRuntime.createOpenCodeSdkClient({
-                  baseUrl: server.url,
-                  directory: input.cwd,
-                  ...(isExternalServer && input.settings.serverPassword
-                    ? { serverPassword: input.settings.serverPassword }
-                    : {}),
-                }),
-              )
-              .pipe(
-                Effect.mapError(
-                  (cause) =>
-                    new OpenCodeProbeError({ cause, detail: openCodeRuntimeErrorDetail(cause) }),
-                ),
-              );
-          }),
-        ),
-      );
-      if (inventoryExit._tag === "Failure") {
-        return fallback(Cause.squash(inventoryExit.cause), version);
-      }
+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 = new Date().toISOString();
+  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,
+      },
+    });
+  };
 
-      const models = providerModelsFromSettings(
-        flattenOpenCodeModels(inventoryExit.value),
+  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,
       );
-      const connectedCount = inventoryExit.value.providerList.connected.length;
+    }
+    if (compareCliVersions(version, MINIMUM_OPENCODE_VERSION) < 0) {
       return buildServerProvider({
-        provider: PROVIDER,
-        enabled: true,
+        presentation: OPENCODE_PRESENTATION,
+        enabled: openCodeSettings.enabled,
         checkedAt,
-        models,
+        models: providerModelsFromSettings(
+          [],
+          PROVIDER,
+          customModels,
+          DEFAULT_OPENCODE_MODEL_CAPABILITIES,
+        ),
         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.",
+          status: "error",
+          auth: { status: "unknown" },
+          message: `OpenCode v${version} is too old. Upgrade to v${MINIMUM_OPENCODE_VERSION} or newer.`,
         },
       });
-    });
+    }
+  }
 
-    const getProviderSettings = serverSettings.getSettings.pipe(
-      Effect.map((settings) => settings.providers.opencode),
-    );
+  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);
+  }
 
-    return yield* makeManagedServerProvider<OpenCodeSettings>({
-      getSettings: getProviderSettings.pipe(Effect.orDie),
-      streamSettings: serverSettings.streamChanges.pipe(
-        Stream.map((settings) => settings.providers.opencode),
-      ),
-      haveSettingsChanged: (previous, next) => !Equal.equals(previous, next),
-      initialSnapshot: makePendingOpenCodeProvider,
-      checkProvider: getProviderSettings.pipe(
-        Effect.flatMap((settings) =>
-          checkOpenCodeProviderStatus({
-            settings,
-            cwd: serverConfig.cwd,
-          }),
-        ),
-      ),
-    });
-  }),
-);
+  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/ProviderAdapterConformance.test.ts b/apps/server/src/provider/Layers/ProviderAdapterConformance.test.ts
deleted file mode 100644
index 24053e5844e..00000000000
--- a/apps/server/src/provider/Layers/ProviderAdapterConformance.test.ts
+++ /dev/null
@@ -1,159 +0,0 @@
-import * as NodeServices from "@effect/platform-node/NodeServices";
-import { Effect, Layer, Option } from "effect";
-import { describe, expect, it } from "vitest";
-
-import { AmpServerManager } from "../../ampServerManager.ts";
-import { GeminiCliServerManager } from "../../geminiCliServerManager.ts";
-import { ServerConfig } from "../../config.ts";
-import { makeAmpAdapterLive } from "./AmpAdapter.ts";
-import { makeClaudeAdapterLive } from "./ClaudeAdapter.ts";
-import { makeCodexAdapterLive } from "./CodexAdapter.ts";
-import { makeCopilotAdapterLive } from "./CopilotAdapter.ts";
-import { makeCursorAdapterLive } from "./CursorAdapter.ts";
-import { makeGeminiCliAdapterLive } from "./GeminiCliAdapter.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
-import { ProviderSessionDirectory } from "../Services/ProviderSessionDirectory.ts";
-import {
-  getProviderCapabilities,
-  validateProviderAdapterConformance,
-} from "../Services/ProviderAdapter.ts";
-import { AmpAdapter } from "../Services/AmpAdapter.ts";
-import { ClaudeAdapter } from "../Services/ClaudeAdapter.ts";
-import { CodexAdapter } from "../Services/CodexAdapter.ts";
-import { CopilotAdapter } from "../Services/CopilotAdapter.ts";
-import { CursorAdapter } from "../Services/CursorAdapter.ts";
-import { GeminiCliAdapter } from "../Services/GeminiCliAdapter.ts";
-
-const providerSessionDirectoryTestLayer = Layer.succeed(ProviderSessionDirectory, {
-  upsert: () => Effect.void,
-  getProvider: () =>
-    Effect.die(new Error("ProviderSessionDirectory.getProvider is not used in conformance tests")),
-  getBinding: () => Effect.succeed(Option.none()),
-  listThreadIds: () => Effect.succeed([]),
-  listBindings: () => Effect.succeed([]),
-});
-
-const codexLayer = makeCodexAdapterLive().pipe(
-  Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
-  Layer.provideMerge(providerSessionDirectoryTestLayer),
-  Layer.provideMerge(ServerSettingsService.layerTest()),
-  Layer.provideMerge(NodeServices.layer),
-);
-
-const copilotLayer = makeCopilotAdapterLive({
-  clientFactory: () =>
-    ({
-      start: async () => undefined,
-      listModels: async () => [],
-      createSession: async () => {
-        throw new Error("createSession should not be called in conformance tests");
-      },
-      resumeSession: async () => {
-        throw new Error("resumeSession should not be called in conformance tests");
-      },
-      stop: async () => [],
-    }) as never,
-}).pipe(
-  Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
-  Layer.provideMerge(ServerSettingsService.layerTest()),
-  Layer.provideMerge(NodeServices.layer),
-);
-
-const claudeLayer = makeClaudeAdapterLive({
-  createQuery: () =>
-    ({
-      [Symbol.asyncIterator]: async function* () {
-        yield* [] as never[];
-      },
-      interrupt: async () => undefined,
-      setModel: async () => undefined,
-      setPermissionMode: async () => undefined,
-      setMaxThinkingTokens: async () => undefined,
-      close: () => undefined,
-    }) as never,
-}).pipe(
-  Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
-  Layer.provideMerge(ServerSettingsService.layerTest()),
-  Layer.provideMerge(NodeServices.layer),
-);
-
-const cursorLayer = makeCursorAdapterLive().pipe(
-  Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
-  Layer.provideMerge(ServerSettingsService.layerTest()),
-  Layer.provideMerge(NodeServices.layer),
-);
-
-const geminiLayer = makeGeminiCliAdapterLive({
-  manager: new GeminiCliServerManager(),
-}).pipe(Layer.provideMerge(ServerSettingsService.layerTest()));
-
-const ampLayer = makeAmpAdapterLive({
-  manager: new AmpServerManager(),
-}).pipe(Layer.provideMerge(ServerSettingsService.layerTest()));
-
-describe("provider adapter conformance", () => {
-  const cases = [
-    {
-      provider: "codex" as const,
-      load: () =>
-        Effect.runPromise(
-          Effect.gen(function* () {
-            return yield* CodexAdapter;
-          }).pipe(Effect.provide(codexLayer)),
-        ),
-    },
-    {
-      provider: "copilot" as const,
-      load: () =>
-        Effect.runPromise(
-          Effect.gen(function* () {
-            return yield* CopilotAdapter;
-          }).pipe(Effect.provide(copilotLayer)),
-        ),
-    },
-    {
-      provider: "claudeAgent" as const,
-      load: () =>
-        Effect.runPromise(
-          Effect.gen(function* () {
-            return yield* ClaudeAdapter;
-          }).pipe(Effect.provide(claudeLayer)),
-        ),
-    },
-    {
-      provider: "cursor" as const,
-      load: () =>
-        Effect.runPromise(
-          Effect.gen(function* () {
-            return yield* CursorAdapter;
-          }).pipe(Effect.provide(cursorLayer)),
-        ),
-    },
-    {
-      provider: "geminiCli" as const,
-      load: () =>
-        Effect.runPromise(
-          Effect.gen(function* () {
-            return yield* GeminiCliAdapter;
-          }).pipe(Effect.provide(geminiLayer)),
-        ),
-    },
-    {
-      provider: "amp" as const,
-      load: () =>
-        Effect.runPromise(
-          Effect.gen(function* () {
-            return yield* AmpAdapter;
-          }).pipe(Effect.provide(ampLayer)),
-        ),
-    },
-  ];
-
-  it.each(cases)("declares the shared harness matrix for $provider", async ({ provider, load }) => {
-    const adapter = await load();
-
-    expect(validateProviderAdapterConformance(adapter)).toEqual([]);
-    expect(adapter.provider).toBe(provider);
-    expect(adapter.capabilities).toEqual(getProviderCapabilities(provider));
-  });
-});
diff --git a/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts b/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
index 05f52a73b38..eeba158ab42 100644
--- a/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
@@ -1,25 +1,31 @@
-import * as NodeServices from "@effect/platform-node/NodeServices";
+import {
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
+  type ServerProvider,
+} from "@t3tools/contracts";
 import { it, assert, vi } from "@effect/vitest";
-import { assertFailure } from "@effect/vitest/utils";
-import type { ProviderKind } from "@t3tools/contracts";
-import { Effect, Layer, Stream } from "effect";
-
-import { ProviderUnsupportedError } from "../Errors.ts";
-import { ClaudeAdapter, type ClaudeAdapterShape } from "../Services/ClaudeAdapter.ts";
-import { CopilotAdapter, type CopilotAdapterShape } from "../Services/CopilotAdapter.ts";
-import { CodexAdapter, type CodexAdapterShape } from "../Services/CodexAdapter.ts";
-import { CursorAdapter, type CursorAdapterShape } from "../Services/CursorAdapter.ts";
-import { GeminiCliAdapter, type GeminiCliAdapterShape } from "../Services/GeminiCliAdapter.ts";
-import { OpenCodeAdapter, type OpenCodeAdapterShape } from "../Services/OpenCodeAdapter.ts";
-import { AmpAdapter, type AmpAdapterShape } from "../Services/AmpAdapter.ts";
-import { KiloAdapter, type KiloAdapterShape } from "../Services/KiloAdapter.ts";
-import { getProviderCapabilities } from "../Services/ProviderAdapter.ts";
+
+import { Effect, Layer, PubSub, Stream } from "effect";
+
+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 type { TextGenerationShape } from "../../textGeneration/TextGeneration.ts";
 import { ProviderAdapterRegistryLive } from "./ProviderAdapterRegistry.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",
-  capabilities: getProviderCapabilities("codex"),
+  provider: CODEX_DRIVER,
+  capabilities: { sessionModelSwitch: "in-session" },
   startSession: vi.fn(),
   sendTurn: vi.fn(),
   interruptTurn: vi.fn(),
@@ -35,8 +41,8 @@ const fakeCodexAdapter: CodexAdapterShape = {
 };
 
 const fakeClaudeAdapter: ClaudeAdapterShape = {
-  provider: "claudeAgent",
-  capabilities: getProviderCapabilities("claudeAgent"),
+  provider: CLAUDE_AGENT_DRIVER,
+  capabilities: { sessionModelSwitch: "in-session" },
   startSession: vi.fn(),
   sendTurn: vi.fn(),
   interruptTurn: vi.fn(),
@@ -51,9 +57,9 @@ const fakeClaudeAdapter: ClaudeAdapterShape = {
   streamEvents: Stream.empty,
 };
 
-const fakeCopilotAdapter: CopilotAdapterShape = {
-  provider: "copilot",
-  capabilities: getProviderCapabilities("copilot"),
+const fakeOpenCodeAdapter: OpenCodeAdapterShape = {
+  provider: OPENCODE_DRIVER,
+  capabilities: { sessionModelSwitch: "in-session" },
   startSession: vi.fn(),
   sendTurn: vi.fn(),
   interruptTurn: vi.fn(),
@@ -69,8 +75,8 @@ const fakeCopilotAdapter: CopilotAdapterShape = {
 };
 
 const fakeCursorAdapter: CursorAdapterShape = {
-  provider: "cursor",
-  capabilities: getProviderCapabilities("cursor"),
+  provider: CURSOR_DRIVER,
+  capabilities: { sessionModelSwitch: "in-session" },
   startSession: vi.fn(),
   sendTurn: vi.fn(),
   interruptTurn: vi.fn(),
@@ -85,133 +91,94 @@ const fakeCursorAdapter: CursorAdapterShape = {
   streamEvents: Stream.empty,
 };
 
-const fakeOpenCodeAdapter: OpenCodeAdapterShape = {
-  provider: "opencode",
-  capabilities: getProviderCapabilities("opencode"),
-  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,
+// 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: {
+      getSnapshot: Effect.succeed({} as unknown as ServerProvider),
+      refresh: Effect.succeed({} as unknown as ServerProvider),
+      streamChanges: Stream.empty,
+    },
+    adapter,
+    textGeneration: {} as unknown as TextGenerationShape,
+  };
 };
 
-const fakeGeminiCliAdapter: GeminiCliAdapterShape = {
-  provider: "geminiCli",
-  capabilities: getProviderCapabilities("geminiCli"),
-  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 fakeInstances: ReadonlyArray<ProviderInstance> = [
+  makeFakeInstance("codex", fakeCodexAdapter),
+  makeFakeInstance("claudeAgent", fakeClaudeAdapter),
+  makeFakeInstance("opencode", fakeOpenCodeAdapter),
+  makeFakeInstance("cursor", fakeCursorAdapter),
+];
 
-const fakeAmpAdapter: AmpAdapterShape = {
-  provider: "amp",
-  capabilities: getProviderCapabilities("amp"),
-  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 fakeKiloAdapter: KiloAdapterShape = {
-  provider: "kilo",
-  capabilities: getProviderCapabilities("kilo"),
-  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 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 = it.layer(
-  ProviderAdapterRegistryLive.pipe(
-    Layer.provide(
-      Layer.mergeAll(
-        Layer.succeed(CodexAdapter, fakeCodexAdapter),
-        Layer.succeed(CopilotAdapter, fakeCopilotAdapter),
-        Layer.succeed(ClaudeAdapter, fakeClaudeAdapter),
-        Layer.succeed(CursorAdapter, fakeCursorAdapter),
-        Layer.succeed(OpenCodeAdapter, fakeOpenCodeAdapter),
-        Layer.succeed(GeminiCliAdapter, fakeGeminiCliAdapter),
-        Layer.succeed(AmpAdapter, fakeAmpAdapter),
-        Layer.succeed(KiloAdapter, fakeKiloAdapter),
-      ),
-    ),
-    Layer.provideMerge(NodeServices.layer),
-  ),
+const layer = Layer.mergeAll(
+  Layer.provide(ProviderAdapterRegistryLive, fakeInstanceRegistryLayer),
+  NodeServices.layer,
 );
 
-layer("ProviderAdapterRegistryLive", (it) => {
-  it.effect("resolves registered provider adapters", () =>
+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 copilot = yield* registry.getByProvider("copilot");
-      const claude = yield* registry.getByProvider("claudeAgent");
-      const cursor = yield* registry.getByProvider("cursor");
-      const opencode = yield* registry.getByProvider("opencode");
-      const geminiCli = yield* registry.getByProvider("geminiCli");
-      const amp = yield* registry.getByProvider("amp");
-      const kilo = yield* registry.getByProvider("kilo");
-
-      assert.equal(codex, fakeCodexAdapter);
-      assert.equal(copilot, fakeCopilotAdapter);
-      assert.equal(claude, fakeClaudeAdapter);
-      assert.equal(cursor, fakeCursorAdapter);
-      assert.equal(opencode, fakeOpenCodeAdapter);
-      assert.equal(geminiCli, fakeGeminiCliAdapter);
-      assert.equal(amp, fakeAmpAdapter);
-      assert.equal(kilo, fakeKiloAdapter);
+      const claudeInstanceId = defaultInstanceIdForDriver(CLAUDE_AGENT_DRIVER);
 
-      const providers = yield* registry.listProviders();
-      assert.deepEqual(providers, [
-        "codex",
-        "claudeAgent",
-        "copilot",
-        "cursor",
-        "geminiCli",
-        "opencode",
-        "amp",
-        "kilo",
+      const adapter = yield* registry.getByInstance(claudeInstanceId);
+      assert.strictEqual(adapter, fakeClaudeAdapter);
+
+      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),
       ]);
-    }),
-  );
 
-  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 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 4295ef43937..f2eeaa1aae8 100644
--- a/apps/server/src/provider/Layers/ProviderAdapterRegistry.ts
+++ b/apps/server/src/provider/Layers/ProviderAdapterRegistry.ts
@@ -1,65 +1,101 @@
 /**
- * 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 {
+  defaultInstanceIdForDriver,
+  ProviderInstanceId,
+  type ProviderDriverKind,
+} from "@t3tools/contracts";
 import { Effect, Layer } from "effect";
 
-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 { AmpAdapter } from "../Services/AmpAdapter.ts";
-import { ClaudeAdapter } from "../Services/ClaudeAdapter.ts";
-import { CodexAdapter } from "../Services/CodexAdapter.ts";
-import { CopilotAdapter } from "../Services/CopilotAdapter.ts";
-import { CursorAdapter } from "../Services/CursorAdapter.ts";
-import { GeminiCliAdapter } from "../Services/GeminiCliAdapter.ts";
-import { KiloAdapter } from "../Services/KiloAdapter.ts";
-import { OpenCodeAdapter } from "../Services/OpenCodeAdapter.ts";
 
-export interface ProviderAdapterRegistryLiveOptions {
-  readonly adapters?: ReadonlyArray<ProviderAdapterShape<ProviderAdapterError>>;
-}
+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 makeProviderAdapterRegistry = Effect.fn("makeProviderAdapterRegistry")(function* (
-  options?: ProviderAdapterRegistryLiveOptions,
-) {
-  const adapters =
-    options?.adapters !== undefined
-      ? options.adapters
-      : [
-          yield* CodexAdapter,
-          yield* ClaudeAdapter,
-          yield* CopilotAdapter,
-          yield* CursorAdapter,
-          yield* GeminiCliAdapter,
-          yield* OpenCodeAdapter,
-          yield* AmpAdapter,
-          yield* KiloAdapter,
-        ];
-  const byProvider = new Map(adapters.map((adapter) => [adapter.provider, 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 getByProvider: ProviderAdapterRegistryShape["getByProvider"] = (provider) => {
-    const adapter = byProvider.get(provider);
-    if (!adapter) {
-      return Effect.fail(new ProviderUnsupportedError({ provider }));
-    }
-    return Effect.succeed(adapter);
-  };
+  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;
 });
 
@@ -67,3 +103,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..4a15fdd6852
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderEventLoggers.ts
@@ -0,0 +1,83 @@
+/**
+ * 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 { Context, Effect, Layer } from "effect";
+
+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..b6c44306f93
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryHydration.ts
@@ -0,0 +1,176 @@
+/**
+ * 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 { Effect, Layer, Stream } from "effect";
+
+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..2246a2ae478
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
@@ -0,0 +1,357 @@
+/**
+ * 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 { Effect, Layer } from "effect";
+
+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 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(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(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..63f687f55b6
--- /dev/null
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.ts
@@ -0,0 +1,434 @@
+/**
+ * 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 { Context, Effect, Equal, Exit, Layer, PubSub, Ref, Schema, Scope, Stream } from "effect";
+
+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: 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: 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: 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 e29d1ae1957..75f9c42936b 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
@@ -1,19 +1,28 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { describe, it, assert } from "@effect/vitest";
+import { describe, it, assert, live } from "@effect/vitest";
 import { Effect, Exit, Layer, PubSub, Ref, Schema, Scope, Sink, Stream } from "effect";
 import * as CodexErrors from "effect-codex-app-server/errors";
 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 { ChildProcessSpawner } from "effect/unstable/process";
 import { deepMerge } from "@t3tools/shared/Struct";
+import { createModelCapabilities } from "@t3tools/shared/model";
 
 import { checkCodexProviderStatus, type CodexAppServerProviderSnapshot } from "./CodexProvider.ts";
-import { checkClaudeProviderStatus, parseClaudeAuthStatusFromOutput } from "./ClaudeProvider.ts";
+import { checkClaudeProviderStatus } from "./ClaudeProvider.ts";
+import { OpenCodeRuntimeLive } from "../opencodeRuntime.ts";
+import { NoOpProviderEventLoggers, ProviderEventLoggers } from "./ProviderEventLoggers.ts";
+import { ProviderInstanceRegistryHydrationLive } from "./ProviderInstanceRegistryHydration.ts";
 import {
   haveProvidersChanged,
   mergeProviderSnapshot,
@@ -21,14 +30,67 @@ import {
 } from "./ProviderRegistry.ts";
 import { ServerConfig } from "../../config.ts";
 import { ServerSettingsService, type ServerSettingsShape } from "../../serverSettings.ts";
+import type { ProviderInstance } from "../ProviderDriver.ts";
+import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
 import { ProviderRegistry } from "../Services/ProviderRegistry.ts";
 
+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();
 
+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),
@@ -46,7 +108,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,
@@ -57,6 +123,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,
@@ -66,7 +159,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)));
     }),
   );
@@ -88,16 +184,15 @@ function failingSpawnerLayer(description: string) {
   );
 }
 
-const codexModelCapabilities = {
-  reasoningEffortLevels: [
-    { value: "high", label: "High", isDefault: true },
-    { value: "low", label: "Low" },
+const codexModelCapabilities = createModelCapabilities({
+  optionDescriptors: [
+    selectDescriptor("reasoningEffort", "Reasoning", [
+      { id: "high", label: "High", isDefault: true },
+      { id: "low", label: "Low" },
+    ]),
+    booleanDescriptor("fastMode", "Fast Mode"),
   ],
-  supportsFastMode: true,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-} satisfies NonNullable<ServerProvider["models"][number]["capabilities"]>;
+}) satisfies NonNullable<ServerProvider["models"][number]["capabilities"]>;
 
 function makeCodexProbeSnapshot(
   input: Partial<CodexAppServerProviderSnapshot> = {},
@@ -151,638 +246,1074 @@ function makeMutableServerSettingsService(
   });
 }
 
-it.layer(
-  Layer.mergeAll(
-    NodeServices.layer,
-    ServerSettingsService.layerTest(),
-    ServerConfig.layerTest(process.cwd(), { prefix: "provider-registry-test-" }).pipe(
-      Layer.provide(NodeServices.layer),
-    ),
-  ),
-)("ProviderRegistry", (it) => {
-  describe("checkCodexProviderStatus", () => {
-    it.effect("uses the app-server account and model list for provider status", () =>
-      Effect.gen(function* () {
-        const status = yield* checkCodexProviderStatus(() =>
-          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",
+it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsService.layerTest()))(
+  "ProviderRegistry",
+  (it) => {
+    describe("checkCodexProviderStatus", () => {
+      it.effect("uses the app-server account and model list for provider status", () =>
+        Effect.gen(function* () {
+          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.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, "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",
+              path: "/Users/test/.codex/skills/gh-fix-ci/SKILL.md",
+              enabled: true,
+              displayName: "CI Debug",
+              shortDescription: "Debug failing GitHub Actions checks",
+            },
+          ]);
+        }),
+      );
+
+      it.effect("returns unauthenticated when app-server requires OpenAI auth", () =>
+        Effect.gen(function* () {
+          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.installed, true);
-        assert.strictEqual(status.version, "1.0.0");
-        assert.strictEqual(status.auth.status, "authenticated");
-        assert.strictEqual(status.auth.type, "chatgpt");
-        assert.strictEqual(status.auth.label, "ChatGPT Pro 20x Subscription");
-        assert.deepStrictEqual(status.models, [
+              }),
+            ),
+          );
+
+          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.",
+          );
+        }),
+      );
+
+      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.status, "ready");
+            assert.strictEqual(status.auth.status, "unknown");
+          }),
+      );
+
+      it.effect("returns an api key label for codex api key auth", () =>
+        Effect.gen(function* () {
+          const status = yield* checkCodexProviderStatus(defaultCodexSettings, () =>
+            Effect.succeed(
+              makeCodexProbeSnapshot({
+                account: {
+                  account: { type: "apiKey" },
+                  requiresOpenaiAuth: false,
+                },
+              }),
+            ),
+          );
+
+          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");
+        }),
+      );
+
+      it.effect("returns unavailable when codex is missing", () =>
+        Effect.gen(function* () {
+          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");
+          assert.strictEqual(
+            status.message,
+            "Codex CLI (`codex`) is not installed or not on PATH.",
+          );
+        }),
+      );
+    });
+
+    describe("ProviderRegistryLive", () => {
+      it("treats equal provider snapshots as unchanged", () => {
+        const providers = [
           {
-            slug: "gpt-live-codex",
-            name: "GPT Live Codex",
-            isCustom: false,
-            capabilities: codexModelCapabilities,
+            instanceId: ProviderInstanceId.make("codex"),
+            driver: ProviderDriverKind.make("codex"),
+            status: "ready",
+            enabled: true,
+            installed: true,
+            auth: { status: "authenticated" },
+            checkedAt: "2026-03-25T00:00:00.000Z",
+            version: "1.0.0",
+            models: [],
+            slashCommands: [],
+            skills: [],
           },
-        ]);
-        assert.deepStrictEqual(status.skills, [
           {
-            name: "github:gh-fix-ci",
-            path: "/Users/test/.codex/skills/gh-fix-ci/SKILL.md",
+            instanceId: ProviderInstanceId.make("claudeAgent"),
+            driver: ProviderDriverKind.make("claudeAgent"),
+            status: "warning",
             enabled: true,
-            displayName: "CI Debug",
-            shortDescription: "Debug failing GitHub Actions checks",
+            installed: true,
+            auth: { status: "unknown" },
+            checkedAt: "2026-03-25T00:00:00.000Z",
+            version: "1.0.0",
+            models: [],
+            slashCommands: [],
+            skills: [],
           },
-        ]);
-      }),
-    );
-
-    it.effect("returns unauthenticated when app-server requires OpenAI auth", () =>
-      Effect.gen(function* () {
-        const status = yield* checkCodexProviderStatus(() =>
-          Effect.succeed(
-            makeCodexProbeSnapshot({
-              account: {
-                account: null,
-                requiresOpenaiAuth: true,
-              },
-            }),
-          ),
-        );
-
-        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.",
-        );
-      }),
-    );
-
-    it.effect("returns ready with unknown auth when app-server does not require OpenAI auth", () =>
-      Effect.gen(function* () {
-        const status = yield* checkCodexProviderStatus(() =>
-          Effect.succeed(
-            makeCodexProbeSnapshot({
-              account: {
-                account: null,
-                requiresOpenaiAuth: false,
-              },
-            }),
-          ),
-        );
-
-        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* () {
-        const status = yield* checkCodexProviderStatus(() =>
-          Effect.succeed(
-            makeCodexProbeSnapshot({
-              account: {
-                account: { type: "apiKey" },
-                requiresOpenaiAuth: false,
-              },
-            }),
-          ),
-        );
-
-        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");
-      }),
-    );
-
-    it.effect("returns unavailable when codex is missing", () =>
-      Effect.gen(function* () {
-        const status = yield* checkCodexProviderStatus(() =>
-          Effect.fail(
-            new CodexErrors.CodexAppServerSpawnError({
-              command: "codex app-server",
-              cause: new Error("spawn codex ENOENT"),
-            }),
-          ),
-        );
-        assert.strictEqual(status.provider, "codex");
-        assert.strictEqual(status.status, "error");
-        assert.strictEqual(status.installed, false);
-        assert.strictEqual(status.auth.status, "unknown");
-        assert.strictEqual(status.message, "Codex CLI (`codex`) is not installed or not on PATH.");
-      }),
-    );
-  });
+        ] as const satisfies ReadonlyArray<ServerProvider>;
 
-  describe("ProviderRegistryLive", () => {
-    it("treats equal provider snapshots as unchanged", () => {
-      const providers = [
-        {
-          provider: "codex",
+        assert.strictEqual(haveProvidersChanged(providers, [...providers]), false);
+      });
+
+      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-03-25T00:00:00.000Z",
-          version: "1.0.0",
-          models: [],
+          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: [],
-        },
-        {
-          provider: "claudeAgent",
-          status: "warning",
-          enabled: true,
-          installed: true,
-          auth: { status: "unknown" },
-          checkedAt: "2026-03-25T00:00:00.000Z",
-          version: "1.0.0",
+        } as const satisfies ServerProvider;
+        const refreshedProvider = {
+          ...previousProvider,
+          checkedAt: "2026-04-14T00:01:00.000Z",
           models: [],
-          slashCommands: [],
-          skills: [],
-        },
-      ] as const satisfies ReadonlyArray<ServerProvider>;
+        } satisfies ServerProvider;
 
-      assert.strictEqual(haveProvidersChanged(providers, [...providers]), false);
-    });
+        assert.deepStrictEqual(mergeProviderSnapshot(previousProvider, refreshedProvider).models, [
+          ...previousProvider.models,
+        ]);
+      });
 
-    it.skip("ignores checkedAt-only changes when comparing provider snapshots", () => {
-      const previousProviders = [
-        {
-          provider: "codex",
+      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-03-25T00:00:00.000Z",
-          version: "1.0.0",
-          message: "Ready",
-          models: [],
+          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 ReadonlyArray<ServerProvider>;
-      const nextProviders = [
-        {
-          ...previousProviders[0],
-          checkedAt: "2026-03-25T00:01:00.000Z",
-        },
-      ] as const satisfies ReadonlyArray<ServerProvider>;
-
-      assert.strictEqual(haveProvidersChanged(previousProviders, nextProviders), false);
-    });
+        } 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;
 
-    it("preserves previously discovered provider models when a refresh returns none", () => {
-      const previousProvider = {
-        provider: "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: {
-              reasoningEffortLevels: [{ value: "high", label: "High", isDefault: true }],
-              supportsFastMode: true,
-              supportsThinkingToggle: true,
-              contextWindowOptions: [],
-              promptInjectedEffortLevels: [],
+        assert.deepStrictEqual(mergeProviderSnapshot(previousProvider, refreshedProvider).models, [
+          ...previousProvider.models,
+        ]);
+      });
+
+      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",
             },
-          },
-        ],
-        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,
-      ]);
-    });
+            displayName: undefined,
+            enabled: true,
+            snapshot: {
+              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(
+            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;
+
+            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("fills missing capabilities from the previous provider snapshot", () => {
-      const previousProvider = {
-        provider: "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: {
-              reasoningEffortLevels: [{ value: "high", label: "High", isDefault: true }],
-              supportsFastMode: true,
-              supportsThinkingToggle: true,
-              contextWindowOptions: [],
-              promptInjectedEffortLevels: [],
+      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}`,
             },
-          },
-        ],
-        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: {
-              reasoningEffortLevels: [],
-              supportsFastMode: false,
-              supportsThinkingToggle: false,
-              contextWindowOptions: [],
-              promptInjectedEffortLevels: [],
+            displayName: undefined,
+            enabled: true,
+            snapshot: {
+              getSnapshot: Effect.succeed(provider),
+              refresh: Effect.succeed(provider),
+              streamChanges: Stream.empty,
             },
-          },
-        ],
-      } satisfies ServerProvider;
+            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 = (millis: number) =>
+            Effect.promise<void>(() => new Promise((resolve) => setTimeout(resolve, millis)));
+          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(10);
+              providers = yield* registry.getProviders;
+            }
 
-      assert.deepStrictEqual(mergeProviderSnapshot(previousProvider, refreshedProvider).models, [
-        ...previousProvider.models,
-      ]);
-    });
+            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_${process.pid}_${Date.now()}`;
+          const serverSettings = yield* makeMutableServerSettingsService(
+            Schema.decodeSync(ServerSettings)(
+              deepMerge(DEFAULT_SERVER_SETTINGS, {
+                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(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(
+              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.
+      //
+      // `live` (imported from `@effect/vitest`) is used instead of
+      // `it.effect` so real timers coordinate the fibres that drive the
+      // settings → reconcile → sync pipeline. Under `it.effect`'s
+      // TestClock, `Effect.sleep` blocks until `TestClock.adjust`, which
+      // would require this test to reach into the internals of the
+      // reconcile pipeline to advance it step by step.
+      //
+      // The nested `it` handed to `it.layer(…, (it) => …)` is the
+      // `MethodsNonLive` variant and therefore lacks `.live`; the
+      // top-level `live` export from `@effect/vitest` is the equivalent.
+      live("re-probes when settings change the codex binaryPath", () =>
+        Effect.gen(function* () {
+          const firstMissing = `t3code_codex_first_${process.pid}_${Date.now()}`;
+          const secondMissing = `t3code_codex_second_${process.pid}_${Date.now()}`;
+          const serverSettings = yield* makeMutableServerSettingsService(
+            Schema.decodeSync(ServerSettings)(
+              deepMerge(DEFAULT_SERVER_SETTINGS, {
+                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(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),
+          );
 
-    it.effect("probes enabled providers in the background during registry startup", () =>
-      Effect.gen(function* () {
-        let spawnCount = 0;
-        const serverSettings = yield* makeMutableServerSettingsService(
-          Schema.decodeSync(ServerSettings)(
-            deepMerge(DEFAULT_SERVER_SETTINGS, {
+          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: { enabled: false },
-                cursor: { enabled: false },
+                codex: { enabled: true, binaryPath: secondMissing },
               },
-            }),
-          ),
-        );
-        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(
-            ServerConfig.layerTest(process.cwd(), {
-              prefix: "t3-provider-registry-",
-            }),
-          ),
-          Layer.provideMerge(
-            mockCommandSpawnerLayer((command, args) => {
-              spawnCount += 1;
-              const joined = args.join(" ");
-              if (joined === "--version") {
-                return { stdout: "claude 1.0.0\n", stderr: "", code: 0 };
-              }
-              if (joined === "auth status") {
-                return { stdout: '{"authenticated":true}\n', stderr: "", code: 0 };
+            });
+
+            // Poll with real timers (via `it.live`) until `checkedAt`
+            // advances or we hit a generous 3-second ceiling. Anything
+            // slower than that is a regression — the real probe fails
+            // fast on ENOENT, and the reconcile + sync pipeline is
+            // purely in-process.
+            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* Effect.sleep("50 millis");
               }
-              throw new Error(`Unexpected args: ${command} ${joined}`);
-            }),
-          ),
-        );
-        const runtimeServices = yield* Layer.build(providerRegistryLayer).pipe(
-          Scope.provide(scope),
-        );
-
-        yield* Effect.gen(function* () {
-          const registry = yield* ProviderRegistry;
-          assert.strictEqual(spawnCount > 0, true);
-          const refreshed = yield* Effect.gen(function* () {
-            for (let remainingAttempts = 50; remainingAttempts > 0; remainingAttempts -= 1) {
+              return yield* registry.getProviders;
+            });
+
+            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("includes unavailable instance snapshots in getProviders", () =>
+        Effect.gen(function* () {
+          const serverSettings = yield* makeMutableServerSettingsService(
+            Schema.decodeSync(ServerSettings)(
+              deepMerge(DEFAULT_SERVER_SETTINGS, {
+                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(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(
+              Schema.decodeSync(ServerSettings)(
+                deepMerge(DEFAULT_SERVER_SETTINGS, {
+                  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(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 claudeProvider = providers.find(
-                (provider) => provider.provider === "claudeAgent",
+              const cursorProvider = providers.find(
+                (provider) => provider.instanceId === ProviderInstanceId.make("cursor"),
               );
-              if (claudeProvider?.status === "ready") {
-                return providers;
-              }
-              yield* Effect.sleep("10 millis");
-            }
-            return yield* registry.getProviders;
-          });
-          assert.strictEqual(
-            refreshed.find((provider) => provider.provider === "claudeAgent")?.status,
-            "ready",
+
+              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));
+          }),
+      );
+
+      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")),
           );
-        }).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(
-          Schema.decodeSync(ServerSettings)(
-            deepMerge(DEFAULT_SERVER_SETTINGS, {
-              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(Layer.succeed(ServerSettingsService, serverSettings)),
-          Layer.provideMerge(
-            ServerConfig.layerTest(process.cwd(), {
-              prefix: "t3-provider-registry-",
-            }),
-          ),
-          Layer.provideMerge(
-            mockCommandSpawnerLayer((command, args) => {
-              if (command === "agent") {
-                cursorSpawned = true;
-              }
+          assert.strictEqual(status.enabled, false);
+          assert.strictEqual(status.status, "disabled");
+          assert.strictEqual(status.installed, false);
+          assert.strictEqual(status.message, "Codex is disabled in T3 Code settings.");
+        }),
+      );
+    });
+
+    // ── 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: `${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}`);
+              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}`);
             }),
           ),
-        );
-        const runtimeServices = yield* Layer.build(
-          Layer.mergeAll(
-            Layer.succeed(ServerSettingsService, serverSettings),
-            providerRegistryLayer,
+        ),
+      );
+
+      it.effect(
+        "includes Claude Opus 4.7 with xhigh as the default effort on supported versions",
+        () =>
+          Effect.gen(function* () {
+            const status = yield* checkClaudeProviderStatus(
+              defaultClaudeSettings,
+              claudeCapabilities(),
+            );
+            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(
+              mockSpawnerLayer((args) => {
+                const joined = args.join(" ");
+                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}`);
+              }),
+            ),
           ),
-        ).pipe(Scope.provide(scope));
+      );
 
-        yield* Effect.gen(function* () {
-          const registry = yield* ProviderRegistry;
-          const providers = yield* registry.getProviders;
-          const cursorProvider = providers.find((provider) => provider.provider === "cursor");
-
-          assert.deepStrictEqual(
-            providers.map((provider) => provider.provider),
-            ["codex", "claudeAgent", "opencode", "cursor"],
+      it.effect("hides Claude Opus 4.7 on older Claude Code versions", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities(),
+          );
+          assert.strictEqual(
+            status.models.some((model) => model.slug === "claude-opus-4-7"),
+            false,
           );
-          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));
-      }),
-    );
-
-    it.effect.skip("probes Copilot from its default command when binary path is unset", () =>
-      Effect.gen(function* () {
-        const serverSettingsLayer = ServerSettingsService.layerTest();
-        const providerRegistryLayer = ProviderRegistryLive.pipe(
-          Layer.provideMerge(serverSettingsLayer),
-          Layer.provideMerge(
-            ServerConfig.layerTest(process.cwd(), {
-              prefix: "t3-provider-registry-",
+          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.",
+          );
+        }).pipe(
+          Effect.provide(
+            mockSpawnerLayer((args) => {
+              const joined = args.join(" ");
+              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}`);
             }),
           ),
-          Layer.provideMerge(
-            mockCommandSpawnerLayer((command, args) => {
+        ),
+      );
+
+      it.effect("returns a display label for claude subscription types", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({ subscriptionType: "maxplan" }),
+          );
+          assert.strictEqual(status.status, "ready");
+          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) => {
               const joined = args.join(" ");
-              if (joined === "--version") {
-                if (command === "codex") {
-                  return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-                }
-                if (command === "claude") {
-                  return { stdout: "claude 1.0.0\n", stderr: "", code: 0 };
-                }
-                if (command === "copilot") {
-                  return { stdout: "copilot 2.3.4\n", stderr: "", code: 0 };
-                }
-                return { stdout: "", stderr: "spawn ENOENT", code: 1 };
-              }
-              if (joined === "login status") {
-                return { stdout: "Logged in\n", stderr: "", code: 0 };
-              }
-              if (joined === "auth status") {
-                return { stdout: "Authenticated\n", stderr: "", code: 0 };
-              }
-              throw new Error(`Unexpected command: ${command} ${joined}`);
+              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}`);
             }),
           ),
-        );
-
-        const providers = yield* Effect.gen(function* () {
-          const registry = yield* ProviderRegistry;
-          return yield* registry.getProviders;
-        }).pipe(Effect.provide(providerRegistryLayer));
-
-        const copilot = providers.find((provider) => provider.provider === "copilot");
-        assert.isDefined(copilot);
-        assert.strictEqual(copilot?.status, "ready");
-        assert.strictEqual(copilot?.installed, true);
-        assert.notStrictEqual(
-          copilot?.message,
-          "Copilot is enabled, but no binary path is configured for probing.",
-        );
-      }),
-    );
-
-    it.effect.skip("reports cursor as unavailable when its CLI command is missing", () =>
-      Effect.gen(function* () {
-        const serverSettingsLayer = ServerSettingsService.layerTest({
-          providers: {
-            cursor: {
-              enabled: true,
-              binaryPath: "/tmp/t3-missing-cursor-cli",
-            },
-          },
-        });
-        const providerRegistryLayer = ProviderRegistryLive.pipe(
-          Layer.provideMerge(serverSettingsLayer),
-          Layer.provideMerge(
-            ServerConfig.layerTest(process.cwd(), {
-              prefix: "t3-provider-registry-",
+        ),
+      );
+
+      it.effect("does not duplicate Claude in full subscription labels", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({
+              subscriptionType: "Claude Max Subscription",
             }),
-          ),
-          Layer.provideMerge(
-            mockCommandSpawnerLayer((command, args) => {
+          );
+          assert.strictEqual(status.auth.status, "authenticated");
+          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") {
-                if (command === "codex") {
-                  return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-                }
-                if (command === "claude") {
-                  return { stdout: "claude 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 };
-              }
-              if (joined === "auth status") {
-                return { stdout: "Authenticated\n", stderr: "", code: 0 };
-              }
-              throw new Error(`Unexpected command: ${command} ${joined}`);
+              if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
+              throw new Error(`Unexpected args: ${joined}`);
             }),
           ),
-        );
-
-        const providers = yield* Effect.gen(function* () {
-          const registry = yield* ProviderRegistry;
-          return yield* registry.getProviders;
-        }).pipe(Effect.provide(providerRegistryLayer));
-
-        const cursor = providers.find((provider) => provider.provider === "cursor");
-        assert.isDefined(cursor);
-        assert.strictEqual(cursor?.status, "warning");
-        assert.strictEqual(cursor?.installed, false);
-        assert.strictEqual(cursor?.message, "Cursor CLI not found on PATH.");
-      }),
-    );
-
-    it.effect("serves cached provider snapshots from getProviders without re-probing", () =>
-      Effect.gen(function* () {
-        let probeCount = 0;
-        const providerRegistryLayer = ProviderRegistryLive.pipe(
-          Layer.provideMerge(ServerSettingsService.layerTest()),
-          Layer.provideMerge(
-            ServerConfig.layerTest(process.cwd(), {
-              prefix: "t3-provider-registry-",
+        ),
+      );
+
+      it.effect("does not duplicate Claude in provider-prefixed subscription names", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({
+              subscriptionType: "Claude Max",
             }),
-          ),
-          Layer.provideMerge(
-            mockCommandSpawnerLayer((command, args) => {
-              probeCount += 1;
+          );
+          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") {
-                if (command === "codex") {
-                  return { stdout: "codex 1.0.0\n", stderr: "", code: 0 };
-                }
-                if (command === "claude") {
-                  return { stdout: "claude 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 };
-              }
-              if (joined === "auth status") {
-                return { stdout: "Authenticated\n", stderr: "", code: 0 };
-              }
-              throw new Error(`Unexpected command: ${command} ${joined}`);
+              if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
+              throw new Error(`Unexpected args: ${joined}`);
             }),
           ),
-        );
-
-        yield* Effect.gen(function* () {
-          const registry = yield* ProviderRegistry;
-          yield* registry.getProviders;
-          const initialProbeCount = probeCount;
-          yield* registry.getProviders;
-          assert.strictEqual(probeCount, initialProbeCount);
-        }).pipe(Effect.provide(providerRegistryLayer));
-      }),
-    );
-
-    it.effect("skips codex probes entirely when the provider is disabled", () =>
-      Effect.gen(function* () {
-        const serverSettingsLayer = ServerSettingsService.layerTest({
-          providers: {
-            codex: {
-              enabled: false,
-            },
-          },
-        });
+        ),
+      );
 
-        const status = yield* checkCodexProviderStatus().pipe(
+      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(
-            Layer.mergeAll(serverSettingsLayer, failingSpawnerLayer("spawn codex ENOENT")),
+            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","account":{"email":"claude@example.com"}}\n',
+                  stderr: "",
+                  code: 0,
+                };
+              throw new Error(`Unexpected args: ${joined}`);
+            }),
           ),
-        );
-        assert.strictEqual(status.provider, "codex");
-        assert.strictEqual(status.enabled, false);
-        assert.strictEqual(status.status, "disabled");
-        assert.strictEqual(status.installed, false);
-        assert.strictEqual(status.message, "Codex is disabled in T3 Code settings.");
-      }),
-    );
-  });
-
-  // ── 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");
-      }).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}`);
-          }),
         ),
-      ),
-    );
+      );
+
+      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}`);
+        });
 
-    it.effect(
-      "includes Claude Opus 4.7 with xhigh as the default effort on supported versions",
-      () =>
-        Effect.gen(function* () {
-          const status = yield* checkClaudeProviderStatus();
-          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.",
-            );
-          }
+        return Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            {
+              ...defaultClaudeSettings,
+              homePath: claudeHome,
+            },
+            claudeCapabilities(),
+          );
+          assert.strictEqual(status.status, "ready");
           assert.deepStrictEqual(
-            opus47.capabilities.reasoningEffortLevels.find((level) => level.isDefault),
-            { value: "xhigh", label: "Extra High", isDefault: true },
+            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(
+            defaultClaudeSettings,
+            claudeCapabilities({
+              subscriptionType: "maxplan",
+              slashCommands: [
+                {
+                  name: "review",
+                  description: "Review a pull request",
+                  input: { hint: "pr-or-branch" },
+                },
+              ],
+            }),
           );
+
+          assert.deepStrictEqual(status.slashCommands, [
+            {
+              name: "review",
+              description: "Review a pull request",
+              input: { hint: "pr-or-branch" },
+            },
+          ]);
         }).pipe(
           Effect.provide(
             mockSpawnerLayer((args) => {
               const joined = args.join(" ");
-              if (joined === "--version") return { stdout: "2.1.111\n", stderr: "", code: 0 };
+              if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
               if (joined === "auth status")
                 return {
                   stdout: '{"loggedIn":true,"authMethod":"claude.ai"}\n',
@@ -793,306 +1324,147 @@ it.layer(
             }),
           ),
         ),
-    );
-
-    it.effect("hides Claude Opus 4.7 on older Claude Code versions", () =>
-      Effect.gen(function* () {
-        const status = yield* checkClaudeProviderStatus();
-        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.",
-        );
-      }).pipe(
-        Effect.provide(
-          mockSpawnerLayer((args) => {
-            const joined = args.join(" ");
-            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}`);
-          }),
-        ),
-      ),
-    );
-
-    it.effect("returns a display label for claude subscription types", () =>
-      Effect.gen(function* () {
-        const status = yield* checkClaudeProviderStatus(() => Effect.succeed("maxplan"));
-        assert.strictEqual(status.provider, "claudeAgent");
-        assert.strictEqual(status.status, "ready");
-        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) => {
-            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}`);
-          }),
-        ),
-      ),
-    );
-
-    it.effect("includes probed claude slash commands in the provider snapshot", () =>
-      Effect.gen(function* () {
-        const status = yield* checkClaudeProviderStatus(
-          () => Effect.succeed("maxplan"),
-          () =>
-            Effect.succeed([
-              {
-                name: "review",
-                description: "Review a pull request",
-                input: { hint: "pr-or-branch" },
-              },
-            ]),
-        );
+      );
 
-        assert.deepStrictEqual(status.slashCommands, [
-          {
-            name: "review",
-            description: "Review a pull request",
-            input: { hint: "pr-or-branch" },
-          },
-        ]);
-      }).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}`);
-          }),
-        ),
-      ),
-    );
-
-    it.effect("deduplicates probed claude slash commands by name", () =>
-      Effect.gen(function* () {
-        const status = yield* checkClaudeProviderStatus(
-          () => Effect.succeed("maxplan"),
-          () =>
-            Effect.succeed([
-              {
-                name: "ui",
-                description: "Explore and refine UI",
-              },
-              {
-                name: "ui",
-                input: { hint: "component-or-screen" },
-              },
-            ]),
-        );
+      it.effect("deduplicates probed claude slash commands by name", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities({
+              subscriptionType: "maxplan",
+              slashCommands: [
+                {
+                  name: "ui",
+                  description: "Explore and refine UI",
+                },
+                {
+                  name: "ui",
+                  input: { hint: "component-or-screen" },
+                },
+              ],
+            }),
+          );
 
-        assert.deepStrictEqual(status.slashCommands, [
-          {
-            name: "ui",
-            description: "Explore and refine UI",
-            input: { hint: "component-or-screen" },
-          },
-        ]);
-      }).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}`);
-          }),
-        ),
-      ),
-    );
-
-    it.effect("returns an api key label for claude api key auth", () =>
-      Effect.gen(function* () {
-        const status = yield* checkClaudeProviderStatus();
-        assert.strictEqual(status.provider, "claudeAgent");
-        assert.strictEqual(status.status, "ready");
-        assert.strictEqual(status.auth.status, "authenticated");
-        assert.strictEqual(status.auth.type, "apiKey");
-        assert.strictEqual(status.auth.label, "Claude API Key");
-      }).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":"api-key"}\n',
-                stderr: "",
-                code: 0,
-              };
-            throw new Error(`Unexpected args: ${joined}`);
-          }),
-        ),
-      ),
-    );
-
-    it.effect("returns unavailable when claude is missing", () =>
-      Effect.gen(function* () {
-        const status = yield* checkClaudeProviderStatus();
-        assert.strictEqual(status.provider, "claudeAgent");
-        assert.strictEqual(status.status, "error");
-        assert.strictEqual(status.installed, false);
-        assert.strictEqual(status.auth.status, "unknown");
-        assert.strictEqual(
-          status.message,
-          "Claude Agent CLI (`claude`) is not installed or not on PATH.",
-        );
-      }).pipe(Effect.provide(failingSpawnerLayer("spawn claude ENOENT"))),
-    );
-
-    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");
-        assert.strictEqual(status.status, "error");
-        assert.strictEqual(status.installed, true);
-      }).pipe(
-        Effect.provide(
-          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: "",
-                code: 1,
-              };
-            throw new Error(`Unexpected args: ${joined}`);
-          }),
-        ),
-      ),
-    );
-
-    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", () =>
-      Effect.gen(function* () {
-        const status = yield* checkClaudeProviderStatus();
-        assert.strictEqual(status.provider, "claudeAgent");
-        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.",
-        );
-      }).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: "", stderr: "error: unknown command 'auth'", code: 2 };
-            throw new Error(`Unexpected args: ${joined}`);
-          }),
+          assert.deepStrictEqual(status.slashCommands, [
+            {
+              name: "ui",
+              description: "Explore and refine UI",
+              input: { hint: "component-or-screen" },
+            },
+          ]);
+        }).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}`);
+            }),
+          ),
         ),
-      ),
-    );
-  });
-
-  // ── 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.effect("returns an api key label for claude api key auth", () =>
+        Effect.gen(function* () {
+          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");
+          assert.strictEqual(status.auth.label, "Claude API Key");
+        }).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":"api-key"}\n',
+                  stderr: "",
+                  code: 0,
+                };
+              throw new Error(`Unexpected args: ${joined}`);
+            }),
+          ),
+        ),
+      );
 
-    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.effect("returns unavailable when claude is missing", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities(),
+          );
+          assert.strictEqual(status.status, "error");
+          assert.strictEqual(status.installed, false);
+          assert.strictEqual(status.auth.status, "unknown");
+          assert.strictEqual(
+            status.message,
+            "Claude Agent CLI (`claude`) is not installed or not on PATH.",
+          );
+        }).pipe(Effect.provide(failingSpawnerLayer("spawn claude ENOENT"))),
+      );
 
-    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.effect("returns error when version check fails with non-zero exit code", () =>
+        Effect.gen(function* () {
+          const status = yield* checkClaudeProviderStatus(
+            defaultClaudeSettings,
+            claudeCapabilities(),
+          );
+          assert.strictEqual(status.status, "error");
+          assert.strictEqual(status.installed, true);
+        }).pipe(
+          Effect.provide(
+            mockSpawnerLayer((args) => {
+              const joined = args.join(" ");
+              if (joined === "--version")
+                return {
+                  stdout: "",
+                  stderr: "Something went wrong",
+                  code: 1,
+                };
+              throw new Error(`Unexpected args: ${joined}`);
+            }),
+          ),
+        ),
+      );
 
-    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");
+      it.effect("returns warning when the Claude initialization result is unavailable", () =>
+        Effect.gen(function* () {
+          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,
+            "Could not verify Claude authentication status from initialization result.",
+          );
+        }).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: "",
+                  code: 1,
+                };
+              throw new Error(`Unexpected args: ${joined}`);
+            }),
+          ),
+        ),
+      );
     });
-  });
-});
+  },
+);
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.ts b/apps/server/src/provider/Layers/ProviderRegistry.ts
index b1d20b4d603..4f586d881e3 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.ts
@@ -1,51 +1,66 @@
 /**
- * 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, FileSystem, Layer, Path, PubSub, Ref, Stream } from "effect";
+import {
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
+  type ProviderInstanceId,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { Cause, Effect, Equal, FileSystem, Layer, Path, PubSub, Ref, Stream } from "effect";
+import * as Semaphore from "effect/Semaphore";
 
 import { ServerConfig } from "../../config.ts";
-import { ClaudeProviderLive } from "./ClaudeProvider.ts";
-import { CodexProviderLive } from "./CodexProvider.ts";
-import { CursorProviderLive } from "./CursorProvider.ts";
-import { OpenCodeProviderLive } from "./OpenCodeProvider.ts";
-import { ClaudeProvider } from "../Services/ClaudeProvider.ts";
-import { CodexProvider } from "../Services/CodexProvider.ts";
-import { CursorProvider } from "../Services/CursorProvider.ts";
-import { OpenCodeProvider } from "../Services/OpenCodeProvider.ts";
+import { ProviderInstanceRegistry } from "../Services/ProviderInstanceRegistry.ts";
 import { ProviderRegistry, type ProviderRegistryShape } from "../Services/ProviderRegistry.ts";
-import { OpenCodeRuntimeLive } from "../opencodeRuntime.ts";
 import {
   hydrateCachedProvider,
-  PROVIDER_CACHE_IDS,
+  isCachedProviderCorrelated,
   orderProviderSnapshots,
   readProviderStatusCache,
   resolveProviderStatusCachePath,
   writeProviderStatusCache,
 } from "../providerStatusCache.ts";
-
-type ProviderSnapshotSource = {
-  readonly provider: ProviderKind;
-  readonly getSnapshot: Effect.Effect<ServerProvider>;
-  readonly refresh: Effect.Effect<ServerProvider>;
-  readonly streamChanges: Stream.Stream<ServerProvider>;
-};
+import type { ProviderInstance } from "../ProviderDriver.ts";
+import type { ProviderSnapshotSource } from "../builtInProviderCatalog.ts";
 
 const loadProviders = (
   providerSources: ReadonlyArray<ProviderSnapshotSource>,
 ): Effect.Effect<ReadonlyArray<ServerProvider>> =>
-  Effect.forEach(providerSources, (providerSource) => providerSource.getSnapshot, {
-    concurrency: "unbounded",
-  });
+  Effect.forEach(
+    providerSources,
+    (providerSource) =>
+      providerSource.getSnapshot.pipe(
+        Effect.flatMap((snapshot) => correlateSnapshotWithSource(providerSource, snapshot)),
+      ),
+    {
+      concurrency: "unbounded",
+    },
+  );
 
 const hasModelCapabilities = (model: ServerProvider["models"][number]): boolean =>
-  (model.capabilities?.reasoningEffortLevels.length ?? 0) > 0 ||
-  model.capabilities?.supportsFastMode === true ||
-  model.capabilities?.supportsThinkingToggle === true ||
-  (model.capabilities?.contextWindowOptions.length ?? 0) > 0 ||
-  (model.capabilities?.promptInjectedEffortLevels.length ?? 0) > 0;
+  (model.capabilities?.optionDescriptors?.length ?? 0) > 0;
 
 const mergeProviderModels = (
   previousModels: ReadonlyArray<ServerProvider["models"][number]>,
@@ -86,85 +101,123 @@ export const haveProvidersChanged = (
   nextProviders: ReadonlyArray<ServerProvider>,
 ): boolean => !Equal.equals(previousProviders, nextProviders);
 
-const ProviderRegistryLiveBase = Layer.effect(
+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 openCodeProvider = yield* OpenCodeProvider;
-    const cursorProvider = yield* CursorProvider;
+    const instanceRegistry = yield* ProviderInstanceRegistry;
     const config = yield* ServerConfig;
     const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
 
-    const providerSources = [
-      {
-        provider: "codex",
-        getSnapshot: codexProvider.getSnapshot,
-        refresh: codexProvider.refresh,
-        streamChanges: codexProvider.streamChanges,
-      },
-      {
-        provider: "claudeAgent",
-        getSnapshot: claudeProvider.getSnapshot,
-        refresh: claudeProvider.refresh,
-        streamChanges: claudeProvider.streamChanges,
-      },
-      {
-        provider: "opencode",
-        getSnapshot: openCodeProvider.getSnapshot,
-        refresh: openCodeProvider.refresh,
-        streamChanges: openCodeProvider.streamChanges,
-      },
-      {
-        provider: "cursor",
-        getSnapshot: cursorProvider.getSnapshot,
-        refresh: cursorProvider.refresh,
-        streamChanges: cursorProvider.streamChanges,
-      },
-    ] satisfies ReadonlyArray<ProviderSnapshotSource>;
-    const activeProviders = PROVIDER_CACHE_IDS;
+    // 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 fallbackProviders = yield* loadProviders(providerSources);
-    const cachePathByProvider = new Map(
-      activeProviders.map(
-        (provider) =>
-          [
-            provider,
-            resolveProviderStatusCachePath({
-              cacheDir: config.providerStatusCacheDir,
-              provider,
-            }),
-          ] as const,
-      ),
-    );
-    const fallbackByProvider = new Map(
-      fallbackProviders.map((provider) => [provider.provider, provider] as const),
-    );
+
+    // 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(
-      activeProviders,
-      (provider) => {
-        const filePath = cachePathByProvider.get(provider);
-        const fallbackProvider = fallbackByProvider.get(provider);
-        if (!filePath || !fallbackProvider) {
-          return Effect.succeed<ServerProvider | undefined>(undefined);
-        }
-        return readProviderStatusCache(filePath).pipe(
-          Effect.provideService(FileSystem.FileSystem, fileSystem),
-          Effect.map((cachedProvider) =>
-            cachedProvider === undefined
-              ? undefined
-              : hydrateCachedProvider({
-                  cachedProvider,
-                  fallbackProvider,
-                }),
-          ),
-        );
-      },
+      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) =>
@@ -175,39 +228,64 @@ const ProviderRegistryLiveBase = Layer.effect(
     );
     const providersRef = yield* Ref.make<ReadonlyArray<ServerProvider>>(cachedProviders);
 
-    const persistProvider = (provider: ServerProvider) => {
-      const filePath = cachePathByProvider.get(
-        provider.provider as (typeof PROVIDER_CACHE_IDS)[number],
-      );
-      if (!filePath) return Effect.void;
-      return writeProviderStatusCache({
-        filePath,
-        provider,
-      }).pipe(
-        Effect.provideService(FileSystem.FileSystem, fileSystem),
-        Effect.provideService(Path.Path, path),
-        Effect.tapError(Effect.logError),
-        Effect.ignore,
-      );
-    };
+    // 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 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,
+        );
+      });
 
     const upsertProviders = Effect.fn("upsertProviders")(function* (
       nextProviders: ReadonlyArray<ServerProvider>,
       options?: {
         readonly publish?: boolean;
+        readonly persist?: boolean;
+        readonly replace?: boolean;
       },
     ) {
       const [previousProviders, providers] = yield* Ref.modify(
         providersRef,
         (previousProviders) => {
           const mergedProviders = new Map(
-            previousProviders.map((provider) => [provider.provider, provider] as const),
+            previousProviders.map((provider) => [snapshotInstanceKey(provider), provider] as const),
           );
 
           for (const provider of nextProviders) {
+            const key = snapshotInstanceKey(provider);
             mergedProviders.set(
-              provider.provider,
-              mergeProviderSnapshot(mergedProviders.get(provider.provider), provider),
+              key,
+              options?.replace === true
+                ? provider
+                : mergeProviderSnapshot(mergedProviders.get(key), provider),
             );
           }
 
@@ -217,10 +295,12 @@ const ProviderRegistryLiveBase = Layer.effect(
       );
 
       if (haveProvidersChanged(previousProviders, providers)) {
-        yield* Effect.forEach(nextProviders, persistProvider, {
-          concurrency: "unbounded",
-          discard: true,
-        });
+        if (options?.persist !== false) {
+          yield* Effect.forEach(nextProviders, persistProvider, {
+            concurrency: "unbounded",
+            discard: true,
+          });
+        }
         if (options?.publish !== false) {
           yield* PubSub.publish(changesPubSub, providers);
         }
@@ -238,64 +318,246 @@ const ProviderRegistryLiveBase = Layer.effect(
       return yield* upsertProviders([provider], options);
     });
 
-    const refresh = Effect.fn("refresh")(function* (provider?: ProviderKind) {
-      if (provider) {
-        const providerSource = providerSources.find((candidate) => candidate.provider === provider);
-        if (!providerSource) {
-          return yield* Ref.get(providersRef);
-        }
-        return yield* providerSource.refresh.pipe(
-          Effect.flatMap((nextProvider) => syncProvider(nextProvider)),
-        );
-      }
-
-      return yield* Effect.forEach(
-        providerSources,
-        (providerSource) => providerSource.refresh.pipe(Effect.flatMap(syncProvider)),
-        {
-          concurrency: "unbounded",
-          discard: true,
-        },
-      ).pipe(Effect.andThen(Ref.get(providersRef)));
+    const refreshOneSource = Effect.fn("refreshOneSource")(function* (
+      providerSource: ProviderSnapshotSource,
+    ) {
+      return yield* providerSource.refresh.pipe(
+        Effect.flatMap((nextProvider) =>
+          correlateSnapshotWithSource(providerSource, nextProvider).pipe(
+            Effect.flatMap(syncProvider),
+          ),
+        ),
+      );
     });
 
-    yield* Effect.forEach(
-      providerSources,
-      (providerSource) =>
-        Stream.runForEach(providerSource.streamChanges, (provider) => syncProvider(provider)).pipe(
-          Effect.forkScoped,
-        ),
-      {
+    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);
+    });
+
+    /**
+     * 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* loadProviders(providerSources).pipe(
-      Effect.flatMap((providers) => upsertProviders(providers, { publish: false })),
+    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),
+          },
+        );
+      }),
     );
 
+    // 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;
+      }
+      yield* Effect.logError("provider registry refresh failed; preserving cached providers", {
+        cause: Cause.pretty(cause),
+      });
+      return yield* Ref.get(providersRef);
+    });
+
     return {
       getProviders: Ref.get(providersRef),
-      refresh: (provider?: ProviderKind) =>
-        refresh(provider).pipe(
-          Effect.tapError(Effect.logError),
-          Effect.orElseSucceed(() => [] as ReadonlyArray<ServerProvider>),
-        ),
+      refresh: (provider?: ProviderDriverKind) =>
+        refresh(provider).pipe(Effect.catchCause(recoverRefreshFailure)),
+      refreshInstance: (instanceId: ProviderInstanceId) =>
+        refreshInstance(instanceId).pipe(Effect.catchCause(recoverRefreshFailure)),
       get streamChanges() {
         return Stream.fromPubSub(changesPubSub);
       },
     } satisfies ProviderRegistryShape;
   }),
 );
-
-export const ProviderRegistryLive = Layer.unwrap(
-  Effect.sync(() =>
-    ProviderRegistryLiveBase.pipe(
-      Layer.provideMerge(CodexProviderLive),
-      Layer.provideMerge(ClaudeProviderLive),
-      Layer.provideMerge(CursorProviderLive),
-      Layer.provideMerge(OpenCodeProviderLive),
-      Layer.provideMerge(OpenCodeRuntimeLive),
-    ),
-  ),
-);
diff --git a/apps/server/src/provider/Layers/ProviderService.test.ts b/apps/server/src/provider/Layers/ProviderService.test.ts
index 9bb40596a06..7e771251437 100644
--- a/apps/server/src/provider/Layers/ProviderService.test.ts
+++ b/apps/server/src/provider/Layers/ProviderService.test.ts
@@ -12,28 +12,34 @@ 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 { Effect, Fiber, Layer, Metric, Option, PubSub, Ref, Stream } from "effect";
+import { Effect, Exit, Fiber, Layer, Metric, Option, PubSub, Ref, Scope, Stream } from "effect";
 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 { getProviderCapabilities } 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 +50,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 +58,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,7 +77,7 @@ 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>());
 
@@ -74,10 +86,15 @@ function makeFakeCodexAdapter(provider: ProviderKind = "codex") {
       const now = new Date().toISOString();
       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,
@@ -177,7 +194,9 @@ function makeFakeCodexAdapter(provider: ProviderKind = "codex") {
 
   const adapter: ProviderAdapterShape<ProviderAdapterError> = {
     provider,
-    capabilities: getProviderCapabilities(provider),
+    capabilities: {
+      sessionModelSwitch: "in-session",
+    },
     startSession,
     sendTurn,
     interruptTurn,
@@ -243,19 +262,13 @@ const hasMetricSnapshot = (
 
 function makeProviderServiceLayer() {
   const codex = makeFakeCodexAdapter();
-  const claude = makeFakeCodexAdapter("claudeAgent");
-  const cursor = makeFakeCodexAdapter("cursor");
-  const registry: typeof ProviderAdapterRegistry.Service = {
-    getByProvider: (provider) =>
-      provider === "codex"
-        ? Effect.succeed(codex.adapter)
-        : provider === "claudeAgent"
-          ? Effect.succeed(claude.adapter)
-          : provider === "cursor"
-            ? Effect.succeed(cursor.adapter)
-            : Effect.fail(new ProviderUnsupportedError({ provider })),
-    listProviders: () => Effect.succeed(["codex", "claudeAgent", "cursor"]),
-  };
+  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(
@@ -270,6 +283,7 @@ function makeProviderServiceLayer() {
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
         Layer.provideMerge(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
       ),
       directoryLayer,
 
@@ -286,27 +300,76 @@ function makeProviderServiceLayer() {
   };
 }
 
+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),
     );
@@ -314,15 +377,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",
         });
@@ -330,11 +395,149 @@ 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", () =>
@@ -342,13 +545,9 @@ it.effect("ProviderServiceLive writes canonical events to the emitting thread se
     const codex = makeFakeCodexAdapter();
     const canonicalEvents: ProviderRuntimeEvent[] = [];
     const canonicalThreadIds: Array<string | null> = [];
-    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 runtimeRepositoryLayer = ProviderSessionRuntimeRepositoryLive.pipe(
       Layer.provide(SqlitePersistenceMemory),
     );
@@ -368,6 +567,7 @@ it.effect("ProviderServiceLive writes canonical events to the emitting thread se
       Layer.provide(directoryLayer),
       Layer.provide(defaultServerSettingsLayer),
       Layer.provide(AnalyticsService.layerTest),
+      Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
     );
 
     yield* Effect.gen(function* () {
@@ -375,7 +575,7 @@ it.effect("ProviderServiceLive writes canonical events to the emitting thread se
       yield* sleep(10);
       codex.emit({
         eventId: asEventId("evt-canonical-thread-segment"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: asThreadId("thread-canonical-thread-segment"),
         createdAt: new Date().toISOString(),
         type: "turn.completed",
@@ -398,13 +598,9 @@ it.effect("ProviderServiceLive keeps persisted resumable sessions on startup", (
     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(
@@ -415,7 +611,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));
@@ -425,6 +622,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* () {
@@ -439,7 +637,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);
 
@@ -469,13 +669,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),
@@ -485,6 +681,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"),
@@ -497,7 +694,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,
@@ -513,7 +711,9 @@ it.effect(
 
       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)) {
@@ -522,13 +722,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),
       );
@@ -537,6 +733,7 @@ it.effect(
         Layer.provide(secondDirectoryLayer),
         Layer.provide(defaultServerSettingsLayer),
         Layer.provide(AnalyticsService.layerTest),
+        Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
       );
 
       secondCodex.startSession.mockClear();
@@ -580,7 +777,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",
@@ -660,35 +858,13 @@ routing.layer("ProviderServiceLive routing", (it) => {
     }),
   );
 
-  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",
-        threadId: asThreadId("thread-claude"),
-        cwd: "/tmp/project-claude",
-        runtimeMode: "full-access",
-      });
-
-      assert.equal(session.provider, "claudeAgent");
-      assert.equal(routing.claude.startSession.mock.calls.length, 1);
-      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 };
-        assert.equal(startPayload.provider, "claudeAgent");
-        assert.equal(startPayload.cwd, "/tmp/project-claude");
-      }
-    }),
-  );
-
   it.effect("recovers stale persisted sessions for rollback by resuming thread identity", () =>
     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",
         runtimeMode: "full-access",
@@ -729,7 +905,8 @@ routing.layer("ProviderServiceLive routing", (it) => {
       const runtimeRepository = yield* ProviderSessionRuntimeRepository;
 
       const initial = yield* provider.startSession(asThreadId("thread-reap-preserve"), {
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-reap-preserve"),
         cwd: "/tmp/project-reap-preserve",
         runtimeMode: "full-access",
@@ -774,13 +951,74 @@ routing.layer("ProviderServiceLive routing", (it) => {
     }),
   );
 
+  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: ProviderDriverKind.make("claudeAgent"),
+        providerInstanceId: claudeAgentInstanceId,
+        threadId: asThreadId("thread-claude"),
+        cwd: "/tmp/project-claude",
+        runtimeMode: "full-access",
+      });
+
+      assert.equal(session.provider, "claudeAgent");
+      assert.equal(routing.claude.startSession.mock.calls.length, 1);
+      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;
+          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: "codex",
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: codexInstanceId,
         threadId,
         cwd: "/tmp/project-provider-replacement",
         runtimeMode: "full-access",
@@ -790,7 +1028,8 @@ routing.layer("ProviderServiceLive routing", (it) => {
       routing.claude.stopSession.mockClear();
 
       const claudeSession = yield* provider.startSession(threadId, {
-        provider: "claudeAgent",
+        provider: ProviderDriverKind.make("claudeAgent"),
+        providerInstanceId: claudeAgentInstanceId,
         threadId,
         cwd: "/tmp/project-provider-replacement",
         runtimeMode: "full-access",
@@ -816,7 +1055,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-send-turn",
         runtimeMode: "full-access",
@@ -856,16 +1096,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",
       });
 
@@ -892,13 +1131,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);
       }
@@ -911,12 +1149,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",
       });
@@ -934,10 +1174,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"),
-        cwd: "/tmp/project-send-turn",
+      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({
@@ -963,7 +1204,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
             lastError: string | null;
             lastRuntimeEvent: string | null;
           };
-          assert.equal(runtimePayload.cwd, "/tmp/project-send-turn");
+          assert.equal(runtimePayload.cwd, session.cwd);
           assert.equal(runtimePayload.model, null);
           assert.equal(runtimePayload.activeTurnId, `turn-${String(session.threadId)}`);
           assert.equal(runtimePayload.lastError, null);
@@ -982,14 +1223,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),
       );
@@ -998,12 +1235,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",
@@ -1015,14 +1254,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),
       );
@@ -1031,6 +1266,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();
@@ -1038,7 +1274,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",
@@ -1064,6 +1301,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();
@@ -1072,7 +1393,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",
       });
@@ -1086,7 +1408,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       const completedEvent: LegacyProviderRuntimeEvent = {
         type: "turn.completed",
         eventId: asEventId("evt-1"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         createdAt: new Date().toISOString(),
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
@@ -1103,6 +1425,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,
+      );
     }),
   );
 
@@ -1110,7 +1439,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",
       });
@@ -1125,7 +1455,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       fanout.codex.emit({
         type: "tool.started",
         eventId: asEventId("evt-seq-1"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         createdAt: new Date().toISOString(),
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
@@ -1135,7 +1465,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       fanout.codex.emit({
         type: "tool.completed",
         eventId: asEventId("evt-seq-2"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         createdAt: new Date().toISOString(),
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
@@ -1145,7 +1475,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       fanout.codex.emit({
         type: "turn.completed",
         eventId: asEventId("evt-seq-3"),
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         createdAt: new Date().toISOString(),
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
@@ -1165,7 +1495,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",
       });
@@ -1190,7 +1521,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         {
           type: "tool.completed",
           eventId: asEventId("evt-ordered-1"),
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           createdAt: new Date().toISOString(),
           threadId: session.threadId,
           turnId: asTurnId("turn-1"),
@@ -1201,7 +1532,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         {
           type: "message.delta",
           eventId: asEventId("evt-ordered-2"),
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           createdAt: new Date().toISOString(),
           threadId: session.threadId,
           turnId: asTurnId("turn-1"),
@@ -1210,7 +1541,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         {
           type: "turn.completed",
           eventId: asEventId("evt-ordered-3"),
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           createdAt: new Date().toISOString(),
           threadId: session.threadId,
           turnId: asTurnId("turn-1"),
@@ -1237,7 +1568,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",
@@ -1266,7 +1598,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
 
       assert.equal(
         hasMetricSnapshot(snapshots, "t3_provider_turns_total", {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "interrupt",
           outcome: "success",
         }),
@@ -1274,7 +1606,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",
         }),
@@ -1282,7 +1614,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",
         }),
@@ -1290,7 +1622,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       );
       assert.equal(
         hasMetricSnapshot(snapshots, "t3_provider_turns_total", {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "rollback",
           outcome: "success",
         }),
@@ -1298,7 +1630,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
       );
       assert.equal(
         hasMetricSnapshot(snapshots, "t3_provider_sessions_total", {
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           operation: "stop",
           outcome: "success",
         }),
@@ -1314,7 +1646,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",
@@ -1330,7 +1663,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
 
         assert.equal(
           hasMetricSnapshot(snapshots, "t3_provider_turns_total", {
-            provider: "claudeAgent",
+            provider: ProviderDriverKind.make("claudeAgent"),
             operation: "send",
             outcome: "success",
           }),
@@ -1338,7 +1671,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         );
         assert.equal(
           hasMetricSnapshot(snapshots, "t3_provider_turn_duration", {
-            provider: "claudeAgent",
+            provider: ProviderDriverKind.make("claudeAgent"),
             operation: "send",
           }),
           true,
@@ -1349,6 +1682,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;
@@ -1383,7 +1760,7 @@ validation.layer("ProviderServiceLive validation", (it) => {
         Effect.sync(() => {
           const now = new Date().toISOString();
           return {
-            provider: "codex",
+            provider: ProviderDriverKind.make("codex"),
             status: "ready",
             threadId: input.threadId,
             runtimeMode: input.runtimeMode,
@@ -1395,7 +1772,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 94630d3bca9..05b4e72ec18 100644
--- a/apps/server/src/provider/Layers/ProviderService.ts
+++ b/apps/server/src/provider/Layers/ProviderService.ts
@@ -19,10 +19,12 @@ 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 { Cause, Effect, Layer, Option, PubSub, Ref, Schema, SchemaIssue, Stream } from "effect";
 
 import {
   increment,
@@ -34,19 +36,24 @@ 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";
 
+/**
+ * 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;
 }
 
@@ -141,18 +148,53 @@ 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;
@@ -169,6 +211,24 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
       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,
@@ -178,38 +238,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>>(),
+  );
 
-  yield* Effect.forEach(adapters, (adapter) =>
-    Stream.runForEach(adapter.streamEvents, processRuntimeEvent).pipe(Effect.forkScoped),
-  ).pipe(Effect.asVoid);
+  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);
+  });
+
+  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);
@@ -219,7 +347,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",
@@ -242,6 +373,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 } : {}),
@@ -254,7 +386,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",
@@ -284,29 +419,49 @@ 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 currentProvider: ProviderSession["provider"];
+    readonly currentInstanceId: ProviderInstanceId;
   }) {
+    const currentAdapters = yield* getAdapterEntries;
     yield* Effect.forEach(
-      adapters,
-      (adapter) =>
-        adapter.provider === input.currentProvider
+      currentAdapters,
+      ([instanceId, adapter]) =>
+        instanceId === input.currentInstanceId
           ? Effect.void
           : Effect.gen(function* () {
               const hasSession = yield* adapter.hasSession(input.threadId);
@@ -341,63 +496,72 @@ 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 effectiveCwd =
           input.cwd ??
-          (persistedBinding?.provider === input.provider
+          (persistedBinding?.providerInstanceId === resolvedInstanceId
             ? readPersistedCwd(persistedBinding.runtimePayload)
             : undefined);
         yield* Effect.annotateCurrentSpan({
+          "provider.kind": resolvedProvider,
           "provider.resume_cursor.source":
             input.resumeCursor !== undefined
               ? "request"
-              : effectiveResumeCursor !== undefined && persistedBinding?.provider === input.provider
+              : effectiveResumeCursor !== undefined &&
+                  persistedBinding?.providerInstanceId === resolvedInstanceId
                 ? "persisted"
                 : "none",
           "provider.resume_cursor.present": effectiveResumeCursor !== undefined,
           "provider.cwd.source":
             input.cwd !== undefined
               ? "request"
-              : effectiveCwd !== undefined && persistedBinding?.provider === input.provider
+              : effectiveCwd !== undefined &&
+                  persistedBinding?.providerInstanceId === resolvedInstanceId
                 ? "persisted"
                 : "none",
           "provider.cwd.effective": effectiveCwd ?? "",
         });
-        const adapter = yield* registry.getByProvider(input.provider);
+        const adapter = yield* registry.getByInstance(resolvedInstanceId);
         const session = yield* adapter.startSession({
           ...input,
+          providerInstanceId: resolvedInstanceId,
           ...(effectiveCwd !== undefined ? { cwd: effectiveCwd } : {}),
           ...(effectiveResumeCursor !== undefined ? { resumeCursor: effectiveResumeCursor } : {}),
         });
@@ -408,31 +572,36 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
             `Adapter/provider mismatch: requested '${adapter.provider}', received '${session.provider}'.`,
           );
         }
+        const sessionWithInstance = {
+          ...session,
+          providerInstanceId: resolvedInstanceId,
+        };
 
         yield* stopStaleSessionsForThread({
           threadId,
-          currentProvider: adapter.provider,
+          currentInstanceId: resolvedInstanceId,
         });
-        yield* upsertSessionBinding(session, threadId, {
+        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,
+          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",
+            }),
         }),
       );
     },
@@ -479,6 +648,7 @@ 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: {
@@ -647,6 +817,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         yield* directory.upsert({
           threadId: input.threadId,
           provider: routed.adapter.provider,
+          providerInstanceId: routed.instanceId,
           status: "stopped",
           runtimePayload: {
             activeTurnId: null,
@@ -669,8 +840,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(
@@ -694,29 +873,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",
@@ -761,8 +965,16 @@ 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, {
@@ -770,23 +982,22 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         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(),
-            },
-          }),
-        ),
-      ),
-    ).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) => {
+      const providerInstanceId = dieOnMissingBindingInstanceId("ProviderService.stopAll", binding);
+      return directory.upsert({
+        threadId: binding.threadId,
+        provider: binding.provider,
+        providerInstanceId,
+        status: "stopped",
+        runtimePayload: {
+          activeTurnId: null,
+          lastRuntimeEvent: "provider.stopAll",
+          lastRuntimeEventAt: new Date().toISOString(),
+        },
+      });
+    }).pipe(Effect.asVoid);
     yield* analytics.record("provider.sessions.stopped_all", {
       sessionCount: threadIds.length,
     });
@@ -794,8 +1005,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) }),
+      ),
     ),
   );
 
@@ -808,6 +1021,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 d19eab25eb6..2ff26320e57 100644
--- a/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts
@@ -3,7 +3,7 @@ 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 { assertSome } from "@effect/vitest/utils";
 import { Effect, Layer, Option } from "effect";
@@ -38,7 +38,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       const initialThreadId = ThreadId.make("thread-1");
 
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId: initialThreadId,
       });
 
@@ -47,7 +47,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);
@@ -56,7 +56,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);
@@ -85,7 +85,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: {
@@ -98,7 +98,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       });
 
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId,
         status: "running",
         runtimePayload: {
@@ -133,6 +133,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       yield* runtimeRepository.upsert({
         threadId: newerThreadId,
         providerName: "codex",
+        providerInstanceId: null,
         adapterKey: "codex",
         runtimeMode: "full-access",
         status: "running",
@@ -148,6 +149,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       yield* runtimeRepository.upsert({
         threadId: olderThreadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "approval-required",
         status: "starting",
@@ -165,7 +167,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       assert.deepEqual(bindings, [
         {
           threadId: olderThreadId,
-          provider: "claudeAgent",
+          provider: ProviderDriverKind.make("claudeAgent"),
           adapterKey: "claudeAgent",
           runtimeMode: "approval-required",
           status: "starting",
@@ -179,7 +181,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
         },
         {
           threadId: newerThreadId,
-          provider: "codex",
+          provider: ProviderDriverKind.make("codex"),
           adapterKey: "codex",
           runtimeMode: "full-access",
           status: "running",
@@ -203,6 +205,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       yield* runtimeRepository.upsert({
         threadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "full-access",
         status: "running",
@@ -212,7 +215,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       });
 
       yield* directory.upsert({
-        provider: "codex",
+        provider: ProviderDriverKind.make("codex"),
         threadId,
       });
 
@@ -235,7 +238,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));
@@ -249,7 +252,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);
@@ -272,7 +275,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       const threadId = ThreadId.make("thread-cursor");
 
       yield* directory.upsert({
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         threadId,
       });
 
@@ -281,7 +284,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       const resolvedBinding = yield* directory.getBinding(threadId);
       assertSome(resolvedBinding, {
         threadId,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
       });
       if (Option.isSome(resolvedBinding)) {
         assert.equal(resolvedBinding.value.threadId, threadId);
@@ -323,7 +326,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       const binding = yield* directory.getBinding(threadId);
       assertSome(binding, {
         threadId,
-        provider: "geminiCli",
+        provider: ProviderDriverKind.make("geminiCli"),
       });
     }));
 });
diff --git a/apps/server/src/provider/Layers/ProviderSessionDirectory.ts b/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
index 50a3ffe3fe2..e1479082f2f 100644
--- a/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
@@ -1,11 +1,9 @@
-import { type ProviderKind, type ThreadId } from "@t3tools/contracts";
-import { Cache, Duration, Effect, Layer, Option } from "effect";
-import * as Semaphore from "effect/Semaphore";
+import { defaultInstanceIdForDriver, ProviderDriverKind, type ThreadId } from "@t3tools/contracts";
+import { Effect, Layer, Option, Schema } from "effect";
 
 import type { ProviderSessionRuntime } from "../../persistence/Services/ProviderSessionRuntime.ts";
 import { ProviderSessionRuntimeRepository } from "../../persistence/Services/ProviderSessionRuntime.ts";
 import { ProviderSessionDirectoryPersistenceError, ProviderValidationError } from "../Errors.ts";
-import { normalizePersistedProviderKindName } from "../providerKind.ts";
 import {
   ProviderSessionDirectory,
   type ProviderRuntimeBinding,
@@ -22,19 +20,19 @@ function toPersistenceError(operation: string) {
     });
 }
 
-function decodeProviderKind(
+function decodeProviderDriverKind(
   providerName: string,
   operation: string,
-): Effect.Effect<ProviderKind, ProviderSessionDirectoryPersistenceError> {
-  const normalizedProvider = normalizePersistedProviderKindName(providerName);
-  if (normalizedProvider !== null) {
-    return Effect.succeed(normalizedProvider);
-  }
-  return Effect.fail(
-    new ProviderSessionDirectoryPersistenceError({
-      operation,
-      detail: `Unknown persisted provider '${providerName}'.`,
-    }),
+): Effect.Effect<ProviderDriverKind, ProviderSessionDirectoryPersistenceError> {
+  return Schema.decodeUnknownEffect(ProviderDriverKind)(providerName).pipe(
+    Effect.mapError(
+      (cause) =>
+        new ProviderSessionDirectoryPersistenceError({
+          operation,
+          detail: `Unknown persisted provider '${providerName}'.`,
+          cause,
+        }),
+    ),
   );
 }
 
@@ -59,12 +57,17 @@ function toRuntimeBinding(
   runtime: ProviderSessionRuntime,
   operation: string,
 ): Effect.Effect<ProviderRuntimeBindingWithMetadata, ProviderSessionDirectoryPersistenceError> {
-  return decodeProviderKind(runtime.providerName, operation).pipe(
+  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,
@@ -79,12 +82,6 @@ function toRuntimeBinding(
 const makeProviderSessionDirectory = Effect.gen(function* () {
   const repository = yield* ProviderSessionRuntimeRepository;
 
-  const upsertLocks = yield* Cache.make<string, Semaphore.Semaphore>({
-    capacity: 10_000,
-    timeToLive: Duration.minutes(60),
-    lookup: () => Semaphore.make(1),
-  });
-
   const getBinding = (threadId: ThreadId) =>
     repository.getByThreadId({ threadId }).pipe(
       Effect.mapError(toPersistenceError("ProviderSessionDirectory.getBinding:getByThreadId")),
@@ -92,71 +89,59 @@ 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,
-                }),
-              ),
-              // Gracefully treat unknown persisted providers as "no binding"
-              Effect.orElseSucceed(() => Option.none<ProviderRuntimeBinding>()),
+            toRuntimeBinding(value, "ProviderSessionDirectory.getBinding").pipe(
+              Effect.map((binding) => Option.some(binding)),
             ),
         }),
       ),
     );
 
   const upsert: ProviderSessionDirectoryShape["upsert"] = Effect.fn(function* (binding) {
-    const threadId = binding.threadId;
-    if (!threadId) {
+    const existing = yield* repository
+      .getByThreadId({ threadId: binding.threadId })
+      .pipe(Effect.mapError(toPersistenceError("ProviderSessionDirectory.upsert:getByThreadId")));
+
+    const existingRuntime = Option.getOrUndefined(existing);
+    const resolvedThreadId = binding.threadId ?? existingRuntime?.threadId;
+    if (!resolvedThreadId) {
       return yield* new ProviderValidationError({
         operation: "ProviderSessionDirectory.upsert",
         issue: "threadId must be a non-empty string.",
       });
     }
 
-    const lock = yield* Cache.get(upsertLocks, threadId);
-    yield* Semaphore.withPermit(lock)(
-      Effect.gen(function* () {
-        const existing = yield* repository
-          .getByThreadId({ threadId })
-          .pipe(
-            Effect.mapError(toPersistenceError("ProviderSessionDirectory.upsert:getByThreadId")),
-          );
-
-        const existingRuntime = Option.getOrUndefined(existing);
-        const now = new Date().toISOString();
-        const providerChanged =
-          existingRuntime !== undefined && existingRuntime.providerName !== binding.provider;
-        yield* repository
-          .upsert({
-            threadId,
-            providerName: binding.provider,
-            adapterKey:
-              binding.adapterKey ??
-              (providerChanged
-                ? binding.provider
-                : (existingRuntime?.adapterKey ?? binding.provider)),
-            runtimeMode: binding.runtimeMode ?? existingRuntime?.runtimeMode ?? "full-access",
-            status: binding.status ?? existingRuntime?.status ?? "running",
-            lastSeenAt: now,
-            resumeCursor:
-              binding.resumeCursor !== undefined
-                ? binding.resumeCursor
-                : (existingRuntime?.resumeCursor ?? null),
-            runtimePayload: mergeRuntimePayload(
-              existingRuntime?.runtimePayload ?? null,
-              binding.runtimePayload,
-            ),
-          })
-          .pipe(Effect.mapError(toPersistenceError("ProviderSessionDirectory.upsert:upsert")));
-      }),
-    );
+    const now = new Date().toISOString();
+    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)),
+        runtimeMode: binding.runtimeMode ?? existingRuntime?.runtimeMode ?? "full-access",
+        status: binding.status ?? existingRuntime?.status ?? "running",
+        lastSeenAt: now,
+        resumeCursor:
+          binding.resumeCursor !== undefined
+            ? binding.resumeCursor
+            : (existingRuntime?.resumeCursor ?? null),
+        runtimePayload: mergeRuntimePayload(
+          existingRuntime?.runtimePayload ?? null,
+          binding.runtimePayload,
+        ),
+      })
+      .pipe(Effect.mapError(toPersistenceError("ProviderSessionDirectory.upsert:upsert")));
   });
 
   const getProvider: ProviderSessionDirectoryShape["getProvider"] = (threadId) =>
diff --git a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
index abde9b5446e..91e1a9aef97 100644
--- a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
@@ -1,5 +1,11 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { ProjectId, ThreadId, TurnId } from "@t3tools/contracts";
+import {
+  ProjectId,
+  ThreadId,
+  TurnId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
 import { Effect, Exit, Layer, ManagedRuntime, Option, Scope, Stream } from "effect";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
@@ -17,7 +23,7 @@ import { ProviderSessionDirectoryLive } from "./ProviderSessionDirectory.ts";
 import { makeProviderSessionReaperLive } from "./ProviderSessionReaper.ts";
 
 const defaultModelSelection = {
-  provider: "codex",
+  instanceId: ProviderInstanceId.make("codex"),
   model: "gpt-5-codex",
 } as const;
 
@@ -139,17 +145,20 @@ describe("ProviderSessionReaper", () => {
       respondToUserInput: () => unsupported(),
       stopSession,
       listSessions: () => Effect.succeed([]),
-      getCapabilities: () =>
-        Effect.succeed({
-          sessionModelSwitch: "in-session" as const,
-          transport: "app-server-json-rpc" as const,
-          modelDiscovery: "native" as const,
-          supportsModelDiscovery: true,
-          supportsResume: true,
-          supportsRollback: false,
-          supportsAttachments: false,
-          persistentRuntime: true,
-        }),
+      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,
     };
@@ -207,6 +216,7 @@ describe("ProviderSessionReaper", () => {
       repository.upsert({
         threadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "full-access",
         status: "running",
@@ -254,6 +264,7 @@ describe("ProviderSessionReaper", () => {
       repository.upsert({
         threadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "full-access",
         status: "running",
@@ -300,6 +311,7 @@ describe("ProviderSessionReaper", () => {
       repository.upsert({
         threadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "full-access",
         status: "running",
@@ -346,6 +358,7 @@ describe("ProviderSessionReaper", () => {
       repository.upsert({
         threadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "full-access",
         status: "stopped",
@@ -414,6 +427,7 @@ describe("ProviderSessionReaper", () => {
       repository.upsert({
         threadId: failedThreadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "full-access",
         status: "running",
@@ -428,6 +442,7 @@ describe("ProviderSessionReaper", () => {
       repository.upsert({
         threadId: reapedThreadId,
         providerName: "codex",
+        providerInstanceId: null,
         adapterKey: "codex",
         runtimeMode: "full-access",
         status: "running",
@@ -493,6 +508,7 @@ describe("ProviderSessionReaper", () => {
       repository.upsert({
         threadId: defectThreadId,
         providerName: "claudeAgent",
+        providerInstanceId: null,
         adapterKey: "claudeAgent",
         runtimeMode: "full-access",
         status: "running",
@@ -507,6 +523,7 @@ describe("ProviderSessionReaper", () => {
       repository.upsert({
         threadId: reapedThreadId,
         providerName: "codex",
+        providerInstanceId: null,
         adapterKey: "codex",
         runtimeMode: "full-access",
         status: "running",
diff --git a/apps/server/src/provider/Layers/copilotTurnTracking.test.ts b/apps/server/src/provider/Layers/copilotTurnTracking.test.ts
index 5e42103ac4d..945ed32ae61 100644
--- a/apps/server/src/provider/Layers/copilotTurnTracking.test.ts
+++ b/apps/server/src/provider/Layers/copilotTurnTracking.test.ts
@@ -5,24 +5,19 @@ import {
   assistantUsageFields,
   beginCopilotTurn,
   clearTurnTracking,
+  createCopilotTurnTracker,
   isCopilotTurnTerminalEvent,
+  makeCopilotTurnTrackingState,
   markTurnAwaitingCompletion,
   recordTurnUsage,
   type CopilotTurnTrackingState,
 } from "./copilotTurnTracking.ts";
 
 function makeState(): CopilotTurnTrackingState {
-  return {
-    currentTurnId: undefined,
-    currentProviderTurnId: undefined,
-    pendingCompletionTurnId: undefined,
-    pendingCompletionProviderTurnId: undefined,
-    pendingTurnIds: [],
-    pendingTurnUsage: undefined,
-  };
+  return makeCopilotTurnTrackingState();
 }
 
-describe("copilotTurnTracking", () => {
+describe("copilotTurnTracking (state-passing API)", () => {
   it("keeps turn tracking alive until session.idle", () => {
     expect(isCopilotTurnTerminalEvent({ type: "assistant.usage" } as never)).toBe(false);
     expect(isCopilotTurnTerminalEvent({ type: "session.idle" } as never)).toBe(true);
@@ -57,3 +52,52 @@ describe("copilotTurnTracking", () => {
     expect(state.pendingCompletionTurnId).toBeUndefined();
   });
 });
+
+describe("copilotTurnTracking (per-instance closure factory)", () => {
+  it("isolates state between two trackers (no shared mutable state)", () => {
+    const tracker1 = createCopilotTurnTracker();
+    const tracker2 = createCopilotTurnTracker();
+
+    tracker1.enqueuePendingTurnId(TurnId.make("turn-A"));
+    tracker1.beginTurn(TurnId.make("provider-A"));
+    tracker1.recordUsage({ model: "gpt-A", cost: 0.1, totalTokens: 1 } as never);
+
+    expect(tracker1.currentTurnId()).toBe("turn-A");
+    expect(tracker2.currentTurnId()).toBeUndefined();
+    expect(tracker2.pendingTurnUsage()).toBeUndefined();
+  });
+
+  it("threads the closure through completion refs and usage fields", () => {
+    const tracker = createCopilotTurnTracker();
+    tracker.enqueuePendingTurnId(TurnId.make("turn-1"));
+    tracker.beginTurn(TurnId.make("provider-1"));
+    tracker.recordUsage({ model: "gpt-4.1", cost: 0.5, totalTokens: 200 } as never);
+    tracker.markAwaitingCompletion();
+
+    expect(tracker.completionRefs()).toEqual({
+      turnId: TurnId.make("turn-1"),
+      providerTurnId: TurnId.make("provider-1"),
+    });
+    expect(tracker.usageFields()).toEqual({
+      usage: { model: "gpt-4.1", cost: 0.5, totalTokens: 200 },
+      modelUsage: { model: "gpt-4.1" },
+      totalCostUsd: 0.5,
+    });
+
+    tracker.clear();
+    expect(tracker.currentTurnId()).toBeUndefined();
+    expect(tracker.pendingTurnUsage()).toBeUndefined();
+  });
+
+  it("removePendingTurnId deletes the matching id only", () => {
+    const tracker = createCopilotTurnTracker();
+    const turnA = TurnId.make("turn-A");
+    const turnB = TurnId.make("turn-B");
+
+    tracker.enqueuePendingTurnId(turnA);
+    tracker.enqueuePendingTurnId(turnB);
+    tracker.removePendingTurnId(turnA);
+
+    expect(tracker.state.pendingTurnIds).toEqual([turnB]);
+  });
+});
diff --git a/apps/server/src/provider/Layers/copilotTurnTracking.ts b/apps/server/src/provider/Layers/copilotTurnTracking.ts
index 1b831e5148b..e64dd83526f 100644
--- a/apps/server/src/provider/Layers/copilotTurnTracking.ts
+++ b/apps/server/src/provider/Layers/copilotTurnTracking.ts
@@ -1,3 +1,23 @@
+/**
+ * copilotTurnTracking — per-instance tracking of in-flight Copilot turns.
+ *
+ * Two surfaces are exported:
+ *
+ *   1. `createCopilotTurnTracker()` — a factory that returns operations
+ *      bound to a freshly allocated `CopilotTurnTrackingState` closure. Use
+ *      this from `makeCopilotAdapter`, where each `ProviderInstance` needs
+ *      its own isolated turn-tracking state. Two driver instances of the
+ *      same kind MUST NOT share this state.
+ *
+ *   2. The legacy state-passing helpers (`beginCopilotTurn`,
+ *      `markTurnAwaitingCompletion`, etc.) — kept for unit tests that drive
+ *      the state machine directly without an adapter. Production code paths
+ *      should prefer the closure factory.
+ *
+ * The state object is intentionally a plain mutable record. Concurrent
+ * mutation is impossible because the SDK delivers events serially on a
+ * single callback thread per session.
+ */
 import { TurnId } from "@t3tools/contracts";
 import type { SessionEvent } from "@github/copilot-sdk";
 
@@ -12,6 +32,17 @@ export interface CopilotTurnTrackingState {
   pendingTurnUsage: CopilotAssistantUsage | undefined;
 }
 
+export function makeCopilotTurnTrackingState(): CopilotTurnTrackingState {
+  return {
+    currentTurnId: undefined,
+    currentProviderTurnId: undefined,
+    pendingCompletionTurnId: undefined,
+    pendingCompletionProviderTurnId: undefined,
+    pendingTurnIds: [],
+    pendingTurnUsage: undefined,
+  };
+}
+
 export function completionTurnRefs(state: CopilotTurnTrackingState) {
   return {
     turnId: state.pendingCompletionTurnId ?? state.currentTurnId,
@@ -67,3 +98,63 @@ export function assistantUsageFields(usage: CopilotAssistantUsage | undefined):
 export function isCopilotTurnTerminalEvent(event: SessionEvent): boolean {
   return event.type === "abort" || event.type === "session.idle";
 }
+
+/**
+ * Per-instance Copilot turn tracker. The returned object owns its own
+ * `CopilotTurnTrackingState` closure — two drivers of the same kind get
+ * two independent trackers and cannot observe one another's turns.
+ *
+ * The shape mirrors the legacy state-passing helpers above: each method is
+ * the same operation pre-bound to the closure.
+ */
+export interface CopilotTurnTracker {
+  readonly state: CopilotTurnTrackingState;
+  readonly currentTurnId: () => TurnId | undefined;
+  readonly currentProviderTurnId: () => TurnId | undefined;
+  readonly pendingTurnUsage: () => CopilotAssistantUsage | undefined;
+  readonly enqueuePendingTurnId: (turnId: TurnId) => void;
+  readonly removePendingTurnId: (turnId: TurnId) => void;
+  readonly setCurrentTurnId: (turnId: TurnId | undefined) => void;
+  readonly setCurrentProviderTurnId: (turnId: TurnId | undefined) => void;
+  readonly completionRefs: () => {
+    readonly turnId: TurnId | undefined;
+    readonly providerTurnId: TurnId | undefined;
+  };
+  readonly beginTurn: (providerTurnId: TurnId) => void;
+  readonly markAwaitingCompletion: () => void;
+  readonly recordUsage: (usage: CopilotAssistantUsage) => void;
+  readonly clear: () => void;
+  readonly usageFields: () => {
+    usage?: CopilotAssistantUsage;
+    modelUsage?: { model: string };
+    totalCostUsd?: number;
+  };
+}
+
+export function createCopilotTurnTracker(): CopilotTurnTracker {
+  const state = makeCopilotTurnTrackingState();
+  return {
+    state,
+    currentTurnId: () => state.currentTurnId,
+    currentProviderTurnId: () => state.currentProviderTurnId,
+    pendingTurnUsage: () => state.pendingTurnUsage,
+    enqueuePendingTurnId: (turnId) => {
+      state.pendingTurnIds.push(turnId);
+    },
+    removePendingTurnId: (turnId) => {
+      state.pendingTurnIds = state.pendingTurnIds.filter((candidate) => candidate !== turnId);
+    },
+    setCurrentTurnId: (turnId) => {
+      state.currentTurnId = turnId;
+    },
+    setCurrentProviderTurnId: (turnId) => {
+      state.currentProviderTurnId = turnId;
+    },
+    completionRefs: () => completionTurnRefs(state),
+    beginTurn: (providerTurnId) => beginCopilotTurn(state, providerTurnId),
+    markAwaitingCompletion: () => markTurnAwaitingCompletion(state),
+    recordUsage: (usage) => recordTurnUsage(state, usage),
+    clear: () => clearTurnTracking(state),
+    usageFields: () => assistantUsageFields(state.pendingTurnUsage),
+  };
+}
diff --git a/apps/server/src/provider/Layers/scopedSafeTeardown.test.ts b/apps/server/src/provider/Layers/scopedSafeTeardown.test.ts
new file mode 100644
index 00000000000..ebbc379b7db
--- /dev/null
+++ b/apps/server/src/provider/Layers/scopedSafeTeardown.test.ts
@@ -0,0 +1,94 @@
+import { it } from "@effect/vitest";
+import { Cause, Effect, Exit } from "effect";
+import { describe, expect } from "vitest";
+
+import { scopedSafeTeardown } from "./scopedSafeTeardown.ts";
+
+describe("scopedSafeTeardown", () => {
+  it.effect("returns the body's value when teardown is clean", () =>
+    Effect.gen(function* () {
+      const finalizers: string[] = [];
+      const wrapped = Effect.gen(function* () {
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => {
+            finalizers.push("clean");
+          }),
+        );
+        return "body-ok";
+      }).pipe(scopedSafeTeardown("test"));
+
+      const value = yield* wrapped;
+      expect(value).toBe("body-ok");
+      expect(finalizers).toEqual(["clean"]);
+    }),
+  );
+
+  it.effect("preserves body success when a finalizer dies", () =>
+    // The production failure mode: `Layer.build(...)` registers a finalizer
+    // that kills a subprocess; if the kill fails, the defect would otherwise
+    // override a successful probe body.
+    Effect.gen(function* () {
+      const finalizers: string[] = [];
+      const wrapped = Effect.gen(function* () {
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => {
+            finalizers.push("ran-before-die");
+          }),
+        );
+        yield* Effect.addFinalizer(() =>
+          Effect.die(new Error("simulated subprocess kill failure")),
+        );
+        return "body-ok";
+      }).pipe(scopedSafeTeardown("test"));
+
+      const value = yield* wrapped;
+      expect(value).toBe("body-ok");
+      // The clean finalizer still ran; teardown defect was logged + swallowed.
+      expect(finalizers).toEqual(["ran-before-die"]);
+    }),
+  );
+
+  it.effect("preserves typed body failures even when teardown is clean", () =>
+    Effect.gen(function* () {
+      class BodyError {
+        readonly _tag = "BodyError" as const;
+      }
+      const wrapped = Effect.gen(function* () {
+        yield* Effect.addFinalizer(() => Effect.void);
+        return yield* Effect.fail(new BodyError());
+      }).pipe(scopedSafeTeardown("test"));
+
+      const exit = yield* Effect.exit(wrapped);
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        // Body's typed failure should surface, not a defect.
+        const squashed = Cause.squash(exit.cause);
+        expect(squashed).toBeInstanceOf(BodyError);
+      }
+    }),
+  );
+
+  it.effect("prefers the body's typed failure over a teardown defect", () =>
+    // Even when both the body fails AND teardown defects, the body's typed
+    // failure is what callers see. This matters because `Effect.result` /
+    // `.pipe(Effect.exit)` in callers expects a typed Failure, not a Die.
+    Effect.gen(function* () {
+      class BodyError {
+        readonly _tag = "BodyError" as const;
+      }
+      const wrapped = Effect.gen(function* () {
+        yield* Effect.addFinalizer(() =>
+          Effect.die(new Error("simulated subprocess kill failure")),
+        );
+        return yield* Effect.fail(new BodyError());
+      }).pipe(scopedSafeTeardown("test"));
+
+      const exit = yield* Effect.exit(wrapped);
+      expect(Exit.isFailure(exit)).toBe(true);
+      if (Exit.isFailure(exit)) {
+        const squashed = Cause.squash(exit.cause);
+        expect(squashed).toBeInstanceOf(BodyError);
+      }
+    }),
+  );
+});
diff --git a/apps/server/src/provider/Layers/scopedSafeTeardown.ts b/apps/server/src/provider/Layers/scopedSafeTeardown.ts
new file mode 100644
index 00000000000..688374590e7
--- /dev/null
+++ b/apps/server/src/provider/Layers/scopedSafeTeardown.ts
@@ -0,0 +1,61 @@
+/**
+ * scopedSafeTeardown — run a scope-requiring effect so that finalizer
+ * failures during scope close cannot override the body's Exit.
+ *
+ * Motivation
+ * ----------
+ * The obvious pattern is `body.pipe(Effect.scoped)`: provide a fresh
+ * Scope, run the body, close the scope with the body's Exit. If a
+ * finalizer (e.g. `ChildProcess.kill` from an effect-codex-app-server
+ * spawn) dies during that close, the combined Exit becomes the
+ * finalizer's defect — even when the body already succeeded.
+ *
+ * Concretely this bit us in the Codex provider probe: a successful
+ * `initialize` → `account/read` → `skills/list` → `model/list`
+ * round-trip produced a `CodexAppServerProviderSnapshot`, but the
+ * `Layer.build(CodexClient.layerCommand(...))` finalizer then failed to
+ * kill the `codex app-server` subprocess with a `PlatformError`. The
+ * defect bubbled past `Effect.result` in `checkCodexProviderStatus`,
+ * died `refreshOneSource`, and `providersRef` never saw the snapshot.
+ *
+ * Strategy
+ * --------
+ * 1. Make a fresh scope manually.
+ * 2. Run the body against that scope, capturing its Exit via
+ *    `Effect.exit`.
+ * 3. Close the scope, catching any cause (typed failure *or* defect)
+ *    with a log.
+ * 4. Replay the captured Exit so typed body failures still surface and
+ *    successes still return their value.
+ *
+ * The helper deliberately logs teardown causes at `Warning` level —
+ * silently swallowing them is dangerous because they usually indicate a
+ * real bug in a downstream Layer's finalizer.
+ *
+ * @module provider/Layers/scopedSafeTeardown
+ */
+import { Effect, Exit, Scope } from "effect";
+
+/**
+ * Run `effect` with a freshly made `Scope.Scope`, guaranteeing that
+ * teardown failures cannot override the body's Exit.
+ *
+ * Shape matches `Effect.scoped`: takes an effect whose env includes
+ * `Scope.Scope`, returns one whose env excludes it.
+ *
+ * @param label Short label for the warning log emitted when teardown
+ *   fails. Use something like `"codex-probe"`.
+ */
+export const scopedSafeTeardown =
+  (label: string) =>
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, Scope.Scope>> =>
+    Effect.gen(function* () {
+      const scope = yield* Scope.make();
+      const bodyExit = yield* effect.pipe(Effect.provideService(Scope.Scope, scope), Effect.exit);
+      yield* Scope.close(scope, Exit.void).pipe(
+        Effect.catchCause((cause) =>
+          Effect.logWarning(`${label} teardown errored; preserving body result`, cause),
+        ),
+      );
+      return yield* bodyExit;
+    }) as Effect.Effect<A, E, Exclude<R, Scope.Scope>>;
diff --git a/apps/server/src/provider/ProviderDriver.ts b/apps/server/src/provider/ProviderDriver.ts
new file mode 100644
index 00000000000..e7d3e40cd8c
--- /dev/null
+++ b/apps/server/src/provider/ProviderDriver.ts
@@ -0,0 +1,167 @@
+/**
+ * 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 { Effect, Schema, Scope } from "effect";
+
+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/AmpAdapter.ts b/apps/server/src/provider/Services/AmpAdapter.ts
deleted file mode 100644
index 96763e7629b..00000000000
--- a/apps/server/src/provider/Services/AmpAdapter.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import { Context } from "effect";
-
-import type { ProviderAdapterError } from "../Errors.ts";
-import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
-
-export interface AmpAdapterShape extends Omit<
-  ProviderAdapterShape<ProviderAdapterError>,
-  "provider"
-> {
-  readonly provider: "amp";
-}
-
-export class AmpAdapter extends Context.Service<AmpAdapter, AmpAdapterShape>()(
-  "t3/provider/Services/AmpAdapter",
-) {}
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 7e21ac56d9e..00000000000
--- a/apps/server/src/provider/Services/ClaudeProvider.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Context } from "effect";
-
-import type { ServerProviderShape } from "./ServerProvider.ts";
-
-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 e116f1a761b..00000000000
--- a/apps/server/src/provider/Services/CodexProvider.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Context } from "effect";
-
-import type { ServerProviderShape } from "./ServerProvider.ts";
-
-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/CopilotAdapter.ts b/apps/server/src/provider/Services/CopilotAdapter.ts
index edacaef4ce6..e4e93cb1896 100644
--- a/apps/server/src/provider/Services/CopilotAdapter.ts
+++ b/apps/server/src/provider/Services/CopilotAdapter.ts
@@ -1,11 +1,28 @@
+/**
+ * CopilotAdapter — Service tag + shape type for the GitHub Copilot adapter.
+ *
+ * The driver model ({@link ../Drivers/CopilotDriver}) bundles one adapter
+ * per instance as a captured closure, so production code no longer reads
+ * adapters through this Service tag. The tag is retained for back-compat
+ * with the conformance suite and any legacy boot graph that still resolves
+ * a single Copilot adapter via the Effect Context.
+ *
+ * Wrap a per-instance adapter into this tag with the `makeCopilotAdapterLive`
+ * Layer in `Layers/CopilotAdapter.ts`.
+ *
+ * @module CopilotAdapter
+ */
 import { Context } from "effect";
 
 import type { ProviderAdapterError } from "../Errors.ts";
 import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
 
-export interface CopilotAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {
-  readonly provider: "copilot";
-}
+/**
+ * CopilotAdapterShape — per-instance Copilot adapter contract. Carries
+ * a branded driver kind (`ProviderDriverKind`) as the nominal discriminant
+ * inherited from `ProviderAdapterShape`.
+ */
+export interface CopilotAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {}
 
 export class CopilotAdapter extends Context.Service<CopilotAdapter, CopilotAdapterShape>()(
   "t3/provider/Services/CopilotAdapter",
diff --git a/apps/server/src/provider/Services/CursorAdapter.ts b/apps/server/src/provider/Services/CursorAdapter.ts
index f1edb316198..83581f0a454 100644
--- a/apps/server/src/provider/Services/CursorAdapter.ts
+++ b/apps/server/src/provider/Services/CursorAdapter.ts
@@ -1,12 +1,19 @@
-import { Context } from "effect";
-
+/**
+ * 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";
 
-export interface CursorAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {
-  readonly provider: "cursor";
-}
-
-export class CursorAdapter extends Context.Service<CursorAdapter, CursorAdapterShape>()(
-  "t3/provider/Services/CursorAdapter",
-) {}
+/**
+ * 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/CursorProvider.ts b/apps/server/src/provider/Services/CursorProvider.ts
deleted file mode 100644
index aa70994f5e9..00000000000
--- a/apps/server/src/provider/Services/CursorProvider.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Context } from "effect";
-
-import type { ServerProviderShape } from "./ServerProvider.ts";
-
-export interface CursorProviderShape extends ServerProviderShape {}
-
-export class CursorProvider extends Context.Service<CursorProvider, CursorProviderShape>()(
-  "t3/provider/Services/CursorProvider",
-) {}
diff --git a/apps/server/src/provider/Services/GeminiCliAdapter.ts b/apps/server/src/provider/Services/GeminiCliAdapter.ts
deleted file mode 100644
index f6b49b97098..00000000000
--- a/apps/server/src/provider/Services/GeminiCliAdapter.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import { Context } from "effect";
-
-import type { ProviderAdapterError } from "../Errors.ts";
-import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
-
-export interface GeminiCliAdapterShape extends Omit<
-  ProviderAdapterShape<ProviderAdapterError>,
-  "provider"
-> {
-  readonly provider: "geminiCli";
-}
-
-export class GeminiCliAdapter extends Context.Service<GeminiCliAdapter, GeminiCliAdapterShape>()(
-  "t3/provider/Services/GeminiCliAdapter",
-) {}
diff --git a/apps/server/src/provider/Services/KiloAdapter.ts b/apps/server/src/provider/Services/KiloAdapter.ts
deleted file mode 100644
index eba18b6e85a..00000000000
--- a/apps/server/src/provider/Services/KiloAdapter.ts
+++ /dev/null
@@ -1,15 +0,0 @@
-import { Context } from "effect";
-
-import type { ProviderAdapterError } from "../Errors.ts";
-import type { ProviderAdapterShape } from "./ProviderAdapter.ts";
-
-export interface KiloAdapterShape extends Omit<
-  ProviderAdapterShape<ProviderAdapterError>,
-  "provider"
-> {
-  readonly provider: "kilo";
-}
-
-export class KiloAdapter extends Context.Service<KiloAdapter, KiloAdapterShape>()(
-  "t3/provider/Services/KiloAdapter",
-) {}
diff --git a/apps/server/src/provider/Services/OpenCodeAdapter.ts b/apps/server/src/provider/Services/OpenCodeAdapter.ts
index ad5660022bf..e3ad97904d1 100644
--- a/apps/server/src/provider/Services/OpenCodeAdapter.ts
+++ b/apps/server/src/provider/Services/OpenCodeAdapter.ts
@@ -1,12 +1,19 @@
-import { Context } from "effect";
-
+/**
+ * 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";
 
-export interface OpenCodeAdapterShape extends ProviderAdapterShape<ProviderAdapterError> {
-  readonly provider: "opencode";
-}
-
-export class OpenCodeAdapter extends Context.Service<OpenCodeAdapter, OpenCodeAdapterShape>()(
-  "t3/provider/Services/OpenCodeAdapter",
-) {}
+/**
+ * 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/OpenCodeProvider.ts b/apps/server/src/provider/Services/OpenCodeProvider.ts
deleted file mode 100644
index a799830eec4..00000000000
--- a/apps/server/src/provider/Services/OpenCodeProvider.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { Context } from "effect";
-
-import type { ServerProviderShape } from "./ServerProvider.ts";
-
-export interface OpenCodeProviderShape extends ServerProviderShape {}
-
-export class OpenCodeProvider extends Context.Service<OpenCodeProvider, OpenCodeProviderShape>()(
-  "t3/provider/Services/OpenCodeProvider",
-) {}
diff --git a/apps/server/src/provider/Services/ProviderAdapter.ts b/apps/server/src/provider/Services/ProviderAdapter.ts
index f153c2bf072..dd1be738721 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,
@@ -23,205 +23,13 @@ import type {
 import type { Effect } from "effect";
 import type { Stream } from "effect";
 
-export type ProviderSessionModelSwitchMode = "in-session" | "restart-session" | "unsupported";
-export type ProviderTransport =
-  | "app-server-json-rpc"
-  | "sdk-cli-server"
-  | "sdk-query"
-  | "acp-stdio"
-  | "http-sse"
-  | "cli-headless-json"
-  | "cli-persistent-json";
-export type ProviderModelDiscovery =
-  | "native"
-  | "acp-or-config"
-  | "config-or-static"
-  | "session-native"
-  | "unsupported";
-export type ProviderHarnessOperation =
-  | "startSession"
-  | "sendTurn"
-  | "interruptTurn"
-  | "respondToRequest"
-  | "respondToUserInput"
-  | "readThread"
-  | "rollbackThread"
-  | "stopSession"
-  | "streamEvents";
-
-export const PROVIDER_HARNESS_OPERATIONS: ReadonlyArray<ProviderHarnessOperation> = [
-  "startSession",
-  "sendTurn",
-  "interruptTurn",
-  "respondToRequest",
-  "respondToUserInput",
-  "readThread",
-  "rollbackThread",
-  "stopSession",
-  "streamEvents",
-] as const;
+export type ProviderSessionModelSwitchMode = "in-session" | "unsupported";
 
 export interface ProviderAdapterCapabilities {
   /**
    * Declares whether changing the model on an existing session is supported.
    */
   readonly sessionModelSwitch: ProviderSessionModelSwitchMode;
-  /**
-   * Declares the provider transport family used by the adapter.
-   */
-  readonly transport: ProviderTransport;
-  /**
-   * Describes how model discovery is sourced for this provider.
-   */
-  readonly modelDiscovery: ProviderModelDiscovery;
-  /**
-   * Quick boolean check for whether model discovery is available at all.
-   */
-  readonly supportsModelDiscovery: boolean;
-  /**
-   * Whether a stopped or missing runtime can be recovered from persisted resume
-   * state.
-   */
-  readonly supportsResume: boolean;
-  /**
-   * Whether conversation rollback is supported by the underlying provider.
-   */
-  readonly supportsRollback: boolean;
-  /**
-   * Whether the adapter accepts chat attachments.
-   */
-  readonly supportsAttachments: boolean;
-  /**
-   * Whether the provider keeps a runtime/session alive across turns after
-   * `startSession`.
-   */
-  readonly persistentRuntime: boolean;
-}
-
-export const PROVIDER_CAPABILITIES_BY_PROVIDER: Readonly<
-  Record<ProviderKind, ProviderAdapterCapabilities>
-> = {
-  codex: {
-    sessionModelSwitch: "in-session",
-    transport: "app-server-json-rpc",
-    modelDiscovery: "native",
-    supportsModelDiscovery: true,
-    supportsResume: true,
-    supportsRollback: true,
-    supportsAttachments: true,
-    persistentRuntime: true,
-  },
-  copilot: {
-    sessionModelSwitch: "in-session",
-    transport: "sdk-cli-server",
-    modelDiscovery: "native",
-    supportsModelDiscovery: true,
-    supportsResume: true,
-    supportsRollback: false,
-    supportsAttachments: true,
-    persistentRuntime: true,
-  },
-  claudeAgent: {
-    sessionModelSwitch: "in-session",
-    transport: "sdk-query",
-    modelDiscovery: "session-native",
-    supportsModelDiscovery: true,
-    supportsResume: true,
-    supportsRollback: false,
-    supportsAttachments: true,
-    persistentRuntime: true,
-  },
-  cursor: {
-    sessionModelSwitch: "unsupported",
-    transport: "acp-stdio",
-    modelDiscovery: "acp-or-config",
-    supportsModelDiscovery: true,
-    supportsResume: true,
-    supportsRollback: false,
-    supportsAttachments: false,
-    persistentRuntime: true,
-  },
-  opencode: {
-    sessionModelSwitch: "in-session",
-    transport: "http-sse",
-    modelDiscovery: "native",
-    supportsModelDiscovery: true,
-    supportsResume: true,
-    supportsRollback: true,
-    supportsAttachments: false,
-    persistentRuntime: true,
-  },
-  geminiCli: {
-    sessionModelSwitch: "restart-session",
-    transport: "cli-headless-json",
-    modelDiscovery: "config-or-static",
-    supportsModelDiscovery: true,
-    supportsResume: true,
-    supportsRollback: false,
-    supportsAttachments: false,
-    persistentRuntime: false,
-  },
-  amp: {
-    sessionModelSwitch: "restart-session",
-    transport: "cli-persistent-json",
-    modelDiscovery: "config-or-static",
-    supportsModelDiscovery: true,
-    supportsResume: false,
-    supportsRollback: false,
-    supportsAttachments: false,
-    persistentRuntime: true,
-  },
-  kilo: {
-    sessionModelSwitch: "in-session",
-    transport: "http-sse",
-    modelDiscovery: "native",
-    supportsModelDiscovery: true,
-    supportsResume: true,
-    supportsRollback: true,
-    supportsAttachments: false,
-    persistentRuntime: true,
-  },
-} as const;
-
-export function getProviderCapabilities(provider: ProviderKind): ProviderAdapterCapabilities {
-  return PROVIDER_CAPABILITIES_BY_PROVIDER[provider];
-}
-
-export function validateProviderAdapterConformance<TError>(
-  adapter: ProviderAdapterShape<TError>,
-): ReadonlyArray<string> {
-  const issues: string[] = [];
-  const expected = getProviderCapabilities(adapter.provider);
-
-  for (const operation of PROVIDER_HARNESS_OPERATIONS) {
-    if (operation === "streamEvents") {
-      if (adapter.streamEvents === undefined || adapter.streamEvents === null) {
-        issues.push(`missing operation '${operation}'`);
-      }
-      continue;
-    }
-
-    if (typeof adapter[operation] !== "function") {
-      issues.push(`missing operation '${operation}'`);
-    }
-  }
-
-  for (const [key, value] of Object.entries(expected) as Array<
-    [
-      keyof ProviderAdapterCapabilities,
-      ProviderAdapterCapabilities[keyof ProviderAdapterCapabilities],
-    ]
-  >) {
-    if (adapter.capabilities[key] !== value) {
-      issues.push(
-        `capability mismatch for '${String(key)}': expected '${String(value)}', received '${String(
-          adapter.capabilities[key],
-        )}'`,
-      );
-    }
-  }
-
-  return issues;
 }
 
 export interface ProviderThreadTurnSnapshot {
@@ -238,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..1161487d5a3 100644
--- a/apps/server/src/provider/Services/ProviderAdapterRegistry.ts
+++ b/apps/server/src/provider/Services/ProviderAdapterRegistry.ts
@@ -1,34 +1,91 @@
 /**
  * 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 type { ProviderDriverKind, ProviderInstanceId } from "@t3tools/contracts";
 import { Context } from "effect";
-import type { Effect } from "effect";
+import type { Effect, PubSub, Scope, Stream } from "effect";
 
 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 +95,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..f642475a243
--- /dev/null
+++ b/apps/server/src/provider/Services/ProviderInstanceRegistry.ts
@@ -0,0 +1,84 @@
+/**
+ * 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 { Context } from "effect";
+import type { Effect, PubSub, Scope, Stream } from "effect";
+
+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..ff861f961c7
--- /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 { Context } from "effect";
+import type { Effect } from "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..13a87bd873b 100644
--- a/apps/server/src/provider/Services/ProviderRegistry.ts
+++ b/apps/server/src/provider/Services/ProviderRegistry.ts
@@ -6,23 +6,42 @@
  *
  * @module ProviderRegistry
  */
-import type { ProviderKind, ServerProvider } from "@t3tools/contracts";
+import type { ProviderInstanceId, ProviderDriverKind, ServerProvider } from "@t3tools/contracts";
 import { Context } from "effect";
 import type { Effect, Stream } from "effect";
 
 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?: ProviderKind) => Effect.Effect<ReadonlyArray<ServerProvider>>;
+  readonly refresh: (provider?: ProviderDriverKind) => Effect.Effect<ReadonlyArray<ServerProvider>>;
 
   /**
-   * Stream of provider snapshot updates.
+   * 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>>;
+
+  /**
+   * 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..17a64689b49 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,
@@ -29,6 +29,7 @@ import type { Effect, Stream } from "effect";
 
 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 +86,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 bee7a1b3736..99ffb800f90 100644
--- a/apps/server/src/provider/Services/ProviderSessionDirectory.ts
+++ b/apps/server/src/provider/Services/ProviderSessionDirectory.ts
@@ -1,5 +1,6 @@
 import type {
-  ProviderKind,
+  ProviderInstanceId,
+  ProviderDriverKind,
   ProviderSessionRuntimeStatus,
   RuntimeMode,
   ThreadId,
@@ -14,7 +15,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;
@@ -39,7 +46,7 @@ export interface ProviderSessionDirectoryShape {
 
   readonly getProvider: (
     threadId: ThreadId,
-  ) => Effect.Effect<ProviderKind, ProviderSessionDirectoryReadError>;
+  ) => Effect.Effect<ProviderDriverKind, ProviderSessionDirectoryReadError>;
 
   readonly getBinding: (
     threadId: ThreadId,
diff --git a/apps/server/src/provider/acp/AcpAdapterSupport.test.ts b/apps/server/src/provider/acp/AcpAdapterSupport.test.ts
index 7457713e0af..a7fcdc4c827 100644
--- a/apps/server/src/provider/acp/AcpAdapterSupport.test.ts
+++ b/apps/server/src/provider/acp/AcpAdapterSupport.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import * as EffectAcpErrors from "effect-acp/errors";
+import { ProviderDriverKind } from "@t3tools/contracts";
 
 import { acpPermissionOutcome, mapAcpToAdapterError } from "./AcpAdapterSupport.ts";
 
@@ -12,7 +13,7 @@ describe("AcpAdapterSupport", () => {
 
   it("maps ACP request errors to provider adapter request errors", () => {
     const error = mapAcpToAdapterError(
-      "cursor",
+      ProviderDriverKind.make("cursor"),
       "thread-1" as never,
       "session/prompt",
       new EffectAcpErrors.AcpRequestError({
diff --git a/apps/server/src/provider/acp/AcpAdapterSupport.ts b/apps/server/src/provider/acp/AcpAdapterSupport.ts
index 914bb7e8c31..499ebd2e707 100644
--- a/apps/server/src/provider/acp/AcpAdapterSupport.ts
+++ b/apps/server/src/provider/acp/AcpAdapterSupport.ts
@@ -1,6 +1,6 @@
 import {
   type ProviderApprovalDecision,
-  type ProviderKind,
+  type ProviderDriverKind,
   type ThreadId,
 } from "@t3tools/contracts";
 import { Schema } from "effect";
@@ -13,7 +13,7 @@ import {
 } from "../Errors.ts";
 
 export function mapAcpToAdapterError(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   threadId: ThreadId,
   method: string,
   error: EffectAcpErrors.AcpError,
diff --git a/apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts b/apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts
index 79b51f585b1..713d0668928 100644
--- a/apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts
+++ b/apps/server/src/provider/acp/AcpCoreRuntimeEvents.test.ts
@@ -1,4 +1,4 @@
-import { RuntimeRequestId, TurnId } from "@t3tools/contracts";
+import { ProviderDriverKind, RuntimeRequestId, TurnId } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 
 import {
@@ -30,7 +30,7 @@ describe("AcpCoreRuntimeEvents", () => {
     expect(
       makeAcpRequestOpenedEvent({
         stamp,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         threadId: "thread-1" as never,
         turnId,
         requestId: RuntimeRequestId.make("request-1"),
@@ -52,7 +52,7 @@ describe("AcpCoreRuntimeEvents", () => {
     expect(
       makeAcpRequestResolvedEvent({
         stamp,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         threadId: "thread-1" as never,
         turnId,
         requestId: RuntimeRequestId.make("request-1"),
@@ -75,7 +75,7 @@ describe("AcpCoreRuntimeEvents", () => {
     expect(
       makeAcpPlanUpdatedEvent({
         stamp,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         threadId: "thread-1" as never,
         turnId,
         payload: {
@@ -95,7 +95,7 @@ describe("AcpCoreRuntimeEvents", () => {
     expect(
       makeAcpToolCallEvent({
         stamp,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         threadId: "thread-1" as never,
         turnId,
         toolCall: {
@@ -119,7 +119,7 @@ describe("AcpCoreRuntimeEvents", () => {
     expect(
       makeAcpContentDeltaEvent({
         stamp,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         threadId: "thread-1" as never,
         turnId,
         itemId: "assistant:session-1:segment:0",
@@ -137,7 +137,7 @@ describe("AcpCoreRuntimeEvents", () => {
     expect(
       makeAcpAssistantItemEvent({
         stamp,
-        provider: "cursor",
+        provider: ProviderDriverKind.make("cursor"),
         threadId: "thread-1" as never,
         turnId,
         itemId: "assistant:session-1:segment:0",
diff --git a/apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts b/apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts
index 0c0f06cc622..c93e61dc37b 100644
--- a/apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts
+++ b/apps/server/src/provider/acp/AcpCoreRuntimeEvents.ts
@@ -4,7 +4,7 @@ import {
   type CanonicalRequestType,
   type EventId,
   type ProviderApprovalDecision,
-  type ProviderKind,
+  type ProviderDriverKind,
   type ProviderRuntimeEvent,
   type RuntimeRequestId,
   type ThreadId,
@@ -78,7 +78,7 @@ function runtimeItemStatusFromAcpToolStatus(
 
 export function makeAcpRequestOpenedEvent(input: {
   readonly stamp: AcpEventStamp;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly threadId: ThreadId;
   readonly turnId: TurnId | undefined;
   readonly requestId: RuntimeRequestId;
@@ -111,7 +111,7 @@ export function makeAcpRequestOpenedEvent(input: {
 
 export function makeAcpRequestResolvedEvent(input: {
   readonly stamp: AcpEventStamp;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly threadId: ThreadId;
   readonly turnId: TurnId | undefined;
   readonly requestId: RuntimeRequestId;
@@ -134,7 +134,7 @@ export function makeAcpRequestResolvedEvent(input: {
 
 export function makeAcpPlanUpdatedEvent(input: {
   readonly stamp: AcpEventStamp;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly threadId: ThreadId;
   readonly turnId: TurnId | undefined;
   readonly payload: AcpPlanUpdate;
@@ -159,7 +159,7 @@ export function makeAcpPlanUpdatedEvent(input: {
 
 export function makeAcpToolCallEvent(input: {
   readonly stamp: AcpEventStamp;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly threadId: ThreadId;
   readonly turnId: TurnId | undefined;
   readonly toolCall: AcpToolCallState;
@@ -193,7 +193,7 @@ export function makeAcpToolCallEvent(input: {
 
 export function makeAcpAssistantItemEvent(input: {
   readonly stamp: AcpEventStamp;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly threadId: ThreadId;
   readonly turnId: TurnId | undefined;
   readonly itemId: string;
@@ -215,7 +215,7 @@ export function makeAcpAssistantItemEvent(input: {
 
 export function makeAcpContentDeltaEvent(input: {
   readonly stamp: AcpEventStamp;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly threadId: ThreadId;
   readonly turnId: TurnId | undefined;
   readonly itemId?: string;
diff --git a/apps/server/src/provider/acp/AcpNativeLogging.ts b/apps/server/src/provider/acp/AcpNativeLogging.ts
index 2fb3f4e8335..3d44aac0a47 100644
--- a/apps/server/src/provider/acp/AcpNativeLogging.ts
+++ b/apps/server/src/provider/acp/AcpNativeLogging.ts
@@ -1,4 +1,4 @@
-import type { ProviderKind, ThreadId } from "@t3tools/contracts";
+import type { ProviderDriverKind, ThreadId } from "@t3tools/contracts";
 import { Cause, Effect } from "effect";
 import type * as EffectAcpProtocol from "effect-acp/protocol";
 
@@ -7,7 +7,7 @@ import type { AcpSessionRequestLogEvent, AcpSessionRuntimeOptions } from "./AcpS
 
 function writeNativeAcpLog(input: {
   readonly nativeEventLogger: EventNdjsonLogger | undefined;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly threadId: ThreadId;
   readonly kind: "request" | "protocol";
   readonly payload: unknown;
@@ -44,7 +44,7 @@ function formatRequestLogPayload(event: AcpSessionRequestLogEvent) {
 
 export function makeAcpNativeLoggers(input: {
   readonly nativeEventLogger: EventNdjsonLogger | undefined;
-  readonly provider: ProviderKind;
+  readonly provider: ProviderDriverKind;
   readonly threadId: ThreadId;
 }): Pick<AcpSessionRuntimeOptions, "requestLogger" | "protocolLogging"> {
   return {
diff --git a/apps/server/src/provider/acp/AcpSessionRuntime.ts b/apps/server/src/provider/acp/AcpSessionRuntime.ts
index d32e70cb4ce..b4cf6656086 100644
--- a/apps/server/src/provider/acp/AcpSessionRuntime.ts
+++ b/apps/server/src/provider/acp/AcpSessionRuntime.ts
@@ -21,7 +21,7 @@ export interface AcpSpawnInput {
   readonly command: string;
   readonly args: ReadonlyArray<string>;
   readonly cwd?: string;
-  readonly env?: Readonly<Record<string, string>>;
+  readonly env?: NodeJS.ProcessEnv;
 }
 
 export interface AcpSessionRuntimeOptions {
diff --git a/apps/server/src/provider/acp/CursorAcpSupport.test.ts b/apps/server/src/provider/acp/CursorAcpSupport.test.ts
index 94de569b2b2..30941acbfd5 100644
--- a/apps/server/src/provider/acp/CursorAcpSupport.test.ts
+++ b/apps/server/src/provider/acp/CursorAcpSupport.test.ts
@@ -99,11 +99,11 @@ describe("applyCursorAcpModelSelection", () => {
       applyCursorAcpModelSelection({
         runtime,
         model: "gpt-5.4-medium-fast[reasoning=medium,context=272k]",
-        modelOptions: {
-          reasoning: "xhigh",
-          contextWindow: "1m",
-          fastMode: true,
-        },
+        selections: [
+          { id: "reasoning", value: "xhigh" },
+          { id: "contextWindow", value: "1m" },
+          { id: "fastMode", value: true },
+        ],
         mapError: ({ step, configId, cause }) =>
           new Error(
             step === "set-config-option"
diff --git a/apps/server/src/provider/acp/CursorAcpSupport.ts b/apps/server/src/provider/acp/CursorAcpSupport.ts
index 72b9af394b3..3e405dd7ff3 100644
--- a/apps/server/src/provider/acp/CursorAcpSupport.ts
+++ b/apps/server/src/provider/acp/CursorAcpSupport.ts
@@ -1,4 +1,4 @@
-import { type CursorModelOptions, type CursorSettings } from "@t3tools/contracts";
+import { type CursorSettings, type ProviderOptionSelection } from "@t3tools/contracts";
 import { Effect, Layer, Scope } from "effect";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import type * as EffectAcpErrors from "effect-acp/errors";
@@ -23,6 +23,7 @@ export interface CursorAcpRuntimeInput extends Omit<
 > {
   readonly childProcessSpawner: ChildProcessSpawner.ChildProcessSpawner["Service"];
   readonly cursorSettings: CursorAcpRuntimeCursorSettings | null | undefined;
+  readonly environment?: NodeJS.ProcessEnv;
 }
 
 export interface CursorAcpModelSelectionErrorContext {
@@ -34,6 +35,7 @@ export interface CursorAcpModelSelectionErrorContext {
 export function buildCursorAcpSpawnInput(
   cursorSettings: CursorAcpRuntimeCursorSettings | null | undefined,
   cwd: string,
+  environment?: NodeJS.ProcessEnv,
 ): AcpSpawnInput {
   return {
     command: cursorSettings?.binaryPath || "agent",
@@ -42,6 +44,7 @@ export function buildCursorAcpSpawnInput(
       "acp",
     ],
     cwd,
+    ...(environment ? { env: environment } : {}),
   };
 }
 
@@ -52,7 +55,7 @@ export const makeCursorAcpRuntime = (
     const acpContext = yield* Layer.build(
       AcpSessionRuntime.layer({
         ...input,
-        spawn: buildCursorAcpSpawnInput(input.cursorSettings, input.cwd),
+        spawn: buildCursorAcpSpawnInput(input.cursorSettings, input.cwd, input.environment),
         authMethodId: "cursor_login",
         clientCapabilities: CURSOR_PARAMETERIZED_MODEL_PICKER_CAPABILITIES,
       }).pipe(
@@ -76,7 +79,7 @@ interface CursorAcpModelSelectionRuntime {
 export function applyCursorAcpModelSelection<E>(input: {
   readonly runtime: CursorAcpModelSelectionRuntime;
   readonly model: string | null | undefined;
-  readonly modelOptions: CursorModelOptions | null | undefined;
+  readonly selections: ReadonlyArray<ProviderOptionSelection> | null | undefined;
   readonly mapError: (context: CursorAcpModelSelectionErrorContext) => E;
 }): Effect.Effect<void, E> {
   return Effect.gen(function* () {
@@ -91,7 +94,7 @@ export function applyCursorAcpModelSelection<E>(input: {
 
     const configUpdates = resolveCursorAcpConfigUpdates(
       yield* input.runtime.getConfigOptions,
-      input.modelOptions,
+      input.selections,
     );
     for (const update of configUpdates) {
       yield* input.runtime.setConfigOption(update.configId, update.value).pipe(
diff --git a/apps/server/src/provider/builtInDrivers.ts b/apps/server/src/provider/builtInDrivers.ts
new file mode 100644
index 00000000000..09c165e8c61
--- /dev/null
+++ b/apps/server/src/provider/builtInDrivers.ts
@@ -0,0 +1,65 @@
+/**
+ * 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 { AmpDriver, type AmpDriverEnv } from "./Drivers/AmpDriver.ts";
+import { ClaudeDriver, type ClaudeDriverEnv } from "./Drivers/ClaudeDriver.ts";
+import { CodexDriver, type CodexDriverEnv } from "./Drivers/CodexDriver.ts";
+import { CopilotDriver, type CopilotDriverEnv } from "./Drivers/CopilotDriver.ts";
+import { CursorDriver, type CursorDriverEnv } from "./Drivers/CursorDriver.ts";
+import { GeminiCliDriver, type GeminiCliDriverEnv } from "./Drivers/GeminiCliDriver.ts";
+import { KiloDriver, type KiloDriverEnv } from "./Drivers/KiloDriver.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
+  | AmpDriverEnv
+  | CopilotDriverEnv
+  | GeminiCliDriverEnv
+  | KiloDriverEnv;
+
+/**
+ * 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.
+ *
+ * Upstream drivers come first (Codex, Claude, Cursor, OpenCode); fork
+ * extension drivers follow in alphabetical order.
+ */
+export const BUILT_IN_DRIVERS: ReadonlyArray<AnyProviderDriver<BuiltInDriversEnv>> = [
+  CodexDriver,
+  ClaudeDriver,
+  CursorDriver,
+  OpenCodeDriver,
+  AmpDriver,
+  CopilotDriver,
+  GeminiCliDriver,
+  KiloDriver,
+];
diff --git a/apps/server/src/provider/builtInProviderCatalog.ts b/apps/server/src/provider/builtInProviderCatalog.ts
new file mode 100644
index 00000000000..ee25b6d0184
--- /dev/null
+++ b/apps/server/src/provider/builtInProviderCatalog.ts
@@ -0,0 +1,17 @@
+import type { ProviderDriverKind, ProviderInstanceId, ServerProvider } from "@t3tools/contracts";
+import type { Stream } from "effect";
+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/claude-agent-sdk.d.ts b/apps/server/src/provider/claude-agent-sdk.d.ts
deleted file mode 100644
index dd98e6c595f..00000000000
--- a/apps/server/src/provider/claude-agent-sdk.d.ts
+++ /dev/null
@@ -1,186 +0,0 @@
-declare module "@anthropic-ai/claude-agent-sdk" {
-  export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk";
-
-  export interface PermissionUpdate {
-    readonly [key: string]: unknown;
-  }
-
-  export type PermissionResult =
-    | {
-        readonly behavior: "allow";
-        readonly updatedInput?: unknown;
-        readonly message?: string;
-      }
-    | {
-        readonly behavior: "deny";
-        readonly updatedInput?: unknown;
-        readonly message?: string;
-      };
-
-  export interface CanUseToolCallbackOptions {
-    readonly signal: AbortSignal;
-    readonly toolUseID?: string;
-    readonly suggestions?: ReadonlyArray<PermissionUpdate>;
-    readonly [key: string]: unknown;
-  }
-
-  export type CanUseTool = (
-    toolName: string,
-    toolInput: Record<string, unknown>,
-    callbackOptions: CanUseToolCallbackOptions,
-  ) => Promise<PermissionResult>;
-
-  export interface SDKUserMessage {
-    readonly [key: string]: unknown;
-  }
-
-  export interface SDKResultMessage {
-    readonly subtype?: string;
-    readonly duration_ms?: number;
-    readonly durationMs?: number;
-    readonly is_error?: boolean;
-    readonly isError?: boolean;
-    readonly num_turns?: number;
-    readonly total_cost_usd?: number;
-    readonly stop_reason?: string | null;
-    readonly errors?: ReadonlyArray<unknown>;
-    readonly usage?: {
-      readonly input_tokens?: number;
-      readonly output_tokens?: number;
-      readonly cache_creation_input_tokens?: number;
-      readonly cache_read_input_tokens?: number;
-      readonly server_tool_use?: {
-        readonly web_search_requests?: number;
-      };
-    };
-    readonly modelUsage?: { readonly [key: string]: unknown };
-    readonly result?: string;
-    readonly session_id?: string;
-    readonly [key: string]: unknown;
-  }
-
-  export interface SDKMessage {
-    readonly type?: string;
-    readonly subtype?: string;
-    readonly role?: string;
-    readonly message?: {
-      readonly id?: string;
-      readonly content?: ReadonlyArray<unknown>;
-      readonly [key: string]: unknown;
-    };
-    readonly content?: ReadonlyArray<Record<string, unknown>>;
-    readonly uuid?: string;
-    readonly session_id?: string;
-    readonly parent_tool_use_id?: string;
-    readonly tool_use_id?: string;
-    readonly tool_name?: string;
-    readonly input?: Record<string, unknown>;
-    readonly result?: string;
-    readonly error?: string;
-    readonly errors?: ReadonlyArray<unknown>;
-    readonly content_block?: Record<string, unknown>;
-    readonly index?: number;
-    readonly preceding_tool_use_ids?: ReadonlyArray<string>;
-    readonly is_error?: boolean;
-    readonly suggestions?: ReadonlyArray<PermissionUpdate>;
-
-    // System message fields
-    readonly status?: string;
-    readonly hook_id?: string;
-    readonly hook_name?: string;
-    readonly hook_event?: string;
-    readonly output?: string;
-    readonly stdout?: string;
-    readonly stderr?: string;
-    readonly outcome?: "error" | "cancelled" | "success";
-    readonly exit_code?: number;
-
-    // Task fields
-    readonly task_id?: string;
-    readonly description?: string;
-    readonly task_type?: string;
-    readonly summary?: string;
-    readonly usage?: { readonly [key: string]: unknown };
-    readonly last_tool_name?: string;
-
-    // File persistence fields
-    readonly files?: ReadonlyArray<{ readonly filename: string; readonly file_id: string }>;
-    readonly failed?: ReadonlyArray<{ readonly filename: string; readonly error: string }>;
-
-    // Tool progress fields
-    readonly elapsed_time_seconds?: number;
-
-    // Auth status fields
-    readonly isAuthenticating?: boolean;
-
-    // Stream event fields
-    readonly event?: Record<string, unknown>;
-
-    readonly [key: string]: unknown;
-  }
-
-  export type ThinkingConfig =
-    | { readonly type: "adaptive" }
-    | { readonly type: "enabled"; readonly budgetTokens?: number }
-    | { readonly type: "disabled" };
-
-  export type EffortLevel = "low" | "medium" | "high" | "max";
-
-  export interface SpawnOptions {
-    readonly args: string[];
-    readonly env?: Record<string, string | undefined>;
-    readonly cwd?: string;
-    readonly [key: string]: unknown;
-  }
-
-  export interface SpawnedProcess {
-    readonly stdin: NodeJS.WritableStream;
-    readonly stdout: NodeJS.ReadableStream;
-    killed: boolean;
-    exitCode: number | null;
-    kill(signal: NodeJS.Signals): boolean;
-    on(event: "exit" | "error", listener: (...args: unknown[]) => void): void;
-    once(event: "exit" | "error", listener: (...args: unknown[]) => void): void;
-    off(event: "exit" | "error", listener: (...args: unknown[]) => void): void;
-  }
-
-  export type SettingSource = "user" | "project" | "local";
-
-  export interface Options {
-    readonly cwd?: string;
-    readonly model?: string;
-    readonly pathToClaudeCodeExecutable?: string;
-    readonly permissionMode?: PermissionMode;
-    readonly allowDangerouslySkipPermissions?: boolean;
-    /** @deprecated Use `thinking` instead. */
-    readonly maxThinkingTokens?: number;
-    readonly thinking?: ThinkingConfig;
-    readonly effort?: EffortLevel;
-    readonly resume?: string;
-    readonly resumeSessionAt?: string;
-    readonly includePartialMessages?: boolean;
-    readonly persistSession?: boolean;
-    readonly sessionId?: string;
-    readonly settings?: Record<string, unknown>;
-    readonly settingSources?: SettingSource[];
-    readonly spawnClaudeCodeProcess?: (options: SpawnOptions) => SpawnedProcess;
-    readonly canUseTool?: CanUseTool;
-    readonly env?: Record<string, string | undefined>;
-    readonly additionalDirectories?: ReadonlyArray<string>;
-    readonly stderr?: (message: string) => void;
-  }
-
-  export type Query = AsyncIterable<SDKMessage> & {
-    readonly interrupt?: () => Promise<void>;
-    readonly setModel?: (model?: string) => Promise<void>;
-    readonly setPermissionMode?: (mode: PermissionMode) => Promise<void>;
-    readonly setMaxThinkingTokens?: (maxThinkingTokens: number | null) => Promise<void>;
-    readonly close?: () => void;
-    readonly initializationResult?: () => Promise<Record<string, unknown>>;
-  };
-
-  export function query(input: {
-    readonly prompt: string | AsyncIterable<SDKUserMessage>;
-    readonly options?: Options;
-  }): Query;
-}
diff --git a/apps/server/src/provider/copilot-sdk.d.ts b/apps/server/src/provider/copilot-sdk.d.ts
deleted file mode 100644
index eaf0def0904..00000000000
--- a/apps/server/src/provider/copilot-sdk.d.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-declare module "@github/copilot-sdk" {
-  export type CopilotClientOptions = any;
-  export type ModelInfo = any;
-  export type PermissionRequest = any;
-  export type PermissionRequestResult = any;
-  export type SessionEvent = any;
-  export type CopilotSession = any;
-
-  export class CopilotClient {
-    constructor(options: CopilotClientOptions);
-    start(): Promise<void>;
-    listModels(): Promise<ModelInfo[]>;
-    createSession(config: any): Promise<CopilotSession>;
-    resumeSession(sessionId: string, config: any): Promise<CopilotSession>;
-    stop(): Promise<Error[]>;
-  }
-}
diff --git a/apps/server/src/provider/makeManagedServerProvider.test.ts b/apps/server/src/provider/makeManagedServerProvider.test.ts
index 31fe73a467e..ff664763804 100644
--- a/apps/server/src/provider/makeManagedServerProvider.test.ts
+++ b/apps/server/src/provider/makeManagedServerProvider.test.ts
@@ -1,15 +1,28 @@
 import { describe, it, assert } from "@effect/vitest";
-import type { ServerProvider } from "@t3tools/contracts";
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
 import { Deferred, Effect, Fiber, PubSub, Ref, Stream } from "effect";
 
 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 initialSnapshot: ServerProvider = {
-  provider: "codex",
+  instanceId: ProviderInstanceId.make("codex"),
+  driver: ProviderDriverKind.make("codex"),
   enabled: true,
   installed: true,
   version: null,
@@ -23,7 +36,8 @@ const initialSnapshot: ServerProvider = {
 };
 
 const refreshedSnapshot: ServerProvider = {
-  provider: "codex",
+  instanceId: ProviderInstanceId.make("codex"),
+  driver: ProviderDriverKind.make("codex"),
   enabled: true,
   installed: true,
   version: "1.0.0",
@@ -43,13 +57,7 @@ const enrichedSnapshot: ServerProvider = {
       slug: "composer-2",
       name: "Composer 2",
       isCustom: false,
-      capabilities: {
-        reasoningEffortLevels: [],
-        supportsFastMode: true,
-        supportsThinkingToggle: false,
-        contextWindowOptions: [],
-        promptInjectedEffortLevels: [],
-      },
+      capabilities: fastModeCapabilities,
     },
   ],
 };
@@ -68,13 +76,7 @@ const enrichedSnapshotSecond: ServerProvider = {
       slug: "gpt-5.4",
       name: "GPT-5.4",
       isCustom: false,
-      capabilities: {
-        reasoningEffortLevels: [],
-        supportsFastMode: false,
-        supportsThinkingToggle: false,
-        contextWindowOptions: [],
-        promptInjectedEffortLevels: [],
-      },
+      capabilities: emptyCapabilities,
     },
   ],
 };
diff --git a/apps/server/src/provider/opencodeRuntime.ts b/apps/server/src/provider/opencodeRuntime.ts
index 41ec5102c3c..c3e973e7e32 100644
--- a/apps/server/src/provider/opencodeRuntime.ts
+++ b/apps/server/src/provider/opencodeRuntime.ts
@@ -109,6 +109,7 @@ export interface OpenCodeRuntimeShape {
    */
   readonly startOpenCodeServerProcess: (input: {
     readonly binaryPath: string;
+    readonly environment?: NodeJS.ProcessEnv;
     readonly port?: number;
     readonly hostname?: string;
     readonly timeoutMs?: number;
@@ -121,6 +122,7 @@ export interface OpenCodeRuntimeShape {
   readonly connectToOpenCodeServer: (input: {
     readonly binaryPath: string;
     readonly serverUrl?: string | null;
+    readonly environment?: NodeJS.ProcessEnv;
     readonly port?: number;
     readonly hostname?: string;
     readonly timeoutMs?: number;
@@ -128,6 +130,7 @@ export interface OpenCodeRuntimeShape {
   readonly runOpenCodeCommand: (input: {
     readonly binaryPath: string;
     readonly args: ReadonlyArray<string>;
+    readonly environment?: NodeJS.ProcessEnv;
   }) => Effect.Effect<OpenCodeCommandResult, OpenCodeRuntimeError>;
   readonly createOpenCodeSdkClient: (input: {
     readonly baseUrl: string;
@@ -274,7 +277,7 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
       const child = yield* spawner.spawn(
         ChildProcess.make(input.binaryPath, [...input.args], {
           shell: process.platform === "win32",
-          env: process.env,
+          env: input.environment ?? process.env,
         }),
       );
       const [stdout, stderr, code] = yield* Effect.all(
@@ -330,8 +333,10 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
       const child = yield* spawner
         .spawn(
           ChildProcess.make(input.binaryPath, args, {
+            detached: process.platform !== "win32",
+            shell: process.platform === "win32",
             env: {
-              ...process.env,
+              ...(input.environment ?? process.env),
               OPENCODE_CONFIG_CONTENT: JSON.stringify({}),
             },
           }),
@@ -348,6 +353,25 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
           ),
         );
 
+      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>();
@@ -452,6 +476,7 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
 
     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 } : {}),
diff --git a/apps/server/src/provider/providerKind.ts b/apps/server/src/provider/providerKind.ts
index 14f54075553..a748919b460 100644
--- a/apps/server/src/provider/providerKind.ts
+++ b/apps/server/src/provider/providerKind.ts
@@ -1,4 +1,11 @@
-import type { ProviderKind } from "@t3tools/contracts";
+/**
+ * Fork-local `ProviderKind` closed string union.
+ *
+ * Upstream's #2277 refactor removed `ProviderKind` from `@t3tools/contracts`
+ * in favor of the open branded `ProviderDriverKind`. The fork still ships
+ * eight built-in driver names and needs a closed union for legacy-name
+ * normalization in `OrchestrationEventStore`'s read path.
+ */
 
 const PROVIDER_KINDS = [
   "codex",
@@ -9,7 +16,9 @@ const PROVIDER_KINDS = [
   "geminiCli",
   "amp",
   "kilo",
-] as const satisfies ReadonlyArray<ProviderKind>;
+] as const;
+
+export type ProviderKind = (typeof PROVIDER_KINDS)[number];
 
 const LEGACY_PROVIDER_KIND_ALIASES = {
   claudeCode: "claudeAgent",
diff --git a/apps/server/src/provider/providerSnapshot.test.ts b/apps/server/src/provider/providerSnapshot.test.ts
index 0a0d31ccb59..449dca8fc5a 100644
--- a/apps/server/src/provider/providerSnapshot.test.ts
+++ b/apps/server/src/provider/providerSnapshot.test.ts
@@ -1,23 +1,33 @@
 import { describe, expect, it } from "vitest";
-import type { ModelCapabilities } from "@t3tools/contracts";
+import { ProviderDriverKind, type ModelCapabilities } from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
 
 import { providerModelsFromSettings } from "./providerSnapshot.ts";
 
-const OPENCODE_CUSTOM_MODEL_CAPABILITIES: ModelCapabilities = {
-  reasoningEffortLevels: [],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-  variantOptions: [{ value: "medium", label: "Medium", isDefault: true }],
-  agentOptions: [{ value: "build", label: "Build", isDefault: true }],
-};
+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(
       [],
-      "opencode",
+      ProviderDriverKind.make("opencode"),
       ["openai/gpt-5"],
       OPENCODE_CUSTOM_MODEL_CAPABILITIES,
     );
diff --git a/apps/server/src/provider/providerSnapshot.ts b/apps/server/src/provider/providerSnapshot.ts
index 82a3f418803..af0c91274c3 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,
@@ -8,7 +9,9 @@ import type {
   ServerProviderState,
 } from "@t3tools/contracts";
 import { Effect, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { normalizeModelSlug } from "@t3tools/shared/model";
+import { isWindowsCommandNotFound } from "../processRunner.ts";
 
 export const DEFAULT_TIMEOUT_MS = 4_000;
 // Auth status checks involve disk/network lookups and can be slow on first run (especially Windows)
@@ -34,6 +37,8 @@ export interface ServerProviderPresentation {
   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();
@@ -45,6 +50,26 @@ export function isCommandMissingCause(error: Error): boolean {
   return lower.includes("enoent") || lower.includes("notfound");
 }
 
+export const spawnAndCollect = (binaryPath: string, command: ChildProcess.Command) =>
+  Effect.gen(function* () {
+    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" },
+    );
+
+    const result: CommandResult = { stdout, stderr, code: exitCode };
+    if (isWindowsCommandNotFound(exitCode, stderr)) {
+      return yield* Effect.fail(new Error(`spawn ${binaryPath} ENOENT`));
+    }
+    return result;
+  }).pipe(Effect.scoped);
+
 export function detailFromResult(
   result: CommandResult & { readonly timedOut?: boolean },
 ): string | undefined {
@@ -88,7 +113,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> {
@@ -157,20 +182,18 @@ export function buildBooleanOptionDescriptor(input: {
 }
 
 export function buildServerProvider(input: {
-  provider: ServerProvider["provider"];
-  presentation?: ServerProviderPresentation;
+  presentation: ServerProviderPresentation;
   enabled: boolean;
   checkedAt: string;
   models: ReadonlyArray<ServerProviderModel>;
   slashCommands?: ReadonlyArray<ServerProviderSlashCommand>;
   skills?: ReadonlyArray<ServerProviderSkill>;
   probe: ProviderProbeResult;
-}): ServerProvider {
+}): ServerProviderDraft {
   return {
-    provider: input.provider,
-    ...(input.presentation?.displayName ? { displayName: input.presentation.displayName } : {}),
-    ...(input.presentation?.badgeLabel ? { badgeLabel: input.presentation.badgeLabel } : {}),
-    ...(typeof input.presentation?.showInteractionModeToggle === "boolean"
+    displayName: input.presentation.displayName,
+    ...(input.presentation.badgeLabel ? { badgeLabel: input.presentation.badgeLabel } : {}),
+    ...(typeof input.presentation.showInteractionModeToggle === "boolean"
       ? { showInteractionModeToggle: input.presentation.showInteractionModeToggle }
       : {}),
     enabled: input.enabled,
diff --git a/apps/server/src/provider/providerStatusCache.test.ts b/apps/server/src/provider/providerStatusCache.test.ts
index b0cb5bc663c..8986ba48f29 100644
--- a/apps/server/src/provider/providerStatusCache.test.ts
+++ b/apps/server/src/provider/providerStatusCache.test.ts
@@ -1,20 +1,33 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import type { ServerProvider } from "@t3tools/contracts";
+import {
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
 import { assert, it } from "@effect/vitest";
 import { Effect, FileSystem } from "effect";
 
 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: ServerProvider["provider"],
+  provider: ProviderDriverKind,
   overrides?: Partial<ServerProvider>,
 ): ServerProvider => ({
-  provider,
+  instanceId: defaultInstanceIdForDriver(provider),
+  driver: provider,
   enabled: true,
   installed: true,
   version: "1.0.0",
@@ -32,26 +45,26 @@ it.layer(NodeServices.layer)("providerStatusCache", (it) => {
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-provider-cache-" });
-      const codexProvider = makeProvider("codex");
-      const claudeProvider = makeProvider("claudeAgent", {
+      const codexProvider = makeProvider(CODEX_DRIVER);
+      const claudeProvider = makeProvider(CLAUDE_AGENT_DRIVER, {
         status: "warning",
         auth: { status: "unknown" },
       });
-      const openCodeProvider = makeProvider("opencode", {
+      const openCodeProvider = makeProvider(OPENCODE_DRIVER, {
         status: "warning",
         auth: { status: "unknown", type: "opencode" },
       });
-      const codexPath = resolveProviderStatusCachePath({
+      const codexPath = yield* resolveProviderStatusCachePath({
         cacheDir: tempDir,
-        provider: "codex",
+        instanceId: defaultInstanceIdForDriver(ProviderDriverKind.make("codex")),
       });
-      const claudePath = resolveProviderStatusCachePath({
+      const claudePath = yield* resolveProviderStatusCachePath({
         cacheDir: tempDir,
-        provider: "claudeAgent",
+        instanceId: defaultInstanceIdForDriver(ProviderDriverKind.make("claudeAgent")),
       });
-      const openCodePath = resolveProviderStatusCachePath({
+      const openCodePath = yield* resolveProviderStatusCachePath({
         cacheDir: tempDir,
-        provider: "opencode",
+        instanceId: defaultInstanceIdForDriver(ProviderDriverKind.make("opencode")),
       });
 
       yield* writeProviderStatusCache({
@@ -74,20 +87,14 @@ it.layer(NodeServices.layer)("providerStatusCache", (it) => {
   );
 
   it("hydrates cached provider status while preserving current settings-derived models", () => {
-    const cachedCodex = makeProvider("codex", {
+    const cachedCodex = makeProvider(CODEX_DRIVER, {
       checkedAt: "2026-04-10T12:00:00.000Z",
       models: [
         {
           slug: "gpt-5-mini",
           name: "GPT-5 Mini",
           isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [],
-            supportsFastMode: false,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
+          capabilities: emptyCapabilities,
         },
       ],
       message: "Cached message",
@@ -100,19 +107,13 @@ it.layer(NodeServices.layer)("providerStatusCache", (it) => {
         },
       ],
     });
-    const fallbackCodex = makeProvider("codex", {
+    const fallbackCodex = makeProvider(CODEX_DRIVER, {
       models: [
         {
           slug: "gpt-5.4",
           name: "GPT-5.4",
           isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [],
-            supportsFastMode: false,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
+          capabilities: emptyCapabilities,
         },
       ],
       message: "Pending refresh",
@@ -131,13 +132,7 @@ it.layer(NodeServices.layer)("providerStatusCache", (it) => {
             slug: "gpt-5-mini",
             name: "GPT-5 Mini",
             isCustom: false,
-            capabilities: {
-              reasoningEffortLevels: [],
-              supportsFastMode: false,
-              supportsThinkingToggle: false,
-              contextWindowOptions: [],
-              promptInjectedEffortLevels: [],
-            },
+            capabilities: emptyCapabilities,
           },
         ],
         installed: cachedCodex.installed,
@@ -153,11 +148,11 @@ it.layer(NodeServices.layer)("providerStatusCache", (it) => {
   });
 
   it("ignores stale cached enabled state when the provider is now disabled", () => {
-    const cachedCodex = makeProvider("codex", {
+    const cachedCodex = makeProvider(CODEX_DRIVER, {
       checkedAt: "2026-04-10T12:00:00.000Z",
       message: "Cached ready status",
     });
-    const disabledFallback = makeProvider("codex", {
+    const disabledFallback = makeProvider(CODEX_DRIVER, {
       enabled: false,
       installed: false,
       version: null,
@@ -174,4 +169,68 @@ it.layer(NodeServices.layer)("providerStatusCache", (it) => {
       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
index 6ba5a4d5bb2..d6c051fd560 100644
--- a/apps/server/src/provider/providerStatusCache.ts
+++ b/apps/server/src/provider/providerStatusCache.ts
@@ -1,25 +1,17 @@
-import * as nodePath from "node:path";
-import { type ServerProvider, ServerProvider as ServerProviderSchema } from "@t3tools/contracts";
-import { Cause, Effect, FileSystem, Schema } from "effect";
+import {
+  type ProviderDriverKind,
+  type ProviderInstanceId,
+  type ServerProvider,
+  ServerProvider as ServerProviderSchema,
+} from "@t3tools/contracts";
+import { Cause, Effect, FileSystem, Path, Schema } from "effect";
 
 import { writeFileStringAtomically } from "../atomicWrite.ts";
 
-export const PROVIDER_CACHE_IDS = [
-  "codex",
-  "claudeAgent",
-  "opencode",
-  "cursor",
-] as const satisfies ReadonlyArray<ServerProvider["provider"]>;
-
 const decodeProviderStatusCache = Schema.decodeUnknownEffect(
   Schema.fromJsonString(ServerProviderSchema),
 );
 
-const providerOrderRank = (provider: ServerProvider["provider"]): number => {
-  const rank = (PROVIDER_CACHE_IDS as ReadonlyArray<ServerProvider["provider"]>).indexOf(provider);
-  return rank === -1 ? Number.MAX_SAFE_INTEGER : rank;
-};
-
 const mergeProviderModels = (
   fallbackModels: ReadonlyArray<ServerProvider["models"][number]>,
   cachedModels: ReadonlyArray<ServerProvider["models"][number]>,
@@ -32,13 +24,27 @@ export const orderProviderSnapshots = (
   providers: ReadonlyArray<ServerProvider>,
 ): ReadonlyArray<ServerProvider> =>
   [...providers].toSorted(
-    (left, right) => providerOrderRank(left.provider) - providerOrderRank(right.provider),
+    (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
@@ -64,10 +70,46 @@ export const hydrateCachedProvider = (input: {
     : hydratedProvider;
 };
 
-export const resolveProviderStatusCachePath = (input: {
+/**
+ * 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: ServerProvider["provider"];
-}) => nodePath.join(input.cacheDir, `${input.provider}.json`);
+  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* () {
diff --git a/apps/server/src/provider/testUtils/providerAdapterRegistryMock.ts b/apps/server/src/provider/testUtils/providerAdapterRegistryMock.ts
new file mode 100644
index 00000000000..9a4f107db8b
--- /dev/null
+++ b/apps/server/src/provider/testUtils/providerAdapterRegistryMock.ts
@@ -0,0 +1,95 @@
+/**
+ * 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 { Effect, PubSub, Record, Result, Stream } from "effect";
+
+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..97a532a9d98
--- /dev/null
+++ b/apps/server/src/provider/unavailableProviderSnapshot.ts
@@ -0,0 +1,72 @@
+/**
+ * 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 { 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 `new Date()` so callers
+   * (notably tests) don't have to pass it.
+   */
+  readonly checkedAt?: string;
+}
+
+/**
+ * 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,
+): ServerProvider {
+  const checkedAt = input.checkedAt ?? new Date().toISOString();
+  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 7c62395598b..b48273ff485 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -17,6 +17,8 @@ import {
   type OrchestrationEvent,
   ORCHESTRATION_WS_METHODS,
   ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   ResolvedKeybindingRule,
   ThreadId,
   WS_METHODS,
@@ -27,6 +29,7 @@ import { assert, it } from "@effect/vitest";
 import { assertFailure, assertInclude, assertTrue } from "@effect/vitest/utils";
 import {
   Deferred,
+  DateTime,
   Duration,
   Effect,
   FileSystem,
@@ -36,6 +39,7 @@ import {
   Path,
   Stream,
 } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
 import {
   FetchHttpClient,
   HttpBody,
@@ -48,6 +52,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";
@@ -56,13 +62,7 @@ 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 {
-  GitStatusBroadcaster,
-  type GitStatusBroadcasterShape,
-} from "./git/Services/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 {
@@ -75,6 +75,7 @@ import {
   type ProjectionSnapshotQueryShape,
 } from "./orchestration/Services/ProjectionSnapshotQuery.ts";
 import { SqlitePersistenceMemory } from "./persistence/Layers/Sqlite.ts";
+import { PersistenceSqlError } from "./persistence/Errors.ts";
 import {
   ProviderRegistry,
   type ProviderRegistryShape,
@@ -103,6 +104,13 @@ 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";
 
@@ -110,7 +118,7 @@ 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 = {
@@ -193,26 +201,14 @@ const makeDefaultOrchestrationThreadShell = (
   };
 };
 
-const workspaceAndProjectServicesLayer = Layer.mergeAll(
-  WorkspacePathsLive,
-  WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive)),
-  WorkspaceFileSystemLive.pipe(
-    Layer.provide(WorkspacePathsLive),
-    Layer.provide(WorkspaceEntriesLive.pipe(Layer.provide(WorkspacePathsLive))),
-  ),
-  ProjectFaviconResolverLive,
-);
-
 const browserOtlpTracingLayer = Layer.mergeAll(
   FetchHttpClient.layer,
   OtlpSerialization.layerJson,
   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* () {
@@ -322,9 +318,12 @@ const buildAppUnderTest = (options?: {
     providerRegistry?: Partial<ProviderRegistryShape>;
     serverSettings?: Partial<ServerSettingsShape>;
     open?: Partial<OpenShape>;
-    gitCore?: Partial<GitCoreShape>;
+    vcsDriver?: Partial<VcsDriver.VcsDriverShape>;
+    vcsDriverRegistry?: Partial<VcsDriverRegistry.VcsDriverRegistryShape>;
+    gitVcsDriver?: Partial<GitVcsDriver.GitVcsDriverShape>;
     gitManager?: Partial<GitManagerShape>;
-    gitStatusBroadcaster?: Partial<GitStatusBroadcasterShape>;
+    sourceControlRepositoryService?: Partial<SourceControlRepositoryService.SourceControlRepositoryServiceShape>;
+    vcsStatusBroadcaster?: Partial<VcsStatusBroadcaster.VcsStatusBroadcasterShape>;
     projectSetupScriptRunner?: Partial<ProjectSetupScriptRunnerShape>;
     terminalManager?: Partial<TerminalManagerShape>;
     orchestrationEngine?: Partial<OrchestrationEngineShape>;
@@ -367,25 +366,115 @@ const buildAppUnderTest = (options?: {
       desktopBootstrapToken: defaultDesktopBootstrapToken,
       autoBootstrapProjectFromCwd: false,
       logWebSocketEvents: false,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       ...options?.config,
     };
     const layerConfig = Layer.succeed(ServerConfig, config);
-    const gitCoreLayer = Layer.mock(GitCore)({
+    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),
-      ...options?.layers?.gitCore,
+      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 workspaceEntriesLayer = WorkspaceEntriesLive.pipe(
       Layer.provide(WorkspacePathsLive),
-      Layer.provideMerge(gitCoreLayer),
+      Layer.provideMerge(vcsDriverRegistryLayer),
     );
     const workspaceAndProjectServicesLayer = Layer.mergeAll(
       WorkspacePathsLive,
@@ -396,11 +485,19 @@ const buildAppUnderTest = (options?: {
       ),
       ProjectFaviconResolverLive,
     );
-    const gitStatusBroadcasterLayer = options?.layers?.gitStatusBroadcaster
-      ? Layer.mock(GitStatusBroadcaster)({
-          ...options.layers.gitStatusBroadcaster,
+    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,
         })
-      : GitStatusBroadcasterLive.pipe(Layer.provide(gitManagerLayer));
+      : VcsStatusBroadcaster.layer.pipe(Layer.provide(gitWorkflowLayer));
 
     const servedRoutesLayer = HttpRouter.serve(makeRoutesLayer, {
       disableListenLog: true,
@@ -439,9 +536,16 @@ const buildAppUnderTest = (options?: {
           ...options?.layers?.open,
         }),
       ),
-      Layer.provide(gitCoreLayer),
       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 }),
@@ -539,7 +643,7 @@ const buildAppUnderTest = (options?: {
           ...options?.layers?.repositoryIdentityResolver,
         }),
       ),
-      Layer.provideMerge(authTestLayer),
+      Layer.provideMerge(makeAuthTestLayer()),
       Layer.provide(workspaceAndProjectServicesLayer),
       Layer.provideMerge(FetchHttpClient.layer),
       Layer.provide(layerConfig),
@@ -1845,7 +1949,8 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     Effect.gen(function* () {
       const providers = [
         {
-          provider: "codex" as const,
+          instanceId: ProviderInstanceId.make("codex"),
+          driver: ProviderDriverKind.make("codex"),
           enabled: true,
           installed: true,
           version: "1.0.0",
@@ -1906,7 +2011,7 @@ 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)),
   );
@@ -1915,7 +2020,8 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     Effect.gen(function* () {
       const nextProviders = [
         {
-          provider: "codex" as const,
+          instanceId: ProviderInstanceId.make("codex"),
+          driver: ProviderDriverKind.make("codex"),
           enabled: true,
           installed: true,
           version: "1.0.0",
@@ -2064,12 +2170,17 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          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(
@@ -2164,7 +2275,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             workspaceRoot: missingWorkspaceRoot,
             createWorkspaceRootIfMissing: true,
             defaultModelSelection: {
-              provider: "codex",
+              instanceId: ProviderInstanceId.make("codex"),
               model: "gpt-5-codex",
             },
             createdAt: new Date().toISOString(),
@@ -2269,9 +2380,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 },
               }),
@@ -2285,9 +2396,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,
@@ -2368,16 +2479,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,
@@ -2386,18 +2497,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),
           },
         },
       });
@@ -2405,13 +2518,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);
@@ -2455,27 +2568,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",
           }),
@@ -2484,25 +2595,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",
           }),
         ),
@@ -2522,7 +2633,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       let statusCalls = 0;
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          gitVcsDriver: {
             pullCurrentBranch: () => Effect.fail(gitError),
           },
           gitManager: {
@@ -2541,9 +2652,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 },
               }),
@@ -2562,9 +2673,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,
@@ -2579,7 +2690,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,
         ),
       );
@@ -2618,9 +2729,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 },
               }),
@@ -2639,9 +2750,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,
@@ -2676,12 +2787,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: {
@@ -2690,9 +2801,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 },
               }),
@@ -2712,7 +2823,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       const wsUrl = yield* getWsServerUrl("/ws");
       const startedAt = Date.now();
       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;
 
@@ -2727,15 +2838,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 },
                 }),
@@ -2800,6 +2914,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
         yield* buildAppUnderTest({
           layers: {
+            vcsDriver: {
+              isInsideWorkTree: () => Effect.succeed(true),
+            },
             gitManager: {
               invalidateLocalStatus: () => Effect.void,
               invalidateRemoteStatus: () => Effect.void,
@@ -2809,9 +2926,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 },
                     }),
@@ -2983,6 +3100,34 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("routes websocket rpc orchestration shell snapshot errors", () =>
+    Effect.gen(function* () {
+      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 = {
@@ -3475,9 +3620,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         const refreshStatus = vi.fn((_: string) =>
           Effect.succeed({
             isRepo: true,
-            hasOriginRemote: true,
-            isDefaultBranch: false,
-            branch: "t3code/bootstrap-branch",
+            hasPrimaryRemote: true,
+            isDefaultRef: false,
+            refName: "t3code/bootstrap-refName",
             hasWorkingTreeChanges: false,
             workingTree: {
               files: [],
@@ -3490,13 +3635,14 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             pr: null,
           }),
         );
-        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]) =>
@@ -3511,10 +3657,10 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
         yield* buildAppUnderTest({
           layers: {
-            gitCore: {
+            gitVcsDriver: {
               createWorktree,
             },
-            gitStatusBroadcaster: {
+            vcsStatusBroadcaster: {
               refreshStatus,
             },
             orchestrationEngine: {
@@ -3562,7 +3708,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,
               },
@@ -3584,8 +3730,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], {
@@ -3615,13 +3761,14 @@ 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]) =>
@@ -3630,7 +3777,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          gitVcsDriver: {
             createWorktree,
           },
           orchestrationEngine: {
@@ -3678,7 +3825,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,
             },
@@ -3708,13 +3855,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]) =>
@@ -3730,7 +3878,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
 
       yield* buildAppUnderTest({
         layers: {
-          gitCore: {
+          gitVcsDriver: {
             createWorktree,
           },
           orchestrationEngine: {
@@ -3794,7 +3942,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,
             },
@@ -3826,13 +3974,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: {
@@ -3877,7 +4026,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,
             },
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 9a8885ffc0f..939b2c8abf8 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -16,28 +16,23 @@ import { OpenLive } from "./open.ts";
 import { layerConfig as SqlitePersistenceLayerLive } from "./persistence/Layers/Sqlite.ts";
 import { ServerLifecycleEventsLive } from "./serverLifecycleEvents.ts";
 import { AnalyticsServiceLayerLive } from "./telemetry/Layers/AnalyticsService.ts";
-import { makeEventNdjsonLogger } from "./provider/Layers/EventNdjsonLogger.ts";
 import { ProviderSessionDirectoryLive } from "./provider/Layers/ProviderSessionDirectory.ts";
 import { ProviderSessionRuntimeRepositoryLive } from "./persistence/Layers/ProviderSessionRuntime.ts";
-import { makeCodexAdapterLive } from "./provider/Layers/CodexAdapter.ts";
-import { makeClaudeAdapterLive } from "./provider/Layers/ClaudeAdapter.ts";
-import { makeCopilotAdapterLive } from "./provider/Layers/CopilotAdapter.ts";
-import { makeCursorAdapterLive } from "./provider/Layers/CursorAdapter.ts";
-import { makeGeminiCliAdapterLive } from "./provider/Layers/GeminiCliAdapter.ts";
-import { makeOpenCodeAdapterLive } from "./provider/Layers/OpenCodeAdapter.ts";
-import { makeAmpAdapterLive } from "./provider/Layers/AmpAdapter.ts";
-import { makeKiloAdapterLive } from "./provider/Layers/KiloAdapter.ts";
 import { ProviderAdapterRegistryLive } from "./provider/Layers/ProviderAdapterRegistry.ts";
-import { makeProviderServiceLive } from "./provider/Layers/ProviderService.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 { GitCoreLive } from "./git/Layers/GitCore.ts";
-import { GitHubCliLive } from "./git/Layers/GitHubCli.ts";
-import { GitStatusBroadcasterLive } from "./git/Layers/GitStatusBroadcaster.ts";
-import { RoutingTextGenerationLive } from "./git/Layers/RoutingTextGeneration.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 { GitManagerLive } from "./git/Layers/GitManager.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";
@@ -53,6 +48,15 @@ import { RepositoryIdentityResolverLive } from "./project/Layers/RepositoryIdent
 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";
@@ -81,6 +85,7 @@ import {
   orchestrationSnapshotRouteLayer,
 } from "./orchestration/http.ts";
 import { NetService } from "@t3tools/shared/Net";
+import { disableTailscaleServe, ensureTailscaleServe } from "@t3tools/tailscale";
 
 const PtyAdapterLive = Layer.unwrap(
   Effect.gen(function* () {
@@ -139,80 +144,76 @@ const ReactorLayerLive = Layer.empty.pipe(
   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 codexAdapterLayer = makeCodexAdapterLive(
-      nativeEventLogger ? { nativeEventLogger } : undefined,
-    );
-    const claudeAdapterLayer = makeClaudeAdapterLive(
-      nativeEventLogger ? { nativeEventLogger } : undefined,
-    );
-    const copilotAdapterLayer = makeCopilotAdapterLive(
-      nativeEventLogger ? { nativeEventLogger } : undefined,
-    );
-    const cursorAdapterLayer = makeCursorAdapterLive(
-      nativeEventLogger ? { nativeEventLogger } : undefined,
-    );
-    const geminiCliAdapterLayer = makeGeminiCliAdapterLive();
-    const openCodeAdapterLayer = makeOpenCodeAdapterLive();
-    const ampAdapterLayer = makeAmpAdapterLive();
-    const kiloAdapterLayer = makeKiloAdapterLive();
-    const adapterRegistryLayer = ProviderAdapterRegistryLive.pipe(
-      Layer.provide(codexAdapterLayer),
-      Layer.provide(claudeAdapterLayer),
-      Layer.provide(copilotAdapterLayer),
-      Layer.provide(cursorAdapterLayer),
-      Layer.provide(geminiCliAdapterLayer),
-      Layer.provide(openCodeAdapterLayer),
-      Layer.provide(ampAdapterLayer),
-      Layer.provide(kiloAdapterLayer),
-      Layer.provideMerge(ProviderSessionDirectoryLayerLive),
-    );
-    return makeProviderServiceLive(
-      canonicalEventLogger ? { canonicalEventLogger } : undefined,
-    ).pipe(
-      Layer.provide(adapterRegistryLayer),
-      Layer.provideMerge(ProviderSessionDirectoryLayerLive),
-    );
-  }),
+// `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(GitCoreLive),
+  Layer.provideMerge(VcsDriverRegistryLayerLive),
 );
 
 const WorkspaceFileSystemLayerLive = WorkspaceFileSystemLive.pipe(
@@ -236,22 +237,44 @@ const ProviderRuntimeLayerLive = ProviderSessionReaperLive.pipe(
   Layer.provideMerge(OrchestrationLayerLive),
 );
 
-const RuntimeDependenciesLive = ReactorLayerLive.pipe(
+const RuntimeCoreDependenciesLive = ReactorLayerLive.pipe(
   // Core Services
   Layer.provideMerge(CheckpointingLayerLive),
+  Layer.provideMerge(SourceControlProviderRegistryLayerLive),
   Layer.provideMerge(GitLayerLive),
+  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(AnalyticsServiceLayerLive),
   Layer.provideMerge(OpenLive),
@@ -318,6 +341,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, {
@@ -325,6 +399,7 @@ export const makeServerLayer = Layer.unwrap(
       }),
       httpListeningLayer,
       runtimeStateLayer,
+      tailscaleServeLayer,
     );
 
     return serverApplicationLayer.pipe(
@@ -332,6 +407,7 @@ export const makeServerLayer = Layer.unwrap(
       Layer.provideMerge(HttpServerLive),
       Layer.provide(ObservabilityLive),
       Layer.provideMerge(FetchHttpClient.layer),
+      Layer.provideMerge(VcsProcess.layer),
       Layer.provideMerge(PlatformServicesLive),
     );
   }),
diff --git a/apps/server/src/serverRuntimeStartup.test.ts b/apps/server/src/serverRuntimeStartup.test.ts
index 836b71c7eb4..91b4b215c10 100644
--- a/apps/server/src/serverRuntimeStartup.test.ts
+++ b/apps/server/src/serverRuntimeStartup.test.ts
@@ -1,5 +1,5 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { DEFAULT_MODEL_BY_PROVIDER, ProjectId, ThreadId } from "@t3tools/contracts";
+import { DEFAULT_MODEL, ProjectId, ProviderInstanceId, ThreadId } from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
 import { Deferred, Effect, Fiber, Option, Ref, Stream } from "effect";
 
@@ -21,8 +21,8 @@ import {
 
 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,
   });
 });
 
diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.ts
index 99728f681f4..1f164860a6f 100644
--- a/apps/server/src/serverRuntimeStartup.ts
+++ b/apps/server/src/serverRuntimeStartup.ts
@@ -1,9 +1,10 @@
 import {
   CommandId,
-  DEFAULT_MODEL_BY_PROVIDER,
+  DEFAULT_MODEL,
   DEFAULT_PROVIDER_INTERACTION_MODE,
   type ModelSelection,
   ProjectId,
+  ProviderInstanceId,
   ThreadId,
 } from "@t3tools/contracts";
 import {
@@ -154,8 +155,8 @@ export const launchStartupHeartbeat = recordStartupHeartbeat.pipe(
 );
 
 export const getAutoBootstrapDefaultModelSelection = (): ModelSelection => ({
-  provider: "codex",
-  model: DEFAULT_MODEL_BY_PROVIDER.codex,
+  instanceId: ProviderInstanceId.make("codex"),
+  model: DEFAULT_MODEL,
 });
 
 export const resolveWelcomeBase = Effect.gen(function* () {
diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts
index f9e0542f9a6..f11c5bf4519 100644
--- a/apps/server/src/serverSettings.test.ts
+++ b/apps/server/src/serverSettings.test.ts
@@ -1,5 +1,12 @@
 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.ts";
@@ -24,44 +31,44 @@ it.layer(NodeServices.layer)("server settings", (it) => {
       assert.deepEqual(decodePatch({ providers: { codex: { binaryPath: "/tmp/codex" } } }), {
         providers: { codex: { binaryPath: "/tmp/codex" } },
       });
-      assert.deepEqual(
-        decodePatch({
-          providers: {
-            copilot: {
-              binaryPath: "/tmp/copilot",
-              configDir: "/tmp/copilot-config",
-            },
-          },
-        }),
-        {
-          providers: {
-            copilot: {
-              binaryPath: "/tmp/copilot",
-              configDir: "/tmp/copilot-config",
-            },
-          },
-        },
-      );
 
       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;
@@ -78,12 +85,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!,
         },
       });
 
@@ -94,9 +105,7 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           },
         },
         textGenerationModelSelection: {
-          options: {
-            fastMode: false,
-          },
+          options: [{ id: "fastMode", value: false }],
         },
       });
 
@@ -104,22 +113,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())),
   );
 
@@ -130,11 +144,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!,
         },
       });
 
@@ -142,21 +158,104 @@ 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())),
   );
 
@@ -166,29 +265,70 @@ it.layer(NodeServices.layer)("server settings", (it) => {
 
       yield* serverSettings.updateSettings({
         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!,
         },
       });
 
       const next = yield* serverSettings.updateSettings({
         textGenerationModelSelection: {
-          provider: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.provider,
+          instanceId: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.instanceId,
           model: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.model,
         },
       });
 
       assert.deepEqual(next.textGenerationModelSelection, {
-        provider: DEFAULT_SERVER_SETTINGS.textGenerationModelSelection.provider,
+        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())),
+  );
+
   it.effect("trims provider path settings when updates are applied", () =>
     Effect.gen(function* () {
       const serverSettings = yield* ServerSettingsService;
@@ -202,14 +342,10 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           claudeAgent: {
             binaryPath: "  /opt/homebrew/bin/claude  ",
           },
-          copilot: {
-            binaryPath: "  /opt/homebrew/bin/copilot  ",
-            configDir: "  /Users/julius/.config/copilot  ",
-          },
           opencode: {
             binaryPath: "  /opt/homebrew/bin/opencode  ",
-            serverUrl: "  http://localhost:1234  ",
-            serverPassword: "  s3cret  ",
+            serverUrl: "  http://127.0.0.1:4096  ",
+            serverPassword: "  secret-password  ",
           },
         },
       });
@@ -218,25 +354,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.copilot, {
-        enabled: true,
-        binaryPath: "/opt/homebrew/bin/copilot",
-        configDir: "/Users/julius/.config/copilot",
-        customModels: [],
-      });
       assert.deepEqual(next.providers.opencode, {
         enabled: true,
         binaryPath: "/opt/homebrew/bin/opencode",
-        serverUrl: "http://localhost:1234",
-        serverPassword: "s3cret",
+        serverUrl: "http://127.0.0.1:4096",
+        serverPassword: "secret-password",
         customModels: [],
       });
     }).pipe(Effect.provide(makeServerSettingsLayer())),
@@ -298,7 +430,8 @@ it.layer(NodeServices.layer)("server settings", (it) => {
             binaryPath: "/opt/homebrew/bin/codex",
           },
           opencode: {
-            serverUrl: "http://localhost:1234",
+            serverUrl: "http://127.0.0.1:4096",
+            serverPassword: "secret-password",
           },
         },
       });
@@ -317,10 +450,74 @@ it.layer(NodeServices.layer)("server settings", (it) => {
             binaryPath: "/opt/homebrew/bin/codex",
           },
           opencode: {
-            serverUrl: "http://localhost:1234",
+            serverUrl: "http://127.0.0.1:4096",
+            serverPassword: "secret-password",
           },
         },
       });
     }).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");
+      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 acda7be294f..2b9d8a52951 100644
--- a/apps/server/src/serverSettings.ts
+++ b/apps/server/src/serverSettings.ts
@@ -11,10 +11,15 @@
  * @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,
@@ -44,6 +49,47 @@ import { ServerConfig } from "./config.ts";
 import { type DeepPartial, deepMerge } from "@t3tools/shared/Struct";
 import { 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 textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+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. */
@@ -106,16 +152,13 @@ export class ServerSettingsService extends Context.Service<
 
 const ServerSettingsJson = fromLenientJson(ServerSettings);
 
-const PROVIDER_ORDER: readonly ProviderKind[] = [
-  "codex",
-  "claudeAgent",
-  "copilot",
-  "cursor",
-  "opencode",
-  "geminiCli",
-  "amp",
-  "kilo",
-];
+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.
@@ -125,22 +168,36 @@ const PROVIDER_ORDER: readonly ProviderKind[] = [
  */
 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,
   };
 }
 
@@ -185,6 +242,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>();
@@ -242,6 +300,138 @@ const makeServerSettings = Effect.gen(function* () {
 
   const getSettingsFromCache = Cache.get(settingsCache, cacheKey);
 
+  const toSettingsError = (detail: string, cause: unknown) =>
+    new ServerSettingsError({
+      settingsPath,
+      detail,
+      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 = (settings: ServerSettings) => {
     const sparseSettings = stripDefaultServerSettings(settings, DEFAULT_SERVER_SETTINGS) ?? {};
 
@@ -333,14 +523,19 @@ 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)(
+          const nextPersisted = yield* persistProviderEnvironmentSecrets(
+            current,
             applyServerSettingsPatch(current, patch),
-          ).pipe(
+          );
+          const next = yield* Schema.decodeEffect(ServerSettings)(nextPersisted).pipe(
             Effect.mapError(
               (cause) =>
                 new ServerSettingsError({
@@ -353,13 +548,27 @@ const makeServerSettings = Effect.gen(function* () {
           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..406c9772f34
--- /dev/null
+++ b/apps/server/src/sourceControl/AzureDevOpsCli.test.ts
@@ -0,0 +1,288 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it, afterEach, describe, expect, vi } from "@effect/vitest";
+import { Effect, FileSystem, Layer, Option } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import type { VcsError } from "@t3tools/contracts";
+
+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(
+            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(
+            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(
+            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(
+            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-${Date.now()}.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..375bfc1a54b
--- /dev/null
+++ b/apps/server/src/sourceControl/AzureDevOpsCli.ts
@@ -0,0 +1,429 @@
+import { Context, Effect, Layer, Result, Schema, SchemaIssue } from "effect";
+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..c46bc0ee7fc
--- /dev/null
+++ b/apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.test.ts
@@ -0,0 +1,91 @@
+import { assert, it } from "@effect/vitest";
+import { Effect, Layer, Option } from "effect";
+
+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..cd4162a934e
--- /dev/null
+++ b/apps/server/src/sourceControl/AzureDevOpsSourceControlProvider.ts
@@ -0,0 +1,144 @@
+import { Effect, Layer } from "effect";
+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 && 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 ? { 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 ? { source } : {}),
+          ...(input.target ? { 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 ? { 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..5542ea40921
--- /dev/null
+++ b/apps/server/src/sourceControl/BitbucketApi.test.ts
@@ -0,0 +1,513 @@
+import { assert, it, vi } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { ConfigProvider, DateTime, Effect, FileSystem, Layer, Option } from "effect";
+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: () => Response.json(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("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);
+    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);
+    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..4f795e864a1
--- /dev/null
+++ b/apps/server/src/sourceControl/BitbucketApi.ts
@@ -0,0 +1,703 @@
+import { Config, Context, Effect, FileSystem, Layer, Option, Schema } from "effect";
+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 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 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: Schema.Schema.Type<typeof RawBitbucketRepositorySchema>,
+): 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 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 Schema.is(BitbucketApiError)(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 getRepository = (input: {
+    readonly cwd: string;
+    readonly context?: SourceControlProvider.SourceControlProviderContext;
+    readonly repository?: string;
+  }) =>
+    resolveRepository(input).pipe(
+      Effect.flatMap((repository) =>
+        executeJson(
+          "getRepository",
+          HttpClientRequest.get(
+            apiUrl(
+              `/repositories/${encodeURIComponent(repository.workspace)}/${encodeURIComponent(repository.repoSlug)}`,
+            ),
+          ),
+          RawBitbucketRepositorySchema,
+        ),
+      ),
+    );
+
+  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) =>
+      getRepository(input).pipe(Effect.map((repository) => repository.mainbranch?.name ?? null)),
+    // 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..4bf658f5685
--- /dev/null
+++ b/apps/server/src/sourceControl/BitbucketSourceControlProvider.test.ts
@@ -0,0 +1,126 @@
+import { assert, it } from "@effect/vitest";
+import { Effect, Layer, Option } from "effect";
+
+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..ede80e921dc
--- /dev/null
+++ b/apps/server/src/sourceControl/BitbucketSourceControlProvider.ts
@@ -0,0 +1,126 @@
+import { Effect, Layer, Option } from "effect";
+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..778e0c4962e
--- /dev/null
+++ b/apps/server/src/sourceControl/GitHubCli.test.ts
@@ -0,0 +1,291 @@
+import { assert, it, afterEach, describe, expect, vi } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+import { VcsProcessExitError, type VcsError } 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(
+            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(
+            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(
+            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(
+            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..fe83d41ef43
--- /dev/null
+++ b/apps/server/src/sourceControl/GitHubCli.ts
@@ -0,0 +1,370 @@
+import { Context, Effect, Layer, Result, Schema, SchemaIssue } from "effect";
+
+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..3c4ad5ac473
--- /dev/null
+++ b/apps/server/src/sourceControl/GitHubSourceControlProvider.test.ts
@@ -0,0 +1,156 @@
+import { assert, it } from "@effect/vitest";
+import { DateTime, Effect, Layer, Option } from "effect";
+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..7dba4893697
--- /dev/null
+++ b/apps/server/src/sourceControl/GitHubSourceControlProvider.ts
@@ -0,0 +1,196 @@
+import { Effect, Layer, Option, Result, Schema } from "effect";
+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";
+
+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) =>
+            Schema.is(SourceControlProviderError)(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..5c7e978d857
--- /dev/null
+++ b/apps/server/src/sourceControl/GitLabCli.test.ts
@@ -0,0 +1,326 @@
+import { assert, it, afterEach, expect, vi } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+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(
+            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(
+            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(
+            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(JSON.stringify({ id: 1234 }))))
+        .mockReturnValueOnce(
+          Effect.succeed(
+            processOutput(
+              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..c4485bb09b7
--- /dev/null
+++ b/apps/server/src/sourceControl/GitLabCli.ts
@@ -0,0 +1,442 @@
+import { Context, Effect, Layer, Option, Result, Schema, SchemaIssue, type DateTime } from "effect";
+
+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..930c1c018f5
--- /dev/null
+++ b/apps/server/src/sourceControl/GitLabSourceControlProvider.test.ts
@@ -0,0 +1,107 @@
+import { assert, it } from "@effect/vitest";
+import { Effect, Layer, Option } from "effect";
+
+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..5b0538babd8
--- /dev/null
+++ b/apps/server/src/sourceControl/GitLabSourceControlProvider.ts
@@ -0,0 +1,144 @@
+import { Effect, Layer, Option } from "effect";
+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..ce41265d336
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlDiscovery.test.ts
@@ -0,0 +1,257 @@
+import { assert, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Effect, Layer, Option } from "effect";
+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..4a44d35087a
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlDiscovery.ts
@@ -0,0 +1,144 @@
+import {
+  type SourceControlDiscoveryResult,
+  type VcsDiscoveryItem,
+  type VcsDriverKind,
+} from "@t3tools/contracts";
+import { Context, Effect, Layer, Option } from "effect";
+
+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,
+          truncateOutputAtMaxBytes: 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..12f89caf77e
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlProvider.ts
@@ -0,0 +1,101 @@
+import { Context, Effect } from "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..87c0c4756a4
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlProviderDiscovery.ts
@@ -0,0 +1,237 @@
+import type {
+  SourceControlProviderAuth,
+  SourceControlProviderDiscoveryItem,
+  SourceControlProviderKind,
+} from "@t3tools/contracts";
+import { Effect, Option } from "effect";
+
+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,
+      truncateOutputAtMaxBytes: 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,
+          truncateOutputAtMaxBytes: 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..395bd9b5e87
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlProviderRegistry.test.ts
@@ -0,0 +1,145 @@
+import { assert, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { DateTime, Effect, Layer, Option } from "effect";
+
+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..c8b79f21651
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlProviderRegistry.ts
@@ -0,0 +1,251 @@
+import { Cache, Context, Duration, Effect, Exit, Layer } from "effect";
+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..5280ee0e59c
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
@@ -0,0 +1,318 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import { Effect, FileSystem, Layer } from "effect";
+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..1bf71ac12dc
--- /dev/null
+++ b/apps/server/src/sourceControl/SourceControlRepositoryService.ts
@@ -0,0 +1,320 @@
+import * as NodeOS from "node:os";
+import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
+
+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";
+
+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) =>
+    Schema.is(SourceControlRepositoryError)(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* Effect.fail(
+          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* Effect.fail(
+            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* Effect.fail(
+        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..48c7a836110
--- /dev/null
+++ b/apps/server/src/sourceControl/azureDevOpsPullRequests.ts
@@ -0,0 +1,106 @@
+import { Cause, DateTime, Exit, Option, Result, Schema } from "effect";
+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..5313eaba974
--- /dev/null
+++ b/apps/server/src/sourceControl/bitbucketPullRequests.ts
@@ -0,0 +1,104 @@
+import { DateTime, Option, Schema } from "effect";
+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 93%
rename from apps/server/src/git/githubPullRequests.ts
rename to apps/server/src/sourceControl/gitHubPullRequests.ts
index d137a46d6fa..f0804dda8c6 100644
--- a/apps/server/src/git/githubPullRequests.ts
+++ b/apps/server/src/sourceControl/gitHubPullRequests.ts
@@ -1,4 +1,4 @@
-import { Cause, Exit, Result, Schema } from "effect";
+import { Cause, DateTime, Exit, Option, Result, Schema } from "effect";
 import { PositiveInt, TrimmedNonEmptyString } from "@t3tools/contracts";
 import { decodeJsonResult, formatSchemaError } from "@t3tools/shared/schemaJson";
 
@@ -9,7 +9,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 +23,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 +80,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..d8245d3249a
--- /dev/null
+++ b/apps/server/src/sourceControl/gitLabMergeRequests.ts
@@ -0,0 +1,148 @@
+import { Cause, DateTime, Exit, Option, Result, Schema } from "effect";
+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/textGeneration/AmpTextGeneration.ts b/apps/server/src/textGeneration/AmpTextGeneration.ts
new file mode 100644
index 00000000000..f21bfac0052
--- /dev/null
+++ b/apps/server/src/textGeneration/AmpTextGeneration.ts
@@ -0,0 +1,54 @@
+/**
+ * AmpTextGeneration — Graceful "not supported" text-generation shape for Amp.
+ *
+ * Amp's CLI does not currently expose a structured-output mode that maps
+ * cleanly onto our `TextGenerationShape` contract (commit messages, PR
+ * titles, branch names, thread titles). Rather than block the driver from
+ * registering, this factory returns an implementation that fails every
+ * operation with a clear `TextGenerationError`. The user can still pick a
+ * different instance (Codex, Claude, OpenCode, …) for text generation
+ * features, and the Amp instance remains usable for chat-style sessions.
+ *
+ * @module AmpTextGeneration
+ */
+import { Effect } from "effect";
+
+import type { GenericProviderSettings } from "@t3tools/contracts";
+import { TextGenerationError } from "@t3tools/contracts";
+
+import { type TextGenerationShape } from "./TextGeneration.ts";
+
+const NOT_SUPPORTED_DETAIL =
+  "Amp does not expose a structured text-generation API. Use a different provider instance for commit/PR/branch/title generation.";
+
+const fail = (
+  operation:
+    | "generateCommitMessage"
+    | "generatePrContent"
+    | "generateBranchName"
+    | "generateThreadTitle",
+) => Effect.fail(new TextGenerationError({ operation, detail: NOT_SUPPORTED_DETAIL }));
+
+export const makeAmpTextGeneration = Effect.fn("makeAmpTextGeneration")(function* (
+  _ampSettings: GenericProviderSettings,
+  _environment: NodeJS.ProcessEnv = process.env,
+) {
+  const generateCommitMessage: TextGenerationShape["generateCommitMessage"] = () =>
+    fail("generateCommitMessage");
+
+  const generatePrContent: TextGenerationShape["generatePrContent"] = () =>
+    fail("generatePrContent");
+
+  const generateBranchName: TextGenerationShape["generateBranchName"] = () =>
+    fail("generateBranchName");
+
+  const generateThreadTitle: TextGenerationShape["generateThreadTitle"] = () =>
+    fail("generateThreadTitle");
+
+  return {
+    generateCommitMessage,
+    generatePrContent,
+    generateBranchName,
+    generateThreadTitle,
+  } satisfies TextGenerationShape;
+});
diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
new file mode 100644
index 00000000000..19cff6f0344
--- /dev/null
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
@@ -0,0 +1,339 @@
+import { ClaudeSettings, ProviderInstanceId } from "@t3tools/contracts";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import { Effect, FileSystem, Layer, Path, Schema } from "effect";
+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 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 = Schema.decodeSync(ClaudeSettings)(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(
+        {
+          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 77%
rename from apps/server/src/git/Layers/ClaudeTextGeneration.ts
rename to apps/server/src/textGeneration/ClaudeTextGeneration.ts
index 97e18c3e789..2f0cbc509b6 100644
--- a/apps/server/src/git/Layers/ClaudeTextGeneration.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
@@ -7,31 +7,38 @@
  *
  * @module ClaudeTextGeneration
  */
-import { Effect, Layer, Option, Schema, Stream } from "effect";
+import { Effect, Option, Schema, Stream } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
-import { ClaudeModelSelection } from "@t3tools/contracts";
+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 { resolveClaudeApiModelId } from "../../provider/Layers/ClaudeProvider.ts";
-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 +50,12 @@ const ClaudeOutputEnvelope = Schema.Struct({
   structured_output: Schema.Unknown,
 });
 
-const makeClaudeTextGeneration = Effect.gen(function* () {
+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,
@@ -81,28 +91,32 @@ 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 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 runClaudeCommand = Effect.fn("runClaudeJson.runClaudeCommand")(function* () {
       const command = ChildProcess.make(
-        claudeSettings?.binaryPath || "claude",
+        claudeSettings.binaryPath || "claude",
         [
           "-p",
           "--output-format",
@@ -111,11 +125,12 @@ const makeClaudeTextGeneration = Effect.gen(function* () {
           jsonSchemaStr,
           "--model",
           resolveClaudeApiModelId(modelSelection),
-          ...(normalizedOptions?.effort ? ["--effort", normalizedOptions.effort] : []),
+          ...(cliEffort ? ["--effort", cliEffort] : []),
           ...(Object.keys(settings).length > 0 ? ["--settings", JSON.stringify(settings)] : []),
           "--dangerously-skip-permissions",
         ],
         {
+          env: claudeEnvironment,
           cwd,
           shell: process.platform === "win32",
           stdin: {
@@ -216,13 +231,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 +259,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 +281,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 +302,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 +322,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 51%
rename from apps/server/src/git/Layers/CodexTextGeneration.test.ts
rename to apps/server/src/textGeneration/CodexTextGeneration.test.ts
index a07505f025c..07123e921b1 100644
--- a/apps/server/src/git/Layers/CodexTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/CodexTextGeneration.test.ts
@@ -1,29 +1,24 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
-import { Effect, FileSystem, Layer, Path, Result } from "effect";
+import { Effect, FileSystem, Layer, Path, Result, Schema } from "effect";
+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 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: {
@@ -161,39 +156,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 = Schema.decodeSync(CodexSettings)({ 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 +179,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 +210,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 +233,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 +254,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 +279,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 +306,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 +327,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 +347,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 +367,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 +388,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 +410,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-${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 generated = yield* textGeneration.generateBranchName({
             modelSelection: DEFAULT_TEST_MODEL_SELECTION,
             cwd: process.cwd(),
             message: "Fix layout bug from screenshot.",
@@ -515,24 +433,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 +448,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-${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 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-${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 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 +567,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 79%
rename from apps/server/src/git/Layers/CodexTextGeneration.ts
rename to apps/server/src/textGeneration/CodexTextGeneration.ts
index 8f15bfa1868..786a0be4c49 100644
--- a/apps/server/src/git/Layers/CodexTextGeneration.ts
+++ b/apps/server/src/textGeneration/CodexTextGeneration.ts
@@ -1,44 +1,50 @@
-import { randomUUID } from "node:crypto";
-
-import { Effect, FileSystem, Layer, Option, Path, Schema, Scope, Stream } from "effect";
+import { Effect, FileSystem, Option, Path, Random, Schema, Scope, Stream } from "effect";
 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 { expandHomePath } from "../../pathExpansion.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 { ServerSettingsService } from "../../serverSettings.ts";
+} 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* () {
+/**
+ * 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>;
@@ -64,21 +70,23 @@ 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> =>
@@ -139,7 +147,7 @@ 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(
       operation,
@@ -148,16 +156,12 @@ const makeCodexTextGeneration = Effect.gen(function* () {
     );
     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 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",
@@ -168,7 +172,9 @@ const makeCodexTextGeneration = Effect.gen(function* () {
           modelSelection.model,
           "--config",
           `model_reasoning_effort="${reasoningEffort}"`,
-          ...(modelSelection.options?.fastMode ? ["--config", `service_tier="fast"`] : []),
+          ...(getModelSelectionBooleanOptionValue(modelSelection, "fastMode") === true
+            ? ["--config", `service_tier="fast"`]
+            : []),
           "--output-schema",
           schemaPath,
           "--output-last-message",
@@ -178,10 +184,8 @@ const makeCodexTextGeneration = Effect.gen(function* () {
         ],
         {
           env: {
-            ...process.env,
-            ...(codexSettings?.homePath
-              ? { CODEX_HOME: expandHomePath(codexSettings.homePath) }
-              : {}),
+            ...environment,
+            ...(codexConfig.homePath ? { CODEX_HOME: expandHomePath(codexConfig.homePath) } : {}),
           },
           cwd,
           shell: process.platform === "win32",
@@ -281,13 +285,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,
@@ -316,13 +313,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,
@@ -349,13 +339,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,
@@ -382,13 +365,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,
@@ -410,5 +386,3 @@ const makeCodexTextGeneration = Effect.gen(function* () {
     generateThreadTitle,
   } satisfies TextGenerationShape;
 });
-
-export const CodexTextGenerationLive = Layer.effect(TextGeneration, makeCodexTextGeneration);
diff --git a/apps/server/src/textGeneration/CopilotTextGeneration.ts b/apps/server/src/textGeneration/CopilotTextGeneration.ts
new file mode 100644
index 00000000000..30911721431
--- /dev/null
+++ b/apps/server/src/textGeneration/CopilotTextGeneration.ts
@@ -0,0 +1,60 @@
+/**
+ * CopilotTextGeneration — `TextGenerationShape` factory for the GitHub
+ * Copilot provider.
+ *
+ * The Copilot SDK does not expose a straightforward "one-shot prompt with
+ * structured JSON output" command analogous to `claude -p --output-format
+ * json` or `codex exec`. Spinning up a full session per text-generation
+ * call (commit messages, PR titles, etc.) would be both expensive and a
+ * poor product experience because every invocation would run agentic tool
+ * approvals, slash-command discovery, etc.
+ *
+ * Until/unless the SDK ships a dedicated structured-prompt entrypoint,
+ * this factory exposes a `TextGenerationShape` that fails gracefully on
+ * every operation with a stable, user-actionable error message. Callers
+ * (`SessionTextGeneration` etc.) already fall back to other providers
+ * when one fails, so this keeps Copilot a valid `ProviderInstance` member
+ * without claiming a capability it cannot honour.
+ *
+ * @module CopilotTextGeneration
+ */
+import { Effect } from "effect";
+
+import { TextGenerationError } from "@t3tools/contracts";
+
+import { type TextGenerationShape } from "./TextGeneration.ts";
+import type { CopilotSettings } from "../provider/Drivers/CopilotSettings.ts";
+
+const UNSUPPORTED_DETAIL =
+  "GitHub Copilot does not support headless text generation. Pick a different provider for commit / PR / branch / thread title generation.";
+
+export const makeCopilotTextGeneration = Effect.fn("makeCopilotTextGeneration")(function* (
+  _copilotSettings: CopilotSettings,
+  _environment: NodeJS.ProcessEnv = process.env,
+) {
+  const fail = <Op extends "generateCommitMessage" | "generatePrContent" | "generateBranchName" | "generateThreadTitle">(
+    operation: Op,
+  ) =>
+    Effect.fail(
+      new TextGenerationError({
+        operation,
+        detail: UNSUPPORTED_DETAIL,
+      }),
+    );
+
+  const generateCommitMessage: TextGenerationShape["generateCommitMessage"] = () =>
+    fail("generateCommitMessage");
+  const generatePrContent: TextGenerationShape["generatePrContent"] = () =>
+    fail("generatePrContent");
+  const generateBranchName: TextGenerationShape["generateBranchName"] = () =>
+    fail("generateBranchName");
+  const generateThreadTitle: TextGenerationShape["generateThreadTitle"] = () =>
+    fail("generateThreadTitle");
+
+  return {
+    generateCommitMessage,
+    generatePrContent,
+    generateBranchName,
+    generateThreadTitle,
+  } satisfies TextGenerationShape;
+});
diff --git a/apps/server/src/textGeneration/CursorTextGeneration.test.ts b/apps/server/src/textGeneration/CursorTextGeneration.test.ts
new file mode 100644
index 00000000000..0de135c8465
--- /dev/null
+++ b/apps/server/src/textGeneration/CursorTextGeneration.test.ts
@@ -0,0 +1,264 @@
+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 { Effect, Layer, Schema } from "effect";
+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 __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 = Schema.decodeSync(CursorSettings)({ binaryPath: agentPath });
+    const textGeneration = yield* makeCursorTextGeneration(config);
+    return yield* effectFn(textGeneration);
+  }).pipe(Effect.scoped);
+}
+
+function waitForFileContent(path: string): Effect.Effect<string> {
+  return Effect.promise(async () => {
+    const deadline = Date.now() + 5_000;
+    for (;;) {
+      try {
+        return readFileSync(path, "utf8");
+      } catch (error) {
+        if (Date.now() >= deadline) {
+          throw error instanceof Error ? error : new Error(String(error));
+        }
+      }
+      await new Promise((resolve) => setTimeout(resolve, 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/git/Layers/CursorTextGeneration.ts b/apps/server/src/textGeneration/CursorTextGeneration.ts
similarity index 81%
rename from apps/server/src/git/Layers/CursorTextGeneration.ts
rename to apps/server/src/textGeneration/CursorTextGeneration.ts
index 24f066059c7..1cde82d61b6 100644
--- a/apps/server/src/git/Layers/CursorTextGeneration.ts
+++ b/apps/server/src/textGeneration/CursorTextGeneration.ts
@@ -1,32 +1,27 @@
-import { Effect, Layer, Option, Ref, Schema } from "effect";
+import { Effect, Option, Ref, Schema } from "effect";
 import { ChildProcessSpawner } from "effect/unstable/process";
 
-import { CursorModelSelection } from "@t3tools/contracts";
+import { type CursorSettings, type ModelSelection } from "@t3tools/contracts";
 import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
 
 import { TextGenerationError } from "@t3tools/contracts";
-import {
-  type ThreadTitleGenerationResult,
-  type TextGenerationShape,
-  TextGeneration,
-} from "../Services/TextGeneration.ts";
+import { type ThreadTitleGenerationResult, type TextGenerationShape } from "./TextGeneration.ts";
 import {
   buildBranchNamePrompt,
   buildCommitMessagePrompt,
   buildPrContentPrompt,
   buildThreadTitlePrompt,
-} from "../Prompts.ts";
+} from "./TextGenerationPrompts.ts";
 import {
   extractJsonObject,
   sanitizeCommitSubject,
   sanitizePrTitle,
   sanitizeThreadTitle,
-} from "../Utils.ts";
+} from "./TextGenerationUtils.ts";
 import {
   applyCursorAcpModelSelection,
   makeCursorAcpRuntime,
-} from "../../provider/acp/CursorAcpSupport.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+} from "../provider/acp/CursorAcpSupport.ts";
 
 const CURSOR_TIMEOUT_MS = 180_000;
 
@@ -55,9 +50,15 @@ function isTextGenerationError(error: unknown): error is TextGenerationError {
   );
 }
 
-const makeCursorTextGeneration = Effect.gen(function* () {
+/**
+ * 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 serverSettingsService = yield* Effect.service(ServerSettingsService);
 
   const runCursorJson = <S extends Schema.Top>({
     operation,
@@ -74,17 +75,13 @@ const makeCursorTextGeneration = Effect.gen(function* () {
     cwd: string;
     prompt: string;
     outputSchemaJson: S;
-    modelSelection: CursorModelSelection;
+    modelSelection: ModelSelection;
   }): Effect.Effect<S["Type"], TextGenerationError, S["DecodingServices"]> =>
     Effect.gen(function* () {
-      const cursorSettings = yield* Effect.map(
-        serverSettingsService.getSettings,
-        (settings) => settings.providers.cursor,
-      ).pipe(Effect.catch(() => Effect.undefined));
-
       const outputRef = yield* Ref.make("");
       const runtime = yield* makeCursorAcpRuntime({
         cursorSettings,
+        environment,
         childProcessSpawner: commandSpawner,
         cwd,
         clientInfo: { name: "t3-code-git-text", version: "0.0.0" },
@@ -108,7 +105,7 @@ const makeCursorTextGeneration = Effect.gen(function* () {
         yield* applyCursorAcpModelSelection({
           runtime,
           model: modelSelection.model,
-          modelOptions: modelSelection.options,
+          selections: modelSelection.options,
           mapError: ({ cause, configId, step }) =>
             mapCursorAcpError(
               operation,
@@ -186,13 +183,6 @@ const makeCursorTextGeneration = Effect.gen(function* () {
       includeBranch: input.includeBranch === true,
     });
 
-    if (input.modelSelection.provider !== "cursor") {
-      return yield* new TextGenerationError({
-        operation: "generateCommitMessage",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runCursorJson({
       operation: "generateCommitMessage",
       cwd: input.cwd,
@@ -221,13 +211,6 @@ const makeCursorTextGeneration = Effect.gen(function* () {
       diffPatch: input.diffPatch,
     });
 
-    if (input.modelSelection.provider !== "cursor") {
-      return yield* new TextGenerationError({
-        operation: "generatePrContent",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runCursorJson({
       operation: "generatePrContent",
       cwd: input.cwd,
@@ -250,13 +233,6 @@ const makeCursorTextGeneration = Effect.gen(function* () {
       attachments: input.attachments,
     });
 
-    if (input.modelSelection.provider !== "cursor") {
-      return yield* new TextGenerationError({
-        operation: "generateBranchName",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runCursorJson({
       operation: "generateBranchName",
       cwd: input.cwd,
@@ -278,13 +254,6 @@ const makeCursorTextGeneration = Effect.gen(function* () {
       attachments: input.attachments,
     });
 
-    if (input.modelSelection.provider !== "cursor") {
-      return yield* new TextGenerationError({
-        operation: "generateThreadTitle",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const generated = yield* runCursorJson({
       operation: "generateThreadTitle",
       cwd: input.cwd,
@@ -305,5 +274,3 @@ const makeCursorTextGeneration = Effect.gen(function* () {
     generateThreadTitle,
   } satisfies TextGenerationShape;
 });
-
-export const CursorTextGenerationLive = Layer.effect(TextGeneration, makeCursorTextGeneration);
diff --git a/apps/server/src/textGeneration/GeminiCliTextGeneration.ts b/apps/server/src/textGeneration/GeminiCliTextGeneration.ts
new file mode 100644
index 00000000000..aa009414e29
--- /dev/null
+++ b/apps/server/src/textGeneration/GeminiCliTextGeneration.ts
@@ -0,0 +1,66 @@
+/**
+ * GeminiCliTextGeneration — `TextGenerationShape` factory for the Gemini CLI
+ * provider.
+ *
+ * Earlier revisions invoked `gemini -p <prompt> --approval-mode yolo` inside
+ * the user's repository to coerce structured JSON output. That gave a
+ * commit/PR/branch/title generation request the same trust posture as a
+ * full agentic session — capable of executing arbitrary tool calls in the
+ * workspace without user approval. The Gemini CLI does not expose a
+ * non-interactive mode that disables tool execution outright (the only
+ * non-interactive approval mode is `yolo`), so the safe option is to not
+ * run it at all from text-generation paths.
+ *
+ * This factory keeps Gemini CLI a valid `ProviderInstance` member by
+ * returning a graceful "not supported" failure on every operation. Callers
+ * (`SessionTextGeneration` etc.) already fall back to other providers when
+ * one fails, so picking Gemini for chat/sessions still works — only the
+ * automated text-generation helpers redirect users to a different provider.
+ *
+ * @module GeminiCliTextGeneration
+ */
+import { Effect } from "effect";
+
+import { type GenericProviderSettings, TextGenerationError } from "@t3tools/contracts";
+
+import { type TextGenerationShape } from "./TextGeneration.ts";
+
+const UNSUPPORTED_DETAIL =
+  "Gemini CLI is not supported for headless text generation (the only non-interactive Gemini mode auto-approves tool calls in the workspace). Pick a different provider for commit / PR / branch / thread title generation.";
+
+export const makeGeminiCliTextGeneration = Effect.fn("makeGeminiCliTextGeneration")(function* (
+  _config: GenericProviderSettings,
+  _environment: NodeJS.ProcessEnv = process.env,
+) {
+  const fail = <
+    Op extends
+      | "generateCommitMessage"
+      | "generatePrContent"
+      | "generateBranchName"
+      | "generateThreadTitle",
+  >(
+    operation: Op,
+  ) =>
+    Effect.fail(
+      new TextGenerationError({
+        operation,
+        detail: UNSUPPORTED_DETAIL,
+      }),
+    );
+
+  const generateCommitMessage: TextGenerationShape["generateCommitMessage"] = () =>
+    fail("generateCommitMessage");
+  const generatePrContent: TextGenerationShape["generatePrContent"] = () =>
+    fail("generatePrContent");
+  const generateBranchName: TextGenerationShape["generateBranchName"] = () =>
+    fail("generateBranchName");
+  const generateThreadTitle: TextGenerationShape["generateThreadTitle"] = () =>
+    fail("generateThreadTitle");
+
+  return {
+    generateCommitMessage,
+    generatePrContent,
+    generateBranchName,
+    generateThreadTitle,
+  } satisfies TextGenerationShape;
+});
diff --git a/apps/server/src/textGeneration/KiloTextGeneration.ts b/apps/server/src/textGeneration/KiloTextGeneration.ts
new file mode 100644
index 00000000000..fef1da33142
--- /dev/null
+++ b/apps/server/src/textGeneration/KiloTextGeneration.ts
@@ -0,0 +1,302 @@
+/**
+ * KiloTextGeneration — Text generation layer using a per-instance Kilo
+ * server for branch/commit/PR/thread-title generation.
+ *
+ * Kilo's API mirrors OpenCode's, so this driver delegates to a private
+ * `KiloServerManager` (no shared state with the adapter's manager) and
+ * runs `session.prompt`-style requests via the SDK client. Unlike the
+ * OpenCode text-generation driver, Kilo does not yet expose a long-lived
+ * shared server pool: each request currently creates a transient session
+ * on the manager-owned server and the server is released when the
+ * factory's scope finalizer fires (registry shutdown).
+ *
+ * @module KiloTextGeneration
+ */
+import { Effect, Schema } from "effect";
+
+import {
+  TextGenerationError,
+  type ChatAttachment,
+  type ModelSelection,
+} from "@t3tools/contracts";
+import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
+
+import {
+  KiloServerManager,
+} from "../kiloServerManager.ts";
+import { parseKiloModel, readJsonData } from "../kilo/utils.ts";
+import { createClient } from "../kilo/serverLifecycle.ts";
+import type { KiloProviderOptions, SharedServerState } from "../kilo/types.ts";
+import { type TextGenerationShape } from "./TextGeneration.ts";
+import {
+  buildBranchNamePrompt,
+  buildCommitMessagePrompt,
+  buildPrContentPrompt,
+  buildThreadTitlePrompt,
+} from "./TextGenerationPrompts.ts";
+import {
+  extractJsonObject,
+  sanitizeCommitSubject,
+  sanitizePrTitle,
+  sanitizeThreadTitle,
+} from "./TextGenerationUtils.ts";
+import type { KiloSettings } from "../provider/Layers/KiloProvider.ts";
+
+type TextGenerationOperation =
+  | "generateCommitMessage"
+  | "generatePrContent"
+  | "generateBranchName"
+  | "generateThreadTitle";
+
+function getKiloPromptErrorMessage(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 getKiloTextResponse(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();
+}
+
+export const makeKiloTextGeneration = Effect.fn("makeKiloTextGeneration")(function* (
+  kiloSettings: KiloSettings,
+  _environment: NodeJS.ProcessEnv = process.env,
+) {
+  // Per-instance manager: one server process bound to this text-generation
+  // factory's scope. The manager owns the spawned child via its internal
+  // `ensureServer`/`getOrStartServer`, so `stopAll()` actually kills it on
+  // scope close. Concurrent generation calls share the same pending start
+  // because `getOrStartServer` is internally serialized.
+  const manager = new KiloServerManager();
+
+  yield* Effect.acquireRelease(Effect.sync(() => manager), (m) => Effect.sync(() => m.stopAll()));
+
+  const resolveBinaryPath = (): string => kiloSettings.binaryPath.trim() || "kilo";
+
+  const ensureKiloServer = (): Promise<SharedServerState> =>
+    manager.getOrStartServer({ binaryPath: resolveBinaryPath() } as KiloProviderOptions);
+
+  const runKiloJson = Effect.fn("runKiloJson")(function* <S extends Schema.Top>(input: {
+    readonly operation: TextGenerationOperation;
+    readonly cwd: string;
+    readonly prompt: string;
+    readonly outputSchemaJson: S;
+    readonly modelSelection: ModelSelection;
+    readonly attachments?: ReadonlyArray<ChatAttachment> | undefined;
+  }) {
+    const parsed = parseKiloModel(input.modelSelection.model);
+    if (!parsed) {
+      return yield* new TextGenerationError({
+        operation: input.operation,
+        detail: "Kilo model selection must use the 'provider/model' format.",
+      });
+    }
+
+    const rawText = yield* Effect.tryPromise({
+      try: async () => {
+        const shared = await ensureKiloServer();
+        const client = await createClient({
+          baseUrl: shared.baseUrl,
+          directory: input.cwd,
+          responseStyle: "data",
+          throwOnError: true,
+          ...(shared.authHeader
+            ? { headers: { Authorization: shared.authHeader } }
+            : {}),
+        });
+
+        const created = (await readJsonData(
+          client.session.create({ title: `T3 Code ${input.operation}` }),
+        )) as { readonly id?: string } | { readonly data?: { readonly id?: string } };
+        const sessionId =
+          ("id" in created && typeof created.id === "string" && created.id) ||
+          ("data" in created &&
+            created.data &&
+            typeof created.data.id === "string" &&
+            created.data.id) ||
+          "";
+        if (!sessionId) {
+          throw new Error("Kilo session.create returned no session id.");
+        }
+
+        const result = (await readJsonData(
+          client.session.promptAsync({
+            sessionID: sessionId,
+            model: { providerID: parsed.providerId, modelID: parsed.modelId },
+            ...(parsed.variant ? { variant: parsed.variant } : {}),
+            parts: [{ type: "text", text: input.prompt }],
+          }),
+        )) as
+          | {
+              readonly data?: {
+                readonly info?: { readonly error?: unknown };
+                readonly parts?: ReadonlyArray<unknown>;
+              };
+              readonly info?: { readonly error?: unknown };
+              readonly parts?: ReadonlyArray<unknown>;
+            }
+          | undefined;
+
+        const data = result && "data" in result && result.data ? result.data : result;
+        const errorMessage = getKiloPromptErrorMessage(data?.info?.error);
+        if (errorMessage) {
+          throw new Error(errorMessage);
+        }
+        const text = getKiloTextResponse(data?.parts);
+        if (text.length === 0) {
+          throw new Error("Kilo returned empty output.");
+        }
+        return text;
+      },
+      catch: (cause) =>
+        new TextGenerationError({
+          operation: input.operation,
+          detail: cause instanceof Error ? cause.message : "Kilo text generation failed.",
+          cause,
+        }),
+    });
+
+    return yield* Schema.decodeEffect(Schema.fromJsonString(input.outputSchemaJson))(
+      extractJsonObject(rawText),
+    ).pipe(
+      Effect.catchTag("SchemaError", (cause) =>
+        Effect.fail(
+          new TextGenerationError({
+            operation: input.operation,
+            detail: "Kilo returned invalid structured output.",
+            cause,
+          }),
+        ),
+      ),
+    );
+  });
+
+  const generateCommitMessage: TextGenerationShape["generateCommitMessage"] = Effect.fn(
+    "KiloTextGeneration.generateCommitMessage",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildCommitMessagePrompt({
+      branch: input.branch,
+      stagedSummary: input.stagedSummary,
+      stagedPatch: input.stagedPatch,
+      includeBranch: input.includeBranch === true,
+    });
+    const generated = yield* runKiloJson({
+      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(
+    "KiloTextGeneration.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* runKiloJson({
+      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(
+    "KiloTextGeneration.generateBranchName",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildBranchNamePrompt({
+      message: input.message,
+      attachments: input.attachments,
+    });
+    const generated = yield* runKiloJson({
+      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(
+    "KiloTextGeneration.generateThreadTitle",
+  )(function* (input) {
+    const { prompt, outputSchema } = buildThreadTitlePrompt({
+      message: input.message,
+      attachments: input.attachments,
+    });
+    const generated = yield* runKiloJson({
+      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/OpenCodeTextGeneration.test.ts b/apps/server/src/textGeneration/OpenCodeTextGeneration.test.ts
new file mode 100644
index 00000000000..907c749355f
--- /dev/null
+++ b/apps/server/src/textGeneration/OpenCodeTextGeneration.test.ts
@@ -0,0 +1,346 @@
+import { OpenCodeSettings, ProviderInstanceId } from "@t3tools/contracts";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { it } from "@effect/vitest";
+import { Duration, Effect, Layer, Schema } from "effect";
+import { TestClock } from "effect/testing";
+import { 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/git/Layers/OpenCodeTextGeneration.ts b/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
similarity index 84%
rename from apps/server/src/git/Layers/OpenCodeTextGeneration.ts
rename to apps/server/src/textGeneration/OpenCodeTextGeneration.ts
index fd28188d600..d646e4f2e5a 100644
--- a/apps/server/src/git/Layers/OpenCodeTextGeneration.ts
+++ b/apps/server/src/textGeneration/OpenCodeTextGeneration.ts
@@ -1,29 +1,30 @@
-import { Effect, Exit, Fiber, Layer, Schema, Scope } from "effect";
+import { Effect, Exit, Fiber, Schema, Scope } from "effect";
 import * as Semaphore from "effect/Semaphore";
 
 import {
   TextGenerationError,
   type ChatAttachment,
-  type OpenCodeModelSelection,
+  type ModelSelection,
+  type OpenCodeSettings,
 } from "@t3tools/contracts";
 import { sanitizeBranchFragment, sanitizeFeatureBranchName } from "@t3tools/shared/git";
+import { getModelSelectionStringOptionValue } from "@t3tools/shared/model";
 
-import { ServerConfig } from "../../config.ts";
-import { resolveAttachmentPath } from "../../attachmentStore.ts";
-import { ServerSettingsService } from "../../serverSettings.ts";
+import { ServerConfig } from "../config.ts";
+import { resolveAttachmentPath } from "../attachmentStore.ts";
 import {
   buildBranchNamePrompt,
   buildCommitMessagePrompt,
   buildPrContentPrompt,
   buildThreadTitlePrompt,
-} from "../Prompts.ts";
-import { type TextGenerationShape, TextGeneration } from "../Services/TextGeneration.ts";
+} from "./TextGenerationPrompts.ts";
+import { type TextGenerationShape } from "./TextGeneration.ts";
 import {
   extractJsonObject,
   sanitizeCommitSubject,
   sanitizePrTitle,
   sanitizeThreadTitle,
-} from "../Utils.ts";
+} from "./TextGenerationUtils.ts";
 import {
   OpenCodeRuntime,
   type OpenCodeServerConnection,
@@ -31,7 +32,7 @@ import {
   openCodeRuntimeErrorDetail,
   parseOpenCodeModelSlug,
   toOpenCodeFileParts,
-} from "../../provider/opencodeRuntime.ts";
+} from "../provider/opencodeRuntime.ts";
 
 const OPENCODE_TEXT_GENERATION_IDLE_TTL = "30 seconds";
 
@@ -92,9 +93,11 @@ interface SharedOpenCodeTextGenerationServerState {
   idleCloseFiber: Fiber.Fiber<void, never> | null;
 }
 
-const makeOpenCodeTextGeneration = Effect.gen(function* () {
+export const makeOpenCodeTextGeneration = Effect.fn("makeOpenCodeTextGeneration")(function* (
+  openCodeSettings: OpenCodeSettings,
+  environment: NodeJS.ProcessEnv = process.env,
+) {
   const serverConfig = yield* ServerConfig;
-  const serverSettingsService = yield* ServerSettingsService;
   const openCodeRuntime = yield* OpenCodeRuntime;
   const idleFiberScope = yield* Effect.acquireRelease(Scope.make(), (scope) =>
     Scope.close(scope, Exit.void),
@@ -201,6 +204,7 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
                 openCodeRuntime
                   .startOpenCodeServerProcess({
                     binaryPath: input.binaryPath,
+                    environment,
                   })
                   .pipe(
                     Effect.provideService(Scope.Scope, serverScope),
@@ -266,7 +270,7 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
     readonly cwd: string;
     readonly prompt: string;
     readonly outputSchemaJson: S;
-    readonly modelSelection: OpenCodeModelSelection;
+    readonly modelSelection: ModelSelection;
     readonly attachments?: ReadonlyArray<ChatAttachment> | undefined;
   }) {
     const parsedModel = parseOpenCodeModelSlug(input.modelSelection.model);
@@ -277,26 +281,6 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
       });
     }
 
-    const settings = yield* serverSettingsService.getSettings.pipe(
-      Effect.map(
-        (value) =>
-          value.providers?.opencode ?? {
-            enabled: true,
-            binaryPath: "opencode",
-            serverUrl: "",
-            serverPassword: "",
-            customModels: [],
-          },
-      ),
-      Effect.orElseSucceed(() => ({
-        enabled: true,
-        binaryPath: "opencode",
-        serverUrl: "",
-        serverPassword: "",
-        customModels: [],
-      })),
-    );
-
     const fileParts = toOpenCodeFileParts({
       attachments: input.attachments,
       resolveAttachmentPath: (attachment) =>
@@ -309,8 +293,8 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
           const client = openCodeRuntime.createOpenCodeSdkClient({
             baseUrl: server.url,
             directory: input.cwd,
-            ...(settings.serverUrl.length > 0 && settings.serverPassword
-              ? { serverPassword: settings.serverPassword }
+            ...(openCodeSettings.serverUrl.length > 0 && openCodeSettings.serverPassword
+              ? { serverPassword: openCodeSettings.serverPassword }
               : {}),
           });
           const session = await client.session.create({
@@ -320,16 +304,17 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
           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,
-            ...(input.modelSelection.options?.agent
-              ? { agent: input.modelSelection.options.agent }
-              : {}),
-            ...(input.modelSelection.options?.variant
-              ? { variant: input.modelSelection.options.variant }
-              : {}),
+            ...(selectedAgent ? { agent: selectedAgent } : {}),
+            ...(selectedVariant ? { variant: selectedVariant } : {}),
             parts: [{ type: "text", text: input.prompt }, ...fileParts],
           });
           const info = result.data?.info;
@@ -352,11 +337,11 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
       });
 
     const rawOutput =
-      settings.serverUrl.length > 0
-        ? yield* runAgainstServer({ url: settings.serverUrl })
+      openCodeSettings.serverUrl.length > 0
+        ? yield* runAgainstServer({ url: openCodeSettings.serverUrl })
         : yield* Effect.acquireUseRelease(
             acquireSharedServer({
-              binaryPath: settings.binaryPath,
+              binaryPath: openCodeSettings.binaryPath,
               operation: input.operation,
             }),
             runAgainstServer,
@@ -381,13 +366,6 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
   const generateCommitMessage: TextGenerationShape["generateCommitMessage"] = Effect.fn(
     "OpenCodeTextGeneration.generateCommitMessage",
   )(function* (input) {
-    if (input.modelSelection.provider !== "opencode") {
-      return yield* new TextGenerationError({
-        operation: "generateCommitMessage",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const { prompt, outputSchema } = buildCommitMessagePrompt({
       branch: input.branch,
       stagedSummary: input.stagedSummary,
@@ -414,13 +392,6 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
   const generatePrContent: TextGenerationShape["generatePrContent"] = Effect.fn(
     "OpenCodeTextGeneration.generatePrContent",
   )(function* (input) {
-    if (input.modelSelection.provider !== "opencode") {
-      return yield* new TextGenerationError({
-        operation: "generatePrContent",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const { prompt, outputSchema } = buildPrContentPrompt({
       baseBranch: input.baseBranch,
       headBranch: input.headBranch,
@@ -445,13 +416,6 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
   const generateBranchName: TextGenerationShape["generateBranchName"] = Effect.fn(
     "OpenCodeTextGeneration.generateBranchName",
   )(function* (input) {
-    if (input.modelSelection.provider !== "opencode") {
-      return yield* new TextGenerationError({
-        operation: "generateBranchName",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const { prompt, outputSchema } = buildBranchNamePrompt({
       message: input.message,
       attachments: input.attachments,
@@ -473,13 +437,6 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
   const generateThreadTitle: TextGenerationShape["generateThreadTitle"] = Effect.fn(
     "OpenCodeTextGeneration.generateThreadTitle",
   )(function* (input) {
-    if (input.modelSelection.provider !== "opencode") {
-      return yield* new TextGenerationError({
-        operation: "generateThreadTitle",
-        detail: "Invalid model selection.",
-      });
-    }
-
     const { prompt, outputSchema } = buildThreadTitlePrompt({
       message: input.message,
       attachments: input.attachments,
@@ -505,5 +462,3 @@ const makeOpenCodeTextGeneration = Effect.gen(function* () {
     generateThreadTitle,
   } satisfies TextGenerationShape;
 });
-
-export const OpenCodeTextGenerationLive = Layer.effect(TextGeneration, makeOpenCodeTextGeneration);
diff --git a/apps/server/src/textGeneration/TextGeneration.test.ts b/apps/server/src/textGeneration/TextGeneration.test.ts
new file mode 100644
index 00000000000..4f3d44f9258
--- /dev/null
+++ b/apps/server/src/textGeneration/TextGeneration.test.ts
@@ -0,0 +1,117 @@
+import { it } from "@effect/vitest";
+import { Effect, PubSub, Result, Stream } from "effect";
+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 57%
rename from apps/server/src/git/Services/TextGeneration.ts
rename to apps/server/src/textGeneration/TextGeneration.ts
index c0356438a29..51796faf8a7 100644
--- a/apps/server/src/git/Services/TextGeneration.ts
+++ b/apps/server/src/textGeneration/TextGeneration.ts
@@ -1,18 +1,13 @@
-/**
- * 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, ProviderKind } from "@t3tools/contracts";
+import { Context, Effect, Layer } from "effect";
+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" | "cursor" | "opencode";
 
 export interface CommitMessageGenerationInput {
@@ -20,8 +15,6 @@ export interface CommitMessageGenerationInput {
   branch: string | null;
   stagedSummary: string;
   stagedPatch: string;
-  provider?: ProviderKind | undefined;
-  model?: string | undefined;
   /** When true, the model also returns a semantic branch name for the change. */
   includeBranch?: boolean;
   /** What model and provider to use for generation. */
@@ -42,8 +35,6 @@ export interface PrContentGenerationInput {
   commitSummary: string;
   diffSummary: string;
   diffPatch: string;
-  provider?: ProviderKind | undefined;
-  model?: string | undefined;
   /** What model and provider to use for generation. */
   modelSelection: ModelSelection;
 }
@@ -56,8 +47,6 @@ export interface PrContentGenerationResult {
 export interface BranchNameGenerationInput {
   cwd: string;
   message: string;
-  provider?: ProviderKind | undefined;
-  model?: string | undefined;
   attachments?: ReadonlyArray<ChatAttachment> | undefined;
   /** What model and provider to use for generation. */
   modelSelection: ModelSelection;
@@ -125,5 +114,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..b0e020fa4fc
--- /dev/null
+++ b/apps/server/src/textGeneration/TextGenerationPolicy.ts
@@ -0,0 +1,19 @@
+import { Schema } from "effect";
+
+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 87%
rename from apps/server/src/git/Prompts.ts
rename to apps/server/src/textGeneration/TextGenerationPrompts.ts
index 4092358825c..43ae62047b9 100644
--- a/apps/server/src/git/Prompts.ts
+++ b/apps/server/src/textGeneration/TextGenerationPrompts.ts
@@ -9,7 +9,13 @@
 import { Schema } from "effect";
 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..fcd8cc8b689
--- /dev/null
+++ b/apps/server/src/textGeneration/TextGenerationUtils.ts
@@ -0,0 +1,159 @@
+import { Schema } from "effect";
+
+import { TextGenerationError } from "@t3tools/contracts";
+
+/** 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]`;
+}
+
+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);
+}
+
+/** 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/vcs/GitVcsDriver.test.ts b/apps/server/src/vcs/GitVcsDriver.test.ts
new file mode 100644
index 00000000000..0e5ba5b82ec
--- /dev/null
+++ b/apps/server/src/vcs/GitVcsDriver.test.ts
@@ -0,0 +1,99 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Effect, FileSystem, Layer, Path, PlatformError } from "effect";
+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;
+
+  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",
+      },
+    });
+
+    assert.deepStrictEqual(observedEnv, {
+      GIT_INDEX_FILE: "/tmp/t3-index",
+    });
+  }).pipe(
+    Effect.provide(
+      Layer.mock(VcsProcess.VcsProcess)({
+        run: (input) =>
+          Effect.sync(() => {
+            observedEnv = input.env;
+            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..49a135aec4c
--- /dev/null
+++ b/apps/server/src/vcs/GitVcsDriver.ts
@@ -0,0 +1,557 @@
+import { Context, DateTime, Effect, Layer, Option } from "effect";
+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 truncateOutputAtMaxBytes?: 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 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 truncateOutputAtMaxBytes?: boolean;
+  },
+) =>
+  process.run({
+    operation,
+    command: "git",
+    args,
+    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?.truncateOutputAtMaxBytes !== undefined
+      ? { truncateOutputAtMaxBytes: options.truncateOutputAtMaxBytes }
+      : {}),
+  });
+
+export const makeVcsDriverShape = Effect.fn("makeGitVcsDriverShape")(function* () {
+  const process = 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(
+      process,
+      "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(process, 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.truncateOutputAtMaxBytes !== undefined
+        ? { truncateOutputAtMaxBytes: input.truncateOutputAtMaxBytes }
+        : {}),
+    });
+
+  const detectRepository: VcsDriver.VcsDriverShape["detectRepository"] = Effect.fn(
+    "detectRepository",
+  )(function* (cwd) {
+    if (!(yield* isInsideWorkTree(cwd))) {
+      return null;
+    }
+
+    const root = yield* gitCommand(process, "GitVcsDriver.detectRepository.root", cwd, [
+      "rev-parse",
+      "--show-toplevel",
+    ]);
+    const gitCommonDir = yield* gitCommand(
+      process,
+      "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(
+      process,
+      "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,
+        truncateOutputAtMaxBytes: 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(process, "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(
+        process,
+        "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,
+          truncateOutputAtMaxBytes: 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(process, "GitVcsDriver.initRepository", input.cwd, ["init"], {
+      timeoutMs: 10_000,
+      maxOutputBytes: 64 * 1024,
+    }).pipe(Effect.asVoid);
+
+  return VcsDriver.VcsDriver.of({
+    capabilities,
+    execute,
+    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..0daf9ab9564
--- /dev/null
+++ b/apps/server/src/vcs/GitVcsDriverCore.test.ts
@@ -0,0 +1,365 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it, describe } from "@effect/vitest";
+import { Effect, FileSystem, Layer, Path, PlatformError, Scope } from "effect";
+
+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("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 59%
rename from apps/server/src/git/Layers/GitCore.ts
rename to apps/server/src/vcs/GitVcsDriverCore.ts
index 660d1092b40..4425285164d 100644
--- a/apps/server/src/git/Layers/GitCore.ts
+++ b/apps/server/src/vcs/GitVcsDriverCore.ts
@@ -1,11 +1,11 @@
 import {
   Cache,
   Data,
+  DateTime,
   Duration,
   Effect,
   Exit,
   FileSystem,
-  Layer,
   Option,
   Path,
   PlatformError,
@@ -19,25 +19,17 @@ import {
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import nodePath from "node:path";
 
-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 "../observability/Attributes.ts";
+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";
+} from "../git/remoteRefs.ts";
+import { ServerConfig } from "../config.ts";
 import { decodeJsonResult } from "@t3tools/shared/schemaJson";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -47,21 +39,13 @@ 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 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,
@@ -72,6 +56,7 @@ const NON_REPOSITORY_STATUS_DETAILS = Object.freeze<GitStatusDetails>({
   hasUpstream: false,
   aheadCount: 0,
   behindCount: 0,
+  aheadOfDefaultCount: 0,
 });
 
 type TraceTailState = {
@@ -91,7 +76,7 @@ interface ExecuteGitOptions {
   fallbackErrorMessage?: string | undefined;
   maxOutputBytes?: number | undefined;
   truncateOutputAtMaxBytes?: boolean | undefined;
-  progress?: ExecuteGitProgress | undefined;
+  progress?: GitVcsDriver.ExecuteGitProgress | undefined;
 }
 
 function parseBranchAb(value: string): { ahead: number; behind: number } {
@@ -127,47 +112,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();
@@ -206,34 +150,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,
   };
@@ -274,7 +218,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;
@@ -283,28 +227,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,
   };
 }
 
@@ -316,11 +260,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;
     }
   }
@@ -347,8 +291,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(
@@ -382,7 +326,7 @@ 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) =>
@@ -402,17 +346,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;
@@ -426,8 +371,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,
@@ -461,7 +406,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;
@@ -485,7 +430,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,
       });
@@ -497,9 +443,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,
@@ -581,7 +530,7 @@ const createTrace2Monitor = Effect.fn("createTrace2Monitor")(function* (
 });
 
 const collectOutput = Effect.fn("collectOutput")(function* <E>(
-  input: Pick<ExecuteGitInput, "operation" | "cwd" | "args">,
+  input: Pick<GitVcsDriver.ExecuteGitInput, "operation" | "cwd" | "args">,
   stream: Stream.Stream<Uint8Array, E>,
   maxOutputBytes: number,
   truncateOutputAtMaxBytes: boolean,
@@ -654,14 +603,14 @@ 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* (options?: {
+  executeOverride?: GitVcsDriver.GitVcsDriverShape["execute"];
 }) {
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const { worktreesDir } = yield* ServerConfig;
 
-  let executeRaw: GitCoreShape["execute"];
+  let executeRaw: GitVcsDriver.GitVcsDriverShape["execute"];
 
   if (options?.executeOverride) {
     executeRaw = options.executeOverride;
@@ -712,7 +661,6 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
               input.progress?.onStderrLine,
             ),
             child.exitCode.pipe(
-              Effect.map((value) => Number(value)),
               Effect.mapError(toGitCommandError(commandInput, "failed to report exit code.")),
             ),
             input.stdin === undefined
@@ -739,12 +687,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(
@@ -768,7 +716,7 @@ 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,
@@ -792,7 +740,7 @@ 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,
@@ -807,7 +755,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       ...(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();
@@ -824,7 +772,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"}`,
           ),
         );
       }),
@@ -860,16 +808,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,
@@ -889,7 +837,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}'.`,
@@ -898,7 +846,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,
@@ -908,7 +856,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>>([])),
     );
@@ -925,7 +873,7 @@ 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],
       {
@@ -936,7 +884,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
   };
 
   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()));
@@ -979,13 +927,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);
@@ -995,27 +943,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";
@@ -1026,7 +983,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.",
@@ -1035,12 +992,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) {
@@ -1048,7 +1005,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,
@@ -1060,39 +1017,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()));
 
@@ -1119,7 +1084,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;
       }
 
@@ -1140,20 +1105,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;
     }
 
@@ -1163,7 +1128,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",
@@ -1178,7 +1143,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;
     }
 
@@ -1199,7 +1164,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"],
       {
@@ -1211,27 +1176,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"],
             {
@@ -1244,21 +1209,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 ")) {
@@ -1280,13 +1246,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 }>();
@@ -1315,12 +1299,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: {
@@ -1331,67 +1312,71 @@ 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"],
       {
@@ -1406,11 +1391,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();
@@ -1427,11 +1412,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()));
@@ -1439,656 +1424,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,
+            maxOutputBytes: RANGE_COMMIT_SUMMARY_MAX_OUTPUT_BYTES,
             truncateOutputAtMaxBytes: 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,
+            truncateOutputAtMaxBytes: true,
+          },
+        ),
+        runGitStdoutWithOptions(
+          "GitVcsDriver.readRangeContext.diffPatch",
+          cwd,
+          ["diff", "--patch", "--minimal", range],
+          {
+            maxOutputBytes: RANGE_DIFF_PATCH_MAX_OUTPUT_BYTES,
+            truncateOutputAtMaxBytes: 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"],
             {
@@ -2097,71 +2036,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",
@@ -2175,7 +2116,7 @@ export const makeGitCore = Effect.fn("makeGitCore")(function* (options?: {
       ),
     );
 
-  return {
+  return GitVcsDriver.GitVcsDriver.of({
     execute,
     status,
     statusDetails,
@@ -2186,22 +2127,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..ae09d840f88
--- /dev/null
+++ b/apps/server/src/vcs/VcsDriver.ts
@@ -0,0 +1,31 @@
+import { Context, type Effect } from "effect";
+
+import type {
+  VcsDriverCapabilities,
+  VcsError,
+  VcsInitInput,
+  VcsListRemotesResult,
+  VcsListWorkspaceFilesResult,
+  VcsRepositoryIdentity,
+} from "@t3tools/contracts";
+import * as VcsProcess from "./VcsProcess.ts";
+
+export interface VcsDriverShape {
+  readonly capabilities: VcsDriverCapabilities;
+  readonly execute: (
+    input: Omit<VcsProcess.VcsProcessInput, "command">,
+  ) => Effect.Effect<VcsProcess.VcsProcessOutput, VcsError>;
+  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..b9330c885a8
--- /dev/null
+++ b/apps/server/src/vcs/VcsDriverRegistry.test.ts
@@ -0,0 +1,86 @@
+import { assert, it, describe } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+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,
+});
+
+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(
+        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(
+        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 command = input.args.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) => 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..b29fa43ed8e
--- /dev/null
+++ b/apps/server/src/vcs/VcsDriverRegistry.ts
@@ -0,0 +1,155 @@
+import { Cache, Context, Duration, Effect, Exit, Layer } from "effect";
+
+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.ts b/apps/server/src/vcs/VcsProcess.ts
new file mode 100644
index 00000000000..33e03a2551d
--- /dev/null
+++ b/apps/server/src/vcs/VcsProcess.ts
@@ -0,0 +1,259 @@
+import { Duration, Context, Effect, Layer, Option, PlatformError, Sink, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  VcsOutputDecodeError,
+  type VcsError,
+  VcsProcessExitError,
+  VcsProcessSpawnError,
+  VcsProcessTimeoutError,
+} from "@t3tools/contracts";
+
+export interface VcsProcessInput {
+  readonly operation: string;
+  readonly command: string;
+  readonly args: ReadonlyArray<string>;
+  readonly cwd: string;
+  readonly stdin?: string;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly allowNonZeroExit?: boolean;
+  readonly timeoutMs?: number;
+  readonly maxOutputBytes?: number;
+  readonly truncateOutputAtMaxBytes?: boolean;
+}
+
+export interface VcsProcessOutput {
+  readonly exitCode: ChildProcessSpawner.ExitCode;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly stdoutTruncated: boolean;
+  readonly stderrTruncated: boolean;
+}
+
+export interface VcsProcessCollectedText {
+  readonly text: string;
+  readonly truncated: boolean;
+}
+
+export interface VcsProcessHandle {
+  readonly pid: ChildProcessSpawner.ProcessId;
+  readonly stdin: Sink.Sink<void, Uint8Array, never, VcsError>;
+  readonly stdout: Stream.Stream<Uint8Array, VcsError>;
+  readonly stderr: Stream.Stream<Uint8Array, VcsError>;
+  readonly exitCode: Effect.Effect<ChildProcessSpawner.ExitCode, VcsError>;
+  readonly writeStdin: (input: string) => Effect.Effect<void, VcsError>;
+}
+
+export interface VcsProcessShape {
+  readonly withProcess: <A, E, R>(
+    input: VcsProcessInput,
+    use: (handle: VcsProcessHandle) => Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E | VcsError, R>;
+  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(" ");
+}
+
+function outputDecodeError(
+  input: VcsProcessInput,
+  detail: string,
+  cause: unknown,
+): VcsOutputDecodeError {
+  return new VcsOutputDecodeError({
+    operation: input.operation,
+    command: commandLabel(input.command, input.args),
+    cwd: input.cwd,
+    detail,
+    cause,
+  });
+}
+
+export const collectText = Effect.fn("VcsProcess.collectText")(function* (input: {
+  readonly operation: string;
+  readonly command: string;
+  readonly cwd: string;
+  readonly stream: Stream.Stream<Uint8Array, VcsError>;
+  readonly maxOutputBytes?: number;
+  readonly truncateOutputAtMaxBytes?: boolean;
+}) {
+  const decoder = new TextDecoder();
+  let text = "";
+  let bytes = 0;
+  let truncated = false;
+  const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const truncateOutputAtMaxBytes = input.truncateOutputAtMaxBytes ?? false;
+
+  yield* Stream.runForEach(input.stream, (chunk) =>
+    Effect.sync(() => {
+      if (truncated) return;
+
+      const remainingBytes = maxOutputBytes - bytes;
+      if (remainingBytes <= 0) {
+        truncated = true;
+        if (truncateOutputAtMaxBytes) {
+          text += OUTPUT_TRUNCATED_MARKER;
+        }
+        return;
+      }
+
+      const nextChunk = chunk.byteLength > remainingBytes ? chunk.slice(0, remainingBytes) : chunk;
+      text += decoder.decode(nextChunk, { stream: true });
+      bytes += nextChunk.byteLength;
+
+      if (chunk.byteLength > remainingBytes) {
+        truncated = true;
+        if (truncateOutputAtMaxBytes) {
+          text += OUTPUT_TRUNCATED_MARKER;
+        }
+      }
+    }),
+  );
+
+  if (!truncated) {
+    text += decoder.decode();
+  }
+
+  return { text, truncated } satisfies VcsProcessCollectedText;
+});
+
+export const make = Effect.fn("makeVcsProcess")(function* () {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+  const spawn = Effect.fn("VcsProcess.spawn")(function* (input: VcsProcessInput) {
+    const label = commandLabel(input.command, input.args);
+    const child = yield* spawner
+      .spawn(
+        ChildProcess.make(input.command, [...input.args], {
+          cwd: input.cwd,
+          env: {
+            ...process.env,
+            ...input.env,
+          },
+        }),
+      )
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new VcsProcessSpawnError({
+              operation: input.operation,
+              command: label,
+              cwd: input.cwd,
+              cause,
+            }),
+        ),
+      );
+    yield* Effect.addFinalizer(() => child.kill().pipe(Effect.ignore));
+
+    const mapStreamError = (streamName: "stdout" | "stderr") =>
+      Stream.mapError((cause: PlatformError.PlatformError) =>
+        outputDecodeError(input, `failed to read process ${streamName}`, cause),
+      );
+    const mapEffectError = (detail: string) =>
+      Effect.mapError((cause: PlatformError.PlatformError) =>
+        outputDecodeError(input, detail, cause),
+      );
+    const writeStdin = (stdin: string) =>
+      Stream.run(Stream.encodeText(Stream.make(stdin)), child.stdin).pipe(
+        mapEffectError("failed to write process stdin"),
+      );
+
+    return {
+      pid: child.pid,
+      stdin: child.stdin.pipe(
+        Sink.mapError((cause) => outputDecodeError(input, "failed to write process stdin", cause)),
+      ),
+      stdout: child.stdout.pipe(mapStreamError("stdout")),
+      stderr: child.stderr.pipe(mapStreamError("stderr")),
+      exitCode: child.exitCode.pipe(mapEffectError("failed to read process exit code")),
+      writeStdin,
+    } satisfies VcsProcessHandle;
+  });
+
+  const withProcess: VcsProcessShape["withProcess"] = (input, use) =>
+    Effect.scoped(spawn(input).pipe(Effect.flatMap(use)));
+
+  const run = Effect.fn("VcsProcess.run")(function* (input: VcsProcessInput) {
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxOutputBytes = input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const label = commandLabel(input.command, input.args);
+
+    const runProcess = Effect.gen(function* () {
+      const [stdout, stderr, exitCode] = yield* withProcess(input, (child) =>
+        Effect.all(
+          [
+            collectText({
+              operation: input.operation,
+              command: label,
+              cwd: input.cwd,
+              stream: child.stdout,
+              maxOutputBytes,
+              truncateOutputAtMaxBytes: input.truncateOutputAtMaxBytes ?? false,
+            }),
+            collectText({
+              operation: input.operation,
+              command: label,
+              cwd: input.cwd,
+              stream: child.stderr,
+              maxOutputBytes,
+              truncateOutputAtMaxBytes: input.truncateOutputAtMaxBytes ?? false,
+            }),
+            child.exitCode,
+            input.stdin === undefined ? Effect.void : child.writeStdin(input.stdin),
+          ],
+          { concurrency: "unbounded" },
+        ),
+      ).pipe(Effect.map(([stdout, stderr, exitCode]) => [stdout, stderr, exitCode] as const));
+
+      if (!input.allowNonZeroExit && exitCode !== 0) {
+        return yield* new VcsProcessExitError({
+          operation: input.operation,
+          command: label,
+          cwd: input.cwd,
+          exitCode,
+          detail: stderr.text.trim() || `${label} exited with code ${exitCode}.`,
+        });
+      }
+
+      return {
+        exitCode,
+        stdout: stdout.text,
+        stderr: stderr.text,
+        stdoutTruncated: stdout.truncated,
+        stderrTruncated: stderr.truncated,
+      } satisfies VcsProcessOutput;
+    });
+
+    return yield* runProcess.pipe(
+      Effect.scoped,
+      Effect.timeoutOption(Duration.millis(timeoutMs)),
+      Effect.flatMap((result) =>
+        Option.match(result, {
+          onSome: Effect.succeed,
+          onNone: () =>
+            Effect.fail(
+              new VcsProcessTimeoutError({
+                operation: input.operation,
+                command: label,
+                cwd: input.cwd,
+                timeoutMs,
+              }),
+            ),
+        }),
+      ),
+    );
+  });
+
+  return VcsProcess.of({ withProcess, run });
+});
+
+export const layer = Layer.effect(VcsProcess, make());
diff --git a/apps/server/src/vcs/VcsProjectConfig.test.ts b/apps/server/src/vcs/VcsProjectConfig.test.ts
new file mode 100644
index 00000000000..b08b5716732
--- /dev/null
+++ b/apps/server/src/vcs/VcsProjectConfig.test.ts
@@ -0,0 +1,66 @@
+import { assert, it, describe } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Effect, FileSystem, Layer, Path } from "effect";
+
+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"),
+          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..6b4ba008d4e
--- /dev/null
+++ b/apps/server/src/vcs/VcsProjectConfig.ts
@@ -0,0 +1,117 @@
+import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
+
+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),
+});
+
+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 Schema.is(ProjectVcsConfig)(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..b26f331a3c7
--- /dev/null
+++ b/apps/server/src/vcs/VcsProvisioningService.test.ts
@@ -0,0 +1,94 @@
+import { assert, it } from "@effect/vitest";
+import { DateTime, Effect, Layer, Option } from "effect";
+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..9f8f822f2a2
--- /dev/null
+++ b/apps/server/src/vcs/VcsProvisioningService.ts
@@ -0,0 +1,54 @@
+import { Context, Effect, Layer } from "effect";
+
+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 61%
rename from apps/server/src/git/Layers/GitStatusBroadcaster.test.ts
rename to apps/server/src/vcs/VcsStatusBroadcaster.test.ts
index 72a0c24e27b..ca7cccf303c 100644
--- a/apps/server/src/git/Layers/GitStatusBroadcaster.test.ts
+++ b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
@@ -1,83 +1,78 @@
-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 { Deferred, Effect, Exit, FileSystem, Layer, Option, Path, Scope, Stream } from "effect";
 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.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 +83,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 +108,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 +149,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 +174,66 @@ 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.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(Layer.mergeAll(testLayer, NodeServices.layer)));
+  });
+
   it.effect("streams a local snapshot first and remote updates later", () => {
     const state = {
       currentLocalStatus: baseLocalStatus,
@@ -190,9 +245,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,11 +266,11 @@ 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)));
   });
 
@@ -230,9 +285,9 @@ 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.provide(
-        Layer.succeed(GitManager, {
+        Layer.mock(GitWorkflowService.GitWorkflowService)({
           localStatus: () =>
             Effect.sync(() => {
               state.localStatusCalls += 1;
@@ -247,14 +302,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 +317,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 +327,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 +350,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..1d0cddc4c41
--- /dev/null
+++ b/apps/server/src/vcs/VcsStatusBroadcaster.ts
@@ -0,0 +1,344 @@
+import { realpathSync } from "node:fs";
+
+import {
+  Context,
+  Duration,
+  Effect,
+  Exit,
+  Fiber,
+  Layer,
+  PubSub,
+  Ref,
+  Scope,
+  Stream,
+  SynchronizedRef,
+} from "effect";
+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 VCS_STATUS_REFRESH_INTERVAL = Duration.seconds(30);
+
+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;
+}
+
+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,
+  ) => Stream.Stream<VcsStatusStreamEvent, GitManagerServiceError>;
+}
+
+export class VcsStatusBroadcaster extends Context.Service<
+  VcsStatusBroadcaster,
+  VcsStatusBroadcasterShape
+>()("t3/vcs/VcsStatusBroadcaster") {}
+
+function fingerprintStatusPart(status: unknown): string {
+  return JSON.stringify(status);
+}
+
+function normalizeCwd(cwd: string): string {
+  try {
+    return realpathSync.native(cwd);
+  } catch {
+    return cwd;
+  }
+}
+
+export const layer = Layer.effect(
+  VcsStatusBroadcaster,
+  Effect.gen(function* () {
+    const workflow = yield* GitWorkflowService.GitWorkflowService;
+    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 getStatus: VcsStatusBroadcasterShape["getStatus"] = Effect.fn(
+      "VcsStatusBroadcaster.getStatus",
+    )(function* (input) {
+      const cwd = 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 = 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 = normalizeCwd(rawCwd);
+      const [local, remote] = yield* Effect.all([
+        refreshLocalStatus(cwd),
+        refreshRemoteStatus(cwd),
+      ]);
+      return mergeGitStatusParts(local, remote);
+    });
+
+    const makeRemoteRefreshLoop = (cwd: string) => {
+      const logRefreshFailure = (error: Error) =>
+        Effect.logWarning("VCS remote status refresh failed", {
+          cwd,
+          detail: error.message,
+        });
+
+      return refreshRemoteStatus(cwd).pipe(
+        Effect.catch(logRefreshFailure),
+        Effect.andThen(
+          Effect.forever(
+            Effect.sleep(VCS_STATUS_REFRESH_INTERVAL).pipe(
+              Effect.andThen(refreshRemoteStatus(cwd).pipe(Effect.catch(logRefreshFailure))),
+            ),
+          ),
+        ),
+      );
+    };
+
+    const retainRemotePoller = Effect.fn("VcsStatusBroadcaster.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("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) =>
+      Stream.unwrap(
+        Effect.gen(function* () {
+          const cwd = 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);
+
+          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..f513f03b756
--- /dev/null
+++ b/apps/server/src/vcs/testing/VcsDriverContractHarness.ts
@@ -0,0 +1,163 @@
+import { assert, it, describe } from "@effect/vitest";
+import {
+  Effect,
+  FileSystem,
+  Layer,
+  Path,
+  type PlatformError,
+  type Scope,
+  DateTime,
+  Option,
+} from "effect";
+
+import type { VcsDriverKind } from "@t3tools/contracts";
+import * as VcsDriver from "../VcsDriver.ts";
+
+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(identity?.rootPath.endsWith(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 85b43ab37f6..a7385794e93 100644
--- a/apps/server/src/workspace/Layers/WorkspaceEntries.test.ts
+++ b/apps/server/src/workspace/Layers/WorkspaceEntries.test.ts
@@ -5,8 +5,8 @@ import { it, afterEach, describe, expect, vi } from "@effect/vitest";
 import { Effect, FileSystem, Layer, Path, PlatformError } from "effect";
 
 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 +14,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 +26,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 +51,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 } : {}),
diff --git a/apps/server/src/workspace/Layers/WorkspaceEntries.ts b/apps/server/src/workspace/Layers/WorkspaceEntries.ts
index 497c5170c38..3046546813f 100644
--- a/apps/server/src/workspace/Layers/WorkspaceEntries.ts
+++ b/apps/server/src/workspace/Layers/WorkspaceEntries.ts
@@ -2,7 +2,7 @@ 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 { Cache, DateTime, Duration, Effect, Exit, Layer, Path } from "effect";
 
 import { type FilesystemBrowseInput, type ProjectEntry } from "@t3tools/contracts";
 import { isExplicitRelativePath, isWindowsAbsolutePath } from "@t3tools/shared/path";
@@ -13,7 +13,7 @@ import {
   type RankedSearchResult,
 } from "@t3tools/shared/searchRanking";
 
-import { GitCore } from "../../git/Services/GitCore.ts";
+import { VcsDriverRegistry } from "../../vcs/VcsDriverRegistry.ts";
 import {
   WorkspaceEntries,
   WorkspaceEntriesBrowseError,
@@ -126,8 +126,9 @@ function scoreEntry(entry: SearchableWorkspaceEntry, query: string): number | nu
 }
 
 function isPathInIgnoredDirectory(relativePath: string): boolean {
-  const segments = relativePath.split("/").filter((segment) => segment.length > 0);
-  return segments.slice(0, -1).some((segment) => IGNORED_DIRECTORY_NAMES.has(segment));
+  const firstSegment = relativePath.split("/")[0];
+  if (!firstSegment) return false;
+  return IGNORED_DIRECTORY_NAMES.has(firstSegment);
 }
 
 function directoryAncestorsOf(relativePath: string): string[] {
@@ -173,38 +174,39 @@ const resolveBrowseTarget = (
 
 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)));
 
@@ -215,7 +217,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) {
@@ -247,16 +252,12 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
         )
         .map(toSearchableWorkspaceEntry);
 
-      const directoryBudget = Math.floor(WORKSPACE_INDEX_MAX_ENTRIES / 2);
-      const cappedDirectories = directoryEntries.slice(0, directoryBudget);
-      const fileBudget = WORKSPACE_INDEX_MAX_ENTRIES - cappedDirectories.length;
-      const cappedFiles = fileEntries.slice(0, fileBudget);
-      const entries = [...cappedDirectories, ...cappedFiles];
-      const totalAvailable = directoryEntries.length + fileEntries.length;
+      const now = yield* DateTime.now;
+      const entries = [...directoryEntries, ...fileEntries];
       return {
-        scannedAt: Date.now(),
-        entries,
-        truncated: listedFiles.truncated || totalAvailable > WORKSPACE_INDEX_MAX_ENTRIES,
+        scannedAt: now.epochMilliseconds,
+        entries: entries.slice(0, WORKSPACE_INDEX_MAX_ENTRIES),
+        truncated: listedFiles.truncated || entries.length > WORKSPACE_INDEX_MAX_ENTRIES,
       };
     },
   );
@@ -283,15 +284,7 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
         }),
     }).pipe(
       Effect.catchIf(
-        (error) => {
-          if (relativeDir.length === 0) return false;
-          const cause = error.cause;
-          if (cause instanceof Error && "code" in cause) {
-            const code = (cause as NodeJS.ErrnoException).code;
-            return code === "ENOENT" || code === "ENOTDIR";
-          }
-          return false;
-        },
+        () => relativeDir.length > 0,
         () => Effect.succeed({ relativeDir, dirents: null }),
       ),
     );
@@ -300,7 +293,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[] = [];
@@ -348,7 +341,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) {
@@ -380,8 +373,9 @@ export const makeWorkspaceEntries = Effect.gen(function* () {
       }
     }
 
+    const now = yield* DateTime.now;
     return {
-      scannedAt: Date.now(),
+      scannedAt: now.epochMilliseconds,
       entries,
       truncated,
     };
@@ -390,9 +384,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);
   });
diff --git a/apps/server/src/workspace/Layers/WorkspaceFileSystem.test.ts b/apps/server/src/workspace/Layers/WorkspaceFileSystem.test.ts
index fcfd13c912e..9c38b88f851 100644
--- a/apps/server/src/workspace/Layers/WorkspaceFileSystem.test.ts
+++ b/apps/server/src/workspace/Layers/WorkspaceFileSystem.test.ts
@@ -3,7 +3,8 @@ import { it, describe, expect } from "@effect/vitest";
 import { Effect, FileSystem, Layer, Path } from "effect";
 
 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 +20,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/ws.ts b/apps/server/src/ws.ts
index aac716cfeb6..fbefe6eac62 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -29,9 +29,6 @@ import { RpcSerialization, RpcServer } from "effect/unstable/rpc";
 
 import { CheckpointDiffQuery } from "./checkpointing/Services/CheckpointDiffQuery.ts";
 import { ServerConfig } from "./config.ts";
-import { GitCore } from "./git/Services/GitCore.ts";
-import { GitManager } from "./git/Services/GitManager.ts";
-import { GitStatusBroadcaster } from "./git/Services/GitStatusBroadcaster.ts";
 import { Keybindings } from "./keybindings.ts";
 import { Open, resolveAvailableEditors } from "./open.ts";
 import { normalizeDispatchCommand } from "./orchestration/Normalizer.ts";
@@ -45,15 +42,29 @@ import {
 import { ProviderRegistry } from "./provider/Services/ProviderRegistry.ts";
 import { ServerLifecycleEvents } from "./serverLifecycleEvents.ts";
 import { ServerRuntimeStartup } from "./serverRuntimeStartup.ts";
-import { ServerSettingsService } from "./serverSettings.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 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,
@@ -136,9 +147,9 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
       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 gitWorkflow = yield* GitWorkflowService;
+      const vcsProvisioning = yield* VcsProvisioningService;
+      const vcsStatusBroadcaster = yield* VcsStatusBroadcaster;
       const terminalManager = yield* TerminalManager;
       const providerRegistry = yield* ProviderRegistry;
       const config = yield* ServerConfig;
@@ -151,6 +162,8 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
       const repositoryIdentityResolver = yield* RepositoryIdentityResolver;
       const serverEnvironment = yield* ServerEnvironment;
       const serverAuth = yield* ServerAuth;
+      const sourceControlDiscovery = yield* SourceControlDiscoveryLayer.SourceControlDiscovery;
+      const sourceControlRepositories = yield* SourceControlRepositoryService;
       const bootstrapCredentials = yield* BootstrapCredentialService;
       const sessions = yield* SessionCredentialService;
       const serverCommandId = (tag: string) =>
@@ -453,10 +466,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;
@@ -464,7 +477,7 @@ 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);
@@ -512,7 +525,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();
 
@@ -540,7 +553,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
       });
 
       const refreshGitStatus = (cwd: string) =>
-        gitStatusBroadcaster
+        vcsStatusBroadcaster
           .refreshStatus(cwd)
           .pipe(Effect.ignoreCause({ log: true }), Effect.forkDetach, Effect.asVoid);
 
@@ -667,6 +680,9 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             ORCHESTRATION_WS_METHODS.subscribeShell,
             Effect.gen(function* () {
               const snapshot = yield* projectionSnapshotQuery.getShellSnapshot().pipe(
+                Effect.tapError((cause) =>
+                  Effect.logError("orchestration shell snapshot load failed", { cause }),
+                ),
                 Effect.mapError(
                   (cause) =>
                     new OrchestrationGetSnapshotError({
@@ -749,10 +765,13 @@ 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.serverUpsertKeybinding]: (rule) =>
@@ -765,13 +784,55 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             { "rpc.aggregate": "server" },
           ),
         [WS_METHODS.serverGetSettings]: (_input) =>
-          observeRpcEffect(WS_METHODS.serverGetSettings, serverSettings.getSettings, {
-            "rpc.aggregate": "server",
-          }),
+          observeRpcEffect(
+            WS_METHODS.serverGetSettings,
+            serverSettings.getSettings.pipe(Effect.map(redactServerSettingsForClient)),
+            {
+              "rpc.aggregate": "server",
+            },
+          ),
         [WS_METHODS.serverUpdateSettings]: ({ patch }) =>
-          observeRpcEffect(WS_METHODS.serverUpdateSettings, serverSettings.updateSettings(patch), {
-            "rpc.aggregate": "server",
-          }),
+          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.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,
@@ -820,26 +881,26 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             ),
             { "rpc.aggregate": "workspace" },
           ),
-        [WS_METHODS.subscribeGitStatus]: (input) =>
+        [WS_METHODS.subscribeVcsStatus]: (input) =>
           observeRpcStream(
-            WS_METHODS.subscribeGitStatus,
-            gitStatusBroadcaster.streamStatus(input),
+            WS_METHODS.subscribeVcsStatus,
+            vcsStatusBroadcaster.streamStatus(input),
             {
-              "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) =>
@@ -852,7 +913,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
           observeRpcStream(
             WS_METHODS.gitRunStackedAction,
             Stream.callback<GitActionProgressEvent, GitManagerServiceError>((queue) =>
-              gitManager
+              gitWorkflow
                 .runStackedAction(input, {
                   actionId: input.actionId,
                   progressReporter: {
@@ -869,55 +930,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), {
@@ -963,6 +1028,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                   version: 1 as const,
                   type: "keybindingsUpdated" as const,
                   payload: {
+                    keybindings: event.keybindings,
                     issues: event.issues,
                   },
                 })),
@@ -976,6 +1042,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                 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,
@@ -983,13 +1050,9 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                 })),
               );
 
-              yield* Effect.all(
-                [providerRegistry.refresh("codex"), providerRegistry.refresh("claudeAgent")],
-                {
-                  concurrency: "unbounded",
-                  discard: true,
-                },
-              ).pipe(Effect.ignoreCause({ log: true }), Effect.forkScoped);
+              yield* providerRegistry
+                .refresh()
+                .pipe(Effect.ignoreCause({ log: true }), Effect.forkScoped);
 
               const liveUpdates = Stream.merge(
                 keybindingsUpdates,
@@ -1076,7 +1139,30 @@ export const websocketRpcRouteLayer = Layer.unwrap(
           },
         }).pipe(
           Effect.provide(
-            makeWsRpcLayer(session.sessionId).pipe(Layer.provideMerge(RpcSerialization.layerJson)),
+            makeWsRpcLayer(session.sessionId).pipe(
+              Layer.provideMerge(RpcSerialization.layerJson),
+              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/web/index.html b/apps/web/index.html
index 53e59c71bbc..53040ee5f88 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/src/appSettings.test.ts b/apps/web/src/appSettings.test.ts
deleted file mode 100644
index cf3548beeff..00000000000
--- a/apps/web/src/appSettings.test.ts
+++ /dev/null
@@ -1,440 +0,0 @@
-import { Schema } from "effect";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-
-import {
-  AppSettingsSchema,
-  DEFAULT_SIDEBAR_PROJECT_SORT_ORDER,
-  DEFAULT_SIDEBAR_THREAD_SORT_ORDER,
-  DEFAULT_TIMESTAMP_FORMAT,
-  getProviderStartOptions,
-} from "./appSettings";
-import {
-  getAppModelOptions,
-  getAppSettingsSnapshot,
-  getCustomModelOptionsByProvider,
-  getCustomModelsByProvider,
-  getCustomModelsForProvider,
-  getDefaultCustomModelsForProvider,
-  MODEL_PROVIDER_SETTINGS,
-  normalizeCustomModelSlugs,
-  patchCustomModels,
-  patchGitTextGenerationModelOverrides,
-  resolveAppModelSelection,
-  resolveGitTextGenerationModelSelection,
-} from "./appSettings";
-
-/** Empty custom models for all providers — test helper */
-const EMPTY_CUSTOM_MODELS = {
-  codex: [] as readonly string[],
-  copilot: [] as readonly string[],
-  claudeAgent: [] as readonly string[],
-  cursor: [] as readonly string[],
-  opencode: [] as readonly string[],
-  geminiCli: [] as readonly string[],
-  amp: [] as readonly string[],
-  kilo: [] as readonly string[],
-} as const;
-
-const APP_SETTINGS_STORAGE_KEY = "t3code:app-settings:v1";
-
-const originalWindow = globalThis.window;
-const originalLocalStorage = globalThis.localStorage;
-
-function createLocalStorageMock(): Storage {
-  const store = new Map<string, string>();
-  return {
-    get length() {
-      return store.size;
-    },
-    clear() {
-      store.clear();
-    },
-    getItem(key) {
-      return store.get(key) ?? null;
-    },
-    key(index) {
-      return Array.from(store.keys())[index] ?? null;
-    },
-    removeItem(key) {
-      store.delete(key);
-    },
-    setItem(key, value) {
-      store.set(key, String(value));
-    },
-  };
-}
-
-beforeEach(() => {
-  const localStorage = createLocalStorageMock();
-  Object.defineProperty(globalThis, "localStorage", {
-    configurable: true,
-    value: localStorage,
-  });
-  Object.defineProperty(globalThis, "window", {
-    configurable: true,
-    value: {
-      localStorage,
-    },
-  });
-});
-
-afterEach(() => {
-  Object.defineProperty(globalThis, "window", {
-    configurable: true,
-    value: originalWindow,
-  });
-  Object.defineProperty(globalThis, "localStorage", {
-    configurable: true,
-    value: originalLocalStorage,
-  });
-});
-
-describe("normalizeCustomModelSlugs", () => {
-  it("normalizes aliases, removes built-ins, and deduplicates values", () => {
-    expect(
-      normalizeCustomModelSlugs([
-        " custom/internal-model ",
-        "gpt-5.3-codex",
-        "5.3",
-        "custom/internal-model",
-        "",
-        null,
-      ]),
-    ).toEqual(["custom/internal-model"]);
-  });
-
-  it("normalizes provider-specific aliases for claude and cursor", () => {
-    expect(normalizeCustomModelSlugs(["sonnet"], "claudeAgent")).toEqual([]);
-    expect(normalizeCustomModelSlugs(["claude/custom-sonnet"], "claudeAgent")).toEqual([
-      "claude/custom-sonnet",
-    ]);
-    expect(normalizeCustomModelSlugs(["composer"], "cursor")).toEqual([]);
-    expect(normalizeCustomModelSlugs(["cursor/custom-model"], "cursor")).toEqual([
-      "cursor/custom-model",
-    ]);
-  });
-});
-
-describe("getAppModelOptions", () => {
-  it("appends saved custom models after the built-in options", () => {
-    const options = getAppModelOptions("codex", ["custom/internal-model"]);
-
-    expect(options.map((option) => option.slug)).toEqual([
-      "gpt-5.4",
-      "gpt-5.4-mini",
-      "gpt-5.3-codex",
-      "gpt-5.3-codex-spark",
-      "gpt-5.2-codex",
-      "gpt-5.2",
-      "custom/internal-model",
-    ]);
-  });
-
-  it("keeps the currently selected custom model available even if it is no longer saved", () => {
-    const options = getAppModelOptions("codex", [], "custom/selected-model");
-
-    expect(options.at(-1)).toEqual({
-      slug: "custom/selected-model",
-      name: "custom/selected-model",
-      isCustom: true,
-    });
-  });
-
-  it("keeps a saved custom provider model available as an exact slug option", () => {
-    const options = getAppModelOptions("claudeAgent", ["claude/custom-opus"], "claude/custom-opus");
-
-    expect(options.some((option) => option.slug === "claude/custom-opus" && option.isCustom)).toBe(
-      true,
-    );
-  });
-});
-
-describe("resolveAppModelSelection", () => {
-  it("preserves saved custom model slugs instead of falling back to the default", () => {
-    expect(
-      resolveAppModelSelection(
-        "codex",
-        { ...EMPTY_CUSTOM_MODELS, codex: ["galapagos-alpha"] },
-        "galapagos-alpha",
-      ),
-    ).toBe("galapagos-alpha");
-  });
-
-  it("falls back to the provider default when no model is selected", () => {
-    expect(resolveAppModelSelection("codex", EMPTY_CUSTOM_MODELS, "")).toBe("gpt-5.4");
-  });
-
-  it("resolves display names through the shared resolver", () => {
-    expect(resolveAppModelSelection("codex", EMPTY_CUSTOM_MODELS, "GPT-5.3 Codex")).toBe(
-      "gpt-5.3-codex",
-    );
-  });
-
-  it("resolves aliases through the shared resolver", () => {
-    expect(resolveAppModelSelection("claudeAgent", EMPTY_CUSTOM_MODELS, "sonnet")).toBe(
-      "claude-sonnet-4-6",
-    );
-  });
-
-  it("resolves transient selected custom models included in app model options", () => {
-    expect(resolveAppModelSelection("codex", EMPTY_CUSTOM_MODELS, "custom/selected-model")).toBe(
-      "custom/selected-model",
-    );
-  });
-});
-
-describe("resolveGitTextGenerationModelSelection", () => {
-  it("prefers a provider-specific override over the active thread model", () => {
-    const settings = {
-      ...getAppSettingsSnapshot(),
-      ...patchGitTextGenerationModelOverrides({}, "codex", "gpt-5.4-mini"),
-    };
-
-    expect(resolveGitTextGenerationModelSelection("codex", settings, "gpt-5.4")).toBe(
-      "gpt-5.4-mini",
-    );
-  });
-
-  it("falls back to the active thread model when no override is configured", () => {
-    const settings = getAppSettingsSnapshot();
-
-    expect(resolveGitTextGenerationModelSelection("cursor", settings, "opus-4.6-thinking")).toBe(
-      "opus-4.6-thinking",
-    );
-  });
-
-  it("uses the provider git default when neither an override nor thread model exists", () => {
-    const settings = getAppSettingsSnapshot();
-
-    expect(resolveGitTextGenerationModelSelection("codex", settings, null)).toBe("gpt-5.4-mini");
-  });
-});
-
-describe("timestamp format defaults", () => {
-  it("defaults timestamp format to locale", () => {
-    expect(DEFAULT_TIMESTAMP_FORMAT).toBe("locale");
-  });
-
-  it("includes provider-specific custom slugs in non-codex model lists", () => {
-    const claudeOptions = getAppModelOptions("claudeAgent", ["claude/custom-opus"]);
-    const cursorOptions = getAppModelOptions("cursor", ["cursor/custom-model"]);
-
-    expect(claudeOptions.some((option) => option.slug === "claude/custom-opus")).toBe(true);
-    expect(cursorOptions.some((option) => option.slug === "cursor/custom-model")).toBe(true);
-  });
-});
-
-describe("getAppSettingsSnapshot", () => {
-  it("defaults provider logos to color", () => {
-    expect(getAppSettingsSnapshot().providerLogoAppearance).toBe("original");
-  });
-
-  it("hydrates a persisted provider logo appearance preference", () => {
-    const persistedSettings = {
-      ...getAppSettingsSnapshot(),
-      providerLogoAppearance: "accent",
-    };
-    localStorage.setItem(APP_SETTINGS_STORAGE_KEY, JSON.stringify(persistedSettings));
-
-    expect(getAppSettingsSnapshot().providerLogoAppearance).toBe("accent");
-  });
-
-  it("migrates the legacy grayscale provider logo preference", () => {
-    localStorage.setItem(
-      APP_SETTINGS_STORAGE_KEY,
-      JSON.stringify({
-        grayscaleProviderLogos: true,
-      }),
-    );
-
-    expect(getAppSettingsSnapshot().providerLogoAppearance).toBe("grayscale");
-  });
-});
-
-describe("sidebar sort defaults", () => {
-  it("defaults project sorting to updated_at", () => {
-    expect(DEFAULT_SIDEBAR_PROJECT_SORT_ORDER).toBe("updated_at");
-  });
-
-  it("defaults thread sorting to updated_at", () => {
-    expect(DEFAULT_SIDEBAR_THREAD_SORT_ORDER).toBe("updated_at");
-  });
-});
-
-describe("provider-specific custom models", () => {
-  it("includes provider-specific custom slugs in non-codex model lists", () => {
-    const claudeOptions = getAppModelOptions("claudeAgent", ["claude/custom-opus"]);
-
-    expect(claudeOptions.some((option) => option.slug === "claude/custom-opus")).toBe(true);
-  });
-});
-
-describe("getProviderStartOptions", () => {
-  it("returns only populated provider overrides", () => {
-    expect(
-      getProviderStartOptions({
-        claudeBinaryPath: "/usr/local/bin/claude",
-        codexBinaryPath: "",
-        codexHomePath: "/Users/you/.codex",
-      }),
-    ).toEqual({
-      claudeAgent: {
-        binaryPath: "/usr/local/bin/claude",
-      },
-      codex: {
-        homePath: "/Users/you/.codex",
-      },
-    });
-  });
-
-  it("returns undefined when no provider overrides are configured", () => {
-    expect(
-      getProviderStartOptions({
-        claudeBinaryPath: "",
-        codexBinaryPath: "",
-        codexHomePath: "",
-      }),
-    ).toBeUndefined();
-  });
-});
-
-describe("provider-indexed custom model settings", () => {
-  const settings = {
-    customCodexModels: ["custom/codex-model"],
-    customClaudeModels: ["claude/custom-opus"],
-    customCopilotModels: [],
-    customCursorModels: [],
-    customOpencodeModels: [],
-    customGeminiCliModels: [],
-    customAmpModels: [],
-    customKiloModels: [],
-  } as const;
-
-  it("exports one provider config per provider", () => {
-    expect(MODEL_PROVIDER_SETTINGS.map((config) => config.provider)).toEqual([
-      "codex",
-      "copilot",
-      "claudeAgent",
-      "cursor",
-      "opencode",
-      "geminiCli",
-      "amp",
-      "kilo",
-    ]);
-  });
-
-  it("reads custom models for each provider", () => {
-    expect(getCustomModelsForProvider(settings, "codex")).toEqual(["custom/codex-model"]);
-    expect(getCustomModelsForProvider(settings, "claudeAgent")).toEqual(["claude/custom-opus"]);
-  });
-
-  it("reads default custom models for each provider", () => {
-    const defaults = {
-      customCodexModels: ["default/codex-model"],
-      customClaudeModels: ["claude/default-opus"],
-      customCopilotModels: [],
-      customCursorModels: [],
-      customOpencodeModels: [],
-      customGeminiCliModels: [],
-      customAmpModels: [],
-      customKiloModels: [],
-    } as const;
-
-    expect(getDefaultCustomModelsForProvider(defaults, "codex")).toEqual(["default/codex-model"]);
-    expect(getDefaultCustomModelsForProvider(defaults, "claudeAgent")).toEqual([
-      "claude/default-opus",
-    ]);
-  });
-
-  it("patches custom models for codex", () => {
-    expect(patchCustomModels("codex", ["custom/codex-model"])).toEqual({
-      customCodexModels: ["custom/codex-model"],
-    });
-  });
-
-  it("patches custom models for claude", () => {
-    expect(patchCustomModels("claudeAgent", ["claude/custom-opus"])).toEqual({
-      customClaudeModels: ["claude/custom-opus"],
-    });
-  });
-
-  it("builds a complete provider-indexed custom model record", () => {
-    expect(getCustomModelsByProvider(settings)).toEqual({
-      codex: ["custom/codex-model"],
-      copilot: [],
-      claudeAgent: ["claude/custom-opus"],
-      cursor: [],
-      opencode: [],
-      geminiCli: [],
-      amp: [],
-      kilo: [],
-    });
-  });
-
-  it("builds provider-indexed model options including custom models", () => {
-    const modelOptionsByProvider = getCustomModelOptionsByProvider(settings);
-
-    expect(
-      modelOptionsByProvider.codex.some((option) => option.slug === "custom/codex-model"),
-    ).toBe(true);
-    expect(
-      modelOptionsByProvider.claudeAgent.some((option) => option.slug === "claude/custom-opus"),
-    ).toBe(true);
-  });
-
-  it("normalizes and deduplicates custom model options per provider", () => {
-    const modelOptionsByProvider = getCustomModelOptionsByProvider({
-      customCodexModels: ["  custom/codex-model ", "gpt-5.4", "custom/codex-model"],
-      customClaudeModels: [" sonnet ", "claude/custom-opus", "claude/custom-opus"],
-      customCopilotModels: [],
-      customCursorModels: [],
-      customOpencodeModels: [],
-      customGeminiCliModels: [],
-      customAmpModels: [],
-      customKiloModels: [],
-    });
-
-    expect(
-      modelOptionsByProvider.codex.filter((option) => option.slug === "custom/codex-model"),
-    ).toHaveLength(1);
-    expect(modelOptionsByProvider.codex.some((option) => option.slug === "gpt-5.4")).toBe(true);
-    expect(
-      modelOptionsByProvider.claudeAgent.filter((option) => option.slug === "claude/custom-opus"),
-    ).toHaveLength(1);
-    expect(
-      modelOptionsByProvider.claudeAgent.some((option) => option.slug === "claude-sonnet-4-6"),
-    ).toBe(true);
-  });
-});
-
-describe("AppSettingsSchema", () => {
-  it("fills decoding defaults for persisted settings that predate newer keys", () => {
-    const decode = Schema.decodeUnknownSync(Schema.fromJsonString(AppSettingsSchema));
-
-    expect(
-      decode(
-        JSON.stringify({
-          codexBinaryPath: "/usr/local/bin/codex",
-          confirmThreadDelete: false,
-        }),
-      ),
-    ).toMatchObject({
-      claudeBinaryPath: "",
-      codexBinaryPath: "/usr/local/bin/codex",
-      codexHomePath: "",
-      defaultThreadEnvMode: "local",
-      confirmThreadDelete: false,
-      enableAssistantStreaming: false,
-      sidebarProjectSortOrder: DEFAULT_SIDEBAR_PROJECT_SORT_ORDER,
-      sidebarThreadSortOrder: DEFAULT_SIDEBAR_THREAD_SORT_ORDER,
-      timestampFormat: DEFAULT_TIMESTAMP_FORMAT,
-      customCodexModels: [],
-      customClaudeModels: [],
-    });
-  });
-});
-
-// Note: upstream's resolveAppModelSelectionState tests removed — the fork
-// uses resolveGitTextGenerationModelSelection with per-provider overrides
-// instead of a single textGenerationModelSelection field.  Equivalent
-// coverage lives in the resolveGitTextGenerationModelSelection tests above.
diff --git a/apps/web/src/appSettings.ts b/apps/web/src/appSettings.ts
index 1c6784e4920..c89244df6ca 100644
--- a/apps/web/src/appSettings.ts
+++ b/apps/web/src/appSettings.ts
@@ -1,11 +1,8 @@
 import { useCallback, useMemo } from "react";
 import { Effect, Schema } from "effect";
-import {
-  DEFAULT_SERVER_SETTINGS,
-  type ProviderStartOptions,
-  type ProviderKind,
-} from "@t3tools/contracts";
+import { DEFAULT_SERVER_SETTINGS } from "@t3tools/contracts";
 import { DEFAULT_CLIENT_SETTINGS, type UnifiedSettings } from "@t3tools/contracts/settings";
+import type { ProviderKind } from "./providerKind";
 import { DEFAULT_ACCENT_COLOR, isValidAccentColor, normalizeAccentColor } from "./accentColor";
 import { useLocalStorage } from "./hooks/useLocalStorage";
 import { useSettings, useUpdateSettings } from "./hooks/useSettings";
@@ -19,8 +16,6 @@ import {
   SidebarProjectSortOrder,
   SidebarThreadSortOrder,
 } from "./appearance";
-import { normalizeCustomModelSlugs } from "./customModels";
-import { normalizeGitTextGenerationModelByProvider } from "./gitTextGeneration";
 
 // Re-export everything from domain modules for backwards compatibility
 export {
@@ -36,29 +31,47 @@ export {
   DEFAULT_SIDEBAR_THREAD_SORT_ORDER,
 } from "./appearance";
 
-export {
-  MAX_CUSTOM_MODEL_LENGTH,
-  type CustomModelSettingsKey,
-  type ProviderCustomModelConfig,
-  type ProviderCustomModelSettings,
-  MODEL_PROVIDER_SETTINGS,
-  type AppModelOption,
-  normalizeCustomModelSlugs,
-  getCustomModelsForProvider,
-  patchCustomModels,
-  getDefaultCustomModelsForProvider,
-  getCustomModelsByProvider,
-  getAppModelOptions,
-  resolveAppModelSelection,
-  getCustomModelOptionsByProvider,
-  getSlashModelOptions,
-} from "./customModels";
+const MAX_CUSTOM_MODEL_COUNT = 32;
+const MAX_CUSTOM_MODEL_LENGTH_VALUE = 256;
+export const MAX_CUSTOM_MODEL_LENGTH = MAX_CUSTOM_MODEL_LENGTH_VALUE;
 
-export {
-  getGitTextGenerationModelOverride,
-  patchGitTextGenerationModelOverrides,
-  resolveGitTextGenerationModelSelection,
-} from "./gitTextGeneration";
+/**
+ * Lightweight, fork-local custom-model normalizer used while the legacy
+ * AppSettings shape is still alive in the web client. The new instance-keyed
+ * pipeline lives in `modelSelection.ts`; this helper just trims, dedupes and
+ * caps the legacy per-driver string arrays so we can keep round-tripping them
+ * through `withUnifiedCompatSettings` / `toUnifiedPatch` without touching the
+ * removed contracts surface.
+ */
+function normalizeCustomModelSlugsLocal(
+  models: Iterable<string | null | undefined>,
+): ReadonlyArray<string> {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const candidate of models) {
+    if (typeof candidate !== "string") continue;
+    const trimmed = candidate.trim();
+    if (!trimmed || trimmed.length > MAX_CUSTOM_MODEL_LENGTH_VALUE) continue;
+    if (seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+    if (out.length >= MAX_CUSTOM_MODEL_COUNT) break;
+  }
+  return out;
+}
+
+function normalizeGitTextGenerationModelByProviderLocal(
+  overrides: Record<string, string>,
+): Record<string, string> {
+  const next: Record<string, string> = {};
+  for (const [k, v] of Object.entries(overrides)) {
+    if (typeof v !== "string") continue;
+    const trimmed = v.trim();
+    if (!trimmed) continue;
+    next[k === "claudeCode" ? "claudeAgent" : k] = trimmed;
+  }
+  return next;
+}
 
 const APP_SETTINGS_STORAGE_KEY = "t3code:app-settings:v1";
 const APP_SETTINGS_PROVIDER_CUSTOM_MODEL_KEYS = {
@@ -74,6 +87,7 @@ const APP_SETTINGS_PROVIDER_CUSTOM_MODEL_KEYS = {
 const MIRRORED_CLIENT_KEYS = new Set<keyof AppSettings>([
   "confirmThreadDelete",
   "diffWordWrap",
+  "diffIgnoreWhitespace",
   "sidebarProjectSortOrder",
   "sidebarThreadSortOrder",
   "timestampFormat",
@@ -120,6 +134,7 @@ export const AppSettingsSchema = Schema.Struct({
   ),
   confirmThreadDelete: Schema.Boolean.pipe(withDefaults(() => true)),
   diffWordWrap: Schema.Boolean.pipe(withDefaults(() => false)),
+  diffIgnoreWhitespace: Schema.Boolean.pipe(withDefaults(() => true)),
   enableAssistantStreaming: Schema.Boolean.pipe(withDefaults(() => false)),
   showCommandOutput: Schema.Boolean.pipe(withDefaults(() => true)),
   showFileChangeDiffs: Schema.Boolean.pipe(withDefaults(() => true)),
@@ -175,15 +190,15 @@ const DEFAULT_APP_SETTINGS = AppSettingsSchema.make({});
 function normalizeAppSettings(settings: AppSettings): AppSettings {
   return {
     ...settings,
-    customCodexModels: normalizeCustomModelSlugs(settings.customCodexModels, "codex"),
-    customCopilotModels: normalizeCustomModelSlugs(settings.customCopilotModels, "copilot"),
-    customClaudeModels: normalizeCustomModelSlugs(settings.customClaudeModels, "claudeAgent"),
-    customCursorModels: normalizeCustomModelSlugs(settings.customCursorModels, "cursor"),
-    customOpencodeModels: normalizeCustomModelSlugs(settings.customOpencodeModels, "opencode"),
-    customGeminiCliModels: normalizeCustomModelSlugs(settings.customGeminiCliModels, "geminiCli"),
-    customAmpModels: normalizeCustomModelSlugs(settings.customAmpModels, "amp"),
-    customKiloModels: normalizeCustomModelSlugs(settings.customKiloModels, "kilo"),
-    gitTextGenerationModelByProvider: normalizeGitTextGenerationModelByProvider(
+    customCodexModels: normalizeCustomModelSlugsLocal(settings.customCodexModels),
+    customCopilotModels: normalizeCustomModelSlugsLocal(settings.customCopilotModels),
+    customClaudeModels: normalizeCustomModelSlugsLocal(settings.customClaudeModels),
+    customCursorModels: normalizeCustomModelSlugsLocal(settings.customCursorModels),
+    customOpencodeModels: normalizeCustomModelSlugsLocal(settings.customOpencodeModels),
+    customGeminiCliModels: normalizeCustomModelSlugsLocal(settings.customGeminiCliModels),
+    customAmpModels: normalizeCustomModelSlugsLocal(settings.customAmpModels),
+    customKiloModels: normalizeCustomModelSlugsLocal(settings.customKiloModels),
+    gitTextGenerationModelByProvider: normalizeGitTextGenerationModelByProviderLocal(
       settings.gitTextGenerationModelByProvider,
     ),
     accentColor: normalizeAccentColor(settings.accentColor),
@@ -195,30 +210,6 @@ function normalizeAppSettings(settings: AppSettings): AppSettings {
   };
 }
 
-export function getProviderStartOptions(
-  settings: Pick<AppSettings, "claudeBinaryPath" | "codexBinaryPath" | "codexHomePath">,
-): ProviderStartOptions | undefined {
-  const providerOptions: ProviderStartOptions = {
-    ...(settings.codexBinaryPath || settings.codexHomePath
-      ? {
-          codex: {
-            ...(settings.codexBinaryPath ? { binaryPath: settings.codexBinaryPath } : {}),
-            ...(settings.codexHomePath ? { homePath: settings.codexHomePath } : {}),
-          },
-        }
-      : {}),
-    ...(settings.claudeBinaryPath
-      ? {
-          claudeAgent: {
-            binaryPath: settings.claudeBinaryPath,
-          },
-        }
-      : {}),
-  };
-
-  return Object.keys(providerOptions).length > 0 ? providerOptions : undefined;
-}
-
 let cachedRawSettings: string | null = null;
 let cachedSnapshot: AppSettings = DEFAULT_APP_SETTINGS;
 
@@ -269,6 +260,7 @@ function withUnifiedCompatSettings(
     | "confirmThreadDelete"
     | "defaultThreadEnvMode"
     | "diffWordWrap"
+    | "diffIgnoreWhitespace"
     | "enableAssistantStreaming"
     | "providers"
     | "sidebarProjectSortOrder"
@@ -286,6 +278,7 @@ function withUnifiedCompatSettings(
     defaultThreadEnvMode: unifiedSettings.defaultThreadEnvMode,
     confirmThreadDelete: unifiedSettings.confirmThreadDelete,
     diffWordWrap: unifiedSettings.diffWordWrap,
+    diffIgnoreWhitespace: unifiedSettings.diffIgnoreWhitespace,
     enableAssistantStreaming: unifiedSettings.enableAssistantStreaming,
     sidebarProjectSortOrder: unifiedSettings.sidebarProjectSortOrder,
     sidebarThreadSortOrder: unifiedSettings.sidebarThreadSortOrder,
@@ -340,7 +333,7 @@ function toUnifiedPatch(patch: Partial<AppSettings>): Partial<UnifiedSettings> {
     }
     providersPatch[provider] = {
       ...(providersPatch[provider] ?? {}),
-      customModels: normalizeCustomModelSlugs(models, provider),
+      customModels: normalizeCustomModelSlugsLocal(models),
     };
   }
   return {
@@ -348,6 +341,9 @@ function toUnifiedPatch(patch: Partial<AppSettings>): Partial<UnifiedSettings> {
       ? { confirmThreadDelete: patch.confirmThreadDelete }
       : {}),
     ...(patch.diffWordWrap !== undefined ? { diffWordWrap: patch.diffWordWrap } : {}),
+    ...(patch.diffIgnoreWhitespace !== undefined
+      ? { diffIgnoreWhitespace: patch.diffIgnoreWhitespace }
+      : {}),
     ...(patch.sidebarProjectSortOrder !== undefined
       ? { sidebarProjectSortOrder: patch.sidebarProjectSortOrder }
       : {}),
@@ -402,6 +398,7 @@ export function useAppSettings() {
       confirmThreadDelete: unifiedSettings.confirmThreadDelete,
       defaultThreadEnvMode: unifiedSettings.defaultThreadEnvMode,
       diffWordWrap: unifiedSettings.diffWordWrap,
+      diffIgnoreWhitespace: unifiedSettings.diffIgnoreWhitespace,
       enableAssistantStreaming: unifiedSettings.enableAssistantStreaming,
       providers: unifiedSettings.providers,
       sidebarProjectSortOrder: unifiedSettings.sidebarProjectSortOrder,
diff --git a/apps/web/src/authBootstrap.test.ts b/apps/web/src/authBootstrap.test.ts
index b06c4248fca..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
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/components/AnimatedHeight.tsx b/apps/web/src/components/AnimatedHeight.tsx
new file mode 100644
index 00000000000..dd404c49dff
--- /dev/null
+++ b/apps/web/src/components/AnimatedHeight.tsx
@@ -0,0 +1,59 @@
+"use client";
+
+import { type ReactNode, useLayoutEffect, useRef, useState } from "react";
+
+export function AnimatedHeight({ children }: { readonly children: ReactNode }) {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [height, setHeight] = useState<number | null>(null);
+
+  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);
+      setHeight((currentHeight) => (currentHeight === nextHeight ? currentHeight : nextHeight));
+    };
+    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
+      className="overflow-hidden transition-[height] duration-200 ease-out motion-reduce:transition-none"
+      style={height === null ? undefined : { height }}
+    >
+      <div ref={contentRef}>{children}</div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/AppSidebarLayout.tsx b/apps/web/src/components/AppSidebarLayout.tsx
index b1ce57235a8..d98f30a1e5c 100644
--- a/apps/web/src/components/AppSidebarLayout.tsx
+++ b/apps/web/src/components/AppSidebarLayout.tsx
@@ -54,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 7beaec808db..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,
@@ -28,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,
@@ -38,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",
@@ -50,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",
@@ -61,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",
@@ -72,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",
@@ -186,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,
@@ -212,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,
@@ -236,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,
@@ -260,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,
@@ -284,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",
     ]);
@@ -292,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",
         },
@@ -309,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",
         },
@@ -326,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,
         },
@@ -343,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,
         },
@@ -373,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",
@@ -384,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 7adab1a2e16..31f614a2e2c 100644
--- a/apps/web/src/components/BranchToolbar.logic.ts
+++ b/apps/web/src/components/BranchToolbar.logic.ts
@@ -1,4 +1,4 @@
-import type { EnvironmentId, GitBranch, ProjectId } from "@t3tools/contracts";
+import type { EnvironmentId, VcsRef, ProjectId } from "@t3tools/contracts";
 import { Schema } from "effect";
 export {
   dedupeRemoteBranchesWithLocalMatches,
@@ -100,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 c6f37c42a95..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 {
@@ -30,6 +53,142 @@ 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,
@@ -74,34 +233,51 @@ export const BranchToolbar = memo(function BranchToolbar({
     });
   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 } : {})}
diff --git a/apps/web/src/components/BranchToolbarBranchSelector.tsx b/apps/web/src/components/BranchToolbarBranchSelector.tsx
index 828e6e122ba..2e30edfc02c 100644
--- a/apps/web/src/components/BranchToolbarBranchSelector.tsx
+++ b/apps/web/src/components/BranchToolbarBranchSelector.tsx
@@ -1,5 +1,5 @@
 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 { LegendList, type LegendListRef } from "@legendapp/list/react";
 import { ChevronDownIcon } from "lucide-react";
@@ -19,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 {
@@ -45,13 +47,14 @@ import {
 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?: (branch: string | null) => void;
+  onActiveThreadBranchOverrideChange?: (refName: string | null) => void;
   onCheckoutPullRequestRequest?: (reference: string) => void;
   onComposerFocusRequest?: () => void;
 }
@@ -67,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}`;
@@ -76,6 +79,7 @@ function getBranchTriggerLabel(input: {
 }
 
 export function BranchToolbarBranchSelector({
+  className,
   environmentId,
   threadId,
   draftId,
@@ -190,7 +194,7 @@ export function BranchToolbarBranchSelector({
   );
 
   // ---------------------------------------------------------------------------
-  // Git branch queries
+  // Git ref queries
   // ---------------------------------------------------------------------------
   const queryClient = useQueryClient();
   const [isBranchMenuOpen, setIsBranchMenuOpen] = useState(false);
@@ -221,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);
@@ -286,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;
 
   // ---------------------------------------------------------------------------
@@ -300,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;
@@ -319,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?.();
@@ -340,12 +349,12 @@ 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);
@@ -354,7 +363,7 @@ export function BranchToolbarBranchSelector({
         toastManager.add(
           stackedThreadToast({
             type: "error",
-            title: "Failed to checkout branch.",
+            title: "Failed to switch ref.",
             description: toBranchActionErrorMessage(error),
           }),
         );
@@ -362,7 +371,7 @@ export function BranchToolbarBranchSelector({
     });
   };
 
-  const createBranch = (rawName: string) => {
+  const createRef = (rawName: string) => {
     const name = rawName.trim();
     const api = readEnvironmentApi(environmentId);
     if (!api || !branchCwd || !name || isBranchActionPending) return;
@@ -374,19 +383,19 @@ 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(
           stackedThreadToast({
             type: "error",
-            title: "Failed to create and checkout branch.",
+            title: "Failed to create and switch ref.",
             description: toBranchActionErrorMessage(error),
           }),
         );
@@ -417,7 +426,7 @@ export function BranchToolbarBranchSelector({
         return;
       }
       void queryClient.invalidateQueries({
-        queryKey: gitQueryKeys.branches(environmentId, branchCwd),
+        queryKey: gitQueryKeys.refs(environmentId, branchCwd),
       });
     },
     [branchCwd, environmentId, queryClient],
@@ -479,7 +488,7 @@ export function BranchToolbarBranchSelector({
   useEffect(() => {
     if (shouldVirtualizeBranchList) return;
     maybeFetchNextBranchPage();
-  }, [branches.length, maybeFetchNextBranchPage, shouldVirtualizeBranchList]);
+  }, [refs.length, maybeFetchNextBranchPage, shouldVirtualizeBranchList]);
 
   const triggerLabel = getBranchTriggerLabel({
     activeWorktreePath,
@@ -505,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>
       );
@@ -519,25 +533,25 @@ export function BranchToolbarBranchSelector({
           key={itemValue}
           index={index}
           value={itemValue}
-          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 (
@@ -546,7 +560,7 @@ export function BranchToolbarBranchSelector({
         key={itemValue}
         index={index}
         value={itemValue}
-        onClick={() => selectBranch(branch)}
+        onClick={() => selectBranch(refName)}
       >
         <div className="flex w-full items-center justify-between gap-2">
           <span className="truncate">{itemValue}</span>
@@ -577,25 +591,25 @@ 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>
+        <ComboboxEmpty>No refs found.</ComboboxEmpty>
 
         {shouldVirtualizeBranchList ? (
           <ComboboxListVirtualized>
diff --git a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
index 6e1c80f5573..6d06882662f 100644
--- a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
+++ b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
@@ -58,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/ChatView.browser.tsx b/apps/web/src/components/ChatView.browser.tsx
index 2469acfb821..578dc7c045d 100644
--- a/apps/web/src/components/ChatView.browser.tsx
+++ b/apps/web/src/components/ChatView.browser.tsx
@@ -9,6 +9,8 @@ import {
   type MessageId,
   type OrchestrationReadModel,
   type ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerConfig,
   type ServerLifecycleWelcomePayload,
   type ThreadId,
@@ -18,7 +20,9 @@ import {
   DEFAULT_SERVER_SETTINGS,
 } from "@t3tools/contracts";
 import { scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime";
+import { createModelCapabilities, createModelSelection } from "@t3tools/shared/model";
 import { RouterProvider, createMemoryHistory } from "@tanstack/react-router";
+import { Option } from "effect";
 import { HttpResponse, http, ws } from "msw";
 import { setupWorker } from "msw/browser";
 import { page } from "vitest/browser";
@@ -166,7 +170,8 @@ function createBaseServerConfig(): ServerConfig {
     issues: [],
     providers: [
       {
-        provider: "codex",
+        driver: ProviderDriverKind.make("codex"),
+        instanceId: ProviderInstanceId.make("codex"),
         enabled: true,
         installed: true,
         version: "0.116.0",
@@ -202,6 +207,8 @@ function createMockEnvironmentApi(input: {
     filesystem: {
       browse: input.browse,
     },
+    sourceControl: {} as EnvironmentApi["sourceControl"],
+    vcs: {} as EnvironmentApi["vcs"],
     git: {} as EnvironmentApi["git"],
     orchestration: {
       dispatchCommand: input.dispatchCommand,
@@ -322,7 +329,7 @@ function createSnapshotForTargetUser(options: {
         title: "Project",
         workspaceRoot: "/repo/project",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         scripts: [],
@@ -337,7 +344,7 @@ function createSnapshotForTargetUser(options: {
         projectId: PROJECT_ID,
         title: THREAD_TITLE,
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         interactionMode: "default",
@@ -402,7 +409,7 @@ function addThreadToSnapshot(
         projectId: PROJECT_ID,
         title: "New thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         interactionMode: "default",
@@ -739,7 +746,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",
@@ -771,7 +778,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",
@@ -806,7 +813,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,
@@ -883,7 +890,7 @@ function createSnapshotWithPendingUserInput(): OrchestrationReadModel {
 }
 
 function createSnapshotWithPlanFollowUpPrompt(options?: {
-  modelSelection?: { provider: "codex"; model: string };
+  modelSelection?: { instanceId: ProviderInstanceId; model: string };
   planMarkdown?: string;
 }): OrchestrationReadModel {
   const snapshot = createSnapshotForTargetUser({
@@ -891,7 +898,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 =
@@ -947,13 +954,80 @@ function resolveWsRpc(body: NormalizedWsRpcRequestBody): unknown {
   if (tag === WS_METHODS.serverGetConfig) {
     return fixture.serverConfig;
   }
-  if (tag === WS_METHODS.gitListBranches) {
+  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.vcsListRefs) {
     return {
       isRepo: true,
-      hasOriginRemote: true,
+      hasPrimaryRemote: true,
       nextCursor: null,
       totalCount: 1,
-      branches: [
+      refs: [
         {
           name: "main",
           current: true,
@@ -1657,6 +1731,74 @@ describe("ChatView timeline estimator parity (full app)", () => {
     customWsRpcResolver = null;
     document.body.innerHTML = "";
   });
+
+  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.",
+      );
+
+      expect(findButtonByText("Local checkout")).toBeNull();
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  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",
+          },
+        };
+      },
+    });
+
+    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(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 logical key", async () => {
     useUiStateStore.setState({
       projectExpandedById: {
@@ -1922,7 +2064,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
     try {
       await waitForServerConfigToApply();
       const menuButton = await waitForElement(
-        () => document.querySelector('button[aria-label="Select editor"]'),
+        () => document.querySelector('button[aria-label="Copy options"]'),
         "Unable to find Open picker button.",
       );
       (menuButton as HTMLButtonElement).click();
@@ -1971,7 +2113,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
     try {
       await waitForServerConfigToApply();
       const menuButton = await waitForElement(
-        () => document.querySelector('button[aria-label="Select editor"]'),
+        () => document.querySelector('button[aria-label="Copy options"]'),
         "Unable to find Open picker button.",
       );
       (menuButton as HTMLButtonElement).click();
@@ -2283,16 +2425,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.",
       );
@@ -2421,7 +2563,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(
@@ -2437,6 +2579,126 @@ describe("ChatView timeline estimator parity (full app)", () => {
     }
   });
 
+  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: 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 {
+            sequence: fixture.snapshot.snapshotSequence + 1,
+          };
+        }
+        return undefined;
+      },
+    });
+
+    try {
+      useComposerDraftStore.getState().setPrompt(THREAD_REF, "Hello there");
+      await waitForLayout();
+
+      const sendButton = await waitForSendButton();
+      expect(sendButton.disabled).toBe(false);
+      sendButton.click();
+
+      await vi.waitFor(
+        () => {
+          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 {
+      await mounted.cleanup();
+    }
+  });
+
   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({
@@ -2448,13 +2710,13 @@ describe("ChatView timeline estimator parity (full app)", () => {
         ),
       },
       resolveRpc: (body) => {
-        if (body._tag === WS_METHODS.gitListBranches) {
+        if (body._tag === WS_METHODS.vcsListRefs) {
           return {
             isRepo: true,
-            hasOriginRemote: true,
+            hasPrimaryRemote: true,
             nextCursor: null,
             totalCount: 1,
-            branches: [
+            refs: [
               {
                 name: "main",
                 current: true,
@@ -2541,13 +2803,13 @@ describe("ChatView timeline estimator parity (full app)", () => {
         ),
       },
       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,
@@ -2637,13 +2899,13 @@ describe("ChatView timeline estimator parity (full app)", () => {
       viewport: DEFAULT_VIEWPORT,
       snapshot: snapshotWithTwoThreads,
       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,
@@ -2897,13 +3159,13 @@ describe("ChatView timeline estimator parity (full app)", () => {
       snapshot: createDraftOnlySnapshot(),
       initialPath: `/draft/${activeDraftId}`,
       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,
@@ -3022,13 +3284,13 @@ describe("ChatView timeline estimator parity (full app)", () => {
       snapshot: createDraftOnlySnapshot(),
       initialPath: `/draft/${draftId}`,
       resolveRpc: (body) => {
-        if (body._tag === WS_METHODS.gitListBranches) {
+        if (body._tag === WS_METHODS.vcsListRefs) {
           return {
             isRepo: true,
-            hasOriginRemote: true,
+            hasPrimaryRemote: true,
             nextCursor: null,
             totalCount: branches.length,
-            branches,
+            refs: branches,
           };
         }
         return undefined;
@@ -3046,8 +3308,8 @@ describe("ChatView timeline estimator parity (full app)", () => {
       branchButton.click();
 
       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.",
       );
 
       const popup = await waitForElement(
@@ -3777,16 +4039,16 @@ describe("ChatView timeline estimator parity (full app)", () => {
   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,
-          },
-        },
+        [ProviderInstanceId.make("codex")]: createModelSelection(
+          ProviderInstanceId.make("codex"),
+          "gpt-5.3-codex",
+          [
+            { id: "reasoningEffort", value: "medium" },
+            { id: "fastMode", value: true },
+          ],
+        ),
       },
-      stickyActiveProvider: "codex",
+      stickyActiveProvider: ProviderInstanceId.make("codex"),
     });
 
     const mounted = await mountChatView({
@@ -3810,14 +4072,16 @@ describe("ChatView timeline estimator parity (full app)", () => {
       );
       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: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5.3-codex",
-            options: {
-              fastMode: true,
-            },
+            options: expect.arrayContaining([{ id: "fastMode", value: true }]),
           },
         },
         activeProvider: "codex",
@@ -3830,16 +4094,16 @@ describe("ChatView timeline estimator parity (full app)", () => {
   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,
-          },
-        },
+        [ProviderInstanceId.make("claudeAgent")]: createModelSelection(
+          ProviderInstanceId.make("claudeAgent"),
+          "claude-opus-4-6",
+          [
+            { id: "effort", value: "max" },
+            { id: "fastMode", value: true },
+          ],
+        ),
       },
-      stickyActiveProvider: "claudeAgent",
+      stickyActiveProvider: ProviderInstanceId.make("claudeAgent"),
     });
 
     const mounted = await mountChatView({
@@ -3865,14 +4129,14 @@ describe("ChatView timeline estimator parity (full app)", () => {
 
       expect(composerDraftFor(newDraftId)).toMatchObject({
         modelSelectionByProvider: {
-          claudeAgent: {
-            provider: "claudeAgent",
-            model: "claude-opus-4-6",
-            options: {
-              effort: "max",
-              fastMode: true,
-            },
-          },
+          claudeAgent: createModelSelection(
+            ProviderInstanceId.make("claudeAgent"),
+            "claude-opus-4-6",
+            [
+              { id: "effort", value: "max" },
+              { id: "fastMode", value: true },
+            ],
+          ),
         },
         activeProvider: "claudeAgent",
       });
@@ -3912,16 +4176,16 @@ describe("ChatView timeline estimator parity (full app)", () => {
   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,
-          },
-        },
+        [ProviderInstanceId.make("codex")]: createModelSelection(
+          ProviderInstanceId.make("codex"),
+          "gpt-5.3-codex",
+          [
+            { id: "reasoningEffort", value: "medium" },
+            { id: "fastMode", value: true },
+          ],
+        ),
       },
-      stickyActiveProvider: "codex",
+      stickyActiveProvider: ProviderInstanceId.make("codex"),
     });
 
     const mounted = await mountChatView({
@@ -3945,27 +4209,27 @@ describe("ChatView timeline estimator parity (full app)", () => {
       );
       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: {
-            provider: "codex",
+            instanceId: ProviderInstanceId.make("codex"),
             model: "gpt-5.3-codex",
-            options: {
-              fastMode: true,
-            },
+            options: expect.arrayContaining([{ id: "fastMode", value: true }]),
           },
         },
         activeProvider: "codex",
       });
 
-      useComposerDraftStore.getState().setModelSelection(draftId, {
-        provider: "codex",
-        model: "gpt-5.4",
-        options: {
-          reasoningEffort: "low",
-          fastMode: true,
-        },
-      });
+      useComposerDraftStore.getState().setModelSelection(
+        draftId,
+        createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+          { id: "reasoningEffort", value: "low" },
+          { id: "fastMode", value: true },
+        ]),
+      );
 
       await newThreadButton.click();
 
@@ -3976,14 +4240,10 @@ describe("ChatView timeline estimator parity (full app)", () => {
       );
       expect(composerDraftFor(draftId)).toMatchObject({
         modelSelectionByProvider: {
-          codex: {
-            provider: "codex",
-            model: "gpt-5.4",
-            options: {
-              reasoningEffort: "low",
-              fastMode: true,
-            },
-          },
+          codex: createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+            { id: "reasoningEffort", value: "low" },
+            { id: "fastMode", value: true },
+          ]),
         },
         activeProvider: "codex",
       });
@@ -4134,8 +4394,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
     });
 
     try {
-      await waitForServerConfigToApply();
-      await waitForCommandPaletteShortcutLabel();
+      await Promise.all([waitForServerConfigToApply(), waitForCommandPaletteShortcutLabel()]);
       const palette = page.getByTestId("command-palette");
       await openCommandPaletteFromTrigger();
 
@@ -4187,8 +4446,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
     });
 
     try {
-      await waitForServerConfigToApply();
-      await waitForCommandPaletteShortcutLabel();
+      await Promise.all([waitForServerConfigToApply(), waitForCommandPaletteShortcutLabel()]);
       const palette = page.getByTestId("command-palette");
       await openCommandPaletteFromTrigger();
 
@@ -4261,13 +4519,13 @@ describe("ChatView timeline estimator parity (full app)", () => {
     });
 
     try {
-      await waitForServerConfigToApply();
-      await waitForCommandPaletteShortcutLabel();
+      await Promise.all([waitForServerConfigToApply(), waitForCommandPaletteShortcutLabel()]);
       const palette = page.getByTestId("command-palette");
       await openCommandPaletteFromTrigger();
 
       await expect.element(palette).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/");
@@ -4314,6 +4572,126 @@ describe("ChatView timeline estimator parity (full app)", () => {
     }
   });
 
+  it("shows clone destination controls after resolving an add project repository", async () => {
+    const mounted = await mountChatView({
+      viewport: DEFAULT_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        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 {
+      await Promise.all([waitForServerConfigToApply(), waitForCommandPaletteShortcutLabel()]);
+      const palette = page.getByTestId("command-palette");
+      await openCommandPaletteFromTrigger();
+
+      await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Add project", { exact: true }).click();
+      await palette.getByText("GitHub repository", { exact: true }).click();
+
+      const repositoryInput = await waitForCommandPaletteInput(
+        "Enter GitHub repository (owner/repo)",
+      );
+      await page.getByPlaceholder("Enter GitHub repository (owner/repo)").fill("t3-oss/t3-env");
+      await dispatchInputKey(repositoryInput, { key: "Enter" });
+
+      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 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 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("opens add project browse mode from the sidebar add button", async () => {
     const mounted = await mountChatView({
       viewport: DEFAULT_VIEWPORT,
@@ -4340,6 +4718,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
 
       const palette = page.getByTestId("command-palette");
       await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Local folder", { exact: true }).click();
 
       const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
       await expect.element(browseInput).toHaveValue("~/");
@@ -4402,6 +4781,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
 
       const palette = page.getByTestId("command-palette");
       await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Local folder", { exact: true }).click();
 
       const browseInput = await waitForCommandPaletteInput(ADD_PROJECT_SUBMENU_PLACEHOLDER);
       await expect.element(browseInput).toHaveValue("~/Development/");
@@ -4461,6 +4841,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
       await page.getByTestId("sidebar-add-project-trigger").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");
 
@@ -4540,6 +4921,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
       await page.getByTestId("sidebar-add-project-trigger").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/");
 
@@ -4671,6 +5053,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
         .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/");
@@ -4764,6 +5147,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
 
       const palette = page.getByTestId("command-palette");
       await expect.element(palette).toBeInTheDocument();
+      await palette.getByText("Local folder", { exact: true }).click();
       const browseInput = palette.getByPlaceholder(ADD_PROJECT_SUBMENU_PLACEHOLDER);
       await browseInput.fill("~/Applications/access");
 
@@ -4881,6 +5265,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
 
       await expect.element(palette).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/");
@@ -5452,7 +5837,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",
       }),
@@ -5482,7 +5870,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",
       }),
@@ -5606,14 +5997,17 @@ describe("ChatView timeline estimator parity (full app)", () => {
         projects: snapshot.projects.map((project) =>
           project.id === PROJECT_ID
             ? Object.assign({}, project, {
-                defaultModelSelection: { provider: "codex", model: "gpt-5.4" },
+                defaultModelSelection: {
+                  instanceId: ProviderInstanceId.make("codex"),
+                  model: "gpt-5.4",
+                },
               })
             : project,
         ),
         threads: snapshot.threads.map((thread) =>
           thread.id === THREAD_ID
             ? Object.assign({}, thread, {
-                modelSelection: { provider: "codex", model: "gpt-5.4" },
+                modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
               })
             : thread,
         ),
@@ -5664,43 +6058,36 @@ describe("ChatView timeline estimator parity (full app)", () => {
           providers: [
             {
               ...nextFixture.serverConfig.providers[0]!,
-              provider: "codex",
               models: [
                 {
                   slug: "gpt-5.1-codex-max",
                   name: "GPT-5.1 Codex Max",
                   isCustom: false,
-                  capabilities: {
-                    supportsFastMode: true,
-                    supportsThinkingToggle: false,
-                    reasoningEffortLevels: [],
-                    promptInjectedEffortLevels: [],
-                    contextWindowOptions: [],
-                  },
+                  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: {
-                    supportsFastMode: true,
-                    supportsThinkingToggle: false,
-                    reasoningEffortLevels: [],
-                    promptInjectedEffortLevels: [],
-                    contextWindowOptions: [],
-                  },
+                  capabilities: createModelCapabilities({
+                    optionDescriptors: [
+                      { id: "fastMode", label: "Fast Mode", type: "boolean" as const },
+                    ],
+                  }),
                 },
                 {
                   slug: "gpt-5.4",
                   name: "GPT-5.4",
                   isCustom: false,
-                  capabilities: {
-                    supportsFastMode: true,
-                    supportsThinkingToggle: false,
-                    reasoningEffortLevels: [],
-                    promptInjectedEffortLevels: [],
-                    contextWindowOptions: [],
-                  },
+                  capabilities: createModelCapabilities({
+                    optionDescriptors: [
+                      { id: "fastMode", label: "Fast Mode", type: "boolean" as const },
+                    ],
+                  }),
                 },
               ],
             },
diff --git a/apps/web/src/components/ChatView.logic.test.ts b/apps/web/src/components/ChatView.logic.test.ts
index 08266e22a38..fecaeddafa2 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";
@@ -220,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,
@@ -253,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",
@@ -452,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",
@@ -466,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,
@@ -503,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,
@@ -549,7 +556,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,
@@ -592,7 +599,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,
@@ -635,7 +642,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,
@@ -685,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 1c72f9a5a35..417313ef2c1 100644
--- a/apps/web/src/components/ChatView.logic.ts
+++ b/apps/web/src/components/ChatView.logic.ts
@@ -1,16 +1,15 @@
 import {
   type EnvironmentId,
+  isProviderDriverKind,
   ProjectId,
   type ModelSelection,
-  type OrchestrationThreadActivity,
-  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 { type ComposerImageAttachment, type DraftThreadState } from "../composerDraftStore";
-import { deriveWorkLogEntries, type WorkLogEntry } from "../session-logic";
 import { Schema } from "effect";
 import { selectThreadByRef, useStore } from "../store";
 import {
@@ -181,30 +180,6 @@ export function cloneComposerImageForRetry(
   }
 }
 
-/**
- * Resolve which provider the health banner should reflect before a session
- * starts. Once a session is active its provider takes precedence; otherwise
- * fall back to the user's currently selected draft provider.
- */
-export function resolveProviderHealthBannerProvider(opts: {
-  sessionProvider: ProviderKind | null;
-  selectedProvider: ProviderKind;
-}): ProviderKind {
-  return opts.sessionProvider ?? opts.selectedProvider;
-}
-
-/**
- * Derive work-log entries that keep completed tool calls from previous turns
- * visible while the user is composing a new message. Passing `undefined` for
- * the turn-id filter causes `deriveWorkLogEntries` to include all activities
- * rather than scoping to only the latest turn.
- */
-export function deriveVisibleThreadWorkLogEntries(
-  activities: ReadonlyArray<OrchestrationThreadActivity>,
-): WorkLogEntry[] {
-  return deriveWorkLogEntries(activities, undefined);
-}
-
 export function deriveComposerSendState(options: {
   prompt: string;
   imageCount: number;
@@ -252,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(
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 535c0d9fcae..9ef221e262a 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -1,14 +1,14 @@
 import {
   type ApprovalRequestId,
-  DEFAULT_MODEL_BY_PROVIDER,
-  type ClaudeAgentEffort,
+  DEFAULT_MODEL,
+  defaultInstanceIdForDriver,
   type EnvironmentId,
   type MessageId,
   type ModelSelection,
   type ProjectScript,
-  type ProviderKind,
   type ProjectId,
   type ProviderApprovalDecision,
+  ProviderInstanceId,
   type ServerProvider,
   type ResolvedKeybindingsConfig,
   type ScopedThreadRef,
@@ -17,6 +17,7 @@ import {
   type KeybindingCommand,
   OrchestrationThreadActivity,
   ProviderInteractionMode,
+  ProviderDriverKind,
   RuntimeMode,
   TerminalOpenInput,
 } from "@t3tools/contracts";
@@ -26,7 +27,11 @@ import {
   scopeProjectRef,
   scopeThreadRef,
 } from "@t3tools/client-runtime";
-import { applyClaudePromptEffortPrefix, createModelSelection } 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 { Debouncer } from "@tanstack/react-pacer";
@@ -99,9 +104,9 @@ 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 {
@@ -112,10 +117,11 @@ 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 { deriveLogicalProjectKeyFromSettings } from "../logicalProject";
 import {
+  reconnectSavedEnvironment,
   useSavedEnvironmentRegistryStore,
   useSavedEnvironmentRuntimeStore,
 } from "../environments/runtime";
@@ -143,6 +149,7 @@ 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,
@@ -175,6 +182,13 @@ import {
 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).]";
@@ -182,6 +196,11 @@ const EMPTY_ACTIVITIES: OrchestrationThreadActivity[] = [];
 const EMPTY_PROPOSED_PLANS: Thread["proposedPlans"] = [];
 const EMPTY_PROVIDERS: ServerProvider[] = [];
 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">;
 
@@ -299,17 +318,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 ClaudeAgentEffort | 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;
@@ -615,6 +632,7 @@ export default function ChatView(props: ChatViewProps) {
     (store) => store.setStickyModelSelection,
   );
   const timestampFormat = settings.timestampFormat;
+  const autoOpenPlanSidebar = settings.autoOpenPlanSidebar;
   const navigate = useNavigate();
   const rawSearch = useSearch({
     strict: false,
@@ -775,8 +793,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,
           )
@@ -851,6 +869,78 @@ export default function ChatView(props: ChatViewProps) {
   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((settings) => ({
     sidebarProjectGroupingMode: settings.sidebarProjectGroupingMode,
     sidebarProjectGroupingOverrides: settings.sidebarProjectGroupingOverrides,
@@ -1017,7 +1107,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,
@@ -1029,7 +1122,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,
@@ -1046,12 +1141,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(
@@ -1423,10 +1632,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;
@@ -1855,11 +2078,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],
@@ -1941,7 +2166,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))
       ) {
@@ -2007,6 +2232,7 @@ export default function ChatView(props: ChatViewProps) {
       planSidebarOpenOnNextThreadRef.current = false;
       setPlanSidebarOpen(true);
     } else {
+      planSidebarOpenOnNextThreadRef.current = false;
       setPlanSidebarOpen(false);
     }
     planSidebarDismissedForTurnRef.current = null;
@@ -2015,6 +2241,7 @@ export default function ChatView(props: ChatViewProps) {
   // 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;
@@ -2022,7 +2249,13 @@ export default function ChatView(props: ChatViewProps) {
     const turnKey = activePlan.turnId ?? sidebarProposedPlan?.turnId ?? "__dismissed__";
     if (planSidebarDismissedForTurnRef.current === turnKey) return;
     setPlanSidebarOpen(true);
-  }, [activePlan, activeLatestTurn?.turnId, planSidebarOpen, sidebarProposedPlan?.turnId]);
+  }, [
+    activePlan,
+    activeLatestTurn?.turnId,
+    autoOpenPlanSidebar,
+    planSidebarOpen,
+    sidebarProposedPlan?.turnId,
+  ]);
 
   useEffect(() => {
     setIsRevertingCheckpoint(false);
@@ -2321,6 +2554,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;
@@ -2356,6 +2596,8 @@ export default function ChatView(props: ChatViewProps) {
     },
     [
       activeThread,
+      activeEnvironmentUnavailable,
+      activeEnvironmentUnavailableLabel,
       environmentId,
       isConnecting,
       isRevertingCheckpoint,
@@ -2368,7 +2610,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;
@@ -2426,11 +2676,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;
     }
@@ -2512,11 +2764,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);
@@ -2543,10 +2797,8 @@ export default function ChatView(props: ChatViewProps) {
       }
       const title = truncate(titleSeed);
       const threadCreateModelSelection = createModelSelection(
-        ctxSelectedProvider,
-        ctxSelectedModel ||
-          activeProject.defaultModelSelection?.model ||
-          DEFAULT_MODEL_BY_PROVIDER.codex,
+        ctxSelectedModelSelection.instanceId,
+        ctxSelectedModel || activeProject.defaultModelSelection?.model || DEFAULT_MODEL,
         ctxSelectedModelSelection.options,
       );
 
@@ -2943,7 +3195,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);
         }
@@ -2972,6 +3224,7 @@ export default function ChatView(props: ChatViewProps) {
       runtimeMode,
       setComposerDraftInteractionMode,
       setThreadError,
+      autoOpenPlanSidebar,
       environmentId,
     ],
   );
@@ -2986,6 +3239,7 @@ export default function ChatView(props: ChatViewProps) {
       !isServerThread ||
       isSendBusy ||
       isConnecting ||
+      activeEnvironmentUnavailable ||
       sendInFlightRef.current
     ) {
       return;
@@ -3064,8 +3318,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: {
@@ -3082,12 +3336,16 @@ 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);
   }, [
@@ -3096,31 +3354,58 @@ export default function ChatView(props: ChatViewProps) {
     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(
@@ -3215,14 +3500,14 @@ export default function ChatView(props: ChatViewProps) {
       {/* Top bar */}
       <header
         className={cn(
-          "border-b border-border px-3 sm:px-5",
+          "border-b border-border",
           isElectron
             ? cn(
-                "drag-region flex h-[52px] items-center wco:h-[env(titlebar-area-height)]",
+                "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)]",
               )
-            : "py-2 sm:py-3",
+            : "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
@@ -3308,103 +3593,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}
-              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>
-
-          {isGitRepo && (
-            <BranchToolbar
-              environmentId={activeThread.environmentId}
-              threadId={activeThread.id}
-              {...(routeKind === "draft" && draftId ? { draftId } : {})}
-              onEnvModeChange={onEnvModeChange}
-              {...(canOverrideServerThreadEnvMode ? { effectiveEnvModeOverride: envMode } : {})}
-              {...(canOverrideServerThreadEnvMode
-                ? {
-                    activeThreadBranchOverride: activeThreadBranch,
-                    onActiveThreadBranchOverrideChange: setPendingServerThreadBranch,
+          <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
+                  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}
+                  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
                   }
-                : {})}
-              envLocked={envLocked}
-              onComposerFocusRequest={scheduleComposerFocus}
-              {...(canCheckoutPullRequestIntoThread
-                ? { onCheckoutPullRequestRequest: openPullRequestDialog }
-                : {})}
-              {...(hasMultipleEnvironments
-                ? {
-                    availableEnvironments: logicalProjectEnvironments,
-                    onEnvironmentChange,
+                  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>
+
           {pullRequestDialogState ? (
             <PullRequestThreadDialog
               key={pullRequestDialogState.key}
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 450f678dd5c..3f4997e215c 100644
--- a/apps/web/src/components/CommandPalette.logic.ts
+++ b/apps/web/src/components/CommandPalette.logic.ts
@@ -17,6 +17,7 @@ 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). */
diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index a9f9f8007cf..ab29afe36d0 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -2,13 +2,18 @@
 
 import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime";
 import {
-  DEFAULT_MODEL_BY_PROVIDER,
+  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 { Option } from "effect";
 import {
   ArrowDownIcon,
   ArrowLeftIcon,
@@ -16,6 +21,7 @@ import {
   CornerLeftUpIcon,
   FolderIcon,
   FolderPlusIcon,
+  LinkIcon,
   MessageSquareIcon,
   SettingsIcon,
   SquarePenIcon,
@@ -24,6 +30,7 @@ import {
   useCallback,
   useDeferredValue,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -41,6 +48,10 @@ import {
 import { useHandleNewThread } from "../hooks/useHandleNewThread";
 import { useSettings } from "../hooks/useSettings";
 import { readLocalApi } from "../localApi";
+import {
+  getSourceControlDiscoverySnapshot,
+  refreshSourceControlDiscovery,
+} from "../lib/sourceControlDiscoveryState";
 import {
   startNewThreadInProjectFromContext,
   startNewThreadFromContext,
@@ -88,6 +99,7 @@ import {
 } 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";
@@ -103,6 +115,7 @@ import {
 import { Button } from "./ui/button";
 import { Kbd, KbdGroup } from "./ui/kbd";
 import { stackedThreadToast, toastManager } from "./ui/toast";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
 import { ComposerHandleContext, useComposerHandleContext } from "../composerHandleContext";
 import type { ChatComposerHandle } from "./chat/ChatComposer";
 
@@ -138,6 +151,181 @@ interface AddProjectEnvironmentOption {
   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);
@@ -228,6 +416,9 @@ function OpenCommandPaletteDialog() {
     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);
@@ -296,7 +487,10 @@ function OpenCommandPaletteDialog() {
           : null;
     return getEnvironmentBrowsePlatform(os);
   }, [browseEnvironmentId, primaryEnvironmentId, savedEnvironmentRuntimeById]);
-  const isBrowsing = isFilesystemBrowseQuery(query, browseEnvironmentPlatform);
+  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 => {
@@ -542,6 +736,7 @@ function OpenCommandPaletteDialog() {
   }
 
   function popView(): void {
+    setAddProjectCloneFlow(null);
     if (viewStack.length <= 1) {
       setAddProjectEnvironmentId(null);
     }
@@ -561,6 +756,7 @@ function OpenCommandPaletteDialog() {
   const startAddProjectBrowse = useCallback(
     (environmentId: EnvironmentId): void => {
       setAddProjectEnvironmentId(environmentId);
+      setAddProjectCloneFlow(null);
       pushPaletteView({
         addonIcon: <FolderPlusIcon className={ADDON_ICON_CLASS} />,
         groups: [],
@@ -570,6 +766,158 @@ function OpenCommandPaletteDialog() {
     [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",
@@ -580,7 +928,7 @@ function OpenCommandPaletteDialog() {
       icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
       keepOpen: true,
       run: async () => {
-        startAddProjectBrowse(option.environmentId);
+        startAddProjectSourceSelection(option.environmentId);
       },
     }),
   );
@@ -617,15 +965,15 @@ function OpenCommandPaletteDialog() {
       return;
     }
 
-    startAddProjectBrowse(environmentId);
+    void startAddProjectSourceSelection(environmentId);
   }, [
     addProjectEnvironmentGroups,
     addProjectEnvironmentOptions.length,
     defaultAddProjectEnvironmentId,
-    startAddProjectBrowse,
+    startAddProjectSourceSelection,
   ]);
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     if (openIntent?.kind !== "add-project") {
       return;
     }
@@ -675,29 +1023,34 @@ function OpenCommandPaletteDialog() {
     });
   }
 
-  if (addProjectEnvironmentOptions.length > 1) {
-    actionItems.push({
-      kind: "submenu",
-      value: "action:add-project",
-      searchTerms: ["add project", "folder", "directory", "browse", "environment"],
-      title: "Add project",
-      icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
-      addonIcon: <FolderPlusIcon className={ADDON_ICON_CLASS} />,
-      groups: addProjectEnvironmentGroups,
-    });
-  } else {
-    actionItems.push({
-      kind: "action",
-      value: "action:add-project",
-      searchTerms: ["add project", "folder", "directory", "browse"],
-      title: "Add project",
-      icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
-      keepOpen: true,
-      run: async () => {
-        openAddProjectFlow();
-      },
-    });
-  }
+  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",
@@ -788,8 +1141,8 @@ function OpenCommandPaletteDialog() {
           workspaceRoot: cwd,
           createWorkspaceRootIfMissing: true,
           defaultModelSelection: {
-            provider: "codex",
-            model: DEFAULT_MODEL_BY_PROVIDER.codex,
+            instanceId: ProviderInstanceId.make("codex"),
+            model: DEFAULT_MODEL,
           },
           createdAt: new Date().toISOString(),
         });
@@ -821,6 +1174,137 @@ function OpenCommandPaletteDialog() {
     ],
   );
 
+  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);
@@ -859,13 +1343,38 @@ function OpenCommandPaletteDialog() {
     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;
+    }
 
-  let displayedGroups = filteredGroups;
-  if (isBrowsing) {
+    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 = getCommandPaletteInputPlaceholder(paletteMode);
+  const inputPlaceholder =
+    remoteProjectInputPlaceholder(addProjectCloneFlow) ??
+    getCommandPaletteInputPlaceholder(paletteMode);
   const isSubmenu = paletteMode === "submenu" || paletteMode === "submenu-browse";
   const hasHighlightedBrowseItem = highlightedItemValue?.startsWith("browse:") ?? false;
   const canSubmitBrowsePath = isBrowsing && !relativePathNeedsActiveProject;
@@ -877,8 +1386,25 @@ function OpenCommandPaletteDialog() {
     (hasTrailingPathSeparator(query) ? !browseResult : exactBrowseEntry === null);
   const useMetaForMod = isMacPlatform(navigator.platform);
   const submitModifierLabel = useMetaForMod ? "\u2318" : "Ctrl";
-  const submitActionLabel = willCreateProjectPath ? "Create & Add" : "Add";
+  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 &&
@@ -916,6 +1442,12 @@ function OpenCommandPaletteDialog() {
   }
 
   function handleKeyDown(event: KeyboardEvent<HTMLInputElement>): void {
+    if (addProjectCloneFlow?.step === "repository" && event.key === "Enter") {
+      event.preventDefault();
+      void submitAddProjectCloneFlow();
+      return;
+    }
+
     const shouldSubmitBrowsePath =
       canSubmitBrowsePath &&
       event.key === "Enter" &&
@@ -923,7 +1455,11 @@ function OpenCommandPaletteDialog() {
 
     if (shouldSubmitBrowsePath) {
       event.preventDefault();
-      void handleAddProject(resolvedAddProjectPath);
+      if (isCloneDestinationStep) {
+        void submitAddProjectCloneFlow(resolvedAddProjectPath);
+      } else {
+        void handleAddProject(resolvedAddProjectPath);
+      }
       return;
     }
 
@@ -934,6 +1470,10 @@ function OpenCommandPaletteDialog() {
   }
 
   function executeItem(item: CommandPaletteActionItem | CommandPaletteSubmenuItem): void {
+    if (item.disabled) {
+      return;
+    }
+
     if (item.kind === "submenu") {
       pushView(item);
       return;
@@ -995,11 +1535,14 @@ function OpenCommandPaletteDialog() {
         composerHandleRef?.current?.focusAtEnd();
         return false;
       }}
+      onBackdropPointerDown={() => {
+        setOpen(false);
+      }}
     >
       <Command
-        key={`${viewStack.length}-${browseGeneration}-${isBrowsing}`}
+        key={`${viewStack.length}-${browseGeneration}-${isBrowsing}-${addProjectCloneFlow?.step ?? "none"}`}
         aria-label="Command palette"
-        autoHighlight={isBrowsing ? false : "always"}
+        autoHighlight={isBrowsing || isRemoteProjectCloneFlow ? false : "always"}
         mode="none"
         onItemHighlighted={(value) => {
           setHighlightedItemValue(typeof value === "string" ? value : null);
@@ -1009,7 +1552,15 @@ function OpenCommandPaletteDialog() {
       >
         <div className="relative">
           <CommandInput
-            className={isBrowsing ? (willCreateProjectPath ? "pe-36" : "pe-16") : undefined}
+            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
@@ -1034,17 +1585,40 @@ function OpenCommandPaletteDialog() {
                 : {})}
             onKeyDown={handleKeyDown}
           />
-          {isBrowsing ? (
+          {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 end-2.5 top-1/2 pe-1 ps-2 -translate-y-1/2",
+                "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}
+              disabled={
+                relativePathNeedsActiveProject || (isCloneDestinationStep && isRemoteProjectPending)
+              }
               onMouseDown={(event) => {
                 event.preventDefault();
               }}
@@ -1052,11 +1626,17 @@ function OpenCommandPaletteDialog() {
                 if (relativePathNeedsActiveProject) {
                   return;
                 }
-                void handleAddProject(resolvedAddProjectPath);
+                if (isCloneDestinationStep) {
+                  void submitAddProjectCloneFlow(resolvedAddProjectPath);
+                } else {
+                  void handleAddProject(resolvedAddProjectPath);
+                }
               }}
               title={`${submitActionLabel} (${addShortcutLabel})`}
             >
-              <span>{submitActionLabel}</span>
+              <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>
@@ -1064,19 +1644,47 @@ function OpenCommandPaletteDialog() {
           ) : 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}
-            {...(relativePathNeedsActiveProject
-              ? { emptyStateMessage: "Relative paths require an active project." }
-              : willCreateProjectPath
-                ? {
-                    emptyStateMessage: "Press Enter to create this folder and add it as a project.",
-                  }
-                : {})}
+            {...(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">
@@ -1090,7 +1698,14 @@ function OpenCommandPaletteDialog() {
               </Kbd>
               <span className={cn("text-muted-foreground/80")}>Navigate</span>
             </KbdGroup>
-            {!canSubmitBrowsePath || hasHighlightedBrowseItem ? (
+            {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>
diff --git a/apps/web/src/components/CommandPaletteResults.tsx b/apps/web/src/components/CommandPaletteResults.tsx
index 8cdf0694a08..4ad08db0824 100644
--- a/apps/web/src/components/CommandPaletteResults.tsx
+++ b/apps/web/src/components/CommandPaletteResults.tsx
@@ -43,15 +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}
-                isActive={props.highlightedItemValue === item.value}
-                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>
       ))}
@@ -59,6 +63,33 @@ 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;
@@ -89,7 +120,6 @@ function CommandPaletteResultRow(props: {
           <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>
-            {props.item.titleTrailingContent}
           </span>
           <span className="truncate text-muted-foreground/70 text-xs">
             {props.item.description}
@@ -99,9 +129,9 @@ function CommandPaletteResultRow(props: {
         <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>
-          {props.item.titleTrailingContent}
         </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 8113099638e..c9696b0c737 100644
--- a/apps/web/src/components/ComposerPromptEditor.tsx
+++ b/apps/web/src/components/ComposerPromptEditor.tsx
@@ -152,10 +152,7 @@ function ComposerMentionDecorator(props: { path: string }) {
   return (
     <Tooltip>
       <TooltipTrigger render={chip} />
-      <TooltipPopup
-        side="top"
-        className="max-w-[30rem] whitespace-normal leading-tight wrap-anywhere"
-      >
+      <TooltipPopup side="top" className="max-w-120 whitespace-normal leading-tight wrap-anywhere">
         {props.path}
       </TooltipPopup>
     </Tooltip>
@@ -275,7 +272,7 @@ 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>
@@ -1493,7 +1490,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);
       });
@@ -1624,7 +1621,7 @@ function ComposerPromptEditorInner({
           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-[200px] 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"
@@ -1635,7 +1632,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>
             )
diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index b8f44459f72..3d2bb8d7b56 100644
--- a/apps/web/src/components/DiffPanel.tsx
+++ b/apps/web/src/components/DiffPanel.tsx
@@ -8,6 +8,7 @@ import {
   ChevronLeftIcon,
   ChevronRightIcon,
   Columns2Icon,
+  PilcrowIcon,
   Rows3Icon,
   TextWrapIcon,
 } from "lucide-react";
@@ -173,6 +174,7 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
   const { resolvedTheme } = useTheme();
   const [diffRenderMode, setDiffRenderMode] = useState<DiffRenderMode>("stacked");
   const [diffWordWrap, setDiffWordWrap] = useState(settings.diffWordWrap);
+  const [diffIgnoreWhitespace, setDiffIgnoreWhitespace] = useState(settings.diffIgnoreWhitespace);
   const patchViewportRef = useRef<HTMLDivElement>(null);
   const turnStripRef = useRef<HTMLDivElement>(null);
   const previousDiffOpenRef = useRef(false);
@@ -278,6 +280,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,
     }),
@@ -318,9 +321,10 @@ export default function DiffPanel({ mode = "inline" }: DiffPanelProps) {
   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) {
@@ -552,6 +556,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>
     </>
   );
diff --git a/apps/web/src/components/GitActionsControl.browser.tsx b/apps/web/src/components/GitActionsControl.browser.tsx
index 24af3bed146..a0e25787413 100644
--- a/apps/web/src/components/GitActionsControl.browser.tsx
+++ b/apps/web/src/components/GitActionsControl.browser.tsx
@@ -100,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", () => ({
@@ -113,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 c6a50b82c27..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,35 +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 branch back to a temporary worktree branch", () => {
+  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({ branch: "t3code/bda76797" }),
+      gitStatus: status({ refName: "t3code/bda76797" }),
     });
 
     assert.equal(update, null);
@@ -1032,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 e4e611fb87c..3f6bae61cdd 100644
--- a/apps/web/src/components/GitActionsControl.logic.ts
+++ b/apps/web/src/components/GitActionsControl.logic.ts
@@ -1,9 +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";
 
@@ -21,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;
 }
@@ -38,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;
@@ -45,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") {
@@ -77,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);
@@ -101,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",
@@ -126,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",
@@ -143,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." };
@@ -161,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",
@@ -193,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",
@@ -215,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",
@@ -233,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.",
@@ -249,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",
@@ -266,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 {
@@ -279,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" ||
@@ -294,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}`,
     };
@@ -315,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}`,
   };
 }
 
@@ -341,31 +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.branch) {
+  if (input.threadBranch === input.gitStatus.refName) {
     return null;
   }
 
   if (
     input.threadBranch !== null &&
-    input.gitStatus.branch !== null &&
+    input.gitStatus.refName !== null &&
     !isTemporaryWorktreeBranch(input.threadBranch) &&
-    isTemporaryWorktreeBranch(input.gitStatus.branch)
+    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 31342d8406b..f8801f98d29 100644
--- a/apps/web/src/components/GitActionsControl.tsx
+++ b/apps/web/src/components/GitActionsControl.tsx
@@ -3,13 +3,34 @@ import type {
   GitActionProgressEvent,
   GitRunStackedActionResult,
   GitStackedAction,
-  GitStatusResult,
-  ProviderKind,
+  SourceControlCloneProtocol,
+  SourceControlProviderDiscoveryItem,
+  SourceControlProviderKind,
+  SourceControlPublishRepositoryResult,
+  SourceControlRepositoryVisibility,
+  VcsStatusResult,
 } from "@t3tools/contracts";
+import type { ProviderKind } from "../providerKind";
 import { useIsMutating, useMutation, useQueryClient } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import { Option } from "effect";
 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,
@@ -23,7 +44,8 @@ import {
   resolveQuickAction,
   resolveThreadBranchUpdate,
 } from "./GitActionsControl.logic";
-import { resolveGitTextGenerationModelSelection, useAppSettings } from "~/appSettings";
+import { AnimatedHeight } from "./AnimatedHeight";
+import { useAppSettings } from "~/appSettings";
 import { Button } from "~/components/ui/button";
 import { Checkbox } from "~/components/ui/checkbox";
 import {
@@ -36,24 +58,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 { 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";
 
@@ -74,6 +101,11 @@ interface PendingDefaultBranchAction {
   filePaths?: string[];
 }
 
+type PublishProviderKind = Extract<
+  SourceControlProviderKind,
+  "github" | "gitlab" | "bitbucket" | "azure-devops"
+>;
+
 type GitActionToastId = ReturnType<typeof toastManager.add>;
 
 interface ActiveGitActionProgress {
@@ -93,7 +125,7 @@ interface RunGitActionWithToastInput {
   commitMessage?: string;
   onConfirmed?: () => void;
   skipDefaultBranchPrompt?: boolean;
-  statusOverride?: GitStatusResult | null;
+  statusOverride?: VcsStatusResult | null;
   featureBranch?: boolean;
   progressToastId?: GitActionToastId;
   filePaths?: string[];
@@ -101,6 +133,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;
@@ -125,22 +239,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) {
@@ -151,7 +266,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.";
@@ -159,7 +274,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) {
@@ -169,51 +284,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,
@@ -246,15 +981,9 @@ 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 gitProvider = provider ?? activeServerThread?.modelSelection.provider ?? "codex";
-  const gitModel = model ?? activeServerThread?.modelSelection.model ?? "";
-  const gitTextGenerationModel = resolveGitTextGenerationModelSelection(
-    gitProvider,
-    settings,
-    gitModel,
-  );
   const activeGitActionProgressRef = useRef<ActiveGitActionProgress | null>(null);
   let runGitActionWithToast: (input: RunGitActionWithToastInput) => Promise<void>;
 
@@ -336,9 +1065,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 ?? [];
@@ -367,7 +1102,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" &&
@@ -396,18 +1135,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.")
@@ -417,6 +1156,7 @@ export default function GitActionsControl({
         action: pendingDefaultBranchAction.action,
         branchName: pendingDefaultBranchAction.branchName,
         includesCommit: pendingDefaultBranchAction.includesCommit,
+        terminology: changeRequestTerminology,
       })
     : null;
 
@@ -482,7 +1222,7 @@ export default function GitActionsControl({
     if (!prUrl) {
       toastManager.add({
         type: "error",
-        title: "No open PR found.",
+        title: "No open pull request found.",
         data: threadToastData,
       });
       return;
@@ -491,7 +1231,7 @@ export default function GitActionsControl({
       toastManager.add(
         stackedThreadToast({
           type: "error",
-          title: "Unable to open PR link",
+          title: "Unable to open pull request link",
           description: err instanceof Error ? err.message : "An error occurred.",
           ...(threadToastData !== undefined ? { data: threadToastData } : {}),
         }),
@@ -511,8 +1251,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 =
@@ -548,6 +1288,7 @@ export default function GitActionsControl({
         hasCustomCommitMessage: !!commitMessage?.trim(),
         hasWorkingTreeChanges: !!actionStatus?.hasWorkingTreeChanges,
         featureBranch,
+        terminology: changeRequestTerminology,
         shouldPushBeforePr:
           action === "create_pr" &&
           (!actionStatus?.hasUpstream || (actionStatus?.aheadCount ?? 0) > 0),
@@ -778,6 +1519,10 @@ export default function GitActionsControl({
       void openExistingPr();
       return;
     }
+    if (quickAction.kind === "open_publish") {
+      setIsPublishDialogOpen(true);
+      return;
+    }
     if (quickAction.kind === "run_pull") {
       const promise = pullMutation.mutateAsync();
       void toastManager.promise<
@@ -789,8 +1534,8 @@ export default function GitActionsControl({
           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) => ({
@@ -875,6 +1620,8 @@ export default function GitActionsControl({
     [gitCwd, threadToastData],
   );
 
+  const canPublishRepository = isRepo && gitStatusForActions !== null && !hasPrimaryRemote;
+
   if (!gitCwd) return null;
 
   return (
@@ -903,7 +1650,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>
@@ -919,7 +1669,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>
@@ -948,7 +1698,7 @@ export default function GitActionsControl({
                   item,
                   gitStatus: gitStatusForActions,
                   isBusy: isGitActionRunning,
-                  hasOriginRemote,
+                  hasPrimaryRemote,
                 });
                 if (item.disabled && disabledReason) {
                   return (
@@ -959,7 +1709,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>
@@ -978,18 +1731,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 && (
@@ -1027,10 +1792,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>
@@ -1166,7 +1933,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
@@ -1175,6 +1942,13 @@ export default function GitActionsControl({
         </DialogPopup>
       </Dialog>
 
+      <PublishRepositoryDialog
+        open={isPublishDialogOpen}
+        onOpenChange={setIsPublishDialogOpen}
+        environmentId={activeEnvironmentId}
+        gitCwd={gitCwd}
+      />
+
       <Dialog
         open={pendingDefaultBranchAction !== null}
         onOpenChange={(open) => {
@@ -1186,18 +1960,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 62a7043d855..cd583f0c2aa 100644
--- a/apps/web/src/components/Icons.tsx
+++ b/apps/web/src/components/Icons.tsx
@@ -19,6 +19,180 @@ export const GitHubIcon: Icon = (props) => (
   </svg>
 );
 
+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, monochrome: _monochrome, ...props }) => (
   <svg
     {...props}
@@ -61,6 +235,58 @@ export const KiroIcon: Icon = (props) => (
   </svg>
 );
 
+// Editor / IDE icons — restored from the fork for the editor-picker UI.
+// Kept as simple `currentColor`-based marks so they can be tinted via CSS.
+export const WindsurfIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
+    <path d="M3 17.5C3 17.5 7.5 13 12 8.5C16.5 4 21 2 21 2C21 2 19.5 7.5 16 12C12.5 16.5 7 21 7 21L3 17.5Z" />
+    <path
+      d="M3 12C3 12 7 8.5 10.5 5.5C14 2.5 18 1 18 1C18 1 16 5 13 8.5C10 12 6 15.5 6 15.5L3 12Z"
+      opacity="0.6"
+    />
+  </svg>
+);
+
+export const PositronIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 24 24" fill="none">
+    <rect x="2" y="2" width="20" height="20" rx="3" stroke="currentColor" strokeWidth="1.5" />
+    <path d="M7 7h4v10H7V7Z" fill="currentColor" />
+    <circle cx="15.5" cy="12" r="2.5" fill="currentColor" />
+  </svg>
+);
+
+export const SublimeTextIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
+    <path d="M3.854 7.074l16.292-4.96v5.528L3.854 12.6V7.074ZM3.854 11.901l16.292 4.96v5.528L3.854 17.43v-5.529ZM20.146 6.57L3.854 11.53V5.999l16.292-4.96V6.57Z" />
+  </svg>
+);
+
+export const WebStormIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
+    <path d="M2 2h20v20H2V2Zm1.5 1.5v17h17v-17h-17ZM5 5h2v1H5V5Zm0 13h8v1H5v-1Zm2.2-8.5 1.8 5 1.8-5h1.4l1.8 5 1.8-5H17l-2.7 8h-1.2l-1.9-5.3L9.3 17.5H8.1L5.4 9.5h1.8Z" />
+  </svg>
+);
+
+// Simple fork-style IntelliJ mark — distinct from the multi-color
+// `IntelliJIdeaIcon` defined later in this file.
+export const IntelliJIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
+    <path d="M2 2h20v20H2V2Zm1.5 1.5v17h17v-17h-17ZM5 5h2v1H5V5Zm0 13h8v1H5v-1ZM8 9.5h1.5v8H8v-8Z" />
+  </svg>
+);
+
+export const FleetIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
+    <path d="M13 2L4.5 13h5l-1 9L17 11h-5l1-9Z" />
+  </svg>
+);
+
+export const GhosttyIcon: Icon = (props) => (
+  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
+    <path d="M12 2C7.58 2 4 5.58 4 10v8c0 1.1.45 2.1 1.17 2.83L6 22v-2.5c0-.83.67-1.5 1.5-1.5s1.5.67 1.5 1.5V22h2v-2.5c0-.83.67-1.5 1.5-1.5s1.5.67 1.5 1.5V22h2v-2.5c0-.83.67-1.5 1.5-1.5s1.5.67 1.5 1.5V22l.83-.83A3.98 3.98 0 0 0 20 18v-8c0-4.42-3.58-8-8-8Zm-3 10a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3Zm6 0a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3Z" />
+  </svg>
+);
+
 export const VisualStudioCode: Icon = (props) => {
   const id = useId();
   const maskId = `${id}-vscode-a`;
@@ -299,54 +525,6 @@ export const Zed: Icon = (props) => {
   );
 };
 
-export const WindsurfIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
-    <path d="M3 17.5C3 17.5 7.5 13 12 8.5C16.5 4 21 2 21 2C21 2 19.5 7.5 16 12C12.5 16.5 7 21 7 21L3 17.5Z" />
-    <path
-      d="M3 12C3 12 7 8.5 10.5 5.5C14 2.5 18 1 18 1C18 1 16 5 13 8.5C10 12 6 15.5 6 15.5L3 12Z"
-      opacity="0.6"
-    />
-  </svg>
-);
-
-export const PositronIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 24 24" fill="none">
-    <rect x="2" y="2" width="20" height="20" rx="3" stroke="currentColor" strokeWidth="1.5" />
-    <path d="M7 7h4v10H7V7Z" fill="currentColor" />
-    <circle cx="15.5" cy="12" r="2.5" fill="currentColor" />
-  </svg>
-);
-
-export const SublimeTextIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
-    <path d="M3.854 7.074l16.292-4.96v5.528L3.854 12.6V7.074ZM3.854 11.901l16.292 4.96v5.528L3.854 17.43v-5.529ZM20.146 6.57L3.854 11.53V5.999l16.292-4.96V6.57Z" />
-  </svg>
-);
-
-export const WebStormIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
-    <path d="M2 2h20v20H2V2Zm1.5 1.5v17h17v-17h-17ZM5 5h2v1H5V5Zm0 13h8v1H5v-1Zm2.2-8.5 1.8 5 1.8-5h1.4l1.8 5 1.8-5H17l-2.7 8h-1.2l-1.9-5.3L9.3 17.5H8.1L5.4 9.5h1.8Z" />
-  </svg>
-);
-
-export const IntelliJIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
-    <path d="M2 2h20v20H2V2Zm1.5 1.5v17h17v-17h-17ZM5 5h2v1H5V5Zm0 13h8v1H5v-1ZM8 9.5h1.5v8H8v-8Z" />
-  </svg>
-);
-
-export const FleetIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
-    <path d="M13 2L4.5 13h5l-1 9L17 11h-5l1-9Z" />
-  </svg>
-);
-
-export const GhosttyIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 24 24" fill="currentColor">
-    <path d="M12 2C7.58 2 4 5.58 4 10v8c0 1.1.45 2.1 1.17 2.83L6 22v-2.5c0-.83.67-1.5 1.5-1.5s1.5.67 1.5 1.5V22h2v-2.5c0-.83.67-1.5 1.5-1.5s1.5.67 1.5 1.5V22h2v-2.5c0-.83.67-1.5 1.5-1.5s1.5.67 1.5 1.5V22l.83-.83A3.98 3.98 0 0 0 20 18v-8c0-4.42-3.58-8-8-8Zm-3 10a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3Zm6 0a1.5 1.5 0 1 1 0-3 1.5 1.5 0 0 1 0 3Z" />
-  </svg>
-);
-
 export const OpenAI: Icon = ({ className, ...props }) => (
   <svg
     {...props}
@@ -528,27 +706,6 @@ export const Gemini: Icon = ({ monochrome, ...props }) => {
   );
 };
 
-export const AmpIcon: Icon = ({ monochrome, ...props }) => (
-  <svg {...props} viewBox="0 0 28 28" fill="none">
-    <path
-      d="M13.9197 13.61L17.3816 26.566L14.242 27.4049L11.2645 16.2643L0.119926 13.2906L0.957817 10.15L13.9197 13.61Z"
-      fill={monochrome ? "currentColor" : "#F34E3F"}
-    />
-    <path
-      d="M13.7391 16.0892L4.88169 24.9056L2.58872 22.6019L11.4461 13.7865L13.7391 16.0892Z"
-      fill={monochrome ? "currentColor" : "#F34E3F"}
-    />
-    <path
-      d="M18.9386 8.58315L22.4005 21.5392L19.2609 22.3781L16.2833 11.2374L5.13879 8.26381L5.97668 5.12318L18.9386 8.58315Z"
-      fill={monochrome ? "currentColor" : "#F34E3F"}
-    />
-    <path
-      d="M23.9803 3.55632L27.4422 16.5124L24.3025 17.3512L21.325 6.21062L10.1805 3.23698L11.0183 0.0963593L23.9803 3.55632Z"
-      fill={monochrome ? "currentColor" : "#F34E3F"}
-    />
-  </svg>
-);
-
 const ANTIGRAVITY_ICON_DATA_URL =
   "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAAAAXNSR0IArs4c6QAAAERlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAgKADAAQAAAABAAAAgAAAAABIjgR3AAAjOElEQVR4Ae1dCYxkV3W9tfdW3T0z3bMvPcxge2zGy2BjY0MwxEAWEBACihSCEiMUSFCiRJEsRygIiIKySUlYAkmMQSxJQAKi4AQngDcMAe87nsF4xuPxrJ6ll+rqri3n3Pfv71e/f1XP4u7+Zdeb+XXvu+/9999/57z7lv+rOiVnF1ILnNYuvV3aAsW+JJIbbe6yXRpPWyh9XtFnCsZC+ePS42ysSCv7vEq2MbwQZbQp/rSTzrjhY0puVUacPc7mF7lQepj3TBqwVd44e9QWjbMCcbawYqeR7uftBH0hUOLSo7ZonPcdZ2tnb2qrhUBg5nZ5/DRfj57XLs0qFM1j9herjAMuavPjvs428eO+Hm2vdmltwWVBrUDx7S+U7lfcL9O3d7reCgzf/kLpflv5Zfr2lgAzUxwIUZvFo9I/v12an4+6BTvH4i8WGQeEb4vTzWaSbWF6VFo7md3i/jm+LRZkZogDwLeZfq4y7lpWZlNFX0SRKDh+3PRzlWwuK8Nvunm2uMZeyGbpvjwdnRXx8/nxqM44g+V3sc79nNfwuBXfZno76ae10tlClhbVGWfw0yXrbOFnXIObrZ1kmp++UJwX9PNbBcxmcZOt7JaeVNnU2F4lfbvpcZI2Hrx/01mMxam3Cv55fp6mc/2G9XU7wWxxkjbfbvGoZFmp3t6+wtDwim25XO6KdDp9JUyXpFKpMaT143gph6lGo7EX+D5Ur9d/XKlU7jl18sRT09OlGTQKQWQw8ONkNN3icZI2C1q2D6AlmIym+XHqCx4AOr127YZduXz+9wD2r1nBXblwC4AU36jMzn7m0KED94MYdZwRB34rGy+gAMdIplloGIhmMOmDTZufz3Rfpr08KQK/bv2mX0Rv/wLsL/UejiY4pzAFr/DbB5/b/70YIrQiBi9o5DDdl9Q1GIgWp6SNwZdRnfEm0C2+es26rXD3X0KPv4iFdMML0wLwCI9hWPitI4cPPo0SCW4U/GicF16QBATSwOUJpvsyqvvAm65y46axd2ez2c+yoG5YnBaoVqsfeHb/3q+hdJ8EPvi+zkq0JUEGGXyAeQIDbb7d4gY449T1gMfPbNq89eOZTOajsHXDIrYA2votg0PDxYmJU3fAK/BKhpNdNRpvmyeOACzACjGd0sAPgadNwd809knI63mlblj8FsDwesXg4NAmkOA7AQnsoj5uZjNpaRZXaQSwRF9S949YAqDnf6wLflObLkkEJNhZHBwaOHXqxO1neEEfY4kjgA+66bHgb9y05V2ZTPajZ1iBbvYXqAXoCQaKxafHx089EVOkAR2TNGdiJoLLYGCbbqBbHsbDY3T1mq39/cV7mLkblrcFpqYmrjh65PDTqAUngNHDJoE2OWRlzdYEPhMYokSweCix0M/09Q180WXvfi53CxALYuJhF2IV2FhFs1FnYDwkgBksky/NE4S9f926Da+H+7mQJ3XD8rcAsSAmqEmIEXRiaNj5eJquFbcMGvE+LJNJy4drpTP5fOEmL29XTUALEBNig6rMw8yzRWuaIrAMdpLJOBvzptesWbcLsru9yxZKVugPsFGcUDXD0iRra7rJpiHAbscSfWkeIJ0vFH7XMnZlslogwCbECrXzMTS9qdLM7AdmYrDMviT4Baz53+aydD+T1gLEhhihXkYCHz8f27Dq0YxMiJ4UxoeGVmwLz+wqiWyBAKMQsxg8We8wPc4DMJHBMoUkwUTjlS6p+5nUFggwmoddUF+zh9X3CWDAM9F0O4H50njYc0V4Zgcq3P2o46OGLZEaJHWN0xboHXhbTVUOMFK8kGD4MY9h2qTzncBoJovPk1gD7uTZnRb40IxAF3tExlaKbMexoS8txXRKGpW0jJdSsn+iIXvG6/JMqS4lsAFJTS3WKfccYDQPO9Tft6E13O35L4UygwU/c6ij8M2WoVMkX6ZaMSDyhleIvGmHyAUrUjKMOVJ2Ni2pckZSM+gskNXptJycEnnkeF1uOTQrdxyflcmqI0Kn3CvrGWAUYkaTdzALA20kQexbwUxk8E80vePW/688PyXXvzEluzaK5Kvo8eWUVMtpqYEEqfBISQpdfmUhLW8Yyco1xYLcdawin3m2JI+XKjqldk3SEZ/EyPDyJStvcQWfBvMATPBDXDxq8/MnSufdZdCx33x1Rt73K2lZ3ScAPYVx3kGOHTO4eOjcB1Md8XRa6rDVcGQyKbluVY9sL+Tlr56ZkNtOlbXlEnWT7StjQPu5ovgx3rA5ADPaSZbRj5vuF5hYneP3L12bk+vfnpMBbI7yBWv2d2AbAk/w08ioZIC0eAaZ+KpsA3JLb1o+snlI0s+IfK+zSGB4+TKKsc4DzANEwfRPpM5g0sUS+snJ3tVX5OXd7+iVNLZESrMOfPR1RwLchjp/EIBgZxR82OAB6DUaOEgMOAElwmg+LTduGJaT1RNy7+QMiJLQG2+ultWS0j+acyHGdmGwE6K6xa0QxhMbOOHbsiUr7/z1ouT681Kq56XcwCF5mZaCHmXIciovM6kcDidn03mppLNSSWWlClnFM5UqCFHDQbmukJM/Xjck6/IZfdie2AaYq5jh5ePKVD+uuu8B7CTLGI3PFZ9AjUu93t6U/Orbh2TFuh51++zCKdjTerDnu7Gfj8zoBbLqATAR0h7fgMRyEUcWJzVwkhsKnH7JQI/8zuig/PXBE7pnkMAmiFbJwDYco3G0ytwkMHqyH/dP9O2J0kmAS68akPMuK2IdD/et4IMAwT+6OhIACz/n+nFXdPMkQY6gA/A6QeeRwYGxRHXEuYmQAineivXknRNluWt8Ws9NVAM0V+a0MfMngVaEncy46SYtT6IkwR9elZVXv2mF1LJ5mZ1FdclvDOipOiiAQ8d93A5JwJsm+DkcJEAN4JIAuYAA9XQdZKirjSQQ6CREEUz5zZEheWhqRiYx3iS6UeKxi1YZg158YMZ5meOzJsN68dVDsnLzgExV09r76QGUAPQECrsjgXoAWIwAJEEVBCD4tQB46iRAo+kAERp1uXygD/sEffLfJyeT7AXisIvaFLgoAeIyxdmSgTpqwd4/uDInF75mlcxislcB4A0M5O4g3I4AKXiDNNIyONjrs3ARFdwZ3T8m+iBBzREgVQ+J0EjXQhI4L1CTApjzjlVDcvdEqZO8gI9XE55GABqbEvwzFkiLZF3aKL8Ysf2VwzK0gWM/Zu4NzNQBdkMPTPcgObNLKwE4B4D7BwlyJAF6fh5EqOHOqwC7FoBPT0Dw695Bb5DDikAaNXlF/4Dsgie4/dQEvEC7ZlvatohcrV3FmMZDN4Ii5zVF2xXSlHFZIuj9Pf1Z2X7ViHApNwv3X6uDADgaPAISsPenQAybB2SDeUAu8AIVEKFgHgBA16HX01UlgPMC9AQ8qlpmIZuRN64Ylh9OTIFwqESyQ1sMzQP4t9DqhFZ2/9wl1eto/LUvL8qKrcMyXc1JFSBXSQDwug5dSYA4pvUggPMCpAEHhixw483ncQBqDAHuqCkRHAEIOL2AAg8de8QoCxJe4NLikGztOSa7S9O6u7ikN77wxVphNc8eRwArfl5mS0iKTGM83nL5qNTzPTJbceBX61l4ARAARyMgAR2d8wIAHzYlAO4uhxvB86E58NH7awC6RtefIvjuUCJkKiiPcQ4vVRnExOHVg8NKgKS0R5t6tMSyFQH8E3y9zTWWNoljf3GkV1ZfOCLlWk4q6OnVOrxAQIAavQBJQA8AmYJMYS5AAnA+QA9AAjgSzPV+Hfc98EmCRprgo6kCEmD6CB9Sk1cNr5JvHjsqE7Va2wnU0rZM09V87Hw9zNSKAGGGxCrY9l19/grJrxqUchXbtyRBDRIkUA+AeA06vQAJICBAWsGn5CogpTByHoB+7SaAAJXjP72AAx5SQac3qbihBXEdXuAFNvUPy/a+otw3fiLJk8G2EHYsAdJYv63ZuQbuG+4f4FYANg/1AAC/Dt0Ogu/mAZj+2VwAm0M5EAH9G7DzIAkcAZzrB9AZEADAqwcg8KCMDiuYC9AL9KQysmt4RB6YONm2kZOc2JEEoPvvH+mToW2j6P05EAAPcvDgh16ARw06wVcPwGGAc4DAC3A1kCEJ1Im7/QDuBHIJqO4fE7xGPfAA9TnwG41ZLaeRQXnYccA+IbaHq3Lh0GoZPLhPxqscFjovdCQBgICs3DYimaEhmali8wegV2oggHqAvAJfBwlqsDd4EHydCHIe4OYA3AvgW0EcAgA9/mHvn74AXkAnfXDxbuxnr8ehwNMLgAiYRmLzGEdFRvtXyZb+IXn45FEQovMo0JEESOPB/Yod65z7x7iv4JMAetALYHsHh/MAJACmeuYBgk0h0EBXA5hK6BBQhwdo0AtwAqhDQUAAHSQIugOcPZ86iVDHTnoPHh/vGF6rBOi8/u+WwqdT7+RQG+4/P9wrA2NrZAYgzwJc5/4dAWoEHkedB7wAwacH4KErAbh/Lgk5kbNXwV3vhydg71ciYK2PiaA0uEagB8D50On6HREQB/iN2izeKMvJthUbpe/ZJ2W6lqhh4LQw6zgPAPxlYNMqyQyvxNqf7p9HQcf9qrp99nwHfl3dvyOAbnoCdM4BHAG4JMRzg+Af0MbmKPyBEgDPk7n8094PoINe38Ckj+6fPb8Bz6MS84SR4lq8dzgke8c7bxjoOAJwmB3cvh6Pffvx2JfLP/Z8EMCkjf1KAuf+dQ4AwNxKwBEAT/gBJjZ19B+SMBFs4GkfPYBgI0gwERQMBw24eDpK3QeAVD0FTxCSYFZ6erOyZXg9CHAE6afV8ZAvGaGzCIBOmuktSN/YRpnVnu+7/YKSga5fx35IrgTU/Sv4uFVMAFOcDBJ44FxXD6B9H2gEHoAJGOEFAOswAC/gRkrECToPkILunzo3m1KYMI6t2ip3P/soyuT5nRM6igBc/hXwQkZ2dI1UAvdfC3q/Ss/1O/CdB1D3H+wFcB3PIYAeAM/22PUDH8AIgceBLWEgizj2D9QDkARw/xwCeKAsmwPUmY5VwujKLfjmUVFOlk521GqgowjAXtq3Zb00eoYC188JXwETPjcHcJM/BzoJIOoBnBeg+0fXxUECuLcECD5dNocBGKHbEZBAz5kDX8tQz4Bmg1dREtTx2jG8Ss/AWlkztE5OlE6gxM4ZBjqKACnswPWMjeGpXw8mftjoUXdfQI80InD3j0tAgMNZu5KAOm5TPQAJwN7vXg6xl7roCbgSwBpANZIhRW+gPoJeACRQ4kDHqoC67gVwdQCPwKePPXgcvX5kuzx5MO4X23BaQkPnEADuPzuI173Xb5JKFT0eO4AhAXS8tzEfJODyLRj/2Tv1gZD2ZrcEZK/n+M9nAoSZcbAEn84D0Ko6wOUugQ4WWCJiqxD8oSfB0pBDATeLVLIZa7J69HzJ5/4X9eNP/XdG6BgCcPzPr10jqcFRqVYIPlw/x3yAz00ft9530sDXnq/AEzQCBgAD9083TcgZ1BNwCMA1aKpxIse5AIcMfIGE3x5SPXgjSL0Iy9U5AsrlnAAEGFgxJkMDq+XoiX3uHC092R8dQwBusxY2b4UnL0oNBAg3ehT8ZgLosi90+wSeBAhAJPAggev1BMeRwPV9bguTBG5QcJ4AVGH+gAicQGpZBF9JBRl4g1zfiIyMbJMjJ/YGpSYbfNaucwiQz0tu03Zd83Pp5cZ6fPdLXb0RwI374SPgoNcTKAcagAzBdw4f6ClKJEA9mAhS0CvUAiI4b0ALwFdvwIkk5gWBTk/AnUXBN41G1u6UzFN3gGQsMfmhMwgAl5xZsUrSqzbq2K87fOj5c+AHOsd7r+eHwIe91iNApI86uBwpnBfAAMF5ATwPHxo5SnDGQMJwiKAksbhjyIkldNiHR3dIT8+wlErH9VwYEx06hAB4c2f9mDR6V8H1Y4IXuH28C4bxNxj3FXjcDryDAR91/WHvByQc/wmhAW8a4/yauObQ1QBzOiJU9Qyk6fyAebhzSHJw/QAigKj5oY0yiLlAqXQMdpIi2aEzCIDlX3bzBWjuXl3iEXg73ESPM/1m8I0EoetX8AIXDj3AWK0+RJwFMPBbxkqRYFhwBKFl7p8NDcxJLyBYKeQL+ILKuovl0IH7/GITqyefAHDD6f5Byazd7nq/ru2dy2dv53rfPeq1nu9m+44A7KXsocFRLUl98oDUTu2TRukwVnPTSMPInu/HNdbg/YIxyQ6sx44vfkwIkOpQoDmcR1CvwDjZE8wPOECwDJKBqwyqw+suk2zu3zFcufKRIbGhIwiQWb0Zyz/sANL9KwFMBqCHbt8Dn0go8LDBHVf2fVdmf/4/Ujv+pNTLeIULT/GAmAOGYGZyku5ZKbnRi6Sw7ZelZ/PrJYPezMlcSAQU6eYDPM8NC+ol1GtwOODcoCE9q14ufYMbZPz5PYmfBySfAGj0zKYLsZ8ziNZHdZUABD44FHwAaBM9zsYJPiX28yv7bpXyg/8s1aOP4XyATrDV/yOPSscBptUnD8nMxHMy88ydUl53uQzs+qAUNrwaJLDJIUvGeQq+I4FG+WFlYh6Q7RuVIawGxo/t5gmJDmiNJAf0skK/ZDbu1Mne3AOe6JgPsJuWeojD/ZYf+EeZuu1GqR5+EOnondzF80GP3jrTmAePgmf33y0nv/tHMvXYVzAf4I4fZ/puZ0B/Swg6vUENE70q0qqQFayq9UcmMgUZ2vgqPEfCUJXwkGwPwPEfS78UHrU2agSGHsD1fL7dwzGXL3gQfKeTz4gD/Ol7/l7Kj3wJ+TFG65buGSIBItQxdEz86C8xV5iS4sXvAznYXJwkslvz0JkiJK8bvFkQEKxv7SVSwAOi6VP7wbnk9rPk1gxNypDefLFIYQU6MIAF+G6TB7oCTzL44ON28FZv+aGbHPjQ2/Z4d4nWn+z1mChO3vtpmXry6wq9rvkxJJAGulkEIlTpCZCXB3V+QzmDyeQAhgFUuHX5CUhJMAHQcPk+yWzehTZ0j3RtyacPeJQAbm8/7JEAYPZnt4AAn3c9X3vpObYyejQ9wAQ8ysyBu7FH4IAPhwNcg4+L+BN0KnVYABkyvTK4+Ro4H3qN5IbkEkDd/2ZJj5yHyRt7NhpSvQB7P6vtHbr8wncCj/1Upu/9lDRm8ZOf7cb6M8UDxKpPHZHxH/+tVDFJVBKAn+YF2Mf5+4LcKCIJKPkWQR8mknkMAzr/ONNrLlH+5BIADZDZgh8nh/t3z/Kdu3eun8MBScGDYzE8AUAv3/8ZqZ/aC/AX4bYwj6gcfkgmH/oXLC648xesDIC+9v7QA5hHwIOWwU0ysOEKeDBSJJlhEVrqhbhRNC9er0pvuRKF5TDRI/gEO+j90PXBTAA+CTD71C0yu/f7AB95Fi2kpPTkN2Vm/52BFwAJQk8ATpIEJARqp6+cYzVQ3Pp6zB35NxySGZJJAP4A05oLAvePHk7A6f6VBKwyx35K9n7M1sf3yczDX0DL4/WsxQycD8yckknsK9SmTzQNAdw65mHg61AAQy+GgcKKrag7B4zkhWQSAMut7PbXSipXDJd5oevn2I+ephsySoiazGCtXju+Z3FcfxQzeJjZg/fK9O5vcBHYTALGSYTAA/DXQ9J9a/AllmujpSQmnjwCoKek8I59evNV6PUEmwfdOt0+e3xw0P0DjNrh+2V2938E9iVqV8wBph77qlRPPqUk4DAQzglQBSOBeYSBl70Jr7PjjxQkcC6QPAKgATNbr5F0cQMaDJADfL6Fo2/lkASh7pZnZbj+xvTzIAOJsUQBk8zayb0gwZd1QqirAfZ8EkE9gEcCGHOrdkjfxiuRlrxhIFkEQOul+lZK9rzr0M85+QP4dPnB4UgQeAD0/uq+70kF+/aLMutfkEspKe/+T6kcuiccCugFQjLgfJ0QkhScDJ73Njx1xO/Wa+4FC1+yDMkiAJovs/VqyYxcoI/abdLn3uNnVekRnOtvTOHBzSNf0G1f2pc8wOPUy8dlCruOdSxBreeHQ4F5AlSMP2ZVWH8lJoTc1EqWF0gOAdj7e1dIbsdb0aHxPN5cv3kAAs+DYCPvzE+/LtUjjyK6mMu+BWjFCeH+H0j557do1ZQEBB71jHoCKQxKcce7sCTkuwbJCckhAHv/y16Hv02L/XO0Hl2/ewM36PVoVP7Tid/Rh2X28X8DEZa/N/E7gqWHb5bqqWcc6MAWHABH5zaKlBioas+ma6VnA/Y2+IwiISEZBGDvH1gjuZ3vxFyuJ5josWoBCSgJPr3B7ITMPPhP2Jo9BDIkoPqoQ/X53VJ65PPgI18QDQgAqZ6AHkF1PC0sFKW48734QxZ4tyEhc4EEtCDaAuNp7qK3Y+zfAfAR1aUfQWf1Ag9AAiDf7J5vyuy+26Avo+tHrZoC6lXGDuEs3jriKOWWgUYEDAdGAjChsOEa6cMbRzppaCpkeSKnSwDcwiIFuMMMXqLMXYTejy3fOfDRkmxN7fkEH2v+Iw/j7Z6bML3Gmz2JCnD3s5Mydf+n8b7hM24+gPqx0bT34x7c/ABeAN8hHLjkfZJd/N3B08LsdAmwOM1N148NkvwV79cdM53hc52vPd/r/XCzXOuX7/07qU88CzIsb7VjG4NDwdHHpXT/J/FC0XQwD3A5jQgqcc+Z4e1SvOyD2OnsRYbTwin2ki+EcRlbEjeOt27yl71Hshuvcl3FwNchwFw/qogeX37wc1LBa1qJcv1RBDgU7Pm2lB//ivZ4QsueT8n5gHoB1TEh3P5W6cOqYLnD8hEArZK74C2Sf8VvoMc71689X0lg4HMIwLzvp1/DrP9fobEpkxxQX5C1dP9nZWbvrXNDgZEgGAr08TCHgl2/L4XNr8NtcaBYnrA8BMANZ7HkK1z5IX3gw2erDnxKNKKN/Rj3K09/By95/EP4Dv/yNNMZXBVeoFE+IaUffUIqB38yRwIUQfpyo4gPi7g5lOoZkcGrP4xvPe9CwvIsDZeeAAR/6y9Iz2tv1HGfs6S5no/qeOBX998h0z/8BMb/48kc91vxAvOB2vh+mbzrz/ASyQO8QQ2OAEYEDgt4Wji0VYq/8DHJrca7j8vgCVoRgHW14OtmOzuJG8ysu0R6XnODpAfwsIfg63hv63y2FA5OqPZ9X0p3fQTv6h/U+NldcBnPIgmO75bJO/4Uzwvui/UEOifAR2blDim+9qOYHI690CTwsfP1sGFaEYAZYk8IzzxThS4PD3p6rvwDSQ+O6V6/gm+bPNrzWR38AOueb0npzg/jRY+EzvhP9965dMU3kSZvvwEPre7Qs6xRKTkc6EESjF4ifZe8H49CF+W7BHbZeTWPI0CrzK3s8wqNN+Bv7oxdK9m1l4cPetyIjx5P8PnjS3ioMvPA56T0g4/rS5iJXO7F31xrK0lw8mklwcwTX8VQj5+XQW72fpO2Y5gfuw77A9uQcM6TwlZYzbOj1duGeSe0zd0uES4xg+/dSQYPQ/QPLBjwcP/46RW+0VO+71P4/t6tGBr4Pn8cN9tdIMFpuJd66ahM/fAvpAqP0HvpBzAErlMS6JePrer5QcyLRkGAx3H/Zjxn2RZDIwAztctoaSXk40PtMw+gfO3oE9rLU1m86sU7xMy3Pn0MW6jfl5mHbpbaiacc8JhJv+gCSNColaX86FewYfSI9Fx8PX7z4BrsDQ+D6xgKsF9cPXQvCMLvE54T+YkRg2HmYs2fId5GAEuOOym0Yf26H1+NPt8yn5HETVV2fxvf1D2OYeAy3CR+5mViP276AQD/M7e9e243fkbVWZ7MIDb+V/l6+W03SHblyyWDt4VS+SJWOvgG83M/xtB3GHnOvgMQI+/eQuxa2aIEsHwhQ8wA2ajX649mMpmzIwALwKPTyl68xcPXtxk4EPJmCfyLHnx3y/rJe0VbVPFsg2Rwwdrh7MFnOcQIIgp8HJ56WfqauMya6KVpnlqter8lnLXEpCgEXL+te07u7qyrkYgT2Rb8wqkebJdzA5/35GFkuJpksq9r/HRa305qzJTL+J51NyS5BQKMQswWqqtPAJ7knxiNy/g41jPdkOgW8DBqh6Wl6XNX3lBoiOiWxvRGBQHfi/svGrsheS1AbIgRaqZ4BdKv6DycfQ8QzRgtROPTpdLNfsaunpwWCLAx3Fgx003OqywJwEQGyxQXD9OOHcPUVcTWmnpi9yMRLVAKsAmxQq18nZWcFzcPwAQ/xMX1ZKwz69PTpT/0M3f15W8BYkJsUJMoyFa5OEzDOYCfyTL6BTXpRw4fvAsXw5ZVNyShBYgFMUFdmnCKxFlVS6euwTwAI0y0YBmjUhlGpp06eeJDlrkrl7cFiIXX+6NewMfQKhpijd2H0AvYLgTlQke6XJ6e6O3t25/NZt9opXbl0rcA1v03HDt2+Ce4MoHna0WUcUeUCBo3AkTBRxlKDCMC49TpMcyWmpwc3zNQHCym0+lLmaEblrYFqtXqF5878MxNuGoUcCMCQWaaSVbQiECdP6rXBCptIcCBHmezPOmJiVP/VywOrQcJLmDGbliaFqjVat868Oy+P8fVCLABHiWCgW+gmwwrSQIQTAumG8BRyXxmM28gE+Onbh8YKPan05muJ7CWXERZrVa+SPAx7vvA+7r1+DgCsGZGhOCnN+ZAZWIrEliaEcDy0Y5t4lM/6untxZwgd50auh+L0gKYe9343IH9N6NwAm5Hq54fJQDrRPDDEB0CfFCjQFua2VmI6SonJyf2gJW39PT0vgrvDawKr9JVzrkF0K57Tp44/t7njx2xCZ8Put/7DXSTYW9HJZrAZ6UIHEnA4INp7p0yejC/ESdWB/iZ0dE11/T1D/wN8p7dG0Q4sRu0BUqlqck/OXr08N2ey/d7fivdJ4iRwaSRQkE3sH0CmG7gG1Es7hOAttg4iJBeuXJkJ4jwHrxI8uYuoKffApjk3Qrgv3z8+LFHALyBaT19Icn8zEOg7VwDvUkSWCMA1CYv4KcZ8CYN8DjwfRt1LQf7BXksGbdgeLgY84RLM5n0DvADXw7A34F5aYdp4HugVqs/gcndgxjjH56cGN+HJR5/9NB6rIFowBvAvozqdo6RoAn4oMnDl/EZJ1A8GHzwTTfw46RPCJ8A/rmmU/qHXc+XUZ3xVoFlLWdgw55O8POZ7kvqdhA86lEQfQK0AtzOMRktk3U1m/7dQEbYiJQM1qAWp406C2wXmMc/h/lJBjuXOm0++KbDHF7Xru/bqHdy8NvFdF9Sjx5sK9oofT1KAkuPymh5KEaD2Rnhj/DOC8wQDSzcAIymxcUtv12MoJrNQDfJ8w30qIwr28/fKn257HFt59fF0uOktRUl28ri1O2wNIu3kpbPyvClXx/1ADQwAxvfpNkoLTCNgZIXtsB49LCyLC/JQxvPo4weMKnNl9QtMH8nBt5/NJjNl9TjDrYX7Qa0r8fZ4sowm9WDcQaV7TwAG90y8wRe0LyAD4jpdiFKO9d0O5d2/0B0HvBWHtMYonFn7ZxPvw1Za4vHSdrsYJv5usUpfZ15fJvF7VxKBou7WPDpE4AZ/Mb241YIL0QSMFBnsHNMMi/zUFp+plGnjB4wzSuDNgYr08U699Paz+7A4r6kHnew3cxueivJfJZG3YKv0xbGDQzLSGmN7suozri5dep+vJXd8pm0azFueqCGdbB4K2nntkpfKnvYoAtc0M9nOmVUNxulD6gfb2W3c1mVqG42Sg0+GGajtIb1ZVS3cymjoFtanN3KtzwWp2SgPRribNE8SYwTgGjwbaYbUHFx2qJgW/5Wdl7T8pjuS+oaOAQwY7SBzeZLd0b8JytigPrSzvdtLMHipvuSOgPzvJgC28IPFvdlVGf8bA5exy/Lj1O3oBtBFolrcLPFSdp8u8WjkuX7Nj9uOiWDledi7jPO5qcnXTcg/Hr6NtMpo3pc3PKZZLmm+/nN7kvqFjRvtHGjcWY2WzvJND99oXhcub6Nuh+sbN/WCboBEq2rbzc9TtLm2xeK8zp+fj9O3YLlCUGzBMq4xvZtpvvydHS/bD+/XdtsFvfz+7ZO1MMG9yrv20xvJ/20VjqLt7Sobpf202PBZsaFwLD0c5Vx17IyrcIvNtkEAG7Oj5t+rpJtZmX47TfP9v9tVpxWeBtrbgAAAABJRU5ErkJggg==";
 
@@ -659,29 +816,38 @@ export const IntelliJIdeaIcon: Icon = (props) => {
   );
 };
 
-export const OpenCodeIcon: Icon = ({ monochrome, ...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={monochrome ? "currentColor" : "#BCBBBB"}
-        opacity={monochrome ? 0.45 : undefined}
-      />
-      <path d="M24 8H8V32H24V8ZM32 40H0V0H32V40Z" fill={monochrome ? "currentColor" : "#211E1E"} />
-    </g>
-    <defs>
-      <clipPath id="opencode__clip0_1311_94969">
-        <rect width="32" height="40" fill="white" />
-      </clipPath>
-    </defs>
-  </svg>
-);
-
-export const KiloIcon: Icon = (props) => (
-  <svg {...props} viewBox="0 0 100 100" fill="currentColor">
-    <path d="M0,0v100h100V0H0ZM92.5925926,92.5925926H7.4074074V7.4074074h85.1851852v85.1851852ZM61.1111044,71.9096084h9.2592593v7.4074074h-11.6402116l-5.026455-5.026455v-11.6402116h7.4074074v9.2592593ZM77.7777711,71.9096084h-7.4074074v-9.2592593h-9.2592593v-7.4074074h11.6402116l5.026455,5.026455v11.6402116ZM46.2962963,61.1114207h-7.4074074v-7.4074074h7.4074074v7.4074074ZM22.2222222,53.7040133h7.4074074v16.6666667h16.6666667v7.4074074h-19.047619l-5.026455-5.026455v-19.047619ZM77.7777711,38.8888889v7.4074074h-24.0740741v-7.4074074h8.2781918v-9.2592593h-8.2781918v-7.4074074h10.6591442l5.026455,5.026455v11.6402116h8.3884749ZM29.6296296,30.5555556h9.2592593l7.4074074,7.4074074v8.3333333h-7.4074074v-8.3333333h-9.2592593v8.3333333h-7.4074074v-24.0740741h7.4074074v8.3333333ZM46.2962963,30.5555556h-7.4074074v-8.3333333h7.4074074v8.3333333Z" />
-  </svg>
-);
+export const OpenCodeIcon: Icon = ({ monochrome, ...props }) => {
+  if (monochrome) {
+    return (
+      <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="currentColor" opacity={0.45} />
+          <path d="M24 8H8V32H24V8ZM32 40H0V0H32V40Z" fill="currentColor" />
+        </g>
+        <defs>
+          <clipPath id="opencode__clip0_1311_94969">
+            <rect width="32" height="40" fill="white" />
+          </clipPath>
+        </defs>
+      </svg>
+    );
+  }
+  return (
+    <svg {...props} viewBox="0 0 32 40" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <g clipPath="url(#opencode__clip0_1311_94969)">
+        <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">
+          <rect width="32" height="40" fill="white" />
+        </clipPath>
+      </defs>
+    </svg>
+  );
+};
 
 export const GithubCopilotIcon: Icon = ({ className, ...props }) => (
   <svg
@@ -693,3 +859,69 @@ export const GithubCopilotIcon: Icon = ({ className, ...props }) => (
     <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>
+);
+
+// Amp / Sourcegraph — orange ampersand-inspired wedge mark.
+export const AmpIcon: Icon = ({ className, monochrome, ...props }) => (
+  <svg
+    {...props}
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    className={cn(className)}
+  >
+    <rect width="24" height="24" rx="5" fill={monochrome ? "currentColor" : "#FF5C00"} />
+    <path
+      d="M7.5 17.5 12 6.5l4.5 11h-2.4l-.85-2.2h-2.5L9.9 17.5H7.5Zm3.6-4.05h1.8L12 10.6l-.9 2.85Z"
+      fill={monochrome ? "var(--background, #fff)" : "#fff"}
+    />
+  </svg>
+);
+
+// Kilo Code — orange wedge / triangle mark with stylized "K".
+export const KiloIcon: Icon = ({ className, ...props }) => (
+  <svg
+    {...props}
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    className={cn(className)}
+  >
+    <rect width="24" height="24" rx="5" fill="#FF6B35" />
+    <path
+      d="M8 6.5h2.2v4.4l3.6-4.4h2.7l-3.9 4.6 4.1 6.4h-2.7l-3.1-5-.7.8v4.2H8V6.5Z"
+      fill="#fff"
+    />
+  </svg>
+);
+
+// Re-export the existing Google Gemini mark under the GeminiCli driver
+// alias so providerDriverMeta can import a name that matches the driver
+// kind. The underlying SVG is the same multicolor crystal mark.
+export const GeminiCliIcon: Icon = Gemini;
+
+// Re-export GithubCopilotIcon under the shorter "CopilotIcon" alias used
+// by providerDriverMeta to keep the meta entries terse.
+export const CopilotIcon: Icon = GithubCopilotIcon;
diff --git a/apps/web/src/components/KeybindingsToast.browser.tsx b/apps/web/src/components/KeybindingsToast.browser.tsx
index 79600215d21..2772da10276 100644
--- a/apps/web/src/components/KeybindingsToast.browser.tsx
+++ b/apps/web/src/components/KeybindingsToast.browser.tsx
@@ -7,6 +7,8 @@ import {
   type MessageId,
   type OrchestrationReadModel,
   type ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerConfig,
   type ServerLifecycleWelcomePayload,
   type ThreadId,
@@ -72,7 +74,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,18 +98,24 @@ 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: {
         ...DEFAULT_SERVER_SETTINGS.providers,
-        codex: { enabled: true, binaryPath: "", homePath: "", customModels: [] },
-        claudeAgent: { enabled: true, binaryPath: "", customModels: [], launchArgs: "" },
-        cursor: { enabled: true, binaryPath: "", apiEndpoint: "", customModels: [] },
+        codex: {
+          ...DEFAULT_SERVER_SETTINGS.providers.codex,
+          enabled: true,
+        },
+        claudeAgent: {
+          ...DEFAULT_SERVER_SETTINGS.providers.claudeAgent,
+          enabled: true,
+        },
+        cursor: { ...DEFAULT_SERVER_SETTINGS.providers.cursor, enabled: true },
         opencode: {
+          ...DEFAULT_SERVER_SETTINGS.providers.opencode,
           enabled: true,
-          binaryPath: "",
-          serverUrl: "",
-          serverPassword: "",
-          customModels: [],
         },
       },
     },
@@ -122,7 +131,7 @@ function createMinimalSnapshot(): OrchestrationReadModel {
         title: "Project",
         workspaceRoot: "/repo/project",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         scripts: [],
@@ -137,7 +146,7 @@ function createMinimalSnapshot(): OrchestrationReadModel {
         projectId: PROJECT_ID,
         title: "Test thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5",
         },
         interactionMode: "default",
@@ -239,13 +248,13 @@ function resolveWsRpc(tag: string): unknown {
   if (tag === WS_METHODS.serverGetConfig) {
     return 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) {
@@ -272,7 +281,7 @@ function sendServerConfigUpdatedPush(issues: ServerConfig["issues"]) {
   rpcHarness.emitStreamValue(WS_METHODS.subscribeServerConfig, {
     version: 1,
     type: "keybindingsUpdated",
-    payload: { issues },
+    payload: { keybindings: fixture.serverConfig.keybindings, issues },
   });
 }
 
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/ProviderLogo.tsx b/apps/web/src/components/ProviderLogo.tsx
index a3bb15259c3..282fd56c6f1 100644
--- a/apps/web/src/components/ProviderLogo.tsx
+++ b/apps/web/src/components/ProviderLogo.tsx
@@ -1,8 +1,8 @@
 import { type ComponentProps } from "react";
-import { type ProviderKind } from "@t3tools/contracts";
 
 import { useAppSettings } from "../appSettings";
 import { cn } from "../lib/utils";
+import type { ProviderKind } from "../providerKind";
 import {
   type Icon,
   AmpIcon,
@@ -26,7 +26,7 @@ const PROVIDER_ICON_BY_PROVIDER: Record<ProviderKind, Icon> = {
   kilo: KiloIcon,
 };
 
-export type ProviderLogoProps = Omit<ComponentProps<Icon>, "monochrome"> & {
+export type ProviderLogoProps = ComponentProps<Icon> & {
   provider: ProviderKind;
 };
 
@@ -39,8 +39,11 @@ export function ProviderLogo({ provider, className, style, ...props }: ProviderL
   return (
     <ProviderIcon
       {...props}
-      monochrome={isAccentAppearance}
-      className={cn(className, settings.providerLogoAppearance === "grayscale" && "grayscale")}
+      className={cn(
+        className,
+        settings.providerLogoAppearance === "grayscale" && "grayscale",
+        isAccentAppearance && "[&_path]:fill-[currentColor]",
+      )}
       style={isAccentAppearance ? { ...style, color: accentColor } : style}
     />
   );
diff --git a/apps/web/src/components/PullRequestThreadDialog.tsx b/apps/web/src/components/PullRequestThreadDialog.tsx
index ef5998e990f..ee1b212e976 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,
@@ -52,6 +54,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;
@@ -168,9 +177,9 @@ 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 ??
@@ -178,11 +187,11 @@ export function PullRequestThreadDialog({
     (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 (
@@ -196,18 +205,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);
@@ -245,7 +259,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/Sidebar.logic.test.ts b/apps/web/src/components/Sidebar.logic.test.ts
index f92f2f628c3..926c117c1c0 100644
--- a/apps/web/src/components/Sidebar.logic.test.ts
+++ b/apps/web/src/components/Sidebar.logic.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ProviderDriverKind } from "@t3tools/contracts";
 
 import {
   createThreadJumpHintVisibilityController,
@@ -20,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,
@@ -474,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",
@@ -698,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,
     },
@@ -717,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.tsx b/apps/web/src/components/Sidebar.tsx
index 586c7ed1df8..f617472c99e 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -3,8 +3,7 @@ import {
   ArrowUpDownIcon,
   ChevronRightIcon,
   CloudIcon,
-  GitPullRequestIcon,
-  PlusIcon,
+  FolderPlusIcon,
   SearchIcon,
   SettingsIcon,
   SquarePenIcon,
@@ -12,6 +11,7 @@ import {
   TriangleAlertIcon,
 } from "lucide-react";
 import {
+  ChangeRequestStatusIcon,
   prStatusIndicator,
   resolveThreadPr,
   terminalStatusFromRunningIds,
@@ -143,6 +143,7 @@ import {
   SidebarMenuSubItem,
   SidebarSeparator,
   SidebarTrigger,
+  useSidebar,
 } from "./ui/sidebar";
 import { useThreadSelectionStore } from "../threadSelectionStore";
 import { useCommandPaletteStore } from "../commandPaletteStore";
@@ -366,13 +367,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));
@@ -557,7 +558,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>
                 }
               />
@@ -568,7 +569,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}
@@ -604,7 +605,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}
@@ -620,13 +625,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}
                   >
@@ -637,13 +642,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}
                         >
@@ -664,11 +669,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>
@@ -931,6 +936,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
   }));
   const { updateSettings } = useUpdateSettings();
   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);
@@ -996,7 +1002,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
       toastManager.add(
         stackedThreadToast({
           type: "error",
-          title: "Unable to open PR link",
+          title: "Unable to open pull request link",
           description: error instanceof Error ? error.message : "An error occurred.",
         }),
       );
@@ -1519,12 +1525,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(
@@ -1555,12 +1564,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(
@@ -1658,6 +1678,9 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
               }
             : null,
       });
+      if (isMobile) {
+        setOpenMobile(false);
+      }
       void handleNewThread(scopeProjectRef(member.environmentId, member.id), {
         ...(seedContext.branch !== undefined ? { branch: seedContext.branch } : {}),
         ...(seedContext.worktreePath !== undefined
@@ -1666,7 +1689,7 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         envMode: seedContext.envMode,
       });
     },
-    [defaultThreadEnvMode, handleNewThread, router],
+    [defaultThreadEnvMode, handleNewThread, isMobile, router, setOpenMobile],
   );
 
   const handleCreateThreadClick = useCallback(
@@ -1949,7 +1972,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 : {})}
@@ -2006,7 +2029,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"
                 />
               }
             >
@@ -2020,12 +2043,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.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" />
@@ -2401,9 +2424,13 @@ 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">
@@ -2594,7 +2621,7 @@ const SidebarProjectsContent = memo(function SidebarProjectsContent(
                   />
                 }
               >
-                <PlusIcon className="size-3.5" />
+                <FolderPlusIcon className="size-3.5" />
               </TooltipTrigger>
               <TooltipPopup side="right">Add project</TooltipPopup>
             </Tooltip>
@@ -2703,6 +2730,7 @@ export default function Sidebar() {
   const { updateSettings } = useUpdateSettings();
   const { handleNewThread } = useNewThreadHandler();
   const { archiveThread, deleteThread } = useThreadActions();
+  const { isMobile, setOpenMobile } = useSidebar();
   const routeThreadRef = useParams({
     strict: false,
     select: (params) => resolveThreadRouteRef(params),
@@ -2855,12 +2883,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(
diff --git a/apps/web/src/components/ThreadStatusIndicators.tsx b/apps/web/src/components/ThreadStatusIndicators.tsx
index 497e0f88339..5ed0c0e4c40 100644
--- a/apps/web/src/components/ThreadStatusIndicators.tsx
+++ b/apps/web/src/components/ThreadStatusIndicators.tsx
@@ -1,5 +1,5 @@
 import { scopeProjectRef, scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime";
-import type { GitStatusResult } from "@t3tools/contracts";
+import type { VcsStatusResult } from "@t3tools/contracts";
 import { CloudIcon, GitPullRequestIcon, TerminalIcon } from "lucide-react";
 import { useMemo } from "react";
 import { usePrimaryEnvironmentId } from "../environments/primary";
@@ -11,12 +11,13 @@ 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: "PR open" | "PR closed" | "PR merged";
+  label: string;
   colorClass: string;
   tooltip: string;
   url: string;
@@ -28,43 +29,51 @@ export interface TerminalStatusIndicator {
   pulse: boolean;
 }
 
-export type ThreadPr = GitStatusResult["pr"];
+export type ThreadPr = VcsStatusResult["pr"];
 
-export function prStatusIndicator(pr: ThreadPr): PrStatusIndicator | null {
+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: "PR open",
+      label: `${presentation.shortName} open`,
       colorClass: "text-emerald-600 dark:text-emerald-300/90",
-      tooltip: `#${pr.number} PR open: ${pr.title}`,
+      tooltip: `#${pr.number} ${presentation.shortName} open: ${pr.title}`,
       url: pr.url,
     };
   }
   if (pr.state === "closed") {
     return {
-      label: "PR closed",
+      label: `${presentation.shortName} closed`,
       colorClass: "text-zinc-500 dark:text-zinc-400/80",
-      tooltip: `#${pr.number} PR closed: ${pr.title}`,
+      tooltip: `#${pr.number} ${presentation.shortName} closed: ${pr.title}`,
       url: pr.url,
     };
   }
   if (pr.state === "merged") {
     return {
-      label: "PR merged",
+      label: `${presentation.shortName} merged`,
       colorClass: "text-violet-600 dark:text-violet-300/90",
-      tooltip: `#${pr.number} PR merged: ${pr.title}`,
+      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: GitStatusResult | null,
+  gitStatus: VcsStatusResult | null,
 ): ThreadPr | null {
-  if (threadBranch === null || gitStatus === null || gitStatus.branch !== threadBranch) {
+  if (threadBranch === null || gitStatus === null || gitStatus.refName !== threadBranch) {
     return null;
   }
 
@@ -124,7 +133,7 @@ export function ThreadStatusLabel({
 
 /**
  * Non-interactive leading status icons for a thread row in compact contexts
- * like the command palette. Shows the PR state icon (if present) and the
+ * 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 }) {
@@ -146,7 +155,7 @@ export function ThreadRowLeadingStatus({ thread }: { thread: SidebarThreadSummar
     cwd: thread.branch != null ? gitCwd : null,
   });
   const pr = resolveThreadPr(thread.branch, gitStatus.data);
-  const prStatus = prStatusIndicator(pr);
+  const prStatus = prStatusIndicator(pr, gitStatus.data?.sourceControlProvider);
   const threadStatus = resolveThreadStatusPill({
     thread: {
       ...thread,
@@ -170,7 +179,7 @@ export function ThreadRowLeadingStatus({ thread }: { thread: SidebarThreadSummar
               />
             }
           >
-            <GitPullRequestIcon className="size-3" />
+            <ChangeRequestStatusIcon className="size-3" />
           </TooltipTrigger>
           <TooltipPopup side="top">{prStatus.tooltip}</TooltipPopup>
         </Tooltip>
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 e0bb560980a..b54bd865c8b 100644
--- a/apps/web/src/components/WebSocketConnectionSurface.tsx
+++ b/apps/web/src/components/WebSocketConnectionSurface.tsx
@@ -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(
@@ -297,7 +305,7 @@ export function WebSocketConnectionCoordinator() {
               },
               description: describeExhaustedToast(),
               timeout: 0,
-              title: "Disconnected from T3 Server",
+              title: buildReconnectTitle(status),
               type: "error",
             })
           : stackedThreadToast({
@@ -334,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: {
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 3033872544e..d64d0316684 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -5,7 +5,6 @@ import type {
   ProjectEntry,
   ProviderApprovalDecision,
   ProviderInteractionMode,
-  ProviderKind,
   ResolvedKeybindingsConfig,
   RuntimeMode,
   ScopedThreadRef,
@@ -14,6 +13,8 @@ import type {
   TurnId,
 } from "@t3tools/contracts";
 import {
+  ProviderDriverKind,
+  ProviderInstanceId,
   PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
   PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,
 } from "@t3tools/contracts";
@@ -60,7 +61,6 @@ import {
   shouldUseCompactComposerFooter,
 } from "../composerFooterLayout";
 import { type ComposerPromptEditorHandle, ComposerPromptEditor } from "../ComposerPromptEditor";
-import { type ModelOptionEntry } from "../../providerModelOptions";
 import { ProviderModelPicker } from "./ProviderModelPicker";
 import { type ComposerCommandItem, ComposerCommandMenu } from "./ComposerCommandMenu";
 import { ComposerPendingApprovalActions } from "./ComposerPendingApprovalActions";
@@ -72,11 +72,10 @@ import { ComposerPlanFollowUpBanner } from "./ComposerPlanFollowUpBanner";
 import { resolveComposerMenuActiveItemId } from "./composerMenuHighlight";
 import { searchSlashCommandItems } from "./composerSlashCommandSearch";
 import {
-  getComposerProviderControls,
   getComposerProviderState,
   renderProviderTraitsMenuContent,
   renderProviderTraitsPicker,
-} from "./composerProviderRegistry";
+} from "./composerProviderState";
 import { ContextWindowMeter } from "./ContextWindowMeter";
 import { buildExpandedImagePreview, type ExpandedImagePreview } from "./ExpandedImagePreview";
 import { basenameOfPath } from "../../vscode-icons";
@@ -97,7 +96,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";
@@ -105,6 +111,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`;
 
@@ -132,6 +139,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,
@@ -161,6 +175,10 @@ 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;
@@ -283,7 +301,9 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
   promptHasText: boolean;
   isSendBusy: boolean;
   isConnecting: boolean;
+  isEnvironmentUnavailable: boolean;
   hasSendableContent: boolean;
+  preserveComposerFocusOnPointerDown?: boolean;
   onPreviousPendingQuestion: () => void;
   onInterrupt: () => void;
   onImplementPlanInNewThread: () => void;
@@ -302,8 +322,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}
@@ -344,7 +366,7 @@ export interface ChatComposerHandle {
     selectedPromptEffort: string | null;
     selectedModelOptionsForDispatch: unknown;
     selectedModelSelection: ModelSelection;
-    selectedProvider: ProviderKind;
+    selectedProvider: ProviderDriverKind;
     selectedModel: string;
     selectedProviderModels: ReadonlyArray<ServerProvider["models"][number]>;
   };
@@ -373,6 +395,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;
@@ -383,7 +409,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;
@@ -404,7 +430,7 @@ export interface ChatComposerProps {
   interactionMode: ProviderInteractionMode;
 
   // Provider / model
-  lockedProvider: ProviderKind | null;
+  lockedProvider: ProviderDriverKind | null;
   providerStatuses: ServerProvider[];
   activeProjectDefaultModelSelection: ModelSelection | null | undefined;
   activeThreadModelSelection: ModelSelection | null | undefined;
@@ -447,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;
@@ -480,6 +506,7 @@ export const ChatComposer = memo(
       isConnecting,
       isSendBusy,
       isPreparingWorktree,
+      environmentUnavailable,
       activePendingApproval,
       pendingApprovals,
       pendingUserInputs,
@@ -564,29 +591,134 @@ export const ChatComposer = memo(
     // ------------------------------------------------------------------
     // 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 =
-      activeThreadModelSelection?.provider ?? activeProjectDefaultModelSelection?.provider ?? null;
+      activeThread?.session?.providerInstanceId ??
+      activeThreadModelSelection?.instanceId ??
+      activeProjectDefaultModelSelection?.instanceId ??
+      null;
+    const explicitSelectedInstanceId = selectedProviderByThreadId ?? threadProvider;
+
+    const unlockedSelectedProvider =
+      resolveProviderDriverKindForInstanceSelection(
+        providerInstanceEntries,
+        providerStatuses,
+        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
+      );
+    }, [
+      activeThread,
+      activeThreadModelSelection?.instanceId,
+      lockedProvider,
+      providerInstanceEntries,
+    ]);
 
-    const unlockedSelectedProvider = resolveSelectableProvider(
-      providerStatuses,
-      selectedProviderByThreadId ?? threadProvider ?? "codex",
-    );
-    const selectedProvider: ProviderKind = lockedProvider ?? unlockedSelectedProvider;
+    // 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),
+      );
+      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 selectedProviderModels = getProviderModels(providerStatuses, selectedProvider);
+    // 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(
-      () => providerStatuses.find((provider) => provider.provider === selectedProvider),
-      [providerStatuses, selectedProvider],
+      () => selectedProviderEntry?.snapshot ?? null,
+      [selectedProviderEntry],
+    );
+    const selectedProviderModels = useMemo<ReadonlyArray<ServerProvider["models"][number]>>(
+      () => selectedProviderEntry?.models ?? [],
+      [selectedProviderEntry],
     );
 
     const composerProviderState = useMemo(
@@ -596,7 +728,7 @@ export const ChatComposer = memo(
           model: selectedModel,
           models: selectedProviderModels,
           prompt,
-          modelOptions: composerModelOptions,
+          modelOptions: composerModelOptions?.[selectedProvider],
         }),
       [composerModelOptions, prompt, selectedModel, selectedProvider, selectedProviderModels],
     );
@@ -604,38 +736,39 @@ export const ChatComposer = memo(
     const selectedPromptEffort = composerProviderState.promptEffort;
     const selectedModelOptionsForDispatch = composerProviderState.modelOptionsForDispatch;
     const composerProviderControls = useMemo(
-      () => getComposerProviderControls(selectedProvider),
-      [selectedProvider],
+      () => ({
+        showInteractionModeToggle: getProviderInteractionModeToggle(
+          providerStatuses,
+          selectedProvider,
+        ),
+      }),
+      [providerStatuses, selectedProvider],
     );
     const selectedModelSelection = useMemo<ModelSelection>(
-      () => createModelSelection(selectedProvider, selectedModel, selectedModelOptionsForDispatch),
-      [selectedModel, selectedModelOptionsForDispatch, selectedProvider],
+      () =>
+        createModelSelection(selectedInstanceId, selectedModel, selectedModelOptionsForDispatch),
+      [selectedInstanceId, selectedModel, selectedModelOptionsForDispatch],
     );
     const selectedModelForPicker = selectedModel;
-    const modelOptionsByProvider = useMemo<
-      Record<ProviderKind, ReadonlyArray<ModelOptionEntry>>
+    // 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 modelsFor = (kind: ProviderKind): ReadonlyArray<ModelOptionEntry> =>
-        (providerStatuses.find((p) => p.provider === kind)?.models ?? []).map(
-          ({ slug, name, isCustom }) => ({ slug, name, isCustom }),
-        );
-      return {
-        codex: modelsFor("codex"),
-        claudeAgent: modelsFor("claudeAgent"),
-        copilot: modelsFor("copilot"),
-        cursor: modelsFor("cursor"),
-        opencode: modelsFor("opencode"),
-        geminiCli: modelsFor("geminiCli"),
-        amp: modelsFor("amp"),
-        kilo: modelsFor("kilo"),
-      };
-    }, [providerStatuses]);
+      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 = modelOptionsByProvider[selectedProvider];
+      const currentOptions = modelOptionsByInstance.get(selectedInstanceId) ?? [];
       return currentOptions.some((option) => option.slug === selectedModelForPicker)
         ? selectedModelForPicker
         : (normalizeModelSlug(selectedModelForPicker, selectedProvider) ?? selectedModelForPicker);
-    }, [modelOptionsByProvider, selectedModelForPicker, selectedProvider]);
+    }, [modelOptionsByInstance, selectedInstanceId, selectedModelForPicker, selectedProvider]);
 
     // ------------------------------------------------------------------
     // Context window
@@ -662,17 +795,25 @@ export const ChatComposer = memo(
     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);
 
     // ------------------------------------------------------------------
@@ -817,6 +958,8 @@ export const ChatComposer = memo(
       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);
@@ -909,6 +1052,11 @@ export const ChatComposer = memo(
           : null,
       [activePendingIsResponding, activePendingProgress, activePendingResolvedAnswers],
     );
+    const collapsedComposerPrimaryActionDisabled =
+      phase === "running" || isSendBusy || isConnecting || !composerSendState.hasSendableContent;
+    const collapsedComposerPrimaryActionLabel = "Send message";
+    const showMobilePendingAnswerActions =
+      isMobileViewport && !isComposerCollapsedMobile && pendingPrimaryAction !== null;
 
     // ------------------------------------------------------------------
     // Prompt helpers
@@ -1438,6 +1586,69 @@ export const ChatComposer = memo(
       [composerHighlightedItemId, composerMenuItems],
     );
 
+    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
     // ------------------------------------------------------------------
@@ -1468,7 +1679,7 @@ export const ChatComposer = memo(
         }
       }
       if (key === "Enter" && !event.shiftKey) {
-        void onSend();
+        submitComposer();
         return true;
       }
       return false;
@@ -1578,6 +1789,50 @@ export const ChatComposer = memo(
     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]);
+
+    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);
+        }
+      };
+    }, []);
 
     // ------------------------------------------------------------------
     // Imperative handle
@@ -1691,7 +1946,7 @@ export const ChatComposer = memo(
     return (
       <form
         ref={composerFormRef}
-        onSubmit={onSend}
+        onSubmit={submitComposer}
         className="mx-auto w-full min-w-0 max-w-208"
         data-chat-composer-form="true"
       >
@@ -1706,21 +1961,83 @@ export const ChatComposer = memo(
           onDrop={onComposerDrop}
         >
           <div
+            ref={composerSurfaceRef}
+            data-chat-composer-mobile-collapsed={isComposerCollapsedMobile ? "true" : "false"}
             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",
+              environmentUnavailable ? "opacity-75" : null,
               composerProviderState.composerSurfaceClassName,
             )}
+            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();
+            }}
           >
-            {activePendingApproval ? (
-              <div className="rounded-t-[19px] border-b border-border/65 bg-muted/20">
+            {!isComposerCollapsedMobile &&
+              (activePendingApproval ? (
+                <div className="rounded-t-[19px] border-b border-border/65 bg-muted/20">
+                  <ComposerPendingApprovalPanel
+                    approval={activePendingApproval}
+                    pendingCount={pendingApprovals.length}
+                  />
+                </div>
+              ) : pendingUserInputs.length > 0 ? (
+                <div className="rounded-t-[19px] border-b border-border/65 bg-muted/20">
+                  <ComposerPendingUserInputPanel
+                    pendingUserInputs={pendingUserInputs}
+                    respondingRequestIds={respondingRequestIds}
+                    answers={activePendingDraftAnswers}
+                    questionIndex={activePendingQuestionIndex}
+                    onToggleOption={onSelectActivePendingUserInputOption}
+                    onAdvance={onAdvanceActivePendingUserInput}
+                  />
+                </div>
+              ) : showPlanFollowUpPrompt && activeProposedPlan ? (
+                <div className="rounded-t-[19px] border-b border-border/65 bg-muted/20">
+                  <ComposerPlanFollowUpBanner
+                    key={activeProposedPlan.id}
+                    planTitle={proposedPlanTitle(activeProposedPlan.planMarkdown) ?? null}
+                  />
+                </div>
+              ) : null)}
+
+            {isComposerCollapsedMobile && activePendingApproval ? (
+              <div
+                className="rounded-t-[19px] border-b border-border/65 bg-muted/20"
+                data-chat-composer-collapsed-controls="true"
+              >
                 <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>
-            ) : pendingUserInputs.length > 0 ? (
-              <div className="rounded-t-[19px] border-b border-border/65 bg-muted/20">
+            ) : 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}
@@ -1729,13 +2046,92 @@ export const ChatComposer = memo(
                   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>
-            ) : showPlanFollowUpPrompt && activeProposedPlan ? (
-              <div className="rounded-t-[19px] border-b border-border/65 bg-muted/20">
-                <ComposerPlanFollowUpBanner
-                  key={activeProposedPlan.id}
-                  planTitle={proposedPlanTitle(activeProposedPlan.planMarkdown) ?? null}
-                />
+            ) : null}
+
+            {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}
 
@@ -1743,6 +2139,7 @@ export const ChatComposer = memo(
               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 && (
@@ -1764,7 +2161,8 @@ export const ChatComposer = memo(
                 </div>
               )}
 
-              {!isComposerApprovalState &&
+              {!isComposerCollapsedMobile &&
+                !isComposerApprovalState &&
                 pendingUserInputs.length === 0 &&
                 composerImages.length > 0 && (
                   <div className="mb-3 flex flex-wrap gap-2">
@@ -1831,43 +2229,80 @@ export const ChatComposer = memo(
                   </div>
                 )}
 
-              <ComposerPromptEditor
-                ref={composerEditorRef}
-                value={
-                  isComposerApprovalState
-                    ? ""
-                    : activePendingProgress
-                      ? activePendingProgress.customAnswer
-                      : prompt
-                }
-                cursor={composerCursor}
-                terminalContexts={
-                  !isComposerApprovalState && pendingUserInputs.length === 0
-                    ? composerTerminalContexts
-                    : []
-                }
-                skills={selectedProviderStatus?.skills ?? []}
-                onRemoveTerminalContext={removeComposerTerminalContextFromDraft}
-                onChange={onPromptChange}
-                onCommandKeyDown={onComposerCommandKey}
-                onPaste={onComposerPaste}
-                placeholder={
-                  isComposerApprovalState
-                    ? (activePendingApproval?.detail ?? "Resolve this approval request to continue")
-                    : activePendingProgress
-                      ? "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"
-                }
-                disabled={isConnecting || isComposerApprovalState}
-              />
+              <div className="relative">
+                <ComposerPromptEditor
+                  ref={composerEditorRef}
+                  value={
+                    isComposerApprovalState
+                      ? ""
+                      : activePendingProgress
+                        ? activePendingProgress.customAnswer
+                        : prompt
+                  }
+                  cursor={composerCursor}
+                  terminalContexts={
+                    !isComposerApprovalState && pendingUserInputs.length === 0
+                      ? composerTerminalContexts
+                      : []
+                  }
+                  skills={selectedProviderStatus?.skills ?? []}
+                  {...(showMobilePendingAnswerActions ? { className: "max-sm:pb-11" } : {})}
+                  onRemoveTerminalContext={removeComposerTerminalContextFromDraft}
+                  onChange={onPromptChange}
+                  onCommandKeyDown={onComposerCommandKey}
+                  onPaste={onComposerPaste}
+                  placeholder={
+                    isComposerApprovalState
+                      ? (activePendingApproval?.detail ??
+                        "Resolve this approval request to continue")
+                      : activePendingProgress
+                        ? "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"
+                          : environmentUnavailable
+                            ? `${environmentUnavailable.label} is ${
+                                environmentUnavailable.connectionState === "connecting"
+                                  ? "connecting"
+                                  : "disconnected"
+                              }`
+                            : phase === "disconnected"
+                              ? "Ask for follow-up changes or attach images"
+                              : "Ask anything, @tag files/folders, or use / to show available commands"
+                  }
+                  disabled={
+                    isConnecting ||
+                    isComposerApprovalState ||
+                    (environmentUnavailable !== null && activePendingProgress === null)
+                  }
+                />
+                {showMobilePendingAnswerActions ? (
+                  <div
+                    data-chat-composer-mobile-pending-actions="true"
+                    className="absolute bottom-0 right-0 flex justify-end"
+                  >
+                    <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}
+                    />
+                  </div>
+                ) : null}
+              </div>
             </div>
 
             {/* Bottom toolbar */}
-            {activePendingApproval ? (
+            {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}
@@ -1882,17 +2317,19 @@ export const ChatComposer = memo(
                 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}
-                    provider={selectedProvider}
+                    activeInstanceId={selectedInstanceId}
                     model={selectedModelForPickerWithCustomFallback}
                     lockedProvider={lockedProvider}
-                    providers={providerStatuses}
+                    lockedContinuationGroupKey={lockedContinuationGroupKey}
+                    instanceEntries={providerInstanceEntries}
                     keybindings={keybindings}
-                    modelOptionsByProvider={modelOptionsByProvider}
+                    modelOptionsByInstance={modelOptionsByInstance}
                     terminalOpen={terminalOpen}
                     open={isComposerModelPickerOpen}
                     {...(composerProviderState.modelPickerIconClassName
@@ -1904,7 +2341,7 @@ export const ChatComposer = memo(
                     onOpenChange={(open) => {
                       setIsComposerModelPickerOpen(open);
                     }}
-                    onProviderModelChange={onProviderModelSelect}
+                    onInstanceModelChange={onProviderModelSelect}
                   />
 
                   {isComposerFooterCompact ? (
@@ -1967,8 +2404,10 @@ export const ChatComposer = memo(
                     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}
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 390457f01d1..aedcc3fb288 100644
--- a/apps/web/src/components/chat/ChatHeader.tsx
+++ b/apps/web/src/components/chat/ChatHeader.tsx
@@ -2,10 +2,10 @@ import {
   type EnvironmentId,
   type EditorId,
   type ProjectScript,
-  type ProviderKind,
   type ResolvedKeybindingsConfig,
   type ThreadId,
 } from "@t3tools/contracts";
+import type { ProviderKind } from "../../providerKind";
 import { scopeThreadRef } from "@t3tools/client-runtime";
 import { memo } from "react";
 import GitActionsControl from "../GitActionsControl";
@@ -17,6 +17,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;
@@ -46,6 +47,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,
@@ -73,6 +86,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">
@@ -106,7 +126,7 @@ export const ChatHeader = memo(function ChatHeader({
             onDeleteScript={onDeleteProjectScript}
           />
         )}
-        {activeProjectName && (
+        {showOpenInPicker && (
           <OpenInPicker
             keybindings={keybindings}
             availableEditors={availableEditors}
@@ -156,14 +176,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 54181caa02e..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,74 +81,58 @@ 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}
@@ -169,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();
@@ -177,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();
@@ -196,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();
@@ -213,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();
@@ -225,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",
     });
 
@@ -244,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",
     });
 
@@ -263,7 +286,9 @@ describe("CompactComposerControlsMenu", () => {
 
     await vi.waitFor(() => {
       const text = document.body.textContent ?? "";
-      expect(text).toContain("Remove Ultrathink from the prompt to change effort.");
+      expect(text).toContain(
+        'Your prompt contains "ultrathink" in the text. Remove it to change this option.',
+      );
     });
   });
 
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 5d13e6593b4..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";
@@ -39,7 +39,7 @@ export type ComposerCommandItem =
   | {
       id: string;
       type: "provider-slash-command";
-      provider: ProviderKind;
+      provider: ProviderDriverKind;
       command: ServerProviderSlashCommand;
       label: string;
       description: string;
@@ -47,7 +47,7 @@ export type ComposerCommandItem =
   | {
       id: string;
       type: "skill";
-      provider: ProviderKind;
+      provider: ProviderDriverKind;
       skill: ServerProviderSkill;
       label: string;
       description: string;
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/CursorTraitsPicker.tsx b/apps/web/src/components/chat/CursorTraitsPicker.tsx
deleted file mode 100644
index eed84cbe7ec..00000000000
--- a/apps/web/src/components/chat/CursorTraitsPicker.tsx
+++ /dev/null
@@ -1,125 +0,0 @@
-import { CURSOR_REASONING_OPTIONS, type CursorReasoningOption } from "@t3tools/contracts";
-import { getCursorModelCapabilities, parseCursorModelSelection } from "@t3tools/shared/model";
-import { memo, useState } from "react";
-import { ChevronDownIcon } from "lucide-react";
-import { Button } from "../ui/button";
-import {
-  Menu,
-  MenuGroup,
-  MenuPopup,
-  MenuRadioGroup,
-  MenuRadioItem,
-  MenuSeparator as MenuDivider,
-  MenuTrigger,
-} from "../ui/menu";
-
-export const CursorTraitsPicker = memo(function CursorTraitsPicker(props: {
-  selection: ReturnType<typeof parseCursorModelSelection>;
-  capabilities: ReturnType<typeof getCursorModelCapabilities>;
-  disabled?: boolean;
-  onReasoningChange: (reasoning: CursorReasoningOption) => void;
-  onFastModeChange: (enabled: boolean) => void;
-  onThinkingModeChange: (enabled: boolean) => void;
-}) {
-  const [isMenuOpen, setIsMenuOpen] = useState(false);
-  const reasoningLabelByOption: Record<CursorReasoningOption, string> = {
-    low: "Low",
-    normal: "Normal",
-    high: "High",
-    xhigh: "Extra High",
-  };
-  const traitSummary = [
-    ...(props.capabilities.supportsReasoning
-      ? [reasoningLabelByOption[props.selection.reasoning]]
-      : []),
-    ...(props.capabilities.supportsFast && props.selection.fast ? ["Fast"] : []),
-    ...(props.capabilities.supportsThinking && props.selection.thinking ? ["Thinking"] : []),
-  ];
-  const triggerLabel = traitSummary.length > 0 ? traitSummary.join(" · ") : "Traits";
-
-  return (
-    <Menu
-      open={isMenuOpen}
-      onOpenChange={(open) => {
-        if (props.disabled) {
-          setIsMenuOpen(false);
-          return;
-        }
-        setIsMenuOpen(open);
-      }}
-    >
-      <MenuTrigger
-        render={
-          <Button
-            size="sm"
-            variant="ghost"
-            className="shrink-0 whitespace-nowrap px-2 text-muted-foreground/70 hover:text-foreground/80 sm:px-3"
-            disabled={props.disabled}
-          />
-        }
-      >
-        <span>{triggerLabel}</span>
-        <ChevronDownIcon aria-hidden="true" className="size-3 opacity-60" />
-      </MenuTrigger>
-      <MenuPopup align="start">
-        {props.capabilities.supportsReasoning && (
-          <MenuGroup>
-            <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Reasoning</div>
-            <MenuRadioGroup
-              value={props.selection.reasoning}
-              onValueChange={(value) => {
-                if (props.disabled) return;
-                if (!value) return;
-                const nextReasoning = CURSOR_REASONING_OPTIONS.find((option) => option === value);
-                if (!nextReasoning) return;
-                props.onReasoningChange(nextReasoning);
-              }}
-            >
-              {CURSOR_REASONING_OPTIONS.map((reasoning) => (
-                <MenuRadioItem key={reasoning} value={reasoning}>
-                  {reasoningLabelByOption[reasoning]}
-                  {reasoning === "normal" ? " (default)" : ""}
-                </MenuRadioItem>
-              ))}
-            </MenuRadioGroup>
-          </MenuGroup>
-        )}
-        {props.capabilities.supportsReasoning &&
-          (props.capabilities.supportsFast || props.capabilities.supportsThinking) && (
-            <MenuDivider />
-          )}
-        {props.capabilities.supportsFast && (
-          <MenuGroup>
-            <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Fast Mode</div>
-            <MenuRadioGroup
-              value={props.selection.fast ? "on" : "off"}
-              onValueChange={(value) => {
-                if (props.disabled) return;
-                props.onFastModeChange(value === "on");
-              }}
-            >
-              <MenuRadioItem value="off">off</MenuRadioItem>
-              <MenuRadioItem value="on">on</MenuRadioItem>
-            </MenuRadioGroup>
-          </MenuGroup>
-        )}
-        {props.capabilities.supportsFast && props.capabilities.supportsThinking && <MenuDivider />}
-        {props.capabilities.supportsThinking && (
-          <MenuGroup>
-            <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Thinking</div>
-            <MenuRadioGroup
-              value={props.selection.thinking ? "on" : "off"}
-              onValueChange={(value) => {
-                if (props.disabled) return;
-                props.onThinkingModeChange(value === "on");
-              }}
-            >
-              <MenuRadioItem value="off">off</MenuRadioItem>
-              <MenuRadioItem value="on">on</MenuRadioItem>
-            </MenuRadioGroup>
-          </MenuGroup>
-        )}
-      </MenuPopup>
-    </Menu>
-  );
-});
diff --git a/apps/web/src/components/chat/MessagesTimeline.browser.tsx b/apps/web/src/components/chat/MessagesTimeline.browser.tsx
index c794fff5686..0eb5c8a1fc0 100644
--- a/apps/web/src/components/chat/MessagesTimeline.browser.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.browser.tsx
@@ -96,7 +96,6 @@ describe("MessagesTimeline", () => {
               label: "thinking",
               detail: "Inspecting repository state",
               tone: "thinking",
-              activityKind: "task.progress",
             },
           },
         ]}
@@ -144,7 +143,6 @@ describe("MessagesTimeline", () => {
                 label: "thinking",
                 detail: "Inspecting repository state",
                 tone: "thinking",
-                activityKind: "task.progress",
               },
             },
           ]}
diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
index 85822d105e7..e239449ca12 100644
--- a/apps/web/src/components/chat/MessagesTimeline.test.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -152,7 +152,6 @@ describe("MessagesTimeline", () => {
               createdAt: "2026-03-17T19:12:28.000Z",
               label: "Context compacted",
               tone: "info",
-              activityKind: "context.compacted",
             },
           },
         ]}
@@ -179,7 +178,6 @@ describe("MessagesTimeline", () => {
               label: "Updated files",
               tone: "tool",
               changedFiles: ["C:/Users/mike/dev-stuff/t3code/apps/web/src/session-logic.ts"],
-              activityKind: "tool.completed",
             },
           },
         ]}
diff --git a/apps/web/src/components/chat/ModelListRow.tsx b/apps/web/src/components/chat/ModelListRow.tsx
index 6cd097ad1fe..064df338e46 100644
--- a/apps/web/src/components/chat/ModelListRow.tsx
+++ b/apps/web/src/components/chat/ModelListRow.tsx
@@ -1,9 +1,8 @@
-import { type ProviderKind } from "@t3tools/contracts";
+import { type ProviderDriverKind, type ProviderInstanceId } from "@t3tools/contracts";
 import { memo } from "react";
 import { StarIcon } from "lucide-react";
 import {
   getDisplayModelName,
-  getProviderLabel,
   getTriggerDisplayModelLabel,
   type ModelEsque,
   PROVIDER_ICON_BY_PROVIDER,
@@ -16,7 +15,17 @@ import { cn } from "~/lib/utils";
 export const ModelListRow = memo(function ModelListRow(props: {
   index: number;
   model: ModelEsque;
-  provider: ProviderKind;
+  /** 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;
@@ -25,13 +34,16 @@ export const ModelListRow = memo(function ModelListRow(props: {
   jumpLabel?: string | null;
   onToggleFavorite: () => void;
 }) {
-  const ProviderIcon = PROVIDER_ICON_BY_PROVIDER[props.provider];
+  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.provider}:${props.model.slug}`}
+      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",
@@ -92,9 +104,16 @@ export const ModelListRow = memo(function ModelListRow(props: {
         </div>
         {props.showProvider && (
           <div className="flex items-center gap-1 mt-0.5">
-            <ProviderIcon className="size-3 shrink-0" />
+            {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">
-              {getProviderLabel(props.provider, props.model)}
+              {providerLabel}
             </span>
           </div>
         )}
diff --git a/apps/web/src/components/chat/ModelPickerContent.tsx b/apps/web/src/components/chat/ModelPickerContent.tsx
index 9318688c65c..c3468ef8c65 100644
--- a/apps/web/src/components/chat/ModelPickerContent.tsx
+++ b/apps/web/src/components/chat/ModelPickerContent.tsx
@@ -1,8 +1,7 @@
 import {
-  type ProviderKind,
-  PROVIDER_DISPLAY_NAMES,
+  type ProviderInstanceId,
+  type ProviderDriverKind,
   type ResolvedKeybindingsConfig,
-  type ServerProvider,
 } from "@t3tools/contracts";
 import { resolveSelectableModel } from "@t3tools/shared/model";
 import { memo, useMemo, useState, useCallback, useEffect, useLayoutEffect, useRef } from "react";
@@ -22,40 +21,89 @@ import {
 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;
-  provider: ProviderKind;
+  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: {
-  provider: ProviderKind;
+  /** The instance currently selected in the composer (combobox "value"). */
+  activeInstanceId: ProviderInstanceId;
   model: string;
-  lockedProvider: ProviderKind | null;
-  providers?: ReadonlyArray<ServerProvider>;
+  /**
+   * 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;
-  modelOptionsByProvider: Record<ProviderKind, ReadonlyArray<ModelEsque>>;
+  /**
+   * 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;
-  onProviderModelChange: (provider: ProviderKind, model: string) => void;
+  onInstanceModelChange: (instanceId: ProviderInstanceId, model: string) => void;
 }) {
-  const { keybindings: providedKeybindings, modelOptionsByProvider, onProviderModelChange } = props;
+  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 [selectedProvider, setSelectedProvider] = useState<ProviderKind | "favorites">(() => {
-    if (props.lockedProvider !== null) {
-      return props.lockedProvider;
-    }
-    return favorites.length > 0 ? "favorites" : props.provider;
-  });
+  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],
@@ -66,9 +114,9 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
     searchInputRef.current?.focus({ preventScroll: true });
   }, []);
 
-  const handleSelectProvider = useCallback(
-    (provider: ProviderKind | "favorites") => {
-      setSelectedProvider(provider);
+  const handleSelectInstance = useCallback(
+    (instanceId: ProviderInstanceId | "favorites") => {
+      setSelectedInstanceId(instanceId);
       window.requestAnimationFrame(() => {
         focusSearchInput();
       });
@@ -90,44 +138,97 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
     };
   }, [focusSearchInput]);
 
-  // Create a Set for efficient lookup
+  // 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) => `${fav.provider}:${fav.model}`));
-  }, [favorites]);
-  const favoriteOrder = useMemo(() => {
-    return new Map(
-      favorites.map((favorite, index) => [`${favorite.provider}:${favorite.model}`, index]),
-    );
+    return new Set(favorites.map((fav) => providerModelKey(fav.provider, fav.model)));
   }, [favorites]);
 
-  const readyProviderSet = useMemo(() => {
-    if (!props.providers || props.providers.length === 0) {
-      return null;
+  /**
+   * 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 new Set(
-      props.providers
-        .filter((provider) => provider.status === "ready")
-        .map((provider) => provider.provider),
-    );
-  }, [props.providers]);
-
-  // Flatten models into a searchable array
+    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(() => {
-    return Object.entries(props.modelOptionsByProvider).flatMap(([providerKind, models]) => {
-      if (readyProviderSet && !readyProviderSet.has(providerKind as ProviderKind)) {
-        return [];
+    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;
       }
-      return models.map((m) => ({
-        slug: m.slug,
-        name: m.name,
-        ...(m.shortName ? { shortName: m.shortName } : {}),
-        ...(m.subProvider ? { subProvider: m.subProvider } : {}),
-        provider: providerKind as ProviderKind,
-      })) satisfies Array<ModelPickerItem>;
-    });
-  }, [props.modelOptionsByProvider, readyProviderSet]);
+      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 provider
+  // Filter models based on search query and selected instance
   const filteredModels = useMemo(() => {
     let result = flatModels;
 
@@ -138,13 +239,23 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
           model,
           score: scoreModelPickerSearch(
             {
-              ...model,
-              isFavorite: favoritesSet.has(`${model.provider}:${model.slug}`),
+              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(`${model.provider}:${model.slug}`),
-          tieBreaker: buildModelPickerSearchText(model),
+          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(
           (
@@ -157,10 +268,12 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
           } => rankedModel.score !== null,
         );
 
-      // When searching, we only respect locked provider, ignoring sidebar selection
+      // 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) => rankedModel.model.provider === props.lockedProvider)
+          .filter((rankedModel) => matchesLockedProvider(rankedModel.model))
           .toSorted((a, b) => {
             const scoreDelta = a.score - b.score;
             if (scoreDelta !== 0) {
@@ -188,72 +301,87 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
         .map((rankedModel) => rankedModel.model);
     }
 
-    // Locked provider mode always shows that provider's models, with favorites first.
     if (props.lockedProvider !== null) {
-      result = result.filter((m) => m.provider === props.lockedProvider);
-    } else if (selectedProvider === "favorites") {
-      result = result.filter((m) => favoritesSet.has(`${m.provider}:${m.slug}`));
+      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.provider === selectedProvider);
+      result = result.filter((m) => m.instanceId === selectedInstanceId);
     }
 
-    return result.toSorted((a, b) => {
-      const aOrder = favoriteOrder.get(`${a.provider}:${a.slug}`);
-      const bOrder = favoriteOrder.get(`${b.provider}:${b.slug}`);
-
-      if (aOrder !== undefined && bOrder !== undefined) {
-        return aOrder - bOrder;
-      }
-      if (aOrder !== undefined) {
-        return -1;
-      }
-      if (bOrder !== undefined) {
-        return 1;
-      }
-      return 0;
+    return sortProviderModelItems(result, {
+      favoriteModelKeys: favoritesSet,
+      groupFavorites: selectedInstanceId !== "favorites",
+      instanceOrder: selectedInstanceId === "favorites" ? instanceOrder : [],
     });
   }, [
-    favoriteOrder,
     favoritesSet,
     flatModels,
+    instanceOrder,
+    matchesLockedProvider,
     props.lockedProvider,
     searchQuery,
-    selectedProvider,
+    showLockedInstanceSidebar,
+    selectedInstanceId,
   ]);
 
   const handleModelSelect = useCallback(
-    (modelSlug: string, provider: ProviderKind) => {
-      const resolvedModel = resolveSelectableModel(
-        provider,
-        modelSlug,
-        modelOptionsByProvider[provider],
-      );
+    (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) {
-        onProviderModelChange(provider, resolvedModel);
+        onInstanceModelChange(instanceId, resolvedModel);
       }
     },
-    [modelOptionsByProvider, onProviderModelChange],
+    [entryByInstanceId, modelOptionsByInstance, onInstanceModelChange],
   );
 
   const toggleFavorite = useCallback(
-    (provider: ProviderKind, model: string) => {
+    (instanceId: ProviderInstanceId, model: string) => {
       const newFavorites = [...favorites];
-      const index = newFavorites.findIndex((f) => f.provider === provider && f.model === model);
+      const index = newFavorites.findIndex((f) => f.provider === instanceId && f.model === model);
       if (index >= 0) {
         newFavorites.splice(index, 1);
       } else {
-        newFavorites.push({ provider, model });
+        newFavorites.push({ provider: instanceId, model });
       }
       updateSettings({ favorites: newFavorites });
     },
     [favorites, updateSettings],
   );
 
-  const isLocked = props.lockedProvider !== null;
-  const isSearching = searchQuery.trim().length > 0;
-  const showSidebar = !isLocked && !isSearching;
   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,
@@ -264,7 +392,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       if (!jumpCommand) {
         return mapping;
       }
-      mapping.set(`${model.provider}:${model.slug}`, jumpCommand);
+      mapping.set(`${model.instanceId}:${model.slug}`, jumpCommand);
     }
     return mapping;
   }, [filteredModels]);
@@ -273,16 +401,16 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
     [modelJumpCommandByKey],
   );
   const allModelKeys = useMemo(
-    (): string[] => flatModels.map((model) => `${model.provider}:${model.slug}`),
+    (): string[] => flatModels.map((model) => `${model.instanceId}:${model.slug}`),
     [flatModels],
   );
   const filteredModelKeys = useMemo(
-    (): string[] => filteredModels.map((model) => `${model.provider}:${model.slug}`),
+    (): string[] => filteredModels.map((model) => `${model.instanceId}:${model.slug}`),
     [filteredModels],
   );
   const filteredModelByKey = useMemo(
     (): ReadonlyMap<string, ModelPickerItem> =>
-      new Map(filteredModels.map((model) => [`${model.provider}:${model.slug}`, model] as const)),
+      new Map(filteredModels.map((model) => [`${model.instanceId}:${model.slug}`, model] as const)),
     [filteredModels],
   );
   const modelJumpShortcutContext = useMemo(
@@ -331,18 +459,10 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       if (!targetModelKey) {
         return;
       }
-      // Split on the first colon only — model slugs may themselves contain
-      // colons (e.g. "github-copilot:claude:opus") and `split(":")` would
-      // drop everything after the second segment.
-      const separatorIndex = targetModelKey.indexOf(":");
-      if (separatorIndex === -1) {
-        return;
-      }
-      const provider = targetModelKey.slice(0, separatorIndex) as ProviderKind;
-      const slug = targetModelKey.slice(separatorIndex + 1);
+      const { instanceId, slug } = splitInstanceModelKey(targetModelKey);
       event.preventDefault();
       event.stopPropagation();
-      handleModelSelect(slug, provider);
+      handleModelSelect(slug, instanceId);
     };
 
     window.addEventListener("keydown", onWindowKeyDown, true);
@@ -400,25 +520,25 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       <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 ? "flex-col" : "flex-row",
+          isLocked && !showLockedInstanceSidebar ? "flex-col" : "flex-row",
         )}
       >
         {/* Locked provider header (only shown in locked mode) */}
-        {isLocked && LockedProviderIcon && props.lockedProvider && (
+        {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">
-              {PROVIDER_DISPLAY_NAMES[props.lockedProvider]}
-            </span>
+            <span className="font-medium text-sm">{lockedHeaderLabel}</span>
           </div>
         )}
 
         {/* Sidebar (only in unlocked mode) */}
         {showSidebar && (
           <ModelPickerSidebar
-            selectedProvider={selectedProvider}
-            onSelectProvider={handleSelectProvider}
-            {...(props.providers && { providers: props.providers })}
+            selectedInstanceId={selectedInstanceId}
+            onSelectInstance={handleSelectInstance}
+            instanceEntries={sidebarInstanceEntries}
+            showFavorites={!isLocked}
+            showComingSoon={!isLocked}
           />
         )}
 
@@ -430,7 +550,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
           filter={null}
           autoHighlight
           open
-          value={`${props.provider}:${props.model}`}
+          value={`${props.activeInstanceId}:${props.model}`}
           onItemHighlighted={(modelKey) => {
             highlightedModelKeyRef.current = typeof modelKey === "string" ? modelKey : null;
           }}
@@ -438,14 +558,14 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
             if (typeof modelKey !== "string") {
               return;
             }
-            const [provider, slug] = modelKey.split(":") as [ProviderKind, string];
-            handleModelSelect(slug, provider);
+            const { instanceId, slug } = splitInstanceModelKey(modelKey);
+            handleModelSelect(slug, instanceId);
           }}
         >
           <div
             className={cn(
               "flex min-h-0 flex-1 flex-col overflow-hidden",
-              isLocked ? "min-w-0" : showSidebar && "border-l",
+              isLocked && !showLockedInstanceSidebar ? "min-w-0" : showSidebar && "border-l",
             )}
           >
             {/* Search bar */}
@@ -472,11 +592,10 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
                     ).preventBaseUIHandler?.();
                     e.preventDefault();
                     e.stopPropagation();
-                    const [provider, slug] = highlightedModelKeyRef.current.split(":") as [
-                      ProviderKind,
-                      string,
-                    ];
-                    handleModelSelect(slug, provider);
+                    const { instanceId, slug } = splitInstanceModelKey(
+                      highlightedModelKeyRef.current,
+                    );
+                    handleModelSelect(slug, instanceId);
                     return;
                   }
                   e.stopPropagation();
@@ -503,14 +622,17 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
                       key={modelKey}
                       index={index}
                       model={model}
-                      provider={model.provider}
+                      instanceId={model.instanceId}
+                      driverKind={model.driverKind}
+                      providerDisplayName={model.instanceDisplayName}
+                      providerAccentColor={model.instanceAccentColor}
                       isFavorite={favoritesSet.has(modelKey)}
-                      showProvider={!isLocked}
+                      showProvider={!isLocked || showLockedInstanceSidebar}
                       preferShortName={!isLocked}
-                      useTriggerLabel={isLocked}
-                      showNewBadge={isModelPickerNewModel(model.provider, model.slug)}
+                      useTriggerLabel={isLocked && !showLockedInstanceSidebar}
+                      showNewBadge={isModelPickerNewModel(model.driverKind, model.slug)}
                       jumpLabel={modelJumpLabelByKey.get(modelKey) ?? null}
-                      onToggleFavorite={() => toggleFavorite(model.provider, model.slug)}
+                      onToggleFavorite={() => toggleFavorite(model.instanceId, model.slug)}
                     />
                   );
                 })}
diff --git a/apps/web/src/components/chat/ModelPickerSidebar.tsx b/apps/web/src/components/chat/ModelPickerSidebar.tsx
index e3a5c571962..121b5267a3d 100644
--- a/apps/web/src/components/chat/ModelPickerSidebar.tsx
+++ b/apps/web/src/components/chat/ModelPickerSidebar.tsx
@@ -1,27 +1,32 @@
-import { type ProviderKind, type ServerProvider } from "@t3tools/contracts";
-import { memo } from "react";
+import { type ProviderInstanceId } from "@t3tools/contracts";
+import { memo, useMemo } from "react";
 import { Clock3Icon, SparklesIcon, StarIcon } from "lucide-react";
-import { AVAILABLE_PROVIDER_OPTIONS, PROVIDER_ICON_BY_PROVIDER } from "./providerIconUtils";
+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 { getProviderSnapshot } from "../../providerModels";
+import type { ProviderInstanceEntry } from "../../providerInstances";
 
-function describeUnavailableProvider(label: string, live: ServerProvider | undefined): string {
-  if (!live) {
-    return `${label} — waiting for provider status…`;
-  }
-  if (live.status === "ready") {
+/**
+ * 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 =
-    live.status === "error"
+    entry.status === "error"
       ? "Unavailable"
-      : live.status === "warning"
+      : entry.status === "warning"
         ? "Limited"
-        : live.status === "disabled"
+        : entry.status === "disabled"
           ? "Disabled in settings"
           : "Not ready";
-  const msg = live.message?.trim();
+  const msg = entry.snapshot.message?.trim();
   return msg ? `${label} — ${kind}. ${msg}` : `${label} — ${kind}.`;
 }
 
@@ -38,119 +43,221 @@ 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: {
-  selectedProvider: ProviderKind | "favorites";
-  onSelectProvider: (provider: ProviderKind | "favorites") => void;
-  providers?: ReadonlyArray<ServerProvider>;
+  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 handleProviderClick = (provider: ProviderKind | "favorites") => {
-    props.onSelectProvider(provider);
+  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 (
-    <div className="flex flex-col w-12 border-r bg-muted/30  p-1 overflow-y-auto gap-1">
-      {/* Favorites section */}
-      <div className="pb-1 mb-1 border-b">
-        <div className="relative w-full">
-          {props.selectedProvider === "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.selectedProvider === "favorites" && SELECTED_BUTTON_CLASS,
-                  )}
-                  onClick={() => handleProviderClick("favorites")}
-                  type="button"
-                  data-model-picker-provider="favorites"
-                  aria-label="Favorites"
+    <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}
                 >
-                  <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>
+                  Favorites
+                </TooltipPopup>
+              </Tooltip>
+            </div>
+          </div>
+        ) : null}
 
-      {/* Provider buttons */}
-      {AVAILABLE_PROVIDER_OPTIONS.map((option) => {
-        const OptionIcon = PROVIDER_ICON_BY_PROVIDER[option.value];
-        const liveProvider = props.providers
-          ? getProviderSnapshot(props.providers, option.value)
-          : undefined;
+        {/* 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 isDisabled = !liveProvider || liveProvider.status !== "ready";
-        const isSelected = props.selectedProvider === option.value;
-        const badge = option.pickerSidebarBadge;
+          const tooltip = isDisabled
+            ? describeUnavailableInstance(entry)
+            : showNewBadge
+              ? `${entry.displayName} — New`
+              : entry.displayName;
 
-        const providerTooltip = isDisabled
-          ? describeUnavailableProvider(option.label, liveProvider)
-          : badge === "new"
-            ? `${option.label} — New`
-            : option.label;
+          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 button = (
-          <button
-            data-model-picker-provider={option.value}
-            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",
-            )}
-            onClick={() => !isDisabled && handleProviderClick(option.value)}
-            disabled={isDisabled}
-            type="button"
-            aria-label={
-              isDisabled
-                ? (providerTooltip ?? option.label)
-                : badge === "new"
-                  ? `${option.label}, new`
-                  : option.label
-            }
-          >
-            <OptionIcon className="size-5 shrink-0" aria-hidden />
-            {badge === "new" ? (
-              <span className={NEW_BADGE_CLASS} aria-hidden>
-                <SparklesIcon className="size-2" />
-              </span>
-            ) : badge === "soon" ? (
-              <span className={SOON_BADGE_CLASS} aria-hidden>
-                <Clock3Icon className="size-2" />
-              </span>
-            ) : null}
-          </button>
-        );
+          const trigger = isDisabled ? (
+            <span className="relative block w-full">{button}</span>
+          ) : (
+            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>
+          );
+        })}
 
-        return (
-          <div key={option.value} className="relative w-full">
-            {isSelected && <div className={SELECTED_INDICATOR_CLASS} />}
+        {showComingSoon ? (
+          <>
+            {/* Gemini button (coming soon) */}
             <Tooltip>
-              <TooltipTrigger render={trigger} />
+              <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}
               >
-                {providerTooltip}
+                Gemini — Coming soon
               </TooltipPopup>
             </Tooltip>
-          </div>
-        );
-      })}
-    </div>
+            {/* 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/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 c827febf042..d3b168876a6 100644
--- a/apps/web/src/components/chat/ProviderModelPicker.browser.tsx
+++ b/apps/web/src/components/chat/ProviderModelPicker.browser.tsx
@@ -1,12 +1,22 @@
-import { type ProviderKind, type ServerProvider } from "@t3tools/contracts";
+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_CLIENT_SETTINGS, 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";
 
 // Mock the environments/runtime module to provide a mock primary environment connection
@@ -66,17 +76,35 @@ vi.mock("../../environments/runtime", () => {
   };
 });
 
-function effort(value: string, isDefault = false) {
+function selectDescriptor(
+  id: string,
+  label: string,
+  options: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>,
+) {
   return {
-    value,
-    label: value,
-    ...(isDefault ? { isDefault: true } : {}),
+    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,
   };
 }
 
 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",
@@ -90,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",
@@ -127,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",
@@ -190,7 +233,8 @@ function buildCodexProvider(models: ServerProvider["models"]): ServerProvider {
 
 function buildOpenCodeProvider(models: ServerProvider["models"]): ServerProvider {
   return {
-    provider: "opencode",
+    driver: ProviderDriverKind.make("opencode"),
+    instanceId: ProviderInstanceId.make("opencode"),
     enabled: true,
     installed: true,
     version: "1.0.0",
@@ -204,37 +248,47 @@ function buildOpenCodeProvider(models: ServerProvider["models"]): ServerProvider
 }
 
 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();
@@ -277,7 +331,7 @@ describe("ProviderModelPicker", () => {
 
   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,
     });
@@ -298,7 +352,7 @@ describe("ProviderModelPicker", () => {
 
   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,
     });
@@ -307,11 +361,9 @@ describe("ProviderModelPicker", () => {
       await page.getByRole("button").click();
 
       await vi.waitFor(() => {
-        // Fork: sidebar order includes copilot between codex and claudeAgent.
-        expect(getSidebarProviderOrder().slice(0, 4)).toEqual([
+        expect(getSidebarProviderOrder().slice(0, 3)).toEqual([
           "favorites",
           "codex",
-          "copilot",
           "claudeAgent",
         ]);
       });
@@ -322,7 +374,7 @@ describe("ProviderModelPicker", () => {
 
   it("filters models by selected provider in sidebar", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -333,7 +385,7 @@ describe("ProviderModelPicker", () => {
       // Start with Claude models visible
       await vi.waitFor(() => {
         const text = document.body.textContent ?? "";
-        expect(text).not.toContain("GPT-5.3 Codex");
+        expect(text).not.toContain("GPT-5 Codex");
         expect(text).toContain("Claude Opus 4.6");
       });
 
@@ -346,7 +398,7 @@ describe("ProviderModelPicker", () => {
       // Now should only show Codex models
       await vi.waitFor(() => {
         const listText = getModelPickerListText();
-        expect(listText).toContain("GPT-5.3 Codex");
+        expect(listText).toContain("GPT-5 Codex");
         expect(listText).not.toContain("Claude Opus 4.6");
       });
     } finally {
@@ -354,9 +406,37 @@ describe("ProviderModelPicker", () => {
     }
   });
 
+  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({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -394,9 +474,9 @@ describe("ProviderModelPicker", () => {
     );
 
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
-      lockedProvider: "claudeAgent",
+      lockedProvider: ProviderDriverKind.make("claudeAgent"),
     });
 
     try {
@@ -406,14 +486,9 @@ describe("ProviderModelPicker", () => {
         const text = document.body.textContent ?? "";
         // Should show locked provider label
         expect(text).toContain("Claude");
-        // Fork: production claudeAgent model list now includes Opus 4.7 and 4.5
-        // in addition to Opus 4.6, Sonnet 4.6 and Haiku 4.5. Favorite (Sonnet)
-        // surfaces first, then remaining models in production order.
         expect(getVisibleModelNames()).toEqual([
           "Claude Sonnet 4.6",
-          "Claude Opus 4.7",
           "Claude Opus 4.6",
-          "Claude Opus 4.5",
           "Claude Haiku 4.5",
         ]);
       });
@@ -423,31 +498,115 @@ describe("ProviderModelPicker", () => {
     }
   });
 
+  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 onProviderModelChange = vi.fn();
-    const modelOptionsByProvider = {
-      claudeAgent: [
-        { slug: "claude-opus-4-6", name: "Claude Opus 4.6" },
-        { slug: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
+    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: [{ slug: "gpt-5-codex", name: "GPT-5 Codex" }],
-      cursor: [],
-      opencode: [],
-      copilot: [],
-      geminiCli: [],
-      amp: [],
-      kilo: [],
-    } as const;
+      ["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
-        provider="claudeAgent"
+        activeInstanceId={"claudeAgent" as ProviderInstanceId}
         model="gpt-5-codex"
         lockedProvider={null}
-        providers={TEST_PROVIDERS}
-        modelOptionsByProvider={modelOptionsByProvider}
-        onProviderModelChange={onProviderModelChange}
+        instanceEntries={instanceEntries}
+        modelOptionsByInstance={modelOptionsByInstance}
+        onInstanceModelChange={onInstanceModelChange}
       />,
       { container: host },
     );
@@ -466,13 +625,7 @@ describe("ProviderModelPicker", () => {
     }
   });
 
-  // Fork: getCustomModelOptionsByProvider reads from the static MODEL_OPTIONS_BY_PROVIDER
-  // list (keyed on settings.providers[x].customModels) and does not merge live provider
-  // `models` — so subProvider / shortName metadata supplied via server-reported model
-  // entries never reaches the picker's trigger. Testing that enrichment path would
-  // require changing production wiring; see ChatComposer.modelOptionsByProvider which
-  // uses providerStatuses.models directly in the real app.
-  it.skip("uses the trigger label for locked opencode rows", async () => {
+  it("uses the trigger label for locked opencode rows", async () => {
     const providers: ReadonlyArray<ServerProvider> = [
       buildOpenCodeProvider([
         {
@@ -481,20 +634,22 @@ describe("ProviderModelPicker", () => {
           subProvider: "GitHub Copilot",
           shortName: "Opus 4.5",
           isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-            supportsFastMode: false,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+            ],
+          }),
         },
       ]),
     ];
     const mounted = await mountPicker({
-      provider: "opencode",
+      activeInstanceId: OPENCODE_INSTANCE_ID,
       model: "github-copilot/claude-opus-4.5",
-      lockedProvider: "opencode",
+      lockedProvider: ProviderDriverKind.make("opencode"),
       providers,
     });
 
@@ -519,7 +674,7 @@ describe("ProviderModelPicker", () => {
 
   it("searches models by name in flat list", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -549,9 +704,9 @@ describe("ProviderModelPicker", () => {
 
   it("supports arrow-key navigation in the model picker", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
-      lockedProvider: "claudeAgent",
+      lockedProvider: ProviderDriverKind.make("claudeAgent"),
     });
 
     try {
@@ -560,13 +715,12 @@ describe("ProviderModelPicker", () => {
       const searchInput = page.getByPlaceholder("Search models...");
       await userEvent.click(searchInput);
       await userEvent.keyboard("{ArrowDown}");
-      // Fork: production claudeAgent list now starts with Claude Opus 4.7.
       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.7");
+        expect(highlightedItem?.textContent).toContain("Claude Opus 4.6");
       });
       await userEvent.keyboard("{ArrowDown}");
       await vi.waitFor(() => {
@@ -574,11 +728,14 @@ describe("ProviderModelPicker", () => {
           '[data-slot="combobox-item"][data-highlighted]',
         );
         expect(highlightedItem).not.toBeNull();
-        expect(highlightedItem?.textContent).toContain("Claude Opus 4.6");
+        expect(highlightedItem?.textContent).toContain("Claude Sonnet 4.6");
       });
       await userEvent.keyboard("{Enter}");
 
-      expect(mounted.onProviderModelChange).toHaveBeenCalledWith("claudeAgent", "claude-opus-4-6");
+      expect(mounted.onProviderModelChange).toHaveBeenCalledWith(
+        "claudeAgent",
+        "claude-sonnet-4-6",
+      );
     } finally {
       await mounted.cleanup();
     }
@@ -586,7 +743,7 @@ describe("ProviderModelPicker", () => {
 
   it("hides the provider sidebar while searching", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -610,7 +767,7 @@ describe("ProviderModelPicker", () => {
 
   it("closes the picker when escape is pressed in search", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -638,7 +795,7 @@ describe("ProviderModelPicker", () => {
 
   it("searches models by provider name", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -649,7 +806,7 @@ describe("ProviderModelPicker", () => {
       await vi.waitFor(() => {
         const text = document.body.textContent ?? "";
         expect(text).toContain("Claude Opus 4.6");
-        expect(text).not.toContain("GPT-5.3 Codex");
+        expect(text).not.toContain("GPT-5 Codex");
       });
 
       // Search by provider name
@@ -658,7 +815,7 @@ describe("ProviderModelPicker", () => {
 
       await vi.waitFor(() => {
         const listText = getModelPickerListText();
-        expect(listText).toContain("GPT-5.3 Codex");
+        expect(listText).toContain("GPT-5 Codex");
         expect(listText).not.toContain("Claude Opus 4.6");
       });
     } finally {
@@ -667,56 +824,57 @@ describe("ProviderModelPicker", () => {
   });
 
   it("matches fuzzy multi-token queries across provider and model text", async () => {
-    // Fork: getCustomModelOptionsByProvider reads from the static
-    // MODEL_OPTIONS_BY_PROVIDER list and does not merge server-reported model
-    // names, so we assert against the static opencode option "Anthropic /
-    // Claude Opus 4.7" using a query that fuzzily matches across the combined
-    // provider/model search fields.
     const providers: ReadonlyArray<ServerProvider> = [
       buildCodexProvider([
         {
-          slug: "gpt-5.3-codex",
-          name: "GPT-5.3 Codex",
+          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"),
+            ],
+          }),
         },
       ]),
       buildOpenCodeProvider([
         {
-          slug: "anthropic/claude-opus-4-7",
-          name: "Anthropic / Claude Opus 4.7",
+          slug: "github-copilot/claude-opus-4.7",
+          name: "Claude Opus 4.7",
+          subProvider: "GitHub Copilot",
           isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-            supportsFastMode: false,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+            ],
+          }),
         },
       ]),
     ];
     const mounted = await mountPicker({
-      provider: "opencode",
-      model: "anthropic/claude-opus-4-7",
+      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("opcd anth op");
+      await page.getByPlaceholder("Search models...").fill("coplt op");
 
       await vi.waitFor(() => {
         const listText = getModelPickerListText();
-        expect(listText).toContain("Anthropic / Claude Opus 4.7");
-        expect(listText).not.toContain("GPT-5.3 Codex");
+        expect(listText).toContain("Claude Opus 4.7");
+        expect(listText).not.toContain("GPT-5 Codex");
       });
     } finally {
       await mounted.cleanup();
@@ -724,24 +882,22 @@ describe("ProviderModelPicker", () => {
   });
 
   it("renders each search result with its own provider branding", async () => {
-    // Fork: getCustomModelOptionsByProvider reads static MODEL_OPTIONS_BY_PROVIDER
-    // and does not merge subProvider metadata from server-reported models.
-    // Instead of asserting the "OpenCode · GitHub Copilot" combined label, we
-    // assert each matching row carries its own provider label alongside its
-    // model name (Claude for claudeAgent rows, OpenCode for opencode rows).
     const providers: ReadonlyArray<ServerProvider> = [
       buildOpenCodeProvider([
         {
-          slug: "anthropic/claude-opus-4-7",
-          name: "Anthropic / Claude Opus 4.7",
+          slug: "github-copilot/claude-opus-4.7",
+          name: "Claude Opus 4.7",
+          subProvider: "GitHub Copilot",
           isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [effort("low"), effort("medium", true), effort("high")],
-            supportsFastMode: false,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
+          capabilities: createModelCapabilities({
+            optionDescriptors: [
+              selectDescriptor("reasoningEffort", "Reasoning", [
+                { id: "low", label: "low" },
+                { id: "medium", label: "medium", isDefault: true },
+                { id: "high", label: "high" },
+              ]),
+            ],
+          }),
         },
       ]),
       {
@@ -751,25 +907,24 @@ describe("ProviderModelPicker", () => {
             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: [],
-            },
+            }),
           },
         ],
       },
     ];
     const mounted = await mountPicker({
-      provider: "opencode",
-      model: "anthropic/claude-opus-4-7",
+      activeInstanceId: OPENCODE_INSTANCE_ID,
+      model: "github-copilot/claude-opus-4.7",
       lockedProvider: null,
       providers,
     });
@@ -780,14 +935,8 @@ describe("ProviderModelPicker", () => {
 
       await vi.waitFor(() => {
         const listText = getModelPickerListText();
-        // Both the claudeAgent and opencode results show in search.
-        expect(listText).toContain("Claude Opus 4.6");
-        expect(listText).toContain("Anthropic / Claude Opus 4.7");
-        // Each row carries its own provider label rather than sharing one.
-        expect(listText).toContain("OpenCode");
+        expect(listText).toContain("OpenCode · GitHub Copilot");
         expect(listText).toContain("Claude");
-        // Anti-assertion: rows should not be conflated — "OpenCode" should
-        // never appear directly abutting the claudeAgent row's model name.
         expect(listText).not.toContain("OpenCodeClaude Opus 4.6");
       });
     } finally {
@@ -799,7 +948,7 @@ describe("ProviderModelPicker", () => {
     localStorage.removeItem("t3code:client-settings:v1");
 
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -844,7 +993,7 @@ describe("ProviderModelPicker", () => {
     localStorage.removeItem("t3code:client-settings:v1");
 
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
       lockedProvider: null,
     });
@@ -875,8 +1024,6 @@ describe("ProviderModelPicker", () => {
   });
 
   it("shows favorited models first within the selected provider list", async () => {
-    // Fork: static codex model list starts with GPT-5.4, GPT-5.4 Mini, so
-    // after favoriting GPT-5.3 Codex it should float to the top of the list.
     localStorage.setItem(
       "t3code:client-settings:v1",
       JSON.stringify({
@@ -886,8 +1033,7 @@ describe("ProviderModelPicker", () => {
     );
 
     const mounted = await mountPicker({
-      provider: "codex",
-      model: "gpt-5.3-codex",
+      model: "gpt-5-codex",
       lockedProvider: null,
     });
 
@@ -896,7 +1042,7 @@ describe("ProviderModelPicker", () => {
       await page.getByRole("button", { name: "Codex", exact: true }).click();
 
       await vi.waitFor(() => {
-        expect(getVisibleModelNames().slice(0, 2)).toEqual(["GPT-5.3 Codex", "GPT-5.4"]);
+        expect(getVisibleModelNames().slice(0, 2)).toEqual(["GPT-5.3 Codex", "GPT-5 Codex"]);
       });
     } finally {
       await mounted.cleanup();
@@ -906,9 +1052,9 @@ describe("ProviderModelPicker", () => {
 
   it("dispatches callback with correct provider and model when selected", async () => {
     const mounted = await mountPicker({
-      provider: "claudeAgent",
+      activeInstanceId: CLAUDE_INSTANCE_ID,
       model: "claude-opus-4-6",
-      lockedProvider: "claudeAgent",
+      lockedProvider: ProviderDriverKind.make("claudeAgent"),
     });
 
     try {
@@ -933,25 +1079,23 @@ describe("ProviderModelPicker", () => {
     }
   });
 
-  // TODO: Fork's getCustomModelOptionsByProvider reads the static
-  // MODEL_OPTIONS_BY_PROVIDER list (which always contains gpt-5.3-codex-spark)
-  // and does not filter by server-reported models, so the "hidden" assertion
-  // cannot hold without rewiring production code. Re-enable once the picker
-  // sources model options from providers[x].models instead.
-  it.skip("only shows codex spark when the server reports it", 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]!,
@@ -962,32 +1106,37 @@ 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: "codex",
       model: "gpt-5.3-codex",
       lockedProvider: null,
       providers: providersWithoutSpark,
@@ -1006,7 +1155,6 @@ describe("ProviderModelPicker", () => {
     }
 
     const visible = await mountPicker({
-      provider: "codex",
       model: "gpt-5.3-codex",
       lockedProvider: null,
       providers: providersWithSpark,
@@ -1026,7 +1174,7 @@ describe("ProviderModelPicker", () => {
   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]!;
@@ -1038,8 +1186,7 @@ describe("ProviderModelPicker", () => {
     }
 
     const mounted = await mountPicker({
-      provider: "codex",
-      model: "gpt-5.3-codex",
+      model: "gpt-5-codex",
       lockedProvider: null,
       providers: disabledProviders,
     });
@@ -1048,11 +1195,10 @@ describe("ProviderModelPicker", () => {
       await page.getByRole("button").click();
 
       await vi.waitFor(() => {
-        const listText = getModelPickerListText();
-        // Codex (enabled, selected) models are visible.
-        expect(listText).toContain("GPT-5.3 Codex");
-        // Disabled claudeAgent models should not appear in the list.
-        expect(listText).not.toContain("Claude Opus 4.6");
+        const text = document.body.textContent ?? "";
+        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();
@@ -1061,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.logic.test.ts b/apps/web/src/components/chat/ProviderModelPicker.logic.test.ts
deleted file mode 100644
index 60a44bc4590..00000000000
--- a/apps/web/src/components/chat/ProviderModelPicker.logic.test.ts
+++ /dev/null
@@ -1,93 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { MODEL_OPTIONS_BY_PROVIDER } from "@t3tools/contracts";
-
-import { resolveModelOptionsByProvider } from "../../providerModelOptions";
-
-const EMPTY_CUSTOM_MODELS = {
-  customCodexModels: [],
-  customCopilotModels: [],
-  customClaudeModels: [],
-  customCursorModels: [],
-  customOpencodeModels: [],
-  customGeminiCliModels: [],
-  customAmpModels: [],
-  customKiloModels: [],
-} as const;
-
-describe("resolveModelOptionsByProvider", () => {
-  it("keeps built-in model catalogs when the server has no snapshot for a provider", () => {
-    const modelOptions = resolveModelOptionsByProvider(EMPTY_CUSTOM_MODELS);
-
-    expect(modelOptions.copilot.length).toBeGreaterThan(0);
-    expect(modelOptions.cursor.length).toBeGreaterThan(0);
-    expect(modelOptions.opencode.length).toBeGreaterThan(0);
-    expect(modelOptions.geminiCli.length).toBeGreaterThan(0);
-    expect(modelOptions.amp.length).toBeGreaterThan(0);
-    expect(modelOptions.kilo.length).toBeGreaterThan(0);
-    for (const provider of ["copilot", "cursor", "opencode", "geminiCli", "amp", "kilo"] as const) {
-      expect(
-        modelOptions[provider].some(
-          (option) => option.slug === MODEL_OPTIONS_BY_PROVIDER[provider][0]?.slug,
-        ),
-      ).toBe(true);
-    }
-  });
-
-  it("merges discovered provider models on top of the built-in fallback list", () => {
-    const modelOptions = resolveModelOptionsByProvider({
-      ...EMPTY_CUSTOM_MODELS,
-      discovered: {
-        opencode: [
-          { slug: "openai/gpt-5", name: "OpenAI / GPT-5", connected: true },
-          { slug: "anthropic/sonnet", name: "Anthropic / Sonnet", connected: false },
-        ],
-        kilo: [{ slug: "openai/gpt-5", name: "OpenAI / GPT-5", connected: true }],
-        copilot: [{ slug: "gpt-5.4", name: "GPT-5.4", pricingTier: "1x" }],
-      },
-    });
-
-    expect(modelOptions.opencode[0]).toEqual({
-      slug: "anthropic/sonnet",
-      name: "Anthropic / Sonnet",
-      connected: false,
-    });
-    expect(modelOptions.opencode).toContainEqual({
-      slug: "openai/gpt-5",
-      name: "OpenAI / GPT-5",
-      connected: true,
-      isCustom: false,
-    });
-    expect(modelOptions.kilo).toContainEqual({
-      slug: "openai/gpt-5",
-      name: "OpenAI / GPT-5",
-      connected: true,
-      isCustom: false,
-    });
-    expect(modelOptions.copilot.find((option) => option.slug === "gpt-5.4")?.pricingTier).toBe(
-      "1x",
-    );
-  });
-
-  it("retains copilot fallback models when discovery only returns a partial snapshot", () => {
-    const baseCopilotModels = MODEL_OPTIONS_BY_PROVIDER.copilot.map((option) => option.slug);
-    const firstFallbackSlug = baseCopilotModels[0];
-    const secondFallbackSlug = baseCopilotModels.find((slug) => slug !== firstFallbackSlug);
-
-    expect(firstFallbackSlug).toBeTruthy();
-    expect(secondFallbackSlug).toBeTruthy();
-
-    const modelOptions = resolveModelOptionsByProvider({
-      ...EMPTY_CUSTOM_MODELS,
-      discovered: {
-        copilot: [{ slug: firstFallbackSlug!, name: "Refreshed Copilot Model", pricingTier: "1x" }],
-      },
-    });
-
-    expect(modelOptions.copilot.find((option) => option.slug === firstFallbackSlug)).toMatchObject({
-      slug: firstFallbackSlug,
-      name: "Refreshed Copilot Model",
-      pricingTier: "1x",
-    });
-    expect(modelOptions.copilot.some((option) => option.slug === secondFallbackSlug)).toBe(true);
-  });
-});
diff --git a/apps/web/src/components/chat/ProviderModelPicker.tsx b/apps/web/src/components/chat/ProviderModelPicker.tsx
index 4f4140f834d..4a2860ee469 100644
--- a/apps/web/src/components/chat/ProviderModelPicker.tsx
+++ b/apps/web/src/components/chat/ProviderModelPicker.tsx
@@ -1,9 +1,9 @@
 import {
-  type ProviderKind,
+  type ProviderInstanceId,
+  type ProviderDriverKind,
   type ResolvedKeybindingsConfig,
-  type ServerProvider,
 } from "@t3tools/contracts";
-import { memo, useEffect, useState } from "react";
+import { memo, useEffect, useMemo, useState } from "react";
 import type { VariantProps } from "class-variance-authority";
 import { ChevronDownIcon } from "lucide-react";
 import { Button, buttonVariants } from "../ui/button";
@@ -11,21 +11,28 @@ import { Popover, PopoverPopup, PopoverTrigger } from "../ui/popover";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { cn } from "~/lib/utils";
 import { ModelPickerContent } from "./ModelPickerContent";
+import { ProviderInstanceIcon } from "./ProviderInstanceIcon";
 import {
   ModelEsque,
-  PROVIDER_ICON_BY_PROVIDER,
   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>;
+  lockedProvider: ProviderDriverKind | null;
+  lockedContinuationGroupKey?: string | null;
+  /** Instance entries rendered in the sidebar + used to resolve display name. */
+  instanceEntries: ReadonlyArray<ProviderInstanceEntry>;
   keybindings?: ResolvedKeybindingsConfig;
-  modelOptionsByProvider: Record<ProviderKind, ReadonlyArray<ModelEsque>>;
+  modelOptionsByInstance: ReadonlyMap<ProviderInstanceId, ReadonlyArray<ModelEsque>>;
   activeProviderIconClassName?: string;
   compact?: boolean;
   disabled?: boolean;
@@ -34,22 +41,36 @@ export const ProviderModelPicker = memo(function ProviderModelPicker(props: {
   triggerVariant?: VariantProps<typeof buttonVariants>["variant"];
   triggerClassName?: string;
   onOpenChange?: (open: boolean) => void;
-  onProviderModelChange: (provider: ProviderKind, model: string) => void;
+  onInstanceModelChange: (instanceId: ProviderInstanceId, model: string) => void;
 }) {
   const [uncontrolledIsMenuOpen, setUncontrolledIsMenuOpen] = useState(false);
-  const activeProvider = props.lockedProvider ?? props.provider;
   const isMenuOpen = props.open ?? uncontrolledIsMenuOpen;
-  const selectedProviderOptions = props.modelOptionsByProvider[activeProvider];
-  // If the current slug belongs to a different provider (for example after a provider
-  // switch or disable), prefer the active provider's first option so the trigger icon
-  // and label stay in sync instead of showing a stale foreign slug.
+
+  // 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
+    );
+  }, [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 =
-    selectedProviderOptions.find((option) => option.slug === props.model) ??
-    selectedProviderOptions[0];
-  const ProviderIcon = PROVIDER_ICON_BY_PROVIDER[activeProvider];
+    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);
@@ -65,9 +86,9 @@ export const ProviderModelPicker = memo(function ProviderModelPicker(props: {
     };
   }, [isMenuOpen]);
 
-  const handleProviderModelChange = (provider: ProviderKind, model: string) => {
+  const handleInstanceModelChange = (instanceId: ProviderInstanceId, model: string) => {
     if (props.disabled) return;
-    props.onProviderModelChange(provider, model);
+    props.onInstanceModelChange(instanceId, model);
     setIsMenuOpen(false);
   };
 
@@ -103,10 +124,17 @@ 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", props.activeProviderIconClassName)}
-          />
+          {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={
@@ -142,15 +170,16 @@ export const ProviderModelPicker = memo(function ProviderModelPicker(props: {
         className="border-0 bg-transparent p-0 shadow-none before:hidden [--viewport-inline-padding:0] *:data-[slot=popover-viewport]:p-0"
       >
         <ModelPickerContent
-          provider={props.provider}
+          activeInstanceId={activeInstanceId}
           model={props.model}
           lockedProvider={props.lockedProvider}
-          {...(props.providers && { providers: props.providers })}
+          lockedContinuationGroupKey={props.lockedContinuationGroupKey ?? null}
+          instanceEntries={props.instanceEntries}
           {...(props.keybindings ? { keybindings: props.keybindings } : {})}
-          modelOptionsByProvider={props.modelOptionsByProvider}
+          modelOptionsByInstance={props.modelOptionsByInstance}
           terminalOpen={props.terminalOpen ?? false}
           onRequestClose={() => setIsMenuOpen(false)}
-          onProviderModelChange={handleProviderModelChange}
+          onInstanceModelChange={handleInstanceModelChange}
         />
       </PopoverPopup>
     </Popover>
diff --git a/apps/web/src/components/chat/ProviderStatusBanner.tsx b/apps/web/src/components/chat/ProviderStatusBanner.tsx
index 5eaacafe052..a882942585f 100644
--- a/apps/web/src/components/chat/ProviderStatusBanner.tsx
+++ b/apps/web/src/components/chat/ProviderStatusBanner.tsx
@@ -2,7 +2,7 @@ import { type ServerProvider } from "@t3tools/contracts";
 import { memo } from "react";
 import { Alert, AlertDescription, AlertTitle } from "../ui/alert";
 import { CircleAlertIcon } from "lucide-react";
-import { formatProviderKindLabel } from "../../providerModels";
+import { formatProviderDriverKindLabel } from "../../providerModels";
 
 export const ProviderStatusBanner = memo(function ProviderStatusBanner({
   status,
@@ -13,7 +13,7 @@ export const ProviderStatusBanner = memo(function ProviderStatusBanner({
     return null;
   }
 
-  const providerLabel = status.displayName?.trim() || formatProviderKindLabel(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/TraitsPicker.browser.tsx b/apps/web/src/components/chat/TraitsPicker.browser.tsx
deleted file mode 100644
index 992558fa9e4..00000000000
--- a/apps/web/src/components/chat/TraitsPicker.browser.tsx
+++ /dev/null
@@ -1,803 +0,0 @@
-import "../../index.css";
-
-import {
-  type ModelSelection,
-  ClaudeModelOptions,
-  CodexModelOptions,
-  CursorModelOptions,
-  DEFAULT_MODEL_BY_PROVIDER,
-  DEFAULT_SERVER_SETTINGS,
-  OpenCodeModelOptions,
-  EnvironmentId,
-  type ServerProvider,
-  ThreadId,
-} from "@t3tools/contracts";
-import { scopedThreadKey, scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
-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";
-
-// ── 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: "opencode",
-    enabled: true,
-    installed: true,
-    version: "0.1.0",
-    status: "ready",
-    auth: { status: "authenticated" },
-    checkedAt: "2026-01-01T00:00:00.000Z",
-    slashCommands: [],
-    skills: [],
-    models: [
-      {
-        slug: "openai/gpt-5",
-        name: "GPT-5",
-        isCustom: false,
-        capabilities: {
-          reasoningEffortLevels: [],
-          supportsFastMode: false,
-          supportsThinkingToggle: false,
-          contextWindowOptions: [],
-          promptInjectedEffortLevels: [],
-          variantOptions: [
-            { value: "low", label: "Low" },
-            { value: "medium", label: "Medium", isDefault: true },
-          ],
-          agentOptions: [
-            { value: "build", label: "Build", isDefault: true },
-            { value: "plan", label: "Plan" },
-          ],
-        },
-      },
-    ],
-  },
-  {
-    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: [],
-        },
-      },
-    ],
-  },
-];
-const findTestProvider = (provider: ServerProvider["provider"]) => {
-  const testProvider = TEST_PROVIDERS.find((candidate) => candidate.provider === provider);
-  if (!testProvider) {
-    throw new Error(`Missing test provider fixture: ${provider}`);
-  }
-  return testProvider;
-};
-
-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_UNIFIED_SETTINGS,
-  });
-  const handlePromptChange = useCallback(
-    (nextPrompt: string) => {
-      setPrompt(CLAUDE_THREAD_REF, nextPrompt);
-    },
-    [setPrompt],
-  );
-
-  return (
-    <TraitsPicker
-      provider="claudeAgent"
-      models={TEST_PROVIDERS[2]!.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 = "";
-    localStorage.removeItem(COMPOSER_DRAFT_STORAGE_KEY);
-    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 thinking 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 disabled 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).toContain("Remove Ultrathink from the prompt to change effort.");
-      expect(text).not.toContain("Fallback 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,
-  };
-}
-
-async function mountCursorPicker(props: { model?: string; options?: CursorModelOptions }) {
-  const model = props.model ?? DEFAULT_MODEL_BY_PROVIDER.cursor;
-  const cursorThreadId = ThreadId.make("thread-cursor-traits");
-  const cursorThreadRef = scopeThreadRef(LOCAL_ENVIRONMENT_ID, cursorThreadId);
-  const cursorThreadKey = scopedThreadKey(cursorThreadRef);
-  const host = document.createElement("div");
-  document.body.append(host);
-
-  useComposerDraftStore.setState({
-    draftsByThreadKey: {
-      [cursorThreadKey]: {
-        prompt: "",
-        images: [],
-        nonPersistedImageIds: [],
-        persistedAttachments: [],
-        terminalContexts: [],
-        modelSelectionByProvider: {
-          cursor: {
-            provider: "cursor",
-            model,
-            ...(props.options ? { options: props.options } : {}),
-          },
-        },
-        activeProvider: "cursor",
-        runtimeMode: null,
-        interactionMode: null,
-      },
-    },
-    draftThreadsByThreadKey: {},
-    logicalProjectDraftThreadKeyByLogicalProjectKey: {},
-  });
-
-  const screen = await render(
-    <TraitsPicker
-      provider="cursor"
-      models={[
-        {
-          slug: "composer-2",
-          name: "Composer 2",
-          isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [],
-            supportsFastMode: true,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-          },
-        },
-        {
-          slug: "claude-opus-4-6",
-          name: "Opus 4.6",
-          isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [],
-            supportsFastMode: true,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [
-              { value: "200k", label: "200K", isDefault: true },
-              { value: "1m", label: "1M" },
-            ],
-            promptInjectedEffortLevels: [],
-          },
-        },
-      ]}
-      threadRef={cursorThreadRef}
-      model={model}
-      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 },
-    });
-  });
-});
-
-// ── OpenCode TraitsPicker tests ───────────────────────────────────────
-
-async function mountOpenCodePicker(props: {
-  model?: string;
-  options?: OpenCodeModelOptions;
-  models?: ServerProvider["models"];
-}) {
-  const threadId = ThreadId.make("thread-opencode-traits");
-  const threadRef = scopeThreadRef(LOCAL_ENVIRONMENT_ID, threadId);
-  const threadKey = scopedThreadKey(threadRef);
-  const model = props.model ?? DEFAULT_MODEL_BY_PROVIDER.opencode;
-  const draftsByThreadKey: Record<string, ComposerThreadDraftState> = {
-    [threadKey]: {
-      prompt: "",
-      images: [],
-      nonPersistedImageIds: [],
-      persistedAttachments: [],
-      terminalContexts: [],
-      modelSelectionByProvider: {
-        opencode: {
-          provider: "opencode",
-          model,
-          ...(props.options ? { options: props.options } : {}),
-        },
-      },
-      activeProvider: "opencode",
-      runtimeMode: null,
-      interactionMode: null,
-    },
-  };
-
-  useComposerDraftStore.setState({
-    draftsByThreadKey,
-    draftThreadsByThreadKey: {},
-    logicalProjectDraftThreadKeyByLogicalProjectKey: {},
-  });
-  const host = document.createElement("div");
-  document.body.append(host);
-  const screen = await render(
-    <TraitsPicker
-      provider="opencode"
-      models={props.models ?? findTestProvider("opencode").models}
-      threadRef={threadRef}
-      model={model}
-      prompt=""
-      modelOptions={props.options}
-      onPromptChange={() => {}}
-    />,
-    { container: host },
-  );
-
-  const cleanup = async () => {
-    await screen.unmount();
-    host.remove();
-  };
-
-  return {
-    [Symbol.asyncDispose]: cleanup,
-    cleanup,
-  };
-}
-
-describe("TraitsPicker (OpenCode)", () => {
-  afterEach(() => {
-    document.body.innerHTML = "";
-    localStorage.removeItem(COMPOSER_DRAFT_STORAGE_KEY);
-    useComposerDraftStore.setState({
-      draftsByThreadKey: {},
-      draftThreadsByThreadKey: {},
-      logicalProjectDraftThreadKeyByLogicalProjectKey: {},
-      stickyModelSelectionByProvider: {},
-    });
-  });
-
-  it("shows the selected agent label with capitalization in the trigger", async () => {
-    await using _ = await mountOpenCodePicker({
-      options: {
-        variant: "medium",
-        agent: "plan",
-      },
-    });
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Medium · Plan");
-      expect(text).not.toContain("Medium · plan");
-    });
-  });
-
-  it("does not show a leading separator when only agent options are available", async () => {
-    await using _ = await mountOpenCodePicker({
-      model: "openai/gpt-5.4",
-      models: [
-        {
-          slug: "openai/gpt-5.4",
-          name: "OpenAI · GPT-5.4",
-          isCustom: false,
-          capabilities: {
-            reasoningEffortLevels: [],
-            supportsFastMode: false,
-            supportsThinkingToggle: false,
-            contextWindowOptions: [],
-            promptInjectedEffortLevels: [],
-            variantOptions: [],
-            agentOptions: [
-              { value: "build", label: "Build", isDefault: true },
-              { value: "plan", label: "Plan" },
-            ],
-          },
-        },
-      ],
-    });
-
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Agent");
-      expect(text).toContain("Build (default)");
-      expect(text).toContain("Plan");
-      expect(document.querySelectorAll('[data-slot="menu-separator"]')).toHaveLength(0);
-    });
-  });
-});
-
-describe("TraitsPicker (Cursor)", () => {
-  afterEach(() => {
-    document.body.innerHTML = "";
-    localStorage.removeItem(COMPOSER_DRAFT_STORAGE_KEY);
-    useComposerDraftStore.setState({
-      draftsByThreadKey: {},
-      draftThreadsByThreadKey: {},
-      logicalProjectDraftThreadKeyByLogicalProjectKey: {},
-      stickyModelSelectionByProvider: {},
-    });
-  });
-
-  it("uses the selected fast mode menu label for the trigger in fast-only state", async () => {
-    await using _ = await mountCursorPicker({
-      model: "composer-2",
-      options: { fastMode: false },
-    });
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Normal");
-    });
-
-    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 Normal for Cursor Opus 4.6 when fast mode and context window are both at defaults", async () => {
-    await using _ = await mountCursorPicker({
-      model: "claude-opus-4-6",
-      options: { fastMode: false },
-    });
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Normal");
-    });
-
-    await page.getByRole("button").click();
-
-    await vi.waitFor(() => {
-      const text = document.body.textContent ?? "";
-      expect(text).toContain("Fast Mode");
-      expect(text).toContain("Context Window");
-      expect(text).toContain("200K (default)");
-      expect(text).toContain("1M");
-    });
-  });
-
-  it("shows Normal · 1M for Cursor Opus 4.6 when fast mode is off and context window is overridden", async () => {
-    await using _ = await mountCursorPicker({
-      model: "claude-opus-4-6",
-      options: { fastMode: false, contextWindow: "1m" },
-    });
-
-    await vi.waitFor(() => {
-      expect(document.body.textContent ?? "").toContain("Normal · 1M");
-    });
-  });
-});
diff --git a/apps/web/src/components/chat/TraitsPicker.tsx b/apps/web/src/components/chat/TraitsPicker.tsx
index 491c289cc71..62caa323fd3 100644
--- a/apps/web/src/components/chat/TraitsPicker.tsx
+++ b/apps/web/src/components/chat/TraitsPicker.tsx
@@ -1,21 +1,17 @@
 import {
-  type ClaudeModelOptions,
-  type CodexModelOptions,
-  type CursorModelOptions,
-  type OpenCodeModelOptions,
-  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";
@@ -34,12 +30,7 @@ import { useComposerDraftStore, DraftId } from "../../composerDraftStore";
 import { getProviderModelCapabilities } from "../../providerModels";
 import { cn } from "~/lib/utils";
 
-type ProviderOptions = ProviderModelOptions[ProviderKind];
-type NamedOption = {
-  value: string;
-  label: string;
-  isDefault?: boolean | undefined;
-};
+type ProviderOptions = ReadonlyArray<ProviderOptionSelection>;
 
 type TraitsPersistence =
   | {
@@ -54,66 +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);
-  }
-  if (provider === "cursor") {
-    return trimOrNull((modelOptions as CursorModelOptions | undefined)?.reasoning);
-  }
-  if (provider === "opencode") {
-    return trimOrNull((modelOptions as OpenCodeModelOptions | undefined)?.variant);
-  }
-  return trimOrNull((modelOptions as ClaudeModelOptions | undefined)?.effort);
-}
-
-function getEffortKey(provider: ProviderKind): string {
-  if (provider === "codex") return "reasoningEffort";
-  if (provider === "cursor") return "reasoning";
-  if (provider === "opencode") return "variant";
-  return "effort";
-}
-
-function getRawAgent(modelOptions: ProviderOptions | null | undefined): string | null {
-  return trimOrNull((modelOptions as OpenCodeModelOptions | undefined)?.agent);
-}
-
-function resolveNamedOption(
-  options: ReadonlyArray<NamedOption>,
-  raw: string | null,
-): NamedOption | null {
-  if (raw) {
-    const matchingOption = options.find((option) => option.value === raw);
-    if (matchingOption) {
-      return matchingOption;
-    }
-  }
-  return options.find((option) => option.isDefault) ?? options[0] ?? null;
+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 (modelOptions && "contextWindow" in modelOptions) {
-    return trimOrNull(modelOptions.contextWindow);
+  if (!descriptor) {
+    return null;
   }
-  return null;
-}
-
-function buildNextOptions(
-  provider: ProviderKind,
-  modelOptions: ProviderOptions | null | undefined,
-  patch: Record<string, unknown>,
-): ProviderOptions {
-  return { ...(modelOptions as Record<string, unknown> | undefined), ...patch } as ProviderOptions;
+  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,
@@ -121,76 +84,73 @@ function getSelectedTraits(
   allowPromptInjectedEffort: boolean,
 ) {
   const caps = getProviderModelCapabilities(models, model, provider);
-  const effortLevels =
-    provider === "opencode"
-      ? (caps.variantOptions ?? [])
-      : 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 =
-    provider === "opencode"
-      ? (resolveNamedOption(effortLevels, rawEffort)?.value ?? null)
-      : (resolveEffort(caps, rawEffort) ?? null);
-
-  // Thinking toggle (only for models that support it)
-  const thinkingEnabled = caps.supportsThinkingToggle
-    ? modelOptions && "thinking" in modelOptions
-      ? modelOptions.thinking === true
-      : null
-    : 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 agentOptions = caps.agentOptions ?? [];
-  const selectedAgentOption =
-    provider === "opencode" ? resolveNamedOption(agentOptions, getRawAgent(modelOptions)) : null;
+  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,
-    agentOptions,
-    selectedAgent: selectedAgentOption?.value ?? null,
-    selectedAgentLabel: selectedAgentOption?.label ?? null,
+    selectedAgent,
+    selectedAgentLabel,
   };
 }
 
 function getTraitsSectionVisibility(input: {
-  provider: ProviderKind;
+  provider: ProviderDriverKind;
   models: ReadonlyArray<ServerProviderModel>;
   model: string | null | undefined;
   prompt: string;
@@ -206,11 +166,11 @@ function getTraitsSectionVisibility(input: {
     input.allowPromptInjectedEffort ?? true,
   );
 
-  const showEffort = selected.effort !== null;
-  const showThinking = selected.thinkingEnabled !== null;
-  const showFastMode = selected.caps.supportsFastMode;
-  const showContextWindow = selected.contextWindowOptions.length > 1;
-  const showAgent = selected.agentOptions.length > 0;
+  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,
@@ -224,7 +184,7 @@ function getTraitsSectionVisibility(input: {
 }
 
 export function shouldRenderTraitsControls(input: {
-  provider: ProviderKind;
+  provider: ProviderDriverKind;
   models: ReadonlyArray<ServerProviderModel>;
   model: string | null | undefined;
   prompt: string;
@@ -235,7 +195,7 @@ export function shouldRenderTraitsControls(input: {
 }
 
 export interface TraitsMenuContentProps {
-  provider: ProviderKind;
+  provider: ProviderDriverKind;
   models: ReadonlyArray<ServerProviderModel>;
   model: string | null | undefined;
   prompt: string;
@@ -275,22 +235,12 @@ export const TraitsMenuContent = memo(function TraitsMenuContentImpl({
     [model, persistence, provider, setProviderModelOptions],
   );
   const {
-    caps,
-    effort,
-    effortLevels,
-    thinkingEnabled,
-    fastModeEnabled,
-    contextWindowOptions,
-    contextWindow,
-    defaultContextWindow,
+    descriptors,
+    selectDescriptors,
+    booleanDescriptors,
+    primarySelectDescriptor,
     ultrathinkPromptControlled,
-    showEffort,
-    showThinking,
-    showFastMode,
-    showContextWindow,
     ultrathinkInBodyText,
-    agentOptions,
-    selectedAgent,
     hasAnyControls,
   } = getTraitsSectionVisibility({
     provider,
@@ -300,53 +250,30 @@ export const TraitsMenuContent = memo(function TraitsMenuContentImpl({
     modelOptions,
     allowPromptInjectedEffort,
   });
-  const defaultEffort = getDefaultEffort(caps);
-  const showsEffortSection = showEffort;
-  const showsThinkingSection = !showEffort && showThinking;
-  const showsFastModeSection = showFastMode;
-  const showsContextWindowSection = showContextWindow;
-  const hasSectionsBeforeAgent =
-    showsEffortSection || showsThinkingSection || showsFastModeSection || showsContextWindowSection;
+  const updateDescriptors = (nextDescriptors: ReadonlyArray<ProviderOptionDescriptor>) => {
+    updateModelOptions(buildProviderOptionSelectionsFromDescriptors(nextDescriptors));
+  };
 
-  const handleEffortChange = useCallback(
-    (value: string) => {
-      if (ultrathinkPromptControlled) return;
-      if (!value) return;
-      const nextOption = effortLevels.find((option) => option.value === value);
-      if (!nextOption) return;
-      if (provider === "opencode") {
-        updateModelOptions(buildNextOptions(provider, modelOptions, { variant: nextOption.value }));
-        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 = getEffortKey(provider);
-      updateModelOptions(
-        buildNextOptions(provider, modelOptions, { [effortKey]: nextOption.value }),
-      );
-    },
-    [
-      ultrathinkPromptControlled,
-      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 (!hasAnyControls) {
     return null;
@@ -354,118 +281,62 @@ export const TraitsMenuContent = memo(function TraitsMenuContentImpl({
 
   return (
     <>
-      {showsEffortSection ? (
-        <>
+      {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">
-              {provider === "opencode" ? "Variant" : "Effort"}
+              {descriptor.label}
             </div>
-            {ultrathinkPromptControlled ? (
+            {ultrathinkInBodyText && descriptor.id === primarySelectDescriptor?.id ? (
               <div className="px-2 pb-1.5 text-muted-foreground/80 text-xs">
-                Remove Ultrathink from the prompt to change effort.
+                Your prompt contains &quot;ultrathink&quot; in the text. Remove it to change this
+                option.
               </div>
             ) : null}
-            <MenuRadioGroup value={effort} onValueChange={handleEffortChange}>
-              {effortLevels.map((option) => (
+            <MenuRadioGroup
+              value={
+                ultrathinkPromptControlled && descriptor.id === primarySelectDescriptor?.id
+                  ? "ultrathink"
+                  : (getDescriptorStringValue(descriptor) ?? "")
+              }
+              onValueChange={(value) => handleSelectChange(descriptor, value)}
+            >
+              {descriptor.options.map((option) => (
                 <MenuRadioItem
-                  key={option.value}
-                  value={option.value}
-                  disabled={ultrathinkPromptControlled}
+                  key={option.id}
+                  value={option.id}
+                  disabled={ultrathinkInBodyText && descriptor.id === primarySelectDescriptor?.id}
                 >
                   {option.label}
-                  {(provider === "opencode" ? option.isDefault : option.value === defaultEffort)
-                    ? " (default)"
-                    : ""}
+                  {option.isDefault ? " (default)" : ""}
                 </MenuRadioItem>
               ))}
             </MenuRadioGroup>
           </MenuGroup>
-        </>
-      ) : showsThinkingSection ? (
-        <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}
-      {showsFastModeSection ? (
-        <>
-          {showsEffortSection || showsThinkingSection ? <MenuDivider /> : null}
-          <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}
-      {showsContextWindowSection ? (
-        <>
-          {showsEffortSection || showsThinkingSection || showsFastModeSection ? (
-            <MenuDivider />
-          ) : null}
+        </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>
-              ))}
-            </MenuRadioGroup>
-          </MenuGroup>
-        </>
-      ) : null}
-      {agentOptions.length > 0 ? (
-        <>
-          {hasSectionsBeforeAgent ? <MenuDivider /> : null}
-          <MenuGroup>
-            <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Agent</div>
-            <MenuRadioGroup
-              value={selectedAgent ?? ""}
-              onValueChange={(value) => {
-                updateModelOptions(buildNextOptions(provider, modelOptions, { agent: value }));
-              }}
-            >
-              {agentOptions.map((option) => (
-                <MenuRadioItem key={option.value} value={option.value}>
-                  {option.label}
-                  {option.isDefault ? " (default)" : ""}
-                </MenuRadioItem>
-              ))}
+              <MenuRadioItem value="on">On</MenuRadioItem>
+              <MenuRadioItem value="off">Off</MenuRadioItem>
             </MenuRadioGroup>
           </MenuGroup>
-        </>
-      ) : null}
+        </div>
+      ))}
     </>
   );
 });
@@ -483,52 +354,15 @@ export const TraitsPicker = memo(function TraitsPicker({
   ...persistence
 }: TraitsMenuContentProps & TraitsPersistence) {
   const [isMenuOpen, setIsMenuOpen] = useState(false);
-  const {
-    caps,
-    effort,
-    effortLevels,
-    thinkingEnabled,
-    fastModeEnabled,
-    contextWindowOptions,
-    contextWindow,
-    defaultContextWindow,
-    ultrathinkPromptControlled,
-    showEffort,
-    showThinking,
-    showContextWindow,
-  } = getTraitsSectionVisibility({
-    provider,
-    models,
-    model,
-    prompt,
-    modelOptions,
-    allowPromptInjectedEffort,
-  });
-  const { selectedAgentLabel } = getSelectedTraits(
-    provider,
-    models,
-    model,
-    prompt,
-    modelOptions,
-    allowPromptInjectedEffort,
-  );
-
-  const effortLabel = effort
-    ? (effortLevels.find((l) => l.value === effort)?.label ?? effort)
-    : null;
-  const primaryTraitLabel = ultrathinkPromptControlled
-    ? "Ultrathink"
-    : effortLabel
-      ? effortLabel
-      : thinkingEnabled === null
-        ? null
-        : `Thinking ${thinkingEnabled ? "On" : "Off"}`;
-  const contextWindowLabel =
-    showContextWindow && contextWindow !== defaultContextWindow
-      ? (contextWindowOptions.find((o) => o.value === contextWindow)?.label ?? null)
-      : null;
-  const fastOnlyControl =
-    caps.supportsFastMode && !showEffort && !showThinking && !showContextWindow;
+  const { descriptors, primarySelectDescriptor, ultrathinkPromptControlled } =
+    getTraitsSectionVisibility({
+      provider,
+      models,
+      model,
+      prompt,
+      modelOptions,
+      allowPromptInjectedEffort,
+    });
   if (
     !shouldRenderTraitsControls({
       provider,
@@ -542,27 +376,22 @@ export const TraitsPicker = memo(function TraitsPicker({
     return null;
   }
 
-  const selectedTriggerTraits = [
-    primaryTraitLabel,
-    ...(caps.supportsFastMode &&
-    (fastModeEnabled || (primaryTraitLabel === null && contextWindowLabel !== null))
-      ? [fastModeEnabled ? "Fast" : "Normal"]
-      : []),
-    ...(contextWindowLabel ? [contextWindowLabel] : []),
-    ...(selectedAgentLabel ? [selectedAgentLabel] : []),
-  ].filter(Boolean);
-  const triggerLabel = fastOnlyControl
-    ? fastModeEnabled
-      ? "Fast"
-      : "Normal"
-    : selectedTriggerTraits.length > 0
-      ? selectedTriggerTraits.join(" · ")
-      : caps.supportsFastMode
-        ? "Normal"
-        : defaultContextWindow
-          ? (contextWindowOptions.find((option) => option.value === defaultContextWindow)?.label ??
-            defaultContextWindow)
-          : (selectedAgentLabel ?? "");
+  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 c4dd2cbb6ee..00000000000
--- a/apps/web/src/components/chat/composerProviderRegistry.test.tsx
+++ /dev/null
@@ -1,516 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { ServerProviderModel } from "@t3tools/contracts";
-import {
-  getComposerProviderControls,
-  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: [],
-    },
-  },
-];
-
-const OPENCODE_MODELS: ReadonlyArray<ServerProviderModel> = [
-  {
-    slug: "openai/gpt-5",
-    name: "GPT-5",
-    isCustom: false,
-    capabilities: {
-      reasoningEffortLevels: [],
-      supportsFastMode: false,
-      supportsThinkingToggle: false,
-      contextWindowOptions: [],
-      promptInjectedEffortLevels: [],
-      variantOptions: [
-        { value: "low", label: "Low" },
-        { value: "medium", label: "Medium", isDefault: true },
-      ],
-      agentOptions: [
-        { value: "build", label: "Build", isDefault: true },
-        { value: "plan", label: "Plan" },
-      ],
-    },
-  },
-];
-
-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");
-  });
-
-  it("preserves OpenCode variant and agent options for dispatch", () => {
-    const state = getComposerProviderState({
-      provider: "opencode",
-      model: "openai/gpt-5",
-      models: OPENCODE_MODELS,
-      prompt: "",
-      modelOptions: {
-        opencode: {
-          variant: "medium",
-          agent: "plan",
-        },
-      },
-    });
-
-    expect(state).toEqual({
-      provider: "opencode",
-      promptEffort: "medium",
-      modelOptionsForDispatch: {
-        variant: "medium",
-        agent: "plan",
-      },
-    });
-  });
-});
-
-describe("getComposerProviderControls", () => {
-  it("hides the interaction mode toggle for OpenCode", () => {
-    expect(getComposerProviderControls("opencode")).toEqual({
-      showInteractionModeToggle: false,
-    });
-  });
-
-  it("keeps the interaction mode toggle for Codex and Claude", () => {
-    expect(getComposerProviderControls("codex")).toEqual({
-      showInteractionModeToggle: true,
-    });
-    expect(getComposerProviderControls("claudeAgent")).toEqual({
-      showInteractionModeToggle: true,
-    });
-  });
-});
-
-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 844dfaa3d85..00000000000
--- a/apps/web/src/components/chat/composerProviderRegistry.tsx
+++ /dev/null
@@ -1,220 +0,0 @@
-import {
-  type ProviderKind,
-  type ProviderModelOptions,
-  type ScopedThreadRef,
-  type ServerProviderModel,
-} from "@t3tools/contracts";
-import {
-  isClaudeUltrathinkPrompt,
-  normalizeProviderModelOptionsWithCapabilities,
-  resolveEffort,
-  trimOrNull,
-} 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: 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 TraitsRenderInput = {
-  threadRef?: ScopedThreadRef;
-  draftId?: DraftId;
-  model: string;
-  models: ReadonlyArray<ServerProviderModel>;
-  modelOptions: ProviderModelOptions[ProviderKind] | undefined;
-  prompt: string;
-  onPromptChange: (prompt: string) => void;
-};
-
-export type ComposerProviderControls = {
-  showInteractionModeToggle: boolean;
-};
-
-type ProviderRegistryEntry = {
-  controls: ComposerProviderControls;
-  getState: (input: ComposerProviderStateInput) => ComposerProviderState;
-  renderTraitsMenuContent: (input: TraitsRenderInput) => ReactNode;
-  renderTraitsPicker: (input: TraitsRenderInput) => ReactNode;
-};
-
-function hasComposerTraitsTarget(input: {
-  threadRef: ScopedThreadRef | undefined;
-  draftId: DraftId | undefined;
-}): boolean {
-  return input.threadRef !== undefined || input.draftId !== undefined;
-}
-
-function renderTraitsControl(
-  Component: typeof TraitsMenuContent | typeof TraitsPicker,
-  provider: ProviderKind,
-  input: TraitsRenderInput,
-): ReactNode {
-  const { threadRef, draftId, model, models, modelOptions, prompt, onPromptChange } = input;
-  if (
-    !hasComposerTraitsTarget({ threadRef, draftId }) ||
-    !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}
-    />
-  );
-}
-
-function getProviderStateFromCapabilities(
-  input: ComposerProviderStateInput,
-): ComposerProviderState {
-  const { provider, model, models, prompt, modelOptions } = input;
-  const caps = getProviderModelCapabilities(models, model, provider);
-  const providerOptions = modelOptions?.[provider];
-  const rawEffort = providerOptions
-    ? "effort" in providerOptions
-      ? providerOptions.effort
-      : "reasoningEffort" in providerOptions
-        ? providerOptions.reasoningEffort
-        : "reasoning" in providerOptions
-          ? providerOptions.reasoning
-          : "variant" in providerOptions
-            ? providerOptions.variant
-            : null
-    : null;
-  const normalizedOptions = normalizeProviderModelOptionsWithCapabilities(
-    provider,
-    caps,
-    providerOptions,
-  );
-  const promptEffort =
-    provider === "opencode"
-      ? (trimOrNull(
-          normalizedOptions && "variant" in normalizedOptions ? normalizedOptions.variant : null,
-        ) ?? null)
-      : (resolveEffort(caps, rawEffort) ?? null);
-  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 DEFAULT_PROVIDER_CONTROLS: ComposerProviderControls = {
-  showInteractionModeToggle: true,
-};
-
-function createProviderRegistryEntry(
-  provider: ProviderKind,
-  controls?: Partial<ComposerProviderControls>,
-): ProviderRegistryEntry {
-  return {
-    controls: {
-      ...DEFAULT_PROVIDER_CONTROLS,
-      ...controls,
-    },
-    getState: (input) => getProviderStateFromCapabilities(input),
-    renderTraitsMenuContent: (input) => renderTraitsControl(TraitsMenuContent, provider, input),
-    renderTraitsPicker: (input) => renderTraitsControl(TraitsPicker, provider, input),
-  };
-}
-
-const composerProviderRegistry: Record<ProviderKind, ProviderRegistryEntry> = {
-  codex: createProviderRegistryEntry("codex"),
-  claudeAgent: createProviderRegistryEntry("claudeAgent"),
-  copilot: createProviderRegistryEntry("copilot"),
-  cursor: createProviderRegistryEntry("cursor"),
-  opencode: createProviderRegistryEntry("opencode", {
-    showInteractionModeToggle: false,
-  }),
-  geminiCli: createProviderRegistryEntry("geminiCli"),
-  amp: createProviderRegistryEntry("amp"),
-  kilo: createProviderRegistryEntry("kilo"),
-};
-
-export function getComposerProviderState(input: ComposerProviderStateInput): ComposerProviderState {
-  return composerProviderRegistry[input.provider].getState(input);
-}
-
-export function getComposerProviderControls(provider: ProviderKind): ComposerProviderControls {
-  return composerProviderRegistry[provider].controls;
-}
-
-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.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
index c3661fda2b4..2131480a6a2 100644
--- a/apps/web/src/components/chat/modelPickerModelHighlights.ts
+++ b/apps/web/src/components/chat/modelPickerModelHighlights.ts
@@ -1,4 +1,4 @@
-import type { ProviderKind } from "@t3tools/contracts";
+import type { ProviderDriverKind } from "@t3tools/contracts";
 
 /**
  * Model slugs that show a gold "NEW" chip in the model picker list.
@@ -8,6 +8,6 @@ const NEW_MODEL_KEYS = new Set<string>([
   // Example: "claudeAgent:claude-opus-4-7",
 ]);
 
-export function isModelPickerNewModel(provider: ProviderKind, slug: string): boolean {
+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
index 1ce629d8a4a..10282dbe3e7 100644
--- a/apps/web/src/components/chat/modelPickerSearch.test.ts
+++ b/apps/web/src/components/chat/modelPickerSearch.test.ts
@@ -6,7 +6,8 @@ describe("buildModelPickerSearchText", () => {
   it("builds provider-agnostic search text from generic fields", () => {
     expect(
       buildModelPickerSearchText({
-        provider: "opencode",
+        driverKind: "opencode",
+        providerDisplayName: "opencode",
         name: "Claude Opus 4.7",
         subProvider: "GitHub Copilot",
       }),
@@ -19,7 +20,8 @@ describe("scoreModelPickerSearch", () => {
     expect(
       scoreModelPickerSearch(
         {
-          provider: "opencode",
+          driverKind: "opencode",
+          providerDisplayName: "opencode",
           name: "Claude Opus 4.7",
           subProvider: "GitHub Copilot",
         },
@@ -32,7 +34,8 @@ describe("scoreModelPickerSearch", () => {
     expect(
       scoreModelPickerSearch(
         {
-          provider: "codex",
+          driverKind: "codex",
+          providerDisplayName: "codex",
           name: "GPT-5 Codex",
         },
         "coplt op",
@@ -43,7 +46,8 @@ describe("scoreModelPickerSearch", () => {
   it("ranks exact token matches ahead of fuzzier matches", () => {
     const exactScore = scoreModelPickerSearch(
       {
-        provider: "opencode",
+        driverKind: "opencode",
+        providerDisplayName: "opencode",
         name: "Claude Opus 4.7",
         subProvider: "GitHub Copilot",
       },
@@ -51,7 +55,8 @@ describe("scoreModelPickerSearch", () => {
     );
     const fuzzyScore = scoreModelPickerSearch(
       {
-        provider: "opencode",
+        driverKind: "opencode",
+        providerDisplayName: "opencode",
         name: "Claude Opus 4.7",
         subProvider: "GitHub Copilot",
       },
@@ -66,7 +71,8 @@ describe("scoreModelPickerSearch", () => {
   it("gives favorite models a strong enough ranking boost for partial queries", () => {
     const favoriteScore = scoreModelPickerSearch(
       {
-        provider: "claudeAgent",
+        driverKind: "claudeAgent",
+        providerDisplayName: "Claude",
         name: "Claude Opus 4.7",
         isFavorite: true,
       },
@@ -74,7 +80,8 @@ describe("scoreModelPickerSearch", () => {
     );
     const nonFavoriteScore = scoreModelPickerSearch(
       {
-        provider: "cursor",
+        driverKind: "cursor",
+        providerDisplayName: "Cursor",
         name: "Opus 4.5",
       },
       "opu",
@@ -88,7 +95,8 @@ describe("scoreModelPickerSearch", () => {
   it("does not let the favorite boost outrank clearly better textual matches", () => {
     const favoriteScore = scoreModelPickerSearch(
       {
-        provider: "claudeAgent",
+        driverKind: "claudeAgent",
+        providerDisplayName: "Claude",
         name: "Claude Opus 4.7",
         isFavorite: true,
       },
@@ -96,7 +104,8 @@ describe("scoreModelPickerSearch", () => {
     );
     const nonFavoriteExactScore = scoreModelPickerSearch(
       {
-        provider: "cursor",
+        driverKind: "cursor",
+        providerDisplayName: "Cursor",
         name: "Opus 4.7",
       },
       "opus 4.7",
@@ -106,4 +115,17 @@ describe("scoreModelPickerSearch", () => {
     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
index a4871fa0f31..d3a954ee4fa 100644
--- a/apps/web/src/components/chat/modelPickerSearch.ts
+++ b/apps/web/src/components/chat/modelPickerSearch.ts
@@ -1,8 +1,14 @@
-import { type ProviderKind, PROVIDER_DISPLAY_NAMES } from "@t3tools/contracts";
 import { normalizeSearchQuery, scoreQueryMatch } from "@t3tools/shared/searchRanking";
 
 type ModelPickerSearchableModel = {
-  provider: ProviderKind;
+  /** 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;
@@ -16,8 +22,8 @@ function getModelPickerSearchFields(model: ModelPickerSearchableModel): string[]
     normalizeSearchQuery(model.name),
     ...(model.shortName ? [normalizeSearchQuery(model.shortName)] : []),
     ...(model.subProvider ? [normalizeSearchQuery(model.subProvider)] : []),
-    normalizeSearchQuery(model.provider),
-    normalizeSearchQuery(PROVIDER_DISPLAY_NAMES[model.provider]),
+    normalizeSearchQuery(model.driverKind),
+    normalizeSearchQuery(model.providerDisplayName),
     buildModelPickerSearchText(model),
   ];
 }
@@ -40,13 +46,7 @@ function scoreModelPickerSearchToken(
 
 export function buildModelPickerSearchText(model: ModelPickerSearchableModel): string {
   return normalizeSearchQuery(
-    [
-      model.name,
-      model.shortName,
-      model.subProvider,
-      model.provider,
-      PROVIDER_DISPLAY_NAMES[model.provider],
-    ]
+    [model.name, model.shortName, model.subProvider, model.driverKind, model.providerDisplayName]
       .filter((value): value is string => typeof value === "string" && value.length > 0)
       .join(" "),
   );
diff --git a/apps/web/src/components/chat/providerIconUtils.ts b/apps/web/src/components/chat/providerIconUtils.ts
index 8ae2fd6f4dd..88b56295f36 100644
--- a/apps/web/src/components/chat/providerIconUtils.ts
+++ b/apps/web/src/components/chat/providerIconUtils.ts
@@ -1,30 +1,16 @@
-import { type ProviderKind, PROVIDER_DISPLAY_NAMES } from "@t3tools/contracts";
-import {
-  AmpIcon,
-  ClaudeAI,
-  CursorIcon,
-  Gemini,
-  GithubCopilotIcon,
-  Icon,
-  KiloIcon,
-  OpenAI,
-  OpenCodeIcon,
-} from "../Icons";
+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: Record<ProviderKind, Icon> = {
-  codex: OpenAI,
-  copilot: GithubCopilotIcon,
-  claudeAgent: ClaudeAI,
-  cursor: CursorIcon,
-  opencode: OpenCodeIcon,
-  geminiCli: Gemini,
-  amp: AmpIcon,
-  kilo: KiloIcon,
+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: ProviderKind;
+  value: ProviderDriverKind;
   label: string;
   available: true;
   pickerSidebarBadge?: "new" | "soon";
@@ -41,11 +27,6 @@ export type ModelEsque = {
   subProvider?: string | undefined;
 };
 
-export function getProviderLabel(provider: ProviderKind, model: ModelEsque): string {
-  const providerLabel = PROVIDER_DISPLAY_NAMES[provider];
-  return model.subProvider ? `${providerLabel} · ${model.subProvider}` : providerLabel;
-}
-
 export function getDisplayModelName(
   model: ModelEsque,
   options?: { preferShortName?: boolean },
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/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 880c4376e2c..98c02d92f64 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1,8 +1,19 @@
-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";
@@ -11,6 +22,7 @@ import { DateTime } from "effect";
 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,
@@ -44,8 +58,20 @@ import { Switch } from "../ui/switch";
 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,55 +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(
         stackedThreadToast({
           type: "error",
-          title: canCopyToClipboard ? "Could not copy pairing URL" : "Clipboard copy unavailable",
+          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">
@@ -377,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()}
@@ -420,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>
@@ -443,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) {
@@ -477,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">
@@ -620,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>;
@@ -631,6 +1066,9 @@ type PairingClientsListProps = {
 
 const PairingClientsList = memo(function PairingClientsList({
   endpointUrl,
+  endpoints,
+  defaultEndpointKey,
+  presentation = "current",
   isLoading,
   pairingLinks,
   clientSessions,
@@ -646,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}
         />
@@ -655,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}
@@ -669,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);
@@ -693,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"
@@ -703,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)}`
@@ -723,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"
@@ -755,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>(
@@ -771,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>
@@ -793,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) => {
@@ -825,12 +1547,12 @@ 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(
           stackedThreadToast({
@@ -851,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);
@@ -920,22 +1710,53 @@ export function ConnectionsSettings() {
   }, []);
 
   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",
@@ -957,24 +1778,25 @@ export function ConnectionsSettings() {
     }
   }, [
     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(
         stackedThreadToast({
           type: "error",
-          title: "Could not reconnect backend",
+          title: "Could not connect backend",
           description: message,
         }),
       );
@@ -983,6 +1805,26 @@ export function ConnectionsSettings() {
     }
   }, []);
 
+  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);
@@ -1003,6 +1845,84 @@ export function ConnectionsSettings() {
     }
   }, []);
 
+  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");
@@ -1105,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);
     }
 
@@ -1123,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={
@@ -1258,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">
@@ -1305,120 +2670,32 @@ export function ConnectionsSettings() {
                 </Button>
               }
             />
-            <DialogPopup>
+            <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>
@@ -1430,8 +2707,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/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..236e1db5655
--- /dev/null
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -0,0 +1,725 @@
+"use client";
+
+import { ChevronDownIcon, 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 { 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 { Switch } from "../ui/switch";
+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 {
+  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;
+}
+
+/**
+ * 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,
+}: 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 FallbackIconComponent = driverOption?.icon;
+  const displayName =
+    instance.displayName?.trim() || driverOption?.label || String(instance.driver);
+  const accentColor = normalizeProviderAccentColor(instance.accentColor);
+
+  // 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),
+    );
+  };
+
+  return (
+    <div 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">
+              {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)} />
+              )}
+              <h3 className="truncate text-sm font-medium text-foreground">{displayName}</h3>
+              {String(instanceId) !== String(instance.driver) ? (
+                // Hide the id chip on a default slot whose id === the
+                // driver slug — it's redundant with the driver icon +
+                // label. Custom instances (and any instance the user has
+                // since renamed) keep the chip so their slug stays
+                // visible for copy/paste + disambiguation.
+                <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}
+              {versionLabel ? (
+                <code className="text-xs text-muted-foreground">{versionLabel}</code>
+              ) : null}
+              {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}
+            </div>
+            <p className="flex min-w-0 flex-wrap items-center gap-x-1 text-xs text-muted-foreground">
+              {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>
+          </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..244fa9f31ca
--- /dev/null
+++ b/apps/web/src/components/settings/ProviderSettingsForm.tsx
@@ -0,0 +1,306 @@
+"use client";
+
+import { useMemo, type ReactNode } from "react";
+import { Schema } from "effect";
+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 {
+  try {
+    const decoded = Schema.decodeUnknownSync(fieldSchema as Schema.Decoder<unknown>)(undefined);
+    return typeof decoded === "boolean" ? decoded : undefined;
+  } catch {
+    return 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 7b29fc7d73b..6cca3de8d1b 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -11,17 +11,20 @@ import {
   type DesktopUpdateState,
   type LocalApi,
   type ServerConfig,
+  type SourceControlDiscoveryResult,
 } from "@t3tools/contracts";
-import { DateTime } from "effect";
+import { DateTime, Option } from "effect";
 import { page } from "vitest/browser";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { render } from "vitest-browser-react";
 
 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 { SourceControlSettingsPanel } from "./SourceControlSettings";
 
 const authAccessHarness = vi.hoisted(() => {
   type Snapshot = AuthAccessSnapshot;
@@ -113,6 +116,8 @@ const authAccessHarness = vi.hoisted(() => {
   };
 });
 
+const mockConnectDesktopSshEnvironment = vi.hoisted(() => vi.fn());
+
 vi.mock("../../environments/runtime", () => {
   const primaryConnection = {
     kind: "primary" as const,
@@ -150,6 +155,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,
@@ -257,7 +263,9 @@ 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 => {
@@ -293,11 +301,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:
@@ -306,7 +361,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),
@@ -347,7 +412,9 @@ describe("GeneralSettingsPanel observability", () => {
     resetServerStateForTests();
     await __resetLocalApiForTests();
     localStorage.clear();
+    useUiStateStore.setState({ defaultAdvertisedEndpointKey: null });
     authAccessHarness.reset();
+    mockConnectDesktopSshEnvironment.mockReset();
   });
 
   afterEach(async () => {
@@ -433,6 +500,176 @@ describe("GeneralSettingsPanel observability", () => {
       .toBeInTheDocument();
   });
 
+  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 single logs-folder action", async () => {
     setServerConfigSnapshot(createBaseServerConfig());
 
@@ -463,6 +700,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]> = [];
@@ -568,7 +807,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();
   });
@@ -579,6 +818,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]> = [
@@ -679,9 +920,77 @@ 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 () => {
@@ -717,9 +1026,162 @@ describe("GeneralSettingsPanel observability", () => {
 
     await page.getByLabelText("Toggle OpenCode details").click();
 
-    await expect.element(page.getByText("OpenCode server URL")).toBeInTheDocument();
+    // 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("OpenCode server password")).toBeInTheDocument();
-    await expect.element(page.getByPlaceholder("Server password")).toBeInTheDocument();
+    await expect.element(page.getByText("Server password")).toBeInTheDocument();
+    await expect.element(page.getByPlaceholder("Optional")).toBeInTheDocument();
+  });
+});
+
+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("heading", { name: "Git" })).toBeInTheDocument();
+    await expect.element(page.getByText("Nothing detected yet")).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("heading", { name: "Git" })).toBeInTheDocument();
+    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("heading", { name: "Git" })).toBeInTheDocument();
+    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..77206d2484f
--- /dev/null
+++ b/apps/web/src/components/settings/SettingsPanels.logic.test.ts
@@ -0,0 +1,63 @@
+import {
+  DEFAULT_SERVER_SETTINGS,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ProviderInstanceConfig,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vitest";
+import { buildProviderInstanceUpdatePatch } from "./SettingsPanels.logic";
+
+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..57a63b7f2ae
--- /dev/null
+++ b/apps/web/src/components/settings/SettingsPanels.logic.ts
@@ -0,0 +1,43 @@
+import type {
+  ProviderDriverKind,
+  ProviderInstanceConfig,
+  ProviderInstanceId,
+  ServerSettings,
+  UnifiedSettings,
+} from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
+
+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 10dca18abd5..8fc36d4a32b 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -1,26 +1,17 @@
-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 { useCallback, useMemo, useRef, useState } from "react";
 import {
+  defaultInstanceIdForDriver,
   type DesktopUpdateChannel,
-  type ModelSelection,
+  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 { createModelSelection, normalizeModelSlug } from "@t3tools/shared/model";
+import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
 import {
@@ -31,11 +22,6 @@ import {
   resolveDesktopUpdateButtonAction,
 } from "../../components/desktopUpdate.logic";
 import { ProviderModelPicker } from "../chat/ProviderModelPicker";
-import {
-  buildModelOptionsByProvider,
-  mergeDiscoveredModels,
-  type ModelOptionEntry,
-} from "../../providerModelOptions";
 import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
@@ -47,10 +33,13 @@ 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 {
@@ -59,16 +48,17 @@ import {
   useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
-import { cn } from "../../lib/utils";
-import { Badge } from "../ui/badge";
 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 { stackedThreadToast, toastManager } from "../ui/toast";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { AddProviderInstanceDialog } from "./AddProviderInstanceDialog";
+import { ProviderInstanceCard } from "./ProviderInstanceCard";
+import { DRIVER_OPTIONS, getDriverOption } from "./providerDriverMeta";
+import { buildProviderInstanceUpdatePatch } from "./SettingsPanels.logic";
 import {
   SettingResetButton,
   SettingsPageContainer,
@@ -83,7 +73,6 @@ import {
   useServerObservability,
   useServerProviders,
 } from "../../rpc/serverState";
-import { formatProviderKindLabel } from "../../providerModels";
 
 const THEME_OPTIONS = [
   {
@@ -106,173 +95,28 @@ const TIMESTAMP_FORMAT_LABELS = {
   "24-hour": "24-hour",
 } as const;
 
-type InstallProviderSettings = {
-  provider: ProviderKind;
-  title: string;
-  badgeLabel?: string;
-  binaryPlaceholder: string;
-  binaryDescription: ReactNode;
-  homePathKey?: "codexHomePath";
-  homePlaceholder?: string;
-  homeDescription?: ReactNode;
-  customModelExample: string;
-  apiEndpointPlaceholder?: string;
-  apiEndpointDescription?: ReactNode;
-  serverUrlPlaceholder?: string;
-  serverUrlDescription?: ReactNode;
-  serverPasswordPlaceholder?: string;
-  serverPasswordDescription?: 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.",
-    customModelExample: "gpt-6.7-codex-ultra-preview",
-  },
-  {
-    provider: "copilot",
-    title: "GitHub Copilot",
-    binaryPlaceholder: "Copilot binary path",
-    binaryDescription: "Path to the Copilot CLI binary",
-    customModelExample: "gpt-4o-copilot",
-  },
-  {
-    provider: "claudeAgent",
-    title: "Claude Code",
-    binaryPlaceholder: "Claude binary path",
-    binaryDescription: "Path to the Claude binary",
-    customModelExample: "claude-sonnet-5-0",
-  },
-  {
-    provider: "cursor",
-    title: "Cursor Agent",
-    badgeLabel: "Early Access",
-    binaryPlaceholder: "Cursor binary path",
-    binaryDescription: "Path to the Cursor Agent binary",
-    customModelExample: "cursor-fast",
-    apiEndpointPlaceholder: "https://cursor.example.com/api",
-    apiEndpointDescription: "Optional custom Cursor API endpoint",
-  },
-  {
-    provider: "opencode",
-    title: "OpenCode",
-    binaryPlaceholder: "OpenCode binary path",
-    binaryDescription: "Path to the OpenCode binary",
-    customModelExample: "opencode-pro",
-    serverUrlPlaceholder: "http://127.0.0.1:4096",
-    serverUrlDescription: "Leave blank to let T3 Code spawn the server when needed",
-    serverPasswordPlaceholder: "Server password",
-    serverPasswordDescription:
-      "If your OpenCode server requires authentication, enter the password here. NOTE: Stored in plain text on disk",
-  },
-  {
-    provider: "geminiCli",
-    title: "Gemini CLI",
-    binaryPlaceholder: "Gemini CLI binary path",
-    binaryDescription: "Path to the Gemini CLI binary",
-    customModelExample: "gemini-2.0-ultra",
-  },
-  {
-    provider: "amp",
-    title: "AMPcode",
-    binaryPlaceholder: "AMPcode binary path",
-    binaryDescription: "Path to the AMPcode binary",
-    customModelExample: "amp-pro",
-  },
-  {
-    provider: "kilo",
-    title: "Kilo",
-    binaryPlaceholder: "Kilo binary path",
-    binaryDescription: "Path to the Kilo binary",
-    customModelExample: "kilo-advanced",
-  },
-] as const;
+const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
-const PROVIDER_STATUS_STYLES = {
-  disabled: {
-    dot: "bg-amber-400",
-  },
-  error: {
-    dot: "bg-destructive",
-  },
-  ready: {
-    dot: "bg-success",
-  },
-  warning: {
-    dot: "bg-warning",
-  },
-} as const;
-
-function getProviderSummary(provider: ServerProvider | undefined, enabled: boolean) {
-  if (!provider) {
-    if (!enabled) {
-      return {
-        headline: "Disabled",
-        detail: "This provider is disabled for new sessions in T3 Code.",
-      };
-    }
-    return {
-      headline: "Status unavailable",
-      detail:
-        "Live installation and authentication status has not been published for this provider yet.",
-    };
-  }
-  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;
@@ -507,11 +351,31 @@ export function useSettingsRestore(onRestored?: () => void) {
     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);
-  });
+  // A provider surface is "dirty" if either the legacy per-kind
+  // `settings.providers[kind]` struct differs from defaults (for users
+  // on pre-migration data) or the new `settings.providerInstances` map
+  // has any entries (every edit to a default slot promotes it into an
+  // explicit entry, so any key in that map represents user intent to
+  // diverge from factory defaults). Checking both keeps the Restore
+  // Defaults chip accurate throughout the legacy→instance migration.
+  const areProviderSettingsDirty =
+    PROVIDER_SETTINGS.some((providerSettings) => {
+      type LegacyProviderSettings = (typeof settings.providers)[keyof typeof settings.providers];
+      const currentProviders = settings.providers as Record<
+        string,
+        LegacyProviderSettings | undefined
+      >;
+      const defaultProviders = DEFAULT_UNIFIED_SETTINGS.providers as Record<
+        string,
+        LegacyProviderSettings | undefined
+      >;
+      const currentSettings = currentProviders[providerSettings.provider];
+      const defaultSettings = defaultProviders[providerSettings.provider];
+      return !Equal.equals(currentSettings, defaultSettings);
+    }) ||
+    Object.keys(settings.providerInstances ?? {}).length > 0 ||
+    Object.keys(settings.providerModelPreferences ?? {}).length > 0 ||
+    (settings.favorites ?? []).length > 0;
 
   const changedSettingLabels = useMemo(
     () => [
@@ -522,8 +386,11 @@ export function useSettingsRestore(onRestored?: () => void) {
       ...(settings.diffWordWrap !== DEFAULT_UNIFIED_SETTINGS.diffWordWrap
         ? ["Diff line wrapping"]
         : []),
+      ...(settings.diffIgnoreWhitespace !== DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace
+        ? ["Diff whitespace changes"]
+        : []),
       ...(settings.autoOpenPlanSidebar !== DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar
-        ? ["Task sidebar"]
+        ? ["Auto-open task panel"]
         : []),
       ...(settings.enableAssistantStreaming !== DEFAULT_UNIFIED_SETTINGS.enableAssistantStreaming
         ? ["Assistant output"]
@@ -551,6 +418,7 @@ export function useSettingsRestore(onRestored?: () => void) {
       settings.confirmThreadDelete,
       settings.addProjectBaseDirectory,
       settings.defaultThreadEnvMode,
+      settings.diffIgnoreWhitespace,
       settings.diffWordWrap,
       settings.enableAssistantStreaming,
       settings.timestampFormat,
@@ -590,57 +458,17 @@ export function GeneralSettingsPanel() {
   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 ||
-      settings.providers.claudeAgent.launchArgs !== "",
-    ),
-    copilot: false,
-    cursor: Boolean(
-      settings.providers.cursor.binaryPath !==
-        DEFAULT_UNIFIED_SETTINGS.providers.cursor.binaryPath ||
-      settings.providers.cursor.apiEndpoint !==
-        DEFAULT_UNIFIED_SETTINGS.providers.cursor.apiEndpoint ||
-      settings.providers.cursor.customModels.length > 0,
-    ),
-    opencode: Boolean(
-      settings.providers.opencode.binaryPath !==
-        DEFAULT_UNIFIED_SETTINGS.providers.opencode.binaryPath ||
-      settings.providers.opencode.serverUrl !==
-        DEFAULT_UNIFIED_SETTINGS.providers.opencode.serverUrl ||
-      settings.providers.opencode.serverPassword !==
-        DEFAULT_UNIFIED_SETTINGS.providers.opencode.serverPassword ||
-      settings.providers.opencode.customModels.length > 0,
-    ),
-    geminiCli: false,
-    amp: false,
-    kilo: false,
-  });
-  const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
-    Record<ProviderKind, string>
-  >({
-    codex: "",
-    claudeAgent: "",
-    copilot: "",
-    cursor: "",
-    opencode: "",
-    geminiCli: "",
-    amp: "",
-    kilo: "",
-  });
-  const [customModelErrorByProvider, setCustomModelErrorByProvider] = useState<
-    Partial<Record<ProviderKind, string | null>>
-  >({});
   const [isRefreshingProviders, setIsRefreshingProviders] = useState(false);
+  const [isAddInstanceDialogOpen, setIsAddInstanceDialogOpen] = useState(false);
+  // Collapsible state per provider-instance card, keyed by the instance id.
+  // `Record<string, boolean>` so we don't need to preseed an entry for every
+  // configured instance — an absent key reads as collapsed. Default-slot
+  // rows share this state: their id is the driver slug
+  // (`defaultInstanceIdForDriver(driver)`), which is also `ProviderDriverKind` at
+  // runtime, so a pre-existing open key for e.g. "codex" persists across
+  // the legacy/unified render swap.
+  const [openInstanceDetails, setOpenInstanceDetails] = useState<Record<string, boolean>>({});
   const refreshingRef = useRef(false);
-  const modelListRefs = useRef<Partial<Record<ProviderKind, HTMLDivElement | null>>>({});
   const refreshProviders = useCallback(() => {
     if (refreshingRef.current) return;
     refreshingRef.current = true;
@@ -663,9 +491,11 @@ export function GeneralSettingsPanel() {
   const visibleProviderSettings = PROVIDER_SETTINGS.filter(
     (providerSettings) =>
       providerSettings.provider !== "cursor" ||
-      serverProviders.some((provider) => provider.provider === "cursor"),
+      serverProviders.some(
+        (provider) =>
+          provider.instanceId === defaultInstanceIdForDriver(ProviderDriverKind.make("cursor")),
+      ),
   );
-  const codexHomePath = settings.providers.codex.homePath;
   const logsDirectoryPath = observability?.logsDirectoryPath ?? null;
   const diagnosticsDescription = (() => {
     const exports: string[] = [];
@@ -680,45 +510,21 @@ export function GeneralSettingsPanel() {
   })();
 
   const textGenerationModelSelection = resolveAppModelSelectionState(settings, serverProviders);
-  const textGenProvider = textGenerationModelSelection.provider;
+  const textGenInstanceId = textGenerationModelSelection.instanceId;
   const textGenModel = textGenerationModelSelection.model;
   const textGenModelOptions = textGenerationModelSelection.options;
-  const staticProviderModelOptions = useMemo(
-    () =>
-      buildModelOptionsByProvider({
-        customCodexModels: settings.providers.codex.customModels,
-        customCopilotModels: settings.providers.copilot.customModels,
-        customClaudeModels: settings.providers.claudeAgent.customModels,
-        customCursorModels: settings.providers.cursor.customModels,
-        customOpencodeModels: settings.providers.opencode.customModels,
-        customGeminiCliModels: settings.providers.geminiCli.customModels,
-        customAmpModels: settings.providers.amp.customModels,
-        customKiloModels: settings.providers.kilo.customModels,
-      }),
-    [settings.providers],
-  );
-  const discoveredProviderModelOptions = useMemo(
-    () =>
-      Object.fromEntries(
-        serverProviders.map((provider) => [
-          provider.provider,
-          provider.models.map((model) => ({
-            slug: model.slug,
-            name: model.name,
-            isCustom: model.isCustom,
-          })),
-        ]),
-      ) as Partial<Record<ProviderKind, (typeof staticProviderModelOptions)[ProviderKind]>>,
-    [serverProviders],
+  const gitModelInstanceEntries = sortProviderInstanceEntries(
+    deriveProviderInstanceEntries(serverProviders),
   );
-  const providerModelOptions = useMemo(
-    () => mergeDiscoveredModels(staticProviderModelOptions, discoveredProviderModelOptions),
-    [discoveredProviderModelOptions, staticProviderModelOptions],
+  const textGenInstanceEntry = gitModelInstanceEntries.find(
+    (entry) => entry.instanceId === textGenInstanceId,
   );
-  const gitModelOptionsByProvider = getCustomModelOptionsByProvider(
+  const textGenProvider: ProviderDriverKind =
+    textGenInstanceEntry?.driverKind ?? DEFAULT_DRIVER_KIND;
+  const gitModelOptionsByInstance = getCustomModelOptionsByInstance(
     settings,
     serverProviders,
-    textGenProvider,
+    textGenInstanceId,
     textGenModel,
   );
   const isGitWritingModelDirty = !Equal.equals(
@@ -770,159 +576,220 @@ export function GeneralSettingsPanel() {
   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;
-      }
+  const lastCheckedAt =
+    serverProviders.length > 0
+      ? serverProviders.reduce(
+          (latest, provider) => (provider.checkedAt > latest ? provider.checkedAt : latest),
+          serverProviders[0]!.checkedAt,
+        )
+      : null;
 
-      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],
+  /**
+   * Build the list of rows to render, one per configured instance. Each
+   * row carries enough context to drive `ProviderInstanceCard` without
+   * threading storage concerns: whether it's a built-in default slot (in
+   * which case `isDefault` is true, deletion is gated off, and the
+   * effective envelope may have been synthesized from legacy just for
+   * this render), the driver kind narrow for the in-card model-slug
+   * normalization, and whether a reset-to-factory action is warranted.
+   *
+   * Ordering mirrors the prior split: visible built-in default slots
+   * first (one per visible kind), then user-authored custom instances
+   * grouped by driver after their default sibling, then orphan instances
+   * whose driver isn't in the visible-defaults set.
+   */
+  interface InstanceRow {
+    readonly instanceId: ProviderInstanceId;
+    readonly instance: ProviderInstanceConfig;
+    readonly driver: ProviderDriverKind;
+    /** True for the slot whose id is `defaultInstanceIdForDriver(driver)`. */
+    readonly isDefault: boolean;
+    /**
+     * True when this default slot differs from the factory defaults —
+     * either through an explicit `providerInstances[defaultId]` entry,
+     * or through a non-default legacy `settings.providers[kind]` struct
+     * that we're still bridging. Used to show the reset-to-factory
+     * affordance. Undefined for custom rows (they have a delete button
+     * instead; "factory defaults" isn't meaningful).
+     */
+    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 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 rows: InstanceRow[] = [];
+  const visibleDriverKinds = new Set<ProviderDriverKind>(
+    visibleProviderSettings.map((providerSettings) => providerSettings.provider),
   );
 
-  const providerCards = visibleProviderSettings.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, providerConfig.enabled);
-    const liveModelsBySlug = new Map(
-      (liveProvider?.models ?? []).map((model) => [model.slug, model]),
-    );
-    const models: ReadonlyArray<ServerProviderModel> = providerModelOptions[
-      providerSettings.provider
-    ].map(
-      (modelOption: ModelOptionEntry) =>
-        liveModelsBySlug.get(modelOption.slug) ?? {
-          slug: modelOption.slug,
-          name: modelOption.name,
-          isCustom: modelOption.isCustom ?? false,
-          capabilities: null,
-        },
+  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);
+    // Prefer an explicit `providerInstances[defaultId]` entry when one
+    // exists (every edit via this UI promotes the default slot into
+    // that map); fall back to synthesizing one from the legacy
+    // `settings.providers[kind]` struct so first-time viewers still see
+    // their persisted config.
+    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,
+    });
+    // Non-default customs for this driver kind follow their default.
+    for (const [id, instance] of instancesByDriver.get(providerSettings.provider) ?? []) {
+      if (id === defaultInstanceId) continue;
+      rows.push({ instanceId: id, instance, driver: instance.driver, isDefault: false });
+    }
+  }
+  // Orphan instances: drivers the visible-defaults list doesn't cover
+  // (e.g. Cursor when the server hasn't reported it but the user has
+  // authored a Cursor instance anyway, or fork drivers not shipped by
+  // this build). Preserve insertion order within each driver.
+  for (const [driver, list] of instancesByDriver) {
+    if (visibleDriverKinds.has(driver)) continue;
+    for (const [id, instance] of list) {
+      const isDefaultSlot = defaultSlotIdsBySource.has(String(id));
+      rows.push({
+        instanceId: id,
+        instance,
+        driver: instance.driver,
+        isDefault: isDefaultSlot,
+      });
+    }
+  }
+
+  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,
+      }),
     );
+  };
 
-    return {
-      provider: providerSettings.provider,
-      title: providerSettings.title,
-      badgeLabel: providerSettings.badgeLabel,
-      binaryPlaceholder: providerSettings.binaryPlaceholder,
-      binaryDescription: providerSettings.binaryDescription,
-      homePathKey: providerSettings.homePathKey,
-      homePlaceholder: providerSettings.homePlaceholder,
-      homeDescription: providerSettings.homeDescription,
-      apiEndpointPlaceholder: providerSettings.apiEndpointPlaceholder,
-      apiEndpointDescription: providerSettings.apiEndpointDescription,
-      serverUrlPlaceholder: providerSettings.serverUrlPlaceholder,
-      serverUrlDescription: providerSettings.serverUrlDescription,
-      serverPasswordPlaceholder: providerSettings.serverPasswordPlaceholder,
-      serverPasswordDescription: providerSettings.serverPasswordDescription,
-      apiEndpointValue:
-        "apiEndpoint" in providerConfig ? (providerConfig.apiEndpoint as string) : "",
-      serverUrlValue: "serverUrl" in providerConfig ? (providerConfig.serverUrl as string) : "",
-      serverPasswordValue:
-        "serverPassword" in providerConfig ? (providerConfig.serverPassword as string) : "",
-      customModelExample: providerSettings.customModelExample,
-      binaryPathValue: providerConfig.binaryPath,
-      isDirty: !Equal.equals(providerConfig, defaultProviderConfig),
-      liveProvider,
-      models,
-      providerConfig,
-      statusStyle: PROVIDER_STATUS_STYLES[statusKey],
-      summary,
-      versionLabel: getProviderVersionLabel(liveProvider?.version),
-    };
-  });
+  const deleteProviderInstance = (id: ProviderInstanceId) => {
+    updateSettings({
+      providerInstances: withoutProviderInstanceKey(settings.providerInstances, id),
+      providerModelPreferences: withoutProviderInstanceKey(settings.providerModelPreferences, id),
+      favorites: withoutProviderInstanceFavorites(settings.favorites ?? [], id),
+    });
+  };
 
-  const lastCheckedAt =
-    serverProviders.length > 0
-      ? serverProviders.reduce(
-          (latest, provider) => (provider.checkedAt > latest ? provider.checkedAt : latest),
-          serverProviders[0]!.checkedAt,
-        )
-      : null;
+  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 })),
+      ],
+    });
+  };
+
+  /**
+   * Reset a built-in default slot back to factory defaults. Clears both
+   * the legacy `settings.providers[kind]` struct and any explicit
+   * `providerInstances[defaultId]` entry that has promoted legacy into
+   * the new map, so hydration re-synthesizes a clean envelope on next
+   * load. Safe to call on drivers that have never been edited.
+   */
+  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>
@@ -1026,6 +893,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."
@@ -1054,12 +947,12 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="Task sidebar"
-          description="Open the plan and task sidebar automatically when steps appear."
+          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="task sidebar"
+                label="auto-open task panel"
                 onClick={() =>
                   updateSettings({
                     autoOpenPlanSidebar: DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar,
@@ -1074,7 +967,7 @@ export function GeneralSettingsPanel() {
               onCheckedChange={(checked) =>
                 updateSettings({ autoOpenPlanSidebar: Boolean(checked) })
               }
-              aria-label="Open the task sidebar automatically"
+              aria-label="Open the task panel automatically"
             />
           }
         />
@@ -1137,10 +1030,10 @@ export function GeneralSettingsPanel() {
             ) : null
           }
           control={
-            <Input
+            <DraftInput
               className="w-full sm:w-72"
               value={settings.addProjectBaseDirectory}
-              onChange={(event) => updateSettings({ addProjectBaseDirectory: event.target.value })}
+              onCommit={(next) => updateSettings({ addProjectBaseDirectory: next })}
               placeholder="~/"
               spellCheck={false}
               aria-label="Add project base directory"
@@ -1219,18 +1112,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}
-                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: createModelSelection(provider, model),
+                        textGenerationModelSelection: createModelSelection(instanceId, model),
                       },
                       serverProviders,
                     ),
@@ -1240,8 +1134,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=""
@@ -1256,7 +1153,7 @@ export function GeneralSettingsPanel() {
                       {
                         ...settings,
                         textGenerationModelSelection: createModelSelection(
-                          textGenProvider,
+                          textGenInstanceId,
                           textGenModel,
                           nextOptions,
                         ),
@@ -1276,6 +1173,22 @@ export function GeneralSettingsPanel() {
         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={
@@ -1300,464 +1213,90 @@ export function GeneralSettingsPanel() {
           </div>
         }
       >
-        {providerCards.map((providerCard) => {
-          const customModelInput = customModelInputByProvider[providerCard.provider];
-          const customModelError = customModelErrorByProvider[providerCard.provider] ?? null;
-          const providerDisplayName =
-            providerCard.liveProvider?.displayName?.trim() ||
-            providerCard.title ||
-            formatProviderKindLabel(providerCard.provider);
-
+        {rows.map((row) => {
+          const driverOption = getDriverOption(row.driver);
+          const liveProvider = serverProviders.find(
+            (candidate) => candidate.instanceId === row.instanceId,
+          );
+          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.badgeLabel ? (
-                        <Badge variant="warning" size="sm" className="shrink-0">
-                          {providerCard.badgeLabel}
-                        </Badge>
-                      ) : null}
-                      {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) => {
+                // When the user disables the exact instance the text-gen
+                // selection points at, fall back to the global default so we
+                // don't leave the selection dangling on a disabled instance.
+                // Prior kind-level behavior cleared on any kind-matching
+                // disable; instance-level addressing makes this narrower and
+                // more accurate (other instances of the same kind stay
+                // untouched).
+                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.provider}-home-path`}
-                          className="block"
-                        >
-                          <span className="text-xs font-medium text-foreground">
-                            CODEX_HOME path
-                          </span>
-                          <Input
-                            id={`provider-install-${providerCard.provider}-home-path`}
-                            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}
-
-                    {providerCard.provider === "claudeAgent" ? (
-                      <div className="border-t border-border/60 px-4 py-3 sm:px-5">
-                        <label htmlFor="provider-install-claudeAgent-launch-args" className="block">
-                          <span className="text-xs font-medium text-foreground">
-                            Launch arguments
-                          </span>
-                          <Input
-                            id="provider-install-claudeAgent-launch-args"
-                            className="mt-1.5"
-                            value={settings.providers.claudeAgent.launchArgs}
-                            onChange={(event) =>
-                              updateSettings({
-                                providers: {
-                                  ...settings.providers,
-                                  claudeAgent: {
-                                    ...settings.providers.claudeAgent,
-                                    launchArgs: event.target.value,
-                                  },
-                                },
-                              })
-                            }
-                            placeholder="e.g. --chrome"
-                            spellCheck={false}
-                          />
-                          <span className="mt-1 block text-xs text-muted-foreground">
-                            Additional CLI arguments passed to Claude Code on session start.
-                          </span>
-                        </label>
-                      </div>
-                    ) : null}
-
-                    {providerCard.apiEndpointPlaceholder && providerCard.provider === "cursor" ? (
-                      <div className="border-t border-border/60 px-4 py-3 sm:px-5">
-                        <label
-                          htmlFor={`provider-install-${providerCard.provider}-api-endpoint`}
-                          className="block"
-                        >
-                          <span className="text-xs font-medium text-foreground">API endpoint</span>
-                          <Input
-                            id={`provider-install-${providerCard.provider}-api-endpoint`}
-                            className="mt-1.5"
-                            value={providerCard.apiEndpointValue}
-                            onChange={(event) =>
-                              updateSettings({
-                                providers: {
-                                  ...settings.providers,
-                                  cursor: {
-                                    ...settings.providers.cursor,
-                                    apiEndpoint: event.target.value,
-                                  },
-                                },
-                              })
-                            }
-                            placeholder={providerCard.apiEndpointPlaceholder}
-                            spellCheck={false}
-                          />
-                          {providerCard.apiEndpointDescription ? (
-                            <span className="mt-1 block text-xs text-muted-foreground">
-                              {providerCard.apiEndpointDescription}
-                            </span>
-                          ) : null}
-                        </label>
-                      </div>
-                    ) : null}
-
-                    {providerCard.serverUrlPlaceholder && providerCard.provider === "opencode" ? (
-                      <div className="border-t border-border/60 px-4 py-3 sm:px-5">
-                        <label
-                          htmlFor={`provider-install-${providerCard.provider}-server-url`}
-                          className="block"
-                        >
-                          <span className="text-xs font-medium text-foreground">
-                            {providerCard.title} server URL
-                          </span>
-                          <Input
-                            id={`provider-install-${providerCard.provider}-server-url`}
-                            className="mt-1.5"
-                            value={providerCard.serverUrlValue}
-                            onChange={(event) =>
-                              updateSettings({
-                                providers: {
-                                  ...settings.providers,
-                                  opencode: {
-                                    ...settings.providers.opencode,
-                                    serverUrl: event.target.value,
-                                  },
-                                },
-                              })
-                            }
-                            placeholder={providerCard.serverUrlPlaceholder}
-                            spellCheck={false}
-                          />
-                          {providerCard.serverUrlDescription ? (
-                            <span className="mt-1 block text-xs text-muted-foreground">
-                              {providerCard.serverUrlDescription}
-                            </span>
-                          ) : null}
-                        </label>
-                      </div>
-                    ) : null}
-
-                    {providerCard.serverPasswordPlaceholder &&
-                    providerCard.provider === "opencode" ? (
-                      <div className="border-t border-border/60 px-4 py-3 sm:px-5">
-                        <label
-                          htmlFor={`provider-install-${providerCard.provider}-server-password`}
-                          className="block"
-                        >
-                          <span className="text-xs font-medium text-foreground">
-                            {providerCard.title} server password
-                          </span>
-                          <Input
-                            id={`provider-install-${providerCard.provider}-server-password`}
-                            className="mt-1.5"
-                            type="password"
-                            value={providerCard.serverPasswordValue}
-                            onChange={(event) =>
-                              updateSettings({
-                                providers: {
-                                  ...settings.providers,
-                                  opencode: {
-                                    ...settings.providers.opencode,
-                                    serverPassword: event.target.value,
-                                  },
-                                },
-                              })
-                            }
-                            placeholder={providerCard.serverPasswordPlaceholder}
-                            spellCheck={false}
-                          />
-                          {providerCard.serverPasswordDescription ? (
-                            <span className="mt-1 block text-xs text-muted-foreground">
-                              {providerCard.serverPasswordDescription}
-                            </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?.length ?? 0) > 0 ||
-                            (caps?.variantOptions?.length ?? 0) > 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.customModelExample}
-                          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,
+                })
+              }
+            />
           );
         })}
       </SettingsSection>
 
+      <AddProviderInstanceDialog
+        open={isAddInstanceDialogOpen}
+        onOpenChange={setIsAddInstanceDialogOpen}
+      />
+
       <SettingsSection title="Advanced">
         <SettingsRow
           title="Keybindings"
diff --git a/apps/web/src/components/settings/SettingsSidebarNav.tsx b/apps/web/src/components/settings/SettingsSidebarNav.tsx
index a150a7c75fd..88260355d97 100644
--- a/apps/web/src/components/settings/SettingsSidebarNav.tsx
+++ b/apps/web/src/components/settings/SettingsSidebarNav.tsx
@@ -1,6 +1,6 @@
-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, GitBranchIcon, Link2Icon, Settings2Icon } from "lucide-react";
+import { useCanGoBack, useNavigate } from "@tanstack/react-router";
 
 import {
   SidebarContent,
@@ -10,10 +10,12 @@ import {
   SidebarMenuButton,
   SidebarMenuItem,
   SidebarSeparator,
+  useSidebar,
 } from "../ui/sidebar";
 
 export type SettingsSectionPath =
   | "/settings/general"
+  | "/settings/source-control"
   | "/settings/connections"
   | "/settings/archived";
 
@@ -23,12 +25,34 @@ export const SETTINGS_NAV_ITEMS: ReadonlyArray<{
   icon: ComponentType<{ className?: string }>;
 }> = [
   { label: "General", to: "/settings/general", icon: Settings2Icon },
+  { 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 +72,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 +97,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..c58a4468363
--- /dev/null
+++ b/apps/web/src/components/settings/SourceControlSettings.tsx
@@ -0,0 +1,392 @@
+import { GitPullRequestIcon, RefreshCwIcon } from "lucide-react";
+import { Option } from "effect";
+import { type ReactNode } from "react";
+import type {
+  SourceControlProviderKind,
+  SourceControlDiscoveryResult,
+  SourceControlProviderAuth,
+  SourceControlProviderDiscoveryItem,
+  VcsDriverKind,
+  VcsDiscoveryItem,
+} from "@t3tools/contracts";
+
+import { cn } from "../../lib/utils";
+import {
+  refreshSourceControlDiscovery,
+  useSourceControlDiscovery,
+} from "../../lib/sourceControlDiscoveryState";
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "../ui/empty";
+import { Skeleton } from "../ui/skeleton";
+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 { 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;
+
+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,
+}: {
+  readonly item: VcsDiscoveryItem | SourceControlProviderDiscoveryItem;
+}) {
+  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;
+
+  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} />
+              <h3 className="truncate text-[13px] font-semibold tracking-[-0.01em] text-foreground">
+                {item.label}
+              </h3>
+              {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">
+              {itemSummary({ item, auth, authAccount })}
+            </p>
+          </div>
+          <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
+            {!isVcsNotReady(item) ? (
+              <Switch checked={enabled} disabled aria-label={`${item.label} availability`} />
+            ) : null}
+          </div>
+        </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} />
+              ))}
+            </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..3d41e375965
--- /dev/null
+++ b/apps/web/src/components/settings/providerDriverMeta.ts
@@ -0,0 +1,124 @@
+import {
+  AmpSettings,
+  ClaudeSettings,
+  CodexSettings,
+  CopilotSettings,
+  CursorSettings,
+  GeminiCliSettings,
+  KiloSettings,
+  OpenCodeSettings,
+  ProviderDriverKind,
+} from "@t3tools/contracts";
+import type { Schema } from "effect";
+import {
+  AmpIcon,
+  ClaudeAI,
+  CopilotIcon,
+  CursorIcon,
+  GeminiCliIcon,
+  type Icon,
+  KiloIcon,
+  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,
+  },
+  {
+    value: ProviderDriverKind.make("amp"),
+    label: "Amp",
+    icon: AmpIcon,
+    settingsSchema: AmpSettings,
+    badgeLabel: "Fork Extension",
+  },
+  {
+    value: ProviderDriverKind.make("copilot"),
+    label: "GitHub Copilot",
+    icon: CopilotIcon,
+    settingsSchema: CopilotSettings,
+    badgeLabel: "Fork Extension",
+  },
+  {
+    value: ProviderDriverKind.make("geminiCli"),
+    label: "Gemini CLI",
+    icon: GeminiCliIcon,
+    settingsSchema: GeminiCliSettings,
+    badgeLabel: "Fork Extension",
+  },
+  {
+    value: ProviderDriverKind.make("kilo"),
+    label: "Kilo Code",
+    icon: KiloIcon,
+    settingsSchema: KiloSettings,
+    badgeLabel: "Fork Extension",
+  },
+];
+
+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..d437399da2e
--- /dev/null
+++ b/apps/web/src/components/settings/providerStatus.ts
@@ -0,0 +1,91 @@
+import type { ServerProvider } 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}`;
+}
diff --git a/apps/web/src/components/settings/settingsLayout.tsx b/apps/web/src/components/settings/settingsLayout.tsx
index f41e32f9e5c..c464165bb3e 100644
--- a/apps/web/src/components/settings/settingsLayout.tsx
+++ b/apps/web/src/components/settings/settingsLayout.tsx
@@ -28,13 +28,13 @@ export function SettingsSection({
 }) {
   return (
     <section className="space-y-2.5">
-      <div className="flex items-center justify-between px-1">
+      <div className="flex h-5 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}
@@ -52,7 +52,7 @@ export function SettingsRow({
   children,
 }: {
   title: ReactNode;
-  description: string;
+  description: ReactNode;
   status?: ReactNode;
   resetAction?: ReactNode;
   control?: ReactNode;
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/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/scroll-area.tsx b/apps/web/src/components/ui/scroll-area.tsx
index c8aa6dc96db..37ffbb185a2 100644
--- a/apps/web/src/components/ui/scroll-area.tsx
+++ b/apps/web/src/components/ui/scroll-area.tsx
@@ -23,7 +23,7 @@ function ScrollArea({
     >
       <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-y-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",
           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 && "[scrollbar-gutter:stable]",
diff --git a/apps/web/src/components/ui/sidebar.tsx b/apps/web/src/components/ui/sidebar.tsx
index 2da4cf6a88a..c2c187268c0 100644
--- a/apps/web/src/components/ui/sidebar.tsx
+++ b/apps/web/src/components/ui/sidebar.tsx
@@ -252,7 +252,14 @@ 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>
diff --git a/apps/web/src/composerDraftStore.test.ts b/apps/web/src/composerDraftStore.test.ts
index 4b7b52e6e60..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" | "cursor",
+  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");
@@ -901,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,
       }),
@@ -917,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", () => {
@@ -929,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,
       }),
@@ -943,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,
       }),
     );
@@ -967,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,
       }),
     );
@@ -987,15 +1033,18 @@ 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,
       }),
@@ -1007,22 +1056,24 @@ describe("composerDraftStore modelSelection", () => {
 
     store.setModelSelection(
       threadRef,
-      modelSelection("cursor", "claude-opus-4-6", {
+      modelSelection(CURSOR_DRIVER, "claude-opus-4-6", {
         reasoning: "xhigh",
         fastMode: true,
         thinking: false,
       }),
     );
 
-    store.setProviderModelOptions(threadRef, "cursor", {
-      reasoning: "high",
-      fastMode: false,
-      thinking: true,
-    });
+    store.setProviderModelOptions(
+      threadRef,
+      CURSOR_DRIVER,
+      toSelections({ reasoning: "medium", fastMode: false, thinking: true }),
+    );
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.cursor).toEqual(
-      modelSelection("cursor", "claude-opus-4-6", {
-        reasoning: "high",
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CURSOR_INSTANCE],
+    ).toEqual(
+      modelSelection(CURSOR_DRIVER, "claude-opus-4-6", {
+        reasoning: "medium",
         fastMode: false,
         thinking: true,
       }),
@@ -1032,25 +1083,22 @@ describe("composerDraftStore modelSelection", () => {
   it("preserves the selected Cursor model when only traits change", () => {
     const store = useComposerDraftStore.getState();
 
-    store.setProviderModelOptions(
-      threadRef,
-      "cursor",
-      {
-        reasoning: "high",
-      },
-      {
-        model: "gpt-5.4-medium",
-        persistSticky: true,
-      },
-    );
+    store.setProviderModelOptions(threadRef, CURSOR_DRIVER, toSelections({ reasoning: "high" }), {
+      model: "gpt-5.4",
+      persistSticky: true,
+    });
 
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider.cursor).toEqual(
-      modelSelection("cursor", "gpt-5.4-medium", {
+    expect(
+      draftFor(threadId, TEST_ENVIRONMENT_ID)?.modelSelectionByProvider[CURSOR_INSTANCE],
+    ).toEqual(
+      modelSelection(CURSOR_DRIVER, "gpt-5.4", {
         reasoning: "high",
       }),
     );
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.cursor).toEqual(
-      modelSelection("cursor", "gpt-5.4-medium", {
+    expect(
+      useComposerDraftStore.getState().stickyModelSelectionByProvider[CURSOR_INSTANCE],
+    ).toEqual(
+      modelSelection(CURSOR_DRIVER, "gpt-5.4", {
         reasoning: "high",
       }),
     );
@@ -1060,25 +1108,29 @@ 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", {
-      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", () => {
@@ -1097,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", () => {
@@ -1112,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,
       }),
     );
@@ -1147,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" }));
   });
 });
 
@@ -1185,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"));
   });
 });
 
@@ -1202,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,
       }),
@@ -1220,10 +1280,10 @@ 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");
   });
@@ -1232,7 +1292,7 @@ describe("composerDraftStore sticky composer settings", () => {
     const store = useComposerDraftStore.getState();
 
     store.setStickyModelSelection(
-      modelSelection("cursor", "gpt-5.4-medium", {
+      modelSelection(CURSOR_DRIVER, "gpt-5.4", {
         reasoning: undefined,
         fastMode: undefined,
         thinking: undefined,
@@ -1240,9 +1300,9 @@ describe("composerDraftStore sticky composer settings", () => {
       }),
     );
 
-    expect(useComposerDraftStore.getState().stickyModelSelectionByProvider.cursor).toEqual(
-      modelSelection("cursor", "gpt-5.4-medium"),
-    );
+    expect(
+      useComposerDraftStore.getState().stickyModelSelectionByProvider[CURSOR_INSTANCE],
+    ).toEqual(modelSelection(CURSOR_DRIVER, "gpt-5.4"));
     expect(useComposerDraftStore.getState().stickyActiveProvider).toBe("cursor");
   });
 
@@ -1251,12 +1311,12 @@ describe("composerDraftStore sticky composer settings", () => {
     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",
     });
@@ -1275,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 7f33309f876..9533ea0b90b 100644
--- a/apps/web/src/composerDraftStore.ts
+++ b/apps/web/src/composerDraftStore.ts
@@ -1,16 +1,14 @@
 import {
-  CURSOR_REASONING_OPTIONS,
+  DEFAULT_MODEL,
   DEFAULT_MODEL_BY_PROVIDER,
-  type CursorModelOptions,
-  type CursorReasoningOption,
-  ClaudeAgentEffort,
-  CodexReasoningEffort,
+  defaultInstanceIdForDriver,
   type EnvironmentId,
   ModelSelection,
   ProjectId,
+  ProviderInstanceId,
   ProviderInteractionMode,
-  ProviderKind,
-  ProviderModelOptions,
+  ProviderDriverKind,
+  ProviderOptionSelection,
   RuntimeMode,
   type ServerProvider,
   type ScopedProjectRef,
@@ -31,7 +29,7 @@ import { DeepMutable } from "effect/Types";
 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,
@@ -46,7 +44,7 @@ import { getDefaultServerModel } from "./providerModels";
 import { UnifiedSettings } from "@t3tools/contracts/settings";
 
 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;
@@ -97,32 +95,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(CodexReasoningEffort),
-  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 &
@@ -130,16 +144,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;
@@ -181,9 +194,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;
 
@@ -202,8 +215,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;
 }
@@ -258,8 +280,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. */
@@ -334,15 +356,19 @@ 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;
@@ -379,37 +405,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>({
@@ -427,7 +471,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,
@@ -530,155 +574,125 @@ function shouldRemoveDraft(draft: ComposerThreadDraftState): boolean {
   );
 }
 
-function normalizeProviderKind(value: unknown): ProviderKind | null {
-  return Schema.is(ProviderKind)(value) ? value : null;
+function normalizeProviderDriverKind(value: unknown): ProviderDriverKind | null {
+  return Schema.is(ProviderDriverKind)(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 cursorCandidate =
-    candidate?.cursor && typeof candidate.cursor === "object"
-      ? (candidate.cursor as Record<string, unknown>)
-      : null;
-  const openCodeCandidate =
-    candidate?.opencode && typeof candidate.opencode === "object"
-      ? (candidate.opencode as Record<string, unknown>)
-      : null;
-
-  const isCodexReasoningEffort = Schema.is(CodexReasoningEffort);
-  const isClaudeAgentEffort = Schema.is(ClaudeAgentEffort);
-
-  const codexReasoningEffort = isCodexReasoningEffort(codexCandidate?.reasoningEffort)
-    ? codexCandidate.reasoningEffort
-    : provider === "codex"
-      ? isCodexReasoningEffort(legacy?.effort)
-        ? legacy.effort
-        : undefined
-      : 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 = isClaudeAgentEffort(claudeCandidate?.effort)
-    ? 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 cursorReasoningRaw = cursorCandidate?.reasoning;
-  const cursorReasoning: CursorReasoningOption | undefined =
-    typeof cursorReasoningRaw === "string" &&
-    (CURSOR_REASONING_OPTIONS as readonly string[]).includes(cursorReasoningRaw)
-      ? (cursorReasoningRaw as CursorReasoningOption)
-      : undefined;
-  const cursorFastMode =
-    cursorCandidate?.fastMode === true
-      ? true
-      : cursorCandidate?.fastMode === false
-        ? false
-        : undefined;
-  const cursorThinking =
-    cursorCandidate?.thinking === true
-      ? true
-      : cursorCandidate?.thinking === false
-        ? false
-        : undefined;
-  const cursorContextWindow =
-    typeof cursorCandidate?.contextWindow === "string" && cursorCandidate.contextWindow.length > 0
-      ? cursorCandidate.contextWindow
-      : undefined;
-
-  const cursor: CursorModelOptions | undefined =
-    cursorCandidate !== null
-      ? (() => {
-          const nextCursor = {
-            ...(cursorReasoning ? { reasoning: cursorReasoning } : {}),
-            ...(cursorFastMode !== undefined ? { fastMode: cursorFastMode } : {}),
-            ...(cursorThinking !== undefined ? { thinking: cursorThinking } : {}),
-            ...(cursorContextWindow !== undefined ? { contextWindow: cursorContextWindow } : {}),
-          } satisfies CursorModelOptions;
-          return Object.keys(nextCursor).length > 0 ? nextCursor : undefined;
-        })()
-      : undefined;
-
-  const openCodeVariant =
-    typeof openCodeCandidate?.variant === "string" && openCodeCandidate.variant.length > 0
-      ? openCodeCandidate.variant
-      : undefined;
-  const openCodeAgent =
-    typeof openCodeCandidate?.agent === "string" && openCodeCandidate.agent.length > 0
-      ? openCodeCandidate.agent
-      : undefined;
-  const opencode =
-    openCodeVariant !== undefined || openCodeAgent !== undefined
-      ? {
-          ...(openCodeVariant !== undefined ? { variant: openCodeVariant } : {}),
-          ...(openCodeAgent !== undefined ? { agent: openCodeAgent } : {}),
-        }
-      : 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 && cursor === undefined && !opencode) {
-    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 } : {}),
-    ...(cursor !== undefined ? { cursor } : {}),
-    ...(opencode ? { opencode } : {}),
-  };
+
+  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?: {
@@ -687,99 +701,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 = modelOptions?.[provider];
-  return createModelSelection(provider, model, 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 createModelSelection(modelSelection.provider, modelSelection.model, 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", "cursor", "opencode"] as const) {
       const options = modelOptions[provider];
-      if (options && Object.keys(options).length > 0) {
-        result[provider] = createModelSelection(
-          provider,
-          modelSelection?.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[provider],
+            : (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;
 }
@@ -790,29 +839,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 {
@@ -1398,8 +1487,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 &&
@@ -1407,9 +1496,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 =
@@ -1423,7 +1512,7 @@ function normalizePersistedDraftsByThreadId(
         {
           provider: legacyDraftCandidate.provider,
           model: legacyDraftCandidate.model,
-          modelOptions: normalizedModelOptions ?? legacyDraftCandidate.modelOptions,
+          modelOptions: normalizedModelOptions ?? (legacyDraftCandidate.modelOptions as unknown),
           legacyCodex: legacyDraftCandidate,
         },
       );
@@ -1439,7 +1528,7 @@ function normalizePersistedDraftsByThreadId(
         modelSelection,
         mergedModelOptions,
       );
-      activeProvider = modelSelection?.provider ?? null;
+      activeProvider = modelSelection?.instanceId ?? null;
     }
 
     const hasModelData =
@@ -1470,7 +1559,12 @@ function normalizePersistedDraftsByThreadId(
       prompt,
       attachments,
       ...(terminalContexts.length > 0 ? { terminalContexts } : {}),
-      ...(hasModelData ? { modelSelectionByProvider, activeProvider } : {}),
+      ...(hasModelData
+        ? {
+            modelSelectionByProvider: compactModelSelectionByProvider(modelSelectionByProvider),
+            activeProvider,
+          }
+        : {}),
       ...(runtimeMode ? { runtimeMode } : {}),
       ...(interactionMode ? { interactionMode } : {}),
     };
@@ -1514,7 +1608,7 @@ function migratePersistedComposerDraftStoreState(
     stickyModelSelection,
     nextStickyModelOptions,
   );
-  const stickyActiveProvider = normalizeProviderKind(candidate.stickyProvider) ?? null;
+  const stickyActiveProvider = normalizeProviderInstanceId(candidate.stickyProvider) ?? null;
 
   const { draftThreadsByThreadKey, logicalProjectDraftThreadKeyByLogicalProjectKey } =
     normalizePersistedDraftThreads(rawDraftThreadsByThreadId, rawProjectDraftThreadIdByProjectKey);
@@ -1526,7 +1620,7 @@ function migratePersistedComposerDraftStoreState(
     draftsByThreadKey,
     draftThreadsByThreadKey,
     logicalProjectDraftThreadKeyByLogicalProjectKey,
-    stickyModelSelectionByProvider,
+    stickyModelSelectionByProvider: compactModelSelectionByProvider(stickyModelSelectionByProvider),
     stickyActiveProvider,
   };
 }
@@ -1571,7 +1665,9 @@ function partializeComposerDraftStoreState(
         : {}),
       ...(hasModelData
         ? {
-            modelSelectionByProvider: draft.modelSelectionByProvider,
+            modelSelectionByProvider: compactModelSelectionByProvider(
+              draft.modelSelectionByProvider,
+            ),
             activeProvider: draft.activeProvider,
           }
         : {}),
@@ -1585,7 +1681,9 @@ function partializeComposerDraftStoreState(
     draftThreadsByThreadKey: state.draftThreadsByThreadKey,
     logicalProjectDraftThreadKeyByLogicalProjectKey:
       state.logicalProjectDraftThreadKeyByLogicalProjectKey,
-    stickyModelSelectionByProvider: state.stickyModelSelectionByProvider,
+    stickyModelSelectionByProvider: compactModelSelectionByProvider(
+      state.stickyModelSelectionByProvider,
+    ),
     stickyActiveProvider: state.stickyActiveProvider,
   };
 }
@@ -1608,17 +1706,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 =
@@ -1643,7 +1743,7 @@ function normalizeCurrentPersistedComposerDraftStoreState(
       stickyModelSelection,
       nextStickyModelOptions,
     );
-    stickyActiveProvider = normalizeProviderKind(normalizedPersistedState.stickyProvider);
+    stickyActiveProvider = normalizeProviderInstanceId(normalizedPersistedState.stickyProvider);
   }
 
   return {
@@ -1653,7 +1753,7 @@ function normalizeCurrentPersistedComposerDraftStoreState(
     ),
     draftThreadsByThreadKey,
     logicalProjectDraftThreadKeyByLogicalProjectKey,
-    stickyModelSelectionByProvider,
+    stickyModelSelectionByProvider: compactModelSelectionByProvider(stickyModelSelectionByProvider),
     stickyActiveProvider,
   };
 }
@@ -1782,9 +1882,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,
@@ -2145,18 +2245,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,
             };
           });
         },
@@ -2176,8 +2276,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,
                 };
@@ -2263,20 +2367,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] = createModelSelection(
-                  normalized.provider,
+                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
@@ -2302,29 +2406,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", "cursor", "opencode"] 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] = createModelSelection(
-                  provider,
-                  current?.model ?? DEFAULT_MODEL_BY_PROVIDER[provider],
+              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)) {
@@ -2348,19 +2451,17 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
           if (threadKey.length === 0) {
             return;
           }
-          const normalizedProvider = normalizeProviderKind(provider);
+          const normalizedProvider = normalizeProviderDriverKind(provider);
           if (normalizedProvider === null) {
             return;
           }
+          const instanceKey = defaultInstanceIdForDriver(normalizedProvider);
           const fallbackModel =
             normalizeModelSlug(options?.model, normalizedProvider) ??
-            DEFAULT_MODEL_BY_PROVIDER[normalizedProvider];
-          // Normalize just this provider's options
-          const normalizedOpts = normalizeProviderModelOptions(
-            { [normalizedProvider]: nextProviderOptions },
-            normalizedProvider,
-          );
-          const providerOpts = normalizedOpts?.[normalizedProvider];
+            DEFAULT_MODEL_BY_PROVIDER[normalizedProvider] ??
+            DEFAULT_MODEL;
+          const providerOpts =
+            nextProviderOptions && nextProviderOptions.length > 0 ? nextProviderOptions : undefined;
 
           set((state) => {
             const existing = state.draftsByThreadKey[threadKey];
@@ -2368,16 +2469,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] = createModelSelection(
-                normalizedProvider,
+              nextMap[instanceKey] = createModelSelection(
+                instanceKey,
                 currentForProvider?.model ?? fallbackModel,
                 providerOpts,
               );
-            } else if (currentForProvider?.options) {
+            } 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
@@ -2386,20 +2487,20 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
             if (options?.persistSticky === true) {
               nextStickyMap = { ...state.stickyModelSelectionByProvider };
               const stickyBase =
-                nextStickyMap[normalizedProvider] ??
-                base.modelSelectionByProvider[normalizedProvider] ??
-                createModelSelection(normalizedProvider, fallbackModel);
+                nextStickyMap[instanceKey] ??
+                base.modelSelectionByProvider[instanceKey] ??
+                createModelSelection(instanceKey, fallbackModel);
               if (providerOpts) {
-                nextStickyMap[normalizedProvider] = createModelSelection(
-                  normalizedProvider,
+                nextStickyMap[instanceKey] = createModelSelection(
+                  instanceKey,
                   stickyBase.model,
                   providerOpts,
                 );
-              } else if (stickyBase.options) {
+              } 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 (
@@ -2850,7 +2951,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;
@@ -2863,6 +2970,7 @@ export function useEffectiveComposerModelState(input: {
         draft,
         providers: input.providers,
         selectedProvider: input.selectedProvider,
+        selectedInstanceId: input.selectedInstanceId,
         threadModelSelection: input.threadModelSelection,
         projectModelSelection: input.projectModelSelection,
         settings: input.settings,
@@ -2872,6 +2980,7 @@ export function useEffectiveComposerModelState(input: {
       input.providers,
       input.settings,
       input.projectModelSelection,
+      input.selectedInstanceId,
       input.selectedProvider,
       input.threadModelSelection,
     ],
diff --git a/apps/web/src/customModels.ts b/apps/web/src/customModels.ts
deleted file mode 100644
index e2afa21bfd5..00000000000
--- a/apps/web/src/customModels.ts
+++ /dev/null
@@ -1,326 +0,0 @@
-import type { ProviderKind } from "@t3tools/contracts";
-import {
-  getDefaultModel,
-  getModelOptions,
-  normalizeModelSlug,
-  resolveSelectableModel,
-} from "@t3tools/shared/model";
-
-import type { AppSettings } from "./appSettings";
-
-const MAX_CUSTOM_MODEL_COUNT = 32;
-export const MAX_CUSTOM_MODEL_LENGTH = 256;
-
-export type CustomModelSettingsKey =
-  | "customCodexModels"
-  | "customCopilotModels"
-  | "customClaudeModels"
-  | "customCursorModels"
-  | "customOpencodeModels"
-  | "customGeminiCliModels"
-  | "customAmpModels"
-  | "customKiloModels";
-
-export type ProviderCustomModelConfig = {
-  provider: ProviderKind;
-  settingsKey: CustomModelSettingsKey;
-  defaultSettingsKey: CustomModelSettingsKey;
-  title: string;
-  description: string;
-  placeholder: string;
-  example: string;
-};
-
-const BUILT_IN_MODEL_SLUGS_BY_PROVIDER: Record<ProviderKind, ReadonlySet<string>> = {
-  codex: new Set(getModelOptions("codex").map((option) => option.slug)),
-  copilot: new Set(getModelOptions("copilot").map((option) => option.slug)),
-  claudeAgent: new Set(getModelOptions("claudeAgent").map((option) => option.slug)),
-  cursor: new Set(getModelOptions("cursor").map((option) => option.slug)),
-  opencode: new Set(getModelOptions("opencode").map((option) => option.slug)),
-  geminiCli: new Set(getModelOptions("geminiCli").map((option) => option.slug)),
-  amp: new Set(getModelOptions("amp").map((option) => option.slug)),
-  kilo: new Set(getModelOptions("kilo").map((option) => option.slug)),
-};
-
-const PROVIDER_CUSTOM_MODEL_CONFIG: Record<ProviderKind, ProviderCustomModelConfig> = {
-  codex: {
-    provider: "codex",
-    settingsKey: "customCodexModels",
-    defaultSettingsKey: "customCodexModels",
-    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",
-  },
-  copilot: {
-    provider: "copilot",
-    settingsKey: "customCopilotModels",
-    defaultSettingsKey: "customCopilotModels",
-    title: "Copilot",
-    description: "Save additional Copilot model slugs for the picker and `/model` command.",
-    placeholder: "your-copilot-model-slug",
-    example: "gpt-4o-copilot",
-  },
-  claudeAgent: {
-    provider: "claudeAgent",
-    settingsKey: "customClaudeModels",
-    defaultSettingsKey: "customClaudeModels",
-    title: "Claude",
-    description: "Save additional Claude model slugs for the picker and `/model` command.",
-    placeholder: "your-claude-model-slug",
-    example: "claude-sonnet-5-0",
-  },
-  cursor: {
-    provider: "cursor",
-    settingsKey: "customCursorModels",
-    defaultSettingsKey: "customCursorModels",
-    title: "Cursor",
-    description: "Save additional Cursor model slugs for the picker and `/model` command.",
-    placeholder: "your-cursor-model-slug",
-    example: "cursor-fast",
-  },
-  opencode: {
-    provider: "opencode",
-    settingsKey: "customOpencodeModels",
-    defaultSettingsKey: "customOpencodeModels",
-    title: "OpenCode",
-    description: "Save additional OpenCode model slugs for the picker and `/model` command.",
-    placeholder: "your-opencode-model-slug",
-    example: "opencode-pro",
-  },
-  geminiCli: {
-    provider: "geminiCli",
-    settingsKey: "customGeminiCliModels",
-    defaultSettingsKey: "customGeminiCliModels",
-    title: "Gemini CLI",
-    description: "Save additional Gemini CLI model slugs for the picker and `/model` command.",
-    placeholder: "your-gemini-model-slug",
-    example: "gemini-2.0-ultra",
-  },
-  amp: {
-    provider: "amp",
-    settingsKey: "customAmpModels",
-    defaultSettingsKey: "customAmpModels",
-    title: "Amp",
-    description: "Save additional Amp model slugs for the picker and `/model` command.",
-    placeholder: "your-amp-model-slug",
-    example: "amp-pro",
-  },
-  kilo: {
-    provider: "kilo",
-    settingsKey: "customKiloModels",
-    defaultSettingsKey: "customKiloModels",
-    title: "Kilo",
-    description: "Save additional Kilo model slugs for the picker and `/model` command.",
-    placeholder: "your-kilo-model-slug",
-    example: "kilo-advanced",
-  },
-};
-
-export const MODEL_PROVIDER_SETTINGS = Object.values(PROVIDER_CUSTOM_MODEL_CONFIG);
-
-export type ProviderCustomModelSettings = Pick<
-  AppSettings,
-  | "customCodexModels"
-  | "customCopilotModels"
-  | "customClaudeModels"
-  | "customCursorModels"
-  | "customOpencodeModels"
-  | "customGeminiCliModels"
-  | "customAmpModels"
-  | "customKiloModels"
->;
-
-export interface AppModelOption {
-  slug: string;
-  name: string;
-  isCustom: boolean;
-}
-
-export function normalizeCustomModelSlugs(
-  models: Iterable<string | null | undefined>,
-  provider: ProviderKind = "codex",
-): string[] {
-  const normalizedModels: string[] = [];
-  const seen = new Set<string>();
-  const builtInModelSlugs = BUILT_IN_MODEL_SLUGS_BY_PROVIDER[provider];
-
-  for (const candidate of models) {
-    const normalized = normalizeModelSlug(candidate, provider);
-    if (
-      !normalized ||
-      normalized.length > MAX_CUSTOM_MODEL_LENGTH ||
-      builtInModelSlugs.has(normalized) ||
-      seen.has(normalized)
-    ) {
-      continue;
-    }
-
-    seen.add(normalized);
-    normalizedModels.push(normalized);
-    if (normalizedModels.length >= MAX_CUSTOM_MODEL_COUNT) {
-      break;
-    }
-  }
-
-  return normalizedModels;
-}
-
-export function getCustomModelsForProvider(
-  settings: ProviderCustomModelSettings,
-  provider: ProviderKind,
-): readonly string[] {
-  switch (provider) {
-    case "copilot":
-      return settings.customCopilotModels;
-    case "claudeAgent":
-      return settings.customClaudeModels;
-    case "cursor":
-      return settings.customCursorModels;
-    case "opencode":
-      return settings.customOpencodeModels;
-    case "geminiCli":
-      return settings.customGeminiCliModels;
-    case "amp":
-      return settings.customAmpModels;
-    case "kilo":
-      return settings.customKiloModels;
-    case "codex":
-    default:
-      return settings.customCodexModels;
-  }
-}
-
-export function patchCustomModels(provider: ProviderKind, models: string[]): Partial<AppSettings> {
-  switch (provider) {
-    case "copilot":
-      return { customCopilotModels: models };
-    case "claudeAgent":
-      return { customClaudeModels: models };
-    case "cursor":
-      return { customCursorModels: models };
-    case "opencode":
-      return { customOpencodeModels: models };
-    case "geminiCli":
-      return { customGeminiCliModels: models };
-    case "amp":
-      return { customAmpModels: models };
-    case "kilo":
-      return { customKiloModels: models };
-    case "codex":
-    default:
-      return { customCodexModels: models };
-  }
-}
-
-export function getDefaultCustomModelsForProvider(
-  defaults: Pick<AppSettings, CustomModelSettingsKey>,
-  provider: ProviderKind,
-): readonly string[] {
-  return defaults[PROVIDER_CUSTOM_MODEL_CONFIG[provider].defaultSettingsKey];
-}
-
-export function getCustomModelsByProvider(
-  settings: Pick<AppSettings, CustomModelSettingsKey>,
-): Record<ProviderKind, readonly string[]> {
-  return {
-    codex: getCustomModelsForProvider(settings, "codex"),
-    copilot: getCustomModelsForProvider(settings, "copilot"),
-    claudeAgent: getCustomModelsForProvider(settings, "claudeAgent"),
-    cursor: getCustomModelsForProvider(settings, "cursor"),
-    opencode: getCustomModelsForProvider(settings, "opencode"),
-    geminiCli: getCustomModelsForProvider(settings, "geminiCli"),
-    amp: getCustomModelsForProvider(settings, "amp"),
-    kilo: getCustomModelsForProvider(settings, "kilo"),
-  };
-}
-
-export function getAppModelOptions(
-  provider: ProviderKind,
-  customModels: readonly string[],
-  selectedModel?: string | null,
-): AppModelOption[] {
-  const options: AppModelOption[] = getModelOptions(provider).map(({ slug, name }) => ({
-    slug,
-    name,
-    isCustom: false,
-  }));
-  const seen = new Set(options.map((option) => option.slug));
-  const trimmedSelectedModel = selectedModel?.trim().toLowerCase();
-
-  for (const slug of normalizeCustomModelSlugs(customModels, provider)) {
-    if (seen.has(slug)) {
-      continue;
-    }
-
-    seen.add(slug);
-    options.push({
-      slug,
-      name: slug,
-      isCustom: true,
-    });
-  }
-
-  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 options;
-}
-
-export function resolveAppModelSelection(
-  provider: ProviderKind,
-  customModels: Record<ProviderKind, readonly string[]>,
-  selectedModel: string | null | undefined,
-): string {
-  const customModelsForProvider = customModels[provider];
-  const options = getAppModelOptions(provider, customModelsForProvider, selectedModel);
-  return resolveSelectableModel(provider, selectedModel, options) ?? getDefaultModel(provider);
-}
-
-export function getCustomModelOptionsByProvider(
-  settings: Pick<AppSettings, CustomModelSettingsKey>,
-): Record<ProviderKind, ReadonlyArray<{ slug: string; name: string }>> {
-  const customModelsByProvider = getCustomModelsByProvider(settings);
-  return {
-    codex: getAppModelOptions("codex", customModelsByProvider.codex),
-    copilot: getAppModelOptions("copilot", customModelsByProvider.copilot),
-    claudeAgent: getAppModelOptions("claudeAgent", customModelsByProvider.claudeAgent),
-    cursor: getAppModelOptions("cursor", customModelsByProvider.cursor),
-    opencode: getAppModelOptions("opencode", customModelsByProvider.opencode),
-    geminiCli: getAppModelOptions("geminiCli", customModelsByProvider.geminiCli),
-    amp: getAppModelOptions("amp", customModelsByProvider.amp),
-    kilo: getAppModelOptions("kilo", customModelsByProvider.kilo),
-  };
-}
-
-export function getSlashModelOptions(
-  provider: ProviderKind,
-  customModels: readonly string[],
-  query: string,
-  selectedModel?: string | null,
-): AppModelOption[] {
-  const normalizedQuery = query.trim().toLowerCase();
-  const options = getAppModelOptions(provider, customModels, selectedModel);
-  if (!normalizedQuery) {
-    return options;
-  }
-
-  return options.filter((option) => {
-    const searchSlug = option.slug.toLowerCase();
-    const searchName = option.name.toLowerCase();
-    return searchSlug.includes(normalizedQuery) || searchName.includes(normalizedQuery);
-  });
-}
diff --git a/apps/web/src/environmentApi.ts b/apps/web/src/environmentApi.ts
index 64df079df49..335d68d3720 100644
--- a/apps/web/src/environmentApi.ts
+++ b/apps/web/src/environmentApi.ts
@@ -23,16 +23,23 @@ export function createEnvironmentApi(rpcClient: WsRpcClient): EnvironmentApi {
     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,
     },
diff --git a/apps/web/src/environmentGrouping.test.ts b/apps/web/src/environmentGrouping.test.ts
index 9ae26fe8b46..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";
 
@@ -48,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: [],
diff --git a/apps/web/src/environments/primary/auth.ts b/apps/web/src/environments/primary/auth.ts
index 42eaa821cf9..93fcdd5fcbb 100644
--- a/apps/web/src/environments/primary/auth.ts
+++ b/apps/web/src/environments/primary/auth.ts
@@ -110,6 +110,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 };
@@ -123,7 +157,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,
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 57f23241456..64ff7a1c3ca 100644
--- a/apps/web/src/environments/runtime/connection.test.ts
+++ b/apps/web/src/environments/runtime/connection.test.ts
@@ -85,16 +85,7 @@ function createTestClient() {
       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),
     },
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.threadSubscriptions.test.ts b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
index 5f169adc9b4..ea96d6c3219 100644
--- a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
+++ b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
@@ -2,6 +2,7 @@ import { QueryClient } from "@tanstack/react-query";
 import {
   EnvironmentId,
   ProjectId,
+  ProviderInstanceId,
   ThreadId,
   TurnId,
   type OrchestrationShellSnapshot,
@@ -14,31 +15,36 @@ 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: 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"),
-  })),
+  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: vi.fn(),
+  getSavedEnvironmentRecord: mockGetSavedEnvironmentRecord,
   hasSavedEnvironmentRegistryHydrated: vi.fn(() => true),
   listSavedEnvironmentRecords: mockListSavedEnvironmentRecords,
   persistSavedEnvironmentRecord: vi.fn(),
-  readSavedEnvironmentBearerToken: vi.fn(),
+  readSavedEnvironmentBearerToken: mockReadSavedEnvironmentBearerToken,
   removeSavedEnvironmentBearerToken: vi.fn(),
   useSavedEnvironmentRegistryStore: {
     subscribe: mockSavedEnvironmentRegistrySubscribe,
@@ -46,6 +52,7 @@ vi.mock("./catalog", () => ({
       upsert: vi.fn(),
       remove: vi.fn(),
       markConnected: vi.fn(),
+      rename: vi.fn(),
     }),
   },
   useSavedEnvironmentRuntimeStore: {
@@ -98,7 +105,7 @@ function makeThreadShellSnapshot(params: {
         projectId,
         title: "Thread",
         modelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         runtimeMode: "full-access",
@@ -144,31 +151,72 @@ describe("retainThreadDetailSubscription", () => {
     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 },
+          },
+        })),
+      },
       orchestration: {
         subscribeThread: mockSubscribeThread,
       },
     });
-    mockCreateEnvironmentConnection.mockImplementation((input) => ({
-      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),
-    }));
-    mockSavedEnvironmentRegistrySubscribe.mockReturnValue(() => undefined);
+    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();
   });
 
@@ -203,6 +251,31 @@ describe("retainThreadDetailSubscription", () => {
     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,
@@ -252,6 +325,95 @@ describe("retainThreadDetailSubscription", () => {
     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);
+
+    await reconnectSavedEnvironment(environmentId);
+    await vi.waitFor(() => {
+      expect(mockCreateEnvironmentConnection).toHaveBeenCalledTimes(3);
+      expect(mockSubscribeThread).toHaveBeenCalledTimes(2);
+    });
+
+    release();
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("reconnects 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),
+    });
+
+    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,
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 9dae1b15856..ca051ff392c 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -1,5 +1,7 @@
 import {
   type AuthSessionRole,
+  type DesktopSshEnvironmentBootstrap,
+  type DesktopSshEnvironmentTarget,
   type EnvironmentId,
   type OrchestrationEvent,
   type OrchestrationShellSnapshot,
@@ -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,
@@ -59,8 +63,11 @@ import {
 } 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,
@@ -85,6 +92,28 @@ type ThreadDetailSubscriptionEntry = {
 };
 
 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<
@@ -97,6 +126,8 @@ const lastAppliedProjectionVersionByEnvironment = new Map<
 
 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.
@@ -107,7 +138,9 @@ let needsProviderInvalidation = false;
 // - 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 NOOP = () => undefined;
+const SSH_HTTP_STATUS_RE = /^\[ssh_http:(\d+)\]\s/u;
 
 function compareAppliedProjectionVersion(
   left: { readonly sequence: number; readonly updatedAt: string | null },
@@ -327,6 +360,25 @@ function disposeThreadDetailSubscriptionsForEnvironment(environmentId: Environme
   }
 }
 
+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>,
@@ -491,6 +543,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",
@@ -797,40 +1070,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,
+              ),
+            ),
+          );
         },
       },
     ),
@@ -838,18 +1151,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, {
@@ -858,6 +1178,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 {
@@ -866,6 +1189,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;
 }
@@ -876,10 +1200,10 @@ async function removeConnection(environmentId: EnvironmentId): Promise<boolean>
     return false;
   }
 
-  disposeThreadDetailSubscriptionsForEnvironment(environmentId);
   lastAppliedProjectionVersionByEnvironment.delete(environmentId);
   environmentConnections.delete(environmentId);
   emitEnvironmentConnectionRegistryChange();
+  detachThreadDetailSubscriptionsForEnvironment(environmentId);
   await connection.dispose();
   return true;
 }
@@ -905,6 +1229,10 @@ function createPrimaryEnvironmentConnection(): EnvironmentConnection {
   );
 }
 
+function maybeCreatePrimaryEnvironmentConnection(): EnvironmentConnection | null {
+  return getPrimaryKnownEnvironment()?.environmentId ? createPrimaryEnvironmentConnection() : null;
+}
+
 async function ensureSavedEnvironmentConnection(
   record: SavedEnvironmentRecord,
   options?: {
@@ -919,69 +1247,144 @@ 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 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) => {
+          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 {
+          await refreshSavedEnvironmentMetadata(
+            activeRecord.environmentId,
+            activeBearerToken,
+            client,
+            roleHint,
+            options?.serverConfig ?? null,
+          );
+        } 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(
@@ -1006,6 +1409,55 @@ function stopActiveService() {
   activeService = null;
 }
 
+function reconnectEnvironmentConnectionsAfterBrowserResume(reason: string): void {
+  const now = Date.now();
+  if (now - lastBrowserResumeReconnectAt < BROWSER_RESUME_RECONNECT_COOLDOWN_MS) {
+    return;
+  }
+  lastBrowserResumeReconnectAt = now;
+
+  for (const connection of environmentConnections.values()) {
+    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 () => {
@@ -1036,13 +1488,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> {
@@ -1053,23 +1515,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: {
@@ -1077,33 +1573,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);
@@ -1112,26 +1618,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> {
@@ -1170,7 +1700,7 @@ export function startEnvironmentConnectionService(queryClient: QueryClient): ()
     },
   );
 
-  createPrimaryEnvironmentConnection();
+  maybeCreatePrimaryEnvironmentConnection();
 
   const unsubscribeSavedEnvironments = useSavedEnvironmentRegistryStore.subscribe(() => {
     if (!hasSavedEnvironmentRegistryHydrated()) {
@@ -1183,12 +1713,15 @@ export function startEnvironmentConnectionService(queryClient: QueryClient): ()
     .then(() => syncSavedEnvironmentConnections(listSavedEnvironmentRecords()))
     .catch(() => undefined);
 
+  const unsubscribeBrowserResumeReconnects = subscribeBrowserResumeReconnects();
+
   activeService = {
     queryClient,
     queryInvalidationThrottler,
     refCount: 1,
     stop: () => {
       unsubscribeSavedEnvironments();
+      unsubscribeBrowserResumeReconnects();
       queryInvalidationThrottler.cancel();
     },
   };
@@ -1206,7 +1739,10 @@ 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);
   }
diff --git a/apps/web/src/gitTextGeneration.ts b/apps/web/src/gitTextGeneration.ts
deleted file mode 100644
index 1130985c90f..00000000000
--- a/apps/web/src/gitTextGeneration.ts
+++ /dev/null
@@ -1,84 +0,0 @@
-import {
-  DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER,
-  type ProviderKind,
-} from "@t3tools/contracts";
-import { normalizeModelSlug } from "@t3tools/shared/model";
-
-import type { AppSettings } from "./appSettings";
-import type { ProviderCustomModelSettings } from "./customModels";
-import { getCustomModelsByProvider, resolveAppModelSelection } from "./customModels";
-
-const PROVIDER_KINDS = [
-  "codex",
-  "copilot",
-  "claudeAgent",
-  "cursor",
-  "opencode",
-  "geminiCli",
-  "amp",
-  "kilo",
-] as const satisfies readonly ProviderKind[];
-
-export function getGitTextGenerationModelOverride(
-  settings: Pick<AppSettings, "gitTextGenerationModelByProvider">,
-  provider: ProviderKind,
-): string | null {
-  return normalizeModelSlug(settings.gitTextGenerationModelByProvider[provider], provider);
-}
-
-export function patchGitTextGenerationModelOverrides(
-  overrides: AppSettings["gitTextGenerationModelByProvider"],
-  provider: ProviderKind,
-  model: string | null | undefined,
-): Pick<AppSettings, "gitTextGenerationModelByProvider"> {
-  const normalized = normalizeModelSlug(model, provider);
-  const nextOverrides = { ...overrides };
-  if (normalized) {
-    nextOverrides[provider] = normalized;
-  } else {
-    delete nextOverrides[provider];
-  }
-  return { gitTextGenerationModelByProvider: nextOverrides };
-}
-
-export function resolveGitTextGenerationModelSelection(
-  provider: ProviderKind,
-  settings: Pick<
-    AppSettings,
-    keyof ProviderCustomModelSettings | "gitTextGenerationModelByProvider"
-  >,
-  activeModel: string | null | undefined,
-): string {
-  const customModelsByProvider = getCustomModelsByProvider(settings);
-  const overrideModel = getGitTextGenerationModelOverride(settings, provider);
-  if (overrideModel) {
-    return resolveAppModelSelection(provider, customModelsByProvider, overrideModel);
-  }
-  const normalizedActiveModel = normalizeModelSlug(activeModel, provider);
-  if (normalizedActiveModel) {
-    return resolveAppModelSelection(provider, customModelsByProvider, normalizedActiveModel);
-  }
-  return resolveAppModelSelection(
-    provider,
-    customModelsByProvider,
-    DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER[provider],
-  );
-}
-
-export function normalizeGitTextGenerationModelByProvider(
-  overrides: Record<string, string>,
-): Record<string, string> {
-  // Migrate legacy "claudeCode" key to current "claudeAgent" before filtering.
-  if ("claudeCode" in overrides && !("claudeAgent" in overrides)) {
-    overrides = { ...overrides, claudeAgent: overrides.claudeCode };
-  }
-  const normalizedOverrides: Partial<Record<ProviderKind, string>> = {};
-  for (const provider of PROVIDER_KINDS) {
-    const normalized = normalizeModelSlug(overrides[provider], provider);
-    if (!normalized) {
-      continue;
-    }
-    normalizedOverrides[provider] = normalized;
-  }
-  return normalizedOverrides;
-}
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 8ab512b397b..3630171bf59 100644
--- a/apps/web/src/hooks/useHandleNewThread.ts
+++ b/apps/web/src/hooks/useHandleNewThread.ts
@@ -1,10 +1,5 @@
 import { scopedProjectKey, scopeProjectRef } from "@t3tools/client-runtime";
-import {
-  DEFAULT_RUNTIME_MODE,
-  type ModelSlug,
-  type ProviderKind,
-  type ScopedProjectRef,
-} from "@t3tools/contracts";
+import { DEFAULT_RUNTIME_MODE, type ScopedProjectRef } from "@t3tools/contracts";
 import { useParams, useRouter } from "@tanstack/react-router";
 import { useCallback, useMemo } from "react";
 import { useShallow } from "zustand/react/shallow";
@@ -41,8 +36,6 @@ function useNewThreadState() {
         branch?: string | null;
         worktreePath?: string | null;
         envMode?: DraftThreadEnvMode;
-        provider?: ProviderKind | null;
-        model?: ModelSlug | null;
       },
     ): Promise<void> => {
       const {
@@ -51,7 +44,6 @@ function useNewThreadState() {
         getDraftThread,
         applyStickyState,
         setDraftThreadContext,
-        setModelSelection,
         setLogicalProjectDraftThreadId,
       } = useComposerDraftStore.getState();
       const currentRouteTarget = getCurrentRouteTarget();
@@ -81,12 +73,6 @@ function useNewThreadState() {
               ...(hasEnvModeOption ? { envMode: options?.envMode } : {}),
             });
           }
-          if (options?.provider != null && options?.model != null) {
-            setModelSelection(storedDraftThread.draftId, {
-              provider: options.provider,
-              model: options.model,
-            });
-          }
           setLogicalProjectDraftThreadId(logicalProjectKey, projectRef, storedDraftThread.draftId, {
             threadId: storedDraftThread.threadId,
           });
@@ -116,12 +102,6 @@ function useNewThreadState() {
             ...(hasEnvModeOption ? { envMode: options?.envMode } : {}),
           });
         }
-        if (options?.provider != null && options?.model != null) {
-          setModelSelection(currentRouteTarget.draftId, {
-            provider: options.provider,
-            model: options.model,
-          });
-        }
         setLogicalProjectDraftThreadId(logicalProjectKey, projectRef, currentRouteTarget.draftId, {
           threadId: latestActiveDraftThread.threadId,
           createdAt: latestActiveDraftThread.createdAt,
@@ -148,12 +128,6 @@ function useNewThreadState() {
         });
         applyStickyState(draftId);
 
-        if (options?.provider != null && options?.model != null) {
-          setModelSelection(draftId, {
-            provider: options.provider,
-            model: options.model,
-          });
-        }
         await router.navigate({
           to: "/draft/$draftId",
           params: { draftId },
diff --git a/apps/web/src/hooks/useSettings.ts b/apps/web/src/hooks/useSettings.ts
index 96f394038d2..1e28a3ea5c3 100644
--- a/apps/web/src/hooks/useSettings.ts
+++ b/apps/web/src/hooks/useSettings.ts
@@ -26,7 +26,8 @@ import { ModelSelection } from "@t3tools/contracts";
 import { ensureLocalApi } from "~/localApi";
 import { Predicate, Schema, Struct } from "effect";
 import type { DeepMutable } from "effect/Types";
-import { normalizeCustomModelSlugs } from "~/customModels";
+import { normalizeCustomModelSlugs } from "~/modelSelection";
+import { ProviderDriverKind } from "@t3tools/contracts";
 import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
 import { applySettingsUpdated, getServerConfig, useServerSettings } from "~/rpc/serverState";
 
@@ -239,10 +240,10 @@ export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<s
     const sel = legacySettings.textGenerationModelSelection;
     const selPatch: NonNullable<DeepMutable<ServerSettingsPatch>["textGenerationModelSelection"]> =
       {
-        provider: sel.provider,
+        instanceId: sel.instanceId,
         model: sel.model,
-        ...("options" in sel && sel.options != null ? { options: sel.options } : {}),
-      } as NonNullable<DeepMutable<ServerSettingsPatch>["textGenerationModelSelection"]>;
+        ...(sel.options != null ? { options: [...sel.options] } : {}),
+      };
     patch.textGenerationModelSelection = selPatch;
   }
 
@@ -263,7 +264,8 @@ export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<s
     patch.providers.codex ??= {};
     patch.providers.codex.customModels = normalizeCustomModelSlugs(
       legacySettings.customCodexModels,
-      "codex",
+      new Set(),
+      ProviderDriverKind.make("codex"),
     );
   }
 
@@ -278,7 +280,8 @@ export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<s
     patch.providers.claudeAgent ??= {};
     patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
       legacySettings.customClaudeModels,
-      "claudeAgent",
+      new Set(),
+      ProviderDriverKind.make("claudeAgent"),
     );
   }
 
@@ -299,7 +302,8 @@ export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<s
     patch.providers.copilot ??= {};
     patch.providers.copilot.customModels = normalizeCustomModelSlugs(
       legacySettings.customCopilotModels,
-      "copilot",
+      new Set(),
+      ProviderDriverKind.make("copilot"),
     );
   }
 
diff --git a/apps/web/src/hooks/useThreadActions.ts b/apps/web/src/hooks/useThreadActions.ts
index de60ffb18dc..46a1955cc49 100644
--- a/apps/web/src/hooks/useThreadActions.ts
+++ b/apps/web/src/hooks/useThreadActions.ts
@@ -209,7 +209,7 @@ export function useThreadActions() {
       }
 
       try {
-        await ensureEnvironmentApi(threadRef.environmentId).git.removeWorktree({
+        await ensureEnvironmentApi(threadRef.environmentId).vcs.removeWorktree({
           cwd: threadProject.cwd,
           path: orphanedWorktreePath,
           force: true,
diff --git a/apps/web/src/hostedPairing.test.ts b/apps/web/src/hostedPairing.test.ts
new file mode 100644
index 00000000000..ef2b2eb5279
--- /dev/null
+++ b/apps/web/src/hostedPairing.test.ts
@@ -0,0 +1,66 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  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("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);
+  });
+});
diff --git a/apps/web/src/hostedPairing.ts b/apps/web/src/hostedPairing.ts
new file mode 100644
index 00000000000..a44cfa70834
--- /dev/null
+++ b/apps/web/src/hostedPairing.ts
@@ -0,0 +1,70 @@
+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;
+}
+
+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 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;
+  }
+
+  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();
+}
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 8c89d2d5397..5d7fee5b171 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -61,6 +61,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 *,
@@ -150,19 +166,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 {
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 2e17cd15521..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),
     },
@@ -155,7 +157,7 @@ function createRegisteredGitStatusClient(environmentId: EnvironmentId) {
 
   return {
     client,
-    emit: (event: GitStatusResult) => {
+    emit: (event: VcsStatusResult) => {
       for (const listener of listeners) {
         listener(event);
       }
@@ -219,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,
@@ -231,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),
       ),
     };
@@ -254,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();
@@ -292,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) {
@@ -307,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..4304dcc4aab 100644
--- a/apps/web/src/lib/gitStatusState.ts
+++ b/apps/web/src/lib/gitStatusState.ts
@@ -2,7 +2,7 @@ import { useAtomValue } from "@effect/atom-react";
 import {
   type EnvironmentId,
   type GitManagerServiceError,
-  type GitStatusResult,
+  type VcsStatusResult,
 } from "@t3tools/contracts";
 import { Cause } from "effect";
 import { Atom } from "effect/unstable/reactivity";
@@ -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/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..663d618b92e 100644
--- a/apps/web/src/lib/providerReactQuery.ts
+++ b/apps/web/src/lib/providerReactQuery.ts
@@ -13,6 +13,7 @@ interface CheckpointDiffQueryInput {
   threadId: ThreadId | null;
   fromTurnCount: number | null;
   toTurnCount: number | null;
+  ignoreWhitespace: boolean;
   cacheScope?: string | null;
   enabled?: boolean;
 }
@@ -27,6 +28,7 @@ export const providerQueryKeys = {
       input.threadId,
       input.fromTurnCount,
       input.toTurnCount,
+      input.ignoreWhitespace,
       input.cacheScope ?? null,
     ] as const,
 };
@@ -36,6 +38,7 @@ function decodeCheckpointDiffRequest(input: CheckpointDiffQueryInput) {
     return Schema.decodeUnknownOption(OrchestrationGetFullThreadDiffInput)({
       threadId: input.threadId,
       toTurnCount: input.toTurnCount,
+      ignoreWhitespace: input.ignoreWhitespace,
     }).pipe(Option.map((fields) => ({ kind: "fullThreadDiff" as const, input: fields })));
   }
 
@@ -43,6 +46,7 @@ function decodeCheckpointDiffRequest(input: CheckpointDiffQueryInput) {
     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..911517fb4e5
--- /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 { Effect } from "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/threadDraftDefaults.test.ts b/apps/web/src/lib/threadDraftDefaults.test.ts
deleted file mode 100644
index 091a947edf8..00000000000
--- a/apps/web/src/lib/threadDraftDefaults.test.ts
+++ /dev/null
@@ -1,135 +0,0 @@
-import { EnvironmentId, ProjectId, ThreadId, type TurnId } from "@t3tools/contracts";
-import { describe, expect, it } from "vitest";
-import { resolveDraftThreadDefaults } from "./threadDraftDefaults";
-import { DEFAULT_INTERACTION_MODE, DEFAULT_RUNTIME_MODE, type Thread } from "../types";
-
-function makeThread(overrides: Partial<Thread> = {}): Thread {
-  return {
-    id: ThreadId.make("thread-1"),
-    environmentId: EnvironmentId.make("environment-local"),
-    codexThreadId: null,
-    projectId: ProjectId.make("project-1"),
-    title: "Thread",
-    modelSelection: { provider: "codex", model: "gpt-5.4" },
-    runtimeMode: DEFAULT_RUNTIME_MODE,
-    interactionMode: DEFAULT_INTERACTION_MODE,
-    session: null,
-    messages: [],
-    proposedPlans: [],
-    error: null,
-    createdAt: "2026-03-01T00:00:00.000Z",
-    archivedAt: null,
-    updatedAt: "2026-03-01T00:00:00.000Z",
-    latestTurn: null,
-    branch: null,
-    worktreePath: null,
-    turnDiffSummaries: [],
-    activities: [],
-    ...overrides,
-  };
-}
-
-function completedTurn(completedAt: string) {
-  return {
-    turnId: "turn-1" as TurnId,
-    state: "completed" as const,
-    requestedAt: completedAt,
-    startedAt: completedAt,
-    completedAt,
-    assistantMessageId: null,
-  };
-}
-
-describe("resolveDraftThreadDefaults", () => {
-  it("prefers the most recent thread from the active project", () => {
-    const defaults = resolveDraftThreadDefaults({
-      threads: [
-        makeThread({
-          id: ThreadId.make("thread-project"),
-          projectId: ProjectId.make("project-1"),
-          modelSelection: { provider: "cursor", model: "composer-1.5" },
-          createdAt: "2026-03-08T10:00:00.000Z",
-        }),
-        makeThread({
-          id: ThreadId.make("thread-other-project"),
-          projectId: ProjectId.make("project-2"),
-          modelSelection: { provider: "claudeAgent", model: "claude-sonnet-4-6" },
-          createdAt: "2026-03-09T10:00:00.000Z",
-        }),
-      ],
-      projectId: ProjectId.make("project-1"),
-      fallbackModel: "gpt-5.4",
-    });
-
-    expect(defaults).toEqual({
-      provider: "cursor",
-      model: "composer-1.5",
-    });
-  });
-
-  it("falls back to the most recent thread overall when the project has no history", () => {
-    const defaults = resolveDraftThreadDefaults({
-      threads: [
-        makeThread({
-          id: ThreadId.make("thread-older"),
-          modelSelection: { provider: "codex", model: "gpt-5.4" },
-          createdAt: "2026-03-08T10:00:00.000Z",
-          updatedAt: "2026-03-08T10:00:00.000Z",
-        }),
-        makeThread({
-          id: ThreadId.make("thread-newest"),
-          projectId: ProjectId.make("project-2"),
-          modelSelection: { provider: "claudeAgent", model: "claude-sonnet-4-6" },
-          createdAt: "2026-03-09T10:00:00.000Z",
-          updatedAt: "2026-03-09T10:00:00.000Z",
-        }),
-      ],
-      projectId: ProjectId.make("project-3"),
-      fallbackModel: "gpt-5.4",
-    });
-
-    expect(defaults).toEqual({
-      provider: "claudeAgent",
-      model: "claude-sonnet-4-6",
-    });
-  });
-
-  it("uses the most recently visited conversation instead of the newest created thread", () => {
-    const defaults = resolveDraftThreadDefaults({
-      threads: [
-        makeThread({
-          id: ThreadId.make("thread-revisited"),
-          modelSelection: { provider: "cursor", model: "composer-1.5" },
-          createdAt: "2026-03-01T10:00:00.000Z",
-          updatedAt: "2026-03-09T11:00:00.000Z",
-          latestTurn: completedTurn("2026-03-09T10:59:00.000Z"),
-        }),
-        makeThread({
-          id: ThreadId.make("thread-newer"),
-          modelSelection: { provider: "claudeAgent", model: "claude-sonnet-4-6" },
-          createdAt: "2026-03-08T10:00:00.000Z",
-        }),
-      ],
-      projectId: ProjectId.make("project-1"),
-      fallbackModel: "gpt-5.4",
-    });
-
-    expect(defaults).toEqual({
-      provider: "cursor",
-      model: "composer-1.5",
-    });
-  });
-
-  it("falls back to the supplied model when there is no previous conversation", () => {
-    const defaults = resolveDraftThreadDefaults({
-      threads: [],
-      projectId: ProjectId.make("project-1"),
-      fallbackModel: "claude-sonnet-4-6",
-    });
-
-    expect(defaults).toEqual({
-      provider: "claudeAgent",
-      model: "claude-sonnet-4-6",
-    });
-  });
-});
diff --git a/apps/web/src/lib/threadDraftDefaults.ts b/apps/web/src/lib/threadDraftDefaults.ts
deleted file mode 100644
index f385ee9089c..00000000000
--- a/apps/web/src/lib/threadDraftDefaults.ts
+++ /dev/null
@@ -1,64 +0,0 @@
-import { type ProjectId, type ProviderKind } from "@t3tools/contracts";
-import { resolveModelSlugForProvider } from "@t3tools/shared/model";
-import type { Thread } from "../types";
-import { inferProviderForThreadModel } from "./threadProvider";
-
-export interface DraftThreadDefaults {
-  readonly provider: ProviderKind;
-  readonly model: string;
-}
-
-function timestampOrNaN(value: string | null | undefined): number {
-  if (!value) return Number.NaN;
-  return Date.parse(value);
-}
-
-function threadRecencyTimestamp(
-  thread: Pick<Thread, "createdAt" | "updatedAt" | "latestTurn">,
-): number {
-  return (
-    [thread.updatedAt, thread.latestTurn?.completedAt, thread.createdAt]
-      .map((value) => timestampOrNaN(value))
-      .find((value) => Number.isFinite(value)) ?? 0
-  );
-}
-
-function compareThreadsByRecency(left: Thread, right: Thread): number {
-  const byRecency = threadRecencyTimestamp(right) - threadRecencyTimestamp(left);
-  if (byRecency !== 0) return byRecency;
-  return right.id.localeCompare(left.id);
-}
-
-function latestThread(threads: ReadonlyArray<Thread>, projectId?: ProjectId | null): Thread | null {
-  const matchingThreads =
-    projectId === undefined || projectId === null
-      ? threads
-      : threads.filter((thread) => thread.projectId === projectId);
-  return matchingThreads.toSorted(compareThreadsByRecency)[0] ?? null;
-}
-
-export function resolveDraftThreadDefaults(input: {
-  readonly threads: ReadonlyArray<Thread>;
-  readonly projectId: ProjectId | null | undefined;
-  readonly fallbackModel: string;
-}): DraftThreadDefaults {
-  const recentThread =
-    latestThread(input.threads, input.projectId) ?? latestThread(input.threads) ?? null;
-  if (!recentThread) {
-    const fallbackProvider = inferProviderForThreadModel({
-      model: input.fallbackModel,
-      sessionProviderName: null,
-    });
-    return {
-      provider: fallbackProvider,
-      model: resolveModelSlugForProvider(fallbackProvider, input.fallbackModel),
-    };
-  }
-
-  const provider = recentThread.modelSelection.provider;
-
-  return {
-    provider,
-    model: resolveModelSlugForProvider(provider, recentThread.modelSelection.model),
-  };
-}
diff --git a/apps/web/src/lib/threadProvider.test.ts b/apps/web/src/lib/threadProvider.test.ts
deleted file mode 100644
index 24266d80c23..00000000000
--- a/apps/web/src/lib/threadProvider.test.ts
+++ /dev/null
@@ -1,42 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { inferProviderForThreadModel, resolveThreadProvider } from "./threadProvider";
-
-describe("inferProviderForThreadModel", () => {
-  it("prefers the active session provider when present", () => {
-    expect(
-      inferProviderForThreadModel({
-        model: "gpt-5.3-codex",
-        sessionProviderName: "claudeAgent",
-      }),
-    ).toBe("claudeAgent");
-  });
-
-  it("infers cursor threads from composer models", () => {
-    expect(
-      inferProviderForThreadModel({
-        model: "composer-1.5",
-        sessionProviderName: null,
-      }),
-    ).toBe("cursor");
-  });
-
-  it("infers opencode threads from slash-delimited models", () => {
-    expect(
-      inferProviderForThreadModel({
-        model: "openai/gpt-5.1",
-        sessionProviderName: null,
-      }),
-    ).toBe("opencode");
-  });
-});
-
-describe("resolveThreadProvider", () => {
-  it("falls back to the thread model when the session is closed", () => {
-    expect(
-      resolveThreadProvider({
-        modelSelection: { provider: "cursor", model: "composer" },
-        session: null,
-      }),
-    ).toBe("cursor");
-  });
-});
diff --git a/apps/web/src/lib/threadProvider.ts b/apps/web/src/lib/threadProvider.ts
deleted file mode 100644
index 6497b432c3d..00000000000
--- a/apps/web/src/lib/threadProvider.ts
+++ /dev/null
@@ -1,132 +0,0 @@
-import { type ProviderKind } from "@t3tools/contracts";
-import { getModelOptions, normalizeModelSlug } from "@t3tools/shared/model";
-import type { Thread } from "../types";
-
-const PROVIDER_KINDS = [
-  "codex",
-  "copilot",
-  "claudeAgent",
-  "cursor",
-  "opencode",
-  "geminiCli",
-  "amp",
-  "kilo",
-] as const satisfies ReadonlyArray<ProviderKind>;
-
-const PROVIDER_KIND_SET = new Set<ProviderKind>(PROVIDER_KINDS);
-
-const CODEX_MODEL_SLUGS = new Set<string>(getModelOptions("codex").map((option) => option.slug));
-const COPILOT_MODEL_SLUGS = new Set<string>(
-  getModelOptions("copilot").map((option) => option.slug),
-);
-const CLAUDE_MODEL_SLUGS = new Set<string>(
-  getModelOptions("claudeAgent").map((option) => option.slug),
-);
-const CURSOR_MODEL_SLUGS = new Set<string>(getModelOptions("cursor").map((option) => option.slug));
-const OPENCODE_MODEL_SLUGS = new Set<string>(
-  getModelOptions("opencode").map((option) => option.slug),
-);
-const GEMINI_CLI_MODEL_SLUGS = new Set<string>(
-  getModelOptions("geminiCli").map((option) => option.slug),
-);
-const AMP_MODEL_SLUGS = new Set<string>(getModelOptions("amp").map((option) => option.slug));
-const KILO_MODEL_SLUGS = new Set<string>(getModelOptions("kilo").map((option) => option.slug));
-const CURSOR_DISTINCT_MODEL_SLUGS = new Set(
-  [...CURSOR_MODEL_SLUGS].filter(
-    (slug) =>
-      !CODEX_MODEL_SLUGS.has(slug) &&
-      !COPILOT_MODEL_SLUGS.has(slug) &&
-      !CLAUDE_MODEL_SLUGS.has(slug) &&
-      !OPENCODE_MODEL_SLUGS.has(slug),
-  ),
-);
-const AMP_DISTINCT_MODEL_SLUGS = new Set(
-  [...AMP_MODEL_SLUGS].filter(
-    (slug) =>
-      !CODEX_MODEL_SLUGS.has(slug) &&
-      !COPILOT_MODEL_SLUGS.has(slug) &&
-      !CLAUDE_MODEL_SLUGS.has(slug) &&
-      !CURSOR_MODEL_SLUGS.has(slug) &&
-      !OPENCODE_MODEL_SLUGS.has(slug) &&
-      !GEMINI_CLI_MODEL_SLUGS.has(slug) &&
-      !KILO_MODEL_SLUGS.has(slug),
-  ),
-);
-
-export function toProviderKind(providerName: string | null | undefined): ProviderKind | null {
-  if (!providerName) return null;
-  // Normalize legacy provider name
-  if (providerName === "claudeCode") return "claudeAgent";
-  return PROVIDER_KIND_SET.has(providerName as ProviderKind)
-    ? (providerName as ProviderKind)
-    : null;
-}
-
-export function inferProviderForThreadModel(input: {
-  readonly model: string;
-  readonly sessionProviderName: string | null;
-}): ProviderKind {
-  const sessionProvider = toProviderKind(input.sessionProviderName);
-  if (sessionProvider) {
-    return sessionProvider;
-  }
-
-  const normalizedCopilot = normalizeModelSlug(input.model, "copilot");
-  if (normalizedCopilot && COPILOT_MODEL_SLUGS.has(normalizedCopilot)) {
-    return "copilot";
-  }
-
-  const normalizedGeminiCli = normalizeModelSlug(input.model, "geminiCli");
-  if (normalizedGeminiCli && GEMINI_CLI_MODEL_SLUGS.has(normalizedGeminiCli)) {
-    return "geminiCli";
-  }
-
-  const normalizedAmp = normalizeModelSlug(input.model, "amp");
-  if (normalizedAmp && AMP_DISTINCT_MODEL_SLUGS.has(normalizedAmp)) {
-    return "amp";
-  }
-
-  const normalizedCursor = normalizeModelSlug(input.model, "cursor");
-  if (normalizedCursor && CURSOR_DISTINCT_MODEL_SLUGS.has(normalizedCursor)) {
-    return "cursor";
-  }
-
-  const normalizedClaude = normalizeModelSlug(input.model, "claudeAgent");
-  if (normalizedClaude && CLAUDE_MODEL_SLUGS.has(normalizedClaude)) {
-    return "claudeAgent";
-  }
-
-  const normalizedCodex = normalizeModelSlug(input.model, "codex");
-  if (normalizedCodex && CODEX_MODEL_SLUGS.has(normalizedCodex)) {
-    return "codex";
-  }
-
-  const normalizedOpencode = normalizeModelSlug(input.model, "opencode");
-  if (normalizedOpencode && OPENCODE_MODEL_SLUGS.has(normalizedOpencode)) {
-    return "opencode";
-  }
-
-  const normalizedKilo = normalizeModelSlug(input.model, "kilo");
-  if (normalizedKilo && KILO_MODEL_SLUGS.has(normalizedKilo)) {
-    return "kilo";
-  }
-
-  if (input.model.includes("/")) {
-    return "opencode";
-  }
-
-  if (input.model.trim().startsWith("composer-") || input.model.trim().endsWith("-thinking")) {
-    return "cursor";
-  }
-
-  return input.model.trim().startsWith("claude-") ? "claudeAgent" : "codex";
-}
-
-export function resolveThreadProvider(
-  thread: Pick<Thread, "modelSelection" | "session">,
-): ProviderKind {
-  return inferProviderForThreadModel({
-    model: thread.modelSelection.model,
-    sessionProviderName: thread.session?.provider ?? thread.modelSelection.provider ?? null,
-  });
-}
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/localApi.test.ts b/apps/web/src/localApi.test.ts
index 4918728afd1..a30854257f4 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -3,9 +3,11 @@ import {
   DEFAULT_SERVER_SETTINGS,
   type DesktopBridge,
   EnvironmentId,
-  type GitStatusResult,
+  type VcsStatusResult,
   ProjectId,
   type OrchestrationShellStreamItem,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerConfig,
   type ServerProvider,
   type TerminalEvent,
@@ -32,7 +34,7 @@ function registerListener<T>(listeners: Set<(event: T) => void>, listener: (even
 
 const terminalEventListeners = new Set<(event: TerminalEvent) => void>();
 const shellStreamListeners = new Set<(event: OrchestrationShellStreamItem) => void>();
-const gitStatusListeners = new Set<(event: GitStatusResult) => void>();
+const gitStatusListeners = new Set<(event: VcsStatusResult) => void>();
 
 const rpcClientMock = {
   dispose: vi.fn(),
@@ -54,22 +56,29 @@ const rpcClientMock = {
   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(),
   },
@@ -169,16 +178,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,
@@ -211,7 +251,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",
@@ -260,11 +301,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,
@@ -332,7 +373,7 @@ describe("wsApi", () => {
         title: "Project",
         workspaceRoot: "/tmp/workspace",
         defaultModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5-codex",
         },
         scripts: [],
@@ -352,24 +393,24 @@ 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 shell stream subscription options to the RPC client", async () => {
@@ -398,7 +439,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",
@@ -536,8 +577,10 @@ describe("wsApi", () => {
       autoOpenPlanSidebar: false,
       confirmThreadArchive: true,
       confirmThreadDelete: false,
+      diffIgnoreWhitespace: true,
       diffWordWrap: true,
       favorites: [],
+      providerModelPreferences: {},
       sidebarProjectGroupingMode: "repository_path" as const,
       sidebarProjectGroupingOverrides: {
         "environment-local:/tmp/project": "separate" as const,
@@ -595,8 +638,10 @@ describe("wsApi", () => {
       autoOpenPlanSidebar: false,
       confirmThreadArchive: true,
       confirmThreadDelete: false,
+      diffIgnoreWhitespace: true,
       diffWordWrap: true,
       favorites: [],
+      providerModelPreferences: {},
       sidebarProjectGroupingMode: "repository_path" as const,
       sidebarProjectGroupingOverrides: {
         "environment-local:/tmp/project": "separate" as const,
diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index 4401b5b778e..c9120e53bb8 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,7 +28,11 @@ 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 (options) => {
@@ -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,34 @@ 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()),
+      upsertKeybinding: (input) =>
+        rpcClient
+          ? rpcClient.server.upsertKeybinding(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()),
     },
   };
 }
 
+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 +156,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 +177,7 @@ export async function __resetLocalApiForTests() {
   __resetClientSettingsPersistenceForTests();
   await resetEnvironmentServiceForTests();
   resetGitStatusStateForTests();
+  resetSourceControlDiscoveryStateForTests();
   resetRequestLatencyStateForTests();
   resetSavedEnvironmentRegistryStoreForTests();
   resetSavedEnvironmentRuntimeStoreForTests();
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/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 088abfbc591..8ba0c8fa5d9 100644
--- a/apps/web/src/modelSelection.ts
+++ b/apps/web/src/modelSelection.ts
@@ -1,114 +1,325 @@
 import {
+  DEFAULT_GIT_TEXT_GENERATION_MODEL,
   DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER,
+  defaultInstanceIdForDriver,
   type ModelSelection,
-  type ProviderKind,
-  type ProviderModelOptions,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ServerProvider,
 } from "@t3tools/contracts";
-import type { UnifiedSettings } from "@t3tools/contracts/settings";
-import { createModelSelection, resolveSelectableModel } from "@t3tools/shared/model";
-
-import { getComposerProviderState } from "./components/chat/composerProviderRegistry";
-import { getAppModelOptions, MAX_CUSTOM_MODEL_LENGTH } from "./customModels";
+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");
+
+/**
+ * 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;
+}
+
+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: [],
+    }
+  );
+}
+
+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: ProviderDriverKind = ProviderDriverKind.make("codex"),
+): string[] {
+  const normalizedModels: string[] = [];
+  const seen = new Set<string>();
+
+  for (const candidate of models) {
+    const normalized = normalizeModelSlug(candidate, provider);
+    if (
+      !normalized ||
+      normalized.length > MAX_CUSTOM_MODEL_LENGTH ||
+      builtInModelSlugs.has(normalized) ||
+      seen.has(normalized)
+    ) {
+      continue;
+    }
+
+    seen.add(normalized);
+    normalizedModels.push(normalized);
+    if (normalizedModels.length >= MAX_CUSTOM_MODEL_COUNT) {
+      break;
+    }
+  }
+
+  return normalizedModels;
+}
+
+export function getAppModelOptions(
+  settings: UnifiedSettings,
+  providers: ReadonlyArray<ServerProvider>,
+  provider: ProviderDriverKind,
+  _selectedModel?: string | null,
+): AppModelOption[] {
+  const options: AppModelOption[] = getProviderModels(providers, provider).map(toAppModelOption);
+  const seen = new Set(options.map((option) => option.slug));
+  const builtInModelSlugs = new Set(
+    getProviderModels(providers, provider)
+      .filter((model) => !model.isCustom)
+      .map((model) => model.slug),
+  );
+
+  // 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;
+    }
 
-export { MAX_CUSTOM_MODEL_LENGTH };
+    seen.add(slug);
+    options.push({
+      slug,
+      name: slug,
+      isCustom: true,
+    });
+  }
 
-export function getCustomModelOptionsByProvider(
+  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,
-  _providers?: ReadonlyArray<ServerProvider>,
-  selectedProvider?: ProviderKind | null,
-  selectedModel?: string | null,
-) {
-  return {
-    codex: getAppModelOptions(
-      "codex",
-      settings.providers.codex.customModels,
-      selectedProvider === "codex" ? selectedModel : undefined,
-    ),
-    copilot: getAppModelOptions(
-      "copilot",
-      settings.providers.copilot.customModels,
-      selectedProvider === "copilot" ? selectedModel : undefined,
-    ),
-    claudeAgent: getAppModelOptions(
-      "claudeAgent",
-      settings.providers.claudeAgent.customModels,
-      selectedProvider === "claudeAgent" ? selectedModel : undefined,
-    ),
-    cursor: getAppModelOptions(
-      "cursor",
-      settings.providers.cursor.customModels,
-      selectedProvider === "cursor" ? selectedModel : undefined,
-    ),
-    opencode: getAppModelOptions(
-      "opencode",
-      settings.providers.opencode.customModels,
-      selectedProvider === "opencode" ? selectedModel : undefined,
-    ),
-    geminiCli: getAppModelOptions(
-      "geminiCli",
-      settings.providers.geminiCli.customModels,
-      selectedProvider === "geminiCli" ? selectedModel : undefined,
-    ),
-    amp: getAppModelOptions(
-      "amp",
-      settings.providers.amp.customModels,
-      selectedProvider === "amp" ? selectedModel : undefined,
-    ),
-    kilo: getAppModelOptions(
-      "kilo",
-      settings.providers.kilo.customModels,
-      selectedProvider === "kilo" ? selectedModel : undefined,
-    ),
-  } as const;
+  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 applyInstanceModelPreferences(
+    options,
+    readInstanceModelPreferences(settings, entry.instanceId),
+  );
 }
 
 export function resolveAppModelSelection(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   settings: UnifiedSettings,
-  _providers: ReadonlyArray<ServerProvider>,
-  model: string | null | undefined,
+  providers: ReadonlyArray<ServerProvider>,
+  selectedModel: string | null | undefined,
 ): string {
-  const modelOptions = getCustomModelOptionsByProvider(settings, _providers, provider, model);
+  const resolvedProvider = resolveSelectableProvider(providers, provider);
+  const options = getAppModelOptions(settings, providers, resolvedProvider, selectedModel);
   return (
-    resolveSelectableModel(provider, model, modelOptions[provider]) ??
-    getDefaultServerModel(_providers, provider)
+    resolveSelectableModel(resolvedProvider, selectedModel, options) ??
+    getDefaultServerModel(providers, resolvedProvider)
   );
 }
 
+export function resolveAppModelSelectionForInstance(
+  instanceId: ProviderInstanceId,
+  settings: UnifiedSettings,
+  providers: ReadonlyArray<ServerProvider>,
+  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(
   settings: UnifiedSettings,
   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 modelOptionsByProvider = getCustomModelOptionsByProvider(settings);
-
-  const model =
-    resolveSelectableModel(
+  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,
-      provider === selection.provider ? selection.model : null,
-      modelOptionsByProvider[provider],
-    ) ?? getDefaultServerModel(providers, provider);
+      model,
+      models: entry.models,
+      prompt: "",
+      modelOptions: selectedEntry ? selection.options : undefined,
+    });
 
-  const providerModelOptions: Partial<ProviderModelOptions> = {
-    [provider]: provider === selection.provider ? 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 = keptSelectedProvider ? selection.model : null;
+  const model = resolveAppModelSelection(provider, settings, providers, selectedModel);
   const { modelOptionsForDispatch } = getComposerProviderState({
     provider,
     model,
     models: getProviderModels(providers, provider),
     prompt: "",
-    modelOptions: providerModelOptions,
+    modelOptions: keptSelectedProvider ? selection.options : undefined,
   });
 
-  return createModelSelection(provider, model, modelOptionsForDispatch);
+  return createModelSelection(defaultInstanceIdForDriver(provider), model, modelOptionsForDispatch);
 }
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/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/providerKind.ts b/apps/web/src/providerKind.ts
new file mode 100644
index 00000000000..fbee7ea7042
--- /dev/null
+++ b/apps/web/src/providerKind.ts
@@ -0,0 +1,33 @@
+/**
+ * Fork-local `ProviderKind` closed string union.
+ *
+ * Upstream's #2277 refactor removed the `ProviderKind` union from
+ * `@t3tools/contracts` in favor of `ProviderDriverKind` (an open branded
+ * slug). The fork still relies on a closed union of the eight provider names
+ * it ships adapters for — used as keys in `Record<ProviderKind, …>` shapes
+ * and as the discriminator in exhaustive `switch` statements throughout the
+ * web app.
+ *
+ * This module preserves that closed union so existing call sites compile
+ * unchanged. New code that needs to interop with the runtime instance
+ * registry should prefer `ProviderDriverKind` from `@t3tools/contracts`.
+ */
+
+export const PROVIDER_KINDS = [
+  "codex",
+  "copilot",
+  "claudeAgent",
+  "cursor",
+  "opencode",
+  "geminiCli",
+  "amp",
+  "kilo",
+] as const;
+
+export type ProviderKind = (typeof PROVIDER_KINDS)[number];
+
+const PROVIDER_KIND_SET: ReadonlySet<string> = new Set<string>(PROVIDER_KINDS);
+
+export function isProviderKind(value: unknown): value is ProviderKind {
+  return typeof value === "string" && PROVIDER_KIND_SET.has(value);
+}
diff --git a/apps/web/src/providerModelOptions.ts b/apps/web/src/providerModelOptions.ts
deleted file mode 100644
index 561654de31b..00000000000
--- a/apps/web/src/providerModelOptions.ts
+++ /dev/null
@@ -1,100 +0,0 @@
-import { type ProviderKind } from "@t3tools/contracts";
-import { resolveCursorPickerModelSlug } from "@t3tools/shared/model";
-
-import { getAppModelOptions } from "./customModels";
-import { getCursorModelFamilyOptions } from "@t3tools/shared/model";
-
-export type ModelOptionEntry = {
-  slug: string;
-  name: string;
-  pricingTier?: string;
-  isCustom?: boolean;
-  connected?: boolean;
-};
-
-export function buildModelOptionsByProvider(settings: {
-  customCodexModels: readonly string[];
-  customCopilotModels: readonly string[];
-  customClaudeModels: readonly string[];
-  customCursorModels: readonly string[];
-  customOpencodeModels: readonly string[];
-  customGeminiCliModels: readonly string[];
-  customAmpModels: readonly string[];
-  customKiloModels: readonly string[];
-}): Record<ProviderKind, ReadonlyArray<ModelOptionEntry>> {
-  const cursorFamilyOptions = getCursorModelFamilyOptions();
-  return {
-    codex: getAppModelOptions("codex", settings.customCodexModels),
-    copilot: getAppModelOptions("copilot", settings.customCopilotModels),
-    claudeAgent: getAppModelOptions("claudeAgent", settings.customClaudeModels),
-    cursor: [
-      ...cursorFamilyOptions,
-      ...getAppModelOptions("cursor", settings.customCursorModels).filter(
-        (option) =>
-          option.isCustom && !cursorFamilyOptions.some((family) => family.slug === option.slug),
-      ),
-    ],
-    opencode: getAppModelOptions("opencode", settings.customOpencodeModels),
-    geminiCli: getAppModelOptions("geminiCli", settings.customGeminiCliModels),
-    amp: getAppModelOptions("amp", settings.customAmpModels),
-    kilo: getAppModelOptions("kilo", settings.customKiloModels),
-  };
-}
-
-export function mergeDiscoveredModels(
-  base: Record<ProviderKind, ReadonlyArray<ModelOptionEntry>>,
-  discovered: Partial<Record<ProviderKind, ReadonlyArray<ModelOptionEntry> | undefined>>,
-): Record<ProviderKind, ReadonlyArray<ModelOptionEntry>> {
-  const result = { ...base };
-  for (const [provider, models] of Object.entries(discovered) as Array<
-    [ProviderKind, ReadonlyArray<ModelOptionEntry> | undefined]
-  >) {
-    if (!models || models.length === 0) continue;
-    const normalizedModels =
-      provider === "cursor"
-        ? models.filter((model) => resolveCursorPickerModelSlug(model.slug) === model.slug)
-        : models;
-    const dedupedModels = Array.from(new Map(normalizedModels.map((m) => [m.slug, m])).values());
-    const existing = new Set(base[provider]?.map((m) => m.slug));
-    if (provider === "copilot") {
-      const baseTiers = new Map((base[provider] ?? []).map((m) => [m.slug, m.pricingTier]));
-      const enriched = dedupedModels.map((m) => {
-        if (m.pricingTier) return m;
-        const tier = baseTiers.get(m.slug);
-        return tier ? { ...m, pricingTier: tier } : m;
-      });
-      const enrichedBySlug = new Map(enriched.map((m) => [m.slug, m]));
-      const merged = (base[provider] ?? []).map((m) => {
-        const discoveredModel = enrichedBySlug.get(m.slug);
-        return discoveredModel ? Object.assign({}, m, discoveredModel) : m;
-      });
-      const additions = enriched.filter((m) => !existing.has(m.slug));
-      result[provider] = [...additions, ...merged];
-      continue;
-    }
-    const discoveredBySlug = new Map(dedupedModels.map((m) => [m.slug, m]));
-    const merged = (base[provider] ?? []).map((m) => {
-      const discoveredModel = discoveredBySlug.get(m.slug);
-      return discoveredModel ? Object.assign({}, m, discoveredModel) : m;
-    });
-    // For non-copilot providers, surface discovered-only models first so newly
-    // available runtime models are visible at the top of the picker.
-    const additions = dedupedModels.filter((m) => !existing.has(m.slug));
-    result[provider] = [...additions, ...merged];
-  }
-  return result;
-}
-
-export function resolveModelOptionsByProvider(settings: {
-  customCodexModels: readonly string[];
-  customCopilotModels: readonly string[];
-  customClaudeModels: readonly string[];
-  customCursorModels: readonly string[];
-  customOpencodeModels: readonly string[];
-  customGeminiCliModels: readonly string[];
-  customAmpModels: readonly string[];
-  customKiloModels: readonly string[];
-  discovered?: Partial<Record<ProviderKind, ReadonlyArray<ModelOptionEntry> | undefined>>;
-}): Record<ProviderKind, ReadonlyArray<ModelOptionEntry>> {
-  return mergeDiscoveredModels(buildModelOptionsByProvider(settings), settings.discovered ?? {});
-}
diff --git a/apps/web/src/providerModels.ts b/apps/web/src/providerModels.ts
index f94b344e669..aa9afcf31e1 100644
--- a/apps/web/src/providerModels.ts
+++ b/apps/web/src/providerModels.ts
@@ -1,19 +1,21 @@
 import {
+  DEFAULT_MODEL,
   DEFAULT_MODEL_BY_PROVIDER,
+  defaultInstanceIdForDriver,
+  ProviderDriverKind,
   type ModelCapabilities,
-  type ProviderKind,
+  type ProviderInstanceId,
   type ServerProvider,
   type ServerProviderModel,
 } from "@t3tools/contracts";
-import {
-  EMPTY_MODEL_CAPABILITIES,
-  hasEffortLevel,
-  normalizeModelSlug,
-  resolveContextWindow,
-  trimOrNull,
-} from "@t3tools/shared/model";
+import { createModelCapabilities, normalizeModelSlug } from "@t3tools/shared/model";
+
+const EMPTY_CAPABILITIES: ModelCapabilities = createModelCapabilities({
+  optionDescriptors: [],
+});
+const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
-export function formatProviderKindLabel(provider: ProviderKind): string {
+export function formatProviderDriverKindLabel(provider: ProviderDriverKind): string {
   return provider
     .replace(/([a-z])([A-Z])/g, "$1 $2")
     .replace(/[_-]+/g, " ")
@@ -23,36 +25,37 @@ export function formatProviderKindLabel(provider: ProviderKind): string {
 
 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: ProviderKind,
+  provider: ProviderDriverKind,
 ): string {
   const snapshot = getProviderSnapshot(providers, provider);
-  return snapshot?.displayName?.trim() || formatProviderKindLabel(provider);
+  return snapshot?.displayName?.trim() || formatProviderDriverKindLabel(provider);
 }
 
 export function getProviderInteractionModeToggle(
   providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 ): boolean {
   return getProviderSnapshot(providers, provider)?.showInteractionModeToggle ?? true;
 }
 
 export function isProviderEnabled(
   providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 ): boolean {
   if (providers.length === 0) {
     return true;
@@ -60,36 +63,38 @@ export function isProviderEnabled(
   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_MODEL_CAPABILITIES
-  );
+  return models.find((candidate) => candidate.slug === slug)?.capabilities ?? EMPTY_CAPABILITIES;
 }
 
 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/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
index 981006315ed..5528072e57b 100644
--- a/apps/web/src/rightPanelLayout.ts
+++ b/apps/web/src/rightPanelLayout.ts
@@ -1,3 +1,3 @@
-export const RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY = "(max-width: 1180px)";
+export const RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY = "(max-width: 980px)";
 export const RIGHT_PANEL_SHEET_CLASS_NAME =
-  "w-[min(88vw,820px)] max-w-[820px] p-0 wco:mt-[env(titlebar-area-height)] wco:h-[calc(100%-env(titlebar-area-height))] wco:max-h-[calc(100%-env(titlebar-area-height))]";
+  "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..f5844f2c941 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -13,6 +13,7 @@ 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 SettingsGeneralRouteImport } from './routes/settings.general'
 import { Route as SettingsConnectionsRouteImport } from './routes/settings.connections'
 import { Route as SettingsArchivedRouteImport } from './routes/settings.archived'
@@ -38,6 +39,11 @@ const ChatIndexRoute = ChatIndexRouteImport.update({
   path: '/',
   getParentRoute: () => ChatRoute,
 } as any)
+const SettingsSourceControlRoute = SettingsSourceControlRouteImport.update({
+  id: '/source-control',
+  path: '/source-control',
+  getParentRoute: () => SettingsRoute,
+} as any)
 const SettingsGeneralRoute = SettingsGeneralRouteImport.update({
   id: '/general',
   path: '/general',
@@ -72,6 +78,7 @@ export interface FileRoutesByFullPath {
   '/settings/archived': typeof SettingsArchivedRoute
   '/settings/connections': typeof SettingsConnectionsRoute
   '/settings/general': typeof SettingsGeneralRoute
+  '/settings/source-control': typeof SettingsSourceControlRoute
   '/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
   '/draft/$draftId': typeof ChatDraftDraftIdRoute
 }
@@ -81,6 +88,7 @@ export interface FileRoutesByTo {
   '/settings/archived': typeof SettingsArchivedRoute
   '/settings/connections': typeof SettingsConnectionsRoute
   '/settings/general': typeof SettingsGeneralRoute
+  '/settings/source-control': typeof SettingsSourceControlRoute
   '/': typeof ChatIndexRoute
   '/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
   '/draft/$draftId': typeof ChatDraftDraftIdRoute
@@ -93,6 +101,7 @@ export interface FileRoutesById {
   '/settings/archived': typeof SettingsArchivedRoute
   '/settings/connections': typeof SettingsConnectionsRoute
   '/settings/general': typeof SettingsGeneralRoute
+  '/settings/source-control': typeof SettingsSourceControlRoute
   '/_chat/': typeof ChatIndexRoute
   '/_chat/$environmentId/$threadId': typeof ChatEnvironmentIdThreadIdRoute
   '/_chat/draft/$draftId': typeof ChatDraftDraftIdRoute
@@ -106,6 +115,7 @@ export interface FileRouteTypes {
     | '/settings/archived'
     | '/settings/connections'
     | '/settings/general'
+    | '/settings/source-control'
     | '/$environmentId/$threadId'
     | '/draft/$draftId'
   fileRoutesByTo: FileRoutesByTo
@@ -115,6 +125,7 @@ export interface FileRouteTypes {
     | '/settings/archived'
     | '/settings/connections'
     | '/settings/general'
+    | '/settings/source-control'
     | '/'
     | '/$environmentId/$threadId'
     | '/draft/$draftId'
@@ -126,6 +137,7 @@ export interface FileRouteTypes {
     | '/settings/archived'
     | '/settings/connections'
     | '/settings/general'
+    | '/settings/source-control'
     | '/_chat/'
     | '/_chat/$environmentId/$threadId'
     | '/_chat/draft/$draftId'
@@ -167,6 +179,13 @@ 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/general': {
       id: '/settings/general'
       path: '/general'
@@ -223,12 +242,14 @@ interface SettingsRouteChildren {
   SettingsArchivedRoute: typeof SettingsArchivedRoute
   SettingsConnectionsRoute: typeof SettingsConnectionsRoute
   SettingsGeneralRoute: typeof SettingsGeneralRoute
+  SettingsSourceControlRoute: typeof SettingsSourceControlRoute
 }
 
 const SettingsRouteChildren: SettingsRouteChildren = {
   SettingsArchivedRoute: SettingsArchivedRoute,
   SettingsConnectionsRoute: SettingsConnectionsRoute,
   SettingsGeneralRoute: SettingsGeneralRoute,
+  SettingsSourceControlRoute: SettingsSourceControlRoute,
 }
 
 const SettingsRouteWithChildren = SettingsRoute._addFileChildren(
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index acfa9c5ce2a..37971a286d6 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -13,6 +13,7 @@ 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 {
   SlowRpcAckToastCoordinator,
   WebSocketConnectionCoordinator,
@@ -46,20 +47,42 @@ import { syncBrowserChromeTheme } from "../hooks/useTheme";
 import {
   ensureEnvironmentConnectionBootstrapped,
   getPrimaryEnvironmentConnection,
+  listSavedEnvironmentRecords,
+  waitForSavedEnvironmentRegistryHydration,
   startEnvironmentConnectionService,
+  useSavedEnvironmentRegistryStore,
 } from "../environments/runtime";
 import { migrateLocalSettingsToServer } from "../hooks/useSettings";
 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(),
@@ -78,6 +101,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(() => {
@@ -92,30 +116,65 @@ 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 ? <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);
@@ -188,7 +247,13 @@ function errorDetails(error: unknown): string {
 }
 
 function ServerStateBootstrap() {
-  useEffect(() => startServerStateSync(getPrimaryEnvironmentConnection().client.server), []);
+  useEffect(() => {
+    if (!getPrimaryKnownEnvironment()) {
+      return;
+    }
+
+    return startServerStateSync(getPrimaryEnvironmentConnection().client.server);
+  }, []);
 
   return null;
 }
diff --git a/apps/web/src/routes/_chat.$environmentId.$threadId.tsx b/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
index ff20673e2de..dc1abed8a0b 100644
--- a/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
+++ b/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
@@ -26,8 +26,9 @@ import { Sidebar, SidebarInset, SidebarProvider, SidebarRail } from "~/component
 
 const DiffPanel = lazy(() => import("../components/DiffPanel"));
 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 = 36 * 16;
 const COMPOSER_COMPACT_MIN_LEFT_CONTROLS_WIDTH_PX = 208;
 
 const DiffLoadingFallback = (props: { mode: DiffPanelMode }) => {
@@ -124,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,
@@ -238,7 +240,7 @@ 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}
@@ -259,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}
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 fb8191f4480..da22d7e6028 100644
--- a/apps/web/src/routes/_chat.tsx
+++ b/apps/web/src/routes/_chat.tsx
@@ -108,7 +108,10 @@ function ChatRouteLayout() {
 
 export const Route = createFileRoute("/_chat")({
   beforeLoad: async ({ context }) => {
-    if (context.authGateState.status !== "authenticated") {
+    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 6925dac69cc..6575cd1bafa 100644
--- a/apps/web/src/routes/pair.tsx
+++ b/apps/web/src/routes/pair.tsx
@@ -1,11 +1,21 @@
 import { createFileRoute, redirect, useNavigate } from "@tanstack/react-router";
 
-import { PairingPendingSurface, PairingRouteSurface } from "../components/auth/PairingRouteSurface";
+import {
+  HostedPairingRouteSurface,
+  PairingPendingSurface,
+  PairingRouteSurface,
+} from "../components/auth/PairingRouteSurface";
 
 export const Route = createFileRoute("/pair")({
   beforeLoad: async ({ context }) => {
     const { authGateState } = context;
-    if (authGateState.status === "authenticated") {
+    if (authGateState.status === "hosted-pairing") {
+      return {
+        authGateState,
+      };
+    }
+
+    if (authGateState.status === "authenticated" || authGateState.status === "hosted-static") {
       throw redirect({ to: "/", replace: true });
     }
     return {
@@ -24,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.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 64b5e7bc684..ec98e7ee363 100644
--- a/apps/web/src/routes/settings.tsx
+++ b/apps/web/src/routes/settings.tsx
@@ -1,6 +1,13 @@
 import { RotateCcwIcon } from "lucide-react";
-import { Outlet, createFileRoute, redirect, useLocation } from "@tanstack/react-router";
-import { useEffect, useState } from "react";
+import {
+  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";
@@ -25,16 +32,25 @@ function RestoreDefaultsButton({ onRestored }: { onRestored: () => void }) {
 
 function SettingsContentLayout() {
   const location = useLocation();
+  const navigate = useNavigate();
+  const canGoBack = useCanGoBack();
   const [restoreSignal, setRestoreSignal] = useState(0);
   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();
       }
     };
 
@@ -42,7 +58,7 @@ 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">
@@ -88,7 +104,10 @@ function SettingsRouteLayout() {
 
 export const Route = createFileRoute("/settings")({
   beforeLoad: async ({ context, location }) => {
-    if (context.authGateState.status !== "authenticated") {
+    if (
+      context.authGateState.status !== "authenticated" &&
+      context.authGateState.status !== "hosted-static"
+    ) {
       throw redirect({ to: "/pair", replace: true });
     }
 
diff --git a/apps/web/src/rpc/protocol.ts b/apps/web/src/rpc/protocol.ts
index 5c5c51d8990..3c52764a0aa 100644
--- a/apps/web/src/rpc/protocol.ts
+++ b/apps/web/src/rpc/protocol.ts
@@ -14,14 +14,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 +78,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 +194,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 +227,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/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 b67be32dc78..8e5819032df 100644
--- a/apps/web/src/rpc/wsRpcClient.ts
+++ b/apps/web/src/rpc/wsRpcClient.ts
@@ -2,8 +2,8 @@ import {
   type GitActionProgressEvent,
   type GitRunStackedActionInput,
   type GitRunStackedActionResult,
-  type GitStatusResult,
-  type GitStatusStreamEvent,
+  type VcsStatusResult,
+  type VcsStatusStreamEvent,
   type LocalApi,
   ORCHESTRATION_WS_METHODS,
   type ServerSettingsPatch,
@@ -71,30 +71,40 @@ export interface WsRpcClient {
   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
@@ -102,12 +112,21 @@ 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 upsertKeybinding: RpcUnaryMethod<typeof WS_METHODS.serverUpsertKeybinding>;
     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 subscribeConfig: RpcStreamMethod<typeof WS_METHODS.subscribeServerConfig>;
     readonly subscribeLifecycle: RpcStreamMethod<typeof WS_METHODS.subscribeServerLifecycle>;
     readonly subscribeAuthAccess: RpcStreamMethod<typeof WS_METHODS.subscribeAuthAccess>;
@@ -136,11 +155,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) =>
@@ -151,25 +169,43 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
     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;
 
@@ -189,16 +225,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) =>
@@ -206,31 +232,30 @@ 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 ?? {})),
       upsertKeybinding: (input) =>
         transport.request((client) => client[WS_METHODS.serverUpsertKeybinding](input)),
       getSettings: () => transport.request((client) => client[WS_METHODS.serverGetSettings]({})),
       updateSettings: (patch) =>
         transport.request((client) => client[WS_METHODS.serverUpdateSettings]({ patch })),
+      discoverSourceControl: () =>
+        transport.request((client) => client[WS_METHODS.serverDiscoverSourceControl]({})),
       subscribeConfig: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeServerConfig]({}),
-          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,
-        ),
+        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,
-        ),
+        transport.subscribe((client) => client[WS_METHODS.subscribeAuthAccess]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeAuthAccess,
+        }),
     },
     orchestration: {
       dispatchCommand: (input) =>
@@ -243,13 +268,13 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
         transport.subscribe(
           (client) => client[ORCHESTRATION_WS_METHODS.subscribeShell]({}),
           listener,
-          options,
+          { ...options, tag: ORCHESTRATION_WS_METHODS.subscribeShell },
         ),
       subscribeThread: (input, listener, options) =>
         transport.subscribe(
           (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 a5610a931f6..84d886668fb 100644
--- a/apps/web/src/rpc/wsTransport.test.ts
+++ b/apps/web/src/rpc/wsTransport.test.ts
@@ -284,10 +284,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 +303,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 +361,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 +403,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);
diff --git a/apps/web/src/rpc/wsTransport.ts b/apps/web/src/rpc/wsTransport.ts
index d9a50a9fad0..316be9db9ee 100644
--- a/apps/web/src/rpc/wsTransport.ts
+++ b/apps/web/src/rpc/wsTransport.ts
@@ -25,6 +25,7 @@ import { isTransportConnectionErrorMessage } from "./transportError";
 interface SubscribeOptions {
   readonly retryDelay?: Duration.Input;
   readonly onResubscribe?: () => void;
+  readonly tag?: string;
 }
 
 interface RequestOptions {
@@ -40,6 +41,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;
@@ -52,8 +59,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,
@@ -124,18 +136,24 @@ export class WsTransport {
 
         const session = this.session;
         try {
-          if (hasReceivedValue) {
-            try {
-              options?.onResubscribe?.();
-            } catch {
-              // Swallow reconnect hook errors so the stream can recover.
-            }
-          }
-
           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;
@@ -191,6 +209,7 @@ export class WsTransport {
       }
 
       clearAllTrackedRpcRequests();
+      this.lastHeartbeatPongAt = 0;
       const previousSession = this.session;
       this.session = this.createSession();
       await this.closeSession(previousSession);
@@ -200,6 +219,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;
@@ -209,14 +232,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 {
@@ -230,6 +281,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,
   ): {
@@ -242,6 +297,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) =>
@@ -263,6 +335,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 8f042213295..9e2e4ba086c 100644
--- a/apps/web/src/session-logic.test.ts
+++ b/apps/web/src/session-logic.test.ts
@@ -19,7 +19,6 @@ import {
   findSidebarProposedPlan,
   hasActionableProposedPlan,
   hasToolActivityForTurn,
-  hasToolActivitySince,
   isLatestTurnSettled,
   PROVIDER_OPTIONS,
 } from "./session-logic";
@@ -935,7 +934,6 @@ describe("deriveWorkLogEntries", () => {
     ];
 
     const [entry] = deriveWorkLogEntries(activities, undefined);
-    expect(entry?.activityKind).toBe("tool.completed");
     expect(entry?.itemType).toBe("web_search");
   });
 
@@ -1146,46 +1144,10 @@ describe("deriveWorkLogEntries", () => {
     ];
 
     const [entry] = deriveWorkLogEntries(activities, undefined);
-    expect(entry?.activityKind).toBe("approval.requested");
     expect(entry?.requestKind).toBe("file-read");
     expect(entry?.tone).toBe("info");
   });
 
-  it("keeps multi-turn tool activity since the latest user message", () => {
-    const activities: OrchestrationThreadActivity[] = [
-      makeActivity({
-        id: "before-user",
-        createdAt: "2026-02-23T00:00:01.000Z",
-        turnId: "turn-1",
-        summary: "Old tool call",
-        kind: "tool.completed",
-        tone: "tool",
-      }),
-      makeActivity({
-        id: "after-user-first-turn",
-        createdAt: "2026-02-23T00:00:03.000Z",
-        turnId: "turn-2",
-        summary: "First Copilot tool call",
-        kind: "tool.completed",
-        tone: "tool",
-      }),
-      makeActivity({
-        id: "after-user-second-turn",
-        createdAt: "2026-02-23T00:00:04.000Z",
-        turnId: "turn-3",
-        summary: "Second Copilot tool call",
-        kind: "tool.completed",
-        tone: "tool",
-      }),
-    ];
-
-    const entries = deriveWorkLogEntries(activities, undefined, "2026-02-23T00:00:02.000Z");
-    expect(entries.map((entry) => entry.id)).toEqual([
-      "after-user-first-turn",
-      "after-user-second-turn",
-    ]);
-  });
-
   it("collapses repeated lifecycle updates for the same tool call into one entry", () => {
     const activities: OrchestrationThreadActivity[] = [
       makeActivity({
@@ -1368,7 +1330,6 @@ describe("deriveTimelineEntries", () => {
           createdAt: "2026-02-23T00:00:03.000Z",
           label: "Ran tests",
           tone: "tool",
-          activityKind: "tool.completed",
         },
       ],
     );
@@ -1482,30 +1443,6 @@ describe("hasToolActivityForTurn", () => {
   });
 });
 
-describe("hasToolActivitySince", () => {
-  it("tracks tool activity across multiple turns since the latest user message", () => {
-    const activities: OrchestrationThreadActivity[] = [
-      makeActivity({
-        id: "before-user",
-        createdAt: "2026-02-23T00:00:01.000Z",
-        turnId: "turn-1",
-        kind: "tool.completed",
-        tone: "tool",
-      }),
-      makeActivity({
-        id: "after-user",
-        createdAt: "2026-02-23T00:00:03.000Z",
-        turnId: "turn-2",
-        kind: "tool.completed",
-        tone: "tool",
-      }),
-    ];
-
-    expect(hasToolActivitySince(activities, "2026-02-23T00:00:02.000Z")).toBe(true);
-    expect(hasToolActivitySince(activities, "2026-02-23T00:00:04.000Z")).toBe(false);
-  });
-});
-
 describe("isLatestTurnSettled", () => {
   const latestTurn = {
     turnId: TurnId.make("turn-1"),
diff --git a/apps/web/src/session-logic.ts b/apps/web/src/session-logic.ts
index f629a8af29b..4a1b07c9090 100644
--- a/apps/web/src/session-logic.ts
+++ b/apps/web/src/session-logic.ts
@@ -6,7 +6,7 @@ import {
   type OrchestrationLatestTurn,
   type OrchestrationThreadActivity,
   type OrchestrationProposedPlanId,
-  type ProviderKind,
+  ProviderDriverKind,
   type ToolLifecycleItemType,
   type UserInputQuestion,
   type ThreadId,
@@ -22,7 +22,7 @@ import type {
   TurnDiffSummary,
 } from "./types";
 
-export type ProviderPickerKind = ProviderKind;
+export type ProviderPickerKind = ProviderDriverKind;
 
 export const PROVIDER_OPTIONS: Array<{
   value: ProviderPickerKind;
@@ -31,14 +31,24 @@ export const PROVIDER_OPTIONS: Array<{
   /** Shown on the model picker sidebar when relevant */
   pickerSidebarBadge?: "new" | "soon";
 }> = [
-  { value: "codex", label: "Codex", available: true },
-  { value: "copilot", label: "GitHub Copilot", available: true },
-  { value: "claudeAgent", label: "Claude Code", available: true },
-  { value: "cursor", label: "Cursor Agent", available: true, pickerSidebarBadge: "new" },
-  { value: "opencode", label: "OpenCode", available: true, pickerSidebarBadge: "new" },
-  { value: "geminiCli", label: "Gemini CLI", available: true },
-  { value: "amp", label: "AMPcode", available: true },
-  { value: "kilo", label: "Kilo", available: true },
+  { value: ProviderDriverKind.make("codex"), label: "Codex", available: true },
+  { value: ProviderDriverKind.make("copilot"), label: "GitHub Copilot", available: true },
+  { value: ProviderDriverKind.make("claudeAgent"), label: "Claude Code", available: true },
+  {
+    value: ProviderDriverKind.make("cursor"),
+    label: "Cursor Agent",
+    available: true,
+    pickerSidebarBadge: "new",
+  },
+  {
+    value: ProviderDriverKind.make("opencode"),
+    label: "OpenCode",
+    available: true,
+    pickerSidebarBadge: "new",
+  },
+  { value: ProviderDriverKind.make("geminiCli"), label: "Gemini CLI", available: true },
+  { value: ProviderDriverKind.make("amp"), label: "AMPcode", available: true },
+  { value: ProviderDriverKind.make("kilo"), label: "Kilo", available: true },
 ];
 
 export interface WorkLogEntry {
@@ -50,7 +60,6 @@ export interface WorkLogEntry {
   rawCommand?: string;
   changedFiles?: ReadonlyArray<string>;
   tone: "thinking" | "tool" | "info" | "error";
-  activityKind: OrchestrationThreadActivity["kind"];
   toolTitle?: string;
   itemType?: ToolLifecycleItemType;
   requestKind?: PendingApproval["requestKind"];
@@ -478,14 +487,10 @@ export function hasActionableProposedPlan(
 export function deriveWorkLogEntries(
   activities: ReadonlyArray<OrchestrationThreadActivity>,
   latestTurnId: TurnId | undefined,
-  sinceCreatedAt?: string,
 ): WorkLogEntry[] {
   const ordered = [...activities].toSorted(compareActivitiesByOrder);
   const entries = ordered
-    .filter((activity) =>
-      latestTurnId ? activity.turnId === latestTurnId || activity.turnId === null : true,
-    )
-    .filter((activity) => (sinceCreatedAt ? activity.createdAt >= sinceCreatedAt : true))
+    .filter((activity) => (latestTurnId ? activity.turnId === latestTurnId : true))
     .filter((activity) => activity.kind !== "tool.started")
     .filter((activity) => activity.kind !== "task.started")
     .filter((activity) => activity.kind !== "context-window.updated")
@@ -493,7 +498,7 @@ export function deriveWorkLogEntries(
     .filter((activity) => !isPlanBoundaryToolActivity(activity))
     .map(toDerivedWorkLogEntry);
   return collapseDerivedWorkLogEntries(entries).map(
-    ({ collapseKey: _collapseKey, ...entry }) => entry,
+    ({ activityKind: _activityKind, collapseKey: _collapseKey, ...entry }) => entry,
   );
 }
 
@@ -1155,16 +1160,6 @@ export function hasToolActivityForTurn(
   return activities.some((activity) => activity.turnId === turnId && activity.tone === "tool");
 }
 
-export function hasToolActivitySince(
-  activities: ReadonlyArray<OrchestrationThreadActivity>,
-  sinceCreatedAt: string | undefined,
-): boolean {
-  return activities.some(
-    (activity) =>
-      activity.tone === "tool" && (sinceCreatedAt ? activity.createdAt >= sinceCreatedAt : true),
-  );
-}
-
 export function deriveTimelineEntries(
   messages: ChatMessage[],
   proposedPlans: ProposedPlan[],
@@ -1218,11 +1213,7 @@ export function deriveCompletionDividerBeforeEntryId(
 
   const turnStartedAt = Date.parse(latestTurn.startedAt);
   const turnCompletedAt = Date.parse(latestTurn.completedAt);
-  if (
-    Number.isNaN(turnStartedAt) ||
-    Number.isNaN(turnCompletedAt) ||
-    turnCompletedAt < turnStartedAt
-  ) {
+  if (Number.isNaN(turnStartedAt) || Number.isNaN(turnCompletedAt)) {
     return null;
   }
 
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 4104f4a75cf..1d5eba7bdb4 100644
--- a/apps/web/src/store.test.ts
+++ b/apps/web/src/store.test.ts
@@ -1,11 +1,12 @@
 import { scopeThreadRef } from "@t3tools/client-runtime";
 import {
   CheckpointRef,
-  DEFAULT_MODEL_BY_PROVIDER,
+  DEFAULT_MODEL,
   EnvironmentId,
   EventId,
   MessageId,
   ProjectId,
+  ProviderInstanceId,
   ThreadId,
   TurnId,
   type OrchestrationEvent,
@@ -15,6 +16,7 @@ import { describe, expect, it } from "vitest";
 import {
   applyOrchestrationEvent,
   applyOrchestrationEvents,
+  removeEnvironmentState,
   selectEnvironmentState,
   selectProjectsAcrossEnvironments,
   selectThreadByRef,
@@ -65,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,
@@ -93,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",
@@ -245,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({
@@ -463,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",
@@ -480,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",
@@ -518,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",
@@ -531,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",
@@ -548,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 cbdcecb8e26..c6d30e28b09 100644
--- a/apps/web/src/store.ts
+++ b/apps/web/src/store.ts
@@ -18,7 +18,7 @@ import type {
   ScopedProjectRef,
   ScopedThreadRef,
 } from "@t3tools/contracts";
-import { ProviderKind } from "@t3tools/contracts";
+import { isProviderDriverKind, ProviderDriverKind } from "@t3tools/contracts";
 import type { ThreadId, TurnId } from "@t3tools/contracts";
 import { Schema } from "effect";
 import { resolveModelSlugForProvider } from "@t3tools/shared/model";
@@ -129,12 +129,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: ProviderKind; 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),
   };
 }
 
@@ -145,6 +149,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,
@@ -1000,11 +1005,11 @@ function toLegacySessionStatus(
   }
 }
 
-function toLegacyProvider(providerName: string | null): ProviderKind {
-  if (Schema.is(ProviderKind)(providerName)) {
+function toLegacyProvider(providerName: string | null): ProviderDriverKind {
+  if (Schema.is(ProviderDriverKind)(providerName)) {
     return providerName;
   }
-  return "codex";
+  return ProviderDriverKind.make("codex");
 }
 
 function attachmentPreviewRoutePath(attachmentId: string): string {
@@ -1900,6 +1905,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,
@@ -1925,6 +1944,7 @@ export function setThreadBranch(
 
 interface AppStore extends AppState {
   setActiveEnvironmentId: (environmentId: EnvironmentId) => void;
+  removeEnvironmentState: (environmentId: EnvironmentId) => void;
   syncServerShellSnapshot: (
     snapshot: OrchestrationShellSnapshot,
     environmentId: EnvironmentId,
@@ -1948,6 +1968,8 @@ export const useStore = create<AppStore>((set) => ({
   ...initialState,
   setActiveEnvironmentId: (environmentId) =>
     set((state) => setActiveEnvironmentId(state, environmentId)),
+  removeEnvironmentState: (environmentId) =>
+    set((state) => removeEnvironmentState(state, environmentId)),
   syncServerShellSnapshot: (snapshot, environmentId) =>
     set((state) => syncServerShellSnapshot(state, snapshot, environmentId)),
   syncServerThreadDetail: (thread, environmentId) =>
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 f63208d9ba7..3e6aaebc0dc 100644
--- a/apps/web/src/uiStateStore.test.ts
+++ b/apps/web/src/uiStateStore.test.ts
@@ -4,11 +4,13 @@ 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,
@@ -22,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";
@@ -79,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";
@@ -531,6 +568,17 @@ describe("uiStateStore persistence round-trip", () => {
     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
diff --git a/apps/web/src/uiStateStore.ts b/apps/web/src/uiStateStore.ts
index 07a7a7bd16b..aec5bec3d2b 100644
--- a/apps/web/src/uiStateStore.ts
+++ b/apps/web/src/uiStateStore.ts
@@ -20,6 +20,7 @@ export interface PersistedUiState {
   expandedProjectCwds?: string[];
   projectOrderCwds?: string[];
   threadLastVisitedAtById?: Record<string, string>;
+  defaultAdvertisedEndpointKey?: string | null;
   threadChangedFilesExpandedById?: Record<string, Record<string, boolean>>;
 }
 
@@ -33,7 +34,11 @@ 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. */
@@ -53,6 +58,7 @@ const initialState: UiState = {
   projectOrder: [],
   threadLastVisitedAtById: {},
   threadChangedFilesExpandedById: {},
+  defaultAdvertisedEndpointKey: null,
 };
 
 const persistedCollapsedProjectCwds = new Set<string>();
@@ -91,6 +97,11 @@ function readPersistedState(): UiState {
     return {
       ...initialState,
       threadLastVisitedAtById: persistedThreadLastVisitedAtById,
+      defaultAdvertisedEndpointKey:
+        typeof parsed.defaultAdvertisedEndpointKey === "string" &&
+        parsed.defaultAdvertisedEndpointKey.length > 0
+          ? parsed.defaultAdvertisedEndpointKey
+          : null,
       threadChangedFilesExpandedById: sanitizePersistedThreadChangedFilesExpanded(
         parsed.threadChangedFilesExpandedById,
       ),
@@ -188,6 +199,7 @@ export function persistState(state: UiState): void {
         expandedProjectCwds,
         projectOrderCwds,
         threadLastVisitedAtById: state.threadLastVisitedAtById,
+        defaultAdvertisedEndpointKey: state.defaultAdvertisedEndpointKey,
         threadChangedFilesExpandedById,
       } satisfies PersistedUiState),
     );
@@ -541,6 +553,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 {
@@ -615,6 +638,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: (
@@ -634,6 +658,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..99c5a65d85e 100644
--- a/apps/web/src/vite-env.d.ts
+++ b/apps/web/src/vite-env.d.ts
@@ -3,6 +3,9 @@
 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 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 56711f4ad4b..07d4c74050c 100644
--- a/apps/web/test/wsRpcHarness.ts
+++ b/apps/web/test/wsRpcHarness.ts
@@ -26,7 +26,7 @@ const STREAM_METHODS = new Set<string>([
   ORCHESTRATION_WS_METHODS.subscribeShell,
   ORCHESTRATION_WS_METHODS.subscribeThread,
   WS_METHODS.gitRunStackedAction,
-  WS_METHODS.subscribeGitStatus,
+  WS_METHODS.subscribeVcsStatus,
   WS_METHODS.subscribeTerminalEvents,
   WS_METHODS.subscribeServerConfig,
   WS_METHODS.subscribeServerLifecycle,
diff --git a/apps/web/vercel.json b/apps/web/vercel.json
new file mode 100644
index 00000000000..ecfa7a47fc9
--- /dev/null
+++ b/apps/web/vercel.json
@@ -0,0 +1,10 @@
+{
+  "buildCommand": "turbo build --filter @t3tools/web && bun ../../scripts/apply-web-brand-assets.ts production",
+  "installCommand": "bun add -g turbo && bun install --filter '@t3tools/contracts' --filter '@t3tools/client-runtime' --filter '@t3tools/scripts' --filter '@t3tools/web'",
+  "rewrites": [
+    {
+      "source": "/(.*)",
+      "destination": "/index.html"
+    }
+  ]
+}
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index d257c8251d3..42ff74adb96 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -9,6 +9,15 @@ 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 configuredHostedAppUrl = (() => {
+  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 process.env.VITE_HOSTED_APP_URL?.trim();
+})();
 const sourcemapEnv = process.env.T3CODE_WEB_SOURCEMAP?.trim().toLowerCase();
 
 const buildSourcemap =
@@ -61,12 +70,15 @@ export default defineConfig({
       "@pierre/diffs/react",
       "@pierre/diffs/worker/worker.js",
       "ghostty-web",
+      "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.VITE_HOSTED_APP_URL": JSON.stringify(configuredHostedAppUrl ?? ""),
     "import.meta.env.APP_VERSION": JSON.stringify(pkg.version),
   },
   resolve: {
diff --git a/bun.lock b/bun.lock
index aa4be4d7cd8..dd137cf65fd 100644
--- a/bun.lock
+++ b/bun.lock
@@ -19,13 +19,17 @@
       "name": "@t3tools/desktop",
       "version": "0.0.21",
       "dependencies": {
+        "@effect/platform-node": "catalog:",
         "effect": "catalog:",
-        "electron": "40.8.5",
+        "electron": "40.9.3",
         "electron-updater": "^6.6.2",
       },
       "devDependencies": {
+        "@t3tools/client-runtime": "workspace:*",
         "@t3tools/contracts": "workspace:*",
         "@t3tools/shared": "workspace:*",
+        "@t3tools/ssh": "workspace:*",
+        "@t3tools/tailscale": "workspace:*",
         "@types/node": "catalog:",
         "effect-acp": "workspace:*",
         "tsdown": "catalog:",
@@ -68,6 +72,7 @@
         "@effect/vitest": "catalog:",
         "@t3tools/contracts": "workspace:*",
         "@t3tools/shared": "workspace:*",
+        "@t3tools/tailscale": "workspace:*",
         "@t3tools/web": "workspace:*",
         "@types/bun": "catalog:",
         "@types/node": "catalog:",
@@ -137,6 +142,7 @@
       "version": "0.0.0-alpha.1",
       "dependencies": {
         "@t3tools/contracts": "workspace:*",
+        "effect": "catalog:",
       },
       "devDependencies": {
         "@effect/language-service": "catalog:",
@@ -203,6 +209,38 @@
         "vitest": "catalog:",
       },
     },
+    "packages/ssh": {
+      "name": "@t3tools/ssh",
+      "version": "0.0.0-alpha.1",
+      "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",
+      "version": "0.0.0-alpha.1",
+      "dependencies": {
+        "@effect/platform-node": "catalog:",
+        "effect": "catalog:",
+      },
+      "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@effect/vitest": "catalog:",
+        "@types/node": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:",
+      },
+    },
     "scripts": {
       "name": "@t3tools/scripts",
       "dependencies": {
@@ -225,6 +263,9 @@
     "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:",
@@ -241,17 +282,17 @@
     "yaml": "^2.8.3",
   },
   "catalog": {
-    "@effect/atom-react": "4.0.0-beta.45",
+    "@effect/atom-react": "4.0.0-beta.59",
     "@effect/language-service": "0.84.2",
-    "@effect/openapi-generator": "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/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",
     "@types/bun": "^1.3.11",
     "@types/node": "^24.10.13",
-    "effect": "4.0.0-beta.45",
+    "effect": "4.0.0-beta.59",
     "tsdown": "^0.21.7",
     "typescript": "^5.7.3",
     "vitest": "^4.0.0",
@@ -339,21 +380,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/openapi-generator": ["@effect/openapi-generator@4.0.0-beta.45", "", { "peerDependencies": { "@effect/platform-node": "^4.0.0-beta.45", "effect": "^4.0.0-beta.45" }, "bin": { "openapigen": "dist/bin.js" } }, "sha512-zT1UPzapV6mZebMuYhoDPQj/FKNn4R+oDgz1hEcQwazal4+lVDyEYGhRl0PgZroy6CP78fAOWNgW7TriGqSlOQ=="],
+    "@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.45", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.45" }, "peerDependencies": { "effect": "^4.0.0-beta.45" } }, "sha512-dZsbkJ+o4JfKE1OIAlMq8YWhmEfXxtTYennYADK/M/XlOtkFLsc2jkZppDvMznVni6JpFxWc7wd5rUf8jBVP5g=="],
+    "@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=="],
 
@@ -765,6 +806,10 @@
 
     "@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=="],
@@ -1121,13 +1166,13 @@
 
     "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
 
-    "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=="],
+    "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@40.8.5", "", { "dependencies": { "@electron/get": "^2.0.0", "@types/node": "^24.9.0", "extract-zip": "^2.0.1" }, "bin": { "electron": "cli.js" } }, "sha512-pgTY/VPQKaiU4sTjfU96iyxCXrFm4htVPCMRT4b7q9ijNTRgtLmLvcmzp2G4e7xDrq9p7OLHSmu1rBKFf6Y1/A=="],
+    "electron": ["electron@40.9.3", "", { "dependencies": { "@electron/get": "^2.0.0", "@types/node": "^24.9.0", "extract-zip": "^2.0.1" }, "bin": { "electron": "cli.js" } }, "sha512-rDcJOT6BBE689Ada+4jD3rVr05pMv9MZOgT0x/rIMVDF9c4ttx4RTb6lVARTyxZC7uqpirttCtcli1eg1DX5qg=="],
 
     "electron-to-chromium": ["electron-to-chromium@1.5.313", "", {}, "sha512-QBMrTWEf00GXZmJyx2lbYD45jpI3TUFnNIzJ5BBc8piGUDwMPa1GV6HJWTZVvY/eiN3fSopl7NRbgGp9sZ9LTA=="],
 
@@ -1881,7 +1926,7 @@
 
     "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
 
-    "toml": ["toml@3.0.0", "", {}, "sha512-y/mWCZinnvxjTKYhJ+pYxwD0mRLVvOtdS2Awbgxln6iEnt4rk0yBxeSBHkGJcPucRiG0e55mwWp+g/05rsrd6w=="],
+    "toml": ["toml@4.1.1", "", {}, "sha512-EBJnVBr3dTXdA89WVFoAIPUqkBjxPMwRqsfuo1r240tKFHXv3zgca4+NJib/h6TyvGF7vOawz0jGuryJCdNHrw=="],
 
     "totalist": ["totalist@3.0.1", "", {}, "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ=="],
 
@@ -1935,7 +1980,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=="],
 
@@ -2043,7 +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=="],
+    "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=="],
 
     "wsl-utils": ["wsl-utils@0.1.0", "", { "dependencies": { "is-wsl": "^3.1.0" } }, "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw=="],
 
@@ -2143,6 +2188,8 @@
 
     "@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=="],
 
+    "@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=="],
+
     "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=="],
 
     "astro/tinyglobby": ["tinyglobby@0.2.16", "", { "dependencies": { "fdir": "^6.5.0", "picomatch": "^4.0.4" } }, "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg=="],
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/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/package.json b/package.json
index d37b193d757..2a320ec9244 100644
--- a/package.json
+++ b/package.json
@@ -8,14 +8,14 @@
       "scripts"
     ],
     "catalog": {
-      "effect": "4.0.0-beta.45",
-      "@effect/atom-react": "4.0.0-beta.45",
-      "@effect/openapi-generator": "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.11",
       "@types/node": "^24.10.13",
@@ -93,5 +93,12 @@
     "workerDirectory": [
       "apps/web/public"
     ]
-  }
+  },
+  "patchedDependencies": {
+    "effect@4.0.0-beta.59": "patches/effect@4.0.0-beta.59.patch"
+  },
+  "trustedDependencies": [
+    "node-pty",
+    "electron"
+  ]
 }
diff --git a/packages/client-runtime/package.json b/packages/client-runtime/package.json
index bfe2d7828eb..fbe97d0dd69 100644
--- a/packages/client-runtime/package.json
+++ b/packages/client-runtime/package.json
@@ -15,7 +15,8 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@t3tools/contracts": "workspace:*"
+    "@t3tools/contracts": "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..314d8272c81
--- /dev/null
+++ b/packages/client-runtime/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/client-runtime/src/index.ts b/packages/client-runtime/src/index.ts
index 9ca76328a8e..cb7472dff51 100644
--- a/packages/client-runtime/src/index.ts
+++ b/packages/client-runtime/src/index.ts
@@ -1,2 +1,4 @@
+export * from "./advertisedEndpoint.ts";
 export * from "./knownEnvironment.ts";
 export * from "./scoped.ts";
+export * from "./sourceControlDiscoveryState.ts";
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/contracts/src/git.test.ts b/packages/contracts/src/git.test.ts
index ebd5324fb9f..b4f7bc213ce 100644
--- a/packages/contracts/src/git.test.ts
+++ b/packages/contracts/src/git.test.ts
@@ -2,14 +2,14 @@ import { describe, expect, it } from "vitest";
 import { Schema } from "effect";
 
 import {
-  GitCreateWorktreeInput,
+  VcsCreateWorktreeInput,
   GitPreparePullRequestThreadInput,
   GitRunStackedActionResult,
   GitRunStackedActionInput,
   GitResolvePullRequestResult,
 } 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 2b9d14ec19f..b5fa114d789 100644
--- a/packages/contracts/src/git.ts
+++ b/packages/contracts/src/git.ts
@@ -1,6 +1,7 @@
 import { Schema } from "effect";
 import { NonNegativeInt, PositiveInt, ThreadId, TrimmedNonEmptyString } from "./baseSchemas.ts";
-import { ProviderKind } from "./orchestration.ts";
+import { SourceControlProviderError, SourceControlProviderInfo } from "./sourceControl.ts";
+import { VcsDriverKind } from "./vcs.ts";
 
 const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
 const GIT_LIST_BRANCHES_MAX_LIMIT = 200;
@@ -41,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,
 });
@@ -80,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),
@@ -88,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,
@@ -106,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,
@@ -122,15 +115,13 @@ export const GitRunStackedActionInput = Schema.Struct({
   action: GitStackedAction,
   commitMessage: Schema.optional(TrimmedNonEmptyStringSchema.check(Schema.isMaxLength(10_000))),
   featureBranch: Schema.optional(Schema.Boolean),
-  provider: Schema.optional(ProviderKind),
-  model: Schema.optional(Schema.String),
   filePaths: Schema.optional(
     Schema.Array(TrimmedNonEmptyStringSchema).check(Schema.isMinLength(1)),
   ),
 });
 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),
@@ -138,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,
@@ -162,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(
@@ -223,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,
@@ -282,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,
@@ -316,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", {
@@ -336,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",
   {
@@ -372,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 47081d8df1b..1a3647eb314 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -1,15 +1,19 @@
 export * from "./baseSchemas.ts";
 export * from "./auth.ts";
 export * from "./environment.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";
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index ca16c5c8e1a..8f21a7a7b81 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -1,22 +1,22 @@
 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,
+  VcsStatusInput,
+  VcsStatusResult,
+  VcsCreateRefResult,
 } from "./git.ts";
 import type { FilesystemBrowseInput, FilesystemBrowseResult } from "./filesystem.ts";
 import type {
@@ -25,12 +25,7 @@ import type {
   ProjectWriteFileInput,
   ProjectWriteFileResult,
 } from "./project.ts";
-import type {
-  ProviderGetUsageInput,
-  ProviderListModelsInput,
-  ProviderListModelsResult,
-  ProviderUsageResult,
-} from "./provider.ts";
+import type { ProviderInstanceId } from "./providerInstance.ts";
 import type {
   ServerConfig,
   ServerProviderUpdatedPayload,
@@ -58,8 +53,24 @@ import type {
   OrchestrationThreadStreamItem,
 } from "./orchestration.ts";
 import type { EnvironmentId } from "./baseSchemas.ts";
+import type {
+  AuthBearerBootstrapResult,
+  AuthSessionState,
+  AuthWebSocketTokenResult,
+} from "./auth.ts";
+import type { AdvertisedEndpoint } from "./remoteAccess.ts";
 import { EditorId } from "./editor.ts";
-import { ServerSettings, type ClientSettings, type ServerSettingsPatch } from "./settings.ts";
+import type { 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;
@@ -131,6 +142,36 @@ export interface DesktopEnvironmentBootstrap {
   bootstrapToken?: string;
 }
 
+export interface DesktopSshEnvironmentTarget {
+  alias: string;
+  hostname: string;
+  username: string | null;
+  port: number | null;
+}
+
+export type DesktopSshHostSource = "ssh-config" | "known-hosts";
+
+export interface DesktopDiscoveredSshHost extends DesktopSshEnvironmentTarget {
+  source: DesktopSshHostSource;
+}
+
+export interface DesktopSshEnvironmentBootstrap {
+  target: DesktopSshEnvironmentTarget;
+  httpBaseUrl: string;
+  wsBaseUrl: string;
+  pairingToken: string | null;
+  remotePort?: number;
+  remoteServerKind?: "external" | "managed";
+}
+
+export interface DesktopSshPasswordPromptRequest {
+  requestId: string;
+  destination: string;
+  username: string | null;
+  prompt: string;
+  expiresAt: string;
+}
+
 export interface PersistedSavedEnvironmentRecord {
   environmentId: EnvironmentId;
   label: string;
@@ -138,6 +179,7 @@ export interface PersistedSavedEnvironmentRecord {
   httpBaseUrl: string;
   createdAt: string;
   lastConnectedAt: string | null;
+  desktopSsh?: DesktopSshEnvironmentTarget;
 }
 
 export type DesktopServerExposureMode = "local-only" | "network-accessible";
@@ -146,6 +188,8 @@ export interface DesktopServerExposureState {
   mode: DesktopServerExposureMode;
   endpointUrl: string | null;
   advertisedHost: string | null;
+  tailscaleServeEnabled: boolean;
+  tailscaleServePort: number;
 }
 
 export interface PickFolderOptions {
@@ -164,8 +208,31 @@ 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>;
+  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>;
@@ -182,7 +249,7 @@ export interface DesktopBridge {
   installUpdate: () => Promise<DesktopUpdateActionResult>;
   onUpdateState: (listener: (state: DesktopUpdateState) => void) => () => void;
   getLogDir: () => Promise<string>;
-  listLogFiles: () => Promise<string[]>;
+  listLogFiles: () => Promise<readonly string[]>;
   readLogFile: (filename: string) => Promise<string>;
   openLogDir: () => Promise<void>;
 }
@@ -225,10 +292,18 @@ 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>;
     upsertKeybinding: (input: ServerUpsertKeybindingInput) => Promise<ServerUpsertKeybindingResult>;
     getSettings: () => Promise<ServerSettings>;
     updateSettings: (patch: ServerSettingsPatch) => Promise<ServerSettings>;
+    discoverSourceControl: () => Promise<SourceControlDiscoveryResult>;
   };
 }
 
@@ -237,7 +312,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.
  */
@@ -258,30 +333,39 @@ export interface EnvironmentApi {
   filesystem: {
     browse: (input: FilesystemBrowseInput) => Promise<FilesystemBrowseResult>;
   };
-  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>;
+  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;
   };
-  provider?: {
-    listModels: (input: ProviderListModelsInput) => Promise<ProviderListModelsResult>;
-    getUsage: (input: ProviderGetUsageInput) => Promise<ProviderUsageResult>;
+  git: {
+    resolvePullRequest: (input: GitPullRequestRefInput) => Promise<GitResolvePullRequestResult>;
+    preparePullRequestThread: (
+      input: GitPreparePullRequestThreadInput,
+    ) => Promise<GitPreparePullRequestThreadResult>;
   };
   orchestration: {
     dispatchCommand: (command: ClientOrchestrationCommand) => Promise<{ sequence: number }>;
diff --git a/packages/contracts/src/model.ts b/packages/contracts/src/model.ts
index b776b3a3d8e..cd8ab45a4bd 100644
--- a/packages/contracts/src/model.ts
+++ b/packages/contracts/src/model.ts
@@ -1,497 +1,159 @@
-import { Schema } from "effect";
+import { Effect, Schema, SchemaTransformation } from "effect";
 import { TrimmedNonEmptyString } from "./baseSchemas.ts";
-import type { ProviderKind } from "./orchestration.ts";
+import { ProviderDriverKind } from "./providerInstance.ts";
 
-export const CODEX_REASONING_EFFORT_OPTIONS = ["xhigh", "high", "medium", "low"] as const;
-export const CodexReasoningEffort = Schema.Literals(CODEX_REASONING_EFFORT_OPTIONS);
-export type CodexReasoningEffort = typeof CodexReasoningEffort.Type;
-export const CLAUDE_CODE_EFFORT_OPTIONS = [
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max",
-  "ultrathink",
-] as const;
-export const ClaudeCodeEffort = Schema.Literals(CLAUDE_CODE_EFFORT_OPTIONS);
-export type ClaudeCodeEffort = typeof ClaudeCodeEffort.Type;
-/**
- * Alias of ClaudeCodeEffort — upstream renamed this to ClaudeAgentEffort.
- * Both names are exported for backward compatibility with existing fork code
- * and newly merged upstream code.
- */
-export const ClaudeAgentEffort = ClaudeCodeEffort;
-export type ClaudeAgentEffort = ClaudeCodeEffort;
-export const CURSOR_REASONING_OPTIONS = ["low", "normal", "high", "xhigh"] as const;
-export const CursorReasoningOption = Schema.Literals(CURSOR_REASONING_OPTIONS);
-export type CursorReasoningOption = typeof CursorReasoningOption.Type;
-
-export type ProviderReasoningEffort =
-  | CodexReasoningEffort
-  | ClaudeCodeEffort
-  | CursorReasoningOption;
-
-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 CopilotModelOptions = Schema.Struct({
-  reasoningEffort: Schema.optional(Schema.Literals(CODEX_REASONING_EFFORT_OPTIONS)),
-});
-export type CopilotModelOptions = typeof CopilotModelOptions.Type;
+export const ProviderOptionDescriptorType = Schema.Literals(["select", "boolean"]);
+export type ProviderOptionDescriptorType = typeof ProviderOptionDescriptorType.Type;
 
-export const OpencodeModelOptions = Schema.Struct({
-  providerId: Schema.optional(Schema.String),
-  modelId: Schema.optional(Schema.String),
-  variant: Schema.optional(Schema.String),
-  reasoningEffort: Schema.optional(Schema.String),
-  agent: Schema.optional(Schema.String),
+export const ProviderOptionChoice = Schema.Struct({
+  id: TrimmedNonEmptyString,
+  label: TrimmedNonEmptyString,
+  description: Schema.optional(TrimmedNonEmptyString),
+  isDefault: Schema.optional(Schema.Boolean),
 });
-export type OpencodeModelOptions = typeof OpencodeModelOptions.Type;
-/**
- * Upstream's shorter-form OpenCode options schema. Kept as a type alias
- * over the fork's richer OpencodeModelOptions so upstream code that imports
- * `OpenCodeModelOptions` keeps compiling.
- */
-export const OpenCodeModelOptions = OpencodeModelOptions;
-export type OpenCodeModelOptions = OpencodeModelOptions;
+export type ProviderOptionChoice = typeof ProviderOptionChoice.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),
+const ProviderOptionDescriptorBase = {
+  id: TrimmedNonEmptyString,
+  label: TrimmedNonEmptyString,
+  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 ClaudeModelOptions = typeof ClaudeModelOptions.Type;
+export type SelectProviderOptionDescriptor = typeof SelectProviderOptionDescriptor.Type;
 
-export const CursorModelOptions = Schema.Struct({
-  reasoning: Schema.optional(Schema.Literals(CURSOR_REASONING_OPTIONS)),
-  fastMode: Schema.optional(Schema.Boolean),
-  thinking: Schema.optional(Schema.Boolean),
-  contextWindow: Schema.optional(Schema.String),
+export const BooleanProviderOptionDescriptor = Schema.Struct({
+  ...ProviderOptionDescriptorBase,
+  type: Schema.Literal("boolean"),
+  currentValue: Schema.optional(Schema.Boolean),
 });
-export type CursorModelOptions = typeof CursorModelOptions.Type;
+export type BooleanProviderOptionDescriptor = typeof BooleanProviderOptionDescriptor.Type;
 
-export const GeminiCliModelOptions = Schema.Struct({
-  thinkingBudget: Schema.optional(Schema.Number),
-});
-export type GeminiCliModelOptions = typeof GeminiCliModelOptions.Type;
+export const ProviderOptionDescriptor = Schema.Union([
+  SelectProviderOptionDescriptor,
+  BooleanProviderOptionDescriptor,
+]);
+export type ProviderOptionDescriptor = typeof ProviderOptionDescriptor.Type;
 
-export const AmpModelOptions = Schema.Struct({
-  mode: Schema.optional(Schema.Literals(["smart", "rush", "deep", "large"])),
-});
-export type AmpModelOptions = typeof AmpModelOptions.Type;
+export const ProviderOptionSelectionValue = Schema.Union([TrimmedNonEmptyString, Schema.Boolean]);
+export type ProviderOptionSelectionValue = typeof ProviderOptionSelectionValue.Type;
 
-export const KiloModelOptions = Schema.Struct({
-  providerId: Schema.optional(Schema.String),
-  modelId: Schema.optional(Schema.String),
-  variant: Schema.optional(Schema.String),
-  reasoningEffort: Schema.optional(Schema.String),
-  agent: Schema.optional(Schema.String),
+export const ProviderOptionSelection = Schema.Struct({
+  id: TrimmedNonEmptyString,
+  value: ProviderOptionSelectionValue,
 });
-export type KiloModelOptions = typeof KiloModelOptions.Type;
+export type ProviderOptionSelection = typeof ProviderOptionSelection.Type;
 
-export const ProviderModelOptions = Schema.Struct({
-  codex: Schema.optional(CodexModelOptions),
-  copilot: Schema.optional(CopilotModelOptions),
-  claudeAgent: Schema.optional(ClaudeModelOptions),
-  cursor: Schema.optional(CursorModelOptions),
-  opencode: Schema.optional(OpencodeModelOptions),
-  geminiCli: Schema.optional(GeminiCliModelOptions),
-  amp: Schema.optional(AmpModelOptions),
-  kilo: Schema.optional(KiloModelOptions),
-});
-export type ProviderModelOptions = typeof ProviderModelOptions.Type;
-
-export const EffortOption = Schema.Struct({
-  value: TrimmedNonEmptyString,
-  label: TrimmedNonEmptyString,
-  isDefault: Schema.optional(Schema.Boolean),
-});
-export type EffortOption = typeof EffortOption.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)),
+    }),
+  ),
+);
 
-export const ContextWindowOption = Schema.Struct({
-  value: TrimmedNonEmptyString,
-  label: TrimmedNonEmptyString,
-  isDefault: Schema.optional(Schema.Boolean),
-});
-export type ContextWindowOption = typeof ContextWindowOption.Type;
+/**
+ * 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) continue;
+    if (typeof rawValue === "string") {
+      const trimmed = rawValue.trim();
+      if (trimmed) 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),
-  variantOptions: Schema.optional(Schema.Array(EffortOption)),
-  agentOptions: Schema.optional(Schema.Array(EffortOption)),
+  optionDescriptors: Schema.optional(Schema.Array(ProviderOptionDescriptor)),
 });
 export type ModelCapabilities = typeof ModelCapabilities.Type;
 
-type ModelDefinition = {
-  readonly slug: string;
-  readonly name: string;
-  readonly pricingTier?: string;
-  readonly capabilities?: ModelCapabilities;
-};
+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");
 
-type CursorModelFamilyOption = {
-  readonly slug: string;
-  readonly name: string;
-};
-
-export const CURSOR_MODEL_FAMILY_OPTIONS = [
-  { slug: "auto", name: "Auto" },
-  { slug: "composer-1.5", name: "Composer 1.5" },
-  { slug: "composer-1", name: "Composer 1" },
-  { slug: "gpt-5.4-medium", name: "GPT-5.4" },
-  { slug: "gpt-5.4-medium-fast", name: "GPT-5.4 Fast" },
-  { slug: "gpt-5.4-high", name: "GPT-5.4 High" },
-  { slug: "gpt-5.4-high-fast", name: "GPT-5.4 High Fast" },
-  { slug: "gpt-5.4-xhigh", name: "GPT-5.4 Extra High" },
-  { slug: "gpt-5.4-xhigh-fast", name: "GPT-5.4 Extra High Fast" },
-  { slug: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
-  { slug: "gpt-5.3-codex-spark-preview", name: "GPT-5.3 Codex Spark" },
-  { slug: "gpt-5.2-codex", name: "GPT-5.2 Codex" },
-  { slug: "gpt-5.2", name: "GPT-5.2" },
-  { slug: "gpt-5.2-high", name: "GPT-5.2 High" },
-  { slug: "gpt-5.1-codex-max", name: "GPT-5.1 Codex Max" },
-  { slug: "gpt-5.1-codex-max-high", name: "GPT-5.1 Codex Max High" },
-  { slug: "gpt-5.1-high", name: "GPT-5.1 High" },
-  { slug: "gpt-5.1-codex-mini", name: "GPT-5.1 Codex Mini" },
-  { slug: "opus-4.6", name: "Claude 4.6 Opus" },
-  { slug: "opus-4.5", name: "Claude 4.5 Opus" },
-  { slug: "sonnet-4.6", name: "Claude 4.6 Sonnet" },
-  { slug: "sonnet-4.5", name: "Claude 4.5 Sonnet" },
-  { slug: "gemini-3.1-pro", name: "Gemini 3.1 Pro" },
-  { slug: "gemini-3-pro", name: "Gemini 3 Pro" },
-  { slug: "gemini-3-flash", name: "Gemini 3 Flash" },
-  { slug: "grok", name: "Grok" },
-  { slug: "kimi-k2.5", name: "Kimi K2.5" },
-] as const satisfies readonly CursorModelFamilyOption[];
-
-export type CursorModelFamily = (typeof CURSOR_MODEL_FAMILY_OPTIONS)[number]["slug"];
-
-/**
- * TODO: This should not be a static array, each provider
- * should return its own model list over the WS API.
- */
-export const MODEL_OPTIONS_BY_PROVIDER = {
-  codex: [
-    {
-      slug: "gpt-5.4",
-      name: "GPT-5.4",
-      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",
-      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",
-      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",
-      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",
-      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",
-      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: [],
-      },
-    },
-  ],
-  copilot: [
-    { slug: "gpt-5.4", name: "GPT-5.4" },
-    { slug: "claude-sonnet-4.6", name: "Claude Sonnet 4.6" },
-    { slug: "claude-sonnet-4.5", name: "Claude Sonnet 4.5" },
-    { slug: "claude-haiku-4.5", name: "Claude Haiku 4.5" },
-    { slug: "claude-opus-4.6", name: "Claude Opus 4.6" },
-    { slug: "claude-opus-4.6-fast", name: "Claude Opus 4.6 (fast mode)" },
-    { slug: "claude-opus-4.5", name: "Claude Opus 4.5" },
-    { slug: "claude-sonnet-4", name: "Claude Sonnet 4" },
-    { slug: "gemini-3-pro-preview", name: "Gemini 3 Pro (Preview)" },
-    { slug: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
-    { slug: "gpt-5.2-codex", name: "GPT-5.2 Codex" },
-    { slug: "gpt-5.2", name: "GPT-5.2" },
-    { slug: "gpt-5.1-codex-max", name: "GPT-5.1 Codex Max" },
-    { slug: "gpt-5.1-codex", name: "GPT-5.1 Codex" },
-    { slug: "gpt-5.1-codex-mini", name: "GPT-5.1 Codex Mini" },
-    { slug: "gpt-5.1", name: "GPT-5.1" },
-    { slug: "gpt-5-mini", name: "GPT-5 mini" },
-    { slug: "gpt-4.1", name: "GPT-4.1" },
-  ],
-  claudeAgent: [
-    {
-      slug: "claude-opus-4-7",
-      name: "Claude Opus 4.7",
-      capabilities: {
-        reasoningEffortLevels: [
-          { 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" },
-        ],
-        supportsFastMode: false,
-        supportsThinkingToggle: false,
-        contextWindowOptions: [
-          { value: "200k", label: "200k", isDefault: true },
-          { value: "1m", label: "1M" },
-        ],
-        promptInjectedEffortLevels: ["ultrathink"],
-      },
-    },
-    {
-      slug: "claude-opus-4-6",
-      name: "Claude Opus 4.6",
-      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: [
-          { value: "200k", label: "200k" },
-          { value: "1m", label: "1M", isDefault: true },
-        ],
-        promptInjectedEffortLevels: ["ultrathink"],
-      },
-    },
-    {
-      slug: "claude-opus-4-5",
-      name: "Claude Opus 4.5",
-      capabilities: {
-        reasoningEffortLevels: [
-          { value: "low", label: "Low" },
-          { value: "medium", label: "Medium" },
-          { value: "high", label: "High", isDefault: true },
-          { value: "max", label: "Max" },
-        ],
-        supportsFastMode: true,
-        supportsThinkingToggle: false,
-        contextWindowOptions: [],
-        promptInjectedEffortLevels: [],
-      },
-    },
-    {
-      slug: "claude-sonnet-4-6",
-      name: "Claude Sonnet 4.6",
-      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" },
-          { value: "1m", label: "1M", isDefault: true },
-        ],
-        promptInjectedEffortLevels: ["ultrathink"],
-      },
-    },
-    {
-      slug: "claude-haiku-4-5",
-      name: "Claude Haiku 4.5",
-      capabilities: {
-        reasoningEffortLevels: [],
-        supportsFastMode: false,
-        supportsThinkingToggle: true,
-        contextWindowOptions: [],
-        promptInjectedEffortLevels: [],
-      },
-    },
-  ],
-  cursor: [
-    { slug: "auto", name: "Auto" },
-    { slug: "composer-1.5", name: "Composer 1.5" },
-    { slug: "composer-1", name: "Composer 1" },
-    { slug: "gpt-5.3-codex-low", name: "GPT-5.3 Codex Low" },
-    { slug: "gpt-5.3-codex-low-fast", name: "GPT-5.3 Codex Low Fast" },
-    { slug: "gpt-5.3-codex", name: "GPT-5.3 Codex" },
-    { slug: "gpt-5.3-codex-fast", name: "GPT-5.3 Codex Fast" },
-    { slug: "gpt-5.3-codex-high", name: "GPT-5.3 Codex High" },
-    { slug: "gpt-5.3-codex-high-fast", name: "GPT-5.3 Codex High Fast" },
-    { slug: "gpt-5.3-codex-xhigh", name: "GPT-5.3 Codex Extra High" },
-    { slug: "gpt-5.3-codex-xhigh-fast", name: "GPT-5.3 Codex Extra High Fast" },
-    { slug: "gpt-5.2", name: "GPT-5.2" },
-    { slug: "gpt-5.3-codex-spark-preview", name: "GPT-5.3 Codex Spark" },
-    { slug: "gpt-5.2-codex-low", name: "GPT-5.2 Codex Low" },
-    { slug: "gpt-5.2-codex-low-fast", name: "GPT-5.2 Codex Low Fast" },
-    { slug: "gpt-5.2-codex", name: "GPT-5.2 Codex" },
-    { slug: "gpt-5.2-codex-fast", name: "GPT-5.2 Codex Fast" },
-    { slug: "gpt-5.2-codex-high", name: "GPT-5.2 Codex High" },
-    { slug: "gpt-5.2-codex-high-fast", name: "GPT-5.2 Codex High Fast" },
-    { slug: "gpt-5.2-codex-xhigh", name: "GPT-5.2 Codex Extra High" },
-    { slug: "gpt-5.2-codex-xhigh-fast", name: "GPT-5.2 Codex Extra High Fast" },
-    { slug: "gpt-5.1-codex-max", name: "GPT-5.1 Codex Max" },
-    { slug: "gpt-5.1-codex-max-high", name: "GPT-5.1 Codex Max High" },
-    { slug: "gpt-5.4-high", name: "GPT-5.4 High" },
-    { slug: "opus-4.6", name: "Claude 4.6 Opus" },
-    { slug: "opus-4.6-thinking", name: "Claude 4.6 Opus (Thinking)" },
-    { slug: "gpt-5.4-medium", name: "GPT-5.4" },
-    { slug: "gpt-5.4-medium-fast", name: "GPT-5.4 Fast" },
-    { slug: "gpt-5.4-high-fast", name: "GPT-5.4 High Fast" },
-    { slug: "gpt-5.4-xhigh", name: "GPT-5.4 Extra High" },
-    { slug: "gpt-5.4-xhigh-fast", name: "GPT-5.4 Extra High Fast" },
-    { slug: "opus-4.5", name: "Claude 4.5 Opus" },
-    { slug: "opus-4.5-thinking", name: "Claude 4.5 Opus (Thinking)" },
-    { slug: "sonnet-4.6", name: "Claude 4.6 Sonnet" },
-    { slug: "sonnet-4.6-thinking", name: "Claude 4.6 Sonnet (Thinking)" },
-    { slug: "gpt-5.2-high", name: "GPT-5.2 High" },
-    { slug: "gemini-3.1-pro", name: "Gemini 3.1 Pro" },
-    { slug: "grok", name: "Grok" },
-    { slug: "sonnet-4.5", name: "Claude 4.5 Sonnet" },
-    { slug: "sonnet-4.5-thinking", name: "Claude 4.5 Sonnet (Thinking)" },
-    { slug: "gpt-5.1-high", name: "GPT-5.1 High" },
-    { slug: "gemini-3-pro", name: "Gemini 3 Pro" },
-    { slug: "gemini-3-flash", name: "Gemini 3 Flash" },
-    { slug: "gpt-5.1-codex-mini", name: "GPT-5.1 Codex Mini" },
-    { slug: "kimi-k2.5", name: "Kimi K2.5" },
-  ],
-  opencode: [
-    { slug: "openai/gpt-5", name: "OpenAI / GPT-5" },
-    { slug: "openai/gpt-5-mini", name: "OpenAI / GPT-5 Mini" },
-    { slug: "anthropic/claude-opus-4-7", name: "Anthropic / Claude Opus 4.7" },
-    { slug: "anthropic/claude-sonnet-4-6", name: "Anthropic / Claude Sonnet 4.6" },
-    { slug: "anthropic/claude-opus-4-6", name: "Anthropic / Claude Opus 4.6" },
-    { slug: "anthropic/claude-opus-4-5", name: "Anthropic / Claude Opus 4.5" },
-    { slug: "google/gemini-2.5-pro", name: "Google / Gemini 2.5 Pro" },
-    { slug: "google/gemini-2.5-flash", name: "Google / Gemini 2.5 Flash" },
-  ],
-  geminiCli: [
-    { slug: "gemini-2.5-pro", name: "Gemini 2.5 Pro" },
-    { slug: "gemini-2.5-flash", name: "Gemini 2.5 Flash" },
-    { slug: "gemini-3-pro-preview", name: "Gemini 3 Pro" },
-    { slug: "gemini-3-flash-preview", name: "Gemini 3 Flash" },
-    { slug: "gemini-3.1-pro-preview", name: "Gemini 3.1 Pro" },
-  ],
-  amp: [
-    { slug: "smart", name: "Smart (Opus 4.6)" },
-    { slug: "rush", name: "Rush (Fast)" },
-    { slug: "deep", name: "Deep (GPT-5.3 Codex)" },
-    { slug: "large", name: "Large" },
-  ],
-  kilo: [
-    { slug: "openai/gpt-5", name: "OpenAI / GPT-5" },
-    { slug: "openai/gpt-5-mini", name: "OpenAI / GPT-5 Mini" },
-    { slug: "anthropic/claude-sonnet-4-6", name: "Anthropic / Claude Sonnet 4.6" },
-    { slug: "anthropic/claude-opus-4-6", name: "Anthropic / Claude Opus 4.6" },
-    { slug: "google/gemini-2.5-pro", name: "Google / Gemini 2.5 Pro" },
-    { slug: "google/gemini-2.5-flash", name: "Google / Gemini 2.5 Flash" },
-  ],
-} as const satisfies Record<ProviderKind, readonly ModelDefinition[]>;
-export type ModelOptionsByProvider = typeof MODEL_OPTIONS_BY_PROVIDER;
-
-type BuiltInModelSlug = (typeof MODEL_OPTIONS_BY_PROVIDER)[ProviderKind][number]["slug"];
-export type ModelSlug = BuiltInModelSlug | (string & {});
-export type CursorModelSlug = (typeof MODEL_OPTIONS_BY_PROVIDER)["cursor"][number]["slug"];
+export const DEFAULT_MODEL = "gpt-5.4";
+export const DEFAULT_GIT_TEXT_GENERATION_MODEL = "gpt-5.4-mini";
 
-export const DEFAULT_MODEL_BY_PROVIDER: Record<ProviderKind, ModelSlug> = {
-  codex: "gpt-5.4",
-  copilot: "claude-sonnet-4.6",
-  claudeAgent: "claude-sonnet-4-6",
-  cursor: "opus-4.6-thinking",
-  opencode: "openai/gpt-5",
-  geminiCli: "gemini-2.5-pro",
-  amp: "smart",
-  kilo: "openai/gpt-5",
-} as const satisfies Record<ProviderKind, ModelSlug>;
+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",
+};
 
-export const DEFAULT_MODEL = DEFAULT_MODEL_BY_PROVIDER.codex;
-export const DEFAULT_GIT_TEXT_GENERATION_MODEL = "gpt-5.4-mini" as const;
-export const DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER = {
-  ...DEFAULT_MODEL_BY_PROVIDER,
-  codex: "gpt-5.4-mini",
-  claudeAgent: "claude-haiku-4-5",
-} as const satisfies Record<ProviderKind, ModelSlug>;
+/** Per-provider text generation model defaults. */
+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",
@@ -499,31 +161,13 @@ 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",
   },
-  copilot: {
-    "4.1": "gpt-4.1",
-    "5.4": "gpt-5.4",
-    "5-mini": "gpt-5-mini",
-    "5.1": "gpt-5.1",
-    "5.1-codex": "gpt-5.1-codex",
-    "5.1-max": "gpt-5.1-codex-max",
-    "5.1-mini": "gpt-5.1-codex-mini",
-    "5.2": "gpt-5.2",
-    "5.2-codex": "gpt-5.2-codex",
-    "5.3": "gpt-5.3-codex",
-    haiku: "claude-haiku-4.5",
-    sonnet: "claude-sonnet-4.6",
-    opus: "claude-opus-4.6",
-    gemini: "gemini-3-pro-preview",
-  },
-  claudeAgent: {
+  [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",
-    "opus-4.5": "claude-opus-4-5",
-    "claude-opus-4.5": "claude-opus-4-5",
     sonnet: "claude-sonnet-4-6",
     "sonnet-4.6": "claude-sonnet-4-6",
     "claude-sonnet-4.6": "claude-sonnet-4-6",
@@ -533,136 +177,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: {
-    composer: "composer-1.5",
+  [CURSOR_DRIVER_KIND]: {
+    composer: "composer-2",
     "composer-1.5": "composer-1.5",
-    "composer-1": "composer-1",
-    "5.4": "gpt-5.4-medium",
-    "gpt-5.4": "gpt-5.4-medium",
-    "5.2": "gpt-5.2",
-    "5.2-codex": "gpt-5.2-codex",
-    "gpt-5.2-codex": "gpt-5.2-codex",
-    "5.1-max": "gpt-5.1-codex-max",
-    "gpt-5.1-codex-max": "gpt-5.1-codex-max",
-    "gpt-5.3-codex": "gpt-5.3-codex",
-    "gpt-5.3-codex-spark": "gpt-5.3-codex-spark-preview",
-    "gemini-3.1": "gemini-3.1-pro",
-    "gemini-3.1-pro": "gemini-3.1-pro",
-    "claude-4.6-sonnet-thinking": "sonnet-4.6-thinking",
-    "claude-4.5-sonnet-thinking": "sonnet-4.5-thinking",
-    "claude-4.6-opus-thinking": "opus-4.6-thinking",
-    "claude-4.5-opus-thinking": "opus-4.5-thinking",
-    "sonnet-4.5-thinking": "sonnet-4.5-thinking",
-    "sonnet-4.6-thinking": "sonnet-4.6-thinking",
-    "opus-4.6-thinking": "opus-4.6-thinking",
-    "opus-4.5-thinking": "opus-4.5-thinking",
-  },
-  opencode: {
-    "gpt-5": "openai/gpt-5",
-    "gpt-5-mini": "openai/gpt-5-mini",
-    "claude-opus-4-7": "anthropic/claude-opus-4-7",
-    "claude-sonnet-4-6": "anthropic/claude-sonnet-4-6",
-    "claude-opus-4-6": "anthropic/claude-opus-4-6",
-    "claude-opus-4-5": "anthropic/claude-opus-4-5",
-    "gemini-2.5-pro": "google/gemini-2.5-pro",
-    "gemini-2.5-flash": "google/gemini-2.5-flash",
-  },
-  kilo: {
-    "gpt-5": "openai/gpt-5",
-    "gpt-5-mini": "openai/gpt-5-mini",
-    "claude-sonnet-4-6": "anthropic/claude-sonnet-4-6",
-    "claude-opus-4-6": "anthropic/claude-opus-4-6",
-    "gemini-2.5-pro": "google/gemini-2.5-pro",
-    "gemini-2.5-flash": "google/gemini-2.5-flash",
-  },
-  geminiCli: {
-    gemini: "gemini-2.5-pro",
-    "2.5-pro": "gemini-2.5-pro",
-    "2.5-flash": "gemini-2.5-flash",
-    "3-pro": "gemini-3-pro-preview",
-    "3-flash": "gemini-3-flash-preview",
-    "3.1-pro": "gemini-3.1-pro-preview",
-    // Compatibility aliases for old slugs without -preview suffix
-    "gemini-3-pro": "gemini-3-pro-preview",
-    "gemini-3-flash": "gemini-3-flash-preview",
-    "gemini-3.1-pro": "gemini-3.1-pro-preview",
-  },
-  amp: {
-    opus: "smart",
-    fast: "rush",
-    codex: "deep",
-    large: "large",
+    "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]: {},
 };
 
-export const REASONING_EFFORT_OPTIONS_BY_PROVIDER = {
-  codex: CODEX_REASONING_EFFORT_OPTIONS,
-  copilot: [],
-  claudeAgent: CLAUDE_CODE_EFFORT_OPTIONS,
-  cursor: [],
-  opencode: [],
-  kilo: [],
-  geminiCli: [],
-  amp: [],
-} as const satisfies Record<ProviderKind, readonly ProviderReasoningEffort[]>;
-
-export const DEFAULT_REASONING_EFFORT_BY_PROVIDER = {
-  codex: "high",
-  copilot: null,
-  claudeAgent: "high",
-  cursor: null,
-  opencode: null,
-  kilo: null,
-  geminiCli: null,
-  amp: null,
-} as const satisfies Record<ProviderKind, ProviderReasoningEffort | null>;
-
-export const CLAUDE_CODE_EFFORT_OPTIONS_BY_PROVIDER = {
-  codex: [],
-  copilot: [],
-  claudeAgent: CLAUDE_CODE_EFFORT_OPTIONS,
-  cursor: [],
-  opencode: [],
-  kilo: [],
-  geminiCli: [],
-  amp: [],
-} as const satisfies Record<ProviderKind, readonly ClaudeCodeEffort[]>;
-
-export const DEFAULT_CLAUDE_CODE_EFFORT_BY_PROVIDER = {
-  codex: null,
-  copilot: null,
-  claudeAgent: "high",
-  cursor: null,
-  opencode: null,
-  kilo: null,
-  geminiCli: null,
-  amp: null,
-} as const satisfies Record<ProviderKind, ClaudeCodeEffort | null>;
-
-// ── Model capabilities index ──────────────────────────────────────────
-
-export const MODEL_CAPABILITIES_INDEX = Object.fromEntries(
-  Object.entries(MODEL_OPTIONS_BY_PROVIDER).map(([provider, models]) => [
-    provider,
-    Object.fromEntries(
-      (models as readonly ModelDefinition[])
-        .filter(
-          (m): m is ModelDefinition & { capabilities: ModelCapabilities } => m.capabilities != null,
-        )
-        .map((m) => [m.slug, m.capabilities]),
-    ),
-  ]),
-) as unknown as Record<ProviderKind, Record<string, ModelCapabilities>>;
-
 // ── Provider display names ────────────────────────────────────────────
 
-export const PROVIDER_DISPLAY_NAMES: Record<ProviderKind, string> = {
-  codex: "Codex",
-  copilot: "Copilot",
-  claudeAgent: "Claude",
-  cursor: "Cursor",
-  opencode: "OpenCode",
-  geminiCli: "Gemini CLI",
-  amp: "Amp",
-  kilo: "Kilo",
+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 3b89e11afd0..605d0375342 100644
--- a/packages/contracts/src/orchestration.test.ts
+++ b/packages/contracts/src/orchestration.test.ts
@@ -5,6 +5,10 @@ import { Effect, Schema } from "effect";
 import {
   DEFAULT_PROVIDER_INTERACTION_MODE,
   DEFAULT_RUNTIME_MODE,
+  ModelSelection,
+  OrchestrationCommand,
+  OrchestrationEvent,
+  OrchestrationGetFullThreadDiffInput,
   OrchestrationGetTurnDiffInput,
   OrchestrationLatestTurn,
   ProjectCreatedPayload,
@@ -18,8 +22,10 @@ import {
   ThreadTurnDiff,
   ThreadTurnStartRequestedPayload,
 } 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);
@@ -31,7 +37,16 @@ const decodeThreadTurnStartRequestedPayload = Schema.decodeUnknownEffect(
 const decodeOrchestrationLatestTurn = Schema.decodeUnknownEffect(OrchestrationLatestTurn);
 const decodeOrchestrationProposedPlan = Schema.decodeUnknownEffect(OrchestrationProposedPlan);
 const decodeOrchestrationSession = Schema.decodeUnknownEffect(OrchestrationSession);
+
+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);
 const decodeThreadMetaUpdatedPayload = Schema.decodeUnknownEffect(ThreadMetaUpdatedPayload);
 
 it.effect("parses turn diff input when fromTurnCount <= toTurnCount", () =>
@@ -46,6 +61,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(
@@ -93,7 +131,7 @@ it.effect("trims branded ids and command string fields at decode boundaries", ()
     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",
     });
   }),
@@ -129,7 +167,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");
   }),
 );
 
@@ -143,7 +181,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");
   }),
 );
 
@@ -202,7 +240,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);
   }),
@@ -267,7 +305,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");
   }),
 );
 
@@ -281,7 +319,67 @@ 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");
+  }),
+);
+
+it.effect("decodes thread archive and unarchive commands", () =>
+  Effect.gen(function* () {
+    const archive = yield* decodeOrchestrationCommand({
+      type: "thread.archive",
+      commandId: "cmd-archive-1",
+      threadId: "thread-1",
+    });
+    const unarchive = yield* decodeOrchestrationCommand({
+      type: "thread.unarchive",
+      commandId: "cmd-unarchive-1",
+      threadId: "thread-1",
+    });
+
+    assert.strictEqual(archive.type, "thread.archive");
+    assert.strictEqual(unarchive.type, "thread.unarchive");
+  }),
+);
+
+it.effect("decodes thread archived and unarchived events", () =>
+  Effect.gen(function* () {
+    const archived = yield* decodeOrchestrationEvent({
+      sequence: 1,
+      eventId: "event-archive-1",
+      aggregateKind: "thread",
+      aggregateId: "thread-1",
+      type: "thread.archived",
+      occurredAt: "2026-01-01T00:00:00.000Z",
+      commandId: "cmd-archive-1",
+      causationEventId: null,
+      correlationId: "cmd-archive-1",
+      metadata: {},
+      payload: {
+        threadId: "thread-1",
+        archivedAt: "2026-01-01T00:00:00.000Z",
+        updatedAt: "2026-01-01T00:00:00.000Z",
+      },
+    });
+    const unarchived = yield* decodeOrchestrationEvent({
+      sequence: 2,
+      eventId: "event-unarchive-1",
+      aggregateKind: "thread",
+      aggregateId: "thread-1",
+      type: "thread.unarchived",
+      occurredAt: "2026-01-02T00:00:00.000Z",
+      commandId: "cmd-unarchive-1",
+      causationEventId: null,
+      correlationId: "cmd-unarchive-1",
+      metadata: {},
+      payload: {
+        threadId: "thread-1",
+        updatedAt: "2026-01-02T00:00:00.000Z",
+      },
+    });
+
+    assert.strictEqual(archived.type, "thread.archived");
+    assert.strictEqual(archived.payload.archivedAt, "2026-01-01T00:00:00.000Z");
+    assert.strictEqual(unarchived.type, "thread.unarchived");
   }),
 );
 
@@ -300,39 +398,113 @@ 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.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.strictEqual(parsed.modelSelection?.provider, "codex");
-    assert.strictEqual(parsed.modelSelection?.options?.reasoningEffort, "high");
-    assert.strictEqual(parsed.modelSelection?.options?.fastMode, true);
+
+    assert.deepStrictEqual(parsed.defaultModelSelection?.options, [
+      { id: "reasoningEffort", value: "low" },
+    ]);
   }),
 );
 
-it.effect("accepts cursor provider in thread.turn.start", () =>
+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* Schema.encodeEffect(ThreadCreatedPayload)(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({
       type: "thread.turn.start",
-      commandId: "cmd-turn-cursor",
+      commandId: "cmd-turn-title-seed",
       threadId: "thread-1",
       message: {
-        messageId: "msg-3",
+        messageId: "msg-title-seed",
         role: "user",
         text: "hello",
         attachments: [],
       },
-      modelSelection: {
-        provider: "cursor",
-        model: "composer-1.5",
-      },
+      titleSeed: "Investigate reconnect failures",
       createdAt: "2026-01-01T00:00:00.000Z",
     });
-    assert.strictEqual(parsed.modelSelection?.provider, "cursor");
-    assert.strictEqual(parsed.interactionMode, DEFAULT_PROVIDER_INTERACTION_MODE);
+    assert.strictEqual(parsed.titleSeed, "Investigate reconnect failures");
   }),
 );
 
@@ -395,6 +567,18 @@ it.effect("decodes thread.turn-start-requested source proposed plan metadata whe
   }),
 );
 
+it.effect("decodes thread.turn-start-requested title seed when present", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decodeThreadTurnStartRequestedPayload({
+      threadId: "thread-2",
+      messageId: "msg-2",
+      titleSeed: "Investigate reconnect failures",
+      createdAt: "2026-01-01T00:00:00.000Z",
+    });
+    assert.strictEqual(parsed.titleSeed, "Investigate reconnect failures");
+  }),
+);
+
 it.effect("decodes latest turn source proposed plan metadata when present", () =>
   Effect.gen(function* () {
     const parsed = yield* decodeOrchestrationLatestTurn({
@@ -461,3 +645,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 3e9feead5bc..047ef9e5cd9 100644
--- a/packages/contracts/src/orchestration.ts
+++ b/packages/contracts/src/orchestration.ts
@@ -1,14 +1,5 @@
-import { Effect, Option, Schema, SchemaIssue, Struct } from "effect";
-import {
-  AmpModelOptions,
-  ClaudeModelOptions,
-  CodexModelOptions,
-  CopilotModelOptions,
-  CursorModelOptions,
-  GeminiCliModelOptions,
-  KiloModelOptions,
-  OpencodeModelOptions,
-} from "./model.ts";
+import { Effect, Option, Schema, SchemaIssue, SchemaTransformation, Struct } from "effect";
+import { ProviderOptionSelections } from "./model.ts";
 import { RepositoryIdentity } from "./environment.ts";
 import {
   ApprovalRequestId,
@@ -18,13 +9,13 @@ import {
   IsoDateTime,
   MessageId,
   NonNegativeInt,
-  PositiveInt,
   ProjectId,
   ProviderItemId,
   ThreadId,
   TrimmedNonEmptyString,
   TurnId,
 } from "./baseSchemas.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
 
 export const ORCHESTRATION_WS_METHODS = {
   dispatchCommand: "orchestration.dispatchCommand",
@@ -35,17 +26,6 @@ export const ORCHESTRATION_WS_METHODS = {
   subscribeThread: "orchestration.subscribeThread",
 } as const;
 
-export const ProviderKind = Schema.Literals([
-  "codex",
-  "copilot",
-  "claudeAgent",
-  "cursor",
-  "opencode",
-  "geminiCli",
-  "amp",
-  "kilo",
-]);
-export type ProviderKind = typeof ProviderKind.Type;
 export const ProviderApprovalPolicy = Schema.Literals([
   "untrusted",
   "on-failure",
@@ -60,181 +40,74 @@ 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"),
-  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 CopilotModelSelection = Schema.Struct({
-  provider: Schema.Literal("copilot"),
-  model: TrimmedNonEmptyString,
-  options: Schema.optionalKey(CopilotModelOptions),
-});
-export type CopilotModelSelection = typeof CopilotModelSelection.Type;
-
-export const CursorModelSelection = Schema.Struct({
-  provider: Schema.Literal("cursor"),
-  model: TrimmedNonEmptyString,
-  options: Schema.optionalKey(CursorModelOptions),
-});
-export type CursorModelSelection = typeof CursorModelSelection.Type;
-
-export const OpencodeModelSelection = Schema.Struct({
-  provider: Schema.Literal("opencode"),
-  model: TrimmedNonEmptyString,
-  options: Schema.optionalKey(OpencodeModelOptions),
-});
-export type OpencodeModelSelection = typeof OpencodeModelSelection.Type;
 /**
- * Upstream-compatible alias so upstream-authored code that imports
- * `OpenCodeModelSelection` still resolves against the fork's richer schema.
+ * `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.
  */
-export const OpenCodeModelSelection = OpencodeModelSelection;
-export type OpenCodeModelSelection = OpencodeModelSelection;
-
-export const GeminiCliModelSelection = Schema.Struct({
-  provider: Schema.Literal("geminiCli"),
-  model: TrimmedNonEmptyString,
-  options: Schema.optionalKey(GeminiCliModelOptions),
-});
-export type GeminiCliModelSelection = typeof GeminiCliModelSelection.Type;
-
-export const AmpModelSelection = Schema.Struct({
-  provider: Schema.Literal("amp"),
+const ModelSelectionWire = Schema.Struct({
+  instanceId: ProviderInstanceId,
   model: TrimmedNonEmptyString,
-  options: Schema.optionalKey(AmpModelOptions),
-});
-export type AmpModelSelection = typeof AmpModelSelection.Type;
-
-export const KiloModelSelection = Schema.Struct({
-  provider: Schema.Literal("kilo"),
-  model: TrimmedNonEmptyString,
-  options: Schema.optionalKey(KiloModelOptions),
-});
-export type KiloModelSelection = typeof KiloModelSelection.Type;
-
-export const ModelSelection = Schema.Union([
-  CodexModelSelection,
-  ClaudeModelSelection,
-  CopilotModelSelection,
-  CursorModelSelection,
-  OpencodeModelSelection,
-  GeminiCliModelSelection,
-  AmpModelSelection,
-  KiloModelSelection,
-]);
+  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 CodexProviderStartOptions = Schema.Struct({
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-  homePath: Schema.optional(TrimmedNonEmptyString),
-});
-export type CodexProviderStartOptions = typeof CodexProviderStartOptions.Type;
-
-export const CopilotProviderStartOptions = Schema.Struct({
-  cliPath: Schema.optional(TrimmedNonEmptyString),
-  configDir: Schema.optional(TrimmedNonEmptyString),
-});
-export type CopilotProviderStartOptions = typeof CopilotProviderStartOptions.Type;
-
-export const ClaudeProviderStartOptions = Schema.Struct({
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-  permissionMode: Schema.optional(TrimmedNonEmptyString),
-  maxThinkingTokens: Schema.optional(NonNegativeInt),
-});
-export type ClaudeProviderStartOptions = typeof ClaudeProviderStartOptions.Type;
-
-export const CursorProviderStartOptions = Schema.Struct({
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-});
-export type CursorProviderStartOptions = typeof CursorProviderStartOptions.Type;
-
-export const GeminiCliProviderStartOptions = Schema.Struct({
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-});
-export type GeminiCliProviderStartOptions = typeof GeminiCliProviderStartOptions.Type;
-
-export const AmpProviderStartOptions = Schema.Struct({
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-});
-export type AmpProviderStartOptions = typeof AmpProviderStartOptions.Type;
-
-export const OpencodeProviderStartOptions = Schema.Struct({
-  serverUrl: Schema.optional(TrimmedNonEmptyString),
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-  hostname: Schema.optional(TrimmedNonEmptyString),
-  port: Schema.optional(PositiveInt),
-  workspace: Schema.optional(TrimmedNonEmptyString),
-  username: Schema.optional(TrimmedNonEmptyString),
-  password: Schema.optional(TrimmedNonEmptyString),
-});
-export type OpencodeProviderStartOptions = typeof OpencodeProviderStartOptions.Type;
-
-export const KiloProviderStartOptions = Schema.Struct({
-  serverUrl: Schema.optional(TrimmedNonEmptyString),
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-  hostname: Schema.optional(TrimmedNonEmptyString),
-  port: Schema.optional(PositiveInt),
-  workspace: Schema.optional(TrimmedNonEmptyString),
-  username: Schema.optional(TrimmedNonEmptyString),
-  password: Schema.optional(TrimmedNonEmptyString),
-});
-export type KiloProviderStartOptions = typeof KiloProviderStartOptions.Type;
-
-export const ProviderStartOptions = Schema.Struct({
-  codex: Schema.optional(CodexProviderStartOptions),
-  copilot: Schema.optional(CopilotProviderStartOptions),
-  claudeAgent: Schema.optional(ClaudeProviderStartOptions),
-  cursor: Schema.optional(CursorProviderStartOptions),
-  amp: Schema.optional(AmpProviderStartOptions),
-  geminiCli: Schema.optional(GeminiCliProviderStartOptions),
-  opencode: Schema.optional(OpencodeProviderStartOptions),
-  kilo: Schema.optional(KiloProviderStartOptions),
-});
-export type ProviderStartOptions = typeof ProviderStartOptions.Type;
-
-/** Opencode options with credentials stripped for safe persistence in events. */
-const OpencodeProviderStartOptionsRedacted = Schema.Struct({
-  serverUrl: Schema.optional(TrimmedNonEmptyString),
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-  hostname: Schema.optional(TrimmedNonEmptyString),
-  port: Schema.optional(PositiveInt),
-  workspace: Schema.optional(TrimmedNonEmptyString),
-});
-
-/** Kilo options with credentials stripped for safe persistence in events. */
-const KiloProviderStartOptionsRedacted = Schema.Struct({
-  serverUrl: Schema.optional(TrimmedNonEmptyString),
-  binaryPath: Schema.optional(TrimmedNonEmptyString),
-  hostname: Schema.optional(TrimmedNonEmptyString),
-  port: Schema.optional(PositiveInt),
-  workspace: Schema.optional(TrimmedNonEmptyString),
-});
-
-/** ProviderStartOptions without sensitive fields (username/password). Use in persisted events. */
-export const ProviderStartOptionsRedacted = Schema.Struct({
-  codex: Schema.optional(CodexProviderStartOptions),
-  copilot: Schema.optional(CopilotProviderStartOptions),
-  claudeAgent: Schema.optional(ClaudeProviderStartOptions),
-  cursor: Schema.optional(CursorProviderStartOptions),
-  amp: Schema.optional(AmpProviderStartOptions),
-  geminiCli: Schema.optional(GeminiCliProviderStartOptions),
-  opencode: Schema.optional(OpencodeProviderStartOptionsRedacted),
-  kilo: Schema.optional(KiloProviderStartOptionsRedacted),
-});
-export type ProviderStartOptionsRedacted = typeof ProviderStartOptionsRedacted.Type;
-
 export const RuntimeMode = Schema.Literals([
   "approval-required",
   "auto-accept-edits",
@@ -382,6 +255,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),
@@ -1297,7 +1171,10 @@ export const DispatchResult = Schema.Struct({
 export type DispatchResult = typeof DispatchResult.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;
@@ -1308,6 +1185,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;
 
diff --git a/packages/contracts/src/provider.test.ts b/packages/contracts/src/provider.test.ts
index 854514b65dd..67318d0e33f 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 { ProviderSendTurnInput, ProviderSessionStartInput } from "./provider.ts";
+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", () => {
@@ -41,18 +52,6 @@ describe("ProviderSessionStartInput", () => {
     ).toThrow();
   });
 
-  it("accepts copilot provider payloads", () => {
-    const parsed = decodeProviderSessionStartInput({
-      threadId: "thread-1",
-      provider: "copilot",
-      cwd: "/tmp/workspace",
-      model: "claude-sonnet-4.6",
-      runtimeMode: "full-access",
-    });
-    expect(parsed.provider).toBe("copilot");
-    expect(parsed.runtimeMode).toBe("full-access");
-  });
-
   it("accepts claude runtime knobs", () => {
     const parsed = decodeProviderSessionStartInput({
       threadId: "thread-1",
@@ -61,67 +60,57 @@ 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 payloads with model selection", () => {
+  it("accepts cursor provider", () => {
     const parsed = decodeProviderSessionStartInput({
       threadId: "thread-1",
+      provider: "cursor",
       cwd: "/tmp/workspace",
+      runtimeMode: "full-access",
       modelSelection: {
         provider: "cursor",
-        model: "composer-1.5",
-        options: {
-          thinking: true,
-        },
+        model: "composer-2",
+        options: [{ id: "fastMode", value: true }],
       },
-      runtimeMode: "approval-required",
     });
-    expect(parsed.modelSelection?.provider).toBe("cursor");
-    expect(parsed.modelSelection?.model).toBe("composer-1.5");
-    expect(
-      parsed.modelSelection?.provider === "cursor"
-        ? parsed.modelSelection.options?.thinking
-        : undefined,
-    ).toBe(true);
-    expect(parsed.runtimeMode).toBe("approval-required");
+    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 cursor provider", () => {
+  it("accepts fork-provided driver kinds as branded slugs", () => {
     const parsed = decodeProviderSessionStartInput({
       threadId: "thread-1",
-      provider: "cursor",
+      provider: "ollama",
+      providerInstanceId: "ollama_local",
       cwd: "/tmp/workspace",
       runtimeMode: "full-access",
       modelSelection: {
-        provider: "cursor",
-        model: "composer-2",
-        options: { fastMode: true },
+        instanceId: "ollama_local",
+        model: "llama3.3",
       },
     });
-    expect(parsed.provider).toBe("cursor");
-    expect(parsed.modelSelection?.provider).toBe("cursor");
-    expect(parsed.modelSelection?.model).toBe("composer-2");
-    if (parsed.modelSelection?.provider === "cursor") {
-      expect(parsed.modelSelection.options?.fastMode).toBe(true);
-    }
+
+    expect(parsed.provider).toBe("ollama");
+    expect(parsed.providerInstanceId).toBe("ollama_local");
+    expect(parsed.modelSelection?.instanceId).toBe("ollama_local");
   });
 });
 
@@ -132,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", () => {
@@ -154,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 b5ad72a0f95..ff479190559 100644
--- a/packages/contracts/src/provider.ts
+++ b/packages/contracts/src/provider.ts
@@ -16,12 +16,12 @@ import {
   ProviderApprovalDecision,
   ProviderApprovalPolicy,
   ProviderInteractionMode,
-  ProviderKind,
   ProviderRequestKind,
   ProviderSandboxMode,
   ProviderUserInputAnswers,
   RuntimeMode,
 } 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),
@@ -106,7 +112,7 @@ export type ProviderRespondToUserInputInput = typeof ProviderRespondToUserInputI
 // ── Provider model discovery ────────────────────────────────────────
 
 export const ProviderListModelsInput = Schema.Struct({
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 });
 export type ProviderListModelsInput = typeof ProviderListModelsInput.Type;
 
@@ -124,7 +130,7 @@ export interface ProviderListModelsResult {
 // ── Provider usage / quota ──────────────────────────────────────────
 
 export const ProviderGetUsageInput = Schema.Struct({
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
 });
 export type ProviderGetUsageInput = typeof ProviderGetUsageInput.Type;
 
@@ -164,7 +170,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..9139001cf3b
--- /dev/null
+++ b/packages/contracts/src/providerInstance.test.ts
@@ -0,0 +1,192 @@
+import { describe, expect, it } from "vitest";
+import { Schema } from "effect";
+
+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("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..d5bb25f7729
--- /dev/null
+++ b/packages/contracts/src/providerInstance.ts
@@ -0,0 +1,148 @@
+/**
+ * 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 { Effect, Schema } from "effect";
+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 7b822a2860b..42c0117935b 100644
--- a/packages/contracts/src/providerRuntime.test.ts
+++ b/packages/contracts/src/providerRuntime.test.ts
@@ -6,6 +6,23 @@ 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 beaa5457405..3116812cb7b 100644
--- a/packages/contracts/src/providerRuntime.ts
+++ b/packages/contracts/src/providerRuntime.ts
@@ -12,7 +12,7 @@ import {
   TrimmedNonEmptyString,
   TurnId,
 } from "./baseSchemas.ts";
-import { ProviderKind } from "./orchestration.ts";
+import { ProviderInstanceId, ProviderDriverKind } from "./providerInstance.ts";
 
 const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
 const UnknownRecordSchema = Schema.Record(Schema.String, Schema.Unknown);
@@ -260,7 +260,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..70a20d7aeb4
--- /dev/null
+++ b/packages/contracts/src/remoteAccess.ts
@@ -0,0 +1,68 @@
+import { Schema } from "effect";
+
+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 5dec716a725..4167bd0a763 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -11,28 +11,28 @@ import {
 } 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,
+  VcsStatusInput,
+  VcsStatusResult,
+  VcsStatusStreamEvent,
 } from "./git.ts";
 import { KeybindingsConfigError } from "./keybindings.ts";
 import {
@@ -48,6 +48,7 @@ import {
   OrchestrationReplayEventsInput,
   OrchestrationRpcSchemas,
 } from "./orchestration.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
 import {
   ProjectSearchEntriesError,
   ProjectSearchEntriesInput,
@@ -76,6 +77,17 @@ import {
   ServerUpsertKeybindingResult,
 } 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
@@ -91,16 +103,18 @@ export const WS_METHODS = {
   // Filesystem methods
   filesystemBrowse: "filesystem.browse",
 
-  // Git methods
-  gitPull: "git.pull",
-  gitRefreshStatus: "git.refreshStatus",
+  // 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",
 
@@ -118,9 +132,15 @@ export const WS_METHODS = {
   serverUpsertKeybinding: "server.upsertKeybinding",
   serverGetSettings: "server.getSettings",
   serverUpdateSettings: "server.updateSettings",
+  serverDiscoverSourceControl: "server.discoverSourceControl",
+
+  // Source control methods
+  sourceControlLookupRepository: "sourceControl.lookupRepository",
+  sourceControlCloneRepository: "sourceControl.cloneRepository",
+  sourceControlPublishRepository: "sourceControl.publishRepository",
 
   // Streaming subscriptions
-  subscribeGitStatus: "subscribeGitStatus",
+  subscribeVcsStatus: "subscribeVcsStatus",
   subscribeTerminalEvents: "subscribeTerminalEvents",
   subscribeServerConfig: "subscribeServerConfig",
   subscribeServerLifecycle: "subscribeServerLifecycle",
@@ -140,7 +160,15 @@ 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,
 });
 
@@ -156,6 +184,35 @@ 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 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,
@@ -179,22 +236,22 @@ export const WsFilesystemBrowseRpc = Rpc.make(WS_METHODS.filesystemBrowse, {
   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,
 });
 
@@ -217,38 +274,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, {
@@ -361,22 +418,26 @@ export const WsRpcGroup = RpcGroup.make(
   WsServerUpsertKeybindingRpc,
   WsServerGetSettingsRpc,
   WsServerUpdateSettingsRpc,
+  WsServerDiscoverSourceControlRpc,
+  WsSourceControlLookupRepositoryRpc,
+  WsSourceControlCloneRepositoryRpc,
+  WsSourceControlPublishRepositoryRpc,
   WsProjectsSearchEntriesRpc,
   WsProjectsWriteFileRpc,
   WsShellOpenInEditorRpc,
   WsFilesystemBrowseRpc,
-  WsSubscribeGitStatusRpc,
-  WsGitPullRpc,
-  WsGitRefreshStatusRpc,
+  WsSubscribeVcsStatusRpc,
+  WsVcsPullRpc,
+  WsVcsRefreshStatusRpc,
   WsGitRunStackedActionRpc,
   WsGitResolvePullRequestRpc,
   WsGitPreparePullRequestThreadRpc,
-  WsGitListBranchesRpc,
-  WsGitCreateWorktreeRpc,
-  WsGitRemoveWorktreeRpc,
-  WsGitCreateBranchRpc,
-  WsGitCheckoutRpc,
-  WsGitInitRpc,
+  WsVcsListRefsRpc,
+  WsVcsCreateWorktreeRpc,
+  WsVcsRemoveWorktreeRpc,
+  WsVcsCreateRefRpc,
+  WsVcsSwitchRefRpc,
+  WsVcsInitRpc,
   WsTerminalOpenRpc,
   WsTerminalWriteRpc,
   WsTerminalResizeRpc,
diff --git a/packages/contracts/src/server.test.ts b/packages/contracts/src/server.test.ts
index 2603d51d6a9..149b0db2013 100644
--- a/packages/contracts/src/server.test.ts
+++ b/packages/contracts/src/server.test.ts
@@ -6,9 +6,10 @@ 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",
@@ -23,4 +24,23 @@ describe("ServerProvider", () => {
     expect(parsed.slashCommands).toEqual([]);
     expect(parsed.skills).toEqual([]);
   });
+
+  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 1f048c13407..a3d07ea69c2 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -11,7 +11,7 @@ import {
 import { KeybindingRule, ResolvedKeybindingsConfig } from "./keybindings.ts";
 import { EditorId } from "./editor.ts";
 import { ModelCapabilities } from "./model.ts";
-import { ProviderKind } from "./orchestration.ts";
+import { ProviderDriverKind, ProviderInstanceId } from "./providerInstance.ts";
 import { ServerSettings } from "./settings.ts";
 
 const KeybindingsMalformedConfigIssue = Schema.Struct({
@@ -47,6 +47,7 @@ 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;
 
@@ -83,10 +84,42 @@ 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 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,
@@ -95,6 +128,15 @@ 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([])),
@@ -106,6 +148,15 @@ 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,
@@ -147,6 +198,7 @@ export const ServerConfigUpdatedPayload = Schema.Struct({
 export type ServerConfigUpdatedPayload = typeof ServerConfigUpdatedPayload.Type;
 
 export const ServerConfigKeybindingsUpdatedPayload = Schema.Struct({
+  keybindings: ResolvedKeybindingsConfig,
   issues: ServerConfigIssues,
 });
 export type ServerConfigKeybindingsUpdatedPayload =
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
new file mode 100644
index 00000000000..d2b73f567a7
--- /dev/null
+++ b/packages/contracts/src/settings.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+import { Schema } from "effect";
+
+import { ProviderInstanceId } from "./providerInstance.ts";
+import { DEFAULT_SERVER_SETTINGS, ServerSettings, ServerSettingsPatch } from "./settings.ts";
+
+const decodeServerSettings = Schema.decodeUnknownSync(ServerSettings);
+const decodeServerSettingsPatch = Schema.decodeUnknownSync(ServerSettingsPatch);
+
+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");
+  });
+});
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index cc48d739384..a8d5d8b4f55 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -2,18 +2,9 @@ import { Effect } from "effect";
 import * as Schema from "effect/Schema";
 import * as SchemaTransformation from "effect/SchemaTransformation";
 import { TrimmedNonEmptyString, TrimmedString } from "./baseSchemas.ts";
-import {
-  AmpModelOptions,
-  ClaudeModelOptions,
-  CodexModelOptions,
-  CopilotModelOptions,
-  CursorModelOptions,
-  DEFAULT_GIT_TEXT_GENERATION_MODEL_BY_PROVIDER,
-  GeminiCliModelOptions,
-  KiloModelOptions,
-  OpencodeModelOptions,
-} from "./model.ts";
-import { ModelSelection, ProviderKind } from "./orchestration.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) ───────────────────────────────
 
@@ -41,13 +32,33 @@ 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))),
+  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: ProviderKind,
+      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)),
   ),
@@ -86,39 +97,371 @@ 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([]))),
-  launchArgs: 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 = Schema.Struct({
-  enabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
-  binaryPath: makeBinaryPathSetting("agent"),
-  apiEndpoint: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
-  customModels: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
-});
+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 = Schema.Struct({
-  enabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
-  binaryPath: makeBinaryPathSetting("opencode"),
-  serverUrl: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
-  serverPassword: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
-  customModels: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
-});
+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;
 
+// ── Fork provider settings ───────────────────────────────────────────
+//
+// The following four schemas describe the fork's additional drivers (Amp,
+// Copilot, Gemini CLI, Kilo). All four are JSON-compatible with the legacy
+// `GenericProviderSettings` shape — the driver implementations keep
+// `configSchema = GenericProviderSettings` for now. These typed schemas
+// exist primarily so the web settings UI can render rich form controls
+// (titles, descriptions, placeholders) per field. Once each driver moves
+// its config to its own package, these can shrink or move.
+
+export const AmpSettings = makeProviderSettingsSchema(
+  {
+    enabled: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(Effect.succeed(true)),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    binaryPath: makeBinaryPathSetting("amp").pipe(
+      Schema.annotateKey({
+        title: "Binary path",
+        description: "Path to the Amp CLI binary used by this instance.",
+        providerSettingsForm: { placeholder: "amp", clearWhenEmpty: "omit" },
+      }),
+    ),
+    configDir: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Config directory",
+        description:
+          "Custom Amp configuration directory. Leave blank to use the Amp default.",
+        providerSettingsForm: {
+          placeholder: "~/.config/amp",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+    customModels: Schema.Array(Schema.String).pipe(
+      Schema.withDecodingDefault(Effect.succeed([])),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+  },
+  {
+    order: ["binaryPath", "configDir"],
+  },
+);
+export type AmpSettings = typeof AmpSettings.Type;
+
+export const CopilotSettings = makeProviderSettingsSchema(
+  {
+    enabled: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(Effect.succeed(true)),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    binaryPath: makeBinaryPathSetting("copilot").pipe(
+      Schema.annotateKey({
+        title: "Binary path",
+        description: "Path to the GitHub Copilot CLI binary used by this instance.",
+        providerSettingsForm: { placeholder: "copilot", clearWhenEmpty: "omit" },
+      }),
+    ),
+    configDir: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Config directory",
+        description:
+          "Custom config directory used when running this Copilot instance. Keeps account state separate.",
+        providerSettingsForm: { placeholder: "~/.copilot", clearWhenEmpty: "omit" },
+      }),
+    ),
+    customModels: Schema.Array(Schema.String).pipe(
+      Schema.withDecodingDefault(Effect.succeed([])),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+  },
+  {
+    order: ["binaryPath", "configDir"],
+  },
+);
+export type CopilotSettings = typeof CopilotSettings.Type;
+
+export const GeminiCliSettings = makeProviderSettingsSchema(
+  {
+    enabled: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(Effect.succeed(true)),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    binaryPath: makeBinaryPathSetting("gemini").pipe(
+      Schema.annotateKey({
+        title: "Binary path",
+        description:
+          "Path to the `gemini` executable. Leave blank to resolve from PATH.",
+        providerSettingsForm: { placeholder: "gemini", clearWhenEmpty: "omit" },
+      }),
+    ),
+    configDir: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Config directory",
+        description:
+          "Override `GEMINI_HOME` (Gemini CLI honours `~/.gemini` by default).",
+        providerSettingsForm: { placeholder: "~/.gemini", clearWhenEmpty: "omit" },
+      }),
+    ),
+    customModels: Schema.Array(Schema.String).pipe(
+      Schema.withDecodingDefault(Effect.succeed([])),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+  },
+  {
+    order: ["binaryPath", "configDir"],
+  },
+);
+export type GeminiCliSettings = typeof GeminiCliSettings.Type;
+
+export const KiloSettings = makeProviderSettingsSchema(
+  {
+    enabled: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(Effect.succeed(true)),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+    binaryPath: makeBinaryPathSetting("kilo").pipe(
+      Schema.annotateKey({
+        title: "Binary path",
+        description: "Path to the Kilo CLI binary.",
+        providerSettingsForm: { placeholder: "kilo", clearWhenEmpty: "omit" },
+      }),
+    ),
+    configDir: TrimmedString.pipe(
+      Schema.withDecodingDefault(Effect.succeed("")),
+      Schema.annotateKey({
+        title: "Config directory",
+        description:
+          "Custom Kilo configuration directory. Leave blank to use the Kilo default.",
+        providerSettingsForm: {
+          placeholder: "~/.config/kilo",
+          clearWhenEmpty: "omit",
+        },
+      }),
+    ),
+    customModels: Schema.Array(Schema.String).pipe(
+      Schema.withDecodingDefault(Effect.succeed([])),
+      Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
+    ),
+  },
+  {
+    order: ["binaryPath", "configDir"],
+  },
+);
+export type KiloSettings = typeof KiloSettings.Type;
+
 export const GenericProviderSettings = Schema.Struct({
   enabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
   customModels: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
@@ -142,23 +485,36 @@ export const ServerSettings = Schema.Struct({
   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({}))),
-    copilot: GenericProviderSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+    copilot: CopilotSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
     cursor: CursorSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
     opencode: OpenCodeSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
-    geminiCli: GenericProviderSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
-    amp: GenericProviderSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
-    kilo: GenericProviderSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+    geminiCli: GeminiCliSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+    amp: AmpSettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
+    kilo: KiloSettings.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;
@@ -188,99 +544,24 @@ 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 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 CopilotModelOptionsPatch = Schema.Struct({
-  reasoningEffort: Schema.optionalKey(CopilotModelOptions.fields.reasoningEffort),
+const ModelSelectionPatch = Schema.Struct({
+  instanceId: Schema.optionalKey(ProviderInstanceId),
+  model: Schema.optionalKey(TrimmedNonEmptyString),
+  options: Schema.optionalKey(ProviderOptionSelections),
 });
 
-const CursorModelOptionsPatch = Schema.Struct({
-  reasoning: Schema.optionalKey(CursorModelOptions.fields.reasoning),
-  fastMode: Schema.optionalKey(CursorModelOptions.fields.fastMode),
-  thinking: Schema.optionalKey(CursorModelOptions.fields.thinking),
-});
-
-const OpencodeModelOptionsPatch = Schema.Struct({
-  providerId: Schema.optionalKey(OpencodeModelOptions.fields.providerId),
-  reasoningEffort: Schema.optionalKey(OpencodeModelOptions.fields.reasoningEffort),
-});
-
-const GeminiCliModelOptionsPatch = Schema.Struct({
-  thinkingBudget: Schema.optionalKey(GeminiCliModelOptions.fields.thinkingBudget),
-});
-
-const AmpModelOptionsPatch = Schema.Struct({
-  mode: Schema.optionalKey(AmpModelOptions.fields.mode),
-});
-
-const KiloModelOptionsPatch = Schema.Struct({
-  providerId: Schema.optionalKey(KiloModelOptions.fields.providerId),
-  reasoningEffort: Schema.optionalKey(KiloModelOptions.fields.reasoningEffort),
-});
-
-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),
-  }),
-  Schema.Struct({
-    provider: Schema.optionalKey(Schema.Literal("copilot")),
-    model: Schema.optionalKey(TrimmedNonEmptyString),
-    options: Schema.optionalKey(CopilotModelOptionsPatch),
-  }),
-  Schema.Struct({
-    provider: Schema.optionalKey(Schema.Literal("cursor")),
-    model: Schema.optionalKey(TrimmedNonEmptyString),
-    options: Schema.optionalKey(CursorModelOptionsPatch),
-  }),
-  Schema.Struct({
-    provider: Schema.optionalKey(Schema.Literal("opencode")),
-    model: Schema.optionalKey(TrimmedNonEmptyString),
-    options: Schema.optionalKey(OpencodeModelOptionsPatch),
-  }),
-  Schema.Struct({
-    provider: Schema.optionalKey(Schema.Literal("geminiCli")),
-    model: Schema.optionalKey(TrimmedNonEmptyString),
-    options: Schema.optionalKey(GeminiCliModelOptionsPatch),
-  }),
-  Schema.Struct({
-    provider: Schema.optionalKey(Schema.Literal("amp")),
-    model: Schema.optionalKey(TrimmedNonEmptyString),
-    options: Schema.optionalKey(AmpModelOptionsPatch),
-  }),
-  Schema.Struct({
-    provider: Schema.optionalKey(Schema.Literal("kilo")),
-    model: Schema.optionalKey(TrimmedNonEmptyString),
-    options: Schema.optionalKey(KiloModelOptionsPatch),
-  }),
-]);
-
 const CodexSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
   binaryPath: Schema.optionalKey(Schema.String),
   homePath: Schema.optionalKey(Schema.String),
+  shadowHomePath: Schema.optionalKey(Schema.String),
   customModels: Schema.optionalKey(Schema.Array(Schema.String)),
 });
 
 const ClaudeSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
   binaryPath: Schema.optionalKey(Schema.String),
+  homePath: Schema.optionalKey(Schema.String),
   customModels: Schema.optionalKey(Schema.Array(Schema.String)),
   launchArgs: Schema.optionalKey(Schema.String),
 });
@@ -331,6 +612,11 @@ export const ServerSettingsPatch = Schema.Struct({
       kilo: Schema.optionalKey(GenericProviderSettingsPatch),
     }),
   ),
+  // 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;
 
@@ -338,15 +624,29 @@ 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: ProviderKind,
+        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),
diff --git a/packages/contracts/src/sourceControl.ts b/packages/contracts/src/sourceControl.ts
new file mode 100644
index 00000000000..0384b5d18da
--- /dev/null
+++ b/packages/contracts/src/sourceControl.ts
@@ -0,0 +1,179 @@
+import { Schema } from "effect";
+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 3feae674924..514320f6d4d 100644
--- a/packages/contracts/src/terminal.test.ts
+++ b/packages/contracts/src/terminal.test.ts
@@ -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);
   });
diff --git a/packages/contracts/src/terminal.ts b/packages/contracts/src/terminal.ts
index 21bd74a0999..c4d9972d8c3 100644
--- a/packages/contracts/src/terminal.ts
+++ b/packages/contracts/src/terminal.ts
@@ -4,11 +4,11 @@ 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(
diff --git a/packages/contracts/src/vcs.ts b/packages/contracts/src/vcs.ts
new file mode 100644
index 00000000000..2dd09cf04c6
--- /dev/null
+++ b/packages/contracts/src/vcs.ts
@@ -0,0 +1,154 @@
+import { Schema } from "effect";
+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 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})`;
+  }
+}
+
+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`;
+  }
+}
+
+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}`;
+  }
+}
+
+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/shared/package.json b/packages/shared/package.json
index 82085dfcaf3..d407a78af58 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -12,6 +12,10 @@
       "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"
@@ -71,6 +75,10 @@
     "./path": {
       "types": "./src/path.ts",
       "import": "./src/path.ts"
+    },
+    "./keybindings": {
+      "types": "./src/keybindings.ts",
+      "import": "./src/keybindings.ts"
     }
   },
   "scripts": {
diff --git a/packages/shared/src/git.test.ts b/packages/shared/src/git.test.ts
index 2160c460dc5..5eb9fd51244 100644
--- a/packages/shared/src/git.test.ts
+++ b/packages/shared/src/git.test.ts
@@ -1,4 +1,4 @@
-import type { GitStatusRemoteResult, GitStatusResult } from "@t3tools/contracts";
+import type { VcsStatusRemoteResult, VcsStatusResult } from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
 
 import {
@@ -54,17 +54,17 @@ describe("parseGitHubRepositoryNameWithOwnerFromRemoteUrl", () => {
 });
 
 describe("isTemporaryWorktreeBranch", () => {
-  it("matches the generated temporary worktree branch format", () => {
+  it("matches the generated temporary worktree refName format", () => {
     expect(isTemporaryWorktreeBranch(buildTemporaryWorktreeBranchName())).toBe(true);
   });
 
-  it("matches generated temporary worktree branches", () => {
+  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 branch names", () => {
+  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);
@@ -73,7 +73,7 @@ describe("isTemporaryWorktreeBranch", () => {
 
 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,
@@ -82,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,
@@ -95,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 }],
@@ -117,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 4570ba9ecb0..1ad17f52bd4 100644
--- a/packages/shared/src/git.ts
+++ b/packages/shared/src/git.ts
@@ -1,19 +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 {
@@ -35,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 {
@@ -49,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[],
@@ -60,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;
@@ -90,8 +91,8 @@ export function buildTemporaryWorktreeBranchName(): string {
   return `${WORKTREE_BRANCH_PREFIX}/${token}`;
 }
 
-export function isTemporaryWorktreeBranch(branch: string): boolean {
-  return TEMP_WORKTREE_BRANCH_PATTERN.test(branch.trim().toLowerCase());
+export function isTemporaryWorktreeBranch(refName: string): boolean {
+  return TEMP_WORKTREE_BRANCH_PATTERN.test(refName.trim().toLowerCase());
 }
 
 /**
@@ -165,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);
@@ -308,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..c67ad784fe1
--- /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;
+}
+
+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/model.test.ts b/packages/shared/src/model.test.ts
index b1d9bd7673b..61cc8d181f4 100644
--- a/packages/shared/src/model.test.ts
+++ b/packages/shared/src/model.test.ts
@@ -1,78 +1,81 @@
 import { describe, expect, it } from "vitest";
 import {
-  CURSOR_MODEL_FAMILY_OPTIONS,
-  CURSOR_REASONING_OPTIONS,
   DEFAULT_MODEL,
-  DEFAULT_MODEL_BY_PROVIDER,
-  DEFAULT_REASONING_EFFORT_BY_PROVIDER,
-  MODEL_OPTIONS_BY_PROVIDER,
-  CODEX_REASONING_EFFORT_OPTIONS,
+  ProviderDriverKind,
+  ProviderInstanceId,
   type ModelCapabilities,
 } from "@t3tools/contracts";
 
 import {
   applyClaudePromptEffortPrefix,
-  getDefaultContextWindow,
-  getDefaultModel,
-  getDefaultReasoningEffort,
-  getCursorModelFamilyOptions,
-  getModelCapabilities,
-  getModelOptions,
-  getDefaultEffort,
-  getReasoningEffortOptions,
-  hasContextWindowOption,
-  hasEffortLevel,
+  buildProviderOptionSelectionsFromDescriptors,
+  createModelCapabilities,
+  createModelSelection,
+  getModelSelectionBooleanOptionValue,
+  getModelSelectionStringOptionValue,
+  getProviderOptionDescriptors,
+  getProviderOptionBooleanSelectionValue,
+  getProviderOptionStringSelectionValue,
   isClaudeUltrathinkPrompt,
-  normalizeClaudeModelOptions,
-  normalizeClaudeModelOptionsWithCapabilities,
-  normalizeCodexModelOptions,
-  normalizeCodexModelOptionsWithCapabilities,
   normalizeModelSlug,
-  parseCursorModelSelection,
-  resolveApiModelId,
-  resolveContextWindow,
-  resolveCursorPickerModelSlug,
-  resolveCursorModelFromSelection,
-  resolveEffort,
-  resolveReasoningEffortForProvider,
-  resolveSelectableModel,
-  resolveModelSlug,
   resolveModelSlugForProvider,
-  inferProviderForModel,
+  resolveSelectableModel,
   trimOrNull,
 } from "./model.ts";
 
-const codexCaps: ModelCapabilities = {
-  reasoningEffortLevels: [
-    { value: "xhigh", label: "Extra High" },
-    { value: "high", label: "High", isDefault: true },
+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", () => {
@@ -81,143 +84,22 @@ describe("normalizeModelSlug", () => {
     expect(normalizeModelSlug(null)).toBeNull();
     expect(normalizeModelSlug(undefined)).toBeNull();
   });
-
-  it("preserves non-aliased model slugs", () => {
-    expect(normalizeModelSlug("gpt-5.2")).toBe("gpt-5.2");
-    expect(normalizeModelSlug("gpt-5.2-codex")).toBe("gpt-5.2-codex");
-  });
-
-  it("uses provider-specific aliases", () => {
-    expect(normalizeModelSlug("sonnet", "claudeAgent")).toBe("claude-sonnet-4-6");
-    expect(normalizeModelSlug("opus", "claudeAgent")).toBe("claude-opus-4-7");
-    expect(normalizeModelSlug("opus-4.7", "claudeAgent")).toBe("claude-opus-4-7");
-    expect(normalizeModelSlug("opus-4.6", "claudeAgent")).toBe("claude-opus-4-6");
-    expect(normalizeModelSlug("opus-4.5", "claudeAgent")).toBe("claude-opus-4-5");
-    expect(normalizeModelSlug("claude-haiku-4-5-20251001", "claudeAgent")).toBe("claude-haiku-4-5");
-    expect(normalizeModelSlug("composer", "cursor")).toBe("composer-1.5");
-    expect(normalizeModelSlug("gpt-5.3-codex-spark", "cursor")).toBe("gpt-5.3-codex-spark-preview");
-    expect(normalizeModelSlug("gpt-5.4", "cursor")).toBe("gpt-5.4-medium");
-    expect(normalizeModelSlug("gpt-5.2-codex", "cursor")).toBe("gpt-5.2-codex");
-    expect(normalizeModelSlug("gemini-3.1", "cursor")).toBe("gemini-3.1-pro");
-    expect(normalizeModelSlug("claude-4.6-sonnet-thinking", "cursor")).toBe("sonnet-4.6-thinking");
-    expect(normalizeModelSlug("claude-4.5-sonnet-thinking", "cursor")).toBe("sonnet-4.5-thinking");
-  });
-
-  it("does not leak prototype properties as aliases", () => {
-    expect(normalizeModelSlug("toString")).toBe("toString");
-    expect(normalizeModelSlug("constructor")).toBe("constructor");
-  });
 });
 
 describe("resolveModelSlugForProvider", () => {
   it("returns defaults when the model is missing", () => {
-    expect(resolveModelSlugForProvider("codex", undefined)).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("claudeAgent", "sonnet")).toBe("claude-sonnet-4-6");
-    // Unknown slugs are preserved (may be custom models)
-    expect(resolveModelSlugForProvider("claudeAgent", "gpt-5.3-codex")).toBe("gpt-5.3-codex");
-    expect(resolveModelSlugForProvider("cursor", undefined)).toBe(DEFAULT_MODEL_BY_PROVIDER.cursor);
-    expect(resolveModelSlugForProvider("cursor", "composer")).toBe("composer-1.5");
-    expect(resolveModelSlugForProvider("cursor", "gpt-5.3-codex-high-fast")).toBe(
-      "gpt-5.3-codex-high-fast",
+    expect(resolveModelSlugForProvider(ProviderDriverKind.make("ollama"), undefined)).toBe(
+      DEFAULT_MODEL,
     );
-    // Unknown slugs are preserved (may be custom models)
-    expect(resolveModelSlugForProvider("cursor", "claude-sonnet-4-6")).toBe("claude-sonnet-4-6");
-  });
-
-  it("keeps codex defaults for backward compatibility", () => {
-    expect(getDefaultModel()).toBe(DEFAULT_MODEL);
-    expect(getModelOptions("claudeAgent")).toEqual(MODEL_OPTIONS_BY_PROVIDER.claudeAgent);
-    expect(getModelOptions("cursor")).toEqual(MODEL_OPTIONS_BY_PROVIDER.cursor);
-    expect(getCursorModelFamilyOptions()).toEqual(CURSOR_MODEL_FAMILY_OPTIONS);
   });
 
   it("preserves normalized unknown models", () => {
-    expect(resolveModelSlugForProvider("codex", "custom/internal-model")).toBe(
-      "custom/internal-model",
-    );
-  });
-});
-
-describe("cursor model selection", () => {
-  it("includes the expected cursor reasoning levels and families", () => {
-    expect(CURSOR_REASONING_OPTIONS).toEqual(["low", "normal", "high", "xhigh"]);
-    expect(getCursorModelFamilyOptions().map((option) => option.slug)).toContain("gpt-5.3-codex");
-    expect(getCursorModelFamilyOptions().map((option) => option.slug)).toContain("gpt-5.2-codex");
-    expect(getCursorModelFamilyOptions().map((option) => option.slug)).toContain("gpt-5.4-medium");
-    expect(getCursorModelFamilyOptions().map((option) => option.slug)).toContain("opus-4.6");
-    expect(getCursorModelFamilyOptions().map((option) => option.slug)).toContain("sonnet-4.5");
-  });
-
-  it("parses codex reasoning and fast mode variants", () => {
-    expect(parseCursorModelSelection("gpt-5.3-codex-high-fast")).toEqual({
-      family: "gpt-5.3-codex",
-      reasoning: "high",
-      fast: true,
-      thinking: false,
-    });
-    expect(parseCursorModelSelection("gpt-5.2-codex")).toEqual({
-      family: "gpt-5.2-codex",
-      reasoning: "normal",
-      fast: false,
-      thinking: false,
-    });
-  });
-
-  it("parses newer cursor codex reasoning variants", () => {
-    expect(parseCursorModelSelection("gpt-5.2-codex-high-fast")).toEqual({
-      family: "gpt-5.2-codex",
-      reasoning: "high",
-      fast: true,
-      thinking: false,
-    });
-    expect(
-      resolveCursorModelFromSelection({
-        family: "gpt-5.2-codex",
-        reasoning: "xhigh",
-        fast: true,
-      }),
-    ).toBe("gpt-5.2-codex-xhigh-fast");
-  });
-
-  it("parses and resolves thinking variants", () => {
-    expect(parseCursorModelSelection("sonnet-4.6-thinking")).toEqual({
-      family: "sonnet-4.6",
-      reasoning: "normal",
-      fast: false,
-      thinking: true,
-    });
     expect(
-      resolveCursorModelFromSelection({
-        family: "sonnet-4.6",
-        thinking: true,
-      }),
-    ).toBe("sonnet-4.6-thinking");
-    expect(parseCursorModelSelection("sonnet-4.5-thinking")).toEqual({
-      family: "sonnet-4.5",
-      reasoning: "normal",
-      fast: false,
-      thinking: true,
-    });
-  });
-
-  it("resolves codex family selections into concrete model ids", () => {
-    expect(
-      resolveCursorModelFromSelection({
-        family: "gpt-5.3-codex",
-        reasoning: "xhigh",
-        fast: true,
-      }),
-    ).toBe("gpt-5.3-codex-xhigh-fast");
-  });
-
-  it("collapses trait-backed cursor variants to a single picker option", () => {
-    expect(resolveCursorPickerModelSlug("gpt-5.2-codex-high-fast")).toBe("gpt-5.2-codex");
-    expect(resolveCursorPickerModelSlug("opus-4.6-thinking")).toBe("opus-4.6");
-    expect(resolveCursorPickerModelSlug("sonnet-4.5-thinking")).toBe("sonnet-4.5");
-    expect(resolveCursorPickerModelSlug("gpt-5.4-high-fast")).toBe("gpt-5.4-high-fast");
+      resolveModelSlugForProvider(ProviderDriverKind.make("codex"), "custom/internal-model"),
+    ).toBe("custom/internal-model");
   });
 });
 
@@ -227,119 +109,15 @@ 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("returns claude effort options for Opus 4.7", () => {
-    const values = getReasoningEffortOptions("claudeAgent", "claude-opus-4-7");
-    expect(values).toEqual(["low", "medium", "high", "xhigh", "max", "ultrathink"]);
-  });
-
-  it("returns claude effort options for Opus 4.6", () => {
-    const values = getReasoningEffortOptions("claudeAgent", "claude-opus-4-6");
-    expect(values).toEqual(["low", "medium", "high", "max", "ultrathink"]);
-  });
-
-  it("returns claude effort options for Opus 4.5", () => {
-    const values = getReasoningEffortOptions("claudeAgent", "claude-opus-4-5");
-    expect(values).toEqual(["low", "medium", "high", "max"]);
-  });
-
-  it("returns claude effort options for Sonnet 4.6", () => {
-    const values = getReasoningEffortOptions("claudeAgent", "claude-sonnet-4-6");
-    expect(values).toEqual(["low", "medium", "high", "ultrathink"]);
-  });
-
-  it("returns no claude effort options for Haiku 4.5", () => {
-    expect(getReasoningEffortOptions("claudeAgent", "claude-haiku-4-5")).toEqual([]);
-  });
-
-  it("returns no reasoning options for cursor", () => {
-    expect(getReasoningEffortOptions("cursor")).toEqual([]);
-  });
-});
-
-describe("inferProviderForModel", () => {
-  it("detects known provider model slugs", () => {
-    expect(inferProviderForModel("gpt-5.3-codex")).toBe("codex");
-    expect(inferProviderForModel("claude-sonnet-4-6")).toBe("claudeAgent");
-    expect(inferProviderForModel("sonnet")).toBe("claudeAgent");
-  });
-
-  it("co-locates labels with effort values", () => {
-    const levels = getModelCapabilities("claudeAgent", "claude-opus-4-6").reasoningEffortLevels;
-    const high = levels.find((l) => l.value === "high");
-    expect(high).toEqual({ value: "high", label: "High", isDefault: true });
-    const xhigh = getModelCapabilities("codex", "gpt-5.4").reasoningEffortLevels.find(
-      (l) => l.value === "xhigh",
+    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",
     );
-    expect(xhigh).toEqual({ value: "xhigh", label: "Extra High" });
-    expect(getDefaultReasoningEffort("cursor")).toBe(DEFAULT_REASONING_EFFORT_BY_PROVIDER.cursor);
-  });
-});
-
-describe("getDefaultEffort", () => {
-  it("returns the default effort from capabilities", () => {
-    expect(getDefaultEffort(getModelCapabilities("codex", "gpt-5.4"))).toBe("high");
-    expect(getDefaultEffort(getModelCapabilities("claudeAgent", "claude-opus-4-6"))).toBe("high");
-    expect(getDefaultEffort(getModelCapabilities("claudeAgent", "claude-haiku-4-5"))).toBeNull();
-  });
-});
-
-describe("hasEffortLevel", () => {
-  it("validates effort against model capabilities", () => {
-    const opusCaps = getModelCapabilities("claudeAgent", "claude-opus-4-6");
-    expect(hasEffortLevel(opusCaps, "max")).toBe(true);
-    expect(hasEffortLevel(opusCaps, "xhigh")).toBe(false);
-
-    const codexCaps = getModelCapabilities("codex", "gpt-5.4");
-    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();
   });
 });
 
@@ -365,95 +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("normalize*ModelOptionsWithCapabilities", () => {
-  it("preserves explicit false codex fast mode", () => {
+describe("descriptor helpers", () => {
+  it("applies selection values to capability descriptors", () => {
     expect(
-      normalizeCodexModelOptionsWithCapabilities(codexCaps, {
-        reasoningEffort: "high",
-        fastMode: false,
+      getProviderOptionDescriptors({
+        caps: claudeCaps,
+        selections: [
+          { id: "effort", value: "medium" },
+          { id: "contextWindow", value: "200k" },
+        ],
       }),
-    ).toEqual({
-      reasoningEffort: "high",
-      fastMode: false,
+    ).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 },
+      ],
     });
+
+    expect(buildProviderOptionSelectionsFromDescriptors(descriptors)).toEqual([
+      { id: "reasoningEffort", value: "high" },
+      { id: "fastMode", value: true },
+    ]);
   });
 
-  it("preserves the default Claude context window explicitly", () => {
+  it("stores option selection arrays in model selections", () => {
     expect(
-      normalizeClaudeModelOptionsWithCapabilities(
-        {
-          ...claudeCaps,
-          contextWindowOptions: [
-            { value: "200k", label: "200k", isDefault: true },
-            { value: "1m", label: "1M" },
-          ],
-        },
-        {
-          effort: "high",
-          contextWindow: "200k",
-        },
-      ),
+      createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: true },
+      ]),
     ).toEqual({
-      effort: "high",
-      contextWindow: "200k",
+      instanceId: "codex",
+      model: "gpt-5.4",
+      options: [
+        { id: "reasoningEffort", value: "high" },
+        { id: "fastMode", value: true },
+      ],
     });
   });
 
-  it("omits unsupported Claude context window options", () => {
+  it("reads typed option selection values", () => {
+    const selection = createModelSelection(ProviderInstanceId.make("codex"), "gpt-5.4", [
+      { id: "reasoningEffort", value: "high" },
+      { id: "fastMode", value: true },
+    ]);
+
+    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 295bea4c6c2..9fdbd6c0447 100644
--- a/packages/shared/src/model.ts
+++ b/packages/shared/src/model.ts
@@ -1,599 +1,231 @@
 import {
-  CLAUDE_CODE_EFFORT_OPTIONS_BY_PROVIDER,
-  CURSOR_MODEL_FAMILY_OPTIONS,
-  CURSOR_REASONING_OPTIONS,
-  DEFAULT_CLAUDE_CODE_EFFORT_BY_PROVIDER,
+  DEFAULT_MODEL,
   DEFAULT_MODEL_BY_PROVIDER,
-  MODEL_CAPABILITIES_INDEX,
-  MODEL_OPTIONS_BY_PROVIDER,
   MODEL_SLUG_ALIASES_BY_PROVIDER,
-  REASONING_EFFORT_OPTIONS_BY_PROVIDER,
-  DEFAULT_REASONING_EFFORT_BY_PROVIDER,
-  type ClaudeAgentEffort,
-  type ClaudeModelOptions,
-  type ClaudeCodeEffort,
-  type CodexModelOptions,
-  type CodexReasoningEffort,
-  type CursorModelFamily,
-  type CursorModelOptions,
-  type CursorModelSlug,
-  type CursorReasoningOption,
   type ModelCapabilities,
   type ModelSelection,
-  type ModelSlug,
-  type OpenCodeModelOptions,
-  type ProviderKind,
-  type ProviderModelOptions,
-  type ProviderReasoningEffort,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ProviderOptionDescriptor,
+  type ProviderOptionSelection,
 } from "@t3tools/contracts";
 
-type CursorModelCapability = {
-  readonly supportsReasoning: boolean;
-  readonly supportsFast: boolean;
-  readonly supportsThinking: boolean;
-  readonly defaultReasoning: CursorReasoningOption;
-  readonly defaultThinking: boolean;
-};
-
-const CURSOR_MODEL_CAPABILITY_BY_FAMILY: Record<CursorModelFamily, CursorModelCapability> = {
-  auto: {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "composer-1.5": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "composer-1": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.3-codex": {
-    supportsReasoning: true,
-    supportsFast: true,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.2-codex": {
-    supportsReasoning: true,
-    supportsFast: true,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.2": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.2-high": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.1-codex-max": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.1-codex-max-high": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.4-medium": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.4-medium-fast": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.4-high": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.4-high-fast": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.4-xhigh": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.4-xhigh-fast": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.3-codex-spark-preview": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "opus-4.6": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: true,
-    defaultReasoning: "normal",
-    defaultThinking: true,
-  },
-  "opus-4.5": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: true,
-    defaultReasoning: "normal",
-    defaultThinking: true,
-  },
-  "sonnet-4.6": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: true,
-    defaultReasoning: "normal",
-    defaultThinking: true,
-  },
-  "sonnet-4.5": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: true,
-    defaultReasoning: "normal",
-    defaultThinking: true,
-  },
-  "gemini-3.1-pro": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  grok: {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.1-high": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gemini-3-pro": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gemini-3-flash": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "gpt-5.1-codex-mini": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-  "kimi-k2.5": {
-    supportsReasoning: false,
-    supportsFast: false,
-    supportsThinking: false,
-    defaultReasoning: "normal",
-    defaultThinking: false,
-  },
-};
-
-const MODEL_SLUG_SET_BY_PROVIDER: Record<ProviderKind, ReadonlySet<ModelSlug>> = {
-  codex: new Set(MODEL_OPTIONS_BY_PROVIDER.codex.map((option) => option.slug)),
-  copilot: new Set(MODEL_OPTIONS_BY_PROVIDER.copilot.map((option) => option.slug)),
-  claudeAgent: new Set(MODEL_OPTIONS_BY_PROVIDER.claudeAgent.map((option) => option.slug)),
-  cursor: new Set(MODEL_OPTIONS_BY_PROVIDER.cursor.map((option) => option.slug)),
-  opencode: new Set(MODEL_OPTIONS_BY_PROVIDER.opencode.map((option) => option.slug)),
-  kilo: new Set(MODEL_OPTIONS_BY_PROVIDER.kilo.map((option) => option.slug)),
-  geminiCli: new Set(MODEL_OPTIONS_BY_PROVIDER.geminiCli.map((option) => option.slug)),
-  amp: new Set(MODEL_OPTIONS_BY_PROVIDER.amp.map((option) => option.slug)),
-};
-
-const CURSOR_MODEL_FAMILY_SET = new Set<CursorModelFamily>(
-  CURSOR_MODEL_FAMILY_OPTIONS.map((option) => option.slug),
-);
-
-export interface CursorModelSelection {
-  readonly family: CursorModelFamily;
-  readonly reasoning: CursorReasoningOption;
-  readonly fast: boolean;
-  readonly thinking: boolean;
-}
+const DEFAULT_PROVIDER_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 export interface SelectableModelOption {
   slug: string;
   name: string;
 }
 
-export function getModelOptions(provider: ProviderKind = "codex") {
-  return MODEL_OPTIONS_BY_PROVIDER[provider];
-}
-
-export function getCursorModelFamilyOptions() {
-  return CURSOR_MODEL_FAMILY_OPTIONS;
-}
-
-export function getCursorModelCapabilities(family: CursorModelFamily) {
-  return CURSOR_MODEL_CAPABILITY_BY_FAMILY[family];
-}
-
-function fallbackCursorModelFamily(): CursorModelFamily {
-  const fallback = parseCursorModelSelection(DEFAULT_MODEL_BY_PROVIDER.cursor);
-  return fallback.family;
-}
-
-function resolveCursorModelFamily(model: string | null | undefined): CursorModelFamily {
-  const normalized = normalizeModelSlug(model, "cursor");
-  if (!normalized) {
-    return fallbackCursorModelFamily();
-  }
-
-  if (
-    normalized === "gpt-5.3-codex" ||
-    normalized === "gpt-5.3-codex-fast" ||
-    normalized === "gpt-5.3-codex-low" ||
-    normalized === "gpt-5.3-codex-low-fast" ||
-    normalized === "gpt-5.3-codex-high" ||
-    normalized === "gpt-5.3-codex-high-fast" ||
-    normalized === "gpt-5.3-codex-xhigh" ||
-    normalized === "gpt-5.3-codex-xhigh-fast"
-  ) {
-    return "gpt-5.3-codex";
-  }
-  if (
-    normalized === "gpt-5.2-codex" ||
-    normalized === "gpt-5.2-codex-fast" ||
-    normalized === "gpt-5.2-codex-low" ||
-    normalized === "gpt-5.2-codex-low-fast" ||
-    normalized === "gpt-5.2-codex-high" ||
-    normalized === "gpt-5.2-codex-high-fast" ||
-    normalized === "gpt-5.2-codex-xhigh" ||
-    normalized === "gpt-5.2-codex-xhigh-fast"
-  ) {
-    return "gpt-5.2-codex";
-  }
-
-  if (normalized === "sonnet-4.6-thinking") {
-    return "sonnet-4.6";
-  }
-  if (normalized === "sonnet-4.5-thinking") {
-    return "sonnet-4.5";
-  }
-  if (normalized === "opus-4.6-thinking") {
-    return "opus-4.6";
-  }
-  if (normalized === "opus-4.5-thinking") {
-    return "opus-4.5";
-  }
-
-  return CURSOR_MODEL_FAMILY_SET.has(normalized as CursorModelFamily)
-    ? (normalized as CursorModelFamily)
-    : fallbackCursorModelFamily();
-}
-
-function resolveCursorReasoning(model: CursorModelSlug): CursorReasoningOption {
-  if (model.includes("-xhigh")) return "xhigh";
-  if (model.includes("-high")) return "high";
-  if (model.includes("-low")) return "low";
-  return "normal";
-}
-
-export function parseCursorModelSelection(model: string | null | undefined): CursorModelSelection {
-  const family = resolveCursorModelFamily(model);
-  const capability = CURSOR_MODEL_CAPABILITY_BY_FAMILY[family];
-  const normalized = resolveModelSlugForProvider("cursor", model) as CursorModelSlug;
-
-  if (capability.supportsReasoning) {
-    return {
-      family,
-      reasoning: resolveCursorReasoning(normalized),
-      fast: normalized.endsWith("-fast"),
-      thinking: false,
-    };
-  }
-
-  if (capability.supportsThinking) {
-    return {
-      family,
-      reasoning: capability.defaultReasoning,
-      fast: false,
-      thinking: normalized.endsWith("-thinking"),
-    };
-  }
-
+export function createModelCapabilities(input: {
+  optionDescriptors: ReadonlyArray<ProviderOptionDescriptor>;
+}): ModelCapabilities {
   return {
-    family,
-    reasoning: capability.defaultReasoning,
-    fast: false,
-    thinking: capability.defaultThinking,
+    optionDescriptors: input.optionDescriptors.map(cloneDescriptor),
   };
 }
 
-export function resolveCursorPickerModelSlug(
-  model: string | null | undefined,
-): CursorModelSlug | CursorModelFamily {
-  const selection = parseCursorModelSelection(model);
-  const capability = CURSOR_MODEL_CAPABILITY_BY_FAMILY[selection.family];
-  const normalized = resolveModelSlugForProvider("cursor", model) as CursorModelSlug;
-  return capability.supportsReasoning || capability.supportsThinking
-    ? selection.family
-    : normalized;
+function getRawSelectionValueById(
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+  id: string,
+): string | boolean | undefined {
+  const selection = selections?.find((candidate) => candidate.id === id);
+  return selection?.value;
 }
 
-export function resolveCursorModelFromSelection(input: {
-  readonly family: CursorModelFamily;
-  readonly reasoning?: CursorReasoningOption | null;
-  readonly fast?: boolean;
-  readonly thinking?: boolean;
-}): CursorModelSlug {
-  const family = resolveCursorModelFamily(input.family);
-  const capability = CURSOR_MODEL_CAPABILITY_BY_FAMILY[family];
-
-  if (capability.supportsReasoning) {
-    const reasoning = CURSOR_REASONING_OPTIONS.includes(input.reasoning ?? "normal")
-      ? (input.reasoning ?? "normal")
-      : capability.defaultReasoning;
-    const reasoningSuffix = reasoning === "normal" ? "" : `-${reasoning}`;
-    const fastSuffix = input.fast ? "-fast" : "";
-    const candidate = `${family}${reasoningSuffix}${fastSuffix}`;
-    return resolveModelSlugForProvider("cursor", candidate) as CursorModelSlug;
-  }
-
-  if (capability.supportsThinking) {
-    const candidate = input.thinking ? `${family}-thinking` : family;
-    return resolveModelSlugForProvider("cursor", candidate) as CursorModelSlug;
-  }
-
-  return resolveModelSlugForProvider("cursor", family) as CursorModelSlug;
+export function getProviderOptionSelectionValue(
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+  id: string,
+): string | boolean | undefined {
+  return getRawSelectionValueById(selections, id);
 }
 
-export function getDefaultModel(provider: ProviderKind = "codex"): ModelSlug {
-  return DEFAULT_MODEL_BY_PROVIDER[provider];
+export function getProviderOptionStringSelectionValue(
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+  id: string,
+): string | undefined {
+  const value = getProviderOptionSelectionValue(selections, id);
+  return typeof value === "string" ? value : undefined;
 }
 
-// ── Effort helpers ────────────────────────────────────────────────────
+export function getProviderOptionBooleanSelectionValue(
+  selections: ReadonlyArray<ProviderOptionSelection> | null | undefined,
+  id: string,
+): boolean | undefined {
+  const value = getProviderOptionSelectionValue(selections, id);
+  return typeof value === "boolean" ? value : undefined;
+}
 
-/** 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);
+export function getModelSelectionOptionValue(
+  modelSelection: ModelSelection | null | undefined,
+  id: string,
+): string | boolean | undefined {
+  return getProviderOptionSelectionValue(modelSelection?.options, id);
 }
 
-/** 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 getModelSelectionStringOptionValue(
+  modelSelection: ModelSelection | null | undefined,
+  id: string,
+): string | undefined {
+  return getProviderOptionStringSelectionValue(modelSelection?.options, id);
 }
 
-export const EMPTY_MODEL_CAPABILITIES: ModelCapabilities = {
-  reasoningEffortLevels: [],
-  supportsFastMode: false,
-  supportsThinkingToggle: false,
-  contextWindowOptions: [],
-  promptInjectedEffortLevels: [],
-};
-
-/** Look up the capabilities for a specific model under a provider. */
-export function getModelCapabilities(
-  provider: ProviderKind,
-  model: string | null | undefined,
-): ModelCapabilities {
-  const slug = normalizeModelSlug(model, provider);
-  if (slug && MODEL_CAPABILITIES_INDEX[provider]?.[slug]) {
-    return MODEL_CAPABILITIES_INDEX[provider][slug];
-  }
-  return EMPTY_MODEL_CAPABILITIES;
+export function getModelSelectionBooleanOptionValue(
+  modelSelection: ModelSelection | null | undefined,
+  id: string,
+): boolean | undefined {
+  return getProviderOptionBooleanSelectionValue(modelSelection?.options, 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,
+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 ───────────────────────────────────────────
-
-/** 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 cloneDescriptor(descriptor: ProviderOptionDescriptor): ProviderOptionDescriptor {
+  return descriptor.type === "select"
+    ? {
+        ...descriptor,
+        options: [...descriptor.options],
+        ...(descriptor.promptInjectedValues
+          ? { promptInjectedValues: [...descriptor.promptInjectedValues] }
+          : {}),
+      }
+    : { ...descriptor };
 }
 
-/** 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 cloneSelection(selection: ProviderOptionSelection): ProviderOptionSelection {
+  return { ...selection };
 }
 
-/**
- * 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,
-): string | undefined {
-  const defaultValue = getDefaultContextWindow(caps);
-  if (!raw) return defaultValue ?? undefined;
-  return hasContextWindowOption(caps, raw) ? raw : (defaultValue ?? undefined);
-}
-
-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 } : {}),
+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,
   };
-  return Object.keys(nextOptions).length > 0 ? nextOptions : 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 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 normalizeCursorModelOptionsWithCapabilities(
-  caps: ModelCapabilities,
-  modelOptions: CursorModelOptions | null | undefined,
-): CursorModelOptions | undefined {
-  const reasoning = resolveEffort(caps, modelOptions?.reasoning);
-  const thinking = caps.supportsThinkingToggle ? modelOptions?.thinking : undefined;
-  const fastMode = caps.supportsFastMode ? modelOptions?.fastMode : undefined;
-  const contextWindow = resolveContextWindow(caps, modelOptions?.contextWindow);
-  const nextOptions: CursorModelOptions = {
-    ...(reasoning ? { reasoning: reasoning as CursorModelOptions["reasoning"] } : {}),
-    ...(fastMode !== undefined ? { fastMode } : {}),
-    ...(thinking !== undefined ? { thinking } : {}),
-    ...(contextWindow !== undefined ? { contextWindow } : {}),
-  };
-  return Object.keys(nextOptions).length > 0 ? nextOptions : undefined;
+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;
 }
 
-function resolveLabeledOption(
-  options: ReadonlyArray<{ value: string; isDefault?: boolean | undefined }> | undefined,
-  raw: string | null | undefined,
+export function getProviderOptionCurrentLabel(
+  descriptor: ProviderOptionDescriptor | null | undefined,
 ): string | undefined {
-  if (!options || options.length === 0) {
-    return raw ?? undefined;
+  if (!descriptor) {
+    return undefined;
+  }
+  if (descriptor.type === "boolean") {
+    return typeof descriptor.currentValue === "boolean"
+      ? descriptor.currentValue
+        ? "On"
+        : "Off"
+      : undefined;
   }
-  if (raw && options.some((option) => option.value === raw)) {
-    return raw;
+  const currentValue = getProviderOptionCurrentValue(descriptor);
+  if (typeof currentValue !== "string") {
+    return undefined;
   }
-  return options.find((option) => option.isDefault)?.value ?? options[0]?.value;
+  return descriptor.options.find((option) => option.id === currentValue)?.label;
 }
 
-export function normalizeOpenCodeModelOptionsWithCapabilities(
-  caps: ModelCapabilities,
-  modelOptions: OpenCodeModelOptions | null | undefined,
-): OpenCodeModelOptions | undefined {
-  const variant = resolveLabeledOption(caps.variantOptions, trimOrNull(modelOptions?.variant));
-  const agent = resolveLabeledOption(caps.agentOptions, trimOrNull(modelOptions?.agent));
-  const nextOptions: OpenCodeModelOptions = {
-    ...(variant ? { variant } : {}),
-    ...(agent ? { agent } : {}),
-  };
-  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;
 }
 
-/**
- * Dispatch normalization to the provider-specific helper.
- *
- * Only upstream providers (codex, claudeAgent, cursor, opencode) have
- * capability-based normalization implemented. Fork-only providers
- * (copilot, geminiCli, amp, kilo) return the original options unchanged.
- */
-export function normalizeProviderModelOptionsWithCapabilities(
-  provider: ProviderKind,
-  caps: ModelCapabilities,
-  modelOptions: ProviderModelOptions[ProviderKind] | null | undefined,
-): ProviderModelOptions[ProviderKind] | undefined {
-  switch (provider) {
-    case "codex":
-      return normalizeCodexModelOptionsWithCapabilities(caps, modelOptions as CodexModelOptions);
-    case "claudeAgent":
-      return normalizeClaudeModelOptionsWithCapabilities(caps, modelOptions as ClaudeModelOptions);
-    case "cursor":
-      return normalizeCursorModelOptionsWithCapabilities(caps, modelOptions as CursorModelOptions);
-    case "opencode":
-      return normalizeOpenCodeModelOptionsWithCapabilities(
-        caps,
-        modelOptions as OpenCodeModelOptions,
-      );
-    default:
-      // Fork-only providers: pass through without capability-based filtering.
-      return modelOptions ?? 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 {
@@ -602,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;
@@ -613,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;
@@ -621,7 +253,7 @@ export function normalizeModelSlug(
 }
 
 export function resolveSelectableModel(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   value: string | null | undefined,
   options: ReadonlyArray<SelectableModelOption>,
 ): string | null {
@@ -653,19 +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;
   }
-
-  // Always preserve the normalized slug — it may be a custom model unknown
-  // to the static catalog.  Only fall back to the default for empty input.
   return normalized;
 }
 
 export function resolveModelSlugForProvider(
-  provider: ProviderKind,
+  provider: ProviderDriverKind,
   model: string | null | undefined,
 ): string {
   return resolveModelSlug(model, provider);
@@ -678,226 +307,51 @@ export function trimOrNull<T extends string>(value: T | null | undefined): T | n
   return trimmed || null;
 }
 
-export function inferProviderForModel(
-  model: string | null | undefined,
-  fallback: ProviderKind = "codex",
-): ProviderKind {
-  const normalizedClaude = normalizeModelSlug(model, "claudeAgent");
-  if (normalizedClaude && MODEL_SLUG_SET_BY_PROVIDER.claudeAgent.has(normalizedClaude)) {
-    return "claudeAgent";
-  }
-
-  const normalizedCodex = normalizeModelSlug(model, "codex");
-  if (normalizedCodex && MODEL_SLUG_SET_BY_PROVIDER.codex.has(normalizedCodex)) {
-    return "codex";
-  }
-
-  return typeof model === "string" && model.trim().startsWith("claude-") ? "claudeAgent" : fallback;
-}
-
-export function getReasoningEffortOptions(provider: "codex"): ReadonlyArray<CodexReasoningEffort>;
-export function getReasoningEffortOptions(
-  provider: "claudeAgent",
-  model?: string | null | undefined,
-): ReadonlyArray<ClaudeCodeEffort>;
-export function getReasoningEffortOptions(
-  provider?: ProviderKind,
-  model?: string | null | undefined,
-): ReadonlyArray<ProviderReasoningEffort>;
-export function getReasoningEffortOptions(
-  provider: ProviderKind = "codex",
-  model?: string | null | undefined,
-): ReadonlyArray<ProviderReasoningEffort> {
-  // Use model-specific capabilities when we have a known model in the index.
-  const slug = normalizeModelSlug(model, provider);
-  if (slug && MODEL_CAPABILITIES_INDEX[provider]?.[slug]) {
-    const caps = MODEL_CAPABILITIES_INDEX[provider][slug];
-    return caps.reasoningEffortLevels.map((l) => l.value) as ProviderReasoningEffort[];
-  }
-  // Fall back to provider-level defaults for unknown/custom models.
-  return REASONING_EFFORT_OPTIONS_BY_PROVIDER[provider];
-}
-
-export function getDefaultReasoningEffort(provider: "codex"): CodexReasoningEffort;
-export function getDefaultReasoningEffort(provider: "claudeAgent"): ClaudeCodeEffort;
-export function getDefaultReasoningEffort(provider?: ProviderKind): ProviderReasoningEffort | null;
-export function getDefaultReasoningEffort(
-  provider: ProviderKind = "codex",
-): ProviderReasoningEffort | null {
-  return DEFAULT_REASONING_EFFORT_BY_PROVIDER[provider];
+function cloneSelections(
+  selections: ReadonlyArray<ProviderOptionSelection>,
+): Array<ProviderOptionSelection> {
+  return selections.map(cloneSelection);
 }
 
-export function getClaudeCodeEffortOptions(
-  provider: ProviderKind = "claudeAgent",
-): ReadonlyArray<ClaudeCodeEffort> {
-  return CLAUDE_CODE_EFFORT_OPTIONS_BY_PROVIDER[provider];
-}
-
-export function getDefaultClaudeCodeEffort(provider: "claudeAgent"): ClaudeCodeEffort;
-export function getDefaultClaudeCodeEffort(provider: ProviderKind): ClaudeCodeEffort | null;
-export function getDefaultClaudeCodeEffort(
-  provider: ProviderKind = "claudeAgent",
-): ClaudeCodeEffort | null {
-  return DEFAULT_CLAUDE_CODE_EFFORT_BY_PROVIDER[provider];
-}
-
-export function resolveReasoningEffortForProvider(
-  provider: "codex",
-  effort: string | null | undefined,
-): CodexReasoningEffort | null;
-export function resolveReasoningEffortForProvider(
-  provider: "claudeAgent",
-  effort: string | null | undefined,
-): ClaudeCodeEffort | null;
-export function resolveReasoningEffortForProvider(
-  provider: ProviderKind,
-  effort: string | null | undefined,
-): ProviderReasoningEffort | null;
-export function resolveReasoningEffortForProvider(
-  provider: ProviderKind,
-  effort: string | null | undefined,
-): ProviderReasoningEffort | null {
-  if (typeof effort !== "string") {
-    return null;
-  }
-
-  const trimmed = effort.trim();
-  if (!trimmed) {
-    return null;
-  }
-
-  const options = REASONING_EFFORT_OPTIONS_BY_PROVIDER[provider] as ReadonlyArray<string>;
-  return options.includes(trimmed) ? (trimmed as ProviderReasoningEffort) : null;
-}
-
-export function getEffectiveClaudeCodeEffort(
-  effort: ClaudeCodeEffort | null | undefined,
-): Exclude<ClaudeCodeEffort, "ultrathink"> | null {
-  if (!effort) {
-    return null;
-  }
-  return effort === "ultrathink" ? null : effort;
-}
-
-export function normalizeCodexModelOptions(
-  model: string | null | undefined,
-  modelOptions: CodexModelOptions | null | undefined,
-): CodexModelOptions | undefined {
-  const caps = getModelCapabilities("codex", model);
-  const defaultReasoningEffort = getDefaultEffort(caps) as CodexReasoningEffort;
-  const reasoningEffort = trimOrNull(modelOptions?.reasoningEffort) ?? defaultReasoningEffort;
-  const fastModeEnabled = modelOptions?.fastMode === true;
-  const nextOptions: CodexModelOptions = {
-    ...(reasoningEffort !== defaultReasoningEffort ? { reasoningEffort } : {}),
-    ...(fastModeEnabled ? { fastMode: true } : {}),
-  };
-  return Object.keys(nextOptions).length > 0 ? nextOptions : undefined;
-}
-
-export function normalizeClaudeModelOptions(
-  model: string | null | undefined,
-  modelOptions: ClaudeModelOptions | null | undefined,
-): ClaudeModelOptions | undefined {
-  const caps = getModelCapabilities("claudeAgent", model);
-  const defaultReasoningEffort = getDefaultEffort(caps);
-  const resolvedEffort = trimOrNull(modelOptions?.effort);
-  const isPromptInjected = caps.promptInjectedEffortLevels.includes(resolvedEffort ?? "");
-  const effort =
-    resolvedEffort &&
-    !isPromptInjected &&
-    hasEffortLevel(caps, resolvedEffort) &&
-    resolvedEffort !== defaultReasoningEffort
-      ? resolvedEffort
-      : undefined;
-  const thinking =
-    caps.supportsThinkingToggle && modelOptions?.thinking === false ? false : undefined;
-  const fastMode = caps.supportsFastMode && modelOptions?.fastMode === true ? true : undefined;
-  const contextWindow = resolveContextWindow(caps, modelOptions?.contextWindow);
-  const nextOptions: ClaudeModelOptions = {
-    ...(thinking === false ? { thinking: false } : {}),
-    ...(effort ? { effort } : {}),
-    ...(fastMode ? { fastMode: true } : {}),
-    ...(contextWindow ? { contextWindow } : {}),
+export function createModelSelection(
+  instanceId: ProviderInstanceId,
+  model: string,
+  options?: ReadonlyArray<ProviderOptionSelection> | null,
+): ModelSelection {
+  const selections = options ? cloneSelections(options) : [];
+  const base: ModelSelection = {
+    instanceId,
+    model,
   };
-  return Object.keys(nextOptions).length > 0 ? nextOptions : undefined;
+  return selections.length > 0 ? { ...base, options: selections } : base;
 }
 
 /**
- * Resolve the actual API model identifier from a model selection.
+ * Returns the effort value if it is a prompt-injected value according to
+ * any select descriptor in the given capabilities, or null otherwise.
  *
- * 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.
- *
- * 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;
     }
   }
-}
-
-/**
- * Upstream-compatible constructor for `ModelSelection` values.
- *
- * Dispatches on provider to keep TypeScript narrowing happy. Fork-only
- * providers (copilot, geminiCli, amp, kilo) are handled via a catch-all
- * branch that preserves options verbatim.
- */
-export function createModelSelection(
-  provider: ProviderKind,
-  model: string,
-  options?: ProviderModelOptions[ProviderKind] | undefined,
-): ModelSelection {
-  switch (provider) {
-    case "codex":
-      return {
-        provider,
-        model,
-        ...(options ? { options: options as CodexModelOptions } : {}),
-      };
-    case "claudeAgent":
-      return {
-        provider,
-        model,
-        ...(options ? { options: options as ClaudeModelOptions } : {}),
-      };
-    case "cursor":
-      return {
-        provider,
-        model,
-        ...(options ? { options: options as CursorModelOptions } : {}),
-      };
-    case "opencode":
-      return {
-        provider,
-        model,
-        ...(options ? { options: options as OpenCodeModelOptions } : {}),
-      };
-    default:
-      return {
-        provider,
-        model,
-        ...(options ? { options } : {}),
-      } as ModelSelection;
-  }
+  return null;
 }
 
 export function applyClaudePromptEffortPrefix(
   text: string,
-  effort: ClaudeAgentEffort | null | undefined,
+  effort: string | null | undefined,
 ): string {
   const trimmed = text.trim();
   if (!trimmed) {
diff --git a/packages/shared/src/serverSettings.test.ts b/packages/shared/src/serverSettings.test.ts
index bbe5d8dc2af..3e8114f0dc2 100644
--- a/packages/shared/src/serverSettings.test.ts
+++ b/packages/shared/src/serverSettings.test.ts
@@ -1,5 +1,10 @@
-import { DEFAULT_SERVER_SETTINGS } from "@t3tools/contracts";
+import {
+  DEFAULT_SERVER_SETTINGS,
+  ProviderDriverKind,
+  ProviderInstanceId,
+} from "@t3tools/contracts";
 import { describe, expect, it } from "vitest";
+import { createModelSelection } from "./model.ts";
 import {
   applyServerSettingsPatch,
   extractPersistedServerObservabilitySettings,
@@ -56,25 +61,25 @@ describe("serverSettings helpers", () => {
   it("replaces text generation selection when provider/model are provided", () => {
     const current = {
       ...DEFAULT_SERVER_SETTINGS,
-      textGenerationModelSelection: {
-        provider: "codex" as const,
-        model: "gpt-5.4-mini",
-        options: {
-          reasoningEffort: "high" as const,
-          fastMode: true,
-        },
-      },
+      textGenerationModelSelection: createModelSelection(
+        ProviderInstanceId.make("codex"),
+        "gpt-5.4-mini",
+        [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ],
+      ),
     };
 
     expect(
       applyServerSettingsPatch(current, {
         textGenerationModelSelection: {
-          provider: "codex",
+          instanceId: ProviderInstanceId.make("codex"),
           model: "gpt-5.4-mini",
         },
       }).textGenerationModelSelection,
     ).toEqual({
-      provider: "codex",
+      instanceId: "codex",
       model: "gpt-5.4-mini",
     });
   });
@@ -82,57 +87,111 @@ describe("serverSettings helpers", () => {
   it("still deep merges text generation selection when only options are provided", () => {
     const current = {
       ...DEFAULT_SERVER_SETTINGS,
-      textGenerationModelSelection: {
-        provider: "codex" as const,
-        model: "gpt-5.4-mini",
-        options: {
-          reasoningEffort: "high" as const,
-          fastMode: true,
-        },
-      },
+      textGenerationModelSelection: createModelSelection(
+        ProviderInstanceId.make("codex"),
+        "gpt-5.4-mini",
+        [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ],
+      ),
     };
 
     expect(
       applyServerSettingsPatch(current, {
         textGenerationModelSelection: {
-          options: {
-            fastMode: false,
-          },
+          options: [{ id: "fastMode", value: false }],
         },
       }).textGenerationModelSelection,
     ).toEqual({
-      provider: "codex",
+      instanceId: "codex",
       model: "gpt-5.4-mini",
-      options: {
-        reasoningEffort: "high",
-        fastMode: false,
-      },
+      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: {
-        provider: "codex" as const,
-        model: "gpt-5.4-mini",
-        options: {
-          reasoningEffort: "high" as const,
-          fastMode: true,
-        },
-      },
+      textGenerationModelSelection: createModelSelection(
+        ProviderInstanceId.make("codex"),
+        "gpt-5.4-mini",
+        [
+          { id: "reasoningEffort", value: "high" },
+          { id: "fastMode", value: true },
+        ],
+      ),
     };
 
     expect(
       applyServerSettingsPatch(current, {
         textGenerationModelSelection: {
-          provider: "opencode",
+          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({
-      provider: "opencode",
+      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 784c90cfeec..655de4d92ad 100644
--- a/packages/shared/src/serverSettings.ts
+++ b/packages/shared/src/serverSettings.ts
@@ -1,31 +1,10 @@
-import {
-  ServerSettings,
-  type AmpModelOptions,
-  type ClaudeModelOptions,
-  type CodexModelOptions,
-  type CopilotModelOptions,
-  type CursorModelOptions,
-  type GeminiCliModelOptions,
-  type KiloModelOptions,
-  type OpenCodeModelOptions,
-  type ServerSettingsPatch,
-} from "@t3tools/contracts";
+import { ServerSettings, type ServerSettingsPatch } from "@t3tools/contracts";
 import { Schema } from "effect";
 import { deepMerge } from "./Struct.ts";
 import { fromLenientJson } from "./schemaJson.ts";
+import { createModelSelection } from "./model.ts";
 
-/** Narrow schema that only decodes the observability subtree, avoiding
- *  validation failures from unrelated ServerSettings fields. */
-const ObservabilitySubtreeJson = fromLenientJson(
-  Schema.Struct({
-    observability: Schema.optional(
-      Schema.Struct({
-        otlpTracesUrl: Schema.optional(Schema.String),
-        otlpMetricsUrl: Schema.optional(Schema.String),
-      }),
-    ),
-  }),
-);
+const ServerSettingsJson = fromLenientJson(ServerSettings);
 
 export interface PersistedServerObservabilitySettings {
   readonly otlpTracesUrl: string | undefined;
@@ -40,12 +19,10 @@ export function normalizePersistedServerSettingString(
 }
 
 export function extractPersistedServerObservabilitySettings(input: {
-  readonly observability?:
-    | {
-        readonly otlpTracesUrl?: string | undefined;
-        readonly otlpMetricsUrl?: string | undefined;
-      }
-    | undefined;
+  readonly observability?: {
+    readonly otlpTracesUrl?: string;
+    readonly otlpMetricsUrl?: string;
+  };
 }): PersistedServerObservabilitySettings {
   return {
     otlpTracesUrl: normalizePersistedServerSettingString(input.observability?.otlpTracesUrl),
@@ -57,7 +34,7 @@ export function parsePersistedServerObservabilitySettings(
   raw: string,
 ): PersistedServerObservabilitySettings {
   try {
-    const decoded = Schema.decodeUnknownSync(ObservabilitySubtreeJson)(raw);
+    const decoded = Schema.decodeUnknownSync(ServerSettingsJson)(raw);
     return extractPersistedServerObservabilitySettings(decoded);
   } catch {
     return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
@@ -67,11 +44,26 @@ export function parsePersistedServerObservabilitySettings(
 function shouldReplaceTextGenerationModelSelection(
   patch: ServerSettingsPatch["textGenerationModelSelection"] | undefined,
 ): boolean {
-  return Boolean(patch && (patch.provider !== undefined || patch.model !== undefined));
+  return Boolean(patch && (patch.instanceId !== undefined || patch.model !== undefined));
 }
 
-const withModelSelectionOptions = <Options>(options: Options | undefined) =>
-  options ? { options } : {};
+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
@@ -84,68 +76,28 @@ export function applyServerSettingsPatch(
 ): ServerSettings {
   const selectionPatch = patch.textGenerationModelSelection;
   const next = deepMerge(current, patch);
-  if (!selectionPatch || !shouldReplaceTextGenerationModelSelection(selectionPatch)) {
-    return next;
+  const nextWithReplacements =
+    patch.providerInstances !== undefined
+      ? {
+          ...next,
+          providerInstances: patch.providerInstances,
+        }
+      : next;
+  if (!selectionPatch) {
+    return nextWithReplacements;
   }
 
-  const provider = selectionPatch.provider ?? current.textGenerationModelSelection.provider;
+  const instanceId = selectionPatch.instanceId ?? current.textGenerationModelSelection.instanceId;
   const model = selectionPatch.model ?? current.textGenerationModelSelection.model;
-
-  const makeSelection = (): ServerSettings["textGenerationModelSelection"] => {
-    switch (provider) {
-      case "codex":
-        return {
-          provider,
-          model,
-          ...withModelSelectionOptions(selectionPatch.options as CodexModelOptions | undefined),
-        };
-      case "claudeAgent":
-        return {
-          provider,
-          model,
-          ...withModelSelectionOptions(selectionPatch.options as ClaudeModelOptions | undefined),
-        };
-      case "cursor":
-        return {
-          provider,
-          model,
-          ...withModelSelectionOptions(selectionPatch.options as CursorModelOptions | undefined),
-        };
-      case "opencode":
-        return {
-          provider,
-          model,
-          ...withModelSelectionOptions(selectionPatch.options as OpenCodeModelOptions | undefined),
-        };
-      case "copilot":
-        return {
-          provider,
-          model,
-          ...withModelSelectionOptions(selectionPatch.options as CopilotModelOptions | undefined),
-        };
-      case "geminiCli":
-        return {
-          provider,
-          model,
-          ...withModelSelectionOptions(selectionPatch.options as GeminiCliModelOptions | undefined),
-        };
-      case "amp":
-        return {
-          provider,
-          model,
-          ...withModelSelectionOptions(selectionPatch.options as AmpModelOptions | undefined),
-        };
-      case "kilo":
-        return {
-          provider,
-          model,
-          ...withModelSelectionOptions(selectionPatch.options as KiloModelOptions | undefined),
-        };
-    }
-  };
+  const options = shouldReplaceTextGenerationModelSelection(selectionPatch)
+    ? selectionPatch.options
+    : mergeModelSelectionOptionsById({
+        current: current.textGenerationModelSelection.options,
+        patch: selectionPatch.options,
+      });
 
   return {
-    ...next,
-    textGenerationModelSelection: makeSelection(),
+    ...nextWithReplacements,
+    textGenerationModelSelection: createModelSelection(instanceId, model, options),
   };
 }
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/ssh/package.json b/packages/ssh/package.json
new file mode 100644
index 00000000000..08793e67c1c
--- /dev/null
+++ b/packages/ssh/package.json
@@ -0,0 +1,46 @@
+{
+  "name": "@t3tools/ssh",
+  "version": "0.0.0-alpha.1",
+  "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": {
+    "prepare": "effect-language-service patch",
+    "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..f9fe311450d
--- /dev/null
+++ b/packages/ssh/src/auth.test.ts
@@ -0,0 +1,65 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import { Effect, FileSystem, Path } from "effect";
+
+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..7cb2de11ef5
--- /dev/null
+++ b/packages/ssh/src/auth.ts
@@ -0,0 +1,205 @@
+import { Context, Effect, FileSystem, Layer, Path, PlatformError } from "effect";
+
+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..22e93b69c43
--- /dev/null
+++ b/packages/ssh/src/command.test.ts
@@ -0,0 +1,151 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Duration, Effect, Fiber, Layer, Result, Sink, Stream } from "effect";
+import { TestClock } from "effect/testing";
+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..cadba077602
--- /dev/null
+++ b/packages/ssh/src/command.ts
@@ -0,0 +1,337 @@
+import * as Crypto from "node:crypto";
+
+import type { DesktopSshEnvironmentTarget, DesktopUpdateChannel } from "@t3tools/contracts";
+import { Duration, Effect, FileSystem, Option, Path, Scope, Stream } from "effect";
+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..0e2f5472ddf
--- /dev/null
+++ b/packages/ssh/src/config.test.ts
@@ -0,0 +1,136 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import { Effect, FileSystem, Path } from "effect";
+
+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..b326f66a468
--- /dev/null
+++ b/packages/ssh/src/config.ts
@@ -0,0 +1,251 @@
+import type { DesktopDiscoveredSshHost } from "@t3tools/contracts";
+
+import { Effect, FileSystem, Path, PlatformError } from "effect";
+
+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..b902ef82721
--- /dev/null
+++ b/packages/ssh/src/errors.ts
@@ -0,0 +1,46 @@
+import { Data } from "effect";
+
+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..f6c7598ef75
--- /dev/null
+++ b/packages/ssh/src/tunnel.test.ts
@@ -0,0 +1,294 @@
+import { assert, describe, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { NetService } from "@t3tools/shared/Net";
+import { Duration, Effect, Fiber, Layer, Result, Sink, Stream } from "effect";
+import { TestClock } from "effect/testing";
+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,
+  REMOTE_PICK_PORT_SCRIPT,
+  SshEnvironmentManager,
+  waitForHttpReady,
+} from "./tunnel.ts";
+
+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.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();
+
+    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'");
+  });
+
+  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(),
+      '[ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null',
+    );
+    assert.include(buildRemoteLaunchScript(), "RUNNER_CHANGED=1");
+    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(), "printf 'external\\n' >\"$MANAGED_FILE\"");
+    assert.isBelow(
+      buildRemoteLaunchScript().indexOf('if [ "$REMOTE_MANAGED" = "managed" ]'),
+      buildRemoteLaunchScript().indexOf("printf 'external\\n' >\"$MANAGED_FILE\""),
+    );
+    assert.isBelow(
+      buildRemoteLaunchScript().indexOf('DEFAULT_REMOTE_PORT="$(resolve_default_runtime_port'),
+      buildRemoteLaunchScript().indexOf('elif [ -n "$REMOTE_PID" ]'),
+    );
+  });
+
+  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("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, 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..302341d071e
--- /dev/null
+++ b/packages/ssh/src/tunnel.ts
@@ -0,0 +1,1584 @@
+import type {
+  DesktopSshEnvironmentBootstrap,
+  DesktopSshEnvironmentTarget,
+} from "@t3tools/contracts";
+import { type NetError, NetService } from "@t3tools/shared/Net";
+import { fromLenientJson } from "@t3tools/shared/schemaJson";
+import {
+  Deferred,
+  Context,
+  Duration,
+  Effect,
+  Exit,
+  FileSystem,
+  Layer,
+  Option,
+  Path,
+  Ref,
+  Schema,
+  Scope,
+  Schedule,
+  Stream,
+} from "effect";
+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;
+}
+
+export interface SshEnvironmentManagerOptions {
+  readonly resolveCliPackageSpec?: () => string;
+  readonly resolveCliRunner?: () => 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
+  | SshPasswordPrompt;
+
+type SshEnvironmentEffectError =
+  | SshCommandError
+  | SshInvalidTargetError
+  | SshLaunchError
+  | SshPairingError
+  | SshReadinessError
+  | SshPasswordPromptError
+  | 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));
+
+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_RUNNER_SCRIPT = `#!/bin/sh
+set -eu
+T3_NODE_SCRIPT_PATH=@@T3_NODE_SCRIPT_PATH@@
+if [ -n "$T3_NODE_SCRIPT_PATH" ]; then
+  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 npx and npm are unavailable on PATH.\\n' >&2
+exit 1
+`;
+
+export const REMOTE_LAUNCH_SCRIPT = `set -eu
+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"
+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) || !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(String(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_REMOTE_PORT="$(resolve_default_runtime_port 2>/dev/null || true)"
+if [ -n "$DEFAULT_REMOTE_PORT" ]; then
+  REMOTE_PORT="$DEFAULT_REMOTE_PORT"
+  if wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
+    if [ "$REMOTE_MANAGED" = "managed" ] && [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+      kill "$REMOTE_PID" 2>/dev/null || true
+      wait_for_pid_exit "$REMOTE_PID"
+    fi
+    printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+    printf 'external\\n' >"$MANAGED_FILE"
+    REMOTE_PID=""
+    REMOTE_MANAGED="external"
+  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_PID" ] || [ -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),
+    }),
+  );
+}
+
+export function buildRemoteLaunchScript(input?: RemoteT3RunnerOptions): string {
+  return applyScriptPlaceholders(REMOTE_LAUNCH_SCRIPT, {
+    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* decodeRemoteLaunchResult(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* decodeRemotePairingResult(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;
+  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
+  | 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;
+        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?.() ?? (packageSpec === undefined ? undefined : { packageSpec });
+    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..2f8e6d4df6d
--- /dev/null
+++ b/packages/ssh/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "diagnosticSeverity": {
+          "importFromBarrel": "error",
+          "anyUnknownInErrorContext": "warning",
+          "instanceOfSchema": "warning",
+          "deterministicKeys": "warning"
+        }
+      }
+    ]
+  },
+  "include": ["src"]
+}
diff --git a/packages/tailscale/package.json b/packages/tailscale/package.json
new file mode 100644
index 00000000000..7088559c74a
--- /dev/null
+++ b/packages/tailscale/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@t3tools/tailscale",
+  "version": "0.0.0-alpha.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "prepare": "effect-language-service patch",
+    "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..149525a03f4
--- /dev/null
+++ b/packages/tailscale/src/tailscale.test.ts
@@ -0,0 +1,141 @@
+import { assert, describe, it } from "@effect/vitest";
+import { Effect, Layer, Sink, Stream } from "effect";
+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..e90299d3ac1
--- /dev/null
+++ b/packages/tailscale/src/tailscale.ts
@@ -0,0 +1,320 @@
+import { Data, Effect, Option, Schema, Stream } from "effect";
+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..2f8e6d4df6d
--- /dev/null
+++ b/packages/tailscale/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "diagnosticSeverity": {
+          "importFromBarrel": "error",
+          "anyUnknownInErrorContext": "warning",
+          "instanceOfSchema": "warning",
+          "deterministicKeys": "warning"
+        }
+      }
+    ]
+  },
+  "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..1bbdd237c22
--- /dev/null
+++ b/scripts/apply-web-brand-assets.ts
@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Effect, FileSystem, Option, Path } from "effect";
+import { Argument, Command } from "effect/unstable/cli";
+import { resolveWebIconOverrides, type WebAssetBrand } from "./lib/brand-assets.ts";
+
+const WEB_ASSET_BRANDS = [
+  "development",
+  "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."),
+    ),
+    targetDirectory: Argument.string("target-directory").pipe(
+      Argument.withDescription("Output directory that contains the hosted web build assets."),
+      Argument.optional,
+    ),
+  },
+  ({ brand, targetDirectory }) =>
+    applyWebBrandAssets(
+      brand,
+      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/lib/brand-assets.test.ts b/scripts/lib/brand-assets.test.ts
new file mode 100644
index 00000000000..8c85455185e
--- /dev/null
+++ b/scripts/lib/brand-assets.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  BRAND_ASSET_PATHS,
+  DEVELOPMENT_ICON_OVERRIDES,
+  PUBLISH_ICON_OVERRIDES,
+  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",
+    });
+  });
+});
diff --git a/scripts/lib/brand-assets.ts b/scripts/lib/brand-assets.ts
index 3cc91044d98..f671b846e8a 100644
--- a/scripts/lib/brand-assets.ts
+++ b/scripts/lib/brand-assets.ts
@@ -20,45 +20,60 @@ export const BRAND_ASSET_PATHS = {
   developmentWebAppleTouchIconPng: "assets/dev/blueprint-web-apple-touch-180.png",
 } as const;
 
+export type WebAssetBrand = "development" | "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",
+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.productionWebFavicon16Png,
-    targetRelativePath: "dist/client/favicon-16x16.png",
+  production: {
+    faviconIco: BRAND_ASSET_PATHS.productionWebFaviconIco,
+    favicon16Png: BRAND_ASSET_PATHS.productionWebFavicon16Png,
+    favicon32Png: BRAND_ASSET_PATHS.productionWebFavicon32Png,
+    appleTouchIconPng: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
   },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon32Png,
-    targetRelativePath: "dist/client/favicon-32x32.png",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
-    targetRelativePath: "dist/client/apple-touch-icon.png",
-  },
-];
+} 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/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..cb4ed0384db
--- /dev/null
+++ b/scripts/notify-discord-release.ts
@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Config, Data, Effect, Layer, Logger, Schema } from "effect";
+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 payload = buildDiscordReleaseAnnouncement({
+        target,
+        roleId,
+        releaseName,
+        version: releaseVersion,
+        tag,
+        releaseUrl,
+        timestamp: new Date().toISOString(),
+      });
+
+      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/release-smoke.ts b/scripts/release-smoke.ts
index 1736abab378..0bdf8b32afa 100644
--- a/scripts/release-smoke.ts
+++ b/scripts/release-smoke.ts
@@ -24,6 +24,8 @@ const workspaceFiles = [
   "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",
@@ -36,6 +38,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 } {
@@ -292,7 +305,7 @@ try {
           fi
 
           found_windows_manifest=true
-          node ${JSON.stringify(resolve(repoRoot, "scripts/merge-update-manifests.ts"))} --platform win \
+          ${JSON.stringify(process.execPath)} ${JSON.stringify(resolve(repoRoot, "scripts/merge-update-manifests.ts"))} --platform win \
             "$arm64_manifest" \
             "$x64_manifest" \
             "$output_manifest"
diff --git a/turbo.json b/turbo.json
index e6ebeee912f..0b19d93c4ae 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",