diff --git a/.gitattributes b/.gitattributes
index c7612b2aeaf8..d72319addcf3 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,3 +1,6 @@
 # git autocrlf=true converts LF to CRLF on Windows, causing issues with oxfmt
 * text=auto eol=lf
+# Batch files need CRLF for cmd.exe to parse them reliably.
+*.cmd text eol=crlf
+*.bat text eol=crlf
 patches/*.patch whitespace=-trailing-space,-space-before-tab
diff --git a/.github/actions/setup-apt-mirrors/action.yml b/.github/actions/setup-apt-mirrors/action.yml
new file mode 100644
index 000000000000..5beff201d188
--- /dev/null
+++ b/.github/actions/setup-apt-mirrors/action.yml
@@ -0,0 +1,22 @@
+name: Setup APT mirrors
+description: Configure Ubuntu package downloads with automatic mirror failover.
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        # Replace the existing Blacksmith mirror list as well as direct sources.
+        printf '%s\tpriority:%s\n' \
+          https://archive.ubuntu.com/ubuntu 1 \
+          https://mirrors.edge.kernel.org/ubuntu 2 \
+          https://mirror.math.princeton.edu/pub/ubuntu 3 \
+          | sudo tee /etc/apt/blacksmith-ubuntu-mirrors.txt > /dev/null
+
+        # APT's mirror transport retries each file against the next server.
+        sudo find /etc/apt -maxdepth 2 -type f \( -name '*.list' -o -name '*.sources' \) \
+          -exec sed -i -E \
+          's#https?://(([^/]+\.)?archive|security)\.ubuntu\.com/ubuntu/?#mirror+file:/etc/apt/blacksmith-ubuntu-mirrors.txt#g' {} +
+
+        # Move on to a fallback before an unreachable server exhausts the job.
+        printf '%s\n' 'Acquire::http::Timeout "15";' 'Acquire::https::Timeout "15";' \
+          | sudo tee /etc/apt/apt.conf.d/80-mirror-timeouts > /dev/null
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7fee5f57a83c..4bcb1e21ab99 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -45,14 +45,22 @@ jobs:
       - name: Ensure Electron runtime is installed
         run: vp run --filter @t3tools/desktop ensure:electron
 
+      # Files/dependencies are repo-wide; export checks cover clean workspaces only.
+      - name: Check unused code
+        run: vp run knip:check
+
       - name: Check
         run: vp check
 
       - name: Typecheck
         run: vpr typecheck
 
+      - uses: ./.github/actions/setup-apt-mirrors
+
       - name: Install browser secret helper build libraries
-        run: sudo apt-get update && sudo apt-get install -y libsecret-1-dev pkg-config
+        run: |
+          sudo sed -i 's|http://|https://|g' /etc/apt/blacksmith-ubuntu-mirrors.txt /etc/apt/sources.list.d/ubuntu.sources
+          sudo apt-get update && sudo apt-get install -y libsecret-1-dev pkg-config
 
       - name: Build desktop pipeline
         run: vp run build:desktop
@@ -88,8 +96,12 @@ jobs:
       - name: Ensure Electron runtime is installed
         run: vp run --filter @t3tools/desktop ensure:electron
 
+      - uses: ./.github/actions/setup-apt-mirrors
+
       - name: Install browser secret helper build libraries
-        run: sudo apt-get update && sudo apt-get install -y libsecret-1-dev pkg-config
+        run: |
+          sudo sed -i 's|http://|https://|g' /etc/apt/blacksmith-ubuntu-mirrors.txt /etc/apt/sources.list.d/ubuntu.sources
+          sudo apt-get update && sudo apt-get install -y libsecret-1-dev pkg-config
 
       - name: Test
         run: vp run --parallel --concurrency-limit 4 --filter '!t3' --filter '!@t3tools/monorepo' test
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 404e4e8075cc..2785ecb8fa78 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -216,6 +216,8 @@ jobs:
       - name: Typecheck
         run: vp run typecheck
 
+      - uses: ./.github/actions/setup-apt-mirrors
+
       - name: Install browser secret helper build libraries
         run: sudo apt-get update && sudo apt-get install -y libsecret-1-dev pkg-config
 
@@ -519,7 +521,7 @@ jobs:
           $setupExe = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\setup.exe"
           $proc = Start-Process -FilePath $setupExe `
             -ArgumentList "modify", "--installPath", "`"$installPath`"", "--add", `
-            "Microsoft.VisualStudio.Component.VC.Tools.x86.x64.Spectre", "--quiet", "--norestart" `
+            "Microsoft.VisualStudio.Component.VC.Runtimes.x86.x64.Spectre", "--quiet", "--norestart" `
             -Wait -PassThru -NoNewWindow
           if ($null -eq $proc -or $proc.ExitCode -ne 0) {
             $code = if ($null -ne $proc) { $proc.ExitCode } else { 1 }
@@ -527,6 +529,9 @@ jobs:
             exit $code
           }
 
+      - uses: ./.github/actions/setup-apt-mirrors
+        if: matrix.platform == 'linux'
+
       - name: Install Linux desktop build libraries
         if: matrix.platform == 'linux'
         shell: bash
diff --git a/AGENTS.md b/AGENTS.md
index 97ff25bde3cf..f9102ba145ed 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,7 +86,7 @@ The most common defect in this repo is a change that works on the path you teste
 - **Contracts.** Anything crossing the wire is typed in `packages/contracts`. Change the schema and the server, web, mobile, and desktop all follow.
 - **Reverse states.** If you added a way in, add the way out and the way to see it. Snooze needs unsnooze. Close needs reopen. A one-way door is a bug.
 - **Connection modes.** Local, remote/relay, and tunnel behave differently. Multi-device and multi-environment cases are real.
-- **Docs.** `docs/` splits by audience. Behavior changes that a user would notice belong in `docs/user/` (shipped-product voice, no repo tooling or source paths); architecture and contributor changes in `docs/internals/`; runbooks in `docs/operations/`; new vocabulary in `docs/internals/glossary.md`.
+- **Docs.** Check whether the change makes existing guidance inaccurate. Apply the [documentation rules](#documentation) before adding anything.
 
 ## Dev servers
 
@@ -134,11 +134,22 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
 - One concern per PR. If the description says "also", split it.
 - When babysitting: poll checks and comments newer than the last push, verify each bot finding against the source, fix real ones, dismiss false positives with a written reason. Stay quiet when nothing is new. Stop when the bots are green on the latest commit.
 
+## Documentation
+
+Most code changes do not need an internal documentation change. Agents can read the code.
+
+- `docs/internals/` is for architectural decisions and their reasons, constraints that span components, and implementation traps that are hard to discover from the source. Before adding a paragraph, ask what a maintainer would get wrong without it. If reading the relevant code answers the question, leave it out.
+- Do not document every feature, enumerate fields or methods, narrate control flow, maintain file catalogs, or append PR summaries. Types, tests, and code already record the implementation. The glossary defines shared vocabulary; it is not a feature index.
+- Keep a local implementation explanation in a nearby code comment. Use an internal doc when the reasoning crosses boundaries or needs context the code cannot carry well. Link to the relevant source instead of copying it.
+- When a documented decision or constraint changes, rewrite or remove the affected text. Do not append another account of the new behavior. A new internal page needs a distinct, durable reason to exist.
+- `docs/user/` helps users accomplish tasks. Give each major feature a concise section explaining what it does, how to start, and anything unintuitive. A settings path is useful; descriptions of visible buttons, icons, layouts, animations, or every UI state are not. Before adding text, ask what task or decision it helps the user with.
+- Keep user docs in the shipped product's voice, without implementation details or contributor tooling. Update the relevant feature section when how to use it changes. A UI tweak does not need a documentation entry, and a new control does not need its own page.
+- `docs/operations/` holds maintainer setup, release, and debugging procedures. Keep instructions for operating an installed T3 Code server in the user guides.
+
 ## Plans and work artifacts
 
 - Do not commit implementation plans, research notes, or agent scratch files. Keep temporary working material outside the worktree. `.plans/` is gitignored only as a safety net for legacy tooling.
 - Track active maintainer work in the GitHub issue or project item that owns it. External proposals follow `CONTRIBUTING.md` and belong in Ideas discussions.
-- Put durable architecture, constraints, and decisions in `docs/internals/`. Update those docs when the product changes so agents find current facts instead of abandoned intentions.
 - A merged PR is the implementation record. Close or update its tracking item when the work lands; do not preserve a second checklist in the repository.
 
 ## How it works
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6cdb8ebcd540..c15dcbf346ee 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
 
 ## Developer Setup
 
-See the [maintainer scripts guide](docs/internals/scripts.md#first-checkout) for the initial checkout,
+See the [development runbook](docs/operations/development.md#first-checkout) for the initial checkout,
 development commands, tests, and platform-specific desktop packaging prerequisites.
 
 ## Read This First
@@ -53,6 +53,10 @@ Explain exactly what changed.
 
 Explain exactly why the change should exist.
 
+Follow the [documentation rules](AGENTS.md#documentation). Keep internal docs for decisions and
+hard-to-discover constraints. Update user guides when how to use a feature changes; skip descriptions
+of obvious controls and cosmetic changes.
+
 Do not mix unrelated fixes together.
 
 If the PR makes anything resembling a UI change, include clear before/after images.
diff --git a/README.md b/README.md
index e959d66d8115..b3c74fd295c0 100644
--- a/README.md
+++ b/README.md
@@ -117,12 +117,12 @@ Full docs live in [docs/](./docs). There's no docs site yet.
 - [Install and first run](./docs/user/install.md)
 - [Permission modes](./docs/user/permission-modes.md)
 - [Keyboard shortcuts](./docs/user/keybindings.md)
-- [Customize a project icon](./docs/user/project-settings.md)
+- [Project settings](./docs/user/project-settings.md)
 - [Remote access from a phone or another machine](./docs/user/remote-access.md)
 - [Keeping app and server in sync](./docs/user/updating.md)
 - [Source control integrations](./docs/user/source-control.md)
 - Multiple accounts: [Codex](./docs/user/providers-codex.md) · [Claude](./docs/user/providers-claude.md)
-- Linux: [run T3 Code as a background service](./docs/user/background-service.md)
+- [Run T3 Code as a background service](./docs/user/background-service.md)
 
 Building from source? Start at [docs/internals/overview.md](./docs/internals/overview.md).
 
diff --git a/apps/desktop/scripts/electron-launcher.mjs b/apps/desktop/scripts/electron-launcher.mjs
index 07fb87b051f1..496a8a27a7b6 100644
--- a/apps/desktop/scripts/electron-launcher.mjs
+++ b/apps/desktop/scripts/electron-launcher.mjs
@@ -165,10 +165,14 @@ function registerMacLauncherBundle(appBundlePath) {
   }
 }
 
+// Bundle-internal paths are macOS paths whatever host builds them.
 export function resolveMacLauncherIconPaths(runtimeDir, development = isDevelopment) {
   return {
     sourceIconPath: development ? developmentMacIconPngPath : productionMacIconPngPath,
-    generatedIconPath: NodePath.join(runtimeDir, development ? "icon-dev.icns" : "icon-prod.icns"),
+    generatedIconPath: NodePath.posix.join(
+      runtimeDir,
+      development ? "icon-dev.icns" : "icon-prod.icns",
+    ),
   };
 }
 
@@ -280,12 +284,12 @@ function readJson(path) {
 }
 
 export function resolveMacLauncherPaths(appBundlePath, displayName = APP_DISPLAY_NAME) {
-  const executableDir = NodePath.join(appBundlePath, "Contents", "MacOS");
+  const executableDir = NodePath.posix.join(appBundlePath, "Contents", "MacOS");
   const launcherExecutableName = `${displayName} Launcher`;
   return {
     launcherExecutableName,
-    launcherBinaryPath: NodePath.join(executableDir, launcherExecutableName),
-    runtimeElectronBinaryPath: NodePath.join(executableDir, "Electron"),
+    launcherBinaryPath: NodePath.posix.join(executableDir, launcherExecutableName),
+    runtimeElectronBinaryPath: NodePath.posix.join(executableDir, "Electron"),
   };
 }
 
diff --git a/apps/desktop/scripts/electron-launcher.test.mjs b/apps/desktop/scripts/electron-launcher.test.mjs
index 1ed5a1b8ebf9..9d2a907c73d6 100644
--- a/apps/desktop/scripts/electron-launcher.test.mjs
+++ b/apps/desktop/scripts/electron-launcher.test.mjs
@@ -84,9 +84,10 @@ describe("electron development launcher", () => {
     const development = resolveMacLauncherIconPaths("/runtime", true);
     const production = resolveMacLauncherIconPaths("/runtime", false);
 
-    assert.match(development.sourceIconPath, /assets\/dev\/blueprint-macos-1024\.png$/);
+    // The source icons are real repo paths, joined for the host.
+    assert.match(development.sourceIconPath, /assets[\\/]dev[\\/]blueprint-macos-1024\.png$/);
     assert.equal(development.generatedIconPath, "/runtime/icon-dev.icns");
-    assert.match(production.sourceIconPath, /assets\/prod\/black-macos-1024\.png$/);
+    assert.match(production.sourceIconPath, /assets[\\/]prod[\\/]black-macos-1024\.png$/);
     assert.equal(production.generatedIconPath, "/runtime/icon-prod.icns");
   });
 });
diff --git a/apps/desktop/src/app/DesktopAppIdentity.test.ts b/apps/desktop/src/app/DesktopAppIdentity.test.ts
index 5c39ff304b3b..71bcf5f7aef1 100644
--- a/apps/desktop/src/app/DesktopAppIdentity.test.ts
+++ b/apps/desktop/src/app/DesktopAppIdentity.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -88,6 +89,7 @@ const makeEnvironmentLayer = (overrides: TestEnvironmentInput = {}) => {
     Layer.provide(
       Layer.mergeAll(
         NodeServices.layer,
+        NodePath.layerPosix,
         DesktopConfig.layerTest({
           ...env,
         }),
diff --git a/apps/desktop/src/app/DesktopAssets.test.ts b/apps/desktop/src/app/DesktopAssets.test.ts
index bb118d43d29a..78819d06e6cc 100644
--- a/apps/desktop/src/app/DesktopAssets.test.ts
+++ b/apps/desktop/src/app/DesktopAssets.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -20,7 +21,11 @@ const environmentLayer = DesktopEnvironment.layer({
   isPackaged: true,
   resourcesPath: "/Applications/T3 Code.app/Contents/Resources",
   runningUnderArm64Translation: false,
-}).pipe(Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest({}))));
+}).pipe(
+  Layer.provide(
+    Layer.mergeAll(NodeServices.layer, NodePath.layerPosix, DesktopConfig.layerTest({})),
+  ),
+);
 
 describe("DesktopAssets", () => {
   it.effect("uses canonical source-tree icons for unpackaged development", () =>
@@ -39,6 +44,7 @@ describe("DesktopAssets", () => {
         Layer.provide(
           Layer.mergeAll(
             NodeServices.layer,
+            NodePath.layerPosix,
             DesktopConfig.layerTest({ VITE_DEV_SERVER_URL: "http://localhost:5733" }),
           ),
         ),
diff --git a/apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts b/apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts
index c58830b30a7f..aa28ff8d86eb 100644
--- a/apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts
+++ b/apps/desktop/src/app/DesktopConnectionCatalogStore.test.ts
@@ -4,6 +4,7 @@ import { ConnectionCatalogDocument } from "@t3tools/client-runtime/platform";
 import { EnvironmentId, type PersistedSavedEnvironmentRecord } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as PlatformError from "effect/PlatformError";
@@ -226,10 +227,11 @@ describe("DesktopConnectionCatalogStore", () => {
   it.effect("surfaces malformed catalog documents without deleting them", () =>
     withStore(
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const environment = yield* DesktopEnvironment.DesktopEnvironment;
         const fileSystem = yield* FileSystem.FileSystem;
         const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
-        const catalogPath = `${environment.stateDir}/connection-catalog.json`;
+        const catalogPath = path.join(environment.stateDir, "connection-catalog.json");
         yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
         yield* fileSystem.writeFileString(catalogPath, "{not-json");
 
@@ -247,6 +249,7 @@ describe("DesktopConnectionCatalogStore", () => {
 
   it.effect("surfaces catalog filesystem failures instead of treating them as missing", () =>
     Effect.gen(function* () {
+      const path = yield* Path.Path;
       const baseFileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-connection-catalog-test-",
@@ -255,7 +258,7 @@ describe("DesktopConnectionCatalogStore", () => {
         _tag: "PermissionDenied",
         module: "FileSystem",
         method: "readFileString",
-        pathOrDescriptor: `${baseDir}/userdata/connection-catalog.json`,
+        pathOrDescriptor: path.join(baseDir, "userdata", "connection-catalog.json"),
       });
       const fileSystemLayer = Layer.succeed(
         FileSystem.FileSystem,
@@ -272,11 +275,11 @@ describe("DesktopConnectionCatalogStore", () => {
         error,
         DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreReadError,
       );
-      assert.equal(error.catalogPath, `${baseDir}/userdata/connection-catalog.json`);
+      assert.equal(error.catalogPath, path.join(baseDir, "userdata", "connection-catalog.json"));
       assert.strictEqual(error.cause, permissionError);
       assert.equal(
         error.message,
-        `Failed to read the desktop connection catalog at ${baseDir}/userdata/connection-catalog.json.`,
+        `Failed to read the desktop connection catalog at ${path.join(baseDir, "userdata", "connection-catalog.json")}.`,
       );
       assert.notEqual(error.message, permissionError.message);
     }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
@@ -285,6 +288,7 @@ describe("DesktopConnectionCatalogStore", () => {
   it.effect("reports the failed catalog write operation and path", () =>
     Effect.gen(function* () {
       const baseFileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
       const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-connection-catalog-test-",
       });
@@ -292,7 +296,7 @@ describe("DesktopConnectionCatalogStore", () => {
         _tag: "PermissionDenied",
         module: "FileSystem",
         method: "makeDirectory",
-        pathOrDescriptor: `${baseDir}/userdata`,
+        pathOrDescriptor: path.join(baseDir, "userdata"),
       });
       const fileSystemLayer = Layer.succeed(
         FileSystem.FileSystem,
@@ -310,11 +314,11 @@ describe("DesktopConnectionCatalogStore", () => {
         DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreWriteError,
       );
       assert.equal(error.operation, "create-directory");
-      assert.equal(error.path, `${baseDir}/userdata`);
+      assert.equal(error.path, path.join(baseDir, "userdata"));
       assert.strictEqual(error.cause, permissionError);
       assert.equal(
         error.message,
-        `Desktop connection catalog write failed during create-directory at ${baseDir}/userdata.`,
+        `Desktop connection catalog write failed during create-directory at ${path.join(baseDir, "userdata")}.`,
       );
       assert.notEqual(error.message, permissionError.message);
     }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
@@ -323,6 +327,7 @@ describe("DesktopConnectionCatalogStore", () => {
   it.effect("reports the legacy migration stage", () =>
     withStore(
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const environment = yield* DesktopEnvironment.DesktopEnvironment;
         const fileSystem = yield* FileSystem.FileSystem;
         const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
@@ -335,7 +340,7 @@ describe("DesktopConnectionCatalogStore", () => {
           DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreMigrationError,
         );
         assert.equal(error.operation, "read-legacy-registry");
-        assert.equal(error.catalogPath, `${environment.stateDir}/connection-catalog.json`);
+        assert.equal(error.catalogPath, path.join(environment.stateDir, "connection-catalog.json"));
         assert.instanceOf(
           error.cause,
           DesktopSavedEnvironments.DesktopSavedEnvironmentsDocumentDecodeError,
@@ -345,7 +350,7 @@ describe("DesktopConnectionCatalogStore", () => {
         assert.exists(registryError.cause);
         assert.equal(
           error.message,
-          `Legacy desktop saved-environment migration failed during read-legacy-registry into ${environment.stateDir}/connection-catalog.json.`,
+          `Legacy desktop saved-environment migration failed during read-legacy-registry into ${path.join(environment.stateDir, "connection-catalog.json")}.`,
         );
         assert.notEqual(error.message, registryError.message);
       }),
@@ -355,10 +360,11 @@ describe("DesktopConnectionCatalogStore", () => {
   it.effect("reports invalid encrypted catalog data without exposing it", () =>
     withStore(
       Effect.gen(function* () {
+        const path = yield* Path.Path;
         const environment = yield* DesktopEnvironment.DesktopEnvironment;
         const fileSystem = yield* FileSystem.FileSystem;
         const store = yield* DesktopConnectionCatalogStore.DesktopConnectionCatalogStore;
-        const catalogPath = `${environment.stateDir}/connection-catalog.json`;
+        const catalogPath = path.join(environment.stateDir, "connection-catalog.json");
         yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
         yield* fileSystem.writeFileString(catalogPath, '{"version":1,"encryptedCatalog":"%%%"}\n');
 
@@ -381,6 +387,7 @@ describe("DesktopConnectionCatalogStore", () => {
 
   it.effect("surfaces a catalog that can no longer be decrypted without deleting it", () =>
     Effect.gen(function* () {
+      const path = yield* Path.Path;
       const fileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* fileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-connection-catalog-test-",
@@ -399,14 +406,14 @@ describe("DesktopConnectionCatalogStore", () => {
         DesktopConnectionCatalogStore.DesktopConnectionCatalogStoreProtectionError,
       );
       assert.equal(error.operation, "decrypt-catalog");
-      assert.equal(error.catalogPath, `${baseDir}/userdata/connection-catalog.json`);
+      assert.equal(error.catalogPath, path.join(baseDir, "userdata", "connection-catalog.json"));
       assert.instanceOf(error.cause, ElectronSafeStorage.ElectronSafeStorageDecryptError);
       const decryptError = error.cause as ElectronSafeStorage.ElectronSafeStorageDecryptError;
       assert.instanceOf(decryptError.cause, Error);
       assert.equal(decryptError.cause.message, "invalid encrypted catalog");
       assert.equal(
         error.message,
-        `Desktop connection catalog protection failed during decrypt-catalog at ${baseDir}/userdata/connection-catalog.json.`,
+        `Desktop connection catalog protection failed during decrypt-catalog at ${path.join(baseDir, "userdata", "connection-catalog.json")}.`,
       );
       assert.notEqual(error.message, decryptError.message);
       yield* Ref.set(failDecrypt, false);
diff --git a/apps/desktop/src/app/DesktopEnvironment.test.ts b/apps/desktop/src/app/DesktopEnvironment.test.ts
index 218e2c3e4ba2..89cc592831a7 100644
--- a/apps/desktop/src/app/DesktopEnvironment.test.ts
+++ b/apps/desktop/src/app/DesktopEnvironment.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -26,7 +27,11 @@ const makeEnvironmentLayer = (
   DesktopEnvironment.layer({
     ...defaultInput,
     ...overrides,
-  }).pipe(Layer.provide(Layer.mergeAll(NodeServices.layer, DesktopConfig.layerTest(env))));
+  }).pipe(
+    Layer.provide(
+      Layer.mergeAll(NodeServices.layer, NodePath.layerPosix, DesktopConfig.layerTest(env)),
+    ),
+  );
 
 const makeEnvironment = (
   overrides: Partial<DesktopEnvironment.MakeDesktopEnvironmentInput> = {},
diff --git a/apps/desktop/src/backend/DesktopServerExposure.test.ts b/apps/desktop/src/backend/DesktopServerExposure.test.ts
index dcfee93778d1..4a8b516cb936 100644
--- a/apps/desktop/src/backend/DesktopServerExposure.test.ts
+++ b/apps/desktop/src/backend/DesktopServerExposure.test.ts
@@ -272,8 +272,6 @@ describe("DesktopServerExposure", () => {
           modeError,
           DesktopServerExposure.DesktopServerExposureModePersistenceError,
         );
-        assert.isTrue(DesktopServerExposure.isDesktopServerExposureSetModeError(modeError));
-        assert.isTrue(DesktopServerExposure.isDesktopServerExposureError(modeError));
         assert.equal(modeError.mode, "network-accessible");
         assert.strictEqual(modeError.cause, settingsFailure);
         assert.strictEqual(modeError.cause.cause, diskFailure);
@@ -290,7 +288,6 @@ describe("DesktopServerExposure", () => {
           tailscaleError,
           DesktopServerExposure.DesktopTailscaleServePersistenceError,
         );
-        assert.isTrue(DesktopServerExposure.isDesktopServerExposureError(tailscaleError));
         assert.equal(tailscaleError.enabled, true);
         assert.equal(tailscaleError.port, 8443);
         assert.strictEqual(tailscaleError.cause, settingsFailure);
diff --git a/apps/desktop/src/backend/DesktopServerExposure.ts b/apps/desktop/src/backend/DesktopServerExposure.ts
index f04d2af7b1f6..6c3cd55527eb 100644
--- a/apps/desktop/src/backend/DesktopServerExposure.ts
+++ b/apps/desktop/src/backend/DesktopServerExposure.ts
@@ -244,7 +244,6 @@ export const DesktopServerExposureSetModeError = Schema.Union([
   DesktopServerExposureModePersistenceError,
 ]);
 export type DesktopServerExposureSetModeError = typeof DesktopServerExposureSetModeError.Type;
-export const isDesktopServerExposureSetModeError = Schema.is(DesktopServerExposureSetModeError);
 
 export const DesktopServerExposureError = Schema.Union([
   DesktopServerExposureNoNetworkAddressError,
@@ -252,7 +251,6 @@ export const DesktopServerExposureError = Schema.Union([
   DesktopTailscaleServePersistenceError,
 ]);
 export type DesktopServerExposureError = typeof DesktopServerExposureError.Type;
-export const isDesktopServerExposureError = Schema.is(DesktopServerExposureError);
 
 export interface DesktopServerExposureBackendConfig {
   readonly port: number;
diff --git a/apps/desktop/src/electron/ElectronDialog.test.ts b/apps/desktop/src/electron/ElectronDialog.test.ts
index 3acaf7154508..2ed5a1f2f913 100644
--- a/apps/desktop/src/electron/ElectronDialog.test.ts
+++ b/apps/desktop/src/electron/ElectronDialog.test.ts
@@ -43,7 +43,6 @@ describe("ElectronDialog", () => {
       );
 
       assert.instanceOf(error, ElectronDialog.ElectronDialogPickFolderError);
-      assert.isTrue(ElectronDialog.isElectronDialogError(error));
       assert.strictEqual(error.ownerWindowId, 7);
       assert.strictEqual(error.defaultPath, "/workspace");
       assert.strictEqual(error.cause, cause);
diff --git a/apps/desktop/src/electron/ElectronDialog.ts b/apps/desktop/src/electron/ElectronDialog.ts
index 4300d9ab0d39..30ca73a5e143 100644
--- a/apps/desktop/src/electron/ElectronDialog.ts
+++ b/apps/desktop/src/electron/ElectronDialog.ts
@@ -73,7 +73,6 @@ export const ElectronDialogError = Schema.Union([
   ElectronDialogShowErrorBoxError,
 ]);
 export type ElectronDialogError = typeof ElectronDialogError.Type;
-export const isElectronDialogError = Schema.is(ElectronDialogError);
 
 export interface ElectronDialogPickFolderInput {
   readonly owner: Option.Option<Electron.BrowserWindow>;
diff --git a/apps/desktop/src/electron/ElectronShell.test.ts b/apps/desktop/src/electron/ElectronShell.test.ts
index 9ae6f502b000..17f3e06039b6 100644
--- a/apps/desktop/src/electron/ElectronShell.test.ts
+++ b/apps/desktop/src/electron/ElectronShell.test.ts
@@ -36,6 +36,20 @@ describe("ElectronShell", () => {
     }).pipe(Effect.provide(ElectronShell.layer)),
   );
 
+  it.effect("opens the Full Disk Access settings anchor", () =>
+    Effect.gen(function* () {
+      openExternalMock.mockResolvedValue(undefined);
+
+      const electronShell = yield* ElectronShell.ElectronShell;
+      const result = yield* electronShell.openSystemSettings("full-disk-access");
+
+      assert.equal(result, true);
+      assert.deepEqual(openExternalMock.mock.calls, [
+        ["x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_AllFiles"],
+      ]);
+    }).pipe(Effect.provide(ElectronShell.layer)),
+  );
+
   it.effect("opens remote SSH editor URLs", () =>
     Effect.gen(function* () {
       openExternalMock.mockResolvedValue(undefined);
diff --git a/apps/desktop/src/electron/ElectronShell.ts b/apps/desktop/src/electron/ElectronShell.ts
index 2ed13bfebd0f..0ac4f8f9cc6a 100644
--- a/apps/desktop/src/electron/ElectronShell.ts
+++ b/apps/desktop/src/electron/ElectronShell.ts
@@ -1,4 +1,8 @@
-import { REMOTE_CAPABLE_EDITOR_IDS, remoteSchemeForEditor } from "@t3tools/contracts";
+import {
+  REMOTE_CAPABLE_EDITOR_IDS,
+  remoteSchemeForEditor,
+  type SystemSettingsPane,
+} from "@t3tools/contracts";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -6,6 +10,20 @@ import * as Option from "effect/Option";
 
 import * as Electron from "electron";
 
+/**
+ * Deep links to individual System Settings panes. These are app-fixed, not
+ * renderer-supplied, so they skip `parseSafeExternalUrl` — which exists to keep
+ * arbitrary link schemes from reaching the OS handler — and open through their
+ * own path below. The pane rather than the URL crosses the IPC boundary, so a
+ * renderer can only ask for one of these known destinations.
+ *
+ * Full Disk Access uses the post-Ventura `PrivacySecurity.extension` anchor.
+ */
+const SYSTEM_SETTINGS_URLS: Record<SystemSettingsPane, string> = {
+  "full-disk-access":
+    "x-apple.systempreferences:com.apple.settings.PrivacySecurity.extension?Privacy_AllFiles",
+};
+
 // Remote open-in-editor deep links (`vscode://vscode-remote/ssh-remote+…`)
 // must reach the OS handler; every other non-web scheme stays blocked.
 const SAFE_WEB_PROTOCOLS = new Set(["http:", "https:"]);
@@ -43,6 +61,8 @@ export class ElectronShell extends Context.Service<
   ElectronShell,
   {
     readonly openExternal: (rawUrl: unknown) => Effect.Effect<boolean>;
+    /** Opens a known System Settings pane by identifier, not by URL. */
+    readonly openSystemSettings: (pane: SystemSettingsPane) => Effect.Effect<boolean>;
     readonly copyText: (text: string) => Effect.Effect<void>;
   }
 >()("@t3tools/desktop/electron/ElectronShell") {}
@@ -59,6 +79,13 @@ export const make = ElectronShell.of({
           ),
         ),
     }),
+  openSystemSettings: (pane) =>
+    Effect.promise(() =>
+      Electron.shell.openExternal(SYSTEM_SETTINGS_URLS[pane]).then(
+        () => true,
+        () => false,
+      ),
+    ),
   copyText: (text) =>
     Effect.sync(() => {
       Electron.clipboard.writeText(text);
diff --git a/apps/desktop/src/electron/ElectronTheme.test.ts b/apps/desktop/src/electron/ElectronTheme.test.ts
index 4b81943eff2b..b4028930af66 100644
--- a/apps/desktop/src/electron/ElectronTheme.test.ts
+++ b/apps/desktop/src/electron/ElectronTheme.test.ts
@@ -64,7 +64,6 @@ describe("ElectronTheme", () => {
       const error = yield* Effect.flip(electronTheme.setSource("dark"));
 
       assert.instanceOf(error, ElectronTheme.ElectronThemeSetSourceError);
-      assert.isTrue(ElectronTheme.isElectronThemeSetSourceError(error));
       assert.strictEqual(error.source, "dark");
       assert.strictEqual(error.cause, cause);
       assert.include(error.message, "dark");
diff --git a/apps/desktop/src/electron/ElectronTheme.ts b/apps/desktop/src/electron/ElectronTheme.ts
index ef47e3d0954f..24b2d856b9d2 100644
--- a/apps/desktop/src/electron/ElectronTheme.ts
+++ b/apps/desktop/src/electron/ElectronTheme.ts
@@ -19,8 +19,6 @@ export class ElectronThemeSetSourceError extends Schema.TaggedErrorClass<Electro
   }
 }
 
-export const isElectronThemeSetSourceError = Schema.is(ElectronThemeSetSourceError);
-
 export class ElectronTheme extends Context.Service<
   ElectronTheme,
   {
diff --git a/apps/desktop/src/electron/ElectronUpdater.test.ts b/apps/desktop/src/electron/ElectronUpdater.test.ts
index c2acc9ce120a..1e005d26fdf5 100644
--- a/apps/desktop/src/electron/ElectronUpdater.test.ts
+++ b/apps/desktop/src/electron/ElectronUpdater.test.ts
@@ -71,7 +71,6 @@ describe("ElectronUpdater", () => {
       const error = yield* updater.checkForUpdates.pipe(Effect.flip);
 
       assert.instanceOf(error, ElectronUpdater.ElectronUpdaterCheckForUpdatesError);
-      assert.isTrue(ElectronUpdater.isElectronUpdaterError(error));
       assert.equal(error.channel, "beta");
       assert.strictEqual(error.cause, cause);
       assert.equal(error.message, "Electron updater failed to check for updates on channel beta.");
@@ -89,7 +88,6 @@ describe("ElectronUpdater", () => {
       const error = yield* updater.downloadUpdate.pipe(Effect.flip);
 
       assert.instanceOf(error, ElectronUpdater.ElectronUpdaterDownloadUpdateError);
-      assert.isTrue(ElectronUpdater.isElectronUpdaterError(error));
       assert.equal(error.channel, "nightly");
       assert.strictEqual(error.cause, cause);
       assert.equal(
@@ -126,7 +124,6 @@ describe("ElectronUpdater", () => {
         .pipe(Effect.flip);
 
       assert.instanceOf(error, ElectronUpdater.ElectronUpdaterQuitAndInstallError);
-      assert.isTrue(ElectronUpdater.isElectronUpdaterError(error));
       assert.equal(error.channel, "alpha");
       assert.equal(error.isSilent, true);
       assert.equal(error.isForceRunAfter, false);
diff --git a/apps/desktop/src/electron/ElectronUpdater.ts b/apps/desktop/src/electron/ElectronUpdater.ts
index 4157d29a9df8..8e044de65ad6 100644
--- a/apps/desktop/src/electron/ElectronUpdater.ts
+++ b/apps/desktop/src/electron/ElectronUpdater.ts
@@ -54,7 +54,6 @@ export const ElectronUpdaterError = Schema.Union([
   ElectronUpdaterQuitAndInstallError,
 ]);
 export type ElectronUpdaterError = typeof ElectronUpdaterError.Type;
-export const isElectronUpdaterError = Schema.is(ElectronUpdaterError);
 
 export class ElectronUpdater extends Context.Service<
   ElectronUpdater,
diff --git a/apps/desktop/src/electron/ElectronWindow.test.ts b/apps/desktop/src/electron/ElectronWindow.test.ts
index bebb0e5c4178..c802e595633a 100644
--- a/apps/desktop/src/electron/ElectronWindow.test.ts
+++ b/apps/desktop/src/electron/ElectronWindow.test.ts
@@ -79,7 +79,6 @@ describe("ElectronWindow", () => {
       const error = yield* electronWindow.create(options).pipe(Effect.flip);
 
       assert.instanceOf(error, ElectronWindow.ElectronWindowCreateError);
-      assert.isTrue(ElectronWindow.isElectronWindowCreateError(error));
       assert.deepEqual(error.options, {
         title: "T3 Code",
         width: 1100,
diff --git a/apps/desktop/src/electron/ElectronWindow.ts b/apps/desktop/src/electron/ElectronWindow.ts
index 5f6a9d34280b..9234399191cf 100644
--- a/apps/desktop/src/electron/ElectronWindow.ts
+++ b/apps/desktop/src/electron/ElectronWindow.ts
@@ -58,8 +58,6 @@ export class ElectronWindowCreateError extends Schema.TaggedErrorClass<ElectronW
   }
 }
 
-export const isElectronWindowCreateError = Schema.is(ElectronWindowCreateError);
-
 export class ElectronWindowOperationError extends Schema.TaggedErrorClass<ElectronWindowOperationError>()(
   "ElectronWindowOperationError",
   {
diff --git a/apps/desktop/src/ipc/DesktopIpc.test.ts b/apps/desktop/src/ipc/DesktopIpc.test.ts
index fc311877f829..5533831f9b55 100644
--- a/apps/desktop/src/ipc/DesktopIpc.test.ts
+++ b/apps/desktop/src/ipc/DesktopIpc.test.ts
@@ -41,7 +41,6 @@ describe("DesktopIpc", () => {
       const error = yield* Effect.flip(Effect.scoped(ipc.handle(invokeMethod)));
 
       assert.instanceOf(error, DesktopIpc.DesktopIpcRegistrationError);
-      assert.isTrue(DesktopIpc.isDesktopIpcError(error));
       assert.strictEqual(error.handlerKind, "invoke");
       assert.strictEqual(error.channel, invokeMethod.channel);
       assert.strictEqual(error.cause, cause);
@@ -69,7 +68,6 @@ describe("DesktopIpc", () => {
       if (exit._tag === "Success") return;
       const error = Cause.squash(exit.cause);
       assert.instanceOf(error, DesktopIpc.DesktopIpcUnregistrationError);
-      assert.isTrue(DesktopIpc.isDesktopIpcError(error));
       assert.strictEqual(error.handlerKind, "sync");
       assert.strictEqual(error.channel, syncMethod.channel);
       assert.strictEqual(error.cause, cause);
diff --git a/apps/desktop/src/ipc/DesktopIpc.ts b/apps/desktop/src/ipc/DesktopIpc.ts
index e948571cc628..643543d4ec33 100644
--- a/apps/desktop/src/ipc/DesktopIpc.ts
+++ b/apps/desktop/src/ipc/DesktopIpc.ts
@@ -55,7 +55,6 @@ export const DesktopIpcError = Schema.Union([
   DesktopIpcUnregistrationError,
 ]);
 export type DesktopIpcError = typeof DesktopIpcError.Type;
-export const isDesktopIpcError = Schema.is(DesktopIpcError);
 
 export interface DesktopIpcMethod<E, R> {
   readonly channel: string;
diff --git a/apps/desktop/src/ipc/DesktopIpcHandlers.ts b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
index 2cdffbefb7ad..3e30083064af 100644
--- a/apps/desktop/src/ipc/DesktopIpcHandlers.ts
+++ b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
@@ -38,6 +38,7 @@ import {
   getSystemLocale,
   getWindowFullscreenState,
   openExternal,
+  openSystemSettings,
   probeRemoteEditors,
   pickFolder,
   pickProjectFavicon,
@@ -94,6 +95,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
   yield* ipc.handle(setTheme);
   yield* ipc.handle(showContextMenu);
   yield* ipc.handle(openExternal);
+  yield* ipc.handle(openSystemSettings);
   yield* ipc.handle(probeRemoteEditors);
   yield* ipc.handle(getUpdateState);
   yield* ipc.handle(setUpdateChannel);
diff --git a/apps/desktop/src/ipc/channels.ts b/apps/desktop/src/ipc/channels.ts
index 81b50d165d24..5b2c815eaa42 100644
--- a/apps/desktop/src/ipc/channels.ts
+++ b/apps/desktop/src/ipc/channels.ts
@@ -4,6 +4,7 @@ export const PICK_THEME_FILES_CHANNEL = "desktop:pick-theme-files";
 export const SET_THEME_CHANNEL = "desktop:set-theme";
 export const CONTEXT_MENU_CHANNEL = "desktop:context-menu";
 export const OPEN_EXTERNAL_CHANNEL = "desktop:open-external";
+export const OPEN_SYSTEM_SETTINGS_CHANNEL = "desktop:open-system-settings";
 export const PROBE_REMOTE_EDITORS_CHANNEL = "desktop:probe-remote-editors";
 export const MENU_ACTION_CHANNEL = "desktop:menu-action";
 export const QUIT_SHORTCUT_CHANNEL = "desktop:quit-shortcut";
diff --git a/apps/desktop/src/ipc/methods/window.ts b/apps/desktop/src/ipc/methods/window.ts
index edae8394302c..61de1361a311 100644
--- a/apps/desktop/src/ipc/methods/window.ts
+++ b/apps/desktop/src/ipc/methods/window.ts
@@ -9,6 +9,7 @@ import {
   PickFolderOptionsSchema,
   PRIMARY_LOCAL_ENVIRONMENT_ID,
   REMOTE_CAPABLE_EDITOR_IDS,
+  SystemSettingsPaneSchema,
   type DesktopEnvironmentBootstrap,
   type PickedThemeFile,
 } from "@t3tools/contracts";
@@ -298,6 +299,16 @@ export const openExternal = DesktopIpc.makeIpcMethod({
   }),
 });
 
+export const openSystemSettings = DesktopIpc.makeIpcMethod({
+  channel: IpcChannels.OPEN_SYSTEM_SETTINGS_CHANNEL,
+  payload: SystemSettingsPaneSchema,
+  result: Schema.Boolean,
+  handler: Effect.fn("desktop.ipc.window.openSystemSettings")(function* (pane) {
+    const shell = yield* ElectronShell.ElectronShell;
+    return yield* shell.openSystemSettings(pane);
+  }),
+});
+
 export const probeRemoteEditors = DesktopIpc.makeIpcMethod({
   channel: IpcChannels.PROBE_REMOTE_EDITORS_CHANNEL,
   payload: Schema.Undefined,
diff --git a/apps/desktop/src/linuxSecretStorage.test.ts b/apps/desktop/src/linuxSecretStorage.test.ts
index a91790200771..5827e38e406f 100644
--- a/apps/desktop/src/linuxSecretStorage.test.ts
+++ b/apps/desktop/src/linuxSecretStorage.test.ts
@@ -3,7 +3,6 @@ import { describe, expect, it } from "vite-plus/test";
 import {
   normalizeLinuxPasswordStorePreference,
   resolveLinuxPasswordStoreSwitch,
-  resolveLinuxSecretStorageUnavailableMessage,
 } from "./linuxSecretStorage.ts";
 
 const autoSwitch = (env: NodeJS.ProcessEnv) =>
@@ -124,80 +123,4 @@ describe("linuxSecretStorage", () => {
       }),
     ).toBe("gnome-libsecret");
   });
-
-  it("uses GNOME Keyring remediation for libsecret and unknown backends", () => {
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "auto",
-        selectedBackend: "gnome_libsecret",
-        env: { XDG_CURRENT_DESKTOP: "niri" },
-      }),
-    ).toContain("GNOME Keyring");
-  });
-
-  it("prefers explicit libsecret selection over KDE desktop heuristics", () => {
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "gnome-libsecret",
-        selectedBackend: "unknown",
-        env: { XDG_CURRENT_DESKTOP: "KDE" },
-      }),
-    ).toContain("GNOME Keyring");
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "auto",
-        selectedBackend: "gnome_libsecret",
-        env: { XDG_CURRENT_DESKTOP: "KDE" },
-      }),
-    ).toContain("GNOME Keyring");
-  });
-
-  it("prefers explicit KWallet preference over selected gnome-libsecret backend", () => {
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "kwallet6",
-        selectedBackend: "gnome_libsecret",
-        env: { XDG_CURRENT_DESKTOP: "niri" },
-      }),
-    ).toContain("KWallet");
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "kwallet",
-        selectedBackend: "gnome-libsecret",
-        env: {},
-      }),
-    ).toContain("KWallet");
-  });
-
-  it("uses KWallet remediation wording for KDE-looking sessions", () => {
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "auto",
-        selectedBackend: "kwallet6",
-        env: {},
-      }),
-    ).toContain("KWallet");
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "auto",
-        selectedBackend: "unknown",
-        env: { XDG_CURRENT_DESKTOP: "KDE" },
-      }),
-    ).toContain("KWallet");
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "auto",
-        selectedBackend: "unknown",
-        env: { DESKTOP_SESSION: "plasmawayland" },
-      }),
-    ).toContain("KWallet");
-    // A desktop name outranks a bare KDE marker when choosing the wording.
-    expect(
-      resolveLinuxSecretStorageUnavailableMessage({
-        configuredPreference: "auto",
-        selectedBackend: "unknown",
-        env: { GDMSESSION: "gnome", KDE_FULL_SESSION: "true" },
-      }),
-    ).toContain("GNOME Keyring");
-  });
 });
diff --git a/apps/desktop/src/linuxSecretStorage.ts b/apps/desktop/src/linuxSecretStorage.ts
index fe3e21eadb92..3aa7a440d1e8 100644
--- a/apps/desktop/src/linuxSecretStorage.ts
+++ b/apps/desktop/src/linuxSecretStorage.ts
@@ -25,9 +25,6 @@ const ELECTRON_KDE_DESKTOP = "KDE";
 // Chromium recognizes LXQt and still selects basic text for it, so it does need a forced backend.
 const ELECTRON_UNPROTECTED_DESKTOPS = new Set(["LXQt"]);
 
-const KDE_NAME_PREFIXES = ["kde", "plasma"];
-const NEGATIVE_FLAG_VALUES = new Set(["0", "false", "no", "off"]);
-
 export function normalizeLinuxPasswordStorePreference(
   value: unknown,
 ): LinuxPasswordStorePreference {
@@ -77,102 +74,6 @@ function electronSelectsProtectedBackend(env: NodeJS.ProcessEnv): boolean {
   return false;
 }
 
-export function resolveLinuxSecretStorageUnavailableMessage(input: {
-  readonly configuredPreference: LinuxPasswordStorePreference;
-  readonly selectedBackend: string | null;
-  readonly env: NodeJS.ProcessEnv;
-}): string {
-  if (input.configuredPreference === "gnome-libsecret") {
-    return getGnomeKeyringRemediationMessage();
-  }
-
-  if (
-    input.configuredPreference === "kwallet" ||
-    input.configuredPreference === "kwallet5" ||
-    input.configuredPreference === "kwallet6"
-  ) {
-    return getKWalletRemediationMessage();
-  }
-
-  const backend = normalizeSelectedStorageBackend(input.selectedBackend);
-  if (backend === "gnome-libsecret") {
-    return getGnomeKeyringRemediationMessage();
-  }
-
-  if (
-    backend === "kwallet" ||
-    backend === "kwallet5" ||
-    backend === "kwallet6" ||
-    looksLikeKdeSession(input.env)
-  ) {
-    return getKWalletRemediationMessage();
-  }
-
-  return getGnomeKeyringRemediationMessage();
-}
-
-function getGnomeKeyringRemediationMessage(): string {
-  return "T3 Code could not access GNOME Keyring to save this environment credential. Install and start GNOME Keyring, then restart T3 Code.";
-}
-
-function getKWalletRemediationMessage(): string {
-  return "T3 Code could not access KWallet to save this environment credential. Enable the KDE wallet subsystem in System Settings, then restart T3 Code.";
-}
-
-// Advisory only: this picks between the GNOME Keyring and KWallet wording in the failure notice. It
-// never decides which backend to select, so a loose match costs a user slightly wrong instructions
-// rather than an unprotected credential store.
-function looksLikeKdeSession(env: NodeJS.ProcessEnv): boolean {
-  const currentDesktopNames = nonEmptyDesktopNames(env.XDG_CURRENT_DESKTOP);
-  if (currentDesktopNames.length > 0) {
-    return currentDesktopNames.some(isKdeDesktopName);
-  }
-
-  const legacyNames = legacyDesktopNames(env);
-  if (legacyNames.length > 0) {
-    return legacyNames.some(isKdeDesktopName);
-  }
-
-  return isSet(env.KDE_SESSION_VERSION) || isAffirmativeFlag(env.KDE_FULL_SESSION);
-}
-
-function isKdeDesktopName(name: string): boolean {
-  return KDE_NAME_PREFIXES.some((prefix) => name.startsWith(prefix));
-}
-
-function legacyDesktopNames(env: NodeJS.ProcessEnv): string[] {
-  return [env.XDG_SESSION_DESKTOP, env.DESKTOP_SESSION, env.GDMSESSION].flatMap((entry) => {
-    const normalized = normalizeDesktopName(entry);
-    return normalized ? [normalized] : [];
-  });
-}
-
-function nonEmptyDesktopNames(value: string | undefined): string[] {
-  return splitDesktopNameList(value).flatMap((entry) => {
-    const normalized = normalizeDesktopName(entry);
-    return normalized ? [normalized] : [];
-  });
-}
-
-function isSet(value: string | undefined): boolean {
-  return Boolean(value?.trim());
-}
-
-function isAffirmativeFlag(value: string | undefined): boolean {
-  const normalized = value?.trim().toLowerCase();
-  return normalized ? !NEGATIVE_FLAG_VALUES.has(normalized) : false;
-}
-
 function splitDesktopNameList(value: string | undefined): string[] {
   return value?.split(":") ?? [];
 }
-
-function normalizeDesktopName(value: string | undefined): string | null {
-  const normalized = value?.trim().toLowerCase();
-  return normalized && normalized.length > 0 ? normalized : null;
-}
-
-function normalizeSelectedStorageBackend(value: string | null): string | null {
-  const normalized = value?.trim().toLowerCase().replace(/_/gu, "-");
-  return normalized && normalized.length > 0 ? normalized : null;
-}
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index 685a9b1204db..74001dd785d3 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -116,6 +116,8 @@ contextBridge.exposeInMainWorld("desktopBridge", {
       ...(position === undefined ? {} : { position }),
     }),
   openExternal: (url: string) => ipcRenderer.invoke(IpcChannels.OPEN_EXTERNAL_CHANNEL, url),
+  openSystemSettings: (pane: string) =>
+    ipcRenderer.invoke(IpcChannels.OPEN_SYSTEM_SETTINGS_CHANNEL, pane),
   probeRemoteEditors: () => ipcRenderer.invoke(IpcChannels.PROBE_REMOTE_EDITORS_CHANNEL, undefined),
   onMenuAction: (listener) => {
     const wrappedListener = (_event: Electron.IpcRendererEvent, action: unknown) => {
diff --git a/apps/desktop/src/preview/BrowserImport/BrowserImport.test.ts b/apps/desktop/src/preview/BrowserImport/BrowserImport.test.ts
index 9b0a652f09f1..003461085376 100644
--- a/apps/desktop/src/preview/BrowserImport/BrowserImport.test.ts
+++ b/apps/desktop/src/preview/BrowserImport/BrowserImport.test.ts
@@ -14,6 +14,7 @@ import * as Ref from "effect/Ref";
 import * as BrowserSession from "../BrowserSession.ts";
 import * as BrowserImport from "./BrowserImport.ts";
 import { BROWSER_IMPORT_SOURCES, sourcePathContext } from "./Sources.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const helium = BROWSER_IMPORT_SOURCES.find((source) => source.id === "helium")!;
 
@@ -105,28 +106,30 @@ describe("BrowserImport.importCookies", () => {
     }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
   );
 
-  it.effect("refuses to import while the source browser holds its profile", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const { importer, root } = yield* withImporter();
-      // The lock Chromium leaves while it is running, dangling target and
-      // all. This must stop the import before it ever asks the keychain.
-      yield* fileSystem.symlink("host-that-does-not-exist-1234", `${root}/SingletonLock`);
-
-      const error = yield* importer
-        .importCookies({
-          input: {
-            sourceId: "helium",
-            sourceProfileDirectory: "Default",
-            targetProfileId: "default",
-          },
-          scope: "persist:t3code-preview-test",
-          persistent: true,
-        })
-        .pipe(Effect.flip);
+  it.effect.skipIf(!symlinksSupported)(
+    "refuses to import while the source browser holds its profile",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const { importer, root } = yield* withImporter();
+        // The lock Chromium leaves while it is running, dangling target and
+        // all. This must stop the import before it ever asks the keychain.
+        yield* fileSystem.symlink("host-that-does-not-exist-1234", `${root}/SingletonLock`);
+
+        const error = yield* importer
+          .importCookies({
+            input: {
+              sourceId: "helium",
+              sourceProfileDirectory: "Default",
+              targetProfileId: "default",
+            },
+            scope: "persist:t3code-preview-test",
+            persistent: true,
+          })
+          .pipe(Effect.flip);
 
-      assert.equal(error.reason, "browserRunning");
-    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+        assert.equal(error.reason, "browserRunning");
+      }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
   );
 });
 
diff --git a/apps/desktop/src/preview/BrowserImport/BrowserImport.ts b/apps/desktop/src/preview/BrowserImport/BrowserImport.ts
index e92f2f05e05c..386b3ef6f813 100644
--- a/apps/desktop/src/preview/BrowserImport/BrowserImport.ts
+++ b/apps/desktop/src/preview/BrowserImport/BrowserImport.ts
@@ -27,6 +27,7 @@ import * as BrowserSession from "../BrowserSession.ts";
 import { ChromiumCookieReadError, readChromiumCookies } from "./ChromiumCookies.ts";
 import type { CookieReadResult } from "./CookieDatabase.ts";
 import { FirefoxCookieReadError, readFirefoxCookies } from "./FirefoxCookies.ts";
+import { readSafariCookies, safariAccessDenied, SafariCookieReadError } from "./SafariCookies.ts";
 import {
   BROWSER_IMPORT_SOURCES,
   resolveCookieDatabase,
@@ -92,6 +93,15 @@ const unavailableReason = Effect.fn("BrowserImport.unavailableReason")(function*
   if (!definition.platforms.includes(context.platform)) return "unsupportedPlatform";
   if (!(yield* isSourceInstalled(definition, context))) return "notInstalled";
   if (yield* isSourceRunning(definition, context)) return "browserRunning";
+  // Safari's jar is found by `stat`, which TCC permits without Full Disk
+  // Access — so a Safari that lists as ready may still refuse the read. Probe
+  // the grant here, so the wizard can open on the permission step and a
+  // post-grant recheck can tell granted from still-denied, rather than only
+  // discovering it by attempting the import.
+  if (definition.engine === "safari") {
+    const jar = yield* resolveCookieDatabase(definition, context, ".");
+    if (jar !== undefined && (yield* safariAccessDenied(jar))) return "needsFullDiskAccess";
+  }
   return undefined;
 });
 
@@ -254,25 +264,29 @@ export const make = Effect.gen(function* BrowserImportMake() {
     const userDataDirectory = definition.userDataDirectory(pathContext);
     const read: Effect.Effect<
       CookieReadResult,
-      ChromiumCookieReadError | FirefoxCookieReadError,
+      ChromiumCookieReadError | FirefoxCookieReadError | SafariCookieReadError,
       FileSystem.FileSystem | Path.Path | Scope.Scope | ChildProcessSpawner.ChildProcessSpawner
     > =
-      definition.engine === "firefox"
-        ? readFirefoxCookies(databasePath).pipe(
+      definition.engine === "safari"
+        ? readSafariCookies(databasePath).pipe(
             Effect.map((cookies) => ({ cookies, undecryptable: 0, undecryptableHosts: [] })),
           )
-        : readChromiumCookies({
-            cookieDatabasePath: databasePath,
-            keychainService: definition.keychainService,
-            keychainAccount: definition.keychainAccount,
-            linuxSecretApplication: definition.linuxSecretApplication,
-            ...(platform === "win32" && userDataDirectory !== undefined
-              ? {
-                  windowsLocalStatePath: pathContext.path.join(userDataDirectory, "Local State"),
-                }
-              : {}),
-            platform,
-          });
+        : definition.engine === "firefox"
+          ? readFirefoxCookies(databasePath).pipe(
+              Effect.map((cookies) => ({ cookies, undecryptable: 0, undecryptableHosts: [] })),
+            )
+          : readChromiumCookies({
+              cookieDatabasePath: databasePath,
+              keychainService: definition.keychainService,
+              keychainAccount: definition.keychainAccount,
+              linuxSecretApplication: definition.linuxSecretApplication,
+              ...(platform === "win32" && userDataDirectory !== undefined
+                ? {
+                    windowsLocalStatePath: pathContext.path.join(userDataDirectory, "Local State"),
+                  }
+                : {}),
+              platform,
+            });
 
     const result = yield* read.pipe(
       Effect.scoped,
@@ -289,6 +303,12 @@ export const make = Effect.gen(function* BrowserImportMake() {
           Effect.fail(
             new BrowserImportFailedError({ sourceId: definition.id, reason: "readFailed", cause }),
           ),
+        // Safari's reasons are already user-facing: a TCC refusal is the Full
+        // Disk Access prompt, anything else is a read failure.
+        SafariCookieReadError: (cause) =>
+          Effect.fail(
+            new BrowserImportFailedError({ sourceId: definition.id, reason: cause.reason, cause }),
+          ),
       }),
     );
 
diff --git a/apps/desktop/src/preview/BrowserImport/SafariCookies.test.ts b/apps/desktop/src/preview/BrowserImport/SafariCookies.test.ts
new file mode 100644
index 000000000000..f5d07f765943
--- /dev/null
+++ b/apps/desktop/src/preview/BrowserImport/SafariCookies.test.ts
@@ -0,0 +1,443 @@
+// @effect-diagnostics nodeBuiltinImport:off - Hand-builds Safari's binary jar
+// format byte by byte.
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as PlatformError from "effect/PlatformError";
+
+import {
+  isPermissionDenied,
+  parseBinaryCookies,
+  readSafariCookies,
+  safariAccessDenied,
+  SafariCookieReadError,
+} from "./SafariCookies.ts";
+
+const APPLE_EPOCH_OFFSET_SECONDS = 978_307_200;
+
+interface FixtureCookie {
+  readonly domain: string;
+  readonly name: string;
+  readonly path: string;
+  readonly value: string;
+  readonly flags: number;
+  /** Seconds since 2001-01-01, as Safari stores them. */
+  readonly expiry: number;
+}
+
+/** Encodes one cookie exactly as Safari lays it out. */
+function encodeCookie(cookie: FixtureCookie): Buffer {
+  const strings = [cookie.domain, cookie.name, cookie.path, cookie.value];
+  const headerSize = 56;
+  const offsets: number[] = [];
+  let cursor = headerSize;
+  for (const value of strings) {
+    offsets.push(cursor);
+    cursor += Buffer.byteLength(value) + 1;
+  }
+  const size = cursor;
+
+  const buffer = Buffer.alloc(size);
+  buffer.writeUInt32LE(size, 0);
+  buffer.writeUInt32LE(0, 4);
+  buffer.writeUInt32LE(cookie.flags, 8);
+  buffer.writeUInt32LE(0, 12);
+  buffer.writeUInt32LE(offsets[0]!, 16);
+  buffer.writeUInt32LE(offsets[1]!, 20);
+  buffer.writeUInt32LE(offsets[2]!, 24);
+  buffer.writeUInt32LE(offsets[3]!, 28);
+  buffer.writeUInt32LE(0, 32);
+  buffer.writeUInt32LE(0, 36);
+  buffer.writeDoubleLE(cookie.expiry, 40);
+  buffer.writeDoubleLE(0, 48);
+  strings.forEach((value, index) => {
+    buffer.write(value, offsets[index]!, "utf8");
+  });
+  return buffer;
+}
+
+/** Builds a single-page `Cookies.binarycookies` file. */
+function encodeBinaryCookies(cookies: ReadonlyArray<FixtureCookie>): Buffer {
+  const encoded = cookies.map(encodeCookie);
+  const headerSize = 12 + encoded.length * 4;
+  const offsets: number[] = [];
+  let cursor = headerSize;
+  for (const cookie of encoded) {
+    offsets.push(cursor);
+    cursor += cookie.length;
+  }
+
+  const page = Buffer.alloc(cursor);
+  page.writeUInt32BE(0x0000_0100, 0);
+  page.writeUInt32LE(encoded.length, 4);
+  offsets.forEach((offset, index) => page.writeUInt32LE(offset, 8 + index * 4));
+  encoded.forEach((cookie, index) => cookie.copy(page, offsets[index]!));
+
+  const header = Buffer.alloc(8 + 4);
+  header.write("cook", 0, "latin1");
+  header.writeUInt32BE(1, 4);
+  header.writeUInt32BE(page.length, 8);
+  return Buffer.concat([header, page]);
+}
+
+describe("parseBinaryCookies", () => {
+  it("reads Safari's format and rebases its 2001 epoch", () => {
+    const file = encodeBinaryCookies([
+      {
+        domain: ".apple.com",
+        name: "session",
+        path: "/",
+        value: "abc",
+        // secure | httpOnly
+        flags: 0x1 | 0x4,
+        expiry: 800_000_000,
+      },
+      {
+        domain: "example.test",
+        name: "plain",
+        path: "/app",
+        value: "v",
+        flags: 0,
+        expiry: 0,
+      },
+    ]);
+
+    expect(parseBinaryCookies(file)).toEqual([
+      {
+        url: "https://apple.com/",
+        name: "session",
+        value: "abc",
+        domain: ".apple.com",
+        path: "/",
+        secure: true,
+        httpOnly: true,
+        // Safari counts from 2001-01-01, Electron from 1970.
+        expirationDate: 800_000_000 + APPLE_EPOCH_OFFSET_SECONDS,
+        // The format predates SameSite; Lax is the safe modern default.
+        sameSite: "lax",
+      },
+      {
+        url: "http://example.test/app",
+        name: "plain",
+        value: "v",
+        // Host-only: no leading dot in the jar, so no `domain` for Electron,
+        // which would otherwise re-add the dot and widen it to subdomains.
+        domain: undefined,
+        path: "/app",
+        secure: false,
+        httpOnly: false,
+        expirationDate: undefined,
+        sameSite: "lax",
+      },
+    ]);
+  });
+
+  it("keeps __Host- cookies host-only so Electron accepts them", () => {
+    const file = encodeBinaryCookies([
+      { domain: "example.test", name: "__Host-id", path: "/", value: "v", flags: 0x1, expiry: 0 },
+    ]);
+
+    expect(parseBinaryCookies(file)[0]).toMatchObject({
+      url: "https://example.test/",
+      name: "__Host-id",
+      domain: undefined,
+    });
+  });
+
+  it("brackets IPv6 hosts in the cookie URL", () => {
+    const file = encodeBinaryCookies([
+      { domain: "::1", name: "local", path: "/", value: "v", flags: 0, expiry: 0 },
+    ]);
+
+    expect(parseBinaryCookies(file)[0]).toMatchObject({
+      url: "http://[::1]/",
+      domain: undefined,
+    });
+  });
+
+  it("reads cookies spread across multiple pages", () => {
+    // Safari pages its cookie file, and a single-page reader would silently
+    // return only the first slice.
+    const first = encodeBinaryCookies([
+      { domain: "a.test", name: "one", path: "/", value: "1", flags: 0, expiry: 1 },
+    ]);
+    const second = encodeBinaryCookies([
+      { domain: "b.test", name: "two", path: "/", value: "2", flags: 0, expiry: 1 },
+    ]);
+    // Splice the two single-page files into one two-page file.
+    const firstPage = first.subarray(12);
+    const secondPage = second.subarray(12);
+    const header = Buffer.alloc(16);
+    header.write("cook", 0, "latin1");
+    header.writeUInt32BE(2, 4);
+    header.writeUInt32BE(firstPage.length, 8);
+    header.writeUInt32BE(secondPage.length, 12);
+
+    const parsed = parseBinaryCookies(Buffer.concat([header, firstPage, secondPage]));
+
+    expect(parsed.map((cookie) => cookie.name)).toEqual(["one", "two"]);
+  });
+
+  it("rejects a page that runs past the end of the file", () => {
+    // `Buffer.subarray` clamps rather than throwing, so an overlong first page
+    // swallows the second one's bytes and advances the cursor past the end.
+    // Every cookie after the boundary then vanishes from a "successful" import.
+    const first = encodeBinaryCookies([
+      { domain: "a.test", name: "one", path: "/", value: "1", flags: 0, expiry: 1 },
+    ]);
+    const second = encodeBinaryCookies([
+      { domain: "b.test", name: "two", path: "/", value: "2", flags: 0, expiry: 1 },
+    ]);
+    const firstPage = first.subarray(12);
+    const secondPage = second.subarray(12);
+    const header = Buffer.alloc(16);
+    header.write("cook", 0, "latin1");
+    header.writeUInt32BE(2, 4);
+    // Declares more bytes for page one than the file holds in total.
+    header.writeUInt32BE(firstPage.length + secondPage.length + 32, 8);
+    header.writeUInt32BE(secondPage.length, 12);
+
+    expect(() => parseBinaryCookies(Buffer.concat([header, firstPage, secondPage]))).toThrow(
+      SafariCookieReadError,
+    );
+  });
+
+  it("rejects a record whose declared size runs past its page", () => {
+    const valid = encodeBinaryCookies([
+      { domain: "a.test", name: "n", path: "/", value: "v", expiry: 1_000, flags: 0 },
+    ]);
+    // The record's own length is what bounds its string offsets; an inflated
+    // one lets them read the following record's bytes as this cookie's value.
+    const pageStart = 8 + 4;
+    const recordStart = pageStart + valid.readUInt32LE(pageStart + 8);
+    const corrupt = Buffer.from(valid);
+    corrupt.writeUInt32LE(0xffff, recordStart);
+
+    expect(() => parseBinaryCookies(corrupt)).toThrow(SafariCookieReadError);
+  });
+
+  it("rejects records truncated inside the 56-byte header", () => {
+    const valid = encodeBinaryCookies([
+      { domain: "a.test", name: "n", path: "/", value: "v", expiry: 1_000, flags: 0 },
+    ]);
+    const pageStart = 8 + 4;
+    const recordStart = pageStart + valid.readUInt32LE(pageStart + 8);
+
+    for (let size = 48; size < 56; size += 1) {
+      const corrupt = Buffer.from(valid);
+      corrupt.writeUInt32LE(size, recordStart);
+      expect(() => parseBinaryCookies(corrupt), `record size ${size}`).toThrow(
+        SafariCookieReadError,
+      );
+    }
+  });
+
+  it("rejects record offsets that point into the page header or an earlier record", () => {
+    const valid = encodeBinaryCookies([
+      { domain: "a.test", name: "n", path: "/", value: "v", expiry: 1_000, flags: 0 },
+      { domain: "b.test", name: "m", path: "/", value: "w", expiry: 1_000, flags: 0 },
+    ]);
+    const pageStart = 8 + 4;
+    const firstRecord = valid.readUInt32LE(pageStart + 8);
+
+    // Pointing the second offset at the page's offset table would let those
+    // table bytes parse as a fabricated record.
+    const intoTable = Buffer.from(valid);
+    intoTable.writeUInt32LE(4, pageStart + 12);
+    expect(() => parseBinaryCookies(intoTable)).toThrow(SafariCookieReadError);
+
+    // Pointing it back at the first record makes the same bytes count twice.
+    const overlapping = Buffer.from(valid);
+    overlapping.writeUInt32LE(firstRecord, pageStart + 12);
+    expect(() => parseBinaryCookies(overlapping)).toThrow(SafariCookieReadError);
+
+    // And a well-formed two-record page still parses.
+    expect(parseBinaryCookies(valid)).toHaveLength(2);
+  });
+
+  it("rejects string offsets that point into the record header", () => {
+    const valid = encodeBinaryCookies([
+      { domain: "a.test", name: "n", path: "/", value: "v", expiry: 1_000, flags: 0 },
+    ]);
+    const pageStart = 8 + 4;
+    const recordStart = pageStart + valid.readUInt32LE(pageStart + 8);
+
+    for (const offsetField of [16, 20, 24, 28]) {
+      const corrupt = Buffer.from(valid);
+      corrupt.writeUInt32LE(55, recordStart + offsetField);
+      expect(() => parseBinaryCookies(corrupt), `offset field ${offsetField}`).toThrow(
+        SafariCookieReadError,
+      );
+    }
+  });
+
+  it("accepts the checksum and property-list trailer Safari writes", () => {
+    const file = encodeBinaryCookies([
+      { domain: "a.test", name: "c", path: "/", value: "v", flags: 0, expiry: 0 },
+    ]);
+    const checksum = Buffer.alloc(8);
+    const plist = Buffer.from("bplist00 stub");
+    const plistLength = Buffer.alloc(4);
+    plistLength.writeUInt32BE(plist.length, 0);
+
+    expect(parseBinaryCookies(Buffer.concat([file, checksum]))).toHaveLength(1);
+    expect(parseBinaryCookies(Buffer.concat([file, checksum, plistLength, plist]))).toHaveLength(1);
+  });
+
+  it("rejects a jar whose page table stops short of its contents", () => {
+    // A second, undeclared page after the first would be silently dropped —
+    // the cookies it holds vanish from the import with no error — so a file
+    // the header does not fully describe is refused instead.
+    const first = encodeBinaryCookies([
+      { domain: "a.test", name: "c", path: "/", value: "v", flags: 0, expiry: 0 },
+    ]);
+    const extraPage = encodeBinaryCookies([
+      { domain: "b.test", name: "d", path: "/", value: "w", flags: 0, expiry: 0 },
+    ]).subarray(12);
+
+    expect(() => parseBinaryCookies(Buffer.concat([first, extraPage]))).toThrow(
+      SafariCookieReadError,
+    );
+    // A trailer that claims a property list it doesn't contain is refused too.
+    const badLength = Buffer.alloc(4);
+    badLength.writeUInt32BE(99, 0);
+    expect(() =>
+      parseBinaryCookies(Buffer.concat([first, Buffer.alloc(8), badLength, Buffer.from("x")])),
+    ).toThrow(SafariCookieReadError);
+  });
+
+  it("rejects a file that is not binarycookies", () => {
+    expect(() => parseBinaryCookies(Buffer.from("not a cookie jar"))).toThrow(
+      SafariCookieReadError,
+    );
+  });
+});
+
+describe("readSafariCookies", () => {
+  it.effect("adds the cookie path and parser cause to malformed jar failures", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const directory = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-safari-" });
+      const jar = `${directory}/Cookies.binarycookies`;
+      yield* fileSystem.writeFileString(jar, "not a cookie jar");
+
+      const error = yield* readSafariCookies(jar).pipe(Effect.flip);
+
+      assert.equal(error.reason, "readFailed");
+      assert.equal(error.cookieDatabasePath, jar);
+      assert.instanceOf(error.cause, SafariCookieReadError);
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+
+  it.effect("reports a TCC denial as a permission the user can grant", () =>
+    Effect.gen(function* () {
+      // What Full Disk Access actually looks like: the file is there, the read
+      // is refused with EPERM. Effect tags that `Unknown`, not
+      // `PermissionDenied`, so the reader has to look at the errno. Reporting
+      // it as a generic failure would send the user looking for a missing
+      // browser instead of a checkbox.
+      const denied = PlatformError.systemError({
+        _tag: "Unknown",
+        module: "FileSystem",
+        method: "readFile",
+        pathOrDescriptor: "/protected/Cookies.binarycookies",
+        cause: Object.assign(new Error("operation not permitted"), { code: "EPERM" }),
+      });
+
+      const error = yield* readSafariCookies("/protected/Cookies.binarycookies").pipe(
+        Effect.flip,
+        Effect.provide(FileSystem.layerNoop({ readFile: () => Effect.fail(denied) })),
+      );
+
+      assert.equal(error.reason, "needsFullDiskAccess");
+    }),
+  );
+
+  it.effect("reports an ordinary permission failure as a plain read failure", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const directory = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-safari-" });
+      const jar = `${directory}/Cookies.binarycookies`;
+      yield* fileSystem.writeFile(jar, new Uint8Array([0x63, 0x6f, 0x6f, 0x6b]));
+      // A mode-bits refusal is EACCES: granting Full Disk Access cannot fix
+      // it, so it must not be routed to that grant.
+      yield* fileSystem.chmod(jar, 0o000);
+
+      const error = yield* readSafariCookies(jar).pipe(Effect.flip);
+
+      assert.equal(error.reason, "readFailed");
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+
+  it.effect("reports a missing jar as a plain read failure", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const directory = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-safari-" });
+
+      const error = yield* readSafariCookies(`${directory}/absent.binarycookies`).pipe(Effect.flip);
+
+      assert.equal(error.reason, "readFailed");
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+});
+
+describe("safariAccessDenied", () => {
+  const eperm = PlatformError.systemError({
+    _tag: "Unknown",
+    module: "FileSystem",
+    method: "open",
+    pathOrDescriptor: "/protected/Cookies.binarycookies",
+    cause: Object.assign(new Error("operation not permitted"), { code: "EPERM" }),
+  });
+  const denied = (error: PlatformError.PlatformError) =>
+    FileSystem.layerNoop({ open: () => Effect.fail(error) });
+
+  it.effect("reports TCC's EPERM as a missing Full Disk Access grant", () =>
+    Effect.gen(function* () {
+      // `stat` finds the jar without the grant, so only an open tells the
+      // listing whether the import would actually be allowed.
+      assert.isTrue(
+        yield* safariAccessDenied("/protected/Cookies.binarycookies").pipe(
+          Effect.provide(denied(eperm)),
+        ),
+      );
+    }),
+  );
+
+  it.effect("does not read a readable jar, or any other failure, as denied", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const directory = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-safari-" });
+      const jar = `${directory}/Cookies.binarycookies`;
+      yield* fileSystem.writeFile(jar, new Uint8Array([0x63, 0x6f, 0x6f, 0x6b]));
+      assert.isFalse(yield* safariAccessDenied(jar));
+      // Missing entirely is "not installed", not "denied".
+      assert.isFalse(yield* safariAccessDenied(`${directory}/absent.binarycookies`));
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+});
+
+describe("isPermissionDenied", () => {
+  // Shapes taken from a real `FileSystem.readFile` failure on macOS — verified
+  // against Safari's TCC-protected jar, whose denial is EPERM, tagged
+  // `Unknown` rather than `PermissionDenied`.
+  const platformError = (reasonTag: string, code: string): PlatformError.PlatformError =>
+    ({ _tag: "PlatformError", reason: { _tag: reasonTag, cause: { code } } }) as never;
+
+  it("treats a TCC EPERM denial as permission denied", () => {
+    // The regression: EPERM is tagged `Unknown`, so checking the tag alone
+    // reported Safari's Full Disk Access refusal as a generic read failure.
+    expect(isPermissionDenied(platformError("Unknown", "EPERM"))).toBe(true);
+  });
+
+  it("does not send an ordinary EACCES failure to the Full Disk Access grant", () => {
+    // A POSIX permission or ACL refusal cannot be fixed by granting Full Disk
+    // Access, so it stays a plain read failure; only TCC's EPERM routes there.
+    expect(isPermissionDenied(platformError("PermissionDenied", "EACCES"))).toBe(false);
+  });
+
+  it("does not treat an unrelated failure as permission denied", () => {
+    expect(isPermissionDenied(platformError("Unknown", "EIO"))).toBe(false);
+  });
+});
diff --git a/apps/desktop/src/preview/BrowserImport/SafariCookies.ts b/apps/desktop/src/preview/BrowserImport/SafariCookies.ts
new file mode 100644
index 000000000000..88aa856b83e9
--- /dev/null
+++ b/apps/desktop/src/preview/BrowserImport/SafariCookies.ts
@@ -0,0 +1,263 @@
+/**
+ * Safari cookie extraction.
+ *
+ * Safari does not encrypt its cookies; it stores them in a proprietary
+ * `Cookies.binarycookies` file inside its app container. The protection is
+ * TCC, not cryptography — the file lives under a path only apps with Full Disk
+ * Access may read, so the gate is a permission the user grants in System
+ * Settings rather than a key to obtain.
+ *
+ * The format, big-endian throughout except the page bodies:
+ *
+ *   magic "cook", u32 pageCount, u32 pageSize[pageCount], then each page:
+ *     u32 0x00000100, u32le cookieCount, u32le cookieOffset[cookieCount],
+ *     then each cookie:
+ *       u32le size, u32le unknown, u32le flags, u32le unknown,
+ *       u32le urlOffset, nameOffset, pathOffset, valueOffset,
+ *       u64 end-of-header, f64 expiry, f64 creation, then NUL-terminated
+ *       strings at the offsets above (relative to the cookie start).
+ *
+ * @module SafariCookies
+ */
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as PlatformError from "effect/PlatformError";
+import * as Schema from "effect/Schema";
+
+import { cookieScope, type ImportedCookie } from "./CookieDatabase.ts";
+
+/** Safari's timestamps count seconds from 2001-01-01, not the UNIX epoch. */
+const APPLE_EPOCH_OFFSET_SECONDS = 978_307_200;
+
+/** `u32 0x00000100`, `u32le cookieCount`, then one `u32le` offset per cookie. */
+const COOKIE_PAGE_HEADER_SIZE = 12;
+/** Through the `f64 creation` field; string bytes follow. */
+const COOKIE_RECORD_HEADER_SIZE = 56;
+
+const FLAG_SECURE = 0x1;
+const FLAG_HTTP_ONLY = 0x4;
+
+export const SafariCookieReadFailure = Schema.Literals(["needsFullDiskAccess", "readFailed"]);
+export type SafariCookieReadFailure = typeof SafariCookieReadFailure.Type;
+
+export class SafariCookieReadError extends Schema.TaggedErrorClass<SafariCookieReadError>()(
+  "SafariCookieReadError",
+  {
+    reason: SafariCookieReadFailure,
+    /**
+     * Which jar the read was for. The parser raises this before a path is in
+     * hand, so it is optional rather than required.
+     */
+    cookieDatabasePath: Schema.optional(Schema.String),
+    /** Kept for the log; never surfaced to the user. */
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    return this.cookieDatabasePath === undefined
+      ? `Could not read Safari cookies: ${this.reason}.`
+      : `Could not read Safari cookies at ${this.cookieDatabasePath}: ${this.reason}.`;
+  }
+}
+
+const isSafariCookieReadError = Schema.is(SafariCookieReadError);
+
+/** Reads a NUL-terminated ASCII string at an offset. */
+function readCString(buffer: Buffer, start: number): string {
+  const end = buffer.indexOf(0, start);
+  return buffer.toString("utf8", start, end === -1 ? buffer.length : end);
+}
+
+export function parseBinaryCookies(buffer: Buffer): ReadonlyArray<ImportedCookie> {
+  if (buffer.length < 8 || buffer.toString("latin1", 0, 4) !== "cook") {
+    throw new SafariCookieReadError({ reason: "readFailed" });
+  }
+
+  const pageCount = buffer.readUInt32BE(4);
+  // Every declared structure is bounds-checked against what the file actually
+  // contains, and a mismatch fails the read. `Buffer.subarray` clamps silently,
+  // so accepting a short page or an overlong record would return a cookie set
+  // that is quietly missing entries or carrying fields read out of the next
+  // record — a partial import the user has no way to notice.
+  if (8 + pageCount * 4 > buffer.length) {
+    throw new SafariCookieReadError({ reason: "readFailed" });
+  }
+  const pageSizes: number[] = [];
+  for (let index = 0; index < pageCount; index += 1) {
+    pageSizes.push(buffer.readUInt32BE(8 + index * 4));
+  }
+
+  const cookies: ImportedCookie[] = [];
+  let pageStart = 8 + pageCount * 4;
+
+  for (const pageSize of pageSizes) {
+    if (pageSize < COOKIE_PAGE_HEADER_SIZE || pageStart + pageSize > buffer.length) {
+      throw new SafariCookieReadError({ reason: "readFailed" });
+    }
+    const page = buffer.subarray(pageStart, pageStart + pageSize);
+    pageStart += pageSize;
+
+    // Page bodies switch to little-endian after the big-endian header.
+    const cookieCount = page.readUInt32LE(4);
+    const offsetTableEnd = COOKIE_PAGE_HEADER_SIZE + cookieCount * 4;
+    if (offsetTableEnd > page.length) {
+      throw new SafariCookieReadError({ reason: "readFailed" });
+    }
+    // Every record accepted so far, so a later offset cannot point back into
+    // one of them: the page header, the offset table, and earlier records are
+    // all bytes that would otherwise parse as a fabricated cookie.
+    const accepted: Array<readonly [start: number, end: number]> = [];
+    for (let index = 0; index < cookieCount; index += 1) {
+      const cookieStart = page.readUInt32LE(8 + index * 4);
+      if (cookieStart < offsetTableEnd || cookieStart + COOKIE_RECORD_HEADER_SIZE > page.length) {
+        throw new SafariCookieReadError({ reason: "readFailed" });
+      }
+      // Bounded by the record's own length so a string offset cannot run past
+      // it into the following record's bytes.
+      const recordSize = page.readUInt32LE(cookieStart);
+      const cookieEnd = cookieStart + recordSize;
+      if (
+        recordSize < COOKIE_RECORD_HEADER_SIZE ||
+        cookieEnd > page.length ||
+        accepted.some(([start, end]) => cookieStart < end && cookieEnd > start)
+      ) {
+        throw new SafariCookieReadError({ reason: "readFailed" });
+      }
+      accepted.push([cookieStart, cookieEnd]);
+      const cookie = page.subarray(cookieStart, cookieEnd);
+
+      const flags = cookie.readUInt32LE(8);
+      const urlOffset = cookie.readUInt32LE(16);
+      const nameOffset = cookie.readUInt32LE(20);
+      const pathOffset = cookie.readUInt32LE(24);
+      const valueOffset = cookie.readUInt32LE(28);
+      const expiry = cookie.readDoubleLE(40);
+
+      // Offsets are relative to the record; one pointing outside it would
+      // otherwise read a neighbouring cookie's bytes as this one's value.
+      if (
+        [urlOffset, nameOffset, pathOffset, valueOffset].some(
+          (offset) => offset < COOKIE_RECORD_HEADER_SIZE || offset >= cookie.length,
+        )
+      ) {
+        throw new SafariCookieReadError({ reason: "readFailed" });
+      }
+      const domain = readCString(cookie, urlOffset);
+      const name = readCString(cookie, nameOffset);
+      const path = readCString(cookie, pathOffset);
+      const value = readCString(cookie, valueOffset);
+      if (domain === "" || name === "") continue;
+
+      const secure = (flags & FLAG_SECURE) !== 0;
+      const expirationDate =
+        expiry > 0 ? Math.floor(expiry) + APPLE_EPOCH_OFFSET_SECONDS : undefined;
+
+      cookies.push({
+        // Safari marks domain cookies with a leading dot like the other
+        // engines, so the shared scope rule applies: host-only cookies keep
+        // `domain` undefined, or Electron widens them to every subdomain.
+        ...cookieScope(domain, path || "/", secure),
+        name,
+        value,
+        path: path || "/",
+        secure,
+        httpOnly: (flags & FLAG_HTTP_ONLY) !== 0,
+        expirationDate,
+        // Bits 3–5 of the flags carry something SameSite-shaped, but no public
+        // description of them agrees and real jars do not match any of them
+        // cleanly. Lax is the modern browser default; claiming "none" would
+        // widen every imported cookie's scope.
+        sameSite: "lax",
+      });
+    }
+  }
+
+  // Safari writes an 8-byte checksum after the pages, then an optional
+  // length-prefixed property list. Anything else past the declared pages —
+  // in particular whole extra pages — means the page table does not describe
+  // the file, and a jar the header lies about is refused rather than
+  // imported with cookies silently missing.
+  const trailer = buffer.length - pageStart;
+  // Legal shapes: nothing, the 8-byte checksum alone, or checksum + u32
+  // length + exactly that many property-list bytes.
+  const validTrailer =
+    trailer === 0 ||
+    trailer === 8 ||
+    (trailer >= 12 && trailer === 8 + 4 + buffer.readUInt32BE(pageStart + 8));
+  if (!validTrailer) {
+    throw new SafariCookieReadError({ reason: "readFailed" });
+  }
+
+  return cookies;
+}
+
+/**
+ * Whether a filesystem error is the OS refusing access.
+ *
+ * A TCC denial arrives as EPERM, which Effect tags `Unknown` rather than
+ * `PermissionDenied` (reserved for EACCES), so the underlying errno is checked
+ * too — otherwise a Full Disk Access refusal is reported as a generic read
+ * failure and the user is never told what to grant.
+ */
+export const isPermissionDenied = (error: PlatformError.PlatformError): boolean => {
+  // TCC denies with EPERM, which Effect tags `Unknown` rather than
+  // `PermissionDenied` — so the errno is what identifies it. EACCES (and the
+  // `PermissionDenied` tag it maps to) is an ordinary POSIX permission or
+  // ACL failure that granting Full Disk Access cannot fix, so it stays a plain
+  // read failure rather than sending the user to a grant that won't help.
+  const code = (error.reason as { cause?: { code?: unknown } }).cause?.code;
+  return code === "EPERM";
+};
+
+/**
+ * Whether reading the jar is refused by TCC. `stat` succeeds on the jar
+ * inside Safari's container even without Full Disk Access — that is what lets
+ * the listing find it — so presence alone cannot tell granted from denied.
+ * Opening it for read is what TCC gates: EPERM means the grant is missing.
+ * Anything else (including a missing jar) is not a permission answer.
+ */
+export const safariAccessDenied = Effect.fnUntraced(function* (cookiePath: string) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  return yield* fileSystem.open(cookiePath, { flag: "r" }).pipe(
+    Effect.as(false),
+    Effect.catch((cause) => Effect.succeed(isPermissionDenied(cause))),
+    Effect.scoped,
+  );
+});
+
+export const readSafariCookies = Effect.fn("SafariCookies.readSafariCookies")(function* (
+  cookiePath: string,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const contents = yield* fileSystem.readFile(cookiePath).pipe(
+    Effect.mapError((cause) => {
+      // TCC denies the read even though the file exists — a permission the user
+      // grants in System Settings rather than a missing browser. macOS never
+      // prompts for Full Disk Access, so there is no dialog to wait on; the
+      // read just fails, and it fails with EPERM, which Effect surfaces as an
+      // `Unknown` system error rather than `PermissionDenied` (that is EACCES).
+      return new SafariCookieReadError({
+        reason: isPermissionDenied(cause) ? "needsFullDiskAccess" : "readFailed",
+        cookieDatabasePath: cookiePath,
+        cause,
+      });
+    }),
+  );
+  // The parser throws on a malformed jar; catch it here so callers see a typed
+  // failure rather than a defect.
+  return yield* Effect.try({
+    try: () => parseBinaryCookies(Buffer.from(contents)),
+    catch: (cause) =>
+      isSafariCookieReadError(cause)
+        ? new SafariCookieReadError({
+            reason: cause.reason,
+            cookieDatabasePath: cookiePath,
+            cause,
+          })
+        : new SafariCookieReadError({
+            reason: "readFailed",
+            cookieDatabasePath: cookiePath,
+            cause,
+          }),
+  });
+});
diff --git a/apps/desktop/src/preview/BrowserImport/Sources.test.ts b/apps/desktop/src/preview/BrowserImport/Sources.test.ts
index feaac842cbef..a867f78497b4 100644
--- a/apps/desktop/src/preview/BrowserImport/Sources.test.ts
+++ b/apps/desktop/src/preview/BrowserImport/Sources.test.ts
@@ -1,5 +1,6 @@
 // @effect-diagnostics nodeBuiltinImport:off - Builds a Chromium-shaped cookie
 // table with the same native bindings the source reads.
+import * as NodePath from "node:path";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import {
@@ -32,6 +33,7 @@ import {
   sourcePathContext,
   windowsChromiumCookiesAreHeld,
 } from "./Sources.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const helium = BROWSER_IMPORT_SOURCES.find((source) => source.id === "helium")!;
 
@@ -125,7 +127,7 @@ const writeFirefoxCookieDatabase = (
   });
 
 describe("Helium on Linux", () => {
-  it.effect("discovers its profiles and checks the user-data lock", () =>
+  it.effect.skipIf(!symlinksSupported)("discovers its profiles and checks the user-data lock", () =>
     run(
       Effect.gen(function* () {
         const fileSystem = yield* FileSystem.FileSystem;
@@ -221,48 +223,52 @@ describe("isSourceRunning", () => {
     ),
   );
 
-  it.effect("reads Chromium's dangling SingletonLock symlink as a running browser", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const context = yield* withSourceHome();
-        assert.isFalse(yield* isSourceRunning(helium, context));
-
-        // Chromium points the lock at `<host>-<pid>`, a target that never
-        // exists on disk. A check that follows the link reports a running
-        // browser as closed, letting an import read a live, mid-write database.
-        yield* fileSystem.symlink(
-          "host-that-does-not-exist-1234",
-          `${userDataDirectory(context)}/SingletonLock`,
-        );
+  it.effect.skipIf(!symlinksSupported)(
+    "reads Chromium's dangling SingletonLock symlink as a running browser",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const context = yield* withSourceHome();
+          assert.isFalse(yield* isSourceRunning(helium, context));
+
+          // Chromium points the lock at `<host>-<pid>`, a target that never
+          // exists on disk. A check that follows the link reports a running
+          // browser as closed, letting an import read a live, mid-write database.
+          yield* fileSystem.symlink(
+            "host-that-does-not-exist-1234",
+            `${userDataDirectory(context)}/SingletonLock`,
+          );
 
-        assert.isTrue(yield* isSourceRunning(helium, context));
-      }),
-    ),
+          assert.isTrue(yield* isSourceRunning(helium, context));
+        }),
+      ),
   );
 
-  it.effect("uses the provided hostname to classify Chromium locks", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const paths = yield* withSourceHome();
-        yield* fileSystem.symlink(
-          "lock-owner-99999999",
-          `${helium.userDataDirectory(paths)}/SingletonLock`,
-        );
+  it.effect.skipIf(!symlinksSupported)(
+    "uses the provided hostname to classify Chromium locks",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const paths = yield* withSourceHome();
+          yield* fileSystem.symlink(
+            "lock-owner-99999999",
+            `${helium.userDataDirectory(paths)}/SingletonLock`,
+          );
 
-        assert.isTrue(
-          yield* isSourceRunning(helium, paths).pipe(
-            Effect.provideService(HostProcessHostname, "another-host"),
-          ),
-        );
-        assert.isFalse(
-          yield* isSourceRunning(helium, paths).pipe(
-            Effect.provideService(HostProcessHostname, "lock-owner"),
-          ),
-        );
-      }),
-    ),
+          assert.isTrue(
+            yield* isSourceRunning(helium, paths).pipe(
+              Effect.provideService(HostProcessHostname, "another-host"),
+            ),
+          );
+          assert.isFalse(
+            yield* isSourceRunning(helium, paths).pipe(
+              Effect.provideService(HostProcessHostname, "lock-owner"),
+            ),
+          );
+        }),
+      ),
   );
 });
 
@@ -385,25 +391,27 @@ describe("isSourceInstalled", () => {
     ),
   );
 
-  it.effect("follows cookie database symlinks when detecting profiles", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const context = yield* withSourceHome();
-        const root = userDataDirectory(context);
-        yield* fileSystem.makeDirectory(`${root}/Default`, { recursive: true });
-        yield* fileSystem.symlink("missing-cookies", `${root}/Default/Cookies`);
+  it.effect.skipIf(!symlinksSupported)(
+    "follows cookie database symlinks when detecting profiles",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const context = yield* withSourceHome();
+          const root = userDataDirectory(context);
+          yield* fileSystem.makeDirectory(`${root}/Default`, { recursive: true });
+          yield* fileSystem.symlink("missing-cookies", `${root}/Default/Cookies`);
 
-        assert.deepEqual(yield* listSourceProfiles(helium, context), []);
-        assert.isFalse(yield* isSourceInstalled(helium, context));
+          assert.deepEqual(yield* listSourceProfiles(helium, context), []);
+          assert.isFalse(yield* isSourceInstalled(helium, context));
 
-        yield* fileSystem.writeFileString(`${root}/Default/missing-cookies`, "db");
-        assert.deepEqual(yield* listSourceProfiles(helium, context), [
-          { directory: "Default", name: "Default" },
-        ]);
-        assert.isTrue(yield* isSourceInstalled(helium, context));
-      }),
-    ),
+          yield* fileSystem.writeFileString(`${root}/Default/missing-cookies`, "db");
+          assert.deepEqual(yield* listSourceProfiles(helium, context), [
+            { directory: "Default", name: "Default" },
+          ]);
+          assert.isTrue(yield* isSourceInstalled(helium, context));
+        }),
+      ),
   );
 });
 
@@ -524,7 +532,7 @@ Path=Profiles/wxyz.empty
         yield* fileSystem.makeDirectory(`${root}/Profiles/wxyz.empty`, { recursive: true });
 
         assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory: "Profiles/abcd.default-release", name: "original" },
+          { directory: context.path.join("Profiles", "abcd.default-release"), name: "original" },
         ]);
       }),
     ),
@@ -605,10 +613,16 @@ describe("cookieDatabaseCandidatePaths", () => {
     run(
       Effect.gen(function* () {
         const context = yield* withSourceHome();
-        const profile = `${context.home}/Library/Application Support/net.imput.helium/Profile 1`;
+        const profile = context.path.join(
+          context.home,
+          "Library",
+          "Application Support",
+          "net.imput.helium",
+          "Profile 1",
+        );
         assert.deepEqual(cookieDatabaseCandidatePaths(helium, context, "Profile 1"), [
-          `${profile}/Network/Cookies`,
-          `${profile}/Cookies`,
+          context.path.join(profile, "Network", "Cookies"),
+          context.path.join(profile, "Cookies"),
         ]);
       }),
     ),
@@ -619,7 +633,7 @@ describe("cookieDatabaseCandidatePaths", () => {
       Effect.gen(function* () {
         const fileSystem = yield* FileSystem.FileSystem;
         const context = yield* withSourceHome();
-        const root = helium.userDataDirectory(context);
+        const root = userDataDirectory(context);
         // Chromium 96+ keeps sessions in Network/; a root Cookies left behind
         // by the move is stale and must not be the one imported.
         yield* fileSystem.makeDirectory(`${root}/Default/Network`, { recursive: true });
@@ -628,7 +642,7 @@ describe("cookieDatabaseCandidatePaths", () => {
 
         assert.equal(
           yield* resolveCookieDatabase(helium, context, "Default"),
-          `${root}/Default/Network/Cookies`,
+          context.path.join(root, "Default", "Network", "Cookies"),
         );
         // A fresh install with only the Network/ jar is installed, not hidden.
         yield* fileSystem.remove(`${root}/Default/Cookies`);
@@ -660,44 +674,48 @@ describe("cookieDatabaseCandidatePaths", () => {
 const firefox = BROWSER_IMPORT_SOURCES.find((source) => source.id === "firefox")!;
 
 describe("Firefox Snap profiles", () => {
-  it.effect("finds Snap profiles with or without profiles.ini and checks their locks", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-firefox-snap-" });
-        const context = yield* sourcePathContext.pipe(
-          Effect.provideService(HostProcessEnvironment, { HOME: home }),
-          Effect.provideService(HostProcessPlatform, "linux"),
-        );
-        const root = `${home}/snap/firefox/common/.mozilla/firefox`;
-        const directory = `${root}/abcd.default`;
-        yield* fileSystem.makeDirectory(directory, { recursive: true });
-        yield* writeFirefoxCookieDatabase(`${directory}/cookies.sqlite`, 2, 1);
-        yield* fileSystem.writeFileString(
-          `${root}/profiles.ini`,
-          "[Profile0]\nName=Personal\nIsRelative=1\nPath=abcd.default\n",
-        );
+  it.effect.skipIf(!symlinksSupported)(
+    "finds Snap profiles with or without profiles.ini and checks their locks",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const home = yield* fileSystem.makeTempDirectoryScoped({
+            prefix: "t3code-firefox-snap-",
+          });
+          const context = yield* sourcePathContext.pipe(
+            Effect.provideService(HostProcessEnvironment, { HOME: home }),
+            Effect.provideService(HostProcessPlatform, "linux"),
+          );
+          const root = context.path.join(home, "snap", "firefox", "common", ".mozilla", "firefox");
+          const directory = context.path.join(root, "abcd.default");
+          yield* fileSystem.makeDirectory(directory, { recursive: true });
+          yield* writeFirefoxCookieDatabase(`${directory}/cookies.sqlite`, 2, 1);
+          yield* fileSystem.writeFileString(
+            `${root}/profiles.ini`,
+            "[Profile0]\nName=Personal\nIsRelative=1\nPath=abcd.default\n",
+          );
 
-        assert.isTrue(yield* isSourceInstalled(firefox, context));
-        assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory, name: "Personal", cookieCount: 2 },
-        ]);
-        assert.equal(
-          yield* resolveCookieDatabase(firefox, context, directory),
-          `${directory}/cookies.sqlite`,
-        );
-        assert.isFalse(yield* isSourceRunning(firefox, context));
-        yield* fileSystem.symlink("foreign-host:+4242", `${directory}/lock`);
-        assert.isTrue(yield* isSourceRunning(firefox, context));
-        yield* fileSystem.remove(`${directory}/lock`);
-        assert.isFalse(yield* isSourceRunning(firefox, context));
+          assert.isTrue(yield* isSourceInstalled(firefox, context));
+          assert.deepEqual(yield* listSourceProfiles(firefox, context), [
+            { directory, name: "Personal", cookieCount: 2 },
+          ]);
+          assert.equal(
+            yield* resolveCookieDatabase(firefox, context, directory),
+            context.path.join(directory, "cookies.sqlite"),
+          );
+          assert.isFalse(yield* isSourceRunning(firefox, context));
+          yield* fileSystem.symlink("foreign-host:+4242", `${directory}/lock`);
+          assert.isTrue(yield* isSourceRunning(firefox, context));
+          yield* fileSystem.remove(`${directory}/lock`);
+          assert.isFalse(yield* isSourceRunning(firefox, context));
 
-        yield* fileSystem.remove(`${root}/profiles.ini`);
-        assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory, name: "abcd.default", cookieCount: 2 },
-        ]);
-      }),
-    ),
+          yield* fileSystem.remove(`${root}/profiles.ini`);
+          assert.deepEqual(yield* listSourceProfiles(firefox, context), [
+            { directory, name: "abcd.default", cookieCount: 2 },
+          ]);
+        }),
+      ),
   );
 
   it.effect("keeps matching profile names in native and Snap installs distinct", () =>
@@ -709,8 +727,8 @@ describe("Firefox Snap profiles", () => {
           Effect.provideService(HostProcessEnvironment, { HOME: home }),
           Effect.provideService(HostProcessPlatform, "linux"),
         );
-        const native = `${home}/.mozilla/firefox`;
-        const snap = `${home}/snap/firefox/common/.mozilla/firefox`;
+        const native = context.path.join(home, ".mozilla", "firefox");
+        const snap = context.path.join(home, "snap", "firefox", "common", ".mozilla", "firefox");
         for (const root of [native, snap]) {
           yield* fileSystem.makeDirectory(`${root}/abcd.default`, { recursive: true });
           yield* writeFirefoxCookieDatabase(`${root}/abcd.default/cookies.sqlite`, 1, 0);
@@ -724,14 +742,14 @@ describe("Firefox Snap profiles", () => {
         const profiles = yield* listSourceProfiles(firefox, context);
         assert.deepEqual(
           profiles.map((profile) => profile.directory),
-          ["abcd.default", `${snap}/abcd.default`],
+          ["abcd.default", context.path.join(snap, "abcd.default")],
         );
         const databases = yield* Effect.forEach(profiles, (profile) =>
           resolveCookieDatabase(firefox, context, profile.directory),
         );
         assert.deepEqual(databases, [
-          `${native}/abcd.default/cookies.sqlite`,
-          `${snap}/abcd.default/cookies.sqlite`,
+          context.path.join(native, "abcd.default", "cookies.sqlite"),
+          context.path.join(snap, "abcd.default", "cookies.sqlite"),
         ]);
       }),
     ),
@@ -741,8 +759,8 @@ describe("Firefox Snap profiles", () => {
 describe("listSourceProfiles Firefox fallback", () => {
   const cases = [
     { platform: "linux" as const, profileDirectory: "linux.default" },
-    { platform: "darwin" as const, profileDirectory: "Profiles/macos.default" },
-    { platform: "win32" as const, profileDirectory: "Profiles/windows.default" },
+    { platform: "darwin" as const, profileDirectory: NodePath.join("Profiles", "macos.default") },
+    { platform: "win32" as const, profileDirectory: NodePath.join("Profiles", "windows.default") },
   ];
 
   for (const { platform, profileDirectory } of cases) {
@@ -813,7 +831,11 @@ describe("listSourceProfiles Firefox fallback", () => {
 
         // Returning the empty declared list would hide the browser entirely.
         assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory: "Profiles/real.default", name: "real.default", cookieCount: 3 },
+          {
+            directory: path.join("Profiles", "real.default"),
+            name: "real.default",
+            cookieCount: 3,
+          },
         ]);
         assert.isTrue(yield* isSourceInstalled(firefox, context));
       }),
@@ -844,7 +866,11 @@ describe("listSourceProfiles Firefox fallback", () => {
         );
 
         assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory: "Profiles/declared.default", name: "Declared", cookieCount: 2 },
+          {
+            directory: path.join("Profiles", "declared.default"),
+            name: "Declared",
+            cookieCount: 2,
+          },
         ]);
 
         yield* fileSystem.remove(path.join(root, "profiles.ini"));
@@ -853,8 +879,16 @@ describe("listSourceProfiles Firefox fallback", () => {
         yield* writeFirefoxCookieDatabase(path.join(fallbackDirectory, "cookies.sqlite"), 1, 4);
 
         assert.deepEqual(yield* listSourceProfiles(firefox, context), [
-          { directory: "Profiles/declared.default", name: "declared.default", cookieCount: 2 },
-          { directory: "Profiles/fallback.default", name: "fallback.default", cookieCount: 1 },
+          {
+            directory: path.join("Profiles", "declared.default"),
+            name: "declared.default",
+            cookieCount: 2,
+          },
+          {
+            directory: path.join("Profiles", "fallback.default"),
+            name: "fallback.default",
+            cookieCount: 1,
+          },
         ]);
       }),
     ),
@@ -862,7 +896,7 @@ describe("listSourceProfiles Firefox fallback", () => {
 });
 
 describe("isSourceRunning for Firefox", () => {
-  it.effect("finds the lock inside the profile, not at the root", () =>
+  it.effect.skipIf(!symlinksSupported)("finds the lock inside the profile, not at the root", () =>
     run(
       Effect.gen(function* () {
         const fileSystem = yield* FileSystem.FileSystem;
@@ -917,53 +951,56 @@ describe("isSourceRunning for Firefox", () => {
     ),
   );
 
-  it.effect("detects a live fcntl lock on .parentlock, as macOS Firefox leaves it", () =>
-    run(
-      Effect.gen(function* () {
-        const fileSystem = yield* FileSystem.FileSystem;
-        const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
-        const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-firefox-" });
-        const context = yield* sourcePathContext.pipe(
-          Effect.provideService(HostProcessEnvironment, { HOME: home }),
-          Effect.provideService(HostProcessPlatform, "darwin"),
-        );
-        const root = firefox.userDataDirectory(context)!;
-        const profile = `${root}/Profiles/abcd.default-release`;
-        yield* fileSystem.makeDirectory(profile, { recursive: true });
-        yield* fileSystem.writeFileString(`${profile}/cookies.sqlite`, "db");
-        const parentLock = `${profile}/.parentlock`;
-        yield* fileSystem.writeFileString(parentLock, "");
-
-        // Hold the lock from a child the way Firefox does (F_SETLK, write),
-        // and keep it until the scope closes.
-        const holder = yield* spawner.spawn(
-          ChildProcess.make(
-            "python3",
-            [
-              "-c",
-              "import fcntl,os,sys,time\n" +
-                "fd=os.open(sys.argv[1],os.O_WRONLY)\n" +
-                "fcntl.lockf(fd,fcntl.LOCK_EX|fcntl.LOCK_NB)\n" +
-                "print('locked',flush=True)\n" +
-                "time.sleep(30)",
-              parentLock,
-            ],
-            { stdin: "ignore" },
-          ),
-        );
-        // Wait for the child to confirm it holds the lock before probing.
-        yield* holder.stdout.pipe(
-          Stream.decodeText(),
-          Stream.splitLines,
-          Stream.filter((line) => line.trim() === "locked"),
-          Stream.take(1),
-          Stream.runDrain,
-        );
+  // Holds the lock with python3's fcntl, which does not exist on Windows.
+  it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+    "detects a live fcntl lock on .parentlock, as macOS Firefox leaves it",
+    () =>
+      run(
+        Effect.gen(function* () {
+          const fileSystem = yield* FileSystem.FileSystem;
+          const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+          const home = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3code-firefox-" });
+          const context = yield* sourcePathContext.pipe(
+            Effect.provideService(HostProcessEnvironment, { HOME: home }),
+            Effect.provideService(HostProcessPlatform, "darwin"),
+          );
+          const root = firefox.userDataDirectory(context)!;
+          const profile = `${root}/Profiles/abcd.default-release`;
+          yield* fileSystem.makeDirectory(profile, { recursive: true });
+          yield* fileSystem.writeFileString(`${profile}/cookies.sqlite`, "db");
+          const parentLock = `${profile}/.parentlock`;
+          yield* fileSystem.writeFileString(parentLock, "");
+
+          // Hold the lock from a child the way Firefox does (F_SETLK, write),
+          // and keep it until the scope closes.
+          const holder = yield* spawner.spawn(
+            ChildProcess.make(
+              "python3",
+              [
+                "-c",
+                "import fcntl,os,sys,time\n" +
+                  "fd=os.open(sys.argv[1],os.O_WRONLY)\n" +
+                  "fcntl.lockf(fd,fcntl.LOCK_EX|fcntl.LOCK_NB)\n" +
+                  "print('locked',flush=True)\n" +
+                  "time.sleep(30)",
+                parentLock,
+              ],
+              { stdin: "ignore" },
+            ),
+          );
+          // Wait for the child to confirm it holds the lock before probing.
+          yield* holder.stdout.pipe(
+            Stream.decodeText(),
+            Stream.splitLines,
+            Stream.filter((line) => line.trim() === "locked"),
+            Stream.take(1),
+            Stream.runDrain,
+          );
 
-        assert.isTrue(yield* isSourceRunning(firefox, context));
-        yield* holder.kill();
-      }),
-    ),
+          assert.isTrue(yield* isSourceRunning(firefox, context));
+          yield* holder.kill();
+        }),
+      ),
   );
 
   it.effect("reads a Firefox lock symlink's pid to tell live from crashed", () =>
@@ -1056,3 +1093,106 @@ describe("listSourceProfiles hardening", () => {
     ),
   );
 });
+
+describe("Safari profiles", () => {
+  const safari = BROWSER_IMPORT_SOURCES.find((source) => source.id === "safari")!;
+  const workUuid = "C561D071-67AD-4537-866F-54F65FB8E8DD";
+  const otherUuid = "2875EB19-B938-4E38-BE92-5AE97C256BDD";
+
+  const fixture = Effect.fnUntraced(function* () {
+    const context = yield* withSourceHome();
+    const fileSystem = yield* FileSystem.FileSystem;
+    const root = safari.userDataDirectory(context)!;
+    const library = context.path.dirname(root);
+    yield* fileSystem.makeDirectory(root, { recursive: true });
+    yield* fileSystem.writeFileString(context.path.join(root, "Cookies.binarycookies"), "default");
+    const store = (uuid: string) =>
+      context.path.join(library, "WebKit", "WebsiteDataStore", uuid.toLowerCase(), "Cookies");
+    for (const uuid of [workUuid, otherUuid]) {
+      yield* fileSystem.makeDirectory(store(uuid), { recursive: true });
+      yield* fileSystem.writeFileString(
+        context.path.join(store(uuid), "Cookies.binarycookies"),
+        uuid,
+      );
+    }
+    yield* fileSystem.makeDirectory(context.path.join(library, "Safari"), { recursive: true });
+    const metadata = context.path.join(library, "Safari", "SafariTabs.db");
+    return { context, root, store, metadata };
+  });
+
+  it.effect("discovers named profiles and resolves only the selected profile's cookies", () =>
+    run(
+      Effect.gen(function* () {
+        const { context, root, store, metadata } = yield* fixture();
+        yield* Effect.sync(() => {
+          const database = new NodeSqlite.DatabaseSync(metadata);
+          try {
+            database.exec(`CREATE TABLE bookmarks (
+            title TEXT, external_uuid TEXT, parent INTEGER DEFAULT 0,
+            type INTEGER DEFAULT 1, subtype INTEGER DEFAULT 2,
+            deleted INTEGER DEFAULT 0, order_index INTEGER DEFAULT 0
+          )`);
+            const insert = database.prepare(
+              "INSERT INTO bookmarks (title, external_uuid, deleted) VALUES (?, ?, ?)",
+            );
+            insert.run("", "DefaultProfile", 0);
+            insert.run("Ping", workUuid, 0);
+            insert.run("Deleted", otherUuid, 1);
+            insert.run("Unsafe", "../../outside", 0);
+            database.exec(
+              "INSERT INTO bookmarks (title, external_uuid, subtype) VALUES ('Tab group', 'group', 1)",
+            );
+          } finally {
+            database.close();
+          }
+        });
+        const profiles = yield* listSourceProfiles(safari, context);
+        assert.deepEqual(profiles, [
+          { directory: ".", name: "Personal" },
+          { directory: store(workUuid), name: "Ping" },
+        ]);
+        assert.strictEqual(
+          yield* resolveCookieDatabase(safari, context, "."),
+          context.path.join(root, "Cookies.binarycookies"),
+        );
+        const selected = yield* resolveCookieDatabase(safari, context, profiles[1]!.directory);
+        assert.strictEqual(selected, context.path.join(store(workUuid), "Cookies.binarycookies"));
+        const fileSystem = yield* FileSystem.FileSystem;
+        assert.strictEqual(yield* fileSystem.readFileString(selected!), workUuid);
+        yield* fileSystem.remove(selected!);
+        assert.isUndefined(yield* resolveCookieDatabase(safari, context, profiles[1]!.directory));
+        assert.deepEqual(yield* listSourceProfiles(safari, context), profiles);
+      }),
+    ),
+  );
+
+  for (const metadataState of ["missing", "corrupt"] as const) {
+    it.effect(`recovers separate cookie stores when metadata is ${metadataState}`, () =>
+      run(
+        Effect.gen(function* () {
+          const { context, store, metadata } = yield* fixture();
+          const fileSystem = yield* FileSystem.FileSystem;
+          if (metadataState === "corrupt") yield* fileSystem.writeFileString(metadata, "invalid");
+          yield* fileSystem.remove(context.path.join(store(otherUuid), "Cookies.binarycookies"));
+          assert.deepEqual(yield* listSourceProfiles(safari, context), [
+            { directory: ".", name: "Safari" },
+            { directory: store(workUuid), name: workUuid.toLowerCase() },
+          ]);
+          assert.isTrue(yield* isSourceInstalled(safari, context));
+        }),
+      ),
+    );
+  }
+
+  it.effect("keeps Safari without profiles available", () =>
+    run(
+      Effect.gen(function* () {
+        const context = yield* withSourceHome();
+        assert.deepEqual(yield* listSourceProfiles(safari, context), [
+          { directory: ".", name: "Safari" },
+        ]);
+        assert.isFalse(yield* isSourceInstalled(safari, context));
+      }),
+    ),
+  );
+});
diff --git a/apps/desktop/src/preview/BrowserImport/Sources.ts b/apps/desktop/src/preview/BrowserImport/Sources.ts
index 702933a432b3..6075f0ad56a3 100644
--- a/apps/desktop/src/preview/BrowserImport/Sources.ts
+++ b/apps/desktop/src/preview/BrowserImport/Sources.ts
@@ -1,10 +1,11 @@
 /**
  * Importable browser sources.
  *
- * Two engines are modelled. Chromium-family browsers keep cookies in an
+ * Chromium-family browsers keep cookies in an
  * encrypted SQLite database whose key lives in an OS credential store; Firefox
  * keeps them in plain SQLite with no key at all, so it needs no keychain and
- * works the same on every platform.
+ * works the same on every platform. Safari uses binary cookie files, with
+ * separate WebKit data stores for named profiles.
  *
  * Each entry pins its own paths and credential-store coordinates rather than
  * deriving them, because the forks do not agree. macOS uses service/account
@@ -31,7 +32,7 @@ import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
-export type BrowserImportEngine = "chromium" | "firefox";
+export type BrowserImportEngine = "chromium" | "firefox" | "safari";
 
 /**
  * Directory roots a definition builds its paths from. Passed in rather than
@@ -177,6 +178,26 @@ export const BROWSER_IMPORT_SOURCES: ReadonlyArray<BrowserImportSourceDefinition
     // Helium retains Chromium's libsecret application name on Linux.
     linuxSecretApplication: "chromium",
   }),
+  {
+    // The default jar lives here; named profiles use WebKit data stores
+    // alongside this directory inside the same app container.
+    id: "safari",
+    name: "Safari",
+    engine: "safari",
+    platforms: ["darwin"],
+    userDataDirectory: (context) =>
+      context.platform === "darwin"
+        ? context.path.join(
+            context.home,
+            "Library",
+            "Containers",
+            "com.apple.Safari",
+            "Data",
+            "Library",
+            "Cookies",
+          )
+        : undefined,
+  },
   {
     id: "firefox",
     name: "Firefox",
@@ -220,6 +241,9 @@ export const cookieDatabaseCandidatePaths = (
   if (definition.engine === "firefox") {
     return [context.path.join(profilePath, "cookies.sqlite")];
   }
+  if (definition.engine === "safari") {
+    return [context.path.join(profilePath, "Cookies.binarycookies")];
+  }
   // Chromium: pre-96 uses `Cookies`, 96+ use `Network/Cookies`. An upgrade
   // leaves the legacy file behind, so prefer the current one and fall back.
   return [
@@ -386,6 +410,64 @@ const withCookieCounts = (
     ),
   );
 
+const SafariProfileRows = Schema.Array(
+  Schema.Struct({ title: Schema.NullOr(Schema.String), external_uuid: Schema.String }),
+);
+const decodeSafariProfiles = Schema.decodeUnknownEffect(SafariProfileRows);
+const isSafariProfileUuid = (value: string) =>
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+
+const listSafariProfiles = Effect.fnUntraced(function* (
+  context: BrowserImportPathContext,
+  root: string,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const library = context.path.dirname(root);
+  const metadata = context.path.join(library, "Safari", "SafariTabs.db");
+  const declared = yield* Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    return yield* decodeSafariProfiles(
+      yield* sql`
+      select title, external_uuid from bookmarks
+      where parent = 0 and type = 1 and subtype = 2 and deleted = 0
+      order by order_index
+    `,
+    );
+  }).pipe(
+    Effect.provide(NodeSqliteClient.layer({ filename: metadata, readonly: true })),
+    Effect.orElseSucceed(() => []),
+  );
+  const defaultProfile = declared.find((profile) => profile.external_uuid === "DefaultProfile");
+  const profiles: Array<BrowserImportSourceProfile> = [
+    {
+      directory: ".",
+      name: defaultProfile ? defaultProfile.title?.trim() || "Personal" : "Safari",
+    },
+  ];
+  const stores = context.path.join(library, "WebKit", "WebsiteDataStore");
+  const profileDirectory = (uuid: string) =>
+    context.path.join(stores, uuid.toLowerCase(), "Cookies");
+  for (const profile of declared) {
+    if (!isSafariProfileUuid(profile.external_uuid)) continue;
+    profiles.push({
+      directory: profileDirectory(profile.external_uuid),
+      name: profile.title?.trim() || profile.external_uuid,
+    });
+  }
+  // If Safari's metadata is unavailable, recover stores that have cookies.
+  // With readable metadata, avoid resurrecting deleted profiles left on disk.
+  if (declared.length === 0) {
+    const entries = yield* fileSystem.readDirectory(stores).pipe(Effect.orElseSucceed(() => []));
+    for (const entry of entries.filter(isSafariProfileUuid).sort()) {
+      const directory = context.path.join(stores, entry, "Cookies");
+      if (yield* databaseFileExists(context.path.join(directory, "Cookies.binarycookies"))) {
+        profiles.push({ directory, name: entry });
+      }
+    }
+  }
+  return profiles;
+});
+
 /**
  * Profiles the source browser knows about.
  *
@@ -403,6 +485,10 @@ const listSourceProfilesInDirectory = Effect.fnUntraced(function* (
   const root = definition.userDataDirectory(context);
   if (root === undefined) return [];
 
+  if (definition.engine === "safari") {
+    return yield* listSafariProfiles(context, root);
+  }
+
   if (definition.engine === "firefox") {
     const declared = yield* fileSystem.readFileString(context.path.join(root, "profiles.ini")).pipe(
       Effect.map((ini) => parseFirefoxProfiles(ini, context.path, root)),
@@ -773,11 +859,15 @@ export const isSourceRunning = Effect.fn("BrowserImportSources.isSourceRunning")
   const root = definition.userDataDirectory(context);
   if (root === undefined) return false;
   // Probe the source's own lock state rather than scanning the process table.
+  // Safari keeps no lock and writes its jar atomically, so a running instance
+  // is not a hazard there.
+  //
   // Chromium exposes its lock through the cookie jar on Windows and through a
   // user-data SingletonLock on POSIX. Firefox keeps its locks inside each
   // profile under three names across platforms (`lock` on macOS and Linux,
   // `.parentlock` beside it, `parent.lock` on Windows). Looking for Firefox's
   // at the root finds nothing and reports a running browser as importable.
+  if (definition.engine === "safari") return false;
   if (definition.engine !== "firefox") {
     if (context.platform === "win32") {
       return yield* windowsChromiumCookiesAreHeld(definition, context);
diff --git a/apps/desktop/src/preview/BrowserSession.test.ts b/apps/desktop/src/preview/BrowserSession.test.ts
index ff22f3dd2272..aaf34c3578f9 100644
--- a/apps/desktop/src/preview/BrowserSession.test.ts
+++ b/apps/desktop/src/preview/BrowserSession.test.ts
@@ -172,8 +172,6 @@ describe("BrowserSession", () => {
       const error = yield* browserSessions.getPartition("environment-a").pipe(Effect.flip);
 
       assert.instanceOf(error, BrowserSession.BrowserSessionPartitionDerivationError);
-      assert.isTrue(BrowserSession.isBrowserSessionGetSessionError(error));
-      assert.isTrue(BrowserSession.isBrowserSessionError(error));
       assert.equal(error.scope, "environment-a");
       assert.strictEqual(error.cause, platformCause);
       assert.strictEqual(error.cause.reason.cause, nativeCause);
@@ -196,8 +194,6 @@ describe("BrowserSession", () => {
       const error = yield* browserSessions.getSession("environment-b").pipe(Effect.flip);
 
       assert.instanceOf(error, BrowserSession.BrowserSessionCreationError);
-      assert.isTrue(BrowserSession.isBrowserSessionGetSessionError(error));
-      assert.isTrue(BrowserSession.isBrowserSessionError(error));
       assert.equal(error.scope, "environment-b");
       assert.equal(error.partition, partition);
       assert.strictEqual(error.cause, cause);
@@ -270,7 +266,6 @@ describe("BrowserSession", () => {
       const storageError = yield* browserSessions.clearCookies().pipe(Effect.flip);
 
       assert.instanceOf(storageError, BrowserSession.BrowserSessionStorageClearError);
-      assert.isTrue(BrowserSession.isBrowserSessionError(storageError));
       assert.equal(storageError.partition, secondPartition);
       assert.strictEqual(storageError.cause, storageCause);
       assert.equal(
@@ -287,7 +282,6 @@ describe("BrowserSession", () => {
       const cacheError = yield* browserSessions.clearCache().pipe(Effect.flip);
 
       assert.instanceOf(cacheError, BrowserSession.BrowserSessionCacheClearError);
-      assert.isTrue(BrowserSession.isBrowserSessionError(cacheError));
       assert.equal(cacheError.partition, firstPartition);
       assert.strictEqual(cacheError.cause, cacheCause);
       assert.equal(
diff --git a/apps/desktop/src/preview/BrowserSession.ts b/apps/desktop/src/preview/BrowserSession.ts
index 7f3c9ec5d7ac..7ff879852283 100644
--- a/apps/desktop/src/preview/BrowserSession.ts
+++ b/apps/desktop/src/preview/BrowserSession.ts
@@ -93,7 +93,6 @@ export const BrowserSessionGetSessionError = Schema.Union([
   BrowserSessionCreationError,
 ]);
 export type BrowserSessionGetSessionError = typeof BrowserSessionGetSessionError.Type;
-export const isBrowserSessionGetSessionError = Schema.is(BrowserSessionGetSessionError);
 
 export const BrowserSessionError = Schema.Union([
   BrowserSessionPartitionDerivationError,
@@ -102,7 +101,6 @@ export const BrowserSessionError = Schema.Union([
   BrowserSessionCacheClearError,
 ]);
 export type BrowserSessionError = typeof BrowserSessionError.Type;
-export const isBrowserSessionError = Schema.is(BrowserSessionError);
 
 export class BrowserSession extends Context.Service<
   BrowserSession,
diff --git a/apps/desktop/src/preview/Manager.test.ts b/apps/desktop/src/preview/Manager.test.ts
index a7b3afabd3c3..79c7fd1725e1 100644
--- a/apps/desktop/src/preview/Manager.test.ts
+++ b/apps/desktop/src/preview/Manager.test.ts
@@ -272,6 +272,7 @@ const makeTestPreviewWebContents = (
     ipc: { on: vi.fn(), off: vi.fn() },
     send: webviewSend,
     navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+    setIgnoreMenuShortcuts: vi.fn(),
     setWindowOpenHandler: vi.fn(),
     debugger: {
       isAttached: () => false,
@@ -382,6 +383,7 @@ const makeFaviconWebContents = (options?: {
     send: webviewSend,
     session: { fetch },
     navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+    setIgnoreMenuShortcuts: vi.fn(),
     setWindowOpenHandler: vi.fn(),
     executeJavaScriptInIsolatedWorld,
     debugger: {
@@ -474,6 +476,67 @@ describe("PreviewManager", () => {
     webviewSend.mockClear();
   });
 
+  effectIt.effect("keeps preview shortcuts out of the host window", () =>
+    withManager((manager) =>
+      Effect.gen(function* () {
+        const preview = makeFaviconWebContents();
+        const sendInputEvent = vi.fn();
+        const hostWebContents = { sendInputEvent };
+        Object.assign(preview.webContents, { hostWebContents });
+        fromId.mockReturnValue(preview.webContents);
+        yield* manager.setMainWindow({
+          isDestroyed: () => false,
+          once: vi.fn(),
+          webContents: hostWebContents,
+        } as never);
+        yield* manager.createTab("tab_keys");
+        yield* manager.registerWebview("tab_keys", 42);
+
+        expect(
+          (preview.webContents as Electron.WebContents).setIgnoreMenuShortcuts,
+        ).toHaveBeenCalledWith(true);
+        const beforeInput = preview.listeners.get("before-input-event")!;
+        for (const control of [false, true]) {
+          for (const key of ["k", ",", "w", "j", "q", "+", "a", "c", "v", "x"]) {
+            for (const type of ["keyDown", "keyUp"]) {
+              const preventDefault = vi.fn();
+              beforeInput(
+                { preventDefault } as never,
+                { type, key, meta: !control, control, shift: key === "j", alt: false } as never,
+              );
+              yield* Effect.yieldNow;
+              expect(preventDefault).not.toHaveBeenCalled();
+            }
+          }
+        }
+        expect(sendInputEvent).not.toHaveBeenCalled();
+
+        const preventDefault = vi.fn();
+        beforeInput(
+          { preventDefault } as never,
+          {
+            type: "keyDown",
+            key: "r",
+            meta: true,
+            control: false,
+            shift: false,
+            alt: false,
+          } as never,
+        );
+        yield* Effect.yieldNow;
+        expect(preventDefault).toHaveBeenCalledOnce();
+        expect(preview.reload).toHaveBeenCalledOnce();
+        expect(sendInputEvent).not.toHaveBeenCalled();
+
+        const setIgnoreMenuShortcuts = vi.fn();
+        preview.listeners.get("did-create-window")!({
+          webContents: { setIgnoreMenuShortcuts, setWindowOpenHandler: vi.fn() },
+        } as never);
+        expect(setIgnoreMenuShortcuts).toHaveBeenCalledWith(true);
+      }),
+    ),
+  );
+
   effectIt.effect("reports an unregistered webview as temporarily unavailable", () =>
     withManager((manager) =>
       Effect.gen(function* () {
@@ -617,6 +680,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -718,6 +782,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           get debugger() {
             if (destroyed) throw new Error("Object has been destroyed");
@@ -1222,6 +1287,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1286,6 +1352,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1326,6 +1393,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1372,6 +1440,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1427,6 +1496,7 @@ describe("PreviewManager", () => {
               ipc: { on: vi.fn(), off: vi.fn() },
               send: webviewSend,
               navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+              setIgnoreMenuShortcuts: vi.fn(),
               setWindowOpenHandler: vi.fn(),
               debugger: {
                 isAttached: () => false,
@@ -1524,6 +1594,7 @@ describe("PreviewManager", () => {
         ipc: { on: vi.fn(), off: vi.fn() },
         send: webviewSend,
         navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+        setIgnoreMenuShortcuts: vi.fn(),
         setWindowOpenHandler: vi.fn(),
         debugger: {
           isAttached: () => false,
@@ -1859,6 +1930,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1951,6 +2023,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -1987,10 +2060,30 @@ describe("PreviewManager", () => {
           /\/browser-artifacts\/browser-screenshot-example-com-[^.]+\.png$/,
         );
 
+        // Chromium reports UnknownVizError while a hidden guest warms its
+        // first compositor frame, so transient failures are retried.
+        capturePage.mockClear();
+        capturePage.mockRejectedValueOnce(new Error("UnknownVizError"));
+        capturePage.mockRejectedValueOnce(new Error("UnknownVizError"));
+        const retriedFiber = yield* Effect.exit(manager.captureScreenshot("tab_1")).pipe(
+          Effect.forkChild({ startImmediately: true }),
+        );
+        yield* TestClock.adjust(1_000);
+        const retriedExit = yield* Fiber.join(retriedFiber);
+        expect(Exit.isSuccess(retriedExit)).toBe(true);
+        expect(capturePage).toHaveBeenCalledTimes(3);
+
+        // A persistent failure still surfaces once the retries are spent.
+        capturePage.mockClear();
         const captureCause = new Error("capture failed");
-        capturePage.mockRejectedValueOnce(captureCause);
-        const exit = yield* Effect.exit(manager.captureScreenshot("tab_1"));
+        capturePage.mockRejectedValue(captureCause);
+        const failingFiber = yield* Effect.exit(manager.captureScreenshot("tab_1")).pipe(
+          Effect.forkChild({ startImmediately: true }),
+        );
+        yield* TestClock.adjust(1_000);
+        const exit = yield* Fiber.join(failingFiber);
         expect(Exit.isFailure(exit)).toBe(true);
+        expect(capturePage).toHaveBeenCalledTimes(3);
         if (Exit.isSuccess(exit)) return;
         const error = Option.getOrThrow(Cause.findErrorOption(exit.cause));
         expect(error).toMatchObject({
@@ -2324,6 +2417,127 @@ describe("PreviewManager", () => {
     ),
   );
 
+  effectIt.effect("stops capture retries when the tab swaps during the retry delay", () =>
+    withManager((manager) =>
+      Effect.gen(function* () {
+        const capturePage = vi.fn(async () => ({
+          toPNG: () => Buffer.from("png"),
+          toJPEG: () => Buffer.from("jpeg"),
+          getSize: () => ({ width: 100, height: 80 }),
+        }));
+        fromId.mockReturnValue(makeTestPreviewWebContents(capturePage, 42));
+        yield* manager.createTab("tab_1");
+        yield* manager.registerWebview("tab_1", 42);
+
+        capturePage.mockRejectedValueOnce(new Error("UnknownVizError"));
+        const fiber = yield* Effect.exit(manager.captureScreenshot("tab_1")).pipe(
+          Effect.forkChild({ startImmediately: true }),
+        );
+        // Let the rejection schedule its retry before replacing the guest.
+        yield* TestClock.adjust(60);
+        expect(capturePage).toHaveBeenCalledTimes(1);
+        fromId.mockReturnValue(makeTestPreviewWebContents(capturePage, 43));
+        yield* manager.registerWebview("tab_1", 43);
+        yield* TestClock.adjust(1_000);
+        const exit = yield* Fiber.join(fiber);
+
+        expect(Exit.isFailure(exit)).toBe(true);
+        expect(capturePage).toHaveBeenCalledTimes(1);
+        expect(writeFile).not.toHaveBeenCalled();
+      }),
+    ),
+  );
+
+  effectIt.effect("discards a screenshot that resolves after its guest is replaced", () =>
+    withManager((manager) =>
+      Effect.gen(function* () {
+        const image = {
+          toPNG: () => Buffer.from("stale-png"),
+          toJPEG: () => Buffer.from("stale-jpeg"),
+          getSize: () => ({ width: 100, height: 80 }),
+        };
+        const pending = Promise.withResolvers<typeof image>();
+        const capturePage = vi.fn(() => pending.promise);
+        fromId.mockReturnValue(makeTestPreviewWebContents(capturePage, 42));
+        yield* manager.createTab("tab_1");
+        yield* manager.registerWebview("tab_1", 42);
+
+        const fiber = yield* Effect.exit(manager.captureScreenshot("tab_1")).pipe(
+          Effect.forkChild({ startImmediately: true }),
+        );
+        yield* TestClock.adjust(0);
+        expect(capturePage).toHaveBeenCalledOnce();
+        fromId.mockReturnValue(makeTestPreviewWebContents(capturePage, 43));
+        yield* manager.registerWebview("tab_1", 43);
+        pending.resolve(image);
+        const exit = yield* Fiber.join(fiber);
+
+        expect(Exit.isFailure(exit)).toBe(true);
+        expect(capturePage).toHaveBeenCalledOnce();
+        expect(writeFile).not.toHaveBeenCalled();
+      }),
+    ),
+  );
+
+  effectIt.effect("releases snapshot control when every capture attempt stalls", () =>
+    withManager((manager) =>
+      Effect.gen(function* () {
+        const capturePage = vi.fn(() => new Promise<TestCapturedPreviewImage>(() => {}));
+        const wc = makeTestPreviewWebContents(capturePage);
+        Object.assign(wc, { isDevToolsOpened: () => false });
+        Object.assign(wc.debugger, {
+          sendCommand: vi.fn(async (method: string, params?: Record<string, unknown>) => {
+            if (method === "Runtime.evaluate") {
+              return {
+                result: {
+                  value:
+                    params?.["expression"] === "42"
+                      ? 42
+                      : {
+                          url: "https://example.com",
+                          title: "Example",
+                          loading: false,
+                          visibleText: "Example",
+                          interactiveElements: [],
+                        },
+                },
+              };
+            }
+            return method === "Accessibility.getFullAXTree" ? { nodes: [] } : undefined;
+          }),
+        });
+        fromId.mockReturnValue(wc);
+        yield* manager.createTab("tab_1");
+        yield* manager.registerWebview("tab_1", 42);
+
+        const snapshot = yield* Effect.exit(manager.automationSnapshot("tab_1")).pipe(
+          Effect.forkChild({ startImmediately: true }),
+        );
+        yield* TestClock.adjust(100);
+        expect(capturePage).toHaveBeenCalledOnce();
+        const evaluate = yield* manager
+          .automationEvaluate("tab_1", { expression: "42" })
+          .pipe(Effect.forkChild({ startImmediately: true }));
+        expect(evaluate.pollUnsafe()).toBeUndefined();
+
+        yield* TestClock.adjust(4_000);
+        const exit = yield* Fiber.join(snapshot);
+        expect(Exit.isFailure(exit)).toBe(true);
+        expect(capturePage).toHaveBeenCalledTimes(3);
+        if (Exit.isSuccess(exit)) return;
+        const error = Option.getOrThrow(Cause.findErrorOption(exit.cause));
+        expect(error).toMatchObject({
+          _tag: "PreviewOperationError",
+          operation: "automationSnapshot.capturePage",
+          tabId: "tab_1",
+          webContentsId: 42,
+          cause: { _tag: "TimeoutError" },
+        });
+        expect(yield* Fiber.join(evaluate)).toBe(42);
+      }),
+    ),
+  );
+
   effectIt.effect("grants each concurrent preview recording its own tab frame", () =>
     withManager((manager) =>
       Effect.gen(function* () {
@@ -2368,6 +2582,7 @@ describe("PreviewManager", () => {
             ipc: { on: vi.fn(), off: vi.fn() },
             send: webviewSend,
             navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+            setIgnoreMenuShortcuts: vi.fn(),
             setWindowOpenHandler: vi.fn(),
             debugger: {
               isAttached: () => false,
@@ -2670,6 +2885,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3173,6 +3389,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn(), removeListener: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3228,6 +3445,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3304,6 +3522,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3389,6 +3608,7 @@ describe("PreviewManager", () => {
             goBack,
             goForward,
           },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3518,6 +3738,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3618,6 +3839,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3773,6 +3995,7 @@ describe("PreviewManager", () => {
           },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
@@ -3837,6 +4060,7 @@ describe("PreviewManager", () => {
           ipc: { on: vi.fn(), off: vi.fn() },
           send: webviewSend,
           navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+          setIgnoreMenuShortcuts: vi.fn(),
           setWindowOpenHandler: vi.fn(),
           debugger: {
             isAttached: () => false,
diff --git a/apps/desktop/src/preview/Manager.ts b/apps/desktop/src/preview/Manager.ts
index 324b92034f36..900ba5fe983c 100644
--- a/apps/desktop/src/preview/Manager.ts
+++ b/apps/desktop/src/preview/Manager.ts
@@ -48,6 +48,7 @@ import * as Path from "effect/Path";
 import * as Ref from "effect/Ref";
 import * as Schema from "effect/Schema";
 import * as Semaphore from "effect/Semaphore";
+import * as Schedule from "effect/Schedule";
 import * as Scope from "effect/Scope";
 import * as SynchronizedRef from "effect/SynchronizedRef";
 
@@ -113,6 +114,13 @@ const MAX_SCREENSHOT_WIDTH = 1280;
 const RECORDING_ARM_GRACE_MS = 10_000;
 const PICTURE_IN_PICTURE_FRAME_INTERVAL_MS = Math.ceil(1_000 / 12);
 const PICTURE_IN_PICTURE_JPEG_QUALITY = 80;
+/**
+ * Cold guests can reject capturePage with UnknownVizError or never settle it.
+ * Bound each attempt so snapshots release control even when Chromium stalls.
+ */
+const CAPTURE_PAGE_RETRY_ATTEMPTS = 3;
+const CAPTURE_PAGE_RETRY_DELAY_MS = 120;
+const CAPTURE_PAGE_ATTEMPT_TIMEOUT_MS = 1_000;
 const PICTURE_IN_PICTURE_INITIAL_WIDTH = 480;
 const PICTURE_IN_PICTURE_INITIAL_HEIGHT = 320;
 const PICTURE_IN_PICTURE_MIN_WIDTH = 240;
@@ -465,22 +473,6 @@ interface ExpectedAgentInput {
   readonly expiresAt: number;
 }
 
-const APP_FORWARDED_SHORTCUTS: ReadonlyArray<{
-  key: string;
-  meta: boolean;
-  shift: boolean;
-  control: boolean;
-}> = Object.freeze([
-  // mod+shift+J → preview.toggle
-  { key: "j", meta: true, shift: true, control: false },
-  // mod+K → command palette
-  { key: "k", meta: true, shift: false, control: false },
-  // mod+, → settings (macOS convention)
-  { key: ",", meta: true, shift: false, control: false },
-  // mod+W → close tab/panel
-  { key: "w", meta: true, shift: false, control: false },
-]);
-
 /**
  * Protocols a preview page may open in a real popup window.
  *
@@ -655,6 +647,42 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       try: evaluate,
       catch: (cause) => new PreviewOperationError({ ...errorContext, cause }),
     });
+  const capturePageWithRetry = Effect.fn("PreviewManager.capturePageWithRetry")(function* (
+    errorContext: PreviewOperationContext,
+    tabId: string,
+    wc: Electron.WebContents,
+  ) {
+    const requireCurrentGuest = Effect.gen(function* () {
+      const tabs = yield* SynchronizedRef.get(tabsRef);
+      if (wc.isDestroyed() || tabs.get(tabId)?.webContentsId !== wc.id) {
+        return yield* new PreviewWebContentsNotFoundError({ tabId, webContentsId: wc.id });
+      }
+    });
+    const capture = Effect.gen(function* () {
+      // Check after the retry delay, and again before accepting its result.
+      yield* requireCurrentGuest;
+      const image = yield* Effect.tryPromise({
+        // An abort-signal parameter makes a stalled promise interruptible.
+        try: (_signal) => wc.capturePage(),
+        catch: (cause) => new PreviewOperationError({ ...errorContext, cause }),
+      }).pipe(
+        Effect.timeout(CAPTURE_PAGE_ATTEMPT_TIMEOUT_MS),
+        Effect.catchTags({
+          TimeoutError: (cause) =>
+            Effect.fail(new PreviewOperationError({ ...errorContext, cause })),
+        }),
+      );
+      yield* requireCurrentGuest;
+      return image;
+    });
+    return yield* capture.pipe(
+      Effect.retry({
+        times: CAPTURE_PAGE_RETRY_ATTEMPTS - 1,
+        schedule: Schedule.spaced(CAPTURE_PAGE_RETRY_DELAY_MS),
+        while: isPreviewOperationError,
+      }),
+    );
+  });
   const currentIso = DateTime.now.pipe(Effect.map(DateTime.formatIso));
   const currentMillis = Clock.currentTimeMillis;
   const encodeJson = (errorContext: PreviewOperationContext, value: unknown) =>
@@ -1535,16 +1563,6 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     }
   });
 
-  const isAppShortcut = (input: Electron.Input): boolean =>
-    input.type === "keyDown" &&
-    APP_FORWARDED_SHORTCUTS.some(
-      (shortcut) =>
-        shortcut.key.toLowerCase() === input.key.toLowerCase() &&
-        shortcut.meta === input.meta &&
-        shortcut.shift === input.shift &&
-        shortcut.control === input.control,
-    );
-
   const computeNavStatus = (wc: Electron.WebContents): PreviewNavStatus => {
     const url = wc.getURL();
     const title = wc.getTitle();
@@ -1819,30 +1837,11 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         }).pipe(Effect.ignore),
       );
     };
-    const forwardShortcut = Effect.fn("PreviewManager.forwardShortcut")(function* (
-      event: Electron.Event,
-      input: Electron.Input,
-    ) {
-      const mainWindow = yield* Ref.get(mainWindowRef);
-      if (!isAppShortcut(input) || Option.isNone(mainWindow) || mainWindow.value.isDestroyed()) {
-        return;
-      }
-      event.preventDefault();
-      mainWindow.value.webContents.sendInputEvent({
-        type: "keyDown",
-        keyCode: input.key,
-        modifiers: [
-          ...(input.meta ? (["meta"] as const) : []),
-          ...(input.shift ? (["shift"] as const) : []),
-          ...(input.control ? (["control"] as const) : []),
-          ...(input.alt ? (["alt"] as const) : []),
-        ],
-      });
-    });
     // A popup opens with Electron's default handler, so the page inside it could
     // otherwise spawn native windows without limit. Nothing in an OAuth flow
     // opens a second popup, so the chain stops at the first one.
     const windowCreated = (window: Electron.BrowserWindow): void => {
+      window.webContents.setIgnoreMenuShortcuts(true);
       window.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
     };
     const beforeInput = (event: Electron.Event, input: Electron.Input): void => {
@@ -1855,7 +1854,6 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
         );
         return;
       }
-      runFork(forwardShortcut(event, input));
     };
     yield* Scope.addFinalizer(
       scope,
@@ -1878,6 +1876,9 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     );
     const install = Effect.fn("PreviewManager.installWebContentsListeners")(function* () {
       yield* attempt({ operation: "attachListeners", tabId, webContentsId: wc.id }, () => {
+        // Preview input belongs to the page, including keys injected through CDP.
+        // Never let it invoke the host application's menu accelerators.
+        wc.setIgnoreMenuShortcuts(true);
         wc.on("did-start-navigation", navigationStarted);
         wc.on("did-navigate", syncNavigation);
         wc.on("did-navigate-in-page", syncInPageNavigation);
@@ -2691,13 +2692,14 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
     const [createdAt, millis, image] = yield* Effect.all([
       currentIso,
       currentMillis,
-      attemptPromise(
+      capturePageWithRetry(
         {
           operation: "captureScreenshot.capturePage",
           tabId,
           webContentsId: wc.id,
         },
-        () => wc.capturePage(),
+        tabId,
+        wc,
       ),
     ]);
     const id = `browser-screenshot-${artifactSiteSlug(wc.getURL())}-${millis.toString(36)}`;
@@ -3556,13 +3558,14 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
       );
       const [accessibility, sourceImage, diagnostics, timelines] = yield* Effect.all([
         send("Accessibility.getFullAXTree"),
-        attemptPromise(
+        capturePageWithRetry(
           {
             operation: "automationSnapshot.capturePage",
             tabId,
             webContentsId: wc.id,
           },
-          () => wc.capturePage(),
+          tabId,
+          wc,
         ),
         Ref.get(diagnosticsRef),
         Ref.get(actionTimelineRef),
diff --git a/apps/desktop/src/settings/DesktopClientSettings.diagnostics.test.ts b/apps/desktop/src/settings/DesktopClientSettings.diagnostics.test.ts
index 5034df44cf70..d2fd166e878c 100644
--- a/apps/desktop/src/settings/DesktopClientSettings.diagnostics.test.ts
+++ b/apps/desktop/src/settings/DesktopClientSettings.diagnostics.test.ts
@@ -54,7 +54,7 @@ const readWithLogs = (fileSystemLayer: Layer.Layer<FileSystem.FileSystem>) => {
     const environment = yield* DesktopEnvironment.DesktopEnvironment;
     const settings = yield* DesktopClientSettings.DesktopClientSettings;
     return {
-      result: yield* settings.get,
+      result: yield* Effect.result(settings.get),
       settingsPath: environment.clientSettingsPath,
       records,
     };
@@ -73,12 +73,13 @@ describe("DesktopClientSettings diagnostics", () => {
     Effect.gen(function* () {
       const result = yield* readWithLogs(FileSystem.layerNoop({}));
 
-      assert.isTrue(Option.isNone(result.result));
+      if (result.result._tag !== "Success") return assert.fail("expected a successful read");
+      assert.isTrue(Option.isNone(result.result.success));
       assert.deepEqual(result.records, []);
     }),
   );
 
-  it.effect("logs non-missing filesystem failures with the settings path", () => {
+  it.effect("reports non-missing filesystem failures and logs the settings path", () => {
     const permissionError = PlatformError.systemError({
       _tag: "PermissionDenied",
       module: "FileSystem",
@@ -93,7 +94,12 @@ describe("DesktopClientSettings diagnostics", () => {
         }),
       );
 
-      assert.isTrue(Option.isNone(result.result));
+      if (result.result._tag !== "Failure") return assert.fail("expected a read failure");
+      assert.instanceOf(
+        result.result.failure,
+        DesktopClientSettings.DesktopClientSettingsReadError,
+      );
+      assert.strictEqual(result.result.failure.cause, permissionError);
       assert.equal(result.records.length, 1);
       assert.deepEqual(result.records[0]?.message, [
         "Could not read desktop client settings.",
@@ -103,7 +109,7 @@ describe("DesktopClientSettings diagnostics", () => {
     });
   });
 
-  it.effect("logs malformed settings documents with the settings path", () =>
+  it.effect("reports malformed settings documents and logs the settings path", () =>
     Effect.gen(function* () {
       const result = yield* readWithLogs(
         FileSystem.layerNoop({
@@ -111,7 +117,12 @@ describe("DesktopClientSettings diagnostics", () => {
         }),
       );
 
-      assert.isTrue(Option.isNone(result.result));
+      if (result.result._tag !== "Failure") return assert.fail("expected a decode failure");
+      assert.instanceOf(
+        result.result.failure,
+        DesktopClientSettings.DesktopClientSettingsReadError,
+      );
+      assert.equal(result.result.failure.operation, "decode-document");
       assert.equal(result.records.length, 1);
       const message = result.records[0]?.message;
       if (!Array.isArray(message)) {
diff --git a/apps/desktop/src/settings/DesktopClientSettings.test.ts b/apps/desktop/src/settings/DesktopClientSettings.test.ts
index 28cce3cfb507..9fbacc832a90 100644
--- a/apps/desktop/src/settings/DesktopClientSettings.test.ts
+++ b/apps/desktop/src/settings/DesktopClientSettings.test.ts
@@ -26,7 +26,6 @@ const clientSettings: ClientSettings = {
   confirmThreadArchive: true,
   confirmThreadDelete: false,
   confirmThreadUnpin: false,
-  continueThreadsAfterServerUpdate: true,
   contextWindowMeterEnabled: false,
   composerCollapseOnBlur: false,
   composerCollapseOnScroll: true,
@@ -45,6 +44,7 @@ const clientSettings: ClientSettings = {
   fontSizeTerminal: 12,
   fontSmoothing: true,
   glassOpacity: 80,
+  onboardingCompletedAt: null,
   panelAnimationDurationMs: 0,
   planModeEnabled: false,
   proactivePanelsEnabled: true,
@@ -137,6 +137,59 @@ describe("DesktopClientSettings", () => {
     ),
   );
 
+  for (const failure of [
+    { label: "permission", reason: "PermissionDenied" },
+    { label: "I/O", reason: "Unknown" },
+  ] as const) {
+    it.effect(`preserves saved preferences across ${failure.label} read failures and retries`, () =>
+      withClientSettings(
+        Effect.gen(function* () {
+          const environment = yield* DesktopEnvironment.DesktopEnvironment;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const settings = yield* DesktopClientSettings.DesktopClientSettings;
+          const savedSettings = {
+            ...clientSettings,
+            onboardingCompletedAt: "2026-09-05T12:00:00.000Z",
+          };
+          yield* settings.set(savedSettings);
+          const savedContents = yield* fileSystem.readFileString(environment.clientSettingsPath);
+          const cause = PlatformError.systemError({
+            _tag: failure.reason,
+            module: "FileSystem",
+            method: "readFileString",
+            pathOrDescriptor: environment.clientSettingsPath,
+          });
+          let failRead = true;
+          const retryableSettings = yield* DesktopClientSettings.make.pipe(
+            Effect.provideService(
+              FileSystem.FileSystem,
+              FileSystem.FileSystem.of({
+                ...fileSystem,
+                readFileString: (path) =>
+                  Effect.suspend(() =>
+                    failRead ? Effect.fail(cause) : fileSystem.readFileString(path),
+                  ),
+              }),
+            ),
+          );
+
+          const error = yield* retryableSettings.get.pipe(Effect.flip);
+          assert.instanceOf(error, DesktopClientSettings.DesktopClientSettingsReadError);
+          assert.equal(error.operation, "read-file");
+          assert.equal(error.path, environment.clientSettingsPath);
+          assert.strictEqual(error.cause, cause);
+          assert.equal(
+            yield* fileSystem.readFileString(environment.clientSettingsPath),
+            savedContents,
+          );
+
+          failRead = false;
+          assert.deepEqual(yield* retryableSettings.get, Option.some(savedSettings));
+        }),
+      ),
+    );
+  }
+
   it.effect("reports the failed client settings write operation and path", () =>
     withClientSettings(
       Effect.gen(function* () {
@@ -223,17 +276,31 @@ describe("DesktopClientSettings", () => {
     ),
   );
 
-  it.effect("treats malformed client settings documents as absent", () =>
-    withClientSettings(
-      Effect.gen(function* () {
-        const environment = yield* DesktopEnvironment.DesktopEnvironment;
-        const fileSystem = yield* FileSystem.FileSystem;
-        const settings = yield* DesktopClientSettings.DesktopClientSettings;
-        yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
-        yield* fileSystem.writeFileString(environment.clientSettingsPath, "{not-json");
+  for (const document of [
+    { label: "malformed JSON", contents: "{not-json" },
+    { label: "invalid direct settings", contents: '{"fontSizeCode":"large"}' },
+    { label: "invalid legacy settings", contents: '{"settings":{"fontSizeCode":"large"}}' },
+  ]) {
+    it.effect(`reports ${document.label} without treating the settings file as absent`, () =>
+      withClientSettings(
+        Effect.gen(function* () {
+          const environment = yield* DesktopEnvironment.DesktopEnvironment;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const settings = yield* DesktopClientSettings.DesktopClientSettings;
+          yield* fileSystem.makeDirectory(environment.stateDir, { recursive: true });
+          yield* fileSystem.writeFileString(environment.clientSettingsPath, document.contents);
 
-        assert.isTrue(Option.isNone(yield* settings.get));
-      }),
-    ),
-  );
+          const error = yield* settings.get.pipe(Effect.flip);
+          assert.instanceOf(error, DesktopClientSettings.DesktopClientSettingsReadError);
+          assert.equal(error.operation, "decode-document");
+          assert.equal(error.path, environment.clientSettingsPath);
+          assert.instanceOf(error.cause, Schema.SchemaError);
+          assert.equal(
+            yield* fileSystem.readFileString(environment.clientSettingsPath),
+            document.contents,
+          );
+        }),
+      ),
+    );
+  }
 });
diff --git a/apps/desktop/src/settings/DesktopClientSettings.ts b/apps/desktop/src/settings/DesktopClientSettings.ts
index 4ff091e27a27..5eadd27d5454 100644
--- a/apps/desktop/src/settings/DesktopClientSettings.ts
+++ b/apps/desktop/src/settings/DesktopClientSettings.ts
@@ -12,25 +12,33 @@ import * as Ref from "effect/Ref";
 
 import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
 
-const ClientSettingsDocumentSchema = Schema.Struct({
-  settings: ClientSettingsSchema,
-});
-
 const ClientSettingsJson = fromLenientJson(ClientSettingsSchema);
-const LegacyClientSettingsDocumentJson = fromLenientJson(ClientSettingsDocumentSchema);
-const decodeLegacyClientSettingsDocumentJson = Schema.decodeEffect(
-  LegacyClientSettingsDocumentJson,
+const decodeClientSettingsDocument = Schema.decodeEffect(
+  fromLenientJson(Schema.Record(Schema.String, Schema.Unknown)),
 );
-const decodeClientSettingsJsonValue = Schema.decodeEffect(ClientSettingsJson);
-const decodeClientSettingsJson = (raw: string): Effect.Effect<ClientSettings, Schema.SchemaError> =>
-  decodeLegacyClientSettingsDocumentJson(raw).pipe(
-    Effect.map((document) => document.settings),
-    Effect.catchTags({
-      SchemaError: () => decodeClientSettingsJsonValue(raw),
-    }),
+const decodeClientSettingsValue = Schema.decodeUnknownEffect(ClientSettingsSchema);
+const decodeClientSettingsJson = Effect.fnUntraced(function* (raw: string) {
+  const document = yield* decodeClientSettingsDocument(raw);
+  // Select the shape before validation so invalid legacy settings cannot become defaults.
+  return yield* decodeClientSettingsValue(
+    Object.hasOwn(document, "settings") ? document.settings : document,
   );
+});
 const encodeClientSettingsJson = Schema.encodeEffect(ClientSettingsJson);
 
+export class DesktopClientSettingsReadError extends Schema.TaggedErrorClass<DesktopClientSettingsReadError>()(
+  "DesktopClientSettingsReadError",
+  {
+    operation: Schema.Literals(["read-file", "decode-document"]),
+    path: Schema.String,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Desktop client settings read failed during ${this.operation} at ${this.path}.`;
+  }
+}
+
 const DesktopClientSettingsWriteOperation = Schema.Literals([
   "create-temporary-file-name",
   "encode-document",
@@ -55,7 +63,7 @@ export class DesktopClientSettingsWriteError extends Schema.TaggedErrorClass<Des
 export class DesktopClientSettings extends Context.Service<
   DesktopClientSettings,
   {
-    readonly get: Effect.Effect<Option.Option<ClientSettings>>;
+    readonly get: Effect.Effect<Option.Option<ClientSettings>, DesktopClientSettingsReadError>;
     readonly set: (
       settings: ClientSettings,
     ) => Effect.Effect<void, DesktopClientSettingsWriteError>;
@@ -65,7 +73,7 @@ export class DesktopClientSettings extends Context.Service<
 const readClientSettings = (
   fileSystem: FileSystem.FileSystem,
   settingsPath: string,
-): Effect.Effect<Option.Option<ClientSettings>> =>
+): Effect.Effect<Option.Option<ClientSettings>, DesktopClientSettingsReadError> =>
   fileSystem.readFileString(settingsPath).pipe(
     Effect.map(Option.some),
     Effect.catchTags({
@@ -74,7 +82,15 @@ const readClientSettings = (
           ? Effect.succeed(Option.none<string>())
           : Effect.logWarning("Could not read desktop client settings.", cause).pipe(
               Effect.annotateLogs({ settingsPath }),
-              Effect.as(Option.none<string>()),
+              Effect.andThen(
+                Effect.fail(
+                  new DesktopClientSettingsReadError({
+                    operation: "read-file",
+                    path: settingsPath,
+                    cause,
+                  }),
+                ),
+              ),
             ),
     }),
     Effect.flatMap(
@@ -87,7 +103,15 @@ const readClientSettings = (
               SchemaError: (cause) =>
                 Effect.logWarning("Could not decode desktop client settings.", cause).pipe(
                   Effect.annotateLogs({ settingsPath }),
-                  Effect.as(Option.none<ClientSettings>()),
+                  Effect.andThen(
+                    Effect.fail(
+                      new DesktopClientSettingsReadError({
+                        operation: "decode-document",
+                        path: settingsPath,
+                        cause,
+                      }),
+                    ),
+                  ),
                 ),
             }),
           ),
diff --git a/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts b/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts
index 05b1ca144444..348f6cb3843e 100644
--- a/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts
+++ b/apps/desktop/src/settings/DesktopSavedEnvironments.test.ts
@@ -3,6 +3,7 @@ import { assert, describe, it } from "@effect/vitest";
 import { EnvironmentId, type PersistedSavedEnvironmentRecord } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as PlatformError from "effect/PlatformError";
@@ -400,11 +401,12 @@ describe("DesktopSavedEnvironments", () => {
 
   it.effect("reports saved environment filesystem reads separately from document decoding", () =>
     Effect.gen(function* () {
+      const path = yield* Path.Path;
       const baseFileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-saved-environments-test-",
       });
-      const registryPath = `${baseDir}/userdata/saved-environments.json`;
+      const registryPath = path.join(baseDir, "userdata", "saved-environments.json");
       const permissionError = PlatformError.systemError({
         _tag: "PermissionDenied",
         module: "FileSystem",
@@ -433,6 +435,7 @@ describe("DesktopSavedEnvironments", () => {
   it.effect("reports the failed saved environment write operation and path", () =>
     Effect.gen(function* () {
       const baseFileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
       const baseDir = yield* baseFileSystem.makeTempDirectoryScoped({
         prefix: "t3-desktop-saved-environments-test-",
       });
@@ -440,7 +443,7 @@ describe("DesktopSavedEnvironments", () => {
         _tag: "PermissionDenied",
         module: "FileSystem",
         method: "makeDirectory",
-        pathOrDescriptor: `${baseDir}/userdata`,
+        pathOrDescriptor: path.join(baseDir, "userdata"),
       });
       const fileSystemLayer = Layer.succeed(
         FileSystem.FileSystem,
@@ -456,11 +459,11 @@ describe("DesktopSavedEnvironments", () => {
       const error = yield* savedEnvironments.setRegistry([savedRegistryRecord]).pipe(Effect.flip);
       assert.instanceOf(error, DesktopSavedEnvironments.DesktopSavedEnvironmentsWriteError);
       assert.equal(error.operation, "create-directory");
-      assert.equal(error.path, `${baseDir}/userdata`);
+      assert.equal(error.path, path.join(baseDir, "userdata"));
       assert.strictEqual(error.cause, permissionError);
       assert.equal(
         error.message,
-        `Desktop saved-environment write failed during create-directory at ${baseDir}/userdata.`,
+        `Desktop saved-environment write failed during create-directory at ${path.join(baseDir, "userdata")}.`,
       );
       assert.notEqual(error.message, permissionError.message);
     }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
diff --git a/apps/desktop/src/updates/DesktopUpdates.test.ts b/apps/desktop/src/updates/DesktopUpdates.test.ts
index 1978337df3e7..509778521511 100644
--- a/apps/desktop/src/updates/DesktopUpdates.test.ts
+++ b/apps/desktop/src/updates/DesktopUpdates.test.ts
@@ -794,7 +794,6 @@ describe("DesktopUpdates", () => {
         const error = yield* updates.setChannel("nightly").pipe(Effect.flip);
 
         assert.instanceOf(error, DesktopUpdates.DesktopUpdateChannelPersistenceError);
-        assert.isTrue(DesktopUpdates.isDesktopUpdateSetChannelError(error));
         assert.equal(error.channel, "nightly");
         assert.strictEqual(error.cause, settingsFailure);
         assert.strictEqual(error.cause.cause, diskFailure);
diff --git a/apps/desktop/src/updates/DesktopUpdates.ts b/apps/desktop/src/updates/DesktopUpdates.ts
index 20f005f2ab2d..344d135a1024 100644
--- a/apps/desktop/src/updates/DesktopUpdates.ts
+++ b/apps/desktop/src/updates/DesktopUpdates.ts
@@ -155,7 +155,6 @@ export const DesktopUpdateSetChannelError = Schema.Union([
   DesktopUpdateChannelPersistenceError,
 ]);
 export type DesktopUpdateSetChannelError = typeof DesktopUpdateSetChannelError.Type;
-export const isDesktopUpdateSetChannelError = Schema.is(DesktopUpdateSetChannelError);
 
 export class DesktopUpdates extends Context.Service<
   DesktopUpdates,
diff --git a/apps/desktop/src/window/DesktopWindow.test.ts b/apps/desktop/src/window/DesktopWindow.test.ts
index abf6f220eca4..bdd03865c7bf 100644
--- a/apps/desktop/src/window/DesktopWindow.test.ts
+++ b/apps/desktop/src/window/DesktopWindow.test.ts
@@ -280,6 +280,7 @@ function makeTestLayer(input: {
               input.openedExternalUrls?.push(url);
               return true;
             }),
+          openSystemSettings: () => Effect.succeed(true),
           copyText: () => Effect.void,
         } satisfies ElectronShell.ElectronShell["Service"]),
         electronThemeLayer,
@@ -380,6 +381,7 @@ const makeSplashScenario = (createOutcomes: readonly (Electron.BrowserWindow | n
           electronMenuLayer,
           Layer.succeed(ElectronShell.ElectronShell, {
             openExternal: () => Effect.succeed(true),
+            openSystemSettings: () => Effect.succeed(true),
             copyText: () => Effect.void,
           } satisfies ElectronShell.ElectronShell["Service"]),
           electronThemeLayer,
diff --git a/apps/desktop/src/window/QuitHold.test.ts b/apps/desktop/src/window/QuitHold.test.ts
index c4bf2f34b0a1..58809d8eb14d 100644
--- a/apps/desktop/src/window/QuitHold.test.ts
+++ b/apps/desktop/src/window/QuitHold.test.ts
@@ -252,24 +252,31 @@ describe("makeQuitShortcutHandler", () => {
     expect(harness.notifications).toEqual([]);
   });
 
-  it("honors a quick double press when both key releases beat their mode reads", async () => {
-    const resolvers: Array<(mode: QuitConfirmationMode) => void> = [];
-    const harness = makeHarness({
-      getMode: () => new Promise((resolve) => resolvers.push(resolve)),
-    });
-    await harness.send(makeInput({}));
-    await harness.send(makeInput({ type: "keyUp" }));
-    vi.advanceTimersByTime(QUIT_DOUBLE_PRESS_MS - 100);
-    await harness.send(makeInput({}));
-    await harness.send(makeInput({ type: "keyUp" }));
-
-    resolvers[1]?.("double-click");
-    await Promise.resolve();
-    await Promise.resolve();
-
-    expect(harness.quit).toHaveBeenCalledTimes(1);
-    expect(harness.notifications).toEqual([]);
-  });
+  it.each(["direct", "hold", "double-click"] as const)(
+    "quits on a quick second press without waiting for a pending %s mode read",
+    async (mode) => {
+      const resolvers: Array<(mode: QuitConfirmationMode) => void> = [];
+      const harness = makeHarness({
+        getMode: () => new Promise((resolve) => resolvers.push(resolve)),
+      });
+      await harness.send(makeInput({}));
+      await harness.send(makeInput({ type: "keyUp" }));
+      vi.advanceTimersByTime(QUIT_DOUBLE_PRESS_MS - 100);
+      await harness.send(makeInput({}));
+
+      expect(harness.quit).toHaveBeenCalledTimes(1);
+      expect(harness.notifications).toEqual([]);
+
+      await harness.send(makeInput({ type: "keyUp" }));
+
+      resolvers[0]?.(mode);
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(harness.quit).toHaveBeenCalledTimes(1);
+      expect(harness.notifications).toEqual([]);
+    },
+  );
 
   it("discards a stale mode resolution from a superseded press", async () => {
     // Press #1's mode is still pending when the user releases and
@@ -378,6 +385,38 @@ describe("makeQuitShortcutHandler", () => {
     expect(harness.notifications).toEqual([HOLD_DOWN, UP]);
   });
 
+  it("quits on a quick second press in hold mode when the first release is unseen", async () => {
+    const harness = makeHarness();
+    await harness.send(makeInput({}));
+    vi.advanceTimersByTime(QUIT_DOUBLE_PRESS_MS - 100);
+    await harness.send(makeInput({}));
+
+    expect(harness.concealWindow).not.toHaveBeenCalled();
+    expect(harness.quit).toHaveBeenCalledTimes(1);
+    expect(harness.notifications).toEqual([HOLD_DOWN, UP]);
+  });
+
+  it("does not count auto-repeat as a second press", async () => {
+    const harness = makeHarness();
+    await harness.send(makeInput({}));
+    await harness.holdFor(QUIT_DOUBLE_PRESS_MS - 100);
+
+    expect(harness.quit).not.toHaveBeenCalled();
+    expect(harness.notifications).toEqual([HOLD_DOWN]);
+  });
+
+  it("does not count a released tap after another shortcut interrupts it", async () => {
+    const harness = makeHarness();
+    await harness.send(makeInput({}));
+    await harness.send(makeInput({ type: "keyUp" }));
+    await harness.send(makeInput({ key: "c" }));
+    vi.advanceTimersByTime(100);
+    await harness.send(makeInput({}));
+
+    expect(harness.quit).not.toHaveBeenCalled();
+    expect(harness.notifications).toEqual([HOLD_DOWN, UP, HOLD_DOWN]);
+  });
+
   it("cancels the hold when another key interrupts it", async () => {
     const harness = makeHarness();
     await harness.send(makeInput({}));
diff --git a/apps/desktop/src/window/QuitHold.ts b/apps/desktop/src/window/QuitHold.ts
index 4095e3d4354b..a995184ddd70 100644
--- a/apps/desktop/src/window/QuitHold.ts
+++ b/apps/desktop/src/window/QuitHold.ts
@@ -12,7 +12,8 @@ export const QUIT_DOUBLE_PRESS_MS = 500;
 // tap release can go completely unseen and a release-based timer would quit
 // anyway. Once held, quitting waits for Q keyUp or a quiet grace period after
 // repeats stop so they cannot reach the next app. Keyboards with
-// auto-repeat disabled fall back to the application menu Quit action.
+// auto-repeat disabled must use a double press or the application menu Quit action.
+// Supporting holds without repeats requires a native physical key-state check.
 export const QUIT_HOLD_RELEASE_GRACE_MS = 600;
 // A slow repeat rate can exceed the fixed grace. Waiting for two observed
 // cadences keeps the timer behind the next repeat without slowing normal rates.
@@ -52,8 +53,8 @@ export function makeQuitShortcutHandler(
   let lastRepeatAt = 0;
   let repeatCadenceMs = 0;
   // Incremented when a press is superseded or explicitly cancelled. A plain
-  // key release does not invalidate its pending mode read: direct mode and a
-  // completed second press must still be honored after that read settles.
+  // key release does not invalidate its pending mode read: a direct-mode
+  // press must still quit after that read settles.
   let generation = 0;
 
   const clearWatchdog = () => {
@@ -64,9 +65,9 @@ export function makeQuitShortcutHandler(
   };
 
   const release = (cancelPendingMode = true, keepDoublePressHint = false) => {
+    if (cancelPendingMode) generation += 1;
     if (!holding && !notified) return;
     const keepHint = keepDoublePressHint && mode === "double-click" && notified;
-    if (cancelPendingMode) generation += 1;
     holding = false;
     armed = false;
     quitOnRelease = false;
@@ -85,6 +86,7 @@ export function makeQuitShortcutHandler(
   // Dismisses any overlay first so a cancelled quit cannot leave a stale hint.
   const quitNow = () => {
     release();
+    lastPressAt = 0;
     options.quit();
   };
 
@@ -138,13 +140,10 @@ export function makeQuitShortcutHandler(
       // quit shortcut, so it must not cancel an active double-press window.
       if (key === modifierKey && !input.alt && !input.shift) return;
 
-      // Any other key (or an extra modifier) pressed mid-hold breaks the
-      // gesture; without this the hold timer keeps running through the
-      // interruption and the next qualifying repeat would quit early. The
-      // interrupted press also stops counting toward a double press, but only
-      // here, not in release(), which runs mid-restart on an unseen-release
-      // re-press and must not wipe that press's own tap timestamp.
-      if ((holding || notified) && !input.isAutoRepeat) {
+      // Other keys cancel the hold and the first tap, even after release.
+      // Keep this separate from release(), which also runs when a fresh Q
+      // keydown follows a keyUp that macOS did not deliver.
+      if (!input.isAutoRepeat) {
         lastPressAt = 0;
         release();
       }
@@ -171,6 +170,13 @@ export function makeQuitShortcutHandler(
     if (holding || notified) release();
 
     generation += 1;
+    // Every mode accepts two presses. Quit before reading settings so a slow
+    // read cannot delay the second press. Repeats never reach this branch.
+    if (previousPressAt !== 0 && now - previousPressAt <= QUIT_DOUBLE_PRESS_MS) {
+      quitNow();
+      return;
+    }
+
     const pressGeneration = generation;
     holding = true;
     heldSince = now;
@@ -181,13 +187,6 @@ export function makeQuitShortcutHandler(
           quitNow();
           return;
         }
-        // Keep a second press as an escape hatch when macOS misses the events
-        // that would complete a hold.
-        if (previousPressAt !== 0 && now - previousPressAt <= QUIT_DOUBLE_PRESS_MS) {
-          quitNow();
-          return;
-        }
-
         if (resolvedMode === "double-click") {
           const remainingMs = QUIT_DOUBLE_PRESS_MS - (Date.now() - now);
           if (remainingMs <= 0) {
diff --git a/apps/desktop/vite.config.ts b/apps/desktop/vite.config.ts
index ce74cf58e0a3..294a02030a83 100644
--- a/apps/desktop/vite.config.ts
+++ b/apps/desktop/vite.config.ts
@@ -1,3 +1,4 @@
+import "vite-plus/test/config";
 import { defineConfig } from "vite-plus";
 
 import { loadRepoEnv } from "../../scripts/lib/public-config.ts";
@@ -83,4 +84,10 @@ export default defineConfig({
       entry: ["src/preview-pip-preload.ts"],
     },
   ],
+  test: {
+    // The Windows lane runs workspace suites concurrently; filesystem-heavy
+    // desktop integration tests can exceed Vitest's 5 second default there.
+    testTimeout: 15_000,
+    setupFiles: ["../../packages/shared/src/testing/longTempDir.ts"],
+  },
 });
diff --git a/apps/marketing/package.json b/apps/marketing/package.json
index 912faf88164d..78c121d14fe2 100644
--- a/apps/marketing/package.json
+++ b/apps/marketing/package.json
@@ -11,7 +11,8 @@
   },
   "dependencies": {
     "@t3tools/shared": "workspace:*",
-    "astro": "^7.0.3"
+    "astro": "^7.0.3",
+    "sharp": "0.34.5"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.7",
diff --git a/apps/marketing/public/fonts/dm-sans-OFL.txt b/apps/marketing/public/fonts/dm-sans-OFL.txt
new file mode 100644
index 000000000000..a0eedfbf0df0
--- /dev/null
+++ b/apps/marketing/public/fonts/dm-sans-OFL.txt
@@ -0,0 +1,93 @@
+Copyright 2014 The DM Sans Project Authors (https://github.com/googlefonts/dm-fonts)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/apps/marketing/public/fonts/jetbrains-mono-OFL.txt b/apps/marketing/public/fonts/jetbrains-mono-OFL.txt
new file mode 100644
index 000000000000..821a3dac22af
--- /dev/null
+++ b/apps/marketing/public/fonts/jetbrains-mono-OFL.txt
@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/apps/marketing/public/app-desktop.webp b/apps/marketing/src/assets/app-desktop.webp
similarity index 100%
rename from apps/marketing/public/app-desktop.webp
rename to apps/marketing/src/assets/app-desktop.webp
diff --git a/apps/marketing/src/assets/fonts/dm-sans-latin-ext.woff2 b/apps/marketing/src/assets/fonts/dm-sans-latin-ext.woff2
new file mode 100644
index 000000000000..6e84cba1949c
Binary files /dev/null and b/apps/marketing/src/assets/fonts/dm-sans-latin-ext.woff2 differ
diff --git a/apps/marketing/src/assets/fonts/dm-sans-latin.woff2 b/apps/marketing/src/assets/fonts/dm-sans-latin.woff2
new file mode 100644
index 000000000000..c75f7bf1b465
Binary files /dev/null and b/apps/marketing/src/assets/fonts/dm-sans-latin.woff2 differ
diff --git a/apps/marketing/src/assets/fonts/jetbrains-mono-cyrillic-ext.woff2 b/apps/marketing/src/assets/fonts/jetbrains-mono-cyrillic-ext.woff2
new file mode 100644
index 000000000000..289de93149ab
Binary files /dev/null and b/apps/marketing/src/assets/fonts/jetbrains-mono-cyrillic-ext.woff2 differ
diff --git a/apps/marketing/src/assets/fonts/jetbrains-mono-cyrillic.woff2 b/apps/marketing/src/assets/fonts/jetbrains-mono-cyrillic.woff2
new file mode 100644
index 000000000000..de39acbc4069
Binary files /dev/null and b/apps/marketing/src/assets/fonts/jetbrains-mono-cyrillic.woff2 differ
diff --git a/apps/marketing/src/assets/fonts/jetbrains-mono-greek.woff2 b/apps/marketing/src/assets/fonts/jetbrains-mono-greek.woff2
new file mode 100644
index 000000000000..a53d52d6d02c
Binary files /dev/null and b/apps/marketing/src/assets/fonts/jetbrains-mono-greek.woff2 differ
diff --git a/apps/marketing/src/assets/fonts/jetbrains-mono-latin-ext.woff2 b/apps/marketing/src/assets/fonts/jetbrains-mono-latin-ext.woff2
new file mode 100644
index 000000000000..82f96681c076
Binary files /dev/null and b/apps/marketing/src/assets/fonts/jetbrains-mono-latin-ext.woff2 differ
diff --git a/apps/marketing/src/assets/fonts/jetbrains-mono-latin.woff2 b/apps/marketing/src/assets/fonts/jetbrains-mono-latin.woff2
new file mode 100644
index 000000000000..4d09cda4a4c3
Binary files /dev/null and b/apps/marketing/src/assets/fonts/jetbrains-mono-latin.woff2 differ
diff --git a/apps/marketing/src/assets/fonts/jetbrains-mono-vietnamese.woff2 b/apps/marketing/src/assets/fonts/jetbrains-mono-vietnamese.woff2
new file mode 100644
index 000000000000..e38f5538f84e
Binary files /dev/null and b/apps/marketing/src/assets/fonts/jetbrains-mono-vietnamese.woff2 differ
diff --git a/apps/marketing/public/icon.webp b/apps/marketing/src/assets/icon.webp
similarity index 100%
rename from apps/marketing/public/icon.webp
rename to apps/marketing/src/assets/icon.webp
diff --git a/apps/marketing/src/layouts/Layout.astro b/apps/marketing/src/layouts/Layout.astro
index 686b555fd4c0..ca5ea15f61de 100644
--- a/apps/marketing/src/layouts/Layout.astro
+++ b/apps/marketing/src/layouts/Layout.astro
@@ -1,4 +1,8 @@
 ---
+import { Image } from "astro:assets";
+import appIcon from "../assets/icon.webp";
+import dmSansLatinUrl from "../assets/fonts/dm-sans-latin.woff2?url";
+import "../styles/fonts.css";
 import {
   ANDROID_PLAY_STORE_URL,
   GITHUB_REPOSITORY_URL,
@@ -24,11 +28,12 @@ const {
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="description" content={description} />
-    <link rel="preconnect" href="https://fonts.googleapis.com" />
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link
-      href="https://fonts.googleapis.com/css2?family=DM+Sans:opsz,wght@9..40,400;9..40,500;9..40,600&family=JetBrains+Mono:wght@400;500&display=swap"
-      rel="stylesheet"
+      rel="preload"
+      href={dmSansLatinUrl}
+      as="font"
+      type="font/woff2"
+      crossorigin="anonymous"
     />
     <link rel="icon" href="/favicon.ico" sizes="48x48" />
     <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32" />
@@ -67,7 +72,17 @@ const {
       <footer class="footer">
         <div class="footer-inner">
           <div class="footer-brand">
-            <img src="/icon.webp" alt="" />
+            <Image
+              src={appIcon}
+              alt=""
+              width={20}
+              height={20}
+              densities={[1, 2, 3]}
+              format="webp"
+              quality={90}
+              loading="lazy"
+              decoding="async"
+            />
             <span>&copy; {new Date().getFullYear()} T3 Tools Inc · MIT licensed</span>
           </div>
           <div class="footer-links">
diff --git a/apps/marketing/src/lib/homeMotion.test.ts b/apps/marketing/src/lib/homeMotion.test.ts
new file mode 100644
index 000000000000..42f7775a0157
--- /dev/null
+++ b/apps/marketing/src/lib/homeMotion.test.ts
@@ -0,0 +1,226 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { startHomeMotion } from "./homeMotion";
+
+class ElementStub extends EventTarget {
+  properties = new Map<string, string>();
+  style = { setProperty: (name: string, value: string) => this.properties.set(name, value) };
+  children: ElementStub[] = [];
+  scrollLeft = 0;
+  scrollWidth = 1_200;
+  clientWidth = 400;
+  matches = () => false;
+  contains = (target: EventTarget | null) =>
+    target === this || (target instanceof ElementStub && this.children.includes(target));
+  querySelectorAll = () => this.children;
+  getBoundingClientRect = vi.fn(() => ({ left: 0, top: 0, width: 400, height: 600 }));
+  scrollTo = vi.fn((options: ScrollToOptions) => {
+    this.scrollLeft = options.left ?? this.scrollLeft;
+  });
+}
+
+let observers: ObserverStub[] = [];
+class ObserverStub {
+  constructor(private readonly callback: IntersectionObserverCallback) {
+    observers.push(this);
+  }
+  observe = vi.fn();
+  disconnect = vi.fn();
+  report(target: ElementStub, isIntersecting: boolean) {
+    this.callback(
+      [{ target, isIntersecting } as unknown as IntersectionObserverEntry],
+      this as unknown as IntersectionObserver,
+    );
+  }
+}
+
+let page = Object.assign(new EventTarget(), { visibilityState: "visible", activeElement: null });
+let viewport = new EventTarget();
+let reduced = Object.assign(new EventTarget(), { matches: false });
+let fine = Object.assign(new EventTarget(), { matches: true });
+let frames = new Map<number, FrameRequestCallback>();
+let dispose: (() => void) | undefined;
+
+beforeEach(() => {
+  vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+  observers = [];
+  frames = new Map();
+  page = Object.assign(new EventTarget(), { visibilityState: "visible", activeElement: null });
+  viewport = new EventTarget();
+  reduced = Object.assign(new EventTarget(), { matches: false });
+  fine = Object.assign(new EventTarget(), { matches: true });
+  vi.stubGlobal("document", page);
+  vi.stubGlobal(
+    "window",
+    Object.assign(viewport, {
+      matchMedia: (query: string) => (query.includes("reduced-motion") ? reduced : fine),
+    }),
+  );
+  vi.stubGlobal("Node", ElementStub);
+  vi.stubGlobal("IntersectionObserver", ObserverStub);
+  let frameId = 0;
+  vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+    frames.set(++frameId, callback);
+    return frameId;
+  });
+  vi.stubGlobal("cancelAnimationFrame", (id: number) => frames.delete(id));
+});
+
+afterEach(() => {
+  dispose?.();
+  dispose = undefined;
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+function fixture() {
+  const hero = new ElementStub();
+  const field = new ElementStub();
+  const mark = new ElementStub();
+  const otherMark = new ElementStub();
+  field.children = [mark, otherMark];
+  const endorsements = new ElementStub();
+  const caret = new ElementStub();
+  dispose = startHomeMotion({ hero, field, endorsements, caret } as unknown as Parameters<
+    typeof startHomeMotion
+  >[0]);
+  return { hero, field, mark, otherMark, endorsements, caret, observer: observers[0]! };
+}
+
+function movePointer(hero: ElementStub, x = 400, y = 600) {
+  hero.dispatchEvent(Object.assign(new Event("pointermove"), { clientX: x, clientY: y }));
+}
+
+describe("homepage motion", () => {
+  it("gates each mark and caret and batches pointer input into one frame", () => {
+    const { hero, field, mark, otherMark, caret, observer } = fixture();
+    expect(mark.properties.get("--home-motion-state")).toBe("paused");
+    observer.report(mark, true);
+    observer.report(caret, true);
+    expect(mark.properties.get("--home-motion-state")).toBe("running");
+    expect(otherMark.properties.get("--home-motion-state")).toBe("paused");
+    expect(caret.properties.get("--home-motion-state")).toBe("running");
+
+    movePointer(hero, 100, 100);
+    movePointer(hero);
+    expect(frames.size).toBe(1);
+    expect(hero.getBoundingClientRect).not.toHaveBeenCalled();
+    const [id, callback] = [...frames][0]!;
+    frames.delete(id);
+    callback(0);
+    expect(field.properties.get("--px")).toBe("18.0px");
+    expect(field.properties.get("--py")).toBe("14.0px");
+
+    movePointer(hero);
+    page.visibilityState = "hidden";
+    page.dispatchEvent(new Event("visibilitychange"));
+    expect(frames.size).toBe(0);
+    expect(field.properties.get("--px")).toBe("0px");
+    expect(mark.properties.get("--home-motion-state")).toBe("paused");
+    expect(caret.properties.get("--home-motion-state")).toBe("paused");
+    page.visibilityState = "visible";
+    page.dispatchEvent(new Event("visibilitychange"));
+    reduced.matches = true;
+    reduced.dispatchEvent(new Event("change"));
+    movePointer(hero);
+    expect(frames.size).toBe(0);
+    expect(mark.properties.get("--home-motion-state")).toBe("paused");
+    reduced.matches = false;
+    fine.matches = false;
+    reduced.dispatchEvent(new Event("change"));
+    movePointer(hero);
+    expect(frames.size).toBe(0);
+    expect(mark.properties.get("--home-motion-state")).toBe("running");
+  });
+
+  it("pages every eight seconds, reverses at the end, and has no timer without overflow", () => {
+    const { endorsements, observer } = fixture();
+    expect(vi.getTimerCount()).toBe(0);
+    observer.report(endorsements, true);
+    vi.advanceTimersByTime(7_999);
+    expect(endorsements.scrollTo).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(16_001);
+    expect(endorsements.scrollTo.mock.calls.map(([options]) => options.left)).toEqual([
+      400, 800, 400,
+    ]);
+    expect(
+      endorsements.scrollTo.mock.calls.every(([options]) => options.behavior === "smooth"),
+    ).toBe(true);
+
+    endorsements.clientWidth = endorsements.scrollWidth;
+    viewport.dispatchEvent(new Event("resize"));
+    expect(vi.getTimerCount()).toBe(0);
+    expect(endorsements.scrollTo).toHaveBeenLastCalledWith({ left: 400, behavior: "instant" });
+    endorsements.clientWidth = 400;
+    viewport.dispatchEvent(new Event("resize"));
+    expect(vi.getTimerCount()).toBe(1);
+  });
+
+  it("pauses paging for hover, focus, hidden content, and reduced motion", () => {
+    const { endorsements, observer } = fixture();
+    observer.report(endorsements, true);
+    const changeVisibility = (visible: boolean) => {
+      page.visibilityState = visible ? "visible" : "hidden";
+      page.dispatchEvent(new Event("visibilitychange"));
+    };
+    const changeMotion = (matches: boolean) => {
+      reduced.matches = matches;
+      reduced.dispatchEvent(new Event("change"));
+    };
+    const pauses = [
+      [
+        () => endorsements.dispatchEvent(new Event("pointerenter")),
+        () => endorsements.dispatchEvent(new Event("pointerleave")),
+      ],
+      [
+        () => endorsements.dispatchEvent(new Event("focusin")),
+        () =>
+          endorsements.dispatchEvent(Object.assign(new Event("focusout"), { relatedTarget: null })),
+      ],
+      [() => changeVisibility(false), () => changeVisibility(true)],
+      [() => observer.report(endorsements, false), () => observer.report(endorsements, true)],
+      [() => changeMotion(true), () => changeMotion(false)],
+    ] as const;
+    for (const [pause, resume] of pauses) {
+      pause();
+      expect(vi.getTimerCount()).toBe(0);
+      vi.advanceTimersByTime(16_000);
+      resume();
+      expect(vi.getTimerCount()).toBe(1);
+    }
+    expect(endorsements.scrollTo).not.toHaveBeenCalled();
+    vi.advanceTimersByTime(8_000);
+    expect(endorsements.scrollTo).toHaveBeenCalledWith({ left: 400, behavior: "smooth" });
+    endorsements.dispatchEvent(new Event("pointerenter"));
+    expect(endorsements.scrollTo).toHaveBeenLastCalledWith({ left: 400, behavior: "instant" });
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it.each(["wheel", "pointerdown", "keydown"])("hands control to the user after %s", (event) => {
+    const { endorsements, observer } = fixture();
+    observer.report(endorsements, true);
+    endorsements.dispatchEvent(new Event(event));
+    observer.report(endorsements, false);
+    observer.report(endorsements, true);
+    endorsements.dispatchEvent(new Event("pointerleave"));
+    viewport.dispatchEvent(new Event("resize"));
+    vi.advanceTimersByTime(60_000);
+    expect(vi.getTimerCount()).toBe(0);
+    expect(endorsements.scrollTo).not.toHaveBeenCalled();
+  });
+
+  it("cancels pending work and ignores events after cleanup", () => {
+    const { hero, mark, endorsements, observer } = fixture();
+    observer.report(mark, true);
+    observer.report(endorsements, true);
+    movePointer(hero);
+    dispose?.();
+    observer.report(mark, true);
+    movePointer(hero);
+    reduced.dispatchEvent(new Event("change"));
+    expect(observer.disconnect).toHaveBeenCalledTimes(1);
+    expect(frames.size).toBe(0);
+    expect(vi.getTimerCount()).toBe(0);
+    expect(mark.properties.get("--home-motion-state")).toBe("paused");
+  });
+});
diff --git a/apps/marketing/src/lib/homeMotion.ts b/apps/marketing/src/lib/homeMotion.ts
new file mode 100644
index 000000000000..5322eae4406d
--- /dev/null
+++ b/apps/marketing/src/lib/homeMotion.ts
@@ -0,0 +1,176 @@
+/** Runs homepage motion only while its content is visible. Manual scrolling stops paging. */
+export function startHomeMotion({
+  hero,
+  field,
+  endorsements,
+  caret,
+}: {
+  hero: HTMLElement;
+  field: HTMLElement;
+  endorsements: HTMLElement;
+  caret: HTMLElement;
+}) {
+  if (typeof IntersectionObserver === "undefined") return () => {};
+
+  const marks = Array.from(field.querySelectorAll<HTMLElement>(".hero-float-mark"));
+  const visible = new Set<Element>();
+  const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+  const finePointer = window.matchMedia("(pointer: fine)");
+  const events = new AbortController();
+  const eventOptions = { signal: events.signal };
+  let disposed = false;
+  let hovered = endorsements.matches(":hover");
+  let focused = endorsements.contains(document.activeElement);
+  let userControlled = false;
+  let direction = 1;
+  let automaticScroll = false;
+  let pageTimer: ReturnType<typeof setTimeout> | undefined;
+  let pointerFrame: number | undefined;
+  let pointer: { x: number; y: number } | null = null;
+
+  const canMove = (element: Element) =>
+    !disposed &&
+    visible.has(element) &&
+    document.visibilityState === "visible" &&
+    !reducedMotion.matches;
+  const canParallax = () => finePointer.matches && marks.some(canMove);
+  const canPage = () =>
+    canMove(endorsements) &&
+    !hovered &&
+    !focused &&
+    !userControlled &&
+    endorsements.scrollWidth > endorsements.clientWidth;
+
+  function resetPointer() {
+    if (pointerFrame !== undefined) cancelAnimationFrame(pointerFrame);
+    pointerFrame = undefined;
+    pointer = null;
+    field.style.setProperty("--px", "0px");
+    field.style.setProperty("--py", "0px");
+  }
+
+  function updatePaging() {
+    if (canPage()) {
+      pageTimer ??= setTimeout(advancePage, 8_000);
+      return;
+    }
+    if (pageTimer !== undefined) clearTimeout(pageTimer);
+    pageTimer = undefined;
+    if (automaticScroll) {
+      automaticScroll = false;
+      endorsements.scrollTo({ left: endorsements.scrollLeft, behavior: "instant" });
+    }
+  }
+
+  function advancePage() {
+    pageTimer = undefined;
+    if (!canPage()) return;
+    const end = endorsements.scrollWidth - endorsements.clientWidth;
+    const current = endorsements.scrollLeft;
+    if (current >= end - 1) direction = -1;
+    else if (current <= 1) direction = 1;
+    automaticScroll = true;
+    endorsements.scrollTo({
+      left: Math.max(0, Math.min(end, current + direction * endorsements.clientWidth)),
+      behavior: "smooth",
+    });
+    updatePaging();
+  }
+
+  function update() {
+    for (const mark of marks) {
+      mark.style.setProperty("--home-motion-state", canMove(mark) ? "running" : "paused");
+    }
+    caret.style.setProperty("--home-motion-state", canMove(caret) ? "running" : "paused");
+    const parallax = canParallax();
+    field.style.setProperty("--parallax-duration", parallax ? "0.7s" : "0s");
+    if (!parallax) resetPointer();
+    updatePaging();
+  }
+
+  const observer = new IntersectionObserver((entries) => {
+    if (disposed) return;
+    for (const entry of entries) {
+      if (entry.isIntersecting) visible.add(entry.target);
+      else visible.delete(entry.target);
+    }
+    update();
+  });
+  for (const element of [...marks, endorsements, caret]) observer.observe(element);
+
+  hero.addEventListener(
+    "pointermove",
+    (event) => {
+      if (!canParallax()) return;
+      pointer = { x: event.clientX, y: event.clientY };
+      pointerFrame ??= requestAnimationFrame(() => {
+        pointerFrame = undefined;
+        if (!pointer || !canParallax()) return;
+        const bounds = hero.getBoundingClientRect();
+        if (bounds.width === 0 || bounds.height === 0) return;
+        field.style.setProperty(
+          "--px",
+          `${(((pointer.x - bounds.left) / bounds.width - 0.5) * 36).toFixed(1)}px`,
+        );
+        field.style.setProperty(
+          "--py",
+          `${(((pointer.y - bounds.top) / bounds.height - 0.5) * 28).toFixed(1)}px`,
+        );
+      });
+    },
+    eventOptions,
+  );
+  hero.addEventListener("pointerleave", resetPointer, eventOptions);
+  endorsements.addEventListener(
+    "pointerenter",
+    () => {
+      hovered = true;
+      updatePaging();
+    },
+    eventOptions,
+  );
+  endorsements.addEventListener(
+    "pointerleave",
+    () => {
+      hovered = false;
+      updatePaging();
+    },
+    eventOptions,
+  );
+  endorsements.addEventListener(
+    "focusin",
+    () => {
+      focused = true;
+      updatePaging();
+    },
+    eventOptions,
+  );
+  endorsements.addEventListener(
+    "focusout",
+    (event) => {
+      focused = event.relatedTarget instanceof Node && endorsements.contains(event.relatedTarget);
+      updatePaging();
+    },
+    eventOptions,
+  );
+  const takeControl = () => {
+    userControlled = true;
+    updatePaging();
+  };
+  endorsements.addEventListener("wheel", takeControl, { ...eventOptions, passive: true });
+  endorsements.addEventListener("pointerdown", takeControl, eventOptions);
+  endorsements.addEventListener("keydown", takeControl, eventOptions);
+  document.addEventListener("visibilitychange", update, eventOptions);
+  window.addEventListener("resize", update, eventOptions);
+  reducedMotion.addEventListener("change", update, eventOptions);
+  finePointer.addEventListener("change", update, eventOptions);
+  update();
+
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    events.abort();
+    observer.disconnect();
+    update();
+  };
+}
diff --git a/apps/marketing/src/pages/index.astro b/apps/marketing/src/pages/index.astro
index 6b45f1a1bbc3..723ad4d4324b 100644
--- a/apps/marketing/src/pages/index.astro
+++ b/apps/marketing/src/pages/index.astro
@@ -1,4 +1,6 @@
 ---
+import { getImage } from "astro:assets";
+import desktopScreenshot from "../assets/app-desktop.webp";
 import Layout from "../layouts/Layout.astro";
 import {
   ANDROID_PLAY_STORE_URL,
@@ -8,16 +10,13 @@ import {
 } from "../lib/site";
 import { tweets } from "../lib/tweets";
 
-const desktopEndorsementRows = [
-  tweets.filter((_, index) => index % 2 === 0),
-  tweets.filter((_, index) => index % 2 === 1),
-];
+const screenshot = await getImage({
+  src: desktopScreenshot,
+  widths: [864, 1180, 1728, 2360],
+  format: "webp",
+  quality: 90,
+});
 
-const mobileEndorsementRows = [
-  tweets.filter((_, index) => index % 3 === 0),
-  tweets.filter((_, index) => index % 3 === 1),
-  tweets.filter((_, index) => index % 3 === 2),
-];
 ---
 
 <Layout>
@@ -80,14 +79,23 @@ const mobileEndorsementRows = [
       <div data-rise style="--d:520ms">
         <div class="hero-preview">
           <figure class="hero-screenshot-frame">
-            <img
-              src="/app-desktop.webp"
-              alt="T3 Code with a settled thread beside its pull request diff"
-              width="2880"
-              height="1800"
-              loading="eager"
-              decoding="async"
-            />
+            <picture>
+              <!-- Match the hidden mobile layout without requesting a screenshot. -->
+              <source
+                media="(max-width: 820px)"
+                srcset="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
+              />
+              <img
+                src={desktopScreenshot.src}
+                srcset={`${screenshot.srcSet.attribute}, ${desktopScreenshot.src} ${desktopScreenshot.width}w`}
+                sizes="(max-width: 960px) min(864px, calc(100vw - 20px)), min(1180px, calc(100vw - 60px))"
+                alt="T3 Code with a settled thread beside its pull request diff"
+                width={desktopScreenshot.width}
+                height={desktopScreenshot.height}
+                loading="eager"
+                decoding="async"
+              />
+            </picture>
           </figure>
         </div>
       </div>
@@ -103,80 +111,29 @@ const mobileEndorsementRows = [
       </div>
     </div>
 
-    <div class="endorsement-carousel endorsement-carousel--desktop" aria-label="Developer endorsements">
-        {
-          desktopEndorsementRows.map((row, rowIndex) => (
-            <div class:list={["endorsement-row", rowIndex === 1 && "is-reverse"]}>
-              <div class="endorsement-track">
-                {[0, 1].map((groupIndex) => (
-                  <div class="endorsement-track-group" aria-hidden={groupIndex === 1 ? "true" : undefined}>
-                    {row.map((tweet) => (
-                      <a
-                        class="endorsement-card"
-                        href={tweet.link}
-                        target="_blank"
-                        rel="noopener noreferrer"
-                        aria-label={`Read ${tweet.handle}'s post on X`}
-                        tabindex={groupIndex === 1 ? "-1" : undefined}
-                      >
-                        <div class="endorsement-author">
-                          <img
-                            src={`/pfps/${tweet.handle}.webp`}
-                            alt=""
-                            width="28"
-                            height="28"
-                            loading="lazy"
-                            decoding="async"
-                          />
-                          <div class="endorsement-handle">@{tweet.handle}</div>
-                        </div>
-                        <p>{tweet.excerpt ?? tweet.content}</p>
-                      </a>
-                    ))}
-                  </div>
-                ))}
-              </div>
-            </div>
-          ))
-        }
-    </div>
-
-    <div class="endorsement-carousel endorsement-carousel--mobile" aria-label="Developer endorsements">
-        {
-          mobileEndorsementRows.map((row, rowIndex) => (
-            <div class:list={["endorsement-row", rowIndex === 1 && "is-reverse"]}>
-              <div class="endorsement-track">
-                {[0, 1].map((groupIndex) => (
-                  <div class="endorsement-track-group" aria-hidden={groupIndex === 1 ? "true" : undefined}>
-                    {row.map((tweet) => (
-                      <a
-                        class="endorsement-card"
-                        href={tweet.link}
-                        target="_blank"
-                        rel="noopener noreferrer"
-                        aria-label={`Read ${tweet.handle}'s post on X`}
-                        tabindex={groupIndex === 1 ? "-1" : undefined}
-                      >
-                        <div class="endorsement-author">
-                          <img
-                            src={`/pfps/${tweet.handle}.webp`}
-                            alt=""
-                            width="28"
-                            height="28"
-                            loading="lazy"
-                            decoding="async"
-                          />
-                          <div class="endorsement-handle">@{tweet.handle}</div>
-                        </div>
-                        <p>{tweet.excerpt ?? tweet.content}</p>
-                      </a>
-                    ))}
-                  </div>
-                ))}
-              </div>
-            </div>
-          ))
-        }
+    <div class="endorsement-carousel" role="region" aria-label="Developer endorsements" tabindex="0">
+      {tweets.map((tweet) => (
+        <a
+          class="endorsement-card"
+          href={tweet.link}
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label={`Read ${tweet.handle}'s post on X`}
+        >
+          <div class="endorsement-author">
+            <img
+              src={`/pfps/${tweet.handle}.webp`}
+              alt=""
+              width="28"
+              height="28"
+              loading="lazy"
+              decoding="async"
+            />
+            <div class="endorsement-handle">@{tweet.handle}</div>
+          </div>
+          <p>{tweet.excerpt ?? tweet.content}</p>
+        </a>
+      ))}
     </div>
   </section>
 
@@ -398,6 +355,7 @@ const mobileEndorsementRows = [
 
 <script>
   import { fetchLatestRelease, RELEASES_URL, type ReleaseAsset } from "../lib/releases";
+  import { startHomeMotion } from "../lib/homeMotion";
 
   type Platform = { os: "mac" | "win" | "linux"; label: string };
 
@@ -463,26 +421,12 @@ const mobileEndorsementRows = [
 
   init();
 
-  // Marks lean a few pixels toward the pointer, each by its own depth.
   const hero = document.querySelector<HTMLElement>(".hero");
   const field = document.querySelector<HTMLElement>(".hero-float");
-  const fine = window.matchMedia("(pointer: fine) and (prefers-reduced-motion: no-preference)").matches;
-  if (hero && field && fine) {
-    let raf = 0;
-    let nx = 0;
-    let ny = 0;
-    const apply = () => {
-      raf = 0;
-      field.style.setProperty("--px", `${(nx * 18).toFixed(1)}px`);
-      field.style.setProperty("--py", `${(ny * 14).toFixed(1)}px`);
-    };
-    hero.addEventListener("pointermove", (e) => {
-      const r = hero.getBoundingClientRect();
-      nx = ((e.clientX - r.left) / r.width - 0.5) * 2;
-      ny = ((e.clientY - r.top) / r.height - 0.5) * 2;
-      if (!raf) raf = requestAnimationFrame(apply);
-    });
-    hero.addEventListener("pointerleave", () => { nx = 0; ny = 0; if (!raf) raf = requestAnimationFrame(apply); });
+  const endorsements = document.querySelector<HTMLElement>(".endorsement-carousel");
+  const caret = document.querySelector<HTMLElement>(".caret");
+  if (hero && field && endorsements && caret) {
+    startHomeMotion({ hero, field, endorsements, caret });
   }
 </script>
 
@@ -655,11 +599,7 @@ const mobileEndorsementRows = [
   :global([data-platform="linux"]) .dl-icon--linux { display: block; }
   :global(html:not([data-platform])) .dl-icon--apple { display: block; }
 
-  /* Floating harness marks. Six points on an ellipse around the hero copy:
-     two small at the top, two high and wide, two low and close. Symmetric,
-     and none of them touch the screenshot. Each mark flies in from its own
-     side on load, then drifts on its own period, and the whole set leans a
-     few pixels toward the pointer. */
+  /* Marks enter once, then drift while visible and lean toward the pointer. */
   .hero-float {
     position: absolute;
     inset: 0;
@@ -677,7 +617,7 @@ const mobileEndorsementRows = [
     height: var(--s);
     margin-left: calc(var(--s) / -2);
     translate: calc(var(--px) * var(--depth)) calc(var(--py) * var(--depth));
-    transition: translate 0.7s cubic-bezier(0.2, 0.7, 0.2, 1);
+    transition: translate var(--parallax-duration, 0s) cubic-bezier(0.2, 0.7, 0.2, 1);
   }
 
   .hero-float-card {
@@ -694,6 +634,7 @@ const mobileEndorsementRows = [
     animation:
       mark-in 1s cubic-bezier(0.2, 0.7, 0.2, 1) var(--d) both,
       mark-drift var(--dur) ease-in-out calc(var(--d) + 1s) infinite;
+    animation-play-state: running, var(--home-motion-state, paused);
   }
 
   .hero-float-card img {
@@ -717,16 +658,16 @@ const mobileEndorsementRows = [
     50% { transform: translate(var(--dx), var(--dy)) rotate(calc(var(--rot) + var(--wob))); }
   }
 
-  .hf-opencode    { --x: max(-300px, -19vw); --y: 20px;  --s: 64px; --rot: 6deg;  --depth: 0.6; --d: 620ms; --dur: 8.5s;  --dx: 2px;  --dy: -8px;  --wob: 3deg;  --fx: -40px;  --fy: -80px; }
-  .hf-antigravity { --x: min(300px, 19vw);   --y: 20px;  --s: 64px; --rot: -5deg; --depth: 0.6; --d: 580ms; --dur: 9.8s;  --dx: -2px; --dy: -9px;  --wob: -3deg; --fx: 40px;   --fy: -80px; }
-  .hf-claude   { --x: max(-560px, -38vw);  --y: 128px; --s: 96px; --rot: -8deg; --depth: 1.2; --d: 380ms; --dur: 10.5s; --dx: 4px;  --dy: -12px; --wob: -2deg; --fx: -160px; --fy: -40px; --tint: rgba(217, 119, 87, 0.22); }
-  .hf-codex    { --x: min(560px, 38vw);    --y: 128px; --s: 96px; --rot: 7deg;  --depth: 1.2; --d: 460ms; --dur: 9.2s;  --dx: -4px; --dy: -10px; --wob: 2deg;  --fx: 160px;  --fy: -40px; }
-  .hf-grok     { --x: max(-440px, -30vw);  --y: 440px; --s: 80px; --rot: 4deg;  --depth: 0.9; --d: 540ms; --dur: 11.5s; --dx: 3px;  --dy: -9px;  --wob: -3deg; --fx: -120px; --fy: 80px; }
-  .hf-cursor   { --x: min(440px, 30vw);    --y: 440px; --s: 80px; --rot: -5deg; --depth: 0.9; --d: 700ms; --dur: 7.8s;  --dx: -3px; --dy: -11px; --wob: 3deg;  --fx: 120px;  --fy: 80px; }
+  .hf-opencode    { --x: max(-300px, -19vw); --y: 20px; --s: 64px; --rot: 6deg; --depth: 0.6; --d: 620ms; --dur: 8.5s; --dx: 2px; --dy: -8px; --wob: 3deg; --fx: -40px; --fy: -80px; }
+  .hf-antigravity { --x: min(300px, 19vw); --y: 20px; --s: 64px; --rot: -5deg; --depth: 0.6; --d: 580ms; --dur: 9.8s; --dx: -2px; --dy: -9px; --wob: -3deg; --fx: 40px; --fy: -80px; }
+  .hf-claude   { --x: max(-560px, -38vw); --y: 128px; --s: 96px; --rot: -8deg; --depth: 1.2; --d: 380ms; --dur: 10.5s; --dx: 4px; --dy: -12px; --wob: -2deg; --fx: -160px; --fy: -40px; --tint: rgba(217, 119, 87, 0.22); }
+  .hf-codex    { --x: min(560px, 38vw); --y: 128px; --s: 96px; --rot: 7deg; --depth: 1.2; --d: 460ms; --dur: 9.2s; --dx: -4px; --dy: -10px; --wob: 2deg; --fx: 160px; --fy: -40px; }
+  .hf-grok     { --x: max(-440px, -30vw); --y: 440px; --s: 80px; --rot: 4deg; --depth: 0.9; --d: 540ms; --dur: 11.5s; --dx: 3px; --dy: -9px; --wob: -3deg; --fx: -120px; --fy: 80px; }
+  .hf-cursor   { --x: min(440px, 30vw); --y: 440px; --s: 80px; --rot: -5deg; --depth: 0.9; --d: 700ms; --dur: 7.8s; --dx: -3px; --dy: -11px; --wob: 3deg; --fx: 120px; --fy: 80px; }
 
   @media (prefers-reduced-motion: reduce) {
     .hero-float-card { animation: none; transform: rotate(var(--rot)); }
-    .hero-float-mark { transition: none; }
+    .hero-float-mark { translate: none; transition: none; }
   }
 
   @media (max-width: 1180px) {
@@ -749,12 +690,12 @@ const mobileEndorsementRows = [
     }
 
     /* Four above the headline, two beside the CTA. Keeps the copy clear. */
-    .hf-claude      { --x: -37vw; --y: 44px;  --s: 64px; --rot: -10deg; }
-    .hf-opencode    { --x: -12vw; --y: 52px;  --s: 56px; --rot: -4deg; }
-    .hf-antigravity { --x: 12vw;  --y: 52px;  --s: 56px; --rot: 5deg; }
-    .hf-codex       { --x: 37vw;  --y: 44px;  --s: 64px; --rot: 8deg; }
+    .hf-claude      { --x: -37vw; --y: 44px; --s: 64px; --rot: -10deg; }
+    .hf-opencode    { --x: -12vw; --y: 52px; --s: 56px; --rot: -4deg; }
+    .hf-antigravity { --x: 12vw; --y: 52px; --s: 56px; --rot: 5deg; }
+    .hf-codex       { --x: 37vw; --y: 44px; --s: 64px; --rot: 8deg; }
     .hf-grok     { --x: -36vw; --y: 474px; --s: 64px; --rot: -6deg; }
-    .hf-cursor   { --x: 36vw;  --y: 474px; --s: 64px; --rot: 7deg; }
+    .hf-cursor   { --x: 36vw; --y: 474px; --s: 64px; --rot: 7deg; }
   }
 
   @media (max-width: 340px) {
@@ -878,67 +819,22 @@ const mobileEndorsementRows = [
   }
 
   .endorsement-carousel {
-    position: relative;
-    display: flex;
-    flex-direction: column;
-    gap: 12px;
-  }
-
-  .endorsement-carousel--mobile {
-    display: none;
-  }
-
-  .endorsement-carousel::before,
-  .endorsement-carousel::after {
-    content: "";
-    position: absolute;
-    top: 0;
-    bottom: 0;
-    z-index: 2;
-    width: max(48px, calc((100vw - 1240px) / 2 + 56px));
-    pointer-events: none;
-  }
-
-  .endorsement-carousel::before {
-    left: 0;
-    background: linear-gradient(90deg, var(--bg), transparent);
-  }
-
-  .endorsement-carousel::after {
-    right: 0;
-    background: linear-gradient(270deg, var(--bg), transparent);
-  }
-
-  .endorsement-row {
-    overflow: hidden;
-  }
-
-  .endorsement-track {
-    width: max-content;
-    display: flex;
-    animation: endorsementMarquee 76s linear infinite;
-    will-change: transform;
-  }
-
-  .endorsement-track-group {
-    display: flex;
+    display: grid;
+    grid-auto-flow: column;
+    grid-template-rows: repeat(2, 132px);
+    grid-auto-columns: clamp(264px, 22vw, 308px);
     gap: 12px;
-    padding-right: 12px;
-  }
-
-  .endorsement-row.is-reverse .endorsement-track {
-    animation-direction: reverse;
-    animation-duration: 84s;
-  }
-
-  .endorsement-carousel:hover .endorsement-track,
-  .endorsement-carousel:focus-within .endorsement-track {
-    animation-play-state: paused;
+    overflow-x: auto;
+    overscroll-behavior-x: contain;
+    /* Percentages resolve against this element's own box rather than the
+       viewport, so the first card lines up with the heading's .container edge
+       even when a classic scrollbar makes 100vw wider than the layout. */
+    padding: 4px max(32px, calc((100% - 1240px) / 2 + 32px));
+    scroll-padding-inline: max(32px, calc((100% - 1240px) / 2 + 32px));
   }
 
   .endorsement-card {
     position: relative;
-    width: clamp(264px, 22vw, 308px);
     height: 132px;
     padding: 14px 16px;
     display: flex;
@@ -1117,6 +1013,15 @@ const mobileEndorsementRows = [
     background: var(--fg);
     margin-left: 4px;
     animation: blink 1s steps(2) infinite;
+    animation-play-state: var(--home-motion-state, paused);
+  }
+
+  @keyframes blink {
+    50% { opacity: 0; }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .caret { animation: none; }
   }
 
   .open-pitch {
@@ -1234,19 +1139,6 @@ const mobileEndorsementRows = [
     margin-bottom: 24px;
   }
 
-  @keyframes blink {
-    50% { opacity: 0; }
-  }
-
-  @keyframes endorsementMarquee {
-    from {
-      transform: translateX(0);
-    }
-    to {
-      transform: translateX(-50%);
-    }
-  }
-
   /* ── Responsive ────────────────────────────────────────── */
   @media (max-width: 960px) {
     .hero-preview {
@@ -1273,25 +1165,13 @@ const mobileEndorsementRows = [
     .endorsements-head {
       margin-bottom: 40px;
     }
-    .endorsement-carousel--desktop {
-      display: none;
-    }
-    .endorsement-carousel--mobile {
-      display: flex;
-    }
-    .endorsement-carousel::before,
-    .endorsement-carousel::after {
-      width: 28px;
-    }
-    .endorsement-track {
-      animation-duration: 68s;
-    }
-    .endorsement-row.is-reverse .endorsement-track {
-      animation-duration: 76s;
+    .endorsement-carousel {
+      grid-template-rows: repeat(3, 132px);
+      grid-auto-columns: 268px;
+      padding-inline: 20px;
+      scroll-padding-inline: 20px;
     }
     .endorsement-card {
-      width: 268px;
-      height: 132px;
       padding: 14px;
     }
     .endorsement-card p {
diff --git a/apps/marketing/src/styles/fonts.css b/apps/marketing/src/styles/fonts.css
new file mode 100644
index 000000000000..2f3933d61239
--- /dev/null
+++ b/apps/marketing/src/styles/fonts.css
@@ -0,0 +1,193 @@
+/*! DM Sans v17 and JetBrains Mono v24. Licenses: /fonts/dm-sans-OFL.txt and /fonts/jetbrains-mono-OFL.txt. */
+/* Keep subset bytes out of the stylesheet so unused glyph ranges do not add transfer size. */
+/* latin-ext */
+@font-face {
+  font-family: "DM Sans";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/dm-sans-latin-ext.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329,
+    U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F,
+    U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: "DM Sans";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/dm-sans-latin.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+/* latin-ext */
+@font-face {
+  font-family: "DM Sans";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/dm-sans-latin-ext.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329,
+    U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F,
+    U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: "DM Sans";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/dm-sans-latin.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+/* latin-ext */
+@font-face {
+  font-family: "DM Sans";
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url(../assets/fonts/dm-sans-latin-ext.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329,
+    U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F,
+    U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: "DM Sans";
+  font-style: normal;
+  font-weight: 600;
+  font-display: swap;
+  src: url(../assets/fonts/dm-sans-latin.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+/* cyrillic-ext */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-cyrillic-ext.woff2?no-inline) format("woff2");
+  unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
+}
+/* cyrillic */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-cyrillic.woff2?no-inline) format("woff2");
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+/* greek */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-greek.woff2?no-inline) format("woff2");
+  unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;
+}
+/* vietnamese */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-vietnamese.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301,
+    U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;
+}
+/* latin-ext */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-latin-ext.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329,
+    U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F,
+    U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-latin.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+/* cyrillic-ext */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-cyrillic-ext.woff2?no-inline) format("woff2");
+  unicode-range: U+0460-052F, U+1C80-1C8A, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
+}
+/* cyrillic */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-cyrillic.woff2?no-inline) format("woff2");
+  unicode-range: U+0301, U+0400-045F, U+0490-0491, U+04B0-04B1, U+2116;
+}
+/* greek */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-greek.woff2?no-inline) format("woff2");
+  unicode-range: U+0370-0377, U+037A-037F, U+0384-038A, U+038C, U+038E-03A1, U+03A3-03FF;
+}
+/* vietnamese */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-vietnamese.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0102-0103, U+0110-0111, U+0128-0129, U+0168-0169, U+01A0-01A1, U+01AF-01B0, U+0300-0301,
+    U+0303-0304, U+0308-0309, U+0323, U+0329, U+1EA0-1EF9, U+20AB;
+}
+/* latin-ext */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-latin-ext.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308, U+0329,
+    U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113, U+2C60-2C7F,
+    U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: "JetBrains Mono";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url(../assets/fonts/jetbrains-mono-latin.woff2?no-inline) format("woff2");
+  unicode-range:
+    U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304, U+0308, U+0329,
+    U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
diff --git a/apps/mobile/README.md b/apps/mobile/README.md
index ed95b060fe3a..a9a8177c4ece 100644
--- a/apps/mobile/README.md
+++ b/apps/mobile/README.md
@@ -38,12 +38,8 @@ vp run dev:client:reset
 Run that reset once after installing or changing the Uniwind dependency patch. Cached transforms
 can otherwise reference its previous pnpm package path. Ordinary Metro starts still keep the cache.
 
-Component edits use Fast Refresh. Connection-runtime edits replace the active Effect layer through
-a stable atom runtime, preserving navigation and existing atom subscribers. Replaced registries
-and managed runtimes dispose their resources; the app does not force a JavaScript reload. The Uniwind patch
-skips global style invalidation when generated styles and themes are unchanged, while real style
-changes still refresh. See [mobile development lifecycle](../../docs/internals/mobile-development.md)
-for the lifetime boundaries.
+Component edits use Fast Refresh. See [mobile development lifecycle](../../docs/internals/mobile-development.md)
+before changing runtime ownership or refresh behavior.
 
 Build and run the local iOS dev client:
 
@@ -51,6 +47,10 @@ Build and run the local iOS dev client:
 vp run ios:dev
 ```
 
+After changing a native dependency patch, rerun CocoaPods before rebuilding an existing iOS
+project. pnpm gives each patch hash a new package path; Pods can otherwise keep compiling the
+previous directory.
+
 If your Xcode account only has a Personal Team, use a bundle identifier you control and opt into the
 reduced-capability local build. Personal Team builds omit the widget and share extensions, push
 entitlement, and native Sign in with Apple entitlement; builds without this opt-in are unchanged.
diff --git a/apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts b/apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts
index 2b39ac201599..4c8a6c4d7cd5 100644
--- a/apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts
+++ b/apps/mobile/modules/t3-markdown-text/src/nativeMarkdownText.ts
@@ -195,7 +195,8 @@ function appendRun(
   return runs;
 }
 
-const SKILL_TOKEN_REGEX = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+const SKILL_TOKEN_REGEX =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g;
 
 function formatSkillLabel(skill: SelectableMarkdownSkill): string {
   const displayName = skill.displayName?.trim();
diff --git a/apps/mobile/scripts/wire-widget-asset-catalog.cjs b/apps/mobile/scripts/wire-widget-asset-catalog.cjs
deleted file mode 100644
index b7c70f0cdcd6..000000000000
--- a/apps/mobile/scripts/wire-widget-asset-catalog.cjs
+++ /dev/null
@@ -1,30 +0,0 @@
-"use strict";
-
-// One-off: apply the widget asset-catalog wiring to the already-generated
-// ios/ project so the current build compiles ExpoWidgetsTarget/Assets.xcassets
-// without a full `expo prebuild`. The durable equivalent lives in
-// plugins/withWidgetLogoAsset.cjs and runs on prebuild.
-
-const path = require("path");
-const fs = require("fs");
-
-const xcodePath = require.resolve("xcode", {
-  paths: [
-    require.resolve("@expo/config-plugins", { paths: [require.resolve("expo/package.json")] }),
-  ],
-});
-const xcode = require(xcodePath);
-const { addWidgetAssetCatalog } = require("../plugins/lib/addWidgetAssetCatalog.cjs");
-
-const pbxprojPath = path.join(__dirname, "..", "ios", "T3CodeDev.xcodeproj", "project.pbxproj");
-const proj = xcode.project(pbxprojPath);
-proj.parseSync();
-
-const added = addWidgetAssetCatalog(proj, { targetName: "ExpoWidgetsTarget" });
-
-if (added) {
-  fs.writeFileSync(pbxprojPath, proj.writeSync());
-  console.log("Added widget asset-compile phase to ExpoWidgetsTarget.");
-} else {
-  console.log("No change: phase already present.");
-}
diff --git a/apps/mobile/src/Stack.tsx b/apps/mobile/src/Stack.tsx
index dd6e1679c5e6..57303a1bb001 100644
--- a/apps/mobile/src/Stack.tsx
+++ b/apps/mobile/src/Stack.tsx
@@ -56,7 +56,6 @@ import { SettingsAuthRouteScreen } from "./features/settings/SettingsAuthRouteSc
 import { SettingsEnvironmentsRouteScreen } from "./features/settings/SettingsEnvironmentsRouteScreen";
 import { SettingsLegalRouteScreen } from "./features/settings/SettingsLegalRouteScreen";
 import { SettingsProjectGroupingRouteScreen } from "./features/settings/SettingsProjectGroupingRouteScreen";
-import { SettingsProviderSetupRouteScreen } from "./features/settings/SettingsProviderSetupRouteScreen";
 import { UsageRouteScreen } from "./features/usage/UsageRouteScreen";
 import { SettingsRouteScreen } from "./features/settings/SettingsRouteScreen";
 import { ShowcaseCaptureCoordinator } from "./features/showcase/ShowcaseCaptureCoordinator";
@@ -165,13 +164,6 @@ const SettingsContentStack = createNativeStackNavigator({
         title: "Add Environment",
       },
     }),
-    SettingsProviderSetup: createNativeStackScreen({
-      screen: SettingsProviderSetupRouteScreen,
-      linking: "providers/:environmentId/:instanceId",
-      options: {
-        title: "Antigravity",
-      },
-    }),
     SettingsArchive: createNativeStackScreen({
       screen: ArchivedThreadsRouteScreen,
       linking: "archive",
diff --git a/apps/mobile/src/components/ComposerAttachmentStrip.tsx b/apps/mobile/src/components/ComposerAttachmentStrip.tsx
index b5d86c44109d..40465012e5da 100644
--- a/apps/mobile/src/components/ComposerAttachmentStrip.tsx
+++ b/apps/mobile/src/components/ComposerAttachmentStrip.tsx
@@ -1,10 +1,16 @@
 import { SymbolView } from "../components/AppSymbol";
 import { videoMimeType } from "@t3tools/shared/video";
-import { useMemo } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { Image, Pressable, ScrollView, View } from "react-native";
 
 import { AppText as Text } from "./AppText";
-import type { DraftComposerAttachment, DraftComposerFileAttachment } from "../lib/composerImages";
+import {
+  isFileBackedComposerAttachment,
+  type DraftComposerAttachment,
+  type DraftComposerFileAttachment,
+  type DraftComposerImageAttachment,
+} from "../lib/composerImages";
+import { resolveOwnedComposerAttachmentFileUri } from "../lib/composerAttachmentFiles";
 import { VideoAttachmentTile } from "./VideoAttachmentTile";
 import type { MediaActionsSource } from "../lib/mediaActions";
 import { PresentationSource } from "./NativePresentation";
@@ -87,35 +93,75 @@ export function ComposerAttachmentThumbnail(props: ComposerAttachmentThumbnailPr
   );
 }
 
+/**
+ * Thumbnail URI for a draft image. File-backed previews rebase into the
+ * current iOS data container (its UUID changes across installs); the raw
+ * persisted URI renders meanwhile, which is correct everywhere but after a
+ * container move.
+ */
+function useComposerImagePreviewUri(attachment: DraftComposerImageAttachment): string {
+  const { fileUri, previewUri } = attachment;
+  const [rebased, setRebased] = useState<{ fileUri: string; uri: string } | null>(null);
+  useEffect(() => {
+    if (fileUri === undefined) return;
+    let cancelled = false;
+    void (async () => {
+      const { Paths } = await import("expo-file-system");
+      const owned = resolveOwnedComposerAttachmentFileUri(fileUri, Paths.document.uri);
+      // Re-render only when the container actually moved.
+      if (!cancelled && owned !== null && owned !== previewUri) setRebased({ fileUri, uri: owned });
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [fileUri, previewUri]);
+  return fileUri !== undefined && rebased?.fileUri === fileUri ? rebased.uri : previewUri;
+}
+
+function ComposerImageAttachment(
+  props: ComposerAttachmentThumbnailProps & { readonly attachment: DraftComposerImageAttachment },
+) {
+  const { attachment } = props;
+  const style = { width: props.size, height: props.size, borderRadius: props.borderRadius };
+  const previewUri = useComposerImagePreviewUri(attachment);
+  const sourceIdentifier = `draft-image:${attachment.id}`;
+  return (
+    <PresentationSource identifier={sourceIdentifier}>
+      <Pressable
+        accessibilityRole="imagebutton"
+        accessibilityLabel={`Open ${attachment.name}`}
+        disabled={!props.onPressPreview}
+        onPress={() =>
+          props.onPressPreview?.(
+            // File-backed images open through the retain-lease + container
+            // rebase path; legacy drafts still carry their inline bytes.
+            isFileBackedComposerAttachment(attachment)
+              ? { kind: "image", attachment, name: attachment.name, sourceIdentifier }
+              : {
+                  kind: "image",
+                  uri: attachment.dataUrl ?? attachment.previewUri,
+                  name: attachment.name,
+                  sourceIdentifier,
+                },
+          )
+        }
+      >
+        <Image
+          source={{ uri: previewUri }}
+          style={style}
+          className="bg-subtle"
+          resizeMode="cover"
+        />
+      </Pressable>
+    </PresentationSource>
+  );
+}
+
 function ComposerAttachmentContent(props: ComposerAttachmentThumbnailProps) {
   const { attachment } = props;
   const style = { width: props.size, height: props.size, borderRadius: props.borderRadius };
   if (attachment.type === "image") {
-    const sourceIdentifier = `draft-image:${attachment.id}`;
-    return (
-      <PresentationSource identifier={sourceIdentifier}>
-        <Pressable
-          accessibilityRole="imagebutton"
-          accessibilityLabel={`Open ${attachment.name}`}
-          disabled={!props.onPressPreview}
-          onPress={() =>
-            props.onPressPreview?.({
-              kind: "image",
-              uri: attachment.dataUrl,
-              name: attachment.name,
-              sourceIdentifier,
-            })
-          }
-        >
-          <Image
-            source={{ uri: attachment.previewUri }}
-            style={style}
-            className="bg-subtle"
-            resizeMode="cover"
-          />
-        </Pressable>
-      </PresentationSource>
-    );
+    return <ComposerImageAttachment {...props} attachment={attachment} />;
   }
   const onPressVideo = props.onPressVideo;
   if (onPressVideo && videoMimeType(attachment) !== null) {
diff --git a/apps/mobile/src/components/FilePreviewModal.tsx b/apps/mobile/src/components/FilePreviewModal.tsx
index c8a6d4291947..1cdb6a6854a6 100644
--- a/apps/mobile/src/components/FilePreviewModal.tsx
+++ b/apps/mobile/src/components/FilePreviewModal.tsx
@@ -3,7 +3,7 @@ import type { AssetResource, EnvironmentId } from "@t3tools/contracts";
 import { useEffect, useEffectEvent, useState } from "react";
 import { Alert, Keyboard } from "react-native";
 
-import type { DraftComposerFileAttachment } from "../lib/composerImages";
+import type { FileBackedComposerAttachment } from "../lib/composerImages";
 import { loadLocalAttachmentPreview } from "../lib/localAttachmentPreview";
 import type { MediaActionsSource } from "../lib/mediaActions";
 import { useAssetUrlState } from "../state/assets";
@@ -22,7 +22,7 @@ export interface ResolvedFilePreviewSource {
 export type FilePreviewSource = Omit<ResolvedFilePreviewSource, "uri"> &
   (
     | { readonly uri: string }
-    | { readonly attachment: DraftComposerFileAttachment }
+    | { readonly attachment: FileBackedComposerAttachment }
     | { readonly environmentId: EnvironmentId; readonly resource: AssetResource }
   );
 
diff --git a/apps/mobile/src/connection/platform.ts b/apps/mobile/src/connection/platform.ts
index d6b50e50a6a7..f7fa30c8f230 100644
--- a/apps/mobile/src/connection/platform.ts
+++ b/apps/mobile/src/connection/platform.ts
@@ -118,6 +118,9 @@ const capabilitiesLayer = Layer.effectContext(
     return Context.make(
       CloudSession,
       CloudSession.of({
+        identity: Effect.sync(() =>
+          Option.fromNullishOr(appAtomRegistry.get(managedRelaySessionAtom)),
+        ),
         clerkToken: Effect.gen(function* () {
           const session = appAtomRegistry.get(managedRelaySessionAtom);
           if (session === null) {
diff --git a/apps/mobile/src/connection/runtime.ts b/apps/mobile/src/connection/runtime.ts
index ee224ce9f6ed..deee27ef040d 100644
--- a/apps/mobile/src/connection/runtime.ts
+++ b/apps/mobile/src/connection/runtime.ts
@@ -30,7 +30,8 @@ type ConnectionLayerSource =
   | typeof mobileBackgroundActivityObserverLayer
   | typeof mobileBackgroundActivityReporterLayer;
 
-const providedClientConnectionLayer = Layer.merge(Connection.layer, snapshotLoaderLayer).pipe(
+const providedClientConnectionLayer = snapshotLoaderLayer.pipe(
+  Layer.provideMerge(Connection.layerWithOptions({ usageLimitSources: true })),
   Layer.provideMerge(
     Layer.mergeAll(
       runtimeContextLayer,
diff --git a/apps/mobile/src/connection/storage.ts b/apps/mobile/src/connection/storage.ts
index e844181673df..ab361b8331a6 100644
--- a/apps/mobile/src/connection/storage.ts
+++ b/apps/mobile/src/connection/storage.ts
@@ -2,6 +2,7 @@ import {
   ConnectionPersistenceError,
   ConnectionRegistrationStore,
   ConnectionTargetStore,
+  putRemoteDpopTokenInCatalog,
   registerConnectionInCatalog,
   removeConnectionFromCatalog,
   removeCatalogValue,
@@ -109,15 +110,7 @@ export const connectionStorageLayer = Layer.effectContext(
             ),
           ),
         ),
-      put: (token) =>
-        catalog.update((document) => ({
-          ...document,
-          remoteDpopTokens: replaceCatalogValue(
-            document.remoteDpopTokens,
-            (value) => value.environmentId,
-            token,
-          ),
-        })),
+      put: (token) => catalog.update((document) => putRemoteDpopTokenInCatalog(document, token)),
       remove: (environmentId) =>
         catalog.update((document) => ({
           ...document,
diff --git a/apps/mobile/src/features/agent-awareness/remoteRegistration.test.ts b/apps/mobile/src/features/agent-awareness/remoteRegistration.test.ts
index 582c58fb27e6..152948274ca3 100644
--- a/apps/mobile/src/features/agent-awareness/remoteRegistration.test.ts
+++ b/apps/mobile/src/features/agent-awareness/remoteRegistration.test.ts
@@ -33,7 +33,6 @@ import {
   mergeAgentAwarenessRegistrationPreferences,
   refreshActiveLiveActivityRemoteRegistration,
   refreshAgentAwarenessRegistration,
-  normalizeAgentAwarenessRelayBaseUrl,
   registerAgentAwarenessConnection,
   registerLiveActivityPushToken,
   releaseAgentAwarenessRelayTokenProvider,
@@ -363,13 +362,6 @@ describe("makeRelayDeviceRegistrationRequest", () => {
     });
   });
 
-  it("normalizes relay base URLs for APNs registration requests", () => {
-    expect(normalizeAgentAwarenessRelayBaseUrl(" https://relay.example.test/// ")).toBe(
-      "https://relay.example.test",
-    );
-    expect(normalizeAgentAwarenessRelayBaseUrl("   ")).toBeNull();
-  });
-
   it("overrides persisted preferences for an in-flight registration", () => {
     expect(
       mergeAgentAwarenessRegistrationPreferences(
diff --git a/apps/mobile/src/features/agent-awareness/remoteRegistration.ts b/apps/mobile/src/features/agent-awareness/remoteRegistration.ts
index a2d4261de603..9f4539c44d64 100644
--- a/apps/mobile/src/features/agent-awareness/remoteRegistration.ts
+++ b/apps/mobile/src/features/agent-awareness/remoteRegistration.ts
@@ -139,16 +139,6 @@ export function mergeAgentAwarenessRegistrationPreferences(
   return { ...stored, ...override };
 }
 
-export function normalizeAgentAwarenessRelayBaseUrl(
-  value: string | null | undefined,
-): string | null {
-  const trimmed = value?.trim();
-  if (!trimmed) {
-    return null;
-  }
-  return trimmed.replace(/\/+$/g, "");
-}
-
 function readRelayConfig(): { readonly url: string } | null {
   const relayUrl = resolveCloudPublicConfig().relay.url;
   if (!relayUrl) {
diff --git a/apps/mobile/src/features/cloud/ConnectOnboardingRouteScreen.tsx b/apps/mobile/src/features/cloud/ConnectOnboardingRouteScreen.tsx
index 7aac695255f4..952d1c388417 100644
--- a/apps/mobile/src/features/cloud/ConnectOnboardingRouteScreen.tsx
+++ b/apps/mobile/src/features/cloud/ConnectOnboardingRouteScreen.tsx
@@ -111,12 +111,6 @@ function ConfiguredConnectOnboardingRouteScreen() {
           <CloudEnvironmentRows
             connectedCloudEnvironments={connectedCloudEnvironments}
             onReconnectEnvironment={onReconnectEnvironment}
-            onSetupProvider={(params) =>
-              navigation.navigate("SettingsSheet", {
-                screen: "SettingsContent",
-                params: { screen: "SettingsProviderSetup", params },
-              })
-            }
             showHeader={false}
           />
         ) : (
diff --git a/apps/mobile/src/features/cloud/linkEnvironment.test.ts b/apps/mobile/src/features/cloud/linkEnvironment.test.ts
index 42aa8ffebb61..feadf6c81893 100644
--- a/apps/mobile/src/features/cloud/linkEnvironment.test.ts
+++ b/apps/mobile/src/features/cloud/linkEnvironment.test.ts
@@ -11,13 +11,11 @@ import { MobilePreferencesStore } from "../../persistence/mobile-preferences";
 import { MobileStorage } from "../../persistence/mobile-storage";
 
 import {
-  cloudEnvironmentsPendingStatus,
   linkEnvironmentToCloud,
   linkEnvironmentToCloudWithPreference,
   connectCloudEnvironment,
   listCloudEnvironments,
   listCloudEnvironmentsWithStatus,
-  normalizeRelayBaseUrl,
   refreshCloudEnvironmentConnection,
 } from "./linkEnvironment";
 
@@ -195,23 +193,6 @@ describe("mobile cloud link environment client", () => {
     loadPreferences.mockClear();
   });
 
-  it("normalizes configured relay base URLs before building DPoP-bound requests", () => {
-    expect(normalizeRelayBaseUrl(" https://relay.example.test/// ")).toBe(
-      "https://relay.example.test",
-    );
-    expect(normalizeRelayBaseUrl("   ")).toBeNull();
-  });
-
-  it("makes linked environments visible while their status is still loading", () => {
-    expect(cloudEnvironmentsPendingStatus([listedEnvironment("env-1")])).toMatchObject([
-      {
-        environment: { environmentId: "env-1", label: "Desktop" },
-        status: null,
-        statusError: "Checking status...",
-      },
-    ]);
-  });
-
   it.effect("decodes relay environment list responses before returning records", () =>
     Effect.gen(function* () {
       vi.stubGlobal(
diff --git a/apps/mobile/src/features/cloud/linkEnvironment.ts b/apps/mobile/src/features/cloud/linkEnvironment.ts
index c2033117f69d..b8dc8f878e0c 100644
--- a/apps/mobile/src/features/cloud/linkEnvironment.ts
+++ b/apps/mobile/src/features/cloud/linkEnvironment.ts
@@ -43,14 +43,6 @@ const RELAY_STATUS_AND_CONNECT_SCOPES = [
   RelayEnvironmentConnectScope,
 ] satisfies ReadonlyArray<RelayDpopAccessTokenScope>;
 
-export function normalizeRelayBaseUrl(value: string | null | undefined): string | null {
-  const trimmed = value?.trim();
-  if (!trimmed) {
-    return null;
-  }
-  return trimmed.replace(/\/+$/g, "");
-}
-
 function readRelayUrl(): string | null {
   return resolveCloudPublicConfig().relay.url;
 }
@@ -405,16 +397,6 @@ export function getCloudEnvironmentStatus(input: {
   });
 }
 
-export function cloudEnvironmentsPendingStatus(
-  environments: ReadonlyArray<RelayClientEnvironmentRecord>,
-): ReadonlyArray<CloudEnvironmentRecordWithStatus> {
-  return environments.map((environment) => ({
-    environment,
-    status: null,
-    statusError: "Checking status...",
-  }));
-}
-
 export function loadCloudEnvironmentStatuses(input: {
   readonly clerkToken: string;
   readonly environments: ReadonlyArray<RelayClientEnvironmentRecord>;
diff --git a/apps/mobile/src/features/connection/CloudEnvironmentRows.tsx b/apps/mobile/src/features/connection/CloudEnvironmentRows.tsx
index f4a5b531d026..448889549016 100644
--- a/apps/mobile/src/features/connection/CloudEnvironmentRows.tsx
+++ b/apps/mobile/src/features/connection/CloudEnvironmentRows.tsx
@@ -26,8 +26,6 @@ import { cn } from "../../lib/cn";
 import { copyTextWithHaptic } from "../../lib/copyTextWithHaptic";
 import type { ConnectedEnvironmentSummary } from "../../state/remote-runtime-types";
 import { serverEnvironment } from "../../state/server";
-import { ProviderSetupLink } from "../settings/ProviderSetupLink";
-import type { ProviderSetupRouteParams } from "../settings/SettingsProviderSetupRouteScreen";
 import { availableCloudEnvironmentPresentation } from "../cloud/cloudEnvironmentPresentation";
 import { hasCloudPublicConfig } from "../cloud/publicConfig";
 import { ConnectionStatusDot } from "./ConnectionStatusDot";
@@ -36,7 +34,6 @@ import { type RelayEnvironmentView, useConnectionController } from "./useConnect
 interface CloudEnvironmentRowsProps {
   readonly connectedCloudEnvironments: ReadonlyArray<ConnectedEnvironmentSummary>;
   readonly onReconnectEnvironment: (environmentId: EnvironmentId) => void;
-  readonly onSetupProvider?: (target: ProviderSetupRouteParams) => void;
   readonly showcaseAvailableEnvironments?: ReadonlyArray<RelayEnvironmentView>;
   readonly showcaseSignedIn?: boolean;
   /**
@@ -151,7 +148,6 @@ function CloudEnvironmentRowsContent(
               onDisconnect={() => handleDisconnectCloudEnvironment(environment.environmentId)}
               errorExpanded={expandedErrorId === environment.environmentId}
               onToggleError={() => handleToggleCloudError(environment.environmentId)}
-              onSetupProvider={props.onSetupProvider}
             />
           ))}
           {availableCloudEnvironments.map((environment, index) => (
@@ -215,7 +211,6 @@ function ConnectedCloudEnvironmentRow(props: {
   readonly onConnect: () => void;
   readonly onDisconnect: () => void;
   readonly onToggleError: () => void;
-  readonly onSetupProvider?: (target: ProviderSetupRouteParams) => void;
 }) {
   const serverConfig = useAtomValue(
     serverEnvironment.configValueAtom(props.environment.environmentId),
@@ -240,23 +235,6 @@ function ConnectedCloudEnvironmentRow(props: {
         onToggleError={props.onToggleError}
         value={props.environment.connectionState !== "available"}
       />
-      {props.onSetupProvider
-        ? serverConfig?.providers
-            .filter((provider) => provider.setup?.canAuthenticate || provider.setup?.canInstall)
-            .map((provider) => (
-              <ProviderSetupLink
-                key={provider.instanceId}
-                provider={provider}
-                disabled={props.environment.connectionState !== "connected"}
-                onPress={() =>
-                  props.onSetupProvider?.({
-                    environmentId: props.environment.environmentId,
-                    instanceId: provider.instanceId,
-                  })
-                }
-              />
-            ))
-        : null}
     </View>
   );
 }
diff --git a/apps/mobile/src/features/connection/ConnectionEnvironmentRow.tsx b/apps/mobile/src/features/connection/ConnectionEnvironmentRow.tsx
index 879b89b9b2f4..75d3e8ce7a34 100644
--- a/apps/mobile/src/features/connection/ConnectionEnvironmentRow.tsx
+++ b/apps/mobile/src/features/connection/ConnectionEnvironmentRow.tsx
@@ -15,8 +15,6 @@ import { cn } from "../../lib/cn";
 import { copyTextWithHaptic } from "../../lib/copyTextWithHaptic";
 import type { ConnectedEnvironmentSummary } from "../../state/remote-runtime-types";
 import { serverEnvironment } from "../../state/server";
-import { ProviderSetupLink } from "../settings/ProviderSetupLink";
-import type { ProviderSetupRouteParams } from "../settings/SettingsProviderSetupRouteScreen";
 import { ConnectionStatusDot } from "./ConnectionStatusDot";
 
 function connectionStatusLabel(environment: ConnectedEnvironmentSummary): string | null {
@@ -33,7 +31,6 @@ export function ConnectionEnvironmentRow(props: {
   readonly onToggle: () => void;
   readonly onReconnect: (environmentId: EnvironmentId) => void;
   readonly onRemove: (environmentId: EnvironmentId) => void;
-  readonly onSetupProvider: (target: ProviderSetupRouteParams) => void;
   readonly onUpdate: (
     environmentId: EnvironmentId,
     updates: { readonly label: string; readonly displayUrl: string },
@@ -182,22 +179,6 @@ export function ConnectionEnvironmentRow(props: {
             </>
           )}
 
-          {serverConfig?.providers
-            .filter((provider) => provider.setup?.canAuthenticate || provider.setup?.canInstall)
-            .map((provider) => (
-              <ProviderSetupLink
-                key={provider.instanceId}
-                provider={provider}
-                disabled={props.environment.connectionState !== "connected"}
-                onPress={() =>
-                  props.onSetupProvider({
-                    environmentId: props.environment.environmentId,
-                    instanceId: provider.instanceId,
-                  })
-                }
-              />
-            ))}
-
           <View className="flex-row justify-end gap-2">
             {props.environment.isRelayManaged ? null : (
               <Pressable
diff --git a/apps/mobile/src/features/connection/ConnectionsRouteScreen.tsx b/apps/mobile/src/features/connection/ConnectionsRouteScreen.tsx
index 964f571bfee2..88d4e2d4bee7 100644
--- a/apps/mobile/src/features/connection/ConnectionsRouteScreen.tsx
+++ b/apps/mobile/src/features/connection/ConnectionsRouteScreen.tsx
@@ -75,12 +75,6 @@ export function ConnectionsRouteScreen() {
                   onReconnect={onReconnectEnvironment}
                   onRemove={onRemoveEnvironmentPress}
                   onUpdate={onUpdateEnvironment}
-                  onSetupProvider={(params) =>
-                    navigation.navigate("SettingsSheet", {
-                      screen: "SettingsContent",
-                      params: { screen: "SettingsProviderSetup", params },
-                    })
-                  }
                 />
               </View>
             ))}
diff --git a/apps/mobile/src/features/diffs/nativeReviewDiffHighlighter.test.ts b/apps/mobile/src/features/diffs/nativeReviewDiffHighlighter.test.ts
index 9e1480d1de93..24b18edd5db3 100644
--- a/apps/mobile/src/features/diffs/nativeReviewDiffHighlighter.test.ts
+++ b/apps/mobile/src/features/diffs/nativeReviewDiffHighlighter.test.ts
@@ -1,9 +1,44 @@
-import { describe, expect, it } from "vite-plus/test";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
 import type { NativeReviewDiffRow } from "./nativeReviewDiffSurface";
 import type { NativeReviewDiffFile } from "./nativeReviewDiffTypes";
 import { highlightNativeReviewDiffVisibleRows } from "./nativeReviewDiffHighlighter";
 
+const tokenization = vi.hoisted(() => ({
+  calls: [] as string[],
+  afterCall: undefined as (() => void) | undefined,
+}));
+
+vi.mock("@shikijs/core", async (importOriginal) => {
+  const original = await importOriginal<typeof import("@shikijs/core")>();
+  return {
+    ...original,
+    createHighlighterCore: async (...args: Parameters<typeof original.createHighlighterCore>) => {
+      const highlighter = await original.createHighlighterCore(...args);
+      return {
+        ...highlighter,
+        codeToTokensBase: (...input: Parameters<typeof highlighter.codeToTokensBase>) => {
+          tokenization.calls.push(input[0]);
+          const result = highlighter.codeToTokensBase(...input);
+          tokenization.afterCall?.();
+          return result;
+        },
+      };
+    },
+  };
+});
+
+// Exercise the native entry path without requiring an iOS or Android runtime.
+vi.mock("react-native-shiki-engine", async () => {
+  const { createJavaScriptRegexEngine } = await import("@shikijs/engine-javascript");
+  return { isNativeEngineAvailable: () => true, createNativeEngine: createJavaScriptRegexEngine };
+});
+
+afterEach(() => {
+  tokenization.calls = [];
+  tokenization.afterCall = undefined;
+});
+
 const TYPESCRIPT_FILE: NativeReviewDiffFile = {
   id: "file-1",
   path: "example.ts",
@@ -187,3 +222,118 @@ describe("highlightNativeReviewDiffVisibleRows", () => {
     );
   });
 });
+
+describe.each(["native", "javascript"] as const)("%s highlighting budgets", (engine) => {
+  const highlightRows = (rows: ReadonlyArray<NativeReviewDiffRow>, signal?: AbortSignal) =>
+    highlightNativeReviewDiffVisibleRows({
+      rows,
+      files: [TYPESCRIPT_FILE],
+      scheme: "dark",
+      engine,
+      firstRowIndex: 0,
+      lastRowIndex: rows.length - 1,
+      overscanRows: 0,
+      signal,
+    });
+
+  const line = (id: number, content: string) =>
+    makeLine({
+      id: `line-${id}`,
+      content,
+      change: "add",
+      oldLineNumber: null,
+      newLineNumber: id,
+    });
+
+  it("still highlights a line at the length limit", async () => {
+    const content = `// ${"x".repeat(997)}`;
+    const result = await highlightRows([line(1, content)]);
+
+    expect(tokenization.calls).toEqual([content]);
+    expect(result.tokensByRowId["line-1"]?.some((token) => token.color !== null)).toBe(true);
+  });
+
+  it("keeps only the long line plain and resumes highlighting after it", async () => {
+    const longLine = `${"x".repeat(1_001)} /*`;
+    const rows = [
+      line(1, "export const before = 1;"),
+      line(2, longLine),
+      { kind: "comment", id: "note", commentText: "Check this", fileId: TYPESCRIPT_FILE.id },
+      line(3, "export const inside = 'x';"),
+      makeHunk("next-hunk"),
+      line(100, "export const after = 2;"),
+    ] satisfies ReadonlyArray<NativeReviewDiffRow>;
+    const result = await highlightRows(rows);
+
+    expect(result.engine).toBe(engine);
+    expect(Object.keys(result.tokensByRowId)).toEqual(["line-1", "line-2", "line-3", "line-100"]);
+    expect(result.tokensByRowId["line-2"]).toEqual([
+      { content: longLine, color: null, fontStyle: null },
+    ]);
+    for (const id of ["line-1", "line-3", "line-100"]) {
+      expect(result.tokensByRowId[id]?.some((token) => token.color !== null)).toBe(true);
+    }
+    expect(tokenization.calls.some((code) => code.includes(longLine))).toBe(false);
+  });
+
+  it("highlights the rows after a long line the same regardless of the first window", async () => {
+    const rows = [
+      line(1, "export const before = 1;"),
+      line(2, `const data = "${"x".repeat(1_050)}";`),
+      line(3, "export const inside = 'x';"),
+      line(4, "export const after = 2;"),
+    ];
+    const spanning = await highlightRows(rows);
+    const afterLongLine = await highlightNativeReviewDiffVisibleRows({
+      rows,
+      files: [TYPESCRIPT_FILE],
+      scheme: "dark",
+      engine,
+      firstRowIndex: 2,
+      lastRowIndex: 3,
+      overscanRows: 0,
+    });
+
+    for (const id of ["line-3", "line-4"]) {
+      expect(spanning.tokensByRowId[id]?.some((token) => token.color !== null)).toBe(true);
+      expect(afterLongLine.tokensByRowId[id]).toEqual(spanning.tokensByRowId[id]);
+    }
+  });
+
+  it("preserves multiline grammar and row mapping across character-limited batches", async () => {
+    const opening = line(1, "const message = `open");
+    const body = Array.from({ length: 40 }, (_, index) => line(index + 2, "inside ".repeat(45)));
+    const closing = line(42, "closed`; ");
+    const trailing = line(43, "export const after = 2;");
+    const result = await highlightRows([opening, ...body, closing, trailing]);
+    const calls = [...tokenization.calls];
+    const expected = await highlightRows([
+      opening,
+      { ...closing, newLineNumber: 2 },
+      { ...trailing, newLineNumber: 3 },
+    ]);
+
+    expect(calls.length).toBeGreaterThan(1);
+    expect(calls.every((code) => code.length <= 8_000)).toBe(true);
+    expect(result.rowCount).toBe(43);
+    for (const row of [opening, ...body, closing, trailing]) {
+      expect(result.tokensByRowId[row.id]?.map((token) => token.content).join("")).toBe(
+        row.content,
+      );
+    }
+    expect(result.tokensByRowId[closing.id]).toEqual(expected.tokensByRowId[closing.id]);
+    expect(result.tokensByRowId[trailing.id]).toEqual(expected.tokensByRowId[trailing.id]);
+  });
+
+  it("stops before later batches and publishes no partial result after cancellation", async () => {
+    const controller = new AbortController();
+    tokenization.afterCall = () => controller.abort();
+    const rows = Array.from({ length: 30 }, (_, index) => line(index + 1, `// ${"x".repeat(400)}`));
+
+    const result = await highlightRows(rows, controller.signal);
+
+    expect(tokenization.calls).toHaveLength(1);
+    expect(result.rowCount).toBe(0);
+    expect(result.tokensByRowId).toEqual({});
+  });
+});
diff --git a/apps/mobile/src/features/diffs/nativeReviewDiffHighlighter.ts b/apps/mobile/src/features/diffs/nativeReviewDiffHighlighter.ts
index 14158e61c7d6..e924ff1aa645 100644
--- a/apps/mobile/src/features/diffs/nativeReviewDiffHighlighter.ts
+++ b/apps/mobile/src/features/diffs/nativeReviewDiffHighlighter.ts
@@ -1,4 +1,4 @@
-import { createHighlighterCore, type HighlighterCore } from "@shikijs/core";
+import { createHighlighterCore, type GrammarState, type HighlighterCore } from "@shikijs/core";
 import { createJavaScriptRegexEngine } from "@shikijs/engine-javascript";
 import bashLanguage from "@shikijs/langs/bash";
 import diffLanguage from "@shikijs/langs/diff";
@@ -46,8 +46,12 @@ export interface NativeReviewDiffHighlighterHandle {
   readonly engine: NativeReviewDiffHighlightEngine;
   readonly tokenize: (
     code: string,
-    options: { readonly lang: NativeReviewDiffLanguage; readonly theme: string },
-  ) => ReadonlyArray<ReadonlyArray<NativeReviewDiffToken>>;
+    options: {
+      readonly lang: NativeReviewDiffLanguage;
+      readonly theme: string;
+      readonly signal?: AbortSignal;
+    },
+  ) => Promise<ReadonlyArray<ReadonlyArray<NativeReviewDiffToken>>>;
 }
 
 interface NativeReviewDiffLineRow extends NativeReviewDiffRow {
@@ -61,26 +65,6 @@ interface IndexedNativeReviewDiffLineRow {
   readonly rowIndex: number;
 }
 
-export interface NativeReviewDiffTokenChunk {
-  readonly chunkIndex: number;
-  readonly fileId: string;
-  readonly filePath: string;
-  readonly language: NativeReviewDiffLanguage;
-  readonly lineCount: number;
-  readonly durationMs: number;
-  readonly tokensByRowId: Record<string, ReadonlyArray<NativeReviewDiffToken>>;
-}
-
-export interface StreamNativeReviewDiffTokenInput {
-  readonly rows: ReadonlyArray<NativeReviewDiffRow>;
-  readonly files: ReadonlyArray<NativeReviewDiffFile>;
-  readonly scheme: NativeReviewDiffHighlightScheme;
-  readonly engine?: NativeReviewDiffHighlightEngine;
-  readonly chunkSize?: number;
-  readonly signal?: AbortSignal;
-  readonly onChunk: (chunk: NativeReviewDiffTokenChunk) => void;
-}
-
 export interface HighlightNativeReviewDiffVisibleRowsInput {
   readonly rows: ReadonlyArray<NativeReviewDiffRow>;
   readonly files: ReadonlyArray<NativeReviewDiffFile>;
@@ -94,9 +78,10 @@ export interface HighlightNativeReviewDiffVisibleRowsInput {
   readonly signal?: AbortSignal;
 }
 
-const NATIVE_REVIEW_DIFF_HIGHLIGHT_CHUNK_SIZE = 500;
 const NATIVE_REVIEW_DIFF_VISIBLE_OVERSCAN_ROWS = 160;
 const NATIVE_REVIEW_DIFF_VISIBLE_MAX_ROWS = 360;
+const NATIVE_REVIEW_DIFF_TOKENIZE_MAX_LINE_LENGTH = 1_000;
+const NATIVE_REVIEW_DIFF_TOKENIZE_MAX_CHARACTERS = 8_000;
 
 const NATIVE_REVIEW_DIFF_THEME_NAME_BY_SCHEME = {
   dark: "t3-pierre-dark",
@@ -226,6 +211,64 @@ function normalizeTokens(
   );
 }
 
+function createHighlighterHandle(
+  highlighter: HighlighterCore,
+  engine: NativeReviewDiffHighlightEngine,
+): NativeReviewDiffHighlighterHandle {
+  return {
+    engine,
+    async tokenize(code, { lang, theme, signal }) {
+      const lines = code.split("\n");
+      const highlighted: Array<ReadonlyArray<NativeReviewDiffToken>> = [];
+      let grammarState: GrammarState | undefined;
+      let start = 0;
+
+      while (start < lines.length) {
+        if (signal?.aborted) return [];
+
+        // Skipping this line leaves its ending grammar state unknown. Resume
+        // from a fresh state rather than leaving the rest of the segment plain:
+        // highlighted rows are cached for the sheet's lifetime, so a plain tail
+        // would stick, and which rows it covered would depend on where the
+        // first visible window happened to start.
+        if (lines[start]!.length > NATIVE_REVIEW_DIFF_TOKENIZE_MAX_LINE_LENGTH) {
+          highlighted.push([{ content: lines[start] || " ", color: null, fontStyle: null }]);
+          grammarState = undefined;
+          start += 1;
+          continue;
+        }
+
+        let end = start;
+        let characters = 0;
+        while (end < lines.length) {
+          const length = lines[end]!.length;
+          const nextCharacters = characters + length + (end > start ? 1 : 0);
+          if (
+            length > NATIVE_REVIEW_DIFF_TOKENIZE_MAX_LINE_LENGTH ||
+            nextCharacters > NATIVE_REVIEW_DIFF_TOKENIZE_MAX_CHARACTERS
+          ) {
+            break;
+          }
+          characters = nextCharacters;
+          end += 1;
+        }
+
+        const tokens = highlighter.codeToTokensBase(lines.slice(start, end).join("\n"), {
+          lang,
+          theme,
+          grammarState,
+        });
+        grammarState = highlighter.getLastGrammarState(tokens);
+        highlighted.push(...normalizeTokens(tokens));
+        start = end;
+        if (start < lines.length) await waitForNextFrame();
+      }
+
+      return signal?.aborted ? [] : highlighted;
+    },
+  };
+}
+
 async function createNativeReviewDiffHighlighter(): Promise<NativeReviewDiffHighlighterHandle> {
   const nativeEngineModule = await import("react-native-shiki-engine");
   if (!nativeEngineModule.isNativeEngineAvailable()) {
@@ -238,10 +281,7 @@ async function createNativeReviewDiffHighlighter(): Promise<NativeReviewDiffHigh
     engine: nativeEngineModule.createNativeEngine(),
   });
 
-  return {
-    engine: "native",
-    tokenize: (code, options) => normalizeTokens(highlighter.codeToTokensBase(code, options)),
-  };
+  return createHighlighterHandle(highlighter, "native");
 }
 
 async function createJavascriptReviewDiffHighlighter(): Promise<NativeReviewDiffHighlighterHandle> {
@@ -251,10 +291,7 @@ async function createJavascriptReviewDiffHighlighter(): Promise<NativeReviewDiff
     engine: createJavaScriptRegexEngine(),
   });
 
-  return {
-    engine: "javascript",
-    tokenize: (code, options) => normalizeTokens(highlighter.codeToTokensBase(code, options)),
-  };
+  return createHighlighterHandle(highlighter, "javascript");
 }
 
 export async function getNativeReviewDiffHighlighter(
@@ -365,20 +402,6 @@ function canShareGrammarContext(
   );
 }
 
-function groupLineRowsByFileId(rows: ReadonlyArray<NativeReviewDiffRow>) {
-  const rowsByFileId = new Map<string, NativeReviewDiffLineRow[]>();
-  for (const row of rows) {
-    if (!isHighlightableLineRow(row)) {
-      continue;
-    }
-
-    const fileRows = rowsByFileId.get(row.fileId) ?? [];
-    fileRows.push(row);
-    rowsByFileId.set(row.fileId, fileRows);
-  }
-  return rowsByFileId;
-}
-
 function createFileMap(files: ReadonlyArray<NativeReviewDiffFile>) {
   return new Map(files.map((file) => [file.id, file]));
 }
@@ -438,8 +461,9 @@ export async function highlightNativeReviewDiffVisibleRows(
   const tokensByRowId: Record<string, ReadonlyArray<NativeReviewDiffToken>> = {};
   let segmentRows: IndexedNativeReviewDiffLineRow[] = [];
   let segmentFile: NativeReviewDiffFile | undefined;
+  let charactersSinceYield = 0;
 
-  const flushSegment = () => {
+  const flushSegment = async () => {
     if (!segmentFile || segmentRows.length === 0 || input.signal?.aborted) {
       segmentRows = [];
       segmentFile = undefined;
@@ -447,7 +471,20 @@ export async function highlightNativeReviewDiffVisibleRows(
     }
 
     const code = segmentRows.map(({ row }) => row.content).join("\n");
-    const tokenLines = highlighter.tokenize(code, { lang: segmentFile.language, theme });
+    if (
+      charactersSinceYield > 0 &&
+      charactersSinceYield + code.length > NATIVE_REVIEW_DIFF_TOKENIZE_MAX_CHARACTERS
+    ) {
+      await waitForNextFrame();
+      charactersSinceYield = 0;
+      if (input.signal?.aborted) return;
+    }
+    const tokenLines = await highlighter.tokenize(code, {
+      lang: segmentFile.language,
+      theme,
+      signal: input.signal,
+    });
+    charactersSinceYield += code.length;
     segmentRows.forEach(({ row }, rowIndex) => {
       tokensByRowId[row.id] = tokenLines[rowIndex] ?? makePlainTokenFallback(row);
     });
@@ -456,6 +493,7 @@ export async function highlightNativeReviewDiffVisibleRows(
   };
 
   for (const selectedRow of selectedRows) {
+    if (input.signal?.aborted) break;
     const { row } = selectedRow;
     const file = fileMap.get(row.fileId);
     if (!file) {
@@ -469,13 +507,17 @@ export async function highlightNativeReviewDiffVisibleRows(
         (previousRow !== undefined &&
           !canShareGrammarContext(previousRow, selectedRow, input.rows)))
     ) {
-      flushSegment();
+      await flushSegment();
     }
 
     segmentFile = file;
     segmentRows.push(selectedRow);
   }
-  flushSegment();
+  await flushSegment();
+
+  if (input.signal?.aborted) {
+    return { engine: highlighter.engine, tokensByRowId: {}, rowCount: 0, durationMs: 0 };
+  }
 
   return {
     engine: highlighter.engine,
@@ -484,47 +526,3 @@ export async function highlightNativeReviewDiffVisibleRows(
     durationMs: Math.round(performance.now() - startedAt),
   };
 }
-
-export async function streamNativeReviewDiffTokens(
-  input: StreamNativeReviewDiffTokenInput,
-): Promise<NativeReviewDiffHighlightEngine> {
-  const highlighter = await getNativeReviewDiffHighlighter(input.engine ?? "native");
-  const rowsByFileId = groupLineRowsByFileId(input.rows);
-  const theme = NATIVE_REVIEW_DIFF_THEME_NAME_BY_SCHEME[input.scheme];
-  const chunkSize = input.chunkSize ?? NATIVE_REVIEW_DIFF_HIGHLIGHT_CHUNK_SIZE;
-  let chunkIndex = 0;
-
-  for (const file of input.files) {
-    const fileRows = rowsByFileId.get(file.id) ?? [];
-    for (let startIndex = 0; startIndex < fileRows.length; startIndex += chunkSize) {
-      if (input.signal?.aborted) {
-        return highlighter.engine;
-      }
-
-      const startedAt = performance.now();
-      const chunkRows = fileRows.slice(startIndex, startIndex + chunkSize);
-      const code = chunkRows.map((row) => row.content).join("\n");
-      const tokenLines = highlighter.tokenize(code, { lang: file.language, theme });
-      const tokensByRowId: Record<string, ReadonlyArray<NativeReviewDiffToken>> = {};
-
-      chunkRows.forEach((row, rowIndex) => {
-        tokensByRowId[row.id] = tokenLines[rowIndex] ?? makePlainTokenFallback(row);
-      });
-
-      input.onChunk({
-        chunkIndex,
-        fileId: file.id,
-        filePath: file.path,
-        language: file.language,
-        lineCount: chunkRows.length,
-        durationMs: Math.round(performance.now() - startedAt),
-        tokensByRowId,
-      });
-
-      chunkIndex += 1;
-      await waitForNextFrame();
-    }
-  }
-
-  return highlighter.engine;
-}
diff --git a/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx b/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
index 2c3422673b00..ca8fd9c61415 100644
--- a/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
+++ b/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
@@ -48,7 +48,6 @@ import {
   NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED,
 } from "../layout/native-mail-search-toolbar";
 import { WorkspaceSidebarToolbar } from "../layout/workspace-sidebar-toolbar";
-import { ReviewHighlighterProvider } from "../review/ReviewHighlighterProvider";
 import { useAppearancePreferences } from "../settings/appearance/AppearancePreferencesProvider";
 import { ThreadRouteScreen } from "../threads/ThreadRouteScreen";
 import { FileMarkdownPreview } from "./FileMarkdownPreview";
@@ -823,123 +822,121 @@ export function ThreadFileScreen(props: ThreadFileRouteScreenProps) {
     : [projectName, parentDir].filter(Boolean).join(" · ");
 
   return (
-    <ReviewHighlighterProvider>
-      <View className="flex-1 bg-sheet">
-        <NativeStackScreenOptions
-          options={{
-            // Static header config lives in Stack.tsx (SOLID_HEADER_OPTIONS: solid
-            // sheet-colored header — this route's content scrolls internally, so
-            // there is nothing for glass to sample). Only dynamic values here.
-            headerShown: !isAndroid,
-            headerTintColor: iconColor,
-            headerTitle: basename(relativePath),
-            title: basename(relativePath),
-            unstable_headerSubtitle:
-              Platform.OS === "ios" && headerSubtitle.length > 0 ? headerSubtitle : undefined,
-          }}
+    <View className="flex-1 bg-sheet">
+      <NativeStackScreenOptions
+        options={{
+          // Static header config lives in Stack.tsx (SOLID_HEADER_OPTIONS: solid
+          // sheet-colored header — this route's content scrolls internally, so
+          // there is nothing for glass to sample). Only dynamic values here.
+          headerShown: !isAndroid,
+          headerTintColor: iconColor,
+          headerTitle: basename(relativePath),
+          title: basename(relativePath),
+          unstable_headerSubtitle:
+            Platform.OS === "ios" && headerSubtitle.length > 0 ? headerSubtitle : undefined,
+        }}
+      />
+      {isAndroid ? (
+        <AndroidScreenHeader
+          title={basename(relativePath)}
+          subtitle={headerSubtitle}
+          onBack={handleBack}
+          trailing={
+            <>
+              {fileInspector.supported ? (
+                <AndroidHeaderIconButton
+                  accessibilityLabel={
+                    panes.auxiliaryPaneVisible ? "Hide file navigator" : "Show file navigator"
+                  }
+                  icon="sidebar.right"
+                  onPress={toggleAuxiliaryPane}
+                />
+              ) : null}
+              <ControlPillMenu
+                actions={androidFileMenuActions}
+                isAnchoredToRight
+                title="File actions"
+                onPressAction={handleAndroidFileMenuAction}
+              >
+                <AndroidHeaderIconButton accessibilityLabel="File actions" icon="ellipsis" />
+              </ControlPillMenu>
+            </>
+          }
         />
-        {isAndroid ? (
-          <AndroidScreenHeader
-            title={basename(relativePath)}
-            subtitle={headerSubtitle}
-            onBack={handleBack}
-            trailing={
-              <>
-                {fileInspector.supported ? (
-                  <AndroidHeaderIconButton
-                    accessibilityLabel={
-                      panes.auxiliaryPaneVisible ? "Hide file navigator" : "Show file navigator"
-                    }
-                    icon="sidebar.right"
-                    onPress={toggleAuxiliaryPane}
-                  />
-                ) : null}
-                <ControlPillMenu
-                  actions={androidFileMenuActions}
-                  isAnchoredToRight
-                  title="File actions"
-                  onPressAction={handleAndroidFileMenuAction}
-                >
-                  <AndroidHeaderIconButton accessibilityLabel="File actions" icon="ellipsis" />
-                </ControlPillMenu>
-              </>
+      ) : null}
+      <WorkspaceSidebarToolbar>
+        {fileInspector.supported ? (
+          <NativeHeaderToolbar.Button
+            accessibilityLabel="Return to chat"
+            icon="chevron.left"
+            onPress={handleReturnToThread}
+          />
+        ) : null}
+      </WorkspaceSidebarToolbar>
+      <NativeHeaderToolbar placement="right">
+        {fileInspector.supported ? (
+          <NativeHeaderToolbar.Button
+            accessibilityLabel={
+              panes.auxiliaryPaneVisible ? "Hide file navigator" : "Show file navigator"
             }
+            icon="sidebar.right"
+            onPress={toggleAuxiliaryPane}
+            separateBackground
           />
         ) : null}
-        <WorkspaceSidebarToolbar>
-          {fileInspector.supported ? (
-            <NativeHeaderToolbar.Button
-              accessibilityLabel="Return to chat"
-              icon="chevron.left"
-              onPress={handleReturnToThread}
-            />
-          ) : null}
-        </WorkspaceSidebarToolbar>
-        <NativeHeaderToolbar placement="right">
-          {fileInspector.supported ? (
-            <NativeHeaderToolbar.Button
-              accessibilityLabel={
-                panes.auxiliaryPaneVisible ? "Hide file navigator" : "Show file navigator"
-              }
-              icon="sidebar.right"
-              onPress={toggleAuxiliaryPane}
-              separateBackground
-            />
+        <NativeHeaderToolbar.Menu accessibilityLabel="File actions" icon="ellipsis">
+          {fileMenuActions.some(({ inline }) => inline) ? (
+            <NativeHeaderToolbar.Menu inline>
+              {fileMenuActions
+                .filter(({ inline }) => inline)
+                .map((action) => (
+                  <NativeHeaderToolbar.MenuAction
+                    key={action.id}
+                    icon={action.icon}
+                    isOn={action.id === resolvedActiveMode}
+                    onPress={action.onPress}
+                  >
+                    {action.title}
+                  </NativeHeaderToolbar.MenuAction>
+                ))}
+            </NativeHeaderToolbar.Menu>
           ) : null}
-          <NativeHeaderToolbar.Menu accessibilityLabel="File actions" icon="ellipsis">
-            {fileMenuActions.some(({ inline }) => inline) ? (
-              <NativeHeaderToolbar.Menu inline>
-                {fileMenuActions
-                  .filter(({ inline }) => inline)
-                  .map((action) => (
-                    <NativeHeaderToolbar.MenuAction
-                      key={action.id}
-                      icon={action.icon}
-                      isOn={action.id === resolvedActiveMode}
-                      onPress={action.onPress}
-                    >
-                      {action.title}
-                    </NativeHeaderToolbar.MenuAction>
-                  ))}
-              </NativeHeaderToolbar.Menu>
-            ) : null}
-            {fileMenuActions
-              .filter(({ inline }) => !inline)
-              .map((action) => (
-                <NativeHeaderToolbar.MenuAction
-                  key={action.id}
-                  icon={action.icon}
-                  onPress={action.onPress}
-                >
-                  {action.title}
-                </NativeHeaderToolbar.MenuAction>
-              ))}
-          </NativeHeaderToolbar.Menu>
-        </NativeHeaderToolbar>
-        <FileContent
-          key={previewKey}
-          activeMode={resolvedActiveMode}
-          cwd={cwd}
-          environmentId={environmentId}
-          previewUri={previewUri}
-          previewFailure={assetPreview._tag === "Failure" ? assetPreview.reason : null}
-          onRetryPreview={handleRetryPreview}
-          videoSource={videoSource}
-          mediaSource={mediaSource}
-          resolveVideoUri={assetPreview.refresh}
-          fileContents={fileData?.contents ?? null}
-          fileError={fileQuery.error}
-          initialLine={targetLine}
-          relativePath={relativePath}
-          threadId={threadId}
-          truncated={fileData?.truncated ?? false}
-          onRefresh={() => fileQuery.refresh()}
-        />
-        <FilePreviewModal
-          source={fullScreenPreview}
-          onRequestClose={() => setFullScreenPreview(null)}
-        />
-      </View>
-    </ReviewHighlighterProvider>
+          {fileMenuActions
+            .filter(({ inline }) => !inline)
+            .map((action) => (
+              <NativeHeaderToolbar.MenuAction
+                key={action.id}
+                icon={action.icon}
+                onPress={action.onPress}
+              >
+                {action.title}
+              </NativeHeaderToolbar.MenuAction>
+            ))}
+        </NativeHeaderToolbar.Menu>
+      </NativeHeaderToolbar>
+      <FileContent
+        key={previewKey}
+        activeMode={resolvedActiveMode}
+        cwd={cwd}
+        environmentId={environmentId}
+        previewUri={previewUri}
+        previewFailure={assetPreview._tag === "Failure" ? assetPreview.reason : null}
+        onRetryPreview={handleRetryPreview}
+        videoSource={videoSource}
+        mediaSource={mediaSource}
+        resolveVideoUri={assetPreview.refresh}
+        fileContents={fileData?.contents ?? null}
+        fileError={fileQuery.error}
+        initialLine={targetLine}
+        relativePath={relativePath}
+        threadId={threadId}
+        truncated={fileData?.truncated ?? false}
+        onRefresh={() => fileQuery.refresh()}
+      />
+      <FilePreviewModal
+        source={fullScreenPreview}
+        onRequestClose={() => setFullScreenPreview(null)}
+      />
+    </View>
   );
 }
diff --git a/apps/mobile/src/features/files/fileTree.test.ts b/apps/mobile/src/features/files/fileTree.test.ts
index 7345a7f366c5..edab2ba687b8 100644
--- a/apps/mobile/src/features/files/fileTree.test.ts
+++ b/apps/mobile/src/features/files/fileTree.test.ts
@@ -1,13 +1,7 @@
 import { describe, expect, it } from "vite-plus/test";
 import type { ProjectEntry } from "@t3tools/contracts";
 
-import {
-  buildFileTree,
-  countFileNodes,
-  defaultExpandedTreePaths,
-  firstFilePath,
-  flattenFileTree,
-} from "./fileTree";
+import { buildFileTree, defaultExpandedTreePaths, flattenFileTree } from "./fileTree";
 
 const entries = [
   { kind: "file", path: "README.md" },
@@ -30,8 +24,6 @@ describe("mobile file tree helpers", () => {
       "directory:src/components",
       "file:src/index.ts",
     ]);
-    expect(countFileNodes(tree)).toBe(4);
-    expect(firstFilePath(tree)).toBe("src/components/App.tsx");
   });
 
   it("flattens expanded directories and hides collapsed descendants", () => {
diff --git a/apps/mobile/src/features/files/fileTree.ts b/apps/mobile/src/features/files/fileTree.ts
index 28b5822aaa0f..2e0b8140329c 100644
--- a/apps/mobile/src/features/files/fileTree.ts
+++ b/apps/mobile/src/features/files/fileTree.ts
@@ -117,18 +117,6 @@ export function buildFileTree(entries: ReadonlyArray<ProjectEntry>): ReadonlyArr
   return [...root.children.values()].sort(compareNodes).map(freezeNode);
 }
 
-export function countFileNodes(nodes: ReadonlyArray<FileTreeNode>): number {
-  let count = 0;
-  for (const node of nodes) {
-    if (node.kind === "file") {
-      count += 1;
-    } else {
-      count += countFileNodes(node.children);
-    }
-  }
-  return count;
-}
-
 export function defaultExpandedTreePaths(nodes: ReadonlyArray<FileTreeNode>): ReadonlySet<string> {
   const expanded = new Set<string>();
   for (const node of nodes) {
@@ -205,16 +193,3 @@ export function flattenFileTree(input: {
   }
   return output;
 }
-
-export function firstFilePath(nodes: ReadonlyArray<FileTreeNode>): string | null {
-  for (const node of nodes) {
-    if (node.kind === "file") {
-      return node.path;
-    }
-    const child = firstFilePath(node.children);
-    if (child !== null) {
-      return child;
-    }
-  }
-  return null;
-}
diff --git a/apps/mobile/src/features/files/nativeSourceFileAdapter.test.ts b/apps/mobile/src/features/files/nativeSourceFileAdapter.test.ts
index 0e7d478c6bdb..937d3a1d3c8f 100644
--- a/apps/mobile/src/features/files/nativeSourceFileAdapter.test.ts
+++ b/apps/mobile/src/features/files/nativeSourceFileAdapter.test.ts
@@ -3,30 +3,10 @@ import { describe, expect, it } from "vite-plus/test";
 import {
   buildNativeSourceRows,
   buildNativeSourceTokens,
-  NATIVE_SOURCE_ROW_HEIGHT,
-  NATIVE_SOURCE_STYLE,
   nativeSourceRowId,
 } from "./nativeSourceFileAdapter";
-import {
-  NATIVE_REVIEW_DIFF_ROW_HEIGHT,
-  NATIVE_REVIEW_DIFF_STYLE,
-} from "../review/nativeReviewDiffAdapter";
 
 describe("nativeSourceFileAdapter", () => {
-  it("uses the same compact code typography as the diff viewer", () => {
-    expect(NATIVE_SOURCE_ROW_HEIGHT).toBe(NATIVE_REVIEW_DIFF_ROW_HEIGHT);
-    expect(NATIVE_SOURCE_STYLE).toMatchObject({
-      rowHeight: NATIVE_REVIEW_DIFF_STYLE.rowHeight,
-      gutterWidth: NATIVE_REVIEW_DIFF_STYLE.gutterWidth,
-      codePadding: NATIVE_REVIEW_DIFF_STYLE.codePadding,
-      textVerticalInset: NATIVE_REVIEW_DIFF_STYLE.textVerticalInset,
-      codeFontSize: NATIVE_REVIEW_DIFF_STYLE.codeFontSize,
-      codeFontWeight: NATIVE_REVIEW_DIFF_STYLE.codeFontWeight,
-      lineNumberFontSize: NATIVE_REVIEW_DIFF_STYLE.lineNumberFontSize,
-      lineNumberFontWeight: NATIVE_REVIEW_DIFF_STYLE.lineNumberFontWeight,
-    });
-  });
-
   it("maps plain source lines onto context rows with stable line numbers", () => {
     expect(buildNativeSourceRows(["const value = 1;", "\treturn value;"])).toEqual([
       {
diff --git a/apps/mobile/src/features/files/nativeSourceFileAdapter.ts b/apps/mobile/src/features/files/nativeSourceFileAdapter.ts
index 0c83134ea703..f1dbefdc383b 100644
--- a/apps/mobile/src/features/files/nativeSourceFileAdapter.ts
+++ b/apps/mobile/src/features/files/nativeSourceFileAdapter.ts
@@ -4,17 +4,11 @@ import type {
   NativeReviewDiffToken,
 } from "../diffs/nativeReviewDiffSurface";
 import type { ResolvedMobileCodeSurface } from "../../lib/appearancePreferences";
-import { resolveMobileCodeSurface } from "../../lib/appearancePreferences";
 import { MOBILE_CODE_SURFACE, MOBILE_TYPOGRAPHY } from "../../lib/typography";
 import type { SourceHighlightTokens } from "./sourceHighlightingState";
 
-export const NATIVE_SOURCE_ROW_HEIGHT = MOBILE_CODE_SURFACE.rowHeight;
 export const NATIVE_SOURCE_CONTENT_WIDTH = 32_000;
 
-export const NATIVE_SOURCE_STYLE: NativeReviewDiffStyle = createNativeSourceStyle(
-  resolveMobileCodeSurface(MOBILE_CODE_SURFACE.fontSize),
-);
-
 export function createNativeSourceStyle(
   codeSurface: ResolvedMobileCodeSurface,
 ): NativeReviewDiffStyle {
diff --git a/apps/mobile/src/features/home/HomeScreen.tsx b/apps/mobile/src/features/home/HomeScreen.tsx
index c06cbcf1e913..4c41ce2bf150 100644
--- a/apps/mobile/src/features/home/HomeScreen.tsx
+++ b/apps/mobile/src/features/home/HomeScreen.tsx
@@ -61,6 +61,7 @@ import type { HomeListFilterMenuEnvironment } from "./home-list-filter-menu";
 import {
   buildHomeListLayout,
   DEFAULT_GROUP_DISPLAY_STATE,
+  EMPTY_HOME_LIST_LAYOUT,
   homeListItemsAreEqual,
   nextGroupDisplayState,
   type HomeGroupDisplayAction,
@@ -339,48 +340,57 @@ export function HomeScreen(props: HomeScreenProps) {
   );
   const scopedProjects = useMemo(
     () =>
-      selectedProjectRefKeys === null
-        ? props.projects
-        : props.projects.filter((project) =>
-            selectedProjectRefKeys.has(scopedProjectKey(project.environmentId, project.id)),
-          ),
-    [props.projects, selectedProjectRefKeys],
+      threadListV2Enabled
+        ? []
+        : selectedProjectRefKeys === null
+          ? props.projects
+          : props.projects.filter((project) =>
+              selectedProjectRefKeys.has(scopedProjectKey(project.environmentId, project.id)),
+            ),
+    [threadListV2Enabled, props.projects, selectedProjectRefKeys],
   );
   const scopedThreads = useMemo(
     () =>
-      selectedProjectRefKeys === null
-        ? props.threads
-        : props.threads.filter((thread) =>
-            selectedProjectRefKeys.has(scopedProjectKey(thread.environmentId, thread.projectId)),
-          ),
-    [props.threads, selectedProjectRefKeys],
+      threadListV2Enabled
+        ? []
+        : selectedProjectRefKeys === null
+          ? props.threads
+          : props.threads.filter((thread) =>
+              selectedProjectRefKeys.has(scopedProjectKey(thread.environmentId, thread.projectId)),
+            ),
+    [threadListV2Enabled, props.threads, selectedProjectRefKeys],
   );
   const scopedPendingTasks = useMemo(
     () =>
-      selectedProjectRefKeys === null
-        ? props.pendingTasks
-        : props.pendingTasks.filter((pendingTask) =>
-            selectedProjectRefKeys.has(
-              scopedProjectKey(pendingTask.message.environmentId, pendingTask.creation.projectId),
+      threadListV2Enabled
+        ? []
+        : selectedProjectRefKeys === null
+          ? props.pendingTasks
+          : props.pendingTasks.filter((pendingTask) =>
+              selectedProjectRefKeys.has(
+                scopedProjectKey(pendingTask.message.environmentId, pendingTask.creation.projectId),
+              ),
             ),
-          ),
-    [props.pendingTasks, selectedProjectRefKeys],
+    [threadListV2Enabled, props.pendingTasks, selectedProjectRefKeys],
   );
 
   const projectGroups = useMemo(
     () =>
-      buildHomeThreadGroups({
-        projects: scopedProjects,
-        threads: scopedThreads,
-        pendingTasks: scopedPendingTasks,
-        environmentId: props.selectedEnvironmentId,
-        searchQuery: props.searchQuery,
-        matchedThreadKeys,
-        projectSortOrder: props.projectSortOrder,
-        threadSortOrder: props.threadSortOrder,
-        projectGroupingMode: props.projectGroupingMode,
-      }),
+      threadListV2Enabled
+        ? []
+        : buildHomeThreadGroups({
+            projects: scopedProjects,
+            threads: scopedThreads,
+            pendingTasks: scopedPendingTasks,
+            environmentId: props.selectedEnvironmentId,
+            searchQuery: props.searchQuery,
+            matchedThreadKeys,
+            projectSortOrder: props.projectSortOrder,
+            threadSortOrder: props.threadSortOrder,
+            projectGroupingMode: props.projectGroupingMode,
+          }),
     [
+      threadListV2Enabled,
       props.projectGroupingMode,
       props.projectSortOrder,
       props.searchQuery,
@@ -396,12 +406,14 @@ export function HomeScreen(props: HomeScreenProps) {
   const hasSearchQuery = props.searchQuery.trim().length > 0;
   const listLayout = useMemo(
     () =>
-      buildHomeListLayout({
-        groups: projectGroups,
-        displayStates: effectiveGroupDisplayStates,
-        showAllThreads: hasSearchQuery,
-      }),
-    [projectGroups, effectiveGroupDisplayStates, hasSearchQuery],
+      threadListV2Enabled
+        ? EMPTY_HOME_LIST_LAYOUT
+        : buildHomeListLayout({
+            groups: projectGroups,
+            displayStates: effectiveGroupDisplayStates,
+            showAllThreads: hasSearchQuery,
+          }),
+    [threadListV2Enabled, projectGroups, effectiveGroupDisplayStates, hasSearchQuery],
   );
 
   const projectCwdByKey = useMemo(() => {
@@ -1033,7 +1045,7 @@ export function HomeScreen(props: HomeScreenProps) {
   // so the v1 check already covers v2.
   const hasAnyThreads =
     props.threads.some((thread) => thread.archivedAt === null) || props.pendingTasks.length > 0;
-  const hasResults = projectGroups.length > 0;
+  const hasResults = threadListV2Enabled ? threadListV2Items.length > 0 : projectGroups.length > 0;
   const selectedEnvironmentLabel =
     props.selectedEnvironmentId === null
       ? null
@@ -1097,10 +1109,8 @@ export function HomeScreen(props: HomeScreenProps) {
       <EmptyState title="No threads yet" detail="Create a task to start a new coding session." />
     )
   ) : null;
-  // Self-contained: v1's listEmpty keys off projectGroups, which ignores the
-  // v2 project scope, so it can be null (results elsewhere) while this list
-  // is empty. Snoozed threads need no special empty state: their shelf header
-  // is a list row even while collapsed.
+  // Use the v2 project scope for its empty state. Snoozed threads need no
+  // special empty state: their shelf header is a list row even while collapsed.
   const v2ListEmpty =
     hasSearchQuery && threadSearch.isPending ? null : hasSearchQuery ? (
       <EmptyState title="No results" detail={`No threads matching "${props.searchQuery}".`} />
diff --git a/apps/mobile/src/features/home/homeListItems.ts b/apps/mobile/src/features/home/homeListItems.ts
index eb3f2a5de199..6709a81e9d1e 100644
--- a/apps/mobile/src/features/home/homeListItems.ts
+++ b/apps/mobile/src/features/home/homeListItems.ts
@@ -62,6 +62,8 @@ export interface HomeListLayout {
   readonly stickyHeaderIndices: ReadonlyArray<number>;
 }
 
+export const EMPTY_HOME_LIST_LAYOUT: HomeListLayout = { items: [], stickyHeaderIndices: [] };
+
 export type HomeGroupDisplayAction = "toggle-collapsed" | "show-more" | "show-less";
 
 export function nextGroupDisplayState(
diff --git a/apps/mobile/src/features/home/workspace-connection-status.test.ts b/apps/mobile/src/features/home/workspace-connection-status.test.ts
index 15a990bb1cbe..f1af93316a6b 100644
--- a/apps/mobile/src/features/home/workspace-connection-status.test.ts
+++ b/apps/mobile/src/features/home/workspace-connection-status.test.ts
@@ -1,11 +1,7 @@
 import { describe, expect, it } from "vite-plus/test";
 
 import type { WorkspaceState } from "../../state/workspaceModel";
-import {
-  shouldShowWorkspaceConnectionStatus,
-  workspaceConnectionStatusLabel,
-  workspaceConnectionStatusPresentation,
-} from "./workspace-connection-status";
+import { workspaceConnectionStatusPresentation } from "./workspace-connection-status";
 
 function workspaceState(overrides: Partial<WorkspaceState> = {}): WorkspaceState {
   return {
@@ -27,14 +23,16 @@ function workspaceState(overrides: Partial<WorkspaceState> = {}): WorkspaceState
 
 describe("workspace connection status", () => {
   it("stays hidden while a ready environment is connected", () => {
-    expect(shouldShowWorkspaceConnectionStatus(workspaceState())).toBe(false);
+    expect(workspaceConnectionStatusPresentation(workspaceState())).toBeNull();
   });
 
   it("surfaces offline snapshots", () => {
     const state = workspaceState({ networkStatus: "offline", hasReadyEnvironment: false });
 
-    expect(shouldShowWorkspaceConnectionStatus(state)).toBe(true);
-    expect(workspaceConnectionStatusLabel(state)).toBe("You are offline");
+    expect(workspaceConnectionStatusPresentation(state)).toEqual({
+      label: "You are offline",
+      showsProgress: false,
+    });
   });
 
   it("names the environment while reconnecting", () => {
@@ -54,8 +52,10 @@ describe("workspace connection status", () => {
       ],
     });
 
-    expect(shouldShowWorkspaceConnectionStatus(state)).toBe(true);
-    expect(workspaceConnectionStatusLabel(state)).toBe("Reconnecting to Julius’s Mac mini");
+    expect(workspaceConnectionStatusPresentation(state)).toEqual({
+      label: "Reconnecting to Julius’s Mac mini",
+      showsProgress: true,
+    });
   });
 
   it("surfaces connection errors before the generic disconnected fallback", () => {
@@ -65,15 +65,19 @@ describe("workspace connection status", () => {
       hasReadyEnvironment: false,
     });
 
-    expect(shouldShowWorkspaceConnectionStatus(state)).toBe(true);
-    expect(workspaceConnectionStatusLabel(state)).toBe("Could not reach Julius’s Mac mini");
+    expect(workspaceConnectionStatusPresentation(state)).toEqual({
+      label: "Could not reach Julius’s Mac mini",
+      showsProgress: false,
+    });
   });
 
   it("shows shell catch-up while cached threads remain visible", () => {
     const state = workspaceState({ hasPendingShellSnapshot: true });
 
-    expect(shouldShowWorkspaceConnectionStatus(state)).toBe(true);
-    expect(workspaceConnectionStatusLabel(state)).toBe("Syncing threads...");
+    expect(workspaceConnectionStatusPresentation(state)).toEqual({
+      label: "Syncing threads...",
+      showsProgress: true,
+    });
   });
 
   it("distinguishes initial shell loading from cached catch-up", () => {
@@ -82,39 +86,9 @@ describe("workspace connection status", () => {
       hasPendingShellSnapshot: true,
     });
 
-    expect(shouldShowWorkspaceConnectionStatus(state)).toBe(true);
-    expect(workspaceConnectionStatusLabel(state)).toBe("Loading threads...");
-  });
-
-  it("presents nothing while connected", () => {
-    expect(workspaceConnectionStatusPresentation(workspaceState())).toBeNull();
-  });
-
-  it("presents progress while reconnecting but not while offline", () => {
-    const reconnecting = workspaceState({
-      hasConnectingEnvironment: true,
-      hasReadyEnvironment: false,
-      connectingEnvironments: [
-        {
-          environmentId: "environment-1" as never,
-          environmentLabel: "Julius’s Mac mini",
-          displayUrl: "",
-          isRelayManaged: false,
-          connectionState: "reconnecting",
-          connectionError: null,
-          connectionErrorTraceId: null,
-        },
-      ],
-    });
-    expect(workspaceConnectionStatusPresentation(reconnecting)).toEqual({
-      label: "Reconnecting to Julius’s Mac mini",
+    expect(workspaceConnectionStatusPresentation(state)).toEqual({
+      label: "Loading threads...",
       showsProgress: true,
     });
-
-    const offline = workspaceState({ networkStatus: "offline", hasReadyEnvironment: false });
-    expect(workspaceConnectionStatusPresentation(offline)).toEqual({
-      label: "You are offline",
-      showsProgress: false,
-    });
   });
 });
diff --git a/apps/mobile/src/features/home/workspace-connection-status.ts b/apps/mobile/src/features/home/workspace-connection-status.ts
index 6f9898b1bb01..d45a46adf933 100644
--- a/apps/mobile/src/features/home/workspace-connection-status.ts
+++ b/apps/mobile/src/features/home/workspace-connection-status.ts
@@ -6,7 +6,7 @@ export interface WorkspaceConnectionStatusPresentation {
   readonly showsProgress: boolean;
 }
 
-export function shouldShowWorkspaceConnectionStatus(state: WorkspaceState): boolean {
+function shouldShowWorkspaceConnectionStatus(state: WorkspaceState): boolean {
   return (
     state.networkStatus === "offline" ||
     state.connectionError !== null ||
@@ -16,7 +16,7 @@ export function shouldShowWorkspaceConnectionStatus(state: WorkspaceState): bool
   );
 }
 
-export function workspaceConnectionStatusLabel(state: WorkspaceState): string {
+function workspaceConnectionStatusLabel(state: WorkspaceState): string {
   if (state.networkStatus === "offline") return "You are offline";
   if (state.connectingEnvironments.length === 1) {
     return `Reconnecting to ${state.connectingEnvironments[0]!.environmentLabel}`;
diff --git a/apps/mobile/src/features/review/ReviewHighlighterProvider.tsx b/apps/mobile/src/features/review/ReviewHighlighterProvider.tsx
deleted file mode 100644
index e35367b74719..000000000000
--- a/apps/mobile/src/features/review/ReviewHighlighterProvider.tsx
+++ /dev/null
@@ -1,20 +0,0 @@
-import { createContext, type ReactNode, useMemo } from "react";
-
-import { type ReviewHighlighterState, useReviewHighlighterState } from "./reviewHighlighterState";
-
-const ReviewHighlighterContext = createContext<ReviewHighlighterState>({
-  engine: null,
-  error: null,
-  status: "idle",
-});
-
-export function ReviewHighlighterProvider(props: { readonly children: ReactNode }) {
-  const value = useReviewHighlighterState();
-  const contextValue = useMemo(() => value, [value]);
-
-  return (
-    <ReviewHighlighterContext.Provider value={contextValue}>
-      {props.children}
-    </ReviewHighlighterContext.Provider>
-  );
-}
diff --git a/apps/mobile/src/features/review/nativeReviewDiffAdapter.test.ts b/apps/mobile/src/features/review/nativeReviewDiffAdapter.test.ts
index 3a291b2e788a..ffc4a71f7a1f 100644
--- a/apps/mobile/src/features/review/nativeReviewDiffAdapter.test.ts
+++ b/apps/mobile/src/features/review/nativeReviewDiffAdapter.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vite-plus/test";
+import { describe, expect, it, vi } from "vite-plus/test";
 import {
   DEFAULT_MOBILE_THEME_ID,
   getMobileThemeVariables,
@@ -9,12 +9,14 @@ import {
 import { readDefaultMobileThemeVariables } from "../../lib/mobileTheme.test-support";
 
 import {
+  buildNativeReviewDiffData,
   createNativeReviewDiffTheme,
   getCachedNativeReviewDiffData,
   type BuildNativeReviewDiffDataInput,
 } from "./nativeReviewDiffAdapter";
 import type { ReviewInlineComment } from "./reviewCommentSelection";
 import { buildReviewParsedDiff } from "./reviewModel";
+import * as ReviewWordDiffs from "./reviewWordDiffs";
 
 const parsedDiff = buildReviewParsedDiff(
   [
@@ -46,6 +48,23 @@ function buildInput(comments: BuildNativeReviewDiffDataInput["comments"]) {
   return { parsedDiff, comments } satisfies BuildNativeReviewDiffDataInput;
 }
 
+function filesPatch(paths: ReadonlyArray<string>) {
+  return paths
+    .map((path) =>
+      [
+        `diff --git a/${path} b/${path}`,
+        `--- a/${path}`,
+        `+++ b/${path}`,
+        "@@ -1,2 +1,2 @@",
+        '-const first = renderPanel({ label: "before", enabled: true });',
+        '-const second = renderPanel({ label: "before", enabled: true });',
+        '+const first = renderPanel({ label: "after", enabled: true });',
+        '+const second = renderPanel({ label: "after", enabled: true });',
+      ].join("\n"),
+    )
+    .join("\n");
+}
+
 function appTheme(themeId: MobileThemeId, appearance: MobileThemeAppearance) {
   return themeId === DEFAULT_MOBILE_THEME_ID
     ? readDefaultMobileThemeVariables(appearance)
@@ -67,6 +86,107 @@ describe("getCachedNativeReviewDiffData", () => {
 
     expect(equivalent).toBe(first);
     expect(changed).not.toBe(first);
+    expect(changed.rows.find((row) => row.kind === "comment")?.commentText).toBe("Changed");
+  });
+
+  it("reuses source rows and word matching when a file comment changes", () => {
+    const diff = buildReviewParsedDiff(filesPatch(["example.ts", "second.ts"]), "comment-reuse");
+    const matchWords = vi.spyOn(ReviewWordDiffs, "computeWordAltDiffRanges");
+    try {
+      const base = getCachedNativeReviewDiffData({ parsedDiff: diff });
+      expect(matchWords).toHaveBeenCalledTimes(4);
+      expect(base.rows.filter((row) => row.wordDiffRanges?.length)).toHaveLength(8);
+      const firstComment = makeComment("First file comment");
+      const secondComment = {
+        ...makeComment("Second file comment"),
+        id: "comment-2",
+        filePath: "second.ts",
+      };
+      const first = getCachedNativeReviewDiffData({
+        parsedDiff: diff,
+        comments: [firstComment, secondComment],
+      });
+      const changed = getCachedNativeReviewDiffData({
+        parsedDiff: diff,
+        comments: [{ ...firstComment, text: "Changed first comment" }, secondComment],
+      });
+
+      expect(matchWords).toHaveBeenCalledTimes(4);
+      expect(changed.files).toBe(base.files);
+      expect(changed.commentTargetsByRowId).toBe(base.commentTargetsByRowId);
+      expect(changed.rowIdByCommentLineId).toBe(base.rowIdByCommentLineId);
+      expect(changed.rows.find((row) => row.id === secondComment.id)).toBe(
+        first.rows.find((row) => row.id === secondComment.id),
+      );
+      const sourceRows = changed.rows.filter((row) => row.kind !== "comment");
+      for (const [index, row] of sourceRows.entries()) {
+        expect(row).toBe(base.rows[index]);
+      }
+      const removed = getCachedNativeReviewDiffData({ parsedDiff: diff, comments: [] });
+      expect(removed.rows).toEqual(base.rows);
+      expect(matchWords).toHaveBeenCalledTimes(4);
+      expect(first.rows.find((row) => row.id === firstComment.id)?.commentText).toBe(
+        "First file comment",
+      );
+    } finally {
+      matchWords.mockRestore();
+    }
+  });
+
+  it("updates comment titles and locations without changing source coordinates", () => {
+    const diff = buildReviewParsedDiff(filesPatch(["example.ts", "second.ts"]), "comment-metadata");
+    const comment = makeComment("Review this line");
+    const first = getCachedNativeReviewDiffData({ parsedDiff: diff, comments: [comment] });
+    const renamed = getCachedNativeReviewDiffData({
+      parsedDiff: diff,
+      comments: [{ ...comment, sectionTitle: "Branch comparison" }],
+    });
+    expect(renamed.rows.find((row) => row.id === comment.id)?.commentSectionTitle).toBe(
+      "Branch comparison",
+    );
+    const moved = getCachedNativeReviewDiffData({
+      parsedDiff: diff,
+      comments: [{ ...comment, filePath: "second.ts", endIndex: 99, rangeLabel: "+2" }],
+    });
+    const commentIndex = moved.rows.findIndex((row) => row.id === comment.id);
+    expect(moved.rows[commentIndex]).toMatchObject({
+      kind: "comment",
+      filePath: "second.ts",
+      commentRangeLabel: "+2",
+    });
+    expect(moved.rows[commentIndex - 1]).toMatchObject({
+      kind: "line",
+      change: "add",
+      newLineNumber: 2,
+    });
+    expect(moved.rows.filter((row) => row.kind !== "comment")).toEqual(
+      first.rows.filter((row) => row.kind !== "comment"),
+    );
+    expect(first.rows.find((row) => row.id === comment.id)?.commentSectionTitle).toBe(
+      "Dirty worktree",
+    );
+  });
+
+  it("keeps cached IDs and targets local to each parsed section and file layout", () => {
+    const original = filesPatch(["example.ts", "second.ts"]);
+    const variants = [
+      buildReviewParsedDiff(original, "first-section"),
+      buildReviewParsedDiff(original, "second-section"),
+      buildReviewParsedDiff(
+        filesPatch(["inserted.ts", "example.ts", "second.ts"]),
+        "first-section",
+      ),
+      buildReviewParsedDiff(filesPatch(["second.ts", "example.ts"]), "first-section"),
+      buildReviewParsedDiff(filesPatch(["example.ts"]), "first-section"),
+      buildReviewParsedDiff(
+        original.replaceAll("@@ -1,2 +1,2 @@", "@@ -7,2 +12,2 @@"),
+        "first-section",
+      ),
+    ];
+    for (const diff of [...variants, variants[0]!]) {
+      const input = { parsedDiff: diff, comments: [makeComment("Coordinates")] };
+      expect(getCachedNativeReviewDiffData(input)).toEqual(buildNativeReviewDiffData(input));
+    }
   });
 });
 
diff --git a/apps/mobile/src/features/review/nativeReviewDiffAdapter.ts b/apps/mobile/src/features/review/nativeReviewDiffAdapter.ts
index a45a955d331f..39b9c0cef26e 100644
--- a/apps/mobile/src/features/review/nativeReviewDiffAdapter.ts
+++ b/apps/mobile/src/features/review/nativeReviewDiffAdapter.ts
@@ -6,8 +6,6 @@ import type {
 import * as Arr from "effect/Array";
 import { pipe } from "effect/Function";
 import type { ResolvedMobileCodeSurface } from "../../lib/appearancePreferences";
-import { resolveMobileCodeSurface } from "../../lib/appearancePreferences";
-import { MOBILE_CODE_SURFACE } from "../../lib/typography";
 import { type MobileThemeId, type MobileThemeVariables } from "../../lib/mobileTheme";
 import { getMobileTerminalTheme, type TerminalAppearanceScheme } from "../terminal/terminalTheme";
 import { computeWordAltDiffRanges } from "./reviewWordDiffs";
@@ -25,13 +23,8 @@ const NATIVE_HEX_COLOR = /^#([\da-f]{2})([\da-f]{2})([\da-f]{2})$/i;
 const NATIVE_RGBA_COLOR =
   /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)$/;
 
-export const NATIVE_REVIEW_DIFF_ROW_HEIGHT = MOBILE_CODE_SURFACE.rowHeight;
 export const NATIVE_REVIEW_DIFF_CONTENT_WIDTH = 2_800;
 
-export const NATIVE_REVIEW_DIFF_STYLE = createNativeReviewDiffStyle(
-  resolveMobileCodeSurface(MOBILE_CODE_SURFACE.fontSize),
-);
-
 function opaqueNativeHexColor(color: string, background: string): string {
   const hex = NATIVE_HEX_COLOR.exec(color);
   if (hex) return color;
@@ -105,10 +98,26 @@ export interface BuildNativeReviewDiffDataInput {
 }
 
 interface CachedNativeReviewDiffData {
+  readonly prepared: PreparedNativeReviewDiffData;
   readonly commentsKey: string;
   readonly data: NativeReviewDiffData;
 }
 
+interface PreparedNativeReviewFileRows {
+  readonly fileId: string;
+  readonly filePath: string;
+  readonly lineCount: number;
+  readonly rows: ReadonlyArray<NativeReviewDiffRow>;
+  commentedRows: {
+    readonly commentsKey: string;
+    readonly rows: ReadonlyArray<NativeReviewDiffRow>;
+  } | null;
+}
+
+interface PreparedNativeReviewDiffData extends Omit<NativeReviewDiffData, "rows"> {
+  readonly fileRows: ReadonlyArray<PreparedNativeReviewFileRows>;
+}
+
 const nativeReviewDiffDataCache = new WeakMap<ReviewParsedDiff, CachedNativeReviewDiffData>();
 
 function buildReviewCommentsCacheKey(comments: ReadonlyArray<ReviewInlineComment>): string {
@@ -116,19 +125,18 @@ function buildReviewCommentsCacheKey(comments: ReadonlyArray<ReviewInlineComment
     return "none";
   }
 
-  return comments
-    .map((comment) =>
-      [
-        comment.id,
-        comment.sectionId,
-        comment.filePath,
-        comment.startIndex,
-        comment.endIndex,
-        comment.rangeLabel,
-        comment.text,
-      ].join("\u001f"),
-    )
-    .join("\u001e");
+  return JSON.stringify(
+    comments.map((comment) => [
+      comment.id,
+      comment.sectionId,
+      comment.sectionTitle,
+      comment.filePath,
+      comment.startIndex,
+      comment.endIndex,
+      comment.rangeLabel,
+      comment.text,
+    ]),
+  );
 }
 
 export function createNativeReviewDiffTheme(
@@ -378,12 +386,11 @@ function mapLineRow(
   };
 }
 
-function mapFileRows(
+function prepareFileRows(
   file: ReviewRenderableFile,
-  comments: ReadonlyArray<ReviewInlineComment>,
   commentTargetsByRowId: Map<string, NativeReviewDiffCommentTarget>,
   rowIdByCommentLineId: Map<string, string>,
-): ReadonlyArray<NativeReviewDiffRow> {
+): PreparedNativeReviewFileRows {
   const rows: NativeReviewDiffRow[] = [
     {
       kind: "file",
@@ -398,22 +405,6 @@ function mapFileRows(
   ];
 
   const lineRows = file.rows.filter((row): row is ReviewRenderableLineRow => row.kind === "line");
-  const commentsByEndIndex = new Map<number, ReviewInlineComment[]>();
-  comments.forEach((comment) => {
-    if (comment.filePath !== file.path) {
-      return;
-    }
-    const endIndex = Math.min(comment.endIndex, lineRows.length - 1);
-    if (endIndex < 0) {
-      return;
-    }
-    const existing = commentsByEndIndex.get(endIndex);
-    if (existing) {
-      existing.push(comment);
-      return;
-    }
-    commentsByEndIndex.set(endIndex, [comment]);
-  });
   let lineIndex = 0;
   file.rows.forEach((row, rowIndex) => {
     if (row.kind === "hunk") {
@@ -434,37 +425,70 @@ function mapFileRows(
       lines: lineRows,
       lineIndex,
     });
-    const commentsForLine = commentsByEndIndex.get(lineIndex) ?? [];
-    for (const comment of commentsForLine) {
+    lineIndex += 1;
+  });
+
+  rows.push(...noticeRowsForFile(file));
+  return {
+    fileId: file.id,
+    filePath: file.path,
+    lineCount: lineRows.length,
+    // Comments must not split the source deletion/addition runs used for word matching.
+    rows: addNativeWordDiffRanges(rows),
+    commentedRows: null,
+  };
+}
+
+function insertFileComments(
+  file: PreparedNativeReviewFileRows,
+  comments: ReadonlyArray<ReviewInlineComment>,
+): ReadonlyArray<NativeReviewDiffRow> {
+  if (comments.length === 0) {
+    file.commentedRows = null;
+    return file.rows;
+  }
+  const commentsKey = buildReviewCommentsCacheKey(comments);
+  if (file.commentedRows?.commentsKey === commentsKey) {
+    return file.commentedRows.rows;
+  }
+
+  const commentsByEndIndex = new Map<number, ReviewInlineComment[]>();
+  for (const comment of comments) {
+    const endIndex = Math.min(comment.endIndex, file.lineCount - 1);
+    if (endIndex < 0) continue;
+    const existing = commentsByEndIndex.get(endIndex);
+    if (existing) {
+      existing.push(comment);
+    } else {
+      commentsByEndIndex.set(endIndex, [comment]);
+    }
+  }
+  const rows: NativeReviewDiffRow[] = [];
+  let lineIndex = 0;
+  for (const row of file.rows) {
+    rows.push(row);
+    if (row.kind !== "line") continue;
+    for (const comment of commentsByEndIndex.get(lineIndex) ?? []) {
       rows.push({
         kind: "comment",
         id: comment.id,
-        fileId: file.id,
-        filePath: file.path,
+        fileId: file.fileId,
+        filePath: file.filePath,
         commentText: comment.text,
         commentRangeLabel: comment.rangeLabel,
         commentSectionTitle: comment.sectionTitle,
       });
     }
     lineIndex += 1;
-  });
-
-  rows.push(...noticeRowsForFile(file));
+  }
+  file.commentedRows = { commentsKey, rows };
   return rows;
 }
 
-export function buildNativeReviewDiffData(
-  input: BuildNativeReviewDiffDataInput,
-): NativeReviewDiffData;
-export function buildNativeReviewDiffData(parsedDiff: ReviewParsedDiff): NativeReviewDiffData;
-export function buildNativeReviewDiffData(
-  input: ReviewParsedDiff | BuildNativeReviewDiffDataInput,
-): NativeReviewDiffData {
-  const parsedDiff = "parsedDiff" in input ? input.parsedDiff : input;
-  const comments = "parsedDiff" in input ? (input.comments ?? []) : [];
+function prepareNativeReviewDiffData(parsedDiff: ReviewParsedDiff): PreparedNativeReviewDiffData {
   if (parsedDiff.kind !== "files") {
     return {
-      rows: [],
+      fileRows: [],
       files: [],
       commentTargetsByRowId: new Map(),
       rowIdByCommentLineId: new Map(),
@@ -482,14 +506,12 @@ export function buildNativeReviewDiffData(
   }));
   const commentTargetsByRowId = new Map<string, NativeReviewDiffCommentTarget>();
   const rowIdByCommentLineId = new Map<string, string>();
-  const rows = addNativeWordDiffRanges(
-    Arr.flatMap(parsedDiff.files, (file) =>
-      mapFileRows(file, comments, commentTargetsByRowId, rowIdByCommentLineId),
-    ),
+  const fileRows = parsedDiff.files.map((file) =>
+    prepareFileRows(file, commentTargetsByRowId, rowIdByCommentLineId),
   );
 
   return {
-    rows,
+    fileRows,
     files,
     commentTargetsByRowId,
     rowIdByCommentLineId,
@@ -498,10 +520,47 @@ export function buildNativeReviewDiffData(
   };
 }
 
+function buildCommentedNativeReviewDiffData(
+  prepared: PreparedNativeReviewDiffData,
+  comments: ReadonlyArray<ReviewInlineComment>,
+): NativeReviewDiffData {
+  const commentsByFilePath = new Map<string, ReviewInlineComment[]>();
+  for (const comment of comments) {
+    const existing = commentsByFilePath.get(comment.filePath);
+    if (existing) {
+      existing.push(comment);
+    } else {
+      commentsByFilePath.set(comment.filePath, [comment]);
+    }
+  }
+  return {
+    rows: Arr.flatMap(prepared.fileRows, (file) =>
+      insertFileComments(file, commentsByFilePath.get(file.filePath) ?? []),
+    ),
+    files: prepared.files,
+    commentTargetsByRowId: prepared.commentTargetsByRowId,
+    rowIdByCommentLineId: prepared.rowIdByCommentLineId,
+    additions: prepared.additions,
+    deletions: prepared.deletions,
+  };
+}
+
+export function buildNativeReviewDiffData(
+  input: BuildNativeReviewDiffDataInput,
+): NativeReviewDiffData;
+export function buildNativeReviewDiffData(parsedDiff: ReviewParsedDiff): NativeReviewDiffData;
+export function buildNativeReviewDiffData(
+  input: ReviewParsedDiff | BuildNativeReviewDiffDataInput,
+): NativeReviewDiffData {
+  const parsedDiff = "parsedDiff" in input ? input.parsedDiff : input;
+  const comments = "parsedDiff" in input ? (input.comments ?? []) : [];
+  return buildCommentedNativeReviewDiffData(prepareNativeReviewDiffData(parsedDiff), comments);
+}
+
 /**
- * Reuses the expensive flattened native row model across React development
- * render probes and unrelated draft updates. Only the latest comment version
- * is retained for each parsed diff so editing a comment cannot grow the cache.
+ * Prepares source rows once per parsed diff, including its section-specific IDs.
+ * Comment edits reuse those rows, word ranges, and targets. Each file retains
+ * only its latest comment overlay, and the weak key releases old parsed diffs.
  */
 export function getCachedNativeReviewDiffData(
   input: BuildNativeReviewDiffDataInput,
@@ -513,10 +572,8 @@ export function getCachedNativeReviewDiffData(
     return cached.data;
   }
 
-  const data = buildNativeReviewDiffData({
-    parsedDiff: input.parsedDiff,
-    comments,
-  });
-  nativeReviewDiffDataCache.set(input.parsedDiff, { commentsKey, data });
+  const prepared = cached?.prepared ?? prepareNativeReviewDiffData(input.parsedDiff);
+  const data = buildCommentedNativeReviewDiffData(prepared, comments);
+  nativeReviewDiffDataCache.set(input.parsedDiff, { prepared, commentsKey, data });
   return data;
 }
diff --git a/apps/mobile/src/features/review/reviewDiffBridgeKeys.test.ts b/apps/mobile/src/features/review/reviewDiffBridgeKeys.test.ts
index 9b39a51dc90f..406665def071 100644
--- a/apps/mobile/src/features/review/reviewDiffBridgeKeys.test.ts
+++ b/apps/mobile/src/features/review/reviewDiffBridgeKeys.test.ts
@@ -1,9 +1,9 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { buildNativeReviewTokensResetKey, hashReviewDiffKey } from "./reviewDiffBridgeKeys";
+import { buildNativeReviewTokensResetKey } from "./reviewDiffBridgeKeys";
 
 describe("native review diff bridge", () => {
-  it("builds stable reset keys from the rendered diff identity", () => {
+  it("changes reset keys when the rendered diff identity changes", () => {
     const input = {
       threadKey: "env:thread",
       sectionId: "turn:2",
@@ -13,15 +13,12 @@ describe("native review diff bridge", () => {
       rowCount: 4,
     };
 
-    expect(buildNativeReviewTokensResetKey(input)).toBe(buildNativeReviewTokensResetKey(input));
-    expect(buildNativeReviewTokensResetKey({ ...input, rowCount: 5 })).not.toBe(
-      buildNativeReviewTokensResetKey(input),
-    );
-    expect(buildNativeReviewTokensResetKey({ ...input, diff: null })).toContain(":empty:");
-  });
+    const resetKey = buildNativeReviewTokensResetKey(input);
 
-  it("includes diff length in the hash key to reduce accidental collisions", () => {
-    expect(hashReviewDiffKey("abc")).toMatch(/^3:/);
-    expect(hashReviewDiffKey("abcd")).toMatch(/^4:/);
+    expect(
+      buildNativeReviewTokensResetKey({ ...input, diff: "diff --git a/b.ts b/b.ts" }),
+    ).not.toBe(resetKey);
+    expect(buildNativeReviewTokensResetKey({ ...input, rowCount: 5 })).not.toBe(resetKey);
+    expect(buildNativeReviewTokensResetKey({ ...input, diff: null })).not.toBe(resetKey);
   });
 });
diff --git a/apps/mobile/src/features/review/reviewDiffBridgeKeys.ts b/apps/mobile/src/features/review/reviewDiffBridgeKeys.ts
index d04534003b37..6c7c1e545785 100644
--- a/apps/mobile/src/features/review/reviewDiffBridgeKeys.ts
+++ b/apps/mobile/src/features/review/reviewDiffBridgeKeys.ts
@@ -3,7 +3,7 @@ import type { NativeReviewDiffHighlightScheme } from "../diffs/nativeReviewDiffH
 // Pure key-derivation helpers for the native review diff bridge. Kept free of
 // react-native / hook imports so they stay unit-testable in node.
 
-export function hashReviewDiffKey(diff: string | null | undefined): string {
+function hashReviewDiffKey(diff: string | null | undefined): string {
   if (!diff) {
     return "empty";
   }
diff --git a/apps/mobile/src/features/review/reviewFileVisibility.test.ts b/apps/mobile/src/features/review/reviewFileVisibility.test.ts
index 4a7a2f98af62..8fec1cbf8bd5 100644
--- a/apps/mobile/src/features/review/reviewFileVisibility.test.ts
+++ b/apps/mobile/src/features/review/reviewFileVisibility.test.ts
@@ -1,7 +1,6 @@
 import { describe, expect, it } from "vite-plus/test";
 
 import {
-  getDefaultReviewExpandedFileIds,
   getValidExplicitReviewFileIds,
   getValidReviewFileIds,
   removeReviewFileId,
@@ -29,7 +28,6 @@ describe("review file visibility", () => {
   const files = [makeFile("a.ts"), makeFile("b.ts")];
 
   it("defaults expanded files to every renderable file", () => {
-    expect(getDefaultReviewExpandedFileIds(files)).toEqual(["a.ts", "b.ts"]);
     expect(getValidReviewFileIds(files, undefined)).toEqual(["a.ts", "b.ts"]);
   });
 
diff --git a/apps/mobile/src/features/review/reviewFileVisibility.ts b/apps/mobile/src/features/review/reviewFileVisibility.ts
index 53f2d7f5f956..fbdfcf230225 100644
--- a/apps/mobile/src/features/review/reviewFileVisibility.ts
+++ b/apps/mobile/src/features/review/reviewFileVisibility.ts
@@ -3,7 +3,7 @@ import { useCallback, useMemo } from "react";
 import { updateReviewExpandedFileIds, updateReviewViewedFileIds } from "./reviewState";
 import type { ReviewRenderableFile } from "./reviewModel";
 
-export function getDefaultReviewExpandedFileIds(
+function getDefaultReviewExpandedFileIds(
   files: ReadonlyArray<ReviewRenderableFile>,
 ): ReadonlyArray<string> {
   return files.map((file) => file.id);
diff --git a/apps/mobile/src/features/review/reviewHighlighterState.test.ts b/apps/mobile/src/features/review/reviewHighlighterState.test.ts
deleted file mode 100644
index 9cc43d07f2af..000000000000
--- a/apps/mobile/src/features/review/reviewHighlighterState.test.ts
+++ /dev/null
@@ -1,90 +0,0 @@
-import { assert, beforeEach, it } from "vite-plus/test";
-import { AtomRegistry } from "effect/unstable/reactivity";
-
-import {
-  createReviewHighlighterManager,
-  IDLE_REVIEW_HIGHLIGHTER_STATE,
-} from "./reviewHighlighterState";
-
-let registry = AtomRegistry.make();
-
-beforeEach(() => {
-  registry.dispose();
-  registry = AtomRegistry.make();
-});
-
-function flushAsyncWork(): Promise<void> {
-  return Promise.resolve().then(() => undefined);
-}
-
-it("initializes review highlighter state once", async () => {
-  let prepareCalls = 0;
-  let languageCalls = 0;
-  let engineCalls = 0;
-  const manager = createReviewHighlighterManager({
-    getRegistry: () => registry,
-    loader: {
-      prepare: async () => {
-        prepareCalls += 1;
-      },
-      prepareLanguages: async () => {
-        languageCalls += 1;
-      },
-      getEngine: async () => {
-        engineCalls += 1;
-        return "javascript";
-      },
-    },
-  });
-
-  assert.deepStrictEqual(manager.getSnapshot(), IDLE_REVIEW_HIGHLIGHTER_STATE);
-
-  await Promise.all([manager.initialize(), manager.initialize()]);
-  await manager.initialize();
-
-  assert.strictEqual(prepareCalls, 1);
-  assert.strictEqual(languageCalls, 1);
-  assert.strictEqual(engineCalls, 1);
-  assert.deepStrictEqual(manager.getSnapshot(), {
-    engine: "javascript",
-    error: null,
-    status: "ready",
-  });
-});
-
-it("stores initialization failures in atom state", async () => {
-  const cause = new Error("load failed");
-  const manager = createReviewHighlighterManager({
-    getRegistry: () => registry,
-    loader: {
-      prepare: async () => {
-        throw cause;
-      },
-      prepareLanguages: async () => undefined,
-      getEngine: async () => "javascript",
-    },
-  });
-
-  void manager.initialize();
-  await flushAsyncWork();
-
-  const snapshot = manager.getSnapshot();
-  assert.strictEqual(snapshot.engine, null);
-  assert.strictEqual(snapshot.status, "error");
-  assert.strictEqual(snapshot.error?._tag, "ReviewHighlighterManagerError");
-  assert.strictEqual(snapshot.error?.operation, "prepare");
-  assert.deepStrictEqual(snapshot.error?.languages, [
-    "typescript",
-    "tsx",
-    "javascript",
-    "jsx",
-    "json",
-    "yaml",
-    "bash",
-  ]);
-  assert.strictEqual(snapshot.error?.cause, cause);
-  assert.strictEqual(
-    snapshot.error?.message,
-    "Review highlighter operation prepare failed for languages typescript, tsx, javascript, jsx, json, yaml, bash.",
-  );
-});
diff --git a/apps/mobile/src/features/review/reviewHighlighterState.ts b/apps/mobile/src/features/review/reviewHighlighterState.ts
deleted file mode 100644
index 51b20bb07ff6..000000000000
--- a/apps/mobile/src/features/review/reviewHighlighterState.ts
+++ /dev/null
@@ -1,179 +0,0 @@
-import { useAtomValue } from "@effect/atom-react";
-import * as Schema from "effect/Schema";
-import { Atom, type AtomRegistry } from "effect/unstable/reactivity";
-import { useEffect } from "react";
-
-import { appAtomRegistry } from "../../state/atom-registry";
-import {
-  getActiveReviewHighlighterEngine,
-  prepareReviewHighlighter,
-  prepareReviewHighlighterLanguages,
-  type ReviewHighlighterEngine,
-} from "./shikiReviewHighlighter";
-
-export type ReviewHighlighterStatus = "idle" | "initializing" | "ready" | "error";
-
-export class ReviewHighlighterManagerError extends Schema.TaggedErrorClass<ReviewHighlighterManagerError>()(
-  "ReviewHighlighterManagerError",
-  {
-    operation: Schema.Literals(["prepare", "prepare-languages", "resolve-engine"]),
-    languages: Schema.Array(Schema.String),
-    cause: Schema.Defect(),
-  },
-) {
-  override get message(): string {
-    return `Review highlighter operation ${this.operation} failed for languages ${this.languages.join(", ")}.`;
-  }
-}
-
-export interface ReviewHighlighterState {
-  readonly engine: ReviewHighlighterEngine | null;
-  readonly error: ReviewHighlighterManagerError | null;
-  readonly status: ReviewHighlighterStatus;
-}
-
-export interface ReviewHighlighterLoader {
-  readonly prepare: () => Promise<void>;
-  readonly prepareLanguages: (languages: ReadonlyArray<string>) => Promise<void>;
-  readonly getEngine: () => Promise<ReviewHighlighterEngine>;
-}
-
-const REVIEW_INITIAL_LANGUAGES = [
-  "typescript",
-  "tsx",
-  "javascript",
-  "jsx",
-  "json",
-  "yaml",
-  "bash",
-] as const;
-
-export const IDLE_REVIEW_HIGHLIGHTER_STATE = Object.freeze<ReviewHighlighterState>({
-  engine: null,
-  error: null,
-  status: "idle",
-});
-
-const INITIALIZING_REVIEW_HIGHLIGHTER_STATE = Object.freeze<ReviewHighlighterState>({
-  engine: null,
-  error: null,
-  status: "initializing",
-});
-
-export const reviewHighlighterStateAtom = Atom.make(IDLE_REVIEW_HIGHLIGHTER_STATE).pipe(
-  Atom.keepAlive,
-  Atom.withLabel("mobile:review-highlighter"),
-);
-
-function isReviewHighlighterProviderDebugLoggingEnabled(): boolean {
-  return typeof __DEV__ !== "undefined" ? __DEV__ : false;
-}
-
-function logReviewHighlighterProviderDiagnostic(
-  message: string,
-  details?: Record<string, unknown>,
-): void {
-  if (!isReviewHighlighterProviderDebugLoggingEnabled()) {
-    return;
-  }
-
-  if (details) {
-    console.log(`[review-highlighter-provider] ${message}`, details);
-    return;
-  }
-
-  console.log(`[review-highlighter-provider] ${message}`);
-}
-
-export function createReviewHighlighterManager(config: {
-  readonly getRegistry: () => AtomRegistry.AtomRegistry;
-  readonly loader: ReviewHighlighterLoader;
-  readonly languages?: ReadonlyArray<string>;
-}) {
-  let started = false;
-  let inFlight: Promise<void> | null = null;
-
-  function getSnapshot(): ReviewHighlighterState {
-    return config.getRegistry().get(reviewHighlighterStateAtom);
-  }
-
-  function setState(state: ReviewHighlighterState): void {
-    config.getRegistry().set(reviewHighlighterStateAtom, state);
-  }
-
-  function initialize(): Promise<void> {
-    if (inFlight) {
-      return inFlight;
-    }
-
-    if (started && getSnapshot().status === "ready") {
-      return Promise.resolve();
-    }
-
-    started = true;
-    setState(INITIALIZING_REVIEW_HIGHLIGHTER_STATE);
-
-    inFlight = (async () => {
-      const startedAt = performance.now();
-      const languages = config.languages ?? REVIEW_INITIAL_LANGUAGES;
-      let operation: ReviewHighlighterManagerError["operation"] = "prepare";
-      let engine: ReviewHighlighterEngine;
-      try {
-        await config.loader.prepare();
-        operation = "prepare-languages";
-        await config.loader.prepareLanguages(languages);
-        operation = "resolve-engine";
-        engine = await config.loader.getEngine();
-      } catch (cause) {
-        const error = new ReviewHighlighterManagerError({
-          operation,
-          languages,
-          cause,
-        });
-        logReviewHighlighterProviderDiagnostic("initialization failed", { error });
-        setState({ engine: null, error, status: "error" });
-        return;
-      }
-
-      const durationMs = Math.round(performance.now() - startedAt);
-      logReviewHighlighterProviderDiagnostic("initialized", {
-        durationMs,
-        engine,
-      });
-      setState({ engine, error: null, status: "ready" });
-    })().finally(() => {
-      inFlight = null;
-    });
-
-    return inFlight;
-  }
-
-  function reset(): void {
-    started = false;
-    inFlight = null;
-    setState(IDLE_REVIEW_HIGHLIGHTER_STATE);
-  }
-
-  return {
-    getSnapshot,
-    initialize,
-    reset,
-  };
-}
-
-const reviewHighlighterManager = createReviewHighlighterManager({
-  getRegistry: () => appAtomRegistry,
-  loader: {
-    prepare: prepareReviewHighlighter,
-    prepareLanguages: prepareReviewHighlighterLanguages,
-    getEngine: getActiveReviewHighlighterEngine,
-  },
-});
-
-export function useReviewHighlighterState(): ReviewHighlighterState {
-  useEffect(() => {
-    void reviewHighlighterManager.initialize();
-  }, []);
-
-  return useAtomValue(reviewHighlighterStateAtom);
-}
diff --git a/apps/mobile/src/features/review/reviewModel.test.ts b/apps/mobile/src/features/review/reviewModel.test.ts
index 3390afd9ff27..ee568085f7a2 100644
--- a/apps/mobile/src/features/review/reviewModel.test.ts
+++ b/apps/mobile/src/features/review/reviewModel.test.ts
@@ -8,7 +8,6 @@ import {
 } from "@t3tools/contracts";
 
 import {
-  buildReviewListItems,
   buildReviewParsedDiff,
   buildReviewSectionItems,
   getDefaultReviewSectionId,
@@ -271,84 +270,4 @@ describe("buildReviewParsedDiff", () => {
       actionLabel: "Load diff",
     });
   });
-
-  it("flattens expanded file rows into virtualized review items", () => {
-    const file = makeRenderableFile({
-      path: "apps/mobile/src/a.ts",
-      rows: [
-        {
-          kind: "hunk",
-          id: "hunk-1",
-          header: "@@ -1,1 +1,2 @@",
-          context: null,
-        },
-        {
-          kind: "line",
-          id: "line-1",
-          change: "add",
-          oldLineNumber: null,
-          newLineNumber: 1,
-          content: "const after = 2;",
-          additionTokenIndex: 0,
-          deletionTokenIndex: null,
-          comparison: null,
-        },
-      ],
-    });
-
-    const items = buildReviewListItems({
-      files: [file],
-      expandedFileIds: [file.id],
-      revealedLargeFileIds: [],
-    });
-
-    expect(items).toEqual([
-      expect.objectContaining({ kind: "file-header", fileId: file.id, expanded: true }),
-      expect.objectContaining({
-        kind: "hunk",
-        fileId: file.id,
-        file,
-        row: file.rows[0],
-      }),
-      expect.objectContaining({
-        kind: "line",
-        fileId: file.id,
-        file,
-        row: file.rows[1],
-        lineIndex: 0,
-      }),
-    ]);
-  });
-
-  it("keeps large diffs collapsed into a placeholder item until revealed", () => {
-    const file = makeRenderableFile({
-      path: "apps/mobile/src/big.ts",
-      rows: Array.from({ length: 401 }, (_, index) => ({
-        kind: "line" as const,
-        id: `line-${index}`,
-        change: "add" as const,
-        oldLineNumber: null,
-        newLineNumber: index + 1,
-        content: `const line${index} = ${index};`,
-        additionTokenIndex: index,
-        deletionTokenIndex: null,
-        comparison: null,
-      })),
-    });
-
-    const items = buildReviewListItems({
-      files: [file],
-      expandedFileIds: [file.id],
-      revealedLargeFileIds: [],
-    });
-
-    expect(items).toEqual([
-      expect.objectContaining({ kind: "file-header", fileId: file.id, expanded: true }),
-      expect.objectContaining({
-        kind: "file-suppressed",
-        fileId: file.id,
-        actionLabel: "Load diff",
-      }),
-    ]);
-  });
 });
diff --git a/apps/mobile/src/features/review/reviewModel.ts b/apps/mobile/src/features/review/reviewModel.ts
index 9459d41872d1..202157b837cc 100644
--- a/apps/mobile/src/features/review/reviewModel.ts
+++ b/apps/mobile/src/features/review/reviewModel.ts
@@ -58,45 +58,6 @@ export interface ReviewRenderableFile {
   readonly rows: ReadonlyArray<ReviewRenderableRow>;
 }
 
-export interface ReviewFileHeaderListItem {
-  readonly kind: "file-header";
-  readonly id: string;
-  readonly fileId: string;
-  readonly file: ReviewRenderableFile;
-  readonly expanded: boolean;
-}
-
-export interface ReviewFileSuppressedListItem {
-  readonly kind: "file-suppressed";
-  readonly id: string;
-  readonly fileId: string;
-  readonly message: string;
-  readonly actionLabel: string | null;
-}
-
-export interface ReviewHunkListItem {
-  readonly kind: "hunk";
-  readonly id: string;
-  readonly fileId: string;
-  readonly file: ReviewRenderableFile;
-  readonly row: ReviewRenderableHunkRow;
-}
-
-export interface ReviewLineListItem {
-  readonly kind: "line";
-  readonly id: string;
-  readonly fileId: string;
-  readonly file: ReviewRenderableFile;
-  readonly row: ReviewRenderableLineRow;
-  readonly lineIndex: number;
-}
-
-export type ReviewListItem =
-  | ReviewFileHeaderListItem
-  | ReviewFileSuppressedListItem
-  | ReviewHunkListItem
-  | ReviewLineListItem;
-
 export type ReviewFilePreviewState =
   | {
       readonly kind: "render";
@@ -316,77 +277,6 @@ export function getReviewFilePreviewState(file: ReviewRenderableFile): ReviewFil
   return { kind: "render" };
 }
 
-// The flattened review list item model is inspired by pierre/diffs' iterator-first
-// virtualization architecture, adapted here for React Native virtualization.
-// Original project: https://github.com/pingdotgg/pierre/tree/main/packages/diffs
-// Reference files:
-// - src/utils/iterateOverDiff.ts
-// - src/components/VirtualizedFileDiff.ts
-export function buildReviewListItems(input: {
-  readonly files: ReadonlyArray<ReviewRenderableFile>;
-  readonly expandedFileIds: ReadonlyArray<string>;
-  readonly revealedLargeFileIds: ReadonlyArray<string>;
-}): ReadonlyArray<ReviewListItem> {
-  const expandedFileIds = new Set(input.expandedFileIds);
-  const revealedLargeFileIds = new Set(input.revealedLargeFileIds);
-  const items: ReviewListItem[] = [];
-
-  input.files.forEach((file) => {
-    const expanded = expandedFileIds.has(file.id);
-    items.push({
-      kind: "file-header",
-      id: `${file.id}:header`,
-      fileId: file.id,
-      file,
-      expanded,
-    });
-
-    if (!expanded) {
-      return;
-    }
-
-    const previewState = getReviewFilePreviewState(file);
-    if (previewState.kind === "suppressed") {
-      if (previewState.reason !== "large" || !revealedLargeFileIds.has(file.id)) {
-        items.push({
-          kind: "file-suppressed",
-          id: `${file.id}:suppressed`,
-          fileId: file.id,
-          message: previewState.message,
-          actionLabel: previewState.actionLabel,
-        });
-        return;
-      }
-    }
-
-    let lineIndex = 0;
-    file.rows.forEach((row, rowIndex) => {
-      if (row.kind === "hunk") {
-        items.push({
-          kind: "hunk",
-          id: `${file.id}:row:${rowIndex}:${row.id}`,
-          fileId: file.id,
-          file,
-          row,
-        });
-        return;
-      }
-
-      items.push({
-        kind: "line",
-        id: `${file.id}:row:${rowIndex}:${row.id}`,
-        fileId: file.id,
-        file,
-        row,
-        lineIndex,
-      });
-      lineIndex += 1;
-    });
-  });
-
-  return items;
-}
-
 function fallbackHunkHeader(hunk: FileDiffMetadata["hunks"][number]): string {
   return `@@ -${hunk.deletionStart},${hunk.deletionCount} +${hunk.additionStart},${hunk.additionCount} @@`;
 }
diff --git a/apps/mobile/src/features/review/reviewState.test.ts b/apps/mobile/src/features/review/reviewState.test.ts
index 8e99636d417f..28fb734f80dd 100644
--- a/apps/mobile/src/features/review/reviewState.test.ts
+++ b/apps/mobile/src/features/review/reviewState.test.ts
@@ -1,11 +1,31 @@
-import { assert, it } from "vite-plus/test";
+import { afterEach, assert, it } from "vite-plus/test";
 
+import { appAtomRegistry } from "../../state/atom-registry";
+import { getCachedNativeReviewDiffData } from "./nativeReviewDiffAdapter";
 import {
+  getCachedReviewParsedDiff,
   getReviewAsyncStateSnapshot,
   setReviewAsyncError,
   setReviewTurnDiffLoading,
 } from "./reviewState";
 
+const reviewInput = {
+  threadKey: "env-local:thread-review",
+  sectionId: "turn:1",
+  diff: [
+    "diff --git a/src/a.ts b/src/a.ts",
+    "new file mode 100644",
+    "--- /dev/null",
+    "+++ b/src/a.ts",
+    "@@ -0,0 +1 @@",
+    "+export const value = 1;",
+  ].join("\n"),
+};
+
+afterEach(() => {
+  appAtomRegistry.reset();
+});
+
 it("stores review async loading and error state in atoms", () => {
   const threadKey = `env-local:thread-review-state-${Date.now()}`;
 
@@ -25,3 +45,87 @@ it("stores review async loading and error state in atoms", () => {
     error: null,
   });
 });
+
+it("reuses unchanged parsed diffs and replaces changed sections", () => {
+  const parsed = getCachedReviewParsedDiff(reviewInput);
+
+  assert.strictEqual(
+    getCachedReviewParsedDiff({ ...reviewInput, diff: `\n${reviewInput.diff}\n` }),
+    parsed,
+  );
+
+  const changed = { ...reviewInput, diff: reviewInput.diff.replace("value = 1", "value = 2") };
+  const updated = getCachedReviewParsedDiff(changed);
+  assert.notStrictEqual(updated, parsed);
+  assert.strictEqual(getCachedReviewParsedDiff(changed), updated);
+});
+
+it("evicts the least recently used section across threads without changing live results or IDs", () => {
+  const recentInput = { ...reviewInput, threadKey: "env-local:thread-recent" };
+  const oldestInput = { ...reviewInput, threadKey: "env-remote:thread-oldest" };
+  const recent = getCachedReviewParsedDiff(recentInput);
+  const oldest = getCachedReviewParsedDiff(oldestInput);
+  const native = getCachedNativeReviewDiffData({ parsedDiff: oldest });
+  for (let index = 0; index < 6; index += 1) {
+    getCachedReviewParsedDiff({ ...reviewInput, threadKey: `env-local:thread-${index}` });
+  }
+
+  assert.strictEqual(getCachedReviewParsedDiff(recentInput), recent);
+  getCachedReviewParsedDiff({ ...reviewInput, threadKey: "env-local:thread-new" });
+
+  assert.strictEqual(getCachedReviewParsedDiff(recentInput), recent);
+  const rebuilt = getCachedReviewParsedDiff(oldestInput);
+  assert.notStrictEqual(rebuilt, oldest);
+  assert.deepStrictEqual(rebuilt, oldest);
+  assert.strictEqual(getCachedNativeReviewDiffData({ parsedDiff: oldest }), native);
+  assert.deepStrictEqual(getCachedNativeReviewDiffData({ parsedDiff: rebuilt }), native);
+});
+
+it("limits cached diffs to 4 Mi source characters before the entry limit", () => {
+  const firstInput = { ...reviewInput, diff: "x".repeat(2 * 1024 * 1024) };
+  const secondInput = { ...firstInput, sectionId: "turn:2" };
+  const first = getCachedReviewParsedDiff(firstInput);
+  const second = getCachedReviewParsedDiff(secondInput);
+
+  getCachedReviewParsedDiff({ ...firstInput, sectionId: "turn:3" });
+
+  assert.strictEqual(getCachedReviewParsedDiff(secondInput), second);
+  assert.notStrictEqual(getCachedReviewParsedDiff(firstInput), first);
+});
+
+it("reclaims the source budget when a cached section changes", () => {
+  const firstInput = { ...reviewInput, diff: "x".repeat(2 * 1024 * 1024) };
+  const secondInput = { ...firstInput, sectionId: "turn:2" };
+  getCachedReviewParsedDiff(firstInput);
+  const second = getCachedReviewParsedDiff(secondInput);
+
+  getCachedReviewParsedDiff({ ...firstInput, diff: null });
+  getCachedReviewParsedDiff({ ...firstInput, sectionId: "turn:3" });
+
+  assert.strictEqual(getCachedReviewParsedDiff(secondInput), second);
+});
+
+it("counts the full source and skips oversized diffs without evicting cached sections", () => {
+  const cached = getCachedReviewParsedDiff(reviewInput);
+  const oversizedInput = {
+    ...reviewInput,
+    sectionId: "turn:oversized",
+    diff: `${reviewInput.diff}${" ".repeat(4 * 1024 * 1024)}`,
+  };
+  const first = getCachedReviewParsedDiff(oversizedInput);
+  const second = getCachedReviewParsedDiff(oversizedInput);
+
+  assert.notStrictEqual(second, first);
+  assert.deepStrictEqual(second, first);
+  assert.strictEqual(getCachedReviewParsedDiff(reviewInput), cached);
+});
+
+it("drops parsed diffs when the app registry resets", () => {
+  const parsed = getCachedReviewParsedDiff(reviewInput);
+
+  appAtomRegistry.reset();
+
+  const rebuilt = getCachedReviewParsedDiff(reviewInput);
+  assert.notStrictEqual(rebuilt, parsed);
+  assert.deepStrictEqual(rebuilt, parsed);
+});
diff --git a/apps/mobile/src/features/review/reviewState.ts b/apps/mobile/src/features/review/reviewState.ts
index a86d53c35859..f211b4bc06d9 100644
--- a/apps/mobile/src/features/review/reviewState.ts
+++ b/apps/mobile/src/features/review/reviewState.ts
@@ -87,12 +87,21 @@ const reviewViewedFileIdsByThreadKeyAtom = Atom.family((threadKey: string) =>
   ),
 );
 
-const reviewParsedDiffBySectionCacheKeyAtom = Atom.family((cacheKey: string) =>
-  Atom.make<{ readonly diff: string | null; readonly parsed: ReviewParsedDiff } | null>(null).pipe(
-    Atom.keepAlive,
-    Atom.withLabel(`mobile:review:parsed-diffs:${cacheKey}`),
-  ),
-);
+export const MAX_CACHED_REVIEW_DIFFS = 8;
+// This bounds source string length, not the parsed or native heap size.
+export const MAX_CACHED_REVIEW_SOURCE_CHARACTERS = 4 * 1024 * 1024;
+
+interface CachedReviewParsedDiff {
+  readonly diff: string | null;
+  readonly parsed: ReviewParsedDiff;
+  readonly sourceCharacterCount: number;
+}
+
+// The factory keeps this mutable cache local to the registry and releases it on reset or disposal.
+const reviewParsedDiffCacheAtom = Atom.make(() => ({
+  entries: new Map<string, CachedReviewParsedDiff>(),
+  sourceCharacterCount: 0,
+})).pipe(Atom.keepAlive, Atom.withLabel("mobile:review:parsed-diffs"));
 
 export interface ReviewCacheForThread {
   readonly threadKey: string | null;
@@ -256,6 +265,20 @@ export function updateReviewViewedFileIds(
   });
 }
 
+/** Returns the larger of current input and matching cached source, without changing recency. */
+export function getReviewParsedDiffSourceCharacterCount(input: {
+  readonly threadKey: string;
+  readonly sectionId: string;
+  readonly diff: string | null;
+}): number {
+  const sourceCharacterCount = input.diff?.length ?? 0;
+  const cache = appAtomRegistry.get(reviewParsedDiffCacheAtom);
+  const cached = cache.entries.get(buildSectionCacheKey(input.threadKey, input.sectionId));
+  return cached && cached.diff === (input.diff?.trim() ?? null)
+    ? Math.max(sourceCharacterCount, cached.sourceCharacterCount)
+    : sourceCharacterCount;
+}
+
 export function getCachedReviewParsedDiff(input: {
   readonly threadKey: string | null;
   readonly sectionId: string | null;
@@ -267,16 +290,39 @@ export function getCachedReviewParsedDiff(input: {
 
   const cacheKey = buildSectionCacheKey(input.threadKey, input.sectionId);
   const normalizedDiff = input.diff?.trim() ?? null;
-  const atom = reviewParsedDiffBySectionCacheKeyAtom(cacheKey);
-  const cached = appAtomRegistry.get(atom);
+  const cache = appAtomRegistry.get(reviewParsedDiffCacheAtom);
+  const cached = cache.entries.get(cacheKey);
   if (cached && cached.diff === normalizedDiff) {
+    cache.entries.delete(cacheKey);
+    cache.entries.set(cacheKey, cached);
     return cached.parsed;
   }
 
   const parsed = buildReviewParsedDiff(input.diff, input.sectionId);
-  appAtomRegistry.set(atom, {
+  if (cached) {
+    cache.entries.delete(cacheKey);
+    cache.sourceCharacterCount -= cached.sourceCharacterCount;
+  }
+  const sourceCharacterCount = input.diff?.length ?? 0;
+  if (sourceCharacterCount > MAX_CACHED_REVIEW_SOURCE_CHARACTERS) {
+    return parsed;
+  }
+
+  for (const [oldestKey, oldest] of cache.entries) {
+    if (
+      cache.entries.size < MAX_CACHED_REVIEW_DIFFS &&
+      cache.sourceCharacterCount + sourceCharacterCount <= MAX_CACHED_REVIEW_SOURCE_CHARACTERS
+    ) {
+      break;
+    }
+    cache.entries.delete(oldestKey);
+    cache.sourceCharacterCount -= oldest.sourceCharacterCount;
+  }
+  cache.entries.set(cacheKey, {
     diff: normalizedDiff,
     parsed,
+    sourceCharacterCount,
   });
+  cache.sourceCharacterCount += sourceCharacterCount;
   return parsed;
 }
diff --git a/apps/mobile/src/features/review/shikiReviewHighlighter.test.ts b/apps/mobile/src/features/review/shikiReviewHighlighter.test.ts
index 0bc6469426e8..6d36171d2711 100644
--- a/apps/mobile/src/features/review/shikiReviewHighlighter.test.ts
+++ b/apps/mobile/src/features/review/shikiReviewHighlighter.test.ts
@@ -1,122 +1,111 @@
-import { describe, expect, it } from "vite-plus/test";
+import { describe, expect, it, vi } from "vite-plus/test";
 
-import type { ReviewRenderableFile } from "./reviewModel";
-import { highlightCodeSnippet, highlightReviewFile } from "./shikiReviewHighlighter";
+import type { ReviewRenderableLineRow } from "./reviewModel";
+import {
+  highlightCodeSnippet,
+  highlightReviewSelectedLines,
+  highlightSourceFile,
+} from "./shikiReviewHighlighter";
 
-function makeRenderableFile(
-  input: Partial<ReviewRenderableFile> & Pick<ReviewRenderableFile, "path">,
-): ReviewRenderableFile {
-  return {
-    id: input.path,
-    cacheKey: input.path,
-    previousPath: null,
-    changeType: "new",
-    additions: 0,
-    deletions: 0,
-    languageHint: null,
-    additionLines: [],
-    deletionLines: [],
-    rows: [],
-    ...input,
-  };
-}
+describe("highlightSourceFile", () => {
+  it("preserves one highlighted token row per source line without trailing newlines", async () => {
+    const lines = [
+      'const items = ["a"];',
+      'expect(items).toEqual(["a"]);',
+      "const next = items.map((item) => item.toUpperCase());",
+      'expect(next).toContain("A");',
+    ];
 
-describe("highlightReviewFile", () => {
-  it("preserves one highlighted token row per diff line even without trailing newlines", async () => {
-    const file = makeRenderableFile({
-      path: "apps/mobile/src/example.txt",
-      additionLines: [
-        'const items = ["a"];',
-        'expect(items).toEqual(["a"]);',
-        "const next = items.map((item) => item.toUpperCase());",
-        'expect(next).toContain("A");',
-      ],
+    const highlighted = await highlightSourceFile({
+      path: "apps/mobile/src/example.ts",
+      contents: lines.join("\n"),
+      theme: "light",
     });
 
-    const highlighted = await highlightReviewFile(file, "light");
-
-    expect(highlighted.additionLines).toHaveLength(file.additionLines.length);
-    expect(highlighted.additionLines[0]?.map((token) => token.content).join("")).toBe(
-      file.additionLines[0],
-    );
-    expect(highlighted.additionLines[1]?.map((token) => token.content).join("")).toBe(
-      file.additionLines[1],
-    );
-    expect(highlighted.additionLines[2]?.map((token) => token.content).join("")).toBe(
-      file.additionLines[2],
-    );
-    expect(highlighted.additionLines[3]?.map((token) => token.content).join("")).toBe(
-      file.additionLines[3],
+    expect(highlighted.map((tokens) => tokens.map((token) => token.content).join(""))).toEqual(
+      lines,
     );
   });
 
-  it("adds word-alt diff emphasis for paired deletion and addition lines", async () => {
-    const file = makeRenderableFile({
-      path: "apps/mobile/src/example-inline-diff.txt",
-      additionLines: ["const after = 2;"],
-      deletionLines: ["const before = 1;"],
-      rows: [
-        {
-          kind: "line",
-          id: "delete-1",
-          change: "delete",
-          oldLineNumber: 1,
-          newLineNumber: null,
-          content: "const before = 1;",
-          additionTokenIndex: null,
-          deletionTokenIndex: 0,
-          comparison: { change: "add", tokenIndex: 0 },
-        },
-        {
-          kind: "line",
-          id: "add-1",
-          change: "add",
-          oldLineNumber: null,
-          newLineNumber: 1,
-          content: "const after = 2;",
-          additionTokenIndex: 0,
-          deletionTokenIndex: null,
-          comparison: { change: "delete", tokenIndex: 0 },
-        },
-      ],
-    });
-
-    const highlighted = await highlightReviewFile(file, "light");
-
-    expect(highlighted.deletionLines[0]?.some((token) => token.diffHighlight === true)).toBe(true);
-    expect(highlighted.additionLines[0]?.some((token) => token.diffHighlight === true)).toBe(true);
-  });
-
   it("falls back to plain tokens for very long lines", async () => {
     const longLine = `const value = "${"a".repeat(1_100)}";`;
-    const file = makeRenderableFile({
-      path: "apps/mobile/src/example-long-line.txt",
-      additionLines: [longLine],
-      rows: [
+
+    const highlighted = await highlightSourceFile({
+      path: "apps/mobile/src/example-long-line.ts",
+      contents: longLine,
+      theme: "light",
+    });
+
+    expect(highlighted).toEqual([
+      [
         {
-          kind: "line",
-          id: "add-1",
-          change: "add",
-          oldLineNumber: null,
-          newLineNumber: 1,
           content: longLine,
-          additionTokenIndex: 0,
-          deletionTokenIndex: null,
-          comparison: null,
+          color: null,
+          fontStyle: null,
         },
       ],
+    ]);
+  });
+
+  it("initializes source and snippet highlighting without a warmup", async () => {
+    vi.resetModules();
+    const highlighter = await import("./shikiReviewHighlighter");
+    const source = "const answer: number = 42;";
+
+    const highlighted = await highlighter.highlightSourceFile({
+      path: "example.ts",
+      contents: source,
+      theme: "dark",
     });
 
-    const highlighted = await highlightReviewFile(file, "light");
+    expect(
+      highlighted
+        .flat()
+        .map((token) => token.content)
+        .join(""),
+    ).toBe(source);
+    expect(highlighted.flat().some((token) => token.color !== null)).toBe(true);
+    expect(
+      await highlighter.highlightCodeSnippet({ code: source, language: "ts", theme: "dark" }),
+    ).toEqual(highlighted);
+  });
+});
 
-    expect(highlighted.additionLines).toHaveLength(1);
-    expect(highlighted.additionLines[0]).toEqual([
+describe("highlightReviewSelectedLines", () => {
+  it("adds word-alt diff emphasis for paired deletion and addition lines", async () => {
+    const lines: ReviewRenderableLineRow[] = [
       {
-        content: longLine,
-        color: null,
-        fontStyle: null,
+        kind: "line",
+        id: "delete-1",
+        change: "delete",
+        oldLineNumber: 1,
+        newLineNumber: null,
+        content: "const before = 1;",
+        additionTokenIndex: null,
+        deletionTokenIndex: 0,
+        comparison: { change: "add", tokenIndex: 0 },
       },
-    ]);
+      {
+        kind: "line",
+        id: "add-1",
+        change: "add",
+        oldLineNumber: null,
+        newLineNumber: 1,
+        content: "const after = 2;",
+        additionTokenIndex: 0,
+        deletionTokenIndex: null,
+        comparison: { change: "delete", tokenIndex: 0 },
+      },
+    ];
+
+    const highlighted = await highlightReviewSelectedLines({
+      filePath: "apps/mobile/src/example-inline-diff.txt",
+      lines,
+      theme: "light",
+    });
+
+    expect(highlighted["delete-1"]?.some((token) => token.diffHighlight === true)).toBe(true);
+    expect(highlighted["add-1"]?.some((token) => token.diffHighlight === true)).toBe(true);
   });
 });
 
diff --git a/apps/mobile/src/features/review/shikiReviewHighlighter.ts b/apps/mobile/src/features/review/shikiReviewHighlighter.ts
index c684a6686430..8fa7f69a433c 100644
--- a/apps/mobile/src/features/review/shikiReviewHighlighter.ts
+++ b/apps/mobile/src/features/review/shikiReviewHighlighter.ts
@@ -17,7 +17,7 @@ import {
   resolveReviewHighlighterEnginePreference,
   type ReviewHighlighterEngine,
 } from "./reviewHighlighterEngine";
-import type { ReviewRenderableFile, ReviewRenderableLineRow } from "./reviewModel";
+import type { ReviewRenderableLineRow } from "./reviewModel";
 import { applyDiffRangesToTokens, computeWordAltDiffRanges } from "./reviewWordDiffs";
 
 export type ReviewDiffTheme = "light" | "dark";
@@ -43,17 +43,6 @@ export interface ReviewHighlightedToken {
   readonly diffHighlight?: boolean;
 }
 
-export interface ReviewHighlightedFile {
-  readonly additionLines: ReadonlyArray<ReadonlyArray<ReviewHighlightedToken>>;
-  readonly deletionLines: ReadonlyArray<ReadonlyArray<ReviewHighlightedToken>>;
-}
-
-export interface ReviewHighlightFileProgress {
-  readonly highlightedFile: ReviewHighlightedFile;
-  readonly complete: boolean;
-  readonly highlightedLineCount: number;
-}
-
 const SHIKI_THEME_NAME_BY_SCHEME = {
   light: "github-light-default",
   dark: "github-dark-default",
@@ -64,16 +53,9 @@ const REVIEW_HIGHLIGHTER_ENGINE_ENV_VALUE =
 const REVIEW_HIGHLIGHTER_ENGINE_PREFERENCE = resolveReviewHighlighterEnginePreference(
   REVIEW_HIGHLIGHTER_ENGINE_ENV_VALUE,
 );
-const REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE = resolveReviewHighlighterBooleanFlag(
-  process.env.EXPO_PUBLIC_REVIEW_HIGHLIGHTER_DISABLE_CACHE,
-  false,
-);
-const REVIEW_HIGHLIGHT_RESULT_CACHE_LIMIT = 8;
 const REVIEW_HIGHLIGHT_CHUNK_LINE_THRESHOLD = 8;
 const REVIEW_HIGHLIGHT_CHUNK_SIZE = 200;
 const REVIEW_TOKENIZE_MAX_LINE_LENGTH = 1_000;
-const highlightCache = new Map<string, Promise<ReviewHighlightedFile>>();
-const resolvedHighlightCache = new Map<string, ReviewHighlightedFile>();
 const REVIEW_INITIAL_LANGUAGE_MODULES = [
   bashLanguage,
   javascriptLanguage,
@@ -204,22 +186,6 @@ type LoadedLanguageModule = {
   default: Parameters<HighlighterCore["loadLanguage"]>[0];
 };
 
-function resolveReviewHighlighterBooleanFlag(
-  value: string | undefined,
-  defaultValue: boolean,
-): boolean {
-  switch (value) {
-    case "1":
-    case "true":
-      return true;
-    case "0":
-    case "false":
-      return false;
-    default:
-      return defaultValue;
-  }
-}
-
 function isReviewHighlighterDebugLoggingEnabled(): boolean {
   return typeof __DEV__ !== "undefined" ? __DEV__ : false;
 }
@@ -267,7 +233,6 @@ async function getHighlighter(): Promise<HighlighterCore> {
       logReviewHighlighterDiagnostic("initializing", {
         configuredPreference: REVIEW_HIGHLIGHTER_ENGINE_ENV_VALUE,
         preference: REVIEW_HIGHLIGHTER_ENGINE_PREFERENCE,
-        resultCacheDisabled: REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE,
       });
 
       const themes = [githubLightDefault, githubDarkDefault];
@@ -488,13 +453,6 @@ async function resolveLanguageFromPath(
   return candidate;
 }
 
-async function resolveLanguage(file: ReviewRenderableFile): Promise<string> {
-  return (
-    resolveLoadedLanguageFromPath(file.path, file.languageHint) ??
-    (await resolveLanguageFromPath(file.path, file.languageHint))
-  );
-}
-
 function normalizeHighlightedLines(
   tokenLines: ReadonlyArray<ReadonlyArray<{ content: string; color?: string; fontStyle?: number }>>,
 ): ReadonlyArray<ReadonlyArray<ReviewHighlightedToken>> {
@@ -507,84 +465,6 @@ function normalizeHighlightedLines(
   );
 }
 
-function makePlainHighlightedLines(
-  lines: ReadonlyArray<string>,
-): ReadonlyArray<ReadonlyArray<ReviewHighlightedToken>> {
-  return lines.map((line) => [
-    {
-      content: stripTrailingNewline(line),
-      color: null,
-      fontStyle: null,
-    },
-  ]);
-}
-
-function applyWordAltDiffHighlightsToFile(
-  file: ReviewRenderableFile,
-  highlighted: ReviewHighlightedFile,
-): ReviewHighlightedFile {
-  const nextAdditionLines = [...highlighted.additionLines];
-  const nextDeletionLines = [...highlighted.deletionLines];
-  const processedPairs = new Set<string>();
-  let changed = false;
-
-  file.rows.forEach((row) => {
-    if (row.kind !== "line" || row.change === "context" || !row.comparison) {
-      return;
-    }
-
-    const deletionTokenIndex =
-      row.change === "delete"
-        ? row.deletionTokenIndex
-        : row.comparison.change === "delete"
-          ? row.comparison.tokenIndex
-          : null;
-    const additionTokenIndex =
-      row.change === "add"
-        ? row.additionTokenIndex
-        : row.comparison.change === "add"
-          ? row.comparison.tokenIndex
-          : null;
-
-    if (deletionTokenIndex === null || additionTokenIndex === null) {
-      return;
-    }
-
-    const pairKey = `${deletionTokenIndex}:${additionTokenIndex}`;
-    if (processedPairs.has(pairKey)) {
-      return;
-    }
-    processedPairs.add(pairKey);
-
-    const deletionLine = stripTrailingNewline(file.deletionLines[deletionTokenIndex] ?? "");
-    const additionLine = stripTrailingNewline(file.additionLines[additionTokenIndex] ?? "");
-    const ranges = computeWordAltDiffRanges({ deletionLine, additionLine });
-
-    if (ranges.deletion.length > 0) {
-      nextDeletionLines[deletionTokenIndex] = applyDiffRangesToTokens(
-        nextDeletionLines[deletionTokenIndex] ?? [],
-        ranges.deletion,
-      );
-      changed = true;
-    }
-
-    if (ranges.addition.length > 0) {
-      nextAdditionLines[additionTokenIndex] = applyDiffRangesToTokens(
-        nextAdditionLines[additionTokenIndex] ?? [],
-        ranges.addition,
-      );
-      changed = true;
-    }
-  });
-
-  return changed
-    ? {
-        additionLines: nextAdditionLines,
-        deletionLines: nextDeletionLines,
-      }
-    : highlighted;
-}
-
 function applyWordAltDiffHighlightsToSelectedLines(input: {
   readonly lines: ReadonlyArray<ReviewRenderableLineRow>;
   readonly tokenMap: Record<string, ReadonlyArray<ReviewHighlightedToken>>;
@@ -733,292 +613,6 @@ export async function highlightSourceFile(input: {
   return highlightLines(input.contents, language, SHIKI_THEME_NAME_BY_SCHEME[input.theme]);
 }
 
-async function highlightPatchLinesInChunks(input: {
-  readonly lines: ReadonlyArray<string>;
-  readonly language: string;
-  readonly theme: string;
-  readonly onChunk: (
-    startIndex: number,
-    tokens: ReadonlyArray<ReadonlyArray<ReviewHighlightedToken>>,
-  ) => void;
-}): Promise<ReadonlyArray<ReadonlyArray<ReviewHighlightedToken>>> {
-  if (input.lines.length === 0) {
-    return [];
-  }
-
-  const highlighter = await getHighlighter();
-  const highlightedLines: Array<ReadonlyArray<ReviewHighlightedToken>> = [];
-
-  for (
-    let startIndex = 0;
-    startIndex < input.lines.length;
-    startIndex += REVIEW_HIGHLIGHT_CHUNK_SIZE
-  ) {
-    const lineChunk = input.lines.slice(startIndex, startIndex + REVIEW_HIGHLIGHT_CHUNK_SIZE);
-    const chunkTokens: Array<ReadonlyArray<ReviewHighlightedToken>> = [];
-    const tokenizableLines: string[] = [];
-    const tokenizableIndexes: number[] = [];
-
-    lineChunk.forEach((line, index) => {
-      const strippedLine = stripTrailingNewline(line);
-      if (strippedLine.length > REVIEW_TOKENIZE_MAX_LINE_LENGTH) {
-        chunkTokens[index] = [{ content: strippedLine, color: null, fontStyle: null }];
-        return;
-      }
-
-      tokenizableIndexes.push(index);
-      tokenizableLines.push(strippedLine);
-    });
-
-    if (tokenizableLines.length > 0) {
-      const tokenLines = highlighter.codeToTokensBase(tokenizableLines.join("\n"), {
-        lang: input.language,
-        theme: input.theme,
-      });
-      const normalizedTokenLines = normalizeHighlightedLines(tokenLines);
-
-      tokenizableIndexes.forEach((chunkIndex, tokenIndex) => {
-        chunkTokens[chunkIndex] = normalizedTokenLines[tokenIndex] ?? [];
-      });
-    }
-
-    const completedChunk = lineChunk.map((_, index) => chunkTokens[index] ?? []);
-    highlightedLines.push(...completedChunk);
-    input.onChunk(startIndex, completedChunk);
-
-    if (startIndex + REVIEW_HIGHLIGHT_CHUNK_SIZE < input.lines.length) {
-      await waitForNextFrame();
-    }
-  }
-
-  return highlightedLines;
-}
-
-function getHighlightCacheKey(file: ReviewRenderableFile, theme: ReviewDiffTheme): string {
-  return `${SHIKI_THEME_NAME_BY_SCHEME[theme]}:${file.cacheKey}`;
-}
-
-function storeResolvedHighlightedFile(cacheKey: string, highlighted: ReviewHighlightedFile): void {
-  if (resolvedHighlightCache.has(cacheKey)) {
-    resolvedHighlightCache.delete(cacheKey);
-  }
-
-  resolvedHighlightCache.set(cacheKey, highlighted);
-
-  while (resolvedHighlightCache.size > REVIEW_HIGHLIGHT_RESULT_CACHE_LIMIT) {
-    const oldestKey = resolvedHighlightCache.keys().next().value;
-    if (oldestKey === undefined) {
-      break;
-    }
-    resolvedHighlightCache.delete(oldestKey);
-  }
-}
-
-export async function highlightReviewFile(
-  file: ReviewRenderableFile,
-  theme: ReviewDiffTheme,
-): Promise<ReviewHighlightedFile> {
-  const shikiTheme = SHIKI_THEME_NAME_BY_SCHEME[theme];
-  const cacheKey = getHighlightCacheKey(file, theme);
-  if (!REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE) {
-    const resolved = resolvedHighlightCache.get(cacheKey);
-    if (resolved) {
-      logReviewHighlighterDiagnostic("file highlight cache hit (resolved)", {
-        fileId: file.id,
-        filePath: file.path,
-        theme,
-      });
-      return resolved;
-    }
-    const cached = highlightCache.get(cacheKey);
-    if (cached) {
-      logReviewHighlighterDiagnostic("file highlight cache hit (pending)", {
-        fileId: file.id,
-        filePath: file.path,
-        theme,
-      });
-      return cached;
-    }
-  }
-
-  const promise = (async () => {
-    const startedAt = Date.now();
-    logReviewHighlighterDiagnostic("file highlight start", {
-      fileId: file.id,
-      filePath: file.path,
-      theme,
-      additionLineCount: file.additionLines.length,
-      deletionLineCount: file.deletionLines.length,
-      rowCount: file.rows.length,
-    });
-    const loadedLanguage = resolveLoadedLanguageFromPath(file.path, file.languageHint);
-    const language = loadedLanguage ?? (await resolveLanguage(file));
-    if (language === "text") {
-      const highlighted = applyWordAltDiffHighlightsToFile(file, {
-        additionLines: makePlainHighlightedLines(file.additionLines),
-        deletionLines: makePlainHighlightedLines(file.deletionLines),
-      });
-      if (!REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE) {
-        storeResolvedHighlightedFile(cacheKey, highlighted);
-      }
-      logReviewHighlighterDiagnostic("file highlight complete", {
-        fileId: file.id,
-        filePath: file.path,
-        theme,
-        language,
-        highlightedAdditionLineCount: highlighted.additionLines.length,
-        highlightedDeletionLineCount: highlighted.deletionLines.length,
-        durationMs: Date.now() - startedAt,
-      });
-      return highlighted;
-    }
-
-    const additionLines = await highlightLines(
-      joinPatchLines(file.additionLines),
-      language,
-      shikiTheme,
-    );
-    await waitForNextFrame();
-    const deletionLines = await highlightLines(
-      joinPatchLines(file.deletionLines),
-      language,
-      shikiTheme,
-    );
-    await waitForNextFrame();
-
-    const highlighted = applyWordAltDiffHighlightsToFile(file, { additionLines, deletionLines });
-    if (!REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE) {
-      storeResolvedHighlightedFile(cacheKey, highlighted);
-    }
-    logReviewHighlighterDiagnostic("file highlight complete", {
-      fileId: file.id,
-      filePath: file.path,
-      theme,
-      language,
-      highlightedAdditionLineCount: highlighted.additionLines.length,
-      highlightedDeletionLineCount: highlighted.deletionLines.length,
-      durationMs: Date.now() - startedAt,
-    });
-    return highlighted;
-  })();
-
-  if (!REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE) {
-    highlightCache.set(cacheKey, promise);
-  }
-  return promise.finally(() => {
-    if (!REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE) {
-      highlightCache.delete(cacheKey);
-    }
-  });
-}
-
-export async function streamHighlightReviewFile(
-  file: ReviewRenderableFile,
-  theme: ReviewDiffTheme,
-  onProgress: (progress: ReviewHighlightFileProgress) => void,
-): Promise<ReviewHighlightedFile> {
-  const shikiTheme = SHIKI_THEME_NAME_BY_SCHEME[theme];
-  const cacheKey = getHighlightCacheKey(file, theme);
-  if (!REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE) {
-    const resolved = resolvedHighlightCache.get(cacheKey);
-    if (resolved) {
-      onProgress({
-        highlightedFile: resolved,
-        complete: true,
-        highlightedLineCount: resolved.additionLines.length + resolved.deletionLines.length,
-      });
-      return resolved;
-    }
-  }
-
-  const startedAt = Date.now();
-  logReviewHighlighterDiagnostic("file stream highlight start", {
-    fileId: file.id,
-    filePath: file.path,
-    theme,
-    additionLineCount: file.additionLines.length,
-    deletionLineCount: file.deletionLines.length,
-    rowCount: file.rows.length,
-  });
-
-  const loadedLanguage = resolveLoadedLanguageFromPath(file.path, file.languageHint);
-  const language = loadedLanguage ?? (await resolveLanguage(file));
-  if (language === "text") {
-    const highlighted = applyWordAltDiffHighlightsToFile(file, {
-      additionLines: makePlainHighlightedLines(file.additionLines),
-      deletionLines: makePlainHighlightedLines(file.deletionLines),
-    });
-    if (!REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE) {
-      storeResolvedHighlightedFile(cacheKey, highlighted);
-    }
-    onProgress({
-      highlightedFile: highlighted,
-      complete: true,
-      highlightedLineCount: highlighted.additionLines.length + highlighted.deletionLines.length,
-    });
-    logReviewHighlighterDiagnostic("file stream highlight complete", {
-      fileId: file.id,
-      filePath: file.path,
-      theme,
-      language,
-      highlightedAdditionLineCount: highlighted.additionLines.length,
-      highlightedDeletionLineCount: highlighted.deletionLines.length,
-      highlightedLineCount: highlighted.additionLines.length + highlighted.deletionLines.length,
-      durationMs: Date.now() - startedAt,
-    });
-    return highlighted;
-  }
-
-  const additionLines: Array<ReadonlyArray<ReviewHighlightedToken>> = [];
-  const deletionLines: Array<ReadonlyArray<ReviewHighlightedToken>> = [];
-  let highlightedLineCount = 0;
-
-  await highlightPatchLinesInChunks({
-    lines: file.additionLines,
-    language,
-    theme: shikiTheme,
-    onChunk: (startIndex, tokens) => {
-      tokens.forEach((lineTokens, index) => {
-        additionLines[startIndex + index] = lineTokens;
-      });
-      highlightedLineCount += tokens.length;
-    },
-  });
-  await waitForNextFrame();
-  await highlightPatchLinesInChunks({
-    lines: file.deletionLines,
-    language,
-    theme: shikiTheme,
-    onChunk: (startIndex, tokens) => {
-      tokens.forEach((lineTokens, index) => {
-        deletionLines[startIndex + index] = lineTokens;
-      });
-      highlightedLineCount += tokens.length;
-    },
-  });
-
-  const highlighted = applyWordAltDiffHighlightsToFile(file, { additionLines, deletionLines });
-  if (!REVIEW_HIGHLIGHTER_DISABLE_RESULT_CACHE) {
-    storeResolvedHighlightedFile(cacheKey, highlighted);
-  }
-  onProgress({
-    highlightedFile: highlighted,
-    complete: true,
-    highlightedLineCount,
-  });
-  logReviewHighlighterDiagnostic("file stream highlight complete", {
-    fileId: file.id,
-    filePath: file.path,
-    theme,
-    language,
-    highlightedAdditionLineCount: highlighted.additionLines.length,
-    highlightedDeletionLineCount: highlighted.deletionLines.length,
-    highlightedLineCount,
-    durationMs: Date.now() - startedAt,
-  });
-  return highlighted;
-}
-
 export async function highlightReviewSelectedLines(input: {
   readonly filePath: string;
   readonly lines: ReadonlyArray<ReviewRenderableLineRow>;
diff --git a/apps/mobile/src/features/review/useNativeReviewDiffBridge.ts b/apps/mobile/src/features/review/useNativeReviewDiffBridge.ts
index c6a656e012f7..1728da662686 100644
--- a/apps/mobile/src/features/review/useNativeReviewDiffBridge.ts
+++ b/apps/mobile/src/features/review/useNativeReviewDiffBridge.ts
@@ -8,7 +8,7 @@ import { useNativeReviewDiffHighlighting } from "./useNativeReviewDiffHighlighti
 import { buildNativeReviewTokensResetKey } from "./reviewDiffBridgeKeys";
 import { useUniwindTheme } from "../../lib/useUniwindTheme";
 
-export { buildNativeReviewTokensResetKey, hashReviewDiffKey } from "./reviewDiffBridgeKeys";
+export { buildNativeReviewTokensResetKey } from "./reviewDiffBridgeKeys";
 
 export function useNativeReviewDiffBridge(input: {
   readonly threadKey: string | null;
diff --git a/apps/mobile/src/features/review/useReviewDiffPrewarming.test.ts b/apps/mobile/src/features/review/useReviewDiffPrewarming.test.ts
new file mode 100644
index 000000000000..b58de1ffe467
--- /dev/null
+++ b/apps/mobile/src/features/review/useReviewDiffPrewarming.test.ts
@@ -0,0 +1,177 @@
+import { afterEach, assert, it, vi } from "vite-plus/test";
+
+import { appAtomRegistry } from "../../state/atom-registry";
+import { getCachedNativeReviewDiffData } from "./nativeReviewDiffAdapter";
+import * as ReviewModel from "./reviewModel";
+import { getCachedReviewParsedDiff, MAX_CACHED_REVIEW_SOURCE_CHARACTERS } from "./reviewState";
+import { getReviewDiffPrewarmSections, prewarmReviewDiffSection } from "./useReviewDiffPrewarming";
+
+const threadKey = "env:thread-prewarm";
+const reviewDiff = [
+  "diff --git a/src/a.ts b/src/a.ts",
+  "new file mode 100644",
+  "--- /dev/null",
+  "+++ b/src/a.ts",
+  "@@ -0,0 +1 @@",
+  "+export const value = 1;",
+].join("\n");
+
+function makeSection(index: number, diff: string | null = reviewDiff) {
+  return {
+    id: `turn:${index}`,
+    kind: "turn",
+    title: `Turn ${index}`,
+    subtitle: null,
+    isLoading: false,
+    diff,
+  } satisfies ReviewModel.ReviewSectionItem;
+}
+
+function prepareSelection(
+  sections: ReadonlyArray<ReviewModel.ReviewSectionItem>,
+  selectedSectionId: string,
+) {
+  const section = sections.find((candidate) => candidate.id === selectedSectionId);
+  assert.ok(section);
+  const input = { threadKey, sectionId: section.id, diff: section.diff };
+  const parsed = getCachedReviewParsedDiff(input);
+  const native = getCachedNativeReviewDiffData({ parsedDiff: parsed });
+  for (const pending of getReviewDiffPrewarmSections({ threadKey, sections, selectedSectionId })) {
+    prewarmReviewDiffSection({ threadKey: input.threadKey, section: pending });
+  }
+  assert.strictEqual(getCachedReviewParsedDiff(input), parsed);
+  assert.strictEqual(getCachedNativeReviewDiffData({ parsedDiff: parsed }), native);
+  return { parsed, native };
+}
+
+afterEach(() => {
+  appAtomRegistry.reset();
+  vi.restoreAllMocks();
+});
+
+it("warms the nearest sections within the remaining entry budget", () => {
+  const sections = Array.from({ length: 12 }, (_, index) => makeSection(index));
+
+  const pending = getReviewDiffPrewarmSections({
+    threadKey,
+    sections,
+    selectedSectionId: "turn:5",
+  });
+
+  assert.deepStrictEqual(
+    pending.map((section) => section.id),
+    ["turn:4", "turn:6", "turn:3", "turn:7", "turn:2", "turn:8", "turn:1"],
+  );
+});
+
+it("reserves the selected source budget and skips unloaded or oversized sections", () => {
+  const halfBudget = "x".repeat(2 * 1024 * 1024);
+  const sections = [
+    makeSection(0),
+    makeSection(1, halfBudget),
+    makeSection(2, "x".repeat(MAX_CACHED_REVIEW_SOURCE_CHARACTERS + 1)),
+    makeSection(3, halfBudget),
+    makeSection(4, null),
+    makeSection(5),
+  ];
+
+  const pending = getReviewDiffPrewarmSections({
+    threadKey,
+    sections,
+    selectedSectionId: "turn:3",
+  });
+
+  assert.deepStrictEqual(
+    pending.map((section) => section.id),
+    ["turn:1"],
+  );
+  prepareSelection(sections, "turn:3");
+});
+
+it("reserves a larger retained source when the selected input loses whitespace", () => {
+  const parsed = getCachedReviewParsedDiff({
+    threadKey,
+    sectionId: "turn:0",
+    diff: reviewDiff.padEnd(MAX_CACHED_REVIEW_SOURCE_CHARACTERS, " "),
+  });
+  const native = getCachedNativeReviewDiffData({ parsedDiff: parsed });
+
+  const selected = prepareSelection([makeSection(0), makeSection(1)], "turn:0");
+
+  assert.strictEqual(selected.parsed, parsed);
+  assert.strictEqual(selected.native, native);
+});
+
+it("reserves a larger retained source when a neighboring input loses whitespace", () => {
+  const parsed = getCachedReviewParsedDiff({
+    threadKey,
+    sectionId: "turn:1",
+    diff: reviewDiff.padEnd(MAX_CACHED_REVIEW_SOURCE_CHARACTERS - reviewDiff.length, " "),
+  });
+  const native = getCachedNativeReviewDiffData({ parsedDiff: parsed });
+
+  prepareSelection([makeSection(0), makeSection(1), makeSection(2)], "turn:0");
+
+  assert.strictEqual(
+    getCachedReviewParsedDiff({
+      threadKey,
+      sectionId: "turn:1",
+      diff: reviewDiff,
+    }),
+    parsed,
+  );
+  assert.strictEqual(getCachedNativeReviewDiffData({ parsedDiff: parsed }), native);
+});
+
+it.each([null, "turn:missing"])(
+  "does not prewarm without a selected section: %s",
+  (selectedSectionId) => {
+    assert.deepStrictEqual(
+      getReviewDiffPrewarmSections({ threadKey, sections: [makeSection(0)], selectedSectionId }),
+      [],
+    );
+  },
+);
+
+it("does not prewarm when the selected section exceeds the source budget", () => {
+  const sections = [
+    makeSection(0, "x".repeat(MAX_CACHED_REVIEW_SOURCE_CHARACTERS + 1)),
+    makeSection(1),
+  ];
+
+  assert.deepStrictEqual(
+    getReviewDiffPrewarmSections({ threadKey, sections, selectedSectionId: "turn:0" }),
+    [],
+  );
+});
+
+it("does not parse an oversized direct prewarm that the cache cannot retain", () => {
+  const parse = vi.spyOn(ReviewModel, "buildReviewParsedDiff");
+
+  prewarmReviewDiffSection({
+    threadKey,
+    section: makeSection(0, "x".repeat(MAX_CACHED_REVIEW_SOURCE_CHARACTERS + 1)),
+  });
+
+  assert.strictEqual(parse.mock.calls.length, 0);
+});
+
+it("reuses selected and native results across repeated nearby selections", () => {
+  const parse = vi.spyOn(ReviewModel, "buildReviewParsedDiff");
+  const sections = Array.from({ length: 10 }, (_, index) => makeSection(index));
+  const first = prepareSelection(sections, "turn:0");
+  assert.strictEqual(parse.mock.calls.length, 8);
+  parse.mockClear();
+  const second = prepareSelection(sections, "turn:1");
+
+  for (let pass = 0; pass < 3; pass += 1) {
+    const firstAgain = prepareSelection(sections, "turn:0");
+    assert.strictEqual(firstAgain.parsed, first.parsed);
+    assert.strictEqual(firstAgain.native, first.native);
+    const secondAgain = prepareSelection(sections, "turn:1");
+    assert.strictEqual(secondAgain.parsed, second.parsed);
+    assert.strictEqual(secondAgain.native, second.native);
+  }
+
+  assert.strictEqual(parse.mock.calls.length, 0);
+});
diff --git a/apps/mobile/src/features/review/useReviewDiffPrewarming.ts b/apps/mobile/src/features/review/useReviewDiffPrewarming.ts
index 80a2a64dbf6e..b110a7e2d4c3 100644
--- a/apps/mobile/src/features/review/useReviewDiffPrewarming.ts
+++ b/apps/mobile/src/features/review/useReviewDiffPrewarming.ts
@@ -2,7 +2,12 @@ import { useEffect } from "react";
 
 import { getCachedNativeReviewDiffData } from "./nativeReviewDiffAdapter";
 import type { ReviewSectionItem } from "./reviewModel";
-import { getCachedReviewParsedDiff } from "./reviewState";
+import {
+  getCachedReviewParsedDiff,
+  getReviewParsedDiffSourceCharacterCount,
+  MAX_CACHED_REVIEW_DIFFS,
+  MAX_CACHED_REVIEW_SOURCE_CHARACTERS,
+} from "./reviewState";
 
 interface IdleDeadlineLike {
   readonly didTimeout: boolean;
@@ -35,7 +40,7 @@ export function prewarmReviewDiffSection(input: {
   readonly section: ReviewSectionItem;
 }): void {
   const { section, threadKey } = input;
-  if (section.diff === null) {
+  if (section.diff === null || section.diff.length > MAX_CACHED_REVIEW_SOURCE_CHARACTERS) {
     return;
   }
 
@@ -47,7 +52,54 @@ export function prewarmReviewDiffSection(input: {
   getCachedNativeReviewDiffData({ parsedDiff, comments: [] });
 }
 
-/** Warms one cached section per idle period, after navigation animations finish. */
+/** Selects nearby loaded sections that fit in the cache with the selected section. */
+export function getReviewDiffPrewarmSections(input: {
+  readonly threadKey: string;
+  readonly sections: ReadonlyArray<ReviewSectionItem>;
+  readonly selectedSectionId: string | null;
+}): ReadonlyArray<ReviewSectionItem> {
+  const { threadKey, sections, selectedSectionId } = input;
+  const selectedIndex = sections.findIndex((section) => section.id === selectedSectionId);
+  const selectedSection = sections[selectedIndex];
+  if (!selectedSection) {
+    return [];
+  }
+
+  let sourceCharacterCount = getReviewParsedDiffSourceCharacterCount({
+    threadKey,
+    sectionId: selectedSection.id,
+    diff: selectedSection.diff,
+  });
+  if (sourceCharacterCount > MAX_CACHED_REVIEW_SOURCE_CHARACTERS) {
+    return [];
+  }
+
+  const pendingSections: ReviewSectionItem[] = [];
+  for (let distance = 1; distance < sections.length; distance += 1) {
+    for (const index of [selectedIndex - distance, selectedIndex + distance]) {
+      if (pendingSections.length >= MAX_CACHED_REVIEW_DIFFS - 1) {
+        return pendingSections;
+      }
+      const section = sections[index];
+      if (!section || section.diff === null) {
+        continue;
+      }
+      const sectionCharacterCount = getReviewParsedDiffSourceCharacterCount({
+        threadKey,
+        sectionId: section.id,
+        diff: section.diff,
+      });
+      if (sourceCharacterCount + sectionCharacterCount > MAX_CACHED_REVIEW_SOURCE_CHARACTERS) {
+        continue;
+      }
+      pendingSections.push(section);
+      sourceCharacterCount += sectionCharacterCount;
+    }
+  }
+  return pendingSections;
+}
+
+/** Warms one nearby section per idle period, after navigation animations finish. */
 export function useReviewDiffPrewarming(input: {
   readonly threadKey: string | null;
   readonly sections: ReadonlyArray<ReviewSectionItem>;
@@ -60,9 +112,11 @@ export function useReviewDiffPrewarming(input: {
       return;
     }
 
-    const pendingSections = sections.filter(
-      (section) => section.id !== selectedSectionId && section.diff !== null,
-    );
+    const pendingSections = getReviewDiffPrewarmSections({
+      threadKey,
+      sections,
+      selectedSectionId,
+    });
     if (pendingSections.length === 0) {
       return;
     }
diff --git a/apps/mobile/src/features/settings/ProviderSetupLink.tsx b/apps/mobile/src/features/settings/ProviderSetupLink.tsx
deleted file mode 100644
index 6e402005bdba..000000000000
--- a/apps/mobile/src/features/settings/ProviderSetupLink.tsx
+++ /dev/null
@@ -1,29 +0,0 @@
-import type { ServerProvider } from "@t3tools/contracts";
-import { Pressable } from "react-native";
-
-import { AppText as Text } from "../../components/AppText";
-import { SymbolView } from "../../components/AppSymbol";
-import { ProviderIcon } from "../../components/ProviderIcon";
-import { providerNeedsSetup } from "./provider-setup-state";
-
-export function ProviderSetupLink(props: {
-  readonly provider: ServerProvider;
-  readonly disabled?: boolean;
-  readonly onPress: () => void;
-}) {
-  const label = props.provider.displayName ?? props.provider.driver;
-  return (
-    <Pressable
-      accessibilityRole="button"
-      disabled={props.disabled}
-      onPress={props.onPress}
-      className="min-h-12 flex-row items-center gap-3 px-4 py-3 active:opacity-70 disabled:opacity-40"
-    >
-      <ProviderIcon provider={props.provider.driver} size={18} />
-      <Text className="min-w-0 flex-1 text-base text-foreground">
-        {providerNeedsSetup(props.provider) ? `Set up ${label}` : `Manage ${label}`}
-      </Text>
-      <SymbolView name="chevron.right" size={12} tintColorClassName="accent-foreground" />
-    </Pressable>
-  );
-}
diff --git a/apps/mobile/src/features/settings/SettingsEnvironmentsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsEnvironmentsRouteScreen.tsx
index d40fc462c87e..793d26511553 100644
--- a/apps/mobile/src/features/settings/SettingsEnvironmentsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsEnvironmentsRouteScreen.tsx
@@ -137,12 +137,6 @@ export function SettingsEnvironmentsRouteScreen() {
                   onReconnect={onReconnectEnvironment}
                   onRemove={onRemoveEnvironmentPress}
                   onUpdate={handleUpdateEnvironment}
-                  onSetupProvider={(params) =>
-                    navigation.navigate("SettingsSheet", {
-                      screen: "SettingsContent",
-                      params: { screen: "SettingsProviderSetup", params },
-                    })
-                  }
                 />
               </View>
             ))}
@@ -170,12 +164,6 @@ export function SettingsEnvironmentsRouteScreen() {
         <CloudEnvironmentRows
           connectedCloudEnvironments={connectedCloudEnvironments}
           onReconnectEnvironment={onReconnectEnvironment}
-          onSetupProvider={(params) =>
-            navigation.navigate("SettingsSheet", {
-              screen: "SettingsContent",
-              params: { screen: "SettingsProviderSetup", params },
-            })
-          }
           {...(SHOWCASE_ENABLED
             ? {
                 showcaseAvailableEnvironments: SHOWCASE_AVAILABLE_CLOUD_ENVIRONMENTS,
diff --git a/apps/mobile/src/features/settings/SettingsProviderSetupRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsProviderSetupRouteScreen.tsx
deleted file mode 100644
index 61ca7297fd90..000000000000
--- a/apps/mobile/src/features/settings/SettingsProviderSetupRouteScreen.tsx
+++ /dev/null
@@ -1,574 +0,0 @@
-import { useAtomValue } from "@effect/atom-react";
-import { useNavigation, type StaticScreenProps } from "@react-navigation/native";
-import type { AtomCommandResult } from "@t3tools/client-runtime/state/runtime";
-import {
-  ANTIGRAVITY_AUTH_METHODS,
-  AuthOrchestrationOperateScope,
-  EnvironmentId,
-  ProviderInstanceId,
-} from "@t3tools/contracts";
-import * as Schema from "effect/Schema";
-import { AsyncResult } from "effect/unstable/reactivity";
-import { useCallback, useEffect, useRef, useState } from "react";
-import { Alert, Platform, Pressable, ScrollView, View } from "react-native";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
-
-import { AndroidScreenHeader } from "../../components/AndroidScreenHeader";
-import { AppText as Text, AppTextInput as TextInput } from "../../components/AppText";
-import { ProviderIcon } from "../../components/ProviderIcon";
-import { cn } from "../../lib/cn";
-import { tryCopyTextWithHaptic } from "../../lib/copyTextWithHaptic";
-import { tryOpenExternalUrl } from "../../lib/openExternalUrl";
-import { NativeStackScreenOptions } from "../../native/StackHeader";
-import { appAtomRegistry } from "../../state/atom-registry";
-import { useEnvironments } from "../../state/environments";
-import { useEnvironmentQuery } from "../../state/query";
-import { serverEnvironment } from "../../state/server";
-import { environmentSession } from "../../state/session";
-import { useAtomCommand } from "../../state/use-atom-command";
-import {
-  antigravityEnabledPatch,
-  readAntigravityAuthMethod,
-  resolveProviderSignInPresentation,
-} from "./provider-setup-state";
-
-export type ProviderSetupRouteParams = {
-  readonly environmentId: EnvironmentId;
-  readonly instanceId: ProviderInstanceId;
-};
-
-const PRIVATE_COMMAND_OPTIONS = { reportFailure: false, reportDefect: false } as const;
-const isEnvironmentId = Schema.is(EnvironmentId);
-const isProviderInstanceId = Schema.is(ProviderInstanceId);
-
-function SetupButton(props: {
-  readonly label: string;
-  readonly disabled?: boolean;
-  readonly primary?: boolean;
-  readonly destructive?: boolean;
-  readonly onPress: () => void;
-}) {
-  return (
-    <Pressable
-      accessibilityRole="button"
-      disabled={props.disabled}
-      onPress={props.onPress}
-      className={cn(
-        "min-h-11 items-center justify-center border border-white/25 px-4 py-3 active:opacity-70 disabled:opacity-40",
-        props.primary && "bg-white",
-      )}
-    >
-      <Text
-        className={cn(
-          "text-base font-t3-medium text-white",
-          props.primary && "text-black",
-          props.destructive && "text-red-400",
-        )}
-      >
-        {props.label}
-      </Text>
-    </Pressable>
-  );
-}
-
-/** The same screen stays inside Settings or the current model picker. */
-export function SettingsProviderSetupRouteScreen({
-  route,
-}: StaticScreenProps<ProviderSetupRouteParams>) {
-  if (
-    !isEnvironmentId(route.params?.environmentId) ||
-    !isProviderInstanceId(route.params?.instanceId)
-  ) {
-    return (
-      <View className="flex-1 bg-black p-5">
-        <Text className="text-base text-white">This provider link is not valid.</Text>
-      </View>
-    );
-  }
-  return (
-    <ProviderSetupScreen
-      key={`${route.params.environmentId}:${route.params.instanceId}`}
-      {...route.params}
-    />
-  );
-}
-
-function ProviderSetupScreen({ environmentId, instanceId }: ProviderSetupRouteParams) {
-  const navigation = useNavigation();
-  const insets = useSafeAreaInsets();
-  const { presentationById } = useEnvironments();
-  const environment = presentationById.get(environmentId);
-  const environmentLabel = environment?.entry.target.label ?? "this environment";
-  const isConnected = environment?.connection.phase === "connected";
-  const config = useAtomValue(serverEnvironment.configValueAtom(environmentId));
-  const provider = config?.providers.find((item) => item.instanceId === instanceId);
-  const access = useEnvironmentQuery(environmentSession.sessionStateAtom(environmentId));
-  const canOperate =
-    access.data?.authenticated === true &&
-    access.data.scopes?.includes(AuthOrchestrationOperateScope) === true;
-  const target = { environmentId, input: { instanceId } };
-  const authQuery = useEnvironmentQuery(
-    canOperate && provider?.setup?.canAuthenticate
-      ? serverEnvironment.providerAuthState(target)
-      : null,
-  );
-  const installQuery = useEnvironmentQuery(
-    canOperate && provider?.setup?.canInstall
-      ? serverEnvironment.providerInstallState(target)
-      : null,
-  );
-  const auth = authQuery.data;
-  const installation = installQuery.data;
-  const startAuth = useAtomCommand(serverEnvironment.startProviderAuth, PRIVATE_COMMAND_OPTIONS);
-  const completeAuth = useAtomCommand(
-    serverEnvironment.completeProviderAuth,
-    PRIVATE_COMMAND_OPTIONS,
-  );
-  const cancelAuth = useAtomCommand(serverEnvironment.cancelProviderAuth, PRIVATE_COMMAND_OPTIONS);
-  const logout = useAtomCommand(serverEnvironment.logoutProviderAuth, PRIVATE_COMMAND_OPTIONS);
-  const startInstall = useAtomCommand(
-    serverEnvironment.startProviderInstall,
-    PRIVATE_COMMAND_OPTIONS,
-  );
-  const cancelInstall = useAtomCommand(
-    serverEnvironment.cancelProviderInstall,
-    PRIVATE_COMMAND_OPTIONS,
-  );
-  const removeInstall = useAtomCommand(
-    serverEnvironment.removeProviderInstallation,
-    PRIVATE_COMMAND_OPTIONS,
-  );
-  const updateSettings = useAtomCommand(serverEnvironment.updateSettings, PRIVATE_COMMAND_OPTIONS);
-  const [callbackUrl, setCallbackUrl] = useState("");
-  const [error, setError] = useState<string | null>(null);
-  const [busy, setBusy] = useState(false);
-  const busyRef = useRef(false);
-  const authActive =
-    auth?.phase === "starting" || auth?.phase === "waiting" || auth?.phase === "verifying";
-  const installActive =
-    installation?.phase === "downloading" ||
-    installation?.phase === "extracting" ||
-    installation?.phase === "verifying";
-  const controlsDisabled = busy || !isConnected || !canOperate;
-  const {
-    signedIn,
-    showSignOut,
-    message: authMessage,
-  } = resolveProviderSignInPresentation(provider, auth);
-  const authMethod = readAntigravityAuthMethod(
-    config?.settings.providerInstances[instanceId]?.config ??
-      (instanceId === "antigravity" ? config?.settings.providers.antigravity : undefined),
-  );
-  const usesBrowser = authMethod === "oauth-personal" || authMethod === "oauth-business";
-  const methodLabel =
-    ANTIGRAVITY_AUTH_METHODS.find((method) => method.value === authMethod)?.label ??
-    "Google account";
-
-  // Return URLs never enter saved drafts, navigation params, or diagnostics.
-  useEffect(() => {
-    setCallbackUrl("");
-  }, [auth?.flowId, auth?.phase]);
-
-  const perform = useCallback(
-    async (command: () => Promise<AtomCommandResult<unknown, unknown>>, failureMessage: string) => {
-      if (busyRef.current || !isConnected || !canOperate) return false;
-      busyRef.current = true;
-      setBusy(true);
-      setError(null);
-      try {
-        const result = await command();
-        if (!AsyncResult.isSuccess(result)) {
-          setError(failureMessage);
-          return false;
-        }
-        return true;
-      } catch {
-        setError(failureMessage);
-        return false;
-      } finally {
-        busyRef.current = false;
-        setBusy(false);
-      }
-    },
-    [canOperate, isConnected],
-  );
-
-  const setEnabled = (enabled: boolean) => {
-    const currentConfig = appAtomRegistry.get(serverEnvironment.configValueAtom(environmentId));
-    const currentProvider = currentConfig?.providers.find((item) => item.instanceId === instanceId);
-    if (!currentConfig || !currentProvider) return;
-    const patch = antigravityEnabledPatch(currentConfig.settings, currentProvider, enabled);
-    if (!patch) return;
-    void perform(
-      () => updateSettings({ environmentId, input: { patch } }),
-      "Could not change this provider. Reconnect and try again.",
-    );
-  };
-
-  const title = provider?.displayName ?? "Antigravity";
-  return (
-    <View className="flex-1 bg-black">
-      <NativeStackScreenOptions
-        options={{
-          title,
-          headerShown: Platform.OS !== "android",
-          headerTransparent: false,
-          headerStyle: { backgroundColor: "#000" },
-          headerTintColor: "#fff",
-          contentStyle: { backgroundColor: "#000" },
-        }}
-      />
-      {Platform.OS === "android" ? (
-        <AndroidScreenHeader title={title} onBack={() => navigation.goBack()} />
-      ) : null}
-      <ScrollView
-        className="flex-1"
-        contentInsetAdjustmentBehavior="automatic"
-        contentContainerClassName="gap-5 px-5 pt-5"
-        contentContainerStyle={{ paddingBottom: insets.bottom + 24 }}
-        keyboardShouldPersistTaps="handled"
-        showsVerticalScrollIndicator={false}
-      >
-        <View className="flex-row items-center gap-3">
-          <ProviderIcon provider="antigravity" size={28} />
-          <Text className="min-w-0 flex-1 text-base text-white">{environmentLabel}</Text>
-        </View>
-        {!isConnected ? (
-          <Text className="text-base text-white">
-            Reconnect to this environment to continue setup.
-          </Text>
-        ) : access.error ? (
-          <View className="gap-3">
-            <Text className="text-base text-white">Could not check your environment access.</Text>
-            <SetupButton label="Retry" onPress={access.refresh} />
-          </View>
-        ) : !access.data ? (
-          <Text className="text-base text-white">Checking environment access.</Text>
-        ) : !canOperate ? (
-          <Text className="text-base text-white">
-            This connection cannot manage providers. Pair again with permission to operate this
-            environment.
-          </Text>
-        ) : null}
-        {!config ? (
-          <Text className="text-base text-white">Loading provider settings.</Text>
-        ) : !provider || provider.driver !== "antigravity" ? (
-          <Text className="text-base text-white">
-            This provider is not available on this environment.
-          </Text>
-        ) : (
-          <>
-            <View className="gap-3">
-              <Text className="text-base text-white">
-                {provider.enabled ? "Enabled" : "Disabled"}
-                {provider.installed
-                  ? `. Installed${provider.version ? ` ${provider.version}` : ""}`
-                  : ". Not installed"}
-              </Text>
-              <SetupButton
-                label={provider.enabled ? "Disable Antigravity" : "Enable Antigravity"}
-                disabled={controlsDisabled}
-                onPress={() => {
-                  if (!provider.enabled) {
-                    setEnabled(true);
-                    return;
-                  }
-                  Alert.alert(
-                    "Disable Antigravity?",
-                    `This stops Antigravity sessions on ${environmentLabel}. Google credentials stay saved.`,
-                    [
-                      { text: "Cancel", style: "cancel" },
-                      { text: "Disable", style: "destructive", onPress: () => setEnabled(false) },
-                    ],
-                  );
-                }}
-              />
-            </View>
-            {provider.setup?.canInstall ? (
-              <View className="gap-3 border-t border-white/20 pt-4">
-                {installActive ? (
-                  <>
-                    <Text accessibilityLiveRegion="polite" className="text-base text-white">
-                      {installation.phase === "downloading"
-                        ? `Downloading ${Math.round(installation.downloadedBytes / 1_048_576)}${installation.totalBytes === null ? "" : ` of ${Math.round(installation.totalBytes / 1_048_576)}`} MB`
-                        : installation.phase === "extracting"
-                          ? "Extracting Antigravity files."
-                          : "Checking the Antigravity installation."}
-                    </Text>
-                    <SetupButton
-                      label="Cancel install"
-                      disabled={controlsDisabled || installation.operationId === null}
-                      onPress={() => {
-                        const operationId = installation.operationId;
-                        if (!operationId) return;
-                        void perform(
-                          () =>
-                            cancelInstall({ environmentId, input: { instanceId, operationId } }),
-                          "Could not cancel the install. Try again.",
-                        );
-                      }}
-                    />
-                  </>
-                ) : !provider.installed ? (
-                  <SetupButton
-                    label={
-                      installation?.phase === "failed" || installation?.phase === "cancelled"
-                        ? "Retry install"
-                        : "Install Antigravity"
-                    }
-                    primary
-                    disabled={controlsDisabled || authActive}
-                    onPress={() =>
-                      void perform(
-                        () => startInstall(target),
-                        "Could not start the install. Try again.",
-                      )
-                    }
-                  />
-                ) : null}
-                {installation?.message ? (
-                  <Text className="text-sm text-white">{installation.message}</Text>
-                ) : null}
-                {installation?.canRemove && !installActive ? (
-                  <SetupButton
-                    label="Remove managed install"
-                    destructive
-                    disabled={controlsDisabled || authActive}
-                    onPress={() => {
-                      Alert.alert(
-                        "Remove the Antigravity install?",
-                        `This removes T3's managed install from ${environmentLabel}. Providers that use it will need it installed again. Google credentials and threads stay.`,
-                        [
-                          { text: "Cancel", style: "cancel" },
-                          {
-                            text: "Remove",
-                            style: "destructive",
-                            onPress: () =>
-                              void perform(
-                                () => removeInstall(target),
-                                "Could not remove the managed install. Try again.",
-                              ),
-                          },
-                        ],
-                      );
-                    }}
-                  />
-                ) : null}
-                {installQuery.error ? (
-                  <Text className="text-sm text-white">
-                    Install status is unavailable. Reconnect and try again.
-                  </Text>
-                ) : null}
-              </View>
-            ) : !provider.installed ? (
-              <Text className="text-base text-white">
-                Antigravity cannot be installed on this environment. Use a supported server host or
-                set an executable path in provider settings.
-              </Text>
-            ) : null}
-            {provider.setup?.canAuthenticate ? (
-              <View className="gap-3 border-t border-white/20 pt-4">
-                <Text className="text-lg font-t3-medium text-white">{methodLabel}</Text>
-                <Text className="text-base text-white">
-                  {signedIn
-                    ? "Signed in. Credentials stay on this environment."
-                    : provider.auth.status === "unknown"
-                      ? "Sign-in has not been checked."
-                      : usesBrowser
-                        ? "Sign in with the Google account you use for Antigravity."
-                        : "Connect with the credentials set in provider settings on web or desktop."}
-                </Text>
-                {authActive ? (
-                  <>
-                    <Text accessibilityLiveRegion="polite" className="text-base text-white">
-                      {auth.phase === "starting"
-                        ? usesBrowser
-                          ? "Starting Google sign-in."
-                          : "Checking credentials."
-                        : auth.phase === "verifying"
-                          ? usesBrowser
-                            ? "Checking Google sign-in."
-                            : "Checking credentials."
-                          : auth.authorizationUrl
-                            ? "Complete sign-in in your browser."
-                            : "Sign-in is open on another client. Complete it there or wait for it to expire."}
-                    </Text>
-                    {auth.authorizationUrl && auth.phase === "waiting" ? (
-                      <>
-                        <SetupButton
-                          label="Open Google sign-in"
-                          primary
-                          disabled={controlsDisabled}
-                          onPress={() => {
-                            if (!auth.authorizationUrl) return;
-                            void tryOpenExternalUrl(auth.authorizationUrl, "provider-auth").then(
-                              (opened) => {
-                                if (!opened)
-                                  setError(
-                                    "Could not open Google sign-in. Copy the link and open it in your browser.",
-                                  );
-                              },
-                            );
-                          }}
-                        />
-                        <SetupButton
-                          label="Copy sign-in link"
-                          disabled={controlsDisabled}
-                          onPress={() => {
-                            if (!auth.authorizationUrl) return;
-                            void tryCopyTextWithHaptic(auth.authorizationUrl, {
-                              target: "provider-sign-in-link",
-                            }).then((copied) => {
-                              if (!copied) setError("Could not copy the sign-in link.");
-                            });
-                          }}
-                        />
-                        <Text className="text-sm leading-5 text-white">
-                          After sign-in, the browser will open a 127.0.0.1 address that cannot load
-                          on your phone. Copy that full address and paste it here.
-                        </Text>
-                        <TextInput
-                          accessibilityLabel="Google sign-in return URL"
-                          autoCapitalize="none"
-                          autoComplete="off"
-                          autoCorrect={false}
-                          className="min-h-12 rounded-none border border-white/25 bg-black px-3 py-3 text-base text-white"
-                          editable={!controlsDisabled}
-                          keyboardType="url"
-                          onChangeText={setCallbackUrl}
-                          placeholder="http://127.0.0.1:.../"
-                          textContentType="none"
-                          value={callbackUrl}
-                        />
-                        <SetupButton
-                          label="Complete sign-in"
-                          primary
-                          disabled={
-                            controlsDisabled || callbackUrl.trim().length === 0 || !auth.flowId
-                          }
-                          onPress={() => {
-                            const flowId = auth.flowId;
-                            if (!flowId) return;
-                            const submittedUrl = callbackUrl.trim();
-                            setCallbackUrl("");
-                            void perform(
-                              () =>
-                                completeAuth({
-                                  environmentId,
-                                  input: { instanceId, flowId, callbackUrl: submittedUrl },
-                                }),
-                              "Could not complete Google sign-in. Check the return URL and try again.",
-                            );
-                          }}
-                        />
-                      </>
-                    ) : null}
-                    {auth.expiresAt ? (
-                      <Text className="text-sm text-white">
-                        Sign-in expires at{" "}
-                        {new Date(auth.expiresAt).toLocaleTimeString([], {
-                          hour: "numeric",
-                          minute: "2-digit",
-                        })}
-                        .
-                      </Text>
-                    ) : null}
-                    {auth.flowId ? (
-                      <SetupButton
-                        label="Cancel sign-in"
-                        disabled={controlsDisabled}
-                        onPress={() => {
-                          const flowId = auth.flowId;
-                          if (!flowId) return;
-                          setCallbackUrl("");
-                          void perform(
-                            () => cancelAuth({ environmentId, input: { instanceId, flowId } }),
-                            "Could not cancel sign-in. Try again.",
-                          );
-                        }}
-                      />
-                    ) : null}
-                  </>
-                ) : showSignOut ? (
-                  <SetupButton
-                    label={usesBrowser ? "Sign out of Google" : "Disconnect"}
-                    destructive
-                    disabled={controlsDisabled}
-                    onPress={() => {
-                      Alert.alert(
-                        usesBrowser ? "Sign out of Google?" : "Disconnect Antigravity?",
-                        `This stops Antigravity sessions for ${title} on ${environmentLabel}. Threads and files stay.`,
-                        [
-                          { text: "Cancel", style: "cancel" },
-                          {
-                            text: "Sign out",
-                            style: "destructive",
-                            onPress: () =>
-                              void perform(
-                                () => logout(target),
-                                "Could not sign out of Google. Try again.",
-                              ),
-                          },
-                        ],
-                      );
-                    }}
-                  />
-                ) : (
-                  <SetupButton
-                    label={
-                      usesBrowser
-                        ? auth?.phase === "failed" || auth?.phase === "cancelled"
-                          ? "Retry Google sign-in"
-                          : "Sign in with Google"
-                        : auth?.phase === "failed" || auth?.phase === "cancelled"
-                          ? "Retry connection"
-                          : "Connect"
-                    }
-                    primary
-                    disabled={
-                      controlsDisabled ||
-                      !provider.enabled ||
-                      !provider.installed ||
-                      installActive ||
-                      authQuery.isPending
-                    }
-                    onPress={() =>
-                      void perform(
-                        () => startAuth(target),
-                        "Could not start Google sign-in. Try again.",
-                      )
-                    }
-                  />
-                )}
-                {!provider.enabled && !signedIn ? (
-                  <Text className="text-sm text-white">Enable Antigravity to sign in.</Text>
-                ) : !provider.installed && !signedIn ? (
-                  <Text className="text-sm text-white">Install Antigravity to sign in.</Text>
-                ) : null}
-                {authMessage ? <Text className="text-sm text-white">{authMessage}</Text> : null}
-                {authQuery.error ? (
-                  <Text className="text-sm text-white">
-                    Sign-in status is unavailable. Reconnect and try again.
-                  </Text>
-                ) : null}
-              </View>
-            ) : null}
-            {provider.message ? (
-              <Text className="text-sm text-white">{provider.message}</Text>
-            ) : null}
-          </>
-        )}
-        {error ? (
-          <Text accessibilityRole="alert" className="text-base text-red-400">
-            {error}
-          </Text>
-        ) : null}
-        {busy ? (
-          <Text accessibilityLiveRegion="polite" className="text-sm text-white">
-            Waiting for the environment.
-          </Text>
-        ) : null}
-      </ScrollView>
-    </View>
-  );
-}
diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
index 41c2076ac7b4..3bd25a20c8da 100644
--- a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
@@ -44,6 +44,7 @@ import {
   type ServerSettingsPatch,
 } from "@t3tools/contracts";
 import {
+  filterSharedServerPatch,
   findSharedSettingsMismatches,
   pickSharedServerSettings,
   supportsSharedSettingsSync,
@@ -584,11 +585,13 @@ function AutoSettleSettingsRows() {
   const mismatches = findSharedSettingsMismatches({
     primaryEnvironmentId: reference.environmentId,
     primarySettings: referenceSettings,
+    primaryCapabilities: reference.serverConfig?.environment.capabilities,
     environments: environments.map((environment) => ({
       environmentId: environment.environmentId,
       label: environment.label,
       syncEligible: supportsSharedSettingsSync(environment),
       settings: environment.serverConfig?.settings ?? null,
+      capabilities: environment.serverConfig?.environment.capabilities,
     })),
   });
 
@@ -652,11 +655,22 @@ function AutoSettleSettingsRows() {
           <Pressable
             accessibilityRole="button"
             onPress={() => {
-              const patch = pickSharedServerSettings(referenceSettings);
+              const patch = pickSharedServerSettings(
+                referenceSettings,
+                reference.serverConfig?.environment.capabilities,
+              );
               for (const mismatch of mismatches) {
+                const target = environments.find(
+                  (candidate) => candidate.environmentId === mismatch.environmentId,
+                );
                 void updateSettings({
                   environmentId: mismatch.environmentId,
-                  input: { patch },
+                  input: {
+                    patch: filterSharedServerPatch(
+                      patch,
+                      target?.serverConfig?.environment.capabilities,
+                    ),
+                  },
                 });
               }
             }}
diff --git a/apps/mobile/src/features/settings/appearance/AppearancePreferencesProvider.tsx b/apps/mobile/src/features/settings/appearance/AppearancePreferencesProvider.tsx
index 79d67ebaa7c2..f161e654788b 100644
--- a/apps/mobile/src/features/settings/appearance/AppearancePreferencesProvider.tsx
+++ b/apps/mobile/src/features/settings/appearance/AppearancePreferencesProvider.tsx
@@ -37,7 +37,6 @@ import {
   getMobileUniwindThemeName,
   type MobileThemeRuntimeState,
 } from "../../../lib/mobileThemeRuntime";
-import { cacheTerminalFontSize } from "../../terminal/terminalUiState";
 
 interface AppearancePreferencesContextValue {
   /** Effective values with base-size derivation applied. Use this for rendering. */
@@ -143,8 +142,7 @@ export function AppearancePreferencesProvider(props: { readonly children: ReactN
   useLayoutEffect(() => {
     selectedThemeIdsRef.current = themeIds;
     syncThemeRuntime(runtimeState);
-    cacheTerminalFontSize(appearance.terminalFontSize);
-  }, [appearance.terminalFontSize, runtimeState, syncThemeRuntime, themeIds]);
+  }, [runtimeState, syncThemeRuntime, themeIds]);
 
   const setThemeIdForAppearance = useCallback(
     (appearance: MobileThemeAppearance, value: MobileThemeId) => {
diff --git a/apps/mobile/src/features/settings/provider-setup-state.test.ts b/apps/mobile/src/features/settings/provider-setup-state.test.ts
deleted file mode 100644
index 3f85b41f2c4e..000000000000
--- a/apps/mobile/src/features/settings/provider-setup-state.test.ts
+++ /dev/null
@@ -1,159 +0,0 @@
-import {
-  DEFAULT_SERVER_SETTINGS,
-  ProviderDriverKind,
-  ProviderInstanceId,
-  ServerProvider,
-  resolveProviderInstanceEnabled,
-} from "@t3tools/contracts";
-import * as Schema from "effect/Schema";
-import { describe, expect, it } from "vite-plus/test";
-
-import { antigravityEnabledPatch, resolveProviderSignInPresentation } from "./provider-setup-state";
-
-const provider = Schema.decodeSync(ServerProvider)({
-  instanceId: "antigravity",
-  driver: "antigravity",
-  enabled: false,
-  installed: false,
-  version: null,
-  status: "disabled",
-  auth: { status: "unauthenticated" },
-  checkedAt: "2026-09-02T00:00:00.000Z",
-  models: [],
-});
-
-describe("resolveProviderSignInPresentation", () => {
-  const completedFlow = { phase: "succeeded", message: "Google sign-in is complete." } as const;
-
-  it("offers sign-in after saved credentials expire, even if the old flow succeeded", () => {
-    expect(
-      resolveProviderSignInPresentation(
-        {
-          enabled: true,
-          auth: { status: "authenticated" },
-        },
-        completedFlow,
-      ),
-    ).toEqual({
-      signedIn: true,
-      showSignOut: true,
-      message: completedFlow.message,
-    });
-
-    expect(
-      resolveProviderSignInPresentation(
-        {
-          enabled: true,
-          auth: { status: "unauthenticated" },
-        },
-        completedFlow,
-      ),
-    ).toEqual({
-      signedIn: false,
-      showSignOut: false,
-      message: null,
-    });
-  });
-
-  it("allows credential cleanup without claiming a disabled unknown account is signed in", () => {
-    expect(
-      resolveProviderSignInPresentation(
-        {
-          enabled: false,
-          auth: { status: "unknown" },
-        },
-        completedFlow,
-      ),
-    ).toEqual({
-      signedIn: false,
-      showSignOut: true,
-      message: null,
-    });
-  });
-
-  it("keeps progress while Google sign-in is still pending", () => {
-    const flow = { phase: "verifying", message: "Checking Google sign-in." } as const;
-    expect(
-      resolveProviderSignInPresentation(
-        {
-          enabled: true,
-          auth: { status: "unauthenticated" },
-        },
-        flow,
-      ),
-    ).toEqual({
-      signedIn: false,
-      showSignOut: false,
-      message: flow.message,
-    });
-  });
-});
-
-describe("antigravityEnabledPatch", () => {
-  it("enables a legacy instance without losing its executable path or models", () => {
-    const settings = {
-      ...DEFAULT_SERVER_SETTINGS,
-      providers: {
-        ...DEFAULT_SERVER_SETTINGS.providers,
-        antigravity: {
-          ...DEFAULT_SERVER_SETTINGS.providers.antigravity,
-          enabled: false,
-          binaryPath: "/opt/google/agy-acp",
-          customModels: ["gemini-native"],
-        },
-      },
-    };
-    const patch = antigravityEnabledPatch(settings, provider, true);
-    const instance = patch?.providerInstances?.[provider.instanceId];
-
-    expect(instance).toMatchObject({
-      enabled: true,
-      config: { binaryPath: "/opt/google/agy-acp", customModels: ["gemini-native"] },
-    });
-    expect(instance?.config).not.toHaveProperty("enabled");
-    expect(instance && resolveProviderInstanceEnabled(instance)).toBe(true);
-    expect(settings.providers.antigravity.enabled).toBe(false);
-  });
-
-  it("keeps separate accounts and environment overrides when enabling a custom instance", () => {
-    const workId = ProviderInstanceId.make("google_work");
-    const personalId = ProviderInstanceId.make("google_personal");
-    const personal = { driver: ProviderDriverKind.make("antigravity"), enabled: true };
-    const settings = {
-      ...DEFAULT_SERVER_SETTINGS,
-      providerInstances: {
-        [personalId]: personal,
-        [workId]: {
-          driver: ProviderDriverKind.make("antigravity"),
-          displayName: "Work Google",
-          enabled: false,
-          config: { enabled: false, binaryPath: "/work/agy-acp", futureSetting: "keep" },
-          environment: [{ name: "WORK_PROXY", value: "http://proxy", sensitive: false }],
-        },
-      },
-    };
-    const patch = antigravityEnabledPatch(settings, { ...provider, instanceId: workId }, true);
-
-    expect(patch?.providerInstances?.[personalId]).toBe(personal);
-    expect(patch?.providerInstances?.[workId]).toMatchObject({
-      displayName: "Work Google",
-      enabled: true,
-      config: { binaryPath: "/work/agy-acp", futureSetting: "keep" },
-      environment: [{ name: "WORK_PROXY", value: "http://proxy", sensitive: false }],
-    });
-    expect(patch?.providers).toBeUndefined();
-  });
-
-  it("does not change a different driver", () => {
-    expect(
-      antigravityEnabledPatch(
-        DEFAULT_SERVER_SETTINGS,
-        {
-          ...provider,
-          driver: ProviderDriverKind.make("codex"),
-        },
-        true,
-      ),
-    ).toBeNull();
-  });
-});
diff --git a/apps/mobile/src/features/settings/provider-setup-state.ts b/apps/mobile/src/features/settings/provider-setup-state.ts
deleted file mode 100644
index 4bb9aebd8f6d..000000000000
--- a/apps/mobile/src/features/settings/provider-setup-state.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import {
-  ANTIGRAVITY_AUTH_METHODS,
-  type AntigravityAuthMethod,
-  DEFAULT_SERVER_SETTINGS,
-  type ProviderAuthState,
-  type ServerProvider,
-  type ServerSettings,
-  type ServerSettingsPatch,
-} from "@t3tools/contracts";
-
-/** Read the configured method from an instance config. Unknown values fall back to personal. */
-export function readAntigravityAuthMethod(config: unknown): AntigravityAuthMethod {
-  const value =
-    config !== null && typeof config === "object" && "authMethod" in config
-      ? config.authMethod
-      : undefined;
-  return (
-    ANTIGRAVITY_AUTH_METHODS.find((method) => method.value === value)?.value ?? "oauth-personal"
-  );
-}
-
-/** A completed sign-in flow does not prove that saved credentials are still valid. */
-export function resolveProviderSignInPresentation(
-  provider: Pick<ServerProvider, "enabled" | "auth"> | undefined,
-  flow: Pick<ProviderAuthState, "phase" | "message"> | null,
-) {
-  const signedIn = provider?.auth.status === "authenticated";
-  return {
-    signedIn,
-    showSignOut: signedIn || (provider?.enabled === false && provider.auth.status === "unknown"),
-    message: flow?.phase === "succeeded" && !signedIn ? null : (flow?.message ?? null),
-  };
-}
-
-/** Keep one enabled flag when a legacy provider becomes an explicit instance. */
-export function antigravityEnabledPatch(
-  settings: ServerSettings,
-  provider: ServerProvider,
-  enabled: boolean,
-): ServerSettingsPatch | null {
-  if (provider.driver !== "antigravity") return null;
-
-  const { enabled: _legacyEnabled, ...legacyConfig } = settings.providers.antigravity;
-  const instance = settings.providerInstances[provider.instanceId] ?? {
-    driver: provider.driver,
-    config: legacyConfig,
-  };
-  const config =
-    instance.config !== null &&
-    typeof instance.config === "object" &&
-    !Array.isArray(instance.config)
-      ? Object.fromEntries(Object.entries(instance.config).filter(([key]) => key !== "enabled"))
-      : instance.config;
-
-  return {
-    ...(provider.instanceId === "antigravity"
-      ? { providers: { antigravity: DEFAULT_SERVER_SETTINGS.providers.antigravity } }
-      : {}),
-    providerInstances: {
-      ...settings.providerInstances,
-      [provider.instanceId]: { ...instance, enabled, config },
-    },
-  };
-}
-
-/** Setup remains available when the provider has no selectable models. */
-export function providerNeedsSetup(provider: ServerProvider): boolean {
-  return (
-    (provider.setup?.canAuthenticate === true || provider.setup?.canInstall === true) &&
-    (!provider.enabled ||
-      !provider.installed ||
-      provider.auth.status !== "authenticated" ||
-      provider.availability === "unavailable" ||
-      provider.models.length === 0)
-  );
-}
diff --git a/apps/mobile/src/features/terminal/ThreadTerminalRouteScreen.tsx b/apps/mobile/src/features/terminal/ThreadTerminalRouteScreen.tsx
index f370401e8ecc..351082580d63 100644
--- a/apps/mobile/src/features/terminal/ThreadTerminalRouteScreen.tsx
+++ b/apps/mobile/src/features/terminal/ThreadTerminalRouteScreen.tsx
@@ -6,6 +6,8 @@ import { NativeHeaderToolbar, NativeStackScreenOptions } from "../../native/Stac
 import { StackActions, useNavigation, type StaticScreenProps } from "@react-navigation/native";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Platform, Pressable, View } from "react-native";
+import * as Clipboard from "expo-clipboard";
+import * as Schema from "effect/Schema";
 import {
   KeyboardController,
   KeyboardEvents,
@@ -27,6 +29,7 @@ import { environmentCatalog } from "../../connection/catalog";
 import { useEnvironmentPresentation } from "../../state/presentation";
 import { terminalEnvironment } from "../../state/terminal";
 import { useAtomCommand } from "../../state/use-atom-command";
+import { useServerConfigs } from "../../state/entities";
 import { useWorkspaceState } from "../../state/workspace";
 import {
   MAX_TERMINAL_FONT_SIZE,
@@ -65,6 +68,13 @@ import {
   resolveTerminalSessionLabel,
   type TerminalMenuSession,
 } from "./terminalMenu";
+import {
+  hostPlatformFromOs,
+  resolveModifiedTerminalInput,
+  type HostPlatform,
+  type PendingModifier,
+} from "./terminalInput";
+import { createTerminalPasteSession } from "./terminalPaste";
 import { cacheTerminalGridSize, getCachedTerminalGridSize } from "./terminalUiState";
 
 const DEFAULT_TERMINAL_COLS = 80;
@@ -72,12 +82,19 @@ const DEFAULT_TERMINAL_ROWS = 24;
 const TERMINAL_ACCESSORY_HEIGHT = 52;
 const SHOWCASE_ENABLED = process.env.EXPO_PUBLIC_SHOWCASE === "1";
 
-type PendingModifier = "ctrl" | "meta";
-type HostPlatform = "mac" | "linux" | "windows" | "unknown";
+class TerminalClipboardReadError extends Schema.TaggedErrorClass<TerminalClipboardReadError>()(
+  "TerminalClipboardReadError",
+  { terminalId: Schema.String, cause: Schema.Defect() },
+) {
+  override get message(): string {
+    return `Failed to read the clipboard for a paste into terminal ${this.terminalId}.`;
+  }
+}
 
 type TerminalToolbarAction =
   | { readonly kind: "send"; readonly key: string; readonly label: string; readonly data: string }
   | { readonly kind: "clear"; readonly key: string; readonly label: string }
+  | { readonly kind: "paste"; readonly key: string; readonly label: string }
   | {
       readonly kind: "modifier";
       readonly key: string;
@@ -114,28 +131,6 @@ function inferHostPlatform(environmentLabel: string | null): HostPlatform {
   return "unknown";
 }
 
-function applyCtrlModifier(input: string): string {
-  const firstCharacter = input[0];
-  if (!firstCharacter) {
-    return input;
-  }
-
-  const lowerCharacter = firstCharacter.toLowerCase();
-  if (lowerCharacter >= "a" && lowerCharacter <= "z") {
-    return String.fromCharCode(lowerCharacter.charCodeAt(0) - 96);
-  }
-
-  if (firstCharacter === "@") return "\u0000";
-  if (firstCharacter === "[") return "\u001b";
-  if (firstCharacter === "\\") return "\u001c";
-  if (firstCharacter === "]") return "\u001d";
-  if (firstCharacter === "^") return "\u001e";
-  if (firstCharacter === "_") return "\u001f";
-  if (firstCharacter === "?") return "\u007f";
-
-  return input;
-}
-
 function pickRunningTerminalSessionForBootstrap(
   sessions: ReadonlyArray<KnownTerminalSession>,
 ): KnownTerminalSession | null {
@@ -462,9 +457,17 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
     });
   }, [terminal.buffer, terminal.buffer.length, terminalKey]);
   const cwd = terminal.summary?.cwd ?? selectedThreadProject?.workspaceRoot ?? null;
+  const serverConfigs = useServerConfigs();
+  const hostOs =
+    routeEnvironmentId === null
+      ? null
+      : (serverConfigs.get(routeEnvironmentId)?.environment.platform.os ?? null);
+  // The descriptor is authoritative; the label is only a hint until it arrives.
   const hostPlatform = useMemo(
-    () => inferHostPlatform(selectedEnvironmentConnection?.environmentLabel ?? null),
-    [selectedEnvironmentConnection?.environmentLabel],
+    () =>
+      hostPlatformFromOs(hostOs) ??
+      inferHostPlatform(selectedEnvironmentConnection?.environmentLabel ?? null),
+    [hostOs, selectedEnvironmentConnection?.environmentLabel],
   );
 
   const terminalTheme = getMobileTerminalTheme(themeId, appearanceScheme);
@@ -488,6 +491,7 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
       { kind: "send", key: "esc", label: "esc", data: "\u001b" },
       ...modifierActions,
       { kind: "send", key: "tab", label: "tab", data: "\t" },
+      { kind: "paste", key: "paste", label: "paste" },
       { kind: "clear", key: "clear", label: "clear" },
       { kind: "send", key: "up", label: "↑", data: "\u001b[A" },
       { kind: "send", key: "down", label: "↓", data: "\u001b[B" },
@@ -693,13 +697,14 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
     setHasMeasuredSurface(true);
   }, [routeEnvironmentId, routeThreadId, terminalId]);
 
+  /** Resolves true once the pty accepted the write, false if it was skipped or rejected. */
   const writeInput = useCallback(
-    (data: string) => {
+    async (data: string): Promise<boolean> => {
       if (!selectedThread || !isRunning) {
-        return;
+        return false;
       }
 
-      void writeTerminal({
+      const result = await writeTerminal({
         environmentId: selectedThread.environmentId,
         input: {
           threadId: selectedThread.id,
@@ -707,27 +712,67 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
           data,
         },
       });
+      return result._tag === "Success";
     },
     [isRunning, selectedThread, terminalId, writeTerminal],
   );
 
+  const pasteSessionRef = useRef<ReturnType<typeof createTerminalPasteSession> | null>(null);
+  if (pasteSessionRef.current === null) {
+    pasteSessionRef.current = createTerminalPasteSession();
+  }
+  const pasteSession = pasteSessionRef.current;
+
+  // Drop delayed clipboard reads whenever the route or attached pty changes.
+  useEffect(() => {
+    pasteSession.reset(isRunning);
+    return () => {
+      pasteSession.reset(false);
+    };
+  }, [isRunning, pasteSession, terminal.lifecycleVersion, terminalKey]);
+
+  const pasteFromClipboard = useCallback(async () => {
+    await pasteSession.paste({
+      readText: Clipboard.getStringAsync,
+      write: writeInput,
+      onReadError: (cause) => {
+        console.error(new TerminalClipboardReadError({ terminalId, cause }));
+      },
+    });
+  }, [pasteSession, terminalId, writeInput]);
+
+  /** Sends a key through the armed toolbar modifier, if any, and disarms it. */
+  const writeModifiedInput = useCallback(
+    (data: string) => {
+      if (pendingModifier === null) {
+        void writeInput(data);
+        return;
+      }
+
+      setPendingModifierState({ terminalId, value: null });
+      const resolved = resolveModifiedTerminalInput({
+        data,
+        modifier: pendingModifier,
+        hostPlatform,
+      });
+      if (resolved.kind === "paste") {
+        void pasteFromClipboard();
+        return;
+      }
+      void writeInput(resolved.data);
+    },
+    [hostPlatform, pasteFromClipboard, pendingModifier, terminalId, writeInput],
+  );
+
   const handleInput = useCallback(
     (data: string) => {
       if (data.length === 0) {
         return;
       }
 
-      if (pendingModifier === "ctrl") {
-        setPendingModifierState({ terminalId, value: null });
-        writeInput(applyCtrlModifier(data));
-      } else if (pendingModifier === "meta") {
-        setPendingModifierState({ terminalId, value: null });
-        writeInput(`\u001b${data}`);
-      } else {
-        writeInput(data);
-      }
+      writeModifiedInput(data);
     },
-    [pendingModifier, terminalId, writeInput],
+    [writeModifiedInput],
   );
 
   const handleResize = useCallback(
@@ -948,16 +993,14 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
           },
         ],
       },
-      ...terminalMenuSessions.map(
-        (session): MenuAction => ({
-          id: `terminal-session:${session.terminalId}`,
-          title: session.displayLabel,
-          subtitle: [getTerminalStatusLabel({ status: session.status }), basename(session.cwd)]
-            .filter(Boolean)
-            .join(" · "),
-          state: session.terminalId === terminalId ? ("on" as const) : undefined,
-        }),
-      ),
+      ...terminalMenuSessions.map((session): MenuAction => ({
+        id: `terminal-session:${session.terminalId}`,
+        title: session.displayLabel,
+        subtitle: [getTerminalStatusLabel({ status: session.status }), basename(session.cwd)]
+          .filter(Boolean)
+          .join(" · "),
+        state: session.terminalId === terminalId ? ("on" as const) : undefined,
+      })),
       {
         id: "terminal-new",
         title: "Open new terminal",
@@ -1023,16 +1066,15 @@ export function ThreadTerminalRouteScreen(props: ThreadTerminalRouteScreenProps)
         return;
       }
 
-      setPendingModifierState({ terminalId, value: null });
-      if (pendingModifier === "ctrl") {
-        writeInput(applyCtrlModifier(action.data));
-      } else if (pendingModifier === "meta") {
-        writeInput(`\u001b${action.data}`);
-      } else {
-        writeInput(action.data);
+      if (action.kind === "paste") {
+        setPendingModifierState({ terminalId, value: null });
+        void pasteFromClipboard();
+        return;
       }
+
+      writeModifiedInput(action.data);
     },
-    [handleClearTerminal, pendingModifier, terminalId, writeInput],
+    [handleClearTerminal, pasteFromClipboard, terminalId, writeModifiedInput],
   );
 
   const handleDismissKeyboard = useCallback(() => {
diff --git a/apps/mobile/src/features/terminal/terminalInput.test.ts b/apps/mobile/src/features/terminal/terminalInput.test.ts
new file mode 100644
index 000000000000..aebc00649cec
--- /dev/null
+++ b/apps/mobile/src/features/terminal/terminalInput.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  applyCtrlModifier,
+  chunkTerminalWrite,
+  encodeTerminalPaste,
+  hostPlatformFromOs,
+  resolveModifiedTerminalInput,
+  TERMINAL_WRITE_MAX_LENGTH,
+} from "./terminalInput";
+
+const byte = (code: number) => String.fromCharCode(code);
+const ESC = byte(0x1b);
+const CTRL_C = byte(0x03);
+const CTRL_V = byte(0x16);
+
+describe("applyCtrlModifier", () => {
+  it("maps letters to control bytes regardless of case", () => {
+    expect(applyCtrlModifier("c")).toBe(CTRL_C);
+    expect(applyCtrlModifier("C")).toBe(CTRL_C);
+    expect(applyCtrlModifier("z")).toBe(byte(0x1a));
+  });
+
+  it("maps the punctuation control keys and leaves the rest untouched", () => {
+    expect(applyCtrlModifier("[")).toBe(ESC);
+    expect(applyCtrlModifier("?")).toBe(byte(0x7f));
+    expect(applyCtrlModifier("1")).toBe("1");
+    expect(applyCtrlModifier("")).toBe("");
+  });
+});
+
+describe("resolveModifiedTerminalInput", () => {
+  it("pastes on ctrl+v for windows, linux, and unknown hosts", () => {
+    for (const hostPlatform of ["windows", "linux", "unknown"] as const) {
+      expect(resolveModifiedTerminalInput({ data: "v", modifier: "ctrl", hostPlatform })).toEqual({
+        kind: "paste",
+      });
+      expect(resolveModifiedTerminalInput({ data: "V", modifier: "ctrl", hostPlatform })).toEqual({
+        kind: "paste",
+      });
+    }
+  });
+
+  it("keeps alt+v as a meta chord on non-mac hosts", () => {
+    expect(
+      resolveModifiedTerminalInput({ data: "v", modifier: "meta", hostPlatform: "windows" }),
+    ).toEqual({ kind: "write", data: `${ESC}v` });
+  });
+
+  it("pastes on cmd+v and forwards raw ctrl+v on mac hosts", () => {
+    expect(
+      resolveModifiedTerminalInput({ data: "v", modifier: "meta", hostPlatform: "mac" }),
+    ).toEqual({ kind: "paste" });
+    expect(
+      resolveModifiedTerminalInput({ data: "v", modifier: "ctrl", hostPlatform: "mac" }),
+    ).toEqual({ kind: "write", data: CTRL_V });
+  });
+
+  it("still encodes every other modified key", () => {
+    expect(
+      resolveModifiedTerminalInput({ data: "c", modifier: "ctrl", hostPlatform: "windows" }),
+    ).toEqual({ kind: "write", data: CTRL_C });
+    expect(
+      resolveModifiedTerminalInput({ data: "[A", modifier: "meta", hostPlatform: "linux" }),
+    ).toEqual({ kind: "write", data: `${ESC}[A` });
+  });
+});
+
+describe("encodeTerminalPaste", () => {
+  it("passes single-line text through unchanged", () => {
+    expect(encodeTerminalPaste("git switch -c fix/paste")).toBe("git switch -c fix/paste");
+    expect(encodeTerminalPaste("")).toBe("");
+  });
+
+  it("turns LF and CRLF line breaks into a single carriage return each", () => {
+    expect(encodeTerminalPaste("one\ntwo\r\nthree\n")).toBe("one\rtwo\rthree\r");
+  });
+
+  it("replaces unsafe control bytes with spaces but keeps tabs", () => {
+    expect(encodeTerminalPaste(`a${byte(0)}b${ESC}c${byte(0x7f)}d\te`)).toBe("a b c d\te");
+  });
+
+  it("never lets a bracketed-paste end marker reach the shell", () => {
+    expect(encodeTerminalPaste(`safe${ESC}[201~; rm -rf /\n`)).toBe("safe [201~; rm -rf /\r");
+  });
+});
+
+describe("chunkTerminalWrite", () => {
+  it("leaves writes within the wire limit whole", () => {
+    expect(chunkTerminalWrite("")).toEqual([]);
+    expect(chunkTerminalWrite("ls")).toEqual(["ls"]);
+    expect(chunkTerminalWrite("x".repeat(TERMINAL_WRITE_MAX_LENGTH))).toHaveLength(1);
+  });
+
+  it("splits oversized writes so every chunk fits the contract", () => {
+    const chunks = chunkTerminalWrite("y".repeat(TERMINAL_WRITE_MAX_LENGTH * 2 + 5));
+    expect(chunks.map((chunk) => chunk.length)).toEqual([
+      TERMINAL_WRITE_MAX_LENGTH,
+      TERMINAL_WRITE_MAX_LENGTH,
+      5,
+    ]);
+    expect(chunks.join("")).toHaveLength(TERMINAL_WRITE_MAX_LENGTH * 2 + 5);
+  });
+
+  it("does not cut a surrogate pair in half at the boundary", () => {
+    const data = `${"z".repeat(TERMINAL_WRITE_MAX_LENGTH - 1)}😀tail`;
+    const chunks = chunkTerminalWrite(data);
+    expect(chunks[0]).toHaveLength(TERMINAL_WRITE_MAX_LENGTH - 1);
+    expect(chunks[1]).toBe("😀tail");
+    expect(chunks.join("")).toBe(data);
+  });
+});
+
+describe("hostPlatformFromOs", () => {
+  it("maps the descriptor os onto the toolbar layout", () => {
+    expect(hostPlatformFromOs("darwin")).toBe("mac");
+    expect(hostPlatformFromOs("windows")).toBe("windows");
+    expect(hostPlatformFromOs("linux")).toBe("linux");
+  });
+
+  it("defers to the caller when the os is unknown or not loaded yet", () => {
+    expect(hostPlatformFromOs("unknown")).toBeNull();
+    expect(hostPlatformFromOs(null)).toBeNull();
+  });
+});
diff --git a/apps/mobile/src/features/terminal/terminalInput.ts b/apps/mobile/src/features/terminal/terminalInput.ts
new file mode 100644
index 000000000000..d7cd60dd7566
--- /dev/null
+++ b/apps/mobile/src/features/terminal/terminalInput.ts
@@ -0,0 +1,108 @@
+import type { ExecutionEnvironmentPlatformOs } from "@t3tools/contracts";
+
+export type PendingModifier = "ctrl" | "meta";
+export type HostPlatform = "mac" | "linux" | "windows" | "unknown";
+
+/** Upper bound of `TerminalWriteInput.data`; longer writes are rejected by the server. */
+export const TERMINAL_WRITE_MAX_LENGTH = 65_536;
+
+export type ModifiedTerminalInput =
+  | { readonly kind: "write"; readonly data: string }
+  | { readonly kind: "paste" };
+
+// C0 controls other than tab, LF, and CR, plus DEL.
+// eslint-disable-next-line no-control-regex -- Pasted text must not carry raw terminal controls.
+const UNSAFE_PASTE_BYTES = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+
+/**
+ * Encodes a key pressed while the toolbar's one-shot ctrl modifier is armed
+ * into the control byte a terminal expects.
+ */
+export function applyCtrlModifier(input: string): string {
+  const firstCharacter = input[0];
+  if (!firstCharacter) {
+    return input;
+  }
+
+  const lowerCharacter = firstCharacter.toLowerCase();
+  if (lowerCharacter >= "a" && lowerCharacter <= "z") {
+    return String.fromCharCode(lowerCharacter.charCodeAt(0) - 96);
+  }
+
+  if (firstCharacter === "@") return "\u0000";
+  if (firstCharacter === "[") return "\u001b";
+  if (firstCharacter === "\\") return "\u001c";
+  if (firstCharacter === "]") return "\u001d";
+  if (firstCharacter === "^") return "\u001e";
+  if (firstCharacter === "_") return "\u001f";
+  if (firstCharacter === "?") return "\u007f";
+
+  return input;
+}
+
+/**
+ * Resolves what a keypress means once a toolbar modifier is armed. The host's
+ * paste chord (cmd+v on a macOS host, ctrl+v elsewhere) pastes the device
+ * clipboard instead of reaching the remote shell as a raw control byte, which
+ * matches what the web terminal does with the same chord. Forwarding the byte
+ * is never what a phone user means: PowerShell binds ctrl+v to paste from the
+ * host machine's clipboard, so the shell inserts whatever the desktop last
+ * copied rather than the text on the phone.
+ */
+export function resolveModifiedTerminalInput(input: {
+  readonly data: string;
+  readonly modifier: PendingModifier;
+  readonly hostPlatform: HostPlatform;
+}): ModifiedTerminalInput {
+  const pasteModifier: PendingModifier = input.hostPlatform === "mac" ? "meta" : "ctrl";
+  if (input.modifier === pasteModifier && input.data.toLowerCase() === "v") {
+    return { kind: "paste" };
+  }
+
+  return {
+    kind: "write",
+    data: input.modifier === "ctrl" ? applyCtrlModifier(input.data) : `\u001b${input.data}`,
+  };
+}
+
+/**
+ * Encodes clipboard text for the remote pty the way the web terminal does when
+ * bracketed paste is off: unsafe control bytes become spaces (which also
+ * defuses an embedded bracketed-paste end marker, since its ESC goes too) and
+ * line breaks become carriage returns, since a bare LF is Ctrl+J to a raw-mode
+ * TUI. The native mobile surface does not expose DECSET 2004, so mobile never
+ * wraps a paste in bracketed-paste markers.
+ */
+export function encodeTerminalPaste(text: string): string {
+  return text.replace(UNSAFE_PASTE_BYTES, " ").replace(/\r\n|\n/g, "\r");
+}
+
+/**
+ * Splits terminal input into writes the wire contract accepts, never cutting
+ * through a surrogate pair so every chunk stays valid UTF-16.
+ */
+export function chunkTerminalWrite(data: string): ReadonlyArray<string> {
+  const chunks: string[] = [];
+  let start = 0;
+  while (start < data.length) {
+    let end = Math.min(start + TERMINAL_WRITE_MAX_LENGTH, data.length);
+    const last = data.charCodeAt(end - 1);
+    if (end < data.length && last >= 0xd800 && last <= 0xdbff) {
+      end -= 1;
+    }
+    chunks.push(data.slice(start, end));
+    start = end;
+  }
+  return chunks;
+}
+
+/**
+ * Maps the OS reported by the environment descriptor onto the toolbar's host
+ * layout. Returns null for "unknown" so callers can fall back to a weaker signal.
+ */
+export function hostPlatformFromOs(os: ExecutionEnvironmentPlatformOs | null): HostPlatform | null {
+  if (os === "darwin") return "mac";
+  if (os === "linux") return "linux";
+  if (os === "windows") return "windows";
+  return null;
+}
diff --git a/apps/mobile/src/features/terminal/terminalMenu.test.ts b/apps/mobile/src/features/terminal/terminalMenu.test.ts
index 966312270951..2f8ce1377720 100644
--- a/apps/mobile/src/features/terminal/terminalMenu.test.ts
+++ b/apps/mobile/src/features/terminal/terminalMenu.test.ts
@@ -1,6 +1,9 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { type KnownTerminalSession } from "@t3tools/client-runtime/state/terminal";
+import {
+  EMPTY_TERMINAL_BUFFER_STATE,
+  type KnownTerminalSession,
+} from "@t3tools/client-runtime/state/terminal";
 import { DEFAULT_TERMINAL_ID, EnvironmentId, ThreadId } from "@t3tools/contracts";
 
 import { getTerminalLabel } from "@t3tools/shared/terminalLabels";
@@ -55,12 +58,13 @@ function makeKnownSession(input: {
             updatedAt: input.updatedAt ?? "2026-04-15T20:00:00.000Z",
           }
         : null,
-      buffer: "",
+      output: EMPTY_TERMINAL_BUFFER_STATE.output,
       status: input.status,
       error: null,
       hasRunningSubprocess: false,
       updatedAt: input.updatedAt ?? "2026-04-15T20:00:00.000Z",
       version: 1,
+      lifecycleVersion: 1,
     },
   };
 }
diff --git a/apps/mobile/src/features/terminal/terminalPaste.test.ts b/apps/mobile/src/features/terminal/terminalPaste.test.ts
new file mode 100644
index 000000000000..ec9bd9d74d93
--- /dev/null
+++ b/apps/mobile/src/features/terminal/terminalPaste.test.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { TERMINAL_WRITE_MAX_LENGTH } from "./terminalInput";
+import { createTerminalPasteSession } from "./terminalPaste";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
+}
+
+describe("terminal paste session", () => {
+  it("drops a clipboard read when the pty restarts in place", async () => {
+    const session = createTerminalPasteSession();
+    session.reset(true);
+    const clipboardRead = deferred<string>();
+    const writes: string[] = [];
+
+    const paste = session.paste({
+      readText: () => clipboardRead.promise,
+      write: async (data) => {
+        writes.push(data);
+        return true;
+      },
+      onReadError: () => undefined,
+    });
+
+    session.reset(true);
+    clipboardRead.resolve("stale");
+    await paste;
+
+    expect(writes).toEqual([]);
+  });
+
+  it("never overlaps writes from rapid paste requests", async () => {
+    const session = createTerminalPasteSession();
+    session.reset(true);
+
+    const firstWrite = deferred<boolean>();
+    const firstWriteStarted = deferred<void>();
+    const writes: string[] = [];
+    let activeWrites = 0;
+    let maximumActiveWrites = 0;
+    const write = async (data: string) => {
+      writes.push(data);
+      activeWrites += 1;
+      maximumActiveWrites = Math.max(maximumActiveWrites, activeWrites);
+      if (writes.length === 1) {
+        firstWriteStarted.resolve();
+        await firstWrite.promise;
+      }
+      activeWrites -= 1;
+      return true;
+    };
+
+    const olderPaste = session.paste({
+      readText: async () => "a".repeat(TERMINAL_WRITE_MAX_LENGTH + 1),
+      write,
+      onReadError: () => undefined,
+    });
+    await firstWriteStarted.promise;
+
+    const newerPaste = session.paste({
+      readText: async () => "newer",
+      write,
+      onReadError: () => undefined,
+    });
+    await Promise.resolve();
+
+    expect(writes.map((chunk) => chunk.length)).toEqual([TERMINAL_WRITE_MAX_LENGTH]);
+    expect(maximumActiveWrites).toBe(1);
+
+    firstWrite.resolve(true);
+    await Promise.all([olderPaste, newerPaste]);
+
+    expect(writes.map((chunk) => chunk.length)).toEqual([TERMINAL_WRITE_MAX_LENGTH, 5]);
+    expect(writes[1]).toBe("newer");
+    expect(maximumActiveWrites).toBe(1);
+  });
+});
diff --git a/apps/mobile/src/features/terminal/terminalPaste.ts b/apps/mobile/src/features/terminal/terminalPaste.ts
new file mode 100644
index 000000000000..3368cd3a5bb7
--- /dev/null
+++ b/apps/mobile/src/features/terminal/terminalPaste.ts
@@ -0,0 +1,60 @@
+import { chunkTerminalWrite, encodeTerminalPaste } from "./terminalInput";
+
+interface TerminalPasteInput {
+  readonly readText: () => Promise<string>;
+  readonly write: (data: string) => Promise<boolean>;
+  readonly onReadError: (cause: unknown) => void;
+}
+
+export interface TerminalPasteSession {
+  readonly reset: (active: boolean) => void;
+  readonly paste: (input: TerminalPasteInput) => Promise<void>;
+}
+
+/** Coordinates clipboard reads and writes for the currently attached pty. */
+export function createTerminalPasteSession(): TerminalPasteSession {
+  let liveTarget: object | null = null;
+  let latestRequest = 0;
+  let writeTail: Promise<void> = Promise.resolve();
+
+  return {
+    reset(active) {
+      liveTarget = active ? {} : null;
+    },
+
+    async paste({ readText, write, onReadError }) {
+      const target = liveTarget;
+      if (target === null) {
+        return;
+      }
+      const request = ++latestRequest;
+      const isCurrent = () => liveTarget === target && latestRequest === request;
+
+      let text: string;
+      try {
+        text = await readText();
+      } catch (cause) {
+        onReadError(cause);
+        return;
+      }
+
+      if (!isCurrent()) {
+        return;
+      }
+
+      const writePaste = async () => {
+        for (const chunk of chunkTerminalWrite(encodeTerminalPaste(text))) {
+          if (!isCurrent() || !(await write(chunk))) {
+            return;
+          }
+        }
+      };
+      const queuedWrite = writeTail.then(writePaste, writePaste);
+      writeTail = queuedWrite.then(
+        () => undefined,
+        () => undefined,
+      );
+      await queuedWrite;
+    },
+  };
+}
diff --git a/apps/mobile/src/features/terminal/terminalTheme.test.ts b/apps/mobile/src/features/terminal/terminalTheme.test.ts
index 24edb384bebb..478ddc96d960 100644
--- a/apps/mobile/src/features/terminal/terminalTheme.test.ts
+++ b/apps/mobile/src/features/terminal/terminalTheme.test.ts
@@ -3,15 +3,11 @@ import { BUILT_IN_THEMES, getThemeColorsForAppearance } from "@t3tools/shared/th
 
 import { themeColorToNativeColor } from "../../lib/mobileTheme";
 
-import {
-  buildGhosttyThemeConfig,
-  getMobileTerminalTheme,
-  getPierreTerminalTheme,
-} from "./terminalTheme";
+import { buildGhosttyThemeConfig, getMobileTerminalTheme } from "./terminalTheme";
 
-describe("getPierreTerminalTheme", () => {
-  it("returns the Pierre light terminal palette", () => {
-    expect(getPierreTerminalTheme("light")).toMatchObject({
+describe("getMobileTerminalTheme", () => {
+  it("preserves the default light terminal palette", () => {
+    expect(getMobileTerminalTheme("t3-code", "light")).toMatchObject({
       background: "#f2f2f7",
       foreground: "#6C6C71",
       cursorForeground: "#009fff",
@@ -19,23 +15,14 @@ describe("getPierreTerminalTheme", () => {
     });
   });
 
-  it("returns the Pierre dark terminal palette", () => {
-    expect(getPierreTerminalTheme("dark")).toMatchObject({
+  it("preserves the default dark terminal palette", () => {
+    expect(getMobileTerminalTheme("t3-code", "dark")).toMatchObject({
       background: "#0a0a0a",
       foreground: "#adadb1",
       cursorForeground: "#009fff",
       cursorBackground: "#0a0a0a",
     });
   });
-});
-
-describe("getMobileTerminalTheme", () => {
-  it("preserves the Pierre terminal for the default theme", () => {
-    for (const scheme of ["light", "dark"] as const) {
-      expect(getMobileTerminalTheme("t3-code", scheme)).toEqual(getPierreTerminalTheme(scheme));
-    }
-  });
-
   it("applies the selected palette without replacing ANSI status colors", () => {
     const standard = getMobileTerminalTheme("t3-code", "dark");
     const ocean = getMobileTerminalTheme("ocean", "dark");
@@ -58,7 +45,7 @@ describe("getMobileTerminalTheme", () => {
 
 describe("buildGhosttyThemeConfig", () => {
   it("serializes theme colors into a ghostty config file", () => {
-    const config = buildGhosttyThemeConfig(getPierreTerminalTheme("dark"));
+    const config = buildGhosttyThemeConfig(getMobileTerminalTheme("t3-code", "dark"));
 
     expect(config).toContain("background = #0a0a0a");
     expect(config).toContain("foreground = #adadb1");
diff --git a/apps/mobile/src/features/terminal/terminalTheme.ts b/apps/mobile/src/features/terminal/terminalTheme.ts
index 9a913022571d..569b10f7bd55 100644
--- a/apps/mobile/src/features/terminal/terminalTheme.ts
+++ b/apps/mobile/src/features/terminal/terminalTheme.ts
@@ -74,7 +74,7 @@ const PIERRE_DARK_THEME: TerminalTheme = {
   ],
 };
 
-export function getPierreTerminalTheme(scheme: TerminalAppearanceScheme): TerminalTheme {
+function getPierreTerminalTheme(scheme: TerminalAppearanceScheme): TerminalTheme {
   return scheme === "light" ? PIERRE_LIGHT_THEME : PIERRE_DARK_THEME;
 }
 
diff --git a/apps/mobile/src/features/terminal/terminalUiState.test.ts b/apps/mobile/src/features/terminal/terminalUiState.test.ts
index 0bb3c1395915..6879fdfdbb20 100644
--- a/apps/mobile/src/features/terminal/terminalUiState.test.ts
+++ b/apps/mobile/src/features/terminal/terminalUiState.test.ts
@@ -2,9 +2,7 @@ import { beforeEach, describe, expect, it } from "vite-plus/test";
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 
 import {
-  cacheTerminalFontSize,
   cacheTerminalGridSize,
-  getCachedTerminalFontSize,
   getCachedTerminalGridSize,
   resetTerminalUiStateCaches,
 } from "./terminalUiState";
@@ -14,14 +12,6 @@ describe("terminalUiState", () => {
     resetTerminalUiStateCaches();
   });
 
-  it("caches terminal font size using the shared normalization rules", () => {
-    expect(getCachedTerminalFontSize()).toBeNull();
-    expect(cacheTerminalFontSize(8.5)).toBe(8.5);
-    expect(getCachedTerminalFontSize()).toBe(8.5);
-    expect(cacheTerminalFontSize(100)).toBe(14);
-    expect(getCachedTerminalFontSize()).toBe(14);
-  });
-
   it("stores terminal grid sizes per terminal target", () => {
     const primaryTarget = {
       environmentId: EnvironmentId.make("env-1"),
diff --git a/apps/mobile/src/features/terminal/terminalUiState.ts b/apps/mobile/src/features/terminal/terminalUiState.ts
index 2cac0bf52b9e..84274430e8a1 100644
--- a/apps/mobile/src/features/terminal/terminalUiState.ts
+++ b/apps/mobile/src/features/terminal/terminalUiState.ts
@@ -1,7 +1,5 @@
 import type { EnvironmentId, ThreadId } from "@t3tools/contracts";
 
-import { DEFAULT_TERMINAL_FONT_SIZE, normalizeTerminalFontSize } from "./terminalPreferences";
-
 export interface TerminalGridSize {
   readonly cols: number;
   readonly rows: number;
@@ -14,22 +12,11 @@ export interface TerminalUiStateTarget {
 }
 
 const terminalGridSizeCache = new Map<string, TerminalGridSize>();
-let cachedTerminalFontSize: number | null = null;
 
 function terminalUiStateKey(target: TerminalUiStateTarget): string {
   return `${target.environmentId}:${target.threadId}:${target.terminalId}`;
 }
 
-export function getCachedTerminalFontSize(): number | null {
-  return cachedTerminalFontSize;
-}
-
-export function cacheTerminalFontSize(value: number | null | undefined): number {
-  const normalized = normalizeTerminalFontSize(value ?? DEFAULT_TERMINAL_FONT_SIZE);
-  cachedTerminalFontSize = normalized;
-  return normalized;
-}
-
 export function getCachedTerminalGridSize(target: TerminalUiStateTarget): TerminalGridSize | null {
   return terminalGridSizeCache.get(terminalUiStateKey(target)) ?? null;
 }
@@ -47,6 +34,5 @@ export function cacheTerminalGridSize(
 }
 
 export function resetTerminalUiStateCaches() {
-  cachedTerminalFontSize = null;
   terminalGridSizeCache.clear();
 }
diff --git a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
index 94cd242d36e1..e1cc7405bde2 100644
--- a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
+++ b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
@@ -904,7 +904,7 @@ export function NewTaskDraftScreen(props: {
     ) {
       Alert.alert(
         "Antigravity model unavailable",
-        "Open model settings to finish setup or choose another model.",
+        "Set up Antigravity on web or desktop, or choose another model.",
       );
       return;
     }
diff --git a/apps/mobile/src/features/threads/ThreadFeed.tsx b/apps/mobile/src/features/threads/ThreadFeed.tsx
index ab48046fbd96..360b980edc95 100644
--- a/apps/mobile/src/features/threads/ThreadFeed.tsx
+++ b/apps/mobile/src/features/threads/ThreadFeed.tsx
@@ -86,6 +86,7 @@ import { copyTextWithHaptic } from "../../lib/copyTextWithHaptic";
 import { tryOpenExternalUrl } from "../../lib/openExternalUrl";
 import { downloadAndShareAttachment } from "../../lib/attachmentDownload";
 import { hasWideMarkdownBlock } from "../../lib/wideMarkdownBlocks";
+import { faviconUrlForOrigin } from "@t3tools/shared/favicon";
 import {
   hasNativeSelectableMarkdownText,
   SelectableMarkdownText,
@@ -596,7 +597,8 @@ const MarkdownExternalLink = memo(function MarkdownExternalLink(props: {
   readonly href: string;
   readonly onPress: (href: string) => void;
 }) {
-  const [failed, setFailed] = useState(() => failedMarkdownFaviconHosts.has(props.host));
+  const [failedHost, setFailedHost] = useState<string | null>(null);
+  const faviconUrl = faviconUrlForOrigin(`https://${props.host}`);
 
   return (
     <NativeText
@@ -607,15 +609,17 @@ const MarkdownExternalLink = memo(function MarkdownExternalLink(props: {
         textDecorationLine: "none",
       }}
     >
-      {!failed ? (
+      {faviconUrl !== null &&
+      failedHost !== props.host &&
+      !failedMarkdownFaviconHosts.has(props.host) ? (
         <Image
           source={{
-            uri: `https://www.google.com/s2/favicons?domain=${encodeURIComponent(props.host)}&sz=32`,
+            uri: faviconUrl,
           }}
           style={[markdownLinkStyles.inlineIcon, markdownLinkStyles.favicon]}
           onError={() => {
             failedMarkdownFaviconHosts.add(props.host);
-            setFailed(true);
+            setFailedHost(props.host);
           }}
         />
       ) : (
diff --git a/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx b/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
index d03a4ee05dd1..07357a1b7524 100644
--- a/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
+++ b/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
@@ -45,6 +45,7 @@ import { buildHomeListFilterMenu } from "../home/home-list-filter-menu";
 import {
   buildHomeListLayout,
   DEFAULT_GROUP_DISPLAY_STATE,
+  EMPTY_HOME_LIST_LAYOUT,
   homeListItemsAreEqual,
   nextGroupDisplayState,
   type HomeGroupDisplayAction,
@@ -269,47 +270,56 @@ function ThreadNavigationSidebarPane(
   );
   const scopedProjects = useMemo(
     () =>
-      selectedProjectRefs === null
-        ? projects
-        : projects.filter((project) =>
-            selectedProjectRefs.has(scopedProjectKey(project.environmentId, project.id)),
-          ),
-    [projects, selectedProjectRefs],
+      threadListV2Enabled
+        ? []
+        : selectedProjectRefs === null
+          ? projects
+          : projects.filter((project) =>
+              selectedProjectRefs.has(scopedProjectKey(project.environmentId, project.id)),
+            ),
+    [threadListV2Enabled, projects, selectedProjectRefs],
   );
   const scopedThreads = useMemo(
     () =>
-      selectedProjectRefs === null
-        ? threads
-        : threads.filter((thread) =>
-            selectedProjectRefs.has(scopedProjectKey(thread.environmentId, thread.projectId)),
-          ),
-    [selectedProjectRefs, threads],
+      threadListV2Enabled
+        ? []
+        : selectedProjectRefs === null
+          ? threads
+          : threads.filter((thread) =>
+              selectedProjectRefs.has(scopedProjectKey(thread.environmentId, thread.projectId)),
+            ),
+    [threadListV2Enabled, selectedProjectRefs, threads],
   );
   const scopedPendingTasks = useMemo(
     () =>
-      selectedProjectRefs === null
-        ? pendingTasks
-        : pendingTasks.filter((pendingTask) =>
-            selectedProjectRefs.has(
-              scopedProjectKey(pendingTask.message.environmentId, pendingTask.creation.projectId),
+      threadListV2Enabled
+        ? []
+        : selectedProjectRefs === null
+          ? pendingTasks
+          : pendingTasks.filter((pendingTask) =>
+              selectedProjectRefs.has(
+                scopedProjectKey(pendingTask.message.environmentId, pendingTask.creation.projectId),
+              ),
             ),
-          ),
-    [pendingTasks, selectedProjectRefs],
+    [threadListV2Enabled, pendingTasks, selectedProjectRefs],
   );
   const groups = useMemo(
     () =>
-      buildHomeThreadGroups({
-        projects: scopedProjects,
-        threads: scopedThreads,
-        pendingTasks: scopedPendingTasks,
-        environmentId: options.selectedEnvironmentId,
-        searchQuery: props.searchQuery,
-        matchedThreadKeys,
-        projectSortOrder: options.projectSortOrder,
-        threadSortOrder: options.threadSortOrder,
-        projectGroupingMode: options.projectGroupingMode,
-      }),
+      threadListV2Enabled
+        ? []
+        : buildHomeThreadGroups({
+            projects: scopedProjects,
+            threads: scopedThreads,
+            pendingTasks: scopedPendingTasks,
+            environmentId: options.selectedEnvironmentId,
+            searchQuery: props.searchQuery,
+            matchedThreadKeys,
+            projectSortOrder: options.projectSortOrder,
+            threadSortOrder: options.threadSortOrder,
+            projectGroupingMode: options.projectGroupingMode,
+          }),
     [
+      threadListV2Enabled,
       matchedThreadKeys,
       options,
       props.searchQuery,
@@ -334,12 +344,14 @@ function ThreadNavigationSidebarPane(
   const hasSearchQuery = props.searchQuery.trim().length > 0;
   const listLayout = useMemo(
     () =>
-      buildHomeListLayout({
-        groups,
-        displayStates: groupDisplayStates,
-        showAllThreads: hasSearchQuery,
-      }),
-    [groups, groupDisplayStates, hasSearchQuery],
+      threadListV2Enabled
+        ? EMPTY_HOME_LIST_LAYOUT
+        : buildHomeListLayout({
+            groups,
+            displayStates: groupDisplayStates,
+            showAllThreads: hasSearchQuery,
+          }),
+    [threadListV2Enabled, groups, groupDisplayStates, hasSearchQuery],
   );
   const projectCwdByKey = useMemo(() => {
     const map = new Map<string, string>();
diff --git a/apps/mobile/src/features/threads/ThreadSettingsSheet.tsx b/apps/mobile/src/features/threads/ThreadSettingsSheet.tsx
index b802c5ac3014..24cdb0cc4546 100644
--- a/apps/mobile/src/features/threads/ThreadSettingsSheet.tsx
+++ b/apps/mobile/src/features/threads/ThreadSettingsSheet.tsx
@@ -5,9 +5,7 @@ import type {
   ProviderOptionDescriptor,
   ProviderOptionSelection,
   RuntimeMode,
-  ServerProvider,
 } from "@t3tools/contracts";
-import { useAtomValue } from "@effect/atom-react";
 import type { LegendListRenderItemProps } from "@legendapp/list/react-native";
 import { AnimatedLegendList } from "@legendapp/list/reanimated";
 import { HeaderHeightContext } from "@react-navigation/elements";
@@ -52,11 +50,6 @@ import {
 } from "../../native/StackHeader";
 import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
 import { serverEnvironment } from "../../state/server";
-import { ProviderSetupLink } from "../settings/ProviderSetupLink";
-import {
-  SettingsProviderSetupRouteScreen,
-  type ProviderSetupRouteParams,
-} from "../settings/SettingsProviderSetupRouteScreen";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { useNewTaskFlow } from "./new-task-flow-provider";
 import {
@@ -73,7 +66,6 @@ import {
   canCommitPendingModel,
   modelMatchesCatalogQuery,
   pendingModelAfterPress,
-  providerSetupCandidates,
   providerSectionIsCollapsed,
 } from "./thread-settings-sheet-state";
 
@@ -446,7 +438,10 @@ function ThreadSettingsSessionProvider(
   const commitPendingModel = useCallback(() => {
     if (pendingModel) {
       if (!canCommitPendingModel(pendingModel, props.providerGroups)) {
-        Alert.alert("Model unavailable", "Complete provider setup or select another model.");
+        Alert.alert(
+          "Model unavailable",
+          "Set up this provider on web or desktop, or select another model.",
+        );
         return false;
       }
       void Haptics.selectionAsync();
@@ -581,11 +576,6 @@ type ThreadSettingsCatalogItem =
       readonly isFirst: boolean;
       readonly isLast: boolean;
     }
-  | {
-      readonly kind: "setup";
-      readonly key: string;
-      readonly provider: ServerProvider;
-    }
   | {
       readonly kind: "empty";
       readonly key: "empty";
@@ -795,37 +785,20 @@ function ThreadSettingsOptionsItem(props: {
 /** One native scroll owner for the model catalog and its related settings. */
 function ThreadSettingsMainContent(props: {
   readonly onOpenSubmenu: (submenu: ThreadSettingsSubmenuPage) => void;
-  readonly onOpenProviderSetup: (instanceId: ProviderInstanceId) => void;
 }) {
   const session = useThreadSettingsSession();
-  const config = useAtomValue(serverEnvironment.configValueAtom(session.environmentId));
   const catalogItems = useThreadSettingsCatalogItems(session);
   const [animationsReady, setAnimationsReady] = useState(false);
   const nativeHeaderHeight = use(HeaderHeightContext) ?? 0;
   const hasActiveCatalogFilter =
     session.providerFilter !== null || session.searchQuery.trim().length > 0;
   const usesTransparentNativeHeader = Platform.OS === "ios" && NATIVE_LIQUID_GLASS_SUPPORTED;
-  const setupProviders = useMemo(
-    () =>
-      providerSetupCandidates({
-        providers: config?.providers ?? [],
-        instanceId: session.providerInstanceId,
-        providerFilter: session.providerFilter,
-        query: session.searchQuery,
-      }),
-    [config?.providers, session.providerInstanceId, session.providerFilter, session.searchQuery],
-  );
   const listItems = useMemo<ReadonlyArray<ThreadSettingsCatalogItem>>(
     () => [
       ...(catalogItems.length === 0 ? ([{ kind: "empty", key: "empty" }] as const) : catalogItems),
-      ...setupProviders.map((provider) => ({
-        kind: "setup" as const,
-        key: `setup:${provider.instanceId}`,
-        provider,
-      })),
       { kind: "options", key: "options" },
     ],
-    [catalogItems, setupProviders],
+    [catalogItems],
   );
   const renderCatalogItem = useCallback(
     (itemProps: LegendListRenderItemProps<ThreadSettingsCatalogItem>) => {
@@ -842,13 +815,6 @@ function ThreadSettingsMainContent(props: {
             option={item.option}
           />
         );
-      } else if (item.kind === "setup") {
-        content = (
-          <ProviderSetupLink
-            provider={item.provider}
-            onPress={() => props.onOpenProviderSetup(item.provider.instanceId)}
-          />
-        );
       } else if (item.kind === "empty") {
         content = (
           <View className="items-center px-8 py-14">
@@ -876,7 +842,7 @@ function ThreadSettingsMainContent(props: {
         </Animated.View>
       );
     },
-    [animationsReady, hasActiveCatalogFilter, props.onOpenProviderSetup, props.onOpenSubmenu],
+    [animationsReady, hasActiveCatalogFilter, props.onOpenSubmenu],
   );
 
   return (
@@ -1002,7 +968,6 @@ function ThreadSettingsChoiceContent(props: {
 type ThreadSettingsPickerStackParams = {
   ThreadSettingsModels: undefined;
   ThreadSettingsChoice: ThreadSettingsSubmenuPage & { readonly title: string };
-  ThreadSettingsProviderSetup: ProviderSetupRouteParams;
 };
 
 type ThreadSettingsPickerPresentation = {
@@ -1146,13 +1111,6 @@ function ThreadSettingsModelsScreen() {
         }}
       />
       <ThreadSettingsMainContent
-        onOpenProviderSetup={(instanceId) => {
-          if (!session.environmentId) return;
-          navigation.navigate("ThreadSettingsProviderSetup", {
-            environmentId: session.environmentId,
-            instanceId,
-          });
-        }}
         onOpenSubmenu={(submenu) => {
           const title =
             submenu.kind === "runtime"
@@ -1287,11 +1245,6 @@ function ThreadSettingsPickerNavigator(props: ThreadSettingsPickerPresentation)
           component={ThreadSettingsChoiceScreen}
           options={({ route }) => ({ title: route.params.title })}
         />
-        <ThreadSettingsPickerStack.Screen
-          name="ThreadSettingsProviderSetup"
-          component={SettingsProviderSetupRouteScreen}
-          options={{ title: "Antigravity" }}
-        />
       </ThreadSettingsPickerStack.Navigator>
     </ThreadSettingsPickerPresentationContext.Provider>
   );
diff --git a/apps/mobile/src/features/threads/floating-working-control.tsx b/apps/mobile/src/features/threads/floating-working-control.tsx
index 0d7f7d88f014..cac2686ab218 100644
--- a/apps/mobile/src/features/threads/floating-working-control.tsx
+++ b/apps/mobile/src/features/threads/floating-working-control.tsx
@@ -1,3 +1,4 @@
+import { formatDuration } from "@t3tools/shared/orchestrationTiming";
 import { GlassContainer, GlassView } from "expo-glass-effect";
 import { useEffect, useState } from "react";
 import { ActivityIndicator, Text as SystemText, View } from "react-native";
@@ -235,6 +236,9 @@ function formatWorkingDuration(startedAt: string, nowMs: number): string {
   if (totalSeconds < 60) {
     return `${totalSeconds}s`;
   }
+  if (totalSeconds >= 3_600) {
+    return formatDuration(totalSeconds * 1_000);
+  }
 
   const minutes = Math.floor(totalSeconds / 60);
   const seconds = String(totalSeconds % 60).padStart(2, "0");
diff --git a/apps/mobile/src/features/threads/new-task-project-selection.test.ts b/apps/mobile/src/features/threads/new-task-project-selection.test.ts
index 7068a95d558a..2d52ed716d50 100644
--- a/apps/mobile/src/features/threads/new-task-project-selection.test.ts
+++ b/apps/mobile/src/features/threads/new-task-project-selection.test.ts
@@ -4,7 +4,6 @@ import { describe, expect, it } from "vite-plus/test";
 import type { EnvironmentProject } from "@t3tools/client-runtime/state/shell";
 import type { HomeProjectScope } from "../home/homeThreadList";
 import {
-  getOnlySelectableProject,
   getProjectScopeSelectionTarget,
   resolveDraftProjectSelection,
 } from "./new-task-project-selection";
@@ -36,18 +35,6 @@ function makeScope(projects: ReadonlyArray<EnvironmentProject>): HomeProjectScop
   };
 }
 
-describe("getOnlySelectableProject", () => {
-  it("auto-selects when there is exactly one physical project", () => {
-    const project = makeProject("t3code");
-    expect(getOnlySelectableProject([makeScope([project])])).toBe(project);
-  });
-
-  it("selects the representative when one logical project has multiple workspaces", () => {
-    const projects = [makeProject("t3code"), makeProject("t3code-2"), makeProject("t3code-3")];
-    expect(getOnlySelectableProject([makeScope(projects)])).toBe(projects[0]);
-  });
-});
-
 describe("getProjectScopeSelectionTarget", () => {
   it("keeps the current environment when it hosts the selected logical project", () => {
     const projects = [makeProject("t3code-mac", "mac"), makeProject("t3code-server", "server")];
diff --git a/apps/mobile/src/features/threads/new-task-project-selection.ts b/apps/mobile/src/features/threads/new-task-project-selection.ts
index 7be899d62a1a..0528dc66687a 100644
--- a/apps/mobile/src/features/threads/new-task-project-selection.ts
+++ b/apps/mobile/src/features/threads/new-task-project-selection.ts
@@ -19,7 +19,7 @@ export function getProjectScopeSelectionTarget(
   );
 }
 
-export function getOnlySelectableProject(
+function getOnlySelectableProject(
   projectScopes: ReadonlyArray<HomeProjectScope>,
 ): EnvironmentProject | null {
   const onlyScope = projectScopes.length === 1 ? projectScopes[0] : null;
diff --git a/apps/mobile/src/features/threads/thread-settings-sheet-state.test.ts b/apps/mobile/src/features/threads/thread-settings-sheet-state.test.ts
index 72bb58f1c17a..8b20c0893da0 100644
--- a/apps/mobile/src/features/threads/thread-settings-sheet-state.test.ts
+++ b/apps/mobile/src/features/threads/thread-settings-sheet-state.test.ts
@@ -1,18 +1,12 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import {
-  ProviderInstanceId,
-  ServerProvider,
-  type ProviderOptionSelection,
-} from "@t3tools/contracts";
-import * as Schema from "effect/Schema";
+import { ProviderInstanceId, type ProviderOptionSelection } from "@t3tools/contracts";
 
 import type { ModelOption } from "../../lib/modelOptions";
 import {
   canCommitPendingModel,
   modelMatchesCatalogQuery,
   pendingModelAfterPress,
-  providerSetupCandidates,
 } from "./thread-settings-sheet-state";
 
 function modelOption(
@@ -123,77 +117,3 @@ describe("thread settings sheet state", () => {
     ).toBe(false);
   });
 });
-
-const decodeServerProvider = Schema.decodeSync(ServerProvider);
-
-function setupProvider(overrides: Partial<ServerProvider> = {}): ServerProvider {
-  return decodeServerProvider({
-    instanceId: "antigravity",
-    driver: "antigravity",
-    displayName: "Antigravity",
-    enabled: false,
-    installed: false,
-    version: null,
-    status: "disabled",
-    auth: { status: "unauthenticated" },
-    checkedAt: "2026-09-02T00:00:00.000Z",
-    setup: { canAuthenticate: true, canInstall: true },
-    models: [],
-    ...overrides,
-  });
-}
-
-describe("providerSetupCandidates", () => {
-  const unfiltered = { providerFilter: null, query: "" };
-
-  it("offers setup without a selectable model and after sign-out", () => {
-    const disabled = setupProvider();
-    const signedOut = setupProvider({ enabled: true, installed: true });
-
-    expect(providerSetupCandidates({ providers: [disabled], ...unfiltered })).toEqual([disabled]);
-    expect(providerSetupCandidates({ providers: [signedOut], ...unfiltered })).toEqual([signedOut]);
-  });
-
-  it("uses the selected environment's status for identical instance IDs", () => {
-    const offlineAccount = setupProvider();
-    const readyAccount = setupProvider({
-      enabled: true,
-      installed: true,
-      auth: { status: "authenticated" },
-      models: [{ slug: "gemini-native", name: "Gemini", isCustom: false, capabilities: null }],
-    });
-
-    expect(providerSetupCandidates({ providers: [offlineAccount], ...unfiltered })).toHaveLength(1);
-    expect(providerSetupCandidates({ providers: [readyAccount], ...unfiltered })).toEqual([]);
-  });
-
-  it("limits existing threads to their provider and respects search", () => {
-    const personal = setupProvider();
-    const work = setupProvider({
-      instanceId: ProviderInstanceId.make("google_work"),
-      displayName: "Work Google",
-    });
-
-    expect(
-      providerSetupCandidates({
-        providers: [personal, work],
-        ...unfiltered,
-        instanceId: work.instanceId,
-      }),
-    ).toEqual([work]);
-    expect(
-      providerSetupCandidates({
-        providers: [personal, work],
-        providerFilter: work.instanceId,
-        query: "work",
-      }),
-    ).toEqual([work]);
-    expect(
-      providerSetupCandidates({
-        providers: [personal, work],
-        providerFilter: null,
-        query: "no-match",
-      }),
-    ).toEqual([]);
-  });
-});
diff --git a/apps/mobile/src/features/threads/thread-settings-sheet-state.ts b/apps/mobile/src/features/threads/thread-settings-sheet-state.ts
index 1b545098c53f..28d318d491e9 100644
--- a/apps/mobile/src/features/threads/thread-settings-sheet-state.ts
+++ b/apps/mobile/src/features/threads/thread-settings-sheet-state.ts
@@ -1,26 +1,4 @@
-import type { ProviderInstanceId, ServerProvider } from "@t3tools/contracts";
 import type { ModelOption, ProviderGroup } from "../../lib/modelOptions";
-import { providerNeedsSetup } from "../settings/provider-setup-state";
-
-/** Read setup choices from this environment, not the selectable model list. */
-export function providerSetupCandidates(input: {
-  readonly providers: ReadonlyArray<ServerProvider>;
-  readonly instanceId?: ProviderInstanceId;
-  readonly providerFilter: string | null;
-  readonly query: string;
-}): ReadonlyArray<ServerProvider> {
-  const query = input.query.trim().toLocaleLowerCase();
-  return input.providers.filter(
-    (provider) =>
-      providerNeedsSetup(provider) &&
-      (input.instanceId === undefined || provider.instanceId === input.instanceId) &&
-      (input.providerFilter === null || provider.instanceId === input.providerFilter) &&
-      (query.length === 0 ||
-        [provider.displayName ?? "", provider.driver, provider.instanceId].some((label) =>
-          label.toLocaleLowerCase().includes(query),
-        )),
-  );
-}
 
 /** Match the terms a user can actually see or recognize in the model picker. */
 export function modelMatchesCatalogQuery(input: {
@@ -53,7 +31,7 @@ export function pendingModelAfterPress(input: {
   return input.current?.key === input.pressed.key ? input.current : input.pressed;
 }
 
-/** A model can disappear while its setup page is open inside the picker. */
+/** A model can disappear while the picker is open. */
 export function canCommitPendingModel(
   pending: ModelOption,
   groups: ReadonlyArray<ProviderGroup>,
diff --git a/apps/mobile/src/features/threads/use-composer-command-menu.test.ts b/apps/mobile/src/features/threads/use-composer-command-menu.test.ts
index 5ae248b6cde8..4c92325f5fbd 100644
--- a/apps/mobile/src/features/threads/use-composer-command-menu.test.ts
+++ b/apps/mobile/src/features/threads/use-composer-command-menu.test.ts
@@ -13,16 +13,9 @@ vi.mock("../../state/use-atom-command", () => ({
 
 import {
   buildComposerSlashCommandItems,
-  composerSelectionAtEnd,
   resolveComposerCommandSelection,
 } from "./use-composer-command-menu";
 
-describe("composerSelectionAtEnd", () => {
-  it("resets a changed draft owner to the new draft end", () => {
-    expect(composerSelectionAtEnd("queued task 🧪")).toEqual({ start: 14, end: 14 });
-  });
-});
-
 describe("mobile slash commands", () => {
   const antigravity = {
     driver: ProviderDriverKind.make("antigravity"),
diff --git a/apps/mobile/src/features/threads/use-composer-command-menu.ts b/apps/mobile/src/features/threads/use-composer-command-menu.ts
index 5b5b444cca74..5900acada910 100644
--- a/apps/mobile/src/features/threads/use-composer-command-menu.ts
+++ b/apps/mobile/src/features/threads/use-composer-command-menu.ts
@@ -27,7 +27,7 @@ import { matchesSlashSkillQuery } from "./composerSlashSkillSearch";
 
 const WORKSPACE_SNAPSHOT_RETRY_COOLDOWN_MS = 10_000;
 
-export function composerSelectionAtEnd(draftMessage: string): ComposerEditorSelection {
+function composerSelectionAtEnd(draftMessage: string): ComposerEditorSelection {
   return { start: draftMessage.length, end: draftMessage.length };
 }
 
diff --git a/apps/mobile/src/features/threads/use-project-actions.ts b/apps/mobile/src/features/threads/use-project-actions.ts
index 1aa4618f2c64..bb0dce57ff71 100644
--- a/apps/mobile/src/features/threads/use-project-actions.ts
+++ b/apps/mobile/src/features/threads/use-project-actions.ts
@@ -118,7 +118,7 @@ export function useCreateProjectThread() {
       const providerError = !serverConfig
         ? "Provider settings are still loading. Try again."
         : isModelSelectionUnavailable(serverConfig, input.modelSelection)
-          ? "Antigravity model unavailable. Open model settings to finish setup or choose another model."
+          ? "Antigravity model unavailable. Set it up on web or desktop, or choose another model."
           : null;
       if (providerError !== null) {
         setPendingConnectionError(providerError);
@@ -138,7 +138,6 @@ export function useCreateProjectThread() {
           messageId: metadata.messageId,
           createdAt: metadata.createdAt,
           text: initialMessageText,
-          attachments: input.initialAttachments,
           uploadedAttachments: prepared.attachments,
           modelSelection: input.modelSelection,
           runtimeMode: input.runtimeMode,
@@ -157,13 +156,8 @@ export function useCreateProjectThread() {
         );
         return AsyncResult.failure(result.cause);
       }
-      // The started turn holds its own copy of the bytes; a failed delete is
-      // surfaced without failing the started task.
-      await prepared.releaseUploads().catch((error) => {
-        console.warn("[project-thread] could not delete consumed pending uploads", error);
-      });
       setPendingConnectionError(null);
-      scheduleUnusedComposerAttachmentCleanup(input.initialAttachments);
+      scheduleUnusedComposerAttachmentCleanup(prepared.draftAttachments);
 
       return mapAtomCommandResult(result, () =>
         scopeThreadRef(input.project.environmentId, threadId),
diff --git a/apps/mobile/src/features/usage/UsageLimitsSection.tsx b/apps/mobile/src/features/usage/UsageLimitsSection.tsx
index 7c363e32e69a..daa366e8b422 100644
--- a/apps/mobile/src/features/usage/UsageLimitsSection.tsx
+++ b/apps/mobile/src/features/usage/UsageLimitsSection.tsx
@@ -1,3 +1,4 @@
+import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
 import { useAtomValue } from "@effect/atom-react";
 import type {
   EnvironmentId,
@@ -7,6 +8,7 @@ import type {
   ServerProviderResetCredits,
   ServerProviderUsageWindow,
   UsageLimitSourceAccount,
+  UsageProviderKind,
 } from "@t3tools/contracts";
 import {
   collectLimitSources,
@@ -22,30 +24,46 @@ import { type ReactNode, useState } from "react";
 import { Alert, Pressable, View } from "react-native";
 
 import { AppText as Text } from "../../components/AppText";
+import { ProviderIcon } from "../../components/ProviderIcon";
 import { environmentPresentations } from "../../state/presentation";
 import { serverEnvironment } from "../../state/server";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { SettingsSection } from "../settings/components/SettingsSection";
+import { useProviderColors } from "./usageProviders";
 
 const PACE_LABEL = { ahead: "ahead of pace", on: "on pace", under: "under pace" } as const;
 const DRIVER_LABEL: Partial<Record<string, string>> = { codex: "Codex", claudeAgent: "Claude" };
 
+type Driver = ServerProvider["driver"];
+
+/** The series colour the usage chart uses for this driver, so the two views read as one. */
+function useBarColor(driver: Driver): string | null {
+  const colors = useProviderColors();
+  const kind: UsageProviderKind | null =
+    driver === "codex" ? "codex" : driver === "claudeAgent" ? "claude" : null;
+  return kind ? colors[kind] : null;
+}
+
 /**
  * One window as a bar spanning its whole duration: the fill is quota spent,
- * the hairline is how far into the window the clock is.
+ * the hairline is how far into the window the clock is. Pace sits under the
+ * left edge, the countdown under the right, so a row reads in one glance.
  */
-function WindowBar(props: { readonly window: ServerProviderUsageWindow; readonly now: number }) {
+function WindowRow(props: {
+  readonly window: ServerProviderUsageWindow;
+  readonly color: string | null;
+  readonly now: number;
+}) {
   const { window, now } = props;
   const used = Math.round(Math.max(0, Math.min(100, window.usedPercent)));
   const elapsed = elapsedShare(window, now);
   const pace = paceOf(window, now);
   const resetsIn = formatResetsIn(window, now);
-  const detail = [pace ? PACE_LABEL[pace] : null, resetsIn].filter(Boolean).join(" · ");
   return (
-    <View className="gap-1.5">
+    <View className="gap-1">
       <View className="flex-row items-baseline justify-between gap-3">
-        <Text className="text-base text-foreground">{window.label}</Text>
-        <Text className="text-base tabular-nums text-foreground">{used}% used</Text>
+        <Text className="text-sm text-foreground">{window.label}</Text>
+        <Text className="text-sm font-t3-medium tabular-nums text-foreground">{used}%</Text>
       </View>
       <View className="h-3 justify-center">
         <View className="h-1.5 flex-row overflow-hidden rounded-full bg-subtle">
@@ -57,7 +75,10 @@ function WindowBar(props: { readonly window: ServerProviderUsageWindow; readonly
                   ? "h-full rounded-full bg-warning"
                   : "h-full rounded-full bg-foreground"
             }
-            style={{ flex: used }}
+            style={[
+              { flex: used },
+              used < 70 && props.color ? { backgroundColor: props.color } : null,
+            ]}
           />
           <View style={{ flex: 100 - used }} />
         </View>
@@ -68,12 +89,19 @@ function WindowBar(props: { readonly window: ServerProviderUsageWindow; readonly
           />
         ) : null}
       </View>
-      {detail ? <Text className="text-xs text-foreground-tertiary">{detail}</Text> : null}
+      {pace || resetsIn ? (
+        <View className="flex-row justify-between gap-3">
+          <Text className="text-xs text-foreground-tertiary">{pace ? PACE_LABEL[pace] : ""}</Text>
+          <Text className="text-xs tabular-nums text-foreground-tertiary">{resetsIn ?? ""}</Text>
+        </View>
+      ) : null}
     </View>
   );
 }
 
+/** One account: icon, name and plan on a single line, then its windows. */
 function AccountLimits(props: {
+  readonly driver: Driver;
   readonly label: string;
   readonly instanceLabel: string;
   readonly detail: string | undefined;
@@ -83,23 +111,35 @@ function AccountLimits(props: {
   readonly footer?: ReactNode;
 }) {
   const { limits, now } = props;
+  const color = useBarColor(props.driver);
   if (!limits) return null;
   const notice = limitsNotice(limits);
   return (
     <View className={props.first ? "gap-3 p-4" : "gap-3 border-t border-border-subtle p-4"}>
-      <View className="flex-row flex-wrap items-baseline gap-x-2 gap-y-1">
-        <Text className="text-lg text-foreground">{props.label}</Text>
-        {props.instanceLabel !== props.label ? (
-          <Text className="shrink text-xs text-foreground-tertiary">· {props.instanceLabel}</Text>
-        ) : null}
-        {props.detail ? (
-          <Text className="shrink text-sm text-foreground-muted">· {props.detail}</Text>
-        ) : null}
+      <View className="flex-row items-center gap-2">
+        <ProviderIcon provider={props.driver} size={16} />
+        <View className="min-w-0 flex-1 flex-row items-baseline gap-2">
+          <Text className="text-base font-t3-medium text-foreground">{props.label}</Text>
+          {props.instanceLabel !== props.label ? (
+            <Text className="shrink text-xs text-foreground-tertiary" numberOfLines={1}>
+              · {props.instanceLabel}
+            </Text>
+          ) : null}
+          {props.detail ? (
+            <Text className="shrink text-sm text-foreground-muted" numberOfLines={1}>
+              · {props.detail}
+            </Text>
+          ) : null}
+        </View>
       </View>
       {notice ? (
         <Text className="text-sm text-foreground-muted">{notice}</Text>
       ) : (
-        limits.windows.map((window) => <WindowBar key={window.id} window={window} now={now} />)
+        <View className="gap-3">
+          {limits.windows.map((window) => (
+            <WindowRow key={window.id} window={window} color={color} now={now} />
+          ))}
+        </View>
       )}
       {props.footer}
     </View>
@@ -170,7 +210,7 @@ function ResetCredits(props: {
   };
 
   return (
-    <View className="gap-2">
+    <View className="flex-row flex-wrap items-center gap-x-3 gap-y-1">
       <Text className="text-xs tabular-nums text-foreground-tertiary">{summary}</Text>
       {credits.availableCount > 0 ? (
         <Pressable
@@ -178,7 +218,7 @@ function ResetCredits(props: {
           accessibilityState={{ disabled: busy }}
           disabled={busy}
           onPress={confirm}
-          className="self-start rounded-full bg-subtle-strong px-3 py-1.5"
+          className="rounded-full bg-subtle-strong px-3 py-1.5"
         >
           <Text className="text-sm font-t3-medium text-foreground">
             {busy ? "Using credit…" : "Use a reset credit"}
@@ -200,6 +240,7 @@ function ProviderLimits(props: {
   const credits = provider.usageLimits?.resetCredits;
   return (
     <AccountLimits
+      driver={provider.driver}
       label={DRIVER_LABEL[provider.driver] ?? String(provider.driver)}
       instanceLabel={providerLimitsLabel(provider, (driver) => DRIVER_LABEL[driver])}
       detail={provider.auth.label}
@@ -229,6 +270,7 @@ function SourceAccountLimits(props: {
   const { account } = props;
   return (
     <AccountLimits
+      driver={account.driver}
       label={DRIVER_LABEL[account.driver] ?? String(account.driver)}
       instanceLabel="CLI Proxy"
       detail={account.plan}
@@ -239,21 +281,97 @@ function SourceAccountLimits(props: {
   );
 }
 
+/**
+ * Re-probes every provider (and usage-limit source) on each connected
+ * environment; the fresh snapshots then arrive over the config stream.
+ * Manual refreshes re-anchor the clock; incoming snapshots can also advance
+ * the rendered countdowns and pace. No periodic clock updates are scheduled.
+ * Environments whose probe failed are named, since their rows keep showing
+ * the previous quota with nothing else to say so.
+ */
+export function useRefreshLimits() {
+  const presentations = useAtomValue(environmentPresentations.presentationsAtom);
+  const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
+    reportFailure: false,
+  });
+  const [now, setNow] = useState(() => Date.now());
+  const [refreshing, setRefreshing] = useState(false);
+  const [failedLabels, setFailedLabels] = useState<readonly string[]>([]);
+  // Always toggles `refreshing`, even with nothing to probe: Android's
+  // RefreshControl keeps its spinner up until it sees true then false.
+  const refresh = async () => {
+    const connected = [...presentations].filter(
+      ([, presentation]) => presentation.connection.phase === "connected",
+    );
+    setRefreshing(true);
+    try {
+      const results = await Promise.all(
+        connected.map(([environmentId]) => refreshProviders({ environmentId, input: {} })),
+      );
+      setFailedLabels(
+        connected
+          .filter((_, index) => {
+            const result = results[index];
+            return result?._tag === "Failure" && !isAtomCommandInterrupted(result);
+          })
+          .map(([, presentation]) => presentation.entry.target.label),
+      );
+    } finally {
+      setNow(Date.now());
+      setRefreshing(false);
+    }
+  };
+  return { now, refreshing, failedLabels, refresh };
+}
+
 /**
  * Subscription quota windows from every connected environment's providers,
- * read from the config each environment already streams. Countdowns anchor to
- * render time rather than ticking.
+ * read from the config each environment already streams.
  */
-export function UsageLimitsSection() {
+export function UsageLimitsSection(props: {
+  readonly now: number;
+  readonly failedLabels: readonly string[];
+}) {
+  // Incoming snapshots also refresh the countdown anchor, without clock ticks.
+  const now = Date.now();
   const presentations = useAtomValue(environmentPresentations.presentationsAtom);
   const groups = collectLimitsGroups(presentations);
   const sources = collectLimitSources(presentations);
-  // Refresh the anchor with incoming snapshots, without scheduling clock ticks.
-  const now = Date.now();
-  if (groups.length === 0 && sources.length === 0) return null;
+
+  if (groups.length === 0 && sources.length === 0) {
+    return (
+      <Text className="py-16 text-center text-base text-foreground-muted">
+        No provider on a connected environment reports subscription limits.
+      </Text>
+    );
+  }
 
   return (
     <>
+      {props.failedLabels.length > 0 ? (
+        <View className="rounded-[16px] border-continuous bg-card px-4 py-3">
+          <Text className="text-sm text-foreground-muted">
+            {props.failedLabels.join(", ")} could not refresh limits. Showing the last known values.
+          </Text>
+        </View>
+      ) : null}
+      {groups.map((group) => (
+        <SettingsSection
+          key={group.environmentId}
+          title={group.environmentLabel ?? "Providers"}
+          card
+        >
+          {group.providers.map((provider, index) => (
+            <ProviderLimits
+              key={provider.instanceId}
+              provider={provider}
+              environmentId={group.environmentId}
+              now={now}
+              first={index === 0}
+            />
+          ))}
+        </SettingsSection>
+      ))}
       {sources.map((source) => (
         <SettingsSection key={source.key} card>
           {source.error ? (
@@ -276,23 +394,6 @@ export function UsageLimitsSection() {
           )}
         </SettingsSection>
       ))}
-      {groups.map((group) => (
-        <SettingsSection
-          key={group.environmentId}
-          title={group.environmentLabel ? `Limits · ${group.environmentLabel}` : "Limits"}
-          card
-        >
-          {group.providers.map((provider, index) => (
-            <ProviderLimits
-              key={provider.instanceId}
-              provider={provider}
-              environmentId={group.environmentId}
-              now={now}
-              first={index === 0}
-            />
-          ))}
-        </SettingsSection>
-      ))}
     </>
   );
 }
diff --git a/apps/mobile/src/features/usage/UsageRouteScreen.tsx b/apps/mobile/src/features/usage/UsageRouteScreen.tsx
index 621c9d2d6f19..17841cbd74fa 100644
--- a/apps/mobile/src/features/usage/UsageRouteScreen.tsx
+++ b/apps/mobile/src/features/usage/UsageRouteScreen.tsx
@@ -1,5 +1,4 @@
 import { useNavigation } from "@react-navigation/native";
-import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
 import type { DailyTotals, MergedUsage } from "@t3tools/shared/usageMerge";
 import {
   enumerateDays,
@@ -13,34 +12,51 @@ import {
   makeWindow,
 } from "@t3tools/shared/usageFormat";
 import { useMemo, useState } from "react";
-import { Alert, Platform, Pressable, RefreshControl, ScrollView, View } from "react-native";
+import { Platform, Pressable, RefreshControl, ScrollView, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 
 import { AndroidScreenHeader } from "../../components/AndroidScreenHeader";
 import { AppText as Text } from "../../components/AppText";
+import { cn } from "../../lib/cn";
 import { NativeStackScreenOptions } from "../../native/StackHeader";
-import { useEnvironments } from "../../state/environments";
-import { serverEnvironment } from "../../state/server";
-import { useAtomCommand } from "../../state/use-atom-command";
 import { useUsage, type EnvironmentUsageStatus } from "../../state/usage";
 import { SettingsSection } from "../settings/components/SettingsSection";
 import { UsageDailyChart } from "./UsageDailyChart";
-import { UsageLimitsSection } from "./UsageLimitsSection";
+import { UsageLimitsSection, useRefreshLimits } from "./UsageLimitsSection";
 import type { UsageChartMetric } from "./usageChartData";
 import { PROVIDER_LABEL, useProviderColors } from "./usageProviders";
 
+type UsageTab = "usage" | "limits";
+const TAB_OPTIONS = [
+  { value: "usage", label: "Usage" },
+  { value: "limits", label: "Limits" },
+] as const satisfies readonly { value: UsageTab; label: string }[];
+
+// Labels are abbreviated to share a row with the metric toggle; screen
+// readers get the full phrase.
 const WINDOW_OPTIONS = [
-  { days: 1, label: "Past 24h" },
-  { days: 7, label: "7 days" },
-  { days: 30, label: "30 days" },
-  { days: 90, label: "90 days" },
+  { value: 1, label: "24h", accessibilityLabel: "Past 24 hours" },
+  { value: 7, label: "7d", accessibilityLabel: "Past 7 days" },
+  { value: 30, label: "30d", accessibilityLabel: "Past 30 days" },
+  { value: 90, label: "90d", accessibilityLabel: "Past 90 days" },
 ] as const;
 
+const METRIC_OPTIONS = [
+  { value: "cost", label: "Cost" },
+  { value: "tokens", label: "Tokens" },
+] as const satisfies readonly { value: UsageChartMetric; label: string }[];
+
 const CHART_HEIGHT = 180;
 
+/**
+ * Two tabs over one screen. Usage is the transcript-derived spend for a
+ * period; Limits is the live subscription quota, which has no period. Both
+ * pull to refresh, each refreshing its own data.
+ */
 export function UsageRouteScreen() {
   const navigation = useNavigation();
   const insets = useSafeAreaInsets();
+  const [tab, setTab] = useState<UsageTab>("usage");
   const [windowSelection, setWindowSelection] = useState(() => ({
     days: 30,
     window: makeWindow(30),
@@ -49,10 +65,7 @@ export function UsageRouteScreen() {
   const { days: windowDays, window } = windowSelection;
   const isPast24Hours = windowDays === 1;
   const { merged, environments, isPending, isPartial, refresh } = useUsage(window);
-  const { environments: limitEnvironments } = useEnvironments();
-  const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
-    reportFailure: false,
-  });
+  const limits = useRefreshLimits();
 
   const days = useMemo(
     () => enumerateDays(window.sinceDay, window.untilDay),
@@ -81,7 +94,8 @@ export function UsageRouteScreen() {
   // The pull spinner tracks re-scans of environments that have answered
   // before. The initial scan renders its own placeholder, and an unreachable
   // environment stays pending forever — neither may pin the spinner on.
-  const refreshing = environments.some((entry) => entry.isPending && entry.summary !== null);
+  const refreshingUsage = environments.some((entry) => entry.isPending && entry.summary !== null);
+  const showingLimits = tab === "limits";
   const selectWindow = (days: number) => {
     setWindowSelection({
       days,
@@ -89,17 +103,6 @@ export function UsageRouteScreen() {
     });
   };
   const refreshWindow = () => {
-    // Refresh subscription limits alongside transcript usage on every connected host.
-    for (const environment of limitEnvironments) {
-      if (environment.connection.phase !== "connected") continue;
-      void refreshProviders({ environmentId: environment.environmentId, input: {} }).then(
-        (result) => {
-          if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
-            Alert.alert("Could not refresh limits", environment.label);
-          }
-        },
-      );
-    }
     const nextWindow = makeWindow(windowDays, undefined, isPast24Hours ? "hour" : "day");
     if (
       nextWindow.sinceDay === window.sinceDay &&
@@ -122,46 +125,75 @@ export function UsageRouteScreen() {
         </>
       ) : null}
       <ScrollView
+        // Remount at each tab's native top. Scrolling to y: 0 ignores iOS's
+        // automatic header inset and hides the tab bar under the header.
+        key={tab}
         contentInsetAdjustmentBehavior="automatic"
         showsVerticalScrollIndicator={false}
         className="flex-1"
         contentContainerClassName="gap-6 px-5 pt-4"
         contentContainerStyle={{ paddingBottom: Math.max(insets.bottom, 18) + 18 }}
-        refreshControl={<RefreshControl refreshing={refreshing} onRefresh={refreshWindow} />}
+        refreshControl={
+          <RefreshControl
+            refreshing={showingLimits ? limits.refreshing : refreshingUsage}
+            onRefresh={showingLimits ? () => void limits.refresh() : refreshWindow}
+          />
+        }
       >
-        <SegmentedControl
-          options={WINDOW_OPTIONS.map((option) => ({ value: option.days, label: option.label }))}
-          selected={windowDays}
-          onSelect={selectWindow}
-        />
+        <SegmentedControl options={TAB_OPTIONS} selected={tab} onSelect={setTab} role="tab" />
 
-        <UsageCoverageNotice environments={environments} merged={merged} isPartial={isPartial} />
-
-        {isPending ? (
-          <Text className="py-16 text-center text-base text-foreground-muted">
-            Scanning provider transcripts…
-          </Text>
-        ) : environments.length === 0 ? (
-          <Text className="py-16 text-center text-base text-foreground-muted">
-            Connect an environment to see usage.
-          </Text>
+        {showingLimits ? (
+          <UsageLimitsSection now={limits.now} failedLabels={limits.failedLabels} />
         ) : (
           <>
-            <ChartCard
+            {/* Period and metric together: neither applies to Limits, and
+                both change every number below, so they share one bar. */}
+            <View className="flex-row items-center gap-3">
+              <SegmentedControl
+                options={WINDOW_OPTIONS}
+                selected={windowDays}
+                onSelect={selectWindow}
+                size="compact"
+                className="flex-1"
+              />
+              <SegmentedControl
+                options={METRIC_OPTIONS}
+                selected={metric}
+                onSelect={setMetric}
+                size="compact"
+                className="w-36"
+              />
+            </View>
+            <UsageCoverageNotice
+              environments={environments}
               merged={merged}
-              days={chartDays}
-              daily={chartTotals}
-              metric={metric}
-              onMetricChange={setMetric}
-              sinceDay={window.sinceDay}
-              untilDay={window.untilDay}
-              isPast24Hours={isPast24Hours}
-              timeZone={window.timeZone}
+              isPartial={isPartial}
             />
-            <ProviderSection merged={merged} metric={metric} />
-            <UsageLimitsSection />
-            <TotalsSection merged={merged} isPast24Hours={isPast24Hours} />
-            <ModelsSection merged={merged} />
+            {isPending ? (
+              <Text className="py-16 text-center text-base text-foreground-muted">
+                Scanning provider transcripts…
+              </Text>
+            ) : environments.length === 0 ? (
+              <Text className="py-16 text-center text-base text-foreground-muted">
+                Connect an environment to see usage.
+              </Text>
+            ) : (
+              <>
+                <ChartCard
+                  merged={merged}
+                  days={chartDays}
+                  daily={chartTotals}
+                  metric={metric}
+                  sinceDay={window.sinceDay}
+                  untilDay={window.untilDay}
+                  isPast24Hours={isPast24Hours}
+                  timeZone={window.timeZone}
+                />
+                <ProviderSection merged={merged} metric={metric} />
+                <TotalsSection merged={merged} isPast24Hours={isPast24Hours} />
+                <ModelsSection merged={merged} />
+              </>
+            )}
           </>
         )}
       </ScrollView>
@@ -170,30 +202,48 @@ export function UsageRouteScreen() {
 }
 
 function SegmentedControl<Value extends number | string>(props: {
-  readonly options: readonly { readonly value: Value; readonly label: string }[];
+  readonly options: readonly {
+    readonly value: Value;
+    readonly label: string;
+    readonly accessibilityLabel?: string;
+  }[];
   readonly selected: Value;
   readonly onSelect: (value: Value) => void;
+  /** The tab bar is full height; filters under it are shorter so it stays primary. */
+  readonly size?: "default" | "compact";
+  /** "tab" for the view switcher; filters stay plain buttons. */
+  readonly role?: "tab" | "button";
+  readonly className?: string;
 }) {
+  const compact = props.size === "compact";
   return (
-    <View className="flex-row overflow-hidden rounded-full border-continuous bg-card">
+    <View
+      accessibilityRole={props.role === "tab" ? "tablist" : undefined}
+      className={cn(
+        "flex-row overflow-hidden rounded-full border-continuous bg-card",
+        props.className,
+      )}
+    >
       {props.options.map((option) => {
         const active = option.value === props.selected;
         return (
           <Pressable
             key={String(option.value)}
-            accessibilityRole="button"
+            accessibilityRole={props.role ?? "button"}
+            accessibilityLabel={option.accessibilityLabel}
             accessibilityState={{ selected: active }}
             onPress={() => props.onSelect(option.value)}
-            className={
-              active
-                ? "flex-1 items-center rounded-full bg-subtle-strong py-2"
-                : "flex-1 items-center py-2"
-            }
+            className={cn(
+              "flex-1 items-center justify-center rounded-full",
+              compact ? "h-9" : "h-11",
+              active && "bg-subtle-strong",
+            )}
           >
             <Text
-              className={
-                active ? "text-sm font-t3-medium text-foreground" : "text-sm text-foreground-muted"
-              }
+              className={cn(
+                compact ? "text-xs" : "text-sm",
+                active ? "font-t3-medium text-foreground" : "text-foreground-muted",
+              )}
             >
               {option.label}
             </Text>
@@ -210,7 +260,6 @@ function ChartCard(props: {
   readonly days: readonly string[];
   readonly daily: readonly DailyTotals[];
   readonly metric: UsageChartMetric;
-  readonly onMetricChange: (metric: UsageChartMetric) => void;
   readonly sinceDay: string;
   readonly untilDay: string;
   readonly isPast24Hours: boolean;
@@ -222,21 +271,18 @@ function ChartCard(props: {
 
   return (
     <View className="gap-4 rounded-[24px] border-continuous bg-card p-4">
-      <View className="flex-row items-start justify-between gap-3">
-        <View className="min-w-0 flex-1 gap-0.5">
-          <Text className="text-sm text-foreground-muted">
-            {metric === "cost" ? "Raw token cost" : "Processed tokens"}
-          </Text>
-          <Text className="text-4xl font-t3-bold tabular-nums text-foreground">
-            {metric === "cost" ? `${formatUsd(merged.costUsd)}*` : formatTokens(merged.totalTokens)}
-          </Text>
-          <Text className="text-sm text-foreground-muted">
-            {metric === "cost"
-              ? "* if billed at full API rate"
-              : `Across ${formatCount(merged.sessions)} sessions`}
-          </Text>
-        </View>
-        <MetricToggle metric={metric} onChange={props.onMetricChange} />
+      <View className="gap-0.5">
+        <Text className="text-sm text-foreground-muted">
+          {metric === "cost" ? "Raw token cost" : "Processed tokens"}
+        </Text>
+        <Text className="text-4xl font-t3-bold tabular-nums text-foreground">
+          {metric === "cost" ? `${formatUsd(merged.costUsd)}*` : formatTokens(merged.totalTokens)}
+        </Text>
+        <Text className="text-sm text-foreground-muted">
+          {metric === "cost"
+            ? "* if billed at full API rate"
+            : `Across ${formatCount(merged.sessions)} sessions`}
+        </Text>
       </View>
 
       {hasActivity ? (
@@ -281,38 +327,6 @@ function ChartCard(props: {
   );
 }
 
-function MetricToggle(props: {
-  readonly metric: UsageChartMetric;
-  readonly onChange: (metric: UsageChartMetric) => void;
-}) {
-  return (
-    <View className="flex-row overflow-hidden rounded-full bg-subtle">
-      {(["cost", "tokens"] as const).map((option) => {
-        const active = option === props.metric;
-        return (
-          <Pressable
-            key={option}
-            accessibilityRole="button"
-            accessibilityState={{ selected: active }}
-            onPress={() => props.onChange(option)}
-            className={active ? "rounded-full bg-subtle-strong px-3 py-1.5" : "px-3 py-1.5"}
-          >
-            <Text
-              className={
-                active
-                  ? "text-xs font-t3-medium uppercase text-foreground"
-                  : "text-xs uppercase text-foreground-muted"
-              }
-            >
-              {option}
-            </Text>
-          </Pressable>
-        );
-      })}
-    </View>
-  );
-}
-
 function ProviderSection(props: {
   readonly merged: MergedUsage;
   readonly metric: UsageChartMetric;
diff --git a/apps/mobile/src/lib/appearancePreferences.test.ts b/apps/mobile/src/lib/appearancePreferences.test.ts
index 3458f0120f99..417a66138d95 100644
--- a/apps/mobile/src/lib/appearancePreferences.test.ts
+++ b/apps/mobile/src/lib/appearancePreferences.test.ts
@@ -2,19 +2,13 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   DEFAULT_BASE_FONT_SIZE,
-  deriveCodeFontSize,
-  deriveTerminalFontSize,
   normalizeBaseFontSize,
-  normalizeCodeFontSize,
-  normalizeCodeWordBreak,
   resolveAppearance,
   resolveAppearancePreferences,
   resolveMarkdownFontSizes,
   resolveMobileCodeSurface,
   resolveNativeMarkdownTypography,
   resolveTextScaleVariables,
-  stepBaseFontSize,
-  stepCodeFontSize,
   stepTerminalFontSize,
 } from "./appearancePreferences";
 
@@ -50,10 +44,8 @@ describe("appearancePreferences", () => {
     expect(appearance.isCodeFontSizeCustom).toBe(false);
 
     const scaled = resolveAppearance(resolveAppearancePreferences({ baseFontSize: 22 }));
-    expect(scaled.terminalFontSize).toBe(deriveTerminalFontSize(22));
-    expect(scaled.codeFontSize).toBe(deriveCodeFontSize(22));
-    expect(scaled.terminalFontSize).toBeGreaterThan(10);
-    expect(scaled.codeFontSize).toBeGreaterThan(11);
+    expect(scaled.terminalFontSize).toBe(14);
+    expect(scaled.codeFontSize).toBe(17);
   });
 
   it("applies explicit overrides over derived values", () => {
@@ -69,15 +61,12 @@ describe("appearancePreferences", () => {
   it("clamps base and code font sizes", () => {
     expect(normalizeBaseFontSize(4)).toBe(11);
     expect(normalizeBaseFontSize(30)).toBe(22);
-    expect(normalizeCodeFontSize(4)).toBe(8);
-    expect(normalizeCodeFontSize(30)).toBe(18);
+    expect(resolveAppearancePreferences({ codeFontSize: 4 }).codeFontSize).toBe(8);
+    expect(resolveAppearancePreferences({ codeFontSize: 30 }).codeFontSize).toBe(18);
   });
 
-  it("steps font sizes within bounds", () => {
+  it("steps terminal font size within bounds", () => {
     expect(stepTerminalFontSize(6, -1)).toBe(6);
-    expect(stepBaseFontSize(11, -1)).toBe(11);
-    expect(stepCodeFontSize(8, -1)).toBe(8);
-    expect(stepBaseFontSize(15, 1)).toBe(16);
   });
 
   it("scales markdown typography from the base size", () => {
@@ -97,9 +86,8 @@ describe("appearancePreferences", () => {
     });
   });
 
-  it("defaults code word break to false", () => {
-    expect(normalizeCodeWordBreak(undefined)).toBe(false);
-    expect(normalizeCodeWordBreak(true)).toBe(true);
+  it("keeps explicit code word break enabled", () => {
+    expect(resolveAppearancePreferences({ codeWordBreak: true }).codeWordBreak).toBe(true);
   });
 
   it("returns the authored text scale at the 16pt default", () => {
diff --git a/apps/mobile/src/lib/appearancePreferences.ts b/apps/mobile/src/lib/appearancePreferences.ts
index d2504a629dda..2ce6a8b5a367 100644
--- a/apps/mobile/src/lib/appearancePreferences.ts
+++ b/apps/mobile/src/lib/appearancePreferences.ts
@@ -75,7 +75,7 @@ export function normalizeBaseFontSize(value: number | null | undefined): number
   return Math.min(MAX_BASE_FONT_SIZE, Math.max(MIN_BASE_FONT_SIZE, Math.round(value)));
 }
 
-export function normalizeCodeFontSize(value: number | null | undefined): number {
+function normalizeCodeFontSize(value: number | null | undefined): number {
   if (typeof value !== "number" || !Number.isFinite(value)) {
     return DEFAULT_CODE_FONT_SIZE;
   }
@@ -83,18 +83,18 @@ export function normalizeCodeFontSize(value: number | null | undefined): number
   return Math.min(MAX_CODE_FONT_SIZE, Math.max(MIN_CODE_FONT_SIZE, Math.round(value)));
 }
 
-export function normalizeCodeWordBreak(value: boolean | null | undefined): boolean {
+function normalizeCodeWordBreak(value: boolean | null | undefined): boolean {
   return value === true;
 }
 
 /** Terminal size derived from base: 10.5pt at base 16, snapped to 0.5pt steps. */
-export function deriveTerminalFontSize(baseFontSize: number): number {
+function deriveTerminalFontSize(baseFontSize: number): number {
   const scale = normalizeBaseFontSize(baseFontSize) / DEFAULT_BASE_FONT_SIZE;
   return normalizeTerminalFontSize(Math.round(DEFAULT_TERMINAL_FONT_SIZE * scale * 2) / 2);
 }
 
 /** Code/diff size derived from base: 12pt at base 16. */
-export function deriveCodeFontSize(baseFontSize: number): number {
+function deriveCodeFontSize(baseFontSize: number): number {
   const scale = normalizeBaseFontSize(baseFontSize) / DEFAULT_BASE_FONT_SIZE;
   return normalizeCodeFontSize(Math.round(DEFAULT_CODE_FONT_SIZE * scale));
 }
@@ -235,22 +235,12 @@ export function resolveNativeMarkdownTypography(baseFontSize: number): NativeMar
   };
 }
 
-export function stepBaseFontSize(current: number, direction: -1 | 1): number {
-  const next = direction === -1 ? current - BASE_FONT_SIZE_STEP : current + BASE_FONT_SIZE_STEP;
-  return normalizeBaseFontSize(next);
-}
-
 export function stepTerminalFontSize(current: number, direction: -1 | 1): number {
   const next =
     direction === -1 ? current - TERMINAL_FONT_SIZE_STEP : current + TERMINAL_FONT_SIZE_STEP;
   return normalizeTerminalFontSize(next);
 }
 
-export function stepCodeFontSize(current: number, direction: -1 | 1): number {
-  const next = direction === -1 ? current - CODE_FONT_SIZE_STEP : current + CODE_FONT_SIZE_STEP;
-  return normalizeCodeFontSize(next);
-}
-
 export {
   DEFAULT_TERMINAL_FONT_SIZE,
   MAX_TERMINAL_FONT_SIZE,
diff --git a/apps/mobile/src/lib/attachmentUpload.test.ts b/apps/mobile/src/lib/attachmentUpload.test.ts
index 5e8a34dd1cdb..c7289d8cb693 100644
--- a/apps/mobile/src/lib/attachmentUpload.test.ts
+++ b/apps/mobile/src/lib/attachmentUpload.test.ts
@@ -14,6 +14,7 @@ const mocks = vi.hoisted(() => ({
   upload: vi.fn(),
   writeFile: vi.fn(),
   deleteFile: vi.fn(),
+  readBase64: vi.fn(),
 }));
 
 vi.mock("@t3tools/client-runtime/state/runtime", () => ({
@@ -30,6 +31,11 @@ vi.mock("../state/atom-registry", () => ({
   appAtomRegistry: { get: mocks.readAtom },
 }));
 
+// The real read lease and cleanup are covered by the composer ownership suite.
+vi.mock("../state/use-composer-drafts", () => ({
+  retainComposerAttachmentFileForPreview: () => () => {},
+}));
+
 vi.mock("../state/assets", () => ({
   assetEnvironment: { createUrl: mocks.createAssetUrl },
 }));
@@ -68,6 +74,10 @@ vi.mock("expo-file-system", () => ({
       mocks.deleteFile(this.uri);
     }
 
+    async base64() {
+      return mocks.readBase64(this.uri);
+    }
+
     upload(url: string, options: unknown) {
       return mocks.upload(this.uri, url, options);
     }
@@ -102,6 +112,16 @@ const image = {
   previewUri: "file:///images/screenshot.png",
 } as const satisfies DraftComposerAttachment;
 
+const fileBackedImage = {
+  id: "image-2",
+  type: "image",
+  name: "photo.png",
+  mimeType: "image/png",
+  sizeBytes: 3,
+  fileUri: "file:///documents/t3-composer-attachments/photo.png",
+  previewUri: "file:///documents/t3-composer-attachments/photo.png",
+} as const satisfies DraftComposerAttachment;
+
 const file = {
   id: "file-1",
   type: "file",
@@ -174,6 +194,8 @@ describe("prepareTurnAttachments", () => {
     mocks.upload.mockReset();
     mocks.writeFile.mockReset();
     mocks.deleteFile.mockReset();
+    mocks.readBase64.mockReset();
+    mocks.readBase64.mockResolvedValue("YWJj");
     mocks.readAtom.mockReturnValue(Option.some({ httpBaseUrl: "https://environment.example/" }));
     mocks.runAtomCommand.mockImplementation(async (_registry: unknown, command: unknown) =>
       command === mocks.createUploadUrl
@@ -208,6 +230,101 @@ describe("prepareTurnAttachments", () => {
     expect(mocks.upload).not.toHaveBeenCalled();
   });
 
+  it("inlines a file-backed image lazily when the server lacks image uploads", async () => {
+    const prepared = await prepareTurnAttachments({
+      environmentId,
+      attachments: [fileBackedImage],
+    });
+
+    expect(prepared.status).toBe("ready");
+    if (prepared.status !== "ready") return;
+    expect(prepared.attachments).toEqual([
+      {
+        type: "image",
+        name: "photo.png",
+        mimeType: "image/png",
+        sizeBytes: 3,
+        dataUrl: "data:image/png;base64,YWJj",
+      },
+    ]);
+    expect(mocks.readBase64).toHaveBeenCalledExactlyOnceWith(fileBackedImage.fileUri);
+    expect(mocks.upload).not.toHaveBeenCalled();
+  });
+
+  it("reads restored images from the current iOS document container for legacy sends", async () => {
+    const fileName = "33333333-3333-4333-8333-333333333333-photo.png";
+    mocks.documentUri =
+      "file:///var/mobile/Containers/Data/Application/22222222-2222-4222-8222-222222222222/Documents";
+    const oldUri = `file:///var/mobile/Containers/Data/Application/11111111-1111-4111-8111-111111111111/Documents/t3-composer-attachments/${fileName}`;
+    const prepared = await prepareTurnAttachments({
+      environmentId,
+      attachments: [{ ...fileBackedImage, fileUri: oldUri, previewUri: oldUri }],
+    });
+    expect(prepared.status).toBe("ready");
+    expect(mocks.readBase64).toHaveBeenCalledExactlyOnceWith(
+      `${mocks.documentUri}/t3-composer-attachments/${fileName}`,
+    );
+  });
+
+  it("rejects a legacy image without inline bytes or a file", async () => {
+    const { fileUri: _, ...missingImage } = fileBackedImage;
+    await expect(
+      prepareTurnAttachments({ environmentId, attachments: [missingImage] }),
+    ).rejects.toThrow("'photo.png' is no longer available. Attach the image again.");
+  });
+
+  it.each(["resolve", "reject"] as const)(
+    "abandons a canceled legacy image read that later %ss",
+    async (outcome) => {
+      const readStarted = Promise.withResolvers<void>();
+      const read = Promise.withResolvers<string>();
+      const controller = new AbortController();
+      mocks.readBase64.mockImplementation(() => {
+        readStarted.resolve();
+        return read.promise;
+      });
+      const preparing = prepareTurnAttachments({
+        environmentId,
+        attachments: [fileBackedImage],
+        signal: controller.signal,
+      });
+      await readStarted.promise;
+      controller.abort();
+      if (outcome === "resolve") read.resolve("YWJj");
+      else read.reject(new Error("Native read failed after cancellation"));
+
+      await expect(preparing).resolves.toEqual({ status: "abandoned" });
+    },
+  );
+
+  it("uploads a file-backed image from its owned copy without staging base64", async () => {
+    const prepared = await prepareTurnAttachments({
+      environmentId,
+      attachments: [fileBackedImage],
+      supportsImageUploads: true,
+    });
+
+    expect(mocks.upload).toHaveBeenCalledWith(
+      fileBackedImage.fileUri,
+      "https://environment.example/api/attachments/upload/signed",
+      expect.objectContaining({ headers: { "Content-Type": "image/png" } }),
+    );
+    expect(mocks.readBase64).not.toHaveBeenCalled();
+    expect(mocks.writeFile).not.toHaveBeenCalled();
+    expect(mocks.deleteFile).not.toHaveBeenCalled();
+    expect(prepared.status).toBe("ready");
+    if (prepared.status !== "ready") return;
+    expect(prepared.attachments).toEqual([
+      {
+        type: "image",
+        id: MINTED_ID,
+        name: "photo.png",
+        mimeType: "image/png",
+        sizeBytes: 3,
+      },
+    ]);
+  });
+
   it("uploads generic file bytes directly and keeps mixed attachment order", async () => {
     const prepared = await prepareTurnAttachments({ environmentId, attachments: [file, image] });
 
diff --git a/apps/mobile/src/lib/attachmentUpload.ts b/apps/mobile/src/lib/attachmentUpload.ts
index f39329373dd7..b6b5e3a8d635 100644
--- a/apps/mobile/src/lib/attachmentUpload.ts
+++ b/apps/mobile/src/lib/attachmentUpload.ts
@@ -20,16 +20,21 @@ import { appAtomRegistry } from "../state/atom-registry";
 import { assetEnvironment } from "../state/assets";
 import { attachmentEnvironment } from "../state/attachments";
 import { environmentSession } from "../state/session";
+import { retainComposerAttachmentFileForPreview } from "../state/use-composer-drafts";
 import { resolveOwnedComposerAttachmentFileUri } from "./composerAttachmentFiles";
-import { toUploadChatImageAttachments, type DraftComposerAttachment } from "./composerImages";
+import {
+  isFileBackedComposerAttachment,
+  type DraftComposerAttachment,
+  type DraftComposerImageAttachment,
+} from "./composerImages";
 import { uuidv4 } from "./uuid";
 
 /**
  * This module owns the server side of a composer attachment's lifecycle.
  * `prepareTurnAttachments` acquires pending uploads (verifying and reusing
  * persisted ones), hands the uploaded ids back to the attachment's durable
- * owner (queued outbox message or composer draft), and returns a release
- * handle for after the turn consumed the bytes. Nothing outside this module
+ * owner (queued outbox message or composer draft), and leaves their cleanup
+ * to that owner after it checks shared references. Nothing outside this module
  * mints or deletes pending uploads. The local-file side of the lifecycle is
  * owned by `removeThreadOutboxMessage` / the composer draft mutators, which
  * release files through `releaseUnusedComposerAttachmentFiles`.
@@ -144,8 +149,6 @@ export interface PreparedTurnAttachments {
   readonly draftAttachments: ReadonlyArray<DraftComposerAttachment>;
   /** Every pending upload backing this turn (reused and newly minted). */
   readonly pendingAttachmentIds: ReadonlyArray<string>;
-  /** Deletes all pending uploads once the delivered turn holds the bytes. */
-  readonly releaseUploads: () => Promise<void>;
 }
 
 export type PrepareTurnAttachmentsResult =
@@ -179,6 +182,48 @@ function attachmentUploadInput(attachment: DraftComposerAttachment) {
   return { ...fields, mimeType };
 }
 
+/**
+ * Wire shape for startTurn on servers without attachment uploads: pure inline
+ * uploads without client draft id / previewUri. File-backed images read their
+ * base64 from disk lazily, only when this legacy path is actually taken.
+ */
+async function toUploadChatImageAttachments(
+  attachments: ReadonlyArray<DraftComposerImageAttachment>,
+): Promise<ReadonlyArray<UploadChatImageAttachment>> {
+  return Promise.all(
+    attachments.map(async (attachment) => ({
+      type: attachment.type,
+      name: attachment.name,
+      mimeType: attachment.mimeType,
+      sizeBytes: attachment.sizeBytes,
+      dataUrl: await composerImageAttachmentDataUrl(attachment),
+    })),
+  );
+}
+
+/** Inline bytes for one image: legacy drafts carry them, file-backed ones read them from disk. */
+async function composerImageAttachmentDataUrl(
+  attachment: DraftComposerImageAttachment,
+): Promise<string> {
+  if (attachment.dataUrl !== undefined) {
+    return attachment.dataUrl;
+  }
+  if (!isFileBackedComposerAttachment(attachment)) {
+    throw new Error(`'${attachment.name}' is no longer available. Attach the image again.`);
+  }
+  const release = retainComposerAttachmentFileForPreview(attachment);
+  try {
+    const { File, Paths } = await import("expo-file-system");
+    const uri =
+      resolveOwnedComposerAttachmentFileUri(attachment.fileUri, Paths.document.uri) ??
+      attachment.fileUri;
+    const base64 = await new File(uri).base64();
+    return `data:${attachment.mimeType};base64,${base64}`;
+  } finally {
+    release();
+  }
+}
+
 async function uploadFileBytes(
   attachment: DraftComposerAttachment,
   url: string,
@@ -187,17 +232,21 @@ async function uploadFileBytes(
 ): Promise<void> {
   const { File, Paths, UploadType } = await import("expo-file-system");
   if (signal.aborted) throw new Error("Upload cancelled.");
+  // Legacy image drafts persisted inline bytes and stage them in a temp cache
+  // file for the native uploader. Everything else uploads its owned copy.
+  const fileUri = attachment.fileUri;
+  const inlineDataUrl = attachment.type === "image" ? attachment.dataUrl : undefined;
+  if (fileUri === undefined && inlineDataUrl === undefined) {
+    throw new Error(`'${attachment.name}' is no longer available. Attach the image again.`);
+  }
   const file =
-    attachment.type === "image"
+    fileUri === undefined
       ? new File(Paths.cache, `t3-upload-${uuidv4()}`)
-      : new File(
-          resolveOwnedComposerAttachmentFileUri(attachment.fileUri, Paths.document.uri) ??
-            attachment.fileUri,
-        );
+      : new File(resolveOwnedComposerAttachmentFileUri(fileUri, Paths.document.uri) ?? fileUri);
   try {
-    if (attachment.type === "image") {
+    if (fileUri === undefined && inlineDataUrl !== undefined) {
       file.create();
-      file.write(attachment.dataUrl.slice(attachment.dataUrl.indexOf(",") + 1), {
+      file.write(inlineDataUrl.slice(inlineDataUrl.indexOf(",") + 1), {
         encoding: "base64",
       });
     }
@@ -218,7 +267,7 @@ async function uploadFileBytes(
       throw new Error(`Upload failed for '${attachment.name}' (${result.status}).`);
     }
   } finally {
-    if (attachment.type === "image" && file.exists) file.delete();
+    if (fileUri === undefined && file.exists) file.delete();
   }
 }
 
@@ -255,17 +304,19 @@ export async function prepareTurnAttachments(input: {
     attachments,
     draftAttachments,
     pendingAttachmentIds,
-    releaseUploads: () => releasePendingAttachmentUploads(environmentId, pendingAttachmentIds),
   });
 
   if (input.attachments.length === 0 || (files.length === 0 && !input.supportsImageUploads)) {
-    return ready(
-      toUploadChatImageAttachments(
+    try {
+      const imageAttachments = await toUploadChatImageAttachments(
         input.attachments.filter((attachment) => attachment.type === "image"),
-      ),
-      [],
-      input.attachments,
-    );
+      );
+      if (input.signal?.aborted) return { status: "abandoned" };
+      return ready(imageAttachments, [], input.attachments);
+    } catch (error) {
+      if (input.signal?.aborted) return { status: "abandoned" };
+      throw error;
+    }
   }
 
   const connection = appAtomRegistry.get(
@@ -285,7 +336,7 @@ export async function prepareTurnAttachments(input: {
     for (const attachment of input.attachments) {
       if (controller.signal.aborted) throw new Error("Upload cancelled.");
       if (attachment.type === "image" && !input.supportsImageUploads) {
-        uploadedAttachments.push(...toUploadChatImageAttachments([attachment]));
+        uploadedAttachments.push(...(await toUploadChatImageAttachments([attachment])));
         continue;
       }
 
diff --git a/apps/mobile/src/lib/commandMetadata.test.ts b/apps/mobile/src/lib/commandMetadata.test.ts
deleted file mode 100644
index d1ba1d86eba9..000000000000
--- a/apps/mobile/src/lib/commandMetadata.test.ts
+++ /dev/null
@@ -1,36 +0,0 @@
-import { describe, expect, it, vi } from "vite-plus/test";
-
-import { makeQueuedMessageMetadata, makeTurnCommandMetadata } from "./commandMetadata";
-
-vi.mock("expo-crypto", () => ({
-  randomUUID: () => crypto.randomUUID(),
-}));
-
-describe("mobile command metadata", () => {
-  it("creates ids and timestamps for thread starts", () => {
-    const metadata = makeTurnCommandMetadata();
-
-    expect(metadata.commandId).toMatch(
-      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
-    );
-    expect(metadata.messageId).toMatch(
-      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
-    );
-    expect(metadata.threadId).toMatch(
-      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
-    );
-    expect(metadata.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
-  });
-
-  it("creates ids and timestamps for queued messages", () => {
-    const metadata = makeQueuedMessageMetadata();
-
-    expect(metadata.commandId).toMatch(
-      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
-    );
-    expect(metadata.messageId).toMatch(
-      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/,
-    );
-    expect(metadata.createdAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
-  });
-});
diff --git a/apps/mobile/src/lib/composer-image-schema.ts b/apps/mobile/src/lib/composer-image-schema.ts
index 3303dad36b0c..41aced8c98e5 100644
--- a/apps/mobile/src/lib/composer-image-schema.ts
+++ b/apps/mobile/src/lib/composer-image-schema.ts
@@ -8,10 +8,19 @@ export const DraftComposerImageAttachmentSchema = Schema.Struct({
   name: Schema.String,
   mimeType: Schema.String,
   sizeBytes: Schema.Number,
-  dataUrl: Schema.String,
+  // Accept future file-backed records before enabling the new image writers.
+  fileUri: Schema.optional(Schema.String.check(Schema.isNonEmpty())),
+  dataUrl: Schema.optional(Schema.String.check(Schema.isNonEmpty())),
   uploadedAttachmentId: Schema.optional(Schema.String),
   uploadEnvironmentId: Schema.optional(EnvironmentId),
-});
+}).check(
+  Schema.makeFilter(
+    ({ fileUri, dataUrl }) =>
+      fileUri !== undefined ||
+      dataUrl !== undefined ||
+      "Image attachment has no file or inline bytes.",
+  ),
+);
 
 export const DraftComposerFileAttachmentSchema = Schema.Struct({
   id: Schema.String,
diff --git a/apps/mobile/src/lib/composerImages.test.ts b/apps/mobile/src/lib/composerImages.test.ts
index 21f2edaf52f6..40e00a271f76 100644
--- a/apps/mobile/src/lib/composerImages.test.ts
+++ b/apps/mobile/src/lib/composerImages.test.ts
@@ -36,37 +36,7 @@ vi.mock("./uuid", () => ({
   uuidv4: () => "attachment-id",
 }));
 
-import {
-  convertPastedImagesToAttachments,
-  isOwnedPastedImageUri,
-  toUploadChatImageAttachments,
-} from "./composerImages";
-
-describe("toUploadChatImageAttachments", () => {
-  it("strips client draft id and previewUri for the startTurn wire shape", () => {
-    expect(
-      toUploadChatImageAttachments([
-        {
-          id: "client-draft-id",
-          type: "image",
-          name: "pasted-image.png",
-          mimeType: "image/png",
-          sizeBytes: 12,
-          dataUrl: "data:image/png;base64,AA==",
-          previewUri: "file:///tmp/preview.png",
-        },
-      ]),
-    ).toEqual([
-      {
-        type: "image",
-        name: "pasted-image.png",
-        mimeType: "image/png",
-        sizeBytes: 12,
-        dataUrl: "data:image/png;base64,AA==",
-      },
-    ]);
-  });
-});
+import { convertPastedImagesToAttachments, isOwnedPastedImageUri } from "./composerImages";
 
 describe("native pasted image cleanup", () => {
   beforeEach(() => {
diff --git a/apps/mobile/src/lib/composerImages.ts b/apps/mobile/src/lib/composerImages.ts
index 77c2ec225564..16faaedd96c2 100644
--- a/apps/mobile/src/lib/composerImages.ts
+++ b/apps/mobile/src/lib/composerImages.ts
@@ -20,9 +20,13 @@ import {
 import { beginForegroundHandoff } from "./foreground-handoff";
 import { uuidv4 } from "./uuid";
 
-export interface DraftComposerImageAttachment extends UploadChatImageAttachment {
+export interface DraftComposerImageAttachment extends Omit<UploadChatImageAttachment, "dataUrl"> {
   readonly id: string;
   readonly previewUri: string;
+  /** Owned image bytes from a file-backed draft. Current writers still use inline bytes. */
+  readonly fileUri?: string;
+  /** Inline bytes from current writers and older drafts. */
+  readonly dataUrl?: string;
   readonly uploadedAttachmentId?: string;
   readonly uploadEnvironmentId?: EnvironmentId;
 }
@@ -40,17 +44,14 @@ export interface DraftComposerFileAttachment {
 
 export type DraftComposerAttachment = DraftComposerImageAttachment | DraftComposerFileAttachment;
 
-/** Wire shape for startTurn: pure uploads without client draft id / previewUri. */
-export function toUploadChatImageAttachments(
-  attachments: ReadonlyArray<DraftComposerImageAttachment>,
-): ReadonlyArray<UploadChatImageAttachment> {
-  return attachments.map((attachment) => ({
-    type: attachment.type,
-    name: attachment.name,
-    mimeType: attachment.mimeType,
-    sizeBytes: attachment.sizeBytes,
-    dataUrl: attachment.dataUrl,
-  }));
+/** Any composer attachment whose bytes live in the app-owned attachment directory. */
+export type FileBackedComposerAttachment = DraftComposerAttachment & { readonly fileUri: string };
+
+/** Files have a local copy. Images can have one after a file-backed draft is restored. */
+export function isFileBackedComposerAttachment(
+  attachment: DraftComposerAttachment,
+): attachment is FileBackedComposerAttachment {
+  return attachment.fileUri !== undefined;
 }
 
 const OWNED_PASTED_IMAGE_DIRECTORY = "t3-composer-paste";
diff --git a/apps/mobile/src/lib/layout.test.ts b/apps/mobile/src/lib/layout.test.ts
index 8342fd1aeebc..7d288b1352a5 100644
--- a/apps/mobile/src/lib/layout.test.ts
+++ b/apps/mobile/src/lib/layout.test.ts
@@ -2,11 +2,9 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   constrainAuxiliaryPaneWidth,
-  constrainPrimarySidebarWidth,
   deriveCenteredContentHorizontalPadding,
   deriveFileInspectorPaneLayout,
   deriveLayout,
-  deriveStableFormSheetDetent,
   deriveThreadFeedInitialContentInset,
   deriveThreadWorkLogSizing,
   deriveWorkspacePaneLayout,
@@ -75,12 +73,6 @@ describe("deriveThreadFeedInitialContentInset", () => {
 });
 
 describe("resizable pane constraints", () => {
-  it("keeps a preferred sidebar width across large windows and clamps it in a narrow split view", () => {
-    expect(constrainPrimarySidebarWidth(430, 1_366)).toBe(430);
-    expect(constrainPrimarySidebarWidth(430, 744)).toBe(384);
-    expect(constrainPrimarySidebarWidth(100, 1_366)).toBe(280);
-  });
-
   it("preserves a useful main pane while constraining a trailing pane", () => {
     expect(constrainAuxiliaryPaneWidth({ preferredWidth: 440, availableWidth: 1_100 })).toBe(440);
     expect(constrainAuxiliaryPaneWidth({ preferredWidth: 440, availableWidth: 900 })).toBe(340);
@@ -392,14 +384,3 @@ describe("deriveWorkspacePaneLayout", () => {
     });
   });
 });
-
-describe("deriveStableFormSheetDetent", () => {
-  it.each([
-    { height: 1_194, expected: 0.62 },
-    { height: 834, expected: 0.863 },
-    { height: 600, expected: 0.893 },
-    { height: 0, expected: 0.92 },
-  ])("derives a stable sheet detent for height $height", ({ height, expected }) => {
-    expect(deriveStableFormSheetDetent(height)).toBe(expected);
-  });
-});
diff --git a/apps/mobile/src/lib/layout.ts b/apps/mobile/src/lib/layout.ts
index 4199dc8dc8ed..ee38ac020e74 100644
--- a/apps/mobile/src/lib/layout.ts
+++ b/apps/mobile/src/lib/layout.ts
@@ -16,7 +16,6 @@ export const SPLIT_LAYOUT_MIN_WIDTH = 720;
 export const SPLIT_LAYOUT_MIN_HEIGHT = 600;
 
 export const SPLIT_SIDEBAR_MIN_WIDTH = 280;
-export const SPLIT_SIDEBAR_MAX_WIDTH = 460;
 const SPLIT_SIDEBAR_DEFAULT_MAX_WIDTH = 380;
 
 export const AUXILIARY_PANE_MIN_CONTENT_WIDTH = 960;
@@ -50,10 +49,6 @@ export const AUXILIARY_PANE_MAX_WIDTH = 480;
 const AUXILIARY_PANE_DEFAULT_MAX_WIDTH = 320;
 const FILE_INSPECTOR_MIN_VIEWPORT_WIDTH = 820;
 const FILE_INSPECTOR_MIN_MAIN_WIDTH = 560;
-const STABLE_FORM_SHEET_MAX_HEIGHT = 720;
-const STABLE_FORM_SHEET_VERTICAL_MARGIN = 64;
-const STABLE_FORM_SHEET_MIN_DETENT = 0.62;
-const STABLE_FORM_SHEET_MAX_DETENT = 0.92;
 
 export type LayoutVariant = "compact" | "split";
 
@@ -218,22 +213,6 @@ export function deriveFileInspectorPaneLayout(input: {
   };
 }
 
-/** Keep a user-selected sidebar width useful as a window is resized. */
-export function constrainPrimarySidebarWidth(
-  preferredWidth: number,
-  viewportWidth = Number.POSITIVE_INFINITY,
-): number {
-  const safeWidth = Number.isFinite(preferredWidth) ? preferredWidth : SPLIT_SIDEBAR_MIN_WIDTH;
-  const viewportMax = Number.isFinite(viewportWidth)
-    ? Math.max(SPLIT_SIDEBAR_MIN_WIDTH, viewportWidth - 360)
-    : SPLIT_SIDEBAR_MAX_WIDTH;
-  return clamp(
-    Math.round(safeWidth),
-    SPLIT_SIDEBAR_MIN_WIDTH,
-    Math.min(SPLIT_SIDEBAR_MAX_WIDTH, viewportMax),
-  );
-}
-
 /**
  * Keep an auxiliary pane within native-feeling bounds without squeezing its
  * neighboring content below a usable reading/editor width.
@@ -275,20 +254,3 @@ export function deriveCenteredContentHorizontalPadding(input: {
 
   return minimumPadding + Math.max(0, (viewportWidth - input.maxContentWidth) / 2);
 }
-
-export function deriveStableFormSheetDetent(containerHeight: number): number {
-  if (!Number.isFinite(containerHeight) || containerHeight <= 0) {
-    return STABLE_FORM_SHEET_MAX_DETENT;
-  }
-
-  const targetHeight = Math.min(
-    STABLE_FORM_SHEET_MAX_HEIGHT,
-    Math.max(0, containerHeight - STABLE_FORM_SHEET_VERTICAL_MARGIN),
-  );
-  const detent = clamp(
-    targetHeight / containerHeight,
-    STABLE_FORM_SHEET_MIN_DETENT,
-    STABLE_FORM_SHEET_MAX_DETENT,
-  );
-  return Math.round(detent * 1_000) / 1_000;
-}
diff --git a/apps/mobile/src/lib/localAttachmentPreview.test.ts b/apps/mobile/src/lib/localAttachmentPreview.test.ts
index 2ed83b26f640..3693caa41185 100644
--- a/apps/mobile/src/lib/localAttachmentPreview.test.ts
+++ b/apps/mobile/src/lib/localAttachmentPreview.test.ts
@@ -46,6 +46,24 @@ beforeEach(() => {
 });
 
 describe("loadLocalAttachmentPreview", () => {
+  it("keeps an image MIME type when its filename has a video extension", async () => {
+    const image = {
+      ...attachment,
+      type: "image" as const,
+      name: "photo.mov",
+      mimeType: "image/png",
+      previewUri: attachment.fileUri,
+    };
+    const preview = await loadLocalAttachmentPreview(image, new AbortController().signal);
+    await preview!.share(new AbortController().signal);
+    expect(mocks.share).toHaveBeenCalledWith(
+      expect.objectContaining({
+        attachment: { name: "photo.mov", mimeType: "image/png" },
+      }),
+    );
+    preview!.dispose();
+  });
+
   it("retains and shares a PDF with its original filename and type", async () => {
     const pdf = { ...attachment, name: "report.pdf", mimeType: "application/pdf" };
     const preview = await loadLocalAttachmentPreview(pdf, new AbortController().signal);
diff --git a/apps/mobile/src/lib/localAttachmentPreview.ts b/apps/mobile/src/lib/localAttachmentPreview.ts
index bdd20e2e63d5..0d90f7210bab 100644
--- a/apps/mobile/src/lib/localAttachmentPreview.ts
+++ b/apps/mobile/src/lib/localAttachmentPreview.ts
@@ -1,13 +1,13 @@
 import { videoMimeType } from "@t3tools/shared/video";
 
-import type { DraftComposerFileAttachment } from "./composerImages";
+import type { FileBackedComposerAttachment } from "./composerImages";
 import { resolveOwnedComposerAttachmentFileUri } from "./composerAttachmentFiles";
 import { shareLocalAttachment, type AttachmentPreviewFile } from "./attachmentDownload";
 import { retainComposerAttachmentFileForPreview } from "../state/use-composer-drafts";
 
 /** Retains the draft original for preview and gives each outgoing share its own lease. */
 export async function loadLocalAttachmentPreview(
-  attachment: DraftComposerFileAttachment,
+  attachment: FileBackedComposerAttachment,
   signal: AbortSignal,
 ): Promise<AttachmentPreviewFile | null> {
   if (signal.aborted) return null;
@@ -41,7 +41,10 @@ export async function loadLocalAttachmentPreview(
             uri: file.uri,
             attachment: {
               name: attachment.name,
-              mimeType: videoMimeType(attachment) ?? attachment.mimeType,
+              mimeType:
+                attachment.type === "file"
+                  ? (videoMimeType(attachment) ?? attachment.mimeType)
+                  : attachment.mimeType,
             },
             signal: shareSignal,
             sourceIdentifier,
diff --git a/apps/mobile/src/lib/nativeMarkdownText.test.ts b/apps/mobile/src/lib/nativeMarkdownText.test.ts
index 1e7cb5f3164e..c3951c8d81f0 100644
--- a/apps/mobile/src/lib/nativeMarkdownText.test.ts
+++ b/apps/mobile/src/lib/nativeMarkdownText.test.ts
@@ -226,6 +226,29 @@ describe("nativeMarkdownDocumentRuns", () => {
     ]);
   });
 
+  it("decorates known skill references that begin with a digit", () => {
+    const node: MarkdownNode = {
+      type: "document",
+      children: [
+        {
+          type: "paragraph",
+          children: [{ type: "text", content: "Use $2spec for this." }],
+        },
+      ],
+    };
+
+    expect(nativeMarkdownDocumentRuns(node, [{ name: "2spec", displayName: "2Spec" }])).toEqual([
+      { text: "Use ", role: "body" },
+      {
+        text: "$2spec",
+        role: "body",
+        skillName: "2spec",
+        skillLabel: "2Spec",
+      },
+      { text: " for this.", role: "body" },
+    ]);
+  });
+
   it("decorates known skill references inside blockquotes", () => {
     const node: MarkdownNode = {
       type: "blockquote",
diff --git a/apps/mobile/src/lib/projectThreadStartTurn.test.ts b/apps/mobile/src/lib/projectThreadStartTurn.test.ts
index 754555dc2a82..bd7918e52d79 100644
--- a/apps/mobile/src/lib/projectThreadStartTurn.test.ts
+++ b/apps/mobile/src/lib/projectThreadStartTurn.test.ts
@@ -6,15 +6,13 @@ import {
   ThreadId,
 } from "@t3tools/contracts";
 import { serializeAssistantCitation } from "@t3tools/shared/assistantCitations";
-import { describe, expect, it, vi } from "vite-plus/test";
+import { describe, expect, it } from "vite-plus/test";
 
 import {
   buildProjectThreadStartTurnInput,
   deriveThreadTitleFromPrompt,
 } from "./projectThreadStartTurn";
 
-vi.mock("./composerImages", () => ({ toUploadChatImageAttachments: () => [] }));
-
 describe("project thread title", () => {
   it("keeps ordinary titles and the empty-prompt fallback", () => {
     expect(deriveThreadTitleFromPrompt("  Fix\n the parser  ")).toBe("Fix the parser");
@@ -52,7 +50,7 @@ describe("project thread title", () => {
       messageId: "message",
       createdAt: "2026-09-01T00:00:00Z",
       text,
-      attachments: [],
+      uploadedAttachments: [],
       modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.6-sol" },
       runtimeMode: "full-access",
       interactionMode: "default",
diff --git a/apps/mobile/src/lib/projectThreadStartTurn.ts b/apps/mobile/src/lib/projectThreadStartTurn.ts
index 3c3da90f962d..37190780c5ac 100644
--- a/apps/mobile/src/lib/projectThreadStartTurn.ts
+++ b/apps/mobile/src/lib/projectThreadStartTurn.ts
@@ -9,7 +9,6 @@ import {
 } from "@t3tools/contracts";
 import { assistantCitationsToPlainText } from "@t3tools/shared/assistantCitations";
 
-import { toUploadChatImageAttachments, type DraftComposerAttachment } from "./composerImages";
 import type { UploadedMobileAttachment } from "./attachmentUpload";
 
 export function deriveThreadTitleFromPrompt(value: string): string {
@@ -30,8 +29,8 @@ export interface ProjectThreadStartTurnSpec {
   readonly messageId: string;
   readonly createdAt: string;
   readonly text: string;
-  readonly attachments: ReadonlyArray<DraftComposerAttachment>;
-  readonly uploadedAttachments?: ReadonlyArray<UploadedMobileAttachment>;
+  /** Wire attachments from `prepareTurnAttachments`, in composer order. */
+  readonly uploadedAttachments: ReadonlyArray<UploadedMobileAttachment>;
   readonly modelSelection: ModelSelection;
   readonly runtimeMode: RuntimeMode;
   readonly interactionMode: ProviderInteractionMode;
@@ -58,11 +57,7 @@ export function buildProjectThreadStartTurnInput(spec: ProjectThreadStartTurnSpe
       messageId: MessageId.make(spec.messageId),
       role: "user" as const,
       text: spec.text,
-      attachments:
-        spec.uploadedAttachments ??
-        toUploadChatImageAttachments(
-          spec.attachments.filter((attachment) => attachment.type === "image"),
-        ),
+      attachments: spec.uploadedAttachments,
     },
     modelSelection: spec.modelSelection,
     titleSeed: title,
diff --git a/apps/mobile/src/lib/providerOptions.test.ts b/apps/mobile/src/lib/providerOptions.test.ts
index d87df6baaf1d..9b94cecb3db9 100644
--- a/apps/mobile/src/lib/providerOptions.test.ts
+++ b/apps/mobile/src/lib/providerOptions.test.ts
@@ -2,11 +2,7 @@ import { describe, expect, it } from "vite-plus/test";
 
 import type { ModelCapabilities } from "@t3tools/contracts";
 
-import {
-  applyProviderOptionSelection,
-  providerOptionValueLabels,
-  resolveProviderOptionDescriptors,
-} from "./providerOptions";
+import { applyProviderOptionSelection, resolveProviderOptionDescriptors } from "./providerOptions";
 
 const CODEX_CAPABILITIES: ModelCapabilities = {
   optionDescriptors: [
@@ -34,15 +30,6 @@ const CODEX_CAPABILITIES: ModelCapabilities = {
 };
 
 describe("mobile provider options", () => {
-  it("summarizes the option values currently in effect", () => {
-    const descriptors = resolveProviderOptionDescriptors({
-      capabilities: CODEX_CAPABILITIES,
-      selections: undefined,
-    });
-
-    expect(providerOptionValueLabels(descriptors)).toEqual(["Medium", "Standard"]);
-  });
-
   it("updates generic select options without knowing provider-specific ids", () => {
     const descriptors = resolveProviderOptionDescriptors({
       capabilities: CODEX_CAPABILITIES,
@@ -62,7 +49,7 @@ describe("mobile provider options", () => {
     expect(applyProviderOptionSelection(descriptors, { id: "unknown", value: "high" })).toBeNull();
   });
 
-  it("treats an unspecified boolean capability as off", () => {
+  it("updates generic boolean options", () => {
     const descriptors = resolveProviderOptionDescriptors({
       capabilities: {
         optionDescriptors: [{ id: "fastMode", label: "Fast Mode", type: "boolean" }],
@@ -70,7 +57,6 @@ describe("mobile provider options", () => {
       selections: undefined,
     });
 
-    expect(providerOptionValueLabels(descriptors)).toEqual([]);
     expect(applyProviderOptionSelection(descriptors, { id: "fastMode", value: true })).toEqual([
       { id: "fastMode", value: true },
     ]);
diff --git a/apps/mobile/src/lib/providerOptions.ts b/apps/mobile/src/lib/providerOptions.ts
index 593f5a37442c..dec0d327030d 100644
--- a/apps/mobile/src/lib/providerOptions.ts
+++ b/apps/mobile/src/lib/providerOptions.ts
@@ -5,7 +5,6 @@ import type {
 } from "@t3tools/contracts";
 import {
   buildProviderOptionSelectionsFromDescriptors,
-  getProviderOptionCurrentLabel,
   getProviderOptionDescriptors,
 } from "@t3tools/shared/model";
 
@@ -22,23 +21,6 @@ export function resolveProviderOptionDescriptors(input: {
   });
 }
 
-/**
- * Labels for the option values currently in effect (select values plus
- * enabled booleans), used to summarize the thread configuration in the
- * composer trigger pill.
- */
-export function providerOptionValueLabels(
-  descriptors: ReadonlyArray<ProviderOptionDescriptor>,
-): ReadonlyArray<string> {
-  return descriptors.flatMap((descriptor) => {
-    if (descriptor.type === "boolean") {
-      return descriptor.currentValue ? [descriptor.label] : [];
-    }
-    const label = getProviderOptionCurrentLabel(descriptor);
-    return label ? [label] : [];
-  });
-}
-
 /**
  * Applies one option change (by descriptor id) and returns the full selection
  * list to store on the model selection, or null when the change doesn't match
diff --git a/apps/mobile/src/lib/threadActivity.test.ts b/apps/mobile/src/lib/threadActivity.test.ts
index cca0bf6890f5..df3dd3197d0d 100644
--- a/apps/mobile/src/lib/threadActivity.test.ts
+++ b/apps/mobile/src/lib/threadActivity.test.ts
@@ -263,6 +263,68 @@ describe("pending user input answers", () => {
 });
 
 describe("pending approvals", () => {
+  it.each([{}, { requestType: "unknown" }])(
+    "exposes legacy OpenCode approvals without a known request kind: %j",
+    (legacyPayload) => {
+      const requested = makeActivity({
+        id: EventId.make("approval-legacy"),
+        kind: "approval.requested",
+        summary: "Approval requested",
+        createdAt: "2026-08-24T00:00:00.000Z",
+        payload: { requestId: "per-legacy", detail: "*", ...legacyPayload },
+      });
+
+      expect(derivePendingApprovals([requested])).toEqual([
+        {
+          requestId: "per-legacy",
+          requestKind: "command",
+          createdAt: requested.createdAt,
+          detail: "*",
+        },
+      ]);
+    },
+  );
+
+  it.each(["tool_user_input", "auth_tokens_refresh"])(
+    "does not turn %s into an approval",
+    (requestType) => {
+      const activity = makeActivity({
+        id: EventId.make("approval-non-approval"),
+        kind: "approval.requested",
+        summary: "Approval requested",
+        createdAt: "2026-08-24T00:00:00.000Z",
+        payload: { requestId: "not-an-approval", requestType },
+      });
+
+      expect(derivePendingApprovals([activity])).toEqual([]);
+    },
+  );
+
+  it.each(["approval.resolved", "provider.approval.respond.failed"])(
+    "removes legacy approvals after %s",
+    (kind) => {
+      const requested = makeActivity({
+        id: EventId.make("approval-legacy-open"),
+        kind: "approval.requested",
+        summary: "Approval requested",
+        createdAt: "2026-08-24T00:00:00.000Z",
+        payload: { requestId: "per-legacy", requestType: "unknown" },
+      });
+      const resolved = makeActivity({
+        id: EventId.make("approval-legacy-resolved"),
+        kind,
+        summary: "Approval resolved",
+        createdAt: "2026-08-24T00:00:01.000Z",
+        payload: {
+          requestId: "per-legacy",
+          detail: "Unknown pending permission request: per-legacy",
+        },
+      });
+
+      expect(derivePendingApprovals([requested, resolved])).toEqual([]);
+    },
+  );
+
   it("keeps app access approvals and persistence choices from remote environments", () => {
     const options = [
       { decision: "decline", label: "Decline" },
@@ -353,6 +415,173 @@ function makeThread(
 }
 
 describe("buildThreadFeed", () => {
+  it("reuses unchanged feed and presentation rows during an assistant text update", () => {
+    const completedTurnId = TurnId.make("completed-turn");
+    const activeTurnId = TurnId.make("active-turn");
+    const thread = makeThread({
+      id: ThreadId.make("feed-reuse"),
+      projectId: ProjectId.make("project-1"),
+      title: "Feed reuse",
+      messages: [
+        {
+          id: MessageId.make("completed-message"),
+          role: "assistant",
+          text: "Completed response",
+          turnId: completedTurnId,
+          streaming: false,
+          createdAt: "2026-04-01T00:00:01.000Z",
+          updatedAt: "2026-04-01T00:00:01.000Z",
+        },
+        {
+          id: MessageId.make("streaming-message"),
+          role: "assistant",
+          text: "Current response",
+          turnId: activeTurnId,
+          streaming: true,
+          createdAt: "2026-04-01T00:00:04.000Z",
+          updatedAt: "2026-04-01T00:00:04.000Z",
+        },
+      ],
+      activities: [
+        makeActivity({
+          id: EventId.make("completed-tool"),
+          kind: "tool.completed",
+          summary: "Read files",
+          createdAt: "2026-04-01T00:00:02.000Z",
+          turnId: completedTurnId,
+          payload: { itemType: "file_read", status: "completed" },
+        }),
+        makeActivity({
+          id: EventId.make("active-tool"),
+          kind: "tool.updated",
+          summary: "Run checks",
+          createdAt: "2026-04-01T00:00:03.000Z",
+          turnId: activeTurnId,
+          payload: { itemType: "command_execution", command: "vp test", status: "inProgress" },
+        }),
+      ],
+    });
+    const latestTurn = {
+      turnId: activeTurnId,
+      state: "running" as const,
+      startedAt: "2026-04-01T00:00:03.000Z",
+      completedAt: null,
+    };
+    const expandedTurns = new Set([completedTurnId]);
+    const expandedGroups = new Set(["work-group:completed-tool", "work-group:active-tool"]);
+    const previousFeed = buildThreadFeed(thread);
+    const previousRows = deriveThreadFeedPresentation(
+      previousFeed,
+      latestTurn,
+      expandedTurns,
+      expandedGroups,
+      latestTurn.startedAt,
+    );
+    const updatedMessage = {
+      ...thread.messages[1]!,
+      text: "Current response with more text",
+      updatedAt: "2026-04-01T00:00:05.000Z",
+    };
+    const nextFeed = buildThreadFeed({
+      ...thread,
+      messages: [thread.messages[0]!, updatedMessage],
+    });
+    const nextRows = deriveThreadFeedPresentation(
+      nextFeed,
+      latestTurn,
+      expandedTurns,
+      expandedGroups,
+      latestTurn.startedAt,
+    );
+
+    expect(nextFeed).toHaveLength(previousFeed.length);
+    expect(nextRows).toHaveLength(previousRows.length);
+    for (const [before, after] of [
+      [previousFeed, nextFeed],
+      [previousRows, nextRows],
+    ] as const) {
+      for (const [index, row] of after.entries()) {
+        if (row.id === updatedMessage.id) {
+          expect(row).not.toBe(before[index]);
+          expect(row).toMatchObject({ message: updatedMessage });
+        } else {
+          expect(row).toBe(before[index]);
+        }
+      }
+    }
+    expect(nextRows.some((row) => row.type === "turn-fold")).toBe(true);
+    expect(nextRows.some((row) => row.type === "activity-group")).toBe(true);
+  });
+
+  it("regroups cached activities for message changes and pagination", () => {
+    const messages = [2, 4].map((second) => ({
+      id: MessageId.make(`message-${second}`),
+      role: "assistant" as const,
+      text: second === 2 ? "" : "Response",
+      streaming: false,
+      turnId: null,
+      createdAt: `2026-04-01T00:00:0${second}.000Z`,
+      updatedAt: `2026-04-01T00:00:0${second}.000Z`,
+    }));
+    const thread = makeThread({
+      id: ThreadId.make("feed-regroup"),
+      projectId: ProjectId.make("project-1"),
+      title: "Feed grouping",
+      messages,
+      activities: [1, 3, 5].map((second) =>
+        makeActivity({
+          id: EventId.make(`work-${second}`),
+          kind: "runtime.warning",
+          summary: `Notice ${second}`,
+          createdAt: `2026-04-01T00:00:0${second}.000Z`,
+        }),
+      ),
+    });
+    const initial = buildThreadFeed(thread);
+    expect(initial.map((row) => row.id)).toEqual(["work-1", "message-4", "work-5"]);
+    const split = buildThreadFeed({
+      ...thread,
+      messages: [{ ...messages[0]!, text: "Now visible" }, messages[1]!],
+    });
+    expect(split.map((row) => row.id)).toEqual([
+      "work-1",
+      "message-2",
+      "work-3",
+      "message-4",
+      "work-5",
+    ]);
+    expect(split[0]).not.toBe(initial[0]);
+    expect(split.at(-1)).toBe(initial.at(-1));
+    expect(initial[0]).toMatchObject({ activities: [{ id: "work-1" }, { id: "work-3" }] });
+
+    const reordered = buildThreadFeed({
+      ...thread,
+      messages: [messages[0]!, { ...messages[1]!, createdAt: "2026-04-01T00:00:06.000Z" }],
+    });
+    expect(reordered.map((row) => row.id)).toEqual(["work-1", "message-4"]);
+    expect(reordered[0]).toMatchObject({
+      activities: [{ id: "work-1" }, { id: "work-3" }, { id: "work-5" }],
+    });
+    const olderMessage = {
+      ...messages[1]!,
+      id: MessageId.make("older-message"),
+      createdAt: "2026-04-01T00:00:00.000Z",
+    };
+    const page = buildThreadFeed(thread, {
+      loadedMessages: [messages[1]!],
+      localMessages: [olderMessage],
+    });
+    expect(page.map((row) => row.id)).toEqual(["older-message", "message-4", "work-5"]);
+    const prepended = buildThreadFeed(thread, { loadedMessages: [olderMessage, ...messages] });
+    expect(prepended.map((row) => row.id)).toEqual([
+      "older-message",
+      "work-1",
+      "message-4",
+      "work-5",
+    ]);
+    expect(prepended.at(-1)).toBe(page.at(-1));
+  });
+
   it("keeps context compaction as a standalone timeline row", () => {
     const thread = makeThread({
       id: ThreadId.make("thread-context-compaction"),
@@ -634,7 +863,8 @@ describe("buildThreadFeed", () => {
     };
 
     for (const currentTurn of [null, latestTurn]) {
-      const feed = buildThreadFeed({ ...thread, latestTurn: currentTurn });
+      const currentThread = { ...thread, latestTurn: currentTurn };
+      const feed = buildThreadFeed(currentThread);
       expect(feed).toMatchObject([
         {
           type: "activity-group",
@@ -1556,6 +1786,30 @@ describe("buildThreadFeed", () => {
       "work-toggle:work-group:tool-completed",
       "assistant-final",
     ]);
+
+    const interrupted = deriveThreadFeedPresentation(
+      feed,
+      { ...thread.latestTurn!, state: "interrupted", completedAt: "2026-04-01T00:00:20.000Z" },
+      new Set(),
+    );
+    expect(interrupted[1]).toMatchObject({
+      type: "turn-fold",
+      label: "You stopped after 19s",
+      expanded: false,
+    });
+    const retimed = deriveThreadFeedPresentation(
+      buildThreadFeed({
+        ...thread,
+        messages: [
+          thread.messages[0]!,
+          { ...thread.messages[1]!, updatedAt: "2026-04-01T00:00:25.000Z" },
+        ],
+      }),
+      null,
+      new Set(),
+    );
+    expect(retimed[1]).toMatchObject({ type: "turn-fold", label: "Worked for 23s" });
+    expect(collapsed[1]).toMatchObject({ type: "turn-fold", label: "Worked for 17s" });
   });
 
   it("folds assistant messages between the first and terminal messages", () => {
@@ -1854,6 +2108,15 @@ describe("buildThreadFeed", () => {
         { id: "activity-3", groupedToolDetail: true, live: false },
       ],
     });
+    const unchanged = deriveThreadFeedPresentation(
+      feed,
+      null,
+      new Set(),
+      new Set(["work-group:activity-1", "unrelated-group"]),
+    );
+    expect(unchanged[0]).toBe(expanded[0]);
+    expect(unchanged[1]).toBe(expanded[1]);
+    expect(deriveThreadFeedPresentation(feed, null, new Set())).toEqual(collapsed);
   });
 
   it.each(
@@ -2210,6 +2473,43 @@ describe("buildThreadFeed", () => {
         { id: "call-b-2", lifecycleStatus: "completed", groupedToolDetail: true, live: false },
       ],
     });
+
+    const correctedFeed = buildThreadFeed({
+      ...thread,
+      activities: thread.activities.map((activity) =>
+        activity.id === "call-a-3"
+          ? {
+              ...activity,
+              tone: "error",
+              payload: {
+                toolCallId: "call-a",
+                itemType: "command_execution",
+                status: "failed",
+                detail: "Corrected failure output",
+              },
+            }
+          : activity,
+      ),
+    });
+    const correctedGroup = correctedFeed.find((entry) => entry.type === "activity-group");
+    expect(correctedGroup).toMatchObject({
+      activities: [
+        { id: "call-a-1", lifecycleStatus: "failed", detail: "Corrected failure output" },
+        { id: "call-b-2", lifecycleStatus: "completed", detail: "second output" },
+      ],
+    });
+    expect(correctedGroup?.activities[0]?.getCopyText()).toContain("Corrected failure output");
+    expect(activityGroup?.activities[0]?.getCopyText()).toContain("first output");
+    const correctedRows = deriveThreadFeedPresentation(
+      correctedFeed,
+      null,
+      new Set([turnId]),
+      new Set([groupId]),
+    );
+    expect(correctedRows.find((entry) => entry.type === "activity-group")).toMatchObject({
+      id: "call-a-1",
+      activities: [{ status: "failure", workEntry: { tone: "error" } }],
+    });
   });
 });
 
diff --git a/apps/mobile/src/lib/threadActivity.ts b/apps/mobile/src/lib/threadActivity.ts
index a034330006c4..ef75fce56af4 100644
--- a/apps/mobile/src/lib/threadActivity.ts
+++ b/apps/mobile/src/lib/threadActivity.ts
@@ -176,6 +176,32 @@ export type ThreadFeedLatestTurn = Pick<
   "turnId" | "state" | "startedAt" | "completedAt"
 >;
 
+type ThreadFeedActivityGroup = Extract<ThreadFeedEntry, { readonly type: "activity-group" }>;
+
+// These keys are immutable inputs. Weak caches release old histories with their source data.
+const activityEntriesCache = new WeakMap<
+  ReadonlyArray<OrchestrationThreadActivity>,
+  ReadonlyArray<Extract<RawThreadFeedEntry, { readonly type: "activity" }>>
+>();
+const messageEntriesCache = new WeakMap<
+  OrchestrationThread["messages"][number],
+  Extract<RawThreadFeedEntry, { readonly type: "message" }>
+>();
+const activityGroupsCache = new WeakMap<ThreadFeedActivity, ThreadFeedActivityGroup>();
+const presentedActivityGroupsCache = new WeakMap<
+  ThreadFeedActivityGroup,
+  {
+    readonly unsettledTurnId: TurnId | null;
+    readonly isWorking: boolean;
+    readonly activeTail: boolean;
+    readonly rows: ReadonlyArray<ThreadFeedEntry>;
+  }
+>();
+const turnFoldRowsCache = new WeakMap<
+  ThreadFeedEntry,
+  Extract<ThreadFeedEntry, { readonly type: "turn-fold" }>
+>();
+
 export function isContextCompactionActivityGroup(
   entry: Extract<ThreadFeedEntry, { readonly type: "activity-group" }>,
 ): boolean {
@@ -1266,11 +1292,31 @@ function isEmptyMessage(entry: RawThreadFeedEntry): boolean {
 
 function groupAdjacentActivities(entries: ReadonlyArray<RawThreadFeedEntry>): ThreadFeedEntry[] {
   const grouped: ThreadFeedEntry[] = [];
-  // Mutable backing array for the trailing group so appending an activity is
-  // O(1) instead of re-copying the group (which made this loop quadratic on
-  // long tool runs). The array is only mutated while it is the trailing group.
-  let openGroupActivities: ThreadFeedActivity[] | null = null;
-  let openGroupTurnId: TurnId | null = null;
+  let firstActivityEntry: Extract<RawThreadFeedEntry, { readonly type: "activity" }> | null = null;
+  let openGroupActivities: ThreadFeedActivity[] = [];
+  const flushGroup = () => {
+    if (firstActivityEntry === null) return;
+    const cached = activityGroupsCache.get(firstActivityEntry.activity);
+    if (
+      cached &&
+      cached.activities.length === openGroupActivities.length &&
+      cached.activities.every((activity, index) => activity === openGroupActivities[index])
+    ) {
+      grouped.push(cached);
+    } else {
+      const group: ThreadFeedActivityGroup = {
+        type: "activity-group",
+        id: firstActivityEntry.id,
+        createdAt: firstActivityEntry.createdAt,
+        turnId: firstActivityEntry.turnId,
+        activities: openGroupActivities,
+      };
+      activityGroupsCache.set(firstActivityEntry.activity, group);
+      grouped.push(group);
+    }
+    firstActivityEntry = null;
+    openGroupActivities = [];
+  };
 
   for (const entry of entries) {
     // Skip empty messages so they don't break activity grouping.
@@ -1279,39 +1325,22 @@ function groupAdjacentActivities(entries: ReadonlyArray<RawThreadFeedEntry>): Th
     }
 
     if (entry.type !== "activity") {
+      flushGroup();
       grouped.push(entry);
-      openGroupActivities = null;
       continue;
     }
 
-    if (entry.activity.workEntry.sourceActivityKind === "context-compaction") {
-      grouped.push({
-        type: "activity-group",
-        id: entry.id,
-        createdAt: entry.createdAt,
-        turnId: entry.turnId,
-        activities: [entry.activity],
-      });
-      openGroupActivities = null;
-      continue;
+    const isCompaction = entry.activity.workEntry.sourceActivityKind === "context-compaction";
+    if (isCompaction || firstActivityEntry?.turnId !== entry.turnId) {
+      flushGroup();
     }
-
-    if (openGroupActivities !== null && openGroupTurnId === entry.turnId) {
-      openGroupActivities.push(entry.activity);
-      continue;
+    firstActivityEntry ??= entry;
+    openGroupActivities.push(entry.activity);
+    if (isCompaction) {
+      flushGroup();
     }
-
-    openGroupActivities = [entry.activity];
-    openGroupTurnId = entry.turnId;
-    grouped.push({
-      type: "activity-group",
-      id: entry.id,
-      createdAt: entry.createdAt,
-      turnId: entry.turnId,
-      activities: openGroupActivities,
-    });
   }
-
+  flushGroup();
   return grouped;
 }
 
@@ -1509,14 +1538,26 @@ export function deriveThreadFeedPresentation(
       entry.turnId === unsettledTurnId;
     const fold = foldsByAnchorId.get(entry.id);
     if (fold) {
-      result.push({
-        type: "turn-fold",
-        id: `turn-fold:${fold.turnId}`,
-        createdAt: fold.createdAt,
-        turnId: fold.turnId,
-        label: fold.label,
-        expanded: expandedTurnIds.has(fold.turnId),
-      });
+      const expanded = expandedTurnIds.has(fold.turnId);
+      let row = turnFoldRowsCache.get(entry);
+      if (
+        !row ||
+        row.turnId !== fold.turnId ||
+        row.createdAt !== fold.createdAt ||
+        row.label !== fold.label ||
+        row.expanded !== expanded
+      ) {
+        row = {
+          type: "turn-fold",
+          id: `turn-fold:${fold.turnId}`,
+          createdAt: fold.createdAt,
+          turnId: fold.turnId,
+          label: fold.label,
+          expanded,
+        };
+        turnFoldRowsCache.set(entry, row);
+      }
+      result.push(row);
     }
     if (!collapsedEntryIds.has(entry.id)) {
       appendPresentedFeedEntry(
@@ -1549,6 +1590,41 @@ function appendPresentedFeedEntry(
     return;
   }
 
+  let cached = presentedActivityGroupsCache.get(entry);
+  if (
+    !cached ||
+    cached.unsettledTurnId !== unsettledTurnId ||
+    cached.isWorking !== isWorking ||
+    cached.activeTail !== activeTail ||
+    cached.rows.some(
+      (row) => row.type === "work-toggle" && expandedWorkGroupIds.has(row.groupId) !== row.expanded,
+    )
+  ) {
+    const rows: ThreadFeedEntry[] = [];
+    appendActivityGroupRows(
+      rows,
+      entry,
+      expandedWorkGroupIds,
+      unsettledTurnId,
+      isWorking,
+      activeTail,
+    );
+    cached = { unsettledTurnId, isWorking, activeTail, rows };
+    presentedActivityGroupsCache.set(entry, cached);
+  }
+  for (const row of cached.rows) {
+    result.push(row);
+  }
+}
+
+function appendActivityGroupRows(
+  result: ThreadFeedEntry[],
+  entry: ThreadFeedActivityGroup,
+  expandedWorkGroupIds: ReadonlySet<string>,
+  unsettledTurnId: TurnId | null,
+  isWorking: boolean,
+  activeTail: boolean,
+): void {
   const activities = omitSupersededLifecycleMarkers(
     entry.activities.filter(
       (activity) =>
@@ -1754,10 +1830,16 @@ export function derivePendingApprovals(
       ? payload.options.filter(isProviderApprovalOption)
       : undefined;
 
-    if (activity.kind === "approval.requested" && requestId && requestKind) {
+    if (
+      activity.kind === "approval.requested" &&
+      requestId &&
+      payload?.requestType !== "tool_user_input" &&
+      payload?.requestType !== "auth_tokens_refresh"
+    ) {
       openByRequestId.set(requestId, {
         requestId,
-        requestKind,
+        // Older OpenCode requests can have no recognized approval kind.
+        requestKind: requestKind ?? "command",
         createdAt: activity.createdAt,
         ...(detail ? { detail } : {}),
         ...(appName ? { appName } : {}),
@@ -1914,7 +1996,7 @@ export function buildPendingUserInputAnswers(
 }
 
 export function buildThreadFeed(
-  thread: OrchestrationThread,
+  thread: Pick<OrchestrationThread, "messages" | "activities">,
   options?: {
     readonly loadedMessages?: ReadonlyArray<OrchestrationThread["messages"][number]>;
     readonly localMessages?: ReadonlyArray<OrchestrationThread["messages"][number]>;
@@ -1926,70 +2008,21 @@ export function buildThreadFeed(
     : loadedMessages;
   const oldestLoadedMessageCreatedAt =
     options?.loadedMessages !== undefined ? (loadedMessages[0]?.createdAt ?? null) : null;
-  const workLogEntries = deriveWorkLogEntries(thread.activities);
+  const activityEntries = getThreadFeedActivityEntries(thread.activities);
   const entries = Arr.sortWith(
     [
-      ...messages.map<RawThreadFeedEntry>((message) => ({
-        type: "message",
-        id: message.id,
-        createdAt: message.createdAt,
-        message,
-      })),
-      ...workLogEntries
-        .filter((entry) => {
-          if (options?.loadedMessages === undefined) {
-            return true;
-          }
-          return (
-            oldestLoadedMessageCreatedAt === null || entry.createdAt >= oldestLoadedMessageCreatedAt
-          );
-        })
-        .map<RawThreadFeedEntry>((entry) => {
-          const summary = workEntryHeading(entry);
-          const detail = workEntryPreview(entry);
-          const getFullDetail = memoizeValue(() => buildWorkEntryExpandedBody(entry));
-          const getCopyText = memoizeValue(() => {
-            const copyLabel = capitalizePhrase(
-              normalizeCompactToolLabel(entry.toolTitle || entry.label),
-            );
-            const fullDetail = getFullDetail();
-            if (entry.command) {
-              const normalizedCommand =
-                entry.rawCommand && copyLabel.trim() !== entry.command.trim()
-                  ? entry.command
-                  : null;
-              return [copyLabel, normalizedCommand, fullDetail ?? entry.command]
-                .filter((value): value is string => Boolean(value))
-                .join("\n");
-            }
-            return [copyLabel, detail, fullDetail]
-              .filter((value, index, values): value is string => {
-                return Boolean(value) && values.indexOf(value) === index;
-              })
-              .join("\n");
-          });
-          return {
-            type: "activity",
-            id: entry.id,
-            createdAt: entry.createdAt,
-            turnId: entry.turnId,
-            activity: {
-              id: entry.id,
-              createdAt: entry.createdAt,
-              turnId: entry.turnId,
-              summary,
-              detail,
-              canExpand: workEntryHasExpandedBody(entry),
-              getFullDetail,
-              getCopyText,
-              icon: workEntryIcon(entry),
-              toolLike: workLogEntryIsToolLike(entry),
-              status: workEntryStatus(entry),
-              ...(entry.toolLifecycleStatus ? { lifecycleStatus: entry.toolLifecycleStatus } : {}),
-              workEntry: entry,
-            },
-          };
-        }),
+      ...messages.map((message) => {
+        let entry = messageEntriesCache.get(message);
+        if (!entry) {
+          entry = { type: "message", id: message.id, createdAt: message.createdAt, message };
+          messageEntriesCache.set(message, entry);
+        }
+        return entry;
+      }),
+      ...activityEntries.filter(
+        (entry) =>
+          oldestLoadedMessageCreatedAt === null || entry.createdAt >= oldestLoadedMessageCreatedAt,
+      ),
     ],
     (s) => new Date(s.createdAt),
     Order.Date,
@@ -1997,3 +2030,56 @@ export function buildThreadFeed(
 
   return groupAdjacentActivities(entries);
 }
+
+function getThreadFeedActivityEntries(activities: ReadonlyArray<OrchestrationThreadActivity>) {
+  const cached = activityEntriesCache.get(activities);
+  if (cached) return cached;
+  const entries = deriveWorkLogEntries(activities).map(toThreadFeedActivityEntry);
+  activityEntriesCache.set(activities, entries);
+  return entries;
+}
+
+function toThreadFeedActivityEntry(
+  entry: DerivedWorkLogEntry,
+): Extract<RawThreadFeedEntry, { readonly type: "activity" }> {
+  const summary = workEntryHeading(entry);
+  const detail = workEntryPreview(entry);
+  const getFullDetail = memoizeValue(() => buildWorkEntryExpandedBody(entry));
+  const getCopyText = memoizeValue(() => {
+    const copyLabel = capitalizePhrase(normalizeCompactToolLabel(entry.toolTitle || entry.label));
+    const fullDetail = getFullDetail();
+    if (entry.command) {
+      const normalizedCommand =
+        entry.rawCommand && copyLabel.trim() !== entry.command.trim() ? entry.command : null;
+      return [copyLabel, normalizedCommand, fullDetail ?? entry.command]
+        .filter((value): value is string => Boolean(value))
+        .join("\n");
+    }
+    return [copyLabel, detail, fullDetail]
+      .filter((value, index, values): value is string => {
+        return Boolean(value) && values.indexOf(value) === index;
+      })
+      .join("\n");
+  });
+  return {
+    type: "activity",
+    id: entry.id,
+    createdAt: entry.createdAt,
+    turnId: entry.turnId,
+    activity: {
+      id: entry.id,
+      createdAt: entry.createdAt,
+      turnId: entry.turnId,
+      summary,
+      detail,
+      canExpand: workEntryHasExpandedBody(entry),
+      getFullDetail,
+      getCopyText,
+      icon: workEntryIcon(entry),
+      toolLike: workLogEntryIsToolLike(entry),
+      status: workEntryStatus(entry),
+      ...(entry.toolLifecycleStatus ? { lifecycleStatus: entry.toolLifecycleStatus } : {}),
+      workEntry: entry,
+    },
+  };
+}
diff --git a/apps/mobile/src/state/composer-attachment-uploads.ts b/apps/mobile/src/state/composer-attachment-uploads.ts
index efc3fe1c39e5..ad38551d5915 100644
--- a/apps/mobile/src/state/composer-attachment-uploads.ts
+++ b/apps/mobile/src/state/composer-attachment-uploads.ts
@@ -4,6 +4,7 @@ import { Atom } from "effect/unstable/reactivity";
 import { useEffect, useRef } from "react";
 
 import { prepareTurnAttachments } from "../lib/attachmentUpload";
+import { isFileBackedComposerAttachment } from "../lib/composerImages";
 import {
   composerAttachmentUploadKey,
   composerDraftEnvironmentId,
@@ -60,10 +61,9 @@ export function useComposerAttachmentUploadWorker() {
     const queue = createComposerAttachmentUploadQueue({
       onChange: (states) => appAtomRegistry.set(composerAttachmentUploadsAtom, states),
       upload: async ({ environmentId, attachment }, signal, onProgress) => {
-        const release =
-          attachment.type === "file"
-            ? retainComposerAttachmentFileForPreview(attachment)
-            : undefined;
+        const release = isFileBackedComposerAttachment(attachment)
+          ? retainComposerAttachmentFileForPreview(attachment)
+          : undefined;
         try {
           const result = await prepareTurnAttachments({
             environmentId,
diff --git a/apps/mobile/src/state/pending-task-editor-writes.test.ts b/apps/mobile/src/state/pending-task-editor-writes.test.ts
index 9305d821fd44..9140f8dbf8a2 100644
--- a/apps/mobile/src/state/pending-task-editor-writes.test.ts
+++ b/apps/mobile/src/state/pending-task-editor-writes.test.ts
@@ -19,7 +19,7 @@ vi.mock("./thread-outbox", async () => {
   harness.manager = createThreadOutboxManager({
     registry: appAtomRegistry,
     storage: {
-      load: async () => [],
+      load: async () => ({ messages: [], errors: [] }),
       write: async (message) => {
         const pending = harness.writeGates.shift();
         if (pending) {
diff --git a/apps/mobile/src/state/thread-outbox-manager.ts b/apps/mobile/src/state/thread-outbox-manager.ts
index 1bd2fbd8e4d0..420195a26b1c 100644
--- a/apps/mobile/src/state/thread-outbox-manager.ts
+++ b/apps/mobile/src/state/thread-outbox-manager.ts
@@ -72,16 +72,26 @@ export function createThreadOutboxManager(options: ThreadOutboxManagerOptions) {
     options.registry.set(queuedMessagesByThreadKeyAtom, groupQueuedThreadMessages(messages));
   };
 
-  // Resolves true when hydration completed; false when the read failed (the
-  // next call retries). Destructive callers (the attachment sweep) must not
-  // treat a failed hydration as an empty queue.
+  // Readable messages can be used after a partial load. Only a complete load
+  // returns true, so cleanup cannot delete files owned by unreadable records.
+  // A later call retries failed reads without replacing live message objects.
   const load = (): Promise<boolean> => {
     if (loadPromise !== null) {
       return loadPromise;
     }
     loadPromise = serialize(async () => {
-      const persistedMessages = await options.storage.load();
-      setMessages([...persistedMessages, ...currentMessages()]);
+      const result = await options.storage.load();
+      const current = currentMessages();
+      const currentIds = new Set(current.map((message) => message.messageId));
+      const recovered = result.messages.filter(
+        (message) => !currentIds.has(message.messageId) && !revisions.has(message.messageId),
+      );
+      // Accepted edits and removals win over a later disk read. Retaining
+      // current objects also keeps retries from restarting the drain.
+      if (recovered.length > 0) setMessages([...recovered, ...current]);
+      if (result.errors.length > 0) {
+        throw new AggregateError(result.errors, "Some queued messages could not be read.");
+      }
       return true;
     }).catch((cause) => {
       loadPromise = null;
@@ -275,19 +285,23 @@ export function createThreadOutboxManager(options: ThreadOutboxManagerOptions) {
     // changes after this request must not enter the clear set.
     const revisionsAtRequest = new Map(revisions);
     return serialize(async () => {
-      const persisted = await options.storage.load().catch((cause) => {
-        warn(
-          "[thread-outbox] failed to load messages while clearing environment",
-          new ThreadOutboxManagerError({
+      const persisted = await options.storage
+        .load()
+        .then((result) => {
+          if (result.errors.length > 0) {
+            throw new AggregateError(result.errors, "Some queued messages could not be read.");
+          }
+          return result.messages;
+        })
+        .catch((cause) => {
+          throw new ThreadOutboxManagerError({
             operation: "clear-environment-load",
             environmentId,
             threadId: null,
             messageId: null,
             cause,
-          }),
-        );
-        return [];
-      });
+          });
+        });
       const allMessages = flattenQueuedThreadMessages(
         groupQueuedThreadMessages([...persisted, ...currentMessages()]),
       );
diff --git a/apps/mobile/src/state/thread-outbox-model.ts b/apps/mobile/src/state/thread-outbox-model.ts
index 9895d51952ad..99f32e5c1764 100644
--- a/apps/mobile/src/state/thread-outbox-model.ts
+++ b/apps/mobile/src/state/thread-outbox-model.ts
@@ -27,6 +27,7 @@ import type { DraftComposerAttachment } from "../lib/composerImages";
 import { scopedThreadKey } from "../lib/scopedEntities";
 import { resolveProviderInteractionMode } from "../features/threads/legacy-plan-mode";
 
+// Keep current writes until a compatible native baseline includes the v4 reader.
 const THREAD_OUTBOX_SCHEMA_VERSION = 3;
 const THREAD_OUTBOX_MAX_RETRY_DELAY_MS = 16_000;
 
@@ -43,7 +44,7 @@ const QueuedThreadCreationSchema = Schema.Struct({
 });
 
 export const QueuedThreadMessageSchema = Schema.Struct({
-  schemaVersion: Schema.Literals([1, 2, THREAD_OUTBOX_SCHEMA_VERSION]),
+  schemaVersion: Schema.Literals([1, 2, THREAD_OUTBOX_SCHEMA_VERSION, 4]),
   environmentId: EnvironmentId,
   threadId: ThreadId,
   messageId: MessageId,
diff --git a/apps/mobile/src/state/thread-outbox-removal.test.ts b/apps/mobile/src/state/thread-outbox-removal.test.ts
index e444274ae2c6..97a7331ff7e0 100644
--- a/apps/mobile/src/state/thread-outbox-removal.test.ts
+++ b/apps/mobile/src/state/thread-outbox-removal.test.ts
@@ -19,7 +19,7 @@ vi.mock("./thread-outbox", async () => {
   harness.manager = createThreadOutboxManager({
     registry: appAtomRegistry,
     storage: {
-      load: async () => [],
+      load: async () => ({ messages: [], errors: [] }),
       write: async () => undefined,
       remove: async () => undefined,
     },
diff --git a/apps/mobile/src/state/thread-outbox-storage.ts b/apps/mobile/src/state/thread-outbox-storage.ts
index ab0853f7dee5..b03b72c78972 100644
--- a/apps/mobile/src/state/thread-outbox-storage.ts
+++ b/apps/mobile/src/state/thread-outbox-storage.ts
@@ -44,8 +44,13 @@ export class ThreadOutboxStorageError extends Schema.TaggedErrorClass<ThreadOutb
   }
 }
 
+export interface ThreadOutboxLoadResult {
+  readonly messages: ReadonlyArray<QueuedThreadMessage>;
+  readonly errors: ReadonlyArray<ThreadOutboxStorageError>;
+}
+
 export interface ThreadOutboxStorage {
-  readonly load: () => Promise<ReadonlyArray<QueuedThreadMessage>>;
+  readonly load: () => Promise<ThreadOutboxLoadResult>;
   readonly write: (message: QueuedThreadMessage) => Promise<void>;
   readonly remove: (message: QueuedThreadMessage) => Promise<void>;
 }
@@ -69,6 +74,7 @@ async function getMessageFile(messageId: MessageId) {
 export const expoThreadOutboxStorage: ThreadOutboxStorage = {
   load: async () => {
     const messages: QueuedThreadMessage[] = [];
+    const errors: ThreadOutboxStorageError[] = [];
     try {
       const { File } = await import("expo-file-system");
       const directory = await getOutboxDirectory();
@@ -80,8 +86,9 @@ export const expoThreadOutboxStorage: ThreadOutboxStorage = {
         try {
           messages.push(decodeQueuedThreadMessage(JSON.parse(await entry.text()) as unknown));
         } catch (cause) {
-          console.warn(
-            "[thread-outbox] ignored invalid persisted message",
+          // Recover readable messages without treating their attachment
+          // owners as the complete inventory needed for cleanup.
+          errors.push(
             new ThreadOutboxStorageError({
               operation: "read-message",
               environmentId: null,
@@ -103,7 +110,7 @@ export const expoThreadOutboxStorage: ThreadOutboxStorage = {
         cause,
       });
     }
-    return messages;
+    return { messages, errors };
   },
   write: async (message) => {
     const fileName = messageFileName(message.messageId);
diff --git a/apps/mobile/src/state/thread-outbox.test.ts b/apps/mobile/src/state/thread-outbox.test.ts
index 17e47aceaf45..c426d552a7e7 100644
--- a/apps/mobile/src/state/thread-outbox.test.ts
+++ b/apps/mobile/src/state/thread-outbox.test.ts
@@ -8,6 +8,64 @@ import {
   ThreadId,
 } from "@t3tools/contracts";
 import { AtomRegistry } from "effect/unstable/reactivity";
+import { onTestFinished, vi } from "vite-plus/test";
+
+const outboxFiles = vi.hoisted(() => new Map<string, string | Error>());
+
+vi.mock("expo-file-system", () => {
+  class Directory {
+    create() {}
+
+    list() {
+      return Array.from(outboxFiles.keys(), (name) => new File(name));
+    }
+  }
+
+  class File {
+    readonly name: string;
+    readonly parentDirectory = new Directory();
+
+    constructor(...parts: [string] | [Directory, string]) {
+      this.name = parts.length === 1 ? parts[0] : parts[1];
+    }
+
+    get exists() {
+      return outboxFiles.has(this.name);
+    }
+
+    create() {
+      outboxFiles.set(this.name, "");
+    }
+
+    write(contents: string) {
+      outboxFiles.set(this.name, contents);
+    }
+
+    moveSync(file: File) {
+      const contents = outboxFiles.get(this.name);
+      if (contents === undefined) throw new Error("Missing file");
+      outboxFiles.set(file.name, contents);
+      outboxFiles.delete(this.name);
+    }
+
+    delete() {
+      outboxFiles.delete(this.name);
+    }
+
+    async text(): Promise<string> {
+      const contents = outboxFiles.get(this.name);
+      if (contents instanceof Error) throw contents;
+      if (contents === undefined) throw new Error("Missing file");
+      return contents;
+    }
+  }
+
+  return {
+    File,
+    Directory,
+    Paths: { document: "/documents" },
+  };
+});
 
 import {
   decodeQueuedThreadMessage,
@@ -24,7 +82,12 @@ import {
   type QueuedThreadMessage,
 } from "./thread-outbox-model";
 import { createThreadOutboxManager, ThreadOutboxManagerError } from "./thread-outbox-manager";
-import type { ThreadOutboxStorage } from "./thread-outbox-storage";
+import {
+  expoThreadOutboxStorage,
+  ThreadOutboxStorageError,
+  type ThreadOutboxLoadResult,
+  type ThreadOutboxStorage,
+} from "./thread-outbox-storage";
 
 function queuedMessage(input: {
   readonly environmentId?: string;
@@ -44,6 +107,164 @@ function queuedMessage(input: {
 }
 
 describe("thread outbox", () => {
+  it.each(["read", "json", "schema"] as const)(
+    "recovers usable messages without permitting cleanup after a record %s failure",
+    async (failure) => {
+      onTestFinished(() => outboxFiles.clear());
+      const first = queuedMessage({
+        messageId: "message-1",
+        createdAt: "2026-06-08T10:00:01.000Z",
+      });
+      const second = queuedMessage({
+        environmentId: "environment-2",
+        messageId: "message-2",
+        createdAt: "2026-06-08T10:00:02.000Z",
+      });
+      // Put the unreadable record first to check that later records still load.
+      outboxFiles.set(
+        "message-2.json",
+        failure === "read"
+          ? new Error("storage unavailable")
+          : failure === "json"
+            ? "{"
+            : JSON.stringify({ ...second, schemaVersion: 999 }),
+      );
+      outboxFiles.set("message-1.json", JSON.stringify(encodeQueuedThreadMessage(first)));
+      const unreadable = outboxFiles.get("message-2.json");
+
+      await expect(expoThreadOutboxStorage.load()).resolves.toMatchObject({
+        messages: [first],
+        errors: [{ operation: "read-message", fileName: "message-2.json" }],
+      });
+
+      const registry = AtomRegistry.make();
+      onTestFinished(() => registry.dispose());
+      const manager = createThreadOutboxManager({
+        registry,
+        storage: expoThreadOutboxStorage,
+        warn: () => {},
+      });
+      await expect(manager.load()).resolves.toBe(false);
+      const recovered = registry.get(manager.queuedMessagesByThreadKeyAtom)[
+        "environment-1:thread-1"
+      ]![0]!;
+      expect(recovered).toEqual(first);
+      await expect(manager.confirmQueued(recovered)).resolves.toBe(true);
+      const edited = { ...recovered, text: "Edited after recovery" };
+      await expect(manager.update(edited)).resolves.toBe(true);
+      const beforeRetry = registry.get(manager.queuedMessagesByThreadKeyAtom);
+      await expect(manager.load()).resolves.toBe(false);
+      expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toBe(beforeRetry);
+      await expect(manager.clearEnvironment(first.environmentId)).rejects.toMatchObject({
+        operation: "clear-environment-load",
+      });
+      expect(outboxFiles.get("message-2.json")).toBe(unreadable);
+      expect(outboxFiles.has("message-1.json")).toBe(true);
+
+      // A delivered readable message can leave the queue while the failed
+      // record stays intact. Its attachment cleanup has a separate guard.
+      await expect(manager.remove(edited)).resolves.toBe(edited);
+      expect(outboxFiles.has("message-1.json")).toBe(false);
+
+      outboxFiles.set("message-2.json", JSON.stringify(encodeQueuedThreadMessage(second)));
+      await expect(manager.load()).resolves.toBe(true);
+      expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({
+        "environment-2:thread-1": [second],
+      });
+      await expect(expoThreadOutboxStorage.load()).resolves.toEqual({
+        messages: [second],
+        errors: [],
+      });
+    },
+  );
+
+  it("preserves queued messages when environment cleanup cannot read the outbox", async () => {
+    const registry = AtomRegistry.make();
+    onTestFinished(() => registry.dispose());
+    const message = queuedMessage({
+      messageId: "message-1",
+      createdAt: "2026-06-08T10:00:01.000Z",
+    });
+    const stored = new Map<MessageId, QueuedThreadMessage>();
+    const manager = createThreadOutboxManager({
+      registry,
+      warn: () => {},
+      storage: {
+        load: async () => {
+          throw new Error("storage unavailable");
+        },
+        write: async (entry) => {
+          stored.set(entry.messageId, entry);
+        },
+        remove: async (entry) => {
+          stored.delete(entry.messageId);
+        },
+      },
+    });
+    await manager.enqueue(message);
+
+    await expect(manager.clearEnvironment(message.environmentId)).rejects.toMatchObject({
+      operation: "clear-environment-load",
+    });
+    expect([...stored.values()]).toEqual([message]);
+    expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({
+      "environment-1:thread-1": [message],
+    });
+  });
+
+  it("keeps in-session edits and removals when an incomplete load is retried", async () => {
+    const registry = AtomRegistry.make();
+    onTestFinished(() => registry.dispose());
+    const message = queuedMessage({
+      messageId: "message-retried",
+      createdAt: "2026-06-08T10:00:01.000Z",
+    });
+    const started = Promise.withResolvers<void>();
+    const response = Promise.withResolvers<ThreadOutboxLoadResult>();
+    const load = vi.fn<ThreadOutboxStorage["load"]>(async () => ({
+      messages: [message],
+      errors: [],
+    }));
+    load.mockImplementationOnce(() => {
+      started.resolve();
+      return response.promise;
+    });
+    const manager = createThreadOutboxManager({
+      registry,
+      storage: { load, write: async () => {}, remove: async () => {} },
+      warn: () => {},
+    });
+    const loading = manager.load();
+    await started.promise;
+    const edited = { ...message, text: "Accepted while storage was being read" };
+    const writing = manager.enqueue(edited);
+    response.resolve({
+      messages: [message],
+      errors: [
+        new ThreadOutboxStorageError({
+          operation: "read-message",
+          environmentId: null,
+          threadId: null,
+          messageId: null,
+          fileName: "unreadable.json",
+          cause: new Error("unreadable record"),
+        }),
+      ],
+    });
+    await expect(loading).resolves.toBe(false);
+    await writing;
+    expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({
+      "environment-1:thread-1": [edited],
+    });
+    await expect(manager.confirmQueued(edited)).resolves.toBe(true);
+
+    await manager.remove(edited);
+    // A later repaired record can contain a stale copy of a removed message.
+    await expect(manager.load()).resolves.toBe(true);
+    expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({});
+    expect(load).toHaveBeenCalledTimes(2);
+  });
+
   it("groups messages by scoped thread and preserves creation order", () => {
     const later = queuedMessage({
       messageId: "message-2",
@@ -102,6 +323,30 @@ describe("thread outbox", () => {
     expect(decodeQueuedThreadMessage(encodeQueuedThreadMessage(message))).toEqual(message);
   });
 
+  it("reads file-backed images from v4 queued messages", () => {
+    const message = {
+      ...queuedMessage({
+        messageId: "message-image",
+        createdAt: "2026-06-08T10:00:01.000Z",
+      }),
+      attachments: [
+        {
+          id: "image-1",
+          type: "image" as const,
+          name: "photo.png",
+          mimeType: "image/png",
+          sizeBytes: 3,
+          fileUri: "file:///documents/t3-composer-attachments/photo.png",
+          previewUri: "file:///documents/t3-composer-attachments/photo.png",
+          uploadedAttachmentId: "pending-photo-png",
+          uploadEnvironmentId: EnvironmentId.make("environment-1"),
+        },
+      ],
+    } satisfies QueuedThreadMessage;
+
+    expect(decodeQueuedThreadMessage({ ...message, schemaVersion: 4 })).toEqual(message);
+  });
+
   it("persists the exact selector snapshot while remaining compatible with v1 messages", () => {
     const legacyMessage = queuedMessage({
       messageId: "message-1",
@@ -217,7 +462,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => undefined,
         remove: async () => undefined,
       },
@@ -264,7 +509,7 @@ describe("thread outbox", () => {
         if (loadCalls === 1) {
           await initialLoadBlocked;
         }
-        return [...stored.values()];
+        return { messages: [...stored.values()], errors: [] };
       },
       write: async () => undefined,
       remove: async (candidate) => {
@@ -300,7 +545,7 @@ describe("thread outbox", () => {
         load: async () => {
           loadCalls += 1;
           if (loadCalls === 1) throw loadCause;
-          return [];
+          return { messages: [], errors: [] };
         },
         write: async () => undefined,
         remove: async () => undefined,
@@ -333,7 +578,7 @@ describe("thread outbox", () => {
     const removalCause = new Error("remove failed");
     let failRemoval = true;
     const storage: ThreadOutboxStorage = {
-      load: async () => [...stored.values()],
+      load: async () => ({ messages: [...stored.values()], errors: [] }),
       write: async (message) => {
         stored.set(message.messageId, message);
       },
@@ -383,7 +628,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => writeBlocked,
         remove: async () => undefined,
       },
@@ -412,7 +657,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => {
           throw writeCause;
         },
@@ -443,7 +688,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => {
           throw new Error("disk full");
         },
@@ -475,7 +720,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => {
           if (failNextWrite) {
             failNextWrite = false;
@@ -512,7 +757,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => undefined,
         remove: async () => undefined,
       },
@@ -536,7 +781,7 @@ describe("thread outbox", () => {
     const registry = AtomRegistry.make();
     const stored = new Map<MessageId, QueuedThreadMessage>();
     const storage: ThreadOutboxStorage = {
-      load: async () => [...stored.values()],
+      load: async () => ({ messages: [...stored.values()], errors: [] }),
       write: async (message) => {
         stored.set(message.messageId, message);
       },
@@ -571,7 +816,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async (message) => {
           writes.push(message.text);
         },
@@ -615,7 +860,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async (message) => {
           writes.push(message.text);
           if (message.text === "stale upload") {
@@ -659,7 +904,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [...stored.values()],
+        load: async () => ({ messages: [...stored.values()], errors: [] }),
         write: async (message) => {
           stored.set(message.messageId, message);
         },
@@ -708,7 +953,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [...stored.values()],
+        load: async () => ({ messages: [...stored.values()], errors: [] }),
         write: async (message) => {
           if (message === retried) {
             replacementWriteStarted.resolve();
@@ -758,7 +1003,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [...stored.values()],
+        load: async () => ({ messages: [...stored.values()], errors: [] }),
         write: async (message) => {
           stored.set(message.messageId, message);
         },
@@ -797,7 +1042,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [...stored.values()],
+        load: async () => ({ messages: [...stored.values()], errors: [] }),
         write: async (message) => {
           stored.set(message.messageId, message);
         },
@@ -861,7 +1106,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [...stored.values()],
+        load: async () => ({ messages: [...stored.values()], errors: [] }),
         write: async (message) => {
           stored.set(message.messageId, message);
         },
@@ -904,7 +1149,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [...stored.values()],
+        load: async () => ({ messages: [...stored.values()], errors: [] }),
         write: async (message) => {
           stored.set(message.messageId, message);
         },
diff --git a/apps/mobile/src/state/thread-outbox.ts b/apps/mobile/src/state/thread-outbox.ts
index 2f9d8c85416c..8b4b2b4326bb 100644
--- a/apps/mobile/src/state/thread-outbox.ts
+++ b/apps/mobile/src/state/thread-outbox.ts
@@ -21,10 +21,6 @@ export async function flushThreadOutbox(): Promise<void> {
   await flushThreadOutboxWrites();
 }
 
-export function ensureThreadOutboxLoaded(): void {
-  void threadOutboxManager.load();
-}
-
 export function enqueueThreadOutboxMessage(message: QueuedThreadMessage): Promise<void> {
   return threadOutboxManager.enqueue(message);
 }
diff --git a/apps/mobile/src/state/use-composer-drafts.test.ts b/apps/mobile/src/state/use-composer-drafts.test.ts
index c5c6ca69f3c0..a5e85227e271 100644
--- a/apps/mobile/src/state/use-composer-drafts.test.ts
+++ b/apps/mobile/src/state/use-composer-drafts.test.ts
@@ -9,15 +9,18 @@ import {
 import { onTestFinished, vi } from "vite-plus/test";
 
 const composerDraftFileMocks = vi.hoisted(() => {
-  let document = "";
+  let document = JSON.stringify({ schemaVersion: 1, drafts: {} });
+  let readError: Error | null = null;
   let writeError: Error | null = null;
   let releaseRead: (() => void) | null = null;
   let readBarrier = Promise.resolve();
   let nextWriteBarrier: Promise<void> | null = null;
   let onWrite: (() => void) | null = null;
   const writes: string[] = [];
+  const readImage = vi.fn(async () => "YWJj");
 
   return {
+    readImage,
     blockRead() {
       readBarrier = new Promise<void>((resolve) => {
         releaseRead = resolve;
@@ -33,6 +36,9 @@ const composerDraftFileMocks = vi.hoisted(() => {
     setDocument(value: unknown) {
       document = JSON.stringify(value);
     },
+    setReadError(error: Error | null) {
+      readError = error;
+    },
     setWriteError(error: Error | null) {
       writeError = error;
     },
@@ -50,6 +56,10 @@ const composerDraftFileMocks = vi.hoisted(() => {
     },
     Directory: class {
       create() {}
+
+      list() {
+        return [];
+      }
     },
     File: class {
       exists = true;
@@ -61,9 +71,14 @@ const composerDraftFileMocks = vi.hoisted(() => {
 
       async text() {
         await readBarrier;
+        if (readError) throw readError;
         return document;
       }
 
+      async base64() {
+        return readImage();
+      }
+
       write(value: string) {
         if (writeError) {
           throw writeError;
@@ -99,13 +114,29 @@ const incomingShareStorageMocks = vi.hoisted(() => ({
 vi.mock("expo-file-system", () => ({
   Directory: composerDraftFileMocks.Directory,
   File: composerDraftFileMocks.File,
-  Paths: { document: "/documents" },
+  Paths: { document: { uri: "file:///documents" } },
 }));
 
-vi.mock("../lib/composerImages", () => ({
+vi.mock("../lib/composerImages", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/composerImages")>()),
   removePersistedComposerAttachmentFile: composerAttachmentCleanupMocks.remove,
 }));
 
+vi.mock("../lib/uuid", () => ({ uuidv4: () => "uuid", randomHex: () => "0000" }));
+vi.mock("./assets", () => ({ assetEnvironment: {} }));
+vi.mock("./attachments", () => ({ attachmentEnvironment: {} }));
+vi.mock("./session", () => ({ environmentSession: {} }));
+vi.mock("@t3tools/client-runtime/state/runtime", () => ({
+  createEnvironmentRpcCommand: () => Symbol("rpc-command"),
+  executeAtomQuery: () => {
+    throw new Error("Unexpected network query in the inline read test");
+  },
+  runAtomCommand: () => {
+    throw new Error("Unexpected network command in the inline read test");
+  },
+  squashAtomCommandFailure: (result: { readonly error: unknown }) => result.error,
+}));
+
 vi.mock("../lib/attachmentUpload", () => ({
   releasePendingAttachmentUploads: composerAttachmentCleanupMocks.releaseUploads,
 }));
@@ -119,6 +150,7 @@ import { threadOutboxManager } from "./thread-outbox";
 import {
   appendComposerDraftAttachments,
   archiveCloudComposerDrafts,
+  clearComposerDraftContent,
   clearComposerDraftContentState,
   clearComposerDraftsEnvironment,
   ComposerDraftPersistenceError,
@@ -127,7 +159,6 @@ import {
   copyComposerDraftContentIfEmpty,
   copyComposerDraftContentState,
   decodePersistedComposerState,
-  decodePersistedComposerDrafts,
   ensureComposerDraftsLoaded,
   type ComposerDraft,
   flushComposerDrafts,
@@ -156,11 +187,14 @@ const DRAFT: ComposerDraft = {
 afterEach(() => {
   vi.useRealTimers();
   resetComposerDraftsLoadState();
-  composerDraftFileMocks.setDocument("");
+  composerDraftFileMocks.setDocument({ schemaVersion: 1, drafts: {} });
+  composerDraftFileMocks.setReadError(null);
   composerDraftFileMocks.setWriteError(null);
   composerDraftFileMocks.setNextWriteBarrier(null);
   composerDraftFileMocks.setOnWrite(null);
   composerDraftFileMocks.resetWrites();
+  composerDraftFileMocks.readImage.mockReset();
+  composerDraftFileMocks.readImage.mockResolvedValue("YWJj");
   appAtomRegistry.set(composerDraftsAtom, {});
   appAtomRegistry.set(composerCloudDraftsAtom, { accountId: null, signedOut: {} });
   appAtomRegistry.set(stickyComposerModelSelectionAtom, null);
@@ -217,12 +251,12 @@ describe("mobile composer drafts", () => {
     };
 
     expect(
-      decodePersistedComposerDrafts({
+      decodePersistedComposerState({
         schemaVersion: 1,
         drafts: {
           "environment-1:thread-1": { text: "Review this file", attachments: [file] },
         },
-      }),
+      }).drafts,
     ).toEqual({
       "environment-1:thread-1": { text: "Review this file", attachments: [file] },
     });
@@ -303,6 +337,106 @@ describe("mobile composer drafts", () => {
     expect(composerAttachmentCleanupMocks.remove).toHaveBeenCalledWith(file.fileUri);
   });
 
+  it("retains a referenced file-backed image and releases it once unreferenced", async () => {
+    const outboxLoad = vi.spyOn(threadOutboxManager, "load").mockResolvedValue(true);
+    onTestFinished(() => outboxLoad.mockRestore());
+    const image = {
+      id: "image-1",
+      type: "image" as const,
+      name: "photo.png",
+      mimeType: "image/png",
+      sizeBytes: 3,
+      fileUri: "file:///documents/t3-composer-attachments/photo.png",
+      previewUri: "file:///documents/t3-composer-attachments/photo.png",
+    };
+    appAtomRegistry.set(composerDraftsAtom, {
+      "environment-1:thread-1": { text: "look at this", attachments: [image] },
+    });
+
+    await releaseUnusedComposerAttachmentFiles([image]);
+    expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
+
+    // A queued outbox message must keep the bytes alive after the draft clears.
+    appAtomRegistry.set(composerDraftsAtom, {});
+    appAtomRegistry.set(threadOutboxManager.queuedMessagesByThreadKeyAtom, {
+      "environment-1:thread-1": [
+        {
+          environmentId: EnvironmentId.make("environment-1"),
+          threadId: ThreadId.make("thread-1"),
+          messageId: MessageId.make("queued-image"),
+          commandId: CommandId.make("command-image"),
+          text: "look at this",
+          attachments: [image],
+          createdAt: "2026-08-31T12:00:00.000Z",
+        },
+      ],
+    });
+    await releaseUnusedComposerAttachmentFiles([image]);
+    expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
+
+    appAtomRegistry.set(threadOutboxManager.queuedMessagesByThreadKeyAtom, {});
+    await releaseUnusedComposerAttachmentFiles([image]);
+    expect(composerAttachmentCleanupMocks.remove).toHaveBeenCalledExactlyOnceWith(image.fileUri);
+  });
+
+  it("keeps an image through an inline read after its draft is removed", async () => {
+    const { prepareTurnAttachments } =
+      await vi.importActual<typeof import("../lib/attachmentUpload")>("../lib/attachmentUpload");
+    const image = {
+      id: "image-reading",
+      type: "image" as const,
+      name: "photo.png",
+      mimeType: "image/png",
+      sizeBytes: 3,
+      fileUri: "file:///documents/t3-composer-attachments/photo.png",
+      previewUri: "file:///documents/t3-composer-attachments/photo.png",
+    };
+    const readStarted = Promise.withResolvers<void>();
+    const read = Promise.withResolvers<void>();
+    const removed = Promise.withResolvers<void>();
+    let imageExists = true;
+    composerDraftFileMocks.readImage.mockImplementation(async () => {
+      readStarted.resolve();
+      await read.promise;
+      if (!imageExists) throw new Error("The image was deleted during its read");
+      return "YWJj";
+    });
+    composerAttachmentCleanupMocks.remove.mockImplementationOnce(async () => {
+      imageExists = false;
+      removed.resolve();
+    });
+    appendComposerDraftAttachments("environment-1:thread-1", [image]);
+    await flushComposerDrafts();
+    const preparing = prepareTurnAttachments({
+      environmentId: EnvironmentId.make("environment-1"),
+      attachments: [image],
+    });
+    onTestFinished(async () => {
+      read.resolve();
+      await preparing.catch(() => undefined);
+    });
+    await readStarted.promise;
+    clearComposerDraftContent("environment-1:thread-1", { deferAttachmentCleanup: true });
+    await releaseUnusedComposerAttachmentFiles([image]);
+    expect(imageExists).toBe(true);
+
+    read.resolve();
+    const prepared = await preparing;
+    expect(prepared.status).toBe("ready");
+    if (prepared.status !== "ready") return;
+    expect(prepared.attachments).toEqual([
+      {
+        type: "image",
+        name: "photo.png",
+        mimeType: "image/png",
+        sizeBytes: 3,
+        dataUrl: "data:image/png;base64,YWJj",
+      },
+    ]);
+    await removed.promise;
+    expect(imageExists).toBe(false);
+  });
+
   it("keeps a failed-send draft's pending upload for retry", async () => {
     const outboxLoad = vi.spyOn(threadOutboxManager, "load").mockResolvedValue(true);
     onTestFinished(() => outboxLoad.mockRestore());
@@ -384,68 +518,75 @@ describe("mobile composer drafts", () => {
     expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
   });
 
-  it("keeps signed-out files through cleanup and restart, and restores only the owning account", async () => {
-    const load = vi.spyOn(threadOutboxManager, "load").mockResolvedValue(true);
-    onTestFinished(() => load.mockRestore());
-    await waitForComposerDraftsLoaded();
-    const environmentId = EnvironmentId.make("cloud-environment");
-    const key = `${environmentId}:thread-1`;
-    const file = {
-      id: "local-pdf",
-      type: "file" as const,
-      name: "notes.pdf",
-      mimeType: "application/pdf",
-      sizeBytes: 42,
-      fileUri: "file:///documents/t3-composer-attachments/notes.pdf",
-      uploadEnvironmentId: environmentId,
-      uploadedAttachmentId: "pending-pdf",
-    };
-    const queued = {
-      environmentId,
-      threadId: ThreadId.make("thread-2"),
-      messageId: MessageId.make("queued-1"),
-      commandId: CommandId.make("command-1"),
-      text: "Send later",
-      attachments: [file],
-      createdAt: "2026-08-31T12:00:00.000Z",
-    };
-    appAtomRegistry.set(composerDraftsAtom, {
-      [key]: { text: "Unsent notes", attachments: [file] },
-      "direct-environment:thread-1": DRAFT,
-      "pending-task:queued-1": { text: "Edited queued task", attachments: [file] },
-    });
-    appAtomRegistry.set(threadOutboxManager.queuedMessagesByThreadKeyAtom, { queued: [queued] });
-    await archiveCloudComposerDrafts("account-a", new Set([environmentId]));
-    expect(appAtomRegistry.get(composerDraftsAtom)).toEqual({
-      "direct-environment:thread-1": DRAFT,
-    });
-    // The registry can remove the active outbox and drafts after the backup lands.
-    appAtomRegistry.set(threadOutboxManager.queuedMessagesByThreadKeyAtom, {});
-    await clearComposerDraftsEnvironment(environmentId);
-    await releaseUnusedComposerAttachmentFiles([file]);
-    expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
-    expect(composerAttachmentCleanupMocks.releaseUploads).not.toHaveBeenCalled();
+  it.each(["file", "image"] as const)(
+    "keeps signed-out %s attachments through cleanup and restart, and restores only the owning account",
+    async (type) => {
+      const load = vi.spyOn(threadOutboxManager, "load").mockResolvedValue(true);
+      onTestFinished(() => load.mockRestore());
+      await waitForComposerDraftsLoaded();
+      const environmentId = EnvironmentId.make("cloud-environment");
+      const key = `${environmentId}:thread-1`;
+      const name = type === "image" ? "notes.png" : "notes.pdf";
+      const metadata = {
+        id: "local-notes",
+        name,
+        mimeType: type === "image" ? "image/png" : "application/pdf",
+        sizeBytes: 42,
+        fileUri: `file:///documents/t3-composer-attachments/${name}`,
+        uploadEnvironmentId: environmentId,
+        uploadedAttachmentId: "pending-notes",
+      };
+      const file =
+        type === "image"
+          ? { ...metadata, type, previewUri: metadata.fileUri }
+          : { ...metadata, type };
+      const queued = {
+        environmentId,
+        threadId: ThreadId.make("thread-2"),
+        messageId: MessageId.make("queued-1"),
+        commandId: CommandId.make("command-1"),
+        text: "Send later",
+        attachments: [file],
+        createdAt: "2026-08-31T12:00:00.000Z",
+      };
+      appAtomRegistry.set(composerDraftsAtom, {
+        [key]: { text: "Unsent notes", attachments: [file] },
+        "direct-environment:thread-1": DRAFT,
+        "pending-task:queued-1": { text: "Edited queued task", attachments: [file] },
+      });
+      appAtomRegistry.set(threadOutboxManager.queuedMessagesByThreadKeyAtom, { queued: [queued] });
+      await archiveCloudComposerDrafts("account-a", new Set([environmentId]));
+      expect(appAtomRegistry.get(composerDraftsAtom)).toEqual({
+        "direct-environment:thread-1": DRAFT,
+      });
+      // The registry can remove the active outbox and drafts after the backup lands.
+      appAtomRegistry.set(threadOutboxManager.queuedMessagesByThreadKeyAtom, {});
+      await clearComposerDraftsEnvironment(environmentId);
+      await releaseUnusedComposerAttachmentFiles([file]);
+      expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
+      expect(composerAttachmentCleanupMocks.releaseUploads).not.toHaveBeenCalled();
 
-    appAtomRegistry.set(composerDraftsAtom, {});
-    appAtomRegistry.set(composerCloudDraftsAtom, { accountId: null, signedOut: {} });
-    resetComposerDraftsLoadState();
-    await waitForComposerDraftsLoaded();
-    await restoreCloudComposerDrafts("account-b");
-    expect(getComposerDraftSnapshot(key).attachments).toEqual([]);
-    expect(appAtomRegistry.get(threadOutboxManager.queuedMessagesByThreadKeyAtom)).toEqual({});
-    const enqueue = vi.spyOn(threadOutboxManager, "enqueue").mockResolvedValue();
-    onTestFinished(() => enqueue.mockRestore());
-    await restoreCloudComposerDrafts("account-a");
-    expect(getComposerDraftSnapshot(key)).toEqual({ text: "Unsent notes", attachments: [file] });
-    expect(getComposerDraftSnapshot("pending-task:queued-1").text).toBe("Edited queued task");
-    expect(enqueue).toHaveBeenCalledExactlyOnceWith(queued);
-    expect(appAtomRegistry.get(composerCloudDraftsAtom).signedOut).toEqual({});
-    const persisted = decodePersistedComposerState(
-      JSON.parse(composerDraftFileMocks.getDocument()),
-    );
-    expect(persisted.drafts[key]?.attachments).toEqual([file]);
-    expect(persisted.cloudDrafts.accountId).toBe("account-a");
-  });
+      appAtomRegistry.set(composerDraftsAtom, {});
+      appAtomRegistry.set(composerCloudDraftsAtom, { accountId: null, signedOut: {} });
+      resetComposerDraftsLoadState();
+      await waitForComposerDraftsLoaded();
+      await restoreCloudComposerDrafts("account-b");
+      expect(getComposerDraftSnapshot(key).attachments).toEqual([]);
+      expect(appAtomRegistry.get(threadOutboxManager.queuedMessagesByThreadKeyAtom)).toEqual({});
+      const enqueue = vi.spyOn(threadOutboxManager, "enqueue").mockResolvedValue();
+      onTestFinished(() => enqueue.mockRestore());
+      await restoreCloudComposerDrafts("account-a");
+      expect(getComposerDraftSnapshot(key)).toEqual({ text: "Unsent notes", attachments: [file] });
+      expect(getComposerDraftSnapshot("pending-task:queued-1").text).toBe("Edited queued task");
+      expect(enqueue).toHaveBeenCalledExactlyOnceWith(queued);
+      expect(appAtomRegistry.get(composerCloudDraftsAtom).signedOut).toEqual({});
+      const persisted = decodePersistedComposerState(
+        JSON.parse(composerDraftFileMocks.getDocument()),
+      );
+      expect(persisted.drafts[key]?.attachments).toEqual([file]);
+      expect(persisted.cloudDrafts.accountId).toBe("account-a");
+    },
+  );
 
   it("fails sign-out preservation before cleanup if a durable backup cannot be written", async () => {
     const load = vi.spyOn(threadOutboxManager, "load").mockResolvedValue(true);
@@ -470,45 +611,52 @@ describe("mobile composer drafts", () => {
     ).toEqual(DRAFT);
   });
 
-  it("keeps a removed file until both playback and a share copy finish", async () => {
-    const outboxLoad = vi.spyOn(threadOutboxManager, "load").mockResolvedValue(true);
-    onTestFinished(() => outboxLoad.mockRestore());
-    const fileName = "33333333-3333-4333-8333-333333333333-recording.mp4";
-    const file = {
-      id: "file-preview",
-      type: "file" as const,
-      name: "recording.mp4",
-      mimeType: "video/mp4",
-      sizeBytes: 42,
-      fileUri: `file:///private/var/mobile/Containers/Data/Application/11111111-1111-4111-8111-111111111111/Documents/t3-composer-attachments/${fileName}`,
-    };
-    const currentFile = {
-      ...file,
-      fileUri: `file:///var/mobile/Containers/Data/Application/22222222-2222-4222-8222-222222222222/Documents/t3-composer-attachments/${fileName}`,
-    };
-    const releasePlayback = retainComposerAttachmentFileForPreview(file);
-    const releaseShareCopy = retainComposerAttachmentFileForPreview(currentFile);
-    onTestFinished(releasePlayback);
-    onTestFinished(releaseShareCopy);
+  it.each(["file", "image"] as const)(
+    "keeps a removed %s until both preview and a share copy finish",
+    async (type) => {
+      const outboxLoad = vi.spyOn(threadOutboxManager, "load").mockResolvedValue(true);
+      onTestFinished(() => outboxLoad.mockRestore());
+      const name = type === "image" ? "photo.png" : "recording.mp4";
+      const fileName = `33333333-3333-4333-8333-333333333333-${name}`;
+      const metadata = {
+        id: "file-preview",
+        name,
+        mimeType: type === "image" ? "image/png" : "video/mp4",
+        sizeBytes: 42,
+        fileUri: `file:///private/var/mobile/Containers/Data/Application/11111111-1111-4111-8111-111111111111/Documents/t3-composer-attachments/${fileName}`,
+      };
+      const file =
+        type === "image"
+          ? { ...metadata, type, previewUri: metadata.fileUri }
+          : { ...metadata, type };
+      const currentFile = {
+        ...file,
+        fileUri: `file:///var/mobile/Containers/Data/Application/22222222-2222-4222-8222-222222222222/Documents/t3-composer-attachments/${fileName}`,
+      };
+      const releasePlayback = retainComposerAttachmentFileForPreview(file);
+      const releaseShareCopy = retainComposerAttachmentFileForPreview(currentFile);
+      onTestFinished(releasePlayback);
+      onTestFinished(releaseShareCopy);
 
-    await releaseUnusedComposerAttachmentFiles([currentFile]);
-    expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
+      await releaseUnusedComposerAttachmentFiles([currentFile]);
+      expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
 
-    releasePlayback();
-    releasePlayback();
-    await releaseUnusedComposerAttachmentFiles([file]);
-    expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
+      releasePlayback();
+      releasePlayback();
+      await releaseUnusedComposerAttachmentFiles([file]);
+      expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
 
-    const deleted = Promise.withResolvers<void>();
-    composerAttachmentCleanupMocks.remove.mockImplementationOnce(async () => {
-      deleted.resolve();
-      return undefined;
-    });
-    releaseShareCopy();
-    await deleted.promise;
+      const deleted = Promise.withResolvers<void>();
+      composerAttachmentCleanupMocks.remove.mockImplementationOnce(async () => {
+        deleted.resolve();
+        return undefined;
+      });
+      releaseShareCopy();
+      await deleted.promise;
 
-    expect(composerAttachmentCleanupMocks.remove.mock.calls).toEqual([[currentFile.fileUri]]);
-  });
+      expect(composerAttachmentCleanupMocks.remove.mock.calls).toEqual([[currentFile.fileUri]]);
+    },
+  );
 
   it("preserves a preview opened while cleanup is checking the incoming inbox", async () => {
     const outboxLoad = vi.spyOn(threadOutboxManager, "load").mockResolvedValue(true);
@@ -836,9 +984,32 @@ describe("mobile composer drafts", () => {
     }
   });
 
+  it("rejects persisted images without image bytes or a file URI", () => {
+    expect(() =>
+      decodePersistedComposerState({
+        schemaVersion: 1,
+        drafts: {
+          "environment-1:thread-1": {
+            text: "Saved image",
+            attachments: [
+              {
+                id: "image-1",
+                type: "image",
+                name: "photo.png",
+                mimeType: "image/png",
+                sizeBytes: 3,
+                previewUri: "file:///photo.png",
+              },
+            ],
+          },
+        },
+      }),
+    ).toThrow();
+  });
+
   it("hydrates selector state even when the message content is empty", () => {
     expect(
-      decodePersistedComposerDrafts({
+      decodePersistedComposerState({
         schemaVersion: 1,
         drafts: {
           "new-task:environment-1:project-1": {
@@ -858,7 +1029,7 @@ describe("mobile composer drafts", () => {
             },
           },
         },
-      }),
+      }).drafts,
     ).toEqual({
       "new-task:environment-1:project-1": {
         text: "",
@@ -881,18 +1052,18 @@ describe("mobile composer drafts", () => {
 
   it("keeps legacy content-only drafts and rejects invalid selector state", () => {
     expect(
-      decodePersistedComposerDrafts({
+      decodePersistedComposerState({
         schemaVersion: 1,
         drafts: {
           "environment-1:thread-1": DRAFT,
         },
-      }),
+      }).drafts,
     ).toEqual({
       "environment-1:thread-1": DRAFT,
     });
 
     expect(() =>
-      decodePersistedComposerDrafts({
+      decodePersistedComposerState({
         schemaVersion: 1,
         drafts: {
           "environment-1:thread-1": {
@@ -1043,9 +1214,62 @@ describe("mobile composer drafts", () => {
     });
   });
 
+  it.each(["read", "decode"] as const)(
+    "preserves saved drafts and attachment files when the draft %s fails",
+    async (failure) => {
+      vi.useFakeTimers();
+      const file = {
+        id: "saved-file",
+        type: "file" as const,
+        name: "report.pdf",
+        mimeType: "application/pdf",
+        sizeBytes: 42,
+        fileUri: "file:///documents/t3-composer-attachments/report.pdf",
+      };
+      composerDraftFileMocks.setDocument({
+        schemaVersion: failure === "decode" ? 999 : 1,
+        drafts: { "environment-1:saved": { text: "Saved draft", attachments: [file] } },
+      });
+      const original = composerDraftFileMocks.getDocument();
+      if (failure === "read") {
+        composerDraftFileMocks.setReadError(new Error("storage unavailable"));
+      }
+
+      await expect(releaseUnusedComposerAttachmentFiles([file])).rejects.toMatchObject({
+        operation: failure,
+      });
+      setComposerDraftText("environment-1:new", "Keep my new edits too");
+      await expect(flushComposerDrafts()).rejects.toMatchObject({ operation: failure });
+
+      expect(composerDraftFileMocks.getDocument()).toBe(original);
+      expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
+    },
+  );
+
+  it("retries a failed debounced read on final flush without dropping saved drafts or new edits", async () => {
+    vi.useFakeTimers();
+    composerDraftFileMocks.setDocument({
+      schemaVersion: 1,
+      drafts: { "environment-1:saved": DRAFT },
+    });
+    const original = composerDraftFileMocks.getDocument();
+    composerDraftFileMocks.setReadError(new Error("storage unavailable"));
+    setComposerDraftText("environment-1:new", "New edits");
+    await vi.advanceTimersByTimeAsync(200);
+    expect(composerDraftFileMocks.getDocument()).toBe(original);
+
+    composerDraftFileMocks.setReadError(null);
+    await flushComposerDrafts();
+
+    expect(JSON.parse(composerDraftFileMocks.getDocument()).drafts).toEqual({
+      "environment-1:saved": DRAFT,
+      "environment-1:new": { text: "New edits", attachments: [] },
+    });
+  });
+
   it("serializes environment cleanup after an older queued write", async () => {
     vi.useFakeTimers();
-    composerDraftFileMocks.setDocument(JSON.stringify({ schemaVersion: 1, drafts: {} }));
+    composerDraftFileMocks.setDocument({ schemaVersion: 1, drafts: {} });
     composerDraftFileMocks.resetWrites();
     let releaseFirstWrite!: () => void;
     const firstWriteBarrier = new Promise<void>((resolve) => {
@@ -1523,7 +1747,92 @@ describe("mobile composer drafts", () => {
     expect(composerAttachmentCleanupMocks.remove.mock.calls).toEqual([[first.fileUri]]);
   });
 
-  // Uses a fresh module instance (hydration is one-shot), so it stays last.
+  // These final tests use fresh module instances for independent hydration.
+  it("keeps attachment files and uploads after a recovered message leaves an incomplete outbox", async () => {
+    vi.resetModules();
+    const drafts = await import("./use-composer-drafts");
+    const { threadOutboxManager: manager } = await import("./thread-outbox");
+    const { expoThreadOutboxStorage: storage, ThreadOutboxStorageError } =
+      await import("./thread-outbox-storage");
+    const { removeThreadOutboxMessage } = await import("./thread-outbox-removal");
+    const { appAtomRegistry: registry } = await import("./atom-registry");
+    onTestFinished(() => registry.dispose());
+    const warning = vi.spyOn(console, "warn").mockImplementation(() => {});
+    onTestFinished(() => warning.mockRestore());
+    const file = {
+      id: "file-partial-outbox",
+      type: "file" as const,
+      name: "shared.pdf",
+      mimeType: "application/pdf",
+      sizeBytes: 42,
+      fileUri: "file:///documents/t3-composer-attachments/shared.pdf",
+      uploadEnvironmentId: EnvironmentId.make("environment-1"),
+      uploadedAttachmentId: "pending-partial-outbox",
+    };
+    const readable = {
+      environmentId: EnvironmentId.make("environment-1"),
+      threadId: ThreadId.make("thread-1"),
+      messageId: MessageId.make("message-readable"),
+      commandId: CommandId.make("command-readable"),
+      text: "Send the readable message",
+      attachments: [file],
+      createdAt: "2026-09-04T00:00:00.000Z",
+    };
+    const saved = new Map([[readable.messageId, readable]]);
+    let unreadable = true;
+    const load = vi.spyOn(storage, "load").mockImplementation(async () => ({
+      messages: [...saved.values()],
+      errors: unreadable
+        ? [
+            new ThreadOutboxStorageError({
+              operation: "read-message",
+              environmentId: null,
+              threadId: null,
+              messageId: null,
+              fileName: "unreadable.json",
+              cause: new Error("unreadable record"),
+            }),
+          ]
+        : [],
+    }));
+    const remove = vi.spyOn(storage, "remove").mockImplementation(async (message) => {
+      saved.delete(message.messageId);
+    });
+    onTestFinished(() => {
+      load.mockRestore();
+      remove.mockRestore();
+    });
+
+    await expect(manager.load()).resolves.toBe(false);
+    await expect(manager.confirmQueued(readable)).resolves.toBe(true);
+    await expect(removeThreadOutboxMessage(readable)).resolves.toBe(true);
+    await drafts.releaseUnusedComposerAttachmentFiles([file]);
+    expect(registry.get(manager.queuedMessagesByThreadKeyAtom)).toEqual({});
+    expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
+    expect(composerAttachmentCleanupMocks.releaseUploads).not.toHaveBeenCalled();
+
+    const recovered = {
+      ...readable,
+      environmentId: EnvironmentId.make("environment-2"),
+      messageId: MessageId.make("message-recovered"),
+      commandId: CommandId.make("command-recovered"),
+    };
+    saved.set(recovered.messageId, recovered);
+    unreadable = false;
+    await expect(manager.load()).resolves.toBe(true);
+    await drafts.releaseUnusedComposerAttachmentFiles([file]);
+    expect(composerAttachmentCleanupMocks.remove).not.toHaveBeenCalled();
+    expect(composerAttachmentCleanupMocks.releaseUploads).not.toHaveBeenCalled();
+
+    await removeThreadOutboxMessage(recovered);
+    await drafts.releaseUnusedComposerAttachmentFiles([file]);
+    expect(composerAttachmentCleanupMocks.remove).toHaveBeenCalledWith(file.fileUri);
+    expect(composerAttachmentCleanupMocks.releaseUploads).toHaveBeenCalledWith(
+      file.uploadEnvironmentId,
+      [file.uploadedAttachmentId],
+    );
+  });
+
   it("hydrates persisted drafts before a cold-start sweep deletes their files", async () => {
     const file = {
       id: "file-cold-start",
diff --git a/apps/mobile/src/state/use-composer-drafts.ts b/apps/mobile/src/state/use-composer-drafts.ts
index 2a613b4914da..6b463c2d2624 100644
--- a/apps/mobile/src/state/use-composer-drafts.ts
+++ b/apps/mobile/src/state/use-composer-drafts.ts
@@ -20,7 +20,7 @@ import {
   isComposerAttachmentFileRetained,
   retainComposerAttachmentFile,
 } from "../lib/composerAttachmentFiles";
-import type { DraftComposerAttachment, DraftComposerFileAttachment } from "../lib/composerImages";
+import type { DraftComposerAttachment, FileBackedComposerAttachment } from "../lib/composerImages";
 import { SerializedAsyncQueue } from "../lib/serialized-async-queue";
 import { appAtomRegistry } from "./atom-registry";
 import {
@@ -148,11 +148,13 @@ export const composerCloudDraftsAtom = Atom.make<ComposerCloudDraftState>({
 
 let loadPromise: Promise<void> | null = null;
 let persistTimer: ReturnType<typeof setTimeout> | null = null;
+let persistRetryNeeded = false;
 const persistenceQueue = new SerializedAsyncQueue();
 
 /** Resets module-level state between test runs. */
 export function resetComposerDraftsLoadState(): void {
   loadPromise = null;
+  persistRetryNeeded = false;
 }
 
 function normalizeDraft(draft: ComposerDraft | undefined): ComposerDraft {
@@ -236,10 +238,6 @@ export function decodePersistedComposerState(value: unknown): {
   };
 }
 
-export function decodePersistedComposerDrafts(value: unknown): Record<string, ComposerDraft> {
-  return decodePersistedComposerState(value).drafts;
-}
-
 async function getComposerDraftsFile() {
   const { Directory, File, Paths } = await import("expo-file-system");
   const directory = new Directory(Paths.document, COMPOSER_DRAFTS_DIRECTORY);
@@ -265,20 +263,12 @@ async function loadPersistedComposerState(): Promise<
     operation = "decode";
     return decodePersistedComposerState(JSON.parse(raw) as unknown);
   } catch (cause) {
-    console.warn(
-      "[composer-drafts] ignored persisted draft failure",
-      new ComposerDraftPersistenceError({
-        operation,
-        directory: COMPOSER_DRAFTS_DIRECTORY,
-        fileName: COMPOSER_DRAFTS_FILE,
-        cause,
-      }),
-    );
-    return {
-      drafts: {},
-      stickyModelSelection: null,
-      cloudDrafts: { accountId: null, signedOut: {} },
-    };
+    throw new ComposerDraftPersistenceError({
+      operation,
+      directory: COMPOSER_DRAFTS_DIRECTORY,
+      fileName: COMPOSER_DRAFTS_FILE,
+      cause,
+    });
   }
 }
 
@@ -341,20 +331,26 @@ export async function flushComposerDrafts(): Promise<void> {
   // An edit during an awaited write schedules another debounced write, so
   // keep landing snapshots until no debounce is pending after a queue drain.
   do {
-    while (persistTimer !== null) {
-      clearTimeout(persistTimer);
+    while (persistTimer !== null || persistRetryNeeded) {
+      if (persistTimer !== null) clearTimeout(persistTimer);
       persistTimer = null;
-      await persistenceQueue.run(() =>
-        writePersistedComposerState(
-          appAtomRegistry.get(composerDraftsAtom),
-          appAtomRegistry.get(stickyComposerModelSelectionAtom),
-        ),
-      );
+      persistRetryNeeded = false;
+      try {
+        await persistenceQueue.run(() =>
+          writePersistedComposerState(
+            appAtomRegistry.get(composerDraftsAtom),
+            appAtomRegistry.get(stickyComposerModelSelectionAtom),
+          ),
+        );
+      } catch (error) {
+        persistRetryNeeded = true;
+        throw error;
+      }
     }
     // Draining also waits for an already-fired debounce whose write is still
     // gated behind its own hydration await inside the queue.
     await persistenceQueue.run(() => Promise.resolve());
-  } while (persistTimer !== null);
+  } while (persistTimer !== null || persistRetryNeeded);
 }
 
 function signedOutAttachmentOwners() {
@@ -376,7 +372,7 @@ function isComposerAttachmentFileReferenced(fileUri: string): boolean {
   return [...drafts, ...queuedMessages, ...signedOutAttachmentOwners()].some((owner) =>
     owner.attachments.some(
       (attachment) =>
-        attachment.type === "file" &&
+        attachment.fileUri !== undefined &&
         composerAttachmentFileReferenceKey(attachment.fileUri) === referenceKey,
     ),
   );
@@ -403,9 +399,9 @@ export async function releaseUnusedComposerAttachmentFiles(
   attachments: ReadonlyArray<DraftComposerAttachment>,
 ): Promise<void> {
   const candidates = new Set(
-    attachments
-      .filter((attachment) => attachment.type === "file")
-      .map((attachment) => attachment.fileUri),
+    attachments.flatMap((attachment) =>
+      attachment.fileUri !== undefined ? [attachment.fileUri] : [],
+    ),
   );
   const uploadCandidates = new Map<EnvironmentId, Set<string>>();
   for (const attachment of attachments) {
@@ -454,7 +450,7 @@ export async function releaseUnusedComposerAttachmentFiles(
     incomingShareFileUris = new Set(
       incomingShares.flatMap((share) =>
         share.attachments.flatMap((attachment) =>
-          attachment.type === "file"
+          attachment.fileUri !== undefined
             ? [composerAttachmentFileReferenceKey(attachment.fileUri)]
             : [],
         ),
@@ -509,7 +505,8 @@ export function scheduleUnusedComposerAttachmentCleanup(
 ): void {
   if (
     !attachments.some(
-      (attachment) => attachment.type === "file" || attachment.uploadedAttachmentId !== undefined,
+      (attachment) =>
+        attachment.fileUri !== undefined || attachment.uploadedAttachmentId !== undefined,
     )
   ) {
     return;
@@ -521,7 +518,7 @@ export function scheduleUnusedComposerAttachmentCleanup(
 
 /** Keeps a native preview or upload readable until it finishes, then retries ownership cleanup. */
 export function retainComposerAttachmentFileForPreview(
-  attachment: DraftComposerFileAttachment,
+  attachment: FileBackedComposerAttachment,
 ): () => void {
   return retainComposerAttachmentFile(attachment.fileUri, () => {
     scheduleUnusedComposerAttachmentCleanup([attachment]);
@@ -534,19 +531,20 @@ function schedulePersistComposerState(): void {
   }
   persistTimer = setTimeout(() => {
     persistTimer = null;
-    ensureComposerDraftsLoaded();
     // The write enters the serialization queue before waiting on hydration,
     // so flushComposerDrafts' queue drain cannot resolve ahead of it.
     void persistenceQueue.run(async () => {
-      if (loadPromise !== null) {
-        await loadPromise;
-      }
       try {
+        await waitForComposerDraftsLoaded();
         await writePersistedComposerState(
           appAtomRegistry.get(composerDraftsAtom),
           appAtomRegistry.get(stickyComposerModelSelectionAtom),
         );
+        persistRetryNeeded = false;
       } catch (error) {
+        // A failed debounce has no timer left. A later final flush must retry
+        // these edits after persisted ownership can be read safely.
+        persistRetryNeeded = true;
         console.warn("[composer-drafts] failed to persist drafts", error);
         // Draft persistence is best-effort; in-memory drafts still keep working.
       }
@@ -558,35 +556,39 @@ export function ensureComposerDraftsLoaded(): void {
   if (loadPromise !== null) {
     return;
   }
-  loadPromise = loadPersistedComposerState()
-    .then((persisted) => {
-      appAtomRegistry.set(composerCloudDraftsAtom, persisted.cloudDrafts);
-      if (Object.keys(persisted.drafts).length > 0) {
-        const current = appAtomRegistry.get(composerDraftsAtom);
-        appAtomRegistry.set(composerDraftsAtom, {
-          ...persisted.drafts,
-          ...current,
-        });
-      }
-      if (
-        persisted.stickyModelSelection !== null &&
-        appAtomRegistry.get(stickyComposerModelSelectionAtom) === null
-      ) {
-        appAtomRegistry.set(stickyComposerModelSelectionAtom, persisted.stickyModelSelection);
-      }
-    })
-    .catch((cause) => {
-      console.warn(
-        "[composer-drafts] failed to hydrate drafts",
-        new ComposerDraftPersistenceError({
-          operation: "hydrate",
-          directory: COMPOSER_DRAFTS_DIRECTORY,
-          fileName: COMPOSER_DRAFTS_FILE,
-          cause,
-        }),
-      );
-      // Draft loading is best-effort; in-memory drafts still keep working.
-    });
+  const loading = loadPersistedComposerState().then((persisted) => {
+    appAtomRegistry.set(composerCloudDraftsAtom, persisted.cloudDrafts);
+    if (Object.keys(persisted.drafts).length > 0) {
+      const current = appAtomRegistry.get(composerDraftsAtom);
+      appAtomRegistry.set(composerDraftsAtom, {
+        ...persisted.drafts,
+        ...current,
+      });
+    }
+    if (
+      persisted.stickyModelSelection !== null &&
+      appAtomRegistry.get(stickyComposerModelSelectionAtom) === null
+    ) {
+      appAtomRegistry.set(stickyComposerModelSelectionAtom, persisted.stickyModelSelection);
+    }
+  });
+  loadPromise = loading;
+  // Handle fire-and-forget hook loads without swallowing failures from the
+  // write and cleanup callers that await this same promise. A later call retries.
+  void loading.catch((cause) => {
+    if (loadPromise === loading) loadPromise = null;
+    console.warn(
+      "[composer-drafts] failed to hydrate drafts",
+      cause instanceof ComposerDraftPersistenceError
+        ? cause
+        : new ComposerDraftPersistenceError({
+            operation: "hydrate",
+            directory: COMPOSER_DRAFTS_DIRECTORY,
+            fileName: COMPOSER_DRAFTS_FILE,
+            cause,
+          }),
+    );
+  });
 }
 
 /** Wait until persisted drafts have been merged into the in-memory composer state. */
diff --git a/apps/mobile/src/state/use-terminal-session.ts b/apps/mobile/src/state/use-terminal-session.ts
index 328557a2005d..6be57007a60f 100644
--- a/apps/mobile/src/state/use-terminal-session.ts
+++ b/apps/mobile/src/state/use-terminal-session.ts
@@ -2,6 +2,7 @@ import {
   combineTerminalSessionState,
   EMPTY_TERMINAL_BUFFER_STATE,
   EMPTY_TERMINAL_SESSION_STATE,
+  terminalOutputText,
   type KnownTerminalSession,
   type TerminalSessionState,
 } from "@t3tools/client-runtime/state/terminal";
@@ -11,10 +12,16 @@ import { useMemo } from "react";
 import { useEnvironmentQuery } from "./query";
 import { terminalEnvironment } from "./terminal";
 
+type LegacyTerminalSessionState = TerminalSessionState & { readonly buffer: string };
+const EMPTY_LEGACY_TERMINAL_SESSION_STATE: LegacyTerminalSessionState = {
+  ...EMPTY_TERMINAL_SESSION_STATE,
+  buffer: "",
+};
+
 export function useAttachedTerminalSession(input: {
   readonly environmentId: EnvironmentId | null;
   readonly terminal: TerminalAttachInput | null;
-}): TerminalSessionState {
+}): LegacyTerminalSessionState {
   const attach = useEnvironmentQuery(
     input.environmentId !== null && input.terminal !== null
       ? terminalEnvironment.attach({
@@ -31,10 +38,14 @@ export function useAttachedTerminalSession(input: {
           input: null,
         }),
   );
+  const output = attach.data?.output ?? EMPTY_TERMINAL_BUFFER_STATE.output;
+  // Installed native binaries still accept initialBuffer. Keep materialization
+  // at this mobile boundary until the native streaming API is released.
+  const buffer = useMemo(() => terminalOutputText(output), [output]);
 
   return useMemo(() => {
     if (input.environmentId === null || input.terminal === null) {
-      return EMPTY_TERMINAL_SESSION_STATE;
+      return EMPTY_LEGACY_TERMINAL_SESSION_STATE;
     }
     const summary =
       metadata.data?.find(
@@ -42,9 +53,12 @@ export function useAttachedTerminalSession(input: {
           terminal.threadId === input.terminal?.threadId &&
           terminal.terminalId === input.terminal?.terminalId,
       ) ?? null;
-    const state = combineTerminalSessionState(summary, attach.data ?? EMPTY_TERMINAL_BUFFER_STATE);
+    const state = {
+      ...combineTerminalSessionState(summary, attach.data ?? EMPTY_TERMINAL_BUFFER_STATE),
+      buffer,
+    };
     return attach.error === null ? state : { ...state, error: attach.error, status: "error" };
-  }, [attach.data, attach.error, input.environmentId, input.terminal, metadata.data]);
+  }, [attach.data, attach.error, buffer, input.environmentId, input.terminal, metadata.data]);
 }
 
 export function useKnownTerminalSessions(input: {
diff --git a/apps/mobile/src/state/use-thread-composer-state.ts b/apps/mobile/src/state/use-thread-composer-state.ts
index 1d760df72cba..64a7ddeb7882 100644
--- a/apps/mobile/src/state/use-thread-composer-state.ts
+++ b/apps/mobile/src/state/use-thread-composer-state.ts
@@ -126,21 +126,28 @@ export function useThreadComposerState() {
     () => (selectedThreadKey ? (queuedMessagesByThreadKey[selectedThreadKey] ?? []) : []),
     [queuedMessagesByThreadKey, selectedThreadKey],
   );
-  const selectedThreadFeed = useMemo(() => {
-    if (!selectedThreadDetail) {
-      return [];
-    }
+  const localFeedbackMessages = useMemo(() => {
     const submissions = selectedThreadKey
       ? (feedbackSubmissionsByThreadKey[selectedThreadKey] ?? [])
       : [];
-    return buildThreadFeed(selectedThreadDetail, {
-      localMessages: submissions.flatMap((submission) =>
-        submission.status === "interrupted"
-          ? []
-          : [codexFeedbackMessage(submission), codexFeedbackMessage(submission, "assistant")],
-      ),
-    });
-  }, [feedbackSubmissionsByThreadKey, selectedThreadDetail, selectedThreadKey]);
+    return submissions.flatMap((submission) =>
+      submission.status === "interrupted"
+        ? []
+        : [codexFeedbackMessage(submission), codexFeedbackMessage(submission, "assistant")],
+    );
+  }, [feedbackSubmissionsByThreadKey, selectedThreadKey]);
+  const selectedThreadMessages = selectedThreadDetail?.messages;
+  const selectedThreadActivities = selectedThreadDetail?.activities;
+  const selectedThreadFeed = useMemo(
+    () =>
+      selectedThreadMessages && selectedThreadActivities
+        ? buildThreadFeed(
+            { messages: selectedThreadMessages, activities: selectedThreadActivities },
+            { localMessages: localFeedbackMessages },
+          )
+        : [],
+    [localFeedbackMessages, selectedThreadActivities, selectedThreadMessages],
+  );
 
   const selectedDraft = selectedThreadKey ? composerDrafts[selectedThreadKey] : null;
   const draftMessage = selectedDraft?.text ?? "";
@@ -269,7 +276,7 @@ export function useThreadComposerState() {
     ) {
       Alert.alert(
         "Antigravity model unavailable",
-        "Open model settings to finish setup or choose another model.",
+        "Set up Antigravity on web or desktop, or choose another model.",
       );
       return null;
     }
diff --git a/apps/mobile/src/state/use-thread-outbox-drain.test.ts b/apps/mobile/src/state/use-thread-outbox-drain.test.ts
index 698e3f5a85f1..9d8f6f02793f 100644
--- a/apps/mobile/src/state/use-thread-outbox-drain.test.ts
+++ b/apps/mobile/src/state/use-thread-outbox-drain.test.ts
@@ -54,6 +54,8 @@ const harness = vi.hoisted(() => ({
   })(),
 }));
 
+vi.mock("react-native", () => ({ Alert: { alert: vi.fn() } }));
+
 vi.mock("expo-file-system", () => ({
   Directory: harness.draftFile.Directory,
   File: harness.draftFile.File,
@@ -113,7 +115,7 @@ vi.mock("./thread-outbox", async () => {
   harness.manager = createThreadOutboxManager({
     registry: appAtomRegistry,
     storage: {
-      load: async () => [],
+      load: async () => ({ messages: [], errors: [] }),
       write: async () => undefined,
       remove: (message) => harness.removeOutboxMessage(message),
     },
@@ -122,7 +124,6 @@ vi.mock("./thread-outbox", async () => {
   return {
     threadOutboxManager: manager,
     flushThreadOutbox: async () => undefined,
-    ensureThreadOutboxLoaded: () => undefined,
     confirmThreadOutboxMessageQueued: (message: never) => manager.confirmQueued(message),
     updateThreadOutboxMessage: (message: never, expectedRevision?: number) =>
       manager.update(message, expectedRevision),
@@ -219,7 +220,6 @@ describe("thread outbox attachment preparation", () => {
     );
     const preparationStarted = Promise.withResolvers<void>();
     const preparationBarrier = Promise.withResolvers<PreparedTurnAttachments>();
-    const releaseUploads = vi.fn(async () => undefined);
     harness.prepareTurnAttachments.mockImplementationOnce(async () => {
       preparationStarted.resolve();
       return preparationBarrier.promise;
@@ -237,12 +237,10 @@ describe("thread outbox attachment preparation", () => {
       attachments: [],
       draftAttachments: message.attachments,
       pendingAttachmentIds: ["pending-reused-upload"],
-      releaseUploads,
     });
 
     await expect(preparation).resolves.toEqual({ status: "abandoned" });
     expect(remainingMessages()).toEqual([edited]);
-    expect(releaseUploads).not.toHaveBeenCalled();
   });
 
   it("keeps an unchanged queued payload ready after attachment reuse", async () => {
@@ -254,13 +252,11 @@ describe("thread outbox attachment preparation", () => {
       }),
       "pending-reused-upload",
     );
-    const releaseUploads = vi.fn(async () => undefined);
     harness.prepareTurnAttachments.mockResolvedValueOnce({
       status: "ready",
       attachments: [],
       draftAttachments: message.attachments,
       pendingAttachmentIds: ["pending-reused-upload"],
-      releaseUploads,
     });
     await harness.manager.enqueue(message);
     const revision = harness.manager.revisionOf(message.messageId);
@@ -271,7 +267,6 @@ describe("thread outbox attachment preparation", () => {
       persistedMessage: message,
       deliveryRevision: revision,
     });
-    expect(releaseUploads).not.toHaveBeenCalled();
   });
 
   it("uses the known next revision after persisting uploaded references", async () => {
@@ -296,7 +291,6 @@ describe("thread outbox attachment preparation", () => {
         attachments: [],
         draftAttachments: uploadedAttachments,
         pendingAttachmentIds: ["pending-new-upload"],
-        releaseUploads: async () => undefined,
       };
     });
     await harness.manager.enqueue(message);
diff --git a/apps/mobile/src/state/use-thread-outbox-drain.ts b/apps/mobile/src/state/use-thread-outbox-drain.ts
index 07e0e7d3100a..487aa4da4c2f 100644
--- a/apps/mobile/src/state/use-thread-outbox-drain.ts
+++ b/apps/mobile/src/state/use-thread-outbox-drain.ts
@@ -15,6 +15,7 @@ import { buildTemporaryWorktreeBranchName } from "@t3tools/shared/git";
 import * as Cause from "effect/Cause";
 import { AsyncResult } from "effect/unstable/reactivity";
 import { useCallback, useEffect, useRef, useState } from "react";
+import { Alert } from "react-native";
 
 import { scopedProjectKey, scopedThreadKey } from "../lib/scopedEntities";
 import { buildProjectThreadStartTurnInput } from "../lib/projectThreadStartTurn";
@@ -26,7 +27,6 @@ import { useProjects, useServerConfigs, useThreadShells } from "./entities";
 import { serverEnvironment } from "./server";
 import {
   confirmThreadOutboxMessageQueued,
-  ensureThreadOutboxLoaded,
   threadOutboxManager,
   threadOutboxRevision,
   updateThreadOutboxMessage,
@@ -583,8 +583,21 @@ export function useThreadOutboxDrain(): void {
   );
 
   useEffect(() => {
-    ensureThreadOutboxLoaded();
+    let mounted = true;
+    const load = async () => {
+      if ((await threadOutboxManager.load()) || !mounted) return;
+      Alert.alert(
+        "Some queued messages could not be loaded",
+        "Unreadable records and attachment files are still saved. Other messages can still be sent.",
+        [
+          { text: "Dismiss", style: "cancel" },
+          { text: "Retry", onPress: () => void load() },
+        ],
+      );
+    };
+    void load();
     return () => {
+      mounted = false;
       for (const timer of retryTimersRef.current.values()) {
         clearTimeout(timer);
       }
@@ -636,7 +649,7 @@ export function useThreadOutboxDrain(): void {
       if (isModelSelectionUnavailable(serverConfig, settings.modelSelection)) {
         return restoreQueuedMessage(
           queuedMessage,
-          "Antigravity model unavailable. Open model settings to finish setup or choose another model.",
+          "Antigravity model unavailable. Set it up on web or desktop, or choose another model.",
         );
       }
       const { reportFailure } = makeDeliveryHelpers(queuedMessage);
@@ -729,7 +742,7 @@ export function useThreadOutboxDrain(): void {
       if (isModelSelectionUnavailable(currentConfig, settings.modelSelection)) {
         return restoreQueuedMessage(
           persistedMessage,
-          "Antigravity model unavailable. Open model settings to finish setup or choose another model.",
+          "Antigravity model unavailable. Set it up on web or desktop, or choose another model.",
         );
       }
       const sendSettings = resolveQueuedThreadSettings(
@@ -766,12 +779,6 @@ export function useThreadOutboxDrain(): void {
         (await completeQueuedMessageDelivery(persistedMessage, deliveryRevision)) === "removed";
       if (delivered) {
         acknowledgedExistingThreadMessageIdsRef.current.delete(persistedMessage.messageId);
-        // The delivered turn holds its own copy of the bytes. A failed delete
-        // is surfaced (never fails the delivered turn); the server also
-        // expires leaked pending uploads.
-        await prepared.releaseUploads().catch((error) => {
-          console.warn("[thread-outbox] could not delete consumed pending uploads", error);
-        });
       }
       return delivered;
     },
@@ -811,7 +818,7 @@ export function useThreadOutboxDrain(): void {
       if (isModelSelectionUnavailable(serverConfig, settings.modelSelection)) {
         return restoreQueuedMessage(
           queuedMessage,
-          "Antigravity model unavailable. Open model settings to finish setup or choose another model.",
+          "Antigravity model unavailable. Set it up on web or desktop, or choose another model.",
         );
       }
       let prepared: PreparedTurnAttachments;
@@ -855,7 +862,7 @@ export function useThreadOutboxDrain(): void {
       if (isModelSelectionUnavailable(currentConfig, settings.modelSelection)) {
         return restoreQueuedMessage(
           persistedMessage,
-          "Antigravity model unavailable. Open model settings to finish setup or choose another model.",
+          "Antigravity model unavailable. Set it up on web or desktop, or choose another model.",
         );
       }
       const sendSettings = resolveQueuedThreadSettings(
@@ -873,7 +880,6 @@ export function useThreadOutboxDrain(): void {
           messageId: queuedMessage.messageId,
           createdAt: queuedMessage.createdAt,
           text: queuedMessage.text.trim(),
-          attachments: queuedMessage.attachments,
           uploadedAttachments: prepared.attachments,
           modelSelection: sendSettings.modelSelection,
           runtimeMode: sendSettings.runtimeMode,
@@ -905,13 +911,7 @@ export function useThreadOutboxDrain(): void {
         // payload as a duplicate creation. Hand it to the thread's composer.
         return recoverEditedCreationAfterDelivery(persistedMessage);
       }
-      if (outcome === "removed") {
-        await prepared.releaseUploads().catch((error) => {
-          console.warn("[thread-outbox] could not delete consumed pending uploads", error);
-        });
-        return true;
-      }
-      return false;
+      return outcome === "removed";
     },
     [makeDeliveryHelpers, restoreQueuedMessage, startTurn],
   );
diff --git a/apps/server/integration/providerService.integration.test.ts b/apps/server/integration/providerService.integration.test.ts
index 3ad85b1a68b9..0d041b36ecb8 100644
--- a/apps/server/integration/providerService.integration.test.ts
+++ b/apps/server/integration/providerService.integration.test.ts
@@ -100,7 +100,10 @@ const makeIntegrationFixture = (options?: { readonly analytics?: Layer.Layer<Ana
       Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers),
     ).pipe(Layer.provide(SqlitePersistenceMemory));
 
-    const layer = makeProviderServiceLive().pipe(Layer.provide(shared));
+    const layer = makeProviderServiceLive().pipe(
+      Layer.provide(NodeServices.layer),
+      Layer.provide(shared),
+    );
 
     return {
       cwd,
diff --git a/apps/server/package.json b/apps/server/package.json
index ca74368348ea..3d03fcd45dba 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -22,13 +22,12 @@
     "test": "vp test run"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.170",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.260",
     "@effect/platform-bun": "catalog:",
     "@effect/platform-node": "catalog:",
     "@effect/sql-sqlite-bun": "catalog:",
     "@ff-labs/fff-node": "0.9.4",
     "@opencode-ai/sdk": "^1.3.15",
-    "@pierre/diffs": "catalog:",
     "effect": "catalog:",
     "msgpackr-extract": "3.0.4",
     "node-pty": "^1.1.0",
diff --git a/apps/server/scripts/t3-sqlite-state.test.ts b/apps/server/scripts/t3-sqlite-state.test.ts
index ec236f4a67c0..fa5471bfa8c4 100644
--- a/apps/server/scripts/t3-sqlite-state.test.ts
+++ b/apps/server/scripts/t3-sqlite-state.test.ts
@@ -7,6 +7,8 @@ import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import * as NodeSqliteClient from "@t3tools/shared/nodeSqliteClient";
 import { runSqliteState } from "./t3-sqlite-state.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const createFixtureDatabase = Effect.fn("createSqliteStateFixtureDatabase")(function* (
   baseDir: string,
@@ -73,47 +75,50 @@ it.layer(NodeServices.layer)("t3-sqlite-state", (it) => {
     }),
   );
 
-  it.effect("backs up isolated state before writes and refuses the shared home", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-state-exec-" });
-      yield* createFixtureDatabase(baseDir);
+  it.effect.skipIf(!symlinksSupported)(
+    "backs up isolated state before writes and refuses the shared home",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-sqlite-state-exec-" });
+        yield* createFixtureDatabase(baseDir);
 
-      const mutation = yield* runSqliteState({
-        operation: "exec",
-        baseDir,
-        sql: "INSERT INTO fixtures (id, label) VALUES (2, 'seeded')",
-      });
-      assert.equal(mutation.operation, "exec");
-      if (mutation.operation === "exec") {
-        assert.equal((yield* fs.stat(mutation.backup)).mode & 0o777, 0o600);
-      }
-
-      const error = yield* runSqliteState(
-        {
+        const mutation = yield* runSqliteState({
           operation: "exec",
           baseDir,
-          sql: "DELETE FROM fixtures",
-        },
-        { sharedHome: baseDir },
-      ).pipe(Effect.flip);
-      assert.equal(error._tag, "SqliteStateSharedHomeMutationError");
+          sql: "INSERT INTO fixtures (id, label) VALUES (2, 'seeded')",
+        });
+        assert.equal(mutation.operation, "exec");
+        if (mutation.operation === "exec" && (yield* HostProcessPlatform) !== "win32") {
+          // NTFS has no POSIX mode bits to report.
+          assert.equal((yield* fs.stat(mutation.backup)).mode & 0o777, 0o600);
+        }
 
-      const aliasParent = yield* fs.makeTempDirectoryScoped({
-        prefix: "t3-sqlite-state-alias-",
-      });
-      const aliasBaseDir = path.join(aliasParent, "shared-home-alias");
-      yield* fs.symlink(baseDir, aliasBaseDir);
-      const aliasError = yield* runSqliteState(
-        {
-          operation: "exec",
-          baseDir: aliasBaseDir,
-          sql: "DELETE FROM fixtures",
-        },
-        { sharedHome: baseDir },
-      ).pipe(Effect.flip);
-      assert.equal(aliasError._tag, "SqliteStateSharedHomeMutationError");
-    }),
+        const error = yield* runSqliteState(
+          {
+            operation: "exec",
+            baseDir,
+            sql: "DELETE FROM fixtures",
+          },
+          { sharedHome: baseDir },
+        ).pipe(Effect.flip);
+        assert.equal(error._tag, "SqliteStateSharedHomeMutationError");
+
+        const aliasParent = yield* fs.makeTempDirectoryScoped({
+          prefix: "t3-sqlite-state-alias-",
+        });
+        const aliasBaseDir = path.join(aliasParent, "shared-home-alias");
+        yield* fs.symlink(baseDir, aliasBaseDir);
+        const aliasError = yield* runSqliteState(
+          {
+            operation: "exec",
+            baseDir: aliasBaseDir,
+            sql: "DELETE FROM fixtures",
+          },
+          { sharedHome: baseDir },
+        ).pipe(Effect.flip);
+        assert.equal(aliasError._tag, "SqliteStateSharedHomeMutationError");
+      }),
   );
 });
diff --git a/apps/server/src/assets/AssetAccess.test.ts b/apps/server/src/assets/AssetAccess.test.ts
index 251a4761705d..53e33cf7fd5b 100644
--- a/apps/server/src/assets/AssetAccess.test.ts
+++ b/apps/server/src/assets/AssetAccess.test.ts
@@ -24,6 +24,7 @@ import { assetFileResponse } from "../http.ts";
 import { ASSET_ROUTE_PREFIX, issueAssetUrl, resolveAsset } from "./AssetAccess.ts";
 import * as NativeAppIconResolver from "./NativeAppIconResolver.ts";
 import { openMediaFile } from "./MediaFile.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 vi.mock("node:fs/promises", async (importOriginal) => {
   const actual = await importOriginal<typeof NodeFSP>();
@@ -108,216 +109,241 @@ describe("AssetAccess", () => {
     }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("rejects non-previewable files, disguised targets, and directories", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-validation-" });
-      for (const name of ["report.md", "secret.txt", "secret.%70ng", "secret.png#private.txt"]) {
-        const filePath = path.join(root, name);
-        yield* fs.writeFileString(filePath, "not media");
-        const error = yield* issueAssetUrl({
-          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+  it.effect.skipIf(!symlinksSupported)(
+    "rejects non-previewable files, disguised targets, and directories",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-validation-" });
+        for (const name of ["report.md", "secret.txt", "secret.%70ng", "secret.png#private.txt"]) {
+          const filePath = path.join(root, name);
+          yield* fs.writeFileString(filePath, "not media");
+          const error = yield* issueAssetUrl({
+            resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+          }).pipe(Effect.flip);
+          expect(error).toBeInstanceOf(AssetPreviewTypeValidationError);
+        }
+        const disguisedPath = path.join(root, "disguised.png");
+        yield* fs.symlink(path.join(root, "secret.txt"), disguisedPath);
+        const disguisedError = yield* issueAssetUrl({
+          resource: {
+            _tag: "media-file",
+            threadId: ThreadId.make("thread-1"),
+            path: disguisedPath,
+          },
         }).pipe(Effect.flip);
-        expect(error).toBeInstanceOf(AssetPreviewTypeValidationError);
-      }
-      const disguisedPath = path.join(root, "disguised.png");
-      yield* fs.symlink(path.join(root, "secret.txt"), disguisedPath);
-      const disguisedError = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: disguisedPath },
-      }).pipe(Effect.flip);
-      expect(disguisedError).toBeInstanceOf(AssetPreviewTypeValidationError);
-      const directoryPath = path.join(root, "directory.png");
-      yield* fs.makeDirectory(directoryPath);
-      const directoryError = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: directoryPath },
-      }).pipe(Effect.flip);
-      expect(directoryError._tag).toBe("AssetWorkspaceAssetNotFoundError");
-    }).pipe(Effect.provide(testLayer)),
-  );
-
-  it.effect("binds media URLs to the canonical target and rejects symlink substitution", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-symlink-" });
-      const filePath = path.join(root, "actual.svg");
-      const aliasPath = path.join(root, "alias.png");
-      const replacementPath = path.join(root, "other.svg");
-      yield* fs.writeFileString(filePath, "<svg/>");
-      yield* fs.writeFileString(replacementPath, "<svg>private</svg>");
-      yield* fs.symlink(filePath, aliasPath);
-      const canonicalFile = yield* fs.realPath(filePath);
-      const result = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: aliasPath },
-      });
-      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
-      const separator = suffix.indexOf("/");
-      const token = suffix.slice(0, separator);
-      const name = suffix.slice(separator + 1);
-      const expected = { kind: "file", path: canonicalFile, mimeType: "image/svg+xml" };
-      expect(yield* resolveAsset(token, name)).toMatchObject(expected);
-      yield* fs.remove(aliasPath);
-      yield* fs.symlink(replacementPath, aliasPath);
-      expect(yield* resolveAsset(token, name)).toMatchObject(expected);
-      yield* fs.remove(filePath);
-      yield* fs.symlink(replacementPath, filePath);
-      expect(yield* resolveAsset(token, name)).toBeNull();
-    }).pipe(Effect.provide(testLayer)),
+        expect(disguisedError).toBeInstanceOf(AssetPreviewTypeValidationError);
+        const directoryPath = path.join(root, "directory.png");
+        yield* fs.makeDirectory(directoryPath);
+        const directoryError = yield* issueAssetUrl({
+          resource: {
+            _tag: "media-file",
+            threadId: ThreadId.make("thread-1"),
+            path: directoryPath,
+          },
+        }).pipe(Effect.flip);
+        expect(directoryError._tag).toBe("AssetWorkspaceAssetNotFoundError");
+      }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("keeps full and partial responses bound to the file opened during resolution", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-file-" });
-      const filePath = path.join(root, "recording.mp4");
-      const savedPath = path.join(root, "saved.mp4");
-      const secretPath = path.join(root, "secret.txt");
-      yield* fs.writeFileString(filePath, "0123456789");
-      yield* fs.writeFileString(secretPath, "private information");
-      const result = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
-      });
-      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
-      const separator = suffix.indexOf("/");
-      for (const [range, expected, status] of [
-        [undefined, "0123456789", 200],
-        ["bytes=2-5", "2345", 206],
-      ] as const) {
-        const asset = yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1));
-        if (!asset) throw new Error("Expected a resolved media file");
-
-        yield* fs.rename(filePath, savedPath);
-        yield* fs.symlink(secretPath, filePath);
-        const response = HttpServerResponse.toWeb(yield* assetFileResponse(asset, range));
-        expect(response.status).toBe(status);
-        expect(response.headers.get("content-length")).toBe(String(expected.length));
-        expect(yield* Effect.promise(() => response.text())).toBe(expected);
+  it.effect.skipIf(!symlinksSupported)(
+    "binds media URLs to the canonical target and rejects symlink substitution",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-symlink-" });
+        const filePath = path.join(root, "actual.svg");
+        const aliasPath = path.join(root, "alias.png");
+        const replacementPath = path.join(root, "other.svg");
+        yield* fs.writeFileString(filePath, "<svg/>");
+        yield* fs.writeFileString(replacementPath, "<svg>private</svg>");
+        yield* fs.symlink(filePath, aliasPath);
+        const canonicalFile = yield* fs.realPath(filePath);
+        const result = yield* issueAssetUrl({
+          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: aliasPath },
+        });
+        const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+        const separator = suffix.indexOf("/");
+        const token = suffix.slice(0, separator);
+        const name = suffix.slice(separator + 1);
+        const expected = { kind: "file", path: canonicalFile, mimeType: "image/svg+xml" };
+        expect(yield* resolveAsset(token, name)).toMatchObject(expected);
+        yield* fs.remove(aliasPath);
+        yield* fs.symlink(replacementPath, aliasPath);
+        expect(yield* resolveAsset(token, name)).toMatchObject(expected);
         yield* fs.remove(filePath);
-        yield* fs.rename(savedPath, filePath);
-      }
-    }).pipe(Effect.provide(testLayer)),
+        yield* fs.symlink(replacementPath, filePath);
+        expect(yield* resolveAsset(token, name)).toBeNull();
+      }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("rejects a symlink swapped in after canonical validation but before open", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-race-" });
-      const filePath = path.join(root, "recording.mp4");
-      const secretPath = path.join(root, "secret.txt");
-      yield* fs.writeFileString(filePath, "video");
-      yield* fs.writeFileString(secretPath, "secret");
-      const canonicalPath = yield* fs.realPath(filePath);
-      const result = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
-      });
-      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
-      const separator = suffix.indexOf("/");
-      const swappingFileSystem = FileSystem.FileSystem.of({
-        ...fs,
-        stat: Effect.fn(function* (requestedPath) {
-          const info = yield* fs.stat(requestedPath);
-          if (requestedPath === canonicalPath) {
-            yield* fs.remove(filePath);
-            yield* fs.symlink(secretPath, filePath);
-          }
-          return info;
-        }),
-      });
-      expect(
-        yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1)).pipe(
-          Effect.provideService(FileSystem.FileSystem, swappingFileSystem),
-        ),
-      ).toBeNull();
-    }).pipe(Effect.provide(testLayer)),
+  it.effect.skipIf(!symlinksSupported)(
+    "keeps full and partial responses bound to the file opened during resolution",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-file-" });
+        const filePath = path.join(root, "recording.mp4");
+        const savedPath = path.join(root, "saved.mp4");
+        const secretPath = path.join(root, "secret.txt");
+        yield* fs.writeFileString(filePath, "0123456789");
+        yield* fs.writeFileString(secretPath, "private information");
+        const result = yield* issueAssetUrl({
+          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+        });
+        const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+        const separator = suffix.indexOf("/");
+        for (const [range, expected, status] of [
+          [undefined, "0123456789", 200],
+          ["bytes=2-5", "2345", 206],
+        ] as const) {
+          const asset = yield* resolveAsset(
+            suffix.slice(0, separator),
+            suffix.slice(separator + 1),
+          );
+          if (!asset) throw new Error("Expected a resolved media file");
+
+          yield* fs.rename(filePath, savedPath);
+          yield* fs.symlink(secretPath, filePath);
+          const response = HttpServerResponse.toWeb(yield* assetFileResponse(asset, range));
+          expect(response.status).toBe(status);
+          expect(response.headers.get("content-length")).toBe(String(expected.length));
+          expect(yield* Effect.promise(() => response.text())).toBe(expected);
+          yield* fs.remove(filePath);
+          yield* fs.rename(savedPath, filePath);
+        }
+      }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("closes a descriptor rejected when its path changes during open", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-rejected-" });
-      const filePath = path.join(root, "recording.mp4");
-      const secretPath = path.join(root, "secret.txt");
-      yield* fs.writeFileString(filePath, "video");
-      yield* fs.writeFileString(secretPath, "secret");
-      const canonicalPath = yield* fs.realPath(filePath);
-      const originalOpen = (yield* Effect.promise(() =>
-        vi.importActual<typeof NodeFSP>("node:fs/promises"),
-      )).open;
-      let opened: NodeFSP.FileHandle | undefined;
-      const openSpy = vi.mocked(NodeFSP.open).mockImplementation(async (target, flags, mode) => {
-        const handle = await originalOpen(target, flags, mode);
-        if (target === canonicalPath) {
-          opened = handle;
-          await NodeFSP.unlink(filePath);
-          await NodeFSP.symlink(secretPath, filePath);
-        }
-        return handle;
-      });
-      yield* Effect.addFinalizer(() => Effect.sync(() => openSpy.mockImplementation(originalOpen)));
-      expect(yield* openMediaFile(canonicalPath)).toBeNull();
-      expect(opened).toBeDefined();
-      expect(opened?.fd).toBe(-1);
-    }).pipe(Effect.provide(testLayer)),
+  it.effect.skipIf(!symlinksSupported)(
+    "rejects a symlink swapped in after canonical validation but before open",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-race-" });
+        const filePath = path.join(root, "recording.mp4");
+        const secretPath = path.join(root, "secret.txt");
+        yield* fs.writeFileString(filePath, "video");
+        yield* fs.writeFileString(secretPath, "secret");
+        const canonicalPath = yield* fs.realPath(filePath);
+        const result = yield* issueAssetUrl({
+          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+        });
+        const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+        const separator = suffix.indexOf("/");
+        const swappingFileSystem = FileSystem.FileSystem.of({
+          ...fs,
+          stat: Effect.fn(function* (requestedPath) {
+            const info = yield* fs.stat(requestedPath);
+            if (requestedPath === canonicalPath) {
+              yield* fs.remove(filePath);
+              yield* fs.symlink(secretPath, filePath);
+            }
+            return info;
+          }),
+        });
+        expect(
+          yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1)).pipe(
+            Effect.provideService(FileSystem.FileSystem, swappingFileSystem),
+          ),
+        ).toBeNull();
+      }).pipe(Effect.provide(testLayer)),
   );
 
-  it.effect("rejects an ancestor symlink race even when canonical path rechecks would pass", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-parent-race-" });
-      const publicDirectory = path.join(root, "public");
-      const privateDirectory = path.join(root, "private");
-      yield* fs.makeDirectory(publicDirectory);
-      yield* fs.makeDirectory(privateDirectory);
-      const filePath = path.join(publicDirectory, "recording.mp4");
-      yield* fs.writeFileString(filePath, "public video");
-      yield* fs.writeFileString(path.join(privateDirectory, "recording.mp4"), "private video");
-      const canonicalPath = yield* fs.realPath(filePath);
-      const result = yield* issueAssetUrl({
-        resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
-      });
-      const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
-      const separator = suffix.indexOf("/");
-      const native = yield* Effect.promise(() =>
-        vi.importActual<typeof NodeFSP>("node:fs/promises"),
-      );
-      const savedDirectory = path.join(root, "saved");
-      const realpathSpy = vi.mocked(NodeFSP.realpath).mockImplementationOnce(async () => {
-        // A pathname-only guard can see the original parents during realpath,
-        // but the private file during both lstat calls and open.
-        await native.unlink(publicDirectory);
-        await native.rename(savedDirectory, publicDirectory);
-        const canonical = await native.realpath(canonicalPath);
-        await native.rename(publicDirectory, savedDirectory);
-        await native.symlink(privateDirectory, publicDirectory, "junction");
-        return canonical;
-      });
-      yield* Effect.addFinalizer(() =>
-        Effect.sync(() => realpathSpy.mockReset().mockImplementation(native.realpath)),
-      );
-      const swappingFileSystem = FileSystem.FileSystem.of({
-        ...fs,
-        realPath: Effect.fn(function* (requestedPath) {
-          const canonical = yield* fs.realPath(requestedPath);
-          if (requestedPath === canonicalPath) {
-            yield* fs.rename(publicDirectory, savedDirectory);
-            yield* Effect.promise(() =>
-              NodeFSP.symlink(privateDirectory, publicDirectory, "junction"),
-            );
+  it.effect.skipIf(!symlinksSupported)(
+    "closes a descriptor rejected when its path changes during open",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-open-rejected-" });
+        const filePath = path.join(root, "recording.mp4");
+        const secretPath = path.join(root, "secret.txt");
+        yield* fs.writeFileString(filePath, "video");
+        yield* fs.writeFileString(secretPath, "secret");
+        const canonicalPath = yield* fs.realPath(filePath);
+        const originalOpen = (yield* Effect.promise(() =>
+          vi.importActual<typeof NodeFSP>("node:fs/promises"),
+        )).open;
+        let opened: NodeFSP.FileHandle | undefined;
+        const openSpy = vi.mocked(NodeFSP.open).mockImplementation(async (target, flags, mode) => {
+          const handle = await originalOpen(target, flags, mode);
+          if (target === canonicalPath) {
+            opened = handle;
+            await NodeFSP.unlink(filePath);
+            await NodeFSP.symlink(secretPath, filePath);
           }
+          return handle;
+        });
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => openSpy.mockImplementation(originalOpen)),
+        );
+        expect(yield* openMediaFile(canonicalPath)).toBeNull();
+        expect(opened).toBeDefined();
+        expect(opened?.fd).toBe(-1);
+      }).pipe(Effect.provide(testLayer)),
+  );
+
+  it.effect.skipIf(!symlinksSupported)(
+    "rejects an ancestor symlink race even when canonical path rechecks would pass",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-media-parent-race-" });
+        const publicDirectory = path.join(root, "public");
+        const privateDirectory = path.join(root, "private");
+        yield* fs.makeDirectory(publicDirectory);
+        yield* fs.makeDirectory(privateDirectory);
+        const filePath = path.join(publicDirectory, "recording.mp4");
+        yield* fs.writeFileString(filePath, "public video");
+        yield* fs.writeFileString(path.join(privateDirectory, "recording.mp4"), "private video");
+        const canonicalPath = yield* fs.realPath(filePath);
+        const result = yield* issueAssetUrl({
+          resource: { _tag: "media-file", threadId: ThreadId.make("thread-1"), path: filePath },
+        });
+        const suffix = result.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
+        const separator = suffix.indexOf("/");
+        const native = yield* Effect.promise(() =>
+          vi.importActual<typeof NodeFSP>("node:fs/promises"),
+        );
+        const savedDirectory = path.join(root, "saved");
+        const realpathSpy = vi.mocked(NodeFSP.realpath).mockImplementationOnce(async () => {
+          // A pathname-only guard can see the original parents during realpath,
+          // but the private file during both lstat calls and open.
+          await native.unlink(publicDirectory);
+          await native.rename(savedDirectory, publicDirectory);
+          const canonical = await native.realpath(canonicalPath);
+          await native.rename(publicDirectory, savedDirectory);
+          await native.symlink(privateDirectory, publicDirectory, "junction");
           return canonical;
-        }),
-      });
-      expect(
-        yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1)).pipe(
-          Effect.provideService(FileSystem.FileSystem, swappingFileSystem),
-        ),
-      ).toBeNull();
-    }).pipe(Effect.provide(testLayer)),
+        });
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => realpathSpy.mockReset().mockImplementation(native.realpath)),
+        );
+        const swappingFileSystem = FileSystem.FileSystem.of({
+          ...fs,
+          realPath: Effect.fn(function* (requestedPath) {
+            const canonical = yield* fs.realPath(requestedPath);
+            if (requestedPath === canonicalPath) {
+              yield* fs.rename(publicDirectory, savedDirectory);
+              yield* Effect.promise(() =>
+                NodeFSP.symlink(privateDirectory, publicDirectory, "junction"),
+              );
+            }
+            return canonical;
+          }),
+        });
+        expect(
+          yield* resolveAsset(suffix.slice(0, separator), suffix.slice(separator + 1)).pipe(
+            Effect.provideService(FileSystem.FileSystem, swappingFileSystem),
+          ),
+        ).toBeNull();
+      }).pipe(Effect.provide(testLayer)),
   );
 
   it.effect("keeps in-place edits readable but requires a new URL after atomic replacement", () =>
@@ -728,7 +754,7 @@ describe("AssetAccess", () => {
         projectFaviconPath: "brand/custom.svg",
       });
 
-      expect(result.sourcePath).toBe("brand/custom.svg");
+      expect(result.sourcePath).toBe(path.join("brand", "custom.svg"));
       expect(result.relativeUrl).toMatch(/\/v[0-9a-f]{64}-custom\.svg$/);
     }).pipe(Effect.provide(testLayer)),
   );
@@ -787,7 +813,7 @@ describe("AssetAccess", () => {
         projectFaviconPath: "brand/saved.svg",
       });
 
-      expect(result.sourcePath).toBe("brand/saved.svg");
+      expect(result.sourcePath).toBe(path.join("brand", "saved.svg"));
       expect(result.relativeUrl).toMatch(/\/v[0-9a-f]{64}-saved\.svg$/);
     }).pipe(Effect.provide(testLayer)),
   );
diff --git a/apps/server/src/assets/MediaFile.ts b/apps/server/src/assets/MediaFile.ts
index f1b63bb659e3..e1053555b052 100644
--- a/apps/server/src/assets/MediaFile.ts
+++ b/apps/server/src/assets/MediaFile.ts
@@ -37,6 +37,11 @@ export interface OpenMediaFile {
   readonly info: NodeFS.BigIntStats;
 }
 
+const realpathLikeFileSystem = (filePath: string) =>
+  new Promise<string>((resolve, reject) => {
+    NodeFS.realpath(filePath, (error, resolved) => (error ? reject(error) : resolve(resolved)));
+  });
+
 /** Opens a canonical media path once. Replacements cannot change the response's source. */
 export const openMediaFile = Effect.fn("openMediaFile")(function* (
   filePath: string,
@@ -71,7 +76,11 @@ export const openMediaFile = Effect.fn("openMediaFile")(function* (
           ) {
             return null;
           }
-          if ((await NodeFSP.realpath(filePath)) !== filePath) return null;
+          // Callers canonicalise with Effect's FileSystem.realPath, which is
+          // Node's JS realpath. fs/promises.realpath is the native binding and
+          // on Windows also expands 8.3 short names, so a path that is already
+          // canonical by the caller's rules would still look swapped here.
+          if ((await realpathLikeFileSystem(filePath)) !== filePath) return null;
           const after = await NodeFSP.lstat(filePath, { bigint: true });
           if (!after.isFile() || info.dev !== after.dev || info.ino !== after.ino) return null;
           accepted = true;
diff --git a/apps/server/src/auth/EnvironmentAuth.test.ts b/apps/server/src/auth/EnvironmentAuth.test.ts
index 6e5f22fa3af6..028fe53e0191 100644
--- a/apps/server/src/auth/EnvironmentAuth.test.ts
+++ b/apps/server/src/auth/EnvironmentAuth.test.ts
@@ -52,6 +52,18 @@ const makeCookieRequest = (
     EnvironmentAuth.EnvironmentAuth["Service"]["authenticateHttpRequest"]
   >[0];
 
+const makeBearerRequest = (
+  token: string,
+): Parameters<EnvironmentAuth.EnvironmentAuth["Service"]["authenticateHttpRequest"]>[0] =>
+  ({
+    cookies: {},
+    headers: {
+      authorization: `Bearer ${token}`,
+    },
+  }) as unknown as Parameters<
+    EnvironmentAuth.EnvironmentAuth["Service"]["authenticateHttpRequest"]
+  >[0];
+
 const requestMetadata = {
   deviceType: "desktop" as const,
   os: "macOS",
@@ -159,6 +171,71 @@ it.layer(NodeServices.layer)("EnvironmentAuth.layer", (it) => {
     }).pipe(Effect.provide(makeEnvironmentAuthLayer())),
   );
 
+  it.effect("rotates desktop bearer sessions without accumulating authorized clients", () =>
+    Effect.gen(function* () {
+      const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
+      const sessions = yield* SessionStore.SessionStore;
+      const browser = yield* serverAuth.createBrowserSession(
+        "desktop-bootstrap-token",
+        requestMetadata,
+      );
+      const browserSession = yield* serverAuth.authenticateHttpRequest(
+        makeCookieRequest(sessions.cookieName, browser.sessionToken),
+      );
+      const staleSessions = yield* Effect.forEach([1, 2, 3], () =>
+        sessions.issue({ subject: "desktop-bootstrap", method: "bearer-access-token" }),
+      );
+      const pairing = yield* serverAuth.issuePairingCredential();
+      const paired = yield* serverAuth.exchangeBootstrapCredentialForAccessToken(
+        pairing.credential,
+        undefined,
+        { ...requestMetadata, label: "T3 Code Desktop" },
+      );
+      const first = yield* serverAuth.exchangeBootstrapCredentialForAccessToken(
+        "desktop-bootstrap-token",
+        undefined,
+        requestMetadata,
+      );
+      const firstSession = yield* serverAuth.authenticateHttpRequest(
+        makeBearerRequest(first.access_token),
+      );
+      const second = yield* serverAuth.exchangeBootstrapCredentialForAccessToken(
+        "desktop-bootstrap-token",
+        undefined,
+        requestMetadata,
+      );
+
+      const active = yield* serverAuth.listSessions();
+      const firstError = yield* serverAuth
+        .authenticateHttpRequest(makeBearerRequest(first.access_token))
+        .pipe(Effect.flip);
+      const secondSession = yield* serverAuth.authenticateHttpRequest(
+        makeBearerRequest(second.access_token),
+      );
+
+      expect(active).toHaveLength(3);
+      expect(active.map((entry) => entry.sessionId)).toContain(browserSession.sessionId);
+      expect(active.map((entry) => entry.sessionId)).toContain(secondSession.sessionId);
+      expect(active.map((entry) => entry.sessionId)).not.toContain(firstSession.sessionId);
+      expect(firstError._tag).toBe("ServerAuthInvalidCredentialError");
+      for (const stale of staleSessions) {
+        const error = yield* sessions.verify(stale.token).pipe(Effect.flip);
+        expect(error._tag).toBe("SessionTokenRevokedError");
+      }
+      const pairedSession = yield* serverAuth.authenticateHttpRequest(
+        makeBearerRequest(paired.access_token),
+      );
+      expect(pairedSession.subject).toBe("one-time-token");
+      expect(active.map((entry) => entry.sessionId)).toContain(pairedSession.sessionId);
+    }).pipe(
+      Effect.provide(
+        makeEnvironmentAuthLayer({
+          desktopBootstrapToken: "desktop-bootstrap-token",
+        }),
+      ),
+    ),
+  );
+
   it.effect("keeps user-issued administrative pairing links manageable", () =>
     Effect.gen(function* () {
       const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
diff --git a/apps/server/src/auth/EnvironmentAuth.ts b/apps/server/src/auth/EnvironmentAuth.ts
index 08838cb7b780..b0406b6e6ecd 100644
--- a/apps/server/src/auth/EnvironmentAuth.ts
+++ b/apps/server/src/auth/EnvironmentAuth.ts
@@ -750,6 +750,9 @@ export const make = Effect.gen(function* () {
                       ttl: Duration.hours(1),
                     }
                   : {}),
+                // Desktop restarts forget the previous bearer token. Replace
+                // its session, including stale entries left by older versions.
+                replaceActiveForSubjectAndMethod: grant.method === "desktop-bootstrap",
                 client: {
                   ...requestMetadata,
                   ...(grant.label ? { label: grant.label } : {}),
@@ -923,12 +926,10 @@ export const make = Effect.gen(function* () {
   const listClientSessions: EnvironmentAuth["Service"]["listClientSessions"] = (currentSessionId) =>
     listSessions().pipe(
       Effect.map((clientSessions) =>
-        clientSessions.map(
-          (clientSession): AuthClientSession => ({
-            ...clientSession,
-            current: clientSession.sessionId === currentSessionId,
-          }),
-        ),
+        clientSessions.map((clientSession): AuthClientSession => ({
+          ...clientSession,
+          current: clientSession.sessionId === currentSessionId,
+        })),
       ),
       Effect.withSpan("EnvironmentAuth.listClientSessions"),
     );
diff --git a/apps/server/src/auth/RpcAuthorization.test.ts b/apps/server/src/auth/RpcAuthorization.test.ts
index 25971b0c0aec..7262239577b4 100644
--- a/apps/server/src/auth/RpcAuthorization.test.ts
+++ b/apps/server/src/auth/RpcAuthorization.test.ts
@@ -43,6 +43,15 @@ describe("RPC authorization scopes", () => {
     );
   });
 
+  it("requires write access to import agent session history", () => {
+    expect(requiredScopeForRpcMethod(WS_METHODS.agentSessionsScan)).toBe(
+      AuthOrchestrationReadScope,
+    );
+    expect(requiredScopeForRpcMethod(WS_METHODS.agentSessionsImport)).toBe(
+      AuthOrchestrationOperateScope,
+    );
+  });
+
   it("reads the reviewer menu under the same scope as the pull request it belongs to", () => {
     // The candidate list is a read like the detail beside it, and asking somebody for a review is
     // a write like every other pull request operation.
diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts
index a1c8966d7052..5d0c0de7d2b9 100644
--- a/apps/server/src/auth/RpcAuthorization.ts
+++ b/apps/server/src/auth/RpcAuthorization.ts
@@ -99,6 +99,8 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.projectsWriteFile]: AuthOrchestrationOperateScope,
   [WS_METHODS.shellOpenInEditor]: AuthOrchestrationOperateScope,
   [WS_METHODS.filesystemBrowse]: AuthOrchestrationReadScope,
+  [WS_METHODS.agentSessionsScan]: AuthOrchestrationReadScope,
+  [WS_METHODS.agentSessionsImport]: AuthOrchestrationOperateScope,
   [WS_METHODS.assetsCreateUrl]: AuthOrchestrationReadScope,
   [WS_METHODS.attachmentsCreateUploadUrl]: AuthOrchestrationOperateScope,
   [WS_METHODS.attachmentsDelete]: AuthOrchestrationOperateScope,
diff --git a/apps/server/src/auth/ServerSecretStore.test.ts b/apps/server/src/auth/ServerSecretStore.test.ts
index d4411fb9f3b7..6b7850aa363b 100644
--- a/apps/server/src/auth/ServerSecretStore.test.ts
+++ b/apps/server/src/auth/ServerSecretStore.test.ts
@@ -109,7 +109,7 @@ const ConcurrentReadMissFileSystemLayer = Layer.effect(
     return {
       ...fileSystem,
       readFile: (path) =>
-        String(path).endsWith("/session-signing-key.bin")
+        /[\\/]session-signing-key\.bin$/.test(String(path))
           ? Ref.updateAndGet(readCountRef, (count) => count + 1).pipe(
               Effect.flatMap((count) => {
                 if (count > 2) {
@@ -219,7 +219,7 @@ it.layer(NodeServices.layer)("ServerSecretStore.layer", (it) => {
       yield* secretStore.set("session-signing-key", Uint8Array.from([1, 2, 3]));
 
       assert.isTrue(
-        chmodCalls.some((call) => call.mode === 0o700 && call.path.endsWith("/secrets")),
+        chmodCalls.some((call) => call.mode === 0o700 && /[\\/]secrets$/.test(call.path)),
       );
       assert.isAtLeast(chmodCalls.filter((call) => call.mode === 0o600).length, 2);
     }).pipe(Effect.provide(NodeServices.layer)),
diff --git a/apps/server/src/auth/SessionStore.test.ts b/apps/server/src/auth/SessionStore.test.ts
index aa3b2d199148..1e2d5c60e9c9 100644
--- a/apps/server/src/auth/SessionStore.test.ts
+++ b/apps/server/src/auth/SessionStore.test.ts
@@ -4,6 +4,9 @@ import { expect, it } from "@effect/vitest";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
 import * as TestClock from "effect/testing/TestClock";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
@@ -43,6 +46,14 @@ const makeSessionStoreLayer = (
     Layer.provide(makeServerConfigLayer(overrides)),
   );
 
+const relaySessionInput = {
+  subject: "managed-relay-bootstrap",
+  method: "dpop-access-token",
+  proofKeyThumbprint: "relay-proof-key",
+  ttl: Duration.hours(1),
+  client: { label: "Relay desktop", deviceType: "desktop" },
+} as const;
+
 const repositoryFailure = new PersistenceSqlError({
   operation: "AuthSessionRepository.getById:query",
   detail: "sqlite is unavailable",
@@ -50,6 +61,7 @@ const repositoryFailure = new PersistenceSqlError({
 
 const failingSessionLookupRepositoryLayer = Layer.succeed(AuthSessions.AuthSessionRepository, {
   create: () => Effect.void,
+  createReplacingActive: () => Effect.succeed([]),
   getById: () => Effect.fail(repositoryFailure),
   listActive: () => Effect.succeed([]),
   revoke: () => Effect.fail(repositoryFailure),
@@ -181,6 +193,78 @@ it.layer(NodeServices.layer)("SessionStore.layer", (it) => {
     }).pipe(Effect.provide(Layer.merge(makeSessionStoreLayer(), TestClock.layer()))),
   );
 
+  it.effect("atomically replaces active sessions with the same subject and method", () =>
+    Effect.gen(function* () {
+      const sessions = yield* SessionStore.SessionStore;
+      const browser = yield* sessions.issue({
+        subject: "desktop-bootstrap",
+        method: "browser-session-cookie",
+      });
+      const [firstBearer, secondBearer] = yield* Effect.all(
+        [
+          sessions.issue({
+            subject: "desktop-bootstrap",
+            method: "bearer-access-token",
+            replaceActiveForSubjectAndMethod: true,
+          }),
+          sessions.issue({
+            subject: "desktop-bootstrap",
+            method: "bearer-access-token",
+            replaceActiveForSubjectAndMethod: true,
+          }),
+        ],
+        { concurrency: "unbounded" },
+      );
+
+      const active = yield* sessions.listActive();
+      const bearerVerification = yield* Effect.all([
+        sessions.verify(firstBearer.token).pipe(Effect.option),
+        sessions.verify(secondBearer.token).pipe(Effect.option),
+      ]);
+
+      expect(active).toHaveLength(2);
+      expect(active.find((entry) => entry.sessionId === browser.sessionId)).toBeDefined();
+      expect(
+        active.filter(
+          (entry) =>
+            entry.subject === "desktop-bootstrap" && entry.method === "bearer-access-token",
+        ),
+      ).toHaveLength(1);
+      expect(bearerVerification.filter(Option.isSome)).toHaveLength(1);
+    }).pipe(Effect.provide(makeSessionStoreLayer())),
+  );
+
+  it.effect("keeps the previous desktop session valid when replacement fails", () =>
+    Effect.gen(function* () {
+      const sessions = yield* SessionStore.SessionStore;
+      const sql = yield* SqlClient.SqlClient;
+      const previous = yield* sessions.issue({
+        subject: "desktop-bootstrap",
+        method: "bearer-access-token",
+      });
+      yield* sql`
+        CREATE TRIGGER reject_auth_session_insert BEFORE INSERT ON auth_sessions
+        BEGIN
+          SELECT RAISE(ABORT, 'simulated insert failure');
+        END
+      `;
+
+      const error = yield* sessions
+        .issue({
+          subject: "desktop-bootstrap",
+          method: "bearer-access-token",
+          replaceActiveForSubjectAndMethod: true,
+        })
+        .pipe(Effect.flip);
+
+      expect(error._tag).toBe("SessionCredentialIssueError");
+      expect((yield* sessions.verify(previous.token)).sessionId).toBe(previous.sessionId);
+      expect((yield* sessions.listActive()).map((session) => session.sessionId)).toEqual([
+        previous.sessionId,
+      ]);
+    }).pipe(Effect.provide(Layer.mergeAll(makeSessionStoreLayer(), SqlitePersistenceMemory))),
+  );
+
   it.effect("rejects websocket tokens once the parent session has expired", () =>
     Effect.gen(function* () {
       const sessions = yield* SessionStore.SessionStore;
@@ -346,6 +430,124 @@ it.layer(NodeServices.layer)("SessionStore.layer", (it) => {
       expect(afterReconnect[0]?.lastConnectedAt?.toString()).not.toBe(firstConnectedAt?.toString());
     }).pipe(Effect.provide(Layer.merge(makeSessionStoreLayer(), TestClock.layer()))),
   );
+
+  it.effect("keeps connected relay sessions visible through expiry and HTTP renewal", () =>
+    Effect.gen(function* () {
+      const sessions = yield* SessionStore.SessionStore;
+      const original = yield* sessions.issue(relaySessionInput);
+      const websocket = yield* sessions.issueWebSocketToken(original.sessionId, {
+        ttl: Duration.hours(2),
+      });
+      yield* sessions.verifyWebSocketToken(websocket.token);
+      yield* sessions.markConnected(original.sessionId);
+      const beforeExpiry = yield* sessions.listActive();
+      expect(beforeExpiry).toHaveLength(1);
+      expect(beforeExpiry[0]?.connected).toBe(true);
+
+      yield* TestClock.adjust(Duration.minutes(61));
+
+      expect(yield* sessions.listActive()).toEqual(beforeExpiry);
+      expect(yield* Effect.flip(sessions.verify(original.token))).toMatchObject({
+        _tag: "SessionTokenExpiredError",
+      });
+      expect(yield* Effect.flip(sessions.verifyWebSocketToken(websocket.token))).toMatchObject({
+        _tag: "WebSocketSessionExpiredError",
+      });
+
+      const renewed = yield* sessions.issue(relaySessionInput);
+      const afterRenewal = yield* sessions.listActive();
+      expect(renewed.sessionId).not.toBe(original.sessionId);
+      expect(afterRenewal).toHaveLength(2);
+      expect(afterRenewal).toEqual(
+        expect.arrayContaining([
+          beforeExpiry[0],
+          expect.objectContaining({
+            sessionId: renewed.sessionId,
+            connected: false,
+            lastConnectedAt: null,
+          }),
+        ]),
+      );
+    }).pipe(Effect.provide(Layer.merge(makeSessionStoreLayer(), TestClock.layer()))),
+  );
+
+  it.effect.each([1, 2])(
+    "removes an expired session from listings and updates after its last of %s sockets closes",
+    (socketCount) =>
+      Effect.gen(function* () {
+        const sessions = yield* SessionStore.SessionStore;
+        const issued = yield* sessions.issue(relaySessionInput);
+        const changes = yield* Queue.unbounded<SessionStore.SessionCredentialChange>();
+        yield* sessions.streamChanges.pipe(
+          Stream.runForEach((change) => Queue.offer(changes, change)),
+          Effect.forkScoped({ startImmediately: true }),
+        );
+        for (let index = 0; index < socketCount; index += 1) {
+          yield* sessions.markConnected(issued.sessionId);
+          expect(yield* Queue.take(changes)).toMatchObject({
+            type: "clientUpserted",
+            clientSession: { sessionId: issued.sessionId, connected: true },
+          });
+        }
+
+        yield* TestClock.adjust(Duration.minutes(61));
+
+        for (let remaining = socketCount - 1; remaining >= 0; remaining -= 1) {
+          yield* sessions.markDisconnected(issued.sessionId);
+          const change = yield* Queue.take(changes);
+          const listed = yield* sessions.listActive();
+          if (remaining > 0) {
+            expect(change).toMatchObject({
+              type: "clientUpserted",
+              clientSession: { sessionId: issued.sessionId, connected: true },
+            });
+            expect(listed).toHaveLength(1);
+            expect(listed[0]?.connected).toBe(true);
+          } else {
+            expect(change).toEqual({ type: "clientRemoved", sessionId: issued.sessionId });
+            expect(listed).toEqual([]);
+          }
+        }
+      }).pipe(
+        Effect.scoped,
+        Effect.provide(Layer.merge(makeSessionStoreLayer(), TestClock.layer())),
+      ),
+  );
+
+  it.effect.each(["revoke", "revokeAllExcept"] as const)(
+    "removes expired connected sessions with %s",
+    (operation) =>
+      Effect.gen(function* () {
+        const sessions = yield* SessionStore.SessionStore;
+        const administrative = yield* sessions.issue({ subject: "desktop-bootstrap" });
+        const client = yield* sessions.issue(relaySessionInput);
+        yield* sessions.markConnected(client.sessionId);
+        yield* TestClock.adjust(Duration.minutes(61));
+        const changes = yield* Queue.unbounded<SessionStore.SessionCredentialChange>();
+        yield* sessions.streamChanges.pipe(
+          Stream.runForEach((change) => Queue.offer(changes, change)),
+          Effect.forkScoped({ startImmediately: true }),
+        );
+
+        if (operation === "revoke") {
+          expect(yield* sessions.revoke(client.sessionId)).toBe(true);
+        } else {
+          expect(yield* sessions.revokeAllExcept(administrative.sessionId)).toBe(1);
+        }
+
+        expect(yield* Queue.take(changes)).toEqual({
+          type: "clientRemoved",
+          sessionId: client.sessionId,
+        });
+        const listed = yield* sessions.listActive();
+        expect(listed).toHaveLength(1);
+        expect(listed[0]?.sessionId).toBe(administrative.sessionId);
+      }).pipe(
+        Effect.scoped,
+        Effect.provide(Layer.merge(makeSessionStoreLayer(), TestClock.layer())),
+      ),
+  );
+
   it.effect("records client connection metadata without clearing prior values", () =>
     Effect.gen(function* () {
       const sessions = yield* SessionStore.SessionStore;
diff --git a/apps/server/src/auth/SessionStore.ts b/apps/server/src/auth/SessionStore.ts
index d4fbe445edf6..f4e5e3c487ac 100644
--- a/apps/server/src/auth/SessionStore.ts
+++ b/apps/server/src/auth/SessionStore.ts
@@ -370,6 +370,11 @@ export class SessionStore extends Context.Service<
       readonly scopes?: ReadonlyArray<AuthEnvironmentScope>;
       readonly client?: AuthClientMetadata;
       readonly proofKeyThumbprint?: string;
+      /**
+       * Atomically revoke active sessions with the same subject and method
+       * before storing this session.
+       */
+      readonly replaceActiveForSubjectAndMethod?: boolean;
     }) => Effect.Effect<IssuedSession, SessionCredentialInternalError>;
     readonly verify: (token: string) => Effect.Effect<VerifiedSession, SessionCredentialError>;
     readonly issueWebSocketToken: (
@@ -477,7 +482,7 @@ export const make = Effect.gen(function* () {
   const secretStore = yield* ServerSecretStore.ServerSecretStore;
   const authSessions = yield* AuthSessions.AuthSessionRepository;
   const signingSecret = yield* secretStore.getOrCreateRandom(SIGNING_SECRET_NAME, 32);
-  const connectedSessionsRef = yield* Ref.make(new Map<string, number>());
+  const connectedSessionsRef = yield* Ref.make(new Map<AuthSessionId, number>());
   const changesPubSub = yield* PubSub.unbounded<SessionCredentialChange>();
   const cookieInput = {
     mode: serverConfig.mode,
@@ -510,6 +515,11 @@ export const make = Effect.gen(function* () {
       }
 
       const connectedSessions = yield* Ref.get(connectedSessionsRef);
+      const connected = connectedSessions.has(row.value.sessionId);
+      const now = yield* DateTime.now;
+      if (!connected && row.value.expiresAt.epochMilliseconds <= now.epochMilliseconds) {
+        return Option.none<AuthClientSession>();
+      }
       return Option.some(
         toAuthClientSession({
           sessionId: row.value.sessionId,
@@ -520,7 +530,7 @@ export const make = Effect.gen(function* () {
           issuedAt: row.value.issuedAt,
           expiresAt: row.value.expiresAt,
           lastConnectedAt: row.value.lastConnectedAt,
-          connected: connectedSessions.has(row.value.sessionId),
+          connected,
         }),
       );
     });
@@ -594,7 +604,7 @@ export const make = Effect.gen(function* () {
     }).pipe(
       Effect.flatMap(() => loadActiveSession(sessionId)),
       Effect.flatMap((session) =>
-        Option.isSome(session) ? emitUpsert(session.value) : Effect.void,
+        Option.isSome(session) ? emitUpsert(session.value) : emitRemoved(sessionId),
       ),
       Effect.catchCause((cause) =>
         Effect.logError("Failed to publish disconnected-session auth update.").pipe(
@@ -647,24 +657,40 @@ export const make = Effect.gen(function* () {
       );
       const signature = signPayload(encodedPayload, signingSecret);
       const client = input?.client ?? createDefaultClientMetadata();
-      yield* authSessions
-        .create({
-          sessionId,
-          subject: claims.sub,
-          scopes: claims.scopes,
-          method: claims.method,
-          client: {
-            label: client.label ?? null,
-            ipAddress: client.ipAddress ?? null,
-            userAgent: client.userAgent ?? null,
-            deviceType: client.deviceType,
-            os: client.os ?? null,
-            browser: client.browser ?? null,
-          },
-          issuedAt,
-          expiresAt,
-        })
-        .pipe(Effect.mapError((cause) => new SessionCredentialIssueError({ sessionId, cause })));
+      const sessionRecord = {
+        sessionId,
+        subject: claims.sub,
+        scopes: claims.scopes,
+        method: claims.method,
+        client: {
+          label: client.label ?? null,
+          ipAddress: client.ipAddress ?? null,
+          userAgent: client.userAgent ?? null,
+          deviceType: client.deviceType,
+          os: client.os ?? null,
+          browser: client.browser ?? null,
+        },
+        issuedAt,
+        expiresAt,
+      } satisfies AuthSessions.CreateAuthSessionInput;
+      const replacedSessionIds = yield* (
+        input?.replaceActiveForSubjectAndMethod
+          ? authSessions.createReplacingActive({ session: sessionRecord, revokedAt: issuedAt })
+          : authSessions.create(sessionRecord).pipe(Effect.as([] as ReadonlyArray<AuthSessionId>))
+      ).pipe(Effect.mapError((cause) => new SessionCredentialIssueError({ sessionId, cause })));
+      if (replacedSessionIds.length > 0) {
+        yield* Ref.update(connectedSessionsRef, (current) => {
+          const next = new Map(current);
+          for (const replacedSessionId of replacedSessionIds) {
+            next.delete(replacedSessionId);
+          }
+          return next;
+        });
+        yield* Effect.forEach(replacedSessionIds, emitRemoved, {
+          concurrency: "unbounded",
+          discard: true,
+        });
+      }
       yield* emitUpsert(
         toAuthClientSession({
           sessionId,
@@ -861,7 +887,10 @@ export const make = Effect.gen(function* () {
     function* () {
       const now = yield* DateTime.now;
       const connectedSessions = yield* Ref.get(connectedSessionsRef);
-      const rows = yield* authSessions.listActive({ now });
+      const rows = yield* authSessions.listActive({
+        now,
+        connectedSessionIds: Array.from(connectedSessions.keys()),
+      });
 
       return rows.map((row) =>
         toAuthClientSession({
diff --git a/apps/server/src/bin.test.ts b/apps/server/src/bin.test.ts
index 0deb261dbf9e..e1a13d4ce8e7 100644
--- a/apps/server/src/bin.test.ts
+++ b/apps/server/src/bin.test.ts
@@ -3,6 +3,7 @@ import * as NodeHttp from "node:http";
 import * as NodeFS from "node:fs";
 import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
+import * as NodeChildProcess from "node:child_process";
 
 import * as NodeHttpServer from "@effect/platform-node/NodeHttpServer";
 import * as NodeServices from "@effect/platform-node/NodeServices";
@@ -137,6 +138,225 @@ const readPersistedSnapshot = (baseDir: string) =>
     }).pipe(Effect.provide(makeProjectPersistenceLayer(config)));
   });
 
+const makeProjectLookupFixture = Effect.fn("makeProjectLookupFixture")(function* (
+  withThread: boolean,
+  removeWorkspace: boolean,
+) {
+  const baseDir = NodeFS.mkdtempSync(
+    NodePath.join(NodeOS.tmpdir(), "t3-cli-project-lookup-state-"),
+  );
+  const workspaceRoot = NodeFS.mkdtempSync(
+    NodePath.join(NodeOS.tmpdir(), "t3-cli-project-lookup-git-"),
+  );
+  NodeChildProcess.execFileSync("git", ["init", "--initial-branch=main", workspaceRoot], {
+    stdio: "ignore",
+  });
+  yield* runCliWithRuntime(["project", "add", workspaceRoot, "--base-dir", baseDir]);
+  const snapshot = yield* readPersistedSnapshot(baseDir);
+  const project = snapshot.projects.find((candidate) => candidate.workspaceRoot === workspaceRoot)!;
+  assert.isDefined(project);
+  if (withThread) {
+    const config = yield* makeCliTestServerConfig(baseDir);
+    yield* Effect.gen(function* () {
+      const engine = yield* OrchestrationEngine.OrchestrationEngineService;
+      yield* engine.dispatch({
+        type: "thread.create",
+        commandId: CommandId.make("cmd-project-lookup-thread"),
+        threadId: ThreadId.make("thread-project-lookup"),
+        projectId: project.id,
+        title: "Project lookup test",
+        modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5-codex" },
+        interactionMode: "default",
+        runtimeMode: "approval-required",
+        branch: null,
+        worktreePath: null,
+        createdAt: DateTime.formatIso(yield* DateTime.now),
+      });
+    }).pipe(Effect.provide(makeProjectPersistenceLayer(config)));
+  }
+  if (removeWorkspace) {
+    NodeFS.renameSync(workspaceRoot, `${workspaceRoot}-removed`);
+    assert.isFalse(NodeFS.existsSync(workspaceRoot));
+  }
+  return { baseDir, workspaceRoot, project };
+});
+
+it.layer(NodeServices.layer)("project lookup with unavailable workspaces", (it) => {
+  it.effect("removes an empty project by ID without force after its directory is gone", () =>
+    Effect.gen(function* () {
+      const { baseDir, project } = yield* makeProjectLookupFixture(false, true);
+      yield* runCliWithRuntime(["project", "remove", project.id, "--base-dir", baseDir]);
+      const after = yield* readPersistedSnapshot(baseDir);
+      assert.isNotNull(after.projects.find((candidate) => candidate.id === project.id)!.deletedAt);
+    }),
+  );
+
+  it.effect.each([true, false])(
+    "requires force for child threads, then removes by ID; missing=%s",
+    (removeWorkspace) =>
+      Effect.gen(function* () {
+        const { baseDir, project } = yield* makeProjectLookupFixture(true, removeWorkspace);
+        const error = yield* runCliWithRuntime([
+          "project",
+          "remove",
+          project.id,
+          "--base-dir",
+          baseDir,
+        ]).pipe(Effect.flip);
+        assert.include(error.message, "cannot be deleted without force=true");
+        const retained = yield* readPersistedSnapshot(baseDir);
+        assert.isNull(
+          retained.projects.find((candidate) => candidate.id === project.id)!.deletedAt,
+        );
+        assert.isNull(
+          retained.threads.find((thread) => thread.id === "thread-project-lookup")!.deletedAt,
+        );
+        yield* runCliWithRuntime([
+          "project",
+          "remove",
+          project.id,
+          "--force",
+          "--base-dir",
+          baseDir,
+        ]);
+        const after = yield* readPersistedSnapshot(baseDir);
+        assert.isNotNull(
+          after.projects.find((candidate) => candidate.id === project.id)!.deletedAt,
+        );
+        assert.isNotNull(
+          after.threads.find((thread) => thread.id === "thread-project-lookup")!.deletedAt,
+        );
+      }),
+  );
+
+  it.effect("cannot remove the old environment's ID from a replacement empty database", () =>
+    Effect.gen(function* () {
+      const { baseDir, project } = yield* makeProjectLookupFixture(true, true);
+      const replacementDir = NodeFS.mkdtempSync(
+        NodePath.join(NodeOS.tmpdir(), "t3-cli-project-lookup-new-state-"),
+      );
+      const error = yield* runCliWithRuntime([
+        "project",
+        "remove",
+        project.id,
+        "--force",
+        "--base-dir",
+        replacementDir,
+      ]).pipe(Effect.flip);
+      assert.include(error.message, "No active project found");
+      assert.include(String(error.cause), "Workspace root does not exist");
+      const original = yield* readPersistedSnapshot(baseDir);
+      assert.isNull(original.projects.find((candidate) => candidate.id === project.id)!.deletedAt);
+      const replacement = yield* readPersistedSnapshot(replacementDir);
+      assert.equal(replacement.projects.length, 0);
+    }),
+  );
+
+  it.effect("renames by ID and stored path, then force removes after the directory is gone", () =>
+    Effect.gen(function* () {
+      const { baseDir, workspaceRoot, project } = yield* makeProjectLookupFixture(true, true);
+      yield* runCliWithRuntime([
+        "project",
+        "rename",
+        project.id,
+        "Renamed by ID",
+        "--base-dir",
+        baseDir,
+      ]);
+      const afterIdRename = yield* readPersistedSnapshot(baseDir);
+      assert.equal(
+        afterIdRename.projects.find((candidate) => candidate.id === project.id)!.title,
+        "Renamed by ID",
+      );
+      yield* runCliWithRuntime([
+        "project",
+        "rename",
+        workspaceRoot,
+        "Renamed by stored path",
+        "--base-dir",
+        baseDir,
+      ]);
+      const afterPathRename = yield* readPersistedSnapshot(baseDir);
+      assert.equal(
+        afterPathRename.projects.find((candidate) => candidate.id === project.id)!.title,
+        "Renamed by stored path",
+      );
+      const error = yield* runCliWithRuntime([
+        "project",
+        "remove",
+        workspaceRoot,
+        "--base-dir",
+        baseDir,
+      ]).pipe(Effect.flip);
+      assert.include(error.message, "cannot be deleted without force=true");
+      yield* runCliWithRuntime([
+        "project",
+        "remove",
+        workspaceRoot,
+        "--force",
+        "--base-dir",
+        baseDir,
+      ]);
+      const after = yield* readPersistedSnapshot(baseDir);
+      assert.isNotNull(after.projects.find((candidate) => candidate.id === project.id)!.deletedAt);
+      assert.isNotNull(
+        after.threads.find((thread) => thread.id === "thread-project-lookup")!.deletedAt,
+      );
+      assert.isFalse(NodeFS.existsSync(workspaceRoot));
+    }),
+  );
+
+  it.effect("preserves normalized paths and distinct symlink project entries", () =>
+    Effect.gen(function* () {
+      const { baseDir, workspaceRoot, project } = yield* makeProjectLookupFixture(false, false);
+      const normalizedInput = `${workspaceRoot}${NodePath.sep}.`;
+      yield* runCliWithRuntime([
+        "project",
+        "rename",
+        normalizedInput,
+        "Normalized",
+        "--base-dir",
+        baseDir,
+      ]);
+      const renamed = yield* readPersistedSnapshot(baseDir);
+      assert.equal(
+        renamed.projects.find((candidate) => candidate.id === project.id)!.title,
+        "Normalized",
+      );
+      const aliasPath = `${workspaceRoot}-alias`;
+      NodeFS.symlinkSync(workspaceRoot, aliasPath, "junction");
+      const error = yield* runCliWithRuntime([
+        "project",
+        "remove",
+        aliasPath,
+        "--force",
+        "--base-dir",
+        baseDir,
+      ]).pipe(Effect.flip);
+      assert.include(error.message, "No active project found");
+      yield* runCliWithRuntime(["project", "add", aliasPath, "--base-dir", baseDir]);
+      const added = yield* readPersistedSnapshot(baseDir);
+      const aliasProject = added.projects.find(
+        (candidate) => candidate.workspaceRoot === aliasPath,
+      )!;
+      assert.notEqual(aliasProject.id, project.id);
+      yield* runCliWithRuntime([
+        "project",
+        "remove",
+        `${aliasPath}${NodePath.sep}.`,
+        "--base-dir",
+        baseDir,
+      ]);
+      const after = yield* readPersistedSnapshot(baseDir);
+      assert.isNotNull(
+        after.projects.find((candidate) => candidate.id === aliasProject.id)!.deletedAt,
+      );
+      assert.isNull(after.projects.find((candidate) => candidate.id === project.id)!.deletedAt);
+      assert.isTrue(NodeFS.existsSync(workspaceRoot));
+    }),
+  );
+});
+
 const withLiveProjectCliServer = <A, E, R>(baseDir: string, run: () => Effect.Effect<A, E, R>) =>
   Effect.gen(function* () {
     const config = yield* makeCliTestServerConfig(baseDir);
diff --git a/apps/server/src/bootstrap.test.ts b/apps/server/src/bootstrap.test.ts
index 05155f32ec4c..d532f71c9fb8 100644
--- a/apps/server/src/bootstrap.test.ts
+++ b/apps/server/src/bootstrap.test.ts
@@ -55,6 +55,24 @@ vi.mock("node:fs", async (importOriginal) => {
   };
 });
 
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+const nullDevice = windowsHost ? "\\\\.\\NUL" : "/dev/null";
+const closeIfOpen = (fd: number) => {
+  try {
+    NodeFS.closeSync(fd);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EBADF") throw error;
+  }
+};
+
+// A successful Windows read streams the inherited fd with autoClose. POSIX
+// reopens the fd through /proc or /dev, so the test still owns the original.
+const openBootstrapInputFd = (filePath: string) =>
+  Effect.acquireRelease(
+    Effect.sync(() => NodeFS.openSync(filePath, "r")),
+    (fd) => (windowsHost ? Effect.void : Effect.sync(() => closeIfOpen(fd))),
+  );
+
 const TestEnvelopeSchema = Schema.Struct({ mode: Schema.String });
 const encodeTestEnvelopeSchema = Schema.encodeEffect(Schema.fromJsonString(TestEnvelopeSchema));
 
@@ -69,10 +87,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
         `${yield* encodeTestEnvelopeSchema({ mode: "desktop" })}\n`,
       );
 
-      const fd = yield* Effect.acquireRelease(
-        Effect.sync(() => NodeFS.openSync(filePath, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
-      );
+      const fd = yield* openBootstrapInputFd(filePath);
 
       const payload = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, { timeoutMs: 100 });
       assertSome(payload, {
@@ -117,7 +132,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
       const filePath = yield* fs.makeTempFileScoped({ prefix: "t3-bootstrap-", suffix: ".ndjson" });
       const fd = yield* Effect.acquireRelease(
         Effect.sync(() => NodeFS.openSync(filePath, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
+        (fd) => Effect.sync(() => closeIfOpen(fd)),
       );
       const fdPath = `/proc/self/fd/${fd}`;
 
@@ -146,7 +161,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
 
   it.effect("returns none when the fd is unavailable", () =>
     Effect.gen(function* () {
-      const fd = NodeFS.openSync("/dev/null", "r");
+      const fd = NodeFS.openSync(nullDevice, "r");
       NodeFS.closeSync(fd);
 
       const payload = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, { timeoutMs: 100 });
@@ -157,8 +172,8 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
   it.effect("preserves fd and cause when stat fails for a non-availability reason", () =>
     Effect.gen(function* () {
       const fd = yield* Effect.acquireRelease(
-        Effect.sync(() => NodeFS.openSync("/dev/null", "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
+        Effect.sync(() => NodeFS.openSync(nullDevice, "r")),
+        (fd) => Effect.sync(() => closeIfOpen(fd)),
       );
 
       fstatSyncInterceptor.failFd = fd;
@@ -183,10 +198,7 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
       const filePath = yield* fs.makeTempFileScoped({ prefix: "t3-bootstrap-", suffix: ".ndjson" });
       yield* fs.writeFileString(filePath, '{"mode":42}\n');
 
-      const fd = yield* Effect.acquireRelease(
-        Effect.sync(() => NodeFS.openSync(filePath, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
-      );
+      const fd = yield* openBootstrapInputFd(filePath);
       const error = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, {
         timeoutMs: 100,
       }).pipe(Effect.flip);
@@ -201,40 +213,43 @@ it.layer(NodeServices.layer)("readBootstrapEnvelope", (it) => {
     }),
   );
 
-  it.effect("returns none when the bootstrap read times out before any value arrives", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-bootstrap-" });
-      const fifoPath = NodePath.join(tempDir, "bootstrap.pipe");
-
-      yield* Effect.sync(() => NodeChildProcess.execFileSync("mkfifo", [fifoPath]));
-
-      const _writer = yield* Effect.acquireRelease(
-        Effect.sync(() =>
-          NodeChildProcess.spawn("sh", ["-c", 'exec 3>"$1"; sleep 60', "sh", fifoPath], {
-            stdio: ["ignore", "ignore", "ignore"],
-          }),
-        ),
-        (writer) =>
-          Effect.sync(() => {
-            writer.kill("SIGKILL");
-          }),
-      );
+  // Needs a FIFO, which mkfifo creates; Windows has neither.
+  it.effect.skipIf(windowsHost)(
+    "returns none when the bootstrap read times out before any value arrives",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-bootstrap-" });
+        const fifoPath = NodePath.join(tempDir, "bootstrap.pipe");
+
+        yield* Effect.sync(() => NodeChildProcess.execFileSync("mkfifo", [fifoPath]));
+
+        const _writer = yield* Effect.acquireRelease(
+          Effect.sync(() =>
+            NodeChildProcess.spawn("sh", ["-c", 'exec 3>"$1"; sleep 60', "sh", fifoPath], {
+              stdio: ["ignore", "ignore", "ignore"],
+            }),
+          ),
+          (writer) =>
+            Effect.sync(() => {
+              writer.kill("SIGKILL");
+            }),
+        );
 
-      const fd = yield* Effect.acquireRelease(
-        Effect.sync(() => NodeFS.openSync(fifoPath, "r")),
-        (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
-      );
+        const fd = yield* Effect.acquireRelease(
+          Effect.sync(() => NodeFS.openSync(fifoPath, "r")),
+          (fd) => Effect.sync(() => closeIfOpen(fd)),
+        );
 
-      const fiber = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, {
-        timeoutMs: 100,
-      }).pipe(Effect.forkScoped);
+        const fiber = yield* readBootstrapEnvelope(TestEnvelopeSchema, fd, {
+          timeoutMs: 100,
+        }).pipe(Effect.forkScoped);
 
-      yield* Effect.yieldNow;
-      yield* TestClock.adjust(Duration.millis(100));
+        yield* Effect.yieldNow;
+        yield* TestClock.adjust(Duration.millis(100));
 
-      const payload = yield* Fiber.join(fiber);
-      assertNone(payload);
-    }).pipe(Effect.provide(TestClock.layer())),
+        const payload = yield* Fiber.join(fiber);
+        assertNone(payload);
+      }).pipe(Effect.provide(TestClock.layer())),
   );
 });
diff --git a/apps/server/src/checkpointing/CheckpointDiffQuery.test.ts b/apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
index cd4309057935..d05ca5ec854a 100644
--- a/apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
+++ b/apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
@@ -90,6 +90,7 @@ describe("CheckpointDiffQuery.layer", () => {
             getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
             getProjectShellById: () => Effect.succeed(Option.none()),
             getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+            getImportedAgentSessionSources: () => Effect.die("unused"),
             getThreadCheckpointContext: () =>
               Effect.sync(() => {
                 getThreadCheckpointContextCalls += 1;
@@ -107,6 +108,7 @@ describe("CheckpointDiffQuery.layer", () => {
                   toCheckpointRef,
                 });
               }),
+            getThreadRuntimeContext: () => Effect.die("unused"),
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
@@ -201,8 +203,10 @@ describe("CheckpointDiffQuery.layer", () => {
             getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
             getProjectShellById: () => Effect.succeed(Option.none()),
             getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+            getImportedAgentSessionSources: () => Effect.die("unused"),
             getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
             getFullThreadDiffContext: () => Effect.die("unused"),
+            getThreadRuntimeContext: () => Effect.die("unused"),
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
@@ -287,8 +291,10 @@ describe("CheckpointDiffQuery.layer", () => {
             getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
             getProjectShellById: () => Effect.succeed(Option.none()),
             getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+            getImportedAgentSessionSources: () => Effect.die("unused"),
             getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
             getFullThreadDiffContext: () => Effect.die("unused"),
+            getThreadRuntimeContext: () => Effect.die("unused"),
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
@@ -358,8 +364,10 @@ describe("CheckpointDiffQuery.layer", () => {
             getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
             getProjectShellById: () => Effect.succeed(Option.none()),
             getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+            getImportedAgentSessionSources: () => Effect.die("unused"),
             getThreadCheckpointContext: () => Effect.succeed(Option.some(threadCheckpointContext)),
             getFullThreadDiffContext: () => Effect.die("unused"),
+            getThreadRuntimeContext: () => Effect.die("unused"),
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
@@ -414,8 +422,10 @@ describe("CheckpointDiffQuery.layer", () => {
             getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
             getProjectShellById: () => Effect.succeed(Option.none()),
             getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+            getImportedAgentSessionSources: () => Effect.die("unused"),
             getThreadCheckpointContext: () => Effect.succeed(Option.none()),
             getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+            getThreadRuntimeContext: () => Effect.die("unused"),
             getThreadShellById: () => Effect.succeed(Option.none()),
             getThreadDetailById: () => Effect.succeed(Option.none()),
             getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
diff --git a/apps/server/src/checkpointing/CheckpointStore.test.ts b/apps/server/src/checkpointing/CheckpointStore.test.ts
index 2f46858986aa..5a9b5cc5d6b0 100644
--- a/apps/server/src/checkpointing/CheckpointStore.test.ts
+++ b/apps/server/src/checkpointing/CheckpointStore.test.ts
@@ -4,6 +4,7 @@ import * as NodePath from "node:path";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
 import { ThreadId, type VcsError } from "@t3tools/contracts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
@@ -12,6 +13,7 @@ import * as Scope from "effect/Scope";
 import { describe, expect } from "vite-plus/test";
 
 import { checkpointRefForThreadTurn } from "./Utils.ts";
+import { parseTurnDiffFilesFromNumstat } from "./Diffs.ts";
 import * as CheckpointStore from "./CheckpointStore.ts";
 import * as VcsDriverRegistry from "../vcs/VcsDriverRegistry.ts";
 import * as VcsProcess from "../vcs/VcsProcess.ts";
@@ -250,6 +252,182 @@ it.layer(TestLayer)("CheckpointStore.layer", (it) => {
         expect(whitespaceIgnoredDiff).toContain("+        <div>");
         expect(whitespaceIgnoredDiff).not.toContain("-      <h1>Title</h1>");
         expect(whitespaceIgnoredDiff).not.toContain("+          <h1>Title</h1>");
+
+        for (const ignoreWhitespace of [false, true]) {
+          const numstat = yield* checkpointStore.diffCheckpoints({
+            cwd: tmp,
+            fromCheckpointRef,
+            toCheckpointRef,
+            ignoreWhitespace,
+            format: "numstat",
+          });
+          expect(parseTurnDiffFilesFromNumstat(numstat)).toEqual([
+            {
+              path: "Component.tsx",
+              additions: ignoreWhitespace ? 4 : 6,
+              deletions: ignoreWhitespace ? 0 : 2,
+            },
+          ]);
+        }
+      }),
+    );
+  });
+
+  describe("checkpoint file summaries", () => {
+    it.effect("counts changes whose full patch exceeds the output limit", () =>
+      Effect.gen(function* () {
+        const tmp = yield* makeTmpDir();
+        yield* initRepoWithCommit(tmp);
+        const checkpointStore = yield* CheckpointStore.CheckpointStore;
+        const threadId = ThreadId.make("large-checkpoint-summary");
+        const fromCheckpointRef = checkpointRefForThreadTurn(threadId, 0);
+        const toCheckpointRef = checkpointRefForThreadTurn(threadId, 1);
+        const filePath = NodePath.join(tmp, "README.md");
+        const lineCount = 20_000;
+        yield* writeTextFile(filePath, `${"before".repeat(50)}\n`.repeat(lineCount));
+        yield* checkpointStore.captureCheckpoint({ cwd: tmp, checkpointRef: fromCheckpointRef });
+        yield* writeTextFile(filePath, `${"after".repeat(60)}\n`.repeat(lineCount));
+        yield* checkpointStore.captureCheckpoint({ cwd: tmp, checkpointRef: toCheckpointRef });
+
+        const numstat = yield* checkpointStore.diffCheckpoints({
+          cwd: tmp,
+          fromCheckpointRef,
+          toCheckpointRef,
+          ignoreWhitespace: false,
+          format: "numstat",
+        });
+
+        expect(parseTurnDiffFilesFromNumstat(numstat)).toEqual([
+          { path: "README.md", additions: lineCount, deletions: lineCount },
+        ]);
+        expect(numstat.length).toBeLessThan(100);
+      }),
+    );
+
+    it.effect("preserves file paths and turn ranges without changing the user index", () =>
+      Effect.gen(function* () {
+        const tmp = yield* makeTmpDir();
+        yield* initRepoWithCommit(tmp);
+        yield* git(tmp, ["config", "diff.renames", "copies"]);
+        const fileSystem = yield* FileSystem.FileSystem;
+        const checkpointStore = yield* CheckpointStore.CheckpointStore;
+        const threadId = ThreadId.make("checkpoint-summary-paths");
+        const baseline = checkpointRefForThreadTurn(threadId, 0);
+        const firstTurn = checkpointRefForThreadTurn(threadId, 1);
+        const secondTurn = checkpointRefForThreadTurn(threadId, 2);
+        const copiedText = Array.from({ length: 20 }, (_, index) => `copy line ${index}\n`).join(
+          "",
+        );
+        const platform = yield* HostProcessPlatform;
+        const renamedPath = platform === "win32" ? "renamed café.txt" : "renamed\tcafé\nname.txt";
+        const addedPath = platform === "win32" ? "new café.txt" : "new\tfile\n名.txt";
+        for (const [path, contents] of Object.entries({
+          "copy-source.txt": copiedText,
+          "deleted.txt": "delete me\n",
+          "rename-old.txt": "before\nkeep one\nkeep two\nkeep three\n",
+          "binary.bin": "\0before",
+        })) {
+          yield* writeTextFile(NodePath.join(tmp, path), contents);
+        }
+        yield* checkpointStore.captureCheckpoint({ cwd: tmp, checkpointRef: baseline });
+
+        yield* fileSystem.rename(
+          NodePath.join(tmp, "rename-old.txt"),
+          NodePath.join(tmp, renamedPath),
+        );
+        yield* fileSystem.remove(NodePath.join(tmp, "deleted.txt"));
+        for (const [path, contents] of Object.entries({
+          "copy-source.txt": `${copiedText}one more\n`,
+          "copied.txt": copiedText,
+          [renamedPath]: "after\nkeep one\nkeep two\nkeep three\n",
+          "binary.bin": "\0after",
+          "empty.txt": "",
+          [addedPath]: "first\nsecond\n",
+        })) {
+          yield* writeTextFile(NodePath.join(tmp, path), contents);
+        }
+        yield* checkpointStore.captureCheckpoint({ cwd: tmp, checkpointRef: firstTurn });
+        const userIndex = yield* fileSystem.readFile(NodePath.join(tmp, ".git/index"));
+        const input = {
+          cwd: tmp,
+          fromCheckpointRef: baseline,
+          toCheckpointRef: firstTurn,
+          ignoreWhitespace: false,
+          format: "numstat" as const,
+        };
+        const firstSummary = parseTurnDiffFilesFromNumstat(
+          yield* checkpointStore.diffCheckpoints(input),
+        );
+        const expectedFiles = [
+          { path: "binary.bin", additions: 0, deletions: 0 },
+          { path: "copied.txt", additions: 0, deletions: 0 },
+          { path: "copy-source.txt", additions: 1, deletions: 0 },
+          { path: "deleted.txt", additions: 0, deletions: 1 },
+          { path: "empty.txt", additions: 0, deletions: 0 },
+          { path: addedPath, additions: 2, deletions: 0 },
+          { path: renamedPath, additions: 1, deletions: 1 },
+        ].toSorted((left, right) => left.path.localeCompare(right.path));
+        expect(firstSummary).toEqual(expectedFiles);
+
+        yield* fileSystem.remove(NodePath.join(tmp, "empty.txt"));
+        yield* writeTextFile(NodePath.join(tmp, "copy-source.txt"), "replacement\n");
+        yield* checkpointStore.captureCheckpoint({ cwd: tmp, checkpointRef: secondTurn });
+        const secondSummary = parseTurnDiffFilesFromNumstat(
+          yield* checkpointStore.diffCheckpoints({
+            ...input,
+            fromCheckpointRef: firstTurn,
+            toCheckpointRef: secondTurn,
+          }),
+        );
+        expect(secondSummary).toEqual([
+          { path: "copy-source.txt", additions: 1, deletions: 21 },
+          { path: "empty.txt", additions: 0, deletions: 0 },
+        ]);
+
+        const inclusiveSummary = parseTurnDiffFilesFromNumstat(
+          yield* checkpointStore.diffCheckpoints({ ...input, toCheckpointRef: secondTurn }),
+        );
+        expect(inclusiveSummary).toEqual(
+          expectedFiles
+            .filter((file) => file.path !== "empty.txt")
+            .map((file) =>
+              file.path === "copy-source.txt" ? { ...file, additions: 1, deletions: 20 } : file,
+            ),
+        );
+        expect(
+          yield* checkpointStore.diffCheckpoints({ ...input, toCheckpointRef: baseline }),
+        ).toBe("");
+        expect(yield* fileSystem.readFile(NodePath.join(tmp, ".git/index"))).toEqual(userIndex);
+      }),
+    );
+
+    it.effect("uses HEAD for a missing baseline only when requested", () =>
+      Effect.gen(function* () {
+        const tmp = yield* makeTmpDir();
+        yield* initRepoWithCommit(tmp);
+        const checkpointStore = yield* CheckpointStore.CheckpointStore;
+        const threadId = ThreadId.make("checkpoint-summary-fallback");
+        const fromCheckpointRef = checkpointRefForThreadTurn(threadId, 0);
+        const toCheckpointRef = checkpointRefForThreadTurn(threadId, 1);
+        yield* writeTextFile(NodePath.join(tmp, "README.md"), "changed\n");
+        yield* checkpointStore.captureCheckpoint({ cwd: tmp, checkpointRef: toCheckpointRef });
+        const input = {
+          cwd: tmp,
+          fromCheckpointRef,
+          toCheckpointRef,
+          ignoreWhitespace: false,
+          format: "numstat" as const,
+        };
+
+        const error = yield* Effect.flip(checkpointStore.diffCheckpoints(input));
+        expect(error._tag).toBe("VcsProcessExitError");
+        const numstat = yield* checkpointStore.diffCheckpoints({
+          ...input,
+          fallbackFromToHead: true,
+        });
+        expect(parseTurnDiffFilesFromNumstat(numstat)).toEqual([
+          { path: "README.md", additions: 1, deletions: 1 },
+        ]);
       }),
     );
   });
diff --git a/apps/server/src/checkpointing/CheckpointStore.ts b/apps/server/src/checkpointing/CheckpointStore.ts
index f13aa4572c17..f1cc596b209d 100644
--- a/apps/server/src/checkpointing/CheckpointStore.ts
+++ b/apps/server/src/checkpointing/CheckpointStore.ts
@@ -39,6 +39,7 @@ export interface DiffCheckpointsInput {
   readonly toCheckpointRef: CheckpointRef;
   readonly fallbackFromToHead?: boolean;
   readonly ignoreWhitespace: boolean;
+  readonly format?: "patch" | "numstat";
 }
 
 export interface DeleteCheckpointRefsInput {
@@ -77,8 +78,9 @@ export class CheckpointStore extends Context.Service<
     ) => Effect.Effect<boolean, CheckpointStoreError>;
 
     /**
-     * Compute a patch diff between two checkpoint refs.
+     * Compute a diff between two checkpoint refs. Defaults to a full patch.
      *
+     * Numstat output has NUL-delimited paths for file summaries.
      * Can optionally treat a missing "from" ref as `HEAD`.
      */
     readonly diffCheckpoints: (
diff --git a/apps/server/src/checkpointing/Diffs.test.ts b/apps/server/src/checkpointing/Diffs.test.ts
index f27f5ecb8dfb..6b7f1a875690 100644
--- a/apps/server/src/checkpointing/Diffs.test.ts
+++ b/apps/server/src/checkpointing/Diffs.test.ts
@@ -1,68 +1,54 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { parseTurnDiffFilesFromUnifiedDiff } from "./Diffs.ts";
+import { parseTurnDiffFilesFromNumstat } from "./Diffs.ts";
 
-describe("parseTurnDiffFilesFromUnifiedDiff", () => {
-  it("returns empty list for empty diff", () => {
-    expect(parseTurnDiffFilesFromUnifiedDiff("")).toEqual([]);
+describe("parseTurnDiffFilesFromNumstat", () => {
+  it("returns an empty list when no files changed", () => {
+    expect(parseTurnDiffFilesFromNumstat("")).toEqual([]);
   });
 
-  it("parses per-file additions and deletions", () => {
-    const diff = [
-      "diff --git a/a.txt b/a.txt",
-      "index 1111111..2222222 100644",
-      "--- a/a.txt",
-      "+++ b/a.txt",
-      "@@ -1,2 +1,3 @@",
-      " one",
-      "-two",
-      "+two updated",
-      "+three",
-      "diff --git a/src/b.ts b/src/b.ts",
-      "index 3333333..4444444 100644",
-      "--- a/src/b.ts",
-      "+++ b/src/b.ts",
-      "@@ -3,2 +3,0 @@",
-      "-old",
-      "-stale",
-      "",
-    ].join("\n");
-
-    expect(parseTurnDiffFilesFromUnifiedDiff(diff)).toEqual([
+  it("sorts files and preserves addition and deletion counts", () => {
+    const numstat = ["0\t2\tsrc/b.ts", "2\t1\ta.txt", ""].join("\0");
+    expect(parseTurnDiffFilesFromNumstat(numstat)).toEqual([
       { path: "a.txt", additions: 2, deletions: 1 },
       { path: "src/b.ts", additions: 0, deletions: 2 },
     ]);
   });
 
-  it("parses rename-only diffs with zero line changes", () => {
-    const diff = [
-      "diff --git a/src/old.ts b/src/new.ts",
-      "similarity index 100%",
-      "rename from src/old.ts",
-      "rename to src/new.ts",
+  it("uses destination paths for renames and copies", () => {
+    const numstat = [
+      "0\t0\t",
+      "src/old.ts",
+      "src/new.ts",
+      "2\t1\t",
+      "src/source.ts",
+      "src/copied.ts",
+      "1\t0\tother.ts",
       "",
-    ].join("\n");
+    ].join("\0");
 
-    expect(parseTurnDiffFilesFromUnifiedDiff(diff)).toEqual([
+    expect(parseTurnDiffFilesFromNumstat(numstat)).toEqual([
+      { path: "other.ts", additions: 1, deletions: 0 },
+      { path: "src/copied.ts", additions: 2, deletions: 1 },
       { path: "src/new.ts", additions: 0, deletions: 0 },
     ]);
   });
 
-  it("normalizes CRLF input before parsing", () => {
-    const diff = [
-      "diff --git a/a.txt b/a.txt",
-      "index 1111111..2222222 100644",
-      "--- a/a.txt",
-      "+++ b/a.txt",
-      "@@ -1 +1,2 @@",
-      "-one",
-      "+one updated",
-      "+two",
-      "",
-    ].join("\r\n");
+  it("keeps binary files and empty files with zero line changes", () => {
+    const numstat = ["-\t-\timage.png", "0\t0\tempty.txt", ""].join("\0");
+    expect(parseTurnDiffFilesFromNumstat(numstat)).toEqual([
+      { path: "empty.txt", additions: 0, deletions: 0 },
+      { path: "image.png", additions: 0, deletions: 0 },
+    ]);
+  });
 
-    expect(parseTurnDiffFilesFromUnifiedDiff(diff)).toEqual([
-      { path: "a.txt", additions: 2, deletions: 1 },
+  it("preserves Unicode, tabs, line endings, and spaces in paths", () => {
+    const path = " café\tline\r\nname.txt ";
+    const numstat = `3\t2\t\0old\tname\n.txt\0${path}\0`;
+
+    expect(parseTurnDiffFilesFromNumstat(numstat)).toEqual([{ path, additions: 3, deletions: 2 }]);
+    expect(parseTurnDiffFilesFromNumstat(`1\t0\t${path}\0`)).toEqual([
+      { path, additions: 1, deletions: 0 },
     ]);
   });
 });
diff --git a/apps/server/src/checkpointing/Diffs.ts b/apps/server/src/checkpointing/Diffs.ts
index 0eeee1b6f3f4..b7951009118e 100644
--- a/apps/server/src/checkpointing/Diffs.ts
+++ b/apps/server/src/checkpointing/Diffs.ts
@@ -1,27 +1,33 @@
-import { parsePatchFiles } from "@pierre/diffs/utils/parsePatchFiles";
-
 export interface TurnDiffFileSummary {
   readonly path: string;
   readonly additions: number;
   readonly deletions: number;
 }
 
-export function parseTurnDiffFilesFromUnifiedDiff(
-  diff: string,
-): ReadonlyArray<TurnDiffFileSummary> {
-  const normalized = diff.replace(/\r\n/g, "\n").trim();
-  if (normalized.length === 0) {
-    return [];
-  }
+/** Reads Git's NUL-delimited numstat output without decoding display paths. */
+export function parseTurnDiffFilesFromNumstat(numstat: string): ReadonlyArray<TurnDiffFileSummary> {
+  const records = numstat.split("\0");
+  const files: TurnDiffFileSummary[] = [];
+
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index]!;
+    const counts = /^(\d+|-)\t(\d+|-)\t/.exec(record);
+    if (!counts) continue;
 
-  const parsedPatches = parsePatchFiles(normalized);
-  const files = parsedPatches.flatMap((patch) =>
-    patch.files.map((file) => ({
-      path: file.name,
-      additions: file.hunks.reduce((total, hunk) => total + hunk.additionLines, 0),
-      deletions: file.hunks.reduce((total, hunk) => total + hunk.deletionLines, 0),
-    })),
-  );
+    let path = record.slice(counts[0].length);
+    if (path.length === 0) {
+      // Renames and copies use two more records: the source and destination.
+      path = records[index + 2] ?? "";
+      index += 2;
+    }
+    if (path.length === 0) continue;
+
+    files.push({
+      path,
+      additions: counts[1] === "-" ? 0 : Number(counts[1]),
+      deletions: counts[2] === "-" ? 0 : Number(counts[2]),
+    });
+  }
 
   return files.toSorted((left, right) => left.path.localeCompare(right.path));
 }
diff --git a/apps/server/src/cli/config.test.ts b/apps/server/src/cli/config.test.ts
index def63b61fafe..2267a5cb1cc9 100644
--- a/apps/server/src/cli/config.test.ts
+++ b/apps/server/src/cli/config.test.ts
@@ -60,7 +60,16 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
     yield* fs.writeFileString(filePath, `${encoded}\n`);
     return yield* Effect.acquireRelease(
       Effect.sync(() => NodeFS.openSync(filePath, "r")),
-      (fd) => Effect.sync(() => NodeFS.closeSync(fd)),
+      // Without a /proc or /dev/fd path to reopen, the reader consumes the fd
+      // itself (autoClose), so on Windows it is already closed here.
+      (fd) =>
+        Effect.sync(() => {
+          try {
+            NodeFS.closeSync(fd);
+          } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "EBADF") throw error;
+          }
+        }),
     );
   });
 
@@ -281,13 +290,15 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
 
   it.effect("uses bootstrap envelope values as fallbacks when flags and env are absent", () =>
     Effect.gen(function* () {
-      const { join } = yield* Path.Path;
-      const baseDir = "/tmp/t3-bootstrap-home";
+      const { join, resolve } = yield* Path.Path;
+      // The resolver absolutises the configured home, so the expectation must
+      // carry the host's drive on Windows.
+      const baseDir = resolve("/tmp/t3-bootstrap-home");
       const fd = yield* openBootstrapFd(
         makeDesktopBootstrap({
           port: 4888,
           host: "127.0.0.2",
-          t3Home: baseDir,
+          t3Home: "/tmp/t3-bootstrap-home",
           noBrowser: true,
           desktopBootstrapToken: "desktop-token",
           desktopTelemetryFd: 4,
diff --git a/apps/server/src/cli/connect.test.ts b/apps/server/src/cli/connect.test.ts
index 1e0c88c24e84..f3cc88d1b58a 100644
--- a/apps/server/src/cli/connect.test.ts
+++ b/apps/server/src/cli/connect.test.ts
@@ -13,31 +13,11 @@ import * as Terminal from "effect/Terminal";
 import * as BootService from "../cloud/bootService.ts";
 import {
   acquireRelayClientForLink,
-  formatHeadlessAuthorizationPrompt,
-  formatRelayClientReady,
   headlessSessionConfig,
-  isPublishAgentActivityEnabledValue,
   reportCloudDisconnectResults,
 } from "./connect.ts";
 import { recoverServiceOnboardingOffer } from "./service.ts";
 
-it("explains how to complete headless authorization", () => {
-  assert.equal(
-    formatHeadlessAuthorizationPrompt("https://example.test/connect"),
-    [
-      "Headless authorization",
-      "Open this URL on a device with a browser:",
-      "  https://example.test/connect",
-      "",
-      "After signing in, return here and enter the code shown in your browser.",
-    ].join("\n"),
-  );
-});
-
-it("formats relay readiness without printing its installation path", () => {
-  assert.equal(formatRelayClientReady("2026.5.2"), "✓ Relay client ready · cloudflared 2026.5.2");
-});
-
 const readHeadlessSessionConfig = (env: Record<string, string>) =>
   headlessSessionConfig.pipe(Effect.provide(ConfigProvider.layer(ConfigProvider.fromEnv({ env }))));
 
@@ -209,10 +189,3 @@ it.effect("keeps disconnect causes in structured logs and out of console warning
     ),
   );
 });
-
-it("treats only the literal 'true' as publish-enabled", () => {
-  assert.equal(isPublishAgentActivityEnabledValue("true"), true);
-  assert.equal(isPublishAgentActivityEnabledValue("false"), false);
-  assert.equal(isPublishAgentActivityEnabledValue(null), false);
-  assert.equal(isPublishAgentActivityEnabledValue("TRUE"), false);
-});
diff --git a/apps/server/src/cli/connect.ts b/apps/server/src/cli/connect.ts
index 25cfb18f3402..b7c78e5ea68b 100644
--- a/apps/server/src/cli/connect.ts
+++ b/apps/server/src/cli/connect.ts
@@ -86,7 +86,7 @@ const promptForOutOfBandOAuthCode = Effect.fn("cloud.cli.prompt_for_out_of_band_
   },
 );
 
-export function formatHeadlessAuthorizationPrompt(authorizeUrl: string): string {
+function formatHeadlessAuthorizationPrompt(authorizeUrl: string): string {
   return [
     "Headless authorization",
     "Open this URL on a device with a browser:",
@@ -144,10 +144,6 @@ function stringToBytes(value: string): Uint8Array {
   return new TextEncoder().encode(value);
 }
 
-export function isPublishAgentActivityEnabledValue(value: string | null): boolean {
-  return isAgentActivityPublishingEnabledValue(value);
-}
-
 interface CloudCliStatus {
   readonly desired: boolean;
   readonly authenticated: boolean;
@@ -464,7 +460,7 @@ const runCloudCommand = Effect.fn("cloud.cli.run_cloud_command")(function* <A, E
 
 const connectedAs = (identity: string | null): string => (identity ? ` as ${identity}` : "");
 
-export function formatRelayClientReady(version: string): string {
+function formatRelayClientReady(version: string): string {
   return `✓ Relay client ready · cloudflared ${version}`;
 }
 
@@ -573,7 +569,7 @@ const connectStatusCommand = Command.make("status", {
           linked: Option.isSome(cloudUserId),
           cloudUserId: Option.isSome(cloudUserId) ? bytesToString(cloudUserId.value) : null,
           relayUrl: Option.isSome(relayUrl) ? bytesToString(relayUrl.value) : null,
-          publishAgentActivity: isPublishAgentActivityEnabledValue(
+          publishAgentActivity: isAgentActivityPublishingEnabledValue(
             Option.isSome(publishAgentActivity) ? bytesToString(publishAgentActivity.value) : null,
           ),
           relayClient: executable,
diff --git a/apps/server/src/cli/invocation.test.ts b/apps/server/src/cli/invocation.test.ts
index c01a2caa49b5..370a8977fc4c 100644
--- a/apps/server/src/cli/invocation.test.ts
+++ b/apps/server/src/cli/invocation.test.ts
@@ -1,49 +1,62 @@
 import { assert, it } from "@effect/vitest";
 
-import { detectCliRunner, formatCliCommand, suggestedPackageSpec } from "./invocation.ts";
+import { formatCliCommand } from "./invocation.ts";
 
-it("detects package runners from their cache entry paths", () => {
-  assert.equal(detectCliRunner("/home/theo/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs"), "npx");
-  assert.equal(
-    detectCliRunner(
+it("formats package runner commands from their cache entry paths", () => {
+  for (const [entryPath, expected] of [
+    ["/home/theo/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs", "npx t3 serve"],
+    [
       "C:\\Users\\theo\\AppData\\Local\\npm-cache\\_npx\\abc\\node_modules\\t3\\dist\\bin.mjs",
-    ),
-    "npx",
-  );
-  assert.equal(
-    detectCliRunner("/home/theo/.cache/pnpm/dlx/abc/node_modules/t3/dist/bin.mjs"),
-    "pnpm dlx",
-  );
-  assert.equal(
-    detectCliRunner("/home/theo/.local/share/pnpm/.pnpm/dlx/abc/node_modules/t3/dist/bin.mjs"),
-    "pnpm dlx",
-  );
-  assert.equal(
-    detectCliRunner(
+      "npx t3 serve",
+    ],
+    ["/home/theo/.cache/pnpm/dlx/abc/node_modules/t3/dist/bin.mjs", "pnpm dlx t3 serve"],
+    [
+      "/home/theo/.local/share/pnpm/.pnpm/dlx/abc/node_modules/t3/dist/bin.mjs",
+      "pnpm dlx t3 serve",
+    ],
+    [
       "C:\\Users\\theo\\AppData\\Local\\pnpm-cache\\dlx\\abc\\node_modules\\t3\\dist\\bin.mjs",
-    ),
-    "pnpm dlx",
-  );
-  assert.equal(detectCliRunner("/home/theo/.bun/install/cache/t3@0.0.31/dist/bin.mjs"), "bunx");
-  assert.equal(detectCliRunner("/tmp/bunx-1000-t3@latest/node_modules/t3/dist/bin.mjs"), "bunx");
-  assert.equal(
-    detectCliRunner(
+      "pnpm dlx t3 serve",
+    ],
+    ["/home/theo/.bun/install/cache/t3@0.0.31/dist/bin.mjs", "bunx t3 serve"],
+    ["/tmp/bunx-1000-t3@latest/node_modules/t3/dist/bin.mjs", "bunx t3 serve"],
+    [
       "C:\\Users\\theo\\AppData\\Local\\Temp\\bunx-0-t3@latest\\node_modules\\t3\\dist\\bin.mjs",
-    ),
-    "bunx",
-  );
+      "bunx t3 serve",
+    ],
+  ] as const) {
+    assert.equal(formatCliCommand({ subcommand: "serve", entryPath, version: "0.0.31" }), expected);
+  }
 });
 
 it("treats stable installs as direct invocations", () => {
-  assert.isNull(detectCliRunner("/usr/local/lib/node_modules/t3/dist/bin.mjs"));
-  assert.isNull(detectCliRunner("/home/theo/Code/work/t3code/apps/server/dist/bin.mjs"));
-  assert.isNull(detectCliRunner("/home/theo/.t3/runtime/0.0.31/node_modules/t3/dist/bin.mjs"));
-  assert.isNull(detectCliRunner(""));
+  for (const entryPath of [
+    "/usr/local/lib/node_modules/t3/dist/bin.mjs",
+    "/home/theo/Code/work/t3code/apps/server/dist/bin.mjs",
+    "/home/theo/.t3/runtime/0.0.31/node_modules/t3/dist/bin.mjs",
+    "",
+  ]) {
+    assert.equal(
+      formatCliCommand({ subcommand: "serve", entryPath, version: "0.0.31" }),
+      "t3 serve",
+    );
+  }
 });
 
 it("re-suggests the nightly channel only for nightly builds", () => {
-  assert.equal(suggestedPackageSpec("0.0.31-nightly.20260729"), "t3@nightly");
-  assert.equal(suggestedPackageSpec("0.0.31"), "t3");
+  for (const [version, expected] of [
+    ["0.0.31-nightly.20260729", "npx t3@nightly serve"],
+    ["0.0.31", "npx t3 serve"],
+  ] as const) {
+    assert.equal(
+      formatCliCommand({
+        subcommand: "serve",
+        entryPath: "/home/theo/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs",
+        version,
+      }),
+      expected,
+    );
+  }
 });
 
 it("formats serve suggestions to match the launching command", () => {
diff --git a/apps/server/src/cli/invocation.ts b/apps/server/src/cli/invocation.ts
index e1b03552948d..55f5b66ad9dd 100644
--- a/apps/server/src/cli/invocation.ts
+++ b/apps/server/src/cli/invocation.ts
@@ -18,7 +18,7 @@ export type CliRunner = "npx" | "pnpm dlx" | "bunx";
  * Global installs and repo checkouts match none of these and return null.
  * Detection is best-effort; callers must fail closed to a plain `t3` command.
  */
-export function detectCliRunner(entryPath: string): CliRunner | null {
+function detectCliRunner(entryPath: string): CliRunner | null {
   const path = entryPath.replaceAll("\\", "/");
   if (path.includes("/_npx/")) {
     return "npx";
@@ -42,7 +42,7 @@ export function detectCliRunner(entryPath: string): CliRunner | null {
  * from the running version: nightly builds re-suggest the nightly channel,
  * anything else suggests the bare package.
  */
-export function suggestedPackageSpec(version: string): string {
+function suggestedPackageSpec(version: string): string {
   return version.includes("-nightly.") ? "t3@nightly" : "t3";
 }
 
diff --git a/apps/server/src/cli/project.ts b/apps/server/src/cli/project.ts
index 6ae40c773a00..3ef92d438582 100644
--- a/apps/server/src/cli/project.ts
+++ b/apps/server/src/cli/project.ts
@@ -282,10 +282,10 @@ const findActiveProjectTarget = Effect.fn("findActiveProjectTarget")(function* (
   const normalizedWorkspaceRoot =
     normalizedWorkspaceRootResult._tag === "Success" ? normalizedWorkspaceRootResult.success : null;
 
-  const exactWorkspaceMatch =
-    normalizedWorkspaceRoot === null
-      ? undefined
-      : activeProjects.find((project) => project.workspaceRoot === normalizedWorkspaceRoot);
+  // A stored workspace path still identifies its project after the directory is gone.
+  const exactWorkspaceMatch = activeProjects.find(
+    (project) => project.workspaceRoot === (normalizedWorkspaceRoot ?? trimmedIdentifier),
+  );
 
   const resolved = exactWorkspaceMatch;
   if (!resolved) {
diff --git a/apps/server/src/cli/theme.test.ts b/apps/server/src/cli/theme.test.ts
index d3dd69b94727..7935f5e51b42 100644
--- a/apps/server/src/cli/theme.test.ts
+++ b/apps/server/src/cli/theme.test.ts
@@ -13,6 +13,12 @@ import * as TestConsole from "effect/testing/TestConsole";
 import { Command } from "effect/unstable/cli";
 
 import { cli } from "../bin.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+
+// These force a failure with chmod, which Windows ignores for directories and
+// cannot use to make a file unreadable, so the failure never happens there.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 
 const runCli = (args: ReadonlyArray<string>) =>
   Command.runWith(cli, { version: "0.0.0" })(args).pipe(
@@ -160,7 +166,7 @@ describe("t3 theme", () => {
   // rolled back rather than left mutating the environment's theme set. The
   // userdata directory is made read-only while themes stays writable, so the
   // failure lands after the publish -- the case the rollback exists for.
-  it.effect("rolls back a publish when the default cannot be written", () =>
+  it.effect.skipIf(windowsHost)("rolls back a publish when the default cannot be written", () =>
     Effect.gen(function* () {
       const baseDir = makeBaseDir();
       writeSettings(baseDir, {});
@@ -185,27 +191,29 @@ describe("t3 theme", () => {
 
   // A symlink is a normal way to hand this command a theme -- desktop hooks
   // symlink the current palette -- so the source is resolved, not refused.
-  it.effect("publishes a theme file through a symlinked source path", () =>
-    Effect.gen(function* () {
-      const baseDir = makeBaseDir();
-      const realFile = NodePath.join(baseDir, "real-nightfall.json");
-      NodeFS.writeFileSync(realFile, NIGHTFALL_THEME_JSON);
-      const linkPath = NodePath.join(baseDir, "nightfall.json");
-      NodeFS.symlinkSync(realFile, linkPath);
-
-      yield* runCli(["theme", "set", linkPath, "--base-dir", baseDir]);
-
-      assert.equal(
-        NodeFS.existsSync(NodePath.join(baseDir, "userdata", "themes", "nightfall.json")),
-        true,
-      );
-      assert.equal(readSettings(baseDir).defaultTheme, "nightfall");
-    }),
+  it.effect.skipIf(!symlinksSupported)(
+    "publishes a theme file through a symlinked source path",
+    () =>
+      Effect.gen(function* () {
+        const baseDir = makeBaseDir();
+        const realFile = NodePath.join(baseDir, "real-nightfall.json");
+        NodeFS.writeFileSync(realFile, NIGHTFALL_THEME_JSON);
+        const linkPath = NodePath.join(baseDir, "nightfall.json");
+        NodeFS.symlinkSync(realFile, linkPath);
+
+        yield* runCli(["theme", "set", linkPath, "--base-dir", baseDir]);
+
+        assert.equal(
+          NodeFS.existsSync(NodePath.join(baseDir, "userdata", "themes", "nightfall.json")),
+          true,
+        );
+        assert.equal(readSettings(baseDir).defaultTheme, "nightfall");
+      }),
   );
 
   // The staging entry is created fresh with O_EXCL, so a symlink planted at
   // its predictable name is cleared, never followed and written through.
-  it.effect("never writes through a symlink at the staging path", () =>
+  it.effect.skipIf(!symlinksSupported)("never writes through a symlink at the staging path", () =>
     Effect.gen(function* () {
       const baseDir = makeBaseDir();
       const themesDir = NodePath.join(baseDir, "userdata", "themes");
@@ -226,31 +234,33 @@ describe("t3 theme", () => {
   // Rollback moves the previous directory entry aside and back, so even an
   // entry the watcher would never publish -- here a symlink -- comes back
   // exactly as it was when the set fails.
-  it.effect("restores a non-theme destination entry when the set fails", () =>
-    Effect.gen(function* () {
-      const baseDir = makeBaseDir();
-      writeSettings(baseDir, {});
-      const userdataDir = NodePath.dirname(settingsPathFor(baseDir));
-      const themesDir = NodePath.join(userdataDir, "themes");
-      NodeFS.mkdirSync(themesDir, { recursive: true });
-      const outside = NodePath.join(baseDir, "outside.json");
-      NodeFS.writeFileSync(outside, NIGHTFALL_THEME_JSON);
-      const destination = NodePath.join(themesDir, "nightfall.json");
-      NodeFS.symlinkSync(outside, destination);
-      const themeFile = NodePath.join(baseDir, "nightfall.json");
-      NodeFS.writeFileSync(themeFile, NIGHTFALL_THEME_JSON);
-
-      NodeFS.chmodSync(userdataDir, 0o555);
-      try {
-        yield* runCli(["theme", "set", themeFile, "--base-dir", baseDir]).pipe(Effect.flip);
-        assert.equal(NodeFS.lstatSync(destination).isSymbolicLink(), true);
-      } finally {
-        NodeFS.chmodSync(userdataDir, 0o755);
-      }
-    }),
+  it.effect.skipIf(!symlinksSupported || windowsHost)(
+    "restores a non-theme destination entry when the set fails",
+    () =>
+      Effect.gen(function* () {
+        const baseDir = makeBaseDir();
+        writeSettings(baseDir, {});
+        const userdataDir = NodePath.dirname(settingsPathFor(baseDir));
+        const themesDir = NodePath.join(userdataDir, "themes");
+        NodeFS.mkdirSync(themesDir, { recursive: true });
+        const outside = NodePath.join(baseDir, "outside.json");
+        NodeFS.writeFileSync(outside, NIGHTFALL_THEME_JSON);
+        const destination = NodePath.join(themesDir, "nightfall.json");
+        NodeFS.symlinkSync(outside, destination);
+        const themeFile = NodePath.join(baseDir, "nightfall.json");
+        NodeFS.writeFileSync(themeFile, NIGHTFALL_THEME_JSON);
+
+        NodeFS.chmodSync(userdataDir, 0o555);
+        try {
+          yield* runCli(["theme", "set", themeFile, "--base-dir", baseDir]).pipe(Effect.flip);
+          assert.equal(NodeFS.lstatSync(destination).isSymbolicLink(), true);
+        } finally {
+          NodeFS.chmodSync(userdataDir, 0o755);
+        }
+      }),
   );
 
-  it.effect("restores the previous theme when a re-publish fails to set", () =>
+  it.effect.skipIf(windowsHost)("restores the previous theme when a re-publish fails to set", () =>
     Effect.gen(function* () {
       const baseDir = makeBaseDir();
       writeSettings(baseDir, {});
@@ -347,7 +357,7 @@ describe("t3 theme", () => {
 
   // An unreadable settings file must never read as "no settings": writing a
   // fresh sparse file over it would discard every key the user had.
-  it.effect("refuses to write when the settings file cannot be read", () =>
+  it.effect.skipIf(windowsHost)("refuses to write when the settings file cannot be read", () =>
     Effect.gen(function* () {
       const baseDir = makeBaseDir();
       writeSettings(baseDir, { enableProviderUpdateChecks: false });
diff --git a/apps/server/src/cloud/CliTokenManager.test.ts b/apps/server/src/cloud/CliTokenManager.test.ts
index e6eb6b7cd6fd..33a0f1224961 100644
--- a/apps/server/src/cloud/CliTokenManager.test.ts
+++ b/apps/server/src/cloud/CliTokenManager.test.ts
@@ -93,19 +93,6 @@ class PromptRejectedError extends Schema.TaggedErrorClass<PromptRejectedError>()
   { message: Schema.String },
 ) {}
 
-it("formats loopback authorization with a headless-host fallback", () => {
-  assert.equal(
-    CliTokenManager.formatLoopbackAuthorizationPrompt("https://clerk.example.test/authorize"),
-    [
-      "Open this URL to authorize T3 Connect:",
-      "  https://clerk.example.test/authorize",
-      "",
-      "Press \u001b[1mEnter\u001b[22m to open it in your browser.",
-      "No browser on this device? Press \u001b[1mH\u001b[22m to switch to headless mode.",
-    ].join("\n"),
-  );
-});
-
 const makeTestTerminal = (queue: Queue.Queue<Terminal.UserInput>) =>
   Terminal.make({
     columns: Effect.succeed(80),
diff --git a/apps/server/src/cloud/CliTokenManager.ts b/apps/server/src/cloud/CliTokenManager.ts
index f1bfad86c734..8c3869accc76 100644
--- a/apps/server/src/cloud/CliTokenManager.ts
+++ b/apps/server/src/cloud/CliTokenManager.ts
@@ -44,7 +44,7 @@ const CLOUD_CLI_OAUTH_CALLBACK_TIMEOUT = Duration.minutes(10);
 const CLOUD_CLI_OAUTH_REFRESH_EARLY_MS = Duration.toMillis(Duration.minutes(5));
 const boldTerminalText = (value: string): string => `\u001b[1m${value}\u001b[22m`;
 
-export function formatLoopbackAuthorizationPrompt(authorizationUrl: string): string {
+function formatLoopbackAuthorizationPrompt(authorizationUrl: string): string {
   return [
     "Open this URL to authorize T3 Connect:",
     `  ${authorizationUrl}`,
@@ -89,12 +89,10 @@ export const waitForLoopbackAuthorization = Effect.fn(
       while (true) {
         const result = yield* Effect.raceFirst(
           input.callback.pipe(
-            Effect.map(
-              (code): LoopbackAuthorizationResult => ({
-                _tag: "AuthorizationCode",
-                code,
-              }),
-            ),
+            Effect.map((code): LoopbackAuthorizationResult => ({
+              _tag: "AuthorizationCode",
+              code,
+            })),
           ),
           readLoopbackAuthorizationAction(terminalInput),
         );
diff --git a/apps/server/src/cloud/bootService.test.ts b/apps/server/src/cloud/bootService.test.ts
index c820f93cd212..688617440500 100644
--- a/apps/server/src/cloud/bootService.test.ts
+++ b/apps/server/src/cloud/bootService.test.ts
@@ -529,11 +529,14 @@ it.layer(NodeServices.layer)("boot service install", (it) => {
   it.effect("installs, reports current state, and uninstalls on macOS", () =>
     Effect.gen(function* () {
       const { service, fs, statePath, commands, timeouts } = yield* makeHarness("darwin");
+      const path = yield* Path.Path;
       const plan = yield* service.install();
 
-      expect(plan.unitPath.endsWith("Library/LaunchAgents/com.t3tools.t3code.service.plist")).toBe(
-        true,
-      );
+      expect(
+        plan.unitPath.endsWith(
+          path.join("Library", "LaunchAgents", "com.t3tools.t3code.service.plist"),
+        ),
+      ).toBe(true);
       expect(yield* fs.readFileString(plan.unitPath)).toContain(
         `    <key>PATH</key>\n    <string>${macInstallerPath}:/usr/local/bin:/usr/sbin:/sbin</string>`,
       );
diff --git a/apps/server/src/cloud/bootService.ts b/apps/server/src/cloud/bootService.ts
index 50ffcedf74b8..a0bd6f30c6ca 100644
--- a/apps/server/src/cloud/bootService.ts
+++ b/apps/server/src/cloud/bootService.ts
@@ -555,9 +555,16 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
         yield* fs.makeDirectory(directory, { recursive: true });
         const tempPath = yield* fs.makeTempFileScoped({ directory, prefix: ".service-write-" });
         yield* fs.writeFileString(tempPath, contents, { mode: 0o600 });
-        yield* (yield* fs.open(tempPath, { flag: "r" })).sync;
+        // Opened read-write: Windows refuses to flush a handle without write access.
+        yield* (yield* fs.open(tempPath, { flag: "r+" })).sync;
         yield* fs.rename(tempPath, filePath);
-        yield* (yield* fs.open(directory, { flag: "r" })).sync;
+        // Windows has no directory fsync (EPERM); NTFS journals the rename.
+        yield* (yield* fs.open(directory, { flag: "r" })).sync.pipe(
+          Effect.catchIf(
+            (error) => (error.reason.cause as NodeJS.ErrnoException | undefined)?.code === "EPERM",
+            () => Effect.void,
+          ),
+        );
       }),
     ).pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause })));
   const plan: BootServicePlan = {
diff --git a/apps/server/src/cloud/cliAuthHtml.test.ts b/apps/server/src/cloud/cliAuthHtml.test.ts
deleted file mode 100644
index 1104927b9800..000000000000
--- a/apps/server/src/cloud/cliAuthHtml.test.ts
+++ /dev/null
@@ -1,31 +0,0 @@
-import { expect, it } from "@effect/vitest";
-
-import {
-  renderLoopbackAuthorizationCompleteHtml,
-  resolveLoopbackAuthorizationStage,
-} from "./cliAuthHtml.ts";
-
-it("renders the branded loopback authorization completion page", () => {
-  const html = renderLoopbackAuthorizationCompleteHtml();
-
-  expect(resolveLoopbackAuthorizationStage()).toBe("dev");
-  expect(html).toContain("T3 Code (Dev)");
-  expect(html).toContain('class="stage stage-dev"');
-  expect(html).not.toContain("Secure terminal handoff");
-  expect(html).toContain("You're connected");
-  expect(html).toContain("Return to your terminal");
-  expect(html).not.toContain('class="next"');
-  expect(html).toContain('name="viewport"');
-  expect(html).not.toContain('class="status"');
-});
-
-it("renders the matching header treatment for each release channel", () => {
-  const nightly = renderLoopbackAuthorizationCompleteHtml("nightly");
-  const latest = renderLoopbackAuthorizationCompleteHtml("latest");
-
-  expect(nightly).toContain("T3 Code (Nightly)");
-  expect(nightly).toContain('class="stage stage-nightly"');
-  expect(latest).toContain('<p class="brand">T3 Code</p>');
-  expect(latest).not.toContain("(Latest)");
-  expect(latest).toContain('class="stage stage-latest"');
-});
diff --git a/apps/server/src/cloud/cliAuthHtml.ts b/apps/server/src/cloud/cliAuthHtml.ts
index 5a22a25993a9..69d3b471ae32 100644
--- a/apps/server/src/cloud/cliAuthHtml.ts
+++ b/apps/server/src/cloud/cliAuthHtml.ts
@@ -2,7 +2,7 @@ export type LoopbackAuthorizationStage = "dev" | "nightly" | "latest";
 
 declare const __T3CODE_BUILD_CHANNEL__: "nightly" | "latest" | undefined;
 
-export function resolveLoopbackAuthorizationStage(): LoopbackAuthorizationStage {
+function resolveLoopbackAuthorizationStage(): LoopbackAuthorizationStage {
   return typeof __T3CODE_BUILD_CHANNEL__ === "undefined" ? "dev" : __T3CODE_BUILD_CHANNEL__;
 }
 
diff --git a/apps/server/src/entrypoint.test.ts b/apps/server/src/entrypoint.test.ts
index 56f2c119764a..bf8247fd4295 100644
--- a/apps/server/src/entrypoint.test.ts
+++ b/apps/server/src/entrypoint.test.ts
@@ -7,6 +7,7 @@ import * as NodeURL from "node:url";
 import { describe, expect, it } from "vite-plus/test";
 
 import { isEntrypoint } from "./entrypoint.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const makeTempDir = () => NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-entrypoint-test-"));
 
@@ -44,21 +45,24 @@ describe("isEntrypoint", () => {
     ).toBe(true);
   });
 
-  it("matches through a symlinked entrypoint, as npm and npx install it", () => {
-    const dir = makeTempDir();
-    const real = NodePath.join(dir, "bin.mjs");
-    const link = NodePath.join(dir, "t3");
-    NodeFS.writeFileSync(real, "");
-    NodeFS.symlinkSync(real, link);
+  it.skipIf(!symlinksSupported)(
+    "matches through a symlinked entrypoint, as npm and npx install it",
+    () => {
+      const dir = makeTempDir();
+      const real = NodePath.join(dir, "bin.mjs");
+      const link = NodePath.join(dir, "t3");
+      NodeFS.writeFileSync(real, "");
+      NodeFS.symlinkSync(real, link);
 
-    expect(
-      isEntrypoint({
-        moduleUrl: NodeURL.pathToFileURL(real).href,
-        entryPath: link,
-        runtimeMain: undefined,
-      }),
-    ).toBe(true);
-  });
+      expect(
+        isEntrypoint({
+          moduleUrl: NodeURL.pathToFileURL(real).href,
+          entryPath: link,
+          runtimeMain: undefined,
+        }),
+      ).toBe(true);
+    },
+  );
 
   it("stays false for an imported module that is not the entrypoint", () => {
     // This is what keeps `bin.test.ts` from launching the CLI on import.
diff --git a/apps/server/src/environment/ServerEnvironment.test.ts b/apps/server/src/environment/ServerEnvironment.test.ts
index e9c07d117e69..aeea232349f0 100644
--- a/apps/server/src/environment/ServerEnvironment.test.ts
+++ b/apps/server/src/environment/ServerEnvironment.test.ts
@@ -166,6 +166,7 @@ it.layer(NodeServices.layer)("ServerEnvironmentLive", (it) => {
       expect(second.capabilities.attachmentUploads).toBe(true);
       expect(second.capabilities.fileAttachments).toEqual({ maxUploadBytes: 50 * 1024 * 1024 });
       expect(second.capabilities.pullRequests).toBe(true);
+      expect(second.capabilities.usagePriceOverrides).toBe(true);
       expect(second.capabilities.threadTitleRegeneration).toBe(true);
       expect(second.capabilities.threadPullRequestLinking).toBe(true);
       expect(second.capabilities.leadAgent).toBe(true);
diff --git a/apps/server/src/environment/ServerEnvironment.ts b/apps/server/src/environment/ServerEnvironment.ts
index e2dac5595adf..0373f1bc42f4 100644
--- a/apps/server/src/environment/ServerEnvironment.ts
+++ b/apps/server/src/environment/ServerEnvironment.ts
@@ -219,9 +219,11 @@ export const make = Effect.gen(function* () {
       pullRequests: true,
       threadSettlement: true,
       threadAutoSettlement: true,
+      threadRestartContinuation: true,
       threadSnooze: true,
       environmentThemes: true,
       usageLimitSources: true,
+      usagePriceOverrides: true,
       threadPinning: true,
       threadPinReorder: true,
       threadTitleRegeneration: true,
diff --git a/apps/server/src/environmentTheme.test.ts b/apps/server/src/environmentTheme.test.ts
index 0d50e020098c..3c3f650b4c3c 100644
--- a/apps/server/src/environmentTheme.test.ts
+++ b/apps/server/src/environmentTheme.test.ts
@@ -13,6 +13,7 @@ import * as Stream from "effect/Stream";
 
 import * as ServerConfig from "./config.ts";
 import * as EnvironmentTheme from "./environmentTheme.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const encodeThemeFile = Schema.encodeSync(Schema.fromJsonString(EnvironmentThemeFile));
 
@@ -188,7 +189,7 @@ it.layer(NodeServices.layer)("environment theme", (it) => {
 
   // A symlinked themes directory stays usable, but a symlinked file inside it
   // must not publish whatever it points at.
-  it.effect("ignores a symlinked theme file", () =>
+  it.effect.skipIf(!symlinksSupported)("ignores a symlinked theme file", () =>
     withEnvironmentThemes(
       {},
       Effect.gen(function* () {
diff --git a/apps/server/src/environmentTheme.ts b/apps/server/src/environmentTheme.ts
index c038af065bdc..b7eb11940cea 100644
--- a/apps/server/src/environmentTheme.ts
+++ b/apps/server/src/environmentTheme.ts
@@ -95,13 +95,23 @@ export class EnvironmentThemeService extends Context.Service<
  * usable, a symlinked file inside it does not), O_NONBLOCK keeps a FIFO from
  * blocking the open, and the fstat type and size gate examines the open
  * descriptor. Returns null for anything that is not a small regular file.
+ *
+ * Windows has neither flag (the constants are undefined, and OR-ing them in
+ * is a no-op), so the symlink check there is an lstat before the open. That
+ * leaves a window a swap could slip through, which the descriptor-bound
+ * checks below then narrow to "a regular file at that path".
  */
 export const readThemeFileGuarded = (filePath: string, maxBytes: number): string | null => {
   let fd: number;
   try {
+    if (NodeFS.constants.O_NOFOLLOW === undefined && NodeFS.lstatSync(filePath).isSymbolicLink()) {
+      return null;
+    }
     fd = NodeFS.openSync(
       filePath,
-      NodeFS.constants.O_RDONLY | NodeFS.constants.O_NOFOLLOW | NodeFS.constants.O_NONBLOCK,
+      NodeFS.constants.O_RDONLY |
+        (NodeFS.constants.O_NOFOLLOW ?? 0) |
+        (NodeFS.constants.O_NONBLOCK ?? 0),
     );
   } catch {
     return null;
diff --git a/apps/server/src/git/Utils.ts b/apps/server/src/git/Utils.ts
deleted file mode 100644
index e4a703f44540..000000000000
--- a/apps/server/src/git/Utils.ts
+++ /dev/null
@@ -1,7 +0,0 @@
-// @effect-diagnostics nodeBuiltinImport:off
-import * as NodeFS from "node:fs";
-import * as NodePath from "node:path";
-
-export function isGitRepository(cwd: string): boolean {
-  return NodeFS.existsSync(NodePath.join(cwd, ".git"));
-}
diff --git a/apps/server/src/http.ts b/apps/server/src/http.ts
index ddc6d67e134c..290b73b48514 100644
--- a/apps/server/src/http.ts
+++ b/apps/server/src/http.ts
@@ -12,6 +12,7 @@ import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { cast } from "effect/Function";
 import {
@@ -437,10 +438,66 @@ export const attachmentUploadRouteLayer = HttpRouter.add(
   }),
 );
 
-export const staticAndDevRouteLayer = HttpRouter.add(
-  "GET",
-  "*",
-  Effect.gen(function* () {
+const decodeBuildManifest = Schema.decodeUnknownEffect(
+  Schema.fromJsonString(
+    Schema.Record(
+      Schema.String,
+      Schema.Struct({
+        file: Schema.String,
+        css: Schema.optional(Schema.Array(Schema.String)),
+        assets: Schema.optional(Schema.Array(Schema.String)),
+      }),
+    ),
+  ),
+);
+
+const loadImmutableBuildAssets = Effect.gen(function* () {
+  const config = yield* ServerConfig.ServerConfig;
+  const staticDir =
+    config.staticDir ?? (config.devUrl ? yield* ServerConfig.resolveStaticDir() : undefined);
+  if (!staticDir) return new Set<string>();
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  return yield* fileSystem.readFileString(path.join(staticDir, ".vite", "manifest.json")).pipe(
+    Effect.flatMap(decodeBuildManifest),
+    Effect.map(
+      (manifest) =>
+        new Set(
+          Object.values(manifest).flatMap((entry) => [
+            entry.file,
+            ...(entry.css ?? []),
+            ...(entry.assets ?? []),
+          ]),
+        ),
+    ),
+    Effect.orElseSucceed(() => new Set<string>()),
+  );
+});
+
+const openStaticFile = Effect.fn("openStaticFile")(function* (filePath: string) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  // Reject directories and special files before opening. Response metadata comes from the handle.
+  const pathInfo = yield* fileSystem.stat(filePath).pipe(Effect.orElseSucceed(() => null));
+  if (pathInfo?.type !== "File") return null;
+  const file = yield* fileSystem.open(filePath, { flag: "r" });
+  const info = yield* file.stat;
+  return info.type === "File" ? { file, info } : null;
+});
+
+const streamStaticFile = (file: FileSystem.File, size: bigint) =>
+  Stream.unfold(
+    0n,
+    Effect.fnUntraced(function* (offset: bigint) {
+      if (offset >= size) return;
+      const remaining = size - offset;
+      const bytes = yield* file.readAlloc(remaining < 65_536n ? remaining : 65_536n);
+      if (Option.isNone(bytes)) return;
+      return [bytes.value, offset + BigInt(bytes.value.byteLength)] as const;
+    }),
+  );
+
+const handleStaticAndDevRequest = Effect.fn("handleStaticAndDevRequest")(
+  function* (immutableBuildAssets: ReadonlySet<string>) {
     const request = yield* HttpServerRequest.HttpServerRequest;
     const url = HttpServerRequest.toURL(request);
 
@@ -467,7 +524,6 @@ export const staticAndDevRouteLayer = HttpRouter.add(
       });
     }
 
-    const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
     const staticRoot = path.resolve(staticDir);
     const staticRequestPath = url.value.pathname === "/" ? "/index.html" : url.value.pathname;
@@ -501,30 +557,78 @@ export const staticAndDevRouteLayer = HttpRouter.add(
       }
     }
 
-    const fileInfo = yield* fileSystem.stat(filePath).pipe(Effect.orElseSucceed(() => null));
-    if (!fileInfo || fileInfo.type !== "File") {
-      const indexPath = path.resolve(staticRoot, "index.html");
-      const indexData = yield* fileSystem
-        .readFile(indexPath)
-        .pipe(Effect.orElseSucceed(() => null));
-      if (!indexData) {
+    let opened = yield* openStaticFile(filePath);
+    if (!opened) {
+      filePath = path.resolve(staticRoot, "index.html");
+      opened = yield* openStaticFile(filePath);
+      if (!opened) {
         return HttpServerResponse.text("Not Found", { status: 404 });
       }
-      return HttpServerResponse.uint8Array(indexData, {
-        status: 200,
-        contentType: "text/html; charset=utf-8",
-      });
+    }
+    const fileInfo = opened.info;
+    const mimeType = Mime.getType(filePath) ?? "application/octet-stream";
+    const isHtml = mimeType === "text/html";
+
+    // A hash-like name is not enough: custom static files can use the same naming pattern.
+    const relativePath = path.relative(staticRoot, filePath).replaceAll("\\", "/");
+    const immutable =
+      !isHtml &&
+      /^assets\/.+-[\w-]{8}\.[^/]+$/.test(relativePath) &&
+      immutableBuildAssets.has(relativePath);
+    const headers: Record<string, string> = {
+      "Cache-Control": immutable ? "public, max-age=31536000, immutable" : "no-cache",
+    };
+    // Deployments can preserve HTML size and mtime while changing its bundle URLs.
+    const modifiedAt = isHtml ? undefined : Option.getOrUndefined(fileInfo.mtime);
+    const etag = modifiedAt
+      ? `W/"${fileInfo.size.toString(16)}-${modifiedAt.getTime().toString(16)}"`
+      : undefined;
+    if (etag !== undefined && modifiedAt !== undefined) {
+      headers.ETag = etag;
+      headers["Last-Modified"] = modifiedAt.toUTCString();
     }
 
-    const contentType = Mime.getType(filePath) ?? "application/octet-stream";
-    const data = yield* fileSystem.readFile(filePath).pipe(Effect.orElseSucceed(() => null));
-    if (!data) {
-      return HttpServerResponse.text("Internal Server Error", { status: 500 });
+    // If-None-Match takes precedence over dates and uses weak comparison for
+    // GET/HEAD, including when compression changes the transferred bytes.
+    const ifNoneMatch = request.headers["if-none-match"];
+    const ifModifiedSince = request.headers["if-modified-since"];
+    const unchanged =
+      ifNoneMatch !== undefined
+        ? ifNoneMatch.split(",").some((value) => {
+            const candidate = value.trim();
+            return (
+              candidate === "*" ||
+              (etag !== undefined && candidate.replace(/^W\//i, "") === etag.slice(2))
+            );
+          })
+        : ifModifiedSince !== undefined &&
+          modifiedAt !== undefined &&
+          Date.parse(modifiedAt.toUTCString()) <= Date.parse(ifModifiedSince);
+    if (!isHtml && unchanged) {
+      return HttpServerResponse.empty({
+        status: 304,
+        headers: { ...headers, Vary: "Accept-Encoding" },
+      });
     }
 
-    return HttpServerResponse.uint8Array(data, {
-      status: 200,
+    const contentType = isHtml ? "text/html; charset=utf-8" : mimeType;
+    // The request scope closes the handle for GET, HEAD, 304, errors, and cancellation.
+    // HEAD still passes through compression, which selects headers without reading the stream.
+    return HttpServerResponse.stream(streamStaticFile(opened.file, fileInfo.size), {
+      headers,
       contentType,
+      contentLength: Number(fileInfo.size),
     });
+  },
+  Effect.catchTags({
+    PlatformError: () =>
+      Effect.succeed(HttpServerResponse.text("Internal Server Error", { status: 500 })),
   }),
 );
+
+// Read the installed build's manifest once. Unknown files use revalidation.
+export const staticAndDevRouteLayer = Layer.unwrap(
+  loadImmutableBuildAssets.pipe(
+    Effect.map((assets) => HttpRouter.add("GET", "*", handleStaticAndDevRequest(assets))),
+  ),
+);
diff --git a/apps/server/src/keybindings.test.ts b/apps/server/src/keybindings.test.ts
index 6c32235c27f8..ec7070809435 100644
--- a/apps/server/src/keybindings.test.ts
+++ b/apps/server/src/keybindings.test.ts
@@ -12,6 +12,7 @@ import * as Schema from "effect/Schema";
 import * as ServerConfig from "./config.ts";
 import * as Keybindings from "./keybindings.ts";
 import { KeybindingsConfigError } from "@t3tools/contracts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
 const KeybindingsConfigJson = Schema.fromJsonString(KeybindingsConfig);
 const encodeKeybindingsConfigJson = Schema.encodeEffect(KeybindingsConfigJson);
@@ -187,33 +188,6 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
     }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
-  it.effect("ships configurable thread navigation defaults", () =>
-    Effect.sync(() => {
-      const defaultsByCommand = new Map(
-        Keybindings.DEFAULT_KEYBINDINGS.map((binding) => [binding.command, binding.key] as const),
-      );
-
-      assert.equal(defaultsByCommand.get("thread.previous"), "mod+shift+[");
-      assert.equal(defaultsByCommand.get("thread.next"), "mod+shift+]");
-      assert.equal(defaultsByCommand.get("thread.copyReference"), "mod+shift+c");
-      assert.equal(defaultsByCommand.get("thread.settle"), "mod+shift+s");
-      assert.equal(defaultsByCommand.get("thread.pin"), "mod+shift+p");
-      assert.equal(defaultsByCommand.get("thread.jump.1"), "mod+1");
-      assert.equal(defaultsByCommand.get("thread.jump.9"), "mod+9");
-      assert.equal(defaultsByCommand.get("modelPicker.toggle"), "mod+shift+m");
-      assert.equal(defaultsByCommand.get("themeEditor.toggle"), "mod+alt+shift+t");
-      assert.equal(defaultsByCommand.get("filePicker.toggle"), "mod+p");
-      assert.equal(defaultsByCommand.get("projectSearch.toggle"), "mod+shift+f");
-      assert.equal(defaultsByCommand.get("sidebar.toggle"), "mod+b");
-      assert.equal(defaultsByCommand.get("rightPanel.toggle"), "mod+alt+b");
-      assert.isFalse(defaultsByCommand.has("rightPanel.toggleMaximized"));
-      assert.equal(defaultsByCommand.get("rightPanel.close"), "mod+w");
-      assert.equal(defaultsByCommand.get("terminal.splitVertical"), "mod+shift+d");
-      assert.equal(defaultsByCommand.get("modelPicker.jump.1"), "mod+1");
-      assert.equal(defaultsByCommand.get("modelPicker.jump.9"), "mod+9");
-    }),
-  );
-
   it.effect("uses defaults in runtime when config is malformed without overriding file", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
@@ -511,31 +485,34 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
     }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
-  it.effect("fails when config directory is not writable", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const { keybindingsConfigPath } = yield* ServerConfig.ServerConfig;
-      const { dirname } = yield* Path.Path;
-      yield* writeKeybindingsConfig(keybindingsConfigPath, [
-        { key: "mod+j", command: "terminal.toggle" },
-      ]);
-      yield* fs.chmod(dirname(keybindingsConfigPath), 0o500);
+  // chmod cannot make a directory unwritable on Windows, so the write succeeds.
+  it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+    "fails when config directory is not writable",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const { keybindingsConfigPath } = yield* ServerConfig.ServerConfig;
+        const { dirname } = yield* Path.Path;
+        yield* writeKeybindingsConfig(keybindingsConfigPath, [
+          { key: "mod+j", command: "terminal.toggle" },
+        ]);
+        yield* fs.chmod(dirname(keybindingsConfigPath), 0o500);
 
-      const result = yield* Effect.gen(function* () {
-        const keybindings = yield* Keybindings.Keybindings;
-        return yield* keybindings.upsertKeybindingRule({
-          key: "mod+shift+r",
-          command: "script.run-tests.run",
-        });
-      }).pipe(toDetailResult);
-      assertFailure(result, "failed to write keybindings config");
+        const result = yield* Effect.gen(function* () {
+          const keybindings = yield* Keybindings.Keybindings;
+          return yield* keybindings.upsertKeybindingRule({
+            key: "mod+shift+r",
+            command: "script.run-tests.run",
+          });
+        }).pipe(toDetailResult);
+        assertFailure(result, "failed to write keybindings config");
 
-      yield* fs.chmod(dirname(keybindingsConfigPath), 0o700);
+        yield* fs.chmod(dirname(keybindingsConfigPath), 0o700);
 
-      const persisted = yield* readKeybindingsConfig(keybindingsConfigPath);
-      const persistedView = persisted.map(({ key, command }) => ({ key, command }));
-      assert.deepEqual(persistedView, [{ key: "mod+j", command: "terminal.toggle" }]);
-    }).pipe(Effect.provide(makeKeybindingsLayer())),
+        const persisted = yield* readKeybindingsConfig(keybindingsConfigPath);
+        const persistedView = persisted.map(({ key, command }) => ({ key, command }));
+        assert.deepEqual(persistedView, [{ key: "mod+j", command: "terminal.toggle" }]);
+      }).pipe(Effect.provide(makeKeybindingsLayer())),
   );
 
   it.effect("caches loaded resolved config across repeated reads", () =>
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
index 391602548774..1dae23cdccb0 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
@@ -12,6 +12,7 @@ import {
 } from "@t3tools/contracts";
 import {
   CommandId,
+  CheckpointRef,
   DEFAULT_PROVIDER_INTERACTION_MODE,
   EventId,
   MessageId,
@@ -27,6 +28,7 @@ import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
 import * as ManagedRuntime from "effect/ManagedRuntime";
 import * as PubSub from "effect/PubSub";
+import * as Queue from "effect/Queue";
 import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
 import { it as effectIt } from "@effect/vitest";
@@ -43,7 +45,8 @@ import { OrchestrationProjectionPipelineLive } from "./ProjectionPipeline.ts";
 import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQuery.ts";
 import * as ThreadBackgroundLiveness from "../ThreadBackgroundLiveness.ts";
 import * as ThreadPlanProgress from "../ThreadPlanProgress.ts";
-import { RuntimeReceiptBusLive } from "./RuntimeReceiptBus.ts";
+import { RuntimeReceiptBusTest } from "./RuntimeReceiptBus.ts";
+import * as RuntimeReceiptBus from "../Services/RuntimeReceiptBus.ts";
 import { OrchestrationEventStoreLive } from "../../persistence/Layers/OrchestrationEventStore.ts";
 import { OrchestrationCommandReceiptRepositoryLive } from "../../persistence/Layers/OrchestrationCommandReceipts.ts";
 import { SqlitePersistenceMemory } from "../../persistence/Layers/Sqlite.ts";
@@ -262,7 +265,8 @@ describe("CheckpointReactor", () => {
     | OrchestrationEngineService
     | CheckpointReactor
     | CheckpointStore.CheckpointStore
-    | ProjectionSnapshotQuery,
+    | ProjectionSnapshotQuery
+    | RuntimeReceiptBus.RuntimeReceiptBus,
     unknown
   > | null = null;
   let scope: Scope.Closeable | null = null;
@@ -288,6 +292,7 @@ describe("CheckpointReactor", () => {
   async function createHarness(options?: {
     readonly hasSession?: boolean;
     readonly seedFilesystemCheckpoints?: boolean;
+    readonly initializeGit?: boolean;
     readonly projectWorkspaceRoot?: string;
     readonly threadWorktreePath?: string | null;
     readonly threadBranch?: string | null;
@@ -299,6 +304,9 @@ describe("CheckpointReactor", () => {
     readonly pullRequestRefreshCalls?: Array<string>;
   }) {
     const cwd = createGitRepository();
+    if (options?.initializeGit === false) {
+      NodeFS.rmSync(NodePath.join(cwd, ".git"), { recursive: true });
+    }
     tempDirs.push(cwd);
     const provider = createProviderServiceHarness(
       cwd,
@@ -356,7 +364,7 @@ describe("CheckpointReactor", () => {
     const layer = CheckpointReactorLive.pipe(
       Layer.provideMerge(orchestrationLayer),
       Layer.provideMerge(projectionSnapshotLayer),
-      Layer.provideMerge(RuntimeReceiptBusLive),
+      Layer.provideMerge(RuntimeReceiptBusTest),
       Layer.provideMerge(Layer.succeed(ProviderService, provider.service)),
       Layer.provideMerge(Layer.mock(PullRequestService)({ refreshAfterTurn })),
       Layer.provideMerge(vcsStatusBroadcasterLayer),
@@ -380,8 +388,21 @@ describe("CheckpointReactor", () => {
     const checkpointStore = await runtime.runPromise(
       Effect.service(CheckpointStore.CheckpointStore),
     );
-    scope = await Effect.runPromise(Scope.make("sequential"));
-    await Effect.runPromise(reactor.start().pipe(Scope.provide(scope)));
+    const receiptBus = await runtime.runPromise(
+      Effect.service(RuntimeReceiptBus.RuntimeReceiptBus),
+    );
+    const testScope = await Effect.runPromise(Scope.make("sequential"));
+    scope = testScope;
+    const receipts = await Effect.runPromise(
+      Effect.gen(function* () {
+        const receipts = yield* Queue.unbounded<RuntimeReceiptBus.OrchestrationRuntimeReceipt>();
+        yield* Stream.runForEach(receiptBus.streamEventsForTest, (receipt) =>
+          Queue.offer(receipts, receipt),
+        ).pipe(Effect.forkIn(testScope, { startImmediately: true }));
+        yield* reactor.start().pipe(Scope.provide(testScope));
+        return receipts;
+      }),
+    );
     const drain = () => Effect.runPromise(reactor.drain);
 
     const createdAt = "2026-01-01T00:00:00.000Z";
@@ -470,16 +491,19 @@ describe("CheckpointReactor", () => {
       provider,
       cwd,
       drain,
+      nextReceipt: Queue.take(receipts),
       pullRequestRefreshes,
     };
   }
 
-  it("captures pre-turn baseline on turn.started and post-turn checkpoint on turn.completed", async () => {
-    const harness = await createHarness({ seedFilesystemCheckpoints: false });
-    const createdAt = "2026-01-01T00:00:00.000Z";
+  effectIt.effect("captures baseline and large turn summaries before completion receipts", () =>
+    Effect.gen(function* () {
+      const harness = yield* Effect.promise(() =>
+        createHarness({ seedFilesystemCheckpoints: false }),
+      );
+      const createdAt = "2026-01-01T00:00:00.000Z";
 
-    await Effect.runPromise(
-      harness.engine.dispatch({
+      yield* harness.engine.dispatch({
         type: "thread.session.set",
         commandId: CommandId.make("cmd-session-set-capture"),
         threadId: ThreadId.make("thread-1"),
@@ -493,61 +517,320 @@ describe("CheckpointReactor", () => {
           updatedAt: createdAt,
         },
         createdAt,
-      }),
-    );
+      });
 
-    harness.provider.emit({
-      type: "turn.started",
-      eventId: EventId.make("evt-turn-started-1"),
-      provider: ProviderDriverKind.make("codex"),
+      harness.provider.emit({
+        type: "turn.started",
+        eventId: EventId.make("evt-turn-started-1"),
+        provider: ProviderDriverKind.make("codex"),
 
-      createdAt: "2026-01-01T00:00:00.000Z",
-      threadId: ThreadId.make("thread-1"),
-      turnId: asTurnId("turn-1"),
-    });
-    await waitForGitRefExists(
-      harness.cwd,
-      checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0),
-    );
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId: ThreadId.make("thread-1"),
+        turnId: asTurnId("turn-1"),
+      });
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.baseline.captured",
+        checkpointTurnCount: 0,
+      });
 
-    NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "v2\n", "utf8");
+      NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "v2\n", "utf8");
+      const largeFileLineCount = 25_000;
+      NodeFS.writeFileSync(
+        NodePath.join(harness.cwd, "large.txt"),
+        `${"payload".repeat(64)}\n`.repeat(largeFileLineCount),
+        "utf8",
+      );
+      harness.provider.emit({
+        type: "turn.completed",
+        eventId: EventId.make("evt-turn-completed-1"),
+        provider: ProviderDriverKind.make("codex"),
+
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId: ThreadId.make("thread-1"),
+        turnId: asTurnId("turn-1"),
+        payload: { state: "completed" },
+      });
+
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.diff.finalized",
+        turnId: "turn-1",
+        checkpointTurnCount: 1,
+      });
+      const thread = (yield* Effect.promise(harness.readModel)).threads.find(
+        (entry) => entry.id === "thread-1",
+      );
+      expect(thread?.checkpoints[0]).toMatchObject({
+        checkpointTurnCount: 1,
+        files: [
+          { path: "large.txt", kind: "modified", additions: largeFileLineCount, deletions: 0 },
+          { path: "README.md", kind: "modified", additions: 1, deletions: 1 },
+        ],
+      });
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "turn.processing.quiesced",
+        turnId: "turn-1",
+        checkpointTurnCount: 1,
+      });
+      yield* Effect.promise(harness.drain);
+      expect(
+        gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0)),
+      ).toBe(true);
+      expect(
+        gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 1)),
+      ).toBe(true);
+      expect(
+        gitShowFileAtRef(
+          harness.cwd,
+          checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0),
+          "README.md",
+        ),
+      ).toBe("v1\n");
+      expect(
+        gitShowFileAtRef(
+          harness.cwd,
+          checkpointRefForThreadTurn(ThreadId.make("thread-1"), 1),
+          "README.md",
+        ),
+      ).toBe("v2\n");
+    }),
+  );
+
+  effectIt.effect("captures and reverts checkpoints from a nested Git workspace", () =>
+    Effect.gen(function* () {
+      const repositoryRoot = createGitRepository();
+      tempDirs.push(repositoryRoot);
+      const workspaceRoot = NodePath.join(repositoryRoot, "apps", "server");
+      NodeFS.mkdirSync(workspaceRoot, { recursive: true });
+      const filePath = NodePath.join(workspaceRoot, "index.ts");
+      NodeFS.writeFileSync(filePath, "export const value = 1;\n");
+      runGit(repositoryRoot, ["add", "."]);
+      runGit(repositoryRoot, ["commit", "-m", "Add nested workspace"]);
+      const harness = yield* Effect.promise(() =>
+        createHarness({
+          seedFilesystemCheckpoints: false,
+          projectWorkspaceRoot: workspaceRoot,
+          threadWorktreePath: workspaceRoot,
+          providerSessionCwd: workspaceRoot,
+        }),
+      );
+      const threadId = ThreadId.make("thread-1");
+      const turnId = asTurnId("turn-nested");
+      const createdAt = "2026-01-01T00:00:00.000Z";
+      harness.provider.emit({
+        type: "turn.started",
+        eventId: EventId.make("evt-nested-start"),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt,
+        threadId,
+        turnId,
+      });
+      yield* Effect.promise(harness.drain);
+      expect(gitRefExists(repositoryRoot, checkpointRefForThreadTurn(threadId, 0))).toBe(true);
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.baseline.captured",
+      });
+
+      NodeFS.writeFileSync(filePath, "export const value = 2;\n");
+      harness.provider.emit({
+        type: "turn.completed",
+        eventId: EventId.make("evt-nested-complete"),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt,
+        threadId,
+        turnId,
+        payload: { state: "completed" },
+      });
+      yield* Effect.promise(harness.drain);
+      const thread = (yield* Effect.promise(harness.readModel)).threads.find(
+        (entry) => entry.id === threadId,
+      );
+      expect(thread?.checkpoints[0]).toMatchObject({
+        status: "ready",
+        files: [{ path: "apps/server/index.ts", additions: 1, deletions: 1 }],
+      });
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.diff.finalized",
+        turnId,
+      });
+      expect(yield* harness.nextReceipt).toMatchObject({ type: "turn.processing.quiesced" });
+
+      yield* harness.engine.dispatch({
+        type: "thread.checkpoint.revert",
+        commandId: CommandId.make("cmd-nested-revert"),
+        threadId,
+        turnCount: 0,
+        createdAt,
+      });
+      yield* Effect.promise(harness.drain);
+      expect(NodeFS.readFileSync(filePath, "utf8")).toBe("export const value = 1;\n");
+      expect(harness.provider.rollbackConversation).toHaveBeenCalledWith({ threadId, numTurns: 1 });
+      expect(gitRefExists(repositoryRoot, checkpointRefForThreadTurn(threadId, 1))).toBe(false);
+      const reverted = (yield* Effect.promise(harness.readModel)).threads.find(
+        (entry) => entry.id === threadId,
+      );
+      expect(reverted?.checkpoints).toEqual([]);
+    }),
+  );
+
+  effectIt.effect.each(["turn.completed", "turn.aborted"] as const)(
+    "captures every edit after a mid-turn diff update on %s",
+    (terminalEventType) =>
+      Effect.gen(function* () {
+        const harness = yield* Effect.promise(() =>
+          createHarness({ seedFilesystemCheckpoints: false }),
+        );
+        const threadId = ThreadId.make("thread-1");
+        const turnId = asTurnId("turn-1");
+        const assistantMessageId = MessageId.make("assistant:mid-turn");
+        const createdAt = "2026-01-01T00:00:00.000Z";
+        yield* harness.engine.dispatch({
+          type: "thread.session.set",
+          commandId: CommandId.make("cmd-mid-turn-running"),
+          threadId,
+          session: {
+            threadId,
+            status: "running",
+            providerName: "codex",
+            runtimeMode: "approval-required",
+            activeTurnId: turnId,
+            lastError: null,
+            updatedAt: createdAt,
+          },
+          createdAt,
+        });
+        harness.provider.emit({
+          type: "turn.started",
+          eventId: EventId.make("evt-mid-turn-start"),
+          provider: ProviderDriverKind.make("codex"),
+          createdAt,
+          threadId,
+          turnId,
+        });
+        expect(yield* harness.nextReceipt).toMatchObject({
+          type: "checkpoint.baseline.captured",
+        });
+
+        NodeFS.writeFileSync(NodePath.join(harness.cwd, "early.ts"), "export const early = 1;\n");
+        yield* harness.engine.dispatch({
+          type: "thread.turn.diff.complete",
+          commandId: CommandId.make("cmd-mid-turn-diff"),
+          threadId,
+          turnId,
+          completedAt: createdAt,
+          checkpointRef: CheckpointRef.make("provider-diff:mid-turn"),
+          assistantMessageId,
+          status: "missing",
+          files: [],
+          checkpointTurnCount: 1,
+          createdAt,
+        });
+        yield* Effect.promise(harness.drain);
+
+        NodeFS.writeFileSync(NodePath.join(harness.cwd, "late.ts"), "export const late = 2;\n");
+        yield* harness.engine.dispatch({
+          type: "thread.session.set",
+          commandId: CommandId.make("cmd-mid-turn-settled"),
+          threadId,
+          session: {
+            threadId,
+            status: terminalEventType === "turn.aborted" ? "interrupted" : "ready",
+            providerName: "codex",
+            runtimeMode: "approval-required",
+            activeTurnId: null,
+            lastError: null,
+            updatedAt: createdAt,
+          },
+          createdAt,
+        });
+        harness.provider.emit({
+          eventId: EventId.make("evt-mid-turn-complete"),
+          provider: ProviderDriverKind.make("codex"),
+          createdAt,
+          threadId,
+          turnId,
+          ...(terminalEventType === "turn.completed"
+            ? { type: "turn.completed", payload: { state: "completed" } }
+            : { type: "turn.aborted", payload: { reason: "Interrupted by user." } }),
+        });
+        yield* Effect.promise(harness.drain);
+        expect(gitRefExists(harness.cwd, checkpointRefForThreadTurn(threadId, 1))).toBe(true);
+        expect(yield* harness.nextReceipt).toMatchObject({
+          type: "checkpoint.diff.finalized",
+          turnId,
+          checkpointTurnCount: 1,
+        });
+        expect(yield* harness.nextReceipt).toMatchObject({
+          type: "turn.processing.quiesced",
+          turnId,
+        });
+        yield* Effect.promise(harness.drain);
+        const thread = (yield* Effect.promise(harness.readModel)).threads.find(
+          (entry) => entry.id === threadId,
+        );
+        expect(thread?.checkpoints).toHaveLength(1);
+        expect(thread?.checkpoints[0]?.status).toBe("ready");
+        expect(thread?.latestTurn?.state).toBe(
+          terminalEventType === "turn.aborted" ? "interrupted" : "completed",
+        );
+        expect(thread?.checkpoints[0]?.assistantMessageId).toBe(assistantMessageId);
+        expect(thread?.checkpoints[0]?.files.map((file) => file.path)).toEqual([
+          "early.ts",
+          "late.ts",
+        ]);
+        expect(
+          gitShowFileAtRef(harness.cwd, checkpointRefForThreadTurn(threadId, 1), "late.ts"),
+        ).toBe("export const late = 2;\n");
+
+        const followUpTurnId = asTurnId("turn-2");
+        harness.provider.emit({
+          type: "turn.started",
+          eventId: EventId.make("evt-follow-up-start"),
+          provider: ProviderDriverKind.make("codex"),
+          createdAt,
+          threadId,
+          turnId: followUpTurnId,
+        });
+        harness.provider.emit({
+          type: "turn.completed",
+          eventId: EventId.make("evt-follow-up-complete"),
+          provider: ProviderDriverKind.make("codex"),
+          createdAt,
+          threadId,
+          turnId: followUpTurnId,
+          payload: { state: "completed" },
+        });
+        expect(yield* harness.nextReceipt).toMatchObject({
+          type: "checkpoint.diff.finalized",
+          turnId: followUpTurnId,
+          checkpointTurnCount: 2,
+        });
+        const followUp = (yield* Effect.promise(harness.readModel)).threads.find(
+          (entry) => entry.id === threadId,
+        );
+        expect(
+          followUp?.checkpoints.find((checkpoint) => checkpoint.turnId === followUpTurnId),
+        ).toMatchObject({ checkpointTurnCount: 2, files: [] });
+      }),
+  );
+
+  it("does not capture an aborted turn without a matching start or active session", async () => {
+    const harness = await createHarness({ seedFilesystemCheckpoints: false });
     harness.provider.emit({
-      type: "turn.completed",
-      eventId: EventId.make("evt-turn-completed-1"),
+      type: "turn.aborted",
+      eventId: EventId.make("evt-untracked-abort"),
       provider: ProviderDriverKind.make("codex"),
-
       createdAt: "2026-01-01T00:00:00.000Z",
       threadId: ThreadId.make("thread-1"),
-      turnId: asTurnId("turn-1"),
-      payload: { state: "completed" },
+      turnId: asTurnId("turn-untracked"),
+      payload: { reason: "Interrupted before the turn started." },
     });
+    await harness.drain();
 
-    await waitForEvent(harness.engine, (event) => event.type === "thread.turn-diff-completed");
-    const thread = await waitForThread(
-      harness.readModel,
-      (entry) => entry.latestTurn?.turnId === "turn-1" && entry.checkpoints.length === 1,
-    );
-    expect(thread.checkpoints[0]?.checkpointTurnCount).toBe(1);
-    expect(
-      gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0)),
-    ).toBe(true);
+    const thread = (await harness.readModel()).threads.find((entry) => entry.id === "thread-1");
+    expect(thread?.checkpoints).toEqual([]);
     expect(
       gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 1)),
-    ).toBe(true);
-    expect(
-      gitShowFileAtRef(
-        harness.cwd,
-        checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0),
-        "README.md",
-      ),
-    ).toBe("v1\n");
-    expect(
-      gitShowFileAtRef(
-        harness.cwd,
-        checkpointRefForThreadTurn(ThreadId.make("thread-1"), 1),
-        "README.md",
-      ),
-    ).toBe("v2\n");
+    ).toBe(false);
   });
 
   it("refreshes local git status state on turn completion using the session cwd", async () => {
@@ -879,52 +1162,148 @@ describe("CheckpointReactor", () => {
     ).toBe(true);
   });
 
-  it("appends capture failure activity when turn diff summary cannot be derived", async () => {
-    const harness = await createHarness({ seedFilesystemCheckpoints: false });
-    const createdAt = "2026-01-01T00:00:00.000Z";
-
-    await Effect.runPromise(
-      harness.engine.dispatch({
-        type: "thread.session.set",
-        commandId: CommandId.make("cmd-session-set-missing-baseline-diff"),
+  effectIt.effect("captures a checkpoint without a summary when the baseline is missing", () =>
+    Effect.gen(function* () {
+      const harness = yield* Effect.promise(() =>
+        createHarness({ seedFilesystemCheckpoints: false }),
+      );
+      harness.provider.emit({
+        type: "turn.completed",
+        eventId: EventId.make("evt-turn-completed-missing-baseline"),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: "2026-01-01T00:00:00.000Z",
         threadId: ThreadId.make("thread-1"),
-        session: {
-          threadId: ThreadId.make("thread-1"),
-          status: "ready",
-          providerName: "codex",
-          runtimeMode: "approval-required",
-          activeTurnId: null,
-          lastError: null,
-          updatedAt: createdAt,
-        },
-        createdAt,
-      }),
-    );
-
-    harness.provider.emit({
-      type: "turn.completed",
-      eventId: EventId.make("evt-turn-completed-missing-baseline"),
-      provider: ProviderDriverKind.make("codex"),
-
-      createdAt: "2026-01-01T00:00:00.000Z",
-      threadId: ThreadId.make("thread-1"),
-      turnId: asTurnId("turn-missing-baseline"),
-      payload: { state: "completed" },
-    });
+        turnId: asTurnId("turn-missing-baseline"),
+        payload: { state: "completed" },
+      });
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.diff.finalized",
+        checkpointTurnCount: 1,
+      });
+      yield* Effect.promise(harness.drain);
+      const thread = (yield* Effect.promise(harness.readModel)).threads[0];
+      expect(thread?.checkpoints[0]).toMatchObject({
+        status: "ready",
+        checkpointTurnCount: 1,
+        files: [],
+      });
+      expect(
+        gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 1)),
+      ).toBe(true);
+      expect(
+        thread?.activities.some((activity) => activity.kind === "checkpoint.capture.failed"),
+      ).toBe(false);
+    }),
+  );
 
-    await waitForEvent(harness.engine, (event) => event.type === "thread.turn-diff-completed");
-    const thread = await waitForThread(
-      harness.readModel,
-      (entry) =>
-        entry.checkpoints.length === 1 &&
-        entry.activities.some((activity) => activity.kind === "checkpoint.capture.failed"),
-    );
+  effectIt.effect.each([
+    { timing: "between turns", commit: false },
+    { timing: "between turns", commit: true },
+    { timing: "during a turn", commit: false },
+    { timing: "during a turn", commit: true },
+  ])("resumes checkpointing after git init $timing (commit: $commit)", ({ timing, commit }) =>
+    Effect.gen(function* () {
+      const harness = yield* Effect.promise(() =>
+        createHarness({ initializeGit: false, seedFilesystemCheckpoints: false }),
+      );
+      const threadId = ThreadId.make("thread-1");
+      const createdAt = "2026-01-01T00:00:00.000Z";
+      const emit = (type: "turn.started" | "turn.completed", turn: number) =>
+        harness.provider.emit({
+          type,
+          eventId: EventId.make(`${type}-${turn}`),
+          provider: ProviderDriverKind.make("codex"),
+          createdAt,
+          threadId,
+          turnId: asTurnId(`turn-${turn}`),
+          ...(type === "turn.completed" ? { payload: { state: "completed" } } : {}),
+        });
+      emit("turn.started", 1);
+      yield* Effect.promise(harness.drain);
+      NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "before git\n");
+      emit("turn.completed", 1);
+      yield* Effect.promise(harness.drain);
+      expect((yield* Effect.promise(harness.readModel)).threads[0]?.checkpoints).toEqual([]);
+
+      if (timing === "during a turn") {
+        emit("turn.started", 2);
+        yield* Effect.promise(harness.drain);
+      }
+      runGit(harness.cwd, ["init", "--initial-branch=main"]);
+      if (commit) {
+        runGit(harness.cwd, ["add", "."]);
+        runGit(harness.cwd, [
+          "-c",
+          "user.name=Test",
+          "-c",
+          "user.email=test@example.com",
+          "commit",
+          "-m",
+          "Initial",
+        ]);
+      }
+      if (timing === "between turns") {
+        // Exercise the domain entry point as well as the provider turn-start event.
+        yield* harness.engine.dispatch({
+          type: "thread.turn.start",
+          commandId: CommandId.make("cmd-after-git-init"),
+          threadId,
+          message: {
+            messageId: MessageId.make("message-after-git-init"),
+            role: "user",
+            text: "continue",
+            attachments: [],
+          },
+          interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+          runtimeMode: "approval-required",
+          createdAt,
+        });
+        expect(yield* harness.nextReceipt).toMatchObject({
+          type: "checkpoint.baseline.captured",
+          checkpointTurnCount: 0,
+        });
+        emit("turn.started", 2);
+        yield* Effect.promise(harness.drain);
+      }
+      NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "after git\n");
+      emit("turn.completed", 2);
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.diff.finalized",
+        checkpointTurnCount: 1,
+      });
+      expect(yield* harness.nextReceipt).toMatchObject({ type: "turn.processing.quiesced" });
+      yield* Effect.promise(harness.drain);
+      const firstCheckpoint = (yield* Effect.promise(harness.readModel)).threads[0]?.checkpoints[0];
+      expect(firstCheckpoint?.files).toEqual(
+        timing === "between turns"
+          ? [{ path: "README.md", kind: "modified", additions: 1, deletions: 1 }]
+          : [],
+      );
+      expect(
+        gitShowFileAtRef(harness.cwd, checkpointRefForThreadTurn(threadId, 1), "README.md"),
+      ).toBe("after git\n");
+      expect(gitRefExists(harness.cwd, checkpointRefForThreadTurn(threadId, 0))).toBe(
+        timing === "between turns",
+      );
 
-    expect(thread.checkpoints[0]?.checkpointTurnCount).toBe(1);
-    expect(
-      thread.activities.some((activity) => activity.kind === "checkpoint.capture.failed"),
-    ).toBe(true);
-  });
+      emit("turn.started", 3);
+      yield* Effect.promise(harness.drain);
+      NodeFS.writeFileSync(NodePath.join(harness.cwd, "README.md"), "next turn\n");
+      emit("turn.completed", 3);
+      expect(yield* harness.nextReceipt).toMatchObject({
+        type: "checkpoint.diff.finalized",
+        checkpointTurnCount: 2,
+      });
+      yield* Effect.promise(harness.drain);
+      const thread = (yield* Effect.promise(harness.readModel)).threads[0];
+      expect(thread?.checkpoints[1]?.files).toEqual([
+        { path: "README.md", kind: "modified", additions: 1, deletions: 1 },
+      ]);
+      expect(
+        thread?.activities.some((activity) => activity.kind === "checkpoint.capture.failed"),
+      ).toBe(false);
+    }),
+  );
 
   it("captures pre-turn baseline from project workspace root when thread worktree is unset", async () => {
     const harness = await createHarness({
@@ -963,6 +1342,36 @@ describe("CheckpointReactor", () => {
     ).toBe("v1\n");
   });
 
+  it("does not create checkpoints while importing historical user messages", async () => {
+    const harness = await createHarness({
+      hasSession: false,
+      seedFilesystemCheckpoints: false,
+      threadWorktreePath: null,
+    });
+    if (runtime === null) throw new Error("Checkpoint test runtime was not initialized.");
+
+    await runtime.runPromise(
+      harness.engine.dispatch({
+        type: "thread.history.import",
+        commandId: CommandId.make("cmd-import-history-without-checkpoint"),
+        threadId: ThreadId.make("thread-1"),
+        messages: [
+          {
+            messageId: MessageId.make("imported-user-message"),
+            role: "user",
+            text: "A message from an existing agent session",
+            createdAt: "2026-01-01T00:00:00.000Z",
+          },
+        ],
+      }),
+    );
+    await harness.drain();
+
+    expect(
+      gitRefExists(harness.cwd, checkpointRefForThreadTurn(ThreadId.make("thread-1"), 0)),
+    ).toBe(false);
+  });
+
   it("captures turn completion checkpoint from project workspace root when provider session cwd is unavailable", async () => {
     const harness = await createHarness({
       hasSession: false,
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
index aa0e233a5dc3..0331b0141fb3 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
@@ -21,7 +21,7 @@ import * as Stream from "effect/Stream";
 import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
 import { isTemporaryWorktreeBranch } from "@t3tools/shared/git";
 
-import { parseTurnDiffFilesFromUnifiedDiff } from "../../checkpointing/Diffs.ts";
+import { parseTurnDiffFilesFromNumstat } from "../../checkpointing/Diffs.ts";
 import {
   checkpointRefForThreadTurn,
   resolveThreadWorkspaceCwd,
@@ -35,7 +35,6 @@ import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts"
 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 { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
 import * as WorkspaceEntries from "../../workspace/WorkspaceEntries.ts";
 import * as PullRequestService from "../../pullRequest/PullRequestService.ts";
@@ -181,8 +180,6 @@ const make = Effect.gen(function* () {
     return project ? [project] : [];
   });
 
-  const isGitWorkspace = (cwd: string) => isGitRepository(cwd);
-
   // Resolves the workspace CWD for checkpoint operations, preferring the
   // active provider session CWD and falling back to the thread/project config.
   // Returns undefined when no CWD can be determined or the workspace is not
@@ -192,7 +189,7 @@ const make = Effect.gen(function* () {
     readonly thread: { readonly projectId: ProjectId; readonly worktreePath: string | null };
     readonly projects: ReadonlyArray<{ readonly id: ProjectId; readonly workspaceRoot: string }>;
     readonly preferSessionRuntime: boolean;
-  }): Effect.fn.Return<string | undefined> {
+  }): Effect.fn.Return<string | undefined, CheckpointStoreError> {
     const fromSession = yield* resolveSessionRuntimeForThread(input.threadId);
     const fromThread = resolveThreadWorkspaceCwd({
       thread: input.thread,
@@ -213,15 +210,13 @@ const make = Effect.gen(function* () {
     if (!cwd) {
       return undefined;
     }
-    if (!isGitWorkspace(cwd)) {
+    if (!(yield* checkpointStore.isGitRepository(cwd))) {
       return undefined;
     }
     return cwd;
   });
 
-  // Shared tail for both capture paths: creates the git checkpoint ref, diffs
-  // it against the previous turn, then dispatches the domain events to update
-  // the orchestration read model.
+  // Capture the completed turn's files, then publish its summary and receipts.
   const captureAndDispatchCheckpoint = Effect.fn("captureAndDispatchCheckpoint")(function* (input: {
     readonly threadId: ThreadId;
     readonly turnId: TurnId;
@@ -263,40 +258,46 @@ const make = Effect.gen(function* () {
     // reflects files created or deleted during this turn.
     yield* workspaceEntries.refresh(input.cwd);
 
-    const files = yield* checkpointStore
-      .diffCheckpoints({
-        cwd: input.cwd,
-        fromCheckpointRef,
-        toCheckpointRef: targetCheckpointRef,
-        fallbackFromToHead: false,
-        ignoreWhitespace: false,
-      })
-      .pipe(
-        Effect.map((diff) =>
-          parseTurnDiffFilesFromUnifiedDiff(diff).map((file) => ({
-            path: file.path,
-            kind: "modified" as const,
-            additions: file.additions,
-            deletions: file.deletions,
-          })),
-        ),
-        Effect.tapError((error) =>
-          appendCaptureFailureActivity({
-            threadId: input.threadId,
-            turnId: input.turnId,
-            detail: `Checkpoint captured, but turn diff summary is unavailable: ${error.message}`,
-            createdAt: input.createdAt,
-          }),
-        ),
-        Effect.catch((error) =>
-          Effect.logWarning("failed to derive checkpoint file summary", {
-            threadId: input.threadId,
-            turnId: input.turnId,
-            turnCount: input.turnCount,
-            detail: error.message,
-          }).pipe(Effect.as([])),
-        ),
-      );
+    // Git may have been initialized during this turn, leaving no pre-turn
+    // snapshot. Keep the completion checkpoint for future turns, but do not
+    // invent a baseline or attempt a diff against a ref that does not exist.
+    const files = yield* (
+      fromCheckpointExists
+        ? checkpointStore.diffCheckpoints({
+            cwd: input.cwd,
+            fromCheckpointRef,
+            toCheckpointRef: targetCheckpointRef,
+            fallbackFromToHead: false,
+            ignoreWhitespace: false,
+            format: "numstat",
+          })
+        : Effect.succeed("")
+    ).pipe(
+      Effect.map((diff) =>
+        parseTurnDiffFilesFromNumstat(diff).map((file) => ({
+          path: file.path,
+          kind: "modified" as const,
+          additions: file.additions,
+          deletions: file.deletions,
+        })),
+      ),
+      Effect.tapError((error) =>
+        appendCaptureFailureActivity({
+          threadId: input.threadId,
+          turnId: input.turnId,
+          detail: `Checkpoint captured, but turn diff summary is unavailable: ${error.message}`,
+          createdAt: input.createdAt,
+        }),
+      ),
+      Effect.catch((error) =>
+        Effect.logWarning("failed to derive checkpoint file summary", {
+          threadId: input.threadId,
+          turnId: input.turnId,
+          turnCount: input.turnCount,
+          detail: error.message,
+        }).pipe(Effect.as([])),
+      ),
+    );
 
     const assistantMessageId =
       input.assistantMessageId ??
@@ -355,9 +356,9 @@ const make = Effect.gen(function* () {
     });
   });
 
-  // Captures a real git checkpoint when a turn completes via a runtime event.
+  // Capture the files left by a completed or interrupted turn.
   const captureCheckpointFromTurnCompletion = Effect.fn("captureCheckpointFromTurnCompletion")(
-    function* (event: Extract<ProviderRuntimeEvent, { type: "turn.completed" }>) {
+    function* (event: Extract<ProviderRuntimeEvent, { type: "turn.completed" | "turn.aborted" }>) {
       const turnId = toTurnId(event.turnId);
       if (!turnId) {
         return;
@@ -414,75 +415,16 @@ const make = Effect.gen(function* () {
         thread,
         cwd: checkpointCwd,
         turnCount: nextTurnCount,
-        status: checkpointStatusFromRuntime(event.payload.state),
-        assistantMessageId: undefined,
+        status:
+          event.type === "turn.aborted"
+            ? "ready"
+            : checkpointStatusFromRuntime(event.payload.state),
+        assistantMessageId: existingPlaceholder?.assistantMessageId ?? undefined,
         createdAt: event.createdAt,
       });
     },
   );
 
-  // Captures a real git checkpoint when a placeholder checkpoint (status "missing")
-  // is detected via a domain event. This replaces the placeholder with a real
-  // git-ref-based checkpoint.
-  //
-  // ProviderRuntimeIngestion creates placeholder checkpoints on turn.diff.updated
-  // events from the Codex runtime. This handler fires when the corresponding
-  // domain event arrives, allowing the reactor to capture the actual filesystem
-  // state into a git ref and dispatch a replacement checkpoint.
-  const captureCheckpointFromPlaceholder = Effect.fn("captureCheckpointFromPlaceholder")(function* (
-    event: Extract<OrchestrationEvent, { type: "thread.turn-diff-completed" }>,
-  ) {
-    const { threadId, turnId, checkpointTurnCount, status } = event.payload;
-
-    // Only replace placeholders; skip events from our own real captures.
-    if (status !== "missing") {
-      return;
-    }
-
-    const thread = yield* resolveThreadDetail(threadId);
-    if (!thread) {
-      yield* Effect.logWarning("checkpoint capture from placeholder skipped: thread not found", {
-        threadId,
-      });
-      return;
-    }
-
-    // If a real checkpoint already exists for this turn, skip.
-    if (
-      thread.checkpoints.some(
-        (checkpoint) => checkpoint.turnId === turnId && checkpoint.status !== "missing",
-      )
-    ) {
-      yield* Effect.logDebug(
-        "checkpoint capture from placeholder skipped: real checkpoint already exists",
-        { threadId, turnId },
-      );
-      return;
-    }
-
-    const projects = yield* resolveThreadProjects(thread.projectId);
-    const checkpointCwd = yield* resolveCheckpointCwd({
-      threadId,
-      thread,
-      projects,
-      preferSessionRuntime: true,
-    });
-    if (!checkpointCwd) {
-      return;
-    }
-
-    yield* captureAndDispatchCheckpoint({
-      threadId,
-      turnId,
-      thread,
-      cwd: checkpointCwd,
-      turnCount: checkpointTurnCount,
-      status: "ready",
-      assistantMessageId: event.payload.assistantMessageId ?? undefined,
-      createdAt: event.payload.completedAt,
-    });
-  });
-
   const ensurePreTurnBaselineFromTurnStart = Effect.fn("ensurePreTurnBaselineFromTurnStart")(
     function* (event: Extract<ProviderRuntimeEvent, { type: "turn.started" }>) {
       const turnId = toTurnId(event.turnId);
@@ -673,6 +615,7 @@ const make = Effect.gen(function* () {
   ) {
     if (event.type === "thread.message-sent") {
       if (
+        event.metadata.historyImport === true ||
         event.payload.role !== "user" ||
         event.payload.streaming ||
         event.payload.turnId !== null
@@ -750,7 +693,7 @@ const make = Effect.gen(function* () {
       }).pipe(Effect.catch(() => Effect.void));
       return;
     }
-    if (!isGitWorkspace(sessionRuntime.value.cwd)) {
+    if (!(yield* checkpointStore.isGitRepository(sessionRuntime.value.cwd))) {
       yield* appendRevertFailureActivity({
         threadId: event.payload.threadId,
         turnCount: event.payload.turnCount,
@@ -878,25 +821,6 @@ const make = Effect.gen(function* () {
       );
       return;
     }
-
-    // When ProviderRuntimeIngestion creates a placeholder checkpoint (status "missing")
-    // from a turn.diff.updated runtime event, capture the real git checkpoint to
-    // replace it. ProviderService broadcasts runtime events to each subscriber.
-    // This domain-event path also captures checkpoints from turn diff updates.
-    if (event.type === "thread.turn-diff-completed") {
-      yield* captureCheckpointFromPlaceholder(event).pipe(
-        Effect.catch((error) =>
-          Effect.flatMap(nowIso, (createdAt) =>
-            appendCaptureFailureActivity({
-              threadId: event.payload.threadId,
-              turnId: event.payload.turnId,
-              detail: error.message,
-              createdAt,
-            }).pipe(Effect.catch(() => Effect.void)),
-          ),
-        ),
-      );
-    }
   });
 
   const processRuntimeEvent = Effect.fn("processRuntimeEvent")(function* (
@@ -941,7 +865,13 @@ const make = Effect.gen(function* () {
         pending.delete(event.threadId);
         yield* pullRequests.refreshAfterTurn;
       }
-      if (event.type === "turn.aborted") return;
+      if (
+        event.type === "turn.aborted" &&
+        !isTrackedTurn &&
+        !sameId(thread?.session?.activeTurnId, turnId)
+      ) {
+        return;
+      }
       yield* captureCheckpointFromTurnCompletion(event).pipe(
         Effect.catch((error) =>
           Effect.flatMap(nowIso, (createdAt) =>
@@ -989,8 +919,7 @@ const make = Effect.gen(function* () {
         if (
           event.type !== "thread.turn-start-requested" &&
           event.type !== "thread.message-sent" &&
-          event.type !== "thread.checkpoint-revert-requested" &&
-          event.type !== "thread.turn-diff-completed"
+          event.type !== "thread.checkpoint-revert-requested"
         ) {
           return Effect.void;
         }
diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
index d3d766084a28..abfb49b53050 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts
@@ -325,6 +325,8 @@ describe("OrchestrationEngine", () => {
           }),
         ),
       hasEventAfter: () => Effect.succeed(false),
+      readAggregateRange: () => Stream.die("unused aggregate replay"),
+      getAggregateReplayStats: () => Effect.die("unused aggregate replay stats"),
     };
 
     const projectionSnapshot = {
@@ -416,8 +418,10 @@ describe("OrchestrationEngine", () => {
           getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
           getProjectShellById: () => Effect.succeed(Option.none()),
           getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+          getImportedAgentSessionSources: () => Effect.die("unused"),
           getThreadCheckpointContext: () => Effect.succeed(Option.none()),
           getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+          getThreadRuntimeContext: () => Effect.die("unused"),
           getThreadShellById: () => Effect.succeed(Option.none()),
           getThreadDetailById: () => Effect.succeed(Option.none()),
           getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
@@ -1234,6 +1238,8 @@ describe("OrchestrationEngine", () => {
         return Stream.fromIterable(events);
       },
       hasEventAfter: () => Effect.succeed(false),
+      readAggregateRange: () => Stream.die("unused aggregate replay"),
+      getAggregateReplayStats: () => Effect.die("unused aggregate replay stats"),
     };
 
     const ServerConfigLayer = ServerConfig.layerTest(process.cwd(), {
@@ -1472,6 +1478,8 @@ describe("OrchestrationEngine", () => {
         return Stream.fromIterable(events);
       },
       hasEventAfter: () => Effect.succeed(false),
+      readAggregateRange: () => Stream.die("unused aggregate replay"),
+      getAggregateReplayStats: () => Effect.die("unused aggregate replay stats"),
     };
 
     let shouldFailProjection = true;
diff --git a/apps/server/src/orchestration/Layers/OrchestrationEngine.ts b/apps/server/src/orchestration/Layers/OrchestrationEngine.ts
index 792dd0da3900..8512007ae8d3 100644
--- a/apps/server/src/orchestration/Layers/OrchestrationEngine.ts
+++ b/apps/server/src/orchestration/Layers/OrchestrationEngine.ts
@@ -381,6 +381,19 @@ const makeOrchestrationEngine = Effect.gen(function* () {
   const readEvents: OrchestrationEngineShape["readEvents"] = (fromSequenceExclusive, limit) =>
     eventStore.readFromSequence(fromSequenceExclusive, limit);
 
+  const readThreadEvents: OrchestrationEngineShape["readThreadEvents"] = ({ threadId, ...range }) =>
+    eventStore.readAggregateRange({ ...range, aggregateKind: "thread", aggregateId: threadId });
+
+  const getThreadReplayStats: OrchestrationEngineShape["getThreadReplayStats"] = ({
+    threadId,
+    ...range
+  }) =>
+    eventStore.getAggregateReplayStats({
+      ...range,
+      aggregateKind: "thread",
+      aggregateId: threadId,
+    });
+
   const dispatch: OrchestrationEngineShape["dispatch"] = (command, options) =>
     Effect.gen(function* () {
       const result = yield* Deferred.make<{ sequence: number }, OrchestrationDispatchError>();
@@ -395,6 +408,8 @@ const makeOrchestrationEngine = Effect.gen(function* () {
 
   return {
     readEvents,
+    readThreadEvents,
+    getThreadReplayStats,
     dispatch,
     subscribeDomainEvents: PubSub.subscribe(eventPubSub).pipe(Effect.map(Stream.fromSubscription)),
     // Each access creates a fresh PubSub subscription so that multiple
diff --git a/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
index 1b8a451175f3..d81d9b11b1f6 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts
@@ -1,4 +1,5 @@
 import {
+  ApprovalRequestId,
   CheckpointRef,
   CommandId,
   CorrelationId,
@@ -19,6 +20,7 @@ import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
+import { makeSqlStatementCounter } from "../../../integration/SqlStatementCounter.integration.ts";
 import { OrchestrationCommandReceiptRepositoryLive } from "../../persistence/Layers/OrchestrationCommandReceipts.ts";
 import { OrchestrationEventStoreLive } from "../../persistence/Layers/OrchestrationEventStore.ts";
 import {
@@ -26,6 +28,7 @@ import {
   SqlitePersistenceMemory,
 } from "../../persistence/Layers/Sqlite.ts";
 import { OrchestrationEventStore } from "../../persistence/Services/OrchestrationEventStore.ts";
+import { ProjectionStateRepository } from "../../persistence/Services/ProjectionState.ts";
 import * as RepositoryIdentityResolver from "../../project/RepositoryIdentityResolver.ts";
 import { OrchestrationEngineLive } from "./OrchestrationEngine.ts";
 import {
@@ -57,6 +60,150 @@ const exists = (filePath: string) =>
 
 const BaseTestLayer = makeProjectionPipelinePrefixedTestLayer("t3-projection-pipeline-test-");
 
+it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-projection-cursor-batch-")))(
+  "OrchestrationProjectionPipeline cursor batches",
+  (it) => {
+    it.effect("writes a project and all projector cursors in two statements", () =>
+      Effect.gen(function* () {
+        const projectionPipeline = yield* OrchestrationProjectionPipeline;
+        const eventStore = yield* OrchestrationEventStore;
+        const projectionState = yield* ProjectionStateRepository;
+        const counter = makeSqlStatementCounter();
+        const createdAt = "2026-01-01T00:00:00.000Z";
+        const event = yield* eventStore.append({
+          type: "project.created",
+          eventId: EventId.make("evt-cursor-batch-project"),
+          aggregateKind: "project",
+          aggregateId: ProjectId.make("project-cursor-batch"),
+          occurredAt: createdAt,
+          commandId: CommandId.make("cmd-cursor-batch-project"),
+          causationEventId: null,
+          correlationId: null,
+          metadata: {},
+          payload: {
+            projectId: ProjectId.make("project-cursor-batch"),
+            title: "Cursor batch project",
+            workspaceRoot: "/tmp/project-cursor-batch",
+            defaultModelSelection: null,
+            scripts: [],
+            createdAt,
+            updatedAt: createdAt,
+          },
+        });
+
+        yield* projectionPipeline.projectEvent(event).pipe(Effect.withTracer(counter.tracer));
+        assert.strictEqual(counter.count(), 2);
+        assert.deepEqual(
+          yield* projectionState.listAll(),
+          Object.values(ORCHESTRATION_PROJECTOR_NAMES)
+            .sort()
+            .map((projector) => ({
+              projector,
+              lastAppliedSequence: event.sequence,
+              updatedAt: createdAt,
+            })),
+        );
+      }),
+    );
+  },
+);
+
+it.layer(Layer.fresh(makeProjectionPipelinePrefixedTestLayer("t3-import-shell-")))(
+  "imported thread shell projection",
+  (it) => {
+    it.effect("does not mark imported user messages as queued work in thread shells", () =>
+      Effect.gen(function* () {
+        const projectionPipeline = yield* OrchestrationProjectionPipeline;
+        const eventStore = yield* OrchestrationEventStore;
+        const sql = yield* SqlClient.SqlClient;
+        const createdAt = "2026-08-24T10:00:00.000Z";
+        const threadId = ThreadId.make("import:codex:shell-session");
+
+        yield* eventStore.append({
+          type: "thread.created",
+          eventId: EventId.make("evt-import-shell-thread"),
+          aggregateKind: "thread",
+          aggregateId: threadId,
+          occurredAt: createdAt,
+          commandId: CommandId.make("cmd-import-shell-thread"),
+          causationEventId: null,
+          correlationId: CommandId.make("cmd-import-shell-thread"),
+          metadata: {},
+          payload: {
+            threadId,
+            projectId: ProjectId.make("project-import-shell"),
+            title: "Imported thread",
+            modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
+            runtimeMode: "full-access",
+            interactionMode: "default",
+            branch: null,
+            worktreePath: null,
+            createdAt,
+            updatedAt: createdAt,
+          },
+        });
+        yield* eventStore.append({
+          type: "thread.message-sent",
+          eventId: EventId.make("evt-import-shell-message"),
+          aggregateKind: "thread",
+          aggregateId: threadId,
+          occurredAt: createdAt,
+          commandId: CommandId.make("cmd-import-shell-message"),
+          causationEventId: null,
+          correlationId: CommandId.make("cmd-import-shell-message"),
+          metadata: { historyImport: true },
+          payload: {
+            threadId,
+            messageId: MessageId.make("import:codex:shell-session:0"),
+            role: "user",
+            text: "Imported user prompt",
+            turnId: null,
+            streaming: false,
+            createdAt,
+            updatedAt: createdAt,
+          },
+        });
+
+        yield* projectionPipeline.bootstrap;
+
+        const readLatestUserMessageAt = sql<{ readonly latestUserMessageAt: string | null }>`
+        SELECT latest_user_message_at AS "latestUserMessageAt"
+        FROM projection_threads
+        WHERE thread_id = ${threadId}
+      `;
+        assert.deepEqual(yield* readLatestUserMessageAt, [{ latestUserMessageAt: null }]);
+
+        const sessionEvent = yield* eventStore.append({
+          type: "thread.session-set",
+          eventId: EventId.make("evt-import-shell-session"),
+          aggregateKind: "thread",
+          aggregateId: threadId,
+          occurredAt: createdAt,
+          commandId: CommandId.make("cmd-import-shell-session"),
+          causationEventId: null,
+          correlationId: CommandId.make("cmd-import-shell-session"),
+          metadata: {},
+          payload: {
+            threadId,
+            session: {
+              threadId,
+              status: "ready",
+              providerName: "codex",
+              providerInstanceId: ProviderInstanceId.make("codex"),
+              runtimeMode: "full-access",
+              activeTurnId: null,
+              lastError: null,
+              updatedAt: createdAt,
+            },
+          },
+        });
+        yield* projectionPipeline.projectEvent(sessionEvent);
+        assert.deepEqual(yield* readLatestUserMessageAt, [{ latestUserMessageAt: null }]);
+      }),
+    );
+  },
+);
+
 it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
   it.effect("bootstraps all projection states and writes projection rows", () =>
     Effect.gen(function* () {
@@ -812,6 +959,8 @@ it.layer(
         },
       });
 
+      const projectionState = yield* ProjectionStateRepository;
+      const cursorsBeforeFailure = yield* projectionState.listAll();
       yield* sql`
         CREATE TRIGGER fail_thread_messages_projection_state_update
         BEFORE UPDATE ON projection_state
@@ -821,39 +970,39 @@ it.layer(
         END;
       `;
 
-      const result = yield* Effect.result(
-        appendAndProject({
-          type: "thread.message-sent",
-          eventId: EventId.make("evt-rollback-3"),
-          aggregateKind: "thread",
-          aggregateId: ThreadId.make("thread-rollback"),
-          occurredAt: now,
-          commandId: CommandId.make("cmd-rollback-3"),
-          causationEventId: null,
-          correlationId: CorrelationId.make("cmd-rollback-3"),
-          metadata: {},
-          payload: {
-            threadId: ThreadId.make("thread-rollback"),
-            messageId: MessageId.make("message-rollback"),
-            role: "user",
-            text: "Rollback me",
-            attachments: [
-              {
-                type: "image",
-                id: "thread-rollback-att-1",
-                name: "rollback.png",
-                mimeType: "image/png",
-                sizeBytes: 5,
-              },
-            ],
-            turnId: null,
-            streaming: false,
-            createdAt: now,
-            updatedAt: now,
-          },
-        }),
-      );
+      const pendingEvent = yield* eventStore.append({
+        type: "thread.message-sent",
+        eventId: EventId.make("evt-rollback-3"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-rollback"),
+        occurredAt: now,
+        commandId: CommandId.make("cmd-rollback-3"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-rollback-3"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-rollback"),
+          messageId: MessageId.make("message-rollback"),
+          role: "user",
+          text: "Rollback me",
+          attachments: [
+            {
+              type: "image",
+              id: "thread-rollback-att-1",
+              name: "rollback.png",
+              mimeType: "image/png",
+              sizeBytes: 5,
+            },
+          ],
+          turnId: null,
+          streaming: false,
+          createdAt: now,
+          updatedAt: now,
+        },
+      });
+      const result = yield* Effect.result(projectionPipeline.projectEvent(pendingEvent));
       assert.equal(result._tag, "Failure");
+      assert.deepEqual(yield* projectionState.listAll(), cursorsBeforeFailure);
 
       const rows = yield* sql<{
         readonly count: number;
@@ -868,6 +1017,21 @@ it.layer(
       const attachmentPath = path.join(attachmentsDir, "thread-rollback-att-1.png");
       assert.isFalse(yield* exists(attachmentPath));
       yield* sql`DROP TRIGGER IF EXISTS fail_thread_messages_projection_state_update`;
+
+      yield* projectionPipeline.bootstrap;
+      yield* projectionPipeline.bootstrap;
+      assert.deepEqual(
+        yield* projectionState.listAll(),
+        cursorsBeforeFailure.map((cursor) => ({
+          ...cursor,
+          lastAppliedSequence: pendingEvent.sequence,
+          updatedAt: pendingEvent.occurredAt,
+        })),
+      );
+      const replayedMessages = yield* sql<{ readonly text: string }>`
+        SELECT text FROM projection_thread_messages WHERE message_id = 'message-rollback'
+      `;
+      assert.deepEqual(replayedMessages, [{ text: "Rollback me" }]);
     }),
   );
 });
@@ -2533,7 +2697,7 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
     }),
   );
 
-  it.effect("maintains shell summary fields across message and activity streams", () =>
+  it.effect("maintains shell summaries without reading message bodies", () =>
     Effect.gen(function* () {
       const projectionPipeline = yield* OrchestrationProjectionPipeline;
       const eventStore = yield* OrchestrationEventStore;
@@ -2741,10 +2905,110 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
           updatedAt: "2026-03-01T08:00:05.000Z",
         },
       ]);
+
+      // Summary refreshes must not decode message bodies or attachment metadata.
+      yield* sql`
+        UPDATE projection_thread_messages
+        SET attachments_json = '{not-json'
+        WHERE thread_id = 'thread-shell-summary'
+      `;
+      yield* sql`
+        INSERT INTO projection_pending_approvals (
+          request_id, thread_id, turn_id, status, decision, created_at, resolved_at
+        ) VALUES
+          ('summary-pending', 'thread-shell-summary', NULL, 'pending', NULL,
+           '2026-03-01T08:00:06.000Z', NULL),
+          ('summary-resolved', 'thread-shell-summary', NULL, 'resolved', 'accept',
+           '2026-03-01T08:00:06.000Z', '2026-03-01T08:00:06.000Z'),
+          ('summary-other-thread', 'thread-shell-summary-other', NULL, 'pending', NULL,
+           '2026-03-01T08:00:06.000Z', NULL)
+      `;
+      yield* sql`
+        INSERT INTO projection_thread_proposed_plans (
+          plan_id, thread_id, turn_id, plan_markdown, implemented_at,
+          implementation_thread_id, created_at, updated_at
+        ) VALUES (
+          'summary-plan', 'thread-shell-summary', 'turn-shell-summary-1', '# Plan', NULL,
+          NULL, '2026-03-01T08:00:06.000Z', '2026-03-01T08:00:06.000Z'
+        )
+      `;
+
+      const refreshEvents = [
+        {
+          type: "thread.session-set",
+          eventId: EventId.make("evt-shell-summary-7"),
+          aggregateKind: "thread",
+          aggregateId: ThreadId.make("thread-shell-summary"),
+          occurredAt: "2026-03-01T08:00:07.000Z",
+          commandId: CommandId.make("cmd-shell-summary-7"),
+          causationEventId: null,
+          correlationId: CorrelationId.make("cmd-shell-summary-7"),
+          metadata: {},
+          payload: {
+            threadId: ThreadId.make("thread-shell-summary"),
+            session: {
+              threadId: ThreadId.make("thread-shell-summary"),
+              status: "ready",
+              providerName: "codex",
+              runtimeMode: "approval-required",
+              activeTurnId: null,
+              lastError: null,
+              updatedAt: "2026-03-01T08:00:07.000Z",
+            },
+          },
+        },
+        {
+          type: "thread.turn-diff-completed",
+          eventId: EventId.make("evt-shell-summary-8"),
+          aggregateKind: "thread",
+          aggregateId: ThreadId.make("thread-shell-summary"),
+          occurredAt: "2026-03-01T08:00:08.000Z",
+          commandId: CommandId.make("cmd-shell-summary-8"),
+          causationEventId: null,
+          correlationId: CorrelationId.make("cmd-shell-summary-8"),
+          metadata: {},
+          payload: {
+            threadId: ThreadId.make("thread-shell-summary"),
+            turnId: TurnId.make("turn-shell-summary-1"),
+            checkpointTurnCount: 1,
+            checkpointRef: CheckpointRef.make("refs/t3/checkpoints/thread-shell-summary/1"),
+            status: "ready",
+            files: [],
+            assistantMessageId: MessageId.make("message-shell-summary-assistant"),
+            completedAt: "2026-03-01T08:00:08.000Z",
+          },
+        },
+      ] satisfies ReadonlyArray<Parameters<typeof eventStore.append>[0]>;
+
+      for (const event of refreshEvents) {
+        yield* appendAndProject(event);
+        const summary = yield* sql<{
+          readonly latestUserMessageAt: string | null;
+          readonly pendingApprovalCount: number;
+          readonly pendingUserInputCount: number;
+          readonly hasActionableProposedPlan: number;
+        }>`
+          SELECT
+            latest_user_message_at AS "latestUserMessageAt",
+            pending_approval_count AS "pendingApprovalCount",
+            pending_user_input_count AS "pendingUserInputCount",
+            has_actionable_proposed_plan AS "hasActionableProposedPlan"
+          FROM projection_threads
+          WHERE thread_id = 'thread-shell-summary'
+        `;
+        assert.deepEqual(summary, [
+          {
+            latestUserMessageAt: "2026-03-01T08:00:02.000Z",
+            pendingApprovalCount: 1,
+            pendingUserInputCount: 1,
+            hasActionableProposedPlan: 1,
+          },
+        ]);
+      }
     }),
   );
 
-  it.effect("ignores non-stale provider approval response failures", () =>
+  it.effect("restores pending approvals when a provider reply fails", () =>
     Effect.gen(function* () {
       const projectionPipeline = yield* OrchestrationProjectionPipeline;
       const eventStore = yield* OrchestrationEventStore;
@@ -2829,6 +3093,24 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
         },
       });
 
+      yield* appendAndProject({
+        type: "thread.approval-response-requested",
+        eventId: EventId.make("evt-nonstale-approval-response"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-nonstale-approval"),
+        occurredAt: "2026-02-26T12:45:02.500Z",
+        commandId: CommandId.make("cmd-nonstale-approval-response"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-nonstale-approval-response"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-nonstale-approval"),
+          requestId: ApprovalRequestId.make("approval-request-nonstale-existing"),
+          decision: "accept",
+          createdAt: "2026-02-26T12:45:02.500Z",
+        },
+      });
+
       yield* appendAndProject({
         type: "thread.activity-appended",
         eventId: EventId.make("evt-nonstale-approval-4"),
@@ -2921,6 +3203,67 @@ it.layer(BaseTestLayer)("OrchestrationProjectionPipeline", (it) => {
         WHERE thread_id = 'thread-nonstale-approval'
       `;
       assert.deepEqual(threadRows, [{ pendingApprovalCount: 1 }]);
+
+      yield* appendAndProject({
+        type: "thread.activity-appended",
+        eventId: EventId.make("evt-nonstale-approval-resolved"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-nonstale-approval"),
+        occurredAt: "2026-02-26T12:45:05.000Z",
+        commandId: CommandId.make("cmd-nonstale-approval-resolved"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-nonstale-approval-resolved"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-nonstale-approval"),
+          activity: {
+            id: EventId.make("activity-nonstale-approval-resolved"),
+            tone: "approval",
+            kind: "approval.resolved",
+            summary: "Approval resolved",
+            payload: {
+              requestId: "approval-request-nonstale-existing",
+              decision: "accept",
+            },
+            turnId: null,
+            createdAt: "2026-02-26T12:45:05.000Z",
+          },
+        },
+      });
+
+      yield* appendAndProject({
+        type: "thread.activity-appended",
+        eventId: EventId.make("evt-nonstale-approval-late-failure"),
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-nonstale-approval"),
+        occurredAt: "2026-02-26T12:45:06.000Z",
+        commandId: CommandId.make("cmd-nonstale-approval-late-failure"),
+        causationEventId: null,
+        correlationId: CorrelationId.make("cmd-nonstale-approval-late-failure"),
+        metadata: {},
+        payload: {
+          threadId: ThreadId.make("thread-nonstale-approval"),
+          activity: {
+            id: EventId.make("activity-nonstale-approval-late-failure"),
+            tone: "error",
+            kind: "provider.approval.respond.failed",
+            summary: "Provider approval response failed",
+            payload: {
+              requestId: "approval-request-nonstale-existing",
+              detail: "Provider timed out while responding to approval request",
+            },
+            turnId: null,
+            createdAt: "2026-02-26T12:45:06.000Z",
+          },
+        },
+      });
+
+      const resolvedThreadRows = yield* sql<{ readonly pendingApprovalCount: number }>`
+        SELECT pending_approval_count AS "pendingApprovalCount"
+        FROM projection_threads
+        WHERE thread_id = 'thread-nonstale-approval'
+      `;
+      assert.deepEqual(resolvedThreadRows, [{ pendingApprovalCount: 0 }]);
     }),
   );
 
@@ -3708,6 +4051,14 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
 
       yield* fileSystem.makeDirectory(attachmentsDir, { recursive: true });
       yield* fileSystem.writeFileString(attachmentPath, "keep this attachment");
+      const readCursors = sql<{
+        readonly projector: string;
+        readonly lastAppliedSequence: number;
+      }>`
+        SELECT projector, last_applied_sequence AS "lastAppliedSequence"
+        FROM projection_state ORDER BY projector
+      `;
+      const cursorsBeforeFailure = yield* readCursors;
       yield* sql`
         CREATE TRIGGER fail_attachment_command_receipt
         BEFORE INSERT ON orchestration_command_receipts
@@ -3719,6 +4070,7 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
       const deleteCommand = { type: "thread.delete", commandId, threadId } as const;
       const dispatchError = yield* engine.dispatch(deleteCommand).pipe(Effect.flip);
       assert.equal(dispatchError._tag, "PersistenceSqlError");
+      assert.deepEqual(yield* readCursors, cursorsBeforeFailure);
       assert.equal(yield* fileSystem.readFileString(attachmentPath), "keep this attachment");
       const rolledBackThreads = yield* sql<{ readonly deletedAt: string | null }>`
         SELECT deleted_at AS "deletedAt" FROM projection_threads WHERE thread_id = ${threadId}
@@ -3735,6 +4087,13 @@ engineLayer("OrchestrationProjectionPipeline via engine dispatch", (it) => {
       yield* sql`DROP TRIGGER fail_attachment_command_receipt`;
 
       const result = yield* engine.dispatch(deleteCommand);
+      assert.deepEqual(
+        yield* readCursors,
+        cursorsBeforeFailure.map((cursor) => ({
+          ...cursor,
+          lastAppliedSequence: result.sequence,
+        })),
+      );
       assert.isFalse(yield* exists(attachmentPath));
       const committedReceipts = yield* sql<{
         readonly status: string;
diff --git a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
index 1ba1b6afa4f3..b338596993d2 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
@@ -1,10 +1,12 @@
 import {
   ApprovalRequestId,
+  isImportedAgentSessionMessageId,
   type ChatAttachment,
   type OrchestrationEvent,
   type OrchestrationSessionStatus,
   ThreadId,
 } from "@t3tools/contracts";
+import { compareDateTimeStrings } from "@t3tools/shared/dateTime";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
@@ -248,7 +250,7 @@ function retainProjectionMessagesAfterRevert(
   }
 
   for (const message of messages) {
-    if (message.role === "system") {
+    if (message.role === "system" || isImportedAgentSessionMessageId(message.messageId)) {
       retainedMessageIds.add(message.messageId);
       continue;
     }
@@ -258,7 +260,10 @@ function retainProjectionMessagesAfterRevert(
   }
 
   const retainedUserCount = messages.filter(
-    (message) => message.role === "user" && retainedMessageIds.has(message.messageId),
+    (message) =>
+      message.role === "user" &&
+      !isImportedAgentSessionMessageId(message.messageId) &&
+      retainedMessageIds.has(message.messageId),
   ).length;
   const missingUserCount = Math.max(0, turnCount - retainedUserCount);
   if (missingUserCount > 0) {
@@ -271,7 +276,7 @@ function retainProjectionMessagesAfterRevert(
       )
       .toSorted(
         (left, right) =>
-          left.createdAt.localeCompare(right.createdAt) ||
+          compareDateTimeStrings(left.createdAt, right.createdAt) ||
           left.messageId.localeCompare(right.messageId),
       )
       .slice(0, missingUserCount);
@@ -281,7 +286,10 @@ function retainProjectionMessagesAfterRevert(
   }
 
   const retainedAssistantCount = messages.filter(
-    (message) => message.role === "assistant" && retainedMessageIds.has(message.messageId),
+    (message) =>
+      message.role === "assistant" &&
+      !isImportedAgentSessionMessageId(message.messageId) &&
+      retainedMessageIds.has(message.messageId),
   ).length;
   const missingAssistantCount = Math.max(0, turnCount - retainedAssistantCount);
   if (missingAssistantCount > 0) {
@@ -294,7 +302,7 @@ function retainProjectionMessagesAfterRevert(
       )
       .toSorted(
         (left, right) =>
-          left.createdAt.localeCompare(right.createdAt) ||
+          compareDateTimeStrings(left.createdAt, right.createdAt) ||
           left.messageId.localeCompare(right.messageId),
       )
       .slice(0, missingAssistantCount);
@@ -587,26 +595,14 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
         return;
       }
 
-      const [messages, proposedPlans, activities, pendingApprovals] = yield* Effect.all([
-        projectionThreadMessageRepository.listByThreadId({ threadId }),
-        projectionThreadProposedPlanRepository.listByThreadId({ threadId }),
-        projectionThreadActivityRepository.listUserInputLifecycleByThreadId({ threadId }),
-        projectionPendingApprovalRepository.listByThreadId({ threadId }),
-      ]);
+      const [latestUserMessageAt, proposedPlans, activities, pendingApprovalCount] =
+        yield* Effect.all([
+          projectionThreadMessageRepository.getLatestUserMessageAt({ threadId }),
+          projectionThreadProposedPlanRepository.listByThreadId({ threadId }),
+          projectionThreadActivityRepository.listUserInputLifecycleByThreadId({ threadId }),
+          projectionPendingApprovalRepository.countPendingByThreadId({ threadId }),
+        ]);
 
-      let latestUserMessageAt: string | null = null;
-      for (const message of messages) {
-        if (
-          message.role === "user" &&
-          (latestUserMessageAt === null || message.createdAt > latestUserMessageAt)
-        ) {
-          latestUserMessageAt = message.createdAt;
-        }
-      }
-
-      const pendingApprovalCount = pendingApprovals.filter(
-        (approval) => approval.status === "pending",
-      ).length;
       const pendingUserInputCount = derivePendingUserInputCountFromActivities(activities);
       const hasActionableProposedPlan = deriveHasActionableProposedPlan({
         latestTurnId: existingRow.value.latestTurnId,
@@ -915,6 +911,7 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             updatedAt: event.occurredAt,
             latestUserMessageAt:
               event.payload.role === "user" &&
+              !isImportedAgentSessionMessageId(event.payload.messageId) &&
               (previousLatest === null || event.payload.createdAt > previousLatest)
                 ? event.payload.createdAt
                 : previousLatest,
@@ -1585,7 +1582,10 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             yield* projectionTurnRepository.upsertByTurnId({
               ...existingTurn.value,
               assistantMessageId: event.payload.assistantMessageId,
-              state: turnStillRunning ? existingTurn.value.state : nextState,
+              state:
+                turnStillRunning || existingTurn.value.state === "interrupted"
+                  ? existingTurn.value.state
+                  : nextState,
               checkpointTurnCount: event.payload.checkpointTurnCount,
               checkpointRef: event.payload.checkpointRef,
               checkpointStatus: event.payload.status,
@@ -1728,6 +1728,44 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
               });
               return;
             }
+            if (Option.isNone(existingRow) || existingRow.value.status !== "resolved") {
+              return;
+            }
+
+            // Sending a reply clears the badge before the provider accepts it.
+            // A failed reply must restore the request unless a terminal event
+            // already closed it, including a reply from another client.
+            const requestActivities = (yield* projectionThreadActivityRepository.listByThreadId({
+              threadId: existingRow.value.threadId,
+            })).filter((activity) => extractActivityRequestId(activity.payload) === requestId);
+            const wasRequested = requestActivities.some(
+              (activity) => activity.kind === "approval.requested",
+            );
+            const wasResolved = requestActivities.some((activity) => {
+              if (activity.kind === "approval.resolved") {
+                return true;
+              }
+              if (activity.kind !== "provider.approval.respond.failed") {
+                return false;
+              }
+              const activityPayload =
+                typeof activity.payload === "object" && activity.payload !== null
+                  ? (activity.payload as Record<string, unknown>)
+                  : null;
+              return isStalePendingApprovalFailureDetail(
+                typeof activityPayload?.detail === "string"
+                  ? activityPayload.detail.toLowerCase()
+                  : null,
+              );
+            });
+            if (wasRequested && !wasResolved) {
+              yield* projectionPendingApprovalRepository.upsert({
+                ...existingRow.value,
+                status: "pending",
+                decision: null,
+                resolvedAt: null,
+              });
+            }
             return;
           }
           // Only approval-requested activities should create pending-approval
@@ -1921,11 +1959,21 @@ const makeOrchestrationProjectionPipeline = Effect.fn("makeOrchestrationProjecti
             prunedThreadRelativePaths: new Map<string, Set<string>>(),
           };
           yield* sql.withTransaction(
-            Effect.forEach(
-              projectors,
-              (projector) => applyProjectorForEvent(projector, event, attachmentSideEffects),
-              { concurrency: 1, discard: true },
-            ),
+            Effect.gen(function* () {
+              yield* Effect.forEach(
+                projectors,
+                (projector) => projector.apply(event, attachmentSideEffects),
+                { concurrency: 1, discard: true },
+              );
+              // Runtime projectors commit together. Bootstrap still advances each cursor separately.
+              yield* projectionStateRepository.upsertMany(
+                projectors.map((projector) => ({
+                  projector: projector.name,
+                  lastAppliedSequence: event.sequence,
+                  updatedAt: event.occurredAt,
+                })),
+              );
+            }),
           );
           // Return the cleanup effect so the caller runs it after the outer transaction commits.
           // @effect-diagnostics-next-line returnEffectInGen:off
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
index 682b280bf4d0..a1b351de3535 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.test.ts
@@ -1,4 +1,5 @@
 import {
+  type AgentSessionImportSource,
   CheckpointRef,
   EventId,
   MessageId,
@@ -11,6 +12,7 @@ import { assert, it } from "@effect/vitest";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
 import * as SqlClient from "effect/unstable/sql/SqlClient";
 
 import { SqlitePersistenceMemory } from "../../persistence/Layers/Sqlite.ts";
@@ -22,6 +24,7 @@ import * as ThreadPlanProgress from "../ThreadPlanProgress.ts";
 import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import { encodeThreadDetailPageCursor } from "../threadDetailCursor.ts";
 import { projectThreadDetailSnapshot } from "../ActivityPayloadProjection.ts";
+import { makeSqlStatementCounter } from "../../../integration/SqlStatementCounter.integration.ts";
 
 const asProjectId = (value: string): ProjectId => ProjectId.make(value);
 const asTurnId = (value: string): TurnId => TurnId.make(value);
@@ -560,6 +563,38 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
           },
         ]);
       }
+
+      const counter = makeSqlStatementCounter();
+      const context = yield* snapshotQuery
+        .getThreadRuntimeContext(ThreadId.make("thread-1"))
+        .pipe(Effect.withTracer(counter.tracer));
+      assert.equal(counter.count(), 1);
+      assert.equal(context._tag, "Some");
+      if (context._tag === "Some") {
+        assert.deepEqual(context.value, {
+          id: ThreadId.make("thread-1"),
+          title: "Thread 1",
+          session: snapshot.threads[0]?.session,
+        });
+      }
+
+      yield* sql`
+        UPDATE projection_thread_sessions
+        SET status = 'starting', active_turn_id = NULL, provider_name = 'claudeAgent',
+            provider_instance_id = 'claude-secondary', last_error = 'Starting another session'
+        WHERE thread_id = 'thread-1'
+      `;
+      const changedContext = yield* snapshotQuery.getThreadRuntimeContext(
+        ThreadId.make("thread-1"),
+      );
+      assert.equal(changedContext._tag, "Some");
+      if (changedContext._tag === "Some") {
+        assert.equal(changedContext.value.session?.status, "starting");
+        assert.equal(changedContext.value.session?.activeTurnId, null);
+        assert.equal(changedContext.value.session?.providerName, "claudeAgent");
+        assert.equal(changedContext.value.session?.providerInstanceId, "claude-secondary");
+        assert.equal(changedContext.value.session?.lastError, "Starting another session");
+      }
     }),
   );
 
@@ -680,6 +715,22 @@ projectionSnapshotLayer("ProjectionSnapshotQuery", (it) => {
         [ThreadId.make("thread-archived")],
       );
       assert.equal(archivedShellSnapshot.threads[0]?.archivedAt, "2026-04-06T00:00:06.000Z");
+      const activeContext = yield* snapshotQuery.getThreadRuntimeContext(
+        ThreadId.make("thread-active"),
+      );
+      assert.equal(activeContext._tag, "Some");
+      if (activeContext._tag === "Some") assert.equal(activeContext.value.session, null);
+      for (const threadId of ["thread-archived", "thread-missing"]) {
+        assert.equal(
+          (yield* snapshotQuery.getThreadRuntimeContext(ThreadId.make(threadId)))._tag,
+          "None",
+        );
+      }
+      yield* sql`UPDATE projection_threads SET deleted_at = '2026-04-06T00:00:08.000Z' WHERE thread_id = 'thread-active'`;
+      assert.equal(
+        (yield* snapshotQuery.getThreadRuntimeContext(ThreadId.make("thread-active")))._tag,
+        "None",
+      );
     }),
   );
 
@@ -2085,7 +2136,9 @@ projectionSnapshotLayer("ProjectionSnapshotQuery windowed thread detail", (it) =
   //
   // Straggler user message at T03.5 (turn_id NULL, not any pending_message_id)
   // and a turnless activity at T03.6 — both belong to the page containing T03+.
-  const seedFanOutThread = Effect.fnUntraced(function* () {
+  const seedFanOutThread = Effect.fnUntraced(function* (options?: {
+    readonly importedMessageCount?: number;
+  }) {
     const sql = yield* SqlClient.SqlClient;
 
     // Tests in this block share one in-memory database; reset before seeding.
@@ -2114,6 +2167,20 @@ projectionSnapshotLayer("ProjectionSnapshotQuery windowed thread detail", (it) =
         'turn-5', 0, 0, 0, '2026-03-01T00:00:00.000Z', '2026-03-01T00:00:10.000Z', NULL)
     `;
 
+    if (options?.importedMessageCount) {
+      for (let index = 0; index < options.importedMessageCount; index += 1) {
+        const messageId = `import:codex:session-w:${String(index).padStart(6, "0")}`;
+        const role = index % 2 === 0 ? "user" : "assistant";
+        yield* sql`
+          INSERT INTO projection_thread_messages (
+            message_id, thread_id, turn_id, role, text, is_streaming, created_at, updated_at
+          )
+          VALUES (${messageId}, 'thread-w', NULL, ${role}, ${"imported message " + index}, 0,
+            '2026-02-28T00:00:00.000Z', '2026-02-28T00:00:00.000Z')
+        `;
+      }
+    }
+
     const turns: ReadonlyArray<{
       turn: string;
       pendingMessage: string | null;
@@ -2347,6 +2414,51 @@ projectionSnapshotLayer("ProjectionSnapshotQuery windowed thread detail", (it) =
     }),
   );
 
+  it.effect("keeps imported history on the oldest page after resumed turns", () =>
+    Effect.gen(function* () {
+      yield* seedFanOutThread({ importedMessageCount: 12 });
+      const snapshotQuery = yield* ProjectionSnapshotQuery;
+
+      const completePage = yield* snapshotQuery.getThreadDetailSnapshot(threadW, { turnLimit: 50 });
+      assert.equal(completePage._tag, "Some");
+      if (completePage._tag !== "Some") return;
+      assert.equal(
+        completePage.value.thread.messages.filter((message) => message.id.startsWith("import:"))
+          .length,
+        12,
+      );
+      assert.equal(completePage.value.page?.hasMore, false);
+      assert.equal(completePage.value.page?.beforeCursor, null);
+
+      const recentPage = yield* snapshotQuery.getThreadDetailSnapshot(threadW, { turnLimit: 2 });
+      assert.equal(recentPage._tag, "Some");
+      if (recentPage._tag !== "Some") return;
+      assert.equal(
+        recentPage.value.thread.messages.some((message) => message.id.startsWith("import:")),
+        false,
+      );
+      const cursor = recentPage.value.page?.beforeCursor;
+      assert.notEqual(cursor, null);
+      assert.notEqual(cursor, undefined);
+      if (cursor === null || cursor === undefined) return;
+
+      const oldestPage = yield* snapshotQuery.getThreadDetailSnapshot(threadW, {
+        turnLimit: 1,
+        beforeCursor: cursor,
+      });
+      assert.equal(oldestPage._tag, "Some");
+      if (oldestPage._tag !== "Some") return;
+
+      const importedIds = oldestPage.value.thread.messages
+        .map((message) => message.id)
+        .filter((messageId) => messageId.startsWith("import:"));
+      assert.equal(importedIds.length, 12);
+      assert.equal(new Set(importedIds).size, 12);
+      assert.equal(oldestPage.value.page?.hasMore, false);
+      assert.equal(oldestPage.value.page?.beforeCursor, null);
+    }),
+  );
+
   it.effect("a cursor for a different thread degrades to the first page", () =>
     Effect.gen(function* () {
       yield* seedFanOutThread();
@@ -2730,3 +2842,237 @@ projectionSnapshotLayer("ProjectionSnapshotQuery windowed thread detail", (it) =
     }),
   );
 });
+
+projectionSnapshotLayer("ProjectionSnapshotQuery imported sources", (it) => {
+  const encodeJson = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
+  const source: AgentSessionImportSource = {
+    provider: "codex",
+    providerInstanceId: ProviderInstanceId.make("codex-home"),
+    providerSessionId: "native-session",
+    filePath: "/tmp/transcript.jsonl",
+    size: 128,
+    mtimeMs: 1_700_000_000_000,
+    device: 1,
+    inode: 2,
+    birthtimeMs: 1_699_000_000_000,
+  };
+
+  const seedImportedSession = Effect.fn("seedImportedSession")(function* (
+    projectId: ProjectId,
+    source: AgentSessionImportSource,
+  ) {
+    const sql = yield* SqlClient.SqlClient;
+    const threadId = ThreadId.make(
+      `import:${source.providerInstanceId}:${source.providerSessionId}`,
+    );
+    const timestamp = "2026-03-02T00:00:00.000Z";
+    yield* sql`
+      INSERT OR IGNORE INTO projection_projects (
+        project_id, title, workspace_root, scripts_json, created_at, updated_at
+      ) VALUES (${projectId}, 'Imported project', '/tmp/imported-project', '[]',
+        ${timestamp}, ${timestamp})
+    `;
+    yield* sql`
+      INSERT INTO projection_threads (
+        thread_id, project_id, title, model_selection_json, runtime_mode, interaction_mode,
+        created_at, updated_at
+      ) VALUES (${threadId}, ${projectId}, 'Imported thread',
+        ${encodeJson({ instanceId: source.providerInstanceId, model: "gpt-5-codex" })},
+        'full-access', 'default',
+        ${timestamp}, ${timestamp})
+    `;
+    yield* sql`
+      INSERT INTO provider_session_runtime (
+        thread_id, provider_name, provider_instance_id, adapter_key, runtime_mode, status,
+        last_seen_at, resume_cursor_json, runtime_payload_json
+      ) VALUES (${threadId}, ${source.provider}, ${source.providerInstanceId},
+        ${source.provider}, 'full-access', 'stopped', ${timestamp},
+        ${encodeJson({ threadId: source.providerSessionId })},
+        ${encodeJson({ importedTranscripts: [source] })})
+    `;
+    yield* sql`
+      INSERT INTO projection_thread_messages (
+        message_id, thread_id, role, text, is_streaming, created_at, updated_at
+      ) VALUES (${`${threadId}:000000`}, ${threadId}, 'user', 'Imported history', 0,
+        ${timestamp}, ${timestamp})
+    `;
+    return { threadId, source };
+  });
+
+  it.effect("reads completed source copies without decoding message bodies", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      const query = yield* ProjectionSnapshotQuery;
+      const projectId = ProjectId.make("project-import-metadata");
+      const imported = yield* seedImportedSession(projectId, source);
+      const copiedSource = {
+        ...source,
+        filePath: "/tmp/transcript-copy.jsonl",
+        mtimeMs: null,
+        inode: null,
+        birthtimeMs: null,
+      };
+      yield* sql`
+        UPDATE provider_session_runtime
+        SET runtime_payload_json = ${encodeJson({
+          cwd: "/tmp/imported-project",
+          importedTranscripts: [source, copiedSource],
+        })}
+        WHERE thread_id = ${imported.threadId}
+      `;
+      yield* sql`
+        UPDATE projection_thread_messages SET attachments_json = 'not-json'
+        WHERE thread_id = ${imported.threadId}
+      `;
+
+      const counter = makeSqlStatementCounter();
+      const sources = yield* query
+        .getImportedAgentSessionSources(projectId)
+        .pipe(Effect.withTracer(counter.tracer));
+      assert.deepEqual(sources, [imported, { threadId: imported.threadId, source: copiedSource }]);
+      assert.equal(counter.count(), 1);
+    }),
+  );
+
+  it.effect("requires active project threads, a binding, and an imported message", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      const query = yield* ProjectionSnapshotQuery;
+      const projectId = ProjectId.make("project-import-completion");
+      const completed = yield* seedImportedSession(projectId, {
+        ...source,
+        providerSessionId: "completed",
+      });
+      yield* sql`
+        UPDATE projection_thread_messages SET message_id = ${`${completed.threadId}:legacy`}
+        WHERE thread_id = ${completed.threadId}
+      `;
+      const partials = yield* Effect.forEach(
+        [
+          "no-binding",
+          "no-history",
+          "no-imported-message",
+          "wrong-message-thread",
+          "archived",
+          "deleted",
+        ],
+        (providerSessionId) => seedImportedSession(projectId, { ...source, providerSessionId }),
+      );
+      const [noBinding, noHistory, noImportedMessage, wrongMessageThread, archived, deleted] =
+        partials;
+      assert.isDefined(noBinding);
+      assert.isDefined(noHistory);
+      assert.isDefined(noImportedMessage);
+      assert.isDefined(wrongMessageThread);
+      assert.isDefined(archived);
+      assert.isDefined(deleted);
+      yield* sql`DELETE FROM provider_session_runtime WHERE thread_id = ${noBinding.threadId}`;
+      yield* sql`DELETE FROM projection_thread_messages WHERE thread_id = ${noHistory.threadId}`;
+      yield* sql`
+        UPDATE projection_thread_messages SET message_id = ${`normal:${noImportedMessage.threadId}`}
+        WHERE thread_id = ${noImportedMessage.threadId}
+      `;
+      yield* sql`
+        UPDATE projection_thread_messages SET thread_id = 'unrelated-thread'
+        WHERE thread_id = ${wrongMessageThread.threadId}
+      `;
+      yield* sql`
+        UPDATE projection_threads SET archived_at = '2026-03-03T00:00:00.000Z'
+        WHERE thread_id = ${archived.threadId}
+      `;
+      yield* sql`
+        UPDATE projection_threads SET deleted_at = '2026-03-03T00:00:00.000Z'
+        WHERE thread_id = ${deleted.threadId}
+      `;
+      const otherProjectId = ProjectId.make("project-import-other");
+      const otherProject = yield* seedImportedSession(otherProjectId, {
+        ...source,
+        providerSessionId: "other-project",
+      });
+      const deletedProjectId = ProjectId.make("project-import-deleted");
+      yield* seedImportedSession(deletedProjectId, {
+        ...source,
+        providerSessionId: "deleted-project",
+      });
+      yield* sql`
+        UPDATE projection_projects SET deleted_at = '2026-03-03T00:00:00.000Z'
+        WHERE project_id = ${deletedProjectId}
+      `;
+
+      assert.deepEqual(yield* query.getImportedAgentSessionSources(projectId), [completed]);
+      assert.deepEqual(yield* query.getImportedAgentSessionSources(otherProjectId), [otherProject]);
+      assert.deepEqual(yield* query.getImportedAgentSessionSources(deletedProjectId), []);
+      assert.deepEqual(
+        yield* query.getImportedAgentSessionSources(ProjectId.make("project-import-missing")),
+        [],
+      );
+    }),
+  );
+
+  it.effect("keeps original sources when the current runtime provider and cursor change", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      const query = yield* ProjectionSnapshotQuery;
+      const projectId = ProjectId.make("project-import-switched");
+      const imported = yield* seedImportedSession(projectId, {
+        ...source,
+        provider: "claudeAgent",
+        providerInstanceId: ProviderInstanceId.make("claude-original"),
+        providerSessionId: "original-session",
+      });
+      yield* sql`
+        UPDATE provider_session_runtime
+        SET provider_name = 'codex', provider_instance_id = 'codex-new', adapter_key = 'codex',
+          resume_cursor_json = '{"threadId":"new-session"}'
+        WHERE thread_id = ${imported.threadId}
+      `;
+
+      assert.deepEqual(yield* query.getImportedAgentSessionSources(projectId), [imported]);
+    }),
+  );
+
+  it.effect("skips invalid source payloads and entries without dropping valid sources", () =>
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      const query = yield* ProjectionSnapshotQuery;
+      const projectId = ProjectId.make("project-import-invalid");
+      const imported = yield* seedImportedSession(projectId, {
+        ...source,
+        providerSessionId: "a-invalid",
+      });
+      const valid = yield* seedImportedSession(projectId, {
+        ...source,
+        providerSessionId: "z-valid",
+      });
+      for (const payload of [null, "not-json", "null", "[]", "{}", '{"importedTranscripts":{}}']) {
+        yield* sql`
+          UPDATE provider_session_runtime SET runtime_payload_json = ${payload}
+          WHERE thread_id = ${imported.threadId}
+        `;
+        assert.deepEqual(yield* query.getImportedAgentSessionSources(projectId), [valid]);
+      }
+      yield* sql`
+        UPDATE provider_session_runtime SET runtime_payload_json = X'FF'
+        WHERE thread_id = ${imported.threadId}
+      `;
+      assert.deepEqual(yield* query.getImportedAgentSessionSources(projectId), [valid]);
+
+      yield* sql`
+        UPDATE provider_session_runtime
+        SET runtime_payload_json = ${encodeJson({
+          importedTranscripts: [
+            null,
+            {},
+            { ...imported.source, size: -1 },
+            { ...imported.source, provider: "cursor" },
+            { ...imported.source, providerInstanceId: "wrong-instance" },
+            { ...imported.source, providerSessionId: "wrong-session" },
+            imported.source,
+          ],
+        })}
+        WHERE thread_id = ${imported.threadId}
+      `;
+      assert.deepEqual(yield* query.getImportedAgentSessionSources(projectId), [imported, valid]);
+    }),
+  );
+});
diff --git a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
index 0d064a1d6e9c..86e0b94573d9 100644
--- a/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
@@ -1,4 +1,5 @@
 import {
+  AgentSessionImportSource,
   ApprovalRequestId,
   ChatAttachment,
   CheckpointRef,
@@ -75,6 +76,14 @@ import {
 const decodeReadModel = Schema.decodeUnknownEffect(OrchestrationReadModel);
 const decodeShellSnapshot = Schema.decodeUnknownEffect(OrchestrationShellSnapshot);
 const decodeThread = Schema.decodeUnknownEffect(OrchestrationThread);
+const decodeImportedTranscriptsPayload = Schema.decodeUnknownOption(
+  Schema.fromJsonString(
+    Schema.Struct({
+      importedTranscripts: Schema.Array(Schema.Unknown),
+    }),
+  ),
+);
+const decodeAgentSessionImportSource = Schema.decodeUnknownOption(AgentSessionImportSource);
 // Keep detail reads consistent with the in-memory projector's retained
 // activity window. Applying the limit in SQL avoids decoding an unbounded
 // payload_json set before the projector can enforce that invariant.
@@ -113,6 +122,11 @@ const ProjectionThreadActivityIdRowSchema = Schema.Struct({
   activityId: ProjectionThreadActivity.fields.activityId,
 });
 const ProjectionThreadSessionDbRowSchema = ProjectionThreadSession;
+const ProjectionThreadRuntimeContextDbRowSchema = Schema.Struct({
+  id: ThreadId,
+  title: Schema.String,
+  session: Schema.NullOr(ProjectionThreadSessionDbRowSchema),
+});
 const ProjectionCheckpointDbRowSchema = ProjectionCheckpoint.mapFields(
   Struct.assign({
     files: Schema.fromJsonString(Schema.Array(OrchestrationCheckpointFile)),
@@ -159,6 +173,10 @@ const WorkspaceRootLookupInput = Schema.Struct({
 const ProjectIdLookupInput = Schema.Struct({
   projectId: ProjectId,
 });
+const ProjectionImportedAgentSessionSourcesRowSchema = Schema.Struct({
+  threadId: ThreadId,
+  runtimePayload: Schema.Unknown,
+});
 const ThreadIdLookupInput = Schema.Struct({
   threadId: ThreadId,
 });
@@ -978,6 +996,33 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       `,
   });
 
+  const listImportedAgentSessionSourceRows = SqlSchema.findAll({
+    Request: ProjectIdLookupInput,
+    Result: ProjectionImportedAgentSessionSourcesRowSchema,
+    execute: ({ projectId }) =>
+      sql`
+        SELECT
+          threads.thread_id AS "threadId",
+          runtime.runtime_payload_json AS "runtimePayload"
+        FROM projection_threads AS threads
+        INNER JOIN projection_projects AS projects
+          ON projects.project_id = threads.project_id
+        INNER JOIN provider_session_runtime AS runtime
+          ON runtime.thread_id = threads.thread_id
+        WHERE threads.project_id = ${projectId}
+          AND threads.deleted_at IS NULL
+          AND threads.archived_at IS NULL
+          AND projects.deleted_at IS NULL
+          AND EXISTS (
+            SELECT 1
+            FROM projection_thread_messages AS messages
+            WHERE messages.thread_id = threads.thread_id
+              AND messages.message_id GLOB 'import:*'
+          )
+        ORDER BY threads.thread_id ASC
+      `,
+  });
+
   const getThreadCheckpointContextThreadRow = SqlSchema.findOneOption({
     Request: ThreadIdLookupInput,
     Result: ProjectionThreadCheckpointContextThreadRowSchema,
@@ -1038,6 +1083,40 @@ const makeProjectionSnapshotQuery = Effect.gen(function* () {
       `,
   });
 
+  const getThreadRuntimeContextRow = SqlSchema.findOneOption({
+    Request: ThreadIdLookupInput,
+    Result: ProjectionThreadRuntimeContextDbRowSchema,
+    execute: ({ threadId }) =>
+      sql`
+        SELECT
+          threads.thread_id AS id,
+          threads.title,
+          sessions.thread_id AS "threadId",
+          sessions.status,
+          sessions.provider_name AS "providerName",
+          sessions.provider_instance_id AS "providerInstanceId",
+          sessions.runtime_mode AS "runtimeMode",
+          sessions.active_turn_id AS "activeTurnId",
+          sessions.last_error AS "lastError",
+          sessions.updated_at AS "updatedAt"
+        FROM projection_threads AS threads
+        LEFT JOIN projection_thread_sessions AS sessions
+          ON sessions.thread_id = threads.thread_id
+        WHERE threads.thread_id = ${threadId}
+          AND threads.deleted_at IS NULL
+          AND threads.archived_at IS NULL
+        LIMIT 1
+      `.pipe(
+        Effect.map((rows) =>
+          rows.map((row) => ({
+            id: row.id,
+            title: row.title,
+            session: row.threadId === null ? null : row,
+          })),
+        ),
+      ),
+  });
+
   const listThreadMessageRowsByThread = SqlSchema.findAll({
     Request: ThreadIdLookupInput,
     Result: ProjectionThreadMessageDbRowSchema,
@@ -2624,6 +2703,33 @@ pending_approval_requests AS (
         Effect.map(Option.map((row) => row.threadId)),
       );
 
+  const getImportedAgentSessionSources: ProjectionSnapshotQueryShape["getImportedAgentSessionSources"] =
+    Effect.fn("ProjectionSnapshotQuery.getImportedAgentSessionSources")(function* (projectId) {
+      const rows = yield* listImportedAgentSessionSourceRows({ projectId }).pipe(
+        Effect.mapError(
+          toPersistenceSqlOrDecodeError(
+            "ProjectionSnapshotQuery.getImportedAgentSessionSources:query",
+            "ProjectionSnapshotQuery.getImportedAgentSessionSources:decodeRows",
+          ),
+        ),
+      );
+      return rows.flatMap((row) => {
+        const payload = decodeImportedTranscriptsPayload(row.runtimePayload);
+        if (Option.isNone(payload)) return [];
+        return payload.value.importedTranscripts.flatMap((entry) => {
+          const source = decodeAgentSessionImportSource(entry);
+          if (
+            Option.isNone(source) ||
+            row.threadId !==
+              `import:${source.value.providerInstanceId}:${source.value.providerSessionId}`
+          ) {
+            return [];
+          }
+          return [{ threadId: row.threadId, source: source.value }];
+        });
+      });
+    });
+
   const getThreadCheckpointContext: ProjectionSnapshotQueryShape["getThreadCheckpointContext"] = (
     threadId,
   ) =>
@@ -2764,6 +2870,23 @@ pending_approval_requests AS (
       } satisfies OrchestrationThreadShell);
     });
 
+  const getThreadRuntimeContext: ProjectionSnapshotQueryShape["getThreadRuntimeContext"] =
+    Effect.fn("ProjectionSnapshotQuery.getThreadRuntimeContext")(function* (threadId) {
+      const context = yield* getThreadRuntimeContextRow({ threadId }).pipe(
+        Effect.mapError(
+          toPersistenceSqlOrDecodeError(
+            "ProjectionSnapshotQuery.getThreadRuntimeContext:query",
+            "ProjectionSnapshotQuery.getThreadRuntimeContext:decodeRow",
+          ),
+        ),
+      );
+      return Option.map(context, (row) => ({
+        id: row.id,
+        title: row.title,
+        session: row.session === null ? null : mapSessionRow(row.session),
+      }));
+    });
+
   // Contiguous turn range bounding a windowed detail read; undefined loads the
   // full thread. Resolved from a window request inside the snapshot
   // transaction (see getThreadDetailSnapshot).
@@ -3095,17 +3218,35 @@ pending_approval_requests AS (
           );
 
           const oldest = windowRows[0];
+          const hasMore =
+            oldest !== undefined &&
+            (yield* listTurnWindowRows({
+              threadId,
+              beforeAnchorAt: oldest.anchorAt,
+              beforeTurnKey: oldest.turnKey,
+              userTurnLimit: 1,
+              maxRawTurns: 1,
+            }).pipe(
+              Effect.mapError(
+                toPersistenceSqlOrDecodeError(
+                  "ProjectionSnapshotQuery.getThreadDetailSnapshot:probeOlder:query",
+                  "ProjectionSnapshotQuery.getThreadDetailSnapshot:probeOlder:decodeRows",
+                ),
+              ),
+            )).length > 0;
           // An empty window (no turns before the cursor, or a thread with no
           // turns at all) still returns thread metadata with empty collections
           // for turn-linked rows; turnless rows are bounded to the same empty
           // range. The first page of a turnless thread stays unwindowed so
-          // pre-turn content (e.g. a just-created thread) is not hidden.
+          // pre-turn content (e.g. a just-created thread) is not hidden. Once
+          // paging reaches the oldest turn, include turnless messages before
+          // the first turn, such as history imported from a provider session.
           const bounds: ThreadDetailBounds | undefined =
             oldest === undefined && cursor === null
               ? undefined
               : {
-                  minAnchorAt: oldest?.anchorAt ?? "",
-                  minTurnKey: oldest?.turnKey ?? "",
+                  minAnchorAt: hasMore ? (oldest?.anchorAt ?? "") : "",
+                  minTurnKey: hasMore ? (oldest?.turnKey ?? "") : "",
                   beforeAnchorAt: cursor?.beforeAnchorAt ?? ANCHOR_UNBOUNDED,
                   beforeTurnKey: cursor?.beforeTurnId ?? "",
                 };
@@ -3122,23 +3263,6 @@ pending_approval_requests AS (
             return Option.none<OrchestrationThreadDetailSnapshot>();
           }
 
-          const hasMore =
-            oldest !== undefined &&
-            (yield* listTurnWindowRows({
-              threadId,
-              beforeAnchorAt: oldest.anchorAt,
-              beforeTurnKey: oldest.turnKey,
-              userTurnLimit: 1,
-              maxRawTurns: 1,
-            }).pipe(
-              Effect.mapError(
-                toPersistenceSqlOrDecodeError(
-                  "ProjectionSnapshotQuery.getThreadDetailSnapshot:probeOlder:query",
-                  "ProjectionSnapshotQuery.getThreadDetailSnapshot:probeOlder:decodeRows",
-                ),
-              ),
-            )).length > 0;
-
           const { snapshotSequence } = yield* getSnapshotSequence();
           const watermarkRow = yield* getThreadEventWatermarkRow({
             threadId,
@@ -3197,9 +3321,11 @@ pending_approval_requests AS (
     getActiveProjectByWorkspaceRoot,
     getProjectShellById,
     getFirstActiveThreadIdByProjectId,
+    getImportedAgentSessionSources,
     getThreadCheckpointContext,
     getFullThreadDiffContext,
     getThreadShellById,
+    getThreadRuntimeContext,
     getThreadDetailById,
     getThreadDetailSnapshot,
   } satisfies ProjectionSnapshotQueryShape;
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
index 1c5e834ec2d7..a8b26fe52cbd 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
@@ -29,6 +29,7 @@ import * as Deferred from "effect/Deferred";
 import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
 import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Option from "effect/Option";
 import * as PubSub from "effect/PubSub";
 import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
@@ -38,7 +39,11 @@ import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
 import { deriveServerPaths, ServerConfig } from "../../config.ts";
 import { TextGenerationError } from "@t3tools/contracts";
-import { ProviderAdapterRequestError } from "../../provider/Errors.ts";
+import {
+  ProviderAdapterRequestError,
+  ProviderWorkspaceMissingError,
+  type ProviderServiceError,
+} from "../../provider/Errors.ts";
 import { OrchestrationEventStoreLive } from "../../persistence/Layers/OrchestrationEventStore.ts";
 import { OrchestrationCommandReceiptRepositoryLive } from "../../persistence/Layers/OrchestrationCommandReceipts.ts";
 import { SqlitePersistenceMemory } from "../../persistence/Layers/Sqlite.ts";
@@ -56,7 +61,6 @@ import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQu
 import * as ThreadBackgroundLiveness from "../ThreadBackgroundLiveness.ts";
 import * as ThreadPlanProgress from "../ThreadPlanProgress.ts";
 import {
-  providerErrorLabel,
   providerErrorLabelFromInstanceHint,
   ProviderCommandReactorLive,
 } from "./ProviderCommandReactor.ts";
@@ -159,10 +163,6 @@ describe("ProviderCommandReactor", () => {
         }),
       ).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?: {
@@ -170,6 +170,7 @@ describe("ProviderCommandReactor", () => {
     readonly threadModelSelection?: ModelSelection;
     readonly sessionModelSwitch?: "unsupported" | "in-session";
     readonly requiresNewThreadForModelChange?: boolean;
+    readonly unreadableHistory?: boolean;
     readonly titleRegenerationCompletionDispatchFailures?: number;
     readonly titleRegenerationBeforeStart?: "one" | "two";
     readonly serverActivation?: Effect.Effect<void>;
@@ -179,7 +180,7 @@ describe("ProviderCommandReactor", () => {
     readonly stopSessionEffect?: () => Effect.Effect<void, ProviderAdapterRequestError>;
     readonly startSessionEffect?: (
       session: ProviderSession,
-    ) => Effect.Effect<ProviderSession, ProviderAdapterRequestError>;
+    ) => Effect.Effect<ProviderSession, ProviderServiceError>;
     readonly tryHandlePromptCommandEffect?: ProviderAuthService["Service"]["tryHandlePromptCommand"];
   }) {
     const now = "2026-01-01T00:00:00.000Z";
@@ -418,6 +419,8 @@ describe("ProviderCommandReactor", () => {
         const engine = yield* OrchestrationEngineService;
         return {
           readEvents: engine.readEvents,
+          readThreadEvents: engine.readThreadEvents,
+          getThreadReplayStats: engine.getThreadReplayStats,
           dispatch: (command) => {
             if (command.type === "thread.title.regeneration.complete") {
               titleRegenerationCompletionDispatchAttempts += 1;
@@ -510,6 +513,23 @@ describe("ProviderCommandReactor", () => {
         createdAt: now,
       }),
     );
+    if (input?.unreadableHistory === true) {
+      // Metadata commands must not decode this unrelated message body.
+      await runtime.runPromise(
+        Effect.gen(function* () {
+          const sql = yield* SqlClient.SqlClient;
+          yield* sql`
+            INSERT INTO projection_thread_messages (
+              message_id, thread_id, turn_id, role, text, attachments_json,
+              is_streaming, created_at, updated_at
+            ) VALUES (
+              'old-unreadable-message', 'thread-1', NULL, 'assistant',
+              'Old assistant output', 'invalid json', 0, ${now}, ${now}
+            )
+          `;
+        }),
+      );
+    }
     if (input?.titleRegenerationBeforeStart === "two") {
       await Effect.runPromise(
         engine.dispatch({
@@ -559,6 +579,7 @@ describe("ProviderCommandReactor", () => {
 
     return {
       engine,
+      snapshotQuery,
       readModel: () => Effect.runPromise(snapshotQuery.getSnapshot()),
       readPendingTurnStarts: () =>
         runtime!.runPromise(
@@ -1195,6 +1216,58 @@ describe("ProviderCommandReactor", () => {
     }),
   );
 
+  effectIt.effect("shows the missing workspace message without a provider stack trace", () =>
+    Effect.gen(function* () {
+      const attempted = yield* Deferred.make<void>();
+      const missingCwd = "/missing/project/worktree";
+      const missingWorkspace = new ProviderWorkspaceMissingError({
+        threadId: ThreadId.make("thread-1"),
+        cwd: missingCwd,
+      });
+      const harness = yield* Effect.promise(() =>
+        createHarness({
+          startSessionEffect: () =>
+            Deferred.succeed(attempted, undefined).pipe(
+              Effect.andThen(Effect.fail(missingWorkspace)),
+            ),
+        }),
+      );
+
+      yield* harness.engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("cmd-turn-start-missing-workspace"),
+        threadId: ThreadId.make("thread-1"),
+        message: {
+          messageId: asMessageId("user-message-missing-workspace"),
+          role: "user",
+          text: "continue",
+          attachments: [],
+        },
+        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+        runtimeMode: "approval-required",
+        createdAt: "2026-01-01T00:00:00.000Z",
+      });
+      yield* Deferred.await(attempted);
+      yield* Effect.promise(() => harness.drain());
+
+      const thread = (yield* Effect.promise(() => harness.readModel())).threads.find(
+        (entry) => entry.id === ThreadId.make("thread-1"),
+      );
+      expect(thread?.session).toMatchObject({
+        status: "error",
+        activeTurnId: null,
+        lastError: missingWorkspace.message,
+      });
+      const failure = thread?.activities.find(
+        (activity) => activity.kind === "provider.turn.start.failed",
+      );
+      expect(failure?.payload).toMatchObject({ detail: missingWorkspace.message });
+      expect(harness.runtimeSessions).toEqual([]);
+      expect(harness.sendTurn).not.toHaveBeenCalled();
+      expect(yield* Effect.promise(() => harness.readPendingTurnStarts())).toEqual([]);
+    }),
+  );
+
   effectIt.effect("settles a failed provider startup and allows a clean retry", () =>
     Effect.gen(function* () {
       let failStartup = true;
@@ -3531,8 +3604,8 @@ describe("ProviderCommandReactor", () => {
     });
   });
 
-  it("reacts to thread.approval.respond by forwarding provider approval response", async () => {
-    const harness = await createHarness();
+  it("forwards approval responses without reading unrelated message bodies", async () => {
+    const harness = await createHarness({ unreadableHistory: true });
     const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
@@ -3564,7 +3637,7 @@ describe("ProviderCommandReactor", () => {
       }),
     );
 
-    await waitFor(() => harness.respondToRequest.mock.calls.length === 1);
+    await harness.drain();
     expect(harness.respondToRequest.mock.calls[0]?.[0]).toEqual({
       threadId: "thread-1",
       requestId: "approval-request-1",
@@ -3572,8 +3645,8 @@ describe("ProviderCommandReactor", () => {
     });
   });
 
-  it("reacts to thread.user-input.respond by forwarding structured user input answers", async () => {
-    const harness = await createHarness();
+  it("forwards user input answers without reading unrelated message bodies", async () => {
+    const harness = await createHarness({ unreadableHistory: true });
     const now = "2026-01-01T00:00:00.000Z";
 
     await Effect.runPromise(
@@ -3607,7 +3680,7 @@ describe("ProviderCommandReactor", () => {
       }),
     );
 
-    await waitFor(() => harness.respondToUserInput.mock.calls.length === 1);
+    await harness.drain();
     expect(harness.respondToUserInput.mock.calls[0]?.[0]).toEqual({
       threadId: "thread-1",
       requestId: "user-input-request-1",
@@ -3821,12 +3894,12 @@ describe("ProviderCommandReactor", () => {
     expect(resolvedActivity).toBeUndefined();
   });
 
-  it("reacts to thread.session.stop by stopping provider session and clearing thread session state", async () => {
-    const harness = await createHarness();
-    const now = "2026-01-01T00:00:00.000Z";
+  effectIt.effect("stops a provider session without reading unrelated message bodies", () =>
+    Effect.gen(function* () {
+      const harness = yield* Effect.promise(() => createHarness({ unreadableHistory: true }));
+      const now = "2026-01-01T00:00:00.000Z";
 
-    await harness.runEffect(
-      harness.engine.dispatch({
+      yield* harness.engine.dispatch({
         type: "thread.session.set",
         commandId: CommandId.make("cmd-session-set-for-stop"),
         threadId: ThreadId.make("thread-1"),
@@ -3841,27 +3914,27 @@ describe("ProviderCommandReactor", () => {
           updatedAt: now,
         },
         createdAt: now,
-      }),
-    );
+      });
 
-    await harness.runEffect(
-      harness.engine.dispatch({
+      yield* harness.engine.dispatch({
         type: "thread.session.stop",
         commandId: CommandId.make("cmd-session-stop"),
         threadId: ThreadId.make("thread-1"),
         createdAt: now,
-      }),
-    );
+      });
 
-    await waitFor(() => harness.stopSession.mock.calls.length === 1);
-    const readModel = await harness.readModel();
-    const thread = readModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
-    expect(thread?.session).not.toBeNull();
-    expect(thread?.session?.status).toBe("stopped");
-    expect(thread?.session?.threadId).toBe("thread-1");
-    expect(thread?.session?.providerInstanceId).toBe(ProviderInstanceId.make("codex_work"));
-    expect(thread?.session?.activeTurnId).toBeNull();
-  });
+      yield* Effect.promise(() => harness.drain());
+      expect(harness.stopSession).toHaveBeenCalledWith({ threadId: ThreadId.make("thread-1") });
+      const thread = yield* harness.snapshotQuery
+        .getThreadShellById(ThreadId.make("thread-1"))
+        .pipe(Effect.map(Option.getOrThrow));
+      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();
+    }),
+  );
 
   effectIt.effect("stops a ready provider session after automatic settlement", () =>
     Effect.gen(function* () {
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
index 1beab8ed22bb..fc963bcc9cb2 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -34,6 +34,7 @@ import { increment, orchestrationEventsProcessedTotal } from "../../observabilit
 import {
   ProviderAdapterRequestError,
   ProviderAdapterValidationError,
+  ProviderWorkspaceMissingError,
 } from "../../provider/Errors.ts";
 import type { ProviderServiceError } from "../../provider/Errors.ts";
 import { TextGeneration } from "../../textGeneration/TextGeneration.ts";
@@ -56,6 +57,7 @@ import { VcsStatusBroadcaster } from "../../vcs/VcsStatusBroadcaster.ts";
 import { GitWorkflowService } from "../../git/GitWorkflowService.ts";
 const isProviderAdapterRequestError = Schema.is(ProviderAdapterRequestError);
 const isProviderAdapterValidationError = Schema.is(ProviderAdapterValidationError);
+const isProviderWorkspaceMissingError = Schema.is(ProviderWorkspaceMissingError);
 const isProviderDriverKind = Schema.is(ProviderDriverKind);
 
 type ProviderIntentEvent = Extract<
@@ -226,7 +228,7 @@ function formatThreadTitleContext(messages: ReadonlyArray<ThreadTitleMessage>):
   };
 }
 
-export function providerErrorLabel(value: string | undefined): string {
+function providerErrorLabel(value: string | undefined): string {
   const normalized = value?.trim();
   return normalized && normalized.length > 0 ? normalized : "unknown";
 }
@@ -394,6 +396,9 @@ const make = Effect.gen(function* () {
     if (isProviderAdapterValidationError(failReason?.error)) {
       return failReason.error.issue;
     }
+    if (isProviderWorkspaceMissingError(failReason?.error)) {
+      return failReason.error.message;
+    }
     return Cause.pretty(cause);
   };
 
@@ -419,7 +424,7 @@ const make = Effect.gen(function* () {
     readonly detail: string;
     readonly createdAt: string;
   }) {
-    const thread = yield* resolveThread(input.threadId);
+    const thread = yield* resolveThreadShell(input.threadId);
     if (!thread) {
       return;
     }
@@ -447,7 +452,7 @@ const make = Effect.gen(function* () {
       compactingThreadIds.delete(threadId);
       return;
     }
-    const thread = yield* resolveThread(threadId);
+    const thread = yield* resolveThreadShell(threadId);
     if (!thread?.session) return;
     if (
       thread.session.status !== "starting" &&
@@ -525,7 +530,13 @@ const make = Effect.gen(function* () {
     );
   });
 
-  const resolveThread = Effect.fnUntraced(function* (threadId: ThreadId) {
+  const resolveThreadShell = Effect.fnUntraced(function* (threadId: ThreadId) {
+    return yield* projectionSnapshotQuery
+      .getThreadShellById(threadId)
+      .pipe(Effect.map(Option.getOrUndefined));
+  });
+
+  const resolveThreadDetail = Effect.fnUntraced(function* (threadId: ThreadId) {
     return yield* projectionSnapshotQuery
       .getThreadDetailById(threadId, { activityKinds: [] })
       .pipe(Effect.map(Option.getOrUndefined));
@@ -571,7 +582,7 @@ const make = Effect.gen(function* () {
       readonly pendingTurnStart?: boolean;
     },
   ) {
-    const thread = yield* resolveThread(threadId);
+    const thread = yield* resolveThreadShell(threadId);
     if (!thread) {
       return yield* Effect.die(new Error(`Thread '${threadId}' was not found in read model.`));
     }
@@ -834,7 +845,7 @@ const make = Effect.gen(function* () {
     readonly interactionMode?: "default" | "plan";
     readonly createdAt: string;
   }) {
-    const thread = yield* resolveThread(input.threadId);
+    const thread = yield* resolveThreadShell(input.threadId);
     if (!thread) {
       return yield* Effect.die(
         new Error(`Thread '${input.threadId}' was not found in read model.`),
@@ -975,7 +986,7 @@ const make = Effect.gen(function* () {
           );
         if (!generated) return;
 
-        const thread = yield* resolveThread(input.threadId);
+        const thread = yield* resolveThreadShell(input.threadId);
         if (!thread) return;
         if (!canReplaceThreadTitle(thread.title, input.titleSeed)) {
           return;
@@ -1007,7 +1018,7 @@ const make = Effect.gen(function* () {
       return { _tag: "Superseded" } as const;
     }
 
-    const thread = yield* resolveThread(event.payload.threadId);
+    const thread = yield* resolveThreadDetail(event.payload.threadId);
     if (!thread || thread.titleRegeneration?.requestId !== requestId) {
       return { _tag: "Superseded" } as const;
     }
@@ -1040,7 +1051,7 @@ const make = Effect.gen(function* () {
       return { _tag: "Completed", title: undefined } as const;
     }
 
-    const latestThread = yield* resolveThread(event.payload.threadId);
+    const latestThread = yield* resolveThreadShell(event.payload.threadId);
     if (
       !latestThread ||
       latestThread.titleRegeneration?.requestId !== requestId ||
@@ -1177,7 +1188,7 @@ const make = Effect.gen(function* () {
       return;
     }
 
-    const thread = yield* resolveThread(event.payload.threadId);
+    const thread = yield* resolveThreadDetail(event.payload.threadId);
     if (!thread) {
       return;
     }
@@ -1366,7 +1377,7 @@ const make = Effect.gen(function* () {
           "Context compaction requires an existing conversation.",
         );
       }
-      const latestThread = yield* resolveThread(event.payload.threadId);
+      const latestThread = yield* resolveThreadShell(event.payload.threadId);
       if (
         compactingThreadIds.has(event.payload.threadId) ||
         latestThread?.session?.status === "starting" ||
@@ -1436,7 +1447,7 @@ const make = Effect.gen(function* () {
   const processTurnInterruptRequested = Effect.fn("processTurnInterruptRequested")(function* (
     event: Extract<ProviderIntentEvent, { type: "thread.turn-interrupt-requested" }>,
   ) {
-    const thread = yield* resolveThread(event.payload.threadId);
+    const thread = yield* resolveThreadShell(event.payload.threadId);
     if (!thread) {
       return;
     }
@@ -1459,7 +1470,7 @@ const make = Effect.gen(function* () {
 
       const detail = formatFailureDetail(cause);
       return Effect.gen(function* () {
-        const latestThread = yield* resolveThread(event.payload.threadId);
+        const latestThread = yield* resolveThreadShell(event.payload.threadId);
         const latestSession = latestThread?.session;
         if (
           !latestSession ||
@@ -1487,7 +1498,7 @@ const make = Effect.gen(function* () {
             );
           }),
         );
-        const stoppedThread = yield* resolveThread(event.payload.threadId);
+        const stoppedThread = yield* resolveThreadShell(event.payload.threadId);
         const stoppedSession = stoppedThread?.session;
         if (
           !stoppedSession ||
@@ -1531,7 +1542,7 @@ const make = Effect.gen(function* () {
   const processApprovalResponseRequested = Effect.fn("processApprovalResponseRequested")(function* (
     event: Extract<ProviderIntentEvent, { type: "thread.approval-response-requested" }>,
   ) {
-    const thread = yield* resolveThread(event.payload.threadId);
+    const thread = yield* resolveThreadShell(event.payload.threadId);
     if (!thread) {
       return;
     }
@@ -1575,7 +1586,7 @@ const make = Effect.gen(function* () {
     function* (
       event: Extract<ProviderIntentEvent, { type: "thread.user-input-response-requested" }>,
     ) {
-      const thread = yield* resolveThread(event.payload.threadId);
+      const thread = yield* resolveThreadShell(event.payload.threadId);
       if (!thread) {
         return;
       }
@@ -1619,7 +1630,7 @@ const make = Effect.gen(function* () {
   const processSessionStopRequested = Effect.fn("processSessionStopRequested")(function* (
     event: Extract<ProviderIntentEvent, { type: "thread.session-stop-requested" }>,
   ) {
-    const thread = yield* resolveThread(event.payload.threadId);
+    const thread = yield* resolveThreadShell(event.payload.threadId);
     if (!thread) {
       return;
     }
@@ -1696,7 +1707,7 @@ const make = Effect.gen(function* () {
         yield* threadTitleRegenerationWorker.enqueue(event);
         return;
       case "thread.runtime-mode-set": {
-        const thread = yield* resolveThread(event.payload.threadId);
+        const thread = yield* resolveThreadShell(event.payload.threadId);
         if (!thread?.session || thread.session.status === "stopped") {
           return;
         }
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
index ef9300a196ad..dd6a0b179a8f 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
@@ -2,6 +2,7 @@
 import * as NodeFS from "node:fs";
 import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
+import * as NodeChildProcess from "node:child_process";
 
 import {
   OrchestrationReadModel,
@@ -19,18 +20,22 @@ import {
   type OrchestrationCommand,
   ProjectId,
   ProviderItemId,
+  RuntimeRequestId,
   type ServerSettings,
   ThreadId,
   TurnId,
 } from "@t3tools/contracts";
 import * as Clock from "effect/Clock";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
 import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Option from "effect/Option";
 import * as PubSub from "effect/PubSub";
 import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
+import * as Tracer from "effect/Tracer";
 import { it as effectIt } from "@effect/vitest";
 import { afterEach, describe, expect, it } from "vite-plus/test";
 
@@ -42,6 +47,9 @@ import {
   type ProviderServiceShape,
 } from "../../provider/Services/ProviderService.ts";
 import * as RepositoryIdentityResolver from "../../project/RepositoryIdentityResolver.ts";
+import * as CheckpointStore from "../../checkpointing/CheckpointStore.ts";
+import * as VcsDriverRegistry from "../../vcs/VcsDriverRegistry.ts";
+import * as VcsProcess from "../../vcs/VcsProcess.ts";
 import { OrchestrationEngineLive } from "./OrchestrationEngine.ts";
 import { OrchestrationProjectionPipelineLive } from "./ProjectionPipeline.ts";
 import { OrchestrationProjectionSnapshotQueryLive } from "./ProjectionSnapshotQuery.ts";
@@ -55,6 +63,7 @@ import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts"
 import { ServerConfig } from "../../config.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import { makeSqlStatementCounter } from "../../../integration/SqlStatementCounter.integration.ts";
 
 function makeTestServerSettingsLayer(overrides: Partial<ServerSettings> = {}) {
   return ServerSettingsService.layerTest(overrides);
@@ -98,7 +107,12 @@ function isLegacyTurnCompletedEvent(
 }
 
 function createProviderServiceHarness() {
-  const runtimeEventPubSub = Effect.runSync(PubSub.unbounded<ProviderRuntimeEvent>());
+  const runtimeEventPubSub = Effect.runSync(
+    PubSub.unbounded<{
+      readonly events: ReadonlyArray<ProviderRuntimeEvent>;
+      readonly enqueued?: Deferred.Deferred<void>;
+    }>(),
+  );
   const runtimeSessions: ProviderSession[] = [];
 
   const unsupported = () => Effect.die(new Error("Unsupported provider call in test")) as never;
@@ -129,7 +143,16 @@ function createProviderServiceHarness() {
     rollbackConversation: () => unsupported(),
     uploadFeedback: () => unsupported(),
     get streamEvents() {
-      return Stream.fromPubSub(runtimeEventPubSub);
+      return Stream.fromPubSub(runtimeEventPubSub).pipe(
+        Stream.flatMap(({ events, enqueued }) =>
+          Stream.concat(
+            Stream.fromIterable(events),
+            enqueued
+              ? Stream.fromEffect(Deferred.succeed(enqueued, undefined)).pipe(Stream.drain)
+              : Stream.empty,
+          ),
+        ),
+      );
     },
   };
 
@@ -158,12 +181,24 @@ function createProviderServiceHarness() {
   };
 
   const emit = (event: LegacyProviderRuntimeEvent): void => {
-    Effect.runSync(PubSub.publish(runtimeEventPubSub, normalizeLegacyEvent(event)));
+    Effect.runSync(PubSub.publish(runtimeEventPubSub, { events: [normalizeLegacyEvent(event)] }));
   };
 
+  const emitAndWaitForEnqueue = Effect.fnUntraced(function* (
+    events: ReadonlyArray<LegacyProviderRuntimeEvent>,
+  ) {
+    const enqueued = yield* Deferred.make<void>();
+    yield* PubSub.publish(runtimeEventPubSub, {
+      events: events.map(normalizeLegacyEvent),
+      enqueued,
+    });
+    yield* Deferred.await(enqueued);
+  });
+
   return {
     service,
     emit,
+    emitAndWaitForEnqueue,
     setSession,
   };
 }
@@ -228,10 +263,17 @@ describe("ProviderRuntimeIngestion", () => {
   async function createHarness(options?: {
     serverSettings?: Partial<ServerSettings>;
     threadTitle?: string;
+    workspaceSubdirectory?: string;
   }) {
-    const workspaceRoot = makeTempDir("t3-provider-project-");
-    NodeFS.mkdirSync(NodePath.join(workspaceRoot, ".git"));
+    const repositoryRoot = makeTempDir("t3-provider-project-");
+    NodeChildProcess.execFileSync("git", ["init", "--initial-branch=main"], {
+      cwd: repositoryRoot,
+      stdio: "ignore",
+    });
+    const workspaceRoot = NodePath.join(repositoryRoot, options?.workspaceSubdirectory ?? "");
+    NodeFS.mkdirSync(workspaceRoot, { recursive: true });
     const provider = createProviderServiceHarness();
+    const sqlCounter = makeSqlStatementCounter();
     const orchestrationLayer = OrchestrationEngineLive.pipe(
       Layer.provide(OrchestrationProjectionSnapshotQueryLive),
       Layer.provide(OrchestrationProjectionPipelineLive),
@@ -254,17 +296,26 @@ describe("ProviderRuntimeIngestion", () => {
       Layer.provideMerge(SqlitePersistenceMemory),
       Layer.provideMerge(Layer.succeed(ProviderService, provider.service)),
       Layer.provideMerge(makeTestServerSettingsLayer(options?.serverSettings)),
+      Layer.provideMerge(CheckpointStore.layer.pipe(Layer.provide(VcsDriverRegistry.layer))),
+      Layer.provideMerge(VcsProcess.layer),
       Layer.provideMerge(ServerConfig.layerTest(process.cwd(), process.cwd())),
       Layer.provideMerge(NodeServices.layer),
+      Layer.provideMerge(Layer.succeed(Tracer.Tracer, sqlCounter.tracer)),
     );
-    runtime = ManagedRuntime.make(layer);
-    const engine = await runtime.runPromise(Effect.service(OrchestrationEngineService));
-    const snapshotQuery = await runtime.runPromise(Effect.service(ProjectionSnapshotQuery));
-    const ingestion = await runtime.runPromise(Effect.service(ProviderRuntimeIngestionService));
+    const testRuntime = ManagedRuntime.make(layer);
+    runtime = testRuntime;
+    const engine = await testRuntime.runPromise(Effect.service(OrchestrationEngineService));
+    const snapshotQuery = await testRuntime.runPromise(Effect.service(ProjectionSnapshotQuery));
+    const ingestion = await testRuntime.runPromise(Effect.service(ProviderRuntimeIngestionService));
     scope = await Effect.runPromise(Scope.make("sequential"));
-    await Effect.runPromise(ingestion.start().pipe(Scope.provide(scope)));
-    const drain = () => Effect.runPromise(ingestion.drain);
-    const dispatch = (command: OrchestrationCommand) => Effect.runPromise(engine.dispatch(command));
+    await testRuntime.runPromise(ingestion.start().pipe(Scope.provide(scope)));
+    const drain = () => testRuntime.runPromise(ingestion.drain);
+    const dispatch = (command: OrchestrationCommand) =>
+      testRuntime.runPromise(engine.dispatch(command));
+    const emitAndDrain = (events: ReadonlyArray<LegacyProviderRuntimeEvent>) =>
+      testRuntime.runPromise(
+        provider.emitAndWaitForEnqueue(events).pipe(Effect.andThen(ingestion.drain)),
+      );
 
     const createdAt = "2026-01-01T00:00:00.000Z";
     await dispatch({
@@ -322,8 +373,16 @@ describe("ProviderRuntimeIngestion", () => {
     return {
       engine,
       dispatch,
-      readModel: () => Effect.runPromise(snapshotQuery.getSnapshot()),
+      readModel: () => testRuntime.runPromise(snapshotQuery.getSnapshot()),
+      readThreadShell: () =>
+        testRuntime.runPromise(
+          snapshotQuery
+            .getThreadShellById(asThreadId("thread-1"))
+            .pipe(Effect.map(Option.getOrThrow)),
+        ),
       emit: provider.emit,
+      emitAndDrain,
+      sqlCount: sqlCounter.count,
       setProviderSession: provider.setSession,
       drain,
     };
@@ -371,6 +430,196 @@ describe("ProviderRuntimeIngestion", () => {
     expect(thread.session?.lastError).toBe("turn failed");
   });
 
+  it.each([
+    { delivery: "buffered", enableLegacyTokenStreaming: false },
+    { delivery: "streamed", enableLegacyTokenStreaming: true },
+  ])("settles OpenCode aborted turns and saves $delivery assistant text", async (settings) => {
+    const harness = await createHarness({
+      serverSettings: { enableLegacyTokenStreaming: settings.enableLegacyTokenStreaming },
+    });
+    const threadId = asThreadId("thread-1");
+    const turnId = asTurnId("opencode-aborted-turn");
+    const base = {
+      provider: ProviderDriverKind.make("opencode"),
+      threadId,
+      turnId,
+      createdAt: "2026-01-01T00:00:01.000Z",
+    };
+    harness.emit({ ...base, type: "turn.started", eventId: asEventId("opencode-started") });
+    harness.emit({
+      ...base,
+      type: "content.delta",
+      eventId: asEventId("opencode-partial-text"),
+      itemId: asItemId("opencode-text-part"),
+      payload: { streamKind: "assistant_text", delta: "Work before the stop." },
+    });
+    harness.emit({
+      ...base,
+      type: "turn.aborted",
+      eventId: asEventId("opencode-aborted"),
+      createdAt: "2026-01-01T00:00:02.000Z",
+      payload: { reason: "Interrupted by user." },
+    });
+
+    await harness.drain();
+    const thread = (await harness.readModel()).threads.find((entry) => entry.id === threadId);
+    expect(thread?.session).toMatchObject({
+      status: "interrupted",
+      activeTurnId: null,
+      lastError: null,
+    });
+    expect(thread?.latestTurn).toMatchObject({
+      turnId,
+      state: "interrupted",
+      completedAt: "2026-01-01T00:00:02.000Z",
+    });
+    expect(thread?.messages).toEqual([
+      expect.objectContaining({
+        role: "assistant",
+        turnId,
+        text: "Work before the stop.",
+        streaming: false,
+      }),
+    ]);
+  });
+
+  it.each([
+    { source: "the previous turn", turnId: asTurnId("opencode-stopped-turn") },
+    { source: "an unspecified turn", turnId: undefined },
+  ])("ignores late OpenCode aborts for $source across newer turns", async (lateAbort) => {
+    const harness = await createHarness({
+      serverSettings: { enableLegacyTokenStreaming: true },
+    });
+    const threadId = asThreadId("thread-1");
+    const stoppedTurnId = asTurnId("opencode-stopped-turn");
+    const nextTurnId = asTurnId("opencode-next-turn");
+    const base = {
+      provider: ProviderDriverKind.make("opencode"),
+      threadId,
+      createdAt: "2026-01-01T00:00:01.000Z",
+    };
+    harness.emit({
+      ...base,
+      type: "turn.started",
+      eventId: asEventId("opencode-first-started"),
+      turnId: stoppedTurnId,
+    });
+    harness.emit({
+      ...base,
+      type: "turn.aborted",
+      eventId: asEventId("opencode-first-aborted"),
+      turnId: stoppedTurnId,
+      payload: { reason: "Interrupted by user." },
+    });
+    harness.emit({
+      ...base,
+      type: "turn.started",
+      eventId: asEventId("opencode-next-started"),
+      turnId: nextTurnId,
+    });
+    harness.emit({
+      ...base,
+      type: "content.delta",
+      eventId: asEventId("opencode-next-partial-text"),
+      turnId: nextTurnId,
+      itemId: asItemId("opencode-next-text-part"),
+      payload: { streamKind: "assistant_text", delta: "The next turn is running." },
+    });
+    await harness.drain();
+
+    harness.emit({
+      ...base,
+      type: "turn.aborted",
+      eventId: asEventId("opencode-late-abort"),
+      ...(lateAbort.turnId ? { turnId: lateAbort.turnId } : {}),
+      payload: { reason: "Interrupted by user." },
+    });
+    await harness.drain();
+
+    const thread = (await harness.readModel()).threads.find((entry) => entry.id === threadId);
+    expect(thread?.session).toMatchObject({ status: "running", activeTurnId: nextTurnId });
+    expect(thread?.latestTurn).toMatchObject({ turnId: nextTurnId, state: "running" });
+    expect(thread?.messages).toEqual([
+      expect.objectContaining({
+        turnId: nextTurnId,
+        text: "The next turn is running.",
+        streaming: true,
+      }),
+    ]);
+
+    harness.emit({
+      ...base,
+      type: "turn.completed",
+      eventId: asEventId("opencode-next-completed"),
+      turnId: nextTurnId,
+      createdAt: "2026-01-01T00:00:02.000Z",
+      payload: { state: "completed" },
+    });
+    await harness.drain();
+
+    const pendingAt = "2026-01-01T00:00:03.000Z";
+    for (const hasPendingStart of [false, true]) {
+      if (hasPendingStart) {
+        await harness.dispatch({
+          type: "thread.turn.start",
+          commandId: CommandId.make("opencode-pending-start"),
+          threadId,
+          message: {
+            messageId: asMessageId("opencode-pending-message"),
+            role: "user",
+            text: "Start another turn.",
+            attachments: [],
+          },
+          interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+          runtimeMode: "approval-required",
+          createdAt: pendingAt,
+        });
+        harness.emit({
+          ...base,
+          type: "session.state.changed",
+          eventId: asEventId("opencode-pending-starting"),
+          createdAt: pendingAt,
+          payload: { state: "starting" },
+        });
+      }
+      harness.emit({
+        ...base,
+        type: "turn.aborted",
+        eventId: asEventId(`opencode-late-abort-after-completion-${hasPendingStart}`),
+        ...(lateAbort.turnId ? { turnId: lateAbort.turnId } : {}),
+        createdAt: "2026-01-01T00:00:04.000Z",
+        payload: { reason: "Interrupted by user." },
+      });
+      await harness.drain();
+
+      const completedThread = (await harness.readModel()).threads.find(
+        (entry) => entry.id === threadId,
+      );
+      expect(completedThread?.session).toMatchObject({
+        status: hasPendingStart ? "starting" : "ready",
+        activeTurnId: null,
+      });
+      expect(completedThread?.latestTurn).toMatchObject({ turnId: nextTurnId, state: "completed" });
+    }
+
+    harness.emit({
+      ...base,
+      type: "turn.started",
+      eventId: asEventId("opencode-pending-started"),
+      turnId: asTurnId("opencode-pending-turn"),
+      createdAt: "2026-01-01T00:00:05.000Z",
+    });
+    await harness.drain();
+    const startedThread = (await harness.readModel()).threads.find(
+      (entry) => entry.id === threadId,
+    );
+    expect(startedThread?.latestTurn).toMatchObject({
+      turnId: asTurnId("opencode-pending-turn"),
+      state: "running",
+      requestedAt: pendingAt,
+    });
+  });
+
   it("applies provider session.state.changed transitions directly", async () => {
     const harness = await createHarness();
     const waitingAt = "2026-01-01T00:00:00.000Z";
@@ -1914,39 +2163,40 @@ describe("ProviderRuntimeIngestion", () => {
     expect(proposedPlan?.planMarkdown).toBe("## Buffered plan\n\n- first\n- second");
   });
 
-  it("buffers assistant deltas by default until completion", async () => {
+  it("buffers assistant deltas with one lifecycle query per event until completion", async () => {
     const harness = await createHarness();
     const now = "2026-01-01T00:00:00.000Z";
 
-    harness.emit({
-      type: "turn.started",
-      eventId: asEventId("evt-turn-started-buffered"),
-      provider: ProviderDriverKind.make("codex"),
-      createdAt: now,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-buffered"),
-    });
-    await waitForThread(
-      harness.readModel,
-      (thread) =>
-        thread.session?.status === "running" && thread.session?.activeTurnId === "turn-buffered",
-    );
-
-    harness.emit({
-      type: "content.delta",
-      eventId: asEventId("evt-message-delta-buffered"),
-      provider: ProviderDriverKind.make("codex"),
-      createdAt: now,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-buffered"),
-      itemId: asItemId("item-buffered"),
-      payload: {
-        streamKind: "assistant_text",
-        delta: "buffer me",
+    await harness.emitAndDrain([
+      {
+        type: "turn.started",
+        eventId: asEventId("evt-turn-started-buffered"),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: now,
+        threadId: asThreadId("thread-1"),
+        turnId: asTurnId("turn-buffered"),
       },
-    });
+    ]);
+
+    const eventCount = 1_000;
+    const before = harness.sqlCount();
+    await harness.emitAndDrain(
+      Array.from({ length: eventCount }, (_, index) => ({
+        type: "content.delta",
+        eventId: asEventId(`evt-message-delta-buffered-${index}`),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: now,
+        threadId: asThreadId("thread-1"),
+        turnId: asTurnId("turn-buffered"),
+        itemId: asItemId("item-buffered"),
+        payload: {
+          streamKind: "assistant_text",
+          delta: "a",
+        },
+      })),
+    );
+    expect(harness.sqlCount() - before).toBe(eventCount);
 
-    await harness.drain();
     const midReadModel = await harness.readModel();
     const midThread = midReadModel.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
     expect(
@@ -1955,30 +2205,25 @@ describe("ProviderRuntimeIngestion", () => {
       ),
     ).toBe(false);
 
-    harness.emit({
-      type: "item.completed",
-      eventId: asEventId("evt-message-completed-buffered"),
-      provider: ProviderDriverKind.make("codex"),
-      createdAt: now,
-      threadId: asThreadId("thread-1"),
-      turnId: asTurnId("turn-buffered"),
-      itemId: asItemId("item-buffered"),
-      payload: {
-        itemType: "assistant_message",
-        status: "completed",
+    await harness.emitAndDrain([
+      {
+        type: "item.completed",
+        eventId: asEventId("evt-message-completed-buffered"),
+        provider: ProviderDriverKind.make("codex"),
+        createdAt: now,
+        threadId: asThreadId("thread-1"),
+        turnId: asTurnId("turn-buffered"),
+        itemId: asItemId("item-buffered"),
+        payload: {
+          itemType: "assistant_message",
+          status: "completed",
+        },
       },
-    });
-
-    const thread = await waitForThread(harness.readModel, (entry) =>
-      entry.messages.some(
-        (message: ProviderRuntimeTestMessage) =>
-          message.id === "assistant:item-buffered" && !message.streaming,
-      ),
-    );
-    const message = thread.messages.find(
-      (entry: ProviderRuntimeTestMessage) => entry.id === "assistant:item-buffered",
-    );
-    expect(message?.text).toBe("buffer me");
+    ]);
+    const readModel = await harness.readModel();
+    const thread = readModel.threads.find((entry) => entry.id === asThreadId("thread-1"));
+    const message = thread?.messages.find((entry) => entry.id === "assistant:item-buffered");
+    expect(message?.text).toBe("a".repeat(eventCount));
     expect(message?.streaming).toBe(false);
   });
 
@@ -2109,6 +2354,185 @@ describe("ProviderRuntimeIngestion", () => {
     expect(message?.streaming).toBe(false);
   });
 
+  function userInputEvent(
+    turnId: string,
+    requestId: string,
+    responseMode?: "message",
+  ): ProviderRuntimeEvent {
+    return {
+      type: "user-input.requested",
+      eventId: asEventId(`requested:${requestId}`),
+      provider: ProviderDriverKind.make("codex"),
+      threadId: asThreadId("thread-1"),
+      turnId: asTurnId(turnId),
+      requestId: RuntimeRequestId.make(requestId),
+      createdAt: "2026-01-01T00:00:01.000Z",
+      payload: {
+        ...(responseMode ? { responseMode } : {}),
+        questions: ["first", "second"].map((id) => ({
+          id,
+          header: id,
+          question: `Choose ${id}`,
+          options: [{ label: "yes", description: "Continue" }],
+          multiSelect: false,
+        })),
+      },
+    };
+  }
+
+  it.each(["completed", "interrupted", "failed", "aborted"] as const)(
+    "resolves native questions when their turn is %s",
+    async (state) => {
+      const harness = await createHarness();
+      const request = userInputEvent("question-turn", "question-request");
+      await harness.emitAndDrain([
+        {
+          type: "turn.started",
+          eventId: asEventId("question-started"),
+          provider: request.provider,
+          threadId: request.threadId,
+          turnId: request.turnId,
+          createdAt: request.createdAt,
+        },
+        request,
+      ]);
+      expect((await harness.readThreadShell()).hasPendingUserInput).toBe(true);
+      if (state === "interrupted") {
+        await harness.dispatch({
+          type: "thread.turn.interrupt",
+          commandId: CommandId.make("question-interrupt"),
+          threadId: request.threadId,
+          createdAt: "2026-01-01T00:00:02.000Z",
+        });
+      }
+      const completed: ProviderRuntimeEvent = {
+        ...(state === "aborted"
+          ? ({ type: "turn.aborted", payload: { reason: "Interrupted by user." } } as const)
+          : ({ type: "turn.completed", payload: { state } } as const)),
+        eventId: asEventId("question-completed"),
+        provider: request.provider,
+        threadId: request.threadId,
+        turnId: request.turnId,
+        createdAt: "2026-01-01T00:00:03.000Z",
+      };
+      await harness.emitAndDrain([completed]);
+      const thread = (await harness.readModel()).threads[0]!;
+      expect(thread.session?.activeTurnId).toBeNull();
+      expect((await harness.readThreadShell()).hasPendingUserInput).toBe(false);
+      expect(
+        thread.activities.filter((activity) => activity.kind === "user-input.resolved"),
+      ).toMatchObject([{ turnId: request.turnId, payload: { requestId: request.requestId } }]);
+
+      await harness.emitAndDrain([completed]);
+      expect(
+        (await harness.readModel()).threads[0]!.activities.filter(
+          (activity) => activity.kind === "user-input.resolved",
+        ),
+      ).toHaveLength(1);
+    },
+  );
+
+  it("keeps a stale request dismissed when its turn later completes", async () => {
+    const harness = await createHarness();
+    const request = userInputEvent("stale-turn", "stale-question");
+    await harness.emitAndDrain([request]);
+    await harness.dispatch({
+      type: "thread.activity.append",
+      commandId: CommandId.make("stale-question-response"),
+      threadId: request.threadId,
+      activity: {
+        id: asEventId("stale-question-failed"),
+        kind: "provider.user-input.respond.failed",
+        tone: "error",
+        summary: "User input response failed",
+        turnId: request.turnId ?? null,
+        payload: {
+          requestId: request.requestId,
+          detail: "Unknown pending user input request",
+        },
+        createdAt: "2026-01-01T00:00:02.000Z",
+      },
+      createdAt: "2026-01-01T00:00:02.000Z",
+    });
+    expect((await harness.readThreadShell()).hasPendingUserInput).toBe(false);
+    await harness.emitAndDrain([
+      {
+        type: "turn.completed",
+        eventId: asEventId("stale-turn-completed"),
+        provider: request.provider,
+        threadId: request.threadId,
+        turnId: request.turnId,
+        createdAt: "2026-01-01T00:00:03.000Z",
+        payload: { state: "completed" },
+      },
+    ]);
+    expect((await harness.readThreadShell()).hasPendingUserInput).toBe(false);
+    expect(
+      (await harness.readModel()).threads[0]!.activities.filter(
+        (activity) => activity.kind === "user-input.resolved",
+      ),
+    ).toMatchObject([{ payload: { requestId: request.requestId } }]);
+  });
+
+  it("preserves answered questions and leaves newer, child and async questions pending", async () => {
+    const harness = await createHarness();
+    const answered = userInputEvent("old-turn", "answered-question");
+    const unresolved = userInputEvent("old-turn", "old-question");
+    const newer = userInputEvent("new-turn", "new-question");
+    const child = userInputEvent("child-turn", "child-question");
+    const asynchronous = userInputEvent("old-turn", "async-question", "message");
+    const answer: ProviderRuntimeEvent = {
+      type: "user-input.resolved",
+      eventId: asEventId("normal-answer"),
+      provider: answered.provider,
+      threadId: answered.threadId,
+      turnId: answered.turnId,
+      requestId: answered.requestId,
+      createdAt: "2026-01-01T00:00:02.000Z",
+      payload: { answers: { first: "yes", second: "yes" } },
+    };
+    await harness.emitAndDrain([
+      answered,
+      unresolved,
+      newer,
+      child,
+      asynchronous,
+      answer,
+      {
+        type: "turn.started",
+        eventId: asEventId("new-turn-started"),
+        provider: newer.provider,
+        threadId: newer.threadId,
+        turnId: newer.turnId,
+        createdAt: "2026-01-01T00:00:03.000Z",
+      },
+    ]);
+    expect((await harness.readThreadShell()).hasPendingUserInput).toBe(true);
+    await harness.emitAndDrain([
+      {
+        type: "turn.completed",
+        eventId: asEventId("old-turn-completed"),
+        provider: answered.provider,
+        threadId: answered.threadId,
+        turnId: answered.turnId,
+        createdAt: "2026-01-01T00:00:04.000Z",
+        payload: { state: "interrupted" },
+      },
+    ]);
+    const thread = (await harness.readModel()).threads[0]!;
+    expect(thread.session?.activeTurnId).toBe(newer.turnId);
+    expect((await harness.readThreadShell()).hasPendingUserInput).toBe(true);
+    expect(
+      thread.activities.filter((activity) => activity.kind === "user-input.resolved"),
+    ).toMatchObject([
+      {
+        id: answer.eventId,
+        payload: { requestId: answered.requestId, answers: answer.payload.answers },
+      },
+      { turnId: unresolved.turnId, payload: { requestId: unresolved.requestId } },
+    ]);
+  });
+
   it("keeps streaming while an async question is pending", async () => {
     const harness = await createHarness({ serverSettings: { enableLegacyTokenStreaming: true } });
     const base = {
@@ -2952,6 +3376,33 @@ describe("ProviderRuntimeIngestion", () => {
     });
   });
 
+  effectIt.effect("tracks provider diff updates from a nested Git workspace", () =>
+    Effect.gen(function* () {
+      const harness = yield* Effect.promise(() =>
+        createHarness({ workspaceSubdirectory: "apps/server" }),
+      );
+      yield* Effect.promise(() =>
+        harness.emitAndDrain([
+          {
+            type: "turn.diff.updated",
+            eventId: asEventId("evt-nested-diff"),
+            provider: ProviderDriverKind.make("codex"),
+            createdAt: "2026-01-01T00:00:00.000Z",
+            threadId: asThreadId("thread-1"),
+            turnId: asTurnId("nested-turn"),
+            payload: {
+              unifiedDiff: "diff --git a/apps/server/file.ts b/apps/server/file.ts\n+new\n",
+            },
+          },
+        ]),
+      );
+      const snapshot = yield* Effect.promise(harness.readModel);
+      expect(snapshot.threads[0]?.checkpoints).toEqual([
+        expect.objectContaining({ turnId: "nested-turn", status: "missing" }),
+      ]);
+    }),
+  );
+
   it("consumes P1 runtime events into thread metadata, diff checkpoints, and activities", async () => {
     const harness = await createHarness();
     const now = "2026-01-01T00:00:00.000Z";
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
index f78088675045..cf59d00a248b 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
@@ -36,7 +36,9 @@ import { formatTokens } from "@t3tools/shared/usageFormat";
 import { ProviderService } from "../../provider/Services/ProviderService.ts";
 import { ProjectionTurnRepository } from "../../persistence/Services/ProjectionTurns.ts";
 import { ProjectionTurnRepositoryLive } from "../../persistence/Layers/ProjectionTurns.ts";
-import { isGitRepository } from "../../git/Utils.ts";
+import { ProjectionThreadActivityRepository } from "../../persistence/Services/ProjectionThreadActivities.ts";
+import { ProjectionThreadActivityRepositoryLive } from "../../persistence/Layers/ProjectionThreadActivities.ts";
+import * as CheckpointStore from "../../checkpointing/CheckpointStore.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
 import { ThreadBackgroundLivenessService } from "../ThreadBackgroundLiveness.ts";
 import { ThreadPlanProgressService } from "../ThreadPlanProgress.ts";
@@ -955,7 +957,9 @@ const make = Effect.gen(function* () {
   const projectionSnapshotQuery = yield* ProjectionSnapshotQuery;
   const providerService = yield* ProviderService;
   const projectionTurnRepository = yield* ProjectionTurnRepository;
+  const projectionThreadActivityRepository = yield* ProjectionThreadActivityRepository;
   const serverSettingsService = yield* ServerSettingsService;
+  const checkpointStore = yield* CheckpointStore.CheckpointStore;
   const providerCommandId = (event: ProviderRuntimeEvent, tag: string) =>
     crypto.randomUUIDv4.pipe(
       Effect.map((uuid) => CommandId.make(`provider:${event.eventId}:${tag}:${uuid}`)),
@@ -1018,9 +1022,11 @@ const make = Effect.gen(function* () {
       .pipe(Effect.map(Option.getOrUndefined));
   });
 
-  const resolveThreadShell = Effect.fn("resolveThreadShell")(function* (threadId: ThreadId) {
+  const resolveThreadRuntimeContext = Effect.fn("resolveThreadRuntimeContext")(function* (
+    threadId: ThreadId,
+  ) {
     return yield* projectionSnapshotQuery
-      .getThreadShellById(threadId)
+      .getThreadRuntimeContext(threadId)
       .pipe(Effect.map(Option.getOrUndefined));
   });
 
@@ -1562,7 +1568,7 @@ const make = Effect.gen(function* () {
         return;
       }
 
-      const thread = yield* resolveThreadShell(event.threadId);
+      const thread = yield* resolveThreadRuntimeContext(event.threadId);
       if (!thread) return;
 
       let loadedThreadDetail: OrchestrationThread | null | undefined;
@@ -1578,6 +1584,7 @@ const make = Effect.gen(function* () {
       const now = event.createdAt;
       const eventTurnId = toTurnId(event.turnId);
       const activeTurnId = thread.session?.activeTurnId ?? null;
+      const isTerminalTurn = event.type === "turn.completed" || event.type === "turn.aborted";
       const isCompactedThreadState =
         event.type === "thread.state.changed" && event.payload.state === "compacted";
       const pendingTurnStart =
@@ -1586,7 +1593,7 @@ const make = Effect.gen(function* () {
         event.type === "session.exited" ||
         event.type === "thread.started" ||
         event.type === "turn.started" ||
-        event.type === "turn.completed" ||
+        isTerminalTurn ||
         isCompactedThreadState
           ? yield* projectionTurnRepository.getPendingTurnStartByThreadId({
               threadId: thread.id,
@@ -1624,6 +1631,7 @@ const make = Effect.gen(function* () {
           case "turn.started":
             return !conflictsWithActiveTurn || conflictingTurnStartIsPendingTurnStart;
           case "turn.completed":
+          case "turn.aborted":
             if (conflictsWithActiveTurn || missingTurnForActiveTurn) {
               return false;
             }
@@ -1631,14 +1639,10 @@ const make = Effect.gen(function* () {
             if (activeTurnId !== null && eventTurnId !== undefined) {
               return sameId(activeTurnId, eventTurnId);
             }
-            // No active turn tracked: accept only completions that name their
-            // turn (covers a real completion whose turn.started was lost). An
-            // untargeted completion cannot prove it belongs to any turn this
-            // thread ran — the known emitter was the Claude resume handshake
-            // (system/init + result(num_turns: 0)), which is not a turn at
-            // all — and applying it here stomps the "starting" lifecycle
-            // state while a turn start is pending.
-            return eventTurnId !== undefined;
+            // A named completion can recover a lost turn.started event.
+            // An abort needs an active turn so a delayed stop cannot replace
+            // a ready session or clear a newer pending start.
+            return event.type === "turn.completed" && eventTurnId !== undefined;
           default:
             return true;
         }
@@ -1654,7 +1658,7 @@ const make = Effect.gen(function* () {
         event.type === "session.exited" ||
         event.type === "thread.started" ||
         event.type === "turn.started" ||
-        event.type === "turn.completed"
+        isTerminalTurn
       ) {
         const status = (() => {
           switch (event.type) {
@@ -1666,6 +1670,8 @@ const make = Effect.gen(function* () {
               return "running";
             case "session.exited":
               return "stopped";
+            case "turn.aborted":
+              return "interrupted";
             case "turn.completed":
               return normalizeRuntimeTurnState(event.payload.state) === "failed"
                 ? "error"
@@ -1680,7 +1686,7 @@ const make = Effect.gen(function* () {
         const nextActiveTurnId =
           event.type === "turn.started"
             ? (eventTurnId ?? null)
-            : event.type === "turn.completed" || event.type === "session.exited"
+            : isTerminalTurn || event.type === "session.exited"
               ? null
               : event.type === "session.state.changed" &&
                   !sessionStatusAllowsActiveTurn(
@@ -1694,7 +1700,7 @@ const make = Effect.gen(function* () {
             : event.type === "turn.completed" &&
                 normalizeRuntimeTurnState(event.payload.state) === "failed"
               ? (event.payload.errorMessage ?? thread.session?.lastError ?? "Turn failed")
-              : status === "ready"
+              : status === "ready" || status === "interrupted"
                 ? null
                 : (thread.session?.lastError ?? null);
 
@@ -1922,12 +1928,53 @@ const make = Effect.gen(function* () {
         });
       }
 
-      if (event.type === "turn.completed") {
+      if (isTerminalTurn) {
         const detailedThread = yield* getLoadedThreadDetail();
         const messages = detailedThread?.messages ?? [];
         const proposedPlans = detailedThread?.proposedPlans ?? [];
         const turnId = toTurnId(event.turnId);
         if (turnId) {
+          const userInputActivities =
+            yield* projectionThreadActivityRepository.listUserInputLifecycleByThreadId({
+              threadId: thread.id,
+            });
+          const pendingRequestIds = new Set<string>();
+          for (const activity of userInputActivities) {
+            const payload =
+              typeof activity.payload === "object" && activity.payload !== null
+                ? (activity.payload as Record<string, unknown>)
+                : null;
+            const requestId = payload?.requestId;
+            if (typeof requestId !== "string") continue;
+            if (
+              activity.kind === "user-input.requested" &&
+              activity.turnId === turnId &&
+              payload?.responseMode !== "message"
+            ) {
+              pendingRequestIds.add(requestId);
+            } else if (activity.kind === "user-input.resolved") {
+              pendingRequestIds.delete(requestId);
+            }
+          }
+          // A terminal turn cannot accept native callback answers. Message-mode
+          // questions may outlive that turn and still accept a later user message.
+          for (const requestId of pendingRequestIds) {
+            yield* orchestrationEngine.dispatch({
+              type: "thread.activity.append",
+              commandId: yield* providerCommandId(event, "terminal-user-input-resolved"),
+              threadId: thread.id,
+              activity: {
+                id: EventId.make(`${event.eventId}:user-input-resolved:${requestId}`),
+                createdAt: now,
+                tone: "info",
+                kind: "user-input.resolved",
+                summary: "User input dismissed",
+                payload: { requestId },
+                turnId,
+              },
+              createdAt: now,
+            });
+          }
           const assistantMessageIds = yield* getAssistantMessageIdsForTurn(thread.id, turnId);
           yield* Effect.forEach(
             assistantMessageIds,
@@ -2011,7 +2058,12 @@ const make = Effect.gen(function* () {
           : undefined;
         const workspaceCwd =
           checkpointContext?.worktreePath ?? checkpointContext?.workspaceRoot ?? undefined;
-        if (turnId && checkpointContext && workspaceCwd && isGitRepository(workspaceCwd)) {
+        if (
+          turnId &&
+          checkpointContext &&
+          workspaceCwd &&
+          (yield* checkpointStore.isGitRepository(workspaceCwd))
+        ) {
           // Skip if a checkpoint already exists for this turn. A real
           // (non-placeholder) capture from CheckpointReactor should not
           // be clobbered, and dispatching a duplicate placeholder for the
@@ -2055,7 +2107,7 @@ const make = Effect.gen(function* () {
       } else if (!conflictsWithActiveTurn) {
         if (event.type === "turn.plan.updated") {
           threadPlanProgress.recordPlanProgress(thread.id, event.payload.plan);
-        } else if (event.type === "turn.completed" || event.type === "turn.aborted") {
+        } else if (isTerminalTurn && shouldApplyThreadLifecycle) {
           threadPlanProgress.clearThreadPlanProgress(thread.id);
         }
       }
@@ -2221,4 +2273,7 @@ const make = Effect.gen(function* () {
 export const ProviderRuntimeIngestionLive = Layer.effect(
   ProviderRuntimeIngestionService,
   make,
-).pipe(Layer.provide(ProjectionTurnRepositoryLive));
+).pipe(
+  Layer.provide(ProjectionTurnRepositoryLive),
+  Layer.provide(ProjectionThreadActivityRepositoryLive),
+);
diff --git a/apps/server/src/orchestration/LiveStreamBudget.test.ts b/apps/server/src/orchestration/LiveStreamBudget.test.ts
new file mode 100644
index 000000000000..d163a8317fc0
--- /dev/null
+++ b/apps/server/src/orchestration/LiveStreamBudget.test.ts
@@ -0,0 +1,47 @@
+import { it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+import { describe, expect } from "vite-plus/test";
+
+import { makeLiveStreamBudget, type RetainedLiveItem } from "./LiveStreamBudget.ts";
+
+describe("LiveStreamBudget", () => {
+  it.effect("closes the source without releasing a batch still waiting for an ACK", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const budget = yield* makeLiveStreamBudget({ maxItems: 3 });
+        const queue = yield* Queue.unbounded<RetainedLiveItem<{ text: string }>>();
+        const sourceClosed = yield* Deferred.make<void>();
+        const first = yield* budget.retain({ text: "first" });
+        const second = yield* budget.retain({ text: "second" });
+        const third = yield* budget.retain({ text: "third" });
+        yield* Queue.offerAll(queue, [first, second, third]);
+        yield* Effect.scoped(
+          Effect.gen(function* () {
+            const pull = yield* Stream.toPull(
+              budget.deliver(
+                Stream.fromQueue(queue).pipe(
+                  Stream.rechunk(1),
+                  Stream.ensuring(Deferred.succeed(sourceClosed, undefined)),
+                ),
+              ),
+            );
+            expect(yield* pull).toEqual([{ text: "first" }]);
+            // The other two items are in the source's pull state, not its queue.
+            expect(yield* Queue.size(queue)).toBe(0);
+            expect((yield* budget.usage).retainedItems).toBe(3);
+            const overflow = yield* budget.retain({ text: "fourth" }).pipe(Effect.result);
+            expect(overflow._tag).toBe("Failure");
+            // Do not resume the consumer. Its source scope must close now.
+            yield* Deferred.await(sourceClosed);
+            yield* budget.closed;
+            expect((yield* budget.usage).retainedItems).toBe(1);
+          }),
+        );
+        expect(yield* budget.usage).toEqual({ retainedItems: 0, retainedSerializedBytes: 0 });
+      }),
+    ),
+  );
+});
diff --git a/apps/server/src/orchestration/LiveStreamBudget.ts b/apps/server/src/orchestration/LiveStreamBudget.ts
new file mode 100644
index 000000000000..e86127b2b2df
--- /dev/null
+++ b/apps/server/src/orchestration/LiveStreamBudget.ts
@@ -0,0 +1,196 @@
+import { OrchestrationGetSnapshotError } from "@t3tools/contracts";
+import * as Arr from "effect/Array";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
+
+export const LIVE_STREAM_MAX_ITEMS = 1_000;
+export const LIVE_STREAM_MAX_SERIALIZED_BYTES = 8 * 1024 * 1024;
+
+export interface RetainedLiveItem<A> {
+  readonly value: A;
+  readonly serializedBytes: number;
+}
+
+// Published events are immutable and shared across subscriptions. Measure each
+// object once without keeping the event or its serialized copy alive.
+const serializedSizes = new WeakMap<object, number>();
+
+function serializedSize(value: object): number {
+  const cached = serializedSizes.get(value);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const bytes = Buffer.byteLength(JSON.stringify(value));
+  serializedSizes.set(value, bytes);
+  return bytes;
+}
+
+/** One budget covers one subscription and its delivery stream, including the batch waiting for an RPC ACK. */
+export const makeLiveStreamBudget = Effect.fn("makeLiveStreamBudget")(function* (limits?: {
+  readonly maxItems?: number;
+  readonly maxSerializedBytes?: number;
+}) {
+  const maxItems = limits?.maxItems ?? LIVE_STREAM_MAX_ITEMS;
+  const maxSerializedBytes = limits?.maxSerializedBytes ?? LIVE_STREAM_MAX_SERIALIZED_BYTES;
+  const failed = yield* Deferred.make<never, OrchestrationGetSnapshotError>();
+  const cleanupComplete = yield* Deferred.make<void>();
+  let failure: OrchestrationGetSnapshotError | undefined;
+  const retained = new Set<RetainedLiveItem<unknown>>();
+  let retainedSerializedBytes = 0;
+
+  const release = (items: Iterable<RetainedLiveItem<unknown>>) => {
+    for (const item of items) {
+      if (!retained.delete(item)) {
+        continue;
+      }
+      retainedSerializedBytes -= item.serializedBytes;
+    }
+  };
+  yield* Effect.addFinalizer(() =>
+    Effect.sync(() => release(retained)).pipe(
+      Effect.andThen(Deferred.succeed(cleanupComplete, undefined)),
+    ),
+  );
+
+  const check = Effect.suspend(() => (failure ? Effect.fail(failure) : Effect.void));
+
+  const overflow = Effect.fn("LiveStreamBudget.overflow")(function* (
+    nextItems: number,
+    nextSerializedBytes: number,
+  ) {
+    failure ??= new OrchestrationGetSnapshotError({
+      message: "The live event buffer is full. Resume from the last received sequence.",
+    });
+    yield* Deferred.fail(failed, failure);
+    yield* Effect.logWarning("orchestration live event buffer is full", {
+      retainedItems: retained.size,
+      retainedSerializedBytes,
+      nextItems,
+      nextSerializedBytes,
+      maxItems,
+      maxSerializedBytes,
+    });
+    return yield* failure;
+  });
+
+  const retain = <A extends object>(value: A, payload: object = value) =>
+    Effect.suspend(() => {
+      if (failure) {
+        return Effect.fail(failure);
+      }
+      const serializedBytes = serializedSize(payload);
+      const nextItems = retained.size + 1;
+      const nextSerializedBytes = retainedSerializedBytes + serializedBytes;
+      if (nextItems > maxItems || nextSerializedBytes > maxSerializedBytes) {
+        return overflow(nextItems, nextSerializedBytes);
+      }
+      const item = { value, serializedBytes };
+      retained.add(item);
+      retainedSerializedBytes = nextSerializedBytes;
+      return Effect.succeed(item);
+    });
+
+  // Replace one coalescing batch atomically. Queued and coalesced payloads
+  // count against the same budget, and discarded updates release their charge.
+  const replace = <A extends object>(
+    previous: ReadonlyArray<RetainedLiveItem<unknown>>,
+    values: ReadonlyArray<A>,
+    payload: (value: A) => object = (value) => value,
+  ) =>
+    Effect.suspend(() => {
+      if (failure) {
+        return Effect.fail(failure);
+      }
+      const next = values.map((value) => ({
+        value,
+        serializedBytes: serializedSize(payload(value)),
+      }));
+      let nextItems = retained.size + next.length;
+      let nextSerializedBytes =
+        retainedSerializedBytes + next.reduce((sum, item) => sum + item.serializedBytes, 0);
+      for (const item of previous) {
+        if (retained.has(item)) {
+          nextItems -= 1;
+          nextSerializedBytes -= item.serializedBytes;
+        }
+      }
+      if (nextItems > maxItems || nextSerializedBytes > maxSerializedBytes) {
+        return overflow(nextItems, nextSerializedBytes);
+      }
+      release(previous);
+      for (const item of next) {
+        retained.add(item);
+      }
+      retainedSerializedBytes = nextSerializedBytes;
+      return Effect.succeed(next);
+    });
+
+  const deliver = <A, E, R>(stream: Stream.Stream<RetainedLiveItem<A>, E, R>) =>
+    Stream.fromPull(
+      Effect.gen(function* () {
+        yield* check;
+        const sourceScope = yield* Scope.fork(yield* Effect.scope);
+        const source = {
+          pull: yield* Stream.toPull(stream).pipe(Scope.provide(sourceScope)),
+        };
+        let inFlight: ReadonlyArray<RetainedLiveItem<A>> = [];
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => {
+            release(inFlight);
+            inFlight = [];
+            source.pull = Effect.interrupt;
+          }),
+        );
+        yield* Deferred.await(failed).pipe(
+          Effect.catchTags({
+            OrchestrationGetSnapshotError: (error) =>
+              Effect.sync(() => {
+                // A grouped source can retain its own pending chunk. Close it
+                // and release the pull closure without waiting for an RPC ACK.
+                source.pull = Effect.interrupt;
+              }).pipe(
+                Effect.andThen(Scope.close(sourceScope, Exit.fail(error))),
+                Effect.andThen(
+                  Effect.sync(() => {
+                    const delivered = new Set<RetainedLiveItem<unknown>>(inFlight);
+                    for (const item of retained) {
+                      if (!delivered.has(item)) {
+                        release([item]);
+                      }
+                    }
+                  }),
+                ),
+                Effect.andThen(Deferred.succeed(cleanupComplete, undefined)),
+              ),
+          }),
+          Effect.forkScoped,
+        );
+        // @effect-diagnostics-next-line returnEffectInGen:off - Stream.fromPull needs the pull effect as its result.
+        return Effect.gen(function* () {
+          // RpcServer requests the next batch only after the client ACKs this
+          // one. Removing items from a queue alone does not mean delivery ended.
+          release(inFlight);
+          inFlight = [];
+          yield* check;
+          const items = yield* Effect.raceFirst(source.pull, Deferred.await(failed));
+          inFlight = items;
+          yield* check;
+          return Arr.map(items, (item) => item.value);
+        });
+      }),
+    );
+
+  return {
+    retain,
+    replace,
+    release,
+    deliver,
+    check,
+    failed: Deferred.await(failed),
+    closed: Deferred.await(cleanupComplete),
+    usage: Effect.sync(() => ({ retainedItems: retained.size, retainedSerializedBytes })),
+  };
+});
diff --git a/apps/server/src/orchestration/Services/OrchestrationEngine.ts b/apps/server/src/orchestration/Services/OrchestrationEngine.ts
index 08f63c476422..cf2ef2a40354 100644
--- a/apps/server/src/orchestration/Services/OrchestrationEngine.ts
+++ b/apps/server/src/orchestration/Services/OrchestrationEngine.ts
@@ -14,6 +14,7 @@ import type {
   OrchestrationClientOrigin,
   OrchestrationCommand,
   OrchestrationEvent,
+  ThreadId,
 } from "@t3tools/contracts";
 import * as Context from "effect/Context";
 import type * as Effect from "effect/Effect";
@@ -22,6 +23,13 @@ import type * as Stream from "effect/Stream";
 
 import type { OrchestrationDispatchError } from "../Errors.ts";
 import type { OrchestrationEventStoreError } from "../../persistence/Errors.ts";
+import type { OrchestrationAggregateReplayStats } from "../../persistence/Services/OrchestrationEventStore.ts";
+
+export interface OrchestrationThreadReplayRange {
+  readonly threadId: ThreadId;
+  readonly fromSequenceExclusive: number;
+  readonly toSequenceInclusive: number;
+}
 
 /**
  * OrchestrationEngineShape - Service API for orchestration command and event flow.
@@ -33,8 +41,7 @@ export interface OrchestrationEngineShape {
    * @param fromSequenceExclusive - Sequence cursor (exclusive).
    * @param limit - Maximum number of events to read. Defaults to the event
    *   store's page-bounded default; pass a higher value when the caller must
-   *   read every event after the cursor (e.g. per-thread catch-up that filters
-   *   a small subset out of a potentially larger global range).
+   *   read a wider global range. Thread subscriptions use readThreadEvents.
    * @returns Stream containing ordered events.
    */
   readonly readEvents: (
@@ -42,6 +49,16 @@ export interface OrchestrationEngineShape {
     limit?: number,
   ) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError, never>;
 
+  /** Read only this thread's events through a captured authoritative head. */
+  readonly readThreadEvents: (
+    input: OrchestrationThreadReplayRange & { readonly limit?: number },
+  ) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError>;
+
+  /** Measure a bounded thread replay without decoding its event bodies. */
+  readonly getThreadReplayStats: (
+    input: OrchestrationThreadReplayRange & { readonly maxEvents: number },
+  ) => Effect.Effect<OrchestrationAggregateReplayStats, OrchestrationEventStoreError>;
+
   /**
    * Dispatch a validated orchestration command.
    *
diff --git a/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts b/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
index 0854492e255b..37bcc1ae8f39 100644
--- a/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
+++ b/apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
@@ -7,6 +7,7 @@
  * @module ProjectionSnapshotQuery
  */
 import type {
+  AgentSessionImportSource,
   ApprovalRequestId,
   CheckpointRef,
   OrchestrationCheckpointSummary,
@@ -170,6 +171,15 @@ export interface ProjectionSnapshotQueryShape {
     projectId: ProjectId,
   ) => Effect.Effect<Option.Option<ThreadId>, ProjectionRepositoryError>;
 
+  /** Read completed import sources without loading thread history. */
+  readonly getImportedAgentSessionSources: (projectId: ProjectId) => Effect.Effect<
+    ReadonlyArray<{
+      readonly threadId: ThreadId;
+      readonly source: AgentSessionImportSource;
+    }>,
+    ProjectionRepositoryError
+  >;
+
   /**
    * Read the checkpoint context needed to resolve a single thread diff.
    */
@@ -193,6 +203,14 @@ export interface ProjectionSnapshotQueryShape {
     threadId: ThreadId,
   ) => Effect.Effect<Option.Option<OrchestrationThreadShell>, ProjectionRepositoryError>;
 
+  /** Read the active thread and session facts used to ingest provider events. */
+  readonly getThreadRuntimeContext: (
+    threadId: ThreadId,
+  ) => Effect.Effect<
+    Option.Option<Pick<OrchestrationThreadShell, "id" | "title" | "session">>,
+    ProjectionRepositoryError
+  >;
+
   /**
    * Read a single active thread detail snapshot by id.
    */
diff --git a/apps/server/src/orchestration/ThreadLiveEventCoalescer.test.ts b/apps/server/src/orchestration/ThreadLiveEventCoalescer.test.ts
index 0a9915294d03..440356ef933a 100644
--- a/apps/server/src/orchestration/ThreadLiveEventCoalescer.test.ts
+++ b/apps/server/src/orchestration/ThreadLiveEventCoalescer.test.ts
@@ -3,12 +3,14 @@ import {
   MessageId,
   ThreadId,
   TurnId,
-  type OrchestrationEvent,
+  OrchestrationEvent,
   type OrchestrationThreadActivity,
 } from "@t3tools/contracts";
 import { it } from "@effect/vitest";
 import * as Clock from "effect/Clock";
 import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import * as TestClock from "effect/testing/TestClock";
 import { describe, expect } from "vite-plus/test";
 
@@ -19,6 +21,7 @@ import {
 
 const threadId = ThreadId.make("thread-coalescer-test");
 const turnId = TurnId.make("turn-coalescer-test");
+const encodeEvent = Schema.encodeSync(Schema.fromJsonString(OrchestrationEvent));
 
 function makeToolActivity(
   sequence: number,
@@ -61,7 +64,7 @@ function makeToolActivity(
   };
 }
 
-function makeMessage(sequence: number): OrchestrationEvent {
+function makeMessage(sequence: number, text = "Still working"): OrchestrationEvent {
   return {
     sequence,
     eventId: EventId.make(`event-${sequence}`),
@@ -77,7 +80,7 @@ function makeMessage(sequence: number): OrchestrationEvent {
       threadId,
       messageId: MessageId.make(`message-${sequence}`),
       role: "assistant",
-      text: "Still working",
+      text,
       turnId,
       streaming: false,
       createdAt: "2026-01-01T00:00:02.000Z",
@@ -134,15 +137,14 @@ describe("ThreadLiveEventCoalescer", () => {
         const startedAt = yield* Clock.currentTimeMillis;
         yield* Effect.forEach(
           Array.from({ length: 10 }, (_, index) => index + 2),
-          (sequence) =>
-            coalescer.offerAndWait({ kind: "event", event: makeToolActivity(sequence) }),
+          (sequence) => coalescer.offer({ kind: "event", event: makeToolActivity(sequence) }),
           { discard: true },
         );
-        yield* coalescer.offerAndWait({ kind: "event", event: makeMessage(12) });
+        yield* coalescer.offer({ kind: "event", event: makeMessage(12) });
 
         expect(yield* Clock.currentTimeMillis).toBe(startedAt);
         expect(
-          Array.from(yield* coalescer.takeAll).map((item) =>
+          (yield* coalescer.stream.pipe(Stream.take(2), Stream.runCollect)).map((item) =>
             item.kind === "event" ? item.event.sequence : item.kind,
           ),
         ).toEqual([11, 12]);
@@ -155,17 +157,94 @@ describe("ThreadLiveEventCoalescer", () => {
       Effect.gen(function* () {
         const coalescer = yield* makeThreadLiveEventCoalescer({ coalesceWindow: "500 millis" });
         const startedAt = yield* Clock.currentTimeMillis;
-        yield* coalescer.offerAndWait({ kind: "event", event: makeToolActivity(2) });
-        yield* coalescer.offerAndWait({ kind: "event", event: makeToolActivity(3) });
-        yield* coalescer.offerAndWait({ kind: "synchronized" });
+        yield* coalescer.offer({ kind: "event", event: makeToolActivity(2) });
+        yield* coalescer.offer({ kind: "event", event: makeToolActivity(3) });
+        yield* coalescer.offer({ kind: "synchronized" });
 
         expect(yield* Clock.currentTimeMillis).toBe(startedAt);
         expect(
-          Array.from(yield* coalescer.takeAll).map((item) =>
+          (yield* coalescer.stream.pipe(Stream.take(2), Stream.runCollect)).map((item) =>
             item.kind === "event" ? item.event.sequence : item.kind,
           ),
         ).toEqual([3, "synchronized"]);
       }),
     ).pipe(Effect.provide(TestClock.layer())),
   );
+
+  it.effect("fails and clears pending updates when their serialized payload fills the budget", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const first = makeToolActivity(1);
+        const coalescer = yield* makeThreadLiveEventCoalescer({
+          coalesceWindow: "500 millis",
+          maxSerializedBytes: Buffer.byteLength(encodeEvent(first)),
+        });
+        yield* coalescer.offer({ kind: "event", event: first });
+        expect(yield* coalescer.usage).toEqual({
+          retainedItems: 1,
+          retainedSerializedBytes: Buffer.byteLength(encodeEvent(first)),
+        });
+
+        const overflow = yield* coalescer
+          .offer({ kind: "event", event: makeToolActivity(2) })
+          .pipe(Effect.result);
+        expect(overflow._tag).toBe("Failure");
+        yield* coalescer.closed;
+        expect(yield* coalescer.usage).toEqual({ retainedItems: 0, retainedSerializedBytes: 0 });
+        const marker = yield* coalescer.offer({ kind: "synchronized" }).pipe(Effect.result);
+        expect(marker._tag).toBe("Failure");
+        const delivered = yield* coalescer.stream.pipe(Stream.runCollect, Effect.result);
+        expect(delivered._tag).toBe("Failure");
+      }),
+    ),
+  );
+
+  it.effect("keeps the flush timer alive when an offer's shorter scope closes", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const coalescer = yield* makeThreadLiveEventCoalescer({ coalesceWindow: "50 millis" });
+        yield* Effect.scoped(coalescer.offer({ kind: "event", event: makeToolActivity(1) }));
+        yield* TestClock.adjust("50 millis");
+        const items = yield* coalescer.stream.pipe(Stream.take(1), Stream.runCollect);
+        expect(
+          items.map((item) => (item.kind === "event" ? item.event.sequence : item.kind)),
+        ).toEqual([1]);
+      }),
+    ),
+  );
+
+  it.effect("keeps an unacknowledged batch charged and clears later events on overflow", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const coalescer = yield* makeThreadLiveEventCoalescer({ maxItems: 3 });
+        const first = makeMessage(1, "é".repeat(1_024));
+        yield* coalescer.offer({ kind: "event", event: first });
+
+        yield* Effect.scoped(
+          Effect.gen(function* () {
+            const pull = yield* Stream.toPull(coalescer.stream);
+            const batch = yield* pull;
+            expect(
+              batch.map((item) => (item.kind === "event" ? item.event.sequence : null)),
+            ).toEqual([1]);
+            yield* coalescer.offer({ kind: "event", event: makeMessage(2) });
+            yield* coalescer.offer({ kind: "event", event: makeToolActivity(3) });
+            expect((yield* coalescer.usage).retainedItems).toBe(3);
+
+            const overflow = yield* coalescer
+              .offer({ kind: "event", event: makeToolActivity(4, { kind: "tool.completed" }) })
+              .pipe(Effect.result);
+            expect(overflow._tag).toBe("Failure");
+            // Do not pull or acknowledge the batch. Cleanup must still finish.
+            yield* coalescer.closed;
+            expect(yield* coalescer.usage).toEqual({
+              retainedItems: 1,
+              retainedSerializedBytes: Buffer.byteLength(encodeEvent(first)),
+            });
+          }),
+        );
+        expect(yield* coalescer.usage).toEqual({ retainedItems: 0, retainedSerializedBytes: 0 });
+      }),
+    ),
+  );
 });
diff --git a/apps/server/src/orchestration/ThreadLiveEventCoalescer.ts b/apps/server/src/orchestration/ThreadLiveEventCoalescer.ts
index 8271f6a550fb..2831746d3e3d 100644
--- a/apps/server/src/orchestration/ThreadLiveEventCoalescer.ts
+++ b/apps/server/src/orchestration/ThreadLiveEventCoalescer.ts
@@ -1,4 +1,8 @@
-import type { OrchestrationEvent, OrchestrationThreadStreamItem } from "@t3tools/contracts";
+import type {
+  OrchestrationEvent,
+  OrchestrationGetSnapshotError,
+  OrchestrationThreadStreamItem,
+} from "@t3tools/contracts";
 import * as Deferred from "effect/Deferred";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
@@ -9,6 +13,7 @@ import * as Semaphore from "effect/Semaphore";
 import * as Stream from "effect/Stream";
 
 import { projectActivityEvent } from "./ActivityPayloadProjection.ts";
+import { makeLiveStreamBudget, type RetainedLiveItem } from "./LiveStreamBudget.ts";
 
 const COALESCE_WINDOW = Duration.millis(50);
 const MAX_PENDING_UPDATES = 512;
@@ -89,17 +94,24 @@ export function coalesceLiveToolUpdatedEvents(
 }
 
 export const makeThreadLiveEventCoalescer = Effect.fn("makeThreadLiveEventCoalescer")(
-  function* (options?: { readonly coalesceWindow?: Duration.Input }) {
-    const output = yield* Queue.unbounded<OrchestrationThreadStreamItem>();
-    const input = yield* Queue.unbounded<{
-      readonly value: ThreadLiveInput;
-      readonly processed?: Deferred.Deferred<void>;
-    }>();
+  function* (options?: {
+    readonly coalesceWindow?: Duration.Input;
+    readonly maxItems?: number;
+    readonly maxSerializedBytes?: number;
+  }) {
+    const coalescerScope = yield* Effect.scope;
+    const budget = yield* makeLiveStreamBudget(options);
+    const cleanupComplete = yield* Deferred.make<void>();
+    const output = yield* Queue.unbounded<
+      RetainedLiveItem<OrchestrationThreadStreamItem>,
+      OrchestrationGetSnapshotError
+    >();
     const mutex = yield* Semaphore.make(1);
     const coalesceWindow = options?.coalesceWindow ?? COALESCE_WINDOW;
-    let pendingUpdates: Array<OrchestrationEvent> = [];
+    let pendingUpdates: Array<RetainedLiveItem<OrchestrationEvent>> = [];
     let windowGeneration = 0;
     let windowFiber: Fiber.Fiber<void, never> | null = null;
+    let closed = false;
 
     const cancelWindow = Effect.fn("ThreadLiveEventCoalescer.cancelWindow")(function* () {
       const fiber = windowFiber;
@@ -110,22 +122,21 @@ export const makeThreadLiveEventCoalescer = Effect.fn("makeThreadLiveEventCoales
       yield* Fiber.interrupt(fiber);
     });
 
-    const flushPending = Effect.fn("ThreadLiveEventCoalescer.flushPending")(function* (
-      boundary?: OrchestrationEvent,
-    ) {
-      const events = boundary ? [...pendingUpdates, boundary] : pendingUpdates;
-      pendingUpdates = [];
-      if (events.length === 0) {
+    const flushPending = Effect.fn("ThreadLiveEventCoalescer.flushPending")(function* () {
+      if (pendingUpdates.length === 0) {
         return;
       }
-      yield* Queue.offerAll(
-        output,
-        coalesceLiveToolUpdatedEvents(events).map((event) => ({
+      const items = yield* budget.replace(
+        pendingUpdates,
+        coalesceLiveToolUpdatedEvents(pendingUpdates.map((item) => item.value)).map((event) => ({
           kind: "event" as const,
-          event: projectActivityEvent(event),
+          event,
         })),
+        (item) => item.event,
       );
-    });
+      pendingUpdates = [];
+      yield* Queue.offerAll(output, items);
+    }, Effect.uninterruptible);
 
     const flushWindow = (generation: number) =>
       Effect.sleep(coalesceWindow).pipe(
@@ -141,67 +152,90 @@ export const makeThreadLiveEventCoalescer = Effect.fn("makeThreadLiveEventCoales
             }
           }),
         ),
+        Effect.catchTags({ OrchestrationGetSnapshotError: () => Effect.void }),
       );
 
-    const process = Effect.fn("ThreadLiveEventCoalescer.process")(function* (
-      input: ThreadLiveInput,
+    // Keep each source batch together so a synchronization marker cannot pass
+    // events already pulled from PubSub but still being coalesced.
+    const offerAll = Effect.fn("ThreadLiveEventCoalescer.offerAll")(function* (
+      inputs: ReadonlyArray<ThreadLiveInput>,
     ) {
       yield* mutex.withPermits(1)(
-        Effect.gen(function* () {
-          if (input.kind === "event" && isToolUpdated(input.event)) {
-            pendingUpdates.push(input.event);
-            if (pendingUpdates.length === 1) {
-              const generation = ++windowGeneration;
-              windowFiber = yield* Effect.forkScoped(flushWindow(generation));
-            }
-            if (pendingUpdates.length >= MAX_PENDING_UPDATES) {
+        Effect.forEach(
+          inputs,
+          (input) =>
+            Effect.gen(function* () {
+              yield* budget.check;
+              if (input.kind === "event") {
+                // Retain only the client payload, not full persisted tool output.
+                yield* budget.retain(projectActivityEvent(input.event)).pipe(
+                  Effect.tap((item) => Effect.sync(() => pendingUpdates.push(item))),
+                  Effect.uninterruptible,
+                );
+              }
+              if (input.kind === "event" && isToolUpdated(input.event)) {
+                if (pendingUpdates.length === 1) {
+                  const generation = ++windowGeneration;
+                  windowFiber = yield* Effect.forkIn(flushWindow(generation), coalescerScope);
+                }
+                if (pendingUpdates.length >= MAX_PENDING_UPDATES) {
+                  yield* cancelWindow();
+                  windowGeneration += 1;
+                  yield* flushPending();
+                }
+                return;
+              }
+
               yield* cancelWindow();
               windowGeneration += 1;
+              // A non-update event closes the run immediately. The coalescer keeps
+              // that boundary after the final update from the run.
               yield* flushPending();
-            }
+              if (input.kind === "synchronized") {
+                yield* budget.retain({ kind: "synchronized" as const }).pipe(
+                  Effect.flatMap((marker) => Queue.offer(output, marker)),
+                  Effect.uninterruptible,
+                );
+              }
+            }),
+          { discard: true },
+        ),
+      );
+    });
+
+    const close = (error?: OrchestrationGetSnapshotError) =>
+      mutex.withPermits(1)(
+        Effect.gen(function* () {
+          if (closed) {
             return;
           }
-
-          yield* cancelWindow();
+          closed = true;
           windowGeneration += 1;
-          // A non-update event closes the run immediately. The coalescer keeps
-          // that boundary after the final update from the run.
-          if (input.kind === "event") {
-            yield* flushPending(input.event);
-          } else {
-            yield* flushPending();
-            yield* Queue.offer(output, { kind: "synchronized" });
+          yield* cancelWindow();
+          budget.release(pendingUpdates);
+          pendingUpdates = [];
+          budget.release(yield* Queue.clear(output).pipe(Effect.orDie));
+          if (error) {
+            yield* Queue.fail(output, error);
           }
+          yield* Queue.shutdown(output);
+          yield* Deferred.succeed(cleanupComplete, undefined);
         }),
       );
-    });
 
-    yield* Stream.fromQueue(input).pipe(
-      Stream.runForEach(({ value, processed }) =>
-        process(value).pipe(
-          Effect.andThen(processed ? Deferred.succeed(processed, undefined) : Effect.void),
-        ),
-      ),
+    yield* Effect.addFinalizer(() => close());
+    yield* budget.failed.pipe(
+      Effect.catchTags({ OrchestrationGetSnapshotError: close }),
       Effect.forkScoped,
     );
 
-    const offer = (value: ThreadLiveInput) => Queue.offer(input, { value }).pipe(Effect.asVoid);
-
-    // Synchronization callers wait for their marker to pass through the same
-    // ordered input queue before draining output produced ahead of it.
-    const offerAndWait = Effect.fn("ThreadLiveEventCoalescer.offerAndWait")(function* (
-      value: ThreadLiveInput,
-    ) {
-      const processed = yield* Deferred.make<void>();
-      yield* Queue.offer(input, { value, processed });
-      yield* Deferred.await(processed);
-    });
-
     return {
-      offer,
-      offerAndWait,
-      stream: Stream.fromQueue(output),
-      takeAll: Queue.takeAll(output),
+      offer: (input: ThreadLiveInput) => offerAll([input]),
+      offerAll,
+      stream: budget.deliver(Stream.fromQueue(output)),
+      failed: budget.failed,
+      closed: Deferred.await(cleanupComplete),
+      usage: budget.usage,
     } as const;
   },
 );
diff --git a/apps/server/src/orchestration/ThreadSettlementPolicy.test.ts b/apps/server/src/orchestration/ThreadSettlementPolicy.test.ts
index a70fb9f68176..05fb16203e0b 100644
--- a/apps/server/src/orchestration/ThreadSettlementPolicy.test.ts
+++ b/apps/server/src/orchestration/ThreadSettlementPolicy.test.ts
@@ -95,8 +95,8 @@ describe("resolveAutoSettlementAt", () => {
     expect(decide(makeThread({ latestUserMessageAt: "2026-08-25T12:00:00.000Z" }))).toBe(false);
   });
 
-  it("keeps open pull requests active", () => {
-    expect(decide(makeThread(), { state: "open", updatedAt: NOW })).toBe(false);
+  it("settles inactive threads with open pull requests", () => {
+    expect(decide(makeThread(), { state: "open", updatedAt: NOW })).toBe(true);
   });
 
   it("settles closed requests and honors the merge setting", () => {
diff --git a/apps/server/src/orchestration/ThreadSettlementPolicy.ts b/apps/server/src/orchestration/ThreadSettlementPolicy.ts
index 5270c30eebe2..eac5a960a482 100644
--- a/apps/server/src/orchestration/ThreadSettlementPolicy.ts
+++ b/apps/server/src/orchestration/ThreadSettlementPolicy.ts
@@ -81,7 +81,6 @@ export function resolveAutoSettlementAt(input: {
     if (pullRequestSettles(thread, pullRequest, input.autoSettleOnMerge)) {
       return activityAt ?? thread.createdAt;
     }
-    if (pullRequest.state === "open") return null;
   }
   if (input.autoSettleAfterDays === null || activityAt === null) return null;
   return Date.parse(activityAt) < Date.parse(input.now) - input.autoSettleAfterDays * DAY_MS
diff --git a/apps/server/src/orchestration/ThreadSettlementReactor.test.ts b/apps/server/src/orchestration/ThreadSettlementReactor.test.ts
index c7d795175262..d3b24d5f77b1 100644
--- a/apps/server/src/orchestration/ThreadSettlementReactor.test.ts
+++ b/apps/server/src/orchestration/ThreadSettlementReactor.test.ts
@@ -408,6 +408,7 @@ describe("ThreadSettlementReactor", () => {
         const fixture = yield* makeHarness({
           snapshot: makeSnapshot([
             makeThread("merged-in-app", {
+              latestUserMessageAt: "2026-08-27T00:00:00.000Z",
               linkedPullRequest: {
                 projectId: PROJECT_ID,
                 repository: "owner/repository",
@@ -415,7 +416,10 @@ describe("ThreadSettlementReactor", () => {
                 url: "https://example.test/owner/repository/pull/42",
               },
             }),
-            makeThread("slow-periodic-lookup", { branch: "another-feature" }),
+            makeThread("slow-periodic-lookup", {
+              branch: "another-feature",
+              latestUserMessageAt: "2026-08-27T00:00:00.000Z",
+            }),
           ]),
           branchPullRequest: () =>
             Ref.updateAndGet(branchLookupCount, (count) => count + 1).pipe(
@@ -460,7 +464,12 @@ describe("ThreadSettlementReactor", () => {
           const state = yield* Ref.make<"open" | "merged">("open");
           const mergedThreadSettled = yield* Deferred.make<void>();
           const fixture = yield* makeHarness({
-            snapshot: makeSnapshot([makeThread("branch-thread", { branch: "saved-feature" })]),
+            snapshot: makeSnapshot([
+              makeThread("branch-thread", {
+                branch: "saved-feature",
+                latestUserMessageAt: "2026-08-27T00:00:00.000Z",
+              }),
+            ]),
             branchPullRequest: () =>
               Ref.get(state).pipe(
                 Effect.map((pullRequestState) => ({ state: pullRequestState, updatedAt: NOW })),
@@ -500,6 +509,7 @@ describe("ThreadSettlementReactor", () => {
         const fixture = yield* makeHarness({
           snapshot: makeSnapshot([
             makeThread("merged-in-app", {
+              latestUserMessageAt: "2026-08-27T00:00:00.000Z",
               linkedPullRequest: {
                 projectId: PROJECT_ID,
                 repository: "owner/repository",
@@ -508,6 +518,7 @@ describe("ThreadSettlementReactor", () => {
               },
             }),
             makeThread("unrelated-linked", {
+              latestUserMessageAt: "2026-08-27T00:00:00.000Z",
               linkedPullRequest: {
                 projectId: PROJECT_ID,
                 repository: "owner/repository",
@@ -683,7 +694,10 @@ describe("ThreadSettlementReactor", () => {
         const fixture = yield* makeHarness({
           snapshot: makeSnapshot(
             [
-              makeThread("missing-own-project", { linkedPullRequest }),
+              makeThread("missing-own-project", {
+                latestUserMessageAt: "2026-08-27T00:00:00.000Z",
+                linkedPullRequest,
+              }),
               makeThread("missing-branch-project", { branch: "saved-feature" }),
             ],
             [makeProject(LINKED_PROJECT_ID, "/workspace/linked")],
diff --git a/apps/server/src/orchestration/commandInvariants.test.ts b/apps/server/src/orchestration/commandInvariants.test.ts
index 9aaeba943423..93777c67d3e1 100644
--- a/apps/server/src/orchestration/commandInvariants.test.ts
+++ b/apps/server/src/orchestration/commandInvariants.test.ts
@@ -11,12 +11,7 @@ import {
 } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 
-import {
-  findThreadById,
-  listThreadsByProjectId,
-  requireThread,
-  requireThreadAbsent,
-} from "./commandInvariants.ts";
+import { listThreadsByProjectId, requireThread, requireThreadAbsent } from "./commandInvariants.ts";
 
 const now = "2026-01-01T00:00:00.000Z";
 
@@ -121,9 +116,7 @@ const messageSendCommand: OrchestrationCommand = {
 };
 
 describe("commandInvariants", () => {
-  it("finds threads by id and project", () => {
-    expect(findThreadById(readModel, ThreadId.make("thread-1"))?.projectId).toBe("project-a");
-    expect(findThreadById(readModel, ThreadId.make("missing"))).toBeUndefined();
+  it("lists threads by project", () => {
     expect(
       listThreadsByProjectId(readModel, ProjectId.make("project-b")).map((thread) => thread.id),
     ).toEqual([ThreadId.make("thread-2")]);
diff --git a/apps/server/src/orchestration/commandInvariants.ts b/apps/server/src/orchestration/commandInvariants.ts
index beaad93d5eef..110a499d37c9 100644
--- a/apps/server/src/orchestration/commandInvariants.ts
+++ b/apps/server/src/orchestration/commandInvariants.ts
@@ -18,7 +18,7 @@ function invariantError(commandType: string, detail: string): OrchestrationComma
   });
 }
 
-export function findThreadById(
+function findThreadById(
   readModel: OrchestrationReadModel,
   threadId: ThreadId,
 ): OrchestrationThread | undefined {
diff --git a/apps/server/src/orchestration/decider.import.test.ts b/apps/server/src/orchestration/decider.import.test.ts
new file mode 100644
index 000000000000..c809c733800a
--- /dev/null
+++ b/apps/server/src/orchestration/decider.import.test.ts
@@ -0,0 +1,509 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { expect, it } from "@effect/vitest";
+import {
+  CommandId,
+  EventId,
+  MessageId,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as TestClock from "effect/testing/TestClock";
+
+import { decideOrchestrationCommand } from "./decider.ts";
+import { createEmptyReadModel, projectEvent } from "./projector.ts";
+
+it.layer(NodeServices.layer)("thread history import", (it) => {
+  it.effect("marks imported thread creation without changing live creation", () =>
+    Effect.gen(function* () {
+      const createdAt = "2026-08-24T10:00:00.000Z";
+      const projectId = ProjectId.make("project-1");
+      const readModel = yield* projectEvent(createEmptyReadModel(createdAt), {
+        sequence: 1,
+        eventId: EventId.make("event-project-created"),
+        aggregateKind: "project",
+        aggregateId: projectId,
+        type: "project.created",
+        occurredAt: createdAt,
+        commandId: CommandId.make("command-project-created"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-project-created"),
+        metadata: {},
+        payload: {
+          projectId,
+          title: "Project",
+          workspaceRoot: "/tmp/project",
+          defaultModelSelection: null,
+          scripts: [],
+          createdAt,
+          updatedAt: createdAt,
+        },
+      });
+      const makeCreateCommand = (threadId: ThreadId) => ({
+        type: "thread.create" as const,
+        commandId: CommandId.make(`command-create-${threadId}`),
+        threadId,
+        projectId,
+        title: "Imported thread",
+        modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
+        runtimeMode: "full-access" as const,
+        interactionMode: "default" as const,
+        branch: null,
+        worktreePath: null,
+        createdAt,
+      });
+
+      const imported = yield* decideOrchestrationCommand({
+        command: {
+          ...makeCreateCommand(ThreadId.make("import:codex:session-1")),
+          historyImport: true,
+        },
+        readModel,
+      });
+      const live = yield* decideOrchestrationCommand({
+        command: makeCreateCommand(ThreadId.make("live-thread")),
+        readModel,
+      });
+
+      expect(imported).toMatchObject({
+        type: "thread.created",
+        metadata: { historyImport: true },
+      });
+      expect(live).toMatchObject({ type: "thread.created" });
+      expect(live).not.toMatchObject({ metadata: { historyImport: true } });
+    }),
+  );
+
+  it.effect("settles imported messages at the latest absolute timestamp", () =>
+    Effect.gen(function* () {
+      const createdAt = "2026-08-24T10:30:00.000+02:00";
+      const threadId = ThreadId.make("import:codex:session-1");
+      const readModel = yield* projectEvent(createEmptyReadModel(createdAt), {
+        sequence: 1,
+        eventId: EventId.make("event-thread-created"),
+        aggregateKind: "thread",
+        aggregateId: threadId,
+        type: "thread.created",
+        occurredAt: createdAt,
+        commandId: CommandId.make("command-thread-created"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-thread-created"),
+        metadata: {},
+        payload: {
+          threadId,
+          projectId: ProjectId.make("project-1"),
+          title: "Imported thread",
+          modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: null,
+          worktreePath: null,
+          createdAt,
+          updatedAt: createdAt,
+        },
+      });
+
+      const events = yield* decideOrchestrationCommand({
+        command: {
+          type: "thread.history.import",
+          commandId: CommandId.make("command-import-history"),
+          threadId,
+          messages: [
+            {
+              messageId: MessageId.make(`${threadId}:000000`),
+              role: "user",
+              text: "Fix the bug",
+              createdAt,
+            },
+            {
+              messageId: MessageId.make(`${threadId}:000001`),
+              role: "assistant",
+              text: "Fixed",
+              createdAt: "2026-08-24T09:00:00.000Z",
+            },
+          ],
+        },
+        readModel,
+      });
+
+      expect(events).toMatchObject([
+        {
+          type: "thread.message-sent",
+          metadata: { historyImport: true },
+          payload: { role: "user", text: "Fix the bug", turnId: null, streaming: false },
+        },
+        {
+          type: "thread.message-sent",
+          metadata: { historyImport: true },
+          payload: { role: "assistant", text: "Fixed", turnId: null, streaming: false },
+        },
+        {
+          type: "thread.settled",
+          metadata: { historyImport: true },
+          occurredAt: "2026-08-24T09:00:00.000Z",
+          payload: {
+            settledAt: "2026-08-24T09:00:00.000Z",
+            updatedAt: "2026-08-24T09:00:00.000Z",
+          },
+        },
+      ]);
+
+      let projected = readModel;
+      const plannedEvents = Array.isArray(events) ? events : [events];
+      for (const [index, event] of plannedEvents.entries()) {
+        projected = yield* projectEvent(projected, { ...event, sequence: index + 2 });
+      }
+      projected = yield* projectEvent(projected, {
+        sequence: 5,
+        eventId: EventId.make("event-import-reverted"),
+        aggregateKind: "thread",
+        aggregateId: threadId,
+        type: "thread.reverted",
+        occurredAt: "2026-08-24T10:02:00.000Z",
+        commandId: CommandId.make("command-import-reverted"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-import-reverted"),
+        metadata: {},
+        payload: { threadId, turnCount: 0 },
+      });
+      expect(projected.threads[0]?.messages.map((message) => message.text)).toEqual([
+        "Fix the bug",
+        "Fixed",
+      ]);
+    }),
+  );
+
+  it.effect("allows a thread with a newly imported user message to be settled", () =>
+    Effect.gen(function* () {
+      const createdAt = "2026-08-24T10:00:00.000Z";
+      yield* TestClock.setTime(Date.parse("2026-08-24T10:00:30.000Z"));
+      const threadId = ThreadId.make("import:codex:session-1");
+      const withThread = yield* projectEvent(createEmptyReadModel(createdAt), {
+        sequence: 1,
+        eventId: EventId.make("event-import-thread-created"),
+        aggregateKind: "thread",
+        aggregateId: threadId,
+        type: "thread.created",
+        occurredAt: createdAt,
+        commandId: CommandId.make("command-import-thread-created"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-import-thread-created"),
+        metadata: {},
+        payload: {
+          threadId,
+          projectId: ProjectId.make("project-1"),
+          title: "Imported thread",
+          modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: null,
+          worktreePath: null,
+          createdAt,
+          updatedAt: createdAt,
+        },
+      });
+      const readModel = yield* projectEvent(withThread, {
+        sequence: 2,
+        eventId: EventId.make("event-import-user-message"),
+        aggregateKind: "thread",
+        aggregateId: threadId,
+        type: "thread.message-sent",
+        occurredAt: createdAt,
+        commandId: CommandId.make("command-import-user-message"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-import-user-message"),
+        metadata: { historyImport: true },
+        payload: {
+          threadId,
+          messageId: MessageId.make("import:codex:session-1:0"),
+          role: "user",
+          text: "Existing prompt",
+          turnId: null,
+          streaming: false,
+          createdAt,
+          updatedAt: createdAt,
+        },
+      });
+
+      const result = yield* decideOrchestrationCommand({
+        command: {
+          type: "thread.settle",
+          commandId: CommandId.make("command-settle-imported-thread"),
+          threadId,
+        },
+        readModel,
+      });
+
+      expect(result).toMatchObject({ type: "thread.settled" });
+    }),
+  );
+
+  it.effect("rejects history import after a client message reaches the thread", () =>
+    Effect.gen(function* () {
+      const createdAt = "2026-08-24T10:00:00.000Z";
+      const liveMessageAt = "2026-08-24T10:02:00.000Z";
+      const threadId = ThreadId.make("import:codex:client-race");
+      const withThread = yield* projectEvent(createEmptyReadModel(createdAt), {
+        sequence: 1,
+        eventId: EventId.make("event-client-race-thread-created"),
+        aggregateKind: "thread",
+        aggregateId: threadId,
+        type: "thread.created",
+        occurredAt: createdAt,
+        commandId: CommandId.make("command-client-race-thread-created"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-client-race-thread-created"),
+        metadata: {},
+        payload: {
+          threadId,
+          projectId: ProjectId.make("project-1"),
+          title: "Imported thread",
+          modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: null,
+          worktreePath: null,
+          createdAt,
+          updatedAt: createdAt,
+        },
+      });
+      const readModel = yield* projectEvent(withThread, {
+        sequence: 2,
+        eventId: EventId.make("event-client-race-message"),
+        aggregateKind: "thread",
+        aggregateId: threadId,
+        type: "thread.message-sent",
+        occurredAt: liveMessageAt,
+        commandId: CommandId.make("command-client-race-message"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-client-race-message"),
+        metadata: {},
+        payload: {
+          threadId,
+          messageId: MessageId.make("client-race-message"),
+          role: "user",
+          text: "Start live work",
+          turnId: null,
+          streaming: false,
+          createdAt: liveMessageAt,
+          updatedAt: liveMessageAt,
+        },
+      });
+
+      const error = yield* Effect.flip(
+        decideOrchestrationCommand({
+          command: {
+            type: "thread.history.import",
+            commandId: CommandId.make("command-client-race-import"),
+            threadId,
+            messages: [
+              {
+                messageId: MessageId.make(`${threadId}:000000`),
+                role: "user",
+                text: "Old work",
+                createdAt,
+              },
+            ],
+          },
+          readModel,
+        }),
+      );
+
+      expect(error._tag).toBe("OrchestrationCommandInvariantError");
+      expect(error.message).toContain("must be active and empty");
+      expect(readModel.threads[0]?.updatedAt).toBe(liveMessageAt);
+    }),
+  );
+
+  for (const requestKind of ["approval.requested", "user-input.requested"] as const) {
+    it.effect(`rejects history import with an open ${requestKind} activity`, () =>
+      Effect.gen(function* () {
+        const createdAt = "2026-08-24T10:00:00.000Z";
+        const threadId = ThreadId.make(`import:codex:${requestKind}`);
+        const withThread = yield* projectEvent(createEmptyReadModel(createdAt), {
+          sequence: 1,
+          eventId: EventId.make(`event-${requestKind}-thread-created`),
+          aggregateKind: "thread",
+          aggregateId: threadId,
+          type: "thread.created",
+          occurredAt: createdAt,
+          commandId: CommandId.make(`command-${requestKind}-thread-created`),
+          causationEventId: null,
+          correlationId: CommandId.make(`command-${requestKind}-thread-created`),
+          metadata: {},
+          payload: {
+            threadId,
+            projectId: ProjectId.make("project-1"),
+            title: "Imported thread",
+            modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
+            runtimeMode: "full-access",
+            interactionMode: "default",
+            branch: null,
+            worktreePath: null,
+            createdAt,
+            updatedAt: createdAt,
+          },
+        });
+        const readModel = yield* projectEvent(withThread, {
+          sequence: 2,
+          eventId: EventId.make(`event-${requestKind}`),
+          aggregateKind: "thread",
+          aggregateId: threadId,
+          type: "thread.activity-appended",
+          occurredAt: createdAt,
+          commandId: CommandId.make(`command-${requestKind}`),
+          causationEventId: null,
+          correlationId: CommandId.make(`command-${requestKind}`),
+          metadata: {},
+          payload: {
+            threadId,
+            activity: {
+              id: EventId.make(`activity-${requestKind}`),
+              tone: "approval",
+              kind: requestKind,
+              summary: "Pending request",
+              payload: { requestId: "request-1" },
+              turnId: null,
+              createdAt,
+            },
+          },
+        });
+
+        const error = yield* Effect.flip(
+          decideOrchestrationCommand({
+            command: {
+              type: "thread.history.import",
+              commandId: CommandId.make(`command-import-${requestKind}`),
+              threadId,
+              messages: [
+                {
+                  messageId: MessageId.make(`${threadId}:000000`),
+                  role: "user",
+                  text: "Old work",
+                  createdAt,
+                },
+              ],
+            },
+            readModel,
+          }),
+        );
+
+        expect(error._tag).toBe("OrchestrationCommandInvariantError");
+        expect(error.message).toContain("must be active and empty");
+      }),
+    );
+  }
+
+  it.effect("rejects a live user message in the imported-session namespace", () =>
+    Effect.gen(function* () {
+      const createdAt = "2026-08-24T10:00:00.000Z";
+      const threadId = ThreadId.make("thread-live-message");
+      const readModel = yield* projectEvent(createEmptyReadModel(createdAt), {
+        sequence: 1,
+        eventId: EventId.make("event-live-thread-created"),
+        aggregateKind: "thread",
+        aggregateId: threadId,
+        type: "thread.created",
+        occurredAt: createdAt,
+        commandId: CommandId.make("command-live-thread-created"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-live-thread-created"),
+        metadata: {},
+        payload: {
+          threadId,
+          projectId: ProjectId.make("project-1"),
+          title: "Live thread",
+          modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: null,
+          worktreePath: null,
+          createdAt,
+          updatedAt: createdAt,
+        },
+      });
+
+      const error = yield* Effect.flip(
+        decideOrchestrationCommand({
+          command: {
+            type: "thread.turn.start",
+            commandId: CommandId.make("command-live-import-id"),
+            threadId,
+            message: {
+              messageId: MessageId.make("import:forged-live-message"),
+              role: "user",
+              text: "Live work",
+              attachments: [],
+            },
+            runtimeMode: "full-access",
+            interactionMode: "default",
+            createdAt,
+          },
+          readModel,
+        }),
+      );
+
+      expect(error._tag).toBe("OrchestrationCommandInvariantError");
+      expect(error.message).toContain("reserved imported-session namespace");
+    }),
+  );
+
+  it.effect("rejects live assistant messages in the imported-session namespace", () =>
+    Effect.gen(function* () {
+      const createdAt = "2026-08-24T10:00:00.000Z";
+      const threadId = ThreadId.make("thread-live-assistant-message");
+      const readModel = yield* projectEvent(createEmptyReadModel(createdAt), {
+        sequence: 1,
+        eventId: EventId.make("event-live-assistant-thread-created"),
+        aggregateKind: "thread",
+        aggregateId: threadId,
+        type: "thread.created",
+        occurredAt: createdAt,
+        commandId: CommandId.make("command-live-assistant-thread-created"),
+        causationEventId: null,
+        correlationId: CommandId.make("command-live-assistant-thread-created"),
+        metadata: {},
+        payload: {
+          threadId,
+          projectId: ProjectId.make("project-1"),
+          title: "Live thread",
+          modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: null,
+          worktreePath: null,
+          createdAt,
+          updatedAt: createdAt,
+        },
+      });
+
+      for (const commandType of [
+        "thread.message.assistant.delta",
+        "thread.message.assistant.complete",
+      ] as const) {
+        const command =
+          commandType === "thread.message.assistant.delta"
+            ? {
+                type: commandType,
+                commandId: CommandId.make("command-live-assistant-delta-import-id"),
+                threadId,
+                messageId: MessageId.make("import:forged-live-assistant-message"),
+                delta: "Live work",
+                createdAt,
+              }
+            : {
+                type: commandType,
+                commandId: CommandId.make("command-live-assistant-complete-import-id"),
+                threadId,
+                messageId: MessageId.make("import:forged-live-assistant-message"),
+                createdAt,
+              };
+        const error = yield* Effect.flip(decideOrchestrationCommand({ command, readModel }));
+
+        expect(error._tag).toBe("OrchestrationCommandInvariantError");
+        expect(error.message).toContain("reserved imported-session namespace");
+      }
+    }),
+  );
+});
diff --git a/apps/server/src/orchestration/decider.ts b/apps/server/src/orchestration/decider.ts
index b336053ac9e1..1fd9feba7c44 100644
--- a/apps/server/src/orchestration/decider.ts
+++ b/apps/server/src/orchestration/decider.ts
@@ -2,12 +2,14 @@ import {
   EventId,
   MessageId,
   UserInputRequestedPayload,
+  isImportedAgentSessionMessageId,
   type OrchestrationCommand,
   type OrchestrationEvent,
   type OrchestrationReadModel,
   type OrchestrationThread,
   type OrchestrationThreadActivity,
 } from "@t3tools/contracts";
+import { compareDateTimeStrings } from "@t3tools/shared/dateTime";
 import * as DateTime from "effect/DateTime";
 import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
@@ -98,7 +100,7 @@ function hasQueuedTurnStartForThread(
   let latestUserMessageAt: string | null = null;
   let latestUserMessageAtMs = Number.NEGATIVE_INFINITY;
   for (const message of thread.messages) {
-    if (message.role !== "user") continue;
+    if (message.role !== "user" || isImportedAgentSessionMessageId(message.id)) continue;
     const messageAtMs = Date.parse(message.createdAt);
     latestUserMessageAtMs = Math.max(latestUserMessageAtMs, messageAtMs);
     if (messageAtMs === latestUserMessageAtMs) {
@@ -347,6 +349,7 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
           aggregateId: command.threadId,
           occurredAt: command.createdAt,
           commandId: command.commandId,
+          ...(command.historyImport === true ? { metadata: { historyImport: true } } : {}),
         })),
         type: "thread.created",
         payload: {
@@ -905,6 +908,12 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
     }
 
     case "thread.turn.start": {
+      if (isImportedAgentSessionMessageId(command.message.messageId)) {
+        return yield* new OrchestrationCommandInvariantError({
+          commandType: command.type,
+          detail: `Message id '${command.message.messageId}' uses the reserved imported-session namespace.`,
+        });
+      }
       const targetThread = yield* requireThread({
         readModel,
         command,
@@ -1272,6 +1281,12 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
     }
 
     case "thread.message.assistant.delta": {
+      if (isImportedAgentSessionMessageId(command.messageId)) {
+        return yield* new OrchestrationCommandInvariantError({
+          commandType: command.type,
+          detail: `Message id '${command.messageId}' uses the reserved imported-session namespace.`,
+        });
+      }
       yield* requireThread({
         readModel,
         command,
@@ -1299,6 +1314,12 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
     }
 
     case "thread.message.assistant.complete": {
+      if (isImportedAgentSessionMessageId(command.messageId)) {
+        return yield* new OrchestrationCommandInvariantError({
+          commandType: command.type,
+          detail: `Message id '${command.messageId}' uses the reserved imported-session namespace.`,
+        });
+      }
       yield* requireThread({
         readModel,
         command,
@@ -1325,6 +1346,79 @@ export const decideOrchestrationCommand = Effect.fn("decideOrchestrationCommand"
       };
     }
 
+    case "thread.history.import": {
+      const thread = yield* requireThread({
+        readModel,
+        command,
+        threadId: command.threadId,
+      });
+      if (
+        thread.deletedAt !== null ||
+        thread.archivedAt !== null ||
+        thread.messages.length > 0 ||
+        thread.latestTurn !== null ||
+        thread.session !== null ||
+        hasOpenBlockingRequest(thread)
+      ) {
+        return yield* new OrchestrationCommandInvariantError({
+          commandType: command.type,
+          detail: `Thread '${command.threadId}' must be active and empty before history can be imported.`,
+        });
+      }
+      const firstMessage = command.messages[0];
+      if (firstMessage === undefined) {
+        return yield* new OrchestrationCommandInvariantError({
+          commandType: command.type,
+          detail: "Thread history imports require at least one message.",
+        });
+      }
+
+      const events: Array<PlannedOrchestrationEvent> = [];
+      for (const message of command.messages) {
+        events.push({
+          ...(yield* withEventBase({
+            aggregateKind: "thread",
+            aggregateId: command.threadId,
+            occurredAt: message.createdAt,
+            commandId: command.commandId,
+            metadata: { historyImport: true },
+          })),
+          type: "thread.message-sent",
+          payload: {
+            threadId: command.threadId,
+            messageId: message.messageId,
+            role: message.role,
+            text: message.text,
+            turnId: null,
+            streaming: false,
+            createdAt: message.createdAt,
+            updatedAt: message.createdAt,
+          },
+        });
+      }
+      const settledAt = command.messages.reduce(
+        (latest, message) =>
+          compareDateTimeStrings(message.createdAt, latest) > 0 ? message.createdAt : latest,
+        firstMessage.createdAt,
+      );
+      events.push({
+        ...(yield* withEventBase({
+          aggregateKind: "thread",
+          aggregateId: command.threadId,
+          occurredAt: settledAt,
+          commandId: command.commandId,
+          metadata: { historyImport: true },
+        })),
+        type: "thread.settled",
+        payload: {
+          threadId: command.threadId,
+          settledAt,
+          updatedAt: settledAt,
+        },
+      });
+      return events;
+    }
+
     case "thread.proposed-plan.upsert": {
       yield* requireThread({
         readModel,
diff --git a/apps/server/src/orchestration/projector.test.ts b/apps/server/src/orchestration/projector.test.ts
index dad3d07370f9..4b37137936f4 100644
--- a/apps/server/src/orchestration/projector.test.ts
+++ b/apps/server/src/orchestration/projector.test.ts
@@ -7,6 +7,7 @@ import {
   type OrchestrationEvent,
 } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
+import { it as effectIt } from "@effect/vitest";
 import { describe, expect, it } from "vite-plus/test";
 
 import { createEmptyReadModel, projectEvent } from "./projector.ts";
@@ -239,110 +240,234 @@ describe("orchestration projector", () => {
     expect(next.threads).toEqual([]);
   });
 
-  it("tracks latest turn id from session lifecycle events", async () => {
-    const createdAt = "2026-02-23T08:00:00.000Z";
-    const startedAt = "2026-02-23T08:00:05.000Z";
-    const model = createEmptyReadModel(createdAt);
-
-    const afterCreate = await Effect.runPromise(
-      projectEvent(
-        model,
-        makeEvent({
-          sequence: 1,
-          type: "thread.created",
-          aggregateKind: "thread",
-          aggregateId: "thread-1",
-          occurredAt: createdAt,
-          commandId: "cmd-create",
-          payload: {
-            threadId: "thread-1",
-            projectId: "project-1",
-            title: "demo",
-            modelSelection: {
-              provider: ProviderDriverKind.make("codex"),
-              model: "gpt-5.3-codex",
-            },
-            runtimeMode: "full-access",
-            branch: null,
-            worktreePath: null,
-            createdAt,
-            updatedAt: createdAt,
-          },
-        }),
-      ),
-    );
+  effectIt.effect.each([
+    ["ready", "completed"],
+    ["interrupted", "interrupted"],
+  ] as const)(
+    "preserves the turn state after a %s session captures its checkpoint",
+    ([status, state]) =>
+      Effect.gen(function* () {
+        const createdAt = "2026-02-23T08:00:00.000Z";
+        const startedAt = "2026-02-23T08:00:05.000Z";
+        const model = createEmptyReadModel(createdAt);
 
-    const settledAt = "2026-02-23T08:01:00.000Z";
-    const [afterRunning, afterReady] = await Effect.runPromise(
-      Effect.flatMap(
-        projectEvent(
-          afterCreate,
+        const afterCreate = yield* projectEvent(
+          model,
           makeEvent({
-            sequence: 2,
-            type: "thread.session-set",
+            sequence: 1,
+            type: "thread.created",
             aggregateKind: "thread",
             aggregateId: "thread-1",
-            occurredAt: startedAt,
-            commandId: "cmd-running",
+            occurredAt: createdAt,
+            commandId: "cmd-create",
             payload: {
               threadId: "thread-1",
-              session: {
-                threadId: "thread-1",
-                status: "running",
-                providerName: "codex",
-                providerSessionId: "session-1",
-                providerThreadId: "provider-thread-1",
-                runtimeMode: "approval-required",
-                activeTurnId: "turn-1",
-                lastError: null,
-                updatedAt: startedAt,
+              projectId: "project-1",
+              title: "demo",
+              modelSelection: {
+                provider: ProviderDriverKind.make("codex"),
+                model: "gpt-5.3-codex",
               },
+              runtimeMode: "full-access",
+              branch: null,
+              worktreePath: null,
+              createdAt,
+              updatedAt: createdAt,
             },
           }),
-        ),
-        (running) =>
-          Effect.map(
-            projectEvent(
-              running,
-              makeEvent({
-                sequence: 3,
-                type: "thread.session-set",
-                aggregateKind: "thread",
-                aggregateId: "thread-1",
-                occurredAt: settledAt,
-                commandId: "cmd-ready",
-                payload: {
+        );
+
+        const settledAt = "2026-02-23T08:01:00.000Z";
+        const [afterRunning, afterReady] = yield* Effect.flatMap(
+          projectEvent(
+            afterCreate,
+            makeEvent({
+              sequence: 2,
+              type: "thread.session-set",
+              aggregateKind: "thread",
+              aggregateId: "thread-1",
+              occurredAt: startedAt,
+              commandId: "cmd-running",
+              payload: {
+                threadId: "thread-1",
+                session: {
                   threadId: "thread-1",
-                  session: {
+                  status: "running",
+                  providerName: "codex",
+                  providerSessionId: "session-1",
+                  providerThreadId: "provider-thread-1",
+                  runtimeMode: "approval-required",
+                  activeTurnId: "turn-1",
+                  lastError: null,
+                  updatedAt: startedAt,
+                },
+              },
+            }),
+          ),
+          (running) =>
+            Effect.map(
+              projectEvent(
+                running,
+                makeEvent({
+                  sequence: 3,
+                  type: "thread.session-set",
+                  aggregateKind: "thread",
+                  aggregateId: "thread-1",
+                  occurredAt: settledAt,
+                  commandId: "cmd-ready",
+                  payload: {
                     threadId: "thread-1",
-                    status: "ready",
-                    providerName: "codex",
-                    providerSessionId: "session-1",
-                    providerThreadId: "provider-thread-1",
-                    runtimeMode: "approval-required",
-                    activeTurnId: null,
-                    lastError: null,
-                    updatedAt: settledAt,
+                    session: {
+                      threadId: "thread-1",
+                      status,
+                      providerName: "codex",
+                      providerSessionId: "session-1",
+                      providerThreadId: "provider-thread-1",
+                      runtimeMode: "approval-required",
+                      activeTurnId: null,
+                      lastError: null,
+                      updatedAt: settledAt,
+                    },
                   },
-                },
-              }),
+                }),
+              ),
+              (ready) => [running, ready] as const,
             ),
-            (ready) => [running, ready] as const,
-          ),
-      ),
-    );
+        );
 
-    const thread = afterRunning.threads[0];
-    expect(thread?.latestTurn?.turnId).toBe("turn-1");
-    expect(thread?.session?.status).toBe("running");
-
-    // Leaving the "running" session status settles the running turn with the
-    // session timestamp as the turn end.
-    const settledThread = afterReady.threads[0];
-    expect(settledThread?.latestTurn?.turnId).toBe("turn-1");
-    expect(settledThread?.latestTurn?.state).toBe("completed");
-    expect(settledThread?.latestTurn?.completedAt).toBe(settledAt);
-  });
+        const thread = afterRunning.threads[0];
+        expect(thread?.latestTurn?.turnId).toBe("turn-1");
+        expect(thread?.session?.status).toBe("running");
+
+        // Leaving the "running" session status settles the running turn with the
+        // session timestamp as the turn end.
+        const settledThread = afterReady.threads[0];
+        expect(settledThread?.latestTurn?.turnId).toBe("turn-1");
+        expect(settledThread?.latestTurn?.state).toBe(state);
+        expect(settledThread?.latestTurn?.completedAt).toBe(settledAt);
+
+        const captured = yield* projectEvent(
+          afterReady,
+          makeEvent({
+            sequence: 4,
+            type: "thread.turn-diff-completed",
+            aggregateKind: "thread",
+            aggregateId: "thread-1",
+            occurredAt: settledAt,
+            commandId: "cmd-final-checkpoint",
+            payload: {
+              threadId: "thread-1",
+              turnId: "turn-1",
+              checkpointTurnCount: 1,
+              checkpointRef: "refs/t3/checkpoints/thread-1/turn/1",
+              status: "ready",
+              files: [],
+              assistantMessageId: "assistant:turn-1",
+              completedAt: settledAt,
+            },
+          }),
+        );
+        expect(captured.threads[0]?.latestTurn?.state).toBe(state);
+        expect(captured.threads[0]?.checkpoints[0]?.status).toBe("ready");
+      }),
+  );
+
+  effectIt.effect.each([null, "ready", "interrupted", "stopped"] as const)(
+    "replaces a missing checkpoint without inventing interruption for a %s session",
+    (sessionStatus) =>
+      Effect.gen(function* () {
+        const now = "2026-09-04T23:00:00.000Z";
+        const threadId = "thread-placeholder";
+        const event = (sequence: number, type: OrchestrationEvent["type"], payload: unknown) =>
+          makeEvent({
+            sequence,
+            type,
+            payload,
+            aggregateKind: "thread",
+            aggregateId: threadId,
+            occurredAt: now,
+            commandId: `placeholder-${sequence}`,
+          });
+        let model = yield* projectEvent(
+          createEmptyReadModel(now),
+          event(1, "thread.created", {
+            threadId,
+            projectId: "project-1",
+            title: "Placeholder",
+            modelSelection: { instanceId: "codex", model: "test" },
+            runtimeMode: "full-access",
+            interactionMode: "default",
+            branch: null,
+            worktreePath: null,
+            createdAt: now,
+            updatedAt: now,
+          }),
+        );
+        const checkpoint = {
+          threadId,
+          turnId: "turn-placeholder",
+          checkpointTurnCount: 1,
+          checkpointRef: "provider-diff:placeholder",
+          files: [],
+          assistantMessageId: "assistant:placeholder",
+          completedAt: now,
+        };
+        if (sessionStatus === "interrupted" || sessionStatus === "stopped") {
+          model = yield* projectEvent(
+            model,
+            event(2, "thread.session-set", {
+              threadId,
+              session: {
+                threadId,
+                status: "running",
+                providerName: "codex",
+                runtimeMode: "full-access",
+                activeTurnId: "turn-placeholder",
+                lastError: null,
+                updatedAt: now,
+              },
+            }),
+          );
+        }
+        model = yield* projectEvent(
+          model,
+          event(3, "thread.turn-diff-completed", {
+            ...checkpoint,
+            status: "missing",
+          }),
+        );
+        if (sessionStatus !== null) {
+          model = yield* projectEvent(
+            model,
+            event(4, "thread.session-set", {
+              threadId,
+              session: {
+                threadId,
+                status: sessionStatus,
+                providerName: "codex",
+                runtimeMode: "full-access",
+                activeTurnId: null,
+                lastError: null,
+                updatedAt: now,
+              },
+            }),
+          );
+        }
+        model = yield* projectEvent(
+          model,
+          event(5, "thread.turn-diff-completed", {
+            ...checkpoint,
+            status: "ready",
+            checkpointRef: "refs/t3/checkpoints/thread-placeholder/turn/1",
+          }),
+        );
+        expect(model.threads[0]?.latestTurn?.state).toBe(
+          sessionStatus === "interrupted" || sessionStatus === "stopped"
+            ? "interrupted"
+            : "completed",
+        );
+      }),
+  );
 
   it("updates canonical thread runtime mode from thread.runtime-mode-set", async () => {
     const createdAt = "2026-02-23T08:00:00.000Z";
diff --git a/apps/server/src/orchestration/projector.ts b/apps/server/src/orchestration/projector.ts
index 3cea194bbb44..77dbe51b9542 100644
--- a/apps/server/src/orchestration/projector.ts
+++ b/apps/server/src/orchestration/projector.ts
@@ -1,10 +1,12 @@
 import type { OrchestrationEvent, OrchestrationReadModel, ThreadId } from "@t3tools/contracts";
 import {
+  isImportedAgentSessionMessageId,
   OrchestrationCheckpointSummary,
   OrchestrationMessage,
   OrchestrationSession,
   OrchestrationThread,
 } from "@t3tools/contracts";
+import { compareDateTimeStrings } from "@t3tools/shared/dateTime";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import * as Predicate from "effect/Predicate";
@@ -64,7 +66,7 @@ function retainThreadActivities(activities: OrchestrationThread["activities"]) {
 
 function checkpointStatusToLatestTurnState(status: "ready" | "missing" | "error") {
   if (status === "error") return "error" as const;
-  if (status === "missing") return "interrupted" as const;
+  // Match SQL and client projections: a missing git ref is not an interruption.
   return "completed" as const;
 }
 
@@ -117,7 +119,7 @@ function retainThreadMessagesAfterRevert(
 ): ReadonlyArray<OrchestrationMessage> {
   const retainedMessageIds = new Set<string>();
   for (const message of messages) {
-    if (message.role === "system") {
+    if (message.role === "system" || isImportedAgentSessionMessageId(message.id)) {
       retainedMessageIds.add(message.id);
       continue;
     }
@@ -127,7 +129,10 @@ function retainThreadMessagesAfterRevert(
   }
 
   const retainedUserCount = messages.filter(
-    (message) => message.role === "user" && retainedMessageIds.has(message.id),
+    (message) =>
+      message.role === "user" &&
+      !isImportedAgentSessionMessageId(message.id) &&
+      retainedMessageIds.has(message.id),
   ).length;
   const missingUserCount = Math.max(0, turnCount - retainedUserCount);
   if (missingUserCount > 0) {
@@ -140,7 +145,8 @@ function retainThreadMessagesAfterRevert(
       )
       .toSorted(
         (left, right) =>
-          left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
+          compareDateTimeStrings(left.createdAt, right.createdAt) ||
+          left.id.localeCompare(right.id),
       )
       .slice(0, missingUserCount);
     for (const message of fallbackUserMessages) {
@@ -149,7 +155,10 @@ function retainThreadMessagesAfterRevert(
   }
 
   const retainedAssistantCount = messages.filter(
-    (message) => message.role === "assistant" && retainedMessageIds.has(message.id),
+    (message) =>
+      message.role === "assistant" &&
+      !isImportedAgentSessionMessageId(message.id) &&
+      retainedMessageIds.has(message.id),
   ).length;
   const missingAssistantCount = Math.max(0, turnCount - retainedAssistantCount);
   if (missingAssistantCount > 0) {
@@ -162,7 +171,8 @@ function retainThreadMessagesAfterRevert(
       )
       .toSorted(
         (left, right) =>
-          left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
+          compareDateTimeStrings(left.createdAt, right.createdAt) ||
+          left.id.localeCompare(right.id),
       )
       .slice(0, missingAssistantCount);
     for (const message of fallbackAssistantMessages) {
@@ -746,7 +756,11 @@ export function projectEvent(
               ? thread.latestTurn
               : {
                   turnId: payload.turnId,
-                  state: checkpointStatusToLatestTurnState(payload.status),
+                  state:
+                    thread.latestTurn?.turnId === payload.turnId &&
+                    thread.latestTurn.state === "interrupted"
+                      ? "interrupted"
+                      : checkpointStatusToLatestTurnState(payload.status),
                   requestedAt:
                     thread.latestTurn?.turnId === payload.turnId
                       ? thread.latestTurn.requestedAt
diff --git a/apps/server/src/orchestration/workflowScriptQuery.test.ts b/apps/server/src/orchestration/workflowScriptQuery.test.ts
index 47fe888de70c..311b89427697 100644
--- a/apps/server/src/orchestration/workflowScriptQuery.test.ts
+++ b/apps/server/src/orchestration/workflowScriptQuery.test.ts
@@ -5,6 +5,7 @@ import * as NodePath from "node:path";
 import { it as effectIt } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import { afterAll, assert, describe } from "vite-plus/test";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 import { readWorkflowScript } from "./workflowScriptQuery.ts";
 
 const root = NodePath.join(NodeOS.homedir(), ".claude", "projects", "__wf_script_test__");
@@ -14,19 +15,15 @@ NodeFS.writeFileSync(scriptPath, "export const meta = {};\n");
 const outside = NodePath.join(NodeOS.tmpdir(), "wf-outside.js");
 NodeFS.writeFileSync(outside, "evil\n");
 const link = NodePath.join(root, "sneaky.js");
-try {
+// Planted only where the host allows it; the escape test is skipped
+// otherwise rather than passing vacuously on "not-found".
+if (symlinksSupported) {
+  NodeFS.rmSync(link, { force: true });
   NodeFS.symlinkSync(outside, link);
-} catch (error) {
-  // Tolerate only "already exists" from a prior run — any other failure
-  // (EPERM etc.) must fail setup, or the escape test below would pass
-  // vacuously on "not-found" without testing containment.
-  if ((error as NodeJS.ErrnoException).code !== "EEXIST") {
-    throw error;
+  if (!NodeFS.lstatSync(link).isSymbolicLink()) {
+    throw new Error("test setup: sneaky.js must be a symlink");
   }
 }
-if (!NodeFS.lstatSync(link).isSymbolicLink()) {
-  throw new Error("test setup: sneaky.js must be a symlink");
-}
 
 afterAll(() => {
   NodeFS.rmSync(root, { recursive: true, force: true });
@@ -53,23 +50,25 @@ describe("readWorkflowScript containment", () => {
     }),
   );
 
-  effectIt.effect("rejects paths outside the root and symlink escapes", () =>
-    Effect.gen(function* () {
-      const escaped = yield* Effect.exit(readWorkflowScript({ scriptPath: outside }));
-      assert.equal(escaped._tag, "Failure");
-      // A symlink INSIDE the root pointing outside must fail specifically on
-      // realpath re-containment — a "not-found" would mean the link was
-      // never exercised and the assertion proves nothing.
-      const sneaky = yield* Effect.exit(
-        readWorkflowScript({ scriptPath: link }).pipe(
-          Effect.flip,
-          Effect.map((error) => error.reason),
-        ),
-      );
-      assert.equal(sneaky._tag, "Success");
-      if (sneaky._tag === "Success") {
-        assert.equal(sneaky.value, "outside-root");
-      }
-    }),
+  effectIt.effect.skipIf(!symlinksSupported)(
+    "rejects paths outside the root and symlink escapes",
+    () =>
+      Effect.gen(function* () {
+        const escaped = yield* Effect.exit(readWorkflowScript({ scriptPath: outside }));
+        assert.equal(escaped._tag, "Failure");
+        // A symlink INSIDE the root pointing outside must fail specifically on
+        // realpath re-containment — a "not-found" would mean the link was
+        // never exercised and the assertion proves nothing.
+        const sneaky = yield* Effect.exit(
+          readWorkflowScript({ scriptPath: link }).pipe(
+            Effect.flip,
+            Effect.map((error) => error.reason),
+          ),
+        );
+        assert.equal(sneaky._tag, "Success");
+        if (sneaky._tag === "Success") {
+          assert.equal(sneaky.value, "outside-root");
+        }
+      }),
   );
 });
diff --git a/apps/server/src/persistence/AuthSessions.ts b/apps/server/src/persistence/AuthSessions.ts
index 579d3a608190..aebbb839e5ce 100644
--- a/apps/server/src/persistence/AuthSessions.ts
+++ b/apps/server/src/persistence/AuthSessions.ts
@@ -55,6 +55,13 @@ export const CreateAuthSessionInput = Schema.Struct({
 });
 export type CreateAuthSessionInput = typeof CreateAuthSessionInput.Type;
 
+export const CreateReplacingActiveAuthSessionInput = Schema.Struct({
+  session: CreateAuthSessionInput,
+  revokedAt: Schema.DateTimeUtcFromString,
+});
+export type CreateReplacingActiveAuthSessionInput =
+  typeof CreateReplacingActiveAuthSessionInput.Type;
+
 export const GetAuthSessionByIdInput = Schema.Struct({
   sessionId: AuthSessionId,
 });
@@ -62,6 +69,7 @@ export type GetAuthSessionByIdInput = typeof GetAuthSessionByIdInput.Type;
 
 export const ListActiveAuthSessionsInput = Schema.Struct({
   now: Schema.DateTimeUtcFromString,
+  connectedSessionIds: Schema.optionalKey(Schema.Array(AuthSessionId)),
 });
 export type ListActiveAuthSessionsInput = typeof ListActiveAuthSessionsInput.Type;
 
@@ -96,6 +104,9 @@ export class AuthSessionRepository extends Context.Service<
     readonly create: (
       input: CreateAuthSessionInput,
     ) => Effect.Effect<void, AuthSessionRepositoryError>;
+    readonly createReplacingActive: (
+      input: CreateReplacingActiveAuthSessionInput,
+    ) => Effect.Effect<ReadonlyArray<AuthSessionId>, AuthSessionRepositoryError>;
     readonly getById: (
       input: GetAuthSessionByIdInput,
     ) => Effect.Effect<Option.Option<AuthSessionRecord>, AuthSessionRepositoryError>;
@@ -254,10 +265,25 @@ export const make = Effect.gen(function* () {
       `,
   });
 
+  const revokeActiveSessionsForReplacement = SqlSchema.findAll({
+    Request: CreateReplacingActiveAuthSessionInput,
+    Result: Schema.Struct({ sessionId: AuthSessionId }),
+    execute: ({ session, revokedAt }) =>
+      sql`
+        UPDATE auth_sessions
+        SET revoked_at = ${revokedAt}
+        WHERE subject = ${session.subject}
+          AND method = ${session.method}
+          AND revoked_at IS NULL
+          AND expires_at > ${revokedAt}
+        RETURNING session_id AS "sessionId"
+      `,
+  });
+
   const listActiveSessionRows = SqlSchema.findAll({
     Request: ListActiveAuthSessionsInput,
     Result: AuthSessionRawDbRow,
-    execute: ({ now }) =>
+    execute: ({ now, connectedSessionIds = [] }) =>
       sql`
         SELECT
           session_id AS "sessionId",
@@ -276,7 +302,7 @@ export const make = Effect.gen(function* () {
           revoked_at AS "revokedAt"
         FROM auth_sessions
         WHERE revoked_at IS NULL
-          AND expires_at > ${now}
+          AND (expires_at > ${now} OR ${sql.in("session_id", connectedSessionIds)})
         ORDER BY issued_at DESC, session_id DESC
       `,
   });
@@ -343,6 +369,29 @@ export const make = Effect.gen(function* () {
       ),
     );
 
+  const createReplacingActive: AuthSessionRepository["Service"]["createReplacingActive"] = (
+    input,
+  ) =>
+    sql
+      .withTransaction(
+        revokeActiveSessionsForReplacement(input).pipe(
+          Effect.flatMap((revokedRows) =>
+            createSessionRow(input.session).pipe(
+              Effect.as(revokedRows.map((row) => row.sessionId)),
+            ),
+          ),
+        ),
+      )
+      .pipe(
+        Effect.mapError(
+          toPersistenceSqlOrDecodeError(
+            "AuthSessionRepository.createReplacingActive:query",
+            "AuthSessionRepository.createReplacingActive:encodeRequest",
+            { sessionId: input.session.sessionId },
+          ),
+        ),
+      );
+
   const getById: AuthSessionRepository["Service"]["getById"] = (input) =>
     getSessionRowById(input).pipe(
       Effect.mapError(
@@ -442,6 +491,7 @@ export const make = Effect.gen(function* () {
 
   return {
     create,
+    createReplacingActive,
     getById,
     listActive,
     revoke,
diff --git a/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts b/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
index 1e21501e4096..e7e6b6590080 100644
--- a/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
+++ b/apps/server/src/persistence/Layers/OrchestrationEventStore.test.ts
@@ -1,4 +1,11 @@
-import { CommandId, EventId, ProjectId } from "@t3tools/contracts";
+import {
+  CommandId,
+  EventId,
+  MessageId,
+  ProjectId,
+  ThreadId,
+  type OrchestrationEvent,
+} from "@t3tools/contracts";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -12,6 +19,31 @@ import { OrchestrationEventStoreLive } from "./OrchestrationEventStore.ts";
 import { SqlitePersistenceMemory } from "./Sqlite.ts";
 const isPersistenceDecodeError = Schema.is(PersistenceDecodeError);
 
+function messageEvent(threadId: ThreadId, id: string): Omit<OrchestrationEvent, "sequence"> {
+  const now = "2026-01-01T00:00:00.000Z";
+  return {
+    type: "thread.message-sent",
+    eventId: EventId.make(id),
+    aggregateKind: "thread",
+    aggregateId: threadId,
+    occurredAt: now,
+    commandId: null,
+    causationEventId: null,
+    correlationId: null,
+    metadata: {},
+    payload: {
+      threadId,
+      messageId: MessageId.make(id),
+      role: "assistant",
+      text: id,
+      turnId: null,
+      streaming: false,
+      createdAt: now,
+      updatedAt: now,
+    },
+  };
+}
+
 const layer = it.layer(
   OrchestrationEventStoreLive.pipe(Layer.provideMerge(SqlitePersistenceMemory)),
 );
@@ -79,7 +111,7 @@ layer("OrchestrationEventStore", (it) => {
       const sql = yield* SqlClient.SqlClient;
       const now = "2026-01-01T00:00:00.000Z";
 
-      yield* sql`
+      const invalidRows = yield* sql<{ readonly sequence: number }>`
         INSERT INTO orchestration_events (
           event_id,
           aggregate_kind,
@@ -108,6 +140,7 @@ layer("OrchestrationEventStore", (it) => {
           ${"{"},
           ${"{}"}
         )
+        RETURNING sequence
       `;
 
       const replayResult = yield* Effect.result(
@@ -122,6 +155,154 @@ layer("OrchestrationEventStore", (it) => {
           ),
         );
       }
+      const scopedResult = yield* eventStore
+        .readAggregateRange({
+          aggregateKind: "project",
+          aggregateId: "project-invalid-json",
+          fromSequenceExclusive: 0,
+          toSequenceInclusive: invalidRows[0]!.sequence,
+        })
+        .pipe(Stream.runCollect, Effect.result);
+      assert.equal(scopedResult._tag, "Failure");
+      if (scopedResult._tag === "Failure") {
+        assert.ok(isPersistenceDecodeError(scopedResult.failure));
+        assert.ok(
+          scopedResult.failure.operation.includes(
+            "OrchestrationEventStore.readAggregateRange:decodeRows",
+          ),
+        );
+      }
+    }),
+  );
+
+  it.effect("reads one aggregate through the captured head across pruned global gaps", () =>
+    Effect.gen(function* () {
+      const store = yield* OrchestrationEventStore;
+      const sql = yield* SqlClient.SqlClient;
+      const threadId = ThreadId.make("shared-stream-id");
+      const first = yield* store.append(messageEvent(threadId, "scoped-first"));
+      const pruned = yield* store.append(
+        messageEvent(ThreadId.make("pruned-thread"), "pruned-event"),
+      );
+      const second = yield* store.append(messageEvent(threadId, "scoped-second"));
+      // The same stream ID in a different aggregate is not part of this thread.
+      // Its invalid JSON must never reach the event decoder.
+      yield* sql`
+        INSERT INTO orchestration_events (
+          event_id, aggregate_kind, stream_id, stream_version, event_type, occurred_at,
+          actor_kind, payload_json, metadata_json
+        ) VALUES (
+          'same-id-project', 'project', ${threadId}, 0, 'project.created',
+          '2026-01-01T00:00:00.000Z', 'server', '{', '{'
+        ), (
+          'unrelated-invalid', 'thread', 'unrelated-invalid-thread', 0, 'thread.activity-appended',
+          '2026-01-01T00:00:00.000Z', 'server', '{', '{'
+        )
+      `;
+      const last = yield* store.append(messageEvent(threadId, "scoped-last"));
+      yield* sql`DELETE FROM orchestration_events WHERE sequence = ${pruned.sequence}`;
+      yield* store.append(messageEvent(threadId, "after-captured-head"));
+
+      const events = yield* store
+        .readAggregateRange({
+          aggregateKind: "thread",
+          aggregateId: threadId,
+          fromSequenceExclusive: first.sequence,
+          toSequenceInclusive: last.sequence,
+          limit: 100,
+        })
+        .pipe(Stream.runCollect);
+      assert.deepEqual(
+        events.map((event) => event.sequence),
+        [second.sequence, last.sequence],
+      );
+    }),
+  );
+
+  it.effect("bounds thread replay metadata and counts UTF-8 bytes without decoding payloads", () =>
+    Effect.gen(function* () {
+      const store = yield* OrchestrationEventStore;
+      const sql = yield* SqlClient.SqlClient;
+      const rows = yield* sql<{ readonly sequence: number }>`
+        INSERT INTO orchestration_events (
+          event_id, aggregate_kind, stream_id, stream_version, event_type, occurred_at,
+          actor_kind, payload_json, metadata_json
+        ) VALUES
+          ('stats-1', 'thread', 'stats-thread', 0, 'thread.message-sent',
+            '2026-01-01T00:00:00.000Z', 'provider', '{"output":"😀"}', '{}'),
+          ('stats-unrelated', 'thread', 'another-thread', 0, 'thread.created',
+            '2026-01-01T00:00:00.000Z', 'provider', printf('%.*c', 10000, 'x'), '{}'),
+          ('stats-2', 'thread', 'stats-thread', 1, 'thread.activity-appended',
+            '2026-01-01T00:00:00.000Z', 'provider', '{', '{}'),
+          ('stats-other-kind', 'project', 'stats-thread', 0, 'project.deleted',
+            '2026-01-01T00:00:00.000Z', 'provider', printf('%.*c', 20000, 'x'), '{}'),
+          ('stats-3', 'thread', 'stats-thread', 2, 'thread.deleted',
+            '2026-01-01T00:00:00.000Z', 'provider', '{"output":"é"}', '{}'),
+          ('stats-4', 'thread', 'stats-thread', 3, 'thread.created',
+            '2026-01-01T00:00:00.000Z', 'provider', printf('%.*c', 2000, 'x'), '{}')
+        RETURNING sequence
+      `;
+      const range = {
+        aggregateKind: "thread" as const,
+        aggregateId: "stats-thread",
+        fromSequenceExclusive: 0,
+        toSequenceInclusive: rows.at(-1)!.sequence,
+      };
+      assert.deepEqual(yield* store.getAggregateReplayStats({ ...range, maxEvents: 2 }), {
+        eventCount: 3,
+        payloadBytes: 33,
+        hasCreateEvent: false,
+      });
+      assert.deepEqual(yield* store.getAggregateReplayStats({ ...range, maxEvents: 10 }), {
+        eventCount: 4,
+        payloadBytes: 2033,
+        hasCreateEvent: true,
+      });
+      assert.deepEqual(
+        yield* store.getAggregateReplayStats({
+          ...range,
+          toSequenceInclusive: rows[2]!.sequence,
+          maxEvents: 10,
+        }),
+        {
+          eventCount: 2,
+          payloadBytes: 18,
+          hasCreateEvent: false,
+        },
+      );
+    }),
+  );
+
+  it.effect("keeps later pages below the captured head when new events are appended", () =>
+    Effect.gen(function* () {
+      const store = yield* OrchestrationEventStore;
+      const threadId = ThreadId.make("paged-thread");
+      const persisted = yield* Effect.forEach(
+        Array.from({ length: 502 }, (_, index) => index),
+        (index) => store.append(messageEvent(threadId, `paged-${index}`)),
+      );
+      const head = persisted.at(-1)!.sequence;
+      let appendedDuringReplay = false;
+      const replayed = yield* store
+        .readAggregateRange({
+          aggregateKind: "thread",
+          aggregateId: threadId,
+          fromSequenceExclusive: 0,
+          toSequenceInclusive: head,
+          limit: 1_000,
+        })
+        .pipe(
+          Stream.tap(() => {
+            if (appendedDuringReplay) return Effect.void;
+            appendedDuringReplay = true;
+            return store.append(messageEvent(threadId, "appended-during-replay"));
+          }),
+          Stream.runCollect,
+        );
+      assert.deepEqual(
+        replayed.map((event) => event.sequence),
+        persisted.map((event) => event.sequence),
+      );
     }),
   );
 });
diff --git a/apps/server/src/persistence/Layers/OrchestrationEventStore.ts b/apps/server/src/persistence/Layers/OrchestrationEventStore.ts
index e801c34af582..1f97f514e43c 100644
--- a/apps/server/src/persistence/Layers/OrchestrationEventStore.ts
+++ b/apps/server/src/persistence/Layers/OrchestrationEventStore.ts
@@ -72,6 +72,18 @@ const ReadFromSequenceRequestSchema = Schema.Struct({
   sequenceExclusive: NonNegativeInt,
   limit: Schema.Number,
 });
+const AggregateReplayRequestSchema = Schema.Struct({
+  aggregateKind: OrchestrationAggregateKind,
+  aggregateId: Schema.String,
+  fromSequenceExclusive: NonNegativeInt,
+  toSequenceInclusive: NonNegativeInt,
+  limit: Schema.Number,
+});
+const AggregateReplayStatsRowSchema = Schema.Struct({
+  eventCount: Schema.Number,
+  payloadBytes: Schema.Number,
+  hasCreateEvent: Schema.Number,
+});
 const DEFAULT_READ_FROM_SEQUENCE_LIMIT = 1_000;
 const READ_PAGE_SIZE = 500;
 
@@ -189,6 +201,57 @@ const makeEventStore = Effect.gen(function* () {
       `,
   });
 
+  const readAggregateEventRows = SqlSchema.findAll({
+    Request: AggregateReplayRequestSchema,
+    Result: OrchestrationEventPersistedRowSchema,
+    execute: (request) =>
+      sql`
+        SELECT
+          sequence,
+          event_id AS "eventId",
+          event_type AS "type",
+          aggregate_kind AS "aggregateKind",
+          stream_id AS "aggregateId",
+          occurred_at AS "occurredAt",
+          command_id AS "commandId",
+          causation_event_id AS "causationEventId",
+          correlation_id AS "correlationId",
+          payload_json AS "payload",
+          metadata_json AS "metadata"
+        FROM orchestration_events
+        WHERE aggregate_kind = ${request.aggregateKind}
+          AND stream_id = ${request.aggregateId}
+          AND sequence > ${request.fromSequenceExclusive}
+          AND sequence <= ${request.toSequenceInclusive}
+        ORDER BY sequence ASC
+        LIMIT ${request.limit}
+      `,
+  });
+
+  const readAggregateReplayStats = SqlSchema.findOne({
+    Request: AggregateReplayRequestSchema,
+    Result: AggregateReplayStatsRowSchema,
+    execute: (request) =>
+      sql`
+        SELECT
+          COUNT(*) AS "eventCount",
+          COALESCE(SUM(octet_length(payload_json)), 0) AS "payloadBytes",
+          COALESCE(MAX(event_type IN (
+            'thread.created', 'project.created'
+          )), 0) AS "hasCreateEvent"
+        FROM (
+          SELECT payload_json, event_type
+          FROM orchestration_events
+          WHERE aggregate_kind = ${request.aggregateKind}
+            AND stream_id = ${request.aggregateId}
+            AND sequence > ${request.fromSequenceExclusive}
+            AND sequence <= ${request.toSequenceInclusive}
+          ORDER BY sequence ASC
+          LIMIT ${request.limit}
+        )
+      `,
+  });
+
   const append: OrchestrationEventStoreShape["append"] = (event) =>
     appendEventRow({
       eventId: event.eventId,
@@ -295,9 +358,78 @@ const makeEventStore = Effect.gen(function* () {
       ),
     );
 
+  const readAggregateRange: OrchestrationEventStoreShape["readAggregateRange"] = (input) => {
+    const limit = Math.max(0, Math.floor(input.limit ?? DEFAULT_READ_FROM_SEQUENCE_LIMIT));
+    if (limit === 0 || input.fromSequenceExclusive >= input.toSequenceInclusive) {
+      return Stream.empty;
+    }
+    const readPage = (
+      cursor: number,
+      remaining: number,
+    ): Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError> =>
+      Stream.fromEffect(
+        readAggregateEventRows({
+          ...input,
+          fromSequenceExclusive: cursor,
+          limit: Math.min(remaining, READ_PAGE_SIZE),
+        }).pipe(
+          Effect.mapError(
+            toPersistenceSqlOrDecodeError(
+              "OrchestrationEventStore.readAggregateRange:query",
+              "OrchestrationEventStore.readAggregateRange:decodeRows",
+            ),
+          ),
+          Effect.flatMap((rows) =>
+            Effect.forEach(rows, (row) =>
+              decodeEvent(row).pipe(
+                Effect.mapError(
+                  toPersistenceDecodeError("OrchestrationEventStore.readAggregateRange:rowToEvent"),
+                ),
+              ),
+            ),
+          ),
+        ),
+      ).pipe(
+        Stream.flatMap((events) => {
+          const last = events.at(-1);
+          if (last === undefined) {
+            return Stream.empty;
+          }
+          const nextRemaining = remaining - events.length;
+          if (
+            events.length < READ_PAGE_SIZE ||
+            nextRemaining === 0 ||
+            last.sequence >= input.toSequenceInclusive
+          ) {
+            return Stream.fromIterable(events);
+          }
+          return Stream.concat(Stream.fromIterable(events), readPage(last.sequence, nextRemaining));
+        }),
+      );
+    return readPage(input.fromSequenceExclusive, limit);
+  };
+
+  const getAggregateReplayStats: OrchestrationEventStoreShape["getAggregateReplayStats"] = (
+    input,
+  ) =>
+    readAggregateReplayStats({
+      ...input,
+      limit: Math.max(0, Math.floor(input.maxEvents)) + 1,
+    }).pipe(
+      Effect.mapError(
+        toPersistenceSqlOrDecodeError(
+          "OrchestrationEventStore.getAggregateReplayStats:query",
+          "OrchestrationEventStore.getAggregateReplayStats:decodeRow",
+        ),
+      ),
+      Effect.map((row) => ({ ...row, hasCreateEvent: row.hasCreateEvent !== 0 })),
+    );
+
   return {
     append,
     readFromSequence,
+    readAggregateRange,
+    getAggregateReplayStats,
     readAll: () => readFromSequence(0, Number.MAX_SAFE_INTEGER),
     hasEventAfter,
   } satisfies OrchestrationEventStoreShape;
diff --git a/apps/server/src/persistence/Layers/ProjectionPendingApprovals.ts b/apps/server/src/persistence/Layers/ProjectionPendingApprovals.ts
index 3b159a9e1715..d5631cb0a62c 100644
--- a/apps/server/src/persistence/Layers/ProjectionPendingApprovals.ts
+++ b/apps/server/src/persistence/Layers/ProjectionPendingApprovals.ts
@@ -2,6 +2,7 @@ import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
 
 import { toPersistenceSqlError } from "../Errors.ts";
 import {
@@ -68,6 +69,16 @@ const makeProjectionPendingApprovalRepository = Effect.gen(function* () {
       `,
   });
 
+  const countPendingApprovalRows = SqlSchema.findOne({
+    Request: ListProjectionPendingApprovalsInput,
+    Result: Schema.Struct({ count: Schema.Number }),
+    execute: ({ threadId }) => sql`
+      SELECT COUNT(*) AS count
+      FROM projection_pending_approvals
+      WHERE thread_id = ${threadId} AND status = 'pending'
+    `,
+  });
+
   const getProjectionPendingApprovalRow = SqlSchema.findOneOption({
     Request: GetProjectionPendingApprovalInput,
     Result: ProjectionPendingApproval,
@@ -116,6 +127,15 @@ const makeProjectionPendingApprovalRepository = Effect.gen(function* () {
       ),
     );
 
+  const countPendingByThreadId: ProjectionPendingApprovalRepositoryShape["countPendingByThreadId"] =
+    (input) =>
+      countPendingApprovalRows(input).pipe(
+        Effect.mapError(
+          toPersistenceSqlError("ProjectionPendingApprovalRepository.countPendingByThreadId:query"),
+        ),
+        Effect.map((row) => row.count),
+      );
+
   const getByRequestId: ProjectionPendingApprovalRepositoryShape["getByRequestId"] = (input) =>
     getProjectionPendingApprovalRow(input).pipe(
       Effect.mapError(
@@ -142,6 +162,7 @@ const makeProjectionPendingApprovalRepository = Effect.gen(function* () {
   return {
     upsert,
     listByThreadId,
+    countPendingByThreadId,
     getByRequestId,
     deleteByRequestId,
     deleteByThreadId,
diff --git a/apps/server/src/persistence/Layers/ProjectionState.ts b/apps/server/src/persistence/Layers/ProjectionState.ts
index f630fe51e03c..a6fb7f3be4dd 100644
--- a/apps/server/src/persistence/Layers/ProjectionState.ts
+++ b/apps/server/src/persistence/Layers/ProjectionState.ts
@@ -42,6 +42,26 @@ const makeProjectionStateRepository = Effect.gen(function* () {
       `,
   });
 
+  const upsertProjectionStateRows = SqlSchema.void({
+    Request: Schema.Array(ProjectionState),
+    execute: (rows) =>
+      rows.length === 0
+        ? Effect.void
+        : sql`
+            INSERT INTO projection_state ${sql.insert(
+              rows.map((row) => ({
+                projector: row.projector,
+                last_applied_sequence: row.lastAppliedSequence,
+                updated_at: row.updatedAt,
+              })),
+            )}
+            ON CONFLICT (projector)
+            DO UPDATE SET
+              last_applied_sequence = excluded.last_applied_sequence,
+              updated_at = excluded.updated_at
+          `,
+  });
+
   const getProjectionStateRow = SqlSchema.findOneOption({
     Request: GetProjectionStateInput,
     Result: ProjectionState,
@@ -86,6 +106,11 @@ const makeProjectionStateRepository = Effect.gen(function* () {
       Effect.mapError(toPersistenceSqlError("ProjectionStateRepository.upsert:query")),
     );
 
+  const upsertMany: ProjectionStateRepositoryShape["upsertMany"] = (rows) =>
+    upsertProjectionStateRows(rows).pipe(
+      Effect.mapError(toPersistenceSqlError("ProjectionStateRepository.upsertMany:query")),
+    );
+
   const getByProjector: ProjectionStateRepositoryShape["getByProjector"] = (input) =>
     getProjectionStateRow(input).pipe(
       Effect.mapError(toPersistenceSqlError("ProjectionStateRepository.getByProjector:query")),
@@ -106,6 +131,7 @@ const makeProjectionStateRepository = Effect.gen(function* () {
 
   return {
     upsert,
+    upsertMany,
     getByProjector,
     listAll,
     minLastAppliedSequence,
diff --git a/apps/server/src/persistence/Layers/ProjectionThreadMessages.test.ts b/apps/server/src/persistence/Layers/ProjectionThreadMessages.test.ts
index 30e0f42cab89..d4a70af59be5 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreadMessages.test.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreadMessages.test.ts
@@ -12,6 +12,61 @@ const layer = it.layer(
 );
 
 layer("ProjectionThreadMessageRepository", (it) => {
+  it.effect("finds the latest live user-message time within one thread", () =>
+    Effect.gen(function* () {
+      const repository = yield* ProjectionThreadMessageRepository;
+      const threadId = ThreadId.make("thread-latest-user-message");
+      assert.isNull(yield* repository.getLatestUserMessageAt({ threadId }));
+
+      yield* repository.upsert({
+        messageId: MessageId.make("import:codex:latest-user-message:000000"),
+        threadId,
+        turnId: null,
+        role: "user",
+        text: "Imported prompt",
+        isStreaming: false,
+        createdAt: "2026-02-28T19:05:06.000Z",
+        updatedAt: "2026-02-28T19:05:06.000Z",
+      });
+      assert.isNull(yield* repository.getLatestUserMessageAt({ threadId }));
+
+      const messages = [
+        { role: "user", createdAt: "2026-02-28T19:05:02.000Z" },
+        { role: "user", createdAt: "2026-02-28T19:05:01.000Z" },
+        { role: "assistant", createdAt: "2026-02-28T19:05:03.000Z" },
+        { role: "system", createdAt: "2026-02-28T19:05:04.000Z" },
+      ] as const;
+      for (const [index, message] of messages.entries()) {
+        yield* repository.upsert({
+          messageId: MessageId.make(`latest-user-message-${index}`),
+          threadId,
+          turnId: null,
+          ...message,
+          text: "Message body",
+          isStreaming: false,
+          updatedAt: "2026-02-28T19:06:00.000Z",
+        });
+      }
+      yield* repository.upsert({
+        messageId: MessageId.make("latest-user-message-other-thread"),
+        threadId: ThreadId.make("thread-latest-user-message-other"),
+        turnId: null,
+        role: "user",
+        text: "Other thread",
+        isStreaming: false,
+        createdAt: "2026-02-28T19:05:05.000Z",
+        updatedAt: "2026-02-28T19:05:05.000Z",
+      });
+
+      assert.strictEqual(
+        yield* repository.getLatestUserMessageAt({ threadId }),
+        "2026-02-28T19:05:02.000Z",
+      );
+      yield* repository.deleteByThreadId({ threadId });
+      assert.isNull(yield* repository.getLatestUserMessageAt({ threadId }));
+    }),
+  );
+
   it.effect("appends streaming text and applies attachment updates", () =>
     Effect.gen(function* () {
       const repository = yield* ProjectionThreadMessageRepository;
diff --git a/apps/server/src/persistence/Layers/ProjectionThreadMessages.ts b/apps/server/src/persistence/Layers/ProjectionThreadMessages.ts
index 85e854dc6606..be20fb37f36d 100644
--- a/apps/server/src/persistence/Layers/ProjectionThreadMessages.ts
+++ b/apps/server/src/persistence/Layers/ProjectionThreadMessages.ts
@@ -182,6 +182,19 @@ const makeProjectionThreadMessageRepository = Effect.gen(function* () {
       `,
   });
 
+  const getLatestUserMessageAtRow = SqlSchema.findOne({
+    Request: ListProjectionThreadMessagesInput,
+    Result: Schema.Struct({
+      latestUserMessageAt: Schema.NullOr(ProjectionThreadMessage.fields.createdAt),
+    }),
+    execute: ({ threadId }) => sql`
+      SELECT MAX(created_at) AS "latestUserMessageAt"
+      FROM projection_thread_messages
+      WHERE thread_id = ${threadId} AND role = 'user'
+        AND message_id NOT GLOB 'import:*'
+    `,
+  });
+
   const deleteProjectionThreadMessageRows = SqlSchema.void({
     Request: DeleteProjectionThreadMessagesInput,
     execute: ({ threadId }) =>
@@ -219,6 +232,16 @@ const makeProjectionThreadMessageRepository = Effect.gen(function* () {
       Effect.map((rows) => rows.map(toProjectionThreadMessage)),
     );
 
+  const getLatestUserMessageAt: ProjectionThreadMessageRepositoryShape["getLatestUserMessageAt"] = (
+    input,
+  ) =>
+    getLatestUserMessageAtRow(input).pipe(
+      Effect.mapError(
+        toPersistenceSqlError("ProjectionThreadMessageRepository.getLatestUserMessageAt:query"),
+      ),
+      Effect.map((row) => row.latestUserMessageAt),
+    );
+
   const deleteByThreadId: ProjectionThreadMessageRepositoryShape["deleteByThreadId"] = (input) =>
     deleteProjectionThreadMessageRows(input).pipe(
       Effect.mapError(
@@ -231,6 +254,7 @@ const makeProjectionThreadMessageRepository = Effect.gen(function* () {
     appendStreaming,
     getByMessageId,
     listByThreadId,
+    getLatestUserMessageAt,
     deleteByThreadId,
   } satisfies ProjectionThreadMessageRepositoryShape;
 });
diff --git a/apps/server/src/persistence/ProviderSessionRuntime.ts b/apps/server/src/persistence/ProviderSessionRuntime.ts
index 2ccdd862522f..d73f56aab9e0 100644
--- a/apps/server/src/persistence/ProviderSessionRuntime.ts
+++ b/apps/server/src/persistence/ProviderSessionRuntime.ts
@@ -10,6 +10,7 @@ import * as SqlClient from "effect/unstable/sql/SqlClient";
 import * as SqlSchema from "effect/unstable/sql/SqlSchema";
 
 import {
+  AgentSessionImportSource,
   IsoDateTime,
   ProviderInstanceId,
   ProviderSessionRuntimeStatus,
@@ -58,6 +59,16 @@ export type GetProviderSessionRuntimeInput = typeof GetProviderSessionRuntimeInp
 export const DeleteProviderSessionRuntimeInput = Schema.Struct({ threadId: ThreadId });
 export type DeleteProviderSessionRuntimeInput = typeof DeleteProviderSessionRuntimeInput.Type;
 
+export const RecordImportedTranscriptInput = Schema.Struct({
+  threadId: ThreadId,
+  source: AgentSessionImportSource,
+});
+export type RecordImportedTranscriptInput = typeof RecordImportedTranscriptInput.Type;
+
+export interface ProviderSessionRuntimeUpsertOptions {
+  readonly onConflict?: "update" | "ignore";
+}
+
 /**
  * ProviderSessionRuntimeRepository - Service tag for provider runtime persistence.
  */
@@ -67,10 +78,17 @@ export class ProviderSessionRuntimeRepository extends Context.Service<
     /**
      * Insert or replace a provider runtime row.
      *
-     * Upserts by canonical `threadId`, including JSON payload/cursor fields.
+     * Upserts by canonical `threadId`, retaining imported transcript records
+     * from the current database row.
      */
     readonly upsert: (
       runtime: ProviderSessionRuntime,
+      options?: ProviderSessionRuntimeUpsertOptions,
+    ) => Effect.Effect<void, ProviderSessionRuntimeRepositoryError>;
+
+    /** Record one source file without replacing the current session state. */
+    readonly recordImportedTranscript: (
+      input: RecordImportedTranscriptInput,
     ) => Effect.Effect<void, ProviderSessionRuntimeRepositoryError>;
 
     /**
@@ -129,6 +147,10 @@ const GetRuntimeRequestSchema = Schema.Struct({
 
 const DeleteRuntimeRequestSchema = GetRuntimeRequestSchema;
 
+const RecordImportedTranscriptRequestSchema = RecordImportedTranscriptInput.mapFields(
+  Struct.assign({ source: Schema.fromJsonString(AgentSessionImportSource) }),
+);
+
 function toPersistenceSqlOrDecodeError(
   sqlOperation: string,
   decodeOperation: string,
@@ -147,6 +169,8 @@ function toPersistenceSqlOrDecodeError(
 export const make = Effect.gen(function* () {
   const sql = yield* SqlClient.SqlClient;
 
+  // Runtime writes can carry stale payloads. Only recordImportedTranscript may
+  // change source records, so restore that field from the row being updated.
   const upsertRuntimeRow = SqlSchema.void({
     Request: ProviderSessionRuntimeDbRowSchema,
     execute: (runtime) =>
@@ -171,7 +195,11 @@ export const make = Effect.gen(function* () {
           ${runtime.status},
           ${runtime.lastSeenAt},
           ${runtime.resumeCursor},
-          ${runtime.runtimePayload}
+          CASE
+            WHEN json_type(${runtime.runtimePayload}) = 'object'
+            THEN json_remove(${runtime.runtimePayload}, '$.importedTranscripts')
+            ELSE ${runtime.runtimePayload}
+          END
         )
         ON CONFLICT (thread_id)
         DO UPDATE SET
@@ -182,7 +210,107 @@ export const make = Effect.gen(function* () {
           status = excluded.status,
           last_seen_at = excluded.last_seen_at,
           resume_cursor_json = excluded.resume_cursor_json,
-          runtime_payload_json = excluded.runtime_payload_json
+          runtime_payload_json = CASE
+            WHEN json_type(
+              CASE
+                WHEN json_valid(provider_session_runtime.runtime_payload_json)
+                THEN provider_session_runtime.runtime_payload_json
+                ELSE '{}'
+              END,
+              '$.importedTranscripts'
+            ) IS NOT NULL
+            THEN json_set(
+              CASE
+                WHEN json_type(excluded.runtime_payload_json) = 'object'
+                THEN excluded.runtime_payload_json
+                ELSE '{}'
+              END,
+              '$.importedTranscripts',
+              json_extract(provider_session_runtime.runtime_payload_json, '$.importedTranscripts')
+            )
+            ELSE excluded.runtime_payload_json
+          END
+      `,
+  });
+
+  const insertRuntimeRow = SqlSchema.void({
+    Request: ProviderSessionRuntimeDbRowSchema,
+    execute: (runtime) =>
+      sql`
+        INSERT INTO provider_session_runtime (
+          thread_id,
+          provider_name,
+          provider_instance_id,
+          adapter_key,
+          runtime_mode,
+          status,
+          last_seen_at,
+          resume_cursor_json,
+          runtime_payload_json
+        )
+        VALUES (
+          ${runtime.threadId},
+          ${runtime.providerName},
+          ${runtime.providerInstanceId},
+          ${runtime.adapterKey},
+          ${runtime.runtimeMode},
+          ${runtime.status},
+          ${runtime.lastSeenAt},
+          ${runtime.resumeCursor},
+          CASE
+            WHEN json_type(${runtime.runtimePayload}) = 'object'
+            THEN json_remove(${runtime.runtimePayload}, '$.importedTranscripts')
+            ELSE ${runtime.runtimePayload}
+          END
+        )
+        ON CONFLICT (thread_id) DO NOTHING
+      `,
+  });
+
+  const recordImportedTranscriptRow = SqlSchema.void({
+    Request: RecordImportedTranscriptRequestSchema,
+    execute: ({ threadId, source }) =>
+      sql`
+        WITH current_runtime AS (
+          SELECT CASE
+            WHEN json_valid(runtime_payload_json) THEN CASE
+              WHEN json_type(runtime_payload_json) = 'object' THEN runtime_payload_json
+              ELSE '{}'
+            END
+            ELSE '{}'
+          END AS payload
+          FROM provider_session_runtime
+          WHERE thread_id = ${threadId}
+        )
+        UPDATE provider_session_runtime
+        SET runtime_payload_json = (
+          SELECT json_set(
+            payload,
+            '$.importedTranscripts',
+            json((
+              SELECT json_group_array(json(value))
+              FROM (
+                SELECT value
+                FROM json_each(CASE
+                  WHEN json_type(payload, '$.importedTranscripts') = 'array'
+                  THEN json_extract(payload, '$.importedTranscripts')
+                  ELSE '[]'
+                END)
+                WHERE CASE
+                  WHEN type = 'object' THEN
+                    json_extract(value, '$.providerInstanceId')
+                      IS NOT json_extract(${source}, '$.providerInstanceId')
+                    OR json_extract(value, '$.filePath') IS NOT json_extract(${source}, '$.filePath')
+                  ELSE 0
+                END
+                UNION ALL
+                SELECT ${source} AS value
+              )
+            ))
+          )
+          FROM current_runtime
+        )
+        WHERE thread_id = ${threadId}
       `,
   });
 
@@ -235,8 +363,8 @@ export const make = Effect.gen(function* () {
       `,
   });
 
-  const upsert: ProviderSessionRuntimeRepository["Service"]["upsert"] = (runtime) =>
-    upsertRuntimeRow(runtime).pipe(
+  const upsert: ProviderSessionRuntimeRepository["Service"]["upsert"] = (runtime, options) =>
+    (options?.onConflict === "ignore" ? insertRuntimeRow(runtime) : upsertRuntimeRow(runtime)).pipe(
       Effect.mapError(
         toPersistenceSqlOrDecodeError(
           "ProviderSessionRuntimeRepository.upsert:query",
@@ -246,6 +374,18 @@ export const make = Effect.gen(function* () {
       ),
     );
 
+  const recordImportedTranscript: ProviderSessionRuntimeRepository["Service"]["recordImportedTranscript"] =
+    (input) =>
+      recordImportedTranscriptRow(input).pipe(
+        Effect.mapError(
+          toPersistenceSqlOrDecodeError(
+            "ProviderSessionRuntimeRepository.recordImportedTranscript:query",
+            "ProviderSessionRuntimeRepository.recordImportedTranscript:encodeRequest",
+            { threadId: input.threadId },
+          ),
+        ),
+      );
+
   const getByThreadId: ProviderSessionRuntimeRepository["Service"]["getByThreadId"] = (input) =>
     getRuntimeRowByThreadId(input).pipe(
       Effect.mapError(
@@ -324,6 +464,7 @@ export const make = Effect.gen(function* () {
 
   return {
     upsert,
+    recordImportedTranscript,
     getByThreadId,
     list,
     deleteByThreadId,
diff --git a/apps/server/src/persistence/Services/OrchestrationEventStore.ts b/apps/server/src/persistence/Services/OrchestrationEventStore.ts
index b865957c06b3..3e131b068b01 100644
--- a/apps/server/src/persistence/Services/OrchestrationEventStore.ts
+++ b/apps/server/src/persistence/Services/OrchestrationEventStore.ts
@@ -16,6 +16,20 @@ import type * as Stream from "effect/Stream";
 
 import type { OrchestrationEventStoreError } from "../Errors.ts";
 
+export interface OrchestrationAggregateReplayRange {
+  readonly aggregateKind: OrchestrationEvent["aggregateKind"];
+  readonly aggregateId: string;
+  readonly fromSequenceExclusive: number;
+  readonly toSequenceInclusive: number;
+}
+
+export interface OrchestrationAggregateReplayStats {
+  readonly eventCount: number;
+  readonly payloadBytes: number;
+  /** A creation in this range does not prove that the aggregate still exists. */
+  readonly hasCreateEvent: boolean;
+}
+
 /**
  * OrchestrationEventStoreShape - Service API for orchestration event persistence.
  */
@@ -46,6 +60,19 @@ export interface OrchestrationEventStoreShape {
     limit?: number,
   ) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError>;
 
+  /** Read one aggregate through a captured global head, without decoding other streams. */
+  readonly readAggregateRange: (
+    input: OrchestrationAggregateReplayRange & { readonly limit?: number },
+  ) => Stream.Stream<OrchestrationEvent, OrchestrationEventStoreError>;
+
+  /**
+   * Measure at most maxEvents + 1 rows without decoding payloads. The extra
+   * row tells the caller to use a snapshot instead of a truncated replay.
+   */
+  readonly getAggregateReplayStats: (
+    input: OrchestrationAggregateReplayRange & { readonly maxEvents: number },
+  ) => Effect.Effect<OrchestrationAggregateReplayStats, OrchestrationEventStoreError>;
+
   /**
    * Read all events from the beginning of the stream.
    *
diff --git a/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts b/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts
index 40b0d1ae03b6..43a829de6390 100644
--- a/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts
+++ b/apps/server/src/persistence/Services/ProjectionPendingApprovals.ts
@@ -69,6 +69,11 @@ export interface ProjectionPendingApprovalRepositoryShape {
     input: ListProjectionPendingApprovalsInput,
   ) => Effect.Effect<ReadonlyArray<ProjectionPendingApproval>, ProjectionRepositoryError>;
 
+  /** Count pending approvals without loading resolved request history. */
+  readonly countPendingByThreadId: (
+    input: ListProjectionPendingApprovalsInput,
+  ) => Effect.Effect<number, ProjectionRepositoryError>;
+
   /**
    * Read a pending approval row by request id.
    */
diff --git a/apps/server/src/persistence/Services/ProjectionState.ts b/apps/server/src/persistence/Services/ProjectionState.ts
index ba1ca1517368..9372acdeeb65 100644
--- a/apps/server/src/persistence/Services/ProjectionState.ts
+++ b/apps/server/src/persistence/Services/ProjectionState.ts
@@ -37,6 +37,11 @@ export interface ProjectionStateRepositoryShape {
    */
   readonly upsert: (row: ProjectionState) => Effect.Effect<void, ProjectionRepositoryError>;
 
+  /** Insert or replace projector cursors in one statement. Empty batches do nothing. */
+  readonly upsertMany: (
+    rows: ReadonlyArray<ProjectionState>,
+  ) => Effect.Effect<void, ProjectionRepositoryError>;
+
   /**
    * Read projection cursor state for a projector key.
    */
diff --git a/apps/server/src/persistence/Services/ProjectionThreadMessages.ts b/apps/server/src/persistence/Services/ProjectionThreadMessages.ts
index 17b659a2f8da..a41737564382 100644
--- a/apps/server/src/persistence/Services/ProjectionThreadMessages.ts
+++ b/apps/server/src/persistence/Services/ProjectionThreadMessages.ts
@@ -90,6 +90,11 @@ export interface ProjectionThreadMessageRepositoryShape {
     input: ListProjectionThreadMessagesInput,
   ) => Effect.Effect<ReadonlyArray<ProjectionThreadMessage>, ProjectionRepositoryError>;
 
+  /** Read the latest user-message timestamp without loading message bodies. */
+  readonly getLatestUserMessageAt: (
+    input: ListProjectionThreadMessagesInput,
+  ) => Effect.Effect<ProjectionThreadMessage["createdAt"] | null, ProjectionRepositoryError>;
+
   /**
    * Delete projected thread messages by thread.
    */
diff --git a/apps/server/src/process/externalLauncher.test.ts b/apps/server/src/process/externalLauncher.test.ts
index 030453e2f06f..2ae1684b67d4 100644
--- a/apps/server/src/process/externalLauncher.test.ts
+++ b/apps/server/src/process/externalLauncher.test.ts
@@ -20,6 +20,12 @@ import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { SpawnExecutableResolution } from "@t3tools/shared/shell";
 import * as ExternalLauncher from "./externalLauncher.ts";
 
+// Tests below write `#!/bin/sh` stubs into a real temp dir and hand that
+// directory to a posix-mocked resolver as PATH. On a Windows host the temp
+// path carries a drive letter, so the posix `:` split shatters it; there is
+// no posix executable to find there anyway.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 interface MockSpawnResult {
   readonly exitCode?: number;
   readonly stdout?: string;
@@ -153,7 +159,7 @@ it.effect("launches an installed editor with platform-safe arguments", () =>
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("reveals a file in Finder with open -R on macOS", () =>
+it.effect.skipIf(windowsHost)("reveals a file in Finder with open -R on macOS", () =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -336,196 +342,208 @@ it.effect("does not advertise reveal on Windows when PowerShell is missing", ()
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("reveals a WSL file in Windows File Explorer through its UNC path", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["explorer.exe", "powershell.exe", "xdg-open"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "reveals a WSL file in Windows File Explorer through its UNC path",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["explorer.exe", "powershell.exe", "xdg-open"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    let spawned: ChildProcess.StandardCommand | undefined;
-    const result = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      const kind = yield* launcher.resolveFileManagerRevealKind();
-      const editors = yield* launcher.resolveAvailableEditors();
-      yield* launcher.launchEditor({
-        editor: "file-manager",
-        cwd: "/home/t3/workspace/media/clip.mp4",
-        reveal: true,
-      });
-      return { kind, editors };
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: {
-            PATH: binDir,
-            WSL_DISTRO_NAME: "Ubuntu-24.04",
-            WSL_INTEROP: "/run/WSL/1_interop",
-          },
-          onSpawn: (command) => {
-            spawned = command;
-          },
-        }),
-      ),
-    );
+      let spawned: ChildProcess.StandardCommand | undefined;
+      const result = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        const kind = yield* launcher.resolveFileManagerRevealKind();
+        const editors = yield* launcher.resolveAvailableEditors();
+        yield* launcher.launchEditor({
+          editor: "file-manager",
+          cwd: "/home/t3/workspace/media/clip.mp4",
+          reveal: true,
+        });
+        return { kind, editors };
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: {
+              PATH: binDir,
+              WSL_DISTRO_NAME: "Ubuntu-24.04",
+              WSL_INTEROP: "/run/WSL/1_interop",
+            },
+            onSpawn: (command) => {
+              spawned = command;
+            },
+          }),
+        ),
+      );
 
-    assert.equal(result.kind, "file-explorer");
-    assert.equal(result.editors.includes("file-manager"), true);
-    assert.ok(spawned);
-    // The reveal routes through interop PowerShell so Explorer receives its
-    // raw `/select,"<path>"` switch even for spaced paths.
-    assert.equal(spawned.command, "powershell.exe");
-    const encodedCommand = spawned.args[spawned.args.length - 1] ?? "";
-    const decodedCommand = Buffer.from(encodedCommand, "base64").toString("utf16le");
-    assert.equal(
-      decodedCommand,
-      "$ProgressPreference = 'SilentlyContinue'; Start-Process 'explorer.exe' -ArgumentList ('/select,\"' + '\\\\wsl.localhost\\Ubuntu-24.04\\home\\t3\\workspace\\media\\clip.mp4' + '\"')",
-    );
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(result.kind, "file-explorer");
+      assert.equal(result.editors.includes("file-manager"), true);
+      assert.ok(spawned);
+      // The reveal routes through interop PowerShell so Explorer receives its
+      // raw `/select,"<path>"` switch even for spaced paths.
+      assert.equal(spawned.command, "powershell.exe");
+      const encodedCommand = spawned.args[spawned.args.length - 1] ?? "";
+      const decodedCommand = Buffer.from(encodedCommand, "base64").toString("utf16le");
+      assert.equal(
+        decodedCommand,
+        "$ProgressPreference = 'SilentlyContinue'; Start-Process 'explorer.exe' -ArgumentList ('/select,\"' + '\\\\wsl.localhost\\Ubuntu-24.04\\home\\t3\\workspace\\media\\clip.mp4' + '\"')",
+      );
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("does not advertise reveal from WSL when interop PowerShell is missing", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    const explorerPath = path.join(binDir, "explorer.exe");
-    yield* fileSystem.writeFileString(explorerPath, "");
-    yield* fileSystem.chmod(explorerPath, 0o755);
+it.effect.skipIf(windowsHost)(
+  "does not advertise reveal from WSL when interop PowerShell is missing",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      const explorerPath = path.join(binDir, "explorer.exe");
+      yield* fileSystem.writeFileString(explorerPath, "");
+      yield* fileSystem.chmod(explorerPath, 0o755);
 
-    const result = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return {
-        kind: yield* launcher.resolveFileManagerRevealKind(),
-        editors: yield* launcher.resolveAvailableEditors(),
-      };
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: {
-            PATH: binDir,
-            WSL_DISTRO_NAME: "Ubuntu-24.04",
-            WSL_INTEROP: "/run/WSL/1_interop",
-          },
-        }),
-      ),
-    );
+      const result = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return {
+          kind: yield* launcher.resolveFileManagerRevealKind(),
+          editors: yield* launcher.resolveAvailableEditors(),
+        };
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: {
+              PATH: binDir,
+              WSL_DISTRO_NAME: "Ubuntu-24.04",
+              WSL_INTEROP: "/run/WSL/1_interop",
+            },
+          }),
+        ),
+      );
 
-    assert.equal(result.editors.includes("file-manager"), true);
-    assert.isUndefined(result.kind);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(result.editors.includes("file-manager"), true);
+      assert.isUndefined(result.kind);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 // When interop PowerShell is missing the capability advertises the Linux
 // "files" kind (or nothing), so the reveal must open the Linux file manager
 // the label promised even though plain open still prefers File Explorer.
-it.effect("reveals through the Linux file manager when WSL lacks interop PowerShell", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["explorer.exe", "xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "reveals through the Linux file manager when WSL lacks interop PowerShell",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["explorer.exe", "xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    const spawnedCommands: ChildProcess.StandardCommand[] = [];
-    const kind = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      const revealKind = yield* launcher.resolveFileManagerRevealKind();
-      yield* launcher.launchEditor({
-        editor: "file-manager",
-        cwd: "/home/t3/workspace/media/clip.mp4",
-        reveal: true,
-      });
-      return revealKind;
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: {
-            PATH: binDir,
-            WSL_DISTRO_NAME: "Ubuntu-24.04",
-            WSL_INTEROP: "/run/WSL/1_interop",
-            DISPLAY: ":0",
-          },
-          onSpawn: (command) => {
-            spawnedCommands.push(command);
-          },
-          spawnResult: (command) =>
-            command.command === "xdg-mime" ? { stdout: "org.gnome.Nautilus.desktop\n" } : undefined,
-        }),
-      ),
-    );
+      const spawnedCommands: ChildProcess.StandardCommand[] = [];
+      const kind = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        const revealKind = yield* launcher.resolveFileManagerRevealKind();
+        yield* launcher.launchEditor({
+          editor: "file-manager",
+          cwd: "/home/t3/workspace/media/clip.mp4",
+          reveal: true,
+        });
+        return revealKind;
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: {
+              PATH: binDir,
+              WSL_DISTRO_NAME: "Ubuntu-24.04",
+              WSL_INTEROP: "/run/WSL/1_interop",
+              DISPLAY: ":0",
+            },
+            onSpawn: (command) => {
+              spawnedCommands.push(command);
+            },
+            spawnResult: (command) =>
+              command.command === "xdg-mime"
+                ? { stdout: "org.gnome.Nautilus.desktop\n" }
+                : undefined,
+          }),
+        ),
+      );
 
-    assert.equal(kind, "files");
-    const launch = spawnedCommands.find((command) => command.command === "xdg-open");
-    assert.ok(launch);
-    assert.deepEqual(launch.args, ["/home/t3/workspace/media"]);
-    assert.isUndefined(spawnedCommands.find((command) => command.command === "explorer.exe"));
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(kind, "files");
+      const launch = spawnedCommands.find((command) => command.command === "xdg-open");
+      assert.ok(launch);
+      assert.deepEqual(launch.args, ["/home/t3/workspace/media"]);
+      assert.isUndefined(spawnedCommands.find((command) => command.command === "explorer.exe"));
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 // Interop can exist without `explorer.exe` on PATH (appendWindowsPath=false)
 // while WSLg still provides a working Linux file manager; the host must keep
 // the Linux open/reveal path instead of losing the editor entirely.
-it.effect("falls back to the Linux file manager when WSL lacks the Explorer bridge", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "falls back to the Linux file manager when WSL lacks the Explorer bridge",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    const spawnedCommands: ChildProcess.StandardCommand[] = [];
-    const result = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      const editors = yield* launcher.resolveAvailableEditors();
-      const kind = yield* launcher.resolveFileManagerRevealKind();
-      yield* launcher.launchEditor({
-        editor: "file-manager",
-        cwd: "/home/t3/workspace/media/clip.mp4",
-        reveal: true,
-      });
-      return { editors, kind };
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: {
-            PATH: binDir,
-            WSL_DISTRO_NAME: "Ubuntu-24.04",
-            WSL_INTEROP: "/run/WSL/1_interop",
-            DISPLAY: ":0",
-          },
-          onSpawn: (command) => {
-            spawnedCommands.push(command);
-          },
-          spawnResult: (command) =>
-            command.command === "xdg-mime" ? { stdout: "org.gnome.Nautilus.desktop\n" } : undefined,
-        }),
-      ),
-    );
+      const spawnedCommands: ChildProcess.StandardCommand[] = [];
+      const result = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        const editors = yield* launcher.resolveAvailableEditors();
+        const kind = yield* launcher.resolveFileManagerRevealKind();
+        yield* launcher.launchEditor({
+          editor: "file-manager",
+          cwd: "/home/t3/workspace/media/clip.mp4",
+          reveal: true,
+        });
+        return { editors, kind };
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: {
+              PATH: binDir,
+              WSL_DISTRO_NAME: "Ubuntu-24.04",
+              WSL_INTEROP: "/run/WSL/1_interop",
+              DISPLAY: ":0",
+            },
+            onSpawn: (command) => {
+              spawnedCommands.push(command);
+            },
+            spawnResult: (command) =>
+              command.command === "xdg-mime"
+                ? { stdout: "org.gnome.Nautilus.desktop\n" }
+                : undefined,
+          }),
+        ),
+      );
 
-    assert.equal(result.editors.includes("file-manager"), true);
-    assert.equal(result.kind, "files");
-    const launch = spawnedCommands.find((command) => command.command === "xdg-open");
-    assert.ok(launch);
-    assert.deepEqual(launch.args, ["/home/t3/workspace/media"]);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(result.editors.includes("file-manager"), true);
+      assert.equal(result.kind, "files");
+      const launch = spawnedCommands.find((command) => command.command === "xdg-open");
+      assert.ok(launch);
+      assert.deepEqual(launch.args, ["/home/t3/workspace/media"]);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect(
+it.effect.skipIf(windowsHost)(
   "falls back to opening the containing directory for WSL paths Explorer cannot select",
   () =>
     Effect.gen(function* () {
@@ -570,7 +588,7 @@ it.effect(
     }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("reveals by opening the containing directory on Linux", () =>
+it.effect.skipIf(windowsHost)("reveals by opening the containing directory on Linux", () =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -609,127 +627,137 @@ it.effect("reveals by opening the containing directory on Linux", () =>
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("does not advertise a Linux file manager without a graphical session", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    const xdgOpenPath = path.join(binDir, "xdg-open");
-    yield* fileSystem.writeFileString(xdgOpenPath, "#!/bin/sh\n");
-    yield* fileSystem.chmod(xdgOpenPath, 0o755);
+it.effect.skipIf(windowsHost)(
+  "does not advertise a Linux file manager without a graphical session",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      const xdgOpenPath = path.join(binDir, "xdg-open");
+      yield* fileSystem.writeFileString(xdgOpenPath, "#!/bin/sh\n");
+      yield* fileSystem.chmod(xdgOpenPath, 0o755);
 
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(Effect.provide(testLayer({ platform: "linux", env: { PATH: binDir } })));
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(Effect.provide(testLayer({ platform: "linux", env: { PATH: binDir } })));
 
-    assert.equal(editors.includes("file-manager"), false);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), false);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("advertises a Linux file manager when a directory handler is installed", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "advertises a Linux file manager when a directory handler is installed",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    let probe: ChildProcess.StandardCommand | undefined;
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: { PATH: binDir, DISPLAY: ":0" },
-          onSpawn: (command) => {
-            probe = command;
-          },
-          spawnResult: (command) =>
-            command.command === "xdg-mime" ? { stdout: "org.gnome.Nautilus.desktop\n" } : undefined,
-        }),
-      ),
-    );
+      let probe: ChildProcess.StandardCommand | undefined;
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: { PATH: binDir, DISPLAY: ":0" },
+            onSpawn: (command) => {
+              probe = command;
+            },
+            spawnResult: (command) =>
+              command.command === "xdg-mime"
+                ? { stdout: "org.gnome.Nautilus.desktop\n" }
+                : undefined,
+          }),
+        ),
+      );
 
-    assert.equal(editors.includes("file-manager"), true);
-    assert.ok(probe);
-    assert.equal(probe.command, "xdg-mime");
-    assert.deepEqual(probe.args, ["query", "default", "inode/directory"]);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), true);
+      assert.ok(probe);
+      assert.equal(probe.command, "xdg-mime");
+      assert.deepEqual(probe.args, ["query", "default", "inode/directory"]);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 // `xdg-open` with a display variable but no `inode/directory` handler exits
 // nonzero after the launch has already detached: without this gate the server
 // advertises a reveal that is a silent no-op.
-it.effect("does not advertise a Linux file manager without a directory handler", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "does not advertise a Linux file manager without a directory handler",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: { PATH: binDir, DISPLAY: ":0" },
-          spawnResult: (command) => (command.command === "xdg-mime" ? { stdout: "" } : undefined),
-        }),
-      ),
-    );
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: { PATH: binDir, DISPLAY: ":0" },
+            spawnResult: (command) => (command.command === "xdg-mime" ? { stdout: "" } : undefined),
+          }),
+        ),
+      );
 
-    assert.equal(editors.includes("file-manager"), false);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), false);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("does not advertise a Linux file manager when the handler query fails", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    for (const name of ["xdg-open", "xdg-mime"]) {
-      const filePath = path.join(binDir, name);
-      yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
-      yield* fileSystem.chmod(filePath, 0o755);
-    }
+it.effect.skipIf(windowsHost)(
+  "does not advertise a Linux file manager when the handler query fails",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      for (const name of ["xdg-open", "xdg-mime"]) {
+        const filePath = path.join(binDir, name);
+        yield* fileSystem.writeFileString(filePath, "#!/bin/sh\n");
+        yield* fileSystem.chmod(filePath, 0o755);
+      }
 
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(
-      Effect.provide(
-        testLayer({
-          platform: "linux",
-          env: { PATH: binDir, DISPLAY: ":0" },
-          spawnResult: (command) =>
-            command.command === "xdg-mime"
-              ? { exitCode: 47, stdout: "org.gnome.Nautilus.desktop\n" }
-              : undefined,
-        }),
-      ),
-    );
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(
+        Effect.provide(
+          testLayer({
+            platform: "linux",
+            env: { PATH: binDir, DISPLAY: ":0" },
+            spawnResult: (command) =>
+              command.command === "xdg-mime"
+                ? { exitCode: 47, stdout: "org.gnome.Nautilus.desktop\n" }
+                : undefined,
+          }),
+        ),
+      );
 
-    assert.equal(editors.includes("file-manager"), false);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), false);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 // The handler probe carries its own timeout because the editor scan's outer
 // timeout in server.getConfig degrades to an EMPTY editor list: a wedged
 // xdg-mime must cost only the file manager, never the other editors. Runs on
 // the live clock so the probe's real timeout fires.
-it.live("a stalled handler probe drops only the file manager", () =>
+it.live.skipIf(windowsHost)("a stalled handler probe drops only the file manager", () =>
   Effect.gen(function* () {
     const fileSystem = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -758,22 +786,26 @@ it.live("a stalled handler probe drops only the file manager", () =>
   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
-it.effect("does not advertise a Linux file manager when xdg-mime is missing", () =>
-  Effect.gen(function* () {
-    const fileSystem = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
-    const xdgOpenPath = path.join(binDir, "xdg-open");
-    yield* fileSystem.writeFileString(xdgOpenPath, "#!/bin/sh\n");
-    yield* fileSystem.chmod(xdgOpenPath, 0o755);
+it.effect.skipIf(windowsHost)(
+  "does not advertise a Linux file manager when xdg-mime is missing",
+  () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const binDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-editors-" });
+      const xdgOpenPath = path.join(binDir, "xdg-open");
+      yield* fileSystem.writeFileString(xdgOpenPath, "#!/bin/sh\n");
+      yield* fileSystem.chmod(xdgOpenPath, 0o755);
 
-    const editors = yield* Effect.gen(function* () {
-      const launcher = yield* ExternalLauncher.ExternalLauncher;
-      return yield* launcher.resolveAvailableEditors();
-    }).pipe(Effect.provide(testLayer({ platform: "linux", env: { PATH: binDir, DISPLAY: ":0" } })));
+      const editors = yield* Effect.gen(function* () {
+        const launcher = yield* ExternalLauncher.ExternalLauncher;
+        return yield* launcher.resolveAvailableEditors();
+      }).pipe(
+        Effect.provide(testLayer({ platform: "linux", env: { PATH: binDir, DISPLAY: ":0" } })),
+      );
 
-    assert.equal(editors.includes("file-manager"), false);
-  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+      assert.equal(editors.includes("file-manager"), false);
+    }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
 );
 
 it.effect("discovers editors through the service API", () =>
diff --git a/apps/server/src/project/AgentSessionImporter.test.ts b/apps/server/src/project/AgentSessionImporter.test.ts
new file mode 100644
index 000000000000..38d6ad1d4331
--- /dev/null
+++ b/apps/server/src/project/AgentSessionImporter.test.ts
@@ -0,0 +1,1213 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it, vi } from "@effect/vitest";
+import {
+  AgentSessionImportProjectChangedError,
+  CommandId,
+  MessageId,
+  ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  ThreadId,
+  type OrchestrationCommand,
+  type OrchestrationProjectShell,
+  type OrchestrationThread,
+  type ProviderSendTurnInput,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+
+import { makeTestProviderAdapterHarness } from "../../integration/TestProviderAdapter.integration.ts";
+import { ServerConfig } from "../config.ts";
+import { GitWorkflowService } from "../git/GitWorkflowService.ts";
+import { OrchestrationCommandReceiptRepositoryLive } from "../persistence/Layers/OrchestrationCommandReceipts.ts";
+import { OrchestrationEventStoreLive } from "../persistence/Layers/OrchestrationEventStore.ts";
+import { SqlitePersistenceMemory } from "../persistence/Layers/Sqlite.ts";
+import * as ProviderSessionRuntime from "../persistence/ProviderSessionRuntime.ts";
+import { OrchestrationEngineLive } from "../orchestration/Layers/OrchestrationEngine.ts";
+import { OrchestrationProjectionPipelineLive } from "../orchestration/Layers/ProjectionPipeline.ts";
+import { OrchestrationProjectionSnapshotQueryLive } from "../orchestration/Layers/ProjectionSnapshotQuery.ts";
+import { ProviderCommandReactorLive } from "../orchestration/Layers/ProviderCommandReactor.ts";
+import { OrchestrationCommandInvariantError } from "../orchestration/Errors.ts";
+import * as ThreadBackgroundLiveness from "../orchestration/ThreadBackgroundLiveness.ts";
+import * as ThreadPlanProgress from "../orchestration/ThreadPlanProgress.ts";
+import * as OrchestrationEngine from "../orchestration/Services/OrchestrationEngine.ts";
+import * as ProjectionSnapshotQuery from "../orchestration/Services/ProjectionSnapshotQuery.ts";
+import { ProviderCommandReactor } from "../orchestration/Services/ProviderCommandReactor.ts";
+import { ProviderSessionDirectoryLive } from "../provider/Layers/ProviderSessionDirectory.ts";
+import { makeProviderServiceLive } from "../provider/Layers/ProviderService.ts";
+import {
+  NoOpProviderEventLoggers,
+  ProviderEventLoggers,
+} from "../provider/Layers/ProviderEventLoggers.ts";
+import { ProviderSessionDirectoryPersistenceError } from "../provider/Errors.ts";
+import { ProviderAdapterRegistry } from "../provider/Services/ProviderAdapterRegistry.ts";
+import { ProviderAuthService } from "../provider/Services/ProviderAuthService.ts";
+import * as ProviderSessionDirectory from "../provider/Services/ProviderSessionDirectory.ts";
+import { makeAdapterRegistryMock } from "../provider/testUtils/providerAdapterRegistryMock.ts";
+import { makeProviderRegistryLayer } from "../provider/testUtils/providerRegistryMock.ts";
+import { ServerSettingsService } from "../serverSettings.ts";
+import * as AnalyticsService from "../telemetry/AnalyticsService.ts";
+import { TextGeneration } from "../textGeneration/TextGeneration.ts";
+import { VcsStatusBroadcaster } from "../vcs/VcsStatusBroadcaster.ts";
+import * as RepositoryIdentityResolver from "./RepositoryIdentityResolver.ts";
+import { importRecentAgentThreads } from "./AgentSessionImporter.ts";
+import * as AgentSessionScanner from "./AgentSessionScanner.ts";
+
+const PROJECT_ID = ProjectId.make("project-1");
+const WORKSPACE_ROOT = "/tmp/project-from-server";
+const CLAUDE_SESSION_ID = "123e4567-e89b-42d3-a456-426614174000";
+const encodeTranscriptRecord = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
+
+const makeThread = (source: "codex" | "claudeAgent"): AgentSessionScanner.AgentSessionThread => ({
+  source,
+  providerInstanceId: ProviderInstanceId.make(source),
+  providerSessionId: source === "codex" ? "codex-session" : CLAUDE_SESSION_ID,
+  title: `Imported ${source} thread`,
+  model: null,
+  createdAt: "2026-08-24T10:00:00.000Z",
+  updatedAt: "2026-08-24T10:01:00.000Z",
+  messages: [
+    { role: "user", text: "Fix the bug", createdAt: "2026-08-24T10:00:00.000Z" },
+    { role: "assistant", text: "Fixed", createdAt: "2026-08-24T10:01:00.000Z" },
+  ],
+});
+
+const makeThreadOutcome = (thread: AgentSessionScanner.AgentSessionThread) =>
+  ({
+    _tag: "Importable",
+    thread,
+    source: {
+      provider: thread.source,
+      providerInstanceId: thread.providerInstanceId,
+      providerSessionId: thread.providerSessionId,
+      filePath: `/tmp/transcripts/${thread.providerInstanceId}/${thread.providerSessionId}.jsonl`,
+      size: 0,
+      mtimeMs: 0,
+      device: 0,
+      inode: 0,
+      birthtimeMs: 0,
+    },
+  }) satisfies AgentSessionScanner.AgentSessionRecentThread;
+
+const makeProject = (): OrchestrationProjectShell => ({
+  id: PROJECT_ID,
+  title: "Project",
+  workspaceRoot: WORKSPACE_ROOT,
+  defaultModelSelection: null,
+  scripts: [],
+  createdAt: "2026-08-24T09:00:00.000Z",
+  updatedAt: "2026-08-24T09:00:00.000Z",
+});
+
+const makeProjectedThread = (input: {
+  readonly source: "codex" | "claudeAgent";
+  readonly projectId?: ProjectId;
+  readonly imported?: boolean;
+  readonly includeFollowup?: boolean;
+}): OrchestrationThread => {
+  const sourceThread = makeThread(input.source);
+  const threadId = ThreadId.make(
+    `import:${sourceThread.providerInstanceId}:${sourceThread.providerSessionId}`,
+  );
+  return {
+    id: threadId,
+    projectId: input.projectId ?? PROJECT_ID,
+    title: sourceThread.title,
+    modelSelection: { instanceId: sourceThread.providerInstanceId, model: "default" },
+    runtimeMode: "full-access",
+    interactionMode: "default",
+    branch: null,
+    worktreePath: null,
+    latestTurn: null,
+    createdAt: sourceThread.createdAt,
+    updatedAt: sourceThread.updatedAt,
+    archivedAt: null,
+    settledOverride: null,
+    settledAt: null,
+    deletedAt: null,
+    messages: input.imported
+      ? [
+          {
+            id: MessageId.make(`${threadId}:000000`),
+            role: "user",
+            text: "Fix the bug",
+            turnId: null,
+            streaming: false,
+            createdAt: "2026-08-24T10:00:00.000Z",
+            updatedAt: "2026-08-24T10:00:00.000Z",
+          },
+          ...(input.includeFollowup
+            ? [
+                {
+                  id: MessageId.make("user-followup"),
+                  role: "user" as const,
+                  text: "Keep going",
+                  turnId: null,
+                  streaming: false,
+                  createdAt: "2026-08-24T10:02:00.000Z",
+                  updatedAt: "2026-08-24T10:02:00.000Z",
+                },
+              ]
+            : []),
+        ]
+      : [],
+    proposedPlans: [],
+    activities: [],
+    checkpoints: [],
+    session: null,
+  };
+};
+
+const makeSnapshotsLayer = (input: {
+  readonly project?: OrchestrationProjectShell;
+  readonly getThread?: (threadId: ThreadId) => Option.Option<OrchestrationThread>;
+}) =>
+  Layer.mock(ProjectionSnapshotQuery.ProjectionSnapshotQuery)({
+    getProjectShellById: () =>
+      Effect.succeed(input.project === undefined ? Option.none() : Option.some(input.project)),
+    getImportedAgentSessionSources: () => Effect.succeed([]),
+    getThreadDetailById: (threadId) => Effect.succeed(input.getThread?.(threadId) ?? Option.none()),
+  });
+
+const runImport = (input: {
+  readonly scanner: AgentSessionScanner.AgentSessionScanner["Service"];
+  readonly engine: OrchestrationEngine.OrchestrationEngineService["Service"];
+  readonly directory: ProviderSessionDirectory.ProviderSessionDirectory["Service"];
+  readonly snapshots: ReturnType<typeof makeSnapshotsLayer>;
+  readonly expectedWorkspaceRoot?: string;
+}) =>
+  importRecentAgentThreads({
+    projectId: PROJECT_ID,
+    ...(input.expectedWorkspaceRoot === undefined
+      ? {}
+      : { expectedWorkspaceRoot: input.expectedWorkspaceRoot }),
+  }).pipe(
+    Effect.provideService(AgentSessionScanner.AgentSessionScanner, input.scanner),
+    Effect.provideService(OrchestrationEngine.OrchestrationEngineService, input.engine),
+    Effect.provideService(ProviderSessionDirectory.ProviderSessionDirectory, input.directory),
+    Effect.provide(input.snapshots),
+  );
+
+it.layer(NodeServices.layer)("AgentSessionImporter", (it) => {
+  describe("importRecentAgentThreads", () => {
+    it.effect("uses the project root and stores provider-specific resume cursors", () =>
+      Effect.gen(function* () {
+        const commands: Array<OrchestrationCommand> = [];
+        const bindings: Array<ProviderSessionDirectory.ProviderRuntimeBinding> = [];
+        let scannedRoot: string | undefined;
+        const scanner = AgentSessionScanner.AgentSessionScanner.of({
+          scan: Effect.die("unused"),
+          recentThreads: (workspaceRoot) => {
+            scannedRoot = workspaceRoot;
+            return Stream.concat(
+              Stream.succeed(makeThreadOutcome(makeThread("codex"))),
+              Stream.fromEffect(
+                Effect.sync(() => {
+                  expect(bindings).toHaveLength(1);
+                  return makeThreadOutcome(makeThread("claudeAgent"));
+                }),
+              ),
+            );
+          },
+        });
+        const engine = OrchestrationEngine.OrchestrationEngineService.of({
+          dispatch: (command) => Effect.sync(() => ({ sequence: commands.push(command) })),
+          readEvents: () => Stream.empty,
+          readThreadEvents: () => Stream.empty,
+          getThreadReplayStats: () => Effect.die("unused"),
+          streamDomainEvents: Stream.empty,
+          subscribeDomainEvents: Effect.succeed(Stream.empty),
+          latestSequence: Effect.succeed(0),
+        });
+        const directory = ProviderSessionDirectory.ProviderSessionDirectory.of({
+          upsert: (binding) => Effect.sync(() => void bindings.push(binding)),
+          getProvider: () => Effect.die("unused"),
+          recordImportedTranscript: () => Effect.void,
+          getBinding: () => Effect.succeed(Option.none()),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () => Effect.die("unused"),
+        });
+
+        const result = yield* runImport({
+          scanner,
+          engine,
+          directory,
+          snapshots: makeSnapshotsLayer({ project: makeProject() }),
+          expectedWorkspaceRoot: `${WORKSPACE_ROOT}/`,
+        });
+
+        expect(result).toEqual({ importedCount: 2, skippedCount: 0 });
+        expect(scannedRoot).toBe(WORKSPACE_ROOT);
+        expect(commands.map((command) => command.type)).toEqual([
+          "thread.create",
+          "thread.history.import",
+          "thread.create",
+          "thread.history.import",
+        ]);
+        expect(commands.filter((command) => command.type === "thread.create")).toMatchObject([
+          { historyImport: true },
+          { historyImport: true },
+        ]);
+        expect(
+          commands
+            .filter((command) => command.type === "thread.history.import")
+            .flatMap((command) => command.messages.map((message) => message.messageId)),
+        ).toEqual([
+          "import:codex:codex-session:000000",
+          "import:codex:codex-session:000001",
+          `import:claudeAgent:${CLAUDE_SESSION_ID}:000000`,
+          `import:claudeAgent:${CLAUDE_SESSION_ID}:000001`,
+        ]);
+        expect(bindings).toMatchObject([
+          {
+            provider: "codex",
+            providerInstanceId: "codex",
+            resumeCursor: { threadId: "codex-session" },
+            runtimePayload: { cwd: WORKSPACE_ROOT },
+          },
+          {
+            provider: "claudeAgent",
+            providerInstanceId: "claudeAgent",
+            resumeCursor: {
+              threadId: `import:claudeAgent:${CLAUDE_SESSION_ID}`,
+              resume: CLAUDE_SESSION_ID,
+            },
+            runtimePayload: { cwd: WORKSPACE_ROOT },
+          },
+        ]);
+      }),
+    );
+
+    it.effect("rejects a changed project root before scanning or writing", () =>
+      Effect.gen(function* () {
+        const recentThreads = vi.fn(() => Stream.empty);
+        const error = yield* importRecentAgentThreads({
+          projectId: PROJECT_ID,
+          expectedWorkspaceRoot: WORKSPACE_ROOT,
+        }).pipe(
+          Effect.provideService(
+            AgentSessionScanner.AgentSessionScanner,
+            AgentSessionScanner.AgentSessionScanner.of({
+              scan: Effect.die("must not scan a changed project"),
+              recentThreads,
+            }),
+          ),
+          Effect.provide(
+            Layer.mergeAll(
+              Layer.mock(OrchestrationEngine.OrchestrationEngineService)({}),
+              Layer.mock(ProviderSessionDirectory.ProviderSessionDirectory)({}),
+              makeSnapshotsLayer({
+                project: { ...makeProject(), workspaceRoot: "/tmp/project-moved" },
+              }),
+            ),
+          ),
+          Effect.flip,
+        );
+
+        expect(error).toEqual(new AgentSessionImportProjectChangedError({ projectId: PROJECT_ID }));
+        expect(recentThreads).not.toHaveBeenCalled();
+      }),
+    );
+
+    it.effect("counts scanner skips without writing a thread or binding", () =>
+      Effect.gen(function* () {
+        const scanner = AgentSessionScanner.AgentSessionScanner.of({
+          scan: Effect.die("unused"),
+          recentThreads: () => Stream.succeed({ _tag: "Skipped" }),
+        });
+        const engine = OrchestrationEngine.OrchestrationEngineService.of({
+          dispatch: () => Effect.die("must not dispatch for a scanner skip"),
+          readEvents: () => Stream.empty,
+          readThreadEvents: () => Stream.empty,
+          getThreadReplayStats: () => Effect.die("unused"),
+          streamDomainEvents: Stream.empty,
+          subscribeDomainEvents: Effect.succeed(Stream.empty),
+          latestSequence: Effect.succeed(0),
+        });
+        const directory = ProviderSessionDirectory.ProviderSessionDirectory.of({
+          upsert: () => Effect.die("must not bind a scanner skip"),
+          getProvider: () => Effect.die("unused"),
+          recordImportedTranscript: () => Effect.die("unused"),
+          getBinding: () => Effect.die("must not read a scanner skip binding"),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () => Effect.die("unused"),
+        });
+
+        const result = yield* runImport({
+          scanner,
+          engine,
+          directory,
+          snapshots: makeSnapshotsLayer({ project: makeProject() }),
+        });
+
+        expect(result).toEqual({ importedCount: 0, skippedCount: 1 });
+      }),
+    );
+
+    it.effect("recovers after a rejected history receipt and a failed binding write", () =>
+      Effect.gen(function* () {
+        let threadCreated = false;
+        let historyImported = false;
+        let historyAttemptCount = 0;
+        let bindingAttemptCount = 0;
+        const rejectedCommandIds = new Set<string>();
+        const bindings: Array<ProviderSessionDirectory.ProviderRuntimeBinding> = [];
+        const scanner = AgentSessionScanner.AgentSessionScanner.of({
+          scan: Effect.die("unused"),
+          recentThreads: () => Stream.fromIterable([makeThreadOutcome(makeThread("codex"))]),
+        });
+        const engine = OrchestrationEngine.OrchestrationEngineService.of({
+          dispatch: (command) => {
+            if (rejectedCommandIds.has(command.commandId)) {
+              return Effect.fail(
+                new OrchestrationCommandInvariantError({
+                  commandType: command.type,
+                  detail: "Previously rejected.",
+                }),
+              );
+            }
+            if (command.type === "thread.create") threadCreated = true;
+            if (command.type === "thread.history.import") {
+              historyAttemptCount += 1;
+              if (historyAttemptCount === 1) {
+                rejectedCommandIds.add(command.commandId);
+                return Effect.fail(
+                  new OrchestrationCommandInvariantError({
+                    commandType: command.type,
+                    detail: "Temporary history import failure.",
+                  }),
+                );
+              }
+              historyImported = true;
+            }
+            return Effect.succeed({ sequence: 1 });
+          },
+          readEvents: () => Stream.empty,
+          readThreadEvents: () => Stream.empty,
+          getThreadReplayStats: () => Effect.die("unused"),
+          streamDomainEvents: Stream.empty,
+          subscribeDomainEvents: Effect.succeed(Stream.empty),
+          latestSequence: Effect.succeed(0),
+        });
+        const directory = ProviderSessionDirectory.ProviderSessionDirectory.of({
+          upsert: (binding) => {
+            bindingAttemptCount += 1;
+            if (bindingAttemptCount === 1) {
+              return Effect.fail(
+                new ProviderSessionDirectoryPersistenceError({
+                  operation: "upsert",
+                  detail: "Temporary session storage failure.",
+                }),
+              );
+            }
+            bindings.push(binding);
+            return Effect.void;
+          },
+          getProvider: () => Effect.die("unused"),
+          recordImportedTranscript: () => Effect.void,
+          getBinding: () =>
+            Effect.succeed(bindings[0] === undefined ? Option.none() : Option.some(bindings[0])),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () => Effect.die("unused"),
+        });
+        const snapshots = makeSnapshotsLayer({
+          project: makeProject(),
+          getThread: () =>
+            threadCreated
+              ? Option.some(makeProjectedThread({ source: "codex", imported: historyImported }))
+              : Option.none(),
+        });
+        const importOnce = () => runImport({ scanner, engine, directory, snapshots });
+
+        expect(yield* importOnce()).toEqual({ importedCount: 0, skippedCount: 1 });
+        expect(yield* importOnce()).toEqual({ importedCount: 0, skippedCount: 1 });
+        expect(yield* importOnce()).toEqual({ importedCount: 1, skippedCount: 0 });
+        const historyAttemptsAfterCompletion = historyAttemptCount;
+        expect(yield* importOnce()).toEqual({ importedCount: 1, skippedCount: 0 });
+        expect(historyAttemptCount).toBe(historyAttemptsAfterCompletion);
+        expect(historyAttemptCount).toBe(2);
+        expect(bindings).toHaveLength(1);
+      }),
+    );
+
+    it.effect("does not replace completed history or an active binding on retry", () =>
+      Effect.gen(function* () {
+        const scanner = AgentSessionScanner.AgentSessionScanner.of({
+          scan: Effect.die("unused"),
+          recentThreads: () => Stream.fromIterable([makeThreadOutcome(makeThread("codex"))]),
+        });
+        const runningBinding: ProviderSessionDirectory.ProviderRuntimeBinding = {
+          threadId: ThreadId.make("import:codex:codex-session"),
+          provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: ProviderInstanceId.make("codex"),
+          status: "running",
+          resumeCursor: { threadId: "newer-codex-session" },
+        };
+        const directory = ProviderSessionDirectory.ProviderSessionDirectory.of({
+          upsert: () => Effect.die("must not replace an active binding"),
+          getProvider: () => Effect.die("unused"),
+          recordImportedTranscript: () => Effect.void,
+          getBinding: () => Effect.succeed(Option.some(runningBinding)),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () => Effect.die("unused"),
+        });
+        const engine = OrchestrationEngine.OrchestrationEngineService.of({
+          dispatch: () => Effect.die("must not replay history or settle active work"),
+          readEvents: () => Stream.empty,
+          readThreadEvents: () => Stream.empty,
+          getThreadReplayStats: () => Effect.die("unused"),
+          streamDomainEvents: Stream.empty,
+          subscribeDomainEvents: Effect.succeed(Stream.empty),
+          latestSequence: Effect.succeed(0),
+        });
+
+        const result = yield* runImport({
+          scanner,
+          engine,
+          directory,
+          snapshots: makeSnapshotsLayer({
+            project: makeProject(),
+            getThread: () =>
+              Option.some(
+                makeProjectedThread({ source: "codex", imported: true, includeFollowup: true }),
+              ),
+          }),
+        });
+
+        expect(result).toEqual({ importedCount: 1, skippedCount: 0 });
+      }),
+    );
+
+    it.effect("skips malformed Claude ids and wrong-project thread collisions", () =>
+      Effect.gen(function* () {
+        const scanner = AgentSessionScanner.AgentSessionScanner.of({
+          scan: Effect.die("unused"),
+          recentThreads: () =>
+            Stream.fromIterable([
+              makeThreadOutcome({ ...makeThread("claudeAgent"), providerSessionId: "not-a-uuid" }),
+              makeThreadOutcome(makeThread("codex")),
+            ]),
+        });
+        const commands: Array<OrchestrationCommand> = [];
+        const engine = OrchestrationEngine.OrchestrationEngineService.of({
+          dispatch: (command) => Effect.sync(() => ({ sequence: commands.push(command) })),
+          readEvents: () => Stream.empty,
+          readThreadEvents: () => Stream.empty,
+          getThreadReplayStats: () => Effect.die("unused"),
+          streamDomainEvents: Stream.empty,
+          subscribeDomainEvents: Effect.succeed(Stream.empty),
+          latestSequence: Effect.succeed(0),
+        });
+        const directory = ProviderSessionDirectory.ProviderSessionDirectory.of({
+          upsert: () => Effect.die("must not bind malformed or wrong-project sessions"),
+          getProvider: () => Effect.die("unused"),
+          recordImportedTranscript: () => Effect.die("unused"),
+          getBinding: () => Effect.succeed(Option.none()),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () => Effect.die("unused"),
+        });
+
+        const result = yield* runImport({
+          scanner,
+          engine,
+          directory,
+          snapshots: makeSnapshotsLayer({
+            project: makeProject(),
+            getThread: (threadId) =>
+              threadId === "import:codex:codex-session"
+                ? Option.some(
+                    makeProjectedThread({
+                      source: "codex",
+                      projectId: ProjectId.make("project-other"),
+                    }),
+                  )
+                : Option.none(),
+          }),
+        });
+
+        expect(result).toEqual({ importedCount: 0, skippedCount: 2 });
+        expect(commands).toHaveLength(0);
+      }),
+    );
+  });
+});
+
+const integrationThread = {
+  ...makeThread("codex"),
+  updatedAt: "2026-08-24T10:00:00.000Z",
+  messages: Array.from({ length: 12 }, (_, index) => ({
+    role: index % 2 === 0 ? ("user" as const) : ("assistant" as const),
+    text: `Message ${index}`,
+    createdAt: "2026-08-24T10:00:00.000Z",
+  })),
+};
+const integrationScanner = AgentSessionScanner.AgentSessionScanner.of({
+  scan: Effect.die("unused"),
+  recentThreads: () => Stream.fromIterable([makeThreadOutcome(integrationThread)]),
+});
+const integrationServerConfig = ServerConfig.layerTest(process.cwd(), {
+  prefix: "t3-agent-session-importer-test-",
+});
+const integrationRuntimeRepository = ProviderSessionRuntime.layer.pipe(
+  Layer.provide(SqlitePersistenceMemory),
+);
+const integrationLayer = Layer.mergeAll(
+  OrchestrationEngineLive.pipe(
+    Layer.provide(OrchestrationProjectionSnapshotQueryLive),
+    Layer.provide(OrchestrationProjectionPipelineLive),
+  ),
+  OrchestrationProjectionSnapshotQueryLive,
+  integrationRuntimeRepository,
+  ProviderSessionDirectoryLive.pipe(Layer.provide(integrationRuntimeRepository)),
+  Layer.succeed(AgentSessionScanner.AgentSessionScanner, integrationScanner),
+).pipe(
+  Layer.provide(ThreadBackgroundLiveness.layer),
+  Layer.provide(ThreadPlanProgress.layer),
+  Layer.provide(OrchestrationEventStoreLive),
+  Layer.provide(OrchestrationCommandReceiptRepositoryLive),
+  Layer.provide(RepositoryIdentityResolver.layer),
+  Layer.provide(SqlitePersistenceMemory),
+  Layer.provideMerge(integrationServerConfig),
+  Layer.provideMerge(NodeServices.layer),
+);
+
+it.layer(integrationLayer)("AgentSessionImporter integration", (it) => {
+  it.effect("imports once after the real engine persists an old rejected receipt", () =>
+    Effect.gen(function* () {
+      const engine = yield* OrchestrationEngine.OrchestrationEngineService;
+      const snapshots = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+      const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory;
+      const threadId = ThreadId.make("import:codex:codex-session");
+
+      yield* engine.dispatch({
+        type: "project.create",
+        commandId: CommandId.make("create-import-integration-project"),
+        projectId: PROJECT_ID,
+        title: "Project",
+        workspaceRoot: WORKSPACE_ROOT,
+        defaultModelSelection: null,
+        createdAt: "2026-08-24T09:00:00.000Z",
+      });
+      const rejected = yield* Effect.result(
+        engine.dispatch({
+          type: "thread.history.import",
+          commandId: CommandId.make(`agent-session:history:${threadId}`),
+          threadId,
+          messages: [
+            {
+              messageId: MessageId.make(`${threadId}:000000`),
+              role: "user",
+              text: "Fix the bug",
+              createdAt: "2026-08-24T10:00:00.000Z",
+            },
+          ],
+        }),
+      );
+      expect(rejected._tag).toBe("Failure");
+
+      const result = yield* importRecentAgentThreads({ projectId: PROJECT_ID });
+      const importedThread = yield* snapshots.getThreadDetailById(threadId);
+      const binding = yield* directory.getBinding(threadId);
+
+      expect(result).toEqual({ importedCount: 1, skippedCount: 0 });
+      expect(Option.getOrThrow(importedThread).messages.map((message) => message.text)).toEqual(
+        integrationThread.messages.map((message) => message.text),
+      );
+      expect(Option.getOrThrow(importedThread).settledOverride).toBe("settled");
+      expect(Option.getOrThrow(importedThread).updatedAt).toBe("2026-08-24T10:00:00.000Z");
+      expect(Option.getOrThrow(binding)).toMatchObject({
+        provider: "codex",
+        providerInstanceId: "codex",
+        resumeCursor: { threadId: "codex-session" },
+        runtimePayload: { cwd: WORKSPACE_ROOT },
+      });
+
+      yield* engine.dispatch({
+        type: "thread.revert.complete",
+        commandId: CommandId.make("revert-imported-thread-to-baseline"),
+        threadId,
+        turnCount: 0,
+        createdAt: "2026-08-24T10:05:00.000Z",
+      });
+      const afterRevert = yield* snapshots.getThreadDetailById(threadId);
+      expect(Option.getOrThrow(afterRevert).messages.map((message) => message.text)).toEqual(
+        integrationThread.messages.map((message) => message.text),
+      );
+    }),
+  );
+
+  it.effect(
+    "retries a bounded import after scanner restart without rereading completed transcripts",
+    () =>
+      Effect.gen(function* () {
+        const engine = yield* OrchestrationEngine.OrchestrationEngineService;
+        const snapshots = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+        const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const fixtureDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-import-retry-",
+        });
+        const workspaceRoot = path.join(fixtureDir, "workspace");
+        const claudeHomePath = path.join(fixtureDir, "claude");
+        const codexHomePath = path.join(fixtureDir, "codex");
+        const sessionsDir = path.join(codexHomePath, "sessions", "2026", "08", "24");
+        yield* fileSystem.makeDirectory(workspaceRoot);
+        yield* fileSystem.makeDirectory(claudeHomePath);
+        yield* fileSystem.makeDirectory(sessionsDir, { recursive: true });
+
+        const projectId = ProjectId.make("project-bounded-import-retry");
+        const transcripts = Array.from({ length: 101 }, (_, index) => {
+          const providerSessionId = `bounded-session-${String(index).padStart(3, "0")}`;
+          return {
+            providerSessionId,
+            threadId: ThreadId.make(`import:codex:${providerSessionId}`),
+            filePath: path.join(sessionsDir, `rollout-${providerSessionId}.jsonl`),
+          };
+        });
+        for (const [index, transcript] of transcripts.entries()) {
+          yield* fileSystem.writeFileString(
+            transcript.filePath,
+            [
+              encodeTranscriptRecord({
+                type: "session_meta",
+                payload: { id: transcript.providerSessionId, cwd: workspaceRoot },
+              }),
+              encodeTranscriptRecord({
+                type: "event_msg",
+                payload: {
+                  type: "user_message",
+                  message: `Prompt ${transcript.providerSessionId}`,
+                },
+              }),
+            ].join("\n"),
+          );
+          const seconds = nowMs / 1_000 - index;
+          yield* fileSystem.utimes(transcript.filePath, seconds, seconds);
+        }
+        const legacy = transcripts[0]!;
+        const failed = transcripts[1]!;
+        const remaining = transcripts[100]!;
+        yield* engine.dispatch({
+          type: "project.create",
+          commandId: CommandId.make("create-bounded-import-project"),
+          projectId,
+          title: "Bounded import",
+          workspaceRoot,
+          defaultModelSelection: null,
+          createdAt: "2026-08-24T09:00:00.000Z",
+        });
+
+        // This completed import predates persisted transcript source metadata.
+        yield* directory.upsert({
+          threadId: legacy.threadId,
+          provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: ProviderInstanceId.make("codex"),
+          status: "stopped",
+          resumeCursor: { threadId: "legacy-current-session" },
+          runtimePayload: { cwd: workspaceRoot },
+        });
+        yield* engine.dispatch({
+          type: "thread.create",
+          commandId: CommandId.make("create-legacy-bounded-import"),
+          threadId: legacy.threadId,
+          projectId,
+          title: "Legacy import",
+          modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "default" },
+          runtimeMode: "full-access",
+          interactionMode: "default",
+          branch: null,
+          worktreePath: null,
+          createdAt: "2026-08-24T10:00:00.000Z",
+          historyImport: true,
+        });
+        yield* engine.dispatch({
+          type: "thread.history.import",
+          commandId: CommandId.make("import-legacy-bounded-history"),
+          threadId: legacy.threadId,
+          messages: [
+            {
+              messageId: MessageId.make(`${legacy.threadId}:000000`),
+              role: "user",
+              text: "Legacy imported history",
+              createdAt: "2026-08-24T10:00:00.000Z",
+            },
+          ],
+        });
+        expect(yield* snapshots.getImportedAgentSessionSources(projectId)).toEqual([]);
+
+        let failHistory = true;
+        const importerEngine = OrchestrationEngine.OrchestrationEngineService.of({
+          ...engine,
+          dispatch: (command) => {
+            if (
+              failHistory &&
+              command.type === "thread.history.import" &&
+              command.threadId === failed.threadId
+            ) {
+              failHistory = false;
+              return Effect.fail(
+                new OrchestrationCommandInvariantError({
+                  commandType: command.type,
+                  detail: "Injected history import failure.",
+                }),
+              );
+            }
+            return engine.dispatch(command);
+          },
+        });
+        const settingsLayer = ServerSettingsService.layerTest({
+          providers: {
+            claudeAgent: { homePath: claudeHomePath },
+            codex: { homePath: codexHomePath },
+          },
+        });
+        const transcriptPaths = new Set(transcripts.map((transcript) => transcript.filePath));
+        const runAttempt = Effect.fn("runBoundedImportAttempt")(function* (
+          completedPaths: ReadonlySet<string>,
+        ) {
+          const openCounts = new Map<string, number>();
+          const fullReads: string[] = [];
+          const observedFileSystem = FileSystem.FileSystem.of({
+            ...fileSystem,
+            open: (filePath, options) =>
+              Effect.suspend(() => {
+                if (transcriptPaths.has(filePath)) {
+                  const count = (openCounts.get(filePath) ?? 0) + 1;
+                  openCounts.set(filePath, count);
+                  // A fresh scanner first opens each file for project discovery.
+                  if (count > 1) {
+                    fullReads.push(filePath);
+                    if (completedPaths.has(filePath)) {
+                      return Effect.die(new Error(`Completed transcript reopened: ${filePath}`));
+                    }
+                  }
+                }
+                return fileSystem.open(filePath, options);
+              }),
+          });
+          const result = yield* importRecentAgentThreads({ projectId }).pipe(
+            Effect.provide(
+              Layer.fresh(AgentSessionScanner.layer).pipe(
+                Layer.provide(settingsLayer),
+                Layer.provide(Layer.succeed(FileSystem.FileSystem, observedFileSystem)),
+              ),
+            ),
+            Effect.provideService(OrchestrationEngine.OrchestrationEngineService, importerEngine),
+          );
+          return { result, fullReads, openCounts };
+        });
+
+        const first = yield* runAttempt(new Set());
+        expect(first.result).toEqual({ importedCount: 99, skippedCount: 2 });
+        expect(failHistory).toBe(false);
+        expect(first.fullReads).toEqual(transcripts.slice(0, 100).map((entry) => entry.filePath));
+        expect(first.openCounts.get(remaining.filePath)).toBe(1);
+        const completedSources = yield* snapshots.getImportedAgentSessionSources(projectId);
+        expect(completedSources).toHaveLength(99);
+        expect(completedSources).toContainEqual({
+          threadId: legacy.threadId,
+          source: expect.objectContaining({ filePath: legacy.filePath }),
+        });
+        expect(
+          Option.getOrThrow(yield* snapshots.getThreadDetailById(failed.threadId)).messages,
+        ).toEqual([]);
+        expect(Option.getOrThrow(yield* directory.getBinding(failed.threadId))).toMatchObject({
+          status: "stopped",
+          resumeCursor: { threadId: failed.providerSessionId },
+        });
+        expect(Option.isNone(yield* snapshots.getThreadDetailById(remaining.threadId))).toBe(true);
+
+        const completedPaths = new Set(completedSources.map((entry) => entry.source.filePath));
+        const second = yield* runAttempt(completedPaths);
+        expect(second.result).toEqual({ importedCount: 101, skippedCount: 0 });
+        expect(second.fullReads).toEqual([failed.filePath, remaining.filePath]);
+        for (const transcript of transcripts) {
+          expect(second.openCounts.get(transcript.filePath)).toBe(
+            completedPaths.has(transcript.filePath) ? 1 : 2,
+          );
+        }
+        expect(yield* snapshots.getImportedAgentSessionSources(projectId)).toHaveLength(101);
+        expect(
+          Option.getOrThrow(yield* snapshots.getThreadDetailById(legacy.threadId)).messages.map(
+            (message) => message.text,
+          ),
+        ).toEqual(["Legacy imported history"]);
+        expect(
+          Option.getOrThrow(yield* directory.getBinding(legacy.threadId)).resumeCursor,
+        ).toEqual({
+          threadId: "legacy-current-session",
+        });
+        for (const transcript of [failed, remaining]) {
+          expect(
+            Option.getOrThrow(
+              yield* snapshots.getThreadDetailById(transcript.threadId),
+            ).messages.map((message) => message.text),
+          ).toEqual([`Prompt ${transcript.providerSessionId}`]);
+        }
+      }),
+  );
+
+  for (const source of ["codex", "claudeAgent"] as const) {
+    it.effect(`resumes imported ${source} history only after the first prompt`, () =>
+      Effect.gen(function* () {
+        const engine = yield* OrchestrationEngine.OrchestrationEngineService;
+        const snapshots = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+        const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const workspaceRoot = yield* fileSystem.makeTempDirectoryScoped();
+        const projectId = ProjectId.make(`project-import-resume-${source}`);
+        const sourceThread = {
+          ...makeThread(source),
+          providerSessionId: source === "codex" ? "codex-first-resume" : CLAUDE_SESSION_ID,
+        };
+        const threadId = ThreadId.make(
+          `import:${sourceThread.providerInstanceId}:${sourceThread.providerSessionId}`,
+        );
+        const resumeCursor =
+          source === "codex"
+            ? { threadId: sourceThread.providerSessionId }
+            : { threadId, resume: sourceThread.providerSessionId };
+        const provider = ProviderDriverKind.make(source);
+        const harness = yield* makeTestProviderAdapterHarness({ provider });
+        const importSettled = yield* Deferred.make<void>();
+        const turnSent = yield* Deferred.make<void>();
+        const startSession = vi.fn(harness.adapter.startSession);
+        const sendTurn = vi.fn((input: ProviderSendTurnInput) =>
+          harness.adapter
+            .sendTurn(input)
+            .pipe(Effect.tap(() => Deferred.succeed(turnSent, undefined))),
+        );
+        const providerLayer = makeProviderServiceLive().pipe(
+          Layer.provide(
+            Layer.succeed(
+              ProviderAdapterRegistry,
+              makeAdapterRegistryMock({
+                [provider]: { ...harness.adapter, startSession, sendTurn },
+              }),
+            ),
+          ),
+          Layer.provide(
+            Layer.succeed(ProviderSessionDirectory.ProviderSessionDirectory, directory),
+          ),
+          Layer.provide(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+          Layer.provide(AnalyticsService.layerTest),
+        );
+        const reactorLayer = ProviderCommandReactorLive.pipe(
+          Layer.provideMerge(providerLayer),
+          Layer.provide(
+            Layer.succeed(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
+              ...snapshots,
+              // Acknowledge the imported settlement before draining the reactor.
+              getThreadShellById: (requestedThreadId) =>
+                snapshots
+                  .getThreadShellById(requestedThreadId)
+                  .pipe(
+                    Effect.tap(() =>
+                      requestedThreadId === threadId
+                        ? Deferred.succeed(importSettled, undefined)
+                        : Effect.void,
+                    ),
+                  ),
+            }),
+          ),
+          Layer.provide(
+            Layer.mock(ProviderAuthService)({
+              tryHandlePromptCommand: () => Effect.succeed(false),
+            }),
+          ),
+          Layer.provide(makeProviderRegistryLayer()),
+          Layer.provide(Layer.mock(GitWorkflowService)({})),
+          Layer.provide(Layer.mock(VcsStatusBroadcaster)({})),
+          Layer.provide(Layer.mock(TextGeneration)({})),
+          Layer.provide(ServerSettingsService.layerTest()),
+        );
+
+        yield* engine.dispatch({
+          type: "project.create",
+          commandId: CommandId.make(`create-import-resume-project-${source}`),
+          projectId,
+          title: "Import resume",
+          workspaceRoot,
+          defaultModelSelection: null,
+          createdAt: "2026-08-24T09:00:00.000Z",
+        });
+        yield* harness.queueTurnResponseForNextSession({ events: [] });
+
+        yield* Effect.gen(function* () {
+          const reactor = yield* ProviderCommandReactor;
+          yield* reactor.start();
+          expect(yield* importRecentAgentThreads({ projectId })).toEqual({
+            importedCount: 1,
+            skippedCount: 0,
+          });
+          yield* Deferred.await(importSettled);
+          yield* reactor.drain;
+          expect(startSession).not.toHaveBeenCalled();
+          expect(sendTurn).not.toHaveBeenCalled();
+          const importedThread = Option.getOrThrow(yield* snapshots.getThreadDetailById(threadId));
+          expect(importedThread.session).toBeNull();
+          expect(importedThread.latestTurn).toBeNull();
+
+          yield* engine.dispatch({
+            type: "thread.turn.start",
+            commandId: CommandId.make(`resume-imported-${source}`),
+            threadId,
+            message: {
+              messageId: MessageId.make(`resume-imported-message-${source}`),
+              role: "user",
+              text: "Continue this session",
+              attachments: [],
+            },
+            modelSelection: importedThread.modelSelection,
+            runtimeMode: importedThread.runtimeMode,
+            interactionMode: importedThread.interactionMode,
+            createdAt: "2026-08-24T10:02:00.000Z",
+          });
+          yield* Deferred.await(turnSent);
+          yield* reactor.drain;
+          expect(startSession).toHaveBeenCalledExactlyOnceWith(
+            expect.objectContaining({
+              threadId,
+              provider,
+              providerInstanceId: sourceThread.providerInstanceId,
+              resumeCursor,
+              cwd: workspaceRoot,
+            }),
+          );
+          expect(sendTurn).toHaveBeenCalledExactlyOnceWith(
+            expect.objectContaining({ threadId, input: "Continue this session" }),
+          );
+          expect(Option.getOrThrow(yield* directory.getBinding(threadId))).toMatchObject({
+            provider,
+            providerInstanceId: sourceThread.providerInstanceId,
+            resumeCursor,
+          });
+        }).pipe(
+          Effect.provide(reactorLayer),
+          Effect.provideService(
+            AgentSessionScanner.AgentSessionScanner,
+            AgentSessionScanner.AgentSessionScanner.of({
+              scan: Effect.die("unused"),
+              recentThreads: () => Stream.succeed(makeThreadOutcome(sourceThread)),
+            }),
+          ),
+        );
+      }),
+    );
+  }
+
+  it.effect("persists the resume cursor before publishing a new imported thread", () =>
+    Effect.gen(function* () {
+      const engine = yield* OrchestrationEngine.OrchestrationEngineService;
+      const snapshots = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+      const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory;
+      const repository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
+      const projectId = ProjectId.make("project-import-binding-race");
+      const workspaceRoot = "/tmp/project-import-binding-race";
+      const providerSessionId = "codex-binding-race";
+      const threadId = ThreadId.make(`import:codex:${providerSessionId}`);
+      const scanner = AgentSessionScanner.AgentSessionScanner.of({
+        scan: Effect.die("unused"),
+        recentThreads: () =>
+          Stream.succeed(
+            makeThreadOutcome({ ...integrationThread, providerSessionId, title: "Binding race" }),
+          ),
+      });
+      const importerAtBindingWrite = yield* Deferred.make<void>();
+      const releaseImporter = yield* Deferred.make<void>();
+      const importerRepository = ProviderSessionRuntime.ProviderSessionRuntimeRepository.of({
+        ...repository,
+        upsert: (runtime, options) =>
+          options?.onConflict === "ignore"
+            ? Deferred.succeed(importerAtBindingWrite, undefined).pipe(
+                Effect.andThen(Deferred.await(releaseImporter)),
+                Effect.andThen(repository.upsert(runtime, options)),
+              )
+            : repository.upsert(runtime, options),
+      });
+      const importerDirectory = yield* ProviderSessionDirectory.ProviderSessionDirectory.pipe(
+        Effect.provide(
+          Layer.fresh(ProviderSessionDirectoryLive).pipe(
+            Layer.provide(
+              Layer.succeed(
+                ProviderSessionRuntime.ProviderSessionRuntimeRepository,
+                importerRepository,
+              ),
+            ),
+          ),
+        ),
+      );
+
+      yield* engine.dispatch({
+        type: "project.create",
+        commandId: CommandId.make("create-import-binding-race-project"),
+        projectId,
+        title: "Binding race",
+        workspaceRoot,
+        defaultModelSelection: null,
+        createdAt: "2026-08-24T09:00:00.000Z",
+      });
+
+      const importFiber = yield* importRecentAgentThreads({ projectId }).pipe(
+        Effect.provideService(AgentSessionScanner.AgentSessionScanner, scanner),
+        Effect.provideService(ProviderSessionDirectory.ProviderSessionDirectory, importerDirectory),
+        Effect.forkChild,
+      );
+
+      yield* Effect.raceFirst(
+        Deferred.await(importerAtBindingWrite),
+        Fiber.join(importFiber).pipe(
+          Effect.flatMap((result) =>
+            Effect.die(
+              new Error(`Import completed before the binding write: ${JSON.stringify(result)}`),
+            ),
+          ),
+        ),
+      );
+      expect(Option.isNone(yield* snapshots.getThreadDetailById(threadId))).toBe(true);
+
+      yield* directory.upsert({
+        threadId,
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: ProviderInstanceId.make("codex"),
+        status: "running",
+        resumeCursor: { threadId: "active-client-session" },
+        runtimePayload: { cwd: workspaceRoot, activeTurnId: "turn-active" },
+      });
+      yield* Deferred.succeed(releaseImporter, undefined);
+
+      expect(yield* Fiber.join(importFiber)).toEqual({ importedCount: 1, skippedCount: 0 });
+      expect(
+        Option.getOrThrow(yield* snapshots.getThreadDetailById(threadId)).messages.map(
+          (message) => message.text,
+        ),
+      ).toEqual(integrationThread.messages.map((message) => message.text));
+      expect(Option.getOrThrow(yield* directory.getBinding(threadId))).toMatchObject({
+        status: "running",
+        resumeCursor: { threadId: "active-client-session" },
+        runtimePayload: { cwd: workspaceRoot, activeTurnId: "turn-active" },
+      });
+    }),
+  );
+
+  it.effect("does not import history over a turn started on a partial thread", () =>
+    Effect.gen(function* () {
+      const engine = yield* OrchestrationEngine.OrchestrationEngineService;
+      const snapshots = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+      const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory;
+      const repository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
+      const projectId = ProjectId.make("project-import-turn-race");
+      const workspaceRoot = "/tmp/project-import-turn-race";
+      const providerSessionId = "codex-turn-race";
+      const threadId = ThreadId.make(`import:codex:${providerSessionId}`);
+      const scanner = AgentSessionScanner.AgentSessionScanner.of({
+        scan: Effect.die("unused"),
+        recentThreads: () =>
+          Stream.succeed(
+            makeThreadOutcome({ ...integrationThread, providerSessionId, title: "Turn race" }),
+          ),
+      });
+      const importerAtBindingWrite = yield* Deferred.make<void>();
+      const releaseImporter = yield* Deferred.make<void>();
+      const importerRepository = ProviderSessionRuntime.ProviderSessionRuntimeRepository.of({
+        ...repository,
+        upsert: (runtime, options) =>
+          options?.onConflict === "ignore"
+            ? Deferred.succeed(importerAtBindingWrite, undefined).pipe(
+                Effect.andThen(Deferred.await(releaseImporter)),
+                Effect.andThen(repository.upsert(runtime, options)),
+              )
+            : repository.upsert(runtime, options),
+      });
+      const importerDirectory = yield* ProviderSessionDirectory.ProviderSessionDirectory.pipe(
+        Effect.provide(
+          Layer.fresh(ProviderSessionDirectoryLive).pipe(
+            Layer.provide(
+              Layer.succeed(
+                ProviderSessionRuntime.ProviderSessionRuntimeRepository,
+                importerRepository,
+              ),
+            ),
+          ),
+        ),
+      );
+
+      yield* engine.dispatch({
+        type: "project.create",
+        commandId: CommandId.make("create-import-turn-race-project"),
+        projectId,
+        title: "Turn race",
+        workspaceRoot,
+        defaultModelSelection: null,
+        createdAt: "2026-08-24T09:00:00.000Z",
+      });
+      yield* engine.dispatch({
+        type: "thread.create",
+        commandId: CommandId.make("create-import-turn-race-thread"),
+        threadId,
+        projectId,
+        title: "Turn race",
+        modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "default" },
+        runtimeMode: "full-access",
+        interactionMode: "default",
+        branch: null,
+        worktreePath: null,
+        createdAt: "2026-08-24T10:00:00.000Z",
+      });
+
+      const importFiber = yield* importRecentAgentThreads({ projectId }).pipe(
+        Effect.provideService(AgentSessionScanner.AgentSessionScanner, scanner),
+        Effect.provideService(ProviderSessionDirectory.ProviderSessionDirectory, importerDirectory),
+        Effect.forkChild,
+      );
+      yield* Deferred.await(importerAtBindingWrite);
+
+      yield* directory.upsert({
+        threadId,
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: ProviderInstanceId.make("codex"),
+        status: "running",
+        resumeCursor: { threadId: "active-client-session" },
+        runtimePayload: { cwd: workspaceRoot, activeTurnId: "turn-active" },
+      });
+      yield* engine.dispatch({
+        type: "thread.turn.start",
+        commandId: CommandId.make("start-turn-during-import"),
+        threadId,
+        message: {
+          messageId: MessageId.make("message-during-import"),
+          role: "user",
+          text: "Continue while import waits",
+          attachments: [],
+        },
+        runtimeMode: "full-access",
+        interactionMode: "default",
+        createdAt: "2026-08-24T10:02:00.000Z",
+      });
+      yield* Deferred.succeed(releaseImporter, undefined);
+
+      expect(yield* Fiber.join(importFiber)).toEqual({ importedCount: 0, skippedCount: 1 });
+      expect(Option.getOrThrow(yield* directory.getBinding(threadId))).toMatchObject({
+        status: "running",
+        resumeCursor: { threadId: "active-client-session" },
+        runtimePayload: { cwd: workspaceRoot, activeTurnId: "turn-active" },
+      });
+      expect(
+        Option.getOrThrow(yield* snapshots.getThreadDetailById(threadId)).messages.map(
+          (message) => message.text,
+        ),
+      ).toEqual(["Continue while import waits"]);
+    }),
+  );
+});
diff --git a/apps/server/src/project/AgentSessionImporter.ts b/apps/server/src/project/AgentSessionImporter.ts
new file mode 100644
index 000000000000..3820c2cf411a
--- /dev/null
+++ b/apps/server/src/project/AgentSessionImporter.ts
@@ -0,0 +1,297 @@
+import {
+  CommandId,
+  DEFAULT_MODEL,
+  DEFAULT_MODEL_BY_PROVIDER,
+  DEFAULT_PROVIDER_INTERACTION_MODE,
+  DEFAULT_RUNTIME_MODE,
+  AgentSessionImportProjectChangedError,
+  AgentSessionImportProjectNotFoundError,
+  AgentSessionSource,
+  AgentSessionScanError,
+  isImportedAgentSessionMessageId,
+  MessageId,
+  ProjectId,
+  ProviderDriverKind,
+  ThreadId,
+  type AgentSessionImportInput,
+  type AgentSessionImportResult,
+  type OrchestrationThread,
+} from "@t3tools/contracts";
+import { normalizeProjectPathForComparison } from "@t3tools/shared/path";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+
+import * as OrchestrationEngine from "../orchestration/Services/OrchestrationEngine.ts";
+import * as ProjectionSnapshotQuery from "../orchestration/Services/ProjectionSnapshotQuery.ts";
+import * as ProviderSessionDirectory from "../provider/Services/ProviderSessionDirectory.ts";
+import * as AgentSessionScanner from "./AgentSessionScanner.ts";
+
+const CLAUDE_SESSION_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+class AgentSessionUnresumableSessionError extends Schema.TaggedErrorClass<AgentSessionUnresumableSessionError>()(
+  "AgentSessionUnresumableSessionError",
+  {
+    source: AgentSessionSource,
+    providerSessionId: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `Session '${this.providerSessionId}' from '${this.source}' cannot be resumed.`;
+  }
+}
+
+class AgentSessionThreadProjectConflictError extends Schema.TaggedErrorClass<AgentSessionThreadProjectConflictError>()(
+  "AgentSessionThreadProjectConflictError",
+  {
+    threadId: ThreadId,
+    expectedProjectId: ProjectId,
+    actualProjectId: ProjectId,
+  },
+) {
+  override get message(): string {
+    return `Imported thread '${this.threadId}' belongs to project '${this.actualProjectId}', not '${this.expectedProjectId}'.`;
+  }
+}
+
+class AgentSessionThreadModifiedError extends Schema.TaggedErrorClass<AgentSessionThreadModifiedError>()(
+  "AgentSessionThreadModifiedError",
+  { threadId: ThreadId },
+) {
+  override get message(): string {
+    return `Imported thread '${this.threadId}' changed before its history import completed.`;
+  }
+}
+
+function hasImportedHistory(thread: OrchestrationThread): boolean {
+  return thread.messages.some((message) => isImportedAgentSessionMessageId(message.id));
+}
+
+function hasImportBlockingActivity(
+  thread: OrchestrationThread,
+  importedHistoryPresent: boolean,
+): boolean {
+  return (
+    thread.archivedAt !== null ||
+    thread.deletedAt !== null ||
+    thread.latestTurn !== null ||
+    thread.session !== null ||
+    thread.messages.some((message) => !isImportedAgentSessionMessageId(message.id)) ||
+    thread.proposedPlans.length > 0 ||
+    thread.activities.length > 0 ||
+    thread.checkpoints.length > 0 ||
+    thread.snoozedUntil != null ||
+    thread.snoozedAt != null ||
+    thread.pinnedAt != null ||
+    thread.pinOrderKey != null ||
+    thread.titleRegeneration != null ||
+    thread.linkedPullRequest != null ||
+    thread.unsettledAt != null ||
+    (importedHistoryPresent
+      ? thread.settledOverride !== "settled"
+      : thread.settledOverride !== null || thread.settledAt !== null)
+  );
+}
+
+/** Import recent transcript text and persist the cursor needed to resume its provider session. */
+export const importRecentAgentThreads = Effect.fn("importRecentAgentThreads")(function* (
+  input: AgentSessionImportInput,
+) {
+  const scanner = yield* AgentSessionScanner.AgentSessionScanner;
+  const engine = yield* OrchestrationEngine.OrchestrationEngineService;
+  const snapshots = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+  const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory;
+  const crypto = yield* Crypto.Crypto;
+  const project = yield* snapshots.getProjectShellById(input.projectId).pipe(
+    Effect.mapError((cause) => new AgentSessionScanError({ operation: "read-projects", cause })),
+    Effect.flatMap(
+      Option.match({
+        onNone: () =>
+          Effect.fail(new AgentSessionImportProjectNotFoundError({ projectId: input.projectId })),
+        onSome: Effect.succeed,
+      }),
+    ),
+  );
+  const workspaceRoot = project.workspaceRoot;
+  if (
+    input.expectedWorkspaceRoot !== undefined &&
+    normalizeProjectPathForComparison(workspaceRoot) !==
+      normalizeProjectPathForComparison(input.expectedWorkspaceRoot)
+  ) {
+    return yield* new AgentSessionImportProjectChangedError({ projectId: input.projectId });
+  }
+  const completedSources = yield* snapshots
+    .getImportedAgentSessionSources(input.projectId)
+    .pipe(
+      Effect.mapError((cause) => new AgentSessionScanError({ operation: "read-projects", cause })),
+    );
+  const threads = scanner.recentThreads(
+    workspaceRoot,
+    completedSources.map((entry) => entry.source),
+  );
+  const importedThreadIds = new Set<ThreadId>();
+  let importedCount = 0;
+  let skippedCount = 0;
+
+  yield* Stream.runForEach(threads, (outcome) =>
+    Effect.gen(function* () {
+      if (outcome._tag === "Skipped") {
+        skippedCount += 1;
+        return;
+      }
+      if (outcome._tag === "AlreadyImported" || outcome._tag === "Duplicate") {
+        const threadId = ThreadId.make(
+          `import:${outcome.source.providerInstanceId}:${outcome.source.providerSessionId}`,
+        );
+        if (outcome._tag === "AlreadyImported") {
+          importedThreadIds.add(threadId);
+          importedCount += 1;
+        } else if (importedThreadIds.has(threadId)) {
+          const recorded = yield* directory
+            .recordImportedTranscript({ threadId, source: outcome.source })
+            .pipe(Effect.result);
+          if (recorded._tag === "Failure") {
+            skippedCount += 1;
+            yield* Effect.logWarning("Could not record an imported transcript copy", {
+              threadId,
+              cause: recorded.failure,
+            });
+          }
+        }
+        return;
+      }
+      const thread = outcome.thread;
+      const threadId = ThreadId.make(
+        `import:${thread.providerInstanceId}:${thread.providerSessionId}`,
+      );
+      const imported = yield* Effect.gen(function* () {
+        const provider = ProviderDriverKind.make(thread.source);
+        const model = thread.model ?? DEFAULT_MODEL_BY_PROVIDER[provider] ?? DEFAULT_MODEL;
+        const existingThread = yield* snapshots.getThreadDetailById(threadId);
+        const existingBinding = yield* directory.getBinding(threadId);
+
+        if (
+          thread.source === "claudeAgent" &&
+          !CLAUDE_SESSION_ID_PATTERN.test(thread.providerSessionId)
+        ) {
+          return yield* new AgentSessionUnresumableSessionError({
+            source: thread.source,
+            providerSessionId: thread.providerSessionId,
+          });
+        }
+
+        if (Option.isSome(existingThread) && existingThread.value.projectId !== input.projectId) {
+          return yield* new AgentSessionThreadProjectConflictError({
+            threadId,
+            expectedProjectId: input.projectId,
+            actualProjectId: existingThread.value.projectId,
+          });
+        }
+
+        const importedHistoryPresent = Option.isSome(existingThread)
+          ? hasImportedHistory(existingThread.value)
+          : false;
+        if (
+          Option.isSome(existingThread) &&
+          importedHistoryPresent &&
+          Option.isSome(existingBinding)
+        ) {
+          yield* directory.recordImportedTranscript({ threadId, source: outcome.source });
+          return true;
+        }
+
+        if (
+          Option.isSome(existingThread) &&
+          hasImportBlockingActivity(existingThread.value, importedHistoryPresent)
+        ) {
+          return yield* new AgentSessionThreadModifiedError({ threadId });
+        }
+
+        if (
+          Option.isSome(existingBinding) &&
+          (existingBinding.value.provider !== provider ||
+            existingBinding.value.providerInstanceId !== thread.providerInstanceId ||
+            existingBinding.value.status !== "stopped")
+        ) {
+          return yield* new AgentSessionThreadModifiedError({ threadId });
+        }
+
+        // Install the cursor before the thread becomes visible. A concurrent
+        // real session can replace it, while insert-ignore keeps this import
+        // from replacing that newer binding.
+        if (Option.isNone(existingBinding)) {
+          yield* directory.upsert(
+            {
+              threadId,
+              provider,
+              providerInstanceId: thread.providerInstanceId,
+              status: "stopped",
+              runtimeMode: DEFAULT_RUNTIME_MODE,
+              resumeCursor:
+                thread.source === "codex"
+                  ? { threadId: thread.providerSessionId }
+                  : { threadId, resume: thread.providerSessionId },
+              runtimePayload: { cwd: workspaceRoot },
+            },
+            { onConflict: "ignore" },
+          );
+        }
+
+        if (Option.isNone(existingThread)) {
+          yield* engine.dispatch({
+            type: "thread.create",
+            commandId: CommandId.make(yield* crypto.randomUUIDv4),
+            threadId,
+            projectId: input.projectId,
+            title: thread.title,
+            modelSelection: { instanceId: thread.providerInstanceId, model },
+            runtimeMode: DEFAULT_RUNTIME_MODE,
+            interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+            branch: null,
+            worktreePath: null,
+            createdAt: thread.createdAt,
+            historyImport: true,
+          });
+        }
+
+        if (!importedHistoryPresent) {
+          yield* engine.dispatch({
+            type: "thread.history.import",
+            commandId: CommandId.make(yield* crypto.randomUUIDv4),
+            threadId,
+            messages: thread.messages.map((message, index) => ({
+              messageId: MessageId.make(`${threadId}:${String(index).padStart(6, "0")}`),
+              role: message.role,
+              text: message.text,
+              createdAt: message.createdAt,
+            })),
+          });
+        }
+
+        yield* directory.recordImportedTranscript({ threadId, source: outcome.source });
+
+        return true;
+      }).pipe(
+        Effect.catch((cause) =>
+          Effect.logWarning("Could not import an agent session", {
+            provider: thread.source,
+            sessionId: thread.providerSessionId,
+            cause,
+          }).pipe(Effect.as(false)),
+        ),
+      );
+
+      if (imported) {
+        importedThreadIds.add(threadId);
+        importedCount += 1;
+      } else {
+        skippedCount += 1;
+      }
+    }),
+  );
+
+  return { importedCount, skippedCount } satisfies AgentSessionImportResult;
+});
diff --git a/apps/server/src/project/AgentSessionScanner.test.ts b/apps/server/src/project/AgentSessionScanner.test.ts
new file mode 100644
index 000000000000..dc6d72a0ce63
--- /dev/null
+++ b/apps/server/src/project/AgentSessionScanner.test.ts
@@ -0,0 +1,3088 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeOS from "node:os";
+import { describe, expect, it } from "@effect/vitest";
+import {
+  type OrchestrationProjectShell,
+  ProjectId,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerSettings as ContractServerSettings,
+} from "@t3tools/contracts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
+
+import * as ServerConfig from "../config.ts";
+import * as ProjectionSnapshotQuery from "../orchestration/Services/ProjectionSnapshotQuery.ts";
+import * as ServerSettings from "../serverSettings.ts";
+import * as AgentSessionScanner from "./AgentSessionScanner.ts";
+
+const makeProjectShell = (workspaceRoot: string): OrchestrationProjectShell => ({
+  id: ProjectId.make("project-1"),
+  title: "Imported",
+  workspaceRoot,
+  defaultModelSelection: null,
+  scripts: [],
+  createdAt: "2026-01-01T00:00:00.000Z",
+  updatedAt: "2026-01-01T00:00:00.000Z",
+});
+
+/** Only `getShellSnapshot` is exercised; the rest must not be called. */
+const makeProjectionSnapshotQueryLayer = (importedWorkspaceRoots: ReadonlyArray<string>) =>
+  Layer.succeed(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
+    getCommandReadModel: () => Effect.die("unused"),
+    getUserInputActivity: () => Effect.die("unused"),
+    getSnapshot: () => Effect.die("unused"),
+    getShellSnapshot: () =>
+      Effect.succeed({
+        snapshotSequence: 0,
+        projects: importedWorkspaceRoots.map((workspaceRoot) => makeProjectShell(workspaceRoot)),
+        threads: [],
+        updatedAt: "2026-01-01T00:00:00.000Z",
+      }),
+    getArchivedShellSnapshot: () => Effect.die("unused"),
+    getSnapshotSequence: () => Effect.die("unused"),
+    getCounts: () => Effect.die("unused"),
+    getEventReplayStats: () => Effect.die("unused"),
+    getActiveProjectByWorkspaceRoot: () => Effect.die("unused"),
+    getProjectShellById: () => Effect.die("unused"),
+    getImportedAgentSessionSources: () => Effect.succeed([]),
+    getFirstActiveThreadIdByProjectId: () => Effect.die("unused"),
+    getThreadCheckpointContext: () => Effect.die("unused"),
+    getFullThreadDiffContext: () => Effect.die("unused"),
+    getThreadShellById: () => Effect.die("unused"),
+    getThreadRuntimeContext: () => Effect.die("unused"),
+    getThreadDetailById: () => Effect.die("unused"),
+    getThreadDetailSnapshot: () => Effect.die("unused"),
+    searchThreads: () => Effect.die("unused"),
+  });
+
+/**
+ * Run a scan against the given homes. Homes are temp dirs created inside the
+ * test, so the layer is built per run rather than shared.
+ */
+interface ScannerTestInput {
+  readonly claudeHomePath: string;
+  readonly codexHomePath: string;
+  readonly importedWorkspaceRoots?: ReadonlyArray<string>;
+  /** Base dir for the test ServerConfig; worktreesDir derives from it. */
+  readonly configBaseDir?: string;
+  readonly providerInstances?: ContractServerSettings["providerInstances"];
+}
+
+const makeScannerTestLayer = (input: ScannerTestInput) =>
+  AgentSessionScanner.layer.pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        ServerSettings.layerTest({
+          providers: {
+            claudeAgent: { homePath: input.claudeHomePath },
+            codex: { homePath: input.codexHomePath },
+          },
+          ...(input.providerInstances === undefined
+            ? {}
+            : { providerInstances: input.providerInstances }),
+        }),
+        ServerConfig.layerTest(
+          input.claudeHomePath,
+          input.configBaseDir ?? { prefix: "t3code-scanner-config-" },
+        ),
+        makeProjectionSnapshotQueryLayer(input.importedWorkspaceRoots ?? []),
+      ),
+    ),
+  );
+
+const runScan = (input: ScannerTestInput) =>
+  Effect.gen(function* () {
+    const scanner = yield* AgentSessionScanner.AgentSessionScanner;
+    return yield* scanner.scan;
+  }).pipe(Effect.provide(makeScannerTestLayer(input)));
+
+const runRecentThreadOutcomes = (input: ScannerTestInput & { readonly workspaceRoot: string }) =>
+  Effect.gen(function* () {
+    const scanner = yield* AgentSessionScanner.AgentSessionScanner;
+    return yield* scanner.recentThreads(input.workspaceRoot).pipe(
+      Stream.runCollect,
+      Effect.map((outcomes) => Array.from(outcomes)),
+    );
+  }).pipe(Effect.provide(makeScannerTestLayer(input)));
+
+const runRecentThreads = (input: ScannerTestInput & { readonly workspaceRoot: string }) =>
+  runRecentThreadOutcomes(input).pipe(
+    Effect.map((outcomes) =>
+      outcomes.flatMap((outcome) => (outcome._tag === "Importable" ? [outcome.thread] : [])),
+    ),
+  );
+
+const makeTempDir = Effect.fn("AgentSessionScanner.test.makeTempDir")(function* (prefix: string) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  return yield* fileSystem.makeTempDirectoryScoped({ prefix });
+});
+
+const writeTranscript = Effect.fn("AgentSessionScanner.test.writeTranscript")(function* (input: {
+  readonly filePath: string;
+  readonly contents: string;
+  /** Epoch millis, so ordering assertions never depend on write timing. */
+  readonly mtimeMs: number;
+}) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  yield* fileSystem.makeDirectory(path.dirname(input.filePath), { recursive: true });
+  yield* fileSystem.writeFileString(input.filePath, input.contents);
+  // Numeric utimes arguments are seconds, not milliseconds.
+  const seconds = input.mtimeMs / 1000;
+  yield* fileSystem.utimes(input.filePath, seconds, seconds);
+});
+
+/** Claude session line: the first record carries the real `cwd`. */
+const claudeSessionLine = (cwd: string) =>
+  `${JSON.stringify({ type: "user", cwd, sessionId: "s1" })}\n${JSON.stringify({ type: "assistant" })}\n`;
+
+/** Codex rollout line: session metadata is nested under `payload`. */
+const codexRolloutLine = (cwd: string) =>
+  `${JSON.stringify({ timestamp: "2026-01-01T00:00:00.000Z", type: "session_meta", payload: { id: "r1", cwd } })}\n`;
+
+const encodeTranscriptRecord = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
+
+function makeRecordLimitTranscript(cwd: string, overflow: boolean): string {
+  const records =
+    [
+      encodeTranscriptRecord({
+        type: "session_meta",
+        payload: { id: "record-limit-session", cwd },
+      }),
+      encodeTranscriptRecord({
+        type: "event_msg",
+        payload: { type: "user_message", message: "First prompt" },
+      }),
+    ].join("\n") +
+    "\n" +
+    "{}\n".repeat(99_998);
+  return overflow
+    ? records +
+        "\n" +
+        encodeTranscriptRecord({
+          type: "event_msg",
+          payload: { type: "user_message", message: "Overflow prompt" },
+        }) +
+        "\n"
+    : records;
+}
+
+it.layer(NodeServices.layer)("AgentSessionScanner", (it) => {
+  describe("scan", () => {
+    it.effect("reads Claude project cwds from transcripts, newest first", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const olderWorkspace = yield* makeTempDir("t3code-workspace-older-");
+        const newerWorkspace = yield* makeTempDir("t3code-workspace-newer-");
+
+        // Slugs are intentionally lossy; the scanner must not decode them.
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug-older", "a.jsonl"),
+          contents: claudeSessionLine(olderWorkspace),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug-older", "b.jsonl"),
+          contents: claudeSessionLine(olderWorkspace),
+          mtimeMs: Date.parse("2026-01-02T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug-newer", "c.jsonl"),
+          contents: claudeSessionLine(newerWorkspace),
+          mtimeMs: Date.parse("2026-03-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(result.candidates).toEqual([
+          {
+            path: newerWorkspace,
+            title: path.basename(newerWorkspace),
+            sources: ["claudeAgent"],
+            threadCount: 1,
+            lastActiveAt: "2026-03-01T00:00:00.000Z",
+            alreadyImported: false,
+          },
+          {
+            path: olderWorkspace,
+            title: path.basename(olderWorkspace),
+            sources: ["claudeAgent"],
+            threadCount: 2,
+            lastActiveAt: "2026-01-02T00:00:00.000Z",
+            alreadyImported: false,
+          },
+        ]);
+      }),
+    );
+
+    it.effect("groups Codex rollouts by cwd across date directories", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const otherWorkspace = yield* makeTempDir("t3code-workspace-other-");
+
+        const rollout = (year: string, month: string, day: string, name: string) =>
+          path.join(codexHomePath, "sessions", year, month, day, name);
+
+        yield* writeTranscript({
+          filePath: rollout("2026", "01", "05", "rollout-2026-01-05T10-00-00-aaa.jsonl"),
+          contents: codexRolloutLine(workspace),
+          mtimeMs: Date.parse("2026-01-05T10:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: rollout("2026", "02", "09", "rollout-2026-02-09T10-00-00-bbb.jsonl"),
+          contents: codexRolloutLine(workspace),
+          mtimeMs: Date.parse("2026-02-09T10:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: rollout("2026", "02", "09", "rollout-2026-02-09T11-00-00-ccc.jsonl"),
+          contents: codexRolloutLine(otherWorkspace),
+          mtimeMs: Date.parse("2026-02-09T11:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(result.candidates).toEqual([
+          {
+            path: otherWorkspace,
+            title: path.basename(otherWorkspace),
+            sources: ["codex"],
+            threadCount: 1,
+            lastActiveAt: "2026-02-09T11:00:00.000Z",
+            alreadyImported: false,
+          },
+          {
+            path: workspace,
+            title: path.basename(workspace),
+            sources: ["codex"],
+            threadCount: 2,
+            lastActiveAt: "2026-02-09T10:00:00.000Z",
+            alreadyImported: false,
+          },
+        ]);
+      }),
+    );
+
+    it.effect.each(["claudeAgent", "codex"] as const)(
+      "does not open a non-file %s transcript",
+      (source) =>
+        Effect.gen(function* () {
+          const path = yield* Path.Path;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+          const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+          const transcriptPath =
+            source === "claudeAgent"
+              ? path.join(claudeHomePath, "projects", "-slug", "session.jsonl")
+              : path.join(codexHomePath, "sessions", "2026", "08", "24", "rollout-session.jsonl");
+          yield* fileSystem.makeDirectory(transcriptPath, { recursive: true });
+
+          let transcriptOpenCount = 0;
+          const simulatedFileSystem = FileSystem.FileSystem.of({
+            ...fileSystem,
+            open: (filePath, options) => {
+              if (filePath === transcriptPath) transcriptOpenCount += 1;
+              return fileSystem.open(filePath, options);
+            },
+          });
+
+          const result = yield* runScan({ claudeHomePath, codexHomePath }).pipe(
+            Effect.provideService(FileSystem.FileSystem, simulatedFileSystem),
+          );
+
+          expect(result.candidates).toEqual([]);
+          expect(transcriptOpenCount).toBe(0);
+        }),
+    );
+
+    it.effect.each(["claudeAgent", "codex"] as const)(
+      "stops %s directory reads at the discovery operation budget",
+      (source) =>
+        Effect.gen(function* () {
+          const path = yield* Path.Path;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+          const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+          const discoveryRoot =
+            source === "claudeAgent"
+              ? path.join(claudeHomePath, "projects")
+              : path.join(codexHomePath, "sessions");
+          const emptyDirectories = Array.from(
+            { length: 20_001 },
+            (_, index) => `empty-${index.toString().padStart(5, "0")}`,
+          );
+          let directoryReadCount = 0;
+          const simulatedFileSystem = FileSystem.FileSystem.of({
+            ...fileSystem,
+            readDirectory: (directory, options) => {
+              if (directory === discoveryRoot) {
+                directoryReadCount += 1;
+                return Effect.succeed(emptyDirectories);
+              }
+              if (path.dirname(directory) === discoveryRoot) {
+                directoryReadCount += 1;
+                return Effect.succeed([]);
+              }
+              return fileSystem.readDirectory(directory, options);
+            },
+          });
+
+          const result = yield* runScan({ claudeHomePath, codexHomePath }).pipe(
+            Effect.provideService(FileSystem.FileSystem, simulatedFileSystem),
+          );
+
+          expect(result.candidates).toEqual([]);
+          expect(directoryReadCount).toBe(20_000);
+        }),
+    );
+
+    it.effect("merges the same cwd seen by both agents and flags imported projects", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents: claudeSessionLine(workspace),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(
+            codexHomePath,
+            "sessions",
+            "2026",
+            "04",
+            "01",
+            "rollout-2026-04-01T09-00-00-aaa.jsonl",
+          ),
+          contents: codexRolloutLine(workspace),
+          mtimeMs: Date.parse("2026-04-01T09:00:00.000Z"),
+        });
+
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          importedWorkspaceRoots: [workspace],
+        });
+
+        expect(result.candidates).toEqual([
+          {
+            path: workspace,
+            title: path.basename(workspace),
+            projectId: ProjectId.make("project-1"),
+            sources: ["claudeAgent", "codex"],
+            threadCount: 2,
+            lastActiveAt: "2026-04-01T09:00:00.000Z",
+            alreadyImported: true,
+          },
+        ]);
+      }),
+    );
+
+    it.effect("returns the imported project ID through a realpath alias", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const linkParent = yield* makeTempDir("t3code-scanner-links-");
+        const workspaceAlias = path.join(linkParent, "workspace-alias");
+        yield* fileSystem.symlink(workspace, workspaceAlias);
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents: claudeSessionLine(workspaceAlias),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          importedWorkspaceRoots: [workspace],
+        });
+
+        expect(result.candidates[0]).toMatchObject({
+          path: workspace,
+          projectId: ProjectId.make("project-1"),
+          alreadyImported: true,
+        });
+      }),
+    );
+
+    it.effect("matches a persisted project alias to a transcript realpath", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const linkParent = yield* makeTempDir("t3code-scanner-links-");
+        const workspaceAlias = path.join(linkParent, "workspace-alias");
+        yield* fileSystem.symlink(workspace, workspaceAlias);
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents: claudeSessionLine(workspace),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          importedWorkspaceRoots: [workspaceAlias],
+        });
+
+        expect(result.candidates[0]).toMatchObject({
+          path: workspaceAlias,
+          projectId: ProjectId.make("project-1"),
+          alreadyImported: true,
+        });
+      }),
+    );
+
+    it.effect("merges case aliases and preserves the persisted project path", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const workspaceAlias = path.join(
+          path.dirname(workspace),
+          path.basename(workspace).toUpperCase(),
+        );
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents: claudeSessionLine(workspaceAlias),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(codexHomePath, "sessions", "2026", "01", "02", "rollout-b.jsonl"),
+          contents: codexRolloutLine(workspace),
+          mtimeMs: Date.parse("2026-01-02T00:00:00.000Z"),
+        });
+
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          stat: (filePath) => fileSystem.stat(filePath === workspaceAlias ? workspace : filePath),
+        });
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          importedWorkspaceRoots: [workspace],
+        }).pipe(Effect.provideService(FileSystem.FileSystem, simulatedFileSystem));
+
+        expect(result.candidates).toEqual([
+          {
+            path: workspace,
+            title: path.basename(workspace),
+            projectId: ProjectId.make("project-1"),
+            sources: ["claudeAgent", "codex"],
+            threadCount: 2,
+            lastActiveAt: "2026-01-02T00:00:00.000Z",
+            alreadyImported: true,
+          },
+        ]);
+      }),
+    );
+
+    it.effect("keeps case variants distinct when the filesystem identities differ", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const backingUpper = yield* makeTempDir("t3code-backing-upper-");
+        const backingLower = yield* makeTempDir("t3code-backing-lower-");
+        const aliasParent = yield* makeTempDir("t3code-case-aliases-");
+        const upperWorkspace = path.join(aliasParent, "Repo");
+        const lowerWorkspace = path.join(aliasParent, "repo");
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-upper", "a.jsonl"),
+          contents: claudeSessionLine(upperWorkspace),
+          mtimeMs: Date.parse("2026-01-02T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-lower", "b.jsonl"),
+          contents: claudeSessionLine(lowerWorkspace),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          stat: (filePath) =>
+            fileSystem.stat(
+              filePath === upperWorkspace
+                ? backingUpper
+                : filePath === lowerWorkspace
+                  ? backingLower
+                  : filePath,
+            ),
+        });
+        const result = yield* runScan({ claudeHomePath, codexHomePath }).pipe(
+          Effect.provideService(FileSystem.FileSystem, simulatedFileSystem),
+        );
+
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([
+          upperWorkspace,
+          lowerWorkspace,
+        ]);
+      }),
+    );
+
+    it.effect("uses explicit provider instance homes instead of overridden legacy homes", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-legacy-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-legacy-");
+        const claudeInstanceHome = yield* makeTempDir("t3code-claude-instance-");
+        const codexInstanceHome = yield* makeTempDir("t3code-codex-instance-");
+        const legacyWorkspace = yield* makeTempDir("t3code-workspace-legacy-");
+        const claudeWorkspace = yield* makeTempDir("t3code-workspace-claude-");
+        const codexWorkspace = yield* makeTempDir("t3code-workspace-codex-");
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-legacy", "session.jsonl"),
+          contents: claudeSessionLine(legacyWorkspace),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(claudeInstanceHome, "projects", "-actual", "session.jsonl"),
+          contents: claudeSessionLine(claudeWorkspace),
+          mtimeMs: Date.parse("2026-02-01T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(
+            codexInstanceHome,
+            "sessions",
+            "2026",
+            "03",
+            "01",
+            "rollout-instance.jsonl",
+          ),
+          contents: codexRolloutLine(codexWorkspace),
+          mtimeMs: Date.parse("2026-03-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          providerInstances: {
+            [ProviderInstanceId.make("claudeAgent")]: {
+              driver: ProviderDriverKind.make("claudeAgent"),
+              config: { homePath: claudeInstanceHome },
+            },
+            [ProviderInstanceId.make("codex")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: codexInstanceHome },
+            },
+          },
+        });
+
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([
+          codexWorkspace,
+          claudeWorkspace,
+        ]);
+      }),
+    );
+
+    it.effect("scans each distinct home across multiple instances once", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const otherCodexHome = yield* makeTempDir("t3code-codex-other-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const otherWorkspace = yield* makeTempDir("t3code-workspace-other-");
+
+        for (const [home, cwd] of [
+          [codexHomePath, workspace],
+          [otherCodexHome, otherWorkspace],
+        ] as const) {
+          yield* writeTranscript({
+            filePath: path.join(home, "sessions", "2026", "01", "01", "rollout-session.jsonl"),
+            contents: codexRolloutLine(cwd),
+            mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+          });
+        }
+
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          providerInstances: {
+            [ProviderInstanceId.make("codex-personal")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: codexHomePath },
+            },
+            [ProviderInstanceId.make("codex-work")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: otherCodexHome },
+            },
+          },
+        });
+
+        expect(result.candidates).toHaveLength(2);
+        expect(result.candidates.map((candidate) => candidate.threadCount)).toEqual([1, 1]);
+        expect(result.candidates.map((candidate) => candidate.path).sort()).toEqual(
+          [workspace, otherWorkspace].sort(),
+        );
+      }),
+    );
+
+    it.effect("honors provider instance home directory environment variables", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-legacy-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-legacy-");
+        const claudeEnvironmentHome = yield* makeTempDir("t3code-claude-env-");
+        const codexEnvironmentHome = yield* makeTempDir("t3code-codex-env-");
+        const claudeWorkspace = yield* makeTempDir("t3code-workspace-claude-");
+        const codexWorkspace = yield* makeTempDir("t3code-workspace-codex-");
+
+        yield* writeTranscript({
+          filePath: path.join(claudeEnvironmentHome, "projects", "-actual", "session.jsonl"),
+          contents: claudeSessionLine(claudeWorkspace),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(
+            codexEnvironmentHome,
+            "sessions",
+            "2026",
+            "01",
+            "01",
+            "rollout-session.jsonl",
+          ),
+          contents: codexRolloutLine(codexWorkspace),
+          mtimeMs: Date.parse("2026-01-02T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          providerInstances: {
+            [ProviderInstanceId.make("claudeAgent")]: {
+              driver: ProviderDriverKind.make("claudeAgent"),
+              environment: [
+                { name: "CLAUDE_CONFIG_DIR", value: claudeEnvironmentHome, sensitive: false },
+              ],
+              config: {},
+            },
+            [ProviderInstanceId.make("codex")]: {
+              driver: ProviderDriverKind.make("codex"),
+              environment: [{ name: "CODEX_HOME", value: codexEnvironmentHome, sensitive: false }],
+              config: {},
+            },
+          },
+        });
+
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([
+          codexWorkspace,
+          claudeWorkspace,
+        ]);
+      }),
+    );
+
+    it.effect("ignores invalid provider instances while scanning the remaining providers", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-actual", "session.jsonl"),
+          contents: claudeSessionLine(workspace),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          providerInstances: {
+            [ProviderInstanceId.make("codex")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: 123 },
+            },
+          },
+        });
+
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([workspace]);
+      }),
+    );
+
+    it.effect("does not scan provider instances disabled by the envelope or config", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const envelopeDisabledHome = yield* makeTempDir("t3code-codex-disabled-envelope-");
+        const configDisabledHome = yield* makeTempDir("t3code-codex-disabled-config-");
+        const envelopeWorkspace = yield* makeTempDir("t3code-workspace-disabled-envelope-");
+        const configWorkspace = yield* makeTempDir("t3code-workspace-disabled-config-");
+
+        for (const [home, workspace, session] of [
+          [envelopeDisabledHome, envelopeWorkspace, "envelope-disabled"],
+          [configDisabledHome, configWorkspace, "config-disabled"],
+        ] as const) {
+          yield* writeTranscript({
+            filePath: path.join(home, "sessions", "2026", "08", "24", `rollout-${session}.jsonl`),
+            contents: codexRolloutLine(workspace),
+            mtimeMs: Date.parse("2026-08-24T12:00:00.000Z"),
+          });
+        }
+
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          providerInstances: {
+            [ProviderInstanceId.make("codex-envelope-disabled")]: {
+              driver: ProviderDriverKind.make("codex"),
+              enabled: false,
+              config: { homePath: envelopeDisabledHome },
+            },
+            [ProviderInstanceId.make("codex-config-disabled")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { enabled: false, homePath: configDisabledHome },
+            },
+          },
+        });
+
+        expect(result.candidates).toEqual([]);
+      }),
+    );
+
+    it.effect("ignores relative working directories from malformed transcripts", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-relative", "session.jsonl"),
+          contents: claudeSessionLine(path.relative(path.resolve(), workspace)),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(result.candidates).toEqual([]);
+      }),
+    );
+
+    it.effect("drops candidates whose directory no longer exists", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents: claudeSessionLine(path.join(claudeHomePath, "does-not-exist")),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(result.candidates).toEqual([]);
+      }),
+    );
+
+    it.effect("excludes the home directory, temporary root, and T3 data directory", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const configBaseDir = yield* makeTempDir("t3code-scanner-base-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        for (const [index, cwd] of [
+          NodeOS.homedir(),
+          NodeOS.tmpdir(),
+          configBaseDir,
+          workspace,
+        ].entries()) {
+          yield* writeTranscript({
+            filePath: path.join(claudeHomePath, "projects", `-slug-${index}`, "session.jsonl"),
+            contents: claudeSessionLine(cwd),
+            mtimeMs: Date.parse("2026-01-01T00:00:00.000Z") + index,
+          });
+        }
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath, configBaseDir });
+
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([workspace]);
+      }),
+    );
+
+    it.effect("excludes T3-managed worktree sandboxes", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const fileSystem = yield* FileSystem.FileSystem;
+
+        const worktreeCwd = path.join(claudeHomePath, ".t3", "worktrees", "t3code", "wt-1");
+        yield* fileSystem.makeDirectory(worktreeCwd, { recursive: true });
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents: claudeSessionLine(worktreeCwd),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(result.candidates).toEqual([]);
+      }),
+    );
+
+    it.effect("excludes sandboxes under the configured worktrees dir without .t3 in the path", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const configBaseDir = yield* makeTempDir("t3code-scanner-base-");
+        const fileSystem = yield* FileSystem.FileSystem;
+
+        // worktreesDir derives as `<baseDir>/worktrees`, and the temp base
+        // dir contains no `.t3` segment — only the config-based prefix match
+        // can exclude this one.
+        const worktreeCwd = path.join(configBaseDir, "worktrees", "t3code", "wt-2");
+        yield* fileSystem.makeDirectory(worktreeCwd, { recursive: true });
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents: claudeSessionLine(worktreeCwd),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath, configBaseDir });
+
+        expect(result.candidates).toEqual([]);
+      }),
+    );
+
+    it.effect("excludes sandboxes reached through a symlink into the worktrees dir", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const configBaseDir = yield* makeTempDir("t3code-scanner-base-");
+        const linkParent = yield* makeTempDir("t3code-scanner-links-");
+        const fileSystem = yield* FileSystem.FileSystem;
+
+        // The recorded cwd is a symlink whose own spelling looks harmless;
+        // only its realpath reveals the managed sandbox.
+        const worktreeCwd = path.join(configBaseDir, "worktrees", "t3code", "wt-3");
+        yield* fileSystem.makeDirectory(worktreeCwd, { recursive: true });
+        const symlinkCwd = path.join(linkParent, "innocent-project");
+        yield* fileSystem.symlink(worktreeCwd, symlinkCwd);
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents: claudeSessionLine(symlinkCwd),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath, configBaseDir });
+
+        expect(result.candidates).toEqual([]);
+      }),
+    );
+
+    it.effect("finds the cwd on a later line when the first records carry none", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        // Claude transcripts often open with records that have no cwd.
+        const contents = `{"type":"file-history-snapshot","messageId":"m1"}\n{"type":"queue-operation","operation":"enqueue"}\n${claudeSessionLine(workspace)}`;
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-slug", "a.jsonl"),
+          contents,
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([workspace]);
+      }),
+    );
+
+    it.effect("reads a complete transcript record at the exact chunk boundary", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const record = claudeSessionLine(workspace).split("\n")[0]!;
+        const prefix = '{"padding":"';
+        const suffix = `",${record.slice(1)}`;
+        const contents = `${prefix}${"x".repeat(32 * 1024 - prefix.length - suffix.length)}${suffix}`;
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-exact", "session.jsonl"),
+          contents,
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(contents).toHaveLength(32 * 1024);
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([workspace]);
+      }),
+    );
+
+    it.effect("finds session metadata after a first record larger than one chunk", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const history = `{"type":"file-history-snapshot","data":"${"x".repeat(32 * 1024)}"}\n`;
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-large", "session.jsonl"),
+          contents: `${history}${claudeSessionLine(workspace)}`,
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([workspace]);
+      }),
+    );
+
+    it.effect.each([64, 65])("shares metadata bytes across homes for %s one-MiB files", (count) =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const claudeHomePath = yield* makeTempDir("t3code-metadata-home-");
+        const secondHome = yield* makeTempDir("t3code-metadata-second-");
+        const codexHomePath = yield* makeTempDir("t3code-metadata-codex-");
+        const firstWorkspace = yield* makeTempDir("t3code-metadata-first-project-");
+        const secondWorkspace = yield* makeTempDir("t3code-metadata-second-project-");
+        const directories = [
+          path.join(claudeHomePath, "projects", "p"),
+          path.join(secondHome, "projects", "p"),
+        ];
+        const templates = directories.map((directory) => path.join(directory, "template.jsonl"));
+        for (const [index, workspace] of [firstWorkspace, secondWorkspace].entries()) {
+          const record = encodeTranscriptRecord({ cwd: workspace });
+          yield* writeTranscript({
+            filePath: templates[index]!,
+            contents:
+              " ".repeat(1024 * 1024 - new TextEncoder().encode(record).byteLength) + record,
+            mtimeMs: Date.parse("2026-01-01T00:00:00.000Z") - index * 1_000,
+          });
+        }
+        const resolveFile = (filePath: string) => {
+          const index = directories.indexOf(path.dirname(filePath));
+          return index === -1 ? filePath : templates[index]!;
+        };
+        let reservedBytes = 0;
+        let opens = 0;
+        const requests: number[] = [];
+        const observedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          readDirectory: (directory, options) => {
+            const index = directories.indexOf(directory);
+            return index === -1
+              ? fileSystem.readDirectory(directory, options)
+              : Effect.succeed(
+                  Array.from(
+                    { length: index === 0 ? 32 : count - 32 },
+                    (_, item) => `session-${item}.jsonl`,
+                  ),
+                );
+          },
+          stat: (filePath) => fileSystem.stat(resolveFile(filePath)),
+          open: (filePath, options) => {
+            if (!directories.includes(path.dirname(filePath)))
+              return fileSystem.open(filePath, options);
+            opens += 1;
+            return fileSystem.open(resolveFile(filePath), options).pipe(
+              Effect.map((file) => ({
+                ...file,
+                stat: file.stat,
+                readAlloc: (size: FileSystem.SizeInput) => {
+                  reservedBytes += Number(size);
+                  requests.push(Number(size));
+                  return file.readAlloc(size);
+                },
+              })),
+            );
+          },
+        });
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          providerInstances: {
+            [ProviderInstanceId.make("claude-work")]: {
+              driver: ProviderDriverKind.make("claudeAgent"),
+              config: { homePath: secondHome },
+            },
+          },
+        }).pipe(Effect.provideService(FileSystem.FileSystem, observedFileSystem));
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([
+          firstWorkspace,
+          secondWorkspace,
+        ]);
+        expect(result.candidates.map((candidate) => candidate.threadCount)).toEqual([32, 32]);
+        expect(result.truncated).toBe(count === 65 ? true : undefined);
+        expect(opens).toBe(64);
+        expect(reservedBytes).toBe(64 * 1024 * 1024);
+        expect(requests[0]).toBe(8 * 1024);
+        expect(Math.max(...requests)).toBe(8 * 1024);
+      }),
+    );
+
+    it.effect.each([50, 51])("bounds metadata open/read calls for %s short-read files", (count) =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const claudeHomePath = yield* makeTempDir("t3code-short-metadata-home-");
+        const codexHomePath = yield* makeTempDir("t3code-short-metadata-codex-");
+        const workspace = yield* makeTempDir("t3code-short-metadata-project-");
+        const directory = path.join(claudeHomePath, "projects", "p");
+        const template = path.join(directory, "template.jsonl");
+        const record = encodeTranscriptRecord({ cwd: workspace });
+        const contents = " ".repeat(399 - new TextEncoder().encode(record).byteLength) + record;
+        const bytes = new TextEncoder().encode(contents);
+        yield* writeTranscript({
+          filePath: template,
+          contents,
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+        let operations = 0;
+        const observedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          readDirectory: (target, options) =>
+            target === directory
+              ? Effect.succeed(
+                  Array.from({ length: count }, (_, index) => `session-${index}.jsonl`),
+                )
+              : fileSystem.readDirectory(target, options),
+          stat: (filePath) =>
+            fileSystem.stat(path.dirname(filePath) === directory ? template : filePath),
+          open: (filePath, options) => {
+            if (path.dirname(filePath) !== directory) return fileSystem.open(filePath, options);
+            operations += 1;
+            let offset = 0;
+            return fileSystem.open(template, options).pipe(
+              Effect.map((file) => ({
+                ...file,
+                stat: file.stat,
+                readAlloc: () =>
+                  Effect.sync(() => {
+                    operations += 1;
+                    if (offset === bytes.length) return Option.none<Uint8Array>();
+                    return Option.some(bytes.subarray(offset, ++offset));
+                  }),
+              })),
+            );
+          },
+        });
+        const result = yield* runScan({ claudeHomePath, codexHomePath }).pipe(
+          Effect.provideService(FileSystem.FileSystem, observedFileSystem),
+        );
+        expect(operations).toBe(20_000);
+        expect(result.candidates[0]?.threadCount).toBe(50);
+        expect(result.truncated).toBe(count === 51 ? true : undefined);
+      }),
+    );
+
+    it.effect("bounds malformed metadata records without excluding another account", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const claudeHomePath = yield* makeTempDir("t3code-record-metadata-home-");
+        const secondHome = yield* makeTempDir("t3code-record-metadata-second-");
+        const codexHomePath = yield* makeTempDir("t3code-record-metadata-codex-");
+        const workspace = yield* makeTempDir("t3code-record-metadata-project-");
+        const directory = path.join(claudeHomePath, "projects", "p");
+        const template = path.join(directory, "template.jsonl");
+        yield* writeTranscript({
+          filePath: template,
+          contents: "x\n".repeat(1_001),
+          mtimeMs: Date.parse("2026-01-02T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(secondHome, "projects", "p", "session.jsonl"),
+          contents: encodeTranscriptRecord({ cwd: workspace }),
+          mtimeMs: Date.parse("2026-01-01T00:00:00.000Z"),
+        });
+        let malformedOpens = 0;
+        const observedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          readDirectory: (target, options) =>
+            target === directory
+              ? Effect.succeed(Array.from({ length: 102 }, (_, index) => `session-${index}.jsonl`))
+              : fileSystem.readDirectory(target, options),
+          stat: (filePath) =>
+            fileSystem.stat(path.dirname(filePath) === directory ? template : filePath),
+          open: (filePath, options) => {
+            if (path.dirname(filePath) !== directory) return fileSystem.open(filePath, options);
+            malformedOpens += 1;
+            return fileSystem.open(template, options);
+          },
+        });
+        const result = yield* runScan({
+          claudeHomePath,
+          codexHomePath,
+          providerInstances: {
+            [ProviderInstanceId.make("claude-work")]: {
+              driver: ProviderDriverKind.make("claudeAgent"),
+              config: { homePath: secondHome },
+            },
+          },
+        }).pipe(Effect.provideService(FileSystem.FileSystem, observedFileSystem));
+        expect(result.candidates.map((candidate) => candidate.path)).toEqual([workspace]);
+        expect(malformedOpens).toBe(100);
+        expect(result.truncated).toBe(true);
+      }),
+    );
+
+    it.effect.each([19_999, 20_000])(
+      "reports unfinished directory work for %s project directories",
+      (count) =>
+        Effect.gen(function* () {
+          const path = yield* Path.Path;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const claudeHomePath = yield* makeTempDir("t3code-directory-budget-home-");
+          const codexHomePath = yield* makeTempDir("t3code-directory-budget-codex-");
+          const projectsDir = path.join(claudeHomePath, "projects");
+          let reads = 0;
+          const observedFileSystem = FileSystem.FileSystem.of({
+            ...fileSystem,
+            readDirectory: (directory, options) => {
+              if (directory === projectsDir) {
+                reads += 1;
+                return Effect.succeed(
+                  Array.from({ length: count }, (_, index) => `project-${index}`),
+                );
+              }
+              if (path.dirname(directory) === projectsDir) {
+                reads += 1;
+                return Effect.succeed([]);
+              }
+              return fileSystem.readDirectory(directory, options);
+            },
+          });
+          const result = yield* runScan({ claudeHomePath, codexHomePath }).pipe(
+            Effect.provideService(FileSystem.FileSystem, observedFileSystem),
+          );
+          expect(reads).toBe(20_000);
+          expect(result.candidates).toEqual([]);
+          expect(result.truncated).toBe(count === 20_000 ? true : undefined);
+        }),
+    );
+
+    it.effect("skips malformed transcripts without failing the scan", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-broken", "a.jsonl"),
+          contents: "not json at all\n",
+          mtimeMs: Date.parse("2026-05-01T00:00:00.000Z"),
+        });
+        // Valid JSON, but no cwd anywhere in the record.
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-no-cwd", "a.jsonl"),
+          contents: `{"type":"summary"}\n`,
+          mtimeMs: Date.parse("2026-05-02T00:00:00.000Z"),
+        });
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-good", "a.jsonl"),
+          contents: claudeSessionLine(workspace),
+          mtimeMs: Date.parse("2026-05-03T00:00:00.000Z"),
+        });
+
+        const result = yield* runScan({ claudeHomePath, codexHomePath });
+
+        expect(result.candidates).toEqual([
+          {
+            path: workspace,
+            title: path.basename(workspace),
+            sources: ["claudeAgent"],
+            threadCount: 1,
+            lastActiveAt: "2026-05-03T00:00:00.000Z",
+            alreadyImported: false,
+          },
+        ]);
+      }),
+    );
+
+    it.effect("returns an empty result when neither home directory exists", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const root = yield* makeTempDir("t3code-missing-homes-");
+
+        const result = yield* runScan({
+          claudeHomePath: path.join(root, "no-claude"),
+          codexHomePath: path.join(root, "no-codex"),
+        });
+
+        expect(result.candidates).toEqual([]);
+        expect(result.scannedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+      }),
+    );
+  });
+
+  describe("recentThreads", () => {
+    it.effect.each([false, true])(
+      "counts terminal newlines correctly with record overflow=%s",
+      (overflow) =>
+        Effect.gen(function* () {
+          const path = yield* Path.Path;
+          const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+          yield* TestClock.setTime(nowMs);
+          const claudeHomePath = yield* makeTempDir("t3code-record-limit-claude-");
+          const codexHomePath = yield* makeTempDir("t3code-record-limit-codex-");
+          const workspace = yield* makeTempDir("t3code-record-limit-project-");
+          const directory = path.join(codexHomePath, "sessions", "2026", "08", "24");
+          yield* writeTranscript({
+            filePath: path.join(directory, "rollout-records.jsonl"),
+            contents: makeRecordLimitTranscript(workspace, overflow),
+            mtimeMs: nowMs,
+          });
+          yield* writeTranscript({
+            filePath: path.join(directory, "rollout-older.jsonl"),
+            contents: [
+              encodeTranscriptRecord({
+                type: "session_meta",
+                payload: { id: "older-session", cwd: workspace },
+              }),
+              encodeTranscriptRecord({
+                type: "event_msg",
+                payload: { type: "user_message", message: "Older prompt" },
+              }),
+            ].join("\n"),
+            mtimeMs: nowMs - 1_000,
+          });
+          const outcomes = yield* runRecentThreadOutcomes({
+            claudeHomePath,
+            codexHomePath,
+            workspaceRoot: workspace,
+          });
+          expect(outcomes.map((outcome) => outcome._tag)).toEqual(
+            overflow ? ["Skipped", "Importable"] : ["Importable", "Skipped"],
+          );
+          expect(
+            outcomes.flatMap((outcome) =>
+              outcome._tag === "Importable"
+                ? outcome.thread.messages.map((message) => message.text)
+                : [],
+            ),
+          ).toEqual([overflow ? "Older prompt" : "First prompt"]);
+        }),
+    );
+
+    it.effect("imports recent Claude and Codex sessions for the selected project only", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const otherWorkspace = yield* makeTempDir("t3code-workspace-other-");
+
+        const claudeTranscript = (cwd: string, sessionId: string) =>
+          `${JSON.stringify({
+            type: "user",
+            cwd,
+            sessionId,
+            timestamp: "2026-08-23T12:00:00.000Z",
+            message: { role: "user", content: "Fix the project" },
+          })}\n${JSON.stringify({
+            type: "assistant",
+            sessionId,
+            timestamp: "2026-08-23T12:01:00.000Z",
+            message: { role: "assistant", content: [{ type: "text", text: "Done" }] },
+          })}\n`;
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-selected", "claude-recent.jsonl"),
+          contents: claudeTranscript(workspace, "claude-recent"),
+          mtimeMs: nowMs - 24 * 60 * 60 * 1000,
+        });
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-selected", "claude-old.jsonl"),
+          contents: claudeTranscript(workspace, "claude-old"),
+          mtimeMs: nowMs - 31 * 24 * 60 * 60 * 1000,
+        });
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-other", "claude-other.jsonl"),
+          contents: claudeTranscript(otherWorkspace, "claude-other"),
+          mtimeMs: nowMs - 24 * 60 * 60 * 1000,
+        });
+        yield* writeTranscript({
+          filePath: path.join(
+            codexHomePath,
+            "sessions",
+            "2026",
+            "08",
+            "24",
+            "rollout-codex-recent.jsonl",
+          ),
+          contents: [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: "codex-recent", cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              timestamp: "2026-08-24T10:00:00.000Z",
+              payload: { type: "user_message", message: "Review this code" },
+            }),
+            encodeTranscriptRecord({
+              type: "response_item",
+              timestamp: "2026-08-24T10:01:00.000Z",
+              payload: {
+                type: "message",
+                role: "assistant",
+                content: [{ type: "output_text", text: "Looks good" }],
+              },
+            }),
+          ].join("\n"),
+          mtimeMs: nowMs - 60 * 60 * 1000,
+        });
+
+        const threads = yield* runRecentThreads({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        });
+
+        expect(threads.map((thread) => thread.providerSessionId)).toEqual([
+          "codex-recent",
+          "claude-recent",
+        ]);
+        expect(threads.map((thread) => thread.messages.map((message) => message.text))).toEqual([
+          ["Review this code", "Looks good"],
+          ["Fix the project", "Done"],
+        ]);
+      }),
+    );
+
+    it.effect("imports history recorded with a case alias", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const workspaceAlias = path.join(
+          path.dirname(workspace),
+          path.basename(workspace).toUpperCase(),
+        );
+
+        yield* writeTranscript({
+          filePath: path.join(claudeHomePath, "projects", "-alias", "case-session.jsonl"),
+          contents: [
+            encodeTranscriptRecord({
+              type: "user",
+              cwd: workspaceAlias,
+              sessionId: "case-session",
+              timestamp: "2026-08-24T10:00:00.000Z",
+              message: { role: "user", content: "Import case alias history" },
+            }),
+            encodeTranscriptRecord({
+              type: "assistant",
+              sessionId: "case-session",
+              timestamp: "2026-08-24T10:01:00.000Z",
+              message: { role: "assistant", content: "Imported" },
+            }),
+          ].join("\n"),
+          mtimeMs: nowMs,
+        });
+
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          stat: (filePath) => fileSystem.stat(filePath === workspaceAlias ? workspace : filePath),
+        });
+        const threads = yield* runRecentThreads({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        }).pipe(Effect.provideService(FileSystem.FileSystem, simulatedFileSystem));
+
+        expect(threads.map((thread) => thread.providerSessionId)).toEqual(["case-session"]);
+      }),
+    );
+
+    it.effect("keeps the provider instance that owns a custom session home", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const customHome = yield* makeTempDir("t3code-codex-custom-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        yield* writeTranscript({
+          filePath: path.join(customHome, "sessions", "2026", "08", "24", "rollout-custom.jsonl"),
+          contents: [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: "custom-session", cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: "Use my work account" },
+            }),
+          ].join("\n"),
+          mtimeMs: nowMs,
+        });
+
+        const threads = yield* runRecentThreads({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+          providerInstances: {
+            [ProviderInstanceId.make("codex-work")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: customHome },
+            },
+          },
+        });
+
+        expect(threads[0]?.providerInstanceId).toBe("codex-work");
+      }),
+    );
+
+    it.effect("suppresses duplicate session copies without reporting a skipped import", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const contents = [
+          encodeTranscriptRecord({
+            type: "session_meta",
+            payload: { id: "copied-session", cwd: workspace },
+          }),
+          encodeTranscriptRecord({
+            type: "event_msg",
+            payload: { type: "user_message", message: "Import this session once" },
+          }),
+        ].join("\n");
+
+        for (const [name, mtimeMs] of [
+          ["rollout-copy-a.jsonl", nowMs],
+          ["rollout-copy-b.jsonl", nowMs - 1],
+        ] as const) {
+          yield* writeTranscript({
+            filePath: path.join(codexHomePath, "sessions", "2026", "08", "24", name),
+            contents,
+            mtimeMs,
+          });
+        }
+
+        const outcomes = yield* runRecentThreadOutcomes({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        });
+
+        expect(outcomes.map((outcome) => outcome._tag)).toEqual(["Importable", "Duplicate"]);
+        expect(outcomes[0]).toMatchObject({
+          _tag: "Importable",
+          thread: { providerSessionId: "copied-session" },
+        });
+      }),
+    );
+
+    it.effect("shares a 64 MiB full-read budget across providers without hiding projects", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-budget-claude-");
+        const codexHomePath = yield* makeTempDir("t3code-budget-codex-");
+        const workspace = yield* makeTempDir("t3code-budget-workspace-");
+        const transcriptPaths = new Set<string>();
+        for (const [index, source] of [
+          "codex",
+          "claudeAgent",
+          "codex",
+          "claudeAgent",
+          "codex",
+        ].entries()) {
+          const sessionId = `budget-session-${index}`;
+          const filePath =
+            source === "codex"
+              ? path.join(
+                  codexHomePath,
+                  "sessions",
+                  "2026",
+                  "08",
+                  "24",
+                  `rollout-${sessionId}.jsonl`,
+                )
+              : path.join(claudeHomePath, "projects", "selected", `${sessionId}.jsonl`);
+          const contents =
+            source === "codex"
+              ? [
+                  encodeTranscriptRecord({
+                    type: "session_meta",
+                    payload: { id: sessionId, cwd: workspace },
+                  }),
+                  encodeTranscriptRecord({
+                    type: "event_msg",
+                    payload: { type: "user_message", message: "Imported prompt" },
+                  }),
+                ].join("\n")
+              : encodeTranscriptRecord({
+                  type: "user",
+                  cwd: workspace,
+                  sessionId,
+                  message: { content: "Imported prompt" },
+                });
+          transcriptPaths.add(filePath);
+          yield* writeTranscript({
+            filePath,
+            contents: `${contents}\n`.padEnd(16 * 1024 * 1024, " "),
+            mtimeMs: nowMs - index * 1_000,
+          });
+        }
+
+        const opens = new Map<string, number>();
+        let fullReadBytes = 0;
+        const trackedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          open: (filePath, options) => {
+            const count = (opens.get(filePath) ?? 0) + 1;
+            opens.set(filePath, count);
+            return fileSystem.open(filePath, options).pipe(
+              Effect.map((file) =>
+                !transcriptPaths.has(filePath) || count === 1
+                  ? file
+                  : {
+                      ...file,
+                      stat: file.stat,
+                      readAlloc: (size: FileSystem.SizeInput) =>
+                        file.readAlloc(size).pipe(
+                          Effect.tap((chunk) =>
+                            Effect.sync(() => {
+                              if (chunk._tag === "Some") fullReadBytes += chunk.value.byteLength;
+                            }),
+                          ),
+                        ),
+                    },
+              ),
+            );
+          },
+        });
+        const outcomes = yield* Effect.gen(function* () {
+          const scanner = yield* AgentSessionScanner.AgentSessionScanner;
+          const scan = yield* scanner.scan;
+          expect(scan.candidates[0]?.threadCount).toBe(5);
+          return yield* scanner.recentThreads(workspace).pipe(Stream.runCollect);
+        }).pipe(
+          Effect.provide(makeScannerTestLayer({ claudeHomePath, codexHomePath })),
+          Effect.provideService(FileSystem.FileSystem, trackedFileSystem),
+        );
+
+        expect(outcomes.map((outcome) => outcome._tag)).toEqual([
+          "Importable",
+          "Importable",
+          "Importable",
+          "Importable",
+          "Skipped",
+        ]);
+        expect(fullReadBytes).toBe(64 * 1024 * 1024);
+      }),
+    );
+
+    it.effect("skips excessive records without blocking an older valid transcript", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-record-budget-claude-");
+        const codexHomePath = yield* makeTempDir("t3code-record-budget-codex-");
+        const workspace = yield* makeTempDir("t3code-record-budget-workspace-");
+        for (const [sessionId, padding, mtimeMs] of [
+          ["excessive", "\n".repeat(100_001), nowMs],
+          ["older", "", nowMs - 1_000],
+        ] as const) {
+          yield* writeTranscript({
+            filePath: path.join(
+              codexHomePath,
+              "sessions",
+              "2026",
+              "08",
+              "24",
+              `rollout-${sessionId}.jsonl`,
+            ),
+            contents:
+              [
+                encodeTranscriptRecord({
+                  type: "session_meta",
+                  payload: { id: sessionId, cwd: workspace },
+                }),
+                encodeTranscriptRecord({
+                  type: "event_msg",
+                  payload: { type: "user_message", message: "Imported prompt" },
+                }),
+              ].join("\n") + padding,
+            mtimeMs,
+          });
+        }
+        const outcomes = yield* runRecentThreadOutcomes({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        });
+        expect(outcomes.map((outcome) => outcome._tag)).toEqual(["Skipped", "Importable"]);
+        expect(outcomes[1]).toMatchObject({ thread: { providerSessionId: "older" } });
+      }),
+    );
+
+    for (const source of ["claudeAgent", "codex"] as const) {
+      for (const replacement of [
+        "same root",
+        "other root",
+        "symlink alias",
+        "other then same",
+      ] as const) {
+        it.effect.skipIf(replacement === "symlink alias" && !symlinksSupported)(
+          `rechecks ${source} snapshot cwd after replacement with ${replacement}`,
+          () =>
+            Effect.gen(function* () {
+              const path = yield* Path.Path;
+              const fileSystem = yield* FileSystem.FileSystem;
+              const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+              yield* TestClock.setTime(nowMs);
+              const fixture = yield* makeTempDir("t3code-replaced-cwd-");
+              const workspace = path.join(fixture, "original");
+              const otherWorkspace = path.join(fixture, "other");
+              const alias = path.join(fixture, "alias");
+              const claudeHomePath = path.join(fixture, "claude");
+              const codexHomePath = path.join(fixture, "codex");
+              yield* fileSystem.makeDirectory(workspace);
+              yield* fileSystem.makeDirectory(otherWorkspace);
+              if (replacement === "symlink alias") yield* fileSystem.symlink(workspace, alias);
+              const filePath =
+                source === "codex"
+                  ? path.join(
+                      codexHomePath,
+                      "sessions",
+                      "2026",
+                      "08",
+                      "24",
+                      "rollout-replaced.jsonl",
+                    )
+                  : path.join(claudeHomePath, "projects", "p", "replaced.jsonl");
+              const makeContents = (cwd: string, text: string, laterCwd?: string) =>
+                [
+                  ...(source === "codex"
+                    ? [
+                        { type: "session_meta", payload: { id: "replacement-session", cwd } },
+                        { type: "event_msg", payload: { type: "user_message", message: text } },
+                      ]
+                    : [
+                        {
+                          type: "user",
+                          cwd,
+                          sessionId: "replacement-session",
+                          message: { content: text },
+                        },
+                      ]),
+                  ...(laterCwd === undefined ? [] : [{ cwd: laterCwd }]),
+                ]
+                  .map((record) => encodeTranscriptRecord(record))
+                  .join("\n");
+              yield* writeTranscript({
+                filePath,
+                contents: makeContents(workspace, "Original prompt"),
+                mtimeMs: nowMs,
+              });
+
+              yield* Effect.gen(function* () {
+                const scanner = yield* AgentSessionScanner.AgentSessionScanner;
+                const scan = yield* scanner.scan;
+                expect(scan.candidates.map((candidate) => candidate.path)).toEqual([workspace]);
+                const replacementCwd =
+                  replacement === "symlink alias"
+                    ? alias
+                    : replacement === "same root"
+                      ? workspace
+                      : otherWorkspace;
+                yield* fileSystem.remove(filePath);
+                yield* writeTranscript({
+                  filePath,
+                  contents: makeContents(
+                    replacementCwd,
+                    "Replacement prompt",
+                    replacement === "other then same" ? workspace : undefined,
+                  ),
+                  mtimeMs: nowMs,
+                });
+                const outcomes = yield* scanner.recentThreads(workspace).pipe(Stream.runCollect);
+                if (replacement === "same root" || replacement === "symlink alias") {
+                  expect(outcomes).toHaveLength(1);
+                  expect(outcomes[0]).toMatchObject({
+                    _tag: "Importable",
+                    thread: { messages: [{ text: "Replacement prompt" }] },
+                  });
+                } else {
+                  expect(outcomes).toEqual([{ _tag: "Skipped" }]);
+                }
+              }).pipe(Effect.provide(makeScannerTestLayer({ claudeHomePath, codexHomePath })));
+            }),
+        );
+      }
+    }
+
+    it.effect("checks file identity and provider before skipping completed history", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-completed-claude-");
+        const codexHomePath = yield* makeTempDir("t3code-completed-codex-");
+        const workspace = yield* makeTempDir("t3code-completed-workspace-");
+        const filePath = path.join(
+          codexHomePath,
+          "sessions",
+          "2026",
+          "08",
+          "24",
+          "rollout-replaced.jsonl",
+        );
+        const contents = (sessionId: string) =>
+          [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: sessionId, cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: "Imported prompt" },
+            }),
+          ].join("\n");
+        yield* writeTranscript({
+          filePath,
+          contents: contents("original-session"),
+          mtimeMs: nowMs,
+        });
+
+        yield* Effect.gen(function* () {
+          const scanner = yield* AgentSessionScanner.AgentSessionScanner;
+          const initial = yield* scanner.recentThreads(workspace).pipe(Stream.runCollect);
+          const imported = initial[0];
+          expect(imported?._tag).toBe("Importable");
+          if (imported?._tag !== "Importable") return;
+          const completed = yield* scanner
+            .recentThreads(workspace, [imported.source])
+            .pipe(Stream.runCollect);
+          expect(completed[0]?._tag).toBe("AlreadyImported");
+          const wrongProvider = yield* scanner
+            .recentThreads(workspace, [{ ...imported.source, provider: "claudeAgent" }])
+            .pipe(Stream.runCollect);
+          expect(wrongProvider[0]?._tag).toBe("Importable");
+
+          // Keep the old inode allocated while replacing the path with an equal-size file.
+          yield* fileSystem.open(filePath);
+          yield* fileSystem.remove(filePath);
+          yield* writeTranscript({
+            filePath,
+            contents: contents("replaced-session"),
+            mtimeMs: nowMs,
+          });
+          const replaced = yield* scanner
+            .recentThreads(workspace, [imported.source])
+            .pipe(Stream.runCollect);
+          expect(replaced[0]).toMatchObject({
+            _tag: "Importable",
+            thread: { providerSessionId: "replaced-session" },
+            source: { size: imported.source.size, mtimeMs: imported.source.mtimeMs },
+          });
+        }).pipe(Effect.provide(makeScannerTestLayer({ claudeHomePath, codexHomePath })));
+      }),
+    );
+
+    it.effect("reports an eligible transcript over 16 MiB as skipped", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const transcript = [
+          encodeTranscriptRecord({
+            type: "session_meta",
+            payload: { id: "large-session", cwd: workspace },
+          }),
+          encodeTranscriptRecord({
+            type: "event_msg",
+            payload: { type: "user_message", message: "Import this large session" },
+          }),
+        ]
+          .join("\n")
+          .padEnd(16 * 1024 * 1024 + 1, " ");
+        yield* writeTranscript({
+          filePath: path.join(codexHomePath, "sessions", "2026", "08", "24", "rollout-large.jsonl"),
+          contents: transcript,
+          mtimeMs: nowMs,
+        });
+
+        const outcomes = yield* runRecentThreadOutcomes({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        });
+
+        expect(outcomes).toEqual([{ _tag: "Skipped" }]);
+      }),
+    );
+
+    it.effect("reports stat, read, and parse failures as skipped", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const missingPath = path.join(codexHomePath, "missing.jsonl");
+        const transcriptPaths = {
+          stat: path.join(codexHomePath, "sessions", "2026", "08", "24", "rollout-stat.jsonl"),
+          read: path.join(codexHomePath, "sessions", "2026", "08", "24", "rollout-read.jsonl"),
+          parse: path.join(codexHomePath, "sessions", "2026", "08", "24", "rollout-parse.jsonl"),
+        };
+        const transcriptContents = (sessionId: string) =>
+          [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: sessionId, cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: "Import this session" },
+            }),
+          ].join("\n");
+
+        yield* writeTranscript({
+          filePath: transcriptPaths.stat,
+          contents: transcriptContents("stat-session"),
+          mtimeMs: nowMs,
+        });
+        yield* writeTranscript({
+          filePath: transcriptPaths.read,
+          contents: transcriptContents("read-session"),
+          mtimeMs: nowMs,
+        });
+        yield* writeTranscript({
+          filePath: transcriptPaths.parse,
+          contents: encodeTranscriptRecord({
+            type: "session_meta",
+            payload: { id: "parse-session", cwd: workspace },
+          }),
+          mtimeMs: nowMs,
+        });
+
+        let statCount = 0;
+        let readOpenCount = 0;
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          stat: (filePath) => {
+            if (filePath !== transcriptPaths.stat) return fileSystem.stat(filePath);
+            statCount += 1;
+            return fileSystem.stat(statCount === 1 ? filePath : missingPath);
+          },
+          open: (filePath, options) => {
+            if (filePath !== transcriptPaths.read) return fileSystem.open(filePath, options);
+            readOpenCount += 1;
+            return fileSystem.open(readOpenCount === 1 ? filePath : missingPath, options);
+          },
+        });
+
+        const outcomes = yield* runRecentThreadOutcomes({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        }).pipe(Effect.provideService(FileSystem.FileSystem, simulatedFileSystem));
+
+        expect(outcomes).toEqual([{ _tag: "Skipped" }, { _tag: "Skipped" }, { _tag: "Skipped" }]);
+      }),
+    );
+
+    it.effect("does not reopen a transcript that becomes a non-file after discovery", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const nonFilePath = yield* makeTempDir("t3code-non-file-");
+        const transcriptPath = path.join(
+          codexHomePath,
+          "sessions",
+          "2026",
+          "08",
+          "24",
+          "rollout-changed.jsonl",
+        );
+        yield* writeTranscript({
+          filePath: transcriptPath,
+          contents: [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: "changed-session", cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: "Do not import this session" },
+            }),
+          ].join("\n"),
+          mtimeMs: nowMs,
+        });
+
+        let transcriptStatCount = 0;
+        let transcriptOpenCount = 0;
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          stat: (filePath) => {
+            if (filePath !== transcriptPath) return fileSystem.stat(filePath);
+            transcriptStatCount += 1;
+            return fileSystem.stat(transcriptStatCount === 1 ? transcriptPath : nonFilePath);
+          },
+          open: (filePath, options) => {
+            if (filePath === transcriptPath) transcriptOpenCount += 1;
+            return fileSystem.open(filePath, options);
+          },
+        });
+
+        const outcomes = yield* runRecentThreadOutcomes({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        }).pipe(Effect.provideService(FileSystem.FileSystem, simulatedFileSystem));
+
+        expect(transcriptStatCount).toBe(2);
+        expect(transcriptOpenCount).toBe(1);
+        expect(outcomes).toEqual([{ _tag: "Skipped" }]);
+      }),
+    );
+
+    it.effect("does not import a transcript dated after the current time", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        yield* writeTranscript({
+          filePath: path.join(
+            codexHomePath,
+            "sessions",
+            "2026",
+            "08",
+            "24",
+            "rollout-future.jsonl",
+          ),
+          contents: [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: "future-session", cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: "Future work" },
+            }),
+          ].join("\n"),
+          mtimeMs: nowMs + 1,
+        });
+
+        const outcomes = yield* runRecentThreadOutcomes({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        });
+
+        expect(outcomes).toEqual([]);
+      }),
+    );
+
+    it.effect("skips growth during reading without exceeding the reserved bytes", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const transcriptPath = path.join(
+          codexHomePath,
+          "sessions",
+          "2026",
+          "08",
+          "24",
+          "rollout-growing.jsonl",
+        );
+        const contents = [
+          encodeTranscriptRecord({
+            type: "session_meta",
+            payload: { id: "growing-session", cwd: workspace },
+          }),
+          encodeTranscriptRecord({
+            type: "event_msg",
+            payload: { type: "user_message", message: "Do not import a changing file" },
+          }),
+        ].join("\n");
+        yield* writeTranscript({ filePath: transcriptPath, contents, mtimeMs: nowMs });
+        let transcriptOpenCount = 0;
+        let fullReadBytes = 0;
+        let grew = false;
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          open: (filePath, options) => {
+            if (filePath !== transcriptPath) return fileSystem.open(filePath, options);
+            transcriptOpenCount += 1;
+            if (transcriptOpenCount === 1) return fileSystem.open(filePath, options);
+            return fileSystem.open(filePath, options).pipe(
+              Effect.map((file) => ({
+                ...file,
+                stat: file.stat,
+                readAlloc: (size: FileSystem.SizeInput) =>
+                  file.readAlloc(size).pipe(
+                    Effect.tap((chunk) =>
+                      Effect.gen(function* () {
+                        if (chunk._tag === "None") return;
+                        fullReadBytes += chunk.value.byteLength;
+                        if (!grew) {
+                          grew = true;
+                          yield* fileSystem.writeFileString(filePath, `${contents}\nchanged`);
+                        }
+                      }),
+                    ),
+                  ),
+              })),
+            );
+          },
+        });
+
+        const outcomes = yield* runRecentThreadOutcomes({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        }).pipe(Effect.provideService(FileSystem.FileSystem, simulatedFileSystem));
+
+        expect(transcriptOpenCount).toBe(2);
+        expect(fullReadBytes).toBe(new TextEncoder().encode(contents).byteLength);
+        expect(outcomes).toEqual([{ _tag: "Skipped" }]);
+      }),
+    );
+
+    it.effect("skips a transcript that shrinks after its size check", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const transcriptPath = path.join(
+          codexHomePath,
+          "sessions",
+          "2026",
+          "08",
+          "24",
+          "rollout-shrinking.jsonl",
+        );
+        const shrunkPath = path.join(codexHomePath, "shrunk.jsonl");
+        const contents = [
+          encodeTranscriptRecord({
+            type: "session_meta",
+            payload: { id: "shrinking-session", cwd: workspace },
+          }),
+          encodeTranscriptRecord({
+            type: "event_msg",
+            payload: { type: "user_message", message: "Do not import a changing file" },
+          }),
+        ].join("\n");
+        yield* writeTranscript({
+          filePath: transcriptPath,
+          contents: `${contents}\n${"padding".repeat(100)}`,
+          mtimeMs: nowMs,
+        });
+        yield* writeTranscript({ filePath: shrunkPath, contents, mtimeMs: nowMs });
+
+        let transcriptOpenCount = 0;
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          open: (filePath, options) => {
+            if (filePath !== transcriptPath) return fileSystem.open(filePath, options);
+            transcriptOpenCount += 1;
+            return fileSystem.open(
+              transcriptOpenCount === 1 ? transcriptPath : shrunkPath,
+              options,
+            );
+          },
+        });
+
+        const outcomes = yield* runRecentThreadOutcomes({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+        }).pipe(Effect.provideService(FileSystem.FileSystem, simulatedFileSystem));
+
+        expect(transcriptOpenCount).toBe(2);
+        expect(outcomes).toEqual([{ _tag: "Skipped" }]);
+      }),
+    );
+
+    it.effect("does not read the second transcript when the consumer takes one thread", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+        const makeCodexTranscript = (sessionId: string, text: string) =>
+          [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: sessionId, cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: text },
+            }),
+          ].join("\n");
+        const olderPath = path.join(
+          codexHomePath,
+          "sessions",
+          "2026",
+          "08",
+          "23",
+          "rollout-older.jsonl",
+        );
+        const newerPath = path.join(
+          codexHomePath,
+          "sessions",
+          "2026",
+          "08",
+          "24",
+          "rollout-newer.jsonl",
+        );
+        yield* writeTranscript({
+          filePath: olderPath,
+          contents: makeCodexTranscript("older-session", "Older prompt"),
+          mtimeMs: nowMs - 1_000,
+        });
+        yield* writeTranscript({
+          filePath: newerPath,
+          contents: makeCodexTranscript("newer-session", "Newer prompt"),
+          mtimeMs: nowMs,
+        });
+
+        const openCounts = new Map<string, number>();
+        const contentReads: Array<string> = [];
+        const trackedPaths = new Set([olderPath, newerPath]);
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          open: (filePath, options) => {
+            if (trackedPaths.has(filePath)) {
+              const count = (openCounts.get(filePath) ?? 0) + 1;
+              openCounts.set(filePath, count);
+              if (count === 2) contentReads.push(filePath);
+            }
+            return fileSystem.open(filePath, options);
+          },
+        });
+
+        const threads = yield* Effect.gen(function* () {
+          const scanner = yield* AgentSessionScanner.AgentSessionScanner;
+          return yield* scanner.recentThreads(workspace).pipe(
+            Stream.take(1),
+            Stream.runCollect,
+            Effect.map((items) => Array.from(items)),
+          );
+        }).pipe(
+          Effect.provide(makeScannerTestLayer({ claudeHomePath, codexHomePath })),
+          Effect.provideService(FileSystem.FileSystem, simulatedFileSystem),
+        );
+
+        expect(
+          threads.flatMap((outcome) =>
+            outcome._tag === "Importable" ? [outcome.thread.providerSessionId] : [],
+          ),
+        ).toEqual(["newer-session"]);
+        expect(contentReads).toEqual([newerPath]);
+        expect(openCounts.get(olderPath)).toBe(1);
+      }),
+    );
+
+    it.effect("does not import sessions from a T3-managed worktree", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const configBaseDir = yield* makeTempDir("t3code-scanner-base-");
+        const workspace = path.join(configBaseDir, "worktrees", "t3code", "managed-worktree");
+        yield* fileSystem.makeDirectory(workspace, { recursive: true });
+
+        yield* writeTranscript({
+          filePath: path.join(
+            codexHomePath,
+            "sessions",
+            "2026",
+            "08",
+            "24",
+            "rollout-managed.jsonl",
+          ),
+          contents: [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: "managed-session", cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: "Do not import this session" },
+            }),
+          ].join("\n"),
+          mtimeMs: nowMs,
+        });
+
+        const threads = yield* runRecentThreads({
+          claudeHomePath,
+          codexHomePath,
+          configBaseDir,
+          workspaceRoot: workspace,
+        });
+
+        expect(threads).toEqual([]);
+      }),
+    );
+
+    it.effect("uses one deterministic provider instance for a shared session home", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        yield* writeTranscript({
+          filePath: path.join(sharedHome, "sessions", "2026", "08", "24", "rollout-shared.jsonl"),
+          contents: [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: "shared-session", cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: "Use the shared session" },
+            }),
+          ].join("\n"),
+          mtimeMs: nowMs,
+        });
+
+        const threads = yield* runRecentThreads({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+          providerInstances: {
+            [ProviderInstanceId.make("codex")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: sharedHome },
+            },
+            [ProviderInstanceId.make("codex-personal")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: sharedHome },
+            },
+            [ProviderInstanceId.make("codex-work")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: sharedHome },
+            },
+          },
+        });
+
+        expect(threads.map((thread) => thread.providerInstanceId)).toEqual(["codex"]);
+      }),
+    );
+
+    it.effect("uses configured order when custom instances share a session home", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const sharedHome = yield* makeTempDir("t3code-codex-shared-");
+        const workspace = yield* makeTempDir("t3code-workspace-");
+
+        yield* writeTranscript({
+          filePath: path.join(sharedHome, "sessions", "2026", "08", "24", "rollout-shared.jsonl"),
+          contents: [
+            encodeTranscriptRecord({
+              type: "session_meta",
+              payload: { id: "shared-session", cwd: workspace },
+            }),
+            encodeTranscriptRecord({
+              type: "event_msg",
+              payload: { type: "user_message", message: "Use the first account" },
+            }),
+          ].join("\n"),
+          mtimeMs: nowMs,
+        });
+
+        const threads = yield* runRecentThreads({
+          claudeHomePath,
+          codexHomePath,
+          workspaceRoot: workspace,
+          providerInstances: {
+            [ProviderInstanceId.make("codex-work")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: sharedHome },
+            },
+            [ProviderInstanceId.make("codex-personal")]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath: sharedHome },
+            },
+          },
+        });
+
+        expect(threads.map((thread) => thread.providerInstanceId)).toEqual(["codex-work"]);
+      }),
+    );
+
+    it.effect("keeps a second account when the first has 5000 newer files", () =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const nowMs = Date.parse("2026-08-24T12:00:00.000Z");
+        yield* TestClock.setTime(nowMs);
+        const claudeHomePath = yield* makeTempDir("t3code-claude-home-");
+        const codexHomePath = yield* makeTempDir("t3code-codex-home-");
+        const oldWorkspace = yield* makeTempDir("t3code-workspace-old-");
+        const recentWorkspace = yield* makeTempDir("t3code-workspace-recent-");
+        const recentHome = yield* makeTempDir("t3code-claude-recent-home-");
+        const oldDirectory = path.join(claudeHomePath, "projects", "-aaa-old");
+        const oldTranscript = path.join(oldDirectory, "old.jsonl");
+        const recentDirectory = path.join(recentHome, "projects", "-zzz-recent");
+
+        yield* writeTranscript({
+          filePath: oldTranscript,
+          contents: encodeTranscriptRecord({
+            type: "user",
+            cwd: oldWorkspace,
+            sessionId: "old-session",
+            message: { role: "user", content: "Old work" },
+          }),
+          mtimeMs: nowMs,
+        });
+        yield* writeTranscript({
+          filePath: path.join(recentDirectory, "recent.jsonl"),
+          contents: encodeTranscriptRecord({
+            type: "user",
+            cwd: recentWorkspace,
+            sessionId: "recent-session",
+            message: { role: "user", content: "Recent work" },
+          }),
+          mtimeMs: nowMs - 1_000,
+        });
+
+        const simulatedOldTranscripts = Array.from(
+          { length: 5_000 },
+          (_, index) => `old-${index}.jsonl`,
+        );
+        const resolveTranscript = (filePath: string) =>
+          path.dirname(filePath) === oldDirectory && path.basename(filePath).startsWith("old-")
+            ? oldTranscript
+            : filePath;
+        const simulatedFileSystem = FileSystem.FileSystem.of({
+          ...fileSystem,
+          readDirectory: (directory, options) =>
+            directory === oldDirectory
+              ? Effect.succeed(simulatedOldTranscripts)
+              : fileSystem.readDirectory(directory, options),
+          stat: (filePath) => fileSystem.stat(resolveTranscript(filePath)),
+          open: (filePath, options) => fileSystem.open(resolveTranscript(filePath), options),
+        });
+
+        const input = {
+          claudeHomePath,
+          codexHomePath,
+          providerInstances: {
+            [ProviderInstanceId.make("claude-work")]: {
+              driver: ProviderDriverKind.make("claudeAgent"),
+              config: { homePath: recentHome },
+            },
+          },
+        };
+        const threads = yield* Effect.gen(function* () {
+          const scanner = yield* AgentSessionScanner.AgentSessionScanner;
+          const scan = yield* scanner.scan;
+          expect(scan.truncated).toBe(true);
+          return yield* scanner.recentThreads(recentWorkspace).pipe(Stream.runCollect);
+        }).pipe(
+          Effect.provide(makeScannerTestLayer(input)),
+          Effect.provideService(FileSystem.FileSystem, simulatedFileSystem),
+        );
+
+        expect(
+          threads.flatMap((outcome) =>
+            outcome._tag === "Importable" ? [outcome.thread.providerSessionId] : [],
+          ),
+        ).toEqual(["recent-session"]);
+      }),
+    );
+  });
+});
+
+describe("parseAgentSessionTranscript", () => {
+  it.each([false, true])(
+    "handles the exact record limit and an interior blank overflow=%s",
+    (overflow) => {
+      const thread = AgentSessionScanner.parseAgentSessionTranscript({
+        contents: makeRecordLimitTranscript("/project", overflow),
+        source: "codex",
+        providerInstanceId: ProviderInstanceId.make("codex"),
+        fallbackSessionId: "unused",
+        lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+      });
+      if (overflow) expect(thread).toBeNull();
+      else expect(thread?.messages.map((message) => message.text)).toEqual(["First prompt"]);
+    },
+  );
+
+  it("keeps Claude text and titles while dropping malformed and tool records", () => {
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        "not valid json",
+        JSON.stringify({ type: "ai-title", aiTitle: "Fix authentication" }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "claude-session",
+          isMeta: true,
+          message: { role: "user", content: "Injected skill instructions" },
+        }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "claude-session",
+          isCompactSummary: true,
+          message: { role: "user", content: "Injected compaction summary" },
+        }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "claude-session",
+          timestamp: "2026-08-24T10:00:00.000Z",
+          message: { role: "user", content: [{ type: "text", text: "Fix authentication" }] },
+        }),
+        JSON.stringify({
+          type: "user",
+          sessionId: "claude-session",
+          message: { role: "user", content: [{ type: "tool_result", text: "hidden" }] },
+        }),
+        JSON.stringify({
+          type: "assistant",
+          sessionId: "claude-session",
+          message: {
+            role: "assistant",
+            model: "claude-sonnet-5",
+            content: [{ type: "text", text: "Updated the login flow" }],
+          },
+        }),
+        JSON.stringify({
+          type: "assistant",
+          sessionId: "claude-session",
+          message: {
+            role: "assistant",
+            model: "<synthetic>",
+            content: [{ type: "text", text: "The provider request failed" }],
+          },
+        }),
+      ].join("\n"),
+      source: "claudeAgent",
+      providerInstanceId: ProviderInstanceId.make("claudeAgent"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread).toMatchObject({
+      providerSessionId: "claude-session",
+      title: "Fix authentication",
+      model: "claude-sonnet-5",
+      messages: [
+        { role: "user", text: "Fix authentication" },
+        { role: "assistant", text: "Updated the login flow" },
+        { role: "assistant", text: "The provider request failed" },
+      ],
+    });
+  });
+
+  it("drops injected Codex instructions while keeping the visible user event", () => {
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        JSON.stringify({ type: "session_meta", payload: { id: "codex-session" } }),
+        JSON.stringify({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-1" },
+            content: [
+              {
+                type: "input_text",
+                text: "<user_instructions>\nInternal setup instructions\n</user_instructions>",
+              },
+            ],
+          },
+        }),
+        JSON.stringify({
+          type: "event_msg",
+          payload: { type: "user_message", message: "Fix the actual bug" },
+        }),
+        JSON.stringify({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-1" },
+            content: [{ type: "input_text", text: "Fix the actual bug" }],
+          },
+        }),
+        JSON.stringify({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "assistant",
+            content: [{ type: "output_text", text: "Fixed" }],
+          },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread?.messages.map((message) => message.text)).toEqual([
+      "Fix the actual bug",
+      "Fixed",
+    ]);
+  });
+
+  it("keeps the canonical first prompt after long Codex transcripts are capped", () => {
+    const canonicalPrompt = "\n  Keep the canonical prompt  \n";
+    const canonicalTimestamp = "2026-08-24T10:01:00.000Z";
+    const laterAssistantMessages = Array.from({ length: 200 }, (_, index) =>
+      encodeTranscriptRecord({
+        type: "response_item",
+        timestamp: `2026-08-24T11:${String(index % 60).padStart(2, "0")}:00.000Z`,
+        payload: {
+          type: "message",
+          role: "assistant",
+          content: [{ type: "output_text", text: `Assistant message ${index}` }],
+        },
+      }),
+    );
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          timestamp: "2026-08-24T10:00:00.000Z",
+          payload: {
+            type: "message",
+            role: "user",
+            content: [{ type: "input_text", text: "Keep the canonical prompt" }],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "event_msg",
+          timestamp: canonicalTimestamp,
+          payload: { type: "user_message", message: canonicalPrompt },
+        }),
+        ...laterAssistantMessages,
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread?.messages).toHaveLength(200);
+    expect(thread?.messages[0]).toMatchObject({
+      role: "user",
+      text: canonicalPrompt,
+      createdAt: canonicalTimestamp,
+    });
+  });
+
+  it("restores the canonical first prompt when a later user message remains", () => {
+    const canonicalPrompt = "\n  Keep the canonical prompt  \n";
+    const canonicalTimestamp = "2026-08-24T10:01:00.000Z";
+    const assistantMessages = Array.from({ length: 198 }, (_, index) =>
+      encodeTranscriptRecord({
+        type: "response_item",
+        timestamp: `2026-08-24T11:${String(index % 60).padStart(2, "0")}:00.000Z`,
+        payload: {
+          type: "message",
+          role: "assistant",
+          content: [{ type: "output_text", text: `Assistant message ${index}` }],
+        },
+      }),
+    );
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          timestamp: "2026-08-24T10:00:00.000Z",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-1" },
+            content: [{ type: "input_text", text: "Keep the canonical prompt" }],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "event_msg",
+          timestamp: canonicalTimestamp,
+          payload: { type: "user_message", message: canonicalPrompt },
+        }),
+        ...assistantMessages,
+        encodeTranscriptRecord({
+          type: "event_msg",
+          timestamp: "2026-08-24T11:58:30.000Z",
+          payload: { type: "user_message", message: "Keep this later prompt" },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          timestamp: "2026-08-24T11:59:00.000Z",
+          payload: {
+            type: "message",
+            role: "assistant",
+            content: [{ type: "output_text", text: "Keep this latest response" }],
+          },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread?.messages).toHaveLength(200);
+    expect(thread?.messages[0]).toMatchObject({
+      role: "user",
+      text: canonicalPrompt,
+      createdAt: canonicalTimestamp,
+    });
+    expect(
+      thread?.messages.filter((message) => message.text.trim() === canonicalPrompt.trim()),
+    ).toHaveLength(1);
+    expect(thread?.messages.some((message) => message.text === "Keep this later prompt")).toBe(
+      true,
+    );
+    expect(thread?.messages.at(-1)?.text).toBe("Keep this latest response");
+  });
+
+  it("keeps mixed-format response users when turn IDs repeat after an assistant", () => {
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-older" },
+            content: [{ type: "input_text", text: "Keep this older prompt" }],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "event_msg",
+          payload: { type: "user_message", message: "Keep this newer prompt" },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-newer" },
+            content: [{ type: "input_text", text: "Keep this newer prompt" }],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "assistant",
+            content: [{ type: "output_text", text: "Ask again when needed" }],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-newer" },
+            content: [{ type: "input_text", text: "Keep this newer prompt" }],
+          },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread?.messages.map((message) => message.text)).toEqual([
+      "Keep this older prompt",
+      "Keep this newer prompt",
+      "Ask again when needed",
+      "Keep this newer prompt",
+    ]);
+  });
+
+  it("preserves response user text when Codex turn metadata is ambiguous", () => {
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: ["unexpected"],
+            content: [{ type: "input_text", text: "Keep this legacy prompt" }],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "   " },
+            content: [{ type: "input_text", text: "Keep this prompt with a blank turn ID" }],
+          },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread?.messages.map((message) => message.text)).toEqual([
+      "Keep this legacy prompt",
+      "Keep this prompt with a blank turn ID",
+    ]);
+  });
+
+  it("uses the first valid Codex session ID when a fork copies ancestor metadata", () => {
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({
+          type: "session_meta",
+          payload: { id: "fork-session", forked_from_id: "parent-session" },
+        }),
+        encodeTranscriptRecord({
+          type: "session_meta",
+          payload: { id: "parent-session" },
+        }),
+        encodeTranscriptRecord({
+          type: "event_msg",
+          payload: { type: "user_message", message: "Continue in the fork" },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread?.providerSessionId).toBe("fork-session");
+  });
+
+  it("skips Codex transcripts without a resumable session ID", () => {
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: encodeTranscriptRecord({
+        type: "event_msg",
+        payload: { type: "user_message", message: "This transcript has no session metadata" },
+      }),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "rollout-2026-08-24T12-00-00-not-a-session-id",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread).toBeNull();
+  });
+
+  it("uses the canonical Codex event when its turn has generated response context", () => {
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-1" },
+            content: [
+              {
+                type: "input_text",
+                text: "<environment_context>\n<cwd>/tmp/project</cwd>\n<shell>zsh</shell>\n</environment_context>",
+              },
+            ],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-1" },
+            content: [
+              {
+                type: "input_text",
+                text: "# AGENTS.md instructions for /tmp/project\n\n<INSTRUCTIONS>\nPrivate project rules\n</INSTRUCTIONS>",
+              },
+            ],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "event_msg",
+          payload: {
+            type: "user_message",
+            message: "Do something here so it looks like a real project.",
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            internal_chat_message_metadata_passthrough: { turn_id: "turn-1" },
+            content: [
+              {
+                type: "input_text",
+                text: "Do something here so it looks like a real project.",
+              },
+            ],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "assistant",
+            content: [{ type: "output_text", text: "Created the project." }],
+          },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-25T08:00:00.000Z"),
+    });
+
+    expect(thread?.title).toBe("Do something here so it looks like a real project.");
+    expect(thread?.messages.map((message) => message.text)).toEqual([
+      "Do something here so it looks like a real project.",
+      "Created the project.",
+    ]);
+  });
+
+  it("preserves context markup in response-only Codex messages", () => {
+    const context = "<environment_context>\n<cwd>/tmp/project</cwd>\n</environment_context>";
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            content: [
+              {
+                type: "input_text",
+                text: context,
+              },
+            ],
+          },
+        }),
+        encodeTranscriptRecord({
+          type: "response_item",
+          payload: {
+            type: "message",
+            role: "user",
+            content: [{ type: "input_text", text: "Initialize Git and add a README." }],
+          },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-25T08:00:00.000Z"),
+    });
+
+    expect(thread?.title).toBe("<environment_context>");
+    expect(thread?.messages.map((message) => message.text)).toEqual([
+      context,
+      "Initialize Git and add a README.",
+    ]);
+  });
+
+  it("preserves a canonical Codex event that starts with context markup", () => {
+    const prompt =
+      "<environment_context>\n<cwd>/tmp/project</cwd>\n</environment_context>\n\nCreate a useful project.";
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "event_msg",
+          payload: {
+            type: "user_message",
+            message: prompt,
+          },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-25T08:00:00.000Z"),
+    });
+
+    expect(thread?.title).toBe("<environment_context>");
+    expect(thread?.messages.map((message) => message.text)).toEqual([prompt]);
+  });
+
+  it("preserves a Codex request heading in a canonical event", () => {
+    const prompt = "\n  ## My request for Codex:\n\nFix the visible bug";
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "event_msg",
+          payload: {
+            type: "user_message",
+            message: prompt,
+          },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-25T08:00:00.000Z"),
+    });
+
+    expect(thread?.title).toBe("## My request for Codex:");
+    expect(thread?.messages.map((message) => message.text)).toEqual([prompt]);
+  });
+
+  it("keeps context markup quoted inside visible Codex user text", () => {
+    const quoted =
+      "Do not remove this example:\n<environment_context>\n<cwd>/tmp/example</cwd>\n</environment_context>";
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: [
+        encodeTranscriptRecord({ type: "session_meta", payload: { id: "codex-session" } }),
+        encodeTranscriptRecord({
+          type: "event_msg",
+          payload: { type: "user_message", message: quoted },
+        }),
+      ].join("\n"),
+      source: "codex",
+      providerInstanceId: ProviderInstanceId.make("codex"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-25T08:00:00.000Z"),
+    });
+
+    expect(thread?.messages.map((message) => message.text)).toEqual([quoted]);
+  });
+
+  it("skips sessions without a visible user message", () => {
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: JSON.stringify({
+        type: "assistant",
+        message: { role: "assistant", content: "Done" },
+      }),
+      source: "claudeAgent",
+      providerInstanceId: ProviderInstanceId.make("claudeAgent"),
+      fallbackSessionId: "claude-session",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread).toBeNull();
+  });
+
+  it("keeps the first prompt when later assistant output exceeds the message limit", () => {
+    const transcript = [
+      encodeTranscriptRecord({
+        type: "user",
+        sessionId: "claude-session",
+        message: { role: "user", content: "Keep this prompt" },
+      }),
+      ...Array.from({ length: 250 }, (_, index) =>
+        encodeTranscriptRecord({
+          type: "assistant",
+          message: { role: "assistant", content: `Assistant update ${index}` },
+        }),
+      ),
+    ].join("\n");
+
+    const thread = AgentSessionScanner.parseAgentSessionTranscript({
+      contents: transcript,
+      source: "claudeAgent",
+      providerInstanceId: ProviderInstanceId.make("claudeAgent"),
+      fallbackSessionId: "fallback",
+      lastActiveAtMs: Date.parse("2026-08-24T12:00:00.000Z"),
+    });
+
+    expect(thread?.messages).toHaveLength(200);
+    expect(thread?.messages[0]?.text).toBe("Keep this prompt");
+    expect(thread?.messages.at(-1)?.text).toBe("Assistant update 249");
+  });
+});
diff --git a/apps/server/src/project/AgentSessionScanner.ts b/apps/server/src/project/AgentSessionScanner.ts
new file mode 100644
index 000000000000..bc6d093d42a1
--- /dev/null
+++ b/apps/server/src/project/AgentSessionScanner.ts
@@ -0,0 +1,1313 @@
+/**
+ * AgentSessionScanner - discovery of projects a user already works on.
+ *
+ * Claude Code and Codex both keep a per-session transcript on disk, and each
+ * transcript records the directory the session ran in. Reading those `cwd`
+ * values gives us the set of directories worth offering as projects during
+ * onboarding, without asking the user to browse the filesystem.
+ *
+ * The scan is read-only and best-effort: an unreadable home, a malformed
+ * transcript, or a directory that has since been deleted is skipped rather
+ * than failing the scan. Project creation stays with the client, which
+ * dispatches `project.create` for whichever candidates the user picks.
+ *
+ * @module project/AgentSessionScanner
+ */
+import * as NodeOS from "node:os";
+
+import {
+  AgentSessionScanError,
+  ClaudeSettings,
+  CodexSettings,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  resolveProviderInstanceEnabled,
+  type AgentSessionImportSource,
+  type AgentSessionProjectCandidate,
+  type AgentSessionScanResult,
+  type ProviderInstanceConfig,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+
+import { HostProcessEnvironment, HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { normalizeProjectPathForComparison } from "@t3tools/shared/path";
+
+import * as ServerConfig from "../config.ts";
+import * as ProjectionSnapshotQuery from "../orchestration/Services/ProjectionSnapshotQuery.ts";
+import { resolveCodexHomeLayout } from "../provider/Drivers/CodexHomeLayout.ts";
+import { expandHomePath } from "../pathExpansion.ts";
+import * as ServerSettings from "../serverSettings.ts";
+
+/** Chunk size for full transcript reads. */
+const TRANSCRIPT_PREFIX_BYTES = 32 * 1024;
+/** Small reads avoid wasting the metadata budget on long Codex instruction headers. */
+const METADATA_READ_BYTES = 8 * 1024;
+/** Prevent malformed transcripts from turning project discovery into a full file scan. */
+const MAX_TRANSCRIPT_SCAN_BYTES = 1024 * 1024;
+
+/**
+ * Upper bound on transcripts inspected (first line read) per source.
+ * Newest-first ordering means the cap drops only stale sessions when a home
+ * directory is unusually large.
+ */
+const MAX_TRANSCRIPTS_PER_SOURCE = 5000;
+
+/**
+ * Upper bound on discovery filesystem operations per source. Newest-first
+ * ordering needs mtimes before the read cap can be applied, so directory reads
+ * and candidate stats share a larger budget. Once it runs out the scan stops.
+ */
+const MAX_DISCOVERY_OPERATIONS_PER_SOURCE = MAX_TRANSCRIPTS_PER_SOURCE * 4;
+const MAX_METADATA_BYTES_PER_SOURCE = 64 * 1024 * 1024;
+const MAX_METADATA_OPERATIONS_PER_SOURCE = MAX_TRANSCRIPTS_PER_SOURCE * 4;
+const MAX_METADATA_RECORDS_PER_SOURCE = 100_000;
+const MAX_METADATA_RECORDS_PER_TRANSCRIPT = 1_000;
+const RECENT_THREAD_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+const MAX_IMPORTED_TRANSCRIPT_BYTES = 16 * 1024 * 1024;
+const MAX_IMPORTED_MESSAGES = 200;
+const MAX_IMPORT_BYTES = 64 * 1024 * 1024;
+const MAX_IMPORT_TRANSCRIPTS = 100;
+const MAX_IMPORT_RECORDS = 100_000;
+
+const TranscriptContentBlock = Schema.Struct({
+  type: Schema.optional(Schema.String),
+  text: Schema.optional(Schema.String),
+});
+
+const TranscriptMessage = Schema.Struct({
+  role: Schema.optional(Schema.String),
+  content: Schema.optional(Schema.Union([Schema.String, Schema.Array(TranscriptContentBlock)])),
+  model: Schema.optional(Schema.String),
+});
+
+const CodexTurnMetadata = Schema.Struct({
+  turn_id: Schema.optional(Schema.Union([Schema.String, Schema.Null])),
+});
+
+const TranscriptRecord = Schema.Struct({
+  type: Schema.optional(Schema.String),
+  timestamp: Schema.optional(Schema.String),
+  sessionId: Schema.optional(Schema.String),
+  aiTitle: Schema.optional(Schema.String),
+  isSidechain: Schema.optional(Schema.Boolean),
+  isMeta: Schema.optional(Schema.Boolean),
+  isCompactSummary: Schema.optional(Schema.Boolean),
+  message: Schema.optional(TranscriptMessage),
+  payload: Schema.optional(
+    Schema.Struct({
+      id: Schema.optional(Schema.String),
+      session_id: Schema.optional(Schema.String),
+      type: Schema.optional(Schema.String),
+      role: Schema.optional(Schema.String),
+      message: Schema.optional(Schema.String),
+      model: Schema.optional(Schema.String),
+      content: Schema.optional(Schema.Array(TranscriptContentBlock)),
+      internal_chat_message_metadata_passthrough: Schema.optional(Schema.Unknown),
+    }),
+  ),
+});
+
+const decodeClaudeSettings = Schema.decodeUnknownOption(ClaudeSettings);
+const decodeCodexSettings = Schema.decodeUnknownOption(CodexSettings);
+const decodeTranscriptRecord = Schema.decodeUnknownOption(Schema.fromJsonString(TranscriptRecord));
+const decodeCodexTurnMetadata = Schema.decodeUnknownOption(CodexTurnMetadata);
+
+export interface AgentSessionThreadMessage {
+  readonly role: "user" | "assistant";
+  readonly text: string;
+  readonly createdAt: string;
+}
+
+export interface AgentSessionThread {
+  readonly source: AgentSessionSource;
+  readonly providerInstanceId: ProviderInstanceId;
+  readonly providerSessionId: string;
+  readonly title: string;
+  readonly model: string | null;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly messages: ReadonlyArray<AgentSessionThreadMessage>;
+}
+
+export type AgentSessionRecentThread =
+  | {
+      readonly _tag: "Importable";
+      readonly thread: AgentSessionThread;
+      readonly source: AgentSessionImportSource;
+    }
+  | { readonly _tag: "AlreadyImported"; readonly source: AgentSessionImportSource }
+  | { readonly _tag: "Duplicate"; readonly source: AgentSessionImportSource }
+  | { readonly _tag: "Skipped" };
+
+/** Service tag for agent session discovery. */
+export class AgentSessionScanner extends Context.Service<
+  AgentSessionScanner,
+  {
+    /**
+     * Discover every directory the configured Claude and Codex homes have run
+     * a session in. Candidates are returned newest-first; the client decides
+     * which ones to import and how far back to look. Fails with the contract
+     * error directly — there is no server-local context worth wrapping.
+     */
+    readonly scan: Effect.Effect<AgentSessionScanResult, AgentSessionScanError>;
+    readonly recentThreads: (
+      workspaceRoot: string,
+      completedSources?: ReadonlyArray<AgentSessionImportSource>,
+    ) => Stream.Stream<AgentSessionRecentThread, AgentSessionScanError>;
+  }
+>()("t3/project/AgentSessionScanner") {}
+
+type AgentSessionSource = AgentSessionProjectCandidate["sources"][number];
+
+/** A single directory's worth of evidence from one source. */
+interface RawCandidate {
+  readonly cwd: string;
+  readonly source: AgentSessionSource;
+  readonly providerInstanceId: ProviderInstanceId;
+  readonly threadCount: number;
+  readonly lastActiveAtMs: number | null;
+  readonly transcripts: ReadonlyArray<{
+    readonly filePath: string;
+    readonly mtimeMs: number | null;
+  }>;
+}
+
+interface TranscriptCandidate {
+  readonly filePath: string;
+  readonly mtimeMs: number;
+  readonly providerInstanceId: ProviderInstanceId;
+  readonly size: number;
+}
+
+interface MetadataReadBudget {
+  bytesRemaining: number;
+  operationsRemaining: number;
+  recordsRemaining: number;
+  truncated: boolean;
+}
+
+function selectMetadataTranscripts(transcripts: ReadonlyArray<TranscriptCandidate>) {
+  const selected: Array<TranscriptCandidate> = [];
+  let pending = Array.from(
+    Map.groupBy(transcripts, (transcript) => transcript.providerInstanceId).values(),
+    (entries) => entries.values(),
+  );
+  while (pending.length > 0 && selected.length < MAX_TRANSCRIPTS_PER_SOURCE) {
+    const nextRound: typeof pending = [];
+    for (const iterator of pending) {
+      if (selected.length === MAX_TRANSCRIPTS_PER_SOURCE) break;
+      const next = iterator.next();
+      if (next.done) continue;
+      selected.push(next.value);
+      nextRound.push(iterator);
+    }
+    pending = nextRound;
+  }
+  return selected;
+}
+
+function splitTranscriptRecords(contents: string, limit: number): string[] {
+  const records = contents.endsWith("\n") ? contents.slice(0, -1) : contents;
+  return records.split("\n", limit);
+}
+
+function extractText(
+  content: string | ReadonlyArray<typeof TranscriptContentBlock.Type> | undefined,
+): string {
+  if (typeof content === "string") return content.trim();
+  if (content === undefined) return "";
+  return content
+    .filter(
+      (block) =>
+        block.type === "text" || block.type === "input_text" || block.type === "output_text",
+    )
+    .map((block) => block.text?.trim() ?? "")
+    .filter((text) => text.length > 0)
+    .join("\n");
+}
+
+function normalizeTimestamp(value: string | undefined, fallback: string): string {
+  if (value === undefined) return fallback;
+  const parsed = DateTime.make(value);
+  return Option.isSome(parsed) ? DateTime.formatIso(parsed.value) : fallback;
+}
+
+function codexTurnId(metadata: unknown): string | null {
+  const decoded = decodeCodexTurnMetadata(metadata);
+  if (
+    Option.isNone(decoded) ||
+    typeof decoded.value.turn_id !== "string" ||
+    decoded.value.turn_id.trim().length === 0
+  ) {
+    return null;
+  }
+  return decoded.value.turn_id;
+}
+
+/** Keep visible user and assistant text while ignoring tools, reasoning, and malformed records. */
+export function parseAgentSessionTranscript(
+  input: {
+    readonly contents: string;
+    readonly source: AgentSessionSource;
+    readonly providerInstanceId: ProviderInstanceId;
+    readonly fallbackSessionId: string;
+    readonly lastActiveAtMs: number;
+  },
+  lines = splitTranscriptRecords(input.contents, MAX_IMPORT_RECORDS + 1),
+): AgentSessionThread | null {
+  if (lines.length > MAX_IMPORT_RECORDS) return null;
+  const fallbackTimestamp = DateTime.formatIso(DateTime.makeUnsafe(input.lastActiveAtMs));
+  // Claude filenames are session IDs. Codex rollout filenames include extra
+  // timestamp text, so only transcript metadata can provide a resumable ID.
+  let providerSessionId = input.source === "codex" ? "" : input.fallbackSessionId;
+  let title: string | null = null;
+  let model: string | null = null;
+  let hasCodexSessionId = false;
+  const messages: Array<AgentSessionThreadMessage & { readonly codexResponseUser: boolean }> = [];
+  let firstUserMessage:
+    | (AgentSessionThreadMessage & { readonly codexResponseUser: boolean })
+    | undefined;
+  function* decodedRecords() {
+    for (const line of lines) {
+      const decoded = decodeTranscriptRecord(line);
+      if (Option.isSome(decoded)) yield decoded.value;
+    }
+  }
+
+  // A Codex response item can include generated setup text beside the real
+  // prompt. Suppress response-user records only when the shared turn ID and a
+  // verbatim event copy prove which prompt the user submitted.
+  const canonicalCodexResponseUserIndices = new Set<number>();
+  let canonicalUserTextsInTurn = new Set<string>();
+  let responseUsersInTurn: Array<{
+    readonly index: number;
+    readonly turnId: string;
+    readonly text: string;
+  }> = [];
+  const finishCodexTurn = () => {
+    const canonicalTurnIds = new Set(
+      responseUsersInTurn.flatMap((responseUser) =>
+        canonicalUserTextsInTurn.has(responseUser.text) ? [responseUser.turnId] : [],
+      ),
+    );
+    for (const responseUser of responseUsersInTurn) {
+      if (canonicalTurnIds.has(responseUser.turnId)) {
+        canonicalCodexResponseUserIndices.add(responseUser.index);
+      }
+    }
+    canonicalUserTextsInTurn = new Set();
+    responseUsersInTurn = [];
+  };
+  if (input.source === "codex") {
+    let recordIndex = -1;
+    for (const record of decodedRecords()) {
+      recordIndex += 1;
+      if (
+        record.type === "response_item" &&
+        record.payload?.type === "message" &&
+        record.payload.role === "assistant"
+      ) {
+        finishCodexTurn();
+        continue;
+      }
+      if (record.type === "event_msg" && record.payload?.type === "user_message") {
+        const text = record.payload.message?.trim() ?? "";
+        if (text.length > 0) canonicalUserTextsInTurn.add(text);
+        continue;
+      }
+      if (
+        record.type === "response_item" &&
+        record.payload?.type === "message" &&
+        record.payload.role === "user"
+      ) {
+        const turnId = codexTurnId(record.payload.internal_chat_message_metadata_passthrough);
+        const text = extractText(record.payload.content);
+        if (turnId !== null && text.length > 0) {
+          responseUsersInTurn.push({ index: recordIndex, turnId, text });
+        }
+      }
+    }
+    finishCodexTurn();
+  }
+
+  const retainMessage = (
+    message: AgentSessionThreadMessage & { readonly codexResponseUser: boolean },
+  ) => {
+    if (firstUserMessage === undefined && message.role === "user") {
+      firstUserMessage = message;
+    }
+    messages.push(message);
+    if (messages.length > MAX_IMPORTED_MESSAGES) messages.shift();
+  };
+
+  const hasMatchingCodexEventInTurn = (text: string) => {
+    const comparisonText = text.trim();
+    for (let index = messages.length - 1; index >= 0; index--) {
+      const message = messages[index];
+      if (message?.role === "assistant") return false;
+      if (
+        message?.role === "user" &&
+        !message.codexResponseUser &&
+        message.text.trim() === comparisonText
+      ) {
+        return true;
+      }
+    }
+    return false;
+  };
+
+  let recordIndex = -1;
+  for (const record of decodedRecords()) {
+    recordIndex += 1;
+    if (input.source === "claudeAgent") {
+      if (
+        record.isSidechain === true ||
+        record.isMeta === true ||
+        record.isCompactSummary === true
+      ) {
+        continue;
+      }
+      if (record.sessionId?.trim()) providerSessionId = record.sessionId.trim();
+      if (record.aiTitle?.trim()) title = record.aiTitle.trim();
+      const messageModel = record.message?.model?.trim();
+      // Claude uses this sentinel for local error responses. It is not a
+      // model ID that can be selected when the imported session resumes.
+      if (messageModel && messageModel !== "<synthetic>") model = messageModel;
+      if (record.type !== "user" && record.type !== "assistant") {
+        continue;
+      }
+
+      const text = extractText(record.message?.content);
+      if (text.length === 0) continue;
+      retainMessage({
+        role: record.type,
+        text,
+        createdAt: normalizeTimestamp(record.timestamp, fallbackTimestamp),
+        codexResponseUser: false,
+      });
+      continue;
+    }
+
+    if (record.type === "session_meta") {
+      const sessionId = record.payload?.id?.trim() || record.payload?.session_id?.trim();
+      if (!hasCodexSessionId && sessionId) {
+        providerSessionId = sessionId;
+        hasCodexSessionId = true;
+      }
+      continue;
+    }
+    if (record.type === "turn_context" && record.payload?.model?.trim()) {
+      model = record.payload.model.trim();
+      continue;
+    }
+    if (record.type === "event_msg" && record.payload?.type === "user_message") {
+      const text = record.payload.message ?? "";
+      if (text.trim().length === 0) continue;
+      // Codex can write the same prompt as both a response item and an event.
+      // Remove only the matching response copy so mixed-format logs keep every
+      // distinct user message.
+      for (let index = messages.length - 1; index >= 0; index--) {
+        const message = messages[index];
+        if (message?.role === "assistant") break;
+        if (message?.codexResponseUser === true && message.text.trim() === text.trim()) {
+          if (firstUserMessage === message) firstUserMessage = undefined;
+          messages.splice(index, 1);
+          break;
+        }
+      }
+      retainMessage({
+        role: "user",
+        text,
+        createdAt: normalizeTimestamp(record.timestamp, fallbackTimestamp),
+        codexResponseUser: false,
+      });
+      continue;
+    }
+    if (
+      record.type !== "response_item" ||
+      record.payload?.type !== "message" ||
+      (record.payload.role !== "user" && record.payload.role !== "assistant")
+    ) {
+      continue;
+    }
+
+    const extractedText = extractText(record.payload.content);
+    if (extractedText.length === 0) continue;
+    if (record.payload.role === "user" && canonicalCodexResponseUserIndices.has(recordIndex)) {
+      continue;
+    }
+    if (record.payload.role === "user" && hasMatchingCodexEventInTurn(extractedText)) {
+      continue;
+    }
+    retainMessage({
+      role: record.payload.role,
+      text: extractedText,
+      createdAt: normalizeTimestamp(record.timestamp, fallbackTimestamp),
+      codexResponseUser: record.payload.role === "user",
+    });
+  }
+
+  const visibleMessages = messages.map(
+    ({ codexResponseUser: _codexResponseUser, ...message }) => message,
+  );
+  if (providerSessionId.trim().length === 0 || firstUserMessage === undefined) return null;
+  const firstUserMessageRetained = messages.includes(firstUserMessage);
+  const { codexResponseUser: _codexResponseUser, ...visibleFirstUserMessage } = firstUserMessage;
+  const retainedMessages = firstUserMessageRetained
+    ? visibleMessages
+    : [visibleFirstUserMessage, ...visibleMessages.slice(-(MAX_IMPORTED_MESSAGES - 1))];
+  const derivedTitle = visibleFirstUserMessage.text.trim().split("\n")[0]?.slice(0, 100).trim();
+
+  return {
+    source: input.source,
+    providerInstanceId: input.providerInstanceId,
+    providerSessionId,
+    title: title ?? (derivedTitle && derivedTitle.length > 0 ? derivedTitle : "Imported thread"),
+    model,
+    createdAt: retainedMessages[0]?.createdAt ?? fallbackTimestamp,
+    updatedAt: fallbackTimestamp,
+    messages: retainedMessages,
+  };
+}
+
+/**
+ * T3 Code runs its own agent sessions inside disposable worktrees. Their
+ * transcripts look exactly like user sessions, but re-importing the app's own
+ * sandboxes as projects is never right. Matches this server's configured
+ * worktrees directory plus the conventional `.t3/worktrees` layout, which
+ * also catches sandboxes from other T3 homes on the same machine. Separators
+ * are normalized (and, on Windows, case folded) so the prefix match holds
+ * there too. Callers check both the recorded spelling and its realpath so a
+ * symlink into the worktrees directory cannot bypass the filter.
+ */
+function normalizeForWorktreeMatch(value: string, caseFold: boolean): string {
+  const normalized = `${value.replaceAll("\\", "/")}/`;
+  return caseFold ? normalized.toLowerCase() : normalized;
+}
+
+function isT3ManagedWorktree(
+  candidatePath: string,
+  worktreesDir: string,
+  caseFold: boolean,
+): boolean {
+  const normalized = normalizeForWorktreeMatch(candidatePath, caseFold);
+  return (
+    normalized.startsWith(normalizeForWorktreeMatch(worktreesDir, caseFold)) ||
+    normalized.includes("/.t3/worktrees/")
+  );
+}
+
+/** Extract `cwd` from a session-meta record, tolerating the shapes each CLI writes. */
+function extractCwd(line: string): string | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+
+  const record = parsed as Record<string, unknown>;
+  if (typeof record.cwd === "string" && record.cwd.trim().length > 0) {
+    return record.cwd;
+  }
+  // Codex nests session metadata under `payload`.
+  const payload = record.payload;
+  if (typeof payload === "object" && payload !== null) {
+    const nested = (payload as Record<string, unknown>).cwd;
+    if (typeof nested === "string" && nested.trim().length > 0) {
+      return nested;
+    }
+  }
+  return null;
+}
+
+function transcriptIdentity(filePath: string, stats: FileSystem.File.Info) {
+  return {
+    filePath,
+    size: Number(stats.size),
+    mtimeMs: Option.match(stats.mtime, { onNone: () => null, onSome: (date) => date.getTime() }),
+    device: stats.dev,
+    inode: Option.getOrNull(stats.ino),
+    birthtimeMs: Option.match(stats.birthtime, {
+      onNone: () => null,
+      onSome: (date) => date.getTime(),
+    }),
+  };
+}
+
+function sameTranscriptIdentity(
+  left: ReturnType<typeof transcriptIdentity>,
+  right: ReturnType<typeof transcriptIdentity>,
+): boolean {
+  return (
+    left.filePath === right.filePath &&
+    left.size === right.size &&
+    left.mtimeMs === right.mtimeMs &&
+    left.device === right.device &&
+    left.inode === right.inode &&
+    left.birthtimeMs === right.birthtimeMs
+  );
+}
+
+export const make = Effect.gen(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const serverConfig = yield* ServerConfig.ServerConfig;
+  const serverSettings = yield* ServerSettings.ServerSettingsService;
+  const projectionSnapshotQuery = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+  const baseDir = path.resolve(serverConfig.baseDir);
+  const worktreesDir = path.resolve(serverConfig.worktreesDir);
+  // Windows filesystems are case-insensitive, so path prefix checks there
+  // must case fold.
+  const foldWorktreeCase = (yield* HostProcessPlatform) === "win32";
+  const hostEnvironment = yield* HostProcessEnvironment;
+  const excludedProjectRoots = new Set(
+    [NodeOS.homedir(), NodeOS.tmpdir()].map((directory) =>
+      normalizeProjectPathForComparison(path.resolve(directory)),
+    ),
+  );
+
+  const isExcludedProjectPath = (candidatePath: string) =>
+    excludedProjectRoots.has(normalizeProjectPathForComparison(candidatePath)) ||
+    normalizeForWorktreeMatch(candidatePath, foldWorktreeCase).startsWith(
+      normalizeForWorktreeMatch(baseDir, foldWorktreeCase),
+    ) ||
+    isT3ManagedWorktree(candidatePath, worktreesDir, foldWorktreeCase);
+
+  const listDirectory = (directory: string) =>
+    fileSystem.readDirectory(directory).pipe(Effect.orElseSucceed((): ReadonlyArray<string> => []));
+
+  const statOption = (target: string) =>
+    fileSystem.stat(target).pipe(Effect.map(Option.some), Effect.orElseSucceed(Option.none));
+
+  /** Match directory aliases without assuming the host volume is case-insensitive. */
+  const directoryIdentity = Effect.fn("AgentSessionScanner.directoryIdentity")(function* (
+    target: string,
+    knownStats?: FileSystem.File.Info,
+  ) {
+    const resolved = path.resolve(target);
+    const stats = knownStats === undefined ? yield* statOption(resolved) : Option.some(knownStats);
+    if (
+      Option.isSome(stats) &&
+      Option.isSome(stats.value.ino) &&
+      Number.isSafeInteger(stats.value.ino.value) &&
+      stats.value.ino.value > 0
+    ) {
+      return `inode:${stats.value.dev}:${stats.value.ino.value}`;
+    }
+    const realPath = yield* fileSystem
+      .realPath(resolved)
+      .pipe(Effect.orElseSucceed(() => resolved));
+    return `path:${normalizeProjectPathForComparison(realPath)}`;
+  });
+
+  // A large history snapshot can precede session metadata. Read bounded
+  // chunks until a complete record names its cwd or the safety budget ends.
+  const readCwd = Effect.fn("AgentSessionScanner.readCwd")(function* (
+    transcript: TranscriptCandidate,
+    budget: MetadataReadBudget,
+  ) {
+    if (transcript.size === 0) return null;
+    if (
+      budget.bytesRemaining === 0 ||
+      budget.operationsRemaining < 2 ||
+      budget.recordsRemaining === 0
+    ) {
+      budget.truncated = true;
+      return null;
+    }
+    budget.operationsRemaining -= 1;
+    return yield* Effect.scoped(
+      fileSystem.open(transcript.filePath, { flag: "r" }).pipe(
+        Effect.flatMap((file) =>
+          Effect.gen(function* () {
+            const decoder = new TextDecoder();
+            let remaining = "";
+            let bytesRead = 0;
+            let recordsRead = 0;
+            const maxBytes = Math.min(MAX_TRANSCRIPT_SCAN_BYTES, transcript.size);
+            const reserveRecord = () => {
+              if (
+                recordsRead === MAX_METADATA_RECORDS_PER_TRANSCRIPT ||
+                budget.recordsRemaining === 0
+              ) {
+                budget.truncated = true;
+                return false;
+              }
+              recordsRead += 1;
+              budget.recordsRemaining -= 1;
+              return true;
+            };
+            const readLastRecord = () => {
+              const record = remaining + decoder.decode();
+              return record.length === 0 || !reserveRecord() ? null : extractCwd(record.trim());
+            };
+
+            while (bytesRead < maxBytes) {
+              if (budget.bytesRemaining === 0 || budget.operationsRemaining === 0) {
+                budget.truncated = true;
+                return null;
+              }
+              const readSize = Math.min(
+                METADATA_READ_BYTES,
+                maxBytes - bytesRead,
+                budget.bytesRemaining,
+              );
+              budget.operationsRemaining -= 1;
+              budget.bytesRemaining -= readSize;
+              const next = yield* file.readAlloc(readSize);
+              if (Option.isNone(next)) {
+                return readLastRecord();
+              }
+
+              bytesRead += next.value.byteLength;
+              remaining += decoder.decode(next.value, { stream: true });
+              const lines = remaining.split("\n");
+              remaining = lines.pop() ?? "";
+
+              for (const line of lines) {
+                if (!reserveRecord()) return null;
+                const cwd = extractCwd(line.trim());
+                if (cwd !== null) return cwd;
+              }
+            }
+
+            if (bytesRead < transcript.size) {
+              budget.truncated = true;
+              return null;
+            }
+            return readLastRecord();
+          }),
+        ),
+      ),
+    ).pipe(Effect.orElseSucceed(() => null));
+  });
+
+  /** Check the open file before and after reading, without reading past its reserved byte budget. */
+  const readTranscript = Effect.fn("AgentSessionScanner.readTranscript")(function* (
+    filePath: string,
+    expected: ReturnType<typeof transcriptIdentity>,
+  ) {
+    if (expected.size > MAX_IMPORTED_TRANSCRIPT_BYTES) return null;
+
+    return yield* Effect.scoped(
+      fileSystem.open(filePath, { flag: "r" }).pipe(
+        Effect.flatMap((file) =>
+          Effect.gen(function* () {
+            if (!sameTranscriptIdentity(expected, transcriptIdentity(filePath, yield* file.stat))) {
+              return null;
+            }
+            const decoder = new TextDecoder();
+            let contents = "";
+            let bytesRead = 0;
+
+            while (bytesRead < expected.size) {
+              const next = yield* file.readAlloc(
+                Math.min(TRANSCRIPT_PREFIX_BYTES, expected.size - bytesRead),
+              );
+              if (Option.isNone(next)) {
+                return null;
+              }
+
+              bytesRead += next.value.byteLength;
+              contents += decoder.decode(next.value, { stream: true });
+            }
+
+            return sameTranscriptIdentity(expected, transcriptIdentity(filePath, yield* file.stat))
+              ? contents + decoder.decode()
+              : null;
+          }),
+        ),
+      ),
+    ).pipe(Effect.orElseSucceed(() => null));
+  });
+
+  /**
+   * Resolve the Claude config directory the CLI would use, matching the
+   * precedence the spawned CLI sees: the instance's `homePath` (exported as
+   * `CLAUDE_CONFIG_DIR`), then a `CLAUDE_CONFIG_DIR` already in the
+   * environment, then `~/.claude`.
+   */
+  const resolveClaudeConfigDir = (homePath: string, environmentHome?: string): string => {
+    const configured = homePath.trim();
+    if (configured.length > 0) {
+      return path.resolve(expandHomePath(configured));
+    }
+    const fromEnvironment = environmentHome?.trim() ?? "";
+    if (fromEnvironment.length > 0) {
+      return path.resolve(expandHomePath(fromEnvironment));
+    }
+    return path.join(NodeOS.homedir(), ".claude");
+  };
+
+  const discoverClaudeTranscripts = Effect.fn("AgentSessionScanner.discoverClaudeTranscripts")(
+    function* (homePath: string, providerInstanceId: ProviderInstanceId, operationBudget: number) {
+      const projectsDir = path.join(homePath, "projects");
+      let operationsRemaining = operationBudget;
+      let truncated = false;
+      const readDirectory = (directory: string) => {
+        if (operationsRemaining <= 0) {
+          truncated = true;
+          return Effect.succeed<ReadonlyArray<string>>([]);
+        }
+        operationsRemaining -= 1;
+        return listDirectory(directory);
+      };
+      const projectDirectories = yield* readDirectory(projectsDir);
+      const transcripts: Array<TranscriptCandidate> = [];
+
+      for (const projectDirectory of projectDirectories) {
+        if (operationsRemaining <= 0) {
+          truncated = true;
+          break;
+        }
+        const directory = path.join(projectsDir, projectDirectory);
+        const directoryTranscripts = (yield* readDirectory(directory))
+          .filter((entry) => entry.endsWith(".jsonl"))
+          .map((entry) => path.join(directory, entry));
+
+        for (const filePath of directoryTranscripts) {
+          if (operationsRemaining <= 0) {
+            truncated = true;
+            break;
+          }
+          operationsRemaining -= 1;
+          const stats = yield* statOption(filePath);
+          if (
+            Option.isNone(stats) ||
+            stats.value.type !== "File" ||
+            Option.isNone(stats.value.mtime)
+          ) {
+            continue;
+          }
+          transcripts.push({
+            filePath,
+            mtimeMs: stats.value.mtime.value.getTime(),
+            providerInstanceId,
+            size: Number(stats.value.size),
+          });
+        }
+      }
+      return { transcripts, truncated };
+    },
+  );
+
+  const discoverCodexTranscripts = Effect.fn("AgentSessionScanner.discoverCodexTranscripts")(
+    function* (homePath: string, providerInstanceId: ProviderInstanceId, operationBudget: number) {
+      const sessionsDir = path.join(homePath, "sessions");
+
+      const transcripts: Array<TranscriptCandidate> = [];
+      let operationsRemaining = operationBudget;
+      let truncated = false;
+      const readDirectory = (directory: string) => {
+        if (operationsRemaining <= 0) {
+          truncated = true;
+          return Effect.succeed<ReadonlyArray<string>>([]);
+        }
+        operationsRemaining -= 1;
+        return listDirectory(directory);
+      };
+      // Date-partitioned directories sort chronologically, so walking them in
+      // reverse spends each home's share of the operation budget on recent sessions.
+      for (const year of (yield* readDirectory(sessionsDir)).toSorted().toReversed()) {
+        if (operationsRemaining <= 0) {
+          truncated = true;
+          break;
+        }
+        for (const month of (yield* readDirectory(path.join(sessionsDir, year)))
+          .toSorted()
+          .toReversed()) {
+          if (operationsRemaining <= 0) {
+            truncated = true;
+            break;
+          }
+          for (const day of (yield* readDirectory(path.join(sessionsDir, year, month)))
+            .toSorted()
+            .toReversed()) {
+            if (operationsRemaining <= 0) {
+              truncated = true;
+              break;
+            }
+            const directory = path.join(sessionsDir, year, month, day);
+            for (const entry of (yield* readDirectory(directory)).toSorted().toReversed()) {
+              if (!entry.startsWith("rollout-") || !entry.endsWith(".jsonl")) continue;
+              if (operationsRemaining <= 0) {
+                truncated = true;
+                break;
+              }
+              const filePath = path.join(directory, entry);
+              operationsRemaining -= 1;
+              const stats = yield* statOption(filePath);
+              if (
+                Option.isSome(stats) &&
+                stats.value.type === "File" &&
+                Option.isSome(stats.value.mtime)
+              ) {
+                transcripts.push({
+                  filePath,
+                  mtimeMs: stats.value.mtime.value.getTime(),
+                  providerInstanceId,
+                  size: Number(stats.value.size),
+                });
+              }
+            }
+          }
+        }
+      }
+      return { transcripts, truncated };
+    },
+  );
+
+  const groupTranscriptsByCwd = Effect.fn("AgentSessionScanner.groupTranscriptsByCwd")(function* (
+    source: AgentSessionSource,
+    transcripts: ReadonlyArray<TranscriptCandidate>,
+    budget: MetadataReadBudget,
+  ) {
+    const byOwnerAndCwd = new Map<
+      string,
+      {
+        cwd: string;
+        providerInstanceId: ProviderInstanceId;
+        lastActiveAtMs: number;
+        transcripts: Array<{ filePath: string; mtimeMs: number }>;
+      }
+    >();
+
+    for (const transcript of transcripts) {
+      const cwd = yield* readCwd(transcript, budget);
+      if (cwd === null) continue;
+      const key = `${transcript.providerInstanceId}\0${cwd}`;
+      const existing = byOwnerAndCwd.get(key);
+      if (existing) {
+        existing.lastActiveAtMs = Math.max(existing.lastActiveAtMs, transcript.mtimeMs);
+        existing.transcripts.push(transcript);
+      } else {
+        byOwnerAndCwd.set(key, {
+          cwd,
+          providerInstanceId: transcript.providerInstanceId,
+          lastActiveAtMs: transcript.mtimeMs,
+          transcripts: [transcript],
+        });
+      }
+    }
+
+    return Array.from(byOwnerAndCwd.values(), (group): RawCandidate => ({
+      cwd: group.cwd,
+      source,
+      providerInstanceId: group.providerInstanceId,
+      threadCount: group.transcripts.length,
+      lastActiveAtMs: group.lastActiveAtMs,
+      transcripts: group.transcripts,
+    }));
+  });
+
+  const collectCandidates = Effect.fn("AgentSessionScanner.collectCandidates")(function* () {
+    const settings = yield* serverSettings.getSettings.pipe(
+      Effect.mapError((cause) => new AgentSessionScanError({ operation: "read-settings", cause })),
+    );
+
+    const raw: Array<RawCandidate> = [];
+    let truncated = false;
+
+    for (const source of ["claudeAgent", "codex"] as const) {
+      const instances: Array<{
+        readonly instanceId: ProviderInstanceId;
+        readonly config: ProviderInstanceConfig;
+      }> = Object.entries(settings.providerInstances)
+        .filter(
+          ([, instance]) => instance.driver === source && resolveProviderInstanceEnabled(instance),
+        )
+        .map(([instanceId, config]) => ({
+          instanceId: ProviderInstanceId.make(instanceId),
+          config,
+        }));
+      if (!Object.hasOwn(settings.providerInstances, source)) {
+        const legacyInstance = {
+          instanceId: ProviderInstanceId.make(source),
+          config: {
+            driver: ProviderDriverKind.make(source),
+            config: settings.providers[source],
+          },
+        };
+        if (resolveProviderInstanceEnabled(legacyInstance.config)) {
+          instances.push(legacyInstance);
+        }
+      }
+
+      // A shared home contains one copy of each session. Prefer the built-in
+      // instance as its owner, then keep configured order for custom accounts.
+      instances.sort((left, right) => {
+        const leftDefault = left.instanceId === source ? 0 : 1;
+        const rightDefault = right.instanceId === source ? 0 : 1;
+        return leftDefault - rightDefault;
+      });
+      const homes: Array<{ homePath: string; providerInstanceId: ProviderInstanceId }> = [];
+      const seenHomes = new Set<string>();
+      for (const { instanceId, config: instance } of instances) {
+        const homeVariable = source === "claudeAgent" ? "CLAUDE_CONFIG_DIR" : "CODEX_HOME";
+        const environmentHome =
+          instance.environment?.findLast((variable) => variable.name === homeVariable)?.value ??
+          hostEnvironment[homeVariable];
+
+        let homePath: string;
+        if (source === "claudeAgent") {
+          const config = decodeClaudeSettings(instance.config ?? {});
+          if (Option.isNone(config)) continue;
+          homePath = resolveClaudeConfigDir(config.value.homePath, environmentHome);
+        } else {
+          const config = decodeCodexSettings(instance.config ?? {});
+          if (Option.isNone(config)) continue;
+          const codexSettings =
+            config.value.homePath.trim().length === 0 &&
+            config.value.shadowHomePath.trim().length === 0 &&
+            environmentHome?.trim()
+              ? { ...config.value, homePath: environmentHome }
+              : config.value;
+          const layout = yield* resolveCodexHomeLayout(codexSettings).pipe(
+            Effect.provideService(Path.Path, path),
+          );
+          homePath = layout.sharedHomePath;
+        }
+
+        const homeKey = `${source}\0${yield* directoryIdentity(homePath)}`;
+        if (seenHomes.has(homeKey)) continue;
+        seenHomes.add(homeKey);
+        homes.push({ homePath, providerInstanceId: instanceId });
+      }
+
+      const transcriptCandidates: Array<TranscriptCandidate> = [];
+      const baseOperationBudget = Math.floor(
+        MAX_DISCOVERY_OPERATIONS_PER_SOURCE / Math.max(1, homes.length),
+      );
+      const extraOperationBudgets = MAX_DISCOVERY_OPERATIONS_PER_SOURCE % Math.max(1, homes.length);
+      for (const [index, home] of homes.entries()) {
+        const operationBudget = baseOperationBudget + (index < extraOperationBudgets ? 1 : 0);
+        if (operationBudget === 0) {
+          truncated = true;
+          continue;
+        }
+        const discovered = yield* source === "claudeAgent"
+          ? discoverClaudeTranscripts(home.homePath, home.providerInstanceId, operationBudget)
+          : discoverCodexTranscripts(home.homePath, home.providerInstanceId, operationBudget);
+        truncated ||= discovered.truncated;
+        transcriptCandidates.push(...discovered.transcripts);
+      }
+
+      transcriptCandidates.sort(
+        (left, right) =>
+          right.mtimeMs - left.mtimeMs || left.filePath.localeCompare(right.filePath),
+      );
+      if (transcriptCandidates.length > MAX_TRANSCRIPTS_PER_SOURCE) {
+        truncated = true;
+      }
+      // Give each account a turn before taking another file from the same home.
+      const selectedTranscripts = selectMetadataTranscripts(transcriptCandidates);
+      const metadataBudget: MetadataReadBudget = {
+        bytesRemaining: MAX_METADATA_BYTES_PER_SOURCE,
+        operationsRemaining: MAX_METADATA_OPERATIONS_PER_SOURCE,
+        recordsRemaining: MAX_METADATA_RECORDS_PER_SOURCE,
+        truncated: false,
+      };
+      raw.push(...(yield* groupTranscriptsByCwd(source, selectedTranscripts, metadataBudget)));
+      truncated ||= metadataBudget.truncated;
+    }
+
+    return { candidates: raw, truncated };
+  });
+
+  let cachedCandidates: ReadonlyArray<RawCandidate> | null = null;
+
+  const scan: AgentSessionScanner["Service"]["scan"] = Effect.gen(function* () {
+    const { candidates: raw, truncated } = yield* collectCandidates();
+    cachedCandidates = raw;
+
+    // Filesystem identity merges symlinks and case aliases without collapsing
+    // distinct case-sensitive directories.
+    const merged = new Map<
+      string,
+      {
+        path: string;
+        sources: Array<AgentSessionSource>;
+        threadCount: number;
+        lastActiveAtMs: number | null;
+      }
+    >();
+    const directoryKeys = new Map<string, string>();
+
+    for (const candidate of raw) {
+      const expanded = expandHomePath(candidate.cwd.trim());
+      if (!path.isAbsolute(expanded)) continue;
+      const resolved = path.resolve(expanded);
+      if (isExcludedProjectPath(resolved)) continue;
+      let key = directoryKeys.get(resolved);
+      if (key === undefined) {
+        const stats = yield* statOption(resolved);
+        // Directories that no longer exist can't be imported.
+        if (Option.isNone(stats) || stats.value.type !== "Directory") {
+          directoryKeys.set(resolved, "");
+          continue;
+        }
+        const realPath = yield* fileSystem
+          .realPath(resolved)
+          .pipe(Effect.orElseSucceed(() => resolved));
+        // A symlink can point into the worktrees directory even when its own
+        // spelling doesn't; check again with links resolved.
+        if (isExcludedProjectPath(realPath)) {
+          key = "";
+        } else {
+          key = yield* directoryIdentity(resolved, stats.value);
+        }
+        directoryKeys.set(resolved, key);
+      }
+      if (key === "") continue;
+
+      const existing = merged.get(key);
+      if (!existing) {
+        merged.set(key, {
+          path: resolved,
+          sources: [candidate.source],
+          threadCount: candidate.threadCount,
+          lastActiveAtMs: candidate.lastActiveAtMs,
+        });
+        continue;
+      }
+      if (!existing.sources.includes(candidate.source)) {
+        existing.sources.push(candidate.source);
+      }
+      existing.threadCount += candidate.threadCount;
+      existing.lastActiveAtMs =
+        existing.lastActiveAtMs === null || candidate.lastActiveAtMs === null
+          ? (existing.lastActiveAtMs ?? candidate.lastActiveAtMs)
+          : Math.max(existing.lastActiveAtMs, candidate.lastActiveAtMs);
+    }
+
+    // Resolve persisted roots too. A project and a transcript can name
+    // different symlinks to the same directory.
+    const shellSnapshot = yield* projectionSnapshotQuery
+      .getShellSnapshot()
+      .pipe(
+        Effect.mapError(
+          (cause) => new AgentSessionScanError({ operation: "read-projects", cause }),
+        ),
+      );
+    const importedProjectsByRoot = new Map<string, (typeof shellSnapshot.projects)[number]>();
+    for (const project of shellSnapshot.projects) {
+      const projectRoot = path.resolve(expandHomePath(project.workspaceRoot));
+      importedProjectsByRoot.set(normalizeProjectPathForComparison(projectRoot), project);
+      importedProjectsByRoot.set(yield* directoryIdentity(projectRoot), project);
+    }
+
+    const candidates: Array<AgentSessionProjectCandidate> = [];
+    for (const [key, entry] of merged.entries()) {
+      // Keep the path key for missing roots and use filesystem identity for
+      // aliases that resolve to the same directory.
+      const importedProject =
+        importedProjectsByRoot.get(normalizeProjectPathForComparison(entry.path)) ??
+        importedProjectsByRoot.get(key);
+      const candidatePath = importedProject?.workspaceRoot ?? entry.path;
+      candidates.push({
+        path: candidatePath,
+        title: path.basename(candidatePath) || candidatePath,
+        ...(importedProject === undefined ? {} : { projectId: importedProject.id }),
+        sources: entry.sources,
+        threadCount: entry.threadCount,
+        lastActiveAt:
+          entry.lastActiveAtMs === null
+            ? null
+            : DateTime.formatIso(DateTime.makeUnsafe(entry.lastActiveAtMs)),
+        alreadyImported: importedProject !== undefined,
+      });
+    }
+
+    // Newest first, undated candidates last.
+    candidates.sort((left, right) => {
+      if (left.lastActiveAt === right.lastActiveAt) return left.path.localeCompare(right.path);
+      if (left.lastActiveAt === null) return 1;
+      if (right.lastActiveAt === null) return -1;
+      return right.lastActiveAt.localeCompare(left.lastActiveAt);
+    });
+
+    return {
+      candidates,
+      scannedAt: DateTime.formatIso(yield* DateTime.now),
+      ...(truncated ? { truncated: true } : {}),
+    };
+  });
+
+  const prepareRecentThreads = Effect.fn("AgentSessionScanner.prepareRecentThreads")(function* (
+    workspaceRoot: string,
+    completedSources: ReadonlyArray<AgentSessionImportSource>,
+  ) {
+    const root = path.resolve(expandHomePath(workspaceRoot));
+    const realRoot = yield* fileSystem.realPath(root).pipe(Effect.orElseSucceed(() => root));
+    if (isExcludedProjectPath(root) || isExcludedProjectPath(realRoot)) return Stream.empty;
+    const rootIdentity = yield* directoryIdentity(root);
+    const nowMs = DateTime.toEpochMillis(yield* DateTime.now);
+    const cutoffMs = nowMs - RECENT_THREAD_WINDOW_MS;
+
+    const candidates = cachedCandidates ?? (yield* collectCandidates()).candidates;
+    cachedCandidates = candidates;
+
+    const eligibleTranscripts: Array<{
+      readonly candidate: RawCandidate;
+      readonly transcript: RawCandidate["transcripts"][number] & { readonly mtimeMs: number };
+    }> = [];
+    for (const candidate of candidates) {
+      const expanded = expandHomePath(candidate.cwd.trim());
+      if (!path.isAbsolute(expanded)) continue;
+      const resolved = path.resolve(expanded);
+      if ((yield* directoryIdentity(resolved)) !== rootIdentity) continue;
+
+      for (const transcript of candidate.transcripts) {
+        if (
+          transcript.mtimeMs === null ||
+          transcript.mtimeMs < cutoffMs ||
+          transcript.mtimeMs > nowMs
+        ) {
+          continue;
+        }
+        eligibleTranscripts.push({
+          candidate,
+          transcript: { ...transcript, mtimeMs: transcript.mtimeMs },
+        });
+      }
+    }
+
+    eligibleTranscripts.sort((left, right) => {
+      if (left.transcript.mtimeMs !== right.transcript.mtimeMs) {
+        return right.transcript.mtimeMs - left.transcript.mtimeMs;
+      }
+      return left.transcript.filePath.localeCompare(right.transcript.filePath);
+    });
+
+    const completedByFile = Map.groupBy(
+      completedSources,
+      (source) => `${source.providerInstanceId}\0${source.filePath}`,
+    );
+    const importedSessions = new Set<string>();
+    let bytesRemaining = MAX_IMPORT_BYTES;
+    let transcriptsRemaining = MAX_IMPORT_TRANSCRIPTS;
+    let recordsRemaining = MAX_IMPORT_RECORDS;
+    return Stream.fromIteratorSucceed(eligibleTranscripts.values(), 1).pipe(
+      Stream.mapEffect(({ candidate, transcript }) =>
+        Effect.gen(function* () {
+          const completed = completedByFile.get(
+            `${candidate.providerInstanceId}\0${transcript.filePath}`,
+          );
+          if (
+            completed === undefined &&
+            (transcriptsRemaining === 0 || bytesRemaining === 0 || recordsRemaining === 0)
+          ) {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Skipped" });
+          }
+          const stats = yield* statOption(transcript.filePath);
+          if (Option.isNone(stats) || stats.value.type !== "File") {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Skipped" });
+          }
+          const identity = transcriptIdentity(transcript.filePath, stats.value);
+          const completedSource = completed?.find(
+            (source) =>
+              source.provider === candidate.source && sameTranscriptIdentity(source, identity),
+          );
+          if (completedSource !== undefined) {
+            const sessionKey = `${completedSource.providerInstanceId}\0${completedSource.providerSessionId}`;
+            if (importedSessions.has(sessionKey)) return Option.none<AgentSessionRecentThread>();
+            importedSessions.add(sessionKey);
+            return Option.some<AgentSessionRecentThread>({
+              _tag: "AlreadyImported",
+              source: completedSource,
+            });
+          }
+          if (
+            transcriptsRemaining === 0 ||
+            recordsRemaining === 0 ||
+            identity.size > MAX_IMPORTED_TRANSCRIPT_BYTES ||
+            identity.size > bytesRemaining
+          ) {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Skipped" });
+          }
+          // Reserve the whole file even if its read or parse fails.
+          transcriptsRemaining -= 1;
+          bytesRemaining -= identity.size;
+          const contents = yield* readTranscript(transcript.filePath, identity);
+          if (contents === null) {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Skipped" });
+          }
+          const lines = splitTranscriptRecords(contents, recordsRemaining + 1);
+          if (lines.length > recordsRemaining) {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Skipped" });
+          }
+          recordsRemaining -= lines.length;
+
+          // A stable replacement file can belong to a different project than the cached candidate.
+          let snapshotCwd: string | null = null;
+          for (const line of lines) {
+            snapshotCwd = extractCwd(line);
+            if (snapshotCwd !== null) break;
+          }
+          if (snapshotCwd === null) {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Skipped" });
+          }
+          const expandedCwd = expandHomePath(snapshotCwd.trim());
+          if (
+            !path.isAbsolute(expandedCwd) ||
+            (yield* directoryIdentity(path.resolve(expandedCwd))) !== rootIdentity
+          ) {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Skipped" });
+          }
+
+          const parsedThread = parseAgentSessionTranscript(
+            {
+              contents,
+              source: candidate.source,
+              providerInstanceId: candidate.providerInstanceId,
+              fallbackSessionId: path.basename(transcript.filePath, ".jsonl"),
+              lastActiveAtMs: transcript.mtimeMs,
+            },
+            lines,
+          );
+          if (parsedThread === null) {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Skipped" });
+          }
+
+          const source: AgentSessionImportSource = {
+            ...identity,
+            provider: parsedThread.source,
+            providerInstanceId: parsedThread.providerInstanceId,
+            providerSessionId: parsedThread.providerSessionId,
+          };
+          const sessionKey = `${parsedThread.providerInstanceId}\0${parsedThread.providerSessionId}`;
+          if (importedSessions.has(sessionKey)) {
+            return Option.some<AgentSessionRecentThread>({ _tag: "Duplicate", source });
+          }
+          importedSessions.add(sessionKey);
+          return Option.some<AgentSessionRecentThread>({
+            _tag: "Importable",
+            thread: parsedThread,
+            source,
+          });
+        }),
+      ),
+      Stream.map(Option.toArray),
+      Stream.flattenIterable,
+    );
+  });
+
+  const recentThreads: AgentSessionScanner["Service"]["recentThreads"] = (
+    workspaceRoot,
+    completedSources = [],
+  ) => Stream.unwrap(prepareRecentThreads(workspaceRoot, completedSources));
+
+  return AgentSessionScanner.of({ scan, recentThreads });
+});
+
+export const layer = Layer.effect(AgentSessionScanner, make);
diff --git a/apps/server/src/project/ProjectFaviconResolver.test.ts b/apps/server/src/project/ProjectFaviconResolver.test.ts
index 2c7b0f7bdc62..f86e8f8aa399 100644
--- a/apps/server/src/project/ProjectFaviconResolver.test.ts
+++ b/apps/server/src/project/ProjectFaviconResolver.test.ts
@@ -54,11 +54,12 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
     it.effect("serves repeated resolves from cache instead of re-walking candidates", () =>
       Effect.gen(function* () {
         const resolver = yield* ProjectFaviconResolver.ProjectFaviconResolver;
+        const path = yield* Path.Path;
         const cwd = yield* makeTempDir;
         yield* writeTextFile(cwd, "public/favicon.svg", "<svg>public</svg>");
 
         const resolved = yield* resolver.resolvePath(cwd);
-        expect(resolved?.endsWith("public/favicon.svg")).toBe(true);
+        expect(resolved?.endsWith(path.join("public", "favicon.svg"))).toBe(true);
 
         // `favicon.svg` outranks `public/favicon.svg`, so a resolver that walked
         // the candidate list again would switch to it. Staying on the original
@@ -71,7 +72,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
 
         yield* TestClock.adjust(Duration.minutes(11));
 
-        expect((yield* resolver.resolvePath(cwd))?.endsWith("/favicon.svg")).toBe(true);
+        expect(yield* resolver.resolvePath(cwd)).toBe(path.join(cwd, "favicon.svg"));
         expect(yield* resolver.resolvePath(cwd)).not.toBe(resolved);
       }).pipe(Effect.provide(TestClock.layer())),
     );
@@ -125,6 +126,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
     it.effect("prefers a t3.json iconPath over well-known files", () =>
       Effect.gen(function* () {
         const resolver = yield* ProjectFaviconResolver.ProjectFaviconResolver;
+        const path = yield* Path.Path;
         const cwd = yield* makeTempDir;
         yield* writeTextFile(cwd, "t3.json", '{ "iconPath": "brand/mark.svg" }');
         yield* writeTextFile(cwd, "brand/mark.svg", "<svg>mark</svg>");
@@ -133,13 +135,14 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("brand/mark.svg");
+        expect(resolved).toBe(path.join(cwd, "brand", "mark.svg"));
       }),
     );
 
     it.effect("uses a saved project favicon override", () =>
       Effect.gen(function* () {
         const resolver = yield* ProjectFaviconResolver.ProjectFaviconResolver;
+        const path = yield* Path.Path;
         const cwd = yield* makeTempDir;
         yield* writeTextFile(cwd, "brand/custom.svg", "<svg>custom</svg>");
         yield* writeTextFile(cwd, "favicon.svg", "<svg>automatic</svg>");
@@ -147,7 +150,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd, "brand/custom.svg");
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("brand/custom.svg");
+        expect(resolved).toBe(path.join(cwd, "brand", "custom.svg"));
       }),
     );
 
@@ -231,7 +234,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -256,7 +259,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -274,7 +277,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -292,7 +295,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -310,7 +313,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
 
@@ -458,7 +461,7 @@ it.layer(TestLayer)("ProjectFaviconResolverLive", (it) => {
         const resolved = yield* resolver.resolvePath(cwd);
 
         expect(resolved).not.toBeNull();
-        expect(resolved).toContain("public/brand/logo.svg");
+        expect(resolved).toBe((yield* Path.Path).join(cwd, "public", "brand", "logo.svg"));
       }),
     );
   });
diff --git a/apps/server/src/project/ProjectSetupScriptRunner.test.ts b/apps/server/src/project/ProjectSetupScriptRunner.test.ts
index 8065d90917f0..6cc399dd4de2 100644
--- a/apps/server/src/project/ProjectSetupScriptRunner.test.ts
+++ b/apps/server/src/project/ProjectSetupScriptRunner.test.ts
@@ -41,8 +41,10 @@ const makeProjectionSnapshotQueryLayer = (project: OrchestrationProject) =>
     getProjectShellById: (projectId) =>
       Effect.succeed(projectId === project.id ? Option.some(project) : Option.none()),
     getFirstActiveThreadIdByProjectId: () => Effect.die("unused"),
+    getImportedAgentSessionSources: () => Effect.die("unused"),
     getThreadCheckpointContext: () => Effect.die("unused"),
     getFullThreadDiffContext: () => Effect.die("unused"),
+    getThreadRuntimeContext: () => Effect.die("unused"),
     getThreadShellById: () => Effect.die("unused"),
     getThreadDetailById: () => Effect.die("unused"),
     getThreadDetailSnapshot: () => Effect.die("unused"),
diff --git a/apps/server/src/project/RepositoryIdentityResolver.test.ts b/apps/server/src/project/RepositoryIdentityResolver.test.ts
index 72232a78b689..7c73752ee831 100644
--- a/apps/server/src/project/RepositoryIdentityResolver.test.ts
+++ b/apps/server/src/project/RepositoryIdentityResolver.test.ts
@@ -1,3 +1,5 @@
+// @effect-diagnostics nodeBuiltinImport:off - realpathSync.native resolves Windows 8.3 short names, which the Effect realPath does not.
+import * as NodeFS from "node:fs";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
 import * as Duration from "effect/Duration";
@@ -131,9 +133,11 @@ it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
 
       const resolver = yield* RepositoryIdentityResolver.RepositoryIdentityResolver;
       const identity = yield* resolver.resolve(cwd);
+      // Native realpath, since git reports the long form of a directory the
+      // temp dir may name by its 8.3 short form on Windows.
       const resolvedIdentityRoot =
-        identity?.rootPath === undefined ? "" : yield* fileSystem.realPath(identity.rootPath);
-      const resolvedCwd = yield* fileSystem.realPath(cwd);
+        identity?.rootPath === undefined ? "" : NodeFS.realpathSync.native(identity.rootPath);
+      const resolvedCwd = NodeFS.realpathSync.native(cwd);
 
       expect(identity).not.toBeNull();
       expect(identity?.canonicalKey).toBe("github.com/t3tools/t3code");
@@ -161,8 +165,8 @@ it.layer(NodeServices.layer)("RepositoryIdentityResolverLive", (it) => {
       const resolver = yield* RepositoryIdentityResolver.RepositoryIdentityResolver;
       const identity = yield* resolver.resolve(nestedWorkspace);
       const resolvedIdentityRoot =
-        identity?.rootPath === undefined ? "" : yield* fileSystem.realPath(identity.rootPath);
-      const resolvedRepoRoot = yield* fileSystem.realPath(repoRoot);
+        identity?.rootPath === undefined ? "" : NodeFS.realpathSync.native(identity.rootPath);
+      const resolvedRepoRoot = NodeFS.realpathSync.native(repoRoot);
 
       expect(identity).not.toBeNull();
       expect(identity?.canonicalKey).toBe("github.com/t3tools/t3code");
diff --git a/apps/server/src/provider/AntigravityInstallation.test.ts b/apps/server/src/provider/AntigravityInstallation.test.ts
index 8d6b62731cfd..0528cb4972c9 100644
--- a/apps/server/src/provider/AntigravityInstallation.test.ts
+++ b/apps/server/src/provider/AntigravityInstallation.test.ts
@@ -55,9 +55,24 @@ const zipFixtures = {
     "UEsDBBQAAAAIAAAAIl1zEy/oFAAAABQAAAASAAAAYWd5X2FjcF9zZXJ2ZXIuZXhlS8wryUwvSizLLKlUKCoFcnJTuQBQSwMEFAAAAAgAAAAiXV9yAykQAAAADgAAABkAAABsb2NhbGhhcm5lc3NfZXh0ZXJuYWwuZXhly8lPTsxRyEgsykstLuYCAFBLAQIUAxQAAAAIAAAAIl1zEy/oFAAAABQAAAASAAAAAAAAAAAAAADtgQAAAABhZ3lfYWNwX3NlcnZlci5leGVQSwECFAMUAAAACAAAACJdX3IDKRAAAAAOAAAAGQAAAAAAAAAAAAAA7YFEAAAAbG9jYWxoYXJuZXNzX2V4dGVybmFsLmV4ZVBLBQYAAAAAAgACAIcAAACLAAAAAAA=",
 };
 
-const completeArchive = Buffer.from(zipFixtures.complete, "base64");
+// The installation checks POSIX exec bits off the real filesystem unless the
+// platform is win32, so a linux platform mock cannot pass on NTFS. Default to
+// the host and let the fixture names follow; the suite is about install
+// mechanics, which are the same on every platform.
+const hostPlatform: NodeJS.Platform =
+  HostProcessPlatform.defaultValue() === "win32" ? "win32" : "linux";
+const completeArchive = Buffer.from(
+  hostPlatform === "win32" ? zipFixtures.windows : zipFixtures.complete,
+  "base64",
+);
+const executableName = hostPlatform === "win32" ? "agy_acp_server.exe" : "agy_acp_server.par";
+const harnessName =
+  hostPlatform === "win32" ? "localharness_external.exe" : "localharness_external";
 
-function releaseAsset(archive: Uint8Array = completeArchive, platform: NodeJS.Platform = "linux") {
+function releaseAsset(
+  archive: Uint8Array = completeArchive,
+  platform: NodeJS.Platform = hostPlatform,
+) {
   return {
     version: "fixture-new",
     url: "https://dl.google.com/antigravity-test.zip",
@@ -128,7 +143,7 @@ const makeHarness = Effect.fn("test.makeAntigravityInstallation")(function* (
   const path = yield* Path.Path;
   const baseDir =
     options.baseDir ?? (yield* fs.makeTempDirectoryScoped({ prefix: "t3-agy-test-" }));
-  const platform = options.platform ?? "linux";
+  const platform = options.platform ?? hostPlatform;
   const archive = options.archive ?? completeArchive;
   const asset = options.asset === undefined ? releaseAsset(archive, platform) : options.asset;
   const managedDirectory = path.join(baseDir, "tools", "antigravity-acp", `${platform}-x64`);
@@ -472,7 +487,7 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
           ...fs,
           sink: (target, options) =>
             (stage === "download" && target.endsWith("download.zip")) ||
-            (stage === "extract" && target.endsWith("agy_acp_server.par"))
+            (stage === "extract" && target.endsWith(executableName))
               ? fs.sink(target, options).pipe(Sink.mapInputEffect(() => Effect.fail(noSpace)))
               : fs.sink(target, options),
           writeFileString: (target, content, options) =>
@@ -525,7 +540,7 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
           fileSystem: FileSystem.FileSystem.of({
             ...fs,
             sink: (target, options) =>
-              phase === "extracting" && target.endsWith("agy_acp_server.par")
+              phase === "extracting" && target.endsWith(executableName)
                 ? fs
                     .sink(target, options)
                     .pipe(
@@ -681,65 +696,69 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
       }),
   );
 
-  it.effect("honors explicit paths and reports invalid overrides without falling back", () =>
-    Effect.gen(function* () {
-      const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agy-path-test-" });
-      const externalDirectory = path.join(baseDir, "external");
-      const externalExecutable = path.join(externalDirectory, "agy_acp_server.par");
-      const externalHarness = path.join(externalDirectory, "localharness_external");
-      yield* fs.makeDirectory(externalDirectory);
-      yield* fs.writeFileString(externalExecutable, "external server", { mode: 0o755 });
-      yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
-      const { installation } = yield* makeHarness({
-        baseDir,
-        path: externalDirectory,
-        previous: true,
-      });
-      yield* expectPreviousRelease(installation);
-      expect(yield* installation.resolve(undefined, { PATH: externalDirectory })).toMatchObject({
-        source: "managed",
-        version: previousVersion,
-      });
-      expect(yield* installation.resolve(externalExecutable)).toMatchObject({
-        executablePath: externalExecutable,
-        source: "override",
-        managedVersionDirectory: null,
-      });
-      expect(yield* installation.resolve("agy_acp_server.par")).toMatchObject({
-        source: "override",
-      });
-      yield* fs.remove(externalHarness);
-      expect(yield* installation.resolve(externalExecutable).pipe(Effect.flip)).toMatchObject({
-        operation: "resolve",
-      });
-      expect(
-        yield* installation.resolve(path.join(baseDir, "missing")).pipe(Effect.flip),
-      ).toMatchObject({
-        operation: "resolve",
-      });
-      yield* expectPreviousRelease(installation);
-      yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
-      yield* installation.remove();
-      expect(yield* installation.resolve()).toMatchObject({
-        source: "path",
-        executablePath: externalExecutable,
-      });
-      const isolated = yield* makeHarness({ baseDir });
-      expect(yield* isolated.installation.resolve().pipe(Effect.flip)).toMatchObject({
-        operation: "resolve",
-      });
-      expect(
-        yield* isolated.installation.resolve(undefined, { PATH: externalDirectory }),
-      ).toMatchObject({
-        source: "path",
-        executablePath: externalExecutable,
-      });
-      expect(
-        yield* isolated.installation.resolve("agy_acp_server.par", { PATH: externalDirectory }),
-      ).toMatchObject({ source: "override", executablePath: externalExecutable });
-    }),
+  // Real posix executables in a real temp dir, resolved by a linux-mocked
+  // PATH walk; a Windows temp path cannot be split on `:`.
+  it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+    "honors explicit paths and reports invalid overrides without falling back",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agy-path-test-" });
+        const externalDirectory = path.join(baseDir, "external");
+        const externalExecutable = path.join(externalDirectory, executableName);
+        const externalHarness = path.join(externalDirectory, harnessName);
+        yield* fs.makeDirectory(externalDirectory);
+        yield* fs.writeFileString(externalExecutable, "external server", { mode: 0o755 });
+        yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
+        const { installation } = yield* makeHarness({
+          baseDir,
+          path: externalDirectory,
+          previous: true,
+        });
+        yield* expectPreviousRelease(installation);
+        expect(yield* installation.resolve(undefined, { PATH: externalDirectory })).toMatchObject({
+          source: "managed",
+          version: previousVersion,
+        });
+        expect(yield* installation.resolve(externalExecutable)).toMatchObject({
+          executablePath: externalExecutable,
+          source: "override",
+          managedVersionDirectory: null,
+        });
+        expect(yield* installation.resolve(executableName)).toMatchObject({
+          source: "override",
+        });
+        yield* fs.remove(externalHarness);
+        expect(yield* installation.resolve(externalExecutable).pipe(Effect.flip)).toMatchObject({
+          operation: "resolve",
+        });
+        expect(
+          yield* installation.resolve(path.join(baseDir, "missing")).pipe(Effect.flip),
+        ).toMatchObject({
+          operation: "resolve",
+        });
+        yield* expectPreviousRelease(installation);
+        yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
+        yield* installation.remove();
+        expect(yield* installation.resolve()).toMatchObject({
+          source: "path",
+          executablePath: externalExecutable,
+        });
+        const isolated = yield* makeHarness({ baseDir });
+        expect(yield* isolated.installation.resolve().pipe(Effect.flip)).toMatchObject({
+          operation: "resolve",
+        });
+        expect(
+          yield* isolated.installation.resolve(undefined, { PATH: externalDirectory }),
+        ).toMatchObject({
+          source: "path",
+          executablePath: externalExecutable,
+        });
+        expect(
+          yield* isolated.installation.resolve(executableName, { PATH: externalDirectory }),
+        ).toMatchObject({ source: "override", executablePath: externalExecutable });
+      }),
   );
 
   it.effect("keeps leased releases available while new sessions resolve the new release", () =>
@@ -770,20 +789,12 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
         yield* fs.remove(previous.harnessPath);
         const externalDirectory = path.join(baseDir, "external");
         yield* fs.makeDirectory(externalDirectory);
-        yield* fs.writeFileString(
-          path.join(externalDirectory, "agy_acp_server.par"),
-          "external server",
-          {
-            mode: 0o755,
-          },
-        );
-        yield* fs.writeFileString(
-          path.join(externalDirectory, "localharness_external"),
-          "external harness",
-          {
-            mode: 0o755,
-          },
-        );
+        yield* fs.writeFileString(path.join(externalDirectory, executableName), "external server", {
+          mode: 0o755,
+        });
+        yield* fs.writeFileString(path.join(externalDirectory, harnessName), "external harness", {
+          mode: 0o755,
+        });
         const restarted = yield* makeHarness({ baseDir, path: externalDirectory });
         expect(yield* restarted.installation.state).toMatchObject({
           phase: "failed",
@@ -820,8 +831,8 @@ it.layer(NodeServices.layer)("Antigravity installation", (it) => {
         const profileDirectory = path.join(baseDir, "providers", "antigravity", "profile");
         yield* fs.makeDirectory(externalDirectory);
         yield* fs.makeDirectory(profileDirectory, { recursive: true });
-        const externalExecutable = path.join(externalDirectory, "agy_acp_server.par");
-        const externalHarness = path.join(externalDirectory, "localharness_external");
+        const externalExecutable = path.join(externalDirectory, executableName);
+        const externalHarness = path.join(externalDirectory, harnessName);
         const profilePath = path.join(profileDirectory, "preferences.json");
         yield* fs.writeFileString(externalExecutable, "external server", { mode: 0o755 });
         yield* fs.writeFileString(externalHarness, "external harness", { mode: 0o755 });
diff --git a/apps/server/src/provider/ClaudeModelCatalog.test.ts b/apps/server/src/provider/ClaudeModelCatalog.test.ts
index b370c8e24d3d..d5c9d8f53d1e 100644
--- a/apps/server/src/provider/ClaudeModelCatalog.test.ts
+++ b/apps/server/src/provider/ClaudeModelCatalog.test.ts
@@ -7,9 +7,11 @@ import {
   formatClaudeVersionUpgradeMessage,
   normalizeClaudeCatalogEffort,
   resolveClaudeCatalogApiModelId,
+  resolveClaudeCatalogEffort,
   resolveClaudeModelCatalog,
   resolveClaudeModelsForVersion,
   resolveClaudeModelSlug,
+  scopeClaudeModelCatalog,
 } from "./ClaudeModelCatalog.ts";
 
 /**
@@ -134,4 +136,58 @@ describe("Claude model catalog", () => {
     };
     assert.isFalse(hasValidClaudeManifestAdapters(malformed));
   });
+
+  it("appends custom models with their own descriptors and keeps bare slugs opaque", () => {
+    const catalog = scopeClaudeModelCatalog(resolveClaudeModelCatalog(manifest()), [
+      "synthetic",
+      {
+        slug: "claude-custom-tuned",
+        name: "Tuned",
+        capabilities: {
+          optionDescriptors: [
+            {
+              id: "effort",
+              label: "Reasoning",
+              type: "select",
+              options: [
+                { id: "gentle", label: "Gentle", isDefault: true },
+                { id: "brutal", label: "Brutal" },
+              ],
+            },
+          ],
+        },
+      },
+    ]);
+
+    // The bare custom slug shadows the built-in alias, so it no longer resolves to it.
+    assert.strictEqual(resolveClaudeModelSlug(catalog, "synthetic"), "synthetic");
+    assert.strictEqual(resolveClaudeCatalogEffort(catalog, "synthetic", "extreme"), undefined);
+
+    // The entry with descriptors resolves user-defined effort ids and passes
+    // them through untouched (no effortMap, no model suffix).
+    assert.strictEqual(
+      resolveClaudeCatalogEffort(catalog, "claude-custom-tuned", "brutal"),
+      "brutal",
+    );
+    assert.strictEqual(
+      resolveClaudeCatalogEffort(catalog, "claude-custom-tuned", "bogus"),
+      "gentle",
+    );
+    assert.strictEqual(
+      normalizeClaudeCatalogEffort(catalog, "brutal", "claude-custom-tuned"),
+      "brutal",
+    );
+    assert.strictEqual(
+      resolveClaudeCatalogApiModelId(catalog, {
+        instanceId: ProviderInstanceId.make("claudeAgent"),
+        model: "claude-custom-tuned",
+        options: [{ id: "effort", value: "brutal" }],
+      }),
+      "claude-custom-tuned",
+    );
+    assert.deepStrictEqual(
+      resolveClaudeModelsForVersion(catalog, "3.2.0").map((model) => model.slug),
+      ["claude-synthetic-next", "claude-custom-tuned"],
+    );
+  });
 });
diff --git a/apps/server/src/provider/ClaudeModelCatalog.ts b/apps/server/src/provider/ClaudeModelCatalog.ts
index bd554f042f0b..b1fcd6a92bbf 100644
--- a/apps/server/src/provider/ClaudeModelCatalog.ts
+++ b/apps/server/src/provider/ClaudeModelCatalog.ts
@@ -1,4 +1,5 @@
 import {
+  type CustomModelSetting,
   type ModelCapabilities,
   type ModelSelection,
   ProviderDriverKind,
@@ -9,7 +10,7 @@ import {
   getModelSelectionStringOptionValue,
   getProviderOptionCurrentValue,
   getProviderOptionDescriptors,
-  normalizeCustomModelSlug,
+  readCustomModelEntries,
 } from "@t3tools/shared/model";
 import { compareSemverVersions } from "@t3tools/shared/semver";
 
@@ -70,33 +71,51 @@ export function resolveClaudeModelCatalog(manifest: ModelManifestData): ClaudeMo
 
 export const BUNDLED_CLAUDE_MODEL_CATALOG = resolveClaudeModelCatalog(BUNDLED_MODEL_MANIFEST);
 
-/** Keeps custom model aliases opaque while preserving canonical built-in models and capabilities. */
+/**
+ * Scope the catalog to one instance's settings: custom model slugs stay opaque
+ * (a built-in alias they shadow is dropped, canonical slugs and capabilities
+ * are preserved), and custom entries that declare their own capabilities are
+ * appended so the adapter resolves effort / fast mode / thinking against the
+ * user's descriptors instead of the empty default. Custom entries carry no
+ * runtime profile, so option values pass through to Claude Code verbatim.
+ */
 export function scopeClaudeModelCatalog(
   catalog: ClaudeModelCatalog,
-  customModels: ReadonlyArray<string>,
+  customModels: ReadonlyArray<CustomModelSetting>,
 ): ClaudeModelCatalog {
-  const customAliases = new Set(
-    customModels.flatMap((model) => {
-      const slug = normalizeCustomModelSlug(model);
-      return slug ? [slug.toLowerCase()] : [];
-    }),
-  );
-  if (customAliases.size === 0) return catalog;
+  const customEntries = readCustomModelEntries(customModels);
+  if (customEntries.length === 0) return catalog;
+  const customAliases = new Set(customEntries.map((entry) => entry.slug.toLowerCase()));
 
-  return {
-    models: catalog.models.map((entry) => {
-      if (!entry.model.aliases?.some((alias) => customAliases.has(alias.toLowerCase()))) {
-        return entry;
-      }
-      return {
-        ...entry,
-        model: {
-          ...entry.model,
-          aliases: entry.model.aliases.filter((alias) => !customAliases.has(alias.toLowerCase())),
-        },
-      };
-    }),
-  };
+  const builtInModels = catalog.models.map((entry) => {
+    if (!entry.model.aliases?.some((alias) => customAliases.has(alias.toLowerCase()))) {
+      return entry;
+    }
+    return {
+      ...entry,
+      model: {
+        ...entry.model,
+        aliases: entry.model.aliases.filter((alias) => !customAliases.has(alias.toLowerCase())),
+      },
+    };
+  });
+  const builtInSlugs = new Set(builtInModels.map((entry) => entry.model.slug));
+  const customCatalogModels: Array<ClaudeCatalogModel> = [];
+  for (const entry of customEntries) {
+    if (!entry.capabilities || builtInSlugs.has(entry.slug)) continue;
+    customCatalogModels.push({
+      model: {
+        slug: entry.slug,
+        name: entry.name,
+        isCustom: true,
+        capabilities: entry.capabilities,
+      },
+      runtime: {},
+      compatibility: {},
+    });
+  }
+
+  return { models: [...builtInModels, ...customCatalogModels] };
 }
 
 export function resolveClaudeCatalogModel(
diff --git a/apps/server/src/provider/CodexDeveloperInstructions.ts b/apps/server/src/provider/CodexDeveloperInstructions.ts
index 2bb9647bd414..1c2439a9ad9a 100644
--- a/apps/server/src/provider/CodexDeveloperInstructions.ts
+++ b/apps/server/src/provider/CodexDeveloperInstructions.ts
@@ -22,7 +22,7 @@ Do not switch to global browser skills, Chrome, Node REPL browser automation, st
 const browserToolInstructions = (browserToolsAvailable: boolean): string =>
   browserToolsAvailable ? T3_CODE_BROWSER_TOOL_INSTRUCTIONS : "";
 
-export const codexPlanModeDeveloperInstructions = (
+const codexPlanModeDeveloperInstructions = (
   browserToolsAvailable: boolean,
 ): string => `<collaboration_mode># Plan Mode (Conversational)
 
@@ -155,7 +155,7 @@ If the user stays in Plan mode and asks for revisions after a prior \`<proposed_
 ${browserToolInstructions(browserToolsAvailable)}
 </collaboration_mode>`;
 
-export const codexDefaultModeDeveloperInstructions = (
+const codexDefaultModeDeveloperInstructions = (
   browserToolsAvailable: boolean,
 ): string => `<collaboration_mode># Collaboration Mode: Default
 
diff --git a/apps/server/src/provider/Drivers/AntigravitySkills.test.ts b/apps/server/src/provider/Drivers/AntigravitySkills.test.ts
index c5e1faacf237..bb3381216d72 100644
--- a/apps/server/src/provider/Drivers/AntigravitySkills.test.ts
+++ b/apps/server/src/provider/Drivers/AntigravitySkills.test.ts
@@ -5,6 +5,7 @@ import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 
 import { discoverAntigravitySkills } from "./AntigravitySkills.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const writeSkill = Effect.fn("writeSkill")(function* (directory: string, contents: string) {
   const fileSystem = yield* FileSystem.FileSystem;
@@ -239,27 +240,29 @@ it.layer(NodeServices.layer)("discoverAntigravitySkills", (it) => {
     }),
   );
 
-  it.effect("follows directory symlinks used to install shared skills", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const input = yield* makeWorkspace();
-      const sourceDirectory = path.join(input.profileDirectory, "shared-review");
-      yield* writeSkill(sourceDirectory, "---\nname: review\n---\n");
-      const root = path.join(input.cwd, ".agents", "skills");
-      const linkedDirectory = path.join(root, "review");
-      yield* fileSystem.makeDirectory(root, { recursive: true });
-      yield* fileSystem.symlink(sourceDirectory, linkedDirectory);
+  it.effect.skipIf(!symlinksSupported)(
+    "follows directory symlinks used to install shared skills",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const input = yield* makeWorkspace();
+        const sourceDirectory = path.join(input.profileDirectory, "shared-review");
+        yield* writeSkill(sourceDirectory, "---\nname: review\n---\n");
+        const root = path.join(input.cwd, ".agents", "skills");
+        const linkedDirectory = path.join(root, "review");
+        yield* fileSystem.makeDirectory(root, { recursive: true });
+        yield* fileSystem.symlink(sourceDirectory, linkedDirectory);
 
-      assert.deepEqual(yield* discoverAntigravitySkills(input), [
-        {
-          name: "review",
-          path: path.join(linkedDirectory, "SKILL.md"),
-          scope: "project",
-          enabled: true,
-        },
-      ]);
-    }),
+        assert.deepEqual(yield* discoverAntigravitySkills(input), [
+          {
+            name: "review",
+            path: path.join(linkedDirectory, "SKILL.md"),
+            scope: "project",
+            enabled: true,
+          },
+        ]);
+      }),
   );
 
   it.effect("rejects an oversized skill instead of returning an incomplete catalog", () =>
diff --git a/apps/server/src/provider/Drivers/ClaudeDriver.ts b/apps/server/src/provider/Drivers/ClaudeDriver.ts
index efcf19e9d6b1..324284a3a4c7 100644
--- a/apps/server/src/provider/Drivers/ClaudeDriver.ts
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -26,6 +26,7 @@ import { ChildProcessSpawner } from "effect/unstable/process";
 import { makeClaudeTextGeneration } from "../../textGeneration/ClaudeTextGeneration.ts";
 import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
 import { ServerConfig } from "../../config.ts";
+import { expandHomePath } from "../../pathExpansion.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { ProviderDriverError } from "../Errors.ts";
 import { makeClaudeAdapter } from "../Layers/ClaudeAdapter.ts";
@@ -48,6 +49,7 @@ import { withInstanceIdentity } from "./instanceIdentity.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
 import {
   enrichProviderSnapshotWithVersionAdvisory,
+  makeCachedProviderMaintenanceResolution,
   makePackageManagedProviderMaintenanceResolver,
   normalizeCommandPath,
   resolveProviderMaintenanceCapabilitiesEffect,
@@ -76,11 +78,8 @@ function isClaudeNativeCommandPath(commandPath: string): boolean {
 const UPDATE = makePackageManagedProviderMaintenanceResolver({
   provider: DRIVER_KIND,
   npmPackageName: "@anthropic-ai/claude-code",
-  homebrewFormula: "claude-code",
   nativeUpdate: {
-    executable: "claude",
     args: ["update"],
-    lockKey: "claude-native",
     isCommandPath: isClaudeNativeCommandPath,
   },
 });
@@ -121,11 +120,21 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
         driverKind: DRIVER_KIND,
         instanceId,
       });
-      const effectiveConfig = { ...config, enabled } satisfies ClaudeSettings;
-      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
-        binaryPath: effectiveConfig.binaryPath,
-        env: processEnv,
-      });
+      const effectiveConfig = {
+        ...config,
+        enabled,
+        binaryPath: expandHomePath(config.binaryPath),
+      } satisfies ClaudeSettings;
+      const resolveMaintenance = yield* makeCachedProviderMaintenanceResolution(
+        resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+          binaryPath: effectiveConfig.binaryPath,
+          env: processEnv,
+        }).pipe(
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+          Effect.provideService(FileSystem.FileSystem, fileSystem),
+          Effect.provideService(Path.Path, path),
+        ),
+      );
       const continuationGroupKey = yield* makeClaudeContinuationGroupKey(effectiveConfig);
       const stampIdentity = withInstanceIdentity({
         instanceId,
@@ -189,7 +198,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
 
       const snapshotSettings = makeProviderSnapshotSettingsSource(effectiveConfig, serverSettings);
       const snapshot = yield* makeManagedServerProvider<ProviderSnapshotSettings<ClaudeSettings>>({
-        maintenanceCapabilities,
+        resolveMaintenance,
         getSettings: snapshotSettings.getSettings,
         streamSettings: snapshotSettings.streamSettings,
         haveSettingsChanged: haveProviderSnapshotSettingsChanged,
@@ -202,9 +211,12 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
           ),
         checkProvider,
         enrichSnapshot: ({ settings, snapshot, publishSnapshot }) =>
-          enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities, {
-            enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
-          }).pipe(
+          resolveMaintenance().pipe(
+            Effect.flatMap((maintenanceCapabilities) =>
+              enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities, {
+                enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
+              }),
+            ),
             Effect.provideService(HttpClient.HttpClient, httpClient),
             Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
           ),
diff --git a/apps/server/src/provider/Drivers/ClaudeSkillDispatch.test.ts b/apps/server/src/provider/Drivers/ClaudeSkillDispatch.test.ts
index 99074c8b07ed..e6e6da9d5e9e 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkillDispatch.test.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkillDispatch.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from "vite-plus/test";
 
 import { planClaudeSkillDispatch } from "./ClaudeSkillDispatch.ts";
 
-const SKILLS = new Set(["implement", "review", "re-release-version"]);
+const SKILLS = new Set(["2spec", "implement", "review", "re-release-version"]);
 
 describe("planClaudeSkillDispatch", () => {
   it("leaves a prompt without a known skill untouched", () => {
@@ -27,6 +27,14 @@ describe("planClaudeSkillDispatch", () => {
     });
   });
 
+  it("dispatches a known skill whose name begins with a digit", () => {
+    expect(planClaudeSkillDispatch("use $2spec for this", SKILLS)).toEqual({
+      leadingText: "use",
+      commandText: "/2spec for this",
+      skillName: "2spec",
+    });
+  });
+
   it("dispatches the last mention and rewrites earlier ones inline", () => {
     expect(planClaudeSkillDispatch("$review the diff, then $implement the fixes", SKILLS)).toEqual({
       leadingText: "/review the diff, then",
@@ -38,4 +46,10 @@ describe("planClaudeSkillDispatch", () => {
   it("ignores a dollar token glued to other text", () => {
     expect(planClaudeSkillDispatch("cost is 5$implement", SKILLS)).toBeUndefined();
   });
+
+  it("ignores currency amounts and compact monetary expressions", () => {
+    const skillsWithCurrency = new Set([...SKILLS, "20", "20k", "100M"]);
+    expect(planClaudeSkillDispatch("pay $20 tomorrow", skillsWithCurrency)).toBeUndefined();
+    expect(planClaudeSkillDispatch("budget is $20k tomorrow", skillsWithCurrency)).toBeUndefined();
+  });
 });
diff --git a/apps/server/src/provider/Drivers/ClaudeSkillDispatch.ts b/apps/server/src/provider/Drivers/ClaudeSkillDispatch.ts
index a008e0f9ec9b..27e7dcf68bdf 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkillDispatch.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkillDispatch.ts
@@ -29,7 +29,8 @@
  * (`packages/shared/src/composerInlineTokens.ts`), so a rendered chip and a
  * dispatched skill are always the same set.
  */
-const SKILL_MENTION_PATTERN = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+const SKILL_MENTION_PATTERN =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g;
 
 export interface ClaudeSkillDispatch {
   /** Text before the dispatched mention, or `undefined` when it opens the prompt. */
diff --git a/apps/server/src/provider/Drivers/ClaudeSkills.test.ts b/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
index 3e46ba94df03..d126a15c12b8 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkills.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -492,7 +493,11 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
 
   it.effect("lets the administrator's managed policy outrank every other settings file", () =>
     Effect.gen(function* () {
-      const path = yield* Path.Path;
+      // The function is pure on its `path` argument, so hand it the
+      // implementation matching each platform under test rather than the
+      // host's.
+      const path = yield* Path.Path.pipe(Effect.provide(NodePath.layerPosix));
+      const win32Path = yield* Path.Path.pipe(Effect.provide(NodePath.layerWin32));
 
       for (const [platform, expected] of [
         ["darwin", "/Library/Application Support/ClaudeCode/managed-settings.json"],
@@ -508,14 +513,15 @@ it.layer(NodeServices.layer)("discoverClaudeSkills", (it) => {
       }
 
       assert.deepEqual(
-        skillOverrideSettingsPaths(path, "/home/.claude", undefined, "win32", {
-          PROGRAMDATA: "C:/ProgramData",
+        skillOverrideSettingsPaths(win32Path, "C:\\Users\\me\\.claude", undefined, "win32", {
+          PROGRAMDATA: "C:\\ProgramData",
         }).at(-1),
-        "C:/ProgramData/ClaudeCode/managed-settings.json",
+        "C:\\ProgramData\\ClaudeCode\\managed-settings.json",
+      );
+      assert.deepEqual(
+        skillOverrideSettingsPaths(win32Path, "C:\\Users\\me\\.claude", undefined, "win32", {}),
+        ["C:\\Users\\me\\.claude\\settings.json"],
       );
-      assert.deepEqual(skillOverrideSettingsPaths(path, "/home/.claude", undefined, "win32", {}), [
-        "/home/.claude/settings.json",
-      ]);
 
       // Only the repository root's local file joins in, after the
       // workspace's own local file so it wins.
diff --git a/apps/server/src/provider/Drivers/CodexDriver.test.ts b/apps/server/src/provider/Drivers/CodexDriver.test.ts
new file mode 100644
index 000000000000..bac34db452fd
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CodexDriver.test.ts
@@ -0,0 +1,372 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+import { expect, it } from "@effect/vitest";
+import { ProviderInstanceId } from "@t3tools/contracts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import { HttpClient } from "effect/unstable/http";
+import * as ChildProcess from "effect/unstable/process/ChildProcess";
+import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
+
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
+import { ServerConfig } from "../../config.ts";
+import { ServerSettingsService } from "../../serverSettings.ts";
+import { layerTest as codexResetCreditLayerTest } from "../Layers/codexResetCredit.ts";
+import { NoOpProviderEventLoggers, ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import * as ModelManifest from "../ModelManifest.ts";
+import {
+  createProviderVersionAdvisory,
+  ProviderVersionCache,
+  resolveLatestProviderVersion,
+} from "../providerMaintenance.ts";
+import { CodexDriver } from "./CodexDriver.ts";
+
+const testLayer = ServerConfig.layerTest(process.cwd(), {
+  prefix: "t3-codex-driver-maintenance-",
+}).pipe(
+  Layer.provideMerge(NodeServices.layer),
+  Layer.provideMerge(ServerSettingsService.layerTest()),
+  Layer.provideMerge(ModelManifest.layerTest),
+  Layer.provideMerge(codexResetCreditLayerTest),
+  Layer.provideMerge(
+    Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+      shouldRunScopeWork: () => Effect.succeed(false),
+    }),
+  ),
+  Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+  Layer.provideMerge(
+    Layer.succeed(
+      HttpClient.HttpClient,
+      HttpClient.make(() => Effect.die("Disabled Codex must not make an HTTP request")),
+    ),
+  ),
+);
+
+// The `#!/bin/sh` stub below cannot be resolved as an executable on Windows.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
+const noSpawn = ChildProcessSpawner.make(() =>
+  Effect.die("Disabled Codex must not spawn a process"),
+);
+
+it.layer(testLayer)("CodexDriver", (it) => {
+  it.effect.skipIf(windowsHost)(
+    "runs the standalone updater against the shared home, not the shadow home",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-codex-driver-" });
+        const sharedHome = NodePath.join(tempDir, "codex-home");
+        const shadowHome = NodePath.join(tempDir, "codex-shadow");
+        const binaryPath = NodePath.join(sharedHome, "packages", "standalone", "bin", "codex");
+        yield* fs.makeDirectory(NodePath.dirname(binaryPath), { recursive: true });
+        yield* fs.writeFileString(binaryPath, "#!/bin/sh\n");
+        yield* fs.chmod(binaryPath, 0o755);
+
+        const instance = yield* CodexDriver.create({
+          instanceId: ProviderInstanceId.make("codex-shadow"),
+          displayName: "Codex test",
+          enabled: false,
+          environment: [],
+          config: {
+            ...CodexDriver.defaultConfig(),
+            binaryPath,
+            homePath: sharedHome,
+            shadowHomePath: shadowHome,
+          },
+        });
+
+        const capabilities = yield* instance.snapshot.resolveMaintenance();
+        expect(capabilities.update).toMatchObject({
+          executable: binaryPath,
+          args: ["update"],
+          lockKey: "codex-native",
+          env: { CODEX_HOME: sharedHome },
+        });
+      }).pipe(
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
+        Effect.scoped,
+      ),
+  );
+
+  it.effect("stays manual-only when the configured executable does not exist", () =>
+    Effect.gen(function* () {
+      const instance = yield* CodexDriver.create({
+        instanceId: ProviderInstanceId.make("codex-missing"),
+        displayName: "Codex test",
+        enabled: false,
+        environment: [],
+        config: {
+          ...CodexDriver.defaultConfig(),
+          binaryPath: NodePath.join(NodeOS.tmpdir(), "t3-codex-missing", "codex"),
+        },
+      });
+      expect((yield* instance.snapshot.resolveMaintenance()).update).toBeNull();
+    }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn), Effect.scoped),
+  );
+
+  for (const fixture of [
+    {
+      name: "leaves mise npm-backend installations manual-only",
+      installSegments: ["mise", "installs", "npm-openai-codex", "0.110.0"],
+      npmOwned: false,
+    },
+    {
+      name: "leaves mise tool aliases backed by npm manual-only",
+      installSegments: ["mise", "installs", "codex", "0.110.0"],
+      npmOwned: false,
+    },
+    {
+      name: "keeps npm updates for globals in a mise Node installation",
+      installSegments: ["mise", "installs", "node", "24.0.0"],
+      npmOwned: true,
+    },
+    {
+      name: "keeps npm updates for ordinary global installations",
+      installSegments: ["npm-global"],
+      npmOwned: true,
+    },
+  ] as const) {
+    it.effect.skipIf(windowsHost)(fixture.name, () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-codex-installer-" });
+        const installPath = NodePath.join(tempDir, ...fixture.installSegments);
+        const realBinaryPath = NodePath.join(
+          installPath,
+          "lib",
+          "node_modules",
+          "@openai",
+          "codex",
+          "bin",
+          "codex.js",
+        );
+        const binaryPath = NodePath.join(tempDir, "bin", "codex");
+        yield* fs.makeDirectory(NodePath.dirname(realBinaryPath), { recursive: true });
+        yield* fs.makeDirectory(NodePath.dirname(binaryPath), { recursive: true });
+        yield* fs.writeFileString(realBinaryPath, "#!/bin/sh\n");
+        yield* fs.chmod(realBinaryPath, 0o755);
+        yield* fs.symlink(realBinaryPath, binaryPath);
+
+        const instance = yield* CodexDriver.create({
+          instanceId: ProviderInstanceId.make("codex-installer"),
+          displayName: "Codex installer test",
+          enabled: false,
+          environment: [],
+          config: {
+            ...CodexDriver.defaultConfig(),
+            binaryPath,
+            homePath: NodePath.join(tempDir, "codex-home"),
+          },
+        });
+
+        const update = (yield* instance.snapshot.resolveMaintenance()).update;
+        if (fixture.npmOwned) {
+          expect(update).toMatchObject({
+            executable: "npm",
+            args: [
+              "install",
+              "-g",
+              "--prefix",
+              installPath,
+              "--allow-scripts=@openai/codex",
+              "@openai/codex@latest",
+            ],
+          });
+        } else {
+          expect(update).toBeNull();
+        }
+      }).pipe(
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
+        Effect.scoped,
+      ),
+    );
+  }
+
+  for (const layout of ["direct", "wrapper"] as const) {
+    it.effect.skipIf(windowsHost)(`leaves a mise ${layout} installation manual-only`, () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: `t3-codex-mise-${layout}-` });
+        const binaryPath =
+          layout === "direct"
+            ? NodePath.join(tempDir, "mise", "installs", "codex", "0.110.0", "codex")
+            : NodePath.join(tempDir, "omarchy", "bin", "codex");
+        yield* fs.makeDirectory(NodePath.dirname(binaryPath), { recursive: true });
+        yield* fs.writeFileString(
+          binaryPath,
+          layout === "direct"
+            ? "#!/bin/sh\n"
+            : '#!/bin/sh\nmise use -g --quiet "codex" || exit 1\nexec mise x "codex" -- "codex" "$@"\n',
+        );
+        yield* fs.chmod(binaryPath, 0o755);
+
+        const instance = yield* CodexDriver.create({
+          instanceId: ProviderInstanceId.make(`codex-mise-${layout}`),
+          displayName: "Codex mise test",
+          enabled: false,
+          environment: [],
+          config: {
+            ...CodexDriver.defaultConfig(),
+            binaryPath,
+            homePath: NodePath.join(tempDir, "codex-home"),
+          },
+        });
+
+        expect((yield* instance.snapshot.resolveMaintenance()).update).toBeNull();
+      }).pipe(
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
+        Effect.scoped,
+      ),
+    );
+  }
+
+  it.effect.each([
+    {
+      name: "conventional shim",
+      dataRoot: "mise",
+      commandName: "codex",
+      version: "0.153.4",
+      nodeFirst: false,
+    },
+    {
+      name: "custom data directory",
+      dataRoot: "custom-tool-data",
+      commandName: "codex",
+      version: "0.153.4",
+      nodeFirst: false,
+    },
+    {
+      name: "renamed configured command",
+      dataRoot: "mise",
+      commandName: "custom-codex",
+      version: "0.153.4",
+      nodeFirst: false,
+    },
+    {
+      name: "outdated provider",
+      dataRoot: "mise",
+      commandName: "codex",
+      version: "0.153.3",
+      nodeFirst: false,
+    },
+    {
+      name: "npm before shim",
+      dataRoot: "mise",
+      commandName: "codex",
+      version: "0.153.4",
+      nodeFirst: true,
+    },
+  ])(
+    "does not mistake Homebrew mise for Codex's installer: $name",
+    (fixture) =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-codex-mise-shim-" });
+        const brewPrefix = NodePath.join(tempDir, "homebrew");
+        const brewPath = NodePath.join(brewPrefix, "bin", "brew");
+        const misePath = NodePath.join(brewPrefix, "Cellar", "mise", "2026.9.1", "bin", "mise");
+        const shimDir = NodePath.join(tempDir, fixture.dataRoot, "shims");
+        const npmPrefix = NodePath.join(tempDir, "mise", "installs", "node", "24.13.0");
+        const npmBin = NodePath.join(npmPrefix, "bin");
+        const npmEntry = NodePath.join(
+          npmPrefix,
+          "lib",
+          "node_modules",
+          "@openai",
+          "codex",
+          "bin",
+          "codex.js",
+        );
+        for (const file of [brewPath, misePath, npmEntry]) {
+          yield* fs.makeDirectory(NodePath.dirname(file), { recursive: true });
+          yield* fs.writeFileString(file, "#!/bin/sh\n");
+          yield* fs.chmod(file, 0o755);
+        }
+        yield* fs.makeDirectory(shimDir, { recursive: true });
+        yield* fs.makeDirectory(npmBin, { recursive: true });
+        yield* fs.symlink(misePath, NodePath.join(shimDir, fixture.commandName));
+        yield* fs.symlink(npmEntry, NodePath.join(npmBin, fixture.commandName));
+        const lookupPath = [
+          ...(fixture.nodeFirst ? [npmBin, shimDir] : [shimDir, npmBin]),
+          NodePath.dirname(brewPath),
+        ].join(NodePath.delimiter);
+        const probes: Array<ReadonlyArray<string>> = [];
+        const metadataSpawner = ChildProcessSpawner.make((command) => {
+          if (!ChildProcess.isStandardCommand(command) || command.command !== brewPath) {
+            return Effect.die("Provider resolution must not execute a provider or updater");
+          }
+          probes.push(command.args);
+          const stdout =
+            command.args[0] === "--prefix"
+              ? brewPrefix
+              : JSON.stringify({ formulae: [{ versions: { stable: "2026.9.1" } }] });
+          return Effect.succeed(
+            ChildProcessSpawner.makeHandle({
+              pid: ChildProcessSpawner.ProcessId(1),
+              exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
+              isRunning: Effect.succeed(false),
+              kill: () => Effect.void,
+              unref: Effect.succeed(Effect.void),
+              stdin: Sink.drain,
+              stdout: Stream.encodeText(Stream.make(stdout)),
+              stderr: Stream.empty,
+              all: Stream.empty,
+              getInputFd: () => Sink.drain,
+              getOutputFd: () => Stream.empty,
+            }),
+          );
+        });
+        const instance = yield* CodexDriver.create({
+          instanceId: ProviderInstanceId.make("codex-mise-shim"),
+          displayName: "Codex shim test",
+          enabled: false,
+          environment: [{ name: "PATH", value: lookupPath, sensitive: false }],
+          config: {
+            ...CodexDriver.defaultConfig(),
+            binaryPath: fixture.commandName,
+            homePath: NodePath.join(tempDir, "codex-home"),
+          },
+        }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, metadataSpawner));
+        const capabilities = yield* instance.snapshot.resolveMaintenance();
+        const latestVersion = yield* resolveLatestProviderVersion(capabilities).pipe(
+          Effect.provideService(
+            ProviderVersionCache,
+            new Map([
+              ["@openai/codex", { expiresAt: Number.MAX_SAFE_INTEGER, version: "0.153.4" }],
+            ]),
+          ),
+        );
+        expect(probes).toEqual([]);
+        expect(latestVersion).toBe("0.153.4");
+        expect(
+          createProviderVersionAdvisory({
+            driver: CodexDriver.driverKind,
+            currentVersion: fixture.version,
+            latestVersion,
+            maintenanceCapabilities: capabilities,
+          }),
+        ).toMatchObject({
+          status: fixture.version === "0.153.4" ? "current" : "behind_latest",
+          currentVersion: fixture.version,
+          latestVersion: "0.153.4",
+          canUpdate: fixture.nodeFirst,
+        });
+        if (fixture.nodeFirst) {
+          expect(capabilities.update).toMatchObject({
+            executable: "npm",
+            args: expect.arrayContaining(["--prefix", npmPrefix, "@openai/codex@latest"]),
+          });
+        } else {
+          expect(capabilities.update).toBeNull();
+        }
+      }).pipe(Effect.scoped),
+    { skip: windowsHost },
+  );
+});
diff --git a/apps/server/src/provider/Drivers/CodexDriver.ts b/apps/server/src/provider/Drivers/CodexDriver.ts
index 04dad8d9c784..071fb20674a8 100644
--- a/apps/server/src/provider/Drivers/CodexDriver.ts
+++ b/apps/server/src/provider/Drivers/CodexDriver.ts
@@ -33,6 +33,7 @@ import { ChildProcessSpawner } from "effect/unstable/process";
 import { makeCodexTextGeneration } from "../../textGeneration/CodexTextGeneration.ts";
 import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
 import { ServerConfig } from "../../config.ts";
+import { expandHomePath } from "../../pathExpansion.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { ProviderDriverError } from "../Errors.ts";
 import { makeCodexAdapter } from "../Layers/CodexAdapter.ts";
@@ -55,7 +56,9 @@ import { withInstanceIdentity } from "./instanceIdentity.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
 import {
   enrichProviderSnapshotWithVersionAdvisory,
+  makeCachedProviderMaintenanceResolution,
   makePackageManagedProviderMaintenanceResolver,
+  normalizeCommandPath,
   resolveProviderMaintenanceCapabilitiesEffect,
 } from "../providerMaintenance.ts";
 import {
@@ -71,12 +74,29 @@ import {
 const decodeCodexSettings = Schema.decodeSync(CodexSettings);
 
 const DRIVER_KIND = ProviderDriverKind.make("codex");
-const UPDATE = makePackageManagedProviderMaintenanceResolver({
-  provider: DRIVER_KIND,
-  npmPackageName: "@openai/codex",
-  homebrewFormula: "codex",
-  nativeUpdate: null,
-});
+// The standalone installer lays out `<CODEX_HOME>/packages/standalone/…`;
+// CODEX_HOME is not always `~/.codex`.
+function isCodexStandaloneCommandPath(commandPath: string): boolean {
+  return normalizeCommandPath(commandPath).includes("/packages/standalone/");
+}
+
+/**
+ * `codex update` replaces the standalone tree under `CODEX_HOME`. That tree
+ * lives in the shared home even when an auth-overlay shadow home is in use
+ * (the overlay only carries auth and a few local entries), so the updater
+ * runs against `sharedHomePath` rather than the instance's effective home.
+ */
+function makeCodexMaintenanceResolver(sharedHomePath: string) {
+  return makePackageManagedProviderMaintenanceResolver({
+    provider: DRIVER_KIND,
+    npmPackageName: "@openai/codex",
+    nativeUpdate: {
+      args: ["update"],
+      isCommandPath: isCodexStandaloneCommandPath,
+      env: { CODEX_HOME: sharedHomePath },
+    },
+  });
+}
 
 /**
  * Services the driver needs to materialize an instance. Surfaced as the
@@ -108,6 +128,8 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
     Effect.gen(function* () {
       const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
       const resetCreditCoordinator = yield* CodexResetCreditCoordinator;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const pathService = yield* Path.Path;
       const httpClient = yield* HttpClient.HttpClient;
       const serverSettings = yield* ServerSettingsService;
       const eventLoggers = yield* ProviderEventLoggers;
@@ -136,12 +158,22 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
       const effectiveConfig = {
         ...config,
         enabled,
+        binaryPath: expandHomePath(config.binaryPath),
         homePath: homeLayout.effectiveHomePath ?? "",
       } satisfies CodexSettings;
-      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
-        binaryPath: effectiveConfig.binaryPath,
-        env: processEnv,
-      });
+      const resolveMaintenance = yield* makeCachedProviderMaintenanceResolution(
+        resolveProviderMaintenanceCapabilitiesEffect(
+          makeCodexMaintenanceResolver(homeLayout.sharedHomePath),
+          {
+            binaryPath: effectiveConfig.binaryPath,
+            env: processEnv,
+          },
+        ).pipe(
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+          Effect.provideService(FileSystem.FileSystem, fileSystem),
+          Effect.provideService(Path.Path, pathService),
+        ),
+      );
 
       // `makeCodexAdapter` and `makeCodexTextGeneration` have `never` error
       // channels at construction time — their failure modes are all on the
@@ -177,7 +209,7 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
       );
       const snapshotSettings = makeProviderSnapshotSettingsSource(effectiveConfig, serverSettings);
       const snapshot = yield* makeManagedServerProvider<ProviderSnapshotSettings<CodexSettings>>({
-        maintenanceCapabilities,
+        resolveMaintenance,
         getSettings: snapshotSettings.getSettings,
         streamSettings: snapshotSettings.streamSettings,
         haveSettingsChanged: haveProviderSnapshotSettingsChanged,
@@ -190,9 +222,12 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
           ),
         checkProvider,
         enrichSnapshot: ({ settings, snapshot, publishSnapshot }) =>
-          enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities, {
-            enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
-          }).pipe(
+          resolveMaintenance().pipe(
+            Effect.flatMap((maintenanceCapabilities) =>
+              enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities, {
+                enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
+              }),
+            ),
             Effect.provideService(HttpClient.HttpClient, httpClient),
             Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
           ),
diff --git a/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts b/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
index 03c717abb14d..2c78ffd18662 100644
--- a/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
+++ b/apps/server/src/provider/Drivers/CodexHomeLayout.test.ts
@@ -13,6 +13,7 @@ import {
   materializeCodexShadowHome,
   resolveCodexHomeLayout,
 } from "./CodexHomeLayout.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 const decodeCodexSettingsValue = Schema.decodeSync(CodexSettings);
 
 const decodeCodexSettings = (input: {
@@ -84,130 +85,139 @@ it.layer(NodeServices.layer)("CodexHomeLayout", (it) => {
   });
 
   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 mcpOauthLocksTarget = yield* fileSystem.readLink(
-          path.join(shadowHome, "mcp-oauth-locks"),
-        );
-        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(mcpOauthLocksTarget).toBe(path.join(sharedHome, "mcp-oauth-locks"));
-        expect(modelsCacheExists).toBe(false);
-        expect(authLinkResult._tag).toBe("Failure");
-        expect(authContents).toContain("shadow");
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "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 mcpOauthLocksTarget = yield* fileSystem.readLink(
+            path.join(shadowHome, "mcp-oauth-locks"),
+          );
+          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(mcpOauthLocksTarget).toBe(path.join(sharedHome, "mcp-oauth-locks"));
+          expect(modelsCacheExists).toBe(false);
+          expect(authLinkResult._tag).toBe("Failure");
+          expect(authContents).toContain("shadow");
+        }),
     );
 
-    it.effect("replaces Codex-created local MCP OAuth locks with the shared lock directory", () =>
-      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");
-        const sharedLocks = path.join(sharedHome, "mcp-oauth-locks");
-        const shadowLocks = path.join(shadowHome, "mcp-oauth-locks");
-
-        yield* writeTextFile(path.join(sharedLocks, "file-store.lock"), "");
-        yield* writeTextFile(path.join(shadowLocks, "file-store.lock"), "");
-
-        const layout = yield* resolveCodexHomeLayout(
-          decodeCodexSettings({
-            homePath: sharedHome,
-            shadowHomePath: shadowHome,
-          }),
-        );
-
-        yield* materializeCodexShadowHome(layout);
-
-        const locksTarget = yield* fileSystem.readLink(shadowLocks);
-        const sharedLockExists = yield* fileSystem.exists(
-          path.join(sharedLocks, "file-store.lock"),
-        );
-
-        expect(locksTarget).toBe(sharedLocks);
-        expect(sharedLockExists).toBe(true);
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "replaces Codex-created local MCP OAuth locks with the shared lock directory",
+      () =>
+        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");
+          const sharedLocks = path.join(sharedHome, "mcp-oauth-locks");
+          const shadowLocks = path.join(shadowHome, "mcp-oauth-locks");
+
+          yield* writeTextFile(path.join(sharedLocks, "file-store.lock"), "");
+          yield* writeTextFile(path.join(shadowLocks, "file-store.lock"), "");
+
+          const layout = yield* resolveCodexHomeLayout(
+            decodeCodexSettings({
+              homePath: sharedHome,
+              shadowHomePath: shadowHome,
+            }),
+          );
+
+          yield* materializeCodexShadowHome(layout);
+
+          const locksTarget = yield* fileSystem.readLink(shadowLocks);
+          const sharedLockExists = yield* fileSystem.exists(
+            path.join(sharedLocks, "file-store.lock"),
+          );
+
+          expect(locksTarget).toBe(sharedLocks);
+          expect(sharedLockExists).toBe(true);
+        }),
     );
 
-    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.skipIf(!symlinksSupported)(
+      "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", () =>
@@ -233,36 +243,38 @@ it.layer(NodeServices.layer)("CodexHomeLayout", (it) => {
       }),
     );
 
-    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).toBeInstanceOf(CodexShadowHomeEntryConflictError);
-        expect(error).toMatchObject({
-          sharedHomePath: sharedHome,
-          effectiveHomePath: shadowHome,
-          entryName: "config.toml",
-          linkPath: path.join(shadowHome, "config.toml"),
-          targetPath: path.join(sharedHome, "config.toml"),
-        });
-        expect(error.message).toBe(
-          `Cannot create Codex shadow home entry 'config.toml' because '${path.join(shadowHome, "config.toml")}' already exists and is not a symlink.`,
-        );
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "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).toBeInstanceOf(CodexShadowHomeEntryConflictError);
+          expect(error).toMatchObject({
+            sharedHomePath: sharedHome,
+            effectiveHomePath: shadowHome,
+            entryName: "config.toml",
+            linkPath: path.join(shadowHome, "config.toml"),
+            targetPath: path.join(sharedHome, "config.toml"),
+          });
+          expect(error.message).toBe(
+            `Cannot create Codex shadow home entry 'config.toml' because '${path.join(shadowHome, "config.toml")}' already exists and is not a symlink.`,
+          );
+        }),
     );
 
     it.effect("preserves filesystem operation, paths, and cause", () =>
diff --git a/apps/server/src/provider/Drivers/CursorDriver.test.ts b/apps/server/src/provider/Drivers/CursorDriver.test.ts
new file mode 100644
index 000000000000..4b9dc529c117
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CursorDriver.test.ts
@@ -0,0 +1,99 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+import { expect, it } from "@effect/vitest";
+import { ProviderInstanceId } from "@t3tools/contracts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import { HttpClient } from "effect/unstable/http";
+import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
+
+import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
+import { ServerConfig } from "../../config.ts";
+import { ServerSettingsService } from "../../serverSettings.ts";
+import { NoOpProviderEventLoggers, ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import { CursorDriver } from "./CursorDriver.ts";
+
+const testLayer = ServerConfig.layerTest(process.cwd(), {
+  prefix: "t3-cursor-driver-copy-command-",
+}).pipe(
+  Layer.provideMerge(NodeServices.layer),
+  Layer.provideMerge(ServerSettingsService.layerTest()),
+  Layer.provideMerge(
+    Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+      shouldRunScopeWork: () => Effect.succeed(false),
+    }),
+  ),
+  Layer.provideMerge(Layer.succeed(ProviderEventLoggers, NoOpProviderEventLoggers)),
+  Layer.provideMerge(
+    Layer.succeed(
+      HttpClient.HttpClient,
+      HttpClient.make(() => Effect.die("Disabled Cursor must not make an HTTP request")),
+    ),
+  ),
+);
+
+// The `#!/bin/sh` stub below cannot be resolved as an executable on Windows.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
+it.layer(testLayer)("CursorDriver", (it) => {
+  it.effect.skipIf(windowsHost)(
+    "quotes a configured executable path in the copyable update command",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-cursor-driver-" });
+        const binaryPath = NodePath.join(tempDir, "Cursor Tools", "bin", "cursor-agent");
+        yield* fs.makeDirectory(NodePath.dirname(binaryPath), { recursive: true });
+        yield* fs.writeFileString(binaryPath, "#!/bin/sh\n");
+        yield* fs.chmod(binaryPath, 0o755);
+
+        const instance = yield* CursorDriver.create({
+          instanceId: ProviderInstanceId.make("cursor-copy-command"),
+          displayName: "Cursor test",
+          enabled: false,
+          environment: [],
+          config: { ...CursorDriver.defaultConfig(), binaryPath },
+        });
+
+        const capabilities = yield* instance.snapshot.resolveMaintenance();
+        expect(capabilities.update).toMatchObject({
+          command: `'${binaryPath}' update`,
+          executable: binaryPath,
+          args: ["update"],
+        });
+        expect((yield* instance.snapshot.refresh).status).toBe("disabled");
+      }).pipe(
+        Effect.provideService(
+          ChildProcessSpawner.ChildProcessSpawner,
+          ChildProcessSpawner.make(() => Effect.die("Disabled Cursor must not spawn a process")),
+        ),
+        Effect.scoped,
+      ),
+  );
+
+  it.effect("stays manual-only when the configured executable does not exist", () =>
+    Effect.gen(function* () {
+      const instance = yield* CursorDriver.create({
+        instanceId: ProviderInstanceId.make("cursor-missing"),
+        displayName: "Cursor test",
+        enabled: false,
+        environment: [],
+        config: {
+          ...CursorDriver.defaultConfig(),
+          binaryPath: NodePath.join(NodeOS.tmpdir(), "t3-cursor-missing", "cursor-agent"),
+        },
+      });
+      expect((yield* instance.snapshot.resolveMaintenance()).update).toBeNull();
+    }).pipe(
+      Effect.provideService(
+        ChildProcessSpawner.ChildProcessSpawner,
+        ChildProcessSpawner.make(() => Effect.die("Disabled Cursor must not spawn a process")),
+      ),
+      Effect.scoped,
+    ),
+  );
+});
diff --git a/apps/server/src/provider/Drivers/CursorDriver.ts b/apps/server/src/provider/Drivers/CursorDriver.ts
index 9dbdaaaf7c8f..ddfda0f9133c 100644
--- a/apps/server/src/provider/Drivers/CursorDriver.ts
+++ b/apps/server/src/provider/Drivers/CursorDriver.ts
@@ -41,6 +41,8 @@ import {
 import { withInstanceIdentity } from "./instanceIdentity.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
 import {
+  makeCachedProviderMaintenanceResolution,
+  makeManualOnlyProviderMaintenanceCapabilities,
   makeProviderMaintenanceCapabilities,
   type ProviderMaintenanceCapabilitiesResolver,
   resolveProviderMaintenanceCapabilitiesEffect,
@@ -54,15 +56,25 @@ import { probeCursorSkills } from "./CursorSkills.ts";
 const decodeCursorSettings = Schema.decodeSync(CursorSettings);
 
 const DRIVER_KIND = ProviderDriverKind.make("cursor");
+// cursor-agent updates itself, so the resolved executable is its own updater.
+// No executable means nothing to update, not "whatever is on PATH".
 const UPDATE: ProviderMaintenanceCapabilitiesResolver = {
-  resolve: (options) =>
-    makeProviderMaintenanceCapabilities({
-      provider: DRIVER_KIND,
-      packageName: null,
-      updateExecutable: options?.binaryPath?.trim() || "cursor-agent",
-      updateArgs: ["update"],
-      updateLockKey: "cursor-agent",
-    }),
+  resolve: (context) =>
+    Effect.succeed(
+      context
+        ? makeProviderMaintenanceCapabilities({
+            provider: DRIVER_KIND,
+            packageName: null,
+            updateExecutable: context.resolvedCommandPath,
+            updateArgs: ["update"],
+            updateLockKey: "cursor-agent",
+            platform: context.platform,
+          })
+        : makeManualOnlyProviderMaintenanceCapabilities({
+            provider: DRIVER_KIND,
+            packageName: null,
+          }),
+    ),
 };
 
 export type CursorDriverEnv =
@@ -106,10 +118,16 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
         continuationGroupKey: continuationIdentity.continuationKey,
       });
       const effectiveConfig = { ...config, enabled } satisfies CursorSettings;
-      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
-        binaryPath: effectiveConfig.binaryPath,
-        env: processEnv,
-      });
+      const resolveMaintenance = yield* makeCachedProviderMaintenanceResolution(
+        resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+          binaryPath: effectiveConfig.binaryPath,
+          env: processEnv,
+        }).pipe(
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+          Effect.provideService(FileSystem.FileSystem, fileSystem),
+          Effect.provideService(Path.Path, path),
+        ),
+      );
 
       const adapter = yield* makeCursorAdapter(effectiveConfig, {
         environment: processEnv,
@@ -128,7 +146,7 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
 
       const snapshotSettings = makeProviderSnapshotSettingsSource(effectiveConfig, serverSettings);
       const snapshot = yield* makeManagedServerProvider<ProviderSnapshotSettings<CursorSettings>>({
-        maintenanceCapabilities,
+        resolveMaintenance,
         getSettings: snapshotSettings.getSettings,
         streamSettings: snapshotSettings.streamSettings,
         haveSettingsChanged: haveProviderSnapshotSettingsChanged,
@@ -138,15 +156,20 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
         // Model catalog and capabilities come exclusively from Cursor's
         // list_available_models extension method during provider checks.
         enrichSnapshot: ({ settings, snapshot: currentSnapshot, publishSnapshot }) =>
-          enrichCursorSnapshot({
-            settings: settings.provider,
-            snapshot: currentSnapshot,
-            maintenanceCapabilities,
-            enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
-            publishSnapshot,
-            stampIdentity,
-            httpClient,
-          }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+          resolveMaintenance().pipe(
+            Effect.flatMap((maintenanceCapabilities) =>
+              enrichCursorSnapshot({
+                settings: settings.provider,
+                snapshot: currentSnapshot,
+                maintenanceCapabilities,
+                enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
+                publishSnapshot,
+                stampIdentity,
+                httpClient,
+              }),
+            ),
+            Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+          ),
       }).pipe(
         Effect.mapError(
           (cause) =>
diff --git a/apps/server/src/provider/Drivers/CursorSkills.ts b/apps/server/src/provider/Drivers/CursorSkills.ts
index 5113fd3d0ca6..599dc712d46a 100644
--- a/apps/server/src/provider/Drivers/CursorSkills.ts
+++ b/apps/server/src/provider/Drivers/CursorSkills.ts
@@ -19,8 +19,9 @@ import * as Schema from "effect/Schema";
 import { parse as parseYamlDocument } from "yaml";
 
 const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
-const SKILL_MENTION_PATTERN = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
-const HAS_SKILL_MENTION_PATTERN = /(^|\s)\$[a-zA-Z][a-zA-Z0-9:_-]*(?=\s|$)/;
+const SKILL_MENTION_PATTERN =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+const HAS_SKILL_MENTION_PATTERN = new RegExp(SKILL_MENTION_PATTERN.source);
 const MAX_SKILL_DEPTH = 10;
 const MAX_SKILL_BYTES = FileSystem.Size(1_000_000);
 const MAX_SKILL_SCAN_ENTRIES = 10_000;
@@ -147,16 +148,18 @@ const discoverSkillsInRoot = Effect.fn("discoverCursorSkillsInRoot")(function* (
     if (!resolvedDirectory) {
       return;
     }
-    if (
-      visitedDirectories.has(resolvedDirectory) ||
-      (resolvedDirectory !== rootDirectory &&
-        !resolvedDirectory.startsWith(`${rootDirectory}${path.sep}`))
-    ) {
+    if (visitedDirectories.has(resolvedDirectory)) {
       return;
     }
     visitedDirectories.add(resolvedDirectory);
+    // A symlink whose target lives outside the root is a skill package
+    // boundary: read its own SKILL.md so linked skill libraries show up, but
+    // never walk the target tree.
+    const insideRoot =
+      resolvedDirectory === rootDirectory ||
+      resolvedDirectory.startsWith(`${rootDirectory}${path.sep}`);
 
-    const skillPath = path.join(resolvedDirectory, "SKILL.md");
+    const skillPath = path.join(directory, "SKILL.md");
     const skillInfo = yield* orUndefined(fileSystem.stat(skillPath), input.budget);
     if (skillInfo?.type === "File") {
       let frontmatter: CursorSkillFrontmatter | undefined = { cliVisible: true };
@@ -167,7 +170,7 @@ const discoverSkillsInRoot = Effect.fn("discoverCursorSkillsInRoot")(function* (
           frontmatter = parseSkillFrontmatter(contents);
         }
       }
-      const name = path.basename(resolvedDirectory).trim();
+      const name = path.basename(directory).trim();
       if (frontmatter?.cliVisible && name) {
         skills.push({
           name,
@@ -184,7 +187,10 @@ const discoverSkillsInRoot = Effect.fn("discoverCursorSkillsInRoot")(function* (
       }
     }
 
-    const entries = yield* orUndefined(fileSystem.readDirectory(resolvedDirectory), input.budget);
+    if (!insideRoot) {
+      return;
+    }
+    const entries = yield* orUndefined(fileSystem.readDirectory(directory), input.budget);
     if (!entries) {
       return;
     }
@@ -194,7 +200,7 @@ const discoverSkillsInRoot = Effect.fn("discoverCursorSkillsInRoot")(function* (
         return;
       }
       input.budget.remainingEntries -= 1;
-      const child = path.join(resolvedDirectory, entry);
+      const child = path.join(directory, entry);
       const info = yield* orUndefined(fileSystem.stat(child), input.budget);
       if (info?.type !== "Directory") continue;
       if (depth >= MAX_SKILL_DEPTH) {
diff --git a/apps/server/src/provider/Drivers/GrokDriver.ts b/apps/server/src/provider/Drivers/GrokDriver.ts
index 8957b4c67781..066d0a6b63a8 100644
--- a/apps/server/src/provider/Drivers/GrokDriver.ts
+++ b/apps/server/src/provider/Drivers/GrokDriver.ts
@@ -28,11 +28,7 @@ import {
 import { withInstanceIdentity } from "./instanceIdentity.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
 import { discoverGrokSkills } from "./GrokSkills.ts";
-import {
-  makeManualOnlyProviderMaintenanceCapabilities,
-  makeStaticProviderMaintenanceResolver,
-  resolveProviderMaintenanceCapabilitiesEffect,
-} from "../providerMaintenance.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
 import {
   haveProviderSnapshotSettingsChanged,
   makeProviderSnapshotSettingsSource,
@@ -41,12 +37,10 @@ import {
 const decodeGrokSettings = Schema.decodeSync(GrokSettings);
 
 const DRIVER_KIND = ProviderDriverKind.make("grok");
-const UPDATE = makeStaticProviderMaintenanceResolver(
-  makeManualOnlyProviderMaintenanceCapabilities({
-    provider: DRIVER_KIND,
-    packageName: null,
-  }),
-);
+const MAINTENANCE_CAPABILITIES = makeManualOnlyProviderMaintenanceCapabilities({
+  provider: DRIVER_KIND,
+  packageName: null,
+});
 
 export type GrokDriverEnv =
   | BackgroundPolicy.BackgroundPolicy
@@ -88,11 +82,6 @@ export const GrokDriver: ProviderDriver<GrokSettings, GrokDriverEnv> = {
         continuationGroupKey: continuationIdentity.continuationKey,
       });
       const effectiveConfig = { ...config, enabled } satisfies GrokSettings;
-      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
-        binaryPath: effectiveConfig.binaryPath,
-        env: processEnv,
-      });
-
       const adapter = yield* makeGrokAdapter(effectiveConfig, {
         environment: processEnv,
         ...(eventLoggers.native ? { nativeEventLogger: eventLoggers.native } : {}),
@@ -108,7 +97,7 @@ export const GrokDriver: ProviderDriver<GrokSettings, GrokDriverEnv> = {
 
       const snapshotSettings = makeProviderSnapshotSettingsSource(effectiveConfig, serverSettings);
       const snapshot = yield* makeManagedServerProvider<ProviderSnapshotSettings<GrokSettings>>({
-        maintenanceCapabilities,
+        resolveMaintenance: () => Effect.succeed(MAINTENANCE_CAPABILITIES),
         getSettings: snapshotSettings.getSettings,
         streamSettings: snapshotSettings.streamSettings,
         haveSettingsChanged: haveProviderSnapshotSettingsChanged,
@@ -118,7 +107,7 @@ export const GrokDriver: ProviderDriver<GrokSettings, GrokDriverEnv> = {
         enrichSnapshot: ({ settings, snapshot: currentSnapshot, publishSnapshot }) =>
           enrichGrokSnapshot({
             snapshot: currentSnapshot,
-            maintenanceCapabilities,
+            maintenanceCapabilities: MAINTENANCE_CAPABILITIES,
             enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
             publishSnapshot,
             httpClient,
diff --git a/apps/server/src/provider/Drivers/GrokSkills.test.ts b/apps/server/src/provider/Drivers/GrokSkills.test.ts
index 13415bc35de3..ce8a31b51985 100644
--- a/apps/server/src/provider/Drivers/GrokSkills.test.ts
+++ b/apps/server/src/provider/Drivers/GrokSkills.test.ts
@@ -1,141 +1,172 @@
 import { describe, expect, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
 import * as Sink from "effect/Sink";
 import * as Stream from "effect/Stream";
 import { ChildProcessSpawner } from "effect/unstable/process";
 
-import { discoverGrokSkills, parseGrokInspectSkills } from "./GrokSkills.ts";
+import { discoverGrokSkills } from "./GrokSkills.ts";
 
 const inspectPayload = (skills: ReadonlyArray<unknown>) => JSON.stringify({ skills });
 
-describe("parseGrokInspectSkills", () => {
-  it("maps inspect entries onto provider skills, sorted by name", () => {
-    const skills = parseGrokInspectSkills(
-      inspectPayload([
-        {
-          name: "writing-docs",
-          description: "Write user docs.",
-          source: { type: "user", path: "/home/dev/.grok/skills/writing-docs/SKILL.md" },
-          userInvocable: true,
-        },
+const makeInspectSpawner = (stdout: string, exitCode = 0, spawnCwds?: Array<string | undefined>) =>
+  ChildProcessSpawner.make((command) => {
+    spawnCwds?.push(command._tag === "StandardCommand" ? command.options.cwd : undefined);
+    return Effect.succeed(
+      ChildProcessSpawner.makeHandle({
+        pid: ChildProcessSpawner.ProcessId(1),
+        exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(exitCode)),
+        isRunning: Effect.succeed(false),
+        kill: () => Effect.void,
+        unref: Effect.succeed(Effect.void),
+        stdin: Sink.drain,
+        stdout: Stream.encodeText(Stream.make(stdout)),
+        stderr: Stream.empty,
+        all: Stream.empty,
+        getInputFd: () => Sink.drain,
+        getOutputFd: () => Stream.empty,
+      }),
+    );
+  });
+
+describe("discoverGrokSkills", () => {
+  it.effect("maps inspect entries onto provider skills, sorted by name", () =>
+    Effect.gen(function* () {
+      const skills = yield* discoverGrokSkills({ binaryPath: "grok" }, {});
+
+      expect(skills).toEqual([
         {
           name: "deploy",
           description: "Deploy the app.",
-          source: {
-            type: "plugin",
-            path: "/home/dev/.grok/installed-plugins/pkg/plug/skills/deploy/SKILL.md",
-          },
-          userInvocable: true,
+          path: "/home/dev/.grok/installed-plugins/pkg/plug/skills/deploy/SKILL.md",
+          scope: "plugin",
+          enabled: true,
         },
-      ]),
-    );
+        {
+          name: "writing-docs",
+          description: "Write user docs.",
+          path: "/home/dev/.grok/skills/writing-docs/SKILL.md",
+          scope: "user",
+          enabled: true,
+        },
+      ]);
+    }).pipe(
+      Effect.provideService(
+        ChildProcessSpawner.ChildProcessSpawner,
+        makeInspectSpawner(
+          inspectPayload([
+            {
+              name: "writing-docs",
+              description: "Write user docs.",
+              source: { type: "user", path: "/home/dev/.grok/skills/writing-docs/SKILL.md" },
+              userInvocable: true,
+            },
+            {
+              name: "deploy",
+              description: "Deploy the app.",
+              source: {
+                type: "plugin",
+                path: "/home/dev/.grok/installed-plugins/pkg/plug/skills/deploy/SKILL.md",
+              },
+              userInvocable: true,
+            },
+          ]),
+        ),
+      ),
+    ),
+  );
 
-    expect(skills).toEqual([
-      {
-        name: "deploy",
-        description: "Deploy the app.",
-        path: "/home/dev/.grok/installed-plugins/pkg/plug/skills/deploy/SKILL.md",
-        scope: "plugin",
-        enabled: true,
-      },
-      {
-        name: "writing-docs",
-        description: "Write user docs.",
-        path: "/home/dev/.grok/skills/writing-docs/SKILL.md",
-        scope: "user",
-        enabled: true,
-      },
-    ]);
-  });
+  it.effect("disables skills the CLI marks as not user-invocable", () =>
+    Effect.gen(function* () {
+      const skills = yield* discoverGrokSkills({ binaryPath: "grok" }, {});
 
-  it("disables skills the CLI marks as not user-invocable", () => {
-    const skills = parseGrokInspectSkills(
-      inspectPayload([
+      expect(skills).toEqual([
         {
           name: "internal-helper",
-          source: { type: "bundled", path: "/opt/grok/bundled/skills/internal-helper/SKILL.md" },
-          userInvocable: false,
+          path: "/opt/grok/bundled/skills/internal-helper/SKILL.md",
+          scope: "bundled",
+          enabled: false,
         },
-      ]),
-    );
-
-    expect(skills).toEqual([
-      {
-        name: "internal-helper",
-        path: "/opt/grok/bundled/skills/internal-helper/SKILL.md",
-        scope: "bundled",
-        enabled: false,
-      },
-    ]);
-  });
-
-  it("skips entries without a name or a filesystem path", () => {
-    const skills = parseGrokInspectSkills(
-      inspectPayload([
-        { name: "  ", source: { type: "user", path: "/tmp/skills/a/SKILL.md" } },
-        { name: "no-path", source: { type: "user" } },
-        { name: "no-source" },
-        "not-an-object",
-        { name: "kept", source: { type: "project", path: "/repo/.grok/skills/kept/SKILL.md" } },
-      ]),
-    );
+      ]);
+    }).pipe(
+      Effect.provideService(
+        ChildProcessSpawner.ChildProcessSpawner,
+        makeInspectSpawner(
+          inspectPayload([
+            {
+              name: "internal-helper",
+              source: {
+                type: "bundled",
+                path: "/opt/grok/bundled/skills/internal-helper/SKILL.md",
+              },
+              userInvocable: false,
+            },
+          ]),
+        ),
+      ),
+    ),
+  );
 
-    expect(skills.map((skill) => skill.name)).toEqual(["kept"]);
-  });
+  it.effect("skips entries without a name or a filesystem path", () =>
+    Effect.gen(function* () {
+      const skills = yield* discoverGrokSkills({ binaryPath: "grok" }, {});
+      expect(skills.map((skill) => skill.name)).toEqual(["kept"]);
+    }).pipe(
+      Effect.provideService(
+        ChildProcessSpawner.ChildProcessSpawner,
+        makeInspectSpawner(
+          inspectPayload([
+            { name: "  ", source: { type: "user", path: "/tmp/skills/a/SKILL.md" } },
+            { name: "no-path", source: { type: "user" } },
+            { name: "no-source" },
+            "not-an-object",
+            { name: "kept", source: { type: "project", path: "/repo/.grok/skills/kept/SKILL.md" } },
+          ]),
+        ),
+      ),
+    ),
+  );
 
-  it("returns an empty list for malformed or unexpected output", () => {
-    expect(parseGrokInspectSkills("not json")).toEqual([]);
-    expect(parseGrokInspectSkills("null")).toEqual([]);
-    expect(parseGrokInspectSkills(JSON.stringify({ skills: "nope" }))).toEqual([]);
-    expect(parseGrokInspectSkills(JSON.stringify({}))).toEqual([]);
-  });
-});
+  it.effect("rejects malformed or unexpected output as a decode failure", () =>
+    Effect.gen(function* () {
+      for (const stdout of ["not json", "null", '{"skills":"nope"}', "{}"]) {
+        const error = yield* discoverGrokSkills({ binaryPath: "grok" }, {}).pipe(
+          Effect.flip,
+          Effect.provideService(
+            ChildProcessSpawner.ChildProcessSpawner,
+            makeInspectSpawner(stdout),
+          ),
+        );
+        expect(error).toMatchObject({ _tag: "GrokSkillsProbeError", stage: "decode" });
+      }
+    }),
+  );
 
-describe("discoverGrokSkills", () => {
   it.effect("spawns in the configured cwd and rejects a failed probe", () => {
     const spawnCwds: Array<string | undefined> = [];
-    let exitCode = 0;
-    const spawner = ChildProcessSpawner.make((command) => {
-      spawnCwds.push(command._tag === "StandardCommand" ? command.options.cwd : undefined);
-      return Effect.succeed(
-        ChildProcessSpawner.makeHandle({
-          pid: ChildProcessSpawner.ProcessId(1),
-          exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(exitCode)),
-          isRunning: Effect.succeed(false),
-          kill: () => Effect.void,
-          unref: Effect.succeed(Effect.void),
-          stdin: Sink.drain,
-          stdout: Stream.encodeText(
-            Stream.make(
-              inspectPayload([
-                {
-                  name: "kept",
-                  source: { type: "project", path: "/workspaces/demo/.grok/skills/kept/SKILL.md" },
-                },
-              ]),
-            ),
-          ),
-          stderr: Stream.empty,
-          all: Stream.empty,
-          getInputFd: () => Sink.drain,
-          getOutputFd: () => Stream.empty,
-        }),
-      );
-    });
+    const stdout = inspectPayload([
+      {
+        name: "kept",
+        source: { type: "project", path: "/workspaces/demo/.grok/skills/kept/SKILL.md" },
+      },
+    ]);
 
     return Effect.gen(function* () {
       const skills = yield* discoverGrokSkills({ binaryPath: "grok" }, {}, "/workspaces/demo").pipe(
-        Effect.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+        Effect.provideService(
+          ChildProcessSpawner.ChildProcessSpawner,
+          makeInspectSpawner(stdout, 0, spawnCwds),
+        ),
       );
 
       expect(spawnCwds).toEqual(["/workspaces/demo"]);
       expect(skills.map((skill) => skill.name)).toEqual(["kept"]);
 
-      exitCode = 1;
       const failed = yield* discoverGrokSkills({ binaryPath: "grok" }).pipe(
         Effect.result,
-        Effect.provide(Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner)),
+        Effect.provideService(
+          ChildProcessSpawner.ChildProcessSpawner,
+          makeInspectSpawner(stdout, 1),
+        ),
       );
       expect(failed._tag).toBe("Failure");
     });
diff --git a/apps/server/src/provider/Drivers/GrokSkills.ts b/apps/server/src/provider/Drivers/GrokSkills.ts
index b7962205d346..53a20049ad5d 100644
--- a/apps/server/src/provider/Drivers/GrokSkills.ts
+++ b/apps/server/src/provider/Drivers/GrokSkills.ts
@@ -91,10 +91,6 @@ function decodeGrokInspectSkills(stdout: string): ReadonlyArray<ServerProviderSk
   return [...skillsByName.values()].sort((left, right) => left.name.localeCompare(right.name));
 }
 
-export function parseGrokInspectSkills(stdout: string): ReadonlyArray<ServerProviderSkill> {
-  return decodeGrokInspectSkills(stdout) ?? [];
-}
-
 /**
  * Run `grok inspect --json` and map the reported catalog onto provider
  * skills. Callers that need best-effort discovery can recover this effect to
diff --git a/apps/server/src/provider/Drivers/OpenCodeDriver.ts b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
index 08a4d220787b..72c1c0683de5 100644
--- a/apps/server/src/provider/Drivers/OpenCodeDriver.ts
+++ b/apps/server/src/provider/Drivers/OpenCodeDriver.ts
@@ -45,6 +45,7 @@ import { withInstanceIdentity } from "./instanceIdentity.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
 import {
   enrichProviderSnapshotWithVersionAdvisory,
+  makeCachedProviderMaintenanceResolution,
   makePackageManagedProviderMaintenanceResolver,
   normalizeCommandPath,
   resolveProviderMaintenanceCapabilitiesEffect,
@@ -69,11 +70,8 @@ function isOpenCodeNativeCommandPath(commandPath: string): boolean {
 const UPDATE = makePackageManagedProviderMaintenanceResolver({
   provider: DRIVER_KIND,
   npmPackageName: "opencode-ai",
-  homebrewFormula: "anomalyco/tap/opencode",
   nativeUpdate: {
-    executable: "opencode",
     args: ["upgrade"],
-    lockKey: "opencode-native",
     isCommandPath: isOpenCodeNativeCommandPath,
   },
 });
@@ -100,6 +98,9 @@ export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv>
   defaultConfig: (): OpenCodeSettings => decodeOpenCodeSettings({}),
   create: ({ instanceId, displayName, accentColor, environment, enabled, config }) =>
     Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const pathService = yield* Path.Path;
       const openCodeRuntime = yield* OpenCodeRuntime;
       const serverConfig = yield* ServerConfig;
       const httpClient = yield* HttpClient.HttpClient;
@@ -118,10 +119,16 @@ export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv>
         continuationGroupKey: continuationIdentity.continuationKey,
       });
       const effectiveConfig = { ...config, enabled } satisfies OpenCodeSettings;
-      const maintenanceCapabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
-        binaryPath: effectiveConfig.binaryPath,
-        env: processEnv,
-      });
+      const resolveMaintenance = yield* makeCachedProviderMaintenanceResolution(
+        resolveProviderMaintenanceCapabilitiesEffect(UPDATE, {
+          binaryPath: effectiveConfig.binaryPath,
+          env: processEnv,
+        }).pipe(
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
+          Effect.provideService(FileSystem.FileSystem, fileSystem),
+          Effect.provideService(Path.Path, pathService),
+        ),
+      );
 
       const adapter = yield* makeOpenCodeAdapter(effectiveConfig, {
         instanceId,
@@ -195,7 +202,7 @@ export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv>
       const snapshotSettings = makeProviderSnapshotSettingsSource(effectiveConfig, serverSettings);
       const snapshot = yield* makeManagedServerProvider<ProviderSnapshotSettings<OpenCodeSettings>>(
         {
-          maintenanceCapabilities,
+          resolveMaintenance,
           getSettings: snapshotSettings.getSettings,
           streamSettings: snapshotSettings.streamSettings,
           haveSettingsChanged: haveProviderSnapshotSettingsChanged,
@@ -205,9 +212,12 @@ export const OpenCodeDriver: ProviderDriver<OpenCodeSettings, OpenCodeDriverEnv>
             makePendingOpenCodeProvider(settings.provider).pipe(Effect.map(stampIdentity)),
           checkProvider,
           enrichSnapshot: ({ settings, snapshot, publishSnapshot }) =>
-            enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities, {
-              enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
-            }).pipe(
+            resolveMaintenance().pipe(
+              Effect.flatMap((maintenanceCapabilities) =>
+                enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities, {
+                  enableProviderUpdateChecks: settings.enableProviderUpdateChecks,
+                }),
+              ),
               Effect.provideService(HttpClient.HttpClient, httpClient),
               Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
             ),
diff --git a/apps/server/src/provider/Errors.ts b/apps/server/src/provider/Errors.ts
index 0cf1522399b4..4abb10554462 100644
--- a/apps/server/src/provider/Errors.ts
+++ b/apps/server/src/provider/Errors.ts
@@ -85,6 +85,22 @@ export class ProviderAdapterProcessError extends Schema.TaggedErrorClass<Provide
   }
 }
 
+/**
+ * ProviderWorkspaceMissingError - The session's working directory no longer
+ * exists on disk, so no provider process can start in it.
+ */
+export class ProviderWorkspaceMissingError extends Schema.TaggedErrorClass<ProviderWorkspaceMissingError>()(
+  "ProviderWorkspaceMissingError",
+  {
+    threadId: Schema.String,
+    cwd: Schema.String,
+  },
+) {
+  override get message(): string {
+    return `This thread's workspace folder no longer exists or is not a directory: ${this.cwd}. Restore the folder at this path before retrying.`;
+  }
+}
+
 /**
  * ProviderValidationError - Invalid provider API input.
  */
@@ -197,6 +213,7 @@ export type ProviderAdapterError =
 export type ProviderServiceError =
   | ProviderValidationError
   | ProviderUnsupportedError
+  | ProviderWorkspaceMissingError
   | ProviderInstanceNotFoundError
   | ProviderSessionNotFoundError
   | ProviderSessionDirectoryPersistenceError
diff --git a/apps/server/src/provider/Layers/AntigravityAdapter.test.ts b/apps/server/src/provider/Layers/AntigravityAdapter.test.ts
index 6020d688cbd4..4bd0bb3e1010 100644
--- a/apps/server/src/provider/Layers/AntigravityAdapter.test.ts
+++ b/apps/server/src/provider/Layers/AntigravityAdapter.test.ts
@@ -421,7 +421,8 @@ it.layer(layer)("AntigravityAdapter", (it) => {
         modelSelection: { instanceId, model: nativeAlternative },
       });
       expect(second.model).toBe(nativeAlternative);
-      expect(second.cwd).toBe("/tmp");
+      // The adapter resolves the cwd it was given through the host Path.
+      expect(second.cwd).toBe((yield* Path.Path).resolve("/tmp"));
       expect(h.launches[1]?.resumeSessionId).toBe(nativeSessionId);
       expect(h.calls).toEqual([
         "start",
diff --git a/apps/server/src/provider/Layers/AntigravityProvider.ts b/apps/server/src/provider/Layers/AntigravityProvider.ts
index 62bd224cd4da..bd886a123808 100644
--- a/apps/server/src/provider/Layers/AntigravityProvider.ts
+++ b/apps/server/src/provider/Layers/AntigravityProvider.ts
@@ -232,13 +232,14 @@ export const makeAntigravityProvider = Effect.fn("makeAntigravityProvider")(func
     return yield* options.stampIdentity(next.draft);
   });
 
+  const maintenanceCapabilities =
+    options.maintenanceCapabilities ??
+    makeManualOnlyProviderMaintenanceCapabilities({
+      provider: ProviderDriverKind.make("antigravity"),
+      packageName: null,
+    });
   const managed = yield* makeManagedServerProvider({
-    maintenanceCapabilities:
-      options.maintenanceCapabilities ??
-      makeManualOnlyProviderMaintenanceCapabilities({
-        provider: ProviderDriverKind.make("antigravity"),
-        packageName: null,
-      }),
+    resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
     getSettings: Effect.succeed(settings),
     streamSettings: Stream.empty,
     haveSettingsChanged: () => false,
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
index 99bb95d83c65..84cc03b75a6d 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
@@ -23,7 +23,9 @@ import {
 } from "@t3tools/contracts";
 import { createModelSelection } from "@t3tools/shared/model";
 import { assert, describe, it } from "@effect/vitest";
+import * as Clock from "effect/Clock";
 import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
@@ -1899,7 +1901,8 @@ describe("ClaudeAdapterLive", () => {
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
 
-      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 8).pipe(
+      const runtimeEventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.takeUntil((event) => event.type === "turn.completed"),
         Stream.runCollect,
         Effect.forkChild,
       );
@@ -1937,6 +1940,17 @@ describe("ClaudeAdapterLive", () => {
         },
       } as unknown as SDKMessage);
 
+      harness.query.emit({
+        type: "system",
+        subtype: "task_started",
+        task_id: "task-agent-1",
+        description: "Review the database layer",
+        task_type: "local_agent",
+        tool_use_id: "tool-task-1",
+        uuid: "task-agent-1-uuid",
+        session_id: "sdk-session-task",
+      } as unknown as SDKMessage);
+
       harness.query.emit({
         type: "assistant",
         session_id: "sdk-session-task",
@@ -1953,6 +1967,12 @@ describe("ClaudeAdapterLive", () => {
         subtype: "success",
         is_error: false,
         errors: [],
+        usage: {
+          input_tokens: 100,
+          cache_read_input_tokens: 40,
+          cache_creation_input_tokens: 10,
+          output_tokens: 20,
+        },
         session_id: "sdk-session-task",
         uuid: "result-task-1",
       } as unknown as SDKMessage);
@@ -1964,6 +1984,11 @@ describe("ClaudeAdapterLive", () => {
         assert.equal(toolStarted.payload.itemType, "collab_agent_tool_call");
         assert.equal(toolStarted.payload.title, "Subagent task");
       }
+      const completed = runtimeEvents.find((event) => event.type === "turn.completed");
+      assert.equal(completed?.type, "turn.completed");
+      if (completed?.type === "turn.completed") {
+        assert.equal(completed.payload.tokenUsage?.hasSubagents, true);
+      }
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
       Effect.provide(harness.layer),
@@ -1975,7 +2000,8 @@ describe("ClaudeAdapterLive", () => {
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
 
-      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 6).pipe(
+      const runtimeEventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.takeUntil((event) => event.type === "turn.completed"),
         Stream.runCollect,
         Effect.forkChild,
       );
@@ -1998,6 +2024,12 @@ describe("ClaudeAdapterLive", () => {
         is_error: false,
         errors: ["Error: Request was aborted."],
         stop_reason: "tool_use",
+        usage: {
+          input_tokens: 12,
+          cache_read_input_tokens: 3,
+          cache_creation_input_tokens: 1,
+          output_tokens: 4,
+        },
         session_id: "sdk-session-abort",
         uuid: "result-abort",
       } as unknown as SDKMessage);
@@ -2011,6 +2043,7 @@ describe("ClaudeAdapterLive", () => {
           "session.state.changed",
           "turn.started",
           "thread.started",
+          "thread.token-usage.updated",
           "turn.completed",
         ],
       );
@@ -2022,6 +2055,15 @@ describe("ClaudeAdapterLive", () => {
         assert.equal(turnCompleted.payload.state, "interrupted");
         assert.equal(turnCompleted.payload.errorMessage, "Error: Request was aborted.");
         assert.equal(turnCompleted.payload.stopReason, "tool_use");
+        assert.deepEqual(turnCompleted.payload.tokenUsage, {
+          usageStatus: "partial",
+          usageScope: "main_agent",
+          inputTokens: 16,
+          cachedInputTokens: 3,
+          cacheCreationTokens: 1,
+          outputTokens: 4,
+          hasSubagents: false,
+        });
       }
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
@@ -2090,6 +2132,177 @@ describe("ClaudeAdapterLive", () => {
     );
   });
 
+  it.effect("fails a turn when the result carries a give-up terminal_reason", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+
+      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 7).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      const session = yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      const turn = yield* adapter.sendTurn({
+        threadId: session.threadId,
+        input: "hello",
+        attachments: [],
+      });
+
+      // The CLI stamps subtype success with an empty error list when it
+      // gives up after exhausting API retries; the terminal_reason is the
+      // only structured failure signal.
+      harness.query.emit({
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        result: "",
+        errors: [],
+        stop_reason: null,
+        terminal_reason: "api_error",
+        session_id: "sdk-session-api-error",
+        uuid: "result-api-error",
+      } as unknown as SDKMessage);
+
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
+      assert.deepEqual(
+        runtimeEvents.map((event) => event.type),
+        [
+          "session.started",
+          "session.configured",
+          "session.state.changed",
+          "turn.started",
+          "thread.started",
+          "runtime.error",
+          "turn.completed",
+        ],
+      );
+
+      const turnCompleted = runtimeEvents[runtimeEvents.length - 1];
+      assert.equal(turnCompleted?.type, "turn.completed");
+      if (turnCompleted?.type === "turn.completed") {
+        assert.equal(String(turnCompleted.turnId), String(turn.turnId));
+        assert.equal(turnCompleted.payload.state, "failed");
+        assert.equal(
+          turnCompleted.payload.errorMessage,
+          "Claude gave up after repeated API errors.",
+        );
+      }
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("fails a turn for every dead-turn terminal_reason", () => {
+    const reasons = [
+      "blocking_limit",
+      "rapid_refill_breaker",
+      "prompt_too_long",
+      "image_error",
+      "model_error",
+      "malformed_tool_use_exhausted",
+      "budget_exhausted",
+      "structured_output_retry_exhausted",
+      "tool_deferred_unavailable",
+      "turn_setup_failed",
+    ];
+    // One harness per reason: the fake query settles a single turn.
+    const runDeadTurn = (reason: string) => {
+      const harness = makeHarness();
+      return Effect.gen(function* () {
+        const adapter = yield* ClaudeAdapter;
+        const completionFiber = yield* adapter.streamEvents.pipe(
+          Stream.filter((event) => event.type === "turn.completed"),
+          Stream.runHead,
+          Effect.forkChild,
+        );
+        const session = yield* adapter.startSession({
+          threadId: THREAD_ID,
+          provider: ProviderDriverKind.make("claudeAgent"),
+          runtimeMode: "full-access",
+        });
+        yield* adapter.sendTurn({ threadId: session.threadId, input: "hello", attachments: [] });
+        harness.query.emit({
+          type: "result",
+          subtype: "success",
+          is_error: false,
+          result: "",
+          errors: [],
+          stop_reason: null,
+          terminal_reason: reason,
+          session_id: "sdk-session-dead-turn",
+          uuid: `result-${reason}`,
+        } as unknown as SDKMessage);
+        const completed = yield* Fiber.join(completionFiber);
+        assert.equal(completed._tag, "Some");
+        if (completed._tag === "Some" && completed.value.type === "turn.completed") {
+          assert.equal(completed.value.payload.state, "failed", reason);
+          assert.ok(completed.value.payload.errorMessage, `${reason} carries an error message`);
+        }
+      }).pipe(
+        Effect.provideService(Random.Random, makeDeterministicRandomService()),
+        Effect.provide(harness.layer),
+      );
+    };
+    return Effect.forEach(reasons, runDeadTurn, { discard: true });
+  });
+
+  it.effect("fails a turn when a success result reports a 529 overload", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+
+      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 7).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      const session = yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      yield* adapter.sendTurn({
+        threadId: session.threadId,
+        input: "hello",
+        attachments: [],
+      });
+
+      harness.query.emit({
+        type: "result",
+        subtype: "success",
+        is_error: true,
+        api_error_status: 529,
+        result: "",
+        errors: [],
+        stop_reason: null,
+        session_id: "sdk-session-overload",
+        uuid: "result-overload",
+      } as unknown as SDKMessage);
+
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
+      const turnCompleted = runtimeEvents[runtimeEvents.length - 1];
+      assert.equal(turnCompleted?.type, "turn.completed");
+      if (turnCompleted?.type === "turn.completed") {
+        assert.equal(turnCompleted.payload.state, "failed");
+        assert.equal(
+          turnCompleted.payload.errorMessage,
+          "Claude API is overloaded (529). Try again shortly.",
+        );
+      }
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
   it.effect("interruptTurn settles live tasks and closes the provider session", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
@@ -2338,7 +2551,10 @@ describe("ClaudeAdapterLive", () => {
         session_id: "sdk-session-result-usage",
         usage: {
           input_tokens: 400,
+          cache_read_input_tokens: 90,
+          cache_creation_input_tokens: 10,
           output_tokens: 50,
+          output_tokens_details: { thinking_tokens: 30 },
         },
         modelUsage: {
           [SYNTHETIC_CLAUDE_CAPABLE_MODEL]: {
@@ -2356,16 +2572,211 @@ describe("ClaudeAdapterLive", () => {
         assert.deepEqual(usageEvent.payload.usage, {
           usedTokens: 200,
           lastUsedTokens: 200,
-          totalProcessedTokens: 450,
+          totalProcessedTokens: 550,
           inputTokens: 180,
           outputTokens: 20,
           maxTokens: 200000,
         });
       }
-      assert.equal(
-        runtimeEvents.find((event) => event.type === "turn.completed")?.type,
-        "turn.completed",
+      const completed = runtimeEvents.find((event) => event.type === "turn.completed");
+      assert.equal(completed?.type, "turn.completed");
+      if (completed?.type === "turn.completed") {
+        assert.deepEqual(completed.payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 500,
+          cachedInputTokens: 90,
+          cacheCreationTokens: 10,
+          reasoningTokens: 30,
+          outputTokens: 50,
+          hasSubagents: false,
+        });
+      }
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("treats omitted Claude cache counters as zero contributions", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+      yield* adapter.sendTurn({
+        threadId: THREAD_ID,
+        input: "uncached turn",
+        attachments: [],
+      });
+      harness.query.emit({
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        duration_ms: 100,
+        duration_api_ms: 90,
+        num_turns: 1,
+        result: "done",
+        stop_reason: "end_turn",
+        session_id: "sdk-session-uncached-usage",
+        usage: {
+          input_tokens: 42,
+          output_tokens: 9,
+        },
+      } as unknown as SDKMessage);
+
+      const completed = yield* Fiber.join(completedFiber);
+      assert.equal(completed._tag, "Some");
+      if (completed._tag === "Some" && completed.value.type === "turn.completed") {
+        assert.deepEqual(completed.value.payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 42,
+          outputTokens: 9,
+          hasSubagents: false,
+        });
+      }
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("uses per-turn result usage across consecutive Claude turns", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const firstTurnSettled = yield* Deferred.make<void>();
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.tap((event) =>
+          event.type === "session.state.changed" && event.payload.reason === "api_retry:1/2"
+            ? Deferred.succeed(firstTurnSettled, undefined).pipe(Effect.asVoid)
+            : Effect.void,
+        ),
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
       );
+
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+      yield* adapter.sendTurn({
+        threadId: THREAD_ID,
+        input: "first turn",
+        attachments: [],
+      });
+      harness.query.emit({
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        duration_ms: 100,
+        duration_api_ms: 90,
+        num_turns: 1,
+        result: "first",
+        stop_reason: "end_turn",
+        session_id: "sdk-session-consecutive-usage",
+        usage: {
+          input_tokens: 100,
+          cache_read_input_tokens: 20,
+          cache_creation_input_tokens: 5,
+          output_tokens: 10,
+        },
+        modelUsage: {
+          "claude-opus-4-6": {
+            inputTokens: 10_000,
+            outputTokens: 1_000,
+            cacheReadInputTokens: 2_000,
+            cacheCreationInputTokens: 500,
+            webSearchRequests: 0,
+            costUSD: 1,
+            contextWindow: 200_000,
+            maxOutputTokens: 64_000,
+          },
+        },
+      } as unknown as SDKMessage);
+      harness.query.emit({
+        type: "system",
+        subtype: "api_retry",
+        attempt: 1,
+        max_retries: 2,
+        retry_delay_ms: 1,
+        error_status: 502,
+        error: { type: "api_error" },
+        session_id: "sdk-session-consecutive-usage",
+        uuid: "consecutive-usage-barrier",
+      } as unknown as SDKMessage);
+      yield* Deferred.await(firstTurnSettled);
+
+      yield* adapter.sendTurn({
+        threadId: THREAD_ID,
+        input: "second turn",
+        attachments: [],
+      });
+      harness.query.emit({
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        duration_ms: 80,
+        duration_api_ms: 70,
+        num_turns: 2,
+        result: "second",
+        stop_reason: "end_turn",
+        session_id: "sdk-session-consecutive-usage",
+        usage: {
+          input_tokens: 30,
+          cache_read_input_tokens: 2,
+          cache_creation_input_tokens: 3,
+          output_tokens: 7,
+        },
+        modelUsage: {
+          "claude-opus-4-6": {
+            inputTokens: 20_000,
+            outputTokens: 2_000,
+            cacheReadInputTokens: 4_000,
+            cacheCreationInputTokens: 1_000,
+            webSearchRequests: 0,
+            costUSD: 2,
+            contextWindow: 200_000,
+            maxOutputTokens: 64_000,
+          },
+        },
+      } as unknown as SDKMessage);
+
+      const completed = Array.from(yield* Fiber.join(completedFiber));
+      assert.equal(completed[0]?.type, "turn.completed");
+      assert.equal(completed[1]?.type, "turn.completed");
+      if (completed[0]?.type === "turn.completed" && completed[1]?.type === "turn.completed") {
+        assert.deepEqual(completed[0].payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 125,
+          cachedInputTokens: 20,
+          cacheCreationTokens: 5,
+          outputTokens: 10,
+          hasSubagents: false,
+        });
+        assert.deepEqual(completed[1].payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 35,
+          cachedInputTokens: 2,
+          cacheCreationTokens: 3,
+          outputTokens: 7,
+          hasSubagents: false,
+        });
+      }
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
       Effect.provide(harness.layer),
@@ -2770,6 +3181,11 @@ describe("ClaudeAdapterLive", () => {
         assert.equal(String(turnCompleted.turnId), String(turn.turnId));
         assert.equal(turnCompleted.payload.state, "interrupted");
         assert.equal(turnCompleted.payload.errorMessage, "Claude runtime interrupted.");
+        assert.deepEqual(turnCompleted.payload.tokenUsage, {
+          usageStatus: "unavailable",
+          usageScope: "main_agent",
+          hasSubagents: false,
+        });
       }
 
       const sessionExited = runtimeEvents[5];
@@ -2949,225 +3365,820 @@ describe("ClaudeAdapterLive", () => {
 
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
-
-      const runtimeEventsFiber = yield* Stream.runForEach(
-        adapter.streamEvents,
-        () => Effect.void,
-      ).pipe(Effect.forkChild);
+
+      const runtimeEventsFiber = yield* Stream.runForEach(
+        adapter.streamEvents,
+        () => Effect.void,
+      ).pipe(Effect.forkChild);
+
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      yield* adapter.stopSession(THREAD_ID);
+
+      yield* Effect.yieldNow;
+      yield* Effect.yieldNow;
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust("50 millis");
+      yield* Effect.yieldNow;
+
+      runtimeEventsFiber.interruptUnsafe();
+
+      assert.equal(
+        promptConsumerError,
+        undefined,
+        `Prompt consumer should not receive a thrown error on session stop, ` +
+          `but got: "${promptConsumerError instanceof Error ? promptConsumerError.message : String(promptConsumerError)}"`,
+      );
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(layer),
+    );
+  });
+
+  it.effect("forwards Claude task progress summaries for subagent updates", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+
+      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 6).pipe(
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      harness.query.emit({
+        type: "system",
+        subtype: "task_progress",
+        task_id: "task-subagent-1",
+        description: "Running background teammate",
+        summary: "Code reviewer checked the migration edge cases.",
+        usage: {
+          total_tokens: 123,
+          tool_uses: 4,
+          duration_ms: 987,
+        },
+        session_id: "sdk-session-task-summary",
+        uuid: "task-progress-1",
+      } as unknown as SDKMessage);
+
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
+      const progressEvent = runtimeEvents.find((event) => event.type === "task.progress");
+      assert.equal(progressEvent?.type, "task.progress");
+      if (progressEvent?.type === "task.progress") {
+        assert.equal(
+          progressEvent.payload.summary,
+          "Code reviewer checked the migration edge cases.",
+        );
+        assert.equal(progressEvent.payload.description, "Running background teammate");
+      }
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("consumes undeclared and UX-internal system subtypes without warning rows", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const runtimeEventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.takeUntil(
+          (event) =>
+            event.type === "session.state.changed" && event.payload.reason === "api_retry:3/10",
+        ),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      // Undeclared wire-only roster snapshot + every typed UX-internal
+      // subtype and top-level type consumed silently: none may surface as
+      // unknown-subtype warnings.
+      for (const message of [
+        {
+          type: "system",
+          subtype: "background_tasks_changed",
+          tasks: [{ task_id: "t1", task_type: "local_agent", description: "Say hi" }],
+          session_id: "session",
+          uuid: "roster",
+        },
+        {
+          type: "system",
+          subtype: "vcs_state_changed",
+          kind: "push",
+          cwd: "/tmp/worktree",
+          session_id: "session",
+          uuid: "vcs",
+        },
+        {
+          type: "system",
+          subtype: "code_change_published",
+          provider: "github",
+          url: "https://github.com/pingdotgg/t3code/pull/1",
+          repo: "pingdotgg/t3code",
+          identifier: "1",
+          session_id: "session",
+          uuid: "ccp",
+        },
+        {
+          type: "system",
+          subtype: "task_updated",
+          task_id: "t1",
+          patch: { status: "running" },
+          session_id: "session",
+          uuid: "tu",
+        },
+        { type: "system", subtype: "commands_changed", session_id: "session", uuid: "cc" },
+        { type: "system", subtype: "local_command_output", session_id: "session", uuid: "lco" },
+        { type: "system", subtype: "plugin_install", session_id: "session", uuid: "pi" },
+        { type: "system", subtype: "memory_recall", session_id: "session", uuid: "mr" },
+        { type: "system", subtype: "elicitation_complete", session_id: "session", uuid: "ec" },
+        {
+          type: "system",
+          subtype: "control_request_progress",
+          request_id: "ctrl-1",
+          status: "started",
+          session_id: "session",
+          uuid: "crp",
+        },
+        {
+          type: "system",
+          subtype: "worker_shutting_down",
+          reason: "host_exit",
+          session_id: "session",
+          uuid: "wsd",
+        },
+        {
+          type: "system",
+          subtype: "informational",
+          content: "Loaded 3 skills",
+          level: "notice",
+          session_id: "session",
+          uuid: "info",
+        },
+        { type: "prompt_suggestion", suggestion: "try this", session_id: "session", uuid: "ps" },
+        {
+          type: "conversation_reset",
+          new_conversation_id: "conv-2",
+          session_id: "session",
+          uuid: "cr",
+        },
+        {
+          type: "system",
+          subtype: "notification",
+          key: "context",
+          text: "low priority note",
+          priority: "low",
+          session_id: "session",
+          uuid: "notif",
+        },
+      ]) {
+        harness.query.emit(message as unknown as SDKMessage);
+      }
+      // Safety model-fallback notices DO surface as a warning row.
+      harness.query.emit({
+        type: "system",
+        subtype: "model_refusal_fallback",
+        trigger: "refusal",
+        direction: "retry",
+        original_model: "claude-fable-5",
+        fallback_model: "claude-opus-4-8",
+        request_id: "req_test",
+        api_refusal_category: "cyber",
+        api_refusal_explanation: null,
+        content: "Safeguards flagged this message. Switched to Opus 4.8.",
+        session_id: "session",
+        uuid: "mrf",
+      } as unknown as SDKMessage);
+      // High-priority notifications DO surface as a warning row.
+      harness.query.emit({
+        type: "system",
+        subtype: "notification",
+        key: "limit",
+        text: "context window nearly full",
+        priority: "high",
+        session_id: "session",
+        uuid: "notif-high",
+      } as unknown as SDKMessage);
+      // Warning-level informational notes and refusals without a fallback
+      // model surface as warning rows too.
+      harness.query.emit({
+        type: "system",
+        subtype: "informational",
+        content: "Stop hook prevented continuation",
+        level: "warning",
+        prevent_continuation: true,
+        session_id: "session",
+        uuid: "info-warn",
+      } as unknown as SDKMessage);
+      harness.query.emit({
+        type: "system",
+        subtype: "model_refusal_no_fallback",
+        original_model: "claude-opus-5",
+        request_id: null,
+        api_refusal_explanation: "The request was declined by the API.",
+        content: "Model refused",
+        session_id: "session",
+        uuid: "mrnf",
+      } as unknown as SDKMessage);
+      // session_state_changed maps to the matching session states.
+      for (const [state, uuid] of [
+        ["running", "ssc-run"],
+        ["requires_action", "ssc-req"],
+        ["idle", "ssc-idle"],
+      ]) {
+        harness.query.emit({
+          type: "system",
+          subtype: "session_state_changed",
+          state,
+          session_id: "session",
+          uuid,
+        } as unknown as SDKMessage);
+      }
+      // api_retry maps to a session heartbeat, not a warning row.
+      harness.query.emit({
+        type: "system",
+        subtype: "api_retry",
+        attempt: 3,
+        max_retries: 10,
+        retry_delay_ms: 1000,
+        error_status: 502,
+        error: { type: "api_error" },
+        session_id: "session",
+        uuid: "retry",
+      } as unknown as SDKMessage);
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
+
+      const warnings = runtimeEvents.filter((event) => event.type === "runtime.warning");
+      // Exactly four warnings: the fallback notice, high-priority notification,
+      // warning-level informational note, and the refusal. Nothing else.
+      assert.deepEqual(
+        warnings.map((event) => event.payload.message),
+        [
+          "Safeguards flagged this message. Switched to Opus 4.8.",
+          "context window nearly full",
+          "Stop hook prevented continuation",
+          "The request was declined by the API.",
+        ],
+      );
+      const sessionStates = runtimeEvents
+        .filter((event) => event.type === "session.state.changed")
+        .map((event) =>
+          event.type === "session.state.changed"
+            ? `${event.payload.state}:${event.payload.reason ?? ""}`
+            : "",
+        )
+        .filter(
+          (entry) => entry.startsWith("running:session_state") || entry.includes("session_state"),
+        );
+      assert.deepEqual(sessionStates, [
+        "running:session_state:running",
+        "waiting:session_state:requires_action",
+        "ready:session_state:idle",
+      ]);
+      const heartbeat = runtimeEvents.find(
+        (event) =>
+          event.type === "session.state.changed" &&
+          typeof event.payload.reason === "string" &&
+          event.payload.reason.startsWith("api_retry:"),
+      );
+      assert.equal(heartbeat?.type, "session.state.changed");
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  const observeUsageLimitEvents = (adapter: ClaudeAdapterShape, query: FakeClaudeQuery) =>
+    Effect.gen(function* () {
+      const runtimeEvents: Array<ProviderRuntimeEvent> = [];
+      let receipt: Deferred.Deferred<void> | undefined;
+      const runtimeEventsFiber = yield* Stream.runForEach(adapter.streamEvents, (event) =>
+        Effect.gen(function* () {
+          runtimeEvents.push(event);
+          if (
+            receipt &&
+            event.type === "session.state.changed" &&
+            event.payload.reason === "api_retry:1/1"
+          ) {
+            yield* Deferred.succeed(receipt, undefined);
+          }
+        }),
+      ).pipe(Effect.forkChild);
+      const drainSdkMessages = Effect.gen(function* () {
+        receipt = yield* Deferred.make<void>();
+        // The heartbeat follows queued SDK messages without adding a warning.
+        query.emit({
+          type: "system",
+          subtype: "api_retry",
+          attempt: 1,
+          max_retries: 1,
+          retry_delay_ms: 0,
+          error_status: 429,
+          error: { type: "rate_limit_error" },
+          session_id: "sdk-session-limit",
+          uuid: "usage-limit-drain",
+        } as unknown as SDKMessage);
+        yield* Deferred.await(receipt);
+      });
+      return { runtimeEvents, runtimeEventsFiber, drainSdkMessages };
+    });
+
+  it.effect("surfaces a rejected Claude usage limit once per turn", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const { runtimeEvents, runtimeEventsFiber, drainSdkMessages } =
+        yield* observeUsageLimitEvents(adapter, harness.query);
+
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "hello", attachments: [] });
+
+      // resetsAt is epoch seconds, so the window reopens 4h 1m30s out.
+      const nowMs = yield* Clock.currentTimeMillis;
+      const rateLimitInfo = {
+        status: "rejected",
+        rateLimitType: "five_hour",
+        utilization: 1,
+        resetsAt: Math.floor(nowMs / 1000) + 4 * 60 * 60 + 90,
+      };
+      const rejected = {
+        type: "rate_limit_event",
+        rate_limit_info: rateLimitInfo,
+        session_id: "sdk-session-limit",
+        uuid: "rate-limit-rejected",
+      };
+      // Sibling fields drift while the window is parked, so the same rendered
+      // line can arrive more than once inside one turn.
+      harness.query.emit(rejected as unknown as SDKMessage);
+      yield* drainSdkMessages;
+      // The repeat lands minutes later, so the remaining wait has visibly
+      // shrunk. Deduping on the rendered row would let that drift through.
+      yield* TestClock.adjust("5 minutes");
+      harness.query.emit(rejected as unknown as SDKMessage);
+      yield* drainSdkMessages;
+
+      const usageLimitRows = () =>
+        runtimeEvents
+          .filter((event) => event.type === "runtime.warning")
+          .map((event) => (event.type === "runtime.warning" ? event.payload.message : ""));
+      assert.equal(usageLimitRows().length, 1);
+      // A wait, not a wall clock: the server renders this row but clients read
+      // it from other timezones. Reading resetsAt as milliseconds would put the
+      // window minutes out instead of hours, so the hour also pins the scale.
+      assert.match(
+        usageLimitRows()[0] ?? "",
+        /^Claude usage limit reached\. This turn is paused until the 5-hour limit resets in 4h( \d{1,2}m)?\.$/,
+      );
+      // The exact instant still rides along for clients that want to render it.
+      assert.deepEqual(
+        runtimeEvents.find((event) => event.type === "runtime.warning")?.payload.detail,
+        rateLimitInfo,
+      );
+      // The raw telemetry event still flows for every copy.
+      assert.equal(
+        runtimeEvents.filter((event) => event.type === "account.rate-limits.updated").length,
+        2,
+      );
+
+      // Same window, drifting siblings: still the one pause.
+      harness.query.emit({
+        ...rejected,
+        rate_limit_info: { ...rateLimitInfo, utilization: 0.99 },
+        uuid: "rate-limit-rejected-drift",
+      } as unknown as SDKMessage);
+      yield* drainSdkMessages;
+      assert.equal(usageLimitRows().length, 1);
+
+      // Retrying inside the same window renders the identical line. Staying
+      // quiet there would put the new turn right back to a silent spin.
+      harness.query.emit({
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        errors: [],
+        session_id: "sdk-session-limit",
+        uuid: "result-limit",
+      } as unknown as SDKMessage);
+      yield* drainSdkMessages;
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "retry", attachments: [] });
+      harness.query.emit(rejected as unknown as SDKMessage);
+      yield* drainSdkMessages;
+
+      assert.equal(usageLimitRows().length, 2);
+
+      runtimeEventsFiber.interruptUnsafe();
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("keeps allowed and malformed Claude rate-limit events out of the work log", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const { runtimeEvents, runtimeEventsFiber, drainSdkMessages } =
+        yield* observeUsageLimitEvents(adapter, harness.query);
+
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+      // A turn is in flight, so silence here is the status filter doing its job
+      // rather than the between-turns guard.
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "hello", attachments: [] });
+
+      for (const rateLimitInfo of [
+        { status: "allowed", rateLimitType: "five_hour", utilization: 0.4 },
+        { status: "allowed_warning", rateLimitType: "five_hour", utilization: 0.9 },
+        // Undeclared shape from an older/newer CLI must not take the session down.
+        undefined,
+      ]) {
+        harness.query.emit({
+          type: "rate_limit_event",
+          ...(rateLimitInfo ? { rate_limit_info: rateLimitInfo } : {}),
+          session_id: "sdk-session-limit-ok",
+          uuid: `rate-limit-${rateLimitInfo?.status ?? "malformed"}`,
+        } as unknown as SDKMessage);
+      }
+      yield* drainSdkMessages;
+
+      assert.deepEqual(
+        runtimeEvents.filter((event) => event.type === "runtime.warning"),
+        [],
+      );
+      assert.equal(
+        runtimeEvents.filter((event) => event.type === "account.rate-limits.updated").length,
+        2,
+      );
+
+      runtimeEventsFiber.interruptUnsafe();
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("stays quiet when no turn is parked by the Claude limit", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const { runtimeEvents, runtimeEventsFiber, drainSdkMessages } =
+        yield* observeUsageLimitEvents(adapter, harness.query);
+
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+
+      const nowMs = yield* Clock.currentTimeMillis;
+      const resetsAt = Math.floor(nowMs / 1000) + 60 * 60;
+      // The stream stays live between turns, so a reject can land with nothing
+      // to pause; claiming "this turn is paused" there would be a lie.
+      harness.query.emit({
+        type: "rate_limit_event",
+        rate_limit_info: {
+          status: "rejected",
+          rateLimitType: "five_hour",
+          utilization: 1,
+          resetsAt,
+        },
+        session_id: "sdk-session-idle",
+        uuid: "rate-limit-idle",
+      } as unknown as SDKMessage);
+      yield* drainSdkMessages;
+
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "hello", attachments: [] });
+      // Provisioned overage carries the request even though the base window
+      // rejected it, so the turn keeps running and needs no row.
+      for (const overage of [
+        { overageStatus: "allowed" },
+        { overageStatus: "allowed_warning" },
+        { isUsingOverage: true },
+        { overageInUse: true },
+      ]) {
+        harness.query.emit({
+          type: "rate_limit_event",
+          rate_limit_info: {
+            status: "rejected",
+            rateLimitType: "five_hour",
+            resetsAt,
+            utilization: 1,
+            ...overage,
+          },
+          session_id: "sdk-session-idle",
+          uuid: "rate-limit-overage",
+        } as unknown as SDKMessage);
+      }
+      yield* drainSdkMessages;
+
+      assert.deepEqual(
+        runtimeEvents.filter((event) => event.type === "runtime.warning"),
+        [],
+      );
+      // Idle and overage-covered events still reach the account telemetry stream.
+      assert.equal(
+        runtimeEvents.filter((event) => event.type === "account.rate-limits.updated").length,
+        5,
+      );
+
+      runtimeEventsFiber.interruptUnsafe();
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("still surfaces the pause when overage is exhausted too", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const { runtimeEvents, runtimeEventsFiber, drainSdkMessages } =
+        yield* observeUsageLimitEvents(adapter, harness.query);
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
         provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "hello", attachments: [] });
 
-      yield* adapter.stopSession(THREAD_ID);
+      const nowMs = yield* Clock.currentTimeMillis;
+      const resetsAt = Math.floor(nowMs / 1000) + 60 * 60;
+      // The overage-exhausted / out-of-credits shape: the base window and the
+      // overage it would have spent both reject, with neither isUsingOverage
+      // nor overageInUse set to say anything is still covered. Nothing is
+      // carrying the turn here, so staying quiet would be the silent spin
+      // this row exists to prevent.
+      harness.query.emit({
+        type: "rate_limit_event",
+        rate_limit_info: {
+          status: "rejected",
+          rateLimitType: "five_hour",
+          resetsAt,
+          overageStatus: "rejected",
+        },
+        session_id: "sdk-session-dual-reject",
+        uuid: "rate-limit-dual-reject",
+      } as unknown as SDKMessage);
+      yield* drainSdkMessages;
 
-      yield* Effect.yieldNow;
-      yield* Effect.yieldNow;
-      yield* Effect.yieldNow;
-      yield* TestClock.adjust("50 millis");
-      yield* Effect.yieldNow;
+      assert.equal(runtimeEvents.filter((event) => event.type === "runtime.warning").length, 1);
 
       runtimeEventsFiber.interruptUnsafe();
-
-      assert.equal(
-        promptConsumerError,
-        undefined,
-        `Prompt consumer should not receive a thrown error on session stop, ` +
-          `but got: "${promptConsumerError instanceof Error ? promptConsumerError.message : String(promptConsumerError)}"`,
-      );
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
-      Effect.provide(layer),
+      Effect.provide(harness.layer),
     );
   });
 
-  it.effect("forwards Claude task progress summaries for subagent updates", () => {
+  it.effect("keeps one row per window when two Claude limits interleave", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
+      const { runtimeEvents, runtimeEventsFiber, drainSdkMessages } =
+        yield* observeUsageLimitEvents(adapter, harness.query);
 
-      const runtimeEventsFiber = yield* Stream.take(adapter.streamEvents, 6).pipe(
-        Stream.runCollect,
-        Effect.forkChild,
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "hello", attachments: [] });
+
+      const nowMs = yield* Clock.currentTimeMillis;
+      const nowSeconds = Math.floor(nowMs / 1000);
+      const rejection = (rateLimitType: string, resetsAt: number, uuid: string) => ({
+        type: "rate_limit_event",
+        rate_limit_info: { status: "rejected", rateLimitType, resetsAt },
+        session_id: "sdk-session-interleaved",
+        uuid,
+      });
+
+      // One turn can park on more than one window; each deserves its own row,
+      // and a later repeat of an earlier window deserves none.
+      for (const message of [
+        rejection("five_hour", nowSeconds + 2 * 60 * 60, "limit-five-hour"),
+        rejection("seven_day", nowSeconds + 48 * 60 * 60, "limit-seven-day"),
+        rejection("five_hour", nowSeconds + 2 * 60 * 60, "limit-five-hour-repeat"),
+      ]) {
+        harness.query.emit(message as unknown as SDKMessage);
+        yield* drainSdkMessages;
+      }
+
+      assert.deepEqual(
+        runtimeEvents
+          .filter((event) => event.type === "runtime.warning")
+          .map((event) => (event.type === "runtime.warning" ? event.payload.message : ""))
+          .map((message) => message.replace(/ in \d+h( \d{1,2}m)?/, "")),
+        [
+          "Claude usage limit reached. This turn is paused until the 5-hour limit resets.",
+          "Claude usage limit reached. This turn is paused until the 7-day limit resets.",
+        ],
       );
 
+      runtimeEventsFiber.interruptUnsafe();
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("re-announces a Claude limit for a synthetic turn", () => {
+    const harness = makeHarness();
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const { runtimeEvents, runtimeEventsFiber, drainSdkMessages } =
+        yield* observeUsageLimitEvents(adapter, harness.query);
+
       yield* adapter.startSession({
         threadId: THREAD_ID,
         provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "hello", attachments: [] });
+
+      const nowMs = yield* Clock.currentTimeMillis;
+      const rejected = {
+        type: "rate_limit_event",
+        rate_limit_info: {
+          status: "rejected",
+          rateLimitType: "five_hour",
+          resetsAt: Math.floor(nowMs / 1000) + 2 * 60 * 60,
+        },
+        session_id: "sdk-session-synthetic",
+        uuid: "rate-limit-synthetic",
+      };
+      harness.query.emit(rejected as unknown as SDKMessage);
+      yield* drainSdkMessages;
 
       harness.query.emit({
-        type: "system",
-        subtype: "task_progress",
-        task_id: "task-subagent-1",
-        description: "Running background teammate",
-        summary: "Code reviewer checked the migration edge cases.",
-        usage: {
-          total_tokens: 123,
-          tool_uses: 4,
-          duration_ms: 987,
+        type: "result",
+        subtype: "success",
+        is_error: false,
+        errors: [],
+        session_id: "sdk-session-synthetic",
+        uuid: "result-synthetic",
+      } as unknown as SDKMessage);
+      yield* drainSdkMessages;
+
+      // A background agent answering between prompts auto-starts a synthetic
+      // turn, which parks on the same window and needs its own row.
+      harness.query.emit({
+        type: "assistant",
+        session_id: "sdk-session-synthetic",
+        uuid: "assistant-synthetic",
+        parent_tool_use_id: null,
+        message: {
+          id: "assistant-message-synthetic",
+          content: [{ type: "text", text: "Following up" }],
         },
-        session_id: "sdk-session-task-summary",
-        uuid: "task-progress-1",
       } as unknown as SDKMessage);
+      yield* drainSdkMessages;
+      harness.query.emit({ ...rejected, uuid: "rate-limit-synthetic-2" } as unknown as SDKMessage);
+      yield* drainSdkMessages;
 
-      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
-      const progressEvent = runtimeEvents.find((event) => event.type === "task.progress");
-      assert.equal(progressEvent?.type, "task.progress");
-      if (progressEvent?.type === "task.progress") {
-        assert.equal(
-          progressEvent.payload.summary,
-          "Code reviewer checked the migration edge cases.",
-        );
-        assert.equal(progressEvent.payload.description, "Running background teammate");
-      }
+      assert.equal(runtimeEvents.filter((event) => event.type === "runtime.warning").length, 2);
+
+      runtimeEventsFiber.interruptUnsafe();
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
       Effect.provide(harness.layer),
     );
   });
 
-  it.effect("consumes undeclared and UX-internal system subtypes without warning rows", () => {
+  it.effect("drops an unusable Claude reset time, not the row or the session", () => {
     const harness = makeHarness();
     return Effect.gen(function* () {
       const adapter = yield* ClaudeAdapter;
-      const runtimeEvents: Array<ProviderRuntimeEvent> = [];
-      const runtimeEventsFiber = yield* Stream.runForEach(adapter.streamEvents, (event) =>
-        Effect.sync(() => runtimeEvents.push(event)),
-      ).pipe(Effect.forkChild);
+      const { runtimeEvents, runtimeEventsFiber, drainSdkMessages } =
+        yield* observeUsageLimitEvents(adapter, harness.query);
 
       yield* adapter.startSession({
         threadId: THREAD_ID,
         provider: ProviderDriverKind.make("claudeAgent"),
         runtimeMode: "full-access",
       });
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "hello", attachments: [] });
 
-      // Undeclared wire-only roster snapshot + every typed UX-internal
-      // subtype and top-level type consumed silently: none may surface as
-      // unknown-subtype warnings.
-      for (const message of [
-        {
-          type: "system",
-          subtype: "background_tasks_changed",
-          tasks: [{ task_id: "t1", task_type: "local_agent", description: "Say hi" }],
-          session_id: "session",
-          uuid: "roster",
-        },
-        {
-          type: "system",
-          subtype: "vcs_state_changed",
-          kind: "push",
-          cwd: "/tmp/worktree",
-          session_id: "session",
-          uuid: "vcs",
-        },
-        {
-          type: "system",
-          subtype: "code_change_published",
-          provider: "github",
-          url: "https://github.com/pingdotgg/t3code/pull/1",
-          repo: "pingdotgg/t3code",
-          identifier: "1",
-          session_id: "session",
-          uuid: "ccp",
-        },
-        {
-          type: "system",
-          subtype: "task_updated",
-          task_id: "t1",
-          patch: { status: "running" },
-          session_id: "session",
-          uuid: "tu",
-        },
-        { type: "system", subtype: "commands_changed", session_id: "session", uuid: "cc" },
-        { type: "system", subtype: "model_refusal_fallback", session_id: "session", uuid: "mrf" },
-        { type: "system", subtype: "local_command_output", session_id: "session", uuid: "lco" },
-        { type: "system", subtype: "plugin_install", session_id: "session", uuid: "pi" },
-        { type: "system", subtype: "memory_recall", session_id: "session", uuid: "mr" },
-        { type: "system", subtype: "elicitation_complete", session_id: "session", uuid: "ec" },
-        { type: "prompt_suggestion", suggestion: "try this", session_id: "session", uuid: "ps" },
-        {
-          type: "system",
-          subtype: "notification",
-          key: "context",
-          text: "low priority note",
-          priority: "low",
-          session_id: "session",
-          uuid: "notif",
-        },
-      ]) {
-        harness.query.emit(message as unknown as SDKMessage);
+      for (const [rateLimitType, resetsAt] of [
+        ["five_hour", undefined],
+        // Implausibly far out once scaled to milliseconds: no credible wait.
+        ["seven_day", 1e20],
+      ] as const) {
+        harness.query.emit({
+          type: "rate_limit_event",
+          rate_limit_info: { status: "rejected", rateLimitType, resetsAt },
+          session_id: "sdk-session-limit-unusable",
+          uuid: `rate-limit-${rateLimitType}`,
+        } as unknown as SDKMessage);
       }
-      // High-priority notifications DO surface as a warning row.
-      harness.query.emit({
-        type: "system",
-        subtype: "notification",
-        key: "limit",
-        text: "context window nearly full",
-        priority: "high",
-        session_id: "session",
-        uuid: "notif-high",
-      } as unknown as SDKMessage);
-      // session_state_changed maps to the matching session states.
-      for (const [state, uuid] of [
-        ["running", "ssc-run"],
-        ["requires_action", "ssc-req"],
-        ["idle", "ssc-idle"],
-      ]) {
+      yield* drainSdkMessages;
+
+      assert.deepEqual(
+        runtimeEvents
+          .filter((event) => event.type === "runtime.warning")
+          .map((event) => (event.type === "runtime.warning" ? event.payload.message : "")),
+        [
+          "Claude usage limit reached. This turn is paused until the 5-hour limit resets.",
+          "Claude usage limit reached. This turn is paused until the 7-day limit resets.",
+        ],
+      );
+      // A throw inside the telemetry handler would tear the session down.
+      assert.deepEqual(
+        runtimeEvents
+          .filter((event) => event.type === "session.exited" || event.type === "runtime.error")
+          .map((event) => event.type),
+        [],
+      );
+      // Still live enough to take the next turn.
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "still here", attachments: [] });
+
+      runtimeEventsFiber.interruptUnsafe();
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  it.effect("warns for unmapped Claude limits and names the probed model bucket", () => {
+    const scopedLimitNames = Ref.makeUnsafe<ClaudeScopedLimitNames>({ overageIncluded: undefined });
+    const harness = makeHarness({ scopedLimitNames });
+    return Effect.gen(function* () {
+      const adapter = yield* ClaudeAdapter;
+      const { runtimeEvents, runtimeEventsFiber, drainSdkMessages } =
+        yield* observeUsageLimitEvents(adapter, harness.query);
+      yield* adapter.startSession({
+        threadId: THREAD_ID,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        runtimeMode: "full-access",
+      });
+      yield* adapter.sendTurn({ threadId: THREAD_ID, input: "hello", attachments: [] });
+
+      for (const rateLimitType of ["seven_day_overage_included", "future_window"]) {
         harness.query.emit({
-          type: "system",
-          subtype: "session_state_changed",
-          state,
-          session_id: "session",
-          uuid,
+          type: "rate_limit_event",
+          rate_limit_info: { status: "rejected", rateLimitType },
+          session_id: "sdk-session-unmapped-limit",
+          uuid: `rejected-${rateLimitType}`,
         } as unknown as SDKMessage);
       }
-      // api_retry maps to a session heartbeat, not a warning row.
+      yield* drainSdkMessages;
+      assert.deepEqual(
+        runtimeEvents.filter((event) => event.type === "account.rate-limits.updated"),
+        [],
+      );
+
+      yield* Ref.set(scopedLimitNames, { overageIncluded: "Model A" });
+      const nowMs = yield* Clock.currentTimeMillis;
       harness.query.emit({
-        type: "system",
-        subtype: "api_retry",
-        attempt: 3,
-        max_retries: 10,
-        retry_delay_ms: 1000,
-        error_status: 502,
-        error: { type: "api_error" },
-        session_id: "session",
-        uuid: "retry",
+        type: "rate_limit_event",
+        rate_limit_info: {
+          status: "rejected",
+          rateLimitType: "seven_day_overage_included",
+          utilization: 1,
+          resetsAt: Math.floor(nowMs / 1000) + 3600,
+        },
+        session_id: "sdk-session-unmapped-limit",
+        uuid: "rejected-probed-bucket",
       } as unknown as SDKMessage);
-      yield* Effect.yieldNow;
-      yield* Effect.yieldNow;
-
-      const warnings = runtimeEvents.filter((event) => event.type === "runtime.warning");
-      // Exactly one warning: the high-priority notification. Nothing else.
+      yield* drainSdkMessages;
       assert.deepEqual(
-        warnings.map((event) => event.payload.message),
-        ["context window nearly full"],
+        runtimeEvents
+          .filter((event) => event.type === "runtime.warning")
+          .map((event) => event.payload.message),
+        [
+          "Claude usage limit reached. This turn is paused until the 7-day model limit resets.",
+          "Claude usage limit reached. This turn is paused until the limit resets.",
+          "Claude usage limit reached. This turn is paused until the 7-day Model A limit resets in 1h.",
+        ],
       );
-      const sessionStates = runtimeEvents
-        .filter((event) => event.type === "session.state.changed")
-        .map((event) =>
-          event.type === "session.state.changed"
-            ? `${event.payload.state}:${event.payload.reason ?? ""}`
-            : "",
-        )
-        .filter(
-          (entry) => entry.startsWith("running:session_state") || entry.includes("session_state"),
-        );
-      assert.deepEqual(sessionStates, [
-        "running:session_state:running",
-        "waiting:session_state:requires_action",
-        "ready:session_state:idle",
-      ]);
-      const heartbeat = runtimeEvents.find(
-        (event) =>
-          event.type === "session.state.changed" &&
-          typeof event.payload.reason === "string" &&
-          event.payload.reason.startsWith("api_retry:"),
+      assert.equal(
+        runtimeEvents.filter((event) => event.type === "account.rate-limits.updated").length,
+        1,
       );
-      assert.equal(heartbeat?.type, "session.state.changed");
       runtimeEventsFiber.interruptUnsafe();
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
@@ -4190,6 +5201,7 @@ describe("ClaudeAdapterLive", () => {
         { command: "pwd" },
         {
           signal: new AbortController().signal,
+          requestId: "request-1",
           suggestions: [
             {
               type: "setMode",
@@ -4301,6 +5313,7 @@ describe("ClaudeAdapterLive", () => {
         { title: "hello" },
         {
           signal: new AbortController().signal,
+          requestId: "request-2",
           suggestions: [],
           toolUseID: "tool-use-mcp-1",
         },
@@ -4327,6 +5340,7 @@ describe("ClaudeAdapterLive", () => {
         { command: "git status" },
         {
           signal: new AbortController().signal,
+          requestId: "request-3",
           suggestions: [
             {
               type: "addRules",
@@ -4385,6 +5399,7 @@ describe("ClaudeAdapterLive", () => {
         {},
         {
           signal: new AbortController().signal,
+          requestId: "request-4",
           toolUseID: "tool-agent-1",
         },
       );
@@ -4409,6 +5424,7 @@ describe("ClaudeAdapterLive", () => {
         { pattern: "foo", path: "src" },
         {
           signal: new AbortController().signal,
+          requestId: "request-5",
           toolUseID: "tool-grep-approval-1",
         },
       );
@@ -4951,6 +5967,7 @@ describe("ClaudeAdapterLive", () => {
         },
         {
           signal: new AbortController().signal,
+          requestId: "request-6",
           toolUseID: "tool-exit-1",
         },
       );
@@ -5073,7 +6090,7 @@ describe("ClaudeAdapterLive", () => {
           dialogKind: "resume_return",
           payload: { sessionAgeMinutes: 145, estimatedTokens: 275123 },
         },
-        { signal: new AbortController().signal },
+        { signal: new AbortController().signal, requestId: "request-dialog" },
       );
 
       const requested = yield* Stream.runHead(adapter.streamEvents);
@@ -5173,6 +6190,7 @@ describe("ClaudeAdapterLive", () => {
 
       const permissionPromise = canUseTool("AskUserQuestion", askInput, {
         signal: new AbortController().signal,
+        requestId: "request-7",
         toolUseID: "tool-ask-1",
       });
 
@@ -5299,6 +6317,7 @@ describe("ClaudeAdapterLive", () => {
 
       const permissionPromise = canUseTool("AskUserQuestion", askInput, {
         signal: new AbortController().signal,
+        requestId: "request-8",
         toolUseID: "tool-ask-2",
       });
 
@@ -5364,6 +6383,7 @@ describe("ClaudeAdapterLive", () => {
         },
         {
           signal: controller.signal,
+          requestId: "request-9",
           toolUseID: "tool-ask-abort",
         },
       );
@@ -5439,6 +6459,7 @@ describe("ClaudeAdapterLive", () => {
         },
         {
           signal: controller.signal,
+          requestId: "request-10",
           toolUseID: "tool-ask-pre-aborted",
         },
       );
@@ -5495,7 +6516,11 @@ describe("ClaudeAdapterLive", () => {
             },
           ],
         },
-        { signal: new AbortController().signal, toolUseID: "tool-ask-stop" },
+        {
+          signal: new AbortController().signal,
+          requestId: "request-stop",
+          toolUseID: "tool-ask-stop",
+        },
       );
 
       const requestedEvent = yield* Stream.runHead(adapter.streamEvents);
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.ts b/apps/server/src/provider/Layers/ClaudeAdapter.ts
index 5848bcc457de..a005f583066f 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.ts
@@ -14,6 +14,7 @@ import {
   type PermissionResult,
   type PermissionUpdate,
   type SDKMessage,
+  type SDKRateLimitInfo,
   type SDKResultMessage,
   type SettingSource,
   type SDKUserMessage,
@@ -24,6 +25,7 @@ import { isWorkspaceImagePreviewPath } from "@t3tools/shared/filePreview";
 import { type ClaudeScopedLimitNames, claudeRateLimitEventToUpdate } from "./claudeUsageLimits.ts";
 import {
   ApprovalRequestId,
+  classifyTaskAgentKind,
   type CanonicalItemType,
   type CanonicalRequestType,
   type ClaudeSettings,
@@ -38,6 +40,7 @@ import {
   type ProviderSendTurnInput,
   type ProviderSession,
   type ThreadTokenUsageSnapshot,
+  type TurnTokenUsage,
   type ProviderUserInputAnswers,
   type RuntimeContentStreamKind,
   RuntimeItemId,
@@ -154,6 +157,7 @@ interface ClaudeTurnState {
   readonly capturedProposedPlanKeys: Set<string>;
   latestAssistantUsage: unknown | undefined;
   compactedSinceLatestAssistantUsage: boolean;
+  hasSubagents: boolean;
   nextSyntheticAssistantBlockIndex: number;
 }
 
@@ -324,6 +328,8 @@ interface ClaudeSessionContext {
   lastKnownTotalProcessedTokens: number | undefined;
   lastAssistantUuid: string | undefined;
   lastThreadStartedId: string | undefined;
+  /** Limits already announced for the running turn, keyed `window:resetsAt`. */
+  announcedUsageLimits: { turnId: string; keys: Set<string> } | undefined;
   stopped: boolean;
 }
 
@@ -434,10 +440,45 @@ function resultErrorsText(result: SDKResultMessage): string {
  * so they must never become the error banner.
  */
 function resultUserFacingError(result: SDKResultMessage): string | undefined {
-  if (result.subtype === "success" || !Array.isArray(result.errors)) {
-    return undefined;
+  const listed =
+    result.subtype === "success" || !Array.isArray(result.errors)
+      ? undefined
+      : result.errors.find((error) => !error.startsWith("[ede_diagnostic]"));
+  if (listed) {
+    return listed;
+  }
+  // Structured failure markers for results whose error list is empty or
+  // diagnostic-only: an overloaded API (529) and the terminal reasons the
+  // CLI stamps when it gives up on a turn.
+  if (isOverloadedResult(result)) {
+    return "Claude API is overloaded (529). Try again shortly.";
+  }
+  switch (result.terminal_reason) {
+    case "api_error":
+      return "Claude gave up after repeated API errors.";
+    case "malformed_tool_use_exhausted":
+      return "Claude gave up after repeated malformed tool calls.";
+    case "budget_exhausted":
+      return "Claude stopped: the turn's token budget was exhausted.";
+    case "structured_output_retry_exhausted":
+      return "Claude could not produce the requested structured output.";
+    case "tool_deferred_unavailable":
+      return "Claude could not resume a deferred tool call: the tool is no longer available.";
+    case "turn_setup_failed":
+      return "Claude could not start the turn.";
+    case "blocking_limit":
+      return "Claude stopped: a usage limit blocked the request.";
+    case "rapid_refill_breaker":
+      return "Claude stopped: the context refilled too quickly after compaction.";
+    case "prompt_too_long":
+      return "Claude stopped: the prompt exceeds the model's context window.";
+    case "image_error":
+      return "Claude stopped: an image in the conversation could not be processed.";
+    case "model_error":
+      return "Claude stopped: the model returned an error.";
+    default:
+      return undefined;
   }
-  return result.errors.find((error) => !error.startsWith("[ede_diagnostic]"));
 }
 
 function isInterruptedResult(result: SDKResultMessage): boolean {
@@ -465,6 +506,55 @@ function isInterruptedResult(result: SDKResultMessage): boolean {
   );
 }
 
+const CLAUDE_USAGE_LIMIT_WINDOWS = {
+  five_hour: "5-hour",
+  seven_day: "7-day",
+  seven_day_opus: "7-day Opus",
+  seven_day_sonnet: "7-day Sonnet",
+  seven_day_overage_included: "7-day model",
+  overage: "overage",
+} satisfies Record<NonNullable<SDKRateLimitInfo["rateLimitType"]>, string>;
+
+/** Beyond this the reset time is not credible, so the row ships without a wait. */
+const CLAUDE_USAGE_LIMIT_MAX_WAIT_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * `resetsAt` is epoch seconds. The row states the remaining wait rather than a
+ * wall-clock time: this renders on the server, while the row is read on clients
+ * that may sit in another timezone and locale, and that carry their own
+ * timestamp preference. A wait reads the same everywhere.
+ */
+function describeClaudeUsageLimit(
+  info: SDKRateLimitInfo,
+  nowMs: number,
+  names: ClaudeScopedLimitNames,
+): string {
+  const label =
+    info.rateLimitType === "seven_day_overage_included" && names.overageIncluded
+      ? `7-day ${names.overageIncluded}`
+      : info.rateLimitType
+        ? CLAUDE_USAGE_LIMIT_WINDOWS[info.rateLimitType]
+        : undefined;
+  const resetsAtMs = info.resetsAt === undefined ? undefined : info.resetsAt * 1000;
+  const waitMs =
+    resetsAtMs === undefined || !Number.isFinite(nowMs) ? undefined : resetsAtMs - nowMs;
+  const wait =
+    waitMs !== undefined && waitMs > 0 && waitMs <= CLAUDE_USAGE_LIMIT_MAX_WAIT_MS
+      ? formatClaudeUsageLimitWait(waitMs)
+      : undefined;
+  return `Claude usage limit reached. This turn is paused until the ${
+    label ? `${label} ` : ""
+  }limit resets${wait ? ` in ${wait}` : ""}.`;
+}
+
+function formatClaudeUsageLimitWait(waitMs: number): string {
+  const totalMinutes = Math.ceil(waitMs / 60_000);
+  const hours = Math.floor(totalMinutes / 60);
+  const minutes = totalMinutes % 60;
+  if (hours === 0) return `${totalMinutes}m`;
+  return minutes === 0 ? `${hours}h` : `${hours}h ${minutes}m`;
+}
+
 function asRuntimeItemId(value: string): RuntimeItemId {
   return RuntimeItemId.make(value);
 }
@@ -608,6 +698,85 @@ function normalizeClaudeActiveTokenUsage(
   });
 }
 
+function normalizeClaudeTurnTokenUsage(
+  result: SDKResultMessage | undefined,
+  hasSubagents: boolean,
+  terminalStatus: ProviderRuntimeTurnStatus,
+): TurnTokenUsage {
+  const usage = result?.usage as Record<string, unknown> | undefined;
+  if (!usage) {
+    return {
+      usageStatus: "unavailable",
+      usageScope: "main_agent",
+      hasSubagents,
+    };
+  }
+
+  const uncachedInputTokens = finiteNonNegativeInteger(usage.input_tokens);
+  const cachedInputTokens = finiteNonNegativeInteger(usage.cache_read_input_tokens);
+  const cacheCreationTokens = finiteNonNegativeInteger(usage.cache_creation_input_tokens);
+  const rawOutputTokens = finiteNonNegativeInteger(usage.output_tokens);
+  const outputDetails = usage.output_tokens_details as Record<string, unknown> | undefined;
+  const thinkingTokens = finiteNonNegativeInteger(outputDetails?.thinking_tokens);
+  const cachedInputContribution = usage.cache_read_input_tokens == null ? 0 : cachedInputTokens;
+  const cacheCreationContribution =
+    usage.cache_creation_input_tokens == null ? 0 : cacheCreationTokens;
+  const inputTokens =
+    uncachedInputTokens !== undefined &&
+    cachedInputContribution !== undefined &&
+    cacheCreationContribution !== undefined
+      ? uncachedInputTokens + cachedInputContribution + cacheCreationContribution
+      : undefined;
+  const hasKnownUsage =
+    uncachedInputTokens !== undefined ||
+    cachedInputTokens !== undefined ||
+    cacheCreationTokens !== undefined ||
+    rawOutputTokens !== undefined;
+  const hasPositiveUsage =
+    (uncachedInputTokens ?? 0) +
+      (cachedInputTokens ?? 0) +
+      (cacheCreationTokens ?? 0) +
+      (rawOutputTokens ?? 0) >
+    0;
+
+  if (!hasKnownUsage || (result?.subtype !== "success" && !hasPositiveUsage)) {
+    return {
+      usageStatus: "unavailable",
+      usageScope: "main_agent",
+      hasSubagents,
+    };
+  }
+
+  const commonUsage = {
+    usageScope: "main_agent",
+    ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+    ...(cacheCreationTokens !== undefined ? { cacheCreationTokens } : {}),
+    ...(thinkingTokens !== undefined && rawOutputTokens !== undefined
+      ? { reasoningTokens: Math.min(rawOutputTokens, thinkingTokens) }
+      : {}),
+    hasSubagents,
+  } as const;
+  if (
+    terminalStatus === "completed" &&
+    result?.subtype === "success" &&
+    inputTokens !== undefined &&
+    rawOutputTokens !== undefined
+  ) {
+    return {
+      ...commonUsage,
+      usageStatus: "complete",
+      inputTokens,
+      outputTokens: rawOutputTokens,
+    };
+  }
+  return {
+    ...commonUsage,
+    usageStatus: "partial",
+    ...(inputTokens !== undefined ? { inputTokens } : {}),
+    ...(rawOutputTokens !== undefined ? { outputTokens: rawOutputTokens } : {}),
+  };
+}
+
 function compactBoundaryTokenUsageSnapshot(
   message: Record<string, unknown>,
   contextWindow?: number,
@@ -1390,7 +1559,43 @@ const buildUserMessageEffect = Effect.fn("buildUserMessageEffect")(function* (
   return buildUserMessage({ sdkContent });
 });
 
+/**
+ * terminal_reason values the CLI classifies as dead turns: the turn died
+ * rather than finished, even when the result subtype is success and the
+ * error list is empty. Kept in sync with the messages in
+ * resultUserFacingError.
+ */
+const FAILED_TERMINAL_REASONS: ReadonlySet<NonNullable<SDKResultMessage["terminal_reason"]>> =
+  new Set([
+    "api_error",
+    "malformed_tool_use_exhausted",
+    "budget_exhausted",
+    "structured_output_retry_exhausted",
+    "tool_deferred_unavailable",
+    "turn_setup_failed",
+    "blocking_limit",
+    "rapid_refill_breaker",
+    "prompt_too_long",
+    "image_error",
+    "model_error",
+  ]);
+
+/**
+ * The CLI reports repeated 529 overload failures as a success-subtype result
+ * with api_error_status 529 and an empty error list; the status code is the
+ * only structured failure signal.
+ */
+function isOverloadedResult(result: SDKResultMessage): boolean {
+  return result.subtype === "success" && result.api_error_status === 529;
+}
+
 function turnStatusFromResult(result: SDKResultMessage): ProviderRuntimeTurnStatus {
+  if (
+    isOverloadedResult(result) ||
+    (result.terminal_reason !== undefined && FAILED_TERMINAL_REASONS.has(result.terminal_reason))
+  ) {
+    return "failed";
+  }
   if (result.subtype === "success") {
     return "completed";
   }
@@ -2432,6 +2637,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           ? { totalCostUsd: result.total_cost_usd }
           : {}),
         ...(errorMessage ? { errorMessage } : {}),
+        tokenUsage: normalizeClaudeTurnTokenUsage(result, turnState.hasSubagents, status),
       },
       providerRefs: nativeProviderRefs(context),
     });
@@ -2976,6 +3182,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         capturedProposedPlanKeys: new Set(),
         latestAssistantUsage: undefined,
         compactedSinceLatestAssistantUsage: false,
+        hasSubagents: false,
         nextSyntheticAssistantBlockIndex: -1,
       };
       context.session = {
@@ -3174,15 +3381,11 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     // Undeclared-but-real subtypes (absent from the SDK's union, so they can't
     // be switch cases): consumed intentionally without emitting, otherwise
     // they fall through to the unknown-subtype warning and surface as spurious
-    // error rows in client work logs. `background_tasks_changed` is a roster
-    // snapshot ({tasks: [...]}) — the task_* lifecycle events carry the
-    // authoritative per-agent data and the typed background_tasks control
-    // request is the reconciliation source. `vcs_state_changed`
+    // error rows in client work logs. `vcs_state_changed`
     // ({kind: commit|push|rebase}) and `code_change_published`
     // ({provider, url, repo}) are informational CLI notices; the work log
     // already shows the underlying git/gh tool calls.
     switch (message.subtype as string) {
-      case "background_tasks_changed":
       case "vcs_state_changed":
       case "code_change_published":
         return;
@@ -3286,6 +3489,15 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
             )
           : undefined;
         const owningAgentId = launchingTool?.agentId;
+        if (
+          context.turnState &&
+          classifyTaskAgentKind({
+            taskType: message.task_type,
+            ...(owningAgentId ? { agentId: owningAgentId } : {}),
+          }) === "agent"
+        ) {
+          context.turnState.hasSubagents = true;
+        }
         // Model/effort: the Agent tool's input carries explicit overrides;
         // absent ones inherit the session's selection (SDK behavior).
         // Subagent assistant snapshots refine model with the authoritative API
@@ -3495,14 +3707,48 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
           yield* emitRuntimeWarning(context, message.text, message);
         }
         return;
+      case "model_refusal_fallback":
+        // A safety fallback switched the model mid-session (e.g. Fable 5
+        // retried on Opus 4.8 after a flagged request). The CLI ships the
+        // user-facing notice in `content`; surface it like high-priority
+        // notifications so the rest of the session isn't silently served
+        // by a different model.
+        yield* emitRuntimeWarning(context, message.content, message);
+        return;
       // Inner protocol/UX details with no T3 surface today — consumed
       // deliberately so they don't masquerade as unknown-subtype warnings.
-      case "model_refusal_fallback":
+      // `background_tasks_changed` is a roster snapshot ({tasks: [...]}); the
+      // task_* lifecycle events carry the authoritative per-agent data and
+      // the typed background_tasks control request is the reconciliation
+      // source. `control_request_progress` is a liveness heartbeat for an
+      // in-flight control request. `worker_shutting_down` is a Remote
+      // Control worker notice; the session close path reports the outcome.
       case "local_command_output":
       case "plugin_install":
       case "commands_changed":
       case "memory_recall":
       case "elicitation_complete":
+      case "background_tasks_changed":
+      case "control_request_progress":
+      case "worker_shutting_down":
+        return;
+      case "informational":
+        // Transcript-level CLI notes. Only warnings (e.g. a Stop hook that
+        // refused continuation) warrant a work-log row; info/notice/
+        // suggestion levels are CLI chrome.
+        if (message.level === "warning") {
+          yield* emitRuntimeWarning(context, message.content, message);
+        }
+        return;
+      case "model_refusal_no_fallback":
+        // The API refused the request and no fallback model was available.
+        // The terminal result reports the failed turn; this row carries the
+        // refusal explanation the result's error list lacks.
+        yield* emitRuntimeWarning(
+          context,
+          message.api_refusal_explanation?.trim() || message.content,
+          message,
+        );
         return;
       case "permission_denied":
         yield* offerRuntimeEvent({
@@ -3528,7 +3774,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         // handled above, so `message` narrows to never here — a new SDK
         // release adding a subtype fails this typecheck instead of silently
         // warning at runtime. The runtime fallback still catches undeclared
-        // wire-only subtypes (like background_tasks_changed used to be).
+        // wire-only subtypes (like vcs_state_changed).
         message satisfies never;
         const unknownMessage = message as never as { subtype: string };
         yield* emitRuntimeWarning(
@@ -3608,16 +3854,52 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
     }
 
     if (message.type === "rate_limit_event") {
+      const rateLimitInfo = message.rate_limit_info;
+      if (!rateLimitInfo) return;
       const names = options?.scopedLimitNames
         ? yield* Ref.get(options.scopedLimitNames)
         : { overageIncluded: undefined };
-      const limits = claudeRateLimitEventToUpdate(message.rate_limit_info, names);
-      if (!limits) return;
-      yield* offerRuntimeEvent({
-        ...base,
-        type: "account.rate-limits.updated",
-        payload: { limits },
-      });
+      const limits = claudeRateLimitEventToUpdate(rateLimitInfo, names);
+      if (limits) {
+        yield* offerRuntimeEvent({
+          ...base,
+          type: "account.rate-limits.updated",
+          payload: { limits },
+        });
+      }
+      // A rejected window parks the turn inside the SDK: no further messages
+      // arrive and no result lands, so without a row the thread just spins.
+      // Warnings (allowed_warning) still have headroom and stay quiet, an
+      // account spending provisioned overage keeps running despite the reject,
+      // and between turns there is no turn to report as paused.
+      if (
+        rateLimitInfo.status === "rejected" &&
+        rateLimitInfo.overageStatus !== "allowed" &&
+        rateLimitInfo.overageStatus !== "allowed_warning" &&
+        rateLimitInfo.isUsingOverage !== true &&
+        rateLimitInfo.overageInUse !== true &&
+        context.turnState !== undefined
+      ) {
+        // Tracked per turn as a set of limit identities, not as the rendered
+        // row: a parked window re-fires while the remaining wait shrinks, and a
+        // turn can park on more than one window, so a single slot would let an
+        // interleaved repeat through. A new turn — including a synthetic one —
+        // starts a fresh set and announces its pause again.
+        const turnId = context.turnState.turnId;
+        if (context.announcedUsageLimits?.turnId !== turnId) {
+          context.announcedUsageLimits = { turnId, keys: new Set() };
+        }
+        const limitKey = `${rateLimitInfo.rateLimitType ?? "unknown"}:${rateLimitInfo.resetsAt ?? "unknown"}`;
+        if (!context.announcedUsageLimits.keys.has(limitKey)) {
+          context.announcedUsageLimits.keys.add(limitKey);
+          const notice = describeClaudeUsageLimit(
+            rateLimitInfo,
+            Date.parse(stamp.createdAt),
+            names,
+          );
+          yield* emitRuntimeWarning(context, notice, rateLimitInfo);
+        }
+      }
       return;
     }
   });
@@ -3657,7 +3939,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         yield* handleSdkTelemetryMessage(context, message);
         return;
       // Composer prompt suggestions have no T3 surface; consumed deliberately.
+      // `conversation_reset` announces a CLI-side conversation id swap
+      // (e.g. /clear); T3 keeps its own thread identity and resume cursor.
       case "prompt_suggestion":
+      case "conversation_reset":
         return;
       default: {
         // Exhaustiveness guard (see handleSystemMessage): new SDK top-level
@@ -4498,6 +4783,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         lastKnownTotalProcessedTokens: undefined,
         lastAssistantUuid: resumeState?.resumeSessionAt,
         lastThreadStartedId: undefined,
+        announcedUsageLimits: undefined,
         stopped: false,
       };
       yield* Ref.set(contextRef, context);
@@ -4649,6 +4935,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         capturedProposedPlanKeys: new Set(),
         latestAssistantUsage: undefined,
         compactedSinceLatestAssistantUsage: false,
+        hasSubagents: false,
         nextSyntheticAssistantBlockIndex: -1,
       };
 
diff --git a/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts b/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
index 253118299820..232b8cc02d00 100644
--- a/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
@@ -1,4 +1,11 @@
+// @effect-diagnostics nodeBuiltinImport:off - cleanup uses Node's retrying rm, which the FileSystem service does not expose.
+import * as ClaudeSdk from "@anthropic-ai/claude-agent-sdk";
+import { vi } from "vite-plus/test";
+import * as Deferred from "effect/Deferred";
+import * as Fiber from "effect/Fiber";
+import * as TestClock from "effect/testing/TestClock";
 import { ClaudeSettings } from "@t3tools/contracts";
+import * as NodeFSP from "node:fs/promises";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -12,6 +19,8 @@ import {
   probeClaudeCapabilities,
 } from "./ClaudeProvider.ts";
 
+vi.mock("@anthropic-ai/claude-agent-sdk", { spy: true });
+
 const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
 
 it("isolates Claude capability probes without dropping workspace setting sources", () => {
@@ -51,8 +60,25 @@ it.layer(NodeServices.layer)("Claude capability probe SDK boundary", (it) => {
       const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-probe-sdk-" });
       const executablePath = path.join(tempDir, "fake-claude.mjs");
       const invocationPath = path.join(tempDir, "invocation.json");
-      const workspaceCwd = path.join(tempDir, "workspace");
-      yield* fs.makeDirectory(workspaceCwd, { recursive: true });
+      // The probe aborts the SDK without awaiting the child's exit, and on
+      // Windows a directory that is still some process's cwd cannot be
+      // removed. Keep the workspace outside the scoped directory and let it
+      // go with a retrying removal once the child has gone.
+      const workspaceCwd = yield* fs.makeTempDirectory({ prefix: "t3-claude-probe-cwd-" });
+      // Node's own retry rather than an Effect schedule: it.effect runs on a
+      // TestClock, so a scheduled retry would wait for time nobody advances.
+      // If the child still holds the directory after that, an empty temp
+      // directory is left behind rather than failing the test for it.
+      yield* Effect.addFinalizer(() =>
+        Effect.promise(() =>
+          NodeFSP.rm(workspaceCwd, {
+            recursive: true,
+            force: true,
+            maxRetries: 20,
+            retryDelay: 250,
+          }).catch(() => undefined),
+        ),
+      );
 
       yield* fs.writeFileString(
         executablePath,
@@ -162,3 +188,38 @@ it.layer(NodeServices.layer)("Claude capability probe SDK boundary", (it) => {
     }).pipe(Effect.scoped),
   );
 });
+
+it.effect("preserves initialized capabilities when optional usage times out", () =>
+  Effect.gen(function* () {
+    const usageStarted = yield* Deferred.make<void>();
+    let abortSignal: AbortSignal | undefined;
+    const query = vi.spyOn(ClaudeSdk, "query").mockImplementation(({ options }) => {
+      abortSignal = options?.abortController?.signal;
+      return {
+        initializationResult: async () => ({
+          account: { email: "dev@example.com", subscriptionType: "pro", tokenSource: "oauth" },
+          commands: [{ name: "review", description: "Review changes", argumentHint: "[path]" }],
+        }),
+        usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET: () => {
+          Deferred.doneUnsafe(usageStarted, Effect.void);
+          return new Promise(() => {});
+        },
+      } as ReturnType<typeof ClaudeSdk.query>;
+    });
+    yield* Effect.addFinalizer(() => Effect.sync(() => query.mockRestore()));
+    const probe = yield* probeClaudeCapabilities(
+      decodeClaudeSettings({ binaryPath: "claude" }),
+    ).pipe(Effect.forkChild);
+    yield* Deferred.await(usageStarted);
+    yield* TestClock.adjust("4 seconds");
+    const capabilities = yield* Fiber.join(probe);
+    assert.equal(capabilities?.email, "dev@example.com");
+    assert.equal(capabilities?.subscriptionType, "pro");
+    assert.equal(capabilities?.tokenSource, "oauth");
+    assert.deepEqual(capabilities?.slashCommands, [
+      { name: "review", description: "Review changes", input: { hint: "[path]" } },
+    ]);
+    assert.equal(capabilities?.usage, undefined);
+    assert.equal(abortSignal?.aborted, true);
+  }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+);
diff --git a/apps/server/src/provider/Layers/ClaudeProvider.ts b/apps/server/src/provider/Layers/ClaudeProvider.ts
index e4ec8c522da7..e3d2c6ab565d 100644
--- a/apps/server/src/provider/Layers/ClaudeProvider.ts
+++ b/apps/server/src/provider/Layers/ClaudeProvider.ts
@@ -355,44 +355,47 @@ const probeClaudeCapabilities = (
         }),
       });
       const init = await q.initializationResult();
-      // Usage is a second control round trip on the same process; a failure
-      // there must not cost the slash commands and account we already have.
-      const usage = await q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET().then(
-        (response) => ({
-          rate_limits_available: response.rate_limits_available,
-          rate_limits: response.rate_limits,
-        }),
-        () => undefined,
-      );
-      const account = init.account as
-        | {
-            readonly email?: string;
-            readonly subscriptionType?: string;
-            readonly tokenSource?: string;
-            readonly apiProvider?: string;
-          }
-        | undefined;
-      return {
-        email: account?.email,
-        subscriptionType: account?.subscriptionType,
-        tokenSource: account?.tokenSource,
-        apiProvider: account?.apiProvider,
-        slashCommands: parseClaudeInitializationCommands(init.commands),
-        ...(usage ? { usage } : {}),
-      } satisfies ClaudeCapabilitiesProbe;
+      return { q, init };
     });
   }).pipe(
+    Effect.timeout(CAPABILITIES_PROBE_TIMEOUT_MS),
+    Effect.flatMap(({ q, init }) =>
+      Effect.gen(function* () {
+        // Usage has its own deadline so a slow optional request cannot discard initialization.
+        const usageResult = yield* Effect.tryPromise(() =>
+          q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET(),
+        ).pipe(Effect.timeout(DEFAULT_TIMEOUT_MS), Effect.result);
+        const usage = Result.isSuccess(usageResult)
+          ? {
+              rate_limits_available: usageResult.success.rate_limits_available,
+              rate_limits: usageResult.success.rate_limits,
+            }
+          : undefined;
+        const account = init.account as
+          | {
+              readonly email?: string;
+              readonly subscriptionType?: string;
+              readonly tokenSource?: string;
+              readonly apiProvider?: string;
+            }
+          | undefined;
+        return {
+          email: account?.email,
+          subscriptionType: account?.subscriptionType,
+          tokenSource: account?.tokenSource,
+          apiProvider: account?.apiProvider,
+          slashCommands: parseClaudeInitializationCommands(init.commands),
+          ...(usage ? { usage } : {}),
+        } satisfies ClaudeCapabilitiesProbe;
+      }),
+    ),
     Effect.ensuring(
       Effect.sync(() => {
         if (!abort.signal.aborted) abort.abort();
       }),
     ),
-    Effect.timeoutOption(CAPABILITIES_PROBE_TIMEOUT_MS),
     Effect.result,
-    Effect.map((result) => {
-      if (Result.isFailure(result)) return undefined;
-      return Option.isSome(result.success) ? result.success.value : undefined;
-    }),
+    Effect.map((result) => (Result.isSuccess(result) ? result.success : undefined)),
   );
 };
 
diff --git a/apps/server/src/provider/Layers/CodexAdapter.test.ts b/apps/server/src/provider/Layers/CodexAdapter.test.ts
index eefd7f05afa6..4676d780a530 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.test.ts
@@ -222,6 +222,7 @@ function makeScopedRuntimeFactory(options?: { readonly failConstruction?: boolea
 
 const providerSessionDirectoryTestLayer = Layer.succeed(ProviderSessionDirectory, {
   upsert: () => Effect.void,
+  recordImportedTranscript: () => Effect.die("unused"),
   getProvider: () =>
     Effect.die(new Error("ProviderSessionDirectory.getProvider is not used in test")),
   getBinding: () => Effect.succeed(Option.none()),
@@ -597,7 +598,453 @@ function startLifecycleRuntime() {
   });
 }
 
+function codexTokenUsageEvent(input: {
+  readonly id: string;
+  readonly turnId: string;
+  readonly inputTokens: number;
+  readonly cachedInputTokens: number;
+  readonly cacheCreationTokens: number;
+  readonly outputTokens: number;
+  readonly reasoningTokens: number;
+  readonly last?: {
+    readonly inputTokens: number;
+    readonly cachedInputTokens: number;
+    readonly cacheCreationTokens: number;
+    readonly outputTokens: number;
+    readonly reasoningTokens: number;
+  };
+}): ProviderEvent {
+  const totalTokens = input.inputTokens + input.outputTokens;
+  const last = input.last ?? input;
+  return {
+    id: asEventId(input.id),
+    kind: "notification",
+    provider: ProviderDriverKind.make("codex"),
+    threadId: asThreadId("thread-1"),
+    turnId: asTurnId(input.turnId),
+    createdAt: "2026-01-01T00:00:00.000Z",
+    method: "thread/tokenUsage/updated",
+    payload: {
+      threadId: "thread-1",
+      turnId: input.turnId,
+      tokenUsage: {
+        total: {
+          inputTokens: input.inputTokens,
+          cachedInputTokens: input.cachedInputTokens,
+          cacheWriteInputTokens: input.cacheCreationTokens,
+          outputTokens: input.outputTokens,
+          reasoningOutputTokens: input.reasoningTokens,
+          totalTokens,
+        },
+        last: {
+          inputTokens: last.inputTokens,
+          cachedInputTokens: last.cachedInputTokens,
+          cacheWriteInputTokens: last.cacheCreationTokens,
+          outputTokens: last.outputTokens,
+          reasoningOutputTokens: last.reasoningTokens,
+          totalTokens: last.inputTokens + last.outputTokens,
+        },
+      },
+    },
+  };
+}
+
+function codexTurnEvent(method: "turn/started" | "turn/completed", turnId: string): ProviderEvent {
+  return {
+    id: asEventId(`evt-${method}-${turnId}`),
+    kind: "notification",
+    provider: ProviderDriverKind.make("codex"),
+    threadId: asThreadId("thread-1"),
+    turnId: asTurnId(turnId),
+    createdAt: "2026-01-01T00:00:00.000Z",
+    method,
+    payload:
+      method === "turn/started"
+        ? {}
+        : {
+            threadId: "thread-1",
+            turn: { id: turnId, items: [], status: "completed" },
+          },
+  };
+}
+
 lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
+  it.effect("calculates one Codex turn total from cumulative counters", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-usage"));
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-usage-1",
+          turnId: "turn-usage",
+          inputTokens: 100,
+          cachedInputTokens: 40,
+          cacheCreationTokens: 10,
+          outputTokens: 20,
+          reasoningTokens: 8,
+        }),
+      );
+      // Codex can repeat both notifications without new work.
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-usage"));
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-usage-duplicate",
+          turnId: "turn-usage",
+          inputTokens: 100,
+          cachedInputTokens: 40,
+          cacheCreationTokens: 10,
+          outputTokens: 20,
+          reasoningTokens: 8,
+        }),
+      );
+      yield* runtime.emit({
+        id: asEventId("evt-collab-activity"),
+        kind: "notification",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        turnId: asTurnId("turn-usage"),
+        createdAt: "2026-01-01T00:00:00.000Z",
+        method: "collabAgent/activity",
+        payload: {
+          agentThreadId: "child-1",
+          agentPath: "/root/child-1",
+          activityKind: "started",
+        },
+      });
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-usage-2",
+          turnId: "turn-usage",
+          inputTokens: 150,
+          cachedInputTokens: 60,
+          cacheCreationTokens: 15,
+          outputTokens: 30,
+          reasoningTokens: 12,
+        }),
+      );
+      yield* runtime.emit(codexTurnEvent("turn/completed", "turn-usage"));
+
+      const completed = yield* Fiber.join(completedFiber);
+      NodeAssert.equal(completed._tag, "Some");
+      if (completed._tag === "Some" && completed.value.type === "turn.completed") {
+        NodeAssert.deepStrictEqual(completed.value.payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 150,
+          cachedInputTokens: 60,
+          cacheCreationTokens: 15,
+          outputTokens: 30,
+          reasoningTokens: 12,
+          hasSubagents: true,
+        });
+      }
+    }),
+  );
+
+  it.effect("does not charge a late prior-turn update to the next Codex turn", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-first"));
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-late-1",
+          turnId: "turn-first",
+          inputTokens: 100,
+          cachedInputTokens: 40,
+          cacheCreationTokens: 10,
+          outputTokens: 20,
+          reasoningTokens: 8,
+        }),
+      );
+      yield* runtime.emit(codexTurnEvent("turn/completed", "turn-first"));
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-second"));
+      // A late update for the finished turn lands after the next turn starts.
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-late-2",
+          turnId: "turn-first",
+          inputTokens: 150,
+          cachedInputTokens: 60,
+          cacheCreationTokens: 15,
+          outputTokens: 30,
+          reasoningTokens: 12,
+        }),
+      );
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-late-3",
+          turnId: "turn-second",
+          inputTokens: 170,
+          cachedInputTokens: 65,
+          cacheCreationTokens: 16,
+          outputTokens: 35,
+          reasoningTokens: 14,
+        }),
+      );
+      yield* runtime.emit(codexTurnEvent("turn/completed", "turn-second"));
+
+      const completed = Array.from(yield* Fiber.join(completedFiber));
+      const second = completed[1];
+      NodeAssert.equal(second?.type, "turn.completed");
+      if (second?.type === "turn.completed") {
+        NodeAssert.deepStrictEqual(second.payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 20,
+          cachedInputTokens: 5,
+          cacheCreationTokens: 1,
+          outputTokens: 5,
+          reasoningTokens: 2,
+          hasSubagents: false,
+        });
+      }
+    }),
+  );
+
+  it.effect("clamps Codex cache and reasoning subsets to their totals", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-clamp"));
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-clamp-1",
+          turnId: "turn-clamp",
+          inputTokens: 100,
+          cachedInputTokens: 140,
+          cacheCreationTokens: 120,
+          outputTokens: 20,
+          reasoningTokens: 30,
+        }),
+      );
+      yield* runtime.emit(codexTurnEvent("turn/completed", "turn-clamp"));
+
+      const completed = yield* Fiber.join(completedFiber);
+      NodeAssert.equal(completed._tag, "Some");
+      if (completed._tag === "Some" && completed.value.type === "turn.completed") {
+        NodeAssert.deepStrictEqual(completed.value.payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 100,
+          cachedInputTokens: 100,
+          cacheCreationTokens: 100,
+          outputTokens: 20,
+          reasoningTokens: 20,
+          hasSubagents: false,
+        });
+      }
+    }),
+  );
+
+  it.effect("counts the last response when Codex resets its running total mid-turn", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-reset"));
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-reset-1",
+          turnId: "turn-reset",
+          inputTokens: 5_000,
+          cachedInputTokens: 4_000,
+          cacheCreationTokens: 100,
+          outputTokens: 500,
+          reasoningTokens: 200,
+          last: {
+            inputTokens: 100,
+            cachedInputTokens: 80,
+            cacheCreationTokens: 10,
+            outputTokens: 20,
+            reasoningTokens: 8,
+          },
+        }),
+      );
+      // Codex restarted its cumulative total. The new total is smaller than
+      // the previous one, so only `last` is counted for this update.
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-reset-2",
+          turnId: "turn-reset",
+          inputTokens: 150,
+          cachedInputTokens: 90,
+          cacheCreationTokens: 5,
+          outputTokens: 30,
+          reasoningTokens: 12,
+        }),
+      );
+      yield* runtime.emit(codexTurnEvent("turn/completed", "turn-reset"));
+
+      const completed = yield* Fiber.join(completedFiber);
+      NodeAssert.equal(completed._tag, "Some");
+      if (completed._tag === "Some" && completed.value.type === "turn.completed") {
+        NodeAssert.deepStrictEqual(completed.value.payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 250,
+          cachedInputTokens: 170,
+          cacheCreationTokens: 15,
+          outputTokens: 50,
+          reasoningTokens: 20,
+          hasSubagents: false,
+        });
+      }
+    }),
+  );
+
+  it.effect("uses the last response usage when no prior Codex total exists", () =>
+    Effect.gen(function* () {
+      const adapter = yield* CodexAdapter;
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        resumeCursor: { threadId: "provider-thread-1" },
+        runtimeMode: "full-access",
+      });
+      const runtime = lifecycleRuntimeFactory.lastRuntime;
+      NodeAssert.ok(runtime);
+      const firstCompletionsFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+
+      // Resumed thread: the cumulative total already holds old history, so the
+      // first update must count only `last`.
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-resumed"));
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-resume-baseline",
+          turnId: "turn-resumed",
+          inputTokens: 1_000,
+          cachedInputTokens: 400,
+          cacheCreationTokens: 100,
+          outputTokens: 200,
+          reasoningTokens: 80,
+          last: {
+            inputTokens: 300,
+            cachedInputTokens: 120,
+            cacheCreationTokens: 30,
+            outputTokens: 60,
+            reasoningTokens: 24,
+          },
+        }),
+      );
+      yield* runtime.emit(codexTurnEvent("turn/completed", "turn-resumed"));
+
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-after-resume"));
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-after-resume",
+          turnId: "turn-after-resume",
+          inputTokens: 1_100,
+          cachedInputTokens: 440,
+          cacheCreationTokens: 110,
+          outputTokens: 220,
+          reasoningTokens: 88,
+        }),
+      );
+      yield* runtime.emit(codexTurnEvent("turn/completed", "turn-after-resume"));
+
+      const firstCompletions = Array.from(yield* Fiber.join(firstCompletionsFiber));
+
+      yield* adapter.rollbackThread(asThreadId("thread-1"), 1);
+      const rollbackCompletionFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      // Rollback drops the baseline and Codex shrinks its total, so the first
+      // update after it counts only `last` again.
+      yield* runtime.emit(codexTurnEvent("turn/started", "turn-after-rollback"));
+      yield* runtime.emit(
+        codexTokenUsageEvent({
+          id: "evt-after-rollback",
+          turnId: "turn-after-rollback",
+          inputTokens: 1_050,
+          cachedInputTokens: 420,
+          cacheCreationTokens: 105,
+          outputTokens: 210,
+          reasoningTokens: 84,
+          last: {
+            inputTokens: 50,
+            cachedInputTokens: 20,
+            cacheCreationTokens: 5,
+            outputTokens: 10,
+            reasoningTokens: 4,
+          },
+        }),
+      );
+      yield* runtime.emit(codexTurnEvent("turn/completed", "turn-after-rollback"));
+
+      const rollbackCompletion = yield* Fiber.join(rollbackCompletionFiber);
+      const completions = [
+        ...firstCompletions,
+        ...(rollbackCompletion._tag === "Some" ? [rollbackCompletion.value] : []),
+      ];
+      NodeAssert.deepStrictEqual(
+        completions.map((event) =>
+          event.type === "turn.completed" ? event.payload.tokenUsage : undefined,
+        ),
+        [
+          {
+            usageStatus: "complete",
+            usageScope: "main_agent",
+            inputTokens: 300,
+            cachedInputTokens: 120,
+            cacheCreationTokens: 30,
+            outputTokens: 60,
+            reasoningTokens: 24,
+            hasSubagents: false,
+          },
+          {
+            usageStatus: "complete",
+            usageScope: "main_agent",
+            inputTokens: 100,
+            cachedInputTokens: 40,
+            cacheCreationTokens: 10,
+            outputTokens: 20,
+            reasoningTokens: 8,
+            hasSubagents: false,
+          },
+          {
+            usageStatus: "complete",
+            usageScope: "main_agent",
+            inputTokens: 50,
+            cachedInputTokens: 20,
+            cacheCreationTokens: 5,
+            outputTokens: 10,
+            reasoningTokens: 4,
+            hasSubagents: false,
+          },
+        ],
+      );
+    }),
+  );
+
   it.effect("carries child model metadata through every task event", () =>
     Effect.gen(function* () {
       const { adapter, runtime } = yield* startLifecycleRuntime();
@@ -1431,6 +1878,213 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
     }),
   );
 
+  it.effect("names the edited files in an apply-patch approval without a reason", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+
+      yield* runtime.emit({
+        id: asEventId("evt-apply-patch"),
+        kind: "request",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        createdAt: "2026-08-24T00:00:00.000Z",
+        method: "applyPatchApproval",
+        requestKind: "file-change",
+        requestId: ApprovalRequestId.make("req-patch"),
+        turnId: asTurnId("turn-1"),
+        payload: {
+          callId: "call-1",
+          conversationId: "provider-thread-1",
+          fileChanges: {
+            "/tmp/removed.md": { type: "delete", content: "gone" },
+            "/tmp/added.ts": { type: "add", content: "export {};" },
+          },
+        },
+      } satisfies ProviderEvent);
+
+      const firstEvent = yield* Fiber.join(firstEventFiber);
+
+      NodeAssert.equal(firstEvent._tag, "Some");
+      if (firstEvent._tag !== "Some" || firstEvent.value.type !== "request.opened") {
+        return;
+      }
+      NodeAssert.equal(firstEvent.value.payload.requestType, "apply_patch_approval");
+      NodeAssert.equal(
+        firstEvent.value.payload.detail,
+        "add /tmp/added.ts\ndelete /tmp/removed.md",
+      );
+    }),
+  );
+
+  it.effect("keeps the reason when an apply-patch approval carries one", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+
+      yield* runtime.emit({
+        id: asEventId("evt-apply-patch-reason"),
+        kind: "request",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        createdAt: "2026-08-24T00:00:00.000Z",
+        method: "applyPatchApproval",
+        requestKind: "file-change",
+        requestId: ApprovalRequestId.make("req-patch-reason"),
+        turnId: asTurnId("turn-1"),
+        payload: {
+          callId: "call-2",
+          conversationId: "provider-thread-1",
+          reason: "Needs to rewrite the changelog",
+          fileChanges: { "/tmp/CHANGELOG.md": { type: "add", content: "x" } },
+        },
+      } satisfies ProviderEvent);
+
+      const firstEvent = yield* Fiber.join(firstEventFiber);
+
+      NodeAssert.equal(firstEvent._tag, "Some");
+      if (firstEvent._tag !== "Some" || firstEvent.value.type !== "request.opened") {
+        return;
+      }
+      NodeAssert.equal(firstEvent.value.payload.detail, "Needs to rewrite the changelog");
+    }),
+  );
+
+  it.effect("falls back to the grant root for a file-change approval without a reason", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+
+      yield* runtime.emit({
+        id: asEventId("evt-file-change"),
+        kind: "request",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        createdAt: "2026-08-24T00:00:00.000Z",
+        method: "item/fileChange/requestApproval",
+        requestKind: "file-change",
+        requestId: ApprovalRequestId.make("req-file-change"),
+        turnId: asTurnId("turn-1"),
+        payload: {
+          itemId: "item-1",
+          grantRoot: "/tmp/workspace",
+          startedAtMs: 0,
+          threadId: "provider-thread-1",
+          turnId: "turn-1",
+        },
+      } satisfies ProviderEvent);
+
+      const firstEvent = yield* Fiber.join(firstEventFiber);
+
+      NodeAssert.equal(firstEvent._tag, "Some");
+      if (firstEvent._tag !== "Some" || firstEvent.value.type !== "request.opened") {
+        return;
+      }
+      NodeAssert.equal(firstEvent.value.payload.requestType, "file_change_approval");
+      NodeAssert.equal(firstEvent.value.payload.detail, "/tmp/workspace");
+    }),
+  );
+
+  it.effect("prefers the edited files over a blank apply-patch reason", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+
+      yield* runtime.emit({
+        id: asEventId("evt-apply-patch-blank"),
+        kind: "request",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        createdAt: "2026-08-24T00:00:00.000Z",
+        method: "applyPatchApproval",
+        requestKind: "file-change",
+        requestId: ApprovalRequestId.make("req-patch-blank"),
+        turnId: asTurnId("turn-1"),
+        payload: {
+          callId: "call-3",
+          conversationId: "provider-thread-1",
+          reason: "   ",
+          fileChanges: {
+            "/tmp/moved.ts": { type: "update", unified_diff: "@@", move_path: "/tmp/renamed.ts" },
+          },
+        },
+      } satisfies ProviderEvent);
+
+      const firstEvent = yield* Fiber.join(firstEventFiber);
+
+      NodeAssert.equal(firstEvent._tag, "Some");
+      if (firstEvent._tag !== "Some" || firstEvent.value.type !== "request.opened") {
+        return;
+      }
+      NodeAssert.equal(firstEvent.value.payload.detail, "update /tmp/moved.ts -> /tmp/renamed.ts");
+    }),
+  );
+
+  it.effect("caps the described files in an oversized apply-patch approval", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+
+      const fileChanges = Object.fromEntries(
+        Array.from({ length: 25 }, (_unused, index) => [
+          `/tmp/file-${String(index).padStart(2, "0")}.ts`,
+          { type: "add", content: "x" },
+        ]),
+      );
+
+      yield* runtime.emit({
+        id: asEventId("evt-apply-patch-many"),
+        kind: "request",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        createdAt: "2026-08-24T00:00:00.000Z",
+        method: "applyPatchApproval",
+        requestKind: "file-change",
+        requestId: ApprovalRequestId.make("req-patch-many"),
+        turnId: asTurnId("turn-1"),
+        payload: { callId: "call-4", conversationId: "provider-thread-1", fileChanges },
+      } satisfies ProviderEvent);
+
+      const firstEvent = yield* Fiber.join(firstEventFiber);
+
+      NodeAssert.equal(firstEvent._tag, "Some");
+      if (firstEvent._tag !== "Some" || firstEvent.value.type !== "request.opened") {
+        return;
+      }
+      const detail = firstEvent.value.payload.detail ?? "";
+      NodeAssert.equal(detail.split("\n").length, 21);
+      NodeAssert.ok(detail.endsWith("+5 more"));
+    }),
+  );
+
+  it.effect("leaves an apply-patch approval without changes or a reason undetailed", () =>
+    Effect.gen(function* () {
+      const { adapter, runtime } = yield* startLifecycleRuntime();
+      const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+
+      yield* runtime.emit({
+        id: asEventId("evt-apply-patch-empty"),
+        kind: "request",
+        provider: ProviderDriverKind.make("codex"),
+        threadId: asThreadId("thread-1"),
+        createdAt: "2026-08-24T00:00:00.000Z",
+        method: "applyPatchApproval",
+        requestKind: "file-change",
+        requestId: ApprovalRequestId.make("req-patch-empty"),
+        turnId: asTurnId("turn-1"),
+        payload: { callId: "call-5", conversationId: "provider-thread-1", fileChanges: {} },
+      } satisfies ProviderEvent);
+
+      const firstEvent = yield* Fiber.join(firstEventFiber);
+
+      NodeAssert.equal(firstEvent._tag, "Some");
+      if (firstEvent._tag !== "Some" || firstEvent.value.type !== "request.opened") {
+        return;
+      }
+      NodeAssert.equal(firstEvent.value.payload.detail, undefined);
+    }),
+  );
+
   it.effect("maps MCP elicitation requests into app access approvals", () =>
     Effect.gen(function* () {
       const { adapter, runtime } = yield* startLifecycleRuntime();
diff --git a/apps/server/src/provider/Layers/CodexAdapter.ts b/apps/server/src/provider/Layers/CodexAdapter.ts
index 0dd0d6fc271f..d1981b33d47d 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.ts
@@ -26,6 +26,7 @@ import {
   RuntimeRequestId,
   RuntimeTaskId,
   type RuntimeTaskUsage,
+  type TurnTokenUsage,
   ProviderApprovalDecision,
   ThreadId,
   ProviderSendTurnInput,
@@ -99,9 +100,34 @@ interface CodexAdapterSessionContext {
   readonly scope: Scope.Closeable;
   readonly runtime: CodexSessionRuntimeShape;
   readonly eventFiber: Fiber.Fiber<void, never>;
+  readonly turnTokenUsage: CodexTurnTokenUsageState;
   stopped: boolean;
 }
 
+type CodexCumulativeTokenUsage = {
+  readonly inputTokens: number;
+  readonly cachedInputTokens: number;
+  readonly cacheCreationTokens?: number;
+  readonly outputTokens: number;
+  readonly reasoningTokens: number;
+};
+
+interface CodexTurnTokenUsageAccumulator {
+  inputTokens: number;
+  cachedInputTokens: number;
+  cacheCreationTokens: number | undefined;
+  outputTokens: number;
+  reasoningTokens: number;
+  observed: boolean;
+  hasSubagents: boolean;
+}
+
+interface CodexTurnTokenUsageState {
+  baseline: CodexCumulativeTokenUsage | undefined;
+  activeTurnId: string | undefined;
+  readonly byTurnId: Map<string, CodexTurnTokenUsageAccumulator>;
+}
+
 function mapCodexRuntimeError(
   threadId: ThreadId,
   method: string,
@@ -429,6 +455,162 @@ function normalizeCodexTokenUsage(
   };
 }
 
+function codexTokenUsageBreakdown(
+  usage: EffectCodexSchema.V2ThreadTokenUsageUpdatedNotification__TokenUsageBreakdown,
+): CodexCumulativeTokenUsage {
+  return {
+    inputTokens: usage.inputTokens,
+    cachedInputTokens: usage.cachedInputTokens,
+    ...(usage.cacheWriteInputTokens !== undefined
+      ? { cacheCreationTokens: usage.cacheWriteInputTokens }
+      : {}),
+    outputTokens: usage.outputTokens,
+    reasoningTokens: usage.reasoningOutputTokens,
+  };
+}
+
+function makeCodexTurnTokenUsageState(): CodexTurnTokenUsageState {
+  return {
+    baseline: undefined,
+    activeTurnId: undefined,
+    byTurnId: new Map(),
+  };
+}
+
+function getCodexTurnAccumulator(
+  state: CodexTurnTokenUsageState,
+  turnId: string,
+): CodexTurnTokenUsageAccumulator {
+  const existing = state.byTurnId.get(turnId);
+  if (existing) return existing;
+  const created: CodexTurnTokenUsageAccumulator = {
+    inputTokens: 0,
+    cachedInputTokens: 0,
+    cacheCreationTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0,
+    observed: false,
+    hasSubagents: false,
+  };
+  state.byTurnId.set(turnId, created);
+  return created;
+}
+
+/**
+ * Usage added by one `thread/tokenUsage/updated` notification. Codex reports a
+ * running `total` for the thread and `last`, the usage of the newest model
+ * response. Within a turn the growth of `total` equals `last`. Without a prior
+ * total (first update after resume or rollback), or when Codex reset the
+ * running total, `last` is the delta.
+ */
+function codexTurnTokenUsageDelta(
+  previous: CodexCumulativeTokenUsage | undefined,
+  current: CodexCumulativeTokenUsage,
+  last: CodexCumulativeTokenUsage,
+): CodexCumulativeTokenUsage {
+  if (
+    previous === undefined ||
+    current.inputTokens < previous.inputTokens ||
+    current.cachedInputTokens < previous.cachedInputTokens ||
+    current.outputTokens < previous.outputTokens ||
+    current.reasoningTokens < previous.reasoningTokens
+  ) {
+    return last;
+  }
+  return {
+    inputTokens: current.inputTokens - previous.inputTokens,
+    cachedInputTokens: current.cachedInputTokens - previous.cachedInputTokens,
+    ...(current.cacheCreationTokens !== undefined &&
+    previous.cacheCreationTokens !== undefined &&
+    current.cacheCreationTokens >= previous.cacheCreationTokens
+      ? { cacheCreationTokens: current.cacheCreationTokens - previous.cacheCreationTokens }
+      : {}),
+    outputTokens: current.outputTokens - previous.outputTokens,
+    reasoningTokens: current.reasoningTokens - previous.reasoningTokens,
+  };
+}
+
+function accumulateCodexTurnTokenUsage(
+  state: CodexTurnTokenUsageState,
+  turnId: string,
+  usage: EffectCodexSchema.V2ThreadTokenUsageUpdatedNotification["tokenUsage"],
+): void {
+  const current = codexTokenUsageBreakdown(usage.total);
+  if (state.activeTurnId !== turnId) {
+    // The total is thread-wide, so every update moves the baseline. A late
+    // update for a finished turn is not counted toward the live turn.
+    state.baseline = current;
+    return;
+  }
+
+  const accumulator = getCodexTurnAccumulator(state, turnId);
+  const delta = codexTurnTokenUsageDelta(
+    state.baseline,
+    current,
+    codexTokenUsageBreakdown(usage.last),
+  );
+  state.baseline = current;
+
+  if (
+    delta.inputTokens > 0 ||
+    delta.cachedInputTokens > 0 ||
+    delta.outputTokens > 0 ||
+    delta.reasoningTokens > 0
+  ) {
+    accumulator.observed = true;
+  }
+  accumulator.inputTokens += delta.inputTokens;
+  accumulator.cachedInputTokens += delta.cachedInputTokens;
+  accumulator.outputTokens += delta.outputTokens;
+  accumulator.reasoningTokens += delta.reasoningTokens;
+  if (delta.cacheCreationTokens === undefined) {
+    accumulator.cacheCreationTokens = undefined;
+  } else if (accumulator.cacheCreationTokens !== undefined) {
+    accumulator.cacheCreationTokens += delta.cacheCreationTokens;
+  }
+}
+
+function completeCodexTurnTokenUsage(
+  state: CodexTurnTokenUsageState,
+  turnId: string,
+  completed: boolean,
+): TurnTokenUsage {
+  const usage = state.byTurnId.get(turnId);
+  state.byTurnId.delete(turnId);
+  if (state.activeTurnId === turnId) state.activeTurnId = undefined;
+  if (!usage) {
+    return {
+      usageStatus: "unavailable",
+      usageScope: "main_agent",
+      hasSubagents: false,
+    };
+  }
+
+  if (!usage.observed) {
+    return {
+      usageStatus: "unavailable",
+      usageScope: "main_agent",
+      hasSubagents: usage.hasSubagents,
+    };
+  }
+
+  // Codex counts cache reads and writes inside inputTokens. Clamp the
+  // subsets so the record keeps the documented relationships even if a
+  // counter drifts.
+  return {
+    usageStatus: completed ? "complete" : "partial",
+    usageScope: "main_agent",
+    inputTokens: usage.inputTokens,
+    cachedInputTokens: Math.min(usage.inputTokens, usage.cachedInputTokens),
+    ...(usage.cacheCreationTokens !== undefined
+      ? { cacheCreationTokens: Math.min(usage.inputTokens, usage.cacheCreationTokens) }
+      : {}),
+    outputTokens: usage.outputTokens,
+    reasoningTokens: Math.min(usage.outputTokens, usage.reasoningTokens),
+    hasSubagents: usage.hasSubagents,
+  };
+}
+
 function toTurnStatus(
   value: EffectCodexSchema.V2TurnCompletedNotification["turn"]["status"] | "cancelled",
 ): "completed" | "failed" | "cancelled" | "interrupted" {
@@ -605,6 +787,36 @@ function itemDetail(itemType: CanonicalItemType, item: CodexLifecycleItem): stri
   return undefined;
 }
 
+// Codex sends `reason` only sometimes, and sends it blank rather than absent
+// often enough to matter, so an empty one must not outrank the paths below.
+function nonEmptyDetail(value: string | null | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+}
+
+// Keeps one oversized patch from pushing a wall of paths through every consumer
+// of the approval, while still saying how much it covers.
+const MAX_DESCRIBED_FILE_CHANGES = 20;
+
+// An apply-patch approval carries the edited paths as the keys of `fileChanges`.
+// Without them the approval card has nothing to show but its own title — the
+// command-execution branch already falls back to the command for the same reason.
+function describeFileChanges(
+  fileChanges: EffectCodexSchema.ServerRequest__ApplyPatchApprovalParams["fileChanges"] | undefined,
+): string | undefined {
+  if (fileChanges === undefined) return undefined;
+  const entries = Object.entries(fileChanges).toSorted(([left], [right]) =>
+    left.localeCompare(right),
+  );
+  if (entries.length === 0) return undefined;
+  const described = entries.slice(0, MAX_DESCRIBED_FILE_CHANGES).map(([path, change]) => {
+    const movePath = change.type === "update" ? change.move_path : undefined;
+    return movePath ? `${change.type} ${path} -> ${movePath}` : `${change.type} ${path}`;
+  });
+  const remaining = entries.length - described.length;
+  return remaining > 0 ? `${described.join("\n")}\n+${remaining} more` : described.join("\n");
+}
+
 function toRequestTypeFromMethod(method: string): CanonicalRequestType {
   switch (method) {
     case "item/commandExecution/requestApproval":
@@ -1143,7 +1355,9 @@ function mapToRuntimeEvents(
             EffectCodexSchema.ServerRequest__FileChangeRequestApprovalParams,
             event.payload,
           );
-          return payload?.reason ?? undefined;
+          // These params carry no path of their own, only the root the agent
+          // wants to write under.
+          return nonEmptyDetail(payload?.reason) ?? nonEmptyDetail(payload?.grantRoot);
         }
         case "mcpServer/elicitation/request":
           return elicitation?.message;
@@ -1152,7 +1366,11 @@ function mapToRuntimeEvents(
             EffectCodexSchema.ServerRequest__ApplyPatchApprovalParams,
             event.payload,
           );
-          return payload?.reason ?? undefined;
+          return (
+            nonEmptyDetail(payload?.reason) ??
+            describeFileChanges(payload?.fileChanges) ??
+            nonEmptyDetail(payload?.grantRoot)
+          );
         }
         case "execCommandApproval": {
           const payload = readPayload(
@@ -2063,6 +2281,7 @@ export const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
               }
             : {}),
         };
+        const turnTokenUsage = makeCodexTurnTokenUsageState();
         const sessionScope = yield* Scope.make("sequential");
         let sessionScopeTransferred = false;
         yield* Effect.addFinalizer(() =>
@@ -2091,7 +2310,64 @@ export const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
         const eventFiber = yield* Stream.runForEach(runtime.events, (event) =>
           Effect.gen(function* () {
             yield* writeNativeEvent(event);
-            const runtimeEvents = mapToRuntimeEvents(event, event.threadId);
+            if (event.method === "turn/started" && event.turnId) {
+              if (turnTokenUsage.activeTurnId !== event.turnId) {
+                turnTokenUsage.byTurnId.clear();
+                turnTokenUsage.activeTurnId = event.turnId;
+                getCodexTurnAccumulator(turnTokenUsage, event.turnId);
+              }
+            } else if (event.method === "thread/tokenUsage/updated") {
+              const payload = readPayload(
+                EffectCodexSchema.V2ThreadTokenUsageUpdatedNotification,
+                event.payload,
+              );
+              if (payload) {
+                accumulateCodexTurnTokenUsage(turnTokenUsage, payload.turnId, payload.tokenUsage);
+              }
+            } else if (turnTokenUsage.activeTurnId) {
+              const collabPayload =
+                typeof event.payload === "object" && event.payload !== null
+                  ? (event.payload as Record<string, unknown>)
+                  : undefined;
+              const isCollabSpawn =
+                event.method === "collabAgent/started" ||
+                (event.method === "collabAgent/activity" &&
+                  collabPayload?.activityKind === "started");
+              if (isCollabSpawn && event.turnId === turnTokenUsage.activeTurnId) {
+                getCodexTurnAccumulator(turnTokenUsage, turnTokenUsage.activeTurnId).hasSubagents =
+                  true;
+              }
+            }
+
+            const runtimeEvents = mapToRuntimeEvents(event, event.threadId).map((runtimeEvent) => {
+              if (runtimeEvent.type === "turn.completed" && runtimeEvent.turnId) {
+                return {
+                  ...runtimeEvent,
+                  payload: {
+                    ...runtimeEvent.payload,
+                    tokenUsage: completeCodexTurnTokenUsage(
+                      turnTokenUsage,
+                      String(runtimeEvent.turnId),
+                      runtimeEvent.payload.state === "completed",
+                    ),
+                  },
+                } satisfies ProviderRuntimeEvent;
+              }
+              if (runtimeEvent.type === "turn.aborted" && runtimeEvent.turnId) {
+                return {
+                  ...runtimeEvent,
+                  payload: {
+                    ...runtimeEvent.payload,
+                    tokenUsage: completeCodexTurnTokenUsage(
+                      turnTokenUsage,
+                      String(runtimeEvent.turnId),
+                      false,
+                    ),
+                  },
+                } satisfies ProviderRuntimeEvent;
+              }
+              return runtimeEvent;
+            });
             if (runtimeEvents.length === 0) {
               yield* Effect.logDebug("ignoring unhandled Codex provider event", {
                 method: event.method,
@@ -2129,6 +2405,7 @@ export const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
           scope: sessionScope,
           runtime,
           eventFiber,
+          turnTokenUsage,
           stopped: false,
         });
         sessionScopeTransferred = true;
@@ -2262,7 +2539,17 @@ export const makeCodexAdapter = Effect.fn("makeCodexAdapter")(function* (
     }
 
     return requireSession(threadId).pipe(
-      Effect.flatMap((session) => session.runtime.rollbackThread(numTurns)),
+      Effect.flatMap((session) =>
+        session.runtime.rollbackThread(numTurns).pipe(
+          Effect.tap(() =>
+            Effect.sync(() => {
+              session.turnTokenUsage.baseline = undefined;
+              session.turnTokenUsage.activeTurnId = undefined;
+              session.turnTokenUsage.byTurnId.clear();
+            }),
+          ),
+        ),
+      ),
       Effect.mapError((cause) =>
         cause._tag === "ProviderAdapterSessionNotFoundError"
           ? cause
diff --git a/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts b/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
index 5bc5940fe539..02b7a45f33ad 100644
--- a/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
+++ b/apps/server/src/provider/Layers/CodexCollabRuntime.integration.test.ts
@@ -9,6 +9,7 @@
  */
 // @effect-diagnostics nodeBuiltinImport:off
 import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
@@ -23,6 +24,7 @@ import { assert, describe } from "vite-plus/test";
 
 import wireFixture from "../testFixtures/codexMultiAgentWire.json" with { type: "json" };
 import { makeCodexSessionRuntime } from "./CodexSessionRuntime.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
 const ROOT = wireFixture.rootThreadId;
 const [CHILD_A, CHILD_B] = wireFixture.childThreadIds as [string, string];
@@ -157,7 +159,11 @@ function readRecordedRequests() {
 }
 
 const scriptPath = NodePath.join(import.meta.dirname, "../testFixtures/.collab-script.json");
-const peerPath = NodePath.join(import.meta.dirname, "../testFixtures/codexCollabMockPeer.sh");
+// Windows cannot run the shebang wrapper; the .cmd sibling does the same job.
+const peerPath = NodePath.join(
+  import.meta.dirname,
+  `../testFixtures/codexCollabMockPeer.${HostProcessPlatform.defaultValue() === "win32" ? "cmd" : "sh"}`,
+);
 
 describe("CodexSessionRuntime collab integration", () => {
   it.effect("looks up child model metadata once after activity registration", () =>
@@ -195,7 +201,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-collab-model-activity"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -287,7 +293,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-collab-model-spawn"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -366,7 +372,7 @@ describe("CodexSessionRuntime collab integration", () => {
           const runtime = yield* makeCodexSessionRuntime({
             threadId: ThreadId.make(`thread-collab-model-${name}`),
             binaryPath: peerPath,
-            cwd: "/tmp",
+            cwd: NodeOS.tmpdir(),
             runtimeMode: "full-access",
             environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
           });
@@ -405,7 +411,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-collab-integration"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -547,7 +553,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-collab-stop"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -625,7 +631,7 @@ describe("CodexSessionRuntime collab integration", () => {
       const runtime = yield* makeCodexSessionRuntime({
         threadId: ThreadId.make("thread-codex-queued-stop"),
         binaryPath: peerPath,
-        cwd: "/tmp",
+        cwd: NodeOS.tmpdir(),
         runtimeMode: "full-access",
         environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
       });
@@ -722,7 +728,7 @@ describe("CodexSessionRuntime collab integration", () => {
         const runtime = yield* makeCodexSessionRuntime({
           threadId: ThreadId.make("thread-codex-mcp-elicitation"),
           binaryPath: peerPath,
-          cwd: "/tmp",
+          cwd: NodeOS.tmpdir(),
           runtimeMode: "auto",
           environment: { ...process.env, T3_CODEX_COLLAB_SCRIPT: scriptPath },
         });
diff --git a/apps/server/src/provider/Layers/CodexProvider.ts b/apps/server/src/provider/Layers/CodexProvider.ts
index ac35ee138a8b..d65a09c6d4f9 100644
--- a/apps/server/src/provider/Layers/CodexProvider.ts
+++ b/apps/server/src/provider/Layers/CodexProvider.ts
@@ -15,6 +15,7 @@ import * as CodexErrors from "effect-codex-app-server/errors";
 
 import type {
   CodexSettings,
+  CustomModelSetting,
   ServerProvider,
   ServerProviderState,
   ModelCapabilities,
@@ -24,7 +25,7 @@ import type {
 } from "@t3tools/contracts";
 import { PREFERRED_DEFAULT_CODEX_MODELS, ServerSettingsError } from "@t3tools/contracts";
 
-import { createModelCapabilities } from "@t3tools/shared/model";
+import { createModelCapabilities, readCustomModelEntries } from "@t3tools/shared/model";
 import { resolveSpawnCommand } from "@t3tools/shared/shell";
 import { codexAppServerArgs, resolveCodexLaunchArgs } from "./codexLaunchArgs.ts";
 import {
@@ -244,9 +245,14 @@ export function applyPreferredCodexDefaultModel(
   });
 }
 
+/**
+ * Codex has no static default capability set, so a bare custom slug borrows
+ * the first built-in's descriptors; an entry with its own capabilities keeps
+ * them.
+ */
 function appendCustomCodexModels(
   models: ReadonlyArray<ServerProviderModel>,
-  customModels: ReadonlyArray<string>,
+  customModels: ReadonlyArray<CustomModelSetting>,
 ): ReadonlyArray<ServerProviderModel> {
   if (customModels.length === 0) {
     return models;
@@ -255,17 +261,16 @@ function appendCustomCodexModels(
   const seen = new Set(models.map((model) => model.slug));
   const fallbackCapabilities = models.find((model) => model.capabilities)?.capabilities ?? null;
   const customEntries: ServerProviderModel[] = [];
-  for (const rawModel of customModels) {
-    const slug = rawModel.trim();
-    if (!slug || seen.has(slug)) {
+  for (const entry of readCustomModelEntries(customModels)) {
+    if (seen.has(entry.slug)) {
       continue;
     }
-    seen.add(slug);
+    seen.add(entry.slug);
     customEntries.push({
-      slug,
-      name: slug,
+      slug: entry.slug,
+      name: entry.name,
       isCustom: true,
-      capabilities: fallbackCapabilities,
+      capabilities: entry.capabilities ?? fallbackCapabilities,
     });
   }
   return customEntries.length === 0 ? models : [...models, ...customEntries];
@@ -399,7 +404,7 @@ const probeCodexAppServerProvider = Effect.fn("probeCodexAppServerProvider")(fun
   readonly homePath?: string;
   readonly launchArgs?: string;
   readonly cwd: string;
-  readonly customModels?: ReadonlyArray<string>;
+  readonly customModels?: ReadonlyArray<CustomModelSetting>;
   readonly environment?: NodeJS.ProcessEnv;
 }) {
   const { client, initialize } = yield* withCodexAppServerClient(input);
@@ -470,21 +475,8 @@ export const probeCodexSkillsForCwd = Effect.fn("probeCodexSkillsForCwd")(functi
   return parseCodexSkillsListResponse(skillsResponse, input.cwd);
 });
 
-const emptyCodexModelsFromSettings = (codexSettings: CodexSettings): ServerProvider["models"] => {
-  const models = new Set<string>();
-  for (const model of codexSettings.customModels) {
-    const trimmed = model.trim();
-    if (trimmed.length > 0) {
-      models.add(trimmed);
-    }
-  }
-  return Array.from(models, (model) => ({
-    slug: model,
-    name: model,
-    isCustom: true,
-    capabilities: null,
-  }));
-};
+const emptyCodexModelsFromSettings = (codexSettings: CodexSettings): ServerProvider["models"] =>
+  appendCustomCodexModels([], codexSettings.customModels);
 
 const makePendingCodexProvider = (
   codexSettings: CodexSettings,
@@ -562,7 +554,7 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
     readonly homePath?: string;
     readonly launchArgs?: string;
     readonly cwd: string;
-    readonly customModels: ReadonlyArray<string>;
+    readonly customModels: ReadonlyArray<CustomModelSetting>;
     readonly environment?: NodeJS.ProcessEnv;
   }) => Effect.Effect<
     CodexAppServerProviderSnapshot,
diff --git a/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts b/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
index fd4d66dd497b..0136c3fbf170 100644
--- a/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
+++ b/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
@@ -9,11 +9,7 @@ import * as CodexErrors from "effect-codex-app-server/errors";
 import * as CodexRpc from "effect-codex-app-server/rpc";
 import * as EffectCodexSchema from "effect-codex-app-server/schema";
 
-import {
-  buildCodexDeveloperInstructions,
-  codexDefaultModeDeveloperInstructions,
-  codexPlanModeDeveloperInstructions,
-} from "../CodexDeveloperInstructions.ts";
+import { buildCodexDeveloperInstructions } from "../CodexDeveloperInstructions.ts";
 import { codexSessionAppServerArgs } from "./codexLaunchArgs.ts";
 import {
   buildTurnStartParams,
@@ -459,7 +455,7 @@ describe("buildCodexDeveloperInstructions", () => {
       reasoningEffort: "high",
     });
 
-    NodeAssert.ok(instructions.startsWith(codexDefaultModeDeveloperInstructions(true)));
+    NodeAssert.match(instructions, /^<collaboration_mode># Collaboration Mode: Default/);
     NodeAssert.match(instructions, /T3 Code/);
     NodeAssert.match(instructions, /Codex harness/);
     NodeAssert.match(instructions, /as gpt-5\.3-codex with high reasoning effort/);
@@ -484,7 +480,7 @@ describe("buildCodexDeveloperInstructions", () => {
       reasoningEffort: "medium",
     });
 
-    NodeAssert.ok(instructions.startsWith(codexPlanModeDeveloperInstructions(true)));
+    NodeAssert.match(instructions, /^<collaboration_mode># Plan Mode/);
     NodeAssert.match(instructions, /as gpt-5\.3-codex with medium reasoning effort/);
   });
 
@@ -513,11 +509,11 @@ describe("buildCodexDeveloperInstructions", () => {
 });
 
 describe("T3 browser developer instructions", () => {
+  const runtime = { model: "gpt-5.3-codex", reasoningEffort: "high" };
+
   it("prefers the product-native preview tools in both collaboration modes", () => {
-    for (const instructions of [
-      codexDefaultModeDeveloperInstructions(true),
-      codexPlanModeDeveloperInstructions(true),
-    ]) {
+    for (const mode of ["default", "plan"] as const) {
+      const instructions = buildCodexDeveloperInstructions(mode, runtime, true);
       NodeAssert.match(instructions, /t3-code/);
       NodeAssert.match(instructions, /preview_status/);
       NodeAssert.match(instructions, /preview_open/);
@@ -526,10 +522,8 @@ describe("T3 browser developer instructions", () => {
   });
 
   it("omits the browser block entirely when the preview tools are not attached", () => {
-    for (const instructions of [
-      codexDefaultModeDeveloperInstructions(false),
-      codexPlanModeDeveloperInstructions(false),
-    ]) {
+    for (const mode of ["default", "plan"] as const) {
+      const instructions = buildCodexDeveloperInstructions(mode, runtime, false);
       NodeAssert.doesNotMatch(instructions, /preview_status/);
       NodeAssert.doesNotMatch(instructions, /preview_open/);
       NodeAssert.doesNotMatch(instructions, /T3 Code collaborative browser/);
@@ -543,7 +537,6 @@ describe("T3 browser developer instructions", () => {
   });
 
   it("tracks the turn's MCP configuration rather than defaulting to on", () => {
-    const runtime = { model: "gpt-5.3-codex", reasoningEffort: "high" };
     NodeAssert.match(buildCodexDeveloperInstructions("default", runtime, true), /preview_open/);
     NodeAssert.doesNotMatch(
       buildCodexDeveloperInstructions("default", runtime, false),
diff --git a/apps/server/src/provider/Layers/CursorAdapter.test.ts b/apps/server/src/provider/Layers/CursorAdapter.test.ts
index b952c97ffac8..9881710135ce 100644
--- a/apps/server/src/provider/Layers/CursorAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CursorAdapter.test.ts
@@ -30,6 +30,8 @@ import { buildRuntimeInstructions } from "../RuntimeInstructions.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import type { CursorAdapterShape } from "../Services/CursorAdapter.ts";
 import { makeCursorAdapter } from "./CursorAdapter.ts";
+import { execScriptSource, writeFakeCli } from "../../testUtils/fakeCli.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 const decodeCursorSettings = Schema.decodeSync(CursorSettings);
 
 // Test-local service tag so the rest of the file can keep using `yield* CursorAdapter`.
@@ -39,26 +41,25 @@ class CursorAdapter extends Context.Service<CursorAdapter, CursorAdapterShape>()
 
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
 const mockAgentPath = NodePath.join(__dirname, "../../../scripts/acp-mock-agent.ts");
-const mockAgentCommand = "node";
-const mockAgentArgs = [mockAgentPath] as const;
-
+// Stopping a session kills the agent with SIGTERM; Windows terminates the
+// process instead, so the mock never sees a signal to log.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 async function makeMockAgentWrapper(
   extraEnv?: Record<string, string>,
   options?: { initialDelaySeconds?: number },
 ) {
   const dir = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "cursor-acp-mock-"));
-  const wrapperPath = NodePath.join(dir, "fake-agent.sh");
-  const envExports = Object.entries(extraEnv ?? {})
-    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
-    .join("\n");
-  const script = `#!/bin/sh
-${envExports}
-${options?.initialDelaySeconds ? `sleep ${JSON.stringify(String(options.initialDelaySeconds))}` : ""}
-exec ${JSON.stringify(mockAgentCommand)} ${mockAgentArgs.map((arg) => JSON.stringify(arg)).join(" ")} "$@"
-`;
-  await NodeFSP.writeFile(wrapperPath, script, "utf8");
-  await NodeFSP.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-agent",
+    env: extraEnv ?? {},
+    source: execScriptSource({
+      scriptPath: mockAgentPath,
+      ...(options?.initialDelaySeconds === undefined
+        ? {}
+        : { delayMs: Math.round(options.initialDelaySeconds * 1000) }),
+    }),
+  });
 }
 
 async function makeProbeWrapper(
@@ -67,20 +68,12 @@ async function makeProbeWrapper(
   extraEnv?: Record<string, string>,
 ) {
   const dir = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "cursor-acp-probe-"));
-  const wrapperPath = NodePath.join(dir, "fake-agent.sh");
-  const envExports = Object.entries(extraEnv ?? {})
-    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
-    .join("\n");
-  const script = `#!/bin/sh
-printf '%s\t' "$@" >> ${JSON.stringify(argvLogPath)}
-printf '\n' >> ${JSON.stringify(argvLogPath)}
-export T3_ACP_REQUEST_LOG_PATH=${JSON.stringify(requestLogPath)}
-${envExports}
-exec ${JSON.stringify(mockAgentCommand)} ${mockAgentArgs.map((arg) => JSON.stringify(arg)).join(" ")} "$@"
-`;
-  await NodeFSP.writeFile(wrapperPath, script, "utf8");
-  await NodeFSP.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-agent",
+    env: { T3_ACP_REQUEST_LOG_PATH: requestLogPath, ...extraEnv },
+    source: execScriptSource({ scriptPath: mockAgentPath, argvLogPath }),
+  });
 }
 
 async function readArgvLog(filePath: string) {
@@ -390,7 +383,7 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
     }),
   );
 
-  it.effect("closes the ACP child process when a session stops", () =>
+  it.effect.skipIf(windowsHost)("closes the ACP child process when a session stops", () =>
     Effect.gen(function* () {
       const adapter = yield* CursorAdapter;
       const settings = yield* ServerSettingsService;
@@ -422,7 +415,7 @@ cursorAdapterTestLayer("CursorAdapterLive", (it) => {
     }),
   );
 
-  it.effect(
+  it.effect.skipIf(windowsHost)(
     "serializes concurrent startSession calls for the same thread and closes the replaced ACP session",
     () =>
       Effect.gen(function* () {
diff --git a/apps/server/src/provider/Layers/CursorProvider.test.ts b/apps/server/src/provider/Layers/CursorProvider.test.ts
index 98983b4b4434..4fa382c788d5 100644
--- a/apps/server/src/provider/Layers/CursorProvider.test.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.test.ts
@@ -16,7 +16,6 @@ import {
   buildCursorCapabilitiesFromConfigOptions,
   checkCursorProviderStatus,
   discoverCursorModelsViaAcp,
-  getCursorFallbackModels,
   getCursorParameterizedModelPickerUnsupportedMessage,
   parseCursorAboutOutput,
   parseCursorCliConfigChannel,
@@ -30,6 +29,8 @@ import {
   probeCursorSkills,
   rewriteCursorSkillMentions,
 } from "../Drivers/CursorSkills.ts";
+import { execScriptSource, writeFakeCli } from "../../testUtils/fakeCli.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
 const runNode = <A, E>(
   effect: Effect.Effect<
@@ -39,6 +40,10 @@ const runNode = <A, E>(
   >,
 ): Promise<A> => Effect.runPromise(effect.pipe(Effect.provide(NodeServices.layer)));
 
+// Closing the probe kills the agent with SIGTERM; Windows terminates the
+// process instead, so the mock never sees a signal to log.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 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));
@@ -73,47 +78,38 @@ 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 mockAgentCommand = ["node", mockAgentPath].map((arg) => JSON.stringify(arg)).join(" ");
-  const envExports = Object.entries(extraEnv ?? {})
-    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
-    .join("\n");
-  const script = `#!/bin/sh
-${envExports}
-exec ${mockAgentCommand} "$@"
-`;
-  yield* fileSystem.writeFileString(wrapperPath, script);
-  yield* fileSystem.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-agent",
+    env: extraEnv ?? {},
+    source: execScriptSource({ scriptPath: mockAgentPath }),
+  });
 });
 
 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 mockAgentCommand = ["node", mockAgentPath].map((arg) => JSON.stringify(arg)).join(" ");
-  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 ${mockAgentCommand} "$@"
-`;
-  yield* fileSystem.writeFileString(wrapperPath, script);
-  yield* fileSystem.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-agent",
+    source: [
+      'if (process.argv[2] === "about") {',
+      '  process.stdout.write("CLI Version         2026.04.09-f2b0fcd\\n");',
+      '  process.stdout.write("User Email          cursor@example.com\\n");',
+      "  process.exit(0);",
+      "}",
+      execScriptSource({ scriptPath: mockAgentPath }),
+    ].join("\n"),
+  });
 });
 
 const waitForFileContent = Effect.fn("waitForFileContent")(function* (
@@ -398,6 +394,56 @@ describe("Cursor skills", () => {
       }),
     ));
 
+  it("treats a symlinked skill outside the root as a package boundary", async () =>
+    await runNode(
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const userHome = yield* fileSystem.makeTempDirectory({
+          directory: NodeOS.tmpdir(),
+          prefix: "cursor-skills-home-",
+        });
+        const workspace = yield* fileSystem.makeTempDirectory({
+          directory: NodeOS.tmpdir(),
+          prefix: "cursor-skills-workspace-",
+        });
+        const library = yield* fileSystem.makeTempDirectory({
+          directory: NodeOS.tmpdir(),
+          prefix: "cursor-skills-library-",
+        });
+        const writeSkill = Effect.fn("writeCursorSkill")(function* (
+          directory: string,
+          contents: string,
+        ) {
+          yield* fileSystem.makeDirectory(directory, { recursive: true });
+          yield* fileSystem.writeFileString(path.join(directory, "SKILL.md"), contents);
+        });
+
+        // A skill package managed in a config repo and installed by symlink.
+        // Its own SKILL.md must be discovered under the link name, but nothing
+        // below the target may be walked.
+        yield* writeSkill(path.join(library, "shared-review"), "---\ndescription: shared\n---\n");
+        yield* writeSkill(path.join(library, "shared-review", "hidden"), "---\n---\n");
+        const root = path.join(workspace, ".cursor", "skills");
+        yield* fileSystem.makeDirectory(root, { recursive: true });
+        yield* fileSystem.symlink(path.join(library, "shared-review"), path.join(root, "review"));
+
+        const skills = yield* discoverCursorSkills(workspace, { HOME: userHome });
+        expect(skills).toEqual([
+          {
+            name: "review",
+            description: "shared",
+            path: path.join(root, "review", "SKILL.md"),
+            scope: "project",
+            enabled: true,
+          },
+        ]);
+        expect(
+          (yield* probeCursorSkills(workspace, { HOME: userHome }).pipe(Effect.result))._tag,
+        ).toBe("Success");
+      }),
+    ));
+
   it("rewrites only discovered skill mentions into Cursor slash invocations", () => {
     expect(hasCursorSkillMention("use $Review_Pr:V2 here")).toBe(true);
     expect(hasCursorSkillMention("please $review this")).toBe(true);
@@ -408,15 +454,23 @@ describe("Cursor skills", () => {
       "please /review this",
     );
   });
-});
 
-describe("getCursorFallbackModels", () => {
-  it("does not publish any built-in cursor models before ACP discovery", () => {
-    expect(
-      getCursorFallbackModels({
-        customModels: ["internal/cursor-model"],
-      }).map((model) => model.slug),
-    ).toEqual(["internal/cursor-model"]);
+  it("detects and invokes digit-leading Cursor skills without rewriting money", () => {
+    const names = new Set(["2spec", "20k", "100M", "1e6"]);
+    // Repeated presence checks must not carry a global-regex cursor.
+    expect(hasCursorSkillMention("use $2spec here")).toBe(true);
+    expect(hasCursorSkillMention("use $2spec here")).toBe(true);
+    expect(rewriteCursorSkillMentions("use $2spec here", names)).toBe("use /2spec here");
+    expect(rewriteCursorSkillMentions("use $2spec here", new Set())).toBe("use $2spec here");
+    for (const text of [
+      "pay $20 tomorrow",
+      "budget $20k here",
+      "cost $100M total",
+      "limit $1e6 here",
+    ]) {
+      expect(hasCursorSkillMention(text)).toBe(false);
+      expect(rewriteCursorSkillMentions(text, names)).toBe(text);
+    }
   });
 });
 
@@ -593,7 +647,7 @@ describe("discoverCursorModelsViaAcp", () => {
     ]);
   });
 
-  it("closes the ACP probe runtime after discovery completes", async () => {
+  it.skipIf(windowsHost)("closes the ACP probe runtime after discovery completes", async () => {
     const { exitLogPath, wrapperPath } = await runNode(
       makeExitLogFixture("cursor-provider-exit-log-"),
     );
diff --git a/apps/server/src/provider/Layers/CursorProvider.ts b/apps/server/src/provider/Layers/CursorProvider.ts
index e6c7853844e0..48fbfe27c482 100644
--- a/apps/server/src/provider/Layers/CursorProvider.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.ts
@@ -572,7 +572,7 @@ export const discoverCursorModelsViaAcp = (
   environment?: NodeJS.ProcessEnv,
 ) => discoverCursorModelsViaListAvailableModels(cursorSettings, environment);
 
-export function getCursorFallbackModels(
+function getCursorFallbackModels(
   cursorSettings: Pick<CursorSettings, "customModels">,
 ): ReadonlyArray<ServerProviderModel> {
   return providerModelsFromSettings([], cursorSettings.customModels, EMPTY_CAPABILITIES);
diff --git a/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts b/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
index c072e6e5148f..500f2815c539 100644
--- a/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
+++ b/apps/server/src/provider/Layers/EventNdjsonLogger.test.ts
@@ -341,6 +341,19 @@ describe("EventNdjsonLogger", () => {
           },
           threadId,
         );
+        yield* native.write(
+          {
+            event: {
+              type: "message.part.updated",
+              payload: {
+                properties: {
+                  part: { type: "tool", state: { status: "running", output: "progress" } },
+                },
+              },
+            },
+          },
+          threadId,
+        );
         yield* native.write({ type: "turn.completed", id: "native-final" }, threadId);
         yield* store.close();
 
@@ -362,6 +375,51 @@ describe("EventNdjsonLogger", () => {
     }),
   );
 
+  it.effect("keeps OpenCode tool input, final output, and errors in native logs", () =>
+    Effect.gen(function* () {
+      const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
+      const basePath = NodePath.join(tempDir, "events.log");
+      const threadId = ThreadId.make("thread-tool-lifecycle");
+
+      try {
+        const store = yield* makeEventNdjsonLogStore(basePath, { batchWindowMs: 0 });
+        const native = store.logger("native");
+        const input = { command: "run-build" };
+        const states = [
+          { status: "pending", input },
+          { status: "completed", input, output: "Build complete", time: { start: 1, end: 2 } },
+          { status: "error", input, error: "Build failed", time: { start: 3, end: 4 } },
+          { status: "unknown", input },
+          null,
+        ];
+        const events = states.map((state) => ({
+          event: {
+            type: "message.part.updated",
+            payload: { properties: { part: { type: "tool", state } } },
+          },
+        }));
+        for (const event of events) {
+          yield* native.write(event, threadId);
+        }
+        yield* store.close();
+
+        const payloads = NodeFS.readFileSync(
+          ownedLogPath(basePath, "thread-tool-lifecycle"),
+          "utf8",
+        )
+          .trim()
+          .split("\n")
+          .map((line) => parseLogLine(line).payload);
+        assert.deepEqual(
+          payloads,
+          events.map((event) => encodeUnknownJson(event)),
+        );
+      } finally {
+        NodeFS.rmSync(tempDir, { recursive: true, force: true });
+      }
+    }),
+  );
+
   it.effect("contains hostile event accessors inside guarded serialization", () =>
     Effect.gen(function* () {
       const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-log-"));
diff --git a/apps/server/src/provider/Layers/EventNdjsonLogger.ts b/apps/server/src/provider/Layers/EventNdjsonLogger.ts
index 241eddb3b9cb..fd81dbacb70a 100644
--- a/apps/server/src/provider/Layers/EventNdjsonLogger.ts
+++ b/apps/server/src/provider/Layers/EventNdjsonLogger.ts
@@ -229,7 +229,15 @@ function shouldPersist(stream: EventNdjsonStream, event: unknown): boolean {
       const part = Reflect.get(properties, "part");
       if (typeof part !== "object" || part === null) return true;
       const partType = Reflect.get(part, "type");
-      return partType !== "text" && partType !== "reasoning";
+      if (partType === "text" || partType === "reasoning") return false;
+      if (partType === "tool") {
+        // Running snapshots repeat growing output. Pending and terminal states stay in the log.
+        const state = Reflect.get(part, "state");
+        if (typeof state === "object" && state !== null) {
+          return Reflect.get(state, "status") !== "running";
+        }
+      }
+      return true;
     }
 
     return true;
diff --git a/apps/server/src/provider/Layers/GrokAdapter.test.ts b/apps/server/src/provider/Layers/GrokAdapter.test.ts
index 44a0c7343d22..41fa6ed0f60a 100644
--- a/apps/server/src/provider/Layers/GrokAdapter.test.ts
+++ b/apps/server/src/provider/Layers/GrokAdapter.test.ts
@@ -33,25 +33,24 @@ import {
   nextGrokPlanModeActive,
   selectGrokPermissionOptionId,
 } from "./GrokAdapter.ts";
+import { execScriptSource, writeFakeCli } from "../../testUtils/fakeCli.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 const decodeGrokSettings = Schema.decodeSync(GrokSettings);
 
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
 const mockAgentPath = NodePath.join(__dirname, "../../../scripts/acp-mock-agent.ts");
-const mockAgentCommand = process.execPath;
+// Stopping a session kills the agent with SIGTERM; Windows terminates the
+// process instead, so the mock never sees a signal to log.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 
 async function makeMockGrokWrapper(extraEnv?: Record<string, string>) {
   const dir = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "grok-acp-mock-"));
-  const wrapperPath = NodePath.join(dir, "fake-grok.sh");
-  const envExports = Object.entries(extraEnv ?? {})
-    .map(([key, value]) => `export ${key}=${JSON.stringify(value)}`)
-    .join("\n");
-  const script = `#!/bin/sh
-${envExports}
-exec ${JSON.stringify(mockAgentCommand)} ${JSON.stringify(mockAgentPath)} "$@"
-`;
-  await NodeFSP.writeFile(wrapperPath, script, "utf8");
-  await NodeFSP.chmod(wrapperPath, 0o755);
-  return wrapperPath;
+  return writeFakeCli({
+    directory: dir,
+    name: "fake-grok",
+    env: extraEnv ?? {},
+    source: execScriptSource({ scriptPath: mockAgentPath }),
+  });
 }
 
 function waitForFileContent(
@@ -340,7 +339,7 @@ it.layer(grokAdapterTestLayer)("GrokAdapterLive", (it) => {
     }),
   );
 
-  it.effect("closes the ACP child process when a session stops", () =>
+  it.effect.skipIf(windowsHost)("closes the ACP child process when a session stops", () =>
     Effect.gen(function* () {
       const threadId = ThreadId.make("grok-stop-session-close");
       const tempDir = yield* Effect.promise(() =>
diff --git a/apps/server/src/provider/Layers/GrokProvider.test.ts b/apps/server/src/provider/Layers/GrokProvider.test.ts
index e7c62f4cbf77..c751919b189a 100644
--- a/apps/server/src/provider/Layers/GrokProvider.test.ts
+++ b/apps/server/src/provider/Layers/GrokProvider.test.ts
@@ -6,7 +6,6 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { describe, expect, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
-import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 import { GrokSettings } from "@t3tools/contracts";
 
@@ -17,6 +16,7 @@ import {
   checkGrokProviderStatus,
   parseGrokModelsCliOutput,
 } from "./GrokProvider.ts";
+import { execScriptSource, writeFakeCli } from "../../testUtils/fakeCli.ts";
 
 const decodeGrokSettings = Schema.decodeSync(GrokSettings);
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
@@ -308,14 +308,17 @@ it.layer(NodeServices.layer)("checkGrokProviderStatus", (it) => {
       const snapshot = yield* Effect.scoped(
         Effect.gen(function* () {
           const fs = yield* FileSystem.FileSystem;
-          const path = yield* Path.Path;
           const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-grok-version-" });
-          const grokPath = path.join(dir, "grok");
-          yield* fs.writeFileString(
-            grokPath,
-            ["#!/bin/sh", `printf "%s\\n" "${secretStderr}" >&2`, "exit 2", ""].join("\n"),
-          );
-          yield* fs.chmod(grokPath, 0o755);
+          const grokPath = writeFakeCli({
+            directory: dir,
+            name: "grok",
+            source: [
+              // @effect-diagnostics-next-line preferSchemaOverJson:off
+              `process.stderr.write(${JSON.stringify(`${secretStderr}\n`)});`,
+              "process.exit(2);",
+              "",
+            ].join("\n"),
+          });
 
           return yield* checkGrokProviderStatus(
             decodeGrokSettings({ enabled: true, binaryPath: grokPath }),
@@ -331,37 +334,31 @@ it.layer(NodeServices.layer)("checkGrokProviderStatus", (it) => {
     }),
   );
 
-  // Single-quotes a path for /bin/sh. Temp dirs and execPath never contain quotes.
-  const shellQuote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
-
-  // A shell stand-in for the Grok CLI: `--version` and `models` print canned text,
+  // A stand-in for the Grok CLI: `--version` and `models` print canned text,
   // and `agent stdio` execs the mock ACP agent so `initialize` returns model metadata.
   const writeFakeGrokCli = (input: { readonly modelsOutput: string; readonly acp: boolean }) =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
       const dir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-grok-probe-" });
-      const modelsPath = path.join(dir, "models.txt");
-      yield* fs.writeFileString(modelsPath, input.modelsOutput);
-      const grokPath = path.join(dir, "grok");
-      const mockAgentPath = path.resolve(__dirname, "../../../scripts/acp-mock-agent.ts");
-      yield* fs.writeFileString(
-        grokPath,
-        [
-          "#!/bin/sh",
-          'case "$1" in',
-          '  --version) printf "grok 1.0.13\\n"; exit 0;;',
-          `  models) cat ${shellQuote(modelsPath)}; exit 0;;`,
-          input.acp
-            ? `  agent) exec ${shellQuote(process.execPath)} ${shellQuote(mockAgentPath)};;`
-            : "  agent) exit 3;;",
-          "esac",
-          "exit 1",
+      const mockAgentPath = NodePath.resolve(__dirname, "../../../scripts/acp-mock-agent.ts");
+      return writeFakeCli({
+        directory: dir,
+        name: "grok",
+        source: [
+          'if (process.argv[2] === "--version") {',
+          '  process.stdout.write("grok 1.0.13\\n");',
+          "  process.exit(0);",
+          "}",
+          'if (process.argv[2] === "models") {',
+          // @effect-diagnostics-next-line preferSchemaOverJson:off
+          `  process.stdout.write(${JSON.stringify(input.modelsOutput)});`,
+          "  process.exit(0);",
+          "}",
+          'if (process.argv[2] !== "agent") process.exit(1);',
+          ...(input.acp ? [execScriptSource({ scriptPath: mockAgentPath })] : ["process.exit(3);"]),
           "",
         ].join("\n"),
-      );
-      yield* fs.chmod(grokPath, 0o755);
-      return grokPath;
+      });
     });
 
   it.effect("reports ready with ACP-discovered models when logged in", () =>
diff --git a/apps/server/src/provider/Layers/GrokProvider.ts b/apps/server/src/provider/Layers/GrokProvider.ts
index 50a881f38897..493e46d44352 100644
--- a/apps/server/src/provider/Layers/GrokProvider.ts
+++ b/apps/server/src/provider/Layers/GrokProvider.ts
@@ -1,4 +1,5 @@
 import {
+  type CustomModelSetting,
   type GrokSettings,
   type ModelCapabilities,
   type ServerProvider,
@@ -104,7 +105,7 @@ export function buildInitialGrokProviderSnapshot(
 }
 
 function grokModelsFromSettings(
-  customModels: ReadonlyArray<string> | undefined,
+  customModels: ReadonlyArray<CustomModelSetting> | undefined,
   builtInModels: ReadonlyArray<ServerProviderModel> = GROK_BUILT_IN_MODELS,
 ): ReadonlyArray<ServerProviderModel> {
   return providerModelsFromSettings(builtInModels, customModels ?? [], EMPTY_CAPABILITIES);
diff --git a/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
index dfa6f20be7c0..082e20d7cb54 100644
--- a/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
@@ -3,6 +3,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
 import * as Cause from "effect/Cause";
 import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
@@ -15,7 +17,12 @@ import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
 import * as TestClock from "effect/testing/TestClock";
 import { beforeEach } from "vite-plus/test";
-import type { PermissionRequest, QuestionRequest } from "@opencode-ai/sdk/v2";
+import type {
+  Event as OpenCodeEvent,
+  PermissionRequest,
+  QuestionRequest,
+  ToolPart,
+} from "@opencode-ai/sdk/v2";
 
 import {
   ApprovalRequestId,
@@ -36,12 +43,12 @@ import {
   type OpenCodeRuntimeShape,
 } from "../opencodeRuntime.ts";
 import {
-  appendOpenCodeAssistantTextDelta,
   isOpenCodeNotFound,
   isSameOpenCodeDirectory,
   makeOpenCodeAdapter,
   mergeOpenCodeAssistantText,
 } from "./OpenCodeAdapter.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 // Test-local service tag so the rest of the file can keep using `yield* OpenCodeAdapter`.
 class OpenCodeAdapter extends Context.Service<OpenCodeAdapter, OpenCodeAdapterShape>()(
@@ -85,23 +92,30 @@ const runtimeMock = {
     promptAsyncImplementation: null as (() => Promise<void>) | null,
     autoPromptEcho: true,
     autoConnect: true,
+    endEventStream: false,
     promptEchoEvents: [] as Array<unknown>,
     closeError: null as Error | null,
     messages: [] as MessageEntry[],
     subscribedEvents: [] as Array<unknown | Promise<unknown>>,
     eventSubscribeObserved: null as (() => void) | null,
+    eventStreamError: null as ((cause: unknown) => void) | null,
     permissionReplyCalls: [] as Array<{ requestID: string; reply: string }>,
-    permissionReplyImplementation: null as (() => Promise<void>) | null,
+    permissionReplyImplementation: null as ((signal?: AbortSignal) => Promise<void>) | null,
+    permissionReplySignals: [] as AbortSignal[],
     questionReplyCalls: [] as Array<{
       requestID: string;
       answers: ReadonlyArray<ReadonlyArray<string>>;
     }>,
+    questionReplyImplementation: null as ((signal?: AbortSignal) => Promise<void>) | null,
     sessionStatus: "idle" as "idle" | "busy",
     sessionStatusFailures: 0,
     sessionStatusCalls: 0,
     sessionStatusImplementation: null as (() => Promise<unknown>) | null,
     sessionGetIds: [] as string[],
     sessionGetObserved: null as ((sessionID: string) => void) | null,
+    sessionGetImplementation: null as
+      | ((sessionID: string, signal?: AbortSignal) => Promise<void>)
+      | null,
     missingSessionIds: new Set<string>(),
     transientErrorSessionIds: new Set<string>(),
     sessionDirectoryById: new Map<string, string>(),
@@ -137,20 +151,25 @@ const runtimeMock = {
     this.state.promptAsyncImplementation = null;
     this.state.autoPromptEcho = true;
     this.state.autoConnect = true;
+    this.state.endEventStream = false;
     this.state.promptEchoEvents.length = 0;
     this.state.closeError = null;
     this.state.messages = [];
     this.state.subscribedEvents = [];
     this.state.eventSubscribeObserved = null;
+    this.state.eventStreamError = null;
     this.state.permissionReplyCalls.length = 0;
     this.state.permissionReplyImplementation = null;
+    this.state.permissionReplySignals.length = 0;
     this.state.questionReplyCalls.length = 0;
+    this.state.questionReplyImplementation = null;
     this.state.sessionStatus = "idle";
     this.state.sessionStatusFailures = 0;
     this.state.sessionStatusCalls = 0;
     this.state.sessionStatusImplementation = null;
     this.state.sessionGetIds.length = 0;
     this.state.sessionGetObserved = null;
+    this.state.sessionGetImplementation = null;
     this.state.missingSessionIds.clear();
     this.state.transientErrorSessionIds.clear();
     this.state.sessionDirectoryById.clear();
@@ -222,9 +241,12 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
             data: { id: runtimeMock.state.createdSessionIds.shift() ?? `${baseUrl}/session` },
           };
         },
-        get: async ({ sessionID }: { sessionID: string }) => {
+        get: async ({ sessionID }: { sessionID: string }, options?: { signal?: AbortSignal }) => {
           runtimeMock.state.sessionGetIds.push(sessionID);
           runtimeMock.state.sessionGetObserved?.(sessionID);
+          if (runtimeMock.state.sessionGetImplementation) {
+            await runtimeMock.state.sessionGetImplementation(sessionID, options?.signal);
+          }
           // The real client is `throwOnError: true`: non-2xx rejects rather
           // than resolving, so missing → 404 throw, transient → 500 throw.
           if (runtimeMock.state.transientErrorSessionIds.has(sessionID)) {
@@ -264,6 +286,12 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
             runtimeMock.state.abortSignals.push(options.signal);
           }
           await runtimeMock.state.abortImplementation?.(sessionID, options?.signal);
+          runtimeMock.state.pendingPermissions = runtimeMock.state.pendingPermissions.filter(
+            (request) => request.sessionID !== sessionID,
+          );
+          runtimeMock.state.pendingQuestions = runtimeMock.state.pendingQuestions.filter(
+            (request) => request.sessionID !== sessionID,
+          );
         },
         children: async ({ sessionID }: { sessionID: string }) => {
           runtimeMock.state.sessionChildrenCalls.push(sessionID);
@@ -357,19 +385,60 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
         },
       },
       event: {
-        subscribe: async () => {
+        subscribe: async (
+          _input: unknown,
+          options?: { signal?: AbortSignal; onSseError?: (cause: unknown) => void },
+        ) => {
           runtimeMock.state.eventSubscribeObserved?.();
+          runtimeMock.state.eventStreamError = options?.onSseError ?? null;
           return {
             stream: (async function* () {
-              if (runtimeMock.state.autoConnect) {
-                yield { id: "evt-auto-connected", type: "server.connected", properties: {} };
-              }
-              for (const event of runtimeMock.state.subscribedEvents) {
-                const resolved = await event;
-                while (runtimeMock.state.promptEchoEvents.length > 0) {
-                  yield runtimeMock.state.promptEchoEvents.shift();
+              const aborted = promiseWithResolvers<void>();
+              const onAbort = () => aborted.resolve(undefined);
+              options?.signal?.addEventListener("abort", onAbort, { once: true });
+              try {
+                if (runtimeMock.state.autoConnect) {
+                  yield { id: "evt-auto-connected", type: "server.connected", properties: {} };
+                }
+                for (const event of runtimeMock.state.subscribedEvents) {
+                  if (options?.signal?.aborted) return;
+                  const resolved = await Promise.race([event, aborted.promise]);
+                  if (options?.signal?.aborted) return;
+                  while (runtimeMock.state.promptEchoEvents.length > 0) {
+                    yield runtimeMock.state.promptEchoEvents.shift();
+                  }
+                  const nativeEvent = resolved as OpenCodeEvent;
+                  if (nativeEvent.type === "permission.asked") {
+                    runtimeMock.state.pendingPermissions =
+                      runtimeMock.state.pendingPermissions.filter(
+                        (request) => request.id !== nativeEvent.properties.id,
+                      );
+                    runtimeMock.state.pendingPermissions.push(nativeEvent.properties);
+                  } else if (nativeEvent.type === "permission.replied") {
+                    runtimeMock.state.pendingPermissions =
+                      runtimeMock.state.pendingPermissions.filter(
+                        (request) => request.id !== nativeEvent.properties.requestID,
+                      );
+                  } else if (nativeEvent.type === "question.asked") {
+                    runtimeMock.state.pendingQuestions = runtimeMock.state.pendingQuestions.filter(
+                      (request) => request.id !== nativeEvent.properties.id,
+                    );
+                    runtimeMock.state.pendingQuestions.push(nativeEvent.properties);
+                  } else if (
+                    nativeEvent.type === "question.replied" ||
+                    nativeEvent.type === "question.rejected"
+                  ) {
+                    runtimeMock.state.pendingQuestions = runtimeMock.state.pendingQuestions.filter(
+                      (request) => request.id !== nativeEvent.properties.requestID,
+                    );
+                  }
+                  yield resolved;
+                }
+                if (!runtimeMock.state.endEventStream && !options?.signal?.aborted) {
+                  await aborted.promise;
                 }
-                yield resolved;
+              } finally {
+                options?.signal?.removeEventListener("abort", onAbort);
               }
             })(),
           };
@@ -384,11 +453,18 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
               : runtimeMock.state.pendingPermissions,
           };
         },
-        reply: async ({ requestID, reply }: { requestID: string; reply: string }) => {
+        reply: async (
+          { requestID, reply }: { requestID: string; reply: string },
+          options?: { signal?: AbortSignal },
+        ) => {
           runtimeMock.state.permissionReplyCalls.push({ requestID, reply });
+          if (options?.signal) runtimeMock.state.permissionReplySignals.push(options.signal);
           if (runtimeMock.state.permissionReplyImplementation) {
-            await runtimeMock.state.permissionReplyImplementation();
+            await runtimeMock.state.permissionReplyImplementation(options?.signal);
           }
+          runtimeMock.state.pendingPermissions = runtimeMock.state.pendingPermissions.filter(
+            (request) => request.id !== requestID,
+          );
         },
       },
       question: {
@@ -400,14 +476,21 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
               : runtimeMock.state.pendingQuestions,
           };
         },
-        reply: async ({
-          requestID,
-          answers,
-        }: {
-          requestID: string;
-          answers: ReadonlyArray<ReadonlyArray<string>>;
-        }) => {
+        reply: async (
+          {
+            requestID,
+            answers,
+          }: {
+            requestID: string;
+            answers: ReadonlyArray<ReadonlyArray<string>>;
+          },
+          options?: { signal?: AbortSignal },
+        ) => {
           runtimeMock.state.questionReplyCalls.push({ requestID, answers });
+          await runtimeMock.state.questionReplyImplementation?.(options?.signal);
+          runtimeMock.state.pendingQuestions = runtimeMock.state.pendingQuestions.filter(
+            (request) => request.id !== requestID,
+          );
         },
       },
     }) as unknown as ReturnType<OpenCodeRuntimeShape["createOpenCodeSdkClient"]>,
@@ -433,6 +516,7 @@ const OpenCodeRuntimeTestDouble: OpenCodeRuntimeShape = {
 
 const providerSessionDirectoryTestLayer = Layer.succeed(ProviderSessionDirectory, {
   upsert: () => Effect.void,
+  recordImportedTranscript: () => Effect.die("unused"),
   getProvider: () =>
     Effect.die(new Error("ProviderSessionDirectory.getProvider is not used in test")),
   getBinding: () => Effect.succeed(Option.none()),
@@ -2006,132 +2090,122 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     }),
   );
 
-  it.effect("ignores a stale admission status response after the next turn starts", () =>
+  it.effect("marks subagents when a child is proven related by ancestry lookup", () =>
     Effect.gen(function* () {
       const adapter = yield* OpenCodeAdapter;
-      const threadId = asThreadId("thread-stale-admission-status-after-stop");
-      const idleEvent = promiseWithResolvers<unknown>();
-      const userMessageEvent = promiseWithResolvers<unknown>();
-      const staleStatusStarted = promiseWithResolvers<void>();
-      const staleStatusRelease = promiseWithResolvers<void>();
-      const staleStatusReturned = promiseWithResolvers<void>();
-      const activePromptStarted = promiseWithResolvers<void>();
-      const activePromptRelease = promiseWithResolvers<void>();
-      runtimeMock.state.autoPromptEcho = false;
-      runtimeMock.state.subscribedEvents = [idleEvent.promise, userMessageEvent.promise];
-      runtimeMock.state.sessionStatusImplementation = async () => {
-        if (runtimeMock.state.sessionStatusCalls === 1) {
-          staleStatusStarted.resolve(undefined);
-          await staleStatusRelease.promise;
-          staleStatusReturned.resolve(undefined);
-          return {
-            data: { "http://127.0.0.1:9999/session": { type: "busy" as const } },
-          };
-        }
-        return { data: {} };
-      };
-      runtimeMock.state.promptAsyncImplementation = async () => {
-        if (runtimeMock.state.promptCalls.length === 2) {
-          activePromptStarted.resolve(undefined);
-          await activePromptRelease.promise;
-        }
-      };
+      const threadId = asThreadId("thread-child-ancestry-usage");
+      // The child's `session.created` event was missed. Only the ancestry
+      // lookup can prove that `ses_child` belongs to this thread.
+      runtimeMock.state.sessionParentById.set("ses_child", "http://127.0.0.1:9999/session");
+      runtimeMock.state.sessionStatus = "busy";
+      const busy = promiseWithResolvers<unknown>();
+      const childPermission = promiseWithResolvers<unknown>();
+      const idle = promiseWithResolvers<unknown>();
+      runtimeMock.state.subscribedEvents = [busy.promise, childPermission.promise, idle.promise];
 
-      const completedFiber = yield* adapter.streamEvents.pipe(
-        Stream.filter((event) => event.threadId === threadId && event.type === "turn.completed"),
-        Stream.runHead,
+      const eventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter(
+          (event) =>
+            event.threadId === threadId &&
+            (event.type === "request.opened" || event.type === "turn.completed"),
+        ),
+        Stream.take(2),
+        Stream.runCollect,
         Effect.forkChild,
       );
       yield* adapter.startSession({
         provider: ProviderDriverKind.make("opencode"),
         threadId,
-        runtimeMode: "full-access",
-      });
-      const stoppedTurn = yield* adapter.sendTurn({
-        threadId,
-        input: "Stop while status is pending",
-        modelSelection: createModelSelection(
-          ProviderInstanceId.make("opencode"),
-          "opencode/kimi-k3",
-        ),
+        runtimeMode: "approval-required",
       });
-      yield* Effect.promise(() => staleStatusStarted.promise);
-      yield* adapter.interruptTurn(threadId, stoppedTurn.turnId);
-
-      const activeTurnFiber = yield* adapter
+      const sendFiber = yield* adapter
         .sendTurn({
           threadId,
-          input: "Start while the old status is pending",
+          input: "Delegate to a child",
           modelSelection: createModelSelection(
             ProviderInstanceId.make("opencode"),
             "opencode/kimi-k3",
           ),
         })
         .pipe(Effect.forkChild);
-      yield* Effect.promise(() => activePromptStarted.promise);
-      const activeMessageId = (runtimeMock.state.promptCalls.at(-1) as { messageID: string })
-        .messageID;
-
-      staleStatusRelease.resolve(undefined);
-      yield* Effect.promise(() => staleStatusReturned.promise);
-      for (let index = 0; index < 2; index += 1) {
-        yield* Effect.yieldNow;
-      }
-      idleEvent.resolve({
-        id: "evt-idle-after-stale-admission-status",
+      busy.resolve({
+        id: "evt-child-ancestry-busy",
         type: "session.status",
         properties: {
           sessionID: "http://127.0.0.1:9999/session",
-          status: { type: "idle" },
+          status: { type: "busy" },
         },
       });
-      for (let index = 0; index < 4; index += 1) {
-        yield* Effect.yieldNow;
-      }
-      NodeAssert.equal(activeTurnFiber.pollUnsafe(), undefined);
-      NodeAssert.equal(completedFiber.pollUnsafe(), undefined);
-      const sessionsBeforeAcceptance = yield* adapter.listSessions();
-      const sessionBeforeAcceptance = sessionsBeforeAcceptance.find(
-        (candidate) => candidate.threadId === threadId,
-      );
-      NodeAssert.equal(sessionBeforeAcceptance?.status, "running");
-      NodeAssert.notEqual(sessionBeforeAcceptance?.activeTurnId, stoppedTurn.turnId);
+      yield* Fiber.join(sendFiber);
 
-      userMessageEvent.resolve({
-        id: "evt-user-after-stale-admission-status",
-        type: "message.updated",
+      const requestOpened = promiseWithResolvers<void>();
+      runtimeMock.state.sessionGetObserved = (sessionID) => {
+        if (sessionID === "ses_child") requestOpened.resolve(undefined);
+      };
+      childPermission.resolve({
+        id: "evt-child-ancestry-permission",
+        type: "permission.asked",
+        properties: permissionRequest("per_child_ancestry", "ses_child"),
+      });
+      yield* Effect.promise(() => requestOpened.promise);
+      yield* Effect.yieldNow;
+      runtimeMock.state.sessionStatus = "idle";
+      idle.resolve({
+        id: "evt-child-ancestry-idle",
+        type: "session.status",
         properties: {
           sessionID: "http://127.0.0.1:9999/session",
-          info: { id: activeMessageId, role: "user" },
+          status: { type: "idle" },
         },
       });
-      yield* Effect.yieldNow;
-      activePromptRelease.resolve(undefined);
-      const activeTurn = yield* Fiber.join(activeTurnFiber);
-      yield* advanceTestClock(250);
 
-      const completed = Option.getOrUndefined(
-        yield* Fiber.join(completedFiber).pipe(Effect.timeout("1 second")),
+      const events = Array.from(yield* Fiber.join(eventsFiber).pipe(Effect.timeout("1 second")));
+      NodeAssert.deepEqual(
+        events.map((event) => event.type),
+        ["request.opened", "turn.completed"],
       );
-      NodeAssert.equal(completed?.turnId, activeTurn.turnId);
-      const sessions = yield* adapter.listSessions();
-      const session = sessions.find((candidate) => candidate.threadId === threadId);
-      NodeAssert.equal(session?.status, "ready");
-      NodeAssert.equal(session?.activeTurnId, undefined);
-
+      const completed = events[1];
+      if (completed?.type === "turn.completed") {
+        NodeAssert.deepEqual(completed.payload.tokenUsage, {
+          usageStatus: "unavailable",
+          usageScope: "main_agent",
+          hasSubagents: true,
+        });
+      }
       yield* adapter.stopSession(threadId);
     }),
   );
 
-  it.effect("reconciles a sole idle when the matching prompt echo arrives later", () =>
+  it.effect("sums owned OpenCode step usage and marks unresolved usage partial", () =>
     Effect.gen(function* () {
       const adapter = yield* OpenCodeAdapter;
-      const threadId = asThreadId("thread-idle-before-delayed-echo");
-      const idleEvent = promiseWithResolvers<unknown>();
-      const userMessageEvent = promiseWithResolvers<unknown>();
-      runtimeMock.state.autoPromptEcho = false;
-      runtimeMock.state.subscribedEvents = [idleEvent.promise, userMessageEvent.promise];
-      runtimeMock.state.sessionStatusImplementation = async () => ({ data: {} });
+      const threadId = asThreadId("thread-step-usage");
+      const busy = promiseWithResolvers<unknown>();
+      const firstStep = promiseWithResolvers<unknown>();
+      const assistantMessage = promiseWithResolvers<unknown>();
+      const duplicateStep = promiseWithResolvers<unknown>();
+      const secondStep = promiseWithResolvers<unknown>();
+      const unresolvedHeader = promiseWithResolvers<unknown>();
+      const unresolvedStep = promiseWithResolvers<unknown>();
+      const recoveredStep = promiseWithResolvers<unknown>();
+      const recoveredIncompleteHeader = promiseWithResolvers<unknown>();
+      const recoveredCompleteHeader = promiseWithResolvers<unknown>();
+      const childSession = promiseWithResolvers<unknown>();
+      const idle = promiseWithResolvers<unknown>();
+      runtimeMock.state.subscribedEvents = [
+        busy.promise,
+        firstStep.promise,
+        assistantMessage.promise,
+        duplicateStep.promise,
+        secondStep.promise,
+        unresolvedHeader.promise,
+        unresolvedStep.promise,
+        recoveredStep.promise,
+        recoveredIncompleteHeader.promise,
+        recoveredCompleteHeader.promise,
+        childSession.promise,
+        idle.promise,
+      ];
 
       const completedFiber = yield* adapter.streamEvents.pipe(
         Stream.filter((event) => event.threadId === threadId && event.type === "turn.completed"),
@@ -2143,65 +2217,808 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
         threadId,
         runtimeMode: "full-access",
       });
-      const turn = yield* adapter.sendTurn({
-        threadId,
-        input: "Finish before the echo arrives",
-        modelSelection: createModelSelection(
-          ProviderInstanceId.make("opencode"),
-          "opencode/kimi-k3",
-        ),
-      });
-      const messageId = (runtimeMock.state.promptCalls[0] as { messageID?: string }).messageID;
-      idleEvent.resolve({
-        id: "evt-idle-before-delayed-echo",
+      const sendFiber = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "Use two model steps",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("opencode"),
+            "opencode/kimi-k3",
+          ),
+        })
+        .pipe(Effect.forkChild);
+      busy.resolve({
+        id: "evt-step-usage-busy",
         type: "session.status",
         properties: {
           sessionID: "http://127.0.0.1:9999/session",
-          status: { type: "idle" },
+          status: { type: "busy" },
         },
       });
-      userMessageEvent.resolve({
-        id: "evt-delayed-matching-echo",
+      yield* Fiber.join(sendFiber);
+      const promptMessageId = (runtimeMock.state.promptCalls[0] as { messageID: string }).messageID;
+
+      const stepPart = {
+        id: "step-usage-1",
+        sessionID: "http://127.0.0.1:9999/session",
+        messageID: "assistant-step-usage-1",
+        type: "step-finish",
+        reason: "tool-calls",
+        cost: 0,
+        tokens: {
+          input: 100,
+          output: 20,
+          reasoning: 5,
+          cache: { read: 40, write: 10 },
+        },
+      } as const;
+      firstStep.resolve({
+        id: "evt-step-usage-1",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: stepPart,
+        },
+      });
+      assistantMessage.resolve({
+        id: "evt-step-usage-assistant",
         type: "message.updated",
         properties: {
           sessionID: "http://127.0.0.1:9999/session",
-          info: { id: messageId, role: "user" },
+          info: {
+            id: "assistant-step-usage-1",
+            role: "assistant",
+            parentID: promptMessageId,
+          },
+        },
+      });
+      duplicateStep.resolve({
+        id: "evt-step-usage-1-duplicate",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: stepPart,
+        },
+      });
+      secondStep.resolve({
+        id: "evt-step-usage-2",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: {
+            ...stepPart,
+            id: "step-usage-2",
+            tokens: {
+              input: 50,
+              output: 10,
+              reasoning: 2,
+              cache: { read: 10, write: 0 },
+            },
+          },
+        },
+      });
+      unresolvedHeader.resolve({
+        id: "evt-step-usage-unresolved-header",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: {
+            id: "assistant-step-usage-without-parent",
+            role: "assistant",
+          },
+        },
+      });
+      unresolvedStep.resolve({
+        id: "evt-step-usage-unresolved",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: {
+            ...stepPart,
+            id: "step-usage-unresolved",
+            messageID: "assistant-step-usage-without-parent",
+            tokens: {
+              input: 1_000,
+              output: 1_000,
+              reasoning: 0,
+              cache: { read: 0, write: 0 },
+            },
+          },
+        },
+      });
+      recoveredStep.resolve({
+        id: "evt-step-usage-recovered",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: {
+            ...stepPart,
+            id: "step-usage-recovered",
+            messageID: "assistant-step-usage-recovered",
+            tokens: {
+              input: 30,
+              output: 10,
+              reasoning: 2,
+              cache: { read: 5, write: 1 },
+            },
+          },
+        },
+      });
+      recoveredIncompleteHeader.resolve({
+        id: "evt-step-usage-recovered-incomplete-header",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: {
+            id: "assistant-step-usage-recovered",
+            role: "assistant",
+            parentID: "",
+          },
+        },
+      });
+      recoveredCompleteHeader.resolve({
+        id: "evt-step-usage-recovered-complete-header",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: {
+            id: "assistant-step-usage-recovered",
+            role: "assistant",
+            parentID: promptMessageId,
+          },
+        },
+      });
+      childSession.resolve({
+        id: "evt-step-usage-child",
+        type: "session.created",
+        properties: {
+          info: {
+            id: "child-step-usage",
+            parentID: "http://127.0.0.1:9999/session",
+          },
+        },
+      });
+      idle.resolve({
+        id: "evt-step-usage-idle",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "idle" },
         },
       });
-      yield* advanceTestClock(250);
 
-      const completed = Option.getOrUndefined(
-        yield* Fiber.join(completedFiber).pipe(Effect.timeout("1 second")),
-      );
-      NodeAssert.equal(completed?.turnId, turn.turnId);
-      const sessions = yield* adapter.listSessions();
-      const session = sessions.find((candidate) => candidate.threadId === threadId);
-      NodeAssert.equal(session?.status, "ready");
-      NodeAssert.equal(session?.activeTurnId, undefined);
+      const completed = yield* Fiber.join(completedFiber).pipe(Effect.timeout("1 second"));
+      NodeAssert.equal(completed._tag, "Some");
+      if (completed._tag === "Some" && completed.value.type === "turn.completed") {
+        NodeAssert.deepStrictEqual(completed.value.payload.tokenUsage, {
+          usageStatus: "partial",
+          usageScope: "main_agent",
+          inputTokens: 246,
+          cachedInputTokens: 55,
+          cacheCreationTokens: 11,
+          outputTokens: 49,
+          reasoningTokens: 9,
+          hasSubagents: true,
+        });
+      }
 
       yield* adapter.stopSession(threadId);
     }),
   );
 
-  it.effect("reconciles the only idle after a stopped turn when the prompt echo is missing", () =>
+  it.effect("keeps the next turn usage while the prior completion is delayed", () =>
     Effect.gen(function* () {
-      const adapter = yield* OpenCodeAdapter;
-      const threadId = asThreadId("thread-idle-only-without-echo-after-stop");
-      const idleEvent = promiseWithResolvers<unknown>();
-      runtimeMock.state.autoPromptEcho = false;
-      runtimeMock.state.subscribedEvents = [idleEvent.promise];
-      runtimeMock.state.sessionStatusImplementation = async () => ({ data: {} });
-      runtimeMock.state.promptAsyncImplementation = async () => {
-        const prompt = runtimeMock.state.promptCalls.at(-1) as { messageID?: string } | undefined;
-        if (prompt?.messageID) {
-          runtimeMock.state.messages.push({
-            info: { id: prompt.messageID, role: "user" },
-            parts: [],
-          });
-        }
-      };
+      const threadId = asThreadId("thread-token-usage-terminal-handoff");
+      const firstBusy = promiseWithResolvers<unknown>();
+      const firstAssistantMessage = promiseWithResolvers<unknown>();
+      const firstStep = promiseWithResolvers<unknown>();
+      const firstIdle = promiseWithResolvers<unknown>();
+      const secondBusy = promiseWithResolvers<unknown>();
+      const secondAssistantMessage = promiseWithResolvers<unknown>();
+      const secondStep = promiseWithResolvers<unknown>();
+      const secondIdle = promiseWithResolvers<unknown>();
+      runtimeMock.state.subscribedEvents = [
+        firstBusy.promise,
+        firstAssistantMessage.promise,
+        firstStep.promise,
+        firstIdle.promise,
+        secondBusy.promise,
+        secondAssistantMessage.promise,
+        secondStep.promise,
+        secondIdle.promise,
+      ];
 
-      yield* adapter.startSession({
+      const firstStepWriteStarted = yield* Deferred.make<void>();
+      const firstStepWriteRelease = yield* Deferred.make<void>();
+      const terminalUuidStarted = yield* Deferred.make<void>();
+      const terminalUuidRelease = yield* Deferred.make<void>();
+      let blockFirstStepWrite = true;
+      let blockNextUuid = false;
+      const nodeCrypto = yield* Crypto.Crypto;
+      const gatedCrypto = {
+        ...nodeCrypto,
+        randomUUIDv4: Effect.suspend(() => {
+          if (!blockNextUuid) return nodeCrypto.randomUUIDv4;
+          blockNextUuid = false;
+          return Deferred.succeed(terminalUuidStarted, undefined).pipe(
+            Effect.andThen(Deferred.await(terminalUuidRelease)),
+            Effect.andThen(nodeCrypto.randomUUIDv4),
+          );
+        }),
+      } satisfies Crypto.Crypto;
+      const adapter = yield* makeOpenCodeAdapter(openCodeAdapterTestSettings, {
+        nativeEventLogger: {
+          filePath: "memory://opencode-token-usage-terminal-handoff",
+          write: (record) => {
+            const eventType = (record as { event?: { type?: unknown } }).event?.type;
+            if (blockFirstStepWrite && eventType === "message.part.updated") {
+              blockFirstStepWrite = false;
+              return Deferred.succeed(firstStepWriteStarted, undefined).pipe(
+                Effect.andThen(Deferred.await(firstStepWriteRelease)),
+              );
+            }
+            return Effect.void;
+          },
+          close: () => Effect.void,
+        },
+      }).pipe(Effect.provideService(Crypto.Crypto, gatedCrypto));
+
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "turn.completed"),
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+
+      const firstSend = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "Run the first token handoff turn",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("opencode"),
+            "opencode/kimi-k3",
+          ),
+        })
+        .pipe(Effect.forkChild);
+      firstBusy.resolve({
+        id: "evt-token-handoff-first-busy",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "busy" },
+        },
+      });
+      const firstTurn = yield* Fiber.join(firstSend);
+      const firstPromptMessageId = (runtimeMock.state.promptCalls[0] as { messageID: string })
+        .messageID;
+      firstAssistantMessage.resolve({
+        id: "evt-token-handoff-first-assistant",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: {
+            id: "assistant-token-handoff-first",
+            role: "assistant",
+            parentID: firstPromptMessageId,
+          },
+        },
+      });
+      firstStep.resolve({
+        id: "evt-token-handoff-first-step",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: {
+            id: "step-token-handoff-first",
+            sessionID: "http://127.0.0.1:9999/session",
+            messageID: "assistant-token-handoff-first",
+            type: "step-finish",
+            reason: "stop",
+            cost: 0,
+            tokens: {
+              input: 100,
+              output: 20,
+              reasoning: 5,
+              cache: { read: 40, write: 10 },
+            },
+          },
+        },
+      });
+      yield* Deferred.await(firstStepWriteStarted);
+      blockNextUuid = true;
+      firstIdle.resolve({
+        id: "evt-token-handoff-first-idle",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "idle" },
+        },
+      });
+      yield* Deferred.succeed(firstStepWriteRelease, undefined);
+      yield* Deferred.await(terminalUuidStarted);
+
+      runtimeMock.state.sessionStatus = "busy";
+      const secondTurn = yield* adapter.sendTurn({
+        threadId,
+        input: "Run the second token handoff turn",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode"),
+          "opencode/kimi-k3",
+        ),
+      });
+      NodeAssert.notEqual(secondTurn.turnId, firstTurn.turnId);
+      const secondPromptMessageId = (runtimeMock.state.promptCalls[1] as { messageID: string })
+        .messageID;
+      yield* Deferred.succeed(terminalUuidRelease, undefined);
+
+      secondBusy.resolve({
+        id: "evt-token-handoff-second-busy",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "busy" },
+        },
+      });
+      secondAssistantMessage.resolve({
+        id: "evt-token-handoff-second-assistant",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: {
+            id: "assistant-token-handoff-second",
+            role: "assistant",
+            parentID: secondPromptMessageId,
+          },
+        },
+      });
+      secondStep.resolve({
+        id: "evt-token-handoff-second-step",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: {
+            id: "step-token-handoff-second",
+            sessionID: "http://127.0.0.1:9999/session",
+            messageID: "assistant-token-handoff-second",
+            type: "step-finish",
+            reason: "stop",
+            cost: 0,
+            tokens: {
+              input: 90,
+              output: 13,
+              reasoning: 3,
+              cache: { read: 20, write: 5 },
+            },
+          },
+        },
+      });
+      secondIdle.resolve({
+        id: "evt-token-handoff-second-idle",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "idle" },
+        },
+      });
+
+      const completed = Array.from(
+        yield* Fiber.join(completedFiber).pipe(Effect.timeout("1 second")),
+      );
+      NodeAssert.deepStrictEqual(
+        completed.map((event) =>
+          event.type === "turn.completed" ? event.payload.tokenUsage : undefined,
+        ),
+        [
+          {
+            usageStatus: "complete",
+            usageScope: "main_agent",
+            inputTokens: 150,
+            cachedInputTokens: 40,
+            cacheCreationTokens: 10,
+            outputTokens: 25,
+            reasoningTokens: 5,
+            hasSubagents: false,
+          },
+          {
+            usageStatus: "complete",
+            usageScope: "main_agent",
+            inputTokens: 115,
+            cachedInputTokens: 20,
+            cacheCreationTokens: 5,
+            outputTokens: 16,
+            reasoningTokens: 3,
+            hasSubagents: false,
+          },
+        ],
+      );
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("ignores a stale admission status response after the next turn starts", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-stale-admission-status-after-stop");
+      const idleEvent = promiseWithResolvers<unknown>();
+      const userMessageEvent = promiseWithResolvers<unknown>();
+      const staleStatusStarted = promiseWithResolvers<void>();
+      const staleStatusRelease = promiseWithResolvers<void>();
+      const staleStatusReturned = promiseWithResolvers<void>();
+      const activePromptStarted = promiseWithResolvers<void>();
+      const activePromptRelease = promiseWithResolvers<void>();
+      runtimeMock.state.autoPromptEcho = false;
+      runtimeMock.state.subscribedEvents = [idleEvent.promise, userMessageEvent.promise];
+      runtimeMock.state.sessionStatusImplementation = async () => {
+        if (runtimeMock.state.sessionStatusCalls === 1) {
+          staleStatusStarted.resolve(undefined);
+          await staleStatusRelease.promise;
+          staleStatusReturned.resolve(undefined);
+          return {
+            data: { "http://127.0.0.1:9999/session": { type: "busy" as const } },
+          };
+        }
+        return { data: {} };
+      };
+      runtimeMock.state.promptAsyncImplementation = async () => {
+        if (runtimeMock.state.promptCalls.length === 2) {
+          activePromptStarted.resolve(undefined);
+          await activePromptRelease.promise;
+        }
+      };
+
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+      const stoppedTurn = yield* adapter.sendTurn({
+        threadId,
+        input: "Stop while status is pending",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode"),
+          "opencode/kimi-k3",
+        ),
+      });
+      yield* Effect.promise(() => staleStatusStarted.promise);
+      yield* adapter.interruptTurn(threadId, stoppedTurn.turnId);
+
+      const activeTurnFiber = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "Start while the old status is pending",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("opencode"),
+            "opencode/kimi-k3",
+          ),
+        })
+        .pipe(Effect.forkChild);
+      yield* Effect.promise(() => activePromptStarted.promise);
+      const activeMessageId = (runtimeMock.state.promptCalls.at(-1) as { messageID: string })
+        .messageID;
+
+      staleStatusRelease.resolve(undefined);
+      yield* Effect.promise(() => staleStatusReturned.promise);
+      for (let index = 0; index < 2; index += 1) {
+        yield* Effect.yieldNow;
+      }
+      idleEvent.resolve({
+        id: "evt-idle-after-stale-admission-status",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "idle" },
+        },
+      });
+      for (let index = 0; index < 4; index += 1) {
+        yield* Effect.yieldNow;
+      }
+      NodeAssert.equal(activeTurnFiber.pollUnsafe(), undefined);
+      NodeAssert.equal(completedFiber.pollUnsafe(), undefined);
+      const sessionsBeforeAcceptance = yield* adapter.listSessions();
+      const sessionBeforeAcceptance = sessionsBeforeAcceptance.find(
+        (candidate) => candidate.threadId === threadId,
+      );
+      NodeAssert.equal(sessionBeforeAcceptance?.status, "running");
+      NodeAssert.notEqual(sessionBeforeAcceptance?.activeTurnId, stoppedTurn.turnId);
+
+      userMessageEvent.resolve({
+        id: "evt-user-after-stale-admission-status",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: { id: activeMessageId, role: "user" },
+        },
+      });
+      yield* Effect.yieldNow;
+      activePromptRelease.resolve(undefined);
+      const activeTurn = yield* Fiber.join(activeTurnFiber);
+      yield* advanceTestClock(250);
+
+      const completed = Option.getOrUndefined(
+        yield* Fiber.join(completedFiber).pipe(Effect.timeout("1 second")),
+      );
+      NodeAssert.equal(completed?.turnId, activeTurn.turnId);
+      const sessions = yield* adapter.listSessions();
+      const session = sessions.find((candidate) => candidate.threadId === threadId);
+      NodeAssert.equal(session?.status, "ready");
+      NodeAssert.equal(session?.activeTurnId, undefined);
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("ignores a late prior-turn step after the next prompt is admitted", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-token-usage-late-prior-step");
+      const firstBusy = promiseWithResolvers<unknown>();
+      const firstAssistant = promiseWithResolvers<unknown>();
+      const secondBusy = promiseWithResolvers<unknown>();
+      const secondAssistant = promiseWithResolvers<unknown>();
+      const lateFirstStep = promiseWithResolvers<unknown>();
+      const secondStep = promiseWithResolvers<unknown>();
+      const secondIdle = promiseWithResolvers<unknown>();
+      runtimeMock.state.subscribedEvents = [
+        firstBusy.promise,
+        firstAssistant.promise,
+        secondBusy.promise,
+        secondAssistant.promise,
+        lateFirstStep.promise,
+        secondStep.promise,
+        secondIdle.promise,
+      ];
+
+      const terminalsFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter(
+          (event) =>
+            event.threadId === threadId &&
+            (event.type === "turn.aborted" || event.type === "turn.completed"),
+        ),
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+
+      const firstSend = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "Start the interrupted turn",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("opencode"),
+            "opencode/kimi-k3",
+          ),
+        })
+        .pipe(Effect.forkChild);
+      firstBusy.resolve({
+        id: "evt-token-late-first-busy",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "busy" },
+        },
+      });
+      yield* Fiber.join(firstSend);
+      const firstPromptMessageId = (runtimeMock.state.promptCalls[0] as { messageID: string })
+        .messageID;
+      firstAssistant.resolve({
+        id: "evt-token-late-first-assistant",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: {
+            id: "assistant-token-late-first",
+            role: "assistant",
+            parentID: firstPromptMessageId,
+          },
+        },
+      });
+      yield* Effect.yieldNow;
+      yield* adapter.interruptTurn(threadId);
+
+      const secondSend = yield* adapter
+        .sendTurn({
+          threadId,
+          input: "Start the next turn",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("opencode"),
+            "opencode/kimi-k3",
+          ),
+        })
+        .pipe(Effect.forkChild);
+      while (runtimeMock.state.promptCalls.length < 2) {
+        yield* Effect.yieldNow;
+      }
+      secondBusy.resolve({
+        id: "evt-token-late-second-busy",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "busy" },
+        },
+      });
+      yield* Fiber.join(secondSend);
+      const secondPromptMessageId = (runtimeMock.state.promptCalls[1] as { messageID: string })
+        .messageID;
+      secondAssistant.resolve({
+        id: "evt-token-late-second-assistant",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: {
+            id: "assistant-token-late-second",
+            role: "assistant",
+            parentID: secondPromptMessageId,
+          },
+        },
+      });
+      lateFirstStep.resolve({
+        id: "evt-token-late-first-step",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: {
+            id: "step-token-late-first",
+            sessionID: "http://127.0.0.1:9999/session",
+            messageID: "assistant-token-late-first",
+            type: "step-finish",
+            reason: "stop",
+            cost: 0,
+            tokens: {
+              input: 1_000,
+              output: 1_000,
+              reasoning: 0,
+              cache: { read: 0, write: 0 },
+            },
+          },
+        },
+      });
+      secondStep.resolve({
+        id: "evt-token-late-second-step",
+        type: "message.part.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          part: {
+            id: "step-token-late-second",
+            sessionID: "http://127.0.0.1:9999/session",
+            messageID: "assistant-token-late-second",
+            type: "step-finish",
+            reason: "stop",
+            cost: 0,
+            tokens: {
+              input: 40,
+              output: 10,
+              reasoning: 2,
+              cache: { read: 5, write: 1 },
+            },
+          },
+        },
+      });
+      secondIdle.resolve({
+        id: "evt-token-late-second-idle",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "idle" },
+        },
+      });
+
+      const terminals = Array.from(
+        yield* Fiber.join(terminalsFiber).pipe(Effect.timeout("1 second")),
+      );
+      const secondCompleted = terminals.find((event) => event.type === "turn.completed");
+      NodeAssert.equal(secondCompleted?.type, "turn.completed");
+      if (secondCompleted?.type === "turn.completed") {
+        NodeAssert.deepStrictEqual(secondCompleted.payload.tokenUsage, {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 46,
+          cachedInputTokens: 5,
+          cacheCreationTokens: 1,
+          outputTokens: 12,
+          reasoningTokens: 2,
+          hasSubagents: false,
+        });
+      }
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("reconciles a sole idle when the matching prompt echo arrives later", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-idle-before-delayed-echo");
+      const idleEvent = promiseWithResolvers<unknown>();
+      const userMessageEvent = promiseWithResolvers<unknown>();
+      runtimeMock.state.autoPromptEcho = false;
+      runtimeMock.state.subscribedEvents = [idleEvent.promise, userMessageEvent.promise];
+      runtimeMock.state.sessionStatusImplementation = async () => ({ data: {} });
+
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+      const turn = yield* adapter.sendTurn({
+        threadId,
+        input: "Finish before the echo arrives",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode"),
+          "opencode/kimi-k3",
+        ),
+      });
+      const messageId = (runtimeMock.state.promptCalls[0] as { messageID?: string }).messageID;
+      idleEvent.resolve({
+        id: "evt-idle-before-delayed-echo",
+        type: "session.status",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          status: { type: "idle" },
+        },
+      });
+      userMessageEvent.resolve({
+        id: "evt-delayed-matching-echo",
+        type: "message.updated",
+        properties: {
+          sessionID: "http://127.0.0.1:9999/session",
+          info: { id: messageId, role: "user" },
+        },
+      });
+      yield* advanceTestClock(250);
+
+      const completed = Option.getOrUndefined(
+        yield* Fiber.join(completedFiber).pipe(Effect.timeout("1 second")),
+      );
+      NodeAssert.equal(completed?.turnId, turn.turnId);
+      const sessions = yield* adapter.listSessions();
+      const session = sessions.find((candidate) => candidate.threadId === threadId);
+      NodeAssert.equal(session?.status, "ready");
+      NodeAssert.equal(session?.activeTurnId, undefined);
+
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("reconciles the only idle after a stopped turn when the prompt echo is missing", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-idle-only-without-echo-after-stop");
+      const idleEvent = promiseWithResolvers<unknown>();
+      runtimeMock.state.autoPromptEcho = false;
+      runtimeMock.state.subscribedEvents = [idleEvent.promise];
+      runtimeMock.state.sessionStatusImplementation = async () => ({ data: {} });
+      runtimeMock.state.promptAsyncImplementation = async () => {
+        const prompt = runtimeMock.state.promptCalls.at(-1) as { messageID?: string } | undefined;
+        if (prompt?.messageID) {
+          runtimeMock.state.messages.push({
+            info: { id: prompt.messageID, role: "user" },
+            parts: [],
+          });
+        }
+      };
+
+      yield* adapter.startSession({
         provider: ProviderDriverKind.make("opencode"),
         threadId,
         runtimeMode: "full-access",
@@ -2566,13 +3383,418 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
           status: { type: "idle" },
         },
       });
-      steerRelease.resolve(undefined);
-      NodeAssert.equal(Exit.isFailure(yield* Fiber.join(steerFiber)), true);
-
-      const completed = Option.getOrUndefined(
-        yield* Fiber.join(completedFiber).pipe(Effect.timeout("1 second")),
+      steerRelease.resolve(undefined);
+      NodeAssert.equal(Exit.isFailure(yield* Fiber.join(steerFiber)), true);
+
+      const completed = Option.getOrUndefined(
+        yield* Fiber.join(completedFiber).pipe(Effect.timeout("1 second")),
+      );
+      NodeAssert.equal(completed?.turnId, activeTurn.turnId);
+    }),
+  );
+
+  it.effect.each([
+    { permission: "external_directory", decision: "accept", reply: "once" },
+    { permission: "doom_loop", decision: "acceptForSession", reply: "always" },
+    { permission: "todowrite", decision: "decline", reply: "reject" },
+    { permission: "webfetch", decision: "cancel", reply: "reject" },
+    { permission: "custom_tool", decision: "accept", reply: "once" },
+  ] as const)(
+    "shows $permission approval and resolves its $decision reply without SSE",
+    ({ permission, decision, reply }) =>
+      Effect.gen(function* () {
+        const adapter = yield* OpenCodeAdapter;
+        const threadId = asThreadId(`thread-permission-${permission}`);
+        const request = {
+          ...permissionRequest(`per_${permission}`, "http://127.0.0.1:9999/session"),
+          permission,
+          patterns: ["*"],
+        };
+        runtimeMock.state.subscribedEvents = [
+          {
+            id: "evt-permission",
+            type: "permission.asked",
+            properties: request,
+          } satisfies OpenCodeEvent,
+        ];
+        const openedFiber = yield* adapter.streamEvents.pipe(
+          Stream.filter((event) => event.threadId === threadId && event.type === "request.opened"),
+          Stream.runHead,
+          Effect.forkChild,
+        );
+        yield* adapter.startSession({
+          provider: ProviderDriverKind.make("opencode"),
+          threadId,
+          runtimeMode: "approval-required",
+        });
+        const opened = Option.getOrThrow(yield* Fiber.join(openedFiber));
+        NodeAssert.ok(opened.type === "request.opened");
+        NodeAssert.equal(opened.payload.requestType, "command_execution_approval");
+        NodeAssert.equal(opened.payload.detail, permission.replaceAll("_", " "));
+        NodeAssert.deepEqual(
+          opened.payload.options?.map((option) => option.label),
+          ["Allow once", "Allow for workspace", "Deny"],
+        );
+        const resolvedFiber = yield* adapter.streamEvents.pipe(
+          Stream.filter(
+            (event) => event.threadId === threadId && event.type === "request.resolved",
+          ),
+          Stream.runHead,
+          Effect.forkChild,
+        );
+        yield* adapter.respondToRequest(threadId, ApprovalRequestId.make(request.id), decision);
+        const resolved = Option.getOrThrow(yield* Fiber.join(resolvedFiber));
+        NodeAssert.equal(resolved.requestId, request.id);
+        yield* adapter.respondToRequest(threadId, ApprovalRequestId.make(request.id), decision);
+        NodeAssert.deepEqual(runtimeMock.state.permissionReplyCalls, [
+          { requestID: request.id, reply },
+        ]);
+        yield* adapter.stopSession(threadId);
+      }),
+  );
+
+  it.effect("keeps a permission reply retryable after its HTTP request times out", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-permission-timeout");
+      const request = permissionRequest("per_timeout", "http://127.0.0.1:9999/session");
+      const replyStarted = promiseWithResolvers<void>();
+      runtimeMock.state.permissionReplyImplementation = async () => {
+        replyStarted.resolve(undefined);
+        await new Promise<void>(() => {});
+      };
+      runtimeMock.state.subscribedEvents = [
+        { id: "evt-ask", type: "permission.asked", properties: request },
+      ];
+      const openedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "request.opened"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "approval-required",
+      });
+      yield* Fiber.join(openedFiber);
+      const replyFiber = yield* adapter
+        .respondToRequest(threadId, ApprovalRequestId.make(request.id), "accept")
+        .pipe(Effect.exit, Effect.forkChild);
+      yield* Effect.promise(() => replyStarted.promise);
+      yield* Effect.yieldNow;
+      yield* advanceTestClock(10_000);
+      NodeAssert.equal(Exit.isFailure(yield* Fiber.join(replyFiber)), true);
+      NodeAssert.equal(runtimeMock.state.permissionReplySignals[0]?.aborted, true);
+      runtimeMock.state.permissionReplyImplementation = null;
+      const resolvedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "request.resolved"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      yield* adapter.respondToRequest(threadId, ApprovalRequestId.make(request.id), "accept");
+      NodeAssert.equal(Option.getOrThrow(yield* Fiber.join(resolvedFiber)).requestId, request.id);
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("keeps a recovering permission retryable until its native request is loaded", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-permission-recovering");
+      const request = permissionRequest("per_recovering", "ses_resumed");
+      const listStarted = promiseWithResolvers<void>();
+      const releaseList = promiseWithResolvers<PermissionRequest[]>();
+      runtimeMock.state.permissionListImplementation = async () => {
+        listStarted.resolve(undefined);
+        return await releaseList.promise;
+      };
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "approval-required",
+        resumeCursor: { schemaVersion: 1, sessionId: request.sessionID },
+      });
+      yield* Effect.promise(() => listStarted.promise);
+      const reply = yield* adapter
+        .respondToRequest(threadId, ApprovalRequestId.make(request.id), "accept")
+        .pipe(Effect.result);
+      NodeAssert.equal(reply._tag, "Failure");
+      if (reply._tag === "Failure" && reply.failure._tag === "ProviderAdapterRequestError") {
+        NodeAssert.match(reply.failure.detail, /still loading/);
+      }
+      const openedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "request.opened"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      releaseList.resolve([request]);
+      yield* Fiber.join(openedFiber);
+      yield* adapter.respondToRequest(threadId, ApprovalRequestId.make(request.id), "accept");
+      NodeAssert.deepEqual(runtimeMock.state.permissionReplyCalls, [
+        { requestID: request.id, reply: "once" },
+      ]);
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("closes missing permissions and questions after reconnect", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-missing-requests");
+      const sessionID = "http://127.0.0.1:9999/session";
+      const reconnect = promiseWithResolvers<unknown>();
+      runtimeMock.state.subscribedEvents = [
+        {
+          id: "evt-permission",
+          type: "permission.asked",
+          properties: permissionRequest("per_missing", sessionID),
+        },
+        {
+          id: "evt-question",
+          type: "question.asked",
+          properties: questionRequest("que_missing", sessionID),
+        },
+        reconnect.promise,
+      ];
+      const openedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter(
+          (event) =>
+            event.threadId === threadId &&
+            (event.type === "request.opened" || event.type === "user-input.requested"),
+        ),
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "approval-required",
+      });
+      yield* Fiber.join(openedFiber);
+      const resolvedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter(
+          (event) =>
+            event.threadId === threadId &&
+            (event.type === "request.resolved" || event.type === "user-input.resolved"),
+        ),
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      runtimeMock.state.pendingPermissions = [];
+      runtimeMock.state.pendingQuestions = [];
+      reconnect.resolve({ id: "evt-reconnected", type: "server.connected", properties: {} });
+      const resolved = yield* Fiber.join(resolvedFiber);
+      NodeAssert.deepEqual(
+        resolved.map((event) => event.requestId),
+        ["per_missing", "que_missing"],
+      );
+      NodeAssert.deepEqual(runtimeMock.state.permissionReplyCalls, []);
+      NodeAssert.deepEqual(runtimeMock.state.questionReplyCalls, []);
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("closes pending requests after Stop and ignores late requests from that turn", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-stop-requests");
+      const sessionID = "http://127.0.0.1:9999/session";
+      const startRequests = promiseWithResolvers<unknown>();
+      const lateRequests = promiseWithResolvers<unknown>();
+      runtimeMock.state.subscribedEvents = [
+        startRequests.promise,
+        {
+          id: "evt-question",
+          type: "question.asked",
+          properties: questionRequest("que_stop", sessionID),
+        },
+        lateRequests.promise,
+        {
+          id: "evt-late-question",
+          type: "question.asked",
+          properties: questionRequest("que_late", sessionID),
+        },
+        { id: "evt-drained", type: "session.compacted", properties: { sessionID } },
+      ];
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "approval-required",
+      });
+      const turn = yield* adapter.sendTurn({
+        threadId,
+        input: "Work",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode"),
+          "opencode/kimi-k3",
+        ),
+      });
+      const openedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter(
+          (event) =>
+            event.threadId === threadId &&
+            (event.type === "request.opened" || event.type === "user-input.requested"),
+        ),
+        Stream.take(2),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      startRequests.resolve({
+        id: "evt-permission",
+        type: "permission.asked",
+        properties: permissionRequest("per_stop", sessionID),
+      });
+      yield* Fiber.join(openedFiber);
+      const stoppedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId),
+        Stream.takeUntil((event) => event.type === "turn.aborted"),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      yield* adapter.interruptTurn(threadId, turn.turnId);
+      const stopped = yield* Fiber.join(stoppedFiber);
+      NodeAssert.deepEqual(
+        stopped.map((event) => event.type),
+        ["request.resolved", "user-input.resolved", "turn.aborted"],
+      );
+      const lateFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId),
+        Stream.takeUntil((event) => event.type === "thread.state.changed"),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      lateRequests.resolve({
+        id: "evt-late-permission",
+        type: "permission.asked",
+        properties: permissionRequest("per_late", sessionID),
+      });
+      const late = yield* Fiber.join(lateFiber);
+      NodeAssert.deepEqual(
+        late.map((event) => event.type),
+        ["thread.state.changed"],
+      );
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("keeps progress live during automatic approval and never reopens a finished turn", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-auto-approval-progress");
+      const sessionID = "http://127.0.0.1:9999/session";
+      const ask = promiseWithResolvers<unknown>();
+      const idle = promiseWithResolvers<unknown>();
+      const replyStarted = promiseWithResolvers<void>();
+      const releaseReply = promiseWithResolvers<void>();
+      runtimeMock.state.permissionReplyImplementation = async () => {
+        replyStarted.resolve(undefined);
+        await releaseReply.promise;
+        throw new Error("reply response lost");
+      };
+      runtimeMock.state.subscribedEvents = [ask.promise, idle.promise];
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+      yield* adapter.sendTurn({
+        threadId,
+        input: "Work",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode"),
+          "opencode/kimi-k3",
+        ),
+      });
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId),
+        Stream.takeUntil((event) => event.type === "turn.completed"),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      ask.resolve({
+        id: "evt-ask",
+        type: "permission.asked",
+        properties: permissionRequest("per_slow_auto", sessionID),
+      });
+      yield* Effect.promise(() => replyStarted.promise);
+      idle.resolve({
+        id: "evt-idle",
+        type: "session.status",
+        properties: { sessionID, status: { type: "idle" } },
+      });
+      const completed = yield* Fiber.join(completedFiber);
+      NodeAssert.equal(
+        completed.some((event) => event.type === "request.opened"),
+        false,
+      );
+      const remainingFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId),
+        Stream.takeUntil((event) => event.type === "session.exited"),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      releaseReply.resolve(undefined);
+      yield* advanceTestClock(10_000);
+      yield* adapter.stopSession(threadId);
+      const remaining = yield* Fiber.join(remainingFiber);
+      NodeAssert.equal(
+        remaining.some((event) => event.type === "request.opened"),
+        false,
+      );
+    }),
+  );
+
+  it.effect("keeps automatic approval fallback available after a steer", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-auto-approval-steer");
+      const ask = promiseWithResolvers<unknown>();
+      const replyStarted = promiseWithResolvers<void>();
+      const releaseReply = promiseWithResolvers<void>();
+      runtimeMock.state.sessionStatus = "busy";
+      runtimeMock.state.permissionReplyImplementation = async () => {
+        replyStarted.resolve(undefined);
+        await releaseReply.promise;
+        throw new Error("reply failed");
+      };
+      runtimeMock.state.subscribedEvents = [ask.promise];
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+      const modelSelection = createModelSelection(
+        ProviderInstanceId.make("opencode"),
+        "opencode/kimi-k3",
       );
-      NodeAssert.equal(completed?.turnId, activeTurn.turnId);
+      const turn = yield* adapter.sendTurn({ threadId, input: "Work", modelSelection });
+      ask.resolve({
+        id: "evt-ask",
+        type: "permission.asked",
+        properties: permissionRequest("per_steer_auto", "http://127.0.0.1:9999/session"),
+      });
+      yield* Effect.promise(() => replyStarted.promise);
+      const steered = yield* adapter.sendTurn({
+        threadId,
+        input: "Keep the change small",
+        modelSelection,
+      });
+      NodeAssert.equal(steered.turnId, turn.turnId);
+      const openedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "request.opened"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      releaseReply.resolve(undefined);
+      NodeAssert.equal(
+        Option.getOrThrow(yield* Fiber.join(openedFiber)).requestId,
+        "per_steer_auto",
+      );
+      runtimeMock.state.permissionReplyImplementation = null;
+      yield* adapter.respondToRequest(threadId, ApprovalRequestId.make("per_steer_auto"), "accept");
+      yield* adapter.stopSession(threadId);
     }),
   );
 
@@ -2691,6 +3913,9 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
       Effect.gen(function* () {
         const adapter = yield* OpenCodeAdapter;
         const threadId = asThreadId(`thread-full-access-${requestId}`);
+        const replyStarted = promiseWithResolvers<void>();
+        runtimeMock.state.permissionReplyImplementation = async () =>
+          replyStarted.resolve(undefined);
         runtimeMock.state.subscribedEvents = [
           {
             id: "evt-child-created",
@@ -2709,11 +3934,11 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
             type: "permission.asked",
             properties: { id: requestId, sessionID, permission, patterns, metadata: {}, always },
           },
-          {
+          replyStarted.promise.then(() => ({
             id: "evt-permission-replied",
             type: "permission.replied",
             properties: { sessionID, requestID: requestId, reply: "once" },
-          },
+          })),
           // The suppressed ask emits nothing, so an empty question serves as a
           // sentinel that closes the collected stream once the pump is past it.
           {
@@ -3000,53 +4225,68 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     }),
   );
 
-  it.effect("retries ancestry for one live child request after a transient failure", () =>
-    Effect.gen(function* () {
-      const adapter = yield* OpenCodeAdapter;
-      const threadId = asThreadId("thread-child-request-ancestry-retry");
-      const parentId = "http://127.0.0.1:9999/session";
-      const ancestryAttempted = promiseWithResolvers<void>();
-      runtimeMock.state.sessionParentById.set("ses_existing_child", parentId);
-      runtimeMock.state.transientErrorSessionIds.add("ses_existing_child");
-      runtimeMock.state.sessionGetObserved = (sessionID) => {
-        if (sessionID === "ses_existing_child") {
-          ancestryAttempted.resolve(undefined);
+  it.effect.each(["failure", "timeout"] as const)(
+    "retries ancestry for a child request after a transient %s",
+    (lookupFailure) =>
+      Effect.gen(function* () {
+        const adapter = yield* OpenCodeAdapter;
+        const threadId = asThreadId(`thread-child-request-ancestry-retry-${lookupFailure}`);
+        const parentId = "http://127.0.0.1:9999/session";
+        const ancestryAttempted = promiseWithResolvers<void>();
+        runtimeMock.state.sessionParentById.set("ses_existing_child", parentId);
+        runtimeMock.state.transientErrorSessionIds.add("ses_existing_child");
+        let lookupSignal: AbortSignal | undefined;
+        if (lookupFailure === "timeout") {
+          runtimeMock.state.sessionGetImplementation = async (_sessionID, signal) => {
+            lookupSignal = signal;
+            await new Promise<void>(() => {});
+          };
         }
-      };
-      runtimeMock.state.subscribedEvents = [
-        {
-          id: "evt-existing-child-permission",
-          type: "permission.asked",
-          properties: permissionRequest("per_retry", "ses_existing_child"),
-        },
-      ];
+        runtimeMock.state.sessionGetObserved = (sessionID) => {
+          if (sessionID === "ses_existing_child") {
+            ancestryAttempted.resolve(undefined);
+          }
+        };
+        runtimeMock.state.subscribedEvents = [
+          {
+            id: "evt-existing-child-permission",
+            type: "permission.asked",
+            properties: permissionRequest("per_retry", "ses_existing_child"),
+          },
+        ];
 
-      const eventsFiber = yield* adapter.streamEvents.pipe(
-        Stream.filter(
-          (event) =>
-            event.threadId === threadId &&
-            (event.type === "runtime.warning" || event.type === "request.opened"),
-        ),
-        Stream.take(2),
-        Stream.runCollect,
-        Effect.forkChild,
-      );
-      yield* adapter.startSession({
-        provider: ProviderDriverKind.make("opencode"),
-        threadId,
-        runtimeMode: "approval-required",
-      });
-      yield* Effect.promise(() => ancestryAttempted.promise);
-      runtimeMock.state.transientErrorSessionIds.delete("ses_existing_child");
-      yield* advanceTestClock(250);
+        const eventsFiber = yield* adapter.streamEvents.pipe(
+          Stream.filter(
+            (event) =>
+              event.threadId === threadId &&
+              (event.type === "runtime.warning" || event.type === "request.opened"),
+          ),
+          Stream.take(2),
+          Stream.runCollect,
+          Effect.forkChild,
+        );
+        yield* adapter.startSession({
+          provider: ProviderDriverKind.make("opencode"),
+          threadId,
+          runtimeMode: "approval-required",
+        });
+        yield* Effect.promise(() => ancestryAttempted.promise);
+        if (lookupFailure === "timeout") {
+          yield* Effect.yieldNow;
+          yield* advanceTestClock(10_000);
+          NodeAssert.equal(lookupSignal?.aborted, true);
+          runtimeMock.state.sessionGetImplementation = null;
+        }
+        runtimeMock.state.transientErrorSessionIds.delete("ses_existing_child");
+        yield* advanceTestClock(250);
 
-      const events = Array.from(yield* Fiber.join(eventsFiber).pipe(Effect.timeout("1 second")));
-      NodeAssert.deepEqual(
-        events.map((event) => event.type),
-        ["runtime.warning", "request.opened"],
-      );
-      yield* adapter.respondToRequest(threadId, ApprovalRequestId.make("per_retry"), "accept");
-    }),
+        const events = Array.from(yield* Fiber.join(eventsFiber).pipe(Effect.timeout("1 second")));
+        NodeAssert.deepEqual(
+          events.map((event) => event.type),
+          ["runtime.warning", "request.opened"],
+        );
+        yield* adapter.respondToRequest(threadId, ApprovalRequestId.make("per_retry"), "accept");
+      }),
   );
 
   it.effect("does not resurrect a recovered child request after its live reply", () =>
@@ -3101,7 +4341,8 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
       const response = yield* Effect.exit(
         adapter.respondToRequest(threadId, ApprovalRequestId.make(stale.id), "accept"),
       );
-      NodeAssert.equal(Exit.isFailure(response), true);
+      NodeAssert.equal(Exit.isSuccess(response), true);
+      NodeAssert.deepEqual(runtimeMock.state.permissionReplyCalls, []);
     }),
   );
 
@@ -3153,7 +4394,8 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
       const response = yield* Effect.exit(
         adapter.respondToRequest(threadId, ApprovalRequestId.make(request.id), "accept"),
       );
-      NodeAssert.equal(Exit.isFailure(response), true);
+      NodeAssert.equal(Exit.isSuccess(response), true);
+      NodeAssert.deepEqual(runtimeMock.state.permissionReplyCalls, []);
     }),
   );
 
@@ -4927,6 +6169,11 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
 
     return Effect.gen(function* () {
       const adapter = yield* OpenCodeAdapter;
+      const startedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.started"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
       yield* adapter.startSession({
         provider: ProviderDriverKind.make("opencode"),
         threadId: asThreadId("thread-custom-instance"),
@@ -4965,6 +6212,11 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
         }),
         parts: [{ type: "text", text: "Fix it" }],
       });
+      const started = yield* Fiber.join(startedFiber);
+      NodeAssert.equal(started._tag, "Some");
+      if (started._tag === "Some" && started.value.type === "turn.started") {
+        NodeAssert.equal(started.value.payload.effort, undefined);
+      }
     }).pipe(Effect.provide(adapterLayer));
   });
 
@@ -5150,46 +6402,45 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     }),
   );
 
-  it.effect("treats lexically or physically identical directories as the same", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const sameDirectory = (left: string, right: string) =>
-        isSameOpenCodeDirectory(fileSystem, path, left, right);
-
-      // Lexical-only differences (trailing slash, dot segments) short-circuit
-      // without touching the filesystem — the paths need not exist.
-      NodeAssert.equal(yield* sameDirectory("/repo/project/", "/repo/project"), true);
-      NodeAssert.equal(yield* sameDirectory("/repo/nested/../project", "/repo/project"), true);
-      // Nonexistent paths degrade to the lexical comparison instead of failing.
-      NodeAssert.equal(yield* sameDirectory("/repo/project", "/repo/other"), false);
-
-      // A symlinked cwd (the macOS `/tmp` → `/private/tmp` shape) resolves to
-      // the directory it points at, so the two spellings compare equal.
-      const base = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-opencode-dir-" });
-      const real = path.join(base, "real");
-      const link = path.join(base, "link");
-      yield* fileSystem.makeDirectory(real);
-      yield* fileSystem.symlink(real, link);
-      NodeAssert.equal(yield* sameDirectory(link, real), true);
-      NodeAssert.equal(yield* sameDirectory(link, path.join(base, "other")), false);
-    }).pipe(Effect.scoped),
+  it.effect.skipIf(!symlinksSupported)(
+    "treats lexically or physically identical directories as the same",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const sameDirectory = (left: string, right: string) =>
+          isSameOpenCodeDirectory(fileSystem, path, left, right);
+
+        // Lexical-only differences (trailing slash, dot segments) short-circuit
+        // without touching the filesystem — the paths need not exist.
+        NodeAssert.equal(yield* sameDirectory("/repo/project/", "/repo/project"), true);
+        NodeAssert.equal(yield* sameDirectory("/repo/nested/../project", "/repo/project"), true);
+        // Nonexistent paths degrade to the lexical comparison instead of failing.
+        NodeAssert.equal(yield* sameDirectory("/repo/project", "/repo/other"), false);
+
+        // A symlinked cwd (the macOS `/tmp` → `/private/tmp` shape) resolves to
+        // the directory it points at, so the two spellings compare equal.
+        const base = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-opencode-dir-" });
+        const real = path.join(base, "real");
+        const link = path.join(base, "link");
+        yield* fileSystem.makeDirectory(real);
+        yield* fileSystem.symlink(real, link);
+        NodeAssert.equal(yield* sameDirectory(link, real), true);
+        NodeAssert.equal(yield* sameDirectory(link, path.join(base, "other")), false);
+      }).pipe(Effect.scoped),
   );
 
-  it.effect("appends raw assistant text deltas and reconciles part update snapshots", () =>
+  it.effect("reconciles assistant text snapshots", () =>
     Effect.sync(() => {
       const firstUpdate = mergeOpenCodeAssistantText(undefined, "Hello");
-      const overlapDelta = appendOpenCodeAssistantTextDelta(firstUpdate.latestText, "lo world");
-      const secondUpdate = mergeOpenCodeAssistantText(overlapDelta.nextText, "Hellolo world");
       const appendedUpdate = mergeOpenCodeAssistantText("Hello", "Hello world");
       const changedUpdate = mergeOpenCodeAssistantText("Hello world", "Hello there");
       const staleUpdate = mergeOpenCodeAssistantText("Hello world", "Hello");
 
-      NodeAssert.deepEqual(
-        [firstUpdate.deltaToEmit, overlapDelta.deltaToEmit, secondUpdate.deltaToEmit],
-        ["Hello", "lo world", ""],
-      );
-      NodeAssert.equal(secondUpdate.latestText, "Hellolo world");
+      NodeAssert.deepEqual(firstUpdate, {
+        latestText: "Hello",
+        deltaToEmit: "Hello",
+      });
       NodeAssert.deepEqual(appendedUpdate, {
         latestText: "Hello world",
         deltaToEmit: " world",
@@ -5286,6 +6537,376 @@ it.layer(OpenCodeAdapterTestLayer)("OpenCodeAdapterLive", (it) => {
     }),
   );
 
+  it.effect("emits tool lifecycle events before late assistant metadata", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-tool-lifecycle");
+      const sessionID = "http://127.0.0.1:9999/session";
+      const messageID = "msg-tools-before-role";
+      const start = promiseWithResolvers<OpenCodeEvent>();
+      const input = { command: "pwd" };
+      const states = [
+        { status: "pending", input, raw: "" },
+        { status: "running", input, title: "Working directory", time: { start: 1 } },
+        {
+          status: "completed",
+          input,
+          output: "/repo\n",
+          title: "Working directory",
+          metadata: {},
+          time: { start: 1, end: 2 },
+        },
+        { status: "error", input, error: "Command failed", time: { start: 3, end: 4 } },
+      ] satisfies ReadonlyArray<ToolPart["state"]>;
+      runtimeMock.state.subscribedEvents = [
+        start.promise,
+        ...states.map(
+          (state) =>
+            ({
+              id: `evt-tool-${state.status}`,
+              type: "message.part.updated",
+              properties: {
+                sessionID,
+                time: 4,
+                part: {
+                  id: state.status === "error" ? "part-failed" : "part-working",
+                  sessionID,
+                  messageID,
+                  type: "tool",
+                  callID: state.status === "error" ? "call-failed" : "call-working",
+                  tool: "bash",
+                  state,
+                },
+              },
+            }) satisfies OpenCodeEvent,
+        ),
+        {
+          id: "evt-text-before-role",
+          type: "message.part.updated",
+          properties: {
+            sessionID,
+            time: 4,
+            part: {
+              id: "part-late-text",
+              sessionID,
+              messageID,
+              type: "text",
+              text: "Tool results received",
+              time: { start: 4 },
+            },
+          },
+        },
+        {
+          id: "evt-late-assistant-role",
+          type: "message.updated",
+          properties: { sessionID, info: { id: messageID, role: "assistant" } },
+        },
+        {
+          id: "evt-tool-lifecycle-drained",
+          type: "session.compacted",
+          properties: { sessionID },
+        },
+      ];
+      const eventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId),
+        Stream.takeUntil((event) => event.type === "thread.state.changed"),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+      yield* adapter.sendTurn({
+        threadId,
+        input: "Read the working directory",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode"),
+          "opencode/kimi-k3",
+        ),
+      });
+      start.resolve({
+        id: "evt-tool-lifecycle-started",
+        type: "session.status",
+        properties: { sessionID, status: { type: "busy" } },
+      });
+      const events = yield* Fiber.join(eventsFiber);
+      const tools = events.filter(
+        (event) =>
+          event.type === "item.started" ||
+          event.type === "item.updated" ||
+          event.type === "item.completed",
+      );
+      NodeAssert.deepEqual(
+        tools.map((event) => [event.type, event.itemId, event.payload.status]),
+        [
+          ["item.started", "call-working", "inProgress"],
+          ["item.updated", "call-working", "inProgress"],
+          ["item.completed", "call-working", "completed"],
+          ["item.completed", "call-failed", "failed"],
+        ],
+      );
+      NodeAssert.partialDeepStrictEqual(tools[2]?.payload.data, {
+        command: "pwd",
+        result: "/repo\n",
+      });
+      NodeAssert.partialDeepStrictEqual(tools[3]?.payload.data, {
+        command: "pwd",
+        state: { error: "Command failed" },
+      });
+      NodeAssert.deepEqual(
+        events
+          .filter((event) => event.type === "content.delta")
+          .map((event) => event.payload.delta),
+        ["Tool results received"],
+      );
+    }),
+  );
+
+  it.effect("maps native task progress only while a turn is active", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-native-progress");
+      const sessionID = "http://127.0.0.1:9999/session";
+      const startProgress = promiseWithResolvers<OpenCodeEvent>();
+      const finishTurn = promiseWithResolvers<OpenCodeEvent>();
+      const lateProgress = promiseWithResolvers<OpenCodeEvent>();
+      const todos = [
+        { content: "Read files", status: "completed", priority: "high" },
+        { content: "Fix OpenCode", status: "in_progress", priority: "high" },
+        { content: "Run tests", status: "pending", priority: "medium" },
+        { content: "Old task", status: "cancelled", priority: "low" },
+      ];
+      const todoEvent = {
+        id: "evt-todos",
+        type: "todo.updated",
+        properties: { sessionID, todos },
+      } satisfies OpenCodeEvent;
+      runtimeMock.state.subscribedEvents = [
+        startProgress.promise,
+        ...["todowrite", "bash"].map(
+          (tool) =>
+            ({
+              id: `evt-${tool}`,
+              type: "message.part.updated",
+              properties: {
+                sessionID,
+                time: 2,
+                part: {
+                  id: `part-${tool}`,
+                  sessionID,
+                  messageID: "msg-tools",
+                  type: "tool",
+                  callID: `call-${tool}`,
+                  tool,
+                  state: {
+                    status: "completed",
+                    input: tool === "bash" ? { command: "pwd" } : { todos },
+                    output: tool === "bash" ? "/repo\n" : "Tasks updated",
+                    title: tool === "bash" ? "Working directory" : "Tasks updated",
+                    metadata: {},
+                    time: { start: 1, end: 2 },
+                  },
+                },
+              },
+            }) satisfies OpenCodeEvent,
+        ),
+        finishTurn.promise,
+        lateProgress.promise,
+        { id: "evt-progress-drained", type: "session.compacted", properties: { sessionID } },
+      ];
+      const eventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter(
+          (event) =>
+            event.threadId === threadId &&
+            (event.type === "turn.plan.updated" || event.type === "item.completed"),
+        ),
+        Stream.take(3),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+      const turn = yield* adapter.sendTurn({
+        threadId,
+        input: "Work through the task list",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode"),
+          "opencode/kimi-k3",
+        ),
+      });
+      startProgress.resolve(todoEvent);
+      const events = yield* Fiber.join(eventsFiber);
+      const plan = events.find((event) => event.type === "turn.plan.updated");
+      NodeAssert.equal(plan?.turnId, turn.turnId);
+      NodeAssert.deepEqual(plan?.payload.plan, [
+        { step: "Read files", status: "completed" },
+        { step: "Fix OpenCode", status: "inProgress" },
+        { step: "Run tests", status: "pending" },
+      ]);
+      const tools = events.filter((event) => event.type === "item.completed");
+      NodeAssert.equal(tools[0]?.payload.itemType, "dynamic_tool_call");
+      NodeAssert.equal(tools[1]?.payload.title, "Working directory");
+      NodeAssert.partialDeepStrictEqual(tools[1]?.payload.data, {
+        command: "pwd",
+        result: "/repo\n",
+      });
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      finishTurn.resolve({
+        id: "evt-progress-completed",
+        type: "session.status",
+        properties: { sessionID, status: { type: "idle" } },
+      });
+      yield* Fiber.join(completedFiber);
+      const lateEventsFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId),
+        Stream.takeUntil((event) => event.type === "thread.state.changed"),
+        Stream.runCollect,
+        Effect.forkChild,
+      );
+      lateProgress.resolve({ ...todoEvent, id: "evt-late-todos" });
+      NodeAssert.deepEqual(
+        (yield* Fiber.join(lateEventsFiber)).map((event) => event.type),
+        ["thread.state.changed"],
+      );
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect("warns on disconnection and recovers a completion missed during reconnect", () =>
+    Effect.gen(function* () {
+      const adapter = yield* OpenCodeAdapter;
+      const threadId = asThreadId("thread-reconnect-completion");
+      const reconnect = promiseWithResolvers<unknown>();
+      runtimeMock.state.subscribedEvents = [reconnect.promise];
+      runtimeMock.state.sessionStatus = "busy";
+      yield* adapter.startSession({
+        provider: ProviderDriverKind.make("opencode"),
+        threadId,
+        runtimeMode: "full-access",
+      });
+      const turn = yield* adapter.sendTurn({
+        threadId,
+        input: "Work",
+        modelSelection: createModelSelection(
+          ProviderInstanceId.make("opencode"),
+          "opencode/kimi-k3",
+        ),
+      });
+      const warningFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "runtime.warning"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      runtimeMock.state.eventStreamError?.(new Error("socket closed"));
+      const warning = Option.getOrThrow(yield* Fiber.join(warningFiber));
+      NodeAssert.ok(warning.type === "runtime.warning");
+      NodeAssert.equal(warning.payload.message, "OpenCode connection lost. Reconnecting.");
+      const completedFiber = yield* adapter.streamEvents.pipe(
+        Stream.filter((event) => event.threadId === threadId && event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      runtimeMock.state.sessionStatus = "idle";
+      reconnect.resolve({
+        id: "evt-reconnected",
+        type: "server.connected",
+        properties: {},
+      } satisfies OpenCodeEvent);
+      NodeAssert.equal(Option.getOrThrow(yield* Fiber.join(completedFiber)).turnId, turn.turnId);
+      NodeAssert.equal(
+        (yield* adapter.listSessions()).find((session) => session.threadId === threadId)?.status,
+        "ready",
+      );
+      yield* adapter.stopSession(threadId);
+    }),
+  );
+
+  it.effect(
+    "ends a running session on clean stream closure without discarding unresolved permissions",
+    () =>
+      Effect.gen(function* () {
+        const adapter = yield* OpenCodeAdapter;
+        const threadId = asThreadId("thread-stream-closed");
+        const endStream = promiseWithResolvers<unknown>();
+        const request = permissionRequest("per_disconnect", "http://127.0.0.1:9999/session");
+        runtimeMock.state.pendingPermissions = [request];
+        runtimeMock.state.subscribedEvents = [endStream.promise];
+        const openedFiber = yield* adapter.streamEvents.pipe(
+          Stream.filter((event) => event.threadId === threadId && event.type === "request.opened"),
+          Stream.runHead,
+          Effect.forkChild,
+        );
+        const session = yield* adapter.startSession({
+          provider: ProviderDriverKind.make("opencode"),
+          threadId,
+          runtimeMode: "approval-required",
+        });
+        yield* Fiber.join(openedFiber);
+        yield* adapter.sendTurn({
+          threadId,
+          input: "Work",
+          modelSelection: createModelSelection(
+            ProviderInstanceId.make("opencode"),
+            "opencode/kimi-k3",
+          ),
+        });
+        const exitedFiber = yield* adapter.streamEvents.pipe(
+          Stream.filter((event) => event.threadId === threadId),
+          Stream.takeUntil((event) => event.type === "session.exited"),
+          Stream.runCollect,
+          Effect.forkChild,
+        );
+        runtimeMock.state.endEventStream = true;
+        runtimeMock.state.abortImplementation = async () => {
+          throw new Error("server unreachable");
+        };
+        endStream.resolve({
+          id: "evt-busy",
+          type: "session.status",
+          properties: { sessionID: request.sessionID, status: { type: "busy" } },
+        });
+        const exited = yield* Fiber.join(exitedFiber);
+        NodeAssert.equal(
+          exited.some((event) => event.type === "request.resolved"),
+          false,
+        );
+        NodeAssert.match(
+          exited.find((event) => event.type === "runtime.error")?.payload.message ?? "",
+          /event stream ended/,
+        );
+        NodeAssert.equal(yield* adapter.hasSession(threadId), false);
+        runtimeMock.state.endEventStream = false;
+        runtimeMock.state.subscribedEvents = [];
+        runtimeMock.state.abortImplementation = null;
+        const recoveredFiber = yield* adapter.streamEvents.pipe(
+          Stream.filter((event) => event.threadId === threadId && event.type === "request.opened"),
+          Stream.runHead,
+          Effect.forkChild,
+        );
+        yield* adapter.startSession({
+          provider: ProviderDriverKind.make("opencode"),
+          threadId,
+          runtimeMode: "approval-required",
+          resumeCursor: session.resumeCursor,
+        });
+        NodeAssert.equal(
+          Option.getOrThrow(yield* Fiber.join(recoveredFiber)).requestId,
+          request.id,
+        );
+        yield* adapter.respondToRequest(threadId, ApprovalRequestId.make(request.id), "accept");
+        yield* adapter.stopSession(threadId);
+      }),
+  );
+
   it.effect("lets OpenCode own session title generation and emits title metadata updates", () =>
     Effect.gen(function* () {
       const adapter = yield* OpenCodeAdapter;
diff --git a/apps/server/src/provider/Layers/OpenCodeAdapter.ts b/apps/server/src/provider/Layers/OpenCodeAdapter.ts
index e0305236a717..b8aa7d4a9a52 100644
--- a/apps/server/src/provider/Layers/OpenCodeAdapter.ts
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.ts
@@ -9,6 +9,7 @@ import {
   RuntimeRequestId,
   ThreadId,
   type ToolLifecycleItemType,
+  type TurnTokenUsage,
   TurnId,
   type UserInputQuestion,
 } from "@t3tools/contracts";
@@ -338,7 +339,7 @@ interface OpenCodeSessionContext {
   readonly partById: Map<string, Part>;
   readonly emittedTextByPartId: Map<string, string>;
   readonly completedAssistantPartIds: Set<string>;
-  readonly turns: Array<OpenCodeTurnSnapshot>;
+  turnTokenUsage: OpenCodeTurnTokenUsageAccumulator | undefined;
   activeTurnId: TurnId | undefined;
   activeAgent: string | undefined;
   activeVariant: string | undefined;
@@ -369,6 +370,75 @@ interface OpenCodeSessionContext {
   readonly sessionScope: Scope.Closeable;
 }
 
+interface OpenCodeTurnTokenUsageAccumulator {
+  readonly partIds: Set<string>;
+  readonly promptMessageIds: Set<string>;
+  readonly assistantOwnershipByMessageId: Map<string, "owned" | "other" | "unknown">;
+  readonly unresolvedStepPartIds: Set<string>;
+  inputTokens: number;
+  cachedInputTokens: number;
+  cacheCreationTokens: number;
+  outputTokens: number;
+  reasoningTokens: number;
+  complete: boolean;
+  hasSubagents: boolean;
+}
+
+function makeOpenCodeTurnTokenUsageAccumulator(): OpenCodeTurnTokenUsageAccumulator {
+  return {
+    partIds: new Set(),
+    promptMessageIds: new Set(),
+    assistantOwnershipByMessageId: new Map(),
+    unresolvedStepPartIds: new Set(),
+    inputTokens: 0,
+    cachedInputTokens: 0,
+    cacheCreationTokens: 0,
+    outputTokens: 0,
+    reasoningTokens: 0,
+    complete: true,
+    hasSubagents: false,
+  };
+}
+
+function accumulateOpenCodeStepUsage(
+  accumulator: OpenCodeTurnTokenUsageAccumulator,
+  part: Extract<Part, { readonly type: "step-finish" }>,
+): void {
+  if (accumulator.partIds.has(part.id)) return;
+  accumulator.partIds.add(part.id);
+  accumulator.inputTokens += part.tokens.input + part.tokens.cache.read + part.tokens.cache.write;
+  accumulator.cachedInputTokens += part.tokens.cache.read;
+  accumulator.cacheCreationTokens += part.tokens.cache.write;
+  accumulator.outputTokens += part.tokens.output + part.tokens.reasoning;
+  accumulator.reasoningTokens += part.tokens.reasoning;
+}
+
+function takeOpenCodeTurnTokenUsage(
+  context: OpenCodeSessionContext,
+  complete: boolean,
+): TurnTokenUsage {
+  const usage = context.turnTokenUsage;
+  context.turnTokenUsage = undefined;
+  if (!usage || usage.partIds.size === 0) {
+    return {
+      usageStatus: "unavailable",
+      usageScope: "main_agent",
+      hasSubagents: usage?.hasSubagents ?? false,
+    };
+  }
+  return {
+    usageStatus:
+      complete && usage.complete && usage.unresolvedStepPartIds.size === 0 ? "complete" : "partial",
+    usageScope: "main_agent",
+    inputTokens: usage.inputTokens,
+    cachedInputTokens: usage.cachedInputTokens,
+    cacheCreationTokens: usage.cacheCreationTokens,
+    outputTokens: usage.outputTokens,
+    reasoningTokens: Math.min(usage.outputTokens, usage.reasoningTokens),
+    hasSubagents: usage.hasSubagents,
+  };
+}
+
 export interface OpenCodeAdapterLiveOptions {
   readonly instanceId?: ProviderInstanceId;
   readonly environment?: NodeJS.ProcessEnv;
@@ -417,6 +487,9 @@ type EventBaseInput = {
 
 function toToolLifecycleItemType(toolName: string): ToolLifecycleItemType {
   const normalized = toolName.toLowerCase();
+  if (normalized === "todowrite" || normalized === "todoread") {
+    return "dynamic_tool_call";
+  }
   if (normalized.includes("bash") || normalized.includes("command")) {
     return "command_execution";
   }
@@ -449,16 +522,15 @@ function toToolLifecycleItemType(toolName: string): ToolLifecycleItemType {
 
 function mapPermissionToRequestType(
   permission: string,
-): "command_execution_approval" | "file_read_approval" | "file_change_approval" | "unknown" {
+): "command_execution_approval" | "file_read_approval" | "file_change_approval" {
   switch (permission) {
-    case "bash":
-      return "command_execution_approval";
     case "read":
       return "file_read_approval";
     case "edit":
       return "file_change_approval";
     default:
-      return "unknown";
+      // Every OpenCode permission needs an actionable approval in each client.
+      return "command_execution_approval";
   }
 }
 
@@ -474,31 +546,6 @@ function mapPermissionDecision(reply: "once" | "always" | "reject"): string {
   }
 }
 
-function resolveTurnSnapshot(
-  context: OpenCodeSessionContext,
-  turnId: TurnId,
-): OpenCodeTurnSnapshot {
-  const existing = context.turns.find((turn) => turn.id === turnId);
-  if (existing) {
-    return existing;
-  }
-
-  const created: OpenCodeTurnSnapshot = { id: turnId, items: [] };
-  context.turns.push(created);
-  return created;
-}
-
-function appendTurnItem(
-  context: OpenCodeSessionContext,
-  turnId: TurnId | undefined,
-  item: unknown,
-): void {
-  if (!turnId) {
-    return;
-  }
-  resolveTurnSnapshot(context, turnId).items.push(item);
-}
-
 const ensureSessionContext = Effect.fn("ensureSessionContext")(function* (
   sessions: ReadonlyMap<ThreadId, OpenCodeSessionContext>,
   threadId: ThreadId,
@@ -579,7 +626,7 @@ export function mergeOpenCodeAssistantText(
   };
 }
 
-export function appendOpenCodeAssistantTextDelta(
+function appendOpenCodeAssistantTextDelta(
   previousText: string,
   delta: string,
 ): {
@@ -1056,12 +1103,17 @@ export function makeOpenCodeAdapter(
       ) {
         context.pendingIdleReconciliation = undefined;
       }
+      const tokenUsage = takeOpenCodeTurnTokenUsage(context, true);
       context.activeTurnId = undefined;
       context.activeAgent = undefined;
       context.activeVariant = undefined;
       context.interruptedTurnId = undefined;
       context.awaitingBusyAfterInterruption = false;
       context.reconcileIdleStatus = false;
+      for (const requestId of context.autoRepliedRequestIds) {
+        context.emittedTerminalRequestIds.add(requestId);
+      }
+      context.autoRepliedRequestIds.clear();
       applyProviderSessionUpdate(
         context,
         { status: "ready" },
@@ -1071,6 +1123,7 @@ export function makeOpenCodeAdapter(
       if (pendingIdleReconciliation?.fiber) {
         yield* Fiber.interrupt(pendingIdleReconciliation.fiber);
       }
+      yield* schedulePendingRequestRecovery(context);
       yield* emit({
         ...(yield* buildEventBase({
           threadId: context.session.threadId,
@@ -1080,6 +1133,7 @@ export function makeOpenCodeAdapter(
         type: "turn.completed",
         payload: {
           state: "completed",
+          tokenUsage,
         },
       });
     });
@@ -1217,6 +1271,7 @@ export function makeOpenCodeAdapter(
         deleteContextIfCurrent(context);
         return;
       }
+      const tokenUsage = takeOpenCodeTurnTokenUsage(context, false);
       context.promptAdmission = undefined;
       context.activeTurnId = undefined;
       context.activeAgent = undefined;
@@ -1238,6 +1293,7 @@ export function makeOpenCodeAdapter(
         payload: {
           state: "failed",
           errorMessage: detail,
+          tokenUsage,
         },
       });
       yield* emit({
@@ -1415,7 +1471,13 @@ export function makeOpenCodeAdapter(
       if (cancellation) {
         context.cancellation = undefined;
       }
+      let tokenUsage: TurnTokenUsage = {
+        usageStatus: "unavailable",
+        usageScope: "main_agent",
+        hasSubagents: false,
+      };
       if (context.activeTurnId === turnId) {
+        tokenUsage = takeOpenCodeTurnTokenUsage(context, false);
         context.activeTurnId = undefined;
         context.activeAgent = undefined;
         context.activeVariant = undefined;
@@ -1425,6 +1487,7 @@ export function makeOpenCodeAdapter(
           { clearActiveTurnId: true, clearLastError: true },
         );
       }
+      yield* clearPendingOpenCodeRequests(context, { type: "session.abort" });
       yield* emit({
         ...(yield* buildEventBase({
           threadId: context.session.threadId,
@@ -1434,6 +1497,7 @@ export function makeOpenCodeAdapter(
         type: "turn.aborted",
         payload: {
           reason: "Interrupted by user.",
+          tokenUsage,
         },
       });
       if (cancellation) {
@@ -1568,6 +1632,16 @@ export function makeOpenCodeAdapter(
       }
     });
 
+    // Records a child session of this thread. A child seen during a live turn
+    // means that turn used subagents, whether the relation came from a
+    // `session.created` event or a later ancestry lookup after reconnect.
+    const addRelatedOpenCodeSession = (context: OpenCodeSessionContext, sessionId: string) => {
+      context.relatedSessionIds.add(sessionId);
+      if (context.activeTurnId && context.turnTokenUsage) {
+        context.turnTokenUsage.hasSubagents = true;
+      }
+    };
+
     const isRelatedOpenCodeSession = Effect.fn("isRelatedOpenCodeSession")(function* (
       context: OpenCodeSessionContext,
       candidateSessionId: string,
@@ -1578,7 +1652,19 @@ export function makeOpenCodeAdapter(
 
       const seen = new Set<string>();
       const getSession = (sessionID: string) =>
-        runOpenCodeSdk("session.get", () => context.client.session.get({ sessionID })).pipe(
+        runOpenCodeSdk("session.get", (signal) =>
+          context.client.session.get({ sessionID }, { signal }),
+        ).pipe(
+          Effect.timeoutOrElse({
+            duration: "10 seconds",
+            orElse: () =>
+              Effect.fail(
+                new OpenCodeRuntimeError({
+                  operation: "session.get",
+                  detail: "OpenCode session ancestry lookup did not complete within 10 seconds.",
+                }),
+              ),
+          }),
           Effect.catchIf(
             (cause) => isOpenCodeNotFound(cause),
             () => Effect.succeed(undefined),
@@ -1587,7 +1673,7 @@ export function makeOpenCodeAdapter(
       let sessionId: string | undefined = candidateSessionId;
       for (let depth = 0; sessionId !== undefined && depth < 32; depth += 1) {
         if (context.relatedSessionIds.has(sessionId)) {
-          context.relatedSessionIds.add(candidateSessionId);
+          addRelatedOpenCodeSession(context, candidateSessionId);
           return true;
         }
         if (seen.has(sessionId)) {
@@ -1610,6 +1696,52 @@ export function makeOpenCodeAdapter(
       return false;
     });
 
+    const openPermissionRequest = Effect.fn("openPermissionRequest")(function* (
+      context: OpenCodeSessionContext,
+      request: PermissionRequest,
+      raw: unknown,
+    ) {
+      const base = yield* buildEventBase({
+        threadId: context.session.threadId,
+        turnId: context.activeTurnId,
+        requestId: request.id,
+        raw,
+      });
+      const stopped = yield* Ref.get(context.stopped);
+      if (
+        stopped ||
+        context.emittedTerminalRequestIds.has(request.id) ||
+        context.pendingPermissions.has(request.id)
+      ) {
+        return;
+      }
+      const patterns = request.patterns.filter((pattern) => pattern !== "*");
+      const detail =
+        request.permission === "bash" && patterns.length > 0
+          ? patterns.join("\n")
+          : [request.permission.replaceAll("_", " "), ...patterns].join("\n");
+      context.autoRepliedRequestIds.delete(request.id);
+      context.pendingPermissions.set(request.id, request);
+      emitUnsafe({
+        ...base,
+        type: "request.opened",
+        payload: {
+          requestType: mapPermissionToRequestType(request.permission),
+          detail,
+          args: request.metadata,
+          options: [
+            { decision: "accept", label: "Allow once" },
+            {
+              decision: "acceptForSession",
+              label: "Allow for workspace",
+              warning: "Applies to matching requests in other OpenCode sessions in this workspace.",
+            },
+            { decision: "decline", label: "Deny" },
+          ],
+        },
+      });
+    });
+
     // Full access means the user already granted everything, but two upstream
     // paths never consult the session ruleset we send: doom-loop detection
     // (evaluated against the agent ruleset only) and subagent sessions (which
@@ -1622,15 +1754,12 @@ export function makeOpenCodeAdapter(
     const autoReplyFullAccess = Effect.fn("autoReplyFullAccess")(function* (
       context: OpenCodeSessionContext,
       request: PermissionRequest,
+      raw: unknown,
     ) {
-      // Mark before awaiting: retry and recovery fibers re-enter the ask path,
-      // and the matching `permission.replied` can arrive, while the SDK call
-      // is in flight. Marked ids skip the ask and swallow the terminal event.
-      context.resolvedRequestIds.add(request.id);
-      context.autoRepliedRequestIds.add(request.id);
-      const replied = yield* runOpenCodeSdk("permission.reply", () =>
-        context.client.permission.reply({ requestID: request.id, reply: "once" }),
+      const replied = yield* runOpenCodeSdk("permission.reply", (signal) =>
+        context.client.permission.reply({ requestID: request.id, reply: "once" }, { signal }),
       ).pipe(
+        Effect.timeout("10 seconds"),
         Effect.as(true),
         Effect.orElseSucceed(() => false),
       );
@@ -1638,9 +1767,8 @@ export function makeOpenCodeAdapter(
         // Fall back to the dialog. The id stays resolved so a recovered copy
         // of this ask cannot reopen after the user answers;
         // `pendingPermissions` gates re-asks while the dialog is open.
-        context.autoRepliedRequestIds.delete(request.id);
+        yield* openPermissionRequest(context, request, raw);
       }
-      return replied;
     });
 
     const emitPendingOpenCodeRequest = Effect.fn("emitPendingOpenCodeRequest")(function* (
@@ -1651,39 +1779,26 @@ export function makeOpenCodeAdapter(
       if (context.resolvedRequestIds.has(event.properties.id)) {
         return;
       }
+      if (context.activeTurnId === undefined && context.reconcileIdleStatus) {
+        context.resolvedRequestIds.add(event.properties.id);
+        return;
+      }
       if (event.type === "permission.asked") {
         const request = event.properties;
         if (context.pendingPermissions.has(request.id)) {
           return;
         }
-        if (
-          context.session.runtimeMode === "full-access" &&
-          (yield* autoReplyFullAccess(context, request))
-        ) {
-          return;
-        }
-        const base = yield* buildEventBase({
-          threadId: context.session.threadId,
-          turnId: context.activeTurnId,
-          requestId: request.id,
-          raw,
-        });
-        // No yield between this check and the publish: a terminal
-        // `permission.replied` delivered on the pump in between would leave a
-        // dialog that can never close.
-        if (context.emittedTerminalRequestIds.has(request.id)) {
+        if (context.session.runtimeMode === "full-access") {
+          // Reply outside the event pump so a slow HTTP response cannot hide
+          // progress, terminal replies, or the acknowledgment for Stop.
+          context.resolvedRequestIds.add(request.id);
+          context.autoRepliedRequestIds.add(request.id);
+          yield* autoReplyFullAccess(context, request, raw).pipe(
+            Effect.forkIn(context.sessionScope),
+          );
           return;
         }
-        context.pendingPermissions.set(request.id, request);
-        emitUnsafe({
-          ...base,
-          type: "request.opened",
-          payload: {
-            requestType: mapPermissionToRequestType(request.permission),
-            detail: request.patterns.length > 0 ? request.patterns.join("\n") : request.permission,
-            args: request.metadata,
-          },
-        });
+        yield* openPermissionRequest(context, request, raw);
         return;
       }
 
@@ -1691,14 +1806,19 @@ export function makeOpenCodeAdapter(
       if (context.pendingQuestions.has(request.id)) {
         return;
       }
+      const base = yield* buildEventBase({
+        threadId: context.session.threadId,
+        turnId: context.activeTurnId,
+        requestId: request.id,
+        raw,
+      });
+      const stopped = yield* Ref.get(context.stopped);
+      if (stopped || context.resolvedRequestIds.has(request.id)) {
+        return;
+      }
       context.pendingQuestions.set(request.id, request);
-      yield* emit({
-        ...(yield* buildEventBase({
-          threadId: context.session.threadId,
-          turnId: context.activeTurnId,
-          requestId: request.id,
-          raw,
-        })),
+      emitUnsafe({
+        ...base,
         type: "user-input.requested",
         payload: { questions: normalizeQuestionRequest(request) },
       });
@@ -1719,26 +1839,32 @@ export function makeOpenCodeAdapter(
     const emitTerminalOpenCodeRequest = Effect.fn("emitTerminalOpenCodeRequest")(function* (
       context: OpenCodeSessionContext,
       event: OpenCodeTerminalRequestEvent,
+      raw: unknown = event,
     ) {
       const requestId = event.properties.requestID;
       if (context.emittedTerminalRequestIds.has(requestId)) {
         return;
       }
-      context.emittedTerminalRequestIds.add(requestId);
       if (context.autoRepliedRequestIds.delete(requestId)) {
+        context.emittedTerminalRequestIds.add(requestId);
         return;
       }
+      const base = yield* buildEventBase({
+        threadId: context.session.threadId,
+        turnId: context.activeTurnId,
+        requestId,
+        raw,
+      });
+      if (context.emittedTerminalRequestIds.has(requestId)) return;
+      context.emittedTerminalRequestIds.add(requestId);
       if (event.type === "permission.replied") {
-        yield* emit({
-          ...(yield* buildEventBase({
-            threadId: context.session.threadId,
-            turnId: context.activeTurnId,
-            requestId,
-            raw: event,
-          })),
+        const request = context.pendingPermissions.get(requestId);
+        context.pendingPermissions.delete(requestId);
+        emitUnsafe({
+          ...base,
           type: "request.resolved",
           payload: {
-            requestType: "unknown",
+            requestType: request ? mapPermissionToRequestType(request.permission) : "unknown",
             decision: mapPermissionDecision(event.properties.reply),
           },
         });
@@ -1746,6 +1872,7 @@ export function makeOpenCodeAdapter(
       }
 
       const request = context.pendingQuestions.get(requestId);
+      context.pendingQuestions.delete(requestId);
       const answers =
         event.type === "question.replied" && request
           ? Object.fromEntries(
@@ -1755,18 +1882,73 @@ export function makeOpenCodeAdapter(
               ]),
             )
           : {};
-      yield* emit({
-        ...(yield* buildEventBase({
-          threadId: context.session.threadId,
-          turnId: context.activeTurnId,
-          requestId,
-          raw: event,
-        })),
+      emitUnsafe({
+        ...base,
         type: "user-input.resolved",
         payload: { answers },
       });
     });
 
+    const closePendingOpenCodeRequests = Effect.fn("closePendingOpenCodeRequests")(function* (
+      context: OpenCodeSessionContext,
+      permissions: ReadonlyArray<PermissionRequest>,
+      questions: ReadonlyArray<QuestionRequest>,
+      raw: unknown,
+    ) {
+      for (const request of permissions) {
+        if (!context.pendingPermissions.has(request.id)) continue;
+        yield* resolvePendingOpenCodeRequest(context, request.id);
+        const base = yield* buildEventBase({
+          threadId: context.session.threadId,
+          turnId: context.activeTurnId,
+          requestId: request.id,
+          raw,
+        });
+        if (context.emittedTerminalRequestIds.has(request.id)) continue;
+        context.pendingPermissions.delete(request.id);
+        context.emittedTerminalRequestIds.add(request.id);
+        emitUnsafe({
+          ...base,
+          type: "request.resolved",
+          payload: { requestType: mapPermissionToRequestType(request.permission) },
+        });
+      }
+      for (const request of questions) {
+        if (!context.pendingQuestions.has(request.id)) continue;
+        yield* resolvePendingOpenCodeRequest(context, request.id);
+        const base = yield* buildEventBase({
+          threadId: context.session.threadId,
+          turnId: context.activeTurnId,
+          requestId: request.id,
+          raw,
+        });
+        if (context.emittedTerminalRequestIds.has(request.id)) continue;
+        context.pendingQuestions.delete(request.id);
+        context.emittedTerminalRequestIds.add(request.id);
+        emitUnsafe({ ...base, type: "user-input.resolved", payload: { answers: {} } });
+      }
+    });
+
+    const clearPendingOpenCodeRequests = Effect.fn("clearPendingOpenCodeRequests")(function* (
+      context: OpenCodeSessionContext,
+      raw: unknown,
+    ) {
+      context.pendingRequestRecovery = undefined;
+      for (const requestId of context.requestRelationRetries.keys()) {
+        yield* resolvePendingOpenCodeRequest(context, requestId);
+      }
+      for (const requestId of context.autoRepliedRequestIds) {
+        context.emittedTerminalRequestIds.add(requestId);
+      }
+      context.autoRepliedRequestIds.clear();
+      yield* closePendingOpenCodeRequests(
+        context,
+        [...context.pendingPermissions.values()],
+        [...context.pendingQuestions.values()],
+        raw,
+      );
+    });
+
     const scheduleRequestRelationRetry = Effect.fn("scheduleRequestRelationRetry")(function* (
       context: OpenCodeSessionContext,
       event: OpenCodeRoutedRequestEvent,
@@ -1854,10 +2036,21 @@ export function makeOpenCodeAdapter(
       const run = Effect.gen(function* () {
         let retryCount = 0;
         while (context.pendingRequestRecovery === recovery) {
-          const responses = yield* Effect.all({
-            permissions: runOpenCodeSdk("permission.list", () => context.client.permission.list()),
-            questions: runOpenCodeSdk("question.list", () => context.client.question.list()),
-          }).pipe(
+          // Only requests pending before the snapshot can be closed by it.
+          const priorPermissions = [...context.pendingPermissions.values()];
+          const priorQuestions = [...context.pendingQuestions.values()];
+          const responses = yield* Effect.all(
+            {
+              permissions: runOpenCodeSdk("permission.list", (signal) =>
+                context.client.permission.list(undefined, { signal }),
+              ),
+              questions: runOpenCodeSdk("question.list", (signal) =>
+                context.client.question.list(undefined, { signal }),
+              ),
+            },
+            { concurrency: 2 },
+          ).pipe(
+            Effect.timeout("10 seconds"),
             Effect.match({
               onFailure: (cause) => ({ type: "failure" as const, cause }),
               onSuccess: (value) => ({ type: "success" as const, value }),
@@ -1901,6 +2094,14 @@ export function makeOpenCodeAdapter(
             yield* Effect.sleep(`${delayMs} millis`);
             continue;
           }
+          const permissionIds = new Set(permissions.map((request) => request.id));
+          const questionIds = new Set(questions.map((request) => request.id));
+          yield* closePendingOpenCodeRequests(
+            context,
+            priorPermissions.filter((request) => !permissionIds.has(request.id)),
+            priorQuestions.filter((request) => !questionIds.has(request.id)),
+            { type: "pending-requests.recovered" },
+          );
           yield* Effect.forEach(
             permissions,
             (request) =>
@@ -1969,7 +2170,13 @@ export function makeOpenCodeAdapter(
         }
         yield* schedulePendingRequestRecovery(context);
         if (!isFirstConnection) {
+          if (context.turnTokenUsage) {
+            context.turnTokenUsage.complete = false;
+          }
           yield* schedulePromptAdmissionRecovery(context, event);
+          if (context.activeTurnId !== undefined && context.promptAdmission === undefined) {
+            yield* scheduleIdleReconciliation(context, context.activeTurnId, event);
+          }
         }
         return;
       }
@@ -1985,7 +2192,7 @@ export function makeOpenCodeAdapter(
       if (event.type === "session.created" || event.type === "session.updated") {
         const session = event.properties.info;
         if (session.parentID && context.relatedSessionIds.has(session.parentID)) {
-          context.relatedSessionIds.add(session.id);
+          addRelatedOpenCodeSession(context, session.id);
         }
       } else if (event.type === "session.deleted") {
         context.relatedSessionIds.delete(event.properties.info.id);
@@ -2046,6 +2253,7 @@ export function makeOpenCodeAdapter(
           context.awaitingBusyAfterInterruption) &&
         (event.type === "message.part.delta" ||
           event.type === "message.part.updated" ||
+          event.type === "todo.updated" ||
           (event.type === "message.updated" && event.properties.info.role === "assistant"));
       if (suppressInterruptedParentOutput) {
         return;
@@ -2108,10 +2316,36 @@ export function makeOpenCodeAdapter(
           }
           context.messageRoleById.set(event.properties.info.id, event.properties.info.role);
           if (event.properties.info.role === "assistant") {
+            const usage = context.turnTokenUsage;
+            const parentMessageId =
+              typeof event.properties.info.parentID === "string" &&
+              event.properties.info.parentID.trim().length > 0
+                ? event.properties.info.parentID
+                : undefined;
+            const observedOwnership =
+              parentMessageId === undefined
+                ? "unknown"
+                : usage?.promptMessageIds.has(parentMessageId)
+                  ? "owned"
+                  : "other";
+            const priorOwnership = usage?.assistantOwnershipByMessageId.get(
+              event.properties.info.id,
+            );
+            const ownership =
+              priorOwnership === undefined || priorOwnership === "unknown"
+                ? observedOwnership
+                : priorOwnership;
+            if (usage) {
+              usage.assistantOwnershipByMessageId.set(event.properties.info.id, ownership);
+            }
             for (const part of context.partById.values()) {
               if (part.messageID !== event.properties.info.id) {
                 continue;
               }
+              if (usage && part.type === "step-finish") {
+                if (ownership !== "unknown") usage.unresolvedStepPartIds.delete(part.id);
+                if (ownership === "owned") accumulateOpenCodeStepUsage(usage, part);
+              }
               yield* emitAssistantTextDelta(context, part, turnId, event);
             }
           }
@@ -2125,7 +2359,11 @@ export function makeOpenCodeAdapter(
 
         case "message.part.delta": {
           const existingPart = context.partById.get(event.properties.partID);
-          if (!existingPart) {
+          if (
+            !existingPart ||
+            (existingPart.type !== "text" && existingPart.type !== "reasoning") ||
+            event.properties.field !== "text"
+          ) {
             break;
           }
           const role = messageRoleForPart(context, existingPart);
@@ -2170,9 +2408,27 @@ export function makeOpenCodeAdapter(
 
         case "message.part.updated": {
           const part = event.properties.part;
-          context.partById.set(part.id, part);
+          // Tool events use the incoming part and do not need a cached copy.
+          if (part.type !== "tool") {
+            context.partById.set(part.id, part);
+          }
           const messageRole = messageRoleForPart(context, part);
 
+          if (turnId && part.type === "step-finish" && context.turnTokenUsage) {
+            const ownership = context.turnTokenUsage.assistantOwnershipByMessageId.get(
+              part.messageID,
+            );
+            if (ownership === "owned") {
+              accumulateOpenCodeStepUsage(context.turnTokenUsage, part);
+            } else if (
+              ownership === "unknown" ||
+              (ownership === undefined &&
+                context.messageRoleById.get(part.messageID) !== "assistant")
+            ) {
+              context.turnTokenUsage.unresolvedStepPartIds.add(part.id);
+            }
+          }
+
           if (messageRole === "assistant") {
             yield* emitAssistantTextDelta(context, part, turnId, event);
           }
@@ -2180,7 +2436,9 @@ export function makeOpenCodeAdapter(
           if (part.type === "tool") {
             const itemType = toToolLifecycleItemType(part.tool);
             const title =
-              part.state.status === "running" ? (part.state.title ?? part.tool) : part.tool;
+              part.state.status === "running" || part.state.status === "completed"
+                ? (part.state.title ?? part.tool)
+                : part.tool;
             const detail = detailFromToolPart(part);
             const payload = {
               itemType,
@@ -2194,6 +2452,14 @@ export function makeOpenCodeAdapter(
               data: {
                 tool: part.tool,
                 state: part.state,
+                ...(typeof part.state.input.command === "string"
+                  ? { command: part.state.input.command }
+                  : {}),
+                ...(itemType === "file_change" ? { input: part.state.input } : {}),
+                ...(part.state.status === "completed" &&
+                (itemType === "command_execution" || itemType === "mcp_tool_call")
+                  ? { result: part.state.output }
+                  : {}),
               },
             };
             const runtimeEvent: ProviderRuntimeEvent = {
@@ -2212,7 +2478,6 @@ export function makeOpenCodeAdapter(
                     : "item.updated",
               payload,
             };
-            appendTurnItem(context, turnId, part);
             yield* emit(runtimeEvent);
           }
           break;
@@ -2224,7 +2489,6 @@ export function makeOpenCodeAdapter(
         }
 
         case "permission.replied": {
-          context.pendingPermissions.delete(event.properties.requestID);
           yield* emitTerminalOpenCodeRequest(context, event);
           break;
         }
@@ -2236,18 +2500,45 @@ export function makeOpenCodeAdapter(
 
         case "question.replied": {
           yield* emitTerminalOpenCodeRequest(context, event);
-          context.pendingQuestions.delete(event.properties.requestID);
           break;
         }
 
         case "question.rejected": {
-          context.pendingQuestions.delete(event.properties.requestID);
           yield* emitTerminalOpenCodeRequest(context, event);
           break;
         }
 
+        case "todo.updated": {
+          if (turnId === undefined) break;
+          const base = yield* buildEventBase({
+            threadId: context.session.threadId,
+            turnId,
+            raw: event,
+          });
+          // Session-wide task updates must not reopen progress after a turn ends.
+          if (context.activeTurnId !== turnId) break;
+          emitUnsafe({
+            ...base,
+            type: "turn.plan.updated",
+            payload: {
+              plan: event.properties.todos
+                .filter((todo) => todo.status !== "cancelled")
+                .map((todo) => ({
+                  step: trimText(todo.content) ?? "Task",
+                  status:
+                    todo.status === "completed"
+                      ? "completed"
+                      : todo.status === "in_progress"
+                        ? "inProgress"
+                        : "pending",
+                })),
+            },
+          });
+          break;
+        }
+
         case "session.status": {
-          if (event.properties.status.type === "busy") {
+          if (event.properties.status.type === "busy" || event.properties.status.type === "retry") {
             if (turnId === undefined) {
               break;
             }
@@ -2272,7 +2563,7 @@ export function makeOpenCodeAdapter(
               })),
               type: "runtime.warning",
               payload: {
-                message: event.properties.status.message,
+                message: `OpenCode retry ${event.properties.status.attempt}: ${event.properties.status.message}`,
                 detail: event.properties.status,
               },
             });
@@ -2331,10 +2622,12 @@ export function makeOpenCodeAdapter(
             terminalCancellation.turnSettled = true;
             terminalCancellation.acknowledged = true;
           }
+          const tokenUsage = activeTurnId ? takeOpenCodeTurnTokenUsage(context, false) : undefined;
           context.activeTurnId = undefined;
           context.activeAgent = undefined;
           context.activeVariant = undefined;
           context.reconcileIdleStatus = false;
+          yield* schedulePendingRequestRecovery(context);
           yield* updateProviderSession(
             context,
             {
@@ -2354,6 +2647,7 @@ export function makeOpenCodeAdapter(
               payload: {
                 state: "failed",
                 errorMessage: message,
+                tokenUsage,
               },
             });
           }
@@ -2388,9 +2682,29 @@ export function makeOpenCodeAdapter(
       // 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()),
+      let lastStreamError: unknown;
+      let warnedAboutDisconnect = false;
+      const streamErrors = yield* Queue.unbounded<unknown>();
+      yield* Scope.addFinalizer(context.sessionScope, Queue.shutdown(streamErrors));
+      yield* Stream.fromQueue(streamErrors).pipe(
+        Stream.runForEach((cause) =>
+          Effect.gen(function* () {
+            if (warnedAboutDisconnect) return;
+            warnedAboutDisconnect = true;
+            yield* emit({
+              ...(yield* buildEventBase({
+                threadId: context.session.threadId,
+                turnId: context.activeTurnId,
+              })),
+              type: "runtime.warning",
+              payload: {
+                message: "OpenCode connection lost. Reconnecting.",
+                detail: openCodeRuntimeErrorDetail(cause),
+              },
+            });
+          }),
+        ),
+        Effect.forkIn(context.sessionScope),
       );
 
       // Fibers forked into `context.sessionScope` are interrupted
@@ -2399,6 +2713,10 @@ export function makeOpenCodeAdapter(
         runOpenCodeSdk("event.subscribe", () =>
           context.client.event.subscribe(undefined, {
             signal: eventsAbortController.signal,
+            onSseError: (cause) => {
+              lastStreamError = cause;
+              Queue.offerUnsafe(streamErrors, cause);
+            },
           }),
         ),
         (subscription) =>
@@ -2410,7 +2728,13 @@ export function makeOpenCodeAdapter(
                 detail: openCodeRuntimeErrorDetail(cause),
                 cause,
               }),
-          ).pipe(Stream.runForEach((event) => handleSubscribedEvent(context, event))),
+          ).pipe(
+            Stream.runForEach((event) => {
+              if (event.type === "server.connected") lastStreamError = undefined;
+              if (event.type === "server.connected") warnedAboutDisconnect = false;
+              return handleSubscribedEvent(context, event);
+            }),
+          ),
       ).pipe(
         Effect.exit,
         Effect.flatMap((exit) =>
@@ -2420,12 +2744,14 @@ export function makeOpenCodeAdapter(
             if (eventsAbortController.signal.aborted || (yield* Ref.get(context.stopped))) {
               return;
             }
-            if (Exit.isFailure(exit)) {
-              yield* emitUnexpectedExit(
-                context,
-                openCodeRuntimeErrorDetail(Cause.squash(exit.cause)),
-              );
-            }
+            yield* emitUnexpectedExit(
+              context,
+              Exit.isFailure(exit)
+                ? openCodeRuntimeErrorDetail(Cause.squash(exit.cause))
+                : lastStreamError !== undefined
+                  ? `OpenCode event stream disconnected: ${openCodeRuntimeErrorDetail(lastStreamError)}`
+                  : "OpenCode event stream ended unexpectedly. Send another message to reconnect.",
+            );
           }),
         ),
         Effect.forkIn(context.sessionScope),
@@ -2444,6 +2770,12 @@ export function makeOpenCodeAdapter(
           Effect.forkIn(context.sessionScope),
         );
       }
+      // Scope finalizers run in reverse order. Abort the pending read before
+      // interrupting the pump, whose iterator.return() waits for that read.
+      yield* Scope.addFinalizer(
+        context.sessionScope,
+        Effect.sync(() => eventsAbortController.abort()),
+      );
     });
 
     const startSession: OpenCodeAdapterShape["startSession"] = Effect.fn("startSession")(
@@ -2635,7 +2967,7 @@ export function makeOpenCodeAdapter(
           emittedTextByPartId: new Map(),
           messageRoleById: new Map(),
           completedAssistantPartIds: new Set(),
-          turns: [],
+          turnTokenUsage: undefined,
           activeTurnId: undefined,
           activeAgent: undefined,
           activeVariant: undefined,
@@ -2808,6 +3140,10 @@ export function makeOpenCodeAdapter(
           context.promptAdmission = promptAdmission;
 
           context.activeTurnId = turnId;
+          if (steeringTurnId === undefined) {
+            context.turnTokenUsage = makeOpenCodeTurnTokenUsageAccumulator();
+          }
+          context.turnTokenUsage?.promptMessageIds.add(messageId);
           context.activeAgent = agent ?? (input.interactionMode === "plan" ? "plan" : undefined);
           context.activeVariant = variant;
           if (steeringTurnId === undefined) {
@@ -2832,7 +3168,6 @@ export function makeOpenCodeAdapter(
               type: "turn.started",
               payload: {
                 model: modelSelection?.model ?? context.session.model,
-                ...(variant ? { effort: variant } : {}),
               },
             });
           }
@@ -2897,6 +3232,7 @@ export function makeOpenCodeAdapter(
                         }
                         return;
                       }
+                      const tokenUsage = takeOpenCodeTurnTokenUsage(context, false);
                       context.promptAdmission = undefined;
                       context.activeTurnId = undefined;
                       context.activeAgent = undefined;
@@ -2913,7 +3249,10 @@ export function makeOpenCodeAdapter(
                       yield* emit({
                         ...(yield* buildEventBase({ threadId: input.threadId, turnId })),
                         type: "turn.aborted",
-                        payload: { reason: requestError.detail },
+                        payload: {
+                          reason: requestError.detail,
+                          tokenUsage,
+                        },
                       });
                       return;
                     }
@@ -2941,6 +3280,7 @@ export function makeOpenCodeAdapter(
                       });
                       return;
                     }
+                    const tokenUsage = takeOpenCodeTurnTokenUsage(context, false);
                     context.promptAdmission = undefined;
                     context.activeTurnId = undefined;
                     context.activeAgent = undefined;
@@ -2964,6 +3304,7 @@ export function makeOpenCodeAdapter(
                       type: "turn.aborted",
                       payload: {
                         reason: requestError.detail,
+                        tokenUsage,
                       },
                     });
                   }),
@@ -3259,6 +3600,7 @@ export function makeOpenCodeAdapter(
           } else {
             context.cancellation = undefined;
             context.reconcileIdleStatus = true;
+            yield* clearPendingOpenCodeRequests(context, { type: "session.abort" });
           }
         }
         yield* Deferred.succeed(cancellation.completion, undefined).pipe(Effect.ignore);
@@ -3269,20 +3611,52 @@ export function makeOpenCodeAdapter(
       "respondToRequest",
     )(function* (threadId, requestId, decision) {
       const context = yield* ensureSessionContext(sessions, threadId);
-      if (!context.pendingPermissions.has(requestId)) {
+      const request = context.pendingPermissions.get(requestId);
+      if (!request) {
+        if (context.emittedTerminalRequestIds.has(requestId)) return;
         return yield* new ProviderAdapterRequestError({
           provider: PROVIDER,
           method: "permission.reply",
-          detail: `Unknown pending permission request: ${requestId}`,
+          detail:
+            context.pendingRequestRecovery || context.requestRelationRetries.has(requestId)
+              ? "OpenCode is still loading this permission request. Try again."
+              : `Unknown pending permission request: ${requestId}`,
         });
       }
 
-      yield* runOpenCodeSdk("permission.reply", () =>
-        context.client.permission.reply({
-          requestID: requestId,
-          reply: toOpenCodePermissionReply(decision),
+      const reply = toOpenCodePermissionReply(decision);
+      yield* runOpenCodeSdk("permission.reply", (signal) =>
+        context.client.permission.reply(
+          {
+            requestID: requestId,
+            reply,
+          },
+          { signal },
+        ),
+      ).pipe(
+        Effect.mapError(toRequestError),
+        Effect.timeoutOrElse({
+          duration: "10 seconds",
+          orElse: () =>
+            Effect.fail(
+              new ProviderAdapterRequestError({
+                provider: PROVIDER,
+                method: "permission.reply",
+                detail: "OpenCode permission reply did not complete within 10 seconds.",
+              }),
+            ),
         }),
-      ).pipe(Effect.mapError(toRequestError));
+      );
+      yield* resolvePendingOpenCodeRequest(context, requestId);
+      yield* emitTerminalOpenCodeRequest(
+        context,
+        {
+          id: `reply:${requestId}`,
+          type: "permission.replied",
+          properties: { sessionID: request.sessionID, requestID: requestId, reply },
+        },
+        { type: "permission.reply", requestID: requestId, reply },
+      );
     });
 
     const respondToUserInput: OpenCodeAdapterShape["respondToUserInput"] = Effect.fn(
@@ -3291,19 +3665,54 @@ export function makeOpenCodeAdapter(
       const context = yield* ensureSessionContext(sessions, threadId);
       const request = context.pendingQuestions.get(requestId);
       if (!request) {
+        if (context.emittedTerminalRequestIds.has(requestId)) return;
         return yield* new ProviderAdapterRequestError({
           provider: PROVIDER,
           method: "question.reply",
-          detail: `Unknown pending user-input request: ${requestId}`,
+          detail:
+            context.pendingRequestRecovery || context.requestRelationRetries.has(requestId)
+              ? "OpenCode is still loading this question. Try again."
+              : `Unknown pending user-input request: ${requestId}`,
         });
       }
 
-      yield* runOpenCodeSdk("question.reply", () =>
-        context.client.question.reply({
-          requestID: requestId,
-          answers: toOpenCodeQuestionAnswers(request, answers),
+      const questionAnswers = toOpenCodeQuestionAnswers(request, answers);
+      yield* runOpenCodeSdk("question.reply", (signal) =>
+        context.client.question.reply(
+          {
+            requestID: requestId,
+            answers: questionAnswers,
+          },
+          { signal },
+        ),
+      ).pipe(
+        Effect.mapError(toRequestError),
+        Effect.timeoutOrElse({
+          duration: "10 seconds",
+          orElse: () =>
+            Effect.fail(
+              new ProviderAdapterRequestError({
+                provider: PROVIDER,
+                method: "question.reply",
+                detail: "OpenCode question reply did not complete within 10 seconds.",
+              }),
+            ),
         }),
-      ).pipe(Effect.mapError(toRequestError));
+      );
+      yield* resolvePendingOpenCodeRequest(context, requestId);
+      yield* emitTerminalOpenCodeRequest(
+        context,
+        {
+          id: `reply:${requestId}`,
+          type: "question.replied",
+          properties: {
+            sessionID: request.sessionID,
+            requestID: requestId,
+            answers: questionAnswers,
+          },
+        },
+        { type: "question.reply", requestID: requestId },
+      );
     });
 
     const stopSession: OpenCodeAdapterShape["stopSession"] = Effect.fn("stopSession")(
diff --git a/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts b/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
index 18d94ebd0e18..bb8ff7835c8f 100644
--- a/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderAdapterRegistry.test.ts
@@ -111,10 +111,13 @@ const makeFakeInstance = (
     displayName: undefined,
     enabled: true,
     snapshot: {
-      maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-        provider: driverKind,
-        packageName: null,
-      }),
+      resolveMaintenance: () =>
+        Effect.succeed(
+          makeManualOnlyProviderMaintenanceCapabilities({
+            provider: driverKind,
+            packageName: null,
+          }),
+        ),
       getSnapshot: Effect.succeed({} as unknown as ServerProvider),
       refresh: Effect.succeed({} as unknown as ServerProvider),
       streamChanges: Stream.empty,
diff --git a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
index d750789fde02..25dafa5ba040 100644
--- a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
@@ -34,9 +34,12 @@ import {
   type ProviderInstanceConfigMap,
   ProviderInstanceId,
 } from "@t3tools/contracts";
+import { isHostWindows } from "@t3tools/shared/hostProcess";
 import * as DateTime from "effect/DateTime";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 import * as Stream from "effect/Stream";
 import { HttpClient, HttpClientResponse } from "effect/unstable/http";
 
@@ -44,6 +47,7 @@ import * as BackgroundPolicy from "../../background/BackgroundPolicy.ts";
 import type { BuiltInDriversEnv } from "../builtInDrivers.ts";
 import { AntigravityInstallation } from "../AntigravityInstallation.ts";
 import { ServerConfig } from "../../config.ts";
+import { expandHomePath } from "../../pathExpansion.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 import { ClaudeDriver } from "../Drivers/ClaudeDriver.ts";
 import { CodexDriver } from "../Drivers/CodexDriver.ts";
@@ -138,6 +142,80 @@ const makeOpenCodeConfig = (overrides: Partial<OpenCodeSettings>): OpenCodeSetti
   ...overrides,
 });
 
+const makeTildeProviderFixtures = Effect.fn(
+  "ProviderInstanceRegistryLive.test.makeTildeProviderFixtures",
+)(function* () {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const homePath = expandHomePath("~");
+  const fixtureDir = yield* fileSystem.makeTempDirectoryScoped({
+    directory: homePath,
+    prefix: ".t3-provider-path-test-",
+  });
+  const codexPath = path.join(fixtureDir, "codex");
+  const claudePath = path.join(fixtureDir, "claude");
+  const claudeHomePath = path.join(fixtureDir, "claude-home");
+  const codexScriptPath = path.join(fixtureDir, "codex-script.json");
+  const codexFixtureDir = path.join(import.meta.dirname, "../testFixtures");
+
+  yield* fileSystem.copyFile(path.join(codexFixtureDir, "codexCollabMockPeer.sh"), codexPath);
+  yield* fileSystem.copyFile(
+    path.join(codexFixtureDir, "codexCollabMockPeer.mjs"),
+    path.join(fixtureDir, "codexCollabMockPeer.mjs"),
+  );
+  yield* fileSystem.copyFile(
+    path.join(codexFixtureDir, "codexMultiAgentWire.json"),
+    path.join(fixtureDir, "codexMultiAgentWire.json"),
+  );
+  yield* fileSystem.writeFileString(
+    codexScriptPath,
+    // @effect-diagnostics-next-line preferSchemaOverJson:off - fixed script document read by the external Codex mock peer.
+    JSON.stringify({ rootThreadId: "probe-thread", notifications: [] }),
+  );
+  yield* fileSystem.chmod(codexPath, 0o755);
+
+  yield* fileSystem.writeFileString(
+    claudePath,
+    [
+      "#!/usr/bin/env node",
+      'import * as NodeReadline from "node:readline";',
+      'if (process.argv.includes("--version")) {',
+      '  process.stdout.write("claude 2.1.219\\n");',
+      "  process.exit(0);",
+      "}",
+      "const lines = NodeReadline.createInterface({ input: process.stdin });",
+      'lines.on("line", (line) => {',
+      "  const message = JSON.parse(line);",
+      '  if (message.type !== "control_request" || message.request?.subtype !== "initialize") return;',
+      "  process.stdout.write(JSON.stringify({",
+      '    type: "control_response",',
+      "    response: {",
+      '      subtype: "success",',
+      "      request_id: message.request_id,",
+      "      response: {",
+      "        commands: [], agents: [], models: [],",
+      '        output_style: "default", available_output_styles: ["default"],',
+      '        account: { email: "test@example.com", subscriptionType: "pro", tokenSource: "oauth" },',
+      "      },",
+      "    },",
+      '  }) + "\\n");',
+      "});",
+      "setInterval(() => {}, 1_000);",
+      "",
+    ].join("\n"),
+  );
+  yield* fileSystem.chmod(claudePath, 0o755);
+  yield* fileSystem.makeDirectory(claudeHomePath);
+
+  const asTildePath = (filePath: string) => `~/${path.relative(homePath, filePath)}`;
+  return {
+    codexBinaryPath: asTildePath(codexPath),
+    claudeBinaryPath: asTildePath(claudePath),
+    claudeHomePath,
+    codexScriptPath,
+  };
+});
+
 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
@@ -214,15 +292,19 @@ describe("ProviderInstanceRegistryLive — multi-instance codex slice", () => {
       expect(personalSnapshot.instanceId).toBe(personalId);
       expect(personalSnapshot.driver).toBe(codexDriverKind);
       expect(personalSnapshot.enabled).toBe(false);
+      // The layout resolves the configured home through the host Path.
+      const path = yield* Path.Path;
       expect(personalSnapshot.continuation?.groupKey).toBe(
-        "codex:home:/home/julius/.codex_personal",
+        `codex:home:${path.resolve("/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");
+      expect(workSnapshot.continuation?.groupKey).toBe(
+        `codex:home:${path.resolve("/home/julius/.codex")}`,
+      );
 
       // Nothing goes to the unavailable bucket — both drivers are registered.
       const unavailable = yield* registry.listUnavailable;
@@ -256,6 +338,60 @@ describe("ProviderInstanceRegistryLive — multi-instance codex slice", () => {
     }).pipe(Effect.provide(testLayer)),
   );
 
+  it.live("runs Codex and Claude readiness probes from configured tilde paths", () =>
+    Effect.gen(function* () {
+      if (yield* isHostWindows) return;
+
+      const fixtures = yield* makeTildeProviderFixtures();
+
+      const codexId = ProviderInstanceId.make("codex_tilde");
+      const claudeId = ProviderInstanceId.make("claude_tilde");
+      const configMap: ProviderInstanceConfigMap = {
+        [codexId]: {
+          driver: ProviderDriverKind.make("codex"),
+          enabled: true,
+          environment: [
+            {
+              name: "T3_CODEX_COLLAB_SCRIPT",
+              value: fixtures.codexScriptPath,
+              sensitive: false,
+            },
+          ],
+          config: makeCodexConfig({ enabled: true, binaryPath: fixtures.codexBinaryPath }),
+        },
+        [claudeId]: {
+          driver: ProviderDriverKind.make("claudeAgent"),
+          enabled: true,
+          config: makeClaudeConfig({
+            enabled: true,
+            binaryPath: fixtures.claudeBinaryPath,
+            homePath: fixtures.claudeHomePath,
+          }),
+        },
+      };
+
+      const { registry } = yield* makeProviderInstanceRegistry({
+        drivers: [CodexDriver, ClaudeDriver],
+        configMap,
+      });
+      const codex = yield* registry.getInstance(codexId);
+      const claude = yield* registry.getInstance(claudeId);
+      expect(codex).toBeDefined();
+      expect(claude).toBeDefined();
+
+      const [codexSnapshot, claudeSnapshot] = yield* Effect.all(
+        [codex!.snapshot.refresh, claude!.snapshot.refresh],
+        { concurrency: "unbounded" },
+      );
+      expect(codexSnapshot).toMatchObject({ status: "ready", installed: true, version: "0.0.0" });
+      expect(claudeSnapshot).toMatchObject({
+        status: "ready",
+        installed: true,
+        version: "2.1.219",
+      });
+    }).pipe(Effect.provide(testLayer)),
+  );
+
   it.live(
     "shadows instances whose driver is not registered in this build without failing boot",
     () =>
@@ -451,13 +587,17 @@ describe("ProviderInstanceRegistryLive — all drivers slice", () => {
       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");
+      expect(codexSnapshot.continuation?.groupKey).toBe(
+        `codex:home:${(yield* Path.Path).resolve("/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");
+      expect(claudeSnapshot.continuation?.groupKey).toBe(
+        `claude:home:${(yield* Path.Path).resolve("/home/julius/.claude-work")}`,
+      );
 
       const cursorSnapshot = yield* cursor!.snapshot.getSnapshot;
       expect(cursorSnapshot.instanceId).toBe(cursorId);
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
index b961032a7082..ffabf6d8d4f3 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
@@ -3,6 +3,7 @@ import { describe, it, assert } from "@effect/vitest";
 import * as DateTime from "effect/DateTime";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
@@ -42,14 +43,17 @@ import * as OpenCodeRuntime from "../opencodeRuntime.ts";
 import * as ProviderEventLoggers from "./ProviderEventLoggers.ts";
 import { ProviderInstanceRegistryHydrationLive } from "./ProviderInstanceRegistryHydration.ts";
 import {
-  haveProvidersChanged,
   mergeProviderSnapshot,
   upsertProviderWorkspaceSnapshot,
   ProviderRegistryLive,
 } from "./ProviderRegistry.ts";
 import * as ServerConfig from "../../config.ts";
 import * as ServerSettingsModule from "../../serverSettings.ts";
-import { readProviderStatusCache, resolveProviderStatusCachePath } from "../providerStatusCache.ts";
+import {
+  readProviderStatusCache,
+  resolveProviderStatusCachePath,
+  writeProviderStatusCache,
+} from "../providerStatusCache.ts";
 import { COMPACT_SLASH_COMMAND } from "../providerSnapshot.ts";
 import type { ProviderInstance } from "../ProviderDriver.ts";
 import * as ProviderInstanceRegistry from "../Services/ProviderInstanceRegistry.ts";
@@ -342,6 +346,21 @@ function makeMutableServerSettingsService(
   });
 }
 
+// The registry writes the status cache and only then publishes the change, so
+// a subscriber that sees `checkedAt` on the stream knows the file is on disk.
+// Subscribed before the publish that triggers it; a spin on the file would
+// race the write and lose on a slow host.
+const awaitPersistedProvider = (
+  registry: ProviderRegistry.ProviderRegistry["Service"],
+  checkedAt: string,
+) =>
+  registry.streamChanges.pipe(
+    Stream.filter((providers) => providers.some((provider) => provider.checkedAt === checkedAt)),
+    Stream.take(1),
+    Stream.runDrain,
+    Effect.forkScoped,
+  );
+
 it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), TestHttpClientLive))(
   "ProviderRegistry",
   (it) => {
@@ -535,39 +554,6 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
     });
 
     describe("ProviderRegistryLive", () => {
-      it("treats equal provider snapshots as unchanged", () => {
-        const providers = [
-          {
-            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: [],
-          },
-          {
-            instanceId: ProviderInstanceId.make("claudeAgent"),
-            driver: ProviderDriverKind.make("claudeAgent"),
-            status: "warning",
-            enabled: true,
-            installed: true,
-            auth: { status: "unknown" },
-            checkedAt: "2026-03-25T00:00:00.000Z",
-            version: "1.0.0",
-            models: [],
-            slashCommands: [],
-            skills: [],
-          },
-        ] as const satisfies ReadonlyArray<ServerProvider>;
-
-        assert.strictEqual(haveProvidersChanged(providers, [...providers]), false);
-      });
-
       it("stores workspace skills and commands without changing machine metadata", () => {
         const provider = {
           instanceId: ProviderInstanceId.make("codex"),
@@ -900,6 +886,186 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
         assert.deepStrictEqual(afterFailure.models, [authoritativeProvider.models[0]!]);
       });
 
+      describe("Codex model inventories", () => {
+        const cachedProvider = {
+          instanceId: ProviderInstanceId.make("codex-personal"),
+          driver: ProviderDriverKind.make("codex"),
+          status: "ready",
+          enabled: true,
+          installed: true,
+          auth: { status: "authenticated" },
+          checkedAt: "2026-09-04T19:00:00.000Z",
+          version: "0.153.3",
+          models: [
+            "vega-alpha",
+            "joule-alpha",
+            "kindle-alpha",
+            "ultima-alpha",
+            "solstice-alpha",
+          ].map((slug) => ({ slug, name: slug, isCustom: false, capabilities: null })),
+          slashCommands: [],
+          skills: [],
+        } satisfies ServerProvider;
+        const customModel = {
+          slug: "custom-model",
+          name: "Custom model",
+          isCustom: true,
+          capabilities: null,
+        } as const;
+        const refreshedProvider = {
+          ...cachedProvider,
+          checkedAt: "2026-09-04T19:01:00.000Z",
+          models: [
+            { slug: "gpt-6-astra", name: "GPT 6 Astra", isCustom: false, capabilities: null },
+            cachedProvider.models[0]!,
+            customModel,
+          ],
+        } satisfies ServerProvider;
+        const pendingProvider = {
+          ...cachedProvider,
+          status: "warning",
+          installed: false,
+          auth: { status: "unknown" },
+          models: [customModel],
+        } satisfies ServerProvider;
+        const failedProvider = {
+          ...pendingProvider,
+          checkedAt: "2026-09-04T19:02:00.000Z",
+          status: "error",
+          installed: true,
+        } satisfies ServerProvider;
+
+        it("drops retired alpha models after discovery, including without OpenAI authentication", () => {
+          for (const authStatus of ["authenticated", "unknown"] as const) {
+            assert.deepStrictEqual(
+              mergeProviderSnapshot(cachedProvider, {
+                ...refreshedProvider,
+                auth: { status: authStatus },
+              }).models,
+              refreshedProvider.models,
+            );
+          }
+        });
+
+        it("keeps discovered models during startup and failed probes without restoring removed custom models", () => {
+          for (const provider of [pendingProvider, failedProvider]) {
+            assert.deepStrictEqual(
+              mergeProviderSnapshot(
+                {
+                  ...cachedProvider,
+                  models: [...cachedProvider.models, { ...customModel, slug: "removed-custom" }],
+                },
+                provider,
+              ).models,
+              [customModel, ...cachedProvider.models],
+            );
+          }
+        });
+
+        it("clears discovered models after sign-out, disable, uninstall, or empty discovery", () => {
+          const emptyProvider = { ...refreshedProvider, models: [customModel] };
+          const clearedProviders = [
+            { ...emptyProvider, status: "error", auth: { status: "unauthenticated" } },
+            { ...emptyProvider, status: "disabled", enabled: false },
+            { ...emptyProvider, status: "error", installed: false, auth: { status: "unknown" } },
+            emptyProvider,
+            { ...emptyProvider, models: [] },
+          ] satisfies ReadonlyArray<ServerProvider>;
+
+          for (const provider of clearedProviders) {
+            assert.deepStrictEqual(
+              mergeProviderSnapshot(cachedProvider, provider).models,
+              provider.models,
+            );
+          }
+        });
+
+        it.effect("persists removals across failed refreshes and registry restarts", () =>
+          Effect.gen(function* () {
+            const config = yield* ServerConfig.ServerConfig;
+            const filePath = yield* resolveProviderStatusCachePath({
+              cacheDir: config.providerStatusCacheDir,
+              instanceId: cachedProvider.instanceId,
+            });
+            yield* writeProviderStatusCache({ filePath, provider: cachedProvider });
+            const nextProvider = yield* Ref.make<ServerProvider>(refreshedProvider);
+            const instance = {
+              instanceId: cachedProvider.instanceId,
+              driverKind: cachedProvider.driver,
+              continuationIdentity: {
+                driverKind: cachedProvider.driver,
+                continuationKey: "codex:instance:codex-personal",
+              },
+              displayName: undefined,
+              enabled: true,
+              snapshot: {
+                resolveMaintenance: () =>
+                  Effect.succeed(
+                    makeManualOnlyProviderMaintenanceCapabilities({
+                      provider: cachedProvider.driver,
+                      packageName: null,
+                    }),
+                  ),
+                getSnapshot: Effect.succeed(pendingProvider),
+                refresh: Ref.get(nextProvider),
+                streamChanges: Stream.empty,
+                applyUsageLimits: () => Effect.void,
+              },
+              adapter: {} as ProviderInstance["adapter"],
+              textGeneration: {} as ProviderInstance["textGeneration"],
+            } satisfies ProviderInstance;
+            const instanceRegistryLayer = Layer.succeed(
+              ProviderInstanceRegistry.ProviderInstanceRegistry,
+              {
+                getInstance: (id) =>
+                  Effect.succeed(id === instance.instanceId ? instance : undefined),
+                listInstances: Effect.succeed([instance]),
+                listUnavailable: Effect.succeed([]),
+                streamChanges: Stream.empty,
+                subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), PubSub.subscribe),
+              },
+            );
+            const retainedModels = [
+              customModel,
+              ...refreshedProvider.models.filter((model) => !model.isCustom),
+            ];
+
+            for (const restarted of [false, true]) {
+              yield* Effect.gen(function* () {
+                const registry = yield* ProviderRegistry.ProviderRegistry;
+                const expectedModels = restarted
+                  ? retainedModels
+                  : [customModel, ...cachedProvider.models];
+                assert.deepStrictEqual((yield* registry.getProviders)[0]?.models, expectedModels);
+
+                yield* registry.refreshInstance(instance.instanceId);
+                assert.deepStrictEqual(
+                  (yield* readProviderStatusCache(filePath))?.models,
+                  restarted ? retainedModels : refreshedProvider.models,
+                );
+
+                yield* Ref.set(nextProvider, failedProvider);
+                const afterFailure = yield* registry.refreshInstance(instance.instanceId);
+                assert.deepStrictEqual(afterFailure[0]?.models, retainedModels);
+                assert.deepStrictEqual(
+                  (yield* readProviderStatusCache(filePath))?.models,
+                  retainedModels,
+                );
+              }).pipe(
+                Effect.provide(ProviderRegistryLive.pipe(Layer.provide(instanceRegistryLayer))),
+                Effect.scoped,
+              );
+            }
+          }).pipe(
+            Effect.provide(
+              ServerConfig.layerTest(process.cwd(), {
+                prefix: "t3-codex-retired-model-cache-",
+              }).pipe(Layer.provideMerge(NodeServices.layer)),
+            ),
+          ),
+        );
+      });
+
       describe("Antigravity model inventories", () => {
         const previousProvider = {
           instanceId: ProviderInstanceId.make("antigravity-personal"),
@@ -1091,10 +1257,13 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             displayName: undefined,
             enabled: true,
             snapshot: {
-              maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-                provider: codexDriver,
-                packageName: null,
-              }),
+              resolveMaintenance: () =>
+                Effect.succeed(
+                  makeManualOnlyProviderMaintenanceCapabilities({
+                    provider: codexDriver,
+                    packageName: null,
+                  }),
+                ),
               getSnapshot: Effect.succeed(initialProvider),
               refresh: Ref.update(refreshCalls, (count) => count + 1).pipe(
                 Effect.andThen(Effect.never),
@@ -1183,10 +1352,13 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             displayName: undefined,
             enabled: true,
             snapshot: {
-              maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-                provider: driver,
-                packageName: null,
-              }),
+              resolveMaintenance: () =>
+                Effect.succeed(
+                  makeManualOnlyProviderMaintenanceCapabilities({
+                    provider: driver,
+                    packageName: null,
+                  }),
+                ),
               getSnapshot: Effect.succeed(provider),
               refresh: Effect.succeed(provider),
               streamChanges: Stream.empty,
@@ -1372,10 +1544,13 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
               displayName: undefined,
               enabled: true,
               snapshot: {
-                maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-                  provider: codexDriver,
-                  packageName: null,
-                }),
+                resolveMaintenance: () =>
+                  Effect.succeed(
+                    makeManualOnlyProviderMaintenanceCapabilities({
+                      provider: codexDriver,
+                      packageName: null,
+                    }),
+                  ),
                 getSnapshot: Effect.succeed(codexProvider),
                 refresh: Ref.update(codexRefreshCalls, (count) => count + 1).pipe(
                   Effect.as(codexProvider),
@@ -1396,10 +1571,13 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
               displayName: undefined,
               enabled: true,
               snapshot: {
-                maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-                  provider: openCodeDriver,
-                  packageName: null,
-                }),
+                resolveMaintenance: () =>
+                  Effect.succeed(
+                    makeManualOnlyProviderMaintenanceCapabilities({
+                      provider: openCodeDriver,
+                      packageName: null,
+                    }),
+                  ),
                 getSnapshot: Effect.succeed(failedOpenCodeProvider),
                 refresh: Ref.update(openCodeRefreshCalls, (count) => count + 1).pipe(
                   Effect.andThen(Ref.get(catalogSnapshot)),
@@ -1520,10 +1698,13 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             displayName: undefined,
             enabled: true,
             snapshot: {
-              maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-                provider: cursorDriver,
-                packageName: null,
-              }),
+              resolveMaintenance: () =>
+                Effect.succeed(
+                  makeManualOnlyProviderMaintenanceCapabilities({
+                    provider: cursorDriver,
+                    packageName: null,
+                  }),
+                ),
               getSnapshot: Effect.succeed(initialProvider),
               refresh: Effect.succeed(refreshedProvider),
               streamChanges: Stream.fromPubSub(changes),
@@ -1571,18 +1752,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             assert.deepStrictEqual((yield* registry.getProviders)[0]?.models, [
               ...initialProvider.models,
             ]);
+            const persisted = yield* awaitPersistedProvider(registry, refreshedProvider.checkedAt);
             yield* PubSub.publish(changes, refreshedProvider);
-
-            let cachedProvider = yield* readProviderStatusCache(filePath);
-            for (
-              let attempt = 0;
-              attempt < 50 && cachedProvider?.checkedAt !== refreshedProvider.checkedAt;
-              attempt += 1
-            ) {
-              yield* TestClock.adjust("10 millis");
-              yield* Effect.yieldNow;
-              cachedProvider = yield* readProviderStatusCache(filePath);
-            }
+            yield* Fiber.join(persisted);
+            const cachedProvider = yield* readProviderStatusCache(filePath);
 
             assert.deepStrictEqual(cachedProvider, {
               ...refreshedProvider,
@@ -1650,10 +1823,13 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
               displayName: undefined,
               enabled: true,
               snapshot: {
-                maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-                  provider: openCodeDriver,
-                  packageName: null,
-                }),
+                resolveMaintenance: () =>
+                  Effect.succeed(
+                    makeManualOnlyProviderMaintenanceCapabilities({
+                      provider: openCodeDriver,
+                      packageName: null,
+                    }),
+                  ),
                 getSnapshot: Effect.succeed(initialProvider),
                 refresh: Effect.succeed(authoritativeProvider),
                 streamChanges: Stream.fromPubSub(changes),
@@ -1697,31 +1873,23 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
                 instanceId: openCodeInstanceId,
               });
 
+              const authoritativePersisted = yield* awaitPersistedProvider(
+                registry,
+                authoritativeProvider.checkedAt,
+              );
               yield* PubSub.publish(changes, authoritativeProvider);
-
+              yield* Fiber.join(authoritativePersisted);
               let cachedProvider = yield* readProviderStatusCache(filePath);
-              for (
-                let attempt = 0;
-                attempt < 50 && cachedProvider?.checkedAt !== authoritativeProvider.checkedAt;
-                attempt += 1
-              ) {
-                yield* TestClock.adjust("10 millis");
-                yield* Effect.yieldNow;
-                cachedProvider = yield* readProviderStatusCache(filePath);
-              }
 
               assert.deepStrictEqual(cachedProvider?.models, [authoritativeProvider.models[0]!]);
 
+              const failedPersisted = yield* awaitPersistedProvider(
+                registry,
+                failedProvider.checkedAt,
+              );
               yield* PubSub.publish(changes, failedProvider);
-              for (
-                let attempt = 0;
-                attempt < 50 && cachedProvider?.checkedAt !== failedProvider.checkedAt;
-                attempt += 1
-              ) {
-                yield* TestClock.adjust("10 millis");
-                yield* Effect.yieldNow;
-                cachedProvider = yield* readProviderStatusCache(filePath);
-              }
+              yield* Fiber.join(failedPersisted);
+              cachedProvider = yield* readProviderStatusCache(filePath);
 
               assert.deepStrictEqual(cachedProvider?.models, [authoritativeProvider.models[0]!]);
               assert.deepStrictEqual((yield* registry.getProviders)[0]?.models, [
@@ -1758,10 +1926,13 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             displayName: undefined,
             enabled: true,
             snapshot: {
-              maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-                provider: codexDriver,
-                packageName: null,
-              }),
+              resolveMaintenance: () =>
+                Effect.succeed(
+                  makeManualOnlyProviderMaintenanceCapabilities({
+                    provider: codexDriver,
+                    packageName: null,
+                  }),
+                ),
               getSnapshot: Effect.succeed(cachedProvider),
               refresh: Effect.die(new Error("simulated refresh failure")),
               streamChanges: Stream.empty,
@@ -1852,10 +2023,13 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             displayName: undefined,
             enabled: true,
             snapshot: {
-              maintenanceCapabilities: makeManualOnlyProviderMaintenanceCapabilities({
-                provider: provider.driver,
-                packageName: null,
-              }),
+              resolveMaintenance: () =>
+                Effect.succeed(
+                  makeManualOnlyProviderMaintenanceCapabilities({
+                    provider: provider.driver,
+                    packageName: null,
+                  }),
+                ),
               getSnapshot: Effect.succeed(provider),
               refresh: Effect.succeed(provider),
               streamChanges: Stream.empty,
@@ -2534,9 +2708,10 @@ it.layer(Layer.mergeAll(NodeServices.layer, ServerSettingsModule.layerTest(), Te
             claudeCapabilities(),
           );
           assert.strictEqual(status.status, "ready");
+          // The home is resolved through the host Path before it reaches the env.
           assert.deepStrictEqual(
             recorded.commands.map((command) => command.env?.CLAUDE_CONFIG_DIR),
-            [claudeConfigDir],
+            [(yield* Path.Path).resolve(claudeConfigDir)],
           );
         }).pipe(Effect.provide(recorded.layer));
       });
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.ts b/apps/server/src/provider/Layers/ProviderRegistry.ts
index 4c8658e38afc..94dde9f931bb 100644
--- a/apps/server/src/provider/Layers/ProviderRegistry.ts
+++ b/apps/server/src/provider/Layers/ProviderRegistry.ts
@@ -102,15 +102,19 @@ export function upsertProviderWorkspaceSnapshot(
 
 const shouldRetainMissingProviderModels = (provider: ServerProvider): boolean => {
   const isAntigravity = provider.driver === ProviderDriverKind.make("antigravity");
-  if (!isAntigravity && provider.driver !== ProviderDriverKind.make("opencode")) {
+  const isCodex = provider.driver === ProviderDriverKind.make("codex");
+  if (!isAntigravity && !isCodex && provider.driver !== ProviderDriverKind.make("opencode")) {
     return true;
   }
 
-  if (isAntigravity && (!provider.enabled || provider.auth.status === "unauthenticated")) {
+  if (
+    (isAntigravity || isCodex) &&
+    (!provider.enabled || provider.auth.status === "unauthenticated")
+  ) {
     return false;
   }
 
-  // Both drivers replace their inventories after successful catalog discovery.
+  // Successful discovery replaces these inventories so cached retired models disappear.
   // Antigravity's local health check does not authenticate or discover models.
   const isPendingAntigravityAuthentication =
     isAntigravity && provider.status === "warning" && provider.auth.status === "unknown";
@@ -184,7 +188,7 @@ export const mergeProviderSnapshot = (
           : {}),
       };
 
-export const haveProvidersChanged = (
+const haveProvidersChanged = (
   previousProviders: ReadonlyArray<ServerProvider>,
   nextProviders: ReadonlyArray<ServerProvider>,
 ): boolean => !Equal.equals(previousProviders, nextProviders);
@@ -528,14 +532,19 @@ export const ProviderRegistryLive = Layer.effect(
 
     const getProviderMaintenanceCapabilitiesForInstance = Effect.fn(
       "getProviderMaintenanceCapabilitiesForInstance",
-    )(function* (instanceId: ProviderInstanceId, provider: ProviderDriverKind) {
-      const instance = Array.from((yield* Ref.get(liveSubsRef)).values()).find(
-        (candidate) => candidate.instanceId === instanceId,
-      );
-      return (
-        instance?.snapshot.maintenanceCapabilities ??
-        makeManualProviderMaintenanceCapabilities(provider)
-      );
+    )(function* (
+      instanceId: ProviderInstanceId,
+      provider: ProviderDriverKind,
+      options?: { readonly fresh?: boolean },
+    ) {
+      // Read the instance registry, not `liveSubsRef`: the latter trails
+      // reconciliation, and an update must never run a retired instance's
+      // command against a freshly configured executable.
+      const instance = yield* instanceRegistry.getInstance(instanceId);
+      if (!instance || instance.driverKind !== provider) {
+        return makeManualProviderMaintenanceCapabilities(provider);
+      }
+      return yield* instance.snapshot.resolveMaintenance(options);
     });
 
     /**
diff --git a/apps/server/src/provider/Layers/ProviderService.test.ts b/apps/server/src/provider/Layers/ProviderService.test.ts
index fb997b1ab82a..238265ec5a45 100644
--- a/apps/server/src/provider/Layers/ProviderService.test.ts
+++ b/apps/server/src/provider/Layers/ProviderService.test.ts
@@ -32,6 +32,7 @@ import {
 } from "@t3tools/shared/assistantCitations";
 import { createModelSelection } from "@t3tools/shared/model";
 import { it, assert, describe, vi } from "@effect/vitest";
+import { afterAll } from "vite-plus/test";
 
 import * as Cause from "effect/Cause";
 import * as Deferred from "effect/Deferred";
@@ -54,6 +55,7 @@ import {
   ProviderAdapterSessionNotFoundError,
   ProviderUnsupportedError,
   ProviderValidationError,
+  ProviderWorkspaceMissingError,
   type ProviderAdapterError,
 } from "../Errors.ts";
 import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
@@ -79,6 +81,16 @@ const serverConfigTestLayer = ServerConfig.layerTest(process.cwd(), process.cwd(
   Layer.provide(NodeServices.layer),
 );
 
+// startSession verifies the workspace folder exists before dispatching to an
+// adapter, so session cwd fixtures must be real directories.
+const fixtureCwdRoot = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "provider-service-test-"));
+afterAll(() => NodeFS.rmSync(fixtureCwdRoot, { recursive: true, force: true }));
+function fixtureCwd(name: string): string {
+  const dir = NodePath.join(fixtureCwdRoot, name);
+  NodeFS.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
 const asRequestId = (value: string): ApprovalRequestId => ApprovalRequestId.make(value);
 const asEventId = (value: string): EventId => EventId.make(value);
 const asThreadId = (value: string): ThreadId => ThreadId.make(value);
@@ -314,6 +326,69 @@ function makeFakeCodexAdapter(
   };
 }
 
+interface RecordedAnalyticsEvent {
+  readonly event: string;
+  readonly properties?: Readonly<Record<string, unknown>>;
+}
+
+function makeRecordingAnalytics() {
+  const events: Array<RecordedAnalyticsEvent> = [];
+  const layer = Layer.succeed(
+    AnalyticsService.AnalyticsService,
+    AnalyticsService.AnalyticsService.of({
+      record: (event, properties) =>
+        Effect.sync(() => {
+          events.push({ event, ...(properties ? { properties } : {}) });
+        }),
+      flush: Effect.void,
+    }),
+  );
+
+  return {
+    layer,
+    reset: () => {
+      events.length = 0;
+    },
+    eventsByName: (event: string) => events.filter((entry) => entry.event === event),
+  };
+}
+
+function makeStaticInstanceRegistry(
+  entries: ReadonlyArray<readonly [ProviderInstanceId, ProviderAdapterShape<ProviderAdapterError>]>,
+): ProviderAdapterRegistry.ProviderAdapterRegistry["Service"] {
+  const adapters = new Map(entries);
+  const unsupported = (instanceId: ProviderInstanceId) =>
+    new ProviderUnsupportedError({
+      provider: ProviderDriverKind.make(instanceId),
+    });
+
+  return {
+    getByInstance: (instanceId) => {
+      const adapter = adapters.get(instanceId);
+      return adapter ? Effect.succeed(adapter) : Effect.fail(unsupported(instanceId));
+    },
+    getInstanceInfo: (instanceId) => {
+      const adapter = adapters.get(instanceId);
+      return adapter
+        ? Effect.succeed({
+            instanceId,
+            driverKind: adapter.provider,
+            displayName: undefined,
+            enabled: true,
+            continuationIdentity: {
+              driverKind: adapter.provider,
+              continuationKey: `${adapter.provider}:instance:${instanceId}`,
+            },
+          })
+        : Effect.fail(unsupported(instanceId));
+    },
+    listInstances: () => Effect.succeed(Array.from(adapters.keys())),
+    subscribeChanges: Effect.flatMap(PubSub.unbounded<void>(), (pubsub) =>
+      PubSub.subscribe(pubsub),
+    ),
+  };
+}
+
 const advanceTestClock = (ms: number) =>
   TestClock.adjust(`${ms} millis`).pipe(Effect.andThen(Effect.yieldNow));
 
@@ -332,6 +407,7 @@ function makeProviderServiceLayer(
   input: {
     readonly directory?: ProviderSessionDirectory.ProviderSessionDirectory["Service"];
     readonly supportsConversationRollback?: boolean;
+    readonly analyticsLayer?: Layer.Layer<AnalyticsService.AnalyticsService>;
     readonly registry?: ProviderAdapterRegistry.ProviderAdapterRegistry["Service"];
   } = {},
 ) {
@@ -361,11 +437,12 @@ function makeProviderServiceLayer(
   const layer = it.layer(
     Layer.mergeAll(
       makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
         Layer.provide(serverConfigTestLayer),
-        Layer.provideMerge(AnalyticsService.layerTest),
+        Layer.provideMerge(input.analyticsLayer ?? AnalyticsService.layerTest),
         Layer.provide(
           Layer.succeed(
             ProviderEventLoggers.ProviderEventLoggers,
@@ -388,6 +465,126 @@ function makeProviderServiceLayer(
   };
 }
 
+for (const [enabled, completed] of [
+  [false, false],
+  [true, false],
+  [true, true],
+] as const) {
+  it.effect(
+    `persists shutdown recovery before stopping providers when enabled=${enabled}, completed=${completed}`,
+    () =>
+      Effect.gen(function* () {
+        const codex = makeFakeCodexAdapter();
+        const persistence = yield* Layer.build(
+          ProviderSessionDirectoryLive.pipe(
+            Layer.provide(
+              ProviderSessionRuntime.layer.pipe(Layer.provide(SqlitePersistenceMemory)),
+            ),
+          ),
+        );
+        const directory = yield* ProviderSessionDirectory.ProviderSessionDirectory.pipe(
+          Effect.provide(persistence),
+        );
+        const threadId = asThreadId("shutdown-recovery");
+        const turnId = asTurnId("shutdown-recovery-turn");
+        const scope = yield* Scope.make();
+        const services = yield* Layer.build(
+          makeProviderServiceLive().pipe(
+            Layer.provide(NodeServices.layer),
+            Layer.provide(
+              Layer.succeed(ProviderSessionDirectory.ProviderSessionDirectory, directory),
+            ),
+            Layer.provide(
+              Layer.succeed(
+                ProviderAdapterRegistry.ProviderAdapterRegistry,
+                makeStaticInstanceRegistry([[codexInstanceId, codex.adapter]]),
+              ),
+            ),
+            Layer.provide(ServerSettings.layerTest({ continueThreadsAfterServerUpdate: enabled })),
+            Layer.provide(serverConfigTestLayer),
+            Layer.provide(AnalyticsService.layerTest),
+            Layer.provide(
+              Layer.succeed(
+                ProviderEventLoggers.ProviderEventLoggers,
+                ProviderEventLoggers.NoOpProviderEventLoggers,
+              ),
+            ),
+          ),
+        ).pipe(Scope.provide(scope));
+        const provider = yield* ProviderService.ProviderService.pipe(Effect.provide(services));
+        const session = yield* provider.startSession(threadId, {
+          provider: CODEX_DRIVER,
+          providerInstanceId: codexInstanceId,
+          threadId,
+          runtimeMode: "full-access",
+        });
+        codex.listSessions.mockReturnValue(
+          Effect.succeed([
+            {
+              ...session,
+              status: completed ? "ready" : "running",
+              activeTurnId: completed ? undefined : turnId,
+            },
+          ]),
+        );
+        const pending = yield* directory.getBinding(threadId);
+        assert(Option.isSome(pending));
+        yield* directory.upsert({
+          ...pending.value,
+          runtimePayload: { activeTurnId: null, continueAfterServerUpdate: turnId },
+        });
+        const accepted = yield* provider.sendTurn({ threadId, continuation: true });
+        const admitted = yield* directory.getBinding(threadId);
+        assert(Option.isSome(admitted));
+        assert.propertyVal(admitted.value.runtimePayload, "activeTurnId", accepted.turnId);
+        assert.propertyVal(admitted.value.runtimePayload, "continueAfterServerUpdate", null);
+        if (completed) {
+          // Updates can mark an already-admitted turn immediately before it finishes.
+          yield* directory.upsert({
+            ...admitted.value,
+            runtimePayload: {
+              continueAfterServerUpdate: accepted.turnId,
+              continueAfterServerUpdatePrepared: null,
+            },
+          });
+        }
+        const markers: unknown[] = [];
+        codex.stopAll.mockImplementation(() =>
+          Effect.gen(function* () {
+            const binding = yield* directory.getBinding(threadId);
+            assert(Option.isSome(binding));
+            markers.push(binding.value.runtimePayload);
+          }).pipe(Effect.orDie),
+        );
+        yield* Scope.close(scope, Exit.void);
+        const binding = yield* directory.getBinding(threadId);
+        assert(Option.isSome(binding));
+        assert.equal(codex.stopAll.mock.calls.length, 1);
+        assert.deepStrictEqual(binding.value.resumeCursor, session.resumeCursor);
+        assert.equal(binding.value.status, "stopped");
+        assert.propertyVal(markers[0], "activeTurnId", completed ? null : turnId);
+        if (enabled && !completed) {
+          assert.propertyVal(markers[0], "continueAfterServerUpdate", turnId);
+          assert.propertyVal(binding.value.runtimePayload, "continueAfterServerUpdate", turnId);
+        } else if (completed) {
+          assert.propertyVal(
+            binding.value.runtimePayload,
+            "continueAfterServerUpdate",
+            accepted.turnId,
+          );
+          assert.propertyVal(
+            binding.value.runtimePayload,
+            "continueAfterServerUpdatePrepared",
+            null,
+          );
+        } else {
+          assert.propertyVal(markers[0], "continueAfterServerUpdate", null);
+          assert.propertyVal(binding.value.runtimePayload, "continueAfterServerUpdate", null);
+        }
+      }).pipe(Effect.provide(NodeServices.layer)),
+  );
+}
+
 it.effect("ProviderServiceLive catches stopAll failures during shutdown", () =>
   Effect.gen(function* () {
     const codex = makeFakeCodexAdapter();
@@ -413,6 +610,7 @@ it.effect("ProviderServiceLive catches stopAll failures during shutdown", () =>
     const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
     const providerLayer = Layer.mergeAll(
       makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
@@ -440,6 +638,125 @@ it.effect("ProviderServiceLive catches stopAll failures during shutdown", () =>
   }),
 );
 
+it.effect("ProviderServiceLive flushes deferred completions during shutdown", () =>
+  Effect.gen(function* () {
+    const recordedAnalytics = makeRecordingAnalytics();
+    const codex = makeFakeCodexAdapter();
+    const registry = makeStaticInstanceRegistry([[codexInstanceId, codex.adapter]]);
+    const providerAdapterLayer = Layer.succeed(
+      ProviderAdapterRegistry.ProviderAdapterRegistry,
+      registry,
+    );
+    const runtimeRepositoryLayer = ProviderSessionRuntime.layer.pipe(
+      Layer.provide(SqlitePersistenceMemory),
+    );
+    const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
+    const providerLayer = Layer.mergeAll(
+      makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
+        Layer.provide(providerAdapterLayer),
+        Layer.provide(directoryLayer),
+        Layer.provide(defaultServerSettingsLayer),
+        Layer.provide(serverConfigTestLayer),
+        Layer.provide(recordedAnalytics.layer),
+        Layer.provide(
+          Layer.succeed(
+            ProviderEventLoggers.ProviderEventLoggers,
+            ProviderEventLoggers.NoOpProviderEventLoggers,
+          ),
+        ),
+      ),
+      directoryLayer,
+      runtimeRepositoryLayer,
+      NodeServices.layer,
+    );
+    const scope = yield* Scope.make();
+    const runtimeServices = yield* Layer.build(providerLayer).pipe(Scope.provide(scope));
+    const provider = yield* ProviderService.ProviderService.pipe(Effect.provide(runtimeServices));
+    const threadId = asThreadId("thread-turn-analytics-stop-all-deferred");
+    const firstStarted = yield* Deferred.make<void>();
+    const secondStarted = yield* Deferred.make<void>();
+    const sendRelease = yield* Deferred.make<void>();
+    const turnId = asTurnId("turn-analytics-stop-all-deferred");
+    yield* provider.startSession(threadId, {
+      provider: CODEX_DRIVER,
+      providerInstanceId: codexInstanceId,
+      threadId,
+      runtimeMode: "full-access",
+    });
+    codex.sendTurn
+      .mockImplementationOnce(() =>
+        Effect.gen(function* () {
+          yield* Deferred.succeed(firstStarted, undefined);
+          yield* Deferred.await(sendRelease);
+          return { threadId, turnId };
+        }),
+      )
+      .mockImplementationOnce(() =>
+        Effect.gen(function* () {
+          yield* Deferred.succeed(secondStarted, undefined);
+          yield* Deferred.await(sendRelease);
+          return { threadId, turnId: asTurnId("turn-analytics-stop-all-other") };
+        }),
+      );
+
+    const firstSend = yield* provider
+      .sendTurn({ threadId, input: "first", attachments: [] })
+      .pipe(Effect.forkChild);
+    yield* Deferred.await(firstStarted);
+    const secondSend = yield* provider
+      .sendTurn({ threadId, input: "second", attachments: [] })
+      .pipe(Effect.forkChild);
+    yield* Deferred.await(secondStarted);
+
+    const runtimeEvents = yield* Stream.take(provider.streamEvents, 2).pipe(
+      Stream.runDrain,
+      Effect.forkChild,
+    );
+    yield* Effect.yieldNow;
+    codex.emit({
+      type: "turn.started",
+      eventId: asEventId("evt-turn-analytics-stop-all-deferred-start"),
+      provider: CODEX_DRIVER,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      threadId,
+      turnId,
+      payload: { model: "native-stop-all" },
+    });
+    codex.emit({
+      type: "turn.completed",
+      eventId: asEventId("evt-turn-analytics-stop-all-deferred-complete"),
+      provider: CODEX_DRIVER,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      threadId,
+      turnId,
+      payload: {
+        state: "completed",
+        tokenUsage: {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          inputTokens: 1_200,
+          outputTokens: 300,
+          hasSubagents: false,
+        },
+      },
+    });
+    yield* Fiber.join(runtimeEvents);
+    assert.equal(recordedAnalytics.eventsByName("provider.turn.completed").length, 0);
+
+    const closeExit = yield* Scope.close(scope, Exit.void).pipe(Effect.exit);
+    const completed = recordedAnalytics.eventsByName("provider.turn.completed");
+    assert.equal(Exit.isSuccess(closeExit), true);
+    assert.equal(completed.length, 1);
+    assert.equal(completed[0]?.properties?.model, "native-stop-all");
+    assert.equal(completed[0]?.properties?.inputTokens, 1_200);
+    assert.equal(completed[0]?.properties?.outputTokens, 300);
+    yield* Fiber.interrupt(firstSend);
+    yield* Fiber.interrupt(secondSend);
+    assert.equal(recordedAnalytics.eventsByName("provider.turn.completed").length, 1);
+  }),
+);
+
 it.effect("ProviderServiceLive rejects new sessions for disabled providers", () =>
   Effect.gen(function* () {
     const codex = makeFakeCodexAdapter();
@@ -473,6 +790,7 @@ it.effect("ProviderServiceLive rejects new sessions for disabled providers", ()
     );
     const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
     const providerLayer = makeProviderServiceLive().pipe(
+      Layer.provide(NodeServices.layer),
       Layer.provide(providerAdapterLayer),
       Layer.provide(directoryLayer),
       Layer.provide(defaultServerSettingsLayer),
@@ -556,6 +874,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const providerLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(serverSettingsLayer),
@@ -625,6 +944,7 @@ it.effect("ProviderServiceLive rejects new sessions for disabled custom instance
     );
     const directoryLayer = ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer));
     const providerLayer = makeProviderServiceLive().pipe(
+      Layer.provide(NodeServices.layer),
       Layer.provide(providerAdapterLayer),
       Layer.provide(directoryLayer),
       Layer.provide(defaultServerSettingsLayer),
@@ -743,7 +1063,7 @@ unsupportedRollback.layer("ProviderServiceLive unsupported rewind", (it) => {
         yield* provider.startSession(threadId, {
           providerInstanceId: codexInstanceId,
           threadId,
-          cwd: "/tmp/project",
+          cwd: fixtureCwd("project"),
           runtimeMode: "approval-required",
         });
         if (!active) {
@@ -797,6 +1117,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const providerLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, registry)),
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
@@ -917,6 +1238,7 @@ it.effect("ProviderServiceLive keeps persisted resumable sessions on startup", (
     }).pipe(Effect.provide(directoryLayer));
 
     const providerLayer = makeProviderServiceLive().pipe(
+      Layer.provide(NodeServices.layer),
       Layer.provide(Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, registry)),
       Layer.provide(directoryLayer),
       Layer.provide(defaultServerSettingsLayer),
@@ -982,6 +1304,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const firstProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
         ),
@@ -1009,7 +1332,7 @@ it.effect(
         const session = yield* provider.startSession(threadId, {
           provider: ProviderDriverKind.make("codex"),
           providerInstanceId: codexInstanceId,
-          cwd: "/tmp/project",
+          cwd: fixtureCwd("project"),
           runtimeMode: "full-access",
           threadId,
         });
@@ -1042,6 +1365,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const secondProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
         ),
@@ -1079,7 +1403,7 @@ it.effect(
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project");
+        assert.equal(startPayload.cwd, fixtureCwd("project"));
         assert.deepEqual(startPayload.resumeCursor, updatedResumeCursor);
         assert.equal(startPayload.threadId, startedSession.threadId);
       }
@@ -1093,6 +1417,61 @@ it.effect(
 );
 
 routing.layer("ProviderServiceLive routing", (it) => {
+  it.effect.each([CODEX_DRIVER, CLAUDE_AGENT_DRIVER, CURSOR_DRIVER])(
+    "rejects missing, file, and saved workspace paths before starting %s",
+    (driver) =>
+      Effect.gen(function* () {
+        const provider = yield* ProviderService.ProviderService;
+        const adapter =
+          driver === CODEX_DRIVER
+            ? routing.codex
+            : driver === CLAUDE_AGENT_DRIVER
+              ? routing.claude
+              : routing.cursor;
+        const cwd = fixtureCwd(`missing-workspace-${driver}`);
+        const movedCwd = `${cwd}-moved`;
+        const threadId = asThreadId(`missing-workspace-${driver}`);
+        const input = {
+          provider: driver,
+          providerInstanceId: ProviderInstanceId.make(driver),
+          threadId,
+          runtimeMode: "full-access" as const,
+          cwd,
+        };
+
+        yield* provider.startSession(threadId, input);
+        yield* provider.stopSession({ threadId });
+        adapter.startSession.mockClear();
+        NodeFS.renameSync(cwd, movedCwd);
+
+        const failure = yield* provider.startSession(threadId, input).pipe(Effect.flip);
+        assert.instanceOf(failure, ProviderWorkspaceMissingError);
+        assert.include(failure.message, cwd);
+        assert.equal(adapter.startSession.mock.calls.length, 0);
+
+        const { cwd: _cwd, ...savedInput } = input;
+        const savedFailure = yield* provider.startSession(threadId, savedInput).pipe(Effect.flip);
+        assert.instanceOf(savedFailure, ProviderWorkspaceMissingError);
+        assert.include(savedFailure.message, cwd);
+        assert.equal(adapter.startSession.mock.calls.length, 0);
+
+        NodeFS.writeFileSync(cwd, "not a directory");
+        const fileFailure = yield* provider.startSession(threadId, input).pipe(Effect.flip);
+        assert.instanceOf(fileFailure, ProviderWorkspaceMissingError);
+        assert.include(fileFailure.message, cwd);
+        assert.equal(adapter.startSession.mock.calls.length, 0);
+
+        NodeFS.unlinkSync(cwd);
+        NodeFS.renameSync(movedCwd, cwd);
+        const restored = yield* provider.startSession(threadId, savedInput);
+        assert.equal(restored.cwd, cwd);
+        assert.equal(adapter.startSession.mock.calls.length, 1);
+        yield* provider.stopSession({ threadId });
+        adapter.startSession.mockClear();
+        adapter.stopSession.mockClear();
+      }),
+  );
+
   it.effect("allows promptless continuation only for capable providers", () =>
     Effect.gen(function* () {
       const provider = yield* ProviderService.ProviderService;
@@ -1151,7 +1530,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
       assert.equal(session.provider, "codex");
@@ -1221,7 +1600,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project");
+        assert.equal(startPayload.cwd, fixtureCwd("project"));
         assert.deepEqual(startPayload.resumeCursor, session.resumeCursor);
         assert.equal(startPayload.threadId, session.threadId);
       }
@@ -1498,7 +1877,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: CODEX_DRIVER,
         providerInstanceId: codexInstanceId,
         threadId,
-        cwd: "/tmp/feedback-project",
+        cwd: fixtureCwd("feedback-project"),
         runtimeMode: "full-access",
       });
       yield* routing.codex.stopSession(threadId);
@@ -1561,7 +1940,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-attach"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
 
@@ -1636,7 +2015,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
       yield* routing.codex.stopSession(initial.threadId);
@@ -1662,7 +2041,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project");
+        assert.equal(startPayload.cwd, fixtureCwd("project"));
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -1681,7 +2060,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-reap-preserve"),
-        cwd: "/tmp/project-reap-preserve",
+        cwd: fixtureCwd("project-reap-preserve"),
         runtimeMode: "full-access",
       });
 
@@ -1716,7 +2095,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project-reap-preserve");
+        assert.equal(startPayload.cwd, fixtureCwd("project-reap-preserve"));
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -1732,7 +2111,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("claudeAgent"),
         providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-claude"),
-        cwd: "/tmp/project-claude",
+        cwd: fixtureCwd("project-claude"),
         runtimeMode: "full-access",
       });
 
@@ -1748,7 +2127,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         };
         assert.equal(startPayload.provider, "claudeAgent");
         assert.equal(startPayload.providerInstanceId, claudeAgentInstanceId);
-        assert.equal(startPayload.cwd, "/tmp/project-claude");
+        assert.equal(startPayload.cwd, fixtureCwd("project-claude"));
       }
     }),
   );
@@ -1763,7 +2142,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId,
-        cwd: "/tmp/project-binding-mismatch",
+        cwd: fixtureCwd("project-binding-mismatch"),
         runtimeMode: "full-access",
       });
       yield* directory.upsert({
@@ -1793,7 +2172,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId,
-        cwd: "/tmp/project-provider-replacement",
+        cwd: fixtureCwd("project-provider-replacement"),
         runtimeMode: "full-access",
       });
 
@@ -1804,7 +2183,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("claudeAgent"),
         providerInstanceId: claudeAgentInstanceId,
         threadId,
-        cwd: "/tmp/project-provider-replacement",
+        cwd: fixtureCwd("project-provider-replacement"),
         runtimeMode: "full-access",
       });
 
@@ -1831,7 +2210,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-1"),
-        cwd: "/tmp/project-send-turn",
+        cwd: fixtureCwd("project-send-turn"),
         runtimeMode: "full-access",
       });
 
@@ -1856,7 +2235,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "codex");
-        assert.equal(startPayload.cwd, "/tmp/project-send-turn");
+        assert.equal(startPayload.cwd, fixtureCwd("project-send-turn"));
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -1872,7 +2251,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         provider: ProviderDriverKind.make("claudeAgent"),
         providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-claude-send-turn"),
-        cwd: "/tmp/project-claude-send-turn",
+        cwd: fixtureCwd("project-claude-send-turn"),
         modelSelection: createModelSelection(
           ProviderInstanceId.make("claudeAgent"),
           "claude-opus-4-6",
@@ -1903,7 +2282,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "claudeAgent");
-        assert.equal(startPayload.cwd, "/tmp/project-claude-send-turn");
+        assert.equal(startPayload.cwd, fixtureCwd("project-claude-send-turn"));
         assert.deepEqual(
           startPayload.modelSelection,
           createModelSelection(ProviderInstanceId.make("claudeAgent"), "claude-opus-4-6", [
@@ -2067,6 +2446,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(runtimeRepositoryLayer),
       );
       const firstProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
         ),
@@ -2088,7 +2468,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           provider: ProviderDriverKind.make("claudeAgent"),
           providerInstanceId: claudeAgentInstanceId,
           threadId: asThreadId("thread-claude-start"),
-          cwd: "/tmp/project-claude-start",
+          cwd: fixtureCwd("project-claude-start"),
           runtimeMode: "full-access",
         });
       }).pipe(Effect.provide(firstProviderLayer));
@@ -2106,6 +2486,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(runtimeRepositoryLayer),
       );
       const secondProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
         ),
@@ -2129,7 +2510,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           provider: ProviderDriverKind.make("claudeAgent"),
           providerInstanceId: claudeAgentInstanceId,
           threadId: initial.threadId,
-          cwd: "/tmp/project-claude-start",
+          cwd: fixtureCwd("project-claude-start"),
           runtimeMode: "full-access",
         });
       }).pipe(Effect.provide(secondProviderLayer));
@@ -2145,7 +2526,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           threadId?: string;
         };
         assert.equal(startPayload.provider, "claudeAgent");
-        assert.equal(startPayload.cwd, "/tmp/project-claude-start");
+        assert.equal(startPayload.cwd, fixtureCwd("project-claude-start"));
         assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
         assert.equal(startPayload.threadId, initial.threadId);
       }
@@ -2175,6 +2556,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           Layer.provide(runtimeRepositoryLayer),
         );
         const firstProviderLayer = makeProviderServiceLive().pipe(
+          Layer.provide(NodeServices.layer),
           Layer.provide(
             Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
           ),
@@ -2196,7 +2578,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
             provider: ProviderDriverKind.make("claudeAgent"),
             providerInstanceId: claudeAgentInstanceId,
             threadId: asThreadId("thread-claude-cwd"),
-            cwd: "/tmp/project-claude-cwd",
+            cwd: fixtureCwd("project-claude-cwd"),
             runtimeMode: "full-access",
           });
         }).pipe(Effect.provide(firstProviderLayer));
@@ -2209,6 +2591,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           Layer.provide(runtimeRepositoryLayer),
         );
         const secondProviderLayer = makeProviderServiceLive().pipe(
+          Layer.provide(NodeServices.layer),
           Layer.provide(
             Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
           ),
@@ -2247,7 +2630,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
             threadId?: string;
           };
           assert.equal(startPayload.provider, "claudeAgent");
-          assert.equal(startPayload.cwd, "/tmp/project-claude-cwd");
+          assert.equal(startPayload.cwd, fixtureCwd("project-claude-cwd"));
           assert.deepEqual(startPayload.resumeCursor, initial.resumeCursor);
           assert.equal(startPayload.threadId, initial.threadId);
         }
@@ -2282,7 +2665,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         createdAt: "2026-01-01T00:00:00.000Z",
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
-        status: "completed",
+        payload: { state: "completed" },
       };
 
       fanout.codex.emit(completedEvent);
@@ -2349,7 +2732,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         createdAt: "2026-01-01T00:00:00.000Z",
         threadId: session.threadId,
         turnId: asTurnId("turn-1"),
-        status: "completed",
+        payload: { state: "completed" },
       });
 
       yield* Fiber.join(consumer);
@@ -2415,7 +2798,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
           createdAt: "2026-01-01T00:00:00.000Z",
           threadId: session.threadId,
           turnId: asTurnId("turn-1"),
-          status: "completed",
+          payload: { state: "completed" },
         },
       ];
 
@@ -2441,7 +2824,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
         provider: ProviderDriverKind.make("claudeAgent"),
         providerInstanceId: claudeAgentInstanceId,
         threadId: asThreadId("thread-metrics"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
 
@@ -2519,7 +2902,7 @@ fanout.layer("ProviderServiceLive fanout", (it) => {
           provider: ProviderDriverKind.make("claudeAgent"),
           providerInstanceId: claudeAgentInstanceId,
           threadId: asThreadId("thread-send-metrics"),
-          cwd: "/tmp/project-send-metrics",
+          cwd: fixtureCwd("project-send-metrics"),
           runtimeMode: "full-access",
         });
 
@@ -2659,6 +3042,1057 @@ citations.layer("ProviderServiceLive assistant citations", (it) => {
   );
 });
 
+const recordedTurnAnalytics = makeRecordingAnalytics();
+const secondaryCodexInstanceId = ProviderInstanceId.make("codex_work");
+const primaryAnalyticsCodex = makeFakeCodexAdapter();
+const secondaryAnalyticsCodex = makeFakeCodexAdapter();
+const turnAnalytics = makeProviderServiceLayer({
+  analyticsLayer: recordedTurnAnalytics.layer,
+  registry: makeStaticInstanceRegistry([
+    [codexInstanceId, primaryAnalyticsCodex.adapter],
+    [secondaryCodexInstanceId, secondaryAnalyticsCodex.adapter],
+  ]),
+});
+
+turnAnalytics.layer("ProviderServiceLive turn analytics", (it) => {
+  it.effect("records one completed-turn event with the allowed properties", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-complete");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      const turn = yield* provider.sendTurn({
+        threadId,
+        input: "measure this turn",
+        attachments: [],
+        interactionMode: "plan",
+        modelSelection: createModelSelection(codexInstanceId, "gpt-5.6-sol", [
+          { id: "reasoningEffort", value: "high" },
+        ]),
+      });
+      yield* advanceTestClock(40);
+
+      const runtimeEvents = yield* Stream.take(provider.streamEvents, 2).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      const completedEvent: LegacyProviderRuntimeEvent = {
+        type: "turn.completed",
+        eventId: asEventId("evt-turn-analytics-complete"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId: turn.turnId,
+        payload: {
+          state: "completed",
+          tokenUsage: {
+            usageStatus: "complete",
+            usageScope: "main_agent",
+            inputTokens: 1_200,
+            cachedInputTokens: 800,
+            cacheCreationTokens: 100,
+            outputTokens: 300,
+            reasoningTokens: 120,
+            hasSubagents: false,
+          },
+        },
+      };
+      primaryAnalyticsCodex.emit(completedEvent);
+      primaryAnalyticsCodex.emit({
+        ...completedEvent,
+        eventId: asEventId("evt-turn-analytics-complete-duplicate"),
+      });
+      yield* Fiber.join(runtimeEvents);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.deepEqual(completed[0]?.properties, {
+        provider: CODEX_DRIVER,
+        model: "gpt-5.6-sol",
+        effort: "high",
+        interactionMode: "plan",
+        runtimeMode: "full-access",
+        mixedModels: false,
+        durationMs: 40,
+        terminalStatus: "completed",
+        usageStatus: "complete",
+        usageScope: "main_agent",
+        hasSubagents: false,
+        inputTokens: 1_200,
+        cachedInputTokens: 800,
+        cacheCreationTokens: 100,
+        outputTokens: 300,
+        reasoningTokens: 120,
+      });
+    }),
+  );
+
+  it.effect("does not report a generic model variant as reasoning effort", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-generic-variant");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      const turn = yield* provider.sendTurn({
+        threadId,
+        input: "use the provider preset",
+        attachments: [],
+        modelSelection: createModelSelection(codexInstanceId, "provider/model", [
+          { id: "variant", value: "high" },
+        ]),
+      });
+
+      const runtimeEvent = yield* Stream.take(provider.streamEvents, 1).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      primaryAnalyticsCodex.emit({
+        type: "turn.completed",
+        eventId: asEventId("evt-turn-analytics-generic-variant"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId: turn.turnId,
+        payload: { state: "completed" },
+      });
+      yield* Fiber.join(runtimeEvent);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.notProperty(completed[0]?.properties ?? {}, "effort");
+    }),
+  );
+
+  it.effect("ignores model metadata bound to another provider instance", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-mismatched-model-instance");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      const turn = yield* provider.sendTurn({
+        threadId,
+        input: "ignore this mismatched selection",
+        attachments: [],
+        modelSelection: createModelSelection(secondaryCodexInstanceId, "wrong-model", [
+          { id: "reasoningEffort", value: "high" },
+        ]),
+      });
+
+      const runtimeEvent = yield* Stream.take(provider.streamEvents, 1).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      primaryAnalyticsCodex.emit({
+        type: "turn.completed",
+        eventId: asEventId("evt-turn-analytics-mismatched-model-instance"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId: turn.turnId,
+        payload: { state: "completed" },
+      });
+      yield* Fiber.join(runtimeEvent);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.notProperty(completed[0]?.properties ?? {}, "model");
+      assert.notProperty(completed[0]?.properties ?? {}, "effort");
+    }),
+  );
+
+  it.effect("keeps overlapping request metadata with out-of-order adapter responses", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-overlap");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+
+      const firstStarted = yield* Deferred.make<void>();
+      const secondStarted = yield* Deferred.make<void>();
+      const firstRelease = yield* Deferred.make<void>();
+      const secondRelease = yield* Deferred.make<void>();
+      const initialStartsObserved = yield* Deferred.make<void>();
+      let initialStartCount = 0;
+      const firstTurnId = asTurnId("turn-analytics-overlap-first");
+      const secondTurnId = asTurnId("turn-analytics-overlap-second");
+      primaryAnalyticsCodex.sendTurn
+        .mockImplementationOnce((input) =>
+          Effect.gen(function* () {
+            yield* Deferred.succeed(firstStarted, undefined);
+            yield* Deferred.await(firstRelease);
+            return { threadId: input.threadId, turnId: firstTurnId };
+          }),
+        )
+        .mockImplementationOnce((input) =>
+          Effect.gen(function* () {
+            yield* Deferred.succeed(secondStarted, undefined);
+            yield* Deferred.await(secondRelease);
+            return { threadId: input.threadId, turnId: secondTurnId };
+          }),
+        );
+
+      const runtimeEvents = yield* Stream.take(provider.streamEvents, 5).pipe(
+        Stream.tap((event) => {
+          if (event.type !== "turn.started" || initialStartCount >= 2) return Effect.void;
+          initialStartCount += 1;
+          return initialStartCount === 2
+            ? Deferred.succeed(initialStartsObserved, undefined).pipe(Effect.asVoid)
+            : Effect.void;
+        }),
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      const firstSend = yield* provider
+        .sendTurn({
+          threadId,
+          input: "first",
+          attachments: [],
+          interactionMode: "default",
+          modelSelection: createModelSelection(codexInstanceId, "requested-first"),
+        })
+        .pipe(Effect.forkChild);
+      yield* Deferred.await(firstStarted);
+      const secondSend = yield* provider
+        .sendTurn({
+          threadId,
+          input: "second",
+          attachments: [],
+          interactionMode: "plan",
+          modelSelection: createModelSelection(codexInstanceId, "requested-second"),
+        })
+        .pipe(Effect.forkChild);
+      yield* Deferred.await(secondStarted);
+
+      for (const [turnId, suffix] of [
+        [firstTurnId, "first"],
+        [secondTurnId, "second"],
+      ] as const) {
+        primaryAnalyticsCodex.emit({
+          type: "turn.started",
+          eventId: asEventId(`evt-turn-analytics-overlap-start-${suffix}`),
+          provider: CODEX_DRIVER,
+          createdAt: "2026-01-01T00:00:00.000Z",
+          threadId,
+          turnId,
+          payload: { model: `native-${suffix}`, effort: `native-effort-${suffix}` },
+        });
+      }
+      yield* Deferred.await(initialStartsObserved);
+      yield* Deferred.succeed(secondRelease, undefined);
+      yield* Fiber.join(secondSend);
+      primaryAnalyticsCodex.emit({
+        type: "turn.started",
+        eventId: asEventId("evt-turn-analytics-overlap-start-second-duplicate"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId: secondTurnId,
+        payload: { model: "native-second", effort: "native-effort-second" },
+      });
+      yield* Deferred.succeed(firstRelease, undefined);
+      yield* Fiber.join(firstSend);
+      for (const [turnId, suffix] of [
+        [secondTurnId, "second"],
+        [firstTurnId, "first"],
+      ] as const) {
+        primaryAnalyticsCodex.emit({
+          type: "turn.completed",
+          eventId: asEventId(`evt-turn-analytics-overlap-complete-${suffix}`),
+          provider: CODEX_DRIVER,
+          createdAt: "2026-01-01T00:00:00.000Z",
+          threadId,
+          turnId,
+          payload: { state: "completed" },
+        });
+      }
+      yield* Fiber.join(runtimeEvents);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 2);
+      assert.deepInclude(completed[0]?.properties ?? {}, {
+        model: "native-second",
+        effort: "native-effort-second",
+        interactionMode: "plan",
+      });
+      assert.deepInclude(completed[1]?.properties ?? {}, {
+        model: "native-first",
+        effort: "native-effort-first",
+        interactionMode: "default",
+      });
+    }),
+  );
+
+  it.effect("waits for the adapter response when a turn completes before sendTurn returns", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-fast-completion");
+      const turnId = asTurnId("turn-analytics-fast-completion");
+      const returnRelease = yield* Deferred.make<void>();
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      yield* Effect.yieldNow;
+      primaryAnalyticsCodex.sendTurn.mockImplementationOnce((input) =>
+        Effect.gen(function* () {
+          primaryAnalyticsCodex.emit({
+            type: "turn.started",
+            eventId: asEventId("evt-turn-analytics-fast-start"),
+            provider: CODEX_DRIVER,
+            createdAt: "2026-01-01T00:00:00.000Z",
+            threadId,
+            turnId,
+            payload: { model: "native-fast", effort: "high" },
+          });
+          primaryAnalyticsCodex.emit({
+            type: "turn.completed",
+            eventId: asEventId("evt-turn-analytics-fast-complete"),
+            provider: CODEX_DRIVER,
+            createdAt: "2026-01-01T00:00:00.000Z",
+            threadId,
+            turnId,
+            payload: { state: "completed" },
+          });
+          yield* Deferred.await(returnRelease);
+          return { threadId: input.threadId, turnId };
+        }),
+      );
+
+      const terminalReceipt = yield* provider.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      const sendFiber = yield* provider
+        .sendTurn({
+          threadId,
+          input: "finish immediately",
+          attachments: [],
+          interactionMode: "plan",
+          modelSelection: createModelSelection(codexInstanceId, "requested-fast"),
+        })
+        .pipe(Effect.forkChild);
+      const terminal = yield* Fiber.join(terminalReceipt);
+      assert.equal(terminal._tag, "Some");
+      assert.equal(sendFiber.pollUnsafe(), undefined);
+      assert.equal(recordedTurnAnalytics.eventsByName("provider.turn.completed").length, 0);
+
+      yield* Deferred.succeed(returnRelease, undefined);
+      yield* Fiber.join(sendFiber);
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.deepInclude(completed[0]?.properties ?? {}, {
+        model: "native-fast",
+        effort: "high",
+        interactionMode: "plan",
+      });
+    }),
+  );
+
+  it.effect("does not give a synthetic turn the metadata of an in-flight send", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-synthetic-start");
+      const syntheticTurnId = asTurnId("turn-analytics-synthetic");
+      const realTurnId = asTurnId("turn-analytics-real");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      yield* Effect.yieldNow;
+      // Claude closes a leftover synthetic turn while it prepares the real
+      // turn, so both events arrive before sendTurn returns the real turn ID.
+      primaryAnalyticsCodex.sendTurn.mockImplementationOnce((input) =>
+        Effect.gen(function* () {
+          primaryAnalyticsCodex.emit({
+            type: "turn.started",
+            eventId: asEventId("evt-turn-analytics-synthetic-start"),
+            provider: CODEX_DRIVER,
+            createdAt: "2026-01-01T00:00:00.000Z",
+            threadId,
+            turnId: syntheticTurnId,
+            payload: {},
+          });
+          primaryAnalyticsCodex.emit({
+            type: "turn.completed",
+            eventId: asEventId("evt-turn-analytics-synthetic-complete"),
+            provider: CODEX_DRIVER,
+            createdAt: "2026-01-01T00:00:00.000Z",
+            threadId,
+            turnId: syntheticTurnId,
+            payload: { state: "completed" },
+          });
+          primaryAnalyticsCodex.emit({
+            type: "turn.started",
+            eventId: asEventId("evt-turn-analytics-real-start"),
+            provider: CODEX_DRIVER,
+            createdAt: "2026-01-01T00:00:00.000Z",
+            threadId,
+            turnId: realTurnId,
+            payload: { model: "native-real" },
+          });
+          yield* Effect.yieldNow;
+          return { threadId: input.threadId, turnId: realTurnId };
+        }),
+      );
+
+      yield* provider.sendTurn({
+        threadId,
+        input: "start the real turn",
+        attachments: [],
+        interactionMode: "plan",
+        modelSelection: createModelSelection(codexInstanceId, "requested-real"),
+      });
+      const realCompletion = yield* provider.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed" && event.turnId === realTurnId),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      primaryAnalyticsCodex.emit({
+        type: "turn.completed",
+        eventId: asEventId("evt-turn-analytics-real-complete"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId: realTurnId,
+        payload: { state: "completed" },
+      });
+      yield* Fiber.join(realCompletion);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 2);
+      assert.equal(completed[0]?.properties?.interactionMode, undefined);
+      assert.equal(completed[0]?.properties?.model, undefined);
+      assert.deepInclude(completed[1]?.properties ?? {}, {
+        model: "native-real",
+        interactionMode: "plan",
+      });
+    }),
+  );
+
+  it.effect("defers overlapping terminal analytics until exact request association", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-overlap-fast-completion");
+      const firstStarted = yield* Deferred.make<void>();
+      const secondStarted = yield* Deferred.make<void>();
+      const firstRelease = yield* Deferred.make<void>();
+      const secondRelease = yield* Deferred.make<void>();
+      const firstTurnId = asTurnId("turn-analytics-overlap-fast-first");
+      const secondTurnId = asTurnId("turn-analytics-overlap-fast-second");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      primaryAnalyticsCodex.sendTurn
+        .mockImplementationOnce(() =>
+          Effect.gen(function* () {
+            yield* Deferred.succeed(firstStarted, undefined);
+            yield* Deferred.await(firstRelease);
+            return { threadId, turnId: firstTurnId };
+          }),
+        )
+        .mockImplementationOnce(() =>
+          Effect.gen(function* () {
+            yield* Deferred.succeed(secondStarted, undefined);
+            yield* Deferred.await(secondRelease);
+            return { threadId, turnId: secondTurnId };
+          }),
+        );
+
+      const runtimeEvents = yield* Stream.take(provider.streamEvents, 4).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      const firstSend = yield* provider
+        .sendTurn({
+          threadId,
+          input: "first fast completion",
+          attachments: [],
+          interactionMode: "default",
+          modelSelection: createModelSelection(codexInstanceId, "requested-first"),
+        })
+        .pipe(Effect.forkChild);
+      yield* Deferred.await(firstStarted);
+      yield* advanceTestClock(10);
+      const secondSend = yield* provider
+        .sendTurn({
+          threadId,
+          input: "second fast completion",
+          attachments: [],
+          interactionMode: "plan",
+          modelSelection: createModelSelection(codexInstanceId, "requested-second"),
+        })
+        .pipe(Effect.forkChild);
+      yield* Deferred.await(secondStarted);
+      yield* advanceTestClock(20);
+
+      for (const [turnId, suffix] of [
+        [firstTurnId, "first"],
+        [secondTurnId, "second"],
+      ] as const) {
+        primaryAnalyticsCodex.emit({
+          type: "turn.started",
+          eventId: asEventId(`evt-turn-analytics-overlap-fast-start-${suffix}`),
+          provider: CODEX_DRIVER,
+          createdAt: "2026-01-01T00:00:00.000Z",
+          threadId,
+          turnId,
+          payload: { model: `native-${suffix}`, effort: `native-effort-${suffix}` },
+        });
+        primaryAnalyticsCodex.emit({
+          type: "turn.completed",
+          eventId: asEventId(`evt-turn-analytics-overlap-fast-complete-${suffix}`),
+          provider: CODEX_DRIVER,
+          createdAt: "2026-01-01T00:00:00.000Z",
+          threadId,
+          turnId,
+          payload: { state: "completed" },
+        });
+      }
+      yield* Fiber.join(runtimeEvents);
+      assert.equal(recordedTurnAnalytics.eventsByName("provider.turn.completed").length, 0);
+      yield* advanceTestClock(40);
+
+      yield* Deferred.succeed(secondRelease, undefined);
+      yield* Fiber.join(secondSend);
+      let completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.deepInclude(completed[0]?.properties ?? {}, {
+        model: "native-second",
+        effort: "native-effort-second",
+        interactionMode: "plan",
+        durationMs: 20,
+      });
+
+      yield* Deferred.succeed(firstRelease, undefined);
+      yield* Fiber.join(firstSend);
+      completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 2);
+      assert.deepInclude(completed[1]?.properties ?? {}, {
+        model: "native-first",
+        effort: "native-effort-first",
+        interactionMode: "default",
+        durationMs: 30,
+      });
+    }),
+  );
+
+  it.effect("cleans pending metadata when a send is canceled", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-canceled-send");
+      const canceledStarted = yield* Deferred.make<void>();
+      const canceledRelease = yield* Deferred.make<void>();
+      const nextReturnRelease = yield* Deferred.make<void>();
+      const nextTurnId = asTurnId("turn-analytics-after-canceled-send");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      primaryAnalyticsCodex.sendTurn
+        .mockImplementationOnce(() =>
+          Effect.gen(function* () {
+            yield* Deferred.succeed(canceledStarted, undefined);
+            yield* Deferred.await(canceledRelease);
+            return { threadId, turnId: asTurnId("turn-analytics-canceled") };
+          }),
+        )
+        .mockImplementationOnce(() =>
+          Effect.gen(function* () {
+            primaryAnalyticsCodex.emit({
+              type: "turn.started",
+              eventId: asEventId("evt-turn-analytics-after-canceled-start"),
+              provider: CODEX_DRIVER,
+              createdAt: "2026-01-01T00:00:00.000Z",
+              threadId,
+              turnId: nextTurnId,
+              payload: { model: "native-next", effort: "high" },
+            });
+            primaryAnalyticsCodex.emit({
+              type: "turn.completed",
+              eventId: asEventId("evt-turn-analytics-after-canceled-complete"),
+              provider: CODEX_DRIVER,
+              createdAt: "2026-01-01T00:00:00.000Z",
+              threadId,
+              turnId: nextTurnId,
+              payload: { state: "completed" },
+            });
+            yield* Deferred.await(nextReturnRelease);
+            return { threadId, turnId: nextTurnId };
+          }),
+        );
+
+      const canceledSend = yield* provider
+        .sendTurn({
+          threadId,
+          input: "cancel this request",
+          attachments: [],
+          interactionMode: "default",
+        })
+        .pipe(Effect.forkChild);
+      yield* Deferred.await(canceledStarted);
+      yield* Fiber.interrupt(canceledSend);
+
+      const terminalReceipt = yield* provider.streamEvents.pipe(
+        Stream.filter((event) => event.type === "turn.completed"),
+        Stream.runHead,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      const nextSend = yield* provider
+        .sendTurn({
+          threadId,
+          input: "measure the next request",
+          attachments: [],
+          interactionMode: "plan",
+        })
+        .pipe(Effect.forkChild);
+      const terminal = yield* Fiber.join(terminalReceipt);
+      assert.equal(terminal._tag, "Some");
+      assert.equal(nextSend.pollUnsafe(), undefined);
+      // The canceled request must not hold the completion. The live request
+      // still does, until its adapter response links it to the turn.
+      assert.equal(recordedTurnAnalytics.eventsByName("provider.turn.completed").length, 0);
+      yield* Deferred.succeed(nextReturnRelease, undefined);
+      const nextTurn = yield* Fiber.join(nextSend);
+      assert.equal(nextTurn.turnId, nextTurnId);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.deepInclude(completed[0]?.properties ?? {}, {
+        model: "native-next",
+        effort: "high",
+        interactionMode: "plan",
+      });
+    }),
+  );
+
+  it.effect("bounds deferred completions and drains them after sends are canceled", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-bounded-deferred");
+      const allStarted = yield* Deferred.make<void>();
+      const sendRelease = yield* Deferred.make<void>();
+      const turnIds = Array.from({ length: 9 }, (_, index) =>
+        asTurnId(`turn-analytics-bounded-deferred-${index + 1}`),
+      );
+      let startedCount = 0;
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      for (const turnId of turnIds) {
+        primaryAnalyticsCodex.sendTurn.mockImplementationOnce((input) =>
+          Effect.gen(function* () {
+            startedCount += 1;
+            if (startedCount === turnIds.length) {
+              yield* Deferred.succeed(allStarted, undefined);
+            }
+            yield* Deferred.await(sendRelease);
+            return { threadId: input.threadId, turnId };
+          }),
+        );
+      }
+
+      const runtimeEvents = yield* Stream.take(provider.streamEvents, turnIds.length * 2).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      const sends = [];
+      for (let index = 0; index < turnIds.length; index += 1) {
+        sends.push(
+          yield* provider
+            .sendTurn({
+              threadId,
+              input: `bounded deferred ${index + 1}`,
+              attachments: [],
+              interactionMode: index % 2 === 0 ? "default" : "plan",
+            })
+            .pipe(Effect.forkChild),
+        );
+      }
+      yield* Deferred.await(allStarted);
+
+      for (const [index, turnId] of turnIds.entries()) {
+        primaryAnalyticsCodex.emit({
+          type: "turn.started",
+          eventId: asEventId(`evt-turn-analytics-bounded-deferred-start-${index + 1}`),
+          provider: CODEX_DRIVER,
+          createdAt: "2026-01-01T00:00:00.000Z",
+          threadId,
+          turnId,
+          payload: { model: `native-bounded-${index + 1}` },
+        });
+        primaryAnalyticsCodex.emit({
+          type: "turn.completed",
+          eventId: asEventId(`evt-turn-analytics-bounded-deferred-complete-${index + 1}`),
+          provider: CODEX_DRIVER,
+          createdAt: "2026-01-01T00:00:00.000Z",
+          threadId,
+          turnId,
+          payload: { state: "completed" },
+        });
+      }
+      yield* Fiber.join(runtimeEvents);
+      assert.equal(recordedTurnAnalytics.eventsByName("provider.turn.completed").length, 1);
+
+      for (const send of sends) {
+        yield* Fiber.interrupt(send);
+      }
+      assert.equal(recordedTurnAnalytics.eventsByName("provider.turn.completed").length, 9);
+    }),
+  );
+
+  it.effect("flushes a deferred completion when the session stops", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-stop-deferred");
+      const firstStarted = yield* Deferred.make<void>();
+      const secondStarted = yield* Deferred.make<void>();
+      const sendRelease = yield* Deferred.make<void>();
+      const turnId = asTurnId("turn-analytics-stop-deferred");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "full-access",
+      });
+      primaryAnalyticsCodex.sendTurn
+        .mockImplementationOnce(() =>
+          Effect.gen(function* () {
+            yield* Deferred.succeed(firstStarted, undefined);
+            yield* Deferred.await(sendRelease);
+            return { threadId, turnId };
+          }),
+        )
+        .mockImplementationOnce(() =>
+          Effect.gen(function* () {
+            yield* Deferred.succeed(secondStarted, undefined);
+            yield* Deferred.await(sendRelease);
+            return { threadId, turnId: asTurnId("turn-analytics-stop-other") };
+          }),
+        );
+
+      const firstSend = yield* provider
+        .sendTurn({ threadId, input: "first", attachments: [] })
+        .pipe(Effect.forkChild);
+      yield* Deferred.await(firstStarted);
+      const secondSend = yield* provider
+        .sendTurn({ threadId, input: "second", attachments: [] })
+        .pipe(Effect.forkChild);
+      yield* Deferred.await(secondStarted);
+
+      const runtimeEvents = yield* Stream.take(provider.streamEvents, 2).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      primaryAnalyticsCodex.emit({
+        type: "turn.started",
+        eventId: asEventId("evt-turn-analytics-stop-deferred-start"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId,
+        payload: { model: "native-stop" },
+      });
+      primaryAnalyticsCodex.emit({
+        type: "turn.completed",
+        eventId: asEventId("evt-turn-analytics-stop-deferred-complete"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId,
+        payload: { state: "completed" },
+      });
+      yield* Fiber.join(runtimeEvents);
+      assert.equal(recordedTurnAnalytics.eventsByName("provider.turn.completed").length, 0);
+
+      yield* provider.stopSession({ threadId });
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.equal(completed[0]?.properties?.model, "native-stop");
+      yield* Fiber.interrupt(firstSend);
+      yield* Fiber.interrupt(secondSend);
+    }),
+  );
+
+  it.effect("keeps the first metadata when steering reuses a rerouted turn", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-steering");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "auto",
+      });
+      const firstTurn = yield* provider.sendTurn({
+        threadId,
+        input: "start",
+        attachments: [],
+        interactionMode: "default",
+        modelSelection: createModelSelection(codexInstanceId, "gpt-5.6-sol", [
+          { id: "reasoningEffort", value: "high" },
+        ]),
+      });
+      yield* advanceTestClock(10);
+
+      const reroutedEvent = yield* Stream.take(provider.streamEvents, 1).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      primaryAnalyticsCodex.emit({
+        type: "model.rerouted",
+        eventId: asEventId("evt-turn-analytics-rerouted"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId: firstTurn.turnId,
+        payload: {
+          fromModel: "gpt-5.6-sol",
+          toModel: "gpt-5.6-terra",
+          reason: "capacity",
+        },
+      });
+      yield* Fiber.join(reroutedEvent);
+      yield* advanceTestClock(15);
+
+      const steeredTurn = yield* provider.sendTurn({
+        threadId,
+        input: "steer",
+        attachments: [],
+        interactionMode: "plan",
+        modelSelection: createModelSelection(codexInstanceId, "gpt-5.6-terra", [
+          { id: "reasoningEffort", value: "low" },
+        ]),
+      });
+      assert.equal(steeredTurn.turnId, firstTurn.turnId);
+      yield* advanceTestClock(20);
+
+      const completedEvent = yield* Stream.take(provider.streamEvents, 1).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      primaryAnalyticsCodex.emit({
+        type: "turn.completed",
+        eventId: asEventId("evt-turn-analytics-steered-complete"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId: firstTurn.turnId,
+        payload: {
+          state: "completed",
+          tokenUsage: {
+            usageStatus: "complete",
+            usageScope: "main_agent",
+            inputTokens: 500,
+            outputTokens: 100,
+            hasSubagents: false,
+          },
+        },
+      });
+      yield* Fiber.join(completedEvent);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.equal(completed[0]?.properties?.model, "gpt-5.6-sol");
+      assert.equal(completed[0]?.properties?.effort, "high");
+      assert.equal(completed[0]?.properties?.interactionMode, "default");
+      assert.equal(completed[0]?.properties?.mixedModels, true);
+      assert.equal(completed[0]?.properties?.durationMs, 45);
+    }),
+  );
+
+  it.effect("bounds active metadata while preserving recent delayed completions", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-bounded-active");
+      const runtimeEvents = yield* Stream.take(provider.streamEvents, 12).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+
+      for (let index = 1; index <= 10; index += 1) {
+        primaryAnalyticsCodex.emit({
+          type: "turn.started",
+          eventId: asEventId(`evt-turn-analytics-bounded-start-${index}`),
+          provider: CODEX_DRIVER,
+          createdAt: "2026-01-01T00:00:00.000Z",
+          threadId,
+          turnId: asTurnId(`turn-analytics-bounded-${index}`),
+          payload: { model: `model-${index}` },
+        });
+      }
+      for (const index of [3, 1]) {
+        primaryAnalyticsCodex.emit({
+          type: "turn.completed",
+          eventId: asEventId(`evt-turn-analytics-bounded-complete-${index}`),
+          provider: CODEX_DRIVER,
+          createdAt: "2026-01-01T00:00:00.000Z",
+          threadId,
+          turnId: asTurnId(`turn-analytics-bounded-${index}`),
+          payload: { state: "completed" },
+        });
+      }
+      yield* Fiber.join(runtimeEvents);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 2);
+      assert.equal(completed[0]?.properties?.model, "model-3");
+      assert.notProperty(completed[1]?.properties ?? {}, "model");
+    }),
+  );
+
+  it.effect("separates provider instances and omits unavailable counts", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-instances");
+      const turnId = asTurnId("turn-shared-between-instances");
+      const runtimeEvents = yield* Stream.take(provider.streamEvents, 2).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      const event: LegacyProviderRuntimeEvent = {
+        type: "turn.completed",
+        eventId: asEventId("evt-turn-analytics-primary-instance"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId,
+        payload: {
+          state: "completed",
+          tokenUsage: {
+            usageStatus: "unavailable",
+            usageScope: "main_agent",
+            hasSubagents: false,
+          },
+        },
+      };
+      primaryAnalyticsCodex.emit(event);
+      secondaryAnalyticsCodex.emit({
+        ...event,
+        eventId: asEventId("evt-turn-analytics-secondary-instance"),
+      });
+      yield* Fiber.join(runtimeEvents);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 2);
+      for (const entry of completed) {
+        assert.deepEqual(entry.properties, {
+          provider: CODEX_DRIVER,
+          terminalStatus: "completed",
+          usageStatus: "unavailable",
+          usageScope: "main_agent",
+          hasSubagents: false,
+        });
+      }
+    }),
+  );
+
+  it.effect("records known token counts for an interrupted turn", () =>
+    Effect.gen(function* () {
+      recordedTurnAnalytics.reset();
+      const provider = yield* ProviderService.ProviderService;
+      const threadId = asThreadId("thread-turn-analytics-interrupted");
+      yield* provider.startSession(threadId, {
+        provider: CODEX_DRIVER,
+        providerInstanceId: codexInstanceId,
+        threadId,
+        runtimeMode: "approval-required",
+      });
+      const turn = yield* provider.sendTurn({
+        threadId,
+        input: "stop after some work",
+        attachments: [],
+      });
+
+      const runtimeEvent = yield* Stream.take(provider.streamEvents, 1).pipe(
+        Stream.runDrain,
+        Effect.forkChild,
+      );
+      yield* Effect.yieldNow;
+      primaryAnalyticsCodex.emit({
+        type: "turn.aborted",
+        eventId: asEventId("evt-turn-analytics-interrupted"),
+        provider: CODEX_DRIVER,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        threadId,
+        turnId: turn.turnId,
+        payload: {
+          reason: "Interrupted by user",
+          tokenUsage: {
+            usageStatus: "partial",
+            usageScope: "main_agent",
+            inputTokens: 120,
+            outputTokens: 30,
+            hasSubagents: true,
+          },
+        },
+      });
+      yield* Fiber.join(runtimeEvent);
+
+      const completed = recordedTurnAnalytics.eventsByName("provider.turn.completed");
+      assert.equal(completed.length, 1);
+      assert.equal(completed[0]?.properties?.terminalStatus, "interrupted");
+      assert.equal(completed[0]?.properties?.usageStatus, "partial");
+      assert.equal(completed[0]?.properties?.inputTokens, 120);
+      assert.equal(completed[0]?.properties?.outputTokens, 30);
+      assert.equal(completed[0]?.properties?.hasSubagents, true);
+    }),
+  );
+});
+
 const validation = makeProviderServiceLayer();
 validation.layer("ProviderServiceLive validation", (it) => {
   it.effect("rejects citation-expanded input over the provider character limit", () =>
@@ -2803,7 +4237,7 @@ validation.layer("ProviderServiceLive validation", (it) => {
         provider: ProviderDriverKind.make("codex"),
         providerInstanceId: codexInstanceId,
         threadId: asThreadId("thread-missing"),
-        cwd: "/tmp/project",
+        cwd: fixtureCwd("project"),
         runtimeMode: "full-access",
       });
 
@@ -2837,6 +4271,7 @@ const getBinding = vi.fn((threadId: ThreadId) =>
 const boundedListing = makeProviderServiceLayer({
   directory: {
     upsert: () => Effect.void,
+    recordImportedTranscript: () => Effect.die("unused"),
     getProvider: () => Effect.die("ProviderService.listSessions does not use getProvider"),
     getBinding,
     listThreadIds,
@@ -2852,7 +4287,7 @@ boundedListing.layer("ProviderServiceLive session listing", (it) => {
         provider: CODEX_DRIVER,
         providerInstanceId: codexInstanceId,
         threadId: activeSessionThreadId,
-        cwd: "/tmp/project-active-session",
+        cwd: fixtureCwd("project-active-session"),
         runtimeMode: "full-access",
       });
       listThreadIds.mockClear();
diff --git a/apps/server/src/provider/Layers/ProviderService.ts b/apps/server/src/provider/Layers/ProviderService.ts
index 7171430d636b..b853d779763c 100644
--- a/apps/server/src/provider/Layers/ProviderService.ts
+++ b/apps/server/src/provider/Layers/ProviderService.ts
@@ -31,9 +31,11 @@ import {
 } from "@t3tools/contracts";
 import { expandAssistantCitationsForProvider } from "@t3tools/shared/assistantCitations";
 import { causeErrorTag } from "@t3tools/shared/observability";
+import { getModelSelectionStringOptionValue } from "@t3tools/shared/model";
 import * as DateTime from "effect/DateTime";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as PubSub from "effect/PubSub";
@@ -54,8 +56,12 @@ import {
   providerTurnMetricAttributes,
   withMetrics,
 } from "../../observability/Metrics.ts";
-import { ProviderAdapterRequestError } from "../Errors.ts";
-import { type ProviderAdapterError, ProviderValidationError } from "../Errors.ts";
+import {
+  ProviderAdapterRequestError,
+  type ProviderAdapterError,
+  ProviderValidationError,
+  ProviderWorkspaceMissingError,
+} from "../Errors.ts";
 import type { ProviderAdapterShape } from "../Services/ProviderAdapter.ts";
 import * as ProviderAdapterRegistry from "../Services/ProviderAdapterRegistry.ts";
 import * as ProviderService from "../Services/ProviderService.ts";
@@ -96,6 +102,75 @@ export interface ProviderServiceLiveOptions {
   readonly revokeMcpCredential?: typeof McpSessionRegistry.revokeActiveMcpThread;
 }
 
+interface TurnAnalyticsMetadata {
+  readonly requestId: number;
+  readonly provider: ProviderDriverKind;
+  readonly startedAtMs: number;
+  readonly mixedModels: boolean;
+  readonly model?: string;
+  readonly effort?: string;
+  readonly interactionMode?: string;
+  readonly runtimeMode?: string;
+}
+
+interface ActiveTurnAnalytics {
+  readonly metadata: TurnAnalyticsMetadata;
+  readonly requestAssociated: boolean;
+}
+
+interface DeferredTurnAnalyticsCompletion {
+  readonly completionKey: string;
+  readonly completedAtMs: number;
+  readonly terminalProperties: Readonly<Record<string, unknown>>;
+}
+
+interface TurnAnalyticsSessionState {
+  readonly pendingByRequestId: Map<number, TurnAnalyticsMetadata>;
+  readonly activeByTurnId: Map<string, ActiveTurnAnalytics>;
+  readonly deferredCompletionsByTurnId: Map<string, DeferredTurnAnalyticsCompletion>;
+}
+
+interface TurnAnalyticsState {
+  readonly sessions: Map<string, TurnAnalyticsSessionState>;
+  readonly completedKeys: Set<string>;
+  readonly completedOrder: Array<string>;
+}
+
+const MAX_COMPLETED_TURN_ANALYTICS_KEYS = 512;
+const MAX_ACTIVE_TURN_ANALYTICS_PER_SESSION = 8;
+
+function setActiveTurnAnalytics(
+  session: TurnAnalyticsSessionState,
+  turnId: string,
+  active: ActiveTurnAnalytics,
+): void {
+  session.activeByTurnId.set(turnId, active);
+  while (session.activeByTurnId.size > MAX_ACTIVE_TURN_ANALYTICS_PER_SESSION) {
+    const oldestTurnId = session.activeByTurnId.keys().next().value;
+    if (oldestTurnId === undefined) return;
+    session.activeByTurnId.delete(oldestTurnId);
+  }
+}
+
+function turnAnalyticsSessionKey(instanceId: ProviderInstanceId, threadId: ThreadId): string {
+  return `${String(instanceId)}\u0000${String(threadId)}`;
+}
+
+function turnAnalyticsCompletionKey(
+  instanceId: ProviderInstanceId,
+  threadId: ThreadId,
+  turnId: string,
+): string {
+  return `${turnAnalyticsSessionKey(instanceId, threadId)}\u0000${turnId}`;
+}
+
+function turnEffort(modelSelection: ProviderSendTurnInput["modelSelection"]): string | undefined {
+  return (
+    getModelSelectionStringOptionValue(modelSelection, "reasoningEffort") ??
+    getModelSelectionStringOptionValue(modelSelection, "effort")
+  );
+}
+
 type ProviderServiceMethod<Name extends keyof ProviderService.ProviderService["Service"]> =
   ProviderService.ProviderService["Service"][Name];
 
@@ -153,6 +228,7 @@ function toRuntimePayloadFromSession(
   session: ProviderSession,
   extra?: {
     readonly modelSelection?: unknown;
+    readonly continueAfterServerUpdate?: TurnId;
     readonly lastRuntimeEvent?: string;
     readonly lastRuntimeEventAt?: string;
   },
@@ -162,6 +238,9 @@ function toRuntimePayloadFromSession(
     model: session.model ?? null,
     activeTurnId: session.activeTurnId ?? null,
     lastError: session.lastError ?? null,
+    ...(extra?.continueAfterServerUpdate !== undefined
+      ? { continueAfterServerUpdate: extra.continueAfterServerUpdate }
+      : {}),
     ...(extra?.modelSelection !== undefined ? { modelSelection: extra.modelSelection } : {}),
     ...(extra?.lastRuntimeEvent !== undefined ? { lastRuntimeEvent: extra.lastRuntimeEvent } : {}),
     ...(extra?.lastRuntimeEventAt !== undefined
@@ -248,6 +327,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
     options?.issueMcpCredential ?? McpSessionRegistry.issueActiveMcpCredential;
   const revokeMcpCredential =
     options?.revokeMcpCredential ?? McpSessionRegistry.revokeActiveMcpThread;
+  const fileSystem = yield* FileSystem.FileSystem;
   const runtimeEventPubSub = yield* PubSub.unbounded<ProviderRuntimeEvent>();
   const pendingCompactions = new Map<ThreadId, PendingCompaction>();
   const timedOutNativeCompactions = new Set<ThreadId>();
@@ -258,7 +338,366 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
       yield* Deferred.succeed(pending.completion, terminal);
       return true;
     });
+  const turnAnalytics = yield* Ref.make<TurnAnalyticsState>({
+    sessions: new Map(),
+    completedKeys: new Set(),
+    completedOrder: [],
+  });
+  let turnAnalyticsRequestId = 0;
   const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
+
+  const finishTurnAnalytics = (
+    state: TurnAnalyticsState,
+    input: {
+      readonly sessionKey: string;
+      readonly turnId: string;
+      readonly completion: DeferredTurnAnalyticsCompletion;
+    },
+  ): Readonly<Record<string, unknown>> | undefined => {
+    if (state.completedKeys.has(input.completion.completionKey)) return undefined;
+    state.completedKeys.add(input.completion.completionKey);
+    state.completedOrder.push(input.completion.completionKey);
+    while (state.completedOrder.length > MAX_COMPLETED_TURN_ANALYTICS_KEYS) {
+      const expired = state.completedOrder.shift();
+      if (expired) state.completedKeys.delete(expired);
+    }
+
+    const session = state.sessions.get(input.sessionKey);
+    const metadata = session?.activeByTurnId.get(input.turnId)?.metadata;
+    session?.activeByTurnId.delete(input.turnId);
+    session?.deferredCompletionsByTurnId.delete(input.turnId);
+    if (
+      session &&
+      session.activeByTurnId.size === 0 &&
+      session.pendingByRequestId.size === 0 &&
+      session.deferredCompletionsByTurnId.size === 0
+    ) {
+      state.sessions.delete(input.sessionKey);
+    }
+
+    return {
+      ...input.completion.terminalProperties,
+      ...(metadata?.model ? { model: metadata.model } : {}),
+      ...(metadata?.effort ? { effort: metadata.effort } : {}),
+      ...(metadata?.interactionMode ? { interactionMode: metadata.interactionMode } : {}),
+      ...(metadata?.runtimeMode ? { runtimeMode: metadata.runtimeMode } : {}),
+      ...(metadata ? { mixedModels: metadata.mixedModels } : {}),
+      ...(metadata
+        ? { durationMs: Math.max(0, input.completion.completedAtMs - metadata.startedAtMs) }
+        : {}),
+    };
+  };
+
+  const recordCompletedTurnProperties = (
+    properties: ReadonlyArray<Readonly<Record<string, unknown>>>,
+  ) =>
+    Effect.forEach(properties, (entry) => analytics.record("provider.turn.completed", entry), {
+      discard: true,
+    });
+
+  const clearTurnAnalyticsSession = (providerInstanceId: ProviderInstanceId, threadId: ThreadId) =>
+    Effect.gen(function* () {
+      const properties = yield* Ref.modify(turnAnalytics, (state) => {
+        const sessionKey = turnAnalyticsSessionKey(providerInstanceId, threadId);
+        const session = state.sessions.get(sessionKey);
+        const completed: Array<Readonly<Record<string, unknown>>> = [];
+        if (session) {
+          for (const [turnId, completion] of session.deferredCompletionsByTurnId) {
+            const entry = finishTurnAnalytics(state, { sessionKey, turnId, completion });
+            if (entry) completed.push(entry);
+          }
+        }
+        state.sessions.delete(sessionKey);
+        return [completed, state] as const;
+      });
+      yield* recordCompletedTurnProperties(properties);
+    });
+
+  const beginTurnAnalytics = Effect.fn("beginTurnAnalytics")(function* (input: {
+    readonly providerInstanceId: ProviderInstanceId;
+    readonly provider: ProviderDriverKind;
+    readonly threadId: ThreadId;
+    readonly modelSelection: ProviderSendTurnInput["modelSelection"];
+    readonly interactionMode: ProviderSendTurnInput["interactionMode"];
+    readonly runtimeMode: string | undefined;
+  }) {
+    const startedAtMs = DateTime.toEpochMillis(yield* DateTime.now);
+    turnAnalyticsRequestId += 1;
+    const requestId = turnAnalyticsRequestId;
+    const effort = turnEffort(input.modelSelection);
+    return yield* Ref.modify(turnAnalytics, (state) => {
+      const key = turnAnalyticsSessionKey(input.providerInstanceId, input.threadId);
+      const session = state.sessions.get(key) ?? {
+        pendingByRequestId: new Map(),
+        activeByTurnId: new Map(),
+        deferredCompletionsByTurnId: new Map(),
+      };
+      const metadata: TurnAnalyticsMetadata = {
+        provider: input.provider,
+        startedAtMs,
+        mixedModels: false,
+        requestId,
+        ...(input.modelSelection?.model ? { model: input.modelSelection.model } : {}),
+        ...(effort ? { effort } : {}),
+        ...(input.interactionMode ? { interactionMode: input.interactionMode } : {}),
+        ...(input.runtimeMode ? { runtimeMode: input.runtimeMode } : {}),
+      };
+      session.pendingByRequestId.set(requestId, metadata);
+      state.sessions.set(key, session);
+      return [metadata, state] as const;
+    });
+  });
+
+  const clearPendingTurnAnalytics = (input: {
+    readonly providerInstanceId: ProviderInstanceId;
+    readonly threadId: ThreadId;
+    readonly requestId: number;
+  }) =>
+    Effect.gen(function* () {
+      const properties = yield* Ref.modify(turnAnalytics, (state) => {
+        const sessionKey = turnAnalyticsSessionKey(input.providerInstanceId, input.threadId);
+        const session = state.sessions.get(sessionKey);
+        if (!session)
+          return [[] as ReadonlyArray<Readonly<Record<string, unknown>>>, state] as const;
+        session.pendingByRequestId.delete(input.requestId);
+        const completed: Array<Readonly<Record<string, unknown>>> = [];
+        if (session.pendingByRequestId.size === 0) {
+          for (const [turnId, completion] of session.deferredCompletionsByTurnId) {
+            const entry = finishTurnAnalytics(state, { sessionKey, turnId, completion });
+            if (entry) completed.push(entry);
+          }
+        }
+        if (
+          session.activeByTurnId.size === 0 &&
+          session.pendingByRequestId.size === 0 &&
+          session.deferredCompletionsByTurnId.size === 0
+        ) {
+          state.sessions.delete(sessionKey);
+        }
+        return [completed, state] as const;
+      });
+      yield* recordCompletedTurnProperties(properties);
+    });
+
+  const associateTurnAnalytics = (input: {
+    readonly providerInstanceId: ProviderInstanceId;
+    readonly threadId: ThreadId;
+    readonly turnId: string;
+    readonly metadata: TurnAnalyticsMetadata;
+  }) =>
+    Effect.gen(function* () {
+      const properties = yield* Ref.modify(turnAnalytics, (state) => {
+        const completionKey = turnAnalyticsCompletionKey(
+          input.providerInstanceId,
+          input.threadId,
+          input.turnId,
+        );
+        const sessionKey = turnAnalyticsSessionKey(input.providerInstanceId, input.threadId);
+        const session = state.sessions.get(sessionKey);
+        if (!session || state.completedKeys.has(completionKey)) {
+          if (session) {
+            session.pendingByRequestId.delete(input.metadata.requestId);
+            if (
+              session.activeByTurnId.size === 0 &&
+              session.pendingByRequestId.size === 0 &&
+              session.deferredCompletionsByTurnId.size === 0
+            ) {
+              state.sessions.delete(sessionKey);
+            }
+          }
+          return [[] as ReadonlyArray<Readonly<Record<string, unknown>>>, state] as const;
+        }
+        const existing = session.activeByTurnId.get(input.turnId);
+        const existingMetadata = existing?.metadata;
+        const base = existing?.requestAssociated ? existing.metadata : input.metadata;
+        setActiveTurnAnalytics(session, input.turnId, {
+          requestAssociated: true,
+          metadata: {
+            ...base,
+            ...(existingMetadata?.model
+              ? { model: existingMetadata.model }
+              : input.metadata.model
+                ? { model: input.metadata.model }
+                : {}),
+            ...(existingMetadata?.effort
+              ? { effort: existingMetadata.effort }
+              : input.metadata.effort
+                ? { effort: input.metadata.effort }
+                : {}),
+            ...(base?.interactionMode
+              ? {}
+              : input.metadata.interactionMode
+                ? { interactionMode: input.metadata.interactionMode }
+                : {}),
+            ...(base?.runtimeMode
+              ? {}
+              : input.metadata.runtimeMode
+                ? { runtimeMode: input.metadata.runtimeMode }
+                : {}),
+            mixedModels: existingMetadata?.mixedModels ?? input.metadata.mixedModels,
+          },
+        });
+        session.pendingByRequestId.delete(input.metadata.requestId);
+        const completion = session.deferredCompletionsByTurnId.get(input.turnId);
+        const completed = completion
+          ? finishTurnAnalytics(state, {
+              sessionKey,
+              turnId: input.turnId,
+              completion,
+            })
+          : undefined;
+        return [completed ? [completed] : [], state] as const;
+      });
+      yield* recordCompletedTurnProperties(properties);
+    });
+
+  const observeTurnStartedForAnalytics = Effect.fn("observeTurnStartedForAnalytics")(function* (
+    source: { readonly instanceId: ProviderInstanceId; readonly provider: ProviderDriverKind },
+    event: Extract<ProviderRuntimeEvent, { readonly type: "turn.started" }>,
+  ) {
+    if (!event.turnId) return;
+    const observedAtMs = DateTime.toEpochMillis(yield* DateTime.now);
+    yield* Ref.update(turnAnalytics, (state) => {
+      const completionKey = turnAnalyticsCompletionKey(
+        source.instanceId,
+        event.threadId,
+        String(event.turnId),
+      );
+      if (state.completedKeys.has(completionKey)) return state;
+      const sessionKey = turnAnalyticsSessionKey(source.instanceId, event.threadId);
+      const session = state.sessions.get(sessionKey) ?? {
+        pendingByRequestId: new Map(),
+        activeByTurnId: new Map(),
+        deferredCompletionsByTurnId: new Map(),
+      };
+      // A start never binds send metadata on its own. Claude can start a
+      // synthetic turn for leftover agent output while sendTurn is still
+      // preparing the real turn, so only the adapter's sendTurn response
+      // links a request to its turn. Completions that land before that
+      // response wait in deferredCompletionsByTurnId.
+      const current = session.activeByTurnId.get(String(event.turnId));
+      const metadata: TurnAnalyticsMetadata = {
+        ...(current?.metadata ?? {
+          requestId: ++turnAnalyticsRequestId,
+          provider: source.provider,
+          startedAtMs: observedAtMs,
+          mixedModels: false,
+        }),
+        ...(event.payload.model ? { model: event.payload.model } : {}),
+        ...(event.payload.effort ? { effort: event.payload.effort } : {}),
+      };
+      setActiveTurnAnalytics(session, String(event.turnId), {
+        metadata,
+        requestAssociated: current?.requestAssociated ?? false,
+      });
+      state.sessions.set(sessionKey, session);
+      return state;
+    });
+  });
+
+  const observeModelReroutedForAnalytics = (
+    source: { readonly instanceId: ProviderInstanceId },
+    event: Extract<ProviderRuntimeEvent, { readonly type: "model.rerouted" }>,
+  ) =>
+    Ref.update(turnAnalytics, (state) => {
+      const session = state.sessions.get(
+        turnAnalyticsSessionKey(source.instanceId, event.threadId),
+      );
+      if (!session) return state;
+      if (event.turnId) {
+        const current = session.activeByTurnId.get(String(event.turnId));
+        if (current) {
+          session.activeByTurnId.set(String(event.turnId), {
+            ...current,
+            metadata: { ...current.metadata, mixedModels: true },
+          });
+        }
+      } else {
+        for (const [turnId, current] of session.activeByTurnId) {
+          session.activeByTurnId.set(turnId, {
+            ...current,
+            metadata: { ...current.metadata, mixedModels: true },
+          });
+        }
+      }
+      return state;
+    });
+
+  const recordTurnCompletedAnalytics = Effect.fn("recordTurnCompletedAnalytics")(function* (
+    source: { readonly instanceId: ProviderInstanceId; readonly provider: ProviderDriverKind },
+    event: Extract<ProviderRuntimeEvent, { readonly type: "turn.completed" | "turn.aborted" }>,
+  ) {
+    if (!event.turnId) return;
+    const completedAtMs = DateTime.toEpochMillis(yield* DateTime.now);
+    const tokenUsage = event.payload.tokenUsage;
+    const completion: DeferredTurnAnalyticsCompletion = {
+      completionKey: turnAnalyticsCompletionKey(
+        source.instanceId,
+        event.threadId,
+        String(event.turnId),
+      ),
+      completedAtMs,
+      terminalProperties: {
+        provider: source.provider,
+        terminalStatus:
+          event.type === "turn.completed"
+            ? event.payload.state
+            : event.payload.reason.toLowerCase().includes("interrupt")
+              ? "interrupted"
+              : "cancelled",
+        usageStatus: tokenUsage?.usageStatus ?? "unavailable",
+        usageScope: tokenUsage?.usageScope ?? "main_agent",
+        ...(tokenUsage ? { hasSubagents: tokenUsage.hasSubagents } : {}),
+        ...(tokenUsage?.inputTokens !== undefined ? { inputTokens: tokenUsage.inputTokens } : {}),
+        ...(tokenUsage?.cachedInputTokens !== undefined
+          ? { cachedInputTokens: tokenUsage.cachedInputTokens }
+          : {}),
+        ...(tokenUsage?.cacheCreationTokens !== undefined
+          ? { cacheCreationTokens: tokenUsage.cacheCreationTokens }
+          : {}),
+        ...(tokenUsage?.outputTokens !== undefined
+          ? { outputTokens: tokenUsage.outputTokens }
+          : {}),
+        ...(tokenUsage?.reasoningTokens !== undefined
+          ? { reasoningTokens: tokenUsage.reasoningTokens }
+          : {}),
+      },
+    };
+    const properties = yield* Ref.modify(turnAnalytics, (state) => {
+      if (state.completedKeys.has(completion.completionKey)) {
+        return [[] as ReadonlyArray<Readonly<Record<string, unknown>>>, state] as const;
+      }
+      const turnId = String(event.turnId);
+      const sessionKey = turnAnalyticsSessionKey(source.instanceId, event.threadId);
+      const session = state.sessions.get(sessionKey);
+      if (session?.deferredCompletionsByTurnId.has(turnId)) {
+        return [[] as ReadonlyArray<Readonly<Record<string, unknown>>>, state] as const;
+      }
+      const active = session?.activeByTurnId.get(turnId);
+      const needsAssociation =
+        (session?.pendingByRequestId.size ?? 0) > 0 && active?.requestAssociated !== true;
+      if (!session || !needsAssociation) {
+        const completed = finishTurnAnalytics(state, { sessionKey, turnId, completion });
+        return [completed ? [completed] : [], state] as const;
+      }
+
+      session.deferredCompletionsByTurnId.set(turnId, completion);
+      const completed: Array<Readonly<Record<string, unknown>>> = [];
+      while (session.deferredCompletionsByTurnId.size > MAX_ACTIVE_TURN_ANALYTICS_PER_SESSION) {
+        const oldest = session.deferredCompletionsByTurnId.entries().next().value;
+        if (!oldest) break;
+        const [oldestTurnId, oldestCompletion] = oldest;
+        const entry = finishTurnAnalytics(state, {
+          sessionKey,
+          turnId: oldestTurnId,
+          completion: oldestCompletion,
+        });
+        if (entry) completed.push(entry);
+      }
+      return [completed, state] as const;
+    });
+    yield* recordCompletedTurnProperties(properties);
+  });
   /**
    * Attach the `t3-code` MCP server to the session that is about to start.
    *
@@ -402,6 +841,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
     threadId: ThreadId,
     extra?: {
       readonly modelSelection?: unknown;
+      readonly continueAfterServerUpdate?: TurnId;
       readonly lastRuntimeEvent?: string;
       readonly lastRuntimeEventAt?: string;
     },
@@ -437,6 +877,18 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         provider: canonicalEvent.provider,
         eventType: canonicalEvent.type,
       });
+      if (canonicalEvent.type === "turn.started") {
+        yield* observeTurnStartedForAnalytics(source, canonicalEvent);
+      } else if (canonicalEvent.type === "model.rerouted") {
+        yield* observeModelReroutedForAnalytics(source, canonicalEvent);
+      } else if (
+        canonicalEvent.type === "turn.completed" ||
+        canonicalEvent.type === "turn.aborted"
+      ) {
+        yield* recordTurnCompletedAnalytics(source, canonicalEvent);
+      } else if (canonicalEvent.type === "session.exited") {
+        yield* clearTurnAnalyticsSession(source.instanceId, canonicalEvent.threadId);
+      }
       if (
         isCompactedEvent(canonicalEvent) &&
         timedOutNativeCompactions.delete(canonicalEvent.threadId)
@@ -789,7 +1241,22 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
                 : "none",
           "provider.cwd.effective": effectiveCwd ?? "",
         });
+        if (effectiveCwd !== undefined) {
+          // Fail fast with an actionable error when the workspace folder is
+          // gone (e.g. moved, deleted, or replaced by a plain file).
+          // Otherwise every adapter surfaces this as a misleading "failed to
+          // spawn <binary>" process error. Stat failures other than "missing"
+          // fall through to the adapter.
+          const workspaceIsDirectory = yield* fileSystem.stat(effectiveCwd).pipe(
+            Effect.map((workspaceStat) => workspaceStat.type === "Directory"),
+            Effect.catch((statError) => Effect.succeed(statError.reason._tag !== "NotFound")),
+          );
+          if (!workspaceIsDirectory) {
+            return yield* new ProviderWorkspaceMissingError({ threadId, cwd: effectiveCwd });
+          }
+        }
         const adapter = yield* registry.getByInstance(resolvedInstanceId);
+        yield* clearTurnAnalyticsSession(resolvedInstanceId, threadId);
         yield* prepareMcpSession(threadId, resolvedInstanceId);
         const session = yield* adapter
           .startSession({
@@ -953,7 +1420,35 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
       // rather than issuing a new one: sessions that go a long time between
       // browser tool calls used to lose the toolkit outright.
       yield* McpSessionRegistry.touchActiveMcpThread(input.threadId);
-      const turn = yield* routed.adapter.sendTurn(input);
+      const analyticsModelSelection =
+        input.modelSelection?.instanceId === routed.instanceId ? input.modelSelection : undefined;
+      const turn = yield* Effect.acquireUseRelease(
+        beginTurnAnalytics({
+          providerInstanceId: routed.instanceId,
+          provider: routed.adapter.provider,
+          threadId: input.threadId,
+          modelSelection: analyticsModelSelection,
+          interactionMode: input.interactionMode,
+          runtimeMode: routed.runtimeMode,
+        }),
+        (turnMetadata) =>
+          Effect.gen(function* () {
+            const turn = yield* routed.adapter.sendTurn(input);
+            yield* associateTurnAnalytics({
+              providerInstanceId: routed.instanceId,
+              threadId: input.threadId,
+              turnId: String(turn.turnId),
+              metadata: turnMetadata,
+            });
+            return turn;
+          }),
+        (turnMetadata) =>
+          clearPendingTurnAnalytics({
+            providerInstanceId: routed.instanceId,
+            threadId: input.threadId,
+            requestId: turnMetadata.requestId,
+          }),
+      );
       yield* directory.upsert({
         threadId: input.threadId,
         provider: routed.adapter.provider,
@@ -963,6 +1458,9 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
         runtimePayload: {
           ...(input.modelSelection !== undefined ? { modelSelection: input.modelSelection } : {}),
           activeTurnId: turn.turnId,
+          // Admission and marker consumption must survive the same restart.
+          continueAfterServerUpdate: null,
+          continueAfterServerUpdatePrepared: null,
           lastRuntimeEvent: "provider.sendTurn",
           lastRuntimeEventAt: yield* nowIso,
         },
@@ -1254,6 +1752,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
           yield* settleCompaction(input.threadId, pendingCompaction, "turn.aborted");
         }
         timedOutNativeCompactions.delete(input.threadId);
+        yield* clearTurnAnalyticsSession(routed.instanceId, input.threadId);
         yield* clearMcpSession(input.threadId);
         yield* directory.upsert({
           threadId: input.threadId,
@@ -1262,6 +1761,8 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
           status: "stopped",
           runtimePayload: {
             activeTurnId: null,
+            continueAfterServerUpdate: null,
+            continueAfterServerUpdatePrepared: null,
           },
         });
         yield* analytics.record("provider.session.stopped", {
@@ -1471,6 +1972,22 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
   );
 
   const runStopAll = Effect.fn("runStopAll")(function* () {
+    const continueAfterRestart = yield* serverSettings.getSettings.pipe(
+      Effect.map((settings) => settings.continueThreadsAfterServerUpdate),
+      Effect.orElseSucceed(() => false),
+    );
+    const properties = yield* Ref.modify(turnAnalytics, (state) => {
+      const completed: Array<Readonly<Record<string, unknown>>> = [];
+      for (const [sessionKey, session] of state.sessions) {
+        for (const [turnId, completion] of session.deferredCompletionsByTurnId) {
+          const entry = finishTurnAnalytics(state, { sessionKey, turnId, completion });
+          if (entry) completed.push(entry);
+        }
+      }
+      state.sessions.clear();
+      return [completed, state] as const;
+    });
+    yield* recordCompletedTurnProperties(properties);
     const threadIds = yield* directory.listThreadIds();
     const currentAdapters = yield* getAdapterEntries;
     const activeSessions = yield* Effect.forEach(currentAdapters, ([instanceId, adapter]) =>
@@ -1486,6 +2003,9 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
     yield* Effect.forEach(activeSessions, (session) =>
       Effect.flatMap(nowIso, (lastRuntimeEventAt) =>
         upsertSessionBinding(session, session.threadId, {
+          ...(continueAfterRestart && session.status === "running" && session.activeTurnId
+            ? { continueAfterServerUpdate: session.activeTurnId }
+            : {}),
           lastRuntimeEvent: "provider.stopAll",
           lastRuntimeEventAt,
         }),
diff --git a/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts b/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts
index 079b7f10ebfd..8b41bd3e518c 100644
--- a/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionDirectory.test.ts
@@ -4,9 +4,13 @@ import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { ProviderDriverKind, ThreadId } from "@t3tools/contracts";
-import { it, assert } from "@effect/vitest";
-import { assertSome } from "@effect/vitest/utils";
+import {
+  ProviderDriverKind,
+  ProviderInstanceId,
+  ThreadId,
+  type AgentSessionImportSource,
+} from "@t3tools/contracts";
+import { assert, expect, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
@@ -20,9 +24,22 @@ import * as ProviderSessionRuntime from "../../persistence/ProviderSessionRuntim
 import { ProviderSessionDirectory } from "../Services/ProviderSessionDirectory.ts";
 import { ProviderSessionDirectoryLive } from "./ProviderSessionDirectory.ts";
 
+const importedSource = {
+  provider: "codex",
+  providerInstanceId: ProviderInstanceId.make("codex"),
+  providerSessionId: "provider-session",
+  filePath: "/tmp/provider-session.jsonl",
+  size: 100,
+  mtimeMs: 1_000,
+  device: 1,
+  inode: 123,
+  birthtimeMs: 500,
+} satisfies AgentSessionImportSource;
+
 function makeDirectoryLayer<E, R>(persistenceLayer: Layer.Layer<SqlClient.SqlClient, E, R>) {
   const runtimeRepositoryLayer = ProviderSessionRuntime.layer.pipe(Layer.provide(persistenceLayer));
   return Layer.mergeAll(
+    persistenceLayer,
     runtimeRepositoryLayer,
     ProviderSessionDirectoryLive.pipe(Layer.provide(runtimeRepositoryLayer)),
     NodeServices.layer,
@@ -30,7 +47,7 @@ function makeDirectoryLayer<E, R>(persistenceLayer: Layer.Layer<SqlClient.SqlCli
 }
 
 it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryLive", (it) => {
-  it("upserts and reads thread bindings", () =>
+  it.effect("upserts and reads thread bindings", () =>
     Effect.gen(function* () {
       const directory = yield* ProviderSessionDirectory;
       const runtimeRepository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
@@ -39,13 +56,14 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
 
       yield* directory.upsert({
         provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: ProviderInstanceId.make("codex"),
         threadId: initialThreadId,
       });
 
       const provider = yield* directory.getProvider(initialThreadId);
       assert.equal(provider, "codex");
       const resolvedBinding = yield* directory.getBinding(initialThreadId);
-      assertSome(resolvedBinding, {
+      expect(Option.getOrThrow(resolvedBinding)).toMatchObject({
         threadId: initialThreadId,
         provider: ProviderDriverKind.make("codex"),
       });
@@ -57,6 +75,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
 
       yield* directory.upsert({
         provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: ProviderInstanceId.make("codex"),
         threadId: nextThreadId,
       });
       const updatedBinding = yield* directory.getBinding(nextThreadId);
@@ -74,10 +93,11 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       }
 
       const threadIds = yield* directory.listThreadIds();
-      assert.deepEqual(threadIds, [nextThreadId]);
-    }));
+      expect(threadIds).toEqual(expect.arrayContaining([initialThreadId, nextThreadId]));
+    }),
+  );
 
-  it("persists runtime fields and merges payload updates", () =>
+  it.effect("persists runtime fields and merges payload updates", () =>
     Effect.gen(function* () {
       const directory = yield* ProviderSessionDirectory;
       const runtimeRepository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
@@ -86,6 +106,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
 
       yield* directory.upsert({
         provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: ProviderInstanceId.make("codex"),
         threadId,
         status: "starting",
         resumeCursor: {
@@ -99,6 +120,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
 
       yield* directory.upsert({
         provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: ProviderInstanceId.make("codex"),
         threadId,
         status: "running",
         runtimePayload: {
@@ -120,9 +142,158 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
           activeTurnId: "turn-1",
         });
       }
-    }));
+    }),
+  );
+
+  it.effect("keeps the existing binding when an insert conflicts", () =>
+    Effect.gen(function* () {
+      const directory = yield* ProviderSessionDirectory;
+      const threadId = ThreadId.make("thread-insert-conflict");
+
+      yield* directory.upsert({
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: ProviderInstanceId.make("codex"),
+        threadId,
+        status: "running",
+        resumeCursor: { threadId: "active-provider-thread" },
+      });
+
+      yield* directory.upsert(
+        {
+          provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: ProviderInstanceId.make("codex"),
+          threadId,
+          status: "stopped",
+          resumeCursor: { threadId: "stale-provider-thread" },
+        },
+        { onConflict: "ignore" },
+      );
+
+      const binding = yield* directory.getBinding(threadId);
+      expect(Option.getOrThrow(binding)).toMatchObject({
+        threadId,
+        status: "running",
+        resumeCursor: { threadId: "active-provider-thread" },
+      });
+    }),
+  );
+
+  it.effect("records source files without replacing the current provider session", () =>
+    Effect.gen(function* () {
+      const directory = yield* ProviderSessionDirectory;
+      const repository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
+      const source = { ...importedSource, providerSessionId: "record-source" };
+      const threadId = ThreadId.make(
+        `import:${source.providerInstanceId}:${source.providerSessionId}`,
+      );
+      const runtimePayload = { cwd: "/tmp/project", activeTurnId: "active-turn" };
+      yield* directory.upsert({
+        threadId,
+        provider: ProviderDriverKind.make("claudeAgent"),
+        providerInstanceId: ProviderInstanceId.make("claude-current"),
+        status: "running",
+        resumeCursor: { resume: "current-native-session" },
+        runtimePayload,
+      });
+      const before = Option.getOrThrow(yield* repository.getByThreadId({ threadId }));
+
+      yield* directory.recordImportedTranscript({ threadId, source });
+      const replacement = { ...source, size: 200, mtimeMs: 2_000 };
+      yield* directory.recordImportedTranscript({ threadId, source: replacement });
+      const secondFile = { ...source, filePath: "/tmp/provider-session-copy.jsonl" };
+      yield* directory.recordImportedTranscript({ threadId, source: secondFile });
+
+      expect(Option.getOrThrow(yield* repository.getByThreadId({ threadId }))).toEqual({
+        ...before,
+        runtimePayload: { ...runtimePayload, importedTranscripts: [replacement, secondFile] },
+      });
+    }),
+  );
+
+  it.effect("does not create a binding when recording an imported transcript", () =>
+    Effect.gen(function* () {
+      const directory = yield* ProviderSessionDirectory;
+      const threadId = ThreadId.make("import:codex:missing-source-binding");
+
+      yield* directory.recordImportedTranscript({ threadId, source: importedSource });
+
+      expect(Option.isNone(yield* directory.getBinding(threadId))).toBe(true);
+    }),
+  );
+
+  it.effect("keeps newly recorded sources when a runtime write uses a stale payload", () =>
+    Effect.gen(function* () {
+      const directory = yield* ProviderSessionDirectory;
+      const repository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
+      const firstSource = { ...importedSource, providerSessionId: "stale-source" };
+      const threadId = ThreadId.make(
+        `import:${firstSource.providerInstanceId}:${firstSource.providerSessionId}`,
+      );
+      yield* directory.upsert({
+        threadId,
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId: ProviderInstanceId.make("codex"),
+        status: "stopped",
+        resumeCursor: { threadId: "original-native-session" },
+        runtimePayload: { cwd: "/tmp/stale-source-project" },
+      });
+      yield* directory.recordImportedTranscript({ threadId, source: firstSource });
+      const stale = Option.getOrThrow(yield* repository.getByThreadId({ threadId }));
+      const secondSource = { ...firstSource, filePath: "/tmp/stale-source-copy.jsonl" };
+      yield* directory.recordImportedTranscript({ threadId, source: secondSource });
+
+      yield* repository.upsert({
+        ...stale,
+        status: "running",
+        resumeCursor: { threadId: "new-native-session" },
+        lastSeenAt: "2026-08-24T10:00:00.000Z",
+      });
+
+      expect(Option.getOrThrow(yield* repository.getByThreadId({ threadId }))).toEqual({
+        ...stale,
+        status: "running",
+        resumeCursor: { threadId: "new-native-session" },
+        lastSeenAt: "2026-08-24T10:00:00.000Z",
+        runtimePayload: {
+          cwd: "/tmp/stale-source-project",
+          importedTranscripts: [firstSource, secondSource],
+        },
+      });
+    }),
+  );
+
+  it.effect("reserves imported source records for the atomic recording method", () =>
+    Effect.gen(function* () {
+      const directory = yield* ProviderSessionDirectory;
+      for (const onConflict of ["update", "ignore"] as const) {
+        const source = { ...importedSource, providerSessionId: `reserved-source-${onConflict}` };
+        const threadId = ThreadId.make(
+          `import:${source.providerInstanceId}:${source.providerSessionId}`,
+        );
+        const binding = {
+          threadId,
+          provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: ProviderInstanceId.make("codex"),
+        };
+        yield* directory.upsert(
+          { ...binding, runtimePayload: { cwd: "/tmp/project", importedTranscripts: [source] } },
+          { onConflict },
+        );
+        expect(Option.getOrThrow(yield* directory.getBinding(threadId)).runtimePayload).toEqual({
+          cwd: "/tmp/project",
+        });
+
+        yield* directory.recordImportedTranscript({ threadId, source });
+        yield* directory.upsert({ ...binding, runtimePayload: null });
+
+        expect(Option.getOrThrow(yield* directory.getBinding(threadId)).runtimePayload).toEqual({
+          importedTranscripts: [source],
+        });
+      }
+    }),
+  );
 
-  it("lists persisted bindings with metadata in oldest-first order", () =>
+  it.effect("lists persisted bindings with metadata in oldest-first order", () =>
     Effect.gen(function* () {
       const directory = yield* ProviderSessionDirectory;
       const runtimeRepository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
@@ -162,12 +333,15 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
         },
       });
 
-      const bindings = yield* directory.listBindings();
+      const bindings = (yield* directory.listBindings()).filter(
+        (binding) => binding.threadId === olderThreadId || binding.threadId === newerThreadId,
+      );
 
       assert.deepEqual(bindings, [
         {
           threadId: olderThreadId,
           provider: ProviderDriverKind.make("claudeAgent"),
+          providerInstanceId: ProviderInstanceId.make("claudeAgent"),
           adapterKey: "claudeAgent",
           runtimeMode: "approval-required",
           status: "starting",
@@ -182,6 +356,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
         {
           threadId: newerThreadId,
           provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: ProviderInstanceId.make("codex"),
           adapterKey: "codex",
           runtimeMode: "full-access",
           status: "running",
@@ -194,40 +369,45 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
           },
         },
       ]);
-    }));
+    }),
+  );
 
-  it("resets adapterKey to the new provider when provider changes without an explicit adapter key", () =>
-    Effect.gen(function* () {
-      const directory = yield* ProviderSessionDirectory;
-      const runtimeRepository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
-      const threadId = ThreadId.make("thread-provider-change");
+  it.effect(
+    "resets adapterKey to the new provider when provider changes without an explicit adapter key",
+    () =>
+      Effect.gen(function* () {
+        const directory = yield* ProviderSessionDirectory;
+        const runtimeRepository = yield* ProviderSessionRuntime.ProviderSessionRuntimeRepository;
+        const threadId = ThreadId.make("thread-provider-change");
 
-      yield* runtimeRepository.upsert({
-        threadId,
-        providerName: "claudeAgent",
-        providerInstanceId: null,
-        adapterKey: "claudeAgent",
-        runtimeMode: "full-access",
-        status: "running",
-        lastSeenAt: "2026-01-01T00:00:00.000Z",
-        resumeCursor: null,
-        runtimePayload: null,
-      });
+        yield* runtimeRepository.upsert({
+          threadId,
+          providerName: "claudeAgent",
+          providerInstanceId: null,
+          adapterKey: "claudeAgent",
+          runtimeMode: "full-access",
+          status: "running",
+          lastSeenAt: "2026-01-01T00:00:00.000Z",
+          resumeCursor: null,
+          runtimePayload: null,
+        });
 
-      yield* directory.upsert({
-        provider: ProviderDriverKind.make("codex"),
-        threadId,
-      });
+        yield* directory.upsert({
+          provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: ProviderInstanceId.make("codex"),
+          threadId,
+        });
 
-      const runtime = yield* runtimeRepository.getByThreadId({ threadId });
-      assert.equal(Option.isSome(runtime), true);
-      if (Option.isSome(runtime)) {
-        assert.equal(runtime.value.providerName, "codex");
-        assert.equal(runtime.value.adapterKey, "codex");
-      }
-    }));
+        const runtime = yield* runtimeRepository.getByThreadId({ threadId });
+        assert.equal(Option.isSome(runtime), true);
+        if (Option.isSome(runtime)) {
+          assert.equal(runtime.value.providerName, "codex");
+          assert.equal(runtime.value.adapterKey, "codex");
+        }
+      }),
+  );
 
-  it("rehydrates persisted mappings across layer restart", () =>
+  it.effect("rehydrates persisted mappings across layer restart", () =>
     Effect.gen(function* () {
       const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-provider-directory-"));
       const dbPath = NodePath.join(tempDir, "orchestration.sqlite");
@@ -239,6 +419,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
         const directory = yield* ProviderSessionDirectory;
         yield* directory.upsert({
           provider: ProviderDriverKind.make("codex"),
+          providerInstanceId: ProviderInstanceId.make("codex"),
           threadId,
         });
       }).pipe(Effect.provide(directoryLayer));
@@ -250,7 +431,7 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
         assert.equal(provider, "codex");
 
         const resolvedBinding = yield* directory.getBinding(threadId);
-        assertSome(resolvedBinding, {
+        expect(Option.getOrThrow(resolvedBinding)).toMatchObject({
           threadId,
           provider: ProviderDriverKind.make("codex"),
         });
@@ -267,5 +448,6 @@ it.layer(makeDirectoryLayer(SqlitePersistenceMemory))("ProviderSessionDirectoryL
       }).pipe(Effect.provide(directoryLayer));
 
       NodeFS.rmSync(tempDir, { recursive: true, force: true });
-    }));
+    }),
+  );
 });
diff --git a/apps/server/src/provider/Layers/ProviderSessionDirectory.ts b/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
index 253a954d2102..29ec8d2ed168 100644
--- a/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionDirectory.ts
@@ -100,7 +100,7 @@ const makeProviderSessionDirectory = Effect.gen(function* () {
       ),
     );
 
-  const upsert: ProviderSessionDirectoryShape["upsert"] = Effect.fn(function* (binding) {
+  const upsert: ProviderSessionDirectoryShape["upsert"] = Effect.fn(function* (binding, options) {
     const existing = yield* repository
       .getByThreadId({ threadId: binding.threadId })
       .pipe(Effect.mapError(toPersistenceError("ProviderSessionDirectory.upsert:getByThreadId")));
@@ -126,25 +126,30 @@ const makeProviderSessionDirectory = Effect.gen(function* () {
       });
     }
     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,
-        ),
-      })
+      .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,
+          ),
+        },
+        options,
+      )
       .pipe(Effect.mapError(toPersistenceError("ProviderSessionDirectory.upsert:upsert")));
   });
 
@@ -164,6 +169,15 @@ const makeProviderSessionDirectory = Effect.gen(function* () {
       ),
     );
 
+  const recordImportedTranscript: ProviderSessionDirectoryShape["recordImportedTranscript"] = (
+    input,
+  ) =>
+    repository
+      .recordImportedTranscript(input)
+      .pipe(
+        Effect.mapError(toPersistenceError("ProviderSessionDirectory.recordImportedTranscript")),
+      );
+
   const listThreadIds: ProviderSessionDirectoryShape["listThreadIds"] = () =>
     repository.list().pipe(
       Effect.mapError(toPersistenceError("ProviderSessionDirectory.listThreadIds:list")),
@@ -184,6 +198,7 @@ const makeProviderSessionDirectory = Effect.gen(function* () {
 
   return {
     upsert,
+    recordImportedTranscript,
     getProvider,
     getBinding,
     listThreadIds,
diff --git a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
index e5d6beb25d54..c680a8228e3b 100644
--- a/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionReaper.test.ts
@@ -217,8 +217,10 @@ describe("ProviderSessionReaper", () => {
           getActiveProjectByWorkspaceRoot: () => Effect.die("unused"),
           getProjectShellById: () => Effect.die("unused"),
           getFirstActiveThreadIdByProjectId: () => Effect.die("unused"),
+          getImportedAgentSessionSources: () => Effect.die("unused"),
           getThreadCheckpointContext: () => Effect.die("unused"),
           getFullThreadDiffContext: () => Effect.die("unused"),
+          getThreadRuntimeContext: () => Effect.die("unused"),
           getThreadShellById: (threadId) =>
             Effect.succeed(
               input.readModel.threads.find((thread) => thread.id === threadId)
diff --git a/apps/server/src/provider/ModelManifest.test.ts b/apps/server/src/provider/ModelManifest.test.ts
index 73049ad01c30..bb592a0a6fc8 100644
--- a/apps/server/src/provider/ModelManifest.test.ts
+++ b/apps/server/src/provider/ModelManifest.test.ts
@@ -17,7 +17,6 @@ import {
   make,
   resolveProviderCatalog,
   type ModelManifestData,
-  manifestUpdatedAtMs,
   encodeManifestCache,
 } from "./ModelManifest.ts";
 
@@ -382,7 +381,6 @@ describe("ModelManifest service", () => {
       const fs = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
       const config = yield* ServerConfig.ServerConfig;
-      assert.isAbove(manifestUpdatedAtMs(BUNDLED_MODEL_MANIFEST), 0);
       const cachePath = path.join(config.stateDir, "model-manifest.json");
       // A cache of the manifest as it was before the release edited it. The
       // fetch time is irrelevant: the remote may be unreachable now, so
diff --git a/apps/server/src/provider/ModelManifest.ts b/apps/server/src/provider/ModelManifest.ts
index c3cb36566c02..67a7334f613d 100644
--- a/apps/server/src/provider/ModelManifest.ts
+++ b/apps/server/src/provider/ModelManifest.ts
@@ -138,7 +138,7 @@ export const BUNDLED_MODEL_MANIFEST: ModelManifestData =
   Schema.decodeUnknownSync(ModelManifestSchema)(bundledManifestJson);
 
 /** Epoch millis of the manifest's `updatedAt`, or 0 when absent or unparsable. */
-export function manifestUpdatedAtMs(manifest: ModelManifestData): number {
+function manifestUpdatedAtMs(manifest: ModelManifestData): number {
   if (manifest.updatedAt === undefined) return 0;
   const parsed = Date.parse(manifest.updatedAt);
   return Number.isNaN(parsed) ? 0 : parsed;
diff --git a/apps/server/src/provider/ProviderInstanceEnvironment.test.ts b/apps/server/src/provider/ProviderInstanceEnvironment.test.ts
index 7ac3f2f2837d..7d6bbe61a2aa 100644
--- a/apps/server/src/provider/ProviderInstanceEnvironment.test.ts
+++ b/apps/server/src/provider/ProviderInstanceEnvironment.test.ts
@@ -1,8 +1,55 @@
-import { describe, expect, it } from "vite-plus/test";
+import * as NodeOS from "node:os";
+
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Path from "effect/Path";
 
 import { mergeProviderInstanceEnvironment } from "./ProviderInstanceEnvironment.ts";
 
 describe("mergeProviderInstanceEnvironment", () => {
+  it.effect.each([
+    { value: "~/.account", tail: ".account" },
+    { value: "~\\.account\\work", tail: ".account\\work" },
+  ])("expands configured provider homes set to $value", ({ value, tail }) =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const baseEnv = {
+        CODEX_HOME: "~/.inherited-codex",
+        CLAUDE_CONFIG_DIR: "~/.inherited-claude",
+      };
+      const environment = mergeProviderInstanceEnvironment(
+        [
+          { name: "CODEX_HOME", value, sensitive: false },
+          { name: "CLAUDE_CONFIG_DIR", value, sensitive: false },
+          { name: "CUSTOM_VALUE", value, sensitive: false },
+        ],
+        baseEnv,
+      );
+
+      expect(environment).toEqual({
+        CODEX_HOME: path.join(NodeOS.homedir(), tail),
+        CLAUDE_CONFIG_DIR: path.join(NodeOS.homedir(), tail),
+        CUSTOM_VALUE: value,
+      });
+      expect(baseEnv).toEqual({
+        CODEX_HOME: "~/.inherited-codex",
+        CLAUDE_CONFIG_DIR: "~/.inherited-claude",
+      });
+    }).pipe(Effect.provide(NodeServices.layer)),
+  );
+
+  it("leaves inherited provider homes unchanged", () => {
+    const baseEnv = { CODEX_HOME: "~/.codex", CLAUDE_CONFIG_DIR: "~\\.claude" };
+
+    expect(
+      mergeProviderInstanceEnvironment(
+        [{ name: "CUSTOM_VALUE", value: "~/.custom", sensitive: false }],
+        baseEnv,
+      ),
+    ).toEqual({ ...baseEnv, CUSTOM_VALUE: "~/.custom" });
+  });
+
   it("overrides inherited environment values and preserves empty strings", () => {
     expect(
       mergeProviderInstanceEnvironment(
diff --git a/apps/server/src/provider/ProviderInstanceEnvironment.ts b/apps/server/src/provider/ProviderInstanceEnvironment.ts
index e469253604e6..77c0c6c2dc88 100644
--- a/apps/server/src/provider/ProviderInstanceEnvironment.ts
+++ b/apps/server/src/provider/ProviderInstanceEnvironment.ts
@@ -1,5 +1,7 @@
 import type { ProviderInstanceEnvironment } from "@t3tools/contracts";
 
+import { expandHomePath } from "../pathExpansion.ts";
+
 export function mergeProviderInstanceEnvironment(
   environment: ProviderInstanceEnvironment | undefined,
   baseEnv: NodeJS.ProcessEnv = process.env,
@@ -10,7 +12,11 @@ export function mergeProviderInstanceEnvironment(
 
   const next: NodeJS.ProcessEnv = { ...baseEnv };
   for (const variable of environment) {
-    next[variable.name] = variable.value;
+    // Child processes do not apply shell expansion to environment values.
+    next[variable.name] =
+      variable.name === "CODEX_HOME" || variable.name === "CLAUDE_CONFIG_DIR"
+        ? expandHomePath(variable.value)
+        : variable.value;
   }
   return next;
 }
diff --git a/apps/server/src/provider/RuntimeInstructions.test.ts b/apps/server/src/provider/RuntimeInstructions.test.ts
index 350d8c73c150..320aa332c937 100644
--- a/apps/server/src/provider/RuntimeInstructions.test.ts
+++ b/apps/server/src/provider/RuntimeInstructions.test.ts
@@ -2,17 +2,6 @@ import { describe, expect, it } from "vite-plus/test";
 import { buildRuntimeInstructions } from "./RuntimeInstructions.ts";
 
 describe("buildRuntimeInstructions", () => {
-  it.each(["Codex", "Claude Code", "Cursor", "Grok", "OpenCode", "Antigravity"])(
-    "identifies the %s harness and describes media embedding",
-    (harness) => {
-      const instructions = buildRuntimeInstructions({ harness });
-      expect(instructions).toContain(`running in T3 Code through the ${harness} harness.`);
-      expect(instructions).toContain("embed images and videos");
-      expect(instructions).toContain("Markdown with absolute file paths");
-      expect(instructions).not.toContain("undefined");
-    },
-  );
-
   it("keeps known model and effort metadata on one line", () => {
     expect(
       buildRuntimeInstructions({
diff --git a/apps/server/src/provider/Services/ProviderRegistry.ts b/apps/server/src/provider/Services/ProviderRegistry.ts
index a1ea0c083ac2..bd917834e972 100644
--- a/apps/server/src/provider/Services/ProviderRegistry.ts
+++ b/apps/server/src/provider/Services/ProviderRegistry.ts
@@ -56,10 +56,12 @@ export interface ProviderRegistryShape {
   /**
    * Resolve the maintenance capabilities owned by one live provider instance.
    * Falls back to manual-only capabilities when the instance is not live.
+   * `fresh` re-derives ownership from the executable instead of the cache.
    */
   readonly getProviderMaintenanceCapabilitiesForInstance: (
     instanceId: ProviderInstanceId,
     provider: ProviderDriverKind,
+    options?: { readonly fresh?: boolean },
   ) => Effect.Effect<ProviderMaintenanceCapabilities>;
 
   /**
diff --git a/apps/server/src/provider/Services/ProviderSessionDirectory.ts b/apps/server/src/provider/Services/ProviderSessionDirectory.ts
index f2dd4323f7a3..9dbafd3e804e 100644
--- a/apps/server/src/provider/Services/ProviderSessionDirectory.ts
+++ b/apps/server/src/provider/Services/ProviderSessionDirectory.ts
@@ -1,4 +1,5 @@
 import type {
+  AgentSessionImportSource,
   ProviderInstanceId,
   ProviderDriverKind,
   ProviderSessionRuntimeStatus,
@@ -40,11 +41,22 @@ export type ProviderSessionDirectoryWriteError =
   | ProviderValidationError
   | ProviderSessionDirectoryPersistenceError;
 
+export interface ProviderSessionDirectoryUpsertOptions {
+  readonly onConflict?: "update" | "ignore";
+}
+
 export interface ProviderSessionDirectoryShape {
   readonly upsert: (
     binding: ProviderRuntimeBinding,
+    options?: ProviderSessionDirectoryUpsertOptions,
   ) => Effect.Effect<void, ProviderSessionDirectoryWriteError>;
 
+  /** Record an imported file without changing the current provider session. */
+  readonly recordImportedTranscript: (input: {
+    readonly threadId: ThreadId;
+    readonly source: AgentSessionImportSource;
+  }) => Effect.Effect<void, ProviderSessionDirectoryPersistenceError>;
+
   readonly getProvider: (
     threadId: ThreadId,
   ) => Effect.Effect<ProviderDriverKind, ProviderSessionDirectoryReadError>;
diff --git a/apps/server/src/provider/Services/ServerProvider.ts b/apps/server/src/provider/Services/ServerProvider.ts
index 5d0486d87ca7..dfea57cd93b5 100644
--- a/apps/server/src/provider/Services/ServerProvider.ts
+++ b/apps/server/src/provider/Services/ServerProvider.ts
@@ -4,7 +4,14 @@ import type * as Stream from "effect/Stream";
 import type { ProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
 
 export interface ServerProviderShape {
-  readonly maintenanceCapabilities: ProviderMaintenanceCapabilities;
+  /**
+   * Ownership-derived update capabilities. Cached between reads; pass
+   * `{ fresh: true }` before executing an update so it never trusts a
+   * resolution older than the click.
+   */
+  readonly resolveMaintenance: (options?: {
+    readonly fresh?: boolean;
+  }) => Effect.Effect<ProviderMaintenanceCapabilities>;
   readonly getSnapshot: Effect.Effect<ServerProvider>;
   readonly refresh: Effect.Effect<ServerProvider>;
   readonly streamChanges: Stream.Stream<ServerProvider>;
diff --git a/apps/server/src/provider/makeManagedServerProvider.test.ts b/apps/server/src/provider/makeManagedServerProvider.test.ts
index aa0828e048c9..292ef66ff2ee 100644
--- a/apps/server/src/provider/makeManagedServerProvider.test.ts
+++ b/apps/server/src/provider/makeManagedServerProvider.test.ts
@@ -158,7 +158,7 @@ describe("makeManagedServerProvider", () => {
           const checkCalls = yield* Ref.make(0);
           const releaseCheck = yield* Deferred.make<void>();
           const provider = yield* makeManagedServerProvider<TestSettings>({
-            maintenanceCapabilities,
+            resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
             getSettings: Effect.succeed({ enabled: true }),
             streamSettings: Stream.empty,
             haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -198,7 +198,7 @@ describe("makeManagedServerProvider", () => {
         const checkCalls = yield* Ref.make(0);
         const initialCheckDone = yield* Deferred.make<void>();
         yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.empty,
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -229,7 +229,7 @@ describe("makeManagedServerProvider", () => {
         const checkCalls = yield* Ref.make(0);
         const initialCheckDone = yield* Deferred.make<void>();
         yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.empty,
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -256,7 +256,7 @@ describe("makeManagedServerProvider", () => {
         const checkCalls = yield* Ref.make(0);
         const initialCheckDone = yield* Deferred.make<void>();
         const provider = yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.empty,
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -311,7 +311,7 @@ describe("makeManagedServerProvider", () => {
         const periodicCheckDone = yield* Deferred.make<void>();
 
         yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.empty,
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -353,7 +353,7 @@ describe("makeManagedServerProvider", () => {
         const releaseInitialCheck = yield* Deferred.make<void>();
         const releaseSettingsCheck = yield* Deferred.make<void>();
         const provider = yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Ref.get(settingsRef),
           streamSettings: Stream.fromPubSub(settingsChanges),
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -397,7 +397,7 @@ describe("makeManagedServerProvider", () => {
         const initialCheckDone = yield* Deferred.make<void>();
         const enrichmentCalls = yield* Ref.make(0);
         yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.fromPubSub(settingsChanges),
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -430,7 +430,7 @@ describe("makeManagedServerProvider", () => {
         const releaseEnrichment = yield* Deferred.make<void>();
         const releaseCheck = yield* Deferred.make<void>();
         const provider = yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.empty,
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -471,7 +471,7 @@ describe("makeManagedServerProvider", () => {
         const secondCallbackReady = yield* Deferred.make<void>();
         const allowFirstRefresh = yield* Deferred.make<void>();
         const provider = yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.empty,
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -527,7 +527,7 @@ describe("makeManagedServerProvider", () => {
     Effect.scoped(
       Effect.gen(function* () {
         const provider = yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.empty,
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
@@ -595,7 +595,7 @@ describe("makeManagedServerProvider", () => {
           windows: [{ id: "primary", kind: "session", label: "Session", usedPercent: 10 }],
         } as const;
         const provider = yield* makeManagedServerProvider<TestSettings>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed({ enabled: true }),
           streamSettings: Stream.empty,
           haveSettingsChanged: (previous, next) => previous.enabled !== next.enabled,
diff --git a/apps/server/src/provider/makeManagedServerProvider.ts b/apps/server/src/provider/makeManagedServerProvider.ts
index ec3d26e6c87e..c180412ec42d 100644
--- a/apps/server/src/provider/makeManagedServerProvider.ts
+++ b/apps/server/src/provider/makeManagedServerProvider.ts
@@ -39,7 +39,7 @@ function withUsageLimits(
 export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(function* <
   Settings,
 >(input: {
-  readonly maintenanceCapabilities: ServerProviderShape["maintenanceCapabilities"];
+  readonly resolveMaintenance: ServerProviderShape["resolveMaintenance"];
   readonly getSettings: Effect.Effect<Settings, ServerSettingsError>;
   readonly streamSettings: Stream.Stream<Settings>;
   readonly haveSettingsChanged: (previous: Settings, next: Settings) => boolean;
@@ -283,7 +283,7 @@ export const makeManagedServerProvider = Effect.fn("makeManagedServerProvider")(
   );
 
   return {
-    maintenanceCapabilities: input.maintenanceCapabilities,
+    resolveMaintenance: input.resolveMaintenance,
     getSnapshot: Ref.get(snapshotStateRef).pipe(Effect.map((state) => state.snapshot)),
     refresh: refreshSnapshot().pipe(Effect.tapError(Effect.logError), Effect.orDie),
     applyUsageLimits,
diff --git a/apps/server/src/provider/model-manifest.json b/apps/server/src/provider/model-manifest.json
index 590d02c8ac03..bca9f09eee8c 100644
--- a/apps/server/src/provider/model-manifest.json
+++ b/apps/server/src/provider/model-manifest.json
@@ -1,8 +1,9 @@
 {
   "version": 1,
-  "updatedAt": "2026-09-03T09:58:00Z",
+  "updatedAt": "2026-09-04T19:10:48Z",
   "currentModels": {
     "codex": [
+      "gpt-6-astra",
       "gpt-5.6-luna",
       "gpt-5.6-terra",
       "gpt-5.6-sol",
diff --git a/apps/server/src/provider/opencodeRuntime.environment.test.ts b/apps/server/src/provider/opencodeRuntime.environment.test.ts
index 584a9d80fb9c..680032de06b4 100644
--- a/apps/server/src/provider/opencodeRuntime.environment.test.ts
+++ b/apps/server/src/provider/opencodeRuntime.environment.test.ts
@@ -1,12 +1,24 @@
 import type { OpencodeClient } from "@opencode-ai/sdk/v2";
+import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it as effectIt } from "@effect/vitest";
+import {
+  HostProcessEnvironment,
+  HostProcessExecutablePath,
+  HostProcessPlatform,
+} from "@t3tools/shared/hostProcess";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Path from "effect/Path";
 import * as TestClock from "effect/testing/TestClock";
+import { FetchHttpClient, HttpClient } from "effect/unstable/http";
 import { describe, expect, it } from "vite-plus/test";
 
 import {
+  OpenCodeRuntime,
   OpenCodeRuntimeError,
+  OpenCodeRuntimeLive,
   resolveOpenCodeConfigContent,
   resolveOpenCodeServerPassword,
   verifyOpenCodeServerVersion,
@@ -150,3 +162,78 @@ describe("verifyOpenCodeServerVersion", () => {
     }).pipe(Effect.provide(TestClock.layer())),
   );
 });
+
+describe("OpenCode server output", () => {
+  effectIt.live(
+    "drains stdout and stderr after startup so server requests can finish",
+    () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const environment = yield* HostProcessEnvironment;
+        const executablePath = yield* HostProcessExecutablePath;
+        const platform = yield* HostProcessPlatform;
+        const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-opencode-output-" });
+        const isWindows = platform === "win32";
+        const binaryPath = path.join(tempDir, isWindows ? "opencode.cmd" : "opencode");
+        const scriptPath = path.join(tempDir, "opencode.mjs");
+
+        yield* fs.writeFileString(
+          scriptPath,
+          `import { createServer } from "node:http";
+const writeOutput = (stream) => new Promise((resolve, reject) => {
+  stream.write("x".repeat(2 * 1024 * 1024), (error) => error ? reject(error) : resolve());
+});
+const server = createServer(async (request, response) => {
+  if (request.url.startsWith("/global/health")) {
+    response.setHeader("Content-Type", "application/json");
+    response.end(JSON.stringify({ healthy: true, version: "1.14.19" }));
+    return;
+  }
+  await Promise.all([writeOutput(process.stdout), writeOutput(process.stderr)]);
+  response.end("drained");
+});
+server.listen(0, "127.0.0.1", () => {
+  process.stdout.write("opencode server listening on http://127.0.0.1:" + server.address().port + "\\n");
+});
+`,
+        );
+        yield* fs.writeFileString(
+          binaryPath,
+          [
+            ...(isWindows ? ["@echo off"] : ["#!/bin/sh"]),
+            isWindows
+              ? '"%T3_TEST_NODE_BINARY%" "%T3_TEST_OPENCODE_SCRIPT%" %*'
+              : 'exec "$T3_TEST_NODE_BINARY" "$T3_TEST_OPENCODE_SCRIPT" "$@"',
+            "",
+          ].join("\n"),
+        );
+        if (!isWindows) {
+          yield* fs.chmod(binaryPath, 0o755);
+        }
+
+        const runtime = yield* OpenCodeRuntime;
+        const server = yield* runtime.startOpenCodeServerProcess({
+          binaryPath,
+          directory: tempDir,
+          port: 0,
+          environment: {
+            ...environment,
+            T3_TEST_NODE_BINARY: executablePath,
+            T3_TEST_OPENCODE_SCRIPT: scriptPath,
+          },
+        });
+        const response = yield* HttpClient.get(`${server.url}/output`);
+
+        expect(yield* response.text).toBe("drained");
+        expect(yield* server.isRunning).toBe(true);
+      }).pipe(
+        Effect.scoped,
+        Effect.provide([
+          OpenCodeRuntimeLive.pipe(Layer.provideMerge(NodeServices.layer)),
+          FetchHttpClient.layer,
+        ]),
+      ),
+    10_000,
+  );
+});
diff --git a/apps/server/src/provider/opencodeRuntime.inventory.test.ts b/apps/server/src/provider/opencodeRuntime.inventory.test.ts
index 2a878a24ab8e..39ffec7436d4 100644
--- a/apps/server/src/provider/opencodeRuntime.inventory.test.ts
+++ b/apps/server/src/provider/opencodeRuntime.inventory.test.ts
@@ -1,12 +1,14 @@
 import * as NodeAssert from "node:assert/strict";
 
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import type { OpencodeClient } from "@opencode-ai/sdk/v2";
+import { createOpencodeClient, type OpencodeClient } from "@opencode-ai/sdk/v2";
 import { it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
+import * as Queue from "effect/Queue";
 import {
   HostProcessEnvironment,
   HostProcessExecutablePath,
@@ -18,6 +20,44 @@ import { OpenCodeRuntime, OpenCodeRuntimeLive } from "./opencodeRuntime.ts";
 const testLayer = OpenCodeRuntimeLive.pipe(Layer.provideMerge(NodeServices.layer));
 
 it.layer(testLayer)("OpenCodeRuntime inventory", (it) => {
+  it.effect("aborts pending SDK requests when inventory loading is interrupted", () =>
+    Effect.gen(function* () {
+      const runtime = yield* OpenCodeRuntime;
+      const started = yield* Queue.make<void>();
+      const aborted = yield* Queue.make<string>();
+      const client = createOpencodeClient({
+        baseUrl: "http://opencode.test",
+        fetch: Object.assign(
+          (input: string | Request | URL) => {
+            const request = input instanceof Request ? input : new Request(input.toString());
+            return new Promise<Response>((_resolve, reject) => {
+              request.signal.addEventListener(
+                "abort",
+                () => {
+                  Queue.offerUnsafe(aborted, new URL(request.url).pathname);
+                  reject(request.signal.reason);
+                },
+                { once: true },
+              );
+              Queue.offerUnsafe(started, undefined);
+            });
+          },
+          { preconnect: () => undefined },
+        ),
+      });
+
+      const inventoryFiber = yield* runtime.loadOpenCodeInventory(client).pipe(Effect.forkChild);
+      yield* Queue.takeN(started, 3);
+      yield* Fiber.interrupt(inventoryFiber);
+
+      NodeAssert.deepEqual((yield* Queue.takeAll(aborted)).toSorted(), [
+        "/agent",
+        "/provider",
+        "/skill",
+      ]);
+    }),
+  );
+
   it.effect("keeps provider inventory when agent discovery fails", () =>
     Effect.gen(function* () {
       const runtime = yield* OpenCodeRuntime;
diff --git a/apps/server/src/provider/opencodeRuntime.permissions.test.ts b/apps/server/src/provider/opencodeRuntime.permissions.test.ts
index be2696d7e100..a6ae1fbe0437 100644
--- a/apps/server/src/provider/opencodeRuntime.permissions.test.ts
+++ b/apps/server/src/provider/opencodeRuntime.permissions.test.ts
@@ -1,15 +1,21 @@
 import * as NodeAssert from "node:assert/strict";
 
+import * as RegExpUtils from "effect/RegExp";
 import { describe, it } from "vite-plus/test";
 
-import { buildOpenCodePermissionRules } from "./opencodeRuntime.ts";
+import { buildOpenCodePermissionRules, toOpenCodePermissionReply } from "./opencodeRuntime.ts";
 
 function actionFor(
   runtimeMode: Parameters<typeof buildOpenCodePermissionRules>[0],
   permission: string,
+  target = "*",
 ) {
-  return buildOpenCodePermissionRules(runtimeMode).find((rule) => rule.permission === permission)
-    ?.action;
+  // OpenCode uses the last matching rule. Its wildcards match directory separators.
+  return buildOpenCodePermissionRules(runtimeMode).findLast(
+    (rule) =>
+      (rule.permission === "*" || rule.permission === permission) &&
+      new RegExp(`^${RegExpUtils.escape(rule.pattern).replaceAll("\\*", ".*")}$`, "s").test(target),
+  )?.action;
 }
 
 describe("buildOpenCodePermissionRules", () => {
@@ -27,12 +33,38 @@ describe("buildOpenCodePermissionRules", () => {
     NodeAssert.equal(actionFor("auto", "edit"), "ask");
   });
 
-  it("keeps asking for everything else in the auto modes", () => {
-    for (const runtimeMode of ["auto-accept-edits", "auto"] as const) {
+  it("allows workspace reads and task updates without asking in supervised modes", () => {
+    for (const runtimeMode of ["approval-required", "auto-accept-edits", "auto"] as const) {
+      for (const permission of ["read", "glob", "grep", "lsp", "skill", "todowrite"]) {
+        NodeAssert.equal(actionFor(runtimeMode, permission, "src/index.ts"), "allow");
+      }
+    }
+  });
+
+  it("preserves OpenCode's environment-file approval rules", () => {
+    for (const runtimeMode of ["approval-required", "auto-accept-edits", "auto"] as const) {
+      for (const target of [
+        ".env",
+        ".env.local",
+        "config/service.env",
+        "config/service.env.local",
+      ]) {
+        NodeAssert.equal(actionFor(runtimeMode, "read", target), "ask");
+      }
+      for (const target of [".env.example", "config/service.env.example"]) {
+        NodeAssert.equal(actionFor(runtimeMode, "read", target), "allow");
+      }
+    }
+  });
+
+  it("still asks before commands, network access, external directories and unknown tools", () => {
+    for (const runtimeMode of ["approval-required", "auto-accept-edits", "auto"] as const) {
       NodeAssert.equal(actionFor(runtimeMode, "bash"), "ask");
       NodeAssert.equal(actionFor(runtimeMode, "webfetch"), "ask");
+      NodeAssert.equal(actionFor(runtimeMode, "websearch"), "ask");
       NodeAssert.equal(actionFor(runtimeMode, "external_directory"), "ask");
-      NodeAssert.equal(actionFor(runtimeMode, "*"), "ask");
+      NodeAssert.equal(actionFor(runtimeMode, "doom_loop"), "ask");
+      NodeAssert.equal(actionFor(runtimeMode, "custom_tool"), "ask");
     }
   });
 
@@ -43,3 +75,15 @@ describe("buildOpenCodePermissionRules", () => {
     ]);
   });
 });
+
+describe("toOpenCodePermissionReply", () => {
+  it.each([
+    ["accept", "once"],
+    ["acceptForSession", "always"],
+    ["acceptAlways", "always"],
+    ["decline", "reject"],
+    ["cancel", "reject"],
+  ] as const)("maps %s to %s", (decision, reply) => {
+    NodeAssert.equal(toOpenCodePermissionReply(decision), reply);
+  });
+});
diff --git a/apps/server/src/provider/opencodeRuntime.ts b/apps/server/src/provider/opencodeRuntime.ts
index afd806e5666e..19725d9472ca 100644
--- a/apps/server/src/provider/opencodeRuntime.ts
+++ b/apps/server/src/provider/opencodeRuntime.ts
@@ -80,6 +80,7 @@ export function resolveOpenCodeServerPassword(
 const OPENCODE_SERVER_READY_PREFIX = "opencode server listening";
 const DEFAULT_OPENCODE_SERVER_TIMEOUT_MS = 30_000;
 const DEFAULT_HOSTNAME = "127.0.0.1";
+const OPENCODE_SERVER_STARTUP_MAX_OUTPUT_CHARS = 64 * 1024;
 const OPENCODE_SKILL_DISCOVERY_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
 export interface OpenCodeServerProcess {
   readonly url: string;
@@ -494,8 +495,19 @@ export function buildOpenCodePermissionRules(runtimeMode: RuntimeMode): Permissi
   // reviewer, OpenCode among them, fall back to Supervised for that mode.
   const editAction = runtimeMode === "auto-accept-edits" ? "allow" : "ask";
 
+  // Session rules override OpenCode's agent defaults. Allow reads and task
+  // updates, but keep its default approval rules for environment files.
   return [
     { permission: "*", pattern: "*", action: "ask" },
+    { permission: "read", pattern: "*", action: "allow" },
+    { permission: "read", pattern: "*.env", action: "ask" },
+    { permission: "read", pattern: "*.env.*", action: "ask" },
+    { permission: "read", pattern: "*.env.example", action: "allow" },
+    { permission: "glob", pattern: "*", action: "allow" },
+    { permission: "grep", pattern: "*", action: "allow" },
+    { permission: "lsp", pattern: "*", action: "allow" },
+    { permission: "skill", pattern: "*", action: "allow" },
+    { permission: "todowrite", pattern: "*", action: "allow" },
     { permission: "bash", pattern: "*", action: "ask" },
     { permission: "edit", pattern: "*", action: editAction },
     { permission: "webfetch", pattern: "*", action: "ask" },
@@ -514,6 +526,7 @@ export function toOpenCodePermissionReply(
     case "accept":
       return "once";
     case "acceptForSession":
+    case "acceptAlways":
       return "always";
     case "decline":
     case "cancel":
@@ -707,18 +720,24 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
       );
       yield* Scope.addFinalizer(runtimeScope, terminateChild);
 
-      const stdoutRef = yield* Ref.make("");
-      const stderrRef = yield* Ref.make("");
+      const stdoutRef = yield* Ref.make<string | null>("");
+      const stderrRef = yield* Ref.make<string | null>("");
       const readyDeferred = yield* Deferred.make<string, OpenCodeRuntimeError>();
 
       const setReadyFromStdoutChunk = (chunk: string) =>
-        Ref.updateAndGet(stdoutRef, (stdout) => `${stdout}${chunk}`).pipe(
-          Effect.flatMap((nextStdout) => {
-            const parsed = parseServerUrlFromOutput(nextStdout);
-            return parsed
-              ? Deferred.succeed(readyDeferred, parsed).pipe(Effect.ignore)
-              : Effect.void;
-          }),
+        Ref.modify(stdoutRef, (stdout) => {
+          if (stdout === null) {
+            return [null, null] as const;
+          }
+          const nextStdout = `${stdout}${chunk}`;
+          return [
+            parseServerUrlFromOutput(nextStdout),
+            nextStdout.slice(-OPENCODE_SERVER_STARTUP_MAX_OUTPUT_CHARS),
+          ] as const;
+        }).pipe(
+          Effect.flatMap((parsed) =>
+            parsed ? Deferred.succeed(readyDeferred, parsed).pipe(Effect.ignore) : Effect.void,
+          ),
         );
 
       const stdoutFiber = yield* child.stdout.pipe(
@@ -729,7 +748,13 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
       );
       const stderrFiber = yield* child.stderr.pipe(
         Stream.decodeText(),
-        Stream.runForEach((chunk) => Ref.update(stderrRef, (stderr) => `${stderr}${chunk}`)),
+        Stream.runForEach((chunk) =>
+          Ref.update(stderrRef, (stderr) =>
+            stderr === null
+              ? null
+              : `${stderr}${chunk}`.slice(-OPENCODE_SERVER_STARTUP_MAX_OUTPUT_CHARS),
+          ),
+        ),
         Effect.ignore,
         Effect.forkIn(runtimeScope),
       );
@@ -737,8 +762,8 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
       const exitFiber = yield* child.exitCode.pipe(
         Effect.flatMap((code) =>
           Effect.gen(function* () {
-            const stdout = yield* Ref.get(stdoutRef);
-            const stderr = yield* Ref.get(stderrRef);
+            const stdout = (yield* Ref.get(stdoutRef)) ?? "";
+            const stderr = (yield* Ref.get(stderrRef)) ?? "";
             const exitCode = Number(code);
             yield* Deferred.fail(
               readyDeferred,
@@ -764,14 +789,11 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
         Deferred.await(readyDeferred).pipe(Effect.timeoutOption(timeoutMs)),
       );
 
-      // Startup-time fibers are no longer needed once ready has resolved (either
-      // way). The exit fiber is only interrupted on failure; on success it keeps
-      // the caller's `exitCode` effect observable until the scope closes.
-      yield* Fiber.interrupt(stdoutFiber).pipe(Effect.ignore);
-      yield* Fiber.interrupt(stderrFiber).pipe(Effect.ignore);
+      if (Exit.isFailure(readyExit) || Option.isNone(readyExit.value)) {
+        yield* Fiber.interruptAll([stdoutFiber, stderrFiber, exitFiber]).pipe(Effect.ignore);
+      }
 
       if (Exit.isFailure(readyExit)) {
-        yield* Fiber.interrupt(exitFiber).pipe(Effect.ignore);
         const squashed = Cause.squash(readyExit.cause);
         return yield* ensureRuntimeError(
           "startOpenCodeServerProcess",
@@ -782,13 +804,18 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
 
       const readyOption = readyExit.value;
       if (Option.isNone(readyOption)) {
-        yield* Fiber.interrupt(exitFiber).pipe(Effect.ignore);
         return yield* new OpenCodeRuntimeError({
           operation: "startOpenCodeServerProcess",
           detail: `Timed out waiting for OpenCode server start after ${timeoutMs}ms.`,
         });
       }
 
+      // Keep draining both pipes until the process scope closes. Stopping the
+      // readers can block OpenCode when its output buffers fill. Startup output
+      // is no longer needed, so discard later output instead of retaining it.
+      yield* Ref.set(stdoutRef, null);
+      yield* Ref.set(stderrRef, null);
+
       const url = readyOption.value;
       const version = yield* verifyOpenCodeServerVersion(
         createOpenCodeSdkClient({
@@ -854,7 +881,7 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
   };
 
   const loadProviders = (client: OpencodeClient) =>
-    runOpenCodeSdk("provider.list", () => client.provider.list()).pipe(
+    runOpenCodeSdk("provider.list", (signal) => client.provider.list(undefined, { signal })).pipe(
       Effect.filterMapOrFail(
         (list) =>
           list.data
@@ -870,7 +897,7 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
     );
 
   const loadAgents = (client: OpencodeClient) =>
-    runOpenCodeSdk("app.agents", () => client.app.agents()).pipe(
+    runOpenCodeSdk("app.agents", (signal) => client.app.agents(undefined, { signal })).pipe(
       Effect.map((result) => result.data ?? []),
       Effect.orElseSucceed((): ReadonlyArray<Agent> => []),
     );
diff --git a/apps/server/src/provider/providerMaintenance.test.ts b/apps/server/src/provider/providerMaintenance.test.ts
index 5683da2c1a82..2ceaf21996bf 100644
--- a/apps/server/src/provider/providerMaintenance.test.ts
+++ b/apps/server/src/provider/providerMaintenance.test.ts
@@ -1,5 +1,6 @@
 // @effect-diagnostics nodeBuiltinImport:off
 import { expect, it } from "@effect/vitest";
+import * as NodeChildProcess from "node:child_process";
 import * as NodeFS from "node:fs";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as NodeOS from "node:os";
@@ -8,20 +9,31 @@ import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
 import { HttpClient } from "effect/unstable/http";
+import { ChildProcessSpawner } from "effect/unstable/process";
 import {
   createProviderVersionAdvisory,
   enrichProviderSnapshotWithVersionAdvisory,
+  homebrewOwnershipFromCommandPath,
+  makeCachedProviderMaintenanceResolution,
   makePackageManagedProviderMaintenanceResolver,
   makeProviderMaintenanceCapabilities,
-  makeStaticProviderMaintenanceResolver,
   normalizeCommandPath,
+  npmGlobalPrefixFromCommandPath,
+  parseHomebrewLatestVersion,
   ProviderVersionCache,
   resolveLatestProviderVersion,
   resolveProviderMaintenanceCapabilitiesEffect,
+  type ProviderMaintenanceCapabilities,
 } from "./providerMaintenance.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const driver = (value: string) => ProviderDriverKind.make(value);
+// These write `#!/bin/sh` stubs and evaluate them with darwin/linux path
+// semantics; a Windows temp path cannot be split on `:`.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 const makeTempDir = (name: string) =>
   Crypto.Crypto.pipe(
     Effect.flatMap((crypto) => crypto.randomUUIDv4),
@@ -34,40 +46,16 @@ const isNativeTestCommandPath =
 const packageToolUpdate = makePackageManagedProviderMaintenanceResolver({
   provider: driver("packageTool"),
   npmPackageName: "@example/package-tool",
-  homebrewFormula: "package-tool",
   nativeUpdate: null,
 });
 const nativePackageToolUpdate = makePackageManagedProviderMaintenanceResolver({
   provider: driver("nativePackageTool"),
   npmPackageName: "@example/native-package-tool",
-  homebrewFormula: "native-package-tool",
   nativeUpdate: {
-    executable: "native-package-tool",
     args: ["update"],
-    lockKey: "native-package-tool-native",
     isCommandPath: isNativeTestCommandPath("/.local/bin/native-package-tool"),
   },
 });
-const scopedPackageToolUpdate = makePackageManagedProviderMaintenanceResolver({
-  provider: driver("scopedPackageTool"),
-  npmPackageName: "@example/scoped-package-tool",
-  homebrewFormula: "example/tap/scoped-package-tool",
-  nativeUpdate: {
-    executable: "scoped-package-tool",
-    args: ["upgrade"],
-    lockKey: "scoped-package-tool-native",
-    isCommandPath: isNativeTestCommandPath("/.scoped-package-tool/bin/scoped-package-tool"),
-  },
-});
-const staticToolUpdate = makeStaticProviderMaintenanceResolver(
-  makeProviderMaintenanceCapabilities({
-    provider: driver("staticTool"),
-    packageName: null,
-    updateExecutable: "static-tool",
-    updateArgs: ["update"],
-    updateLockKey: "static-tool",
-  }),
-);
 const installedPackageToolProvider: ServerProvider = {
   instanceId: ProviderInstanceId.make("packageTool"),
   driver: driver("packageTool"),
@@ -81,10 +69,59 @@ const installedPackageToolProvider: ServerProvider = {
   slashCommands: [],
   skills: [],
 };
+const manualPackageTool: ProviderMaintenanceCapabilities = {
+  provider: driver("packageTool"),
+  packageName: "@example/package-tool",
+  update: null,
+};
+
+function writeExecutable(path: string) {
+  NodeFS.mkdirSync(NodePath.dirname(path), { recursive: true });
+  NodeFS.writeFileSync(path, "#!/bin/sh\n");
+  NodeFS.chmodSync(path, 0o755);
+}
+
+/** Symlink `<tempDir>/bin/<name>` into a package entry point, like npm/pnpm do. */
+function linkIntoPackage(tempDir: string, name: string, packageSegments: ReadonlyArray<string>) {
+  const target = NodePath.join(tempDir, ...packageSegments, "bin", `${name}.js`);
+  writeExecutable(target);
+  const link = NodePath.join(tempDir, "bin", name);
+  NodeFS.mkdirSync(NodePath.dirname(link), { recursive: true });
+  NodeFS.symlinkSync(target, link);
+  return link;
+}
+
+const noSpawn = ChildProcessSpawner.make(() =>
+  Effect.die("maintenance resolution should not spawn a process here"),
+);
+
+function stdoutSpawner(onSpawn: (command: string, args: ReadonlyArray<string>) => string) {
+  return ChildProcessSpawner.make((command) => {
+    const { command: executable, args } = command as unknown as {
+      readonly command: string;
+      readonly args: ReadonlyArray<string>;
+    };
+    return Effect.succeed(
+      ChildProcessSpawner.makeHandle({
+        pid: ChildProcessSpawner.ProcessId(1),
+        exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
+        isRunning: Effect.succeed(false),
+        kill: () => Effect.void,
+        unref: Effect.succeed(Effect.void),
+        stdin: Sink.drain,
+        stdout: Stream.encodeText(Stream.make(onSpawn(executable, args))),
+        stderr: Stream.empty,
+        all: Stream.empty,
+        getInputFd: () => Sink.drain,
+        getOutputFd: () => Stream.empty,
+      }),
+    );
+  });
+}
 
 it.layer(NodeServices.layer)("providerMaintenance", (it) => {
   it.effect("reads cached versions through the injectable cache reference", () =>
-    resolveLatestProviderVersion(packageToolUpdate.resolve()).pipe(
+    resolveLatestProviderVersion(manualPackageTool).pipe(
       Effect.provideService(
         ProviderVersionCache,
         new Map([
@@ -109,14 +146,25 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
     ),
   );
 
+  it.effect("prefers the installer's own latest version over the npm registry", () =>
+    resolveLatestProviderVersion({ ...manualPackageTool, latestVersion: "1.2.0" }).pipe(
+      Effect.provideService(ProviderVersionCache, new Map()),
+      Effect.provideService(
+        HttpClient.HttpClient,
+        HttpClient.make(() =>
+          Effect.die("installer-reported latest should not make an HTTP request"),
+        ),
+      ),
+      Effect.map((version) => {
+        expect(version).toBe("1.2.0");
+      }),
+    ),
+  );
+
   it.effect("does not fetch latest provider versions when update checks are disabled", () =>
-    enrichProviderSnapshotWithVersionAdvisory(
-      installedPackageToolProvider,
-      packageToolUpdate.resolve(),
-      {
-        enableProviderUpdateChecks: false,
-      },
-    ).pipe(
+    enrichProviderSnapshotWithVersionAdvisory(installedPackageToolProvider, manualPackageTool, {
+      enableProviderUpdateChecks: false,
+    }).pipe(
       Effect.provideService(ProviderVersionCache, new Map()),
       Effect.provideService(
         HttpClient.HttpClient,
@@ -164,437 +212,540 @@ it.layer(NodeServices.layer)("providerMaintenance", (it) => {
     });
   });
 
-  it("marks installed providers behind latest when a newer provider version is available", () => {
+  it("keeps the manual update hint when the install is behind but unowned", () => {
     expect(
       createProviderVersionAdvisory({
-        driver: driver("nativePackageTool"),
+        driver: driver("packageTool"),
         currentVersion: "2.1.110",
         latestVersion: "2.1.117",
-        maintenanceCapabilities: nativePackageToolUpdate.resolve(),
+        maintenanceCapabilities: manualPackageTool,
       }),
     ).toMatchObject({
       status: "behind_latest",
-      currentVersion: "2.1.110",
       latestVersion: "2.1.117",
-      updateCommand:
-        "npm install -g --allow-scripts=@example/native-package-tool @example/native-package-tool@latest",
-      canUpdate: true,
+      updateCommand: null,
+      canUpdate: false,
       message: "Install the update now or review provider settings.",
     });
   });
 
-  it("keeps update commands owned by provider maintenance capabilities", () => {
-    expect(staticToolUpdate.resolve()).toEqual({
-      provider: driver("staticTool"),
-      packageName: null,
-      update: {
-        command: "static-tool update",
-
-        executable: "static-tool",
-
-        args: ["update"],
-
-        lockKey: "static-tool",
-      },
-    });
-  });
+  it.effect("stays manual-only when the binary cannot be located", () =>
+    resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
+      binaryPath: "package-tool",
+      env: { PATH: "" },
+    }).pipe(
+      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
+      Effect.map((capabilities) => {
+        expect(capabilities).toEqual(manualPackageTool);
+      }),
+    ),
+  );
 
-  it.effect(
-    "switches package-managed providers to vite-plus updates when the resolved binary lives in vite-plus global bin",
+  it.effect.skipIf(!symlinksSupported)(
+    "pins npm updates to the global prefix that owns the package",
     () =>
       Effect.gen(function* () {
-        const tempDir = yield* makeTempDir("t3-vite-plus-capabilities");
-        const vitePlusBinDir = NodePath.join(tempDir, ".vite-plus", "bin");
-        NodeFS.mkdirSync(vitePlusBinDir, { recursive: true });
-        const packageToolPath = NodePath.join(vitePlusBinDir, "package-tool");
-        NodeFS.writeFileSync(packageToolPath, "#!/bin/sh\n");
-        NodeFS.chmodSync(packageToolPath, 0o755);
+        const tempDir = yield* makeTempDir("t3-npm-capabilities");
+        const link = linkIntoPackage(tempDir, "package-tool", [
+          "lib",
+          "node_modules",
+          "@example",
+          "package-tool",
+        ]);
 
         const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
           packageToolUpdate,
           {
-            binaryPath: "package-tool",
-            env: {
-              PATH: vitePlusBinDir,
-            },
+            binaryPath: link,
+            env: { PATH: "" },
           },
-        ).pipe(Effect.provideService(HostProcessPlatform, "darwin"));
+        ).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn));
 
         expect(capabilities).toEqual({
           provider: driver("packageTool"),
           packageName: "@example/package-tool",
           update: {
-            command: "vp i -g @example/package-tool",
+            command: `npm install -g --prefix ${tempDir} --allow-scripts=@example/package-tool @example/package-tool@latest`,
+            executable: "npm",
+            args: [
+              "install",
+              "-g",
+              "--prefix",
+              tempDir,
+              "--allow-scripts=@example/package-tool",
+              "@example/package-tool@latest",
+            ],
+            lockKey: `npm-global:${normalizeCommandPath(tempDir)}`,
+          },
+        });
+      }),
+  );
+
+  it("derives the npm prefix only from the global lib/node_modules layout", () => {
+    expect(
+      npmGlobalPrefixFromCommandPath(
+        "/usr/local/lib/node_modules/@openai/codex/bin/codex.js",
+        "@openai/codex",
+      ),
+    ).toBe("/usr/local");
+    // A copy nested inside another package is not a global install.
+    expect(
+      npmGlobalPrefixFromCommandPath(
+        "/usr/local/lib/node_modules/other/node_modules/@openai/codex/bin/codex.js",
+        "@openai/codex",
+      ),
+    ).toBeNull();
+    expect(
+      npmGlobalPrefixFromCommandPath(
+        "/lib/node_modules/@openai/codex/bin/codex.js",
+        "@openai/codex",
+      ),
+    ).toBe("/");
+    // Neither is a project-local dependency.
+    expect(
+      npmGlobalPrefixFromCommandPath(
+        "/work/app/node_modules/@openai/codex/bin/codex.js",
+        "@openai/codex",
+      ),
+    ).toBeNull();
+  });
+
+  it.effect("proves Windows npm ownership from the package manifest beside the shim", () =>
+    Effect.gen(function* () {
+      const tempDir = yield* makeTempDir("t3-npm-windows-capabilities");
+      const shim = NodePath.join(tempDir, "package-tool.cmd");
+      NodeFS.mkdirSync(tempDir, { recursive: true });
+      NodeFS.writeFileSync(shim, "@echo off\r\n");
+      NodeFS.mkdirSync(NodePath.join(tempDir, "node_modules", "@example", "package-tool"), {
+        recursive: true,
+      });
+      NodeFS.writeFileSync(
+        NodePath.join(tempDir, "node_modules", "@example", "package-tool", "package.json"),
+        "{}",
+      );
 
-            executable: "vp",
+      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
+        binaryPath: shim,
+        env: { PATH: "", PATHEXT: ".COM;.EXE;.BAT;.CMD" },
+      }).pipe(
+        Effect.provideService(HostProcessPlatform, "win32"),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
+      );
 
-            args: ["i", "-g", "@example/package-tool"],
+      expect(capabilities.update).toMatchObject({
+        executable: "npm",
+        args: ["install", "-g", "--prefix", tempDir, expect.any(String), expect.any(String)],
+      });
 
-            lockKey: "vite-plus-global",
+      // The same layout on POSIX is a project checkout, not a global install.
+      const script = NodePath.join(tempDir, "package-tool");
+      writeExecutable(script);
+      const posix = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
+        binaryPath: script,
+        env: { PATH: "" },
+      }).pipe(
+        Effect.provideService(HostProcessPlatform, "linux"),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
+      );
+      expect(posix.update).toBeNull();
+    }),
+  );
+
+  it.effect.skipIf(!symlinksSupported)(
+    "switches to pnpm updates when the real path lives in pnpm's global store",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-pnpm-capabilities");
+        const link = linkIntoPackage(tempDir, "package-tool", [
+          ".local",
+          "share",
+          "pnpm",
+          "global",
+          "5",
+          "node_modules",
+          "@example",
+          "package-tool",
+        ]);
+
+        const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
+          packageToolUpdate,
+          {
+            binaryPath: link,
+            env: { PATH: "" },
           },
+        ).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn));
+
+        expect(capabilities.update).toMatchObject({
+          command: "pnpm add -g @example/package-tool@latest",
+          lockKey: "pnpm-global",
         });
       }),
   );
 
-  it.effect(
-    "switches package-managed providers to bun updates when the resolved binary lives in bun's global bin",
+  it.effect.skipIf(windowsHost)(
+    "switches to bun updates when the resolved binary lives in bun's global bin",
     () =>
       Effect.gen(function* () {
         const tempDir = yield* makeTempDir("t3-bun-capabilities");
         const bunBinDir = NodePath.join(tempDir, ".bun", "bin");
-        NodeFS.mkdirSync(bunBinDir, { recursive: true });
-        NodeFS.writeFileSync(NodePath.join(bunBinDir, "native-package-tool.exe"), "MZ");
+        writeExecutable(NodePath.join(bunBinDir, "package-tool"));
 
         const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
-          nativePackageToolUpdate,
+          packageToolUpdate,
           {
-            binaryPath: "native-package-tool",
-            env: {
-              PATH: bunBinDir,
-              PATHEXT: ".COM;.EXE;.BAT;.CMD",
-            },
+            binaryPath: "package-tool",
+            env: { PATH: bunBinDir },
           },
-        ).pipe(Effect.provideService(HostProcessPlatform, "win32"));
-
-        expect(capabilities).toEqual({
-          provider: driver("nativePackageTool"),
-          packageName: "@example/native-package-tool",
-          update: {
-            command: "bun i -g @example/native-package-tool@latest",
+        ).pipe(
+          Effect.provideService(HostProcessPlatform, "darwin"),
+          Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
+        );
+
+        expect(capabilities.update).toMatchObject({
+          command: "bun i -g @example/package-tool@latest",
+          lockKey: "bun-global",
+        });
+      }),
+  );
 
-            executable: "bun",
+  it.effect.skipIf(windowsHost)("switches to native updates and runs the resolved executable", () =>
+    Effect.gen(function* () {
+      const tempDir = yield* makeTempDir("t3-native-capabilities");
+      const nativeBinDir = NodePath.join(tempDir, ".local", "bin");
+      const nativePath = NodePath.join(nativeBinDir, "native-package-tool");
+      writeExecutable(nativePath);
+
+      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
+        nativePackageToolUpdate,
+        {
+          binaryPath: "native-package-tool",
+          env: { PATH: nativeBinDir },
+        },
+      ).pipe(
+        Effect.provideService(HostProcessPlatform, "darwin"),
+        Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn),
+      );
 
-            args: ["i", "-g", "@example/native-package-tool@latest"],
+      expect(capabilities).toEqual({
+        provider: driver("nativePackageTool"),
+        packageName: "@example/native-package-tool",
+        update: {
+          command: `${nativePath} update`,
+          executable: nativePath,
+          args: ["update"],
+          lockKey: "nativePackageTool-native",
+        },
+      });
+    }),
+  );
 
-            lockKey: "bun-global",
-          },
-        });
-      }),
+  // Regression for #9850: an explicit native path outside PATH, with spaces,
+  // must be what actually gets spawned.
+  it.effect.skipIf(windowsHost)("runs an explicit native updater outside PATH", () =>
+    Effect.gen(function* () {
+      const tempDir = yield* makeTempDir("t3-native-update");
+      const nativePath = NodePath.join(
+        tempDir,
+        "with spaces",
+        ".local",
+        "bin",
+        "native-package-tool",
+      );
+      NodeFS.mkdirSync(NodePath.dirname(nativePath), { recursive: true });
+      NodeFS.writeFileSync(nativePath, "#!/bin/sh\nprintf '%s' \"$1\"\n");
+      NodeFS.chmodSync(nativePath, 0o755);
+
+      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
+        nativePackageToolUpdate,
+        { binaryPath: nativePath, env: { PATH: "" } },
+      ).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn));
+
+      expect(capabilities.update?.executable).toBe(nativePath);
+      const result = NodeChildProcess.spawnSync(
+        capabilities.update!.executable,
+        capabilities.update!.args,
+        { env: { PATH: "" }, encoding: "utf8" },
+      );
+      expect(result.status).toBe(0);
+      expect(result.stdout).toBe("update");
+    }),
   );
 
-  it.effect(
-    "switches package-managed providers to pnpm updates when the resolved binary lives in pnpm's global bin",
+  it.effect.skipIf(!symlinksSupported)(
+    "prefers npm ownership over the Node keg the package lives under",
     () =>
       Effect.gen(function* () {
-        const tempDir = yield* makeTempDir("t3-pnpm-capabilities");
-        const pnpmHomeDir = NodePath.join(tempDir, ".local", "share", "pnpm");
-        NodeFS.mkdirSync(pnpmHomeDir, { recursive: true });
-        const scopedPackageToolPath = NodePath.join(pnpmHomeDir, "scoped-package-tool");
-        NodeFS.writeFileSync(scopedPackageToolPath, "#!/bin/sh\n");
-        NodeFS.chmodSync(scopedPackageToolPath, 0o755);
+        // `brew install node` keeps npm globals inside the node keg.
+        const tempDir = yield* makeTempDir("t3-homebrew-node-capabilities");
+        const keg = NodePath.join(tempDir, "Cellar", "node", "22.1.0");
+        const target = NodePath.join(
+          keg,
+          "lib",
+          "node_modules",
+          "@example",
+          "package-tool",
+          "bin",
+          "package-tool.js",
+        );
+        writeExecutable(target);
+        const link = NodePath.join(tempDir, "bin", "package-tool");
+        NodeFS.mkdirSync(NodePath.dirname(link), { recursive: true });
+        NodeFS.symlinkSync(target, link);
 
         const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
-          scopedPackageToolUpdate,
+          packageToolUpdate,
           {
-            binaryPath: "scoped-package-tool",
-            env: {
-              PATH: pnpmHomeDir,
-            },
+            binaryPath: link,
+            env: { PATH: "" },
           },
-        ).pipe(Effect.provideService(HostProcessPlatform, "darwin"));
-
-        expect(capabilities).toEqual({
-          provider: driver("scopedPackageTool"),
-          packageName: "@example/scoped-package-tool",
-          update: {
-            command: "pnpm add -g @example/scoped-package-tool@latest",
+        ).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn));
 
-            executable: "pnpm",
-
-            args: ["add", "-g", "@example/scoped-package-tool@latest"],
-
-            lockKey: "pnpm-global",
-          },
+        expect(capabilities.update).toMatchObject({
+          executable: "npm",
+          args: expect.arrayContaining(["--prefix", keg]),
+          lockKey: `npm-global:${normalizeCommandPath(keg)}`,
         });
       }),
   );
 
-  it("switches package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
-    expect(
-      packageToolUpdate.resolve({
-        binaryPath: "/opt/homebrew/bin/package-tool",
-        env: {
-          PATH: "",
-        },
-      }),
-    ).toEqual({
+  it("quotes copyable command words the shell would split", () => {
+    const posix = makeProviderMaintenanceCapabilities({
       provider: driver("packageTool"),
       packageName: "@example/package-tool",
-      update: {
-        command: "brew upgrade package-tool",
+      updateExecutable: "npm",
+      updateArgs: [
+        "install",
+        "-g",
+        "--prefix",
+        "/Users/Jane Doe/.npm-global",
+        "@example/package-tool@latest",
+      ],
+      updateLockKey: "npm-global",
+      platform: "darwin",
+    });
+    expect(posix.update?.command).toBe(
+      "npm install -g --prefix '/Users/Jane Doe/.npm-global' @example/package-tool@latest",
+    );
+    const windows = makeProviderMaintenanceCapabilities({
+      provider: driver("packageTool"),
+      packageName: null,
+      updateExecutable: "C:\\Program Files\\Tool\\tool.exe",
+      updateArgs: ["update"],
+      updateLockKey: "tool",
+      platform: "win32",
+    });
+    expect(windows.update?.command).toBe("& 'C:\\Program Files\\Tool\\tool.exe' update");
+  });
+
+  it.effect.skipIf(windowsHost)("carries the native updater's environment into the action", () =>
+    Effect.gen(function* () {
+      const tempDir = yield* makeTempDir("t3-native-env");
+      const nativePath = NodePath.join(tempDir, ".local", "bin", "native-package-tool");
+      writeExecutable(nativePath);
+      const resolver = makePackageManagedProviderMaintenanceResolver({
+        provider: driver("nativePackageTool"),
+        npmPackageName: "@example/native-package-tool",
+        nativeUpdate: {
+          args: ["update"],
+          isCommandPath: isNativeTestCommandPath("/.local/bin/native-package-tool"),
+          env: { TOOL_HOME: tempDir },
+        },
+      });
 
-        executable: "brew",
+      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(resolver, {
+        binaryPath: nativePath,
+        env: { PATH: "" },
+      }).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn));
 
-        args: ["upgrade", "package-tool"],
+      expect(capabilities.update?.env).toEqual({ TOOL_HOME: tempDir });
+    }),
+  );
 
-        lockKey: "homebrew",
-      },
+  it("recognizes Homebrew kegs and casks from the real executable path", () => {
+    expect(
+      homebrewOwnershipFromCommandPath("/opt/homebrew/Cellar/claude-code@latest/2.1.0/bin/claude"),
+    ).toEqual({ kind: "formula", name: "claude-code@latest", prefix: "/opt/homebrew" });
+    expect(homebrewOwnershipFromCommandPath("/usr/local/Caskroom/codex/0.148.0/codex")).toEqual({
+      kind: "cask",
+      name: "codex",
+      prefix: "/usr/local",
+    });
+    // A plain /usr/local/bin binary is not evidence of Homebrew (#8832).
+    expect(homebrewOwnershipFromCommandPath("/usr/local/bin/codex")).toBeNull();
+    // A keg elsewhere reports its prefix so the resolver can reject it against
+    // `brew --prefix`.
+    expect(homebrewOwnershipFromCommandPath("/srv/Cellar/claude/1.0.0/bin/claude")).toMatchObject({
+      prefix: "/srv",
     });
   });
 
-  it.effect(
-    "switches native-package-tool to native updates when the binary resolves through the native installer",
+  it.effect.skipIf(windowsHost)(
+    "stays manual-only for an explicit binary path that does not exist",
     () =>
       Effect.gen(function* () {
-        const tempDir = yield* makeTempDir("t3-native-package-tool-native-capabilities");
-        const nativeBinDir = NodePath.join(tempDir, ".local", "bin");
-        NodeFS.mkdirSync(nativeBinDir, { recursive: true });
-        const nativePackageToolPath = NodePath.join(nativeBinDir, "native-package-tool");
-        NodeFS.writeFileSync(nativePackageToolPath, "#!/bin/sh\n");
-        NodeFS.chmodSync(nativePackageToolPath, 0o755);
+        const tempDir = yield* makeTempDir("t3-missing-native-capabilities");
+        const missingPath = NodePath.join(tempDir, ".local", "bin", "native-package-tool");
 
         const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
           nativePackageToolUpdate,
-          {
-            binaryPath: "native-package-tool",
-            env: {
-              PATH: nativeBinDir,
-            },
-          },
-        ).pipe(Effect.provideService(HostProcessPlatform, "darwin"));
-
-        expect(capabilities).toEqual({
-          provider: driver("nativePackageTool"),
-          packageName: "@example/native-package-tool",
-          update: {
-            command: "native-package-tool update",
-
-            executable: "native-package-tool",
+          { binaryPath: missingPath, env: { PATH: "" } },
+        ).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn));
 
-            args: ["update"],
-
-            lockKey: "native-package-tool-native",
-          },
-        });
+        expect(capabilities.update).toBeNull();
       }),
   );
 
-  it.effect(
-    "switches scoped-package-tool to native upgrades when the binary resolves through the standalone installer",
-    () =>
+  it.effect.each([
+    { directory: "Caskroom", name: "package-tool", kind: "cask" },
+    { directory: "Cellar", name: "package-tool", kind: "formula" },
+    { directory: "Cellar", name: "package-tool@latest", kind: "formula" },
+  ] as const)(
+    "upgrades the owning Homebrew $kind $name through an executable alias",
+    (fixture) =>
       Effect.gen(function* () {
-        const tempDir = yield* makeTempDir("t3-scoped-package-tool-native-capabilities");
-        const nativeBinDir = NodePath.join(tempDir, ".scoped-package-tool", "bin");
-        NodeFS.mkdirSync(nativeBinDir, { recursive: true });
-        const scopedPackageToolPath = NodePath.join(nativeBinDir, "scoped-package-tool");
-        NodeFS.writeFileSync(scopedPackageToolPath, "#!/bin/sh\n");
-        NodeFS.chmodSync(scopedPackageToolPath, 0o755);
+        const tempDir = yield* makeTempDir("t3-homebrew-capabilities");
+        const brewBinDir = NodePath.join(tempDir, "brew-bin");
+        const brewPath = NodePath.join(brewBinDir, "brew");
+        writeExecutable(brewPath);
+        const ownedBinary = NodePath.join(
+          tempDir,
+          fixture.directory,
+          fixture.name,
+          "0.148.0",
+          "package-tool-0.148.0",
+        );
+        writeExecutable(ownedBinary);
+        const link = NodePath.join(tempDir, "bin", "custom-package-tool");
+        NodeFS.mkdirSync(NodePath.dirname(link), { recursive: true });
+        NodeFS.symlinkSync(ownedBinary, link);
+        const spawned: Array<ReadonlyArray<string>> = [];
 
         const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
-          scopedPackageToolUpdate,
+          packageToolUpdate,
           {
-            binaryPath: "scoped-package-tool",
-            env: {
-              PATH: nativeBinDir,
-            },
+            binaryPath: link,
+            env: { PATH: brewBinDir },
           },
-        ).pipe(Effect.provideService(HostProcessPlatform, "darwin"));
-
+        ).pipe(
+          Effect.provideService(HostProcessPlatform, "darwin"),
+          Effect.provideService(
+            ChildProcessSpawner.ChildProcessSpawner,
+            stdoutSpawner((command, args) => {
+              spawned.push([command, ...args]);
+              return args[0] === "--prefix"
+                ? `${tempDir}\n`
+                : JSON.stringify(
+                    fixture.kind === "cask"
+                      ? { casks: [{ version: "0.148.0,42" }] }
+                      : { formulae: [{ versions: { stable: "0.148.0" } }] },
+                  );
+            }),
+          ),
+        );
+
+        expect(spawned).toEqual([
+          [brewPath, "--prefix"],
+          [brewPath, "info", "--json=v2", fixture.name],
+        ]);
         expect(capabilities).toEqual({
-          provider: driver("scopedPackageTool"),
-          packageName: "@example/scoped-package-tool",
+          provider: driver("packageTool"),
+          packageName: "@example/package-tool",
+          latestVersion: "0.148.0",
           update: {
-            command: "scoped-package-tool upgrade",
-
-            executable: "scoped-package-tool",
-
-            args: ["upgrade"],
-
-            lockKey: "scoped-package-tool-native",
+            command:
+              fixture.kind === "cask"
+                ? `brew upgrade --cask ${fixture.name}`
+                : `brew upgrade ${fixture.name}`,
+            executable: brewPath,
+            args:
+              fixture.kind === "cask"
+                ? ["upgrade", "--cask", fixture.name]
+                : ["upgrade", fixture.name],
+            lockKey: "homebrew",
           },
         });
       }),
+    { skip: !symlinksSupported },
   );
 
-  it("switches native-package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
-    expect(
-      nativePackageToolUpdate.resolve({
-        binaryPath: "/opt/homebrew/bin/native-package-tool",
-        env: {
-          PATH: "",
-        },
-      }),
-    ).toEqual({
-      provider: driver("nativePackageTool"),
-      packageName: "@example/native-package-tool",
-      update: {
-        command: "brew upgrade native-package-tool",
-
-        executable: "brew",
-
-        args: ["upgrade", "native-package-tool"],
-
-        lockKey: "homebrew",
-      },
-    });
-  });
+  it.effect.skipIf(windowsHost)(
+    "stays manual-only when the keg is not under the resolved brew's prefix",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-homebrew-foreign-prefix");
+        const brewBinDir = NodePath.join(tempDir, "brew-bin");
+        writeExecutable(NodePath.join(brewBinDir, "brew"));
+        const kegBinary = NodePath.join(
+          tempDir,
+          "elsewhere",
+          "Cellar",
+          "package-tool",
+          "1.0.0",
+          "bin",
+          "package-tool",
+        );
+        writeExecutable(kegBinary);
 
-  it("switches scoped-package-tool to Homebrew updates when the binary resolves through Homebrew", () => {
-    expect(
-      scopedPackageToolUpdate.resolve({
-        binaryPath: "/opt/homebrew/bin/scoped-package-tool",
-        env: {
-          PATH: "",
-        },
+        const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
+          packageToolUpdate,
+          {
+            binaryPath: kegBinary,
+            env: { PATH: brewBinDir },
+          },
+        ).pipe(
+          Effect.provideService(HostProcessPlatform, "darwin"),
+          Effect.provideService(
+            ChildProcessSpawner.ChildProcessSpawner,
+            stdoutSpawner(() => "/opt/homebrew\n"),
+          ),
+        );
+
+        expect(capabilities).toEqual(manualPackageTool);
       }),
-    ).toEqual({
-      provider: driver("scopedPackageTool"),
-      packageName: "@example/scoped-package-tool",
-      update: {
-        command: "brew upgrade example/tap/scoped-package-tool",
-
-        executable: "brew",
-
-        args: ["upgrade", "example/tap/scoped-package-tool"],
+  );
 
-        lockKey: "homebrew",
-      },
-    });
+  it("reads the stable formula version from brew info", () => {
+    const info = JSON.stringify({ formulae: [{ versions: { stable: "2.1.5" } }] });
+    const formula = { kind: "formula", name: "claude-code", prefix: "/opt/homebrew" } as const;
+    expect(parseHomebrewLatestVersion(info, formula)).toBe("2.1.5");
+    expect(parseHomebrewLatestVersion("not json", formula)).toBeNull();
   });
 
-  it.effect("keeps npm updates for binaries symlinked into npm's global node_modules tree", () =>
-    Effect.gen(function* () {
-      const tempDir = yield* makeTempDir("t3-npm-capabilities");
-      const binDir = NodePath.join(tempDir, "bin");
-      const packageBinDir = NodePath.join(
-        tempDir,
-        "lib",
-        "node_modules",
-        "@example",
-        "package-tool",
-        "bin",
-      );
-      NodeFS.mkdirSync(binDir, { recursive: true });
-      NodeFS.mkdirSync(packageBinDir, { recursive: true });
-      const packageBinPath = NodePath.join(packageBinDir, "package-tool.js");
-      const symlinkPath = NodePath.join(binDir, "package-tool");
-      NodeFS.writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
-      NodeFS.chmodSync(packageBinPath, 0o755);
-      NodeFS.symlinkSync(packageBinPath, symlinkPath);
-
-      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
-        binaryPath: symlinkPath,
-        env: {
-          PATH: "",
-        },
-      });
-
-      expect(capabilities).toEqual({
-        provider: driver("packageTool"),
-        packageName: "@example/package-tool",
-        update: {
-          command:
-            "npm install -g --allow-scripts=@example/package-tool @example/package-tool@latest",
-
-          executable: "npm",
+  it.effect.skipIf(windowsHost)(
+    "disables one-click updates for explicit custom binary paths it cannot safely map",
+    () =>
+      Effect.gen(function* () {
+        const tempDir = yield* makeTempDir("t3-custom-capabilities");
+        const customPath = NodePath.join(tempDir, "tools", "package-tool");
+        writeExecutable(customPath);
 
-          args: [
-            "install",
-            "-g",
-            "--allow-scripts=@example/package-tool",
-            "@example/package-tool@latest",
-          ],
+        const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(
+          packageToolUpdate,
+          {
+            binaryPath: customPath,
+            env: { PATH: "" },
+          },
+        ).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, noSpawn));
 
-          lockKey: "npm-global",
-        },
-      });
-    }),
+        expect(capabilities).toEqual(manualPackageTool);
+      }),
   );
 
-  it.effect("uses Effect FileSystem realPath when detecting pnpm global symlinks", () =>
+  it.effect("caches resolution until a fresh read is requested", () =>
     Effect.gen(function* () {
-      const tempDir = yield* makeTempDir("t3-pnpm-realpath-capabilities");
-      const binDir = NodePath.join(tempDir, "bin");
-      const packageBinDir = NodePath.join(
-        tempDir,
-        ".local",
-        "share",
-        "pnpm",
-        "global",
-        "5",
-        "node_modules",
-        "@example",
-        "package-tool",
-        "bin",
+      let resolutions = 0;
+      const resolve = yield* makeCachedProviderMaintenanceResolution(
+        Effect.sync(() => {
+          resolutions += 1;
+          return manualPackageTool;
+        }),
       );
-      NodeFS.mkdirSync(binDir, { recursive: true });
-      NodeFS.mkdirSync(packageBinDir, { recursive: true });
-      const packageBinPath = NodePath.join(packageBinDir, "package-tool.js");
-      const symlinkPath = NodePath.join(binDir, "package-tool");
-      NodeFS.writeFileSync(packageBinPath, "#!/usr/bin/env node\n");
-      NodeFS.chmodSync(packageBinPath, 0o755);
-      NodeFS.symlinkSync(packageBinPath, symlinkPath);
-
-      const capabilities = yield* resolveProviderMaintenanceCapabilitiesEffect(packageToolUpdate, {
-        binaryPath: symlinkPath,
-        env: {
-          PATH: "",
-        },
-      });
-
-      expect(capabilities).toEqual({
-        provider: driver("packageTool"),
-        packageName: "@example/package-tool",
-        update: {
-          command: "pnpm add -g @example/package-tool@latest",
-
-          executable: "pnpm",
-
-          args: ["add", "-g", "@example/package-tool@latest"],
-
-          lockKey: "pnpm-global",
-        },
-      });
+      yield* resolve();
+      yield* resolve();
+      expect(resolutions).toBe(1);
+      yield* resolve({ fresh: true });
+      yield* resolve();
+      expect(resolutions).toBe(2);
     }),
   );
-
-  it("allows the package's own install scripts in npm global updates", () => {
-    const claudeUpdate = makePackageManagedProviderMaintenanceResolver({
-      provider: driver("claudeAgent"),
-      npmPackageName: "@anthropic-ai/claude-code",
-      homebrewFormula: "claude-code",
-      nativeUpdate: {
-        executable: "claude",
-        args: ["update"],
-        lockKey: "claude-native",
-        isCommandPath: isNativeTestCommandPath("/.local/bin/claude"),
-      },
-    });
-
-    expect(claudeUpdate.resolve()).toEqual({
-      provider: driver("claudeAgent"),
-      packageName: "@anthropic-ai/claude-code",
-      update: {
-        command:
-          "npm install -g --allow-scripts=@anthropic-ai/claude-code @anthropic-ai/claude-code@latest",
-
-        executable: "npm",
-
-        args: [
-          "install",
-          "-g",
-          "--allow-scripts=@anthropic-ai/claude-code",
-          "@anthropic-ai/claude-code@latest",
-        ],
-
-        lockKey: "npm-global",
-      },
-    });
-  });
-
-  it("disables one-click updates for explicit custom binary paths it cannot safely map", () => {
-    expect(
-      packageToolUpdate.resolve({
-        binaryPath: "C:\\Tools\\package-tool\\package-tool.exe",
-        env: {
-          PATH: "",
-          PATHEXT: ".COM;.EXE;.BAT;.CMD",
-        },
-      }),
-    ).toEqual({
-      provider: driver("packageTool"),
-      packageName: "@example/package-tool",
-      update: null,
-    });
-  });
 });
diff --git a/apps/server/src/provider/providerMaintenance.ts b/apps/server/src/provider/providerMaintenance.ts
index 14d17cf365c3..e8ff090a4ec9 100644
--- a/apps/server/src/provider/providerMaintenance.ts
+++ b/apps/server/src/provider/providerMaintenance.ts
@@ -4,20 +4,37 @@ import {
   type ServerProviderVersionAdvisory,
 } from "@t3tools/contracts";
 import { compareSemverVersions } from "@t3tools/shared/semver";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { causeErrorTag } from "@t3tools/shared/observability";
 import { resolveCommandPath } from "@t3tools/shared/shell";
 import * as Config from "effect/Config";
 import * as Context from "effect/Context";
 import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Option from "effect/Option";
+import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
 import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
 
 const LATEST_VERSION_CACHE_TTL_MS = 60 * 60 * 1_000;
 const LATEST_VERSION_TIMEOUT_MS = 4_000;
+const HOMEBREW_INFO_TIMEOUT_MS = 10_000;
+const HOMEBREW_INFO_MAX_BYTES = 256 * 1_024;
 const PROVIDER_UPDATE_ACTION_TOAST_MESSAGE = "Install the update now or review provider settings.";
 
+/**
+ * Ownership is re-derived from the executable this often. Installs do not
+ * move on their own, so this mostly bounds how stale a Homebrew "latest" can
+ * get; the npm registry check keeps its own cache.
+ */
+export const MAINTENANCE_CAPABILITIES_CACHE_TTL = Duration.hours(1);
+
 const compactEnv = (input: Record<string, Option.Option<string>>): NodeJS.ProcessEnv =>
   Object.fromEntries(
     Object.entries(input).flatMap(([key, value]) =>
@@ -41,6 +58,13 @@ export interface ProviderMaintenanceCapabilities {
   readonly provider: ProviderDriverKind;
   readonly packageName: string | null;
   readonly update: ProviderMaintenanceCommandAction | null;
+  /**
+   * Latest version reported by the installer that owns the executable.
+   * `undefined` means the installer has no channel of its own and the npm
+   * registry entry for `packageName` is authoritative; `null` means the
+   * installer was asked and did not know.
+   */
+  readonly latestVersion?: string | null;
 }
 
 export interface ProviderMaintenanceCommandAction {
@@ -48,30 +72,44 @@ export interface ProviderMaintenanceCommandAction {
   readonly executable: string;
   readonly args: ReadonlyArray<string>;
   readonly lockKey: string;
+  /**
+   * Extra environment for the spawned updater, on top of the server's own.
+   * A native updater finds its install through the same variables the
+   * provider runs with (e.g. `CODEX_HOME`), so an instance with a custom home
+   * must update that home and not the default one.
+   */
+  readonly env?: NodeJS.ProcessEnv;
 }
 
-export interface ProviderMaintenanceCapabilityResolutionOptions {
-  readonly binaryPath?: string | null;
-  readonly env?: NodeJS.ProcessEnv;
-  readonly resolvedCommandPath?: string | null;
-  readonly realCommandPath?: string | null;
+/** Where the provider executable was found; every path is absolute. */
+export interface ProviderMaintenanceResolutionContext {
+  readonly binaryPath: string;
+  readonly resolvedCommandPath: string;
+  readonly realCommandPath: string;
+  readonly env: NodeJS.ProcessEnv;
+  /** Host platform; decides how the copyable command quotes the executable. */
+  readonly platform: NodeJS.Platform;
 }
 
+export type ProviderMaintenanceResolverServices =
+  | FileSystem.FileSystem
+  | Path.Path
+  | ChildProcessSpawner.ChildProcessSpawner;
+
 export interface ProviderMaintenanceCapabilitiesResolver {
   readonly resolve: (
-    options?: ProviderMaintenanceCapabilityResolutionOptions,
-  ) => ProviderMaintenanceCapabilities;
+    context: ProviderMaintenanceResolutionContext | null,
+  ) => Effect.Effect<ProviderMaintenanceCapabilities, never, ProviderMaintenanceResolverServices>;
 }
 
 export interface PackageManagedProviderMaintenanceDefinition {
   readonly provider: ProviderDriverKind;
   readonly npmPackageName: string;
-  readonly homebrewFormula: string | null;
   readonly nativeUpdate: {
-    readonly executable: string;
     readonly args: ReadonlyArray<string>;
-    readonly lockKey: string;
     readonly isCommandPath: (commandPath: string) => boolean;
+    /** Environment the native updater needs to target this instance's install. */
+    readonly env?: NodeJS.ProcessEnv;
   } | null;
 }
 
@@ -94,26 +132,57 @@ function nonEmptyString(value: unknown): string | null {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
 
+/**
+ * The copyable command must paste into a shell as-is, so an executable path
+ * with spaces or quotes is quoted for the host's default shell.
+ */
+function quoteShellWord(word: string, platform: NodeJS.Platform): string {
+  const safeWord = platform === "win32" ? /^[\w./:\\@=-]+$/ : /^[\w./:@=-]+$/;
+  if (safeWord.test(word)) return word;
+  return platform === "win32"
+    ? `'${word.replace(/['\u2018\u2019]/g, "$&$&")}'`
+    : `'${word.replaceAll("'", "'\\''")}'`;
+}
+
+function quoteUpdateExecutable(executable: string, platform: NodeJS.Platform): string {
+  const quoted = quoteShellWord(executable, platform);
+  // Windows terminals default to PowerShell, where a quoted executable needs &.
+  return platform === "win32" && quoted !== executable ? `& ${quoted}` : quoted;
+}
+
 export function makeProviderMaintenanceCapabilities(input: {
   readonly provider: ProviderDriverKind;
   readonly packageName: string | null;
   readonly updateExecutable: string | null;
   readonly updateArgs: ReadonlyArray<string>;
   readonly updateLockKey: string | null;
+  /** Shown to the user instead of `<executable> <args>`; use for a bare tool name like `brew`. */
+  readonly updateCommand?: string;
+  readonly platform?: NodeJS.Platform;
+  readonly env?: NodeJS.ProcessEnv;
+  readonly latestVersion?: string | null;
 }): ProviderMaintenanceCapabilities {
+  const platform = input.platform ?? HostProcessPlatform.defaultValue();
   const update =
     input.updateExecutable === null || input.updateLockKey === null
       ? null
       : {
-          command: [input.updateExecutable, ...input.updateArgs].join(" "),
+          command:
+            input.updateCommand ??
+            [
+              quoteUpdateExecutable(input.updateExecutable, platform),
+              ...input.updateArgs.map((arg) => quoteShellWord(arg, platform)),
+            ].join(" "),
           executable: input.updateExecutable,
           args: input.updateArgs,
           lockKey: input.updateLockKey,
+          ...(input.env ? { env: input.env } : {}),
         };
   return {
     provider: input.provider,
     packageName: input.packageName,
     update,
+    ...("latestVersion" in input ? { latestVersion: input.latestVersion } : {}),
   };
 }
 
@@ -130,217 +199,320 @@ export function makeManualOnlyProviderMaintenanceCapabilities(input: {
   });
 }
 
-function makeNpmGlobalProviderMaintenanceCapabilities(
-  definition: PackageManagedProviderMaintenanceDefinition,
-): ProviderMaintenanceCapabilities {
-  return makeProviderMaintenanceCapabilities({
-    provider: definition.provider,
-    packageName: definition.npmPackageName,
-    updateExecutable: "npm",
-    // npm 12 blocks install scripts by default (empty allow-scripts allowlist)
-    // and still exits 0, so a package whose postinstall finishes the install
-    // (claude copies its native binary over a placeholder stub) is left broken
-    // while the update reports success. Allow this one package's scripts.
-    // Older npm warns about the unknown config and continues.
-    updateArgs: [
-      "install",
-      "-g",
-      `--allow-scripts=${definition.npmPackageName}`,
-      `${definition.npmPackageName}@latest`,
-    ],
-    updateLockKey: "npm-global",
-  });
+export function normalizeCommandPath(commandPath: string): string {
+  return commandPath.replaceAll("\\", "/").toLowerCase();
 }
 
-function makeBunGlobalProviderMaintenanceCapabilities(
-  definition: PackageManagedProviderMaintenanceDefinition,
-): ProviderMaintenanceCapabilities {
-  return makeProviderMaintenanceCapabilities({
-    provider: definition.provider,
-    packageName: definition.npmPackageName,
-    updateExecutable: "bun",
-    updateArgs: ["i", "-g", `${definition.npmPackageName}@latest`],
-    updateLockKey: "bun-global",
-  });
+function isVitePlusGlobalCommandPath(commandPath: string): boolean {
+  return normalizeCommandPath(commandPath).includes("/.vite-plus/bin/");
 }
 
-function makePnpmGlobalProviderMaintenanceCapabilities(
-  definition: PackageManagedProviderMaintenanceDefinition,
-): ProviderMaintenanceCapabilities {
-  return makeProviderMaintenanceCapabilities({
-    provider: definition.provider,
-    packageName: definition.npmPackageName,
-    updateExecutable: "pnpm",
-    updateArgs: ["add", "-g", `${definition.npmPackageName}@latest`],
-    updateLockKey: "pnpm-global",
-  });
+function isBunGlobalCommandPath(commandPath: string): boolean {
+  return normalizeCommandPath(commandPath).includes("/.bun/bin/");
 }
 
-function makeVitePlusGlobalProviderMaintenanceCapabilities(
-  definition: PackageManagedProviderMaintenanceDefinition,
-): ProviderMaintenanceCapabilities {
-  return makeProviderMaintenanceCapabilities({
-    provider: definition.provider,
-    packageName: definition.npmPackageName,
-    updateExecutable: "vp",
-    updateArgs: ["i", "-g", definition.npmPackageName],
-    updateLockKey: "vite-plus-global",
-  });
+function isPnpmGlobalCommandPath(commandPath: string): boolean {
+  const normalized = normalizeCommandPath(commandPath);
+  return (
+    normalized.includes("/.local/share/pnpm/") ||
+    normalized.includes("/library/pnpm/") ||
+    normalized.includes("/local/share/pnpm/") ||
+    normalized.includes("/appdata/local/pnpm/") ||
+    normalized.includes("/pnpm/global/")
+  );
 }
 
-function makeHomebrewProviderMaintenanceCapabilities(
-  definition: PackageManagedProviderMaintenanceDefinition,
-): ProviderMaintenanceCapabilities {
-  if (!definition.homebrewFormula) {
-    return makeManualOnlyProviderMaintenanceCapabilities({
-      provider: definition.provider,
-      packageName: definition.npmPackageName,
-    });
+/**
+ * The npm global prefix that owns a package, derived from the real path of
+ * its entry point: `<prefix>/lib/node_modules/<pkg>/…`. Windows global
+ * installs have no `lib` segment and are proven by the shim instead (see
+ * `resolveNpmGlobalPrefix`). A project-local `node_modules` is not a global
+ * install and yields null.
+ */
+export function npmGlobalPrefixFromCommandPath(
+  realCommandPath: string,
+  packageName: string,
+): string | null {
+  const slashPath = realCommandPath.replaceAll("\\", "/");
+  const normalized = slashPath.toLowerCase();
+  const packageSegment = `/lib/node_modules/${packageName.toLowerCase()}/`;
+  const packageIndex = normalized.lastIndexOf(packageSegment);
+  if (packageIndex < 0 || normalized.slice(0, packageIndex).includes("/node_modules/")) {
+    return null;
   }
-
-  return makeProviderMaintenanceCapabilities({
-    provider: definition.provider,
-    packageName: definition.npmPackageName,
-    updateExecutable: "brew",
-    updateArgs: ["upgrade", definition.homebrewFormula],
-    updateLockKey: "homebrew",
-  });
-}
-
-function makeNativeProviderMaintenanceCapabilities(
-  definition: PackageManagedProviderMaintenanceDefinition,
-): ProviderMaintenanceCapabilities | null {
-  if (!definition.nativeUpdate) {
+  // Mise's npm backend uses a global-looking layout inside a tool version.
+  // Globals under its Node installation still belong to npm.
+  const miseTool = /\/mise\/installs\/([^/]+)\/[^/]+$/.exec(normalized.slice(0, packageIndex))?.[1];
+  if (miseTool && miseTool !== "node") {
     return null;
   }
-
-  return makeProviderMaintenanceCapabilities({
-    provider: definition.provider,
-    packageName: definition.npmPackageName,
-    updateExecutable: definition.nativeUpdate.executable,
-    updateArgs: definition.nativeUpdate.args,
-    updateLockKey: definition.nativeUpdate.lockKey,
-  });
+  return packageIndex === 0 ? "/" : slashPath.slice(0, packageIndex);
 }
 
-export function hasPathSeparator(value: string): boolean {
-  return value.includes("/") || value.includes("\\");
-}
+// `<prefix>/Cellar/<name>/<version>/…` or `<prefix>/Caskroom/<name>/<version>/…`.
+// Homebrew always nests a version directory under the keg.
+const HOMEBREW_KEG_PATTERN = /^(.*)\/(cellar|caskroom)\/([^/]+)\/[^/]+\//i;
 
-export function normalizeCommandPath(commandPath: string): string {
-  return commandPath.replaceAll("\\", "/").toLowerCase();
+export interface HomebrewOwnership {
+  readonly kind: "formula" | "cask";
+  readonly name: string;
+  /** The Homebrew prefix the keg sits under; must match `brew --prefix`. */
+  readonly prefix: string;
 }
 
-function isBunGlobalCommandPath(commandPath: string): boolean {
-  return normalizeCommandPath(commandPath).includes("/.bun/bin/");
+/**
+ * Homebrew looks like the owner when the real path runs through a versioned
+ * keg or cask. It is only proven once the prefix matches the `brew` that will
+ * run the upgrade (see `resolvePackageManagedProviderMaintenance`).
+ */
+export function homebrewOwnershipFromCommandPath(
+  realCommandPath: string,
+): HomebrewOwnership | null {
+  const match = HOMEBREW_KEG_PATTERN.exec(realCommandPath.replaceAll("\\", "/"));
+  if (!match) {
+    return null;
+  }
+  return {
+    kind: match[2]!.toLowerCase() === "cellar" ? "formula" : "cask",
+    name: match[3]!,
+    prefix: match[1]!,
+  };
 }
 
-function isVitePlusGlobalCommandPath(commandPath: string): boolean {
-  return normalizeCommandPath(commandPath).includes("/.vite-plus/bin/");
-}
+const HomebrewInfoResponse = Schema.Struct({
+  formulae: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        versions: Schema.optional(Schema.Struct({ stable: Schema.optional(Schema.String) })),
+      }),
+    ),
+  ),
+  casks: Schema.optional(Schema.Array(Schema.Struct({ version: Schema.optional(Schema.String) }))),
+});
 
-function isPnpmGlobalCommandPath(commandPath: string): boolean {
-  const normalized = normalizeCommandPath(commandPath);
-  return (
-    normalized.includes("/.local/share/pnpm/") ||
-    normalized.includes("/library/pnpm/") ||
-    normalized.includes("/local/share/pnpm/") ||
-    normalized.includes("/appdata/local/pnpm/") ||
-    normalized.includes("/pnpm/global/")
-  );
-}
+const decodeHomebrewInfo = Schema.decodeUnknownOption(Schema.fromJsonString(HomebrewInfoResponse));
 
-function isNpmGlobalCommandPath(commandPath: string): boolean {
-  const normalized = normalizeCommandPath(commandPath);
-  return (
-    normalized.includes("/node_modules/.bin/") ||
-    normalized.includes("/lib/node_modules/") ||
-    normalized.includes("/npm/node_modules/")
-  );
+/** Cask versions may carry a build suffix after a comma (`1.2.3,456`). */
+export function parseHomebrewLatestVersion(
+  infoJson: string,
+  ownership: HomebrewOwnership,
+): string | null {
+  const decoded = decodeHomebrewInfo(infoJson);
+  if (Option.isNone(decoded)) {
+    return null;
+  }
+  const raw =
+    ownership.kind === "formula"
+      ? decoded.value.formulae?.[0]?.versions?.stable
+      : decoded.value.casks?.[0]?.version?.split(",", 1)[0];
+  return nonEmptyString(raw);
 }
 
-function isHomebrewCommandPath(commandPath: string): boolean {
-  const normalized = normalizeCommandPath(commandPath);
-  return (
-    normalized.includes("/opt/homebrew/cellar/") ||
-    normalized.includes("/usr/local/cellar/") ||
-    normalized.includes("/homebrew/cellar/") ||
-    normalized.includes("/opt/homebrew/caskroom/") ||
-    normalized.includes("/usr/local/caskroom/") ||
-    normalized.includes("/homebrew/caskroom/") ||
-    normalized.startsWith("/opt/homebrew/bin/") ||
-    normalized.startsWith("/usr/local/bin/")
+/** Run `brew <args>` and return stdout, or null on failure, timeout, or oversized output. */
+const runHomebrew = Effect.fn("runHomebrew")(function* (
+  brewPath: string,
+  args: ReadonlyArray<string>,
+  env: NodeJS.ProcessEnv,
+) {
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const collect = Effect.gen(function* () {
+    const child = yield* spawner.spawn(ChildProcess.make(brewPath, args, { env, extendEnv: true }));
+    yield* Effect.addFinalizer(() => child.kill().pipe(Effect.ignore));
+    // stderr is drained so a chatty brew cannot block on a full pipe.
+    const [stdout, exitCode] = yield* Effect.all(
+      [
+        collectUint8StreamText({ stream: child.stdout, maxBytes: HOMEBREW_INFO_MAX_BYTES }),
+        child.exitCode,
+        Stream.runDrain(child.stderr),
+      ],
+      { concurrency: "unbounded" },
+    );
+    return Number(exitCode) !== 0 || stdout.truncated ? null : stdout.text;
+  });
+  return yield* collect.pipe(
+    Effect.scoped,
+    Effect.timeoutOption(Duration.millis(HOMEBREW_INFO_TIMEOUT_MS)),
+    Effect.map(Option.getOrNull),
+    Effect.catchCause((cause) =>
+      Effect.logWarning("Homebrew probe failed", {
+        subcommand: args[0],
+        errorTag: causeErrorTag(cause),
+      }).pipe(Effect.as(null)),
+    ),
   );
-}
+});
 
-export function resolvePackageManagedProviderMaintenance(
+/**
+ * Derive update capabilities from where the executable actually lives. Every
+ * branch that yields a one-click command has evidence that the named tool
+ * owns that path; anything unproven stays manual-only so T3 Code never runs
+ * a package manager against an install it did not create.
+ */
+export const resolvePackageManagedProviderMaintenance = Effect.fn(
+  "resolvePackageManagedProviderMaintenance",
+)(function* (
   definition: PackageManagedProviderMaintenanceDefinition,
-  options?: ProviderMaintenanceCapabilityResolutionOptions,
-): ProviderMaintenanceCapabilities {
-  const binaryPath = nonEmptyString(options?.binaryPath);
-  if (!binaryPath) {
-    return makeNpmGlobalProviderMaintenanceCapabilities(definition);
+  context: ProviderMaintenanceResolutionContext | null,
+) {
+  const manual = makeManualOnlyProviderMaintenanceCapabilities({
+    provider: definition.provider,
+    packageName: definition.npmPackageName,
+  });
+  if (!context) {
+    return manual;
   }
+  const commandPaths = [context.resolvedCommandPath, context.realCommandPath];
+  const packageName = definition.npmPackageName;
 
-  const resolvedCommandPath =
-    options?.resolvedCommandPath ?? (hasPathSeparator(binaryPath) ? binaryPath : null);
+  const nativeUpdate = definition.nativeUpdate;
+  if (nativeUpdate && commandPaths.some((commandPath) => nativeUpdate.isCommandPath(commandPath))) {
+    return makeProviderMaintenanceCapabilities({
+      provider: definition.provider,
+      packageName,
+      updateExecutable: context.resolvedCommandPath,
+      updateArgs: nativeUpdate.args,
+      updateLockKey: `${definition.provider}-native`,
+      platform: context.platform,
+      ...(nativeUpdate.env ? { env: nativeUpdate.env } : {}),
+    });
+  }
+  if (commandPaths.some(isVitePlusGlobalCommandPath)) {
+    return makeProviderMaintenanceCapabilities({
+      provider: definition.provider,
+      packageName,
+      updateExecutable: "vp",
+      updateArgs: ["i", "-g", packageName],
+      updateLockKey: "vite-plus-global",
+    });
+  }
+  if (commandPaths.some(isBunGlobalCommandPath)) {
+    return makeProviderMaintenanceCapabilities({
+      provider: definition.provider,
+      packageName,
+      updateExecutable: "bun",
+      updateArgs: ["i", "-g", `${packageName}@latest`],
+      updateLockKey: "bun-global",
+    });
+  }
+  if (commandPaths.some(isPnpmGlobalCommandPath)) {
+    return makeProviderMaintenanceCapabilities({
+      provider: definition.provider,
+      packageName,
+      updateExecutable: "pnpm",
+      updateArgs: ["add", "-g", `${packageName}@latest`],
+      updateLockKey: "pnpm-global",
+    });
+  }
 
-  if (resolvedCommandPath) {
-    const commandPaths = [
-      resolvedCommandPath,
-      ...(options?.realCommandPath ? [options.realCommandPath] : []),
-    ];
+  // npm proof names the package, so it outranks a keg the path merely passes
+  // through: a Homebrew-installed Node keeps its globals under
+  // `Cellar/node/<ver>/lib/node_modules/`, and that is npm's install, not brew's.
+  const npmPrefix = yield* resolveNpmGlobalPrefix(context, packageName);
+  if (npmPrefix) {
+    // npm 12 blocks install scripts by default (empty allow-scripts allowlist)
+    // and still exits 0, so a package whose postinstall finishes the install
+    // (claude copies its native binary over a placeholder stub) is left broken
+    // while the update reports success. Allow this one package's scripts.
+    // Older npm warns about the unknown config and continues.
+    return makeProviderMaintenanceCapabilities({
+      provider: definition.provider,
+      packageName,
+      updateExecutable: "npm",
+      updateArgs: [
+        "install",
+        "-g",
+        "--prefix",
+        npmPrefix,
+        `--allow-scripts=${packageName}`,
+        `${packageName}@latest`,
+      ],
+      updateLockKey: `npm-global:${normalizeCommandPath(npmPrefix)}`,
+    });
+  }
 
-    const nativeUpdate = definition.nativeUpdate;
-    if (
-      nativeUpdate &&
-      commandPaths.some((commandPath) => nativeUpdate.isCommandPath(commandPath))
-    ) {
-      return (
-        makeNativeProviderMaintenanceCapabilities(definition) ??
-        makeNpmGlobalProviderMaintenanceCapabilities(definition)
-      );
-    }
-    if (commandPaths.some(isVitePlusGlobalCommandPath)) {
-      return makeVitePlusGlobalProviderMaintenanceCapabilities(definition);
-    }
-    if (commandPaths.some(isBunGlobalCommandPath)) {
-      return makeBunGlobalProviderMaintenanceCapabilities(definition);
-    }
-    if (commandPaths.some(isPnpmGlobalCommandPath)) {
-      return makePnpmGlobalProviderMaintenanceCapabilities(definition);
+  const homebrew = homebrewOwnershipFromCommandPath(context.realCommandPath);
+  if (homebrew) {
+    // Mise shims resolve to the version manager, not the provider.
+    if (homebrew.kind === "formula" && homebrew.name.toLowerCase() === "mise") {
+      return manual;
     }
-    if (commandPaths.some(isNpmGlobalCommandPath)) {
-      return makeNpmGlobalProviderMaintenanceCapabilities(definition);
+    const brewPath = yield* resolveCommandPath("brew", { env: context.env }).pipe(
+      Effect.catchTags({ CommandResolutionError: () => Effect.succeed(null) }),
+    );
+    if (!brewPath) {
+      return manual;
     }
-    if (commandPaths.some(isHomebrewCommandPath)) {
-      return makeHomebrewProviderMaintenanceCapabilities(definition);
+    // A keg-shaped path is only Homebrew's if it sits under the prefix of the
+    // `brew` that would upgrade it; `brew --prefix` is a cheap shell script.
+    const fileSystem = yield* FileSystem.FileSystem;
+    const brewPrefix = nonEmptyString(yield* runHomebrew(brewPath, ["--prefix"], context.env));
+    const realBrewPrefix = brewPrefix
+      ? yield* fileSystem.realPath(brewPrefix).pipe(Effect.orElseSucceed(() => brewPrefix))
+      : null;
+    if (
+      !realBrewPrefix ||
+      normalizeCommandPath(realBrewPrefix) !== normalizeCommandPath(homebrew.prefix)
+    ) {
+      return manual;
     }
+    const args =
+      homebrew.kind === "cask" ? ["upgrade", "--cask", homebrew.name] : ["upgrade", homebrew.name];
+    // Homebrew lags npm by hours on every release, so compare against what
+    // `brew upgrade` can actually deliver.
+    const info = yield* runHomebrew(brewPath, ["info", "--json=v2", homebrew.name], context.env);
+    return makeProviderMaintenanceCapabilities({
+      provider: definition.provider,
+      packageName,
+      updateExecutable: brewPath,
+      updateArgs: args,
+      updateLockKey: "homebrew",
+      updateCommand: ["brew", ...args].join(" "),
+      latestVersion: info ? parseHomebrewLatestVersion(info, homebrew) : null,
+    });
   }
 
-  if (!hasPathSeparator(binaryPath)) {
-    return makeNpmGlobalProviderMaintenanceCapabilities(definition);
-  }
+  return manual;
+});
 
-  return makeManualOnlyProviderMaintenanceCapabilities({
-    provider: definition.provider,
-    packageName: definition.npmPackageName,
-  });
-}
+/**
+ * POSIX npm links `<prefix>/bin/<cmd>` into the package, so the real path is
+ * proof. Windows npm writes `.cmd` shims beside `node_modules`, so the proof
+ * is the package manifest next to the shim.
+ */
+const resolveNpmGlobalPrefix = Effect.fn("resolveNpmGlobalPrefix")(function* (
+  context: ProviderMaintenanceResolutionContext,
+  packageName: string,
+) {
+  const fromRealPath = npmGlobalPrefixFromCommandPath(context.realCommandPath, packageName);
+  if (fromRealPath) {
+    return fromRealPath;
+  }
+  if ((yield* HostProcessPlatform) !== "win32") {
+    return null;
+  }
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const shimDir = path.dirname(context.resolvedCommandPath);
+  const manifestPath = path.join(
+    shimDir,
+    "node_modules",
+    ...packageName.split("/"),
+    "package.json",
+  );
+  // npm writes both `<cmd>.cmd` and an extensionless sh script into the
+  // Windows prefix; either one sits directly beside `node_modules`. A POSIX
+  // project checkout has the same shape, which is why this is Windows-only.
+  const hasManifest = yield* fileSystem
+    .exists(manifestPath)
+    .pipe(Effect.orElseSucceed(() => false));
+  return hasManifest ? shimDir : null;
+});
 
 export function makePackageManagedProviderMaintenanceResolver(
   definition: PackageManagedProviderMaintenanceDefinition,
 ): ProviderMaintenanceCapabilitiesResolver {
   return {
-    resolve: (options) => resolvePackageManagedProviderMaintenance(definition, options),
-  };
-}
-
-export function makeStaticProviderMaintenanceResolver(
-  capabilities: ProviderMaintenanceCapabilities,
-): ProviderMaintenanceCapabilitiesResolver {
-  return {
-    resolve: () => capabilities,
+    resolve: (context) => resolvePackageManagedProviderMaintenance(definition, context),
   };
 }
 
@@ -353,38 +525,68 @@ function makeManualProviderMaintenanceCapabilities(
   });
 }
 
+/**
+ * Locate the configured provider executable, follow symlinks, and hand the
+ * result to the resolver. A binary that cannot be found yields the resolver's
+ * no-context answer.
+ */
 export const resolveProviderMaintenanceCapabilitiesEffect = Effect.fn(
   "resolveProviderMaintenanceCapabilitiesEffect",
 )(function* (
   resolver: ProviderMaintenanceCapabilitiesResolver,
-  options?: Omit<ProviderMaintenanceCapabilityResolutionOptions, "realCommandPath">,
+  options?: {
+    readonly binaryPath?: string | null;
+    readonly env?: NodeJS.ProcessEnv;
+  },
 ) {
   const binaryPath = nonEmptyString(options?.binaryPath);
   if (!binaryPath) {
-    return resolver.resolve(options);
+    return yield* resolver.resolve(null);
   }
 
   const env = options?.env ?? (yield* readCommandLookupEnv);
-  const resolvedCommandPath =
-    (yield* resolveCommandPath(binaryPath, { env }).pipe(
-      Effect.catchTag("CommandResolutionError", () => Effect.succeed(null)),
-    )) ?? (hasPathSeparator(binaryPath) ? binaryPath : null);
+  // resolveCommandPath checks explicit paths for existence too, so a missing
+  // binary always lands in the no-context branch and never gets an update
+  // command it cannot run.
+  const resolvedCommandPath = yield* resolveCommandPath(binaryPath, { env }).pipe(
+    Effect.catchTags({ CommandResolutionError: () => Effect.succeed(null) }),
+  );
   if (!resolvedCommandPath) {
-    return resolver.resolve(options);
+    return yield* resolver.resolve(null);
   }
 
   const fileSystem = yield* FileSystem.FileSystem;
   const realCommandPath = yield* fileSystem
     .realPath(resolvedCommandPath)
-    .pipe(Effect.orElseSucceed(() => resolvedCommandPath));
-  return resolver.resolve({
-    ...options,
-    env,
+    .pipe(Effect.orElseSucceed(() => null));
+  if (!realCommandPath) {
+    return yield* resolver.resolve(null);
+  }
+  return yield* resolver.resolve({
+    binaryPath,
     resolvedCommandPath,
     realCommandPath,
+    env,
+    platform: yield* HostProcessPlatform,
   });
 });
 
+/**
+ * Turn a one-shot resolution into the shape drivers expose: a cached read for
+ * advisories and a `fresh` read that update execution uses so it never trusts
+ * ownership derived before the user clicked.
+ */
+export const makeCachedProviderMaintenanceResolution = Effect.fn(
+  "makeCachedProviderMaintenanceResolution",
+)(function* (resolve: Effect.Effect<ProviderMaintenanceCapabilities>) {
+  const [cached, invalidate] = yield* Effect.cachedInvalidateWithTTL(
+    resolve,
+    MAINTENANCE_CAPABILITIES_CACHE_TTL,
+  );
+  return (options?: { readonly fresh?: boolean }) =>
+    options?.fresh ? invalidate.pipe(Effect.andThen(cached)) : cached;
+});
+
 function deriveVersionAdvisory(input: {
   readonly currentVersion: string | null;
   readonly latestVersion: string | null;
@@ -456,6 +658,9 @@ const fetchNpmLatestVersion = Effect.fn("fetchNpmLatestVersion")(function* (pack
 export const resolveLatestProviderVersion = Effect.fn("resolveLatestProviderVersion")(function* (
   maintenanceCapabilities: ProviderMaintenanceCapabilities,
 ) {
+  if (maintenanceCapabilities.latestVersion !== undefined) {
+    return maintenanceCapabilities.latestVersion;
+  }
   const packageName = maintenanceCapabilities.packageName;
   if (!packageName) {
     return null;
diff --git a/apps/server/src/provider/providerMaintenanceRunner.test.ts b/apps/server/src/provider/providerMaintenanceRunner.test.ts
index c45f1f7406cb..19af22c882ae 100644
--- a/apps/server/src/provider/providerMaintenanceRunner.test.ts
+++ b/apps/server/src/provider/providerMaintenanceRunner.test.ts
@@ -70,7 +70,7 @@ const baseProvider: ServerProvider = {
   driver: CODEX_DRIVER,
   enabled: true,
   installed: true,
-  version: null,
+  version: "0.0.0",
   status: "ready",
   auth: { status: "authenticated" },
   checkedAt: "2026-04-10T00:00:00.000Z",
@@ -129,6 +129,7 @@ function mockSpawnerLayer(
   handler: (
     command: string,
     args: ReadonlyArray<string>,
+    options: { readonly env?: NodeJS.ProcessEnv | undefined },
   ) => {
     readonly stdout?: string;
     readonly stderr?: string;
@@ -142,8 +143,11 @@ function mockSpawnerLayer(
       const childProcess = command as unknown as {
         readonly command: string;
         readonly args: ReadonlyArray<string>;
+        readonly options: { readonly env?: NodeJS.ProcessEnv | undefined };
       };
-      return Effect.succeed(mockHandle(handler(childProcess.command, childProcess.args)));
+      return Effect.succeed(
+        mockHandle(handler(childProcess.command, childProcess.args, childProcess.options)),
+      );
     }),
   );
 }
@@ -198,6 +202,7 @@ function makeRegistry(
 
     return {
       registry,
+      providersRef,
       updateStatesRef,
     };
   });
@@ -210,7 +215,8 @@ const makeTestRunner = (registry: ProviderRegistryShape) =>
         Layer.provide(
           Layer.mergeAll(
             Layer.succeed(ProviderRegistry, registry),
-            Layer.succeed(ProviderVersionCache, new Map()),
+            // Fresh per runner so a version cached by one test cannot leak into another.
+            Layer.sync(ProviderVersionCache, () => new Map()),
           ),
         ),
       ),
@@ -250,6 +256,182 @@ describe("providerMaintenanceRunner", () => {
     );
   });
 
+  it.effect("reports unchanged when the updater exits 0 but the provider is gone", () => {
+    return Effect.gen(function* () {
+      const { registry, providersRef } = yield* makeRegistry(baseProvider);
+      // After the update, the refreshed snapshot no longer sees an install.
+      const updater = yield* makeTestRunner({
+        ...registry,
+        refreshInstance: () =>
+          Ref.updateAndGet(providersRef, (providers) =>
+            providers.map((provider) => ({ ...provider, installed: false, version: null })),
+          ),
+      });
+
+      const result = yield* updater.updateProvider(CODEX_DRIVER);
+      assert.strictEqual(result.providers[0]?.updateState?.status, "unchanged");
+      assert.match(result.providers[0]?.updateState?.message ?? "", /could not verify/);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          NonWindowsPlatform,
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer(() => ({ stdout: "updated" })),
+        ),
+      ),
+    );
+  });
+
+  it.effect(
+    "keeps a successful update when the binary is present but its version is unreadable",
+    () => {
+      return Effect.gen(function* () {
+        const { registry, providersRef } = yield* makeRegistry(baseCursorProvider);
+        // Cursor's `agent about` probe can fail right after an update while the
+        // new binary is perfectly fine.
+        const updater = yield* makeTestRunner({
+          ...registry,
+          refreshInstance: () =>
+            Ref.updateAndGet(providersRef, (providers) =>
+              providers.map((provider) => ({ ...provider, installed: true, version: null })),
+            ),
+        });
+
+        const result = yield* updater.updateProvider(CURSOR_DRIVER);
+        assert.strictEqual(result.providers[0]?.updateState?.status, "succeeded");
+      }).pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            NonWindowsPlatform,
+            latestVersionHttpClient("0.0.0"),
+            mockSpawnerLayer(() => ({ stdout: "updated" })),
+          ),
+        ),
+      );
+    },
+  );
+
+  it.effect("spawns the updater with the environment its capabilities declare", () => {
+    const seen: Array<NodeJS.ProcessEnv | undefined> = [];
+    return Effect.gen(function* () {
+      const { registry } = yield* makeRegistry(baseProvider);
+      const updater = yield* makeTestRunner({
+        ...registry,
+        getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider) =>
+          Effect.succeed({
+            ...lifecycleFor(provider),
+            update: {
+              command: "codex update",
+              executable: "/work/codex-home/packages/standalone/bin/codex",
+              args: ["update"],
+              lockKey: "codex-native",
+              env: { CODEX_HOME: "/work/codex-home" },
+            },
+          }),
+      });
+
+      yield* updater.updateProvider(CODEX_DRIVER);
+      assert.deepStrictEqual(seen, [{ CODEX_HOME: "/work/codex-home" }]);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          NonWindowsPlatform,
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer((_command, _args, options) => {
+            seen.push(options.env);
+            return { stdout: "updated" };
+          }),
+        ),
+      ),
+    );
+  });
+
+  it.effect("re-resolves ownership before running and executes the fresh command", () => {
+    const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
+    const fresh: Array<boolean> = [];
+    return Effect.gen(function* () {
+      const { registry } = yield* makeRegistry(baseProvider);
+      const updater = yield* makeTestRunner({
+        ...registry,
+        getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider, options) => {
+          fresh.push(options?.fresh === true);
+          return Effect.succeed(
+            makeProviderMaintenanceCapabilities({
+              provider,
+              packageName: "@openai/codex",
+              updateExecutable: options?.fresh ? "/opt/homebrew/bin/brew" : "brew",
+              updateArgs: ["upgrade", "--cask", "codex"],
+              updateLockKey: "homebrew",
+            }),
+          );
+        },
+      });
+
+      yield* updater.updateProvider(CODEX_DRIVER);
+      // Cached read picks the lock; the two fresh reads bracket the command.
+      assert.deepStrictEqual(fresh, [false, true, true]);
+      assert.deepStrictEqual(calls, [
+        { command: "/opt/homebrew/bin/brew", args: ["upgrade", "--cask", "codex"] },
+      ]);
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          NonWindowsPlatform,
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer((command, args) => {
+            calls.push({ command, args });
+            return { stdout: "updated" };
+          }),
+        ),
+      ),
+    );
+  });
+
+  it.effect("aborts without running when the installation changed since the advisory", () => {
+    const calls: Array<string> = [];
+    return Effect.gen(function* () {
+      const { registry, updateStatesRef } = yield* makeRegistry(baseProvider);
+      const updater = yield* makeTestRunner({
+        ...registry,
+        getProviderMaintenanceCapabilitiesForInstance: (_instanceId, provider, options) =>
+          Effect.succeed(
+            options?.fresh
+              ? makeProviderMaintenanceCapabilities({
+                  provider,
+                  packageName: "@openai/codex",
+                  updateExecutable: null,
+                  updateArgs: [],
+                  updateLockKey: null,
+                })
+              : lifecycleFor(provider),
+          ),
+      });
+
+      const result = yield* updater.updateProvider(CODEX_DRIVER);
+      assert.deepStrictEqual(calls, []);
+      assert.strictEqual(result.providers[0]?.updateState?.status, "failed");
+      assert.strictEqual(
+        result.providers[0]?.updateState?.message,
+        "Provider installation changed. Refresh and try again.",
+      );
+      assert.deepStrictEqual(
+        (yield* Ref.get(updateStatesRef)).map((state) => state.status),
+        ["queued", "running", "failed"],
+      );
+    }).pipe(
+      Effect.provide(
+        Layer.mergeAll(
+          NonWindowsPlatform,
+          latestVersionHttpClient("0.0.0"),
+          mockSpawnerLayer((command) => {
+            calls.push(command);
+            return { stdout: "updated" };
+          }),
+        ),
+      ),
+    );
+  });
+
   it.effect("uses the resolved provider capabilities when choosing the update executable", () => {
     const calls: Array<{ command: string; args: ReadonlyArray<string> }> = [];
     return Effect.gen(function* () {
diff --git a/apps/server/src/provider/providerMaintenanceRunner.ts b/apps/server/src/provider/providerMaintenanceRunner.ts
index 3c114dd83d87..e91560312566 100644
--- a/apps/server/src/provider/providerMaintenanceRunner.ts
+++ b/apps/server/src/provider/providerMaintenanceRunner.ts
@@ -23,7 +23,11 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
 import { ProviderRegistry } from "./Services/ProviderRegistry.ts";
 import { makeProviderMaintenanceCommandCoordinator } from "./providerMaintenanceCommandCoordinator.ts";
-import { enrichProviderSnapshotWithVersionAdvisory } from "./providerMaintenance.ts";
+import {
+  enrichProviderSnapshotWithVersionAdvisory,
+  type ProviderMaintenanceCommandAction,
+  ProviderVersionCache,
+} from "./providerMaintenance.ts";
 import type { ProviderMaintenanceCapabilities } from "./providerMaintenance.ts";
 import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
 const isServerProviderUpdateError = Schema.is(ServerProviderUpdateError);
@@ -73,6 +77,7 @@ const runProviderMaintenanceCommandWithSpawner = Effect.fn("ProviderMaintenanceR
     readonly spawner: ChildProcessSpawner.ChildProcessSpawner["Service"];
     readonly command: string;
     readonly args: ReadonlyArray<string>;
+    readonly env?: NodeJS.ProcessEnv;
   }) {
     const collectCommandResult = Effect.fn("ProviderMaintenanceRunner.collectCommandResult")(
       function* () {
@@ -83,7 +88,12 @@ const runProviderMaintenanceCommandWithSpawner = Effect.fn("ProviderMaintenanceR
         // shell. On Linux/macOS (incl. the WSL backend) this is a no-op.
         const resolved = yield* resolveSpawnCommand(input.command, input.args);
         const child = yield* input.spawner
-          .spawn(ChildProcess.make(resolved.command, resolved.args, { shell: resolved.shell }))
+          .spawn(
+            ChildProcess.make(resolved.command, resolved.args, {
+              shell: resolved.shell,
+              ...(input.env ? { env: input.env, extendEnv: true } : {}),
+            }),
+          )
           .pipe(
             Effect.mapError(
               (cause) =>
@@ -181,6 +191,10 @@ function isOutdatedProvider(provider: ServerProvider | undefined): boolean {
   return provider?.versionAdvisory?.status === "behind_latest";
 }
 
+function isStillInstalled(provider: ServerProvider): boolean {
+  return provider.installed;
+}
+
 function makeUpdateState(input: {
   readonly status: ServerProviderUpdateState["status"];
   readonly startedAt: string | null;
@@ -201,11 +215,13 @@ export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () {
   const providerRegistry = yield* ProviderRegistry;
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const httpClient = yield* HttpClient.HttpClient;
-  const runMaintenanceCommand = (command: string, args: ReadonlyArray<string>) =>
+  const versionCache = yield* ProviderVersionCache;
+  const runMaintenanceCommand = (update: ProviderMaintenanceCommandAction) =>
     runProviderMaintenanceCommandWithSpawner({
       spawner,
-      command,
-      args,
+      command: update.executable,
+      args: update.args,
+      ...(update.env ? { env: update.env } : {}),
     });
   const commandCoordinator = yield* makeProviderMaintenanceCommandCoordinator({
     makeAlreadyRunningError: () =>
@@ -258,17 +274,18 @@ export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () {
             enrichProviderSnapshotWithVersionAdvisory(
               refreshedProvider,
               maintenanceCapabilities,
-            ).pipe(Effect.provideService(HttpClient.HttpClient, httpClient)),
+            ).pipe(
+              Effect.provideService(HttpClient.HttpClient, httpClient),
+              Effect.provideService(ProviderVersionCache, versionCache),
+            ),
           {
             concurrency: "unbounded",
           },
         ).pipe(
-          Effect.map(
-            (verifiedProviders): VerifiedProviderRefresh => ({
-              providers,
-              verifiedProviders,
-            }),
-          ),
+          Effect.map((verifiedProviders): VerifiedProviderRefresh => ({
+            providers,
+            verifiedProviders,
+          })),
           Effect.catchCause((cause) =>
             Effect.logWarning("Provider post-update version verification failed", {
               provider,
@@ -339,7 +356,26 @@ export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () {
               }),
             );
 
-            const result = yield* runMaintenanceCommand(update.executable, update.args);
+            // The cached capabilities chose the lock; re-derive ownership
+            // now so the command that runs matches the executable as it is
+            // at click time, not as it was at the last health refresh.
+            const fresh = yield* providerRegistry.getProviderMaintenanceCapabilitiesForInstance(
+              instanceId,
+              provider,
+              { fresh: true },
+            );
+            if (!fresh.update || fresh.update.lockKey !== update.lockKey) {
+              return yield* finish(
+                makeUpdateState({
+                  status: "failed",
+                  startedAt,
+                  finishedAt: yield* nowIso,
+                  message: "Provider installation changed. Refresh and try again.",
+                }),
+              );
+            }
+
+            const result = yield* runMaintenanceCommand(fresh.update);
             const finishedAt = yield* nowIso;
             if (result.timedOut || result.exitCode !== 0) {
               return yield* finish(
@@ -353,18 +389,30 @@ export const make = Effect.fn("ProviderMaintenanceRunner.make")(function* () {
               );
             }
 
+            // Homebrew's "latest" moves once the upgrade lands; read it again.
+            const verified = yield* providerRegistry.getProviderMaintenanceCapabilitiesForInstance(
+              instanceId,
+              provider,
+              { fresh: true },
+            );
             const { verifiedProviders } = yield* verifyRefreshedProvider(
               provider,
-              capabilities,
+              verified,
               instanceId,
             );
-            const couldNotVerify = verifiedProviders.length === 0;
-            const stillOutdated =
-              couldNotVerify ||
-              verifiedProviders.some((verifiedProvider) => isOutdatedProvider(verifiedProvider));
+            // "Succeeded" needs the provider to still be installed: an
+            // installer that exits 0 and leaves the binary missing is not a
+            // success. A missing version alone is not held against it, since
+            // Cursor's `about` probe can fail transiently on a healthy binary.
+            const couldNotVerify =
+              verifiedProviders.length === 0 ||
+              verifiedProviders.some((verifiedProvider) => !isStillInstalled(verifiedProvider));
+            const stillOutdated = verifiedProviders.some((verifiedProvider) =>
+              isOutdatedProvider(verifiedProvider),
+            );
             return yield* finish(
               makeUpdateState({
-                status: stillOutdated ? "unchanged" : "succeeded",
+                status: couldNotVerify || stillOutdated ? "unchanged" : "succeeded",
                 startedAt,
                 finishedAt,
                 message: couldNotVerify
diff --git a/apps/server/src/provider/providerSnapshot.test.ts b/apps/server/src/provider/providerSnapshot.test.ts
index 011572780666..399d86f7a133 100644
--- a/apps/server/src/provider/providerSnapshot.test.ts
+++ b/apps/server/src/provider/providerSnapshot.test.ts
@@ -52,6 +52,27 @@ describe("providerModelsFromSettings", () => {
     ]);
   });
 
+  it("keeps an entry's own name and capabilities over the driver default", () => {
+    const capabilities = createModelCapabilities({
+      optionDescriptors: [{ id: "fastMode", label: "Fast Mode", type: "boolean" }],
+    });
+    const models = providerModelsFromSettings(
+      [],
+      ["bare", { slug: "named", name: "Named", capabilities }],
+      OPENCODE_CUSTOM_MODEL_CAPABILITIES,
+    );
+
+    expect(models).toEqual([
+      {
+        slug: "bare",
+        name: "bare",
+        isCustom: true,
+        capabilities: OPENCODE_CUSTOM_MODEL_CAPABILITIES,
+      },
+      { slug: "named", name: "Named", isCustom: true, capabilities },
+    ]);
+  });
+
   it("preserves a custom slug that collides with a provider alias", () => {
     const capabilities = createModelCapabilities({ optionDescriptors: [] });
     const models = providerModelsFromSettings(
diff --git a/apps/server/src/provider/providerSnapshot.ts b/apps/server/src/provider/providerSnapshot.ts
index 55534629d3eb..9663aeacb63f 100644
--- a/apps/server/src/provider/providerSnapshot.ts
+++ b/apps/server/src/provider/providerSnapshot.ts
@@ -1,4 +1,5 @@
 import type {
+  CustomModelSetting,
   ProviderDriverKind,
   ModelCapabilities,
   ServerProvider,
@@ -14,7 +15,7 @@ import * as PlatformError from "effect/PlatformError";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
-import { normalizeCustomModelSlug } from "@t3tools/shared/model";
+import { readCustomModelEntries } from "@t3tools/shared/model";
 import { isWindowsCommandNotFound } from "../processRunner.ts";
 import { createProviderVersionAdvisory } from "./providerMaintenance.ts";
 import { collectUint8StreamText } from "../stream/collectUint8StreamText.ts";
@@ -145,26 +146,30 @@ export function parseGenericCliVersion(output: string): string | null {
   return match?.[1] ?? null;
 }
 
+/**
+ * Append the user's custom models after the built-ins. A custom entry that
+ * declares its own capabilities keeps them; a bare slug gets the driver's
+ * default set. Slugs that collide with a built-in are dropped.
+ */
 export function providerModelsFromSettings(
   builtInModels: ReadonlyArray<ServerProviderModel>,
-  customModels: ReadonlyArray<string>,
+  customModels: ReadonlyArray<CustomModelSetting>,
   customModelCapabilities: ModelCapabilities,
 ): ReadonlyArray<ServerProviderModel> {
   const resolvedBuiltInModels = [...builtInModels];
   const seen = new Set(resolvedBuiltInModels.map((model) => model.slug));
   const customEntries: ServerProviderModel[] = [];
 
-  for (const candidate of customModels) {
-    const normalized = normalizeCustomModelSlug(candidate);
-    if (!normalized || seen.has(normalized)) {
+  for (const entry of readCustomModelEntries(customModels)) {
+    if (seen.has(entry.slug)) {
       continue;
     }
-    seen.add(normalized);
+    seen.add(entry.slug);
     customEntries.push({
-      slug: normalized,
-      name: normalized,
+      slug: entry.slug,
+      name: entry.name,
       isCustom: true,
-      capabilities: customModelCapabilities,
+      capabilities: entry.capabilities ?? customModelCapabilities,
     });
   }
 
diff --git a/apps/server/src/provider/testFixtures/codexCollabMockPeer.cmd b/apps/server/src/provider/testFixtures/codexCollabMockPeer.cmd
new file mode 100644
index 000000000000..18220e2c7f69
--- /dev/null
+++ b/apps/server/src/provider/testFixtures/codexCollabMockPeer.cmd
@@ -0,0 +1,8 @@
+@echo off
+rem Wrapper so CodexSessionRuntime can spawn the mock peer on Windows: the
+rem runtime always passes "app-server" as the first argument; drop it and
+rem run the .mjs peer with node. "shift /1" leaves %0 alone so %~dp0 still
+rem names this file's directory.
+shift /1
+node "%~dp0codexCollabMockPeer.mjs" %1 %2 %3 %4 %5 %6 %7 %8 %9
+exit /b %ERRORLEVEL%
diff --git a/apps/server/src/provider/testFixtures/codexCollabMockPeer.mjs b/apps/server/src/provider/testFixtures/codexCollabMockPeer.mjs
index 4e6d1b261947..fa567d75cf8a 100644
--- a/apps/server/src/provider/testFixtures/codexCollabMockPeer.mjs
+++ b/apps/server/src/provider/testFixtures/codexCollabMockPeer.mjs
@@ -57,6 +57,14 @@ rl.on("line", (line) => {
     });
     return;
   }
+  if (method === "account/read") {
+    write({ id, result: { account: { type: "apiKey" }, requiresOpenaiAuth: false } });
+    return;
+  }
+  if (method === "skills/list" || method === "model/list") {
+    write({ id, result: { data: [] } });
+    return;
+  }
   if (method === "thread/start") {
     write({ id, result: fixture.responses.threadStart });
     return;
diff --git a/apps/server/src/pullRequest/AzureDevOpsPullRequestProvider.test.ts b/apps/server/src/pullRequest/AzureDevOpsPullRequestProvider.test.ts
deleted file mode 100644
index 51d8f74bbc45..000000000000
--- a/apps/server/src/pullRequest/AzureDevOpsPullRequestProvider.test.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { describe, expect, it } from "vite-plus/test";
-
-import { AZURE_DEVOPS_VIEWER_PERMISSIONS } from "./AzureDevOpsPullRequestProvider.ts";
-
-describe("azure devops viewer permissions", () => {
-  it("offers every action to whoever is signed in, because Azure names no permission", () => {
-    // The same answer for a viewer who can write, one who can only read, and an author with read
-    // access: `az repos pr show` and `az repos pr list` carry nothing about the caller's standing,
-    // and an unknown permission is granted rather than guessed away. Azure refuses the ones it
-    // will not allow, at the moment they are taken, in words this could not have written.
-    expect(AZURE_DEVOPS_VIEWER_PERMISSIONS).toEqual({
-      actions: [
-        "merge",
-        "ready",
-        "draft",
-        "close",
-        "reopen",
-        "enable-auto-merge",
-        "disable-auto-merge",
-      ],
-      // False because the host itself cannot post one, not because this viewer may not.
-      comment: false,
-      resolve: false,
-      verdicts: [],
-      // True because `az repos pr reviewer` does take one, and Azure says nothing about who may.
-      requestReviewers: true,
-    });
-  });
-});
diff --git a/apps/server/src/pullRequest/AzureDevOpsPullRequestProvider.ts b/apps/server/src/pullRequest/AzureDevOpsPullRequestProvider.ts
index 0062e58a4c87..3d501a32d61b 100644
--- a/apps/server/src/pullRequest/AzureDevOpsPullRequestProvider.ts
+++ b/apps/server/src/pullRequest/AzureDevOpsPullRequestProvider.ts
@@ -56,7 +56,7 @@ const CAPABILITIES: PullRequestCapabilities = {
  * they try. That is the safer half of an unknown: hiding a control from someone entitled to it
  * leaves them no way through and no reason given.
  */
-export const AZURE_DEVOPS_VIEWER_PERMISSIONS: PullRequestViewerPermissions = {
+const AZURE_DEVOPS_VIEWER_PERMISSIONS: PullRequestViewerPermissions = {
   actions: CAPABILITIES.actions,
   comment: CAPABILITIES.comment,
   resolve: CAPABILITIES.review.resolve,
@@ -157,23 +157,21 @@ export const make = Effect.gen(function* () {
     getChangeRequest: (input) =>
       cli.getPullRequest({ cwd: input.cwd, number: input.number }).pipe(
         Effect.mapError(fail("getChangeRequest")),
-        Effect.map(
-          (pullRequest): ProviderChangeRequestDetail => ({
-            ...toChangeRequest(pullRequest),
-            body: pullRequest.body,
-            changedFiles: 0,
-            mergedAt: pullRequest.state === "merged" ? pullRequest.closedAt : null,
-            closedAt: pullRequest.state === "closed" ? pullRequest.closedAt : null,
-            reviewers: pullRequest.reviewers,
-            checks: [],
-            mergeCapabilities: { merge: true, squash: true, rebase: false },
-            viewerPermissions: AZURE_DEVOPS_VIEWER_PERMISSIONS,
-            autoMergeEnabled: pullRequest.autoMergeEnabled,
-            ...(pullRequest.autoMergeMethod === undefined
-              ? {}
-              : { autoMergeMethod: pullRequest.autoMergeMethod }),
-          }),
-        ),
+        Effect.map((pullRequest): ProviderChangeRequestDetail => ({
+          ...toChangeRequest(pullRequest),
+          body: pullRequest.body,
+          changedFiles: 0,
+          mergedAt: pullRequest.state === "merged" ? pullRequest.closedAt : null,
+          closedAt: pullRequest.state === "closed" ? pullRequest.closedAt : null,
+          reviewers: pullRequest.reviewers,
+          checks: [],
+          mergeCapabilities: { merge: true, squash: true, rebase: false },
+          viewerPermissions: AZURE_DEVOPS_VIEWER_PERMISSIONS,
+          autoMergeEnabled: pullRequest.autoMergeEnabled,
+          ...(pullRequest.autoMergeMethod === undefined
+            ? {}
+            : { autoMergeMethod: pullRequest.autoMergeMethod }),
+        })),
       ),
 
     getChangeRequestActivity: (input) =>
@@ -187,15 +185,13 @@ export const make = Effect.gen(function* () {
                 Effect.orElseSucceed(() => ({ comments: [], truncated: true })),
               )
           ).pipe(
-            Effect.map(
-              (conversation): ProviderChangeRequestActivity => ({
-                comments: conversation.comments,
-                commentCount: conversation.comments.length,
-                commentsTruncated: conversation.truncated,
-                reviewThreads: [],
-                commits: [],
-              }),
-            ),
+            Effect.map((conversation): ProviderChangeRequestActivity => ({
+              comments: conversation.comments,
+              commentCount: conversation.comments.length,
+              commentsTruncated: conversation.truncated,
+              reviewThreads: [],
+              commits: [],
+            })),
           ),
         ),
       ),
diff --git a/apps/server/src/pullRequest/PullRequestService.test.ts b/apps/server/src/pullRequest/PullRequestService.test.ts
index 1f2ff59a94d3..eb2f913c9206 100644
--- a/apps/server/src/pullRequest/PullRequestService.test.ts
+++ b/apps/server/src/pullRequest/PullRequestService.test.ts
@@ -1005,10 +1005,12 @@ it.effect("refuses an action the host never claimed it could run", () =>
   }),
 );
 
-it.effect("publishes a successful merge for immediate settlement", () =>
+it.effect("publishes a merge for immediate settlement only after host confirmation", () =>
   Effect.scoped(
     Effect.gen(function* () {
       const mergedAt = "2026-09-03T02:00:00.000Z";
+      let state: "open" | "merged" = "open";
+      let confirmationFails = false;
       const reference = { projectId: "p1" as ProjectId, repository: "acme/web", number: 1 };
       const service = yield* makeService({
         projects: [
@@ -1016,7 +1018,17 @@ it.effect("publishes a successful merge for immediate settlement", () =>
         ],
         providers: [
           fakeProvider("github", {
-            runAction: () => TestClock.setTime(Date.parse(mergedAt)),
+            getChangeRequestSummary: () =>
+              confirmationFails
+                ? Effect.fail(
+                    new PullRequestProviderError({
+                      provider: "github",
+                      operation: "getChangeRequestSummary",
+                      reason: "failed",
+                      detail: "HTTP 504",
+                    }),
+                  )
+                : Effect.succeed({ ...changeRequest(1, mergedAt), state }),
           }),
         ],
       });
@@ -1025,6 +1037,13 @@ it.effect("publishes a successful merge for immediate settlement", () =>
         Effect.forkChild({ startImmediately: true }),
       );
 
+      // Queueing succeeds while the host still reports an open PR.
+      yield* service.runAction({ ...reference, action: "merge" });
+      confirmationFails = true;
+      yield* service.runAction({ ...reference, action: "merge" });
+      confirmationFails = false;
+      state = "merged";
+      yield* TestClock.setTime(Date.parse(mergedAt));
       yield* service.runAction({
         ...reference,
         repository: " ACME/WEB ",
@@ -1965,6 +1984,7 @@ it.effect("refuses a merge strategy the host does not offer", () =>
             review: FULL_REVIEW,
             reviewers: FULL_REVIEWERS,
           },
+          getChangeRequestSummary: () => Effect.succeed(changeRequest(1, "2026-07-02T00:00:00Z")),
           runAction: (input) => {
             ranWith = input.mergeMethod ?? "merge";
             return Effect.void;
@@ -3037,6 +3057,114 @@ it.effect("fills in the line counts for the rows it is given", () =>
     ]);
   }),
 );
+it.effect(
+  "reuses counts across overlapping pages until expiry, explicit invalidation, or a reference changes",
+  () =>
+    Effect.gen(function* () {
+      const asked: number[][] = [];
+      const ref = (number: number) => ({
+        projectId: "p1" as ProjectId,
+        repository: "acme/web",
+        number,
+      });
+      const service = yield* makeService({
+        projects: [
+          project({ id: "p1", title: "web", workspaceRoot: "/a", repository: "acme/web" }),
+        ],
+        providers: [
+          fakeProvider("github", {
+            listChangeRequestStats: (input) => {
+              asked.push(input.changeRequests.map((ref) => ref.number));
+              return Effect.succeed(
+                input.changeRequests.map((ref) => ({ ...ref, additions: 12, deletions: 3 })),
+              );
+            },
+          }),
+        ],
+      });
+
+      yield* service.listStats({ refs: [ref(1), ref(2)] });
+      const overlapping = yield* service.listStats({ refs: [ref(2), ref(3)] });
+      assert.deepStrictEqual(
+        overlapping.stats.map((stat) => stat.number),
+        [2, 3],
+      );
+      yield* service.listStats({ refs: [ref(1), ref(2), ref(3)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3]]);
+
+      yield* service.invalidate({ reference: ref(2) });
+      yield* service.listStats({ refs: [ref(1), ref(2), ref(3)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3], [2]]);
+
+      yield* TestClock.adjust("61 seconds");
+      yield* service.listStats({ refs: [ref(1), ref(2), ref(3)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3], [2], [1, 2, 3]]);
+
+      yield* service.refreshAfterTurn;
+      yield* service.listStats({ refs: [ref(1)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3], [2], [1, 2, 3], [1]]);
+
+      yield* service.invalidate({});
+      yield* service.listStats({ refs: [ref(1)] });
+      assert.deepStrictEqual(asked, [[1, 2], [3], [2], [1, 2, 3], [1], [1]]);
+    }),
+);
+
+it.effect("reads the fresh diff when detail or summary discovers a changed revision", () =>
+  Effect.gen(function* () {
+    const summaryStarted = yield* Deferred.make<void>();
+    const releaseSummary = yield* Deferred.make<void>();
+    let revision = "2026-07-02T00:00:00Z";
+    let patch = "old patch";
+    let diffCalls = 0;
+    const reference = { projectId: "p1" as ProjectId, repository: "acme/web", number: 1 };
+    const service = yield* makeService({
+      projects: [project({ id: "p1", title: "web", workspaceRoot: "/a", repository: "acme/web" })],
+      providers: [
+        fakeProvider("github", {
+          getChangeRequest: () =>
+            Effect.sync(() => ({ ...hostedChangeRequest("body"), updatedAt: revision })),
+          getChangeRequestSummary: () =>
+            Effect.gen(function* () {
+              const result = changeRequest(1, revision);
+              yield* Deferred.succeed(summaryStarted, undefined);
+              yield* Deferred.await(releaseSummary);
+              return result;
+            }),
+          getDiff: () =>
+            Effect.sync(() => {
+              diffCalls += 1;
+              return { patch, truncated: false, nextCursor: null };
+            }),
+        }),
+      ],
+    });
+
+    const coldSummary = yield* service.summary(reference).pipe(Effect.forkChild());
+    yield* Deferred.await(summaryStarted);
+    yield* service.detail(reference);
+    assert.strictEqual((yield* service.diff(reference)).patch, "old patch");
+    revision = "2026-07-02T00:01:00Z";
+    patch = "new patch";
+    yield* TestClock.adjust("16 seconds");
+    yield* service.detail(reference);
+    yield* Effect.yieldNow;
+    assert.strictEqual((yield* service.detail(reference)).updatedAt, revision);
+    yield* Deferred.succeed(releaseSummary, undefined);
+    yield* Fiber.join(coldSummary);
+    yield* service.summary(reference, { recoverTransientFailure: false });
+    assert.strictEqual((yield* service.diff(reference)).patch, "new patch");
+    assert.strictEqual(diffCalls, 2);
+
+    revision = "2026-07-02T00:02:00Z";
+    patch = "summary-discovered patch";
+    yield* TestClock.adjust("61 seconds");
+    yield* service.summary(reference, { recoverTransientFailure: false });
+    assert.strictEqual((yield* service.diff(reference)).patch, patch);
+    assert.strictEqual(diffCalls, 3);
+  }),
+);
+
 it.effect("keeps the rows when the line counts cannot be read", () =>
   Effect.gen(function* () {
     const service = yield* makeService({
@@ -3060,6 +3188,7 @@ it.effect(
     Effect.gen(function* () {
       let coreCalls = 0;
       let activityCalls = 0;
+      let statsCalls = 0;
       const reference = { projectId: "p1" as ProjectId, repository: "acme/web", number: 1 };
       const service = yield* makeService({
         projects: [
@@ -3067,6 +3196,10 @@ it.effect(
         ],
         providers: [
           fakeProvider("github", {
+            listChangeRequestStats: () => {
+              statsCalls += 1;
+              return Effect.succeed([]);
+            },
             getChangeRequest: () => {
               coreCalls += 1;
               return Effect.succeed({
@@ -3106,6 +3239,16 @@ it.effect(
       assert.strictEqual(coreCalls, 1);
       assert.strictEqual(activityCalls, 0);
 
+      const counts = yield* service.listStats({ refs: [reference] });
+      assert.strictEqual(statsCalls, 0);
+      assert.deepStrictEqual(counts.stats, [
+        {
+          ...reference,
+          additions: core.additions,
+          deletions: core.deletions,
+        },
+      ]);
+
       yield* Effect.all([service.activity(reference), service.activity(reference)], {
         concurrency: 2,
       });
diff --git a/apps/server/src/pullRequest/PullRequestService.ts b/apps/server/src/pullRequest/PullRequestService.ts
index 6a37ed935848..a8d3dc2fdeaf 100644
--- a/apps/server/src/pullRequest/PullRequestService.ts
+++ b/apps/server/src/pullRequest/PullRequestService.ts
@@ -2136,6 +2136,21 @@ export const make = Effect.gen(function* () {
     Math.max(turnRefreshEpoch, refEpochs.get(refScope(ref)) ?? 0);
   const refCacheKey = (ref: PullRequestRef) =>
     JSON.stringify([refEpoch(ref), ref.projectId, ref.repository, ref.number]);
+  // Counts belong to a PR, not a filtered page. Background reads and filter changes reuse
+  // them; explicit refreshes, mutations, and turns strand old and in-flight results.
+  const statsCacheKey = (key: string) => JSON.stringify([listingsEpoch, key]);
+  const recentStats = new Map<
+    string,
+    { readonly at: number; readonly value: PullRequestDiffStat }
+  >();
+  const recordStats = (key: string, value: PullRequestDiffStat, at: number) => {
+    recentStats.delete(key);
+    recentStats.set(key, { at, value });
+    if (recentStats.size > REF_EPOCH_CAPACITY) {
+      const oldest = recentStats.keys().next().value;
+      if (oldest !== undefined) recentStats.delete(oldest);
+    }
+  };
   const bumpRefEpoch = (ref: PullRequestRef) => {
     const scope = refScope(ref);
     if (!refEpochs.has(scope) && refEpochs.size >= REF_EPOCH_CAPACITY) {
@@ -2175,13 +2190,15 @@ export const make = Effect.gen(function* () {
   const summary: PullRequestService["Service"]["summary"] = (input, options) => {
     const key = refCacheKey(input);
     const cached = Cache.get(summaryCache, key);
-    if (options?.recoverTransientFailure !== false) {
-      return lastGoodSummary.serveHeld(key, cached, "reuse");
-    }
     const held = lastGoodSummary.peek(key);
-    return held?.state === "merged"
+    return held !== undefined &&
+      (options?.recoverTransientFailure !== false || held.state === "merged")
       ? Effect.succeed(held)
-      : cached.pipe(Effect.tap((value) => lastGoodSummary.record(key, value)));
+      : cached.pipe(
+          Effect.tap((value) =>
+            shouldReplaceHeldSummary(key, value) ? lastGoodSummary.record(key, value) : Effect.void,
+          ),
+        );
   };
 
   // Keys serialize positionally and parse back in the lookup, so the cache is the only holder
@@ -2263,8 +2280,25 @@ export const make = Effect.gen(function* () {
 
   const detailCache = yield* Cache.makeWith(
     (key: string) => {
+      const statsKey = statsCacheKey(key);
       const [, projectId, repository, number] = JSON.parse(key) as [number, string, string, number];
-      return detailUncached({ projectId, repository, number } as PullRequestRef);
+      return detailUncached({ projectId, repository, number } as PullRequestRef).pipe(
+        Effect.tap(
+          Effect.fn("PullRequestService.recordDetailStats")(function* (value: PullRequestDetail) {
+            recordStats(
+              statsKey,
+              {
+                projectId: value.projectId,
+                repository: value.repository,
+                number: value.number,
+                additions: value.additions,
+                deletions: value.deletions,
+              },
+              yield* Clock.currentTimeMillis,
+            );
+          }),
+        ),
+      );
     },
     {
       capacity: DETAIL_CACHE_CAPACITY,
@@ -2360,38 +2394,69 @@ export const make = Effect.gen(function* () {
       input.number,
       input.cursor ?? null,
       input.commit ?? null,
+      input.commit === undefined
+        ? (lastGoodSummary.peek(refCacheKey(input))?.updatedAt ?? null)
+        : null,
     ]);
     return staleDiff(key, Cache.get(diffCache, key));
   };
 
   const listStatsCache = yield* Cache.makeWith(
     (key: string) => {
-      const [, refs] = JSON.parse(key) as [number, ReadonlyArray<[string, string, number]>];
+      const [, refs] = JSON.parse(key) as [number, ReadonlyArray<[string, string, number, number]>];
       return listStatsUncached({
         refs: refs.map(([projectId, repository, number]) => ({ projectId, repository, number })),
-      } as unknown as PullRequestListStatsInput);
+      } as unknown as PullRequestListStatsInput).pipe(
+        Effect.flatMap((result) =>
+          Clock.currentTimeMillis.pipe(Effect.map((at) => ({ result, at }))),
+        ),
+      );
     },
     {
       capacity: LIST_STATS_CACHE_CAPACITY,
       timeToLive: (exit) => (Exit.isSuccess(exit) ? LIST_STATS_CACHE_TTL : Duration.zero),
     },
   );
-  // The stats read leans on the host's search API — the scarcest limit of them all — so it
-  // shares between clients like every other read. Refs are sorted so one page's worth of rows
-  // is one key however the client assembled them, and the listings epoch rides along so the
-  // refresh that forgets the listing forgets its decorations with it.
-  const listStats: PullRequestService["Service"]["listStats"] = (input) => {
-    if (input.refs.length === 0) return Effect.succeed({ stats: [] });
-    const key = JSON.stringify([
+  const statsBatchKey = (refs: Iterable<PullRequestRef>) =>
+    JSON.stringify([
       listingsEpoch,
-      input.refs
-        .map((ref) => [ref.projectId, ref.repository, ref.number] as const)
+      [...refs]
+        .map((ref) => [ref.projectId, ref.repository, ref.number, refEpoch(ref)] as const)
         .toSorted((left, right) =>
           `${left[0]} ${left[1]} ${left[2]}`.localeCompare(`${right[0]} ${right[1]} ${right[2]}`),
         ),
     ]);
-    return Cache.get(listStatsCache, key);
-  };
+  // Exact batches share in-flight reads; overlapping pages reuse each row already fetched.
+  const listStats: PullRequestService["Service"]["listStats"] = Effect.fn(
+    "PullRequestService.listStats",
+  )(function* (input: PullRequestListStatsInput) {
+    if (input.refs.length === 0) return { stats: [] };
+    const now = yield* Clock.currentTimeMillis;
+    const held: PullRequestDiffStat[] = [];
+    const missing = new Map<string, PullRequestRef>();
+    for (const ref of input.refs) {
+      const key = statsCacheKey(refCacheKey(ref));
+      const cached = recentStats.get(key);
+      if (cached !== undefined && now - cached.at < Duration.toMillis(LIST_STATS_CACHE_TTL)) {
+        held.push(cached.value);
+      } else {
+        missing.set(key, ref);
+      }
+    }
+    if (missing.size === 0) return { stats: held };
+    const key = statsBatchKey(missing.values());
+    const { result, at } = yield* Cache.get(listStatsCache, key);
+    for (const [key, ref] of missing) {
+      const stat = result.stats.find(
+        (stat) =>
+          stat.projectId === ref.projectId &&
+          stat.repository.toLowerCase() === ref.repository.toLowerCase() &&
+          stat.number === ref.number,
+      );
+      if (stat !== undefined) recordStats(key, stat, at);
+    }
+    return { stats: [...held, ...result.stats] };
+  });
 
   const invalidate: PullRequestService["Service"]["invalidate"] = (input) => {
     const reference = input.reference;
@@ -2432,6 +2497,15 @@ export const make = Effect.gen(function* () {
     bumpRefEpoch({ ...input, repository });
     listingsEpoch = ++epochCounter;
     if (input.action === "merge") {
+      // A successful merge action can merely enqueue the PR or enable auto-merge.
+      const confirmed = yield* summaryUncached({ ...input, repository }).pipe(
+        Effect.catch((error) =>
+          Effect.logWarning("failed to confirm pull request merge", { error }).pipe(
+            Effect.as(null),
+          ),
+        ),
+      );
+      if (confirmed?.state !== "merged") return;
       yield* PubSub.publish(mergedPullRequests, {
         projectId: input.projectId,
         repository,
diff --git a/apps/server/src/relay/AgentAwarenessRelay.test.ts b/apps/server/src/relay/AgentAwarenessRelay.test.ts
index b38861c9877e..59049500729d 100644
--- a/apps/server/src/relay/AgentAwarenessRelay.test.ts
+++ b/apps/server/src/relay/AgentAwarenessRelay.test.ts
@@ -39,6 +39,7 @@ import {
   type ProjectionSnapshotQueryShape,
 } from "../orchestration/Services/ProjectionSnapshotQuery.ts";
 import {
+  isAgentActivityPublishingEnabledValue,
   RELAY_ENVIRONMENT_CREDENTIAL_SECRET,
   RELAY_ISSUER_SECRET,
   RELAY_URL_SECRET,
@@ -137,7 +138,7 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
     expect(AgentAwarenessRelay.eventThreadId(event)).toBe(threadId);
   });
 
-  it("does not publish start intents, streaming content, or non-awareness activity events", () => {
+  it("does not publish imported, start-intent, streaming, or non-awareness events", () => {
     const now = "2026-05-25T00:00:00.000Z";
     const base = {
       sequence: 1,
@@ -146,6 +147,7 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
       aggregateKind: "thread",
       aggregateId: "thread-1" as ThreadId,
       occurredAt: now,
+      metadata: {},
     };
 
     expect(
@@ -201,6 +203,36 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
         },
       } as unknown as OrchestrationEvent),
     ).toBe(false);
+    expect(
+      AgentAwarenessRelay.shouldPublishAgentAwarenessEvent({
+        ...base,
+        type: "thread.created",
+        metadata: { historyImport: true },
+        payload: { threadId: "thread-1" as ThreadId },
+      } as unknown as OrchestrationEvent),
+    ).toBe(false);
+    expect(
+      AgentAwarenessRelay.shouldPublishAgentAwarenessEvent({
+        ...base,
+        type: "thread.settled",
+        metadata: { historyImport: true },
+        payload: { threadId: "thread-1" as ThreadId },
+      } as unknown as OrchestrationEvent),
+    ).toBe(false);
+    expect(
+      AgentAwarenessRelay.shouldPublishAgentAwarenessEvent({
+        ...base,
+        type: "thread.created",
+        payload: { threadId: "thread-1" as ThreadId },
+      } as unknown as OrchestrationEvent),
+    ).toBe(true);
+    expect(
+      AgentAwarenessRelay.shouldPublishAgentAwarenessEvent({
+        ...base,
+        type: "thread.settled",
+        payload: { threadId: "thread-1" as ThreadId },
+      } as unknown as OrchestrationEvent),
+    ).toBe(true);
   });
 
   it("deduplicates awareness state updates whose only change is their event timestamp", () => {
@@ -220,9 +252,10 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
   });
 
   it("requires an explicit opt-in before publishing agent activity", () => {
-    expect(AgentAwarenessRelay.isAgentActivityPublishingEnabled(null)).toBe(false);
-    expect(AgentAwarenessRelay.isAgentActivityPublishingEnabled("false")).toBe(false);
-    expect(AgentAwarenessRelay.isAgentActivityPublishingEnabled("true")).toBe(true);
+    expect(isAgentActivityPublishingEnabledValue(null)).toBe(false);
+    expect(isAgentActivityPublishingEnabledValue("false")).toBe(false);
+    expect(isAgentActivityPublishingEnabledValue("TRUE")).toBe(false);
+    expect(isAgentActivityPublishingEnabledValue("true")).toBe(true);
   });
 
   it("redacts failed activity details and caps other relay detail", () => {
@@ -398,17 +431,32 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
     }),
   );
 
-  it.effect("keeps the orchestration listener armed until relay config is installed", () =>
+  it.effect("keeps the listener armed and skips imported thread work", () =>
     Effect.scoped(
       Effect.gen(function* () {
         const events = yield* Queue.unbounded<OrchestrationEvent>();
         const threadShellRequested = yield* Deferred.make<void>();
+        const releaseThreadShell = yield* Deferred.make<void>();
+        const threadShellRequests: Array<ThreadId> = [];
+        let fetchCallCount = 0;
         const secrets = makeMemorySecretStore();
         const now = "2026-05-25T00:00:00.000Z";
         const projectId = "project-1" as ProjectId;
         const threadId = "thread-1" as ThreadId;
+        const importedThreadId = "import:codex:session-1" as ThreadId;
         const environmentId = "env-1" as EnvironmentId;
 
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = (() => {
+          fetchCallCount += 1;
+          return Promise.resolve(Response.json({ ok: true, deliveries: [] }));
+        }) as unknown as typeof fetch;
+        yield* Effect.addFinalizer(() =>
+          Effect.sync(() => {
+            globalThis.fetch = originalFetch;
+          }),
+        );
+
         const project = {
           id: projectId,
           title: "T3 Code",
@@ -459,6 +507,8 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
 
         const orchestrationEngine = {
           readEvents: () => Stream.empty,
+          readThreadEvents: () => Stream.empty,
+          getThreadReplayStats: () => Effect.die("unused thread replay stats"),
           dispatch: () => Effect.succeed({ sequence: 1 }),
           streamDomainEvents: Stream.fromQueue(events),
           subscribeDomainEvents: Effect.succeed(Stream.fromQueue(events)),
@@ -469,15 +519,18 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
           getShellSnapshot: () =>
             Effect.succeed({
               snapshotSequence: 1,
-              projects: [project],
-              threads: [thread],
+              projects: [],
+              threads: [],
               updatedAt: now,
             } satisfies OrchestrationShellSnapshot),
-          getThreadShellById: () =>
-            Deferred.succeed(threadShellRequested, undefined).pipe(
-              Effect.ignore,
-              Effect.as(Option.some(thread)),
-            ),
+          getThreadShellById: (requestedThreadId: ThreadId) =>
+            Effect.gen(function* () {
+              threadShellRequests.push(requestedThreadId);
+              if (requestedThreadId !== threadId) return Option.none();
+              yield* Deferred.succeed(threadShellRequested, undefined);
+              yield* Deferred.await(releaseThreadShell);
+              return Option.some(thread);
+            }),
           getProjectShellById: () => Effect.succeed(Option.some(project)),
         } as unknown as ProjectionSnapshotQueryShape;
 
@@ -507,17 +560,40 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
         yield* Effect.gen(function* () {
           const relay = yield* AgentAwarenessRelay.AgentAwarenessRelay;
           yield* relay.start();
-          yield* secrets.setString(RELAY_URL_SECRET, "http://127.0.0.1:1");
+          yield* secrets.setString(RELAY_URL_SECRET, "https://relay.example.test");
           yield* secrets.setString(RELAY_ENVIRONMENT_CREDENTIAL_SECRET, "relay-credential");
           yield* secrets.setString(PUBLISH_AGENT_ACTIVITY_SECRET, "true");
           yield* Queue.offer(events, {
-            type: "thread.activity-appended",
+            type: "thread.created",
             sequence: 1,
+            eventId: "evt-import-created",
+            commandId: CommandId.make("cmd-import-created"),
+            aggregateKind: "thread",
+            aggregateId: importedThreadId,
+            metadata: { historyImport: true },
+            payload: { threadId: importedThreadId },
+            occurredAt: now,
+          } as unknown as OrchestrationEvent);
+          yield* Queue.offer(events, {
+            type: "thread.settled",
+            sequence: 2,
+            eventId: "evt-import-settled",
+            commandId: CommandId.make("cmd-import-settled"),
+            aggregateKind: "thread",
+            aggregateId: importedThreadId,
+            metadata: { historyImport: true },
+            payload: { threadId: importedThreadId },
+            occurredAt: now,
+          } as unknown as OrchestrationEvent);
+          yield* Queue.offer(events, {
+            type: "thread.activity-appended",
+            sequence: 3,
             eventId: "evt-1",
             commandId: CommandId.make("cmd-1"),
             aggregateKind: "thread",
             aggregateId: threadId,
             actor: { kind: "server" },
+            metadata: {},
             payload: {
               threadId,
               activity: {
@@ -528,6 +604,9 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
           } as unknown as OrchestrationEvent);
 
           yield* Deferred.await(threadShellRequested).pipe(Effect.timeout("2 seconds"));
+          expect(threadShellRequests).toEqual([threadId]);
+          expect(fetchCallCount).toBe(0);
+          yield* Deferred.succeed(releaseThreadShell, undefined);
         }).pipe(
           Effect.provide(
             AgentAwarenessRelay.layer.pipe(
@@ -653,6 +732,8 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
           }),
           Layer.succeed(OrchestrationEngineService, {
             readEvents: () => Stream.empty,
+            readThreadEvents: () => Stream.empty,
+            getThreadReplayStats: () => Effect.die("unused thread replay stats"),
             dispatch: () => Effect.succeed({ sequence: 1 }),
             streamDomainEvents: Stream.fromQueue(events),
             subscribeDomainEvents: Effect.succeed(Stream.fromQueue(events)),
@@ -686,6 +767,7 @@ describe.sequential("signRelayAgentActivityPublishProof", () => {
             aggregateKind: "thread",
             aggregateId: threadId,
             actor: { kind: "server" },
+            metadata: {},
             payload: {
               threadId,
               activity: {
diff --git a/apps/server/src/relay/AgentAwarenessRelay.ts b/apps/server/src/relay/AgentAwarenessRelay.ts
index 5127ecf7d359..8d7b9e98361e 100644
--- a/apps/server/src/relay/AgentAwarenessRelay.ts
+++ b/apps/server/src/relay/AgentAwarenessRelay.ts
@@ -67,6 +67,9 @@ export function eventThreadId(event: OrchestrationEvent): ThreadId | null {
 }
 
 export function shouldPublishAgentAwarenessEvent(event: OrchestrationEvent): boolean {
+  if (event.metadata.historyImport === true) {
+    return false;
+  }
   switch (event.type) {
     case "thread.message-sent":
     case "thread.turn-start-requested":
@@ -102,10 +105,6 @@ export function agentAwarenessPublishIdentity(state: RelayAgentActivityState | n
   return JSON.stringify(meaningfulState);
 }
 
-export function isAgentActivityPublishingEnabled(value: string | null): boolean {
-  return isAgentActivityPublishingEnabledValue(value);
-}
-
 export function resolveAgentActivityPublishingStartupState(input: {
   readonly relayConfigured: boolean;
   readonly publishEnabled: boolean;
@@ -322,7 +321,7 @@ export const make = Effect.gen(function* () {
   });
 
   const readPublishAgentActivityEnabled = readSecretString(PUBLISH_AGENT_ACTIVITY_SECRET).pipe(
-    Effect.map(isAgentActivityPublishingEnabled),
+    Effect.map(isAgentActivityPublishingEnabledValue),
   );
 
   const makeRelayClient = (relayConfig: {
diff --git a/apps/server/src/resourceTelemetry/NativeTelemetryClient.test.ts b/apps/server/src/resourceTelemetry/NativeTelemetryClient.test.ts
index 8a595bc8b480..7d365d0c0bac 100644
--- a/apps/server/src/resourceTelemetry/NativeTelemetryClient.test.ts
+++ b/apps/server/src/resourceTelemetry/NativeTelemetryClient.test.ts
@@ -1,6 +1,5 @@
 import type { HostPowerSnapshot } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
-import * as Cause from "effect/Cause";
 import * as DateTime from "effect/DateTime";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
@@ -9,12 +8,9 @@ import * as Ref from "effect/Ref";
 import * as Semaphore from "effect/Semaphore";
 
 import {
-  NativeTelemetryRequestTimedOut,
-  NativeTelemetryStreamClosed,
   canCommandNativeTelemetrySidecar,
   canRequestNativeTelemetryRetry,
   commitCollectionControlUpdate,
-  nativeTelemetrySupervisorFailureMessage,
   retainRecentNativeTelemetryFailures,
   resolveNativeSampleIntervalMs,
   synchronizeCollectionControlOnStart,
@@ -82,44 +78,6 @@ describe("canCommandNativeTelemetrySidecar", () => {
   });
 });
 
-describe("NativeTelemetryRequestTimedOut", () => {
-  it("models history and sample request deadlines without a fabricated cause", () => {
-    const historyTimeout = new NativeTelemetryRequestTimedOut({
-      operation: "readHistory",
-      timeoutMs: 15_000,
-    });
-    const sampleTimeout = new NativeTelemetryRequestTimedOut({
-      operation: "sampleNow",
-      timeoutMs: 5_000,
-    });
-
-    expect(historyTimeout.message).toBe(
-      "Resource monitor 'readHistory' request timed out after 15000ms.",
-    );
-    expect(sampleTimeout.message).toBe(
-      "Resource monitor 'sampleNow' request timed out after 5000ms.",
-    );
-    expect("cause" in historyTimeout).toBe(false);
-    expect("cause" in sampleTimeout).toBe(false);
-  });
-});
-
-describe("native telemetry supervisor failures", () => {
-  it("distinguishes a closed event stream from a process exit", () => {
-    expect(new NativeTelemetryStreamClosed().message).toBe(
-      "Resource monitor event stream closed unexpectedly.",
-    );
-  });
-
-  it("keeps defect details out of the caller-visible health message", () => {
-    const secret = "credential=do-not-expose";
-    const message = nativeTelemetrySupervisorFailureMessage(Cause.die(new Error(secret)));
-
-    expect(message).toBe("Resource monitor supervisor stopped unexpectedly.");
-    expect(message).not.toContain(secret);
-  });
-});
-
 describe("retainRecentNativeTelemetryFailures", () => {
   it("expires old failures so an isolated crash restarts from the initial backoff", () => {
     expect(retainRecentNativeTelemetryFailures([0, 30_000], 90_001)).toEqual([]);
diff --git a/apps/server/src/resourceTelemetry/NativeTelemetryClient.ts b/apps/server/src/resourceTelemetry/NativeTelemetryClient.ts
index 232079d9dc9b..4af8f1b762d5 100644
--- a/apps/server/src/resourceTelemetry/NativeTelemetryClient.ts
+++ b/apps/server/src/resourceTelemetry/NativeTelemetryClient.ts
@@ -73,7 +73,7 @@ export class NativeTelemetryHandshakeTimedOut extends Schema.TaggedErrorClass<Na
   }
 }
 
-export class NativeTelemetryRequestTimedOut extends Schema.TaggedErrorClass<NativeTelemetryRequestTimedOut>()(
+class NativeTelemetryRequestTimedOut extends Schema.TaggedErrorClass<NativeTelemetryRequestTimedOut>()(
   "NativeTelemetryRequestTimedOut",
   {
     operation: Schema.Literals(["readHistory", "sampleNow"]),
@@ -131,7 +131,7 @@ export class NativeTelemetryExited extends Schema.TaggedErrorClass<NativeTelemet
   }
 }
 
-export class NativeTelemetryStreamClosed extends Schema.TaggedErrorClass<NativeTelemetryStreamClosed>()(
+class NativeTelemetryStreamClosed extends Schema.TaggedErrorClass<NativeTelemetryStreamClosed>()(
   "NativeTelemetryStreamClosed",
   {},
 ) {
@@ -340,10 +340,6 @@ function errorMessage(error: NativeTelemetryClientError): string {
   return error.message;
 }
 
-export function nativeTelemetrySupervisorFailureMessage(_cause: Cause.Cause<unknown>): string {
-  return "Resource monitor supervisor stopped unexpectedly.";
-}
-
 export function canRequestNativeTelemetryRetry(
   status: ResourceTelemetrySourceStatus,
   hasHandle: boolean,
@@ -734,7 +730,7 @@ export const make = Effect.fn("resourceTelemetry.nativeTelemetryClient.make")(fu
             ...current,
             status: "unavailable" as const,
             hello: Option.none(),
-            lastError: Option.some(nativeTelemetrySupervisorFailureMessage(cause)),
+            lastError: Option.some("Resource monitor supervisor stopped unexpectedly."),
           })).pipe(
             Effect.andThen(publishHealth),
             Effect.andThen(
diff --git a/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts b/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts
index 243556b6e3b0..7fa23aac3908 100644
--- a/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts
+++ b/apps/server/src/resourceTelemetry/ResourceMonitorBinary.test.ts
@@ -11,6 +11,10 @@ import * as FileSystem from "effect/FileSystem";
 import { ServerConfig } from "../config.ts";
 import * as ResourceMonitorBinary from "./ResourceMonitorBinary.ts";
 
+// The override checks POSIX exec bits on a real file under a linux platform
+// mock; NTFS never reports those bits, so the check cannot be satisfied there.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 describe("ResourceMonitorBinary", () => {
   afterEach(() => {
     vi.restoreAllMocks();
@@ -42,7 +46,7 @@ describe("ResourceMonitorBinary", () => {
     }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
   );
 
-  it.effect("resolves an executable override", () =>
+  it.effect.skipIf(windowsHost)("resolves an executable override", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* fileSystem.makeTempDirectoryScoped({
@@ -66,7 +70,7 @@ describe("ResourceMonitorBinary", () => {
     }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
   );
 
-  it.effect("resolves an executable override on an unsupported platform", () =>
+  it.effect.skipIf(windowsHost)("resolves an executable override on an unsupported platform", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
       const baseDir = yield* fileSystem.makeTempDirectoryScoped({
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index 92e47ddb303e..b96313bb9f66 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -36,6 +36,7 @@ import {
   type ProviderInstallState,
   ProviderSetupError,
   ResolvedKeybindingRule,
+  type ServerLifecycleStreamEvent,
   ThreadId,
   TurnId,
   WS_METHODS,
@@ -91,6 +92,7 @@ const decodeTransferThreadSnapshot = Schema.decodeUnknownEffect(
 const decodeTransferShellSnapshot = Schema.decodeUnknownEffect(
   Schema.fromJsonString(OrchestrationShellSnapshot),
 );
+const encodeTestJson = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
 
 import * as BackgroundPolicy from "./background/BackgroundPolicy.ts";
 import * as ServerConfig from "./config.ts";
@@ -115,6 +117,8 @@ import {
 import * as ProjectionSnapshotQuery from "./orchestration/Services/ProjectionSnapshotQuery.ts";
 import { ThreadDeletionReactor } from "./orchestration/Services/ThreadDeletionReactor.ts";
 import { SqlitePersistenceMemory } from "./persistence/Layers/Sqlite.ts";
+import { OrchestrationEventStoreLive } from "./persistence/Layers/OrchestrationEventStore.ts";
+import { OrchestrationEventStore } from "./persistence/Services/OrchestrationEventStore.ts";
 import { PersistenceSqlError } from "./persistence/Errors.ts";
 import * as ProviderRegistry from "./provider/Services/ProviderRegistry.ts";
 import * as ProviderService from "./provider/Services/ProviderService.ts";
@@ -125,6 +129,7 @@ import {
   AntigravityInstallationError,
 } from "./provider/AntigravityInstallation.ts";
 import type { ProviderInstance } from "./provider/ProviderDriver.ts";
+import * as ProviderSessionDirectory from "./provider/Services/ProviderSessionDirectory.ts";
 import { ProviderAdapterRequestError } from "./provider/Errors.ts";
 import { makeManualOnlyProviderMaintenanceCapabilities } from "./provider/providerMaintenance.ts";
 import * as ServerLifecycleEvents from "./serverLifecycleEvents.ts";
@@ -198,6 +203,7 @@ import {
   type TransferBudgetRun,
   transferBudgetViolations,
 } from "../integration/TransferBudgetReport.integration.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const defaultProjectId = ProjectId.make("project-default");
 const defaultThreadId = ThreadId.make("thread-default");
@@ -511,6 +517,9 @@ const buildAppUnderTest = (options?: {
     projectSetupScriptRunner?: Partial<
       ProjectSetupScriptRunner.ProjectSetupScriptRunner["Service"]
     >;
+    providerSessionDirectory?: Partial<
+      ProviderSessionDirectory.ProviderSessionDirectory["Service"]
+    >;
     terminalManager?: Partial<TerminalManager.TerminalManager["Service"]>;
     orchestrationEngine?: Partial<OrchestrationEngine.OrchestrationEngineService["Service"]>;
     threadDeletionReactor?: Partial<ThreadDeletionReactor["Service"]>;
@@ -792,6 +801,13 @@ const buildAppUnderTest = (options?: {
             managedDirectory: "unused-test-antigravity-runtime",
             ...options?.layers?.antigravityInstallation,
           }),
+          Layer.mock(ProviderSessionDirectory.ProviderSessionDirectory)({
+            upsert: () => Effect.void,
+            getBinding: () => Effect.succeed(Option.none()),
+            listThreadIds: () => Effect.succeed([]),
+            listBindings: () => Effect.succeed([]),
+            ...options?.layers?.providerSessionDirectory,
+          }),
         ),
       ),
       Layer.provide(
@@ -928,6 +944,13 @@ const buildAppUnderTest = (options?: {
         Layer.mergeAll(
           Layer.mock(OrchestrationEngine.OrchestrationEngineService)({
             readEvents: () => Stream.empty,
+            readThreadEvents: () => Stream.empty,
+            getThreadReplayStats: () =>
+              Effect.succeed({
+                eventCount: 0,
+                payloadBytes: 0,
+                hasCreateEvent: false,
+              }),
             dispatch: () => Effect.succeed({ sequence: 0 }),
             streamDomainEvents: Stream.empty,
             latestSequence: Effect.succeed(0),
@@ -973,6 +996,7 @@ const buildAppUnderTest = (options?: {
             }),
           getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
           getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+          getImportedAgentSessionSources: () => Effect.succeed([]),
           getThreadCheckpointContext: () => Effect.succeed(Option.none()),
           ...options?.layers?.projectionSnapshotQuery,
         }),
@@ -1204,6 +1228,32 @@ const withWsRpcClient = <A, E, R>(
   onMessage?: (message: string) => void,
 ) => makeWsRpcClient.pipe(Effect.flatMap(f), Effect.provide(wsRpcProtocolLayer(wsUrl, onMessage)));
 
+const withFirstWsAckHeld = (
+  wsUrl: string,
+  held: Deferred.Deferred<void>,
+  release: Deferred.Deferred<void>,
+) => {
+  let holdNextAck = true;
+  return Layer.effect(RpcClient.Protocol)(
+    Effect.map(RpcClient.Protocol, (protocol) =>
+      RpcClient.Protocol.of({
+        ...protocol,
+        send: (clientId, request, transferables) => {
+          const send = protocol.send(clientId, request, transferables);
+          if (request._tag !== "Ack" || !holdNextAck) {
+            return send;
+          }
+          holdNextAck = false;
+          return Deferred.succeed(held, undefined).pipe(
+            Effect.andThen(Deferred.await(release)),
+            Effect.andThen(send),
+          );
+        },
+      }),
+    ),
+  ).pipe(Layer.provide(wsRpcProtocolLayer(wsUrl)));
+};
+
 const appendSessionCookieToWsUrl = (url: string, sessionCookieHeader: string) => {
   const isAbsoluteUrl = /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(url);
   const next = new URL(url, "http://localhost");
@@ -1657,6 +1707,359 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("revalidates static files without sending unchanged bodies", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-static-cache-" });
+      const assetPath = path.join(staticDir, "app.js");
+      yield* fileSystem.writeFileString(assetPath, 'export const build = "first";');
+      yield* buildAppUnderTest({ config: { staticDir } });
+
+      const initial = yield* HttpClient.get("/app.js");
+      assert.equal(initial.status, 200);
+      assert.equal(initial.headers["cache-control"], "no-cache");
+      assert.include(yield* initial.text, "first");
+      const etag = initial.headers.etag;
+      assert.isDefined(etag);
+      assert.isDefined(initial.headers["last-modified"]);
+
+      for (const headers of [
+        { "if-none-match": etag! },
+        { "if-none-match": `"older", ${etag!.replace(/^W\//, "")}` },
+        { "if-none-match": "*" },
+        { "if-modified-since": initial.headers["last-modified"]! },
+      ]) {
+        const response = yield* HttpClient.get("/app.js", { headers });
+        assert.equal(response.status, 304);
+        assert.equal(response.headers.etag, etag);
+        assert.equal(response.headers["cache-control"], "no-cache");
+        assert.equal(yield* response.text, "");
+      }
+
+      const mismatched = yield* HttpClient.get("/app.js", {
+        headers: {
+          "if-none-match": '"another-build"',
+          "if-modified-since": initial.headers["last-modified"]!,
+        },
+      });
+      assert.equal(mismatched.status, 200);
+      assert.include(yield* mismatched.text, "first");
+
+      yield* fileSystem.writeFileString(assetPath, 'export const build = "the next build";');
+      const changed = yield* HttpClient.get("/app.js", { headers: { "if-none-match": etag! } });
+      assert.equal(changed.status, 200);
+      assert.notEqual(changed.headers.etag, etag);
+      assert.include(yield* changed.text, "next build");
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("serves changed HTML with the same size and timestamp", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-static-html-" });
+      const indexPath = path.join(staticDir, "index.html");
+      const modifiedAt = DateTime.toDateUtc(DateTime.makeUnsafe("1985-10-26T08:15:00.000Z"));
+      yield* fileSystem.writeFileString(indexPath, "<html>old build</html>");
+      yield* fileSystem.utimes(indexPath, modifiedAt, modifiedAt);
+      yield* buildAppUnderTest({ config: { staticDir } });
+
+      const initial = yield* HttpClient.get("/");
+      assert.equal(yield* initial.text, "<html>old build</html>");
+      const previousEtag = initial.headers.etag ?? '"previous-html"';
+      const nextHtml = "<html>new build</html>";
+      yield* fileSystem.writeFileString(indexPath, nextHtml);
+      yield* fileSystem.utimes(indexPath, modifiedAt, modifiedAt);
+
+      for (const [resource, headers] of [
+        ["/", { "if-none-match": previousEtag }],
+        ["/threads/example", { "if-modified-since": modifiedAt.toUTCString() }],
+        ["/", { "if-none-match": "*" }],
+      ] as const) {
+        const response = yield* HttpClient.get(resource, { headers });
+        assert.equal(response.status, 200);
+        assert.equal(yield* response.text, nextHtml);
+        assert.equal(response.headers["cache-control"], "no-cache");
+        assert.isUndefined(response.headers.etag);
+        assert.isUndefined(response.headers["last-modified"]);
+      }
+
+      const head = yield* HttpClient.head("/", {
+        headers: { "if-none-match": previousEtag, "accept-encoding": "identity" },
+      });
+      assert.equal(head.status, 200);
+      assert.equal(head.headers["content-length"], String(Buffer.byteLength(nextHtml)));
+      assert.equal(yield* head.text, "");
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("caches hashed static assets without freezing mutable files or SPA fallbacks", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-static-hashes-" });
+      yield* fileSystem.makeDirectory(path.join(staticDir, "assets"));
+      yield* fileSystem.makeDirectory(path.join(staticDir, ".vite"));
+      yield* fileSystem.writeFileString(
+        path.join(staticDir, ".vite", "manifest.json"),
+        `{
+          "index.html": { "file": "assets/index-AbCd0123.js", "isEntry": true },
+          "large.js": { "file": "assets/large-aBcD9876.js" }
+        }`,
+      );
+      yield* fileSystem.writeFileString(path.join(staticDir, "index.html"), "<html>app</html>");
+      yield* fileSystem.writeFileString(
+        path.join(staticDir, "assets", "index-AbCd0123.js"),
+        "export const app = true;",
+      );
+      yield* fileSystem.writeFileString(path.join(staticDir, "assets", "config.json"), "{}");
+      const largeAsset = "export const value = 123;\n".repeat(8192);
+      yield* fileSystem.writeFileString(
+        path.join(staticDir, "assets", "large-aBcD9876.js"),
+        largeAsset,
+      );
+      yield* buildAppUnderTest({ config: { staticDir } });
+
+      const asset = yield* HttpClient.get("/assets/index-AbCd0123.js");
+      assert.equal(asset.status, 200);
+      assert.equal(asset.headers["cache-control"], "public, max-age=31536000, immutable");
+      assert.equal(yield* asset.text, "export const app = true;");
+
+      const head = yield* HttpClient.head("/assets/index-AbCd0123.js", {
+        headers: { "accept-encoding": "identity" },
+      });
+      assert.equal(head.status, 200);
+      assert.equal(head.headers.etag, asset.headers.etag);
+      assert.equal(head.headers["content-length"], String("export const app = true;".length));
+      assert.equal(yield* head.text, "");
+
+      const compressed = yield* HttpClient.get("/assets/large-aBcD9876.js", {
+        headers: { "accept-encoding": "gzip" },
+      });
+      assert.equal(compressed.headers["content-encoding"], "gzip");
+      assert.equal(compressed.headers.vary, "Accept-Encoding");
+      assert.equal(yield* compressed.text, largeAsset);
+      const compressedHead = yield* HttpClient.head("/assets/large-aBcD9876.js", {
+        headers: { "accept-encoding": "gzip" },
+      });
+      assert.equal(compressedHead.status, 200);
+      assert.equal(compressedHead.headers["content-encoding"], "gzip");
+      assert.equal(compressedHead.headers.vary, "Accept-Encoding");
+      assert.equal(compressedHead.headers.etag, compressed.headers.etag);
+      assert.equal(compressedHead.headers["content-length"], compressed.headers["content-length"]);
+      assert.equal(yield* compressedHead.text, "");
+      const unchanged = yield* HttpClient.get("/assets/large-aBcD9876.js", {
+        headers: { "accept-encoding": "identity", "if-none-match": compressed.headers.etag! },
+      });
+      assert.equal(unchanged.status, 304);
+      assert.equal(unchanged.headers.vary, "Accept-Encoding");
+      assert.equal(yield* unchanged.text, "");
+
+      for (const resource of [
+        "/assets/config.json",
+        "/threads/example",
+        "/assets/old-ZyXw9876.js",
+      ]) {
+        const response = yield* HttpClient.get(resource);
+        assert.equal(response.status, 200);
+        assert.equal(response.headers["cache-control"], "no-cache");
+        assert.equal(
+          yield* response.text,
+          resource.endsWith("config.json") ? "{}" : "<html>app</html>",
+        );
+      }
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  for (const manifest of [
+    { label: "missing", contents: null },
+    { label: "nonmatching", contents: '{"other.js":{"file":"assets/other-AbCd0123.js"}}' },
+    { label: "malformed", contents: "{not-json" },
+  ]) {
+    it.effect(`revalidates hash-like static filenames with a ${manifest.label} manifest`, () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const staticDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-static-mutable-",
+        });
+        yield* fileSystem.makeDirectory(path.join(staticDir, "assets"));
+        if (manifest.contents !== null) {
+          yield* fileSystem.makeDirectory(path.join(staticDir, ".vite"));
+          yield* fileSystem.writeFileString(
+            path.join(staticDir, ".vite", "manifest.json"),
+            manifest.contents,
+          );
+        }
+        const filePath = path.join(staticDir, "assets", "config-20260904.js");
+        yield* fileSystem.writeFileString(filePath, "first config");
+        yield* buildAppUnderTest({ config: { staticDir } });
+
+        const initial = yield* HttpClient.get("/assets/config-20260904.js");
+        assert.equal(initial.headers["cache-control"], "no-cache");
+        assert.equal(yield* initial.text, "first config");
+
+        yield* fileSystem.writeFileString(filePath, "replacement config");
+        const changed = yield* HttpClient.get("/assets/config-20260904.js", {
+          headers: { "if-none-match": initial.headers.etag! },
+        });
+        assert.equal(changed.status, 200);
+        assert.equal(changed.headers["cache-control"], "no-cache");
+        assert.notEqual(changed.headers.etag, initial.headers.etag);
+        assert.equal(yield* changed.text, "replacement config");
+      }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+    );
+  }
+
+  it.effect("binds static metadata and bytes to one file across atomic replacement", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-static-replace-" });
+      const beforeOpenPath = path.join(staticDir, "before-open.txt");
+      const afterOpenPath = path.join(staticDir, "after-open.txt");
+      const afterOpenSnapshotPath = path.join(staticDir, "after-open-snapshot.txt");
+      const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+      const original = "original bytes";
+      const replacement = "replacement bytes with a different size";
+      for (const filePath of [beforeOpenPath, afterOpenPath]) {
+        yield* fileSystem.writeFileString(filePath, original);
+        yield* fileSystem.writeFileString(`${filePath}.next`, replacement);
+      }
+      if (windowsHost) {
+        // Windows cannot replace an open destination, so model the race with its original handle.
+        yield* fileSystem.writeFileString(afterOpenSnapshotPath, original);
+      }
+      const replaced = new Set<string>();
+      const replaceOnce = Effect.fnUntraced(function* (filePath: string) {
+        if (replaced.has(filePath)) return;
+        replaced.add(filePath);
+        yield* fileSystem.rename(`${filePath}.next`, filePath);
+      });
+      const replacingFileSystem = FileSystem.FileSystem.of({
+        ...fileSystem,
+        stat: (filePath) =>
+          fileSystem
+            .stat(filePath)
+            .pipe(
+              Effect.tap(() => (filePath === beforeOpenPath ? replaceOnce(filePath) : Effect.void)),
+            ),
+        open: (filePath, options) =>
+          fileSystem
+            .open(
+              filePath === afterOpenPath && windowsHost ? afterOpenSnapshotPath : filePath,
+              options,
+            )
+            .pipe(
+              Effect.tap(() => (filePath === afterOpenPath ? replaceOnce(filePath) : Effect.void)),
+            ),
+      });
+      yield* buildAppUnderTest({ config: { staticDir } }).pipe(
+        Effect.provideService(FileSystem.FileSystem, replacingFileSystem),
+      );
+
+      for (const [name, expected] of [
+        ["before-open.txt", replacement],
+        ["after-open.txt", original],
+      ] as const) {
+        const response = yield* HttpClient.get(`/${name}`, {
+          headers: { "accept-encoding": "identity" },
+        });
+        assert.equal(response.status, 200);
+        assert.equal(response.headers["content-length"], String(expected.length));
+        assert.isTrue(response.headers.etag?.startsWith(`W/"${expected.length.toString(16)}-`));
+        assert.equal(yield* response.text, expected);
+        assert.isTrue(replaced.has(path.join(staticDir, name)));
+        assert.equal(yield* fileSystem.readFileString(path.join(staticDir, name)), replacement);
+      }
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("closes static file handles after GET, HEAD, 304, and request cancellation", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-static-close-" });
+      const filePath = path.join(staticDir, "app.txt");
+      const body = "file content\n".repeat(1024);
+      yield* fileSystem.writeFileString(filePath, body);
+      const closed = yield* Queue.unbounded<FileSystem.File>();
+      const blocked = yield* Deferred.make<void>();
+      const active = new Set<FileSystem.File>();
+      let blockAfterOpen = false;
+      let bodyReads = 0;
+      const trackedFileSystem = FileSystem.FileSystem.of({
+        ...fileSystem,
+        open: (candidate, options) =>
+          Effect.gen(function* () {
+            if (candidate !== filePath) return yield* fileSystem.open(candidate, options);
+            let opened: FileSystem.File | undefined;
+            // Registered first, so this signal runs after the real descriptor-close finalizer.
+            yield* Effect.addFinalizer(() =>
+              Effect.gen(function* () {
+                if (opened === undefined) return;
+                active.delete(opened);
+                yield* Queue.offer(closed, opened);
+              }),
+            );
+            const file = yield* fileSystem.open(candidate, options);
+            opened = file;
+            active.add(file);
+            if (blockAfterOpen) {
+              yield* Deferred.succeed(blocked, undefined);
+              return yield* Effect.never;
+            }
+            return new Proxy(file, {
+              get(target, key) {
+                if (key === "readAlloc") {
+                  return (size: FileSystem.SizeInput) => {
+                    bodyReads += 1;
+                    return target.readAlloc(size);
+                  };
+                }
+                return Reflect.get(target, key, target);
+              },
+            });
+          }),
+      });
+      yield* buildAppUnderTest({ config: { staticDir } }).pipe(
+        Effect.provideService(FileSystem.FileSystem, trackedFileSystem),
+      );
+
+      const get = yield* HttpClient.get("/app.txt");
+      assert.equal(yield* get.text, body);
+      yield* Queue.take(closed);
+      assert.equal(active.size, 0);
+      assert.isAbove(bodyReads, 0);
+      const readsAfterGet = bodyReads;
+
+      const head = yield* HttpClient.head("/app.txt", { headers: { "accept-encoding": "gzip" } });
+      assert.equal(head.status, 200);
+      assert.equal(head.headers["content-encoding"], "gzip");
+      assert.equal(yield* head.text, "");
+      yield* Queue.take(closed);
+      assert.equal(active.size, 0);
+      assert.equal(bodyReads, readsAfterGet);
+
+      const unchanged = yield* HttpClient.get("/app.txt", {
+        headers: { "if-none-match": get.headers.etag! },
+      });
+      assert.equal(unchanged.status, 304);
+      yield* Queue.take(closed);
+      assert.equal(active.size, 0);
+      assert.equal(bodyReads, readsAfterGet);
+
+      blockAfterOpen = true;
+      const cancelled = yield* HttpClient.get("/app.txt").pipe(Effect.forkChild);
+      yield* Deferred.await(blocked);
+      assert.equal(active.size, 1);
+      yield* Fiber.interrupt(cancelled);
+      yield* Queue.take(closed);
+      assert.equal(active.size, 0);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("redirects to dev URL when configured", () =>
     Effect.gen(function* () {
       yield* buildAppUnderTest({
@@ -1915,6 +2318,38 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("replaces the local desktop credential on repeated bootstrap exchanges", () =>
+    Effect.gen(function* () {
+      yield* buildAppUnderTest();
+      const first = yield* exchangeAccessToken();
+      const second = yield* exchangeAccessToken();
+      const third = yield* exchangeAccessToken();
+      assert.equal(first.response.status, 200);
+      assert.equal(second.response.status, 200);
+      assert.equal(third.response.status, 200);
+
+      const clientsResponse = yield* HttpClient.get("/api/auth/clients", {
+        headers: { authorization: `Bearer ${third.body.access_token}` },
+      });
+      const clients = (yield* clientsResponse.json) as ReadonlyArray<{
+        readonly current: boolean;
+        readonly subject: string;
+      }>;
+      assert.equal(clientsResponse.status, 200);
+      assert.equal(clients.length, 1);
+      assert.equal(clients[0]?.current, true);
+      assert.equal(clients[0]?.subject, "desktop-bootstrap");
+
+      for (const previous of [first, second]) {
+        const response = yield* HttpClient.get("/api/auth/session", {
+          headers: { authorization: `Bearer ${previous.body.access_token}` },
+        });
+        const state = (yield* response.json) as { readonly authenticated: boolean };
+        assert.equal(state.authenticated, false);
+      }
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("persists token exchange client display metadata for authorized-client listings", () =>
     Effect.gen(function* () {
       yield* buildAppUnderTest({
@@ -4921,6 +5356,103 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("keeps agent session import project failures structured over websocket rpc", () =>
+    Effect.gen(function* () {
+      yield* buildAppUnderTest();
+
+      const projectId = ProjectId.make("missing-import-project");
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const error = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[WS_METHODS.agentSessionsImport]({ projectId }).pipe(Effect.flip),
+        ),
+      );
+
+      assert.equal(error._tag, "AgentSessionImportProjectNotFoundError");
+      if (error._tag === "AgentSessionImportProjectNotFoundError") {
+        assert.equal(error.projectId, projectId);
+      }
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("returns scanner skip counts over websocket rpc", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const codexHome = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-agent-import-rpc-codex-",
+      });
+      const workspaceRoot = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-agent-import-rpc-workspace-",
+      });
+      const transcriptDirectory = path.join(codexHome, "sessions", "2026", "08", "31");
+      const transcriptPath = path.join(transcriptDirectory, "rollout-skipped.jsonl");
+      yield* fileSystem.makeDirectory(transcriptDirectory, { recursive: true });
+      yield* fileSystem.writeFileString(
+        transcriptPath,
+        encodeTestJson({
+          timestamp: "2026-08-31T12:00:00.000Z",
+          type: "session_meta",
+          payload: { id: "rpc-skipped-session", cwd: workspaceRoot },
+        }),
+      );
+      yield* fileSystem.utimes(transcriptPath, 0, 0);
+
+      const projectId = ProjectId.make("agent-import-rpc-project");
+      const project = {
+        id: projectId,
+        title: "Agent import RPC",
+        workspaceRoot,
+        defaultModelSelection: null,
+        scripts: [],
+        createdAt: "2026-08-31T12:00:00.000Z",
+        updatedAt: "2026-08-31T12:00:00.000Z",
+      } as const;
+      yield* buildAppUnderTest({
+        layers: {
+          serverSettings: {
+            getSettings: Effect.succeed({
+              ...DEFAULT_SERVER_SETTINGS,
+              providerInstances: {
+                [ProviderInstanceId.make("codex")]: {
+                  driver: ProviderDriverKind.make("codex"),
+                  config: { homePath: codexHome },
+                },
+                [ProviderInstanceId.make("claudeAgent")]: {
+                  driver: ProviderDriverKind.make("claudeAgent"),
+                  enabled: false,
+                  config: {},
+                },
+              },
+            }),
+          },
+          projectionSnapshotQuery: {
+            getProjectShellById: (requestedProjectId) =>
+              Effect.succeed(
+                requestedProjectId === projectId ? Option.some(project) : Option.none(),
+              ),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const result = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          Effect.gen(function* () {
+            const scan = yield* client[WS_METHODS.agentSessionsScan]({});
+            assert.deepEqual(
+              scan.candidates.map((candidate) => candidate.path),
+              [workspaceRoot],
+            );
+            return yield* client[WS_METHODS.agentSessionsImport]({ projectId });
+          }),
+        ),
+      );
+
+      assert.deepEqual(result, { importedCount: 0, skippedCount: 1 });
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("uploads Codex thread feedback through websocket rpc", () =>
     Effect.gen(function* () {
       const input = {
@@ -5949,6 +6481,98 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("subscribeServerLifecycle buffers updates published during snapshot capture", () =>
+    Effect.gen(function* () {
+      const pubsub = yield* PubSub.unbounded<ServerLifecycleStreamEvent>();
+      const streamSubscribed = yield* Deferred.make<void>();
+      const snapshotPublished = yield* Deferred.make<void>();
+      const bootstrapProjectId = ProjectId.make("project-bootstrap");
+      const bootstrapThreadId = ThreadId.make("thread-bootstrap");
+      const snapshotEvent = {
+        version: 1 as const,
+        sequence: 1,
+        type: "welcome" as const,
+        payload: {
+          environment: testEnvironmentDescriptor,
+          cwd: "/tmp/project",
+          projectName: "project",
+          bootstrapStatus: "pending" as const,
+        },
+      };
+      const gapEvent = {
+        version: 1 as const,
+        sequence: 2,
+        type: "welcome" as const,
+        payload: {
+          environment: testEnvironmentDescriptor,
+          cwd: "/tmp/project",
+          projectName: "project",
+          bootstrapStatus: "complete" as const,
+          bootstrapProjectId,
+          bootstrapThreadId,
+          bootstrapProjectCreated: true,
+          bootstrapThreadCreated: true,
+        },
+      };
+      const sentinelEvent = {
+        version: 1 as const,
+        sequence: 3,
+        type: "ready" as const,
+        payload: { at: "2026-01-01T00:00:01.000Z", environment: testEnvironmentDescriptor },
+      };
+      const liveStream = Stream.unwrap(
+        Effect.gen(function* () {
+          const subscription = yield* PubSub.subscribe(pubsub);
+          yield* Deferred.succeed(streamSubscribed, undefined);
+          return Stream.fromSubscription(subscription);
+        }),
+      );
+
+      yield* buildAppUnderTest({
+        layers: {
+          serverLifecycleEvents: {
+            snapshot: PubSub.publish(pubsub, gapEvent).pipe(
+              Effect.andThen(Deferred.succeed(snapshotPublished, undefined)),
+              Effect.as({ sequence: 1, events: [snapshotEvent] }),
+            ),
+            stream: liveStream,
+          },
+        },
+      });
+
+      yield* Effect.gen(function* () {
+        yield* Deferred.await(snapshotPublished);
+        yield* Deferred.await(streamSubscribed);
+        yield* PubSub.publish(pubsub, sentinelEvent);
+      }).pipe(Effect.forkScoped);
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const events = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[WS_METHODS.subscribeServerLifecycle]({}).pipe(Stream.take(2), Stream.runCollect),
+        ),
+      );
+
+      const [first, second] = Array.from(events);
+      assert.equal(first?.type, "welcome");
+      assert.equal(first?.sequence, 1);
+      if (first?.type !== "welcome") {
+        assert.fail("expected the pending bootstrap event");
+      }
+      assert.equal(first.payload.bootstrapStatus, "pending");
+      assert.equal(second?.type, "welcome");
+      assert.equal(second?.sequence, 2);
+      if (second?.type !== "welcome") {
+        assert.fail("expected the bootstrap completion event");
+      }
+      assert.equal(second.payload.bootstrapStatus, "complete");
+      assert.equal(second.payload.bootstrapProjectId, bootstrapProjectId);
+      assert.equal(second.payload.bootstrapThreadId, bootstrapThreadId);
+      assert.equal(second.payload.bootstrapProjectCreated, true);
+      assert.equal(second.payload.bootstrapThreadCreated, true);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("routes websocket rpc projects.searchEntries", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
@@ -6071,7 +6695,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest), TestClock.withLive),
   );
 
-  it.effect("preserves structured workspace rpc failures", () =>
+  it.effect.skipIf(!symlinksSupported)("preserves structured workspace rpc failures", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
@@ -7616,6 +8240,104 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  for (const subscription of ["thread", "shell"] as const) {
+    it.effect("delivers large raw tool results through the " + subscription + " stream", () =>
+      Effect.gen(function* () {
+        const eventThreadId =
+          subscription === "thread" ? defaultThreadId : ThreadId.make("other-live-thread");
+        const thread = makeDefaultOrchestrationReadModel().threads[0]!;
+        const baseEvent = makeLiveToolActivityEvent(2, "tool.completed");
+        const event: OrchestrationEvent = {
+          ...baseEvent,
+          aggregateId: eventThreadId,
+          payload: {
+            threadId: eventThreadId,
+            activity: {
+              ...baseEvent.payload.activity,
+              summary: "Build complete",
+              payload: {
+                itemType: "command_execution",
+                toolCallId: "call-build",
+                status: "completed",
+                title: "Build complete",
+                data: {
+                  item: {
+                    command: "build",
+                    aggregatedOutput: "Build complete\n" + "x".repeat(9 * 1024 * 1024),
+                  },
+                },
+              },
+            },
+          },
+        };
+        yield* buildAppUnderTest({
+          layers: {
+            orchestrationEngine: {
+              streamDomainEvents: Stream.concat(Stream.make(event), Stream.never),
+            },
+            projectionSnapshotQuery: {
+              getThreadDetailSnapshot: () =>
+                Effect.succeed(Option.some({ snapshotSequence: 1, thread })),
+              getThreadShellById: (threadId) =>
+                Effect.succeed(
+                  Option.some({
+                    ...makeDefaultOrchestrationThreadShell(),
+                    id: threadId,
+                    title: "Build complete",
+                  }),
+                ),
+            },
+          },
+        });
+
+        const wsUrl = yield* getWsServerUrl("/ws");
+        const items =
+          subscription === "thread"
+            ? yield* Effect.scoped(
+                withWsRpcClient(wsUrl, (client) =>
+                  client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+                    threadId: defaultThreadId,
+                    requestCompletionMarker: true,
+                  }).pipe(
+                    Stream.takeUntil((item) => item.kind === "synchronized"),
+                    Stream.runCollect,
+                  ),
+                ),
+              )
+            : yield* Effect.scoped(
+                withWsRpcClient(wsUrl, (client) =>
+                  client[ORCHESTRATION_WS_METHODS.subscribeShell]({
+                    requestCompletionMarker: true,
+                  }).pipe(
+                    Stream.takeUntil((item) => item.kind === "synchronized"),
+                    Stream.runCollect,
+                  ),
+                ),
+              );
+
+        assert.equal(items[0]?.kind, "snapshot");
+        const update = items[1];
+        if (subscription === "thread") {
+          assertTrue(update?.kind === "event" && update.event.type === "thread.activity-appended");
+          assert.equal(update.event.sequence, 2);
+          assert.deepEqual(update.event.payload.activity.payload, {
+            itemType: "command_execution",
+            toolCallId: "call-build",
+            status: "completed",
+            title: "Build complete",
+            data: { item: { command: "build", aggregatedOutput: "Build complete" } },
+          });
+        } else {
+          assertTrue(update?.kind === "thread-upserted");
+          assert.equal(update.sequence, 2);
+          assert.equal(update.thread.id, eventThreadId);
+          assert.equal(update.thread.title, "Build complete");
+        }
+        assert.deepEqual(items[2], { kind: "synchronized" });
+      }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+    );
+  }
+
   it.effect("coalesces buffered live tool updates to the latest state", () =>
     Effect.gen(function* () {
       const thread = makeDefaultOrchestrationReadModel().threads[0]!;
@@ -7816,50 +8538,329 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest), TestClock.withLive),
   );
 
-  it.effect("subscribeThread sends a fresh snapshot instead of replaying a large gap", () =>
-    Effect.gen(function* () {
-      let readEventsCalls = 0;
-      const thread = makeDefaultOrchestrationReadModel().threads[0]!;
+  it.effect(
+    "subscribeThread sends a fresh snapshot when its event count exceeds the replay limit",
+    () =>
+      Effect.gen(function* () {
+        let readEventsCalls = 0;
+        const thread = makeDefaultOrchestrationReadModel().threads[0]!;
+
+        yield* buildAppUnderTest({
+          layers: {
+            orchestrationEngine: {
+              latestSequence: Effect.succeed(100_000),
+              getThreadReplayStats: () =>
+                Effect.succeed({
+                  eventCount: 1_001,
+                  payloadBytes: 1_000,
+                  hasCreateEvent: false,
+                }),
+              readThreadEvents: () =>
+                Stream.sync(() => {
+                  readEventsCalls += 1;
+                  return {} as OrchestrationEvent;
+                }),
+            },
+            projectionSnapshotQuery: {
+              getThreadDetailSnapshot: () =>
+                Effect.succeed(Option.some({ snapshotSequence: 100_000, thread })),
+            },
+          },
+        });
+
+        const wsUrl = yield* getWsServerUrl("/ws");
+        const items = yield* Effect.scoped(
+          withWsRpcClient(wsUrl, (client) =>
+            client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+              threadId: defaultThreadId,
+              afterSequence: 5,
+              requestCompletionMarker: true,
+            }).pipe(Stream.take(2), Stream.runCollect),
+          ),
+        );
+
+        const [first, second] = Array.from(items);
+        // Never truncate a thread's replay at the event limit.
+        assert.equal(first?.kind, "snapshot");
+        if (first?.kind === "snapshot") {
+          assert.equal(first.snapshot.thread.id, defaultThreadId);
+          assert.equal(first.snapshot.snapshotSequence, 100_000);
+        }
+        assert.equal(second?.kind, "synchronized");
+        assert.equal(readEventsCalls, 0);
+      }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect(
+    "stops an overflowing thread producer without an ACK and replays the missing events",
+    () =>
+      Effect.gen(function* () {
+        const liveEvents = yield* PubSub.unbounded<OrchestrationEvent>();
+        const attached = yield* Deferred.make<void>();
+        const detached = yield* Deferred.make<void>();
+        const ackHeld = yield* Deferred.make<void>();
+        const releaseAck = yield* Deferred.make<void>();
+        const firstApplied = yield* Deferred.make<void>();
+        const replayStarted = yield* Deferred.make<void>();
+        const replayCalls: Array<{ afterSequence: number; headSequence: number }> = [];
+        let headSequence = 0;
+        let snapshotCalls = 0;
+        const message = (sequence: number, text: string) =>
+          ({
+            sequence,
+            eventId: EventId.make(`slow-thread-${sequence}`),
+            aggregateKind: "thread",
+            aggregateId: defaultThreadId,
+            occurredAt: "2026-01-01T00:00:01.000Z",
+            commandId: null,
+            causationEventId: null,
+            correlationId: null,
+            metadata: {},
+            type: "thread.message-sent",
+            payload: {
+              threadId: defaultThreadId,
+              messageId: MessageId.make(`slow-message-${sequence}`),
+              role: "assistant",
+              text,
+              turnId: TurnId.make("turn-edit"),
+              streaming: false,
+              createdAt: "2026-01-01T00:00:01.000Z",
+              updatedAt: "2026-01-01T00:00:01.000Z",
+            },
+          }) satisfies OrchestrationEvent;
+        const events = [
+          message(1, "a".repeat(4 * 1024 * 1024)),
+          message(2, "b".repeat(4 * 1024 * 1024)),
+          makeLiveToolActivityEvent(3, "tool.completed"),
+          message(4, "Finished"),
+        ] as const;
+
+        yield* buildAppUnderTest({
+          layers: {
+            orchestrationEngine: {
+              latestSequence: Effect.sync(() => headSequence),
+              streamDomainEvents: Stream.unwrap(
+                Effect.gen(function* () {
+                  const subscription = yield* PubSub.subscribe(liveEvents);
+                  yield* Deferred.succeed(attached, undefined);
+                  return Stream.fromSubscription(subscription);
+                }),
+              ).pipe(Stream.ensuring(Deferred.succeed(detached, undefined))),
+              readThreadEvents: ({ fromSequenceExclusive, toSequenceInclusive }) => {
+                replayCalls.push({
+                  afterSequence: fromSequenceExclusive,
+                  headSequence: toSequenceInclusive,
+                });
+                const range = events.filter(
+                  (event) =>
+                    event.sequence > fromSequenceExclusive && event.sequence <= toSequenceInclusive,
+                );
+                return Stream.concat(
+                  Stream.fromEffect(Deferred.succeed(replayStarted, undefined)).pipe(Stream.drain),
+                  Stream.fromIterable(range),
+                );
+              },
+              getThreadReplayStats: ({ fromSequenceExclusive, toSequenceInclusive }) => {
+                const range = events.filter(
+                  (event) =>
+                    event.sequence > fromSequenceExclusive && event.sequence <= toSequenceInclusive,
+                );
+                return Effect.succeed({
+                  eventCount: range.length,
+                  payloadBytes: range.reduce(
+                    (bytes, event) => bytes + Buffer.byteLength(jsonRequestBody(event.payload)),
+                    0,
+                  ),
+                  hasCreateEvent: false,
+                });
+              },
+            },
+            projectionSnapshotQuery: {
+              getThreadDetailSnapshot: () =>
+                Effect.sync(() => {
+                  snapshotCalls += 1;
+                  return Option.none();
+                }),
+            },
+          },
+        });
+
+        const wsUrl = yield* getWsServerUrl("/ws");
+        yield* makeWsRpcClient.pipe(
+          Effect.flatMap((client) =>
+            Effect.gen(function* () {
+              let cursor = 0;
+              const received: number[] = [];
+              const attempt = yield* client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+                threadId: defaultThreadId,
+                afterSequence: cursor,
+              }).pipe(
+                Stream.tap((item) => {
+                  if (item.kind !== "event") return Effect.void;
+                  cursor = item.event.sequence;
+                  received.push(cursor);
+                  return Deferred.succeed(firstApplied, undefined);
+                }),
+                Stream.runDrain,
+                Effect.result,
+                Effect.forkScoped,
+              );
+              yield* Deferred.await(attached);
+              yield* Deferred.await(replayStarted);
+              headSequence = 1;
+              yield* PubSub.publish(liveEvents, events[0]!);
+              yield* Deferred.await(ackHeld);
+              yield* Deferred.await(firstApplied);
+              headSequence = 4;
+              yield* PubSub.publishAll(liveEvents, events.slice(1));
+
+              // This must finish while the server is still waiting for the first
+              // batch's ACK. A failed output queue alone would leave PubSub live.
+              yield* Deferred.await(detached);
+              assert.equal(yield* PubSub.size(liveEvents), 0);
+              assert.deepEqual(received, [1]);
+              yield* Deferred.succeed(releaseAck, undefined);
+              const result = yield* Fiber.join(attempt);
+              assertTrue(result._tag === "Failure");
+              assert.equal(result.failure._tag, "OrchestrationGetSnapshotError");
+
+              const recovered = yield* client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+                threadId: defaultThreadId,
+                afterSequence: cursor,
+                requestCompletionMarker: true,
+              }).pipe(
+                Stream.takeUntil((item) => item.kind === "synchronized"),
+                Stream.runCollect,
+              );
+              assert.deepEqual(
+                recovered.map((item) => (item.kind === "event" ? item.event.sequence : item.kind)),
+                [2, 3, 4, "synchronized"],
+              );
+              const first = recovered[0];
+              assertTrue(first?.kind === "event" && first.event.type === "thread.message-sent");
+              assert.equal(first.event.payload.text, events[1]!.payload.text);
+              const completed = recovered[1];
+              assertTrue(
+                completed?.kind === "event" && completed.event.type === "thread.activity-appended",
+              );
+              assert.equal(completed.event.payload.activity.kind, "tool.completed");
+              assert.deepEqual(replayCalls, [
+                { afterSequence: 0, headSequence: 0 },
+                { afterSequence: 1, headSequence: 4 },
+              ]);
+              assert.equal(snapshotCalls, 0);
+            }),
+          ),
+          Effect.provide(withFirstWsAckHeld(wsUrl, ackHeld, releaseAck)),
+        );
+      }).pipe(Effect.scoped, Effect.provide(NodeHttpServer.layerTest)),
+  );
 
+  it.effect("stops an overflowing shell producer without an ACK and recovers deleted entries", () =>
+    Effect.gen(function* () {
+      const liveEvents = yield* PubSub.unbounded<OrchestrationEvent>();
+      const detached = yield* Deferred.make<void>();
+      const ackHeld = yield* Deferred.make<void>();
+      const releaseAck = yield* Deferred.make<void>();
+      let headSequence = 1;
+      let snapshotCalls = 0;
+      let replayCalls = 0;
+      const thread = makeDefaultOrchestrationThreadShell();
+      const project = makeDefaultOrchestrationReadModel().projects[0]!;
+      const events: OrchestrationEvent[] = Array.from({ length: 1_001 }, (_, index) =>
+        makeLiveToolActivityEvent(index + 2, "tool.completed"),
+      );
+      events.push(
+        {
+          ...events[0]!,
+          sequence: 1_003,
+          type: "thread.archived",
+          payload: {
+            threadId: defaultThreadId,
+            archivedAt: "2026-01-01T00:00:02.000Z",
+            updatedAt: "2026-01-01T00:00:02.000Z",
+          },
+        },
+        {
+          ...events[0]!,
+          sequence: 1_004,
+          aggregateKind: "project",
+          aggregateId: defaultProjectId,
+          type: "project.deleted",
+          payload: { projectId: defaultProjectId, deletedAt: "2026-01-01T00:00:02.000Z" },
+        },
+      );
       yield* buildAppUnderTest({
         layers: {
           orchestrationEngine: {
-            // Head is far ahead of the client's afterSequence (gap > 1000).
-            latestSequence: Effect.succeed(100_000),
-            readEvents: () =>
-              Stream.sync(() => {
-                readEventsCalls += 1;
-                return {} as OrchestrationEvent;
-              }),
+            latestSequence: Effect.sync(() => headSequence),
+            streamDomainEvents: Stream.fromPubSub(liveEvents).pipe(
+              Stream.ensuring(Deferred.succeed(detached, undefined)),
+            ),
+            readEvents: () => {
+              replayCalls += 1;
+              return Stream.empty;
+            },
           },
           projectionSnapshotQuery: {
-            getThreadDetailSnapshot: () =>
-              Effect.succeed(Option.some({ snapshotSequence: 100_000, thread })),
+            getShellSnapshot: () =>
+              Effect.sync(() => {
+                snapshotCalls += 1;
+                return {
+                  snapshotSequence: headSequence,
+                  projects: headSequence === 1 ? [project] : [],
+                  threads: headSequence === 1 ? [thread] : [],
+                  updatedAt: "2026-01-01T00:00:02.000Z",
+                };
+              }),
           },
         },
       });
-
       const wsUrl = yield* getWsServerUrl("/ws");
-      const items = yield* Effect.scoped(
-        withWsRpcClient(wsUrl, (client) =>
-          client[ORCHESTRATION_WS_METHODS.subscribeThread]({
-            threadId: defaultThreadId,
-            afterSequence: 5,
-            requestCompletionMarker: true,
-          }).pipe(Stream.take(2), Stream.runCollect),
+      yield* makeWsRpcClient.pipe(
+        Effect.flatMap((client) =>
+          Effect.gen(function* () {
+            const received: OrchestrationShellStreamItem[] = [];
+            const attempt = yield* client[ORCHESTRATION_WS_METHODS.subscribeShell]({}).pipe(
+              Stream.tap((item) => Effect.sync(() => received.push(item))),
+              Stream.runDrain,
+              Effect.result,
+              Effect.forkScoped,
+            );
+            yield* Deferred.await(ackHeld);
+            headSequence = 1_004;
+            yield* PubSub.publishAll(liveEvents, events);
+            yield* Deferred.await(detached);
+            assert.equal(yield* PubSub.size(liveEvents), 0);
+            yield* Deferred.succeed(releaseAck, undefined);
+            const result = yield* Fiber.join(attempt);
+            assertTrue(result._tag === "Failure");
+            assert.equal(result.failure._tag, "OrchestrationGetSnapshotError");
+            assert.equal(received.length, 1);
+            const initial = received[0];
+            assertTrue(initial?.kind === "snapshot");
+            assert.equal(initial.snapshot.threads.length, 1);
+
+            const recovered = yield* client[ORCHESTRATION_WS_METHODS.subscribeShell]({
+              afterSequence: initial.snapshot.snapshotSequence,
+              requestCompletionMarker: true,
+            }).pipe(
+              Stream.takeUntil((item) => item.kind === "synchronized"),
+              Stream.runCollect,
+            );
+            const snapshot = recovered[0];
+            assertTrue(snapshot?.kind === "snapshot");
+            assert.equal(snapshot.snapshot.snapshotSequence, 1_004);
+            assert.deepEqual(snapshot.snapshot.projects, []);
+            assert.deepEqual(snapshot.snapshot.threads, []);
+            assert.deepEqual(recovered[1], { kind: "synchronized" });
+            assert.equal(snapshotCalls, 2);
+            assert.equal(replayCalls, 0);
+          }),
         ),
+        Effect.provide(withFirstWsAckHeld(wsUrl, ackHeld, releaseAck)),
       );
-
-      const [first, second] = Array.from(items);
-      // Large gap => fresh thread snapshot, and the global replay never starts.
-      assert.equal(first?.kind, "snapshot");
-      if (first?.kind === "snapshot") {
-        assert.equal(first.snapshot.thread.id, defaultThreadId);
-        assert.equal(first.snapshot.snapshotSequence, 100_000);
-      }
-      assert.equal(second?.kind, "synchronized");
-      assert.equal(readEventsCalls, 0);
-    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+    }).pipe(Effect.scoped, Effect.provide(NodeHttpServer.layerTest)),
   );
 
   it.effect("subscribeThread replaces a cursor ahead of the authoritative head", () =>
@@ -7871,7 +8872,9 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         layers: {
           orchestrationEngine: {
             latestSequence: Effect.succeed(5),
-            readEvents: () =>
+            getThreadReplayStats: () =>
+              Effect.die("An invalid cursor must not start a replay query"),
+            readThreadEvents: () =>
               Stream.sync(() => {
                 readEventsCalls += 1;
                 return {} as OrchestrationEvent;
@@ -7899,9 +8902,225 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("subscribeThread replays a small thread range across a large global gap", () =>
+    Effect.gen(function* () {
+      const event = makeLiveToolActivityEvent(99_999, "tool.completed");
+      yield* buildAppUnderTest({
+        layers: {
+          orchestrationEngine: {
+            latestSequence: Effect.succeed(100_000),
+            getThreadReplayStats: () =>
+              Effect.succeed({
+                eventCount: 1,
+                payloadBytes: Buffer.byteLength(jsonRequestBody(event.payload)),
+                hasCreateEvent: false,
+              }),
+            readThreadEvents: () => Stream.make(event),
+            readEvents: () => Stream.die("Thread replay must not read the global log"),
+          },
+          projectionSnapshotQuery: {
+            getEventReplayStats: () => Effect.die("Thread replay must not measure the global log"),
+            getThreadDetailSnapshot: () =>
+              Effect.die("Unrelated activity must not force a snapshot"),
+          },
+        },
+      });
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const items = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+            threadId: defaultThreadId,
+            afterSequence: 5,
+            requestCompletionMarker: true,
+          }).pipe(
+            Stream.takeUntil((item) => item.kind === "synchronized"),
+            Stream.runCollect,
+          ),
+        ),
+      );
+      assert.deepEqual(
+        items.map((item) => (item.kind === "event" ? item.event.sequence : item.kind)),
+        [99_999, "synchronized"],
+      );
+      const first = items[0];
+      assertTrue(first?.kind === "event" && first.event.type === "thread.activity-appended");
+      assert.equal(first.event.payload.activity.kind, "tool.completed");
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("subscribeThread resets cached history when its ID is created again", () =>
+    Effect.gen(function* () {
+      const thread = {
+        ...makeDefaultOrchestrationReadModel().threads[0]!,
+        title: "Recreated thread",
+      };
+      let requestedTurnLimit: number | undefined;
+      yield* buildAppUnderTest({
+        layers: {
+          orchestrationEngine: {
+            latestSequence: Effect.succeed(5),
+            getThreadReplayStats: () =>
+              Effect.succeed({
+                eventCount: 3,
+                payloadBytes: 1_000,
+                hasCreateEvent: true,
+              }),
+            readThreadEvents: () => Stream.die("A recreated thread must not reuse cached history"),
+          },
+          projectionSnapshotQuery: {
+            getThreadDetailSnapshot: (_threadId, options) => {
+              requestedTurnLimit = options?.turnLimit;
+              return Effect.succeed(Option.some({ snapshotSequence: 5, thread }));
+            },
+          },
+        },
+      });
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const items = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+            threadId: defaultThreadId,
+            afterSequence: 2,
+            turnLimit: 1,
+            requestCompletionMarker: true,
+          }).pipe(
+            Stream.takeUntil((item) => item.kind === "synchronized"),
+            Stream.runCollect,
+          ),
+        ),
+      );
+      const first = items[0];
+      assertTrue(first?.kind === "snapshot");
+      assert.equal(first.snapshot.thread.title, "Recreated thread");
+      assert.equal(first.snapshot.snapshotSequence, 5);
+      assert.equal(requestedTurnLimit, 1);
+      assert.deepEqual(items[1], { kind: "synchronized" });
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  for (const { createBeforeDelete, oversized } of [
+    { createBeforeDelete: false, oversized: false },
+    { createBeforeDelete: true, oversized: false },
+    { createBeforeDelete: true, oversized: true },
+  ]) {
+    it.effect(
+      oversized
+        ? "keeps the missing-snapshot error when an absent thread exceeds the replay limit"
+        : `synchronizes an absent thread and removes its shell after ${createBeforeDelete ? "creation and deletion" : "deletion"}`,
+      () =>
+        Effect.gen(function* () {
+          const store = yield* OrchestrationEventStore;
+          const base = makeLiveToolActivityEvent(0, "tool.completed");
+          if (createBeforeDelete) {
+            const thread = makeDefaultOrchestrationReadModel().threads[0]!;
+            yield* store.append({
+              ...base,
+              eventId: EventId.make(`create-before-final-delete-${oversized}`),
+              type: "thread.created",
+              payload: {
+                threadId: defaultThreadId,
+                projectId: thread.projectId,
+                title: thread.title,
+                modelSelection: thread.modelSelection,
+                runtimeMode: thread.runtimeMode,
+                interactionMode: thread.interactionMode,
+                branch: thread.branch,
+                worktreePath: thread.worktreePath,
+                createdAt: thread.createdAt,
+                updatedAt: thread.updatedAt,
+              },
+            });
+          }
+          if (oversized) {
+            yield* Effect.forEach(
+              Array.from({ length: 1_000 }, (_, index) => index + 1),
+              (sequence) => store.append(makeLiveToolActivityEvent(sequence, "tool.completed")),
+              { discard: true },
+            );
+          }
+          const deleted = yield* store.append({
+            ...base,
+            eventId: EventId.make(`deleted-replay-${createBeforeDelete}-${oversized}`),
+            type: "thread.deleted",
+            payload: { threadId: defaultThreadId, deletedAt: base.occurredAt },
+          });
+          yield* buildAppUnderTest({
+            layers: {
+              orchestrationEngine: {
+                latestSequence: Effect.succeed(deleted.sequence),
+                getThreadReplayStats: ({ threadId, ...range }) =>
+                  store.getAggregateReplayStats({
+                    ...range,
+                    aggregateKind: "thread",
+                    aggregateId: threadId,
+                  }),
+                readThreadEvents: ({ threadId, ...range }) =>
+                  store.readAggregateRange({
+                    ...range,
+                    aggregateKind: "thread",
+                    aggregateId: threadId,
+                  }),
+                readEvents: store.readFromSequence,
+              },
+              projectionSnapshotQuery: {
+                getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
+              },
+            },
+          });
+          const wsUrl = yield* getWsServerUrl("/ws");
+          yield* Effect.scoped(
+            withWsRpcClient(wsUrl, (client) =>
+              Effect.gen(function* () {
+                const threadResult = yield* client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+                  threadId: defaultThreadId,
+                  afterSequence: 0,
+                  requestCompletionMarker: true,
+                }).pipe(
+                  Stream.takeUntil((item) => item.kind === "synchronized"),
+                  Stream.runCollect,
+                  Effect.result,
+                );
+                if (oversized) {
+                  assertTrue(threadResult._tag === "Failure");
+                  assert.equal(threadResult.failure._tag, "OrchestrationGetSnapshotError");
+                  assert.equal(
+                    threadResult.failure.message,
+                    `Thread ${defaultThreadId} was not found`,
+                  );
+                  return;
+                }
+                assertTrue(threadResult._tag === "Success");
+                assert.deepEqual(threadResult.success, [{ kind: "synchronized" }]);
+                const shellItems = yield* client[ORCHESTRATION_WS_METHODS.subscribeShell]({
+                  afterSequence: 0,
+                  requestCompletionMarker: true,
+                }).pipe(
+                  Stream.takeUntil((item) => item.kind === "synchronized"),
+                  Stream.runCollect,
+                );
+                assert.deepEqual(shellItems, [
+                  { kind: "thread-removed", sequence: deleted.sequence, threadId: defaultThreadId },
+                  { kind: "synchronized" },
+                ]);
+              }),
+            ),
+          );
+        }).pipe(
+          Effect.provide(
+            Layer.mergeAll(
+              OrchestrationEventStoreLive.pipe(Layer.provideMerge(SqlitePersistenceMemory)),
+              NodeHttpServer.layerTest,
+            ),
+          ),
+        ),
+    );
+  }
+
   it.effect("subscribeThread bounds catch-up replay to the captured head", () =>
     Effect.gen(function* () {
-      let replayLimit: number | undefined;
+      let replayHead: number | undefined;
+      let headSequence = 50;
+      const liveEvents = yield* PubSub.unbounded<OrchestrationEvent>();
       const now = "2026-01-01T00:00:00.000Z";
       const messageEvent = {
         sequence: 3,
@@ -7929,10 +9148,26 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       yield* buildAppUnderTest({
         layers: {
           orchestrationEngine: {
-            latestSequence: Effect.succeed(50),
-            readEvents: (_afterSequence, limit) => {
-              replayLimit = limit;
-              return Stream.make(messageEvent);
+            latestSequence: Effect.sync(() => headSequence),
+            streamDomainEvents: Stream.fromPubSub(liveEvents),
+            getThreadReplayStats: () =>
+              Effect.sync(() => {
+                headSequence = 100;
+                return { eventCount: 1, payloadBytes: 100, hasCreateEvent: false };
+              }),
+            readThreadEvents: ({ toSequenceInclusive }) => {
+              replayHead = toSequenceInclusive;
+              return Stream.fromEffect(
+                PubSub.publish(liveEvents, {
+                  ...messageEvent,
+                  sequence: 51,
+                  eventId: EventId.make("event-live-after-head"),
+                  payload: {
+                    ...messageEvent.payload,
+                    messageId: MessageId.make("message-live-after-head"),
+                  },
+                }),
+              ).pipe(Stream.flatMap(() => Stream.make(messageEvent)));
             },
           },
         },
@@ -7945,17 +9180,18 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             threadId: defaultThreadId,
             afterSequence: 0,
             requestCompletionMarker: true,
-          }).pipe(Stream.take(2), Stream.runCollect),
+          }).pipe(
+            Stream.takeUntil((item) => item.kind === "synchronized"),
+            Stream.runCollect,
+          ),
         ),
       );
 
-      const [first, second] = Array.from(items);
-      assert.equal(first?.kind, "event");
-      assert.equal(first?.kind === "event" ? first.event.sequence : null, 3);
-      assert.equal(second?.kind, "synchronized");
-      // The replay is bounded to the head captured before the read, not
-      // Number.MAX_SAFE_INTEGER.
-      assert.equal(replayLimit, 50);
+      assert.deepEqual(
+        items.map((item) => (item.kind === "event" ? item.event.sequence : item.kind)),
+        [3, 51, "synchronized"],
+      );
+      assert.equal(replayHead, 50);
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
@@ -8032,6 +9268,19 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         layers: {
           orchestrationEngine: {
             latestSequence: Effect.succeed(5),
+            getThreadReplayStats: () =>
+              Effect.sync(() => {
+                replayStatsCalls += 1;
+                return {
+                  eventCount: 5,
+                  payloadBytes: 8 * 1024 * 1024 + 1,
+                  hasCreateEvent: false,
+                };
+              }),
+            readThreadEvents: () => {
+              readEventsCalls += 1;
+              return Stream.empty;
+            },
             readEvents: () =>
               Stream.sync(() => {
                 readEventsCalls += 1;
diff --git a/apps/server/src/serverRuntimeStartup.reconcile.test.ts b/apps/server/src/serverRuntimeStartup.reconcile.test.ts
index 9374560c4e9b..e46c2a8ca010 100644
--- a/apps/server/src/serverRuntimeStartup.reconcile.test.ts
+++ b/apps/server/src/serverRuntimeStartup.reconcile.test.ts
@@ -1,6 +1,7 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import {
   type OrchestrationCommand,
+  type OrchestrationSessionStatus,
   ProviderDriverKind,
   ProviderInstanceId,
   type ProviderSendTurnInput,
@@ -10,15 +11,21 @@ import {
 import { assert, it } from "@effect/vitest";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Stream from "effect/Stream";
 
 import { OrchestrationCommandInvariantError } from "./orchestration/Errors.ts";
 import * as OrchestrationEngine from "./orchestration/Services/OrchestrationEngine.ts";
 import * as ProjectionSnapshotQuery from "./orchestration/Services/ProjectionSnapshotQuery.ts";
-import { ProviderSessionDirectoryPersistenceError } from "./provider/Errors.ts";
+import {
+  ProviderSessionDirectoryPersistenceError,
+  ProviderSessionNotFoundError,
+} from "./provider/Errors.ts";
 import * as ProviderService from "./provider/Services/ProviderService.ts";
 import * as ProviderSessionDirectory from "./provider/Services/ProviderSessionDirectory.ts";
+import { ServerActivation } from "./serverActivation.ts";
+import * as ServerSettings from "./serverSettings.ts";
 import * as ServerRuntimeStartup from "./serverRuntimeStartup.ts";
 
 const providerInstanceId = ProviderInstanceId.make("codex");
@@ -26,7 +33,7 @@ const updatedAt = "2026-08-20T12:00:00.000Z";
 
 const makeThread = (
   id: string,
-  status: "starting" | "running" | "ready" | "stopped" | "error",
+  status: OrchestrationSessionStatus,
   activeTurnId: TurnId | null = null,
   archivedAt: string | null = null,
   deletedAt: string | null = null,
@@ -73,6 +80,7 @@ const queryWithThreads = (threads: ReadonlyArray<ReturnType<typeof makeThread>>)
 
 const runReconciliation = (input: {
   readonly threads: ReadonlyArray<ReturnType<typeof makeThread>>;
+  readonly continueAfterRestart?: boolean;
   readonly liveThreadIds?: ReadonlyArray<ThreadId>;
   readonly providerService?: ProviderService.ProviderService["Service"];
   readonly directory: ProviderSessionDirectory.ProviderSessionDirectory["Service"];
@@ -90,12 +98,21 @@ const runReconciliation = (input: {
     Effect.provideService(ProviderSessionDirectory.ProviderSessionDirectory, input.directory),
     Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
       readEvents: () => Stream.empty,
+      readThreadEvents: () => Stream.empty,
+      getThreadReplayStats: () => Effect.die("unused thread replay stats"),
       dispatch: input.dispatch,
       streamDomainEvents: Stream.empty,
       subscribeDomainEvents: Effect.succeed(Stream.empty),
       latestSequence: Effect.succeed(0),
     }),
-    Effect.provide(NodeServices.layer),
+    Effect.provide(
+      Layer.mergeAll(
+        ServerSettings.layerTest({
+          continueThreadsAfterServerUpdate: input.continueAfterRestart ?? false,
+        }),
+        NodeServices.layer,
+      ),
+    ),
   );
 
 it.effect("marks active running sessions that have persisted resume state", () => {
@@ -134,9 +151,10 @@ it.effect("marks active running sessions that have persisted resume state", () =
           ),
         ),
       upsert: (binding) => Effect.sync(() => upserts.push(binding)),
+      recordImportedTranscript: () => Effect.die("unused"),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     }),
     Effect.tap((marked) =>
       Effect.sync(() => {
@@ -145,169 +163,187 @@ it.effect("marks active running sessions that have persisted resume state", () =
         assert.deepStrictEqual(upserts[0]?.runtimePayload, {
           activeTurnId: "turn-mark-active",
           continueAfterServerUpdate: active.session.activeTurnId,
+          continueAfterServerUpdatePrepared: null,
         });
       }),
     ),
   );
 });
 
-it.effect("continues marked sessions after activation with provider-specific input", () =>
-  Effect.gen(function* () {
-    const codex = makeThread(
-      "thread-continue-codex",
-      "running",
-      TurnId.make("turn-continue-codex"),
-    );
-    const fallback = makeThread("thread-continue-fallback", "starting");
-    const fallbackContinuationTurnId = TurnId.make("turn-continue-fallback");
-    const fallbackProviderInstanceId = ProviderInstanceId.make("claudeAgent");
-    const continuationSent = yield* Deferred.make<void>();
-    const continuationCleared = yield* Deferred.make<void>();
-    const sends: ProviderSendTurnInput[] = [];
-    const dispatched: OrchestrationCommand[] = [];
-    const upserts: ProviderSessionDirectory.ProviderRuntimeBinding[] = [];
-    const bindings = new Map<ThreadId, ProviderSessionDirectory.ProviderRuntimeBinding>(
-      [codex, fallback].map((thread) => [
-        thread.id,
-        {
-          threadId: thread.id,
-          provider:
-            thread.id === codex.id
-              ? ProviderDriverKind.make("codex")
-              : ProviderDriverKind.make("claudeAgent"),
-          providerInstanceId:
-            thread.id === codex.id ? providerInstanceId : fallbackProviderInstanceId,
-          status: "running" as const,
-          runtimePayload: {
-            continueAfterServerUpdate:
-              thread.id === codex.id ? codex.session.activeTurnId : fallbackContinuationTurnId,
+it.effect.each(["marked update", "opt-in restart"] as const)(
+  "continues %s sessions after activation with provider-specific input",
+  (recovery) =>
+    Effect.gen(function* () {
+      const codex = makeThread(
+        "thread-continue-codex",
+        "running",
+        TurnId.make("turn-continue-codex"),
+      );
+      const fallbackContinuationTurnId = TurnId.make("turn-continue-fallback");
+      const fallback = makeThread(
+        "thread-continue-fallback",
+        recovery === "marked update" ? "starting" : "running",
+        recovery === "marked update" ? null : fallbackContinuationTurnId,
+      );
+      const fallbackProviderInstanceId = ProviderInstanceId.make("claudeAgent");
+      const continuationSent = yield* Deferred.make<void>();
+      const continuationCleared = yield* Deferred.make<void>();
+      const sends: ProviderSendTurnInput[] = [];
+      const dispatched: OrchestrationCommand[] = [];
+      const upserts: ProviderSessionDirectory.ProviderRuntimeBinding[] = [];
+      const bindings = new Map<ThreadId, ProviderSessionDirectory.ProviderRuntimeBinding>(
+        [codex, fallback].map((thread) => [
+          thread.id,
+          {
+            threadId: thread.id,
+            provider:
+              thread.id === codex.id
+                ? ProviderDriverKind.make("codex")
+                : ProviderDriverKind.make("claudeAgent"),
+            providerInstanceId:
+              thread.id === codex.id ? providerInstanceId : fallbackProviderInstanceId,
+            status: "running" as const,
+            resumeCursor: { threadId: thread.id },
+            runtimePayload:
+              recovery === "marked update"
+                ? {
+                    continueAfterServerUpdate:
+                      thread.id === codex.id
+                        ? codex.session.activeTurnId
+                        : fallbackContinuationTurnId,
+                  }
+                : { activeTurnId: thread.session.activeTurnId },
           },
-        },
-      ]),
-    );
-    const providerService: ProviderService.ProviderService["Service"] = {
-      ...makeProviderService(),
-      getCapabilities: (instanceId) =>
-        Effect.succeed({
-          sessionModelSwitch: "in-session",
-          ...(instanceId === providerInstanceId ? { promptlessTurnContinuation: true } : {}),
-        }),
-      sendTurn: (input) =>
-        Effect.gen(function* () {
-          sends.push(input);
-          if (sends.length === 2) {
-            yield* Deferred.succeed(continuationSent, undefined);
-          }
-          return {
-            threadId: input.threadId,
-            turnId: TurnId.make(`continued-${String(input.threadId)}`),
-          };
-        }),
-    };
-
-    yield* runReconciliation({
-      threads: [codex, fallback],
-      providerService,
-      directory: {
-        getBinding: (threadId) =>
-          Effect.sync(() => {
-            const binding = bindings.get(threadId);
-            return binding === undefined ? Option.none() : Option.some(binding);
+        ]),
+      );
+      const providerService: ProviderService.ProviderService["Service"] = {
+        ...makeProviderService(),
+        getCapabilities: (instanceId) =>
+          Effect.succeed({
+            sessionModelSwitch: "in-session",
+            ...(instanceId === providerInstanceId ? { promptlessTurnContinuation: true } : {}),
           }),
-        upsert: (binding) =>
-          Effect.sync(() => {
-            bindings.set(binding.threadId, binding);
-            upserts.push(binding);
-            const clearedCount = upserts.filter((candidate) => {
-              const payload = candidate.runtimePayload;
-              return (
-                payload !== null &&
-                typeof payload === "object" &&
-                !Array.isArray(payload) &&
-                "continueAfterServerUpdate" in payload &&
-                payload.continueAfterServerUpdate === null
-              );
-            }).length;
-            return clearedCount === 1;
-          }).pipe(
-            Effect.flatMap((firstMarkerCleared) =>
-              firstMarkerCleared ? Deferred.succeed(continuationCleared, undefined) : Effect.void,
+        sendTurn: (input) =>
+          Effect.gen(function* () {
+            sends.push(input);
+            if (sends.length === 2) {
+              yield* Deferred.succeed(continuationSent, undefined);
+            }
+            return {
+              threadId: input.threadId,
+              turnId: TurnId.make(`continued-${String(input.threadId)}`),
+            };
+          }),
+      };
+
+      yield* runReconciliation({
+        threads: [codex, fallback],
+        continueAfterRestart: recovery === "opt-in restart",
+        providerService,
+        directory: {
+          getBinding: (threadId) =>
+            Effect.sync(() => {
+              const binding = bindings.get(threadId);
+              return binding === undefined ? Option.none() : Option.some(binding);
+            }),
+          upsert: (binding) =>
+            Effect.sync(() => {
+              bindings.set(binding.threadId, binding);
+              upserts.push(binding);
+              const clearedCount = upserts.filter((candidate) => {
+                const payload = candidate.runtimePayload;
+                return (
+                  payload !== null &&
+                  typeof payload === "object" &&
+                  !Array.isArray(payload) &&
+                  "continueAfterServerUpdate" in payload &&
+                  payload.continueAfterServerUpdate === null
+                );
+              }).length;
+              return clearedCount === 1;
+            }).pipe(
+              Effect.flatMap((firstMarkerCleared) =>
+                firstMarkerCleared ? Deferred.succeed(continuationCleared, undefined) : Effect.void,
+              ),
             ),
+          recordImportedTranscript: () => Effect.die("unused"),
+          getProvider: () => Effect.die("unused"),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () => Effect.succeed([]),
+        },
+        dispatch: (command) =>
+          Effect.sync(() => dispatched.push(command)).pipe(
+            Effect.as({ sequence: dispatched.length }),
           ),
-        getProvider: () => Effect.die("unused"),
-        listThreadIds: () => Effect.die("unused"),
-        listBindings: () => Effect.die("unused"),
-      },
-      dispatch: (command) =>
-        Effect.sync(() => dispatched.push(command)).pipe(
-          Effect.as({ sequence: dispatched.length }),
-        ),
-    });
-    yield* Deferred.await(continuationSent);
-    yield* Deferred.await(continuationCleared);
+      });
+      yield* Deferred.await(continuationSent);
+      yield* Deferred.await(continuationCleared);
 
-    assert.deepStrictEqual(
-      sends.toSorted((left, right) => String(left.threadId).localeCompare(String(right.threadId))),
-      [
-        { threadId: codex.id, continuation: true, interactionMode: "default" },
-        {
-          threadId: fallback.id,
-          input: "Continue where you left off.",
-          interactionMode: "default",
-        },
-      ],
-    );
-    assert.deepStrictEqual(
-      dispatched.map((command) =>
-        command.type === "thread.session.set"
-          ? {
-              threadId: command.threadId,
-              status: command.session.status,
-              activeTurnId: command.session.activeTurnId,
-            }
-          : null,
-      ),
-      [
-        {
-          threadId: codex.id,
-          status: "starting",
-          activeTurnId: null,
-        },
-        {
-          threadId: fallback.id,
-          status: "starting",
-          activeTurnId: fallback.session.activeTurnId,
-        },
-      ],
-    );
-    for (const [thread, continuationTurnId] of [
-      [codex, codex.session.activeTurnId],
-      [fallback, fallbackContinuationTurnId],
-    ] as const) {
       assert.deepStrictEqual(
-        upserts
-          .filter((binding) => binding.threadId === thread.id)
-          .map((binding) => binding.runtimePayload)[0],
-        {
-          continueAfterServerUpdate: continuationTurnId,
-          activeTurnId: null,
-        },
+        sends.toSorted((left, right) =>
+          String(left.threadId).localeCompare(String(right.threadId)),
+        ),
+        [
+          { threadId: codex.id, continuation: true, interactionMode: "default" },
+          {
+            threadId: fallback.id,
+            input: "Continue where you left off.",
+            interactionMode: "default",
+          },
+        ],
+      );
+      assert.deepStrictEqual(
+        dispatched.map((command) =>
+          command.type === "thread.session.set"
+            ? {
+                threadId: command.threadId,
+                status: command.session.status,
+                activeTurnId: command.session.activeTurnId,
+              }
+            : null,
+        ),
+        [
+          {
+            threadId: codex.id,
+            status: "starting",
+            activeTurnId: null,
+          },
+          {
+            threadId: fallback.id,
+            status: "starting",
+            activeTurnId: null,
+          },
+        ],
       );
-    }
-    assert.equal(
-      upserts.some((binding) => {
-        const payload = binding.runtimePayload;
-        return (
-          payload !== null &&
-          typeof payload === "object" &&
-          !Array.isArray(payload) &&
-          "continueAfterServerUpdate" in payload &&
-          payload.continueAfterServerUpdate === null
+      for (const [thread, continuationTurnId] of [
+        [codex, codex.session.activeTurnId],
+        [fallback, fallbackContinuationTurnId],
+      ] as const) {
+        assert.deepStrictEqual(
+          upserts
+            .filter((binding) => binding.threadId === thread.id)
+            .map((binding) => binding.runtimePayload)[0],
+          {
+            continueAfterServerUpdate: continuationTurnId,
+            continueAfterServerUpdatePrepared: true,
+            activeTurnId: null,
+          },
         );
-      }),
-      true,
-    );
-  }),
+      }
+      assert.equal(
+        upserts.some((binding) => {
+          const payload = binding.runtimePayload;
+          return (
+            payload !== null &&
+            typeof payload === "object" &&
+            !Array.isArray(payload) &&
+            "continueAfterServerUpdate" in payload &&
+            payload.continueAfterServerUpdate === null
+          );
+        }),
+        true,
+      );
+    }),
 );
 
 it.effect("does not continue archived or deleted marked sessions", () => {
@@ -357,9 +393,10 @@ it.effect("does not continue archived or deleted marked sessions", () => {
         );
       },
       upsert: () => Effect.void,
+      recordImportedTranscript: () => Effect.die("unused"),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) =>
       Effect.sync(() => dispatched.push(command)).pipe(Effect.as({ sequence: dispatched.length })),
@@ -412,9 +449,10 @@ it.effect("retries continuation preparation before settling a persistent failure
           }),
         ),
       upsert: () => Effect.void,
+      recordImportedTranscript: () => Effect.die("unused"),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) => {
       if (command.type !== "thread.session.set") {
@@ -483,9 +521,10 @@ it.effect("reconciles multiple active and archived orphans but skips live sessio
           ),
         ),
       upsert: (binding) => Effect.sync(() => upserts.push(binding)),
+      recordImportedTranscript: () => Effect.die("unused"),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) =>
       Effect.sync(() => dispatched.push(command)).pipe(Effect.as({ sequence: dispatched.length })),
@@ -519,6 +558,7 @@ it.effect("reconciles multiple active and archived orphans but skips live sessio
                   activeTurnId: null,
                   unrelated: binding.threadId,
                   continueAfterServerUpdate: null,
+                  continueAfterServerUpdatePrepared: null,
                 }
               : { activeTurnId: null, unrelated: binding.threadId },
           );
@@ -561,9 +601,10 @@ it.effect(
                   }),
                 ),
         upsert: () => Effect.fail(writeFailure),
+        recordImportedTranscript: () => Effect.die("unused"),
         getProvider: () => Effect.die("unused"),
         listThreadIds: () => Effect.die("unused"),
-        listBindings: () => Effect.die("unused"),
+        listBindings: () => Effect.succeed([]),
       },
       dispatch: (command) =>
         Effect.sync(() => dispatched.push(command)).pipe(
@@ -598,9 +639,10 @@ it.effect("retries failed projections and continues after a persistent failure",
     directory: {
       getBinding: () => Effect.succeed(Option.none()),
       upsert: () => Effect.void,
+      recordImportedTranscript: () => Effect.die("unused"),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) => {
       if (command.type !== "thread.session.set") {
@@ -647,18 +689,300 @@ it.effect("does not fail startup when the live provider session inventory cannot
     Effect.provideService(ProviderSessionDirectory.ProviderSessionDirectory, {
       getBinding: () => Effect.die("unused"),
       upsert: () => Effect.die("unused"),
+      recordImportedTranscript: () => Effect.die("unused"),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     }),
     Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
       readEvents: () => Stream.empty,
+      readThreadEvents: () => Stream.empty,
+      getThreadReplayStats: () => Effect.die("unused thread replay stats"),
       dispatch: () => Effect.die("unused"),
       streamDomainEvents: Stream.empty,
       subscribeDomainEvents: Effect.succeed(Stream.empty),
       latestSequence: Effect.succeed(0),
     }),
-    Effect.provide(NodeServices.layer),
+    Effect.provide(Layer.mergeAll(NodeServices.layer, ServerSettings.layerTest())),
     Effect.tap(() => Effect.sync(() => assert.equal(queried, false))),
   );
 });
+
+for (const scenario of [
+  "disabled",
+  "stopped projection",
+  "finished projection",
+  "stopped binding",
+  "finished binding",
+  "missing cursor",
+  "mismatched turn",
+  "marked without cursor",
+  "marked stopped projection",
+  "marked superseded turn",
+] as const) {
+  it.effect(`does not recover an interrupted session with ${scenario}`, () => {
+    const turnId = TurnId.make("turn-excluded-recovery");
+    const thread = makeThread(
+      "thread-excluded-recovery",
+      scenario.includes("stopped projection")
+        ? "stopped"
+        : scenario === "finished projection"
+          ? "ready"
+          : scenario === "marked superseded turn"
+            ? "starting"
+            : "running",
+      scenario === "marked superseded turn" ? null : turnId,
+    );
+    const dispatched: OrchestrationCommand[] = [];
+    const upserts: ProviderSessionDirectory.ProviderRuntimeBinding[] = [];
+    return runReconciliation({
+      threads: [thread],
+      continueAfterRestart: scenario !== "disabled",
+      directory: {
+        getBinding: () =>
+          Effect.succeed(
+            Option.some({
+              threadId: thread.id,
+              provider: ProviderDriverKind.make("codex"),
+              providerInstanceId,
+              status: scenario === "stopped binding" ? "stopped" : "running",
+              ...(scenario.includes("cursor") ? {} : { resumeCursor: { threadId: thread.id } }),
+              runtimePayload: {
+                activeTurnId:
+                  scenario === "finished binding"
+                    ? null
+                    : scenario === "mismatched turn" || scenario === "marked superseded turn"
+                      ? "another-turn"
+                      : turnId,
+                ...(scenario.startsWith("marked") ? { continueAfterServerUpdate: turnId } : {}),
+              },
+            }),
+          ),
+        upsert: (binding) =>
+          Effect.sync(() => {
+            upserts.push(binding);
+          }),
+        recordImportedTranscript: () => Effect.die("unused"),
+        getProvider: () => Effect.die("unused"),
+        listThreadIds: () => Effect.die("unused"),
+        listBindings: () => Effect.succeed([]),
+      },
+      dispatch: (command) =>
+        Effect.sync(() => {
+          dispatched.push(command);
+          return { sequence: dispatched.length };
+        }),
+    }).pipe(
+      Effect.tap(() =>
+        Effect.sync(() => {
+          assert.deepStrictEqual(
+            dispatched.map(
+              (command) => command.type === "thread.session.set" && command.session.status,
+            ),
+            ["error"],
+          );
+          assert.deepStrictEqual(
+            upserts.map((binding) => binding.status),
+            ["stopped"],
+          );
+        }),
+      ),
+    );
+  });
+}
+
+for (const preparedStatus of [
+  "starting",
+  "ready",
+  "ready with failed scan",
+  "completed after update marking",
+] as const) {
+  it.effect(`recovers again if startup exits with a prepared ${preparedStatus} session`, () =>
+    Effect.gen(function* () {
+      const turnId = TurnId.make("turn-interrupted-startup");
+      const thread = makeThread("thread-interrupted-startup", "running", turnId);
+      const activation = yield* Deferred.make<void>();
+      const cleared = yield* Deferred.make<void>();
+      const sends: ProviderSendTurnInput[] = [];
+      let binding: ProviderSessionDirectory.ProviderRuntimeBinding = {
+        threadId: thread.id,
+        provider: ProviderDriverKind.make("codex"),
+        providerInstanceId,
+        status: "running",
+        resumeCursor: { threadId: thread.id },
+        runtimePayload: { activeTurnId: turnId },
+      };
+      const input = {
+        threads: [thread],
+        continueAfterRestart: true,
+        providerService: {
+          ...makeProviderService(),
+          getCapabilities: () =>
+            Effect.succeed({
+              sessionModelSwitch: "in-session" as const,
+              promptlessTurnContinuation: true,
+            }),
+          sendTurn: (input: ProviderSendTurnInput) =>
+            Effect.sync(() => {
+              sends.push(input);
+              return { threadId: input.threadId, turnId: TurnId.make("turn-recovered") };
+            }),
+        },
+        directory: {
+          getBinding: () => Effect.sync(() => Option.some(binding)),
+          upsert: (next: ProviderSessionDirectory.ProviderRuntimeBinding) =>
+            Effect.gen(function* () {
+              binding = next;
+              if (binding.status !== "starting" || sends.length === 0) return;
+              yield* Deferred.succeed(cleared, undefined);
+            }),
+          recordImportedTranscript: () => Effect.die("unused"),
+          getProvider: () => Effect.die("unused"),
+          listThreadIds: () => Effect.die("unused"),
+          listBindings: () =>
+            preparedStatus === "ready with failed scan"
+              ? Effect.fail(
+                  new ProviderSessionDirectoryPersistenceError({
+                    operation: "listBindings",
+                    detail: "unreadable unrelated binding",
+                  }),
+                )
+              : Effect.sync(() => [{ ...binding, lastSeenAt: "2026-01-01T00:00:00.000Z" }]),
+        },
+        dispatch: (command: OrchestrationCommand) =>
+          Effect.sync(() => {
+            if (command.type === "thread.session.set") {
+              thread.session.status = command.session.status;
+              thread.session.activeTurnId = command.session.activeTurnId;
+            }
+            return { sequence: 1 };
+          }),
+      };
+
+      yield* runReconciliation(input).pipe(
+        Effect.provideService(ServerActivation, Deferred.await(activation)),
+        Effect.scoped,
+      );
+      assert.deepStrictEqual(sends, []);
+      assert.equal(thread.session.status, "starting");
+      assert.equal(thread.session.activeTurnId, null);
+      assert.deepStrictEqual(binding.runtimePayload, {
+        activeTurnId: null,
+        continueAfterServerUpdate: turnId,
+        continueAfterServerUpdatePrepared: true,
+      });
+
+      if (preparedStatus === "completed after update marking") {
+        thread.session.status = "ready";
+        binding = {
+          ...binding,
+          status: "stopped",
+          runtimePayload: {
+            activeTurnId: null,
+            continueAfterServerUpdate: turnId,
+            continueAfterServerUpdatePrepared: null,
+          },
+        };
+        yield* runReconciliation(input);
+        assert.deepStrictEqual(sends, []);
+        assert.equal(thread.session.status, "ready");
+        return;
+      }
+      thread.session.status =
+        preparedStatus === "ready with failed scan" ? "ready" : preparedStatus;
+      yield* runReconciliation(input);
+      yield* Deferred.await(cleared);
+      assert.deepStrictEqual(sends, [
+        { threadId: thread.id, continuation: true, interactionMode: "default" },
+      ]);
+      assert.deepStrictEqual(binding.runtimePayload, {
+        activeTurnId: null,
+        continueAfterServerUpdate: null,
+        continueAfterServerUpdatePrepared: null,
+      });
+    }),
+  );
+}
+
+it.effect("settles failed opt-in recovery without retrying the provider turn", () =>
+  Effect.gen(function* () {
+    const turnId = TurnId.make("turn-failed-recovery");
+    const thread = makeThread("thread-failed-recovery", "running", turnId);
+    const settled = yield* Deferred.make<void>();
+    const sends: ProviderSendTurnInput[] = [];
+    const dispatched: OrchestrationCommand[] = [];
+    const preparedPayloads: unknown[] = [];
+    let binding: ProviderSessionDirectory.ProviderRuntimeBinding = {
+      threadId: thread.id,
+      provider: ProviderDriverKind.make("codex"),
+      providerInstanceId,
+      status: "running",
+      resumeCursor: { threadId: thread.id },
+      runtimePayload: { activeTurnId: turnId },
+    };
+    yield* runReconciliation({
+      threads: [thread],
+      continueAfterRestart: true,
+      providerService: {
+        ...makeProviderService(),
+        getCapabilities: () =>
+          Effect.succeed({ sessionModelSwitch: "in-session", promptlessTurnContinuation: true }),
+        sendTurn: (input) =>
+          Effect.gen(function* () {
+            sends.push(input);
+            preparedPayloads.push(binding.runtimePayload);
+            return yield* Effect.fail(
+              new ProviderSessionNotFoundError({ threadId: input.threadId }),
+            );
+          }),
+      },
+      directory: {
+        getBinding: () => Effect.sync(() => Option.some(binding)),
+        upsert: (next) =>
+          Effect.sync(() => {
+            binding = next;
+          }),
+        recordImportedTranscript: () => Effect.die("unused"),
+        getProvider: () => Effect.die("unused"),
+        listThreadIds: () => Effect.die("unused"),
+        listBindings: () => Effect.succeed([]),
+      },
+      dispatch: (command) =>
+        Effect.gen(function* () {
+          dispatched.push(command);
+          if (command.type === "thread.session.set" && command.session.status === "error") {
+            yield* Deferred.succeed(settled, undefined);
+          }
+          return { sequence: dispatched.length };
+        }),
+    });
+    yield* Deferred.await(settled);
+    assert.equal(sends.length, 1);
+    assert.deepStrictEqual(preparedPayloads, [
+      {
+        activeTurnId: null,
+        continueAfterServerUpdate: turnId,
+        continueAfterServerUpdatePrepared: true,
+      },
+    ]);
+    assert.deepStrictEqual(
+      dispatched.map(
+        (command) =>
+          command.type === "thread.session.set" && {
+            status: command.session.status,
+            activeTurnId: command.session.activeTurnId,
+          },
+      ),
+      [
+        { status: "starting", activeTurnId: null },
+        { status: "error", activeTurnId: null },
+      ],
+    );
+    assert.equal(binding.status, "stopped");
+    assert.deepStrictEqual(binding.runtimePayload, {
+      activeTurnId: null,
+      continueAfterServerUpdate: null,
+      continueAfterServerUpdatePrepared: null,
+    });
+  }),
+);
diff --git a/apps/server/src/serverRuntimeStartup.test.ts b/apps/server/src/serverRuntimeStartup.test.ts
index 0a8afde249a4..8cba52552270 100644
--- a/apps/server/src/serverRuntimeStartup.test.ts
+++ b/apps/server/src/serverRuntimeStartup.test.ts
@@ -13,17 +13,9 @@ import * as Stream from "effect/Stream";
 import * as ServerConfig from "./config.ts";
 import * as OrchestrationEngine from "./orchestration/Services/OrchestrationEngine.ts";
 import * as ProjectionSnapshotQuery from "./orchestration/Services/ProjectionSnapshotQuery.ts";
-import * as AnalyticsService from "./telemetry/AnalyticsService.ts";
 import * as ServerRuntimeStartup from "./serverRuntimeStartup.ts";
 import * as GitVcsDriver from "./vcs/GitVcsDriver.ts";
 
-it("uses the canonical Codex default for the auto-bootstrapped welcome thread", () => {
-  assert.deepStrictEqual(ServerRuntimeStartup.getAutoBootstrapThreadModelSelection(), {
-    instanceId: ProviderInstanceId.make("codex"),
-    model: DEFAULT_MODEL,
-  });
-});
-
 it.effect("automatic pull only updates enabled, behind, clean default-branch checkouts", () =>
   Effect.gen(function* () {
     const pulled: string[] = [];
@@ -110,55 +102,6 @@ it.effect("enqueueCommand fails queued work when readiness fails", () =>
   ),
 );
 
-it.effect("launchStartupHeartbeat does not block the caller while counts are loading", () =>
-  Effect.scoped(
-    Effect.gen(function* () {
-      const releaseCounts = yield* Deferred.make<void, never>();
-      const countsStarted = yield* Deferred.make<void, never>();
-
-      yield* ServerRuntimeStartup.launchStartupHeartbeat.pipe(
-        Effect.provideService(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
-          getUserInputActivity: () => Effect.die("unused"),
-          getCommandReadModel: () => Effect.die("unused"),
-          getSnapshot: () => Effect.die("unused"),
-          getShellSnapshot: () => Effect.die("unused"),
-          getArchivedShellSnapshot: () => Effect.die("unused"),
-          getSnapshotSequence: () => Effect.die("unused"),
-          getEventReplayStats: () => Effect.die("unused"),
-          getCounts: () =>
-            Deferred.succeed(countsStarted, undefined).pipe(
-              Effect.andThen(Deferred.await(releaseCounts)),
-              Effect.as({
-                projectCount: 2,
-                threadCount: 3,
-              }),
-            ),
-          getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
-          getProjectShellById: () => Effect.succeed(Option.none()),
-          getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
-          getThreadCheckpointContext: () => Effect.succeed(Option.none()),
-          getFullThreadDiffContext: () => Effect.succeed(Option.none()),
-          getThreadShellById: () => Effect.succeed(Option.none()),
-          getThreadDetailById: () => Effect.succeed(Option.none()),
-          getThreadDetailSnapshot: () => Effect.succeed(Option.none()),
-          searchThreads: () => Effect.succeed({ matches: [] }),
-        }),
-        Effect.provideService(AnalyticsService.AnalyticsService, {
-          record: () => Effect.void,
-          flush: Effect.void,
-        }),
-      );
-
-      // The heartbeat is forked, so the caller is already back here while
-      // getCounts is still parked. Awaiting countsStarted proves the forked
-      // work really ran; releaseCounts staying incomplete proves the caller
-      // never waited for it.
-      yield* Deferred.await(countsStarted);
-      assert.equal(yield* Deferred.isDone(releaseCounts), false);
-    }),
-  ),
-);
-
 it.effect("resolveWelcomeBase derives cwd and project name from server config", () =>
   Effect.gen(function* () {
     const welcome = yield* ServerRuntimeStartup.resolveWelcomeBase.pipe(
@@ -200,7 +143,10 @@ it.effect("resolveAutoBootstrapWelcomeTargets returns existing project and threa
               id: bootstrapProjectId,
               title: "Startup Project",
               workspaceRoot: "/tmp/startup-project",
-              defaultModelSelection: ServerRuntimeStartup.getAutoBootstrapThreadModelSelection(),
+              defaultModelSelection: {
+                instanceId: ProviderInstanceId.make("codex"),
+                model: DEFAULT_MODEL,
+              },
               scripts: [],
               createdAt: "2026-01-01T00:00:00.000Z",
               updatedAt: "2026-01-01T00:00:00.000Z",
@@ -209,8 +155,10 @@ it.effect("resolveAutoBootstrapWelcomeTargets returns existing project and threa
           ),
         getProjectShellById: () => Effect.die("unused"),
         getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.some(bootstrapThreadId)),
+        getImportedAgentSessionSources: () => Effect.die("unused"),
         getThreadCheckpointContext: () => Effect.succeed(Option.none()),
         getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+        getThreadRuntimeContext: () => Effect.die("unused"),
         getThreadShellById: () => Effect.die("unused"),
         getThreadDetailById: () => Effect.die("unused"),
         getThreadDetailSnapshot: () => Effect.die("unused"),
@@ -218,6 +166,8 @@ it.effect("resolveAutoBootstrapWelcomeTargets returns existing project and threa
       }),
       Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
         readEvents: () => Stream.empty,
+        readThreadEvents: () => Stream.empty,
+        getThreadReplayStats: () => Effect.die("unused thread replay stats"),
         dispatch: (command) =>
           Ref.update(dispatchCalls, (calls) => [...calls, command.type]).pipe(
             Effect.as({ sequence: 1 }),
@@ -232,6 +182,8 @@ it.effect("resolveAutoBootstrapWelcomeTargets returns existing project and threa
     assert.deepStrictEqual(targets, {
       bootstrapProjectId,
       bootstrapThreadId,
+      bootstrapProjectCreated: false,
+      bootstrapThreadCreated: false,
     });
     assert.deepStrictEqual(yield* Ref.get(dispatchCalls), []);
   });
@@ -263,8 +215,10 @@ it.effect("resolveAutoBootstrapWelcomeTargets creates a project and thread when
         getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
         getProjectShellById: () => Effect.die("unused"),
         getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+        getImportedAgentSessionSources: () => Effect.die("unused"),
         getThreadCheckpointContext: () => Effect.succeed(Option.none()),
         getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+        getThreadRuntimeContext: () => Effect.die("unused"),
         getThreadShellById: () => Effect.die("unused"),
         getThreadDetailById: () => Effect.die("unused"),
         getThreadDetailSnapshot: () => Effect.die("unused"),
@@ -272,6 +226,8 @@ it.effect("resolveAutoBootstrapWelcomeTargets creates a project and thread when
       }),
       Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
         readEvents: () => Stream.empty,
+        readThreadEvents: () => Stream.empty,
+        getThreadReplayStats: () => Effect.die("unused thread replay stats"),
         dispatch: (command) =>
           Ref.update(dispatchCalls, (calls) => [...calls, command]).pipe(
             Effect.as({ sequence: 1 }),
@@ -285,19 +241,75 @@ it.effect("resolveAutoBootstrapWelcomeTargets creates a project and thread when
 
     assert.equal(typeof targets.bootstrapProjectId, "string");
     assert.equal(typeof targets.bootstrapThreadId, "string");
+    assert.equal(targets.bootstrapProjectCreated, true);
+    assert.equal(targets.bootstrapThreadCreated, true);
     const commands = yield* Ref.get(dispatchCalls);
     assert.deepStrictEqual(
       commands.map((command) => command.type),
       ["project.create", "thread.create"],
     );
     assert.equal("defaultModelSelection" in commands[0]!, false);
-    assert.deepStrictEqual(
-      commands[1]?.modelSelection,
-      ServerRuntimeStartup.getAutoBootstrapThreadModelSelection(),
-    );
+    assert.deepStrictEqual(commands[1]?.modelSelection, {
+      instanceId: ProviderInstanceId.make("codex"),
+      model: DEFAULT_MODEL,
+    });
   }),
 );
 
+it.effect(
+  "resolveAutoBootstrapWelcomeTargets preserves a project created before thread failure",
+  () =>
+    Effect.gen(function* () {
+      const dispatchCalls = yield* Ref.make<ReadonlyArray<string>>([]);
+      const targets = yield* ServerRuntimeStartup.resolveAutoBootstrapWelcomeTargets.pipe(
+        Effect.provideService(ServerConfig.ServerConfig, {
+          cwd: "/tmp/startup-project",
+          autoBootstrapProjectFromCwd: true,
+        } as never),
+        Effect.provideService(ProjectionSnapshotQuery.ProjectionSnapshotQuery, {
+          getUserInputActivity: () => Effect.die("unused"),
+          getCommandReadModel: () => Effect.die("unused"),
+          getSnapshot: () => Effect.die("unused"),
+          getShellSnapshot: () => Effect.die("unused"),
+          getArchivedShellSnapshot: () => Effect.die("unused"),
+          getSnapshotSequence: () => Effect.die("unused"),
+          getCounts: () => Effect.die("unused"),
+          getEventReplayStats: () => Effect.die("unused"),
+          getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
+          getProjectShellById: () => Effect.die("unused"),
+          getFirstActiveThreadIdByProjectId: () => Effect.die("thread lookup failed"),
+          getImportedAgentSessionSources: () => Effect.die("unused"),
+          getThreadCheckpointContext: () => Effect.succeed(Option.none()),
+          getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+          getThreadRuntimeContext: () => Effect.die("unused"),
+          getThreadShellById: () => Effect.die("unused"),
+          getThreadDetailById: () => Effect.die("unused"),
+          getThreadDetailSnapshot: () => Effect.die("unused"),
+          searchThreads: () => Effect.succeed({ matches: [] }),
+        }),
+        Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
+          readEvents: () => Stream.empty,
+          readThreadEvents: () => Stream.empty,
+          getThreadReplayStats: () => Effect.die("unused thread replay stats"),
+          dispatch: (command) =>
+            Ref.update(dispatchCalls, (calls) => [...calls, command.type]).pipe(
+              Effect.as({ sequence: 1 }),
+            ),
+          streamDomainEvents: Stream.empty,
+          subscribeDomainEvents: Effect.succeed(Stream.empty),
+          latestSequence: Effect.succeed(0),
+        } satisfies OrchestrationEngine.OrchestrationEngineService["Service"]),
+        Effect.provide(NodeServices.layer),
+      );
+
+      assert.equal(typeof targets.bootstrapProjectId, "string");
+      assert.equal(targets.bootstrapProjectCreated, true);
+      assert.equal(targets.bootstrapThreadId, undefined);
+      assert.equal(targets.bootstrapThreadCreated, undefined);
+      assert.deepStrictEqual(yield* Ref.get(dispatchCalls), ["project.create"]);
+    }),
+);
+
 it.effect("resolveAutoBootstrapWelcomeTargets preserves typed UUID generation failures", () =>
   Effect.gen(function* () {
     const crypto = yield* Crypto.Crypto;
@@ -326,8 +338,10 @@ it.effect("resolveAutoBootstrapWelcomeTargets preserves typed UUID generation fa
         getActiveProjectByWorkspaceRoot: () => Effect.succeed(Option.none()),
         getProjectShellById: () => Effect.die("unused"),
         getFirstActiveThreadIdByProjectId: () => Effect.succeed(Option.none()),
+        getImportedAgentSessionSources: () => Effect.die("unused"),
         getThreadCheckpointContext: () => Effect.succeed(Option.none()),
         getFullThreadDiffContext: () => Effect.succeed(Option.none()),
+        getThreadRuntimeContext: () => Effect.die("unused"),
         getThreadShellById: () => Effect.die("unused"),
         getThreadDetailById: () => Effect.die("unused"),
         getThreadDetailSnapshot: () => Effect.die("unused"),
@@ -335,6 +349,8 @@ it.effect("resolveAutoBootstrapWelcomeTargets preserves typed UUID generation fa
       }),
       Effect.provideService(OrchestrationEngine.OrchestrationEngineService, {
         readEvents: () => Stream.empty,
+        readThreadEvents: () => Stream.empty,
+        getThreadReplayStats: () => Effect.die("unused thread replay stats"),
         dispatch: (command) =>
           Ref.update(dispatchCalls, (calls) => [...calls, command.type]).pipe(
             Effect.as({ sequence: 1 }),
@@ -354,3 +370,31 @@ it.effect("resolveAutoBootstrapWelcomeTargets preserves typed UUID generation fa
     assert.deepStrictEqual(yield* Ref.get(dispatchCalls), []);
   }).pipe(Effect.provide(NodeServices.layer)),
 );
+
+it.effect("completeAutoBootstrapWelcome settles failures without bootstrap targets", () =>
+  Effect.gen(function* () {
+    const completion = yield* ServerRuntimeStartup.completeAutoBootstrapWelcome(
+      Effect.fail("bootstrap failed"),
+    );
+
+    assert.deepStrictEqual(completion, { bootstrapStatus: "complete" });
+  }),
+);
+
+it.effect("completeAutoBootstrapWelcome settles unexpected defects", () =>
+  Effect.gen(function* () {
+    const completion = yield* ServerRuntimeStartup.completeAutoBootstrapWelcome(
+      Effect.die("bootstrap defect"),
+    );
+
+    assert.deepStrictEqual(completion, { bootstrapStatus: "complete" });
+  }),
+);
+
+it.effect("completeAutoBootstrapWelcome settles an empty bootstrap result", () =>
+  Effect.gen(function* () {
+    const completion = yield* ServerRuntimeStartup.completeAutoBootstrapWelcome(Effect.succeed({}));
+
+    assert.deepStrictEqual(completion, { bootstrapStatus: "complete" });
+  }),
+);
diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.ts
index 064796b2810b..2a12dbb3637c 100644
--- a/apps/server/src/serverRuntimeStartup.ts
+++ b/apps/server/src/serverRuntimeStartup.ts
@@ -168,15 +168,7 @@ export const recordStartupHeartbeat = Effect.gen(function* () {
   });
 });
 
-export const launchStartupHeartbeat = recordStartupHeartbeat.pipe(
-  Effect.annotateSpans({ "startup.phase": "heartbeat.record" }),
-  Effect.withSpan("server.startup.heartbeat.record"),
-  Effect.ignoreCause({ log: true }),
-  Effect.forkScoped,
-  Effect.asVoid,
-);
-
-export const getAutoBootstrapThreadModelSelection = (): ModelSelection => ({
+const getAutoBootstrapThreadModelSelection = (): ModelSelection => ({
   instanceId: ProviderInstanceId.make("codex"),
   model: DEFAULT_MODEL,
 });
@@ -202,6 +194,8 @@ export const resolveAutoBootstrapWelcomeTargets = Effect.gen(function* () {
 
   let bootstrapProjectId: ProjectId | undefined;
   let bootstrapThreadId: ThreadId | undefined;
+  let bootstrapProjectCreated = false;
+  let bootstrapThreadCreated = false;
 
   if (serverConfig.autoBootstrapProjectFromCwd) {
     yield* Effect.gen(function* () {
@@ -224,45 +218,79 @@ export const resolveAutoBootstrapWelcomeTargets = Effect.gen(function* () {
           workspaceRoot: serverConfig.cwd,
           createdAt,
         });
+        bootstrapProjectId = nextProjectId;
+        bootstrapProjectCreated = true;
       } else {
         nextProjectId = existingProject.value.id;
+        bootstrapProjectId = nextProjectId;
         nextThreadModelSelection =
           existingProject.value.defaultModelSelection ?? getAutoBootstrapThreadModelSelection();
       }
 
-      const existingThreadId =
-        yield* projectionReadModelQuery.getFirstActiveThreadIdByProjectId(nextProjectId);
-      if (Option.isNone(existingThreadId)) {
-        const createdAt = DateTime.formatIso(yield* DateTime.now);
-        const createdThreadId = ThreadId.make(yield* randomUUID);
-        yield* orchestrationEngine.dispatch({
-          type: "thread.create",
-          commandId: CommandId.make(yield* randomUUID),
-          threadId: createdThreadId,
-          projectId: nextProjectId,
-          title: "New thread",
-          modelSelection: nextThreadModelSelection,
-          interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
-          runtimeMode: "full-access",
-          branch: null,
-          worktreePath: null,
-          createdAt,
-        });
-        bootstrapProjectId = nextProjectId;
-        bootstrapThreadId = createdThreadId;
-      } else {
-        bootstrapProjectId = nextProjectId;
-        bootstrapThreadId = existingThreadId.value;
-      }
+      yield* Effect.gen(function* () {
+        const existingThreadId =
+          yield* projectionReadModelQuery.getFirstActiveThreadIdByProjectId(nextProjectId);
+        if (Option.isNone(existingThreadId)) {
+          const createdAt = DateTime.formatIso(yield* DateTime.now);
+          const createdThreadId = ThreadId.make(yield* randomUUID);
+          yield* orchestrationEngine.dispatch({
+            type: "thread.create",
+            commandId: CommandId.make(yield* randomUUID),
+            threadId: createdThreadId,
+            projectId: nextProjectId,
+            title: "New thread",
+            modelSelection: nextThreadModelSelection,
+            interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+            runtimeMode: "full-access",
+            branch: null,
+            worktreePath: null,
+            createdAt,
+          });
+          bootstrapThreadId = createdThreadId;
+          bootstrapThreadCreated = true;
+        } else {
+          bootstrapThreadId = existingThreadId.value;
+        }
+      }).pipe(
+        Effect.catchCause((cause) =>
+          Cause.hasInterrupts(cause)
+            ? Effect.failCause(cause)
+            : Effect.logWarning("startup thread auto-bootstrap failed", {
+                bootstrapProjectId: nextProjectId,
+                cause,
+              }),
+        ),
+      );
     });
   }
 
   return {
     ...(bootstrapProjectId ? { bootstrapProjectId } : {}),
     ...(bootstrapThreadId ? { bootstrapThreadId } : {}),
+    ...(bootstrapProjectId ? { bootstrapProjectCreated } : {}),
+    ...(bootstrapThreadId ? { bootstrapThreadCreated } : {}),
   } as const;
 });
 
+export const completeAutoBootstrapWelcome = <A extends object, E, R>(
+  bootstrap: Effect.Effect<A, E, R>,
+) =>
+  bootstrap.pipe(
+    Effect.matchCauseEffect({
+      onFailure: (cause) =>
+        Cause.hasInterrupts(cause)
+          ? Effect.failCause(cause)
+          : Effect.logWarning("startup auto-bootstrap failed", { cause }).pipe(
+              Effect.as({ bootstrapStatus: "complete" as const }),
+            ),
+      onSuccess: (targets) =>
+        Effect.succeed({
+          ...targets,
+          bootstrapStatus: "complete" as const,
+        }),
+    }),
+  );
+
 const resolveStartupBrowserTarget = Effect.gen(function* () {
   const serverConfig = yield* ServerConfig.ServerConfig;
   const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
@@ -394,6 +422,7 @@ export const markRunningProviderSessionsForContinuation = Effect.gen(function* (
         runtimePayload: {
           ...readRuntimePayload(binding.value.runtimePayload),
           [SERVER_UPDATE_CONTINUATION_KEY]: activeTurnId,
+          continueAfterServerUpdatePrepared: null,
         },
       });
       marked.push(thread.id);
@@ -423,6 +452,7 @@ const clearContinuationMarkers = (
                 runtimePayload: {
                   ...readRuntimePayload(binding.runtimePayload),
                   [SERVER_UPDATE_CONTINUATION_KEY]: null,
+                  continueAfterServerUpdatePrepared: null,
                 },
               }),
           }),
@@ -443,17 +473,56 @@ export const reconcileProviderSessions = Effect.gen(function* () {
   const orchestrationEngine = yield* OrchestrationEngine.OrchestrationEngineService;
   const providerService = yield* ProviderService.ProviderService;
   const query = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
+  const settings = yield* ServerSettings.ServerSettingsService;
+  const continueAfterRestart = yield* settings.getSettings.pipe(
+    Effect.map((value) => value.continueThreadsAfterServerUpdate),
+    Effect.catch((cause) =>
+      Effect.logWarning("could not read restart continuation preference", { cause }).pipe(
+        Effect.as(false),
+      ),
+    ),
+  );
 
   const liveThreadIds = new Set(
     (yield* providerService.listSessions()).map((session) => session.threadId),
   );
   const { threads } = yield* query.getCommandReadModel();
+  // Provider startup can report ready before the continuation is submitted.
+  // Find those markers in one read rather than querying every idle thread.
+  const preparedThreadIds = new Set(
+    (yield* directory.listBindings().pipe(
+      Effect.catch((cause) =>
+        Effect.logWarning("failed to read prepared provider continuations", { cause }).pipe(
+          Effect.andThen(
+            Effect.forEach(
+              threads.filter(
+                (thread) => thread.session?.status === "ready" && !liveThreadIds.has(thread.id),
+              ),
+              (thread) =>
+                directory.getBinding(thread.id).pipe(Effect.orElseSucceed(() => Option.none())),
+            ),
+          ),
+          Effect.map((bindings) =>
+            bindings.flatMap((binding) => (Option.isSome(binding) ? [binding.value] : [])),
+          ),
+        ),
+      ),
+    ))
+      .filter(
+        (binding) =>
+          readServerUpdateContinuationTurnId(binding.runtimePayload) !== null &&
+          readRuntimePayload(binding.runtimePayload).activeTurnId === null &&
+          readRuntimePayload(binding.runtimePayload).continueAfterServerUpdatePrepared === true,
+      )
+      .map((binding) => binding.threadId),
+  );
   const orphanedThreads = threads.filter(
     (thread) =>
       thread.session !== null &&
       (thread.session.status === "starting" ||
         thread.session.status === "running" ||
-        thread.session.activeTurnId !== null) &&
+        thread.session.activeTurnId !== null ||
+        (thread.session.status === "ready" && preparedThreadIds.has(thread.id))) &&
       !liveThreadIds.has(thread.id),
   );
 
@@ -479,7 +548,27 @@ export const reconcileProviderSessions = Effect.gen(function* () {
       : null;
     const continuationMarked =
       continuationTurnId !== null &&
-      (session.activeTurnId === null || continuationTurnId === session.activeTurnId);
+      (session.activeTurnId === null || continuationTurnId === session.activeTurnId) &&
+      Option.isSome(binding) &&
+      (readRuntimePayload(binding.value.runtimePayload).activeTurnId == null ||
+        readRuntimePayload(binding.value.runtimePayload).activeTurnId === continuationTurnId);
+    const preparedWhileReady =
+      session.status === "ready" &&
+      session.activeTurnId === null &&
+      continuationMarked &&
+      Option.isSome(binding) &&
+      readRuntimePayload(binding.value.runtimePayload).activeTurnId === null &&
+      readRuntimePayload(binding.value.runtimePayload).continueAfterServerUpdatePrepared === true;
+    // Abrupt shutdowns cannot write an update marker. Require both durable
+    // records to agree on an unfinished turn before recovering one implicitly.
+    const interruptedByRestart =
+      continueAfterRestart &&
+      session.status === "running" &&
+      session.activeTurnId !== null &&
+      Option.isSome(binding) &&
+      binding.value.status === "running" &&
+      binding.value.resumeCursor != null &&
+      readRuntimePayload(binding.value.runtimePayload).activeTurnId === session.activeTurnId;
     const settleAsError = (lastError: string) =>
       Effect.gen(function* () {
         yield* Effect.gen(function* () {
@@ -490,7 +579,12 @@ export const reconcileProviderSessions = Effect.gen(function* () {
               runtimePayload: {
                 ...readRuntimePayload(binding.value.runtimePayload),
                 activeTurnId: null,
-                ...(continuationMarkerPresent ? { [SERVER_UPDATE_CONTINUATION_KEY]: null } : {}),
+                ...(continuationMarkerPresent || interruptedByRestart
+                  ? {
+                      [SERVER_UPDATE_CONTINUATION_KEY]: null,
+                      continueAfterServerUpdatePrepared: null,
+                    }
+                  : {}),
               },
             });
           }
@@ -535,7 +629,9 @@ export const reconcileProviderSessions = Effect.gen(function* () {
 
     if (
       Option.isSome(binding) &&
-      continuationMarked &&
+      (continuationMarked || interruptedByRestart) &&
+      (session.status === "running" || session.status === "starting" || preparedWhileReady) &&
+      binding.value.resumeCursor != null &&
       thread.archivedAt === null &&
       thread.deletedAt === null
     ) {
@@ -545,6 +641,9 @@ export const reconcileProviderSessions = Effect.gen(function* () {
           status: "starting",
           runtimePayload: {
             ...readRuntimePayload(binding.value.runtimePayload),
+            // Keep recovery durable if this process also exits before sending.
+            [SERVER_UPDATE_CONTINUATION_KEY]: session.activeTurnId ?? continuationTurnId,
+            continueAfterServerUpdatePrepared: true,
             activeTurnId: null,
           },
         });
@@ -608,12 +707,12 @@ export const reconcileProviderSessions = Effect.gen(function* () {
             }
             return;
           }
-          yield* Effect.logWarning("failed to continue provider session after server update", {
+          yield* Effect.logWarning("failed to continue provider session after server restart", {
             threadId: thread.id,
             cause: continuationExit.cause,
           });
           yield* settleAsError(
-            "Could not continue this thread after the server update. Send a new message to continue.",
+            "Could not continue this thread after the server restart. Send a new message to continue.",
           ).pipe(Effect.ignoreCause);
         }),
       );
@@ -776,36 +875,31 @@ export const make = (options?: StartupOptions) =>
           runStartupPhase(
             "welcome.autobootstrap",
             Effect.gen(function* () {
-              const bootstrapTargets = yield* resolveAutoBootstrapWelcomeTargets.pipe(
-                Effect.provideService(Crypto.Crypto, crypto),
+              const bootstrapCompletion = yield* completeAutoBootstrapWelcome(
+                resolveAutoBootstrapWelcomeTargets.pipe(
+                  Effect.provideService(Crypto.Crypto, crypto),
+                ),
+              );
+
+              yield* Effect.logDebug(
+                "startup phase: publishing completed bootstrap welcome event",
+                {
+                  environmentId: environment.environmentId,
+                  cwd: welcomeBase.cwd,
+                  projectName: welcomeBase.projectName,
+                  ...bootstrapCompletion,
+                },
               );
-              if (!bootstrapTargets.bootstrapProjectId && !bootstrapTargets.bootstrapThreadId) {
-                return;
-              }
-
-              yield* Effect.logDebug("startup phase: publishing bootstrapped welcome event", {
-                environmentId: environment.environmentId,
-                cwd: welcomeBase.cwd,
-                projectName: welcomeBase.projectName,
-                bootstrapProjectId: bootstrapTargets.bootstrapProjectId,
-                bootstrapThreadId: bootstrapTargets.bootstrapThreadId,
-              });
               yield* lifecycleEvents.publish({
                 version: 1,
                 type: "welcome",
                 payload: {
                   environment,
                   ...welcomeBase,
-                  ...bootstrapTargets,
+                  ...bootstrapCompletion,
                 },
               });
-            }).pipe(
-              Effect.catch((cause) =>
-                Effect.logWarning("startup auto-bootstrap welcome failed", {
-                  cause,
-                }),
-              ),
-            ),
+            }).pipe(Effect.ignoreCause({ log: true })),
           ),
         );
       }
@@ -851,7 +945,11 @@ export const make = (options?: StartupOptions) =>
         lifecycleEvents.publish({
           version: 1,
           type: "welcome",
-          payload: { environment, ...welcomeBase },
+          payload: {
+            environment,
+            ...welcomeBase,
+            bootstrapStatus: serverConfig.autoBootstrapProjectFromCwd ? "pending" : "complete",
+          },
         }),
       );
       yield* options?.activate ?? Effect.void;
diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts
index 2f7dfcd5afef..4d8869397864 100644
--- a/apps/server/src/serverSettings.test.ts
+++ b/apps/server/src/serverSettings.test.ts
@@ -15,6 +15,7 @@ import * as Duration from "effect/Duration";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Path from "effect/Path";
 import * as PlatformError from "effect/PlatformError";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
@@ -23,6 +24,7 @@ import * as ServerSecretStore from "./auth/ServerSecretStore.ts";
 import * as ServerConfig from "./config.ts";
 import { SqlitePersistenceMemory } from "./persistence/Layers/Sqlite.ts";
 import * as ServerSettingsModule from "./serverSettings.ts";
+import { resolveProviderInstanceTerminalEnvironment } from "./terminal/Manager.ts";
 
 const decodeSettingsPatch = Schema.decodeUnknownEffect(ServerSettingsPatch);
 const decodeServerSettings = Schema.decodeUnknownEffect(ServerSettings);
@@ -273,6 +275,32 @@ it.layer(NodeServices.layer)("server settings", (it) => {
     ).pipe(Effect.provide(makeServerSettingsLayer())),
   );
 
+  it.effect("persists custom usage prices and removes them from the settings file", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const serverConfig = yield* ServerConfig.ServerConfig;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const serverSettings = yield* ServerSettingsModule.ServerSettingsService;
+        const prices = {
+          inputCostPerMillionTokens: 2,
+          outputCostPerMillionTokens: 8,
+          cacheReadCostPerMillionTokens: 0,
+        };
+        const readPersisted = fileSystem
+          .readFileString(serverConfig.settingsPath)
+          .pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(ServerSettings))));
+
+        yield* serverSettings.updateSettings({ usagePriceOverrides: { "example-model": prices } });
+        const persisted = yield* readPersisted;
+        assert.deepStrictEqual(persisted.usagePriceOverrides, { "example-model": prices });
+
+        yield* serverSettings.updateSettings({ usagePriceOverrides: { "example-model": null } });
+        const restored = yield* readPersisted;
+        assert.deepStrictEqual(restored.usagePriceOverrides, {});
+      }),
+    ).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
+
   it.effect("persists and broadcasts thread settlement settings", () =>
     Effect.scoped(
       Effect.gen(function* () {
@@ -1120,4 +1148,39 @@ it.layer(NodeServices.layer)("server settings", (it) => {
       );
     }).pipe(Effect.provide(makeServerSettingsLayer())),
   );
+
+  it.effect("materializes provider secrets for terminal environment resolution", () =>
+    Effect.gen(function* () {
+      const serverSettings = yield* ServerSettingsModule.ServerSettingsService;
+      const serverConfig = yield* ServerConfig.ServerConfig;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const instanceId = ProviderInstanceId.make("codex_terminal");
+
+      yield* serverSettings.updateSettings({
+        providerInstances: {
+          [instanceId]: {
+            driver: ProviderDriverKind.make("codex"),
+            environment: [
+              { name: "OPENROUTER_API_KEY", value: "sk-terminal-secret", sensitive: true },
+            ],
+            config: { homePath: "~/.codex-terminal" },
+          },
+        },
+      });
+
+      const environment = yield* resolveProviderInstanceTerminalEnvironment({
+        serverSettings,
+        path,
+        rawProviderInstanceId: instanceId,
+        env: undefined,
+      });
+      const persisted = yield* fileSystem.readFileString(serverConfig.settingsPath);
+
+      assert.equal(environment.OPENROUTER_API_KEY, "sk-terminal-secret");
+      assert.match(environment.CODEX_HOME ?? "", /[\\/][.]codex-terminal$/);
+      assert.notInclude(persisted, "sk-terminal-secret");
+      assert.include(persisted, '"valueRedacted": true');
+    }).pipe(Effect.provide(makeServerSettingsLayer())),
+  );
 });
diff --git a/apps/server/src/serviceLauncher.ts b/apps/server/src/serviceLauncher.ts
index b99f90e0fdf5..e912130c8939 100644
--- a/apps/server/src/serviceLauncher.ts
+++ b/apps/server/src/serviceLauncher.ts
@@ -70,8 +70,9 @@ async function pathExists(target: string): Promise<boolean> {
   }
 }
 
+// Opened read-write: Windows refuses to flush a handle without write access.
 async function syncFile(filePath: string): Promise<void> {
-  const handle = await NodeFSP.open(filePath, "r");
+  const handle = await NodeFSP.open(filePath, "r+");
   try {
     await handle.sync();
   } finally {
@@ -79,10 +80,15 @@ async function syncFile(filePath: string): Promise<void> {
   }
 }
 
+// Flushes a directory entry so a rename into it survives power loss. Windows
+// has no directory fsync: the handle opens but sync fails with EPERM, and
+// NTFS journals the rename on its own.
 async function syncDirectory(directory: string): Promise<void> {
   const handle = await NodeFSP.open(directory, "r");
   try {
     await handle.sync();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EPERM") throw error;
   } finally {
     await handle.close();
   }
@@ -188,12 +194,7 @@ export async function writeServiceState(filePath: string, state: ServiceState):
     await handle.close();
     handle = undefined;
     await NodeFSP.rename(tempPath, filePath);
-    const directoryHandle = await NodeFSP.open(directory, "r");
-    try {
-      await directoryHandle.sync();
-    } finally {
-      await directoryHandle.close();
-    }
+    await syncDirectory(directory);
   } finally {
     await handle?.close().catch(() => undefined);
     await NodeFSP.rm(tempPath, { force: true }).catch(() => undefined);
diff --git a/apps/server/src/sourceControl/PrTemplateDetection.test.ts b/apps/server/src/sourceControl/PrTemplateDetection.test.ts
index 34112c9c528c..5b91e631112f 100644
--- a/apps/server/src/sourceControl/PrTemplateDetection.test.ts
+++ b/apps/server/src/sourceControl/PrTemplateDetection.test.ts
@@ -10,6 +10,7 @@ import { ServerConfig } from "../config.ts";
 import * as GitVcsDriver from "../vcs/GitVcsDriver.ts";
 import * as VcsProcess from "../vcs/VcsProcess.ts";
 import { detectPrTemplate } from "./PrTemplateDetection.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const SINGLE_TEMPLATE_PATHS = [
   ".github/pull_request_template.md",
@@ -139,27 +140,29 @@ it.effect.each(TEMPLATE_DIRECTORIES)("recognizes the $0 directory", (relativeDir
   ),
 );
 
-it.effect("skips unusable directory entries and uses the one valid template", () =>
-  runWithTempDirectory((cwd) =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const templateDirectory = path.join(cwd, ".github", "PULL_REQUEST_TEMPLATE");
-      yield* fileSystem.makeDirectory(path.join(templateDirectory, "b-directory.md"), {
-        recursive: true,
-      });
-      yield* fileSystem.writeFileString(path.join(templateDirectory, "a-empty.md"), " \n");
-      yield* fileSystem.symlink(
-        path.join(templateDirectory, "missing.md"),
-        path.join(templateDirectory, "c-broken.md"),
-      );
-      yield* fileSystem.writeFileString(path.join(templateDirectory, "z-valid.md"), "valid");
-      yield* commitTemplates(cwd);
-
-      const template = yield* detectTemplate(cwd);
-      assert.strictEqual(Option.getOrUndefined(template), "valid");
-    }),
-  ),
+it.effect.skipIf(!symlinksSupported)(
+  "skips unusable directory entries and uses the one valid template",
+  () =>
+    runWithTempDirectory((cwd) =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const templateDirectory = path.join(cwd, ".github", "PULL_REQUEST_TEMPLATE");
+        yield* fileSystem.makeDirectory(path.join(templateDirectory, "b-directory.md"), {
+          recursive: true,
+        });
+        yield* fileSystem.writeFileString(path.join(templateDirectory, "a-empty.md"), " \n");
+        yield* fileSystem.symlink(
+          path.join(templateDirectory, "missing.md"),
+          path.join(templateDirectory, "c-broken.md"),
+        );
+        yield* fileSystem.writeFileString(path.join(templateDirectory, "z-valid.md"), "valid");
+        yield* commitTemplates(cwd);
+
+        const template = yield* detectTemplate(cwd);
+        assert.strictEqual(Option.getOrUndefined(template), "valid");
+      }),
+    ),
 );
 
 it.effect("does not guess between multiple directory templates", () =>
@@ -176,60 +179,64 @@ it.effect("does not guess between multiple directory templates", () =>
   ),
 );
 
-it.effect("rejects a committed template symlink escaping the repository", () =>
-  runWithTempDirectory((cwd) =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const outsideDirectory = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-pr-template-outside-",
-      });
-      const outsideTemplate = path.join(outsideDirectory, "secret.md");
-      yield* fileSystem.writeFileString(outsideTemplate, "LOCAL_SECRET_SENTINEL");
-      const escapedTemplatePath = path.join(cwd, ".github", "pull_request_template.md");
-      yield* fileSystem.makeDirectory(path.dirname(escapedTemplatePath), { recursive: true });
-      yield* fileSystem.symlink(outsideTemplate, escapedTemplatePath);
-      yield* writeTemplate(cwd, "pull_request_template.md", "safe template");
-      yield* commitTemplates(cwd);
-
-      const template = yield* detectTemplate(cwd);
-      assert.strictEqual(Option.getOrUndefined(template), "safe template");
-      assert.notInclude(
-        Option.getOrElse(template, () => ""),
-        "LOCAL_SECRET_SENTINEL",
-      );
-    }),
-  ),
+it.effect.skipIf(!symlinksSupported)(
+  "rejects a committed template symlink escaping the repository",
+  () =>
+    runWithTempDirectory((cwd) =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const outsideDirectory = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-pr-template-outside-",
+        });
+        const outsideTemplate = path.join(outsideDirectory, "secret.md");
+        yield* fileSystem.writeFileString(outsideTemplate, "LOCAL_SECRET_SENTINEL");
+        const escapedTemplatePath = path.join(cwd, ".github", "pull_request_template.md");
+        yield* fileSystem.makeDirectory(path.dirname(escapedTemplatePath), { recursive: true });
+        yield* fileSystem.symlink(outsideTemplate, escapedTemplatePath);
+        yield* writeTemplate(cwd, "pull_request_template.md", "safe template");
+        yield* commitTemplates(cwd);
+
+        const template = yield* detectTemplate(cwd);
+        assert.strictEqual(Option.getOrUndefined(template), "safe template");
+        assert.notInclude(
+          Option.getOrElse(template, () => ""),
+          "LOCAL_SECRET_SENTINEL",
+        );
+      }),
+    ),
 );
 
-it.effect("reads the committed template when a worktree parent is replaced", () =>
-  runWithTempDirectory((cwd) =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const outsideDirectory = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-pr-template-outside-",
-      });
-      const templatePath = yield* writeTemplate(
-        cwd,
-        ".github/pull_request_template.md",
-        "committed template",
-      );
-      yield* commitTemplates(cwd);
-      yield* writeTemplate(outsideDirectory, "pull_request_template.md", "LOCAL_SECRET_SENTINEL");
-
-      const templateDirectory = path.dirname(templatePath);
-      yield* fileSystem.rename(templateDirectory, path.join(cwd, ".github-original"));
-      yield* fileSystem.symlink(outsideDirectory, templateDirectory);
-
-      const template = yield* detectTemplate(cwd);
-      assert.strictEqual(Option.getOrUndefined(template), "committed template");
-      assert.notInclude(
-        Option.getOrElse(template, () => ""),
-        "LOCAL_SECRET_SENTINEL",
-      );
-    }),
-  ),
+it.effect.skipIf(!symlinksSupported)(
+  "reads the committed template when a worktree parent is replaced",
+  () =>
+    runWithTempDirectory((cwd) =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const outsideDirectory = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-pr-template-outside-",
+        });
+        const templatePath = yield* writeTemplate(
+          cwd,
+          ".github/pull_request_template.md",
+          "committed template",
+        );
+        yield* commitTemplates(cwd);
+        yield* writeTemplate(outsideDirectory, "pull_request_template.md", "LOCAL_SECRET_SENTINEL");
+
+        const templateDirectory = path.dirname(templatePath);
+        yield* fileSystem.rename(templateDirectory, path.join(cwd, ".github-original"));
+        yield* fileSystem.symlink(outsideDirectory, templateDirectory);
+
+        const template = yield* detectTemplate(cwd);
+        assert.strictEqual(Option.getOrUndefined(template), "committed template");
+        assert.notInclude(
+          Option.getOrElse(template, () => ""),
+          "LOCAL_SECRET_SENTINEL",
+        );
+      }),
+    ),
 );
 
 it.effect("bounds template reads and marks truncated content", () =>
diff --git a/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts b/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
index 861da9a10e05..461bff08668a 100644
--- a/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
+++ b/apps/server/src/sourceControl/SourceControlRepositoryService.test.ts
@@ -3,6 +3,7 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import * as Layer from "effect/Layer";
 import * as PlatformError from "effect/PlatformError";
 import { ChildProcessSpawner } from "effect/unstable/process";
@@ -153,10 +154,11 @@ it.effect("preserves provider failures without deriving the repository message f
 it.effect("clones a looked-up repository into the requested destination", () =>
   Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
     const parent = yield* fs.makeTempDirectoryScoped({
       prefix: "t3-source-control-clone-parent-",
     });
-    const destinationPath = `${parent}/t3code`;
+    const destinationPath = path.join(parent, "t3code");
     const cloneCalls: Array<{ cwd: string; args: ReadonlyArray<string> }> = [];
 
     yield* Effect.gen(function* () {
diff --git a/apps/server/src/sourceControl/githubGraphQlBudget.test.ts b/apps/server/src/sourceControl/githubGraphQlBudget.test.ts
index a166bf0dbbaf..a5b0680fafc5 100644
--- a/apps/server/src/sourceControl/githubGraphQlBudget.test.ts
+++ b/apps/server/src/sourceControl/githubGraphQlBudget.test.ts
@@ -9,11 +9,11 @@ const NEXT_RESET_AT = "2026-08-13T15:00:00.000Z";
 const BEFORE_RESET = Date.parse("2026-08-13T13:30:00.000Z");
 const AFTER_RESET = Date.parse("2026-08-13T14:00:01.000Z");
 
-function rateLimit(remaining: number, limit = 5_000, resetAt = RESET_AT): string {
+function rateLimit(remaining: number, limit = 5_000, resetAt = RESET_AT, cost = 14): string {
   return JSON.stringify({
     data: {
       viewer: { login: "bilal" },
-      rateLimit: { cost: 14, limit, remaining, resetAt },
+      rateLimit: { cost, limit, remaining, resetAt },
     },
   });
 }
@@ -86,6 +86,27 @@ describe("GitHub GraphQL budget", () => {
     }).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
   );
 
+  it.effect("learns a cheaper observed cost without restoring reserved quota", () =>
+    Effect.gen(function* () {
+      yield* TestClock.setTime(BEFORE_RESET);
+      const budget = yield* GitHubGraphQlBudget.GitHubGraphQlBudget;
+      const query = "query { viewer { login } }";
+      yield* budget.observe("github.com", rateLimit(512, 5_000, RESET_AT, 8));
+      yield* budget.query("github.com", query);
+      // The admission reserved eight points, but the completed read only cost one.
+      yield* budget.observe("github.com", rateLimit(511, 5_000, RESET_AT, 1));
+
+      for (let count = 0; count < 4; count += 1) {
+        expect(yield* budget.query("github.com", query)).toContain("rateLimit");
+      }
+      const error = yield* Effect.flip(budget.query("github.com", query));
+      expect(error).toMatchObject({
+        _tag: "SourceControlRateLimitPausedError",
+        retryAt: Date.parse(RESET_AT),
+      });
+    }).pipe(Effect.provide(GitHubGraphQlBudget.layer)),
+  );
+
   it.effect("ignores a response from an older reset window", () =>
     Effect.gen(function* () {
       yield* TestClock.setTime(BEFORE_RESET);
diff --git a/apps/server/src/sourceControl/githubGraphQlBudget.ts b/apps/server/src/sourceControl/githubGraphQlBudget.ts
index 9c43de8e0586..9ece27547f5e 100644
--- a/apps/server/src/sourceControl/githubGraphQlBudget.ts
+++ b/apps/server/src/sourceControl/githubGraphQlBudget.ts
@@ -122,15 +122,20 @@ export const make = Effect.gen(function* () {
       const previous = current.get(key);
       // Concurrent reads can finish out of order. Quota only falls within one reset window, and
       // an answer from an older window must not replace the current one.
-      if (
-        previous !== undefined &&
-        (snapshot.resetAtMs < previous.resetAtMs ||
-          (snapshot.resetAtMs === previous.resetAtMs && snapshot.remaining >= previous.remaining))
-      ) {
+      if (previous !== undefined && snapshot.resetAtMs < previous.resetAtMs) {
         return current;
       }
       const next = new Map(current);
-      next.set(key, snapshot);
+      // Keep the conservative balance, but learn the observed cost even when our reservation
+      // was larger. Otherwise one expensive read makes every later cheap read spend its cost.
+      next.set(
+        key,
+        previous !== undefined &&
+          snapshot.resetAtMs === previous.resetAtMs &&
+          snapshot.remaining >= previous.remaining
+          ? { ...previous, cost: snapshot.cost }
+          : snapshot,
+      );
       return next;
     });
   });
diff --git a/apps/server/src/telemetry/AnalyticsService.test.ts b/apps/server/src/telemetry/AnalyticsService.test.ts
index a8a77269c266..c135467efffa 100644
--- a/apps/server/src/telemetry/AnalyticsService.test.ts
+++ b/apps/server/src/telemetry/AnalyticsService.test.ts
@@ -148,4 +148,47 @@ it.layer(NodeServices.layer)("AnalyticsService test", (it) => {
       );
     }),
   );
+
+  it.effect("does not send batch requests when telemetry is disabled", () =>
+    Effect.gen(function* () {
+      const capturedPaths: Array<string> = [];
+      const serverConfigLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {
+        prefix: "t3-telemetry-disabled-",
+      });
+      const telemetryLayer = AnalyticsService.layer.pipe(Layer.provideMerge(serverConfigLayer));
+      const configLayer = ConfigProvider.layer(
+        ConfigProvider.fromUnknown({
+          T3CODE_TELEMETRY_ENABLED: false,
+          T3CODE_POSTHOG_KEY: "phc_test_key",
+          T3CODE_POSTHOG_HOST: "http://localhost",
+        }),
+      );
+      const batchServerLayer = HttpServer.serve(
+        Effect.gen(function* () {
+          const request = yield* HttpServerRequest.HttpServerRequest;
+          capturedPaths.push(request.url);
+          return HttpServerResponse.jsonUnsafe({});
+        }),
+      );
+      const runtimeLayer = telemetryLayer.pipe(
+        Layer.provide(configLayer),
+        Layer.provide(
+          Layer.mergeAll(
+            Layer.succeed(HostProcessPlatform, "linux"),
+            Layer.succeed(HostProcessArchitecture, "arm64"),
+          ),
+        ),
+        Layer.provideMerge(NodeHttpServer.layerTest),
+      );
+
+      yield* Effect.gen(function* () {
+        yield* Layer.launch(batchServerLayer).pipe(Effect.forkScoped);
+        const analytics = yield* AnalyticsService.AnalyticsService;
+        yield* analytics.record("test.disabled", { index: 1 });
+        yield* analytics.flush;
+      }).pipe(Effect.provide(runtimeLayer));
+
+      assert.deepEqual(capturedPaths, []);
+    }),
+  );
 });
diff --git a/apps/server/src/telemetry/Identify.test.ts b/apps/server/src/telemetry/Identify.test.ts
index ab151821789a..92d3223267d7 100644
--- a/apps/server/src/telemetry/Identify.test.ts
+++ b/apps/server/src/telemetry/Identify.test.ts
@@ -33,26 +33,6 @@ const findIdentityLog = (
   errorTag: string,
 ) => logs.find((log) => log.annotations.source === source && log.annotations.errorTag === errorTag);
 
-it("preserves exact telemetry identity causes without deriving messages from them", () => {
-  const decodeCause = new Error("private nested decode details");
-  const decodeError = new Identify.TelemetryIdentityDecodeError({
-    source: "codex",
-    filePath: "/tmp/auth.json",
-    cause: decodeCause,
-  });
-  const readCause = new Error("private nested read details");
-  const readError = new Identify.TelemetryIdentityReadError({
-    source: "anonymous",
-    filePath: "/tmp/anonymous-id",
-    cause: readCause,
-  });
-
-  assert.strictEqual(decodeError.cause, decodeCause);
-  assert.strictEqual(readError.cause, readCause);
-  assert.notInclude(decodeError.message, decodeCause.message);
-  assert.notInclude(readError.message, readCause.message);
-});
-
 it.layer(NodeServices.layer)("telemetry identity", (it) => {
   it.effect("uses the persisted anonymous id when provider identities are absent", () =>
     Effect.gen(function* () {
diff --git a/apps/server/src/telemetry/Identify.ts b/apps/server/src/telemetry/Identify.ts
index b6c3d0066dff..15d3bf13f782 100644
--- a/apps/server/src/telemetry/Identify.ts
+++ b/apps/server/src/telemetry/Identify.ts
@@ -23,7 +23,7 @@ const ClaudeJsonSchema = Schema.Struct({
 export const TelemetryIdentitySource = Schema.Literals(["codex", "claude", "anonymous"]);
 export type TelemetryIdentitySource = typeof TelemetryIdentitySource.Type;
 
-export class TelemetryIdentityReadError extends Schema.TaggedErrorClass<TelemetryIdentityReadError>()(
+class TelemetryIdentityReadError extends Schema.TaggedErrorClass<TelemetryIdentityReadError>()(
   "TelemetryIdentityReadError",
   {
     source: TelemetryIdentitySource,
@@ -36,7 +36,7 @@ export class TelemetryIdentityReadError extends Schema.TaggedErrorClass<Telemetr
   }
 }
 
-export class TelemetryIdentityDecodeError extends Schema.TaggedErrorClass<TelemetryIdentityDecodeError>()(
+class TelemetryIdentityDecodeError extends Schema.TaggedErrorClass<TelemetryIdentityDecodeError>()(
   "TelemetryIdentityDecodeError",
   {
     source: Schema.Literals(["codex", "claude"]),
diff --git a/apps/server/src/terminal/Manager.test.ts b/apps/server/src/terminal/Manager.test.ts
index 47d91e4516ec..e480e11588b0 100644
--- a/apps/server/src/terminal/Manager.test.ts
+++ b/apps/server/src/terminal/Manager.test.ts
@@ -7,9 +7,14 @@ import {
   type TerminalMetadataStreamEvent,
   type TerminalOpenInput,
   type TerminalRestartInput,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  ServerSettingsError,
+  TerminalProviderInstanceNotFoundError,
 } from "@t3tools/contracts";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import * as Data from "effect/Data";
+import * as Deferred from "effect/Deferred";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Encoding from "effect/Encoding";
@@ -23,11 +28,16 @@ import * as Path from "effect/Path";
 import * as Ref from "effect/Ref";
 import * as Schedule from "effect/Schedule";
 import * as Scope from "effect/Scope";
+import * as Stream from "effect/Stream";
 import * as TestClock from "effect/testing/TestClock";
 import { ChildProcessSpawner } from "effect/unstable/process";
 import { expect } from "vite-plus/test";
 
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerConfig from "../config.ts";
+import { SqlitePersistenceMemory } from "../persistence/Layers/Sqlite.ts";
 import * as ProcessRunner from "../processRunner.ts";
+import * as ServerSettings from "../serverSettings.ts";
 import * as TerminalManager from "./Manager.ts";
 import * as PtyAdapter from "./PtyAdapter.ts";
 
@@ -213,7 +223,11 @@ interface CreateManagerOptions {
   subprocessPollIntervalMs?: number;
   processKillGraceMs?: number;
   maxRetainedInactiveSessions?: number;
+  historyByteLimit?: number;
   ptyAdapter?: FakePtyAdapter;
+  resolveProviderInstanceEnvironment?: Parameters<
+    typeof TerminalManager.makeWithOptions
+  >[0]["resolveProviderInstanceEnvironment"];
 }
 
 interface ManagerFixture {
@@ -243,6 +257,9 @@ const createManager = (
         logsDir,
         historyLineLimit,
         ptyAdapter,
+        ...(options.historyByteLimit !== undefined
+          ? { historyByteLimit: options.historyByteLimit }
+          : {}),
         ...(options.shellResolver !== undefined ? { shellResolver: options.shellResolver } : {}),
         ...(options.env !== undefined ? { env: options.env } : {}),
         ...(options.subprocessInspector !== undefined
@@ -255,6 +272,9 @@ const createManager = (
         ...(options.maxRetainedInactiveSessions !== undefined
           ? { maxRetainedInactiveSessions: options.maxRetainedInactiveSessions }
           : {}),
+        ...(options.resolveProviderInstanceEnvironment !== undefined
+          ? { resolveProviderInstanceEnvironment: options.resolveProviderInstanceEnvironment }
+          : {}),
       });
       const eventsRef = yield* Ref.make<ReadonlyArray<TerminalEvent>>([]);
       const unsubscribe = yield* manager.subscribe((event) =>
@@ -276,6 +296,105 @@ const createManager = (
 const withHostPlatform = (platform: NodeJS.Platform) =>
   Layer.succeed(HostProcessPlatform, platform);
 
+// Apply the existing line policy, then find the longest code-point-aligned byte tail.
+function retainedHistory(text: string, maxLines: number, maxBytes = Infinity): string {
+  const terminated = text.endsWith("\n");
+  const lines = text.split("\n");
+  if (terminated) lines.pop();
+  const retained = lines.slice(Math.max(0, lines.length - maxLines)).join("\n");
+  const capped = terminated ? `${retained}\n` : retained;
+  if (Buffer.byteLength(capped) <= maxBytes) return capped;
+  const points = Array.from(capped);
+  let start = points.length;
+  let bytes = 0;
+  while (start > 0) {
+    const next = Buffer.byteLength(points[start - 1]!);
+    if (bytes + next > maxBytes) break;
+    bytes += next;
+    start -= 1;
+  }
+  return points.slice(start).join("");
+}
+
+it("preserves line and byte limits across arbitrary chunks, Unicode, ANSI sequences, and clear", () => {
+  let randomSeed = 0x20260904;
+  const fragments = [
+    "",
+    "a",
+    "\n",
+    "\n\n",
+    "\r",
+    "\r\n",
+    "café",
+    "名",
+    "🚀",
+    "\u001b[31m",
+    "\u001b[0m",
+    "\u001b]8;;url\u0007",
+    "\ud83d",
+    "\ude80",
+  ];
+  const nextFragment = () => {
+    randomSeed = (Math.imul(randomSeed, 1_664_525) + 1_013_904_223) >>> 0;
+    return fragments[randomSeed % fragments.length]!;
+  };
+
+  for (const maxBytes of [0, 3, 8, 64, Infinity]) {
+    for (const maxLines of [0, 1, 3, 5, 5_000]) {
+      let expected = retainedHistory("before\ninitial\n", maxLines, maxBytes);
+      const history = new TerminalManager.BoundedTerminalHistory(
+        maxLines,
+        "before\ninitial\n",
+        maxBytes,
+      );
+      expect(history.value()).toBe(expected);
+
+      for (let step = 0; step < 300; step += 1) {
+        if (step % 73 === 0) {
+          history.clear();
+          expected = "";
+          expect(history.value()).toBe(expected);
+        }
+        const chunk = nextFragment() + nextFragment();
+        history.append(chunk);
+        expected = retainedHistory(expected + chunk, maxLines, maxBytes);
+        expect(history.value()).toBe(expected);
+      }
+    }
+  }
+});
+
+it("bounds long partial lines and joins surrogate pairs across chunk boundaries", () => {
+  const maxBytes = 65_539;
+  let expected = "";
+  const history = new TerminalManager.BoundedTerminalHistory(5_000, "", maxBytes);
+  const writes = [
+    "a".repeat(16_383) + "😀" + "b".repeat(70_000),
+    "\r" + "c".repeat(70_000) + "\ud83d",
+    "\ude80" + "d".repeat(100),
+    "\uFEFF" + "名".repeat(30_000),
+  ];
+  for (const text of writes) {
+    history.append(text);
+    expected = retainedHistory(expected + text, 5_000, maxBytes);
+    expect(history.value()).toBe(expected);
+    expect(Buffer.byteLength(history.value())).toBeLessThanOrEqual(maxBytes);
+  }
+});
+
+it("preserves retained lines as older storage is compacted", () => {
+  for (const maxLines of [3, 5_000]) {
+    let expected = "";
+    const history = new TerminalManager.BoundedTerminalHistory(maxLines, expected);
+    for (let batch = 0; batch < 40; batch += 1) {
+      const chunk = Array.from({ length: 300 }, (_, line) => `${batch}:${line}\n`).join("");
+      history.append(chunk);
+      expected = retainedHistory(expected + chunk, maxLines);
+      expect(history.value()).toBe(expected);
+    }
+  }
+});
+
 it.layer(
   Layer.merge(NodeServices.layer, ProcessRunner.layer.pipe(Layer.provide(NodeServices.layer))),
   { excludeTestServices: true },
@@ -1090,6 +1209,105 @@ it.layer(
     }),
   );
 
+  it.effect("caps incrementally appended history without losing partial or empty lines", () =>
+    Effect.gen(function* () {
+      const { manager, ptyAdapter } = yield* createManager(3);
+      yield* manager.open(openInput());
+      const process = ptyAdapter.processes[0];
+      expect(process).toBeDefined();
+      if (!process) return;
+
+      process.emitData("line1\n");
+      process.emitData("\n");
+      process.emitData("line3");
+      process.emitData("-continued\nline4");
+      yield* manager.close({ threadId: "thread-1" });
+
+      const reopened = yield* manager.open(openInput());
+      expect(reopened.history).toBe("\nline3-continued\nline4");
+    }),
+  );
+
+  it.effect("bounds persisted and attached history without truncating live output", () =>
+    Effect.gen(function* () {
+      const { manager, ptyAdapter, logsDir } = yield* createManager(5, { historyByteLimit: 10 });
+      const attachEvents = yield* Ref.make<ReadonlyArray<TerminalAttachStreamEvent>>([]);
+      const unsubscribe = yield* manager.attachStream(openInput(), (event) =>
+        Ref.update(attachEvents, (events) => [...events, event]),
+      );
+      yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));
+      const writes = ["a".repeat(32), "😀\rEND"];
+      const process = ptyAdapter.processes[0]!;
+      for (const text of writes) process.emitData(text);
+      yield* manager.close({ threadId: "thread-1" });
+      expect(yield* readFileString(yield* historyLogPath(logsDir))).toBe("aa😀\rEND");
+
+      const reopened = yield* manager.open(openInput());
+      const events = yield* Ref.get(attachEvents);
+      expect(events.filter((event) => event.type === "output").map((event) => event.data)).toEqual(
+        writes,
+      );
+      const snapshot = events.filter((event) => event.type === "snapshot").at(-1)?.snapshot;
+      expect(snapshot?.history).toBe("aa😀\rEND");
+      expect(snapshot?.sequence).toBe(reopened.sequence);
+    }),
+  );
+
+  for (const source of ["current", "legacy"] as const) {
+    it.effect(`reads only a Unicode-safe tail from oversized ${source} history`, () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        let sourcePath: string | undefined;
+        let closedReads = 0;
+        const readRequests: number[] = [];
+        const trackedFileSystem = FileSystem.FileSystem.of({
+          ...fs,
+          readFileString: (candidate, encoding) =>
+            candidate === sourcePath
+              ? Effect.die("History restoration must not read the whole file")
+              : fs.readFileString(candidate, encoding),
+          open: (candidate, options) =>
+            Effect.gen(function* () {
+              if (candidate !== sourcePath) return yield* fs.open(candidate, options);
+              yield* Effect.addFinalizer(() =>
+                Effect.sync(() => {
+                  closedReads += 1;
+                }),
+              );
+              const file = yield* fs.open(candidate, options);
+              return new Proxy(file, {
+                get(target, key) {
+                  if (key === "read") {
+                    return (buffer: Uint8Array) => {
+                      readRequests.push(buffer.byteLength);
+                      return target.read(buffer.subarray(0, 5));
+                    };
+                  }
+                  return Reflect.get(target, key, target);
+                },
+              });
+            }),
+        });
+        const { manager, logsDir } = yield* createManager(5, { historyByteLimit: 15 }).pipe(
+          Effect.provideService(FileSystem.FileSystem, trackedFileSystem),
+        );
+        const nextPath = yield* historyLogPath(logsDir);
+        sourcePath = source === "current" ? nextPath : path.join(logsDir, "thread-1.log");
+        yield* fs.writeFileString(sourcePath, "old".repeat(32_768) + "😀\uFEFFnewest\ré");
+
+        const snapshot = yield* manager.open(openInput());
+        expect(snapshot.history).toBe("\uFEFFnewest\ré");
+        expect(readRequests).toEqual([15, 10, 5]);
+        expect(closedReads).toBe(1);
+        expect(Buffer.from(yield* fs.readFile(nextPath)).toString()).toBe("\uFEFFnewest\ré");
+        if (source === "legacy") expect(yield* fs.exists(sourcePath)).toBe(false);
+        yield* manager.close({ threadId: "thread-1" });
+        expect((yield* manager.open(openInput())).history).toBe("\uFEFFnewest\ré");
+      }),
+    );
+  }
+
   it.effect("strips replay-unsafe terminal query and reply sequences from persisted history", () =>
     Effect.gen(function* () {
       const { manager, ptyAdapter } = yield* createManager();
@@ -1485,6 +1703,31 @@ it.layer(
     }),
   );
 
+  it.effect.each(["linux", "darwin", "win32"] as const)(
+    "advertises truecolor before the PTY backend on %s without replacing explicit values",
+    (platform) =>
+      Effect.gen(function* () {
+        for (const [parentColor, runtimeColor, expected] of [
+          [undefined, undefined, "truecolor"],
+          ["", undefined, "truecolor"],
+          ["24bit", undefined, "24bit"],
+          ["24bit", "", "truecolor"],
+          ["24bit", "custom", "custom"],
+        ] as const) {
+          const env = Object.freeze({ COLORTERM: parentColor });
+          const { manager, ptyAdapter } = yield* createManager(5, {
+            shellResolver: () => "/bin/sh",
+            env,
+          }).pipe(Effect.provide(withHostPlatform(platform)));
+          yield* manager.open(
+            openInput({ env: runtimeColor === undefined ? {} : { COLORTERM: runtimeColor } }),
+          );
+          expect(ptyAdapter.spawnInputs[0]?.env.COLORTERM).toBe(expected);
+          expect(env.COLORTERM).toBe(parentColor);
+        }
+      }),
+  );
+
   it.effect("filters app runtime env variables from terminal sessions", () =>
     Effect.gen(function* () {
       const { manager, ptyAdapter } = yield* createManager(5, {
@@ -1509,6 +1752,26 @@ it.layer(
     }),
   );
 
+  it.effect("expands provider home paths passed to setup terminals", () =>
+    Effect.gen(function* () {
+      const { manager, ptyAdapter } = yield* createManager(5);
+
+      yield* manager.open({
+        ...openInput(),
+        env: {
+          CODEX_HOME: "~/.codex-work",
+          CLAUDE_CONFIG_DIR: "~/.claude-work",
+          CUSTOM_ACCOUNT: "~/leave-this-value-alone",
+        },
+      });
+
+      const environment = ptyAdapter.spawnInputs[0]?.env;
+      expect(environment?.CODEX_HOME).toMatch(/[\\/][.]codex-work$/);
+      expect(environment?.CLAUDE_CONFIG_DIR).toMatch(/[\\/][.]claude-work$/);
+      expect(environment?.CUSTOM_ACCOUNT).toBe("~/leave-this-value-alone");
+    }),
+  );
+
   it.effect("strips AppImage runtime env from terminal sessions", () =>
     Effect.gen(function* () {
       const appDir = "/tmp/.mount_T3Codeabc123";
@@ -1595,6 +1858,382 @@ it.layer(
     }),
   );
 
+  it.effect("resolves a provider instance environment before spawning", () =>
+    Effect.gen(function* () {
+      const providerInstanceId = ProviderInstanceId.make("codex_work");
+      const { manager, ptyAdapter } = yield* createManager(5, {
+        env: { T3CODE_SECRET: "server-only" },
+        resolveProviderInstanceEnvironment: (requestedId, env) =>
+          Effect.succeed({
+            ...env,
+            PROVIDER_SECRET: requestedId === providerInstanceId ? "secret-value" : "wrong",
+            CODEX_HOME: "/accounts/codex-work",
+          }),
+      });
+
+      const snapshot = yield* manager.open(
+        openInput({ providerInstanceId, env: { CLIENT_FLAG: "1" } }),
+      );
+
+      expect(ptyAdapter.spawnInputs[0]?.env.PROVIDER_SECRET).toBe("secret-value");
+      expect(ptyAdapter.spawnInputs[0]?.env.CODEX_HOME).toBe("/accounts/codex-work");
+      expect(ptyAdapter.spawnInputs[0]?.env.CLIENT_FLAG).toBe("1");
+      expect(ptyAdapter.spawnInputs[0]?.env.T3CODE_SECRET).toBeUndefined();
+      expect(snapshot).not.toHaveProperty("env");
+      expect(snapshot).not.toHaveProperty("providerInstanceId");
+    }),
+  );
+
+  it.effect("fails closed when a provider instance is missing", () =>
+    Effect.gen(function* () {
+      const providerInstanceId = ProviderInstanceId.make("deleted_instance");
+      const { manager, ptyAdapter } = yield* createManager(5, {
+        resolveProviderInstanceEnvironment: (requestedId) =>
+          Effect.fail(
+            new TerminalProviderInstanceNotFoundError({
+              providerInstanceId: ProviderInstanceId.make(requestedId),
+            }),
+          ),
+      });
+
+      const error = yield* manager.open(openInput({ providerInstanceId })).pipe(Effect.flip);
+
+      assert.deepStrictEqual(
+        error,
+        new TerminalProviderInstanceNotFoundError({ providerInstanceId }),
+      );
+      expect(ptyAdapter.spawnInputs).toHaveLength(0);
+    }),
+  );
+
+  it.effect("preserves the settings failure when provider environment resolution fails", () =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const providerInstanceId = ProviderInstanceId.make("codex_work");
+      const settingsCause = new Error("secret store read failed");
+      const settingsError = new ServerSettingsError({
+        settingsPath: "/test/settings.json",
+        operation: "read-secret",
+        providerInstanceId,
+        environmentVariable: "OPENROUTER_API_KEY",
+        cause: settingsCause,
+      });
+      const serverSettings = ServerSettings.ServerSettingsService.of({
+        start: Effect.void,
+        ready: Effect.void,
+        getSettings: Effect.fail(settingsError),
+        updateSettings: () => Effect.fail(settingsError),
+        streamChanges: Stream.empty,
+        subscribeChanges: Effect.succeed(Stream.empty),
+      });
+
+      const error = yield* TerminalManager.resolveProviderInstanceTerminalEnvironment({
+        serverSettings,
+        path,
+        rawProviderInstanceId: providerInstanceId,
+        env: undefined,
+      }).pipe(Effect.flip);
+
+      expect(error).toMatchObject({
+        _tag: "TerminalProviderEnvironmentError",
+        providerInstanceId,
+      });
+      expect(error.cause).toBe(settingsError);
+      expect(error.message).not.toContain(settingsError.message);
+      expect(error.message).not.toContain("OPENROUTER_API_KEY");
+    }),
+  );
+
+  it.effect.each([
+    {
+      name: "Codex home",
+      driver: "codex",
+      variable: "CODEX_HOME",
+      config: { homePath: "/configured/codex" },
+      expectedHome: "/configured/codex",
+    },
+    {
+      name: "Codex shadow home",
+      driver: "codex",
+      variable: "CODEX_HOME",
+      config: { homePath: "/configured/codex", shadowHomePath: "/configured/codex-shadow" },
+      expectedHome: "/configured/codex-shadow",
+    },
+    {
+      name: "Claude home",
+      driver: "claudeAgent",
+      variable: "CLAUDE_CONFIG_DIR",
+      config: { homePath: "/configured/claude" },
+      expectedHome: "/configured/claude",
+    },
+  ])("prefers $name over the instance environment", ({ driver, variable, config, expectedHome }) =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const serverSettings = yield* ServerSettings.ServerSettingsService;
+      const environment = yield* TerminalManager.resolveProviderInstanceTerminalEnvironment({
+        serverSettings,
+        path,
+        rawProviderInstanceId: "configured_home",
+        env: undefined,
+      });
+
+      expect(environment[variable]).toBe(path.resolve(expectedHome));
+    }).pipe(
+      Effect.provide(
+        ServerSettings.layerTest({
+          providerInstances: {
+            [ProviderInstanceId.make("configured_home")]: {
+              driver: ProviderDriverKind.make(driver),
+              environment: [{ name: variable, value: "~/.environment-account", sensitive: false }],
+              config,
+            },
+          },
+        }),
+      ),
+    ),
+  );
+
+  it.effect("resolves the legacy Codex default instance", () =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const serverSettings = yield* ServerSettings.ServerSettingsService;
+      const environment = yield* TerminalManager.resolveProviderInstanceTerminalEnvironment({
+        serverSettings,
+        path,
+        rawProviderInstanceId: "codex",
+        env: undefined,
+      });
+
+      expect(environment.CODEX_HOME).toMatch(/[\\/][.]codex-legacy$/);
+    }).pipe(
+      Effect.provide(
+        ServerSettings.ServerSettingsService.layerTest({
+          providerInstances: {},
+          providers: { codex: { homePath: "~/.codex-legacy" } },
+        }),
+      ),
+    ),
+  );
+
+  it.effect("resolves the legacy Claude default instance", () =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const serverSettings = yield* ServerSettings.ServerSettingsService;
+      const environment = yield* TerminalManager.resolveProviderInstanceTerminalEnvironment({
+        serverSettings,
+        path,
+        rawProviderInstanceId: "claudeAgent",
+        env: undefined,
+      });
+
+      expect(environment.CLAUDE_CONFIG_DIR).toMatch(/[\\/][.]claude-legacy$/);
+    }).pipe(
+      Effect.provide(
+        ServerSettings.ServerSettingsService.layerTest({
+          providerInstances: {},
+          providers: { claudeAgent: { homePath: "~/.claude-legacy" } },
+        }),
+      ),
+    ),
+  );
+
+  it.effect("prefers an explicit default instance over legacy provider settings", () =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const serverSettings = yield* ServerSettings.ServerSettingsService;
+      const environment = yield* TerminalManager.resolveProviderInstanceTerminalEnvironment({
+        serverSettings,
+        path,
+        rawProviderInstanceId: "codex",
+        env: undefined,
+      });
+
+      expect(environment.CODEX_HOME).toMatch(/[\\/][.]codex-explicit$/);
+    }).pipe(
+      Effect.provide(
+        ServerSettings.ServerSettingsService.layerTest({
+          providers: { codex: { homePath: "~/.codex-legacy" } },
+          providerInstances: {
+            [ProviderInstanceId.make("codex")]: {
+              driver: "codex",
+              config: { homePath: "~/.codex-explicit" },
+            },
+          },
+        }),
+      ),
+    ),
+  );
+
+  it.effect("keeps unknown provider instance ids unavailable after legacy hydration", () =>
+    Effect.gen(function* () {
+      const path = yield* Path.Path;
+      const serverSettings = yield* ServerSettings.ServerSettingsService;
+      const error = yield* TerminalManager.resolveProviderInstanceTerminalEnvironment({
+        serverSettings,
+        path,
+        rawProviderInstanceId: "codex_unknown",
+        env: undefined,
+      }).pipe(Effect.flip);
+
+      expect(error).toMatchObject({
+        _tag: "TerminalProviderInstanceNotFoundError",
+        providerInstanceId: "codex_unknown",
+      });
+    }).pipe(Effect.provide(ServerSettings.ServerSettingsService.layerTest())),
+  );
+
+  it.effect("restarts a running terminal when the resolved provider environment changes", () =>
+    Effect.gen(function* () {
+      const providerInstanceId = ProviderInstanceId.make("codex_work");
+      let providerSecret = "first-secret";
+      const { manager, ptyAdapter } = yield* createManager(5, {
+        resolveProviderInstanceEnvironment: () =>
+          Effect.succeed({ PROVIDER_SECRET: providerSecret }),
+      });
+
+      yield* manager.open(openInput({ providerInstanceId }));
+      providerSecret = "second-secret";
+      yield* manager.open(openInput({ providerInstanceId }));
+
+      expect(ptyAdapter.processes[0]?.killed).toBe(true);
+      expect(ptyAdapter.spawnInputs).toHaveLength(2);
+      expect(ptyAdapter.spawnInputs[1]?.env.PROVIDER_SECRET).toBe("second-secret");
+    }),
+  );
+
+  it.effect("restarts with current provider secrets and clears bounded history", () =>
+    Effect.gen(function* () {
+      const serverSettings = yield* ServerSettings.ServerSettingsService;
+      const path = yield* Path.Path;
+      const providerInstanceId = ProviderInstanceId.make("codex_restart");
+      const { manager, ptyAdapter, logsDir } = yield* createManager(2, {
+        historyByteLimit: 8,
+        resolveProviderInstanceEnvironment: (rawProviderInstanceId, env) =>
+          TerminalManager.resolveProviderInstanceTerminalEnvironment({
+            serverSettings,
+            path,
+            rawProviderInstanceId,
+            env,
+          }),
+      });
+      const homePath = path.join(logsDir, "codex");
+      const updateSecret = (value: string) =>
+        serverSettings.updateSettings({
+          providerInstances: {
+            [providerInstanceId]: {
+              driver: ProviderDriverKind.make("codex"),
+              config: { homePath },
+              environment: [{ name: "PROVIDER_SECRET", value, sensitive: true }],
+            },
+          },
+        });
+      const input = {
+        providerInstanceId,
+        env: { CLIENT_FLAG: "1", PROVIDER_SECRET: "client-value" },
+      };
+      const outputProcessed = yield* Deferred.make<void>();
+      const unsubscribe = yield* manager.subscribe((event) =>
+        event.type === "output"
+          ? Deferred.succeed(outputProcessed, undefined).pipe(Effect.asVoid)
+          : Effect.void,
+      );
+      yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));
+
+      yield* updateSecret("first-secret");
+      yield* manager.restart(restartInput(input));
+      const firstProcess = ptyAdapter.processes[0]!;
+      expect(ptyAdapter.spawnInputs[0]?.env.PROVIDER_SECRET).toBe("first-secret");
+      firstProcess.emitData("discarded\nold-one\nold-two\n");
+      yield* Deferred.await(outputProcessed);
+      expect((yield* manager.open(openInput(input))).history).toBe("old-two\n");
+
+      yield* updateSecret("second-secret");
+      const restarted = yield* manager.restart(restartInput(input));
+
+      expect(firstProcess.killed).toBe(true);
+      expect(ptyAdapter.spawnInputs).toHaveLength(2);
+      expect(ptyAdapter.spawnInputs[1]?.env).toMatchObject({
+        PROVIDER_SECRET: "second-secret",
+        CODEX_HOME: homePath,
+        CLIENT_FLAG: "1",
+      });
+      expect(restarted.history).toBe("");
+      expect(restarted.status).toBe("running");
+      expect(restarted).not.toHaveProperty("env");
+      expect(restarted).not.toHaveProperty("providerInstanceId");
+      const logPath = yield* historyLogPath(logsDir);
+      expect(yield* readFileString(logPath)).toBe("");
+
+      ptyAdapter.processes[1]!.emitData("discarded again\nnew-one\nnew-two\n");
+      yield* manager.close({ threadId: "thread-1" });
+      expect(yield* readFileString(logPath)).toBe("new-two\n");
+    }).pipe(
+      Effect.provide(
+        ServerSettings.layer.pipe(
+          Layer.provide(ServerSecretStore.layer),
+          Layer.provide(SqlitePersistenceMemory),
+          Layer.provide(
+            ServerConfig.layerTest(process.cwd(), { prefix: "t3code-terminal-provider-restart-" }),
+          ),
+        ),
+      ),
+    ),
+  );
+
+  it.effect("attaches to a running provider terminal without resolving the provider again", () =>
+    Effect.gen(function* () {
+      const providerInstanceId = ProviderInstanceId.make("codex_work");
+      let providerAvailable = true;
+      const { manager, ptyAdapter } = yield* createManager(5, {
+        resolveProviderInstanceEnvironment: (requestedId) =>
+          providerAvailable
+            ? Effect.succeed({ PROVIDER_SECRET: "secret-value" })
+            : Effect.fail(
+                new TerminalProviderInstanceNotFoundError({
+                  providerInstanceId: ProviderInstanceId.make(requestedId),
+                }),
+              ),
+      });
+      yield* manager.open(openInput({ providerInstanceId }));
+      providerAvailable = false;
+      const events: TerminalAttachStreamEvent[] = [];
+
+      const unsubscribe = yield* manager.attachStream(
+        { ...openInput({ providerInstanceId }), restartIfNotRunning: true },
+        (event) => Effect.sync(() => events.push(event)),
+      );
+      unsubscribe();
+
+      expect(events[0]?.type).toBe("snapshot");
+      expect(ptyAdapter.spawnInputs).toHaveLength(1);
+      expect(ptyAdapter.processes[0]?.killed).toBe(false);
+    }),
+  );
+
+  it.effect("fails closed when attaching would create a missing provider terminal", () =>
+    Effect.gen(function* () {
+      const providerInstanceId = ProviderInstanceId.make("deleted_instance");
+      const { manager, ptyAdapter } = yield* createManager(5, {
+        resolveProviderInstanceEnvironment: (requestedId) =>
+          Effect.fail(
+            new TerminalProviderInstanceNotFoundError({
+              providerInstanceId: ProviderInstanceId.make(requestedId),
+            }),
+          ),
+      });
+
+      const error = yield* manager
+        .attachStream(openInput({ providerInstanceId }), () => Effect.void)
+        .pipe(Effect.flip);
+
+      assert.deepStrictEqual(
+        error,
+        new TerminalProviderInstanceNotFoundError({ providerInstanceId }),
+      );
+      expect(ptyAdapter.spawnInputs).toHaveLength(0);
+    }),
+  );
+
   it.effect("starts zsh with prompt spacer disabled to avoid `%` end markers", () =>
     Effect.gen(function* () {
       if ((yield* HostProcessPlatform) === "win32") return;
diff --git a/apps/server/src/terminal/Manager.ts b/apps/server/src/terminal/Manager.ts
index 64c2dbb913fb..d9bdc6bcd92a 100644
--- a/apps/server/src/terminal/Manager.ts
+++ b/apps/server/src/terminal/Manager.ts
@@ -15,6 +15,8 @@ import {
   TerminalError,
   TerminalHistoryError,
   TerminalNotRunningError,
+  TerminalProviderInstanceNotFoundError,
+  TerminalProviderEnvironmentError,
   TerminalResizeError,
   TerminalSessionLookupError,
   TerminalWriteError,
@@ -31,6 +33,9 @@ import {
   type TerminalSessionStatus,
   type TerminalSummary,
   type TerminalWriteInput,
+  ClaudeSettings,
+  CodexSettings,
+  ProviderInstanceId,
 } from "@t3tools/contracts";
 import { makeKeyedCoalescingWorker } from "@t3tools/shared/KeyedCoalescingWorker";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
@@ -52,11 +57,17 @@ import * as Semaphore from "effect/Semaphore";
 import * as SynchronizedRef from "effect/SynchronizedRef";
 
 import * as ServerConfig from "../config.ts";
+import { mergeProviderInstanceEnvironment } from "../provider/ProviderInstanceEnvironment.ts";
+import { resolveCodexHomeLayout } from "../provider/Drivers/CodexHomeLayout.ts";
+import { makeClaudeEnvironment } from "../provider/Drivers/ClaudeHome.ts";
+import { deriveProviderInstanceConfigMap } from "../provider/Layers/ProviderInstanceRegistryHydration.ts";
+import * as ServerSettings from "../serverSettings.ts";
 import {
   increment,
   terminalRestartsTotal,
   terminalSessionsTotal,
 } from "../observability/Metrics.ts";
+import { expandHomePath } from "../pathExpansion.ts";
 import * as ProcessRunner from "../processRunner.ts";
 import * as PortScanner from "../preview/PortScanner.ts";
 import * as PtyAdapter from "./PtyAdapter.ts";
@@ -69,12 +80,16 @@ export {
   TerminalError,
   TerminalHistoryError,
   TerminalNotRunningError,
+  TerminalProviderInstanceNotFoundError,
+  TerminalProviderEnvironmentError,
   TerminalResizeError,
   TerminalSessionLookupError,
   TerminalWriteError,
 };
 
 const DEFAULT_HISTORY_LINE_LIMIT = 5_000;
+const DEFAULT_HISTORY_BYTE_LIMIT = 8 * 1024 * 1024;
+const MAX_HISTORY_CHUNK_LENGTH = 16 * 1024;
 const DEFAULT_PERSIST_DEBOUNCE_MS = 40;
 const DEFAULT_SUBPROCESS_POLL_INTERVAL_MS = 1_000;
 const DEFAULT_PROCESS_KILL_GRACE_MS = 1_000;
@@ -84,6 +99,8 @@ const DEFAULT_OPEN_ROWS = 30;
 const TERMINAL_ENV_BLOCKLIST = new Set(["PORT", "ELECTRON_RENDERER_PORT", "ELECTRON_RUN_AS_NODE"]);
 const nowIso = Effect.map(DateTime.now, DateTime.formatIso);
 const MAX_TERMINAL_LABEL_LENGTH = 128;
+const decodeClaudeSettings = Schema.decodeUnknownOption(ClaudeSettings);
+const decodeCodexSettings = Schema.decodeUnknownOption(CodexSettings);
 
 class TerminalSubprocessCheckError extends Schema.TaggedErrorClass<TerminalSubprocessCheckError>()(
   "TerminalSubprocessCheckError",
@@ -238,14 +255,14 @@ export interface TerminalStartInput extends TerminalOpenInput {
   rows: number;
 }
 
-export interface TerminalSessionState {
+interface TerminalSessionState {
   threadId: string;
   terminalId: string;
   cwd: string;
   worktreePath: string | null;
   status: TerminalSessionStatus;
   pid: number | null;
-  history: string;
+  history: BoundedTerminalHistory;
   pendingHistoryControlSequence: string;
   pendingProcessEvents: Array<PendingProcessEvent>;
   pendingProcessEventIndex: number;
@@ -266,7 +283,7 @@ export interface TerminalSessionState {
 }
 
 interface PersistHistoryRequest {
-  history: string;
+  history: BoundedTerminalHistory;
   immediate: boolean;
 }
 
@@ -281,7 +298,7 @@ type DrainProcessEventAction =
       threadId: string;
       terminalId: string;
       sequence: number;
-      history: string | null;
+      history: BoundedTerminalHistory | null;
       data: string;
     }
   | {
@@ -340,7 +357,7 @@ function snapshot(session: TerminalSessionState): TerminalSessionSnapshot {
     worktreePath: session.worktreePath,
     status: session.status,
     pid: session.pid,
-    history: session.history,
+    history: session.history.value(),
     exitCode: session.exitCode,
     exitSignal: session.exitSignal,
     label: terminalWireLabel(session),
@@ -784,16 +801,188 @@ const windowsProcessTableSnapshot = Effect.fn("terminal.windowsProcessTableSnaps
   },
 );
 
-function capHistory(history: string, maxLines: number): string {
-  if (history.length === 0) return history;
-  const hasTrailingNewline = history.endsWith("\n");
-  const lines = history.split("\n");
-  if (hasTrailingNewline) {
-    lines.pop();
+interface TerminalHistoryChunk {
+  data: string;
+  byteLength: number;
+  lineBreaks: number;
+}
+
+export class BoundedTerminalHistory {
+  private readonly maxLines: number;
+  private readonly maxBytes: number;
+  private chunks: Array<TerminalHistoryChunk | undefined> = [];
+  private start = 0;
+  private byteLength = 0;
+  private lineBreaks = 0;
+  // Reading the old string's tail on each append can force chunk concatenation.
+  private lastCodeUnit: number | undefined;
+  private cachedValue: string | null = "";
+
+  constructor(maxLines: number, initial: string, maxBytes = DEFAULT_HISTORY_BYTE_LIMIT) {
+    this.maxLines = maxLines;
+    this.maxBytes = maxBytes;
+    this.append(initial);
+  }
+
+  append(text: string): void {
+    if (text.length === 0) return;
+    this.cachedValue = null;
+    if (this.maxBytes <= 0 || this.maxLines <= 0) {
+      this.clear();
+      // Preserve the existing zero-line limit's trailing newline behavior.
+      if (this.maxBytes > 0 && text.endsWith("\n")) this.appendChunk("\n");
+      return;
+    }
+
+    let offset = 0;
+    const previous = this.chunks.at(-1);
+    const lastCode = this.lastCodeUnit;
+    const firstCode = text.charCodeAt(0);
+    if (
+      previous &&
+      lastCode !== undefined &&
+      lastCode >= 0xd800 &&
+      lastCode <= 0xdbff &&
+      firstCode >= 0xdc00 &&
+      firstCode <= 0xdfff
+    ) {
+      // Joining a split surrogate changes its UTF-8 size from 3 to 4 bytes.
+      previous.data += text[0];
+      previous.byteLength += 1;
+      this.byteLength += 1;
+      this.lastCodeUnit = firstCode;
+      offset = 1;
+      this.trim();
+    }
+
+    while (offset < text.length) {
+      let end = Math.min(offset + MAX_HISTORY_CHUNK_LENGTH, text.length);
+      const before = text.charCodeAt(end - 1);
+      const after = text.charCodeAt(end);
+      if (before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff) {
+        end -= 1;
+      }
+      const data = text.slice(offset, end);
+      // Detach small chunks from large input strings so evicted prefixes can be collected.
+      this.appendChunk(
+        text.length > MAX_HISTORY_CHUNK_LENGTH
+          ? Buffer.from(data, "utf16le").toString("utf16le")
+          : data,
+      );
+      this.trim();
+      offset = end;
+    }
+  }
+
+  private appendChunk(data: string): void {
+    const byteLength = Buffer.byteLength(data);
+    let lineBreaks = 0;
+    for (let index = data.indexOf("\n"); index !== -1; index = data.indexOf("\n", index + 1)) {
+      lineBreaks += 1;
+    }
+    const previous = this.chunks.at(-1);
+    if (previous && previous.data.length + data.length <= MAX_HISTORY_CHUNK_LENGTH) {
+      previous.data += data;
+      previous.byteLength += byteLength;
+      previous.lineBreaks += lineBreaks;
+    } else {
+      this.chunks.push({ data, byteLength, lineBreaks });
+    }
+    this.byteLength += byteLength;
+    this.lineBreaks += lineBreaks;
+    this.lastCodeUnit = data.charCodeAt(data.length - 1);
+    this.cachedValue = null;
+  }
+
+  private discardChunk(): void {
+    const first = this.chunks[this.start]!;
+    this.byteLength -= first.byteLength;
+    this.lineBreaks -= first.lineBreaks;
+    this.chunks[this.start++] = undefined;
+  }
+
+  private trimChunk(offset: number, byteLength: number, lineBreaks: number): void {
+    const first = this.chunks[this.start]!;
+    if (offset === first.data.length) {
+      this.discardChunk();
+      return;
+    }
+    first.data = first.data.slice(offset);
+    first.byteLength -= byteLength;
+    first.lineBreaks -= lineBreaks;
+    this.byteLength -= byteLength;
+    this.lineBreaks -= lineBreaks;
+  }
+
+  private trim(): void {
+    const trailingNewline = this.lastCodeUnit === 10;
+    let linesToDrop = this.lineBreaks + (trailingNewline ? 0 : 1) - this.maxLines;
+    while (linesToDrop > 0) {
+      const first = this.chunks[this.start]!;
+      if (first.lineBreaks < linesToDrop) {
+        linesToDrop -= first.lineBreaks;
+        this.discardChunk();
+        continue;
+      }
+      let offset = 0;
+      for (let line = 0; line < linesToDrop; line += 1) {
+        offset = first.data.indexOf("\n", offset) + 1;
+      }
+      this.trimChunk(offset, Buffer.byteLength(first.data.slice(0, offset)), linesToDrop);
+      linesToDrop = 0;
+    }
+
+    while (this.byteLength > this.maxBytes) {
+      const first = this.chunks[this.start]!;
+      const bytesToDrop = this.byteLength - this.maxBytes;
+      if (first.byteLength <= bytesToDrop) {
+        this.discardChunk();
+        continue;
+      }
+      if (first.byteLength === first.data.length && first.lineBreaks === 0) {
+        // ASCII without newlines needs no scan to find the byte cutoff.
+        this.trimChunk(bytesToDrop, bytesToDrop, 0);
+        continue;
+      }
+      let offset = 0;
+      let bytes = 0;
+      let lineBreaks = 0;
+      // Scan only the discarded prefix of one small chunk, never all history.
+      while (bytes < bytesToDrop) {
+        const codePoint = first.data.codePointAt(offset)!;
+        bytes += codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4;
+        offset += codePoint <= 0xffff ? 1 : 2;
+        if (codePoint === 10) lineBreaks += 1;
+      }
+      this.trimChunk(offset, bytes, lineBreaks);
+    }
+    if (
+      this.start === this.chunks.length ||
+      (this.start > 2_048 && this.start * 2 >= this.chunks.length)
+    ) {
+      this.chunks = this.chunks.slice(this.start);
+      this.start = 0;
+      if (this.chunks.length === 0) this.lastCodeUnit = undefined;
+    }
+  }
+
+  clear(): void {
+    this.chunks = [];
+    this.start = 0;
+    this.byteLength = 0;
+    this.lineBreaks = 0;
+    this.lastCodeUnit = undefined;
+    this.cachedValue = "";
+  }
+
+  value(): string {
+    if (this.cachedValue !== null) return this.cachedValue;
+    this.cachedValue = this.chunks
+      .slice(this.start)
+      .map((chunk) => chunk!.data)
+      .join("");
+    return this.cachedValue;
   }
-  if (lines.length <= maxLines) return history;
-  const capped = lines.slice(lines.length - maxLines).join("\n");
-  return hasTrailingNewline ? `${capped}\n` : capped;
 }
 
 function isCsiFinalByte(codePoint: number): boolean {
@@ -1093,9 +1282,14 @@ function createTerminalSpawnEnv(
   }
   if (runtimeEnv) {
     for (const [key, value] of Object.entries(runtimeEnv)) {
-      spawnEnv[key] = value;
+      spawnEnv[key] =
+        key === "CODEX_HOME" || key === "CLAUDE_CONFIG_DIR" ? expandHomePath(value) : value;
     }
   }
+  // Both PTY backends feed truecolor-capable terminal clients.
+  if (spawnEnv.COLORTERM === undefined || spawnEnv.COLORTERM === "") {
+    spawnEnv.COLORTERM = "truecolor";
+  }
   return stripAppImageRuntimeEnv(spawnEnv);
 }
 
@@ -1111,6 +1305,7 @@ function normalizedRuntimeEnv(
 interface TerminalManagerOptions {
   logsDir: string;
   historyLineLimit?: number;
+  historyByteLimit?: number;
   ptyAdapter: PtyAdapter.PtyAdapter["Service"];
   shellResolver?: () => string;
   env?: NodeJS.ProcessEnv;
@@ -1127,17 +1322,78 @@ interface TerminalManagerOptions {
     readonly threadId: string;
     readonly terminalId: string;
   }) => Effect.Effect<void>;
+  resolveProviderInstanceEnvironment?: (
+    providerInstanceId: string,
+    env: Record<string, string> | undefined,
+  ) => Effect.Effect<
+    Record<string, string>,
+    TerminalProviderInstanceNotFoundError | TerminalProviderEnvironmentError
+  >;
 }
 
+export const resolveProviderInstanceTerminalEnvironment = Effect.fn(
+  "terminal.resolveProviderInstanceTerminalEnvironment",
+)(function* (input: {
+  readonly serverSettings: ServerSettings.ServerSettingsService["Service"];
+  readonly path: Path.Path;
+  readonly rawProviderInstanceId: string;
+  readonly env: Record<string, string> | undefined;
+}) {
+  const providerInstanceId = ProviderInstanceId.make(input.rawProviderInstanceId);
+  const settings = yield* input.serverSettings.getSettings.pipe(
+    Effect.mapError((cause) => new TerminalProviderEnvironmentError({ providerInstanceId, cause })),
+  );
+  const instance = deriveProviderInstanceConfigMap(settings)[providerInstanceId];
+  if (instance === undefined) {
+    return yield* new TerminalProviderInstanceNotFoundError({ providerInstanceId });
+  }
+
+  let resolved = mergeProviderInstanceEnvironment(instance.environment, input.env ?? {});
+  if (instance.driver === "codex") {
+    const config = decodeCodexSettings(instance.config ?? {});
+    if (Option.isSome(config)) {
+      const layout = yield* resolveCodexHomeLayout(config.value).pipe(
+        Effect.provideService(Path.Path, input.path),
+      );
+      if (layout.effectiveHomePath)
+        resolved = { ...resolved, CODEX_HOME: layout.effectiveHomePath };
+    }
+  } else if (instance.driver === "claudeAgent") {
+    const config = decodeClaudeSettings(instance.config ?? {});
+    if (Option.isSome(config)) {
+      resolved = yield* makeClaudeEnvironment(config.value, resolved).pipe(
+        Effect.provideService(Path.Path, input.path),
+      );
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(resolved).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  );
+});
+
 export const make = Effect.fn("TerminalManager.make")(function* () {
   const { terminalLogsDir } = yield* ServerConfig.ServerConfig;
   const ptyAdapter = yield* PtyAdapter.PtyAdapter;
   const portDiscovery = yield* PortScanner.PortDiscovery;
+  const serverSettings = yield* ServerSettings.ServerSettingsService;
+  const path = yield* Path.Path;
+  const resolveProviderInstanceEnvironment = Effect.fn(
+    "terminal.resolveProviderInstanceEnvironment",
+  )((rawProviderInstanceId: string, env: Record<string, string> | undefined) =>
+    resolveProviderInstanceTerminalEnvironment({
+      serverSettings,
+      path,
+      rawProviderInstanceId,
+      env,
+    }),
+  );
   return yield* makeWithOptions({
     logsDir: terminalLogsDir,
     ptyAdapter,
     registerTerminalProcesses: portDiscovery.registerTerminalProcesses,
     unregisterTerminal: portDiscovery.unregisterTerminal,
+    resolveProviderInstanceEnvironment,
   });
 });
 
@@ -1151,6 +1407,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
 
   const logsDir = options.logsDir;
   const historyLineLimit = options.historyLineLimit ?? DEFAULT_HISTORY_LINE_LIMIT;
+  const historyByteLimit = options.historyByteLimit ?? DEFAULT_HISTORY_BYTE_LIMIT;
   const platform = yield* HostProcessPlatform;
   // Terminals must inherit the user's full environment (minus the blocklist
   // applied in createTerminalSpawnEnv) — an allowlist here silently strips
@@ -1159,6 +1416,24 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
   const baseEnv = options.env ?? process.env;
   const shellResolver = options.shellResolver ?? (() => defaultShellResolver(platform, baseEnv));
   const processRunner = yield* ProcessRunner.ProcessRunner;
+  const resolveLaunchInputEnvironment = Effect.fn("terminal.resolveLaunchInputEnvironment")(
+    function* <Input extends TerminalOpenInput | TerminalAttachInput | TerminalRestartInput>(
+      input: Input,
+    ): Effect.fn.Return<
+      Input,
+      TerminalProviderInstanceNotFoundError | TerminalProviderEnvironmentError
+    > {
+      if (input.providerInstanceId === undefined) return input;
+      const resolver = options.resolveProviderInstanceEnvironment;
+      if (resolver === undefined) {
+        return yield* new TerminalProviderInstanceNotFoundError({
+          providerInstanceId: ProviderInstanceId.make(input.providerInstanceId),
+        });
+      }
+      const env = yield* resolver(input.providerInstanceId, input.env);
+      return { ...input, env };
+    },
+  );
   // One process-table snapshot per poll tick, shared across every terminal.
   // Per-terminal `pgrep`/`ps` calls multiply spawn load by terminal count and
   // can exhaust the PID space on hosts with many sessions (#6332).
@@ -1372,22 +1647,24 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
         return;
       }
 
-      yield* fileSystem.writeFileString(historyPath(threadId, terminalId), request.history).pipe(
-        Effect.catch((error) =>
-          Effect.logWarning("failed to persist terminal history", {
-            threadId,
-            terminalId,
-            error,
-          }),
-        ),
-      );
+      yield* fileSystem
+        .writeFileString(historyPath(threadId, terminalId), request.history.value())
+        .pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("failed to persist terminal history", {
+              threadId,
+              terminalId,
+              error,
+            }),
+          ),
+        );
     }),
   });
 
   const queuePersist = Effect.fn("terminal.queuePersist")(function* (
     threadId: string,
     terminalId: string,
-    history: string,
+    history: BoundedTerminalHistory,
   ) {
     yield* persistWorker.enqueue(toSessionKey(threadId, terminalId), {
       history,
@@ -1405,7 +1682,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
   const persistHistory = Effect.fn("terminal.persistHistory")(function* (
     threadId: string,
     terminalId: string,
-    history: string,
+    history: BoundedTerminalHistory,
   ) {
     yield* persistWorker.enqueue(toSessionKey(threadId, terminalId), {
       history,
@@ -1414,6 +1691,30 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
     yield* flushPersist(threadId, terminalId);
   });
 
+  const readHistoryTail = Effect.fn("terminal.readHistoryTail")(function* (filePath: string) {
+    const file = yield* fileSystem.open(filePath, { flag: "r" });
+    const info = yield* file.stat;
+    const limit = BigInt(historyByteLimit);
+    const offset = info.size > limit ? info.size - limit : 0n;
+    yield* file.seek(offset, "start");
+    const bytes = new Uint8Array(Number(info.size - offset));
+    let length = 0;
+    while (length < bytes.length) {
+      const read = Number(yield* file.read(bytes.subarray(length)));
+      if (read === 0) break;
+      length += read;
+    }
+    let start = 0;
+    if (offset > 0n) {
+      // A tail read can start inside a UTF-8 code point. Skip its remaining bytes.
+      while (start < length && ((bytes[start] ?? 0) & 0xc0) === 0x80) start += 1;
+    }
+    return {
+      history: new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes.subarray(start, length)),
+      truncated: offset > 0n,
+    };
+  });
+
   const readHistory = Effect.fn("terminal.readHistory")(function* (
     threadId: string,
     terminalId: string,
@@ -1428,15 +1729,15 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
           ),
         )
     ) {
-      const raw = yield* fileSystem
-        .readFileString(nextPath)
-        .pipe(
-          Effect.mapError(
-            (cause) => new TerminalHistoryError({ operation: "read", threadId, terminalId, cause }),
-          ),
-        );
-      const capped = capHistory(raw, historyLineLimit);
-      if (capped !== raw) {
+      const { history: raw, truncated } = yield* readHistoryTail(nextPath).pipe(
+        Effect.scoped,
+        Effect.mapError(
+          (cause) => new TerminalHistoryError({ operation: "read", threadId, terminalId, cause }),
+        ),
+      );
+      const history = new BoundedTerminalHistory(historyLineLimit, raw, historyByteLimit);
+      const capped = history.value();
+      if (truncated || capped !== raw) {
         yield* fileSystem
           .writeFileString(nextPath, capped)
           .pipe(
@@ -1446,11 +1747,11 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
             ),
           );
       }
-      return capped;
+      return history;
     }
 
     if (terminalId !== DEFAULT_TERMINAL_ID) {
-      return "";
+      return new BoundedTerminalHistory(historyLineLimit, "", historyByteLimit);
     }
 
     const legacyPath = legacyHistoryPath(threadId);
@@ -1464,18 +1765,17 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
           ),
         ))
     ) {
-      return "";
+      return new BoundedTerminalHistory(historyLineLimit, "", historyByteLimit);
     }
 
-    const raw = yield* fileSystem
-      .readFileString(legacyPath)
-      .pipe(
-        Effect.mapError(
-          (cause) =>
-            new TerminalHistoryError({ operation: "migrate", threadId, terminalId, cause }),
-        ),
-      );
-    const capped = capHistory(raw, historyLineLimit);
+    const { history: raw } = yield* readHistoryTail(legacyPath).pipe(
+      Effect.scoped,
+      Effect.mapError(
+        (cause) => new TerminalHistoryError({ operation: "migrate", threadId, terminalId, cause }),
+      ),
+    );
+    const history = new BoundedTerminalHistory(historyLineLimit, raw, historyByteLimit);
+    const capped = history.value();
     yield* fileSystem
       .writeFileString(nextPath, capped)
       .pipe(
@@ -1492,7 +1792,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
         }),
       ),
     );
-    return capped;
+    return history;
   });
 
   const deleteHistory = Effect.fn("terminal.deleteHistory")(function* (
@@ -1661,10 +1961,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
           );
           session.pendingHistoryControlSequence = sanitized.pendingControlSequence;
           if (sanitized.visibleText.length > 0) {
-            session.history = capHistory(
-              `${session.history}${sanitized.visibleText}`,
-              historyLineLimit,
-            );
+            session.history.append(sanitized.visibleText);
           }
           const eventStamp = advanceEventSequence(session);
 
@@ -2221,7 +2518,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
       liveSession.cwd = input.cwd;
       liveSession.worktreePath = nextWorktreePath;
       liveSession.runtimeEnv = nextRuntimeEnv;
-      liveSession.history = "";
+      liveSession.history.clear();
       liveSession.pendingHistoryControlSequence = "";
       liveSession.pendingProcessEvents = [];
       liveSession.pendingProcessEventIndex = 0;
@@ -2230,7 +2527,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
     } else if (liveSession.status === "exited" || liveSession.status === "error") {
       liveSession.runtimeEnv = nextRuntimeEnv;
       liveSession.worktreePath = nextWorktreePath;
-      liveSession.history = "";
+      liveSession.history.clear();
       liveSession.pendingHistoryControlSequence = "";
       liveSession.pendingProcessEvents = [];
       liveSession.pendingProcessEventIndex = 0;
@@ -2266,7 +2563,10 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
   });
 
   const open: TerminalManager["Service"]["open"] = (input) =>
-    withThreadLock(input.threadId, openLocked(input));
+    withThreadLock(
+      input.threadId,
+      resolveLaunchInputEnvironment(input).pipe(Effect.flatMap(openLocked)),
+    );
 
   const openOrAttachForStream = (input: TerminalAttachInput) =>
     withThreadLock(
@@ -2283,11 +2583,12 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
             });
           }
 
-          return yield* openLocked({
+          const resolvedInput = yield* resolveLaunchInputEnvironment({
             ...input,
             terminalId,
             cwd: input.cwd,
           });
+          return yield* openLocked(resolvedInput);
         }
 
         const session = existing.value;
@@ -2295,11 +2596,12 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
         const targetRows = input.rows ?? session.rows;
 
         if (!session.process && input.cwd && input.restartIfNotRunning === true) {
-          return yield* openLocked({
+          const resolvedInput = yield* resolveLaunchInputEnvironment({
             ...input,
             terminalId,
             cwd: input.cwd,
           });
+          return yield* openLocked(resolvedInput);
         }
 
         if (
@@ -2535,7 +2837,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
       Effect.gen(function* () {
         const terminalId = input.terminalId;
         const session = yield* requireSession(input.threadId, terminalId);
-        session.history = "";
+        session.history.clear();
         session.pendingHistoryControlSequence = "";
         session.pendingProcessEvents = [];
         session.pendingProcessEventIndex = 0;
@@ -2551,84 +2853,87 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
       }),
     );
 
+  const restartResolved = (input: TerminalRestartInput) =>
+    Effect.gen(function* () {
+      yield* increment(terminalRestartsTotal, { scope: "thread" });
+      const terminalId = input.terminalId;
+      yield* assertValidCwd(input.cwd);
+
+      const sessionKey = toSessionKey(input.threadId, terminalId);
+      const existingSession = yield* getSession(input.threadId, terminalId);
+      let session: TerminalSessionState;
+      if (Option.isNone(existingSession)) {
+        const cols = input.cols ?? DEFAULT_OPEN_COLS;
+        const rows = input.rows ?? DEFAULT_OPEN_ROWS;
+        session = {
+          threadId: input.threadId,
+          terminalId,
+          cwd: input.cwd,
+          worktreePath: input.worktreePath ?? null,
+          status: "starting",
+          pid: null,
+          history: new BoundedTerminalHistory(historyLineLimit, "", historyByteLimit),
+          pendingHistoryControlSequence: "",
+          pendingProcessEvents: [],
+          pendingProcessEventIndex: 0,
+          processEventDrainRunning: false,
+          exitCode: null,
+          exitSignal: null,
+          updatedAt: yield* nowIso,
+          eventSequence: 0,
+          cols,
+          rows,
+          process: null,
+          unsubscribeData: null,
+          unsubscribeExit: null,
+          hasRunningSubprocess: false,
+          childCommandLabel: null,
+          runtimeEnv: normalizedRuntimeEnv(input.env),
+        };
+        const createdSession = session;
+        yield* modifyManagerState((state) => {
+          const sessions = new Map(state.sessions);
+          sessions.set(sessionKey, createdSession);
+          return [undefined, { ...state, sessions }] as const;
+        });
+        yield* evictInactiveSessionsIfNeeded();
+      } else {
+        session = existingSession.value;
+        yield* stopProcess(session);
+        session.cwd = input.cwd;
+        session.worktreePath = input.worktreePath ?? null;
+        session.runtimeEnv = normalizedRuntimeEnv(input.env);
+      }
+
+      const cols = input.cols ?? session.cols;
+      const rows = input.rows ?? session.rows;
+
+      session.history.clear();
+      session.pendingHistoryControlSequence = "";
+      session.pendingProcessEvents = [];
+      session.pendingProcessEventIndex = 0;
+      session.processEventDrainRunning = false;
+      yield* persistHistory(input.threadId, terminalId, session.history);
+      yield* startSession(
+        session,
+        {
+          threadId: input.threadId,
+          terminalId,
+          cwd: input.cwd,
+          ...(input.worktreePath !== undefined ? { worktreePath: input.worktreePath } : {}),
+          cols,
+          rows,
+          ...(input.env ? { env: input.env } : {}),
+        },
+        "restarted",
+      );
+      return snapshot(session);
+    });
+
   const restart: TerminalManager["Service"]["restart"] = (input) =>
     withThreadLock(
       input.threadId,
-      Effect.gen(function* () {
-        yield* increment(terminalRestartsTotal, { scope: "thread" });
-        const terminalId = input.terminalId;
-        yield* assertValidCwd(input.cwd);
-
-        const sessionKey = toSessionKey(input.threadId, terminalId);
-        const existingSession = yield* getSession(input.threadId, terminalId);
-        let session: TerminalSessionState;
-        if (Option.isNone(existingSession)) {
-          const cols = input.cols ?? DEFAULT_OPEN_COLS;
-          const rows = input.rows ?? DEFAULT_OPEN_ROWS;
-          session = {
-            threadId: input.threadId,
-            terminalId,
-            cwd: input.cwd,
-            worktreePath: input.worktreePath ?? null,
-            status: "starting",
-            pid: null,
-            history: "",
-            pendingHistoryControlSequence: "",
-            pendingProcessEvents: [],
-            pendingProcessEventIndex: 0,
-            processEventDrainRunning: false,
-            exitCode: null,
-            exitSignal: null,
-            updatedAt: yield* nowIso,
-            eventSequence: 0,
-            cols,
-            rows,
-            process: null,
-            unsubscribeData: null,
-            unsubscribeExit: null,
-            hasRunningSubprocess: false,
-            childCommandLabel: null,
-            runtimeEnv: normalizedRuntimeEnv(input.env),
-          };
-          const createdSession = session;
-          yield* modifyManagerState((state) => {
-            const sessions = new Map(state.sessions);
-            sessions.set(sessionKey, createdSession);
-            return [undefined, { ...state, sessions }] as const;
-          });
-          yield* evictInactiveSessionsIfNeeded();
-        } else {
-          session = existingSession.value;
-          yield* stopProcess(session);
-          session.cwd = input.cwd;
-          session.worktreePath = input.worktreePath ?? null;
-          session.runtimeEnv = normalizedRuntimeEnv(input.env);
-        }
-
-        const cols = input.cols ?? session.cols;
-        const rows = input.rows ?? session.rows;
-
-        session.history = "";
-        session.pendingHistoryControlSequence = "";
-        session.pendingProcessEvents = [];
-        session.pendingProcessEventIndex = 0;
-        session.processEventDrainRunning = false;
-        yield* persistHistory(input.threadId, terminalId, session.history);
-        yield* startSession(
-          session,
-          {
-            threadId: input.threadId,
-            terminalId,
-            cwd: input.cwd,
-            ...(input.worktreePath !== undefined ? { worktreePath: input.worktreePath } : {}),
-            cols,
-            rows,
-            ...(input.env ? { env: input.env } : {}),
-          },
-          "restarted",
-        );
-        return snapshot(session);
-      }),
+      resolveLaunchInputEnvironment(input).pipe(Effect.flatMap(restartResolved)),
     );
 
   const close: TerminalManager["Service"]["close"] = (input) =>
diff --git a/apps/server/src/testUtils/fakeCli.ts b/apps/server/src/testUtils/fakeCli.ts
new file mode 100644
index 000000000000..68ab157aed7a
--- /dev/null
+++ b/apps/server/src/testUtils/fakeCli.ts
@@ -0,0 +1,106 @@
+// @effect-diagnostics nodeBuiltinImport:off preferSchemaOverJson:off - synchronous fixture writer used from plain and Effect tests alike.
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+
+export interface FakeCliOptions {
+  /** Directory the launcher and its stub are written into. */
+  readonly directory: string;
+  /** Command name as callers spawn it, e.g. `codex`. */
+  readonly name: string;
+  /** ES module source the launcher runs with `node`. `process.argv.slice(2)` carries the CLI args. */
+  readonly source: string;
+  /** Environment set for the stub before it runs, on top of the inherited environment. */
+  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * Platform the launcher is shaped for. Effect callers should pass the value
+   * they read from `HostProcessPlatform` so an injected override is honoured;
+   * defaults to the real host for plain tests.
+   */
+  readonly platform?: NodeJS.Platform;
+}
+
+/**
+ * Writes a fake CLI whose behaviour lives in a Node stub. On posix the
+ * launcher is a `#!/bin/sh` script; on Windows it is a `.cmd` shim, since a
+ * shebang file is not executable there and `resolveSpawnCommand` routes
+ * `.cmd` through a shell. Returns the launcher path to hand to the code under
+ * test, which on Windows carries the `.cmd` extension.
+ */
+export function writeFakeCli(options: FakeCliOptions): string {
+  NodeFS.mkdirSync(options.directory, { recursive: true });
+  const stubPath = NodePath.join(options.directory, `${options.name}-stub.mjs`);
+  // The environment rides in a JSON sidecar the stub applies to itself, since
+  // neither sh nor cmd.exe can quote every value (newlines, quotes, `%`) safely.
+  const envPath = NodePath.join(options.directory, `${options.name}-env.json`);
+  NodeFS.writeFileSync(envPath, JSON.stringify(options.env ?? {}), "utf8");
+  NodeFS.writeFileSync(
+    stubPath,
+    [
+      'import { readFileSync as readFakeCliEnv } from "node:fs";',
+      `Object.assign(process.env, JSON.parse(readFakeCliEnv(${JSON.stringify(envPath)}, "utf8")));`,
+      options.source,
+    ].join("\n"),
+    "utf8",
+  );
+
+  if ((options.platform ?? HostProcessPlatform.defaultValue()) === "win32") {
+    const launcherPath = NodePath.join(options.directory, `${options.name}.cmd`);
+    NodeFS.writeFileSync(
+      launcherPath,
+      ["@echo off", `node "%~dp0${options.name}-stub.mjs" %*`, "exit /b %ERRORLEVEL%", ""].join(
+        "\r\n",
+      ),
+      "utf8",
+    );
+    return launcherPath;
+  }
+
+  const launcherPath = NodePath.join(options.directory, options.name);
+  NodeFS.writeFileSync(
+    launcherPath,
+    ["#!/bin/sh", `exec node "$(dirname "$0")/${options.name}-stub.mjs" "$@"`, ""].join("\n"),
+    "utf8",
+  );
+  NodeFS.chmodSync(launcherPath, 0o755);
+  return launcherPath;
+}
+
+/**
+ * Stub source that becomes `scriptPath`: after optionally requiring a leading
+ * argv prefix, it imports the script into its own process so the stub is the
+ * agent. Nothing sits between the code under test and the mock, so a kill or
+ * a closed stdin reaches it directly and its exit log is faithful on every
+ * host. The script must not read `process.argv`; the mock agents are driven
+ * by environment and stdin.
+ */
+export function execScriptSource(options: {
+  readonly scriptPath: string;
+  readonly expectedArgs?: ReadonlyArray<string>;
+  /** Tab-separated argv appended here per invocation, for launch-flag assertions. */
+  readonly argvLogPath?: string;
+  /** Wait before handing over, for tests that race a slow startup. */
+  readonly delayMs?: number;
+}): string {
+  return [
+    'import { appendFileSync } from "node:fs";',
+    'import { pathToFileURL } from "node:url";',
+    "const args = process.argv.slice(2);",
+    ...(options.argvLogPath === undefined
+      ? []
+      : [
+          `appendFileSync(${JSON.stringify(options.argvLogPath)}, args.join(${JSON.stringify("\t")}) + ${JSON.stringify("\n")});`,
+        ]),
+    ...(options.delayMs === undefined
+      ? []
+      : [`Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ${options.delayMs});`]),
+    `const expected = ${JSON.stringify(options.expectedArgs ?? [])};`,
+    "if (expected.some((value, index) => args[index] !== value)) {",
+    '  process.stderr.write(`unexpected args: ${args.join(" ")}\\n`);',
+    "  process.exit(11);",
+    "}",
+    `await import(pathToFileURL(${JSON.stringify(options.scriptPath)}).href);`,
+    "",
+  ].join("\n");
+}
diff --git a/apps/server/src/testUtils/gitConfig.setup.ts b/apps/server/src/testUtils/gitConfig.setup.ts
new file mode 100644
index 000000000000..03bd860bf0d0
--- /dev/null
+++ b/apps/server/src/testUtils/gitConfig.setup.ts
@@ -0,0 +1,21 @@
+// Pins git behaviour for every repository the suite creates, ahead of the
+// host's ~/.gitconfig. Git for Windows installs with core.autocrlf=true,
+// which checks committed LF files out as CRLF and breaks every byte-exact
+// content assertion; a signing key or a non-default init branch on the
+// developer's machine breaks fixtures the same way. Set as environment so
+// each git child the driver spawns sees it without touching the fixtures.
+const entries: ReadonlyArray<readonly [key: string, value: string]> = [
+  ["core.autocrlf", "false"],
+  ["core.filemode", "false"],
+  ["core.longpaths", "true"],
+  ["commit.gpgsign", "false"],
+  ["tag.gpgsign", "false"],
+  ["init.defaultBranch", "main"],
+];
+
+const existing = Number(process.env.GIT_CONFIG_COUNT ?? "0");
+process.env.GIT_CONFIG_COUNT = String(existing + entries.length);
+entries.forEach(([key, value], index) => {
+  process.env[`GIT_CONFIG_KEY_${existing + index}`] = key;
+  process.env[`GIT_CONFIG_VALUE_${existing + index}`] = value;
+});
diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
index 8dcaa3720295..fe95c8649ea3 100644
--- a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
@@ -1,7 +1,7 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it } from "@effect/vitest";
 import { ClaudeSettings, ProviderInstanceId } from "@t3tools/contracts";
-import { isHostWindows } from "@t3tools/shared/hostProcess";
+import { HostProcessPlatform, isHostWindows } from "@t3tools/shared/hostProcess";
 import { createModelSelection } from "@t3tools/shared/model";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
@@ -21,27 +21,26 @@ import {
 import * as TextGeneration from "./TextGeneration.ts";
 import { sanitizeThreadTitle } from "./TextGenerationUtils.ts";
 import { makeClaudeTextGeneration } from "./ClaudeTextGeneration.ts";
+import { writeFakeCli } from "../testUtils/fakeCli.ts";
 const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
 
 const ClaudeTextGenerationTestLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {
   prefix: "t3code-claude-text-generation-test-",
 }).pipe(Layer.provideMerge(NodeServices.layer));
 
+// The stub behaviour lives in Node so the same implementation runs on Windows,
+// where a shebang file is not executable and would fall through to the real
+// Claude CLI on PATH; `writeFakeCli` picks the launcher shape per host.
 function makeFakeClaudeBinary(dir: string) {
   return Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const isWindows = yield* isHostWindows;
+    const platform = yield* HostProcessPlatform;
     const binDir = path.join(dir, "bin");
-    const stubPath = path.join(binDir, "claude-stub.mjs");
-    yield* fs.makeDirectory(binDir, { recursive: true });
-
-    // The stub behaviour lives in Node rather than a `#!/bin/sh` script so the
-    // same implementation is usable on Windows, where a shebang file is not
-    // executable and would fall through to the real Claude CLI on PATH.
-    yield* fs.writeFileString(
-      stubPath,
-      [
+    writeFakeCli({
+      directory: binDir,
+      name: "claude",
+      platform,
+      source: [
         'const args = process.argv.slice(2).join(" ");',
         "",
         "function fail(message, code) {",
@@ -87,24 +86,7 @@ function makeFakeClaudeBinary(dir: string) {
         "process.exitCode = Number(process.env.T3_FAKE_CLAUDE_EXIT_CODE ?? 0);",
         "",
       ].join("\n"),
-    );
-
-    if (isWindows) {
-      // Windows resolves executables through PATHEXT, so the entry point has to
-      // carry a real extension. `resolveSpawnCommand` spawns `.cmd` via a shell.
-      yield* fs.writeFileString(
-        path.join(binDir, "claude.cmd"),
-        ["@echo off", 'node "%~dp0claude-stub.mjs" %*', "exit /b %ERRORLEVEL%", ""].join("\r\n"),
-      );
-    } else {
-      const claudePath = path.join(binDir, "claude");
-      yield* fs.writeFileString(
-        claudePath,
-        ["#!/bin/sh", 'exec node "$(dirname "$0")/claude-stub.mjs" "$@"', ""].join("\n"),
-      );
-      yield* fs.chmod(claudePath, 0o755);
-    }
-
+    });
     return binDir;
   });
 }
diff --git a/apps/server/src/textGeneration/CodexTextGeneration.test.ts b/apps/server/src/textGeneration/CodexTextGeneration.test.ts
index 657118fff51c..0129136d5e8d 100644
--- a/apps/server/src/textGeneration/CodexTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/CodexTextGeneration.test.ts
@@ -14,6 +14,7 @@ import { CodexSettings, ProviderInstanceId, TextGenerationError } from "@t3tools
 import * as ServerConfig from "../config.ts";
 import * as TextGeneration from "./TextGeneration.ts";
 import { makeCodexTextGeneration } from "./CodexTextGeneration.ts";
+import { writeFakeCli } from "../testUtils/fakeCli.ts";
 const decodeCodexSettings = Schema.decodeSync(CodexSettings);
 
 const DEFAULT_TEST_MODEL_SELECTION = createModelSelection(
@@ -25,170 +26,112 @@ const CodexTextGenerationTestLayer = ServerConfig.ServerConfig.layerTest(process
   prefix: "t3code-codex-text-generation-test-",
 }).pipe(Layer.provideMerge(NodeServices.layer));
 
-function makeFakeCodexBinary(
-  dir: string,
-  input: {
-    output: string;
-    exitCode?: number;
-    stderr?: string;
-    requireImage?: boolean;
-    requireServiceTier?: string;
-    requireReasoningEffort?: string;
-    forbidReasoningEffort?: boolean;
-    requireArg?: string;
-    forbidArg?: string;
-    stdinMustContain?: string;
-    stdinMustNotContain?: string;
-  },
-) {
+interface FakeCodexInput {
+  output: string;
+  exitCode?: number;
+  stderr?: string;
+  requireImage?: boolean;
+  requireServiceTier?: string;
+  requireReasoningEffort?: string;
+  forbidReasoningEffort?: boolean;
+  requireArg?: string;
+  forbidArg?: string;
+  stdinMustContain?: string;
+  stdinMustNotContain?: string;
+}
+
+// The stub walks argv the way the shell script it replaced did: `--image`,
+// `--config key=value`, and `--output-last-message <path>` are consumed, the
+// prompt arrives on stdin, and each check exits with its own code so a
+// failing test names the assertion that tripped.
+function makeFakeCodexBinary(dir: string, input: FakeCodexInput) {
+  const check = JSON.stringify({
+    requireImage: input.requireImage ?? false,
+    requireServiceTier: input.requireServiceTier ?? null,
+    requireReasoningEffort: input.requireReasoningEffort ?? null,
+    forbidReasoningEffort: input.forbidReasoningEffort ?? false,
+    requireArg: input.requireArg ?? null,
+    forbidArg: input.forbidArg ?? null,
+    stdinMustContain: input.stdinMustContain ?? null,
+    stdinMustNotContain: input.stdinMustNotContain ?? null,
+    stderr: input.stderr ?? null,
+    output: input.output,
+    exitCode: input.exitCode ?? 0,
+  });
   return Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
-    const binDir = path.join(dir, "bin");
-    const codexPath = path.join(binDir, "codex");
-    yield* fs.makeDirectory(binDir, { recursive: true });
-
-    yield* fs.writeFileString(
-      codexPath,
-      [
-        "#!/bin/sh",
-        'original_args="$*"',
-        'output_path=""',
-        'seen_image="0"',
-        'seen_service_tier=""',
-        'seen_reasoning_effort=""',
-        "while [ $# -gt 0 ]; do",
-        '  if [ "$1" = "--image" ]; then',
-        "    shift",
-        '    if [ -n "$1" ]; then',
-        '      seen_image="1"',
-        "    fi",
-        "    shift",
-        "    continue",
-        "  fi",
-        '  if [ "$1" = "--config" ]; then',
-        "    shift",
-        '    case "$1" in',
-        "      service_tier=*)",
-        '        seen_service_tier="$1"',
-        "        ;;",
-        "    esac",
-        '    case "$1" in',
-        "      model_reasoning_effort=*)",
-        '        seen_reasoning_effort="$1"',
-        "        ;;",
-        "    esac",
-        "    shift",
-        "    continue",
-        "  fi",
-        '  if [ "$1" = "--output-last-message" ]; then',
-        "    shift",
-        '    output_path="$1"',
-        "    shift",
-        "    continue",
-        "  fi",
-        "  shift",
-        "done",
-        'stdin_content="$(cat)"',
-        ...(input.requireArg !== undefined
-          ? [
-              `case " $original_args " in *" ${input.requireArg} "*) ;; *)`,
-              `  printf "%s\\n" "missing arg: ${input.requireArg}" >&2`,
-              `  exit 8`,
-              "esac",
-            ]
-          : []),
-        ...(input.forbidArg !== undefined
-          ? [
-              `case " $original_args " in *" ${input.forbidArg} "*)`,
-              `  printf "%s\\n" "forbidden arg: ${input.forbidArg}" >&2`,
-              `  exit 9`,
-              "esac",
-            ]
-          : []),
-        ...(input.requireImage
-          ? [
-              'if [ "$seen_image" != "1" ]; then',
-              '  printf "%s\\n" "missing --image input" >&2',
-              `  exit 2`,
-              "fi",
-            ]
-          : []),
-        ...(input.requireServiceTier
-          ? [
-              `if [ "$seen_service_tier" != "service_tier=\\"${input.requireServiceTier}\\"" ]; then`,
-              '  printf "%s\\n" "unexpected service tier config: $seen_service_tier" >&2',
-              `  exit 5`,
-              "fi",
-            ]
-          : []),
-        ...(input.requireReasoningEffort !== undefined
-          ? [
-              `if [ "$seen_reasoning_effort" != "model_reasoning_effort=\\"${input.requireReasoningEffort}\\"" ]; then`,
-              '  printf "%s\\n" "unexpected reasoning effort config: $seen_reasoning_effort" >&2',
-              `  exit 6`,
-              "fi",
-            ]
-          : []),
-        ...(input.forbidReasoningEffort
-          ? [
-              'if [ -n "$seen_reasoning_effort" ]; then',
-              '  printf "%s\\n" "reasoning effort config should be omitted: $seen_reasoning_effort" >&2',
-              `  exit 7`,
-              "fi",
-            ]
-          : []),
-        ...(input.stdinMustContain !== undefined
-          ? [
-              // @effect-diagnostics-next-line preferSchemaOverJson:off
-              `if ! printf "%s" "$stdin_content" | grep -F -- ${JSON.stringify(input.stdinMustContain)} >/dev/null; then`,
-              '  printf "%s\\n" "stdin missing expected content" >&2',
-              `  exit 3`,
-              "fi",
-            ]
-          : []),
-        ...(input.stdinMustNotContain !== undefined
-          ? [
-              // @effect-diagnostics-next-line preferSchemaOverJson:off
-              `if printf "%s" "$stdin_content" | grep -F -- ${JSON.stringify(input.stdinMustNotContain)} >/dev/null; then`,
-              '  printf "%s\\n" "stdin contained forbidden content" >&2',
-              `  exit 4`,
-              "fi",
-            ]
-          : []),
-        ...(input.stderr !== undefined
-          ? [
-              // @effect-diagnostics-next-line preferSchemaOverJson:off
-              `printf "%s\\n" ${JSON.stringify(input.stderr)} >&2`,
-            ]
-          : []),
-        'if [ -n "$output_path" ]; then',
-        "  cat > \"$output_path\" <<'__T3CODE_FAKE_CODEX_OUTPUT__'",
-        input.output,
-        "__T3CODE_FAKE_CODEX_OUTPUT__",
-        "fi",
-        `exit ${input.exitCode ?? 0}`,
+    return writeFakeCli({
+      directory: path.join(dir, "bin"),
+      name: "codex",
+      source: [
+        'import * as NodeFS from "node:fs";',
+        `const check = ${check};`,
+        "const args = process.argv.slice(2);",
+        'const originalArgs = ` ${args.join(" ")} `;',
+        "let outputPath = null;",
+        "let seenImage = false;",
+        'let seenServiceTier = "";',
+        'let seenReasoningEffort = "";',
+        "for (let index = 0; index < args.length; index += 1) {",
+        '  if (args[index] === "--image") {',
+        "    index += 1;",
+        "    if (args[index]) seenImage = true;",
+        '  } else if (args[index] === "--config") {',
+        "    index += 1;",
+        '    const value = args[index] ?? "";',
+        '    if (value.startsWith("service_tier=")) seenServiceTier = value;',
+        '    if (value.startsWith("model_reasoning_effort=")) seenReasoningEffort = value;',
+        '  } else if (args[index] === "--output-last-message") {',
+        "    index += 1;",
+        "    outputPath = args[index] ?? null;",
+        "  }",
+        "}",
+        "const chunks = [];",
+        "for await (const chunk of process.stdin) chunks.push(chunk);",
+        'const stdinContent = Buffer.concat(chunks).toString("utf8");',
+        "function fail(message, code) {",
+        '  process.stderr.write(message + "\\n");',
+        "  process.exit(code);",
+        "}",
+        "if (check.requireArg !== null && !originalArgs.includes(` ${check.requireArg} `)) {",
+        '  fail("missing arg: " + check.requireArg, 8);',
+        "}",
+        "if (check.forbidArg !== null && originalArgs.includes(` ${check.forbidArg} `)) {",
+        '  fail("forbidden arg: " + check.forbidArg, 9);',
+        "}",
+        'if (check.requireImage && !seenImage) fail("missing --image input", 2);',
+        "if (",
+        "  check.requireServiceTier !== null &&",
+        '  seenServiceTier !== `service_tier="${check.requireServiceTier}"`',
+        ") {",
+        '  fail("unexpected service tier config: " + seenServiceTier, 5);',
+        "}",
+        "if (",
+        "  check.requireReasoningEffort !== null &&",
+        '  seenReasoningEffort !== `model_reasoning_effort="${check.requireReasoningEffort}"`',
+        ") {",
+        '  fail("unexpected reasoning effort config: " + seenReasoningEffort, 6);',
+        "}",
+        "if (check.forbidReasoningEffort && seenReasoningEffort.length > 0) {",
+        '  fail("reasoning effort config should be omitted: " + seenReasoningEffort, 7);',
+        "}",
+        "if (check.stdinMustContain !== null && !stdinContent.includes(check.stdinMustContain)) {",
+        '  fail("stdin missing expected content", 3);',
+        "}",
+        "if (check.stdinMustNotContain !== null && stdinContent.includes(check.stdinMustNotContain)) {",
+        '  fail("stdin contained forbidden content", 4);',
+        "}",
+        'if (check.stderr !== null) process.stderr.write(check.stderr + "\\n");',
+        'if (outputPath !== null) NodeFS.writeFileSync(outputPath, check.output + "\\n");',
+        "process.exitCode = check.exitCode;",
         "",
       ].join("\n"),
-    );
-    yield* fs.chmod(codexPath, 0o755);
-    return codexPath;
+    });
   });
 }
 
 function withFakeCodexEnv<A, E, R>(
-  input: {
-    output: string;
-    exitCode?: number;
-    stderr?: string;
-    requireImage?: boolean;
-    requireServiceTier?: string;
-    requireReasoningEffort?: string;
-    forbidReasoningEffort?: boolean;
-    requireArg?: string;
-    forbidArg?: string;
-    stdinMustContain?: string;
-    stdinMustNotContain?: string;
+  input: FakeCodexInput & {
     launchArgs?: string;
     environment?: NodeJS.ProcessEnv;
   },
diff --git a/apps/server/src/textGeneration/CursorTextGeneration.test.ts b/apps/server/src/textGeneration/CursorTextGeneration.test.ts
index 2dc4720dcadb..22baa75fb8ed 100644
--- a/apps/server/src/textGeneration/CursorTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/CursorTextGeneration.test.ts
@@ -11,6 +11,7 @@ import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { createModelSelection } from "@t3tools/shared/model";
 import { expect } from "vite-plus/test";
 
@@ -19,39 +20,26 @@ import { CursorSettings, ProviderInstanceId } from "@t3tools/contracts";
 import * as ServerConfig from "../config.ts";
 import * as TextGeneration from "./TextGeneration.ts";
 import { makeCursorTextGeneration } from "./CursorTextGeneration.ts";
+import { execScriptSource, writeFakeCli } from "../testUtils/fakeCli.ts";
 const decodeCursorSettings = Schema.decodeSync(CursorSettings);
 
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
 const mockAgentPath = NodePath.join(__dirname, "../../scripts/acp-mock-agent.ts");
 
-function shellSingleQuote(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
 const CursorTextGenerationTestLayer = ServerConfig.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 = NodePath.join(dir, "bin");
-  const agentPath = NodePath.join(binDir, "agent");
-  NodeFS.mkdirSync(binDir, { recursive: true });
-  NodeFS.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 node ${JSON.stringify(mockAgentPath)}`,
-      "",
-    ].join("\n"),
-    "utf8",
-  );
-  NodeFS.chmodSync(agentPath, 0o755);
-  return agentPath;
+  return writeFakeCli({
+    directory: NodePath.join(dir, "bin"),
+    name: "agent",
+    env,
+    source: execScriptSource({
+      scriptPath: mockAgentPath,
+      expectedArgs: ["acp"],
+    }),
+  });
 }
 
 function withFakeAcpAgent<A, E, R>(
@@ -236,41 +224,46 @@ it.layer(CursorTextGenerationTestLayer)("CursorTextGeneration", (it) => {
     ),
   );
 
-  it.effect("closes the ACP child process after text generation completes", () => {
-    const exitLogDir = NodeFS.mkdtempSync(
-      NodePath.join(NodeOS.tmpdir(), "t3code-cursor-text-exit-log-"),
-    );
-    const exitLogPath = NodePath.join(exitLogDir, "exit.log");
+  // Closing the runtime on Windows is taskkill /F, which never lets the mock
+  // agent reach its exit handler, so there is no exit log to assert on.
+  it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+    "closes the ACP child process after text generation completes",
+    () => {
+      const exitLogDir = NodeFS.mkdtempSync(
+        NodePath.join(NodeOS.tmpdir(), "t3code-cursor-text-exit-log-"),
+      );
+      const exitLogPath = NodePath.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",
-            },
-          });
+      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");
+            expect(generated.subject).toBe("Close runtime after generation");
 
-          const exitLog = yield* waitForFileContent(exitLogPath);
-          expect(exitLog).toContain("exit:0");
+            const exitLog = yield* waitForFileContent(exitLogPath);
+            expect(exitLog).toContain("exit:0");
 
-          NodeFS.rmSync(exitLogDir, { recursive: true, force: true });
-        }),
-    );
-  });
+            NodeFS.rmSync(exitLogDir, { recursive: true, force: true });
+          }),
+      );
+    },
+  );
 });
diff --git a/apps/server/src/textGeneration/GrokTextGeneration.test.ts b/apps/server/src/textGeneration/GrokTextGeneration.test.ts
index 85127b519b98..e1622c8aaeca 100644
--- a/apps/server/src/textGeneration/GrokTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/GrokTextGeneration.test.ts
@@ -16,39 +16,26 @@ import { GrokSettings, ProviderInstanceId } from "@t3tools/contracts";
 import * as ServerConfig from "../config.ts";
 import * as TextGeneration from "./TextGeneration.ts";
 import { makeGrokTextGeneration } from "./GrokTextGeneration.ts";
+import { execScriptSource, writeFakeCli } from "../testUtils/fakeCli.ts";
 const decodeGrokSettings = Schema.decodeSync(GrokSettings);
 
 const __dirname = NodePath.dirname(NodeURL.fileURLToPath(import.meta.url));
 const mockAgentPath = NodePath.join(__dirname, "../../scripts/acp-mock-agent.ts");
 
-function shellSingleQuote(value: string): string {
-  return `'${value.replaceAll("'", `'"'"'`)}'`;
-}
-
 const GrokTextGenerationTestLayer = ServerConfig.ServerConfig.layerTest(process.cwd(), {
   prefix: "t3code-grok-text-generation-test-",
 }).pipe(Layer.provideMerge(NodeServices.layer));
 
 function makeAcpGrokWrapper(dir: string, env: Record<string, string>): string {
-  const binDir = NodePath.join(dir, "bin");
-  const grokPath = NodePath.join(binDir, "grok");
-  NodeFS.mkdirSync(binDir, { recursive: true });
-  NodeFS.writeFileSync(
-    grokPath,
-    [
-      "#!/bin/sh",
-      ...Object.entries(env).map(([key, value]) => `export ${key}=${shellSingleQuote(value)}`),
-      'if [ "$1" != "agent" ] || [ "$2" != "stdio" ]; then',
-      '  printf "%s\\n" "unexpected args: $*" >&2',
-      "  exit 11",
-      "fi",
-      `exec ${JSON.stringify(process.execPath)} ${JSON.stringify(mockAgentPath)}`,
-      "",
-    ].join("\n"),
-    "utf8",
-  );
-  NodeFS.chmodSync(grokPath, 0o755);
-  return grokPath;
+  return writeFakeCli({
+    directory: NodePath.join(dir, "bin"),
+    name: "grok",
+    env,
+    source: execScriptSource({
+      scriptPath: mockAgentPath,
+      expectedArgs: ["agent", "stdio"],
+    }),
+  });
 }
 
 function withFakeAcpGrok<A, E, R>(
diff --git a/apps/server/src/textGeneration/TextGenerationPrompts.test.ts b/apps/server/src/textGeneration/TextGenerationPrompts.test.ts
index 253d88779827..05f45b4cb3b0 100644
--- a/apps/server/src/textGeneration/TextGenerationPrompts.test.ts
+++ b/apps/server/src/textGeneration/TextGenerationPrompts.test.ts
@@ -146,7 +146,7 @@ describe("buildBranchNamePrompt", () => {
 });
 
 describe("buildThreadTitlePrompt", () => {
-  it("includes the user message and the title guidance rules", () => {
+  it("includes the user message without absent attachment metadata", () => {
     const result = buildThreadTitlePrompt({
       message: "Investigate reconnect regressions after session restore",
     });
@@ -154,18 +154,6 @@ describe("buildThreadTitlePrompt", () => {
     expect(result.prompt).toContain("User message:");
     expect(result.prompt).toContain("Investigate reconnect regressions after session restore");
     expect(result.prompt).not.toContain("Attachment metadata:");
-    expect(result.prompt).toContain(
-      "Generate a title that will help the user recognize this T3 Code thread weeks later.",
-    );
-    expect(result.prompt).toContain(
-      "Title the subject and outcome. Discard incidental instructions.",
-    );
-    expect(result.prompt).toContain(
-      "Name the product change, not the mock, plan, report, branch, or PR used to produce it.",
-    );
-    expect(result.prompt).not.toContain(
-      "Title should summarize the user's request, not restate it verbatim.",
-    );
   });
 
   it("includes attachment metadata when attachments are provided", () => {
@@ -188,24 +176,6 @@ describe("buildThreadTitlePrompt", () => {
     expect(result.prompt).toContain("67890 bytes");
   });
 
-  it.each([
-    { mode: "initial", previousTitle: undefined },
-    { mode: "regeneration", previousTitle: "Open Projects in Desktop App" },
-  ])(
-    "tells the $mode prompt not to title linked PRs from local git history",
-    ({ previousTitle }) => {
-      const result = buildThreadTitlePrompt({
-        message: "$takeover https://github.com/pingdotgg/t3code/pull/8588",
-        ...(previousTitle === undefined ? {} : { previousTitle }),
-      });
-
-      expect(result.prompt).toContain(
-        "Local git history is not evidence of what a linked PR or issue is about.",
-      );
-      expect(result.prompt).toContain('such as "Take Over PR 8588"');
-    },
-  );
-
   it("regenerates from recent thread contents and identifies the previous title", () => {
     const result = buildThreadTitlePrompt({
       message: `USER:\nInvestigate reconnect regressions\n\nASSISTANT:\nThe remaining issue is stale session state`,
@@ -216,15 +186,6 @@ describe("buildThreadTitlePrompt", () => {
       "Regenerate the title for an existing T3 Code thread so the user can recognize it weeks later.",
     );
     expect(result.prompt).toContain('The previous title was "Investigate reconnect regressions".');
-    expect(result.prompt).toContain(
-      "Read the USER messages first. Identify the latest explicit durable goal.",
-    );
-    expect(result.prompt).toContain(
-      "Do not promote one assistant finding into the thread subject unless the user adopts it as a new goal.",
-    );
-    expect(result.prompt).toContain(
-      'A subagent-monitoring review that finds a Codex roster bug remains "Review Subagent Monitoring Risks,"',
-    );
     expect(result.prompt).toContain("Thread contents:");
     expect(result.prompt).toContain("The remaining issue is stale session state");
   });
diff --git a/apps/server/src/usage/UsageService.test.ts b/apps/server/src/usage/UsageService.test.ts
index b17fad18b339..255c7ee0f73b 100644
--- a/apps/server/src/usage/UsageService.test.ts
+++ b/apps/server/src/usage/UsageService.test.ts
@@ -14,9 +14,11 @@ import {
   type UsageSummaryInput,
 } from "@t3tools/contracts";
 import * as Duration from "effect/Duration";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Scheduler from "effect/Scheduler";
 import * as TestClock from "effect/testing/TestClock";
@@ -26,7 +28,7 @@ import * as ServerConfig from "../config.ts";
 import * as ServerSettings from "../serverSettings.ts";
 import * as UsageService from "./UsageService.ts";
 
-function claudeLine(id: number, outputTokens: number): string {
+function claudeLine(id: number, outputTokens: number, model = "claude-fable-5"): string {
   return `${JSON.stringify({
     type: "assistant",
     timestamp: "2026-08-01T10:00:00Z",
@@ -34,7 +36,7 @@ function claudeLine(id: number, outputTokens: number): string {
     sessionId: "session-1",
     message: {
       id: `msg_${id}`,
-      model: "claude-fable-5",
+      model,
       usage: { input_tokens: 10, output_tokens: outputTokens },
     },
   })}\n`;
@@ -101,6 +103,49 @@ function totalOutputTokens(summary: { buckets: readonly { totals: { outputTokens
 }
 
 describe("UsageService", () => {
+  it.live("reprices unchanged transcripts when custom prices are added, edited, or removed", () =>
+    Effect.gen(function* () {
+      const { transcript, settings, home } = yield* setup;
+      yield* Effect.promise(() => NodeFSP.writeFile(transcript, claudeLine(1, 5, "example-model")));
+
+      yield* Effect.gen(function* () {
+        const settingsService = yield* ServerSettings.ServerSettingsService;
+        const service = yield* UsageService.make;
+
+        const original = yield* service.readSummary(WINDOW);
+        assert.strictEqual(original.buckets[0]?.costUsd, 0);
+        assert.strictEqual(original.buckets[0]?.unpricedRecords, 1);
+
+        yield* settingsService.updateSettings({
+          usagePriceOverrides: {
+            "example-model": { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 },
+          },
+        });
+        const overridden = yield* service.readSummary(WINDOW);
+        assert.closeTo(overridden.buckets[0]?.costUsd ?? -1, 0.00006, 1e-12);
+        assert.strictEqual(overridden.buckets[0]?.costSource, "modelPriced");
+        assert.strictEqual(overridden.buckets[0]?.unpricedRecords, 0);
+        assert.deepStrictEqual(overridden.buckets[0]?.totals, original.buckets[0]?.totals);
+
+        yield* settingsService.updateSettings({
+          usagePriceOverrides: {
+            "example-model": { inputCostPerMillionTokens: 4, outputCostPerMillionTokens: 16 },
+          },
+        });
+        const edited = yield* service.readSummary(WINDOW);
+        assert.closeTo(edited.buckets[0]?.costUsd ?? -1, 0.00012, 1e-12);
+
+        yield* settingsService.updateSettings({ usagePriceOverrides: { "example-model": null } });
+        const restored = yield* service.readSummary(WINDOW);
+        assert.deepStrictEqual(restored.buckets, original.buckets);
+      }).pipe(
+        Effect.provide(
+          serviceLayers({ prefix: "usage-service-price-overrides-test", home, settings }),
+        ),
+      );
+    }).pipe(Effect.scoped),
+  );
+
   it.live("counts appended usage on a rescan of a grown transcript", () =>
     Effect.gen(function* () {
       const { transcript, settings, home } = yield* setup;
@@ -119,6 +164,65 @@ describe("UsageService", () => {
     }).pipe(Effect.scoped),
   );
 
+  it.live("does not share an in-flight scan after custom prices change", () =>
+    Effect.gen(function* () {
+      const { transcript, settings, home } = yield* setup;
+      yield* Effect.promise(() => NodeFSP.writeFile(transcript, claudeLine(1, 5, "example-model")));
+
+      yield* Effect.gen(function* () {
+        const settingsService = yield* ServerSettings.ServerSettingsService;
+        const fileSystem = yield* FileSystem.FileSystem;
+        const firstScanStarted = yield* Deferred.make<void>();
+        const secondScanStarted = yield* Deferred.make<void>();
+        const releaseRates = yield* Deferred.make<void>();
+        let homeProbes = 0;
+        const service = yield* UsageService.make.pipe(
+          Effect.provideService(FileSystem.FileSystem, {
+            ...fileSystem,
+            exists: (path) =>
+              fileSystem.exists(path).pipe(
+                Effect.tap(() => {
+                  if (path !== NodePath.join(home, "claude", ".claude", "projects"))
+                    return Effect.void;
+                  homeProbes += 1;
+                  return Deferred.succeed(
+                    homeProbes === 1 ? firstScanStarted : secondScanStarted,
+                    undefined,
+                  );
+                }),
+              ),
+          }),
+          Effect.provideService(
+            HttpClient.HttpClient,
+            HttpClient.make((request) =>
+              Deferred.await(releaseRates).pipe(
+                Effect.as(HttpClientResponse.fromWeb(request, Response.json({}))),
+              ),
+            ),
+          ),
+        );
+
+        const first = yield* service.readSummary(WINDOW).pipe(Effect.forkChild);
+        yield* Deferred.await(firstScanStarted);
+        yield* settingsService.updateSettings({
+          usagePriceOverrides: {
+            "example-model": { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 },
+          },
+        });
+        const second = yield* service.readSummary(WINDOW).pipe(Effect.forkChild);
+        yield* Deferred.await(secondScanStarted);
+        yield* Deferred.succeed(releaseRates, undefined);
+
+        const original = yield* Fiber.join(first);
+        const updated = yield* Fiber.join(second);
+        assert.strictEqual(original.buckets[0]?.costUsd, 0);
+        assert.closeTo(updated.buckets[0]?.costUsd ?? -1, 0.00006, 1e-12);
+      }).pipe(
+        Effect.provide(serviceLayers({ prefix: "usage-service-price-race-test", home, settings })),
+      );
+    }).pipe(Effect.scoped),
+  );
+
   it.live("shares one scan between concurrent identical requests", () =>
     Effect.gen(function* () {
       const { transcript, settings, home } = yield* setup;
diff --git a/apps/server/src/usage/UsageService.ts b/apps/server/src/usage/UsageService.ts
index 93f0ca780144..7d012f4591ef 100644
--- a/apps/server/src/usage/UsageService.ts
+++ b/apps/server/src/usage/UsageService.ts
@@ -16,6 +16,7 @@ import * as NodeOS from "node:os";
 
 import {
   USAGE_CONTRACT_VERSION,
+  type ServerSettings as ServerSettingsValue,
   type UsageProviderKind,
   type UsageSource,
   type UsagePricing,
@@ -45,7 +46,7 @@ import * as ServerSettings from "../serverSettings.ts";
 import { resolveClaudeHomePath } from "../provider/Drivers/ClaudeHome.ts";
 import { resolveCodexHomeLayout } from "../provider/Drivers/CodexHomeLayout.ts";
 import { UsageAggregator } from "./usageAggregation.ts";
-import { parseRateTable, type RateTable } from "./usagePricing.ts";
+import { createOverrideRateTable, parseRateTable, type RateTable } from "./usagePricing.ts";
 import {
   listTranscriptFiles,
   readDirectoryVolumeId,
@@ -233,24 +234,22 @@ export const make = Effect.gen(function* () {
       return nestedExists ? nested : path.join(homePath, "projects");
     });
 
-  /** Resolves the transcript directory for each provider. */
-  const resolveTranscriptDirs = Effect.fn("UsageService.resolveTranscriptDirs")(function* () {
-    // A settings failure must surface as an error: swallowing it here would
-    // present "zero usage from every provider" as a valid answer.
-    const settings = yield* settingsService.getSettings.pipe(
-      Effect.catchCause(
-        (cause) =>
-          new UsageReadError({
-            reason: "scanFailed",
-            // Bounded description; the squashed failure travels as the cause.
-            // Squashed, not the Cause tree: a full tree in a Defect field is
-            // the unbounded wire payload the bounded detail exists to avoid.
-            detail: "Server settings could not be read.",
-            cause: Cause.squash(cause),
-          }),
-      ),
-    );
+  // A settings failure must not silently discard custom rates or transcript homes.
+  const readSettings = settingsService.getSettings.pipe(
+    Effect.catchCause(
+      (cause) =>
+        new UsageReadError({
+          reason: "scanFailed",
+          detail: "Server settings could not be read.",
+          cause: Cause.squash(cause),
+        }),
+    ),
+  );
 
+  /** Resolves the transcript directory for each provider. */
+  const resolveTranscriptDirs = Effect.fn("UsageService.resolveTranscriptDirs")(function* (
+    settings: ServerSettingsValue,
+  ) {
     const claudeHome = yield* resolveClaudeHomePath(settings.providers.claudeAgent);
     const claudeDir = yield* resolveClaudeTranscriptDir(claudeHome);
     const codexLayout = yield* resolveCodexHomeLayout(settings.providers.codex);
@@ -380,10 +379,15 @@ export const make = Effect.gen(function* () {
       | null;
   }
 
-  const collectDirs = Effect.fn("UsageService.collectDirs")(function* (windowStartMs: number) {
+  const collectDirs = Effect.fn("UsageService.collectDirs")(function* (
+    windowStartMs: number,
+    settings: ServerSettingsValue,
+  ) {
     // The home resolvers ask for `Path` themselves; satisfy them from the
     // instance we already hold so the scan stays context-free.
-    const dirs = yield* resolveTranscriptDirs().pipe(Effect.provideService(Path.Path, path));
+    const dirs = yield* resolveTranscriptDirs(settings).pipe(
+      Effect.provideService(Path.Path, path),
+    );
     const scanned: ScannedDir[] = [];
     for (const { provider, dir, fileName } of dirs) {
       const volumeId = yield* Effect.promise(() => readDirectoryVolumeId(dir));
@@ -407,7 +411,10 @@ export const make = Effect.gen(function* () {
     return scanned;
   });
 
-  const scanSummary = Effect.fn("UsageService.scanSummary")(function* (input: UsageSummaryInput) {
+  const scanSummary = Effect.fn("UsageService.scanSummary")(function* (
+    input: UsageSummaryInput,
+    settings: ServerSettingsValue,
+  ) {
     if (input.sinceDay > input.untilDay) {
       return yield* new UsageReadError({
         reason: "invalidWindow",
@@ -456,9 +463,10 @@ export const make = Effect.gen(function* () {
     // Pricing only matters once records are aggregated, so the rate table
     // loads while transcripts stream instead of gating them: a cold rates
     // fetch on a slow network no longer delays the scan by its own timeout.
-    const [, scannedDirs] = yield* Effect.all([ensureRates(false), collectDirs(windowStartMs)], {
-      concurrency: 2,
-    });
+    const [, scannedDirs] = yield* Effect.all(
+      [ensureRates(false), collectDirs(windowStartMs, settings)],
+      { concurrency: 2 },
+    );
 
     const aggregator = new UsageAggregator({
       timeZone: input.timeZone,
@@ -467,6 +475,7 @@ export const make = Effect.gen(function* () {
       resolution: input.resolution ?? "day",
       ...hourlyWindow,
       rates,
+      priceOverrides: createOverrideRateTable(settings.usagePriceOverrides),
     });
 
     const sources: UsageSource[] = [];
@@ -550,13 +559,16 @@ export const make = Effect.gen(function* () {
   });
 
   /**
-   * In-flight scans by window, so concurrent identical requests (the usage
+   * In-flight scans by window and custom prices, so concurrent identical requests (the usage
    * page open on two clients at once) share one scan instead of racing over
    * the same corpus twice.
    */
   const inflightScans = new Map<string, Deferred.Deferred<UsageSummary, UsageReadError>>();
 
-  const scanKey = (input: UsageSummaryInput): string =>
+  const scanKey = (
+    input: UsageSummaryInput,
+    priceOverrides: ServerSettingsValue["usagePriceOverrides"],
+  ): string =>
     JSON.stringify([
       input.timeZone,
       input.sinceDay,
@@ -564,10 +576,12 @@ export const make = Effect.gen(function* () {
       input.resolution ?? "day",
       input.sinceTime ?? null,
       input.untilTime ?? null,
+      priceOverrides,
     ]);
 
   const readSummary = Effect.fn("UsageService.readSummary")(function* (input: UsageSummaryInput) {
-    const key = scanKey(input);
+    const settings = yield* readSettings;
+    const key = scanKey(input, settings.usagePriceOverrides);
     const deferred = yield* Effect.uninterruptible(
       Effect.gen(function* () {
         const existing = inflightScans.get(key);
@@ -579,7 +593,7 @@ export const make = Effect.gen(function* () {
         inflightScans.set(key, created);
         // Detached so one departing client cannot tear the scan out from under
         // the fibers awaiting it; a finished scan warms the cache either way.
-        yield* scanSummary(input).pipe(
+        yield* scanSummary(input, settings).pipe(
           Effect.onExit((exit) =>
             Effect.sync(() => inflightScans.delete(key)).pipe(
               Effect.andThen(Deferred.done(created, exit)),
diff --git a/apps/server/src/usage/usageAggregation.ts b/apps/server/src/usage/usageAggregation.ts
index e100be76e979..01a1195efb60 100644
--- a/apps/server/src/usage/usageAggregation.ts
+++ b/apps/server/src/usage/usageAggregation.ts
@@ -61,6 +61,7 @@ export interface AggregateOptions {
   readonly sinceDay: string;
   readonly untilDay: string;
   readonly rates: RateTable;
+  readonly priceOverrides?: RateTable;
   readonly resolution?: UsageResolution;
   readonly sinceTimeMs?: number;
   readonly untilTimeMs?: number;
@@ -165,11 +166,17 @@ export class UsageAggregator {
       record.model,
       record.totals,
       record.reportedCostUsd,
+      this.#options.priceOverrides,
     );
 
     bucket.totals = addTotals(bucket.totals, record.totals);
     bucket.costUsd += priced.costUsd;
-    bucket.cacheSavingsUsd += cacheSavingsUsd(this.#options.rates, record.model, record.totals);
+    bucket.cacheSavingsUsd += cacheSavingsUsd(
+      this.#options.rates,
+      record.model,
+      record.totals,
+      this.#options.priceOverrides,
+    );
     bucket.records += 1;
     if (priced.costSource === "unpriced") bucket.unpricedRecords += 1;
     if (priced.costSource === "providerReported") bucket.providerReportedRecords += 1;
diff --git a/apps/server/src/usage/usagePricing.test.ts b/apps/server/src/usage/usagePricing.test.ts
index 45113414f69c..713d860999cb 100644
--- a/apps/server/src/usage/usagePricing.test.ts
+++ b/apps/server/src/usage/usagePricing.test.ts
@@ -1,6 +1,12 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import { lookupRate, normalizeModelName, parseRateTable } from "./usagePricing.ts";
+import {
+  cacheSavingsUsd,
+  createOverrideRateTable,
+  lookupRate,
+  parseRateTable,
+  priceUsage,
+} from "./usagePricing.ts";
 
 const rate = (input: number, cacheRead?: number) => ({
   input_cost_per_token: input,
@@ -9,8 +15,71 @@ const rate = (input: number, cacheRead?: number) => ({
 });
 
 describe("usage pricing", () => {
-  it("keeps the existing model-name normalization contract", () => {
-    expect(normalizeModelName(" Anthropic/Claude-Opus-5 ")).toBe("claude-opus-5");
+  const totals = {
+    uncachedInputTokens: 1_000_000,
+    cachedInputTokens: 1_000_000,
+    cacheCreationTokens: 1_000_000,
+    outputTokens: 1_000_000,
+    reasoningTokens: 500_000,
+  };
+
+  it("uses custom token rates ahead of public and provider-reported costs", () => {
+    const table = parseRateTable({ "example-model": rate(1) });
+    const overrides = createOverrideRateTable({
+      "example-model": {
+        inputCostPerMillionTokens: 2,
+        outputCostPerMillionTokens: 8,
+        cacheReadCostPerMillionTokens: 0.5,
+        cacheWriteCostPerMillionTokens: 3,
+      },
+    });
+
+    for (const reportedCostUsd of [null, 99]) {
+      expect(priceUsage(table, "example-model", totals, reportedCostUsd, overrides)).toEqual({
+        costUsd: 13.5,
+        costSource: "modelPriced",
+      });
+    }
+    expect(cacheSavingsUsd(table, "example-model", totals, overrides)).toBe(1.5);
+  });
+
+  it("prices unknown models offline and uses input prices for omitted cache rates", () => {
+    const table = parseRateTable({});
+    const overrides = createOverrideRateTable({
+      "example-model": { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 },
+    });
+
+    expect(priceUsage(table, "example-model", totals, null, overrides)).toEqual({
+      costUsd: 14,
+      costSource: "modelPriced",
+    });
+    expect(cacheSavingsUsd(table, "example-model", totals, overrides)).toBe(0);
+  });
+
+  it("preserves explicit zero rates and matches only the exact trimmed model ID", () => {
+    const table = parseRateTable({});
+    const overrides = createOverrideRateTable({
+      " vendor/example-model[1m] ": {
+        inputCostPerMillionTokens: 0,
+        outputCostPerMillionTokens: 0,
+      },
+    });
+    expect(priceUsage(table, " vendor/example-model[1m] ", totals, 99, overrides)).toEqual({
+      costUsd: 0,
+      costSource: "modelPriced",
+    });
+    for (const model of [
+      "example-model[1m]",
+      "vendor/example-model",
+      "vendor/Example-model[1m]",
+      "other/example-model[1m]",
+    ]) {
+      expect(priceUsage(table, model, totals, null, overrides).costSource).toBe("unpriced");
+      expect(priceUsage(table, model, totals, 99, overrides)).toEqual({
+        costUsd: 99,
+        costSource: "providerReported",
+      });
+    }
   });
 
   it("keeps the canonical Fable rate separate from DeepInfra in either order", () => {
diff --git a/apps/server/src/usage/usagePricing.ts b/apps/server/src/usage/usagePricing.ts
index a7beecb1f552..6c94be424827 100644
--- a/apps/server/src/usage/usagePricing.ts
+++ b/apps/server/src/usage/usagePricing.ts
@@ -7,7 +7,11 @@
  *
  * @module usagePricing
  */
-import type { UsageCostSource, UsageTokenTotals } from "@t3tools/contracts";
+import type {
+  UsageCostSource,
+  UsageModelPriceOverride,
+  UsageTokenTotals,
+} from "@t3tools/contracts";
 
 /**
  * The subset of a LiteLLM entry we price against. All values are USD per token.
@@ -26,6 +30,25 @@ export interface ModelRate {
 
 export type RateTable = ReadonlyMap<string, ModelRate>;
 
+/** Custom IDs keep their case, provider prefix, and variant suffix. */
+export function createOverrideRateTable(
+  overrides: Readonly<Record<string, UsageModelPriceOverride>>,
+): RateTable {
+  return new Map(
+    Object.entries(overrides).map(([model, prices]) => [
+      model.trim(),
+      {
+        inputCostPerToken: prices.inputCostPerMillionTokens / 1_000_000,
+        outputCostPerToken: prices.outputCostPerMillionTokens / 1_000_000,
+        cacheReadCostPerToken:
+          (prices.cacheReadCostPerMillionTokens ?? prices.inputCostPerMillionTokens) / 1_000_000,
+        cacheCreationCostPerToken:
+          (prices.cacheWriteCostPerMillionTokens ?? prices.inputCostPerMillionTokens) / 1_000_000,
+      },
+    ]),
+  );
+}
+
 /** Raw shape of one LiteLLM entry, narrowed to the fields we read. */
 interface LiteLlmEntry {
   readonly input_cost_per_token?: unknown;
@@ -104,16 +127,6 @@ function normalizeRateKey(model: string): string {
   return model.trim().toLowerCase();
 }
 
-/**
- * Canonicalises a model name for lookup.
- *
- * Strips a `provider/` prefix and lowercases, since transcripts are
- * inconsistent about casing.
- */
-export function normalizeModelName(model: string): string {
-  return bareModelName(normalizeRateKey(model));
-}
-
 function bareModelName(key: string): string {
   const slash = key.lastIndexOf("/");
   return slash === -1 ? key : key.slice(slash + 1);
@@ -168,12 +181,14 @@ export function priceUsage(
   model: string,
   totals: UsageTokenTotals,
   reportedCostUsd: number | null,
+  overrides?: RateTable,
 ): PricedUsage {
-  if (reportedCostUsd !== null && Number.isFinite(reportedCostUsd)) {
+  const override = overrides?.get(model.trim());
+  if (override === undefined && reportedCostUsd !== null && Number.isFinite(reportedCostUsd)) {
     return { costUsd: reportedCostUsd, costSource: "providerReported" };
   }
 
-  const rate = lookupRate(table, model);
+  const rate = override ?? lookupRate(table, model);
   if (rate === null) return { costUsd: 0, costSource: "unpriced" };
 
   const costUsd =
@@ -189,8 +204,13 @@ export function priceUsage(
  * What the cached input would have cost at full input rates, minus what it
  * actually cost. Drives the "cache savings" figure.
  */
-export function cacheSavingsUsd(table: RateTable, model: string, totals: UsageTokenTotals): number {
-  const rate = lookupRate(table, model);
+export function cacheSavingsUsd(
+  table: RateTable,
+  model: string,
+  totals: UsageTokenTotals,
+  overrides?: RateTable,
+): number {
+  const rate = overrides?.get(model.trim()) ?? lookupRate(table, model);
   if (rate === null) return 0;
   return totals.cachedInputTokens * (rate.inputCostPerToken - rate.cacheReadCostPerToken);
 }
diff --git a/apps/server/src/vcs/GitVcsDriver.test.ts b/apps/server/src/vcs/GitVcsDriver.test.ts
index 89f7c55d5863..031055a3b6cb 100644
--- a/apps/server/src/vcs/GitVcsDriver.test.ts
+++ b/apps/server/src/vcs/GitVcsDriver.test.ts
@@ -68,6 +68,7 @@ runVcsDriverContractSuite<GitVcsDriver.GitVcsDriver, GitContractError>({
 it.effect("GitVcsDriver forwards execute env to the VCS process", () => {
   let observedEnv: NodeJS.ProcessEnv | undefined;
   let observedAppendTruncationMarker: boolean | undefined;
+  let observedOutputMode: VcsProcess.VcsProcessInput["outputMode"];
 
   return Effect.gen(function* () {
     const driver = yield* GitVcsDriver.makeVcsDriverShape();
@@ -80,12 +81,14 @@ it.effect("GitVcsDriver forwards execute env to the VCS process", () => {
         GIT_INDEX_FILE: "/tmp/t3-index",
       },
       appendTruncationMarker: true,
+      outputMode: "error",
     });
 
     assert.deepStrictEqual(observedEnv, {
       GIT_INDEX_FILE: "/tmp/t3-index",
     });
     assert.strictEqual(observedAppendTruncationMarker, true);
+    assert.strictEqual(observedOutputMode, "error");
   }).pipe(
     Effect.provide(
       Layer.mergeAll(
@@ -95,6 +98,7 @@ it.effect("GitVcsDriver forwards execute env to the VCS process", () => {
             Effect.sync(() => {
               observedEnv = input.env;
               observedAppendTruncationMarker = input.appendTruncationMarker;
+              observedOutputMode = input.outputMode;
               return {
                 exitCode: ChildProcessSpawner.ExitCode(0),
                 stdout: "",
diff --git a/apps/server/src/vcs/GitVcsDriver.ts b/apps/server/src/vcs/GitVcsDriver.ts
index 08b474cf42da..f1e48a24d6fe 100644
--- a/apps/server/src/vcs/GitVcsDriver.ts
+++ b/apps/server/src/vcs/GitVcsDriver.ts
@@ -431,6 +431,7 @@ const gitCommand = (
     readonly allowNonZeroExit?: boolean;
     readonly timeoutMs?: number;
     readonly maxOutputBytes?: number;
+    readonly outputMode?: VcsProcess.VcsProcessInput["outputMode"];
     readonly appendTruncationMarker?: boolean;
   },
 ) =>
@@ -447,6 +448,7 @@ const gitCommand = (
       : {}),
     ...(options?.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
     ...(options?.maxOutputBytes !== undefined ? { maxOutputBytes: options.maxOutputBytes } : {}),
+    ...(options?.outputMode !== undefined ? { outputMode: options.outputMode } : {}),
     ...(options?.appendTruncationMarker !== undefined
       ? { appendTruncationMarker: options.appendTruncationMarker }
       : {}),
@@ -485,6 +487,7 @@ export const makeVcsDriverShape = Effect.fn("makeGitVcsDriverShape")(function* (
       ...(input.allowNonZeroExit !== undefined ? { allowNonZeroExit: input.allowNonZeroExit } : {}),
       ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
       ...(input.maxOutputBytes !== undefined ? { maxOutputBytes: input.maxOutputBytes } : {}),
+      ...(input.outputMode !== undefined ? { outputMode: input.outputMode } : {}),
       ...(input.appendTruncationMarker !== undefined
         ? { appendTruncationMarker: input.appendTruncationMarker }
         : {}),
@@ -838,6 +841,7 @@ export const makeVcsDriverShape = Effect.fn("makeGitVcsDriverShape")(function* (
         "checkpoint.from_ref": input.fromCheckpointRef,
         "checkpoint.to_ref": input.toCheckpointRef,
         "checkpoint.ignore_whitespace": input.ignoreWhitespace,
+        "checkpoint.format": input.format ?? "patch",
         "checkpoint.fallback_from_to_head": input.fallbackFromToHead,
       });
 
@@ -869,7 +873,7 @@ export const makeVcsDriverShape = Effect.fn("makeGitVcsDriverShape")(function* (
         cwd: input.cwd,
         args: [
           "diff",
-          "--patch",
+          ...(input.format === "numstat" ? ["--numstat", "-z"] : ["--patch"]),
           "--no-color",
           "--no-ext-diff",
           "--no-textconv",
@@ -880,6 +884,7 @@ export const makeVcsDriverShape = Effect.fn("makeGitVcsDriverShape")(function* (
         ],
         allowNonZeroExit: true,
         maxOutputBytes: CHECKPOINT_DIFF_MAX_OUTPUT_BYTES,
+        outputMode: input.format === "numstat" ? "error" : "truncate",
       });
 
       if (result.exitCode !== 0) {
diff --git a/apps/server/src/vcs/GitVcsDriverCore.test.ts b/apps/server/src/vcs/GitVcsDriverCore.test.ts
index 75f69de952c1..b2400f68779c 100644
--- a/apps/server/src/vcs/GitVcsDriverCore.test.ts
+++ b/apps/server/src/vcs/GitVcsDriverCore.test.ts
@@ -1,4 +1,7 @@
+// @effect-diagnostics nodeBuiltinImport:off - realpathSync.native resolves Windows 8.3 short names, which the Effect realPath does not.
+import * as NodeFS from "node:fs";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { assert, it, describe } from "@effect/vitest";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
@@ -570,7 +573,6 @@ it.effect("backs off failed upstream refreshes across linked worktrees", () =>
       const driver = yield* makeGitVcsDriverCore().pipe(
         Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, failingFetchSpawner),
       );
-      const fileSystem = yield* FileSystem.FileSystem;
       const cwd = yield* makeTmpDir();
       const remote = yield* makeTmpDir("git-vcs-driver-remote-");
       const worktreesRoot = yield* makeTmpDir("git-vcs-driver-worktrees-");
@@ -606,9 +608,11 @@ it.effect("backs off failed upstream refreshes across linked worktrees", () =>
         "rev-parse",
         "--git-common-dir",
       ])).stdout.trim();
+      // Native realpath, since git reports the long form of a directory the
+      // temp dir may name by its 8.3 short form on Windows.
       assert.equal(
-        yield* fileSystem.realPath(pathService.resolve(cwd, rootCommonDir)),
-        yield* fileSystem.realPath(pathService.resolve(worktreePath, linkedCommonDir)),
+        NodeFS.realpathSync.native(pathService.resolve(cwd, rootCommonDir)),
+        NodeFS.realpathSync.native(pathService.resolve(worktreePath, linkedCommonDir)),
       );
       yield* Ref.set(fetchAttempts, 0);
 
@@ -1376,31 +1380,33 @@ it.layer(TestLayer)("GitVcsDriver core integration", (it) => {
   });
 
   describe("worktree operations", () => {
-    it.effect("preserves newline characters in worktree paths when listing refs", () =>
-      Effect.gen(function* () {
-        const cwd = yield* makeTmpDir();
-        yield* initRepoWithCommit(cwd);
-        const worktreesRoot = yield* makeTmpDir("git-vcs-driver-worktrees-");
-        const fileSystem = yield* FileSystem.FileSystem;
-        const pathService = yield* Path.Path;
-        const worktreePath = pathService.join(worktreesRoot, "linked\nworktree");
-        const driver = yield* GitVcsDriver.GitVcsDriver;
+    // NTFS rejects a newline in a file name, so there is nothing to preserve there.
+    it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+      "preserves newline characters in worktree paths when listing refs",
+      () =>
+        Effect.gen(function* () {
+          const cwd = yield* makeTmpDir();
+          yield* initRepoWithCommit(cwd);
+          const worktreesRoot = yield* makeTmpDir("git-vcs-driver-worktrees-");
+          const pathService = yield* Path.Path;
+          const worktreePath = pathService.join(worktreesRoot, "linked\nworktree");
+          const driver = yield* GitVcsDriver.GitVcsDriver;
 
-        yield* git(cwd, ["worktree", "add", "-b", "feature/newline-path", worktreePath]);
+          yield* git(cwd, ["worktree", "add", "-b", "feature/newline-path", worktreePath]);
 
-        const refs = yield* driver.listRefs({ cwd, refresh: true });
-        const listedPath = refs.refs.find(
-          (ref) => ref.name === "feature/newline-path",
-        )?.worktreePath;
+          const refs = yield* driver.listRefs({ cwd, refresh: true });
+          const listedPath = refs.refs.find(
+            (ref) => ref.name === "feature/newline-path",
+          )?.worktreePath;
 
-        if (typeof listedPath !== "string") {
-          return assert.fail("expected the linked branch to include its worktree path");
-        }
-        assert.equal(
-          yield* fileSystem.realPath(listedPath),
-          yield* fileSystem.realPath(worktreePath),
-        );
-      }),
+          if (typeof listedPath !== "string") {
+            return assert.fail("expected the linked branch to include its worktree path");
+          }
+          assert.equal(
+            NodeFS.realpathSync.native(listedPath),
+            NodeFS.realpathSync.native(worktreePath),
+          );
+        }),
     );
 
     it.effect("checks out submodules in a new worktree", () =>
diff --git a/apps/server/src/vcs/VcsDriver.ts b/apps/server/src/vcs/VcsDriver.ts
index f2daf7935027..a8680c9a54be 100644
--- a/apps/server/src/vcs/VcsDriver.ts
+++ b/apps/server/src/vcs/VcsDriver.ts
@@ -31,6 +31,7 @@ export interface VcsDiffCheckpointsInput {
   readonly toCheckpointRef: CheckpointRef;
   readonly fallbackFromToHead?: boolean;
   readonly ignoreWhitespace: boolean;
+  readonly format?: "patch" | "numstat";
 }
 
 export interface VcsDeleteCheckpointRefsInput {
diff --git a/apps/server/src/vcs/VcsProcess.test.ts b/apps/server/src/vcs/VcsProcess.test.ts
index 91191178c330..ac0ee4428046 100644
--- a/apps/server/src/vcs/VcsProcess.test.ts
+++ b/apps/server/src/vcs/VcsProcess.test.ts
@@ -1,5 +1,6 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { describe, expect, it } from "@effect/vitest";
+import { assert, describe, expect, it } from "@effect/vitest";
+import { HostProcessWorkingDirectory } from "@t3tools/shared/hostProcess";
 import * as Duration from "effect/Duration";
 import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
@@ -359,6 +360,24 @@ describe("VcsProcess.run", () => {
     }).pipe(provideLive),
   );
 
+  it.effect("fails with measured byte counts when output must not be truncated", () =>
+    Effect.gen(function* () {
+      const error = yield* run({
+        operation: "test.output-limit",
+        command: "node",
+        args: ["-e", "process.stdout.write('x'.repeat(2048))"],
+        cwd: yield* HostProcessWorkingDirectory,
+        maxOutputBytes: 128,
+        outputMode: "error",
+      }).pipe(Effect.flip);
+
+      assert(error._tag === "VcsProcessOutputLimitError");
+      expect(error.stream).toBe("stdout");
+      expect(error.maxBytes).toBe(128);
+      expect(error.observedBytes).toBeGreaterThan(error.maxBytes);
+    }).pipe(provideLive),
+  );
+
   it.effect("fails with VcsProcessTimeoutError on timeout", () =>
     Effect.gen(function* () {
       const errorFiber = yield* run({
diff --git a/apps/server/src/vcs/VcsProcess.ts b/apps/server/src/vcs/VcsProcess.ts
index 69df83c42025..74608e116eed 100644
--- a/apps/server/src/vcs/VcsProcess.ts
+++ b/apps/server/src/vcs/VcsProcess.ts
@@ -29,6 +29,7 @@ export interface VcsProcessInput {
   readonly allowNonZeroExit?: boolean;
   readonly timeoutMs?: number;
   readonly maxOutputBytes?: number;
+  readonly outputMode?: ProcessRunner.ProcessRunInput["outputMode"];
   readonly appendTruncationMarker?: boolean;
 }
 
@@ -125,7 +126,7 @@ export const make = Effect.gen(function* () {
         ...(input.env !== undefined ? { env: input.env } : {}),
         timeout: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
         maxOutputBytes: input.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES,
-        outputMode: "truncate",
+        outputMode: input.outputMode ?? "truncate",
         truncatedMarker: input.appendTruncationMarker ? OUTPUT_TRUNCATED_MARKER : "",
         timeoutBehavior: "error",
       })
diff --git a/apps/server/src/vcs/VcsProjectConfig.test.ts b/apps/server/src/vcs/VcsProjectConfig.test.ts
index 04f7fcffcda0..88f48e9e8afa 100644
--- a/apps/server/src/vcs/VcsProjectConfig.test.ts
+++ b/apps/server/src/vcs/VcsProjectConfig.test.ts
@@ -14,22 +14,6 @@ const TestLayer = VcsProjectConfig.layer.pipe(
 );
 
 describe("VcsProjectConfig", () => {
-  it("keeps operation context and the original cause on config errors", () => {
-    const cause = new Error("permission denied");
-    const error = new VcsProjectConfig.VcsProjectConfigError({
-      operation: "read",
-      cwd: "/repo/packages/app",
-      configPath: "/repo/.t3code/vcs.json",
-      cause,
-    });
-
-    assert.equal(error.operation, "read");
-    assert.equal(error.cwd, "/repo/packages/app");
-    assert.equal(error.configPath, "/repo/.t3code/vcs.json");
-    assert.strictEqual(error.cause, cause);
-    assert.equal(error.message, "Failed to read VCS project config at /repo/.t3code/vcs.json.");
-  });
-
   it.layer(TestLayer)("uses an explicit requested VCS kind before config", (it) => {
     it.effect("returns the requested kind", () =>
       Effect.gen(function* () {
diff --git a/apps/server/src/vcs/VcsStatusBroadcaster.test.ts b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
index c7d7b79a12e0..ac21a61ddf78 100644
--- a/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
+++ b/apps/server/src/vcs/VcsStatusBroadcaster.test.ts
@@ -27,6 +27,7 @@ import { GitManagerError } from "@t3tools/contracts";
 import * as VcsStatusBroadcaster from "./VcsStatusBroadcaster.ts";
 import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
 import * as GitWorkflowService from "../git/GitWorkflowService.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
 
@@ -144,7 +145,7 @@ function makeBackgroundPolicyLayer(shouldRunScopeWork: (scope: BackgroundScope)
 }
 
 describe("VcsStatusBroadcaster", () => {
-  it.effect(
+  it.effect.skipIf(!symlinksSupported)(
     "automatically pulls an enabled clean default branch when status detects it is behind",
     () => {
       let remoteStatus: VcsStatusRemoteResult = { ...baseRemoteStatus, behindCount: 2 };
@@ -522,67 +523,70 @@ describe("VcsStatusBroadcaster", () => {
     }).pipe(Effect.provide(makeTestLayer(state)));
   });
 
-  it.effect("normalizes symlinked CWDs before cache lookup and workflow calls", () => {
-    const seenCwds: string[] = [];
-    const state = {
-      currentLocalStatus: baseLocalStatus,
-      currentRemoteStatus: baseRemoteStatus,
-      localStatusCalls: 0,
-      remoteStatusCalls: 0,
-      localInvalidationCalls: 0,
-      remoteInvalidationCalls: 0,
-    };
-    const testLayer = VcsStatusBroadcaster.layer.pipe(
-      Layer.provideMerge(NodeServices.layer),
-      Layer.provide(makeBackgroundPolicyLayer(() => true)),
-      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.GitWorkflowService["Service"]>),
-      ),
-    );
+  it.effect.skipIf(!symlinksSupported)(
+    "normalizes symlinked CWDs before cache lookup and workflow calls",
+    () => {
+      const seenCwds: string[] = [];
+      const state = {
+        currentLocalStatus: baseLocalStatus,
+        currentRemoteStatus: baseRemoteStatus,
+        localStatusCalls: 0,
+        remoteStatusCalls: 0,
+        localInvalidationCalls: 0,
+        remoteInvalidationCalls: 0,
+      };
+      const testLayer = VcsStatusBroadcaster.layer.pipe(
+        Layer.provideMerge(NodeServices.layer),
+        Layer.provide(makeBackgroundPolicyLayer(() => true)),
+        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.GitWorkflowService["Service"]>),
+        ),
+      );
 
-    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);
+      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 });
+        const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
+        yield* broadcaster.getStatus({ cwd: linkDir });
+        yield* broadcaster.getStatus({ cwd: realDir });
 
-      assert.deepStrictEqual(seenCwds, [realPath, realPath]);
-      assert.equal(state.localStatusCalls, 1);
-      assert.equal(state.remoteStatusCalls, 1);
-    }).pipe(Effect.provide(testLayer));
-  });
+        assert.deepStrictEqual(seenCwds, [realPath, realPath]);
+        assert.equal(state.localStatusCalls, 1);
+        assert.equal(state.remoteStatusCalls, 1);
+      }).pipe(Effect.provide(testLayer));
+    },
+  );
 
   it.effect("streams a local snapshot first and remote updates later", () => {
     const state = {
diff --git a/apps/server/src/workspace/WorkspaceEntries.test.ts b/apps/server/src/workspace/WorkspaceEntries.test.ts
index d47aaaec8264..ff3343c37138 100644
--- a/apps/server/src/workspace/WorkspaceEntries.test.ts
+++ b/apps/server/src/workspace/WorkspaceEntries.test.ts
@@ -218,7 +218,10 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceEntries", (it) => {
           kind: "file",
         });
 
-        expect(result.entries).toEqual([{ path: "src/index.ts", kind: "file" }]);
+        // Native ranking can put either matching file first.
+        expect(result.entries).toHaveLength(1);
+        expect(result.entries[0]?.kind).toBe("file");
+        expect(["src/index.ts", "src/internal.ts"]).toContain(result.entries[0]?.path);
         expect(result.truncated).toBe(true);
       }),
     );
diff --git a/apps/server/src/workspace/WorkspaceFileSystem.test.ts b/apps/server/src/workspace/WorkspaceFileSystem.test.ts
index 17c7f0bb050c..5afc212ce172 100644
--- a/apps/server/src/workspace/WorkspaceFileSystem.test.ts
+++ b/apps/server/src/workspace/WorkspaceFileSystem.test.ts
@@ -14,6 +14,8 @@ import * as VcsProcess from "../vcs/VcsProcess.ts";
 import * as WorkspaceEntries from "./WorkspaceEntries.ts";
 import * as WorkspaceFileSystem from "./WorkspaceFileSystem.ts";
 import * as WorkspacePaths from "./WorkspacePaths.ts";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const ProjectLayer = WorkspaceFileSystem.layer.pipe(
   Layer.provide(WorkspacePaths.layer),
@@ -99,28 +101,31 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceFileSystemLive", (i
       }),
     );
 
-    it.effect("rejects a FIFO without blocking on open", () =>
-      Effect.gen(function* () {
-        const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
-        const path = yield* Path.Path;
-        const cwd = yield* makeTempDir;
-        const outsideDir = yield* makeTempDir;
-        const fifoPath = path.join(outsideDir, "pipe");
-        yield* Effect.promise(
-          () =>
-            new Promise<void>((resolve, reject) =>
-              NodeChildProcess.execFile("mkfifo", [fifoPath], (error) =>
-                error ? reject(error) : resolve(),
+    // Needs mkfifo; Windows has no FIFOs to reject.
+    it.effect.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+      "rejects a FIFO without blocking on open",
+      () =>
+        Effect.gen(function* () {
+          const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
+          const path = yield* Path.Path;
+          const cwd = yield* makeTempDir;
+          const outsideDir = yield* makeTempDir;
+          const fifoPath = path.join(outsideDir, "pipe");
+          yield* Effect.promise(
+            () =>
+              new Promise<void>((resolve, reject) =>
+                NodeChildProcess.execFile("mkfifo", [fifoPath], (error) =>
+                  error ? reject(error) : resolve(),
+                ),
               ),
-            ),
-        );
+          );
 
-        const error = yield* workspaceFileSystem
-          .readFile({ cwd, relativePath: fifoPath })
-          .pipe(Effect.flip);
+          const error = yield* workspaceFileSystem
+            .readFile({ cwd, relativePath: fifoPath })
+            .pipe(Effect.flip);
 
-        expect(error).toBeInstanceOf(WorkspaceFileSystem.WorkspacePathNotFileError);
-      }),
+          expect(error).toBeInstanceOf(WorkspaceFileSystem.WorkspacePathNotFileError);
+        }),
     );
 
     it.effect("rejects reads outside the workspace root", () =>
@@ -138,34 +143,36 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceFileSystemLive", (i
       }),
     );
 
-    it.effect("rejects symlinks that resolve outside the workspace root", () =>
-      Effect.gen(function* () {
-        const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
-        const fileSystem = yield* FileSystem.FileSystem;
-        const path = yield* Path.Path;
-        const cwd = yield* makeTempDir;
-        const outsideDir = yield* makeTempDir;
-        yield* writeTextFile(outsideDir, "secret.txt", "outside\n");
-        yield* fileSystem.symlink(
-          path.join(outsideDir, "secret.txt"),
-          path.join(cwd, "linked-secret.txt"),
-        );
-
-        const error = yield* workspaceFileSystem
-          .readFile({ cwd, relativePath: "linked-secret.txt" })
-          .pipe(Effect.flip);
-        const resolvedWorkspaceRoot = yield* fileSystem.realPath(cwd);
-        const resolvedPath = yield* fileSystem.realPath(path.join(outsideDir, "secret.txt"));
-
-        expect(error).toBeInstanceOf(WorkspaceFileSystem.WorkspaceFilePathEscapeError);
-        expect(error).toMatchObject({
-          workspaceRoot: cwd,
-          relativePath: "linked-secret.txt",
-          resolvedWorkspaceRoot,
-          resolvedPath,
-        });
-        expect("cause" in error).toBe(false);
-      }),
+    it.effect.skipIf(!symlinksSupported)(
+      "rejects symlinks that resolve outside the workspace root",
+      () =>
+        Effect.gen(function* () {
+          const workspaceFileSystem = yield* WorkspaceFileSystem.WorkspaceFileSystem;
+          const fileSystem = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const cwd = yield* makeTempDir;
+          const outsideDir = yield* makeTempDir;
+          yield* writeTextFile(outsideDir, "secret.txt", "outside\n");
+          yield* fileSystem.symlink(
+            path.join(outsideDir, "secret.txt"),
+            path.join(cwd, "linked-secret.txt"),
+          );
+
+          const error = yield* workspaceFileSystem
+            .readFile({ cwd, relativePath: "linked-secret.txt" })
+            .pipe(Effect.flip);
+          const resolvedWorkspaceRoot = yield* fileSystem.realPath(cwd);
+          const resolvedPath = yield* fileSystem.realPath(path.join(outsideDir, "secret.txt"));
+
+          expect(error).toBeInstanceOf(WorkspaceFileSystem.WorkspaceFilePathEscapeError);
+          expect(error).toMatchObject({
+            workspaceRoot: cwd,
+            relativePath: "linked-secret.txt",
+            resolvedWorkspaceRoot,
+            resolvedPath,
+          });
+          expect("cause" in error).toBe(false);
+        }),
     );
 
     it.effect("rejects directories without manufacturing an I/O cause", () =>
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index c69b4d737f90..c7ba450df37d 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -38,7 +38,7 @@ import {
   OrchestrationSearchThreadsError,
   OrchestrationGetTurnDiffError,
   ORCHESTRATION_WS_METHODS,
-  type ProjectId,
+  ProjectId,
   type ProjectEntriesFailure,
   type ProjectFileFailure,
   type ProjectFileOperation,
@@ -53,6 +53,7 @@ import {
   type RelayClientInstallProgressEvent,
   ServerSelfUpdateError,
   type ServerSelfUpdateProgressEvent,
+  type ServerLifecycleStreamEvent,
   type FilesystemBrowseFailure,
   FilesystemBrowseError,
   AssetWorkspaceContextNotFoundError,
@@ -81,6 +82,7 @@ import {
   projectThreadDetailSnapshot,
 } from "./orchestration/ActivityPayloadProjection.ts";
 import { makeThreadLiveEventCoalescer } from "./orchestration/ThreadLiveEventCoalescer.ts";
+import { makeLiveStreamBudget, type RetainedLiveItem } from "./orchestration/LiveStreamBudget.ts";
 import {
   cleanupFailedUploadedAttachments,
   normalizeDispatchCommand,
@@ -95,6 +97,7 @@ import {
 } from "./observability/RpcInstrumentation.ts";
 import * as ProviderRegistry from "./provider/Services/ProviderRegistry.ts";
 import * as ProviderService from "./provider/Services/ProviderService.ts";
+import * as ProviderSessionDirectory from "./provider/Services/ProviderSessionDirectory.ts";
 import * as ProviderMaintenanceRunner from "./provider/providerMaintenanceRunner.ts";
 import { ProviderAuthService } from "./provider/Services/ProviderAuthService.ts";
 import { ProviderInstanceRegistry } from "./provider/Services/ProviderInstanceRegistry.ts";
@@ -118,6 +121,8 @@ import * as VcsProvisioningService from "./vcs/VcsProvisioningService.ts";
 import * as GitWorkflowService from "./git/GitWorkflowService.ts";
 import * as ReviewService from "./review/ReviewService.ts";
 import * as ProjectSetupScriptRunner from "./project/ProjectSetupScriptRunner.ts";
+import * as AgentSessionScanner from "./project/AgentSessionScanner.ts";
+import { importRecentAgentThreads } from "./project/AgentSessionImporter.ts";
 import * as ServerEnvironment from "./environment/ServerEnvironment.ts";
 import * as RemoteOpenTargets from "./environment/RemoteOpenTargets.ts";
 import * as BackgroundPolicy from "./background/BackgroundPolicy.ts";
@@ -334,12 +339,9 @@ const PROVIDER_STATUS_DEBOUNCE_MS = 200;
 // Matches the event store's default page size (DEFAULT_READ_FROM_SEQUENCE_LIMIT).
 const SHELL_RESUME_MAX_GAP = 1_000;
 
-// Same bound for thread resume. The replay reads the *global* event range and
-// filters per-thread afterwards, so a stale cursor far behind the head would
-// otherwise decode every intervening event's payload — reconnects with cursors
-// hundreds of thousands of events behind have OOM-killed servers on large
-// databases. Past this gap the client is reset with a fresh thread snapshot.
-const THREAD_RESUME_MAX_GAP = 1_000;
+// Thread replay counts only this thread's rows. Busy or pruned unrelated
+// streams must not force a full thread snapshot.
+const THREAD_RESUME_MAX_EVENTS = 1_000;
 // Row count alone does not bound replay memory: a few events with large tool
 // payloads can decode to gigabytes. Before replaying, sum the serialized
 // payload bytes of the range in SQL and reset with a snapshot past this budget.
@@ -516,6 +518,7 @@ const makeWsRpcLayer = (
       const portDiscovery = yield* PortScanner.PortDiscovery;
       const providerRegistry = yield* ProviderRegistry.ProviderRegistry;
       const providerService = yield* ProviderService.ProviderService;
+      const providerSessionDirectory = yield* ProviderSessionDirectory.ProviderSessionDirectory;
       const providerMaintenanceRunner = yield* ProviderMaintenanceRunner.ProviderMaintenanceRunner;
       const providerAuth = yield* ProviderAuthService;
       const providerInstances = yield* ProviderInstanceRegistry;
@@ -565,6 +568,7 @@ const makeWsRpcLayer = (
         return true;
       });
       const projectSetupScriptRunner = yield* ProjectSetupScriptRunner.ProjectSetupScriptRunner;
+      const agentSessionScanner = yield* AgentSessionScanner.AgentSessionScanner;
       const serverEnvironment = yield* ServerEnvironment.ServerEnvironment;
       const backgroundPolicy = yield* BackgroundPolicy.BackgroundPolicy;
       const rpcClientIds = yield* Ref.make(new Set<RpcClientId>());
@@ -728,19 +732,33 @@ const makeWsRpcLayer = (
             });
       };
 
+      // Shell updates refetch the aggregate. Message and tool bodies are not needed.
+      const toShellEvent = ({
+        type,
+        aggregateKind,
+        aggregateId,
+        sequence,
+      }: OrchestrationEvent) => ({
+        type,
+        aggregateKind,
+        aggregateId,
+        sequence,
+      });
+      type ShellEvent = ReturnType<typeof toShellEvent>;
+
       const toShellStreamEvent = (
-        event: OrchestrationEvent,
+        event: ShellEvent,
       ): Effect.Effect<Option.Option<OrchestrationShellStreamEvent>, never, never> => {
         switch (event.type) {
           case "project.created":
           case "project.meta-updated":
-            return projectUpsertOrRemove(event.payload.projectId, event.sequence);
+            return projectUpsertOrRemove(ProjectId.make(event.aggregateId), event.sequence);
           case "project.deleted":
             return Effect.succeed(
               Option.some({
                 kind: "project-removed" as const,
                 sequence: event.sequence,
-                projectId: event.payload.projectId,
+                projectId: ProjectId.make(event.aggregateId),
               }),
             );
           case "thread.deleted":
@@ -749,11 +767,11 @@ const makeWsRpcLayer = (
               Option.some({
                 kind: "thread-removed" as const,
                 sequence: event.sequence,
-                threadId: event.payload.threadId,
+                threadId: ThreadId.make(event.aggregateId),
               }),
             );
           case "thread.unarchived":
-            return threadUpsertOrRemove(event.payload.threadId, event.sequence);
+            return threadUpsertOrRemove(ThreadId.make(event.aggregateId), event.sequence);
           default:
             if (event.aggregateKind !== "thread") {
               return Effect.succeed(Option.none());
@@ -867,13 +885,13 @@ const makeWsRpcLayer = (
       // item. The refetch runs with bounded concurrency (order-preserving).
       const SHELL_REFETCH_CONCURRENCY = 8;
       const coalesceShellEvents = (
-        events: ReadonlyArray<OrchestrationEvent>,
+        events: ReadonlyArray<ShellEvent>,
       ): Effect.Effect<ReadonlyArray<OrchestrationShellStreamEvent>, never, never> =>
         Effect.gen(function* () {
           if (events.length === 0) {
             return [];
           }
-          const latestByAggregate = new Map<string, OrchestrationEvent>();
+          const latestByAggregate = new Map<string, ShellEvent>();
           for (const event of events) {
             latestByAggregate.set(`${event.aggregateKind}:${event.aggregateId}`, event);
           }
@@ -896,16 +914,17 @@ const makeWsRpcLayer = (
         stream: Stream.Stream<OrchestrationEvent, E, R>,
       ): Stream.Stream<OrchestrationShellStreamEvent, E, R> =>
         stream.pipe(
+          Stream.map(toShellEvent),
           Stream.groupedWithin(SHELL_COALESCE_MAX_CHUNK, SHELL_COALESCE_WINDOW),
           Stream.mapEffect(coalesceShellEvents),
           Stream.flatMap((items) => Stream.fromIterable(items)),
         );
 
       type ShellLiveInput =
-        | { readonly kind: "event"; readonly event: OrchestrationEvent }
+        | { readonly kind: "event"; readonly event: ShellEvent }
         | { readonly kind: "synchronized" };
 
-      // A completion marker is queued alongside raw live events so it cannot
+      // A completion marker is queued alongside live event metadata so it cannot
       // overtake an event still waiting in the coalescing window. Split each
       // batch at markers and coalesce only the event segments on either side.
       const coalesceShellLiveInputs = (
@@ -913,7 +932,7 @@ const makeWsRpcLayer = (
       ): Effect.Effect<ReadonlyArray<OrchestrationShellStreamItem>, never, never> =>
         Effect.gen(function* () {
           const output: Array<OrchestrationShellStreamItem> = [];
-          let pendingEvents: Array<OrchestrationEvent> = [];
+          let pendingEvents: Array<ShellEvent> = [];
 
           for (const input of inputs) {
             if (input.kind === "event") {
@@ -930,15 +949,6 @@ const makeWsRpcLayer = (
           return output;
         });
 
-      const coalesceShellLiveStream = <E, R>(
-        stream: Stream.Stream<ShellLiveInput, E, R>,
-      ): Stream.Stream<OrchestrationShellStreamItem, E, R> =>
-        stream.pipe(
-          Stream.groupedWithin(SHELL_COALESCE_MAX_CHUNK, SHELL_COALESCE_WINDOW),
-          Stream.mapEffect(coalesceShellLiveInputs),
-          Stream.flatMap((items) => Stream.fromIterable(items)),
-        );
-
       const dispatchBootstrapTurnStart = (
         command: Extract<OrchestrationCommand, { type: "thread.turn.start" }>,
       ): Effect.Effect<{ readonly sequence: number }, OrchestrationDispatchCommandError> =>
@@ -1419,16 +1429,56 @@ const makeWsRpcLayer = (
               // sequence but the live subscription is not attached yet). Every
               // path below emits from this same buffered live tail. Overlapping
               // events are deduped by sequence on the client.
-              const liveBuffer = yield* Queue.unbounded<ShellLiveInput>();
+              const liveBudget = yield* makeLiveStreamBudget();
+              const liveBuffer = yield* Queue.unbounded<
+                RetainedLiveItem<ShellLiveInput>,
+                OrchestrationGetSnapshotError
+              >();
+              let liveBufferClosed = false;
+              const closeLiveBuffer = (error?: OrchestrationGetSnapshotError) =>
+                Effect.gen(function* () {
+                  if (liveBufferClosed) {
+                    return;
+                  }
+                  liveBufferClosed = true;
+                  liveBudget.release(yield* Queue.clear(liveBuffer).pipe(Effect.orDie));
+                  if (error) {
+                    yield* Queue.fail(liveBuffer, error);
+                  }
+                  yield* Queue.shutdown(liveBuffer);
+                });
+              yield* Effect.addFinalizer(() => closeLiveBuffer());
+              yield* liveBudget.failed.pipe(
+                Effect.catchTags({ OrchestrationGetSnapshotError: closeLiveBuffer }),
+                Effect.forkScoped,
+              );
               yield* Effect.forkScoped(
                 orchestrationEngine.streamDomainEvents.pipe(
+                  Stream.map(toShellEvent),
                   Stream.runForEach((event) =>
-                    Queue.offer(liveBuffer, { kind: "event" as const, event }),
+                    liveBudget.retain({ kind: "event" as const, event }, event).pipe(
+                      Effect.flatMap((item) => Queue.offer(liveBuffer, item)),
+                      Effect.uninterruptible,
+                    ),
                   ),
+                  // Stop the PubSub consumer even if RPC delivery is waiting
+                  // for an ACK and never pulls the failed buffer again.
+                  Effect.raceFirst(liveBudget.failed),
+                  Effect.catchTags({ OrchestrationGetSnapshotError: () => Effect.void }),
                 ),
                 { startImmediately: true },
               );
-              const bufferedLiveStream = coalesceShellLiveStream(Stream.fromQueue(liveBuffer));
+              const coalesceRetainedInputs = (
+                items: ReadonlyArray<RetainedLiveItem<ShellLiveInput>>,
+              ) =>
+                coalesceShellLiveInputs(items.map((item) => item.value)).pipe(
+                  Effect.flatMap((output) => liveBudget.replace(items, output)),
+                );
+              const bufferedLiveStream = Stream.fromQueue(liveBuffer).pipe(
+                Stream.groupedWithin(SHELL_COALESCE_MAX_CHUNK, SHELL_COALESCE_WINDOW),
+                Stream.mapEffect(coalesceRetainedInputs),
+                Stream.flatMap((items) => Stream.fromIterable(items)),
+              );
 
               const loadSnapshot = projectionSnapshotQuery.getShellSnapshot().pipe(
                 Effect.tapError((cause) =>
@@ -1446,18 +1496,21 @@ const makeWsRpcLayer = (
               // Offer the completion marker into the same queue as live events.
               // Anything buffered while snapshot/replay work was in flight is
               // therefore delivered before the client is told it is synchronized.
-              const synchronizedThenLive =
+              const synchronizedThenLive = liveBudget.deliver(
                 input.requestCompletionMarker === true
                   ? Stream.concat(
                       Stream.fromEffect(
-                        Queue.offer(liveBuffer, { kind: "synchronized" as const }).pipe(
+                        liveBudget.retain({ kind: "synchronized" as const }).pipe(
+                          Effect.flatMap((item) => Queue.offer(liveBuffer, item)),
+                          Effect.uninterruptible,
                           Effect.andThen(Queue.takeAll(liveBuffer)),
-                          Effect.flatMap(coalesceShellLiveInputs),
+                          Effect.flatMap(coalesceRetainedInputs),
                         ),
                       ).pipe(Stream.flatMap((items) => Stream.fromIterable(items))),
                       bufferedLiveStream,
                     )
-                  : bufferedLiveStream;
+                  : bufferedLiveStream,
+              );
 
               // When the client already holds a shell snapshot (cached, or loaded
               // over HTTP) it passes that snapshot's sequence, and we resume by
@@ -1554,10 +1607,16 @@ const makeWsRpcLayer = (
               // Attach live delivery before reading either replay or snapshot state.
               // Otherwise an event published while the snapshot is loading is lost.
               const liveBuffer = yield* makeThreadLiveEventCoalescer();
-              yield* Effect.forkScoped(liveStream.pipe(Stream.runForEach(liveBuffer.offer)), {
-                startImmediately: true,
-              });
+              yield* Effect.forkScoped(
+                liveStream.pipe(
+                  Stream.runForEachArray(liveBuffer.offerAll),
+                  Effect.raceFirst(liveBuffer.failed),
+                  Effect.catchTags({ OrchestrationGetSnapshotError: () => Effect.void }),
+                ),
+                { startImmediately: true },
+              );
               const bufferedLiveStream = liveBuffer.stream;
+              let replayOnMissingSnapshot: typeof bufferedLiveStream | undefined;
 
               // When the client already loaded the snapshot over HTTP it passes
               // that snapshot's sequence, and we resume the live subscription by
@@ -1572,24 +1631,41 @@ const makeWsRpcLayer = (
               // catch-up followed by the buffered/ongoing live events. Overlapping
               // events are deduped by sequence on the client.
               //
-              // The replay is bounded to the projection head captured below. The
-              // catch-up range is normally tiny (a fresh HTTP snapshot sequence),
-              // but a stale cached cursor can sit hundreds of thousands of global
-              // events behind — replaying that decodes every intervening event
-              // (including every other thread's tool payloads) only to discard
-              // almost all of them, which has OOM-killed servers on large
-              // databases. A truncated replay would silently drop this thread's
-              // events, so past the gap cap we reset the client with a fresh
-              // thread snapshot instead, exactly like subscribeShell above.
+              // Measure only this thread's rows. Global sequence gaps can
+              // contain unrelated or pruned streams. Keep an explicit upper
+              // bound so events after the captured head stay in the live tail.
               if (input.afterSequence !== undefined) {
                 const afterSequence = input.afterSequence;
                 const headSequence = yield* orchestrationEngine.latestSequence;
-                const replayGap = headSequence - afterSequence;
+                const range = {
+                  threadId: input.threadId,
+                  fromSequenceExclusive: afterSequence,
+                  toSequenceInclusive: headSequence,
+                };
+                const replayStats =
+                  afterSequence > headSequence
+                    ? null
+                    : yield* orchestrationEngine
+                        .getThreadReplayStats({
+                          ...range,
+                          maxEvents: THREAD_RESUME_MAX_EVENTS,
+                        })
+                        .pipe(
+                          Effect.mapError(
+                            (cause) =>
+                              new OrchestrationGetSnapshotError({
+                                message: `Failed to measure thread ${input.threadId} replay range`,
+                                cause,
+                              }),
+                          ),
+                        );
                 if (
-                  yield* canReplayPersistedRange(afterSequence, headSequence, THREAD_RESUME_MAX_GAP)
+                  replayStats !== null &&
+                  replayStats.eventCount <= THREAD_RESUME_MAX_EVENTS &&
+                  replayStats.payloadBytes <= ORCHESTRATION_REPLAY_PAYLOAD_BUDGET_BYTES
                 ) {
                   const catchUpStream = orchestrationEngine
-                    .readEvents(afterSequence, replayGap)
+                    .readThreadEvents({ ...range, limit: THREAD_RESUME_MAX_EVENTS })
                     .pipe(
                       Stream.filter(isThisThreadDetailEvent),
                       Stream.map((event) => ({
@@ -1606,20 +1682,20 @@ const makeWsRpcLayer = (
                     );
                   const afterCatchUp =
                     input.requestCompletionMarker === true
-                      ? Stream.concat(
-                          Stream.fromEffect(
-                            liveBuffer
-                              .offerAndWait({ kind: "synchronized" as const })
-                              .pipe(Effect.andThen(liveBuffer.takeAll)),
-                          ).pipe(Stream.flatMap((items) => Stream.fromIterable(items))),
-                          bufferedLiveStream,
+                      ? Stream.unwrap(
+                          liveBuffer
+                            .offer({ kind: "synchronized" as const })
+                            .pipe(Effect.as(bufferedLiveStream)),
                         )
                       : bufferedLiveStream;
-                  return Stream.concat(catchUpStream, afterCatchUp);
+                  const replay = Stream.concat(catchUpStream, afterCatchUp);
+                  if (!replayStats.hasCreateEvent) {
+                    return replay;
+                  }
+                  replayOnMissingSnapshot = replay;
                 }
-                // Gap too large (or cursor ahead of authoritative state): fall
-                // through to the snapshot path so the client converges from a
-                // fresh thread detail instead of an unbounded replay.
+                // A recreated thread needs a fresh snapshot if it still exists.
+                // Oversized replays and invalid cursors also use the snapshot path.
               }
 
               const snapshot = yield* projectionSnapshotQuery
@@ -1642,6 +1718,12 @@ const makeWsRpcLayer = (
                 );
 
               if (Option.isNone(snapshot)) {
+                // The recreated thread can already be deleted. Preserve the
+                // bounded replay and shell removal instead of retrying a
+                // snapshot that cannot exist. Oversized ranges still fail.
+                if (replayOnMissingSnapshot !== undefined) {
+                  return replayOnMissingSnapshot;
+                }
                 return yield* new OrchestrationGetSnapshotError({
                   message: `Thread ${input.threadId} was not found`,
                   cause: input.threadId,
@@ -1650,13 +1732,10 @@ const makeWsRpcLayer = (
 
               const afterSnapshot =
                 input.requestCompletionMarker === true
-                  ? Stream.concat(
-                      Stream.fromEffect(
-                        liveBuffer
-                          .offerAndWait({ kind: "synchronized" as const })
-                          .pipe(Effect.andThen(liveBuffer.takeAll)),
-                      ).pipe(Stream.flatMap((items) => Stream.fromIterable(items))),
-                      bufferedLiveStream,
+                  ? Stream.unwrap(
+                      liveBuffer
+                        .offer({ kind: "synchronized" as const })
+                        .pipe(Effect.as(bufferedLiveStream)),
                     )
                   : bufferedLiveStream;
               return Stream.concat(
@@ -2272,6 +2351,31 @@ const makeWsRpcLayer = (
             deletePendingAttachment(input.attachmentId),
             { "rpc.aggregate": "workspace" },
           ),
+        [WS_METHODS.agentSessionsScan]: () =>
+          observeRpcEffect(WS_METHODS.agentSessionsScan, agentSessionScanner.scan, {
+            "rpc.aggregate": "workspace",
+          }),
+        [WS_METHODS.agentSessionsImport]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.agentSessionsImport,
+            importRecentAgentThreads(input).pipe(
+              Effect.provideService(AgentSessionScanner.AgentSessionScanner, agentSessionScanner),
+              Effect.provideService(
+                OrchestrationEngine.OrchestrationEngineService,
+                orchestrationEngine,
+              ),
+              Effect.provideService(
+                ProjectionSnapshotQuery.ProjectionSnapshotQuery,
+                projectionSnapshotQuery,
+              ),
+              Effect.provideService(Crypto.Crypto, crypto),
+              Effect.provideService(
+                ProviderSessionDirectory.ProviderSessionDirectory,
+                providerSessionDirectory,
+              ),
+            ),
+            { "rpc.aggregate": "workspace" },
+          ),
         [WS_METHODS.assetsCreateUrl]: (input) =>
           observeRpcEffect(
             WS_METHODS.assetsCreateUrl,
@@ -2686,11 +2790,18 @@ const makeWsRpcLayer = (
           observeRpcStreamEffect(
             WS_METHODS.subscribeServerLifecycle,
             Effect.gen(function* () {
+              const liveBuffer = yield* Queue.unbounded<ServerLifecycleStreamEvent>();
+              yield* Effect.forkScoped(
+                lifecycleEvents.stream.pipe(
+                  Stream.runForEach((event) => Queue.offer(liveBuffer, event)),
+                ),
+                { startImmediately: true },
+              );
               const snapshot = yield* lifecycleEvents.snapshot;
               const snapshotEvents = Array.from(snapshot.events).toSorted(
                 (left, right) => left.sequence - right.sequence,
               );
-              const liveEvents = lifecycleEvents.stream.pipe(
+              const liveEvents = Stream.fromQueue(liveBuffer).pipe(
                 Stream.filter((event) => event.sequence > snapshot.sequence),
               );
               return Stream.concat(Stream.fromIterable(snapshotEvents), liveEvents);
@@ -2829,6 +2940,7 @@ export const websocketRpcRouteLayer = Layer.unwrap(
               previewAutomationBroker,
             ).pipe(
               Layer.provideMerge(RpcSerialization.layerJson),
+              Layer.provide(AgentSessionScanner.layer),
               Layer.provide(ProviderMaintenanceRunner.layer),
               Layer.provide(Layer.succeed(ServerSelfUpdate.ServerSelfUpdate, serverSelfUpdate)),
               // One server-lifetime service means clients share the same PR caches, and a WS
diff --git a/apps/server/vite.config.ts b/apps/server/vite.config.ts
index 647af2a889d5..88c8c2f4d37f 100644
--- a/apps/server/vite.config.ts
+++ b/apps/server/vite.config.ts
@@ -78,6 +78,8 @@ export default mergeConfig(
       // The server suite exercises sqlite, git, temp worktrees, and orchestration
       // runtimes heavily. Running files in parallel introduces load-sensitive flakes.
       fileParallelism: false,
+      // Appended to the root setup, which mergeConfig concatenates.
+      setupFiles: ["./src/testUtils/gitConfig.setup.ts"],
       // Server integration tests exercise sqlite, git, and orchestration together.
       // Under package-wide runs they can exceed the default budget on loaded CI hosts.
       hookTimeout: 120_000,
diff --git a/apps/web/package.json b/apps/web/package.json
index 283024eca095..4c9396cc725b 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -61,10 +61,12 @@
     "@types/culori": "^4.0.1",
     "@types/react": "~19.2.14",
     "@types/react-dom": "~19.2.3",
+    "@types/react-test-renderer": "19.1.0",
     "@vercel/config": "^0.3.0",
     "@vitejs/plugin-react": "^6.0.0",
     "babel-plugin-react-compiler": "1.0.0",
     "compression": "^1.8.1",
+    "react-test-renderer": "19.2.6",
     "tailwindcss": "^4.0.0",
     "vite": "catalog:",
     "vite-plus": "catalog:"
diff --git a/apps/web/src/AppRoot.test.tsx b/apps/web/src/AppRoot.test.tsx
deleted file mode 100644
index 791004b74fad..000000000000
--- a/apps/web/src/AppRoot.test.tsx
+++ /dev/null
@@ -1,26 +0,0 @@
-import { Children, isValidElement, type ReactElement, type ReactNode } from "react";
-import { RouterProvider } from "@tanstack/react-router";
-import { describe, expect, it } from "vite-plus/test";
-
-import { ElectronBrowserHost } from "./browser/ElectronBrowserHost";
-import { PreviewAutomationHosts } from "./components/preview/PreviewAutomationHosts";
-import { QuitHoldOverlay } from "./components/QuitHoldOverlay";
-import { AppAtomRegistryProvider } from "./rpc/atomRegistry";
-import type { AppRouter } from "./router";
-import { AppRoot } from "./AppRoot";
-
-describe("AppRoot", () => {
-  it("shares the application atom registry with routed UI and renderer-wide desktop hosts", () => {
-    const root = AppRoot({ router: {} as AppRouter });
-
-    expect(root.type).toBe(AppAtomRegistryProvider);
-    const children = Children.toArray(
-      (root as ReactElement<{ readonly children: ReactNode }>).props.children,
-    );
-    expect(children).toHaveLength(4);
-    expect(isValidElement(children[0]) && children[0].type).toBe(RouterProvider);
-    expect(isValidElement(children[1]) && children[1].type).toBe(PreviewAutomationHosts);
-    expect(isValidElement(children[2]) && children[2].type).toBe(ElectronBrowserHost);
-    expect(isValidElement(children[3]) && children[3].type).toBe(QuitHoldOverlay);
-  });
-});
diff --git a/apps/web/src/authBootstrap.test.ts b/apps/web/src/authBootstrap.test.ts
index 1a79f729bb03..dfe2b51d0400 100644
--- a/apps/web/src/authBootstrap.test.ts
+++ b/apps/web/src/authBootstrap.test.ts
@@ -310,6 +310,63 @@ describe("resolveInitialServerAuthGateState", () => {
     expect(testApi.calls.session).toBe(2);
   });
 
+  it("keeps manual token submission pending until the session is authenticated", async () => {
+    vi.useFakeTimers();
+    let authenticated = false;
+    let settled = false;
+    try {
+      const testApi = await installAuthApi({
+        session: () =>
+          authenticated
+            ? authenticatedSession(LOOPBACK_AUTH)
+            : unauthenticatedSession(LOOPBACK_AUTH),
+        browserSession: () => Effect.succeed(browserSession(["orchestration:read"])),
+      });
+      const { submitServerAuthCredential } = await import("./environments/primary");
+
+      const submission = submitServerAuthCredential("retry-token").finally(() => {
+        settled = true;
+      });
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(testApi.calls.browserSession).toEqual([{ credential: "retry-token" }]);
+      expect(testApi.calls.session).toBe(1);
+      expect(settled).toBe(false);
+
+      authenticated = true;
+      await vi.advanceTimersByTimeAsync(100);
+      await expect(submission).resolves.toBeUndefined();
+      expect(testApi.calls.session).toBe(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("fails manual token submission when the session is not established", async () => {
+    vi.useFakeTimers();
+    try {
+      const testApi = await installAuthApi({
+        session: () => unauthenticatedSession(LOOPBACK_AUTH),
+        browserSession: () => Effect.succeed(browserSession(["orchestration:read"])),
+      });
+      const { PrimaryEnvironmentAuthSessionTimeoutError, submitServerAuthCredential } =
+        await import("./environments/primary/auth");
+
+      const submission = submitServerAuthCredential("retry-token");
+      const failure = submission.then(
+        () => null,
+        (error: unknown) => error,
+      );
+      await vi.advanceTimersByTimeAsync(2_000);
+
+      await expect(failure).resolves.toBeInstanceOf(PrimaryEnvironmentAuthSessionTimeoutError);
+      expect(testApi.calls.browserSession).toEqual([{ credential: "retry-token" }]);
+      expect(testApi.calls.session).toBeGreaterThan(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("rejects a blank pairing token with a structured validation error", async () => {
     const { PrimaryEnvironmentPairingCredentialRequiredError, submitServerAuthCredential } =
       await import("./environments/primary/auth");
diff --git a/apps/web/src/browser/BrowserDeviceToolbar.test.ts b/apps/web/src/browser/BrowserDeviceToolbar.test.ts
index ee4987794c33..087b5d109b40 100644
--- a/apps/web/src/browser/BrowserDeviceToolbar.test.ts
+++ b/apps/web/src/browser/BrowserDeviceToolbar.test.ts
@@ -1,10 +1,7 @@
 import type { PreviewViewportSetting } from "@t3tools/contracts";
 import { describe, expect, it, vi } from "vite-plus/test";
 
-import {
-  commitViewportAndAspectRatio,
-  reconcileLockedAspectRatio,
-} from "./browserDeviceToolbarState";
+import { commitViewportAndAspectRatio } from "./browserDeviceToolbarState";
 
 describe("commitViewportAndAspectRatio", () => {
   it("commits the aspect ratio only after the viewport succeeds", async () => {
@@ -39,11 +36,3 @@ describe("commitViewportAndAspectRatio", () => {
     expect(onAspectRatioChange).not.toHaveBeenCalled();
   });
 });
-
-describe("reconcileLockedAspectRatio", () => {
-  it("tracks external viewport ratios only while the lock remains active", () => {
-    expect(reconcileLockedAspectRatio(1.5, 16 / 9)).toBe(16 / 9);
-    expect(reconcileLockedAspectRatio(null, 16 / 9)).toBeNull();
-    expect(reconcileLockedAspectRatio(1.5, null)).toBeNull();
-  });
-});
diff --git a/apps/web/src/browser/HostedBrowserWebview.test.tsx b/apps/web/src/browser/HostedBrowserWebview.test.tsx
new file mode 100644
index 000000000000..4a241befef74
--- /dev/null
+++ b/apps/web/src/browser/HostedBrowserWebview.test.tsx
@@ -0,0 +1,200 @@
+import {
+  DEFAULT_CLIENT_SETTINGS,
+  EnvironmentId,
+  FILL_PREVIEW_VIEWPORT,
+  ThreadId,
+  type ClientSettings,
+  type DesktopPreviewBridge,
+} from "@t3tools/contracts";
+import { act } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const mocks = vi.hoisted(() => ({
+  getClientSettings: vi.fn<() => Promise<ClientSettings | null>>(),
+  setClientSettings: vi.fn<(settings: ClientSettings) => Promise<void>>(),
+  createTab: vi.fn<DesktopPreviewBridge["createTab"]>(),
+  closeTab: vi.fn<DesktopPreviewBridge["closeTab"]>(),
+  registerWebview: vi.fn<DesktopPreviewBridge["registerWebview"]>(),
+  getPreviewConfig: vi.fn<DesktopPreviewBridge["getPreviewConfig"]>(),
+  activeRecordings: new Set<string>(),
+}));
+
+vi.mock("~/localApi", () => ({
+  ensureLocalApi: () => ({ persistence: mocks }),
+}));
+
+vi.mock("~/components/preview/previewBridge", () => ({
+  previewBridge: {
+    createTab: mocks.createTab,
+    closeTab: mocks.closeTab,
+    registerWebview: mocks.registerWebview,
+    getPreviewConfig: mocks.getPreviewConfig,
+  },
+}));
+
+vi.mock("~/components/preview/usePreviewBridge", () => ({
+  usePreviewBridge: () => undefined,
+}));
+
+vi.mock("./browserRecording", () => ({
+  useActiveBrowserRecordingTabIds: () => mocks.activeRecordings,
+  stopBrowserRecording: async () => null,
+}));
+
+import {
+  __resetClientSettingsPersistenceForTests,
+  ensureClientSettingsHydrated,
+} from "~/hooks/useSettings";
+import { useBrowserSurfaceStore } from "./browserSurfaceStore";
+import * as desktopTabLifetime from "./desktopTabLifetime";
+import { HostedBrowserWebview } from "./HostedBrowserWebview";
+
+let renderer: ReactTestRenderer | undefined;
+
+function deferred<A>() {
+  let resolve!: (value: A) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<A>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+beforeEach(() => {
+  __resetClientSettingsPersistenceForTests();
+  useBrowserSurfaceStore.setState({ activityByTabId: {}, byTabId: {} });
+  mocks.getClientSettings.mockReset();
+  mocks.setClientSettings.mockReset().mockResolvedValue(undefined);
+  mocks.createTab.mockReset().mockResolvedValue(undefined);
+  mocks.closeTab.mockReset().mockResolvedValue(undefined);
+  mocks.registerWebview.mockReset().mockResolvedValue(undefined);
+  mocks.getPreviewConfig.mockReset().mockResolvedValue({
+    partition: "persist:t3-preview-work",
+    webPreferences: "contextIsolation=yes",
+    preloadUrl: null,
+  });
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("window", globalThis);
+  vi.stubGlobal("navigator", { platform: "Linux" });
+  vi.stubGlobal(
+    "requestAnimationFrame",
+    vi.fn(() => 0),
+  );
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+  vi.spyOn(console, "error").mockImplementation(() => undefined);
+});
+
+afterEach(async () => {
+  vi.useFakeTimers();
+  await act(() => renderer?.unmount());
+  renderer = undefined;
+  await vi.advanceTimersByTimeAsync(0);
+  vi.useRealTimers();
+  __resetClientSettingsPersistenceForTests();
+  useBrowserSurfaceStore.setState({ activityByTabId: {}, byTabId: {} });
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("HostedBrowserWebview settings hydration", () => {
+  it("starts a retained background tab only after a settings read succeeds on retry", async () => {
+    const firstRead = deferred<ClientSettings | null>();
+    const retryRead = deferred<ClientSettings | null>();
+    const tabCreation = deferred<void>();
+    mocks.getClientSettings
+      .mockReturnValueOnce(firstRead.promise)
+      .mockReturnValueOnce(retryRead.promise);
+    mocks.createTab.mockReturnValueOnce(tabCreation.promise);
+    const acquire = vi.spyOn(desktopTabLifetime, "acquireDesktopTab");
+    const createGuest = vi.fn((_attributes: unknown) =>
+      Object.assign(new EventTarget(), { getWebContentsId: () => 41 }),
+    );
+    const threadRef = {
+      environmentId: EnvironmentId.make("host-settings-retry"),
+      threadId: ThreadId.make("thread-settings-retry"),
+    };
+    const runtimeTabId = "retained-background-tab";
+    useBrowserSurfaceStore.getState().acquireActivity(runtimeTabId);
+
+    await act(() => {
+      renderer = create(
+        <HostedBrowserWebview
+          threadRef={threadRef}
+          tabId="server-tab"
+          runtimeTabId={runtimeTabId}
+          initialUrl="https://example.com"
+          viewport={FILL_PREVIEW_VIEWPORT}
+          pictureInPicture={false}
+          profileId="work"
+          zoomFactor={1.25}
+        />,
+        {
+          createNodeMock: (element) =>
+            element.type === "webview"
+              ? createGuest(element.props)
+              : { scrollLeft: 0, scrollTop: 0, scrollTo: () => undefined },
+        },
+      );
+    });
+
+    expect(mocks.getClientSettings).toHaveBeenCalledOnce();
+    expect(acquire).not.toHaveBeenCalled();
+    expect(createGuest).not.toHaveBeenCalled();
+    expect(mocks.createTab).not.toHaveBeenCalled();
+
+    const failure = new Error("Saved settings are unavailable");
+    await act(async () => {
+      const hydration = ensureClientSettingsHydrated();
+      firstRead.reject(failure);
+      await expect(hydration).rejects.toBe(failure);
+    });
+    expect(acquire).not.toHaveBeenCalled();
+    expect(createGuest).not.toHaveBeenCalled();
+    expect(mocks.createTab).not.toHaveBeenCalled();
+
+    let retry!: Promise<void>;
+    await act(() => {
+      retry = ensureClientSettingsHydrated();
+    });
+    expect(mocks.getClientSettings).toHaveBeenCalledTimes(2);
+    expect(acquire).not.toHaveBeenCalled();
+    expect(createGuest).not.toHaveBeenCalled();
+    expect(mocks.createTab).not.toHaveBeenCalled();
+
+    await act(async () => {
+      retryRead.resolve({
+        ...DEFAULT_CLIENT_SETTINGS,
+        browserDefaultZoomFactor: 1.25,
+        browserDefaultAppearance: "dark",
+        browserProfiles: [{ id: "work", name: "Work", kind: "persistent" }],
+        browserDefaultProfileId: "work",
+      });
+      await retry;
+    });
+
+    expect(acquire).toHaveBeenCalledExactlyOnceWith(runtimeTabId);
+    expect(mocks.getPreviewConfig).toHaveBeenCalledExactlyOnceWith(threadRef.environmentId, "work");
+    expect(createGuest).toHaveBeenCalledOnce();
+    expect(createGuest).toHaveBeenCalledWith(
+      expect.objectContaining({
+        partition: "persist:t3-preview-work",
+        src: "https://example.com",
+      }),
+    );
+    expect(mocks.createTab).toHaveBeenCalledExactlyOnceWith(runtimeTabId, {
+      zoomFactor: 1.25,
+      colorScheme: "dark",
+    });
+    expect(mocks.registerWebview).not.toHaveBeenCalled();
+
+    await act(async () => {
+      tabCreation.resolve();
+      await tabCreation.promise;
+    });
+    expect(mocks.registerWebview).toHaveBeenCalledExactlyOnceWith(runtimeTabId, 41);
+    expect(mocks.closeTab).not.toHaveBeenCalled();
+    expect(mocks.setClientSettings).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/web/src/browser/HostedBrowserWebview.tsx b/apps/web/src/browser/HostedBrowserWebview.tsx
index 0f01960ce52b..42d5bcfb35b8 100644
--- a/apps/web/src/browser/HostedBrowserWebview.tsx
+++ b/apps/web/src/browser/HostedBrowserWebview.tsx
@@ -6,6 +6,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 import { previewBridge } from "~/components/preview/previewBridge";
 import { usePreviewBridge } from "~/components/preview/usePreviewBridge";
+import { useClientSettingsHydrated } from "~/hooks/useSettings";
 import { cn, isMacPlatform } from "~/lib/utils";
 
 import { resolveBrowserSurfacePanelRect, useBrowserSurfaceStore } from "./browserSurfaceStore";
@@ -66,6 +67,7 @@ export function HostedBrowserWebview(props: {
     zoomFactor,
     profileId,
   } = props;
+  const clientSettingsHydrated = useClientSettingsHydrated();
   const config = usePreviewWebviewConfig(threadRef.environmentId, profileId);
   const [initialSrc] = useState(() => initialUrl ?? "about:blank");
   const tabLeaseRef = useRef<AcquiredDesktopTab | null>(null);
@@ -94,6 +96,7 @@ export function HostedBrowserWebview(props: {
   usePreviewBridge({ threadRef, tabId, runtimeTabId });
 
   useEffect(() => {
+    if (!clientSettingsHydrated) return;
     crashRecoveryRef.current = INITIAL_WEBVIEW_CRASH_RECOVERY_STATE;
     const lease = acquireDesktopTab(runtimeTabId);
     tabLeaseRef.current = lease;
@@ -101,7 +104,7 @@ export function HostedBrowserWebview(props: {
       if (tabLeaseRef.current === lease) tabLeaseRef.current = null;
       lease.release();
     };
-  }, [runtimeTabId]);
+  }, [clientSettingsHydrated, runtimeTabId]);
 
   const [webviewGeneration, setWebviewGeneration] = useState(0);
   const [recoverySrc, setRecoverySrc] = useState(initialSrc);
@@ -118,7 +121,7 @@ export function HostedBrowserWebview(props: {
   useEffect(() => {
     const webview = webviewRef.current;
     const bridge = previewBridge;
-    if (!webview || !config || !bridge) return;
+    if (!clientSettingsHydrated || !webview || !config || !bridge) return;
     let disposed = false;
     let recoveryTimeout: ReturnType<typeof setTimeout> | null = null;
     const register = () => {
@@ -164,7 +167,7 @@ export function HostedBrowserWebview(props: {
       webview.removeEventListener("dom-ready", register);
       webview.removeEventListener("render-process-gone", recoverGuest);
     };
-  }, [config, initialSrc, runtimeTabId, webviewGeneration]);
+  }, [clientSettingsHydrated, config, initialSrc, runtimeTabId, webviewGeneration]);
 
   const active = presentation.visible && presentation.rect !== null;
   const lastRect = presentation.rect;
@@ -249,7 +252,7 @@ export function HostedBrowserWebview(props: {
     wrapper.scrollTo({ left: 0, top: 0 });
   }, [runtimeTabId, viewport._tag, viewportHeight, viewportWidth]);
 
-  if (!config) return null;
+  if (!clientSettingsHydrated || !config) return null;
 
   const renderingActive = active || backgroundActivity || pictureInPicture || recordingActive;
   const wrapperStyle = resolveHostedBrowserWebviewWrapperStyle({
diff --git a/apps/web/src/browser/browserDefaults.test.ts b/apps/web/src/browser/browserDefaults.test.ts
index bac9600c182b..ed86cde1c9c8 100644
--- a/apps/web/src/browser/browserDefaults.test.ts
+++ b/apps/web/src/browser/browserDefaults.test.ts
@@ -1,15 +1,17 @@
 import { describe, expect, it, vi } from "vite-plus/test";
 import { DEFAULT_BROWSER_PROFILE_ID, INCOGNITO_BROWSER_PROFILE_ID } from "@t3tools/contracts";
 
+import { ensureClientSettingsHydrated } from "~/hooks/useSettings";
+
 const settings = vi.hoisted(() => ({ current: {} as Record<string, unknown> }));
 
 vi.mock("~/hooks/useSettings", () => ({
   getClientSettings: () => settings.current,
   useClientSettings: () => undefined,
-  ensureClientSettingsHydrated: () => Promise.resolve(),
+  ensureClientSettingsHydrated: vi.fn(async () => undefined),
 }));
 
-const { getBrowserDefaults } = await import("./browserDefaults");
+const { getBrowserDefaults, resolveBrowserDefaults } = await import("./browserDefaults");
 
 const withDefaultProfile = (browserDefaultProfileId: string) => {
   settings.current = {
@@ -41,3 +43,22 @@ describe("getBrowserDefaults profile resolution", () => {
     );
   });
 });
+
+describe("resolveBrowserDefaults", () => {
+  it("rejects failed reads and uses the saved profile after a successful retry", async () => {
+    withDefaultProfile("work");
+    settings.current.browserDefaultZoomFactor = 1.25;
+    settings.current.browserDefaultAppearance = "dark";
+    const failure = new Error("Settings read failed");
+    vi.mocked(ensureClientSettingsHydrated).mockRejectedValueOnce(failure);
+
+    await expect(resolveBrowserDefaults()).rejects.toBe(failure);
+    await expect(resolveBrowserDefaults()).resolves.toMatchObject({
+      viewport: { _tag: "fill" },
+      zoomFactor: 1.25,
+      appearance: "dark",
+      autoShowFloatingPreview: true,
+      profileId: "work",
+    });
+  });
+});
diff --git a/apps/web/src/browser/browserDefaults.ts b/apps/web/src/browser/browserDefaults.ts
index eaae409568a2..6141b1a52fa9 100644
--- a/apps/web/src/browser/browserDefaults.ts
+++ b/apps/web/src/browser/browserDefaults.ts
@@ -79,6 +79,7 @@ export function getBrowserDefaults(): BrowserDefaults {
  * Opening a preview is asynchronous anyway, and before hydration the snapshot
  * is the schema defaults rather than the user's — a tab opened in that window
  * would be born at the wrong viewport, zoom and appearance and never corrected.
+ * Read failures reject so a new tab cannot use the wrong profile or viewport.
  */
 export async function resolveBrowserDefaults(): Promise<BrowserDefaults> {
   await ensureClientSettingsHydrated();
diff --git a/apps/web/src/browser/browserDeviceToolbarState.ts b/apps/web/src/browser/browserDeviceToolbarState.ts
index 9986ee022829..70a8e597428b 100644
--- a/apps/web/src/browser/browserDeviceToolbarState.ts
+++ b/apps/web/src/browser/browserDeviceToolbarState.ts
@@ -1,12 +1,5 @@
 import type { PreviewViewportSetting } from "@t3tools/contracts";
 
-export function reconcileLockedAspectRatio(
-  current: number | null,
-  viewportAspectRatio: number | null,
-): number | null {
-  return current === null || viewportAspectRatio === null ? null : viewportAspectRatio;
-}
-
 export async function commitViewportAndAspectRatio(
   setting: PreviewViewportSetting,
   aspectRatio: number | null,
diff --git a/apps/web/src/browser/browserLinkTarget.test.ts b/apps/web/src/browser/browserLinkTarget.test.ts
index 94f97001c96f..a60362c43bd5 100644
--- a/apps/web/src/browser/browserLinkTarget.test.ts
+++ b/apps/web/src/browser/browserLinkTarget.test.ts
@@ -1,6 +1,16 @@
-import { describe, expect, it } from "vite-plus/test";
+import type { BrowserLinkTarget } from "@t3tools/contracts";
+import { describe, expect, it, vi } from "vite-plus/test";
 
-import { resolveLinkTarget } from "./browserLinkTarget";
+import { ensureClientSettingsHydrated } from "~/hooks/useSettings";
+
+import { resolveBrowserLinkTargetPreference, resolveLinkTarget } from "./browserLinkTarget";
+
+const settings = vi.hoisted(() => ({ browserLinkTarget: "system" as BrowserLinkTarget }));
+
+vi.mock("~/hooks/useSettings", () => ({
+  ensureClientSettingsHydrated: vi.fn(async () => undefined),
+  getClientSettings: () => settings,
+}));
 
 const click = { metaKey: false, ctrlKey: false };
 
@@ -67,3 +77,17 @@ describe("resolveLinkTarget", () => {
     }
   });
 });
+
+describe("resolveBrowserLinkTargetPreference", () => {
+  it.each(["system", "app"] as const)(
+    "rejects failed reads instead of using the current %s preference",
+    async (preference) => {
+      settings.browserLinkTarget = preference;
+      const failure = new Error("Settings read failed");
+      vi.mocked(ensureClientSettingsHydrated).mockRejectedValueOnce(failure);
+
+      await expect(resolveBrowserLinkTargetPreference()).rejects.toBe(failure);
+      await expect(resolveBrowserLinkTargetPreference()).resolves.toBe(preference);
+    },
+  );
+});
diff --git a/apps/web/src/browser/browserLinkTarget.ts b/apps/web/src/browser/browserLinkTarget.ts
index d03775572747..7ecffb4593d5 100644
--- a/apps/web/src/browser/browserLinkTarget.ts
+++ b/apps/web/src/browser/browserLinkTarget.ts
@@ -55,6 +55,7 @@ export function isWebUrl(url: string): boolean {
  * hydration the snapshot is the schema default ("system"), so a link clicked
  * in the first moments after launch would ignore a persisted "app" — opening
  * is asynchronous anyway, so waiting costs nothing the user can see.
+ * Read failures reject rather than choosing a browser without the saved preference.
  */
 export async function resolveBrowserLinkTargetPreference(): Promise<BrowserLinkTarget> {
   await ensureClientSettingsHydrated();
diff --git a/apps/web/src/browser/browserRecording.test.ts b/apps/web/src/browser/browserRecording.test.ts
index 49145f314e98..5cfe614f2985 100644
--- a/apps/web/src/browser/browserRecording.test.ts
+++ b/apps/web/src/browser/browserRecording.test.ts
@@ -5,6 +5,8 @@ import {
 } from "@t3tools/contracts";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
 
+import { ensureClientSettingsHydrated } from "~/hooks/useSettings";
+
 const {
   clientSettings,
   events,
@@ -241,6 +243,35 @@ describe("browser recording", () => {
     await stopBrowserRecording("recording-tab");
   });
 
+  it("clears a failed settings read before retrying recording", async () => {
+    const tabId = "settings-read-failure-tab";
+    const error = new Error("Settings read failed");
+    vi.mocked(ensureClientSettingsHydrated).mockRejectedValueOnce(error);
+
+    await expect(startBrowserRecording(tabId)).rejects.toBe(error);
+
+    expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
+    expect(useBrowserSurfaceStore.getState().activityByTabId[tabId]).toBeUndefined();
+    expect(animationFrameCount).toBe(0);
+    expect(startScreencast).not.toHaveBeenCalled();
+    expect(stopScreencast).not.toHaveBeenCalled();
+    expect(getDisplayMedia).not.toHaveBeenCalled();
+    expect(FakeMediaRecorder.instances).toHaveLength(0);
+
+    clientSettings.browserRecordingFrameRate = 60;
+    await startBrowserRecording(tabId);
+
+    expect(getDisplayMedia).toHaveBeenCalledWith({
+      audio: false,
+      video: { frameRate: { max: 60 } },
+    });
+    await stopBrowserRecording(tabId);
+
+    expect(startScreencast).toHaveBeenCalledOnce();
+    expect(readActiveBrowserRecordingTabIds()).toEqual(new Set());
+    expect(useBrowserSurfaceStore.getState().activityByTabId[tabId]).toBeUndefined();
+  });
+
   it("stops the native stream when MediaRecorder cleanup fails", async () => {
     const stopTrack = vi.fn();
     getDisplayMedia.mockResolvedValueOnce({
diff --git a/apps/web/src/browser/browserRecording.ts b/apps/web/src/browser/browserRecording.ts
index 73bc2708ddf6..c7825961abbc 100644
--- a/apps/web/src/browser/browserRecording.ts
+++ b/apps/web/src/browser/browserRecording.ts
@@ -516,10 +516,12 @@ export async function startBrowserRecording(
   activeRecordings.set(tabId, recording);
   publishActiveRecordingTabIds();
   try {
-    const frameRatePromise = ensureClientSettingsHydrated().then(
-      () => getClientSettings().browserRecordingFrameRate,
-    );
-    const [frameRate] = await Promise.all([frameRatePromise, waitForBrowserRecordingPaint()]);
+    await ensureClientSettingsHydrated().catch((cause: unknown) => {
+      clearActiveRecording(recording);
+      throw cause;
+    });
+    const frameRate = getClientSettings().browserRecordingFrameRate;
+    await waitForBrowserRecordingPaint();
     const throwIfStartupCancelled = async (): Promise<void> => {
       // Once a grant starts, a stop lets startup finish so the caller receives an artifact.
       // Only a contended start can be cancelled before it reaches native capture.
diff --git a/apps/web/src/browser/browserTargetResolver.ts b/apps/web/src/browser/browserTargetResolver.ts
index c06c60b5f740..4acb1e2b487f 100644
--- a/apps/web/src/browser/browserTargetResolver.ts
+++ b/apps/web/src/browser/browserTargetResolver.ts
@@ -4,158 +4,16 @@ import type {
   PreviewUrlResolution,
 } from "@t3tools/contracts";
 import { isLoopbackHost, normalizePreviewUrl } from "@t3tools/shared/preview";
+import { isLocalLoopbackHost, isPrivateNetworkHost } from "@t3tools/shared/hostClassification";
 
 import { readPreparedConnection } from "~/state/session";
 
-export const normalizeHostname = (host: string): string =>
-  host
-    .toLowerCase()
-    .replace(/^\[|\]$/g, "")
-    .replace(/\.+$/u, "");
-
-const parseIpv4Address = (host: string): readonly number[] | null => {
-  const parts = normalizeHostname(host).split(".").map(Number);
-  return parts.length === 4 &&
-    parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)
-    ? parts
-    : null;
-};
-
-const parseIpv4MappedIpv6Address = (host: string): readonly number[] | null => {
-  const normalized = normalizeHostname(host);
-  if (!normalized.startsWith("::ffff:")) return null;
-  const suffix = normalized.slice("::ffff:".length);
-  const dotted = parseIpv4Address(suffix);
-  if (dotted) return dotted;
-  const hextets = suffix.split(":");
-  if (hextets.length !== 2 || hextets.some((part) => !/^[\da-f]{1,4}$/u.test(part))) return null;
-  const high = Number.parseInt(hextets[0]!, 16);
-  const low = Number.parseInt(hextets[1]!, 16);
-  return [high >>> 8, high & 0xff, low >>> 8, low & 0xff];
-};
-
-const parseIpv6Address = (host: string): readonly number[] | null => {
-  const normalized = normalizeHostname(host);
-  if (!normalized.includes(":")) return null;
-  const halves = normalized.split("::");
-  if (halves.length > 2) return null;
-  const head = halves[0] ? halves[0].split(":") : [];
-  const tail = halves[1] ? halves[1].split(":") : [];
-  if ([...head, ...tail].some((part) => !/^[\da-f]{1,4}$/u.test(part))) return null;
-  const missing = 8 - head.length - tail.length;
-  if ((halves.length === 1 && missing !== 0) || (halves.length === 2 && missing < 1)) return null;
-  return [...head, ...Array.from({ length: missing }, () => "0"), ...tail].map((part) =>
-    Number.parseInt(part, 16),
-  );
-};
-
-const ipv6PrefixMatches = (
-  address: readonly number[],
-  prefix: readonly number[],
-  prefixLength: number,
-): boolean => {
-  const fullHextets = Math.floor(prefixLength / 16);
-  if (address.slice(0, fullHextets).some((part, index) => part !== prefix[index])) return false;
-  const remainingBits = prefixLength % 16;
-  if (remainingBits === 0) return true;
-  const mask = (0xffff << (16 - remainingBits)) & 0xffff;
-  return (address[fullHextets]! & mask) === (prefix[fullHextets]! & mask);
-};
-
-const isPrivateIpv4Address = (parts: readonly number[]): boolean =>
-  parts[0] === 0 ||
-  parts[0] === 10 ||
-  parts[0] === 127 ||
-  (parts[0] === 100 && parts[1]! >= 64 && parts[1]! <= 127) ||
-  (parts[0] === 172 && parts[1]! >= 16 && parts[1]! <= 31) ||
-  (parts[0] === 192 && parts[1] === 168) ||
-  (parts[0] === 169 && parts[1] === 254) ||
-  (parts[0] === 198 && parts[1]! >= 18 && parts[1]! <= 19);
-
-const isSpecialPurposeIpv4Address = (parts: readonly number[]): boolean =>
-  isPrivateIpv4Address(parts) ||
-  parts[0]! >= 224 ||
-  // Deliberately suppress the whole protocol-assignment block. IANA marks
-  // .9 and .10 globally reachable, but privacy-safe false negatives are
-  // preferable to disclosing another special-purpose address by mistake.
-  (parts[0] === 192 && parts[1] === 0 && parts[2] === 0) ||
-  (parts[0] === 192 && parts[1] === 0 && parts[2] === 2) ||
-  (parts[0] === 192 && parts[1] === 88 && parts[2] === 99) ||
-  (parts[0] === 198 && parts[1] === 51 && parts[2] === 100) ||
-  (parts[0] === 203 && parts[1] === 0 && parts[2] === 113);
-
-export const isLocalLoopbackHost = (host: string): boolean => {
-  const normalized = normalizeHostname(host);
-  if (normalized === "localhost" || normalized === "::1") return true;
-  return parseIpv4Address(normalized)?.[0] === 127;
-};
-
-export const isPrivateNetworkHost = (host: string): boolean => {
-  const normalized = normalizeHostname(host);
-  if (
-    normalized === "::" ||
-    isLocalLoopbackHost(normalized) ||
-    normalized.endsWith(".localhost") ||
-    normalized.endsWith(".local") ||
-    normalized === "home.arpa" ||
-    normalized.endsWith(".home.arpa") ||
-    (!normalized.includes(".") && !normalized.includes(":"))
-  ) {
-    return true;
-  }
-  if (normalized.endsWith(".ts.net")) return true;
-  const parts = parseIpv4Address(normalized) ?? parseIpv4MappedIpv6Address(normalized);
-  if (parts) return isPrivateIpv4Address(parts);
-  const firstIpv6Token = normalized.split(":", 1)[0] ?? "";
-  if (!normalized.includes(":") || !/^[\da-f]{1,4}$/u.test(firstIpv6Token)) return false;
-  const firstIpv6Hextet = Number.parseInt(firstIpv6Token, 16);
-  return (
-    Number.isInteger(firstIpv6Hextet) &&
-    ((firstIpv6Hextet & 0xfe00) === 0xfc00 || (firstIpv6Hextet & 0xffc0) === 0xfe80)
-  );
-};
-
-/** Whether a hostname is eligible to be disclosed to a public favicon provider. */
-export const isPublicFaviconHost = (host: string): boolean => {
-  // A single trailing dot is a valid absolute DNS name. Repeated trailing
-  // dots are malformed and can conceal legacy numeric forms such as 127.1.
-  if (host.endsWith("..")) return false;
-  const normalized = normalizeHostname(host);
-  if (isPrivateNetworkHost(normalized)) return false;
-  if (
-    [".alt", ".example", ".internal", ".invalid", ".onion", ".test"].some(
-      (suffix) => normalized === suffix.slice(1) || normalized.endsWith(suffix),
-    )
-  ) {
-    return false;
-  }
-  const ipv4 = parseIpv4Address(normalized) ?? parseIpv4MappedIpv6Address(normalized);
-  if (ipv4) return !isSpecialPurposeIpv4Address(ipv4);
-  if (!normalized.includes(":")) return true;
-  const ipv6 = parseIpv6Address(normalized);
-  if (!ipv6) return false;
-  if (ipv6PrefixMatches(ipv6, [0x0064, 0xff9b, 0, 0, 0, 0, 0, 0], 96)) {
-    const embeddedIpv4 = [ipv6[6]! >>> 8, ipv6[6]! & 0xff, ipv6[7]! >>> 8, ipv6[7]! & 0xff];
-    return !isSpecialPurposeIpv4Address(embeddedIpv4);
-  }
-  const first = ipv6[0]!;
-  if ((first & 0xe000) !== 0x2000) return false;
-  if (ipv6PrefixMatches(ipv6, [0x2001, 0, 0, 0, 0, 0, 0, 0], 23)) {
-    const publicProtocolAssignment =
-      (ipv6[1] === 1 &&
-        ipv6.slice(2, 7).every((part) => part === 0) &&
-        [1, 2, 3].includes(ipv6[7]!)) ||
-      ipv6PrefixMatches(ipv6, [0x2001, 3, 0, 0, 0, 0, 0, 0], 32) ||
-      ipv6PrefixMatches(ipv6, [0x2001, 4, 0x0112, 0, 0, 0, 0, 0], 48) ||
-      ipv6PrefixMatches(ipv6, [0x2001, 0x20, 0, 0, 0, 0, 0, 0], 28) ||
-      ipv6PrefixMatches(ipv6, [0x2001, 0x30, 0, 0, 0, 0, 0, 0], 28);
-    return publicProtocolAssignment;
-  }
-  if (ipv6PrefixMatches(ipv6, [0x2001, 0x0db8, 0, 0, 0, 0, 0, 0], 32)) return false;
-  if (ipv6PrefixMatches(ipv6, [0x2002, 0, 0, 0, 0, 0, 0, 0], 16)) return false;
-  if (first === 0x3fff && (ipv6[1]! & 0xf000) === 0) return false;
-  return true;
-};
+export {
+  normalizeHostname,
+  isLocalLoopbackHost,
+  isPrivateNetworkHost,
+  isPublicFaviconHost,
+} from "@t3tools/shared/hostClassification";
 
 const readEnvironmentUrl = (environmentId: EnvironmentId): URL => {
   const connection = readPreparedConnection(environmentId);
diff --git a/apps/web/src/browser/desktopTabLifetime.test.ts b/apps/web/src/browser/desktopTabLifetime.test.ts
index 80bfa0d275d7..c5338ecf4ccf 100644
--- a/apps/web/src/browser/desktopTabLifetime.test.ts
+++ b/apps/web/src/browser/desktopTabLifetime.test.ts
@@ -1,6 +1,7 @@
 import {
   DEFAULT_PREVIEW_APPEARANCE,
   DEFAULT_PREVIEW_ZOOM_FACTOR,
+  DEFAULT_CLIENT_SETTINGS,
   EnvironmentId,
   ThreadId,
 } from "@t3tools/contracts";
@@ -21,8 +22,10 @@ vi.mock("./browserRecording", () => ({
 }));
 
 import { acquireDesktopTab } from "./desktopTabLifetime";
+import * as browserDefaults from "./browserDefaults";
+import { __setClientSettingsForTests } from "~/hooks/useSettings";
 
-/** Client settings are unset in tests, so creation carries the schema defaults. */
+/** Tests load default settings unless they select other preferences. */
 const DEFAULT_TAB_STATE = {
   zoomFactor: DEFAULT_PREVIEW_ZOOM_FACTOR,
   colorScheme: DEFAULT_PREVIEW_APPEARANCE,
@@ -31,6 +34,7 @@ import { previewRuntimeTabId } from "./previewRuntimeTabId";
 
 describe("desktopTabLifetime", () => {
   beforeEach(() => {
+    __setClientSettingsForTests(DEFAULT_CLIENT_SETTINGS);
     closeTab.mockClear();
     createTab.mockClear();
     stopBrowserRecording.mockClear();
@@ -40,6 +44,35 @@ describe("desktopTabLifetime", () => {
   afterEach(() => {
     vi.useRealTimers();
     vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("does not create a desktop tab after a failed settings read and permits a later retry", async () => {
+    vi.useFakeTimers();
+    const failure = new Error("Settings read failed");
+    vi.spyOn(browserDefaults, "resolveBrowserDefaults").mockRejectedValueOnce(failure);
+    const failed = acquireDesktopTab("tab_settings_retry");
+
+    await expect(failed.ready).rejects.toBe(failure);
+    expect(createTab).not.toHaveBeenCalled();
+    failed.release();
+    await vi.advanceTimersByTimeAsync(0);
+
+    __setClientSettingsForTests({
+      ...DEFAULT_CLIENT_SETTINGS,
+      browserDefaultZoomFactor: 1.25,
+      browserDefaultAppearance: "dark",
+    });
+    createTab.mockResolvedValueOnce(undefined);
+    const retry = acquireDesktopTab("tab_settings_retry");
+    await retry.ready;
+
+    expect(createTab).toHaveBeenCalledExactlyOnceWith("tab_settings_retry", {
+      zoomFactor: 1.25,
+      colorScheme: "dark",
+    });
+    retry.release();
+    await vi.advanceTimersByTimeAsync(0);
   });
 
   it("shares tab creation readiness across concurrent leases", async () => {
diff --git a/apps/web/src/browser/openFileInPreview.ts b/apps/web/src/browser/openFileInPreview.ts
index f506e42e73e5..a320e3ba34da 100644
--- a/apps/web/src/browser/openFileInPreview.ts
+++ b/apps/web/src/browser/openFileInPreview.ts
@@ -38,6 +38,14 @@ export class BrowserPreviewUnavailableError extends Data.TaggedError(
   readonly message: string;
 }> {}
 
+export class BrowserSettingsReadError extends Data.TaggedError("BrowserSettingsReadError")<{
+  readonly cause: unknown;
+}> {
+  override get message(): string {
+    return "Saved browser settings could not be loaded.";
+  }
+}
+
 export type OpenPreviewMutation<E = unknown> = (input: {
   readonly environmentId: EnvironmentId;
   readonly input: PreviewOpenInput;
@@ -47,8 +55,13 @@ export async function openUrlInPreview<E>(input: {
   readonly threadRef: ScopedThreadRef;
   readonly url: string;
   readonly openPreview: OpenPreviewMutation<E>;
-}): Promise<AtomCommandResult<void, E>> {
-  const defaults = await resolveBrowserDefaults();
+}): Promise<AtomCommandResult<void, E | BrowserSettingsReadError>> {
+  const defaults = await resolveBrowserDefaults().catch(
+    (cause: unknown) => new BrowserSettingsReadError({ cause }),
+  );
+  if (defaults instanceof BrowserSettingsReadError) {
+    return AsyncResult.failure(Cause.fail(defaults));
+  }
   const result = await input.openPreview({
     environmentId: input.threadRef.environmentId,
     input: {
@@ -82,7 +95,12 @@ export async function openFileInPreview<AssetError, PreviewError>(input: {
     readonly input: { readonly resource: AssetResource };
   }) => Promise<AtomCommandResult<AssetCreateUrlResult, AssetError>>;
   readonly openPreview: OpenPreviewMutation<PreviewError>;
-}): Promise<AtomCommandResult<void, AssetError | PreviewError | BrowserPreviewUnavailableError>> {
+}): Promise<
+  AtomCommandResult<
+    void,
+    AssetError | PreviewError | BrowserPreviewUnavailableError | BrowserSettingsReadError
+  >
+> {
   if (!isPreviewSupportedInRuntime()) {
     return AsyncResult.failure(
       Cause.fail(
diff --git a/apps/web/src/browser/useOpenLink.ts b/apps/web/src/browser/useOpenLink.ts
index 0e9bf721f82d..2a1d122eedbf 100644
--- a/apps/web/src/browser/useOpenLink.ts
+++ b/apps/web/src/browser/useOpenLink.ts
@@ -1,5 +1,8 @@
 import type { ScopedThreadRef } from "@t3tools/contracts";
-import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
 import { useCallback } from "react";
 
 import { recordVisitForThread } from "~/browserHistoryStore";
@@ -12,7 +15,7 @@ import {
   resolveBrowserLinkTargetPreference,
   resolveLinkTarget,
 } from "./browserLinkTarget";
-import { openUrlInPreview } from "./openFileInPreview";
+import { BrowserSettingsReadError, openUrlInPreview } from "./openFileInPreview";
 
 const NO_MODIFIER = { metaKey: false, ctrlKey: false } as const;
 
@@ -24,8 +27,8 @@ const NO_MODIFIER = { metaKey: false, ctrlKey: false } as const;
  *
  * An in-app open that fails falls back to the system browser rather than
  * dropping the click: the user asked for the link, and the setting only says
- * where it should go first. The returned promise rejects only when that
- * fallback fails too, the same way `shell.openExternal` does.
+ * where it should go first. Failed settings reads reject without opening a
+ * browser. The promise also rejects if the system-browser fallback fails.
  */
 export function useOpenLink(threadRef: ScopedThreadRef | null | undefined): (
   url: string,
@@ -52,6 +55,8 @@ export function useOpenLink(threadRef: ScopedThreadRef | null | undefined): (
           recordVisitForThread(targetThreadRef, url);
           return;
         }
+        const failure = squashAtomCommandFailure(result);
+        if (failure instanceof BrowserSettingsReadError) throw failure;
         console.error(result.cause);
       }
       const api = readLocalApi();
diff --git a/apps/web/src/clientPersistenceStorage.test.ts b/apps/web/src/clientPersistenceStorage.test.ts
index db69fe96c80a..a86177b48eb3 100644
--- a/apps/web/src/clientPersistenceStorage.test.ts
+++ b/apps/web/src/clientPersistenceStorage.test.ts
@@ -52,22 +52,45 @@ describe("clientPersistenceStorage", () => {
     expect(readBrowserClientSettings()).toEqual(settings);
   });
 
-  it("reports structured decode failures while preserving the fallback", async () => {
+  it.each(["not-json", '{"wordWrap":"invalid"}'])(
+    "does not treat invalid saved settings as absent: %s",
+    async (value) => {
+      const testWindow = getTestWindow();
+      testWindow.localStorage.setItem("t3code:client-settings:v1", value);
+      const { readBrowserClientSettings } = await import("./clientPersistenceStorage");
+
+      expect(() => readBrowserClientSettings()).toThrow(
+        expect.objectContaining({
+          _tag: "LocalStorageOperationError",
+          operation: "decode",
+          storageKey: "t3code:client-settings:v1",
+        }),
+      );
+      expect(testWindow.localStorage.getItem("t3code:client-settings:v1")).toBe(value);
+    },
+  );
+
+  it("preserves saved settings across a transient read failure", async () => {
     const testWindow = getTestWindow();
-    testWindow.localStorage.setItem("t3code:client-settings:v1", "not-json");
-    const consoleError = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const settings = { ...DEFAULT_CLIENT_SETTINGS, timestampFormat: "12-hour" as const };
+    testWindow.localStorage.setItem("t3code:client-settings:v1", JSON.stringify(settings));
+    const write = vi.spyOn(testWindow.localStorage, "setItem");
+    const failure = new Error("storage unavailable");
+    vi.spyOn(testWindow.localStorage, "getItem").mockImplementationOnce(() => {
+      throw failure;
+    });
     const { readBrowserClientSettings } = await import("./clientPersistenceStorage");
 
-    expect(readBrowserClientSettings()).toBeNull();
-    expect(consoleError).toHaveBeenCalledWith(
-      "Could not read persisted client settings.",
+    expect(() => readBrowserClientSettings()).toThrow(
       expect.objectContaining({
         _tag: "LocalStorageOperationError",
-        operation: "decode",
+        operation: "read",
         storageKey: "t3code:client-settings:v1",
-        cause: expect.anything(),
+        cause: failure,
       }),
     );
+    expect(readBrowserClientSettings()).toEqual(settings);
+    expect(write).not.toHaveBeenCalled();
   });
 
   it("defaults word wrap on and discards obsolete wrapping preferences", async () => {
diff --git a/apps/web/src/clientPersistenceStorage.ts b/apps/web/src/clientPersistenceStorage.ts
index 5c0ba7c6eccf..f39ea63c5a7c 100644
--- a/apps/web/src/clientPersistenceStorage.ts
+++ b/apps/web/src/clientPersistenceStorage.ts
@@ -13,12 +13,7 @@ export function readBrowserClientSettings(): ClientSettings | null {
     return null;
   }
 
-  try {
-    return getLocalStorageItem(CLIENT_SETTINGS_STORAGE_KEY, ClientSettingsSchema);
-  } catch (error) {
-    console.error("Could not read persisted client settings.", error);
-    return null;
-  }
+  return getLocalStorageItem(CLIENT_SETTINGS_STORAGE_KEY, ClientSettingsSchema);
 }
 
 export function writeBrowserClientSettings(settings: ClientSettings): void {
diff --git a/apps/web/src/cloud/linkEnvironment.test.ts b/apps/web/src/cloud/linkEnvironment.test.ts
index 7ae5e7ed03a9..3ae0dbd74289 100644
--- a/apps/web/src/cloud/linkEnvironment.test.ts
+++ b/apps/web/src/cloud/linkEnvironment.test.ts
@@ -26,10 +26,7 @@ import { remoteHttpClientLayer } from "@t3tools/client-runtime/rpc";
 import { __resetDesktopPrimaryAuthForTests } from "../environments/primary/desktopAuth";
 
 import {
-  collectCloudLinkTargets,
   linkPrimaryEnvironmentToCloud,
-  listManagedCloudEnvironments,
-  normalizeRelayBaseUrl,
   readPrimaryCloudLinkState,
   type CloudLinkTarget,
   unlinkPrimaryEnvironmentFromCloud,
@@ -155,48 +152,6 @@ afterEach(() => {
 });
 
 describe("web cloud link environment client", () => {
-  it("normalizes relay URLs and de-duplicates cloud link targets", () => {
-    expect(normalizeRelayBaseUrl(" https://relay.example.test/// ")).toBe(
-      "https://relay.example.test",
-    );
-    expect(normalizeRelayBaseUrl(" ")).toBeNull();
-    expect(
-      collectCloudLinkTargets({
-        primary: TARGET,
-        saved: [TARGET, { ...TARGET, environmentId: "environment-2" }],
-      }).map((target) => target.environmentId),
-    ).toEqual(["environment-1", "environment-2"]);
-  });
-
-  it.effect("lists relay-managed environments through the typed relay client", () =>
-    Effect.gen(function* () {
-      const fetchMock = vi.fn().mockResolvedValue(
-        Response.json({
-          environments: [
-            {
-              environmentId: "environment-1",
-              label: "Desktop",
-              endpoint: {
-                httpBaseUrl: "https://desktop.example.test",
-                wsBaseUrl: "wss://desktop.example.test",
-                providerKind: "cloudflare_tunnel",
-              },
-              linkedAt: "2026-06-06T00:00:00.000Z",
-            },
-          ],
-        }),
-      );
-      vi.stubGlobal("fetch", fetchMock);
-
-      const environments = yield* withServices(
-        listManagedCloudEnvironments({ clerkToken: "clerk-token" }),
-      );
-
-      expect(environments).toHaveLength(1);
-      expect(fetchMock.mock.calls[0]?.[1]?.headers.authorization).toBe("Bearer clerk-token");
-    }),
-  );
-
   it.effect("reads primary cloud link state from the explicit target", () =>
     Effect.gen(function* () {
       const fetchMock = vi.fn().mockResolvedValue(
diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts
index 29353e480f50..f88e7863969d 100644
--- a/apps/web/src/cloud/linkEnvironment.ts
+++ b/apps/web/src/cloud/linkEnvironment.ts
@@ -16,7 +16,6 @@ import {
   WS_METHODS,
 } from "@t3tools/contracts";
 import {
-  type RelayClientEnvironmentRecord,
   type RelayEnvironmentLinkResponse,
   type RelayManagedEndpointProviderKind,
 } from "@t3tools/contracts/relay";
@@ -33,14 +32,6 @@ import {
   requestRelayClientInstallConfirmation,
 } from "./relayClientInstallDialog";
 
-export function normalizeRelayBaseUrl(value: string | null | undefined): string | null {
-  const trimmed = value?.trim();
-  if (!trimmed) {
-    return null;
-  }
-  return trimmed.replace(/\/+$/g, "");
-}
-
 function relayUrl(): string | null {
   return resolveCloudPublicConfig().relayUrl;
 }
@@ -194,53 +185,6 @@ export interface CloudLinkTarget {
 
 export type CloudLinkState = EnvironmentCloudLinkStateResult;
 
-export function collectCloudLinkTargets(input: {
-  readonly primary: CloudLinkTarget | null;
-  readonly saved: ReadonlyArray<CloudLinkTarget>;
-}): ReadonlyArray<CloudLinkTarget> {
-  const byId = new Map<string, CloudLinkTarget>();
-  if (input.primary) {
-    byId.set(input.primary.environmentId, input.primary);
-  }
-  for (const environment of input.saved) {
-    if (!byId.has(environment.environmentId)) {
-      byId.set(environment.environmentId, environment);
-    }
-  }
-  return [...byId.values()];
-}
-
-export function listManagedCloudEnvironments(input: {
-  readonly clerkToken: string;
-}): Effect.Effect<
-  ReadonlyArray<RelayClientEnvironmentRecord>,
-  CloudEnvironmentLinkError,
-  ManagedRelay.ManagedRelayClient
-> {
-  return Effect.gen(function* () {
-    const configuredRelayUrl = relayUrl();
-    if (!configuredRelayUrl) {
-      return yield* new CloudEnvironmentLinkError({
-        message: "T3CODE_RELAY_URL is not configured.",
-      });
-    }
-    const relayClient = yield* ManagedRelay.ManagedRelayClient;
-    return yield* relayClient
-      .listEnvironments({
-        clerkToken: input.clerkToken,
-      })
-      .pipe(
-        Effect.mapError(
-          (cause) =>
-            new CloudEnvironmentLinkError({
-              message: "Could not list relay-managed environments.",
-              cause,
-            }),
-        ),
-      );
-  });
-}
-
 export function readPrimaryCloudLinkState(input: {
   readonly target: CloudLinkTarget;
 }): Effect.Effect<CloudLinkState | null, CloudEnvironmentLinkError, HttpClient.HttpClient> {
diff --git a/apps/web/src/components/AppSidebarLayout.tsx b/apps/web/src/components/AppSidebarLayout.tsx
index 3bef170bcf51..6769586f7fa8 100644
--- a/apps/web/src/components/AppSidebarLayout.tsx
+++ b/apps/web/src/components/AppSidebarLayout.tsx
@@ -15,7 +15,11 @@ import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings"
 import { cn, isMacPlatform } from "../lib/utils";
 import { primaryServerKeybindingsAtom } from "../state/server";
 import { useEnvironmentIdentificationMode, useLegacySidebarEnabled } from "../hooks/useSettings";
-import { usePanelAnimationSettings } from "../panelAnimations";
+import {
+  PanelAnimationSuppressionProvider,
+  usePanelAnimationSettings,
+  usePanelNavigationSuppression,
+} from "../panelAnimations";
 import LegacyThreadSidebar from "./LegacySidebar";
 import ThreadSidebar from "./Sidebar";
 import { SettingsSidebarNav } from "./settings/SettingsSidebarNav";
@@ -145,6 +149,8 @@ export function AppSidebarLayout({ children }: { children: ReactNode }) {
   // Settings routes show the settings nav in place of whichever thread
   // sidebar is active.
   const pathname = useLocation({ select: (location) => location.pathname });
+  const panelAnimationsSuppressed = usePanelNavigationSuppression(pathname);
+  const routePanelAnimationsActive = panelAnimationsActive && !panelAnimationsSuppressed;
   const isOnSettings = pathname === "/settings" || pathname.startsWith("/settings/");
   const isMacosDesktop = isElectron && isMacPlatform(navigator.platform);
   const [sidebarWidth, setSidebarWidth] = useState(readInitialThreadSidebarWidth);
@@ -213,42 +219,44 @@ export function AppSidebarLayout({ children }: { children: ReactNode }) {
   }, [navigate, pathname]);
 
   return (
-    <SidebarProvider
-      className="h-dvh! min-h-0!"
-      data-panel-animations={panelAnimationsActive ? "true" : "false"}
-      defaultOpen
-      style={sidebarProviderStyle}
-    >
-      <ProjectProjectionRetention />
-      <Sidebar
-        side="left"
-        collapsible="offcanvas"
-        data-app-sidebar=""
-        className="border-r border-sidebar-border bg-sidebar text-sidebar-foreground"
-        resizable={{
-          maxWidth: sidebarMaximumWidth,
-          minWidth: THREAD_SIDEBAR_MIN_WIDTH,
-          shouldAcceptWidth: ({ currentWidth, nextWidth, wrapper }) =>
-            nextWidth <= currentWidth ||
-            wrapper.clientWidth - nextWidth >= THREAD_MAIN_CONTENT_MIN_WIDTH,
-          storageKey: THREAD_SIDEBAR_WIDTH_STORAGE_KEY,
-          onResize: setSidebarWidth,
-        }}
+    <PanelAnimationSuppressionProvider value={panelAnimationsSuppressed}>
+      <SidebarProvider
+        className="h-dvh! min-h-0!"
+        data-panel-animations={routePanelAnimationsActive ? "true" : "false"}
+        defaultOpen
+        style={sidebarProviderStyle}
       >
-        {isOnSettings ? (
-          <>
-            <SidebarChromeHeader isElectron={isElectron} />
-            <SettingsSidebarNav pathname={pathname} />
-          </>
-        ) : legacySidebarEnabled ? (
-          <LegacyThreadSidebar />
-        ) : (
-          <ThreadSidebar />
-        )}
-        <SidebarRail onDoubleClick={resetSidebarWidth} />
-      </Sidebar>
-      {children}
-      <SidebarControl />
-    </SidebarProvider>
+        <ProjectProjectionRetention />
+        <Sidebar
+          side="left"
+          collapsible="offcanvas"
+          data-app-sidebar=""
+          className="border-r border-sidebar-border bg-sidebar text-sidebar-foreground"
+          resizable={{
+            maxWidth: sidebarMaximumWidth,
+            minWidth: THREAD_SIDEBAR_MIN_WIDTH,
+            shouldAcceptWidth: ({ currentWidth, nextWidth, wrapper }) =>
+              nextWidth <= currentWidth ||
+              wrapper.clientWidth - nextWidth >= THREAD_MAIN_CONTENT_MIN_WIDTH,
+            storageKey: THREAD_SIDEBAR_WIDTH_STORAGE_KEY,
+            onResize: setSidebarWidth,
+          }}
+        >
+          {isOnSettings ? (
+            <>
+              <SidebarChromeHeader isElectron={isElectron} />
+              <SettingsSidebarNav pathname={pathname} />
+            </>
+          ) : legacySidebarEnabled ? (
+            <LegacyThreadSidebar />
+          ) : (
+            <ThreadSidebar />
+          )}
+          <SidebarRail onDoubleClick={resetSidebarWidth} />
+        </Sidebar>
+        {children}
+        <SidebarControl />
+      </SidebarProvider>
+    </PanelAnimationSuppressionProvider>
   );
 }
diff --git a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
index 5a868483b34f..c0fa463fe72a 100644
--- a/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
+++ b/apps/web/src/components/BranchToolbarEnvModeSelector.tsx
@@ -114,7 +114,7 @@ export const BranchToolbarEnvModeSelector = memo(function BranchToolbarEnvModeSe
           </span>
         </span>
       </SelectTrigger>
-      <SelectPopup {...composerFloatingLayerProps}>
+      <SelectPopup alignItemWithTrigger={false} {...composerFloatingLayerProps}>
         <SelectGroup>
           <SelectGroupLabel>Workspace</SelectGroupLabel>
           <SelectItem value="local">
diff --git a/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx b/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
index fabda55688bc..431805f2174b 100644
--- a/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
+++ b/apps/web/src/components/BranchToolbarEnvironmentSelector.tsx
@@ -102,7 +102,7 @@ export const BranchToolbarEnvironmentSelector = memo(function BranchToolbarEnvir
           </span>
         </span>
       </SelectTrigger>
-      <SelectPopup {...composerFloatingLayerProps}>
+      <SelectPopup alignItemWithTrigger={false} {...composerFloatingLayerProps}>
         <SelectGroup>
           <SelectGroupLabel>Run on</SelectGroupLabel>
           {availableEnvironments.map((env) => (
diff --git a/apps/web/src/components/ChatMarkdown.test.tsx b/apps/web/src/components/ChatMarkdown.test.tsx
index c3e536d70ae2..f4551a93088e 100644
--- a/apps/web/src/components/ChatMarkdown.test.tsx
+++ b/apps/web/src/components/ChatMarkdown.test.tsx
@@ -1,9 +1,38 @@
 import { EnvironmentId } from "@t3tools/contracts";
+import { act, type ComponentProps, type ReactNode } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
+import { create, type ReactTestRenderer } from "react-test-renderer";
 import { describe, expect, it, vi } from "vite-plus/test";
 
+import { getSyntaxHighlighterPromise } from "../lib/syntaxHighlighting";
+import { Button } from "./ui/button";
+import { setMarkdownTaskChecked } from "./files/filePreviewMode";
+
 vi.mock("@effect/atom-react", () => ({ useAtomValue: () => null }));
 vi.mock("../hooks/useTheme", () => ({ useTheme: () => ({ resolvedTheme: "dark" }) }));
+vi.mock("../hooks/useSettings", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../hooks/useSettings")>();
+  const settings = actual.getClientSettings();
+  return {
+    ...actual,
+    useClientSettings: (select?: (value: typeof settings) => unknown) =>
+      select ? select(settings) : settings,
+  };
+});
+vi.mock("./ui/tooltip", async () => {
+  const { cloneElement, isValidElement } = await import("react");
+  return {
+    Tooltip: ({ children }: { children: ReactNode }) => <>{children}</>,
+    TooltipTrigger({
+      render,
+      children,
+    }: ComponentProps<typeof import("./ui/tooltip").TooltipTrigger>) {
+      if (!isValidElement(render)) return <>{children}</>;
+      return children === undefined ? render : cloneElement(render, undefined, children);
+    },
+    TooltipPopup: () => null,
+  };
+});
 vi.mock("../state/use-atom-query-runner", () => ({ useAtomQueryRunner: () => vi.fn() }));
 vi.mock("../state/use-atom-command", () => ({ useAtomCommand: () => vi.fn() }));
 vi.mock("../state/session", async (importOriginal) => ({
@@ -35,6 +64,222 @@ import ChatMarkdown, {
   shouldUseMarkdownFileBrowserPrimaryAction,
 } from "./ChatMarkdown";
 
+function codeButton(renderer: ReactTestRenderer, label: string) {
+  const button = renderer.root
+    .findAllByType(Button)
+    .find((instance) => instance.props["aria-label"] === label);
+  if (!button) throw new Error(`Missing code button: ${label}`);
+  return button.props as ComponentProps<typeof Button>;
+}
+
+describe("ChatMarkdown favicon privacy", () => {
+  it("suppresses private link images while preserving public links across updates", async () => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    let renderer: ReactTestRenderer | undefined;
+    const markdown = (url: string) => <ChatMarkdown cwd="/tmp/project" text={`[Link](${url})`} />;
+    try {
+      await act(async () => {
+        renderer = create(markdown("https://github.com"));
+      });
+      expect(renderer!.root.findAllByType("img").map((image) => image.props.src)).toEqual([
+        "https://www.google.com/s2/favicons?domain=github.com&sz=32",
+      ]);
+      for (const url of ["http://192.168.1.10:8080", "http://localhost:3000", "http://home.arpa"]) {
+        await act(async () => {
+          renderer!.update(markdown(url));
+        });
+        expect(renderer!.root.findAllByType("img")).toHaveLength(0);
+      }
+      await act(async () => {
+        renderer!.update(markdown("https://github.com"));
+      });
+      expect(renderer!.root.findAllByType("img")).toHaveLength(1);
+    } finally {
+      await act(async () => {
+        renderer?.unmount();
+      });
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
+describe("ChatMarkdown streaming", () => {
+  it("recovers highlighting after a failed fence changes without resetting its controls", async () => {
+    const highlighter = await getSyntaxHighlighterPromise("text");
+    const codeToHtml = highlighter.codeToHtml.bind(highlighter);
+    let fail = true;
+    vi.spyOn(highlighter, "codeToHtml").mockImplementation((...args) => {
+      if (fail) throw new Error("Temporary highlighter failure");
+      return codeToHtml(...args);
+    });
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    let renderer: ReactTestRenderer | undefined;
+
+    try {
+      await act(async () => {
+        renderer = create(
+          <ChatMarkdown cwd="/tmp/project" text={"```text\ninitial\n```"} isStreaming />,
+        );
+      });
+      const mounted = renderer!;
+      const codeBlock = mounted.root.findByProps({ "data-language": "text" });
+      const initialWrap = codeBlock.props["data-wrap"] === "true";
+      const wrap = codeButton(mounted, initialWrap ? "Disable line wrap" : "Wrap lines");
+      await act(async () => {
+        wrap.onClick?.({} as Parameters<NonNullable<typeof wrap.onClick>>[0]);
+      });
+      expect(mounted.root.findAllByProps({ className: "chat-markdown-shiki" })).toHaveLength(0);
+
+      fail = false;
+      await act(async () => {
+        mounted.update(
+          <ChatMarkdown cwd="/tmp/project" text={"```text\nrecovered\n```"} isStreaming />,
+        );
+      });
+      expect(mounted.root.findAllByProps({ className: "chat-markdown-shiki" })).toHaveLength(1);
+      expect(mounted.root.findByProps({ "data-language": "text" })).toBe(codeBlock);
+      expect(codeBlock.props["data-wrap"]).toBe(String(!initialWrap));
+    } finally {
+      await act(async () => renderer?.unmount());
+      vi.unstubAllGlobals();
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("preserves code controls and details without highlighting an unchanged fence again", async () => {
+    const highlighter = await getSyntaxHighlighterPromise("text");
+    const highlight = vi.spyOn(highlighter, "codeToHtml");
+    const writeText = vi.fn(async (_text: string) => {});
+    vi.stubGlobal("navigator", { clipboard: { writeText } });
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    let renderer: ReactTestRenderer | undefined;
+    const text = [
+      "```text",
+      "First code block",
+      "```",
+      "",
+      "<details><summary>More</summary>",
+      "",
+      "Details content",
+      "",
+      "</details>",
+      "",
+      "Streaming reply",
+    ].join("\n");
+
+    try {
+      await act(async () => {
+        renderer = create(<ChatMarkdown cwd="/tmp/project" text={text} isStreaming />);
+      });
+      const mounted = renderer!;
+      const codeBlock = mounted.root.findByProps({ "data-language": "text" });
+      const initialWrap = codeBlock.props["data-wrap"] === "true";
+      const wrap = codeButton(mounted, initialWrap ? "Disable line wrap" : "Wrap lines");
+      const copy = codeButton(mounted, "Copy code");
+      await act(async () => {
+        wrap.onClick?.({} as Parameters<NonNullable<typeof wrap.onClick>>[0]);
+        copy.onClick?.({} as Parameters<NonNullable<typeof copy.onClick>>[0]);
+      });
+
+      const detailsButton = mounted.root.find(
+        (instance) =>
+          instance.type === "button" && instance.props["data-markdown-details-summary"] === "",
+      );
+      await act(async () => {
+        detailsButton.props.onClick({ nativeEvent: new Event("click") });
+      });
+      const details = mounted.root.findByProps({ "data-markdown-details": "" });
+      expect(details.props["data-markdown-details-open"]).toBe("true");
+      expect(writeText).toHaveBeenCalledWith("First code block\n");
+      expect(highlight).toHaveBeenCalledTimes(1);
+
+      for (let index = 0; index < 10; index += 1) {
+        await act(async () => {
+          mounted.update(<ChatMarkdown cwd="/tmp/project" text={`${text} ${index}`} isStreaming />);
+        });
+      }
+
+      expect(highlight).toHaveBeenCalledTimes(1);
+      expect(mounted.root.findByProps({ "data-language": "text" })).toBe(codeBlock);
+      expect(codeBlock.props["data-wrap"]).toBe(String(!initialWrap));
+      expect(mounted.root.findByProps({ "data-markdown-details": "" })).toBe(details);
+      expect(details.props["data-markdown-details-open"]).toBe("true");
+      await act(async () => {
+        mounted.update(
+          <ChatMarkdown
+            cwd="/tmp/project"
+            text={text.replace("First code block", "Updated code block")}
+            isStreaming
+          />,
+        );
+      });
+      const copyUpdated = codeButton(mounted, "Copied");
+      await act(async () => {
+        copyUpdated.onClick?.({} as Parameters<NonNullable<typeof copyUpdated.onClick>>[0]);
+      });
+      expect(writeText).toHaveBeenLastCalledWith("Updated code block\n");
+      expect(highlight).toHaveBeenCalledTimes(2);
+    } finally {
+      await act(async () => renderer?.unmount());
+      vi.useRealTimers();
+      vi.unstubAllGlobals();
+      vi.restoreAllMocks();
+    }
+  });
+
+  it("edits the current task text and marker after reusing a renderer", async () => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    let renderer: ReactTestRenderer | undefined;
+    let editedText: string | undefined;
+    const message = (text: string) => (
+      <ChatMarkdown
+        cwd="/tmp/project"
+        text={text}
+        onTaskListChange={({ markerOffset, checked }) => {
+          editedText = setMarkdownTaskChecked(text, markerOffset, checked);
+          renderer!.update(message(editedText));
+        }}
+      />
+    );
+
+    try {
+      await act(async () => {
+        renderer = create(message("- [ ] First\n- [ ] Second"));
+      });
+      const mounted = renderer!;
+      const originalInput = mounted.root.findAllByType("input")[1]!;
+      await act(async () => {
+        mounted.update(message("- [ ] A longer first task\n- [ ] Second"));
+      });
+
+      const input = mounted.root.findAllByType("input")[1]!;
+      const listItem = mounted.root.findAllByType("li")[1]!;
+      const { onChange } = input.props as ComponentProps<"input">;
+      if (!onChange) throw new Error("Task checkbox has no edit handler");
+      await act(async () => {
+        onChange({
+          currentTarget: {
+            checked: true,
+            closest: () => ({
+              dataset: { taskMarkerOffset: String(listItem.props["data-task-marker-offset"]) },
+            }),
+          },
+        } as unknown as Parameters<typeof onChange>[0]);
+      });
+
+      expect(input).toBe(originalInput);
+      expect(editedText).toBe("- [ ] A longer first task\n- [x] Second");
+      expect(mounted.root.findAllByType("input")[1]!.props.checked).toBe(true);
+    } finally {
+      await act(async () => renderer?.unmount());
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
 describe("canUseMarkdownFileShellActions", () => {
   const environmentId = EnvironmentId.make("environment-1");
 
@@ -92,6 +337,46 @@ describe("hasMarkdownFilePrimaryAction", () => {
   });
 });
 
+describe("ChatMarkdown skill chips", () => {
+  it("updates digit-leading skill labels when discovered skills change", async () => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    let renderer: ReactTestRenderer | undefined;
+    const text = "Use $2spec with a $20k budget.";
+    try {
+      await act(async () => {
+        renderer = create(<ChatMarkdown cwd="/tmp/project" text={text} />);
+      });
+      const mounted = renderer!;
+      const labels = (label: string) =>
+        mounted.root.findAllByType("span").filter((node) => node.children.includes(label));
+      expect(labels("2Spec")).toHaveLength(0);
+
+      await act(async () => {
+        mounted.update(
+          <ChatMarkdown
+            cwd="/tmp/project"
+            text={text}
+            skills={[
+              { name: "2spec", displayName: "2Spec" },
+              { name: "20k", displayName: "MoneySkill" },
+            ]}
+          />,
+        );
+      });
+      expect(labels("2Spec")).toHaveLength(1);
+      expect(labels("MoneySkill")).toHaveLength(0);
+
+      await act(async () => {
+        mounted.update(<ChatMarkdown cwd="/tmp/project" text={text} skills={[]} />);
+      });
+      expect(labels("2Spec")).toHaveLength(0);
+    } finally {
+      await act(async () => renderer?.unmount());
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
 describe("ChatMarkdown file option chips", () => {
   it("keeps the fallback button text selectable", () => {
     const html = renderToStaticMarkup(
diff --git a/apps/web/src/components/ChatMarkdown.tsx b/apps/web/src/components/ChatMarkdown.tsx
index 75127ea124e8..55de831a52e7 100644
--- a/apps/web/src/components/ChatMarkdown.tsx
+++ b/apps/web/src/components/ChatMarkdown.tsx
@@ -28,6 +28,7 @@ import type {
   ServerProviderSkill,
   ThreadLinkedPullRequest,
 } from "@t3tools/contracts";
+import { faviconUrlForOrigin } from "@t3tools/shared/favicon";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
@@ -51,6 +52,7 @@ import React, {
   Children,
   Suspense,
   type CSSProperties,
+  type ComponentProps,
   type ClipboardEvent as ReactClipboardEvent,
   type KeyboardEvent as ReactKeyboardEvent,
   type MouseEvent as ReactMouseEvent,
@@ -162,8 +164,10 @@ import {
   findProjectForChangeRequest,
   matchesLinkedPullRequestUrl,
   parseChangeRequestUrl,
+  pullRequestCandidateUrlFromReferenceAutolink,
   useOpenChangeRequestLink,
 } from "~/lib/openPullRequestLink";
+import { useOpenLink } from "../browser/useOpenLink";
 import { writeTextToClipboard } from "../hooks/useCopyToClipboard";
 import { isPreviewSupportedInRuntime } from "../previewStateStore";
 import { isAbsolutePath, resolvePathLinkTarget } from "../terminal-links";
@@ -172,8 +176,10 @@ import {
   openFileInPreview,
   openUrlInPreview,
   BrowserPreviewUnavailableError,
+  BrowserSettingsReadError,
 } from "../browser/openFileInPreview";
 import { resolveLinkTarget } from "../browser/browserLinkTarget";
+import { PullRequestLinkPreview } from "./pullRequest/PullRequestLinkPreview";
 
 interface ChatMarkdownProps {
   text: string;
@@ -353,6 +359,55 @@ type MarkdownImageHastNode = {
   children?: MarkdownImageHastNode[];
 };
 
+function meaningfulHastChildren(node: MarkdownImageHastNode): MarkdownImageHastNode[] {
+  return (node.children ?? []).filter(
+    (child) => !(child.type === "text" && (child as { value?: string }).value?.trim() === ""),
+  );
+}
+
+/**
+ * An image that is the only content of its block (optionally wrapped in a
+ * link) is almost always a screenshot or figure, so it gets a reserved slot
+ * while it loads. Images mixed with text or other images — badge rows, icons
+ * in a sentence — stay inline at their natural size, since a placeholder taller
+ * than the image would move the page more than the image itself does.
+ */
+/** Containers whose sole child image reads as a figure rather than part of a sentence. */
+const STANDALONE_IMAGE_BLOCKS = new Set([
+  "p",
+  "div",
+  "li",
+  "td",
+  "th",
+  "figure",
+  "center",
+  "blockquote",
+]);
+
+function soleImageDescendant(node: MarkdownImageHastNode): MarkdownImageHastNode | undefined {
+  const children = meaningfulHastChildren(node);
+  if (children.length !== 1) return undefined;
+  const only = children[0];
+  if (only?.type !== "element") return undefined;
+  if (only.tagName === "img") return only;
+  // A link, emphasis, or similar inline wrapper around the image still counts
+  // as long as nothing else shares the block.
+  return only.tagName === "a" || only.tagName === "strong" || only.tagName === "em"
+    ? soleImageDescendant(only)
+    : undefined;
+}
+
+function markStandaloneImages(node: MarkdownImageHastNode) {
+  // A raw `<img>` on its own line reaches the root without a paragraph.
+  if (node.type === "root" || (node.tagName && STANDALONE_IMAGE_BLOCKS.has(node.tagName))) {
+    const image = soleImageDescendant(node);
+    if (image) image.properties = { ...image.properties, dataStandalone: true };
+  }
+  node.children?.forEach((child) => {
+    if (child.type === "element") markStandaloneImages(child);
+  });
+}
+
 /** Carries authored image source metadata through the sanitizer to the image renderer. */
 function rehypePreserveImageSourceMeta() {
   return (tree: MarkdownImageHastNode) => {
@@ -370,6 +425,7 @@ function rehypePreserveImageSourceMeta() {
     };
 
     visit(tree);
+    markStandaloneImages(tree);
   };
 }
 
@@ -382,7 +438,12 @@ const CHAT_MARKDOWN_SANITIZE_SCHEMA = {
     blockquote: [...(defaultSchema.attributes?.blockquote ?? []), "dataAlert"],
     div: [...(defaultSchema.attributes?.div ?? []), ...CODEX_ARTIFACT_TEMPLATE_HAST_PROPERTIES],
     a: [...(defaultSchema.attributes?.a ?? []), "dataPullRequestAutolink"],
-    img: [...(defaultSchema.attributes?.img ?? []), "dataLocalSrc", "dataMarkdownTitle"],
+    img: [
+      ...(defaultSchema.attributes?.img ?? []),
+      "dataLocalSrc",
+      "dataMarkdownTitle",
+      "dataStandalone",
+    ],
   },
   protocols: {
     ...defaultSchema.protocols,
@@ -1130,16 +1191,17 @@ const failedFaviconHosts = new Set<string>();
 
 const MarkdownLinkFavicon = memo(function MarkdownLinkFavicon({ host }: { host: string }) {
   const [failedHost, setFailedHost] = useState<string | null>(null);
+  const faviconUrl = faviconUrlForOrigin(`https://${host}`);
   return (
     <span
       className="ms-[0.25em] me-[0.2em] inline-flex size-[14px] [vertical-align:-0.125em]"
       aria-hidden
     >
-      {failedHost === host || failedFaviconHosts.has(host) ? (
+      {faviconUrl === null || failedHost === host || failedFaviconHosts.has(host) ? (
         <GlobeIcon className={MARKDOWN_LINK_FAVICON_CLASS_NAME} />
       ) : (
         <img
-          src={`https://www.google.com/s2/favicons?domain=${encodeURIComponent(host)}&sz=32`}
+          src={faviconUrl}
           alt=""
           loading="lazy"
           draggable={false}
@@ -1195,7 +1257,6 @@ function authoredImageSizeStyle(
 }
 
 const CHAT_MARKDOWN_WORKSPACE_IMAGE_CLASS_NAME = cn(
-  CHAT_MARKDOWN_IMAGE_SIZE_CLASS_NAME,
   CHAT_MARKDOWN_MEDIA_LAYOUT_CLASS_NAME,
   CHAT_MARKDOWN_MEDIA_FRAME_CLASS_NAME,
 );
@@ -1237,13 +1298,26 @@ function expandableMarkdownImageProps(
   };
 }
 
+function ChatMarkdownMediaUnavailableLabel(props: {
+  readonly alt: string;
+  readonly kind?: "image" | "video" | undefined;
+}) {
+  const label = props.kind === "video" ? "Video unavailable" : "Image unavailable";
+  return (
+    <span className="inline-flex items-center gap-1.5">
+      <TriangleAlertIcon aria-hidden className="size-3.5 shrink-0" />
+      {props.alt.length > 0 ? `${label} · ${props.alt}` : label}
+    </span>
+  );
+}
+
+/** Inline chip for an image that sits in a line of text or can never load. */
 function ChatMarkdownImageFallback(props: {
   readonly alt: string;
   readonly copyMarkdown?: string | undefined;
   readonly kind?: "image" | "video";
-  readonly actionsSource?: MediaActionSource;
+  readonly actionsSource?: MediaActionSource | undefined;
 }) {
-  const label = props.kind === "video" ? "Video unavailable" : "Image unavailable";
   const content = (
     <span
       data-markdown-copy={props.copyMarkdown}
@@ -1252,10 +1326,7 @@ function ChatMarkdownImageFallback(props: {
         "rounded-md border border-border/40 bg-muted/40 px-2 py-1 text-xs text-muted-foreground",
       )}
     >
-      <span className="inline-flex items-center gap-1.5">
-        <TriangleAlertIcon aria-hidden className="size-3.5 shrink-0" />
-        {props.alt.length > 0 ? `${label} · ${props.alt}` : label}
-      </span>
+      <ChatMarkdownMediaUnavailableLabel alt={props.alt} kind={props.kind} />
     </span>
   );
   return props.actionsSource ? (
@@ -1265,6 +1336,144 @@ function ChatMarkdownImageFallback(props: {
   );
 }
 
+const CHAT_MARKDOWN_IMAGE_FRAME_CLASS_NAME = cn(
+  "aspect-video w-full overflow-hidden bg-muted/60",
+  CHAT_MARKDOWN_MEDIA_MAX_WIDTH_CLASS_NAME,
+  CHAT_MARKDOWN_MEDIA_FRAME_CLASS_NAME,
+);
+
+/**
+ * A standalone image holds a 16:9 slot (or its authored size) until it has
+ * decoded, and keeps that slot if it fails, so a timeline row moves at most
+ * once: when the natural size arrives. A bare `<img>` is zero height until
+ * then. Once decoded the image renders bare again so its box, hit area, and
+ * alignment are exactly the image's own. Inline images (badges, icons in a
+ * sentence) skip the slot: a placeholder taller than the image would move the
+ * page more than the image does.
+ *
+ * Callers key this on the file's identity, not its URL: a re-signed URL for
+ * the same file keeps the decoded image on screen while the new bytes arrive,
+ * and a different file starts from the slot again.
+ */
+function ChatMarkdownImage(props: {
+  /** Null while the URL is being resolved; the last decoded image stays up. */
+  readonly src: string | null;
+  readonly sourceFailed?: boolean | undefined;
+  readonly alt: string;
+  readonly copyMarkdown: string | undefined;
+  readonly standalone: boolean;
+  readonly className?: string | undefined;
+  readonly style?: CSSProperties | undefined;
+  /** Sanitized authored attributes (`id`, `align`, …) that fragment links and layout rely on. */
+  readonly imageProps?:
+    | Omit<ComponentProps<"img">, "src" | "alt" | "className" | "style">
+    | undefined;
+  readonly actionsSource: MediaActionSource;
+  readonly originalUrl?: string | undefined;
+  readonly onImageExpand?: ((preview: ExpandedImagePreview) => void) | undefined;
+}) {
+  const [loadedSrc, setLoadedSrc] = useState<string | null>(null);
+  const [failedSrc, setFailedSrc] = useState<string | null>(null);
+  const src = props.src ?? loadedSrc;
+  const failed = props.sourceFailed === true || (src !== null && failedSrc === src);
+  // A failure forgets the decoded image so the next URL loads behind the slot.
+  const settled = src !== null && !failed && (!props.standalone || loadedSrc !== null);
+  // Cached images are complete before `onLoad` can fire.
+  const markLoadedIfComplete = useCallback((image: HTMLImageElement | null) => {
+    if (image?.complete && image.naturalWidth > 0) setLoadedSrc(image.currentSrc || image.src);
+  }, []);
+  const imageEvents = (loadingSrc: string) => ({
+    onLoad: () => {
+      setLoadedSrc(loadingSrc);
+      setFailedSrc(null);
+    },
+    onError: () => {
+      setFailedSrc(loadingSrc);
+      setLoadedSrc(null);
+    },
+  });
+
+  if (settled) {
+    return (
+      <MediaActions source={props.actionsSource}>
+        <img
+          {...props.imageProps}
+          ref={markLoadedIfComplete}
+          src={src}
+          alt={props.alt}
+          data-markdown-copy={props.copyMarkdown}
+          decoding="async"
+          draggable={false}
+          className={cn(
+            CHAT_MARKDOWN_IMAGE_SIZE_CLASS_NAME,
+            props.className,
+            props.onImageExpand && "cursor-zoom-in",
+          )}
+          style={props.style}
+          {...expandableMarkdownImageProps(
+            props.onImageExpand,
+            src,
+            props.alt,
+            props.originalUrl,
+            props.actionsSource,
+          )}
+          {...imageEvents(src)}
+        />
+      </MediaActions>
+    );
+  }
+  if (!props.standalone) {
+    return failed ? (
+      <ChatMarkdownImageFallback
+        alt={props.alt}
+        copyMarkdown={props.copyMarkdown}
+        actionsSource={props.actionsSource}
+      />
+    ) : (
+      <span
+        id={props.imageProps?.id}
+        data-markdown-copy={props.copyMarkdown}
+        role="status"
+        aria-label="Loading image"
+        className={CHAT_MARKDOWN_MEDIA_LAYOUT_CLASS_NAME}
+      />
+    );
+  }
+  return (
+    <MediaActions source={props.actionsSource}>
+      <span
+        id={props.imageProps?.id}
+        data-markdown-copy={props.copyMarkdown}
+        className={cn(
+          CHAT_MARKDOWN_MEDIA_LAYOUT_CLASS_NAME,
+          CHAT_MARKDOWN_IMAGE_FRAME_CLASS_NAME,
+          "relative",
+        )}
+        style={props.style}
+        {...(failed
+          ? { role: "alert" as const }
+          : { role: "status" as const, "aria-label": "Loading image" })}
+      >
+        {failed ? (
+          <span className="flex size-full items-center justify-center p-2 text-center text-xs text-muted-foreground">
+            <ChatMarkdownMediaUnavailableLabel alt={props.alt} />
+          </span>
+        ) : src !== null ? (
+          <img
+            ref={markLoadedIfComplete}
+            src={src}
+            alt={props.alt}
+            decoding="async"
+            draggable={false}
+            className="invisible absolute inset-0 size-full"
+            {...imageEvents(src)}
+          />
+        ) : null}
+      </span>
+    </MediaActions>
+  );
+}
+
 function ChatMarkdownVideo(props: {
   readonly src: string | null;
   readonly alt: string;
@@ -1311,13 +1520,14 @@ export const ChatMarkdownAssetImage = memo(function ChatMarkdownAssetImage(props
   readonly alt: string;
   readonly copyMarkdown?: string;
   readonly srcFragment?: string;
+  /** Reserve a slot while loading; off for images that share a line with text. */
+  readonly standalone?: boolean | undefined;
   readonly style?: CSSProperties | undefined;
   readonly workspaceRoot?: string | undefined;
   readonly onImageExpand?: ((preview: ExpandedImagePreview) => void) | undefined;
 }) {
   const assetUrl = useAssetUrlState(props.environmentId, props.resource);
   const refreshAssetUrl = useAssetUrlRefresh(props.environmentId, props.resource);
-  const [failedUrl, setFailedUrl] = useState<string | null>(null);
   const resource = props.resource;
   const path =
     resource._tag === "media-file"
@@ -1362,56 +1572,19 @@ export const ChatMarkdownAssetImage = memo(function ChatMarkdownAssetImage(props
     );
   }
 
-  if (assetUrl._tag === "Failure" || (assetUrl._tag === "Success" && failedUrl === assetUrl.url)) {
-    return (
-      <ChatMarkdownImageFallback
-        alt={props.alt}
-        copyMarkdown={props.copyMarkdown}
-        kind={props.kind ?? "image"}
-        actionsSource={actionsSource}
-      />
-    );
-  }
-  if (assetUrl._tag !== "Success") {
-    return (
-      <MediaActions source={actionsSource}>
-        <span
-          data-markdown-copy={props.copyMarkdown}
-          role="status"
-          aria-label="Loading image"
-          className={cn(
-            CHAT_MARKDOWN_MEDIA_LAYOUT_CLASS_NAME,
-            "aspect-video w-64 max-w-full rounded-lg bg-muted/60",
-            CHAT_MARKDOWN_MEDIA_BOUNDS_CLASS_NAME,
-          )}
-          style={props.style}
-        />
-      </MediaActions>
-    );
-  }
   return (
-    <MediaActions source={actionsSource}>
-      <img
-        src={src ?? undefined}
-        alt={props.alt}
-        data-markdown-copy={props.copyMarkdown}
-        loading="lazy"
-        draggable={false}
-        className={cn(
-          CHAT_MARKDOWN_WORKSPACE_IMAGE_CLASS_NAME,
-          props.onImageExpand && "cursor-zoom-in",
-        )}
-        style={props.style}
-        {...expandableMarkdownImageProps(
-          props.onImageExpand,
-          src ?? assetUrl.url,
-          props.alt,
-          undefined,
-          actionsSource,
-        )}
-        onError={() => setFailedUrl(assetUrl.url)}
-      />
-    </MediaActions>
+    <ChatMarkdownImage
+      key={JSON.stringify([props.environmentId, props.resource, props.srcFragment])}
+      src={src}
+      sourceFailed={assetUrl._tag === "Failure"}
+      alt={props.alt}
+      copyMarkdown={props.copyMarkdown}
+      standalone={props.standalone ?? true}
+      className={CHAT_MARKDOWN_WORKSPACE_IMAGE_CLASS_NAME}
+      style={props.style}
+      actionsSource={actionsSource}
+      onImageExpand={props.onImageExpand}
+    />
   );
 });
 
@@ -1952,7 +2125,7 @@ function areMarkdownFileLinkPropsEqual(
   );
 }
 
-function ChatMarkdown({
+function useChatMarkdownState({
   text,
   cwd,
   threadRef,
@@ -1960,13 +2133,9 @@ function ChatMarkdown({
   onTaskListChange,
   isStreaming = false,
   skills = EMPTY_MARKDOWN_SKILLS,
-  className,
-  lineBreaks = false,
-  parseRawHtml = true,
   onUseArtifactTemplate,
   imageBaseDir,
   onImageExpand,
-  extraRemarkPlugins = EMPTY_REMARK_PLUGINS,
 }: ChatMarkdownProps) {
   const { resolvedTheme } = useTheme();
   const [localMediaPreview, setLocalMediaPreview] = useState<ExpandedImagePreview | null>(null);
@@ -2121,6 +2290,7 @@ function ChatMarkdown({
     event.clipboardData.setData("text/html", payload.html);
   }, []);
   const openChangeRequestLink = useOpenChangeRequestLink(threadRef);
+  const openDeferredMarkdownLink = useOpenLink(threadRef);
   // Subscribed rather than read at click time: the anchor has to decide
   // synchronously whether to intercept its `_blank`, and a subscription is what
   // makes a persisted "app" apply once settings hydrate after launch.
@@ -2188,6 +2358,18 @@ function ChatMarkdown({
       }
       return openUrlInPreview({ threadRef, url, openPreview }).then((result) => {
         if (result._tag === "Success") recordVisitForThread(threadRef, url);
+        else if (!isAtomCommandInterrupted(result)) {
+          const error = squashAtomCommandFailure(result);
+          if (error instanceof BrowserSettingsReadError) {
+            toastManager.add(
+              stackedThreadToast({
+                type: "error",
+                title: "Unable to open link in browser",
+                description: error.message,
+              }),
+            );
+          }
+        }
         return result;
       });
     },
@@ -2270,11 +2452,8 @@ function ChatMarkdown({
     },
     [cwd, findWorkspaceBasenameMatch, revealFileInFileManager],
   );
-  /* eslint-disable react/no-unstable-nested-components -- ReactMarkdown requires component
-   * renderers that close over this message's metadata. useMemo keeps them stable until that
-   * metadata changes. */
-  const markdownComponents = useMemo<Components>(() => {
-    const fileLinkChip = (
+  const fileLinkChip = useCallback(
+    (
       fileLinkMeta: MarkdownFileLinkMeta,
       copyMarkdown: string,
       className?: string,
@@ -2339,433 +2518,569 @@ function ChatMarkdown({
           className={className}
         />
       );
-    };
+    },
+    [
+      canUseShellActions,
+      fileLinkParentSuffixByPath,
+      openFileInPanel,
+      openInPreferredEditor,
+      openMarkdownFileInPreview,
+      openMarkdownMedia,
+      preferredEditorMenuLabel,
+      resolvedTheme,
+      revealInFileManagerLabel,
+      revealMarkdownFileInFileManager,
+      threadRef,
+    ],
+  );
 
-    return {
-      div({ node, children, ...props }) {
-        const artifactTemplate = artifactTemplateFromHastProperties(node?.properties);
-        if (artifactTemplate) {
-          return (
-            <CodexArtifactTemplateCard template={artifactTemplate} onUse={onUseArtifactTemplate} />
-          );
-        }
-        return <div {...props}>{children}</div>;
-      },
-      p({ node: _node, children, ...props }) {
-        return <p {...props}>{renderSkillInlineMarkdownChildren(children, skills)}</p>;
-      },
-      blockquote({ node: _node, children, ...props }) {
-        const alert =
-          GITHUB_ALERT_PRESENTATIONS[
-            String((props as Record<string, unknown>)["data-alert"] ?? "")
-          ];
-        if (!alert) {
-          return <blockquote {...props}>{children}</blockquote>;
-        }
-        // Not a <blockquote>: the stylesheet mutes those, and an alert's body is ordinary
-        // text under a colored title — which is how the host renders it.
-        return (
-          <div role="note" className={cn("my-1 border-l-2 pl-3", alert.borderClassName)}>
-            <p className={cn("flex items-center gap-1.5 font-medium", alert.titleClassName)}>
-              <alert.Icon aria-hidden className="size-3.5 shrink-0" />
-              {alert.label}
-            </p>
-            {children}
-          </div>
-        );
-      },
-      ol({ node, start, style, ...props }) {
-        const itemCount =
-          node?.children?.filter((child) => child.type === "element" && child.tagName === "li")
-            .length ?? 0;
-        const gutterStyle = orderedListGutterStyle(itemCount, start);
-        return (
-          <ol {...props} start={start} style={gutterStyle ? { ...style, ...gutterStyle } : style} />
-        );
-      },
-      li({ node, children, ...props }) {
-        const listItemStart = node?.position?.start.offset;
-        const markerOffset =
-          typeof listItemStart === "number" ? findTaskListMarkerOffset(text, listItemStart) : null;
-        return (
-          <li {...props} data-task-marker-offset={markerOffset ?? undefined}>
-            {renderSkillInlineMarkdownChildren(children, skills)}
-          </li>
-        );
-      },
-      input({ node: _node, type, checked, disabled: _disabled, ...props }) {
-        if (type !== "checkbox" || !onTaskListChange) {
-          return (
-            <input
-              {...props}
-              type={type}
-              checked={checked}
-              disabled={_disabled}
-              readOnly={type === "checkbox"}
-            />
-          );
-        }
-        return (
-          <input
-            {...props}
-            type="checkbox"
-            name="markdown-task"
-            aria-label="Toggle task"
-            checked={checked}
-            onChange={(event) => {
-              const markerOffset = Number(
-                event.currentTarget.closest("li")?.dataset.taskMarkerOffset,
+  const componentState = useMemo(
+    () => ({
+      cwd,
+      diffThemeName,
+      environmentId,
+      expandMedia,
+      fileLinkChip,
+      imageBaseDir,
+      inlineCodeFileLinkMetaByText,
+      isStreaming,
+      linkTargetPreference,
+      markdownFileLinkMetaByHref,
+      onTaskListChange,
+      onUseArtifactTemplate,
+      openChangeRequestLink,
+      openDeferredMarkdownLink,
+      openExternalLinkInPreview,
+      openMarkdownMedia,
+      projects,
+      resolveThreadPullRequest,
+      resolvedTheme,
+      serverConfig,
+      skills,
+      text,
+      threadRef,
+      updateThreadPullRequestLink,
+    }),
+    [
+      cwd,
+      diffThemeName,
+      environmentId,
+      expandMedia,
+      fileLinkChip,
+      imageBaseDir,
+      inlineCodeFileLinkMetaByText,
+      isStreaming,
+      linkTargetPreference,
+      markdownFileLinkMetaByHref,
+      onTaskListChange,
+      onUseArtifactTemplate,
+      openChangeRequestLink,
+      openDeferredMarkdownLink,
+      openExternalLinkInPreview,
+      openMarkdownMedia,
+      projects,
+      resolveThreadPullRequest,
+      resolvedTheme,
+      serverConfig,
+      skills,
+      text,
+      threadRef,
+      updateThreadPullRequestLink,
+    ],
+  );
+  return {
+    componentState,
+    handleCopy,
+    markdownUrlTransform,
+    localMediaPreview,
+    setLocalMediaPreview,
+  };
+}
+
+const ChatMarkdownRendererContext = React.createContext<
+  ReturnType<typeof useChatMarkdownState>["componentState"]
+>(null!);
+
+// Keep component types stable when streaming changes the message state.
+const CHAT_MARKDOWN_COMPONENTS = {
+  div: function MarkdownDiv({ node, children, ...props }) {
+    const { onUseArtifactTemplate } = use(ChatMarkdownRendererContext);
+    const artifactTemplate = artifactTemplateFromHastProperties(node?.properties);
+    if (artifactTemplate) {
+      return (
+        <CodexArtifactTemplateCard template={artifactTemplate} onUse={onUseArtifactTemplate} />
+      );
+    }
+    return <div {...props}>{children}</div>;
+  },
+  p: function MarkdownParagraph({ node: _node, children, ...props }) {
+    const { skills } = use(ChatMarkdownRendererContext);
+    return <p {...props}>{renderSkillInlineMarkdownChildren(children, skills)}</p>;
+  },
+  blockquote: function MarkdownBlockquote({ node: _node, children, ...props }) {
+    const alert =
+      GITHUB_ALERT_PRESENTATIONS[String((props as Record<string, unknown>)["data-alert"] ?? "")];
+    if (!alert) {
+      return <blockquote {...props}>{children}</blockquote>;
+    }
+    // Not a <blockquote>: the stylesheet mutes those, and an alert's body is ordinary
+    // text under a colored title — which is how the host renders it.
+    return (
+      <div role="note" className={cn("my-1 border-l-2 pl-3", alert.borderClassName)}>
+        <p className={cn("flex items-center gap-1.5 font-medium", alert.titleClassName)}>
+          <alert.Icon aria-hidden className="size-3.5 shrink-0" />
+          {alert.label}
+        </p>
+        {children}
+      </div>
+    );
+  },
+  ol: function MarkdownOrderedList({ node, start, style, ...props }) {
+    const itemCount =
+      node?.children?.filter((child) => child.type === "element" && child.tagName === "li")
+        .length ?? 0;
+    const gutterStyle = orderedListGutterStyle(itemCount, start);
+    return (
+      <ol {...props} start={start} style={gutterStyle ? { ...style, ...gutterStyle } : style} />
+    );
+  },
+  li: function MarkdownListItem({ node, children, ...props }) {
+    const { text, skills } = use(ChatMarkdownRendererContext);
+    const listItemStart = node?.position?.start.offset;
+    const markerOffset =
+      typeof listItemStart === "number" ? findTaskListMarkerOffset(text, listItemStart) : null;
+    return (
+      <li {...props} data-task-marker-offset={markerOffset ?? undefined}>
+        {renderSkillInlineMarkdownChildren(children, skills)}
+      </li>
+    );
+  },
+  input: function MarkdownInput({ node: _node, type, checked, disabled: _disabled, ...props }) {
+    const { onTaskListChange } = use(ChatMarkdownRendererContext);
+    if (type !== "checkbox" || !onTaskListChange) {
+      return (
+        <input
+          {...props}
+          type={type}
+          checked={checked}
+          disabled={_disabled}
+          readOnly={type === "checkbox"}
+        />
+      );
+    }
+    return (
+      <input
+        {...props}
+        type="checkbox"
+        name="markdown-task"
+        aria-label="Toggle task"
+        checked={checked}
+        onChange={(event) => {
+          const markerOffset = Number(event.currentTarget.closest("li")?.dataset.taskMarkerOffset);
+          if (!Number.isSafeInteger(markerOffset)) return;
+          onTaskListChange({ markerOffset, checked: event.currentTarget.checked });
+        }}
+      />
+    );
+  },
+  a: function MarkdownAnchor({ node, href, children, title: _title, ...props }) {
+    const {
+      cwd,
+      environmentId,
+      imageBaseDir,
+      markdownFileLinkMetaByHref,
+      threadRef,
+      openMarkdownMedia,
+      openChangeRequestLink,
+      openDeferredMarkdownLink,
+      linkTargetPreference,
+      openExternalLinkInPreview,
+      projects,
+      resolveThreadPullRequest,
+      serverConfig,
+      updateThreadPullRequestLink,
+      fileLinkChip,
+    } = use(ChatMarkdownRendererContext);
+    const citation = href ? parseAssistantCitationHref(href) : null;
+    if (citation) return <AssistantCitationChip citation={citation} />;
+    const normalizedHref = href ? normalizeMarkdownLinkHrefKey(href) : "";
+    const fileLinkMeta = normalizedHref
+      ? (markdownFileLinkMetaByHref.get(normalizedHref) ??
+        resolveMarkdownFileLinkMeta(normalizedHref, cwd, imageBaseDir ?? cwd))
+      : null;
+    if (!fileLinkMeta) {
+      const faviconHost = resolveExternalWebLinkHost(href);
+      const pullRequestAutolink = String(
+        (props as Record<string, unknown>)["data-pull-request-autolink"] ?? "",
+      );
+      const pullRequestCopy =
+        pullRequestAutolink === "commit"
+          ? /\/commit\/([0-9a-f]{40})$/iu.exec(href ?? "")?.[1]
+          : pullRequestAutolink === "reference"
+            ? plainHastText(node)
+            : undefined;
+      const isPullRequestAutolink = pullRequestCopy !== undefined;
+      const confirmBeforeOpen = pullRequestAutolink === "reference";
+      const pullRequestCandidateUrl =
+        confirmBeforeOpen && href ? pullRequestCandidateUrlFromReferenceAutolink(href) : href;
+      const pullRequestCandidate = pullRequestCandidateUrl
+        ? parseChangeRequestUrl(pullRequestCandidateUrl)
+        : null;
+      const pullRequestProject =
+        environmentId !== null &&
+        serverConfig?.environment.capabilities.pullRequests === true &&
+        pullRequestCandidate !== null
+          ? findProjectForChangeRequest(
+              projects.filter((project) => project.environmentId === environmentId),
+              pullRequestCandidate,
+            )
+          : undefined;
+      const pullRequestPreviewTarget =
+        environmentId === null || pullRequestProject === undefined || pullRequestCandidate === null
+          ? null
+          : {
+              environmentId,
+              input: {
+                projectId: pullRequestProject.id,
+                repository:
+                  pullRequestProject.repositoryIdentity?.displayName ??
+                  pullRequestCandidate.repository,
+                number: pullRequestCandidate.number,
+              },
+            };
+      const isSameDocumentLink = href?.startsWith("#") ?? false;
+      const onClick = props.onClick;
+      const canOpenInPreview = Boolean(threadRef) && isPreviewSupportedInRuntime();
+      const linkChildren = <MarkdownLinkContext value>{children}</MarkdownLinkContext>;
+      const link = (
+        <a
+          {...props}
+          className={cn(props.className, pullRequestAutolink === "commit" && "font-mono")}
+          data-markdown-copy={pullRequestCopy}
+          href={href}
+          target={isSameDocumentLink ? undefined : "_blank"}
+          rel={isSameDocumentLink ? undefined : "noopener noreferrer"}
+          onClick={(event) => {
+            onClick?.(event);
+            if (isSameDocumentLink && href) {
+              handleMarkdownFragmentClick(event, href);
+              return;
+            }
+            if (
+              href &&
+              faviconHost !== null &&
+              mediaKindFromPath(href) !== null &&
+              !event.defaultPrevented &&
+              !event.metaKey &&
+              !event.ctrlKey &&
+              !event.shiftKey &&
+              !event.altKey
+            ) {
+              event.preventDefault();
+              event.stopPropagation();
+              openMarkdownMedia(href);
+              return;
+            }
+            // A link to a change request in a workspace project opens beside the
+            // conversation instead of in a browser: it is the thing being talked about, and
+            // the panel it opens offers the browser as one of its actions.
+            if (!href || openChangeRequestLink(event, href)) return;
+            // Anything else follows the "Open links in" setting. The system browser
+            // keeps the `_blank` the shell already handles; the in-app browser needs
+            // the click intercepted here. A modifier click is the way out of the
+            // in-app default, so it is left to the shell too.
+            if (
+              event.defaultPrevented ||
+              resolveLinkTarget({
+                url: href,
+                event,
+                preference: linkTargetPreference,
+                canOpenInApp: canOpenInPreview,
+              }) !== "app"
+            ) {
+              return;
+            }
+            event.preventDefault();
+            event.stopPropagation();
+            // Keep the link here if saved settings could not be read.
+            void openExternalLinkInPreview(href).then((result) => {
+              if (result._tag === "Success" || isAtomCommandInterrupted(result)) return;
+              reportMarkdownActionFailure(
+                { operation: "open-link-in-preview", target: href },
+                result.cause,
               );
-              if (!Number.isSafeInteger(markerOffset)) return;
-              onTaskListChange({ markerOffset, checked: event.currentTarget.checked });
-            }}
-          />
-        );
-      },
-      a({ node, href, children, title: _title, ...props }) {
-        const citation = href ? parseAssistantCitationHref(href) : null;
-        if (citation) return <AssistantCitationChip citation={citation} />;
-        const normalizedHref = href ? normalizeMarkdownLinkHrefKey(href) : "";
-        const fileLinkMeta = normalizedHref
-          ? (markdownFileLinkMetaByHref.get(normalizedHref) ??
-            resolveMarkdownFileLinkMeta(normalizedHref, cwd, imageBaseDir ?? cwd))
-          : null;
-        if (!fileLinkMeta) {
-          const faviconHost = resolveExternalWebLinkHost(href);
-          const pullRequestAutolink = String(
-            (props as Record<string, unknown>)["data-pull-request-autolink"] ?? "",
-          );
-          const pullRequestCopy =
-            pullRequestAutolink === "commit"
-              ? /\/commit\/([0-9a-f]{40})$/iu.exec(href ?? "")?.[1]
-              : pullRequestAutolink === "reference"
-                ? plainHastText(node)
-                : undefined;
-          const isPullRequestAutolink = pullRequestCopy !== undefined;
-          const isSameDocumentLink = href?.startsWith("#") ?? false;
-          const onClick = props.onClick;
-          const canOpenInPreview = Boolean(threadRef) && isPreviewSupportedInRuntime();
-          const linkChildren = <MarkdownLinkContext value>{children}</MarkdownLinkContext>;
-          const link = (
-            <a
-              {...props}
-              className={cn(props.className, pullRequestAutolink === "commit" && "font-mono")}
-              data-markdown-copy={pullRequestCopy}
-              href={href}
-              target={isSameDocumentLink ? undefined : "_blank"}
-              rel={isSameDocumentLink ? undefined : "noopener noreferrer"}
-              onClick={(event) => {
-                onClick?.(event);
-                if (isSameDocumentLink && href) {
-                  handleMarkdownFragmentClick(event, href);
-                  return;
-                }
-                if (
-                  href &&
-                  faviconHost !== null &&
-                  mediaKindFromPath(href) !== null &&
-                  !event.defaultPrevented &&
-                  !event.metaKey &&
-                  !event.ctrlKey &&
-                  !event.shiftKey &&
-                  !event.altKey
-                ) {
-                  event.preventDefault();
-                  event.stopPropagation();
-                  openMarkdownMedia(href);
-                  return;
+              if (squashAtomCommandFailure(result) instanceof BrowserSettingsReadError) return;
+              void readLocalApi()?.shell.openExternal(href);
+            });
+          }}
+          onContextMenu={(event) => {
+            if (!href || !faviconHost) return;
+            event.preventDefault();
+            event.stopPropagation();
+            const api = readLocalApi();
+            if (!api) return;
+            const pullRequest = resolveThreadPullRequest(href);
+            const currentPullRequest =
+              threadRef === undefined ? null : readThreadShell(threadRef)?.linkedPullRequest;
+            const threadLinkAction =
+              currentPullRequest != null && matchesLinkedPullRequestUrl(currentPullRequest, href)
+                ? "unlink-from-thread"
+                : pullRequest === null
+                  ? undefined
+                  : "link-to-thread";
+            void showExternalLinkContextMenu({
+              href,
+              canOpenInPreview,
+              threadLinkAction,
+              position: { x: event.clientX, y: event.clientY },
+              showContextMenu: (items, position) => api.contextMenu.show(items, position),
+              openInPreview: async (target) => {
+                const result = await openExternalLinkInPreview(target);
+                if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+                  reportMarkdownActionFailure(
+                    { operation: "open-link-in-preview", target },
+                    result.cause,
+                  );
                 }
-                // A link to a change request in a workspace project opens beside the
-                // conversation instead of in a browser: it is the thing being talked about, and
-                // the panel it opens offers the browser as one of its actions.
-                if (!href || openChangeRequestLink(event, href)) return;
-                // Anything else follows the "Open links in" setting. The system browser
-                // keeps the `_blank` the shell already handles; the in-app browser needs
-                // the click intercepted here. A modifier click is the way out of the
-                // in-app default, so it is left to the shell too.
+              },
+              openExternal: (target) => api.shell.openExternal(target),
+              copyLink: (target) => writeTextToClipboard(target, "link"),
+              updateThreadLink: updateThreadPullRequestLink,
+              reportFailure: (operation, cause) => {
+                reportMarkdownActionFailure({ operation, target: href }, cause);
                 if (
-                  event.defaultPrevented ||
-                  resolveLinkTarget({
-                    url: href,
-                    event,
-                    preference: linkTargetPreference,
-                    canOpenInApp: canOpenInPreview,
-                  }) !== "app"
+                  operation === "link-pull-request-to-thread" ||
+                  operation === "unlink-pull-request-from-thread"
                 ) {
-                  return;
-                }
-                event.preventDefault();
-                event.stopPropagation();
-                // The click was taken from the shell, so an in-app open that fails
-                // hands the link to the system browser instead of dropping it.
-                void openExternalLinkInPreview(href).then((result) => {
-                  if (result._tag === "Success" || isAtomCommandInterrupted(result)) return;
-                  reportMarkdownActionFailure(
-                    { operation: "open-link-in-preview", target: href },
-                    result.cause,
+                  toastManager.add(
+                    stackedThreadToast({
+                      type: "error",
+                      title:
+                        operation === "link-pull-request-to-thread"
+                          ? "Unable to link pull request"
+                          : "Unable to unlink pull request",
+                      description: cause instanceof Error ? cause.message : "The request failed.",
+                    }),
                   );
-                  void readLocalApi()?.shell.openExternal(href);
-                });
-              }}
-              onContextMenu={(event) => {
-                if (!href || !faviconHost) return;
-                event.preventDefault();
-                event.stopPropagation();
-                const api = readLocalApi();
-                if (!api) return;
-                const pullRequest = resolveThreadPullRequest(href);
-                const currentPullRequest =
-                  threadRef === undefined ? null : readThreadShell(threadRef)?.linkedPullRequest;
-                const threadLinkAction =
-                  currentPullRequest != null &&
-                  matchesLinkedPullRequestUrl(currentPullRequest, href)
-                    ? "unlink-from-thread"
-                    : pullRequest === null
-                      ? undefined
-                      : "link-to-thread";
-                void showExternalLinkContextMenu({
-                  href,
-                  canOpenInPreview,
-                  threadLinkAction,
-                  position: { x: event.clientX, y: event.clientY },
-                  showContextMenu: (items, position) => api.contextMenu.show(items, position),
-                  openInPreview: async (target) => {
-                    const result = await openExternalLinkInPreview(target);
-                    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
-                      reportMarkdownActionFailure(
-                        { operation: "open-link-in-preview", target },
-                        result.cause,
-                      );
-                    }
-                  },
-                  openExternal: (target) => api.shell.openExternal(target),
-                  copyLink: (target) => writeTextToClipboard(target, "link"),
-                  updateThreadLink: updateThreadPullRequestLink,
-                  reportFailure: (operation, cause) => {
-                    reportMarkdownActionFailure({ operation, target: href }, cause);
-                    if (
-                      operation === "link-pull-request-to-thread" ||
-                      operation === "unlink-pull-request-from-thread"
-                    ) {
-                      toastManager.add(
-                        stackedThreadToast({
-                          type: "error",
-                          title:
-                            operation === "link-pull-request-to-thread"
-                              ? "Unable to link pull request"
-                              : "Unable to unlink pull request",
-                          description:
-                            cause instanceof Error ? cause.message : "The request failed.",
-                        }),
-                      );
-                    }
-                  },
-                });
-              }}
-            >
-              {faviconHost && hastHasText(node) && !isPullRequestAutolink ? (
-                <MarkdownExternalLinkContent host={faviconHost} plainText={plainHastText(node)}>
-                  {linkChildren}
-                </MarkdownExternalLinkContent>
-              ) : (
-                linkChildren
-              )}
-            </a>
-          );
-          if (!faviconHost || !href) {
-            return link;
-          }
-          return (
-            <Tooltip>
-              <TooltipTrigger render={link} />
-              <TooltipPopup
-                side="top"
-                className="max-w-[min(36rem,calc(100vw-2rem))] whitespace-normal leading-tight wrap-anywhere"
-              >
-                {href}
-              </TooltipPopup>
-            </Tooltip>
-          );
-        }
+                }
+              },
+            });
+          }}
+        >
+          {faviconHost && hastHasText(node) && !isPullRequestAutolink ? (
+            <MarkdownExternalLinkContent host={faviconHost} plainText={plainHastText(node)}>
+              {linkChildren}
+            </MarkdownExternalLinkContent>
+          ) : (
+            linkChildren
+          )}
+        </a>
+      );
+      if (!faviconHost || !href) {
+        return link;
+      }
+      if (pullRequestPreviewTarget !== null) {
+        return (
+          <PullRequestLinkPreview
+            link={link}
+            originalUrl={href}
+            target={pullRequestPreviewTarget}
+            confirmBeforeOpen={confirmBeforeOpen}
+            onOpenPullRequest={(targetUrl) =>
+              openChangeRequestLink(
+                {
+                  metaKey: false,
+                  ctrlKey: false,
+                  preventDefault: () => undefined,
+                  stopPropagation: () => undefined,
+                },
+                targetUrl,
+                undefined,
+                environmentId ?? undefined,
+              )
+            }
+            onOpenFallback={openDeferredMarkdownLink}
+          />
+        );
+      }
+      return (
+        <Tooltip>
+          <TooltipTrigger render={link} />
+          <TooltipPopup
+            side="top"
+            className="max-w-[min(36rem,calc(100vw-2rem))] whitespace-normal leading-tight wrap-anywhere"
+          >
+            {href}
+          </TooltipPopup>
+        </Tooltip>
+      );
+    }
 
+    return fileLinkChip(
+      fileLinkMeta,
+      `[${fileLinkMeta.basename}](${normalizedHref})`,
+      props.className,
+      normalizedHref,
+    );
+  },
+  code: function MarkdownCode({ node, children, className, ...props }) {
+    const { cwd, imageBaseDir, inlineCodeFileLinkMetaByText, fileLinkChip } = use(
+      ChatMarkdownRendererContext,
+    );
+    if (node?.properties?.dataInlineCode != null) {
+      const codeText = nodeToPlainText(children);
+      const fileLinkMeta =
+        inlineCodeFileLinkMetaByText.get(codeText.trim()) ??
+        resolveInlineCodeFileLinkMeta(codeText, cwd, imageBaseDir ?? cwd);
+      if (fileLinkMeta) {
         return fileLinkChip(
           fileLinkMeta,
-          `[${fileLinkMeta.basename}](${normalizedHref})`,
-          props.className,
-          normalizedHref,
+          `\`${codeText}\``,
+          undefined,
+          inlineCodeFilePathCandidate(codeText) ?? codeText.trim(),
         );
-      },
-      code({ node, children, className, ...props }) {
-        if (node?.properties?.dataInlineCode != null) {
-          const codeText = nodeToPlainText(children);
-          const fileLinkMeta =
-            inlineCodeFileLinkMetaByText.get(codeText.trim()) ??
-            resolveInlineCodeFileLinkMeta(codeText, cwd, imageBaseDir ?? cwd);
-          if (fileLinkMeta) {
-            return fileLinkChip(
-              fileLinkMeta,
-              `\`${codeText}\``,
-              undefined,
-              inlineCodeFilePathCandidate(codeText) ?? codeText.trim(),
-            );
-          }
-        }
+      }
+    }
+    return (
+      <code {...props} className={className}>
+        {children}
+      </code>
+    );
+  },
+  img: function MarkdownImage({ node, title, src, alt, ...props }) {
+    const { expandMedia, cwd, imageBaseDir, threadRef } = use(ChatMarkdownRendererContext);
+    const imageExpand = use(MarkdownLinkContext) ? undefined : expandMedia;
+    const localSrc = node?.properties?.dataLocalSrc;
+    const markdownTitle = node?.properties?.dataMarkdownTitle;
+    const standalone = node?.properties?.dataStandalone === true;
+    const authoredSrc = typeof localSrc === "string" ? localSrc : src;
+    const authoredTitle = typeof markdownTitle === "string" ? markdownTitle : title;
+    const srcString =
+      typeof authoredSrc === "string" ? normalizeMarkdownLinkDestination(authoredSrc) : "";
+    const classifiedSrc =
+      typeof localSrc === "string" ? srcString.replaceAll("\\", "/") : srcString;
+    const altText = alt ?? "";
+    const copyMarkdown = markdownImageCopy(altText, srcString, authoredTitle);
+    const { className, style: _style, width, height, ...imageProps } = props;
+    const authoredSizeStyle = authoredImageSizeStyle(width, height);
+    const imageSource = classifyMarkdownImageSource(classifiedSrc, imageBaseDir ?? cwd);
+    const kind = mediaKindFromPath(classifiedSrc) ?? "image";
+    if (imageSource._tag === "Direct") {
+      const mediaSrc = resolveProtocolRelativeMediaUrl(imageSource.uri);
+      const originalUrl =
+        resolveExternalWebLinkHost(imageSource.uri) !== null ? imageSource.uri : undefined;
+      const reference = mediaUrlReference(imageSource.uri);
+      const actionsSource: MediaActionSource = {
+        kind,
+        name: altText || kind,
+        src: mediaSrc,
+        ...(reference ? { reference } : {}),
+      };
+      if (kind === "video") {
         return (
-          <code {...props} className={className}>
-            {children}
-          </code>
+          <ChatMarkdownVideo
+            src={mediaSrc}
+            alt={altText}
+            copyMarkdown={copyMarkdown}
+            originalUrl={originalUrl}
+            style={authoredSizeStyle}
+            actionsSource={actionsSource}
+          />
         );
-      },
-      img: function MarkdownImage({ node, title, src, alt, ...props }) {
-        const imageExpand = use(MarkdownLinkContext) ? undefined : expandMedia;
-        const localSrc = node?.properties?.dataLocalSrc;
-        const markdownTitle = node?.properties?.dataMarkdownTitle;
-        const authoredSrc = typeof localSrc === "string" ? localSrc : src;
-        const authoredTitle = typeof markdownTitle === "string" ? markdownTitle : title;
-        const srcString =
-          typeof authoredSrc === "string" ? normalizeMarkdownLinkDestination(authoredSrc) : "";
-        const classifiedSrc =
-          typeof localSrc === "string" ? srcString.replaceAll("\\", "/") : srcString;
-        const altText = alt ?? "";
-        const copyMarkdown = markdownImageCopy(altText, srcString, authoredTitle);
-        const authoredSizeStyle = authoredImageSizeStyle(props.width, props.height);
-        const imageSource = classifyMarkdownImageSource(classifiedSrc, imageBaseDir ?? cwd);
-        const kind = mediaKindFromPath(classifiedSrc) ?? "image";
-        if (imageSource._tag === "Direct") {
-          const mediaSrc = resolveProtocolRelativeMediaUrl(imageSource.uri);
-          const originalUrl =
-            resolveExternalWebLinkHost(imageSource.uri) !== null ? imageSource.uri : undefined;
-          const reference = mediaUrlReference(imageSource.uri);
-          const actionsSource: MediaActionSource = {
-            kind,
-            name: altText || kind,
-            src: mediaSrc,
-            ...(reference ? { reference } : {}),
-          };
-          if (kind === "video") {
-            return (
-              <ChatMarkdownVideo
-                src={mediaSrc}
-                alt={altText}
-                copyMarkdown={copyMarkdown}
-                originalUrl={originalUrl}
-                style={authoredSizeStyle}
-                actionsSource={actionsSource}
-              />
-            );
-          }
-          return (
-            <MediaActions source={actionsSource}>
-              <img
-                {...props}
-                src={mediaSrc}
-                alt={altText}
-                loading="lazy"
-                className={cn(
-                  props.className,
-                  CHAT_MARKDOWN_IMAGE_SIZE_CLASS_NAME,
-                  imageExpand && "cursor-zoom-in",
-                )}
-                style={authoredSizeStyle}
-                {...expandableMarkdownImageProps(
-                  imageExpand,
-                  mediaSrc,
-                  altText,
-                  originalUrl,
-                  actionsSource,
-                )}
-              />
-            </MediaActions>
-          );
-        }
-        if (imageSource._tag === "WorkspaceFile" && threadRef) {
-          return (
-            <ChatMarkdownAssetImage
-              environmentId={threadRef.environmentId}
-              resource={{
-                _tag: "media-file",
-                threadId: threadRef.threadId,
-                path: imageSource.path,
-              }}
-              alt={altText}
-              kind={kind}
-              copyMarkdown={copyMarkdown}
-              srcFragment={markdownImageSourceFragment(classifiedSrc)}
-              style={authoredSizeStyle}
-              workspaceRoot={cwd}
-              onImageExpand={imageExpand}
-            />
-          );
-        }
-        return <ChatMarkdownImageFallback alt={altText} copyMarkdown={copyMarkdown} kind={kind} />;
-      },
-      table({ node: _node, ...props }) {
-        return <MarkdownTable {...props} />;
-      },
-      details({ node: _node, children, open: detailsOpen }) {
-        return <MarkdownDetails open={detailsOpen}>{children}</MarkdownDetails>;
-      },
-      pre({ node, children, ...props }) {
-        const codeBlock = extractCodeBlock(children);
-        if (!codeBlock) {
-          return <pre {...props}>{children}</pre>;
-        }
+      }
+      return (
+        <ChatMarkdownImage
+          key={mediaSrc}
+          src={mediaSrc}
+          alt={altText}
+          copyMarkdown={copyMarkdown}
+          standalone={standalone}
+          className={className}
+          style={authoredSizeStyle}
+          imageProps={imageProps}
+          actionsSource={actionsSource}
+          originalUrl={originalUrl}
+          onImageExpand={imageExpand}
+        />
+      );
+    }
+    if (imageSource._tag === "WorkspaceFile" && threadRef) {
+      return (
+        <ChatMarkdownAssetImage
+          environmentId={threadRef.environmentId}
+          resource={{
+            _tag: "media-file",
+            threadId: threadRef.threadId,
+            path: imageSource.path,
+          }}
+          alt={altText}
+          kind={kind}
+          copyMarkdown={copyMarkdown}
+          srcFragment={markdownImageSourceFragment(classifiedSrc)}
+          standalone={standalone}
+          style={authoredSizeStyle}
+          workspaceRoot={cwd}
+          onImageExpand={imageExpand}
+        />
+      );
+    }
+    return <ChatMarkdownImageFallback alt={altText} copyMarkdown={copyMarkdown} kind={kind} />;
+  },
+  table: function MarkdownTableRenderer({ node: _node, ...props }) {
+    return <MarkdownTable {...props} />;
+  },
+  details: function MarkdownDetailsRenderer({ node: _node, children, open: detailsOpen }) {
+    return <MarkdownDetails open={detailsOpen}>{children}</MarkdownDetails>;
+  },
+  pre: function MarkdownPre({ node, children, ...props }) {
+    const { resolvedTheme, diffThemeName, isStreaming } = use(ChatMarkdownRendererContext);
+    const codeBlock = extractCodeBlock(children);
+    if (!codeBlock) {
+      return <pre {...props}>{children}</pre>;
+    }
 
-        const language = extractFenceLanguage(codeBlock.className);
-        const fenceTitle = extractFenceTitle(extractPreCodeMeta(node));
-        return (
-          <MarkdownCodeBlock
-            code={codeBlock.code}
-            language={language}
-            fenceTitle={fenceTitle}
-            theme={resolvedTheme}
-          >
-            <RenderErrorBoundary fallback={<pre {...props}>{children}</pre>}>
-              <Suspense fallback={<pre {...props}>{children}</pre>}>
-                <SuspenseShikiCodeBlock
-                  className={codeBlock.className}
-                  code={codeBlock.code}
-                  themeName={diffThemeName}
-                  isStreaming={isStreaming}
-                />
-              </Suspense>
-            </RenderErrorBoundary>
-          </MarkdownCodeBlock>
-        );
-      },
-    };
-  }, [
-    canUseShellActions,
-    cwd,
-    diffThemeName,
-    fileLinkParentSuffixByPath,
-    inlineCodeFileLinkMetaByText,
-    imageBaseDir,
-    isStreaming,
-    linkTargetPreference,
-    markdownFileLinkMetaByHref,
-    onTaskListChange,
-    onUseArtifactTemplate,
-    onImageExpand,
-    expandMedia,
-    openMarkdownMedia,
-    openFileInPanel,
-    openInPreferredEditor,
-    openChangeRequestLink,
-    openExternalLinkInPreview,
-    openMarkdownFileInPreview,
-    preferredEditorMenuLabel,
-    resolveThreadPullRequest,
-    resolvedTheme,
-    revealMarkdownFileInFileManager,
-    revealInFileManagerLabel,
-    skills,
-    text,
-    threadRef,
-    updateThreadPullRequestLink,
-  ]);
-  /* eslint-enable react/no-unstable-nested-components */
+    const language = extractFenceLanguage(codeBlock.className);
+    const fenceTitle = extractFenceTitle(extractPreCodeMeta(node));
+    return (
+      <MarkdownCodeBlock
+        code={codeBlock.code}
+        language={language}
+        fenceTitle={fenceTitle}
+        theme={resolvedTheme}
+      >
+        <RenderErrorBoundary
+          resetKeys={[codeBlock.code, language, diffThemeName, isStreaming]}
+          fallback={<pre {...props}>{children}</pre>}
+        >
+          <Suspense fallback={<pre {...props}>{children}</pre>}>
+            <SuspenseShikiCodeBlock
+              className={codeBlock.className}
+              code={codeBlock.code}
+              themeName={diffThemeName}
+              isStreaming={isStreaming}
+            />
+          </Suspense>
+        </RenderErrorBoundary>
+      </MarkdownCodeBlock>
+    );
+  },
+} satisfies Components;
 
+function ChatMarkdown({
+  text,
+  className,
+  lineBreaks = false,
+  parseRawHtml = true,
+  extraRemarkPlugins = EMPTY_REMARK_PLUGINS,
+  ...props
+}: ChatMarkdownProps) {
+  const {
+    componentState,
+    handleCopy,
+    markdownUrlTransform,
+    localMediaPreview,
+    setLocalMediaPreview,
+  } = useChatMarkdownState({ text, ...props });
   const remarkPlugins = useMemo(
     () => [
       ...(lineBreaks ? CHAT_MARKDOWN_REMARK_PLUGINS_WITH_BREAKS : CHAT_MARKDOWN_REMARK_PLUGINS),
@@ -2785,15 +3100,17 @@ function ChatMarkdown({
       )}
       onCopy={handleCopy}
     >
-      <ReactMarkdown
-        remarkPlugins={remarkPlugins}
-        rehypePlugins={parseRawHtml ? CHAT_MARKDOWN_REHYPE_PLUGINS : undefined}
-        skipHtml={false}
-        components={markdownComponents}
-        urlTransform={markdownUrlTransform}
-      >
-        {text}
-      </ReactMarkdown>
+      <ChatMarkdownRendererContext value={componentState}>
+        <ReactMarkdown
+          remarkPlugins={remarkPlugins}
+          rehypePlugins={parseRawHtml ? CHAT_MARKDOWN_REHYPE_PLUGINS : undefined}
+          skipHtml={false}
+          components={CHAT_MARKDOWN_COMPONENTS}
+          urlTransform={markdownUrlTransform}
+        >
+          {text}
+        </ReactMarkdown>
+      </ChatMarkdownRendererContext>
       {localMediaPreview ? (
         <ExpandedImageDialog
           preview={localMediaPreview}
diff --git a/apps/web/src/components/ChatMarkdown.workspace-images.test.tsx b/apps/web/src/components/ChatMarkdown.workspace-images.test.tsx
index 39be0eedafe2..ad3e951d89a9 100644
--- a/apps/web/src/components/ChatMarkdown.workspace-images.test.tsx
+++ b/apps/web/src/components/ChatMarkdown.workspace-images.test.tsx
@@ -139,9 +139,10 @@ describe("ChatMarkdown workspace images", () => {
         path: "\\\\server\\share\\workspace-image.svg",
       },
     ]);
-    expect(html.match(/https:\/\/signed\.test\/workspace-image\.svg/g)).toHaveLength(4);
+    expect(html.match(/<img[^>]*src="https:\/\/signed\.test\/workspace-image\.svg"/g)).toHaveLength(
+      4,
+    );
     expect(html.match(/max-w-\[min\(100%,30rem\)\]/g)).toHaveLength(4);
-    expect(html.match(/max-h-\[30rem\]/g)).toHaveLength(4);
     expect(html).not.toContain("Image unavailable");
   });
 
@@ -203,23 +204,49 @@ describe("ChatMarkdown workspace images", () => {
     expect(loadedStyle).toHaveProperty(constraint, expectedValue);
   });
 
-  it("keeps all images baseline-aligned and workspace images inline", () => {
+  it("keeps images that share a line inline and lets a standalone one reserve a slot", () => {
     const html = render(
       "![remote](https://example.com/badge.svg) ![workspace](.t3/workspace-image.svg)",
     );
-    const classNames = Array.from(html.matchAll(/<img[^>]*class="([^"]*)"/g), (match) =>
-      match[1]?.split(" "),
-    );
 
-    expect(classNames).toHaveLength(2);
-    expect(classNames[1]).toContain("inline-block!");
+    // Two images in one paragraph are badges: neither reserves a slot.
+    expect(html).not.toContain("aspect-video");
+    expect(html).toContain('src="https://example.com/badge.svg"');
+    expect(html).toContain('src="https://signed.test/workspace-image.svg"');
+    expect(html.match(/<img[^>]*class="[^"]*inline-block![^"]*"/g)).toHaveLength(1);
+    expect(html).not.toContain("invisible");
 
     const centeredHtml = render(
       '<p align="center"><img src=".t3/workspace-image.svg" alt="logo"></p>',
     );
-    const centeredClassName = /<img[^>]*class="([^"]*)"/.exec(centeredHtml)?.[1];
+    const frame = /<span[^>]*role="status"[^>]*>/.exec(centeredHtml)?.[0];
+
+    expect(frame).toContain("inline-block!");
+    expect(frame).toContain("aspect-video");
+  });
+
+  it("reserves a slot for an image that is the only content of its link", () => {
+    const html = render("[![shot](.t3/workspace-image.svg)](https://example.com)");
+
+    expect(html).toContain("aspect-video");
+  });
+
+  it.each([
+    ["a link", "Figure: [![shot](.t3/workspace-image.svg)](https://example.com)"],
+    ["emphasis", "**![shot](.t3/workspace-image.svg)** caption"],
+  ])("keeps an image wrapped in %s inline when text shares its block", (_wrapper, markdown) => {
+    expect(render(markdown)).not.toContain("aspect-video");
+  });
+
+  it("keeps an authored id on a remote image so fragment links resolve", () => {
+    const html = render('<img id="diagram" src="https://example.com/diagram.png" alt="diagram">');
+
+    // The sanitizer prefixes authored ids; the loading slot carries it too.
+    expect(html).toContain('<span id="user-content-diagram"');
+  });
 
-    expect(centeredClassName?.split(" ")).toContain("inline-block!");
+  it("reserves a slot for an image that is alone in a list item", () => {
+    expect(render("- ![shot](.t3/workspace-image.svg)")).toContain("aspect-video");
   });
 
   it("retains an authored SVG fragment on the signed URL", () => {
@@ -278,15 +305,35 @@ describe("ChatMarkdown workspace images", () => {
     );
   });
 
-  it("uses a static bounded-width placeholder while a signed asset URL loads", () => {
+  it("reserves the same 16:9 frame while the URL, the bytes, and a failure resolve", () => {
+    const frameClassName = (html: string) => {
+      const frame = /<span[^>]*role="(?:status|alert)"[^>]*>/.exec(html)?.[0] ?? "";
+      return /class="([^"]*)"/.exec(frame)?.[1]?.split(" ") ?? [];
+    };
+    const markdown = "![shot](.t3/workspace-image.svg)";
+
     testState.assetState = "loading";
+    const loadingUrl = frameClassName(render(markdown));
+    testState.assetState = "success";
+    const loadingBytes = render(markdown);
+    testState.assetState = "failure";
+    const failure = render(markdown);
+
+    expect(loadingUrl).toEqual(expect.arrayContaining(["aspect-video", "w-full"]));
+    expect(loadingUrl).not.toContain("animate-pulse");
+    expect(frameClassName(loadingBytes)).toEqual(loadingUrl);
+    expect(frameClassName(failure)).toEqual(loadingUrl);
+    expect(failure).toContain("Image unavailable");
+    // The bytes are requested inside the frame but never paint at an unknown size.
+    expect(loadingBytes).toMatch(/<img[^>]*src="https:\/\/signed[^>]*class="invisible/);
+    expect(loadingBytes).not.toContain('loading="lazy"');
+  });
 
-    const html = render("![loading](.t3/workspace-image.svg)");
-    const className = /<span[^>]*aria-label="Loading image"[^>]*class="([^"]*)"/.exec(html)?.[1];
+  it("gives a standalone remote image the same frame instead of a bare tag", () => {
+    const html = render("![remote](https://example.com/shot.png)");
 
     expect(html).toContain('aria-label="Loading image"');
-    expect(html).not.toContain("animate-pulse");
-    expect(className?.split(" ")).toContain("w-64");
+    expect(html).toContain("aspect-video");
   });
 
   it("never passes a workspace source to a raw image when thread context is unavailable", () => {
@@ -313,7 +360,6 @@ describe("ChatMarkdown workspace images", () => {
     expect(testState.resources).toEqual([]);
     expect(html).toContain('src="https://example.com/image.png"');
     expect(html).toContain("max-w-[min(100%,30rem)]");
-    expect(html).toContain("max-h-[30rem]");
     expect(html).not.toContain("Image unavailable");
   });
 });
diff --git a/apps/web/src/components/ChatView.logic.test.ts b/apps/web/src/components/ChatView.logic.test.ts
index 8e9c80641f2b..a5a8503985b2 100644
--- a/apps/web/src/components/ChatView.logic.test.ts
+++ b/apps/web/src/components/ChatView.logic.test.ts
@@ -1,4 +1,5 @@
 import {
+  ANTIGRAVITY_DEFAULT_MODEL,
   CheckpointRef,
   EnvironmentId,
   MessageId,
@@ -40,6 +41,7 @@ import {
   resolveComposerInteractionMode,
   resolveComposerProviderSelection,
   resolveDraftPromotionNavigationTarget,
+  resolveProactiveTurnDiffAction,
   resolveThreadMetadataUpdateForNextTurn,
   resolveSendEnvMode,
   resolveDraftHeroState,
@@ -158,6 +160,80 @@ describe("proactive panels", () => {
       }),
     ).toBe(false);
   });
+
+  it("opens a completed turn diff only for changed files", () => {
+    const changedCheckpoint = {
+      status: "ready",
+      files: [{ path: "src/app.ts", kind: "modified", additions: 1, deletions: 0 }],
+    } satisfies Pick<TurnDiffSummary, "status" | "files">;
+    const unchangedCheckpoint = {
+      status: "ready",
+      files: [],
+    } satisfies Pick<TurnDiffSummary, "status" | "files">;
+
+    expect(
+      resolveProactiveTurnDiffAction({
+        checkpoint: changedCheckpoint,
+        isGitRepo: true,
+        activeSurfaceKind: null,
+      }),
+    ).toBe("open");
+    expect(
+      resolveProactiveTurnDiffAction({
+        checkpoint: unchangedCheckpoint,
+        isGitRepo: true,
+        activeSurfaceKind: null,
+      }),
+    ).toBe("ignore");
+  });
+
+  it("waits for definitive checkpoint and repository state", () => {
+    const missingCheckpoint = {
+      status: "missing",
+      files: [],
+    } satisfies Pick<TurnDiffSummary, "status" | "files">;
+    const changedCheckpoint = {
+      status: "ready",
+      files: [{ path: "src/app.ts", kind: "modified", additions: 1, deletions: 0 }],
+    } satisfies Pick<TurnDiffSummary, "status" | "files">;
+
+    expect(
+      resolveProactiveTurnDiffAction({
+        checkpoint: undefined,
+        isGitRepo: true,
+        activeSurfaceKind: null,
+      }),
+    ).toBe("defer");
+    expect(
+      resolveProactiveTurnDiffAction({
+        checkpoint: missingCheckpoint,
+        isGitRepo: true,
+        activeSurfaceKind: null,
+      }),
+    ).toBe("defer");
+    expect(
+      resolveProactiveTurnDiffAction({
+        checkpoint: changedCheckpoint,
+        isGitRepo: undefined,
+        activeSurfaceKind: null,
+      }),
+    ).toBe("defer");
+  });
+
+  it("keeps an active pull request above a completed turn diff", () => {
+    const changedCheckpoint = {
+      status: "ready",
+      files: [{ path: "src/app.ts", kind: "modified", additions: 1, deletions: 0 }],
+    } satisfies Pick<TurnDiffSummary, "status" | "files">;
+
+    expect(
+      resolveProactiveTurnDiffAction({
+        checkpoint: changedCheckpoint,
+        isGitRepo: true,
+        activeSurfaceKind: "pull-request",
+      }),
+    ).toBe("ignore");
+  });
 });
 
 describe("toolGroupConsumesUpwardNavigation", () => {
@@ -793,14 +869,20 @@ describe("resolveComposerProviderSelection", () => {
     );
   });
 
-  it("blocks sends until Antigravity confirms authentication", () => {
+  it("lets Antigravity check saved credentials when resuming after a restart", () => {
     const provider = entry("antigravity", "google_work", {
+      status: "warning",
       auth: { status: "unknown" },
-      models: catalogModels,
+      models: [],
     }).snapshot;
 
-    expect(getAntigravitySendBlockReason(provider, "gemini-pro")).toBe(
-      "Sign in to Antigravity in provider settings before sending.",
+    expect(getAntigravitySendBlockReason(provider, "gemini-pro")).toBeNull();
+    expect(getAntigravitySendBlockReason(provider, ANTIGRAVITY_DEFAULT_MODEL)).toBeNull();
+    expect(
+      getAntigravitySendBlockReason({ ...provider, models: catalogModels }, "gemini-pro"),
+    ).toBeNull();
+    expect(getAntigravitySendBlockReason(provider, "")).toBe(
+      "Choose an Antigravity model before sending.",
     );
   });
 
@@ -1007,6 +1089,56 @@ describe("buildRevertTurnCountByUserMessageId", () => {
       }).size,
     ).toBe(0);
   });
+
+  it.each([true, false])(
+    "returns the previous map when contents are unchanged (rollback supported: %s)",
+    (supportsConversationRollback) => {
+      const input = {
+        supportsConversationRollback,
+        timelineEntries,
+        turnDiffSummaryByAssistantMessageId,
+        inferredCheckpointTurnCountByTurnId: {},
+      };
+      const previous = buildRevertTurnCountByUserMessageId(input);
+      const streamed = timelineEntries.map((entry) =>
+        entry.message.role === "assistant"
+          ? { ...entry, message: { ...entry.message, text: "Updated the file again" } }
+          : entry,
+      );
+
+      expect(
+        buildRevertTurnCountByUserMessageId({ ...input, timelineEntries: streamed }, previous),
+      ).toBe(previous);
+    },
+  );
+
+  it("returns a new map when a revert target changes", () => {
+    const input = {
+      supportsConversationRollback: true,
+      timelineEntries,
+      turnDiffSummaryByAssistantMessageId,
+      inferredCheckpointTurnCountByTurnId: {},
+    };
+    const previous = buildRevertTurnCountByUserMessageId(input);
+    const next = buildRevertTurnCountByUserMessageId(
+      {
+        ...input,
+        turnDiffSummaryByAssistantMessageId: new Map([
+          [
+            assistantMessageId,
+            {
+              ...turnDiffSummaryByAssistantMessageId.get(assistantMessageId)!,
+              checkpointTurnCount: 3,
+            },
+          ],
+        ]),
+      },
+      previous,
+    );
+
+    expect(next).not.toBe(previous);
+    expect(next).toEqual(new Map([[userMessageId, 2]]));
+  });
 });
 
 describe("deriveComposerSendState", () => {
diff --git a/apps/web/src/components/ChatView.logic.ts b/apps/web/src/components/ChatView.logic.ts
index 1a6b1b775f41..bf576a3c7635 100644
--- a/apps/web/src/components/ChatView.logic.ts
+++ b/apps/web/src/components/ChatView.logic.ts
@@ -38,6 +38,7 @@ import {
 } from "../types";
 import { type ComposerImageAttachment, type DraftThreadState } from "../composerDraftStore";
 import * as Schema from "effect/Schema";
+import { shallow } from "zustand/vanilla/shallow";
 import { appAtomRegistry } from "../rpc/atomRegistry";
 import { environmentThreadDetails } from "../state/threads";
 import {
@@ -121,6 +122,24 @@ export function shouldOpenProactiveTurnDiff(input: {
   );
 }
 
+export function resolveProactiveTurnDiffAction(input: {
+  checkpoint: Pick<TurnDiffSummary, "status" | "files"> | undefined;
+  isGitRepo: boolean | undefined;
+  activeSurfaceKind: RightPanelSurface["kind"] | null;
+}): "defer" | "ignore" | "open" {
+  if (input.activeSurfaceKind === "pull-request") return "ignore";
+  if (input.checkpoint === undefined || input.checkpoint.status === "missing") return "defer";
+  if (input.isGitRepo === undefined) return "defer";
+  if (
+    !input.isGitRepo ||
+    input.checkpoint.status !== "ready" ||
+    input.checkpoint.files.length === 0
+  ) {
+    return "ignore";
+  }
+  return "open";
+}
+
 export function codexArtifactTemplatePromptToAppend(
   currentDraft: string,
   template: CodexArtifactTemplate,
@@ -421,14 +440,17 @@ export function getAntigravitySendBlockReason(
   if (!provider.installed) {
     return "Install Antigravity in provider settings before sending.";
   }
-  if (provider.auth.status !== "authenticated") {
+  if (provider.auth.status === "unauthenticated") {
     return "Sign in to Antigravity in provider settings before sending.";
   }
+  const slug = model.trim();
+  if (slug.length === 0) return "Choose an Antigravity model before sending.";
+  // A restart clears the account status and catalog. Session startup checks
+  // saved credentials and validates the model before sending the prompt.
+  if (provider.auth.status === "unknown") return null;
   if (provider.models.length === 0) {
     return "Refresh Antigravity models in provider settings before sending.";
   }
-  const slug = model.trim();
-  if (slug.length === 0) return "Choose an Antigravity model before sending.";
   // A saved model that left the catalog is kept in the picker as unavailable
   // so the user sees what the thread used. The server rejects it at turn
   // start, so block here unless the provider is in an error state, where a
@@ -443,17 +465,24 @@ export function getAntigravitySendBlockReason(
   return null;
 }
 
-export function buildRevertTurnCountByUserMessageId(input: {
-  supportsConversationRollback: boolean;
-  timelineEntries: ReadonlyArray<TimelineEntry>;
-  turnDiffSummaryByAssistantMessageId: ReadonlyMap<MessageId, TurnDiffSummary>;
-  inferredCheckpointTurnCountByTurnId: Readonly<Record<string, number | undefined>>;
-}) {
+/**
+ * Maps each user message to the checkpoint turn count a revert should target.
+ * Returns `previous` when the result is unchanged: streaming text deltas
+ * rebuild `timelineEntries` per token, and the timeline row projection only
+ * reuses rows while this Map keeps its identity.
+ */
+export function buildRevertTurnCountByUserMessageId(
+  input: {
+    supportsConversationRollback: boolean;
+    timelineEntries: ReadonlyArray<TimelineEntry>;
+    turnDiffSummaryByAssistantMessageId: ReadonlyMap<MessageId, TurnDiffSummary>;
+    inferredCheckpointTurnCountByTurnId: Readonly<Record<string, number | undefined>>;
+  },
+  previous: Map<MessageId, number> | null = null,
+): Map<MessageId, number> {
   const byUserMessageId = new Map<MessageId, number>();
-  if (!input.supportsConversationRollback) {
-    return byUserMessageId;
-  }
-  for (let index = 0; index < input.timelineEntries.length; index += 1) {
+  const entryCount = input.supportsConversationRollback ? input.timelineEntries.length : 0;
+  for (let index = 0; index < entryCount; index += 1) {
     const entry = input.timelineEntries[index];
     if (!entry || entry.kind !== "message" || entry.message.role !== "user") {
       continue;
@@ -480,7 +509,7 @@ export function buildRevertTurnCountByUserMessageId(input: {
       break;
     }
   }
-  return byUserMessageId;
+  return previous !== null && shallow(previous, byUserMessageId) ? previous : byUserMessageId;
 }
 
 export function reconcileMountedTerminalThreadIds(input: {
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 6cd83054b8e6..11226371172f 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -93,16 +93,19 @@ import {
   parseStandaloneComposerSlashCommand,
 } from "../composer-logic";
 import {
+  createMessageAttachmentPreviewProjector,
   derivePendingApprovals,
   derivePendingUserInputs,
   derivePhase,
-  deriveTimelineEntries,
+  deriveTimelineEntriesWithState,
   deriveActiveWorkStartedAt,
   deriveActivePlanState,
   findLatestProposedPlan,
   deriveWorkLogEntries,
   hasActionableProposedPlan,
   isLatestTurnSettled,
+  selectHandoffImageResources,
+  type TimelineEntriesProjection,
 } from "../session-logic";
 import { type LegendListRef } from "@legendapp/list/react";
 import {
@@ -159,6 +162,7 @@ import {
   useThreadPreviewState,
 } from "../previewStateStore";
 import { previewRuntimeTabId } from "../browser/previewRuntimeTabId";
+import { BrowserSettingsReadError } from "../browser/openFileInPreview";
 import { addBrowserSurface } from "./preview/addBrowserSurface";
 import { closePreviewSession } from "./preview/closePreviewSession";
 import { ThreadPreviewMiniPlayer } from "./preview/ThreadPreviewMiniPlayer";
@@ -179,7 +183,6 @@ import {
   deriveAgentPanelModel,
   foldSubagentActivities,
 } from "@t3tools/client-runtime/state/subagentRuntime";
-import { DiffWorkerPoolProvider } from "./DiffWorkerPoolProvider";
 import { BranchToolbar } from "./BranchToolbar";
 import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings";
 import ThreadTerminalDrawer from "./ThreadTerminalDrawer";
@@ -220,6 +223,7 @@ import {
 import { useNowMinute } from "../hooks/useNowMinute";
 import { usePanelAnimationSettings, usePanelPresence } from "../panelAnimations";
 import { useNewThreadHandler } from "../hooks/useHandleNewThread";
+import { useOpenPanelPullRequestUrl } from "../hooks/useOpenPanelPullRequestUrl";
 import { useThreadActions } from "../hooks/useThreadActions";
 import { resolveAppModelSelectionForInstance } from "../modelSelection";
 import { confirmTerminalClose, isTerminalCloseConfirmPending } from "../lib/terminalCloseConfirm";
@@ -383,6 +387,7 @@ import {
   resolveComposerInteractionMode,
   resolveComposerProviderSelection,
   resolveDraftHeroState,
+  resolveProactiveTurnDiffAction,
   resolveThreadMetadataUpdateForNextTurn,
   resolveSendEnvMode,
   revokeBlobPreviewUrl,
@@ -441,9 +446,8 @@ import {
   supportsServerUpdateThreadContinuation,
 } from "../versionSkew";
 import { useAssetUrls } from "../assets/assetUrls";
+import { ATTACHMENT_ONLY_BOOTSTRAP_PROMPT } from "./chat/composerPromptHistory";
 
-const ATTACHMENT_ONLY_BOOTSTRAP_PROMPT =
-  "[User attached one or more files without additional text. Respond using the conversation context and the attached files.]";
 const EMPTY_ACTIVITIES: OrchestrationThreadActivity[] = [];
 const EMPTY_PROVIDERS: ServerProvider[] = [];
 const EMPTY_PROVIDER_SKILLS: ServerProvider["skills"] = [];
@@ -1155,6 +1159,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
 });
 
 interface PersistentThreadTerminalPanelProps {
+  visible: boolean;
   threadRef: ScopedThreadRef;
   surface: Extract<RightPanelSurface, { kind: "terminal" }>;
   launchContext: PersistentTerminalLaunchContext | null;
@@ -1173,6 +1178,7 @@ interface PersistentThreadTerminalPanelProps {
 }
 
 const PersistentThreadTerminalPanel = memo(function PersistentThreadTerminalPanel({
+  visible,
   threadRef,
   surface,
   launchContext,
@@ -1288,6 +1294,7 @@ const PersistentThreadTerminalPanel = memo(function PersistentThreadTerminalPane
   return (
     <ThreadTerminalDrawer
       mode="panel"
+      visible={visible}
       threadRef={threadRef}
       threadId={threadRef.threadId}
       cwd={cwd}
@@ -1351,7 +1358,7 @@ function releaseChatTimelineAnchor<T extends { readonly messageId: MessageId | n
   return current.messageId === null ? current : { ...current, messageId: null };
 }
 
-function ChatViewContent(props: ChatViewProps) {
+export default function ChatView(props: ChatViewProps) {
   const {
     environmentId,
     threadId,
@@ -1966,6 +1973,18 @@ function ChatViewContent(props: ChatViewProps) {
   const handleNewThreadInActiveProject = useCallback(() => {
     startNewThreadForProject(activeProjectRef, handleNewThread);
   }, [activeProjectRef, handleNewThread]);
+  const projectGroupingSettings = useClientSettings(selectProjectGroupingSettings);
+  const activeDraftLogicalProjectKey =
+    !isServerThread && activeProject
+      ? deriveLogicalProjectKeyFromSettings(activeProject, projectGroupingSettings)
+      : undefined;
+  const handleOpenDraftProjectSettings = useCallback(() => {
+    if (!activeDraftLogicalProjectKey) return;
+    void navigate({
+      to: "/projects/$projectKey",
+      params: { projectKey: activeDraftLogicalProjectKey },
+    });
+  }, [activeDraftLogicalProjectKey, navigate]);
   const activeEnvironmentShell = useEnvironmentQuery(
     activeThread ? environmentShell.stateAtom(activeThread.environmentId) : null,
   );
@@ -1973,7 +1992,6 @@ function ChatViewContent(props: ChatViewProps) {
   const activeProjectKey = activeProject
     ? `${activeProject.environmentId}:${activeProject.workspaceRoot}`
     : null;
-  const projectGroupingSettings = useClientSettings(selectProjectGroupingSettings);
   const clientSettingsHydrated = useClientSettingsHydrated();
   const [pendingFileSurfaceIdsByProject, setPendingFileSurfaceIdsByProject] = useState<
     ReadonlyMap<string, ReadonlySet<string>>
@@ -2390,7 +2408,10 @@ function ChatViewContent(props: ChatViewProps) {
             <Tooltip>
               <TooltipTrigger
                 render={
-                  <button type="button" className="cursor-help rounded-sm text-left">
+                  <button
+                    type="button"
+                    className="block max-w-full cursor-help truncate rounded-sm text-left"
+                  >
                     Server update available
                   </button>
                 }
@@ -2704,6 +2725,8 @@ function ChatViewContent(props: ChatViewProps) {
     });
   }, []);
   const serverMessages = activeThread?.messages;
+  const [projectServerMessagePreviews] = useState(createMessageAttachmentPreviewProjector);
+  const [projectHandoffMessagePreviews] = useState(createMessageAttachmentPreviewProjector);
   const downloadFileAttachment = useCallback(
     async (attachment: ChatFileAttachment) => {
       const connection = readPreparedConnection(environmentId);
@@ -2743,51 +2766,29 @@ function ChatViewContent(props: ChatViewProps) {
     },
     [activeThreadRef, downloadFileAttachment],
   );
-  const serverAttachmentIds = useMemo(() => {
-    const attachmentIds = new Set<string>();
-    for (const message of serverMessages ?? []) {
-      for (const attachment of message.attachments ?? []) {
-        if (isImageAttachment(attachment)) {
-          attachmentIds.add(attachment.id);
-        }
-      }
-    }
-    return [...attachmentIds];
-  }, [serverMessages]);
   const serverAttachmentResources = useMemo(
-    () =>
-      serverAttachmentIds.map((attachmentId) => ({
-        _tag: "attachment" as const,
-        attachmentId,
-      })),
-    [serverAttachmentIds],
+    () => selectHandoffImageResources(serverMessages, attachmentPreviewHandoffByMessageId),
+    [serverMessages, attachmentPreviewHandoffByMessageId],
   );
   const serverAttachmentUrls = useAssetUrls(environmentId, serverAttachmentResources);
   const serverAttachmentUrlById = useMemo(
     () =>
       new Map(
-        serverAttachmentIds.flatMap((attachmentId, index) => {
+        serverAttachmentResources.flatMap((resource, index) => {
           const url = serverAttachmentUrls[index];
-          return url ? [[attachmentId, url] as const] : [];
+          return url ? [[resource.attachmentId, url] as const] : [];
         }),
       ),
-    [serverAttachmentIds, serverAttachmentUrls],
+    [serverAttachmentResources, serverAttachmentUrls],
   );
   const displayServerMessages = useMemo<ReadonlyArray<ChatMessage>>(() => {
     if (!serverMessages) return [];
-    return serverMessages.map((message) => {
-      if (!message.attachments || message.attachments.length === 0) {
-        return message;
-      }
-      return {
-        ...message,
-        attachments: message.attachments.map((attachment) => {
-          const previewUrl = serverAttachmentUrlById.get(attachment.id);
-          return previewUrl ? { ...attachment, previewUrl } : attachment;
-        }),
-      };
-    });
-  }, [serverAttachmentUrlById, serverMessages]);
+    return serverMessages.map((message) =>
+      projectServerMessagePreviews(message, (attachment) =>
+        serverAttachmentUrlById.get(attachment.id),
+      ),
+    );
+  }, [projectServerMessagePreviews, serverAttachmentUrlById, serverMessages]);
   useEffect(() => {
     if (typeof Image === "undefined" || displayServerMessages.length === 0) {
       return;
@@ -2877,10 +2878,7 @@ function ChatViewContent(props: ChatViewProps) {
     const serverMessagesWithPreviewHandoff =
       Object.keys(attachmentPreviewHandoffByMessageId).length === 0
         ? messages
-        : // Spread only fires for the few messages that actually changed;
-          // unchanged ones early-return their original reference.
-          // In-place mutation would break React's immutable state contract.
-          messages.map((message) => {
+        : messages.map((message) => {
             if (
               message.role !== "user" ||
               !message.attachments ||
@@ -2893,25 +2891,15 @@ function ChatViewContent(props: ChatViewProps) {
               return message;
             }
 
-            let changed = false;
             let imageIndex = 0;
-            const attachments = message.attachments.map((attachment) => {
+            return projectHandoffMessagePreviews(message, (attachment) => {
               if (!isImageAttachment(attachment)) {
-                return attachment;
+                return undefined;
               }
               const handoffPreviewUrl = handoffPreviewUrls[imageIndex];
               imageIndex += 1;
-              if (!handoffPreviewUrl || attachment.previewUrl === handoffPreviewUrl) {
-                return attachment;
-              }
-              changed = true;
-              return {
-                ...attachment,
-                previewUrl: handoffPreviewUrl,
-              };
+              return handoffPreviewUrl;
             });
-
-            return changed ? { ...message, attachments } : message;
           });
 
     const localMessages = [
@@ -2936,12 +2924,29 @@ function ChatViewContent(props: ChatViewProps) {
     displayServerMessages,
     feedbackSubmissions,
     optimisticUserMessages,
+    projectHandoffMessagePreviews,
+  ]);
+  const timelineProjectionRef = useRef<{
+    threadKey: string | null;
+    projection: TimelineEntriesProjection;
+  } | null>(null);
+  const timelineEntries = useMemo(() => {
+    const previous = timelineProjectionRef.current;
+    const projection = deriveTimelineEntriesWithState(
+      timelineMessages,
+      activeThread?.proposedPlans ?? [],
+      workLogEntries,
+      previous?.threadKey === activeThreadKey ? previous.projection : null,
+    );
+    timelineProjectionRef.current = { threadKey: activeThreadKey, projection };
+    return projection.entries;
+  }, [
+    timelineProjectionRef,
+    activeThreadKey,
+    activeThread?.proposedPlans,
+    timelineMessages,
+    workLogEntries,
   ]);
-  const timelineEntries = useMemo(
-    () =>
-      deriveTimelineEntries(timelineMessages, activeThread?.proposedPlans ?? [], workLogEntries),
-    [activeThread?.proposedPlans, timelineMessages, workLogEntries],
-  );
   const [dockedDraftHeroThreadKey, setDockedDraftHeroThreadKey] = useState<string | null>(null);
   const draftHeroDockRequested =
     activeThreadKey !== null && dockedDraftHeroThreadKey === activeThreadKey;
@@ -2967,21 +2972,25 @@ function ChatViewContent(props: ChatViewProps) {
     }
     return byMessageId;
   }, [turnDiffSummaries]);
-  const revertTurnCountByUserMessageId = useMemo(
-    () =>
-      buildRevertTurnCountByUserMessageId({
+  const lastRevertTurnCountRef = useRef<Map<MessageId, number> | null>(null);
+  const revertTurnCountByUserMessageId = useMemo(() => {
+    const next = buildRevertTurnCountByUserMessageId(
+      {
         supportsConversationRollback,
         timelineEntries,
         turnDiffSummaryByAssistantMessageId,
         inferredCheckpointTurnCountByTurnId,
-      }),
-    [
-      supportsConversationRollback,
-      inferredCheckpointTurnCountByTurnId,
-      timelineEntries,
-      turnDiffSummaryByAssistantMessageId,
-    ],
-  );
+      },
+      lastRevertTurnCountRef.current,
+    );
+    lastRevertTurnCountRef.current = next;
+    return next;
+  }, [
+    supportsConversationRollback,
+    inferredCheckpointTurnCountByTurnId,
+    timelineEntries,
+    turnDiffSummaryByAssistantMessageId,
+  ]);
 
   const gitCwd = activeProject
     ? projectScriptCwd({
@@ -3710,6 +3719,18 @@ function ChatViewContent(props: ChatViewProps) {
         threadRef: activeThreadRef,
         openPreview,
         ...(profileId === undefined ? {} : { profileId }),
+      }).then((result) => {
+        if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+        const error = squashAtomCommandFailure(result);
+        if (error instanceof BrowserSettingsReadError) {
+          toastManager.add(
+            stackedThreadToast({
+              type: "error",
+              title: "Unable to open browser",
+              description: error.message,
+            }),
+          );
+        }
       });
     },
     [activeThreadRef, openPreview],
@@ -3919,18 +3940,21 @@ function ChatViewContent(props: ChatViewProps) {
       : null;
     const eligibleCompletion =
       settings.proactivePanelsEnabled && !shouldUseRightPanelSheet && newlyCompletedTurnId !== null;
-    const checkpointReady =
-      eligibleCompletion &&
-      activeThread?.checkpoints.some((checkpoint) => checkpoint.turnId === newlyCompletedTurnId) ===
-        true;
-    const shouldOpenTurn = checkpointReady && gitStatusQuery.data?.isRepo === true;
-    const shouldDeferCompletion =
-      eligibleCompletion && !shouldOpenTurn && gitStatusQuery.data?.isRepo !== false;
+    const completedCheckpoint = eligibleCompletion
+      ? activeThread?.checkpoints.find((checkpoint) => checkpoint.turnId === newlyCompletedTurnId)
+      : undefined;
+    const diffAction = eligibleCompletion
+      ? resolveProactiveTurnDiffAction({
+          checkpoint: completedCheckpoint,
+          isGitRepo: gitStatusQuery.data?.isRepo,
+          activeSurfaceKind: activeRightPanelSurface?.kind ?? null,
+        })
+      : "ignore";
     proactiveTurnObservationRef.current = {
       threadKey: activeThreadKey,
-      runningTurnId: shouldDeferCompletion ? (previousRunningTurnId ?? null) : activeRunningTurnId,
+      runningTurnId: diffAction === "defer" ? (previousRunningTurnId ?? null) : activeRunningTurnId,
     };
-    if (!shouldOpenTurn || newlyCompletedTurnId === null) return;
+    if (diffAction !== "open" || newlyCompletedTurnId === null) return;
 
     useDiffPanelStore.getState().selectTurn(activeThreadRef, newlyCompletedTurnId);
     useRightPanelStore.getState().open(activeThreadRef, "diff");
@@ -3942,6 +3966,7 @@ function ChatViewContent(props: ChatViewProps) {
     activeRunningTurnId,
     activeThreadKey,
     activeThreadRef,
+    activeRightPanelSurface?.kind,
     clientSettingsHydrated,
     gitStatusQuery.data?.isRepo,
     isServerThread,
@@ -4749,6 +4774,10 @@ function ChatViewContent(props: ChatViewProps) {
     requestAnimationFrame(() => positionAnchor(12));
   }, []);
 
+  const onToolOutputCollapsedAtEnd = useCallback(() => {
+    composerRef.current?.restoreAfterTimelineReachedEnd();
+  }, []);
+
   const onIsAtEndChange = useCallback((isAtEnd: boolean) => {
     if (
       !isAtEnd &&
@@ -5065,16 +5094,24 @@ function ChatViewContent(props: ChatViewProps) {
       threadRepository,
     ],
   );
+  const openPanelPullRequestUrl = useOpenPanelPullRequestUrl(activeThreadRef);
   const activeThreadReferenceCopyTarget = useMemo(
     () =>
       activeThreadId === null || !isServerThread
         ? null
         : resolveThreadReferenceCopyTarget({
             threadId: activeThreadId,
+            openPanelPullRequestUrl,
             linkedPullRequestUrl: linkedThreadPullRequest?.url ?? null,
             detectedPullRequestUrl: activeThreadPr?.url ?? null,
           }),
-    [activeThreadId, activeThreadPr?.url, isServerThread, linkedThreadPullRequest?.url],
+    [
+      activeThreadId,
+      activeThreadPr?.url,
+      isServerThread,
+      linkedThreadPullRequest?.url,
+      openPanelPullRequestUrl,
+    ],
   );
   const copyActiveThreadReference = useCallback(() => {
     const target = activeThreadReferenceCopyTarget;
@@ -7550,6 +7587,7 @@ function ChatViewContent(props: ChatViewProps) {
       </Suspense>
     ) : renderedRightPanelSurface?.kind === "terminal" ? (
       <PersistentThreadTerminalPanel
+        visible={rightPanelOpen}
         threadRef={activeThreadRef}
         surface={renderedRightPanelSurface}
         launchContext={activeTerminalLaunchContext ?? null}
@@ -7725,6 +7763,9 @@ function ChatViewContent(props: ChatViewProps) {
             rightPanelOpen={rightPanelOpen}
             gitCwd={gitCwd}
             onNewThreadInProject={handleNewThreadInActiveProject}
+            {...(activeDraftLogicalProjectKey
+              ? { onOpenProjectSettings: handleOpenDraftProjectSettings }
+              : {})}
             onRunProjectScript={runProjectScript}
             onAddProjectScript={saveProjectScript}
             onUpdateProjectScript={updateProjectScript}
@@ -7816,6 +7857,7 @@ function ChatViewContent(props: ChatViewProps) {
                 contentInsetEndAdjustment={composerTimelineInset}
                 liveFollowEnabled={timelineLiveFollowEnabled}
                 onIsAtEndChange={onIsAtEndChange}
+                onToolOutputCollapsedAtEnd={onToolOutputCollapsedAtEnd}
                 onManualNavigation={cancelTimelineLiveFollowForUserNavigation}
                 hideEmptyPlaceholder={isDraftHeroState || threadDetailLoading}
                 topFadeEnabled={!hasTimelineTopBanner}
@@ -7905,6 +7947,7 @@ function ChatViewContent(props: ChatViewProps) {
                             activeThreadId={activeThreadId}
                             activeThreadEnvironmentId={activeThread?.environmentId}
                             activeThread={activeThread}
+                            promptHistoryMessages={timelineMessages}
                             isServerThread={isServerThread}
                             isLocalDraftThread={isLocalDraftThread}
                             forceExpandedOnMobile={forceExpandedMobileComposer && isDraftHeroState}
@@ -8226,11 +8269,3 @@ function ChatViewContent(props: ChatViewProps) {
     </div>
   );
 }
-
-export default function ChatView(props: ChatViewProps) {
-  return (
-    <DiffWorkerPoolProvider>
-      <ChatViewContent {...props} />
-    </DiffWorkerPoolProvider>
-  );
-}
diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index 91822d40e484..feefc0750183 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -30,6 +30,7 @@ import {
 import {
   type DesktopWslState,
   type EnvironmentId,
+  type EnvironmentMachineKind,
   type FilesystemBrowseResult,
   type ProjectId,
   type SourceControlDiscoveryResult,
@@ -70,6 +71,7 @@ import { useAtomValue } from "@effect/atom-react";
 import { isDesktopLocalConnectionTarget } from "../connection/desktopLocal";
 import { useDesktopLocalBootstraps } from "../connection/useDesktopLocalBootstraps";
 import { useHandleNewThread } from "../hooks/useHandleNewThread";
+import { useOpenPanelPullRequestUrl } from "../hooks/useOpenPanelPullRequestUrl";
 import { writeTextToClipboard } from "../hooks/useCopyToClipboard";
 import { useClientSettings } from "../hooks/useSettings";
 import { useTheme } from "../hooks/useTheme";
@@ -208,6 +210,7 @@ function getEnvironmentBrowsePlatform(os: string | null | undefined): string {
 interface AddProjectEnvironmentOption {
   readonly environmentId: EnvironmentId;
   readonly label: string;
+  readonly machine: EnvironmentMachineKind;
   readonly isPrimary: boolean;
   readonly isConnected: boolean;
   readonly status: string;
@@ -508,7 +511,10 @@ export function CommandPalette({ children }: { children: ReactNode }) {
           setOpen(open);
         }}
       >
-        {children}
+        {/* Block background focus calls for the entire time the palette is open. */}
+        <div className="contents" inert={state.open}>
+          {children}
+        </div>
         <CommandPaletteDialog
           mode={state.mode}
           openIntent={state.openIntent}
@@ -634,11 +640,15 @@ function OpenCommandPaletteDialog(props: {
           ),
           retainTerminalOnBranchMismatch: activeThread.worktreePath === null,
         })?.url ?? null);
+  const openPanelPullRequestUrl = useOpenPanelPullRequestUrl(
+    activeThread ? scopeThreadRef(activeThread.environmentId, activeThread.id) : null,
+  );
   const activeThreadReferenceCopyTarget =
     activeThread == null
       ? null
       : resolveThreadReferenceCopyTarget({
           threadId: activeThread.id,
+          openPanelPullRequestUrl,
           linkedPullRequestUrl: activeThread.linkedPullRequest?.url ?? null,
           detectedPullRequestUrl,
         });
@@ -840,6 +850,7 @@ function OpenCommandPaletteDialog(props: {
           runtimeLabel: environment.label,
         }),
         isPrimary,
+        machine: resolveEnvironmentMachineKind(environment.serverConfig),
         isConnected: canCreateProjectInEnvironment(environment.connection.phase),
         status: connectionStatusText(environment.connection),
       };
@@ -1485,7 +1496,7 @@ function OpenCommandPaletteDialog(props: {
           : option.environmentId
         : option.status,
       disabled: !option.isConnected,
-      icon: <FolderPlusIcon className={ITEM_ICON_CLASS} />,
+      icon: <EnvironmentMachineIcon kind={option.machine} className={ITEM_ICON_CLASS} />,
       keepOpen: true,
       run: async () => {
         startAddProjectSourceSelection(option.environmentId);
@@ -2314,19 +2325,20 @@ function OpenCommandPaletteDialog(props: {
       context: { modelPickerOpen: false },
     });
     if (threadJumpIndexFromCommand(command ?? "") !== null) {
+      event.preventDefault();
+      event.stopPropagation();
       const matchingItem = displayedGroups
         .flatMap((group) => group.items)
         .find((item) => item.shortcutCommand === command);
       if (matchingItem) {
-        event.preventDefault();
-        event.stopPropagation();
         executeItem(matchingItem);
-        return;
       }
+      return;
     }
-    if (command === "thread.copyReference" && activeThreadReferenceCopyTarget !== null) {
+    if (command === "thread.copyReference") {
       event.preventDefault();
       event.stopPropagation();
+      if (activeThreadReferenceCopyTarget === null) return;
       setOpen(false);
       void copyActiveThreadReference();
       return;
diff --git a/apps/web/src/components/CommandPaletteContent.tsx b/apps/web/src/components/CommandPaletteContent.tsx
index af3c1b671704..8c1a5b0e3c83 100644
--- a/apps/web/src/components/CommandPaletteContent.tsx
+++ b/apps/web/src/components/CommandPaletteContent.tsx
@@ -1,5 +1,5 @@
 import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
-import type { ComponentProps, ReactNode } from "react";
+import { type ComponentProps, type ReactNode, useLayoutEffect, useRef } from "react";
 
 import { Command, CommandFooter, CommandInput, CommandPanel } from "./ui/command";
 import { Kbd, KbdGroup } from "./ui/kbd";
@@ -33,11 +33,20 @@ export function CommandPaletteContent({
   testId,
   ...commandProps
 }: CommandPaletteContentProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Direct-open flows replace the initial palette view after the dialog has
+  // already moved focus. Reclaim it when the replacement input mounts so
+  // typing cannot continue in the composer behind the modal.
+  useLayoutEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
   return (
     <div className="contents" data-testid={testId}>
       <Command {...commandProps}>
         <div className="relative">
-          <CommandInput {...inputProps} />
+          <CommandInput {...inputProps} ref={inputRef} />
           {inputAccessory}
         </div>
         <CommandPanel className={panelClassName}>{children}</CommandPanel>
diff --git a/apps/web/src/components/ComposerPromptEditor.tsx b/apps/web/src/components/ComposerPromptEditor.tsx
index 695c5e3d0858..2ecb4c873e88 100644
--- a/apps/web/src/components/ComposerPromptEditor.tsx
+++ b/apps/web/src/components/ComposerPromptEditor.tsx
@@ -896,6 +896,13 @@ export interface ComposerPromptEditorHandle {
     expandedCursor: number;
     terminalContextIds: string[];
   };
+  /**
+   * True when a collapsed caret sits on the first ("start") or last ("end")
+   * visual line, counting soft wraps. Prompt history only claims ArrowUp and
+   * ArrowDown at these edges so arrows still move the caret inside multiline
+   * text.
+   */
+  isCaretOnVisualEdge: (edge: "start" | "end") => boolean;
 }
 
 interface ComposerPromptEditorProps {
@@ -929,6 +936,66 @@ interface ComposerPromptEditorProps {
   editorRef: React.RefObject<ComposerPromptEditorHandle | null>;
 }
 
+/**
+ * Client rect of the line the collapsed caret is on, as seen from `edge`.
+ * A caret at a soft-wrap boundary belongs to two visual lines and the
+ * range reports a rect for each, so take the one farthest from the edge
+ * under test: an ambiguous caret then never claims the key and the arrow
+ * moves the caret as usual. A collapsed range reports zero-height rects at
+ * some positions, so probe the adjacent character on the same side. When
+ * the range container is the paragraph itself (an empty line, or a caret
+ * beside an inline chip) measure the child next to the caret before
+ * falling back to the paragraph.
+ */
+function caretLineRect(range: Range, edge: "start" | "end"): DOMRect | null {
+  const collapsedRects = Array.from(range.getClientRects()).filter((rect) => rect.height > 0);
+  const collapsedRect = edge === "start" ? collapsedRects.at(-1) : collapsedRects[0];
+  if (collapsedRect) return collapsedRect;
+
+  const container = range.startContainer;
+  if (container.nodeType === Node.TEXT_NODE) {
+    const textNode = container as Text;
+    if (textNode.data.length === 0) return null;
+    const probeStart = Math.max(
+      0,
+      Math.min(
+        edge === "start" ? range.startOffset : range.startOffset - 1,
+        textNode.data.length - 1,
+      ),
+    );
+    const probeRange = document.createRange();
+    probeRange.setStart(textNode, probeStart);
+    probeRange.setEnd(textNode, probeStart + 1);
+    const probeRect = Array.from(probeRange.getClientRects()).find((rect) => rect.height > 0);
+    if (probeRect) return probeRect;
+    const boundingRect = probeRange.getBoundingClientRect();
+    return boundingRect.height > 0 ? boundingRect : null;
+  }
+
+  if (!(container instanceof HTMLElement)) return null;
+  // The caret sits between the paragraph's children, which is where Lexical
+  // puts it next to an inline chip. Measure the neighbouring child.
+  const neighbour =
+    container.childNodes[Math.max(0, range.startOffset - 1)] ??
+    container.childNodes[range.startOffset];
+  if (neighbour instanceof HTMLElement) {
+    const neighbourRect = neighbour.getBoundingClientRect();
+    if (neighbourRect.height > 0) return neighbourRect;
+  } else if (neighbour instanceof Text && neighbour.data.length > 0) {
+    // Probe the character on the caret's side. A soft-wrapped text node's
+    // first rect is its first visual line, which may not be the caret's.
+    const isBeforeCaret = neighbour === container.childNodes[range.startOffset - 1];
+    const probeStart = isBeforeCaret ? neighbour.data.length - 1 : 0;
+    const probeRange = document.createRange();
+    probeRange.setStart(neighbour, probeStart);
+    probeRange.setEnd(neighbour, probeStart + 1);
+    const probeRect = Array.from(probeRange.getClientRects()).find((rect) => rect.height > 0);
+    if (probeRect) return probeRect;
+  }
+  const containerRect = container.getBoundingClientRect();
+  return containerRect.height > 0 ? containerRect : null;
+}
+
 function ComposerCommandKeyPlugin(props: {
   onCommandKeyDown?: (
     key: "ArrowDown" | "ArrowUp" | "Enter" | "Tab",
@@ -1799,6 +1866,36 @@ function ComposerPromptEditorInner({
         if (target) setOpenCitationComment(target);
       },
       readSnapshot,
+      isCaretOnVisualEdge: (edge) => {
+        const snapshot = readSnapshot();
+        if (snapshot.value.length === 0) return true;
+        const beforeCaret = snapshot.value.slice(0, snapshot.expandedCursor);
+        const afterCaret = snapshot.value.slice(snapshot.expandedCursor);
+        if (edge === "start" ? beforeCaret.includes("\n") : afterCaret.includes("\n")) {
+          return false;
+        }
+        const rootElement = editor.getRootElement();
+        const selection = window.getSelection();
+        if (
+          !rootElement ||
+          !selection ||
+          !selection.isCollapsed ||
+          selection.rangeCount === 0 ||
+          !selection.anchorNode ||
+          !rootElement.contains(selection.anchorNode)
+        ) {
+          return false;
+        }
+        const caretRect = caretLineRect(selection.getRangeAt(0), edge);
+        if (!caretRect) return false;
+        const edgeElement =
+          edge === "start" ? rootElement.firstElementChild : rootElement.lastElementChild;
+        const edgeRect = (edgeElement ?? rootElement).getBoundingClientRect();
+        const threshold = caretRect.height / 2;
+        return edge === "start"
+          ? caretRect.top - edgeRect.top < threshold
+          : edgeRect.bottom - caretRect.bottom < threshold;
+      },
     }),
     [editor, focusAt, readSnapshot],
   );
@@ -1929,7 +2026,7 @@ function ComposerPromptEditorInner({
               terminalContexts.length > 0 ? null : (
                 <div
                   className={cn(
-                    "pointer-events-none absolute inset-0 leading-relaxed text-placeholder",
+                    "pointer-events-none absolute inset-0 leading-relaxed text-placeholder/75",
                     placeholderClassName,
                   )}
                 >
diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index c773617a7cf2..87f5f1ba56f8 100644
--- a/apps/web/src/components/DiffPanel.tsx
+++ b/apps/web/src/components/DiffPanel.tsx
@@ -24,6 +24,7 @@ import {
 } from "lucide-react";
 import * as Schema from "effect/Schema";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCodeViewFileReveal } from "./diffs/useCodeViewFileReveal";
 import { useOpenInPreferredEditor } from "../editorPreferences";
 import { type DraftId } from "../composerDraftStore";
 import { openDiffFilePrimaryAction } from "../diffFileActions";
@@ -129,7 +130,7 @@ export default function DiffPanel({
     fileKeys: EMPTY_COLLAPSED_DIFF_FILE_KEYS,
   }));
   const [codeViewRevision, setCodeViewRevision] = useState(0);
-  const codeViewRef = useRef<AnnotatableCodeViewHandle>(null);
+  const [codeView, setCodeView] = useState<AnnotatableCodeViewHandle | null>(null);
 
   const routeThreadRef = useParams({
     strict: false,
@@ -448,17 +449,15 @@ export default function DiffPanel({
     : null;
 
   useEffect(() => {
-    if (!selectedDiffFileKey) return;
-    codeViewRef.current?.scrollTo({ type: "item", id: selectedDiffFileKey, align: "start" });
-  }, [codeViewMountKey, selectedDiffFileKey, selectedFileRevealRequestId]);
+    if (!selectedDiffFileKey || !codeView?.getInstance()) return;
+    codeView.scrollTo({ type: "item", id: selectedDiffFileKey, align: "start" });
+  }, [codeView, codeViewMountKey, selectedDiffFileKey, selectedFileRevealRequestId]);
 
-  // Held as state so the scroll runs after a collapsed file has been drawn open again; scrolling
-  // in the same tick would land on the folded header's position.
-  const [treeReveal, setTreeReveal] = useState<{ fileKey: string; id: number } | null>(null);
-  useEffect(() => {
-    if (treeReveal === null) return;
-    codeViewRef.current?.scrollTo({ type: "item", id: treeReveal.fileKey, align: "start" });
-  }, [treeReveal]);
+  const treeRevealScope = useMemo(
+    () => ({ collapseScopeKey, diffSelection }),
+    [collapseScopeKey, diffSelection],
+  );
+  const requestTreeReveal = useCodeViewFileReveal(codeView, treeRevealScope);
   const revealDiffFile = useCallback(
     (filePath: string) => {
       const file = codeViewFiles.find((candidate) => candidate.filePath === filePath);
@@ -470,9 +469,9 @@ export default function DiffPanel({
           return { scopeKey: collapseScopeKey, fileKeys: next };
         });
       }
-      setTreeReveal((current) => ({ fileKey: file.fileKey, id: (current?.id ?? 0) + 1 }));
+      requestTreeReveal(file.fileKey);
     },
-    [codeViewFiles, collapseScopeKey],
+    [codeViewFiles, collapseScopeKey, requestTreeReveal],
   );
 
   const openDiffFile = useCallback(
@@ -801,8 +800,9 @@ export default function DiffPanel({
           </Tooltip>
         )}
         <ToggleGroup
-          className="shrink-0 gap-1"
-          size="sm"
+          aria-label="Diff layout"
+          className="shrink-0"
+          variant="segmented"
           value={[diffLayout]}
           onValueChange={(value) => {
             const next = value[0];
@@ -811,10 +811,10 @@ export default function DiffPanel({
             }
           }}
         >
-          <Toggle aria-label="Stacked diff view" value="stacked" variant="ghost">
+          <Toggle aria-label="Stacked diff view" value="stacked">
             <Rows3Icon className="size-3.5" />
           </Toggle>
-          <Toggle aria-label="Split diff view" value="split" variant="ghost">
+          <Toggle aria-label="Split diff view" value="split">
             <Columns2Icon className="size-3.5" />
           </Toggle>
         </ToggleGroup>
@@ -972,7 +972,7 @@ export default function DiffPanel({
                 >
                   <AnnotatableCodeView
                     key={collapseScopeKey ?? reviewSectionId}
-                    viewerRef={codeViewRef}
+                    viewerRef={setCodeView}
                     codeViewKey={codeViewMountKey}
                     className="h-full min-h-0 overflow-auto"
                     files={codeViewFiles}
diff --git a/apps/web/src/components/DiffWorkerPoolProvider.tsx b/apps/web/src/components/DiffWorkerPoolProvider.tsx
index bcf90b118410..1cd2393e82f6 100644
--- a/apps/web/src/components/DiffWorkerPoolProvider.tsx
+++ b/apps/web/src/components/DiffWorkerPoolProvider.tsx
@@ -1,7 +1,15 @@
-import { WorkerPoolContextProvider, useWorkerPool } from "@pierre/diffs/react";
+import { WorkerPoolContext, useWorkerPool } from "@pierre/diffs/react";
+import { WorkerPoolManager } from "@pierre/diffs/worker";
 import DiffsWorker from "@pierre/diffs/worker/worker.js?worker";
 import * as Schema from "effect/Schema";
-import { useEffect, useMemo, type ReactNode } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
 import { useTheme } from "../hooks/useTheme";
 import { resolveDiffThemeName, type DiffThemeName } from "../lib/diffRendering";
 import { PREFERRED_HIGHLIGHTER } from "../lib/syntaxHighlighting";
@@ -16,6 +24,46 @@ export class DiffWorkerError extends Schema.TaggedErrorClass<DiffWorkerError>()(
   }
 }
 
+const DIFF_WORKER_IDLE_TTL_MS = 30_000;
+let sharedWorkerPool:
+  | {
+      readonly pool: WorkerPoolManager;
+      consumers: number;
+      idleTimer: ReturnType<typeof setTimeout> | undefined;
+    }
+  | undefined;
+
+/** Create workers after a viewer commits, then reuse them across short panel closures. */
+function acquireDiffWorkerPool(themeName: DiffThemeName, poolSize: number) {
+  const entry = (sharedWorkerPool ??= {
+    pool: new WorkerPoolManager(
+      {
+        workerFactory: () => {
+          try {
+            return new DiffsWorker();
+          } catch (cause) {
+            throw new DiffWorkerError({ operation: "create-worker", themeName, cause });
+          }
+        },
+        poolSize,
+        totalASTLRUCacheSize: 240,
+      },
+      {
+        theme: themeName,
+        preferredHighlighter: PREFERRED_HIGHLIGHTER,
+        tokenizeMaxLineLength: 1_000,
+        useTokenTransformer: true,
+      },
+    ),
+    consumers: 0,
+    idleTimer: undefined,
+  });
+  clearTimeout(entry.idleTimer);
+  entry.idleTimer = undefined;
+  entry.consumers += 1;
+  return entry;
+}
+
 function DiffWorkerThemeSync({ themeName }: { themeName: DiffThemeName }) {
   const workerPool = useWorkerPool();
 
@@ -46,6 +94,40 @@ function DiffWorkerThemeSync({ themeName }: { themeName: DiffThemeName }) {
   return null;
 }
 
+// Plain-text views do not queue a highlight task that could retry a blank first render.
+function DiffWorkerReady({ children }: { children?: ReactNode }) {
+  const workerPool = useWorkerPool();
+  const [readyPool, setReadyPool] = useState<WorkerPoolManager>();
+  const ready = workerPool
+    ? readyPool === workerPool || workerPool.isInitialized() || !workerPool.isWorkingPool()
+    : typeof window === "undefined";
+
+  useEffect(() => {
+    if (ready || !workerPool) return;
+
+    let mounted = true;
+    const finish = () => {
+      if (mounted) setReadyPool(workerPool);
+    };
+    // Failed pools use Pierre's existing main-thread highlighter.
+    void workerPool.initialize().then(finish, finish);
+    return () => {
+      mounted = false;
+    };
+  }, [ready, workerPool]);
+
+  return ready ? (
+    children
+  ) : (
+    <div
+      role="status"
+      className="flex min-h-0 flex-1 items-center justify-center p-4 text-xs text-muted-foreground"
+    >
+      Loading code...
+    </div>
+  );
+}
+
 export function DiffWorkerPoolProvider({ children }: { children?: ReactNode }) {
   const { resolvedTheme } = useTheme();
   const diffThemeName = resolveDiffThemeName(resolvedTheme);
@@ -54,33 +136,32 @@ export function DiffWorkerPoolProvider({ children }: { children?: ReactNode }) {
       typeof navigator === "undefined" ? 4 : Math.max(1, navigator.hardwareConcurrency || 4);
     return Math.max(2, Math.min(6, Math.floor(cores / 2)));
   }, []);
+  const workerPool = useSyncExternalStore(
+    useCallback(
+      (onStoreChange) => {
+        if (typeof window === "undefined") return () => {};
+        const entry = acquireDiffWorkerPool(diffThemeName, workerPoolSize);
+        onStoreChange();
+        return () => {
+          entry.consumers -= 1;
+          if (entry.consumers !== 0) return;
+          entry.idleTimer = setTimeout(() => {
+            entry.idleTimer = undefined;
+            entry.pool.terminate();
+            if (sharedWorkerPool === entry) sharedWorkerPool = undefined;
+          }, DIFF_WORKER_IDLE_TTL_MS);
+        };
+      },
+      [diffThemeName, workerPoolSize],
+    ),
+    () => sharedWorkerPool?.pool,
+    () => undefined,
+  );
 
   return (
-    <WorkerPoolContextProvider
-      poolOptions={{
-        workerFactory: () => {
-          try {
-            return new DiffsWorker();
-          } catch (cause) {
-            throw new DiffWorkerError({
-              operation: "create-worker",
-              themeName: diffThemeName,
-              cause,
-            });
-          }
-        },
-        poolSize: workerPoolSize,
-        totalASTLRUCacheSize: 240,
-      }}
-      highlighterOptions={{
-        theme: diffThemeName,
-        preferredHighlighter: PREFERRED_HIGHLIGHTER,
-        tokenizeMaxLineLength: 1_000,
-        useTokenTransformer: true,
-      }}
-    >
+    <WorkerPoolContext value={workerPool}>
       <DiffWorkerThemeSync themeName={diffThemeName} />
-      {children}
-    </WorkerPoolContextProvider>
+      <DiffWorkerReady>{children}</DiffWorkerReady>
+    </WorkerPoolContext>
   );
 }
diff --git a/apps/web/src/components/GitActionsControl.tsx b/apps/web/src/components/GitActionsControl.tsx
index 341444324e73..b7fc811d5127 100644
--- a/apps/web/src/components/GitActionsControl.tsx
+++ b/apps/web/src/components/GitActionsControl.tsx
@@ -42,6 +42,7 @@ 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 { toggleVariants } from "~/components/ui/toggle";
 import { cn } from "~/lib/utils";
 import {
   buildGitActionProgressStages,
@@ -831,32 +832,29 @@ function PublishRepositoryDialog(props: PublishRepositoryDialogProps) {
                           Protocol
                         </span>
                         <RadioGroup
+                          className="w-fit flex-row gap-0.5 rounded-lg bg-input/40 p-0.5"
                           value={publishProtocol}
-                          onValueChange={(value) =>
-                            setPublishProtocol(value as SourceControlCloneProtocol)
-                          }
+                          onValueChange={(protocol) => {
+                            if (protocol === "ssh" || protocol === "https") {
+                              setPublishProtocol(protocol);
+                            }
+                          }}
                           aria-labelledby="publish-protocol-label"
                           disabled={publishRepositoryAction.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 dark:border-transparent dark:bg-primary/10 dark:ring-1 dark:ring-primary/30"
-                                    : "border-border bg-background text-muted-foreground hover:border-foreground/20 hover:text-foreground dark:border-transparent dark:bg-white/[0.035]",
-                                )}
-                              >
-                                {value === "ssh" ? "SSH" : "HTTPS"}
-                              </RadioPrimitive.Root>
-                            );
-                          })}
+                          {(["ssh", "https"] as const).map((protocol) => (
+                            <RadioPrimitive.Root
+                              key={protocol}
+                              value={protocol}
+                              data-pressed={publishProtocol === protocol ? "" : undefined}
+                              className={toggleVariants({
+                                variant: "segmented",
+                                size: "segmented",
+                              })}
+                            >
+                              {protocol.toUpperCase()}
+                            </RadioPrimitive.Root>
+                          ))}
                         </RadioGroup>
                       </div>
                     </div>
diff --git a/apps/web/src/components/LegacySidebar.tsx b/apps/web/src/components/LegacySidebar.tsx
index ea910905efe0..a3a07839f837 100644
--- a/apps/web/src/components/LegacySidebar.tsx
+++ b/apps/web/src/components/LegacySidebar.tsx
@@ -171,8 +171,11 @@ import {
   SidebarMenuSubItem,
   useSidebar,
 } from "./ui/sidebar";
-import { useThreadSelectionStore } from "../threadSelectionStore";
-import { openCommandPalette } from "../commandPaletteBus";
+import {
+  getThreadKeysToDeselectAfterDelete,
+  useThreadSelectionStore,
+} from "../threadSelectionStore";
+import { isCommandPaletteOpen, openCommandPalette } from "../commandPaletteBus";
 import {
   archiveSelectedThreadEntries,
   buildMultiSelectThreadContextMenuItems,
@@ -1910,26 +1913,35 @@ const SidebarProjectItem = memo(function SidebarProjectItem(props: SidebarProjec
         if (!confirmed) return;
       }
 
-      const deletedThreadKeys = new Set(threadKeys);
-      for (const { threadRef } of selectedThreadEntries) {
+      // Only discount batch members after their deletions succeed.
+      const deletedThreadKeys = new Set<string>();
+      let firstError: unknown = null;
+      for (const { threadKey, threadRef } of selectedThreadEntries) {
         const result = await deleteThread(threadRef, {
           deletedThreadKeys,
         });
         if (result._tag === "Failure") {
-          if (!isAtomCommandInterrupted(result)) {
-            const error = squashAtomCommandFailure(result);
-            toastManager.add(
-              stackedThreadToast({
-                type: "error",
-                title: "Failed to delete threads",
-                description: error instanceof Error ? error.message : "An error occurred.",
-              }),
-            );
-          }
-          return;
+          if (isAtomCommandInterrupted(result)) break;
+          firstError ??= squashAtomCommandFailure(result);
+          continue;
         }
+        deletedThreadKeys.add(threadKey);
       }
-      removeFromSelection(threadKeys);
+      if (firstError !== null) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to delete threads",
+            description: firstError instanceof Error ? firstError.message : "An error occurred.",
+          }),
+        );
+      }
+      removeFromSelection(
+        getThreadKeysToDeselectAfterDelete(threadKeys, deletedThreadKeys, (threadKey) => {
+          const threadRef = parseScopedThreadKey(threadKey);
+          return threadRef !== null && readThreadShell(threadRef) !== null;
+        }),
+      );
     },
     [
       appSettingsConfirmThreadArchive,
@@ -3510,7 +3522,7 @@ export default function LegacySidebar() {
     const onWindowKeyDown = (event: globalThis.KeyboardEvent) => {
       const shortcutContext = getCurrentSidebarShortcutContext();
 
-      if (event.defaultPrevented || event.repeat) {
+      if (event.defaultPrevented || event.repeat || isCommandPaletteOpen() || isModelPickerOpen()) {
         return;
       }
 
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
index 2ee06a6b6620..12f63f3e16fd 100644
--- a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.test.ts
@@ -18,17 +18,14 @@ import {
   environmentGroupsWithUpdates,
   firstFailedProviderUpdateMessage,
   firstRejectedProviderUpdateMessage,
-  firstUnsuccessfulSecondaryProviderOutcome,
   getProviderUpdateInitialToastView,
   getProviderUpdateProgressToastView,
   getProviderUpdateRejectedToastView,
   getProviderUpdateSidebarPillView,
-  getSingleProviderUpdateProgressToastView,
   hasOneClickUpdateProviderCandidate,
   isProviderUpdateCandidate,
   isTerminalProviderUpdatePhase,
   localEnvironmentUpdateNotificationKey,
-  parseWslDistroFromInstanceId,
   providerUpdateNotificationKey,
   resolveEnvironmentUpdateRowStatus,
   shouldShowPrimaryProviderUpdateToast,
@@ -368,28 +365,6 @@ describe("provider update launch notification logic", () => {
     });
   });
 
-  it("resolves a single-provider completion view from the returned provider snapshot", () => {
-    const view = getSingleProviderUpdateProgressToastView(
-      provider({
-        driver: driver("codex"),
-        updateState: {
-          status: "failed",
-          startedAt: checkedAt,
-          finishedAt: checkedAt,
-          message: "command failed",
-          output: "stderr",
-        },
-      }),
-    );
-
-    expect(view).toMatchObject({
-      phase: "failed",
-      type: "error",
-      title: "Codex v1.1.0 update failed",
-      description: "command failed",
-    });
-  });
-
   it("keeps unchanged providers actionable from settings", () => {
     const view = getProviderUpdateProgressToastView({
       providers: [
@@ -444,31 +419,6 @@ describe("provider update launch notification logic", () => {
     });
   });
 
-  it("uses the updated version in the single-provider success toast title", () => {
-    const view = getSingleProviderUpdateProgressToastView(
-      provider({
-        driver: driver("codex"),
-        version: "1.1.0",
-        latestVersion: "1.1.0",
-        advisoryStatus: "current",
-        updateState: {
-          status: "succeeded",
-          startedAt: checkedAt,
-          finishedAt: checkedAt,
-          message: "Provider updated.",
-          output: null,
-        },
-      }),
-    );
-
-    expect(view).toMatchObject({
-      phase: "succeeded",
-      type: "success",
-      title: "Codex updated: v1.1.0",
-      description: "New sessions will use the updated provider.",
-    });
-  });
-
   it("falls back to a rejected RPC message for transport-level failures", () => {
     const results = [AsyncResult.failure(Cause.die(new Error("WebSocket closed")))];
 
@@ -814,39 +764,6 @@ describe("provider update launch notification logic", () => {
       expect(snapshots).toEqual([primary]);
     });
 
-    it("flags the first unsuccessful secondary outcome, skipping the primary and successes", () => {
-      const primaryFailed = provider({
-        driver: driver("codex"),
-        updateState: terminalState("failed", "primary boom"),
-      });
-
-      expect(
-        firstUnsuccessfulSecondaryProviderOutcome([
-          fulfilledOutcome(true, primaryFailed),
-          fulfilledOutcome(
-            false,
-            provider({
-              driver: driver("codex"),
-              updateState: terminalState("succeeded", "ok"),
-            }),
-          ),
-        ]),
-      ).toBeNull();
-
-      expect(
-        firstUnsuccessfulSecondaryProviderOutcome([
-          fulfilledOutcome(true, primaryFailed),
-          fulfilledOutcome(
-            false,
-            provider({
-              driver: driver("codex"),
-              updateState: terminalState("failed", "wsl boom"),
-            }),
-          ),
-        ]),
-      ).toMatchObject({ status: "failed", provider: { updateState: { message: "wsl boom" } } });
-    });
-
     it("treats a rejected dispatch as not contributing a snapshot", () => {
       const primary = provider({
         driver: driver("codex"),
@@ -995,14 +912,6 @@ describe("provider update launch notification logic", () => {
         }),
       ).toBe("My Device");
     });
-
-    it("parses the WSL distro from the backend instance id", () => {
-      expect(parseWslDistroFromInstanceId("wsl:ubuntu")).toBe("ubuntu");
-      expect(parseWslDistroFromInstanceId("wsl:default")).toBeNull();
-      expect(parseWslDistroFromInstanceId("wsl:")).toBeNull();
-      expect(parseWslDistroFromInstanceId("ssh:host")).toBeNull();
-      expect(parseWslDistroFromInstanceId(undefined)).toBeNull();
-    });
   });
 
   describe("isTerminalProviderUpdatePhase", () => {
diff --git a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
index e9ed26f1ee80..16184ac070bc 100644
--- a/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
+++ b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
@@ -19,6 +19,13 @@ export type ProviderUpdateCandidate = ServerProvider & {
   };
 };
 
+export type ProviderSettingsUpdateCandidate = ServerProvider & {
+  readonly versionAdvisory: NonNullable<ServerProvider["versionAdvisory"]> & {
+    readonly canUpdate: true;
+    readonly updateCommand: string;
+  };
+};
+
 export type ProviderUpdateToastType = "warning" | "loading" | "error" | "success";
 export type ProviderUpdateToastPhase = "initial" | "running" | "failed" | "unchanged" | "succeeded";
 
@@ -149,6 +156,17 @@ export function collectProviderUpdateCandidates(
   return dedupeProvidersByDriver(providers.filter(isProviderUpdateCandidate));
 }
 
+export function isProviderSettingsUpdateCandidate(
+  provider: ServerProvider,
+): provider is ProviderSettingsUpdateCandidate {
+  return (
+    provider.enabled &&
+    provider.versionAdvisory?.status === "behind_latest" &&
+    provider.versionAdvisory.canUpdate === true &&
+    provider.versionAdvisory.updateCommand !== null
+  );
+}
+
 export function hasOneClickUpdateProviderCandidate(
   candidate: ProviderUpdateCandidate,
   providers: ReadonlyArray<ServerProvider>,
@@ -308,41 +326,6 @@ export function getProviderUpdateProgressToastView(input: {
   return getProviderUpdateRunningToastView(input.providerCount);
 }
 
-export function getSingleProviderUpdateProgressToastView(
-  provider: ServerProvider,
-): ProviderUpdateToastView {
-  const view = getProviderUpdateProgressToastView({
-    providers: [provider],
-    providerCount: 1,
-  });
-  const providerName = PROVIDER_DISPLAY_NAMES[provider.driver] ?? provider.driver;
-
-  switch (view.phase) {
-    case "running":
-      return {
-        ...view,
-        title: `Updating ${providerName}`,
-      };
-    case "failed":
-      return {
-        ...view,
-        title: getProviderFailedUpdateTitle(provider),
-      };
-    case "unchanged":
-      return {
-        ...view,
-        title: `${providerName} still needs an update`,
-      };
-    case "succeeded":
-      return {
-        ...view,
-        title: getProviderUpdatedTitle(provider),
-      };
-    default:
-      return view;
-  }
-}
-
 export function collectUpdatedProviderSnapshots(input: {
   readonly results: ReadonlyArray<
     AtomCommandResult<{ readonly providers: ReadonlyArray<ServerProvider> }, unknown>
@@ -631,42 +614,6 @@ export function collectProviderUpdateOutcomeSnapshots(
   return [...worstByDriver.values()];
 }
 
-/**
- * The first secondary (non-primary) backend whose update resolved without
- * succeeding. The primary's own failed/unchanged state is already surfaced
- * inline in settings, so only secondaries (which have no inline row) need an
- * explicit callout.
- */
-export function firstUnsuccessfulSecondaryProviderOutcome(
-  results: ReadonlyArray<PromiseSettledResult<LocalProviderUpdateOutcome>>,
-): { readonly provider: ServerProvider; readonly status: "failed" | "unchanged" } | null {
-  for (const result of results) {
-    if (result.status !== "fulfilled") {
-      continue;
-    }
-    const outcome = result.value;
-    if (outcome.isPrimary || outcome.provider === null) {
-      continue;
-    }
-    const status = outcome.provider.updateState?.status;
-    if (status === "failed" || status === "unchanged") {
-      return { provider: outcome.provider, status };
-    }
-  }
-  return null;
-}
-
-const WSL_INSTANCE_ID_PREFIX = "wsl:";
-
-/** The distro name from a WSL backend instance id ("wsl:ubuntu" -> "ubuntu"), or null for the default. */
-export function parseWslDistroFromInstanceId(instanceId: string | undefined): string | null {
-  if (!instanceId || !instanceId.startsWith(WSL_INSTANCE_ID_PREFIX)) {
-    return null;
-  }
-  const distro = instanceId.slice(WSL_INSTANCE_ID_PREFIX.length).trim();
-  return distro.length === 0 || distro === "default" ? null : distro;
-}
-
 /**
  * A human label that distinguishes local environments by platform (so the
  * popover shows "Windows" / "WSL" rather than the account name twice). WSL is
diff --git a/apps/web/src/components/QuitHoldOverlay.tsx b/apps/web/src/components/QuitHoldOverlay.tsx
index 091fa60c2f71..2bca40f5b130 100644
--- a/apps/web/src/components/QuitHoldOverlay.tsx
+++ b/apps/web/src/components/QuitHoldOverlay.tsx
@@ -40,7 +40,9 @@ export function QuitHoldOverlay() {
   if (!visibleMode) return null;
   const shortcut = isMacPlatform(navigator.platform) ? "⌘Q" : "Ctrl+Q";
   const message =
-    visibleMode === "hold" ? `Hold ${shortcut} to Quit` : `Press ${shortcut} again to Quit`;
+    visibleMode === "hold"
+      ? `Hold ${shortcut} or press twice to quit`
+      : `Press ${shortcut} again to quit`;
   return (
     <div
       role="status"
diff --git a/apps/web/src/components/RenderErrorBoundary.tsx b/apps/web/src/components/RenderErrorBoundary.tsx
index 29f7d612d945..a8b1ced99ae8 100644
--- a/apps/web/src/components/RenderErrorBoundary.tsx
+++ b/apps/web/src/components/RenderErrorBoundary.tsx
@@ -1,10 +1,35 @@
 import { Component, type ReactNode } from "react";
 
+interface RenderErrorBoundaryProps {
+  readonly children: ReactNode;
+  readonly fallback: ReactNode;
+  readonly resetKeys?: ReadonlyArray<unknown>;
+}
+
+interface RenderErrorBoundaryState {
+  readonly failed: boolean;
+  readonly resetKeys?: ReadonlyArray<unknown> | undefined;
+}
+
 export class RenderErrorBoundary extends Component<
-  { readonly children: ReactNode; readonly fallback: ReactNode },
-  { readonly failed: boolean }
+  RenderErrorBoundaryProps,
+  RenderErrorBoundaryState
 > {
-  override state = { failed: false };
+  override state = { failed: false, resetKeys: this.props.resetKeys };
+
+  // Retry changed inputs without remounting healthy children or their controls.
+  static getDerivedStateFromProps(
+    { resetKeys }: RenderErrorBoundaryProps,
+    state: RenderErrorBoundaryState,
+  ) {
+    if (
+      resetKeys?.length !== state.resetKeys?.length ||
+      resetKeys?.some((key, index) => !Object.is(key, state.resetKeys?.[index]))
+    ) {
+      return { failed: false, resetKeys };
+    }
+    return null;
+  }
 
   static getDerivedStateFromError() {
     return { failed: true };
diff --git a/apps/web/src/components/ServerUpdateAction.test.tsx b/apps/web/src/components/ServerUpdateAction.test.tsx
index 584078c12bf4..67236361f677 100644
--- a/apps/web/src/components/ServerUpdateAction.test.tsx
+++ b/apps/web/src/components/ServerUpdateAction.test.tsx
@@ -15,7 +15,8 @@ vi.mock("~/hooks/useCopyToClipboard", () => ({
   useCopyToClipboard: () => ({ copyToClipboard: vi.fn() }),
 }));
 vi.mock("~/hooks/useSettings", () => ({
-  useClientSettings: (
+  useEnvironmentSettings: (
+    _environmentId: EnvironmentId,
     selector: (settings: { continueThreadsAfterServerUpdate: boolean }) => unknown,
   ) => selector({ continueThreadsAfterServerUpdate: testState.continueThreadsAfterServerUpdate }),
 }));
diff --git a/apps/web/src/components/ServerUpdateAction.tsx b/apps/web/src/components/ServerUpdateAction.tsx
index 71b974416dd3..1845ada716b6 100644
--- a/apps/web/src/components/ServerUpdateAction.tsx
+++ b/apps/web/src/components/ServerUpdateAction.tsx
@@ -8,7 +8,7 @@ import type { ComponentProps } from "react";
 
 import { requestConfirmDialog } from "~/confirmDialog";
 import { useCopyToClipboard } from "~/hooks/useCopyToClipboard";
-import { useClientSettings } from "~/hooks/useSettings";
+import { useEnvironmentSettings } from "~/hooks/useSettings";
 import { serverEnvironment } from "~/state/server";
 import { useAtomCommand } from "~/state/use-atom-command";
 import { manualServerUpdateCommand } from "~/versionSkew";
@@ -99,7 +99,8 @@ export function ServerUpdateAction({
   readonly size?: ComponentProps<typeof Button>["size"];
 }) {
   const isDesktopAppUpdate = selfUpdate === "desktop-managed";
-  const continueThreadsAfterServerUpdate = useClientSettings(
+  const continueThreadsAfterServerUpdate = useEnvironmentSettings(
+    environmentId,
     (settings) => settings.continueThreadsAfterServerUpdate,
   );
   const updateServer = useAtomCommand(serverEnvironment.updateServer, {
diff --git a/apps/web/src/components/Sidebar.logic.test.ts b/apps/web/src/components/Sidebar.logic.test.ts
index dbf8fcf78532..cd56835ffd8b 100644
--- a/apps/web/src/components/Sidebar.logic.test.ts
+++ b/apps/web/src/components/Sidebar.logic.test.ts
@@ -4,15 +4,14 @@ import {
   animatePinnedLayoutChanges,
   archiveSelectedThreadEntries,
   buildBulkTitleRegenerationContextMenuItem,
+  buildBulkUnpinContextMenuItem,
   buildMultiSelectThreadContextMenuItems,
   createThreadJumpHintVisibilityController,
   filterSidebarProjectScopeItems,
   getSidebarThreadIdsToPrewarm,
-  getVisibleSidebarThreadIds,
   resolveAdjacentThreadId,
   reduceSidebarProjectScopeMenuState,
   getFallbackThreadIdAfterDelete,
-  getVisibleThreadsForProject,
   getProjectSortTimestamp,
   hasUnseenCompletion,
   isContextMenuPointerDown,
@@ -26,8 +25,8 @@ import {
   resolveWorkingStartedAt,
   searchSidebarThreadsByTitle,
   formatWorkingDurationLabel,
-  shouldNavigateAfterProjectRemoval,
   shouldClearThreadSelectionOnMouseDown,
+  shouldRecedeSidebarThread,
   sortLogicalProjectsForSidebar,
   sortSettledThreadsForSidebar,
   pinOrderKeyBetween,
@@ -82,56 +81,6 @@ describe("animatePinnedLayoutChanges", () => {
   });
 });
 
-describe("shouldNavigateAfterProjectRemoval", () => {
-  const projectThreads = [{ environmentId: "environment-local", id: "thread-1" }];
-
-  it("navigates away from a draft route owned by the removed project", () => {
-    expect(
-      shouldNavigateAfterProjectRemoval({
-        routeTarget: { kind: "draft", draftId: "draft-1" as never },
-        projectThreads,
-        projectDraftId: "draft-1",
-      }),
-    ).toBe(true);
-  });
-
-  it("does not navigate away from a different draft route", () => {
-    expect(
-      shouldNavigateAfterProjectRemoval({
-        routeTarget: { kind: "draft", draftId: "draft-2" as never },
-        projectThreads,
-        projectDraftId: "draft-1",
-      }),
-    ).toBe(false);
-  });
-
-  it("navigates away from a server thread owned by the removed project", () => {
-    expect(
-      shouldNavigateAfterProjectRemoval({
-        routeTarget: {
-          kind: "server",
-          threadRef: {
-            environmentId: EnvironmentId.make("environment-local"),
-            threadId: ThreadId.make("thread-1"),
-          },
-        },
-        projectThreads,
-        projectDraftId: null,
-      }),
-    ).toBe(true);
-  });
-
-  it("does not navigate from an unrelated route", () => {
-    expect(
-      shouldNavigateAfterProjectRemoval({
-        routeTarget: null,
-        projectThreads,
-        projectDraftId: null,
-      }),
-    ).toBe(false);
-  });
-});
-
 describe("archiveSelectedThreadEntries", () => {
   const entries = [{ threadKey: "one" }, { threadKey: "two" }, { threadKey: "three" }] as const;
   const success = { _tag: "Success" } as const;
@@ -185,6 +134,19 @@ describe("archiveSelectedThreadEntries", () => {
   });
 });
 
+describe("buildBulkUnpinContextMenuItem", () => {
+  it("counts only the pinned rows of a mixed selection", () => {
+    expect(buildBulkUnpinContextMenuItem({ pinnedCount: 2 })).toEqual({
+      id: "unpin",
+      label: "Unpin (2)",
+    });
+  });
+
+  it("omits the action when nothing selected is pinned", () => {
+    expect(buildBulkUnpinContextMenuItem({ pinnedCount: 0 })).toBeNull();
+  });
+});
+
 describe("buildBulkTitleRegenerationContextMenuItem", () => {
   it("counts only threads that can start a new regeneration", () => {
     expect(
@@ -281,6 +243,51 @@ describe("hasUnseenCompletion", () => {
   });
 });
 
+describe("shouldRecedeSidebarThread", () => {
+  it.each(["working", "monitoring"] as const)(
+    "recedes an inactive %s thread even when it is unread and woke",
+    (status) => {
+      expect(
+        shouldRecedeSidebarThread({
+          status,
+          isUnread: true,
+          isWoke: true,
+          isActive: false,
+          isSelected: false,
+        }),
+      ).toBe(true);
+    },
+  );
+
+  it.each(["ready", "approval", "input"] as const)(
+    "keeps an unread %s thread prominent",
+    (status) => {
+      expect(
+        shouldRecedeSidebarThread({
+          status,
+          isUnread: true,
+          isWoke: false,
+          isActive: false,
+          isSelected: false,
+        }),
+      ).toBe(false);
+    },
+  );
+
+  it("keeps active and selected working threads prominent", () => {
+    const input = {
+      status: "working" as const,
+      isUnread: true,
+      isWoke: true,
+      isActive: false,
+      isSelected: false,
+    };
+
+    expect(shouldRecedeSidebarThread({ ...input, isActive: true })).toBe(false);
+    expect(shouldRecedeSidebarThread({ ...input, isSelected: true })).toBe(false);
+  });
+});
+
 describe("createThreadJumpHintVisibilityController", () => {
   beforeEach(() => {
     vi.useFakeTimers();
@@ -584,46 +591,6 @@ describe("resolveAdjacentThreadId", () => {
   });
 });
 
-describe("getVisibleSidebarThreadIds", () => {
-  it("returns only the rendered visible thread order across projects", () => {
-    expect(
-      getVisibleSidebarThreadIds([
-        {
-          renderedThreadIds: [
-            ThreadId.make("thread-12"),
-            ThreadId.make("thread-11"),
-            ThreadId.make("thread-10"),
-          ],
-        },
-        {
-          renderedThreadIds: [ThreadId.make("thread-8"), ThreadId.make("thread-6")],
-        },
-      ]),
-    ).toEqual([
-      ThreadId.make("thread-12"),
-      ThreadId.make("thread-11"),
-      ThreadId.make("thread-10"),
-      ThreadId.make("thread-8"),
-      ThreadId.make("thread-6"),
-    ]);
-  });
-
-  it("skips threads from collapsed projects whose thread panels are not shown", () => {
-    expect(
-      getVisibleSidebarThreadIds([
-        {
-          shouldShowThreadPanel: false,
-          renderedThreadIds: [ThreadId.make("thread-hidden-2"), ThreadId.make("thread-hidden-1")],
-        },
-        {
-          shouldShowThreadPanel: true,
-          renderedThreadIds: [ThreadId.make("thread-12"), ThreadId.make("thread-11")],
-        },
-      ]),
-    ).toEqual([ThreadId.make("thread-12"), ThreadId.make("thread-11")]);
-  });
-});
-
 describe("isContextMenuPointerDown", () => {
   it("treats secondary-button presses as context menu gestures on all platforms", () => {
     expect(
@@ -1302,57 +1269,6 @@ describe("resolveProjectStatusIndicator", () => {
   });
 });
 
-describe("getVisibleThreadsForProject", () => {
-  it("includes the active thread even when it falls below the folded preview", () => {
-    const threads = Array.from({ length: 8 }, (_, index) =>
-      makeThread({
-        id: ThreadId.make(`thread-${index + 1}`),
-        title: `Thread ${index + 1}`,
-      }),
-    );
-
-    const result = getVisibleThreadsForProject({
-      threads,
-      activeThreadId: ThreadId.make("thread-8"),
-      isThreadListExpanded: false,
-      previewLimit: 6,
-    });
-
-    expect(result.hasHiddenThreads).toBe(true);
-    expect(result.visibleThreads.map((thread) => thread.id)).toEqual([
-      ThreadId.make("thread-1"),
-      ThreadId.make("thread-2"),
-      ThreadId.make("thread-3"),
-      ThreadId.make("thread-4"),
-      ThreadId.make("thread-5"),
-      ThreadId.make("thread-6"),
-      ThreadId.make("thread-8"),
-    ]);
-    expect(result.hiddenThreads.map((thread) => thread.id)).toEqual([ThreadId.make("thread-7")]);
-  });
-
-  it("returns all threads when the list is expanded", () => {
-    const threads = Array.from({ length: 8 }, (_, index) =>
-      makeThread({
-        id: ThreadId.make(`thread-${index + 1}`),
-      }),
-    );
-
-    const result = getVisibleThreadsForProject({
-      threads,
-      activeThreadId: ThreadId.make("thread-8"),
-      isThreadListExpanded: true,
-      previewLimit: 6,
-    });
-
-    expect(result.hasHiddenThreads).toBe(true);
-    expect(result.visibleThreads.map((thread) => thread.id)).toEqual(
-      threads.map((thread) => thread.id),
-    );
-    expect(result.hiddenThreads).toEqual([]);
-  });
-});
-
 function makeProject(overrides: Partial<Project> = {}): Project {
   const { defaultModelSelection, ...rest } = overrides;
   return {
diff --git a/apps/web/src/components/Sidebar.logic.ts b/apps/web/src/components/Sidebar.logic.ts
index b5bb7bc77cc9..92cdf72c51fe 100644
--- a/apps/web/src/components/Sidebar.logic.ts
+++ b/apps/web/src/components/Sidebar.logic.ts
@@ -12,7 +12,6 @@ import {
   type ThreadSortInput,
 } from "../lib/threadSort";
 import type { SidebarThreadSummary, Thread } from "../types";
-import type { ThreadRouteTarget } from "../threadRoutes";
 import { cn } from "../lib/utils";
 import { isLatestTurnSettled } from "../session-logic";
 
@@ -177,6 +176,18 @@ export function buildBulkTitleRegenerationContextMenuItem(input: {
   };
 }
 
+/**
+ * Bulk unpin follows the same "count only what the action will touch" rule
+ * as title regeneration: on a mixed selection the label counts the pinned
+ * rows alone, and the item disappears when nothing selected is pinned.
+ */
+export function buildBulkUnpinContextMenuItem(input: {
+  pinnedCount: number;
+}): ContextMenuItem<"unpin"> | null {
+  if (input.pinnedCount === 0) return null;
+  return { id: "unpin", label: `Unpin (${input.pinnedCount})` };
+}
+
 export interface ThreadStatusPill {
   label:
     | "Working"
@@ -395,17 +406,6 @@ export function orderItemsByPreferredIds<TItem, TId>(input: {
   return [...ordered, ...remaining];
 }
 
-export function getVisibleSidebarThreadIds<TThreadId>(
-  renderedProjects: readonly {
-    shouldShowThreadPanel?: boolean;
-    renderedThreadIds: readonly TThreadId[];
-  }[],
-): TThreadId[] {
-  return renderedProjects.flatMap((renderedProject) =>
-    renderedProject.shouldShowThreadPanel === false ? [] : renderedProject.renderedThreadIds,
-  );
-}
-
 export function getSidebarThreadIdsToPrewarm<TThreadId>(
   visibleThreadIds: readonly TThreadId[],
   limit = SIDEBAR_THREAD_PREWARM_LIMIT,
@@ -440,28 +440,6 @@ export function resolveAdjacentThreadId<T>(input: {
   return currentIndex < threadIds.length - 1 ? (threadIds[currentIndex + 1] ?? null) : null;
 }
 
-export function shouldNavigateAfterProjectRemoval(input: {
-  routeTarget: ThreadRouteTarget | null;
-  projectThreads: readonly {
-    environmentId: string;
-    id: string;
-  }[];
-  projectDraftId: string | null;
-}): boolean {
-  const { projectDraftId, projectThreads, routeTarget } = input;
-  if (routeTarget?.kind === "draft") {
-    return projectDraftId === routeTarget.draftId;
-  }
-  if (routeTarget?.kind !== "server") {
-    return false;
-  }
-  return projectThreads.some(
-    (thread) =>
-      thread.environmentId === routeTarget.threadRef.environmentId &&
-      thread.id === routeTarget.threadRef.threadId,
-  );
-}
-
 export function isContextMenuPointerDown(input: {
   button: number;
   ctrlKey: boolean;
@@ -520,6 +498,21 @@ export type SidebarThreadStatus =
   | "failed"
   | "ready";
 
+export function shouldRecedeSidebarThread(input: {
+  status: SidebarThreadStatus;
+  isUnread: boolean;
+  isWoke: boolean;
+  isActive: boolean;
+  isSelected: boolean;
+}): boolean {
+  if (input.isActive || input.isSelected) return false;
+  if (input.status === "working" || input.status === "monitoring") return true;
+  if (input.status === "ready" || input.status === "approval" || input.status === "input") {
+    return !input.isUnread && !input.isWoke;
+  }
+  return false;
+}
+
 type SidebarThreadStatusInput = Pick<
   SidebarThreadSummary,
   "hasPendingApprovals" | "hasPendingUserInput" | "session" | "backgroundLiveness"
@@ -811,54 +804,6 @@ export function resolveProjectStatusIndicator(
   return highestPriorityStatus;
 }
 
-export function getVisibleThreadsForProject<T extends Pick<Thread, "id">>(input: {
-  threads: readonly T[];
-  activeThreadId: T["id"] | undefined;
-  isThreadListExpanded: boolean;
-  previewLimit: number;
-}): {
-  hasHiddenThreads: boolean;
-  visibleThreads: T[];
-  hiddenThreads: T[];
-} {
-  const { activeThreadId, isThreadListExpanded, previewLimit, threads } = input;
-  const hasHiddenThreads = threads.length > previewLimit;
-
-  if (!hasHiddenThreads || isThreadListExpanded) {
-    return {
-      hasHiddenThreads,
-      hiddenThreads: [],
-      visibleThreads: [...threads],
-    };
-  }
-
-  const previewThreads = threads.slice(0, previewLimit);
-  if (!activeThreadId || previewThreads.some((thread) => thread.id === activeThreadId)) {
-    return {
-      hasHiddenThreads: true,
-      hiddenThreads: threads.slice(previewLimit),
-      visibleThreads: previewThreads,
-    };
-  }
-
-  const activeThread = threads.find((thread) => thread.id === activeThreadId);
-  if (!activeThread) {
-    return {
-      hasHiddenThreads: true,
-      hiddenThreads: threads.slice(previewLimit),
-      visibleThreads: previewThreads,
-    };
-  }
-
-  const visibleThreadIds = new Set([...previewThreads, activeThread].map((thread) => thread.id));
-
-  return {
-    hasHiddenThreads: true,
-    hiddenThreads: threads.filter((thread) => !visibleThreadIds.has(thread.id)),
-    visibleThreads: threads.filter((thread) => visibleThreadIds.has(thread.id)),
-  };
-}
-
 export function getFallbackThreadIdAfterDelete<
   T extends Pick<Thread, "id" | "projectId" | "createdAt" | "updatedAt"> & ThreadSortInput,
 >(input: {
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index d0ededf6ed83..082ccd13f2ed 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -25,6 +25,7 @@ import {
 import { resolveSettledThreadTimestamp } from "@t3tools/client-runtime/state/thread-sort";
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/models";
 import {
+  parseScopedThreadKey,
   scopeProjectRef,
   scopeThreadRef,
   scopedThreadKey,
@@ -101,17 +102,25 @@ import {
   type SidebarProjectSnapshot,
 } from "../sidebarProjectGrouping";
 import { legacyProjectCwdPreferenceKey, useUiStateStore } from "../uiStateStore";
-import { useThreadSelectionStore } from "../threadSelectionStore";
+import {
+  getThreadKeysToDeselectAfterDelete,
+  useThreadSelectionStore,
+} from "../threadSelectionStore";
 import { useThreadActions } from "../hooks/useThreadActions";
 import { useHandleNewThread } from "../hooks/useHandleNewThread";
-import { openCommandPalette } from "../commandPaletteBus";
+import { isCommandPaletteOpen, openCommandPalette } from "../commandPaletteBus";
 import { startNewThreadFromContext } from "../lib/chatThreadActions";
 import { useClientSettings } from "../hooks/useSettings";
 import { useCopyToClipboard } from "../hooks/useCopyToClipboard";
 import { useLocalStorage } from "../hooks/useLocalStorage";
 import { useNowMinute } from "../hooks/useNowMinute";
 import { useEnvironments, usePrimaryEnvironmentId } from "../state/environments";
-import { useProjects, useThreadShells } from "../state/entities";
+import {
+  readThreadShell,
+  useAllEnvironmentProjectSnapshotsReady,
+  useProjects,
+  useThreadShells,
+} from "../state/entities";
 import { environmentServerConfigsAtom, primaryServerKeybindingsAtom } from "../state/server";
 import { vcsEnvironment } from "../state/vcs";
 import { threadEnvironment } from "../state/threads";
@@ -130,6 +139,7 @@ import { buildThreadActionMenuItems } from "./threadActionMenu.logic";
 import {
   animatePinnedLayoutChanges,
   buildBulkTitleRegenerationContextMenuItem,
+  buildBulkUnpinContextMenuItem,
   filterSidebarProjectScopeItems,
   formatWorkingDurationLabel,
   firstValidTimestampMs,
@@ -143,6 +153,7 @@ import {
   resolveSidebarThreadStatus,
   searchSidebarThreadsByTitle,
   shouldCreateNewThreadInCurrentProject,
+  shouldRecedeSidebarThread,
   resolveWorkingStartedAt,
   sortLogicalProjectsForSidebar,
   sortPinnedThreadsForSidebar,
@@ -203,6 +214,7 @@ import {
   composerDraftHasUserContent,
   DraftId,
   useComposerDraftStore,
+  useThreadHasUnsentDraft,
   type ComposerThreadDraftState,
   type DraftSessionState,
 } from "../composerDraftStore";
@@ -487,6 +499,11 @@ function SortablePinnedThreadRow(props: {
   return props.children({ listeners, setNodeRef, transform, transition, isDragging });
 }
 
+// Unsent work shares one look: the new-thread draft rows and thread rows
+// with unsent composer text both use this tint and pen so they read alike.
+const draftSurfaceClassName = "bg-amber-400/[0.04] hover:bg-amber-400/[0.08]";
+const draftPenClassName = "size-3 shrink-0 text-amber-600 dark:text-amber-300/80";
+
 // One unsent draft session the user has invested content in. Two lines,
 // nothing else: project name, then the typed prompt. All the draft's
 // settings (model, env mode, branch, worktree) still travel with it —
@@ -552,19 +569,14 @@ const SidebarDraftRow = memo(function SidebarDraftRow(props: {
         data-testid="sidebar-draft-row"
         className={cn(
           "group/sidebar-row relative w-full cursor-pointer overflow-hidden rounded-md text-left text-sidebar-foreground outline-none select-none",
-          props.isActive
-            ? "bg-sidebar-row-active"
-            : "bg-amber-400/[0.04] hover:bg-amber-400/[0.08]",
+          props.isActive ? "bg-sidebar-row-active" : draftSurfaceClassName,
         )}
         onClick={handleActivate}
         onKeyDown={handleKeyDown}
       >
         <div className="relative z-10 px-[var(--sidebar-row-content-inset)] py-[var(--sidebar-content-inset)]">
           <div className="flex h-5 min-w-0 items-center gap-1.5">
-            <SquarePenIcon
-              aria-hidden
-              className="size-3 shrink-0 text-amber-600 dark:text-amber-300/80"
-            />
+            <SquarePenIcon aria-hidden className={draftPenClassName} />
             <ProjectFavicon
               environmentId={session.environmentId}
               cwd={props.projectCwd ?? ""}
@@ -827,6 +839,19 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
   });
   const terminalStatus = terminalStatusFromRunningIds(runningTerminalIds);
   const terminalProcessCount = runningTerminalIds.length;
+  // Unsent composer text on this thread. The open thread shows its own
+  // composer, so the marker only decorates rows you have navigated away from.
+  const hasUnsentDraft = useThreadHasUnsentDraft(threadRef) && !props.isActive;
+  const clearComposerContent = useComposerDraftStore((store) => store.clearComposerContent);
+  const handleDiscardDraftClick = useCallback(
+    (event: ReactMouseEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+      releaseComposerDraftUploads(threadRef);
+      clearComposerContent(threadRef);
+    },
+    [clearComposerContent, threadRef],
+  );
 
   const gitCwd = thread.worktreePath ?? props.projectCwd;
   const linkedPullRequestStatus = useLinkedThreadPullRequest(
@@ -859,6 +884,8 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
   // switching sidebars must not light up every historical thread as unread.
   const isUnread = hasUnseenCompletion({ ...thread, lastVisitedAt });
   const status = resolveSidebarThreadStatus(thread);
+  const isInFlight =
+    status === "working" || status === "monitoring" || status === "approval" || status === "input";
   // A woken thread reappears at its original position (the sort is
   // deliberately static), so the pill has to carry the weight. Snoozing is
   // an explicit act, so the pill clears only when the user re-engages:
@@ -872,17 +899,16 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
     wokeAtDate !== null &&
     (lastVisitedDate === null || lastVisitedDate < wokeAtDate) &&
     thread.settledOverride !== "settled";
-  // In-flight rows (working, or waiting on approval/input) fade as a whole:
-  // there is nothing for the user to do yet, so prominence is reserved for
-  // rows that need a human — done (unread), read-but-unsettled, failed, and
-  // freshly woken. The status label keeps its hue, so waiting rows stay
-  // findable. In-flight rows recede the same as read-ready ones (inbox-zero:
-  // working threads aren't your problem yet) — only the colored status label
-  // stands out.
-  const isInFlight =
-    status === "working" || status === "monitoring" || status === "approval" || status === "input";
-  const shouldRecede =
-    (status === "ready" || isInFlight) && !isUnread && !isWoke && !props.isActive && !isSelected;
+  // Background work always recedes when it is not selected: an unread parent
+  // completion must not pull a still-working thread back into the foreground.
+  // Ready and action-required rows keep their unread and wake prominence.
+  const shouldRecede = shouldRecedeSidebarThread({
+    status,
+    isUnread,
+    isWoke,
+    isActive: props.isActive,
+    isSelected,
+  });
   // Status hues follow the system-wide convention set by sidebar v1 and the
   // mobile Live Activity/widgets (amber approval, indigo input, sky working)
   // so a thread reads the same color everywhere it surfaces.
@@ -1163,9 +1189,11 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
       ? "bg-sidebar-row-active text-sidebar-foreground"
       : isSelected
         ? "bg-sidebar-row-selected text-sidebar-foreground"
-        : shouldRecede
-          ? "text-sidebar-muted-foreground/75 hover:bg-sidebar-row-hover hover:text-sidebar-foreground"
-          : "bg-transparent text-sidebar-foreground hover:bg-sidebar-row-hover",
+        : hasUnsentDraft
+          ? cn(draftSurfaceClassName, "text-sidebar-foreground")
+          : shouldRecede
+            ? "text-sidebar-muted-foreground/75 hover:bg-sidebar-row-hover hover:text-sidebar-foreground"
+            : "bg-transparent text-sidebar-foreground hover:bg-sidebar-row-hover",
     isInFlight &&
       !props.isActive &&
       !isSelected &&
@@ -1193,21 +1221,23 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
         variant === "card"
           ? cn(
               "truncate",
-              isUnread || isWoke
-                ? "text-foreground"
-                : shouldRecede
-                  ? "text-secondary-label"
+              shouldRecede
+                ? "text-secondary-label"
+                : isUnread || isWoke
+                  ? "text-foreground"
                   : status === "failed"
                     ? "text-foreground/95"
                     : "text-foreground/90",
             )
           : cn(
               "truncate group-hover/sidebar-row:text-foreground",
-              props.isActive || isWoke
-                ? "text-foreground"
-                : isUnread
-                  ? "text-muted-foreground"
-                  : "text-secondary-label/70",
+              shouldRecede
+                ? "text-secondary-label/70"
+                : props.isActive || isWoke
+                  ? "text-foreground"
+                  : isUnread
+                    ? "text-muted-foreground"
+                    : "text-secondary-label/70",
             ),
         isRegeneratingTitle && "opacity-[0.55]",
       )}
@@ -1251,6 +1281,25 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
       <TerminalIcon className={cn("size-3.5", terminalStatus.pulse && "animate-status-pulse")} />
     </span>
   ) : null;
+  // Same pen the new-thread draft rows lead with, so both kinds of unsent
+  // work read the same way in the list.
+  const draftIndicator = hasUnsentDraft ? (
+    <Tooltip>
+      <TooltipTrigger
+        render={
+          <span
+            role="img"
+            aria-label="Unsent draft"
+            data-testid={`sidebar-draft-indicator-${thread.id}`}
+            className="inline-flex shrink-0 items-center"
+          />
+        }
+      >
+        <SquarePenIcon aria-hidden className={draftPenClassName} />
+      </TooltipTrigger>
+      <TooltipPopup side="top">Unsent draft</TooltipPopup>
+    </Tooltip>
+  ) : null;
   const pinIndicator = props.isPinned ? (
     props.pinningSupported ? (
       <Tooltip>
@@ -1318,6 +1367,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
                 className="size-4"
               />
             </span>
+            {draftIndicator}
             {title}
             {pinIndicator}
             {terminalStatusIcon}
@@ -1465,6 +1515,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
         >
           <div className="relative z-10 h-[4.875rem] px-[var(--sidebar-row-content-inset)] py-[var(--sidebar-content-inset)]">
             <div className="flex h-5 min-w-0 items-center gap-1.5">
+              {draftIndicator}
               <ProjectFavicon
                 environmentId={thread.environmentId}
                 cwd={props.projectCwd ?? ""}
@@ -1551,7 +1602,7 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
                     threadTimeLabel(thread)
                   )}
                 </span>
-                {props.settlementSupported || showSnoozeButton ? (
+                {props.settlementSupported || showSnoozeButton || hasUnsentDraft ? (
                   <span
                     className={cn(
                       // focus-visible, not focus-within: a mouse click leaves
@@ -1563,6 +1614,23 @@ const SidebarThreadRow = memo(function SidebarThreadRow(props: {
                       snoozeMenuOpen && "pointer-events-auto static opacity-100",
                     )}
                   >
+                    {hasUnsentDraft ? (
+                      <Tooltip>
+                        <TooltipTrigger
+                          render={
+                            <button
+                              type="button"
+                              aria-label="Discard draft"
+                              onClick={handleDiscardDraftClick}
+                              className="inline-flex cursor-pointer items-center rounded-md bg-transparent px-1.5 text-xs text-muted-foreground hover:text-foreground"
+                            />
+                          }
+                        >
+                          <XIcon className="size-3.5" />
+                        </TooltipTrigger>
+                        <TooltipPopup side="top">Discard draft</TooltipPopup>
+                      </Tooltip>
+                    ) : null}
                     {showSnoozeButton ? (
                       <SnoozePopoverButton
                         open={snoozeMenuOpen}
@@ -2039,7 +2107,11 @@ export default function Sidebar() {
 
   // Project scope: one menu above the list. Scoping filters the list without
   // making the header width depend on the number or length of project names.
-  const [projectScopeKey, setProjectScopeKey] = useState<string | null>(null);
+  // The selection lives in the persisted UI store next to the other sidebar
+  // project preferences, so routes that unmount the sidebar (Settings) and
+  // app restarts keep it.
+  const projectScopeKey = useUiStateStore((store) => store.sidebarProjectScopeKey);
+  const setProjectScopeKey = useUiStateStore((store) => store.setSidebarProjectScopeKey);
   // {value, label} items let Base UI drive the combobox selection contract
   // while the popup search filters the same collection.
   const projectScopeItems = useMemo(
@@ -2103,11 +2175,15 @@ export default function Sidebar() {
           ),
     [scopedProjectGroup],
   );
+  // A persisted scope whose project is gone falls back to all projects, but
+  // only after every catalog environment has a live project snapshot. Cached
+  // or disconnected environments cannot establish that the project is gone.
+  const allProjectSnapshotsReady = useAllEnvironmentProjectSnapshotsReady();
   useEffect(() => {
-    if (projectScopeKey !== null && scopedProjectGroup === null) {
+    if (projectScopeKey !== null && allProjectSnapshotsReady && scopedProjectGroup === null) {
       setProjectScopeKey(null);
     }
-  }, [projectScopeKey, scopedProjectGroup]);
+  }, [allProjectSnapshotsReady, projectScopeKey, scopedProjectGroup, setProjectScopeKey]);
   // Count-only subscription: the parent needs "are there draft rows" for the
   // empty state, while SidebarDraftBlock owns the per-keystroke content
   // subscription. Selecting a number keeps typing in a draft composer from
@@ -2152,10 +2228,18 @@ export default function Sidebar() {
     },
     [isMobile, router, setOpenMobile],
   );
+  // Safari can send a click after Ctrl+click opens settings. Ignore that one
+  // selection, then clear the guard when the picker opens again.
+  const suppressNextScopeChangeRef = useRef(false);
+  const highlightedProjectScopeKeyRef = useRef<string | null>(null);
   const handleProjectSettings = useCallback(
-    (event: ReactMouseEvent<HTMLButtonElement>, projectGroup: SidebarProjectSnapshot) => {
+    (
+      event: ReactMouseEvent<HTMLElement> | ReactKeyboardEvent<HTMLInputElement>,
+      projectGroup: SidebarProjectSnapshot,
+    ) => {
       event.preventDefault();
       event.stopPropagation();
+      suppressNextScopeChangeRef.current = true;
       dispatchProjectScopeMenu({ type: "project-settings-opened" });
       openProjectSettings(projectGroup);
     },
@@ -2942,8 +3026,9 @@ export default function Sidebar() {
       // right now. Selections can outlive their rows (settled-tail paging,
       // thread deletion elsewhere) and the menu labels must count only what
       // the actions will touch.
-      const threadKeys = [...useThreadSelectionStore.getState().selectedThreadKeys].filter(
-        (threadKey) => threadByKeyRef.current.has(threadKey),
+      const selectedThreadKeys = [...useThreadSelectionStore.getState().selectedThreadKeys];
+      const threadKeys = selectedThreadKeys.filter((threadKey) =>
+        threadByKeyRef.current.has(threadKey),
       );
       if (threadKeys.length === 0) return;
       const count = threadKeys.length;
@@ -2971,10 +3056,22 @@ export default function Sidebar() {
         supportedCount: titleRegenerationThreads.length,
         actionableCount: regeneratableTitleThreads.length,
       });
+      // Unpin (k) counts only the pinned rows in pin-capable environments —
+      // on a mixed selection the unpinned rows are untouched, and the item
+      // is omitted entirely when nothing selected is pinned.
+      const pinnedSelectedThreads = selectedThreads.filter(
+        (thread) =>
+          serverConfigs.get(thread.environmentId)?.environment.capabilities.threadPinning ===
+            true && thread.pinnedAt != null,
+      );
+      const unpinMenuItem = buildBulkUnpinContextMenuItem({
+        pinnedCount: pinnedSelectedThreads.length,
+      });
       const snoozePresets = resolveSnoozePresets(new Date(), timestampFormat);
       const clicked = await settlePromise(() =>
         api.contextMenu.show(
           [
+            ...(unpinMenuItem ? [unpinMenuItem] : []),
             { id: "settle", label: `Settle (${count})` },
             ...(canSnoozeSelection
               ? [
@@ -3056,6 +3153,14 @@ export default function Sidebar() {
         }
         return;
       }
+      if (clicked.value === "unpin") {
+        // Each unpin reports its own failure, like the single-row action.
+        for (const thread of pinnedSelectedThreads) {
+          attemptUnpin(scopeThreadRef(thread.environmentId, thread.id));
+        }
+        clearSelection();
+        return;
+      }
       if (clicked.value === "regenerate-title") {
         for (const thread of regeneratableTitleThreads) {
           const result = await updateThreadMetadata({
@@ -3119,6 +3224,7 @@ export default function Sidebar() {
       // really gone, or the first delete would treat still-alive batch mates
       // as deleted and remove a worktree they still point at.
       const deletedThreadKeys = new Set<string>();
+      let firstError: unknown = null;
       for (const threadKey of threadKeys) {
         const thread = threadByKeyRef.current.get(threadKey);
         if (!thread) continue;
@@ -3126,25 +3232,32 @@ export default function Sidebar() {
           deletedThreadKeys,
         });
         if (result._tag === "Failure") {
-          if (!isAtomCommandInterrupted(result)) {
-            const error = squashAtomCommandFailure(result);
-            toastManager.add(
-              stackedThreadToast({
-                type: "error",
-                title: "Failed to delete threads",
-                description: error instanceof Error ? error.message : "An error occurred.",
-              }),
-            );
-          }
-          return;
+          if (isAtomCommandInterrupted(result)) break;
+          firstError ??= squashAtomCommandFailure(result);
+          continue;
         }
         deletedThreadKeys.add(threadKey);
       }
-      removeFromSelection(threadKeys);
+      if (firstError !== null) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Failed to delete threads",
+            description: firstError instanceof Error ? firstError.message : "An error occurred.",
+          }),
+        );
+      }
+      removeFromSelection(
+        getThreadKeysToDeselectAfterDelete(selectedThreadKeys, deletedThreadKeys, (threadKey) => {
+          const threadRef = parseScopedThreadKey(threadKey);
+          return threadRef !== null && readThreadShell(threadRef) !== null;
+        }),
+      );
     },
     [
       attemptSettle,
       attemptSnooze,
+      attemptUnpin,
       clearSelection,
       confirmThreadDelete,
       deleteThread,
@@ -3413,7 +3526,9 @@ export default function Sidebar() {
   );
   useEffect(() => {
     const onWindowKeyDown = (event: KeyboardEvent) => {
-      if (event.defaultPrevented || event.repeat) return;
+      if (event.defaultPrevented || event.repeat || isCommandPaletteOpen() || isModelPickerOpen()) {
+        return;
+      }
       const command = resolveShortcutCommand(event, keybindings, {
         platform: navigator.platform,
         context: {
@@ -3630,10 +3745,18 @@ export default function Sidebar() {
                   isItemEqualToValue={(a, b) => a.value === b.value}
                   open={projectScopeMenuState.open}
                   onOpenChange={(open) => {
+                    if (open) suppressNextScopeChangeRef.current = false;
                     dispatchProjectScopeMenu({ type: "open-changed", open });
                   }}
+                  onItemHighlighted={(item) => {
+                    highlightedProjectScopeKeyRef.current = item?.value ?? null;
+                  }}
                   value={selectedProjectScopeItem}
                   onValueChange={(item) => {
+                    if (suppressNextScopeChangeRef.current) {
+                      suppressNextScopeChangeRef.current = false;
+                      return;
+                    }
                     if (!item) return;
                     setProjectScopeKey(item.value === "all" ? null : item.value);
                   }}
@@ -3684,6 +3807,24 @@ export default function Sidebar() {
                           size="sm"
                           unstyled
                           value={projectScopeMenuState.query}
+                          onKeyDown={(event) => {
+                            if (
+                              event.defaultPrevented ||
+                              event.nativeEvent.isComposing ||
+                              event.ctrlKey ||
+                              event.altKey ||
+                              event.metaKey ||
+                              (event.key !== "ContextMenu" &&
+                                !(event.shiftKey && event.key === "F10"))
+                            ) {
+                              return;
+                            }
+                            // Combobox items use virtual focus: keyboard events
+                            // stay on this input, not on the highlighted option.
+                            const scopeKey = highlightedProjectScopeKeyRef.current;
+                            const project = scopeKey ? projectGroupByScopeKey.get(scopeKey) : null;
+                            if (project) handleProjectSettings(event, project);
+                          }}
                           onChange={(event) =>
                             dispatchProjectScopeMenu({
                               type: "query-changed",
@@ -3704,6 +3845,9 @@ export default function Sidebar() {
                             value={item}
                             className="h-8 min-h-8 py-0 font-medium"
                             contentClassName="flex min-w-0 items-center gap-2"
+                            onContextMenu={(event) => {
+                              if (project) handleProjectSettings(event, project);
+                            }}
                           >
                             {project ? (
                               <ProjectFavicon
@@ -3722,7 +3866,8 @@ export default function Sidebar() {
                               <Button
                                 size="icon-xs"
                                 variant="ghost-muted"
-                                aria-label={`Project settings for ${project.displayName}`}
+                                tabIndex={-1}
+                                aria-hidden="true"
                                 title={`Project settings for ${project.displayName}`}
                                 className="ml-auto size-6 [--control-icon-color:currentColor] text-icon-muted focus-visible:bg-accent focus-visible:text-foreground"
                                 onPointerDown={(event) => event.stopPropagation()}
diff --git a/apps/web/src/components/ThreadTerminalDrawer.test.ts b/apps/web/src/components/ThreadTerminalDrawer.test.ts
index d9dcd6e79936..1624a739bb1a 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.test.ts
+++ b/apps/web/src/components/ThreadTerminalDrawer.test.ts
@@ -1,11 +1,98 @@
-import { describe, expect, it } from "vite-plus/test";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
 import {
   shouldClearTerminalSelectionAction,
   shouldHandleTerminalExit,
+  terminalContextMenuItems,
   terminalSelectionLineRange,
+  terminalSelectionMenuItems,
+  terminalThemeFromApp,
 } from "./ThreadTerminalDrawer";
 
+describe("terminal selection menus", () => {
+  it("omits Add to chat when the terminal has no chat target", () => {
+    expect(terminalSelectionMenuItems().map(({ id }) => id)).toEqual(["add-to-chat", "copy"]);
+    expect(terminalContextMenuItems({ hasSelection: true }).map(({ id }) => id)).toEqual([
+      "add-to-chat",
+      "copy",
+      "paste",
+    ]);
+
+    expect(terminalSelectionMenuItems({ canAddToChat: false }).map(({ id }) => id)).toEqual([
+      "copy",
+    ]);
+    expect(
+      terminalContextMenuItems({ hasSelection: true, canAddToChat: false }).map(({ id }) => id),
+    ).toEqual(["copy", "paste"]);
+  });
+});
+
+describe("terminalThemeFromApp", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("uses terminal colors inherited by the mount instead of a light document theme", () => {
+    const root = { classList: { contains: () => false } };
+    const body = {};
+    const drawer = {};
+    let canvasColor = "#000";
+    const colors: Record<string, [number, number, number, number]> = {
+      "#000": [0, 0, 0, 255],
+      "#fff": [255, 255, 255, 255],
+      "#ddd": [221, 221, 221, 255],
+      "#111": [17, 17, 17, 255],
+    };
+
+    vi.stubGlobal("document", {
+      documentElement: root,
+      body,
+      querySelector: () => drawer,
+      createElement: () => ({
+        width: 0,
+        height: 0,
+        getContext: () => ({
+          clearRect: () => undefined,
+          fillRect: () => undefined,
+          get fillStyle() {
+            return canvasColor;
+          },
+          set fillStyle(value: string) {
+            canvasColor = value;
+          },
+          getImageData: () => ({ data: colors[canvasColor] ?? [0, 0, 0, 0] }),
+        }),
+      }),
+    });
+    vi.stubGlobal("getComputedStyle", (element: object) => {
+      const local = element === drawer;
+      const values = local
+        ? {
+            "--terminal-background": "#000",
+            "--terminal-foreground": "#fff",
+            "--terminal-cursor": "#ddd",
+            "--terminal-selection-background": "rgba(255, 255, 255, 0.2)",
+          }
+        : {
+            "--terminal-background": "#fff",
+            "--terminal-foreground": "#111",
+          };
+      return {
+        backgroundColor: local ? "#000" : "#fff",
+        color: local ? "#fff" : "#111",
+        colorScheme: local ? "dark" : "light",
+        getPropertyValue: (name: string) => values[name as keyof typeof values] ?? "",
+      };
+    });
+
+    const theme = terminalThemeFromApp();
+
+    expect(theme.background).toEqual({ r: 0, g: 0, b: 0 });
+    expect(theme.foreground).toEqual({ r: 255, g: 255, b: 255 });
+    expect(theme.cursor).toEqual({ r: 221, g: 221, b: 221 });
+  });
+});
+
 describe("terminal selection actions", () => {
   it("clears a pending or currently owned menu when the selection disappears", () => {
     expect(
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index 1c64818c5794..d9ddf9225bdf 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -3,7 +3,13 @@ import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
-import { type TerminalSessionState } from "@t3tools/client-runtime/state/terminal";
+import {
+  INITIAL_TERMINAL_OUTPUT_CURSOR,
+  readTerminalOutputUpdate,
+  type TerminalOutputCursor,
+  type TerminalOutputUpdate,
+  type TerminalSessionState,
+} from "@t3tools/client-runtime/state/terminal";
 import {
   Plus,
   Square,
@@ -14,6 +20,7 @@ import {
 } from "lucide-react";
 import {
   type ContextMenuItem,
+  type ProviderInstanceId,
   type ResolvedKeybindingsConfig,
   type ScopedThreadRef,
   type ThreadId,
@@ -27,6 +34,7 @@ import {
   useCallback,
   useEffect,
   useEffectEvent,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -34,6 +42,7 @@ import {
 import { Popover, PopoverPopup, PopoverTrigger } from "~/components/ui/popover";
 import { Button } from "~/components/ui/button";
 import { PanelTabCloseButton } from "~/components/ui/panel-tab-close-button";
+import { stackedThreadToast, toastManager } from "~/components/ui/toast";
 import { readTextFromClipboard, writeTextToClipboard } from "~/hooks/useCopyToClipboard";
 import { cn } from "~/lib/utils";
 import { type TerminalContextSelection } from "~/lib/terminalContext";
@@ -99,8 +108,15 @@ function writeSystemMessage(terminal: GhosttyTerminalSurface, message: string):
   terminal.write(`\r\n[terminal] ${message}\r\n`);
 }
 
-function writeTerminalBuffer(terminal: GhosttyTerminalSurface, buffer: string): void {
-  terminal.resetAndWrite(buffer);
+export function writeTerminalOutputUpdate(
+  terminal: Pick<GhosttyTerminalSurface, "resetAndWrite" | "write">,
+  update: TerminalOutputUpdate,
+): void {
+  if (update.type === "reset") {
+    terminal.resetAndWrite(update.data);
+  } else if (update.type === "append") {
+    terminal.write(update.data);
+  }
 }
 
 function parseTerminalColor(value: string, fallback: GhosttyColor): GhosttyColor {
@@ -158,16 +174,23 @@ function terminalFontOptions(family: string, size: number): { family?: string; s
 }
 
 export function terminalThemeFromApp(mountElement?: HTMLElement | null): GhosttyTheme {
-  const isDark = document.documentElement.classList.contains("dark");
-  const fallbackBackground = isDark ? "rgb(14, 18, 24)" : "rgb(255, 255, 255)";
-  const fallbackForeground = isDark ? "rgb(237, 241, 247)" : "rgb(28, 33, 41)";
   const drawerSurface =
     mountElement?.closest(".thread-terminal-drawer") ??
     document.querySelector(".thread-terminal-drawer") ??
     document.body;
   const drawerStyles = getComputedStyle(drawerSurface);
+  const themeStyles = mountElement ? getComputedStyle(mountElement) : drawerStyles;
+  const colorScheme = themeStyles.colorScheme;
+  const isDark =
+    colorScheme === "dark"
+      ? true
+      : colorScheme === "light"
+        ? false
+        : document.documentElement.classList.contains("dark");
+  const fallbackBackground = isDark ? "rgb(14, 18, 24)" : "rgb(255, 255, 255)";
+  const fallbackForeground = isDark ? "rgb(237, 241, 247)" : "rgb(28, 33, 41)";
   const bodyStyles = getComputedStyle(document.body);
-  const themeStyles = getComputedStyle(document.documentElement);
+  const rootThemeStyles = getComputedStyle(document.documentElement);
   const background = normalizeComputedColor(
     drawerStyles.backgroundColor,
     normalizeComputedColor(bodyStyles.backgroundColor, fallbackBackground),
@@ -176,8 +199,16 @@ export function terminalThemeFromApp(mountElement?: HTMLElement | null): Ghostty
     drawerStyles.color,
     normalizeComputedColor(bodyStyles.color, fallbackForeground),
   );
-  const terminalBackground = readThemeColor(themeStyles, "--terminal-background", background);
-  const terminalForeground = readThemeColor(themeStyles, "--terminal-foreground", foreground);
+  const terminalBackground = readThemeColor(
+    themeStyles,
+    "--terminal-background",
+    readThemeColor(rootThemeStyles, "--terminal-background", background),
+  );
+  const terminalForeground = readThemeColor(
+    themeStyles,
+    "--terminal-foreground",
+    readThemeColor(rootThemeStyles, "--terminal-foreground", foreground),
+  );
   const terminalCursor = readThemeColor(
     themeStyles,
     "--terminal-cursor",
@@ -218,10 +249,14 @@ export function terminalSelectionLineRange(position: {
 
 export type TerminalContextMenuAction = "add-to-chat" | "copy" | "paste";
 
-/** Post-selection popup: just the two selection actions, always enabled. */
-export function terminalSelectionMenuItems(): ContextMenuItem<"add-to-chat" | "copy">[] {
+/** Post-selection popup: available selection actions, always enabled. */
+export function terminalSelectionMenuItems(options?: {
+  canAddToChat?: boolean;
+}): ContextMenuItem<"add-to-chat" | "copy">[] {
   return [
-    { id: "add-to-chat", label: "Add to chat" },
+    ...(options?.canAddToChat === false
+      ? []
+      : ([{ id: "add-to-chat", label: "Add to chat" }] satisfies ContextMenuItem<"add-to-chat">[])),
     { id: "copy", label: "Copy" },
   ];
 }
@@ -234,11 +269,13 @@ export function terminalSelectionMenuItems(): ContextMenuItem<"add-to-chat" | "c
  */
 export function terminalContextMenuItems(options: {
   hasSelection: boolean;
+  canAddToChat?: boolean;
 }): ContextMenuItem<TerminalContextMenuAction>[] {
+  const { hasSelection, canAddToChat = true } = options;
   return [
-    ...terminalSelectionMenuItems().map((item) => ({
+    ...terminalSelectionMenuItems({ canAddToChat }).map((item) => ({
       ...item,
-      disabled: !options.hasSelection,
+      disabled: !hasSelection,
     })),
     { id: "paste", label: "Paste" },
   ];
@@ -278,10 +315,12 @@ interface TerminalViewportProps {
   cwd: string;
   worktreePath?: string | null;
   runtimeEnv?: Record<string, string>;
+  providerInstanceId?: ProviderInstanceId;
   onSessionExited: () => void;
-  onAddTerminalContext: (selection: TerminalContextSelection) => void;
+  onAddTerminalContext?: (selection: TerminalContextSelection) => void;
   focusRequestId: number;
   autoFocus: boolean;
+  visible: boolean;
   resizeEpoch: number;
   drawerHeight: number;
   keybindings: ResolvedKeybindingsConfig;
@@ -302,16 +341,19 @@ export function TerminalViewport({
   cwd,
   worktreePath,
   runtimeEnv,
+  providerInstanceId,
   onSessionExited,
   onAddTerminalContext,
   focusRequestId,
   autoFocus,
+  visible,
   resizeEpoch,
   drawerHeight,
   keybindings,
 }: TerminalViewportProps) {
   const containerRef = useRef<HTMLDivElement>(null);
   const terminalRef = useRef<GhosttyTerminalSurface | null>(null);
+  const visibleRef = useRef(visible);
   const environmentId = threadRef.environmentId;
   const serverConfig = useAtomValue(serverEnvironment.configValueAtom(environmentId));
   const openInPreferredEditor = useOpenInPreferredEditor(
@@ -340,8 +382,9 @@ export function TerminalViewport({
     onSessionExited();
   });
   const handleAddTerminalContext = useEffectEvent((selection: TerminalContextSelection) => {
-    onAddTerminalContext(selection);
+    onAddTerminalContext?.(selection);
   });
+  const canAddSelectionToChat = useEffectEvent(() => onAddTerminalContext !== undefined);
   const readTerminalLabel = useEffectEvent(() => terminalLabel);
   const terminalFontFamily = useClientSettings((settings) =>
     resolveTerminalFontPreference({
@@ -366,6 +409,7 @@ export function TerminalViewport({
       cwd,
       ...(worktreePath !== undefined ? { worktreePath } : {}),
       ...(runtimeEnv ? { env: runtimeEnv } : {}),
+      ...(providerInstanceId ? { providerInstanceId } : {}),
     },
   });
   const writeTerminal = useEffectEvent((data: string) =>
@@ -380,9 +424,10 @@ export function TerminalViewport({
       input: { threadId, terminalId, cols, rows },
     }),
   );
-  const terminalBuffer = terminalSession.buffer;
+  const terminalOutput = terminalSession.output;
   const terminalError = terminalSession.error;
   const terminalStatus = terminalSession.status;
+  const outputCursorRef = useRef<TerminalOutputCursor>(INITIAL_TERMINAL_OUTPUT_CURSOR);
   const synchronizedStatusRef = useRef<TerminalSessionState["status"]>("closed");
   const synchronizeTerminalStatus = useEffectEvent(
     (terminal: GhosttyTerminalSurface, status: TerminalSessionState["status"]) => {
@@ -403,14 +448,14 @@ export function TerminalViewport({
   );
   const terminalVersion = terminalSession.version;
   const previousSessionRef = useRef({
-    buffer: terminalBuffer,
+    output: terminalOutput,
     error: terminalError,
     status: terminalStatus,
     version: terminalVersion,
   });
   const latestSessionRef = useRef(previousSessionRef.current);
   latestSessionRef.current = {
-    buffer: terminalBuffer,
+    output: terminalOutput,
     error: terminalError,
     status: terminalStatus,
     version: terminalVersion,
@@ -420,6 +465,11 @@ export function TerminalViewport({
     keybindingsRef.current = keybindings;
   }, [keybindings]);
 
+  useLayoutEffect(() => {
+    visibleRef.current = visible;
+    terminalRef.current?.setVisible(visible);
+  }, [visible]);
+
   useEffect(() => {
     const current = terminalFontRef.current;
     if (current.family === terminalFontFamily && current.size === terminalFontSize) return;
@@ -443,6 +493,9 @@ export function TerminalViewport({
       const terminalOptions: GhosttyTerminalSurfaceOptions = {
         theme: terminalThemeFromApp(mount),
         font: terminalFontOptions(setupFont.family, setupFont.size),
+        get visible() {
+          return visibleRef.current;
+        },
         onData: (data) => handleData(data),
         onResize: (cols, rows) => void resizeTerminal(cols, rows),
         onSelectionChange: () => handleSelectionChange(),
@@ -460,6 +513,7 @@ export function TerminalViewport({
         terminal.dispose();
         return null;
       }
+      terminal.setVisible(visibleRef.current);
       // The theme observer is not installed yet, so re-read the theme in case
       // the app toggled light/dark while the WASM surface was loading.
       terminal.setTheme(terminalThemeFromApp(mount));
@@ -474,7 +528,14 @@ export function TerminalViewport({
       }
       const latestSession = latestSessionRef.current;
       previousSessionRef.current = latestSession;
-      if (latestSession.buffer.length > 0) terminal.resetAndWrite(latestSession.buffer);
+      const initialOutput = readTerminalOutputUpdate(
+        latestSession.output,
+        INITIAL_TERMINAL_OUTPUT_CURSOR,
+      );
+      if (initialOutput.type === "reset" && initialOutput.data.length > 0) {
+        writeTerminalOutputUpdate(terminal, initialOutput);
+      }
+      outputCursorRef.current = initialOutput.cursor;
       if (latestSession.error !== null) writeSystemMessage(terminal, latestSession.error);
       // Attaching to a session that already exited must still run exit handling
       // once, so mount synchronization starts from the empty "closed" state.
@@ -482,7 +543,10 @@ export function TerminalViewport({
       // never started, so only "exited" triggers the message — as with xterm.)
       synchronizedStatusRef.current = "closed";
       synchronizeTerminalStatus(terminal, latestSession.status);
-      if (autoFocus) window.requestAnimationFrame(() => terminal.focus());
+      // Startup may finish after the user has returned to the composer.
+      if (visibleRef.current && mount.contains(document.activeElement)) {
+        terminal.focus();
+      }
 
       const dismissSelectionAction = (supersede = false) => {
         const ownsMenu =
@@ -598,7 +662,10 @@ export function TerminalViewport({
         let clicked: TerminalContextMenuAction | null;
         try {
           clicked = await localApi.contextMenu.show(
-            terminalContextMenuItems({ hasSelection: selectionAction !== null }),
+            terminalContextMenuItems({
+              hasSelection: selectionAction !== null,
+              canAddToChat: canAddSelectionToChat(),
+            }),
             { x: event.clientX, y: event.clientY },
           );
         } catch (error) {
@@ -611,7 +678,9 @@ export function TerminalViewport({
         }
         switch (clicked) {
           case "add-to-chat":
-            if (selectionAction) addSelectionToChat(selectionAction.selection);
+            if (selectionAction && canAddSelectionToChat()) {
+              addSelectionToChat(selectionAction.selection);
+            }
             return;
           case "copy":
             if (selectionAction) await copySelection(selectionAction.clipboardText, requestId);
@@ -638,7 +707,10 @@ export function TerminalViewport({
         const requestId = ++selectionActionRequestIdRef.current;
         openSelectionMenuRequestIdRef.current = requestId;
         const clicked = await localApi.contextMenu
-          .show(terminalSelectionMenuItems(), nextAction.position)
+          .show(
+            terminalSelectionMenuItems({ canAddToChat: canAddSelectionToChat() }),
+            nextAction.position,
+          )
           .finally(() => {
             if (openSelectionMenuRequestIdRef.current === requestId) {
               openSelectionMenuRequestIdRef.current = null;
@@ -649,7 +721,7 @@ export function TerminalViewport({
         }
         switch (clicked) {
           case "add-to-chat":
-            addSelectionToChat(nextAction.selection);
+            if (canAddSelectionToChat()) addSelectionToChat(nextAction.selection);
             return;
           case "copy":
             await copySelection(nextAction.clipboardText, requestId);
@@ -731,6 +803,14 @@ export function TerminalViewport({
             threadRef,
             openPreview,
             fallbackToBrowser,
+          }).catch((error: unknown) => {
+            toastManager.add(
+              stackedThreadToast({
+                type: "error",
+                title: "Unable to open link",
+                description: error instanceof Error ? error.message : "An error occurred.",
+              }),
+            );
           });
           return;
         }
@@ -836,16 +916,16 @@ export function TerminalViewport({
 
     return () => {
       cancelled = true;
+      const hadFocus = mount.contains(document.activeElement);
       teardown?.();
+      if (hadFocus && mount.isConnected) mount.focus({ preventScroll: true });
     };
-    // autoFocus is intentionally omitted;
-    // it is only read at mount time and must not trigger terminal teardown/recreation.
   }, [cwd, environmentId, runtimeEnvKey, terminalId, threadId, worktreePath]);
 
   useEffect(() => {
     const terminal = terminalRef.current;
     const current = {
-      buffer: terminalBuffer,
+      output: terminalOutput,
       error: terminalError,
       status: terminalStatus,
       version: terminalVersion,
@@ -857,51 +937,37 @@ export function TerminalViewport({
 
     const previous = previousSessionRef.current;
     synchronizeTerminalStatus(terminal, current.status);
-    if (current.version === previous.version) {
+    if (current.version === previous.version && current.output === previous.output) {
       return;
     }
 
-    if (
-      current.buffer.length >= previous.buffer.length &&
-      current.buffer.startsWith(previous.buffer)
-    ) {
-      terminal.write(current.buffer.slice(previous.buffer.length));
-    } else {
-      writeTerminalBuffer(terminal, current.buffer);
-    }
+    const outputUpdate = readTerminalOutputUpdate(current.output, outputCursorRef.current);
+    writeTerminalOutputUpdate(terminal, outputUpdate);
+    outputCursorRef.current = outputUpdate.cursor;
     terminal.clearSelection();
 
     if (current.error !== null && current.error !== previous.error) {
       writeSystemMessage(terminal, current.error);
     }
 
-    if (previous.version === 0 && autoFocus) {
-      window.requestAnimationFrame(() => {
-        terminal.focus();
-      });
-    }
     previousSessionRef.current = current;
-  }, [autoFocus, terminalBuffer, terminalError, terminalStatus, terminalVersion]);
+  }, [terminalOutput, terminalError, terminalStatus, terminalVersion]);
 
   useEffect(() => {
-    if (!autoFocus) return;
-    const terminal = terminalRef.current;
-    if (!terminal) return;
-    const frame = window.requestAnimationFrame(() => {
-      terminal.focus();
-    });
-    return () => {
-      window.cancelAnimationFrame(frame);
-    };
-  }, [autoFocus, focusRequestId]);
+    if (!autoFocus || !visible) return;
+    // Claim focus when requested, then hand it to the terminal once ready only
+    // if the user has not focused something else in the meantime.
+    (terminalRef.current ?? containerRef.current)?.focus();
+  }, [autoFocus, focusRequestId, visible]);
 
   useEffect(() => {
     const terminal = terminalRef.current;
-    if (!terminal) return;
+    if (!terminal || !visibleRef.current) return;
     const wasAtBottom = terminal.isAtBottom();
     // The surface reports grid changes through onResize, which is the single
     // channel for PTY resize RPCs; fitting here only refreshes the layout.
     const frame = window.requestAnimationFrame(() => {
+      if (!visibleRef.current) return;
       terminal.fit();
       if (wasAtBottom) {
         terminal.scrollToBottom();
@@ -914,6 +980,7 @@ export function TerminalViewport({
   return (
     <div
       ref={containerRef}
+      tabIndex={-1}
       className="relative h-full w-full overflow-hidden bg-[var(--terminal-background)]"
     />
   );
@@ -1477,6 +1544,7 @@ export default function ThreadTerminalDrawer({
                           onAddTerminalContext={onAddTerminalContext}
                           focusRequestId={focusRequestId}
                           autoFocus={terminalId === resolvedActiveTerminalId}
+                          visible={visible}
                           resizeEpoch={resizeEpoch}
                           drawerHeight={drawerHeight}
                           keybindings={keybindings}
@@ -1506,6 +1574,7 @@ export default function ThreadTerminalDrawer({
                   onAddTerminalContext={onAddTerminalContext}
                   focusRequestId={focusRequestId}
                   autoFocus
+                  visible={visible}
                   resizeEpoch={resizeEpoch}
                   drawerHeight={drawerHeight}
                   keybindings={keybindings}
diff --git a/apps/web/src/components/chat/ChangedFilesTree.test.tsx b/apps/web/src/components/chat/ChangedFilesTree.test.tsx
index 4998c40b0c55..899714ed55a1 100644
--- a/apps/web/src/components/chat/ChangedFilesTree.test.tsx
+++ b/apps/web/src/components/chat/ChangedFilesTree.test.tsx
@@ -10,26 +10,21 @@ describe("ChangedFilesCard", () => {
       <ChangedFilesCard
         turnId={TurnId.make("turn-1")}
         files={[{ path: "README.md", kind: "modified", additions: 2, deletions: 1 }]}
-        expanded
-        showCompactPreview={false}
         allDirectoriesExpanded
         resolvedTheme="light"
-        onExpandedChange={() => {}}
         onToggleAllDirectories={() => {}}
         onOpenTurnDiff={() => {}}
       />,
     );
 
-    expect(markup).toContain('data-changed-files-state="expanded"');
-    expect(markup).toContain('aria-expanded="true"');
-    expect(markup).toContain('aria-label="Collapse all folders"');
+    expect(markup).toContain('data-changed-files-state="tree"');
     expect(markup).toContain('aria-label="Open diff"');
     expect(markup).toContain('role="group" aria-label="2 additions, 1 deletions"');
     expect(markup).toContain("1 changed file");
     expect(markup).not.toContain("1 changed files");
   });
 
-  it("renders a scope and representative-file preview for a large latest change", () => {
+  it("shows collapsed folders and root files together", () => {
     const markup = renderToStaticMarkup(
       <ChangedFilesCard
         turnId={TurnId.make("turn-1")}
@@ -44,46 +39,39 @@ describe("ChangedFilesCard", () => {
           },
           { path: "README.md", kind: "modified", additions: 3, deletions: 0 },
         ]}
-        expanded={false}
-        showCompactPreview
         allDirectoriesExpanded={false}
         resolvedTheme="light"
-        onExpandedChange={() => {}}
         onToggleAllDirectories={() => {}}
         onOpenTurnDiff={() => {}}
       />,
     );
 
-    expect(markup).toContain('data-changed-files-state="preview"');
+    expect(markup).toContain('data-changed-files-state="tree"');
     expect(markup).toContain('aria-expanded="false"');
-    expect(markup).toContain("apps");
-    expect(markup).toContain("2 files");
-    expect(markup).toContain("packages");
-    expect(markup).toContain("root");
-    expect(markup).toContain("App.tsx");
-    expect(markup).toContain("git.ts");
+    expect(markup).toContain("apps/web/src");
+    expect(markup).not.toContain("App.tsx");
+    expect(markup).toContain("packages/shared/src");
+    expect(markup).not.toContain("git.ts");
     expect(markup).toContain("README.md");
-    expect(markup).toContain("Show all 4 files");
+    expect(markup).not.toContain("Show all");
     expect(markup).not.toContain("App.test.tsx");
   });
 
-  it("keeps older collapsed changes to a one-line receipt", () => {
+  it("keeps the folder tree visible when folders are collapsed", () => {
     const markup = renderToStaticMarkup(
       <ChangedFilesCard
         turnId={TurnId.make("turn-1")}
         files={[{ path: "apps/web/src/App.tsx", kind: "modified", additions: 120, deletions: 20 }]}
-        expanded={false}
-        showCompactPreview={false}
         allDirectoriesExpanded={false}
         resolvedTheme="light"
-        onExpandedChange={() => {}}
         onToggleAllDirectories={() => {}}
         onOpenTurnDiff={() => {}}
       />,
     );
 
-    expect(markup).toContain('data-changed-files-state="collapsed"');
+    expect(markup).toContain('data-changed-files-state="tree"');
     expect(markup).toContain("1 changed file");
+    expect(markup).toContain("apps/web/src");
     expect(markup).not.toContain("Show all");
     expect(markup).not.toContain("App.tsx");
   });
diff --git a/apps/web/src/components/chat/ChangedFilesTree.tsx b/apps/web/src/components/chat/ChangedFilesTree.tsx
index 906bf4c34cb4..5ac9f09613f3 100644
--- a/apps/web/src/components/chat/ChangedFilesTree.tsx
+++ b/apps/web/src/components/chat/ChangedFilesTree.tsx
@@ -19,99 +19,59 @@ import { DiffStatLabel, hasNonZeroStat } from "./DiffStatLabel";
 import { PierreEntryIcon } from "./PierreEntryIcon";
 import { Button } from "../ui/button";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
-import {
-  changedFileName,
-  selectChangedFilePreview,
-  summarizeChangedFileScopes,
-} from "./changedFilesPresentation";
 
 const EMPTY_DIRECTORY_OVERRIDES: Record<string, boolean> = {};
 
 export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
   turnId: TurnId;
   files: ReadonlyArray<TurnDiffFileChange>;
-  expanded: boolean;
-  showCompactPreview: boolean;
   allDirectoriesExpanded: boolean;
   resolvedTheme: "light" | "dark";
-  onExpandedChange: (expanded: boolean) => void;
   onToggleAllDirectories: () => void;
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
 }) {
   const {
     turnId,
     files,
-    expanded,
-    showCompactPreview,
     allDirectoriesExpanded,
     resolvedTheme,
-    onExpandedChange,
     onToggleAllDirectories,
     onOpenTurnDiff,
   } = props;
   const summaryStat = useMemo(() => summarizeTurnDiffStats(files), [files]);
-  const scopeSummary = useMemo(() => summarizeChangedFileScopes(files), [files]);
-  const previewFiles = useMemo(() => selectChangedFilePreview(files), [files]);
-  const compactPreviewVisible = showCompactPreview && !expanded;
+  const hasDirectories = files.some((file) => /[/\\]/.test(file.path));
 
   return (
     <div
-      className="@container/changed-files mt-4 rounded-2xl border border-border/70 bg-secondary p-2 dark:border-transparent dark:bg-input/32"
-      data-changed-files-state={
-        expanded ? "expanded" : compactPreviewVisible ? "preview" : "collapsed"
-      }
+      className="@container/changed-files mt-4 rounded-lg bg-secondary dark:bg-input/20"
+      data-changed-files-state="tree"
     >
       <div
         data-changed-files-header=""
-        className={cn(
-          "flex items-center justify-between gap-2 rounded-xl",
-          expanded &&
-            "sticky top-2 z-10 mb-2 bg-secondary dark:bg-[color-mix(in_srgb,var(--contrast-foreground)_2.5%,var(--background))]",
-        )}
+        className="sticky top-2 z-10 flex items-center justify-between gap-2 rounded-t-lg bg-secondary px-3 py-2 dark:bg-[color-mix(in_srgb,var(--input)_20%,var(--background))]"
       >
-        <button
-          type="button"
-          aria-expanded={expanded}
-          data-scroll-anchor-ignore
-          className="group flex min-w-0 flex-1 items-center rounded-xl px-2 py-1.5 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-          onClick={() => onExpandedChange(!expanded)}
-        >
-          <span className="flex min-w-0 flex-1 items-center gap-1.5 overflow-hidden">
-            <ChevronRightIcon
-              aria-hidden="true"
-              className={cn(
-                "size-3.5 shrink-0 text-muted-foreground transition-transform",
-                expanded && "rotate-90",
-              )}
-            />
-            <span className="flex shrink-0 items-center gap-1 whitespace-nowrap font-medium text-foreground text-xs leading-4">
-              <span>
-                {files.length} changed file{files.length === 1 ? "" : "s"}
-              </span>
-              {hasNonZeroStat(summaryStat) && (
-                <DiffStatLabel
-                  additions={summaryStat.additions}
-                  className="text-xs leading-4"
-                  deletions={summaryStat.deletions}
-                  layout="inline"
-                />
-              )}
-            </span>
-            <span className="ml-1 hidden min-w-0 flex-1 truncate text-[11px] text-muted-foreground group-hover:text-foreground/80 @[24rem]/changed-files:inline">
-              {expanded ? "Hide files" : "Show files"}
-            </span>
+        <div className="flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1 text-xs font-medium text-foreground">
+          <span>
+            {files.length} changed file{files.length === 1 ? "" : "s"}
           </span>
-        </button>
-        <div className="flex shrink-0 items-center gap-1.5 pr-1">
-          {expanded ? (
+          {hasNonZeroStat(summaryStat) && (
+            <DiffStatLabel
+              additions={summaryStat.additions}
+              deletions={summaryStat.deletions}
+              layout="inline"
+              className="text-xs leading-4"
+            />
+          )}
+        </div>
+        <div className="flex shrink-0 items-center gap-1">
+          {hasDirectories && (
             <Tooltip>
               <TooltipTrigger
                 render={
                   <Button
                     type="button"
                     size="icon-xs"
-                    variant="outline"
-                    className="!size-[22px]"
+                    variant="ghost-muted"
                     aria-label={
                       allDirectoriesExpanded ? "Collapse all folders" : "Expand all folders"
                     }
@@ -130,14 +90,14 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
                 {allDirectoriesExpanded ? "Collapse all folders" : "Expand all folders"}
               </TooltipPopup>
             </Tooltip>
-          ) : null}
+          )}
           <Tooltip>
             <TooltipTrigger
               render={
                 <Button
                   type="button"
                   size="xs"
-                  variant="outline"
+                  variant="ghost-muted"
                   aria-label="Open diff"
                   onClick={() => onOpenTurnDiff(turnId, files[0]?.path)}
                 />
@@ -150,61 +110,14 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
           </Tooltip>
         </div>
       </div>
-      {expanded ? (
-        <ChangedFilesTree
-          key={`changed-files-tree:${turnId}`}
-          turnId={turnId}
-          files={files}
-          allDirectoriesExpanded={allDirectoriesExpanded}
-          resolvedTheme={resolvedTheme}
-          onOpenTurnDiff={onOpenTurnDiff}
-        />
-      ) : compactPreviewVisible ? (
-        <div className="px-2 pb-1.5 pt-1">
-          <p className="flex flex-wrap items-center gap-x-1.5 gap-y-0.5 text-[11px] text-muted-foreground">
-            {scopeSummary.map((scope, index) => (
-              <span key={scope.label} className="inline-flex items-center gap-1">
-                {index > 0 ? <span aria-hidden="true">·</span> : null}
-                <span className="font-mono text-foreground/75">{scope.label}</span>
-                <span>
-                  {scope.fileCount} file{scope.fileCount === 1 ? "" : "s"}
-                </span>
-              </span>
-            ))}
-          </p>
-          <div className="mt-2 flex flex-wrap items-center gap-1.5">
-            {previewFiles.map((file) => (
-              <Tooltip key={file.path}>
-                <TooltipTrigger
-                  render={
-                    <button
-                      type="button"
-                      className="inline-flex max-w-48 items-center gap-1 rounded-md border border-border/70 bg-background/45 px-1.5 py-1 font-mono text-[10px] text-muted-foreground transition-colors hover:bg-accent/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-                      onClick={() => onOpenTurnDiff(turnId, file.path)}
-                    />
-                  }
-                >
-                  <PierreEntryIcon
-                    pathValue={file.path}
-                    kind="file"
-                    theme={resolvedTheme}
-                    className="size-3 shrink-0 text-muted-foreground/70"
-                  />
-                  <span className="truncate">{changedFileName(file.path)}</span>
-                </TooltipTrigger>
-                <TooltipPopup side="top">{file.path}</TooltipPopup>
-              </Tooltip>
-            ))}
-            <button
-              type="button"
-              className="rounded-md px-1.5 py-1 text-[11px] font-medium text-muted-foreground transition-colors hover:bg-accent/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
-              onClick={() => onExpandedChange(true)}
-            >
-              Show all {files.length} files
-            </button>
-          </div>
-        </div>
-      ) : null}
+      <ChangedFilesTree
+        key={`${turnId}:${allDirectoriesExpanded}`}
+        turnId={turnId}
+        files={files}
+        allDirectoriesExpanded={allDirectoriesExpanded}
+        resolvedTheme={resolvedTheme}
+        onOpenTurnDiff={onOpenTurnDiff}
+      />
     </div>
   );
 });
@@ -261,7 +174,8 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
           <button
             type="button"
             data-scroll-anchor-ignore
-            className="group flex w-full items-center gap-1.5 rounded-xl py-1 pr-3 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
+            aria-expanded={isExpanded}
+            className="group flex w-full items-center gap-2 rounded-md py-1.5 pr-2 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
             style={{ paddingLeft: `${leftPadding}px` }}
             onClick={() => toggleDirectory(node.path)}
           >
@@ -287,9 +201,7 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
             )}
           </button>
           {isExpanded && (
-            <div className="space-y-0.5">
-              {node.children.map((childNode) => renderTreeNode(childNode, depth + 1))}
-            </div>
+            <div>{node.children.map((childNode) => renderTreeNode(childNode, depth + 1))}</div>
           )}
         </div>
       );
@@ -299,7 +211,7 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
       <button
         key={`file:${node.path}`}
         type="button"
-        className="group flex w-full items-center gap-1.5 rounded-xl py-1 pr-3 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
+        className="group flex w-full items-center gap-2 rounded-md py-1.5 pr-2 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
         style={{ paddingLeft: `${leftPadding}px` }}
         onClick={() => onOpenTurnDiff(turnId, node.path)}
       >
@@ -312,7 +224,7 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
           theme={resolvedTheme}
           className="size-3.5 text-muted-foreground/70"
         />
-        <span className="truncate font-mono text-[11px] text-muted-foreground/80 group-hover:text-foreground/90">
+        <span className="truncate font-mono text-xs text-foreground/85 group-hover:text-foreground">
           {node.name}
         </span>
         {node.stat && (
@@ -324,7 +236,7 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
     );
   };
 
-  return <div className="space-y-0.5">{treeNodes.map((node) => renderTreeNode(node, 0))}</div>;
+  return <div className="p-2">{treeNodes.map((node) => renderTreeNode(node, 0))}</div>;
 });
 
 function collectDirectoryPaths(nodes: ReadonlyArray<TurnDiffTreeNode>): string[] {
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index 0b034d44338c..10898e311cef 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -88,6 +88,7 @@ import {
 import { ComposerStashBadge } from "./ComposerStashBadge";
 import { ComposerStashMenu } from "./ComposerStashMenu";
 import { useComposerMenuState } from "./useComposerMenuState";
+import { useComposerFocusState } from "./useComposerFocusState";
 import {
   ComposerTasksBadge,
   ComposerTasksContent,
@@ -758,7 +759,7 @@ function ComposerCommandMenuLayer(props: { anchor: HTMLElement | null; children:
 
   return createPortal(
     <div
-      className="pointer-events-auto fixed z-40"
+      className="pointer-events-auto fixed z-40 flex flex-col"
       data-composer-drawer-layer="true"
       style={{
         bottom: position.bottom,
@@ -802,7 +803,12 @@ import {
 } from "../../providerInstances";
 import { type AppModelOption, getAppModelOptionsForInstance } from "../../modelSelection";
 import type { UnifiedSettings } from "@t3tools/contracts/settings";
-import { type SessionPhase, type Thread, videoMimeType } from "../../types";
+import { type ChatMessage, type SessionPhase, type Thread, videoMimeType } from "../../types";
+import {
+  buildComposerPromptHistoryEntries,
+  stepComposerPromptHistory,
+  type ComposerPromptHistoryPosition,
+} from "./composerPromptHistory";
 import type { PendingUserInputDraftAnswer } from "../../pendingUserInput";
 import type { PendingApproval, PendingUserInput } from "../../session-logic";
 import type { ContextWindowSnapshot } from "../../lib/contextWindow";
@@ -1104,7 +1110,7 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
 export interface ChatComposerHandle {
   focusAtEnd: () => void;
   focusAt: (cursor: number) => void;
-  /** Undo only a scroll-triggered collapse when the timeline returns to its live edge. */
+  /** Expand the desktop composer at the timeline end without taking focus. */
   restoreAfterTimelineReachedEnd: () => void;
   addDroppedFiles: (files: File[]) => void;
   insertTextAtEnd: (text: string, options?: { ensureLeadingBoundary?: boolean }) => boolean;
@@ -1171,6 +1177,8 @@ export interface ChatComposerProps {
   activeThreadId: ThreadId | null;
   activeThreadEnvironmentId: EnvironmentId | undefined;
   activeThread: Thread | undefined;
+  /** Timeline messages including optimistic sends, for ArrowUp prompt recall. */
+  promptHistoryMessages: ReadonlyArray<ChatMessage>;
   isServerThread: boolean;
   isLocalDraftThread: boolean;
   forceExpandedOnMobile: boolean;
@@ -1311,6 +1319,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     activeThreadId,
     activeThreadEnvironmentId: _activeThreadEnvironmentId,
     activeThread,
+    promptHistoryMessages,
     isServerThread: _isServerThread,
     isLocalDraftThread: _isLocalDraftThread,
     forceExpandedOnMobile,
@@ -1780,6 +1789,8 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     detectComposerTrigger(prompt, prompt.length),
   );
   const [composerHighlightedItemId, setComposerHighlightedItemId] = useState<string | null>(null);
+  // Active ArrowUp recall. Cleared on edit and on thread switch.
+  const promptHistoryPositionRef = useRef<ComposerPromptHistoryPosition | null>(null);
   const [composerHighlightedSearchKey, setComposerHighlightedSearchKey] = useState<string | null>(
     null,
   );
@@ -1787,8 +1798,14 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
   const [isComposerFooterCompact, setIsComposerFooterCompact] = useState(false);
   const [isComposerPrimaryActionsCompact, setIsComposerPrimaryActionsCompact] = useState(false);
   const [isComposerModelPickerOpen, setIsComposerModelPickerOpen] = useState(false);
-  const [isComposerFocused, setIsComposerFocused] = useState(false);
-  const [isComposerScrollCollapsed, setIsComposerScrollCollapsed] = useState(false);
+  const isMobileViewport = useMediaQuery("max-sm");
+  const {
+    isComposerFocused,
+    setIsComposerFocused,
+    isComposerScrollCollapsed,
+    setIsComposerScrollCollapsed,
+    restoreAfterTimelineReachedEnd,
+  } = useComposerFocusState(isMobileViewport);
   const [composerSubmissionError, setComposerSubmissionError] = useState<string | null>(null);
   const [providerInputSubmissionError, setProviderInputSubmissionError] = useState<string | null>(
     null,
@@ -1800,7 +1817,6 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     key: 0,
     active: false,
   });
-  const isMobileViewport = useMediaQuery("max-sm");
   const { active: panelAnimationsActive, durationMs: panelAnimationDurationMs } =
     usePanelAnimationSettings();
   const isComposerCollapsedMobile =
@@ -2351,7 +2367,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     setComposerTrigger(detectComposerTrigger(promptRef.current, promptRef.current.length));
     setIsDragOverComposer(false);
     setIsComposerScrollCollapsed(false);
-  }, [draftId, activeThreadId, promptRef]);
+  }, [draftId, activeThreadId, promptRef, setIsComposerScrollCollapsed]);
 
   // ------------------------------------------------------------------
   // Footer compact layout observation
@@ -2502,7 +2518,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       COMPOSER_SCROLL_GESTURE_RESET_MS,
     );
     setIsComposerScrollCollapsed(false);
-  }, []);
+  }, [setIsComposerScrollCollapsed]);
 
   const onPromptChange = useCallback(
     (
@@ -2530,6 +2546,12 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       }
       promptRef.current = nextPrompt;
       setPrompt(nextPrompt);
+      // Any edit ends browsing, even one later undone by hand: typing a
+      // character and deleting it leaves the text equal to the recall, and
+      // ArrowDown must move the caret then, not clear the composer.
+      if (promptHistoryPositionRef.current?.recalled !== nextPrompt) {
+        promptHistoryPositionRef.current = null;
+      }
       if (!terminalContextIdListsEqual(composerTerminalContexts, terminalContextIds)) {
         setComposerDraftTerminalContexts(
           composerDraftTarget,
@@ -2789,7 +2811,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       activeElement.blur();
     }
     setIsComposerFocused(false);
-  }, [isMobileViewport]);
+  }, [isMobileViewport, setIsComposerFocused]);
 
   const shouldBlurMobileComposerOnSubmit = useCallback(() => {
     if (!isMobileViewport) return false;
@@ -2949,7 +2971,86 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
         mobileComposerExpandInFlightRef.current = false;
       });
     });
-  }, []);
+  }, [setIsComposerFocused]);
+
+  // ------------------------------------------------------------------
+  // Prompt history (ArrowUp / ArrowDown)
+  // ------------------------------------------------------------------
+  // Entries are built on the keypress, not per render: the timeline changes
+  // on every streamed delta and ArrowUp is rare.
+  const promptHistoryMessagesRef = useRef(promptHistoryMessages);
+  promptHistoryMessagesRef.current = promptHistoryMessages;
+
+  // The composer persists across threads. A recall from thread A must not
+  // be treated as active in thread B, where the text-match fallback could
+  // otherwise turn B's own draft into a browsing position.
+  const promptHistoryTargetKey = composerTargetKey(composerDraftTarget);
+  useEffect(() => {
+    promptHistoryPositionRef.current = null;
+  }, [promptHistoryTargetKey]);
+
+  const replacePromptFromHistory = useCallback(
+    (nextPrompt: string) => {
+      promptRef.current = nextPrompt;
+      setComposerDraftPrompt(composerDraftTarget, nextPrompt);
+      setComposerCursor(collapseExpandedComposerCursor(nextPrompt, nextPrompt.length));
+      setComposerTrigger(null);
+      setComposerHighlightedItemId(null);
+    },
+    [composerDraftTarget, promptRef, setComposerDraftPrompt],
+  );
+
+  const navigatePromptHistory = useCallback(
+    (direction: "backward" | "forward", event: KeyboardEvent): boolean => {
+      if (event.shiftKey || event.altKey || event.metaKey || event.ctrlKey || event.isComposing) {
+        return false;
+      }
+      if (isComposerApprovalState || pendingUserInputs.length > 0) return false;
+      // A composer holding an image, file, picked element, preview
+      // annotation, or review comment is not empty. Recalling text into it
+      // would send the old prompt with the new context, which is never what
+      // ArrowUp meant.
+      if (
+        composerImagesRef.current.length > 0 ||
+        composerFilesRef.current.length > 0 ||
+        composerElementContextsRef.current.length > 0 ||
+        composerPreviewAnnotations.length > 0 ||
+        composerReviewComments.length > 0
+      ) {
+        return false;
+      }
+      // A typed draft with no active recall can never step, so skip the
+      // layout read and the entry build for that common case.
+      if (promptHistoryPositionRef.current === null && promptRef.current.length > 0) {
+        return false;
+      }
+      const editor = composerEditorRef.current;
+      if (!editor?.isCaretOnVisualEdge(direction === "backward" ? "start" : "end")) {
+        return false;
+      }
+      const step = stepComposerPromptHistory({
+        direction,
+        entries: buildComposerPromptHistoryEntries(promptHistoryMessagesRef.current),
+        position: promptHistoryPositionRef.current,
+        currentPrompt: promptRef.current,
+      });
+      if (!step) return false;
+      promptHistoryPositionRef.current = step.position;
+      replacePromptFromHistory(step.prompt);
+      return true;
+    },
+    [
+      composerElementContextsRef,
+      composerFilesRef,
+      composerImagesRef,
+      composerPreviewAnnotations.length,
+      composerReviewComments.length,
+      isComposerApprovalState,
+      pendingUserInputs.length,
+      promptRef,
+      replacePromptFromHistory,
+    ],
+  );
 
   // ------------------------------------------------------------------
   // Callbacks: command key
@@ -2981,6 +3082,9 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
         return true;
       }
     }
+    if (key === "ArrowUp" || key === "ArrowDown") {
+      return navigatePromptHistory(key === "ArrowUp" ? "backward" : "forward", event);
+    }
     const submissionIntent =
       key === "Enter"
         ? composerSubmissionIntentForEnter({
@@ -3336,7 +3440,13 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     const images = [...composerImagesRef.current];
     const files = [...composerFilesRef.current];
     if (prompt.length === 0 && images.length === 0 && files.length === 0) {
-      setIsStashMenuOpen((open) => !open);
+      const entries = usePromptStashStore.getState().entries;
+      const entry = entries.length === 1 ? entries[0] : undefined;
+      if (entry && !entry.pendingImageCount) {
+        await restoreStashEntry(entry);
+      } else {
+        setIsStashMenuOpen((open) => !open);
+      }
       return;
     }
     const stashedFiles: PersistedComposerFileAttachment[] = [];
@@ -3523,6 +3633,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     finalizeStashEntryImages,
     promptRef,
     pulseStashBadge,
+    restoreStashEntry,
     stashEntryToQueue,
   ]);
 
@@ -3680,7 +3791,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     if (!canScrollCollapseComposer) {
       setIsComposerScrollCollapsed(false);
     }
-  }, [canScrollCollapseComposer]);
+  }, [canScrollCollapseComposer, setIsComposerScrollCollapsed]);
 
   // Returning to the window re-fires focus on the element that already held
   // it. That focus arrives after the window's own event, so a window focus
@@ -3769,6 +3880,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     canTrackComposerScrollGesture,
     getTimelineScrollableNode,
     isTimelineAtLogicalEnd,
+    setIsComposerScrollCollapsed,
   ]);
 
   const restingHiddenBlockCount = composerControlsInStrip ? restingControlsHiddenBlockCount : 0;
@@ -4358,7 +4470,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       }
       setIsComposerFocused(false);
     });
-  }, [getTimelineScrollableNode, isMobileViewport]);
+  }, [getTimelineScrollableNode, isMobileViewport, setIsComposerFocused]);
 
   // A held collapse settles when the selection goes away, whether the user
   // clicked elsewhere, pressed Escape, or used the selection toolbar.
@@ -4450,7 +4562,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       }
       desktopOutsidePointerInFlightRef.current = false;
     };
-  }, [isComposerFocused, isMobileViewport, scheduleComposerCollapseCheck]);
+  }, [isComposerFocused, isMobileViewport, scheduleComposerCollapseCheck, setIsComposerFocused]);
 
   useEffect(() => {
     return () => {
@@ -4479,7 +4591,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       setIsComposerFocused(true);
     }
     setIsComposerModelPickerOpen(true);
-  }, [composerControlsHidden]);
+  }, [composerControlsHidden, setIsComposerFocused, setIsComposerScrollCollapsed]);
 
   useImperativeHandle(
     composerRef,
@@ -4490,9 +4602,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       focusAt: (cursor: number) => {
         composerEditorRef.current?.focusAt(cursor);
       },
-      restoreAfterTimelineReachedEnd: () => {
-        setIsComposerScrollCollapsed(false);
-      },
+      restoreAfterTimelineReachedEnd,
       addDroppedFiles: (files: File[]) => {
         void addComposerAttachments(files);
         focusComposer();
@@ -4636,6 +4746,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       interactionMode,
       planModeUiEnabled,
       compactThreadContext,
+      restoreAfterTimelineReachedEnd,
     ],
   );
 
diff --git a/apps/web/src/components/chat/ChatHeader.tsx b/apps/web/src/components/chat/ChatHeader.tsx
index 1dcf9887704c..98b661bf5ff6 100644
--- a/apps/web/src/components/chat/ChatHeader.tsx
+++ b/apps/web/src/components/chat/ChatHeader.tsx
@@ -35,6 +35,7 @@ import { useRemoteOpenState, type RemoteOpenMode } from "../../remoteOpen";
 import { usePrimaryEnvironmentId } from "../../state/environments";
 import { useT3ProjectFileScripts } from "~/hooks/useT3ProjectFileScripts";
 import { useThreadActionMenu } from "~/hooks/useThreadActionMenu";
+import { readLocalApi } from "~/localApi";
 import { threadEnvironment } from "../../state/threads";
 import { useAtomCommand } from "../../state/use-atom-command";
 import { observeResponsiveBreakpointFade, usePanelAnimationSettings } from "../../panelAnimations";
@@ -66,6 +67,7 @@ interface ChatHeaderProps {
   gitCwd: string | null;
   readonly onOpenPullRequest?: ((number: number) => void) | undefined;
   onNewThreadInProject: () => void;
+  onOpenProjectSettings?: (() => void) | undefined;
   onRunProjectScript: (script: ProjectScript) => void;
   onAddProjectScript: (input: NewProjectScriptInput) => Promise<ProjectScriptActionResult>;
   onUpdateProjectScript: (
@@ -137,6 +139,7 @@ export const ChatHeader = memo(function ChatHeader({
   gitCwd,
   onOpenPullRequest,
   onNewThreadInProject,
+  onOpenProjectSettings,
   onRunProjectScript,
   onAddProjectScript,
   onUpdateProjectScript,
@@ -275,15 +278,29 @@ export const ChatHeader = memo(function ChatHeader({
   );
   const handleHeaderContextMenu = useCallback(
     (event: ReactMouseEvent) => {
-      if (!isServerThread || renamingTitle !== null) return;
+      if (renamingTitle !== null) return;
       // The right-side controls (git, scripts, open-in) keep their own
       // behavior; only the breadcrumb area opens the thread menu.
       if ((event.target as HTMLElement).closest("[data-chat-header-actions]")) return;
+      if (!isServerThread && onOpenProjectSettings === undefined) return;
       cancelPendingTitleMenu();
       event.preventDefault();
+      if (!isServerThread) {
+        const api = readLocalApi();
+        if (!api) return;
+        void api.contextMenu
+          .show([{ id: "project-settings", label: "Project settings", icon: "settings" }], {
+            x: event.clientX,
+            y: event.clientY,
+          })
+          .then((action) => {
+            if (action === "project-settings") onOpenProjectSettings?.();
+          });
+        return;
+      }
       openMenu({ x: event.clientX, y: event.clientY });
     },
-    [cancelPendingTitleMenu, isServerThread, openMenu, renamingTitle],
+    [cancelPendingTitleMenu, isServerThread, onOpenProjectSettings, openMenu, renamingTitle],
   );
   const handleRenameKeyDown = useCallback(
     (event: ReactKeyboardEvent<HTMLInputElement>) => {
diff --git a/apps/web/src/components/chat/ComposerActivityStatus.tsx b/apps/web/src/components/chat/ComposerActivityStatus.tsx
index 49d4bece350d..d9e459bcf9ee 100644
--- a/apps/web/src/components/chat/ComposerActivityStatus.tsx
+++ b/apps/web/src/components/chat/ComposerActivityStatus.tsx
@@ -1,12 +1,13 @@
 import { LoaderCircleIcon } from "lucide-react";
+import { observeVisibleAnimation } from "../../lib/visibleAnimation";
 import { threadSyncLabel, type ThreadSyncPhase } from "../../threadSync";
 import { ComposerBanner } from "./ComposerBanner";
 
 export function ComposerActivityRow({ phase }: { readonly phase: ThreadSyncPhase }) {
   return (
     <ComposerBanner.Row>
-      <ComposerBanner.Icon>
-        <LoaderCircleIcon className="motion-safe:animate-spin" />
+      <ComposerBanner.Icon ref={observeVisibleAnimation}>
+        <LoaderCircleIcon className="motion-safe:visible-animate-spin" />
       </ComposerBanner.Icon>
       <ComposerBanner.Content>
         <span
diff --git a/apps/web/src/components/chat/ComposerBanner.tsx b/apps/web/src/components/chat/ComposerBanner.tsx
index 90da8940d498..092baa0ec8af 100644
--- a/apps/web/src/components/chat/ComposerBanner.tsx
+++ b/apps/web/src/components/chat/ComposerBanner.tsx
@@ -178,7 +178,7 @@ function Row({
   layout = "inline",
   ...props
 }: useRender.ComponentProps<"div"> & {
-  layout?: "inline" | "wrap-actions";
+  layout?: "inline" | "wrap-actions" | "wrap-actions-narrow";
 }) {
   const rowProps = {
     className: cn(
@@ -187,6 +187,8 @@ function Row({
       "[&:is(button)]:cursor-pointer [&:is(button)]:rounded-[0.5rem] [&:is(button)]:focus-visible:outline-2 [&:is(button)]:focus-visible:-outline-offset-2 [&:is(button)]:focus-visible:outline-ring",
       layout === "wrap-actions" &&
         "@max-[400px]:*:data-[slot=composer-banner-content]:min-h-(--composer-banner-icon-column)",
+      layout === "wrap-actions-narrow" &&
+        "@max-[320px]:*:data-[slot=composer-banner-content]:min-h-(--composer-banner-icon-column)",
       className,
     ),
     "data-composer-banner-row": "true",
@@ -247,6 +249,7 @@ function Actions({ className, ...props }: ComponentProps<"span">) {
       className={cn(
         "col-start-3 row-start-1 flex flex-wrap items-center justify-end gap-1",
         "@max-[400px]:group-data-[composer-banner-layout=wrap-actions]/banner-row:has-[>:nth-child(2)]:col-start-2 @max-[400px]:group-data-[composer-banner-layout=wrap-actions]/banner-row:has-[>:nth-child(2)]:col-end-4 @max-[400px]:group-data-[composer-banner-layout=wrap-actions]/banner-row:has-[>:nth-child(2)]:row-start-2 @max-[400px]:group-data-[composer-banner-layout=wrap-actions]/banner-row:has-[>:nth-child(2)]:-ms-2 @max-[400px]:group-data-[composer-banner-layout=wrap-actions]/banner-row:has-[>:nth-child(2)]:justify-start",
+        "@max-[320px]:group-data-[composer-banner-layout=wrap-actions-narrow]/banner-row:has-[>:nth-child(2)]:col-start-2 @max-[320px]:group-data-[composer-banner-layout=wrap-actions-narrow]/banner-row:has-[>:nth-child(2)]:col-end-4 @max-[320px]:group-data-[composer-banner-layout=wrap-actions-narrow]/banner-row:has-[>:nth-child(2)]:row-start-2 @max-[320px]:group-data-[composer-banner-layout=wrap-actions-narrow]/banner-row:has-[>:nth-child(2)]:-ms-2 @max-[320px]:group-data-[composer-banner-layout=wrap-actions-narrow]/banner-row:has-[>:nth-child(2)]:justify-start",
         className,
       )}
       {...props}
diff --git a/apps/web/src/components/chat/ComposerBannerStack.tsx b/apps/web/src/components/chat/ComposerBannerStack.tsx
index fee545a4d1ba..5de40a0d90d5 100644
--- a/apps/web/src/components/chat/ComposerBannerStack.tsx
+++ b/apps/web/src/components/chat/ComposerBannerStack.tsx
@@ -269,7 +269,7 @@ function ComposerBannerStackAlert({
       variant={item.variant}
       density="comfortable"
     >
-      <ComposerBanner.Row layout="wrap-actions">
+      <ComposerBanner.Row layout="wrap-actions-narrow">
         <ComposerBanner.Icon className="h-(--composer-banner-icon-column) self-start">
           {item.icon}
         </ComposerBanner.Icon>
diff --git a/apps/web/src/components/chat/ComposerCommandMenu.tsx b/apps/web/src/components/chat/ComposerCommandMenu.tsx
index 74cd98f361bc..8e940969e72d 100644
--- a/apps/web/src/components/chat/ComposerCommandMenu.tsx
+++ b/apps/web/src/components/chat/ComposerCommandMenu.tsx
@@ -91,11 +91,11 @@ export const ComposerCommandMenu = memo(function ComposerCommandMenu(props: {
     >
       <ComposerBanner.Surface
         ref={listRef}
-        className="w-full overflow-hidden pb-(--chat-composer-attachment-overlap) **:data-[slot=scroll-area-scrollbar]:data-[orientation=vertical]:my-4"
+        className="flex min-h-0 w-full flex-col overflow-hidden pb-(--chat-composer-attachment-overlap) **:data-[slot=scroll-area-scrollbar]:data-[orientation=vertical]:my-4"
         data-composer-command-drawer="true"
       >
         {props.items.length > 0 ? (
-          <CommandList className="max-h-72 scroll-pb-6">
+          <CommandList className="max-h-72 min-h-0 scroll-pb-6">
             <CommandGroup>
               {props.items.map((item) => (
                 <ComposerCommandMenuItem
diff --git a/apps/web/src/components/chat/ComposerControl.test.tsx b/apps/web/src/components/chat/ComposerControl.test.tsx
deleted file mode 100644
index 397578179b9f..000000000000
--- a/apps/web/src/components/chat/ComposerControl.test.tsx
+++ /dev/null
@@ -1,76 +0,0 @@
-import { renderToStaticMarkup } from "react-dom/server";
-import { BotIcon } from "lucide-react";
-import { describe, expect, it } from "vite-plus/test";
-
-import {
-  ComposerControl,
-  ComposerControlChevron,
-  ComposerControlIcon,
-  ComposerControlSeparator,
-} from "./ComposerControl";
-
-describe("ComposerControl", () => {
-  it("preserves the expanded composer geometry by default", () => {
-    const markup = renderToStaticMarkup(<ComposerControl>Model</ComposerControl>);
-
-    expect(markup).toContain("h-7");
-    expect(markup).toContain("min-h-7");
-    expect(markup).toContain("gap-1.5");
-    expect(markup).toContain("px-2.5");
-  });
-
-  it("uses the shared xs geometry for resting controls", () => {
-    const markup = renderToStaticMarkup(
-      <ComposerControl size="xs">
-        Model
-        <ComposerControlChevron size="xs" />
-      </ComposerControl>,
-    );
-
-    expect(markup).toContain("sm:h-6");
-    expect(markup).toContain("font-normal");
-    expect(markup).toContain("text-muted-foreground/70");
-    expect(markup).toContain("[--control-icon-color:currentColor]");
-    expect(markup).toContain("svg[data-composer-control-chevron]]:ms-0");
-    expect(markup).toContain("svg[data-composer-control-chevron]]:-me-1");
-    expect(markup).not.toContain("min-h-7");
-    expect(markup).not.toContain("gap-1.5");
-    expect(markup).not.toContain("px-2.5");
-  });
-
-  it("keeps the expanded chevron treatment unless resting overrides it", () => {
-    const expanded = renderToStaticMarkup(<ComposerControlChevron />);
-    const resting = renderToStaticMarkup(<ComposerControlChevron size="xs" />);
-
-    expect(expanded).toContain("size-3.5");
-    expect(expanded).toContain("text-icon-muted");
-    expect(expanded).toContain('stroke-width="2.25"');
-    expect(resting).toContain("size-3");
-    expect(resting).toContain("text-current");
-    expect(resting).toContain("opacity-50");
-    expect(resting).not.toContain("size-3.5");
-    expect(resting).not.toContain("text-icon-muted");
-  });
-
-  it("owns resting icon geometry", () => {
-    const expanded = renderToStaticMarkup(<ComposerControlIcon icon={BotIcon} />);
-    const resting = renderToStaticMarkup(<ComposerControlIcon icon={BotIcon} size="xs" />);
-
-    expect(expanded).toContain("size-4");
-    expect(resting).toContain("size-3");
-    expect(resting).not.toContain("size-4");
-  });
-
-  it("owns separator geometry for both composer sizes", () => {
-    const expanded = renderToStaticMarkup(<ComposerControlSeparator />);
-    const resting = renderToStaticMarkup(
-      <ComposerControlSeparator size="xs" data-resting-controls-separator="true" />,
-    );
-
-    expect(expanded).toContain("h-4");
-    expect(expanded).not.toContain("h-3.5!");
-    expect(resting).toContain("h-3.5!");
-    expect(resting).not.toContain("h-4");
-    expect(resting).toContain('data-resting-controls-separator="true"');
-  });
-});
diff --git a/apps/web/src/components/chat/ComposerPrimaryActions.test.tsx b/apps/web/src/components/chat/ComposerPrimaryActions.test.tsx
index 92f24c833db8..45ef93568cf6 100644
--- a/apps/web/src/components/chat/ComposerPrimaryActions.test.tsx
+++ b/apps/web/src/components/chat/ComposerPrimaryActions.test.tsx
@@ -15,7 +15,7 @@ vi.mock("../SidebarStageBackdrop", () => ({
   useSidebarStageBackdropVariant: (enabled = true) => (enabled ? stageArtworkState.variant : null),
 }));
 
-import { ComposerPrimaryActions, formatPendingPrimaryActionLabel } from "./ComposerPrimaryActions";
+import { ComposerPrimaryActions } from "./ComposerPrimaryActions";
 
 function renderPendingActions(isRunning: boolean) {
   return renderToStaticMarkup(
@@ -92,96 +92,6 @@ afterEach(() => {
   stageArtworkState.variant = null;
 });
 
-describe("formatPendingPrimaryActionLabel", () => {
-  it("returns 'Submitting...' while responding", () => {
-    expect(
-      formatPendingPrimaryActionLabel({
-        compact: false,
-        isLastQuestion: false,
-        isResponding: true,
-        questionIndex: 0,
-      }),
-    ).toBe("Submitting...");
-  });
-
-  it("returns 'Submitting...' while responding regardless of other flags", () => {
-    expect(
-      formatPendingPrimaryActionLabel({
-        compact: true,
-        isLastQuestion: true,
-        isResponding: true,
-        questionIndex: 3,
-      }),
-    ).toBe("Submitting...");
-  });
-
-  it("returns 'Submit' in compact mode on the last question", () => {
-    expect(
-      formatPendingPrimaryActionLabel({
-        compact: true,
-        isLastQuestion: true,
-        isResponding: false,
-        questionIndex: 0,
-      }),
-    ).toBe("Submit");
-  });
-
-  it("returns 'Next' in compact mode when not the last question", () => {
-    expect(
-      formatPendingPrimaryActionLabel({
-        compact: true,
-        isLastQuestion: false,
-        isResponding: false,
-        questionIndex: 1,
-      }),
-    ).toBe("Next");
-  });
-
-  it("returns 'Next question' when not the last question", () => {
-    expect(
-      formatPendingPrimaryActionLabel({
-        compact: false,
-        isLastQuestion: false,
-        isResponding: false,
-        questionIndex: 0,
-      }),
-    ).toBe("Next question");
-  });
-
-  it("returns singular 'Submit answer' on the last question when it is the only question", () => {
-    expect(
-      formatPendingPrimaryActionLabel({
-        compact: false,
-        isLastQuestion: true,
-        isResponding: false,
-        questionIndex: 0,
-      }),
-    ).toBe("Submit answer");
-  });
-
-  it("returns plural 'Submit answers' on the last question when there are multiple questions", () => {
-    expect(
-      formatPendingPrimaryActionLabel({
-        compact: false,
-        isLastQuestion: true,
-        isResponding: false,
-        questionIndex: 1,
-      }),
-    ).toBe("Submit answers");
-  });
-
-  it("returns plural 'Submit answers' for higher question indices", () => {
-    expect(
-      formatPendingPrimaryActionLabel({
-        compact: false,
-        isLastQuestion: true,
-        isResponding: false,
-        questionIndex: 5,
-      }),
-    ).toBe("Submit answers");
-  });
-});
-
 describe("ComposerPrimaryActions", () => {
   it("disables and labels the send button while feedback is uploading", () => {
     const markup = renderSendButton("Sending feedback");
diff --git a/apps/web/src/components/chat/ComposerPrimaryActions.tsx b/apps/web/src/components/chat/ComposerPrimaryActions.tsx
index 46323aa2b09a..91c54b75ed03 100644
--- a/apps/web/src/components/chat/ComposerPrimaryActions.tsx
+++ b/apps/web/src/components/chat/ComposerPrimaryActions.tsx
@@ -37,7 +37,7 @@ interface ComposerPrimaryActionsProps {
   onImplementPlanInNewThread: () => void;
 }
 
-export const formatPendingPrimaryActionLabel = (input: {
+const formatPendingPrimaryActionLabel = (input: {
   compact: boolean;
   isLastQuestion: boolean;
   isResponding: boolean;
diff --git a/apps/web/src/components/chat/ComposerServerUpdateStatus.tsx b/apps/web/src/components/chat/ComposerServerUpdateStatus.tsx
index 4c337c3b3704..4c5aa60ff06a 100644
--- a/apps/web/src/components/chat/ComposerServerUpdateStatus.tsx
+++ b/apps/web/src/components/chat/ComposerServerUpdateStatus.tsx
@@ -1,7 +1,8 @@
 import type { ServerUpdateState } from "@t3tools/client-runtime/state/server";
-import { CircleAlertIcon, InfoIcon, LoaderCircleIcon } from "lucide-react";
+import { CircleAlertIcon, DownloadIcon, LoaderCircleIcon } from "lucide-react";
 import { useId, useState } from "react";
 
+import { observeVisibleAnimation } from "../../lib/visibleAnimation";
 import { serverUpdateStageLabel } from "../ServerUpdateAction";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { ComposerBanner } from "./ComposerBanner";
@@ -12,12 +13,18 @@ export function ComposerServerUpdateIcon({
   readonly status: ServerUpdateState["status"];
 }) {
   if (status === "running") {
-    return <LoaderCircleIcon aria-hidden className="motion-safe:animate-spin" />;
+    return (
+      <LoaderCircleIcon
+        aria-hidden
+        ref={observeVisibleAnimation}
+        className="motion-safe:visible-animate-spin"
+      />
+    );
   }
   if (status === "failed") {
     return <CircleAlertIcon aria-hidden className="text-error" />;
   }
-  return <InfoIcon aria-hidden />;
+  return <DownloadIcon aria-hidden />;
 }
 
 /** One text line, clipped at the end so the error detail never squeezes its title. */
diff --git a/apps/web/src/components/chat/ComposerStashMenu.tsx b/apps/web/src/components/chat/ComposerStashMenu.tsx
index 69032764c1f4..4942b21dd600 100644
--- a/apps/web/src/components/chat/ComposerStashMenu.tsx
+++ b/apps/web/src/components/chat/ComposerStashMenu.tsx
@@ -30,10 +30,10 @@ function stashEntrySnippet(entry: PromptStashEntry): string {
 }
 
 /**
- * Attached banner listing the stashed prompts. Keyboard-first: opened by ⌘S on an
- * empty composer, navigated with arrows, restored with Enter, dismissed
- * with Escape. The listener runs capture-phase on window so it wins over
- * the Lexical editor's handlers while the menu is open.
+ * Attached banner listing the stashed prompts. Opened by the stash badge or ⌘S
+ * when the empty composer cannot restore a single entry. Navigated with arrows,
+ * restored with Enter, dismissed with Escape. The listener runs capture-phase
+ * on window so it wins over the Lexical editor's handlers while the menu is open.
  */
 export const ComposerStashMenu = memo(function ComposerStashMenu(props: {
   entries: ReadonlyArray<PromptStashEntry>;
diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.test.ts b/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
index 6e5cf29c2914..5d310c5fe345 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.test.ts
@@ -1,9 +1,10 @@
 import { describe, expect, it } from "vite-plus/test";
-import { MessageId, TurnId } from "@t3tools/contracts";
+import { CheckpointRef, MessageId, TurnId } from "@t3tools/contracts";
 import {
   computeStableMessagesTimelineRows,
   computeMessageDurationStart,
   deriveMessagesTimelineRows,
+  deriveMessagesTimelineRowsWithState,
   liveWorkEntryLabel,
   normalizeCompactToolLabel,
   resolveAssistantMessageCopyState,
@@ -13,6 +14,402 @@ import {
   type MessagesTimelineRow,
   workEntryDisplayLabel,
 } from "./MessagesTimeline.logic";
+import {
+  createMessageAttachmentPreviewProjector,
+  deriveTimelineEntries,
+  deriveTimelineEntriesWithState,
+  type WorkLogEntry,
+} from "../../session-logic";
+import { buildRevertTurnCountByUserMessageId } from "../ChatView.logic";
+import { isImageAttachment, type ChatMessage, type TurnDiffSummary } from "../../types";
+
+describe("streaming row projection", () => {
+  function fixture(text = "") {
+    const turnId = TurnId.make("live-turn");
+    const historyTurnId = TurnId.make("history-turn");
+    const time = (second: number) => new Date(Date.UTC(2026, 8, 4, 0, 0, second)).toISOString();
+    const messages: ChatMessage[] = [
+      {
+        id: MessageId.make("history-user"),
+        role: "user",
+        text: "Inspect",
+        turnId: null,
+        createdAt: time(0),
+        updatedAt: time(0),
+        streaming: false,
+      },
+      {
+        id: MessageId.make("history-assistant"),
+        role: "assistant",
+        text: "Done",
+        turnId: historyTurnId,
+        createdAt: time(3),
+        updatedAt: time(4),
+        streaming: false,
+      },
+      {
+        id: MessageId.make("live-user"),
+        role: "user",
+        text: "Continue",
+        turnId: null,
+        createdAt: time(5),
+        updatedAt: time(5),
+        streaming: false,
+      },
+      {
+        id: MessageId.make("live-assistant"),
+        role: "assistant",
+        text,
+        turnId,
+        createdAt: time(7),
+        updatedAt: time(7),
+        streaming: true,
+      },
+    ];
+    const work: WorkLogEntry[] = [
+      {
+        id: "history-work",
+        turnId: historyTurnId,
+        createdAt: time(1),
+        label: "Ran command",
+        tone: "tool",
+        command: "vp test",
+        toolCallId: "history-tool",
+        toolLifecycleStatus: "failed",
+        sourceActivityKind: "tool.completed",
+      },
+      {
+        id: "live-work",
+        turnId,
+        createdAt: time(6),
+        label: "Read file",
+        tone: "tool",
+        changedFiles: ["/repo/src/index.ts"],
+        toolCallId: "live-tool",
+        toolLifecycleStatus: "completed",
+        sourceActivityKind: "tool.completed",
+      },
+    ];
+    const timeline = deriveTimelineEntriesWithState(messages, [], work);
+    const input = {
+      timelineEntries: timeline.entries,
+      latestTurn: { turnId, state: "running", startedAt: time(5), completedAt: null },
+      runningTurnId: turnId,
+      isWorking: true,
+      activeTurnStartedAt: time(5),
+      turnDiffSummaryByAssistantMessageId: new Map<MessageId, TurnDiffSummary>(),
+      revertTurnCountByUserMessageId: new Map<MessageId, number>(),
+    } satisfies Parameters<typeof deriveMessagesTimelineRows>[0];
+    return { messages, work, timeline, input, time, turnId, historyTurnId };
+  }
+
+  it.each([
+    ["", "Now visible"],
+    [" \n", "Now visible"],
+    ["Visible", ""],
+    ["", " \t\n"],
+    ["Visible", "★ Insight\nKeep these line breaks"],
+  ])("keeps row parity and history identity when text changes from %j to %j", (before, after) => {
+    const initial = fixture(before);
+    const previous = deriveMessagesTimelineRowsWithState(initial.input);
+    Object.freeze(previous.rows);
+    for (const row of previous.rows) Object.freeze(row);
+    const last = initial.messages.at(-1)!;
+    const messages = [
+      ...initial.messages.slice(0, -1),
+      { ...last, text: after, updatedAt: initial.time(8) },
+    ];
+    const timeline = deriveTimelineEntriesWithState(messages, [], initial.work, initial.timeline);
+    const input = { ...initial.input, timelineEntries: timeline.entries };
+    const next = deriveMessagesTimelineRowsWithState(input, previous);
+
+    expect(next.rows).toEqual(
+      deriveMessagesTimelineRows({
+        ...input,
+        timelineEntries: deriveTimelineEntries(messages, [], initial.work),
+      }),
+    );
+    for (const [index, row] of previous.rows.entries()) {
+      if ((row.kind === "message" || row.kind === "assistant-meta") && row.message === last) {
+        expect(next.rows[index]).toMatchObject({ message: { text: after } });
+        expect(row.message.text).toBe(before);
+      } else {
+        expect(next.rows[index]).toBe(row);
+      }
+    }
+  });
+
+  it("keeps earlier emitted rows unchanged across two projection branches", () => {
+    const initial = fixture();
+    const previous = deriveMessagesTimelineRowsWithState(initial.input);
+    const last = initial.messages.at(-1)!;
+    const branch = (text: string) => {
+      const messages = [...initial.messages.slice(0, -1), { ...last, text }];
+      const timeline = deriveTimelineEntriesWithState(messages, [], initial.work, initial.timeline);
+      const input = { ...initial.input, timelineEntries: timeline.entries };
+      const projection = deriveMessagesTimelineRowsWithState(input, previous);
+      expect(projection.rows).toEqual(deriveMessagesTimelineRows(input));
+      return projection;
+    };
+    const first = branch("First branch");
+    const savedFirst = structuredClone(first.rows);
+    branch("Second branch");
+    expect(first.rows).toEqual(savedFirst);
+    expect(previous.rows).toEqual(deriveMessagesTimelineRows(initial.input));
+  });
+
+  it.each(["file", "image", "handoff", "streaming-image"] as const)(
+    "preserves stream reuse through the real %s preview materializer",
+    (kind) => {
+      const initial = fixture("Partial");
+      const image = {
+        type: "image" as const,
+        id: "image",
+        name: "image.png",
+        mimeType: "image/png",
+        sizeBytes: 42,
+      };
+      const file = {
+        type: "file" as const,
+        id: "file",
+        name: "file.txt",
+        mimeType: "text/plain",
+        sizeBytes: 8,
+      };
+      const source = initial.messages.map((message, index) =>
+        index === 0 || (kind === "streaming-image" && index === initial.messages.length - 1)
+          ? { ...message, attachments: kind === "file" ? [file] : [image, file] }
+          : message,
+      );
+      const server = createMessageAttachmentPreviewProjector();
+      const handoff = createMessageAttachmentPreviewProjector();
+      const materialize = (messages: ReadonlyArray<ChatMessage>, url: string) => {
+        const urls = new Map(kind === "handoff" ? [] : [[image.id, url]]);
+        return messages.map((message) => {
+          const displayed = server(message, (attachment) => urls.get(attachment.id));
+          return kind === "handoff" && message.role === "user"
+            ? handoff(displayed, (attachment) =>
+                isImageAttachment(attachment) ? "blob:handoff" : undefined,
+              )
+            : displayed;
+        });
+      };
+      const firstMessages = materialize(source, "https://first.test/image");
+      const firstTimeline = deriveTimelineEntriesWithState(firstMessages, [], initial.work);
+      const input = { ...initial.input, timelineEntries: firstTimeline.entries };
+      const previous = deriveMessagesTimelineRowsWithState(input);
+      const saved = structuredClone(previous.rows);
+      const nextSource = [...source.slice(0, -1), { ...source.at(-1)!, text: "Next token" }];
+      const nextMessages = materialize(nextSource, "https://first.test/image");
+      const nextTimeline = deriveTimelineEntriesWithState(
+        nextMessages,
+        [],
+        initial.work,
+        firstTimeline,
+      );
+      const nextInput = { ...input, timelineEntries: nextTimeline.entries };
+      const next = deriveMessagesTimelineRowsWithState(nextInput, previous);
+
+      expect(nextMessages[0]).toBe(firstMessages[0]);
+      expect(next.rows).toEqual(deriveMessagesTimelineRows(nextInput));
+      for (const [index, row] of previous.rows.entries()) {
+        if (
+          (row.kind === "message" || row.kind === "assistant-meta") &&
+          row.message.id === source.at(-1)?.id
+        )
+          continue;
+        expect(next.rows[index]).toBe(row);
+      }
+      expect(previous.rows).toEqual(saved);
+
+      if (kind === "image" || kind === "streaming-image") {
+        const renewed = materialize(nextSource, "https://renewed.test/image");
+        const renewedTimeline = deriveTimelineEntriesWithState(
+          renewed,
+          [],
+          initial.work,
+          nextTimeline,
+        );
+        const renewedInput = { ...input, timelineEntries: renewedTimeline.entries };
+        const renewedRows = deriveMessagesTimelineRowsWithState(renewedInput, next);
+        expect(renewedRows.rows).toEqual(deriveMessagesTimelineRows(renewedInput));
+        expect(renewed[0]?.attachments?.[0]).toMatchObject({
+          previewUrl: "https://renewed.test/image",
+        });
+        expect(firstMessages[0]?.attachments?.[0]).toMatchObject({
+          previewUrl: "https://first.test/image",
+        });
+      }
+    },
+  );
+
+  it("reuses rows when the revert map is rebuilt from the streamed entries", () => {
+    const initial = fixture("Partial");
+    const inferredCheckpointTurnCountByTurnId = { [initial.historyTurnId]: 1 };
+    const turnDiffSummaryByAssistantMessageId = new Map<MessageId, TurnDiffSummary>([
+      [
+        MessageId.make("history-assistant"),
+        {
+          turnId: initial.historyTurnId,
+          checkpointTurnCount: 1,
+          checkpointRef: CheckpointRef.make("refs/t3/checkpoints/history-turn"),
+          status: "ready",
+          files: [],
+          assistantMessageId: MessageId.make("history-assistant"),
+          completedAt: initial.time(4),
+        },
+      ],
+    ]);
+    let revertMap: Map<MessageId, number> | null = null;
+    // Mirrors ChatView: the map is derived from each delta's entries.
+    const build = (timelineEntries: typeof initial.timeline.entries) => {
+      revertMap = buildRevertTurnCountByUserMessageId(
+        {
+          supportsConversationRollback: true,
+          timelineEntries,
+          turnDiffSummaryByAssistantMessageId,
+          inferredCheckpointTurnCountByTurnId,
+        },
+        revertMap,
+      );
+      return {
+        ...initial.input,
+        timelineEntries,
+        turnDiffSummaryByAssistantMessageId,
+        revertTurnCountByUserMessageId: revertMap,
+      };
+    };
+    const previous = deriveMessagesTimelineRowsWithState(build(initial.timeline.entries));
+    expect(previous.rows.some((row) => row.kind === "message" && row.revertTurnCount === 0)).toBe(
+      true,
+    );
+    const last = initial.messages.at(-1)!;
+    const messages = [...initial.messages.slice(0, -1), { ...last, text: "Partial token" }];
+    const timeline = deriveTimelineEntriesWithState(messages, [], initial.work, initial.timeline);
+    const next = deriveMessagesTimelineRowsWithState(build(timeline.entries), previous);
+
+    expect(next.rows).toEqual(deriveMessagesTimelineRows(build(timeline.entries)));
+    for (const [index, row] of previous.rows.entries()) {
+      if ((row.kind === "message" || row.kind === "assistant-meta") && row.message === last) {
+        expect(next.rows[index]).toMatchObject({ message: { text: "Partial token" } });
+      } else {
+        expect(next.rows[index]).toBe(row);
+      }
+    }
+  });
+
+  it.each(["completion", "turn", "role", "ordering"] as const)(
+    "rebuilds row structure for a %s change with otherwise unchanged controls",
+    (change) => {
+      const initial = fixture("Partial");
+      const input = {
+        ...initial.input,
+        latestTurn: {
+          ...initial.input.latestTurn,
+          state: "completed" as const,
+          completedAt: initial.time(9),
+        },
+        runningTurnId: null,
+        isWorking: false,
+      };
+      const previous = deriveMessagesTimelineRowsWithState(input);
+      const last = initial.messages.at(-1)!;
+      const changed: ChatMessage =
+        change === "completion"
+          ? { ...last, streaming: false, updatedAt: initial.time(10) }
+          : change === "turn"
+            ? { ...last, turnId: initial.historyTurnId }
+            : change === "role"
+              ? { ...last, role: "user", turnId: null }
+              : { ...last, createdAt: initial.time(0) };
+      const messages = [...initial.messages.slice(0, -1), changed];
+      const timeline = deriveTimelineEntriesWithState(messages, [], initial.work, initial.timeline);
+      const nextInput = { ...input, timelineEntries: timeline.entries };
+      const next = deriveMessagesTimelineRowsWithState(nextInput, previous);
+      expect(next.rows).toEqual(
+        deriveMessagesTimelineRows({
+          ...nextInput,
+          timelineEntries: deriveTimelineEntries(messages, [], initial.work),
+        }),
+      );
+      expect(previous.rows).toEqual(deriveMessagesTimelineRows(input));
+    },
+  );
+
+  it("keeps full parity through completion, trailing failure, metadata, expansion, and paging", () => {
+    const initial = fixture("Partial");
+    let timeline = initial.timeline;
+    let input: Parameters<typeof deriveMessagesTimelineRows>[0] = initial.input;
+    let projection = deriveMessagesTimelineRowsWithState(input);
+    let messages = initial.messages;
+    let work = initial.work;
+    const check = (changes: Partial<typeof input> = {}) => {
+      const oldRows = structuredClone(projection.rows);
+      const previous = projection;
+      timeline = deriveTimelineEntriesWithState(messages, [], work, timeline);
+      input = { ...input, ...changes, timelineEntries: timeline.entries };
+      projection = deriveMessagesTimelineRowsWithState(input, previous);
+      expect(projection.rows).toEqual(
+        deriveMessagesTimelineRows({
+          ...input,
+          timelineEntries: deriveTimelineEntries(messages, [], work),
+        }),
+      );
+      expect(previous.rows).toEqual(oldRows);
+    };
+
+    messages = [
+      ...messages.slice(0, -1),
+      { ...messages.at(-1)!, streaming: false, text: "Complete", updatedAt: initial.time(9) },
+    ];
+    check({
+      latestTurn: { ...initial.input.latestTurn, state: "completed", completedAt: initial.time(9) },
+      runningTurnId: null,
+      isWorking: false,
+    });
+    work = [
+      ...work,
+      {
+        id: "late-failure",
+        turnId: initial.turnId,
+        createdAt: initial.time(10),
+        label: "Failed command",
+        command: "vp test",
+        tone: "error",
+        toolCallId: "failed-tool",
+        toolLifecycleStatus: "failed",
+        sourceActivityKind: "tool.completed",
+      },
+    ];
+    check();
+    messages = [
+      ...messages.slice(0, -1),
+      { ...messages.at(-1)!, text: "Updated final text", updatedAt: initial.time(11) },
+    ];
+    check();
+    check({
+      latestTurn: {
+        ...initial.input.latestTurn,
+        state: "interrupted",
+        completedAt: initial.time(12),
+      },
+    });
+    check({ expandedTurnIds: new Set([initial.historyTurnId, initial.turnId]) });
+    const group = projection.rows.find((row) => row.kind === "work-toggle");
+    check({ expandedWorkGroupIds: new Set(group ? [group.id] : []) });
+    messages = [
+      { ...messages[0]!, id: MessageId.make("older-user"), createdAt: "2026-09-03T23:59:00.000Z" },
+      ...messages,
+    ];
+    check();
+    messages = messages.map((message) =>
+      message.id === MessageId.make("live-assistant")
+        ? { ...message, role: "user", turnId: null, createdAt: initial.time(0) }
+        : message,
+    );
+    check({ revertTurnCountByUserMessageId: new Map([[MessageId.make("live-user"), 3]]) });
+  });
+});
 
 describe("expanded tool group scrolling", () => {
   const entries = [{ id: "first" }, { id: "second" }];
@@ -829,11 +1226,10 @@ describe("deriveMessagesTimelineRows", () => {
       })),
     ];
 
-    const rows = deriveMessagesTimelineRows({
-      timelineEntries,
+    const input = {
       latestTurn: {
         turnId,
-        state: "error",
+        state: "error" as const,
         startedAt: "2026-01-01T00:00:00Z",
         completedAt: "2026-01-01T00:00:10Z",
       },
@@ -841,7 +1237,8 @@ describe("deriveMessagesTimelineRows", () => {
       activeTurnStartedAt: null,
       turnDiffSummaryByAssistantMessageId: new Map(),
       revertTurnCountByUserMessageId: new Map(),
-    });
+    };
+    const rows = deriveMessagesTimelineRows({ ...input, timelineEntries });
 
     expect(rows.map((row) => row.id)).toEqual([
       "turn-fold:turn-1",
@@ -864,6 +1261,11 @@ describe("deriveMessagesTimelineRows", () => {
       showAssistantMeta: false,
       showAssistantCopyButton: false,
     });
+    expect(
+      deriveMessagesTimelineRows({ ...input, timelineEntries: timelineEntries.slice(0, 3) }).map(
+        (row) => row.id,
+      ),
+    ).toEqual(["turn-fold:turn-1", "assistant-final-entry"]);
   });
 
   it("folds all assistant messages before the terminal message", () => {
diff --git a/apps/web/src/components/chat/MessagesTimeline.logic.ts b/apps/web/src/components/chat/MessagesTimeline.logic.ts
index 6883a5c74c76..36c90c89563c 100644
--- a/apps/web/src/components/chat/MessagesTimeline.logic.ts
+++ b/apps/web/src/components/chat/MessagesTimeline.logic.ts
@@ -1,4 +1,5 @@
 import * as Equal from "effect/Equal";
+import { shallow } from "zustand/vanilla/shallow";
 import { renderCodexDirectivesForCopy } from "@t3tools/client-runtime/codex-markdown-directives";
 import { commandProgramName } from "@t3tools/client-runtime/work-log/command-label";
 import {
@@ -19,6 +20,7 @@ export {
 } from "@t3tools/client-runtime/work-log/presentation";
 import {
   formatDuration,
+  isStreamingMessageTextUpdate,
   workEntryDisplayIndicatesToolFailure,
   workEntryIndicatesToolSuccess,
   workEntryIndicatesToolNeutralStatus,
@@ -540,8 +542,8 @@ function workEntryIsActiveTurnActivity(entry: WorkLogEntry): boolean {
 
 /**
  * Settled turns fold activity before their terminal assistant message behind
- * a "Worked for ..." row. Work that lands after that message stays visible so
- * failed or interrupted turns do not hide their trailing tool-call summary.
+ * a "Worked for ..." row. A single ordinary activity after that message joins
+ * the fold, while larger groups and failures stay visible as a trailing summary.
  */
 function deriveTurnFolds(input: {
   timelineEntries: ReadonlyArray<TimelineEntry>;
@@ -621,7 +623,11 @@ function deriveTurnFolds(input: {
       }
       const isCompaction =
         entry.kind === "work" && entry.entry.sourceActivityKind === "context-compaction";
-      if (!isCompaction && index > terminalEntryIndex) {
+      const isSingleTrailingActivity =
+        group.entries.length === terminalEntryIndex + 2 &&
+        entry.kind === "work" &&
+        !workEntryDisplayIndicatesToolFailure(entry.entry);
+      if (!isCompaction && index > terminalEntryIndex && !isSingleTrailingActivity) {
         continue;
       }
       // Agent-spawn CTA rows never fold: workflows outlive their launching
@@ -1153,6 +1159,59 @@ export function deriveMessagesTimelineRows(input: {
   return attachTrailingToolGroupsToAssistant(nextRows);
 }
 
+type MessagesTimelineRowsInput = Parameters<typeof deriveMessagesTimelineRows>[0];
+
+export interface MessagesTimelineRowsProjection {
+  readonly input: MessagesTimelineRowsInput;
+  readonly rows: MessagesTimelineRow[];
+}
+
+function replaceStreamingMessageRows(
+  input: MessagesTimelineRowsInput,
+  previous: MessagesTimelineRowsProjection,
+): MessagesTimelineRow[] | null {
+  const { timelineEntries: previousEntries, ...previousContext } = previous.input;
+  const { timelineEntries, ...context } = input;
+  if (timelineEntries.length !== previousEntries.length || !shallow(previousContext, context)) {
+    return null;
+  }
+  const replacements = new Map<ChatMessage, ChatMessage>();
+  for (const [index, entry] of timelineEntries.entries()) {
+    const previousEntry = previousEntries[index]!;
+    if (entry === previousEntry) continue;
+    if (
+      entry.kind !== "message" ||
+      previousEntry.kind !== "message" ||
+      entry.id !== previousEntry.id ||
+      entry.createdAt !== previousEntry.createdAt
+    ) {
+      return null;
+    }
+    if (entry.message === previousEntry.message) continue;
+    if (!isStreamingMessageTextUpdate(previousEntry.message, entry.message)) return null;
+    replacements.set(previousEntry.message, entry.message);
+  }
+  if (replacements.size === 0) return previous.rows;
+  return previous.rows.map((row) => {
+    if (row.kind !== "message" && row.kind !== "assistant-meta") return row;
+    const message = replacements.get(row.message);
+    return message ? { ...row, message } : row;
+  });
+}
+
+/** Keep one projection per timeline. Reuse rows only when streaming content changes. */
+export function deriveMessagesTimelineRowsWithState(
+  input: MessagesTimelineRowsInput,
+  previous: MessagesTimelineRowsProjection | null = null,
+): MessagesTimelineRowsProjection {
+  return {
+    input,
+    rows:
+      (previous === null ? null : replaceStreamingMessageRows(input, previous)) ??
+      deriveMessagesTimelineRows(input),
+  };
+}
+
 export function computeStableMessagesTimelineRows(
   rows: MessagesTimelineRow[],
   previous: StableMessagesTimelineRowsState,
diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
index bcb4306387c5..16a0cbd83ce3 100644
--- a/apps/web/src/components/chat/MessagesTimeline.test.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -1,9 +1,12 @@
 import { CheckpointRef, EnvironmentId, MessageId, TurnId } from "@t3tools/contracts";
 import { codexFeedbackMessage } from "@t3tools/client-runtime/state/threads";
-import { createRef, type ReactNode, type Ref } from "react";
+import { act, createRef, useLayoutEffect, type ReactNode, type Ref } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
+import { create, type ReactTestRenderer } from "react-test-renderer";
 import { beforeAll, describe, expect, it, vi } from "vite-plus/test";
 import type { LegendListRef, MaintainScrollAtEndOptions } from "@legendapp/list/react";
+import { shouldUseRestingComposerLayout } from "../composerFooterLayout";
+import { useComposerFocusState } from "./useComposerFocusState";
 
 vi.mock("@legendapp/list/react", async () => {
   const legendListTestId = "legend-list";
@@ -122,6 +125,10 @@ vi.mock("@pierre/diffs/react", () => {
   return { FileDiff: MockFileDiff };
 });
 
+vi.mock("../DiffWorkerPoolProvider", () => ({
+  DiffWorkerPoolProvider: ({ children }: { children?: ReactNode }) => children,
+}));
+
 function matchMedia() {
   return {
     matches: false,
@@ -233,6 +240,93 @@ function buildAssistantTimelineEntry(text: string) {
 }
 
 describe("MessagesTimeline", () => {
+  it.each([
+    { toolLifecycleStatus: "inProgress", isAtEnd: true },
+    { toolLifecycleStatus: "inProgress", isAtEnd: false },
+    { toolLifecycleStatus: "completed", isAtEnd: true },
+    { toolLifecycleStatus: "completed", isAtEnd: false },
+  ] as const)(
+    "restores the composer after closing $toolLifecycleStatus tool output only at the end: $isAtEnd",
+    async ({ toolLifecycleStatus, isAtEnd }) => {
+      const frames = new Map<number, FrameRequestCallback>();
+      let nextFrame = 0;
+      vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+        frames.set(++nextFrame, callback);
+        return nextFrame;
+      });
+      vi.stubGlobal("cancelAnimationFrame", (frame: number) => frames.delete(frame));
+      vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+      const flushFrame = () =>
+        act(() => {
+          const callbacks = [...frames.values()];
+          frames.clear();
+          callbacks.forEach((callback) => callback(0));
+        });
+      const props = buildProps();
+      let timelineIsAtEnd = isAtEnd;
+      props.listRef.current = {
+        getState: () => ({ isAtEnd: timelineIsAtEnd }),
+        getScrollableNode: () => null,
+      } as unknown as LegendListRef;
+      let isResting = true;
+      function ThreadProbe() {
+        const composer = useComposerFocusState(false);
+        useLayoutEffect(() => {
+          isResting = shouldUseRestingComposerLayout({
+            isExistingThread: true,
+            isMobileViewport: false,
+            isFocused: composer.isComposerFocused,
+            isScrollCollapsed: composer.isComposerScrollCollapsed,
+            hasExpandedChrome: false,
+            collapseOnBlur: true,
+          });
+        });
+        return (
+          <MessagesTimeline
+            {...props}
+            isWorking={toolLifecycleStatus === "inProgress"}
+            onToolOutputCollapsedAtEnd={composer.restoreAfterTimelineReachedEnd}
+            timelineEntries={[
+              {
+                id: "running-tool",
+                kind: "work",
+                createdAt: MESSAGE_CREATED_AT,
+                entry: {
+                  id: "running-tool",
+                  createdAt: MESSAGE_CREATED_AT,
+                  label: "Run command",
+                  tone: "tool",
+                  toolLifecycleStatus,
+                  detail: "Command output",
+                },
+              },
+            ]}
+          />
+        );
+      }
+      let renderer: ReactTestRenderer | undefined;
+      try {
+        await act(() => {
+          renderer = create(<ThreadProbe />);
+        });
+        const toggle = renderer!.root.findByProps({ "aria-expanded": false });
+        await act(() => toggle.props.onClick());
+        await flushFrame();
+        await flushFrame();
+        expect(isResting).toBe(true);
+
+        timelineIsAtEnd = false;
+        await act(() => toggle.props.onClick());
+        await flushFrame();
+        timelineIsAtEnd = isAtEnd;
+        await flushFrame();
+        expect(isResting).toBe(!isAtEnd);
+      } finally {
+        await act(() => renderer?.unmount());
+      }
+    },
+  );
+
   it("renders a feedback command and its pending response as normal thread messages", () => {
     const submission = {
       id: MessageId.make("feedback-command"),
@@ -375,9 +469,8 @@ describe("MessagesTimeline", () => {
     expect(markup).toContain("sticky top-2 z-10");
     expect(markup).not.toContain("self-start");
     expect(markup).toContain("whitespace-nowrap");
-    expect(markup).toContain("!size-[22px]");
     expect(markup).toContain("size-3");
-    expect(markup).toContain('aria-label="Collapse all folders"');
+    expect(markup).not.toContain('aria-label="Collapse all folders"');
     expect(markup).toContain('aria-label="Open diff"');
     expect(markup).toContain("1 changed file");
   });
@@ -1131,7 +1224,7 @@ describe("MessagesTimeline", () => {
               label: "Ran command",
               tone: "tool",
               itemType: "command_execution",
-              toolLifecycleStatus: "completed",
+              toolLifecycleStatus: "failed",
             },
           },
         ]}
@@ -1199,7 +1292,7 @@ describe("MessagesTimeline", () => {
     expect(markup).not.toContain('aria-label="Hidden work includes a failure"');
   });
 
-  it("shows the animated one-line label for a live tool group", () => {
+  it("shows the one-line label for a live tool group", () => {
     const turnId = TurnId.make("turn-live");
     const markup = renderToStaticMarkup(
       <MessagesTimeline
@@ -1236,7 +1329,6 @@ describe("MessagesTimeline", () => {
 
     expect(markup).toContain("Working for");
     expect(markup).toContain("Running pnpm");
-    expect(markup).toContain("live-activity-focus");
   });
 
   it("scopes a live row failure to the tool named by the row", () => {
@@ -1354,7 +1446,6 @@ describe("MessagesTimeline", () => {
 
     expect(markup).toContain("Running pnpm");
     expect(markup).toContain("lucide-terminal");
-    expect(markup).toContain("live-activity-focus");
     expect(markup).not.toContain("Ran pnpm");
     expect(markup).not.toContain("Thinking");
     expect(markup).not.toContain('data-timeline-row-kind="thinking"');
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index e97f10c39439..4854121b5a3e 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -27,7 +27,9 @@ const NOOP_USE_ARTIFACT_TEMPLATE = () => {};
 const NOOP_OPEN_ATTACHMENT = (_attachment: ChatFileAttachment) => {};
 import { resolveChatListAnchoredEndSpace } from "@t3tools/shared/chatList";
 import { toolActivityFaviconUrl } from "@t3tools/shared/favicon";
+import { formatDuration } from "@t3tools/shared/orchestrationTiming";
 import { getProjectFaviconCacheKey } from "@t3tools/shared/projectFavicon";
+import { observeVisibleAnimation } from "../../lib/visibleAnimation";
 import {
   createContext,
   Fragment,
@@ -50,8 +52,11 @@ import {
   type MaintainScrollAtEndOptions,
 } from "@legendapp/list/react";
 import { FileDiff } from "@pierre/diffs/react";
+import { DiffWorkerPoolProvider } from "../DiffWorkerPoolProvider";
 import {
+  createMessageAttachmentPreviewProjector,
   deriveTimelineEntries,
+  selectMessageImageResources,
   workEntryDisplayIndicatesToolFailure,
   workEntrySignalsSevereFailure,
   workLogEntryIsToolLike,
@@ -98,7 +103,7 @@ import {
   ZapIcon,
 } from "lucide-react";
 import { Button } from "../ui/button";
-import { useAssetUrlRefresh, useAssetUrlState } from "../../assets/assetUrls";
+import { useAssetUrlRefresh, useAssetUrls, useAssetUrlState } from "../../assets/assetUrls";
 import { MediaVideoPlayer } from "../media/MediaVideoPlayer";
 import { getVirtualizedScrollFadeClassName } from "../ui/scroll-area";
 import {
@@ -108,7 +113,6 @@ import {
 } from "./ExpandedImagePreview";
 import { ProposedPlanCard } from "./ProposedPlanCard";
 import { ChangedFilesCard } from "./ChangedFilesTree";
-import { shouldAutoExpandChangedFiles } from "./changedFilesPresentation";
 import { CHAT_TIMELINE_ANCHOR_OFFSET } from "./timelineScrollAnchoring";
 import { MessageCopyButton } from "./MessageCopyButton";
 import { PierreEntryIcon } from "./PierreEntryIcon";
@@ -122,7 +126,8 @@ import {
 import { useAssistantCitationTarget, type CitationHistoryPage } from "./useAssistantCitationTarget";
 import {
   computeStableMessagesTimelineRows,
-  deriveMessagesTimelineRows,
+  deriveMessagesTimelineRowsWithState,
+  type MessagesTimelineRowsProjection,
   liveWorkEntryLabel,
   resolveAssistantMessageCopyState,
   resolveTimelineIsAtEnd,
@@ -203,7 +208,7 @@ interface TimelineRowSharedState {
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
   onToggleTurnFold: (turnId: TurnId) => void;
   onToggleWorkGroup: (groupId: string, anchorKey: string) => void;
-  onToggleWorkEntry: (anchorKey: string) => void;
+  onToggleWorkEntry: (anchorKey: string, collapsed: boolean) => void;
   workGroupViewState: WorkGroupViewState;
   agentPanelModel: AgentPanelModel;
   onOpenAgents: () => void;
@@ -227,7 +232,7 @@ interface WorkGroupViewState {
 
 const WorkGroupViewCtx = createContext<{
   state: WorkGroupViewState;
-  onToggleEntry: () => void;
+  onToggleEntry: (collapsed: boolean) => void;
 } | null>(null);
 const TIMELINE_LIST_HEADER = <div className="h-3 sm:h-4" />;
 const TIMELINE_LIST_FADE_HEADER = (
@@ -330,6 +335,7 @@ interface MessagesTimelineProps {
    */
   liveFollowEnabled: boolean;
   onIsAtEndChange: (isAtEnd: boolean) => void;
+  onToolOutputCollapsedAtEnd?: () => void;
   onManualNavigation: () => void;
   hideEmptyPlaceholder?: boolean;
   topFadeEnabled?: boolean;
@@ -376,6 +382,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   contentInsetEndAdjustment,
   liveFollowEnabled,
   onIsAtEndChange,
+  onToolOutputCollapsedAtEnd,
   onManualNavigation,
   hideEmptyPlaceholder = false,
   topFadeEnabled = false,
@@ -410,24 +417,32 @@ export const MessagesTimeline = memo(function MessagesTimeline({
     };
   }, []);
 
-  const suspendEndScrollMaintenanceForDisclosure = useCallback((anchorKey: string) => {
-    disclosureAnchorKeyRef.current = anchorKey;
-    setDisclosureToggleSettling(true);
-    if (disclosureSettleFrameRef.current !== null) {
-      cancelAnimationFrame(disclosureSettleFrameRef.current);
-    }
-    if (disclosureSettleSecondFrameRef.current !== null) {
-      cancelAnimationFrame(disclosureSettleSecondFrameRef.current);
-    }
-    disclosureSettleFrameRef.current = requestAnimationFrame(() => {
-      disclosureSettleSecondFrameRef.current = requestAnimationFrame(() => {
-        disclosureAnchorKeyRef.current = null;
-        setDisclosureToggleSettling(false);
-        disclosureSettleFrameRef.current = null;
-        disclosureSettleSecondFrameRef.current = null;
+  const suspendEndScrollMaintenanceForDisclosure = useCallback(
+    (anchorKey: string, collapsed = false) => {
+      disclosureAnchorKeyRef.current = anchorKey;
+      setDisclosureToggleSettling(true);
+      if (disclosureSettleFrameRef.current !== null) {
+        cancelAnimationFrame(disclosureSettleFrameRef.current);
+      }
+      if (disclosureSettleSecondFrameRef.current !== null) {
+        cancelAnimationFrame(disclosureSettleSecondFrameRef.current);
+      }
+      disclosureSettleFrameRef.current = requestAnimationFrame(() => {
+        disclosureSettleSecondFrameRef.current = requestAnimationFrame(() => {
+          disclosureAnchorKeyRef.current = null;
+          setDisclosureToggleSettling(false);
+          disclosureSettleFrameRef.current = null;
+          disclosureSettleSecondFrameRef.current = null;
+          // Wait for row measurement and the disclosure click's blur check.
+          // Closing output can reveal the end without a scroll event.
+          if (collapsed && resolveTimelineIsAtEnd(listRef.current?.getState()) === true) {
+            onToolOutputCollapsedAtEnd?.();
+          }
+        });
       });
-    });
-  }, []);
+    },
+    [listRef, onToolOutputCollapsedAtEnd],
+  );
 
   const shouldRestoreVisibleContentPosition = useCallback((row: MessagesTimelineRow) => {
     const disclosureAnchorKey = disclosureAnchorKeyRef.current;
@@ -460,7 +475,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   );
   const onToggleWorkGroup = useCallback(
     (groupId: string, anchorKey: string) => {
-      suspendEndScrollMaintenanceForDisclosure(anchorKey);
+      suspendEndScrollMaintenanceForDisclosure(anchorKey, expandedWorkGroupIds.has(groupId));
       setExpandedWorkGroupIds((existing) => {
         const next = new Set(existing);
         if (next.has(groupId)) {
@@ -471,7 +486,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
         return next;
       });
     },
-    [suspendEndScrollMaintenanceForDisclosure],
+    [expandedWorkGroupIds, suspendEndScrollMaintenanceForDisclosure],
   );
 
   // An in-session interrupt leaves its turn expanded so the user keeps their
@@ -503,9 +518,15 @@ export const MessagesTimeline = memo(function MessagesTimeline({
     });
   }, [latestTurn]);
 
-  const rawRows = useMemo(
-    () =>
-      deriveMessagesTimelineRows({
+  const rowsProjectionRef = useRef<{
+    threadKey: string;
+    workspaceRoot: string | undefined;
+    projection: MessagesTimelineRowsProjection;
+  } | null>(null);
+  const rawRows = useMemo(() => {
+    const previous = rowsProjectionRef.current;
+    const projection = deriveMessagesTimelineRowsWithState(
+      {
         timelineEntries,
         latestTurn,
         runningTurnId,
@@ -515,19 +536,27 @@ export const MessagesTimeline = memo(function MessagesTimeline({
         activeTurnStartedAt,
         turnDiffSummaryByAssistantMessageId,
         revertTurnCountByUserMessageId,
-      }),
-    [
-      timelineEntries,
-      latestTurn,
-      runningTurnId,
-      expandedTurnIds,
-      expandedWorkGroupIds,
-      isWorking,
-      activeTurnStartedAt,
-      turnDiffSummaryByAssistantMessageId,
-      revertTurnCountByUserMessageId,
-    ],
-  );
+      },
+      previous?.threadKey === routeThreadKey && previous.workspaceRoot === workspaceRoot
+        ? previous.projection
+        : null,
+    );
+    rowsProjectionRef.current = { threadKey: routeThreadKey, workspaceRoot, projection };
+    return projection.rows;
+  }, [
+    rowsProjectionRef,
+    routeThreadKey,
+    workspaceRoot,
+    timelineEntries,
+    latestTurn,
+    runningTurnId,
+    expandedTurnIds,
+    expandedWorkGroupIds,
+    isWorking,
+    activeTurnStartedAt,
+    turnDiffSummaryByAssistantMessageId,
+    revertTurnCountByUserMessageId,
+  ]);
   const rows = useStableRows(rawRows);
   const minimapItems = useMemo(() => deriveTimelineMinimapItems(rows), [rows]);
   const [timelineViewportElement, setTimelineViewportElement] = useState<HTMLDivElement | null>(
@@ -639,10 +668,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
       listRef,
       timestampFormat,
       routeThreadKey,
-      // Must be referentially stable: ChatMarkdown keys its react-markdown
-      // component map on threadRef, and a fresh object here remounts every
-      // rendered markdown node whenever this memo recomputes (e.g. on each
-      // activity delta while the thread is working).
+      // Keep Markdown callbacks memoized during unrelated activity updates.
       threadRef: citationThreadRef,
       markdownCwd,
       resolvedTheme,
@@ -1214,9 +1240,24 @@ function UserVideoAttachment({ file }: { readonly file: ChatFileAttachment }) {
 
 function UserTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "message" }> }) {
   const ctx = use(TimelineRowCtx);
+  const resources = useMemo(
+    () => selectMessageImageResources(row.message.attachments),
+    [row.message.attachments],
+  );
+  const previewUrls = useAssetUrls(ctx.activeThreadEnvironmentId, resources);
+  const [projectPreviews] = useState(createMessageAttachmentPreviewProjector);
+  const messageWithPreviews = useMemo(() => {
+    const urlsById = new Map(
+      resources.flatMap((resource, index) => {
+        const url = previewUrls[index];
+        return url ? [[resource.attachmentId, url] as const] : [];
+      }),
+    );
+    return projectPreviews(row.message, (attachment) => urlsById.get(attachment.id));
+  }, [previewUrls, projectPreviews, resources, row.message]);
   // The attachment union has an open member, so guards (not literal type
   // comparisons) split it. Unknown types render as inert rows below the files.
-  const userImages = (row.message.attachments ?? []).filter(isImageAttachment);
+  const userImages = (messageWithPreviews.attachments ?? []).filter(isImageAttachment);
   const userFiles = (row.message.attachments ?? []).filter(isFileAttachment);
   const userVideos = userFiles.filter(isVideoAttachment);
   const otherUserFiles = userFiles.filter((file) => !isVideoAttachment(file));
@@ -1613,6 +1654,7 @@ function WorkingTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "workin
       <div className="flex h-6 min-w-0 items-baseline px-1 text-sm leading-relaxed text-muted-foreground tabular-nums">
         <span
           key={isPreparingWorktree ? "setup" : isCompacting ? "compacting" : "working"}
+          ref={isPreparingWorktree || isCompacting ? observeVisibleAnimation : undefined}
           className="relative shrink-0 overflow-hidden whitespace-nowrap transition-opacity duration-150 starting:opacity-0 motion-reduce:transition-none"
         >
           {isPreparingWorktree ? (
@@ -1646,7 +1688,7 @@ function ThinkingTimelineRow() {
   return (
     <div className="min-h-7">
       {isPreparingWorktree || isCompacting ? null : (
-        <LiveActivityRow label="Thinking" iconName="brain" />
+        <LiveActivityRow label="Thinking" iconName="brain" active shimmer />
       )}
     </div>
   );
@@ -1666,7 +1708,7 @@ function CompactingLabel() {
 // does not create a React commit every second while a response is streaming.
 // ---------------------------------------------------------------------------
 
-/** Live "Working for Xs" label. */
+/** Live elapsed time for the "Working for" label. */
 function WorkingTimer({ createdAt }: { createdAt: string }) {
   const textRef = useRef<HTMLSpanElement>(null);
   const initialText = formatWorkingTimerNow(createdAt);
@@ -1706,7 +1748,11 @@ const WorkGroupSection = memo(function WorkGroupSection({
   isExpandedToolGroup: boolean;
   displayLabel?: string | undefined;
 }) {
-  const { workspaceRoot, routeThreadKey } = use(TimelineRowCtx);
+  const { workspaceRoot, routeThreadKey, onToggleWorkEntry } = use(TimelineRowCtx);
+  const onToggleStandaloneEntry = useCallback(
+    (collapsed: boolean) => onToggleWorkEntry(anchorKey, collapsed),
+    [anchorKey, onToggleWorkEntry],
+  );
   const nonEmptyEntries = useMemo(
     () => groupedEntries.filter((entry) => workEntryIsVisibleInGroup(entry, isExpandedToolGroup)),
     [groupedEntries, isExpandedToolGroup],
@@ -1734,6 +1780,7 @@ const WorkGroupSection = memo(function WorkGroupSection({
             workspaceRoot={workspaceRoot}
             isExpandedToolGroupEntry={false}
             displayLabel={displayLabel}
+            onToggleEntry={onToggleStandaloneEntry}
           />
         ))}
       </div>
@@ -1770,7 +1817,10 @@ function ExpandedWorkGroupEntries({
   }
 
   const groupView = useMemo(
-    () => ({ state: viewState, onToggleEntry: () => onToggleWorkEntry(anchorKey) }),
+    () => ({
+      state: viewState,
+      onToggleEntry: (collapsed: boolean) => onToggleWorkEntry(anchorKey, collapsed),
+    }),
     [anchorKey, onToggleWorkEntry, viewState],
   );
   const updateScrollFades = useCallback(() => {
@@ -1909,30 +1959,36 @@ function LiveActivityRow({
   iconName,
   toolIcon,
   failed = false,
+  active = false,
+  shimmer = false,
 }: {
   label: string;
   iconName?: WorkEntryIconName;
   toolIcon?: ToolActivityIcon | undefined;
   failed?: boolean;
+  active?: boolean;
+  shimmer?: boolean;
 }) {
+  const animated = active && !failed;
+  const showShimmer = animated && shimmer;
   return (
-    <div className="relative min-h-6 w-fit max-w-full min-w-0 overflow-hidden rounded-md text-sm leading-relaxed">
+    <div
+      ref={animated ? observeVisibleAnimation : undefined}
+      className="relative min-h-6 w-fit max-w-full min-w-0 overflow-hidden rounded-md text-sm leading-relaxed"
+    >
       <LiveActivityContent
         label={label}
         iconName={iconName}
         toolIcon={toolIcon}
         failed={failed}
         announceFailure={failed}
+        active={animated && !shimmer}
       />
-      <ActivityShimmerOverlay>
-        <LiveActivityContent
-          label={label}
-          iconName={iconName}
-          toolIcon={toolIcon}
-          failed={failed}
-          highlighted
-        />
-      </ActivityShimmerOverlay>
+      {showShimmer ? (
+        <ActivityShimmerOverlay>
+          <LiveActivityContent label={label} iconName={iconName} toolIcon={toolIcon} highlighted />
+        </ActivityShimmerOverlay>
+      ) : null}
     </div>
   );
 }
@@ -1943,6 +1999,7 @@ function LiveActivityContent({
   toolIcon,
   failed = false,
   announceFailure = false,
+  active = false,
   highlighted = false,
 }: {
   label: string;
@@ -1950,6 +2007,7 @@ function LiveActivityContent({
   toolIcon?: ToolActivityIcon | undefined;
   failed?: boolean;
   announceFailure?: boolean;
+  active?: boolean;
   highlighted?: boolean;
 }) {
   const showTrailingFailureMark =
@@ -1967,7 +2025,7 @@ function LiveActivityContent({
         <span
           className={cn(
             "flex size-6 shrink-0 items-center justify-center",
-            highlighted ? "text-foreground" : failed ? failedToolIconClassName : "text-icon-muted",
+            failed ? failedToolIconClassName : highlighted ? "text-foreground" : "text-icon-muted",
           )}
           role={announceFailure ? "img" : undefined}
           aria-label={announceFailure ? "Tool call failed" : undefined}
@@ -1980,12 +2038,9 @@ function LiveActivityContent({
           />
         </span>
       ) : null}
-      <span className="min-w-0 flex-1 truncate">{label}</span>
+      <span className={cn("min-w-0 flex-1 truncate", active && "live-tool-shine")}>{label}</span>
       {showTrailingFailureMark ? (
-        <XIcon
-          aria-hidden
-          className={cn("size-3 shrink-0", !highlighted && failedToolIconClassName)}
-        />
+        <XIcon aria-hidden className={cn("size-3 shrink-0", failedToolIconClassName)} />
       ) : null}
     </span>
   );
@@ -2004,24 +2059,13 @@ function LiveWorkEntryTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "
       aria-expanded={row.expanded}
       onClick={() => ctx.onToggleWorkGroup(row.groupId, row.id)}
     >
-      {row.active ? (
-        <LiveActivityRow
-          label={label}
-          iconName={workEntryIconName(row.entry)}
-          toolIcon={row.entry.toolIcon ?? row.entry.toolSource?.icon}
-          failed={failed}
-        />
-      ) : (
-        <div className="min-h-6 w-fit max-w-full min-w-0 overflow-hidden rounded-md text-sm leading-relaxed">
-          <LiveActivityContent
-            label={label}
-            iconName={workEntryIconName(row.entry)}
-            toolIcon={row.entry.toolIcon ?? row.entry.toolSource?.icon}
-            failed={failed}
-            announceFailure={failed}
-          />
-        </div>
-      )}
+      <LiveActivityRow
+        label={label}
+        iconName={workEntryIconName(row.entry)}
+        toolIcon={row.entry.toolIcon ?? row.entry.toolSource?.icon}
+        failed={failed}
+        active={row.active}
+      />
     </button>
   );
 }
@@ -2128,30 +2172,21 @@ function AssistantChangedFilesSectionInner({
   resolvedTheme: "light" | "dark";
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
 }) {
-  const activity = use(TimelineRowActivityCtx);
-  const isLatestTurn = activity.latestTurnId === turnSummary.turnId;
   const persistedExpanded = useUiStateStore(
     (store) => store.threadChangedFilesExpandedById[routeThreadKey]?.[turnSummary.turnId],
   );
   const setExpanded = useUiStateStore((store) => store.setThreadChangedFilesExpanded);
-  const [autoExpanded] = useState(() =>
-    shouldAutoExpandChangedFiles(checkpointFiles, isLatestTurn),
-  );
-  const [allDirectoriesExpanded, setAllDirectoriesExpanded] = useState(autoExpanded);
-  const expanded = persistedExpanded ?? (isLatestTurn && autoExpanded);
+  const allDirectoriesExpanded = persistedExpanded ?? false;
 
   return (
     <ChangedFilesCard
       turnId={turnSummary.turnId}
       files={checkpointFiles}
-      expanded={expanded}
-      showCompactPreview={isLatestTurn}
       allDirectoriesExpanded={allDirectoriesExpanded}
       resolvedTheme={resolvedTheme}
-      onExpandedChange={(nextExpanded) =>
-        setExpanded(routeThreadKey, turnSummary.turnId, nextExpanded)
+      onToggleAllDirectories={() =>
+        setExpanded(routeThreadKey, turnSummary.turnId, !allDirectoriesExpanded)
       }
-      onToggleAllDirectories={() => setAllDirectoriesExpanded((current) => !current)}
       onOpenTurnDiff={onOpenTurnDiff}
     />
   );
@@ -2533,19 +2568,22 @@ function UserMessageReviewCommentCard({ comment }: { comment: ReviewCommentConte
           className="text-message-foreground"
         />
       )}
-      {renderablePatch?.kind === "files" &&
-        renderablePatch.files.map((fileDiff) => (
-          <FileDiff
-            key={resolveFileDiffPath(fileDiff)}
-            fileDiff={fileDiff}
-            options={{
-              collapsed: false,
-              diffStyle: "unified",
-              theme: resolveDiffThemeName(ctx.resolvedTheme),
-              preferredHighlighter: PREFERRED_HIGHLIGHTER,
-            }}
-          />
-        ))}
+      {renderablePatch?.kind === "files" && (
+        <DiffWorkerPoolProvider>
+          {renderablePatch.files.map((fileDiff) => (
+            <FileDiff
+              key={resolveFileDiffPath(fileDiff)}
+              fileDiff={fileDiff}
+              options={{
+                collapsed: false,
+                diffStyle: "unified",
+                theme: resolveDiffThemeName(ctx.resolvedTheme),
+                preferredHighlighter: PREFERRED_HIGHLIGHTER,
+              }}
+            />
+          ))}
+        </DiffWorkerPoolProvider>
+      )}
       {renderablePatch?.kind === "raw" && (
         <pre className="overflow-x-auto rounded-md bg-muted/40 p-2 text-xs">
           {renderablePatch.text}
@@ -2591,15 +2629,7 @@ function formatWorkingTimer(startIso: string, endIso: string): string | null {
     return `${elapsedSeconds}s`;
   }
 
-  const hours = Math.floor(elapsedSeconds / 3600);
-  const minutes = Math.floor((elapsedSeconds % 3600) / 60);
-  const seconds = elapsedSeconds % 60;
-
-  if (hours > 0) {
-    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
-  }
-
-  return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+  return formatDuration(elapsedSeconds * 1_000);
 }
 
 function formatWorkingTimerNow(startIso: string): string {
@@ -3039,7 +3069,7 @@ const AgentSpawnCtaRow = memo(function AgentSpawnCtaRow(props: { workEntry: Time
     <button
       type="button"
       onClick={onOpenAgents}
-      className="flex w-full items-center gap-2 rounded-md border border-border/60 bg-card/50 px-2.5 py-1.5 text-left text-[13px] transition hover:bg-accent/50"
+      className="flex w-full items-center gap-2 rounded-md border border-border/60 bg-card/50 px-2.5 py-1.5 text-left text-[.8125rem] transition hover:bg-accent/50"
     >
       <span aria-hidden className={cn("size-1.5 shrink-0 rounded-full", dotClass)} />
       <WorkEntryIcon name="bot" className="size-3.5 shrink-0 text-muted-foreground" />
@@ -3063,6 +3093,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
   workspaceRoot: string | undefined;
   isExpandedToolGroupEntry: boolean;
   displayLabel?: string | undefined;
+  onToggleEntry?: ((collapsed: boolean) => void) | undefined;
 }) {
   const { workEntry, workspaceRoot, isExpandedToolGroupEntry, displayLabel } = props;
   // Before any hooks: spawn CTA rows render their own component.
@@ -3075,6 +3106,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
       workspaceRoot={workspaceRoot}
       isExpandedToolGroupEntry={isExpandedToolGroupEntry}
       displayLabel={displayLabel}
+      onToggleEntry={props.onToggleEntry}
     />
   );
 });
@@ -3084,6 +3116,7 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
   workspaceRoot: string | undefined;
   isExpandedToolGroupEntry: boolean;
   displayLabel?: string | undefined;
+  onToggleEntry?: ((collapsed: boolean) => void) | undefined;
 }) {
   const { workEntry, workspaceRoot, isExpandedToolGroupEntry, displayLabel } = props;
   const { threadRef, onImageExpand } = use(TimelineRowCtx);
@@ -3094,9 +3127,11 @@ const PlainWorkEntryRow = memo(function PlainWorkEntryRow(props: {
   const toggleExpanded = () => {
     const next = !expanded;
     if (groupView) {
-      groupView.onToggleEntry();
+      groupView.onToggleEntry(!next);
       if (next) groupView.state.expandedEntries.add(workEntry.id);
       else groupView.state.expandedEntries.delete(workEntry.id);
+    } else {
+      props.onToggleEntry?.(!next);
     }
     setExpanded(next);
   };
diff --git a/apps/web/src/components/chat/ModelPickerContent.tsx b/apps/web/src/components/chat/ModelPickerContent.tsx
index 8880369a18c9..63dea7844c46 100644
--- a/apps/web/src/components/chat/ModelPickerContent.tsx
+++ b/apps/web/src/components/chat/ModelPickerContent.tsx
@@ -5,6 +5,7 @@ import {
   type ResolvedKeybindingsConfig,
 } from "@t3tools/contracts";
 import { resolveSelectableModel } from "@t3tools/shared/model";
+import { useAtomValue } from "@effect/atom-react";
 import { LegendList, type LegendListRef } from "@legendapp/list/react";
 import { memo, useMemo, useState, useCallback, useEffect, useLayoutEffect, useRef } from "react";
 import { ChevronRightIcon, SearchIcon } from "lucide-react";
@@ -26,6 +27,8 @@ import {
   ComboboxListVirtualized,
 } from "../ui/combobox";
 import { ModelEsque } from "./providerIconUtils";
+import { isCommandPaletteOpen } from "../../commandPaletteBus";
+import { primaryServerKeybindingsAtom } from "../../state/server";
 import {
   modelPickerJumpCommandForIndex,
   modelPickerJumpIndexFromCommand,
@@ -217,10 +220,8 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
           : [],
       ),
   );
-  const keybindings = useMemo<ResolvedKeybindingsConfig>(
-    () => providedKeybindings ?? [],
-    [providedKeybindings],
-  );
+  const serverKeybindings = useAtomValue(primaryServerKeybindingsAtom);
+  const keybindings = providedKeybindings ?? serverKeybindings;
   const updateSettings = useUpdateClientSettings();
 
   const focusSearchInput = useCallback(() => {
@@ -678,7 +679,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
 
   useEffect(() => {
     const onWindowKeyDown = (event: globalThis.KeyboardEvent) => {
-      if (event.defaultPrevented || event.repeat) {
+      if (event.defaultPrevented || event.repeat || isCommandPaletteOpen()) {
         return;
       }
 
@@ -690,6 +691,8 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       if (jumpIndex === null) {
         return;
       }
+      event.preventDefault();
+      event.stopPropagation();
 
       const targetModelKey = modelJumpModelKeys[jumpIndex];
       if (!targetModelKey) {
@@ -699,8 +702,6 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       if (!model) {
         return;
       }
-      event.preventDefault();
-      event.stopPropagation();
       handleModelSelect(model.slug, model.instanceId);
     };
 
diff --git a/apps/web/src/components/chat/ProviderStatusBanner.test.tsx b/apps/web/src/components/chat/ProviderStatusBanner.test.tsx
index f27cda19d957..e51383bc69fe 100644
--- a/apps/web/src/components/chat/ProviderStatusBanner.test.tsx
+++ b/apps/web/src/components/chat/ProviderStatusBanner.test.tsx
@@ -28,6 +28,42 @@ function warningProvider(): ServerProvider {
 }
 
 describe("ProviderStatusBanner", () => {
+  it("waits for an Antigravity auth result before showing a sign-in warning", () => {
+    const status: ServerProvider = {
+      ...warningProvider(),
+      instanceId: ProviderInstanceId.make("google_work"),
+      driver: ProviderDriverKind.make("antigravity"),
+      auth: { status: "unknown" },
+      message: "Antigravity is installed. Google account access is not checked yet.",
+    };
+
+    expect(shouldShowProviderStatusBanner(status, null)).toBe(false);
+    expect(
+      shouldShowProviderStatusBanner(
+        {
+          ...status,
+          auth: { status: "unauthenticated" },
+          message: "Sign in with Google to use Antigravity.",
+        },
+        null,
+      ),
+    ).toBe(true);
+  });
+
+  it("shows Antigravity installation and startup failures before auth is checked", () => {
+    const status: ServerProvider = {
+      ...warningProvider(),
+      driver: ProviderDriverKind.make("antigravity"),
+      auth: { status: "unknown" },
+    };
+
+    expect(shouldShowProviderStatusBanner({ ...status, installed: false }, null)).toBe(true);
+    expect(shouldShowProviderStatusBanner({ ...status, status: "error" }, null)).toBe(true);
+    expect(
+      shouldShowProviderStatusBanner({ ...status, driver: ProviderDriverKind.make("codex") }, null),
+    ).toBe(true);
+  });
+
   it("stays hidden after its current warning is dismissed", () => {
     const status = warningProvider();
 
diff --git a/apps/web/src/components/chat/ProviderStatusBanner.tsx b/apps/web/src/components/chat/ProviderStatusBanner.tsx
index 2ae4bc8b58d4..12f9dc04f26a 100644
--- a/apps/web/src/components/chat/ProviderStatusBanner.tsx
+++ b/apps/web/src/components/chat/ProviderStatusBanner.tsx
@@ -7,9 +7,20 @@ import { formatProviderDriverKindLabel } from "../../providerModels";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 
 export function getProviderStatusBannerKey(status: ServerProvider | null): string | null {
-  return !status || status.status === "ready" || status.status === "disabled"
-    ? null
-    : [status.instanceId, status.status, status.auth.status, status.message ?? ""].join("\u0000");
+  if (!status || status.status === "ready" || status.status === "disabled") return null;
+  // Antigravity checks saved credentials when a session starts. Its local
+  // health check leaves auth unknown after a restart, which is not a failure.
+  if (
+    status.driver === "antigravity" &&
+    status.installed &&
+    status.status === "warning" &&
+    status.auth.status === "unknown"
+  ) {
+    return null;
+  }
+  return [status.instanceId, status.status, status.auth.status, status.message ?? ""].join(
+    "\u0000",
+  );
 }
 
 export function shouldShowProviderStatusBanner(
@@ -59,7 +70,7 @@ export const ProviderStatusBanner = memo(function ProviderStatusBanner({
   onOpenProviderSetup?: (instanceId: ProviderInstanceId) => void;
   status: ServerProvider | null;
 }) {
-  if (!status || status.status === "ready" || status.status === "disabled") {
+  if (!status || getProviderStatusBannerKey(status) === null) {
     return null;
   }
 
diff --git a/apps/web/src/components/chat/SkillInlineText.tsx b/apps/web/src/components/chat/SkillInlineText.tsx
index 6d026ea58cce..b6e398539133 100644
--- a/apps/web/src/components/chat/SkillInlineText.tsx
+++ b/apps/web/src/components/chat/SkillInlineText.tsx
@@ -10,7 +10,8 @@ import {
 } from "../composerInlineChip";
 import { cn } from "~/lib/utils";
 
-const SKILL_TOKEN_REGEX = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|$)/g;
+const SKILL_TOKEN_REGEX =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s|$)/g;
 
 type InlineSkill = Pick<ServerProviderSkill, "name" | "displayName">;
 
diff --git a/apps/web/src/components/chat/changedFilesPresentation.test.ts b/apps/web/src/components/chat/changedFilesPresentation.test.ts
deleted file mode 100644
index d13445b02260..000000000000
--- a/apps/web/src/components/chat/changedFilesPresentation.test.ts
+++ /dev/null
@@ -1,69 +0,0 @@
-import { describe, expect, it } from "vite-plus/test";
-
-import {
-  changedFileName,
-  selectChangedFilePreview,
-  shouldAutoExpandChangedFiles,
-  summarizeChangedFileScopes,
-} from "./changedFilesPresentation";
-
-describe("changed-files presentation", () => {
-  it("auto-expands only small, low-churn latest changes", () => {
-    const smallFiles = [
-      { path: "src/a.ts", kind: "modified", additions: 80, deletions: 20 },
-      { path: "src/b.ts", kind: "modified", additions: 60, deletions: 20 },
-    ];
-
-    expect(shouldAutoExpandChangedFiles(smallFiles, true)).toBe(true);
-    expect(shouldAutoExpandChangedFiles(smallFiles, false)).toBe(false);
-    expect(
-      shouldAutoExpandChangedFiles(
-        [{ path: "src/a.ts", kind: "modified", additions: 201, deletions: 0 }],
-        true,
-      ),
-    ).toBe(false);
-    expect(
-      shouldAutoExpandChangedFiles(
-        Array.from({ length: 6 }, (_, index) => ({
-          path: `src/${index}.ts`,
-          kind: "modified",
-          additions: 1,
-          deletions: 0,
-        })),
-        true,
-      ),
-    ).toBe(false);
-  });
-
-  it("summarizes the most prominent top-level scopes", () => {
-    const files = [
-      { path: "apps/web/src/App.tsx", kind: "modified", additions: 1, deletions: 0 },
-      { path: "README.md", kind: "modified", additions: 1, deletions: 0 },
-      { path: "apps/server/src/index.ts", kind: "modified", additions: 1, deletions: 0 },
-      { path: "packages/shared/src/git.ts", kind: "modified", additions: 1, deletions: 0 },
-      { path: "apps\\mobile\\App.tsx", kind: "modified", additions: 1, deletions: 0 },
-    ];
-
-    expect(summarizeChangedFileScopes(files)).toEqual([
-      { label: "apps", fileCount: 3 },
-      { label: "root", fileCount: 1 },
-      { label: "packages", fileCount: 1 },
-    ]);
-  });
-
-  it("previews files across different scopes before filling from one scope", () => {
-    const files = [
-      { path: "apps/web/src/App.tsx", kind: "modified", additions: 1, deletions: 0 },
-      { path: "apps/web/src/App.test.tsx", kind: "modified", additions: 1, deletions: 0 },
-      { path: "packages/shared/src/git.ts", kind: "modified", additions: 1, deletions: 0 },
-      { path: "README.md", kind: "modified", additions: 1, deletions: 0 },
-    ];
-
-    expect(selectChangedFilePreview(files).map((file) => file.path)).toEqual([
-      "apps/web/src/App.tsx",
-      "packages/shared/src/git.ts",
-      "README.md",
-    ]);
-    expect(changedFileName("apps\\web\\src\\App.tsx")).toBe("App.tsx");
-  });
-});
diff --git a/apps/web/src/components/chat/changedFilesPresentation.ts b/apps/web/src/components/chat/changedFilesPresentation.ts
deleted file mode 100644
index bb3cac6c4b12..000000000000
--- a/apps/web/src/components/chat/changedFilesPresentation.ts
+++ /dev/null
@@ -1,102 +0,0 @@
-import { type TurnDiffFileChange } from "../../types";
-import { summarizeTurnDiffStats } from "../../lib/turnDiffTree";
-
-export const CHANGED_FILES_AUTO_EXPAND_FILE_LIMIT = 5;
-export const CHANGED_FILES_AUTO_EXPAND_LINE_LIMIT = 200;
-export const CHANGED_FILES_PREVIEW_FILE_LIMIT = 3;
-export const CHANGED_FILES_PREVIEW_SCOPE_LIMIT = 4;
-
-export interface ChangedFilesScopeSummary {
-  readonly label: string;
-  readonly fileCount: number;
-}
-
-function pathSegments(pathValue: string): string[] {
-  return pathValue
-    .replaceAll("\\", "/")
-    .split("/")
-    .filter((segment) => segment.length > 0);
-}
-
-export function changedFileName(pathValue: string): string {
-  return pathSegments(pathValue).at(-1) ?? pathValue;
-}
-
-function changedFileScope(pathValue: string): string {
-  const segments = pathSegments(pathValue);
-  return segments.length > 1 ? (segments[0] ?? "root") : "root";
-}
-
-export function shouldAutoExpandChangedFiles(
-  files: ReadonlyArray<TurnDiffFileChange>,
-  isLatestTurn: boolean,
-): boolean {
-  if (!isLatestTurn || files.length > CHANGED_FILES_AUTO_EXPAND_FILE_LIMIT) {
-    return false;
-  }
-  const stat = summarizeTurnDiffStats(files);
-  return stat.additions + stat.deletions <= CHANGED_FILES_AUTO_EXPAND_LINE_LIMIT;
-}
-
-export function summarizeChangedFileScopes(
-  files: ReadonlyArray<TurnDiffFileChange>,
-  limit = CHANGED_FILES_PREVIEW_SCOPE_LIMIT,
-): ChangedFilesScopeSummary[] {
-  const scopes = new Map<string, { fileCount: number; firstIndex: number }>();
-  files.forEach((file, index) => {
-    const label = changedFileScope(file.path);
-    const current = scopes.get(label);
-    scopes.set(label, {
-      fileCount: (current?.fileCount ?? 0) + 1,
-      firstIndex: current?.firstIndex ?? index,
-    });
-  });
-
-  return Array.from(scopes, ([label, scope]) => ({
-    label,
-    fileCount: scope.fileCount,
-    firstIndex: scope.firstIndex,
-  }))
-    .toSorted(
-      (left, right) =>
-        right.fileCount - left.fileCount ||
-        left.firstIndex - right.firstIndex ||
-        left.label.localeCompare(right.label),
-    )
-    .slice(0, limit)
-    .map(({ label, fileCount }) => ({ label, fileCount }));
-}
-
-export function selectChangedFilePreview(
-  files: ReadonlyArray<TurnDiffFileChange>,
-  limit = CHANGED_FILES_PREVIEW_FILE_LIMIT,
-): TurnDiffFileChange[] {
-  const selected: TurnDiffFileChange[] = [];
-  const selectedPaths = new Set<string>();
-  const selectedScopes = new Set<string>();
-
-  for (const file of files) {
-    const scope = changedFileScope(file.path);
-    if (selectedScopes.has(scope)) {
-      continue;
-    }
-    selected.push(file);
-    selectedPaths.add(file.path);
-    selectedScopes.add(scope);
-    if (selected.length === limit) {
-      return selected;
-    }
-  }
-
-  for (const file of files) {
-    if (selectedPaths.has(file.path)) {
-      continue;
-    }
-    selected.push(file);
-    if (selected.length === limit) {
-      break;
-    }
-  }
-
-  return selected;
-}
diff --git a/apps/web/src/components/chat/composerPromptHistory.test.ts b/apps/web/src/components/chat/composerPromptHistory.test.ts
new file mode 100644
index 000000000000..80a7d3b3dfb0
--- /dev/null
+++ b/apps/web/src/components/chat/composerPromptHistory.test.ts
@@ -0,0 +1,214 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { appendElementContextsToPrompt } from "../../lib/elementContext";
+import {
+  appendTerminalContextsToPrompt,
+  materializeInlineTerminalContextPrompt,
+} from "../../lib/terminalContext";
+import { appendReviewCommentsToPrompt, buildFileReviewComment } from "../../reviewCommentContext";
+import { buildPlanImplementationPrompt } from "../../proposedPlan";
+import {
+  ATTACHMENT_ONLY_BOOTSTRAP_PROMPT,
+  buildComposerPromptHistoryEntries,
+  recallableComposerPrompt,
+  stepComposerPromptHistory,
+  type ComposerPromptHistoryPosition,
+} from "./composerPromptHistory";
+
+const entries = buildComposerPromptHistoryEntries([
+  { id: "m1", role: "user", text: "first" },
+  { id: "a1", role: "assistant", text: "reply" },
+  { id: "m2", role: "user", text: "second" },
+  { id: "m3", role: "user", text: "third" },
+]);
+
+function backward(position: ComposerPromptHistoryPosition | null, currentPrompt: string) {
+  return stepComposerPromptHistory({ direction: "backward", entries, position, currentPrompt });
+}
+
+function forward(position: ComposerPromptHistoryPosition | null, currentPrompt: string) {
+  return stepComposerPromptHistory({ direction: "forward", entries, position, currentPrompt });
+}
+
+describe("recallableComposerPrompt", () => {
+  it("strips send-time context blocks and the ultrathink prefix", () => {
+    const withTerminal = appendTerminalContextsToPrompt("Investigate this", [
+      {
+        terminalId: "default",
+        terminalLabel: "Terminal 1",
+        lineStart: 12,
+        lineEnd: 13,
+        text: "git status\nOn branch main",
+      },
+    ]);
+    const withElement = appendElementContextsToPrompt(withTerminal, [
+      {
+        pageUrl: "https://example.com",
+        pageTitle: "Example",
+        tagName: "button",
+        selector: "button.submit",
+        htmlPreview: "<button>Save</button>",
+        componentName: null,
+        source: null,
+        styles: "",
+      },
+    ]);
+    expect(recallableComposerPrompt(`Ultrathink:\n${withElement}`)).toBe("Investigate this");
+  });
+
+  it("removes inline terminal labels along with their trailing block", () => {
+    const context = {
+      terminalId: "default",
+      terminalLabel: "Terminal 1",
+      lineStart: 12,
+      lineEnd: 13,
+      text: "git status",
+    };
+    const typed = materializeInlineTerminalContextPrompt("Look at \uFFFC please", [context]);
+    expect(typed).toBe("Look at @terminal-1:12-13 please");
+    const sent = appendTerminalContextsToPrompt(typed, [context]);
+    expect(recallableComposerPrompt(sent)).toBe("Look at please");
+  });
+
+  it("removes one label per chip and leaves other whitespace alone", () => {
+    const context = {
+      terminalId: "default",
+      terminalLabel: "Terminal 1",
+      lineStart: 4,
+      lineEnd: 4,
+      text: "ls",
+    };
+    const typed = "@terminal-1:4 typed twice: @terminal-1:4\n    indented  code";
+    const sent = appendTerminalContextsToPrompt(typed, [context]);
+    expect(recallableComposerPrompt(sent)).toBe("typed twice: @terminal-1:4\n    indented  code");
+  });
+
+  it("does not strip a typed label that only starts with the chip label", () => {
+    const context = {
+      terminalId: "default",
+      terminalLabel: "Terminal 1",
+      lineStart: 4,
+      lineEnd: 4,
+      text: "ls",
+    };
+    const typed = "see @terminal-1:40 and @terminal-1:4-12 then @terminal-1:4";
+    const sent = appendTerminalContextsToPrompt(typed, [context]);
+    expect(recallableComposerPrompt(sent)).toBe("see @terminal-1:40 and @terminal-1:4-12 then");
+  });
+
+  it("strips only the review comments appended at the end", () => {
+    const comment = buildFileReviewComment({
+      id: "comment-1",
+      filePath: "src/app.ts",
+      startLine: 2,
+      endLine: 3,
+      text: "Keep this configurable.",
+      contents: "one\ntwo\nthree",
+    });
+    const sent = appendReviewCommentsToPrompt("Please update this.", [comment]);
+    expect(recallableComposerPrompt(sent)).toBe("Please update this.");
+    const midPrompt = appendReviewCommentsToPrompt("Before", [comment]) + "\n\nAfter";
+    expect(recallableComposerPrompt(midPrompt)).toBe(midPrompt);
+    // A typed block earlier in the prompt survives when the trailing one goes.
+    const both = appendReviewCommentsToPrompt(midPrompt, [comment]);
+    expect(recallableComposerPrompt(both)).toBe(midPrompt);
+  });
+
+  it("returns an empty string for app-composed sends", () => {
+    expect(recallableComposerPrompt("   ")).toBe("");
+    expect(recallableComposerPrompt(ATTACHMENT_ONLY_BOOTSTRAP_PROMPT)).toBe("");
+    expect(recallableComposerPrompt(buildPlanImplementationPrompt("# Plan\n1. do it"))).toBe("");
+  });
+});
+
+describe("buildComposerPromptHistoryEntries", () => {
+  it("keeps user messages with text, oldest first", () => {
+    expect(entries.map((entry) => entry.prompt)).toEqual(["first", "second", "third"]);
+  });
+
+  it("collapses consecutive duplicates onto the newest message id", () => {
+    const collapsed = buildComposerPromptHistoryEntries([
+      { id: "m1", role: "user", text: "same" },
+      { id: "m2", role: "user", text: "same" },
+      { id: "m3", role: "user", text: "other" },
+      { id: "m4", role: "user", text: "same" },
+    ]);
+    expect(collapsed).toEqual([
+      { id: "m2", prompt: "same" },
+      { id: "m3", prompt: "other" },
+      { id: "m4", prompt: "same" },
+    ]);
+  });
+});
+
+describe("stepComposerPromptHistory", () => {
+  it("does not start browsing from a non-empty draft", () => {
+    expect(backward(null, "typing")).toBeNull();
+  });
+
+  it("walks back from the newest entry", () => {
+    const first = backward(null, "");
+    expect(first).toEqual({ position: { entryId: "m3", recalled: "third" }, prompt: "third" });
+    expect(backward(first!.position, "third")?.prompt).toBe("second");
+  });
+
+  it("is a no-op at the oldest entry so the caret keeps moving", () => {
+    expect(backward({ entryId: "m1", recalled: "first" }, "first")).toBeNull();
+  });
+
+  it("walks forward and empties the composer past the newest entry", () => {
+    const newer = forward({ entryId: "m2", recalled: "second" }, "second");
+    expect(newer?.prompt).toBe("third");
+    expect(forward(newer!.position, "third")).toEqual({ position: null, prompt: "" });
+  });
+
+  it("treats an edited recall as a fresh draft", () => {
+    const position: ComposerPromptHistoryPosition = { entryId: "m3", recalled: "third" };
+    expect(backward(position, "third edited")).toBeNull();
+    expect(forward(position, "third edited")).toBeNull();
+    // Sent and cleared: ArrowUp starts over from the newest entry.
+    expect(backward(position, "")?.position).toEqual({ entryId: "m3", recalled: "third" });
+  });
+
+  it("does nothing on forward when not browsing", () => {
+    expect(forward(null, "")).toBeNull();
+  });
+
+  it("follows the entry by id when the list changes under it", () => {
+    const grown = buildComposerPromptHistoryEntries([
+      { id: "m0", role: "user", text: "zeroth" },
+      { id: "m1", role: "user", text: "A" },
+      { id: "m2", role: "user", text: "B" },
+      { id: "m3", role: "user", text: "A" },
+    ]);
+    const older = stepComposerPromptHistory({
+      direction: "backward",
+      entries: grown,
+      position: { entryId: "m1", recalled: "A" },
+      currentPrompt: "A",
+    });
+    expect(older?.prompt).toBe("zeroth");
+    // Unknown id with no matching text: browsing is over.
+    const missing = stepComposerPromptHistory({
+      direction: "forward",
+      entries: grown,
+      position: { entryId: "gone", recalled: "not sent" },
+      currentPrompt: "not sent",
+    });
+    expect(missing).toBeNull();
+  });
+
+  it("falls back to matching text when a duplicate collapse retires the id", () => {
+    const collapsed = buildComposerPromptHistoryEntries([
+      { id: "m1", role: "user", text: "first" },
+      { id: "m3", role: "user", text: "A" },
+    ]);
+    const step = stepComposerPromptHistory({
+      direction: "backward",
+      entries: collapsed,
+      position: { entryId: "m2", recalled: "A" },
+      currentPrompt: "A",
+    });
+    expect(step?.prompt).toBe("first");
+  });
+});
diff --git a/apps/web/src/components/chat/composerPromptHistory.ts b/apps/web/src/components/chat/composerPromptHistory.ts
new file mode 100644
index 000000000000..c4b6b4c0f93f
--- /dev/null
+++ b/apps/web/src/components/chat/composerPromptHistory.ts
@@ -0,0 +1,212 @@
+import { extractTrailingElementContexts } from "../../lib/elementContext";
+import { extractTrailingPreviewAnnotation } from "../../lib/previewAnnotation";
+import { extractTrailingTerminalContexts } from "../../lib/terminalContext";
+import { PLAN_IMPLEMENTATION_PROMPT_PREFIX } from "../../proposedPlan";
+
+/**
+ * Terminal-style prompt recall for the composer. ArrowUp on an empty
+ * composer walks back through the active thread's sent prompts, ArrowDown
+ * walks forward and restores the unsent draft past the newest entry.
+ *
+ * History is per thread and text only. It is derived from the thread's user
+ * messages on every keypress, so there is no store to persist or sync.
+ */
+
+const CLAUDE_ULTRATHINK_PREFIX = "Ultrathink:\n";
+const REVIEW_COMMENT_BLOCK_PATTERN = /<review_comment\b[^>]*>[\s\S]*?<\/review_comment>/g;
+
+/** Text sent in place of an empty prompt when a message is attachments only. */
+export const ATTACHMENT_ONLY_BOOTSTRAP_PROMPT =
+  "[User attached one or more files without additional text. Respond using the conversation context and the attached files.]";
+
+export interface ComposerPromptHistoryMessage {
+  readonly id: string;
+  readonly role: string;
+  readonly text: string;
+}
+
+export interface ComposerPromptHistoryEntry {
+  readonly id: string;
+  readonly prompt: string;
+}
+
+/**
+ * Active recall. `entryId` is resolved against the current entries on every
+ * step, so a server ack replacing an optimistic message or an older page
+ * loading cannot move the position. `recalled` is the text put in the
+ * composer; once the composer no longer matches it, the user has edited or
+ * sent and browsing is over.
+ */
+export interface ComposerPromptHistoryPosition {
+  readonly entryId: string;
+  readonly recalled: string;
+}
+
+/**
+ * Prefer the id. A consecutive duplicate collapse can retire the recalled
+ * id while the same text lives on under a newer one, so fall back to the
+ * newest entry with matching text.
+ */
+function findActive(
+  entries: ReadonlyArray<ComposerPromptHistoryEntry>,
+  position: ComposerPromptHistoryPosition,
+): number {
+  const byId = entries.findIndex((entry) => entry.id === position.entryId);
+  if (byId >= 0) return byId;
+  return entries.findLastIndex((entry) => entry.prompt === position.recalled);
+}
+
+export interface ComposerPromptHistoryStep {
+  readonly position: ComposerPromptHistoryPosition | null;
+  readonly prompt: string;
+}
+
+/**
+ * Drop only the review comments appended at send time, which sit at the
+ * end. Cuts the original string at the start of the trailing run of blocks
+ * so any review comment block the user typed earlier stays byte-for-byte.
+ */
+function stripTrailingReviewComments(prompt: string): string {
+  let cut = prompt.length;
+  for (const match of [...prompt.matchAll(REVIEW_COMMENT_BLOCK_PATTERN)].toReversed()) {
+    const blockEnd = match.index + match[0].length;
+    if (prompt.slice(blockEnd, cut).trim().length > 0) break;
+    cut = match.index;
+  }
+  return cut === prompt.length ? prompt : prompt.slice(0, cut).trimEnd();
+}
+
+/**
+ * Inline terminal chips are sent as `@terminal-1:12-13` labels in the text
+ * with their content in the trailing block. Once the block is stripped the
+ * label points at nothing, so remove it too. Each block entry removes one
+ * label (the first match) and the single space beside it. Nothing else in
+ * the prompt is touched, so indented code and typed labels survive. Block
+ * headers look like `Terminal 1 lines 12-13`.
+ */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function stripInlineTerminalLabels(prompt: string, headers: ReadonlyArray<string>): string {
+  let result = prompt;
+  for (const header of headers) {
+    const match = /^(.+?) lines? (\d+(?:-\d+)?)$/.exec(header);
+    if (!match) continue;
+    const label = `@${match[1]!.trim().toLowerCase().replace(/\s+/g, "-")}:${match[2]}`;
+    // Whole label only: `@terminal-1:4` must not match inside `@terminal-1:40`
+    // or `@terminal-1:4-12`.
+    const labelPattern = new RegExp(`${escapeRegExp(label)}(?![\\d-])`);
+    const index = result.search(labelPattern);
+    if (index < 0) continue;
+    let end = index + label.length;
+    let start = index;
+    if (result[end] === " ") end += 1;
+    else if (result[start - 1] === " ") start -= 1;
+    result = result.slice(0, start) + result.slice(end);
+  }
+  return result;
+}
+
+/**
+ * Reduce a sent message to the text the user typed. Send-time appends
+ * (terminal and element context blocks, preview annotations, review
+ * comments, the Claude ultrathink prefix) are stripped so a recalled prompt
+ * never carries stale context from another turn.
+ */
+export function recallableComposerPrompt(messageText: string): string {
+  let prompt = messageText.trim();
+  if (prompt.startsWith(CLAUDE_ULTRATHINK_PREFIX)) {
+    prompt = prompt.slice(CLAUDE_ULTRATHINK_PREFIX.length);
+  }
+
+  while (prompt.length > 0) {
+    const withoutReviewComments = stripTrailingReviewComments(prompt);
+    if (withoutReviewComments !== prompt) {
+      prompt = withoutReviewComments;
+      continue;
+    }
+    const previewAnnotation = extractTrailingPreviewAnnotation(prompt);
+    if (previewAnnotation.annotation) {
+      prompt = previewAnnotation.promptText;
+      continue;
+    }
+    const elementContexts = extractTrailingElementContexts(prompt);
+    if (elementContexts.contextCount > 0) {
+      prompt = elementContexts.promptText;
+      continue;
+    }
+    const terminalContexts = extractTrailingTerminalContexts(prompt);
+    if (terminalContexts.contextCount > 0) {
+      prompt = stripInlineTerminalLabels(
+        terminalContexts.promptText,
+        terminalContexts.contexts.map((context) => context.header),
+      );
+      continue;
+    }
+    break;
+  }
+
+  // App-composed sends are not text the user typed, so they are not history.
+  const trimmed = prompt.trim();
+  if (
+    trimmed === ATTACHMENT_ONLY_BOOTSTRAP_PROMPT ||
+    trimmed.startsWith(PLAN_IMPLEMENTATION_PROMPT_PREFIX)
+  ) {
+    return "";
+  }
+  return trimmed;
+}
+
+/**
+ * Oldest first. Consecutive identical prompts collapse into the newest one,
+ * matching shell `HISTCONTROL=ignoredups`. Image-only sends have no text and
+ * are skipped.
+ */
+export function buildComposerPromptHistoryEntries(
+  messages: ReadonlyArray<ComposerPromptHistoryMessage>,
+): ComposerPromptHistoryEntry[] {
+  const entries: ComposerPromptHistoryEntry[] = [];
+  for (const message of messages) {
+    if (message.role !== "user") continue;
+    const prompt = recallableComposerPrompt(message.text);
+    if (prompt.length === 0) continue;
+    const previous = entries[entries.length - 1];
+    if (previous && previous.prompt === prompt) {
+      entries[entries.length - 1] = { id: message.id, prompt };
+      continue;
+    }
+    entries.push({ id: message.id, prompt });
+  }
+  return entries;
+}
+
+/**
+ * Returns null when the key should fall through to normal caret movement.
+ * Backward starts only from an empty composer and stops at the oldest entry.
+ * Forward past the newest entry empties the composer and ends browsing. An
+ * edited or sent recall no longer matches `recalled`, so browsing restarts
+ * from scratch on the next backward step.
+ */
+export function stepComposerPromptHistory(input: {
+  readonly direction: "backward" | "forward";
+  readonly entries: ReadonlyArray<ComposerPromptHistoryEntry>;
+  readonly position: ComposerPromptHistoryPosition | null;
+  readonly currentPrompt: string;
+}): ComposerPromptHistoryStep | null {
+  const { entries, position, currentPrompt } = input;
+  const activeIndex =
+    position && position.recalled === currentPrompt ? findActive(entries, position) : -1;
+
+  if (input.direction === "backward") {
+    if (activeIndex < 0 && currentPrompt.length > 0) return null;
+    const entry = entries[activeIndex < 0 ? entries.length - 1 : activeIndex - 1];
+    if (!entry) return null;
+    return { position: { entryId: entry.id, recalled: entry.prompt }, prompt: entry.prompt };
+  }
+
+  if (activeIndex < 0) return null;
+  const entry = entries[activeIndex + 1];
+  if (!entry) return { position: null, prompt: "" };
+  return { position: { entryId: entry.id, recalled: entry.prompt }, prompt: entry.prompt };
+}
diff --git a/apps/web/src/components/chat/useComposerFocusState.test.tsx b/apps/web/src/components/chat/useComposerFocusState.test.tsx
new file mode 100644
index 000000000000..e4bf38430e85
--- /dev/null
+++ b/apps/web/src/components/chat/useComposerFocusState.test.tsx
@@ -0,0 +1,87 @@
+import { act, useLayoutEffect } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { shouldUseRestingComposerLayout } from "../composerFooterLayout";
+import { useComposerFocusState } from "./useComposerFocusState";
+
+let root: Root;
+let composer: ReturnType<typeof useComposerFocusState>;
+let isResting: boolean;
+
+function ComposerProbe({ isMobileViewport = false }: { isMobileViewport?: boolean }) {
+  const state = useComposerFocusState(isMobileViewport);
+  useLayoutEffect(() => {
+    composer = state;
+    isResting = shouldUseRestingComposerLayout({
+      isExistingThread: true,
+      isMobileViewport,
+      isFocused: state.isComposerFocused,
+      isScrollCollapsed: state.isComposerScrollCollapsed,
+      hasExpandedChrome: false,
+      collapseOnBlur: true,
+    });
+  });
+  return null;
+}
+
+beforeEach(async () => {
+  // The probe has no DOM output, but ReactDOM needs an event target.
+  const document = {
+    nodeType: 9,
+    addEventListener() {},
+    removeEventListener() {},
+  };
+  const container = {
+    nodeType: 1,
+    tagName: "DIV",
+    namespaceURI: "http://www.w3.org/1999/xhtml",
+    ownerDocument: document,
+    addEventListener() {},
+    removeEventListener() {},
+  };
+  vi.stubGlobal("document", document);
+  vi.stubGlobal("window", { document, HTMLIFrameElement: EventTarget });
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  root = createRoot(container as unknown as HTMLElement);
+  await act(() => root.render(<ComposerProbe />));
+});
+
+afterEach(async () => {
+  await act(() => root.unmount());
+  vi.unstubAllGlobals();
+});
+
+describe("composer focus state", () => {
+  it("expands at the timeline end after a tool call takes focus", async () => {
+    await act(() => composer.setIsComposerFocused(true));
+    expect(isResting).toBe(false);
+
+    // A tool disclosure takes focus before the user scrolls through its output.
+    await act(() => composer.setIsComposerFocused(false));
+    expect(isResting).toBe(true);
+
+    await act(() => composer.restoreAfterTimelineReachedEnd());
+    expect(isResting).toBe(false);
+
+    await act(() => composer.setIsComposerFocused(false));
+    expect(isResting).toBe(true);
+  });
+
+  it("can collapse again on the next scroll after returning to the end", async () => {
+    await act(() => composer.setIsComposerScrollCollapsed(true));
+    expect(isResting).toBe(true);
+
+    await act(() => composer.restoreAfterTimelineReachedEnd());
+    expect(isResting).toBe(false);
+
+    await act(() => composer.setIsComposerScrollCollapsed(true));
+    expect(isResting).toBe(true);
+  });
+
+  it("does not expand the phone composer when the timeline reaches the end", async () => {
+    await act(() => root.render(<ComposerProbe isMobileViewport />));
+    await act(() => composer.restoreAfterTimelineReachedEnd());
+    expect(composer.isComposerFocused).toBe(false);
+  });
+});
diff --git a/apps/web/src/components/chat/useComposerFocusState.ts b/apps/web/src/components/chat/useComposerFocusState.ts
new file mode 100644
index 000000000000..c8858b33fa6b
--- /dev/null
+++ b/apps/web/src/components/chat/useComposerFocusState.ts
@@ -0,0 +1,23 @@
+import { useCallback, useState } from "react";
+
+export function useComposerFocusState(isMobileViewport: boolean) {
+  const [isComposerFocused, setIsComposerFocused] = useState(false);
+  const [isComposerScrollCollapsed, setIsComposerScrollCollapsed] = useState(false);
+
+  const restoreAfterTimelineReachedEnd = useCallback(() => {
+    setIsComposerScrollCollapsed(false);
+    // Restore the expanded layout after a timeline control takes focus too.
+    // This state holds the layout open without moving DOM focus to the editor.
+    if (!isMobileViewport) {
+      setIsComposerFocused(true);
+    }
+  }, [isMobileViewport]);
+
+  return {
+    isComposerFocused,
+    setIsComposerFocused,
+    isComposerScrollCollapsed,
+    setIsComposerScrollCollapsed,
+    restoreAfterTimelineReachedEnd,
+  };
+}
diff --git a/apps/web/src/components/cloud/CloudEnvironmentConnectList.test.tsx b/apps/web/src/components/cloud/CloudEnvironmentConnectList.test.tsx
new file mode 100644
index 000000000000..e82135dc44bd
--- /dev/null
+++ b/apps/web/src/components/cloud/CloudEnvironmentConnectList.test.tsx
@@ -0,0 +1,214 @@
+import type { Discovery } from "@t3tools/client-runtime/relay";
+import type { AtomCommandResult } from "@t3tools/client-runtime/state/runtime";
+import { EnvironmentId } from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { AsyncResult } from "effect/unstable/reactivity";
+import { act, type ButtonHTMLAttributes } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+type DiscoveredEnvironments = Discovery.RelayEnvironmentDiscoveryState["environments"];
+
+const discovery = vi.hoisted(() => ({
+  state: null as Discovery.RelayEnvironmentDiscoveryState | null,
+  listeners: new Set<() => void>(),
+  refreshCommand: Symbol("refresh"),
+  registerCommand: Symbol("register"),
+  refresh: vi.fn<() => Promise<AtomCommandResult<void, never>>>(),
+  register: vi.fn(),
+  listEnvironments: vi.fn<() => Promise<DiscoveredEnvironments>>(),
+}));
+
+vi.mock("~/state/relay", () => ({
+  relayEnvironmentDiscovery: { refresh: discovery.refreshCommand },
+}));
+vi.mock("~/connection/catalog", () => ({
+  environmentCatalog: { register: discovery.registerCommand },
+}));
+vi.mock("~/state/use-atom-command", () => ({
+  useAtomCommand: (command: unknown) =>
+    command === discovery.refreshCommand ? discovery.refresh : discovery.register,
+}));
+vi.mock("~/state/environments", async () => {
+  const { useSyncExternalStore } = await import("react");
+  const subscribe = (listener: () => void) => {
+    discovery.listeners.add(listener);
+    return () => discovery.listeners.delete(listener);
+  };
+  const read = () => {
+    if (discovery.state === null) throw new Error("Discovery fixture is not initialized");
+    return discovery.state;
+  };
+  return { useRelayEnvironmentDiscovery: () => useSyncExternalStore(subscribe, read, read) };
+});
+vi.mock("../ConnectionStatusDot", () => ({ ConnectionStatusDot: () => null }));
+vi.mock("../ui/button", () => ({
+  Button: ({ children, ...props }: ButtonHTMLAttributes<HTMLButtonElement>) => (
+    <button {...props}>{children}</button>
+  ),
+}));
+vi.mock("../ui/toast", () => ({ toastManager: { add: vi.fn() } }));
+
+import { CloudEnvironmentConnectRows } from "./CloudEnvironmentConnectList";
+
+const newMachineId = EnvironmentId.make("new-computer");
+const linkedMachines: DiscoveredEnvironments = new Map([
+  [
+    newMachineId,
+    {
+      environment: {
+        environmentId: newMachineId,
+        label: "Work laptop",
+        endpoint: {
+          httpBaseUrl: "https://relay.example.test",
+          wsBaseUrl: "wss://relay.example.test/ws",
+          providerKind: "manual",
+        },
+        linkedAt: "2026-09-05T12:00:00.000Z",
+      },
+      availability: "online",
+      status: Option.none(),
+      error: Option.none(),
+    },
+  ],
+]);
+
+let renderer: ReactTestRenderer | null;
+let page: EventTarget & { visibilityState: DocumentVisibilityState };
+let browserWindow: EventTarget;
+
+function publish(state: Discovery.RelayEnvironmentDiscoveryState) {
+  discovery.state = state;
+  for (const listener of discovery.listeners) listener();
+}
+
+async function mount(refreshWhileEmpty = true) {
+  await act(async () => {
+    renderer = create(
+      <CloudEnvironmentConnectRows
+        primaryEnvironmentId={null}
+        savedEnvironments={[]}
+        showSavedEnvironments
+        refreshWhileEmpty={refreshWhileEmpty}
+        empty={<p>Waiting for your computer to connect.</p>}
+      />,
+    );
+  });
+}
+
+async function advance(milliseconds: number) {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(milliseconds);
+  });
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  page = Object.assign(new EventTarget(), { visibilityState: "visible" as const });
+  browserWindow = new EventTarget();
+  vi.stubGlobal("document", page);
+  vi.stubGlobal("window", browserWindow);
+  renderer = null;
+  discovery.listeners.clear();
+  discovery.state = {
+    environments: new Map(),
+    refreshing: false,
+    offline: false,
+    error: Option.none(),
+  };
+  discovery.listEnvironments.mockReset().mockResolvedValue(new Map());
+  discovery.refresh.mockReset().mockImplementation(async () => {
+    publish({ environments: new Map(), refreshing: true, offline: false, error: Option.none() });
+    const environments = await discovery.listEnvironments();
+    publish({ environments, refreshing: false, offline: false, error: Option.none() });
+    return AsyncResult.success(undefined);
+  });
+});
+
+afterEach(async () => {
+  await act(async () => renderer?.unmount());
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe("cloud onboarding discovery", () => {
+  it("shows a newly linked computer without remounting and stops polling once found", async () => {
+    discovery.listEnvironments
+      .mockResolvedValueOnce(new Map())
+      .mockResolvedValueOnce(linkedMachines);
+    await mount();
+    expect(renderer!.root.findByType("p").children).toEqual([
+      "Waiting for your computer to connect.",
+    ]);
+
+    await advance(5_000);
+
+    expect(renderer!.root.findAllByType("p").map((node) => node.children)).toContainEqual([
+      "Work laptop",
+    ]);
+    expect(renderer!.root.findByType("button").children).toEqual(["Connect"]);
+    await advance(30_000);
+    expect(discovery.listEnvironments).toHaveBeenCalledTimes(2);
+  });
+
+  it("waits while hidden and refreshes immediately when visible again", async () => {
+    page.visibilityState = "hidden";
+    await mount();
+    await advance(30_000);
+    expect(discovery.listEnvironments).not.toHaveBeenCalled();
+
+    await act(async () => {
+      page.visibilityState = "visible";
+      page.dispatchEvent(new Event("visibilitychange"));
+    });
+    expect(discovery.listEnvironments).toHaveBeenCalledTimes(1);
+
+    page.visibilityState = "hidden";
+    page.dispatchEvent(new Event("visibilitychange"));
+    browserWindow.dispatchEvent(new Event("focus"));
+    await advance(30_000);
+    expect(discovery.listEnvironments).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not overlap a slow refresh or restart polling after unmount", async () => {
+    let resolveRefresh!: (environments: DiscoveredEnvironments) => void;
+    const pending = new Promise<DiscoveredEnvironments>((resolve) => {
+      resolveRefresh = resolve;
+    });
+    discovery.listEnvironments.mockResolvedValueOnce(new Map()).mockReturnValueOnce(pending);
+    await mount();
+    await advance(5_000);
+    expect(renderer!.root.findByType("p").children).toEqual([
+      "Waiting for your computer to connect.",
+    ]);
+
+    browserWindow.dispatchEvent(new Event("focus"));
+    page.dispatchEvent(new Event("visibilitychange"));
+    await advance(30_000);
+    expect(discovery.listEnvironments).toHaveBeenCalledTimes(2);
+
+    await act(async () => renderer!.unmount());
+    renderer = null;
+    await act(async () => resolveRefresh(new Map()));
+    await advance(30_000);
+    expect(discovery.listEnvironments).toHaveBeenCalledTimes(2);
+  });
+
+  it("pauses while offline and resumes when discovery is online", async () => {
+    await mount();
+    await act(async () => publish({ ...discovery.state!, offline: true }));
+    await advance(30_000);
+    expect(discovery.listEnvironments).toHaveBeenCalledTimes(1);
+
+    await act(async () => publish({ ...discovery.state!, offline: false }));
+    await advance(5_000);
+    expect(discovery.listEnvironments).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not add polling to other cloud lists", async () => {
+    await mount(false);
+    await advance(30_000);
+    expect(discovery.listEnvironments).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/apps/web/src/components/cloud/CloudEnvironmentConnectList.tsx b/apps/web/src/components/cloud/CloudEnvironmentConnectList.tsx
index 460a253812a0..7f29c69c3208 100644
--- a/apps/web/src/components/cloud/CloudEnvironmentConnectList.tsx
+++ b/apps/web/src/components/cloud/CloudEnvironmentConnectList.tsx
@@ -11,7 +11,7 @@ import {
 import type { EnvironmentId } from "@t3tools/contracts";
 import type { RelayClientEnvironmentRecord } from "@t3tools/contracts/relay";
 import * as Option from "effect/Option";
-import { type ReactNode, useCallback, useEffect, useState } from "react";
+import { type ReactNode, useCallback, useEffect, useEffectEvent, useState } from "react";
 
 import { environmentCatalog } from "~/connection/catalog";
 import { cn } from "~/lib/utils";
@@ -25,6 +25,8 @@ import { Skeleton } from "../ui/skeleton";
 import { toastManager } from "../ui/toast";
 import { presentSavedCloudEnvironmentConnection } from "./cloudEnvironmentConnectionPresentation";
 
+const EMPTY_DISCOVERY_REFRESH_INTERVAL_MS = 5_000;
+
 export interface SavedCloudEnvironmentConnection {
   readonly environmentId: EnvironmentId;
   readonly connection: EnvironmentConnectionPresentation;
@@ -55,11 +57,13 @@ export function CloudEnvironmentConnectRows({
   primaryEnvironmentId,
   savedEnvironments,
   showSavedEnvironments = false,
+  refreshWhileEmpty = false,
   empty = null,
 }: {
   readonly primaryEnvironmentId: EnvironmentId | null;
   readonly savedEnvironments: ReadonlyArray<SavedCloudEnvironmentConnection>;
   readonly showSavedEnvironments?: boolean;
+  readonly refreshWhileEmpty?: boolean;
   readonly empty?: ReactNode;
 }) {
   const environmentsState = useRelayEnvironmentDiscovery();
@@ -69,6 +73,10 @@ export function CloudEnvironmentConnectRows({
   const refreshRelayEnvironments = useAtomCommand(relayEnvironmentDiscovery.refresh, {
     reportFailure: false,
   });
+  const refreshDiscoveryWhenIdle = useEffectEvent(async () => {
+    if (environmentsState.refreshing || environmentsState.offline) return;
+    await refreshRelayEnvironments();
+  });
   const connectRelayEnvironment = useCallback(
     (environment: RelayClientEnvironmentRecord) =>
       registerEnvironment(
@@ -89,8 +97,10 @@ export function CloudEnvironmentConnectRows({
   );
 
   useEffect(() => {
-    void refreshRelayEnvironments();
-  }, [refreshRelayEnvironments]);
+    if (!refreshWhileEmpty || document.visibilityState === "visible") {
+      void refreshRelayEnvironments();
+    }
+  }, [refreshRelayEnvironments, refreshWhileEmpty]);
 
   const connectEnvironment = async (environment: RelayClientEnvironmentRecord) => {
     setConnectingEnvironmentId(environment.environmentId);
@@ -132,10 +142,54 @@ export function CloudEnvironmentConnectRows({
       environment.environmentId !== primaryEnvironmentId &&
       (showSavedEnvironments || !savedById.has(environment.environmentId)),
   );
+  // Discovery clears its list on refresh, so poll only until a machine appears.
+  const shouldRefreshWhileEmpty =
+    refreshWhileEmpty && visibleEnvironments.length === 0 && !environmentsState.offline;
+
+  useEffect(() => {
+    if (!shouldRefreshWhileEmpty) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let disposed = false;
+    let pending = false;
+    const visible = () => document.visibilityState === "visible";
+    const schedule = () => {
+      clearTimeout(timer);
+      if (!disposed && visible()) {
+        timer = setTimeout(() => void refresh(), EMPTY_DISCOVERY_REFRESH_INTERVAL_MS);
+      }
+    };
+    const refresh = async () => {
+      if (disposed || pending || !visible()) return;
+      clearTimeout(timer);
+      pending = true;
+      try {
+        await refreshDiscoveryWhenIdle();
+      } finally {
+        pending = false;
+        schedule();
+      }
+    };
+    const onFocus = () => void refresh();
+    const onVisibilityChange = () => {
+      clearTimeout(timer);
+      if (visible()) void refresh();
+    };
+
+    schedule();
+    window.addEventListener("focus", onFocus);
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => {
+      disposed = true;
+      clearTimeout(timer);
+      window.removeEventListener("focus", onFocus);
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+    };
+  }, [shouldRefreshWhileEmpty]);
 
   const standalone = showSavedEnvironments || savedEnvironments.length === 0;
 
   if (
+    !refreshWhileEmpty &&
     standalone &&
     visibleEnvironments.length === 0 &&
     environmentsState.refreshing &&
diff --git a/apps/web/src/components/color-selector.tsx b/apps/web/src/components/color-selector.tsx
deleted file mode 100644
index d6898b009eeb..000000000000
--- a/apps/web/src/components/color-selector.tsx
+++ /dev/null
@@ -1,101 +0,0 @@
-"use client";
-
-import { useState } from "react";
-import { cn } from "~/lib/utils";
-
-interface ColorSelectorProps {
-  colors: string[];
-  size?: "default" | "sm" | "lg";
-  defaultValue: string;
-  name?: string;
-  onColorSelect?: (color: string) => void;
-  className?: string;
-}
-
-const colorMap = {
-  default: "var(--contrast-foreground)",
-  red: "var(--color-red-500)",
-  green: "var(--color-green-500)",
-  blue: "var(--color-blue-500)",
-  yellow: "var(--color-yellow-500)",
-  purple: "var(--color-purple-500)",
-  pink: "var(--color-pink-500)",
-  indigo: "var(--color-indigo-500)",
-  orange: "var(--color-orange-500)",
-  teal: "var(--color-teal-500)",
-  cyan: "var(--color-cyan-500)",
-  lime: "var(--color-lime-500)",
-  emerald: "var(--color-emerald-500)",
-  violet: "var(--color-violet-500)",
-  fuchsia: "var(--color-fuchsia-500)",
-  rose: "var(--color-rose-500)",
-  sky: "var(--color-sky-500)",
-  amber: "var(--color-amber-500)",
-} as const;
-
-function getSizeClass(size: "default" | "sm" | "lg") {
-  switch (size) {
-    case "sm":
-      return "size-4";
-    case "default":
-      return "size-5";
-    case "lg":
-      return "size-6";
-    default:
-      return "size-5";
-  }
-}
-
-function getColorValue(color: string): string {
-  return colorMap[color as keyof typeof colorMap] || color;
-}
-
-export function ColorSelector({
-  colors,
-  size = "default",
-  defaultValue,
-  name,
-  onColorSelect,
-  className,
-}: ColorSelectorProps) {
-  const [selectedColor, setSelectedColor] = useState<string>(defaultValue);
-
-  const handleColorSelect = (color: string) => {
-    setSelectedColor(color);
-    onColorSelect?.(color);
-  };
-
-  const sizeClass = getSizeClass(size);
-
-  return (
-    <div className={cn("flex gap-2", className)}>
-      {name && <input type="hidden" name={name} value={selectedColor} />}
-      {colors.map((color) => {
-        const colorValue = getColorValue(color);
-        return (
-          <div
-            key={color}
-            className={`${sizeClass} cursor-pointer rounded-full transition-transform duration-200 active:scale-90`}
-            style={{
-              backgroundColor: colorValue,
-              ...(selectedColor === color && {
-                boxShadow: `inset 0 0 0 2px var(--card), 0 0 0 2px ${colorValue}`,
-              }),
-            }}
-            onClick={() => handleColorSelect(color)}
-            onKeyDown={(e) => {
-              if (e.key === "Enter" || e.key === " ") {
-                e.preventDefault();
-                handleColorSelect(color);
-              }
-            }}
-            tabIndex={0}
-            role="button"
-            aria-label={`Select ${color} color`}
-            aria-pressed={selectedColor === color}
-          />
-        );
-      })}
-    </div>
-  );
-}
diff --git a/apps/web/src/components/desktopUpdate.logic.test.ts b/apps/web/src/components/desktopUpdate.logic.test.ts
index dd05693d28b2..fcc97825b681 100644
--- a/apps/web/src/components/desktopUpdate.logic.test.ts
+++ b/apps/web/src/components/desktopUpdate.logic.test.ts
@@ -12,7 +12,6 @@ import {
   isDesktopUpdateButtonDisabled,
   resolveDesktopUpdateButtonAction,
   shouldShowArm64IntelBuildWarning,
-  shouldShowDesktopUpdateButton,
   shouldToastDesktopUpdateActionResult,
 } from "./desktopUpdate.logic";
 
@@ -42,7 +41,6 @@ describe("desktop update button state", () => {
       status: "available",
       availableVersion: "1.1.0",
     };
-    expect(shouldShowDesktopUpdateButton(state)).toBe(true);
     expect(resolveDesktopUpdateButtonAction(state)).toBe("download");
   });
 
@@ -55,7 +53,6 @@ describe("desktop update button state", () => {
       errorContext: "download",
       canRetry: true,
     };
-    expect(shouldShowDesktopUpdateButton(state)).toBe(true);
     expect(resolveDesktopUpdateButtonAction(state)).toBe("download");
     expect(getDesktopUpdateButtonTooltip(state)).toContain("Click to retry");
   });
@@ -70,7 +67,6 @@ describe("desktop update button state", () => {
       errorContext: "install",
       canRetry: true,
     };
-    expect(shouldShowDesktopUpdateButton(state)).toBe(true);
     expect(resolveDesktopUpdateButtonAction(state)).toBe("install");
     expect(getDesktopUpdateButtonTooltip(state)).toContain("Click to retry");
   });
@@ -85,7 +81,6 @@ describe("desktop update button state", () => {
       errorContext: null,
       canRetry: true,
     };
-    expect(shouldShowDesktopUpdateButton(state)).toBe(true);
     expect(resolveDesktopUpdateButtonAction(state)).toBe("install");
     expect(getDesktopUpdateButtonTooltip(state)).toContain("Click to restart and install");
   });
@@ -111,7 +106,7 @@ describe("desktop update button state", () => {
     expect(resolveDesktopUpdateButtonAction(state)).toBe("none");
   });
 
-  it("hides the button for non-actionable check errors", () => {
+  it("has no action for non-actionable check errors", () => {
     const state: DesktopUpdateState = {
       ...baseState,
       status: "error",
@@ -119,7 +114,6 @@ describe("desktop update button state", () => {
       errorContext: "check",
       canRetry: true,
     };
-    expect(shouldShowDesktopUpdateButton(state)).toBe(false);
     expect(resolveDesktopUpdateButtonAction(state)).toBe("none");
   });
 
@@ -130,7 +124,6 @@ describe("desktop update button state", () => {
       availableVersion: "1.1.0",
       downloadPercent: 42.5,
     };
-    expect(shouldShowDesktopUpdateButton(state)).toBe(true);
     expect(isDesktopUpdateButtonDisabled(state)).toBe(true);
     expect(getDesktopUpdateButtonTooltip(state)).toContain("42%");
   });
diff --git a/apps/web/src/components/desktopUpdate.logic.ts b/apps/web/src/components/desktopUpdate.logic.ts
index 656ffbea8198..4a169cb3ef40 100644
--- a/apps/web/src/components/desktopUpdate.logic.ts
+++ b/apps/web/src/components/desktopUpdate.logic.ts
@@ -47,16 +47,6 @@ export function resolveDesktopUpdateButtonAction(
   return "none";
 }
 
-export function shouldShowDesktopUpdateButton(state: DesktopUpdateState | null): boolean {
-  if (!state || !state.enabled) {
-    return false;
-  }
-  if (state.status === "downloading") {
-    return true;
-  }
-  return resolveDesktopUpdateButtonAction(state) !== "none";
-}
-
 export function shouldShowArm64IntelBuildWarning(state: DesktopUpdateState | null): boolean {
   return state?.hostArch === "arm64" && state.appArch === "x64";
 }
diff --git a/apps/web/src/components/diffs/AnnotatableCodeView.test.tsx b/apps/web/src/components/diffs/AnnotatableCodeView.test.tsx
deleted file mode 100644
index 78d9b436d79c..000000000000
--- a/apps/web/src/components/diffs/AnnotatableCodeView.test.tsx
+++ /dev/null
@@ -1,60 +0,0 @@
-import { renderToStaticMarkup } from "react-dom/server";
-import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
-
-const testState = vi.hoisted(() => ({
-  codeViewOptions: null as Record<string, unknown> | null,
-}));
-
-vi.mock("@pierre/diffs/react", () => ({
-  CodeView: (props: { options: Record<string, unknown> }) => {
-    testState.codeViewOptions = props.options;
-    return null;
-  },
-}));
-
-vi.mock("~/composerDraftStore", () => ({
-  useComposerDraftStore: (selector: (store: Record<string, unknown>) => unknown) =>
-    selector({
-      addReviewComment: vi.fn(),
-      removeReviewComment: vi.fn(),
-      getComposerDraft: () => undefined,
-    }),
-}));
-
-vi.mock("./DiffCommentAnnotation", () => ({
-  DiffCommentAnnotation: () => null,
-}));
-
-vi.mock("../files/fileCommentAnnotations", () => ({
-  nextFileCommentId: () => "comment-test",
-}));
-
-import { AnnotatableCodeView } from "./AnnotatableCodeView";
-
-describe("AnnotatableCodeView", () => {
-  beforeEach(() => {
-    testState.codeViewOptions = null;
-  });
-
-  it("opens comments from Pierre's gutter action without ending line selection", () => {
-    renderToStaticMarkup(
-      <AnnotatableCodeView
-        codeViewKey="test-view"
-        files={[]}
-        sectionId="working-tree"
-        sectionTitle="Working tree"
-        composerDraftTarget={"draft-test" as never}
-        options={{}}
-        renderHeaderPrefix={() => null}
-        renderHeaderFilenameSuffix={() => null}
-      />,
-    );
-
-    expect(testState.codeViewOptions).toMatchObject({
-      enableGutterUtility: true,
-      enableLineSelection: true,
-      onGutterUtilityClick: expect.any(Function),
-    });
-    expect(testState.codeViewOptions).not.toHaveProperty("onLineSelectionEnd");
-  });
-});
diff --git a/apps/web/src/components/diffs/DiffCommentAnnotation.tsx b/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
index d210732b6b60..bce9f7e55f58 100644
--- a/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
+++ b/apps/web/src/components/diffs/DiffCommentAnnotation.tsx
@@ -1,5 +1,5 @@
 import { MessageCircle, Trash2 } from "lucide-react";
-import { useState, type ReactNode } from "react";
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
 
 import { Button } from "~/components/ui/button";
 import { Textarea } from "~/components/ui/textarea";
@@ -25,6 +25,7 @@ interface DiffCommentAnnotationProps {
   submitLabel?: string;
   pending?: boolean;
   secondaryAction?: DiffCommentSecondaryAction;
+  focusOnMount?: boolean;
 }
 
 /** The shared inline comment treatment for file previews, thread diffs, and pull-request diffs. */
@@ -40,10 +41,20 @@ export function DiffCommentAnnotation({
   submitLabel = "Comment",
   pending = false,
   secondaryAction,
+  focusOnMount = true,
 }: DiffCommentAnnotationProps) {
   const [localDraftText, setLocalDraftText] = useState("");
   const displayedText = kind === "draft" && !onTextChange ? localDraftText : text;
   const trimmedText = displayedText.trim();
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+
+  useLayoutEffect(() => {
+    if (kind !== "draft" || !focusOnMount) return;
+    const frame = window.requestAnimationFrame(() => {
+      textareaRef.current?.focus({ preventScroll: true });
+    });
+    return () => window.cancelAnimationFrame(frame);
+  }, [focusOnMount, kind]);
 
   if (kind === "comment") {
     return (
@@ -78,9 +89,10 @@ export function DiffCommentAnnotation({
       onPointerDown={(event) => event.stopPropagation()}
     >
       <Textarea
-        autoFocus
+        ref={textareaRef}
+        autoFocus={focusOnMount}
         unstyled
-        className="relative inline-flex w-full rounded-md border border-border/50 bg-background/20 font-sans text-foreground transition-colors focus-within:border-border/70 [&_[data-slot=textarea]]:min-h-12 [&_[data-slot=textarea]]:cursor-text [&_[data-slot=textarea]]:px-2.5 [&_[data-slot=textarea]]:py-1.5 [&_[data-slot=textarea]]:font-sans [&_[data-slot=textarea]]:text-xs [&_[data-slot=textarea]]:leading-5 max-sm:[&_[data-slot=textarea]]:min-h-12"
+        className="relative inline-flex w-full rounded-md border border-border/50 bg-background/20 font-sans text-foreground transition-colors focus-within:border-border/70 [&_[data-slot=textarea]]:min-h-12 [&_[data-slot=textarea]]:cursor-text [&_[data-slot=textarea]]:caret-foreground [&_[data-slot=textarea]]:px-2.5 [&_[data-slot=textarea]]:py-1.5 [&_[data-slot=textarea]]:font-sans [&_[data-slot=textarea]]:text-xs [&_[data-slot=textarea]]:leading-5 max-sm:[&_[data-slot=textarea]]:min-h-12"
         size="sm"
         value={displayedText}
         placeholder={placeholder}
diff --git a/apps/web/src/components/diffs/DiffFileTree.test.tsx b/apps/web/src/components/diffs/DiffFileTree.test.tsx
new file mode 100644
index 000000000000..3a97c60254ab
--- /dev/null
+++ b/apps/web/src/components/diffs/DiffFileTree.test.tsx
@@ -0,0 +1,193 @@
+import type { CodeViewScrollTarget } from "@pierre/diffs";
+import type { FileTree as FileTreeModel } from "@pierre/trees";
+import { FileTree } from "@pierre/trees/react";
+import { act, type MouseEvent, type ReactNode } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { DiffFileTree, type DiffFileTreeEntry } from "./DiffFileTree";
+import { useCodeViewFileReveal } from "./useCodeViewFileReveal";
+
+vi.mock("../../hooks/useTheme", () => ({ useTheme: () => ({ resolvedTheme: "dark" }) }));
+// Tooltip positioning is unrelated to the tree's actual model and activation path.
+vi.mock("../ui/tooltip", () => ({
+  Tooltip: ({ children }: { children: ReactNode }) => children,
+  TooltipTrigger: ({ render }: { render: ReactNode }) => render,
+  TooltipPopup: () => null,
+}));
+
+const entries: DiffFileTreeEntry[] = [
+  { path: "01-tall.ts", status: "modified" },
+  { path: "02-short.ts", status: "modified" },
+  { path: "03-medium.ts", status: "modified" },
+];
+
+class TreeRow {
+  constructor(readonly path: string) {}
+
+  getAttribute(name: string) {
+    return name === "data-item-path" ? this.path : null;
+  }
+}
+
+describe("diff tree file activation", () => {
+  let renderer: ReactTestRenderer | undefined;
+  const targets: CodeViewScrollTarget[] = [];
+  const viewer = {
+    getInstance: () => viewer,
+    scrollTo: (target: CodeViewScrollTarget) => targets.push(target),
+  };
+
+  function Panel({
+    files = entries,
+    selectedPath = null,
+  }: {
+    files?: DiffFileTreeEntry[];
+    selectedPath?: string | null;
+  }) {
+    const reveal = useCodeViewFileReveal(viewer, "working-tree");
+    return (
+      <DiffFileTree
+        entries={files}
+        ariaLabel="Working tree files"
+        selectedPath={selectedPath}
+        onSelectFile={(path) => reveal(`${path}\0${path}`)}
+      />
+    );
+  }
+
+  const model = (): FileTreeModel => renderer!.root.findByType(FileTree).props.model;
+
+  async function mount(props: Parameters<typeof Panel>[0] = {}) {
+    await act(async () => {
+      renderer = create(<Panel {...props} />);
+    });
+  }
+
+  // Exercise T3's capture handler before the real Pierre model's selection transition.
+  // Only DOM hit testing is represented here; native pointer/keyboard dispatch and diff
+  // geometry are verified separately in the integrated client.
+  async function activate(path: string, modifiers: Partial<MouseEvent<HTMLElement>> = {}) {
+    const event = {
+      button: 0,
+      ctrlKey: false,
+      metaKey: false,
+      shiftKey: false,
+      altKey: false,
+      defaultPrevented: false,
+      nativeEvent: { composedPath: () => [{}, new TreeRow(path), {}] },
+      ...modifiers,
+    } as MouseEvent<HTMLElement>;
+    await act(async () => {
+      renderer!.root
+        .find((node) => String(node.type) === "file-tree-container")
+        .props.onClickCapture?.(event);
+      const tree = model();
+      const item = tree.getItem(path)!;
+      if (event.ctrlKey || event.metaKey) {
+        item.toggleSelect();
+      } else {
+        for (const selected of tree.getSelectedPaths()) {
+          if (selected !== path) tree.getItem(selected)?.deselect();
+        }
+        item.select();
+      }
+      item.focus();
+      if ("toggle" in item && !event.ctrlKey && !event.metaKey && !event.shiftKey) item.toggle();
+    });
+  }
+
+  beforeEach(() => {
+    targets.length = 0;
+    vi.useFakeTimers();
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    vi.stubGlobal("HTMLElement", TreeRow);
+  });
+
+  afterEach(async () => {
+    await act(async () => renderer?.unmount());
+    renderer = undefined;
+    vi.runOnlyPendingTimers();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it("reissues the reveal when the sole selected file is activated again", async () => {
+    await mount();
+    await activate("02-short.ts");
+    expect(model().getSelectedPaths()).toEqual(["02-short.ts"]);
+    await activate("02-short.ts");
+    expect(targets).toEqual([
+      { type: "item", id: "02-short.ts\u000002-short.ts", align: "start" },
+      { type: "item", id: "02-short.ts\u000002-short.ts", align: "start" },
+    ]);
+  });
+
+  it("reveals newly selected files once in either direction", async () => {
+    await mount();
+    await activate("02-short.ts");
+    await activate("01-tall.ts");
+    await activate("03-medium.ts");
+    expect(targets.map((target) => ("id" in target ? target.id : null))).toEqual(
+      ["02-short.ts", "01-tall.ts", "03-medium.ts"].map((path) => `${path}\0${path}`),
+    );
+  });
+
+  it("keeps focus-only navigation separate from button activation", async () => {
+    await mount();
+    await activate("02-short.ts");
+    await act(async () => model().getItem("01-tall.ts")!.focus());
+    expect(model().getSelectedPaths()).toEqual(["02-short.ts"]);
+    expect(targets).toHaveLength(1);
+    await activate("01-tall.ts", { detail: 0 });
+    await activate("01-tall.ts", { detail: 0 });
+    expect(targets).toHaveLength(3);
+  });
+
+  it.each(["ctrlKey", "metaKey"] as const)(
+    "does not reveal a selected file that a %s click deselects",
+    async (modifier) => {
+      await mount();
+      await activate("02-short.ts");
+      await activate("02-short.ts", { [modifier]: true });
+      expect(model().getSelectedPaths()).toEqual([]);
+      expect(targets).toHaveLength(1);
+    },
+  );
+
+  it("lets a click narrow multiple selected files without a second reveal", async () => {
+    await mount();
+    await activate("02-short.ts");
+    await act(async () => model().getItem("01-tall.ts")!.select());
+    expect(model().getSelectedPaths()).toHaveLength(2);
+    targets.length = 0;
+    await activate("02-short.ts");
+    expect(model().getSelectedPaths()).toEqual(["02-short.ts"]);
+    expect(targets).toHaveLength(1);
+  });
+
+  it("leaves directory selection and expansion to the tree", async () => {
+    await mount({ files: [{ path: "src/app.ts", status: "modified" }] });
+    const directory = model().getItem("src/")!;
+    if (!("isExpanded" in directory)) throw new Error("Expected the directory handle");
+    expect(directory.isExpanded()).toBe(true);
+    await activate("src/");
+    expect(directory.isExpanded()).toBe(false);
+    await activate("src/");
+    expect(directory.isExpanded()).toBe(true);
+    expect(targets).toEqual([]);
+  });
+
+  it("does not echo controlled selection, but lets the reader activate it", async () => {
+    await mount({ selectedPath: "02-short.ts" });
+    expect(model().getSelectedPaths()).toEqual(["02-short.ts"]);
+    expect(targets).toEqual([]);
+    await activate("02-short.ts");
+    expect(targets).toHaveLength(1);
+    await act(async () => {
+      renderer!.update(<Panel selectedPath="03-medium.ts" />);
+    });
+    expect(model().getSelectedPaths()).toEqual(["03-medium.ts"]);
+    expect(targets).toHaveLength(1);
+  });
+});
diff --git a/apps/web/src/components/diffs/DiffFileTree.tsx b/apps/web/src/components/diffs/DiffFileTree.tsx
index 3715b62ca15a..0d200853bcb4 100644
--- a/apps/web/src/components/diffs/DiffFileTree.tsx
+++ b/apps/web/src/components/diffs/DiffFileTree.tsx
@@ -177,6 +177,29 @@ export function DiffFileTree({
       <FileTree
         model={model}
         aria-label={ariaLabel}
+        onClickCapture={(event) => {
+          if (
+            event.defaultPrevented ||
+            event.button !== 0 ||
+            event.ctrlKey ||
+            event.metaKey ||
+            event.shiftKey ||
+            event.altKey
+          ) {
+            return;
+          }
+          // Pierre does not emit a selection change for its sole selected row.
+          // Read selection before the row handles the click so new selections reveal only once.
+          const selected = model.getSelectedPaths();
+          const path = selected.length === 1 ? selected[0] : undefined;
+          if (!path || !filePathsRef.current.has(path)) return;
+          const clickedSelectedRow = event.nativeEvent
+            .composedPath()
+            .some(
+              (node) => node instanceof HTMLElement && node.getAttribute("data-item-path") === path,
+            );
+          if (clickedSelectedRow) onSelectFileRef.current(path);
+        }}
         className="min-h-0 flex-1 overflow-hidden"
         style={pierreTreeStyle(resolvedTheme)}
       />
diff --git a/apps/web/src/components/diffs/StyledDiffCodeView.test.tsx b/apps/web/src/components/diffs/StyledDiffCodeView.test.tsx
index f0cd49abc41d..ee249888a415 100644
--- a/apps/web/src/components/diffs/StyledDiffCodeView.test.tsx
+++ b/apps/web/src/components/diffs/StyledDiffCodeView.test.tsx
@@ -1,60 +1,507 @@
-import { renderToStaticMarkup } from "react-dom/server";
-import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import type * as NodeWorkerThreads from "node:worker_threads";
+import {
+  FileRenderer,
+  getSharedHighlighter,
+  type CodeViewScrollTarget,
+  type FileContents,
+} from "@pierre/diffs";
+import { useWorkerPool, type CodeViewProps } from "@pierre/diffs/react";
+import { WorkerPoolManager, type WorkerRequest, type WorkerResponse } from "@pierre/diffs/worker";
+import {
+  act,
+  StrictMode,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type Ref,
+} from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
 
 const testState = vi.hoisted(() => ({
-  codeViewClassName: null as string | null,
-  codeViewOptions: null as Record<string, unknown> | null,
+  workers: [] as NodeWorkerThreads.Worker[],
+  terminations: [] as Promise<number>[],
+  requests: [] as WorkerRequest[],
+  pools: new Map<WorkerPoolManager, Promise<void>>(),
+  renderPools: [] as (WorkerPoolManager | undefined)[],
+  failWorkers: false,
+  holdInitialization: false,
+  heldResponses: [] as (() => void)[],
+  onInitializationHeld: undefined as (() => void) | undefined,
 }));
 
-vi.mock("@pierre/diffs/react", () => ({
-  CodeView: (props: { className: string; options: Record<string, unknown> }) => {
-    testState.codeViewClassName = props.className;
-    testState.codeViewOptions = props.options;
-    return null;
+vi.mock("../../hooks/useTheme", () => ({ useTheme: () => ({ resolvedTheme: "dark" }) }));
+
+vi.mock("@pierre/diffs/worker/worker.js?worker", async () => {
+  const { Worker } = await import("node:worker_threads");
+  const moduleUrl = import.meta.resolve("@pierre/diffs/worker/worker.js");
+
+  // Adapt only the transport. Pierre's real worker loads its WASM and produces every response.
+  return {
+    default: class {
+      worker: NodeWorkerThreads.Worker;
+
+      constructor() {
+        if (testState.failWorkers) throw new Error("Worker creation failed");
+        this.worker = new Worker(
+          `const { parentPort, workerData } = require("node:worker_threads");
+           globalThis.self = {
+             addEventListener(type, listener) {
+               if (type === "message") parentPort.on("message", data => listener({ data }));
+               if (type === "error") process.on("uncaughtException", listener);
+             }
+           };
+           globalThis.postMessage = data => parentPort.postMessage(data);
+           import(workerData.moduleUrl);`,
+          { eval: true, workerData: { moduleUrl }, execArgv: [] },
+        );
+        testState.workers.push(this.worker);
+      }
+
+      addEventListener(
+        type: "message" | "error",
+        listener: (event: { data: WorkerResponse } | Error) => void,
+      ) {
+        if (type === "error") {
+          this.worker.on("error", listener);
+          return;
+        }
+        this.worker.on("message", (data: WorkerResponse) => {
+          const deliver = () => listener({ data });
+          if (
+            testState.holdInitialization &&
+            data.type === "success" &&
+            data.requestType === "initialize"
+          ) {
+            testState.heldResponses.push(deliver);
+            if (testState.heldResponses.length === 2) testState.onInitializationHeld?.();
+          } else {
+            deliver();
+          }
+        });
+      }
+
+      postMessage(message: WorkerRequest) {
+        testState.requests.push(message);
+        this.worker.postMessage(message, []);
+      }
+
+      terminate() {
+        testState.terminations.push(this.worker.terminate());
+      }
+    },
+  };
+});
+
+vi.mock("@pierre/diffs/react", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@pierre/diffs/react")>()),
+  CodeView: (props: CodeViewProps) => {
+    return props.items?.map((item) =>
+      item.type === "file" ? <FileOutput key={item.id} file={item.file} /> : null,
+    );
   },
 }));
 
 import { StyledDiffCodeView } from "./StyledDiffCodeView";
+import { useCodeViewFileReveal } from "./useCodeViewFileReveal";
 
-describe("StyledDiffCodeView", () => {
-  beforeEach(() => {
-    testState.codeViewClassName = null;
-    testState.codeViewOptions = null;
-  });
-
-  it("always pairs the shared diff styling with its virtualized geometry", () => {
-    const loadDiffFiles = vi.fn(async () => ({
-      oldFile: { name: "before.ts", contents: "before\n" },
-      newFile: { name: "after.ts", contents: "after\n" },
-    }));
-    renderToStaticMarkup(
-      <StyledDiffCodeView
-        className="min-h-0"
-        items={[]}
-        options={{ theme: "pierre-dark", stickyHeaders: true, loadDiffFiles }}
-      />,
+function FileOutput({ file }: { file: FileContents }) {
+  const pool = useWorkerPool();
+  const [html, setHtml] = useState("");
+  useEffect(() => {
+    testState.renderPools.push(pool);
+    const renderer = new FileRenderer(
+      { theme: "pierre-dark", preferredHighlighter: "shiki-wasm" },
+      render,
+      pool,
     );
+    function render() {
+      const result = renderer.renderFile(file);
+      if (result) setHtml(renderer.renderFullHTML(result));
+    }
+    render();
+    return () => renderer.cleanUp();
+  }, [file, pool]);
+  return <pre data-code-file={file.name}>{html}</pre>;
+}
 
-    expect(testState.codeViewClassName).toBe(
-      "diff-render-surface [--code-background:var(--background)] outline-none min-h-0",
+const files = [
+  { name: "notes.txt", contents: "Plain text is ready.\n", cacheKey: "plain-text" },
+  { name: "answer.ts", contents: "const answer = 42;\n", cacheKey: "typescript" },
+] satisfies FileContents[];
+
+function Views({ count }: { count: number }) {
+  const [draft, setDraft] = useState("Draft");
+  return (
+    <>
+      <button onClick={() => setDraft("Edited draft")}>{draft}</button>
+      {files.slice(0, count).map((file) => (
+        <StyledDiffCodeView key={file.name} items={[{ type: "file", id: file.name, file }]} />
+      ))}
+    </>
+  );
+}
+
+function renderViews(count: number) {
+  return (
+    <StrictMode>
+      <Views count={count} />
+    </StrictMode>
+  );
+}
+
+describe("code-view worker lifecycle", () => {
+  let renderer: ReactTestRenderer | undefined;
+
+  beforeEach(() => {
+    testState.workers = [];
+    testState.terminations = [];
+    testState.requests = [];
+    testState.pools.clear();
+    testState.renderPools = [];
+    testState.failWorkers = false;
+    testState.holdInitialization = false;
+    testState.heldResponses = [];
+    testState.onInitializationHeld = undefined;
+    vi.stubGlobal("window", {});
+    vi.stubGlobal("navigator", { hardwareConcurrency: 2 });
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout"] });
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) =>
+      setImmediate(() => callback(0)),
     );
-    expect(testState.codeViewOptions).toMatchObject({
-      theme: "pierre-dark",
-      stickyHeaders: true,
-      loadDiffFiles,
-      itemMetrics: {
-        diffHeaderHeight: 32,
-        hunkSeparatorHeight: 24,
-        paddingTop: 0,
-        paddingBottom: 8,
-      },
-      layout: { paddingTop: 0, paddingBottom: 0, gap: 0 },
+    vi.stubGlobal("cancelAnimationFrame", clearImmediate);
+    const initialize = WorkerPoolManager.prototype.initialize;
+    vi.spyOn(WorkerPoolManager.prototype, "initialize").mockImplementation(function (
+      this: WorkerPoolManager,
+      ...args
+    ) {
+      const pending = initialize.apply(this, args);
+      testState.pools.set(this, pending);
+      return pending;
+    });
+  });
+
+  afterEach(async () => {
+    await act(async () => renderer?.unmount());
+    renderer = undefined;
+    await vi.runOnlyPendingTimersAsync();
+    await Promise.all(testState.terminations);
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("starts on demand, keeps quick reopens warm, and expires the last closed pool", async () => {
+    await act(async () => {
+      renderer = create(renderViews(0));
+    });
+    const mounted = renderer!;
+    const button = mounted.root.findByType("button");
+    expect(testState.workers).toHaveLength(0);
+    expect(testState.pools.size).toBe(0);
+    await act(async () => {
+      (button.props as { onClick(): void }).onClick();
+      mounted.update(renderViews(1));
     });
-    expect(testState.codeViewOptions?.unsafeCSS).toEqual(
-      expect.stringContaining("[data-unmodified-lines]::before"),
+    const pool = [...testState.pools.keys()][0]!;
+    await act(async () => testState.pools.get(pool));
+    expect(pool.isInitialized()).toBe(true);
+    expect(testState.workers).toHaveLength(2);
+    expect(mounted.root.findByProps({ "data-code-file": "notes.txt" }).children.join("")).toContain(
+      "Plain text is ready.",
+    );
+    expect(testState.requests.filter((request) => request.type === "file")).toHaveLength(0);
+
+    await act(async () => mounted.update(renderViews(2)));
+    await act(async () => pool.primeFileHighlightCache(files[1]!));
+    expect(testState.pools.size).toBe(1);
+    expect(testState.workers).toHaveLength(2);
+    expect(new Set(testState.renderPools)).toEqual(new Set([pool]));
+    expect(pool.getFileResultCache(files[1]!)).toBeDefined();
+    expect(mounted.root.findByProps({ "data-code-file": "answer.ts" }).children.join("")).toContain(
+      "answer",
     );
-    expect(testState.codeViewOptions?.unsafeCSS).toEqual(
-      expect.stringContaining(")[data-expand-index]\n  [data-unmodified-lines]"),
+
+    await act(async () => mounted.update(renderViews(1)));
+    expect(pool.getStats().totalWorkers).toBe(2);
+    expect(testState.terminations).toHaveLength(0);
+    await act(async () => mounted.update(renderViews(0)));
+    await vi.advanceTimersByTimeAsync(29_999);
+    expect(pool.getStats().totalWorkers).toBe(2);
+    expect(testState.terminations).toHaveLength(0);
+
+    await act(async () => mounted.update(renderViews(1)));
+    expect(testState.pools.size).toBe(1);
+    expect(testState.workers).toHaveLength(2);
+    expect(mounted.root.findAllByProps({ role: "status" })).toHaveLength(0);
+    expect(pool.getFileResultCache(files[1]!)).toBeDefined();
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(pool.getStats().totalWorkers).toBe(2);
+
+    await act(async () => mounted.update(renderViews(0)));
+    await vi.advanceTimersByTimeAsync(30_000);
+    await Promise.all(testState.terminations);
+    expect(pool.getStats().totalWorkers).toBe(0);
+    expect(testState.terminations).toHaveLength(2);
+
+    await act(async () => mounted.update(renderViews(1)));
+    const reopenedPool = [...testState.pools.keys()][1]!;
+    await act(async () => testState.pools.get(reopenedPool));
+    expect(reopenedPool.isInitialized()).toBe(true);
+    expect(testState.workers).toHaveLength(4);
+    expect(mounted.root.findByType("button")).toBe(button);
+    expect(button.children).toEqual(["Edited draft"]);
+    expect(mounted.root.findByProps({ "data-code-file": "notes.txt" }).children.join("")).toContain(
+      "Plain text is ready.",
     );
   });
+
+  it("renders through Pierre's main-thread fallback when worker creation fails", async () => {
+    testState.failWorkers = true;
+    await act(async () => {
+      renderer = create(renderViews(1));
+    });
+    const pool = [...testState.pools.keys()][0]!;
+    await act(async () => {
+      await expect(testState.pools.get(pool)).rejects.toMatchObject({ _tag: "DiffWorkerError" });
+      await getSharedHighlighter({
+        themes: ["pierre-dark"],
+        langs: ["text"],
+        preferredHighlighter: "shiki-wasm",
+      });
+    });
+    expect(pool.isWorkingPool()).toBe(false);
+    expect(testState.workers).toHaveLength(0);
+    expect(
+      renderer!.root.findByProps({ "data-code-file": "notes.txt" }).children.join(""),
+    ).toContain("Plain text is ready.");
+  });
+
+  it("keeps an initializing pool until its last view closes and ignores late responses", async () => {
+    testState.holdInitialization = true;
+    const held = new Promise<void>((resolve) => {
+      testState.onInitializationHeld = resolve;
+    });
+    await act(async () => {
+      renderer = create(renderViews(2));
+    });
+    const pool = [...testState.pools.keys()][0]!;
+    const pending = testState.pools.get(pool)!;
+    await held;
+    expect(pool.isInitialized()).toBe(false);
+    expect(testState.pools.size).toBe(1);
+    expect(renderer!.root.findAllByProps({ role: "status" })).toHaveLength(2);
+    expect(testState.renderPools).toHaveLength(0);
+
+    await act(async () => renderer!.update(renderViews(1)));
+    expect(pool.getStats().totalWorkers).toBe(2);
+    expect(testState.terminations).toHaveLength(0);
+    await act(async () => renderer!.update(renderViews(0)));
+    await vi.advanceTimersByTimeAsync(30_000);
+    await pending;
+    await Promise.all(testState.terminations);
+    await act(async () => {
+      for (const deliver of testState.heldResponses) deliver();
+    });
+    expect(pool.getStats().totalWorkers).toBe(0);
+    expect(testState.workers).toHaveLength(2);
+    expect(testState.terminations).toHaveLength(2);
+    expect(testState.renderPools).toHaveLength(0);
+    expect(renderer!.root.findAllByType("pre")).toHaveLength(0);
+  });
+});
+
+type RevealHandle = NonNullable<Parameters<typeof useCodeViewFileReveal>[0]>;
+const revealCalls: {
+  scope: string;
+  fileKey: string;
+  mounted: boolean;
+  collapsed: boolean | undefined;
+}[] = [];
+
+function RevealViewer({
+  viewerRef,
+  scope,
+  collapsed,
+}: {
+  viewerRef: Ref<RevealHandle>;
+  scope: string;
+  collapsed: boolean;
+}) {
+  const instance = useRef<{ collapsed: boolean } | undefined>(undefined);
+  useLayoutEffect(() => {
+    instance.current = { collapsed };
+    return () => {
+      instance.current = undefined;
+    };
+  }, [collapsed]);
+  const handle = useMemo(
+    () => ({
+      getInstance: () => instance.current,
+      scrollTo: (target: CodeViewScrollTarget) => {
+        if (target.type !== "item") return;
+        revealCalls.push({
+          scope,
+          fileKey: target.id,
+          mounted: instance.current !== undefined,
+          collapsed: instance.current?.collapsed,
+        });
+      },
+    }),
+    [scope],
+  );
+  useImperativeHandle(viewerRef, () => handle, [handle]);
+  return null;
+}
+
+function RevealViews({
+  scope,
+  visible,
+  selectedFile = null,
+  requestId = 0,
+}: {
+  scope: string;
+  visible: boolean;
+  selectedFile?: string | null;
+  requestId?: number;
+}) {
+  const [viewer, setViewer] = useState<RevealHandle | null>(null);
+  const [collapsed, setCollapsed] = useState(true);
+  const selectedRequest = useMemo(() => ({ selectedFile, requestId }), [requestId, selectedFile]);
+  useEffect(() => {
+    if (!selectedRequest.selectedFile || !viewer?.getInstance()) return;
+    viewer.scrollTo({ type: "item", id: selectedRequest.selectedFile, align: "start" });
+  }, [selectedRequest, viewer]);
+  const revealScope = useMemo(() => ({ scope, selectedRequest }), [scope, selectedRequest]);
+  const requestReveal = useCodeViewFileReveal(viewer, revealScope);
+  return (
+    <>
+      {visible && (
+        <RevealViewer key={scope} viewerRef={setViewer} scope={scope} collapsed={collapsed} />
+      )}
+      <button
+        onClick={() => {
+          setCollapsed(false);
+          requestReveal("tree-file");
+        }}
+      >
+        Reveal file
+      </button>
+    </>
+  );
+}
+
+describe("code-view file reveals", () => {
+  let renderer: ReactTestRenderer | undefined;
+
+  beforeEach(() => {
+    revealCalls.length = 0;
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  });
+
+  afterEach(async () => {
+    await act(async () => renderer?.unmount());
+    renderer = undefined;
+    vi.unstubAllGlobals();
+  });
+
+  it("does not replay a handled tree click or scroll an old handle when a selected file remounts the view", async () => {
+    await act(async () => {
+      renderer = create(<RevealViews scope="first" visible selectedFile="external-a" />);
+    });
+    await act(async () => {
+      (renderer!.root.findByType("button").props as { onClick(): void }).onClick();
+    });
+    expect(revealCalls.at(-1)?.fileKey).toBe("tree-file");
+    revealCalls.length = 0;
+
+    await act(async () => {
+      renderer!.update(
+        <RevealViews scope="second" visible selectedFile="external-b" requestId={1} />,
+      );
+    });
+    expect(revealCalls).toEqual([
+      { scope: "second", fileKey: "external-b", mounted: true, collapsed: false },
+    ]);
+  });
+
+  it("waits for a live viewer and applies each pending tree click only once", async () => {
+    await act(async () => {
+      renderer = create(<RevealViews scope="diff" visible={false} selectedFile="external" />);
+    });
+    await act(async () => {
+      (renderer!.root.findByType("button").props as { onClick(): void }).onClick();
+    });
+    expect(revealCalls).toEqual([]);
+
+    await act(async () => {
+      renderer!.update(<RevealViews scope="diff" visible selectedFile="external" />);
+    });
+    expect(revealCalls.map((call) => call.fileKey)).toEqual(["external", "tree-file"]);
+    revealCalls.length = 0;
+    await act(async () => {
+      renderer!.update(<RevealViews scope="diff" visible={false} selectedFile="external" />);
+    });
+    await act(async () => {
+      renderer!.update(<RevealViews scope="diff" visible selectedFile="external" />);
+    });
+    expect(revealCalls).toEqual([
+      { scope: "diff", fileKey: "external", mounted: true, collapsed: false },
+    ]);
+
+    revealCalls.length = 0;
+    await act(async () => {
+      (renderer!.root.findByType("button").props as { onClick(): void }).onClick();
+      renderer!.update(<RevealViews scope="diff" visible={false} selectedFile="external" />);
+    });
+    expect(revealCalls).toEqual([]);
+    await act(async () => {
+      renderer!.update(<RevealViews scope="diff" visible selectedFile="external" />);
+    });
+    expect(revealCalls).toEqual([
+      { scope: "diff", fileKey: "external", mounted: true, collapsed: false },
+      { scope: "diff", fileKey: "tree-file", mounted: true, collapsed: false },
+    ]);
+  });
+
+  it("cancels pending tree clicks when an external selection or diff scope changes", async () => {
+    await act(async () => {
+      renderer = create(<RevealViews scope="first" visible={false} selectedFile="external-a" />);
+    });
+    await act(async () => {
+      (renderer!.root.findByType("button").props as { onClick(): void }).onClick();
+    });
+    await act(async () => {
+      renderer!.update(
+        <RevealViews scope="first" visible selectedFile="external-b" requestId={1} />,
+      );
+    });
+    expect(revealCalls.map((call) => call.fileKey)).toEqual(["external-b"]);
+    revealCalls.length = 0;
+
+    await act(async () => renderer!.update(<RevealViews scope="first" visible={false} />));
+    await act(async () => {
+      (renderer!.root.findByType("button").props as { onClick(): void }).onClick();
+    });
+    await act(async () => renderer!.update(<RevealViews scope="second" visible={false} />));
+    await act(async () => renderer!.update(<RevealViews scope="first" visible />));
+    expect(revealCalls).toEqual([]);
+  });
+
+  it("reveals after a collapsed file expands and honors another click on the same file", async () => {
+    await act(async () => {
+      renderer = create(<RevealViews scope="diff" visible />);
+    });
+    const reveal = renderer!.root.findByType("button").props as { onClick(): void };
+    await act(async () => reveal.onClick());
+    await act(async () => reveal.onClick());
+    expect(revealCalls).toEqual([
+      { scope: "diff", fileKey: "tree-file", mounted: true, collapsed: false },
+      { scope: "diff", fileKey: "tree-file", mounted: true, collapsed: false },
+    ]);
+  });
 });
diff --git a/apps/web/src/components/diffs/StyledDiffCodeView.tsx b/apps/web/src/components/diffs/StyledDiffCodeView.tsx
index 14939de09820..64bc88aab2fd 100644
--- a/apps/web/src/components/diffs/StyledDiffCodeView.tsx
+++ b/apps/web/src/components/diffs/StyledDiffCodeView.tsx
@@ -10,6 +10,7 @@ import {
 import type { Ref } from "react";
 
 import { DIFF_SURFACE_THEME_UNSAFE_CSS } from "~/lib/diffRendering";
+import { DiffWorkerPoolProvider } from "../DiffWorkerPoolProvider";
 
 const DIFF_VIEW_UNSAFE_CSS = `${DIFF_SURFACE_THEME_UNSAFE_CSS}
 :is(
@@ -285,38 +286,40 @@ export function StyledDiffCodeView<LAnnotation = undefined>({
   ...props
 }: StyledDiffCodeViewProps<LAnnotation>) {
   return (
-    <CodeView<LAnnotation>
-      {...props}
-      {...(viewerRef ? { ref: viewerRef } : {})}
-      // The custom element itself is focusable for keyboard scrolling. Its native outline sits
-      // outside the panel clipping boundary; actual controls inside retain their own indicators.
-      className={
-        className
-          ? `diff-render-surface [--code-background:var(--background)] outline-none ${className}`
-          : "diff-render-surface [--code-background:var(--background)] outline-none"
-      }
-      options={{
-        ...options,
-        unsafeCSS: unsafeCSSExtra
-          ? `${DIFF_VIEW_UNSAFE_CSS}\n${unsafeCSSExtra}`
-          : DIFF_VIEW_UNSAFE_CSS,
-        itemMetrics: {
-          diffHeaderHeight: 32,
-          hunkSeparatorHeight: 24,
-          // Pierre uses its general file spacing as a fallback in expanded-file layout paths.
-          // Keep it zero alongside the explicit paddingTop or expanding the first file can
-          // reintroduce the library's default 8px gap above its header.
-          spacing: 0,
-          paddingTop: 0,
-          // Unlike the gap above, the 8px under a file's last line is painted
-          // unconditionally by Pierre's stylesheet (`--diffs-gap-fallback`), so the metric has
-          // to count it: at zero every expanded file's virtual height ran 8px short of its
-          // rendered height, and the end of the list sat past the reachable scroll range —
-          // one clipped file row per expanded file above it.
-          paddingBottom: 8,
-        },
-        layout: { paddingTop: 0, paddingBottom: 0, gap: 0 },
-      }}
-    />
+    <DiffWorkerPoolProvider>
+      <CodeView<LAnnotation>
+        {...props}
+        {...(viewerRef ? { ref: viewerRef } : {})}
+        // The custom element itself is focusable for keyboard scrolling. Its native outline sits
+        // outside the panel clipping boundary; actual controls inside retain their own indicators.
+        className={
+          className
+            ? `diff-render-surface [--code-background:var(--background)] outline-none ${className}`
+            : "diff-render-surface [--code-background:var(--background)] outline-none"
+        }
+        options={{
+          ...options,
+          unsafeCSS: unsafeCSSExtra
+            ? `${DIFF_VIEW_UNSAFE_CSS}\n${unsafeCSSExtra}`
+            : DIFF_VIEW_UNSAFE_CSS,
+          itemMetrics: {
+            diffHeaderHeight: 32,
+            hunkSeparatorHeight: 24,
+            // Pierre uses its general file spacing as a fallback in expanded-file layout paths.
+            // Keep it zero alongside the explicit paddingTop or expanding the first file can
+            // reintroduce the library's default 8px gap above its header.
+            spacing: 0,
+            paddingTop: 0,
+            // Unlike the gap above, the 8px under a file's last line is painted
+            // unconditionally by Pierre's stylesheet (`--diffs-gap-fallback`), so the metric has
+            // to count it: at zero every expanded file's virtual height ran 8px short of its
+            // rendered height, and the end of the list sat past the reachable scroll range —
+            // one clipped file row per expanded file above it.
+            paddingBottom: 8,
+          },
+          layout: { paddingTop: 0, paddingBottom: 0, gap: 0 },
+        }}
+      />
+    </DiffWorkerPoolProvider>
   );
 }
diff --git a/apps/web/src/components/diffs/useCodeViewFileReveal.ts b/apps/web/src/components/diffs/useCodeViewFileReveal.ts
new file mode 100644
index 000000000000..6107c524c7b1
--- /dev/null
+++ b/apps/web/src/components/diffs/useCodeViewFileReveal.ts
@@ -0,0 +1,28 @@
+import type { CodeViewScrollTarget } from "@pierre/diffs";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+interface FileRevealHandle {
+  getInstance(): object | undefined;
+  scrollTo(target: CodeViewScrollTarget): void;
+}
+
+// Wait for a mounted viewer and expanded rows, then apply each tree click once.
+// Keep scope stable until the diff or external file selection changes.
+export function useCodeViewFileReveal<TScope>(viewer: FileRevealHandle | null, scope: TScope) {
+  const [request, setRequest] = useState<{ fileKey: string; scope: TScope } | null>(null);
+  const handledRequest = useRef<typeof request>(null);
+
+  useEffect(() => {
+    if (request === null || handledRequest.current === request) return;
+    if (request.scope !== scope) {
+      handledRequest.current = request;
+      return;
+    }
+    if (!viewer?.getInstance()) return;
+
+    viewer.scrollTo({ type: "item", id: request.fileKey, align: "start" });
+    handledRequest.current = request;
+  }, [request, scope, viewer]);
+
+  return useCallback((fileKey: string) => setRequest({ fileKey, scope }), [scope]);
+}
diff --git a/apps/web/src/components/files/FilePreviewPanel.tsx b/apps/web/src/components/files/FilePreviewPanel.tsx
index 0ad18434d7e7..33d4d9a4b6cf 100644
--- a/apps/web/src/components/files/FilePreviewPanel.tsx
+++ b/apps/web/src/components/files/FilePreviewPanel.tsx
@@ -12,6 +12,7 @@ import {
 import { VirtualizedFile, type SelectedLineRange } from "@pierre/diffs";
 import { Editor } from "@pierre/diffs/editor";
 import { EditProvider, File, type FileOptions, Virtualizer } from "@pierre/diffs/react";
+import { DiffWorkerPoolProvider } from "../DiffWorkerPoolProvider";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
@@ -46,7 +47,6 @@ import { buildFileReviewComment } from "~/reviewCommentContext";
 import { assetEnvironment } from "~/state/assets";
 import { useEnvironmentHttpBaseUrl, usePrimaryEnvironmentId } from "~/state/environments";
 import { previewEnvironment } from "~/state/preview";
-import { projectEnvironment } from "~/state/projects";
 import { useAtomCommand } from "~/state/use-atom-command";
 import { useAtomQueryRunner } from "~/state/use-atom-query-runner";
 
@@ -71,9 +71,8 @@ import {
   setMarkdownTaskChecked,
   shouldShowFileExplorer,
 } from "./filePreviewMode";
-import { FileSaveCoordinator } from "./fileSaveCoordinator";
+import { useFileSaveCoordinator } from "./useFileSaveCoordinator";
 import {
-  confirmProjectFileQueryData,
   getOptimisticProjectFileQueryData,
   setProjectFileQueryData,
   useProjectFileQuery,
@@ -100,7 +99,6 @@ interface FilePreviewPanelProps {
 const FILE_EXPLORER_STORAGE_KEY = "t3code.fileExplorerOpen";
 const RENDER_MARKDOWN_STORAGE_KEY = "t3code.renderMarkdown";
 const RENDER_BROWSER_FILE_STORAGE_KEY = "t3code.renderBrowserFile";
-const FILE_SAVE_DEBOUNCE_MS = 500;
 const FILE_LINK_REVEAL_ATTRIBUTE = "data-file-link-reveal";
 const FILE_LINK_REVEAL_UNSAFE_CSS = `
   ${DIFF_SURFACE_THEME_UNSAFE_CSS}
@@ -612,37 +610,6 @@ interface FileSelectionOverride {
   range: SelectedLineRange | null;
 }
 
-function useFileSaveCoordinator({
-  environmentId,
-  cwd,
-  relativePath,
-  onPendingChange,
-}: Pick<
-  EditableFileSurfaceProps,
-  "environmentId" | "cwd" | "relativePath" | "onPendingChange"
->): FileSaveCoordinator {
-  const writeFile = useAtomCommand(projectEnvironment.writeFile);
-  const coordinator = useMemo(
-    () =>
-      new FileSaveCoordinator({
-        debounceMs: FILE_SAVE_DEBOUNCE_MS,
-        onPendingChange: (pending) => onPendingChange(relativePath, pending),
-        persist: (nextContents) =>
-          writeFile({
-            environmentId,
-            input: { cwd, relativePath, contents: nextContents },
-          }),
-        onConfirmed: (confirmedContents) => {
-          confirmProjectFileQueryData(environmentId, cwd, relativePath, confirmedContents);
-        },
-      }),
-    [cwd, environmentId, onPendingChange, relativePath, writeFile],
-  );
-
-  useEffect(() => () => coordinator.dispose(), [coordinator]);
-  return coordinator;
-}
-
 function EditableFileSurface({
   environmentId,
   cwd,
@@ -773,42 +740,47 @@ function EditableFileSurface({
     ],
   );
 
-  const beginComment = useCallback((range: SelectedLineRange) => {
-    const { startLine, endLine } = normalizeFileCommentRange(range);
-    const draftEntry: FileCommentAnnotationEntry = {
-      id: nextFileCommentId(),
-      kind: "draft",
-      startLine,
-      endLine,
-      text: "",
-    };
-    setLineAnnotations((current) => {
-      const withoutDraft = current.flatMap((annotation) => {
-        const entries = annotation.metadata.entries.filter((entry) => entry.kind !== "draft");
-        return entries.length > 0 ? [{ ...annotation, metadata: { entries } }] : [];
+  const beginComment = useCallback(
+    (range: SelectedLineRange) => {
+      editor.setSelections([]);
+      editor.blur();
+      const { startLine, endLine } = normalizeFileCommentRange(range);
+      const draftEntry: FileCommentAnnotationEntry = {
+        id: nextFileCommentId(),
+        kind: "draft",
+        startLine,
+        endLine,
+        text: "",
+      };
+      setLineAnnotations((current) => {
+        const withoutDraft = current.flatMap((annotation) => {
+          const entries = annotation.metadata.entries.filter((entry) => entry.kind !== "draft");
+          return entries.length > 0 ? [{ ...annotation, metadata: { entries } }] : [];
+        });
+        const existingIndex = withoutDraft.findIndex(
+          (annotation) => annotation.lineNumber === endLine,
+        );
+        if (existingIndex < 0) {
+          return [
+            ...withoutDraft,
+            {
+              lineNumber: endLine,
+              metadata: { entries: [draftEntry] },
+            },
+          ];
+        }
+        return withoutDraft.map((annotation, index) =>
+          index === existingIndex
+            ? {
+                ...annotation,
+                metadata: { entries: [...annotation.metadata.entries, draftEntry] },
+              }
+            : annotation,
+        );
       });
-      const existingIndex = withoutDraft.findIndex(
-        (annotation) => annotation.lineNumber === endLine,
-      );
-      if (existingIndex < 0) {
-        return [
-          ...withoutDraft,
-          {
-            lineNumber: endLine,
-            metadata: { entries: [draftEntry] },
-          },
-        ];
-      }
-      return withoutDraft.map((annotation, index) =>
-        index === existingIndex
-          ? {
-              ...annotation,
-              metadata: { entries: [...annotation.metadata.entries, draftEntry] },
-            }
-          : annotation,
-      );
-    });
-  }, []);
+    },
+    [editor],
+  );
   const hasOpenCommentForm = lineAnnotations.some((annotation) =>
     annotation.metadata.entries.some((entry) => entry.kind === "draft"),
   );
@@ -1294,7 +1266,11 @@ export default function FilePreviewPanel({
             </div>
           ) : relativePath && file.data ? (
             isMarkdown && renderMarkdown ? (
+              // Markdown reconciles in place across text updates, so a file
+              // switch needs a new key or the previous file's disclosure and
+              // wrap state carries into the next document.
               <RenderedMarkdownSurface
+                key={relativePath}
                 environmentId={environmentId}
                 cwd={cwd}
                 relativePath={relativePath}
@@ -1304,46 +1280,50 @@ export default function FilePreviewPanel({
                 onPendingChange={onPendingChange}
               />
             ) : file.data.truncated || isHostFile ? (
-              <Virtualizer
-                key={`${relativePath}:${resolvedTheme}:${file.data.byteLength}`}
-                className="file-preview-virtualizer min-h-0 flex-1 overflow-auto"
-                config={{
-                  overscrollSize: 600,
-                  intersectionObserverMargin: 1200,
-                }}
-              >
-                <File
-                  file={{
-                    name: relativePath,
-                    contents: file.data.contents,
-                    cacheKey: projectFileCacheKey(cwd, relativePath, file.data.contents),
-                  }}
-                  options={{
-                    disableFileHeader: true,
-                    overflow: wordWrap ? "wrap" : "scroll",
-                    theme: resolveDiffThemeName(resolvedTheme),
-                    preferredHighlighter: PREFERRED_HIGHLIGHTER,
-                    themeType: resolvedTheme,
-                    unsafeCSS: FILE_LINK_REVEAL_UNSAFE_CSS,
-                    onPostRender: onFilePostRender,
+              <DiffWorkerPoolProvider>
+                <Virtualizer
+                  key={`${relativePath}:${resolvedTheme}:${file.data.byteLength}`}
+                  className="file-preview-virtualizer min-h-0 flex-1 overflow-auto"
+                  config={{
+                    overscrollSize: 600,
+                    intersectionObserverMargin: 1200,
                   }}
-                  className="min-h-full"
-                />
-              </Virtualizer>
+                >
+                  <File
+                    file={{
+                      name: relativePath,
+                      contents: file.data.contents,
+                      cacheKey: projectFileCacheKey(cwd, relativePath, file.data.contents),
+                    }}
+                    options={{
+                      disableFileHeader: true,
+                      overflow: wordWrap ? "wrap" : "scroll",
+                      theme: resolveDiffThemeName(resolvedTheme),
+                      preferredHighlighter: PREFERRED_HIGHLIGHTER,
+                      themeType: resolvedTheme,
+                      unsafeCSS: FILE_LINK_REVEAL_UNSAFE_CSS,
+                      onPostRender: onFilePostRender,
+                    }}
+                    className="min-h-full"
+                  />
+                </Virtualizer>
+              </DiffWorkerPoolProvider>
             ) : (
-              <EditableFileSurface
-                key={`${relativePath}:${resolvedTheme}`}
-                environmentId={environmentId}
-                cwd={cwd}
-                relativePath={relativePath}
-                composerDraftTarget={composerDraftTarget}
-                contents={file.data.contents}
-                resolvedTheme={resolvedTheme}
-                revealRequestId={revealRequestId}
-                wordWrap={wordWrap}
-                onPostRender={onFilePostRender}
-                onPendingChange={onPendingChange}
-              />
+              <DiffWorkerPoolProvider>
+                <EditableFileSurface
+                  key={`${relativePath}:${resolvedTheme}`}
+                  environmentId={environmentId}
+                  cwd={cwd}
+                  relativePath={relativePath}
+                  composerDraftTarget={composerDraftTarget}
+                  contents={file.data.contents}
+                  resolvedTheme={resolvedTheme}
+                  revealRequestId={revealRequestId}
+                  wordWrap={wordWrap}
+                  onPostRender={onFilePostRender}
+                  onPendingChange={onPendingChange}
+                />
+              </DiffWorkerPoolProvider>
             )
           ) : null}
         </div>
diff --git a/apps/web/src/components/files/fileEditorHighlight.test.ts b/apps/web/src/components/files/fileEditorHighlight.test.ts
new file mode 100644
index 000000000000..4de146835246
--- /dev/null
+++ b/apps/web/src/components/files/fileEditorHighlight.test.ts
@@ -0,0 +1,264 @@
+import {
+  FileRenderer,
+  getSharedHighlighter,
+  type BaseCodeOptions,
+  type DiffsHighlighter,
+  type FileContents,
+  type HighlightedToken,
+  type RenderRange,
+} from "@pierre/diffs";
+import { TextDocument } from "@pierre/diffs/editor";
+import { WorkerPoolManager, type WorkerRequest, type WorkerResponse } from "@pierre/diffs/worker";
+import * as NodeWorkerThreads from "node:worker_threads";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+type DocumentChange = NonNullable<ReturnType<TextDocument<unknown>["applyEdits"]>>;
+interface Tokenizer {
+  readonly themeType: "light" | "dark";
+  tokenize(change: DocumentChange, range: RenderRange): Map<number, HighlightedToken[]>;
+  cleanUp(): void;
+}
+
+// This dependency-internal tokenizer is the one used by Editor.#rerender.
+const tokenizerUrl = new URL("./editor/tokenizer.js", import.meta.resolve("@pierre/diffs"));
+const { EditorTokenizer } = (await import(/* @vite-ignore */ tokenizerUrl.href)) as {
+  EditorTokenizer: new (options: {
+    codeOptions: BaseCodeOptions;
+    highlighter: DiffsHighlighter;
+    textDocument: TextDocument<unknown>;
+    setStyle: (style: string) => void;
+    onDeferTokenize: (lines: Map<number, HighlightedToken[]>, theme: "light" | "dark") => void;
+  }) => Tokenizer;
+};
+
+const workerModule = import.meta.resolve("@pierre/diffs/worker/worker.js");
+const source = Array.from(
+  { length: 7_000 },
+  (_, index) =>
+    `export const section${index} = <p>Long wrapped source line ${index} for the file editor.</p>;`,
+).join("\n");
+const options = {
+  theme: "pierre-dark",
+  themeType: "dark",
+  preferredHighlighter: "shiki-wasm",
+  useTokenTransformer: true,
+  overflow: "wrap",
+  disableFileHeader: true,
+} as const;
+const range: RenderRange = {
+  startingLine: 6_950,
+  totalLines: 150,
+  bufferBefore: 0,
+  bufferAfter: 0,
+};
+
+interface HeldResponse {
+  data: WorkerResponse;
+  deliver: () => void;
+}
+let responses: HeldResponse[];
+let responseWaiters: ((response: HeldResponse) => void)[];
+let terminationPromises: Promise<number>[];
+let pool: WorkerPoolManager;
+let renderer: FileRenderer;
+let tokenizer: Tokenizer;
+let file: FileContents;
+let document: TextDocument<unknown>;
+
+function nextResponse(): Promise<HeldResponse> {
+  const response = responses.shift();
+  return response
+    ? Promise.resolve(response)
+    : new Promise((resolve) => responseWaiters.push(resolve));
+}
+
+class WorkerTransport {
+  private readonly worker = new NodeWorkerThreads.Worker(
+    `const { parentPort, workerData } = require("node:worker_threads");
+     globalThis.self = {
+       addEventListener(type, listener) {
+         if (type === "message") parentPort.on("message", data => listener({ data }));
+         if (type === "error") process.on("uncaughtException", listener);
+       }
+     };
+     globalThis.postMessage = data => parentPort.postMessage(data);
+     import(workerData.moduleUrl);`,
+    { eval: true, workerData: { moduleUrl: workerModule }, execArgv: [] },
+  );
+
+  addEventListener(
+    type: "message" | "error",
+    listener: (event: { data: WorkerResponse } | Error) => void,
+  ) {
+    if (type === "error") {
+      this.worker.on("error", listener);
+      return;
+    }
+    this.worker.on("message", (data: WorkerResponse) => {
+      const response = { data, deliver: () => listener({ data }) };
+      if (data.type !== "success" || data.requestType !== "file") {
+        response.deliver();
+        return;
+      }
+      const waiter = responseWaiters.shift();
+      if (waiter) waiter(response);
+      else responses.push(response);
+    });
+  }
+
+  postMessage(message: WorkerRequest) {
+    this.worker.postMessage(message, []);
+  }
+
+  terminate() {
+    terminationPromises.push(this.worker.terminate());
+  }
+}
+
+function applyChange(change: DocumentChange) {
+  // Keep the installed editor's non-DOM order, including the existing contents patch.
+  renderer.updateRenderCache(tokenizer.tokenize(change, range), tokenizer.themeType);
+  file.contents = document.getText();
+  if (change.lineDelta !== 0) renderer.applyDocumentChange(document);
+}
+
+function append(text: string) {
+  const position = document.positionAt(document.getText().length);
+  const change = document.applyEdits([
+    { range: { start: position, end: position }, newText: text },
+  ]);
+  expect(change).toBeDefined();
+  applyChange(change!);
+}
+
+function undo() {
+  const change = document.undo()?.[0];
+  expect(change).toBeDefined();
+  applyChange(change!);
+}
+
+function renderContents() {
+  const result = renderer.renderFile(file, range);
+  expect(result?.totalLines).toBe(document.lineCount);
+  return renderer.renderFullHTML(result!);
+}
+
+beforeEach(async () => {
+  responses = [];
+  responseWaiters = [];
+  terminationPromises = [];
+  vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) =>
+    setImmediate(() => callback(0)),
+  );
+  vi.stubGlobal("cancelAnimationFrame", clearImmediate);
+  vi.stubGlobal("window", { matchMedia: () => ({ matches: true }) });
+  pool = new WorkerPoolManager(
+    // Adapt browser transport only; Pierre's real worker produces each response.
+    { workerFactory: () => new WorkerTransport() as unknown as globalThis.Worker, poolSize: 1 },
+    options,
+  );
+  await pool.initialize(["tsx"]);
+  const highlighter = await getSharedHighlighter({
+    themes: ["pierre-dark"],
+    langs: ["tsx"],
+    preferredHighlighter: "shiki-wasm",
+  });
+  file = { name: "wrapped.tsx", contents: source, cacheKey: "editable-file" };
+  document = new TextDocument(file.name, source, "tsx");
+  renderer = new FileRenderer(options, () => {}, pool);
+  tokenizer = new EditorTokenizer({
+    codeOptions: options,
+    highlighter,
+    textDocument: document,
+    setStyle: () => {},
+    onDeferTokenize: (lines, theme) => renderer.updateRenderCache(lines, theme),
+  });
+  renderContents();
+});
+
+afterEach(async () => {
+  tokenizer?.cleanUp();
+  renderer?.cleanUp();
+  pool?.terminate();
+  await Promise.all(terminationPromises);
+  vi.unstubAllGlobals();
+});
+
+describe("editable file highlighting", () => {
+  it("still accepts an asynchronous highlight when the file has not changed", async () => {
+    expect(renderContents()).not.toContain('style="color:');
+    (await nextResponse()).deliver();
+    expect(renderContents()).toContain('style="color:');
+    expect(pool.getFileResultCache(file)).toBeDefined();
+  });
+
+  it.each([1, 60])(
+    "ignores a dispatched highlight after %i Enter edits and highlights the new version",
+    async (count) => {
+      const oldResponse = await nextResponse();
+      for (let index = 0; index < count; index += 1) append("\n");
+      append("export const EDITED_MARKER = 1;");
+      oldResponse.deliver();
+      expect(renderContents()).toContain("EDITED_MARKER");
+      const currentResponse = await nextResponse();
+      currentResponse.deliver();
+      expect(renderContents()).toContain("EDITED_MARKER");
+      const firstLines = renderer.renderFile(file, { ...range, startingLine: 0, totalLines: 20 });
+      expect(renderer.renderFullHTML(firstLines!)).toContain('style="color:');
+      expect(document.lineCount).toBe(7_000 + count);
+    },
+  );
+
+  it("does not replace a same-line edit with stale tokens", async () => {
+    const oldResponse = await nextResponse();
+    append(" EDITED_MARKER");
+    oldResponse.deliver();
+    expect(renderContents()).toContain("EDITED_MARKER");
+    expect(document.lineCount).toBe(7_000);
+    (await nextResponse()).deliver();
+    expect(renderContents()).toContain("EDITED_MARKER");
+  });
+
+  it("keeps undo edits after an older highlight arrives", async () => {
+    const oldResponse = await nextResponse();
+    append("\nexport const RETAINED_MARKER = 1;");
+    append("\nexport const UNDONE_MARKER = 2;");
+    undo();
+    oldResponse.deliver();
+    const html = renderContents();
+    expect(html).toContain("RETAINED_MARKER");
+    expect(html).not.toContain("UNDONE_MARKER");
+    (await nextResponse()).deliver();
+    expect(renderContents()).toContain("RETAINED_MARKER");
+    undo();
+    expect(document.getText()).toBe(source);
+    expect(renderContents()).not.toContain("RETAINED_MARKER");
+    const redone = document.redo()?.[0];
+    expect(redone).toBeDefined();
+    applyChange(redone!);
+    expect(renderContents()).toContain("RETAINED_MARKER");
+  });
+
+  it("evicts the pre-edit shared cache without losing already-highlighted lines", async () => {
+    (await nextResponse()).deliver();
+    expect(pool.getFileResultCache(file)).toBeDefined();
+    append("\nexport const EDITED_MARKER = 1;");
+    expect(pool.getFileResultCache(file)).toBeUndefined();
+    expect(renderContents()).toContain("EDITED_MARKER");
+    const firstLines = renderer.renderFile(file, { ...range, startingLine: 0, totalLines: 20 });
+    expect(renderer.renderFullHTML(firstLines!)).toContain('style="color:');
+  });
+
+  it("reopens the edited file with the same cache key while an old response is pending", async () => {
+    const oldResponse = await nextResponse();
+    append("\nexport const REOPENED_MARKER = 1;");
+    renderer.cleanUp();
+    renderer = new FileRenderer(options, () => {}, pool);
+    file = { ...file };
+    expect(renderContents()).toContain("REOPENED_MARKER");
+    oldResponse.deliver();
+    (await nextResponse()).deliver();
+    expect(renderContents()).toContain("REOPENED_MARKER");
+    expect(renderContents()).toContain('style="color:');
+  });
+});
diff --git a/apps/web/src/components/files/fileEditorLanguageReadiness.test.ts b/apps/web/src/components/files/fileEditorLanguageReadiness.test.ts
new file mode 100644
index 000000000000..520c0fa82d0e
--- /dev/null
+++ b/apps/web/src/components/files/fileEditorLanguageReadiness.test.ts
@@ -0,0 +1,186 @@
+import {
+  FileRenderer,
+  disposeHighlighter,
+  getSharedHighlighter,
+  type BaseCodeOptions,
+  type DiffsHighlighter,
+  type FileContents,
+  type HighlightedToken,
+} from "@pierre/diffs";
+import { TextDocument } from "@pierre/diffs/editor";
+import { WorkerPoolManager, type WorkerRequest, type WorkerResponse } from "@pierre/diffs/worker";
+import * as NodeWorkerThreads from "node:worker_threads";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+type DocumentChange = NonNullable<ReturnType<TextDocument<unknown>["applyEdits"]>>;
+interface Tokenizer {
+  tokenize(change: DocumentChange): Map<number, HighlightedToken[]>;
+  cleanUp(): void;
+}
+
+const tokenizerUrl = new URL("./editor/tokenizer.js", import.meta.resolve("@pierre/diffs"));
+const { EditorTokenizer } = (await import(/* @vite-ignore */ tokenizerUrl.href)) as {
+  EditorTokenizer: new (options: {
+    codeOptions: BaseCodeOptions;
+    highlighter: DiffsHighlighter;
+    textDocument: TextDocument<unknown>;
+    setStyle: (style: string) => void;
+    onDeferTokenize: () => void;
+  }) => Tokenizer;
+};
+
+const workerModule = import.meta.resolve("@pierre/diffs/worker/worker.js");
+const options = {
+  theme: "pierre-dark",
+  themeType: "dark",
+  preferredHighlighter: "shiki-wasm",
+  useTokenTransformer: true,
+} as const;
+const source = "export const View = () => <div>Ready</div>;";
+let pool: WorkerPoolManager;
+let renderer: FileRenderer;
+let terminationPromises: Promise<number>[];
+
+class WorkerTransport {
+  private readonly worker = new NodeWorkerThreads.Worker(
+    `const { parentPort, workerData } = require("node:worker_threads");
+     globalThis.self = {
+       addEventListener(type, listener) {
+         if (type === "message") parentPort.on("message", data => listener({ data }));
+         if (type === "error") process.on("uncaughtException", listener);
+       }
+     };
+     globalThis.postMessage = data => parentPort.postMessage(data);
+     import(workerData.moduleUrl);`,
+    { eval: true, workerData: { moduleUrl: workerModule }, execArgv: [] },
+  );
+
+  addEventListener(
+    type: "message" | "error",
+    listener: (event: { data: WorkerResponse } | Error) => void,
+  ) {
+    if (type === "error") this.worker.on("error", listener);
+    else this.worker.on("message", (data: WorkerResponse) => listener({ data }));
+  }
+
+  postMessage(message: WorkerRequest) {
+    this.worker.postMessage(message, []);
+  }
+
+  terminate() {
+    terminationPromises.push(this.worker.terminate());
+  }
+}
+
+function firstEnter(highlighter: DiffsHighlighter, file: FileContents, language: string) {
+  const document = new TextDocument(file.name, file.contents, language);
+  const tokenizer = new EditorTokenizer({
+    codeOptions: options,
+    highlighter,
+    textDocument: document,
+    setStyle: () => {},
+    onDeferTokenize: () => {},
+  });
+  try {
+    const end = document.positionAt(file.contents.length);
+    const change = document.applyEdits([{ range: { start: end, end }, newText: "\n" }]);
+    expect(change).toBeDefined();
+    // This is the synchronous first edit, before the tokenizer's debounced prebuild.
+    const dirtyLines = tokenizer.tokenize(change!);
+    expect([...dirtyLines.keys()]).toEqual([0, 1]);
+    expect(document.getText()).toBe(`${file.contents}\n`);
+  } finally {
+    tokenizer.cleanUp();
+  }
+}
+
+beforeEach(async () => {
+  terminationPromises = [];
+  vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) =>
+    setImmediate(() => callback(0)),
+  );
+  vi.stubGlobal("cancelAnimationFrame", clearImmediate);
+  vi.stubGlobal("window", { matchMedia: () => ({ matches: true }) });
+  await disposeHighlighter();
+  pool = new WorkerPoolManager(
+    // Adapt transport only. The installed Pierre worker resolves and highlights the file.
+    { workerFactory: () => new WorkerTransport() as unknown as globalThis.Worker, poolSize: 1 },
+    options,
+  );
+  await pool.initialize();
+  renderer = new FileRenderer(options, undefined, pool);
+});
+
+afterEach(async () => {
+  renderer?.cleanUp();
+  pool?.terminate();
+  await Promise.all(terminationPromises);
+  await disposeHighlighter();
+  vi.unstubAllGlobals();
+});
+
+describe("editable file language readiness", () => {
+  it.each(["hydrate", "renderFile"] as const)(
+    "%s prepares the inferred language before the first edit of a worker-highlighted file",
+    async (method) => {
+      const file = { name: "cold.tsx", contents: source, cacheKey: "cold-tsx" };
+      await pool.primeFileHighlightCache(file);
+      expect(pool.getFileResultCache(file)).toBeDefined();
+      const mainHighlighter = await getSharedHighlighter({
+        themes: ["pierre-dark"],
+        langs: ["text"],
+      });
+      expect(mainHighlighter.getLoadedLanguages()).not.toContain("tsx");
+      renderer[method](file);
+      // Read-only worker rendering must not load editor grammars on the main thread.
+      expect(mainHighlighter.getLoadedLanguages()).not.toContain("tsx");
+      const highlighter = await renderer.initializeHighlighter();
+      firstEnter(highlighter, file, "tsx");
+    },
+  );
+
+  it.each(["hydrate", "renderFile"] as const)(
+    "%s respects an explicit language when the filename suggests plain text",
+    async (method) => {
+      const file: FileContents = {
+        name: "source.txt",
+        lang: "tsx",
+        contents: source,
+        cacheKey: "explicit-tsx",
+      };
+      await pool.primeFileHighlightCache(file);
+      renderer[method](file);
+      firstEnter(await renderer.initializeHighlighter(), file, "tsx");
+    },
+  );
+
+  it("loads a newly opened language after reusing a worker-backed renderer", async () => {
+    const previousFile: FileContents = {
+      name: "previous.ts",
+      contents: "export const value = 1;",
+      cacheKey: "previous-ts",
+    };
+    await getSharedHighlighter({ themes: ["pierre-dark"], langs: ["typescript"] });
+    renderer.renderFile(previousFile);
+    firstEnter(await renderer.initializeHighlighter(), previousFile, "typescript");
+    const nextFile = { name: "next.tsx", contents: source, cacheKey: "next-tsx" };
+    renderer.renderFile(nextFile);
+    firstEnter(await renderer.initializeHighlighter(), nextFile, "tsx");
+  });
+
+  it("prepares a hydrated non-worker file even when its theme was already loaded", async () => {
+    renderer.cleanUp();
+    renderer = new FileRenderer(options);
+    const file = { name: "local.tsx", contents: source, cacheKey: "local-tsx" };
+    renderer.hydrate(file);
+    firstEnter(await renderer.initializeHighlighter(), file, "tsx");
+  });
+
+  it("keeps plain text editable without loading an unrelated grammar", async () => {
+    const file = { name: "notes.txt", contents: "Plain text", cacheKey: "plain-text" };
+    renderer.renderFile(file);
+    const highlighter = await renderer.initializeHighlighter();
+    firstEnter(highlighter, file, "text");
+    expect(highlighter.getLoadedLanguages()).not.toContain("tsx");
+  });
+});
diff --git a/apps/web/src/components/files/fileEditorVirtualization.test.ts b/apps/web/src/components/files/fileEditorVirtualization.test.ts
new file mode 100644
index 000000000000..cf293dd47254
--- /dev/null
+++ b/apps/web/src/components/files/fileEditorVirtualization.test.ts
@@ -0,0 +1,723 @@
+import {
+  getSharedHighlighter,
+  VirtualizedFile,
+  Virtualizer,
+  type FileContents,
+} from "@pierre/diffs";
+import { Editor, TextDocument } from "@pierre/diffs/editor";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const renderingManagerUrl = new URL(
+  "./managers/UniversalRenderingManager.js",
+  import.meta.resolve("@pierre/diffs"),
+);
+const { clearRenderQueue } = (await import(/* @vite-ignore */ renderingManagerUrl.href)) as {
+  clearRenderQueue(): void;
+};
+
+// Layout measurements are controlled here. The real reconciler, document and
+// renderer calculate positions. This does not simulate native CSS wrapping.
+class MeasuredElement {
+  static geometryReads = 0;
+  children: MeasuredElement[] = [];
+  dataset: Record<string, string> = {};
+  nextElementSibling: MeasuredElement | null = null;
+  width = 283;
+
+  constructor(readonly height = 0) {}
+
+  getBoundingClientRect() {
+    MeasuredElement.geometryReads += 1;
+    return { top: 0, height: this.height, width: this.width };
+  }
+}
+
+class MeasuredCodeElement extends MeasuredElement {
+  readonly tagName = "CODE";
+
+  get firstElementChild() {
+    return this.children[0] ?? null;
+  }
+}
+
+const observers: RecordedResizeObserver[] = [];
+const animationFrames = new Map<number, FrameRequestCallback>();
+let nextFrameId = 0;
+
+class RecordedResizeObserver {
+  readonly targets = new Set<Element>();
+
+  constructor(readonly callback: ResizeObserverCallback) {
+    observers.push(this);
+  }
+
+  observe(target: Element) {
+    this.targets.add(target);
+  }
+
+  unobserve(target: Element) {
+    this.targets.delete(target);
+  }
+
+  disconnect() {
+    this.targets.clear();
+  }
+
+  deliver(target: HTMLElement) {
+    const rect = target.getBoundingClientRect();
+    const size = { inlineSize: rect.width, blockSize: rect.height };
+    this.callback(
+      [
+        {
+          target,
+          contentRect: rect,
+          contentBoxSize: [size],
+          borderBoxSize: [size],
+          devicePixelContentBoxSize: [size],
+        },
+      ],
+      this as unknown as ResizeObserver,
+    );
+  }
+}
+
+function drainRenderFrames() {
+  const errors = vi.spyOn(console, "error");
+  try {
+    for (let frame = 0; animationFrames.size > 0; frame += 1) {
+      if (frame === 10) throw new Error("The production render queue did not settle");
+      const callbacks = [...animationFrames.values()];
+      animationFrames.clear();
+      for (const callback of callbacks) callback(frame);
+    }
+    expect(errors).not.toHaveBeenCalled();
+  } finally {
+    errors.mockRestore();
+  }
+}
+
+function measuredElement(element: MeasuredElement): HTMLElement {
+  return element as unknown as HTMLElement;
+}
+
+class LayoutVirtualizer extends Virtualizer {
+  override getOffsetInScrollContainer(_element: HTMLElement) {
+    return 0;
+  }
+}
+
+class MeasuredFile extends VirtualizedFile {
+  override top = 0;
+
+  override attachEditor(editor: Parameters<VirtualizedFile["attachEditor"]>[0]) {
+    this.editor = editor;
+    return () => {
+      this.editor = undefined;
+    };
+  }
+
+  async initialize(file: FileContents) {
+    this.prepareCodeViewItem(file, 0);
+    await this.fileRenderer.initializeHighlighter();
+    expect(
+      this.fileRenderer.renderFile(file, {
+        startingLine: 5950,
+        totalLines: 51,
+        bufferBefore: 0,
+        bufferAfter: 0,
+      }),
+    ).toBeDefined();
+    this.fileContainer = measuredElement(new MeasuredElement());
+  }
+
+  measure(
+    rows: ReadonlyArray<readonly [lineIndex: number, height: number]>,
+    contentWidth = 226.25,
+  ) {
+    const content = new MeasuredElement();
+    content.width = contentWidth;
+    content.children = rows.map(([lineIndex, height]) => {
+      const row = new MeasuredElement(height);
+      row.dataset.lineIndex = String(lineIndex);
+      return row;
+    });
+    const code = new MeasuredCodeElement();
+    code.width = contentWidth + 56.75;
+    code.children = [new MeasuredElement(), content];
+    this.code = measuredElement(code);
+    this.reconcileHeights();
+  }
+
+  resizeContent(contentWidth: number, codeWidth = contentWidth + 56.75) {
+    const code = this.code;
+    const content = code?.children[1];
+    if (!(code instanceof MeasuredElement) || !(content instanceof MeasuredElement)) {
+      throw new Error("Expected measured code and content");
+    }
+    code.width = codeWidth;
+    content.width = contentWidth;
+  }
+
+  observeLayout() {
+    const pre = new MeasuredElement();
+    if (!(this.code instanceof MeasuredElement)) throw new Error("Expected measured code");
+    pre.children = [this.code];
+    this.resizeManager.setup(measuredElement(pre) as HTMLPreElement, {
+      disableAnnotations: true,
+      columnVariables: "measure",
+    });
+    const code = this.code;
+    const observer = observers.find((candidate) => candidate.targets.has(code));
+    if (observer === undefined) throw new Error("The real resize manager did not observe code");
+    return () => observer.deliver(code);
+  }
+
+  dispose() {
+    this.fileContainer = undefined;
+    this.code = undefined;
+    this.cleanUp();
+  }
+}
+
+const instances: MeasuredFile[] = [];
+const editors: Editor<undefined>[] = [];
+
+beforeAll(async () => {
+  await getSharedHighlighter({
+    themes: ["pierre-dark"],
+    langs: ["text"],
+    preferredHighlighter: "shiki-wasm",
+  });
+});
+
+beforeEach(() => {
+  observers.length = 0;
+  animationFrames.clear();
+  MeasuredElement.geometryReads = 0;
+  vi.stubGlobal("HTMLElement", MeasuredElement);
+  vi.stubGlobal("Document", MeasuredElement);
+  vi.stubGlobal("ResizeObserver", RecordedResizeObserver);
+  vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+    const id = ++nextFrameId;
+    animationFrames.set(id, callback);
+    return id;
+  });
+  vi.stubGlobal("cancelAnimationFrame", (id: number) => animationFrames.delete(id));
+});
+
+afterEach(() => {
+  for (const editor of editors.splice(0)) editor.cleanUp();
+  for (const instance of instances.splice(0)) instance.dispose();
+  clearRenderQueue();
+  animationFrames.clear();
+  vi.unstubAllGlobals();
+});
+
+async function makeFixture(
+  overflow: "wrap" | "scroll" = "wrap",
+  lineCount = 6001,
+  contentWidth = 226.25,
+) {
+  const contents = Array.from({ length: lineCount }, (_, index) => `line ${index}`).join("\n");
+  const file: FileContents = {
+    name: "wrapped.txt",
+    contents,
+    cacheKey: `wrapped:${overflow}`,
+    lang: "text",
+  };
+  const document = new TextDocument(file.name, contents, "text");
+  const instance = new MeasuredFile(
+    {
+      overflow,
+      disableFileHeader: true,
+      theme: "pierre-dark",
+      preferredHighlighter: "shiki-wasm",
+      useTokenTransformer: true,
+      controlledSelection: true,
+    },
+    new LayoutVirtualizer(),
+  );
+  instances.push(instance);
+  await instance.initialize(file);
+  instance.measure(
+    [
+      [0, 80],
+      [120, 60],
+      [4999, 100],
+      [5000, 80],
+      [5999, 100],
+      [6000, 60],
+    ],
+    contentWidth,
+  );
+  const apply = (change: { startLine: number } | undefined, passStartLine = true) => {
+    if (change === undefined) throw new Error("Expected a document change");
+    file.contents = document.getText();
+    instance.applyDocumentChange(
+      document,
+      undefined,
+      false,
+      passStartLine ? change.startLine : undefined,
+    );
+  };
+  const append = () => {
+    const position = document.positionAt(document.getText().length);
+    apply(document.applyEdits([{ range: { start: position, end: position }, newText: "\n" }]));
+  };
+  return { instance, document, file, apply, append };
+}
+
+describe("wrapped editor document changes", () => {
+  it("preserves the position above an EOF insertion across layout checkpoints", async () => {
+    const { instance, document, append } = await makeFixture();
+    const previousLastLine = document.lineCount;
+    const before = instance.getLinePosition(previousLastLine);
+    expect(before).toEqual({ top: 120328, height: 60 });
+    const viewport = { top: before!.top - 100, bottom: before!.top + 80 };
+    expect(instance.getAdvancedStickySpecs(viewport)).toEqual({ topOffset: 118240, height: 2156 });
+
+    append();
+
+    expect(document.lineCount).toBe(previousLastLine + 1);
+    expect(instance.getLinePosition(previousLastLine)).toEqual({ top: before!.top, height: 20 });
+    expect(instance.getLinePosition(document.lineCount)).toEqual({ top: 120348, height: 20 });
+    expect(instance.getVirtualizedHeight()).toBe(120376);
+    expect(instance.getAdvancedStickySpecs(viewport)).toEqual({ topOffset: 118240, height: 2136 });
+  });
+
+  it("invalidates changed and shifted rows after an insertion in the middle", async () => {
+    const { instance, document, apply } = await makeFixture();
+    const before = instance.getLinePosition(5001);
+    const position = { line: 5000, character: 2 };
+    apply(document.applyEdits([{ range: { start: position, end: position }, newText: "\n" }]));
+
+    expect(instance.getLinePosition(5001)).toEqual({ top: before!.top, height: 20 });
+    expect(instance.getLineHeight(4999)).toBe(100);
+    expect(instance.getLineHeight(5000)).toBe(20);
+    expect(instance.getLineHeight(5999)).toBe(20);
+    expect(instance.getLinePosition(document.lineCount)).toEqual({ top: 120208, height: 20 });
+  });
+
+  it("keeps preceding measurements when a deletion crosses a checkpoint", async () => {
+    const { instance, document, apply } = await makeFixture();
+    const before = instance.getLinePosition(5000);
+    apply(
+      document.applyEdits([
+        {
+          range: { start: { line: 4999, character: 2 }, end: { line: 5001, character: 2 } },
+          newText: "",
+        },
+      ]),
+    );
+
+    expect(document.lineCount).toBe(5999);
+    expect(instance.getLinePosition(5000)).toEqual({ top: before!.top, height: 20 });
+    expect(instance.getLineHeight(120)).toBe(60);
+    expect(instance.getLineHeight(4999)).toBe(20);
+    expect(instance.getLineHeight(6000)).toBe(20);
+    expect(instance.getLinePosition(document.lineCount)).toEqual({ top: 120068, height: 20 });
+  });
+
+  it("uses the earliest changed line for edits at multiple selections", async () => {
+    const { instance, document, apply } = await makeFixture();
+    const before = instance.getLinePosition(121);
+    apply(
+      document.applyEdits(
+        [120, 5000].map((line) => ({
+          range: { start: { line, character: 2 }, end: { line, character: 2 } },
+          newText: "\n",
+        })),
+      ),
+    );
+
+    expect(document.lineCount).toBe(6003);
+    expect(instance.getLinePosition(121)).toEqual({ top: before!.top, height: 20 });
+    expect(instance.getLineHeight(0)).toBe(80);
+    expect(instance.getLineHeight(120)).toBe(20);
+    expect(instance.getLineHeight(4999)).toBe(20);
+  });
+
+  it("retains the unchanged prefix through repeated Enter, undo and redo", async () => {
+    const { instance, document, apply, append } = await makeFixture();
+    const before = instance.getLinePosition(6001);
+    for (let count = 0; count < 60; count += 1) append();
+    expect(document.lineCount).toBe(6061);
+    expect(instance.getLinePosition(6001)?.top).toBe(before!.top);
+    apply(document.undo()?.[0]);
+    expect(instance.getLinePosition(6001)?.top).toBe(before!.top);
+    apply(document.redo()?.[0]);
+    expect(document.lineCount).toBe(6061);
+    expect(instance.getLinePosition(6001)?.top).toBe(before!.top);
+  });
+
+  it("keeps unwrapped positions unchanged", async () => {
+    const { instance, append } = await makeFixture("scroll");
+    const before = instance.getLinePosition(6001);
+    append();
+    expect(instance.getLinePosition(6001)).toEqual(before);
+    expect(instance.getLinePosition(6002)).toEqual({ top: 120028, height: 20 });
+  });
+
+  it("fully invalidates measurements when the first changed line is unknown", async () => {
+    const { instance, document, apply } = await makeFixture();
+    const position = document.positionAt(document.getText().length);
+    apply(
+      document.applyEdits([{ range: { start: position, end: position }, newText: "\n" }]),
+      false,
+    );
+    expect(instance.getLinePosition(6001)).toEqual({ top: 120008, height: 20 });
+    expect(instance.getLineHeight(0)).toBe(20);
+  });
+
+  it("still discards all measured rows after a metric change", async () => {
+    const { instance, file, append } = await makeFixture();
+    append();
+    instance.setMetrics({ hunkLineCount: 50, lineHeight: 24, diffHeaderHeight: 44, spacing: 8 });
+    instance.prepareCodeViewItem(file, 0);
+    expect(instance.getLinePosition(6001)).toEqual({ top: 144008, height: 24 });
+  });
+
+  it("still discards all measured rows when annotations change", async () => {
+    const { instance, file, append } = await makeFixture();
+    append();
+    instance.setLineAnnotations([{ lineNumber: 10, metadata: undefined }]);
+    instance.prepareCodeViewItem(file, 0);
+    expect(instance.getLinePosition(6001)).toEqual({ top: 120008, height: 20 });
+  });
+});
+
+describe("wrapped measurement widths", () => {
+  it.each([
+    [226.25, 482.25],
+    [482.25, 226.25],
+  ])(
+    "drops offscreen measurements when content changes from %spx to %spx",
+    async (before, after) => {
+      const { instance } = await makeFixture("wrap", 6001, before);
+      instance.measure([[6000, 60]], after);
+      expect(instance.getLineHeight(0)).toBe(20);
+      expect(instance.getLineHeight(120)).toBe(20);
+      expect(instance.getLineHeight(6000)).toBe(60);
+      expect(instance.getVirtualizedHeight()).toBe(120076);
+    },
+  );
+
+  it.each([
+    [226.25, 482.25],
+    [482.25, 226.25],
+  ])(
+    "does not retain old-width prefix heights after a %spx to %spx resize and edit",
+    async (before, after) => {
+      const { instance, append } = await makeFixture("wrap", 6001, before);
+      instance.measure([[6000, 60]], after);
+      append();
+      expect(instance.getLineHeight(0)).toBe(20);
+      expect(instance.getLineHeight(120)).toBe(20);
+      expect(instance.getLinePosition(6001)).toEqual({ top: 120008, height: 20 });
+    },
+  );
+
+  it("repairs an edit before resize delivery when the real resize and render queues drain", async () => {
+    const { instance, append } = await makeFixture();
+    instance.measure([[6000, 60]]);
+    const deliverResize = instance.observeLayout();
+    instance.resizeContent(482.25);
+    const readsBeforeEdit = MeasuredElement.geometryReads;
+    append();
+    expect(MeasuredElement.geometryReads).toBe(readsBeforeEdit);
+    // No synchronous geometry read: the resize entry owns invalidation.
+    expect(instance.getLineHeight(0)).toBe(80);
+    deliverResize();
+    drainRenderFrames();
+    expect(instance.getLineHeight(0)).toBe(20);
+    expect(instance.getLinePosition(6001)).toEqual({ top: 120008, height: 60 });
+  });
+
+  it("keeps measured prefixes through same-width reconciliation and editing", async () => {
+    const { instance, append } = await makeFixture();
+    instance.measure([[6000, 60]]);
+    append();
+    expect(instance.getLineHeight(0)).toBe(80);
+    expect(instance.getLineHeight(120)).toBe(60);
+    expect(instance.getLinePosition(6001)).toEqual({ top: 120328, height: 20 });
+  });
+
+  it("preserves measurements on first and repeated same-width resize deliveries", async () => {
+    const { instance } = await makeFixture();
+    const before = instance.getVirtualizedHeight();
+    const deliverResize = instance.observeLayout();
+    deliverResize();
+    deliverResize();
+    drainRenderFrames();
+    expect(instance.getLineHeight(0)).toBe(80);
+    expect(instance.getVirtualizedHeight()).toBe(before);
+  });
+
+  it.each([
+    [226.25, 482.25],
+    [482.25, 226.25],
+  ])("handles a %spx to %spx resize before first observer delivery", async (before, after) => {
+    const { instance } = await makeFixture("wrap", 6001, before);
+    instance.measure([[6000, 20]], before);
+    const deliverResize = instance.observeLayout();
+    instance.resizeContent(after);
+    deliverResize();
+    drainRenderFrames();
+    expect(instance.getLineHeight(0)).toBe(20);
+    expect(instance.getVirtualizedHeight()).toBe(120036);
+  });
+
+  it("keeps width validity when a new editor attaches to the same file", async () => {
+    const { instance } = await makeFixture();
+    instance.measure([[6000, 20]]);
+    const deliverResize = instance.observeLayout();
+    vi.stubGlobal("SVGSVGElement", EditorElement);
+    vi.stubGlobal(
+      "document",
+      Object.assign(new EditorElement(), { createElement: () => new EditorElement() }),
+    );
+    const first = new Editor<undefined>();
+    editors.push(first);
+    first.edit(instance);
+    first.cleanUp();
+    const second = new Editor<undefined>();
+    editors.push(second);
+    second.edit(instance);
+    instance.resizeContent(482.25);
+    deliverResize();
+    drainRenderFrames();
+    expect(instance.getLineHeight(0)).toBe(20);
+    expect(instance.getVirtualizedHeight()).toBe(120036);
+  });
+
+  it("ignores stale resize deliveries after cleanup", async () => {
+    const { instance } = await makeFixture();
+    const deliverResize = instance.observeLayout();
+    instance.dispose();
+    clearRenderQueue();
+    animationFrames.clear();
+    deliverResize();
+    expect(animationFrames.size).toBe(0);
+  });
+
+  it("does not discard a stable code width for gutter subpixel rounding", async () => {
+    const { instance } = await makeFixture("wrap", 6001, 482.25);
+    const deliverResize = instance.observeLayout();
+    instance.resizeContent(482.234375, 539);
+    deliverResize();
+    drainRenderFrames();
+    expect(instance.getLineHeight(0)).toBe(80);
+  });
+
+  it("waits for a visible width instead of caching measurements while hidden", async () => {
+    const { instance } = await makeFixture();
+    instance.measure([[6000, 20]]);
+    const deliverResize = instance.observeLayout();
+    instance.resizeContent(0, 0);
+    deliverResize();
+    drainRenderFrames();
+    expect(instance.getLineHeight(0)).toBe(80);
+    instance.resizeContent(482.25);
+    deliverResize();
+    drainRenderFrames();
+    expect(instance.getLineHeight(0)).toBe(20);
+    expect(instance.getVirtualizedHeight()).toBe(120036);
+  });
+});
+
+// Supply inert DOM transport so public Editor edits execute its real tokenizer
+// and layout handoff. No native wrapping, observer delivery or scrolling is modeled.
+class EditorElement extends MeasuredElement {
+  style: Record<string, string> = {};
+  parentElement: EditorElement | null = null;
+
+  appendChild(child: EditorElement) {
+    child.parentElement = this;
+    this.children.push(child);
+    return child;
+  }
+
+  prepend(child: EditorElement) {
+    child.parentElement = this;
+    this.children.unshift(child);
+  }
+
+  replaceChildren(...children: (EditorElement | string)[]) {
+    this.children = [];
+    for (const child of children) if (typeof child !== "string") this.appendChild(child);
+  }
+
+  setAttribute() {}
+  removeAttribute() {}
+  addEventListener() {}
+  removeEventListener() {}
+  after() {}
+
+  remove() {
+    if (this.parentElement) {
+      this.parentElement.children = this.parentElement.children.filter((child) => child !== this);
+    }
+  }
+
+  set innerHTML(value: string) {
+    expect(value.startsWith("<svg")).toBe(true);
+    this.replaceChildren(new EditorElement());
+  }
+
+  get firstElementChild() {
+    return this.children[0] ?? null;
+  }
+
+  querySelectorAll(selector: string) {
+    expect(selector).toBe("[data-code]");
+    return this.children.filter((child) => "code" in child.dataset);
+  }
+
+  querySelector(selector: string) {
+    expect(selector).toBe("[data-deletions]");
+    return null;
+  }
+
+  getContext() {
+    return { measureText: (text: string) => ({ width: text.length * 8 }) };
+  }
+}
+
+async function makeEditorFixture(lineCount: number) {
+  const { instance, file } = await makeFixture("wrap", lineCount);
+  vi.stubGlobal("SVGSVGElement", EditorElement);
+  vi.stubGlobal("Document", EditorElement);
+  vi.stubGlobal(
+    "document",
+    Object.assign(new EditorElement(), { createElement: () => new EditorElement() }),
+  );
+  vi.stubGlobal("window", { matchMedia: () => ({ matches: true }) });
+  vi.stubGlobal("requestAnimationFrame", () => 1);
+  vi.stubGlobal("cancelAnimationFrame", () => {});
+  vi.stubGlobal("getComputedStyle", () => ({
+    paddingTop: "0px",
+    fontSize: "13px",
+    fontFamily: "monospace",
+    tabSize: "2",
+    lineHeight: "20px",
+  }));
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      observe() {}
+      disconnect() {}
+    },
+  );
+  instance.setOptions({
+    ...instance.options,
+    useTokenTransformer: true,
+    controlledSelection: true,
+    themeType: "dark",
+  });
+  const content = new EditorElement();
+  content.dataset.content = "";
+  const gutter = new EditorElement();
+  gutter.dataset.gutter = "";
+  const code = new EditorElement();
+  code.dataset.code = "";
+  code.appendChild(gutter);
+  code.appendChild(content);
+  const shadow = new EditorElement();
+  shadow.appendChild(code);
+  const host = Object.assign(new EditorElement(), { shadowRoot: shadow });
+  const highlighter = await getSharedHighlighter({
+    themes: ["pierre-dark"],
+    langs: ["text"],
+    preferredHighlighter: "shiki-wasm",
+  });
+  const editor = new Editor<undefined>();
+  editors.push(editor);
+  editor.edit(instance);
+  editor.__syncRenderView(highlighter, measuredElement(host), file, undefined, {
+    startingLine: 0,
+    totalLines: 1,
+    bufferBefore: 0,
+    bufferAfter: 0,
+  });
+  const append = (count: number) => {
+    const lines = editor.getText().split("\n");
+    const end = { line: lines.length - 1, character: lines.at(-1)!.length };
+    editor.applyEdits([{ range: { start: end, end }, newText: "\n".repeat(count) }]);
+  };
+  const remove = (count: number) => {
+    const lines = editor.getText().split("\n");
+    const startLine = lines.length - count - 1;
+    editor.applyEdits([
+      {
+        range: {
+          start: { line: startLine, character: lines[startLine]!.length },
+          end: { line: lines.length - 1, character: lines.at(-1)!.length },
+        },
+        newText: "",
+      },
+    ]);
+  };
+  return { instance, editor, append, remove };
+}
+
+describe("editor gutter-width changes", () => {
+  it.each([
+    [9999, 1],
+    [9998, 3],
+  ])(
+    "clears prefix measurements when %i lines grow by %i across a digit boundary",
+    async (lines, count) => {
+      const { instance, editor, append } = await makeEditorFixture(lines);
+      expect(instance.getLineHeight(0)).toBe(80);
+      append(count);
+      expect(editor.getText().split("\n")).toHaveLength(lines + count);
+      expect(instance.getLineHeight(0)).toBe(20);
+      expect(instance.getLineHeight(5000)).toBe(20);
+    },
+  );
+
+  it.each([
+    [10000, 1],
+    [10002, 4],
+  ])(
+    "clears prefix measurements when %i lines shrink by %i across a digit boundary",
+    async (lines, count) => {
+      const { instance, editor, remove } = await makeEditorFixture(lines);
+      remove(count);
+      expect(editor.getText().split("\n")).toHaveLength(lines - count);
+      expect(instance.getLineHeight(0)).toBe(20);
+      expect(instance.getLineHeight(5000)).toBe(20);
+    },
+  );
+
+  it("clears newly measured prefixes on undo and redo across a digit boundary", async () => {
+    const { instance, editor, append } = await makeEditorFixture(9999);
+    append(1);
+    instance.measure([[0, 100]]);
+    editor.undo();
+    expect(editor.getText().split("\n")).toHaveLength(9999);
+    expect(instance.getLineHeight(0)).toBe(20);
+    instance.measure([[0, 80]]);
+    editor.redo();
+    expect(editor.getText().split("\n")).toHaveLength(10000);
+    expect(instance.getLineHeight(0)).toBe(20);
+  });
+
+  it.each([
+    [9998, 1],
+    [10000, 2],
+  ])(
+    "retains prefix measurements when %i lines grow by %i without changing digit width",
+    async (lines, count) => {
+      const { instance, editor, append } = await makeEditorFixture(lines);
+      append(count);
+      expect(editor.getText().split("\n")).toHaveLength(lines + count);
+      expect(instance.getLineHeight(0)).toBe(80);
+      expect(instance.getLineHeight(5000)).toBe(80);
+      editor.undo();
+      expect(instance.getLineHeight(0)).toBe(80);
+      editor.redo();
+      expect(instance.getLineHeight(0)).toBe(80);
+    },
+  );
+});
diff --git a/apps/web/src/components/files/useFileSaveCoordinator.test.tsx b/apps/web/src/components/files/useFileSaveCoordinator.test.tsx
new file mode 100644
index 000000000000..603f97cf1f26
--- /dev/null
+++ b/apps/web/src/components/files/useFileSaveCoordinator.test.tsx
@@ -0,0 +1,174 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { AsyncResult } from "effect/unstable/reactivity";
+import { act, StrictMode } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const { writeFile, confirmFile } = vi.hoisted(() => ({
+  writeFile: vi.fn(),
+  confirmFile: vi.fn(),
+}));
+vi.mock("~/state/projects", () => ({ projectEnvironment: { writeFile: {} } }));
+vi.mock("~/state/use-atom-command", () => ({ useAtomCommand: () => writeFile }));
+vi.mock("./projectFilesQueryState", () => ({ confirmProjectFileQueryData: confirmFile }));
+
+import { setMarkdownTaskChecked } from "./filePreviewMode";
+import { useFileSaveCoordinator } from "./useFileSaveCoordinator";
+
+const environmentId = EnvironmentId.make("save-lifecycle-audit");
+const onPendingChange = vi.fn();
+const defaultProps = {
+  environmentId,
+  cwd: "/workspace",
+  relativePath: "file.txt",
+  onPendingChange,
+};
+let renderer: ReactTestRenderer | null;
+
+function ChangeSource(_props: { onChange: (contents: string) => void }) {
+  return null;
+}
+
+function FileSurface(props: Parameters<typeof useFileSaveCoordinator>[0]) {
+  const coordinator = useFileSaveCoordinator(props);
+  return <ChangeSource onChange={(contents) => coordinator.change(contents)} />;
+}
+
+function mount(props = defaultProps) {
+  act(() => {
+    renderer = create(
+      <StrictMode>
+        <FileSurface {...props} />
+      </StrictMode>,
+    );
+  });
+}
+
+function changeHandler(): (contents: string) => void {
+  return renderer!.root.findByType(ChangeSource).props.onChange;
+}
+
+beforeEach(() => {
+  renderer = null;
+  vi.useFakeTimers();
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  writeFile.mockReset().mockResolvedValue(AsyncResult.success(undefined));
+  confirmFile.mockReset();
+  onPendingChange.mockReset();
+});
+
+afterEach(async () => {
+  await act(async () => renderer?.unmount());
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe("file-save React lifecycle", () => {
+  it("persists editor model changes after StrictMode setup replay", async () => {
+    mount();
+    changeHandler()("AUDIT7907NATIVE\n");
+    expect(onPendingChange).toHaveBeenCalledWith("file.txt", true);
+    await vi.advanceTimersByTimeAsync(500);
+    expect(writeFile).toHaveBeenCalledExactlyOnceWith({
+      environmentId,
+      input: { cwd: "/workspace", relativePath: "file.txt", contents: "AUDIT7907NATIVE\n" },
+    });
+    expect(confirmFile).toHaveBeenCalledExactlyOnceWith(
+      environmentId,
+      "/workspace",
+      "file.txt",
+      "AUDIT7907NATIVE\n",
+    );
+    expect(onPendingChange).toHaveBeenLastCalledWith("file.txt", false);
+  });
+
+  it("persists rendered Markdown task changes after StrictMode setup replay", async () => {
+    mount({ ...defaultProps, relativePath: "README.md" });
+    const nextContents = setMarkdownTaskChecked("- [ ] task\n", 2, true);
+    changeHandler()(nextContents);
+    await vi.advanceTimersByTimeAsync(500);
+    expect(writeFile).toHaveBeenCalledExactlyOnceWith({
+      environmentId,
+      input: { cwd: "/workspace", relativePath: "README.md", contents: "- [x] task\n" },
+    });
+  });
+
+  it("keeps the debounce across rerenders of the same file", async () => {
+    mount();
+    changeHandler()("first");
+    await vi.advanceTimersByTimeAsync(300);
+    act(() =>
+      renderer!.update(
+        <StrictMode>
+          <FileSurface {...defaultProps} />
+        </StrictMode>,
+      ),
+    );
+    changeHandler()("latest");
+    await vi.advanceTimersByTimeAsync(499);
+    expect(writeFile).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(1);
+    expect(writeFile).toHaveBeenCalledTimes(1);
+    expect(writeFile.mock.calls[0]![0].input.contents).toBe("latest");
+  });
+
+  it("flushes on unmount and ignores a retired editor callback", async () => {
+    mount();
+    const retiredChange = changeHandler();
+    retiredChange("pending edit");
+    await act(async () => renderer!.unmount());
+    renderer = null;
+    retiredChange("stale editor contents");
+    await vi.runAllTimersAsync();
+    expect(writeFile).toHaveBeenCalledTimes(1);
+    expect(writeFile.mock.calls[0]![0].input.contents).toBe("pending edit");
+  });
+
+  it.each([
+    { relativePath: "other.txt" },
+    { cwd: "/other-workspace" },
+    { environmentId: EnvironmentId.make("other-environment") },
+  ])("retires callbacks when the file identity changes: %j", async (change) => {
+    mount();
+    const retiredChange = changeHandler();
+    retiredChange("old file edit");
+    const nextProps = { ...defaultProps, ...change };
+    act(() =>
+      renderer!.update(
+        <StrictMode>
+          <FileSurface {...nextProps} />
+        </StrictMode>,
+      ),
+    );
+    retiredChange("stale editor contents");
+    changeHandler()("new file edit");
+    await vi.runAllTimersAsync();
+    expect(writeFile.mock.calls.map(([request]) => request)).toEqual([
+      {
+        environmentId,
+        input: { cwd: "/workspace", relativePath: "file.txt", contents: "old file edit" },
+      },
+      {
+        environmentId: nextProps.environmentId,
+        input: {
+          cwd: nextProps.cwd,
+          relativePath: nextProps.relativePath,
+          contents: "new file edit",
+        },
+      },
+    ]);
+  });
+
+  it("does not reactivate a retired callback when the same file mounts again", async () => {
+    mount();
+    const retiredChange = changeHandler();
+    await act(async () => renderer!.unmount());
+    renderer = null;
+    mount();
+    retiredChange("stale contents");
+    changeHandler()("current contents");
+    await vi.runAllTimersAsync();
+    expect(writeFile).toHaveBeenCalledTimes(1);
+    expect(writeFile.mock.calls[0]![0].input.contents).toBe("current contents");
+  });
+});
diff --git a/apps/web/src/components/files/useFileSaveCoordinator.ts b/apps/web/src/components/files/useFileSaveCoordinator.ts
new file mode 100644
index 000000000000..852490cf5be4
--- /dev/null
+++ b/apps/web/src/components/files/useFileSaveCoordinator.ts
@@ -0,0 +1,56 @@
+import type { EnvironmentId } from "@t3tools/contracts";
+import { createRef, useEffect, useMemo } from "react";
+
+import { projectEnvironment } from "~/state/projects";
+import { useAtomCommand } from "~/state/use-atom-command";
+
+import { FileSaveCoordinator } from "./fileSaveCoordinator";
+import { confirmProjectFileQueryData } from "./projectFilesQueryState";
+
+const FILE_SAVE_DEBOUNCE_MS = 500;
+
+interface FileSaveOptions {
+  environmentId: EnvironmentId;
+  cwd: string;
+  relativePath: string;
+  onPendingChange: (relativePath: string, pending: boolean) => void;
+}
+
+export function useFileSaveCoordinator({
+  environmentId,
+  cwd,
+  relativePath,
+  onPendingChange,
+}: FileSaveOptions): Pick<FileSaveCoordinator, "change"> {
+  const writeFile = useAtomCommand(projectEnvironment.writeFile);
+  const session = useMemo(() => {
+    const coordinatorRef = createRef<FileSaveCoordinator>();
+    return {
+      change: (contents: string) => coordinatorRef.current?.change(contents),
+      setup: () => {
+        const coordinator = new FileSaveCoordinator({
+          debounceMs: FILE_SAVE_DEBOUNCE_MS,
+          onPendingChange: (pending) => onPendingChange(relativePath, pending),
+          persist: (nextContents) =>
+            writeFile({
+              environmentId,
+              input: { cwd, relativePath, contents: nextContents },
+            }),
+          onConfirmed: (confirmedContents) => {
+            confirmProjectFileQueryData(environmentId, cwd, relativePath, confirmedContents);
+          },
+        });
+        coordinatorRef.current = coordinator;
+        return () => {
+          coordinatorRef.current = null;
+          coordinator.dispose();
+        };
+      },
+    };
+  }, [cwd, environmentId, onPendingChange, relativePath, writeFile]);
+
+  // StrictMode replays effect setup. Retired file sessions stay inert, while the
+  // replay gets a fresh coordinator instead of reusing a disposed one.
+  useEffect(session.setup, [session]);
+  return session;
+}
diff --git a/apps/web/src/components/media/MediaVideoPlayer.tsx b/apps/web/src/components/media/MediaVideoPlayer.tsx
index f436beeb3855..90c18984e17b 100644
--- a/apps/web/src/components/media/MediaVideoPlayer.tsx
+++ b/apps/web/src/components/media/MediaVideoPlayer.tsx
@@ -127,7 +127,9 @@ export function MediaVideoPlayer({
         <span
           role="alert"
           className={cn(
-            "flex min-h-28 flex-col items-center justify-center gap-3 rounded-lg border border-border/40 bg-muted/40 p-4 text-center text-sm text-muted-foreground",
+            // Same 16:9 slot as the loading and playing states, so a failed or
+            // retried video does not move the rows below it.
+            "flex aspect-video max-h-full min-h-28 w-full flex-col items-center justify-center gap-3 rounded-lg border border-border/40 bg-muted/40 p-4 text-center text-sm text-muted-foreground",
             stateClassName,
           )}
         >
diff --git a/apps/web/src/components/onboarding/FirstRunGate.tsx b/apps/web/src/components/onboarding/FirstRunGate.tsx
new file mode 100644
index 000000000000..a9df5cb00b59
--- /dev/null
+++ b/apps/web/src/components/onboarding/FirstRunGate.tsx
@@ -0,0 +1,244 @@
+import { useAtomValue } from "@effect/atom-react";
+import { useLocation, useNavigate } from "@tanstack/react-router";
+import { Atom } from "effect/unstable/reactivity";
+import { RotateCcwIcon } from "lucide-react";
+import { useEffect, useLayoutEffect, useState } from "react";
+
+import {
+  ensureClientSettingsHydrated,
+  useClientSettings,
+  useClientSettingsHydrationStatus,
+} from "../../hooks/useSettings";
+import { mountOnboardingTheme } from "../../hooks/useTheme";
+import { useCompleteOnboarding } from "../../onboarding/firstRun";
+import {
+  isFirstRunWorkspaceProvenanceAuthoritative,
+  isFreshFirstRunWorkspace,
+  resolveFirstRunDecision,
+  resolveHostedFirstRunDecision,
+  transitionFirstRunGateState,
+  type FirstRunGateState,
+} from "../../onboarding/firstRun.logic";
+import {
+  useAllEnvironmentShellsBootstrapped,
+  useProjects,
+  useThreadShells,
+} from "../../state/entities";
+import { useEnvironments } from "../../state/environments";
+import { environmentProjects } from "../../state/projects";
+import { primaryServerConfigAtom, primaryServerWelcomeAtom } from "../../state/server";
+import { environmentShell } from "../../state/shell";
+import { environmentThreadShells } from "../../state/threads";
+import { Button } from "../ui/button";
+
+/**
+ * Holds back authenticated and hosted app trees until the first-run decision
+ * is known, so a fresh install never flashes the main screen before the wizard.
+ * Nothing renders while pending — no shell, no EventRouter (whose welcome
+ * payload would otherwise navigate into a thread), no dialogs.
+ *
+ * Decision order: a set `onboardingCompletedAt` resolves to the app as soon as
+ * settings hydrate (the common case, no server round-trip). A `null` flag also
+ * covers installs that predate the field, so it alone is not enough — the gate
+ * waits for environment shells to bootstrap and inspects the workspace.
+ * Hosted mode instead checks its saved environment catalog. A timeout shows
+ * recovery for an unreachable primary server without mounting the app tree.
+ */
+
+const FIRST_RUN_DECISION_TIMEOUT_MS = 4_000;
+
+const primaryShellLiveAtom = Atom.make((get) => {
+  const serverConfig = get(primaryServerConfigAtom);
+  return (
+    serverConfig !== null &&
+    get(environmentShell.stateValueAtom(serverConfig.environment.environmentId)).status === "live"
+  );
+}).pipe(Atom.withLabel("web-onboarding-primary-shell-live"));
+
+const workspaceEvidenceLiveAtom = Atom.make((get) => {
+  const environmentIds = new Set([
+    ...get(environmentProjects.projectsAtom).map((project) => project.environmentId),
+    ...get(environmentThreadShells.threadShellsAtom).map((thread) => thread.environmentId),
+  ]);
+
+  for (const environmentId of environmentIds) {
+    if (get(environmentShell.stateValueAtom(environmentId)).status !== "live") {
+      return false;
+    }
+  }
+
+  return true;
+}).pipe(Atom.withLabel("web-onboarding-workspace-evidence-live"));
+
+export function FirstRunGate({
+  enabled,
+  hostedStatic,
+  children,
+}: {
+  readonly enabled: boolean;
+  readonly hostedStatic: boolean;
+  readonly children: React.ReactNode;
+}) {
+  const navigate = useNavigate();
+  const pathname = useLocation({ select: (location) => location.pathname });
+  const hydrationStatus = useClientSettingsHydrationStatus();
+  const hydrated = hydrationStatus === "ready";
+  const completeOnboarding = useCompleteOnboarding();
+  const onboardingCompletedAt = useClientSettings((settings) => settings.onboardingCompletedAt);
+  const bootstrapped = useAllEnvironmentShellsBootstrapped();
+  const { environments, isReady: environmentCatalogReady } = useEnvironments();
+  const projects = useProjects();
+  const threads = useThreadShells();
+  const serverConfig = useAtomValue(primaryServerConfigAtom);
+  const serverWelcome = useAtomValue(primaryServerWelcomeAtom);
+  const primaryShellLive = useAtomValue(primaryShellLiveAtom);
+  const workspaceEvidenceLive = useAtomValue(workspaceEvidenceLiveAtom);
+  // Within a session settings stay hydrated, so remounts (e.g. returning from
+  // the wizard) resolve synchronously instead of blanking a frame.
+  const [gateState, setGateState] = useState<FirstRunGateState>(() => ({
+    decision:
+      (!enabled && !hostedStatic) || (hydrated && onboardingCompletedAt !== null)
+        ? "app"
+        : "pending",
+    stalled: false,
+  }));
+  const { decision, stalled } = gateState;
+  const settingsReadFailed = hydrationStatus === "failed" || hydrationStatus === "retrying";
+  const ownsOnboardingTheme = settingsReadFailed || stalled || decision === "wizard";
+
+  useLayoutEffect(() => {
+    if (!ownsOnboardingTheme) return;
+    return mountOnboardingTheme();
+  }, [ownsOnboardingTheme]);
+
+  // A workspace still counts as fresh when its only content is the server's
+  // own cwd auto-bootstrap: web mode creates a project + thread from cwd at
+  // startup (`autoBootstrapProjectFromCwd` defaults on there), so "no
+  // projects at all" would mean `npx t3` users never see the wizard. Any
+  // other project, more than one thread, or state in a non-primary
+  // environment is real user state — the aggregate hooks span every
+  // environment, and a saved remote's project must never read as "the
+  // bootstrap project" just because its root string matches the primary cwd.
+  const serverCwd = serverConfig?.cwd ?? null;
+  const primaryEnvironmentId = serverConfig?.environment.environmentId ?? null;
+  const workspaceFresh = isFreshFirstRunWorkspace({
+    primaryEnvironmentId,
+    serverCwd,
+    bootstrapProjectId: serverWelcome?.bootstrapProjectId,
+    bootstrapThreadId: serverWelcome?.bootstrapThreadId,
+    bootstrapProjectCreated: serverWelcome?.bootstrapProjectCreated,
+    bootstrapThreadCreated: serverWelcome?.bootstrapThreadCreated,
+    projects,
+    threads,
+  });
+
+  const { decision: nextDecision, persistCompletion } = hostedStatic
+    ? resolveHostedFirstRunDecision({
+        hydrated,
+        completed: onboardingCompletedAt !== null,
+        catalogReady: environmentCatalogReady,
+        environmentCount: environments.length,
+      })
+    : resolveFirstRunDecision({
+        enabled,
+        hydrated,
+        completed: onboardingCompletedAt !== null,
+        bootstrapped,
+        authoritative: primaryShellLive,
+        workspaceAuthoritative: workspaceEvidenceLive,
+        workspaceProvenanceAuthoritative: isFirstRunWorkspaceProvenanceAuthoritative({
+          welcomeReceived: serverWelcome !== null,
+          bootstrapStatus: serverWelcome?.bootstrapStatus ?? null,
+        }),
+        catalogReady: environmentCatalogReady,
+        serverConfigAvailable: serverConfig !== null,
+        workspaceFresh,
+        projectCount: projects.length,
+        threadCount: threads.length,
+      });
+
+  useEffect(() => {
+    if (decision === "wizard" || !hydrated) return;
+
+    if (persistCompletion && onboardingCompletedAt === null) {
+      void completeOnboarding().catch(() => undefined);
+    }
+
+    setGateState((state) =>
+      transitionFirstRunGateState(state, { type: "evidence", decision: nextDecision }),
+    );
+  }, [
+    completeOnboarding,
+    decision,
+    hydrated,
+    nextDecision,
+    onboardingCompletedAt,
+    persistCompletion,
+  ]);
+
+  // A stalled server read gets a recovery screen, but never mounts the app.
+  // The timer starts after settings hydrate so slow local hydration does not
+  // show a false connection failure.
+  useEffect(() => {
+    if (!enabled || decision !== "pending" || !hydrated) return;
+    const timer = window.setTimeout(
+      () => setGateState((state) => transitionFirstRunGateState(state, { type: "timeout" })),
+      FIRST_RUN_DECISION_TIMEOUT_MS,
+    );
+    return () => window.clearTimeout(timer);
+  }, [decision, enabled, hydrated]);
+
+  useEffect(() => {
+    if (decision === "wizard" && pathname !== "/welcome") {
+      void navigate({ to: "/welcome", replace: true });
+    }
+  }, [decision, navigate, pathname]);
+
+  if (settingsReadFailed) {
+    return <FirstRunRecovery reason="settings" retrying={hydrationStatus === "retrying"} />;
+  }
+  if (decision !== "app") {
+    return stalled ? <FirstRunRecovery reason="connection" /> : null;
+  }
+  return children;
+}
+
+function FirstRunRecovery({
+  reason,
+  retrying = false,
+}: {
+  readonly reason: "settings" | "connection";
+  readonly retrying?: boolean;
+}) {
+  const settingsReadFailed = reason === "settings";
+  return (
+    <main className="flex h-dvh min-h-0 items-center justify-center bg-background px-6 text-foreground">
+      <div className="flex max-w-sm flex-col items-center text-center">
+        <h1 className="text-lg font-semibold">
+          {settingsReadFailed ? "Could not read settings" : "Still connecting"}
+        </h1>
+        <p className="mt-2 text-sm text-muted-foreground">
+          {settingsReadFailed
+            ? "Your saved settings could not be loaded."
+            : "T3 Code could not confirm this workspace."}
+        </p>
+        <Button
+          className="mt-5"
+          size="sm"
+          variant="outline"
+          disabled={retrying}
+          onClick={() => {
+            if (settingsReadFailed) {
+              void ensureClientSettingsHydrated().catch(() => undefined);
+            } else {
+              window.location.reload();
+            }
+          }}
+        >
+          <RotateCcwIcon />
+          {settingsReadFailed ? "Retry" : "Reload"}
+        </Button>
+      </div>
+    </main>
+  );
+}
diff --git a/apps/web/src/components/onboarding/WelcomeWizard.tsx b/apps/web/src/components/onboarding/WelcomeWizard.tsx
new file mode 100644
index 000000000000..cb31ef259667
--- /dev/null
+++ b/apps/web/src/components/onboarding/WelcomeWizard.tsx
@@ -0,0 +1,1478 @@
+import { useAuth } from "@clerk/react";
+import { useAtomValue } from "@effect/atom-react";
+import type {
+  AgentSessionProjectCandidate,
+  EnvironmentId,
+  ProjectId,
+  ScopedProjectRef,
+  ServerConfig,
+  ServerProvider,
+} from "@t3tools/contracts";
+import { scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime/environment";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import { CommandId, ProviderDriverKind, ThreadId } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
+import {
+  ArrowRightIcon,
+  CheckIcon,
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  CloudIcon,
+  CopyIcon,
+  LinkIcon,
+  MonitorIcon,
+  TerminalIcon,
+  type LucideIcon,
+} from "lucide-react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+
+import { TYPOGRAPHY_ADVANCED_STORAGE_KEY } from "../../appearanceFonts";
+import { useLocalStorage } from "../../hooks/useLocalStorage";
+import { mountOnboardingTheme } from "../../hooks/useTheme";
+import { hasCloudPublicConfig } from "../../cloud/publicConfig";
+import { useT3ConnectAuthPrompt } from "../clerk/useT3ConnectAuthPrompt";
+import { useCompleteOnboarding } from "../../onboarding/firstRun";
+import {
+  partitionOnboardingProjects,
+  resolveOnboardingLandingProject,
+  resolveOnboardingProjectId,
+} from "../../onboarding/projectImport.logic";
+import {
+  getOnboardingProviderState,
+  resolveOnboardingProviderLoginCommand,
+  selectOnboardingProvidersByDriver,
+} from "../../onboarding/providerReadiness.logic";
+import {
+  isOnboardingRelayEnvironment,
+  resolveOnboardingTargetEnvironment,
+} from "../../onboarding/targetEnvironment.logic";
+import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
+import { newProjectId, randomUUID } from "../../lib/utils";
+import { resolveDefaultProviderModelSelection } from "../../providerInstances";
+import { agentSessionImport, agentSessionScan } from "../../state/agentSessions";
+import { readProjects, useProjects } from "../../state/entities";
+import { useEnvironments, usePrimaryEnvironment } from "../../state/environments";
+import { useEnvironmentQuery } from "../../state/query";
+import { projectEnvironment } from "../../state/projects";
+import { serverEnvironment } from "../../state/server";
+import { terminalEnvironment } from "../../state/terminal";
+import { useAtomCommand } from "../../state/use-atom-command";
+import { connectPairing } from "../../connection/onboarding";
+import { isElectron } from "../../env";
+import { formatRelativeTimeLabel } from "../../timestampFormat";
+import { getProviderSummary } from "../settings/providerStatus";
+import { getDriverOption } from "../settings/providerDriverMeta";
+import { CloudEnvironmentConnectRows } from "../cloud/CloudEnvironmentConnectList";
+import { TerminalViewport } from "../ThreadTerminalDrawer";
+import { Button } from "../ui/button";
+import { Checkbox } from "../ui/checkbox";
+import { Collapsible, CollapsiblePanel, CollapsibleTrigger } from "../ui/collapsible";
+import { Input } from "../ui/input";
+import { toastManager } from "../ui/toast";
+import { cn } from "../../lib/utils";
+
+/**
+ * First-run welcome wizard. Rendered as the full-screen `/welcome` route on a
+ * fresh install (no completed-onboarding flag, empty workspace). Flow per the
+ * onboarding overhaul spec: connection choice → sign-in/pair (remote paths) →
+ * agent setup with inline install terminal → project import → main screen.
+ * Every step past the connection gate is skippable; the whole wizard is
+ * re-runnable by clearing the flag.
+ */
+
+type WizardStep = "connection" | "connect-machines" | "pair-direct" | "agents" | "import";
+
+type ConnectionMode = "local" | "connect" | "direct";
+
+/**
+ * The machine the agent and import steps run against. Local mode targets the
+ * primary environment; the remote modes prefer the machine the user just
+ * connected (the most recently added connected non-primary environment), so
+ * probing and import happen where their code lives rather than on the local
+ * server that happens to serve the app. Deliberately not a persisted
+ * "primary machine" concept — just whichever machine fits the chosen path
+ * right now, labeled inline on each step.
+ */
+function useOnboardingTargetEnvironment(
+  mode: ConnectionMode,
+  pairedEnvironmentId: EnvironmentId | null,
+) {
+  const { environments } = useEnvironments();
+  const primaryEnvironment = usePrimaryEnvironment();
+  return resolveOnboardingTargetEnvironment({
+    mode,
+    environments,
+    primaryEnvironment,
+    pairedEnvironmentId,
+  });
+}
+
+const AGENT_ONBOARDING_THREAD_ID = ThreadId.make("onboarding-agent-setup");
+const ONBOARDING_STAGES = ["Connect", "Agents", "Projects"] as const;
+const SCAN_LIMIT_MESSAGE = "Scan limit reached. Some projects or conversations may be missing.";
+
+export function WelcomeWizard({
+  localAvailable,
+  onDone,
+}: {
+  /**
+   * Whether the "Local Only" card is offered. True whenever the app is served
+   * by an authenticated primary server — desktop, `npx t3`, or a dev server —
+   * since that server is "this machine" regardless of the hostname the app
+   * was opened from. Only hosted-static (app.t3.codes) has no local server.
+   */
+  readonly localAvailable: boolean;
+  readonly onDone: (projectRef?: ScopedProjectRef) => void;
+}) {
+  useLayoutEffect(() => mountOnboardingTheme(), []);
+  const completeOnboarding = useCompleteOnboarding();
+  const [step, setStep] = useState<WizardStep>("connection");
+  const [mode, setMode] = useState<ConnectionMode>("local");
+  const [pairedEnvironmentId, setPairedEnvironmentId] = useState<EnvironmentId | null>(null);
+  const finishingPromiseRef = useRef<Promise<boolean> | null>(null);
+  const completionErrorToastIdRef = useRef<ReturnType<typeof toastManager.add> | null>(null);
+  const targetEnvironment = useOnboardingTargetEnvironment(mode, pairedEnvironmentId);
+  const stageIndex = step === "agents" ? 1 : step === "import" ? 2 : 0;
+  const finish = useCallback(
+    (projectRef?: ScopedProjectRef) => {
+      if (finishingPromiseRef.current !== null) return finishingPromiseRef.current;
+      if (completionErrorToastIdRef.current !== null) {
+        toastManager.close(completionErrorToastIdRef.current);
+        completionErrorToastIdRef.current = null;
+      }
+
+      const completion = completeOnboarding()
+        .then(() => {
+          if (completionErrorToastIdRef.current !== null) {
+            toastManager.close(completionErrorToastIdRef.current);
+            completionErrorToastIdRef.current = null;
+          }
+          onDone(projectRef);
+          return true;
+        })
+        .catch(() => {
+          const errorToast = {
+            type: "error",
+            title: "Could not finish setup",
+            description: "Your settings could not be saved. Try again.",
+          } as const;
+          if (completionErrorToastIdRef.current === null) {
+            completionErrorToastIdRef.current = toastManager.add(errorToast);
+          } else {
+            toastManager.update(completionErrorToastIdRef.current, errorToast);
+          }
+          return false;
+        })
+        .finally(() => {
+          if (finishingPromiseRef.current === completion) {
+            finishingPromiseRef.current = null;
+          }
+        });
+      finishingPromiseRef.current = completion;
+      return completion;
+    },
+    [completeOnboarding, onDone],
+  );
+
+  return (
+    <div className="flex h-dvh min-h-0 flex-col overflow-hidden bg-black text-foreground">
+      {isElectron ? (
+        <div
+          aria-hidden
+          className="drag-region h-[var(--workspace-topbar-height)] min-h-[var(--workspace-topbar-height)] shrink-0 wco:pr-[var(--workspace-native-controls-inset)]"
+        />
+      ) : null}
+      <main className="min-h-0 flex-1 overflow-x-hidden overflow-y-auto">
+        <div className="mx-auto grid min-h-full w-full max-w-5xl content-center gap-10 px-6 py-12 sm:grid-cols-[170px_minmax(0,1fr)] sm:gap-14 sm:px-10 lg:px-12">
+          <aside className="flex min-w-0 flex-col justify-between sm:min-h-72">
+            <nav
+              aria-label="Setup progress"
+              className="flex flex-wrap gap-x-5 gap-y-1 sm:flex-col sm:gap-1"
+            >
+              {ONBOARDING_STAGES.map((stage, index) => (
+                <div
+                  key={stage}
+                  aria-current={index === stageIndex ? "step" : undefined}
+                  className={cn(
+                    "flex min-h-9 items-center gap-2.5 text-sm",
+                    index < stageIndex
+                      ? "text-success-foreground"
+                      : index === stageIndex
+                        ? "text-foreground"
+                        : "text-muted-foreground/60",
+                  )}
+                >
+                  {index < stageIndex ? (
+                    <CheckIcon className="size-3.5" />
+                  ) : (
+                    <span className="w-3.5 font-mono text-xs">0{index + 1}</span>
+                  )}
+                  <span>{stage}</span>
+                </div>
+              ))}
+            </nav>
+            {targetEnvironment ? (
+              <div className="mt-8 hidden items-center gap-2 text-xs text-muted-foreground sm:flex">
+                <span className="size-1.5 rounded-full bg-success" />
+                <span className="truncate">{targetEnvironment.label}</span>
+              </div>
+            ) : null}
+          </aside>
+
+          <section className="min-w-0">
+            {step === "connection" ? (
+              <ConnectionStep
+                localAvailable={localAvailable}
+                localLabel={targetEnvironment?.label ?? "This computer"}
+                onLocal={() => {
+                  setMode("local");
+                  setPairedEnvironmentId(null);
+                  setStep("agents");
+                }}
+                onConnect={() => {
+                  setMode("connect");
+                  setPairedEnvironmentId(null);
+                  setStep("connect-machines");
+                }}
+                onDirect={() => {
+                  setMode("direct");
+                  setPairedEnvironmentId(null);
+                  setStep("pair-direct");
+                }}
+              />
+            ) : step === "connect-machines" ? (
+              <ConnectMachinesStep
+                onBack={() => setStep("connection")}
+                onContinue={() => setStep("agents")}
+              />
+            ) : step === "pair-direct" ? (
+              <PairDirectStep
+                onBack={() => setStep("connection")}
+                onPaired={(environmentId) => {
+                  setPairedEnvironmentId(environmentId);
+                  setStep("agents");
+                }}
+              />
+            ) : step === "agents" ? (
+              <AgentsStep
+                mode={mode}
+                pairedEnvironmentId={pairedEnvironmentId}
+                onBack={() =>
+                  setStep(
+                    mode === "local"
+                      ? "connection"
+                      : mode === "connect"
+                        ? "connect-machines"
+                        : "pair-direct",
+                  )
+                }
+                onContinue={() => setStep("import")}
+                onSkip={() => setStep("import")}
+              />
+            ) : (
+              <ImportStep
+                mode={mode}
+                pairedEnvironmentId={pairedEnvironmentId}
+                onBack={() => setStep("agents")}
+                onDone={finish}
+              />
+            )}
+          </section>
+        </div>
+      </main>
+    </div>
+  );
+}
+
+// ── Step 1: connection choice ────────────────────────────────
+
+function ConnectionStep({
+  localAvailable,
+  localLabel,
+  onLocal,
+  onConnect,
+  onDirect,
+}: {
+  readonly localAvailable: boolean;
+  readonly localLabel: string;
+  readonly onLocal: () => void;
+  readonly onConnect: () => void;
+  readonly onDirect: () => void;
+}) {
+  const cloudEnabled = hasCloudPublicConfig();
+  const [choice, setChoice] = useState<"local" | "connect" | "direct">(
+    localAvailable ? "local" : cloudEnabled ? "connect" : "direct",
+  );
+
+  const advance = () => {
+    if (choice === "local") onLocal();
+    else if (choice === "connect") onConnect();
+    else onDirect();
+  };
+
+  return (
+    <>
+      <h1 className="text-3xl font-semibold text-foreground sm:text-[34px]">Where is your code?</h1>
+      <p className="mt-2.5 text-sm text-muted-foreground">Choose where your agents will run.</p>
+      <div className="mt-8 border-t border-border">
+        {localAvailable ? (
+          <ConnectionOption
+            icon={MonitorIcon}
+            title="This computer"
+            description={localLabel}
+            truncateDescription
+            detail="No account"
+            selected={choice === "local"}
+            onSelect={() => setChoice("local")}
+          />
+        ) : null}
+        {cloudEnabled ? (
+          <ConnectionOption
+            icon={CloudIcon}
+            title="T3 Connect"
+            description="Your computers, wherever you are"
+            detail="Sign in"
+            selected={choice === "connect"}
+            onSelect={() => setChoice("connect")}
+          />
+        ) : null}
+        <ConnectionOption
+          icon={LinkIcon}
+          title="Pair a server"
+          description="Local network or Tailscale"
+          detail="Pairing link"
+          selected={choice === "direct"}
+          onSelect={() => setChoice("direct")}
+        />
+      </div>
+      <div className="mt-7 flex justify-end">
+        <Button className="gap-2" onClick={advance}>
+          Continue
+          <ArrowRightIcon className="size-3.5" />
+        </Button>
+      </div>
+    </>
+  );
+}
+
+function ConnectionOption({
+  icon: Icon,
+  title,
+  description,
+  truncateDescription = false,
+  detail,
+  selected,
+  onSelect,
+}: {
+  readonly icon: LucideIcon;
+  readonly title: string;
+  readonly description: string;
+  readonly truncateDescription?: boolean;
+  readonly detail: string;
+  readonly selected: boolean;
+  readonly onSelect: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      aria-pressed={selected}
+      onClick={onSelect}
+      className={cn(
+        "group flex min-h-20 w-full cursor-pointer items-center gap-4 border-b border-border px-1 py-3 text-left transition-colors",
+        "outline-none focus-visible:bg-accent focus-visible:ring-1 focus-visible:ring-ring",
+        selected
+          ? "text-foreground"
+          : "text-muted-foreground hover:bg-accent/50 hover:text-foreground",
+      )}
+    >
+      <Icon
+        className={cn("size-[18px]", selected ? "text-success-foreground" : "text-icon-muted")}
+      />
+      <span className="min-w-0 flex-1">
+        <span className="block text-sm font-medium">{title}</span>
+        <span
+          className={cn(
+            "mt-1 block text-xs text-muted-foreground",
+            truncateDescription ? "truncate" : "break-words whitespace-normal",
+          )}
+        >
+          {description}
+        </span>
+      </span>
+      <span className="hidden text-xs text-muted-foreground sm:block">{detail}</span>
+      {selected ? (
+        <CheckIcon className="size-4 text-success-foreground" />
+      ) : (
+        <span className="size-4" />
+      )}
+    </button>
+  );
+}
+
+// ── Step 2: T3 Connect (sign in, then connect machines) ──────
+
+const CONNECT_LOGIN_COMMAND = "npx t3 connect";
+
+/**
+ * Sign-in and machine-connection combined: signed out shows the Clerk prompt,
+ * signed in forks on account state — zero connected machines blocks on the
+ * `npx t3 connect` command and auto-advance is left to the user pressing
+ * Continue once their machine appears; existing machines show a confirmation
+ * list with the command folded away. There is deliberately no "primary
+ * machine" selection.
+ */
+function ConnectMachinesStep({
+  onBack,
+  onContinue,
+}: {
+  readonly onBack: () => void;
+  readonly onContinue: () => void;
+}) {
+  // Mirrors ManagedRelayAuthProvider: a pending Clerk session must not read
+  // as signed-out mid-transition.
+  const { isLoaded, isSignedIn } = useAuth({ treatPendingAsSignedOut: false });
+  const { openAuthPrompt } = useT3ConnectAuthPrompt();
+  const { environments } = useEnvironments();
+  const primaryEnvironment = usePrimaryEnvironment();
+  const savedEnvironments = environments.filter(isOnboardingRelayEnvironment);
+  // Only a live connection counts: a saved-but-offline machine must not show
+  // the "connected" confirmation (the agents step would find nothing to
+  // probe). Its row still renders in the list either way.
+  const hasRemoteMachines = savedEnvironments.some(
+    (environment) => environment.connection.phase === "connected",
+  );
+
+  if (!isLoaded) {
+    return <StepShell title="Sign in to T3 Connect" onBack={onBack} />;
+  }
+
+  if (!isSignedIn) {
+    return (
+      <StepShell
+        title="Sign in to T3 Connect"
+        description="Connect your computers with one account."
+        onBack={onBack}
+      >
+        <div className="mt-6">
+          <Button onClick={openAuthPrompt}>Sign in</Button>
+        </div>
+      </StepShell>
+    );
+  }
+
+  return (
+    <StepShell
+      title={hasRemoteMachines ? "Your computers" : "Connect your computer"}
+      description={
+        hasRemoteMachines
+          ? "Connected to your T3 account."
+          : "Run this command on the computer with your code."
+      }
+      onBack={onBack}
+    >
+      {hasRemoteMachines ? (
+        <>
+          <div className="mt-6 overflow-hidden border-y border-border">
+            <CloudEnvironmentConnectRows
+              primaryEnvironmentId={primaryEnvironment?.environmentId ?? null}
+              savedEnvironments={savedEnvironments}
+              showSavedEnvironments
+              empty={null}
+            />
+          </div>
+          <Collapsible className="mt-4">
+            <CollapsibleTrigger className="group flex items-center gap-1 text-xs text-muted-foreground transition-colors hover:text-foreground">
+              <ChevronRightIcon className="size-3.5 transition-transform duration-200 group-data-panel-open:rotate-90" />
+              Add another machine
+            </CollapsibleTrigger>
+            <CollapsiblePanel>
+              <CommandBlock command={CONNECT_LOGIN_COMMAND} className="mt-2" />
+              <p className="mt-2 text-xs text-muted-foreground">
+                Keep T3 Code running on that computer. If it is not running, open T3 Code or run{" "}
+                <code className="font-mono">npx t3 serve</code>.
+              </p>
+            </CollapsiblePanel>
+          </Collapsible>
+          <div className="mt-7 flex justify-end">
+            <Button onClick={onContinue}>Continue</Button>
+          </div>
+        </>
+      ) : (
+        <>
+          <CommandBlock command={CONNECT_LOGIN_COMMAND} className="mt-7" prominent />
+          <p className="mt-2 text-xs text-muted-foreground">
+            Keep T3 Code running on that computer. If it is not running, open T3 Code or run{" "}
+            <code className="font-mono">npx t3 serve</code>.
+          </p>
+          <div className="mt-5 overflow-hidden border-y border-border">
+            <CloudEnvironmentConnectRows
+              primaryEnvironmentId={primaryEnvironment?.environmentId ?? null}
+              savedEnvironments={savedEnvironments}
+              showSavedEnvironments
+              refreshWhileEmpty
+              empty={
+                <p className="px-1 py-4 text-xs text-muted-foreground">
+                  Waiting for your computer to connect.
+                </p>
+              }
+            />
+          </div>
+          <div className="mt-7 flex flex-wrap items-center justify-between gap-3">
+            <Button variant="ghost-muted" onClick={onContinue}>
+              Skip for now
+            </Button>
+            <div className="flex flex-wrap items-center justify-end gap-3">
+              <span className="hidden text-xs text-muted-foreground sm:block">
+                Waiting for connection
+              </span>
+              <Button disabled>Continue</Button>
+            </div>
+          </div>
+        </>
+      )}
+    </StepShell>
+  );
+}
+
+// ── Step 2′: Direct pairing ──────────────────────────────────
+
+/**
+ * Server-minted pairing, D-B treatment: numbered steps, `t3 pair` on the
+ * server, paste the URL here. Registers the remote environment in this
+ * browser's catalog (same path the hosted /pair surface uses).
+ */
+function PairDirectStep({
+  onBack,
+  onPaired,
+}: {
+  readonly onBack: () => void;
+  readonly onPaired: (environmentId: EnvironmentId) => void;
+}) {
+  const connectPairingEnvironment = useAtomCommand(connectPairing, { reportFailure: false });
+  const [pairingUrl, setPairingUrl] = useState("");
+  const [errorMessage, setErrorMessage] = useState("");
+  const [isPairing, setIsPairing] = useState(false);
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const submit = async () => {
+    setIsPairing(true);
+    setErrorMessage("");
+    const result = await connectPairingEnvironment({ pairingUrl });
+    if (!mountedRef.current) return;
+    setIsPairing(false);
+    if (result._tag === "Success") {
+      onPaired(result.value);
+      return;
+    }
+    if (isAtomCommandInterrupted(result)) return;
+    const cause = squashAtomCommandFailure(result);
+    setErrorMessage(cause instanceof Error ? cause.message : "Pairing failed.");
+  };
+
+  return (
+    <StepShell
+      title="Pair a server"
+      description="Connect with a one-time pairing link."
+      onBack={onBack}
+    >
+      <div className="mt-7 space-y-5">
+        <div>
+          <p className="text-sm text-muted-foreground">
+            <span className="font-mono text-muted-foreground/70">01</span> Run this on your server
+          </p>
+          <CommandBlock command="npx t3 pair" className="mt-2" />
+          <p className="mt-2 text-xs text-muted-foreground">
+            Start the server with <code className="font-mono">npx t3 serve</code> first. Add{" "}
+            <code className="font-mono">--tailscale</code> to use your tailnet.
+          </p>
+        </div>
+        <div>
+          <label className="block text-sm text-muted-foreground" htmlFor="onboarding-pairing-url">
+            <span className="font-mono text-muted-foreground/70">02</span> Paste the pairing link
+          </label>
+          <Input
+            id="onboarding-pairing-url"
+            className="mt-2"
+            size="lg"
+            autoCapitalize="none"
+            autoComplete="off"
+            autoCorrect="off"
+            spellCheck={false}
+            nativeInput
+            disabled={isPairing}
+            placeholder="https://your-server:5230/pair#token=…"
+            value={pairingUrl}
+            onChange={(event) => setPairingUrl(event.currentTarget.value)}
+            onKeyDown={(event) => {
+              if (event.nativeEvent.isComposing || event.keyCode === 229) return;
+              if (event.key === "Enter" && pairingUrl.trim().length > 0) void submit();
+            }}
+          />
+        </div>
+        {errorMessage ? (
+          <div className="rounded-lg border border-destructive/30 bg-destructive/6 px-3 py-2 text-sm text-destructive">
+            {errorMessage}
+          </div>
+        ) : null}
+      </div>
+      <div className="mt-7 flex justify-end">
+        <Button
+          disabled={isPairing || pairingUrl.trim().length === 0}
+          onClick={() => void submit()}
+        >
+          {isPairing ? "Pairing..." : "Connect"}
+        </Button>
+      </div>
+    </StepShell>
+  );
+}
+
+// ── Step 3: agents ───────────────────────────────────────────
+
+const PRIMARY_AGENT_DRIVERS = ["claudeAgent", "codex"] as const;
+type OnboardingAgentDriver = (typeof PRIMARY_AGENT_DRIVERS)[number];
+
+const AGENT_INSTALL_COMMANDS: Record<OnboardingAgentDriver, string> = {
+  claudeAgent: "npm install -g @anthropic-ai/claude-code",
+  codex: "npm install -g @openai/codex",
+};
+
+/** Setup values stay fixed while provider probes refresh the surrounding cards. */
+interface AgentTerminalSession {
+  readonly environmentId: EnvironmentId;
+  readonly driver: OnboardingAgentDriver;
+  readonly providerInstanceId: ServerProvider["instanceId"];
+  readonly cwd: string;
+  readonly command: string;
+  readonly keybindings: ServerConfig["keybindings"];
+}
+
+/**
+ * Claude Code and Codex use live probe status. Install opens the built-in terminal inline
+ * with the command pre-typed — the update RPC can't install a binary that
+ * isn't there yet (it infers the package manager from the installed binary's
+ * path), and the terminal also handles the interactive login that follows.
+ */
+function AgentsStep({
+  mode,
+  pairedEnvironmentId,
+  onBack,
+  onContinue,
+  onSkip,
+}: {
+  readonly mode: ConnectionMode;
+  readonly pairedEnvironmentId: EnvironmentId | null;
+  readonly onBack: () => void;
+  readonly onContinue: () => void;
+  readonly onSkip: () => void;
+}) {
+  const targetEnvironment = useOnboardingTargetEnvironment(mode, pairedEnvironmentId);
+  if (targetEnvironment === null) {
+    return (
+      <StepShell
+        title="Your agents"
+        description="Waiting for this computer to connect."
+        onBack={onBack}
+      >
+        <div className="mt-6 flex justify-end">
+          <Button variant="ghost-muted" onClick={onSkip}>
+            Skip for now
+          </Button>
+        </div>
+      </StepShell>
+    );
+  }
+  return (
+    <ConnectedAgentsStep
+      key={targetEnvironment.environmentId}
+      environmentId={targetEnvironment.environmentId}
+      machineLabel={targetEnvironment.label}
+      onBack={onBack}
+      onContinue={onContinue}
+      onSkip={onSkip}
+    />
+  );
+}
+
+function ConnectedAgentsStep({
+  environmentId,
+  machineLabel,
+  onBack,
+  onContinue,
+  onSkip,
+}: {
+  readonly environmentId: EnvironmentId;
+  readonly machineLabel: string;
+  readonly onBack: () => void;
+  readonly onContinue: () => void;
+  readonly onSkip: () => void;
+}) {
+  const providers = useAtomValue(serverEnvironment.providersValueAtom(environmentId));
+  const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
+    reportFailure: false,
+  });
+  const serverConfig = useAtomValue(serverEnvironment.configValueAtom(environmentId));
+  const [terminalSession, setTerminalSession] = useState<AgentTerminalSession | null>(null);
+
+  // Re-probe on entry so freshly installed CLIs show up without a manual
+  // refresh; harmless when nothing changed (single-flighted per environment).
+  useEffect(() => {
+    void refreshProviders({ environmentId, input: {} });
+  }, [environmentId, refreshProviders]);
+
+  const byDriver = useMemo(() => selectOnboardingProvidersByDriver(providers), [providers]);
+
+  const primaryAgents = PRIMARY_AGENT_DRIVERS.map((driver) => ({
+    driver,
+    provider: byDriver.get(driver),
+  }));
+  const readyCount = primaryAgents.filter(
+    ({ provider }) => getOnboardingProviderState(provider) === "ready",
+  ).length;
+  return (
+    <StepShell title="Your agents" description={`Detected on ${machineLabel}.`} onBack={onBack}>
+      <div className="mt-7 border-t border-border">
+        {primaryAgents.map(({ driver, provider }) => (
+          <AgentCard
+            key={driver}
+            driver={driver}
+            provider={provider}
+            terminalOpen={terminalSession?.driver === driver}
+            terminalAvailable={serverConfig !== null}
+            onOpenTerminal={() => {
+              if (provider === undefined || serverConfig === null) return;
+              setTerminalSession({
+                environmentId,
+                driver,
+                providerInstanceId: provider.instanceId,
+                cwd: serverConfig.cwd,
+                command: provider.installed
+                  ? resolveOnboardingProviderLoginCommand(
+                      provider,
+                      serverConfig.settings,
+                      serverConfig.environment.platform.os,
+                    )
+                  : AGENT_INSTALL_COMMANDS[driver],
+                keybindings: serverConfig.keybindings,
+              });
+            }}
+          />
+        ))}
+      </div>
+      {terminalSession !== null ? (
+        <AgentInstallTerminal
+          key={`${terminalSession.environmentId}:${terminalSession.providerInstanceId}:${terminalSession.driver}`}
+          session={terminalSession}
+          onClose={() => {
+            setTerminalSession(null);
+            void refreshProviders({ environmentId, input: {} });
+          }}
+        />
+      ) : null}
+      <div className="mt-7 flex flex-wrap items-center justify-between gap-3">
+        <Button variant="ghost-muted" onClick={onSkip}>
+          Skip
+        </Button>
+        <div className="flex flex-wrap items-center justify-end gap-3">
+          <span className="text-xs text-muted-foreground">
+            {readyCount} of {primaryAgents.length} ready
+          </span>
+          <Button className="gap-2" onClick={onContinue}>
+            Continue
+            <ArrowRightIcon className="size-3.5" />
+          </Button>
+        </div>
+      </div>
+    </StepShell>
+  );
+}
+
+function AgentCard({
+  driver,
+  provider,
+  terminalOpen,
+  terminalAvailable,
+  onOpenTerminal,
+}: {
+  readonly driver: OnboardingAgentDriver;
+  readonly provider: ServerProvider | undefined;
+  readonly terminalOpen: boolean;
+  readonly terminalAvailable: boolean;
+  readonly onOpenTerminal: () => void;
+}) {
+  const meta = getDriverOption(ProviderDriverKind.make(driver));
+  const Icon = meta?.icon;
+  const displayName = driver === "claudeAgent" ? "Claude Code" : (meta?.label ?? driver);
+  const summary = getProviderSummary(provider);
+  const providerState = getOnboardingProviderState(provider);
+
+  return (
+    <div className="flex min-h-20 items-center gap-4 border-b border-border py-3">
+      {Icon ? (
+        <Icon className={cn("size-6 shrink-0", driver !== "claudeAgent" && "fill-foreground")} />
+      ) : null}
+      <div className="min-w-0 flex-1">
+        <span className="block text-sm font-medium text-foreground">{displayName}</span>
+        <p className="mt-1 truncate text-xs text-muted-foreground">
+          {summary.headline}
+          {summary.detail ? ` · ${summary.detail}` : ""}
+        </p>
+      </div>
+      <div className="shrink-0">
+        {providerState === "ready" ? (
+          <span className="inline-flex items-center gap-1.5 text-xs font-medium text-success-foreground">
+            <CheckIcon className="size-3.5" />
+            Ready
+          </span>
+        ) : providerState === "checking" ? (
+          <span className="text-xs text-muted-foreground">Checking...</span>
+        ) : providerState === "disabled" ? (
+          <span className="text-xs text-muted-foreground">Disabled</span>
+        ) : providerState === "attention" ? (
+          <span className="text-xs text-muted-foreground">{summary.headline}</span>
+        ) : (
+          <Button
+            size="xs"
+            variant="ghost"
+            onClick={onOpenTerminal}
+            disabled={terminalOpen || !terminalAvailable}
+          >
+            <TerminalIcon className="size-3.5" />
+            {providerState === "signIn" ? "Sign in" : "Install"}
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Inline install terminal. Opens a PTY on the connected environment under a
+ * synthetic onboarding thread id (terminals are keyed by free-form thread id;
+ * the server validates only the cwd) and pre-types the install or login
+ * command without submitting, so the user reviews and presses Enter.
+ */
+function AgentInstallTerminal({
+  session,
+  onClose,
+}: {
+  readonly session: AgentTerminalSession;
+  readonly onClose: () => void;
+}) {
+  const { command, cwd, driver, environmentId, keybindings, providerInstanceId } = session;
+  // Same terminal typography preference the thread drawer honors.
+  const [advancedTypography] = useLocalStorage(
+    TYPOGRAPHY_ADVANCED_STORAGE_KEY,
+    false,
+    Schema.Boolean,
+  );
+  const openTerminal = useAtomCommand(terminalEnvironment.open, { reportFailure: false });
+  const writeTerminal = useAtomCommand(terminalEnvironment.write, { reportFailure: false });
+  const closeTerminal = useAtomCommand(terminalEnvironment.close, { reportFailure: false });
+  const setupQueueRef = useRef(Promise.resolve());
+  const setupGenerationRef = useRef(0);
+  const activeSetupGenerationRef = useRef<number | null>(null);
+  const [terminalId] = useState(() => `onboarding-${driver}-${randomUUID()}`);
+  const threadRef = useMemo(
+    () => scopeThreadRef(environmentId, AGENT_ONBOARDING_THREAD_ID),
+    [environmentId],
+  );
+  const [setupAttempt, setSetupAttempt] = useState(0);
+  const [setupState, setSetupState] = useState<
+    "preparing" | "ready" | "openFailed" | "writeFailed"
+  >("preparing");
+  const terminalReady = setupState === "ready" || setupState === "writeFailed";
+
+  // Keep each setup generation distinct. In Strict Mode, a canceled open can
+  // finish after the replacement setup starts; it must not close or pre-type
+  // into the replacement session that shares this terminal id.
+  useEffect(() => {
+    const generation = setupGenerationRef.current + 1;
+    setupGenerationRef.current = generation;
+    activeSetupGenerationRef.current = generation;
+    setSetupState("preparing");
+
+    setupQueueRef.current = setupQueueRef.current.then(async () => {
+      if (activeSetupGenerationRef.current !== generation) return;
+      const opened = await openTerminal({
+        environmentId,
+        input: {
+          threadId: AGENT_ONBOARDING_THREAD_ID,
+          terminalId,
+          cwd,
+          providerInstanceId,
+        },
+      });
+      if (opened._tag !== "Success") {
+        if (activeSetupGenerationRef.current === generation) setSetupState("openFailed");
+        return;
+      }
+
+      if (activeSetupGenerationRef.current !== generation) return;
+
+      const wrote = await writeTerminal({
+        environmentId,
+        input: { threadId: AGENT_ONBOARDING_THREAD_ID, terminalId, data: command },
+      });
+      if (activeSetupGenerationRef.current !== generation) return;
+      setSetupState(wrote._tag === "Success" ? "ready" : "writeFailed");
+    });
+
+    // Every exit path unmounts the drawer (Done, Continue/Skip, card switch,
+    // session exit), so this cleanup is the single place the PTY dies —
+    // nothing is left running behind the wizard. An interrupted install is
+    // re-runnable from the card.
+    return () => {
+      if (activeSetupGenerationRef.current === generation) {
+        activeSetupGenerationRef.current = null;
+      }
+      setupQueueRef.current = setupQueueRef.current.then(async () => {
+        await closeTerminal({
+          environmentId,
+          input: { threadId: AGENT_ONBOARDING_THREAD_ID, terminalId, deleteHistory: true },
+        });
+      });
+    };
+  }, [
+    closeTerminal,
+    command,
+    cwd,
+    environmentId,
+    openTerminal,
+    providerInstanceId,
+    setupAttempt,
+    terminalId,
+    writeTerminal,
+  ]);
+
+  return (
+    <div className="thread-terminal-drawer mt-4 overflow-hidden rounded-lg border border-border/70 bg-background text-foreground">
+      <div className="flex items-center justify-between border-b border-border/60 bg-background/60 px-3 py-1.5">
+        <span className="text-[11px] font-medium text-muted-foreground">
+          {setupState === "writeFailed" ? (
+            <>
+              Run <code className="rounded bg-muted px-1 font-mono">{command}</code> in this
+              terminal.
+            </>
+          ) : setupState === "ready" ? (
+            "Review the command, then press Enter to run it."
+          ) : setupState === "openFailed" ? (
+            "Could not open the setup terminal."
+          ) : (
+            "Preparing command..."
+          )}
+        </span>
+        <div className="flex items-center gap-1">
+          {setupState === "openFailed" ? (
+            <Button size="xs" variant="ghost" onClick={() => setSetupAttempt((value) => value + 1)}>
+              Retry
+            </Button>
+          ) : null}
+          <Button size="xs" variant="ghost-muted" onClick={onClose}>
+            Close
+          </Button>
+        </div>
+      </div>
+      <div className="h-64">
+        {terminalReady ? (
+          <TerminalViewport
+            threadRef={threadRef}
+            threadId={AGENT_ONBOARDING_THREAD_ID}
+            terminalId={terminalId}
+            terminalLabel={`Install ${driver}`}
+            cwd={cwd}
+            providerInstanceId={providerInstanceId}
+            advancedTypography={advancedTypography}
+            onSessionExited={onClose}
+            focusRequestId={1}
+            autoFocus
+            visible
+            resizeEpoch={0}
+            drawerHeight={256}
+            keybindings={keybindings}
+          />
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+// ── Step 4: import ───────────────────────────────────────────
+
+/**
+ * One-decision import (4B): a summary line with Import recent / Choose /
+ * Skip. The default imports only projects touched in the last 30 days;
+ * Choose expands a checklist including older ones. Imported projects also
+ * receive Codex and Claude threads active within the last 30 days.
+ */
+function ImportStep({
+  mode,
+  pairedEnvironmentId,
+  onBack,
+  onDone,
+}: {
+  readonly mode: ConnectionMode;
+  readonly pairedEnvironmentId: EnvironmentId | null;
+  readonly onBack: () => void;
+  readonly onDone: (projectRef?: ScopedProjectRef) => Promise<boolean>;
+}) {
+  const targetEnvironment = useOnboardingTargetEnvironment(mode, pairedEnvironmentId);
+  const environmentId = targetEnvironment?.environmentId ?? null;
+  const machineLabel = targetEnvironment?.label ?? "this machine";
+  const providers = useAtomValue(
+    serverEnvironment.providersValueAtom(environmentId ?? ("" as EnvironmentId)),
+  );
+  const scan = useEnvironmentQuery(
+    environmentId === null ? null : agentSessionScan({ environmentId, input: {} }),
+  );
+  const createProject = useAtomCommand(projectEnvironment.create, { reportFailure: false });
+  const importThreads = useAtomCommand(agentSessionImport, { reportFailure: false });
+  const projects = useProjects();
+  const [choosing, setChoosing] = useState(false);
+  const [deselected, setDeselected] = useState<ReadonlySet<string>>(new Set());
+  const [isImporting, setIsImporting] = useState(false);
+  const [importError, setImportError] = useState("");
+  const [landingProject, setLandingProject] = useState<ScopedProjectRef | null>(null);
+  // Keep project creation attempts separate from completed history imports so both can retry.
+  const importedProjectsRef = useRef(new Map<string, ScopedProjectRef>());
+  const projectsWithImportedHistoryRef = useRef(new Map<string, ScopedProjectRef>());
+  const lastImportSelectionRef = useRef<ReadonlyArray<string>>([]);
+  const projectAttemptsRef = useRef(
+    new Map<string, { readonly projectId: ProjectId; readonly commandId: CommandId }>(),
+  );
+  const importGenerationRef = useRef(0);
+
+  // Candidate paths are per-environment; a target switch would otherwise
+  // leave stale entries in the deselection set (and stale success records).
+  useEffect(() => {
+    importGenerationRef.current += 1;
+    setDeselected(new Set());
+    setIsImporting(false);
+    setImportError("");
+    setLandingProject(null);
+    importedProjectsRef.current = new Map();
+    projectsWithImportedHistoryRef.current = new Map();
+    lastImportSelectionRef.current = [];
+    projectAttemptsRef.current = new Map();
+    return () => {
+      importGenerationRef.current += 1;
+    };
+  }, [environmentId]);
+
+  useEffect(() => {
+    if (
+      landingProject !== null &&
+      landingProject.environmentId === environmentId &&
+      projects.some(
+        (project) =>
+          project.id === landingProject.projectId &&
+          project.environmentId === landingProject.environmentId,
+      )
+    ) {
+      setLandingProject(null);
+      void onDone(landingProject).then((completed) => {
+        if (!completed) setIsImporting(false);
+      });
+    }
+  }, [environmentId, landingProject, onDone, projects]);
+
+  const { available: candidates, recent } = useMemo(
+    () => partitionOnboardingProjects(scan.data?.candidates ?? []),
+    [scan.data],
+  );
+  const more = candidates.length - recent.length;
+  const scanTruncated = scan.data?.truncated === true;
+  const scanLimitNotice = scanTruncated ? (
+    <p className="mt-3 text-sm text-muted-foreground" role="status">
+      {SCAN_LIMIT_MESSAGE}
+    </p>
+  ) : null;
+
+  const finishAfterImport = () => {
+    const projectRef = resolveOnboardingLandingProject(
+      lastImportSelectionRef.current,
+      projectsWithImportedHistoryRef.current,
+      importedProjectsRef.current,
+    );
+    if (projectRef === undefined) {
+      void onDone();
+      return;
+    }
+    setIsImporting(true);
+    setLandingProject(projectRef);
+  };
+
+  const runImport = async (selection: ReadonlyArray<AgentSessionProjectCandidate>) => {
+    if (environmentId === null || selection.length === 0) {
+      void onDone();
+      return;
+    }
+    setIsImporting(true);
+    setImportError("");
+    lastImportSelectionRef.current = selection.map((candidate) => candidate.path);
+    const importGeneration = importGenerationRef.current;
+    const importedProjects = importedProjectsRef.current;
+    const projectAttempts = projectAttemptsRef.current;
+    const defaultModelSelection = resolveDefaultProviderModelSelection(providers ?? [], null);
+    // Interrupted imports are neither failures nor successes — the command was
+    // superseded or the environment dropped — but they still didn't land, so
+    // they must not read as "imported everything". Retries skip paths that
+    // already landed this session (re-creating them would only trip the
+    // duplicate-root invariant and read as a failure).
+    let importedProjectsCount =
+      importedProjects.size > 0
+        ? selection.filter((candidate) => importedProjects.has(candidate.path)).length
+        : 0;
+    let importedThreadCount = 0;
+    let skippedThreadCount = 0;
+    let shouldRefreshScan = false;
+    for (const candidate of selection) {
+      if (
+        importGeneration !== importGenerationRef.current ||
+        importedProjects !== importedProjectsRef.current
+      ) {
+        return;
+      }
+      if (importedProjects.has(candidate.path)) continue;
+      let projectId = resolveOnboardingProjectId(readProjects(), environmentId, candidate);
+      if (projectId === null) {
+        let attempt = projectAttempts.get(candidate.path);
+        if (attempt === undefined) {
+          const nextProjectId = newProjectId();
+          attempt = {
+            projectId: nextProjectId,
+            commandId: CommandId.make(`onboarding:project:create:${nextProjectId}`),
+          };
+          projectAttempts.set(candidate.path, attempt);
+        }
+        projectId = attempt.projectId;
+        const result = await createProject({
+          environmentId,
+          input: {
+            projectId,
+            commandId: attempt.commandId,
+            title: candidate.title,
+            workspaceRoot: candidate.path,
+            createWorkspaceRootIfMissing: false,
+            defaultModelSelection,
+          },
+        });
+        if (
+          importGeneration !== importGenerationRef.current ||
+          importedProjects !== importedProjectsRef.current
+        ) {
+          return;
+        }
+        if (result._tag !== "Success") {
+          if (!isAtomCommandInterrupted(result)) {
+            projectAttempts.delete(candidate.path);
+            shouldRefreshScan = true;
+          }
+          continue;
+        }
+      }
+
+      const threadImportResult = await importThreads({
+        environmentId,
+        input: { projectId, expectedWorkspaceRoot: candidate.path },
+      });
+      if (
+        importGeneration !== importGenerationRef.current ||
+        importedProjects !== importedProjectsRef.current
+      ) {
+        return;
+      }
+      if (threadImportResult._tag === "Success") {
+        importedThreadCount += threadImportResult.value.importedCount;
+        skippedThreadCount += threadImportResult.value.skippedCount;
+        if (threadImportResult.value.importedCount > 0) {
+          projectsWithImportedHistoryRef.current.set(
+            candidate.path,
+            scopeProjectRef(environmentId, projectId),
+          );
+        }
+        if (threadImportResult.value.skippedCount === 0) {
+          importedProjectsCount += 1;
+          importedProjects.set(candidate.path, scopeProjectRef(environmentId, projectId));
+        }
+      } else if (!isAtomCommandInterrupted(threadImportResult)) {
+        projectAttempts.delete(candidate.path);
+        shouldRefreshScan = true;
+      }
+    }
+    if (shouldRefreshScan) scan.refresh();
+    setIsImporting(false);
+    if (importedProjectsCount < selection.length) {
+      if (importedThreadCount > 0 && skippedThreadCount > 0) {
+        setImportError(
+          `Imported ${importedThreadCount} ${importedThreadCount === 1 ? "thread" : "threads"}. ${skippedThreadCount} ${skippedThreadCount === 1 ? "thread" : "threads"} could not be imported.`,
+        );
+      } else if (skippedThreadCount > 0) {
+        setImportError(
+          `${skippedThreadCount} ${skippedThreadCount === 1 ? "thread could" : "threads could"} not be imported.`,
+        );
+      } else if (importedThreadCount > 0) {
+        setImportError(
+          `Imported ${importedThreadCount} ${importedThreadCount === 1 ? "thread" : "threads"}. Some thread history could not be imported.`,
+        );
+      } else {
+        setImportError("Could not import thread history.");
+      }
+      return;
+    }
+    finishAfterImport();
+  };
+
+  if (environmentId === null || (scan.isPending && scan.data === null)) {
+    return (
+      <StepShell
+        title="Your projects"
+        description="Looking for projects from Claude Code and Codex."
+        onBack={onBack}
+      >
+        <div className="mt-6 flex justify-end">
+          <Button variant="ghost-muted" onClick={() => void onDone()}>
+            Skip
+          </Button>
+        </div>
+      </StepShell>
+    );
+  }
+
+  if (scan.error !== null || candidates.length === 0) {
+    return (
+      <StepShell
+        title="Your projects"
+        description={
+          scan.error !== null
+            ? "Could not check this computer for projects."
+            : scanTruncated
+              ? SCAN_LIMIT_MESSAGE
+              : "No existing Claude Code or Codex projects found."
+        }
+        onBack={onBack}
+      >
+        {scan.error !== null ? (
+          <p className="mt-3 text-xs text-muted-foreground">You can add projects later.</p>
+        ) : null}
+        <div className="mt-6 flex justify-end gap-2">
+          {scan.error !== null ? (
+            <Button variant="ghost" onClick={scan.refresh}>
+              Retry
+            </Button>
+          ) : null}
+          <Button
+            variant={scan.error !== null || scanTruncated ? "ghost-muted" : "default"}
+            onClick={() => void onDone()}
+          >
+            {scan.error !== null || scanTruncated ? "Skip" : "Start coding"}
+          </Button>
+        </div>
+      </StepShell>
+    );
+  }
+
+  if (choosing) {
+    const selected = candidates.filter((candidate) => !deselected.has(candidate.path));
+    return (
+      <StepShell
+        title="Choose your projects"
+        onBack={() => setChoosing(false)}
+        backDisabled={isImporting}
+        description={`${candidates.length} found on ${machineLabel}.`}
+      >
+        {scanLimitNotice}
+        <div className="mt-6 max-h-72 overflow-x-hidden overflow-y-auto border-y border-border">
+          {candidates.map((candidate) => (
+            <label
+              key={candidate.path}
+              className="flex min-h-12 cursor-pointer items-center gap-3 border-b border-border/60 px-1 py-2 last:border-b-0 hover:bg-accent/50"
+            >
+              <Checkbox
+                checked={!deselected.has(candidate.path)}
+                onCheckedChange={(checked) => {
+                  setDeselected((previous) => {
+                    const next = new Set(previous);
+                    if (checked === true) next.delete(candidate.path);
+                    else next.add(candidate.path);
+                    return next;
+                  });
+                }}
+              />
+              <span className="min-w-0 flex-1 truncate font-mono text-xs text-foreground">
+                {candidate.path}
+              </span>
+              <span className="hidden shrink-0 whitespace-nowrap text-[11px] text-muted-foreground sm:block">
+                {candidate.sources.map(formatSource).join(", ")} · {candidate.threadCount}{" "}
+                {candidate.threadCount === 1 ? "thread" : "threads"}
+                {candidate.lastActiveAt
+                  ? ` · ${formatRelativeTimeLabel(candidate.lastActiveAt)}`
+                  : ""}
+              </span>
+            </label>
+          ))}
+        </div>
+        {importError ? <p className="mt-3 text-sm text-destructive">{importError}</p> : null}
+        <div className="mt-7 flex flex-wrap items-center justify-between gap-3">
+          <Button
+            variant="ghost-muted"
+            disabled={isImporting}
+            onClick={importError ? finishAfterImport : () => void onDone()}
+          >
+            {importError ? "Continue without the rest" : "Skip"}
+          </Button>
+          <Button
+            disabled={isImporting || selected.length === 0}
+            onClick={() => void runImport(selected)}
+          >
+            {isImporting ? "Importing..." : `Import ${selected.length}`}
+          </Button>
+        </div>
+      </StepShell>
+    );
+  }
+
+  return (
+    <StepShell
+      title="Your recent projects"
+      description={`${recent.length} ${recent.length === 1 ? "project" : "projects"} found on ${machineLabel}.${more > 0 ? ` ${more} more available.` : ""}`}
+      onBack={onBack}
+      backDisabled={isImporting}
+    >
+      {scanLimitNotice}
+      <div className="mt-6 border-y border-border">
+        {recent.slice(0, 4).map((candidate) => (
+          <div
+            key={candidate.path}
+            className="flex min-h-12 items-center gap-3 border-b border-border/60 px-1 py-2 last:border-b-0"
+          >
+            <CheckIcon className="size-3.5 shrink-0 text-success-foreground" />
+            <span className="min-w-0 flex-1 truncate font-mono text-xs text-foreground">
+              {candidate.path}
+            </span>
+            <span className="hidden shrink-0 whitespace-nowrap text-[11px] text-muted-foreground sm:block">
+              {candidate.sources.map(formatSource).join(", ")}
+            </span>
+          </div>
+        ))}
+        {recent.length > 4 ? (
+          <p className="px-1 py-3 text-xs text-muted-foreground">
+            {recent.length - 4} more projects
+          </p>
+        ) : null}
+      </div>
+      {importError ? <p className="mt-3 text-sm text-destructive">{importError}</p> : null}
+      <div className="mt-7 flex flex-wrap items-center justify-between gap-3">
+        <Button
+          variant="ghost-muted"
+          disabled={isImporting}
+          onClick={importError ? finishAfterImport : () => void onDone()}
+        >
+          {importError ? "Continue without the rest" : "Skip"}
+        </Button>
+        <div className="flex items-center gap-2">
+          <Button variant="ghost" disabled={isImporting} onClick={() => setChoosing(true)}>
+            Choose
+          </Button>
+          <Button
+            disabled={isImporting || recent.length === 0}
+            onClick={() => void runImport(recent)}
+          >
+            {isImporting
+              ? "Importing..."
+              : `Import ${recent.length} ${recent.length === 1 ? "project" : "projects"}`}
+          </Button>
+        </div>
+      </div>
+    </StepShell>
+  );
+}
+
+// ── Shared bits ──────────────────────────────────────────────
+
+function StepShell({
+  title,
+  description,
+  onBack,
+  backDisabled = false,
+  children,
+}: {
+  readonly title: string;
+  readonly description?: string;
+  readonly onBack?: () => void;
+  readonly backDisabled?: boolean;
+  readonly children?: React.ReactNode;
+}) {
+  return (
+    <>
+      {onBack ? (
+        <Button
+          className="mb-5 -ml-2"
+          disabled={backDisabled}
+          onClick={onBack}
+          size="xs"
+          variant="ghost-muted"
+        >
+          <ChevronLeftIcon className="size-3.5" />
+          Back
+        </Button>
+      ) : null}
+      <h1 className="text-3xl font-semibold text-foreground sm:text-[34px]">{title}</h1>
+      {description ? (
+        <p className="mt-2.5 text-sm leading-relaxed text-muted-foreground">{description}</p>
+      ) : null}
+      {children}
+    </>
+  );
+}
+
+function CommandBlock({
+  command,
+  className,
+  prominent = false,
+}: {
+  readonly command: string;
+  readonly className?: string;
+  readonly prominent?: boolean;
+}) {
+  const { copyToClipboard, isCopied } = useCopyToClipboard({
+    timeout: 1500,
+    target: "command",
+  });
+  return (
+    <div
+      className={cn(
+        "flex items-center justify-between gap-3 border border-border bg-accent/50 font-mono",
+        prominent ? "px-4 py-3.5 text-base" : "px-3 py-2.5 text-sm",
+        className,
+      )}
+    >
+      <span className="min-w-0 truncate">
+        <span className="mr-2 text-muted-foreground">$</span>
+        {command}
+      </span>
+      <Button
+        size="icon-xs"
+        variant="ghost"
+        aria-label="Copy command"
+        onClick={() => copyToClipboard(command, undefined)}
+      >
+        {isCopied ? <CheckIcon className="size-3.5" /> : <CopyIcon className="size-3.5" />}
+      </Button>
+    </div>
+  );
+}
+
+function formatSource(source: "claudeAgent" | "codex"): string {
+  return source === "claudeAgent" ? "Claude" : "Codex";
+}
diff --git a/apps/web/src/components/preview/PreviewAutomationHosts.test.tsx b/apps/web/src/components/preview/PreviewAutomationHosts.test.tsx
new file mode 100644
index 000000000000..75ed20cc4fe7
--- /dev/null
+++ b/apps/web/src/components/preview/PreviewAutomationHosts.test.tsx
@@ -0,0 +1,190 @@
+import {
+  DEFAULT_CLIENT_SETTINGS,
+  EnvironmentId,
+  ThreadId,
+  type ClientSettings,
+  type PreviewAutomationResponse,
+  type PreviewAutomationStreamEvent,
+  type PreviewOpenInput,
+  type PreviewSessionSnapshot,
+} from "@t3tools/contracts";
+import { AsyncResult, Atom } from "effect/unstable/reactivity";
+import { act } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { __resetClientSettingsPersistenceForTests } from "~/hooks/useSettings";
+import { readThreadPreviewState, resetPreviewStateForTests } from "~/previewStateStore";
+import { appAtomRegistry, AppAtomRegistryProvider } from "~/rpc/atomRegistry";
+
+import { PreviewAutomationHosts } from "./PreviewAutomationHosts";
+
+const mocks = vi.hoisted(() => ({
+  getClientSettings: vi.fn<() => Promise<ClientSettings | null>>(),
+  setClientSettings: vi.fn(),
+  open: vi.fn(async (_target: { environmentId: EnvironmentId; input: PreviewOpenInput }) =>
+    AsyncResult.success(snapshot),
+  ),
+  list: vi.fn(async () => AsyncResult.success(emptyList)),
+  resize: vi.fn(),
+  respond:
+    vi.fn<
+      (target: { environmentId: EnvironmentId; input: PreviewAutomationResponse }) => Promise<void>
+    >(),
+  focus: vi.fn(async () => undefined),
+}));
+
+vi.mock("~/localApi", () => ({
+  ensureLocalApi: () => ({ persistence: mocks }),
+}));
+vi.mock("~/env", () => ({ isElectron: true }));
+vi.mock("~/state/environments", () => ({
+  useEnvironments: () => ({ environments: [{ environmentId }] }),
+}));
+vi.mock("~/state/preview", () => ({
+  previewEnvironment: {
+    automationRequests: () => requestsAtom,
+    list: () => listAtom,
+    open: mocks.open,
+    resize: mocks.resize,
+    respondToAutomation: mocks.respond,
+    focusAutomationHost: mocks.focus,
+  },
+}));
+vi.mock("~/state/use-atom-command", () => ({
+  useAtomCommand: (command: unknown) => command,
+}));
+vi.mock("~/state/use-atom-query-runner", () => ({
+  useAtomQueryRunner: () => mocks.list,
+}));
+vi.mock("./previewBridge", () => ({ previewBridge: { automation: {} } }));
+
+const environmentId = EnvironmentId.make("automation-environment");
+const threadId = ThreadId.make("automation-thread");
+const threadRef = { environmentId, threadId };
+const viewport = { _tag: "freeform", width: 1440, height: 900 } as const;
+const savedSettings: ClientSettings = {
+  ...DEFAULT_CLIENT_SETTINGS,
+  browserDefaultViewport: viewport,
+  browserDefaultProfileId: "work",
+  browserProfiles: [{ id: "work", name: "Work", kind: "persistent" }],
+};
+const snapshot: PreviewSessionSnapshot = {
+  threadId,
+  tabId: "automation-tab",
+  navStatus: { _tag: "Idle" },
+  canGoBack: false,
+  canGoForward: false,
+  viewport,
+  profileId: "work",
+  updatedAt: "2026-09-05T00:00:00.000Z",
+};
+const emptyList = { sessions: [], serverEpoch: "test-server", revision: 0 };
+const listAtom = Atom.make(AsyncResult.success(emptyList));
+const requestsAtom = Atom.make<AsyncResult.AsyncResult<PreviewAutomationStreamEvent, Error>>(
+  AsyncResult.initial(false),
+);
+const requestEvent: PreviewAutomationStreamEvent = {
+  type: "request",
+  connectionId: "automation-connection",
+  request: {
+    requestId: "open-request",
+    threadId,
+    operation: "open",
+    input: { open: false, reuseExistingTab: false },
+    timeoutMs: 15_000,
+  },
+};
+
+function deferred<A>() {
+  let resolve!: (value: A) => void;
+  const promise = new Promise<A>((complete) => {
+    resolve = complete;
+  });
+  return { promise, resolve };
+}
+
+let renderer: ReactTestRenderer | null = null;
+
+beforeEach(async () => {
+  vi.clearAllMocks();
+  mocks.getClientSettings.mockReset().mockResolvedValue(savedSettings);
+  mocks.respond.mockReset();
+  __resetClientSettingsPersistenceForTests();
+  resetPreviewStateForTests();
+  appAtomRegistry.set(requestsAtom, AsyncResult.initial(false));
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("window", { addEventListener: vi.fn(), removeEventListener: vi.fn() });
+  vi.stubGlobal("document", { hasFocus: () => false, querySelectorAll: () => [] });
+  await act(() => {
+    renderer = create(
+      <AppAtomRegistryProvider>
+        <PreviewAutomationHosts />
+      </AppAtomRegistryProvider>,
+    );
+  });
+});
+
+afterEach(async () => {
+  await act(() => renderer?.unmount());
+  renderer = null;
+  resetPreviewStateForTests();
+  __resetClientSettingsPersistenceForTests();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("PreviewAutomationHosts open", () => {
+  it("waits for saved settings before opening a tab with the configured profile and viewport", async () => {
+    const readStarted = deferred<void>();
+    const read = deferred<ClientSettings>();
+    const response = deferred<PreviewAutomationResponse>();
+    mocks.getClientSettings.mockImplementationOnce(() => {
+      readStarted.resolve();
+      return read.promise;
+    });
+    mocks.respond.mockImplementationOnce(async ({ input }) => response.resolve(input));
+
+    await act(async () => {
+      appAtomRegistry.set(requestsAtom, AsyncResult.success(requestEvent));
+      await readStarted.promise;
+    });
+    expect(mocks.open).not.toHaveBeenCalled();
+
+    await act(async () => {
+      read.resolve(savedSettings);
+      await response.promise;
+    });
+
+    expect(mocks.open).toHaveBeenCalledExactlyOnceWith({
+      environmentId,
+      input: { threadId, viewport, profileId: "work" },
+    });
+    expect(mocks.getClientSettings).toHaveBeenCalledOnce();
+    await expect(response.promise).resolves.toMatchObject({ requestId: "open-request", ok: true });
+    expect(readThreadPreviewState(threadRef).snapshot).toEqual(snapshot);
+    expect(mocks.setClientSettings).not.toHaveBeenCalled();
+  });
+
+  it("reports a settings read failure without opening a tab", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    mocks.getClientSettings.mockRejectedValueOnce(new Error("Settings read failed"));
+    const response = deferred<PreviewAutomationResponse>();
+    mocks.respond.mockImplementationOnce(async ({ input }) => response.resolve(input));
+
+    await act(async () => {
+      appAtomRegistry.set(requestsAtom, AsyncResult.success(requestEvent));
+      await response.promise;
+    });
+
+    await expect(response.promise).resolves.toMatchObject({
+      requestId: "open-request",
+      ok: false,
+      error: { _tag: "PreviewAutomationExecutionError" },
+    });
+    expect(mocks.getClientSettings).toHaveBeenCalledOnce();
+    expect(mocks.open).not.toHaveBeenCalled();
+    expect(readThreadPreviewState(threadRef).snapshot).toBeNull();
+    expect(mocks.setClientSettings).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/web/src/components/preview/PreviewAutomationHosts.tsx b/apps/web/src/components/preview/PreviewAutomationHosts.tsx
index 54c2e1d9cf68..fd87f7e80c79 100644
--- a/apps/web/src/components/preview/PreviewAutomationHosts.tsx
+++ b/apps/web/src/components/preview/PreviewAutomationHosts.tsx
@@ -41,7 +41,11 @@ import {
   acquireBrowserSurfaceActivity,
   useBrowserSurfaceStore,
 } from "~/browser/browserSurfaceStore";
-import { browserDefaultOpenViewport, resolveBrowserDefaults } from "~/browser/browserDefaults";
+import {
+  browserDefaultOpenProfileId,
+  browserDefaultOpenViewport,
+  resolveBrowserDefaults,
+} from "~/browser/browserDefaults";
 import { runBrowserViewportMutation } from "~/browser/browserViewportActions";
 import { previewRuntimeTabId } from "~/browser/previewRuntimeTabId";
 import { isElectron } from "~/env";
@@ -76,6 +80,7 @@ import {
   resolvePreviewAutomationOpenTab,
   resolvePreviewAutomationTarget,
 } from "./previewAutomationTarget";
+import { resolveHostWaitBudgetMs, waitForHostReadiness } from "./previewAutomationHostBudget";
 import { isPreviewViewportReady } from "./previewViewportReadiness";
 import { shouldRollbackPreviewViewport } from "./previewViewportRollback";
 
@@ -95,25 +100,26 @@ const waitForDesktopOverlay = async (
   tabId: string,
   runtimeTabId: string,
   operation: PreviewAutomationRequest["operation"],
-  timeoutMs: number,
+  deadlineMs: number,
 ): Promise<void> => {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() <= deadline) {
+  const waitBudgetMs = Math.max(0, deadlineMs - Date.now());
+  const ready = await waitForHostReadiness(deadlineMs, async () => {
     const state = assertPreviewRuntimeCurrent(threadRef, tabId, runtimeTabId, {
       operation,
       requestId,
     });
     if (state.desktopByTabId[tabId] && previewBridge && isPreviewWebviewRendering(runtimeTabId)) {
       const status = await previewBridge.automation.status(runtimeTabId);
-      if (status.available) return;
+      return status.available;
     }
-    await new Promise<void>((resolve) => window.setTimeout(resolve, 50));
-  }
+    return false;
+  });
+  if (ready) return;
   throw new PreviewAutomationOverlayTimeoutError({
     requestId,
     environmentId: threadRef.environmentId,
     threadId: threadRef.threadId,
-    timeoutMs,
+    timeoutMs: waitBudgetMs,
   });
 };
 
@@ -317,6 +323,8 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
 
   const handleRequest = useCallback(
     async (request: PreviewAutomationRequest): Promise<unknown> => {
+      // Session sync and tab creation consume the same budget as overlay registration.
+      const hostDeadlineMs = Date.now() + resolveHostWaitBudgetMs(request.timeoutMs);
       const threadRef: ScopedThreadRef = {
         environmentId,
         threadId: request.threadId,
@@ -378,7 +386,7 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
             readyTabId,
             runtimeTabId,
             request.operation,
-            request.timeoutMs,
+            hostDeadlineMs,
           );
           return {
             bridge,
@@ -408,6 +416,7 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
             const reusedExistingTab = activeTabId !== null;
             tabId = activeTabId;
             if (!activeTabId) {
+              const defaults = await resolveBrowserDefaults();
               const result = await open({
                 environmentId,
                 input: {
@@ -415,7 +424,8 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
                   ...(resolvedInputUrl ? { url: resolvedInputUrl } : {}),
                   // An agent that didn't state a size gets the user's
                   // configured default, same as a hand-opened tab.
-                  viewport: browserDefaultOpenViewport(await resolveBrowserDefaults()),
+                  viewport: browserDefaultOpenViewport(defaults),
+                  profileId: browserDefaultOpenProfileId(defaults),
                 },
               });
               if (result._tag === "Failure") {
diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
index bb20ee362376..9456daef72d8 100644
--- a/apps/web/src/components/preview/PreviewView.test.tsx
+++ b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -251,7 +251,7 @@ vi.mock("./AgentBrowserCursor", () => ({ AgentBrowserCursor: () => null }));
 vi.mock("~/browser/BrowserSurfaceSlot", () => ({ BrowserSurfaceSlot: () => null }));
 vi.mock("./usePreviewSession", () => ({ usePreviewSession: vi.fn() }));
 
-import { PreviewView, previewProfileName } from "./PreviewView";
+import { PreviewView } from "./PreviewView";
 import { toastManager } from "~/components/ui/toast";
 import { previewRuntimeTabId } from "~/browser/previewRuntimeTabId";
 
@@ -352,12 +352,6 @@ describe("PreviewView navigation", () => {
     mocks.recordVisitForThread.mockClear();
   });
 
-  it("labels a tab whose saved profile was removed", () => {
-    expect(previewProfileName(BUILT_IN_BROWSER_PROFILES, "profile-removed")).toBe(
-      "Removed profile",
-    );
-  });
-
   it("does not rerender while loading time passes", async () => {
     vi.useFakeTimers();
     mocks.loading = true;
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
index 640690854e53..e6ad2758bc48 100644
--- a/apps/web/src/components/preview/PreviewView.tsx
+++ b/apps/web/src/components/preview/PreviewView.tsx
@@ -1,7 +1,10 @@
 "use client";
 
 import { scopedThreadKey } from "@t3tools/client-runtime/environment";
-import { squashAtomCommandFailure } from "@t3tools/client-runtime/state/runtime";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
 import {
   DEFAULT_BROWSER_PROFILE_ID,
   FILL_PREVIEW_VIEWPORT,
@@ -46,6 +49,7 @@ import {
 } from "~/browser/browserViewportActions";
 import { browserResponsiveViewportForToggle, useBrowserDefaults } from "~/browser/browserDefaults";
 import { previewRuntimeTabId } from "~/browser/previewRuntimeTabId";
+import { BrowserSettingsReadError } from "~/browser/openFileInPreview";
 import { PreviewUnreachable } from "./PreviewUnreachable";
 import { revealInFileExplorerLabel } from "./fileExplorerLabel";
 import { shouldShowPreviewEmptyState } from "./previewEmptyStateLogic";
@@ -76,7 +80,7 @@ interface Props {
   ) => void;
 }
 
-export function previewProfileName(
+function previewProfileName(
   profiles: ReadonlyArray<{ readonly id: string; readonly name: string }>,
   profileId: string,
 ): string {
@@ -186,6 +190,16 @@ export function PreviewView({
         return true;
       }
       const result = await openPreviewSession({ openPreview: open, threadRef, url: resolvedUrl });
+      if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+        const error = squashAtomCommandFailure(result);
+        if (error instanceof BrowserSettingsReadError) {
+          toastManager.add({
+            type: "error",
+            title: "Unable to open browser",
+            description: error.message,
+          });
+        }
+      }
       return result._tag === "Success";
     },
     [open, runtimeTabId, threadRef],
diff --git a/apps/web/src/components/preview/addBrowserSurface.test.ts b/apps/web/src/components/preview/addBrowserSurface.test.ts
index f26cb0fff9e1..d34de83a23b4 100644
--- a/apps/web/src/components/preview/addBrowserSurface.test.ts
+++ b/apps/web/src/components/preview/addBrowserSurface.test.ts
@@ -1,5 +1,6 @@
 import {
   DEFAULT_BROWSER_PROFILE_ID,
+  DEFAULT_CLIENT_SETTINGS,
   FILL_PREVIEW_VIEWPORT,
   type PreviewOpenInput,
   type PreviewSessionSnapshot,
@@ -14,6 +15,7 @@ import {
   resetPreviewStateForTests,
 } from "~/previewStateStore";
 import { selectThreadRightPanelState, useRightPanelStore } from "~/rightPanelStore";
+import { __setClientSettingsForTests } from "~/hooks/useSettings";
 
 import { addBrowserSurface } from "./addBrowserSurface";
 
@@ -32,6 +34,7 @@ const snapshot = (tabId: string): PreviewSessionSnapshot => ({
 });
 
 beforeEach(() => {
+  __setClientSettingsForTests(DEFAULT_CLIENT_SETTINGS);
   resetPreviewStateForTests();
   useRightPanelStore.setState({ byThreadKey: {} });
 });
diff --git a/apps/web/src/components/preview/addBrowserSurface.ts b/apps/web/src/components/preview/addBrowserSurface.ts
index 622cdbec2f1c..e0cd83501201 100644
--- a/apps/web/src/components/preview/addBrowserSurface.ts
+++ b/apps/web/src/components/preview/addBrowserSurface.ts
@@ -4,7 +4,7 @@ import {
 } from "@t3tools/client-runtime/state/runtime";
 import type { ScopedThreadRef } from "@t3tools/contracts";
 
-import type { OpenPreviewMutation } from "~/browser/openFileInPreview";
+import type { BrowserSettingsReadError, OpenPreviewMutation } from "~/browser/openFileInPreview";
 import { useRightPanelStore } from "~/rightPanelStore";
 
 import { openPreviewSession } from "./openPreviewSession";
@@ -15,7 +15,7 @@ export async function addBrowserSurface<E>(input: {
   readonly openPreview: OpenPreviewMutation<E>;
   /** Omit to use the configured default profile. */
   readonly profileId?: string | undefined;
-}): Promise<AtomCommandResult<void, E>> {
+}): Promise<AtomCommandResult<void, E | BrowserSettingsReadError>> {
   const result = await openPreviewSession({
     openPreview: input.openPreview,
     threadRef: input.threadRef,
diff --git a/apps/web/src/components/preview/openDiscoveredPort.ts b/apps/web/src/components/preview/openDiscoveredPort.ts
index a49acbd86104..288db101e7a5 100644
--- a/apps/web/src/components/preview/openDiscoveredPort.ts
+++ b/apps/web/src/components/preview/openDiscoveredPort.ts
@@ -5,7 +5,7 @@ import {
 } from "@t3tools/client-runtime/state/runtime";
 
 import { resolveDiscoveredServerUrl } from "~/browser/browserTargetResolver";
-import type { OpenPreviewMutation } from "~/browser/openFileInPreview";
+import type { BrowserSettingsReadError, OpenPreviewMutation } from "~/browser/openFileInPreview";
 import { recordVisitForThread } from "~/browserHistoryStore";
 import { useRightPanelStore } from "~/rightPanelStore";
 import { openPreviewSession } from "./openPreviewSession";
@@ -14,7 +14,7 @@ export async function openDiscoveredPort<E>(input: {
   readonly threadRef: ScopedThreadRef;
   readonly port: DiscoveredLocalServer;
   readonly openPreview: OpenPreviewMutation<E>;
-}): Promise<AtomCommandResult<void, E>> {
+}): Promise<AtomCommandResult<void, E | BrowserSettingsReadError>> {
   const resolvedUrl = resolveDiscoveredServerUrl(input.threadRef.environmentId, input.port.url);
   const result = await openPreviewSession({
     openPreview: input.openPreview,
diff --git a/apps/web/src/components/preview/openPreviewSession.test.ts b/apps/web/src/components/preview/openPreviewSession.test.ts
index ef3d51a9e7fa..fe14211280c2 100644
--- a/apps/web/src/components/preview/openPreviewSession.test.ts
+++ b/apps/web/src/components/preview/openPreviewSession.test.ts
@@ -1,5 +1,6 @@
 import {
   DEFAULT_BROWSER_PROFILE_ID,
+  DEFAULT_CLIENT_SETTINGS,
   FILL_PREVIEW_VIEWPORT,
   type PreviewOpenInput,
   type PreviewSessionSnapshot,
@@ -7,8 +8,11 @@ import {
 } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
 import { AsyncResult } from "effect/unstable/reactivity";
-import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
 
+import * as browserDefaults from "~/browser/browserDefaults";
+import { BrowserSettingsReadError, openUrlInPreview } from "~/browser/openFileInPreview";
+import { __setClientSettingsForTests } from "~/hooks/useSettings";
 import { readThreadPreviewState, resetPreviewStateForTests } from "~/previewStateStore";
 
 import { openPreviewSession } from "./openPreviewSession";
@@ -31,7 +35,14 @@ const snapshot: PreviewSessionSnapshot = {
   updatedAt: "2026-06-11T23:00:00.000Z",
 };
 
-beforeEach(resetPreviewStateForTests);
+beforeEach(() => {
+  resetPreviewStateForTests();
+  __setClientSettingsForTests(DEFAULT_CLIENT_SETTINGS);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
 
 describe("openPreviewSession", () => {
   it("creates an idle tab without recording a recently visited URL", async () => {
@@ -88,4 +99,44 @@ describe("openPreviewSession", () => {
     expect(readThreadPreviewState(threadRef).snapshot).toBeNull();
     expect(readThreadPreviewState(threadRef).recentlySeenUrls).toEqual([]);
   });
+
+  it.each(["session", "link"] as const)(
+    "does not open a %s with unread settings and uses the saved profile on retry",
+    async (entryPoint) => {
+      const failure = new Error("Settings read failed");
+      vi.spyOn(browserDefaults, "resolveBrowserDefaults").mockRejectedValueOnce(failure);
+      const viewport = { _tag: "freeform", width: 1280, height: 720 } as const;
+      __setClientSettingsForTests({
+        ...DEFAULT_CLIENT_SETTINGS,
+        browserDefaultViewport: viewport,
+        browserDefaultProfileId: "work",
+        browserProfiles: [{ id: "work", name: "Work", kind: "persistent" }],
+      });
+      const openPreview = vi.fn(async () => AsyncResult.success(snapshot));
+      const input = { openPreview, threadRef, url: "https://t3.chat/" };
+      const open = entryPoint === "session" ? openPreviewSession : openUrlInPreview;
+
+      const result = await open(input);
+
+      expect(result._tag).toBe("Failure");
+      if (result._tag === "Failure") {
+        expect(Cause.squash(result.cause)).toBeInstanceOf(BrowserSettingsReadError);
+        expect(Cause.squash(result.cause)).toMatchObject({ cause: failure });
+      }
+      expect(openPreview).not.toHaveBeenCalled();
+      expect(readThreadPreviewState(threadRef).snapshot).toBeNull();
+      expect(readThreadPreviewState(threadRef).recentlySeenUrls).toEqual([]);
+
+      await expect(open(input)).resolves.toMatchObject({ _tag: "Success" });
+      expect(openPreview).toHaveBeenCalledExactlyOnceWith({
+        environmentId: threadRef.environmentId,
+        input: {
+          threadId: threadRef.threadId,
+          url: input.url,
+          viewport,
+          profileId: "work",
+        },
+      });
+    },
+  );
 });
diff --git a/apps/web/src/components/preview/openPreviewSession.ts b/apps/web/src/components/preview/openPreviewSession.ts
index deb5465ebc28..07dab9a0b36d 100644
--- a/apps/web/src/components/preview/openPreviewSession.ts
+++ b/apps/web/src/components/preview/openPreviewSession.ts
@@ -6,12 +6,15 @@ import type {
   ScopedThreadRef,
 } from "@t3tools/contracts";
 import type { AtomCommandResult } from "@t3tools/client-runtime/state/runtime";
+import * as Cause from "effect/Cause";
+import { AsyncResult } from "effect/unstable/reactivity";
 
 import {
   browserDefaultOpenProfileId,
   browserDefaultOpenViewport,
   resolveBrowserDefaults,
 } from "~/browser/browserDefaults";
+import { BrowserSettingsReadError } from "~/browser/openFileInPreview";
 import { applyPreviewServerSnapshot, rememberPreviewUrl } from "~/previewStateStore";
 
 interface OpenPreviewSessionInput<E> {
@@ -29,10 +32,15 @@ interface OpenPreviewSessionInput<E> {
 
 export async function openPreviewSession<E>(
   input: OpenPreviewSessionInput<E>,
-): Promise<AtomCommandResult<PreviewSessionSnapshot, E>> {
+): Promise<AtomCommandResult<PreviewSessionSnapshot, E | BrowserSettingsReadError>> {
   // Resolved once: a tab opened before client settings hydrate would otherwise
   // be born at the schema defaults and never corrected.
-  const defaults = await resolveBrowserDefaults();
+  const defaults = await resolveBrowserDefaults().catch(
+    (cause: unknown) => new BrowserSettingsReadError({ cause }),
+  );
+  if (defaults instanceof BrowserSettingsReadError) {
+    return AsyncResult.failure(Cause.fail(defaults));
+  }
   const result = await input.openPreview({
     environmentId: input.threadRef.environmentId,
     input: {
diff --git a/apps/web/src/components/preview/openTerminalLinkInPreview.test.ts b/apps/web/src/components/preview/openTerminalLinkInPreview.test.ts
index 46dd33f7beb4..2ce81cb06af2 100644
--- a/apps/web/src/components/preview/openTerminalLinkInPreview.test.ts
+++ b/apps/web/src/components/preview/openTerminalLinkInPreview.test.ts
@@ -68,6 +68,33 @@ afterEach(() => {
 });
 
 describe("openTerminalLinkInPreview", () => {
+  it.each(["target", "defaults"] as const)(
+    "does not open either browser when reading %s fails",
+    async (setting) => {
+      const failure = new Error("Settings read failed");
+      if (setting === "target") {
+        linkTargetMocks.preference.mockImplementationOnce(() => {
+          throw failure;
+        });
+      } else {
+        browserDefaultsMocks.resolve.mockRejectedValueOnce(failure);
+      }
+      const fallbackToBrowser = vi.fn();
+      const openPreview = vi.fn(async () => AsyncResult.success(snapshot));
+
+      await expect(
+        openTerminalLinkInPreview({
+          url: "https://example.com/docs",
+          threadRef,
+          openPreview,
+          fallbackToBrowser,
+        }),
+      ).rejects.toBe(failure);
+      expect(fallbackToBrowser).not.toHaveBeenCalled();
+      expect(openPreview).not.toHaveBeenCalled();
+    },
+  );
+
   it("opens in the system browser while that is the configured target", async () => {
     linkTargetMocks.preference.mockReturnValue("system");
     const fallbackToBrowser = vi.fn();
diff --git a/apps/web/src/components/preview/previewAutomationHostBudget.test.ts b/apps/web/src/components/preview/previewAutomationHostBudget.test.ts
new file mode 100644
index 000000000000..1aaa92e19a69
--- /dev/null
+++ b/apps/web/src/components/preview/previewAutomationHostBudget.test.ts
@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  PREVIEW_HOST_RESPONSE_MARGIN_MS,
+  resolveHostWaitBudgetMs,
+  waitForHostReadiness,
+} from "./previewAutomationHostBudget";
+
+describe("resolveHostWaitBudgetMs", () => {
+  it("reserves the full response margin once the request budget allows it", () => {
+    expect(resolveHostWaitBudgetMs(15_000)).toBe(15_000 - PREVIEW_HOST_RESPONSE_MARGIN_MS);
+    expect(resolveHostWaitBudgetMs(60_000)).toBe(60_000 - PREVIEW_HOST_RESPONSE_MARGIN_MS);
+  });
+
+  it("keeps most of a short request budget instead of collapsing it", () => {
+    expect(resolveHostWaitBudgetMs(1_000)).toBe(800);
+    expect(resolveHostWaitBudgetMs(100)).toBe(80);
+  });
+
+  it("returns a non-negative budget for invalid input", () => {
+    for (const invalid of [0, -5, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(resolveHostWaitBudgetMs(invalid)).toBeGreaterThanOrEqual(0);
+    }
+  });
+});
+
+describe("waitForHostReadiness", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it.each([1, 10, 100, 250, 1_000, 15_000])(
+    "stops unavailable-overlay polling before a %ims broker timeout",
+    async (requestTimeoutMs) => {
+      const deadlineMs = Date.now() + resolveHostWaitBudgetMs(requestTimeoutMs);
+      let finishedAt: number | undefined;
+      const result = waitForHostReadiness(deadlineMs, async () => false).then((ready) => {
+        finishedAt = Date.now();
+        return ready;
+      });
+
+      await vi.advanceTimersByTimeAsync(requestTimeoutMs);
+
+      expect(await result).toBe(false);
+      expect(finishedAt).toBeLessThan(requestTimeoutMs);
+      expect(vi.getTimerCount()).toBe(0);
+    },
+  );
+
+  it("includes session setup in the deadline instead of starting a fresh wait budget", async () => {
+    const deadlineMs = Date.now() + resolveHostWaitBudgetMs(15_000);
+    await vi.advanceTimersByTimeAsync(2_000);
+    let finished = false;
+    const result = waitForHostReadiness(deadlineMs, async () => false).then((ready) => {
+      finished = true;
+      return ready;
+    });
+
+    await vi.advanceTimersByTimeAsync(11_499);
+    expect(finished).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    expect(await result).toBe(false);
+    expect(Date.now()).toBe(deadlineMs);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("skips readiness probes when setup has already exhausted the deadline", async () => {
+    const deadlineMs = Date.now() + resolveHostWaitBudgetMs(100);
+    await vi.advanceTimersByTimeAsync(100);
+    const isReady = vi.fn(async () => false);
+
+    expect(await waitForHostReadiness(deadlineMs, isReady)).toBe(false);
+    expect(isReady).not.toHaveBeenCalled();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("returns as soon as the overlay is ready and clears its timeout", async () => {
+    const isReady = vi.fn().mockResolvedValueOnce(false).mockResolvedValueOnce(true);
+    const result = waitForHostReadiness(800, isReady);
+
+    await vi.advanceTimersByTimeAsync(50);
+
+    expect(await result).toBe(true);
+    expect(isReady).toHaveBeenCalledTimes(2);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it.each([false, true])(
+    "keeps a probe result of %s that wins the deadline race",
+    async (ready) => {
+      const isReady = vi.fn(
+        () => new Promise<boolean>((resolve) => setTimeout(() => resolve(ready), 80)),
+      );
+      const result = waitForHostReadiness(80, isReady);
+
+      await vi.advanceTimersByTimeAsync(80);
+
+      expect(await result).toBe(ready);
+      expect(isReady).toHaveBeenCalledTimes(1);
+      expect(vi.getTimerCount()).toBe(0);
+    },
+  );
+
+  it("bounds a stalled status probe and ignores a late ready result", async () => {
+    let completeProbe!: (ready: boolean) => void;
+    const isReady = vi.fn(
+      () =>
+        new Promise<boolean>((resolve) => {
+          completeProbe = resolve;
+        }),
+    );
+    const result = waitForHostReadiness(80, isReady);
+
+    await vi.advanceTimersByTimeAsync(80);
+    expect(await result).toBe(false);
+    expect(vi.getTimerCount()).toBe(0);
+
+    completeProbe(true);
+    await vi.runAllTimersAsync();
+    expect(isReady).toHaveBeenCalledTimes(1);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("preserves probe failures and clears the pending timeout", async () => {
+    const error = new Error("Preview target was replaced");
+    const isReady = vi.fn().mockRejectedValue(error);
+
+    await expect(waitForHostReadiness(800, isReady)).rejects.toBe(error);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});
diff --git a/apps/web/src/components/preview/previewAutomationHostBudget.ts b/apps/web/src/components/preview/previewAutomationHostBudget.ts
new file mode 100644
index 000000000000..3cf4be00077f
--- /dev/null
+++ b/apps/web/src/components/preview/previewAutomationHostBudget.ts
@@ -0,0 +1,42 @@
+/** Allow time to deliver an overlay failure before the broker times out. */
+export const PREVIEW_HOST_RESPONSE_MARGIN_MS = 1_500;
+
+const HOST_RESPONSE_MARGIN_FRACTION = 0.2;
+
+export function resolveHostWaitBudgetMs(requestTimeoutMs: number): number {
+  if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) {
+    return 0;
+  }
+  const reservedMs = Math.min(
+    PREVIEW_HOST_RESPONSE_MARGIN_MS,
+    Math.ceil(requestTimeoutMs * HOST_RESPONSE_MARGIN_FRACTION),
+  );
+  return Math.max(0, requestTimeoutMs - reservedMs);
+}
+
+/** Both readiness probes and polling delays share the request's host deadline. */
+export async function waitForHostReadiness(
+  deadlineMs: number,
+  isReady: () => Promise<boolean>,
+): Promise<boolean> {
+  while (Date.now() < deadlineMs) {
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let ready: boolean | null;
+    try {
+      ready = await Promise.race([
+        isReady(),
+        new Promise<null>((resolve) => {
+          timeout = setTimeout(() => resolve(null), Math.max(0, deadlineMs - Date.now()));
+        }),
+      ]);
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (ready) return true;
+    if (ready === null || Date.now() >= deadlineMs) return false;
+    await new Promise<void>((resolve) =>
+      setTimeout(resolve, Math.min(50, deadlineMs - Date.now())),
+    );
+  }
+  return false;
+}
diff --git a/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx b/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx
index cc9bf0f61887..aa2d278ce249 100644
--- a/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx
@@ -58,9 +58,9 @@ import { useEnvironmentQuery } from "~/state/query";
 import { useAtomCommand } from "~/state/use-atom-command";
 
 import { DiffPanelLoadingState } from "../DiffPanelShell";
-import { DiffWorkerPoolProvider } from "../DiffWorkerPoolProvider";
 import { DiffCommentAnnotation } from "../diffs/DiffCommentAnnotation";
 import { DiffFileTree } from "../diffs/DiffFileTree";
+import { useCodeViewFileReveal } from "../diffs/useCodeViewFileReveal";
 import { diffFileTreeEntries } from "../diffs/diffFileTree.logic";
 import { StyledDiffCodeView } from "../diffs/StyledDiffCodeView";
 import { Button } from "../ui/button";
@@ -250,7 +250,7 @@ export function PullRequestCodeTab({
     readonly slices: ReadonlyArray<DiffSlice>;
   }>({ key: "", cursor: null, slices: NO_SLICES });
   const parseCache = useRef(new Map<string, RenderablePatch>());
-  const viewerRef = useRef<CodeViewHandle<ReviewAnnotationGroup> | null>(null);
+  const [viewer, setViewer] = useState<CodeViewHandle<ReviewAnnotationGroup> | null>(null);
 
   const referenceKey = pullRequestReviewKey(reference);
   const commit = selectedCommitOid;
@@ -603,21 +603,15 @@ export function PullRequestCodeTab({
     [],
   );
 
-  // Held as state so the scroll runs after a folded file has been drawn open; scrolling in the
-  // same tick would land on the folded header's position.
-  const [treeReveal, setTreeReveal] = useState<{ fileKey: string; id: number } | null>(null);
-  useEffect(() => {
-    if (treeReveal === null) return;
-    viewerRef.current?.scrollTo({ type: "item", id: treeReveal.fileKey, align: "start" });
-  }, [treeReveal]);
+  const requestTreeReveal = useCodeViewFileReveal(viewer, scopeKey);
   const revealFile = useCallback(
     (path: string) => {
       const item = items.find((candidate) => resolveFileDiffPath(candidate.fileDiff) === path);
       if (item === undefined) return;
       if (item.collapsed === true) toggleFile(item.id);
-      setTreeReveal((current) => ({ fileKey: item.id, id: (current?.id ?? 0) + 1 }));
+      requestTreeReveal(item.id);
     },
-    [items, toggleFile],
+    [items, requestTreeReveal, toggleFile],
   );
 
   const toggleAllFiles = () => {
@@ -1144,8 +1138,9 @@ export function PullRequestCodeTab({
           </Tooltip>
         ) : null}
         <ToggleGroup
-          className="shrink-0 gap-1"
-          size="sm"
+          aria-label="Diff layout"
+          className="shrink-0"
+          variant="segmented"
           value={[diffLayout]}
           onValueChange={(value) => {
             const next = value[0];
@@ -1154,10 +1149,10 @@ export function PullRequestCodeTab({
             }
           }}
         >
-          <Toggle aria-label="Stacked diff view" value="stacked" variant="ghost">
+          <Toggle aria-label="Stacked diff view" value="stacked">
             <Rows3Icon className="size-3.5" />
           </Toggle>
-          <Toggle aria-label="Split diff view" value="split" variant="ghost">
+          <Toggle aria-label="Split diff view" value="split">
             <Columns2Icon className="size-3.5" />
           </Toggle>
         </ToggleGroup>
@@ -1290,164 +1285,158 @@ export function PullRequestCodeTab({
     );
 
   return (
-    <DiffWorkerPoolProvider>
-      <div className="flex h-full min-h-0 flex-col">
-        {toolbar}
-        {/* Above the code, closed, and counted: these belong to the change rather than to any
+    <div className="flex h-full min-h-0 flex-col">
+      {toolbar}
+      {/* Above the code, closed, and counted: these belong to the change rather than to any
             line of it, and in the stream they read as cards dropped into the patch. */}
-        {orphanFiles.size > 0 ? (
-          <Collapsible
-            className="shrink-0 border-b border-border/60"
-            open={orphansOpen}
-            onOpenChange={setOrphansOpen}
-          >
-            {/* Still a heading, so the section keeps its place in a screen reader's outline;
+      {orphanFiles.size > 0 ? (
+        <Collapsible
+          className="shrink-0 border-b border-border/60"
+          open={orphansOpen}
+          onOpenChange={setOrphansOpen}
+        >
+          {/* Still a heading, so the section keeps its place in a screen reader's outline;
                 the count is spelled out there rather than left as a bare number. */}
-            <h2>
-              <CollapsibleTrigger className="flex w-full items-center gap-1.5 px-4 py-2 text-left text-xs text-muted-foreground">
-                {/* While slices are still arriving a conversation may simply belong to a file
+          <h2>
+            <CollapsibleTrigger className="flex w-full items-center gap-1.5 px-4 py-2 text-left text-xs text-muted-foreground">
+              {/* While slices are still arriving a conversation may simply belong to a file
                     that has not landed yet, which is not the same as being off the diff. */}
-                <span>
-                  {nextCursor === null
-                    ? "Conversations not on the current diff"
-                    : "Conversations not on the diff loaded so far"}
-                </span>
-                <ChevronRightIcon
-                  aria-hidden
-                  className={cn("size-3.5 transition-transform", orphansOpen && "rotate-90")}
-                />
-                <span aria-hidden className="tabular-nums">
-                  {orphanThreads.length}
-                </span>
-                <span className="sr-only">
-                  {orphanThreads.length === 1
-                    ? "1 conversation"
-                    : `${orphanThreads.length} conversations`}
-                </span>
-              </CollapsibleTrigger>
-            </h2>
-            <CollapsiblePanel>
-              {/* Capped: opened on a change with dozens of them, this would otherwise leave no
+              <span>
+                {nextCursor === null
+                  ? "Conversations not on the current diff"
+                  : "Conversations not on the diff loaded so far"}
+              </span>
+              <ChevronRightIcon
+                aria-hidden
+                className={cn("size-3.5 transition-transform", orphansOpen && "rotate-90")}
+              />
+              <span aria-hidden className="tabular-nums">
+                {orphanThreads.length}
+              </span>
+              <span className="sr-only">
+                {orphanThreads.length === 1
+                  ? "1 conversation"
+                  : `${orphanThreads.length} conversations`}
+              </span>
+            </CollapsibleTrigger>
+          </h2>
+          <CollapsiblePanel>
+            {/* Capped: opened on a change with dozens of them, this would otherwise leave no
                   room for the diff it sits above. */}
-              <div className="max-h-64 space-y-3 overflow-auto px-4 pb-3">
-                {[...orphanFiles].map(([path, threads]) => (
-                  <div key={path}>
-                    <Tooltip>
-                      <TooltipTrigger
-                        render={
-                          <p className="truncate px-3 text-xs text-muted-foreground">{path}</p>
-                        }
-                      />
-                      <TooltipPopup side="top">{path}</TooltipPopup>
-                    </Tooltip>
-                    <div className="mt-1 space-y-2">
-                      {threads.map((thread) => (
-                        <div key={thread.id}>
-                          {thread.line === null ? null : (
-                            <p className="px-3 text-xs text-muted-foreground">Line {thread.line}</p>
-                          )}
-                          {renderThreadCard(thread)}
-                        </div>
-                      ))}
-                    </div>
+            <div className="max-h-64 space-y-3 overflow-auto px-4 pb-3">
+              {[...orphanFiles].map(([path, threads]) => (
+                <div key={path}>
+                  <Tooltip>
+                    <TooltipTrigger
+                      render={<p className="truncate px-3 text-xs text-muted-foreground">{path}</p>}
+                    />
+                    <TooltipPopup side="top">{path}</TooltipPopup>
+                  </Tooltip>
+                  <div className="mt-1 space-y-2">
+                    {threads.map((thread) => (
+                      <div key={thread.id}>
+                        {thread.line === null ? null : (
+                          <p className="px-3 text-xs text-muted-foreground">Line {thread.line}</p>
+                        )}
+                        {renderThreadCard(thread)}
+                      </div>
+                    ))}
                   </div>
-                ))}
-              </div>
-            </CollapsiblePanel>
-          </Collapsible>
-        ) : null}
-        <div className="flex min-h-0 flex-1 overflow-hidden">
-          {/* Relative wrapper so the review overlay floats over the diff rather than pushing it
+                </div>
+              ))}
+            </div>
+          </CollapsiblePanel>
+        </Collapsible>
+      ) : null}
+      <div className="flex min-h-0 flex-1 overflow-hidden">
+        {/* Relative wrapper so the review overlay floats over the diff rather than pushing it
             up; the viewer inside still owns its own scrolling. */}
-          <div
-            className="relative min-h-0 min-w-0 flex-1"
-            // The chevron answers this too, but the whole header row is the target a reader
-            // actually aims for. The header lives in the viewer's shadow tree, so the capture
-            // listener walks `composedPath` — the only way to see through the shadow boundary.
-            onClickCapture={(event) => {
-              const composedPath = event.nativeEvent.composedPath?.() ?? [];
-              for (const node of composedPath) {
-                if (!(node instanceof HTMLElement)) continue;
-                // A control inside the header — the collapse chevron — handles itself, and
-                // this capture listener fires before its own click does. Leave it alone or
-                // the two toggles cancel out.
-                if (node instanceof HTMLButtonElement || node instanceof HTMLAnchorElement) {
-                  return;
-                }
-                if (node.hasAttribute("data-diffs-header")) {
-                  const filePath = node.querySelector("[data-title]")?.textContent?.trim();
-                  if (filePath === undefined || filePath === "") return;
-                  const item = items.find(
-                    (candidate) => resolveFileDiffPath(candidate.fileDiff) === filePath,
-                  );
-                  if (item !== undefined) toggleFile(item.id);
-                  return;
-                }
+        <div
+          className="relative min-h-0 min-w-0 flex-1"
+          // The chevron answers this too, but the whole header row is the target a reader
+          // actually aims for. The header lives in the viewer's shadow tree, so the capture
+          // listener walks `composedPath` — the only way to see through the shadow boundary.
+          onClickCapture={(event) => {
+            const composedPath = event.nativeEvent.composedPath?.() ?? [];
+            for (const node of composedPath) {
+              if (!(node instanceof HTMLElement)) continue;
+              // A control inside the header — the collapse chevron — handles itself, and
+              // this capture listener fires before its own click does. Leave it alone or
+              // the two toggles cancel out.
+              if (node instanceof HTMLButtonElement || node instanceof HTMLAnchorElement) {
+                return;
               }
-            }}
-          >
-            {/* The viewer virtualizes against the element it is told is scrolling and places its
+              if (node.hasAttribute("data-diffs-header")) {
+                const filePath = node.querySelector("[data-title]")?.textContent?.trim();
+                if (filePath === undefined || filePath === "") return;
+                const item = items.find(
+                  (candidate) => resolveFileDiffPath(candidate.fileDiff) === filePath,
+                );
+                if (item !== undefined) toggleFile(item.id);
+                return;
+              }
+            }
+          }}
+        >
+          {/* The viewer virtualizes against the element it is told is scrolling and places its
               rows absolutely, so it has to own that element — the thread diff panel hands it the
               same one. Scrolling from a parent instead leaves it painting over its neighbours. */}
-            <StyledDiffCodeView<ReviewAnnotationGroup>
-              // Keep scrollbar space stable so file metadata and line numbers do not shift as a
-              // diff crosses the overflow boundary. The viewer is itself focusable for keyboard
-              // interaction, but its native host outline clips and competes with the focus
-              // indicators on its actual controls.
-              className="h-full overflow-auto [scrollbar-gutter:stable]"
-              viewerRef={viewerRef}
-              items={items}
-              selectedLines={selectedLines}
-              onSelectedLinesChange={setSelectedLines}
-              options={diffViewOptions}
-              // The viewer owns the scroll container, so the sentinel that asks for the next slice
-              // has to live inside it — at the end of the files, where reaching it means the reader
-              // is running out of diff.
-              renderCodeViewFooter={renderCodeViewFooter}
-              renderHeaderPrefix={renderHeaderPrefix}
-              renderHeaderMetadata={renderHeaderMetadata}
-              renderAnnotation={renderAnnotation}
-              unsafeCSSExtra={REPLACE_FILE_COUNTS_CSS}
-            />
-            {reviewOverlay}
-          </div>
-          {fileTreeOpen ? (
-            <aside className="flex w-[min(20rem,40%)] min-w-48 shrink-0 border-l border-border/60">
-              <DiffFileTree
-                ariaLabel={`Pull request #${detail.number} files`}
-                entries={fileTreeEntries}
-                onSelectFile={revealFile}
-                // The tree lists only what has arrived; a footer says so while the diff is still
-                // paging, and lets the reader pull the rest in without scrolling for it.
-                footer={
-                  nextCursor === null ? null : (
-                    <div className="shrink-0 border-t border-border/60 p-2">
-                      <Button
-                        type="button"
-                        size="xs"
-                        variant="outline"
-                        className="w-full"
-                        disabled={diffQuery.isPending}
-                        onClick={
-                          diffQuery.error !== null ? () => diffQuery.refresh() : loadNextSlice
-                        }
-                      >
-                        {diffQuery.error !== null
-                          ? "Retry"
-                          : diffQuery.isPending
-                            ? "Loading more files..."
-                            : "Load more files"}
-                      </Button>
-                    </div>
-                  )
-                }
-              />
-            </aside>
-          ) : null}
+          <StyledDiffCodeView<ReviewAnnotationGroup>
+            // Keep scrollbar space stable so file metadata and line numbers do not shift as a
+            // diff crosses the overflow boundary. The viewer is itself focusable for keyboard
+            // interaction, but its native host outline clips and competes with the focus
+            // indicators on its actual controls.
+            className="h-full overflow-auto [scrollbar-gutter:stable]"
+            viewerRef={setViewer}
+            items={items}
+            selectedLines={selectedLines}
+            onSelectedLinesChange={setSelectedLines}
+            options={diffViewOptions}
+            // The viewer owns the scroll container, so the sentinel that asks for the next slice
+            // has to live inside it — at the end of the files, where reaching it means the reader
+            // is running out of diff.
+            renderCodeViewFooter={renderCodeViewFooter}
+            renderHeaderPrefix={renderHeaderPrefix}
+            renderHeaderMetadata={renderHeaderMetadata}
+            renderAnnotation={renderAnnotation}
+            unsafeCSSExtra={REPLACE_FILE_COUNTS_CSS}
+          />
+          {reviewOverlay}
         </div>
-        {unstructured}
+        {fileTreeOpen ? (
+          <aside className="flex w-[min(20rem,40%)] min-w-48 shrink-0 border-l border-border/60">
+            <DiffFileTree
+              ariaLabel={`Pull request #${detail.number} files`}
+              entries={fileTreeEntries}
+              onSelectFile={revealFile}
+              // The tree lists only what has arrived; a footer says so while the diff is still
+              // paging, and lets the reader pull the rest in without scrolling for it.
+              footer={
+                nextCursor === null ? null : (
+                  <div className="shrink-0 border-t border-border/60 p-2">
+                    <Button
+                      type="button"
+                      size="xs"
+                      variant="outline"
+                      className="w-full"
+                      disabled={diffQuery.isPending}
+                      onClick={diffQuery.error !== null ? () => diffQuery.refresh() : loadNextSlice}
+                    >
+                      {diffQuery.error !== null
+                        ? "Retry"
+                        : diffQuery.isPending
+                          ? "Loading more files..."
+                          : "Load more files"}
+                    </Button>
+                  </div>
+                )
+              }
+            />
+          </aside>
+        ) : null}
       </div>
-    </DiffWorkerPoolProvider>
+      {unstructured}
+    </div>
   );
 }
 
diff --git a/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx b/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
index 70533f06488f..76e50b60003b 100644
--- a/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
@@ -141,7 +141,6 @@ import {
 } from "./pullRequestProjectAssignment.logic";
 import { PullRequestChecksPopover } from "./PullRequestChecksPopover";
 import {
-  PullRequestActorAvatar,
   PullRequestActorLabel,
   PullRequestDiffStat,
   PullRequestMetaLine,
@@ -229,9 +228,8 @@ const TABS: ReadonlyArray<{ value: DetailTab; label: string }> = [
   { value: "code", label: "Code" },
 ];
 
-// The diff viewer pulls in its worker pool, so it stays out of the bundle until Code is opened.
-// Named rather than inlined so the panel can also call it itself, to start the download before
-// anyone has clicked the tab.
+// The diff viewer pulls in its worker pool, so load it only when the reader approaches Code.
+// Start the download on tab hover or focus, before the click, without loading it for every PR.
 const loadCodeTab = () => import("./PullRequestCodeTab");
 const PullRequestCodeTab = lazy(loadCodeTab);
 
@@ -525,14 +523,21 @@ export function PullRequestDetailPanel({
   // summary needs it too — a large description re-parses its whole markdown on every return
   // to the tab. `visibility` keeps boxes, sizes and scroll offsets, and takes hidden content
   // out of the tab order and the accessibility tree.
-  const [mountedTabs, setMountedTabs] = useState<ReadonlySet<DetailTab>>(
-    () => new Set<DetailTab>(["summary"]),
-  );
+  const tabScopeKey = `${environmentId}:${pullRequestKey}`;
+  const [tabMountState, setTabMountState] = useState(() => ({
+    key: tabScopeKey,
+    tabs: new Set<DetailTab>(["summary"]),
+  }));
+  // A previously visited Code tab must not fetch diffs for every later PR while hidden.
+  const mountedTabs =
+    tabMountState.key === tabScopeKey ? tabMountState.tabs : new Set<DetailTab>([tab]);
   useEffect(() => {
-    setMountedTabs((previous) =>
-      previous.has(tab) ? previous : new Set<DetailTab>(previous).add(tab),
-    );
-  }, [tab]);
+    setTabMountState((previous) => {
+      if (previous.key !== tabScopeKey) return { key: tabScopeKey, tabs: new Set([tab]) };
+      if (previous.tabs.has(tab)) return previous;
+      return { key: tabScopeKey, tabs: new Set(previous.tabs).add(tab) };
+    });
+  }, [tab, tabScopeKey]);
   const [chromeCondensed, setChromeCondensed] = useState(false);
   // Each mounted tab remembers its own scroll chrome; short tabs cannot scroll to reopen it.
   const chromeStateByTab = useRef<Partial<Record<DetailTab, boolean>>>({});
@@ -569,12 +574,6 @@ export function PullRequestDetailPanel({
   // Which handoff is preparing, keyed so a per-finding button can say "Preparing..." on itself
   // alone. One at a time whatever the key: they all check the same pull request out.
   const [handoff, setHandoff] = useState<string | null>(null);
-  // The chunk is fetched as soon as the panel exists rather than waiting for the Code tab to be
-  // clicked, so a reader who does click it lands on a chunk already in the module cache.
-  useEffect(() => {
-    void loadCodeTab();
-  }, []);
-
   const detailQuery = useEnvironmentQuery(
     pullRequestEnvironment.detail({ environmentId, input: reference }),
   );
@@ -656,6 +655,13 @@ export function PullRequestDetailPanel({
     if (detail?.autoMergeMethod !== undefined) setMergeMethod(detail.autoMergeMethod);
   }, [detail?.autoMergeMethod, pullRequestKey]);
   const repositoryUrl = detail === null ? null : changeRequestRepositoryUrl(detail.url);
+  const authorProfileUrl =
+    detail?.provider === "github" &&
+    detail.author !== null &&
+    !detail.author.login.endsWith("[bot]") &&
+    repositoryUrl !== null
+      ? new URL(`/${encodeURIComponent(detail.author.login)}`, repositoryUrl).toString()
+      : null;
   const checkoutCommand = detail
     ? pullRequestCheckoutCommand(
         detail.provider,
@@ -693,12 +699,13 @@ export function PullRequestDetailPanel({
   );
   useEffect(() => {
     if (!coreDetail) return;
-    const next = { key: pullRequestKey, updatedAt: coreDetail.updatedAt };
+    const next = { key: tabScopeKey, updatedAt: coreDetail.updatedAt };
     if (shouldRefreshPullRequestActivity(activityRevision.current, next)) {
       activityQuery.refresh();
+      setRefreshToken((token) => token + 1);
     }
     activityRevision.current = next;
-  }, [activityQuery.refresh, coreDetail, pullRequestKey]);
+  }, [activityQuery.refresh, coreDetail, tabScopeKey]);
   useLayoutEffect(() => {
     if (!resolvedCoreDetail) return;
     onStateChange?.({
@@ -707,16 +714,14 @@ export function PullRequestDetailPanel({
       state: resolvedCoreDetail.state,
     });
   }, [onStateChange, resolvedCoreDetail]);
-  // Core detail is cheap enough to re-read while this stays open. Activity is heavier, so the
-  // revision effect above reads it only after this same pull request reports a change. Keyed by
+  // Reuse activity and diff until core detail reports a changed revision. Keyed by
   // the pull request rather than by the panel, because this one panel shows a different pull
   // request every time it is opened.
   useLiveRefresh(
     () => {
       detailQuery.refresh();
-      setRefreshToken((token) => token + 1);
     },
-    { key: `pull-request:${reference.projectId}:${reference.repository}#${reference.number}` },
+    { key: `pull-request:${environmentId}:${pullRequestKey}` },
   );
   // The button, on the other hand, goes around the server's cache rather than through it: it is
   // the answer for a reader who can see that what they are looking at is behind. The
@@ -1870,19 +1875,12 @@ export function PullRequestDetailPanel({
               <div className="col-span-2 min-w-0 px-4 pb-2 pt-1">
                 <div className="flex min-w-0 items-center gap-2 text-xs text-muted-foreground">
                   <span className="flex min-w-0 shrink items-center gap-1.5 overflow-hidden text-xs text-muted-foreground">
-                    <Tooltip>
-                      <TooltipTrigger
-                        render={
-                          <span
-                            className="shrink-0 rounded-full"
-                            aria-label={detail.author?.login ?? "ghost"}
-                          />
-                        }
-                      >
-                        <PullRequestActorAvatar actor={detail.author} />
-                      </TooltipTrigger>
-                      <TooltipPopup side="top">{detail.author?.login ?? "ghost"}</TooltipPopup>
-                    </Tooltip>
+                    <PullRequestActorLabel
+                      actor={detail.author}
+                      profileUrl={authorProfileUrl}
+                      className="shrink-0 rounded-full"
+                      labelClassName="sr-only"
+                    />
                     <span className="shrink-0">{formatRelativeTimeLabel(detail.updatedAt)}</span>
                   </span>
                   <span aria-hidden className="h-3 w-px shrink-0 bg-border/70" />
@@ -2042,7 +2040,11 @@ export function PullRequestDetailPanel({
                 )}
                 <div className="mt-2 flex min-w-0 items-center gap-2 text-xs text-muted-foreground">
                   <PullRequestMetaLine className="min-w-0 whitespace-nowrap">
-                    <PullRequestActorLabel actor={detail.author} className="font-medium" />
+                    <PullRequestActorLabel
+                      actor={detail.author}
+                      profileUrl={authorProfileUrl}
+                      className="font-medium"
+                    />
                     <span>updated {formatRelativeTimeLabel(detail.updatedAt)}</span>
                   </PullRequestMetaLine>
                   {checkoutCommand ? (
@@ -2140,7 +2142,12 @@ export function PullRequestDetailPanel({
               }}
             >
               {visibleTabs.map((item) => (
-                <Toggle key={item.value} value={item.value}>
+                <Toggle
+                  key={item.value}
+                  value={item.value}
+                  onPointerEnter={item.value === "code" ? () => void loadCodeTab() : undefined}
+                  onFocus={item.value === "code" ? () => void loadCodeTab() : undefined}
+                >
                   {item.label}
                 </Toggle>
               ))}
diff --git a/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx b/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx
new file mode 100644
index 000000000000..36a4c8b15c1c
--- /dev/null
+++ b/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx
@@ -0,0 +1,119 @@
+import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
+import type { EnvironmentId, PullRequestRef } from "@t3tools/contracts";
+import { cloneElement, useState, type ComponentPropsWithoutRef, type ReactElement } from "react";
+
+import { formatRelativeTimeLabel } from "~/timestampFormat";
+import { pullRequestEnvironment } from "~/state/pullRequests";
+import { useAtomQueryRunner } from "~/state/use-atom-query-runner";
+import { useEnvironmentQuery } from "~/state/query";
+
+import { PreviewCard, PreviewCardPopup, PreviewCardTrigger } from "../ui/preview-card";
+import { PullRequestActorAvatar, resolvePullRequestState } from "./pullRequestPresentation";
+
+interface PullRequestLinkPreviewTarget {
+  readonly environmentId: EnvironmentId;
+  readonly input: PullRequestRef;
+}
+
+type PullRequestLinkElement = ReactElement<ComponentPropsWithoutRef<"a">>;
+
+export function PullRequestLinkPreview({
+  link,
+  originalUrl,
+  target,
+  confirmBeforeOpen,
+  onOpenPullRequest,
+  onOpenFallback,
+}: {
+  link: PullRequestLinkElement;
+  originalUrl: string;
+  target: PullRequestLinkPreviewTarget;
+  confirmBeforeOpen: boolean;
+  onOpenPullRequest: (url: string) => boolean;
+  onOpenFallback: (url: string) => Promise<void>;
+}) {
+  const [open, setOpen] = useState(false);
+  const [resolvingClick, setResolvingClick] = useState(false);
+  const detailQuery = useEnvironmentQuery(
+    open
+      ? pullRequestEnvironment.detail({
+          environmentId: target.environmentId,
+          input: target.input,
+        })
+      : null,
+  );
+  const readDetail = useAtomQueryRunner(pullRequestEnvironment.detail, {
+    reportFailure: false,
+    reportDefect: false,
+  });
+
+  const trigger = confirmBeforeOpen
+    ? cloneElement(link, {
+        onClick: (event) => {
+          if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+          event.preventDefault();
+          event.stopPropagation();
+          if (resolvingClick) return;
+          setOpen(false);
+          setResolvingClick(true);
+          void readDetail({ environmentId: target.environmentId, input: target.input })
+            .then(async (result) => {
+              if (isAtomCommandInterrupted(result)) return;
+              if (result._tag === "Success" && onOpenPullRequest(result.value.url)) return;
+              await onOpenFallback(originalUrl);
+            })
+            .catch((error: unknown) => {
+              console.error("[pull-request-link-preview] failed to open link", error);
+            })
+            .finally(() => setResolvingClick(false));
+        },
+      })
+    : link;
+  const detail = detailQuery.data;
+  const state =
+    detail === null
+      ? null
+      : resolvePullRequestState({ state: detail.state, isDraft: detail.isDraft });
+  const authorLabel =
+    detail?.author === null
+      ? "ghost"
+      : detail?.author.name && detail.author.name !== detail.author.login
+        ? `${detail.author.name} (@${detail.author.login})`
+        : (detail?.author.login ?? null);
+
+  return (
+    <PreviewCard open={open} onOpenChange={setOpen}>
+      <PreviewCardTrigger render={trigger} delay={350} closeDelay={120} />
+      <PreviewCardPopup align="center" className="w-80 max-w-[calc(100vw-2rem)] p-3">
+        {detail === null ? (
+          <p className="text-xs leading-relaxed text-muted-foreground wrap-anywhere">
+            {detailQuery.isPending ? "Loading pull request details…" : originalUrl}
+          </p>
+        ) : (
+          <div className="min-w-0">
+            <div className="flex min-w-0 items-center gap-1.5 text-[11px] text-muted-foreground">
+              <span className="min-w-0 truncate">{detail.repository}</span>
+              <span className="shrink-0">#{detail.number}</span>
+              <span aria-hidden>·</span>
+              {state === null ? null : (
+                <span className="inline-flex shrink-0 items-center gap-1">
+                  <state.Icon aria-hidden className={`size-3 ${state.toneClassName}`} />
+                  {state.label}
+                </span>
+              )}
+            </div>
+            <p className="mt-1 text-sm font-medium leading-snug text-foreground text-pretty">
+              {detail.title}
+            </p>
+            <div className="mt-2 flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground">
+              <PullRequestActorAvatar actor={detail.author} className="size-4" />
+              <span className="min-w-0 truncate">{authorLabel}</span>
+              <span aria-hidden>·</span>
+              <span className="shrink-0">opened {formatRelativeTimeLabel(detail.createdAt)}</span>
+            </div>
+          </div>
+        )}
+      </PreviewCardPopup>
+    </PreviewCard>
+  );
+}
diff --git a/apps/web/src/components/pullRequest/PullRequestListFilters.tsx b/apps/web/src/components/pullRequest/PullRequestListFilters.tsx
index e45a687e981d..f77e2b845082 100644
--- a/apps/web/src/components/pullRequest/PullRequestListFilters.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestListFilters.tsx
@@ -37,6 +37,7 @@ import {
   MenuPopup,
   MenuRadioGroup,
   MenuRadioItem,
+  MenuRadioItemIndicator,
   MenuSeparator,
   MenuSub,
   MenuSubPopup,
@@ -205,6 +206,7 @@ function PullRequestFilterRadioGroup<Value extends string>({
               <PullRequestFilterOptionIcon option={option} />
               <span className="min-w-0 flex-1 truncate">{option.label}</span>
               {option.unavailable ? <span className="shrink-0">· Unavailable</span> : null}
+              <MenuRadioItemIndicator />
             </span>
           </MenuRadioItem>
         );
@@ -455,8 +457,8 @@ export function PullRequestFiltersMenu({
     readonly environmentId: EnvironmentId;
     readonly title: string;
     readonly workspaceRoot: string;
-    readonly faviconPath?: string | null;
-    readonly projectIcon?: ProjectIconOverride | null;
+    readonly faviconPath?: string | null | undefined;
+    readonly projectIcon?: ProjectIconOverride | null | undefined;
   }>;
   projectId: ProjectId | undefined;
   /**
diff --git a/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx b/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
index 5fbffdd08d3d..fde29d023774 100644
--- a/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestMarkdownEditor.tsx
@@ -5,6 +5,7 @@ import { cn } from "~/lib/utils";
 
 import { Button } from "../ui/button";
 import { Textarea } from "../ui/textarea";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { PullRequestMarkdown } from "./PullRequestMarkdown";
 
 /**
@@ -64,24 +65,19 @@ export function PullRequestMarkdownEditor({
         onCancel();
       }}
     >
-      <div className="flex items-center gap-1">
-        <Button
-          size="xs"
-          variant={preview ? "ghost" : "outline"}
-          disabled={saving}
-          onClick={() => setPreview(false)}
-        >
-          Write
-        </Button>
-        <Button
-          size="xs"
-          variant={preview ? "outline" : "ghost"}
-          disabled={saving}
-          onClick={() => setPreview(true)}
-        >
-          Preview
-        </Button>
-      </div>
+      <ToggleGroup
+        aria-label="Markdown editor mode"
+        variant="segmented"
+        value={[preview ? "preview" : "write"]}
+        disabled={saving}
+        onValueChange={(next) => {
+          const mode = next[0];
+          if (mode === "write" || mode === "preview") setPreview(mode === "preview");
+        }}
+      >
+        <Toggle value="write">Write</Toggle>
+        <Toggle value="preview">Preview</Toggle>
+      </ToggleGroup>
       {preview ? (
         <div className="rounded-lg border border-border/60 px-3 py-2">
           {empty ? (
diff --git a/apps/web/src/components/pullRequest/PullRequestRow.tsx b/apps/web/src/components/pullRequest/PullRequestRow.tsx
index 6ee686a9de7e..ae7aee0168f4 100644
--- a/apps/web/src/components/pullRequest/PullRequestRow.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestRow.tsx
@@ -97,11 +97,11 @@ function PullRequestRowImpl({
       aria-current={selected ? "true" : undefined}
       onClick={() => onSelect(entry)}
       className={cn(
-        "grid w-full grid-cols-[auto_minmax(0,1fr)] items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+        "@container/pr-row grid w-full grid-cols-[auto_minmax(0,1fr)] items-center gap-3 rounded-lg px-3 py-3 text-left transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
         // Offscreen rows are skipped for style, layout and paint: a long list costs what the
         // viewport shows, not what the pages have loaded. The intrinsic size keeps the
         // scrollbar honest while a row is skipped.
-        "[contain-intrinsic-block-size:54px] [content-visibility:auto]",
+        "[contain-intrinsic-block-size:66px] [content-visibility:auto]",
         selected ? "bg-accent" : "hover:bg-accent/60",
       )}
     >
@@ -111,12 +111,36 @@ function PullRequestRowImpl({
         mergeability={entry.mergeability}
         baseBranch={entry.baseBranch}
       />
-      <span className="grid min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3 gap-y-0.5">
+      <span className="grid min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3 gap-y-1.5">
         <span className="col-start-1 row-start-1 block truncate text-sm font-medium text-foreground">
           {entry.title}
         </span>
-        <span className="col-start-2 row-start-1 justify-self-end whitespace-nowrap text-xs text-muted-foreground/70 tabular-nums">
-          {formatRelativeTimeLabel(entry.updatedAt)}
+        <span className="col-start-2 row-start-1 flex max-w-36 items-center justify-self-end gap-2 text-xs">
+          {/* Only a verdict somebody has actually given: "review required" is the absence of
+              one, and saying so on every unreviewed row would say nothing. */}
+          {entry.reviewDecision === "approved" || entry.reviewDecision === "changes-requested" ? (
+            <span
+              className={cn(
+                "sr-only @md/pr-row:not-sr-only @md/pr-row:min-w-0 @md/pr-row:truncate",
+                entry.reviewDecision === "approved"
+                  ? "text-emerald-600/90 dark:text-emerald-400/80"
+                  : "text-amber-600/90 dark:text-amber-400/80",
+              )}
+            >
+              {entry.reviewDecision === "approved" ? "Approved" : "Changes requested"}
+            </span>
+          ) : null}
+          {entry.checksState === undefined ? null : (
+            <PullRequestChecksPopover
+              checksState={entry.checksState}
+              environmentId={entry.environmentId}
+              reference={{
+                projectId: entry.projectId,
+                repository: entry.repository,
+                number: entry.number,
+              }}
+            />
+          )}
         </span>
         <PullRequestMetaLine className="@container/pr-row-meta col-start-1 row-start-2 overflow-hidden text-xs text-muted-foreground/70">
           {matchedElsewhere ? (
@@ -170,37 +194,13 @@ function PullRequestRowImpl({
             labelClassName="sr-only @xs/pr-row-meta:not-sr-only @xs/pr-row-meta:truncate"
           />
           {entry.labels.length > 0 ? <PullRequestRowLabels labels={entry.labels} /> : null}
-          {/* Only a verdict somebody has actually given: "review required" is the absence of
-              one, and saying so on every unreviewed row would say nothing. */}
-          {entry.reviewDecision === "approved" || entry.reviewDecision === "changes-requested" ? (
-            <span
-              className={cn(
-                "min-w-0 truncate",
-                entry.reviewDecision === "approved"
-                  ? "text-emerald-600/90 dark:text-emerald-400/80"
-                  : "text-amber-600/90 dark:text-amber-400/80",
-              )}
-            >
-              {entry.reviewDecision === "approved" ? "Approved" : "Changes requested"}
-            </span>
-          ) : null}
-          {entry.checksState === undefined ? null : (
-            <PullRequestChecksPopover
-              checksState={entry.checksState}
-              environmentId={entry.environmentId}
-              reference={{
-                projectId: entry.projectId,
-                repository: entry.repository,
-                number: entry.number,
-              }}
-            />
-          )}
         </PullRequestMetaLine>
-        <PullRequestDiffStat
-          additions={entry.additions}
-          deletions={entry.deletions}
-          className="col-start-2 row-start-2 justify-self-end text-xs"
-        />
+        <span className="col-start-2 row-start-2 flex items-center justify-self-end gap-3 whitespace-nowrap text-[11px] text-muted-foreground/70 tabular-nums">
+          <PullRequestDiffStat additions={entry.additions} deletions={entry.deletions} />
+          <span className="hidden @sm/pr-row:inline">
+            {formatRelativeTimeLabel(entry.updatedAt)}
+          </span>
+        </span>
       </span>
     </button>
   );
diff --git a/apps/web/src/components/pullRequest/pullRequestDetail.logic.test.ts b/apps/web/src/components/pullRequest/pullRequestDetail.logic.test.ts
index c51429ff6d83..61c630c815e4 100644
--- a/apps/web/src/components/pullRequest/pullRequestDetail.logic.test.ts
+++ b/apps/web/src/components/pullRequest/pullRequestDetail.logic.test.ts
@@ -38,7 +38,6 @@ import {
   shouldRefreshPullRequestActivity,
   resolveBaseFreshness,
   buildPullRequestTimeline,
-  describePullRequestState,
   editPullRequestThreadComment,
   writePullRequestDetailSnapshot,
 } from "./pullRequestDetail.logic";
@@ -199,15 +198,6 @@ describe("pull request primary control", () => {
   });
 });
 
-describe("pull request state description", () => {
-  it("keeps draft and conflicts orthogonal to the terminal states", () => {
-    expect(describePullRequestState("open", true)).toBe("Draft");
-    expect(describePullRequestState("open", false)).toBe("Ready for review");
-    expect(describePullRequestState("merged", true)).toBe("Merged");
-    expect(describePullRequestState("closed", false)).toBe("Closed");
-  });
-});
-
 describe("pull request handoff labels", () => {
   it("names the open thread when actions write to its composer", () => {
     expect(pullRequestHandoffLabels(true)).toEqual({
diff --git a/apps/web/src/components/pullRequest/pullRequestDetail.logic.ts b/apps/web/src/components/pullRequest/pullRequestDetail.logic.ts
index cffe33f8d83d..d00215f02d41 100644
--- a/apps/web/src/components/pullRequest/pullRequestDetail.logic.ts
+++ b/apps/web/src/components/pullRequest/pullRequestDetail.logic.ts
@@ -189,13 +189,6 @@ export function isStackedPullRequestBase(
   return defaultBranch !== baseBranch;
 }
 
-/** Plain-language state, shown beside the author. Conflicts are a merge signal, not a state. */
-export function describePullRequestState(state: PullRequestState, isDraft: boolean): string {
-  if (state === "merged") return "Merged";
-  if (state === "closed") return "Closed";
-  return isDraft ? "Draft" : "Ready for review";
-}
-
 /** Chronological ascending, oldest to newest — reversed for the "newest" reading order. */
 export function orderPullRequestComments<T extends { readonly createdAt: string }>(
   comments: ReadonlyArray<T>,
diff --git a/apps/web/src/components/pullRequest/pullRequestLinkContextMenu.test.ts b/apps/web/src/components/pullRequest/pullRequestLinkContextMenu.test.ts
index db105f97fe95..eb6f47b4c803 100644
--- a/apps/web/src/components/pullRequest/pullRequestLinkContextMenu.test.ts
+++ b/apps/web/src/components/pullRequest/pullRequestLinkContextMenu.test.ts
@@ -1,15 +1,8 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { openOnHostLabel, pullRequestLinkContextMenuItems } from "./pullRequestLinkContextMenu";
+import { openOnHostLabel } from "./pullRequestLinkContextMenu";
 
 describe("pull request link context menu", () => {
-  it("offers the copy first and the host's own page after it", () => {
-    expect(pullRequestLinkContextMenuItems("Open on GitHub")).toEqual([
-      { id: "copy-link", label: "Copy link", icon: "copy" },
-      { id: "open-external", label: "Open on GitHub" },
-    ]);
-  });
-
   it("names every host it knows, and says nothing false about one it does not", () => {
     expect(openOnHostLabel("github")).toBe("Open on GitHub");
     expect(openOnHostLabel("gitlab")).toBe("Open on GitLab");
diff --git a/apps/web/src/components/pullRequest/pullRequestLinkContextMenu.ts b/apps/web/src/components/pullRequest/pullRequestLinkContextMenu.ts
index 16b749445d4c..ef554d0eb3ee 100644
--- a/apps/web/src/components/pullRequest/pullRequestLinkContextMenu.ts
+++ b/apps/web/src/components/pullRequest/pullRequestLinkContextMenu.ts
@@ -19,7 +19,7 @@ export const openOnHostLabel = (provider: string): string =>
   OPEN_ON_HOST_LABELS[provider] ?? "Open on host";
 
 /** Copy first: it is the reason to right-click a number rather than click it. */
-export function pullRequestLinkContextMenuItems(
+function pullRequestLinkContextMenuItems(
   openLabel: string,
 ): readonly ContextMenuItem<PullRequestLinkContextMenuAction>[] {
   return [
diff --git a/apps/web/src/components/pullRequest/pullRequestList.logic.test.ts b/apps/web/src/components/pullRequest/pullRequestList.logic.test.ts
index b3fc1da8d0a3..a90022ad72c9 100644
--- a/apps/web/src/components/pullRequest/pullRequestList.logic.test.ts
+++ b/apps/web/src/components/pullRequest/pullRequestList.logic.test.ts
@@ -69,8 +69,30 @@ function entry(
 }
 
 describe("visible pull request line-count targets", () => {
+  it("reuses counts supplied by the listing and only requests missing counts", () => {
+    const entries = [
+      entry({ number: 1, additions: 12, deletions: 0 }),
+      entry({ number: 2, additions: 0, deletions: 7 }),
+      entry({ number: 3, additions: 0, deletions: 0 }),
+    ];
+    const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
+    const keys = pullRequestStatsKeysToRequest(
+      entriesByKey,
+      new Set(entries.map(pullRequestEntryKey)),
+      [],
+      new Map(),
+    );
+
+    expect(pullRequestStatsBatches(entriesByKey, keys)[0]?.input.refs).toEqual([
+      { projectId: "project-1", repository: "pingdotgg/t3code", number: 3 },
+    ]);
+  });
+
   it("does not request a row again after its received batch is pruned", () => {
-    const entries = [entry({ number: 1 }), entry({ number: 2 })];
+    const entries = [
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+    ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const firstKey = pullRequestEntryKey(entries[0]!);
     const secondKey = pullRequestEntryKey(entries[1]!);
@@ -97,7 +119,9 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("drops historical rows after a long scroll so refresh stays bounded to the viewport", () => {
-    const entries = Array.from({ length: 500 }, (_, index) => entry({ number: index + 1 }));
+    const entries = Array.from({ length: 500 }, (_, index) =>
+      entry({ additions: 0, deletions: 0, number: index + 1 }),
+    );
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const batches = entries.map(
       (item) => pullRequestStatsBatches(entriesByKey, new Set([pullRequestEntryKey(item)]))[0]!,
@@ -112,7 +136,9 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("keeps every per-environment batch within the stats contract limit", () => {
-    const entries = Array.from({ length: 501 }, (_, index) => entry({ number: index + 1 }));
+    const entries = Array.from({ length: 501 }, (_, index) =>
+      entry({ additions: 0, deletions: 0, number: index + 1 }),
+    );
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const batches = pullRequestStatsBatches(
       entriesByKey,
@@ -125,9 +151,9 @@ describe("visible pull request line-count targets", () => {
 
   it("selects visible rows for date modes and every uncached row for size modes", () => {
     const entries = [
-      entry({ number: 1 }),
-      entry({ number: 2 }),
-      entry({ number: 3, environmentId: "env-2" as EnvironmentId }),
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+      entry({ additions: 0, deletions: 0, number: 3, environmentId: "env-2" as EnvironmentId }),
     ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const [firstKey, secondKey] = entries.map(pullRequestEntryKey);
@@ -162,7 +188,11 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("refreshes only visible rows unless size sorting needs every loaded row", () => {
-    const entries = [entry({ number: 1 }), entry({ number: 2 }), entry({ number: 3 })];
+    const entries = [
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+      entry({ additions: 0, deletions: 0, number: 3 }),
+    ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const visibleKeys = new Set([pullRequestEntryKey(entries[1]!)]);
     const cachedStats = mergePullRequestDiffStats(
@@ -198,7 +228,10 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("ignores a late refresh after the filter or stats policy changes", () => {
-    const entries = [entry({ number: 1 }), entry({ number: 2 })];
+    const entries = [
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+    ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const visibleKeys = new Set([pullRequestEntryKey(entries[1]!)]);
     const requestedScope = { key: "open", policy: "visible" } as const;
@@ -217,7 +250,10 @@ describe("visible pull request line-count targets", () => {
   });
 
   it("does not add request batches again while rows are active or cached", () => {
-    const entries = [entry({ number: 1 }), entry({ number: 2 })];
+    const entries = [
+      entry({ additions: 0, deletions: 0, number: 1 }),
+      entry({ additions: 0, deletions: 0, number: 2 }),
+    ];
     const entriesByKey = new Map(entries.map((item) => [pullRequestEntryKey(item), item]));
     const first = pullRequestStatsRequestBatches({
       entriesByKey,
@@ -687,6 +723,7 @@ describe("default merge-readiness ranking", () => {
       number: 4,
       checksState: "passing",
       reviewDecision: "approved",
+      additions: 1_000,
       updatedAt: "2026-06-01T00:00:00Z",
     });
     const draft = entry({
@@ -711,7 +748,7 @@ describe("default merge-readiness ranking", () => {
     ).toEqual([4, 3, 5, 2, 6, 1]);
   });
 
-  it("uses recency inside one readiness tier", () => {
+  it("uses recency when readiness and diff size tie", () => {
     const older = entry({ number: 1, checksState: "passing" });
     const newer = entry({
       number: 2,
@@ -724,13 +761,13 @@ describe("default merge-readiness ranking", () => {
     ]);
   });
 
-  it("puts the smallest measured change first inside a readiness tier", () => {
+  it("ranks smaller measured diffs first within a readiness tier as counts arrive", () => {
     const larger = entry({
       number: 1,
       checksState: "passing",
       reviewDecision: "approved",
-      additions: 40,
-      deletions: 10,
+      additions: 1,
+      deletions: 49,
       updatedAt: "2026-09-01T00:00:00Z",
     });
     const smaller = entry({
@@ -753,6 +790,29 @@ describe("default merge-readiness ranking", () => {
     expect(
       rankPullRequestsByMergeReadiness([larger, unknown, smaller]).map((row) => row.number),
     ).toEqual([2, 1, 3]);
+    expect(
+      rankPullRequestsByMergeReadiness([
+        larger,
+        { ...unknown, additions: 1, deletions: 0 },
+        smaller,
+      ]).map((row) => row.number),
+    ).toEqual([3, 2, 1]);
+  });
+
+  it("distinguishes measured empty diffs from missing counts when sorting groups", () => {
+    const unknown = entry({ number: 1, additions: 0, deletions: 0 });
+    const measured = entry({ number: 2 });
+    const empty = entry({ number: 3, additions: 0, deletions: 0 });
+    const groups = [
+      { key: "others", label: "Others", entries: [unknown, measured, empty] },
+    ] as const;
+
+    const sorted = sortPullRequestGroups(groups, "ready", "", (row) => row.number !== 1);
+
+    expect(sorted[0]!.entries.map((row) => row.number)).toEqual([3, 2, 1]);
+    expect(sortPullRequestGroups(groups, "ready", "sidebar", (row) => row.number !== 1)).toEqual(
+      groups,
+    );
   });
 
   it("keeps authored work first and ranks each group by readiness", () => {
diff --git a/apps/web/src/components/pullRequest/pullRequestList.logic.ts b/apps/web/src/components/pullRequest/pullRequestList.logic.ts
index af1bd6ab4fbe..cee672489389 100644
--- a/apps/web/src/components/pullRequest/pullRequestList.logic.ts
+++ b/apps/web/src/components/pullRequest/pullRequestList.logic.ts
@@ -469,7 +469,11 @@ export function pullRequestStatsKeysToRequest(
     [...enteredKeys].filter((key) => {
       const entry = entriesByKey.get(key);
       return (
-        entry !== undefined && !requested.has(key) && !statsByRow.has(pullRequestDiffStatKey(entry))
+        entry !== undefined &&
+        entry.additions === 0 &&
+        entry.deletions === 0 &&
+        !requested.has(key) &&
+        !statsByRow.has(pullRequestDiffStatKey(entry))
       );
     }),
   );
@@ -1006,7 +1010,8 @@ export function rankPullRequestMatches<Entry extends PullRequestListEntry>(
  * verdict, then everything else still open. Drafts stay in that third tier because their author
  * has not made them mergeable yet. Finished work follows open work when all states are visible. A
  * known conflict is never ready, whatever its checks, review or state say, so it stays at the
- * bottom. Smaller measured changes come first within a tier; recency only breaks a remaining tie.
+ * bottom. Within each tier, smaller measured diffs come first, then unknown sizes. Recency
+ * breaks ties between equally sized diffs.
  */
 export function rankPullRequestsByMergeReadiness<Entry extends PullRequestListEntry>(
   entries: ReadonlyArray<Entry>,
@@ -1023,10 +1028,9 @@ export function rankPullRequestsByMergeReadiness<Entry extends PullRequestListEn
   return entries.toSorted((left, right) => {
     const byTier = tier(left) - tier(right);
     if (byTier !== 0) return byTier;
-    const byMeasurement = Number(hasMeasuredSize(right)) - Number(hasMeasuredSize(left));
-    if (byMeasurement !== 0) return byMeasurement;
-    const bySize = left.additions + left.deletions - (right.additions + right.deletions);
-    return bySize !== 0 ? bySize : right.updatedAt.localeCompare(left.updatedAt);
+    const measured = Number(hasMeasuredSize(right)) - Number(hasMeasuredSize(left));
+    const sized = left.additions + left.deletions - (right.additions + right.deletions);
+    return measured || sized || right.updatedAt.localeCompare(left.updatedAt);
   });
 }
 
diff --git a/apps/web/src/components/pullRequest/pullRequestPresentation.tsx b/apps/web/src/components/pullRequest/pullRequestPresentation.tsx
index f4eb7958a1d3..8611ddc28dde 100644
--- a/apps/web/src/components/pullRequest/pullRequestPresentation.tsx
+++ b/apps/web/src/components/pullRequest/pullRequestPresentation.tsx
@@ -358,11 +358,13 @@ export function PullRequestActorLabel({
   className,
   labelClassName,
   tooltip = true,
+  profileUrl,
 }: {
   actor: PullRequestActor | null;
   className?: string;
   labelClassName?: string;
   tooltip?: boolean;
+  profileUrl?: string | null;
 }) {
   const login = actor?.login ?? "ghost";
   const label = (
@@ -377,11 +379,28 @@ export function PullRequestActorLabel({
   return (
     <Tooltip>
       <TooltipTrigger
-        render={<span className={cn("flex min-w-0 items-center gap-1.5", className)} />}
+        render={
+          profileUrl ? (
+            <a
+              href={profileUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              aria-label={`Open ${login}'s profile`}
+            />
+          ) : (
+            <span />
+          )
+        }
+        className={cn(
+          "flex min-w-0 items-center gap-1.5",
+          profileUrl &&
+            "cursor-pointer rounded-sm underline-offset-2 outline-none hover:text-foreground hover:underline focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
+          className,
+        )}
       >
         {label}
       </TooltipTrigger>
-      <TooltipPopup side="top">{login}</TooltipPopup>
+      <TooltipPopup side="top">{profileUrl ? `Open ${login}'s profile` : login}</TooltipPopup>
     </Tooltip>
   );
 }
diff --git a/apps/web/src/components/pullRequest/pullRequestProjectFilter.logic.test.ts b/apps/web/src/components/pullRequest/pullRequestProjectFilter.logic.test.ts
new file mode 100644
index 000000000000..5c660118ed28
--- /dev/null
+++ b/apps/web/src/components/pullRequest/pullRequestProjectFilter.logic.test.ts
@@ -0,0 +1,158 @@
+import { EnvironmentId, ProjectId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { findScopedProject } from "./pullRequestList.logic";
+import { pullRequestFilterProjects } from "./pullRequestProjectFilter.logic";
+
+const cups = EnvironmentId.make("env-cups");
+const nucbox = EnvironmentId.make("env-nucbox");
+const labels = new Map([
+  [cups, "cups"],
+  [nucbox, "nucbox-1"],
+]);
+
+function project(
+  id: string,
+  environmentId = nucbox,
+  canonicalKey: string | null = "github.com/pingdotgg/t3code",
+) {
+  return {
+    id: ProjectId.make(id),
+    environmentId,
+    title: "t3code",
+    workspaceRoot: `/work/${id}`,
+    repositoryIdentity: canonicalKey === null ? null : { canonicalKey },
+    faviconPath: `${id}/favicon.png`,
+  };
+}
+
+describe("pull request project filter choices", () => {
+  it("collapses three checkouts on one server without dropping another server's copy", () => {
+    const projects = [
+      project("main"),
+      project("worktree-1"),
+      project("worktree-2"),
+      project("main", cups),
+    ];
+
+    const choices = pullRequestFilterProjects(projects, labels);
+
+    expect(choices.map(({ id, environmentId, title }) => ({ id, environmentId, title }))).toEqual([
+      { id: "main", environmentId: cups, title: "t3code · cups" },
+      { id: "main", environmentId: nucbox, title: "t3code · nucbox-1" },
+    ]);
+    expect(choices[1]?.workspaceRoot).toBe("/work/main");
+    expect(choices[1]?.faviconPath).toBe("main/favicon.png");
+  });
+
+  it("keeps a saved worktree selection as the repository's only choice", () => {
+    const projects = [project("main"), project("worktree"), project("worktree", cups)];
+    const selected = findScopedProject(projects, nucbox, "worktree");
+
+    const choices = pullRequestFilterProjects(projects, labels, selected);
+
+    expect(choices.filter((choice) => choice.environmentId === nucbox)).toEqual([
+      { ...projects[1], title: "t3code · nucbox-1" },
+    ]);
+    expect(findScopedProject(choices, nucbox, "worktree")).toBeDefined();
+    expect(findScopedProject(choices, nucbox, "main")).toBeUndefined();
+    expect(findScopedProject(choices, cups, "worktree")).toBeDefined();
+  });
+
+  it("matches canonical repositories regardless of casing", () => {
+    const main = project("main");
+    const worktree = project("worktree", nucbox, "GitHub.com/PingDotGG/T3Code");
+
+    expect(pullRequestFilterProjects([main, worktree], labels)).toEqual([main]);
+  });
+
+  it("does not add a server suffix after duplicate checkouts have collapsed", () => {
+    const main = project("main");
+
+    expect(pullRequestFilterProjects([main, project("worktree")], labels)).toEqual([main]);
+    expect(main.title).toBe("t3code");
+  });
+
+  it("distinguishes same-named repositories on one server by checkout path", () => {
+    const projects = [
+      project("upstream"),
+      project("fork", nucbox, "github.com/juliusmarminge/t3code"),
+    ];
+
+    const choices = pullRequestFilterProjects(projects, labels);
+
+    expect(choices.map((choice) => choice.title)).toEqual([
+      "t3code · nucbox-1 · /work/fork",
+      "t3code · nucbox-1 · /work/upstream",
+    ]);
+  });
+
+  it("keeps repositories on different hosts separate", () => {
+    const choices = pullRequestFilterProjects(
+      [project("github"), project("enterprise", nucbox, "git.example.com/pingdotgg/t3code")],
+      labels,
+    );
+
+    expect(choices.map((choice) => choice.id)).toEqual(["enterprise", "github"]);
+  });
+
+  it("does not merge projects whose repository identity is unknown", () => {
+    const choices = pullRequestFilterProjects(
+      [project("first", nucbox, null), project("second", nucbox, null)],
+      labels,
+    );
+
+    expect(choices.map((choice) => choice.title)).toEqual([
+      "t3code · nucbox-1 · /work/first",
+      "t3code · nucbox-1 · /work/second",
+    ]);
+  });
+
+  it("distinguishes servers with the same display name and checkout path", () => {
+    const first = project("main");
+    const second = project("main", cups);
+    const repeatedLabels = new Map([
+      [cups, "nucbox-1"],
+      [nucbox, "nucbox-1"],
+    ]);
+
+    const choices = pullRequestFilterProjects([first, second], repeatedLabels);
+
+    expect(choices.map((choice) => choice.title)).toEqual([
+      "t3code · nucbox-1 · /work/main · env-cups",
+      "t3code · nucbox-1 · /work/main · env-nucbox",
+    ]);
+  });
+
+  it("uses the environment id when its label is unavailable", () => {
+    const choices = pullRequestFilterProjects(
+      [project("main"), project("remote", cups)],
+      new Map(),
+    );
+
+    expect(choices.map((choice) => choice.title)).toEqual([
+      "t3code · env-cups",
+      "t3code · env-nucbox",
+    ]);
+  });
+
+  it("can distinguish unresolved project records that also share a checkout path", () => {
+    const first = project("first", nucbox, null);
+    const second = { ...project("second", nucbox, null), workspaceRoot: first.workspaceRoot };
+
+    const choices = pullRequestFilterProjects([first, second], labels);
+
+    expect(choices.map((choice) => choice.title)).toEqual([
+      "t3code · nucbox-1 · /work/first · env-nucbox · first",
+      "t3code · nucbox-1 · /work/first · env-nucbox · second",
+    ]);
+  });
+
+  it("leaves unrelated names unchanged and orders them alphabetically", () => {
+    const app = { ...project("app"), title: "Zebra" };
+    const tools = { ...project("tools", nucbox, "github.com/acme/tools"), title: "Alpha" };
+
+    expect(pullRequestFilterProjects([app, tools], labels)).toEqual([tools, app]);
+    expect(pullRequestFilterProjects([], labels)).toEqual([]);
+  });
+});
diff --git a/apps/web/src/components/pullRequest/pullRequestProjectFilter.logic.ts b/apps/web/src/components/pullRequest/pullRequestProjectFilter.logic.ts
new file mode 100644
index 000000000000..5b214e3f37f6
--- /dev/null
+++ b/apps/web/src/components/pullRequest/pullRequestProjectFilter.logic.ts
@@ -0,0 +1,53 @@
+import type { EnvironmentId } from "@t3tools/contracts";
+
+import type { AssignableProject } from "./pullRequestProjectAssignment.logic";
+
+interface FilterProject extends AssignableProject {
+  readonly title: string;
+  readonly workspaceRoot: string;
+}
+
+function distinguishTitles<Project extends FilterProject>(
+  projects: ReadonlyArray<Project>,
+  suffix: (project: Project) => string,
+) {
+  const counts = new Map<string, number>();
+  for (const project of projects) {
+    counts.set(project.title, (counts.get(project.title) ?? 0) + 1);
+  }
+  return projects.map((project) =>
+    (counts.get(project.title) ?? 0) > 1
+      ? { ...project, title: `${project.title} · ${suffix(project)}` }
+      : project,
+  );
+}
+
+/** One choice per repository per server, retaining the selected checkout for saved scopes. */
+export function pullRequestFilterProjects<Project extends FilterProject>(
+  projects: ReadonlyArray<Project>,
+  environmentLabels: ReadonlyMap<EnvironmentId, string>,
+  selectedProject?: Pick<AssignableProject, "id" | "environmentId">,
+) {
+  const byRepository = new Map<string, Project>();
+  for (const project of projects) {
+    const repository = project.repositoryIdentity?.canonicalKey?.toLowerCase();
+    const key = JSON.stringify([
+      project.environmentId,
+      repository ? ["repository", repository] : ["project", project.id],
+    ]);
+    const selected =
+      project.id === selectedProject?.id && project.environmentId === selectedProject.environmentId;
+    if (!byRepository.has(key) || selected) byRepository.set(key, project);
+  }
+
+  const byServer = distinguishTitles(
+    [...byRepository.values()],
+    (project) => environmentLabels.get(project.environmentId) ?? project.environmentId,
+  );
+  const byPath = distinguishTitles(byServer, (project) => project.workspaceRoot);
+  // Separate environments can share both their display name and their checkout path.
+  const byEnvironment = distinguishTitles(byPath, (project) => project.environmentId);
+  return distinguishTitles(byEnvironment, (project) => project.id).toSorted((left, right) =>
+    left.title.localeCompare(right.title),
+  );
+}
diff --git a/apps/web/src/components/settings/BrowserImportWizard.tsx b/apps/web/src/components/settings/BrowserImportWizard.tsx
index a18cb9173ff6..a02bb5dab24e 100644
--- a/apps/web/src/components/settings/BrowserImportWizard.tsx
+++ b/apps/web/src/components/settings/BrowserImportWizard.tsx
@@ -23,6 +23,7 @@ import {
   canCloseWizard,
   isRetryableReason,
   formatSkippedDomains,
+  fullDiskAccessRecheckStep,
   outcomeToStep,
   refreshedSourceProfileDirectory,
   refreshedSourceStep,
@@ -55,6 +56,8 @@ interface BrowserImportWizardProps {
   }) => Promise<ImportOutcome>;
   /** Re-checks the source's availability after the user quits the browser. */
   readonly onRefreshSource: () => Promise<BrowserImportSource | undefined>;
+  /** Opens the OS setting that grants access to a protected cookie store. */
+  readonly onOpenFullDiskAccessSettings: () => void;
   readonly onClose: () => void;
 }
 
@@ -72,6 +75,7 @@ export function BrowserImportWizard({
   canCreateProfile,
   onImport,
   onRefreshSource,
+  onOpenFullDiskAccessSettings,
   onClose,
 }: BrowserImportWizardProps) {
   const [source, setSource] = useState(initialSource);
@@ -111,8 +115,13 @@ export function BrowserImportWizard({
       });
   };
 
-  const recheckAfterQuit = () => {
-    setStep({ step: "checking" });
+  // Re-lists the source after the user did something outside the app (quit the
+  // browser, granted access) and routes to wherever the refreshed source says.
+  const recheckSource = (
+    check: "browser" | "fullDiskAccess",
+    nextStep: (refreshed: BrowserImportSource | undefined) => WizardStep,
+  ) => {
+    setStep({ step: "checking", check });
     void onRefreshSource()
       .then((refreshed) => {
         if (refreshed) {
@@ -121,20 +130,30 @@ export function BrowserImportWizard({
             refreshedSourceProfileDirectory(current, refreshed),
           );
         }
-        setStep(refreshedSourceStep(refreshed));
+        setStep(nextStep(refreshed));
       })
       .catch(() => setStep({ step: "blocked", reason: "readFailed" }));
   };
+  const recheckAfterQuit = () => recheckSource("browser", refreshedSourceStep);
+  const recheckFullDiskAccess = () => recheckSource("fullDiskAccess", fullDiskAccessRecheckStep);
 
   return (
     <Dialog open onOpenChange={(open) => (open || !canCloseWizard(step) ? undefined : onClose())}>
       <DialogPopup className="max-w-lg" showCloseButton={canCloseWizard(step)}>
         {step.step === "quit" ? (
           <QuitStep source={source} onCancel={onClose} onRechecked={recheckAfterQuit} />
+        ) : step.step === "fullDiskAccess" ? (
+          <FullDiskAccessStep
+            source={source}
+            onCancel={onClose}
+            onOpenSettings={onOpenFullDiskAccessSettings}
+            onGranted={step.resume === "import" ? runImport : recheckFullDiskAccess}
+            stillRequired={step.checked === true}
+          />
         ) : step.step === "importing" ? (
           <ImportingStep />
         ) : step.step === "checking" ? (
-          <CheckingStep sourceName={source.name} />
+          <CheckingStep sourceName={source.name} check={step.check} />
         ) : step.step === "done" ? (
           <DoneStep
             {...step}
@@ -223,6 +242,49 @@ type ConfigureStepProps = {
   readonly onImport: () => void;
 };
 
+function FullDiskAccessStep({
+  source,
+  onCancel,
+  onOpenSettings,
+  onGranted,
+  stillRequired,
+}: {
+  readonly source: BrowserImportSource;
+  readonly onCancel: () => void;
+  readonly onOpenSettings: () => void;
+  readonly onGranted: () => void;
+  readonly stillRequired: boolean;
+}) {
+  return (
+    <>
+      <DialogHeader>
+        <DialogTitle>Let T3 Code read {source.name}&rsquo;s cookies</DialogTitle>
+        <DialogDescription>
+          To import cookies from {source.name}, T3 Code needs Full Disk Access. Turn it on in System
+          Settings, then come back to finish the import — you can revoke it again once the import is
+          done.
+        </DialogDescription>
+      </DialogHeader>
+      {stillRequired ? (
+        <DialogPanel>
+          <p role="status" className="text-sm text-muted-foreground">
+            Full Disk Access is still required. If you just turned it on, quit and reopen T3 Code,
+            then try again.
+          </p>
+        </DialogPanel>
+      ) : null}
+      <DialogFooter>
+        <Button variant="outline" onClick={onCancel}>
+          Cancel
+        </Button>
+        <Button variant="outline" onClick={onOpenSettings}>
+          Open System Settings
+        </Button>
+        <Button onClick={onGranted}>I&rsquo;ve turned it on</Button>
+      </DialogFooter>
+    </>
+  );
+}
 function ConfigureStep({
   source,
   destinationEnvironmentName,
@@ -382,16 +444,28 @@ function ImportingStep() {
   );
 }
 
-function CheckingStep({ sourceName }: { readonly sourceName: string }) {
+function CheckingStep({
+  sourceName,
+  check,
+}: {
+  readonly sourceName: string;
+  readonly check: "browser" | "fullDiskAccess";
+}) {
   return (
     <>
       <DialogHeader>
         <DialogTitle>Checking {sourceName}</DialogTitle>
-        <DialogDescription>Checking whether the browser has closed.</DialogDescription>
+        <DialogDescription>
+          {check === "fullDiskAccess"
+            ? "Checking Full Disk Access."
+            : "Checking whether the browser has closed."}
+        </DialogDescription>
       </DialogHeader>
       <DialogPanel className="flex items-center gap-3 py-6">
         <Spinner className="size-4 text-muted-foreground" />
-        <span className="text-sm text-muted-foreground">Checking…</span>
+        <span className="text-sm text-muted-foreground">
+          {check === "fullDiskAccess" ? "Checking access…" : "Checking…"}
+        </span>
       </DialogPanel>
     </>
   );
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 1c4e034cf6a1..5a6f3ebd70b0 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1524,7 +1524,9 @@ function SavedBackendListRow({
           ) : null}
           {environment.connection.error && !resumingServerUpdate ? (
             <p className="flex min-w-0 items-center gap-2 text-destructive text-xs">
-              <span className="truncate">{connectionStatusText(environment.connection)}</span>
+              <span className="min-w-0 break-words">
+                {connectionStatusText(environment.connection)}
+              </span>
               {errorTraceId ? (
                 <button
                   type="button"
diff --git a/apps/web/src/components/settings/CustomModelEditor.tsx b/apps/web/src/components/settings/CustomModelEditor.tsx
new file mode 100644
index 000000000000..9fa65e0bf23e
--- /dev/null
+++ b/apps/web/src/components/settings/CustomModelEditor.tsx
@@ -0,0 +1,387 @@
+"use client";
+
+import { PlusIcon, XIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+import type { ProviderDriverKind, ServerProviderModel } from "@t3tools/contracts";
+import type { CustomModelDefinition } from "@t3tools/shared/model";
+
+import { cn } from "../../lib/utils";
+import { Button } from "../ui/button";
+import { Input } from "../ui/input";
+import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
+import { Switch } from "../ui/switch";
+import {
+  DESCRIPTOR_PRESETS_BY_KIND,
+  type CustomModelDraft,
+  type EditorChoice,
+  type EditorDescriptor,
+  choiceFromPreset,
+  definitionFromDraft,
+  descriptorFromPreset,
+  descriptorsFromCapabilities,
+  draftFromDefinition,
+  emptyEditorChoice,
+  emptyEditorDescriptor,
+  validateDraft,
+} from "./customModelEditor.logic";
+
+const CUSTOM_ID_VALUE = "__custom__";
+const START_FROM_NONE = "__none__";
+
+interface CustomModelEditorProps {
+  readonly instanceId: string;
+  readonly driverKind: ProviderDriverKind | null;
+  readonly entry: CustomModelDefinition;
+  /** Built-in models whose descriptors can be copied as a starting point. */
+  readonly builtInModels: ReadonlyArray<ServerProviderModel>;
+  readonly onSave: (next: CustomModelDefinition) => void;
+  readonly onCancel: () => void;
+}
+
+/**
+ * Inline editor for one custom model: display name plus the option
+ * descriptors the composer should offer for it (Reasoning effort, Fast
+ * mode, ...). Draft state is local; nothing is persisted until Save.
+ */
+export function CustomModelEditor({
+  instanceId,
+  driverKind,
+  entry,
+  builtInModels,
+  onSave,
+  onCancel,
+}: CustomModelEditorProps) {
+  const [draft, setDraft] = useState<CustomModelDraft>(() => draftFromDefinition(entry));
+  const [error, setError] = useState<string | null>(null);
+  const presets = useMemo(
+    () => (driverKind ? (DESCRIPTOR_PRESETS_BY_KIND[driverKind] ?? []) : []),
+    [driverKind],
+  );
+  const startFromCandidates = useMemo(
+    () => builtInModels.filter((model) => (model.capabilities?.optionDescriptors?.length ?? 0) > 0),
+    [builtInModels],
+  );
+  const domId = (suffix: string) => `provider-instance-${instanceId}-custom-model-${suffix}`;
+
+  const updateDescriptor = (key: string, patch: Partial<EditorDescriptor>) => {
+    setError(null);
+    setDraft((current) => ({
+      ...current,
+      descriptors: current.descriptors.map((descriptor) =>
+        descriptor.key === key ? { ...descriptor, ...patch } : descriptor,
+      ),
+    }));
+  };
+
+  const updateChoice = (descriptorKey: string, choiceKey: string, patch: Partial<EditorChoice>) => {
+    setError(null);
+    setDraft((current) => ({
+      ...current,
+      descriptors: current.descriptors.map((descriptor) => {
+        if (descriptor.key !== descriptorKey) return descriptor;
+        return {
+          ...descriptor,
+          choices: descriptor.choices.map((choice) => {
+            if (choice.key === choiceKey) return { ...choice, ...patch };
+            // Only one choice can be the default.
+            return patch.isDefault ? { ...choice, isDefault: false } : choice;
+          }),
+        };
+      }),
+    }));
+  };
+
+  const removeDescriptor = (key: string) => {
+    setError(null);
+    setDraft((current) => ({
+      ...current,
+      descriptors: current.descriptors.filter((descriptor) => descriptor.key !== key),
+    }));
+  };
+
+  const addDescriptor = (descriptor: EditorDescriptor) => {
+    setError(null);
+    setDraft((current) => ({ ...current, descriptors: [...current.descriptors, descriptor] }));
+  };
+
+  // Selecting a preset id replaces the descriptor's label/type/choices so the
+  // usual values are one click away; "Custom…" leaves the row blank to type into.
+  const applyPresetId = (descriptor: EditorDescriptor, value: string | null) => {
+    if (value === null) return;
+    if (value === CUSTOM_ID_VALUE) {
+      updateDescriptor(descriptor.key, { id: "" });
+      return;
+    }
+    const preset = presets.find((candidate) => candidate.id === value);
+    if (!preset) return;
+    updateDescriptor(descriptor.key, {
+      id: preset.id,
+      label: preset.label,
+      type: preset.type,
+      choices: (preset.choices ?? []).map(choiceFromPreset),
+      currentBooleanValue: undefined,
+      description: undefined,
+    });
+  };
+
+  const handleStartFrom = (slug: string | null) => {
+    if (slug === null || slug === START_FROM_NONE) return;
+    const model = startFromCandidates.find((candidate) => candidate.slug === slug);
+    if (!model) return;
+    setError(null);
+    setDraft((current) => ({
+      ...current,
+      descriptors: descriptorsFromCapabilities(model.capabilities, driverKind),
+    }));
+  };
+
+  const handleSave = () => {
+    const problem = validateDraft(draft);
+    if (problem) {
+      setError(problem);
+      return;
+    }
+    onSave(definitionFromDraft(draft));
+  };
+
+  const idSelectValue = (descriptor: EditorDescriptor) =>
+    presets.some((preset) => preset.id === descriptor.id) ? descriptor.id : CUSTOM_ID_VALUE;
+
+  const renderChoice = (descriptor: EditorDescriptor, choice: EditorChoice) => (
+    <div key={choice.key} className="flex items-center gap-2">
+      <Input
+        size="compact"
+        value={choice.id}
+        onChange={(event) => updateChoice(descriptor.key, choice.key, { id: event.target.value })}
+        placeholder="value"
+        className="w-28 font-mono"
+        spellCheck={false}
+        aria-label="Choice value"
+      />
+      <Input
+        size="compact"
+        value={choice.label}
+        onChange={(event) =>
+          updateChoice(descriptor.key, choice.key, { label: event.target.value })
+        }
+        placeholder="Label"
+        className="min-w-0 flex-1"
+        aria-label="Choice label"
+      />
+      <label className="flex shrink-0 items-center gap-1.5 text-[11px] text-muted-foreground">
+        <Switch
+          size="sm"
+          checked={choice.isDefault}
+          onCheckedChange={(checked) =>
+            updateChoice(descriptor.key, choice.key, { isDefault: checked })
+          }
+          aria-label="Default choice"
+        />
+        Default
+      </label>
+      <Button
+        size="icon-micro"
+        variant="ghost-muted"
+        aria-label="Remove choice"
+        onClick={() =>
+          updateDescriptor(descriptor.key, {
+            choices: descriptor.choices.filter((candidate) => candidate.key !== choice.key),
+          })
+        }
+      >
+        <XIcon className="size-3" />
+      </Button>
+    </div>
+  );
+
+  const renderDescriptor = (descriptor: EditorDescriptor, index: number) => (
+    <div
+      key={descriptor.key}
+      className="flex flex-col gap-2 rounded-md border border-border/60 bg-background/40 p-2.5"
+    >
+      <div className="flex flex-wrap items-center gap-2">
+        <span className="w-14 shrink-0 text-[11px] text-muted-foreground">Option {index + 1}</span>
+        {presets.length > 0 ? (
+          <Select
+            value={idSelectValue(descriptor)}
+            onValueChange={(value) => applyPresetId(descriptor, value)}
+          >
+            <SelectTrigger size="compact" className="w-40" aria-label="Option id">
+              <SelectValue>
+                {idSelectValue(descriptor) === CUSTOM_ID_VALUE ? "Custom…" : descriptor.id}
+              </SelectValue>
+            </SelectTrigger>
+            <SelectPopup align="start" alignItemWithTrigger={false}>
+              {presets.map((preset) => (
+                <SelectItem key={preset.id} value={preset.id}>
+                  <span className="flex items-baseline gap-2">
+                    <code className="font-mono text-xs">{preset.id}</code>
+                    <span className="text-muted-foreground">{preset.label}</span>
+                  </span>
+                </SelectItem>
+              ))}
+              <SelectItem value={CUSTOM_ID_VALUE}>Custom…</SelectItem>
+            </SelectPopup>
+          </Select>
+        ) : null}
+        {idSelectValue(descriptor) === CUSTOM_ID_VALUE ? (
+          <Input
+            size="compact"
+            value={descriptor.id}
+            onChange={(event) => updateDescriptor(descriptor.key, { id: event.target.value })}
+            placeholder="optionId"
+            className="w-36 font-mono"
+            spellCheck={false}
+            aria-label="Option id"
+          />
+        ) : null}
+        <Input
+          size="compact"
+          value={descriptor.label}
+          onChange={(event) => updateDescriptor(descriptor.key, { label: event.target.value })}
+          placeholder="Label"
+          className="min-w-0 flex-1"
+          aria-label="Option label"
+        />
+        <Select
+          value={descriptor.type}
+          onValueChange={(value) =>
+            updateDescriptor(descriptor.key, { type: value === "boolean" ? "boolean" : "select" })
+          }
+        >
+          <SelectTrigger size="compact" className="w-24" aria-label="Option type">
+            <SelectValue>{descriptor.type === "boolean" ? "Toggle" : "Choices"}</SelectValue>
+          </SelectTrigger>
+          <SelectPopup align="end" alignItemWithTrigger={false}>
+            <SelectItem value="select">Choices</SelectItem>
+            <SelectItem value="boolean">Toggle</SelectItem>
+          </SelectPopup>
+        </Select>
+        <Button
+          size="icon-micro"
+          variant="ghost-muted"
+          aria-label={`Remove option ${index + 1}`}
+          onClick={() => removeDescriptor(descriptor.key)}
+        >
+          <XIcon className="size-3" />
+        </Button>
+      </div>
+      {descriptor.type === "select" ? (
+        <div className="flex flex-col gap-1.5 pl-16">
+          {descriptor.choices.map((choice) => renderChoice(descriptor, choice))}
+          <Button
+            type="button"
+            size="xs"
+            variant="ghost-muted"
+            className="-ml-2 self-start"
+            onClick={() =>
+              updateDescriptor(descriptor.key, {
+                choices: [...descriptor.choices, emptyEditorChoice()],
+              })
+            }
+          >
+            <PlusIcon className="size-3" />
+            Add choice
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+
+  return (
+    <div
+      className="mx-2 mt-1 mb-2 flex flex-col gap-3 rounded-md border border-border bg-muted/20 p-3"
+      onKeyDown={(event) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          onCancel();
+        }
+      }}
+    >
+      <div className="flex flex-col gap-1">
+        <label htmlFor={domId("name")} className="text-xs text-muted-foreground">
+          Display name
+        </label>
+        <Input
+          id={domId("name")}
+          size="sm"
+          autoFocus
+          value={draft.name}
+          onChange={(event) => setDraft((current) => ({ ...current, name: event.target.value }))}
+          placeholder={draft.slug}
+          className="sm:w-72"
+          spellCheck={false}
+        />
+      </div>
+
+      <div className="flex flex-col gap-2">
+        <div className="flex flex-wrap items-center justify-between gap-2">
+          <span className="text-xs text-muted-foreground">Options shown in the composer</span>
+          {startFromCandidates.length > 0 ? (
+            <Select value={START_FROM_NONE} onValueChange={handleStartFrom}>
+              <SelectTrigger
+                size="compact"
+                className="w-44"
+                aria-label="Copy options from a built-in model"
+              >
+                <SelectValue>Copy from…</SelectValue>
+              </SelectTrigger>
+              <SelectPopup align="end" alignItemWithTrigger={false}>
+                {startFromCandidates.map((model) => (
+                  <SelectItem key={model.slug} value={model.slug}>
+                    {model.name}
+                  </SelectItem>
+                ))}
+              </SelectPopup>
+            </Select>
+          ) : null}
+        </div>
+        {draft.descriptors.length === 0 ? (
+          <p className="text-xs text-muted-foreground/70">
+            No custom options. The composer uses the provider's default options.
+          </p>
+        ) : null}
+        {draft.descriptors.map(renderDescriptor)}
+        <div className="flex flex-wrap gap-1">
+          {presets
+            .filter(
+              (preset) => !draft.descriptors.some((descriptor) => descriptor.id === preset.id),
+            )
+            .map((preset) => (
+              <Button
+                key={preset.id}
+                type="button"
+                size="xs"
+                variant="ghost-muted"
+                className={cn("-ml-2 first:ml-0")}
+                onClick={() => addDescriptor(descriptorFromPreset(preset))}
+              >
+                <PlusIcon className="size-3" />
+                {preset.label}
+              </Button>
+            ))}
+          <Button
+            type="button"
+            size="xs"
+            variant="ghost-muted"
+            onClick={() => addDescriptor(emptyEditorDescriptor())}
+          >
+            <PlusIcon className="size-3" />
+            Custom option
+          </Button>
+        </div>
+      </div>
+
+      {error ? <p className="text-xs text-destructive">{error}</p> : null}
+
+      <div className="flex gap-2">
+        <Button size="sm" variant="outline" onClick={handleSave}>
+          Save
+        </Button>
+        <Button size="sm" variant="ghost" onClick={onCancel}>
+          Cancel
+        </Button>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/settings/DiagnosticsSettings.tsx b/apps/web/src/components/settings/DiagnosticsSettings.tsx
index c8447b711f91..0b23fb2d2072 100644
--- a/apps/web/src/components/settings/DiagnosticsSettings.tsx
+++ b/apps/web/src/components/settings/DiagnosticsSettings.tsx
@@ -36,8 +36,10 @@ import { usePrimaryEnvironment } from "../../state/environments";
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { Button } from "../ui/button";
 import { ScrollArea } from "../ui/scroll-area";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { toastManager } from "../ui/toast";
+import { ExpandableText } from "./ExpandableText";
 import { ResourceTelemetryDiagnostics } from "./ResourceTelemetryDiagnostics";
 import { SettingsPageContainer, SettingsSection, useRelativeTimeTick } from "./settingsLayout";
 import { useAtomCommand } from "../../state/use-atom-command";
@@ -161,43 +163,6 @@ function EmptyRows({ label }: { label: string }) {
   return <div className="px-4 py-4 text-xs text-muted-foreground sm:px-5">{label}</div>;
 }
 
-function ExpandableText({
-  text,
-  className,
-  collapsedClassName = "line-clamp-3",
-  expandLabel = "Show full error",
-}: {
-  text: string;
-  className?: string;
-  collapsedClassName?: string;
-  expandLabel?: string;
-}) {
-  const [expanded, setExpanded] = useState(false);
-  const canExpand = text.length > 180 || text.includes("\n");
-
-  return (
-    <div className={cn("min-w-0", className)}>
-      <div
-        className={cn(
-          "whitespace-pre-wrap break-words",
-          !expanded && canExpand ? collapsedClassName : null,
-        )}
-      >
-        {text}
-      </div>
-      {canExpand ? (
-        <button
-          type="button"
-          className="cursor-pointer mt-1 text-[11px] font-medium text-foreground/70 underline-offset-2 hover:text-foreground hover:underline"
-          onClick={() => setExpanded((value) => !value)}
-        >
-          {expanded ? "Show less" : expandLabel}
-        </button>
-      ) : null}
-    </div>
-  );
-}
-
 function DiagnosticsTable({
   headers,
   children,
@@ -635,21 +600,23 @@ function ResourceHistoryWindowSelector({
   onSelect: (windowMs: number) => void;
 }) {
   return (
-    <div className="flex items-center rounded-md border border-border/60 p-0.5">
+    <ToggleGroup
+      aria-label="Process history period"
+      variant="segmented"
+      value={[String(selectedWindowMs)]}
+      onValueChange={(next) => {
+        const selected = RESOURCE_HISTORY_WINDOWS.find(
+          (option) => String(option.windowMs) === next[0],
+        );
+        if (selected) onSelect(selected.windowMs);
+      }}
+    >
       {RESOURCE_HISTORY_WINDOWS.map((option) => (
-        <button
-          key={option.windowMs}
-          type="button"
-          className={cn(
-            "cursor-pointer h-6 rounded-sm px-2 text-[11px] font-medium text-muted-foreground hover:text-foreground",
-            selectedWindowMs === option.windowMs && "bg-muted text-foreground",
-          )}
-          onClick={() => onSelect(option.windowMs)}
-        >
+        <Toggle key={option.windowMs} value={String(option.windowMs)}>
           {option.label}
-        </button>
+        </Toggle>
       ))}
-    </div>
+    </ToggleGroup>
   );
 }
 
diff --git a/apps/web/src/components/settings/ExpandableText.tsx b/apps/web/src/components/settings/ExpandableText.tsx
new file mode 100644
index 000000000000..de18739e5090
--- /dev/null
+++ b/apps/web/src/components/settings/ExpandableText.tsx
@@ -0,0 +1,44 @@
+import { useState } from "react";
+
+import { cn } from "../../lib/utils";
+
+/**
+ * Long error text clamped to a few lines with a toggle to reveal the rest.
+ * Short single-line text renders as-is without the toggle.
+ */
+export function ExpandableText({
+  text,
+  className,
+  collapsedClassName = "line-clamp-3",
+  expandLabel = "Show full error",
+}: {
+  text: string;
+  className?: string;
+  collapsedClassName?: string;
+  expandLabel?: string;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  const canExpand = text.length > 180 || text.includes("\n");
+
+  return (
+    <div className={cn("min-w-0", className)}>
+      <div
+        className={cn(
+          "whitespace-pre-wrap break-words",
+          !expanded && canExpand ? collapsedClassName : null,
+        )}
+      >
+        {text}
+      </div>
+      {canExpand ? (
+        <button
+          type="button"
+          className="cursor-pointer mt-1 text-[11px] font-medium text-foreground/70 underline-offset-2 hover:text-foreground hover:underline"
+          onClick={() => setExpanded((value) => !value)}
+        >
+          {expanded ? "Show less" : expandLabel}
+        </button>
+      ) : null}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/settings/IntegrationsSettings.logic.test.ts b/apps/web/src/components/settings/IntegrationsSettings.logic.test.ts
index 1c839f0cfdf8..c6d091b59e39 100644
--- a/apps/web/src/components/settings/IntegrationsSettings.logic.test.ts
+++ b/apps/web/src/components/settings/IntegrationsSettings.logic.test.ts
@@ -85,6 +85,7 @@ const failure = (reason: string) => ({
 
 describe("importFailureReason", () => {
   it("recovers the reason token from the flattened message", () => {
+    expect(importFailureReason(failure("needsFullDiskAccess"))).toBe("needsFullDiskAccess");
     expect(importFailureReason(failure("browserRunning"))).toBe("browserRunning");
     expect(importFailureReason(failure("readFailed"))).toBe("readFailed");
     expect(importFailureReason(failure("keychainUnavailable"))).toBe("keychainUnavailable");
diff --git a/apps/web/src/components/settings/IntegrationsSettings.tsx b/apps/web/src/components/settings/IntegrationsSettings.tsx
index 5b1d9ba5e21e..a3e96107b29c 100644
--- a/apps/web/src/components/settings/IntegrationsSettings.tsx
+++ b/apps/web/src/components/settings/IntegrationsSettings.tsx
@@ -55,6 +55,8 @@ import {
   MenuSeparator,
   MenuTrigger,
 } from "../ui/menu";
+import { readLocalApi } from "~/localApi";
+
 import { toastManager } from "../ui/toast";
 import {
   AlertDialog,
@@ -1168,6 +1170,19 @@ function BrowserProfilesSetting({ disabled }: { readonly disabled: boolean }) {
             runWizardImport(importSession.source, importSession.environmentId, input)
           }
           onRefreshSource={() => refreshImportSource(importSession.source.id)}
+          onOpenFullDiskAccessSettings={() => {
+            // Rejects outside the desktop shell (and on shells that predate the
+            // method), so the one toast covers every way the link can fail.
+            void readLocalApi()
+              ?.shell.openSystemSettings("full-disk-access")
+              .catch(() => {
+                toastManager.add({
+                  type: "error",
+                  title: "Could not open System Settings",
+                  description: "Open Privacy & Security → Full Disk Access manually.",
+                });
+              });
+          }}
           onClose={() => setImportSession(null)}
         />
       ) : null}
diff --git a/apps/web/src/components/settings/KeybindingsSettings.tsx b/apps/web/src/components/settings/KeybindingsSettings.tsx
index b0beea24cc47..ad99328647af 100644
--- a/apps/web/src/components/settings/KeybindingsSettings.tsx
+++ b/apps/web/src/components/settings/KeybindingsSettings.tsx
@@ -1324,7 +1324,7 @@ function KeybindingsList(props: KeybindingsListProps) {
 /** Shown in the browser build only; the desktop app receives every shortcut. */
 function BrowserKeybindingNotice() {
   return (
-    <div className="flex items-center gap-1.5 px-3 pb-2 text-[12px] text-muted-foreground sm:px-4">
+    <div className="flex items-center gap-2 px-3 py-2.5 text-[12px] leading-[1.45] text-muted-foreground sm:px-4">
       <TriangleAlertIcon className="size-3.5 shrink-0 text-warning" aria-hidden />
       <span>
         Some shortcuts may be claimed by the browser before T3 Code sees them. Use the desktop app
diff --git a/apps/web/src/components/settings/ProjectSettingsPanel.tsx b/apps/web/src/components/settings/ProjectSettingsPanel.tsx
index 41b942d09f83..7be0f15cd5c2 100644
--- a/apps/web/src/components/settings/ProjectSettingsPanel.tsx
+++ b/apps/web/src/components/settings/ProjectSettingsPanel.tsx
@@ -990,6 +990,11 @@ function ProjectDetail({ group }: { group: SidebarProjectSnapshot }) {
           <SettingsRow
             title="Automatically pull"
             description="Keeps the default branch current in the background when the checkout has no local changes or commits."
+            resetAction={
+              autoPull ? (
+                <SettingResetButton label="automatic pull" onClick={() => setAutoPull(false)} />
+              ) : null
+            }
             control={
               <Switch
                 checked={autoPull}
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.test.ts b/apps/web/src/components/settings/ProviderInstanceCard.test.ts
index ed62ff055b09..a5085774f0c6 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.test.ts
+++ b/apps/web/src/components/settings/ProviderInstanceCard.test.ts
@@ -36,11 +36,52 @@ describe("deriveProviderModelsForDisplay", () => {
     expect(
       deriveProviderModelsForDisplay({
         liveModels,
-        customModels: ["kept-custom"],
+        customModels: [{ slug: "kept-custom", name: "kept-custom", capabilities: null }],
       }).map((model) => model.slug),
     ).toEqual(["server-model", "kept-custom"]);
   });
 
+  it("prefers the entry's name and capabilities over the stale live custom row", () => {
+    const liveCapabilities = { optionDescriptors: [] };
+    const customCapabilities = {
+      optionDescriptors: [
+        {
+          id: "reasoningEffort",
+          label: "Reasoning",
+          type: "select" as const,
+          options: [{ id: "high", label: "High", isDefault: true }],
+          currentValue: "high",
+        },
+      ],
+    };
+    const liveModels: ReadonlyArray<ServerProviderModel> = [
+      { slug: "bare", name: "bare", isCustom: true, capabilities: liveCapabilities },
+      { slug: "named", name: "named", isCustom: true, capabilities: liveCapabilities },
+    ];
+
+    const display = deriveProviderModelsForDisplay({
+      liveModels,
+      customModels: [
+        { slug: "bare", name: "bare", capabilities: null },
+        { slug: "named", name: "My Model", capabilities: customCapabilities },
+      ],
+    });
+
+    // A bare entry keeps the driver default the server filled in.
+    expect(display[0]).toEqual({
+      slug: "bare",
+      name: "bare",
+      isCustom: true,
+      capabilities: liveCapabilities,
+    });
+    expect(display[1]).toEqual({
+      slug: "named",
+      name: "My Model",
+      isCustom: true,
+      capabilities: customCapabilities,
+    });
+  });
+
   it("shows a redacted provider email in the editor header status line", () => {
     const instanceId = ProviderInstanceId.make("codex");
     const driver = ProviderDriverKind.make("codex");
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.tsx b/apps/web/src/components/settings/ProviderInstanceCard.tsx
index 265030a73ff2..5c96de9d0545 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.tsx
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -25,6 +25,11 @@ import {
   type ServerProviderModel,
 } from "@t3tools/contracts";
 
+import {
+  type CustomModelDefinition,
+  readCustomModelEntries,
+  toCustomModelSetting,
+} from "@t3tools/shared/model";
 import { cn } from "../../lib/utils";
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { normalizeProviderAccentColor } from "../../providerInstances";
@@ -96,16 +101,13 @@ function providerEnvironmentsEqual(
 }
 
 /**
- * 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`.
+ * Read `customModels` from the opaque config blob. The concrete driver
+ * schemas type it as `CustomModelSetting[]`, but it arrives here as
+ * `Schema.Unknown`, so the shared reader does the shape checking.
  */
-function readConfigStringArray(config: unknown, key: string): ReadonlyArray<string> {
+function readConfigCustomModels(config: unknown): ReadonlyArray<CustomModelDefinition> {
   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");
+  return readCustomModelEntries((config as Record<string, unknown>).customModels);
 }
 
 /**
@@ -127,9 +129,14 @@ function nextConfigBlobWithValue(
   return base;
 }
 
+/**
+ * Custom rows come from current settings so name/descriptor edits show
+ * instantly; a bare entry falls back to the live row's driver-default
+ * capabilities (the server fills those in on its next probe).
+ */
 export function deriveProviderModelsForDisplay(input: {
   readonly liveModels: ReadonlyArray<ServerProviderModel> | undefined;
-  readonly customModels: ReadonlyArray<string>;
+  readonly customModels: ReadonlyArray<CustomModelDefinition>;
 }): ReadonlyArray<ServerProviderModel> {
   const liveCustomModelsBySlug = new Map(
     Arr.filterMap(input.liveModels ?? [], (model) =>
@@ -137,15 +144,13 @@ export function deriveProviderModelsForDisplay(input: {
     ),
   );
   const serverModels = input.liveModels?.filter((model) => !model.isCustom) ?? [];
-  const customModels = input.customModels.map(
-    (slug) =>
-      liveCustomModelsBySlug.get(slug) ?? {
-        slug,
-        name: slug,
-        isCustom: true,
-        capabilities: null,
-      },
-  );
+  const customModels = input.customModels.map((entry) => ({
+    slug: entry.slug,
+    name: entry.name,
+    isCustom: true,
+    capabilities:
+      entry.capabilities ?? liveCustomModelsBySlug.get(entry.slug)?.capabilities ?? null,
+  }));
   return [...serverModels, ...customModels];
 }
 
@@ -463,7 +468,7 @@ export function ProviderInstanceCard({
     ? instance.driver
     : null;
   const customModels =
-    instance.driver === "antigravity" ? [] : readConfigStringArray(instance.config, "customModels");
+    instance.driver === "antigravity" ? [] : readConfigCustomModels(instance.config);
   // 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.
@@ -504,8 +509,12 @@ export function ProviderInstanceCard({
     );
   };
 
-  const updateCustomModels = (next: ReadonlyArray<string>) => {
-    const nextConfig = nextConfigBlobWithValue(instance.config, "customModels", [...next]);
+  const updateCustomModels = (next: ReadonlyArray<CustomModelDefinition>) => {
+    const nextConfig = nextConfigBlobWithValue(
+      instance.config,
+      "customModels",
+      next.map(toCustomModelSetting),
+    );
     const { config: _omit, ...rest } = instance;
     onUpdate({ ...rest, config: nextConfig } as ProviderInstanceConfig);
   };
@@ -607,7 +616,11 @@ export function ProviderInstanceCard({
                   {instanceId}
                 </code>
               ) : null}
-              {versionCodeNode}
+              {versionLabel ? (
+                <code className="max-w-24 shrink-0 truncate text-xs text-muted-foreground">
+                  {versionLabel}
+                </code>
+              ) : null}
               {versionAdvisory ? (
                 <span role="img" aria-label="Update available" className="inline-flex shrink-0">
                   <ArrowUpCircleIcon className="size-3.5 text-muted-foreground" />
diff --git a/apps/web/src/components/settings/ProviderModelsSection.tsx b/apps/web/src/components/settings/ProviderModelsSection.tsx
index 7b98dbe42991..7866578cfa4a 100644
--- a/apps/web/src/components/settings/ProviderModelsSection.tsx
+++ b/apps/web/src/components/settings/ProviderModelsSection.tsx
@@ -1,13 +1,13 @@
 "use client";
 
-import { ArrowDownIcon, ArrowUpIcon, PlusIcon, StarIcon, XIcon } from "lucide-react";
+import { ArrowDownIcon, ArrowUpIcon, PencilIcon, PlusIcon, StarIcon, XIcon } from "lucide-react";
 import { useEffect, useMemo, useRef, useState } from "react";
 import {
   ProviderDriverKind,
   type ProviderInstanceId,
   type ServerProviderModel,
 } from "@t3tools/contracts";
-import { normalizeCustomModelSlug } from "@t3tools/shared/model";
+import { type CustomModelDefinition, normalizeCustomModelSlug } from "@t3tools/shared/model";
 
 import { cn } from "../../lib/utils";
 import { sortModelsForProviderInstance } from "../../modelOrdering";
@@ -16,6 +16,7 @@ import { Button } from "../ui/button";
 import { Input } from "../ui/input";
 import { Switch } from "../ui/switch";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { CustomModelEditor } from "./CustomModelEditor";
 
 /**
  * Placeholder text for the "add a custom model" input, keyed by driver
@@ -109,11 +110,11 @@ interface ProviderModelsSectionProps {
    */
   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 /
+   * The persisted custom-model list for this instance, resolved. Drives
+   * dedup, and is the list we hand back (with an entry appended / replaced /
    * removed) via `onChange`.
    */
-  readonly customModels: ReadonlyArray<string>;
+  readonly customModels: ReadonlyArray<CustomModelDefinition>;
   /** Server-returned model slugs hidden from the model picker. */
   readonly hiddenModels: ReadonlyArray<string>;
   /** Model slugs favorited for this provider instance. */
@@ -125,7 +126,7 @@ interface ProviderModelsSectionProps {
    * write to the correct storage (legacy `settings.providers[kind]` vs.
    * `providerInstances[id].config`).
    */
-  readonly onChange: (next: ReadonlyArray<string>) => void;
+  readonly onChange: (next: ReadonlyArray<CustomModelDefinition>) => void;
   readonly onHiddenModelsChange: (next: ReadonlyArray<string>) => void;
   readonly onFavoriteModelsChange: (next: ReadonlyArray<string>) => void;
   readonly onModelOrderChange: (next: ReadonlyArray<string>) => void;
@@ -159,6 +160,8 @@ export function ProviderModelsSection({
   const [isAdding, setIsAdding] = useState(false);
   const [filter, setFilter] = useState("");
   const [error, setError] = useState<string | null>(null);
+  // Slug of the custom model whose inline editor is open, if any.
+  const [editingSlug, setEditingSlug] = useState<string | null>(null);
   const listRef = useRef<HTMLDivElement>(null);
   // Slug of a just-added custom model, scrolled into view once its row exists.
   const scrollToSlugRef = useRef<string | null>(null);
@@ -177,6 +180,7 @@ export function ProviderModelsSection({
   const hiddenCount = displayModels.filter(
     (model) => !model.isCustom && hiddenModelSet.has(model.slug),
   ).length;
+  const builtInModels = useMemo(() => models.filter((model) => !model.isCustom), [models]);
   const showFilter = models.length > FILTER_THRESHOLD;
   const normalizedFilter = filter.trim().toLowerCase();
   const isFiltering = showFilter && normalizedFilter.length > 0;
@@ -216,7 +220,7 @@ export function ProviderModelsSection({
       setError(`Model slugs must be ${MAX_CUSTOM_MODEL_LENGTH} characters or less.`);
       return;
     }
-    if (customModels.includes(normalized)) {
+    if (customModels.some((entry) => entry.slug === normalized)) {
       setError("That custom model is already saved.");
       return;
     }
@@ -225,7 +229,7 @@ export function ProviderModelsSection({
     // which is also what lets the pending scroll target resolve and clear.
     scrollToSlugRef.current = normalized;
     setFilter("");
-    onChange([...customModels, normalized]);
+    onChange([...customModels, { slug: normalized, name: normalized, capabilities: null }]);
     setInput("");
     setError(null);
     setIsAdding(false);
@@ -238,12 +242,18 @@ export function ProviderModelsSection({
   };
 
   const handleRemove = (slug: string) => {
-    onChange(customModels.filter((model) => model !== slug));
+    if (editingSlug === slug) setEditingSlug(null);
+    onChange(customModels.filter((entry) => entry.slug !== slug));
     onModelOrderChange(modelOrder.filter((model) => model !== slug));
     onFavoriteModelsChange(favoriteModels.filter((model) => model !== slug));
     setError(null);
   };
 
+  const handleSaveEdit = (next: CustomModelDefinition) => {
+    onChange(customModels.map((entry) => (entry.slug === next.slug ? next : entry)));
+    setEditingSlug(null);
+  };
+
   const setHidden = (slug: string, hidden: boolean) => {
     if (hidden === hiddenModelSet.has(slug)) return;
     onHiddenModelsChange(
@@ -355,21 +365,40 @@ export function ProviderModelsSection({
         </>
       ) : null}
       {model.isCustom ? (
-        <Tooltip>
-          <TooltipTrigger
-            render={
-              <Button
-                size="icon-micro"
-                variant="ghost-muted"
-                aria-label={`Remove ${model.slug}`}
-                onClick={() => handleRemove(model.slug)}
-              />
-            }
-          >
-            <XIcon className="size-3" />
-          </TooltipTrigger>
-          <TooltipPopup side="top">Remove custom model</TooltipPopup>
-        </Tooltip>
+        <>
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <Button
+                  size="icon-micro"
+                  variant="ghost-muted"
+                  aria-label={`Edit ${model.slug}`}
+                  onClick={() =>
+                    setEditingSlug((current) => (current === model.slug ? null : model.slug))
+                  }
+                />
+              }
+            >
+              <PencilIcon className="size-3" />
+            </TooltipTrigger>
+            <TooltipPopup side="top">Edit name and options</TooltipPopup>
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger
+              render={
+                <Button
+                  size="icon-micro"
+                  variant="ghost-muted"
+                  aria-label={`Remove ${model.slug}`}
+                  onClick={() => handleRemove(model.slug)}
+                />
+              }
+            >
+              <XIcon className="size-3" />
+            </TooltipTrigger>
+            <TooltipPopup side="top">Remove custom model</TooltipPopup>
+          </Tooltip>
+        </>
       ) : null}
     </span>
   );
@@ -420,20 +449,23 @@ export function ProviderModelsSection({
         key={`${instanceId}:${model.slug}`}
         data-model-slug={model.slug}
         className={cn(
-          "grid h-7 grid-cols-[1.5rem_minmax(0,1fr)_auto_4rem_auto] items-center gap-2 rounded-md px-2 transition-colors hover:bg-muted/30",
+          // Actions column is at least wide enough for the four custom-row
+          // buttons so capability labels line up across built-in and custom rows.
+          "grid h-7 grid-cols-[1.5rem_minmax(0,1fr)_auto_minmax(5.5rem,auto)_auto] items-center gap-2 rounded-md px-2 transition-colors hover:bg-muted/30",
           isHidden && "opacity-50",
         )}
       >
         {starButton(model, isFavorite)}
         <span className="flex min-w-0 items-baseline gap-2">
           <span className={cn(nameClassName, "truncate")}>{model.name}</span>
-          {model.isCustom ? (
-            <span className="text-[11px] text-muted-foreground/70">custom</span>
-          ) : model.name !== model.slug ? (
+          {model.name !== model.slug ? (
             <code className="truncate font-mono text-[11px] text-muted-foreground/70">
               {model.slug}
             </code>
           ) : null}
+          {model.isCustom ? (
+            <span className="text-[11px] text-muted-foreground/70">custom</span>
+          ) : null}
         </span>
         {/*
           Always a grid item so the columns line up across rows; the text
@@ -489,6 +521,10 @@ export function ProviderModelsSection({
           const group = groupOf(model);
           const previous = visibleModels[index - 1];
           const startsGroup = previous === undefined || groupOf(previous) !== group;
+          const editingEntry =
+            model.isCustom && editingSlug === model.slug
+              ? customModels.find((entry) => entry.slug === model.slug)
+              : undefined;
           return (
             <div key={`${instanceId}:${model.slug}:group`}>
               {startsGroup && favoriteCount > 0 && group === "favorite"
@@ -501,6 +537,17 @@ export function ProviderModelsSection({
                 ? groupLabel("Hidden from picker", index === 0)
                 : null}
               {renderRow(model)}
+              {editingEntry ? (
+                <CustomModelEditor
+                  key={`${instanceId}:${model.slug}:editor`}
+                  instanceId={instanceId}
+                  driverKind={driverKind}
+                  entry={editingEntry}
+                  builtInModels={builtInModels}
+                  onSave={handleSaveEdit}
+                  onCancel={() => setEditingSlug(null)}
+                />
+              ) : null}
             </div>
           );
         })}
diff --git a/apps/web/src/components/settings/ProviderSettingsForm.test.ts b/apps/web/src/components/settings/ProviderSettingsForm.test.ts
index 7dc13fa4f25c..4bb8cf11bd4e 100644
--- a/apps/web/src/components/settings/ProviderSettingsForm.test.ts
+++ b/apps/web/src/components/settings/ProviderSettingsForm.test.ts
@@ -5,8 +5,6 @@ import { DRIVER_OPTION_BY_VALUE } from "./providerDriverMeta";
 import {
   deriveProviderSettingsFields,
   nextProviderConfigWithFieldValue,
-  readProviderConfigBoolean,
-  readProviderConfigString,
 } from "./ProviderSettingsForm";
 
 describe("ProviderSettingsForm helpers", () => {
@@ -90,10 +88,6 @@ describe("ProviderSettingsForm helpers", () => {
     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 },
@@ -156,12 +150,4 @@ describe("ProviderSettingsForm helpers", () => {
 
     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
index 902fd408b54f..6d644aaf01c5 100644
--- a/apps/web/src/components/settings/ProviderSettingsForm.tsx
+++ b/apps/web/src/components/settings/ProviderSettingsForm.tsx
@@ -119,17 +119,13 @@ export function deriveProviderSettingsFields(
     });
 }
 
-export function readProviderConfigString(config: unknown, key: string): string {
+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 {
+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;
diff --git a/apps/web/src/components/settings/ProviderSettingsPanel.tsx b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
index b25c127570c6..fb4620b054c1 100644
--- a/apps/web/src/components/settings/ProviderSettingsPanel.tsx
+++ b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
@@ -1,5 +1,5 @@
 import { useAtomValue } from "@effect/atom-react";
-import { connectionStatusText } from "@t3tools/client-runtime/connection";
+import { connectionStatusTitle } from "@t3tools/client-runtime/connection";
 import { safeErrorLogAttributes } from "@t3tools/client-runtime/errors";
 import {
   isAtomCommandInterrupted,
@@ -49,13 +49,19 @@ import {
   connectionPhasePingClassName,
 } from "../ConnectionStatusDot";
 import {
-  canOneClickUpdateProviderCandidate,
-  collectProviderUpdateCandidates,
-  hasOneClickUpdateProviderCandidate,
+  isProviderSettingsUpdateCandidate,
   isProviderUpdateActive,
-  type ProviderUpdateCandidate,
+  type ProviderSettingsUpdateCandidate,
 } from "../ProviderUpdateLaunchNotification.logic";
 import { Button } from "../ui/button";
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "../ui/empty";
 import {
   NumberField,
   NumberFieldDecrement,
@@ -64,14 +70,15 @@ import {
   NumberFieldInput,
 } from "../ui/number-field";
 import { ScrollArea } from "../ui/scroll-area";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { stackedThreadToast, toastManager } from "../ui/toast";
 import { AddProviderInstanceDialog } from "./AddProviderInstanceDialog";
+import { ExpandableText } from "./ExpandableText";
 import { ProviderInstanceCard } from "./ProviderInstanceCard";
 import { UsageProviderSettings } from "./UsageProviderSettings";
 import { ProviderSetupSection, readAntigravityAuthMethod } from "./ProviderSetupSection";
 import { DRIVER_OPTIONS, getDriverOption } from "./providerDriverMeta";
-import { providerSettingsTabClassName } from "./providerSettingsTabs";
 import { searchableSetting } from "./settingsSearch";
 import {
   backgroundActivityOverrideSettings,
@@ -159,7 +166,54 @@ function providerEnvironmentDetail(environment: EnvironmentPresentation): string
   return environment.displayUrl ?? "Remote device";
 }
 
-function EnvironmentUnavailableRow({
+const providerCardClassName = "rounded-xl border border-border/60 bg-card/40 shadow-xs/5";
+// Shared by the editor grid and the placeholder states so switching devices
+// never changes the card's footprint.
+const providerCardHeightClassName = "lg:h-[min(44rem,calc(100dvh-11rem))] lg:min-h-[32rem]";
+
+/**
+ * Same chrome as the provider editor (section heading, floating device tabs,
+ * tall card) for states that cannot render provider settings yet.
+ */
+function ProviderSettingsPlaceholder({
+  deviceTabs,
+  icon,
+  title,
+  description,
+  children,
+}: {
+  readonly deviceTabs?: ReactNode;
+  readonly icon: ReactNode;
+  readonly title: string;
+  readonly description: string;
+  readonly children?: ReactNode;
+}) {
+  return (
+    <SettingsSection {...searchableSetting("providers")} hideTitle variant="plain">
+      {deviceTabs ? (
+        <div className="flex min-h-11 min-w-0 items-center px-3 sm:px-4">{deviceTabs}</div>
+      ) : null}
+      <div
+        className={cn(
+          providerCardClassName,
+          providerCardHeightClassName,
+          "flex overflow-x-hidden overflow-y-auto",
+        )}
+      >
+        <Empty className="min-h-88">
+          <EmptyMedia variant="icon">{icon}</EmptyMedia>
+          <EmptyHeader>
+            <EmptyTitle>{title}</EmptyTitle>
+            <EmptyDescription>{description}</EmptyDescription>
+          </EmptyHeader>
+          {children ? <EmptyContent className="max-w-xl">{children}</EmptyContent> : null}
+        </Empty>
+      </div>
+    </SettingsSection>
+  );
+}
+
+function EnvironmentUnavailablePlaceholder({
   environment,
   access,
   deviceTabs,
@@ -174,18 +228,33 @@ function EnvironmentUnavailableRow({
     : access.kind === "error"
       ? "Could not connect to this device"
       : "Provider settings are unavailable";
+  // Keep the description to a short status; the raw failure can be a
+  // multi-paragraph CLI dump, so it goes below, clamped and expandable.
   const description = isLoading
     ? access.reason === "permissions"
       ? "Checking what this session is allowed to change."
       : `Waiting for ${environment.label}'s configuration.`
-    : connectionStatusText(environment.connection);
+    : connectionStatusTitle(environment.connection);
+  const error = isLoading ? null : environment.connection.error;
   // No spinner: this state can persist indefinitely for a wedged device, and a
   // continuously repainting animation would run the whole time.
   return (
-    <SettingsSection {...searchableSetting("providers")}>
-      {deviceTabs}
-      <SettingsRow title={title} description={description} />
-    </SettingsSection>
+    <ProviderSettingsPlaceholder
+      deviceTabs={deviceTabs}
+      icon={
+        <EnvironmentMachineIcon kind={resolveEnvironmentMachineKind(environment.serverConfig)} />
+      }
+      title={title}
+      description={description}
+    >
+      {error ? (
+        <ExpandableText
+          key={environment.environmentId}
+          text={error}
+          className="w-full text-left font-mono text-xs leading-relaxed text-muted-foreground"
+        />
+      ) : null}
+    </ProviderSettingsPlaceholder>
   );
 }
 
@@ -254,23 +323,26 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
     options.length === 1 && options[0]?.entry.target._tag === "PrimaryConnectionTarget";
   const deviceTabs =
     !onlyPrimaryDevice && options.length > 0 ? (
-      <ScrollArea hideScrollbars scrollFade className="mx-3 h-11 min-w-0 rounded-none sm:mx-4">
-        <div role="group" aria-label="Devices" className="flex h-full w-max min-w-full px-1">
+      <ScrollArea hideScrollbars scrollFade className="h-11 min-w-0 flex-1 rounded-none">
+        <ToggleGroup
+          aria-label="Devices"
+          variant="segmented"
+          className="my-2"
+          value={effectiveEnvironmentId ? [effectiveEnvironmentId] : []}
+          onValueChange={(next) => {
+            const environment = options.find((option) => option.environmentId === next[0]);
+            if (environment) setSelectedEnvironmentId(environment.environmentId);
+          }}
+        >
           {options.map((environment) => {
             const machine = resolveEnvironmentMachineKind(environment.serverConfig);
-            const selected = environment.environmentId === effectiveEnvironmentId;
             const detail = providerEnvironmentDetail(environment);
-            const statusText = connectionStatusText(environment.connection);
+            const statusText = connectionStatusTitle(environment.connection);
             return (
               <Tooltip key={environment.environmentId}>
                 <TooltipTrigger
                   render={
-                    <button
-                      type="button"
-                      aria-pressed={selected}
-                      className={cn(providerSettingsTabClassName(selected), "gap-2 text-left")}
-                      onClick={() => setSelectedEnvironmentId(environment.environmentId)}
-                    >
+                    <Toggle value={environment.environmentId} className="gap-2 text-left">
                       <EnvironmentMachineIcon
                         kind={machine}
                         className="size-3.5 shrink-0"
@@ -286,7 +358,7 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
                       <span className="sr-only">
                         {detail}, {statusText}
                       </span>
-                    </button>
+                    </Toggle>
                   }
                 />
                 <TooltipPopup side="top">
@@ -295,32 +367,30 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
               </Tooltip>
             );
           })}
-        </div>
+        </ToggleGroup>
       </ScrollArea>
     ) : null;
 
   return (
     <>
       {targetEnvironmentMissing ? (
-        <SettingsSection {...searchableSetting("providers")}>
-          {deviceTabs}
-          <SettingsRow
-            title="Device unavailable"
-            description="Reconnect this device to set up its provider, or select another device."
-          />
-        </SettingsSection>
+        <ProviderSettingsPlaceholder
+          deviceTabs={deviceTabs}
+          icon={<EnvironmentMachineIcon kind={resolveEnvironmentMachineKind(null)} />}
+          title="Device unavailable"
+          description="Reconnect this device to set up its provider, or select another device."
+        />
       ) : null}
       {options.length === 0 && !targetEnvironmentMissing ? (
-        <SettingsSection {...searchableSetting("providers")}>
-          <SettingsRow
-            title={isReady ? "No connected devices" : "Loading devices"}
-            description={
-              isReady
-                ? "Connect an execution environment before configuring providers."
-                : "Reading connected execution environments."
-            }
-          />
-        </SettingsSection>
+        <ProviderSettingsPlaceholder
+          icon={<EnvironmentMachineIcon kind={resolveEnvironmentMachineKind(null)} />}
+          title={isReady ? "No connected devices" : "Loading devices"}
+          description={
+            isReady
+              ? "Connect an execution environment before configuring providers."
+              : "Reading connected execution environments."
+          }
+        />
       ) : null}
 
       {selectedEnvironment ? (
@@ -450,7 +520,7 @@ function AccessGatedProviderSettings({
   });
   if (access.kind !== "editable" && access.kind !== "read-only") {
     return (
-      <EnvironmentUnavailableRow
+      <EnvironmentUnavailablePlaceholder
         environment={environment}
         access={access}
         deviceTabs={deviceTabs}
@@ -502,19 +572,20 @@ export function EnvironmentProviderSettings({
   const [selectedInstanceId, setSelectedInstanceId] = useState<ProviderInstanceId | null>(
     targetInstanceId ?? null,
   );
-  const [updatingProviderDrivers, setUpdatingProviderDrivers] = useState<
-    ReadonlySet<ProviderDriverKind>
+  const [updatingProviderInstanceIds, setUpdatingProviderInstanceIds] = useState<
+    ReadonlySet<ProviderInstanceId>
   >(() => new Set());
   const refreshingRef = useRef(false);
-  const updatingDriversRef = useRef<Set<ProviderDriverKind>>(new Set());
+  const updatingInstanceIdsRef = useRef<Set<ProviderInstanceId>>(new Set());
 
-  const providerUpdateCandidates = useMemo(
-    () => collectProviderUpdateCandidates(serverProviders),
-    [serverProviders],
-  );
   const providerUpdateCandidateByInstanceId = useMemo(
-    () => new Map(providerUpdateCandidates.map((candidate) => [candidate.instanceId, candidate])),
-    [providerUpdateCandidates],
+    () =>
+      new Map(
+        serverProviders
+          .filter(isProviderSettingsUpdateCandidate)
+          .map((candidate) => [candidate.instanceId, candidate]),
+      ),
+    [serverProviders],
   );
   const visibleProviderSettings = PROVIDER_SETTINGS.filter(
     (providerSettings) =>
@@ -564,14 +635,14 @@ export function EnvironmentProviderSettings({
   }, [environmentId, refreshServerProviders]);
 
   const runProviderUpdate = useCallback(
-    async (candidate: ProviderUpdateCandidate) => {
+    async (candidate: ProviderSettingsUpdateCandidate) => {
       // Ref-based re-entry guard, mirroring refreshProviders: a state updater
       // may run after this function returns, so it cannot gate the dispatch.
-      if (updatingDriversRef.current.has(candidate.driver)) {
+      if (updatingInstanceIdsRef.current.has(candidate.instanceId)) {
         return;
       }
-      updatingDriversRef.current.add(candidate.driver);
-      setUpdatingProviderDrivers((previous) => new Set(previous).add(candidate.driver));
+      updatingInstanceIdsRef.current.add(candidate.instanceId);
+      setUpdatingProviderInstanceIds((previous) => new Set(previous).add(candidate.instanceId));
 
       const result = await updateProvider({
         environmentId,
@@ -593,13 +664,13 @@ export function EnvironmentProviderSettings({
           }),
         );
       }
-      updatingDriversRef.current.delete(candidate.driver);
-      setUpdatingProviderDrivers((previous) => {
-        if (!previous.has(candidate.driver)) {
+      updatingInstanceIdsRef.current.delete(candidate.instanceId);
+      setUpdatingProviderInstanceIds((previous) => {
+        if (!previous.has(candidate.instanceId)) {
           return previous;
         }
         const next = new Set(previous);
-        next.delete(candidate.driver);
+        next.delete(candidate.instanceId);
         return next;
       });
     },
@@ -800,23 +871,13 @@ export function EnvironmentProviderSettings({
     const liveProvider = serverProviders.find(
       (candidate) => candidate.instanceId === row.instanceId,
     );
-    const updateCandidate = liveProvider
-      ? providerUpdateCandidateByInstanceId.get(liveProvider.instanceId)
-      : undefined;
-    const isDriverUpdateRunning =
-      updateCandidate !== undefined &&
-      (updatingProviderDrivers.has(updateCandidate.driver) ||
-        serverProviders.some(
-          (provider) =>
-            provider.driver === updateCandidate.driver && isProviderUpdateActive(provider),
-        ));
-    const showInlineUpdateButton =
-      updateCandidate !== undefined &&
-      hasOneClickUpdateProviderCandidate(updateCandidate, serverProviders);
-    const canRunInlineUpdate =
+    const updateCandidate = providerUpdateCandidateByInstanceId.get(row.instanceId);
+    const isInstanceUpdateRunning =
       updateCandidate !== undefined &&
-      canOneClickUpdateProviderCandidate(updateCandidate, serverProviders) &&
-      !updatingProviderDrivers.has(updateCandidate.driver);
+      (updatingProviderInstanceIds.has(updateCandidate.instanceId) ||
+        isProviderUpdateActive(updateCandidate));
+    const showInlineUpdateButton = updateCandidate !== undefined;
+    const canRunInlineUpdate = updateCandidate !== undefined && !isInstanceUpdateRunning;
     const modelPreferences = settings.providerModelPreferences?.[row.instanceId] ?? {
       hiddenModels: [],
       modelOrder: [],
@@ -903,18 +964,19 @@ export function EnvironmentProviderSettings({
               }
             : undefined
         }
-        isUpdating={mode === "editor" && showInlineUpdateButton ? isDriverUpdateRunning : undefined}
+        isUpdating={
+          mode === "editor" && showInlineUpdateButton ? isInstanceUpdateRunning : undefined
+        }
       />
     );
   };
 
   return (
     <>
-      <SettingsSection
-        {...searchableSetting("providers")}
-        variant="plain"
-        headerAction={
-          <div className="flex min-w-0 items-center gap-2">
+      <SettingsSection {...searchableSetting("providers")} hideTitle variant="plain">
+        <div className="flex min-h-11 min-w-0 items-center gap-2 px-3 sm:px-4">
+          {deviceTabs}
+          <div className="ml-auto flex min-w-0 shrink-0 items-center gap-2">
             {readOnly ? (
               <span className="min-w-0 truncate text-xs text-muted-foreground">
                 <ProviderLastChecked lastCheckedAt={lastCheckedAt} />
@@ -963,18 +1025,22 @@ export function EnvironmentProviderSettings({
               </>
             )}
           </div>
-        }
-      >
-        {deviceTabs}
+        </div>
         {readOnly ? (
-          <div className="overflow-hidden rounded-xl border border-border/60 bg-card/40 shadow-xs/5">
+          <div className={cn(providerCardClassName, "overflow-hidden")}>
             <SettingsRow
               title="Limited permissions"
               description={`This session can view ${environmentLabel}'s providers but can't change their settings.`}
             />
           </div>
         ) : null}
-        <div className="overflow-hidden rounded-xl border border-border/60 bg-card/40 shadow-xs/5 lg:grid lg:h-[min(44rem,calc(100dvh-11rem))] lg:min-h-[32rem] lg:grid-cols-[17rem_minmax(0,1fr)]">
+        <div
+          className={cn(
+            providerCardClassName,
+            providerCardHeightClassName,
+            "overflow-hidden lg:grid lg:grid-cols-[17rem_minmax(0,1fr)]",
+          )}
+        >
           <div className="border-b border-border/60 bg-muted/10 lg:flex lg:min-h-0 lg:flex-col lg:border-r lg:border-b-0">
             <ScrollArea scrollFade chainVerticalScroll className="lg:min-h-0 lg:flex-1">
               <div className="divide-y divide-border/50">
diff --git a/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx
index 741cd3c3f37f..ca934952f8a9 100644
--- a/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx
+++ b/apps/web/src/components/settings/ResourceTelemetryDiagnostics.tsx
@@ -45,6 +45,7 @@ import { useAtomCommand } from "../../state/use-atom-command";
 import { formatRelativeTime } from "../../timestampFormat";
 import { Button } from "../ui/button";
 import { ScrollArea } from "../ui/scroll-area";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { toastManager } from "../ui/toast";
 import {
@@ -378,21 +379,21 @@ function HistoryWindowSelector({
   onSelect: (windowMs: number) => void;
 }) {
   return (
-    <div className="flex items-center rounded-md border border-border/60 p-0.5">
+    <ToggleGroup
+      aria-label="Resource history period"
+      variant="segmented"
+      value={[String(selectedWindowMs)]}
+      onValueChange={(next) => {
+        const selected = HISTORY_WINDOWS.find((option) => String(option.windowMs) === next[0]);
+        if (selected) onSelect(selected.windowMs);
+      }}
+    >
       {HISTORY_WINDOWS.map((option) => (
-        <button
-          key={option.windowMs}
-          type="button"
-          className={cn(
-            "cursor-pointer h-6 rounded-sm px-2 text-[11px] font-medium text-muted-foreground hover:text-foreground",
-            selectedWindowMs === option.windowMs && "bg-muted text-foreground",
-          )}
-          onClick={() => onSelect(option.windowMs)}
-        >
+        <Toggle key={option.windowMs} value={String(option.windowMs)}>
           {option.label}
-        </button>
+        </Toggle>
       ))}
-    </div>
+    </ToggleGroup>
   );
 }
 
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index 6dd9310d9eaa..e79464d1757c 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -564,7 +564,7 @@ export function useSettingsRestore(onRestored?: () => void) {
         : []),
       ...(settings.continueThreadsAfterServerUpdate !==
       DEFAULT_UNIFIED_SETTINGS.continueThreadsAfterServerUpdate
-        ? ["Continue threads after server updates"]
+        ? ["Continue threads after restarts"]
         : []),
       ...(isBackgroundActivityDirty ? ["Background activity"] : []),
       ...(settings.defaultThreadEnvMode !== DEFAULT_UNIFIED_SETTINGS.defaultThreadEnvMode
@@ -2308,7 +2308,7 @@ export function GeneralSettingsPanel() {
 
         <SettingsRow
           {...searchableSetting("proactive-panels")}
-          description="Open linked pull requests when found and turn diffs when work finishes."
+          description="Open linked pull requests when found and turn diffs when work changes files."
           resetAction={
             settings.proactivePanelsEnabled !== DEFAULT_UNIFIED_SETTINGS.proactivePanelsEnabled ? (
               <SettingResetButton
@@ -2438,12 +2438,13 @@ export function GeneralSettingsPanel() {
 
         <SettingsRow
           {...searchableSetting("continue-threads-after-server-update")}
-          description="Automatically resume active threads after a server update restarts the environment."
+          serverScoped
+          description="Automatically resume interrupted threads after an update, crash, or machine restart. Applies to this environment and all connected environments that support it. Update older servers first."
           resetAction={
             settings.continueThreadsAfterServerUpdate !==
             DEFAULT_UNIFIED_SETTINGS.continueThreadsAfterServerUpdate ? (
               <SettingResetButton
-                label="continue threads after server updates"
+                label="continue threads after restarts"
                 onClick={() =>
                   updateSettings({
                     continueThreadsAfterServerUpdate:
@@ -2459,7 +2460,7 @@ export function GeneralSettingsPanel() {
               onCheckedChange={(checked) =>
                 updateSettings({ continueThreadsAfterServerUpdate: Boolean(checked) })
               }
-              aria-label="Continue threads after server updates"
+              aria-label="Continue threads after restarts"
             />
           }
         />
@@ -2600,37 +2601,35 @@ export function GeneralSettingsPanel() {
           }
         />
 
-        {settings.defaultThreadEnvMode === "worktree" ? (
-          <SettingsRow
-            serverScoped
-            className="bg-muted/20 sm:pl-9"
-            title={searchableSetting("start-from-origin").title}
-            description="Creates the worktree from the latest matching branch on origin instead of your local branch."
-            resetAction={
-              settings.newWorktreesStartFromOrigin !==
-              DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin ? (
-                <SettingResetButton
-                  label="new worktrees start from origin"
-                  onClick={() =>
-                    updateSettings({
-                      newWorktreesStartFromOrigin:
-                        DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin,
-                    })
-                  }
-                />
-              ) : null
-            }
-            control={
-              <Switch
-                checked={settings.newWorktreesStartFromOrigin}
-                onCheckedChange={(checked) =>
-                  updateSettings({ newWorktreesStartFromOrigin: Boolean(checked) })
+        <SettingsRow
+          serverScoped
+          className="bg-muted/20 sm:pl-9"
+          title={searchableSetting("start-from-origin").title}
+          description="Creates the worktree from the latest matching branch on origin instead of your local branch."
+          resetAction={
+            settings.newWorktreesStartFromOrigin !==
+            DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin ? (
+              <SettingResetButton
+                label="new worktrees start from origin"
+                onClick={() =>
+                  updateSettings({
+                    newWorktreesStartFromOrigin:
+                      DEFAULT_UNIFIED_SETTINGS.newWorktreesStartFromOrigin,
+                  })
                 }
-                aria-label="Start new worktrees from origin by default"
               />
-            }
-          />
-        ) : null}
+            ) : null
+          }
+          control={
+            <Switch
+              checked={settings.newWorktreesStartFromOrigin}
+              onCheckedChange={(checked) =>
+                updateSettings({ newWorktreesStartFromOrigin: Boolean(checked) })
+              }
+              aria-label="Start new worktrees from origin by default"
+            />
+          }
+        />
         <SettingsRow
           serverScoped
           {...searchableSetting("add-project-starts-in")}
@@ -2744,7 +2743,7 @@ export function GeneralSettingsPanel() {
         {isElectron ? (
           <SettingsRow
             {...searchableSetting("quit-confirmation")}
-            description="Choose whether the desktop app quits immediately, after a hold, or after two quick presses."
+            description="Hold mode also quits on two quick presses."
             resetAction={
               settings.confirmQuit !== DEFAULT_UNIFIED_SETTINGS.confirmQuit ? (
                 <SettingResetButton
diff --git a/apps/web/src/components/settings/SettingsSidebarNav.tsx b/apps/web/src/components/settings/SettingsSidebarNav.tsx
index 2716569c571c..f8f0254cda61 100644
--- a/apps/web/src/components/settings/SettingsSidebarNav.tsx
+++ b/apps/web/src/components/settings/SettingsSidebarNav.tsx
@@ -8,6 +8,7 @@ import {
   useState,
   type ComponentType,
   type KeyboardEvent,
+  type ReactNode,
 } from "react";
 import {
   ArchiveIcon,
@@ -21,11 +22,13 @@ import {
   Settings2Icon,
   XIcon,
 } from "lucide-react";
-import { useLocation, useNavigate } from "@tanstack/react-router";
+import { useLocation, useNavigate, useRouterState } from "@tanstack/react-router";
 
 import { Button } from "../ui/button";
+import { Collapsible, CollapsiblePanel } from "../ui/collapsible";
 import { Input } from "../ui/input";
 import { Kbd } from "../ui/kbd";
+import { cn } from "../../lib/utils";
 import {
   SidebarContent,
   SidebarFooter,
@@ -40,6 +43,11 @@ import {
 } from "../ui/sidebar";
 import { SidebarUtilityMenu } from "../sidebar/SidebarChrome";
 import { scrollToSettingsTarget } from "./settingsLayout";
+import {
+  getVisibleSettingsSectionIds,
+  observeSettingsSectionVisibility,
+  type SettingsSectionVisibilityState,
+} from "./settingsSectionVisibility";
 import {
   searchSettings,
   SETTINGS_SECTION_LABELS,
@@ -97,6 +105,7 @@ const SETTINGS_PAGE_SECTIONS: Partial<
   "/settings/appearance": [
     { label: "Colors & themes", targetId: "appearance" },
     { label: "Interface", targetId: "appearance-interface" },
+    { label: "Motion", targetId: "motion" },
     { label: "Typography", targetId: "typography" },
   ],
   "/settings/source-control": [
@@ -114,17 +123,69 @@ function SettingsSectionIcon({ to }: { to: SettingsPath }) {
   return <Icon className="mt-0.5 size-3.5 shrink-0 text-sidebar-muted-foreground/60" />;
 }
 
+function SettingsSubmenuCollapse({
+  open,
+  children,
+}: {
+  readonly open: boolean;
+  readonly children: ReactNode;
+}) {
+  return (
+    <Collapsible open={open}>
+      <CollapsiblePanel className="duration-150 ease-out motion-reduce:transition-none">
+        {children}
+      </CollapsiblePanel>
+    </Collapsible>
+  );
+}
+
 export function SettingsSidebarNav({ pathname }: { pathname: string }) {
   const navigate = useNavigate();
   const currentHash = useLocation({ select: (location) => location.hash });
+  const resolvedPathname = useRouterState({
+    select: (state) => state.resolvedLocation?.pathname,
+  });
   const { isMobile, setOpenMobile, open, setOpen } = useSidebar();
   const searchInputRef = useRef<HTMLInputElement>(null);
   const [query, setQuery] = useState("");
   const [activeResultIndex, setActiveResultIndex] = useState(0);
+  const [sectionVisibility, setSectionVisibility] = useState<SettingsSectionVisibilityState | null>(
+    null,
+  );
   const searchableItems = useAvailableSettingsSearchItems();
   const results = useMemo(() => searchSettings(query, searchableItems), [query, searchableItems]);
   const isSearching = query.trim().length > 0;
   const hasResults = results.length > 0;
+  const activeSettingsPath = SETTINGS_NAV_ITEMS.find(
+    (item) => pathname === item.to || pathname.startsWith(`${item.to}/`),
+  )?.to;
+  const observedVisibilityScope = useMemo(() => {
+    const path = SETTINGS_NAV_ITEMS.find(
+      (item) =>
+        resolvedPathname === item.to || resolvedPathname?.startsWith(`${item.to}/`) === true,
+    )?.to;
+    const pageSections = path ? SETTINGS_PAGE_SECTIONS[path] : undefined;
+    return path && pageSections ? { path, pageSections } : null;
+  }, [resolvedPathname]);
+  const visiblePageSectionIds = getVisibleSettingsSectionIds({
+    activePath: activeSettingsPath,
+    scope: observedVisibilityScope,
+    visibility: sectionVisibility,
+  });
+
+  useEffect(() => {
+    if (!observedVisibilityScope) return;
+    const container = document.querySelector<HTMLElement>("[data-settings-page-layout]");
+    if (!container) return;
+
+    return observeSettingsSectionVisibility({
+      container,
+      targetIds: observedVisibilityScope.pageSections.map((section) => section.targetId),
+      onChange(targetIds) {
+        setSectionVisibility({ scope: observedVisibilityScope, targetIds: new Set(targetIds) });
+      },
+    });
+  }, [observedVisibilityScope]);
 
   useEffect(() => {
     setActiveResultIndex((index) => Math.min(index, Math.max(results.length - 1, 0)));
@@ -347,8 +408,8 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
             <SidebarMenu className="ps-px">
               {SETTINGS_NAV_ITEMS.map((item) => {
                 const Icon = item.icon;
-                const isActive = pathname === item.to || pathname.startsWith(`${item.to}/`);
                 const pageSections = SETTINGS_PAGE_SECTIONS[item.to];
+                const isActive = activeSettingsPath === item.to;
                 return (
                   <SidebarMenuItem key={item.to}>
                     <SidebarMenuButton
@@ -358,21 +419,28 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
                       <Icon />
                       <span className="truncate">{item.label}</span>
                     </SidebarMenuButton>
-                    {isActive && pageSections ? (
-                      <SidebarMenuSub className="border-l-0">
-                        {pageSections.map((section) => (
-                          <SidebarMenuSubItem key={section.targetId}>
-                            <SidebarMenuSubButton
-                              render={<button type="button" />}
-                              size="sm"
-                              className="w-full text-sidebar-muted-foreground/65"
-                              onClick={() => handlePageSectionClick(item.to, section.targetId)}
-                            >
-                              <span className="ms-0.5">{section.label}</span>
-                            </SidebarMenuSubButton>
-                          </SidebarMenuSubItem>
-                        ))}
-                      </SidebarMenuSub>
+                    {pageSections ? (
+                      <SettingsSubmenuCollapse open={isActive}>
+                        <SidebarMenuSub className="border-l-0">
+                          {pageSections.map((section) => (
+                            <SidebarMenuSubItem key={section.targetId}>
+                              <SidebarMenuSubButton
+                                render={<button type="button" />}
+                                size="sm"
+                                data-visible={visiblePageSectionIds.has(section.targetId)}
+                                className={cn(
+                                  "w-full text-sidebar-muted-foreground/65",
+                                  visiblePageSectionIds.has(section.targetId) &&
+                                    "font-medium text-sidebar-foreground",
+                                )}
+                                onClick={() => handlePageSectionClick(item.to, section.targetId)}
+                              >
+                                <span className="ms-0.5">{section.label}</span>
+                              </SidebarMenuSubButton>
+                            </SidebarMenuSubItem>
+                          ))}
+                        </SidebarMenuSub>
+                      </SettingsSubmenuCollapse>
                     ) : null}
                   </SidebarMenuItem>
                 );
diff --git a/apps/web/src/components/settings/ThemeEditorHost.test.tsx b/apps/web/src/components/settings/ThemeEditorHost.test.tsx
new file mode 100644
index 000000000000..eaf0c1b06b2c
--- /dev/null
+++ b/apps/web/src/components/settings/ThemeEditorHost.test.tsx
@@ -0,0 +1,191 @@
+import type { ReactElement } from "react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { reactHookHarness as hooks } from "../../test/reactHookHarness";
+import {
+  getThemeDefinition,
+  installCustomTheme,
+  invalidateCustomThemes,
+  parseThemeFile,
+  removeCustomTheme,
+  THEME_FILE_VERSION,
+  themeColorToHex,
+  updateCustomTheme,
+  type ThemeDefinition,
+} from "../../themePalette";
+import type { ThemeEditorSession } from "./themeEditorStore";
+
+const state = vi.hoisted(() => ({
+  session: null as ThemeEditorSession | null,
+  closeThemeEditor: vi.fn(),
+  onStoreChange: vi.fn(),
+  subscriptions: new Set<() => void>(),
+  theme: {
+    theme: "system",
+    themeHalves: null,
+    setTheme: vi.fn(),
+    refreshTheme: vi.fn(),
+  },
+}));
+
+vi.mock("react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react")>();
+  const { reactHookHarness } = await import("../../test/reactHookHarness");
+  return {
+    ...actual,
+    useCallback: reactHookHarness.useCallback,
+    useSyncExternalStore: (
+      subscribe: (listener: () => void) => () => void,
+      getSnapshot: () => unknown,
+    ) => {
+      const subscription = reactHookHarness.useRef<(() => void) | null>(null);
+      if (!subscription.current) {
+        subscription.current = subscribe(() => state.onStoreChange());
+        state.subscriptions.add(subscription.current);
+      }
+      return getSnapshot();
+    },
+  };
+});
+
+vi.mock("react/compiler-runtime", async () => {
+  const { reactHookHarness } = await import("../../test/reactHookHarness");
+  return { c: reactHookHarness.useMemoCache };
+});
+
+vi.mock("../../hooks/useTheme", () => ({ useTheme: () => state.theme }));
+vi.mock("./themeEditorStore", () => ({
+  useThemeEditorStore: (select: (store: typeof state) => unknown) => select(state),
+}));
+vi.mock("../ui/toast", () => ({
+  toastManager: { add: vi.fn() },
+  stackedThreadToast: (value: unknown) => value,
+}));
+
+import { ThemeEditorHost } from "./ThemeEditorHost";
+
+function renderEditor() {
+  hooks.beginRender();
+  const host = ThemeEditorHost() as ReactElement<{
+    children: ReactElement<{
+      editingTheme: ThemeDefinition | null;
+      seedTheme: ThemeDefinition | null;
+    }>;
+  }> | null;
+  return host?.props.children.props ?? null;
+}
+
+describe("ThemeEditorHost", () => {
+  beforeEach(() => {
+    hooks.reset();
+    state.session = null;
+    state.onStoreChange.mockReset();
+    const storage = new Map<string, string>();
+    vi.stubGlobal("window", {
+      localStorage: {
+        getItem: (key: string) => storage.get(key) ?? null,
+        setItem: (key: string, value: string) => storage.set(key, value),
+      },
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    });
+    invalidateCustomThemes();
+  });
+
+  afterEach(() => {
+    for (const unsubscribe of state.subscriptions) unsubscribe();
+    state.subscriptions.clear();
+    vi.unstubAllGlobals();
+    invalidateCustomThemes();
+  });
+
+  it.each(["editingTheme", "seedTheme"] as const)(
+    "reopens the same %s with its saved colors",
+    (field) => {
+      const theme = installCustomTheme(
+        parseThemeFile({
+          version: THEME_FILE_VERSION,
+          id: "saved-colors",
+          name: "Saved colors",
+          appearance: "dark",
+          colors: { accent: "#1f6e4a" },
+        }),
+      );
+      const session = {
+        id: 1,
+        editingThemeId: field === "editingTheme" ? theme.id : null,
+        seedThemeId: field === "seedTheme" ? theme.id : null,
+        seedName: null,
+        initialAppearance: "dark" as const,
+      };
+      state.session = session;
+      expect(themeColorToHex(renderEditor()?.[field]?.colors.accent ?? "")).toBe("#1f6e4a");
+
+      updateCustomTheme({ ...theme, colors: { ...theme.colors, accent: "#7241b8" } });
+      expect(themeColorToHex(getThemeDefinition(theme.id)?.colors.accent ?? "")).toBe("#7241b8");
+      state.session = null;
+      expect(renderEditor()).toBeNull();
+      state.session = { ...session, id: 2 };
+
+      expect(themeColorToHex(renderEditor()?.[field]?.colors.accent ?? "")).toBe("#7241b8");
+    },
+  );
+
+  it.each(["editingTheme", "seedTheme"] as const)(
+    "refreshes an open %s when the library changes",
+    (field) => {
+      const theme = installCustomTheme(
+        parseThemeFile({
+          version: THEME_FILE_VERSION,
+          id: "updated-theme",
+          name: "Updated theme",
+          appearance: "dark",
+          colors: { accent: "#1f6e4a" },
+        }),
+      );
+      state.session = {
+        id: 1,
+        editingThemeId: field === "editingTheme" ? theme.id : null,
+        seedThemeId: field === "seedTheme" ? theme.id : null,
+        seedName: null,
+        initialAppearance: "dark",
+      };
+      let editor = renderEditor();
+      state.onStoreChange.mockImplementation(() => {
+        editor = renderEditor();
+      });
+
+      updateCustomTheme({ ...theme, colors: { ...theme.colors, accent: "#7241b8" } });
+
+      expect(themeColorToHex(editor?.[field]?.colors.accent ?? "")).toBe("#7241b8");
+    },
+  );
+
+  it("does not keep editing a theme removed from the library", () => {
+    const theme = installCustomTheme(
+      parseThemeFile({
+        version: THEME_FILE_VERSION,
+        id: "removed-theme",
+        name: "Removed theme",
+        appearance: "dark",
+        colors: { accent: "#1f6e4a" },
+      }),
+    );
+    state.session = {
+      id: 1,
+      editingThemeId: theme.id,
+      seedThemeId: null,
+      seedName: null,
+      initialAppearance: "dark",
+    };
+    let editor = renderEditor();
+    expect(editor?.editingTheme?.id).toBe(theme.id);
+    state.onStoreChange.mockImplementation(() => {
+      editor = renderEditor();
+    });
+
+    removeCustomTheme(theme.id);
+
+    expect(editor?.editingTheme).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/settings/ThemeEditorHost.tsx b/apps/web/src/components/settings/ThemeEditorHost.tsx
index 7eca6a2de523..1ffc48fef627 100644
--- a/apps/web/src/components/settings/ThemeEditorHost.tsx
+++ b/apps/web/src/components/settings/ThemeEditorHost.tsx
@@ -1,7 +1,12 @@
-import { lazy, Suspense, useCallback } from "react";
+import { lazy, Suspense, useCallback, useSyncExternalStore } from "react";
 
 import { useTheme } from "../../hooks/useTheme";
-import { getThemeDefinition, type ThemeAppearance, type ThemeDefinition } from "../../themePalette";
+import {
+  getThemeDefinition,
+  subscribeToCustomThemes,
+  type ThemeAppearance,
+  type ThemeDefinition,
+} from "../../themePalette";
 import { stackedThreadToast, toastManager } from "../ui/toast";
 import { useThemeEditorStore } from "./themeEditorStore";
 
@@ -12,6 +17,14 @@ const ThemeEditorPanel = lazy(() =>
   import("./ThemeEditorPanel").then((module) => ({ default: module.ThemeEditorPanel })),
 );
 
+function useThemeDefinition(id: string | null | undefined) {
+  return useSyncExternalStore(
+    subscribeToCustomThemes,
+    () => (id ? (getThemeDefinition(id) ?? null) : null),
+    () => null,
+  );
+}
+
 /**
  * Renders the theme editor above the router. The editor paints its draft on
  * the live app, so it has to outlive the settings route: the point is to walk
@@ -21,6 +34,9 @@ export function ThemeEditorHost() {
   const session = useThemeEditorStore((store) => store.session);
   const closeThemeEditor = useThemeEditorStore((store) => store.closeThemeEditor);
   const { theme, setTheme, themeHalves, refreshTheme } = useTheme();
+  // A saved definition can change without its id changing between sessions.
+  const editingTheme = useThemeDefinition(session?.editingThemeId);
+  const seedTheme = useThemeDefinition(session?.seedThemeId);
 
   // The panel reports which path it actually took: a theme removed while its
   // editor is open resolves to null there, so the save becomes a create even
@@ -95,13 +111,6 @@ export function ThemeEditorHost() {
 
   if (!session) return null;
 
-  // Resolve on every render: an edit or import can change the stored
-  // definitions while a session is open.
-  const editingTheme = session.editingThemeId
-    ? (getThemeDefinition(session.editingThemeId) ?? null)
-    : null;
-  const seedTheme = session.seedThemeId ? (getThemeDefinition(session.seedThemeId) ?? null) : null;
-
   return (
     <Suspense fallback={null}>
       <ThemeEditorPanel
diff --git a/apps/web/src/components/settings/ThemeEditorPanel.tsx b/apps/web/src/components/settings/ThemeEditorPanel.tsx
index 4e85bc8806e8..02d1dad458f1 100644
--- a/apps/web/src/components/settings/ThemeEditorPanel.tsx
+++ b/apps/web/src/components/settings/ThemeEditorPanel.tsx
@@ -38,6 +38,7 @@ import { cn } from "../../lib/utils";
 import { Button } from "../ui/button";
 import { Input } from "../ui/input";
 import { Switch } from "../ui/switch";
+import { Toggle, ToggleGroup } from "../ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { getThemeRoleLabel, ThemeColorField } from "./ThemeColorPicker";
 import {
@@ -942,24 +943,17 @@ export function ThemeEditorPanel({
   );
 
   const renderAppearanceButton = (appearance: ThemeAppearance) => {
-    const isActive = activeAppearance === appearance;
     const lockReason = appearanceLockReason(appearance);
     // A locked mode stays hoverable so the tooltip can say why it is off;
     // a real disabled attribute would swallow the pointer events.
     const button = (
-      <Button
+      <Toggle
         aria-disabled={lockReason !== null}
-        aria-pressed={isActive}
-        size="sm"
+        value={appearance}
         className={lockReason !== null ? "opacity-50" : undefined}
-        style={isActive ? { boxShadow: "inset 0 0 0 1px var(--ring)" } : undefined}
-        variant={isActive ? "secondary" : "outline"}
-        onClick={() => {
-          if (lockReason === null) setActiveAppearance(appearance);
-        }}
       >
         {appearance === "light" ? "Light" : "Dark"}
-      </Button>
+      </Toggle>
     );
     if (lockReason === null) return button;
     return (
@@ -973,10 +967,23 @@ export function ThemeEditorPanel({
   const renderAppearanceButtons = () => (
     <div className="grid grid-cols-[minmax(0,1fr)_minmax(0,2fr)] items-center gap-3">
       <span className="text-sm font-medium">Appearance</span>
-      <div aria-label="Theme appearance" className="grid grid-cols-2 gap-2" role="group">
+      <ToggleGroup
+        aria-label="Theme appearance"
+        variant="segmented"
+        value={[activeAppearance]}
+        onValueChange={(next) => {
+          const appearance = next[0];
+          if (
+            (appearance === "light" || appearance === "dark") &&
+            appearanceLockReason(appearance) === null
+          ) {
+            setActiveAppearance(appearance);
+          }
+        }}
+      >
         {renderAppearanceButton("light")}
         {renderAppearanceButton("dark")}
-      </div>
+      </ToggleGroup>
     </div>
   );
 
diff --git a/apps/web/src/components/settings/browserImportWizard.logic.test.ts b/apps/web/src/components/settings/browserImportWizard.logic.test.ts
index 64bd94f635c4..3df4a95d6c33 100644
--- a/apps/web/src/components/settings/browserImportWizard.logic.test.ts
+++ b/apps/web/src/components/settings/browserImportWizard.logic.test.ts
@@ -7,6 +7,7 @@ import {
   initialTargetSelection,
   isRetryableReason,
   formatSkippedDomains,
+  fullDiskAccessRecheckStep,
   outcomeToStep,
   refreshedSourceProfileDirectory,
   refreshedSourceStep,
@@ -51,6 +52,15 @@ describe("initialWizardStep", () => {
     expect(initialWizardStep(source())).toEqual({ step: "configure" });
   });
 
+  it("asks for Full Disk Access before choosing an import target", () => {
+    expect(initialWizardStep(source({ profiles: [], unavailable: "needsFullDiskAccess" }))).toEqual(
+      {
+        step: "fullDiskAccess",
+        resume: "configure",
+      },
+    );
+  });
+
   it("blocks on a reason nothing local can fix", () => {
     expect(initialWizardStep(source({ unavailable: "unsupportedPlatform" }))).toEqual({
       step: "blocked",
@@ -103,6 +113,14 @@ describe("outcomeToStep", () => {
     expect(outcomeToStep({ kind: "blocked", reason: "browserRunning" })).toEqual({ step: "quit" });
   });
 
+  it("routes a Full Disk Access refusal to its own screen", () => {
+    expect(outcomeToStep({ kind: "blocked", reason: "needsFullDiskAccess" })).toEqual({
+      step: "fullDiskAccess",
+      resume: "import",
+      checked: true,
+    });
+  });
+
   it("surfaces every other failure on the blocked screen", () => {
     expect(outcomeToStep({ kind: "blocked", reason: "readFailed" })).toEqual({
       step: "blocked",
@@ -134,6 +152,20 @@ describe("refreshedSourceStep", () => {
   });
 });
 
+describe("fullDiskAccessRecheckStep", () => {
+  it("marks a still-denied access check for visible feedback", () => {
+    expect(fullDiskAccessRecheckStep(source({ unavailable: "needsFullDiskAccess" }))).toEqual({
+      step: "fullDiskAccess",
+      resume: "configure",
+      checked: true,
+    });
+  });
+
+  it("moves on once access reveals the source profiles", () => {
+    expect(fullDiskAccessRecheckStep(source())).toEqual({ step: "configure" });
+  });
+});
+
 describe("refreshedSourceProfileDirectory", () => {
   const refreshed = source({
     profiles: [
diff --git a/apps/web/src/components/settings/browserImportWizard.logic.ts b/apps/web/src/components/settings/browserImportWizard.logic.ts
index 5479e307b13a..3b71345b9d5a 100644
--- a/apps/web/src/components/settings/browserImportWizard.logic.ts
+++ b/apps/web/src/components/settings/browserImportWizard.logic.ts
@@ -58,8 +58,13 @@ export type ImportOutcome =
  */
 export type WizardStep =
   | { readonly step: "quit" }
+  | {
+      readonly step: "fullDiskAccess";
+      readonly resume: "configure" | "import";
+      readonly checked?: boolean;
+    }
   | { readonly step: "configure" }
-  | { readonly step: "checking" }
+  | { readonly step: "checking"; readonly check: "browser" | "fullDiskAccess" }
   | { readonly step: "importing" }
   | {
       readonly step: "done";
@@ -82,6 +87,9 @@ export function canCloseWizard(step: WizardStep): boolean {
  */
 export function initialWizardStep(source: BrowserImportSource): WizardStep {
   if (source.unavailable === "browserRunning") return { step: "quit" };
+  if (source.unavailable === "needsFullDiskAccess") {
+    return { step: "fullDiskAccess", resume: "configure" };
+  }
   if (source.unavailable !== undefined) return { step: "blocked", reason: source.unavailable };
   if (source.profiles.length === 0) return { step: "blocked", reason: "unknownSourceProfile" };
   return { step: "configure" };
@@ -102,6 +110,11 @@ export function outcomeToStep(outcome: ImportOutcome): WizardStep {
   // other failure surfaces on the blocked screen, which offers a retry when
   // one could help.
   if (outcome.reason === "browserRunning") return { step: "quit" };
+  if (outcome.reason === "needsFullDiskAccess") {
+    // The failed import already checked access, so explain that it is still
+    // denied instead of returning to an indistinguishable permission screen.
+    return { step: "fullDiskAccess", resume: "import", checked: true };
+  }
   return { step: "blocked", reason: outcome.reason };
 }
 
@@ -111,6 +124,12 @@ export function refreshedSourceStep(source: BrowserImportSource | undefined): Wi
   return initialWizardStep(source);
 }
 
+/** A denied FDA recheck returns to the permission step with visible feedback. */
+export function fullDiskAccessRecheckStep(source: BrowserImportSource | undefined): WizardStep {
+  const next = refreshedSourceStep(source);
+  return next.step === "fullDiskAccess" ? { ...next, checked: true } : next;
+}
+
 /** Preserve the chosen source profile when a post-quit refresh still lists it. */
 export function refreshedSourceProfileDirectory(
   currentDirectory: string,
diff --git a/apps/web/src/components/settings/customModelEditor.logic.test.ts b/apps/web/src/components/settings/customModelEditor.logic.test.ts
new file mode 100644
index 000000000000..dba4d7af7bbd
--- /dev/null
+++ b/apps/web/src/components/settings/customModelEditor.logic.test.ts
@@ -0,0 +1,259 @@
+import { describe, expect, it } from "vite-plus/test";
+import { ProviderDriverKind, type ModelCapabilities } from "@t3tools/contracts";
+
+import {
+  DESCRIPTOR_PRESETS_BY_KIND,
+  descriptorFromPreset,
+  definitionFromDraft,
+  descriptorsFromCapabilities,
+  draftFromDefinition,
+  validateDraft,
+  type CustomModelDraft,
+} from "./customModelEditor.logic";
+
+const draft = (overrides: Partial<CustomModelDraft>): CustomModelDraft => ({
+  slug: "my-model",
+  name: "",
+  descriptors: [],
+  ...overrides,
+});
+
+describe("customModelEditor.logic", () => {
+  it("round-trips a definition through the draft, marking the current value as default", () => {
+    const definition = definitionFromDraft(
+      draft({
+        name: " My Model ",
+        descriptors: [
+          {
+            key: "a",
+            type: "select",
+            id: "reasoningEffort",
+            label: "Reasoning",
+            choices: [
+              { key: "a1", id: "low", label: "Low", isDefault: false },
+              { key: "a2", id: "high", label: "", isDefault: true },
+            ],
+          },
+          { key: "b", type: "boolean", id: "fastMode", label: "Fast Mode", choices: [] },
+        ],
+      }),
+    );
+
+    expect(definition).toEqual({
+      slug: "my-model",
+      name: "My Model",
+      capabilities: {
+        optionDescriptors: [
+          {
+            id: "reasoningEffort",
+            label: "Reasoning",
+            type: "select",
+            options: [
+              { id: "low", label: "Low" },
+              { id: "high", label: "high", isDefault: true },
+            ],
+            currentValue: "high",
+          },
+          { id: "fastMode", label: "Fast Mode", type: "boolean" },
+        ],
+      },
+    });
+
+    const reopened = draftFromDefinition(definition);
+    expect(reopened.name).toBe("My Model");
+    expect(reopened.descriptors.map((descriptor) => descriptor.id)).toEqual([
+      "reasoningEffort",
+      "fastMode",
+    ]);
+    expect(reopened.descriptors[0]!.choices.map((choice) => choice.isDefault)).toEqual([
+      false,
+      true,
+    ]);
+  });
+
+  it("preserves the current choice when it differs from the built-in default", () => {
+    const descriptors = descriptorsFromCapabilities(
+      {
+        optionDescriptors: [
+          {
+            id: "effort",
+            label: "Reasoning",
+            type: "select",
+            currentValue: "high",
+            options: [
+              { id: "low", label: "Low", isDefault: true },
+              { id: "high", label: "High" },
+            ],
+          },
+        ],
+      },
+      ProviderDriverKind.make("claudeAgent"),
+    );
+    expect(descriptors[0]!.choices.map((choice) => choice.isDefault)).toEqual([false, true]);
+    expect(
+      definitionFromDraft(draft({ descriptors })).capabilities?.optionDescriptors?.[0],
+    ).toMatchObject({ currentValue: "high" });
+  });
+
+  it("drops prompt-injected choices when copying a built-in's descriptors", () => {
+    const [copied] = descriptorsFromCapabilities(
+      {
+        optionDescriptors: [
+          {
+            id: "effort",
+            label: "Reasoning",
+            type: "select",
+            options: [
+              { id: "high", label: "High", isDefault: true },
+              { id: "ultrathink", label: "Ultrathink" },
+            ],
+            promptInjectedValues: ["ultrathink"],
+          },
+        ],
+      },
+      ProviderDriverKind.make("claudeAgent"),
+    );
+    expect(copied!.choices.map((choice) => choice.id)).toEqual(["high"]);
+  });
+
+  it.each([true, false, undefined])(
+    "preserves boolean values through copy and edit: %s",
+    (currentValue) => {
+      const capabilities: ModelCapabilities = {
+        optionDescriptors: [
+          {
+            id: "thinking",
+            label: "Thinking",
+            type: "boolean",
+            ...(currentValue !== undefined ? { currentValue } : {}),
+          },
+        ],
+      };
+      const copied = definitionFromDraft(
+        draft({
+          descriptors: descriptorsFromCapabilities(capabilities, ProviderDriverKind.make("cursor")),
+        }),
+      );
+      expect(copied.capabilities).toEqual(capabilities);
+      const reopened = draftFromDefinition(copied);
+      expect(definitionFromDraft({ ...reopened, name: "Renamed" }).capabilities).toEqual(
+        capabilities,
+      );
+    },
+  );
+
+  it("excludes Claude context choices from presets and copies without changing other providers or authored entries", () => {
+    const capabilities: ModelCapabilities = {
+      optionDescriptors: [
+        {
+          id: "contextWindow",
+          label: "Context",
+          type: "select",
+          options: [{ id: "1m", label: "1M", isDefault: true }],
+        },
+        { id: "thinking", label: "Thinking", type: "boolean", currentValue: true },
+      ],
+    };
+    const claude = ProviderDriverKind.make("claudeAgent");
+    const copied = definitionFromDraft(
+      draft({ descriptors: descriptorsFromCapabilities(capabilities, claude) }),
+    );
+    expect(copied.capabilities?.optionDescriptors).toEqual([capabilities.optionDescriptors![1]]);
+    const presets = definitionFromDraft(
+      draft({
+        descriptors: (DESCRIPTOR_PRESETS_BY_KIND[claude] ?? []).map(descriptorFromPreset),
+      }),
+    );
+    expect(
+      presets.capabilities?.optionDescriptors?.some((option) => option.id === "contextWindow"),
+    ).toBe(false);
+    const cursorCopy = descriptorsFromCapabilities(capabilities, ProviderDriverKind.make("cursor"));
+    expect(cursorCopy.map((option) => option.id)).toEqual(["contextWindow", "thinking"]);
+    const authored = { slug: "custom", name: "Custom", capabilities };
+    expect(
+      definitionFromDraft(draftFromDefinition(authored)).capabilities?.optionDescriptors?.[0],
+    ).toMatchObject(capabilities.optionDescriptors![0]!);
+  });
+
+  it("preserves choice descriptions when copying, renaming, and saving", () => {
+    const capabilities: ModelCapabilities = {
+      optionDescriptors: [
+        {
+          id: "effort",
+          label: "Reasoning",
+          description: "Choose a reasoning level.",
+          type: "select",
+          options: [
+            { id: "high", label: "High", isDefault: true },
+            { id: "ultracode", label: "Ultracode", description: "Uses additional reasoning." },
+          ],
+        },
+      ],
+    };
+    const copied = definitionFromDraft(
+      draft({
+        descriptors: descriptorsFromCapabilities(
+          capabilities,
+          ProviderDriverKind.make("claudeAgent"),
+        ),
+      }),
+    );
+    const reopened = draftFromDefinition(copied);
+    const saved = definitionFromDraft({ ...reopened, name: "Renamed" });
+    expect(saved.capabilities?.optionDescriptors?.[0]).toMatchObject(
+      capabilities.optionDescriptors![0]!,
+    );
+    expect(copied.capabilities?.optionDescriptors?.[0]).toMatchObject(
+      capabilities.optionDescriptors![0]!,
+    );
+  });
+
+  it.each(Object.entries(DESCRIPTOR_PRESETS_BY_KIND))(
+    "offers saveable presets for %s",
+    (_driver, presets) => {
+      expect(
+        validateDraft(draft({ descriptors: (presets ?? []).map(descriptorFromPreset) })),
+      ).toBeNull();
+    },
+  );
+
+  it("collapses a blank name and no options back to a bare definition", () => {
+    expect(definitionFromDraft(draft({ name: "  " }))).toEqual({
+      slug: "my-model",
+      name: "my-model",
+      capabilities: null,
+    });
+    expect(draftFromDefinition({ slug: "x", name: "x", capabilities: null }).name).toBe("");
+  });
+
+  it("rejects duplicate ids, blank ids, and selects without choices", () => {
+    const select = (id: string, choices: Array<{ id: string }>) => ({
+      key: id,
+      type: "select" as const,
+      id,
+      label: "Label",
+      choices: choices.map((choice) => ({
+        key: choice.id,
+        label: "",
+        isDefault: false,
+        ...choice,
+      })),
+    });
+
+    expect(validateDraft(draft({ descriptors: [select("", [{ id: "a" }])] }))).toBe(
+      "Option 1 needs an id.",
+    );
+    expect(
+      validateDraft(
+        draft({ descriptors: [select("effort", [{ id: "a" }]), select("effort", [{ id: "b" }])] }),
+      ),
+    ).toBe('Option 2: id "effort" is used twice.');
+    expect(validateDraft(draft({ descriptors: [select("effort", [])] }))).toBe(
+      "Option 1 needs at least one choice.",
+    );
+    expect(
+      validateDraft(draft({ descriptors: [select("effort", [{ id: "a" }, { id: "a" }])] })),
+    ).toBe('Option 1: choice "a" is used twice.');
+    expect(validateDraft(draft({ descriptors: [select("effort", [{ id: "a" }])] }))).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/settings/customModelEditor.logic.ts b/apps/web/src/components/settings/customModelEditor.logic.ts
new file mode 100644
index 000000000000..0d48057206df
--- /dev/null
+++ b/apps/web/src/components/settings/customModelEditor.logic.ts
@@ -0,0 +1,258 @@
+import {
+  type ModelCapabilities,
+  ProviderDriverKind,
+  type ProviderOptionDescriptor,
+} from "@t3tools/contracts";
+import { type CustomModelDefinition, createModelCapabilities } from "@t3tools/shared/model";
+
+/** Editable mirror of a `ProviderOptionChoice`. `key` is only a React key. */
+export interface EditorChoice {
+  readonly key: string;
+  readonly id: string;
+  readonly label: string;
+  readonly isDefault: boolean;
+  readonly description?: string;
+}
+
+/** Editable mirror of a `ProviderOptionDescriptor`. `key` is only a React key. */
+export interface EditorDescriptor {
+  readonly key: string;
+  readonly type: "select" | "boolean";
+  readonly id: string;
+  readonly label: string;
+  readonly choices: ReadonlyArray<EditorChoice>;
+  readonly currentBooleanValue?: boolean | undefined;
+  readonly description?: string | undefined;
+}
+
+export interface CustomModelDraft {
+  readonly slug: string;
+  readonly name: string;
+  readonly descriptors: ReadonlyArray<EditorDescriptor>;
+}
+
+export interface DescriptorPreset {
+  readonly id: string;
+  readonly label: string;
+  readonly type: "select" | "boolean";
+  readonly choices?: ReadonlyArray<{ id: string; label: string; isDefault?: boolean }>;
+}
+
+const EFFORT_CHOICES = [
+  { id: "low", label: "Low" },
+  { id: "medium", label: "Medium", isDefault: true },
+  { id: "high", label: "High" },
+  { id: "xhigh", label: "Extra High" },
+] as const;
+
+/**
+ * Option ids each adapter actually reads off a turn's model selection, with
+ * the usual choices pre-filled. Anything else the user types is stored
+ * verbatim but will be ignored by the driver.
+ */
+export const DESCRIPTOR_PRESETS_BY_KIND: Partial<
+  Record<ProviderDriverKind, ReadonlyArray<DescriptorPreset>>
+> = {
+  [ProviderDriverKind.make("codex")]: [
+    { id: "reasoningEffort", label: "Reasoning", type: "select", choices: EFFORT_CHOICES },
+    {
+      id: "serviceTier",
+      label: "Speed",
+      type: "select",
+      choices: [
+        { id: "default", label: "Standard", isDefault: true },
+        { id: "fast", label: "Fast" },
+      ],
+    },
+  ],
+  [ProviderDriverKind.make("claudeAgent")]: [
+    {
+      id: "effort",
+      label: "Reasoning",
+      type: "select",
+      choices: [
+        { id: "low", label: "Low" },
+        { id: "medium", label: "Medium" },
+        { id: "high", label: "High", isDefault: true },
+        { id: "xhigh", label: "Extra High" },
+        { id: "max", label: "Max" },
+      ],
+    },
+    { id: "fastMode", label: "Fast Mode", type: "boolean" },
+    { id: "thinking", label: "Thinking", type: "boolean" },
+  ],
+  [ProviderDriverKind.make("cursor")]: [
+    { id: "reasoning", label: "Reasoning", type: "select", choices: EFFORT_CHOICES },
+    { id: "fastMode", label: "Fast Mode", type: "boolean" },
+    { id: "thinking", label: "Thinking", type: "boolean" },
+  ],
+  [ProviderDriverKind.make("grok")]: [
+    { id: "reasoningEffort", label: "Reasoning", type: "select", choices: EFFORT_CHOICES },
+  ],
+  [ProviderDriverKind.make("opencode")]: [
+    { id: "variant", label: "Reasoning", type: "select", choices: EFFORT_CHOICES },
+    {
+      id: "agent",
+      label: "Agent",
+      type: "select",
+      choices: [
+        { id: "build", label: "Build", isDefault: true },
+        { id: "plan", label: "Plan" },
+      ],
+    },
+  ],
+};
+
+let nextKey = 0;
+export function newEditorKey(): string {
+  nextKey += 1;
+  return `k${nextKey}`;
+}
+
+export function choiceFromPreset(choice: {
+  id: string;
+  label: string;
+  isDefault?: boolean;
+}): EditorChoice {
+  return { key: newEditorKey(), id: choice.id, label: choice.label, isDefault: !!choice.isDefault };
+}
+
+export function descriptorFromPreset(preset: DescriptorPreset): EditorDescriptor {
+  return {
+    key: newEditorKey(),
+    type: preset.type,
+    id: preset.id,
+    label: preset.label,
+    choices: (preset.choices ?? []).map(choiceFromPreset),
+  };
+}
+
+export function emptyEditorDescriptor(): EditorDescriptor {
+  return { key: newEditorKey(), type: "select", id: "", label: "", choices: [] };
+}
+
+export function emptyEditorChoice(): EditorChoice {
+  return { key: newEditorKey(), id: "", label: "", isDefault: false };
+}
+
+/**
+ * Prompt-injected choices (Claude's `ultrathink`) are delivered as prompt text
+ * by built-in runtime profiles a custom entry does not have, so they are
+ * dropped rather than stored as a plain option value.
+ */
+export function descriptorToEditor(descriptor: ProviderOptionDescriptor): EditorDescriptor {
+  const promptInjected = new Set(
+    descriptor.type === "select" ? (descriptor.promptInjectedValues ?? []) : [],
+  );
+  const choices =
+    descriptor.type === "select"
+      ? descriptor.options.filter((option) => !promptInjected.has(option.id))
+      : [];
+  const defaultChoice =
+    choices.find((option) => option.id === descriptor.currentValue) ??
+    choices.find((option) => option.isDefault);
+  return {
+    key: newEditorKey(),
+    type: descriptor.type,
+    id: descriptor.id,
+    label: descriptor.label,
+    ...(descriptor.description !== undefined ? { description: descriptor.description } : {}),
+    ...(descriptor.type === "boolean" && descriptor.currentValue !== undefined
+      ? { currentBooleanValue: descriptor.currentValue }
+      : {}),
+    choices: choices.map((option) => ({
+      key: newEditorKey(),
+      id: option.id,
+      label: option.label,
+      ...(option.description !== undefined ? { description: option.description } : {}),
+      isDefault: option === defaultChoice,
+    })),
+  };
+}
+
+export function draftFromDefinition(entry: CustomModelDefinition): CustomModelDraft {
+  return {
+    slug: entry.slug,
+    name: entry.name === entry.slug ? "" : entry.name,
+    descriptors: (entry.capabilities?.optionDescriptors ?? []).map(descriptorToEditor),
+  };
+}
+
+/** Claude context choices require runtime suffix mappings that custom entries do not carry. */
+export function descriptorsFromCapabilities(
+  capabilities: ModelCapabilities | null | undefined,
+  driverKind: ProviderDriverKind | null,
+): EditorDescriptor[] {
+  return (capabilities?.optionDescriptors ?? [])
+    .filter((descriptor) => driverKind !== "claudeAgent" || descriptor.id !== "contextWindow")
+    .map(descriptorToEditor);
+}
+
+/**
+ * Validate the draft before saving. Returns the first problem in reading
+ * order so the message is actionable, or `null` when the draft is sound.
+ */
+export function validateDraft(draft: CustomModelDraft): string | null {
+  const seenIds = new Set<string>();
+  for (const [index, descriptor] of draft.descriptors.entries()) {
+    const position = `Option ${index + 1}`;
+    const id = descriptor.id.trim();
+    if (!id) return `${position} needs an id.`;
+    if (seenIds.has(id)) return `${position}: id "${id}" is used twice.`;
+    seenIds.add(id);
+    if (!descriptor.label.trim()) return `${position} needs a label.`;
+    if (descriptor.type !== "select") continue;
+    if (descriptor.choices.length === 0) return `${position} needs at least one choice.`;
+    const seenChoices = new Set<string>();
+    for (const choice of descriptor.choices) {
+      const choiceId = choice.id.trim();
+      if (!choiceId) return `${position} has a choice without a value.`;
+      if (seenChoices.has(choiceId)) {
+        return `${position}: choice "${choiceId}" is used twice.`;
+      }
+      seenChoices.add(choiceId);
+    }
+  }
+  return null;
+}
+
+/** Convert a validated draft back into a definition. Blank name → slug. */
+export function definitionFromDraft(draft: CustomModelDraft): CustomModelDefinition {
+  const descriptors: ProviderOptionDescriptor[] = draft.descriptors.map((descriptor) => {
+    const id = descriptor.id.trim();
+    const label = descriptor.label.trim();
+    if (descriptor.type === "boolean") {
+      return {
+        id,
+        label,
+        type: "boolean",
+        ...(descriptor.description !== undefined ? { description: descriptor.description } : {}),
+        ...(descriptor.currentBooleanValue !== undefined
+          ? { currentValue: descriptor.currentBooleanValue }
+          : {}),
+      };
+    }
+    const options = descriptor.choices.map((choice) => ({
+      id: choice.id.trim(),
+      label: choice.label.trim() || choice.id.trim(),
+      ...(choice.description !== undefined ? { description: choice.description } : {}),
+      ...(choice.isDefault ? { isDefault: true } : {}),
+    }));
+    const currentValue = options.find((option) => option.isDefault)?.id;
+    return {
+      id,
+      label,
+      type: "select",
+      ...(descriptor.description !== undefined ? { description: descriptor.description } : {}),
+      options,
+      ...(currentValue ? { currentValue } : {}),
+    };
+  });
+  const name = draft.name.trim();
+  return {
+    slug: draft.slug,
+    name: name || draft.slug,
+    capabilities:
+      descriptors.length > 0 ? createModelCapabilities({ optionDescriptors: descriptors }) : null,
+  };
+}
diff --git a/apps/web/src/components/settings/providerSettingsTabs.ts b/apps/web/src/components/settings/providerSettingsTabs.ts
deleted file mode 100644
index 1c4e828bacd9..000000000000
--- a/apps/web/src/components/settings/providerSettingsTabs.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { cn } from "../../lib/utils";
-
-export function providerSettingsTabClassName(selected: boolean): string {
-  return cn(
-    "relative flex h-full shrink-0 cursor-pointer items-center rounded-sm px-3 text-xs font-medium outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
-    selected
-      ? "text-foreground after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-primary"
-      : "text-muted-foreground hover:text-foreground",
-  );
-}
diff --git a/apps/web/src/components/settings/providerStatus.test.ts b/apps/web/src/components/settings/providerStatus.test.ts
new file mode 100644
index 000000000000..46dc7e262512
--- /dev/null
+++ b/apps/web/src/components/settings/providerStatus.test.ts
@@ -0,0 +1,71 @@
+import { ProviderDriverKind, ProviderInstanceId, type ServerProvider } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { getProviderSummary } from "./providerStatus";
+
+const provider: ServerProvider = {
+  instanceId: ProviderInstanceId.make("codex"),
+  driver: ProviderDriverKind.make("codex"),
+  enabled: true,
+  installed: true,
+  version: "1.0.0",
+  status: "ready",
+  auth: { status: "authenticated", label: "ChatGPT" },
+  checkedAt: "2026-08-23T00:00:00.000Z",
+  models: [],
+  slashCommands: [],
+  skills: [],
+};
+
+describe("getProviderSummary", () => {
+  it("reports ready providers with unknown authentication as available", () => {
+    expect(getProviderSummary({ ...provider, auth: { status: "unknown" } })).toEqual({
+      headline: "Available",
+      detail: null,
+    });
+  });
+
+  it("does not hide a provider error behind a previous authenticated state", () => {
+    expect(
+      getProviderSummary({
+        ...provider,
+        status: "error",
+        message: "The provider process failed to start.",
+      }),
+    ).toEqual({
+      headline: "Unavailable",
+      detail: "The provider process failed to start.",
+    });
+  });
+
+  it("does not hide a provider warning behind an authenticated state", () => {
+    expect(
+      getProviderSummary({
+        ...provider,
+        status: "warning",
+        message: "The provider version is unsupported.",
+      }),
+    ).toEqual({
+      headline: "Needs attention",
+      detail: "The provider version is unsupported.",
+    });
+  });
+
+  it("keeps authentication failures actionable when their provider status is error", () => {
+    expect(
+      getProviderSummary({
+        ...provider,
+        status: "error",
+        auth: { status: "unauthenticated" },
+        message: "Run codex login.",
+      }),
+    ).toEqual({
+      headline: "Not authenticated",
+      detail: "Run codex login.",
+    });
+  });
+
+  it("treats a disabled provider status as disabled even before its enabled flag updates", () => {
+    expect(getProviderSummary({ ...provider, status: "disabled" }).headline).toBe("Disabled");
+  });
+});
diff --git a/apps/web/src/components/settings/providerStatus.ts b/apps/web/src/components/settings/providerStatus.ts
index 0f39f643f5ce..90c618f5daa7 100644
--- a/apps/web/src/components/settings/providerStatus.ts
+++ b/apps/web/src/components/settings/providerStatus.ts
@@ -26,7 +26,8 @@ export type ProviderStatusKey = keyof typeof PROVIDER_STATUS_STYLES;
  * 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.
+ * driver this build does not ship. A ready provider without account metadata
+ * remains available and does not imply an authentication failure.
  */
 export function getProviderSummary(provider: ServerProvider | undefined) {
   if (!provider) {
@@ -35,7 +36,7 @@ export function getProviderSummary(provider: ServerProvider | undefined) {
       detail: "Waiting for the server to report installation and authentication details.",
     };
   }
-  if (!provider.enabled) {
+  if (!provider.enabled || provider.status === "disabled") {
     return {
       headline: "Disabled",
       detail:
@@ -48,13 +49,6 @@ export function getProviderSummary(provider: ServerProvider | undefined) {
       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",
@@ -74,9 +68,16 @@ export function getProviderSummary(provider: ServerProvider | undefined) {
       detail: provider.message ?? "The provider failed its startup checks.",
     };
   }
+  if (provider.auth.status === "authenticated") {
+    const authLabel = provider.auth.label ?? provider.auth.type;
+    return {
+      headline: authLabel ? `Authenticated · ${authLabel}` : "Authenticated",
+      detail: provider.message ?? null,
+    };
+  }
   return {
     headline: "Available",
-    detail: provider.message ?? "Installed and ready, but authentication could not be verified.",
+    detail: provider.message ?? null,
   };
 }
 
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index 22e2204d8a27..7358ed8f9a17 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -218,9 +218,11 @@ export const SETTINGS_SEARCH_ITEMS = [
   },
   {
     id: "continue-threads-after-server-update",
-    title: "Continue threads after server updates",
+    title: "Continue threads after restarts",
     to: "/settings/general",
-    searchTerms: ["resume running active work restart desktop update automatically"],
+    searchTerms: [
+      "resume running active interrupted work restart reboot machine crash desktop update automatically",
+    ],
   },
   {
     id: "background-activity",
diff --git a/apps/web/src/components/settings/settingsSectionVisibility.test.ts b/apps/web/src/components/settings/settingsSectionVisibility.test.ts
new file mode 100644
index 000000000000..90656ad7073a
--- /dev/null
+++ b/apps/web/src/components/settings/settingsSectionVisibility.test.ts
@@ -0,0 +1,245 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  getVisibleSettingsSectionIds,
+  observeSettingsSectionVisibility,
+  type SettingsSectionVisibilityEnvironment,
+} from "./settingsSectionVisibility";
+
+type VisibilityEntry = Pick<
+  IntersectionObserverEntry,
+  "intersectionRatio" | "isIntersecting" | "target"
+>;
+
+function createHarness(
+  targetIds: ReadonlyArray<string>,
+  initialRoot: Element | null = { name: "initial-root" } as unknown as Element,
+) {
+  const targets = new Map(
+    targetIds.map((targetId) => [targetId, { targetId } as unknown as Element]),
+  );
+  const observed = new Set<Element>();
+  const unobserve = vi.fn((target: Element) => observed.delete(target));
+  const disconnectIntersections = vi.fn();
+  const disconnectMutations = vi.fn();
+  const intersectionCallbacks: Array<(entries: ReadonlyArray<VisibilityEntry>) => void> = [];
+  const intersectionRoots: Element[] = [];
+  let root = initialRoot;
+  let onMutation = () => {};
+
+  const environment: SettingsSectionVisibilityEnvironment = {
+    findRoot: () => root,
+    findTarget: (_root, targetId) => targets.get(targetId) ?? null,
+    createIntersectionObserver(callback, observedRoot) {
+      intersectionCallbacks.push(callback);
+      intersectionRoots.push(observedRoot);
+      return {
+        observe: (target) => observed.add(target),
+        unobserve,
+        disconnect: disconnectIntersections,
+      };
+    },
+    createMutationObserver(callback) {
+      onMutation = callback;
+      return { disconnect: disconnectMutations };
+    },
+  };
+
+  return {
+    environment,
+    targets,
+    observed,
+    unobserve,
+    disconnectIntersections,
+    disconnectMutations,
+    intersectionCallbacks,
+    intersectionRoots,
+    intersect(entries: ReadonlyArray<VisibilityEntry>) {
+      intersectionCallbacks.at(-1)?.(entries);
+    },
+    mutate() {
+      onMutation();
+    },
+    replaceRoot(nextRoot: Element | null) {
+      root = nextRoot;
+      onMutation();
+    },
+  };
+}
+
+function visibleEntry(
+  target: Element,
+  { isIntersecting = true, intersectionRatio = 1 } = {},
+): VisibilityEntry {
+  return { target, isIntersecting, intersectionRatio };
+}
+
+describe("settings section visibility", () => {
+  it("does not reuse visibility when returning to the same sectioned route", () => {
+    const firstGeneralVisit = { path: "/settings/general" };
+    const firstVisibility = {
+      scope: firstGeneralVisit,
+      targetIds: new Set(["text-generation"]),
+    };
+
+    expect(
+      getVisibleSettingsSectionIds({
+        activePath: "/settings/general",
+        scope: firstGeneralVisit,
+        visibility: firstVisibility,
+      }),
+    ).toEqual(new Set(["text-generation"]));
+    expect(
+      getVisibleSettingsSectionIds({
+        activePath: "/settings/providers",
+        scope: null,
+        visibility: firstVisibility,
+      }),
+    ).toEqual(new Set());
+
+    const secondGeneralVisit = { path: "/settings/general" };
+    expect(
+      getVisibleSettingsSectionIds({
+        activePath: "/settings/general",
+        scope: secondGeneralVisit,
+        visibility: firstVisibility,
+      }),
+    ).toEqual(new Set());
+  });
+
+  it("accumulates visible sections and emits them in sidebar order", () => {
+    const harness = createHarness(["one", "two", "three"]);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["one", "two", "three"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    harness.intersect([visibleEntry(harness.targets.get("two")!)]);
+    harness.intersect([visibleEntry(harness.targets.get("one")!)]);
+
+    expect(emissions).toEqual([[], ["two"], ["one", "two"]]);
+  });
+
+  it("treats zero-ratio and non-intersecting entries as hidden", () => {
+    const harness = createHarness(["one", "two"]);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["one", "two"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    const one = harness.targets.get("one")!;
+    const two = harness.targets.get("two")!;
+    harness.intersect([visibleEntry(one), visibleEntry(two)]);
+    harness.intersect([visibleEntry(one, { intersectionRatio: 0 })]);
+    harness.intersect([visibleEntry(two, { isIntersecting: false })]);
+
+    expect(emissions).toEqual([[], ["one", "two"], ["two"], []]);
+  });
+
+  it("resyncs replaced and removed targets without retaining stale visibility", () => {
+    const harness = createHarness(["dynamic"]);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["dynamic"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    const firstTarget = harness.targets.get("dynamic")!;
+    harness.intersect([visibleEntry(firstTarget)]);
+    const replacementTarget = { targetId: "dynamic-replacement" } as unknown as Element;
+    harness.targets.set("dynamic", replacementTarget);
+    harness.mutate();
+
+    expect(harness.unobserve).toHaveBeenCalledWith(firstTarget);
+    expect(harness.observed.has(replacementTarget)).toBe(true);
+    expect(emissions.at(-1)).toEqual([]);
+
+    harness.intersect([visibleEntry(firstTarget)]);
+    expect(emissions.at(-1)).toEqual([]);
+    harness.intersect([visibleEntry(replacementTarget)]);
+    expect(emissions.at(-1)).toEqual(["dynamic"]);
+
+    harness.targets.delete("dynamic");
+    harness.mutate();
+    expect(harness.unobserve).toHaveBeenCalledWith(replacementTarget);
+    expect(emissions.at(-1)).toEqual([]);
+  });
+
+  it("rebinds when navigation replaces the settings scroll root", () => {
+    const harness = createHarness(["section"]);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["section"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    const firstTarget = harness.targets.get("section")!;
+    harness.intersect([visibleEntry(firstTarget)]);
+    const firstObserverCallback = harness.intersectionCallbacks[0]!;
+    const nextRoot = { name: "next-root" } as unknown as Element;
+    const nextTarget = { targetId: "next-section" } as unknown as Element;
+    harness.targets.set("section", nextTarget);
+    harness.replaceRoot(nextRoot);
+
+    expect(harness.disconnectIntersections).toHaveBeenCalledOnce();
+    expect(harness.intersectionRoots.at(-1)).toBe(nextRoot);
+    expect(harness.observed.has(nextTarget)).toBe(true);
+    expect(emissions.at(-1)).toEqual([]);
+
+    firstObserverCallback([visibleEntry(firstTarget)]);
+    expect(emissions.at(-1)).toEqual([]);
+    harness.intersect([visibleEntry(nextTarget)]);
+    expect(emissions.at(-1)).toEqual(["section"]);
+  });
+
+  it("starts observing when the settings scroll root mounts later", () => {
+    const harness = createHarness(["section"], null);
+    const emissions: ReadonlyArray<string>[] = [];
+    observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["section"],
+      onChange: (visible) => emissions.push(visible),
+      environment: harness.environment,
+    });
+
+    expect(emissions).toEqual([[]]);
+    expect(harness.intersectionRoots).toEqual([]);
+
+    const root = { name: "mounted-root" } as unknown as Element;
+    harness.replaceRoot(root);
+    harness.intersect([visibleEntry(harness.targets.get("section")!)]);
+
+    expect(harness.intersectionRoots).toEqual([root]);
+    expect(emissions.at(-1)).toEqual(["section"]);
+  });
+
+  it("disconnects both observers and ignores callbacks after cleanup", () => {
+    const harness = createHarness(["one"]);
+    const onChange = vi.fn();
+    const cleanup = observeSettingsSectionVisibility({
+      container: {} as Element,
+      targetIds: ["one"],
+      onChange,
+      environment: harness.environment,
+    });
+
+    cleanup();
+    harness.intersect([visibleEntry(harness.targets.get("one")!)]);
+    harness.mutate();
+
+    expect(harness.disconnectIntersections).toHaveBeenCalledOnce();
+    expect(harness.disconnectMutations).toHaveBeenCalledOnce();
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenLastCalledWith([]);
+  });
+});
diff --git a/apps/web/src/components/settings/settingsSectionVisibility.ts b/apps/web/src/components/settings/settingsSectionVisibility.ts
new file mode 100644
index 000000000000..76b1fc943256
--- /dev/null
+++ b/apps/web/src/components/settings/settingsSectionVisibility.ts
@@ -0,0 +1,186 @@
+type VisibilityEntry = Pick<
+  IntersectionObserverEntry,
+  "intersectionRatio" | "isIntersecting" | "target"
+>;
+
+export type SettingsSectionVisibilityScope = {
+  readonly path: string;
+};
+
+export type SettingsSectionVisibilityState = {
+  readonly scope: SettingsSectionVisibilityScope;
+  readonly targetIds: ReadonlySet<string>;
+};
+
+const EMPTY_VISIBLE_SETTINGS_SECTION_IDS: ReadonlySet<string> = new Set();
+
+export function getVisibleSettingsSectionIds({
+  activePath,
+  scope,
+  visibility,
+}: {
+  readonly activePath: string | undefined;
+  readonly scope: SettingsSectionVisibilityScope | null;
+  readonly visibility: SettingsSectionVisibilityState | null;
+}): ReadonlySet<string> {
+  if (!scope || activePath !== scope.path || visibility?.scope !== scope) {
+    return EMPTY_VISIBLE_SETTINGS_SECTION_IDS;
+  }
+  return visibility.targetIds;
+}
+
+type ElementObserver = {
+  observe(target: Element): void;
+  unobserve(target: Element): void;
+  disconnect(): void;
+};
+
+type MutationSubscription = {
+  disconnect(): void;
+};
+
+export type SettingsSectionVisibilityEnvironment = {
+  findRoot(container: Element): Element | null;
+  findTarget(root: Element, targetId: string): Element | null;
+  createIntersectionObserver(
+    onEntries: (entries: ReadonlyArray<VisibilityEntry>) => void,
+    root: Element,
+  ): ElementObserver;
+  createMutationObserver(onMutation: () => void, container: Element): MutationSubscription;
+};
+
+function createBrowserEnvironment(): SettingsSectionVisibilityEnvironment {
+  return {
+    findRoot(container) {
+      return container.querySelector("[data-settings-page-scroll]");
+    },
+    findTarget(root, targetId) {
+      const target = root.ownerDocument.getElementById(targetId);
+      return target && root.contains(target) ? target : null;
+    },
+    createIntersectionObserver(onEntries, scrollRoot) {
+      const observer = new IntersectionObserver(onEntries, {
+        root: scrollRoot,
+        threshold: 0,
+      });
+      return observer;
+    },
+    createMutationObserver(onMutation, container) {
+      const observer = new MutationObserver(onMutation);
+      observer.observe(container, { childList: true, subtree: true });
+      return observer;
+    },
+  };
+}
+
+export function observeSettingsSectionVisibility({
+  container,
+  targetIds,
+  onChange,
+  environment = createBrowserEnvironment(),
+}: {
+  readonly container: Element;
+  readonly targetIds: ReadonlyArray<string>;
+  readonly onChange: (visibleTargetIds: ReadonlyArray<string>) => void;
+  readonly environment?: SettingsSectionVisibilityEnvironment;
+}): () => void {
+  const orderedTargetIds = [...new Set(targetIds)];
+  const targetsById = new Map<string, Element>();
+  const targetIdsByElement = new Map<Element, string>();
+  const visibleTargetIds = new Set<string>();
+  let lastEmission: string | null = null;
+  let stopped = false;
+  let root: Element | null = null;
+  let intersectionObserver: ElementObserver | null = null;
+  let observerGeneration = 0;
+
+  const emit = () => {
+    const visibleInOrder = orderedTargetIds.filter((targetId) => visibleTargetIds.has(targetId));
+    const emissionKey = visibleInOrder.join("\0");
+    if (emissionKey === lastEmission) return;
+    lastEmission = emissionKey;
+    onChange(visibleInOrder);
+  };
+
+  const handleEntries = (entries: ReadonlyArray<VisibilityEntry>, generation: number) => {
+    if (stopped || generation !== observerGeneration) return;
+    let changed = false;
+    for (const entry of entries) {
+      const targetId = targetIdsByElement.get(entry.target);
+      if (!targetId || targetsById.get(targetId) !== entry.target) continue;
+      const visible = entry.isIntersecting && entry.intersectionRatio > 0;
+      if (visible === visibleTargetIds.has(targetId)) continue;
+      changed = true;
+      if (visible) {
+        visibleTargetIds.add(targetId);
+      } else {
+        visibleTargetIds.delete(targetId);
+      }
+    }
+    if (changed) emit();
+  };
+
+  const syncTargets = () => {
+    if (stopped) return;
+    let changed = false;
+    const nextRoot = environment.findRoot(container);
+
+    if (nextRoot !== root) {
+      observerGeneration += 1;
+      intersectionObserver?.disconnect();
+      intersectionObserver = null;
+      root = nextRoot;
+      targetsById.clear();
+      targetIdsByElement.clear();
+      changed = visibleTargetIds.size > 0;
+      visibleTargetIds.clear();
+
+      if (root) {
+        const generation = observerGeneration;
+        intersectionObserver = environment.createIntersectionObserver(
+          (entries) => handleEntries(entries, generation),
+          root,
+        );
+      }
+    }
+
+    if (!root || !intersectionObserver) {
+      if (changed) emit();
+      return;
+    }
+
+    for (const targetId of orderedTargetIds) {
+      const previousTarget = targetsById.get(targetId) ?? null;
+      const nextTarget = environment.findTarget(root, targetId);
+      if (previousTarget === nextTarget) continue;
+
+      if (previousTarget) {
+        intersectionObserver.unobserve(previousTarget);
+        targetsById.delete(targetId);
+        targetIdsByElement.delete(previousTarget);
+        changed = visibleTargetIds.delete(targetId) || changed;
+      }
+      if (nextTarget) {
+        targetsById.set(targetId, nextTarget);
+        targetIdsByElement.set(nextTarget, targetId);
+        intersectionObserver.observe(nextTarget);
+      }
+    }
+
+    if (changed) emit();
+  };
+
+  const mutationObserver = environment.createMutationObserver(syncTargets, container);
+  syncTargets();
+  emit();
+
+  return () => {
+    stopped = true;
+    observerGeneration += 1;
+    intersectionObserver?.disconnect();
+    mutationObserver.disconnect();
+    targetsById.clear();
+    targetIdsByElement.clear();
+    visibleTargetIds.clear();
+  };
+}
diff --git a/apps/web/src/components/ui/menu.tsx b/apps/web/src/components/ui/menu.tsx
index d7892cb228ab..fbdcbc03480a 100644
--- a/apps/web/src/components/ui/menu.tsx
+++ b/apps/web/src/components/ui/menu.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { Menu as MenuPrimitive } from "@base-ui/react/menu";
-import { ChevronRightIcon } from "lucide-react";
+import { CheckIcon, ChevronRightIcon } from "lucide-react";
 import type * as React from "react";
 
 import { cn } from "~/lib/utils";
@@ -177,6 +177,23 @@ function MenuRadioItem({
   );
 }
 
+function MenuRadioItemIndicator({
+  className,
+  children,
+  ...props
+}: MenuPrimitive.RadioItemIndicator.Props) {
+  return (
+    <MenuPrimitive.RadioItemIndicator
+      aria-hidden
+      className={cn("flex shrink-0", className)}
+      data-slot="menu-radio-item-indicator"
+      {...props}
+    >
+      {children ?? <CheckIcon className="size-3.5" />}
+    </MenuPrimitive.RadioItemIndicator>
+  );
+}
+
 function MenuGroupLabel({
   className,
   inset,
@@ -300,6 +317,7 @@ export {
   MenuRadioGroup as DropdownMenuRadioGroup,
   MenuRadioItem,
   MenuRadioItem as DropdownMenuRadioItem,
+  MenuRadioItemIndicator,
   MenuGroupLabel,
   MenuGroupLabel as DropdownMenuLabel,
   MenuSeparator,
diff --git a/apps/web/src/components/ui/preview-card.tsx b/apps/web/src/components/ui/preview-card.tsx
new file mode 100644
index 000000000000..e0e1e67b399f
--- /dev/null
+++ b/apps/web/src/components/ui/preview-card.tsx
@@ -0,0 +1,44 @@
+import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card";
+
+import { cn } from "~/lib/utils";
+
+const PreviewCard = PreviewCardPrimitive.Root;
+
+function PreviewCardTrigger(props: PreviewCardPrimitive.Trigger.Props) {
+  return <PreviewCardPrimitive.Trigger data-slot="preview-card-trigger" {...props} />;
+}
+
+function PreviewCardPopup({
+  className,
+  align = "start",
+  side = "top",
+  sideOffset = 6,
+  ...props
+}: PreviewCardPrimitive.Popup.Props & {
+  align?: PreviewCardPrimitive.Positioner.Props["align"];
+  side?: PreviewCardPrimitive.Positioner.Props["side"];
+  sideOffset?: PreviewCardPrimitive.Positioner.Props["sideOffset"];
+}) {
+  return (
+    <PreviewCardPrimitive.Portal>
+      <PreviewCardPrimitive.Positioner
+        align={align}
+        className="z-[140] max-w-(--available-width)"
+        data-slot="preview-card-positioner"
+        side={side}
+        sideOffset={sideOffset}
+      >
+        <PreviewCardPrimitive.Popup
+          className={cn(
+            "origin-(--transform-origin) rounded-lg border bg-popover text-popover-foreground shadow-lg outline-none transition-[scale,opacity] data-ending-style:scale-98 data-starting-style:scale-98 data-ending-style:opacity-0 data-starting-style:opacity-0",
+            className,
+          )}
+          data-slot="preview-card-popup"
+          {...props}
+        />
+      </PreviewCardPrimitive.Positioner>
+    </PreviewCardPrimitive.Portal>
+  );
+}
+
+export { PreviewCard, PreviewCardPopup, PreviewCardTrigger };
diff --git a/apps/web/src/components/ui/sidebar.test.tsx b/apps/web/src/components/ui/sidebar.test.tsx
index e2d29d607e13..784c5e087963 100644
--- a/apps/web/src/components/ui/sidebar.test.tsx
+++ b/apps/web/src/components/ui/sidebar.test.tsx
@@ -2,7 +2,6 @@ import { renderToStaticMarkup } from "react-dom/server";
 import { describe, expect, it } from "vite-plus/test";
 
 import {
-  SidebarMenuAction,
   SidebarMenuButton,
   SidebarMenuSubButton,
   SidebarProvider,
@@ -89,17 +88,6 @@ describe("sidebar interactive cursors", () => {
     expect(html).not.toContain("cursor-pointer");
   });
 
-  it("uses a pointer cursor for menu actions", () => {
-    const html = renderToStaticMarkup(
-      <SidebarMenuAction aria-label="Create thread">
-        <span>+</span>
-      </SidebarMenuAction>,
-    );
-
-    expect(html).toContain('data-slot="sidebar-menu-action"');
-    expect(html).toContain("cursor-pointer");
-  });
-
   it("uses a pointer cursor for submenu buttons", () => {
     const html = renderToStaticMarkup(
       <SidebarMenuSubButton render={<button type="button" />}>Show more</SidebarMenuSubButton>,
diff --git a/apps/web/src/components/ui/sidebar.tsx b/apps/web/src/components/ui/sidebar.tsx
index 624798e19f54..22cb4808fadd 100644
--- a/apps/web/src/components/ui/sidebar.tsx
+++ b/apps/web/src/components/ui/sidebar.tsx
@@ -800,7 +800,7 @@ function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
 }
 
 const sidebarMenuButtonVariants = cva(
-  "peer/menu-button flex w-full cursor-pointer items-center gap-[var(--sidebar-control-gap)] overflow-hidden text-left outline-hidden ring-ring transition-[width,height,padding] hover:bg-sidebar-row-hover hover:text-sidebar-foreground focus-visible:ring-2 active:bg-sidebar-row-active active:text-sidebar-foreground disabled:pointer-events-none disabled:opacity-50 group-has-data-[sidebar=menu-action]/menu-item:pe-8 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-row-selected data-[active=true]:font-medium data-[active=true]:text-sidebar-foreground data-[state=open]:hover:bg-sidebar-row-hover data-[state=open]:hover:text-sidebar-foreground group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-[var(--sidebar-content-inset)]! [&>span:last-child]:truncate [&>svg:not([class*='size-'])]:size-4 [&>svg]:shrink-0 [&>svg]:text-[var(--sidebar-icon-color)] hover:[&>svg]:text-sidebar-foreground active:[&>svg]:text-sidebar-foreground data-[active=true]:[&>svg]:text-sidebar-foreground",
+  "peer/menu-button flex w-full cursor-pointer items-center gap-[var(--sidebar-control-gap)] overflow-hidden text-left outline-hidden ring-ring transition-[width,height,padding] hover:bg-sidebar-row-hover hover:text-sidebar-foreground focus-visible:ring-2 active:bg-sidebar-row-active active:text-sidebar-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-row-selected data-[active=true]:font-medium data-[active=true]:text-sidebar-foreground data-[state=open]:hover:bg-sidebar-row-hover data-[state=open]:hover:text-sidebar-foreground group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-[var(--sidebar-content-inset)]! [&>span:last-child]:truncate [&>svg:not([class*='size-'])]:size-4 [&>svg]:shrink-0 [&>svg]:text-[var(--sidebar-icon-color)] hover:[&>svg]:text-sidebar-foreground active:[&>svg]:text-sidebar-foreground data-[active=true]:[&>svg]:text-sidebar-foreground",
   {
     defaultVariants: {
       size: "default",
@@ -875,38 +875,6 @@ function SidebarMenuButton({
   );
 }
 
-function SidebarMenuAction({
-  className,
-  showOnHover = false,
-  render,
-  ...props
-}: useRender.ComponentProps<"button"> & {
-  showOnHover?: boolean;
-}) {
-  const defaultProps = {
-    className: cn(
-      "absolute top-1.5 right-1 flex aspect-square w-5 cursor-pointer items-center justify-center rounded-lg p-0 text-sidebar-foreground outline-hidden ring-ring transition-transform hover:bg-sidebar-row-hover hover:text-sidebar-foreground focus-visible:ring-2 peer-hover/menu-button:text-sidebar-foreground [&>svg:not([class*='size-'])]:size-4 [&>svg]:shrink-0",
-      // Increases the hit area of the button on mobile.
-      "after:-inset-2 after:absolute md:after:hidden",
-      "peer-data-[size=sm]/menu-button:top-1",
-      "peer-data-[size=default]/menu-button:top-1.5",
-      "peer-data-[size=lg]/menu-button:top-2.5",
-      "group-data-[collapsible=icon]:hidden",
-      showOnHover &&
-        "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-sidebar-foreground md:opacity-0",
-      className,
-    ),
-    "data-sidebar": "menu-action",
-    "data-slot": "sidebar-menu-action",
-  };
-
-  return useRender({
-    defaultTagName: "button",
-    props: mergeProps<"button">(defaultProps, props),
-    render,
-  });
-}
-
 function SidebarMenuBadge({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
@@ -1029,7 +997,6 @@ export {
   SidebarInput,
   SidebarInset,
   SidebarMenu,
-  SidebarMenuAction,
   SidebarMenuBadge,
   SidebarMenuButton,
   SidebarMenuItem,
diff --git a/apps/web/src/components/ui/switch.tsx b/apps/web/src/components/ui/switch.tsx
index 0d45c88861e1..267b314caa40 100644
--- a/apps/web/src/components/ui/switch.tsx
+++ b/apps/web/src/components/ui/switch.tsx
@@ -12,7 +12,7 @@ function Switch({
   return (
     <SwitchPrimitive.Root
       className={cn(
-        "inline-flex h-[calc(var(--thumb-size)+2px)] w-[calc(var(--thumb-size)*2-2px)] shrink-0 cursor-pointer items-center rounded-full p-px outline-none transition-[background-color,box-shadow] duration-200 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-checked:bg-primary data-unchecked:bg-input data-disabled:cursor-not-allowed data-disabled:opacity-64",
+        "inline-flex h-[calc(var(--thumb-size)+2px)] w-[calc(var(--thumb-size)*2-2px)] shrink-0 cursor-pointer items-center rounded-full p-[2px] outline-none transition-[background-color,box-shadow] duration-200 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-checked:bg-primary data-unchecked:bg-input data-disabled:cursor-not-allowed data-disabled:opacity-64",
         size === "sm"
           ? "[--thumb-size:--spacing(4)] sm:[--thumb-size:--spacing(3.5)]"
           : "[--thumb-size:--spacing(5)] sm:[--thumb-size:--spacing(4)]",
@@ -24,7 +24,7 @@ function Switch({
     >
       <SwitchPrimitive.Thumb
         className={cn(
-          "pointer-events-none block aspect-square h-full origin-left in-[[role=switch]:active,[data-slot=label]:active,[data-slot=field-label]:active]:not-data-disabled:scale-x-110 in-[[role=switch]:active,[data-slot=label]:active,[data-slot=field-label]:active]:rounded-[var(--thumb-size)/calc(var(--thumb-size)*1.1)] rounded-(--thumb-size) bg-background shadow-sm/5 will-change-transform [transition:translate_.15s,border-radius_.15s,scale_.1s_.1s,transform-origin_.15s] data-checked:origin-[var(--thumb-size)_50%] data-checked:translate-x-[calc(var(--thumb-size)-4px)]",
+          "pointer-events-none block size-[calc(var(--thumb-size)-2px)] shrink-0 origin-left in-[[role=switch]:active,[data-slot=label]:active,[data-slot=field-label]:active]:not-data-disabled:scale-x-110 in-[[role=switch]:active,[data-slot=label]:active,[data-slot=field-label]:active]:rounded-[var(--thumb-size)/calc(var(--thumb-size)*1.1)] rounded-(--thumb-size) bg-background shadow-sm/5 will-change-transform [transition:translate_.15s,border-radius_.15s,scale_.1s_.1s,transform-origin_.15s] data-checked:origin-right data-checked:translate-x-[calc(var(--thumb-size)-4px)]",
         )}
         data-slot="switch-thumb"
       />
diff --git a/apps/web/src/components/ui/toggle-group.tsx b/apps/web/src/components/ui/toggle-group.tsx
index ae10fe81611f..23501ec7a96c 100644
--- a/apps/web/src/components/ui/toggle-group.tsx
+++ b/apps/web/src/components/ui/toggle-group.tsx
@@ -16,7 +16,7 @@ const ToggleGroupContext = React.createContext<VariantProps<typeof toggleVariant
 
 function ToggleGroup({
   className,
-  variant = "default",
+  variant = "segmented",
   size = variant === "segmented" ? "segmented" : "default",
   orientation = "horizontal",
   children,
diff --git a/apps/web/src/components/usage/UsageLimits.tsx b/apps/web/src/components/usage/UsageLimits.tsx
index 17eb96076906..efae9181620d 100644
--- a/apps/web/src/components/usage/UsageLimits.tsx
+++ b/apps/web/src/components/usage/UsageLimits.tsx
@@ -426,18 +426,26 @@ function SourceLimits({ source, now }: { readonly source: LimitsSource; readonly
  * Countdowns anchor to render time rather than ticking: a live clock would
  * repaint the page every minute for no decision-changing gain.
  */
-export function UsageLimitsSection() {
+export function UsageLimitsSection({
+  selectedEnvironmentIds,
+}: {
+  readonly selectedEnvironmentIds: ReadonlySet<EnvironmentId> | null;
+}) {
   const presentations = useAtomValue(environmentPresentations.presentationsAtom);
-  const groups = collectLimitsGroups(presentations);
-  const sources = collectLimitSources(presentations);
-  // Refresh the anchor with incoming snapshots, without scheduling clock ticks.
+  const selected =
+    selectedEnvironmentIds === null
+      ? presentations
+      : new Map([...presentations].filter(([id]) => selectedEnvironmentIds.has(id)));
+  const groups = collectLimitsGroups(selected);
+  const sources = collectLimitSources(selected);
+  // Incoming snapshots refresh the countdown anchor, without clock ticks.
   const now = Date.now();
 
   return (
     <div className="flex flex-col gap-8">
       {groups.length === 0 && sources.length === 0 ? (
         <p className="text-sm text-muted-foreground">
-          No provider on a connected environment reports subscription limits.
+          No provider on the selected environments reports subscription limits.
         </p>
       ) : null}
       {sources.map((source) => (
diff --git a/apps/web/src/components/usage/UsagePage.refresh.test.tsx b/apps/web/src/components/usage/UsagePage.refresh.test.tsx
new file mode 100644
index 000000000000..5a5cfd40aadc
--- /dev/null
+++ b/apps/web/src/components/usage/UsagePage.refresh.test.tsx
@@ -0,0 +1,232 @@
+import type { AtomCommandResult } from "@t3tools/client-runtime/state/runtime";
+import { EnvironmentId, USAGE_CONTRACT_VERSION, type UsageSummaryInput } from "@t3tools/contracts";
+import { mergeUsage } from "@t3tools/shared/usageMerge";
+import * as Cause from "effect/Cause";
+import { AsyncResult } from "effect/unstable/reactivity";
+import { act } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import type { EnvironmentUsageStatus } from "../../state/usage";
+
+type RefreshResult = AtomCommandResult<void, string>;
+type RefreshInput = {
+  readonly environmentId: EnvironmentId;
+  readonly input: Record<string, never>;
+};
+interface PresentationFixture {
+  readonly entry: { readonly target: { readonly label: string } };
+  readonly connection: { readonly phase: "connected" | "disconnected" };
+  readonly serverConfig: Record<string, never> | null;
+}
+
+const testState = vi.hoisted(() => ({
+  presentations: new Map<EnvironmentId, PresentationFixture>(),
+  environments: [] as EnvironmentUsageStatus[],
+  useUsage: vi.fn(),
+  refreshProviders: vi.fn<(input: RefreshInput) => Promise<RefreshResult>>(),
+  refreshUsage: vi.fn(),
+  toast: vi.fn(),
+}));
+
+vi.mock("@effect/atom-react", () => ({ useAtomValue: () => testState.presentations }));
+vi.mock("../../env", () => ({ isElectron: false }));
+vi.mock("../../state/presentation", () => ({
+  environmentPresentations: { presentationsAtom: Symbol("presentations") },
+}));
+vi.mock("../../state/server", () => ({
+  serverEnvironment: { refreshProviders: Symbol("refreshProviders") },
+}));
+vi.mock("../../state/use-atom-command", () => ({
+  useAtomCommand: () => testState.refreshProviders,
+}));
+vi.mock("../../state/usage", () => ({ useUsage: testState.useUsage }));
+vi.mock("../ui/toast", () => ({ toastManager: { add: testState.toast } }));
+vi.mock("../ui/button", () => ({ Button: "button" }));
+vi.mock("../ui/menu", () => ({
+  Menu: "menu-root",
+  MenuTrigger: "menu-trigger",
+  MenuPopup: "menu-popup",
+  MenuCheckboxItem: "label",
+  MenuItem: "menu-item",
+  MenuSeparator: "menu-separator",
+}));
+vi.mock("../ui/select", () => ({
+  Select: "select-root",
+  SelectItem: "select-item",
+  SelectPopup: "select-popup",
+  SelectTrigger: "select-trigger",
+  SelectValue: "select-value",
+}));
+vi.mock("../ui/toggle-group", () => ({ Toggle: "toggle", ToggleGroup: "toggle-group" }));
+vi.mock("../ui/scroll-area", () => ({ ScrollArea: "div" }));
+vi.mock("../ui/sidebar", () => ({ SidebarInset: "div" }));
+vi.mock("../ui/skeleton", () => ({ Skeleton: "div" }));
+vi.mock("../WorkspaceBreadcrumb", () => ({
+  WorkspaceBreadcrumb: "div",
+  WorkspaceBreadcrumbItem: "div",
+  WorkspaceBreadcrumbSeparator: "span",
+}));
+vi.mock("../WorkspacePageContainer", () => ({ WorkspacePageContainer: "main" }));
+vi.mock("../WorkspacePageHeader", () => ({ WorkspacePageHeader: "header" }));
+vi.mock("./UsageLimits", () => ({ UsageLimitsSection: "usage-limits" }));
+vi.mock("./UsageProviderChart", () => ({ UsageProviderChart: "usage-chart" }));
+vi.mock("./UsagePriceOverrides", () => ({ UsagePriceOverrides: () => null }));
+vi.mock("./usageProviders", () => ({
+  PROVIDER_ORDER: [],
+  PROVIDER_PRESENTATION: {},
+  providersWithUsage: () => [],
+}));
+
+import { UsagePage } from "./UsagePage";
+
+let renderer: ReactTestRenderer | null = null;
+
+function seed(...entries: readonly { id: string; connected?: boolean; config?: boolean }[]) {
+  testState.presentations = new Map(
+    entries.map(({ id, connected = true, config = true }) => [
+      EnvironmentId.make(id),
+      {
+        entry: { target: { label: id } },
+        connection: { phase: connected ? "connected" : "disconnected" },
+        serverConfig: config ? {} : null,
+      },
+    ]),
+  );
+  testState.environments = entries.map(({ id }) => ({
+    environmentId: EnvironmentId.make(id),
+    label: id,
+    summary: null,
+    isPending: true,
+    error: null,
+  }));
+}
+
+async function mountLimits() {
+  await act(() => {
+    renderer = create(<UsagePage />);
+  });
+  const metric = renderer!.root.findByProps({
+    "aria-label": "Usage metric",
+    variant: "segmented",
+  });
+  await act(() => metric.props.onValueChange(["limits"]));
+}
+
+async function deselect(label: string) {
+  const item = renderer!.root
+    .findAllByType("label")
+    .find(
+      (candidate) =>
+        candidate.findAll((child) => child.type === "span" && child.children.includes(label))
+          .length > 0,
+    );
+  if (!item) throw new Error(`Missing environment checkbox: ${label}`);
+  await act(() => item.props.onCheckedChange(false));
+}
+
+async function refreshLimits() {
+  const button = renderer!.root.findAllByProps({ "aria-label": "Refresh limits" })[0];
+  if (!button) throw new Error("Missing limits refresh button");
+  await act(async () => button.props.onClick());
+}
+
+beforeEach(() => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  testState.refreshProviders.mockReset().mockResolvedValue(AsyncResult.success(undefined));
+  testState.refreshUsage.mockReset();
+  testState.toast.mockReset();
+  testState.useUsage
+    .mockReset()
+    .mockImplementation(
+      (_input: UsageSummaryInput, selected: ReadonlySet<EnvironmentId> | null) => ({
+        merged: mergeUsage([], USAGE_CONTRACT_VERSION),
+        environments: testState.environments,
+        selectedEnvironments:
+          selected === null
+            ? testState.environments
+            : testState.environments.filter((entry) => selected.has(entry.environmentId)),
+        isPending: true,
+        isPartial: true,
+        refresh: testState.refreshUsage,
+      }),
+    );
+});
+
+afterEach(async () => {
+  await act(() => renderer?.unmount());
+  renderer = null;
+  vi.unstubAllGlobals();
+});
+
+describe("limits refresh across selected environments", () => {
+  it("refreshes selected connected hosts with config and skips the others", async () => {
+    seed(
+      { id: "alpha" },
+      { id: "beta" },
+      { id: "offline", connected: false },
+      { id: "no-config", config: false },
+      { id: "excluded" },
+    );
+    await mountLimits();
+    await deselect("excluded");
+    await refreshLimits();
+
+    expect(testState.refreshProviders.mock.calls.map(([input]) => input)).toEqual([
+      { environmentId: "alpha", input: {} },
+      { environmentId: "beta", input: {} },
+    ]);
+    expect(testState.refreshUsage).not.toHaveBeenCalled();
+    expect(testState.toast).not.toHaveBeenCalled();
+  });
+
+  it("starts every host while another is pending and reports only the failing host", async () => {
+    seed({ id: "slow" }, { id: "failed" }, { id: "healthy" });
+    let finishSlow: (result: RefreshResult) => void = () => {
+      throw new Error("Slow refresh was not started");
+    };
+    const slow = new Promise<RefreshResult>((resolve) => {
+      finishSlow = resolve;
+    });
+    testState.refreshProviders.mockImplementation(({ environmentId }) =>
+      environmentId === "slow"
+        ? slow
+        : Promise.resolve(
+            environmentId === "failed"
+              ? AsyncResult.failure(Cause.fail("host unavailable"))
+              : AsyncResult.success(undefined),
+          ),
+    );
+    await mountLimits();
+    await refreshLimits();
+
+    expect(testState.refreshProviders.mock.calls.map(([input]) => input.environmentId)).toEqual([
+      "slow",
+      "failed",
+      "healthy",
+    ]);
+    expect(testState.toast).toHaveBeenCalledExactlyOnceWith({
+      type: "error",
+      title: "Could not refresh limits for failed",
+    });
+
+    await act(async () => finishSlow(AsyncResult.success(undefined)));
+    expect(testState.toast).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps interrupted refreshes silent while another host succeeds", async () => {
+    seed({ id: "interrupted" }, { id: "healthy" });
+    testState.refreshProviders.mockImplementation(({ environmentId }) =>
+      Promise.resolve(
+        environmentId === "interrupted"
+          ? AsyncResult.failure(Cause.interrupt())
+          : AsyncResult.success(undefined),
+      ),
+    );
+    await mountLimits();
+    await refreshLimits();
+
+    expect(testState.refreshProviders).toHaveBeenCalledTimes(2);
+    expect(testState.toast).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/web/src/components/usage/UsagePage.test.tsx b/apps/web/src/components/usage/UsagePage.test.tsx
index 8e86b521e890..944987388b06 100644
--- a/apps/web/src/components/usage/UsagePage.test.tsx
+++ b/apps/web/src/components/usage/UsagePage.test.tsx
@@ -1,4 +1,4 @@
-import { USAGE_CONTRACT_VERSION } from "@t3tools/contracts";
+import { EnvironmentId, UsageDay, USAGE_CONTRACT_VERSION } from "@t3tools/contracts";
 import { mergeUsage } from "@t3tools/shared/usageMerge";
 import { renderToStaticMarkup } from "react-dom/server";
 import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
@@ -57,6 +57,7 @@ vi.mock("../WorkspaceBreadcrumb", () => ({
 vi.mock("../WorkspacePageContainer", () => ({ WorkspacePageContainer: "main" }));
 vi.mock("../WorkspacePageHeader", () => ({ WorkspacePageHeader: "header" }));
 vi.mock("./UsageProviderChart", () => ({ UsageProviderChart: "div" }));
+vi.mock("./UsagePriceOverrides", () => ({ UsagePriceOverrides: () => null }));
 vi.mock("./usageProviders", async (importOriginal) => {
   const actual = await importOriginal<typeof import("./usageProviders")>();
   return {
@@ -103,6 +104,26 @@ const modelTotals = Object.freeze([
   },
 ]);
 
+const environments = [
+  {
+    environmentId: EnvironmentId.make("test-environment"),
+    label: "Test environment",
+    isPending: false,
+    error: null,
+    summary: {
+      contractVersion: USAGE_CONTRACT_VERSION,
+      readAt: "2026-08-11T12:37:00.000Z",
+      sinceDay: UsageDay.make("2026-08-10"),
+      untilDay: UsageDay.make("2026-08-11"),
+      timeZone: "UTC",
+      buckets: [],
+      sources: [],
+      pricing: { status: "fresh", source: "test", fetchedAt: null, knownModels: 1 },
+      scanDurationMs: 1,
+    },
+  },
+];
+
 beforeEach(() => {
   testState.metric = "cost";
   testState.breakdown = "time";
@@ -127,7 +148,8 @@ beforeEach(() => {
         },
       ],
     },
-    environments: [],
+    environments,
+    selectedEnvironments: environments,
     isPending: false,
     isPartial: false,
     refresh: vi.fn(),
diff --git a/apps/web/src/components/usage/UsagePage.tsx b/apps/web/src/components/usage/UsagePage.tsx
index 9906c76baa8b..d5ccad1f2424 100644
--- a/apps/web/src/components/usage/UsagePage.tsx
+++ b/apps/web/src/components/usage/UsagePage.tsx
@@ -1,13 +1,28 @@
-import type { UsageProviderKind } from "@t3tools/contracts";
 import { isAtomCommandInterrupted } from "@t3tools/client-runtime/state/runtime";
-import { CheckIcon, RefreshCwIcon, XIcon } from "lucide-react";
+import { useAtomValue } from "@effect/atom-react";
+import {
+  USAGE_CONTRACT_VERSION,
+  type EnvironmentId,
+  type UsageProviderKind,
+} from "@t3tools/contracts";
+import {
+  CircleAlertIcon,
+  ChevronDownIcon,
+  CircleDashedIcon,
+  RefreshCwIcon,
+  SlidersHorizontalIcon,
+} from "lucide-react";
 import { useMemo, useState } from "react";
 
-import type { DailyTotals, HourlyTotals } from "@t3tools/shared/usageMerge";
+import {
+  isCompatibleUsageContractVersion,
+  type DailyTotals,
+  type HourlyTotals,
+} from "@t3tools/shared/usageMerge";
 
 import { isElectron } from "../../env";
 import { cn } from "../../lib/utils";
-import { useEnvironments } from "../../state/environments";
+import { environmentPresentations } from "../../state/presentation";
 import { serverEnvironment } from "../../state/server";
 import { useUsage, type EnvironmentUsageStatus } from "../../state/usage";
 import { useAtomCommand } from "../../state/use-atom-command";
@@ -24,6 +39,14 @@ import {
   makeWindow,
 } from "@t3tools/shared/usageFormat";
 import { Button } from "../ui/button";
+import {
+  Menu,
+  MenuCheckboxItem,
+  MenuItem,
+  MenuPopup,
+  MenuSeparator,
+  MenuTrigger,
+} from "../ui/menu";
 import { ScrollArea } from "../ui/scroll-area";
 import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
 import { SidebarInset } from "../ui/sidebar";
@@ -38,6 +61,7 @@ import {
 import { WorkspacePageContainer } from "../WorkspacePageContainer";
 import { WorkspacePageHeader } from "../WorkspacePageHeader";
 import { UsageLimitsSection } from "./UsageLimits";
+import { UsagePriceOverrides } from "./UsagePriceOverrides";
 import { UsageProviderChart, type UsageChartMetric } from "./UsageProviderChart";
 import { PROVIDER_ORDER, PROVIDER_PRESENTATION, providersWithUsage } from "./usageProviders";
 
@@ -67,19 +91,19 @@ export function UsagePage() {
   const [metric, setMetric] = useState<UsageMetric>("cost");
   const showingLimits = metric === "limits";
   const [breakdown, setBreakdown] = useState<"model" | "time">("model");
+  const [selectedEnvironmentIds, setSelectedEnvironmentIds] =
+    useState<ReadonlySet<EnvironmentId> | null>(null);
   const { days: windowDays, window } = windowSelection;
   const isPast24Hours = windowDays === 1;
-  const { merged, environments, isPending, isPartial, refresh } = useUsage(window);
-  const { environments: limitEnvironments } = useEnvironments();
+  const { merged, environments, selectedEnvironments, isPending, isPartial, refresh } = useUsage(
+    window,
+    selectedEnvironmentIds,
+  );
+  const presentations = useAtomValue(environmentPresentations.presentationsAtom);
   const refreshProviders = useAtomCommand(serverEnvironment.refreshProviders, {
     reportFailure: false,
   });
 
-  // Hold the content until every environment is terminal. Rendering merged
-  // totals while devices are still answering makes every number on the page
-  // jump as each one lands.
-  const settling = isPending || isPartial;
-
   const days = useMemo(
     () => enumerateDays(window.sinceDay, window.untilDay),
     [window.sinceDay, window.untilDay],
@@ -116,21 +140,19 @@ export function UsagePage() {
     });
   };
   const refreshWindow = () => {
-    // Limits includes every connected environment; refresh each independently
-    // so one unavailable host does not prevent the others from reporting.
     if (showingLimits) {
-      for (const environment of limitEnvironments) {
-        if (environment.connection.phase !== "connected") continue;
-        void refreshProviders({ environmentId: environment.environmentId, input: {} }).then(
-          (result) => {
+      for (const [environmentId, presentation] of presentations) {
+        if (selectedEnvironmentIds !== null && !selectedEnvironmentIds.has(environmentId)) continue;
+        if (presentation.connection.phase === "connected" && presentation.serverConfig !== null) {
+          void refreshProviders({ environmentId, input: {} }).then((result) => {
             if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
               toastManager.add({
                 type: "error",
-                title: `Could not refresh limits for ${environment.label}`,
+                title: `Could not refresh limits for ${presentation.entry.target.label}`,
               });
             }
-          },
-        );
+          });
+        }
       }
       return;
     }
@@ -151,21 +173,31 @@ export function UsagePage() {
       ? `${formatDateTimeShort(window.sinceTime, window.timeZone)} to ${formatDateTimeShort(window.untilTime, window.timeZone)}`
       : `${formatDayShort(window.sinceDay)} to ${formatDayShort(window.untilDay)}`;
   const topbarContent = (
-    <div className="flex w-full min-w-0 items-center gap-3">
-      <WorkspaceBreadcrumb ariaLabel="Usage breadcrumb" className="min-w-0">
-        <WorkspaceBreadcrumbItem current>
+    <div className="grid w-full min-w-0 grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3 gap-y-2 py-2 xl:flex">
+      <WorkspaceBreadcrumb ariaLabel="Usage breadcrumb" className="col-span-2 min-w-0">
+        <WorkspaceBreadcrumbItem>
           <h1>Usage</h1>
         </WorkspaceBreadcrumbItem>
-        {showingLimits ? null : (
-          <>
-            <WorkspaceBreadcrumbSeparator className="hidden md:flex" />
-            <WorkspaceBreadcrumbItem className="hidden min-w-0 shrink md:flex">
-              <span className="truncate">{windowLabel}</span>
-            </WorkspaceBreadcrumbItem>
-          </>
-        )}
+        <WorkspaceBreadcrumbSeparator />
+        <WorkspaceBreadcrumbItem current className="min-w-10">
+          <UsageEnvironmentFilter
+            environments={environments}
+            selectedEnvironments={selectedEnvironments}
+            selectedEnvironmentIds={selectedEnvironmentIds}
+            onSelectionChange={setSelectedEnvironmentIds}
+            showUsageStatus={!showingLimits}
+            isPartial={isPartial}
+            duplicateSources={merged.duplicateSources}
+            staleEnvironments={merged.staleEnvironments}
+          />
+        </WorkspaceBreadcrumbItem>
       </WorkspaceBreadcrumb>
-      <div className="ms-auto hidden min-w-0 items-center justify-end gap-2 lg:flex">
+      {!showingLimits ? (
+        <span className="hidden min-w-0 truncate text-xs text-muted-foreground 2xl:block">
+          {windowLabel}
+        </span>
+      ) : null}
+      <div className="ms-auto hidden min-w-0 items-center justify-end gap-2 xl:flex">
         <ToggleGroup
           aria-label="Usage metric"
           variant="segmented"
@@ -208,7 +240,7 @@ export function UsagePage() {
           <RefreshCwIcon className="size-3.5" />
         </Button>
       </div>
-      <div className="ms-auto flex min-w-0 items-center justify-end gap-1 lg:hidden">
+      <div className="col-span-2 ms-auto flex min-w-0 items-center justify-end gap-1 xl:hidden">
         <Select
           value={metric}
           onValueChange={(value) => {
@@ -271,25 +303,24 @@ export function UsagePage() {
   return (
     <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground isolate">
       <div className="flex min-h-0 min-w-0 flex-1 flex-col bg-background text-foreground">
-        <WorkspacePageHeader electron={isElectron}>{topbarContent}</WorkspacePageHeader>
+        <WorkspacePageHeader electron={isElectron} className="h-auto">
+          {topbarContent}
+        </WorkspacePageHeader>
 
         <ScrollArea className="min-h-0 flex-1">
           <WorkspacePageContainer width="wide">
-            {showingLimits ? (
-              <UsageLimitsSection />
-            ) : settling ? (
-              <>
-                {environments.length > 1 ? <UsageDeviceStrip environments={environments} /> : null}
-                <UsageSkeleton />
-              </>
+            {selectedEnvironments.length === 0 ? (
+              <p className="text-sm text-muted-foreground">
+                {environments.length === 0
+                  ? `Connect an environment to see ${showingLimits ? "limits" : "usage"}.`
+                  : `Select an environment to see ${showingLimits ? "limits" : "usage"}.`}
+              </p>
+            ) : showingLimits ? (
+              <UsageLimitsSection selectedEnvironmentIds={selectedEnvironmentIds} />
+            ) : isPending ? (
+              <UsageSkeleton />
             ) : (
               <>
-                <UsageCoverageNotice
-                  environments={environments}
-                  duplicateSources={merged.duplicateSources}
-                  staleEnvironments={merged.staleEnvironments}
-                />
-
                 <section className="grid gap-6 lg:grid-cols-[minmax(0,18rem)_minmax(0,1fr)]">
                   <div className="flex min-w-0 flex-col gap-5">
                     <div className="flex flex-col gap-1">
@@ -555,10 +586,8 @@ function Metric({ label, value }: { readonly label: string; readonly value: stri
 }
 
 /**
- * Says plainly when the totals are incomplete: an environment that failed, or
- * one whose transcripts another environment already reported. Environments
- * that are still answering never reach this notice; the page shows the
- * loading skeleton until every one is terminal.
+ * Explains failed or incompatible environments and deduplicated transcripts.
+ * Shown inside the environment filter so arriving results do not move the page.
  */
 function UsageCoverageNotice({
   environments,
@@ -578,7 +607,7 @@ function UsageCoverageNotice({
   }
 
   return (
-    <div className="flex flex-col gap-1 border border-border px-3 py-2 text-xs text-muted-foreground">
+    <div className="flex flex-col gap-1 border-t border-border px-2 py-2 text-xs text-muted-foreground">
       {failed.map((environment) => (
         <span key={environment.label}>{environment.label} could not report usage.</span>
       ))}
@@ -597,66 +626,162 @@ function UsageCoverageNotice({
   );
 }
 
-/**
- * Per-device progress while the page waits for every environment to answer.
- * Only rendered with two or more devices; a lone device has nothing to
- * enumerate.
- */
-function UsageDeviceStrip({
+/** Environment selection and scan progress share a permanent header control. */
+function UsageEnvironmentFilter({
   environments,
+  selectedEnvironments,
+  selectedEnvironmentIds,
+  onSelectionChange,
+  showUsageStatus,
+  isPartial,
+  duplicateSources,
+  staleEnvironments,
 }: {
   readonly environments: readonly EnvironmentUsageStatus[];
+  readonly selectedEnvironments: readonly EnvironmentUsageStatus[];
+  readonly selectedEnvironmentIds: ReadonlySet<EnvironmentId> | null;
+  readonly onSelectionChange: (ids: ReadonlySet<EnvironmentId> | null) => void;
+  readonly showUsageStatus: boolean;
+  readonly isPartial: boolean;
+  readonly duplicateSources: readonly string[];
+  readonly staleEnvironments: readonly string[];
 }) {
-  const scanning = environments.filter(
-    (environment) => environment.summary === null && environment.error === null,
-  );
+  const [modelPricesOpen, setModelPricesOpen] = useState(false);
+  const allSelected = selectedEnvironmentIds === null;
+  const label = allSelected
+    ? "All environments"
+    : selectedEnvironments.length === 1
+      ? selectedEnvironments[0]!.label
+      : `${selectedEnvironments.length} environments`;
+  const pendingCount = selectedEnvironments.filter(
+    (environment) =>
+      environment.error === null && (environment.isPending || environment.summary === null),
+  ).length;
+  const hasIssue =
+    selectedEnvironments.some((environment) => environment.error !== null) ||
+    staleEnvironments.length > 0;
+
   return (
-    <div className="flex flex-wrap items-baseline gap-x-4 gap-y-1 border border-border px-3 py-2 text-xs">
-      {environments.map((environment) => {
-        if (environment.summary !== null) {
-          return (
-            <span
-              key={environment.environmentId}
-              className="flex items-center gap-1 text-foreground"
-            >
-              <CheckIcon className="size-3 text-emerald-600 dark:text-emerald-300/90" aria-hidden />
-              {environment.label}
-            </span>
-          );
-        }
-        if (environment.error !== null) {
-          return (
-            <span
-              key={environment.environmentId}
-              className="flex items-center gap-1 text-destructive"
-            >
-              <XIcon className="size-3" aria-hidden />
-              {environment.label}
-            </span>
-          );
-        }
-        return (
-          <span
-            key={environment.environmentId}
-            className="animate-status-pulse text-muted-foreground"
-          >
-            {environment.label}…
+    <>
+      <Menu>
+        <MenuTrigger className="group/usage-environment inline-flex min-w-0 max-w-full cursor-pointer items-center gap-1 rounded-sm text-left focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring">
+          <span className="min-w-0 truncate">{label}</span>
+          <span className="flex size-3.5 shrink-0 items-center justify-center text-muted-foreground">
+            {showUsageStatus && pendingCount > 0 ? (
+              <>
+                <CircleDashedIcon className="size-3.5" aria-hidden />
+                <span className="sr-only">
+                  {pendingCount} {pendingCount === 1 ? "environment" : "environments"} still
+                  scanning
+                  {isPartial ? "; totals are partial" : ""}
+                </span>
+              </>
+            ) : showUsageStatus && hasIssue ? (
+              <CircleAlertIcon
+                className="size-3.5 text-amber-600 dark:text-amber-400"
+                aria-label="Some environments could not report usage"
+              />
+            ) : (
+              <ChevronDownIcon
+                className="size-3.5 opacity-0 transition-opacity group-hover/usage-environment:opacity-100 group-focus-visible/usage-environment:opacity-100 group-data-popup-open/usage-environment:opacity-100"
+                aria-hidden
+              />
+            )}
           </span>
-        );
-      })}
-      <span className="ms-auto text-muted-foreground">
-        {scanning.length === 1
-          ? "1 device still scanning"
-          : `${scanning.length} devices still scanning`}
-      </span>
-    </div>
+        </MenuTrigger>
+        <MenuPopup align="start" className="w-80 max-w-[calc(100vw-2rem)]">
+          <MenuCheckboxItem
+            checked={allSelected}
+            closeOnClick={false}
+            onCheckedChange={(checked) => onSelectionChange(checked ? null : new Set())}
+          >
+            All environments
+          </MenuCheckboxItem>
+          <MenuSeparator />
+          {environments.map((environment) => {
+            const checked =
+              selectedEnvironmentIds === null ||
+              selectedEnvironmentIds.has(environment.environmentId);
+            const status =
+              environment.error !== null
+                ? "Unavailable"
+                : environment.summary !== null &&
+                    !isCompatibleUsageContractVersion(
+                      environment.summary.contractVersion,
+                      USAGE_CONTRACT_VERSION,
+                    )
+                  ? "Update required"
+                  : environment.summary === null
+                    ? "Scanning…"
+                    : environment.isPending
+                      ? "Refreshing…"
+                      : "Ready";
+            return (
+              <MenuCheckboxItem
+                key={environment.environmentId}
+                checked={checked}
+                closeOnClick={false}
+                className="grid-cols-[1rem_minmax(0,1fr)]"
+                onCheckedChange={(nextChecked) => {
+                  const next = new Set(selectedEnvironments.map((entry) => entry.environmentId));
+                  if (nextChecked) next.add(environment.environmentId);
+                  else next.delete(environment.environmentId);
+                  onSelectionChange(next.size === environments.length ? null : next);
+                }}
+              >
+                <span className="flex min-w-0 items-center gap-3">
+                  <span className="min-w-0 flex-1 truncate">{environment.label}</span>
+                  {showUsageStatus ? (
+                    <span
+                      className={cn(
+                        "shrink-0 text-xs text-muted-foreground",
+                        environment.error !== null && "text-destructive",
+                      )}
+                    >
+                      {status}
+                    </span>
+                  ) : null}
+                </span>
+              </MenuCheckboxItem>
+            );
+          })}
+          {environments.length === 0 ? (
+            <p className="px-2 py-2 text-xs text-muted-foreground">No environments connected.</p>
+          ) : null}
+          {showUsageStatus && isPartial ? (
+            <p className="px-2 py-2 text-xs text-muted-foreground">
+              Totals are partial while selected environments scan.
+            </p>
+          ) : null}
+          {showUsageStatus ? (
+            <UsageCoverageNotice
+              environments={selectedEnvironments}
+              duplicateSources={duplicateSources}
+              staleEnvironments={staleEnvironments}
+            />
+          ) : null}
+          <MenuSeparator />
+          <MenuItem onClick={() => setModelPricesOpen(true)}>
+            <SlidersHorizontalIcon aria-hidden />
+            Model prices
+          </MenuItem>
+        </MenuPopup>
+      </Menu>
+      {modelPricesOpen ? (
+        <UsagePriceOverrides
+          usage={environments}
+          initialSelectedEnvironmentIds={selectedEnvironmentIds}
+          onOpenChange={setModelPricesOpen}
+        />
+      ) : null}
+    </>
   );
 }
 
 /**
  * Stand-in with the loaded page's shape, using the shared `Skeleton` bars so it
  * breathes with the same `animate-skeleton` pulse as every other loading state.
- * Blocks fill in exactly once when the last device answers.
+ * Replaced by results as soon as the first environment answers.
  */
 function UsageSkeleton() {
   return (
diff --git a/apps/web/src/components/usage/UsagePriceOverrides.tsx b/apps/web/src/components/usage/UsagePriceOverrides.tsx
new file mode 100644
index 000000000000..9f3e5697b5ee
--- /dev/null
+++ b/apps/web/src/components/usage/UsagePriceOverrides.tsx
@@ -0,0 +1,554 @@
+import { useAtomValue } from "@effect/atom-react";
+import type { EnvironmentId } from "@t3tools/contracts";
+import { ChevronDownIcon, PlusIcon, RotateCcwIcon, XIcon } from "lucide-react";
+import * as Option from "effect/Option";
+import { AsyncResult, Atom } from "effect/unstable/reactivity";
+import { useRef, useState } from "react";
+
+import { isElectron } from "../../env";
+import { cn } from "../../lib/utils";
+import { environmentPresentations } from "../../state/presentation";
+import { serverEnvironment } from "../../state/server";
+import { environmentSession } from "../../state/session";
+import { useAtomCommand } from "../../state/use-atom-command";
+import type { EnvironmentUsageStatus } from "../../state/usage";
+import {
+  resolvePrimaryOperateAccess,
+  resolveRemoteOperateAccess,
+} from "../settings/ProviderSettingsPanel.logic";
+import { Button } from "../ui/button";
+import {
+  Dialog,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogPanel,
+  DialogPopup,
+  DialogTitle,
+} from "../ui/dialog";
+import { Input } from "../ui/input";
+import { Label } from "../ui/label";
+import { Menu, MenuCheckboxItem, MenuPopup, MenuSeparator, MenuTrigger } from "../ui/menu";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../ui/table";
+import { Tooltip, TooltipTrigger, TooltipPopup } from "../ui/tooltip";
+import { USAGE_PRICE_FIELDS } from "./usagePriceForm";
+import {
+  isEmptyUsagePriceDraft,
+  usagePriceCell,
+  usagePriceTableChanges,
+  usagePriceTableErrors,
+  type UsagePriceDraft,
+  type UsagePriceField,
+} from "./usagePriceTable";
+import {
+  writeUsagePrices,
+  type UsagePriceTarget,
+  type UsagePriceWriteResult,
+} from "./usagePriceTargets";
+
+const priceTargetsAtom = Atom.make((get): readonly UsagePriceTarget[] =>
+  [...get(environmentPresentations.presentationsAtom)].map(([environmentId, environment]) => {
+    const settings = get(serverEnvironment.settingsValueAtom(environmentId));
+    const session = get(environmentSession.sessionStateAtom(environmentId));
+    const sessionAccess = {
+      session: Option.getOrNull(AsyncResult.value(session)),
+      isPending: session.waiting,
+      hasError: session._tag === "Failure",
+    };
+    const isPrimary = environment.entry.target._tag === "PrimaryConnectionTarget";
+    const access = isPrimary
+      ? resolvePrimaryOperateAccess({ ...sessionAccess, isPrimary, hasDesktopBridge: isElectron })
+      : resolveRemoteOperateAccess(sessionAccess);
+    return {
+      environmentId,
+      label: environment.entry.target.label,
+      prices: settings?.usagePriceOverrides ?? null,
+      unavailable:
+        environment.connection.phase !== "connected"
+          ? "Offline"
+          : settings === null
+            ? "Prices not loaded"
+            : environment.serverConfig?.environment.capabilities.usagePriceOverrides !== true
+              ? "Update server to edit prices"
+              : access === "pending"
+                ? "Checking permissions…"
+                : access === "denied"
+                  ? "Read-only access"
+                  : null,
+    };
+  }),
+);
+
+type SaveAttempt = {
+  readonly drafts: readonly UsagePriceDraft[];
+  readonly destinations: readonly {
+    readonly environmentId: EnvironmentId;
+    readonly label: string;
+  }[];
+  readonly results: ReadonlyMap<
+    EnvironmentId,
+    UsagePriceWriteResult | { readonly status: "saving" }
+  >;
+};
+
+export function UsagePriceOverrides({
+  usage,
+  initialSelectedEnvironmentIds,
+  onOpenChange,
+}: {
+  readonly usage: readonly EnvironmentUsageStatus[];
+  readonly initialSelectedEnvironmentIds: ReadonlySet<EnvironmentId> | null;
+  readonly onOpenChange: (open: boolean) => void;
+}) {
+  const environments = useAtomValue(priceTargetsAtom);
+  const [selectedIds, setSelectedIds] = useState(initialSelectedEnvironmentIds);
+  const selected = environments.filter(
+    (environment) => selectedIds === null || selectedIds.has(environment.environmentId),
+  );
+  const [drafts, setDrafts] = useState<readonly UsagePriceDraft[]>([]);
+  const [pending, setPending] = useState(false);
+  const [attempt, setAttempt] = useState<SaveAttempt | null>(null);
+  const focusRowRef = useRef<string | null>(null);
+  const nextRowId = useRef(0);
+  const updateSettings = useAtomCommand(serverEnvironment.updateSettings, { reportFailure: false });
+  const customModels = [
+    ...new Set(selected.flatMap((environment) => Object.keys(environment.prices ?? {}))),
+  ].sort();
+  const models = [
+    ...new Set([
+      ...customModels,
+      ...usage
+        .filter((environment) =>
+          selected.some((target) => target.environmentId === environment.environmentId),
+        )
+        .flatMap((environment) => environment.summary?.buckets.map((bucket) => bucket.model) ?? []),
+    ]),
+  ].sort();
+  // Keep new rows in place while successful environments publish their updated settings.
+  const newModels = new Set(
+    drafts.filter((draft) => draft.isNew).map((draft) => draft.model.trim()),
+  );
+  const rows: readonly UsagePriceDraft[] = [
+    ...customModels
+      .filter((model) => attempt === null || !newModels.has(model))
+      .map(
+        (model) =>
+          drafts.find((draft) => draft.id === `model:${model}`) ?? {
+            id: `model:${model}`,
+            model,
+            isNew: false,
+            values: {},
+          },
+      ),
+    ...drafts.filter((draft) => draft.isNew),
+  ];
+  const stagedDrafts = drafts.filter((draft) => !isEmptyUsagePriceDraft(draft));
+  const errors = usagePriceTableErrors(selected, stagedDrafts);
+  for (const draft of stagedDrafts) {
+    if (!draft.isNew) continue;
+    if (draft.model.trim() === "") errors.set(draft.id, "Enter a model ID.");
+    else if (
+      attempt === null &&
+      (customModels.includes(draft.model.trim()) ||
+        drafts.some((other) => other.id !== draft.id && other.model.trim() === draft.model.trim()))
+    )
+      errors.set(draft.id, "This model already has a row. Edit its prices there.");
+  }
+  const failedDestinations =
+    attempt?.destinations.filter(
+      (destination) => attempt.results.get(destination.environmentId)?.status === "failed",
+    ) ?? [];
+  const locked = pending || failedDestinations.length > 0;
+  const hasChanges = stagedDrafts.length > 0;
+  const destinationLabel =
+    selected.length === 1 ? selected[0]!.label : `${selected.length} environments`;
+  const selectionLabel = selectedIds === null ? "All environments" : destinationLabel;
+  const discard = () => {
+    setDrafts([]);
+    setAttempt(null);
+  };
+  const selectEnvironments = (ids: ReadonlySet<EnvironmentId> | null) => {
+    setSelectedIds(ids);
+    setAttempt(null);
+  };
+  const updateDraft = (draft: UsagePriceDraft) => {
+    setDrafts((previous) =>
+      previous.some((entry) => entry.id === draft.id)
+        ? previous.map((entry) => (entry.id === draft.id ? draft : entry))
+        : [...previous, draft],
+    );
+    setAttempt(null);
+  };
+  const editCell = (row: UsagePriceDraft, field: UsagePriceField, value: string) => {
+    const values = { ...row.values, [field]: value };
+    const original = usagePriceCell(selected, row.model, field);
+    if (
+      !row.isNew &&
+      original.placeholder !== "Mixed" &&
+      original.placeholder !== "Unavailable" &&
+      value === original.value
+    )
+      delete values[field];
+    if (!row.isNew && Object.keys(values).length === 0)
+      setDrafts((previous) => previous.filter((entry) => entry.id !== row.id));
+    else updateDraft({ ...row, values });
+  };
+  const save = async (retry = false) => {
+    if (pending) return;
+    const destinations = retry ? failedDestinations : selected;
+    const edits = retry && attempt ? attempt.drafts : stagedDrafts;
+    if (destinations.length === 0 || edits.length === 0) return;
+    const targets = destinations.map(
+      (destination) =>
+        environments.find(
+          (environment) => environment.environmentId === destination.environmentId,
+        ) ?? { ...destination, prices: null, unavailable: "Environment removed" },
+    );
+    const changes = new Map(
+      targets.map((target) => [target.environmentId, usagePriceTableChanges(target, edits)]),
+    );
+    setPending(true);
+    setAttempt((previous) => ({
+      drafts: edits,
+      destinations: retry && previous ? previous.destinations : targets,
+      results: new Map([
+        ...(retry && previous ? previous.results : []),
+        ...targets.map((target) => [target.environmentId, { status: "saving" } as const] as const),
+      ]),
+    }));
+    let failed = false;
+    await writeUsagePrices({
+      targets: targets.map((target) => ({
+        ...target,
+        unavailable:
+          target.unavailable ?? [...changes.get(target.environmentId)!.errors.values()][0] ?? null,
+      })),
+      changes: new Map([...changes].map(([id, plan]) => [id, plan.changes])),
+      write: updateSettings,
+      onResult: (environmentId, result) => {
+        if (result.status === "failed") failed = true;
+        setAttempt((previous) =>
+          previous === null
+            ? null
+            : { ...previous, results: new Map(previous.results).set(environmentId, result) },
+        );
+      },
+    });
+    setPending(false);
+    if (!failed) setDrafts([]);
+  };
+
+  return (
+    <Dialog
+      open
+      onOpenChange={(open) => {
+        if (!pending) onOpenChange(open);
+      }}
+    >
+      <DialogPopup className="max-w-3xl">
+        <DialogHeader>
+          <DialogTitle>Custom model prices</DialogTitle>
+          <DialogDescription>
+            Prices apply to all past and future usage on the environments you select.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel className="grid gap-4">
+          <div className="flex flex-wrap items-center justify-between gap-2">
+            <div className="flex min-w-0 items-center gap-2">
+              <Label id="usage-prices-apply-label" className="shrink-0">
+                Apply to
+              </Label>
+              <Menu>
+                <MenuTrigger
+                  render={<Button variant="outline" size="sm" className="min-w-0" />}
+                  aria-labelledby="usage-prices-apply-label usage-prices-selection"
+                  disabled={pending || hasChanges}
+                >
+                  <span id="usage-prices-selection" className="truncate">
+                    {selectionLabel}
+                  </span>
+                  <ChevronDownIcon className="size-3.5 shrink-0" aria-hidden />
+                </MenuTrigger>
+                <MenuPopup align="start" className="w-80 max-w-[calc(100vw-2rem)]">
+                  <MenuCheckboxItem
+                    checked={selectedIds === null}
+                    closeOnClick={false}
+                    onCheckedChange={(checked) => selectEnvironments(checked ? null : new Set())}
+                  >
+                    All environments
+                  </MenuCheckboxItem>
+                  <MenuSeparator />
+                  {environments.map((environment) => (
+                    <MenuCheckboxItem
+                      key={environment.environmentId}
+                      checked={selectedIds === null || selectedIds.has(environment.environmentId)}
+                      closeOnClick={false}
+                      onCheckedChange={(checked) => {
+                        const next = new Set(selected.map((target) => target.environmentId));
+                        if (checked) next.add(environment.environmentId);
+                        else next.delete(environment.environmentId);
+                        selectEnvironments(next.size === environments.length ? null : next);
+                      }}
+                    >
+                      <span className="flex min-w-0 items-center gap-3">
+                        <span className="min-w-0 flex-1 truncate">{environment.label}</span>
+                        {environment.unavailable ? (
+                          <span className="text-xs text-muted-foreground">
+                            {environment.unavailable}
+                          </span>
+                        ) : null}
+                      </span>
+                    </MenuCheckboxItem>
+                  ))}
+                </MenuPopup>
+              </Menu>
+            </div>
+            <span className="text-xs text-muted-foreground">USD / million tokens</span>
+          </div>
+          {selected.length === 0 ? (
+            <p className="text-sm text-muted-foreground">
+              {environments.length === 0
+                ? "Connect an environment to set model prices."
+                : "Select an environment to see and change its model prices."}
+            </p>
+          ) : (
+            <>
+              <div className="min-w-0 overflow-hidden rounded-lg border border-border">
+                <Table className="min-w-160 table-fixed" aria-label="Custom model prices">
+                  <colgroup>
+                    <col className="w-[34%]" />
+                    {USAGE_PRICE_FIELDS.map((field) => (
+                      <col key={field.key} />
+                    ))}
+                    <col className="w-10" />
+                  </colgroup>
+                  <TableHeader>
+                    <TableRow className="hover:bg-transparent">
+                      <TableHead className="pl-3">Model ID</TableHead>
+                      {USAGE_PRICE_FIELDS.map((field) => (
+                        <TableHead key={field.key}>{field.label}</TableHead>
+                      ))}
+                      <TableHead className="px-1">
+                        <Button
+                          size="icon-xs"
+                          variant="ghost"
+                          aria-label="Add model price"
+                          disabled={locked}
+                          onClick={() => {
+                            const id = `new:${nextRowId.current++}`;
+                            focusRowRef.current = id;
+                            updateDraft({ id, model: "", isNew: true, values: {} });
+                          }}
+                        >
+                          <PlusIcon aria-hidden />
+                        </Button>
+                      </TableHead>
+                    </TableRow>
+                  </TableHeader>
+                  <TableBody>
+                    {rows.length === 0 ? (
+                      <TableRow className="hover:bg-transparent">
+                        <TableCell
+                          colSpan={6}
+                          className="py-8 text-center whitespace-normal text-muted-foreground"
+                        >
+                          {selected.some((environment) => environment.prices === null)
+                            ? "Some environment prices are unavailable."
+                            : "No custom prices. Add a row to override automatic pricing."}
+                        </TableCell>
+                      </TableRow>
+                    ) : (
+                      rows.map((row) => (
+                        <TableRow
+                          key={row.id}
+                          data-row-id={row.id}
+                          className="hover:bg-transparent"
+                        >
+                          <TableCell className="pl-3 whitespace-normal">
+                            {row.isNew ? (
+                              <Input
+                                size="compact"
+                                value={row.model}
+                                ref={(node) => {
+                                  if (node && focusRowRef.current === row.id) {
+                                    node.focus();
+                                    focusRowRef.current = null;
+                                  }
+                                }}
+                                aria-label="New model ID"
+                                aria-invalid={
+                                  (row.model.trim() !== "" && errors.has(row.id)) || undefined
+                                }
+                                list="usage-price-models"
+                                placeholder="Model ID"
+                                autoComplete="off"
+                                spellCheck={false}
+                                disabled={locked}
+                                onChange={(event) =>
+                                  updateDraft({ ...row, model: event.target.value })
+                                }
+                              />
+                            ) : (
+                              <span
+                                className={cn(
+                                  "block break-all",
+                                  row.removed && "text-muted-foreground line-through",
+                                )}
+                              >
+                                {row.model}
+                              </span>
+                            )}
+                            {errors.has(row.id) &&
+                            (row.model.trim() !== "" ||
+                              Object.values(row.values).some((value) => value !== "")) ? (
+                              <p role="alert" className="mt-1 text-xs text-destructive">
+                                {errors.get(row.id)}
+                              </p>
+                            ) : null}
+                          </TableCell>
+                          {row.removed ? (
+                            <TableCell colSpan={4} className="text-muted-foreground">
+                              Automatic pricing after saving
+                            </TableCell>
+                          ) : (
+                            USAGE_PRICE_FIELDS.map((field) => {
+                              const cell = usagePriceCell(selected, row.model, field.key);
+                              return (
+                                <TableCell key={field.key} className="px-1">
+                                  <Input
+                                    size="compact"
+                                    inputMode="decimal"
+                                    aria-label={`${field.label} price for ${row.model || "new model"}`}
+                                    value={row.values[field.key] ?? (row.isNew ? "" : cell.value)}
+                                    placeholder={
+                                      row.isNew
+                                        ? field.optional
+                                          ? "Input rate"
+                                          : "0.00"
+                                        : cell.placeholder
+                                    }
+                                    autoComplete="off"
+                                    disabled={locked}
+                                    className="tabular-nums"
+                                    onChange={(event) =>
+                                      editCell(row, field.key, event.target.value)
+                                    }
+                                  />
+                                </TableCell>
+                              );
+                            })
+                          )}
+                          <TableCell className="px-1">
+                            <Tooltip>
+                              <TooltipTrigger
+                                render={<Button size="icon-xs" variant="ghost" />}
+                                disabled={locked}
+                                aria-label={
+                                  row.removed
+                                    ? `Undo reset for ${row.model}`
+                                    : row.isNew
+                                      ? "Remove new model"
+                                      : `Reset price for ${row.model} to automatic`
+                                }
+                                onClick={() => {
+                                  if (row.isNew)
+                                    setDrafts((previous) =>
+                                      previous.filter((entry) => entry.id !== row.id),
+                                    );
+                                  else if (row.removed) {
+                                    if (Object.keys(row.values).length === 0)
+                                      setDrafts((previous) =>
+                                        previous.filter((entry) => entry.id !== row.id),
+                                      );
+                                    else updateDraft({ ...row, removed: false });
+                                  } else updateDraft({ ...row, removed: true });
+                                }}
+                              >
+                                {row.isNew ? <XIcon aria-hidden /> : <RotateCcwIcon aria-hidden />}
+                              </TooltipTrigger>
+                              <TooltipPopup>
+                                {row.removed
+                                  ? "Undo reset"
+                                  : row.isNew
+                                    ? "Remove row"
+                                    : "Reset to automatic"}
+                              </TooltipPopup>
+                            </Tooltip>
+                          </TableCell>
+                        </TableRow>
+                      ))
+                    )}
+                  </TableBody>
+                </Table>
+              </div>
+              <datalist id="usage-price-models">
+                {models
+                  .filter((model) => !customModels.includes(model))
+                  .map((model) => (
+                    <option key={model} value={model} />
+                  ))}
+              </datalist>
+              <p className="text-xs text-muted-foreground">
+                Blank cache rates use the input price. Enter 0 for free tokens.
+                {selected.length > 1
+                  ? " Mixed cells keep each environment’s rate until you edit them."
+                  : ""}
+              </p>
+            </>
+          )}
+          {attempt ? (
+            <div role="status" className="grid gap-1 text-xs">
+              {attempt.destinations.map((destination) => {
+                const result = attempt.results.get(destination.environmentId);
+                return (
+                  <div key={destination.environmentId} className="flex justify-between gap-3">
+                    <span className="truncate text-muted-foreground">{destination.label}</span>
+                    <span
+                      className={
+                        result?.status === "failed"
+                          ? "text-right text-destructive"
+                          : "text-muted-foreground"
+                      }
+                    >
+                      {result?.status === "failed"
+                        ? `Not saved · ${result.error}`
+                        : result?.status === "saved"
+                          ? "Saved"
+                          : "Saving…"}
+                    </span>
+                  </div>
+                );
+              })}
+            </div>
+          ) : null}
+        </DialogPanel>
+        <DialogFooter variant="bare" className="items-center sm:justify-between">
+          <span className="text-xs text-muted-foreground">
+            {hasChanges ? `Changes apply to ${destinationLabel}` : ""}
+          </span>
+          <div className="flex w-full flex-wrap justify-end gap-2 sm:w-auto">
+            {hasChanges ? (
+              <Button variant="ghost" disabled={pending} onClick={discard}>
+                {failedDestinations.length > 0 ? "Discard pending changes" : "Discard changes"}
+              </Button>
+            ) : null}
+            <Button
+              disabled={
+                pending ||
+                (!hasChanges && failedDestinations.length === 0) ||
+                (failedDestinations.length === 0 && (errors.size > 0 || selected.length === 0))
+              }
+              onClick={() => void save(failedDestinations.length > 0)}
+            >
+              {pending
+                ? "Saving…"
+                : failedDestinations.length > 0
+                  ? "Retry failed saves"
+                  : "Save changes"}
+            </Button>
+          </div>
+        </DialogFooter>
+      </DialogPopup>
+    </Dialog>
+  );
+}
diff --git a/apps/web/src/components/usage/UsageProviderChart.test.ts b/apps/web/src/components/usage/UsageProviderChart.test.ts
index a4114cfdfb57..622d73d13844 100644
--- a/apps/web/src/components/usage/UsageProviderChart.test.ts
+++ b/apps/web/src/components/usage/UsageProviderChart.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { buildDayColumns, niceScale } from "./UsageProviderChart";
+import { buildPeriodColumns, niceScale } from "./UsageProviderChart";
 import { providersWithUsage } from "./usageProviders";
 
 describe("niceScale", () => {
@@ -41,7 +41,7 @@ describe("niceScale", () => {
   });
 });
 
-describe("buildDayColumns", () => {
+describe("buildPeriodColumns", () => {
   const days = ["2026-08-01", "2026-08-02", "2026-08-03"];
   const byDay = new Map([
     [
@@ -69,11 +69,13 @@ describe("buildDayColumns", () => {
   ]);
 
   it("plots each day on its own", () => {
-    expect(buildDayColumns(days, byDay, "cost").map((column) => column.total)).toEqual([30, 0, 5]);
+    expect(buildPeriodColumns(days, byDay, "cost").map((column) => column.total)).toEqual([
+      30, 0, 5,
+    ]);
   });
 
   it("reads the requested metric", () => {
-    expect(buildDayColumns(days, byDay, "tokens").map((column) => column.total)).toEqual([
+    expect(buildPeriodColumns(days, byDay, "tokens").map((column) => column.total)).toEqual([
       300, 0, 50,
     ]);
   });
@@ -81,7 +83,7 @@ describe("buildDayColumns", () => {
   it("keeps band values absolute rather than cumulative", () => {
     // Regression: the bands were once stack offsets, which drew Claude Code
     // permanently above Codex regardless of which provider spent more.
-    const [first] = buildDayColumns(days, byDay, "cost");
+    const [first] = buildPeriodColumns(days, byDay, "cost");
 
     expect(first?.bands).toEqual([
       { provider: "codex", value: 10 },
@@ -91,7 +93,7 @@ describe("buildDayColumns", () => {
   });
 
   it("reports the total as the sum of its bands", () => {
-    for (const column of buildDayColumns(days, byDay, "cost")) {
+    for (const column of buildPeriodColumns(days, byDay, "cost")) {
       const sum = column.bands.reduce((running, band) => running + band.value, 0);
       expect(column.total).toBeCloseTo(sum, 9);
     }
@@ -125,7 +127,7 @@ describe("hourly chart columns", () => {
     ]);
 
     expect(
-      buildDayColumns(
+      buildPeriodColumns(
         ["2026-08-11T08:37:00.000Z", "2026-08-11T09:37:00.000Z", "2026-08-11T10:37:00.000Z"],
         byHour,
         "cost",
diff --git a/apps/web/src/components/usage/UsageProviderChart.tsx b/apps/web/src/components/usage/UsageProviderChart.tsx
index 26d49e664804..4a66349ddfa5 100644
--- a/apps/web/src/components/usage/UsageProviderChart.tsx
+++ b/apps/web/src/components/usage/UsageProviderChart.tsx
@@ -54,7 +54,7 @@ function valueFor(
   return metric === "tokens" ? entry.totalTokens : entry.costUsd;
 }
 
-function buildPeriodColumns(
+export function buildPeriodColumns(
   periods: readonly string[],
   byPeriod: ReadonlyMap<string, DailyTotals | HourlyTotals>,
   metric: UsageChartMetric,
@@ -169,24 +169,6 @@ export function niceScale(peak: number, count: number): { max: number; ticks: re
   return { max, ticks };
 }
 
-/**
- * Turns the merged daily totals into one column per day.
- *
- * Values are absolute, not cumulative: each provider is drawn from the same
- * zero baseline so the chart never implies that one provider is always larger.
- *
- * The chart paths and the hover readout both consume this, so the number under
- * the cursor is by construction the number that was plotted rather than a
- * second derivation that can drift from it.
- */
-export function buildDayColumns(
-  days: readonly string[],
-  byDay: ReadonlyMap<string, DailyTotals>,
-  metric: UsageChartMetric,
-): readonly DayColumn[] {
-  return buildPeriodColumns(days, byDay, metric);
-}
-
 export function UsageProviderChart({
   providers,
   days,
diff --git a/apps/web/src/components/usage/usagePriceForm.test.ts b/apps/web/src/components/usage/usagePriceForm.test.ts
new file mode 100644
index 000000000000..47c555651412
--- /dev/null
+++ b/apps/web/src/components/usage/usagePriceForm.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { parseUsagePriceForm, usagePriceForm } from "./usagePriceForm.ts";
+
+describe("model price entry", () => {
+  it("preserves exact model IDs and fractional rates", () => {
+    expect(
+      parseUsagePriceForm({
+        ...usagePriceForm(),
+        model: "  vendor/Example-Model  ",
+        inputCostPerMillionTokens: "2.5",
+        outputCostPerMillionTokens: "10",
+      }),
+    ).toEqual({
+      model: "vendor/Example-Model",
+      price: { inputCostPerMillionTokens: 2.5, outputCostPerMillionTokens: 10 },
+    });
+  });
+
+  it("keeps free cache tokens distinct from blank cache prices", () => {
+    const parsed = parseUsagePriceForm({
+      ...usagePriceForm(),
+      model: "example-model",
+      inputCostPerMillionTokens: "2",
+      outputCostPerMillionTokens: "8",
+      cacheReadCostPerMillionTokens: "0",
+      cacheWriteCostPerMillionTokens: " ",
+    });
+    expect(parsed?.price).toEqual({
+      inputCostPerMillionTokens: 2,
+      outputCostPerMillionTokens: 8,
+      cacheReadCostPerMillionTokens: 0,
+    });
+  });
+
+  it("preserves all prices when editing, including small fractional prices", () => {
+    const price = {
+      inputCostPerMillionTokens: 0,
+      outputCostPerMillionTokens: 8,
+      cacheReadCostPerMillionTokens: 0.0000001,
+      cacheWriteCostPerMillionTokens: 3.5,
+    };
+    expect(parseUsagePriceForm(usagePriceForm("example-model", price))).toEqual({
+      model: "example-model",
+      price,
+    });
+  });
+
+  it.each(["", " ", "-1", "Infinity", "NaN", "1e999", "$2", "0x10"])(
+    "rejects invalid required prices: %j",
+    (inputCostPerMillionTokens) => {
+      expect(
+        parseUsagePriceForm({
+          ...usagePriceForm("example-model", {
+            inputCostPerMillionTokens: 2,
+            outputCostPerMillionTokens: 8,
+          }),
+          inputCostPerMillionTokens,
+        }),
+      ).toBeNull();
+    },
+  );
+
+  it("rejects invalid optional rates and missing model IDs", () => {
+    const form = usagePriceForm("example-model", {
+      inputCostPerMillionTokens: 2,
+      outputCostPerMillionTokens: 8,
+    });
+    expect(parseUsagePriceForm({ ...form, cacheReadCostPerMillionTokens: "-1" })).toBeNull();
+    expect(parseUsagePriceForm({ ...form, cacheWriteCostPerMillionTokens: "invalid" })).toBeNull();
+    expect(parseUsagePriceForm({ ...form, model: " " })).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/usage/usagePriceForm.ts b/apps/web/src/components/usage/usagePriceForm.ts
new file mode 100644
index 000000000000..c52178300cdc
--- /dev/null
+++ b/apps/web/src/components/usage/usagePriceForm.ts
@@ -0,0 +1,62 @@
+import type { UsageModelPriceOverride } from "@t3tools/contracts";
+
+export const USAGE_PRICE_FIELDS = [
+  { key: "inputCostPerMillionTokens", label: "Input", optional: false },
+  { key: "outputCostPerMillionTokens", label: "Output", optional: false },
+  { key: "cacheReadCostPerMillionTokens", label: "Cache read", optional: true },
+  { key: "cacheWriteCostPerMillionTokens", label: "Cache write", optional: true },
+] as const;
+
+export type UsagePriceForm = { model: string } & Record<
+  (typeof USAGE_PRICE_FIELDS)[number]["key"],
+  string
+>;
+
+export function usagePriceForm(model = "", price?: UsageModelPriceOverride): UsagePriceForm {
+  return {
+    model,
+    inputCostPerMillionTokens: price?.inputCostPerMillionTokens.toString() ?? "",
+    outputCostPerMillionTokens: price?.outputCostPerMillionTokens.toString() ?? "",
+    cacheReadCostPerMillionTokens: price?.cacheReadCostPerMillionTokens?.toString() ?? "",
+    cacheWriteCostPerMillionTokens: price?.cacheWriteCostPerMillionTokens?.toString() ?? "",
+  };
+}
+
+/** Blank cache prices use the input rate; explicit zero means free. */
+export function parseUsagePriceForm(
+  form: UsagePriceForm,
+): { model: string; price: UsageModelPriceOverride } | null {
+  const model = form.model.trim();
+  if (model.length === 0) return null;
+  const rates: Partial<Record<(typeof USAGE_PRICE_FIELDS)[number]["key"], number>> = {};
+  for (const field of USAGE_PRICE_FIELDS) {
+    const raw = form[field.key].trim();
+    if (raw === "") {
+      if (field.optional) continue;
+      return null;
+    }
+    if (!/^(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(raw)) return null;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0) return null;
+    rates[field.key] = value;
+  }
+  if (
+    rates.inputCostPerMillionTokens === undefined ||
+    rates.outputCostPerMillionTokens === undefined
+  ) {
+    return null;
+  }
+  return {
+    model,
+    price: {
+      inputCostPerMillionTokens: rates.inputCostPerMillionTokens,
+      outputCostPerMillionTokens: rates.outputCostPerMillionTokens,
+      ...(rates.cacheReadCostPerMillionTokens === undefined
+        ? {}
+        : { cacheReadCostPerMillionTokens: rates.cacheReadCostPerMillionTokens }),
+      ...(rates.cacheWriteCostPerMillionTokens === undefined
+        ? {}
+        : { cacheWriteCostPerMillionTokens: rates.cacheWriteCostPerMillionTokens }),
+    },
+  };
+}
diff --git a/apps/web/src/components/usage/usagePriceTable.test.ts b/apps/web/src/components/usage/usagePriceTable.test.ts
new file mode 100644
index 000000000000..57be2cac8a2e
--- /dev/null
+++ b/apps/web/src/components/usage/usagePriceTable.test.ts
@@ -0,0 +1,170 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+import {
+  usagePriceCell,
+  usagePriceTableChanges,
+  usagePriceTableErrors,
+  type UsagePriceDraft,
+} from "./usagePriceTable";
+import type { UsagePriceTarget } from "./usagePriceTargets";
+
+const price = { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 };
+const target = (name: string, prices: UsagePriceTarget["prices"]): UsagePriceTarget => ({
+  environmentId: EnvironmentId.make(name),
+  label: name,
+  prices,
+  unavailable: null,
+});
+const draft = (values: UsagePriceDraft["values"]): UsagePriceDraft => ({
+  id: "model:example",
+  model: "example",
+  isNew: false,
+  values,
+});
+
+describe("price table edits", () => {
+  it("shows shared and mixed cells separately, and never treats missing settings as automatic", () => {
+    const targets = [
+      target("a", { example: price }),
+      target("b", { example: { ...price, outputCostPerMillionTokens: 10 } }),
+    ];
+    expect(usagePriceCell(targets, "example", "inputCostPerMillionTokens").value).toBe("2");
+    expect(usagePriceCell(targets, "example", "outputCostPerMillionTokens")).toEqual({
+      value: "",
+      placeholder: "Mixed",
+    });
+    expect(usagePriceCell(targets, "example", "cacheReadCostPerMillionTokens")).toEqual({
+      value: "",
+      placeholder: "Input rate",
+    });
+    expect(
+      usagePriceCell([target("a", {})], "example", "inputCostPerMillionTokens").placeholder,
+    ).toBe("Automatic");
+    expect(
+      usagePriceCell([targets[0]!, target("b", null)], "example", "inputCostPerMillionTokens")
+        .placeholder,
+    ).toBe("Unavailable");
+  });
+
+  it.each(["constructor", "toString", "__proto__"])(
+    "handles an exact model ID named %s",
+    (model) => {
+      const environment = target("a", {});
+      expect(usagePriceCell([environment], model, "inputCostPerMillionTokens")).toEqual({
+        value: "",
+        placeholder: "Automatic",
+      });
+      const result = usagePriceTableChanges(environment, [
+        {
+          ...draft({ inputCostPerMillionTokens: "2", outputCostPerMillionTokens: "8" }),
+          model,
+          isNew: true,
+        },
+      ]);
+      expect(result.changes).toEqual([{ model, price }]);
+      expect(
+        usagePriceCell([target("a", { [model]: price })], model, "inputCostPerMillionTokens").value,
+      ).toBe("2");
+    },
+  );
+
+  it("changes only edited columns while preserving each environment's other prices and models", () => {
+    const edits = [draft({ inputCostPerMillionTokens: "3" })];
+    const a = usagePriceTableChanges(
+      target("a", { example: { ...price, cacheReadCostPerMillionTokens: 0 }, untouched: price }),
+      edits,
+    );
+    const b = usagePriceTableChanges(
+      target("b", { example: { ...price, outputCostPerMillionTokens: 10 } }),
+      edits,
+    );
+    expect(a.changes).toEqual([
+      {
+        model: "example",
+        price: { ...price, inputCostPerMillionTokens: 3, cacheReadCostPerMillionTokens: 0 },
+      },
+    ]);
+    expect(b.changes).toEqual([
+      { model: "example", price: { inputCostPerMillionTokens: 3, outputCostPerMillionTokens: 10 } },
+    ]);
+  });
+
+  it("batches new rows and resets, and distinguishes blank cache rates from explicit zero", () => {
+    const plan = usagePriceTableChanges(target("a", { example: price }), [
+      { ...draft({}), removed: true },
+      {
+        id: "new:1",
+        model: "  vendor/Model  ",
+        isNew: true,
+        values: {
+          inputCostPerMillionTokens: "2",
+          outputCostPerMillionTokens: "8",
+          cacheReadCostPerMillionTokens: "0",
+          cacheWriteCostPerMillionTokens: "",
+        },
+      },
+    ]);
+    expect(plan.errors.size).toBe(0);
+    expect(plan.changes).toEqual([
+      { model: "example", price: null },
+      { model: "vendor/Model", price: { ...price, cacheReadCostPerMillionTokens: 0 } },
+    ]);
+  });
+
+  it("requires complete prices before turning automatic pricing into an override", () => {
+    const edits = [draft({ inputCostPerMillionTokens: "3" })];
+    expect(usagePriceTableChanges(target("a", { example: price }), edits).errors.size).toBe(0);
+    const missing = usagePriceTableChanges(target("b", {}), edits);
+    expect(missing.changes).toEqual([]);
+    expect(missing.errors.has("model:example")).toBe(true);
+  });
+
+  it("ignores empty new rows without blocking other edits", () => {
+    const environment = target("a", { example: price });
+    const empty: UsagePriceDraft = {
+      id: "new:1",
+      model: " ",
+      isNew: true,
+      values: { inputCostPerMillionTokens: " " },
+    };
+    const plan = usagePriceTableChanges(environment, [
+      draft({ inputCostPerMillionTokens: "3" }),
+      empty,
+    ]);
+    expect(plan.errors.size).toBe(0);
+    expect(plan.changes).toEqual([
+      { model: "example", price: { ...price, inputCostPerMillionTokens: 3 } },
+    ]);
+    expect(usagePriceTableChanges(environment, [empty]).changes).toEqual([]);
+    expect(
+      usagePriceTableChanges(environment, [
+        { ...empty, values: { inputCostPerMillionTokens: "0" } },
+      ]).errors.get(empty.id),
+    ).toBe("Enter a model ID.");
+  });
+
+  it.each(["Offline", "Read-only access", "Update server to edit prices"])(
+    "does not let %s destinations block a valid edit elsewhere",
+    (unavailable) => {
+      const edits = [draft({ inputCostPerMillionTokens: "3" })];
+      const writable = target("writable", { example: price });
+      const other = target("other", {});
+      expect(usagePriceTableErrors([writable, { ...other, unavailable }], edits).size).toBe(0);
+      expect(usagePriceTableErrors([writable, other], edits).has("model:example")).toBe(true);
+    },
+  );
+
+  it("does not write unchanged rates and rejects invalid edited cells", () => {
+    const environment = target("a", { example: price });
+    expect(
+      usagePriceTableChanges(environment, [draft({ inputCostPerMillionTokens: "2.00" })]).changes,
+    ).toEqual([]);
+    expect(
+      usagePriceTableChanges(environment, [draft({ cacheReadCostPerMillionTokens: "-1" })]).errors
+        .size,
+    ).toBe(1);
+    expect(
+      usagePriceTableChanges(environment, [draft({ outputCostPerMillionTokens: "" })]).errors.size,
+    ).toBe(1);
+  });
+});
diff --git a/apps/web/src/components/usage/usagePriceTable.ts b/apps/web/src/components/usage/usagePriceTable.ts
new file mode 100644
index 000000000000..0a9fd16c4515
--- /dev/null
+++ b/apps/web/src/components/usage/usagePriceTable.ts
@@ -0,0 +1,97 @@
+import {
+  parseUsagePriceForm,
+  usagePriceForm,
+  USAGE_PRICE_FIELDS,
+  type UsagePriceForm,
+} from "./usagePriceForm";
+import type { UsagePriceChange, UsagePriceTarget } from "./usagePriceTargets";
+
+export type UsagePriceField = (typeof USAGE_PRICE_FIELDS)[number]["key"];
+
+export interface UsagePriceDraft {
+  readonly id: string;
+  readonly model: string;
+  readonly isNew: boolean;
+  readonly values: Partial<Pick<UsagePriceForm, UsagePriceField>>;
+  readonly removed?: boolean;
+}
+
+export function isEmptyUsagePriceDraft(draft: UsagePriceDraft) {
+  return (
+    draft.isNew &&
+    draft.model.trim() === "" &&
+    Object.values(draft.values).every((value) => value.trim() === "")
+  );
+}
+
+function modelPrice(target: UsagePriceTarget, model: string) {
+  return target.prices && Object.hasOwn(target.prices, model) ? target.prices[model] : undefined;
+}
+
+export function usagePriceCell(
+  targets: readonly UsagePriceTarget[],
+  model: string,
+  field: UsagePriceField,
+) {
+  const optional = USAGE_PRICE_FIELDS.find((entry) => entry.key === field)!.optional;
+  const values = targets.map((target) =>
+    modelPrice(target, model) ? usagePriceForm(model, modelPrice(target, model))[field] : null,
+  );
+  if (targets.some((target) => target.prices === null))
+    return { value: "", placeholder: "Unavailable" };
+  if (values.some((value) => value !== values[0])) return { value: "", placeholder: "Mixed" };
+  return {
+    value: values[0] ?? "",
+    placeholder: values[0] === null ? "Automatic" : optional ? "Input rate" : "0.00",
+  };
+}
+
+/** Only edited cells replace rates; untouched cells retain each environment's own values. */
+export function usagePriceTableChanges(
+  target: UsagePriceTarget,
+  drafts: readonly UsagePriceDraft[],
+) {
+  const changes: UsagePriceChange[] = [];
+  const errors = new Map<string, string>();
+  for (const draft of drafts) {
+    if (isEmptyUsagePriceDraft(draft)) continue;
+    const model = draft.model.trim();
+    if (draft.removed) {
+      if (modelPrice(target, model)) changes.push({ model, price: null });
+      continue;
+    }
+    const original = usagePriceForm(model, modelPrice(target, model));
+    const form = { ...original, ...draft.values };
+    const parsed = parseUsagePriceForm(form);
+    if (parsed === null) {
+      const missing = USAGE_PRICE_FIELDS.find(
+        (field) => !field.optional && form[field.key].trim() === "",
+      );
+      errors.set(
+        draft.id,
+        model === ""
+          ? "Enter a model ID."
+          : missing
+            ? `${missing.label} is required on ${target.label}.`
+            : "Use non-negative numbers for prices.",
+      );
+      continue;
+    }
+    const next = usagePriceForm(model, parsed.price);
+    if (USAGE_PRICE_FIELDS.some((field) => original[field.key] !== next[field.key]))
+      changes.push(parsed);
+  }
+  return { changes, errors };
+}
+
+/** Unavailable destinations report a save failure without blocking writable environments. */
+export function usagePriceTableErrors(
+  targets: readonly UsagePriceTarget[],
+  drafts: readonly UsagePriceDraft[],
+) {
+  return new Map(
+    targets
+      .filter((target) => target.unavailable === null && target.prices !== null)
+      .flatMap((target) => [...usagePriceTableChanges(target, drafts).errors]),
+  );
+}
diff --git a/apps/web/src/components/usage/usagePriceTargets.test.ts b/apps/web/src/components/usage/usagePriceTargets.test.ts
new file mode 100644
index 000000000000..f445c9b429fe
--- /dev/null
+++ b/apps/web/src/components/usage/usagePriceTargets.test.ts
@@ -0,0 +1,143 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  writeUsagePrices,
+  type UsagePriceTarget,
+  type UsagePriceWriteResult,
+} from "./usagePriceTargets";
+
+const price = { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 };
+const target = (id: string, overrides: Partial<UsagePriceTarget> = {}): UsagePriceTarget => ({
+  environmentId: EnvironmentId.make(id),
+  label: id,
+  prices: { example: price },
+  unavailable: null,
+  ...overrides,
+});
+
+describe("model price writes", () => {
+  it("sends all table changes in one patch per environment and skips unchanged destinations", async () => {
+    const write = vi.fn(async () => ({ _tag: "Success" as const }));
+    const onResult = vi.fn();
+    await writeUsagePrices({
+      targets: [target("edited"), target("unchanged")],
+      changes: new Map([
+        [
+          EnvironmentId.make("edited"),
+          [
+            { model: "new-model", price },
+            { model: "example", price: null },
+          ],
+        ],
+      ]),
+      write,
+      onResult,
+    });
+    expect(write).toHaveBeenCalledExactlyOnceWith({
+      environmentId: "edited",
+      input: { patch: { usagePriceOverrides: { "new-model": price, example: null } } },
+    });
+    expect(onResult).toHaveBeenCalledWith("unchanged", { status: "saved" });
+  });
+
+  it("saves independently, skips unavailable targets, and retries failures without rewriting successes", async () => {
+    let resolveSlow!: (result: { _tag: "Success" | "Failure" }) => void;
+    const slow = new Promise<{ _tag: "Success" | "Failure" }>((resolve) => {
+      resolveSlow = resolve;
+    });
+    let resolveFastSaved!: () => void;
+    const fastSaved = new Promise<void>((resolve) => {
+      resolveFastSaved = resolve;
+    });
+    const targets = [target("fast"), target("slow"), target("offline", { unavailable: "Offline" })];
+    const results = new Map<EnvironmentId, UsagePriceWriteResult>();
+    const write = vi.fn(async ({ environmentId }: { environmentId: EnvironmentId }) =>
+      environmentId === "slow" ? slow : { _tag: "Success" as const },
+    );
+    const change = { model: "example", price };
+    const running = writeUsagePrices({
+      targets,
+      changes: new Map(targets.map((target) => [target.environmentId, [change]])),
+      write,
+      onResult: (id, result) => {
+        results.set(id, result);
+        if (id === "fast") resolveFastSaved();
+      },
+    });
+    await fastSaved;
+    expect(results.get(EnvironmentId.make("fast"))).toEqual({ status: "saved" });
+    expect(results.get(EnvironmentId.make("offline"))).toEqual({
+      status: "failed",
+      error: "Offline",
+    });
+    expect(results.has(EnvironmentId.make("slow"))).toBe(false);
+    resolveSlow({ _tag: "Failure" });
+    await running;
+    expect(write).toHaveBeenCalledTimes(2);
+    expect(write).toHaveBeenCalledWith({
+      environmentId: "fast",
+      input: { patch: { usagePriceOverrides: { example: price } } },
+    });
+    const retry = vi.fn(async () => ({ _tag: "Success" as const }));
+    await writeUsagePrices({
+      targets: targets
+        .filter((entry) => results.get(entry.environmentId)?.status === "failed")
+        .map((entry) => ({ ...entry, unavailable: null })),
+      changes: new Map(targets.map((target) => [target.environmentId, [change]])),
+      write: retry,
+      onResult: (id, result) => {
+        results.set(id, result);
+      },
+    });
+    expect(retry.mock.calls).toHaveLength(2);
+    expect(retry).not.toHaveBeenCalledWith(expect.objectContaining({ environmentId: "fast" }));
+    expect([...results.values()].every((result) => result.status === "saved")).toBe(true);
+  });
+
+  it("resets only the chosen model on the selected destination", async () => {
+    const write = vi.fn(async () => ({ _tag: "Success" as const }));
+    const onResult = vi.fn();
+    await writeUsagePrices({
+      targets: [target("selected")],
+      changes: new Map([[EnvironmentId.make("selected"), [{ model: "example", price: null }]]]),
+      write,
+      onResult,
+    });
+    expect(write).toHaveBeenCalledExactlyOnceWith({
+      environmentId: "selected",
+      input: { patch: { usagePriceOverrides: { example: null } } },
+    });
+    expect(onResult).toHaveBeenCalledWith("selected", { status: "saved" });
+  });
+
+  it("reports thrown writes and permission/version restrictions without aborting other saves", async () => {
+    const onResult = vi.fn();
+    const write = vi.fn(async () => {
+      throw new Error("connection lost");
+    });
+    await writeUsagePrices({
+      targets: [
+        target("lost"),
+        target("denied", { unavailable: "Read-only access" }),
+        target("old", { unavailable: "Update server to edit prices" }),
+      ],
+      changes: new Map([[EnvironmentId.make("lost"), [{ model: "example", price }]]]),
+      write,
+      onResult,
+    });
+    expect(write).toHaveBeenCalledTimes(1);
+    expect(onResult).toHaveBeenCalledWith("lost", {
+      status: "failed",
+      error: "Could not save. Try again.",
+    });
+    expect(onResult).toHaveBeenCalledWith("denied", {
+      status: "failed",
+      error: "Read-only access",
+    });
+    expect(onResult).toHaveBeenCalledWith("old", {
+      status: "failed",
+      error: "Update server to edit prices",
+    });
+  });
+});
diff --git a/apps/web/src/components/usage/usagePriceTargets.ts b/apps/web/src/components/usage/usagePriceTargets.ts
new file mode 100644
index 000000000000..377724532bc6
--- /dev/null
+++ b/apps/web/src/components/usage/usagePriceTargets.ts
@@ -0,0 +1,65 @@
+import type {
+  EnvironmentId,
+  ServerSettingsPatch,
+  UsageModelPriceOverride,
+} from "@t3tools/contracts";
+
+export interface UsagePriceTarget {
+  readonly environmentId: EnvironmentId;
+  readonly label: string;
+  readonly prices: Readonly<Record<string, UsageModelPriceOverride>> | null;
+  readonly unavailable: string | null;
+}
+
+export interface UsagePriceChange {
+  readonly model: string;
+  readonly price: UsageModelPriceOverride | null;
+}
+
+export type UsagePriceWriteResult =
+  | { readonly status: "saved" }
+  | { readonly status: "failed"; readonly error: string };
+
+/** Each destination settles independently; retry callers pass only the failed destinations. */
+export async function writeUsagePrices(input: {
+  readonly targets: readonly UsagePriceTarget[];
+  readonly changes: ReadonlyMap<EnvironmentId, readonly UsagePriceChange[]>;
+  readonly write: (input: {
+    environmentId: EnvironmentId;
+    input: { patch: ServerSettingsPatch };
+  }) => Promise<{ readonly _tag: "Success" | "Failure" }>;
+  readonly onResult: (environmentId: EnvironmentId, result: UsagePriceWriteResult) => void;
+}) {
+  await Promise.all(
+    input.targets.map(async (target) => {
+      let result: UsagePriceWriteResult;
+      if (target.unavailable !== null) {
+        result = { status: "failed", error: target.unavailable };
+      } else {
+        try {
+          const changes = input.changes.get(target.environmentId) ?? [];
+          const saved =
+            changes.length === 0
+              ? { _tag: "Success" as const }
+              : await input.write({
+                  environmentId: target.environmentId,
+                  input: {
+                    patch: {
+                      usagePriceOverrides: Object.fromEntries(
+                        changes.map((change) => [change.model, change.price]),
+                      ),
+                    },
+                  },
+                });
+          result =
+            saved._tag === "Success"
+              ? { status: "saved" }
+              : { status: "failed", error: "Could not save. Try again." };
+        } catch {
+          result = { status: "failed", error: "Could not save. Try again." };
+        }
+      }
+      input.onResult(target.environmentId, result);
+    }),
+  );
+}
diff --git a/apps/web/src/composer-editor-mentions.test.ts b/apps/web/src/composer-editor-mentions.test.ts
index 33f37af6802b..337fe7b8ae64 100644
--- a/apps/web/src/composer-editor-mentions.test.ts
+++ b/apps/web/src/composer-editor-mentions.test.ts
@@ -198,6 +198,29 @@ describe("splitPromptIntoComposerSegments", () => {
     ]);
   });
 
+  it("splits digit-leading skill tokens into skill segments", () => {
+    expect(splitPromptIntoComposerSegments("Use $2spec please")).toEqual([
+      { type: "text", text: "Use " },
+      { type: "skill", name: "2spec" },
+      { type: "text", text: " please" },
+    ]);
+  });
+
+  it("keeps digits-only dollar amounts and compact monetary expressions as text", () => {
+    expect(splitPromptIntoComposerSegments("I'll pay $20 tomorrow")).toEqual([
+      { type: "text", text: "I'll pay $20 tomorrow" },
+    ]);
+    expect(splitPromptIntoComposerSegments("Budget is $20k tomorrow")).toEqual([
+      { type: "text", text: "Budget is $20k tomorrow" },
+    ]);
+    expect(splitPromptIntoComposerSegments("Cost is $100M total")).toEqual([
+      { type: "text", text: "Cost is $100M total" },
+    ]);
+    expect(splitPromptIntoComposerSegments("Limit is $1e6 here")).toEqual([
+      { type: "text", text: "Limit is $1e6 here" },
+    ]);
+  });
+
   it("does not convert an incomplete trailing skill token", () => {
     expect(splitPromptIntoComposerSegments("Use $review-follow-up")).toEqual([
       { type: "text", text: "Use $review-follow-up" },
diff --git a/apps/web/src/composerDraftStore.test.ts b/apps/web/src/composerDraftStore.test.ts
index 068bb1ff41f0..53d07aab21d9 100644
--- a/apps/web/src/composerDraftStore.test.ts
+++ b/apps/web/src/composerDraftStore.test.ts
@@ -66,14 +66,13 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test"
 import {
   COMPOSER_DRAFT_STORAGE_KEY,
   clearComposerDraftsEnvironment,
+  composerDraftHasUserContent,
   finalizePromotedDraftThreadByRef,
-  markPromotedDraftThread,
   markPromotedDraftThreadByRef,
-  markPromotedDraftThreads,
-  markPromotedDraftThreadsByRef,
   type ComposerFileAttachment,
   type ComposerImageAttachment,
   composerFileNeedsReattach,
+  partializeComposerDraftStoreState,
   useComposerDraftStore,
   DraftId,
 } from "./composerDraftStore";
@@ -83,7 +82,7 @@ import {
   insertInlineTerminalContextPlaceholder,
   type TerminalContextDraft,
 } from "./lib/terminalContext";
-import { createDebouncedStorage } from "./lib/storage";
+import { createDeferredStorage } from "./lib/storage";
 
 function makeImage(input: {
   id: string;
@@ -195,37 +194,42 @@ describe("composerDraftStore assistant citations", () => {
   beforeEach(resetComposerDraftStore);
   afterEach(resetComposerDraftStore);
 
-  it("keeps quotes, comments, and remote source IDs through persistence and removes them on clear", () => {
-    const threadId = ThreadId.make("citation-draft");
-    const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
-    const citation = {
-      version: 1 as const,
-      environmentId: EnvironmentId.make("remote-source"),
-      threadId: ThreadId.make("source-thread"),
-      messageId: MessageId.make("source-message"),
-      text: "Preserve the selected text after reload.",
-      comment: "Why is this important?\nPlease show an example.",
-      start: 12,
-      end: 52,
-      prefix: "Before. ",
-      suffix: " After.",
-    };
-    const prompt = `Explain ${serializeAssistantCitation(citation)} further.`;
-    useComposerDraftStore.getState().setPrompt(threadRef, prompt);
-    const options = useComposerDraftStore.persist.getOptions();
-    const saved = JSON.parse(
-      JSON.stringify(options.partialize!(useComposerDraftStore.getState())),
-    ) as unknown;
-    resetComposerDraftStore();
-    const hydrated = options.merge!(saved, useComposerDraftStore.getState());
-    useComposerDraftStore.setState(hydrated);
-    const restored = draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt ?? "";
-    expect(restored).toBe(prompt);
-    expect(collectAssistantCitations(restored).map((entry) => entry.citation)).toEqual([citation]);
-    useComposerDraftStore.getState().clearComposerContent(threadRef);
-    expect(
-      collectAssistantCitations(draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt ?? ""),
-    ).toEqual([]);
+  it("keeps quotes, comments, and remote source IDs through persistence and removes them on clear", async () => {
+    await useComposerDraftStore.persist.clearStorage();
+    vi.useFakeTimers();
+    try {
+      const threadId = ThreadId.make("citation-draft");
+      const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
+      const citation = {
+        version: 1 as const,
+        environmentId: EnvironmentId.make("remote-source"),
+        threadId: ThreadId.make("source-thread"),
+        messageId: MessageId.make("source-message"),
+        text: "Preserve the selected text after reload.",
+        comment: "Why is this important?\nPlease show an example.",
+        start: 12,
+        end: 52,
+        prefix: "Before. ",
+        suffix: " After.",
+      };
+      const prompt = `Explain ${serializeAssistantCitation(citation)} further.`;
+      useComposerDraftStore.getState().setPrompt(threadRef, prompt);
+      await vi.advanceTimersByTimeAsync(300);
+      resetComposerDraftStore();
+      await useComposerDraftStore.persist.rehydrate();
+      const restored = draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt ?? "";
+      expect(restored).toBe(prompt);
+      expect(collectAssistantCitations(restored).map((entry) => entry.citation)).toEqual([
+        citation,
+      ]);
+      useComposerDraftStore.getState().clearComposerContent(threadRef);
+      expect(
+        collectAssistantCitations(draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt ?? ""),
+      ).toEqual([]);
+    } finally {
+      await useComposerDraftStore.persist.clearStorage();
+      vi.useRealTimers();
+    }
   });
 });
 
@@ -347,6 +351,31 @@ describe("composerDraftStore clearComposerContent", () => {
   });
 });
 
+describe("composerDraftStore unsent draft marker", () => {
+  const threadId = ThreadId.make("thread-unsent-marker");
+  const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
+
+  beforeEach(() => {
+    resetComposerDraftStore();
+  });
+
+  it("reports content for typed text and clears when the composer is emptied", () => {
+    const hasDraft = () =>
+      composerDraftHasUserContent(useComposerDraftStore.getState().getComposerDraft(threadRef));
+
+    expect(hasDraft()).toBe(false);
+
+    useComposerDraftStore.getState().setPrompt(threadRef, "   ");
+    expect(hasDraft()).toBe(false);
+
+    useComposerDraftStore.getState().setPrompt(threadRef, "follow up on the relay case");
+    expect(hasDraft()).toBe(true);
+
+    useComposerDraftStore.getState().clearComposerContent(threadRef);
+    expect(hasDraft()).toBe(false);
+  });
+});
+
 describe("composerDraftStore file attachments", () => {
   const threadId = ThreadId.make("thread-files");
   const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
@@ -362,7 +391,6 @@ describe("composerDraftStore file attachments", () => {
 
     const persistApi = useComposerDraftStore.persist as unknown as {
       getOptions: () => {
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
         merge: (
           persistedState: unknown,
           currentState: ReturnType<typeof useComposerDraftStore.getState>,
@@ -370,9 +398,7 @@ describe("composerDraftStore file attachments", () => {
       };
     };
     const options = persistApi.getOptions();
-    const persisted = options.partialize(useComposerDraftStore.getState()) as {
-      draftsByThreadKey: Record<string, { files?: Array<Record<string, unknown>> }>;
-    };
+    const persisted = partializeComposerDraftStoreState(useComposerDraftStore.getState());
 
     expect(persisted.draftsByThreadKey[threadKeyFor(threadId, TEST_ENVIRONMENT_ID)]?.files).toEqual(
       [
@@ -410,7 +436,6 @@ describe("composerDraftStore file attachments", () => {
 
     const persistApi = useComposerDraftStore.persist as unknown as {
       getOptions: () => {
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
         merge: (
           persistedState: unknown,
           currentState: ReturnType<typeof useComposerDraftStore.getState>,
@@ -418,9 +443,7 @@ describe("composerDraftStore file attachments", () => {
       };
     };
     const options = persistApi.getOptions();
-    const persisted = options.partialize(useComposerDraftStore.getState()) as {
-      draftsByThreadKey: Record<string, { files?: Array<Record<string, unknown>> }>;
-    };
+    const persisted = partializeComposerDraftStoreState(useComposerDraftStore.getState());
 
     expect(persisted.draftsByThreadKey[threadKeyFor(threadId, TEST_ENVIRONMENT_ID)]?.files).toEqual(
       [
@@ -809,12 +832,9 @@ describe("composerDraftStore terminal contexts", () => {
       .getState()
       .addTerminalContext(threadRef, makeTerminalContext({ id: "ctx-persist" }));
 
-    const persistApi = useComposerDraftStore.persist as unknown as {
-      getOptions: () => {
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
-      };
-    };
-    const persistedState = persistApi.getOptions().partialize(useComposerDraftStore.getState()) as {
+    const persistedState = partializeComposerDraftStoreState(
+      useComposerDraftStore.getState(),
+    ) as unknown as {
       draftsByThreadKey?: Record<string, { terminalContexts?: Array<Record<string, unknown>> }>;
     };
 
@@ -983,12 +1003,9 @@ describe("composerDraftStore element contexts", () => {
 
   it("persists element contexts via the partializer (round-trippable)", () => {
     useComposerDraftStore.getState().addElementContext(threadRef, baseSelection);
-    const persistApi = useComposerDraftStore.persist as unknown as {
-      getOptions: () => {
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
-      };
-    };
-    const persisted = persistApi.getOptions().partialize(useComposerDraftStore.getState()) as {
+    const persisted = partializeComposerDraftStoreState(
+      useComposerDraftStore.getState(),
+    ) as unknown as {
       draftsByThreadKey?: Record<string, { elementContexts?: Array<Record<string, unknown>> }>;
     };
     const entry =
@@ -1041,12 +1058,9 @@ describe("composerDraftStore review comments", () => {
   it("persists review comments and clears them with composer content", () => {
     const store = useComposerDraftStore.getState();
     store.addReviewComment(threadRef, comment);
-    const persistApi = useComposerDraftStore.persist as unknown as {
-      getOptions: () => {
-        partialize: (state: ReturnType<typeof useComposerDraftStore.getState>) => unknown;
-      };
-    };
-    const persisted = persistApi.getOptions().partialize(useComposerDraftStore.getState()) as {
+    const persisted = partializeComposerDraftStoreState(
+      useComposerDraftStore.getState(),
+    ) as unknown as {
       draftsByThreadKey?: Record<string, { reviewComments?: Array<Record<string, unknown>> }>;
     };
 
@@ -1183,7 +1197,7 @@ describe("composerDraftStore project draft thread mapping", () => {
       interactionMode: "plan",
     });
     store.setPrompt(draftId, "keep this prompt");
-    markPromotedDraftThread(threadId);
+    markPromotedDraftThreadByRef(scopeThreadRef(TEST_ENVIRONMENT_ID, threadId));
 
     store.setLogicalProjectDraftThreadId(scopedProjectKey(projectRef), projectRef, draftId, {
       threadId: retryThreadId,
@@ -1346,12 +1360,12 @@ describe("composerDraftStore project draft thread mapping", () => {
     expect(draftByKey(draftId)).toBeUndefined();
   });
 
-  it("marks a promoted draft by thread id without deleting composer state", () => {
+  it("marks a promoted draft by scoped ref without deleting composer state", () => {
     const store = useComposerDraftStore.getState();
     store.setProjectDraftThreadId(projectRef, draftId, { threadId });
     store.setPrompt(draftId, "promote me");
 
-    markPromotedDraftThread(threadId);
+    markPromotedDraftThreadByRef(scopeThreadRef(TEST_ENVIRONMENT_ID, threadId));
 
     expect(useComposerDraftStore.getState().getDraftThreadByProjectRef(projectRef)).toBeNull();
     expect(useComposerDraftStore.getState().getDraftThread(draftId)?.promotedTo).toEqual(
@@ -1376,20 +1390,20 @@ describe("composerDraftStore project draft thread mapping", () => {
     const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
     store.setPrompt(threadRef, "keep me");
 
-    markPromotedDraftThread(threadId);
+    markPromotedDraftThreadByRef(scopeThreadRef(TEST_ENVIRONMENT_ID, threadId));
 
     expect(useComposerDraftStore.getState().getDraftThread(threadRef)).toBeNull();
     expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt).toBe("keep me");
   });
 
-  it("marks promoted drafts from an iterable of server thread ids", () => {
+  it("promotes a draft without changing another thread's draft", () => {
     const store = useComposerDraftStore.getState();
     store.setProjectDraftThreadId(projectRef, draftId, { threadId });
     store.setPrompt(draftId, "promote me");
     store.setProjectDraftThreadId(otherProjectRef, otherDraftId, { threadId: otherThreadId });
     store.setPrompt(otherDraftId, "keep me");
 
-    markPromotedDraftThreads([threadId]);
+    markPromotedDraftThreadByRef(scopeThreadRef(TEST_ENVIRONMENT_ID, threadId));
 
     expect(useComposerDraftStore.getState().getDraftThread(draftId)?.promotedTo).toEqual(
       scopeThreadRef(TEST_ENVIRONMENT_ID, threadId),
@@ -1401,7 +1415,7 @@ describe("composerDraftStore project draft thread mapping", () => {
     expect(draftByKey(otherDraftId)?.prompt).toBe("keep me");
   });
 
-  it("marks every matching scoped draft when multiple environments share a thread id", () => {
+  it("promotes matching thread ids separately for each environment", () => {
     const store = useComposerDraftStore.getState();
     const localThreadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
     const remoteThreadRef = scopeThreadRef(OTHER_TEST_ENVIRONMENT_ID, threadId);
@@ -1411,7 +1425,16 @@ describe("composerDraftStore project draft thread mapping", () => {
     store.setProjectDraftThreadId(remoteProjectRef, remoteDraftId, { threadId });
     store.setPrompt(remoteDraftId, "remote draft");
 
-    markPromotedDraftThread(threadId);
+    markPromotedDraftThreadByRef(localThreadRef);
+
+    expect(store.getDraftThreadByProjectRef(projectRef)).toBeNull();
+    expect(store.getDraftThreadByProjectRef(remoteProjectRef)?.threadId).toBe(threadId);
+    expect(store.getDraftThreadByRef(localThreadRef)?.promotedTo).toEqual(localThreadRef);
+    expect(store.getDraftThreadByRef(remoteThreadRef)?.promotedTo).toBeNull();
+    expect(draftByKey(localDraftId)?.prompt).toBe("local draft");
+    expect(draftByKey(remoteDraftId)?.prompt).toBe("remote draft");
+
+    markPromotedDraftThreadByRef(remoteThreadRef);
 
     expect(store.getDraftThreadByProjectRef(projectRef)).toBeNull();
     expect(store.getDraftThreadByProjectRef(remoteProjectRef)).toBeNull();
@@ -1434,34 +1457,10 @@ describe("composerDraftStore project draft thread mapping", () => {
     expect(draftByKey(draftId)?.prompt).toBe("promote me");
   });
 
-  it("only marks iterable promotion cleanup entries for the matching environment refs", () => {
-    const store = useComposerDraftStore.getState();
-    store.setProjectDraftThreadId(projectRef, draftId, { threadId });
-    store.setPrompt(draftId, "promote me");
-
-    markPromotedDraftThreadsByRef([scopeThreadRef(OTHER_TEST_ENVIRONMENT_ID, threadId)]);
-
-    expect(useComposerDraftStore.getState().getDraftThreadByProjectRef(projectRef)?.threadId).toBe(
-      threadId,
-    );
-    expect(draftByKey(draftId)?.prompt).toBe("promote me");
-  });
-
-  it("keeps existing server-thread composer drafts during iterable promotion cleanup", () => {
-    const store = useComposerDraftStore.getState();
-    const threadRef = scopeThreadRef(TEST_ENVIRONMENT_ID, threadId);
-    store.setPrompt(threadRef, "keep me");
-
-    markPromotedDraftThreads([threadId]);
-
-    expect(useComposerDraftStore.getState().getDraftThread(threadRef)).toBeNull();
-    expect(draftFor(threadId, TEST_ENVIRONMENT_ID)?.prompt).toBe("keep me");
-  });
-
   it("moves composer edits made during promotion to the canonical thread", () => {
     const store = useComposerDraftStore.getState();
     store.setProjectDraftThreadId(projectRef, draftId, { threadId });
-    markPromotedDraftThread(threadId);
+    markPromotedDraftThreadByRef(scopeThreadRef(TEST_ENVIRONMENT_ID, threadId));
     store.setPrompt(draftId, "typed during setup");
 
     finalizePromotedDraftThreadByRef(scopeThreadRef(TEST_ENVIRONMENT_ID, threadId));
@@ -2491,7 +2490,7 @@ describe("composerDraftStore runtime and interaction settings", () => {
 });
 
 // ---------------------------------------------------------------------------
-// createDebouncedStorage
+// createDeferredStorage
 // ---------------------------------------------------------------------------
 
 function createMockStorage() {
@@ -2507,9 +2506,75 @@ function createMockStorage() {
   };
 }
 
-describe("createDebouncedStorage", () => {
+describe("composer draft persistence", () => {
+  it("defers attachment reads and serialization until typing stops, then restores the last draft", async () => {
+    await useComposerDraftStore.persist.clearStorage();
+    vi.useFakeTimers();
+    const stringify = vi.spyOn(JSON, "stringify");
+    try {
+      resetComposerDraftStore();
+      const heavyThreadId = ThreadId.make("heavy-draft");
+      const typingThreadId = ThreadId.make("typing-draft");
+      const heavyRef = scopeThreadRef(TEST_ENVIRONMENT_ID, heavyThreadId);
+      const typingRef = scopeThreadRef(TEST_ENVIRONMENT_ID, typingThreadId);
+      const heavyKey = scopedThreadKey(heavyRef);
+      useComposerDraftStore.getState().setPrompt(heavyRef, "Keep this image");
+      const attachments = [
+        {
+          id: "heavy-image",
+          name: "image.png",
+          mimeType: "image/png",
+          sizeBytes: 49_152,
+          dataUrl: `data:image/png;base64,${"AQID".repeat(16_384)}`,
+        },
+      ];
+      let attachmentReads = 0;
+      useComposerDraftStore.setState((state) => ({
+        draftsByThreadKey: {
+          ...state.draftsByThreadKey,
+          [heavyKey]: {
+            ...state.draftsByThreadKey[heavyKey]!,
+            get persistedAttachments() {
+              attachmentReads += 1;
+              return attachments;
+            },
+          },
+        },
+      }));
+      attachmentReads = 0;
+      stringify.mockClear();
+
+      for (let index = 1; index <= 20; index++) {
+        useComposerDraftStore.getState().setPrompt(typingRef, `Draft ${index}`);
+      }
+      expect(attachmentReads).toBe(0);
+      expect(stringify).not.toHaveBeenCalled();
+
+      await vi.advanceTimersByTimeAsync(300);
+      expect(attachmentReads).toBe(1);
+      expect(stringify).toHaveBeenCalledTimes(1);
+
+      resetComposerDraftStore();
+      await useComposerDraftStore.persist.rehydrate();
+      expect(draftFor(typingThreadId, TEST_ENVIRONMENT_ID)?.prompt).toBe("Draft 20");
+      expect(draftFor(heavyThreadId, TEST_ENVIRONMENT_ID)?.persistedAttachments).toEqual(
+        attachments,
+      );
+    } finally {
+      stringify.mockRestore();
+      await useComposerDraftStore.persist.clearStorage();
+      vi.useRealTimers();
+      resetComposerDraftStore();
+    }
+  });
+});
+
+describe("createDeferredStorage", () => {
+  const serialize = vi.fn((value: string) => `s:${value}`);
+
   beforeEach(() => {
     vi.useFakeTimers();
+    serialize.mockClear();
   });
 
   afterEach(() => {
@@ -2519,69 +2584,74 @@ describe("createDebouncedStorage", () => {
   it("delegates getItem immediately", () => {
     const base = createMockStorage();
     base.getItem.mockReturnValueOnce("value");
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
 
     expect(storage.getItem("key")).toBe("value");
     expect(base.getItem).toHaveBeenCalledWith("key");
   });
 
-  it("does not write to base storage until the debounce fires", () => {
+  it("neither serializes nor writes until the debounce fires", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
 
     storage.setItem("key", "v1");
+    expect(serialize).not.toHaveBeenCalled();
     expect(base.setItem).not.toHaveBeenCalled();
 
     vi.advanceTimersByTime(299);
+    expect(serialize).not.toHaveBeenCalled();
     expect(base.setItem).not.toHaveBeenCalled();
 
     vi.advanceTimersByTime(1);
-    expect(base.setItem).toHaveBeenCalledWith("key", "v1");
+    expect(base.setItem).toHaveBeenCalledWith("key", "s:v1");
   });
 
-  it("only writes the last value when setItem is called rapidly", () => {
+  it("serializes and writes only the last value when setItem is called rapidly", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
 
     storage.setItem("key", "v1");
     storage.setItem("key", "v2");
     storage.setItem("key", "v3");
 
     vi.advanceTimersByTime(300);
+    expect(serialize).toHaveBeenCalledTimes(1);
     expect(base.setItem).toHaveBeenCalledTimes(1);
-    expect(base.setItem).toHaveBeenCalledWith("key", "v3");
+    expect(base.setItem).toHaveBeenCalledWith("key", "s:v3");
   });
 
   it("removeItem cancels a pending setItem write", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
 
     storage.setItem("key", "v1");
     storage.removeItem("key");
 
     vi.advanceTimersByTime(300);
+    expect(serialize).not.toHaveBeenCalled();
     expect(base.setItem).not.toHaveBeenCalled();
     expect(base.removeItem).toHaveBeenCalledWith("key");
   });
 
-  it("flush writes the pending value immediately", () => {
+  it("flush serializes and writes the pending value immediately", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
 
     storage.setItem("key", "v1");
     expect(base.setItem).not.toHaveBeenCalled();
 
     storage.flush();
-    expect(base.setItem).toHaveBeenCalledWith("key", "v1");
+    expect(base.setItem).toHaveBeenCalledWith("key", "s:v1");
 
     // Timer should be cancelled; no duplicate write.
     vi.advanceTimersByTime(300);
+    expect(serialize).toHaveBeenCalledTimes(1);
     expect(base.setItem).toHaveBeenCalledTimes(1);
   });
 
   it("flush is a no-op when nothing is pending", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
 
     storage.flush();
     expect(base.setItem).not.toHaveBeenCalled();
@@ -2589,7 +2659,7 @@ describe("createDebouncedStorage", () => {
 
   it("flush after removeItem is a no-op", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
 
     storage.setItem("key", "v1");
     storage.removeItem("key");
@@ -2600,7 +2670,7 @@ describe("createDebouncedStorage", () => {
 
   it("setItem works normally after removeItem cancels a pending write", () => {
     const base = createMockStorage();
-    const storage = createDebouncedStorage(base);
+    const storage = createDeferredStorage(base, serialize);
 
     storage.setItem("key", "v1");
     storage.removeItem("key");
@@ -2608,6 +2678,6 @@ describe("createDebouncedStorage", () => {
 
     vi.advanceTimersByTime(300);
     expect(base.setItem).toHaveBeenCalledTimes(1);
-    expect(base.setItem).toHaveBeenCalledWith("key", "v2");
+    expect(base.setItem).toHaveBeenCalledWith("key", "s:v2");
   });
 });
diff --git a/apps/web/src/composerDraftStore.ts b/apps/web/src/composerDraftStore.ts
index 2e8b8ae76779..3adb6e45c2ae 100644
--- a/apps/web/src/composerDraftStore.ts
+++ b/apps/web/src/composerDraftStore.ts
@@ -53,9 +53,9 @@ import {
   newElementContextId,
 } from "./lib/elementContext";
 import { create } from "zustand";
-import { createJSONStorage, persist } from "zustand/middleware";
+import { persist, type PersistStorage, type StorageValue } from "zustand/middleware";
 import { useShallow } from "zustand/react/shallow";
-import { createDebouncedStorage, createMemoryStorage } from "./lib/storage";
+import { createDeferredStorage, createMemoryStorage } from "./lib/storage";
 import { getDefaultServerModel } from "./providerModels";
 import { UnifiedSettings } from "@t3tools/contracts/settings";
 import { ReviewCommentContextSchema, type ReviewCommentContext } from "./reviewCommentContext";
@@ -73,11 +73,39 @@ export type DraftId = typeof DraftId.Type;
 
 const COMPOSER_PERSIST_DEBOUNCE_MS = 300;
 
-const composerDebouncedStorage = createDebouncedStorage(
+// Keep the immutable state until flush. Migration writebacks already have the persisted shape.
+type ComposerPersistState =
+  | { capturedState: ComposerDraftStoreState }
+  | PersistedComposerDraftStoreState;
+
+const composerDebouncedStorage = createDeferredStorage<StorageValue<ComposerPersistState>>(
   typeof localStorage !== "undefined" ? localStorage : createMemoryStorage(),
+  (value) =>
+    JSON.stringify({
+      state:
+        "capturedState" in value.state
+          ? partializeComposerDraftStoreState(value.state.capturedState)
+          : value.state,
+      version: value.version,
+    }),
   COMPOSER_PERSIST_DEBOUNCE_MS,
 );
 
+const composerPersistStorage: PersistStorage<ComposerPersistState> = {
+  getItem: (name) => {
+    // The base storage is localStorage (or in-memory), which is synchronous.
+    const raw = composerDebouncedStorage.getItem(name);
+    if (typeof raw !== "string") {
+      return null;
+    }
+    // Parsed persisted JSON. `migrate` and `merge` normalize it from unknown,
+    // so the cast mirrors the one zustand's createJSONStorage performs.
+    return JSON.parse(raw) as StorageValue<ComposerPersistState>;
+  },
+  setItem: (name, value) => composerDebouncedStorage.setItem(name, value),
+  removeItem: (name) => composerDebouncedStorage.removeItem(name),
+};
+
 // Flush pending composer draft writes before page unload to prevent data loss.
 if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
   window.addEventListener("beforeunload", () => {
@@ -2013,7 +2041,8 @@ function migratePersistedComposerDraftStoreState(
   };
 }
 
-function partializeComposerDraftStoreState(
+/** Select the persisted draft fields when the storage write is ready to flush. */
+export function partializeComposerDraftStoreState(
   state: ComposerDraftStoreState,
 ): PersistedComposerDraftStoreState {
   // Draft sessions worth persisting: mapped (a new-thread flow targets
@@ -3876,9 +3905,10 @@ const composerDraftStore = create<ComposerDraftStoreState>()(
     {
       name: COMPOSER_DRAFT_STORAGE_KEY,
       version: COMPOSER_DRAFT_STORAGE_VERSION,
-      storage: createJSONStorage(() => composerDebouncedStorage),
+      storage: composerPersistStorage,
       migrate: migratePersistedComposerDraftStoreState,
-      partialize: partializeComposerDraftStoreState,
+      // Defer the draft walk and serialization until the storage write flushes.
+      partialize: (state): ComposerPersistState => ({ capturedState: state }),
       merge: (persistedState, currentState) => {
         const normalizedPersisted =
           normalizeCurrentPersistedComposerDraftStoreState(persistedState);
@@ -4009,6 +4039,17 @@ export function useComposerThreadDraft(threadRef: ComposerThreadTarget): Compose
   });
 }
 
+/**
+ * True when a real thread's composer holds unsent user content. Selects a
+ * boolean so the sidebar row that reads it re-renders only when the draft
+ * appears or disappears, not on every keystroke.
+ */
+export function useThreadHasUnsentDraft(threadRef: ScopedThreadRef): boolean {
+  return useComposerDraftStore((state) =>
+    composerDraftHasUserContent(getComposerDraftState(state, threadRef)),
+  );
+}
+
 export function useComposerDraftModelState(
   threadRef: ComposerThreadTarget,
 ): ComposerDraftModelState {
@@ -4065,29 +4106,6 @@ export function useEffectiveComposerModelState(input: {
   );
 }
 
-/**
- * Mark a draft thread as promoting once the server has materialized the same thread id.
- *
- * Use the single-thread helper for live `thread.created` events and the
- * iterable helper for bootstrap/recovery paths that discover multiple server
- * threads at once.
- */
-export function markPromotedDraftThread(threadId: ThreadId): void {
-  const store = useComposerDraftStore.getState();
-  const draftThreadTargets: ComposerThreadTarget[] = [];
-  for (const [draftId, draftThread] of Object.entries(store.draftThreadsByThreadKey)) {
-    if (draftThread.threadId === threadId) {
-      draftThreadTargets.push(DraftId.make(draftId));
-    }
-  }
-  if (draftThreadTargets.length === 0) {
-    return;
-  }
-  for (const draftThreadTarget of draftThreadTargets) {
-    store.markDraftThreadPromoting(draftThreadTarget);
-  }
-}
-
 export function markPromotedDraftThreadByRef(threadRef: ScopedThreadRef): void {
   const draftStore = useComposerDraftStore.getState();
   for (const [draftId, draftThread] of Object.entries(draftStore.draftThreadsByThreadKey)) {
@@ -4100,18 +4118,6 @@ export function markPromotedDraftThreadByRef(threadRef: ScopedThreadRef): void {
   }
 }
 
-export function markPromotedDraftThreads(serverThreadIds: Iterable<ThreadId>): void {
-  for (const threadId of serverThreadIds) {
-    markPromotedDraftThread(threadId);
-  }
-}
-
-export function markPromotedDraftThreadsByRef(serverThreadRefs: Iterable<ScopedThreadRef>): void {
-  for (const threadRef of serverThreadRefs) {
-    markPromotedDraftThreadByRef(threadRef);
-  }
-}
-
 export function finalizePromotedDraftThreadByRef(threadRef: ScopedThreadRef): void {
   const draftStore = useComposerDraftStore.getState();
   for (const [draftId, draftThread] of Object.entries(draftStore.draftThreadsByThreadKey)) {
diff --git a/apps/web/src/connection/platform.ts b/apps/web/src/connection/platform.ts
index ac9f77c53c2d..7e88c4aae3c7 100644
--- a/apps/web/src/connection/platform.ts
+++ b/apps/web/src/connection/platform.ts
@@ -182,6 +182,9 @@ const capabilitiesLayer = Layer.effectContext(
       scopes: AuthStandardClientScopes,
     });
     const cloudSession = CloudSession.of({
+      identity: Effect.sync(() =>
+        Option.fromNullishOr(appAtomRegistry.get(managedRelaySessionAtom)),
+      ),
       clerkToken: Effect.gen(function* () {
         const session = appAtomRegistry.get(managedRelaySessionAtom);
         if (session === null) {
diff --git a/apps/web/src/connection/runtime.ts b/apps/web/src/connection/runtime.ts
index 06c8bf0ccfed..ac2316560d98 100644
--- a/apps/web/src/connection/runtime.ts
+++ b/apps/web/src/connection/runtime.ts
@@ -30,10 +30,10 @@ type ConnectionLayerSource =
   | typeof backgroundActivityObserverLayer
   | typeof backgroundActivityReporterLayer;
 
-const providedClientConnectionLayer = Layer.merge(
-  Connection.layerWithOptions({ environmentThemes: true }),
-  snapshotLoaderLayer,
-).pipe(
+const providedClientConnectionLayer = snapshotLoaderLayer.pipe(
+  Layer.provideMerge(
+    Connection.layerWithOptions({ environmentThemes: true, usageLimitSources: true }),
+  ),
   Layer.provideMerge(
     Layer.mergeAll(
       runtimeContextLayer,
diff --git a/apps/web/src/connection/storage.ts b/apps/web/src/connection/storage.ts
index 4ae476c1d11f..0a1183d48abd 100644
--- a/apps/web/src/connection/storage.ts
+++ b/apps/web/src/connection/storage.ts
@@ -6,6 +6,7 @@ import {
   ConnectionTargetStore,
   EMPTY_CONNECTION_CATALOG_DOCUMENT,
   EnvironmentCacheStore,
+  putRemoteDpopTokenInCatalog,
   registerConnectionInCatalog,
   removeCatalogValue,
   removeConnectionFromCatalog,
@@ -446,15 +447,7 @@ export const connectionStorageLayer = Layer.effectContext(
             ),
           ),
         ),
-      put: (token) =>
-        catalog.update((document) => ({
-          ...document,
-          remoteDpopTokens: replaceCatalogValue(
-            document.remoteDpopTokens,
-            (value) => value.environmentId,
-            token,
-          ),
-        })),
+      put: (token) => catalog.update((document) => putRemoteDpopTokenInCatalog(document, token)),
       remove: (environmentId) =>
         catalog.update((document) => ({
           ...document,
diff --git a/apps/web/src/environments/primary/auth.ts b/apps/web/src/environments/primary/auth.ts
index fe0345e41524..d76002a93298 100644
--- a/apps/web/src/environments/primary/auth.ts
+++ b/apps/web/src/environments/primary/auth.ts
@@ -353,6 +353,8 @@ export async function submitServerAuthCredential(credential: string): Promise<vo
 
   resolvedAuthenticatedGateState = null;
   await exchangeBootstrapCredential(trimmedCredential);
+  await waitForAuthenticatedSessionAfterBootstrap();
+  resolvedAuthenticatedGateState = { status: "authenticated" };
   bootstrapPromise = null;
   stripPairingTokenFromUrl();
 }
diff --git a/apps/web/src/filePathDisplay.test.ts b/apps/web/src/filePathDisplay.test.ts
index ecceea09ca1e..4c49133a3138 100644
--- a/apps/web/src/filePathDisplay.test.ts
+++ b/apps/web/src/filePathDisplay.test.ts
@@ -38,4 +38,10 @@ describe("formatWorkspaceRelativePath", () => {
       ),
     ).toBe("t3code/apps/web/src/session-logic.ts:501:9");
   });
+
+  it("keeps double-slash POSIX paths case-sensitive", () => {
+    expect(formatWorkspaceRelativePath("//tmp/project/probe.txt", "//tmp/Project")).toBe(
+      "//tmp/project/probe.txt",
+    );
+  });
 });
diff --git a/apps/web/src/filePathDisplay.ts b/apps/web/src/filePathDisplay.ts
index fc197a4092b5..36f5873cf8e0 100644
--- a/apps/web/src/filePathDisplay.ts
+++ b/apps/web/src/filePathDisplay.ts
@@ -4,6 +4,7 @@ import {
   splitFilePathPosition,
   stripSlashPrefixedWindowsDrive,
 } from "@t3tools/client-runtime/markdown-links";
+import { isWindowsAbsolutePath } from "@t3tools/shared/path";
 
 function normalizePathSeparators(path: string): string {
   return path.replaceAll("\\", "/");
@@ -30,10 +31,13 @@ export function formatWorkspaceRelativePath(
       normalizePathSeparators(trimTrailingPathSeparators(workspaceRoot)),
     );
     const workspaceLabel = fileBasename(normalizedWorkspaceRoot);
-    const pathForCompare = normalizedPath.toLowerCase();
-    const workspaceForCompare = normalizedWorkspaceRoot.toLowerCase();
+    const caseInsensitive = isWindowsAbsolutePath(stripSlashPrefixedWindowsDrive(workspaceRoot));
+    const pathForCompare = caseInsensitive ? normalizedPath.toLowerCase() : normalizedPath;
+    const workspaceForCompare = caseInsensitive
+      ? normalizedWorkspaceRoot.toLowerCase()
+      : normalizedWorkspaceRoot;
     const workspaceWithSeparator = `${workspaceForCompare}/`;
-    const workspaceLabelWithSeparator = `${workspaceLabel.toLowerCase()}/`;
+    const workspaceLabelWithSeparator = `${caseInsensitive ? workspaceLabel.toLowerCase() : workspaceLabel}/`;
 
     if (pathForCompare === workspaceForCompare) {
       displayPath = workspaceLabel;
diff --git a/apps/web/src/hooks/useCopyToClipboard.test.ts b/apps/web/src/hooks/useCopyToClipboard.test.ts
index ccac333cd488..0e0600c921ec 100644
--- a/apps/web/src/hooks/useCopyToClipboard.test.ts
+++ b/apps/web/src/hooks/useCopyToClipboard.test.ts
@@ -14,6 +14,7 @@ describe("writeTextToClipboard", () => {
   it("reports unavailable clipboard support with structural context", async () => {
     vi.stubGlobal("window", {});
     vi.stubGlobal("navigator", {});
+    vi.stubGlobal("document", undefined);
 
     const error = await writeTextToClipboard("plan contents", "plan").then(
       () => undefined,
@@ -27,6 +28,72 @@ describe("writeTextToClipboard", () => {
     expect((error as Error).message).not.toContain("plan contents");
   });
 
+  it.each(["success", "denied", "throws"] as const)(
+    "cleans up the Clipboard API fallback when copying %s",
+    async (result) => {
+      const focus = vi.fn();
+      const restoreFocus = vi.fn();
+      const appendChild = vi.fn();
+      const execCommand = vi.fn(() => {
+        if (result === "throws") throw new Error("copy command failed");
+        return result === "success";
+      });
+      const remove = vi.fn();
+      const select = vi.fn();
+      const setAttribute = vi.fn();
+      const setSelectionRange = vi.fn();
+      const textarea = {
+        focus,
+        remove,
+        select,
+        setAttribute,
+        setSelectionRange,
+        style: {},
+        value: "",
+      };
+
+      vi.stubGlobal("window", {});
+      vi.stubGlobal("navigator", {});
+      vi.stubGlobal("document", {
+        activeElement: { focus: restoreFocus },
+        body: { appendChild },
+        createElement: vi.fn(() => textarea),
+        execCommand,
+      });
+
+      const pendingCopy = writeTextToClipboard("remote command", "command");
+      // The fallback must run during the original user gesture, before any await.
+      expect(execCommand).toHaveBeenCalledWith("copy");
+      if (result === "success") {
+        await expect(pendingCopy).resolves.toBe(true);
+      } else {
+        await expect(pendingCopy).rejects.toBeInstanceOf(ClipboardApiUnavailableError);
+      }
+
+      expect(textarea.value).toBe("remote command");
+      expect(textarea.style).toMatchObject({ fontSize: "16px" });
+      expect(appendChild).toHaveBeenCalledWith(textarea);
+      expect(focus).toHaveBeenCalledWith({ preventScroll: true });
+      expect(select).toHaveBeenCalledOnce();
+      expect(setSelectionRange).toHaveBeenCalledWith(0, "remote command".length);
+      expect(remove).toHaveBeenCalledOnce();
+      expect(restoreFocus).toHaveBeenCalledOnce();
+    },
+  );
+
+  it("uses the Clipboard API without touching the fallback when it is available", async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    const execCommand = vi.fn();
+    vi.stubGlobal("window", {});
+    vi.stubGlobal("navigator", { clipboard: { writeText } });
+    vi.stubGlobal("document", { execCommand });
+
+    await expect(writeTextToClipboard("remote command", "command")).resolves.toBe(true);
+
+    expect(writeText).toHaveBeenCalledWith("remote command");
+    expect(execCommand).not.toHaveBeenCalled();
+  });
+
   it("preserves the exact clipboard failure without exposing copied contents", async () => {
     const cause = new Error("browser clipboard failure");
     const writeText = vi.fn().mockRejectedValue(cause);
@@ -47,12 +114,18 @@ describe("writeTextToClipboard", () => {
     expect((error as Error).message).not.toContain("secret clipboard contents");
   });
 
-  it("keeps empty values as a no-op when clipboard support is available", async () => {
-    const writeText = vi.fn();
-    vi.stubGlobal("window", {});
-    vi.stubGlobal("navigator", { clipboard: { writeText } });
+  it.each([true, false])(
+    "keeps empty values as a no-op with Clipboard API support: %s",
+    async (available) => {
+      const writeText = vi.fn();
+      vi.stubGlobal("window", {});
+      const execCommand = vi.fn();
+      vi.stubGlobal("navigator", available ? { clipboard: { writeText } } : {});
+      vi.stubGlobal("document", { execCommand });
 
-    await expect(writeTextToClipboard("", "plan")).resolves.toBe(false);
-    expect(writeText).not.toHaveBeenCalled();
-  });
+      await expect(writeTextToClipboard("", "plan")).resolves.toBe(false);
+      expect(writeText).not.toHaveBeenCalled();
+      expect(execCommand).not.toHaveBeenCalled();
+    },
+  );
 });
diff --git a/apps/web/src/hooks/useCopyToClipboard.ts b/apps/web/src/hooks/useCopyToClipboard.ts
index ef66410f7db4..8723aaeb941a 100644
--- a/apps/web/src/hooks/useCopyToClipboard.ts
+++ b/apps/web/src/hooks/useCopyToClipboard.ts
@@ -47,12 +47,40 @@ export class ClipboardReadError extends Schema.TaggedErrorClass<ClipboardReadErr
   }
 }
 
+/** Copy fallback for remote web pages served over plain HTTP. */
+function writeTextWithExecCommand(value: string): boolean {
+  if (typeof document === "undefined" || typeof document.execCommand !== "function") return false;
+
+  const textarea = document.createElement("textarea");
+  textarea.value = value;
+  textarea.setAttribute("readonly", "");
+  textarea.setAttribute("aria-hidden", "true");
+  textarea.style.position = "fixed";
+  textarea.style.top = "0";
+  textarea.style.left = "0";
+  textarea.style.opacity = "0";
+  textarea.style.fontSize = "16px";
+
+  const previouslyFocused = document.activeElement;
+  document.body.appendChild(textarea);
+  try {
+    textarea.focus({ preventScroll: true });
+    textarea.select();
+    textarea.setSelectionRange(0, value.length);
+    return document.execCommand("copy");
+  } catch {
+    return false;
+  } finally {
+    textarea.remove();
+    const restoreFocus = (previouslyFocused as { focus?: unknown } | null)?.focus;
+    if (typeof restoreFocus === "function") {
+      restoreFocus.call(previouslyFocused);
+    }
+  }
+}
+
 export async function writeTextToClipboard(value: string, target = "text") {
-  if (
-    typeof window === "undefined" ||
-    typeof navigator === "undefined" ||
-    !navigator.clipboard?.writeText
-  ) {
+  if (typeof window === "undefined") {
     throw new ClipboardApiUnavailableError({
       target,
     });
@@ -60,6 +88,13 @@ export async function writeTextToClipboard(value: string, target = "text") {
 
   if (!value) return false;
 
+  if (typeof navigator === "undefined" || !navigator.clipboard?.writeText) {
+    if (writeTextWithExecCommand(value)) return true;
+    throw new ClipboardApiUnavailableError({
+      target,
+    });
+  }
+
   try {
     await navigator.clipboard.writeText(value);
     return true;
diff --git a/apps/web/src/hooks/useLocalStorage.test.ts b/apps/web/src/hooks/useLocalStorage.test.ts
index 27627a36e4b0..495365dfdcce 100644
--- a/apps/web/src/hooks/useLocalStorage.test.ts
+++ b/apps/web/src/hooks/useLocalStorage.test.ts
@@ -55,9 +55,28 @@ describe("local storage errors", () => {
     }
   });
 
-  it("preserves decode failure context", async () => {
+  it("retries when access to browser storage becomes available", async () => {
+    const storage = createStorage();
+    storage.setItem("read-key", JSON.stringify("saved value"));
+    let blocked = true;
+    vi.stubGlobal("window", {
+      get localStorage() {
+        if (blocked) throw new Error("storage unavailable");
+        return storage;
+      },
+    });
+    const { getLocalStorageItem, LocalStorageOperationError } = await import("./useLocalStorage");
+
+    expect(() => getLocalStorageItem("read-key", Schema.String)).toThrow(
+      LocalStorageOperationError,
+    );
+    blocked = false;
+    expect(getLocalStorageItem("read-key", Schema.String)).toBe("saved value");
+  });
+
+  it.each(["", "not-json"])("preserves decode failure context for %j", async (value) => {
     const { getLocalStorageItem, LocalStorageOperationError } = await loadWithStorage(
-      createStorage({ getItem: () => "not-json" }),
+      createStorage({ getItem: () => value }),
     );
 
     try {
diff --git a/apps/web/src/hooks/useLocalStorage.ts b/apps/web/src/hooks/useLocalStorage.ts
index 3099e73ff43f..112715599484 100644
--- a/apps/web/src/hooks/useLocalStorage.ts
+++ b/apps/web/src/hooks/useLocalStorage.ts
@@ -15,26 +15,26 @@ export class LocalStorageOperationError extends Schema.TaggedErrorClass<LocalSto
   }
 }
 
-const isomorphicLocalStorage: Storage =
-  typeof window !== "undefined"
-    ? window.localStorage
-    : (function () {
-        const store = new Map<string, string>();
-        return {
-          clear: () => store.clear(),
-          getItem: (_) => store.get(_) ?? null,
-          key: (_) => Record.keys(store).at(_) ?? null,
-          get length() {
-            return store.size;
-          },
-          removeItem: (_) => store.delete(_),
-          setItem: (_, value) => store.set(_, value),
-        };
-      })();
+const fallbackStorage: Storage = (() => {
+  const store = new Map<string, string>();
+  return {
+    clear: () => store.clear(),
+    getItem: (_) => store.get(_) ?? null,
+    key: (_) => Record.keys(store).at(_) ?? null,
+    get length() {
+      return store.size;
+    },
+    removeItem: (_) => store.delete(_),
+    setItem: (_, value) => store.set(_, value),
+  };
+})();
+
+const getStorage = (): Storage =>
+  typeof window !== "undefined" ? window.localStorage : fallbackStorage;
 
 const read = (key: string) => {
   try {
-    return isomorphicLocalStorage.getItem(key);
+    return getStorage().getItem(key);
   } catch (cause) {
     throw new LocalStorageOperationError({ operation: "read", storageKey: key, cause });
   }
@@ -58,13 +58,13 @@ const encode = <T, E>(key: string, schema: Schema.Codec<T, E>, value: T) => {
 
 export const getLocalStorageItem = <T, E>(key: string, schema: Schema.Codec<T, E>): T | null => {
   const item = read(key);
-  return item ? decode(key, schema, item) : null;
+  return item === null ? null : decode(key, schema, item);
 };
 
 export const setLocalStorageItem = <T, E>(key: string, value: T, schema: Schema.Codec<T, E>) => {
   const valueToSet = encode(key, schema, value);
   try {
-    isomorphicLocalStorage.setItem(key, valueToSet);
+    getStorage().setItem(key, valueToSet);
   } catch (cause) {
     throw new LocalStorageOperationError({ operation: "write", storageKey: key, cause });
   }
@@ -72,7 +72,7 @@ export const setLocalStorageItem = <T, E>(key: string, value: T, schema: Schema.
 
 export const removeLocalStorageItem = (key: string) => {
   try {
-    isomorphicLocalStorage.removeItem(key);
+    getStorage().removeItem(key);
   } catch (cause) {
     throw new LocalStorageOperationError({ operation: "remove", storageKey: key, cause });
   }
diff --git a/apps/web/src/hooks/useOpenPanelPullRequestUrl.ts b/apps/web/src/hooks/useOpenPanelPullRequestUrl.ts
new file mode 100644
index 000000000000..ec5a6c043065
--- /dev/null
+++ b/apps/web/src/hooks/useOpenPanelPullRequestUrl.ts
@@ -0,0 +1,59 @@
+import { scopeProjectRef } from "@t3tools/client-runtime/environment";
+import { EnvironmentId, ProjectId, type ScopedThreadRef } from "@t3tools/contracts";
+import { useMemo } from "react";
+
+import {
+  readPullRequestDetailSnapshot,
+  resolveDisplayedPullRequestDetail,
+} from "../components/pullRequest/pullRequestDetail.logic";
+import { gitHubPullRequestBrowserUrl } from "../lib/openPullRequestLink";
+import { selectActiveRightPanelSurface, useRightPanelStore } from "../rightPanelStore";
+import { useProject } from "../state/entities";
+import { pullRequestEnvironment } from "../state/pullRequests";
+import { useEnvironmentQuery } from "../state/query";
+
+export function useOpenPanelPullRequestUrl(threadRef: ScopedThreadRef | null) {
+  const surface = useRightPanelStore((state) =>
+    selectActiveRightPanelSurface(state.byThreadKey, threadRef),
+  );
+  const reference = surface?.kind === "pull-request" ? surface : null;
+  const environmentId = reference?.environmentId
+    ? EnvironmentId.make(reference.environmentId)
+    : threadRef?.environmentId;
+  const project = useProject(
+    reference && environmentId
+      ? scopeProjectRef(environmentId, ProjectId.make(reference.projectId))
+      : null,
+  );
+  const detail = useEnvironmentQuery(
+    reference && environmentId
+      ? pullRequestEnvironment.detail({
+          environmentId,
+          input: {
+            projectId: ProjectId.make(reference.projectId),
+            repository: reference.repository,
+            number: reference.number,
+          },
+        })
+      : null,
+  ).data;
+  const cachedDetail = useMemo(
+    () =>
+      reference && environmentId
+        ? readPullRequestDetailSnapshot(
+            typeof window === "undefined" ? undefined : window.localStorage,
+            environmentId,
+            reference,
+          )
+        : null,
+    [environmentId, reference],
+  );
+  return reference
+    ? (resolveDisplayedPullRequestDetail({ live: detail, cached: cachedDetail, reference })?.url ??
+        gitHubPullRequestBrowserUrl(
+          project?.repositoryIdentity,
+          reference.repository,
+          reference.number,
+        ))
+    : undefined;
+}
diff --git a/apps/web/src/hooks/useSettings.test.ts b/apps/web/src/hooks/useSettings.test.ts
index 200e14241e13..d55424766883 100644
--- a/apps/web/src/hooks/useSettings.test.ts
+++ b/apps/web/src/hooks/useSettings.test.ts
@@ -3,12 +3,22 @@ import {
   ProviderDriverKind,
   ProviderInstanceId,
 } from "@t3tools/contracts";
-import { DEFAULT_CLIENT_SETTINGS } from "@t3tools/contracts/settings";
-import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import { DEFAULT_CLIENT_SETTINGS, type ClientSettings } from "@t3tools/contracts/settings";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const persistenceMocks = vi.hoisted(() => ({
+  getClientSettings: vi.fn<() => Promise<ClientSettings | null>>(),
+  setClientSettings: vi.fn<(settings: ClientSettings) => Promise<void>>(),
+}));
+
+vi.mock("~/localApi", () => ({
+  ensureLocalApi: () => ({ persistence: persistenceMocks }),
+}));
 
 import {
   __resetClientSettingsPersistenceForTests,
   __setClientSettingsForTests,
+  ensureClientSettingsHydrated,
   getClientSettings,
   mergeEnvironmentSettings,
   persistClientSettingsPatch,
@@ -17,9 +27,138 @@ import {
 } from "./useSettings";
 
 beforeEach(() => {
+  persistenceMocks.getClientSettings.mockReset().mockResolvedValue(null);
+  persistenceMocks.setClientSettings.mockReset().mockResolvedValue(undefined);
   __resetClientSettingsPersistenceForTests();
 });
 
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("client settings hydration", () => {
+  const savedSettings = {
+    ...DEFAULT_CLIENT_SETTINGS,
+    timestampFormat: "12-hour" as const,
+    favorites: [{ provider: ProviderInstanceId.make("codex_work"), model: "gpt-5.6" }],
+  };
+  const onboardingCompletedAt = "2026-09-05T12:00:00.000Z";
+  const complete = (current: ClientSettings) => ({ ...current, onboardingCompletedAt });
+
+  it("rejects completion after a failed read and preserves saved preferences on retry", async () => {
+    const failure = new Error("storage unavailable");
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    persistenceMocks.getClientSettings
+      .mockRejectedValueOnce(failure)
+      .mockResolvedValue(savedSettings);
+
+    await expect(persistClientSettingsUpdate(complete)).rejects.toBe(failure);
+    expect(persistenceMocks.setClientSettings).not.toHaveBeenCalled();
+    expect(getClientSettings()).toBe(DEFAULT_CLIENT_SETTINGS);
+
+    const completedSettings = { ...savedSettings, onboardingCompletedAt };
+    await expect(persistClientSettingsUpdate(complete)).resolves.toEqual(completedSettings);
+    expect(persistenceMocks.setClientSettings).toHaveBeenCalledExactlyOnceWith(completedSettings);
+    expect(persistenceMocks.getClientSettings).toHaveBeenCalledTimes(2);
+  });
+
+  it("uses defaults only after storage confirms no saved settings exist", async () => {
+    const completedSettings = { ...DEFAULT_CLIENT_SETTINGS, onboardingCompletedAt };
+
+    await expect(persistClientSettingsUpdate(complete)).resolves.toEqual(completedSettings);
+    expect(persistenceMocks.getClientSettings).toHaveBeenCalledOnce();
+    expect(persistenceMocks.setClientSettings).toHaveBeenCalledExactlyOnceWith(completedSettings);
+  });
+
+  it("holds patches until a pending read supplies the saved preferences", async () => {
+    let finishRead!: (settings: ClientSettings) => void;
+    persistenceMocks.getClientSettings.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          finishRead = resolve;
+        }),
+    );
+    const persisted = new Promise<ClientSettings>((resolve) => {
+      persistenceMocks.setClientSettings.mockImplementationOnce(async (settings) => {
+        resolve(settings);
+      });
+    });
+
+    const hydration = ensureClientSettingsHydrated();
+    persistClientSettingsPatch({ wordWrap: false });
+    expect(getClientSettings()).toBe(DEFAULT_CLIENT_SETTINGS);
+    expect(persistenceMocks.setClientSettings).not.toHaveBeenCalled();
+
+    finishRead(savedSettings);
+    await hydration;
+    await expect(persisted).resolves.toEqual({ ...savedSettings, wordWrap: false });
+    expect(persistenceMocks.getClientSettings).toHaveBeenCalledOnce();
+  });
+
+  it("handles failed patch reads without writing and retries with the saved preferences", async () => {
+    const failure = new Error("storage unavailable");
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    persistenceMocks.getClientSettings.mockRejectedValue(failure);
+
+    const hydration = ensureClientSettingsHydrated();
+    persistClientSettingsPatch({ wordWrap: false });
+    await expect(hydration).rejects.toBe(failure);
+    expect(persistenceMocks.setClientSettings).not.toHaveBeenCalled();
+
+    persistenceMocks.getClientSettings.mockResolvedValue(savedSettings);
+    const persisted = new Promise<ClientSettings>((resolve) => {
+      persistenceMocks.setClientSettings.mockImplementationOnce(async (settings) => {
+        resolve(settings);
+      });
+    });
+    persistClientSettingsPatch({ wordWrap: false });
+
+    await expect(persisted).resolves.toEqual({ ...savedSettings, wordWrap: false });
+  });
+
+  it("preserves patch order across hydration and a blocked completion write", async () => {
+    let finishRead!: (settings: ClientSettings) => void;
+    const read = new Promise<ClientSettings>((resolve) => {
+      finishRead = resolve;
+    });
+    persistenceMocks.getClientSettings.mockReturnValue(read);
+    let finishCompletionWrite!: () => void;
+    const blockedWrite = new Promise<void>((resolve) => {
+      finishCompletionWrite = resolve;
+    });
+    let signalCompletionWrite!: () => void;
+    const completionWriteStarted = new Promise<void>((resolve) => {
+      signalCompletionWrite = resolve;
+    });
+    let durableSettings: ClientSettings = savedSettings;
+    const persist = vi
+      .fn<(settings: ClientSettings) => Promise<void>>()
+      .mockImplementationOnce(async (settings) => {
+        signalCompletionWrite();
+        await blockedWrite;
+        durableSettings = settings;
+      })
+      .mockImplementation(async (settings) => {
+        durableSettings = settings;
+      });
+
+    const completion = persistClientSettingsUpdate(complete, persist);
+    persistClientSettingsPatch({ wordWrap: false }, persist);
+    finishRead(savedSettings);
+    await completionWriteStarted;
+    persistClientSettingsPatch({ wordWrap: true }, persist);
+    const finalWrite = persistClientSettingsUpdate((current) => current, persist);
+
+    finishCompletionWrite();
+    await completion;
+    await finalWrite;
+
+    const expected = { ...savedSettings, onboardingCompletedAt, wordWrap: true };
+    expect(getClientSettings()).toEqual(expected);
+    expect(durableSettings).toEqual(expected);
+  });
+});
+
 describe("persistClientSettingsUpdate", () => {
   it("publishes the update only after persistence succeeds", async () => {
     let finishPersistence!: () => void;
@@ -245,3 +384,40 @@ describe("mergeEnvironmentSettings", () => {
     expect(settings.sidebarAutoSettleOnMerge).toBe(false);
   });
 });
+
+describe("onboarding completion persistence", () => {
+  it("keeps onboarding incomplete after a failed save and preserves preferences on retry", async () => {
+    const failure = new Error("disk full");
+    const persist = vi
+      .fn<(settings: typeof DEFAULT_CLIENT_SETTINGS) => Promise<void>>()
+      .mockRejectedValueOnce(failure)
+      .mockResolvedValue(undefined);
+    const existingSettings = {
+      ...DEFAULT_CLIENT_SETTINGS,
+      timestampFormat: "12-hour" as const,
+      favorites: [
+        {
+          provider: ProviderInstanceId.make("codex_work"),
+          model: "gpt-5.6",
+        },
+      ],
+    };
+    __setClientSettingsForTests(existingSettings);
+    const onboardingCompletedAt = "2026-09-01T12:00:00.000Z";
+    const complete = (current: typeof DEFAULT_CLIENT_SETTINGS) => ({
+      ...current,
+      onboardingCompletedAt,
+    });
+
+    await expect(persistClientSettingsUpdate(complete, persist)).rejects.toBe(failure);
+    expect(getClientSettings()).toBe(existingSettings);
+    expect(getClientSettings().onboardingCompletedAt).toBeNull();
+
+    const completedSettings = { ...existingSettings, onboardingCompletedAt };
+    await expect(persistClientSettingsUpdate(complete, persist)).resolves.toEqual(
+      completedSettings,
+    );
+    expect(getClientSettings()).toEqual(completedSettings);
+    expect(persist).toHaveBeenLastCalledWith(completedSettings);
+  });
+});
diff --git a/apps/web/src/hooks/useSettings.ts b/apps/web/src/hooks/useSettings.ts
index bed80616e4a8..9b428b08ea50 100644
--- a/apps/web/src/hooks/useSettings.ts
+++ b/apps/web/src/hooks/useSettings.ts
@@ -26,6 +26,7 @@ import {
 } from "@t3tools/contracts/settings";
 import { safeErrorLogAttributes } from "@t3tools/client-runtime/errors";
 import {
+  filterSharedServerPatch,
   findSharedSettingsMismatches,
   pickSharedServerSettings,
   splitSharedServerPatch,
@@ -53,11 +54,13 @@ type UnifiedSettingsPatch = ServerSettingsPatch & ClientSettingsPatch;
 
 const clientSettingsListeners = new Set<() => void>();
 const clientSettingsHydrationListeners = new Set<() => void>();
+type ClientSettingsHydrationStatus = "pending" | "ready" | "failed" | "retrying";
 let clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
-let clientSettingsHydrated = false;
+let clientSettingsHydrationStatus: ClientSettingsHydrationStatus = "pending";
 let clientSettingsHydrationPromise: Promise<void> | null = null;
 let clientSettingsHydrationGeneration = 0;
 let clientSettingsPersistenceQueue: Promise<void> = Promise.resolve();
+let deferredClientSettingsPatchCount = 0;
 
 function emitClientSettingsChange() {
   for (const listener of clientSettingsListeners) {
@@ -80,36 +83,40 @@ function replaceClientSettingsSnapshot(settings: ClientSettings): void {
   emitClientSettingsChange();
 }
 
-function setClientSettingsHydrated(nextHydrated: boolean): void {
-  if (clientSettingsHydrated === nextHydrated) {
+function setClientSettingsHydrationStatus(nextStatus: ClientSettingsHydrationStatus): void {
+  if (clientSettingsHydrationStatus === nextStatus) {
     return;
   }
-  clientSettingsHydrated = nextHydrated;
+  clientSettingsHydrationStatus = nextStatus;
   emitClientSettingsHydrationChange();
 }
 
 function subscribeClientSettings(listener: () => void): () => void {
   clientSettingsListeners.add(listener);
-  void hydrateClientSettings();
+  void hydrateClientSettings().catch(() => undefined);
   return () => {
     clientSettingsListeners.delete(listener);
   };
 }
 
 function getClientSettingsHydratedSnapshot(): boolean {
-  return clientSettingsHydrated;
+  return clientSettingsHydrationStatus === "ready";
+}
+
+function getClientSettingsHydrationStatusSnapshot(): ClientSettingsHydrationStatus {
+  return clientSettingsHydrationStatus;
 }
 
 function subscribeClientSettingsHydration(listener: () => void): () => void {
   clientSettingsHydrationListeners.add(listener);
-  void hydrateClientSettings();
+  void hydrateClientSettings().catch(() => undefined);
   return () => {
     clientSettingsHydrationListeners.delete(listener);
   };
 }
 
 async function hydrateClientSettings(): Promise<void> {
-  if (clientSettingsHydrated) {
+  if (clientSettingsHydrationStatus === "ready") {
     return;
   }
   if (clientSettingsHydrationPromise) {
@@ -117,6 +124,11 @@ async function hydrateClientSettings(): Promise<void> {
   }
 
   const hydrationGeneration = clientSettingsHydrationGeneration;
+  setClientSettingsHydrationStatus(
+    clientSettingsHydrationStatus === "failed" || clientSettingsHydrationStatus === "retrying"
+      ? "retrying"
+      : "pending",
+  );
   const nextHydration = (async () => {
     try {
       const persistedSettings = await ensureLocalApi().persistence.getClientSettings();
@@ -126,15 +138,16 @@ async function hydrateClientSettings(): Promise<void> {
       if (persistedSettings) {
         replaceClientSettingsSnapshot({ ...DEFAULT_CLIENT_SETTINGS, ...persistedSettings });
       }
+      setClientSettingsHydrationStatus("ready");
     } catch (error) {
+      if (hydrationGeneration === clientSettingsHydrationGeneration) {
+        setClientSettingsHydrationStatus("failed");
+      }
       console.error(`${CLIENT_SETTINGS_PERSISTENCE_ERROR_SCOPE} hydrate failed`, {
         operation: "hydrate",
         ...safeErrorLogAttributes(error),
       });
-    } finally {
-      if (hydrationGeneration === clientSettingsHydrationGeneration) {
-        setClientSettingsHydrated(true);
-      }
+      throw error;
     }
   })();
 
@@ -164,15 +177,32 @@ export function persistClientSettingsPatch(
   patch: ClientSettingsPatch,
   persist: (settings: ClientSettings) => Promise<void> = defaultClientSettingsPersistence,
 ): void {
-  replaceClientSettingsSnapshot({ ...getClientSettingsSnapshot(), ...patch });
-  void enqueueClientSettingsPersistence(() => persist(getClientSettingsSnapshot())).catch(
-    (error) => {
-      console.error(`${CLIENT_SETTINGS_PERSISTENCE_ERROR_SCOPE} persist failed`, {
-        operation: "persist",
-        ...safeErrorLogAttributes(error),
-      });
-    },
-  );
+  // Patches queued before hydration must publish before newer optimistic patches.
+  const deferPatch =
+    clientSettingsHydrationStatus !== "ready" || deferredClientSettingsPatchCount > 0;
+  if (deferPatch) {
+    deferredClientSettingsPatchCount += 1;
+  } else {
+    replaceClientSettingsSnapshot({ ...getClientSettingsSnapshot(), ...patch });
+  }
+  void enqueueClientSettingsPersistence(async () => {
+    if (deferPatch) {
+      try {
+        if (clientSettingsHydrationStatus !== "ready") {
+          await hydrateClientSettings();
+        }
+        replaceClientSettingsSnapshot({ ...getClientSettingsSnapshot(), ...patch });
+      } finally {
+        deferredClientSettingsPatchCount -= 1;
+      }
+    }
+    await persist(getClientSettingsSnapshot());
+  }).catch((error) => {
+    console.error(`${CLIENT_SETTINGS_PERSISTENCE_ERROR_SCOPE} persist failed`, {
+      operation: "persist",
+      ...safeErrorLogAttributes(error),
+    });
+  });
 }
 
 /**
@@ -186,6 +216,9 @@ export async function persistClientSettingsUpdate(
   persist: (settings: ClientSettings) => Promise<void> = defaultClientSettingsPersistence,
 ): Promise<ClientSettings> {
   return enqueueClientSettingsPersistence(async () => {
+    if (clientSettingsHydrationStatus !== "ready") {
+      await hydrateClientSettings();
+    }
     for (;;) {
       const current = getClientSettingsSnapshot();
       const next = update(current);
@@ -233,7 +266,9 @@ export function getClientSettings(): ClientSettings {
 }
 
 /**
- * Resolves once client settings have been read from disk.
+ * Resolves after settings load or storage confirms no saved settings exist.
+ * Failed reads reject and remain retryable. They must not allow defaults to
+ * overwrite saved preferences.
  *
  * The pre-hydration snapshot is just the schema defaults, so imperative paths
  * that open a preview must await this or they bake the built-in viewport, zoom
@@ -251,6 +286,14 @@ export function useClientSettingsHydrated(): boolean {
   );
 }
 
+export function useClientSettingsHydrationStatus(): ClientSettingsHydrationStatus {
+  return useSyncExternalStore(
+    subscribeClientSettingsHydration,
+    getClientSettingsHydrationStatusSnapshot,
+    () => "pending",
+  );
+}
+
 function useClientSettingsValue(): ClientSettings {
   return useSyncExternalStore(
     subscribeClientSettings,
@@ -368,18 +411,6 @@ export function usePrimarySettingsAvailable(): boolean {
   return primaryEnvironment !== null || !isHostedStaticApp();
 }
 
-/** Environments that can receive a shared settings write right now. */
-function useSharedSettingsSyncTargetIds(): ReadonlyArray<EnvironmentId> {
-  const { environments } = useEnvironments();
-  return useMemo(
-    () =>
-      environments
-        .filter(supportsSharedSettingsSync)
-        .map((environment) => environment.environmentId),
-    [environments],
-  );
-}
-
 /**
  * Returns an updater that routes each key to the correct backing store.
  *
@@ -394,7 +425,7 @@ function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
     serverEnvironment.updateSettings,
     "server settings update",
   );
-  const sharedSettingsSyncTargetIds = useSharedSettingsSyncTargetIds();
+  const { environments } = useEnvironments();
   const updateSettings = useCallback(
     (patch: UnifiedSettingsPatch) => {
       const { serverPatch, clientPatch } = splitPatch(patch);
@@ -402,11 +433,11 @@ function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
       if (Object.keys(serverPatch).length > 0) {
         const { sharedPatch, localPatch } = splitSharedServerPatch(serverPatch);
         // Dropping the write silently leaves the control looking saved.
-        const warnUnsaved = () =>
+        const warnUnsaved = (description = PRIMARY_SETTINGS_UNAVAILABLE_MESSAGE) =>
           toastManager.add({
             type: "warning",
             title: "Setting not saved",
-            description: PRIMARY_SETTINGS_UNAVAILABLE_MESSAGE,
+            description,
           });
         if (Object.keys(localPatch).length > 0) {
           if (environmentId) {
@@ -419,26 +450,38 @@ function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
           }
         }
         if (Object.keys(sharedPatch).length > 0) {
-          const targets = new Set(sharedSettingsSyncTargetIds);
+          const targets = new Set(
+            environments.filter(supportsSharedSettingsSync).map((target) => target.environmentId),
+          );
           if (environmentId) {
             targets.add(environmentId);
           }
-          if (targets.size === 0) {
-            warnUnsaved();
-          }
+          let wroteToTarget = false;
           for (const targetId of targets) {
+            const target = environments.find((candidate) => candidate.environmentId === targetId);
+            const targetPatch = filterSharedServerPatch(
+              sharedPatch,
+              target?.serverConfig?.environment.capabilities,
+            );
+            if (Object.keys(targetPatch).length === 0) continue;
+            wroteToTarget = true;
             void persistServerSettings({
               environmentId: targetId,
-              input: { patch: sharedPatch },
+              input: { patch: targetPatch },
             });
           }
+          if (!wroteToTarget) {
+            warnUnsaved(
+              targets.size > 0 ? "Update older servers to save this setting." : undefined,
+            );
+          }
         }
       }
       if (Object.keys(clientPatch).length > 0) {
         persistClientSettingsPatch(clientPatch);
       }
     },
-    [environmentId, persistServerSettings, sharedSettingsSyncTargetIds],
+    [environmentId, environments, persistServerSettings],
   );
 
   return updateSettings;
@@ -453,6 +496,7 @@ function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
 export function useSharedSettingsSync() {
   const primaryEnvironment = usePrimaryEnvironment();
   const primaryEnvironmentId = primaryEnvironment?.environmentId ?? null;
+  const primaryCapabilities = primaryEnvironment?.serverConfig?.environment.capabilities;
   // Read the loaded config, not `primaryServerSettingsAtom`: that atom falls
   // back to defaults while the primary is disconnected, and "apply to all"
   // must never push defaults over real values. Same for a primary too old to
@@ -472,28 +516,35 @@ export function useSharedSettingsSync() {
       findSharedSettingsMismatches({
         primaryEnvironmentId,
         primarySettings,
+        primaryCapabilities,
         environments: environments.map((environment) => ({
           environmentId: environment.environmentId,
           label: environment.label,
           syncEligible: supportsSharedSettingsSync(environment),
           settings: environment.serverConfig?.settings ?? null,
+          capabilities: environment.serverConfig?.environment.capabilities,
         })),
       }),
-    [environments, primaryEnvironmentId, primarySettings],
+    [environments, primaryEnvironmentId, primarySettings, primaryCapabilities],
   );
 
   const applyToAll = useCallback(() => {
     if (primarySettings === null) {
       return;
     }
-    const patch = pickSharedServerSettings(primarySettings);
+    const patch = pickSharedServerSettings(primarySettings, primaryCapabilities);
     for (const mismatch of mismatches) {
+      const target = environments.find(
+        (candidate) => candidate.environmentId === mismatch.environmentId,
+      );
       void persistServerSettings({
         environmentId: mismatch.environmentId,
-        input: { patch },
+        input: {
+          patch: filterSharedServerPatch(patch, target?.serverConfig?.environment.capabilities),
+        },
       });
     }
-  }, [mismatches, persistServerSettings, primarySettings]);
+  }, [environments, mismatches, persistServerSettings, primarySettings, primaryCapabilities]);
 
   return { mismatches, applyToAll };
 }
@@ -515,9 +566,10 @@ export function useUpdateClientSettings() {
 export function __resetClientSettingsPersistenceForTests(): void {
   clientSettingsHydrationGeneration += 1;
   clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
-  clientSettingsHydrated = false;
+  clientSettingsHydrationStatus = "pending";
   clientSettingsHydrationPromise = null;
   clientSettingsPersistenceQueue = Promise.resolve();
+  deferredClientSettingsPatchCount = 0;
   clientSettingsListeners.clear();
   clientSettingsHydrationListeners.clear();
 }
@@ -525,6 +577,6 @@ export function __resetClientSettingsPersistenceForTests(): void {
 export function __setClientSettingsForTests(settings: ClientSettings): void {
   clientSettingsHydrationGeneration += 1;
   clientSettingsSnapshot = settings;
-  clientSettingsHydrated = true;
+  clientSettingsHydrationStatus = "ready";
   clientSettingsHydrationPromise = null;
 }
diff --git a/apps/web/src/hooks/useTheme.test.ts b/apps/web/src/hooks/useTheme.test.ts
index ab87388ff298..9a1748dc4d24 100644
--- a/apps/web/src/hooks/useTheme.test.ts
+++ b/apps/web/src/hooks/useTheme.test.ts
@@ -204,3 +204,200 @@ describe("theme failure handling", () => {
     }
   });
 });
+
+describe("onboarding theme", () => {
+  it("clears custom palettes and restores the latest selected theme", async () => {
+    const storage = createStorage();
+    const classes = new Set<string>();
+    const styleValues = new Map<string, string>();
+    const root = {
+      classList: {
+        add: (name: string) => classes.add(name),
+        remove: (name: string) => classes.delete(name),
+        toggle: (name: string, force?: boolean) => {
+          const next = force ?? !classes.has(name);
+          if (next) classes.add(name);
+          else classes.delete(name);
+          return next;
+        },
+      },
+      dataset: {} as Record<string, string>,
+      offsetHeight: 0,
+      style: {
+        backgroundColor: "",
+        removeProperty: (name: string) => styleValues.delete(name),
+        setProperty: (name: string, value: string) => styleValues.set(name, value),
+      },
+    };
+    vi.doMock("react", () => ({
+      useCallback: <A>(callback: A) => callback,
+      useEffect: () => undefined,
+      useSyncExternalStore: (
+        subscribe: (listener: () => void) => () => void,
+        getSnapshot: () => unknown,
+      ) => {
+        subscribe(() => undefined);
+        return getSnapshot();
+      },
+    }));
+    vi.stubGlobal("window", {
+      addEventListener: () => undefined,
+      localStorage: storage,
+      matchMedia: () => ({
+        matches: false,
+        addEventListener: () => undefined,
+        removeEventListener: () => undefined,
+      }),
+      removeEventListener: () => undefined,
+    });
+    vi.stubGlobal("document", {
+      body: { style: { backgroundColor: "" } },
+      createElement: () => ({ name: "", setAttribute: () => undefined }),
+      documentElement: root,
+      head: { append: () => undefined },
+      querySelector: () => null,
+      querySelectorAll: () => [],
+    });
+    vi.stubGlobal("getComputedStyle", () => ({
+      backgroundColor: "rgb(0, 0, 0)",
+      getPropertyValue: () => "",
+    }));
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+      callback(0);
+      return 0;
+    });
+
+    const { EMBER_THEME, installCustomTheme } = await import("../themePalette");
+    const firstTheme = installCustomTheme({
+      ...EMBER_THEME,
+      id: "first-custom",
+      label: "First Custom",
+    });
+    const secondTheme = installCustomTheme({
+      ...EMBER_THEME,
+      id: "second-custom",
+      label: "Second Custom",
+      colors: { ...EMBER_THEME.colors, error: "#123456" },
+    });
+    storage.setItem("t3code:theme", firstTheme.id);
+
+    const { mountOnboardingTheme, useTheme } = await import("./useTheme");
+    expect(root.dataset.themeId).toBe(firstTheme.id);
+    expect(styleValues.get("--app-theme-error")).toBe(firstTheme.colors.error);
+
+    const cleanup = mountOnboardingTheme();
+    expect(root.dataset.themeId).toBeUndefined();
+    expect(styleValues.size).toBe(0);
+
+    expect(useTheme().setTheme(secondTheme.id)).toBe(true);
+    expect(root.dataset.themeId).toBeUndefined();
+    expect(styleValues.size).toBe(0);
+
+    cleanup();
+    expect(root.dataset.themeId).toBe(secondTheme.id);
+    expect(styleValues.get("--app-theme-error")).toBe(secondTheme.colors.error);
+  });
+
+  it("stays dark during storage changes and restores the latest saved theme", async () => {
+    const storage = createStorage();
+    storage.setItem("t3code:theme", "light");
+    const classes = new Set<string>();
+    const styleValues = new Map<string, string>();
+    const style = {
+      backgroundColor: "",
+      removeProperty: (name: string) => styleValues.delete(name),
+      setProperty: (name: string, value: string) => styleValues.set(name, value),
+    };
+    const root = {
+      classList: {
+        add: (name: string) => classes.add(name),
+        contains: (name: string) => classes.has(name),
+        remove: (name: string) => classes.delete(name),
+        toggle: (name: string, force?: boolean) => {
+          const next = force ?? !classes.has(name);
+          if (next) classes.add(name);
+          else classes.delete(name);
+          return next;
+        },
+      },
+      dataset: {} as Record<string, string>,
+      offsetHeight: 0,
+      style,
+    };
+    const body = { style: { backgroundColor: "" } };
+    let storageHandler: ((event: StorageEvent) => void) | undefined;
+    const setDesktopTheme = vi.fn().mockResolvedValue(undefined);
+    vi.doMock("react", () => ({
+      useCallback: <A>(callback: A) => callback,
+      useEffect: () => undefined,
+      useSyncExternalStore: (
+        subscribe: (listener: () => void) => () => void,
+        getSnapshot: () => unknown,
+      ) => {
+        subscribe(() => undefined);
+        return getSnapshot();
+      },
+    }));
+    vi.stubGlobal("window", {
+      addEventListener: (type: string, listener: (event: StorageEvent) => void) => {
+        if (type === "storage") storageHandler = listener;
+      },
+      localStorage: storage,
+      matchMedia: () => ({
+        matches: false,
+        addEventListener: () => undefined,
+        removeEventListener: () => undefined,
+      }),
+      removeEventListener: () => undefined,
+      desktopBridge: { setTheme: setDesktopTheme },
+    });
+    vi.stubGlobal("document", {
+      body,
+      createElement: () => ({ name: "", setAttribute: () => undefined }),
+      documentElement: root,
+      head: { append: () => undefined },
+      querySelector: () => null,
+      querySelectorAll: () => [],
+    });
+    vi.stubGlobal("getComputedStyle", () => ({
+      backgroundColor:
+        root.dataset.onboardingSurface !== undefined
+          ? "rgb(0, 0, 0)"
+          : classes.has("dark")
+            ? "rgb(10, 10, 10)"
+            : "rgb(255, 255, 255)",
+      getPropertyValue: () => "",
+    }));
+    vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+      callback(0);
+      return 0;
+    });
+
+    const { mountOnboardingTheme, useTheme } = await import("./useTheme");
+    expect(useTheme().resolvedTheme).toBe("light");
+    const cleanup = mountOnboardingTheme();
+
+    expect(root.dataset.onboardingSurface).toBe("");
+    expect(classes.has("dark")).toBe(true);
+    expect(root.style.backgroundColor).toBe("#000");
+    expect(body.style.backgroundColor).toBe("#000");
+    expect(useTheme().resolvedTheme).toBe("dark");
+    expect(setDesktopTheme).toHaveBeenLastCalledWith("dark");
+
+    storage.setItem("t3code:theme", "dark");
+    storageHandler?.({ key: "t3code:theme" } as StorageEvent);
+    storage.setItem("t3code:theme", "light");
+    storageHandler?.({ key: "t3code:theme" } as StorageEvent);
+    expect(classes.has("dark")).toBe(true);
+    expect(useTheme().resolvedTheme).toBe("dark");
+
+    cleanup();
+    expect(root.dataset.onboardingSurface).toBeUndefined();
+    expect(classes.has("dark")).toBe(false);
+    expect(root.style.backgroundColor).toBe("rgb(255, 255, 255)");
+    expect(body.style.backgroundColor).toBe("rgb(255, 255, 255)");
+    expect(storage.getItem("t3code:theme")).toBe("light");
+    expect(useTheme().resolvedTheme).toBe("light");
+    expect(setDesktopTheme).toHaveBeenLastCalledWith("light");
+  });
+});
diff --git a/apps/web/src/hooks/useTheme.ts b/apps/web/src/hooks/useTheme.ts
index 726a03dac7b8..01928552acb0 100644
--- a/apps/web/src/hooks/useTheme.ts
+++ b/apps/web/src/hooks/useTheme.ts
@@ -98,6 +98,14 @@ function readStoredThemeHalvesRaw(): { light?: string; dark?: string } {
 function themeHalvesSignature(halves: ThemeHalves | null): string {
   return `${halves?.light ?? ""}|${halves?.dark ?? ""}`;
 }
+
+function isOnboardingThemeActive(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.dataset?.onboardingSurface !== undefined
+  );
+}
+
 const THEME_COLOR_META_NAME = "theme-color";
 const DYNAMIC_THEME_COLOR_SELECTOR = `meta[name="${THEME_COLOR_META_NAME}"][data-dynamic-theme-color="true"]`;
 
@@ -292,15 +300,19 @@ function resolveBrowserChromeSurface(): HTMLElement {
 
 export function syncBrowserChromeTheme() {
   if (typeof document === "undefined" || typeof getComputedStyle === "undefined") return;
+  const onboardingActive = isOnboardingThemeActive();
   const rootStyles = getComputedStyle(document.documentElement);
-  const themeChromeColor = document.documentElement.dataset.themeId
-    ? normalizeThemeColor(rootStyles.getPropertyValue("--app-chrome-background"))
-    : null;
+  const themeChromeColor =
+    !onboardingActive && document.documentElement.dataset.themeId
+      ? normalizeThemeColor(rootStyles.getPropertyValue("--app-chrome-background"))
+      : null;
   const surfaceColor = normalizeThemeColor(
     getComputedStyle(resolveBrowserChromeSurface()).backgroundColor,
   );
   const fallbackColor = normalizeThemeColor(getComputedStyle(document.body).backgroundColor);
-  const backgroundColor = themeChromeColor ?? surfaceColor ?? fallbackColor;
+  const backgroundColor = onboardingActive
+    ? "#000"
+    : (themeChromeColor ?? surfaceColor ?? fallbackColor);
   if (!backgroundColor) return;
 
   document.documentElement.style.backgroundColor = backgroundColor;
@@ -321,8 +333,15 @@ export function syncBrowserChromeTheme() {
 
 function applyTheme(theme: Theme, { suppressTransitions = false, preservePreview = true } = {}) {
   if (typeof document === "undefined" || typeof window === "undefined") return;
+  const onboardingActive = isOnboardingThemeActive();
   // Keep the editor's draft visible until an explicit refresh restores the selection.
-  if (preservePreview && document.documentElement.dataset?.themeId === THEME_PREVIEW_ID) return;
+  if (
+    preservePreview &&
+    !onboardingActive &&
+    document.documentElement.dataset?.themeId === THEME_PREVIEW_ID
+  ) {
+    return;
+  }
   const appearanceMode = readAppearanceModePreference(theme);
   const followSystem = appearanceMode === "system";
   const systemDark = followSystem ? getSystemDark() : false;
@@ -334,7 +353,13 @@ function applyTheme(theme: Theme, { suppressTransitions = false, preservePreview
     lastAppliedTheme.appearanceMode === appearanceMode &&
     themeHalvesSignature(lastAppliedTheme.themeHalves) === themeHalvesSignature(themeHalves)
   ) {
-    syncDesktopTheme(theme, followSystem, appearanceMode);
+    if (onboardingActive) {
+      document.documentElement.classList.add("dark");
+      syncBrowserChromeTheme();
+      syncDesktopTheme("dark", false, "dark");
+    } else {
+      syncDesktopTheme(theme, followSystem, appearanceMode);
+    }
     return;
   }
 
@@ -348,12 +373,19 @@ function applyTheme(theme: Theme, { suppressTransitions = false, preservePreview
     appearanceMode,
     themeHalves,
   );
-  applyThemePalette(resolveThemeHalf(theme, themeHalves, resolvedAppearance), resolvedAppearance);
-  const isDark = resolvedAppearance === "dark";
-  document.documentElement.classList.toggle("dark", isDark);
+  if (onboardingActive) {
+    document.documentElement.classList.add("dark");
+  } else {
+    applyThemePalette(resolveThemeHalf(theme, themeHalves, resolvedAppearance), resolvedAppearance);
+    document.documentElement.classList.toggle("dark", resolvedAppearance === "dark");
+  }
   lastAppliedTheme = { theme, systemDark, followSystem, appearanceMode, themeHalves };
   syncBrowserChromeTheme();
-  syncDesktopTheme(theme, followSystem, appearanceMode);
+  if (onboardingActive) {
+    syncDesktopTheme("dark", false, "dark");
+  } else {
+    syncDesktopTheme(theme, followSystem, appearanceMode);
+  }
   if (suppressTransitions) {
     // Force a reflow so the no-transitions class takes effect before removal
     void document.documentElement.offsetHeight;
@@ -363,6 +395,28 @@ function applyTheme(theme: Theme, { suppressTransitions = false, preservePreview
   }
 }
 
+/** Own the document-wide dark palette used by the first-run wizard and its portals. */
+export function mountOnboardingTheme(): () => void {
+  if (typeof document === "undefined" || typeof window === "undefined") return () => {};
+
+  const root = document.documentElement;
+  applyThemePalette("dark", "dark");
+  root.dataset.onboardingSurface = "";
+  root.classList.add("dark");
+  syncBrowserChromeTheme();
+  syncDesktopTheme("dark", false, "dark");
+  emitChange();
+
+  return () => {
+    delete root.dataset.onboardingSurface;
+    root.style.backgroundColor = "";
+    document.body.style.backgroundColor = "";
+    lastAppliedTheme = null;
+    applyTheme(getStored(), { suppressTransitions: true, preservePreview: false });
+    emitChange();
+  };
+}
+
 export async function syncDesktopThemePreference(
   bridge: DesktopThemeBridge,
   theme: Theme,
@@ -424,13 +478,9 @@ function getSnapshot(): ThemeSnapshot {
   const systemDark = followSystem ? getSystemDark() : false;
   const themeHalves = readStoredThemeHalves();
 
-  const resolvedTheme = resolveThemeAppearance(
-    theme,
-    systemDark,
-    followSystem,
-    appearanceMode,
-    themeHalves,
-  );
+  const resolvedTheme = isOnboardingThemeActive()
+    ? "dark"
+    : resolveThemeAppearance(theme, systemDark, followSystem, appearanceMode, themeHalves);
   if (
     lastSnapshot &&
     lastSnapshot.theme === theme &&
diff --git a/apps/web/src/hooks/useThreadActions.test.ts b/apps/web/src/hooks/useThreadActions.test.ts
index e2a8b6d1b4b1..b042f19893da 100644
--- a/apps/web/src/hooks/useThreadActions.test.ts
+++ b/apps/web/src/hooks/useThreadActions.test.ts
@@ -1,7 +1,40 @@
 import { EnvironmentId, ThreadId } from "@t3tools/contracts";
-import { describe, expect, it } from "vite-plus/test";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
-import { requestThreadUnpinConfirmation, ThreadArchiveBlockedError } from "./useThreadActions";
+import {
+  navigateAfterThreadDeletion,
+  requestThreadUnpinConfirmation,
+  ThreadArchiveBlockedError,
+} from "./useThreadActions";
+import { toastManager } from "../components/ui/toast";
+
+describe("navigateAfterThreadDeletion", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("reports a rejected navigation without failing the completed deletion", async () => {
+    const addToast = vi.spyOn(toastManager, "add").mockReturnValue("navigation-error");
+
+    await expect(
+      navigateAfterThreadDeletion(() => Promise.reject(new Error("route unavailable"))),
+    ).resolves.toBeUndefined();
+
+    expect(addToast).toHaveBeenCalledOnce();
+    expect(addToast).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: "Thread deleted, but navigation failed",
+        description: "route unavailable",
+      }),
+    );
+  });
+
+  it("does not report an error after successful navigation", async () => {
+    const addToast = vi.spyOn(toastManager, "add");
+
+    await navigateAfterThreadDeletion(() => Promise.resolve());
+
+    expect(addToast).not.toHaveBeenCalled();
+  });
+});
 
 describe("ThreadArchiveBlockedError", () => {
   it("keeps the blocked thread context with the fixed message", () => {
diff --git a/apps/web/src/hooks/useThreadActions.ts b/apps/web/src/hooks/useThreadActions.ts
index 64915228c779..9b162bc8cce3 100644
--- a/apps/web/src/hooks/useThreadActions.ts
+++ b/apps/web/src/hooks/useThreadActions.ts
@@ -144,6 +144,21 @@ export async function requestThreadUnpinConfirmation(input: {
   );
 }
 
+/** Report navigation separately so a completed deletion can still finish worktree cleanup. */
+export async function navigateAfterThreadDeletion(navigate: () => Promise<void>) {
+  const result = await settlePromise(navigate);
+  if (result._tag === "Failure") {
+    const error = squashAtomCommandFailure(result);
+    toastManager.add(
+      stackedThreadToast({
+        type: "error",
+        title: "Thread deleted, but navigation failed",
+        description: error instanceof Error ? error.message : "An error occurred.",
+      }),
+    );
+  }
+}
+
 export function useThreadActions() {
   const closeTerminal = useAtomCommand(terminalEnvironment.close);
   const archiveThreadMutation = useAtomCommand(threadEnvironment.archive, {
@@ -383,39 +398,20 @@ export function useThreadActions() {
       clearTerminalUiState(threadRef);
 
       if (shouldNavigateToFallback) {
-        if (fallbackThreadId) {
-          const fallbackThread = readThreadShell(
-            scopeThreadRef(threadRef.environmentId, fallbackThreadId),
-          );
-          if (fallbackThread) {
-            const navigationResult = await settlePromise(() =>
-              router.navigate({
+        const fallbackThread = fallbackThreadId
+          ? readThreadShell(scopeThreadRef(threadRef.environmentId, fallbackThreadId))
+          : null;
+        await navigateAfterThreadDeletion(() =>
+          fallbackThread
+            ? router.navigate({
                 to: "/$environmentId/$threadId",
                 params: buildThreadRouteParams(
                   scopeThreadRef(fallbackThread.environmentId, fallbackThread.id),
                 ),
                 replace: true,
-              }),
-            );
-            if (navigationResult._tag === "Failure") {
-              return navigationResult;
-            }
-          } else {
-            const navigationResult = await settlePromise(() =>
-              router.navigate({ to: "/", replace: true }),
-            );
-            if (navigationResult._tag === "Failure") {
-              return navigationResult;
-            }
-          }
-        } else {
-          const navigationResult = await settlePromise(() =>
-            router.navigate({ to: "/", replace: true }),
-          );
-          if (navigationResult._tag === "Failure") {
-            return navigationResult;
-          }
-        }
+              })
+            : router.navigate({ to: "/", replace: true }),
+        );
       }
 
       if (!shouldDeleteWorktree || !orphanedWorktreePath || !threadProject) {
@@ -444,9 +440,10 @@ export function useThreadActions() {
             ? refreshResult
             : null;
       if (cleanupFailure) {
+        const removalFailed = removeResult._tag === "Failure";
         const error = squashAtomCommandFailure(cleanupFailure);
-        const message = error instanceof Error ? error.message : "Unknown error removing worktree.";
-        console.error("Failed to remove orphaned worktree after thread deletion", {
+        const message = error instanceof Error ? error.message : "An error occurred.";
+        console.error("Worktree cleanup failed after thread deletion", {
           threadId: threadRef.threadId,
           projectCwd: threadProject.workspaceRoot,
           worktreePath: orphanedWorktreePath,
@@ -455,11 +452,16 @@ export function useThreadActions() {
         toastManager.add(
           stackedThreadToast({
             type: "error",
-            title: "Thread deleted, but worktree removal failed",
-            description: `Could not remove ${displayWorktreePath ?? orphanedWorktreePath}. ${message}`,
+            title: removalFailed
+              ? "Failed to delete worktree"
+              : "Worktree deleted, but Git status refresh failed",
+            description: removalFailed
+              ? `Could not remove ${displayWorktreePath ?? orphanedWorktreePath}. ${message}`
+              : message,
           }),
         );
-        return cleanupFailure;
+        // The thread was deleted. Cleanup has its own toast; returning its
+        // failure would make callers incorrectly report a thread deletion error.
       }
       return deleteResult;
     },
diff --git a/apps/web/src/hostedPairing.ts b/apps/web/src/hostedPairing.ts
index 6c5ac58cb35d..87c352244e5f 100644
--- a/apps/web/src/hostedPairing.ts
+++ b/apps/web/src/hostedPairing.ts
@@ -40,8 +40,9 @@ export function isHostedStaticApp(url?: URL): boolean {
     return true;
   }
 
-  // No window (tests, static render) means no origin to be hosted at.
-  if (url === undefined && typeof window === "undefined") {
+  // No window, or a window without a location (tests, static render), means
+  // no origin to be hosted at.
+  if (url === undefined && (typeof window === "undefined" || window.location === undefined)) {
     return false;
   }
 
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 63dc9e21c094..45d10f28d735 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -425,20 +425,55 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   }
 }
 
+@keyframes live-tool-shine {
+  from {
+    background-position:
+      -4.5rem 0,
+      0 0;
+  }
+  to {
+    background-position:
+      calc(100% + 4.5rem) 0,
+      0 0;
+  }
+}
+
+@utility live-tool-shine {
+  @media (prefers-reduced-motion: no-preference) and (forced-colors: none) {
+    color: transparent;
+    background-image:
+      linear-gradient(to right, transparent, var(--contrast-foreground), transparent),
+      linear-gradient(var(--contrast-secondary-label), var(--contrast-secondary-label));
+    background-size:
+      4.5rem 100%,
+      100% 100%;
+    background-repeat: no-repeat;
+    background-clip: text;
+    animation: live-tool-shine 2.2s steps(30) infinite;
+    animation-play-state: var(--visible-animation-state, paused);
+  }
+}
+
+@utility visible-animate-spin {
+  animation: var(--animate-spin);
+  animation-play-state: var(--visible-animation-state, paused);
+  will-change: var(--visible-animation-will-change, auto);
+}
+
 @keyframes live-activity-focus {
-  0% {
+  from {
     transform: translateX(0);
   }
-  100% {
+  to {
     transform: translateX(100%);
   }
 }
 
 @keyframes live-activity-focus-counter {
-  0% {
+  from {
     transform: translateX(0);
   }
-  100% {
+  to {
     transform: translateX(-100%);
   }
 }
@@ -474,9 +509,10 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   );
   mask-repeat: no-repeat;
   animation: live-activity-focus 2.2s linear infinite;
-  will-change: transform;
+  animation-play-state: var(--visible-animation-state, paused);
+  will-change: var(--visible-animation-will-change, auto);
 
-  @media (prefers-reduced-motion: reduce) {
+  @media (prefers-reduced-motion: reduce), (forced-colors: active) {
     animation: none;
     opacity: 0;
     will-change: auto;
@@ -486,9 +522,10 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
 @utility live-activity-focus-counter {
   width: 100%;
   animation: live-activity-focus-counter 2.2s linear infinite;
-  will-change: transform;
+  animation-play-state: var(--visible-animation-state, paused);
+  will-change: var(--visible-animation-will-change, auto);
 
-  @media (prefers-reduced-motion: reduce) {
+  @media (prefers-reduced-motion: reduce), (forced-colors: active) {
     animation: none;
     will-change: auto;
   }
@@ -1147,6 +1184,39 @@ html[data-theme-id]:not([data-theme-id=""]) {
   --terminal-selection-background: var(--app-theme-terminal-selection-background);
 }
 
+/* The first-run flow owns the whole document so portaled menus and tooltips
+   use the same fixed palette as the wizard. This follows the theme mapping so
+   saved custom themes cannot override it while onboarding is mounted. */
+html[data-onboarding-surface]:root {
+  color-scheme: dark;
+  --accent: #262626;
+  --accent-foreground: #fff;
+  --appearance-contrast-target: #fff;
+  --app-chrome-background: #000;
+  --background: #000;
+  --border: #262626;
+  --card: #000;
+  --card-foreground: #fff;
+  --destructive: var(--color-red-400);
+  --foreground: #fff;
+  --icon-muted: #a1a1aa;
+  --input: #262626;
+  --muted: #171717;
+  --muted-foreground: #a1a1aa;
+  --placeholder: #71717a;
+  --popover: #171717;
+  --popover-foreground: #fff;
+  --ring: #737373;
+  --secondary: #171717;
+  --secondary-foreground: #fff;
+  --secondary-label: #a1a1aa;
+  --success-foreground: var(--color-emerald-400);
+  --terminal-background: #000;
+  --terminal-cursor: #fff;
+  --terminal-foreground: #fff;
+  --terminal-selection-background: rgb(255 255 255 / 20%);
+}
+
 /* Theme-token dependency probes are restored synchronously, before paint. Keep
    transitions from observing the temporary sentinel color in between. */
 html[data-theme-token-probe],
@@ -1348,11 +1418,10 @@ html[data-theme-id="t3-chat"] [data-app-sidebar] {
   }
 }
 
-/* Contrast stays in ordinary custom properties so both Tailwind utilities and
-   global/imperative chrome styles resolve the same adjusted role. Redeclare on
-   the sidebar because it owns a local semantic palette. */
+/* Recompute contrast wherever a subtree owns its own semantic color palette. */
 :root,
-[data-app-sidebar] {
+[data-app-sidebar],
+[data-onboarding-surface] {
   --contrast-toolbar-foreground: color-mix(
     in oklab,
     color-mix(
@@ -1906,24 +1975,6 @@ code {
   color: var(--code-foreground) !important;
 }
 
-@keyframes ultrathink-rainbow {
-  0% {
-    background-position: 0% 50%;
-  }
-  100% {
-    background-position: 200% 50%;
-  }
-}
-
-@keyframes ultrathink-chroma-shift {
-  0% {
-    filter: hue-rotate(0deg) saturate(1.2);
-  }
-  100% {
-    filter: hue-rotate(360deg) saturate(1.2);
-  }
-}
-
 .ultrathink-frame {
   --ultrathink-spectrum: linear-gradient(
     120deg,
@@ -1946,6 +1997,7 @@ code {
   padding: 2px;
   background-image: var(--ultrathink-spectrum);
   background-size: 220% 220%;
+  background-position: 0% 50%;
   pointer-events: none;
   filter: saturate(0.82) brightness(0.92);
   -webkit-mask:
@@ -1956,7 +2008,6 @@ code {
     linear-gradient(#000 0 0) content-box,
     linear-gradient(#000 0 0);
   mask-composite: exclude;
-  animation: ultrathink-rainbow 10s linear infinite;
 }
 
 .ultrathink-frame > * {
@@ -1964,7 +2015,7 @@ code {
 }
 
 .ultrathink-chroma {
-  animation: ultrathink-chroma-shift 10s linear infinite;
+  filter: saturate(1.2);
 }
 
 @keyframes preview-loading-progress {
diff --git a/apps/web/src/keybindings.test.ts b/apps/web/src/keybindings.test.ts
index 8cbc45966529..df005571193e 100644
--- a/apps/web/src/keybindings.test.ts
+++ b/apps/web/src/keybindings.test.ts
@@ -8,8 +8,6 @@ import {
 } from "@t3tools/contracts";
 import {
   formatShortcutLabel,
-  isChatNewShortcut,
-  isChatNewLocalShortcut,
   isDiffToggleShortcut,
   modelPickerJumpCommandForIndex,
   modelPickerJumpIndexFromCommand,
@@ -21,8 +19,7 @@ import {
   isTerminalSplitVerticalShortcut,
   isTerminalToggleShortcut,
   resolveShortcutCommand,
-  shouldShowModelPickerJumpHints,
-  shouldShowThreadJumpHints,
+  shouldShowThreadJumpHintsForModifiers,
   shortcutLabelForCommand,
   terminalDeleteShortcutData,
   terminalNavigationShortcutData,
@@ -498,17 +495,21 @@ describe("thread navigation helpers", () => {
 
   it("shows jump hints only when configured modifiers match", () => {
     assert.isTrue(
-      shouldShowThreadJumpHints(event({ metaKey: true }), DEFAULT_BINDINGS, {
+      shouldShowThreadJumpHintsForModifiers(event({ metaKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
       }),
     );
     assert.isFalse(
-      shouldShowThreadJumpHints(event({ metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
-        platform: "MacIntel",
-      }),
+      shouldShowThreadJumpHintsForModifiers(
+        event({ metaKey: true, shiftKey: true }),
+        DEFAULT_BINDINGS,
+        {
+          platform: "MacIntel",
+        },
+      ),
     );
     assert.isTrue(
-      shouldShowThreadJumpHints(event({ ctrlKey: true }), DEFAULT_BINDINGS, {
+      shouldShowThreadJumpHintsForModifiers(event({ ctrlKey: true }), DEFAULT_BINDINGS, {
         platform: "Linux",
       }),
     );
@@ -516,13 +517,13 @@ describe("thread navigation helpers", () => {
 
   it("never shows jump hints while the terminal is focused, even with an unrestricted binding", () => {
     assert.isFalse(
-      shouldShowThreadJumpHints(event({ metaKey: true }), DEFAULT_BINDINGS, {
+      shouldShowThreadJumpHintsForModifiers(event({ metaKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
         context: { terminalFocus: true },
       }),
     );
     assert.isTrue(
-      shouldShowThreadJumpHints(event({ metaKey: true }), DEFAULT_BINDINGS, {
+      shouldShowThreadJumpHintsForModifiers(event({ metaKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
         context: { terminalFocus: false },
       }),
@@ -539,47 +540,36 @@ describe("model picker navigation helpers", () => {
     assert.strictEqual(modelPickerJumpIndexFromCommand("modelPicker.jump.3"), 2);
     assert.isNull(modelPickerJumpIndexFromCommand("thread.jump.1"));
   });
-
-  it("shows jump hints only while the model picker context is active", () => {
-    assert.isFalse(
-      shouldShowModelPickerJumpHints(event({ metaKey: true }), DEFAULT_BINDINGS, {
-        platform: "MacIntel",
-        context: { modelPickerOpen: false },
-      }),
-    );
-    assert.isTrue(
-      shouldShowModelPickerJumpHints(event({ metaKey: true }), DEFAULT_BINDINGS, {
-        platform: "MacIntel",
-        context: { modelPickerOpen: true },
-      }),
-    );
-  });
 });
 
 describe("chat/editor shortcuts", () => {
   it("matches chat.new shortcut", () => {
-    assert.isTrue(
-      isChatNewShortcut(event({ key: "o", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "o", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
       }),
+      "chat.new",
     );
-    assert.isTrue(
-      isChatNewShortcut(event({ key: "o", ctrlKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "o", ctrlKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
         platform: "Linux",
       }),
+      "chat.new",
     );
   });
 
   it("matches chat.newLocal shortcut", () => {
-    assert.isTrue(
-      isChatNewLocalShortcut(event({ key: "n", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "n", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
         platform: "MacIntel",
       }),
+      "chat.newLocal",
     );
-    assert.isTrue(
-      isChatNewLocalShortcut(event({ key: "n", ctrlKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "n", ctrlKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
         platform: "Linux",
       }),
+      "chat.newLocal",
     );
   });
 
@@ -699,11 +689,12 @@ describe("cross-command precedence", () => {
         context: { terminalFocus: true },
       }),
     );
-    assert.isFalse(
-      isChatNewShortcut(event({ key: "n", metaKey: true }), keybindings, {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "n", metaKey: true }), keybindings, {
         platform: "MacIntel",
         context: { terminalFocus: true },
       }),
+      "terminal.new",
     );
     assert.isFalse(
       isTerminalNewShortcut(event({ key: "n", metaKey: true }), keybindings, {
@@ -711,11 +702,12 @@ describe("cross-command precedence", () => {
         context: { terminalFocus: false },
       }),
     );
-    assert.isTrue(
-      isChatNewShortcut(event({ key: "n", metaKey: true }), keybindings, {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "n", metaKey: true }), keybindings, {
         platform: "MacIntel",
         context: { terminalFocus: false },
       }),
+      "chat.new",
     );
   });
 
@@ -735,11 +727,12 @@ describe("cross-command precedence", () => {
         context: { terminalFocus: true },
       }),
     );
-    assert.isTrue(
-      isChatNewShortcut(event({ key: "n", ctrlKey: true }), keybindings, {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "n", ctrlKey: true }), keybindings, {
         platform: "Linux",
         context: { terminalFocus: true },
       }),
+      "chat.new",
     );
   });
 });
diff --git a/apps/web/src/keybindings.ts b/apps/web/src/keybindings.ts
index 2a8d385cb42b..1b4fa072d5a1 100644
--- a/apps/web/src/keybindings.ts
+++ b/apps/web/src/keybindings.ts
@@ -288,14 +288,6 @@ export function threadTraversalDirectionFromCommand(
   return null;
 }
 
-export function shouldShowThreadJumpHints(
-  event: ShortcutEventLike,
-  keybindings: ResolvedKeybindingsConfig,
-  options?: ShortcutMatchOptions,
-): boolean {
-  return shouldShowThreadJumpHintsForModifiers(event, keybindings, options);
-}
-
 export function shouldShowThreadJumpHintsForModifiers(
   modifiers: ShortcutModifierStateLike,
   keybindings: ResolvedKeybindingsConfig,
@@ -337,32 +329,6 @@ export function modelPickerJumpIndexFromCommand(command: string): number | null
   return index === -1 ? null : index;
 }
 
-export function shouldShowModelPickerJumpHints(
-  event: ShortcutEventLike,
-  keybindings: ResolvedKeybindingsConfig,
-  options?: ShortcutMatchOptions,
-): boolean {
-  return shouldShowModelPickerJumpHintsForModifiers(event, keybindings, options);
-}
-
-export function shouldShowModelPickerJumpHintsForModifiers(
-  modifiers: ShortcutModifierStateLike,
-  keybindings: ResolvedKeybindingsConfig,
-  options?: ShortcutMatchOptions,
-): boolean {
-  const platform = resolvePlatform(options);
-
-  for (const command of MODEL_PICKER_JUMP_KEYBINDING_COMMANDS) {
-    const shortcut = findEffectiveShortcutForCommand(keybindings, command, options);
-    if (!shortcut) continue;
-    if (matchesShortcutModifiers(modifiers, shortcut, platform)) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
 export function isTerminalToggleShortcut(
   event: ShortcutEventLike,
   keybindings: ResolvedKeybindingsConfig,
@@ -419,22 +385,6 @@ export function isPreviewRefreshShortcut(
   return matchesCommandShortcut(event, keybindings, "preview.refresh", options);
 }
 
-export function isChatNewShortcut(
-  event: ShortcutEventLike,
-  keybindings: ResolvedKeybindingsConfig,
-  options?: ShortcutMatchOptions,
-): boolean {
-  return matchesCommandShortcut(event, keybindings, "chat.new", options);
-}
-
-export function isChatNewLocalShortcut(
-  event: ShortcutEventLike,
-  keybindings: ResolvedKeybindingsConfig,
-  options?: ShortcutMatchOptions,
-): boolean {
-  return matchesCommandShortcut(event, keybindings, "chat.newLocal", options);
-}
-
 export function isOpenFavoriteEditorShortcut(
   event: ShortcutEventLike,
   keybindings: ResolvedKeybindingsConfig,
diff --git a/apps/web/src/lib/favicon.ts b/apps/web/src/lib/favicon.ts
index b327146b60bf..c582e0441426 100644
--- a/apps/web/src/lib/favicon.ts
+++ b/apps/web/src/lib/favicon.ts
@@ -1,23 +1 @@
-import { isPublicFaviconHost } from "~/browser/browserTargetResolver";
-
-/**
- * Favicon helpers for the preview tab strip.
- *
- * Uses Google's s2 favicon endpoint (same approach as ami's tab strip).
- * Callers should always render a `<Globe />` fallback when the returned URL
- * fails to load via an `onError` handler.
- */
-const FAVICON_PROVIDER = "https://www.google.com/s2/favicons";
-
-export function faviconUrlForOrigin(rawUrl: string | null | undefined, size = 32): string | null {
-  if (!rawUrl) return null;
-  try {
-    const url = new URL(rawUrl);
-    if (!url.host) return null;
-    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
-    if (!isPublicFaviconHost(url.hostname)) return null;
-    return `${FAVICON_PROVIDER}?domain=${encodeURIComponent(url.host)}&sz=${size}`;
-  } catch {
-    return null;
-  }
-}
+export { faviconUrlForOrigin } from "@t3tools/shared/favicon";
diff --git a/apps/web/src/lib/openPullRequestLink.test.ts b/apps/web/src/lib/openPullRequestLink.test.ts
index bd8cfe3d72d0..ad4971d331d8 100644
--- a/apps/web/src/lib/openPullRequestLink.test.ts
+++ b/apps/web/src/lib/openPullRequestLink.test.ts
@@ -1,13 +1,12 @@
-import { describe, expect, it, vi } from "vite-plus/test";
+import { describe, expect, it } from "vite-plus/test";
 
 import {
   changeRequestRepositoryUrl,
   findProjectForChangeRequest,
   gitHubPullRequestBrowserUrl,
   matchesLinkedPullRequestUrl,
-  openPullRequestLink,
   parseChangeRequestUrl,
-  PullRequestLinkOpenError,
+  pullRequestCandidateUrlFromReferenceAutolink,
   shouldOpenPullRequestExternally,
 } from "./openPullRequestLink";
 import { ProjectId, type RepositoryIdentity } from "@t3tools/contracts";
@@ -130,6 +129,29 @@ describe("changeRequestRepositoryUrl", () => {
   });
 });
 
+describe("pullRequestCandidateUrlFromReferenceAutolink", () => {
+  it("turns GitHub's shared issue route into a pull request candidate", () => {
+    expect(
+      pullRequestCandidateUrlFromReferenceAutolink(
+        "https://github.com/pingdotgg/t3code/issues/8600#issuecomment-1",
+      ),
+    ).toBe("https://github.com/pingdotgg/t3code/pull/8600#issuecomment-1");
+  });
+
+  it("does not reinterpret other issue hosts or malformed references", () => {
+    expect(
+      pullRequestCandidateUrlFromReferenceAutolink(
+        "https://gitlab.com/pingdotgg/t3code/-/issues/8600",
+      ),
+    ).toBeNull();
+    expect(
+      pullRequestCandidateUrlFromReferenceAutolink(
+        "https://github.com/pingdotgg/t3code/issues/not-a-number",
+      ),
+    ).toBeNull();
+  });
+});
+
 describe("matchesLinkedPullRequestUrl", () => {
   const linkedPullRequest = {
     projectId: ProjectId.make("project-1"),
@@ -160,33 +182,6 @@ describe("matchesLinkedPullRequestUrl", () => {
   });
 });
 
-describe("openPullRequestLink", () => {
-  it("opens the requested pull request URL", async () => {
-    const openExternal = vi.fn(async () => undefined);
-    const targetUrl = "https://github.com/pingdotgg/t3code/pull/123";
-
-    await openPullRequestLink({ openExternal }, targetUrl);
-
-    expect(openExternal).toHaveBeenCalledExactlyOnceWith(targetUrl);
-  });
-
-  it("reports bridge failures with a safe target origin", async () => {
-    const cause = new Error("desktop shell unavailable");
-    const targetUrl = "https://github.com/pingdotgg/t3code/pull/123?token=secret";
-    const openExternal = vi.fn(async () => Promise.reject(cause));
-
-    const result = openPullRequestLink({ openExternal }, targetUrl);
-
-    await expect(result).rejects.toEqual(
-      new PullRequestLinkOpenError({
-        targetOrigin: "https://github.com",
-        cause,
-      }),
-    );
-    await expect(result).rejects.not.toHaveProperty("message", expect.stringContaining("secret"));
-  });
-});
-
 describe("shouldOpenPullRequestExternally", () => {
   it("uses the browser for command-click and control-click", () => {
     expect(shouldOpenPullRequestExternally({ metaKey: true, ctrlKey: false })).toBe(true);
diff --git a/apps/web/src/lib/openPullRequestLink.ts b/apps/web/src/lib/openPullRequestLink.ts
index 785305fcd282..2d46e3984fd9 100644
--- a/apps/web/src/lib/openPullRequestLink.ts
+++ b/apps/web/src/lib/openPullRequestLink.ts
@@ -1,12 +1,10 @@
 import type {
   EnvironmentId,
-  LocalApi,
   RepositoryIdentity,
   ScopedThreadRef,
   ThreadLinkedPullRequest,
 } from "@t3tools/contracts";
 import { useNavigate } from "@tanstack/react-router";
-import * as Schema from "effect/Schema";
 import { type MouseEvent, useCallback } from "react";
 
 import { pullRequestHostOf, type SourceControlProviderKind } from "@t3tools/contracts";
@@ -19,41 +17,6 @@ import type { EnvironmentProject } from "@t3tools/client-runtime/state/shell";
 import { useProjects, useServerConfigs } from "../state/entities";
 import { usePrimaryEnvironmentId } from "../state/environments";
 
-export class PullRequestLinkOpenError extends Schema.TaggedErrorClass<PullRequestLinkOpenError>()(
-  "PullRequestLinkOpenError",
-  {
-    targetOrigin: Schema.NullOr(Schema.String),
-    cause: Schema.Defect(),
-  },
-) {
-  static fromCause(targetUrl: string, cause: unknown): PullRequestLinkOpenError {
-    let targetOrigin: string | null = null;
-    try {
-      targetOrigin = new URL(targetUrl).origin;
-    } catch {
-      // Keep malformed URLs out of diagnostics while preserving the open failure below.
-    }
-    return new PullRequestLinkOpenError({ targetOrigin, cause });
-  }
-
-  override get message(): string {
-    return this.targetOrigin === null
-      ? "Unable to open pull request link."
-      : `Unable to open pull request link at ${this.targetOrigin}.`;
-  }
-}
-
-export async function openPullRequestLink(
-  shell: Pick<LocalApi["shell"], "openExternal">,
-  targetUrl: string,
-): Promise<void> {
-  try {
-    await shell.openExternal(targetUrl);
-  } catch (cause) {
-    throw PullRequestLinkOpenError.fromCause(targetUrl, cause);
-  }
-}
-
 /** Builds a GitHub URL that remains available when the pull request API cannot be read. */
 export function gitHubPullRequestBrowserUrl(
   identity: RepositoryIdentity | null | undefined,
@@ -160,6 +123,30 @@ export function parseChangeRequestUrl(targetUrl: string): ChangeRequestLink | nu
   return null;
 }
 
+/**
+ * The pull-request URL a GitHub-style `#123` autolink might name. GitHub writes every bare
+ * reference through `/issues/`, including pull requests, so this only builds a candidate: the
+ * caller must successfully read it as a pull request before treating it as one.
+ */
+export function pullRequestCandidateUrlFromReferenceAutolink(targetUrl: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(targetUrl);
+  } catch {
+    return null;
+  }
+  if (
+    (url.protocol !== "https:" && url.protocol !== "http:") ||
+    !isHostOf(url.hostname.toLowerCase(), "github.com", "github")
+  ) {
+    return null;
+  }
+  const match = /^\/([^/]+\/[^/]+)\/issues\/(\d+)(?:\/|$)/u.exec(url.pathname);
+  if (match?.[1] === undefined || match[2] === undefined) return null;
+  url.pathname = `/${match[1]}/pull/${match[2]}`;
+  return url.toString();
+}
+
 /** Match a stored PR without requiring its project to remain available. */
 export function matchesLinkedPullRequestUrl(
   linkedPullRequest: ThreadLinkedPullRequest,
@@ -263,13 +250,14 @@ export function useOpenChangeRequestLink(
   >,
   targetUrl: string,
   targetThreadRef?: ScopedThreadRef,
+  targetEnvironmentId?: EnvironmentId,
 ) => boolean {
   const navigate = useNavigate();
   const allProjects = useProjects();
   const serverConfigs = useServerConfigs();
   const primaryEnvironmentId = usePrimaryEnvironmentId();
   return useCallback(
-    (event, targetUrl, targetThreadRef) => {
+    (event, targetUrl, targetThreadRef, targetEnvironmentId) => {
       if (shouldOpenPullRequestExternally(event)) return false;
       const resolvedThreadRef = targetThreadRef ?? threadRef;
       const parsed = parseChangeRequestUrl(targetUrl);
@@ -285,13 +273,15 @@ export function useOpenChangeRequestLink(
       // against all of them, the primary first where two hold the same repository.
       const projects = resolvedThreadRef
         ? allProjects.filter((project) => project.environmentId === resolvedThreadRef.environmentId)
-        : allProjects
-            .filter((project) => reads(project.environmentId))
-            .toSorted(
-              (left, right) =>
-                Number(right.environmentId === primaryEnvironmentId) -
-                Number(left.environmentId === primaryEnvironmentId),
-            );
+        : targetEnvironmentId
+          ? allProjects.filter((project) => project.environmentId === targetEnvironmentId)
+          : allProjects
+              .filter((project) => reads(project.environmentId))
+              .toSorted(
+                (left, right) =>
+                  Number(right.environmentId === primaryEnvironmentId) -
+                  Number(left.environmentId === primaryEnvironmentId),
+              );
       const project = findProjectForChangeRequest(projects, parsed);
       if (project === undefined || !reads(project.environmentId)) return false;
       event.preventDefault();
diff --git a/apps/web/src/lib/storage.ts b/apps/web/src/lib/storage.ts
index a37c67064aa9..87b9b12ea8bc 100644
--- a/apps/web/src/lib/storage.ts
+++ b/apps/web/src/lib/storage.ts
@@ -6,7 +6,10 @@ export interface StateStorage<R = unknown> {
   removeItem: (name: string) => R;
 }
 
-export interface DebouncedStorage<R = unknown> extends StateStorage<R> {
+export interface DeferredStorage<TValue> {
+  getItem: (name: string) => string | null | Promise<string | null>;
+  setItem: (name: string, value: TValue) => void;
+  removeItem: (name: string) => void;
   flush: () => void;
 }
 
@@ -39,14 +42,16 @@ export function resolveStorage(storage: Partial<StateStorage> | null | undefined
   return isStateStorage(storage) ? storage : createMemoryStorage();
 }
 
-export function createDebouncedStorage(
+/** Keep the latest value and serialize it when the debounce fires or `flush` runs. */
+export function createDeferredStorage<TValue>(
   baseStorage: Partial<StateStorage> | null | undefined,
+  serialize: (value: TValue) => string,
   debounceMs: number = 300,
-): DebouncedStorage {
+): DeferredStorage<TValue> {
   const resolvedStorage = resolveStorage(baseStorage);
   const debouncedSetItem = new Debouncer(
-    (name: string, value: string) => {
-      resolvedStorage.setItem(name, value);
+    (name: string, value: TValue) => {
+      resolvedStorage.setItem(name, serialize(value));
     },
     { wait: debounceMs },
   );
@@ -58,6 +63,8 @@ export function createDebouncedStorage(
     },
     removeItem: (name) => {
       debouncedSetItem.cancel();
+      // cancel() leaves the captured value in Pacer's lastArgs.
+      debouncedSetItem.reset();
       resolvedStorage.removeItem(name);
     },
     flush: () => {
diff --git a/apps/web/src/lib/terminalContext.test.ts b/apps/web/src/lib/terminalContext.test.ts
index 4b520c9bef4a..199054b1d84b 100644
--- a/apps/web/src/lib/terminalContext.test.ts
+++ b/apps/web/src/lib/terminalContext.test.ts
@@ -3,7 +3,6 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   appendTerminalContextsToPrompt,
-  buildTerminalContextPreviewTitle,
   buildTerminalContextBlock,
   countInlineTerminalContextPlaceholders,
   deriveDisplayedUserMessageState,
@@ -135,20 +134,6 @@ describe("terminalContext", () => {
     });
   });
 
-  it("returns null preview title when every context is invalid", () => {
-    expect(
-      buildTerminalContextPreviewTitle([
-        makeContext({
-          terminalId: "   ",
-        }),
-        makeContext({
-          id: "context-2",
-          text: "\n\n",
-        }),
-      ]),
-    ).toBeNull();
-  });
-
   it("tracks inline terminal context placeholders in prompt text", () => {
     const placeholder = INLINE_TERMINAL_CONTEXT_PLACEHOLDER;
     expect(countInlineTerminalContextPlaceholders(`a${placeholder}b${placeholder}`)).toBe(2);
diff --git a/apps/web/src/lib/terminalContext.ts b/apps/web/src/lib/terminalContext.ts
index 72f49a2f22d2..4cdbc019255d 100644
--- a/apps/web/src/lib/terminalContext.ts
+++ b/apps/web/src/lib/terminalContext.ts
@@ -65,20 +65,6 @@ export function filterTerminalContextsWithText<T extends { text: string }>(
   return contexts.filter((context) => hasTerminalContextText(context));
 }
 
-function previewTerminalContextText(text: string): string {
-  const normalized = normalizeTerminalContextText(text);
-  if (normalized.length === 0) {
-    return "";
-  }
-  const lines = normalized.split("\n");
-  const visibleLines = lines.slice(0, 3);
-  if (lines.length > 3) {
-    visibleLines.push("...");
-  }
-  const preview = visibleLines.join("\n");
-  return preview.length > 180 ? `${preview.slice(0, 177)}...` : preview;
-}
-
 export function normalizeTerminalContextSelection(
   selection: TerminalContextSelection,
 ): TerminalContextSelection | null {
@@ -129,27 +115,6 @@ export function formatInlineTerminalContextLabel(selection: {
   return `@${terminalLabel}:${range}`;
 }
 
-export function buildTerminalContextPreviewTitle(
-  contexts: ReadonlyArray<TerminalContextSelection>,
-): string | null {
-  if (contexts.length === 0) {
-    return null;
-  }
-  const previewParts: string[] = [];
-  for (const context of contexts) {
-    const normalized = normalizeTerminalContextSelection(context);
-    if (!normalized) continue;
-    const preview = previewTerminalContextText(normalized.text);
-    previewParts.push(
-      preview.length > 0
-        ? `${formatTerminalContextLabel(normalized)}\n${preview}`
-        : formatTerminalContextLabel(normalized),
-    );
-  }
-  const previews = previewParts.join("\n\n");
-  return previews.length > 0 ? previews : null;
-}
-
 function buildTerminalContextBodyLines(selection: TerminalContextSelection): string[] {
   return normalizeTerminalContextText(selection.text)
     .split("\n")
diff --git a/apps/web/src/lib/visibleAnimation.test.ts b/apps/web/src/lib/visibleAnimation.test.ts
new file mode 100644
index 000000000000..0cc7c9d8354b
--- /dev/null
+++ b/apps/web/src/lib/visibleAnimation.test.ts
@@ -0,0 +1,154 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { observeVisibleAnimation } from "./visibleAnimation";
+
+let page = Object.assign(new EventTarget(), { visibilityState: "visible" });
+let motion = Object.assign(new EventTarget(), { matches: false });
+let observers: TestIntersectionObserver[] = [];
+let cleanups: Array<() => void> = [];
+
+class TestIntersectionObserver {
+  constructor(private readonly callback: IntersectionObserverCallback) {
+    observers.push(this);
+  }
+
+  observe = vi.fn();
+  unobserve = vi.fn();
+  disconnect = vi.fn();
+
+  report(target: Element, isIntersecting: boolean) {
+    this.callback(
+      [{ target, isIntersecting } as IntersectionObserverEntry],
+      this as unknown as IntersectionObserver,
+    );
+  }
+}
+
+function animationElement() {
+  const properties = new Map<string, string>();
+  const element = {
+    style: { setProperty: (name: string, value: string) => properties.set(name, value) },
+  } as unknown as HTMLElement;
+  return {
+    element,
+    state: () => properties.get("--visible-animation-state"),
+    willChange: () => properties.get("--visible-animation-will-change"),
+  };
+}
+
+function attach(element: HTMLElement) {
+  const cleanup = observeVisibleAnimation(element);
+  if (cleanup) cleanups.push(cleanup);
+  return cleanup;
+}
+
+beforeEach(() => {
+  page = Object.assign(new EventTarget(), { visibilityState: "visible" });
+  motion = Object.assign(new EventTarget(), { matches: false });
+  observers = [];
+  cleanups = [];
+  vi.stubGlobal("document", page);
+  vi.stubGlobal("window", { matchMedia: () => motion });
+  vi.stubGlobal("IntersectionObserver", TestIntersectionObserver);
+});
+
+afterEach(() => {
+  for (const cleanup of cleanups) cleanup();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("observeVisibleAnimation", () => {
+  it("runs only intersecting animations in a visible document with motion enabled", () => {
+    const first = animationElement();
+    const second = animationElement();
+    attach(first.element);
+    attach(second.element);
+    expect(first.state()).toBe("paused");
+
+    const observer = observers[0]!;
+    observer.report(first.element, true);
+    expect(first.state()).toBe("running");
+    expect(second.state()).toBe("paused");
+
+    page.visibilityState = "hidden";
+    page.dispatchEvent(new Event("visibilitychange"));
+    observer.report(second.element, true);
+    expect(first.state()).toBe("paused");
+    expect(first.willChange()).toBe("auto");
+    expect(second.state()).toBe("paused");
+
+    page.visibilityState = "visible";
+    page.dispatchEvent(new Event("visibilitychange"));
+    expect(first.state()).toBe("running");
+    expect(second.state()).toBe("running");
+
+    observer.report(first.element, false);
+    motion.matches = true;
+    motion.dispatchEvent(new Event("change"));
+    expect(first.state()).toBe("paused");
+    expect(second.state()).toBe("paused");
+
+    motion.matches = false;
+    motion.dispatchEvent(new Event("change"));
+    expect(first.state()).toBe("paused");
+    expect(second.state()).toBe("running");
+  });
+
+  it.each(["hidden", "reduced motion"])("starts paused with %s already active", (condition) => {
+    page.visibilityState = condition === "hidden" ? "hidden" : "visible";
+    motion.matches = condition === "reduced motion";
+    const animation = animationElement();
+    attach(animation.element);
+    observers[0]!.report(animation.element, true);
+    expect(animation.state()).toBe("paused");
+
+    page.visibilityState = "visible";
+    motion.matches = false;
+    page.dispatchEvent(new Event("visibilitychange"));
+    expect(animation.state()).toBe("running");
+  });
+
+  it("shares observers, releases the final ref, and ignores late callbacks after remount", () => {
+    const addVisibility = vi.spyOn(page, "addEventListener");
+    const removeVisibility = vi.spyOn(page, "removeEventListener");
+    const addMotion = vi.spyOn(motion, "addEventListener");
+    const removeMotion = vi.spyOn(motion, "removeEventListener");
+    const first = animationElement();
+    const second = animationElement();
+    const detachFirst = attach(first.element);
+    const detachSecond = attach(second.element);
+    expect(observers).toHaveLength(1);
+    expect(addVisibility).toHaveBeenCalledTimes(1);
+    expect(addMotion).toHaveBeenCalledTimes(1);
+
+    const previousObserver = observers[0]!;
+    detachFirst?.();
+    previousObserver.report(first.element, true);
+    expect(first.state()).toBe("paused");
+    expect(previousObserver.unobserve).toHaveBeenCalledWith(first.element);
+    expect(previousObserver.disconnect).not.toHaveBeenCalled();
+
+    detachSecond?.();
+    expect(previousObserver.disconnect).toHaveBeenCalledTimes(1);
+    expect(removeVisibility).toHaveBeenCalledTimes(1);
+    expect(removeMotion).toHaveBeenCalledTimes(1);
+
+    attach(second.element);
+    expect(observers).toHaveLength(2);
+    detachSecond?.();
+    previousObserver.report(second.element, true);
+    expect(second.state()).toBe("paused");
+    observers[1]!.report(second.element, true);
+    expect(second.state()).toBe("running");
+  });
+
+  it("keeps unknown visibility static when IntersectionObserver is unavailable", () => {
+    vi.stubGlobal("IntersectionObserver", undefined);
+    const animation = animationElement();
+    attach(animation.element);
+    expect(animation.state()).toBe("paused");
+    expect(animation.willChange()).toBe("auto");
+    expect(observers).toHaveLength(0);
+  });
+});
diff --git a/apps/web/src/lib/visibleAnimation.ts b/apps/web/src/lib/visibleAnimation.ts
new file mode 100644
index 000000000000..7f5f0118c7fc
--- /dev/null
+++ b/apps/web/src/lib/visibleAnimation.ts
@@ -0,0 +1,64 @@
+interface ObservedAnimation {
+  element: HTMLElement | SVGElement;
+  intersecting: boolean;
+}
+
+const animations = new Map<Element, ObservedAnimation>();
+let observer: IntersectionObserver | null = null;
+let reducedMotion: MediaQueryList | null = null;
+
+function updateAnimation(animation: ObservedAnimation) {
+  const running =
+    animation.intersecting && document.visibilityState === "visible" && !reducedMotion?.matches;
+  animation.element.style.setProperty("--visible-animation-state", running ? "running" : "paused");
+  animation.element.style.setProperty(
+    "--visible-animation-will-change",
+    running ? "transform" : "auto",
+  );
+}
+
+function updateAnimations() {
+  for (const animation of animations.values()) updateAnimation(animation);
+}
+
+/** Attach to a stable animation container. All refs share visibility and motion listeners. */
+export function observeVisibleAnimation(element: HTMLElement | SVGElement | null) {
+  if (element === null) return;
+  element.style.setProperty("--visible-animation-state", "paused");
+  element.style.setProperty("--visible-animation-will-change", "auto");
+  if (typeof IntersectionObserver === "undefined") return;
+
+  if (observer === null) {
+    reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+    reducedMotion.addEventListener("change", updateAnimations);
+    document.addEventListener("visibilitychange", updateAnimations);
+    observer = new IntersectionObserver((entries, source) => {
+      if (source !== observer) return;
+      for (const entry of entries) {
+        const animation = animations.get(entry.target);
+        if (!animation) continue;
+        animation.intersecting = entry.isIntersecting;
+        updateAnimation(animation);
+      }
+    });
+  }
+
+  const animation = { element, intersecting: false };
+  animations.set(element, animation);
+  observer.observe(element);
+
+  return () => {
+    if (animations.get(element) !== animation) return;
+    animations.delete(element);
+    observer?.unobserve(element);
+    element.style.setProperty("--visible-animation-state", "paused");
+    element.style.setProperty("--visible-animation-will-change", "auto");
+    if (animations.size === 0) {
+      observer?.disconnect();
+      observer = null;
+      reducedMotion?.removeEventListener("change", updateAnimations);
+      reducedMotion = null;
+      document.removeEventListener("visibilitychange", updateAnimations);
+    }
+  };
+}
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 9220252cb20e..33c53a86c4e2 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -113,6 +113,14 @@ describe("LocalApi", () => {
     await expect(createLocalApi().dialogs.confirm("Delete this thread?")).resolves.toBe(false);
   });
 
+  it("rejects opening System Settings when the desktop bridge is unavailable", async () => {
+    const { createLocalApi } = await import("./localApi");
+
+    await expect(createLocalApi().shell.openSystemSettings("full-disk-access")).rejects.toThrow(
+      "Unable to open System Settings.",
+    );
+  });
+
   it("delegates host capabilities and persistence to the desktop bridge", async () => {
     const showContextMenu = vi.fn().mockResolvedValue("delete");
     const pickFolder = vi.fn().mockResolvedValue("/tmp/project");
diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index 8f55f65e40de..cafd04f9c048 100644
--- a/apps/web/src/localApi.ts
+++ b/apps/web/src/localApi.ts
@@ -29,6 +29,17 @@ function createBrowserLocalApi(): LocalApi {
 
         window.open(url, "_blank", "noopener,noreferrer");
       },
+      // Only the desktop shell can reach the OS; the web build (and older
+      // desktop shells that predate this method) have nothing to open.
+      openSystemSettings: async (pane) => {
+        if (!window.desktopBridge?.openSystemSettings) {
+          throw new Error("Unable to open System Settings.");
+        }
+        const opened = await window.desktopBridge.openSystemSettings(pane);
+        if (!opened) {
+          throw new Error("Unable to open System Settings.");
+        }
+      },
     },
     contextMenu: {
       show: async <T extends string>(
diff --git a/apps/web/src/markdown-links.test.ts b/apps/web/src/markdown-links.test.ts
index e3b1cc5b2249..5421c0d8781d 100644
--- a/apps/web/src/markdown-links.test.ts
+++ b/apps/web/src/markdown-links.test.ts
@@ -254,6 +254,61 @@ describe("resolveMarkdownFileLinkTarget", () => {
     });
   });
 
+  it("does not classify a case-distinct POSIX sibling as a workspace file", () => {
+    expect(
+      resolveMarkdownFileLinkMeta(
+        "/tmp/t3code-case-test/project/probe.txt",
+        "/tmp/t3code-case-test/Project",
+      ),
+    ).toMatchObject({
+      displayPath: "/tmp/t3code-case-test/project/probe.txt",
+      workspaceRelativePath: null,
+    });
+  });
+
+  it("keeps Windows workspace comparisons case-insensitive", () => {
+    expect(
+      resolveMarkdownFileLinkMeta("C:/Users/MIKE/Project/src/main.ts", "c:/users/mike/project"),
+    ).toMatchObject({
+      displayPath: "project/src/main.ts",
+      workspaceRelativePath: "src/main.ts",
+    });
+  });
+
+  it("keeps drive-root workspace comparisons case-insensitive", () => {
+    expect(resolveMarkdownFileLinkMeta("C:/Users/MIKE/project.ts", "c:/")).toMatchObject({
+      displayPath: "c:/Users/MIKE/project.ts",
+      workspaceRelativePath: "Users/MIKE/project.ts",
+    });
+  });
+
+  it("keeps backslash UNC workspace comparisons case-insensitive", () => {
+    expect(
+      resolveMarkdownFileLinkMeta(
+        "\\\\server\\share\\PROJECT\\src\\main.ts",
+        "\\\\Server\\Share\\Project",
+      ),
+    ).toMatchObject({
+      displayPath: "Project/src/main.ts",
+      workspaceRelativePath: "src/main.ts",
+    });
+  });
+
+  it.each([
+    ["/tmp/repo/file.ts", "/", "tmp/repo/file.ts"],
+    ["C:/Users/MIKE/file.ts", "c:/", "Users/MIKE/file.ts"],
+    ["\\\\server\\SHARE\\file.ts", "\\\\Server\\Share\\", "file.ts"],
+    ["/tmp/repo/file.ts%20", "/tmp/repo", "file.ts "],
+  ])("preserves the preview target for %s in workspace %s", (href, cwd, workspaceRelativePath) => {
+    expect(resolveMarkdownFileLinkMeta(href, cwd)).toMatchObject({ workspaceRelativePath });
+  });
+
+  it("keeps an encoded final space in the absolute target", () => {
+    expect(resolveMarkdownFileLinkTarget("/tmp/repo/file.ts%20", "/tmp/repo")).toBe(
+      "/tmp/repo/file.ts ",
+    );
+  });
+
   it("normalizes slash-prefixed windows drive paths before resolving", () => {
     expect(
       resolveMarkdownFileLinkTarget(
diff --git a/apps/web/src/modelSelection.ts b/apps/web/src/modelSelection.ts
index 64937a442e7a..1a39f06098ac 100644
--- a/apps/web/src/modelSelection.ts
+++ b/apps/web/src/modelSelection.ts
@@ -10,8 +10,10 @@ import {
   type ServerSettingsPatch,
 } from "@t3tools/contracts";
 import {
+  type CustomModelDefinition,
   createModelSelection,
   normalizeCustomModelSlug,
+  readCustomModelEntries,
   resolveSelectableModel,
 } from "@t3tools/shared/model";
 import { getComposerProviderState } from "./components/chat/composerProviderState";
@@ -55,14 +57,14 @@ function readInstanceCustomModels(
   settings: UnifiedSettings,
   instanceId: ProviderInstanceId,
   driverKind: ProviderDriverKind,
-): ReadonlyArray<string> {
+): ReadonlyArray<CustomModelDefinition> {
   if (driverKind === "antigravity") return [];
   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");
+      return readCustomModelEntries(value);
     }
   }
   const defaultInstanceId = defaultInstanceIdForDriver(driverKind);
@@ -71,9 +73,9 @@ function readInstanceCustomModels(
   }
   const legacyProviders = settings.providers as Record<
     string,
-    { readonly customModels: ReadonlyArray<string> } | undefined
+    { readonly customModels: ReadonlyArray<unknown> } | undefined
   >;
-  return legacyProviders[driverKind]?.customModels ?? [];
+  return readCustomModelEntries(legacyProviders[driverKind]?.customModels ?? []);
 }
 
 export interface AppModelOption {
@@ -151,26 +153,24 @@ function applyInstanceModelPreferences(
   );
 }
 
-export function normalizeCustomModelSlugs(
-  models: Iterable<string | null | undefined>,
+function normalizeCustomModelEntries(
+  models: ReadonlyArray<CustomModelDefinition>,
   builtInModelSlugs: ReadonlySet<string>,
-): string[] {
-  const normalizedModels: string[] = [];
+): CustomModelDefinition[] {
+  const normalizedModels: CustomModelDefinition[] = [];
   const seen = new Set<string>();
 
   for (const candidate of models) {
-    const normalized = normalizeCustomModelSlug(candidate);
     if (
-      !normalized ||
-      normalized.length > MAX_CUSTOM_MODEL_LENGTH ||
-      builtInModelSlugs.has(normalized) ||
-      seen.has(normalized)
+      candidate.slug.length > MAX_CUSTOM_MODEL_LENGTH ||
+      builtInModelSlugs.has(candidate.slug) ||
+      seen.has(candidate.slug)
     ) {
       continue;
     }
 
-    seen.add(normalized);
-    normalizedModels.push(normalized);
+    seen.add(candidate.slug);
+    normalizedModels.push(candidate);
     if (normalizedModels.length >= MAX_CUSTOM_MODEL_COUNT) {
       break;
     }
@@ -179,7 +179,7 @@ export function normalizeCustomModelSlugs(
   return normalizedModels;
 }
 
-export function getAppModelOptions(
+function getAppModelOptions(
   settings: UnifiedSettings,
   providers: ReadonlyArray<ServerProvider>,
   provider: ProviderDriverKind,
@@ -205,17 +205,13 @@ export function getAppModelOptions(
   // see the user's authored custom models.
   const defaultInstanceId = defaultInstanceIdForDriver(provider);
   const customModels = readInstanceCustomModels(settings, defaultInstanceId, provider);
-  for (const slug of normalizeCustomModelSlugs(customModels, builtInModelSlugs)) {
-    if (seen.has(slug)) {
+  for (const entry of normalizeCustomModelEntries(customModels, builtInModelSlugs)) {
+    if (seen.has(entry.slug)) {
       continue;
     }
 
-    seen.add(slug);
-    options.push({
-      slug,
-      name: slug,
-      isCustom: true,
-    });
+    seen.add(entry.slug);
+    options.push({ slug: entry.slug, name: entry.name, isCustom: true });
   }
 
   const preferences = readInstanceModelPreferences(settings, defaultInstanceId);
@@ -257,13 +253,13 @@ export function getAppModelOptionsForInstance(
   );
 
   const customModels = readInstanceCustomModels(settings, entry.instanceId, entry.driverKind);
-  for (const slug of normalizeCustomModelSlugs(customModels, builtInModelSlugs)) {
-    if (seen.has(slug)) {
+  for (const custom of normalizeCustomModelEntries(customModels, builtInModelSlugs)) {
+    if (seen.has(custom.slug)) {
       continue;
     }
 
-    seen.add(slug);
-    options.push({ slug, name: slug, isCustom: true });
+    seen.add(custom.slug);
+    options.push({ slug: custom.slug, name: custom.name, isCustom: true });
   }
 
   const preferences = readInstanceModelPreferences(settings, entry.instanceId);
diff --git a/apps/web/src/onboarding/firstRun.logic.test.ts b/apps/web/src/onboarding/firstRun.logic.test.ts
new file mode 100644
index 000000000000..ca35f6322e3b
--- /dev/null
+++ b/apps/web/src/onboarding/firstRun.logic.test.ts
@@ -0,0 +1,514 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  isFirstRunWorkspaceProvenanceAuthoritative,
+  isFreshFirstRunWorkspace,
+  resolveFirstRunDecision,
+  resolveHostedFirstRunDecision,
+  transitionFirstRunGateState,
+} from "./firstRun.logic";
+
+const freshWorkspace = {
+  enabled: true,
+  hydrated: true,
+  completed: false,
+  bootstrapped: true,
+  authoritative: true,
+  workspaceAuthoritative: true,
+  workspaceProvenanceAuthoritative: true,
+  catalogReady: true,
+  serverConfigAvailable: true,
+  workspaceFresh: true,
+  projectCount: 1,
+  threadCount: 1,
+} as const;
+
+describe("resolveFirstRunDecision", () => {
+  it("opens the wizard for an authoritative fresh workspace", () => {
+    expect(resolveFirstRunDecision(freshWorkspace)).toEqual({
+      decision: "wizard",
+      persistCompletion: false,
+    });
+  });
+
+  it("does not permanently complete onboarding from cached project counts", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        authoritative: false,
+        projectCount: 3,
+        workspaceFresh: false,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: false,
+    });
+  });
+
+  it("backfills completion once existing projects are confirmed by the server", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        projectCount: 3,
+        workspaceFresh: false,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: true,
+    });
+  });
+
+  it("does not complete onboarding while another environment is still bootstrapping", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        bootstrapped: false,
+        projectCount: 3,
+        workspaceFresh: false,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: false,
+    });
+  });
+
+  it("waits for managed environments before treating a workspace as new", () => {
+    expect(resolveFirstRunDecision({ ...freshWorkspace, catalogReady: false })).toEqual({
+      decision: "pending",
+      persistCompletion: false,
+    });
+  });
+
+  it("does not complete onboarding before the environment catalog is ready", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        catalogReady: false,
+        projectCount: 3,
+        workspaceFresh: false,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: false,
+    });
+  });
+
+  it("does not complete onboarding before the server configuration is available", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        projectCount: 3,
+        serverConfigAvailable: false,
+        workspaceFresh: false,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: false,
+    });
+  });
+
+  it("does not complete onboarding from cached remote projects", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        projectCount: 3,
+        workspaceAuthoritative: false,
+        workspaceFresh: false,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: false,
+    });
+  });
+
+  it("does not complete onboarding from a single cached remote project", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        workspaceAuthoritative: false,
+        workspaceFresh: false,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: false,
+    });
+  });
+
+  it("waits for live data before judging a single cached project", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        authoritative: false,
+        workspaceFresh: false,
+      }),
+    ).toEqual({
+      decision: "pending",
+      persistCompletion: false,
+    });
+  });
+
+  it("waits for the completed bootstrap welcome before judging a nonempty workspace", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        workspaceProvenanceAuthoritative: false,
+      }),
+    ).toEqual({
+      decision: "pending",
+      persistCompletion: false,
+    });
+  });
+
+  it("waits when the initial welcome is pending and opens the wizard after completion", () => {
+    const pendingProvenance = isFirstRunWorkspaceProvenanceAuthoritative({
+      welcomeReceived: true,
+      bootstrapStatus: "pending",
+    });
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        workspaceProvenanceAuthoritative: pendingProvenance,
+      }),
+    ).toEqual({ decision: "pending", persistCompletion: false });
+
+    const completedProvenance = isFirstRunWorkspaceProvenanceAuthoritative({
+      welcomeReceived: true,
+      bootstrapStatus: "complete",
+    });
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        workspaceProvenanceAuthoritative: completedProvenance,
+      }),
+    ).toEqual({ decision: "wizard", persistCompletion: false });
+  });
+
+  it("does not wait for server data after onboarding is already complete", () => {
+    expect(
+      resolveFirstRunDecision({
+        ...freshWorkspace,
+        authoritative: false,
+        bootstrapped: false,
+        completed: true,
+        serverConfigAvailable: false,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: false,
+    });
+  });
+});
+
+describe("isFirstRunWorkspaceProvenanceAuthoritative", () => {
+  it("waits for cwd bootstrap when the initial catalog is empty", () => {
+    expect(
+      isFirstRunWorkspaceProvenanceAuthoritative({
+        welcomeReceived: true,
+        bootstrapStatus: "pending",
+      }),
+    ).toBe(false);
+  });
+
+  it("accepts an empty catalog after cwd bootstrap completes", () => {
+    expect(
+      isFirstRunWorkspaceProvenanceAuthoritative({
+        welcomeReceived: true,
+        bootstrapStatus: "complete",
+      }),
+    ).toBe(true);
+  });
+
+  it("waits for a welcome before treating an empty catalog as final", () => {
+    expect(
+      isFirstRunWorkspaceProvenanceAuthoritative({
+        welcomeReceived: false,
+        bootstrapStatus: null,
+      }),
+    ).toBe(false);
+  });
+
+  it("accepts a legacy welcome without bootstrap status", () => {
+    expect(
+      isFirstRunWorkspaceProvenanceAuthoritative({
+        welcomeReceived: true,
+        bootstrapStatus: null,
+      }),
+    ).toBe(true);
+  });
+});
+
+describe("transitionFirstRunGateState", () => {
+  it("shows recovery without mounting the app when evidence stalls", () => {
+    expect(
+      transitionFirstRunGateState({ decision: "pending", stalled: false }, { type: "timeout" }),
+    ).toEqual({ decision: "pending", stalled: true });
+  });
+
+  it.each(["app", "wizard"] as const)(
+    "resolves stalled recovery to %s only after authoritative evidence",
+    (decision) => {
+      expect(
+        transitionFirstRunGateState(
+          { decision: "pending", stalled: true },
+          { type: "evidence", decision },
+        ),
+      ).toEqual({ decision, stalled: false });
+    },
+  );
+
+  it("keeps recovery visible while evidence remains pending", () => {
+    const state = { decision: "pending", stalled: true } as const;
+    expect(transitionFirstRunGateState(state, { type: "evidence", decision: "pending" })).toBe(
+      state,
+    );
+  });
+
+  it("allows authoritative wizard evidence to replace an app decision", () => {
+    expect(
+      transitionFirstRunGateState(
+        { decision: "app", stalled: false },
+        { type: "evidence", decision: "wizard" },
+      ),
+    ).toEqual({ decision: "wizard", stalled: false });
+  });
+});
+
+describe("resolveHostedFirstRunDecision", () => {
+  it("keeps the shell hidden until client settings are hydrated", () => {
+    expect(
+      resolveHostedFirstRunDecision({
+        hydrated: false,
+        completed: false,
+        catalogReady: true,
+        environmentCount: 0,
+      }),
+    ).toEqual({
+      decision: "pending",
+      persistCompletion: false,
+    });
+  });
+
+  it("waits for the saved environment catalog before judging a hosted install", () => {
+    expect(
+      resolveHostedFirstRunDecision({
+        hydrated: true,
+        completed: false,
+        catalogReady: false,
+        environmentCount: 0,
+      }),
+    ).toEqual({
+      decision: "pending",
+      persistCompletion: false,
+    });
+  });
+
+  it("opens onboarding when a hosted install has no saved environments", () => {
+    expect(
+      resolveHostedFirstRunDecision({
+        hydrated: true,
+        completed: false,
+        catalogReady: true,
+        environmentCount: 0,
+      }),
+    ).toEqual({
+      decision: "wizard",
+      persistCompletion: false,
+    });
+  });
+
+  it("backfills onboarding for a hosted install with saved environments", () => {
+    expect(
+      resolveHostedFirstRunDecision({
+        hydrated: true,
+        completed: false,
+        catalogReady: true,
+        environmentCount: 1,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: true,
+    });
+  });
+
+  it("opens the app immediately after hosted onboarding is complete", () => {
+    expect(
+      resolveHostedFirstRunDecision({
+        hydrated: true,
+        completed: true,
+        catalogReady: false,
+        environmentCount: 0,
+      }),
+    ).toEqual({
+      decision: "app",
+      persistCompletion: false,
+    });
+  });
+});
+
+const primaryEnvironmentId = "primary-environment";
+const bootstrapProject = {
+  id: "bootstrap-project",
+  environmentId: primaryEnvironmentId,
+  workspaceRoot: "/projects/current",
+};
+const bootstrapThread = {
+  id: "bootstrap-thread",
+  projectId: bootstrapProject.id,
+  environmentId: primaryEnvironmentId,
+  latestTurn: null,
+  latestUserMessageAt: null,
+  session: null,
+};
+
+describe("isFreshFirstRunWorkspace", () => {
+  it("accepts an empty workspace", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        projects: [],
+        threads: [],
+      }),
+    ).toBe(true);
+  });
+
+  it("accepts only the unused project and thread created from the server cwd", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current/",
+        bootstrapProjectId: bootstrapProject.id,
+        bootstrapThreadId: bootstrapThread.id,
+        bootstrapProjectCreated: true,
+        bootstrapThreadCreated: true,
+        projects: [bootstrapProject],
+        threads: [bootstrapThread],
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects an existing unused cwd project and thread reused by startup", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        bootstrapProjectId: bootstrapProject.id,
+        bootstrapThreadId: bootstrapThread.id,
+        bootstrapProjectCreated: false,
+        bootstrapThreadCreated: false,
+        projects: [bootstrapProject],
+        threads: [bootstrapThread],
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects a nonempty workspace when an older server omits creation provenance", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        bootstrapProjectId: bootstrapProject.id,
+        bootstrapThreadId: bootstrapThread.id,
+        projects: [bootstrapProject],
+        threads: [bootstrapThread],
+      }),
+    ).toBe(false);
+  });
+
+  it("normalizes Windows project paths before checking the bootstrap workspace", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "C:\\Projects\\Current\\",
+        bootstrapProjectId: bootstrapProject.id,
+        bootstrapThreadId: bootstrapThread.id,
+        bootstrapProjectCreated: true,
+        bootstrapThreadCreated: true,
+        projects: [{ ...bootstrapProject, workspaceRoot: "c:/projects/current" }],
+        threads: [bootstrapThread],
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects projects from another environment even when their paths match", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        projects: [{ ...bootstrapProject, environmentId: "remote-environment" }],
+        threads: [],
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects threads from another environment", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        projects: [bootstrapProject],
+        threads: [{ ...bootstrapThread, environmentId: "remote-environment" }],
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects a thread that does not belong to the bootstrap project", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        projects: [bootstrapProject],
+        threads: [{ ...bootstrapThread, projectId: "another-project" }],
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects a thread when there is no bootstrap project", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        projects: [],
+        threads: [bootstrapThread],
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects a bootstrap thread that already has a user message", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        projects: [bootstrapProject],
+        threads: [
+          {
+            ...bootstrapThread,
+            latestUserMessageAt: "2026-08-23T12:00:00.000Z",
+          },
+        ],
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects a bootstrap thread that has started a turn", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        projects: [bootstrapProject],
+        threads: [{ ...bootstrapThread, latestTurn: { id: "first-turn" } }],
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects a bootstrap thread that has a provider session", () => {
+    expect(
+      isFreshFirstRunWorkspace({
+        primaryEnvironmentId,
+        serverCwd: "/projects/current",
+        projects: [bootstrapProject],
+        threads: [{ ...bootstrapThread, session: { status: "ready" } }],
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/apps/web/src/onboarding/firstRun.logic.ts b/apps/web/src/onboarding/firstRun.logic.ts
new file mode 100644
index 000000000000..013dbb02d527
--- /dev/null
+++ b/apps/web/src/onboarding/firstRun.logic.ts
@@ -0,0 +1,184 @@
+import { normalizeProjectPathForComparison } from "@t3tools/shared/path";
+
+export type FirstRunDecision = "pending" | "app" | "wizard";
+
+export interface FirstRunGateState {
+  readonly decision: FirstRunDecision;
+  readonly stalled: boolean;
+}
+
+type FirstRunGateEvent =
+  | { readonly type: "evidence"; readonly decision: FirstRunDecision }
+  | { readonly type: "timeout" };
+
+interface FirstRunWorkspaceInput {
+  readonly primaryEnvironmentId: string | null;
+  readonly serverCwd: string | null;
+  readonly bootstrapProjectId?: string | undefined;
+  readonly bootstrapThreadId?: string | undefined;
+  readonly bootstrapProjectCreated?: boolean | undefined;
+  readonly bootstrapThreadCreated?: boolean | undefined;
+  readonly projects: ReadonlyArray<{
+    readonly id: string;
+    readonly environmentId: string;
+    readonly workspaceRoot: string;
+  }>;
+  readonly threads: ReadonlyArray<{
+    readonly id: string;
+    readonly projectId: string;
+    readonly environmentId: string;
+    readonly latestTurn: unknown;
+    readonly latestUserMessageAt: string | null;
+    readonly session: unknown;
+  }>;
+}
+
+interface FirstRunDecisionInput {
+  readonly enabled: boolean;
+  readonly hydrated: boolean;
+  readonly completed: boolean;
+  readonly bootstrapped: boolean;
+  readonly authoritative: boolean;
+  readonly workspaceAuthoritative: boolean;
+  readonly workspaceProvenanceAuthoritative: boolean;
+  readonly catalogReady: boolean;
+  readonly serverConfigAvailable: boolean;
+  readonly workspaceFresh: boolean;
+  readonly projectCount: number;
+  readonly threadCount: number;
+}
+
+interface HostedFirstRunDecisionInput {
+  readonly hydrated: boolean;
+  readonly completed: boolean;
+  readonly catalogReady: boolean;
+  readonly environmentCount: number;
+}
+
+export function isFirstRunWorkspaceProvenanceAuthoritative(input: {
+  readonly welcomeReceived: boolean;
+  readonly bootstrapStatus: "pending" | "complete" | null;
+}): boolean {
+  // An empty catalog is not final while cwd auto-bootstrap is pending. Older
+  // servers omit bootstrapStatus, so a received welcome with null stays valid.
+  return input.welcomeReceived && input.bootstrapStatus !== "pending";
+}
+
+/** Keeps the authenticated app unmounted until workspace evidence settles. */
+export function transitionFirstRunGateState(
+  state: FirstRunGateState,
+  event: FirstRunGateEvent,
+): FirstRunGateState {
+  if (event.type === "timeout") {
+    return state.decision === "pending" && !state.stalled ? { ...state, stalled: true } : state;
+  }
+
+  if (
+    state.decision === "wizard" ||
+    event.decision === "pending" ||
+    (state.decision === "app" && event.decision !== "wizard")
+  ) {
+    return state;
+  }
+
+  return { decision: event.decision, stalled: false };
+}
+
+/** Only a project and thread created by this startup count as a fresh nonempty workspace. */
+export function isFreshFirstRunWorkspace(input: FirstRunWorkspaceInput): boolean {
+  if (input.projects.length > 1 || input.threads.length > 1) {
+    return false;
+  }
+
+  const bootstrapProject = input.projects[0];
+  if (bootstrapProject !== undefined) {
+    if (
+      input.bootstrapProjectCreated !== true ||
+      input.bootstrapProjectId !== bootstrapProject.id ||
+      input.serverCwd === null ||
+      bootstrapProject.environmentId !== input.primaryEnvironmentId ||
+      normalizeProjectPathForComparison(bootstrapProject.workspaceRoot) !==
+        normalizeProjectPathForComparison(input.serverCwd)
+    ) {
+      return false;
+    }
+  }
+
+  const bootstrapThread = input.threads[0];
+  if (bootstrapThread === undefined) {
+    return true;
+  }
+
+  return (
+    bootstrapProject !== undefined &&
+    input.bootstrapThreadCreated === true &&
+    input.bootstrapThreadId === bootstrapThread.id &&
+    bootstrapThread.environmentId === input.primaryEnvironmentId &&
+    bootstrapThread.projectId === bootstrapProject.id &&
+    bootstrapThread.latestTurn === null &&
+    bootstrapThread.latestUserMessageAt === null &&
+    bootstrapThread.session === null
+  );
+}
+
+/** Cached projects may open the app, but only live workspace data may complete onboarding. */
+export function resolveFirstRunDecision(input: FirstRunDecisionInput): {
+  readonly decision: FirstRunDecision;
+  readonly persistCompletion: boolean;
+} {
+  if (!input.enabled || (input.hydrated && input.completed)) {
+    return { decision: "app", persistCompletion: false };
+  }
+
+  if (!input.hydrated) {
+    return { decision: "pending", persistCompletion: false };
+  }
+
+  if (input.projectCount > 1 || input.threadCount > 1) {
+    return {
+      decision: "app",
+      persistCompletion:
+        input.bootstrapped &&
+        input.authoritative &&
+        input.workspaceAuthoritative &&
+        input.catalogReady &&
+        input.serverConfigAvailable,
+    };
+  }
+
+  if (
+    !input.bootstrapped ||
+    !input.authoritative ||
+    !input.workspaceProvenanceAuthoritative ||
+    !input.catalogReady ||
+    !input.serverConfigAvailable
+  ) {
+    return { decision: "pending", persistCompletion: false };
+  }
+
+  return input.workspaceFresh
+    ? { decision: "wizard", persistCompletion: false }
+    : { decision: "app", persistCompletion: input.workspaceAuthoritative };
+}
+
+/** Hosted onboarding depends on saved environments because there is no primary server. */
+export function resolveHostedFirstRunDecision(input: HostedFirstRunDecisionInput): {
+  readonly decision: FirstRunDecision;
+  readonly persistCompletion: boolean;
+} {
+  if (!input.hydrated) {
+    return { decision: "pending", persistCompletion: false };
+  }
+
+  if (input.completed) {
+    return { decision: "app", persistCompletion: false };
+  }
+
+  if (!input.catalogReady) {
+    return { decision: "pending", persistCompletion: false };
+  }
+
+  return input.environmentCount === 0
+    ? { decision: "wizard", persistCompletion: false }
+    : { decision: "app", persistCompletion: true };
+}
diff --git a/apps/web/src/onboarding/firstRun.ts b/apps/web/src/onboarding/firstRun.ts
new file mode 100644
index 000000000000..4daafc7cc924
--- /dev/null
+++ b/apps/web/src/onboarding/firstRun.ts
@@ -0,0 +1,16 @@
+import { useCallback } from "react";
+
+import { ensureClientSettingsHydrated, persistClientSettingsUpdate } from "../hooks/useSettings";
+
+/**
+ * Marks first-run onboarding finished (or skipped) so FirstRunGate never
+ * routes to the welcome wizard again. The gate itself lives in
+ * `components/onboarding/FirstRunGate.tsx`.
+ */
+export function useCompleteOnboarding(): () => Promise<void> {
+  return useCallback(async () => {
+    await ensureClientSettingsHydrated();
+    const onboardingCompletedAt = new Date().toISOString();
+    await persistClientSettingsUpdate((current) => ({ ...current, onboardingCompletedAt }));
+  }, []);
+}
diff --git a/apps/web/src/onboarding/projectImport.logic.test.ts b/apps/web/src/onboarding/projectImport.logic.test.ts
new file mode 100644
index 000000000000..07028abd28b4
--- /dev/null
+++ b/apps/web/src/onboarding/projectImport.logic.test.ts
@@ -0,0 +1,245 @@
+import { EnvironmentId, ProjectId, type AgentSessionProjectCandidate } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  partitionOnboardingProjects,
+  resolveOnboardingLandingProject,
+  resolveOnboardingProjectId,
+} from "./projectImport.logic";
+
+const now = Date.parse("2026-08-22T12:00:00.000Z");
+
+function candidate(
+  path: string,
+  overrides: Partial<AgentSessionProjectCandidate> = {},
+): AgentSessionProjectCandidate {
+  return {
+    title: path.split("/").at(-1) ?? path,
+    path,
+    sources: ["codex"],
+    threadCount: 1,
+    lastActiveAt: "2026-08-20T12:00:00.000Z",
+    alreadyImported: false,
+    ...overrides,
+  };
+}
+
+describe("partitionOnboardingProjects", () => {
+  it("keeps existing projects available for thread history import", () => {
+    const imported = candidate("/projects/current", { alreadyImported: true });
+    const available = candidate("/projects/other");
+
+    expect(partitionOnboardingProjects([imported, available], now)).toEqual({
+      available: [imported, available],
+      recent: [imported, available],
+    });
+  });
+
+  it("keeps projects older than 30 days out of the default selection", () => {
+    const recent = candidate("/projects/recent");
+    const older = candidate("/projects/older", {
+      lastActiveAt: "2026-07-01T12:00:00.000Z",
+    });
+
+    expect(partitionOnboardingProjects([recent, older], now)).toEqual({
+      available: [recent, older],
+      recent: [recent],
+    });
+  });
+
+  it("keeps future activity out of the default selection", () => {
+    const recent = candidate("/projects/recent");
+    const future = candidate("/projects/future", {
+      lastActiveAt: "2026-08-23T12:00:00.000Z",
+    });
+
+    expect(partitionOnboardingProjects([recent, future], now)).toEqual({
+      available: [recent, future],
+      recent: [recent],
+    });
+  });
+});
+
+describe("resolveOnboardingProjectId", () => {
+  const localEnvironmentId = EnvironmentId.make("local");
+  const remoteEnvironmentId = EnvironmentId.make("remote");
+  const localProjectId = ProjectId.make("local-project");
+
+  it("uses the scanned project ID before the project reaches the client", () => {
+    expect(
+      resolveOnboardingProjectId(
+        [],
+        localEnvironmentId,
+        candidate("/projects/repo", { projectId: localProjectId }),
+      ),
+    ).toBe(localProjectId);
+  });
+
+  it("uses the scanned project ID when the client still has an older project at that root", () => {
+    expect(
+      resolveOnboardingProjectId(
+        [
+          {
+            id: ProjectId.make("stale-project"),
+            environmentId: localEnvironmentId,
+            workspaceRoot: "/projects/repo",
+          },
+        ],
+        localEnvironmentId,
+        candidate("/projects/repo", { projectId: localProjectId }),
+      ),
+    ).toBe(localProjectId);
+  });
+
+  it("returns null to create a project when neither the scan nor the client has a project ID", () => {
+    expect(
+      resolveOnboardingProjectId([], localEnvironmentId, candidate("/projects/new")),
+    ).toBeNull();
+  });
+
+  it("finds an existing project by normalized root in the target environment", () => {
+    expect(
+      resolveOnboardingProjectId(
+        [
+          {
+            id: ProjectId.make("remote-project"),
+            environmentId: remoteEnvironmentId,
+            workspaceRoot: "C:\\Work\\Repo",
+          },
+          {
+            id: localProjectId,
+            environmentId: localEnvironmentId,
+            workspaceRoot: "C:\\Work\\Repo\\",
+          },
+        ],
+        localEnvironmentId,
+        candidate("c:/work/repo"),
+      ),
+    ).toBe(localProjectId);
+  });
+
+  it("does not reuse a project from another environment", () => {
+    expect(
+      resolveOnboardingProjectId(
+        [
+          {
+            id: ProjectId.make("remote-project"),
+            environmentId: remoteEnvironmentId,
+            workspaceRoot: "/projects/repo",
+          },
+        ],
+        localEnvironmentId,
+        candidate("/projects/repo"),
+      ),
+    ).toBeNull();
+  });
+
+  it("finds an alias after the scanner returns its persisted project root", () => {
+    expect(
+      resolveOnboardingProjectId(
+        [
+          {
+            id: localProjectId,
+            environmentId: localEnvironmentId,
+            workspaceRoot: "/real/projects/repo",
+          },
+        ],
+        localEnvironmentId,
+        candidate("/real/projects/repo"),
+      ),
+    ).toBe(localProjectId);
+  });
+
+  it("finds the current root owner when the scan has no project ID", () => {
+    const recreatedProjectId = ProjectId.make("recreated-project");
+    expect(
+      resolveOnboardingProjectId(
+        [
+          {
+            id: localProjectId,
+            environmentId: localEnvironmentId,
+            workspaceRoot: "/projects/other",
+          },
+          {
+            id: recreatedProjectId,
+            environmentId: localEnvironmentId,
+            workspaceRoot: "/projects/repo",
+          },
+        ],
+        localEnvironmentId,
+        candidate("/projects/repo"),
+      ),
+    ).toBe(recreatedProjectId);
+  });
+
+  it("does not reuse a moved project when the scan has no project ID", () => {
+    expect(
+      resolveOnboardingProjectId(
+        [
+          {
+            id: localProjectId,
+            environmentId: localEnvironmentId,
+            workspaceRoot: "/projects/moved",
+          },
+        ],
+        localEnvironmentId,
+        candidate("/projects/repo"),
+      ),
+    ).toBeNull();
+  });
+});
+
+describe("resolveOnboardingLandingProject", () => {
+  it("skips a failed first project for a later project with imported history", () => {
+    expect(
+      resolveOnboardingLandingProject(
+        ["/projects/failed", "/projects/imported"],
+        new Map([["/projects/imported", "imported"]]),
+        new Map([["/projects/imported", "imported"]]),
+      ),
+    ).toBe("imported");
+  });
+
+  it("prefers a partial first import that added history", () => {
+    expect(
+      resolveOnboardingLandingProject(
+        ["/projects/partial", "/projects/complete"],
+        new Map([["/projects/partial", "partial"]]),
+        new Map([["/projects/complete", "complete"]]),
+      ),
+    ).toBe("partial");
+  });
+
+  it("uses a completed zero-history project when no import added history", () => {
+    expect(
+      resolveOnboardingLandingProject(
+        ["/projects/empty", "/projects/failed"],
+        new Map(),
+        new Map([["/projects/empty", "empty"]]),
+      ),
+    ).toBe("empty");
+  });
+
+  it("keeps an earlier successful import available on retry", () => {
+    expect(
+      resolveOnboardingLandingProject(
+        ["/projects/imported", "/projects/retry"],
+        new Map([["/projects/imported", "imported"]]),
+        new Map([["/projects/imported", "imported"]]),
+      ),
+    ).toBe("imported");
+  });
+
+  it("ignores cached successes outside the current retry selection", () => {
+    expect(
+      resolveOnboardingLandingProject(
+        ["/projects/current"],
+        new Map([["/projects/previous", "previous"]]),
+        new Map([
+          ["/projects/previous", "previous"],
+          ["/projects/current", "current"],
+        ]),
+      ),
+    ).toBe("current");
+  });
+});
diff --git a/apps/web/src/onboarding/projectImport.logic.ts b/apps/web/src/onboarding/projectImport.logic.ts
new file mode 100644
index 000000000000..d723b911b665
--- /dev/null
+++ b/apps/web/src/onboarding/projectImport.logic.ts
@@ -0,0 +1,55 @@
+import { findProjectByPath } from "@t3tools/client-runtime/state/projects";
+import type { AgentSessionProjectCandidate, EnvironmentId, ProjectId } from "@t3tools/contracts";
+
+const RECENT_PROJECT_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Existing projects still need their agent history imported, so every scan candidate is offered. */
+export function partitionOnboardingProjects(
+  candidates: ReadonlyArray<AgentSessionProjectCandidate>,
+  now = Date.now(),
+) {
+  const cutoff = now - RECENT_PROJECT_WINDOW_MS;
+
+  return {
+    available: candidates,
+    recent: candidates.filter((candidate) => {
+      if (candidate.lastActiveAt === null) return false;
+      const lastActiveAt = Date.parse(candidate.lastActiveAt);
+      return lastActiveAt >= cutoff && lastActiveAt <= now;
+    }),
+  };
+}
+
+/** Use the server's project match before the client snapshot, which can lag behind the scan. */
+export function resolveOnboardingProjectId(
+  projects: ReadonlyArray<{
+    readonly id: ProjectId;
+    readonly environmentId: EnvironmentId;
+    readonly workspaceRoot: string;
+  }>,
+  environmentId: EnvironmentId,
+  candidate: Pick<AgentSessionProjectCandidate, "path" | "projectId">,
+): ProjectId | null {
+  if (candidate.projectId !== undefined) return candidate.projectId;
+  const environmentProjects = projects.filter((project) => project.environmentId === environmentId);
+  const currentRootMatch = findProjectByPath(environmentProjects, candidate.path);
+  if (currentRootMatch !== undefined) return currentRootMatch.id;
+  return null;
+}
+
+/** Prefer a selected project with imported history, then a completed empty import. */
+export function resolveOnboardingLandingProject<T>(
+  selection: ReadonlyArray<string>,
+  projectsWithImportedHistory: ReadonlyMap<string, T>,
+  completedProjects: ReadonlyMap<string, T>,
+): T | undefined {
+  for (const path of selection) {
+    const project = projectsWithImportedHistory.get(path);
+    if (project !== undefined) return project;
+  }
+  for (const path of selection) {
+    const project = completedProjects.get(path);
+    if (project !== undefined) return project;
+  }
+  return undefined;
+}
diff --git a/apps/web/src/onboarding/providerReadiness.logic.test.ts b/apps/web/src/onboarding/providerReadiness.logic.test.ts
new file mode 100644
index 000000000000..ab742ac51b44
--- /dev/null
+++ b/apps/web/src/onboarding/providerReadiness.logic.test.ts
@@ -0,0 +1,317 @@
+import {
+  DEFAULT_SERVER_SETTINGS,
+  ProviderDriverKind,
+  ProviderInstanceId,
+  type ServerProvider,
+} from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  getOnboardingProviderState,
+  resolveOnboardingProviderLoginCommand,
+  selectOnboardingProvidersByDriver,
+} from "./providerReadiness.logic";
+
+const readyCodex: ServerProvider = {
+  instanceId: ProviderInstanceId.make("codex"),
+  driver: ProviderDriverKind.make("codex"),
+  enabled: true,
+  installed: true,
+  version: "1.0.0",
+  status: "ready",
+  auth: { status: "unknown" },
+  checkedAt: "2026-08-23T00:00:00.000Z",
+  models: [],
+  slashCommands: [],
+  skills: [],
+};
+
+describe("getOnboardingProviderState", () => {
+  it("treats an enabled Codex provider with ready status and unknown authentication as ready", () => {
+    expect(getOnboardingProviderState(readyCodex)).toBe("ready");
+  });
+
+  it("treats authenticated providers as ready only when their provider status is ready", () => {
+    expect(getOnboardingProviderState({ ...readyCodex, auth: { status: "authenticated" } })).toBe(
+      "ready",
+    );
+    expect(
+      getOnboardingProviderState({
+        ...readyCodex,
+        auth: { status: "authenticated" },
+        status: "error",
+      }),
+    ).toBe("attention");
+    expect(
+      getOnboardingProviderState({
+        ...readyCodex,
+        auth: { status: "authenticated" },
+        status: "warning",
+      }),
+    ).toBe("attention");
+  });
+
+  it("offers sign-in only when the server reports an authentication failure", () => {
+    expect(
+      getOnboardingProviderState({
+        ...readyCodex,
+        status: "error",
+        auth: { status: "unauthenticated" },
+      }),
+    ).toBe("signIn");
+    expect(getOnboardingProviderState({ ...readyCodex, status: "error" })).toBe("attention");
+    expect(getOnboardingProviderState({ ...readyCodex, status: "warning" })).toBe("attention");
+  });
+
+  it("does not offer installation or sign-in for disabled providers", () => {
+    expect(getOnboardingProviderState({ ...readyCodex, enabled: false, installed: false })).toBe(
+      "disabled",
+    );
+    expect(getOnboardingProviderState({ ...readyCodex, status: "disabled" })).toBe("disabled");
+  });
+
+  it("offers installation only when an enabled provider is missing", () => {
+    expect(getOnboardingProviderState({ ...readyCodex, installed: false, status: "error" })).toBe(
+      "install",
+    );
+  });
+
+  it("waits for a provider snapshot before offering an action", () => {
+    expect(getOnboardingProviderState(undefined)).toBe("checking");
+  });
+});
+
+describe("selectOnboardingProvidersByDriver", () => {
+  it("prefers a ready instance with unknown authentication to an unauthenticated instance", () => {
+    const signedOutCodex: ServerProvider = {
+      ...readyCodex,
+      instanceId: ProviderInstanceId.make("codex_work"),
+      status: "error",
+      auth: { status: "unauthenticated" },
+    };
+
+    expect(selectOnboardingProvidersByDriver([signedOutCodex, readyCodex]).get("codex")).toBe(
+      readyCodex,
+    );
+  });
+
+  it("prefers a provider with an actionable sign-in over a failed provider", () => {
+    const failedCodex: ServerProvider = { ...readyCodex, status: "error" };
+    const signedOutCodex: ServerProvider = {
+      ...readyCodex,
+      instanceId: ProviderInstanceId.make("codex_work"),
+      status: "error",
+      auth: { status: "unauthenticated" },
+    };
+
+    expect(selectOnboardingProvidersByDriver([failedCodex, signedOutCodex]).get("codex")).toBe(
+      signedOutCodex,
+    );
+  });
+
+  it("prefers installed providers over missing or disabled instances", () => {
+    const disabledCodex: ServerProvider = { ...readyCodex, enabled: false };
+    const missingCodex: ServerProvider = {
+      ...readyCodex,
+      instanceId: ProviderInstanceId.make("codex_work"),
+      installed: false,
+      status: "error",
+    };
+
+    expect(
+      selectOnboardingProvidersByDriver([disabledCodex, missingCodex, readyCodex]).get("codex"),
+    ).toBe(readyCodex);
+  });
+
+  it("handles provider snapshots that have not arrived", () => {
+    expect(selectOnboardingProvidersByDriver(undefined).size).toBe(0);
+  });
+
+  it("keeps a ready custom account when the default account is signed out", () => {
+    const signedOutDefault: ServerProvider = {
+      ...readyCodex,
+      status: "error",
+      auth: { status: "unauthenticated" },
+    };
+    const readyCustom: ServerProvider = {
+      ...readyCodex,
+      instanceId: ProviderInstanceId.make("codex_work"),
+    };
+
+    expect(selectOnboardingProvidersByDriver([signedOutDefault, readyCustom]).get("codex")).toBe(
+      readyCustom,
+    );
+  });
+});
+
+describe("resolveOnboardingProviderLoginCommand", () => {
+  it("uses the selected Codex account binary", () => {
+    const provider = { ...readyCodex, instanceId: ProviderInstanceId.make("codex_work") };
+
+    expect(
+      resolveOnboardingProviderLoginCommand(
+        provider,
+        {
+          ...DEFAULT_SERVER_SETTINGS,
+          providerInstances: {
+            [provider.instanceId]: {
+              driver: provider.driver,
+              config: { binaryPath: "/opt/codex-work/bin/codex" },
+            },
+          },
+        },
+        "linux",
+      ),
+    ).toBe("/opt/codex-work/bin/codex login");
+  });
+
+  it("uses the selected Claude account binary", () => {
+    const provider: ServerProvider = {
+      ...readyCodex,
+      driver: ProviderDriverKind.make("claudeAgent"),
+      instanceId: ProviderInstanceId.make("claude_work"),
+    };
+
+    expect(
+      resolveOnboardingProviderLoginCommand(
+        provider,
+        {
+          ...DEFAULT_SERVER_SETTINGS,
+          providerInstances: {
+            [provider.instanceId]: {
+              driver: provider.driver,
+              config: { binaryPath: "/opt/claude-work/bin/claude" },
+            },
+          },
+        },
+        "linux",
+      ),
+    ).toBe("/opt/claude-work/bin/claude auth login");
+  });
+
+  it("quotes a Codex path with spaces for PowerShell", () => {
+    expect(
+      resolveOnboardingProviderLoginCommand(
+        readyCodex,
+        {
+          ...DEFAULT_SERVER_SETTINGS,
+          providers: {
+            ...DEFAULT_SERVER_SETTINGS.providers,
+            codex: {
+              ...DEFAULT_SERVER_SETTINGS.providers.codex,
+              binaryPath: "C:\\Program Files\\Codex & Tools\\codex.exe",
+            },
+          },
+        },
+        "windows",
+      ),
+    ).toBe("& 'C:\\Program Files\\Codex & Tools\\codex.exe' login");
+  });
+
+  it("quotes a Claude path with shell metacharacters on POSIX", () => {
+    const provider: ServerProvider = {
+      ...readyCodex,
+      driver: ProviderDriverKind.make("claudeAgent"),
+      instanceId: ProviderInstanceId.make("claude"),
+    };
+
+    expect(
+      resolveOnboardingProviderLoginCommand(
+        provider,
+        {
+          ...DEFAULT_SERVER_SETTINGS,
+          providers: {
+            ...DEFAULT_SERVER_SETTINGS.providers,
+            claudeAgent: {
+              ...DEFAULT_SERVER_SETTINGS.providers.claudeAgent,
+              binaryPath: "/opt/Claude Tools/$current/claude",
+            },
+          },
+        },
+        "linux",
+      ),
+    ).toBe("'/opt/Claude Tools/$current/claude' auth login");
+  });
+
+  it.each([
+    ["~/my tools/codex", "~/'my tools/codex' login"],
+    ["~\\my tools/codex", "~/'my tools/codex' login"],
+    ["~/tools/codex's build", `~/'tools/codex'"'"'s build' login`],
+    ["~\\tools\\codex's build", `~/'tools\\codex'"'"'s build' login`],
+    ["~/tools/codex; echo unsafe", "~/'tools/codex; echo unsafe' login"],
+  ])("keeps the home prefix expandable while quoting %s", (binaryPath, expectedCommand) => {
+    expect(
+      resolveOnboardingProviderLoginCommand(
+        readyCodex,
+        {
+          ...DEFAULT_SERVER_SETTINGS,
+          providers: {
+            ...DEFAULT_SERVER_SETTINGS.providers,
+            codex: {
+              ...DEFAULT_SERVER_SETTINGS.providers.codex,
+              binaryPath,
+            },
+          },
+        },
+        "linux",
+      ),
+    ).toBe(expectedCommand);
+  });
+
+  it.each(["darwin", "linux"] as const)("quotes backslashes in a Codex path on %s", (platform) => {
+    expect(
+      resolveOnboardingProviderLoginCommand(
+        readyCodex,
+        {
+          ...DEFAULT_SERVER_SETTINGS,
+          providers: {
+            ...DEFAULT_SERVER_SETTINGS.providers,
+            codex: {
+              ...DEFAULT_SERVER_SETTINGS.providers.codex,
+              binaryPath: "/opt/codex\\work/codex",
+            },
+          },
+        },
+        platform,
+      ),
+    ).toBe("'/opt/codex\\work/codex' login");
+  });
+
+  it("keeps a plain Windows path unquoted", () => {
+    expect(
+      resolveOnboardingProviderLoginCommand(
+        readyCodex,
+        {
+          ...DEFAULT_SERVER_SETTINGS,
+          providers: {
+            ...DEFAULT_SERVER_SETTINGS.providers,
+            codex: {
+              ...DEFAULT_SERVER_SETTINGS.providers.codex,
+              binaryPath: "C:\\Tools\\codex.exe",
+            },
+          },
+        },
+        "windows",
+      ),
+    ).toBe("C:\\Tools\\codex.exe login");
+  });
+
+  it("uses the default command when an old server reports an unknown shell", () => {
+    expect(
+      resolveOnboardingProviderLoginCommand(
+        readyCodex,
+        {
+          ...DEFAULT_SERVER_SETTINGS,
+          providers: {
+            ...DEFAULT_SERVER_SETTINGS.providers,
+            codex: {
+              ...DEFAULT_SERVER_SETTINGS.providers.codex,
+              binaryPath: "/opt/Codex Tools/codex",
+            },
+          },
+        },
+        "unknown",
+      ),
+    ).toBe("codex login");
+  });
+});
diff --git a/apps/web/src/onboarding/providerReadiness.logic.ts b/apps/web/src/onboarding/providerReadiness.logic.ts
new file mode 100644
index 000000000000..939b4c64cd64
--- /dev/null
+++ b/apps/web/src/onboarding/providerReadiness.logic.ts
@@ -0,0 +1,99 @@
+import {
+  ClaudeSettings,
+  CodexSettings,
+  type ExecutionEnvironmentPlatformOs,
+  type ServerProvider,
+  type ServerSettings,
+} from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+const decodeClaudeSettings = Schema.decodeUnknownOption(ClaudeSettings);
+const decodeCodexSettings = Schema.decodeUnknownOption(CodexSettings);
+const SAFE_SHELL_BINARY_PATTERN = /^[A-Za-z0-9_./:\\-]+$/;
+
+function quoteProviderBinary(
+  binaryPath: string,
+  fallback: string,
+  platform: ExecutionEnvironmentPlatformOs,
+): string {
+  if (
+    SAFE_SHELL_BINARY_PATTERN.test(binaryPath) &&
+    (platform === "windows" || !binaryPath.includes("\\"))
+  ) {
+    return binaryPath;
+  }
+  if (platform === "windows") return `& '${binaryPath.replaceAll("'", "''")}'`;
+  if (platform === "darwin" || platform === "linux") {
+    if (binaryPath.startsWith("~/") || binaryPath.startsWith("~\\")) {
+      return `~/'${binaryPath.slice(2).replaceAll("'", `'"'"'`)}'`;
+    }
+    return `'${binaryPath.replaceAll("'", `'"'"'`)}'`;
+  }
+  return fallback;
+}
+
+export function getOnboardingProviderState(provider: ServerProvider | undefined) {
+  if (provider === undefined) return "checking";
+  if (!provider.enabled || provider.status === "disabled") return "disabled";
+  if (!provider.installed) return "install";
+  if (provider.auth.status === "unauthenticated") return "signIn";
+  if (provider.status === "ready") return "ready";
+  return "attention";
+}
+
+const PROVIDER_STATE_PRIORITY = {
+  checking: 0,
+  disabled: 1,
+  install: 2,
+  attention: 3,
+  signIn: 4,
+  ready: 5,
+} as const;
+
+/** Select the most usable configured instance for each provider driver. */
+export function selectOnboardingProvidersByDriver(
+  providers: ReadonlyArray<ServerProvider> | null | undefined,
+) {
+  const providersByDriver = new Map<string, ServerProvider>();
+
+  for (const provider of providers ?? []) {
+    const existing = providersByDriver.get(provider.driver);
+    if (
+      existing === undefined ||
+      PROVIDER_STATE_PRIORITY[getOnboardingProviderState(provider)] >
+        PROVIDER_STATE_PRIORITY[getOnboardingProviderState(existing)]
+    ) {
+      providersByDriver.set(provider.driver, provider);
+    }
+  }
+
+  return providersByDriver;
+}
+
+/** Use the selected provider instance's binary when the setup terminal opens its login flow. */
+export function resolveOnboardingProviderLoginCommand(
+  provider: ServerProvider,
+  settings: ServerSettings,
+  platform: ExecutionEnvironmentPlatformOs,
+): string {
+  const instance = settings.providerInstances[provider.instanceId];
+
+  if (provider.driver === "claudeAgent") {
+    const config = decodeClaudeSettings(
+      instance ? (instance.config ?? {}) : settings.providers.claudeAgent,
+    );
+    const binaryPath = Option.isSome(config) ? config.value.binaryPath : "claude";
+    return `${quoteProviderBinary(binaryPath, "claude", platform)} auth login`;
+  }
+
+  if (provider.driver === "codex") {
+    const config = decodeCodexSettings(
+      instance ? (instance.config ?? {}) : settings.providers.codex,
+    );
+    const binaryPath = Option.isSome(config) ? config.value.binaryPath : "codex";
+    return `${quoteProviderBinary(binaryPath, "codex", platform)} login`;
+  }
+
+  return provider.driver;
+}
diff --git a/apps/web/src/onboarding/targetEnvironment.logic.test.ts b/apps/web/src/onboarding/targetEnvironment.logic.test.ts
new file mode 100644
index 000000000000..9928f83b27db
--- /dev/null
+++ b/apps/web/src/onboarding/targetEnvironment.logic.test.ts
@@ -0,0 +1,211 @@
+import {
+  BearerConnectionTarget,
+  PrimaryConnectionTarget,
+  RelayConnectionTarget,
+  SshConnectionTarget,
+} from "@t3tools/client-runtime/connection";
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  isOnboardingRelayEnvironment,
+  resolveOnboardingTargetEnvironment,
+} from "./targetEnvironment.logic";
+
+const primaryEnvironment = {
+  environmentId: EnvironmentId.make("primary"),
+  connection: { phase: "connected" },
+  entry: {
+    target: new PrimaryConnectionTarget({
+      environmentId: EnvironmentId.make("primary"),
+      label: "This computer",
+      httpBaseUrl: "http://127.0.0.1:3773",
+      wsBaseUrl: "ws://127.0.0.1:3773",
+    }),
+  },
+  label: "This computer",
+} as const;
+
+const olderRelay = {
+  environmentId: EnvironmentId.make("older-remote"),
+  connection: { phase: "connected" },
+  entry: {
+    target: new RelayConnectionTarget({
+      environmentId: EnvironmentId.make("older-remote"),
+      label: "Older computer",
+    }),
+  },
+  label: "Older computer",
+} as const;
+
+const newerRelay = {
+  environmentId: EnvironmentId.make("newer-relay"),
+  connection: { phase: "connected" },
+  entry: {
+    target: new RelayConnectionTarget({
+      environmentId: EnvironmentId.make("newer-relay"),
+      label: "New computer",
+    }),
+  },
+  label: "New computer",
+} as const;
+
+const pairedRemote = {
+  environmentId: EnvironmentId.make("paired-remote"),
+  connection: { phase: "connected" },
+  entry: {
+    target: new BearerConnectionTarget({
+      environmentId: EnvironmentId.make("paired-remote"),
+      label: "Direct computer",
+      connectionId: "paired-remote",
+    }),
+  },
+  label: "Direct computer",
+} as const;
+
+const sshEnvironment = {
+  environmentId: EnvironmentId.make("ssh-remote"),
+  connection: { phase: "connected" },
+  entry: {
+    target: new SshConnectionTarget({
+      environmentId: EnvironmentId.make("ssh-remote"),
+      label: "SSH computer",
+      connectionId: "ssh-remote",
+    }),
+  },
+  label: "SSH computer",
+} as const;
+
+const desktopLocalEnvironment = {
+  environmentId: EnvironmentId.make("desktop-local-wsl"),
+  connection: { phase: "connected" },
+  entry: {
+    target: new BearerConnectionTarget({
+      environmentId: EnvironmentId.make("desktop-local-wsl"),
+      label: "WSL",
+      connectionId: "local:wsl:Ubuntu",
+    }),
+  },
+  label: "WSL",
+} as const;
+
+describe("resolveOnboardingTargetEnvironment", () => {
+  it("waits for the exact paired machine instead of using an older connected machine", () => {
+    const pendingPairedRemote = { ...pairedRemote, connection: { phase: "connecting" } };
+
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "direct",
+        environments: [primaryEnvironment, olderRelay, pendingPairedRemote],
+        primaryEnvironment,
+        pairedEnvironmentId: pairedRemote.environmentId,
+      }),
+    ).toBeNull();
+  });
+
+  it("uses the exact paired machine once it connects", () => {
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "direct",
+        environments: [primaryEnvironment, olderRelay, pairedRemote],
+        primaryEnvironment,
+        pairedEnvironmentId: pairedRemote.environmentId,
+      }),
+    ).toBe(pairedRemote);
+  });
+
+  it("waits for a newly paired machine that has not appeared in the catalog", () => {
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "direct",
+        environments: [primaryEnvironment, olderRelay],
+        primaryEnvironment,
+        pairedEnvironmentId: pairedRemote.environmentId,
+      }),
+    ).toBeNull();
+  });
+
+  it("uses the primary machine for local onboarding", () => {
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "local",
+        environments: [primaryEnvironment, olderRelay],
+        primaryEnvironment,
+        pairedEnvironmentId: null,
+      }),
+    ).toBe(primaryEnvironment);
+  });
+
+  it("does not substitute a remote machine when the local primary is offline", () => {
+    const offlinePrimary = { ...primaryEnvironment, connection: { phase: "disconnected" } };
+
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "local",
+        environments: [offlinePrimary, olderRelay],
+        primaryEnvironment: offlinePrimary,
+        pairedEnvironmentId: null,
+      }),
+    ).toBeNull();
+  });
+
+  it("uses the newest connected remote when no exact machine was selected", () => {
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "connect",
+        environments: [primaryEnvironment, olderRelay, newerRelay],
+        primaryEnvironment,
+        pairedEnvironmentId: null,
+      }),
+    ).toBe(newerRelay);
+  });
+
+  it("ignores direct, SSH, and desktop-managed connections in Connect mode", () => {
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "connect",
+        environments: [
+          primaryEnvironment,
+          olderRelay,
+          pairedRemote,
+          sshEnvironment,
+          desktopLocalEnvironment,
+        ],
+        primaryEnvironment,
+        pairedEnvironmentId: null,
+      }),
+    ).toBe(olderRelay);
+  });
+
+  it("uses the primary computer when no relay connection exists", () => {
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "connect",
+        environments: [primaryEnvironment, pairedRemote, sshEnvironment, desktopLocalEnvironment],
+        primaryEnvironment,
+        pairedEnvironmentId: null,
+      }),
+    ).toBe(primaryEnvironment);
+  });
+
+  it("falls back to the connected primary when no remote is available", () => {
+    expect(
+      resolveOnboardingTargetEnvironment({
+        mode: "connect",
+        environments: [primaryEnvironment],
+        primaryEnvironment,
+        pairedEnvironmentId: null,
+      }),
+    ).toBe(primaryEnvironment);
+  });
+});
+
+describe("isOnboardingRelayEnvironment", () => {
+  it("includes only T3 Connect relay targets", () => {
+    expect(
+      [olderRelay, pairedRemote, sshEnvironment, desktopLocalEnvironment].filter(
+        isOnboardingRelayEnvironment,
+      ),
+    ).toEqual([olderRelay]);
+  });
+});
diff --git a/apps/web/src/onboarding/targetEnvironment.logic.ts b/apps/web/src/onboarding/targetEnvironment.logic.ts
new file mode 100644
index 000000000000..6045b8c441e2
--- /dev/null
+++ b/apps/web/src/onboarding/targetEnvironment.logic.ts
@@ -0,0 +1,49 @@
+import type { ConnectionTarget } from "@t3tools/client-runtime/connection";
+import type { EnvironmentId } from "@t3tools/contracts";
+
+interface OnboardingEnvironment {
+  readonly environmentId: EnvironmentId;
+  readonly connection: { readonly phase: string };
+  readonly entry: { readonly target: ConnectionTarget };
+}
+
+export function isOnboardingRelayEnvironment(
+  environment: Pick<OnboardingEnvironment, "entry">,
+): boolean {
+  return environment.entry.target._tag === "RelayConnectionTarget";
+}
+
+/** Keep a directly paired machine pinned while its initial connection completes. */
+export function resolveOnboardingTargetEnvironment<TEnvironment extends OnboardingEnvironment>({
+  mode,
+  environments,
+  primaryEnvironment,
+  pairedEnvironmentId,
+}: {
+  readonly mode: "local" | "connect" | "direct";
+  readonly environments: ReadonlyArray<TEnvironment>;
+  readonly primaryEnvironment: TEnvironment | null;
+  readonly pairedEnvironmentId: EnvironmentId | null;
+}): TEnvironment | null {
+  if (mode === "direct" && pairedEnvironmentId !== null) {
+    const pairedEnvironment = environments.find(
+      (environment) => environment.environmentId === pairedEnvironmentId,
+    );
+    return pairedEnvironment?.connection.phase === "connected" ? pairedEnvironment : null;
+  }
+
+  const connectedRelayEnvironments = environments.filter(
+    (environment) =>
+      environment.connection.phase === "connected" && isOnboardingRelayEnvironment(environment),
+  );
+
+  if (mode === "connect" && connectedRelayEnvironments.length > 0) {
+    return connectedRelayEnvironments[connectedRelayEnvironments.length - 1] ?? null;
+  }
+
+  if (primaryEnvironment?.connection.phase === "connected") {
+    return primaryEnvironment;
+  }
+
+  return mode === "local" ? null : (connectedRelayEnvironments[0] ?? null);
+}
diff --git a/apps/web/src/panelAnimations.test.tsx b/apps/web/src/panelAnimations.test.tsx
new file mode 100644
index 000000000000..2475425086f2
--- /dev/null
+++ b/apps/web/src/panelAnimations.test.tsx
@@ -0,0 +1,64 @@
+import { act, useLayoutEffect } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { usePanelNavigationSuppression } from "./panelAnimations";
+
+let renderer: ReactTestRenderer | null = null;
+let pendingFrames: FrameRequestCallback[] = [];
+let observed: boolean[] = [];
+
+function SuppressionProbe({ navigationKey }: { navigationKey: string }) {
+  const suppressed = usePanelNavigationSuppression(navigationKey);
+  useLayoutEffect(() => {
+    observed.push(suppressed);
+  }, [suppressed]);
+  return null;
+}
+
+beforeEach(() => {
+  pendingFrames = [];
+  observed = [];
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  vi.stubGlobal("window", {
+    requestAnimationFrame: vi.fn((callback: FrameRequestCallback) => {
+      pendingFrames.push(callback);
+      return pendingFrames.length;
+    }),
+    cancelAnimationFrame: vi.fn(),
+  });
+});
+
+afterEach(async () => {
+  await act(() => renderer?.unmount());
+  vi.unstubAllGlobals();
+});
+
+async function paintPendingFrame() {
+  const callback = pendingFrames.shift();
+  await act(() => callback?.(0));
+}
+
+describe("usePanelNavigationSuppression", () => {
+  it("suppresses initial and navigated panel state until each route has painted", async () => {
+    await act(() => {
+      renderer = create(<SuppressionProbe navigationKey="/thread/one" />);
+    });
+    expect(observed.at(-1)).toBe(true);
+
+    await paintPendingFrame();
+    expect(observed.at(-1)).toBe(true);
+    await paintPendingFrame();
+    expect(observed.at(-1)).toBe(false);
+
+    await act(() => {
+      renderer?.update(<SuppressionProbe navigationKey="/thread/two" />);
+    });
+    expect(observed.at(-1)).toBe(true);
+
+    await paintPendingFrame();
+    expect(observed.at(-1)).toBe(true);
+    await paintPendingFrame();
+    expect(observed.at(-1)).toBe(false);
+  });
+});
diff --git a/apps/web/src/panelAnimations.ts b/apps/web/src/panelAnimations.ts
index f606a3f930d5..11dd597ec561 100644
--- a/apps/web/src/panelAnimations.ts
+++ b/apps/web/src/panelAnimations.ts
@@ -1,9 +1,36 @@
-import { useEffect, useRef, useState } from "react";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
 import { type PanelAnimationDurationMs } from "@t3tools/contracts/settings";
 
 import { useMediaQuery } from "./hooks/useMediaQuery";
 import { useClientSettings } from "./hooks/useSettings";
 
+const PanelAnimationSuppressionContext = createContext(false);
+
+export const PanelAnimationSuppressionProvider = PanelAnimationSuppressionContext.Provider;
+
+/**
+ * Suppresses panel motion for the first painted frame of an initial route or navigation.
+ * State restored by a route must be visible immediately; later user actions can animate.
+ */
+export function usePanelNavigationSuppression(navigationKey: string): boolean {
+  const [paintedNavigationKey, setPaintedNavigationKey] = useState<string | null>(null);
+  const suppressed = paintedNavigationKey !== navigationKey;
+
+  useEffect(() => {
+    if (!suppressed) return;
+    let releaseFrame = 0;
+    const paintFrame = window.requestAnimationFrame(() => {
+      releaseFrame = window.requestAnimationFrame(() => setPaintedNavigationKey(navigationKey));
+    });
+    return () => {
+      window.cancelAnimationFrame(paintFrame);
+      window.cancelAnimationFrame(releaseFrame);
+    };
+  }, [navigationKey, suppressed]);
+
+  return suppressed;
+}
+
 export function observeResponsiveBreakpointFade(options: {
   target: HTMLElement;
   container: HTMLElement;
@@ -47,7 +74,8 @@ export function usePanelAnimationSettings(): {
 } {
   const durationMs = useClientSettings((settings) => settings.panelAnimationDurationMs);
   const prefersReducedMotion = useMediaQuery("(prefers-reduced-motion: reduce)");
-  return { active: durationMs > 0 && !prefersReducedMotion, durationMs };
+  const suppressed = useContext(PanelAnimationSuppressionContext);
+  return { active: durationMs > 0 && !prefersReducedMotion && !suppressed, durationMs };
 }
 
 /** Keeps closing panel content mounted until its opt-in transition ends. */
diff --git a/apps/web/src/previewStateStore.test.ts b/apps/web/src/previewStateStore.test.ts
index 321dd68c09aa..f9956f9c02c8 100644
--- a/apps/web/src/previewStateStore.test.ts
+++ b/apps/web/src/previewStateStore.test.ts
@@ -18,12 +18,11 @@ import {
   readThreadPreviewState,
   reconcilePreviewServerSessions,
   rememberPreviewUrl,
-  removePreviewThread,
   resetPreviewStateForTests,
-  subscribeThreadPreviewState,
   setActivePreviewTab,
   updatePreviewServerSnapshot,
 } from "./previewStateStore";
+import { appAtomRegistry } from "./rpc/atomRegistry";
 
 const environmentId = "env-1" as EnvironmentId;
 const ref = scopeThreadRef(environmentId, ThreadId.make("thread-1"));
@@ -353,7 +352,7 @@ describe("previewStateStore (single-tab)", () => {
       },
     };
     let updateCount = 0;
-    const unsubscribe = subscribeThreadPreviewState(ref, () => {
+    const unsubscribe = appAtomRegistry.subscribe(previewStateAtom(scopedThreadKey(ref)), () => {
       updateCount += 1;
     });
 
@@ -609,12 +608,4 @@ describe("previewStateStore (single-tab)", () => {
       `http://localhost:${5000 + __testing.RECENT_URL_LIMIT + 4}/`,
     );
   });
-
-  it("removeThread strips the entry", () => {
-    const snapshot = makeSnapshot();
-    applyPreviewServerSnapshot(ref, snapshot);
-    removePreviewThread(ref);
-    const state = readThreadPreviewState(ref);
-    expect(state).toEqual(__testing.EMPTY_THREAD_PREVIEW_STATE);
-  });
 });
diff --git a/apps/web/src/previewStateStore.ts b/apps/web/src/previewStateStore.ts
index eb1052feeb87..1e7ec3706618 100644
--- a/apps/web/src/previewStateStore.ts
+++ b/apps/web/src/previewStateStore.ts
@@ -173,19 +173,6 @@ export function readThreadPreviewState(ref: ScopedThreadRef): ThreadPreviewState
   return appAtomRegistry.get(previewStateAtom(scopedThreadKey(ref)));
 }
 
-export function subscribeThreadPreviewState(
-  ref: ScopedThreadRef,
-  listener: (state: ThreadPreviewState, previous: ThreadPreviewState) => void,
-): () => void {
-  const atom = previewStateAtom(scopedThreadKey(ref));
-  let previous = appAtomRegistry.get(atom);
-  return appAtomRegistry.subscribe(atom, (state) => {
-    const prior = previous;
-    previous = state;
-    listener(state, prior);
-  });
-}
-
 export function applyPreviewServerEvent(ref: ScopedThreadRef, event: PreviewEvent): void {
   updateThreadPreviewState(ref, (current) => {
     if (current.serverEpoch !== null && event.serverEpoch !== current.serverEpoch) return current;
@@ -472,13 +459,6 @@ export function rememberPreviewUrl(ref: ScopedThreadRef, url: string): void {
   }));
 }
 
-export function removePreviewThread(ref: ScopedThreadRef): void {
-  const threadKey = scopedThreadKey(ref);
-  appAtomRegistry.set(previewStateAtom(threadKey), EMPTY_THREAD_PREVIEW_STATE);
-  syncActivePreviewThread(threadKey, EMPTY_THREAD_PREVIEW_STATE);
-  changedPreviewThreadKeys.delete(threadKey);
-}
-
 export function isPreviewSupportedInRuntime(): boolean {
   if (typeof window === "undefined") return false;
   return Boolean(window.desktopBridge?.preview);
diff --git a/apps/web/src/proposedPlan.ts b/apps/web/src/proposedPlan.ts
index 48186392e8a3..525be17a72e0 100644
--- a/apps/web/src/proposedPlan.ts
+++ b/apps/web/src/proposedPlan.ts
@@ -70,8 +70,11 @@ function sanitizePlanFileSegment(input: string): string {
   return sanitized.length > 0 ? sanitized : "plan";
 }
 
+/** Prefix of the message the app sends when the user approves a plan. */
+export const PLAN_IMPLEMENTATION_PROMPT_PREFIX = "PLEASE IMPLEMENT THIS PLAN:\n";
+
 export function buildPlanImplementationPrompt(planMarkdown: string): string {
-  return `PLEASE IMPLEMENT THIS PLAN:\n${planMarkdown.trim()}`;
+  return `${PLAN_IMPLEMENTATION_PROMPT_PREFIX}${planMarkdown.trim()}`;
 }
 
 export function resolvePlanFollowUpSubmission(input: { draftText: string; planMarkdown: string }): {
diff --git a/apps/web/src/providerInstances.ts b/apps/web/src/providerInstances.ts
index 428bbe91317b..fe95cf54890a 100644
--- a/apps/web/src/providerInstances.ts
+++ b/apps/web/src/providerInstances.ts
@@ -298,7 +298,7 @@ export function sortProviderInstanceEntries(
  * Look up a single instance entry by exact `instanceId`. Missing snapshots
  * are not inferred from driver kind in UI routing code.
  */
-export function getProviderInstanceEntry(
+function getProviderInstanceEntry(
   providers: ReadonlyArray<ServerProvider>,
   instanceId: ProviderInstanceId,
 ): ProviderInstanceEntry | undefined {
diff --git a/apps/web/src/providerModels.ts b/apps/web/src/providerModels.ts
index b1bed7020e62..568e2b839b91 100644
--- a/apps/web/src/providerModels.ts
+++ b/apps/web/src/providerModels.ts
@@ -30,7 +30,7 @@ export function getProviderModels(
   return getProviderSnapshot(providers, provider)?.models ?? [];
 }
 
-export function getProviderSnapshot(
+function getProviderSnapshot(
   providers: ReadonlyArray<ServerProvider>,
   provider: ProviderDriverKind,
 ): ServerProvider | undefined {
@@ -38,13 +38,6 @@ export function getProviderSnapshot(
   return providers.find((candidate) => candidate.instanceId === defaultInstanceId);
 }
 
-export function getProviderInteractionModeToggle(
-  providers: ReadonlyArray<ServerProvider>,
-  provider: ProviderDriverKind,
-): boolean {
-  return getProviderSnapshot(providers, provider)?.showInteractionModeToggle ?? true;
-}
-
 // 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.
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index b30c7a609777..4810e16c79d1 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -9,6 +9,7 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
+import { Route as WelcomeRouteImport } from './routes/welcome'
 import { Route as UsageRouteImport } from './routes/usage'
 import { Route as SettingsRouteImport } from './routes/settings'
 import { Route as PairRouteImport } from './routes/pair'
@@ -31,6 +32,11 @@ import { Route as ChatDraftDraftIdRouteImport } from './routes/_chat.draft.$draf
 import { Route as ChatEnvironmentIdThreadIdRouteImport } from './routes/_chat.$environmentId.$threadId'
 import { Route as ChatLeadAgentEnvironmentIdProjectIdRouteImport } from './routes/_chat.lead-agent.$environmentId.$projectId'
 
+const WelcomeRoute = WelcomeRouteImport.update({
+  id: '/welcome',
+  path: '/welcome',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const UsageRoute = UsageRouteImport.update({
   id: '/usage',
   path: '/usage',
@@ -144,6 +150,7 @@ export interface FileRoutesByFullPath {
   '/pair': typeof PairRoute
   '/settings': typeof SettingsRouteWithChildren
   '/usage': typeof UsageRoute
+  '/welcome': typeof WelcomeRoute
   '/pull-requests': typeof ChatPullRequestsRoute
   '/connect/callback': typeof ConnectCallbackRoute
   '/projects/$projectKey': typeof ProjectsProjectKeyRoute
@@ -165,6 +172,7 @@ export interface FileRoutesByTo {
   '/pair': typeof PairRoute
   '/settings': typeof SettingsRouteWithChildren
   '/usage': typeof UsageRoute
+  '/welcome': typeof WelcomeRoute
   '/pull-requests': typeof ChatPullRequestsRoute
   '/connect/callback': typeof ConnectCallbackRoute
   '/projects/$projectKey': typeof ProjectsProjectKeyRoute
@@ -189,6 +197,7 @@ export interface FileRoutesById {
   '/pair': typeof PairRoute
   '/settings': typeof SettingsRouteWithChildren
   '/usage': typeof UsageRoute
+  '/welcome': typeof WelcomeRoute
   '/_chat/pull-requests': typeof ChatPullRequestsRoute
   '/connect_/callback': typeof ConnectCallbackRoute
   '/projects/$projectKey': typeof ProjectsProjectKeyRoute
@@ -214,6 +223,7 @@ export interface FileRouteTypes {
     | '/pair'
     | '/settings'
     | '/usage'
+    | '/welcome'
     | '/pull-requests'
     | '/connect/callback'
     | '/projects/$projectKey'
@@ -235,6 +245,7 @@ export interface FileRouteTypes {
     | '/pair'
     | '/settings'
     | '/usage'
+    | '/welcome'
     | '/pull-requests'
     | '/connect/callback'
     | '/projects/$projectKey'
@@ -258,6 +269,7 @@ export interface FileRouteTypes {
     | '/pair'
     | '/settings'
     | '/usage'
+    | '/welcome'
     | '/_chat/pull-requests'
     | '/connect_/callback'
     | '/projects/$projectKey'
@@ -282,12 +294,20 @@ export interface RootRouteChildren {
   PairRoute: typeof PairRoute
   SettingsRoute: typeof SettingsRouteWithChildren
   UsageRoute: typeof UsageRoute
+  WelcomeRoute: typeof WelcomeRoute
   ConnectCallbackRoute: typeof ConnectCallbackRoute
   ProjectsProjectKeyRoute: typeof ProjectsProjectKeyRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/welcome': {
+      id: '/welcome'
+      path: '/welcome'
+      fullPath: '/welcome'
+      preLoaderRoute: typeof WelcomeRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/usage': {
       id: '/usage'
       path: '/usage'
@@ -491,6 +511,7 @@ const rootRouteChildren: RootRouteChildren = {
   PairRoute: PairRoute,
   SettingsRoute: SettingsRouteWithChildren,
   UsageRoute: UsageRoute,
+  WelcomeRoute: WelcomeRoute,
   ConnectCallbackRoute: ConnectCallbackRoute,
   ProjectsProjectKeyRoute: ProjectsProjectKeyRoute,
 }
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 64e858d186eb..12cdd946f6c4 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -16,6 +16,7 @@ import { resolveServerBackedAppDisplayName } from "../branding.logic";
 import { AppSidebarLayout } from "../components/AppSidebarLayout";
 import { CommandPalette } from "../components/CommandPalette";
 import { ConfirmDialogHost } from "../components/ConfirmDialogHost";
+import { FirstRunGate } from "../components/onboarding/FirstRunGate";
 import { ConnectOnboardingDialog } from "../components/cloud/ConnectOnboardingDialog";
 import { RelayClientInstallDialog } from "../components/cloud/RelayClientInstallDialog";
 import { SshPasswordPromptDialog } from "../components/desktop/SshPasswordPromptDialog";
@@ -97,6 +98,13 @@ function RootRouteView() {
   const pathname = useLocation({ select: (location) => location.pathname });
   const { authGateState } = Route.useRouteContext();
   const primaryEnvironmentAuthenticated = authGateState.status === "authenticated";
+  const returningFromWelcomeRef = useRef(pathname === "/welcome");
+
+  useEffect(() => {
+    if (pathname === "/welcome") {
+      returningFromWelcomeRef.current = true;
+    }
+  }, [pathname]);
 
   useEffect(() => {
     const frame = window.requestAnimationFrame(() => {
@@ -116,6 +124,19 @@ function RootRouteView() {
     );
   }
 
+  // The welcome wizard is full-screen like /pair, but keeps toasts so its
+  // connect/import actions can report failures.
+  if (pathname === "/welcome") {
+    return (
+      <ToastProvider>
+        <DocumentTitleSync />
+        <ContrastAppearanceSync />
+        <FontAppearanceSync />
+        <Outlet />
+      </ToastProvider>
+    );
+  }
+
   if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
     return (
       <>
@@ -133,6 +154,10 @@ function RootRouteView() {
     </CommandPalette>
   );
 
+  // FirstRunGate holds back everything below it — including EventRouter,
+  // whose welcome payload navigates into a thread — until the first-run
+  // decision is known, so a fresh install renders nothing (not the shell,
+  // not a flash of threads) before landing on the welcome wizard.
   return (
     <ToastProvider>
       <AnchoredToastProvider>
@@ -141,21 +166,28 @@ function RootRouteView() {
         <EnvironmentThemeSync />
         <GlassAppearanceSync />
         <FontAppearanceSync />
-        {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
-        {primaryEnvironmentAuthenticated ? <DesktopAppActivationCoordinator /> : null}
-        <RelayClientInstallDialog />
-        <ConnectOnboardingDialog />
-        <SshPasswordPromptDialog />
-        <ConfirmDialogHost />
-        <SlowRpcRequestToastCoordinator />
-        <HostedStaticEnvironmentBootstrap />
-        {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
-        {primaryEnvironmentAuthenticated ? <PlanAgentSelectionHeal /> : null}
-        {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
-        {appShell}
-        {/* Above the router: a theme draft is judged by walking the app, so the
-            editor has to survive navigation away from settings. */}
-        <ThemeEditorHost />
+        <FirstRunGate
+          enabled={primaryEnvironmentAuthenticated}
+          hostedStatic={authGateState.status === "hosted-static"}
+        >
+          {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
+          {primaryEnvironmentAuthenticated ? <DesktopAppActivationCoordinator /> : null}
+          <RelayClientInstallDialog />
+          <ConnectOnboardingDialog />
+          <SshPasswordPromptDialog />
+          <ConfirmDialogHost />
+          <SlowRpcRequestToastCoordinator />
+          <HostedStaticEnvironmentBootstrap />
+          {primaryEnvironmentAuthenticated ? (
+            <EventRouter skipInitialBootstrapNavigation={returningFromWelcomeRef.current} />
+          ) : null}
+          {primaryEnvironmentAuthenticated ? <PlanAgentSelectionHeal /> : null}
+          {primaryEnvironmentAuthenticated ? <ProviderUpdateLaunchNotification /> : null}
+          {appShell}
+          {/* Above the router: a theme draft is judged by walking the app, so the
+              editor has to survive navigation away from settings. */}
+          <ThemeEditorHost />
+        </FirstRunGate>
       </AnchoredToastProvider>
     </ToastProvider>
   );
@@ -381,7 +413,11 @@ function AuthenticatedTracingBootstrap() {
   return null;
 }
 
-function EventRouter() {
+function EventRouter({
+  skipInitialBootstrapNavigation,
+}: {
+  readonly skipInitialBootstrapNavigation: boolean;
+}) {
   const navigate = useNavigate();
   const pathname = useLocation({ select: (loc) => loc.pathname });
   const projectGroupingSettings = useClientSettings(selectProjectGroupingSettings);
@@ -394,6 +430,7 @@ function EventRouter() {
   const serverWelcome = useAtomValue(primaryServerWelcomeAtom);
   const readPathname = useEffectEvent(() => pathname);
   const handledBootstrapThreadIdRef = useRef<string | null>(null);
+  const skipInitialBootstrapNavigationRef = useRef(skipInitialBootstrapNavigation);
   const handledConfigEventRef = useRef(serverConfigEvent);
   const [keybindingsToastController] = useState<KeybindingsUpdateToastController>(() =>
     createKeybindingsUpdateToastController({}),
@@ -425,6 +462,11 @@ function EventRouter() {
       if (readPathname() !== "/") {
         return;
       }
+      if (skipInitialBootstrapNavigationRef.current) {
+        skipInitialBootstrapNavigationRef.current = false;
+        handledBootstrapThreadIdRef.current = payload.bootstrapThreadId;
+        return;
+      }
       if (handledBootstrapThreadIdRef.current === payload.bootstrapThreadId) {
         return;
       }
diff --git a/apps/web/src/routes/_chat.index.tsx b/apps/web/src/routes/_chat.index.tsx
index ba96e8986a97..6a53ee024548 100644
--- a/apps/web/src/routes/_chat.index.tsx
+++ b/apps/web/src/routes/_chat.index.tsx
@@ -21,10 +21,11 @@ import { hasCloudPublicConfig } from "~/cloud/publicConfig";
 
 function ChatIndexRouteView() {
   const { authGateState } = Route.useRouteContext();
-  const { environments } = useEnvironments();
+  const { environments, isReady } = useEnvironments();
 
-  if (authGateState.status === "hosted-static" && environments.length === 0) {
-    return <HostedStaticOnboardingState />;
+  if (authGateState.status === "hosted-static") {
+    if (!isReady) return null;
+    if (environments.length === 0) return <HostedStaticOnboardingState />;
   }
 
   return <IndexDraftLanding />;
@@ -79,6 +80,8 @@ function IndexDraftLanding() {
       />
     ) : null;
   }
+  // First-run routing to the welcome wizard happens in FirstRunGate at the
+  // root, before this route ever renders.
   return <NoProjectsHero />;
 }
 
diff --git a/apps/web/src/routes/_chat.pull-requests.tsx b/apps/web/src/routes/_chat.pull-requests.tsx
index bcc22daa4a9d..37522ea3b0a2 100644
--- a/apps/web/src/routes/_chat.pull-requests.tsx
+++ b/apps/web/src/routes/_chat.pull-requests.tsx
@@ -86,6 +86,7 @@ import {
   writePullRequestListPreferences,
 } from "../components/pullRequest/pullRequestListPreferences";
 import { assignProjectsToEnvironments } from "../components/pullRequest/pullRequestProjectAssignment.logic";
+import { pullRequestFilterProjects } from "../components/pullRequest/pullRequestProjectFilter.logic";
 import { environmentMachineIcon } from "../components/EnvironmentMachineIcon";
 import { PullRequestDetailPanel } from "../components/pullRequest/PullRequestDetailPanel";
 import {
@@ -356,27 +357,6 @@ function PullRequestsRouteView() {
       ),
     [environments],
   );
-  const scopedProjects = useMemo(() => {
-    // Two machines can hold the same repository, so a title the workspace carries twice is told
-    // apart by the environment it lives on rather than left as two identical rows.
-    const titleCounts = new Map<string, number>();
-    for (const project of projects) {
-      titleCounts.set(project.title, (titleCounts.get(project.title) ?? 0) + 1);
-    }
-    return projects
-      .map((project) => ({
-        id: project.id,
-        environmentId: project.environmentId,
-        title:
-          (titleCounts.get(project.title) ?? 0) > 1
-            ? `${project.title} · ${environmentLabels.get(project.environmentId) ?? project.environmentId}`
-            : project.title,
-        workspaceRoot: project.workspaceRoot,
-        faviconPath: project.faviconPath ?? null,
-        projectIcon: project.projectIcon ?? null,
-      }))
-      .toSorted((left, right) => left.title.localeCompare(right.title));
-  }, [environmentLabels, projects]);
   // The scope the URL asks for, once the environments have had their say about whether it exists.
   const scopedProjectId = useMemo(
     () => resolveProjectScope(search.projectId, projects, projectsKnown),
@@ -386,6 +366,10 @@ function PullRequestsRouteView() {
     () => findScopedProject(projects, scopedEnvironmentId, scopedProjectId),
     [projects, scopedEnvironmentId, scopedProjectId],
   );
+  const scopedProjects = useMemo(
+    () => pullRequestFilterProjects(projects, environmentLabels, scopedProject),
+    [environmentLabels, projects, scopedProject],
+  );
 
   // A link from a thread or the sidebar only knows the repository, so the owning project is
   // resolved here; an explicit `projectId` in the URL still wins.
@@ -826,7 +810,7 @@ function PullRequestsRouteView() {
   // from the first moment rather than the second: a button that stays live through the slow half
   // of its own work is a button that gets pressed again, and buys the whole cascade twice.
   const [invalidating, setInvalidating] = useState(false);
-  const refreshFromHost = async () => {
+  const refreshFromHost = async (includeDetail = true) => {
     const requestedStatsScope = statsScopeRef.current;
     setInvalidating(true);
     try {
@@ -838,11 +822,7 @@ function PullRequestsRouteView() {
     } finally {
       setInvalidating(false);
     }
-    refreshList();
-    baselineQuery.refresh();
-    facetQuery.refresh();
-    authoredQuery.refresh();
-    reviewingQuery.refresh();
+    refreshList(true);
     const visible = visibleStatsKeys.current;
     const batches = pullRequestStatsRefreshBatches({
       requestedScope: requestedStatsScope,
@@ -855,7 +835,7 @@ function PullRequestsRouteView() {
       setStatsTargetState({ key: requestedStatsScope.key, batches });
       statsQuery.refresh(batches.map(({ environmentId, input }) => ({ environmentId, input })));
     }
-    setDetailRefreshToken((token) => token + 1);
+    if (includeDetail) setDetailRefreshToken((token) => token + 1);
   };
   const refreshing = invalidating || listQuery.isPending;
 
@@ -955,7 +935,7 @@ function PullRequestsRouteView() {
         environmentKey,
         scope: scopeKey,
         query: sentQuery,
-        data,
+        data: { ...data, entries: ordered?.key === filterKey ? ordered.entries : data.entries },
         ...(partitions === undefined ? {} : { partitions }),
       };
     });
@@ -1017,7 +997,7 @@ function PullRequestsRouteView() {
   // `ordered` is declared above, ahead of the snapshot write, but grown here from this round's
   // own answer.
   useEffect(() => {
-    if (!answered) return;
+    if (!answered || listQuery.isPending || (listQuery.error && listQuery.data === null)) return;
     setOrdered((previous) => {
       if (previous === null || previous.key !== filterKey) {
         return {
@@ -1045,7 +1025,15 @@ function PullRequestsRouteView() {
       // reads, so its order stands; a row that moved was updated, and moving is the news.
       return { key: filterKey, entries: rankPullRequestMatches(answered.entries, sentParsed.text) };
     });
-  }, [answered, filterKey, sentCursors, sentParsed.text]);
+  }, [
+    answered,
+    filterKey,
+    sentCursors,
+    sentParsed.text,
+    listQuery.isPending,
+    listQuery.error,
+    listQuery.data,
+  ]);
 
   // Carrying on where the last answer stopped, and only raising the page size for the hosts that
   // could not say where that was.
@@ -1081,11 +1069,20 @@ function PullRequestsRouteView() {
   // re-reads only its own slice, so the rows loaded before it would never see a merge, a close,
   // or a retitle. Going back to a single page long enough to cover everything on screen lets the
   // merge above bring every row up to date in place.
-  const refreshList = () => {
+  const refreshList = (includeRelated = false) => {
+    const related = includeRelated
+      ? [
+          ...baselineTargets,
+          ...facetTargets,
+          ...partitionTargets.authored,
+          ...partitionTargets.reviewing,
+        ]
+      : [];
     if (sentCursors === null) {
-      listQuery.refresh();
+      listQuery.refresh([...listTargets, ...related]);
       return;
     }
+    if (related.length > 0) listQuery.refresh(related);
     const loadedCount = ordered?.key === filterKey ? ordered.entries.length : pageSize;
     setPage({
       key: filterKey,
@@ -1117,9 +1114,7 @@ function PullRequestsRouteView() {
   // host's rate limit.
   useLiveRefresh(
     () => {
-      refreshList();
-      authoredQuery.refresh();
-      reviewingQuery.refresh();
+      refreshList(true);
     },
     { enabled: pullRequestsSupported },
   );
@@ -1209,54 +1204,6 @@ function PullRequestsRouteView() {
   );
 
   const scrollRef = useRef<HTMLDivElement>(null);
-  const sentinelRef = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    const sentinel = sentinelRef.current;
-    // A failed page must stop the observer. Retained rows keep the sentinel on screen, so
-    // re-arming it after a failure would ask for the next page again, forever.
-    //
-    // Rows on screen are also what makes reaching the sentinel mean anything: with none, it
-    // sits directly below the empty state and is always in view, so a search that matches
-    // nothing would page through the whole host on its own — one listing of every repository
-    // per step — while the reader looks at an empty page. With nothing to scroll past, the
-    // next page is asked for rather than assumed.
-    if (
-      !sentinel ||
-      entries.length === 0 ||
-      listData?.truncated !== true ||
-      listQuery.isPending ||
-      listQuery.error !== null ||
-      // The rows on screen belong to the previous question, so nothing about them says where
-      // this one carries on from. Growing the page under them would answer neither.
-      showingCarried ||
-      // Asking past the cap is refused, which would strand the list on an error the retry
-      // could never clear, so growth stops here and the rest stays on the host. A continuation
-      // does not grow the page at all, so the cap does not apply to it.
-      (!canContinue && pageSize >= MAX_PAGE_SIZE)
-    ) {
-      return;
-    }
-    const observer = new IntersectionObserver(
-      (observed) => {
-        if (observed.some((entry) => entry.isIntersecting)) {
-          loadMore();
-        }
-      },
-      // Start the next page slightly before the sentinel is on screen.
-      { root: scrollRef.current, rootMargin: "240px" },
-    );
-    observer.observe(sentinel);
-    return () => observer.disconnect();
-  }, [
-    entries.length,
-    filterKey,
-    canContinue,
-    listData?.truncated,
-    listQuery.error,
-    listQuery.isPending,
-    pageSize,
-    showingCarried,
-  ]);
 
   /**
    * The line counts, asked for once the rows are on screen. On GitHub they are forty per cent of
@@ -1307,8 +1254,8 @@ function PullRequestsRouteView() {
     viewers,
   ]);
 
-  // Date sorts keep optional line-count reads near the viewport. Size sorts need every loaded
-  // count before their order is final. Received counts stay cached across both policies.
+  // Date sorts keep optional line-count reads near the viewport. Size and readiness sorts need
+  // every loaded count before their order is final. Counts stay cached across both policies.
   const entriesByStatsKey = useRef<ReadonlyMap<string, EnvironmentPullRequestEntry>>(new Map());
   entriesByStatsKey.current = new Map(
     groups.flatMap((group) =>
@@ -1633,7 +1580,7 @@ function PullRequestsRouteView() {
         />
       ) : firstLoad ? (
         <PullRequestListGhost rows={7} />
-      ) : listQuery.error && listData === null ? (
+      ) : listQuery.error && entries.length === 0 ? (
         <PullRequestsUnavailableState error={listQuery.error} onRetry={() => listQuery.refresh()} />
       ) : carriedToNothing ? (
         <PullRequestListGhost rows={7} />
@@ -1699,22 +1646,33 @@ function PullRequestsRouteView() {
         </div>
       )}
 
-      {listQuery.error && listData !== null ? (
+      {listQuery.error && entries.length > 0 ? (
         <div className="flex items-center justify-between gap-3 rounded-lg border border-amber-500/30 bg-amber-500/5 px-3 py-2 text-xs">
-          <span>The latest request failed. Showing the last pull requests loaded.</span>
+          <span>{listQuery.error} Showing the last pull requests loaded.</span>
           <Button size="xs" variant="outline" onClick={() => listQuery.refresh()}>
             Retry
           </Button>
         </div>
       ) : null}
       {listData?.truncated && entries.length > 0 ? (
-        <div ref={sentinelRef} className="flex justify-center py-2 text-xs text-muted-foreground">
+        <div className="flex justify-center py-3 text-xs text-muted-foreground">
           {loadingMore ? (
             <span className="flex items-center gap-2">
               <LoaderIcon aria-hidden className="size-3.5 animate-spin" />
-              Loading more
+              {sentCursors === null ? "Updating pull requests" : "Loading more"}
             </span>
-          ) : null}
+          ) : canContinue || pageSize < MAX_PAGE_SIZE ? (
+            <Button
+              size="sm"
+              variant="outline"
+              onClick={loadMore}
+              disabled={listQuery.isPending || showingCarried}
+            >
+              Load more pull requests
+            </Button>
+          ) : (
+            <span>Narrow your search to find more pull requests.</span>
+          )}
         </div>
       ) : null}
     </>
@@ -1976,13 +1934,10 @@ function PullRequestsRouteView() {
                 ) ?? null
               }
               refreshToken={detailRefreshToken}
-              // Merging, closing or reopening changes the row this panel was opened from, so
-              // the list behind it is out of date the moment the host takes the action.
+              // Host actions can change both readiness and diff size, so refresh the counts
+              // alongside the list. The panel already refreshes itself after each action.
               onActed={() => {
-                refreshList();
-                baselineQuery.refresh();
-                authoredQuery.refresh();
-                reviewingQuery.refresh();
+                void refreshFromHost(false);
               }}
             />
           </RightPanelTabs>
@@ -2244,7 +2199,7 @@ function PullRequestsColumn({
   return (
     // Painted flat like the chat column: the inset underneath carries the chrome grain, and a
     // content surface that lets it show reads as a different background than every thread.
-    <div className="flex min-h-0 min-w-0 flex-1 flex-col bg-background">
+    <div className="@container/pr-list flex min-h-0 min-w-0 flex-1 flex-col bg-background">
       {/* A closed right panel leaves this column full-width, so the shared header
           reserves native window controls and hosts the controls strip itself: on
           desktop the header is a drag-region, and only a no-drag descendant wins
@@ -2325,8 +2280,10 @@ function PullRequestsColumn({
             content actually passing under the chrome fades. */}
         <WorkspacePageContainer width="expanded" className="gap-4">
           <div className="flex flex-col gap-3">
-            <div ref={inFlowSearchRef} className="flex items-center gap-2">
-              {searchInput}
+            <div ref={inFlowSearchRef} className="flex flex-wrap items-center gap-2">
+              <div className="min-w-0 basis-full @lg/pr-list:basis-0 @lg/pr-list:flex-1">
+                {searchInput}
+              </div>
               {sortMenu}
               {filtersMenu}
               {!condensed ? (
diff --git a/apps/web/src/routes/settings.tsx b/apps/web/src/routes/settings.tsx
index 5e921fca5c2c..696ad200f3b7 100644
--- a/apps/web/src/routes/settings.tsx
+++ b/apps/web/src/routes/settings.tsx
@@ -69,7 +69,10 @@ function SettingsContentLayout() {
   }, [navigateBackWithinApp]);
 
   return (
-    <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground isolate">
+    <SidebarInset
+      className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground isolate"
+      data-settings-page-layout
+    >
       <div className="flex min-h-0 min-w-0 flex-1 flex-col bg-background text-foreground">
         <WorkspacePageHeader electron={isElectron}>
           <div className="flex w-full items-center gap-3">
diff --git a/apps/web/src/routes/welcome.tsx b/apps/web/src/routes/welcome.tsx
new file mode 100644
index 000000000000..10caa4dd46fb
--- /dev/null
+++ b/apps/web/src/routes/welcome.tsx
@@ -0,0 +1,45 @@
+import { createFileRoute, redirect, useNavigate } from "@tanstack/react-router";
+
+import { WelcomeWizard } from "../components/onboarding/WelcomeWizard";
+import { useNewThreadHandler } from "../hooks/useHandleNewThread";
+
+/**
+ * First-run welcome wizard. Full-screen, outside the sidebar shell (the root
+ * route mounts this path bare, like /pair). Reached only via the first-run
+ * gate on the index route; visiting it directly after onboarding is harmless —
+ * finishing again just refreshes the completion flag.
+ */
+export const Route = createFileRoute("/welcome")({
+  beforeLoad: ({ context }) => {
+    const { authGateState } = context;
+    if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
+      throw redirect({ to: "/pair", replace: true });
+    }
+  },
+  component: WelcomeRouteView,
+});
+
+function WelcomeRouteView() {
+  const { authGateState } = Route.useRouteContext();
+  const navigate = useNavigate();
+  const openNewThread = useNewThreadHandler();
+  // An authenticated gate means a primary server is serving this app —
+  // desktop, `npx t3`, or a dev server — and that server is "this machine"
+  // no matter what hostname the browser used. Only hosted-static has no
+  // local server to offer.
+  const localAvailable = authGateState.status === "authenticated";
+  return (
+    <WelcomeWizard
+      localAvailable={localAvailable}
+      onDone={(projectRef) => {
+        if (projectRef !== undefined) {
+          void openNewThread(projectRef, { replace: true }).catch(() => {
+            void navigate({ to: "/", replace: true });
+          });
+          return;
+        }
+        void navigate({ to: "/", replace: true });
+      }}
+    />
+  );
+}
diff --git a/apps/web/src/session-logic.runtime-diagnostics.test.ts b/apps/web/src/session-logic.runtime-diagnostics.test.ts
new file mode 100644
index 000000000000..ca37675c5369
--- /dev/null
+++ b/apps/web/src/session-logic.runtime-diagnostics.test.ts
@@ -0,0 +1,75 @@
+import { EventId, TurnId, type OrchestrationThreadActivity } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { deriveWorkLogEntries } from "./session-logic";
+import { workEntryDisplayLabel } from "./components/chat/MessagesTimeline.logic";
+
+// These are the already-truncated fields emitted by ProviderRuntimeIngestion
+// for the malformed-skill diagnostic reported in issue 1084.
+const retainedMessage =
+  "2026-03-14T16:11:12.550224Z ERROR codex_core::codex: failed to load skill /home/sebherrerabe/repos/devsuite/.agent/skills/monorepo-scaffolding/SKILL.md: invalid YAML: mapping va...";
+const warningSummary =
+  "2026-03-14T16:11:12.550224Z ERROR codex_core::codex: failed to load skill /home/sebherrerabe/repos/devsuite/.agent/sk...";
+
+function makeActivity(
+  overrides: Partial<OrchestrationThreadActivity> = {},
+): OrchestrationThreadActivity {
+  return {
+    id: EventId.make("diagnostic"),
+    createdAt: "2026-09-05T00:00:00.000Z",
+    kind: "runtime.error",
+    tone: "error",
+    summary: "Runtime error",
+    payload: { message: retainedMessage },
+    turnId: TurnId.make("turn-1"),
+    ...overrides,
+  };
+}
+
+describe("runtime diagnostics in the work log", () => {
+  it("shows the retained error message in place of its generic row label", () => {
+    const [entry] = deriveWorkLogEntries([makeActivity()]);
+
+    expect(entry).toMatchObject({ label: "Runtime error", detail: retainedMessage });
+    expect(entry && workEntryDisplayLabel(entry, undefined)).toBe(retainedMessage);
+  });
+
+  it("shows the retained warning message beyond its truncated label", () => {
+    const [entry] = deriveWorkLogEntries([
+      makeActivity({ kind: "runtime.warning", tone: "info", summary: warningSummary }),
+    ]);
+
+    expect(entry).toMatchObject({ label: warningSummary, detail: retainedMessage });
+    expect(entry && workEntryDisplayLabel(entry, undefined)).toBe(retainedMessage);
+  });
+
+  it("keeps an existing diagnostic detail when one is provided", () => {
+    const [entry] = deriveWorkLogEntries([
+      makeActivity({ payload: { message: retainedMessage, detail: "Run claude auth login." } }),
+    ]);
+
+    expect(entry?.detail).toBe("Run claude auth login.");
+  });
+
+  it("does not repeat a short warning already visible in the label", () => {
+    const [entry] = deriveWorkLogEntries([
+      makeActivity({
+        kind: "runtime.warning",
+        tone: "info",
+        summary: "Reconnecting... 2/5",
+        payload: { message: "Reconnecting... 2/5" },
+      }),
+    ]);
+
+    expect(entry?.label).toBe("Reconnecting... 2/5");
+    expect(entry?.detail).toBeUndefined();
+  });
+
+  it("does not interpret an unrelated activity message as a runtime diagnostic", () => {
+    const [entry] = deriveWorkLogEntries([
+      makeActivity({ kind: "tool.completed", tone: "tool", summary: "Read file" }),
+    ]);
+
+    expect(entry?.detail).toBeUndefined();
+  });
+});
diff --git a/apps/web/src/session-logic.test.ts b/apps/web/src/session-logic.test.ts
index 5dade8459e0f..dfb0c49be614 100644
--- a/apps/web/src/session-logic.test.ts
+++ b/apps/web/src/session-logic.test.ts
@@ -10,15 +10,19 @@ import { describe, expect, it } from "vite-plus/test";
 import { resolveWorkEntryToolPresentation } from "@t3tools/client-runtime/work-log/presentation";
 
 import {
+  createMessageAttachmentPreviewProjector,
   deriveActiveWorkStartedAt,
   deriveActivePlanState,
   derivePendingApprovals,
   derivePendingUserInputs,
   deriveTimelineEntries,
+  deriveTimelineEntriesWithState,
   deriveWorkLogEntries,
   findLatestProposedPlan,
   hasActionableProposedPlan,
   isLatestTurnSettled,
+  selectHandoffImageResources,
+  selectMessageImageResources,
   workEntryIndicatesToolFailure,
   workEntryIndicatesToolNeutralStatus,
   workEntryIndicatesToolSuccess,
@@ -62,6 +66,37 @@ function makeActivity(overrides: {
 }
 
 describe("derivePendingApprovals", () => {
+  it.each([{}, { requestType: "unknown" }])(
+    "exposes legacy OpenCode approvals without a known request kind: %j",
+    (legacyPayload) => {
+      const requested = makeActivity({
+        kind: "approval.requested",
+        payload: { requestId: "per-legacy", detail: "*", ...legacyPayload },
+      });
+
+      expect(derivePendingApprovals([requested])).toEqual([
+        {
+          requestId: "per-legacy",
+          requestKind: "command",
+          createdAt: requested.createdAt,
+          detail: "*",
+        },
+      ]);
+    },
+  );
+
+  it.each(["tool_user_input", "auth_tokens_refresh"])(
+    "does not turn %s into an approval",
+    (requestType) => {
+      const activity = makeActivity({
+        kind: "approval.requested",
+        payload: { requestId: "not-an-approval", requestType },
+      });
+
+      expect(derivePendingApprovals([activity])).toEqual([]);
+    },
+  );
+
   it("tracks open approvals and removes resolved ones", () => {
     const activities: OrchestrationThreadActivity[] = [
       makeActivity({
@@ -90,7 +125,7 @@ describe("derivePendingApprovals", () => {
         kind: "approval.requested",
         summary: "File-change approval requested",
         tone: "approval",
-        payload: { requestId: "req-2", requestKind: "file-change" },
+        payload: { requestId: "req-2", requestType: "unknown" },
       }),
     ];
 
@@ -199,7 +234,7 @@ describe("derivePendingApprovals", () => {
         tone: "approval",
         payload: {
           requestId: "req-stale-1",
-          requestKind: "command",
+          requestType: "unknown",
         },
       }),
       makeActivity({
@@ -2042,7 +2077,295 @@ describe("deriveWorkLogEntries", () => {
   });
 });
 
+describe("image asset requests", () => {
+  const image = {
+    type: "image" as const,
+    id: "image",
+    name: "image.png",
+    mimeType: "image/png",
+    sizeBytes: 42,
+  };
+  const message = {
+    id: MessageId.make("image-message"),
+    role: "user" as const,
+    text: "Inspect these images",
+    turnId: null,
+    createdAt: "2026-09-04T00:00:00.000Z",
+    updatedAt: "2026-09-04T00:00:00.000Z",
+    streaming: false,
+    attachments: [image],
+  };
+
+  it("requests the whole row's gallery and crops without signing local preview IDs", () => {
+    const attachments = Object.freeze([
+      image,
+      { ...image, id: "second" },
+      { ...image, id: "crop", name: "preview-annotation-1.png" },
+      { ...image, id: "local", previewUrl: "blob:local" },
+      { ...image, id: "inline", previewUrl: "data:image/png;base64,AA==" },
+      { ...image, id: "provided", previewUrl: "https://preview.test/image" },
+      { ...image, type: "file" as const, id: "file", mimeType: "application/pdf" },
+      { ...image, type: "future", id: "unknown" },
+      image,
+    ]);
+
+    expect(selectMessageImageResources(attachments)).toEqual([
+      { _tag: "attachment", attachmentId: "image" },
+      { _tag: "attachment", attachmentId: "second" },
+      { _tag: "attachment", attachmentId: "crop" },
+      { _tag: "attachment", attachmentId: "provided" },
+    ]);
+  });
+
+  it("requests offscreen handoffs without signing the rest of the loaded history", () => {
+    const history = {
+      ...message,
+      id: MessageId.make("history"),
+      attachments: [{ ...image, id: "history-image" }],
+    };
+    const offscreen = {
+      ...message,
+      id: MessageId.make("offscreen"),
+      attachments: [image, { ...image, id: "crop", name: "preview-annotation-1.png" }],
+    };
+    const empty = {
+      ...message,
+      id: MessageId.make("empty"),
+      attachments: [{ ...image, id: "empty" }],
+    };
+    const assistant = {
+      ...message,
+      id: MessageId.make("assistant"),
+      role: "assistant" as const,
+      attachments: [{ ...image, id: "assistant-image" }],
+    };
+    expect(
+      selectHandoffImageResources([history, message, offscreen, empty, assistant], {
+        [message.id]: ["blob:message"],
+        [offscreen.id]: ["blob:offscreen", "blob:crop"],
+        [empty.id]: [],
+        [assistant.id]: ["blob:unused"],
+      }),
+    ).toEqual([
+      { _tag: "attachment", attachmentId: "image" },
+      { _tag: "attachment", attachmentId: "crop" },
+    ]);
+  });
+
+  it("does not scan history when no handoff is pending", () => {
+    let reads = 0;
+    const messages = new Proxy([message], {
+      get(target, property, receiver) {
+        if (property === "0") reads += 1;
+        return Reflect.get(target, property, receiver);
+      },
+    });
+    const empty = selectHandoffImageResources(messages, {});
+    expect(reads).toBe(0);
+    expect(empty).toHaveLength(0);
+    expect(selectHandoffImageResources(undefined, { missing: ["blob:missing"] })).toBe(empty);
+    expect(selectMessageImageResources(undefined)).toBe(empty);
+  });
+
+  it("hands signed URLs to a mounted row only after the local preview is released", () => {
+    const server = createMessageAttachmentPreviewProjector();
+    const handoff = createMessageAttachmentPreviewProjector();
+    const row = createMessageAttachmentPreviewProjector();
+    const pending = handoff(
+      server(message, () => undefined),
+      () => "blob:pending",
+    );
+    expect(selectMessageImageResources(pending.attachments)).toEqual([]);
+    expect(selectHandoffImageResources([message], { [message.id]: ["blob:pending"] })).toEqual([
+      { _tag: "attachment", attachmentId: image.id },
+    ]);
+
+    const ready = server(message, () => "https://server.test/image");
+    expect(selectMessageImageResources(handoff(ready, () => "blob:pending").attachments)).toEqual(
+      [],
+    );
+    const released = server(message, () => undefined);
+    expect(selectMessageImageResources(released.attachments)).toEqual([
+      { _tag: "attachment", attachmentId: image.id },
+    ]);
+    const displayed = row(released, () => "https://server.test/image");
+    expect(displayed).toEqual(ready);
+    expect(pending.attachments?.[0]).toMatchObject({ previewUrl: "blob:pending" });
+    expect(row(released, () => "https://server.test/renewed").attachments?.[0]).toMatchObject({
+      previewUrl: "https://server.test/renewed",
+    });
+    expect(displayed.attachments?.[0]).toMatchObject({ previewUrl: "https://server.test/image" });
+    expect(row(released, () => undefined)).toBe(message);
+  });
+});
+
 describe("deriveTimelineEntries", () => {
+  const streamingMessage = {
+    id: MessageId.make("streaming-message"),
+    role: "assistant" as const,
+    text: "",
+    turnId: TurnId.make("streaming-turn"),
+    createdAt: "2026-02-23T00:00:03.000Z",
+    updatedAt: "2026-02-23T00:00:03.000Z",
+    streaming: true,
+  };
+
+  it("reuses preview objects while preserving URL and attachment metadata changes", () => {
+    const image = {
+      type: "image" as const,
+      id: "image",
+      name: "image.png",
+      mimeType: "image/png",
+      sizeBytes: 42,
+    };
+    const file = {
+      type: "file" as const,
+      id: "file",
+      name: "file.txt",
+      mimeType: "text/plain",
+      sizeBytes: 8,
+    };
+    const message = { ...streamingMessage, attachments: Object.freeze([image, file]) };
+    const project = createMessageAttachmentPreviewProjector();
+    const urls = new Map([[image.id, "https://first.test/image"]]);
+    const first = project(message, (attachment) => urls.get(attachment.id));
+    Object.freeze(first.attachments);
+    expect(project(message, (attachment) => new Map(urls).get(attachment.id))).toBe(first);
+    const streamed = project({ ...message, text: "Next" }, (attachment) => urls.get(attachment.id));
+    expect(streamed.attachments).toBe(first.attachments);
+    expect(streamed.text).toBe("Next");
+    expect(first.text).toBe("");
+    expect(first.attachments?.[1]).toBe(file);
+
+    urls.set(image.id, "https://second.test/image");
+    const renewed = project(message, (attachment) => urls.get(attachment.id));
+    expect(renewed.attachments?.[0]).toMatchObject({ previewUrl: "https://second.test/image" });
+    expect(first.attachments?.[0]).toMatchObject({ previewUrl: "https://first.test/image" });
+    const renamed = project(
+      { ...message, attachments: [{ ...image, name: "renamed.png" }, file] },
+      (attachment) => urls.get(attachment.id),
+    );
+    expect(renamed.attachments?.[0]).toMatchObject({
+      name: "renamed.png",
+      previewUrl: "https://second.test/image",
+    });
+    expect(project(message, () => undefined)).toBe(message);
+  });
+
+  it("keeps pending preview handoffs stable and restores the current server URL", () => {
+    const message = {
+      ...streamingMessage,
+      role: "user" as const,
+      streaming: false,
+      attachments: [
+        {
+          type: "image" as const,
+          id: "image",
+          name: "image.png",
+          mimeType: "image/png",
+          sizeBytes: 42,
+        },
+      ],
+    };
+    const server = createMessageAttachmentPreviewProjector();
+    const handoff = createMessageAttachmentPreviewProjector();
+    const first = handoff(
+      server(message, () => undefined),
+      () => "blob:handoff",
+    );
+    expect(
+      handoff(
+        server(message, () => undefined),
+        () => "blob:handoff",
+      ),
+    ).toBe(first);
+    const ready = server(message, () => "https://server.test/image");
+    expect(handoff(ready, () => "blob:handoff").attachments?.[0]).toMatchObject({
+      previewUrl: "blob:handoff",
+    });
+    expect(handoff(ready, () => undefined)).toBe(ready);
+    expect(ready.attachments?.[0]).toMatchObject({ previewUrl: "https://server.test/image" });
+    expect(first.attachments?.[0]).toMatchObject({ previewUrl: "blob:handoff" });
+  });
+
+  it("reuses ordered history without changing an earlier projection", () => {
+    const history = { ...streamingMessage, id: MessageId.make("history"), streaming: false };
+    const work = [
+      { id: "work", createdAt: history.createdAt, label: "Ran tests", tone: "tool" as const },
+    ];
+    const first = deriveTimelineEntriesWithState([history, streamingMessage], [], work);
+    Object.freeze(first.entries);
+    for (const entry of first.entries) Object.freeze(entry);
+
+    const firstMessage = {
+      ...streamingMessage,
+      text: "First",
+      updatedAt: "2026-02-23T00:00:04.000Z",
+    };
+    const secondMessage = {
+      ...streamingMessage,
+      text: "Second",
+      updatedAt: "2026-02-23T00:00:05.000Z",
+    };
+    const firstBranch = deriveTimelineEntriesWithState([history, firstMessage], [], work, first);
+    const secondBranch = deriveTimelineEntriesWithState([history, secondMessage], [], work, first);
+
+    expect(firstBranch.entries).toEqual(deriveTimelineEntries([history, firstMessage], [], work));
+    expect(secondBranch.entries).toEqual(deriveTimelineEntries([history, secondMessage], [], work));
+    expect(firstBranch.entries[0]).toBe(first.entries[0]);
+    expect(firstBranch.entries[2]).toBe(first.entries[2]);
+    expect(first.entries[1]).toMatchObject({ message: { text: "" } });
+    expect(firstBranch.entries[1]).toMatchObject({ message: { text: "First" } });
+  });
+
+  it("preserves stable source ordering for ties, append, and older pages", () => {
+    const plan = {
+      id: "plan:thread:turn",
+      turnId: streamingMessage.turnId,
+      planMarkdown: "Plan",
+      implementedAt: null,
+      implementationThreadId: null,
+      createdAt: streamingMessage.createdAt,
+      updatedAt: streamingMessage.createdAt,
+    };
+    const firstWork = {
+      id: "work-1",
+      createdAt: streamingMessage.createdAt,
+      label: "Ran tests",
+      tone: "tool" as const,
+    };
+    const first = deriveTimelineEntriesWithState([streamingMessage], [plan], [firstWork]);
+    const appendedMessage = { ...streamingMessage, id: MessageId.make("appended") };
+    const appendedWork = { ...firstWork, id: "work-2" };
+    const messages = [streamingMessage, appendedMessage];
+    const work = [firstWork, appendedWork];
+    const appended = deriveTimelineEntriesWithState(messages, [plan], work, first);
+    expect(appended.entries.map((entry) => entry.id)).toEqual([
+      streamingMessage.id,
+      appendedMessage.id,
+      plan.id,
+      firstWork.id,
+      appendedWork.id,
+    ]);
+    expect(appended.entries[0]).toBe(first.entries[0]);
+
+    const older = {
+      ...streamingMessage,
+      id: MessageId.make("older"),
+      createdAt: "2026-02-22T00:00:00.000Z",
+    };
+    const prepended = deriveTimelineEntriesWithState([older, ...messages], [plan], work, appended);
+    expect(prepended.entries).toEqual(deriveTimelineEntries([older, ...messages], [plan], work));
+    const corrected = {
+      ...streamingMessage,
+      createdAt: "2026-02-24T00:00:00.000Z",
+      streaming: false,
+    };
+    expect(
+      deriveTimelineEntriesWithState([corrected, appendedMessage], [plan], work, appended).entries,
+    ).toEqual(deriveTimelineEntries([corrected, appendedMessage], [plan], work));
+  });
+
   it("includes proposed plans alongside messages and work entries in chronological order", () => {
     const entries = deriveTimelineEntries(
       [
diff --git a/apps/web/src/session-logic.ts b/apps/web/src/session-logic.ts
index c6c7410bebea..b6a6eb0e6342 100644
--- a/apps/web/src/session-logic.ts
+++ b/apps/web/src/session-logic.ts
@@ -1,6 +1,7 @@
 import * as Option from "effect/Option";
 import * as Arr from "effect/Array";
 import * as Schema from "effect/Schema";
+import { shallow } from "zustand/vanilla/shallow";
 import { isBackgroundTaskActivity } from "@t3tools/client-runtime/state/subagentRuntime";
 import {
   commandDetailRepeatsCommand,
@@ -11,10 +12,10 @@ import { extractToolActivityPresentation } from "@t3tools/client-runtime/work-lo
 import {
   ApprovalRequestId,
   isToolLifecycleItemType,
+  type AssetResource,
   type OrchestrationLatestTurn,
   type OrchestrationThreadActivity,
   type OrchestrationProposedPlanId,
-  ProviderDriverKind,
   ProviderApprovalOption,
   ProviderRequestKind,
   type ToolLifecycleItemType,
@@ -23,51 +24,18 @@ import {
   type TurnId,
 } from "@t3tools/contracts";
 
-import type {
-  ChatMessage,
-  ProposedPlan,
-  SessionPhase,
-  Thread,
-  ThreadSession,
-  TurnDiffSummary,
+import {
+  isImageAttachment,
+  type ChatAttachment,
+  type ChatMessage,
+  type ProposedPlan,
+  type SessionPhase,
+  type Thread,
+  type ThreadSession,
+  type TurnDiffSummary,
 } from "./types";
 
-export type ProviderPickerKind = ProviderDriverKind;
-
-export const PROVIDER_OPTIONS: Array<{
-  value: ProviderPickerKind;
-  label: string;
-  available: boolean;
-  /** Shown on the model picker sidebar when relevant */
-  pickerSidebarBadge?: "new" | "soon";
-}> = [
-  { value: ProviderDriverKind.make("codex"), label: "Codex", available: true },
-  { value: ProviderDriverKind.make("claudeAgent"), label: "Claude", available: true },
-  {
-    value: ProviderDriverKind.make("opencode"),
-    label: "OpenCode",
-    available: true,
-    pickerSidebarBadge: "new",
-  },
-  {
-    value: ProviderDriverKind.make("cursor"),
-    label: "Cursor",
-    available: true,
-    pickerSidebarBadge: "new",
-  },
-  {
-    value: ProviderDriverKind.make("grok"),
-    label: "Grok",
-    available: true,
-    pickerSidebarBadge: "new",
-  },
-  {
-    value: ProviderDriverKind.make("antigravity"),
-    label: "Antigravity",
-    available: true,
-    pickerSidebarBadge: "new",
-  },
-];
+export { formatDuration } from "@t3tools/shared/orchestrationTiming";
 
 export type WorkLogToolLifecycleStatus =
   | "inProgress"
@@ -192,6 +160,13 @@ export type TimelineEntry =
       entry: WorkLogEntry;
     };
 
+export interface TimelineEntriesProjection {
+  readonly messages: ReadonlyArray<ChatMessage>;
+  readonly proposedPlans: ReadonlyArray<ProposedPlan>;
+  readonly workEntries: ReadonlyArray<WorkLogEntry>;
+  readonly entries: TimelineEntry[];
+}
+
 export function workLogEntryIsToolLike(entry: WorkLogEntry): boolean {
   if (entry.tone === "tool" || entry.tone === "thinking" || entry.tone === "error") {
     return true;
@@ -344,32 +319,6 @@ export function workEntryIndicatesToolNeutralStatus(entry: WorkLogEntry): boolea
   return true;
 }
 
-export function formatDuration(durationMs: number): string {
-  if (!Number.isFinite(durationMs) || durationMs < 0) return "0ms";
-  if (durationMs < 1_000) return `${Math.max(1, Math.round(durationMs))}ms`;
-  if (durationMs < 10_000) {
-    const tenths = Math.round(durationMs / 100) / 10;
-    // 9.95s+ rounds up to the next bucket — render "10s", not "10.0s".
-    return tenths >= 10 ? "10s" : `${tenths.toFixed(1)}s`;
-  }
-  if (durationMs < 60_000) return `${Math.round(durationMs / 1_000)}s`;
-  const minutes = Math.floor(durationMs / 60_000);
-  const seconds = Math.round((durationMs % 60_000) / 1_000);
-  if (seconds === 0) return `${minutes}m`;
-  if (seconds === 60) return `${minutes + 1}m`;
-  return `${minutes}m ${seconds}s`;
-}
-
-export function formatElapsed(startIso: string, endIso: string | undefined): string | null {
-  if (!endIso) return null;
-  const startedAt = Date.parse(startIso);
-  const endedAt = Date.parse(endIso);
-  if (Number.isNaN(startedAt) || Number.isNaN(endedAt) || endedAt < startedAt) {
-    return null;
-  }
-  return formatDuration(endedAt - startedAt);
-}
-
 type LatestTurnTiming = Pick<OrchestrationLatestTurn, "turnId" | "startedAt" | "completedAt">;
 type SessionActivityState = Pick<NonNullable<Thread["session"]>, "status" | "activeTurnId">;
 
@@ -464,10 +413,16 @@ export function derivePendingApprovals(
       ? payload.options.filter(isProviderApprovalOption)
       : undefined;
 
-    if (activity.kind === "approval.requested" && requestId && requestKind) {
+    if (
+      activity.kind === "approval.requested" &&
+      requestId &&
+      payload?.requestType !== "tool_user_input" &&
+      payload?.requestType !== "auth_tokens_refresh"
+    ) {
       openByRequestId.set(requestId, {
         requestId,
-        requestKind,
+        // Older OpenCode requests can have no recognized approval kind.
+        requestKind: requestKind ?? "command",
         createdAt: activity.createdAt,
         ...(detail ? { detail } : {}),
         ...(appName ? { appName } : {}),
@@ -947,6 +902,14 @@ function toDerivedWorkLogEntry(activity: OrchestrationThreadActivity): DerivedWo
   const viewedImagePath = asTrimmedString(asRecord(payload?.data)?.imagePath);
   if (detail) {
     entry.detail = detail;
+  } else if (activity.kind === "runtime.error" || activity.kind === "runtime.warning") {
+    const message = asTrimmedString(payload?.message);
+    if (
+      message &&
+      normalizePreviewForComparison(message) !== normalizePreviewForComparison(activity.summary)
+    ) {
+      entry.detail = message;
+    }
   }
   if (viewedImagePath) {
     entry.viewedImagePath = viewedImagePath;
@@ -1768,32 +1731,284 @@ function compareActivityLifecycleRank(kind: string): number {
   return 1;
 }
 
-export function deriveTimelineEntries(
-  messages: ReadonlyArray<ChatMessage>,
-  proposedPlans: ReadonlyArray<ProposedPlan>,
-  workEntries: ReadonlyArray<WorkLogEntry>,
-): TimelineEntry[] {
-  const messageRows: TimelineEntry[] = messages.map((message) => ({
+function timelineEntryFromMessage(message: ChatMessage): TimelineEntry {
+  return {
     id: message.id,
     kind: "message",
     createdAt: message.createdAt,
     message,
-  }));
-  const proposedPlanRows: TimelineEntry[] = proposedPlans.map((proposedPlan) => ({
+  };
+}
+
+function timelineEntryFromProposedPlan(proposedPlan: ProposedPlan): TimelineEntry {
+  return {
     id: proposedPlan.id,
     kind: "proposed-plan",
     createdAt: proposedPlan.createdAt,
     proposedPlan,
-  }));
-  const workRows: TimelineEntry[] = workEntries.map((entry) => ({
-    id: entry.id,
+  };
+}
+
+function timelineEntryFromWork(workEntry: WorkLogEntry): TimelineEntry {
+  return {
+    id: workEntry.id,
     kind: "work",
-    createdAt: entry.createdAt,
-    entry,
-  }));
-  return [...messageRows, ...proposedPlanRows, ...workRows].toSorted((a, b) =>
-    a.createdAt.localeCompare(b.createdAt),
-  );
+    createdAt: workEntry.createdAt,
+    entry: workEntry,
+  };
+}
+
+function compareTimelineEntriesByCreatedAt(left: TimelineEntry, right: TimelineEntry): number {
+  return left.createdAt.localeCompare(right.createdAt);
+}
+
+function timelineEntrySourceOrder(entry: TimelineEntry): number {
+  switch (entry.kind) {
+    case "message":
+      return 0;
+    case "proposed-plan":
+      return 1;
+    case "work":
+      return 2;
+  }
+}
+
+function shouldTakePreviousTimelineEntry(previous: TimelineEntry, suffix: TimelineEntry): boolean {
+  const createdAtComparison = compareTimelineEntriesByCreatedAt(previous, suffix);
+  if (createdAtComparison !== 0) return createdAtComparison < 0;
+  // The original full derivation sorts a source-ordered array with a stable
+  // comparator. On a tie, messages precede plans, plans precede work, and an
+  // older item in the same source array precedes a newly appended item.
+  return timelineEntrySourceOrder(previous) <= timelineEntrySourceOrder(suffix);
+}
+
+function hasExactArrayPrefix<T>(previous: ReadonlyArray<T>, next: ReadonlyArray<T>): boolean {
+  if (previous === next) return true;
+  if (next.length < previous.length) return false;
+  for (let index = 0; index < previous.length; index += 1) {
+    if (previous[index] !== next[index]) return false;
+  }
+  return true;
+}
+
+function mergeTimelineEntrySuffix(
+  previous: ReadonlyArray<TimelineEntry>,
+  suffix: ReadonlyArray<TimelineEntry>,
+): TimelineEntry[] {
+  if (suffix.length === 0) return [...previous];
+  const previousLast = previous.at(-1);
+  let suffixIsOrdered = true;
+  for (let index = 1; index < suffix.length; index += 1) {
+    if (compareTimelineEntriesByCreatedAt(suffix[index - 1]!, suffix[index]!) > 0) {
+      suffixIsOrdered = false;
+      break;
+    }
+  }
+  if (
+    suffixIsOrdered &&
+    (previousLast === undefined || shouldTakePreviousTimelineEntry(previousLast, suffix[0]!))
+  ) {
+    return [...previous, ...suffix];
+  }
+
+  const merged: TimelineEntry[] = [];
+  let previousIndex = 0;
+  let suffixIndex = 0;
+  while (previousIndex < previous.length || suffixIndex < suffix.length) {
+    const previousEntry = previous[previousIndex];
+    const suffixEntry = suffix[suffixIndex];
+    if (
+      previousEntry !== undefined &&
+      (suffixEntry === undefined || shouldTakePreviousTimelineEntry(previousEntry, suffixEntry))
+    ) {
+      merged.push(previousEntry);
+      previousIndex += 1;
+    } else if (suffixEntry !== undefined) {
+      merged.push(suffixEntry);
+      suffixIndex += 1;
+    }
+  }
+  return merged;
+}
+
+type AttachmentResource = Extract<AssetResource, { readonly _tag: "attachment" }>;
+const EMPTY_IMAGE_RESOURCES = Object.freeze<ReadonlyArray<AttachmentResource>>([]);
+
+/** A mounted row requests its stored images. Local previews keep their existing URLs. */
+export function selectMessageImageResources(
+  attachments: ChatMessage["attachments"],
+): ReadonlyArray<AttachmentResource> {
+  const attachmentIds = new Set<string>();
+  for (const attachment of attachments ?? []) {
+    if (!isImageAttachment(attachment)) continue;
+    const previewUrl = attachment.previewUrl;
+    if (previewUrl?.startsWith("blob:") || previewUrl?.startsWith("data:")) continue;
+    attachmentIds.add(attachment.id);
+  }
+  return attachmentIds.size === 0
+    ? EMPTY_IMAGE_RESOURCES
+    : Array.from(attachmentIds, (attachmentId) => ({ _tag: "attachment", attachmentId }));
+}
+
+/** Handoffs need server URLs even while their message rows are unmounted. */
+export function selectHandoffImageResources(
+  messages: ReadonlyArray<ChatMessage> | undefined,
+  handoffs: Readonly<Record<string, ReadonlyArray<string>>>,
+): ReadonlyArray<AttachmentResource> {
+  if (Object.keys(handoffs).length === 0) return EMPTY_IMAGE_RESOURCES;
+  const attachmentIds = new Set<string>();
+  for (const message of messages ?? []) {
+    if (message.role !== "user" || !handoffs[message.id]?.length) continue;
+    for (const attachment of message.attachments ?? []) {
+      if (isImageAttachment(attachment)) attachmentIds.add(attachment.id);
+    }
+  }
+  return attachmentIds.size === 0
+    ? EMPTY_IMAGE_RESOURCES
+    : Array.from(attachmentIds, (attachmentId) => ({ _tag: "attachment", attachmentId }));
+}
+
+/** Own one mapper per preview stage. Immutable messages retain unchanged preview objects. */
+export function createMessageAttachmentPreviewProjector() {
+  const attachmentsBySource = new WeakMap<
+    ReadonlyArray<ChatAttachment>,
+    ReadonlyArray<ChatAttachment>
+  >();
+  const messagesBySource = new WeakMap<ChatMessage, ChatMessage>();
+  return (
+    message: ChatMessage,
+    previewUrlFor: (attachment: ChatAttachment) => string | undefined,
+  ): ChatMessage => {
+    const source = message.attachments;
+    if (!source || source.length === 0) return message;
+    const previous = attachmentsBySource.get(source) ?? source;
+    let changed: ChatAttachment[] | undefined;
+    let hasOverrides = false;
+    for (const [index, attachment] of source.entries()) {
+      const previewUrl = previewUrlFor(attachment);
+      const sourceUrl = "previewUrl" in attachment ? attachment.previewUrl : undefined;
+      const previousAttachment = previous[index]!;
+      const previousUrl =
+        "previewUrl" in previousAttachment ? previousAttachment.previewUrl : undefined;
+      const next =
+        !previewUrl || previewUrl === sourceUrl
+          ? attachment
+          : previewUrl === previousUrl
+            ? previousAttachment
+            : { ...attachment, previewUrl };
+      hasOverrides ||= next !== attachment;
+      if (next !== previousAttachment) {
+        changed ??= previous.slice();
+        changed[index] = next;
+      }
+    }
+    const attachments = hasOverrides ? (changed ?? previous) : source;
+    attachmentsBySource.set(source, attachments);
+    if (attachments === source) {
+      messagesBySource.delete(message);
+      return message;
+    }
+    const previousMessage = messagesBySource.get(message);
+    if (previousMessage?.attachments === attachments) return previousMessage;
+    const result = { ...message, attachments };
+    messagesBySource.set(message, result);
+    return result;
+  };
+}
+
+/** Text and update time do not change a streaming assistant message's timeline structure. */
+export function isStreamingMessageTextUpdate(previous: ChatMessage, next: ChatMessage): boolean {
+  if (
+    previous.role !== "assistant" ||
+    next.role !== "assistant" ||
+    !previous.streaming ||
+    !next.streaming
+  ) {
+    return false;
+  }
+  const { text: _previousText, updatedAt: _previousUpdatedAt, ...previousMetadata } = previous;
+  const { text: _nextText, updatedAt: _nextUpdatedAt, ...nextMetadata } = next;
+  return shallow(previousMetadata, nextMetadata);
+}
+
+function replaceStreamingTimelineMessages(
+  messages: ReadonlyArray<ChatMessage>,
+  previous: TimelineEntriesProjection,
+): TimelineEntry[] | null {
+  if (messages.length !== previous.messages.length) return null;
+  const replacements = new Map<ChatMessage, ChatMessage>();
+  for (const [index, message] of messages.entries()) {
+    const previousMessage = previous.messages[index]!;
+    if (message === previousMessage) continue;
+    if (!isStreamingMessageTextUpdate(previousMessage, message)) return null;
+    replacements.set(previousMessage, message);
+  }
+  if (replacements.size === 0) return previous.entries;
+  return previous.entries.map((entry) => {
+    const replacement = entry.kind === "message" ? replacements.get(entry.message) : undefined;
+    return replacement ? timelineEntryFromMessage(replacement) : entry;
+  });
+}
+
+/** Reuse ordered entries across immutable stream updates. Other changes keep the full sort. */
+export function deriveTimelineEntriesWithState(
+  messages: ReadonlyArray<ChatMessage>,
+  proposedPlans: ReadonlyArray<ProposedPlan>,
+  workEntries: ReadonlyArray<WorkLogEntry>,
+  previous: TimelineEntriesProjection | null = null,
+): TimelineEntriesProjection {
+  if (
+    previous !== null &&
+    previous.proposedPlans.length === proposedPlans.length &&
+    previous.workEntries.length === workEntries.length &&
+    hasExactArrayPrefix(previous.proposedPlans, proposedPlans) &&
+    hasExactArrayPrefix(previous.workEntries, workEntries)
+  ) {
+    const entries = replaceStreamingTimelineMessages(messages, previous);
+    if (entries !== null) return { messages, proposedPlans, workEntries, entries };
+  }
+  const canAppend =
+    previous !== null &&
+    hasExactArrayPrefix(previous.messages, messages) &&
+    hasExactArrayPrefix(previous.proposedPlans, proposedPlans) &&
+    hasExactArrayPrefix(previous.workEntries, workEntries);
+
+  if (canAppend) {
+    const messageRows = messages.slice(previous.messages.length).map(timelineEntryFromMessage);
+    const proposedPlanRows = proposedPlans
+      .slice(previous.proposedPlans.length)
+      .map(timelineEntryFromProposedPlan);
+    const workRows = workEntries.slice(previous.workEntries.length).map(timelineEntryFromWork);
+    const suffix = [...messageRows, ...proposedPlanRows, ...workRows].toSorted(
+      compareTimelineEntriesByCreatedAt,
+    );
+    return {
+      messages,
+      proposedPlans,
+      workEntries,
+      entries: mergeTimelineEntrySuffix(previous.entries, suffix),
+    };
+  }
+
+  const messageRows = messages.map(timelineEntryFromMessage);
+  const proposedPlanRows = proposedPlans.map(timelineEntryFromProposedPlan);
+  const workRows = workEntries.map(timelineEntryFromWork);
+  return {
+    messages,
+    proposedPlans,
+    workEntries,
+    entries: [...messageRows, ...proposedPlanRows, ...workRows].toSorted(
+      compareTimelineEntriesByCreatedAt,
+    ),
+  };
+}
+
+export function deriveTimelineEntries(
+  messages: ReadonlyArray<ChatMessage>,
+  proposedPlans: ReadonlyArray<ProposedPlan>,
+  workEntries: ReadonlyArray<WorkLogEntry>,
+): TimelineEntry[] {
+  return deriveTimelineEntriesWithState(messages, proposedPlans, workEntries).entries;
 }
 
 export function inferCheckpointTurnCountByTurnId(
diff --git a/apps/web/src/state/agentSessions.ts b/apps/web/src/state/agentSessions.ts
new file mode 100644
index 000000000000..996ddb0ea730
--- /dev/null
+++ b/apps/web/src/state/agentSessions.ts
@@ -0,0 +1,25 @@
+import { WS_METHODS } from "@t3tools/contracts";
+import {
+  createEnvironmentRpcCommand,
+  createEnvironmentRpcQueryAtomFamily,
+} from "@t3tools/client-runtime/state/runtime";
+
+import { connectionAtomRuntime } from "../connection/runtime";
+
+/**
+ * Scan of Claude Code / Codex home directories on an environment, surfacing
+ * project candidates for the welcome wizard's import step. The scan walks the
+ * filesystem server-side, so results are cached briefly and refreshed when the
+ * import step remounts.
+ */
+export const agentSessionScan = createEnvironmentRpcQueryAtomFamily(connectionAtomRuntime, {
+  label: "environment-data:agent-sessions:scan",
+  tag: WS_METHODS.agentSessionsScan,
+  staleTimeMs: 30_000,
+  idleTtlMs: 5 * 60_000,
+});
+
+export const agentSessionImport = createEnvironmentRpcCommand(connectionAtomRuntime, {
+  label: "environment-data:agent-sessions:import",
+  tag: WS_METHODS.agentSessionsImport,
+});
diff --git a/apps/web/src/state/entities.ts b/apps/web/src/state/entities.ts
index ec1e4c836211..c44c5b437b63 100644
--- a/apps/web/src/state/entities.ts
+++ b/apps/web/src/state/entities.ts
@@ -15,7 +15,10 @@ import { useMemo } from "react";
 import { appAtomRegistry } from "../rpc/atomRegistry";
 import { environmentProjects } from "./projects";
 import { environmentServerConfigsAtom } from "./server";
-import { allEnvironmentShellsBootstrappedAtom } from "./shell";
+import {
+  allEnvironmentProjectSnapshotsReadyAtom,
+  allEnvironmentShellsBootstrappedAtom,
+} from "./shell";
 import { environmentThreadDetails, environmentThreadShells } from "./threads";
 
 const EMPTY_THREAD_REFS: ReadonlyArray<ScopedThreadRef> = Object.freeze([]);
@@ -79,6 +82,10 @@ export function useAllEnvironmentShellsBootstrapped(): boolean {
   return useAtomValue(allEnvironmentShellsBootstrappedAtom);
 }
 
+export function useAllEnvironmentProjectSnapshotsReady(): boolean {
+  return useAtomValue(allEnvironmentProjectSnapshotsReadyAtom);
+}
+
 export function useThreadShellsForProjectRefs(
   refs: ReadonlyArray<ScopedProjectRef>,
 ): ReadonlyArray<EnvironmentThreadShell> {
diff --git a/apps/web/src/state/pullRequests.ts b/apps/web/src/state/pullRequests.ts
index 99b2ef37c99a..eaec72066735 100644
--- a/apps/web/src/state/pullRequests.ts
+++ b/apps/web/src/state/pullRequests.ts
@@ -130,8 +130,8 @@ function createMergedEnvironmentQuery<Input, A>(
       (override?: ReadonlyArray<EnvironmentQueryTarget<Input>>) => {
         const refreshTargets =
           override ?? (JSON.parse(key) as ReadonlyArray<EnvironmentQueryTarget<Input>>);
-        for (const target of refreshTargets) {
-          appAtomRegistry.refresh(atomFor(target));
+        for (const atom of new Set(refreshTargets.map(atomFor))) {
+          appAtomRegistry.refresh(atom);
         }
       },
       [key],
@@ -173,7 +173,7 @@ export interface MergedPullRequestListView {
   readonly data: MergedPullRequestList | null;
   readonly error: string | null;
   readonly isPending: boolean;
-  readonly refresh: () => void;
+  readonly refresh: (targets?: ReadonlyArray<EnvironmentQueryTarget<PullRequestListInput>>) => void;
 }
 
 /** One listing per environment, merged into the single list the page renders. */
diff --git a/apps/web/src/state/shell.test.ts b/apps/web/src/state/shell.test.ts
new file mode 100644
index 000000000000..745e674400d3
--- /dev/null
+++ b/apps/web/src/state/shell.test.ts
@@ -0,0 +1,135 @@
+import {
+  BearerConnectionTarget,
+  PrimaryConnectionTarget,
+} from "@t3tools/client-runtime/connection";
+import type { EnvironmentCatalogState } from "@t3tools/client-runtime/state/connections";
+import type { EnvironmentShellState } from "@t3tools/client-runtime/state/shell";
+import { EnvironmentId } from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import { Atom, AtomRegistry } from "effect/unstable/reactivity";
+import { describe, expect, it } from "vite-plus/test";
+
+import { createAllEnvironmentProjectSnapshotsReadyAtom } from "./shell";
+
+const LOCAL = EnvironmentId.make("local");
+const REMOTE = EnvironmentId.make("remote");
+
+function shellState(status: EnvironmentShellState["status"]): EnvironmentShellState {
+  return {
+    status,
+    snapshot:
+      status === "empty"
+        ? Option.none()
+        : Option.some({
+            snapshotSequence: 1,
+            updatedAt: "2026-09-04T00:00:00.000Z",
+            projects: [],
+            threads: [],
+          }),
+    error: Option.none(),
+  };
+}
+
+function catalogState(environmentIds: readonly EnvironmentId[]): EnvironmentCatalogState {
+  return {
+    isReady: true,
+    entries: new Map(
+      environmentIds.map((environmentId) => [
+        environmentId,
+        {
+          target:
+            environmentId === LOCAL
+              ? new PrimaryConnectionTarget({
+                  environmentId,
+                  label: environmentId,
+                  httpBaseUrl: `https://${environmentId}.example.test`,
+                  wsBaseUrl: `wss://${environmentId}.example.test`,
+                })
+              : new BearerConnectionTarget({
+                  environmentId,
+                  connectionId: environmentId,
+                  label: environmentId,
+                }),
+          profile: Option.none(),
+        },
+      ]),
+    ),
+  };
+}
+
+function makeHarness(requiresPrimaryEnvironment = true) {
+  const catalog = Atom.make<EnvironmentCatalogState>({ isReady: false, entries: new Map() });
+  const shells = Atom.family((_environmentId: EnvironmentId) =>
+    Atom.make<EnvironmentShellState>(shellState("empty")),
+  );
+  const ready = createAllEnvironmentProjectSnapshotsReadyAtom({
+    catalogValueAtom: catalog,
+    shellStateValueAtom: shells,
+    requiresPrimaryEnvironment,
+  });
+  const registry = AtomRegistry.make();
+  return { catalog, shells, ready, registry };
+}
+
+describe("project snapshot readiness", () => {
+  it("does not clear a saved scope while the ready catalog is still empty", () => {
+    const { catalog, ready, registry } = makeHarness();
+    expect(registry.get(ready)).toBe(false);
+    registry.set(catalog, catalogState([]));
+    expect(registry.get(ready)).toBe(false);
+    registry.dispose();
+  });
+
+  it("waits for primary discovery even if a persisted remote is already live", () => {
+    const { catalog, shells, ready, registry } = makeHarness();
+    registry.set(catalog, catalogState([REMOTE]));
+    registry.set(shells(REMOTE), shellState("live"));
+    expect(registry.get(ready)).toBe(false);
+
+    registry.set(catalog, catalogState([LOCAL, REMOTE]));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(LOCAL), shellState("live"));
+    expect(registry.get(ready)).toBe(true);
+    registry.dispose();
+  });
+
+  it("allows a hosted client to load projects without a primary environment", () => {
+    const { catalog, shells, ready, registry } = makeHarness(false);
+    registry.set(catalog, catalogState([REMOTE]));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(REMOTE), shellState("live"));
+    expect(registry.get(ready)).toBe(true);
+    registry.dispose();
+  });
+
+  it("waits for live snapshots through offline startup and reconnect", () => {
+    const { catalog, shells, ready, registry } = makeHarness();
+    registry.set(catalog, catalogState([LOCAL, REMOTE]));
+    registry.set(shells(LOCAL), shellState("live"));
+    expect(registry.get(ready)).toBe(false);
+
+    // An old cache and a reconnect in progress can both omit a real project.
+    registry.set(shells(REMOTE), shellState("cached"));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(REMOTE), shellState("synchronizing"));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(REMOTE), shellState("live"));
+    expect(registry.get(ready)).toBe(true);
+
+    registry.set(shells(REMOTE), shellState("cached"));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(shells(REMOTE), shellState("live"));
+    expect(registry.get(ready)).toBe(true);
+    registry.dispose();
+  });
+
+  it("stops waiting for an environment only when it leaves the catalog", () => {
+    const { catalog, shells, ready, registry } = makeHarness();
+    registry.set(catalog, catalogState([LOCAL, REMOTE]));
+    registry.set(shells(LOCAL), shellState("live"));
+    expect(registry.get(ready)).toBe(false);
+    registry.set(catalog, catalogState([LOCAL]));
+    expect(registry.get(ready)).toBe(true);
+    registry.dispose();
+  });
+});
diff --git a/apps/web/src/state/shell.ts b/apps/web/src/state/shell.ts
index dfb104e5c996..1f88da2f971d 100644
--- a/apps/web/src/state/shell.ts
+++ b/apps/web/src/state/shell.ts
@@ -7,12 +7,16 @@ import {
   createEnvironmentShellSummaryAtom,
   createEnvironmentSnapshotAtom,
   createShellEnvironmentAtoms,
+  type EnvironmentShellState,
 } from "@t3tools/client-runtime/state/shell";
+import type { EnvironmentCatalogState } from "@t3tools/client-runtime/state/connections";
+import type { EnvironmentId } from "@t3tools/contracts";
 import * as Option from "effect/Option";
 import { AsyncResult, Atom } from "effect/unstable/reactivity";
 
 import { environmentCatalog } from "../connection/catalog";
 import { connectionAtomRuntime } from "../connection/runtime";
+import { isHostedStaticApp } from "../hostedPairing";
 
 export const shellEnvironment = createShellEnvironmentAtoms(connectionAtomRuntime);
 export const environmentShell = createEnvironmentShellAtoms(connectionAtomRuntime);
@@ -46,3 +50,37 @@ export const allEnvironmentShellsBootstrappedAtom = Atom.make((get) => {
   }
   return true;
 }).pipe(Atom.withLabel("web-all-environment-shells-bootstrapped"));
+
+/** Cached or missing snapshots cannot establish that a saved project no longer exists. */
+export function createAllEnvironmentProjectSnapshotsReadyAtom(input: {
+  readonly catalogValueAtom: Atom.Atom<EnvironmentCatalogState>;
+  readonly shellStateValueAtom: (environmentId: EnvironmentId) => Atom.Atom<EnvironmentShellState>;
+  readonly requiresPrimaryEnvironment: boolean;
+}) {
+  return Atom.make((get) => {
+    const catalog = get(input.catalogValueAtom);
+    // The persisted catalog can emit before platform discovery registers the
+    // primary environment. Neither that gap nor an empty catalog proves absence.
+    if (!catalog.isReady || catalog.entries.size === 0) return false;
+    if (
+      input.requiresPrimaryEnvironment &&
+      !Array.from(catalog.entries.values()).some(
+        (entry) => entry.target._tag === "PrimaryConnectionTarget",
+      )
+    ) {
+      return false;
+    }
+    for (const environmentId of catalog.entries.keys()) {
+      const shell = get(input.shellStateValueAtom(environmentId));
+      if (shell.status !== "live" || Option.isNone(shell.snapshot)) return false;
+    }
+    return true;
+  }).pipe(Atom.withLabel("web-all-environment-project-snapshots-ready"));
+}
+
+export const allEnvironmentProjectSnapshotsReadyAtom =
+  createAllEnvironmentProjectSnapshotsReadyAtom({
+    catalogValueAtom: environmentCatalog.catalogValueAtom,
+    shellStateValueAtom: environmentShell.stateValueAtom,
+    requiresPrimaryEnvironment: !isHostedStaticApp(),
+  });
diff --git a/apps/web/src/state/terminalSessions.test.ts b/apps/web/src/state/terminalSessions.test.ts
new file mode 100644
index 000000000000..ee1c25f44394
--- /dev/null
+++ b/apps/web/src/state/terminalSessions.test.ts
@@ -0,0 +1,171 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+import { EnvironmentId, ThreadId, type TerminalSummary } from "@t3tools/contracts";
+import { selectRunningSubprocessTerminalIds } from "@t3tools/client-runtime/state/terminal";
+
+import { selectKnownTerminalSessions } from "./terminalSessions";
+
+vi.mock("./terminal", () => ({ terminalEnvironment: {} }));
+
+const environmentA = EnvironmentId.make("environment-a");
+const environmentB = EnvironmentId.make("environment-b");
+const threadA = ThreadId.make("thread-a");
+const threadB = ThreadId.make("thread-b");
+
+function summary(
+  threadId: string,
+  terminalId: string,
+  changes: Partial<TerminalSummary> = {},
+): TerminalSummary {
+  return {
+    threadId,
+    terminalId,
+    cwd: "/repo",
+    worktreePath: null,
+    status: "running",
+    pid: 123,
+    exitCode: null,
+    exitSignal: null,
+    hasRunningSubprocess: true,
+    label: "Terminal",
+    updatedAt: "2026-09-04T00:00:00.000Z",
+    ...changes,
+  };
+}
+
+describe("selectKnownTerminalSessions", () => {
+  it("preserves numeric terminal order and stable picker ties across threads", () => {
+    const metadata = [
+      summary(threadB, "terminal-2"),
+      summary(threadA, "terminal-10"),
+      summary(threadB, "terminal-1"),
+      summary(threadA, "terminal-1"),
+      summary(threadA, "terminal-01"),
+    ];
+    const all = selectKnownTerminalSessions(metadata, environmentA, null);
+    const selected = selectKnownTerminalSessions(metadata, environmentA, threadB);
+    expect(all.map((session) => `${session.target.threadId}/${session.target.terminalId}`)).toEqual(
+      [
+        "thread-b/terminal-1",
+        "thread-a/terminal-1",
+        "thread-a/terminal-01",
+        "thread-b/terminal-2",
+        "thread-a/terminal-10",
+      ],
+    );
+    expect(selected.map((session) => session.target.terminalId)).toEqual([
+      "terminal-1",
+      "terminal-2",
+    ]);
+    const repeated = [...metadata];
+    expect(selectKnownTerminalSessions(repeated, environmentA, null)).toBe(all);
+    expect(selectKnownTerminalSessions(repeated, environmentA, threadB)).toBe(selected);
+
+    const reordered = metadata.toReversed();
+    expect(selectKnownTerminalSessions(reordered, environmentA, threadB)).toBe(selected);
+    expect(
+      selectKnownTerminalSessions(reordered, environmentA, null).map(
+        (session) => `${session.target.threadId}/${session.target.terminalId}`,
+      ),
+    ).toEqual([
+      "thread-a/terminal-01",
+      "thread-a/terminal-1",
+      "thread-b/terminal-1",
+      "thread-b/terminal-2",
+      "thread-a/terminal-10",
+    ]);
+  });
+
+  it("changes only the affected group and preserves earlier snapshots", () => {
+    const first = summary(threadA, "terminal-1");
+    const second = summary(threadA, "terminal-2");
+    const other = summary(threadB, "terminal-1");
+    const metadata = [first, second, other];
+    const beforeA = selectKnownTerminalSessions(metadata, environmentA, threadA);
+    const beforeB = selectKnownTerminalSessions(metadata, environmentA, threadB);
+    Object.freeze(beforeA);
+    Object.freeze(beforeB);
+    const exited = {
+      ...second,
+      status: "exited" as const,
+      pid: null,
+      exitCode: 0,
+      hasRunningSubprocess: false,
+      label: "Finished",
+      updatedAt: "2026-09-04T00:00:01.000Z",
+    };
+    const next = [first, other, exited];
+    const afterA = selectKnownTerminalSessions(next, environmentA, threadA);
+    expect(selectKnownTerminalSessions(next, environmentA, threadB)).toBe(beforeB);
+    expect(afterA).not.toBe(beforeA);
+    expect(afterA[0]).toBe(beforeA[0]);
+    expect(afterA[1]?.state).toMatchObject({
+      status: "exited",
+      hasRunningSubprocess: false,
+      summary: { label: "Finished", pid: null, exitCode: 0 },
+    });
+    expect(selectRunningSubprocessTerminalIds(afterA)).toEqual(["terminal-1"]);
+    expect(beforeA[1]?.state).toMatchObject({
+      status: "running",
+      hasRunningSubprocess: true,
+      summary: { label: "Terminal", pid: 123 },
+    });
+    expect(selectKnownTerminalSessions(metadata, environmentA, threadA)).toBe(beforeA);
+
+    const renamed = [first, exited, { ...other, label: "Renamed" }];
+    expect(selectKnownTerminalSessions(renamed, environmentA, threadA)).toBe(afterA);
+    expect(
+      selectKnownTerminalSessions(renamed, environmentA, threadB)[0]?.state.summary?.label,
+    ).toBe("Renamed");
+    expect(selectKnownTerminalSessions([other], environmentA, threadA)).toEqual([]);
+    expect(selectKnownTerminalSessions([other], environmentA, threadB)).toBe(beforeB);
+  });
+
+  it("keeps environment targets separate when snapshots share the same objects", () => {
+    const metadata = [summary(threadA, "terminal-1")];
+    const first = selectKnownTerminalSessions(metadata, environmentA, threadA);
+    const second = selectKnownTerminalSessions(metadata, environmentB, threadA);
+    expect(first[0]?.target.environmentId).toBe(environmentA);
+    expect(second[0]?.target.environmentId).toBe(environmentB);
+    expect(first).not.toBe(second);
+    expect(first[0]).not.toBe(second[0]);
+    expect(selectKnownTerminalSessions([...metadata], environmentA, threadA)).toBe(first);
+    expect(selectKnownTerminalSessions([...metadata], environmentB, threadA)).toBe(second);
+  });
+
+  it("returns stable empty results without a connected environment or matching sessions", () => {
+    const metadata = [summary(threadA, "terminal-1")];
+    const empty = selectKnownTerminalSessions(null, environmentA, threadA);
+    expect(selectKnownTerminalSessions(metadata, null, threadA)).toBe(empty);
+    expect(selectKnownTerminalSessions([], environmentA, null)).toBe(empty);
+    expect(selectKnownTerminalSessions(metadata, environmentA, threadB)).toBe(empty);
+  });
+
+  it("does not materialize unrelated raw thread identifiers", () => {
+    const metadata = [summary(" untrimmed-thread ", "terminal-1"), summary(threadA, "terminal-2")];
+    expect(
+      selectKnownTerminalSessions(metadata, environmentA, threadA).map(
+        (session) => session.target.threadId,
+      ),
+    ).toEqual([threadA]);
+  });
+
+  it("reads the metadata array once for all thread selectors", () => {
+    const source = Array.from({ length: 40 }, (_, index) =>
+      summary(`thread-${index}`, "terminal-1"),
+    );
+    let reads = 0;
+    const metadata = new Proxy(source, {
+      get(target, property, receiver) {
+        if (typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) reads += 1;
+        return Reflect.get(target, property, receiver);
+      },
+    });
+    for (const item of source) {
+      expect(
+        selectKnownTerminalSessions(metadata, environmentA, ThreadId.make(item.threadId)),
+      ).toHaveLength(1);
+    }
+    expect(selectKnownTerminalSessions(metadata, environmentA, null)).toHaveLength(source.length);
+    expect(reads).toBe(source.length);
+  });
+});
diff --git a/apps/web/src/state/terminalSessions.ts b/apps/web/src/state/terminalSessions.ts
index 9e480df08b29..5e3a397826de 100644
--- a/apps/web/src/state/terminalSessions.ts
+++ b/apps/web/src/state/terminalSessions.ts
@@ -6,12 +6,121 @@ import {
   type KnownTerminalSession,
   type TerminalSessionState,
 } from "@t3tools/client-runtime/state/terminal";
-import { ThreadId, type EnvironmentId, type TerminalAttachInput } from "@t3tools/contracts";
+import {
+  ThreadId,
+  type EnvironmentId,
+  type TerminalAttachInput,
+  type TerminalSummary,
+} from "@t3tools/contracts";
 import { useMemo } from "react";
 
 import { useEnvironmentQuery } from "./query";
 import { terminalEnvironment } from "./terminal";
 
+const EMPTY_KNOWN_TERMINAL_SESSIONS = Object.freeze<ReadonlyArray<KnownTerminalSession>>([]);
+
+interface TerminalMetadataIndex {
+  readonly all: ReadonlyArray<TerminalSummary>;
+  readonly byThreadId: ReadonlyMap<string, ReadonlyArray<TerminalSummary>>;
+  readonly views: Map<EnvironmentId, Map<ThreadId | null, ReadonlyArray<KnownTerminalSession>>>;
+}
+
+const metadataIndexes = new WeakMap<ReadonlyArray<TerminalSummary>, TerminalMetadataIndex>();
+const sessionsBySummary = new WeakMap<TerminalSummary, Map<EnvironmentId, KnownTerminalSession>>();
+// Reuse groups a consumer still holds without keeping old group members alive
+// merely because their first summary remains in a newer metadata snapshot.
+const groupsByAnchor = new WeakMap<
+  TerminalSummary,
+  Map<
+    EnvironmentId,
+    {
+      readonly all?: WeakRef<ReadonlyArray<KnownTerminalSession>>;
+      readonly thread?: WeakRef<ReadonlyArray<KnownTerminalSession>>;
+    }
+  >
+>();
+
+function knownSession(
+  summary: TerminalSummary,
+  environmentId: EnvironmentId,
+): KnownTerminalSession {
+  let byEnvironment = sessionsBySummary.get(summary);
+  const previous = byEnvironment?.get(environmentId);
+  if (previous) return previous;
+  const session = {
+    target: {
+      environmentId,
+      threadId: ThreadId.make(summary.threadId),
+      terminalId: summary.terminalId,
+    },
+    state: combineTerminalSessionState(summary, EMPTY_TERMINAL_BUFFER_STATE),
+  };
+  if (!byEnvironment) {
+    byEnvironment = new Map();
+    sessionsBySummary.set(summary, byEnvironment);
+  }
+  byEnvironment.set(environmentId, session);
+  return session;
+}
+
+function terminalMetadataIndex(metadata: ReadonlyArray<TerminalSummary>): TerminalMetadataIndex {
+  let index = metadataIndexes.get(metadata);
+  if (!index) {
+    const compare = new Intl.Collator(undefined, { numeric: true }).compare;
+    const all = metadata.toSorted((left, right) => compare(left.terminalId, right.terminalId));
+    const byThreadId = new Map<string, TerminalSummary[]>();
+    for (const summary of all) {
+      const group = byThreadId.get(summary.threadId);
+      if (group) group.push(summary);
+      else byThreadId.set(summary.threadId, [summary]);
+    }
+    index = { all, byThreadId, views: new Map() };
+    metadataIndexes.set(metadata, index);
+  }
+  return index;
+}
+
+/** Share one ordered index per immutable snapshot without changing metadata subscriptions. */
+export function selectKnownTerminalSessions(
+  metadata: ReadonlyArray<TerminalSummary> | null,
+  environmentId: EnvironmentId | null,
+  threadId: ThreadId | null,
+): ReadonlyArray<KnownTerminalSession> {
+  if (environmentId === null || metadata === null || metadata.length === 0) {
+    return EMPTY_KNOWN_TERMINAL_SESSIONS;
+  }
+  const index = terminalMetadataIndex(metadata);
+  let views = index.views.get(environmentId);
+  const cached = views?.get(threadId);
+  if (cached) return cached;
+  const summaries = threadId === null ? index.all : index.byThreadId.get(threadId);
+  if (!summaries || summaries.length === 0) return EMPTY_KNOWN_TERMINAL_SESSIONS;
+
+  const anchor = summaries[0]!;
+  const kind = threadId === null ? "all" : "thread";
+  let groups = groupsByAnchor.get(anchor);
+  const previousGroups = groups?.get(environmentId);
+  const previous = previousGroups?.[kind]?.deref();
+  const sessions =
+    previous?.length === summaries.length &&
+    previous.every((session, index) => session.state.summary === summaries[index])
+      ? previous
+      : summaries.map((summary) => knownSession(summary, environmentId));
+  if (!groups) {
+    groups = new Map();
+    groupsByAnchor.set(anchor, groups);
+  }
+  if (sessions !== previous) {
+    groups.set(environmentId, { ...previousGroups, [kind]: new WeakRef(sessions) });
+  }
+  if (!views) {
+    views = new Map();
+    index.views.set(environmentId, views);
+  }
+  views.set(threadId, sessions);
+  return sessions;
+}
+
 export function useAttachedTerminalSession(input: {
   readonly environmentId: EnvironmentId | null;
   readonly terminal: TerminalAttachInput | null;
@@ -38,11 +147,11 @@ export function useAttachedTerminalSession(input: {
       return EMPTY_TERMINAL_SESSION_STATE;
     }
     const summary =
-      metadata.data?.find(
-        (terminal) =>
-          terminal.threadId === input.terminal?.threadId &&
-          terminal.terminalId === input.terminal?.terminalId,
-      ) ?? null;
+      (metadata.data === null
+        ? null
+        : terminalMetadataIndex(metadata.data)
+            .byThreadId.get(input.terminal.threadId)
+            ?.find((terminal) => terminal.terminalId === input.terminal?.terminalId)) ?? null;
     const state = combineTerminalSessionState(summary, attach.data ?? EMPTY_TERMINAL_BUFFER_STATE);
     return attach.error === null ? state : { ...state, error: attach.error, status: "error" };
   }, [attach.data, attach.error, input.environmentId, input.terminal, metadata.data]);
@@ -60,31 +169,16 @@ export function useKnownTerminalSessions(input: {
           input: null,
         }),
   );
-  return useMemo(() => {
-    if (input.environmentId === null) {
-      return [];
-    }
-    return (metadata.data ?? [])
-      .filter((summary) => input.threadId === null || summary.threadId === input.threadId)
-      .map((summary) => ({
-        target: {
-          environmentId: input.environmentId!,
-          threadId: ThreadId.make(summary.threadId),
-          terminalId: summary.terminalId,
-        },
-        state: combineTerminalSessionState(summary, EMPTY_TERMINAL_BUFFER_STATE),
-      }))
-      .sort((left, right) =>
-        left.target.terminalId.localeCompare(right.target.terminalId, undefined, {
-          numeric: true,
-        }),
-      );
-  }, [input.environmentId, input.threadId, metadata.data]);
+  return useMemo(
+    () => selectKnownTerminalSessions(metadata.data, input.environmentId, input.threadId),
+    [input.environmentId, input.threadId, metadata.data],
+  );
 }
 
 export function useThreadRunningTerminalIds(input: {
   readonly environmentId: EnvironmentId | null;
   readonly threadId: ThreadId | null;
 }): ReadonlyArray<string> {
-  return selectRunningSubprocessTerminalIds(useKnownTerminalSessions(input));
+  const sessions = useKnownTerminalSessions(input);
+  return useMemo(() => selectRunningSubprocessTerminalIds(sessions), [sessions]);
 }
diff --git a/apps/web/src/state/usage.test.tsx b/apps/web/src/state/usage.test.tsx
new file mode 100644
index 000000000000..e01478e6a71a
--- /dev/null
+++ b/apps/web/src/state/usage.test.tsx
@@ -0,0 +1,166 @@
+import { EnvironmentId, UsageDay, USAGE_CONTRACT_VERSION } from "@t3tools/contracts";
+import { act, useLayoutEffect } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+import { useUsage, type EnvironmentUsageStatus, type UsageView } from "./usage";
+
+const testState = vi.hoisted(() => ({ environments: [] as EnvironmentUsageStatus[] }));
+vi.mock("@effect/atom-react", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@effect/atom-react")>()),
+  useAtomValue: () => testState.environments,
+}));
+
+const input = {
+  sinceDay: UsageDay.make("2026-09-04"),
+  untilDay: UsageDay.make("2026-09-04"),
+  timeZone: "UTC",
+};
+
+function environment(id: string, cost: number | null, hostId = id): EnvironmentUsageStatus {
+  return {
+    environmentId: EnvironmentId.make(id),
+    label: id,
+    isPending: cost === null,
+    error: null,
+    summary:
+      cost === null
+        ? null
+        : {
+            ...input,
+            contractVersion: USAGE_CONTRACT_VERSION,
+            readAt: "2026-09-04T12:00:00Z",
+            buckets: [
+              {
+                day: input.sinceDay,
+                provider: "codex",
+                model: id,
+                totals: {
+                  uncachedInputTokens: 100,
+                  cachedInputTokens: 0,
+                  cacheCreationTokens: 0,
+                  outputTokens: 50,
+                  reasoningTokens: 0,
+                },
+                costUsd: cost,
+                cacheSavingsUsd: 0,
+                costSource: "modelPriced",
+                records: 1,
+                unpricedRecords: 0,
+                sessions: 1,
+              },
+            ],
+            sources: [
+              {
+                fingerprint: {
+                  hostId,
+                  provider: "codex",
+                  resolvedHomePath: "/sessions",
+                  volumeId: hostId,
+                },
+                status: "ok",
+                scannedFiles: 1,
+                skippedFiles: 0,
+                malformedRecords: 0,
+                distinctSessions: 1,
+                message: null,
+              },
+            ],
+            pricing: { status: "fresh", source: "test", fetchedAt: null, knownModels: 1 },
+            scanDurationMs: 1,
+          },
+  };
+}
+
+let renderer: ReactTestRenderer | undefined;
+let latest: UsageView;
+
+function Probe({ selected }: { selected: ReadonlySet<EnvironmentId> | null }) {
+  const usage = useUsage(input, selected);
+  useLayoutEffect(() => {
+    latest = usage;
+  }, [usage]);
+  return null;
+}
+
+async function select(...ids: string[]) {
+  await act(() => {
+    renderer?.update(<Probe selected={new Set(ids.map((id) => EnvironmentId.make(id)))} />);
+  });
+}
+
+beforeEach(async () => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  testState.environments = [environment("a", 10), environment("b", 20), environment("slow", null)];
+  await act(() => {
+    renderer = create(<Probe selected={null} />);
+  });
+});
+
+afterEach(async () => {
+  await act(() => renderer?.unmount());
+  vi.unstubAllGlobals();
+});
+
+describe("usage environment selection", () => {
+  it("starts with all environments and adds results as they arrive", async () => {
+    expect(latest.merged.costUsd).toBe(30);
+    expect(latest.isPending).toBe(false);
+    expect(latest.isPartial).toBe(true);
+
+    testState.environments = [...testState.environments.slice(0, 2), environment("slow", 40)];
+    await act(() => renderer?.update(<Probe selected={null} />));
+    expect(latest.merged.costUsd).toBe(70);
+    expect(latest.isPartial).toBe(false);
+  });
+
+  it("excludes unselected usage and pending environments, then restores all", async () => {
+    await select("b");
+    expect(latest.merged.costUsd).toBe(20);
+    expect(latest.merged.models.map((model) => model.model)).toEqual(["b"]);
+    expect(latest.isPending).toBe(false);
+    expect(latest.isPartial).toBe(false);
+    expect(latest.environments).toHaveLength(3);
+
+    await act(() => renderer?.update(<Probe selected={null} />));
+    expect(latest.merged.costUsd).toBe(30);
+    expect(latest.isPartial).toBe(true);
+  });
+
+  it("distinguishes a pending selection from an empty or failed selection", async () => {
+    await select("slow");
+    expect(latest.isPending).toBe(true);
+    expect(latest.merged.costUsd).toBe(0);
+
+    await select();
+    expect(latest.selectedEnvironments).toHaveLength(0);
+    expect(latest.isPending).toBe(false);
+    expect(latest.isPartial).toBe(false);
+
+    testState.environments = [{ ...environment("slow", null), isPending: false, error: "Offline" }];
+    await select("slow");
+    expect(latest.isPending).toBe(false);
+    expect(latest.isPartial).toBe(false);
+  });
+
+  it("deduplicates within the selection so an excluded owner cannot hide usage", async () => {
+    testState.environments = [environment("a", 10, "shared"), environment("b", 20, "shared")];
+    await act(() => renderer?.update(<Probe selected={null} />));
+    expect(latest.merged.costUsd).toBe(10);
+
+    await select("b");
+    expect(latest.merged.costUsd).toBe(20);
+    expect(latest.merged.duplicateSources).toEqual([]);
+  });
+
+  it("keeps selected cached results visible during a refresh", async () => {
+    testState.environments = [
+      { ...environment("a", 10), isPending: true },
+      environment("slow", null),
+    ];
+    await select("a");
+    expect(latest.merged.costUsd).toBe(10);
+    expect(latest.isPending).toBe(false);
+    expect(latest.isPartial).toBe(false);
+  });
+});
diff --git a/apps/web/src/state/usage.ts b/apps/web/src/state/usage.ts
index 7d71a4d531b2..9afc745add18 100644
--- a/apps/web/src/state/usage.ts
+++ b/apps/web/src/state/usage.ts
@@ -61,7 +61,8 @@ const usageByWindowAtom = Atom.family((windowKey: string) =>
 export interface UsageView {
   readonly merged: MergedUsage;
   readonly environments: readonly EnvironmentUsageStatus[];
-  /** True until at least one environment has answered. */
+  readonly selectedEnvironments: readonly EnvironmentUsageStatus[];
+  /** True until at least one selected environment has answered. */
   readonly isPending: boolean;
   /**
    * True while environments that have not failed are still answering. Failed
@@ -72,7 +73,10 @@ export interface UsageView {
   readonly refresh: () => void;
 }
 
-export function useUsage(input: UsageSummaryInput): UsageView {
+export function useUsage(
+  input: UsageSummaryInput,
+  selectedEnvironmentIds: ReadonlySet<EnvironmentId> | null = null,
+): UsageView {
   const windowKey = useMemo(
     () =>
       JSON.stringify({
@@ -95,6 +99,15 @@ export function useUsage(input: UsageSummaryInput): UsageView {
   );
   const atom = usageByWindowAtom(windowKey);
   const environments = useAtomValue(atom);
+  const selectedEnvironments = useMemo(
+    () =>
+      selectedEnvironmentIds === null
+        ? environments
+        : environments.filter((environment) =>
+            selectedEnvironmentIds.has(environment.environmentId),
+          ),
+    [environments, selectedEnvironmentIds],
+  );
 
   // Refreshing only the derived atom would re-read the per-environment SWR
   // queries within their stale window and change nothing. Refresh each
@@ -105,7 +118,7 @@ export function useUsage(input: UsageSummaryInput): UsageView {
   // not the refetch succeeds: an offline environment still recounts tokens.
   const refresh = useCallback(() => {
     const input = JSON.parse(windowKey) as UsageSummaryInput;
-    for (const environment of environments) {
+    for (const environment of selectedEnvironments) {
       const { environmentId } = environment;
       const query = serverEnvironment.usageSummary({ environmentId, input });
       void runAtomCommand(
@@ -115,10 +128,10 @@ export function useUsage(input: UsageSummaryInput): UsageView {
         { reportFailure: false },
       ).finally(() => appAtomRegistry.refresh(query));
     }
-  }, [environments, windowKey]);
+  }, [selectedEnvironments, windowKey]);
 
   const merged = useMemo(() => {
-    const answered: EnvironmentUsage[] = environments.flatMap((environment) =>
+    const answered: EnvironmentUsage[] = selectedEnvironments.flatMap((environment) =>
       environment.summary === null
         ? []
         : [
@@ -130,16 +143,19 @@ export function useUsage(input: UsageSummaryInput): UsageView {
           ],
     );
     return mergeUsage(answered, USAGE_CONTRACT_VERSION);
-  }, [environments]);
+  }, [selectedEnvironments]);
 
-  const answeredCount = environments.filter((environment) => environment.summary !== null).length;
-  const stillReporting = environments.filter(
+  const answeredCount = selectedEnvironments.filter(
+    (environment) => environment.summary !== null,
+  ).length;
+  const stillReporting = selectedEnvironments.filter(
     (environment) => environment.summary === null && environment.error === null,
   ).length;
 
   return {
     merged,
     environments,
+    selectedEnvironments,
     isPending: answeredCount === 0 && stillReporting > 0,
     isPartial: answeredCount > 0 && stillReporting > 0,
     refresh,
diff --git a/apps/web/src/terminal-links.test.ts b/apps/web/src/terminal-links.test.ts
index 34c6c9830a0a..3c466378ba8b 100644
--- a/apps/web/src/terminal-links.test.ts
+++ b/apps/web/src/terminal-links.test.ts
@@ -6,8 +6,6 @@ import {
   isTerminalLinkActivation,
   isTerminalUrl,
   resolvePathLinkTarget,
-  resolveWrappedTerminalLinkRange,
-  wrappedTerminalLinkRangeIntersectsBufferLine,
   type TerminalBufferLineLike,
 } from "./terminal-links";
 
@@ -154,46 +152,6 @@ describe("collectWrappedTerminalLinkLine", () => {
   });
 });
 
-describe("resolveWrappedTerminalLinkRange", () => {
-  it("maps wrapped URL matches back to the correct buffer rows", () => {
-    const prefix = "see ";
-    const firstSegment = `${prefix}https://example.com/a`;
-    const secondSegment = "/bc?x=1";
-    const lines = [
-      createBufferLine("prompt> "),
-      createBufferLine(firstSegment),
-      createBufferLine(secondSegment, true),
-    ];
-    const wrappedLine = collectWrappedTerminalLinkLine(2, (index) => lines[index]);
-
-    expect(wrappedLine).not.toBeNull();
-    if (!wrappedLine) {
-      throw new Error("Expected wrapped terminal line to be present.");
-    }
-
-    const [match] = extractTerminalLinks(wrappedLine.text);
-    expect(match).toEqual({
-      kind: "url",
-      text: "https://example.com/a/bc?x=1",
-      start: prefix.length,
-      end: firstSegment.length + secondSegment.length,
-    });
-    if (!match) {
-      throw new Error("Expected wrapped URL match to be present.");
-    }
-
-    const range = resolveWrappedTerminalLinkRange(wrappedLine, match);
-
-    expect(range).toEqual({
-      start: { x: prefix.length + 1, y: 2 },
-      end: { x: secondSegment.length, y: 3 },
-    });
-    expect(wrappedTerminalLinkRangeIntersectsBufferLine(range, 2)).toBe(true);
-    expect(wrappedTerminalLinkRangeIntersectsBufferLine(range, 3)).toBe(true);
-    expect(wrappedTerminalLinkRangeIntersectsBufferLine(range, 4)).toBe(false);
-  });
-});
-
 describe("resolvePathLinkTarget", () => {
   it("resolves relative paths against cwd", () => {
     expect(
diff --git a/apps/web/src/terminal-links.ts b/apps/web/src/terminal-links.ts
index 204d0a742a05..59e2082a7359 100644
--- a/apps/web/src/terminal-links.ts
+++ b/apps/web/src/terminal-links.ts
@@ -14,16 +14,6 @@ export interface TerminalLinkMatch {
   end: number;
 }
 
-export interface TerminalLinkBufferPosition {
-  x: number;
-  y: number;
-}
-
-export interface TerminalLinkBufferRange {
-  start: TerminalLinkBufferPosition;
-  end: TerminalLinkBufferPosition;
-}
-
 export interface TerminalBufferLineLike {
   readonly isWrapped?: boolean;
   translateToString(trimRight?: boolean): string;
@@ -199,43 +189,6 @@ export function collectWrappedTerminalLinkLine(
   };
 }
 
-function resolveCharacterPosition(
-  segments: ReadonlyArray<WrappedTerminalLinkLineSegment>,
-  characterIndex: number,
-): TerminalLinkBufferPosition {
-  for (const segment of segments) {
-    if (characterIndex < segment.endIndex) {
-      return {
-        x: characterIndex - segment.startIndex + 1,
-        y: segment.bufferLineNumber,
-      };
-    }
-  }
-
-  const lastSegment = segments[segments.length - 1];
-  return {
-    x: Math.max(lastSegment?.text.length ?? 0, 1),
-    y: lastSegment?.bufferLineNumber ?? 1,
-  };
-}
-
-export function resolveWrappedTerminalLinkRange(
-  wrappedLine: WrappedTerminalLinkLine,
-  match: Pick<TerminalLinkMatch, "start" | "end">,
-): TerminalLinkBufferRange {
-  return {
-    start: resolveCharacterPosition(wrappedLine.segments, match.start),
-    end: resolveCharacterPosition(wrappedLine.segments, match.end - 1),
-  };
-}
-
-export function wrappedTerminalLinkRangeIntersectsBufferLine(
-  range: TerminalLinkBufferRange,
-  bufferLineNumber: number,
-): boolean {
-  return range.start.y <= bufferLineNumber && bufferLineNumber <= range.end.y;
-}
-
 export function isTerminalLinkActivation(
   event: Pick<MouseEvent, "metaKey" | "ctrlKey">,
   platform = typeof navigator === "undefined" ? "" : navigator.platform,
diff --git a/apps/web/src/terminal/ghostty/core.test.ts b/apps/web/src/terminal/ghostty/core.test.ts
index 8048d221178c..48cc4256de61 100644
--- a/apps/web/src/terminal/ghostty/core.test.ts
+++ b/apps/web/src/terminal/ghostty/core.test.ts
@@ -1,6 +1,24 @@
-import { describe, expect, it } from "vite-plus/test";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
+import {
+  applyTerminalAttachStreamEvent,
+  DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
+  INITIAL_TERMINAL_OUTPUT_CURSOR,
+  nextTerminalAttachSeedState,
+  readTerminalOutputUpdate,
+  terminalOutputText,
+  type TerminalBufferState,
+} from "@t3tools/client-runtime/state/terminal";
 
-import { ghosttyCellText } from "./core";
+import { writeTerminalOutputUpdate } from "../../components/ThreadTerminalDrawer";
+import { GHOSTTY_CELL_WIDE, GhosttyTerminalCore, ghosttyCellText } from "./core";
+import { loadGhosttyRuntime } from "./runtime";
+
+vi.mock("./vendor/ghostty-vt.wasm?url", async () => ({
+  default: (await import("./vendor/ghostty-vt.wasm?inline")).default,
+}));
+vi.mock("./vendor/ghostty-write-pty.wasm?url&no-inline", async () => ({
+  default: (await import("./vendor/ghostty-write-pty.wasm?inline")).default,
+}));
 
 function codepointView(codepoints: ReadonlyArray<number>): DataView {
   const view = new DataView(new ArrayBuffer(codepoints.length * 4));
@@ -30,7 +48,333 @@ describe("ghosttyCellText", () => {
     expect([...text]).toEqual(["\u{1F642}", "\u{20E3}"]);
   });
 
+  it("converts a single astral codepoint", () => {
+    expect(ghosttyCellText(codepointView([0x1f642]), 1)).toBe("🙂");
+  });
+
   it("returns an empty string for empty cells", () => {
     expect(ghosttyCellText(codepointView([]), 0)).toBe("");
   });
 });
+
+describe("GhosttyTerminalCore snapshots", () => {
+  const cores = new Set<GhosttyTerminalCore>();
+
+  async function createCore(onData: (data: string) => void = () => {}) {
+    const core = await GhosttyTerminalCore.create(
+      12,
+      3,
+      8,
+      16,
+      {
+        foreground: { r: 255, g: 255, b: 255 },
+        background: { r: 0, g: 0, b: 0 },
+        cursor: { r: 255, g: 255, b: 255 },
+      },
+      onData,
+    );
+    cores.add(core);
+    return core;
+  }
+
+  function createSession(history: string) {
+    return applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {
+      type: "snapshot",
+      snapshot: {
+        threadId: "terminal-stream-test",
+        terminalId: "term-1",
+        cwd: "/repo",
+        worktreePath: null,
+        status: "running",
+        pid: 123,
+        history,
+        exitCode: null,
+        exitSignal: null,
+        label: "Terminal",
+        updatedAt: "2026-09-04T00:00:00.000Z",
+      },
+    });
+  }
+
+  function append(state: TerminalBufferState, data: string) {
+    return applyTerminalAttachStreamEvent(state, {
+      type: "output",
+      threadId: "terminal-stream-test",
+      terminalId: "term-1",
+      data,
+    });
+  }
+
+  afterEach(() => {
+    for (const core of cores) core.dispose();
+    cores.clear();
+    vi.restoreAllMocks();
+  });
+
+  it("preserves styles, wide cells, and selection after shared memory grows", async () => {
+    const core = await createCore();
+    const runtime = await loadGhosttyRuntime();
+    const grapheme = `e${"\u0301".repeat(64)}`;
+    core.write(`\x1b[1;3;4;8;9;53;38;2;123;45;67;48;2;9;8;7m${grapheme}\x1b[0m界🙂`);
+    const cells = core.snapshot().rowData[0]!.cells;
+    expect(cells[0]).toEqual({
+      text: grapheme,
+      wide: 0,
+      foreground: { r: 123, g: 45, b: 67 },
+      background: { r: 9, g: 8, b: 7 },
+      bold: true,
+      italic: true,
+      invisible: true,
+      strikethrough: true,
+      overline: true,
+      underline: true,
+      selected: false,
+    });
+    expect(cells.slice(1, 5).map(({ text, wide }) => ({ text, wide }))).toEqual([
+      { text: "界", wide: 0 },
+      { text: "", wide: GHOSTTY_CELL_WIDE.spacerTail },
+      { text: "🙂", wide: 0 },
+      { text: "", wide: GHOSTTY_CELL_WIDE.spacerTail },
+    ]);
+
+    runtime.memory.grow(1);
+    core.setSelection({ x: 0, y: 0 }, { x: 2, y: 0 });
+    expect(core.snapshot().rowData[0]!.cells[0]).toEqual({ ...cells[0], selected: true });
+    core.clearSelection();
+    expect(core.snapshot().rowData[0]!.cells[0]).toEqual(cells[0]);
+
+    core.resetAndWrite("\x1b[2;7;38;2;40;100;200;48;2;12;34;56mC\x1b[0m");
+    expect(core.snapshot().rowData[0]!.cells[0]).toMatchObject({
+      text: "C",
+      foreground: { r: 22, g: 59, b: 112 },
+      background: { r: 40, g: 100, b: 200 },
+      bold: false,
+      underline: false,
+      selected: false,
+    });
+  });
+
+  it("reuses a grown grapheme buffer and releases it on disposal", async () => {
+    const core = await createCore();
+    const runtime = await loadGhosttyRuntime();
+    core.write("ASCII");
+    core.snapshot();
+
+    const grapheme = `z${"\u0301".repeat(256)}`;
+    core.resetAndWrite(`${grapheme}X`);
+    const alloc = vi.spyOn(runtime, "alloc");
+    const free = vi.spyOn(runtime, "free");
+    expect(
+      core
+        .snapshot()
+        .rowData[0]!.cells.slice(0, 2)
+        .map((cell) => cell.text),
+    ).toEqual([grapheme, "X"]);
+    expect(alloc).toHaveBeenCalledTimes(1);
+    const allocation = alloc.mock.results[0]!;
+    if (allocation.type !== "return") throw new Error("Grapheme allocation did not return");
+    const buffer = allocation.value;
+    const capacity = alloc.mock.calls[0]![0];
+
+    core.write("\rQ\u0301");
+    alloc.mockClear();
+    expect(core.snapshot().rowData[0]!.cells[0]!.text).toBe("Q\u0301");
+    expect(alloc).not.toHaveBeenCalled();
+    core.dispose();
+    expect(free).toHaveBeenCalledWith(buffer, capacity);
+  });
+
+  it.each(["varied", "identical"] as const)(
+    "preserves Ghostty state through a full MiB of %s output without rollover resets",
+    async (kind) => {
+      const [core, reference] = await Promise.all([createCore(), createCore()]);
+      const initial = "\x1b[31m";
+      let state = createSession(initial);
+      const first = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR);
+      writeTerminalOutputUpdate(core, first);
+      reference.resetAndWrite(initial);
+      let cursor = first.cursor;
+      const reset = vi.spyOn(core, "resetAndWrite");
+      const inputs: string[] = [];
+      let receivedCharacters = 0;
+
+      for (let index = 0; index < 128; index += 1) {
+        const data =
+          kind === "identical"
+            ? "x".repeat(8192)
+            : `${index.toString().padStart(4, "0")}\r\n${"x".repeat(8186)}`;
+        inputs.push(data);
+        state = append(state, data);
+        const update = readTerminalOutputUpdate(state.output, cursor);
+        if (update.type !== "append") throw new Error(`Expected append, received ${update.type}`);
+        receivedCharacters += update.data.length;
+        writeTerminalOutputUpdate(core, update);
+        cursor = update.cursor;
+      }
+
+      reference.write(inputs.join(""));
+      expect(receivedCharacters).toBe(1024 * 1024);
+      expect(state.output.retainedBytes).toBe(DEFAULT_MAX_TERMINAL_BUFFER_BYTES);
+      expect(reset).not.toHaveBeenCalled();
+      expect(core.snapshot()).toEqual(reference.snapshot());
+    },
+  );
+
+  it("preserves Unicode and split ANSI parser state across batched renderer reads", async () => {
+    const [core, reference] = await Promise.all([createCore(), createCore()]);
+    let state = createSession("");
+    const first = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR);
+    writeTerminalOutputUpdate(core, first);
+    let cursor = first.cursor;
+    const reset = vi.spyOn(core, "resetAndWrite");
+    const inputs = [
+      `${"a".repeat(16_383)}🙂`,
+      "\x1b[3",
+      "1m",
+      "e",
+      "\u0301界🙂",
+      "\x1b[0",
+      "m\r\n",
+      "\x1b]8;;https://t3.codes\x1b",
+      "\\link",
+      "\x1b]8;;\x1b",
+      "\\\x1b[?1049h",
+      "alternate",
+      "\x1b[?1049l",
+      "\r\nend",
+    ];
+    let received = "";
+    for (const [index, data] of inputs.entries()) {
+      state = append(state, data);
+      if (index % 3 !== 0 && index !== inputs.length - 1) continue;
+      const update = readTerminalOutputUpdate(state.output, cursor);
+      if (update.type !== "append") throw new Error(`Expected append, received ${update.type}`);
+      received += update.data;
+      writeTerminalOutputUpdate(core, update);
+      cursor = update.cursor;
+    }
+
+    reference.write(inputs.join(""));
+    expect(received).toBe(inputs.join(""));
+    expect(reset).not.toHaveBeenCalled();
+    expect(core.snapshot()).toEqual(reference.snapshot());
+  });
+
+  it("answers a live VT query when batched reads cross a chunk compaction", async () => {
+    const replies: string[] = [];
+    const core = await createCore((data) => replies.push(data));
+    core.write("\x1b[5n");
+    expect(replies).toEqual(["\x1b[0n"]);
+    replies.length = 0;
+
+    let state = createSession("");
+    const initial = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR);
+    writeTerminalOutputUpdate(core, initial);
+    let cursor = initial.cursor;
+    for (let index = 0; index < 1000; index += 1) {
+      state = append(state, "x");
+      const update = readTerminalOutputUpdate(state.output, cursor);
+      writeTerminalOutputUpdate(core, update);
+      cursor = update.cursor;
+    }
+    for (let index = 0; index < 24; index += 1) state = append(state, "x");
+    state = append(state, "\x1b[5n");
+    const update = readTerminalOutputUpdate(state.output, cursor);
+    writeTerminalOutputUpdate(core, update);
+
+    expect({ type: update.type, replies }).toEqual({ type: "append", replies: ["\x1b[0n"] });
+  });
+
+  it("recovers a lagging renderer once from bounded output and resumes appending", async () => {
+    const [core, reference] = await Promise.all([createCore(), createCore()]);
+    let state = createSession("\x1b[31mold");
+    const initial = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR);
+    writeTerminalOutputUpdate(core, initial);
+    const reset = vi.spyOn(core, "resetAndWrite");
+    const data = "line\r\n".repeat(8192);
+    for (let index = 0; index < 16; index += 1) state = append(state, data);
+
+    const recovery = readTerminalOutputUpdate(state.output, initial.cursor);
+    if (recovery.type !== "reset") throw new Error(`Expected reset, received ${recovery.type}`);
+    expect(new TextEncoder().encode(recovery.data).byteLength).toBe(
+      DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
+    );
+    writeTerminalOutputUpdate(core, recovery);
+    reference.resetAndWrite(recovery.data);
+    expect(core.snapshot()).toEqual(reference.snapshot());
+
+    state = append(state, "\r\nlatest");
+    const next = readTerminalOutputUpdate(state.output, recovery.cursor);
+    expect(next.type).toBe("append");
+    writeTerminalOutputUpdate(core, next);
+    reference.write("\r\nlatest");
+    expect(reset).toHaveBeenCalledTimes(1);
+    expect(core.snapshot()).toEqual(reference.snapshot());
+  });
+
+  it("replays the latest retained output when WASM arrives after several events", async () => {
+    const pendingCore = createCore();
+    let state = createSession("before");
+    state = append(state, "\r\nduring ");
+    state = append(state, "🙂 load");
+    const core = await pendingCore;
+    const first = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR);
+    writeTerminalOutputUpdate(core, first);
+    const reference = await createCore();
+    reference.resetAndWrite(terminalOutputText(state.output));
+    const reset = vi.spyOn(core, "resetAndWrite");
+
+    state = append(state, "\r\nafter");
+    const next = readTerminalOutputUpdate(state.output, first.cursor);
+    expect(next).toMatchObject({ type: "append", data: "\r\nafter" });
+    writeTerminalOutputUpdate(core, next);
+    reference.write("\r\nafter");
+    expect(reset).not.toHaveBeenCalled();
+    expect(core.snapshot()).toEqual(reference.snapshot());
+  });
+
+  it("resets real Ghostty for a repeated snapshot, clear, restart, and a fresh attach", async () => {
+    const [core, reference] = await Promise.all([createCore(), createCore()]);
+    let state = createSession("hello");
+    const initial = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR);
+    writeTerminalOutputUpdate(core, initial);
+    let cursor = initial.cursor;
+
+    const snapshot = {
+      threadId: "terminal-stream-test",
+      terminalId: "term-1",
+      cwd: "/repo",
+      worktreePath: null,
+      status: "running" as const,
+      pid: 456,
+      history: "hello",
+      exitCode: null,
+      exitSignal: null,
+      label: "Terminal",
+      updatedAt: "2026-09-04T00:00:01.000Z",
+    };
+    const events = [
+      { type: "snapshot", snapshot },
+      { type: "cleared", threadId: snapshot.threadId, terminalId: snapshot.terminalId },
+      { type: "restarted", threadId: snapshot.threadId, terminalId: snapshot.terminalId, snapshot },
+    ] as const;
+    for (const event of events) {
+      core.write("\r\nstale local text");
+      state = applyTerminalAttachStreamEvent(state, event);
+      const update = readTerminalOutputUpdate(state.output, cursor);
+      expect(update.type).toBe("reset");
+      writeTerminalOutputUpdate(core, update);
+      cursor = update.cursor;
+      reference.resetAndWrite(event.type === "cleared" ? "" : "hello");
+      expect(core.snapshot()).toEqual(reference.snapshot());
+    }
+
+    core.write("\r\nstale local text");
+    state = createSession("hello");
+    const reattached = readTerminalOutputUpdate(state.output, cursor);
+    expect(reattached.type).toBe("reset");
+    writeTerminalOutputUpdate(core, reattached);
+    reference.resetAndWrite("hello");
+    expect(core.snapshot()).toEqual(reference.snapshot());
+  });
+});
diff --git a/apps/web/src/terminal/ghostty/core.ts b/apps/web/src/terminal/ghostty/core.ts
index 6f6cbbe0a888..d01e20529d45 100644
--- a/apps/web/src/terminal/ghostty/core.ts
+++ b/apps/web/src/terminal/ghostty/core.ts
@@ -174,6 +174,7 @@ function sameColor(left: GhosttyColor, right: GhosttyColor): boolean {
  * every codepoint into String.fromCodePoint at once.
  */
 export function ghosttyCellText(codepointView: DataView, graphemeLength: number): string {
+  if (graphemeLength === 1) return String.fromCodePoint(codepointView.getUint32(0, true));
   const CHUNK_SIZE = 4_096;
   let text = "";
   for (let start = 0; start < graphemeLength; start += CHUNK_SIZE) {
@@ -206,6 +207,8 @@ export class GhosttyTerminalCore {
   private ptyWriterId = 0;
   private ptyWriter: ((data: string) => void) | null = null;
   private scratch = 0;
+  private graphemes = 0;
+  private graphemeCapacity = 0;
   private style = 0;
   private scrollbar = 0;
   private rows: GhosttyRow[] = [];
@@ -878,6 +881,7 @@ export class GhosttyTerminalCore {
       this.runtime.free(this.scrollbar, this.runtime.layout("GhosttyTerminalScrollbar").size);
     }
     if (this.scratch) this.runtime.free(this.scratch, 16);
+    if (this.graphemes) this.runtime.free(this.graphemes, this.graphemeCapacity);
     for (const slot of [
       this.mouseEventSlot,
       this.mouseEncoderSlot,
@@ -944,6 +948,7 @@ export class GhosttyTerminalCore {
       ),
     );
     const cellsIterator = this.runtime.readPointer(this.rowCellsSlot);
+    const { size: styleSize, fields: styleFields } = this.runtime.layout("GhosttyStyle");
     const cells: GhosttyCell[] = [];
     while (
       cells.length < cols &&
@@ -951,7 +956,6 @@ export class GhosttyTerminalCore {
     ) {
       let foreground = this.getCellColor(cellsIterator, CELL_DATA.foreground, defaultForeground);
       let background = this.getCellColor(cellsIterator, CELL_DATA.background, defaultBackground);
-      const styleSize = this.runtime.layout("GhosttyStyle").size;
       this.runtime.bytes(this.style, styleSize).fill(0);
       this.runtime.setField(this.style, "GhosttyStyle", "size", styleSize);
       this.runtime.call(
@@ -960,30 +964,30 @@ export class GhosttyTerminalCore {
         CELL_DATA.style,
         this.style,
       );
-      const inverse = this.runtime.readField(this.style, "GhosttyStyle", "inverse") !== 0;
-      if (inverse) [foreground, background] = [background, foreground];
-      if (this.runtime.readField(this.style, "GhosttyStyle", "faint") !== 0) {
-        foreground = blend(foreground, background);
-      }
       const graphemeLength = this.getCellU32(cellsIterator, CELL_DATA.graphemesLength);
       let text = "";
       if (graphemeLength > 0) {
         const bufferSize = graphemeLength * 4;
-        const codepoints = this.runtime.alloc(bufferSize);
+        if (bufferSize > this.graphemeCapacity) {
+          const capacity = Math.max(bufferSize, this.graphemeCapacity * 2);
+          const buffer = this.runtime.alloc(capacity);
+          this.runtime.free(this.graphemes, this.graphemeCapacity);
+          this.graphemes = buffer;
+          this.graphemeCapacity = capacity;
+        }
         if (
           this.runtime.call(
             "ghostty_render_state_row_cells_get",
             cellsIterator,
             CELL_DATA.graphemes,
-            codepoints,
+            this.graphemes,
           ) === GHOSTTY_SUCCESS
         ) {
           // Read through a DataView: the byte-array allocator guarantees no
           // 4-byte alignment, which a Uint32Array view would require.
-          const codepointView = this.runtime.view(codepoints, bufferSize);
+          const codepointView = this.runtime.view(this.graphemes, bufferSize);
           text = ghosttyCellText(codepointView, graphemeLength);
         }
-        this.runtime.free(codepoints, bufferSize);
       }
       let wide = 0;
       if (text.length === 0 && cells.at(-1)?.text.length) {
@@ -1004,18 +1008,27 @@ export class GhosttyTerminalCore {
         );
         wide = this.runtime.view(this.scratch + 8, 4).getUint32(0, true);
       }
+      const selected = this.getCellBool(cellsIterator, CELL_DATA.selected);
+      // Read the style after allocation and ABI calls, which can grow WASM memory.
+      const styleView = this.runtime.view(this.style, styleSize);
+      if (styleView.getUint8(styleFields.inverse!.offset) !== 0) {
+        [foreground, background] = [background, foreground];
+      }
+      if (styleView.getUint8(styleFields.faint!.offset) !== 0) {
+        foreground = blend(foreground, background);
+      }
       cells.push({
         text,
         wide,
         foreground,
         background,
-        bold: this.runtime.readField(this.style, "GhosttyStyle", "bold") !== 0,
-        italic: this.runtime.readField(this.style, "GhosttyStyle", "italic") !== 0,
-        invisible: this.runtime.readField(this.style, "GhosttyStyle", "invisible") !== 0,
-        strikethrough: this.runtime.readField(this.style, "GhosttyStyle", "strikethrough") !== 0,
-        overline: this.runtime.readField(this.style, "GhosttyStyle", "overline") !== 0,
-        underline: this.runtime.readField(this.style, "GhosttyStyle", "underline") !== 0,
-        selected: this.getCellBool(cellsIterator, CELL_DATA.selected),
+        bold: styleView.getUint8(styleFields.bold!.offset) !== 0,
+        italic: styleView.getUint8(styleFields.italic!.offset) !== 0,
+        invisible: styleView.getUint8(styleFields.invisible!.offset) !== 0,
+        strikethrough: styleView.getUint8(styleFields.strikethrough!.offset) !== 0,
+        overline: styleView.getUint8(styleFields.overline!.offset) !== 0,
+        underline: styleView.getInt32(styleFields.underline!.offset, true) !== 0,
+        selected,
       });
     }
     while (cells.length < cols) cells.push(this.emptyCell(defaultForeground, defaultBackground));
diff --git a/apps/web/src/terminal/ghostty/runtime.ts b/apps/web/src/terminal/ghostty/runtime.ts
index aca82e7cc3c0..976900fa6d84 100644
--- a/apps/web/src/terminal/ghostty/runtime.ts
+++ b/apps/web/src/terminal/ghostty/runtime.ts
@@ -23,6 +23,7 @@ export class GhosttyRuntime {
   readonly memory: WebAssembly.Memory;
   readonly layouts: TypeLayouts;
   private readonly exports: WebAssembly.Exports;
+  private memoryView: DataView;
   private readonly ptyWriters = new Map<number, (data: string) => void>();
   private nextPtyWriterId = 1;
   private writePtyFunctionIndex = 0;
@@ -34,6 +35,7 @@ export class GhosttyRuntime {
       throw new Error("libghostty-vt did not export WebAssembly memory");
     }
     this.memory = memory;
+    this.memoryView = new DataView(memory.buffer);
     const jsonPointer = this.call("ghostty_type_json");
     const bytes = new Uint8Array(memory.buffer);
     let end = jsonPointer;
@@ -104,7 +106,7 @@ export class GhosttyRuntime {
   }
 
   readPointer(slot: number): number {
-    return new DataView(this.memory.buffer).getUint32(slot, true);
+    return this.currentMemoryView().getUint32(slot, true);
   }
 
   attachPtyWriter(terminal: number, writer: (data: string) => void): number {
@@ -132,27 +134,36 @@ export class GhosttyRuntime {
     return new Uint8Array(this.memory.buffer, pointer, size);
   }
 
+  /** Reuse scalar reads across cells, refreshing after any terminal grows shared WASM memory. */
+  private currentMemoryView(): DataView {
+    if (this.memoryView.buffer !== this.memory.buffer) {
+      this.memoryView = new DataView(this.memory.buffer);
+    }
+    return this.memoryView;
+  }
+
   setField(pointer: number, structName: string, fieldName: string, value: number): void {
     const field = this.layout(structName).fields[fieldName];
     if (!field) throw new Error(`libghostty-vt field is unavailable: ${structName}.${fieldName}`);
-    const view = this.view(pointer + field.offset, field.size);
+    const view = this.currentMemoryView();
+    const offset = pointer + field.offset;
     switch (field.type) {
       case "bool":
       case "u8":
-        view.setUint8(0, value);
+        view.setUint8(offset, value);
         return;
       case "u16":
-        view.setUint16(0, value, true);
+        view.setUint16(offset, value, true);
         return;
       case "i32":
-        view.setInt32(0, value, true);
+        view.setInt32(offset, value, true);
         return;
       case "u32":
       case "enum":
-        view.setUint32(0, value, true);
+        view.setUint32(offset, value, true);
         return;
       case "u64":
-        view.setBigUint64(0, BigInt(value), true);
+        view.setBigUint64(offset, BigInt(value), true);
         return;
       default:
         throw new Error(`Unsupported libghostty-vt field type: ${field.type}`);
@@ -162,20 +173,21 @@ export class GhosttyRuntime {
   readField(pointer: number, structName: string, fieldName: string): number {
     const field = this.layout(structName).fields[fieldName];
     if (!field) throw new Error(`libghostty-vt field is unavailable: ${structName}.${fieldName}`);
-    const view = this.view(pointer + field.offset, field.size);
+    const view = this.currentMemoryView();
+    const offset = pointer + field.offset;
     switch (field.type) {
       case "bool":
       case "u8":
-        return view.getUint8(0);
+        return view.getUint8(offset);
       case "u16":
-        return view.getUint16(0, true);
+        return view.getUint16(offset, true);
       case "i32":
-        return view.getInt32(0, true);
+        return view.getInt32(offset, true);
       case "u32":
       case "enum":
-        return view.getUint32(0, true);
+        return view.getUint32(offset, true);
       case "u64":
-        return Number(view.getBigUint64(0, true));
+        return Number(view.getBigUint64(offset, true));
       default:
         throw new Error(`Unsupported libghostty-vt field type: ${field.type}`);
     }
diff --git a/apps/web/src/terminal/ghostty/surface.test.ts b/apps/web/src/terminal/ghostty/surface.test.ts
index 11b3cc890fdb..ee3240b41b08 100644
--- a/apps/web/src/terminal/ghostty/surface.test.ts
+++ b/apps/web/src/terminal/ghostty/surface.test.ts
@@ -1,6 +1,6 @@
-import { describe, expect, it, vi } from "vite-plus/test";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
 
-import type { GhosttyCell, GhosttyRow } from "./core";
+import { GhosttyTerminalCore, type GhosttyCell, type GhosttyRow } from "./core";
 import {
   DEFAULT_TERMINAL_FONT_FAMILY,
   DEFAULT_TERMINAL_FONT_SIZE,
@@ -23,16 +23,334 @@ import {
   terminalGridCellAt,
   terminalScrollbarGeometry,
   terminalScrollbarOffsetAtPointer,
-  terminalLinkAtColumn,
-  terminalLinkAtPosition,
   terminalLinkAtPositionWithRange,
   terminalContentOriginY,
   terminalFontFamily,
   terminalFontSize,
   terminalWheelArrowData,
   terminalWheelDeltaRows,
+  GhosttyTerminalSurface,
+  type GhosttyTerminalSurfaceOptions,
 } from "./surface";
 
+vi.mock("./vendor/ghostty-vt.wasm?url", async () => ({
+  default: (await import("./vendor/ghostty-vt.wasm?inline")).default,
+}));
+vi.mock("./vendor/ghostty-write-pty.wasm?url&no-inline", async () => ({
+  default: (await import("./vendor/ghostty-write-pty.wasm?inline")).default,
+}));
+
+describe("GhosttyTerminalSurface visibility", () => {
+  const surfaces = new Set<GhosttyTerminalSurface>();
+
+  // Keep the real surface, renderer, and WASM core. Only browser layout and
+  // scheduling are replaced so tests can count work while the terminal is hidden.
+  function createHarness() {
+    vi.useFakeTimers();
+    const frames = new Map<number, FrameRequestCallback>();
+    const resizeCallbacks = new Set<() => void>();
+    const paint = vi.fn((_operation: string, _args: ReadonlyArray<unknown>) => {});
+    let frameId = 0;
+    const requestFrame = vi.fn((callback: FrameRequestCallback) => {
+      frames.set(++frameId, callback);
+      return frameId;
+    });
+
+    class TerminalTestElement extends EventTarget {
+      style: Record<string, string> = {};
+      parentElement: TerminalTestElement | null = null;
+      clientWidth = 168;
+      clientHeight = 104;
+      width = 300;
+      height = 150;
+      value = "";
+      private readonly captures = new Set<number>();
+
+      setAttribute() {}
+      append(...children: TerminalTestElement[]) {
+        for (const child of children) child.parentElement = this;
+      }
+      replaceChildren(...children: TerminalTestElement[]) {
+        this.append(...children);
+      }
+      remove() {
+        this.parentElement = null;
+      }
+      getContext() {
+        return context;
+      }
+      focus() {
+        this.dispatchEvent(new Event("focus"));
+      }
+      setPointerCapture(pointerId: number) {
+        this.captures.add(pointerId);
+      }
+      hasPointerCapture(pointerId: number) {
+        return this.captures.has(pointerId);
+      }
+      releasePointerCapture(pointerId: number) {
+        this.captures.delete(pointerId);
+      }
+      getBoundingClientRect() {
+        return { left: 0, top: 0, right: 168, bottom: 104, width: 168, height: 104 };
+      }
+    }
+
+    const canvas = new TerminalTestElement();
+    const mount = new TerminalTestElement();
+    const context = {
+      canvas,
+      beginPath() {},
+      clip() {},
+      rect() {},
+      resetTransform() {},
+      restore() {},
+      save() {},
+      setTransform() {},
+      fillRect: (...args: number[]) => paint("fillRect", args),
+      strokeRect: (...args: number[]) => paint("strokeRect", args),
+      fillText: (...args: [string, number, number, number?]) => paint("fillText", args),
+      measureText: (text: string) => ({
+        width: text.length * 8,
+        actualBoundingBoxAscent: 9,
+        actualBoundingBoxDescent: 3,
+      }),
+    };
+    vi.stubGlobal("document", {
+      createElement: (tag: string) => (tag === "canvas" ? canvas : new TerminalTestElement()),
+      fonts: Object.assign(new EventTarget(), { load: async () => [], add() {} }),
+    });
+    vi.stubGlobal(
+      "window",
+      Object.assign(new EventTarget(), {
+        devicePixelRatio: 1,
+        requestAnimationFrame: requestFrame,
+        cancelAnimationFrame: (id: number) => frames.delete(id),
+        setTimeout,
+        clearTimeout,
+        setInterval,
+        clearInterval,
+        matchMedia: () => Object.assign(new EventTarget(), { matches: false }),
+      }),
+    );
+    vi.stubGlobal(
+      "ResizeObserver",
+      class {
+        constructor(private readonly callback: () => void) {
+          resizeCallbacks.add(callback);
+        }
+        observe() {}
+        disconnect() {
+          resizeCallbacks.delete(this.callback);
+        }
+      },
+    );
+    const snapshot = vi.spyOn(GhosttyTerminalCore.prototype, "snapshot");
+    const onData = vi.fn<(data: string) => void>();
+
+    return {
+      mount,
+      frames,
+      paint,
+      requestFrame,
+      snapshot,
+      onData,
+      get renderedSnapshot() {
+        const result = snapshot.mock.results.at(-1);
+        if (result?.type !== "return") throw new Error("No terminal snapshot was rendered");
+        return result.value;
+      },
+      flushFrame() {
+        const queued = [...frames.values()];
+        frames.clear();
+        for (const callback of queued) callback(0);
+      },
+      resize() {
+        for (const callback of resizeCallbacks) callback();
+      },
+      pointer(type: string, clientX: number, buttons: number) {
+        canvas.dispatchEvent(
+          Object.assign(new Event(type, { cancelable: true }), {
+            clientX,
+            clientY: 5,
+            pointerId: 1,
+            button: 0,
+            buttons,
+          }),
+        );
+      },
+      async create(options: Partial<GhosttyTerminalSurfaceOptions> = {}) {
+        const surface = await GhosttyTerminalSurface.create(mount as unknown as HTMLElement, {
+          theme: {
+            foreground: { r: 255, g: 255, b: 255 },
+            background: { r: 0, g: 0, b: 0 },
+            cursor: { r: 255, g: 255, b: 255 },
+          },
+          onData,
+          onResize() {},
+          onSelectionChange() {},
+          beforeKey: () => false,
+          onLinkActivate() {},
+          ...options,
+          get visible() {
+            return options.visible ?? true;
+          },
+        });
+        surfaces.add(surface);
+        return surface;
+      },
+    };
+  }
+
+  afterEach(() => {
+    for (const surface of surfaces) surface.dispose();
+    surfaces.clear();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("stops hidden snapshots and paint while preserving live VT replies and the next cursor", async () => {
+    const harness = createHarness();
+    const surface = await harness.create();
+    surface.focus();
+    surface.write("ready\x1b[1 q");
+    harness.flushFrame();
+    vi.advanceTimersByTime(500);
+    harness.flushFrame();
+    surface.write("queued");
+    expect(harness.frames.size).toBe(1);
+    surface.setVisible(false);
+    expect(harness.frames.size).toBe(0);
+    expect(vi.getTimerCount()).toBe(0);
+    harness.snapshot.mockClear();
+    harness.paint.mockClear();
+    harness.requestFrame.mockClear();
+
+    surface.write("\x1b[2J\x1b[H\x1b[3");
+    surface.write("1mhidden");
+    surface.write("界🙂\x1b[0m\x1b[5n\x1b[6n");
+    surface.fit();
+    vi.advanceTimersByTime(2_000);
+    harness.flushFrame();
+
+    expect(harness.onData.mock.calls).toEqual([["\x1b[0n"], ["\x1b[1;11R"]]);
+    expect(harness.snapshot).not.toHaveBeenCalled();
+    expect(harness.paint).not.toHaveBeenCalled();
+    expect(harness.requestFrame).not.toHaveBeenCalled();
+
+    surface.setVisible(true);
+    expect(harness.snapshot).toHaveBeenCalledTimes(1);
+    expect(harness.renderedSnapshot).toMatchObject({ cursorX: 10, cursorY: 0 });
+    expect(harness.renderedSnapshot.rowData[0]?.text).toContain("hidden");
+    expect(harness.paint.mock.calls).toContainEqual(["fillRect", [84, 4, 8, 16]]);
+    expect(harness.frames.size).toBe(0);
+  });
+
+  it("keeps the selection on reveal and applies a hidden selection clear", async () => {
+    const harness = createHarness();
+    const surface = await harness.create();
+    surface.write("hello world");
+    harness.flushFrame();
+    harness.pointer("pointerdown", 5, 1);
+    harness.pointer("pointermove", 37, 1);
+    harness.pointer("pointerup", 37, 0);
+    harness.flushFrame();
+    expect(surface.getSelection()).toBe("hello");
+    const position = surface.getSelectionPosition();
+
+    surface.setVisible(false);
+    harness.snapshot.mockClear();
+    surface.setVisible(true);
+    expect(harness.snapshot).toHaveBeenCalledTimes(1);
+    expect(surface.getSelectionPosition()).toEqual(position);
+    expect(
+      harness.renderedSnapshot.rowData[0]?.cells.slice(0, 5).every((cell) => cell.selected),
+    ).toBe(true);
+
+    surface.setVisible(false);
+    harness.snapshot.mockClear();
+    surface.clearSelection();
+    surface.write("!");
+    expect(harness.snapshot).not.toHaveBeenCalled();
+    surface.setVisible(true);
+    expect(harness.snapshot).toHaveBeenCalledTimes(1);
+    expect(surface.getSelection()).toBe("");
+    expect(surface.getSelectionPosition()).toBeNull();
+    expect(harness.renderedSnapshot.rowData[0]?.cells.some((cell) => cell.selected)).toBe(false);
+  });
+
+  it("stops zero-size mounts and repaints when the same size returns", async () => {
+    const harness = createHarness();
+    const surface = await harness.create();
+    surface.focus();
+    surface.write("visible");
+    harness.flushFrame();
+    harness.snapshot.mockClear();
+    harness.paint.mockClear();
+    harness.mount.clientWidth = 0;
+    surface.write("!");
+    harness.flushFrame();
+    harness.requestFrame.mockClear();
+    for (let index = 0; index < 8; index += 1) surface.write("x");
+    vi.advanceTimersByTime(2_000);
+
+    expect(harness.snapshot).not.toHaveBeenCalled();
+    expect(harness.paint).not.toHaveBeenCalled();
+    expect(harness.requestFrame).not.toHaveBeenCalled();
+    harness.mount.clientWidth = 168;
+    harness.resize();
+    expect(harness.snapshot).toHaveBeenCalledTimes(1);
+    expect(harness.renderedSnapshot.rowData[0]?.text).toContain("visible!xxxxxxxx");
+    expect(harness.paint).toHaveBeenCalled();
+  });
+
+  it.each([false, true])(
+    "uses visibility %s if it changes while WASM initializes",
+    async (visible) => {
+      const harness = createHarness();
+      let markCreated!: () => void;
+      const created = new Promise<void>((resolve) => {
+        markCreated = resolve;
+      });
+      let finishLoading!: () => void;
+      const release = new Promise<void>((resolve) => {
+        finishLoading = resolve;
+      });
+      const create = GhosttyTerminalCore.create;
+      vi.spyOn(GhosttyTerminalCore, "create").mockImplementation(async (...args) => {
+        const core = await create(...args);
+        markCreated();
+        await release;
+        return core;
+      });
+      let currentVisible = !visible;
+      const pending = harness.create({
+        get visible() {
+          return currentVisible;
+        },
+      });
+      await created;
+      currentVisible = visible;
+      harness.paint.mockClear();
+      finishLoading();
+      const surface = await pending;
+
+      expect(harness.snapshot).toHaveBeenCalledTimes(visible ? 1 : 0);
+      if (!visible) expect(harness.paint).not.toHaveBeenCalled();
+      surface.write("ready\x1b[5n");
+      expect(harness.onData).toHaveBeenCalledWith("\x1b[0n");
+      if (!visible) {
+        expect(harness.frames.size).toBe(0);
+        surface.setVisible(true);
+      } else {
+        harness.flushFrame();
+      }
+      expect(harness.renderedSnapshot.rowData[0]?.text).toContain("ready");
+    },
+  );
+});
+
 const cell = (text: string): GhosttyCell => ({
   text,
   wide: 0,
@@ -113,7 +431,7 @@ describe("shouldBlinkTerminalCursor", () => {
   });
 });
 
-describe("terminalLinkAtColumn", () => {
+describe("terminalLinkAtPositionWithRange", () => {
   it("maps terminal cells to UTF-16 offsets after a wide emoji", () => {
     const cells = [
       cell("🙂"),
@@ -130,9 +448,11 @@ describe("terminalLinkAtColumn", () => {
       wrapsToNext: false,
     };
 
-    expect(terminalLinkAtColumn(row, 2)).toBe("https://t3.codes");
-    expect(terminalLinkAtColumn(row, cells.length - 1)).toBe("https://t3.codes");
-    expect(terminalLinkAtColumn(row, 0)).toBeNull();
+    expect(terminalLinkAtPositionWithRange([row], 0, 2)?.text).toBe("https://t3.codes");
+    expect(terminalLinkAtPositionWithRange([row], 0, cells.length - 1)?.text).toBe(
+      "https://t3.codes",
+    );
+    expect(terminalLinkAtPositionWithRange([row], 0, 0)).toBeNull();
     expect(terminalLinkAtPositionWithRange([row], 0, 8)?.range).toEqual({
       start: { x: 2, y: 0 },
       end: { x: cells.length - 1, y: 0 },
@@ -153,10 +473,10 @@ describe("terminalLinkAtColumn", () => {
       row("C:\\repo\\file.ts", false),
     ];
 
-    expect(terminalLinkAtPosition(rows, 0, 8)).toBe("https://example.com/reference");
-    expect(terminalLinkAtPosition(rows, 1, 4)).toBe("https://example.com/reference");
-    expect(terminalLinkAtPosition(rows, 2, 2)).toBe("~/project/file");
-    expect(terminalLinkAtPosition(rows, 3, 4)).toBe("C:\\repo\\file.ts");
+    expect(terminalLinkAtPositionWithRange(rows, 0, 8)?.text).toBe("https://example.com/reference");
+    expect(terminalLinkAtPositionWithRange(rows, 1, 4)?.text).toBe("https://example.com/reference");
+    expect(terminalLinkAtPositionWithRange(rows, 2, 2)?.text).toBe("~/project/file");
+    expect(terminalLinkAtPositionWithRange(rows, 3, 4)?.text).toBe("C:\\repo\\file.ts");
     expect(terminalLinkAtPositionWithRange(rows, 1, 4)).toEqual({
       text: "https://example.com/reference",
       range: {
@@ -175,13 +495,13 @@ describe("terminalLinkAtColumn", () => {
     });
     // The head of the wrapped line scrolled above the viewport.
     const headCut = [row("ple.com/missing", true), row("head", true)];
-    expect(terminalLinkAtPosition(headCut, 0, 4)).toBeNull();
+    expect(terminalLinkAtPositionWithRange(headCut, 0, 4)).toBeNull();
     // The bottom row soft-wraps on below the viewport.
     const tailCut = [row("https://t3.codes", false, true)];
-    expect(terminalLinkAtPosition(tailCut, 0, 8)).toBeNull();
+    expect(terminalLinkAtPositionWithRange(tailCut, 0, 8)).toBeNull();
     // A partial bottom row is provably complete and still resolves.
     const complete = [row("https://t3.codes", false), row("", false)];
-    expect(terminalLinkAtPosition(complete, 0, 8)).toBe("https://t3.codes");
+    expect(terminalLinkAtPositionWithRange(complete, 0, 8)?.text).toBe("https://t3.codes");
     // A wide grapheme earlier in the row must not break truncation detection:
     // the soft-wrap flag decides, not string-length-versus-cell-count.
     const wideFull: GhosttyRow = {
@@ -194,7 +514,7 @@ describe("terminalLinkAtColumn", () => {
       isWrapContinuation: false,
       wrapsToNext: true,
     };
-    expect(terminalLinkAtPosition([wideFull], 0, 8)).toBeNull();
+    expect(terminalLinkAtPositionWithRange([wideFull], 0, 8)).toBeNull();
     // Unwritten trailing cells prove the bottom row is complete.
     const unwrittenTail: GhosttyRow = {
       cells: [
@@ -206,7 +526,7 @@ describe("terminalLinkAtColumn", () => {
       isWrapContinuation: false,
       wrapsToNext: false,
     };
-    expect(terminalLinkAtPosition([unwrittenTail], 0, 8)).toBe("https://t3.codes");
+    expect(terminalLinkAtPositionWithRange([unwrittenTail], 0, 8)?.text).toBe("https://t3.codes");
   });
 });
 
diff --git a/apps/web/src/terminal/ghostty/surface.ts b/apps/web/src/terminal/ghostty/surface.ts
index 84e59e10f509..29aaac6f6abd 100644
--- a/apps/web/src/terminal/ghostty/surface.ts
+++ b/apps/web/src/terminal/ghostty/surface.ts
@@ -244,14 +244,6 @@ function terminalColumnOffset(row: GhosttySnapshot["rowData"][number], column: n
   return offset;
 }
 
-export function terminalLinkAtPosition(
-  rows: GhosttySnapshot["rowData"],
-  rowIndex: number,
-  column: number,
-): string | null {
-  return terminalLinkAtPositionWithRange(rows, rowIndex, column)?.text ?? null;
-}
-
 export interface TerminalLinkWithRange {
   readonly text: string;
   readonly range: GhosttyCellRange;
@@ -325,10 +317,6 @@ export function terminalLinkAtPositionWithRange(
   return null;
 }
 
-export function terminalLinkAtColumn(row: GhosttySnapshot["rowData"][number], column: number) {
-  return terminalLinkAtPosition([row], 0, column);
-}
-
 export function isTerminalCopyShortcut(
   event: Pick<KeyboardEvent, "ctrlKey" | "key" | "metaKey" | "shiftKey">,
   platform = navigator.platform,
@@ -532,6 +520,8 @@ export interface GhosttySelectionPosition {
 export interface GhosttyTerminalSurfaceOptions {
   readonly theme: GhosttyTheme;
   readonly font?: GhosttyTerminalFont;
+  /** Read after font and WASM loading. Hosts can supply a getter for the latest value. */
+  readonly visible?: boolean;
   readonly onData: (data: string) => void;
   readonly onResize: (cols: number, rows: number) => void;
   readonly onSelectionChange: () => void;
@@ -556,6 +546,8 @@ export class GhosttyTerminalSurface {
   private readonly context: CanvasRenderingContext2D;
   private readonly core: GhosttyTerminalCore;
   private readonly options: GhosttyTerminalSurfaceOptions;
+  private visible: boolean;
+  private hasSize = false;
   private metrics: GhosttyCellMetrics;
   private fontFamily: string;
   private requestedFontFamily: string | undefined;
@@ -643,6 +635,7 @@ export class GhosttyTerminalSurface {
     this.mouseAnyEventTracking = core.isMouseAnyEventTracking();
     this.metrics = metrics;
     this.options = options;
+    this.visible = options.visible ?? true;
     this.theme = options.theme;
     this.fontFamily = fontFamily;
     this.requestedFontFamily = options.font?.family;
@@ -725,10 +718,24 @@ export class GhosttyTerminalSurface {
       options,
     );
     surface.fit();
-    surface.requestRender();
     return surface;
   }
 
+  /** Pause canvas work without interrupting output parsing or terminal replies. */
+  setVisible(visible: boolean): void {
+    if (this.disposed || this.visible === visible) return;
+    this.visible = visible;
+    this.cursorOn = true;
+    this.forceFullRender = true;
+    this.scrollbarDirty = true;
+    if (!visible) {
+      this.cancelRender();
+      this.setSelectionAutoscroll(0);
+      return;
+    }
+    this.fit();
+  }
+
   write(data: string): void {
     if (this.disposed) return;
     this.core.write(data);
@@ -824,10 +831,16 @@ export class GhosttyTerminalSurface {
   };
 
   fit(): boolean {
-    if (this.disposed) return false;
+    if (this.disposed || !this.visible) return false;
     const width = this.mount.clientWidth;
     const height = this.mount.clientHeight;
-    if (width <= 0 || height <= 0) return false;
+    if (width <= 0 || height <= 0) {
+      this.hasSize = false;
+      this.forceFullRender = true;
+      this.cancelRender();
+      return false;
+    }
+    this.hasSize = true;
     const ratio = window.devicePixelRatio || 1;
     const pixelWidth = Math.max(1, Math.round(width * ratio));
     const pixelHeight = Math.max(1, Math.round(height * ratio));
@@ -864,7 +877,7 @@ export class GhosttyTerminalSurface {
     // Rendering synchronously keeps the repaint inside the same frame as the
     // layout change: ResizeObserver fires before paint, so the browser never
     // composites the old backing store stretched into the new element box.
-    if (shouldRender) this.renderFrame();
+    if (shouldRender || this.forceFullRender) this.renderFrame();
     return true;
   }
 
@@ -883,6 +896,7 @@ export class GhosttyTerminalSurface {
   }
 
   focus(): void {
+    if (this.disposed || !this.visible) return;
     this.input.focus({ preventScroll: true });
   }
 
@@ -982,8 +996,7 @@ export class GhosttyTerminalSurface {
       // the surface unmounts inside the debounce window.
       this.options.onResize(this.cols, this.rows);
     }
-    if (this.frame !== 0) window.cancelAnimationFrame(this.frame);
-    if (this.cursorTimer !== null) window.clearTimeout(this.cursorTimer);
+    this.cancelRender();
     if (this.compositionSuppressionTimer !== null) {
       window.clearTimeout(this.compositionSuppressionTimer);
     }
@@ -1676,19 +1689,39 @@ export class GhosttyTerminalSurface {
   }
 
   private requestRender(): void {
-    if (this.disposed || this.frame !== 0) return;
+    if (this.disposed || !this.visible || !this.hasSize || this.frame !== 0) return;
     this.frame = window.requestAnimationFrame(() => {
       this.frame = 0;
       this.renderFrame();
     });
   }
 
+  private cancelRender(): void {
+    if (this.frame !== 0) {
+      window.cancelAnimationFrame(this.frame);
+      this.frame = 0;
+    }
+    if (this.cursorTimer !== null) {
+      window.clearTimeout(this.cursorTimer);
+      this.cursorTimer = null;
+    }
+  }
+
   private renderFrame(): void {
-    if (this.disposed) return;
+    if (this.disposed || !this.visible) return;
     if (this.frame !== 0) {
       window.cancelAnimationFrame(this.frame);
       this.frame = 0;
     }
+    // Hidden thread drawers stay mounted so switching back is instant, but a
+    // display:none canvas has nothing to show. Ghostty keeps parsing; the
+    // ResizeObserver refits and repaints in full once the mount has a size.
+    if (this.mount.clientWidth === 0 || this.mount.clientHeight === 0) {
+      this.hasSize = false;
+      this.forceFullRender = true;
+      this.cancelRender();
+      return;
+    }
     this.snapshot = this.core.snapshot();
     // A cursor that is not blinking right now must be drawn, never caught in an
     // off phase left behind by a blink that has since been turned off.
@@ -1754,7 +1787,7 @@ export class GhosttyTerminalSurface {
 
   private blinkEnabled(): boolean {
     const snapshot = this.snapshot;
-    if (!snapshot) return false;
+    if (!snapshot || !this.visible || !this.hasSize) return false;
     return shouldBlinkTerminalCursor({
       focused: this.focused,
       cursorBlinking: snapshot.cursorBlinking,
diff --git a/apps/web/src/themePalette.test.ts b/apps/web/src/themePalette.test.ts
index a76885a862ee..e1d9bfb74cab 100644
--- a/apps/web/src/themePalette.test.ts
+++ b/apps/web/src/themePalette.test.ts
@@ -34,7 +34,6 @@ import {
   OCEAN_THEME,
   updateCustomTheme,
   CUSTOM_THEMES_STORAGE_KEY,
-  createManagedThemeColors,
   createVividThemeColors,
   getDefaultThemeColors,
   themeColorToHex,
@@ -91,50 +90,6 @@ describe("theme files", () => {
     }
   });
 
-  it("derives a readable palette from extreme simple-editor colors", () => {
-    const light = createManagedThemeColors("light", "#111827", "#ffff00");
-    const dark = createManagedThemeColors("dark", "#ffffff", "#ffff00");
-    const darkDefaults = getDefaultThemeColors("dark");
-
-    expect(asHex(light.canvas)).not.toBe("#111827");
-    expect(asHex(dark.canvas)).not.toBe("#ffffff");
-    expect(contrastRatio(light.accent, light.canvas)).toBeGreaterThanOrEqual(4.5);
-    expect(contrastRatio(dark.accent, dark.canvas)).toBeGreaterThanOrEqual(4.5);
-    expect(contrastRatio(light.textMuted, light.canvas)).toBeGreaterThanOrEqual(4.5);
-    expect(contrastRatio(dark.textMuted, dark.canvas)).toBeGreaterThanOrEqual(4.5);
-    expect(contrastRatio(light.textMuted, light.canvas)).toBeLessThan(5.5);
-    expect(contrastRatio(dark.textMuted, dark.canvas)).toBeLessThan(5.5);
-    expect(contrastRatio(light.textMuted, light.canvas)).toBeCloseTo(4.705, 1);
-    expect(contrastRatio(dark.textMuted, dark.canvas)).toBeCloseTo(5.082, 1);
-    expect(light.secondaryLabel).toBe(light.textMuted);
-    expect(dark.secondaryLabel).toBe(dark.textMuted);
-    expect(contrastRatio(light.accentForeground, light.accent)).toBeGreaterThanOrEqual(4.5);
-    expect(contrastRatio(dark.accentForeground, dark.accent)).toBeGreaterThanOrEqual(4.5);
-    // Status colors fall back to T3 Code's standard red and amber rather than
-    // the flagship palette's, so no generated theme inherits a brand tint.
-    const channels = (value: string) =>
-      [1, 3, 5].map((index) => Number.parseInt(asHex(value).slice(index, index + 2), 16)) as [
-        number,
-        number,
-        number,
-      ];
-    for (const colors of [light, dark]) {
-      const [errorRed, errorGreen, errorBlue] = channels(colors.error);
-      // Red leads by a wide margin; the old default was a pink whose blue sat
-      // close behind its red.
-      expect(errorRed).toBeGreaterThan(errorGreen * 2);
-      expect(errorRed).toBeGreaterThan(errorBlue * 2);
-      expect(contrastRatio(colors.error, "#ffffff")).toBeGreaterThanOrEqual(2.5);
-      expect(contrastRatio(colors.errorForeground, colors.errorSurface)).toBeGreaterThanOrEqual(
-        4.5,
-      );
-      const [warnRed, warnGreen, warnBlue] = channels(colors.warning);
-      expect(warnRed).toBeGreaterThan(warnBlue);
-      expect(warnGreen).toBeGreaterThan(warnBlue);
-    }
-    expect(asHex(dark.error)).not.toBe(asHex(darkDefaults.error));
-  });
-
   it("keeps stock dark controls in the neutral-black surface hierarchy", () => {
     expectThemeColors(getStandardThemeColors("dark"), {
       canvas: "#0a0a0a",
@@ -158,6 +113,12 @@ describe("theme files", () => {
       ["light", "#111827", "#8ab4f8"],
       ["dark", "#f5ecf5", "#a84370"],
     ];
+    const channels = (value: string) =>
+      [1, 3, 5].map((index) => Number.parseInt(asHex(value).slice(index, index + 2), 16)) as [
+        number,
+        number,
+        number,
+      ];
     for (const [appearance, canvas, accent] of seeds) {
       const colors = createVividThemeColors(appearance, canvas, accent);
       // Exact seeds are honored.
@@ -193,6 +154,17 @@ describe("theme files", () => {
       expect(colors.messageAction).not.toBe(colors.accent);
       // Update family follows the theme, not the default palette.
       expect(asHex(colors.update)).toBe(accent);
+      // Semantic statuses stay red and amber instead of inheriting a brand tint.
+      const [errorRed, errorGreen, errorBlue] = channels(colors.error);
+      expect(errorRed).toBeGreaterThan(errorGreen * 2);
+      expect(errorRed).toBeGreaterThan(errorBlue * 2);
+      expect(contrastRatio(colors.error, "#ffffff")).toBeGreaterThanOrEqual(2.5);
+      expect(contrastRatio(colors.errorForeground, colors.errorSurface)).toBeGreaterThanOrEqual(
+        4.5,
+      );
+      const [warnRed, warnGreen, warnBlue] = channels(colors.warning);
+      expect(warnRed).toBeGreaterThan(warnBlue);
+      expect(warnGreen).toBeGreaterThan(warnBlue);
     }
   });
 
@@ -202,8 +174,8 @@ describe("theme files", () => {
     const inverted = [
       createVividThemeColors("light", "#111827", "#8ab4f8"),
       createVividThemeColors("dark", "#f5ecf5", "#a84370"),
-      createManagedThemeColors("light", "#0d1117", "#69b1ff", { exactSeeds: true }),
-      createManagedThemeColors("dark", "#fdfdfd", "#c2571b", { exactSeeds: true }),
+      createVividThemeColors("light", "#0d1117", "#69b1ff"),
+      createVividThemeColors("dark", "#fdfdfd", "#c2571b"),
     ];
     for (const colors of inverted) {
       expect(contrastRatio(colors.errorForeground, colors.errorSurface)).toBeGreaterThanOrEqual(
diff --git a/apps/web/src/themePalette.ts b/apps/web/src/themePalette.ts
index f67eb943e3fb..f4b5c83df395 100644
--- a/apps/web/src/themePalette.ts
+++ b/apps/web/src/themePalette.ts
@@ -475,12 +475,6 @@ type ThemeRgbColor = {
   b: number;
 };
 
-type ThemeHslColor = {
-  h: number;
-  s: number;
-  l: number;
-};
-
 type ThemeOklch = { L: number; C: number; h: number };
 type ParsedThemeColor = { color: ThemeOklch; alpha: number };
 
@@ -601,48 +595,6 @@ function canonicalizeThemeDefinition(theme: ThemeDefinition): ThemeDefinition {
   };
 }
 
-function themeRgbToHsl(color: ThemeRgbColor): ThemeHslColor {
-  const red = color.r / 255;
-  const green = color.g / 255;
-  const blue = color.b / 255;
-  const max = Math.max(red, green, blue);
-  const min = Math.min(red, green, blue);
-  const delta = max - min;
-  const lightness = (max + min) / 2;
-
-  if (delta === 0) return { h: 0, s: 0, l: lightness };
-
-  const saturation = delta / (1 - Math.abs(2 * lightness - 1));
-  let hue = 0;
-  if (max === red) hue = ((green - blue) / delta) % 6;
-  else if (max === green) hue = (blue - red) / delta + 2;
-  else hue = (red - green) / delta + 4;
-
-  return { h: (hue * 60 + 360) % 360, s: saturation, l: lightness };
-}
-
-function themeHslToRgb(color: ThemeHslColor): ThemeRgbColor {
-  const hue = ((color.h % 360) + 360) % 360;
-  const chroma = (1 - Math.abs(2 * color.l - 1)) * color.s;
-  const hueSector = hue / 60;
-  const secondary = chroma * (1 - Math.abs((hueSector % 2) - 1));
-  const match = color.l - chroma / 2;
-  const [red, green, blue] =
-    hueSector < 1
-      ? [chroma, secondary, 0]
-      : hueSector < 2
-        ? [secondary, chroma, 0]
-        : hueSector < 3
-          ? [0, chroma, secondary]
-          : hueSector < 4
-            ? [0, secondary, chroma]
-            : hueSector < 5
-              ? [secondary, 0, chroma]
-              : [chroma, 0, secondary];
-
-  return { r: (red + match) * 255, g: (green + match) * 255, b: (blue + match) * 255 };
-}
-
 function mixThemeRgbColors(
   base: ThemeRgbColor,
   overlay: ThemeRgbColor,
@@ -1046,205 +998,6 @@ function standardMutedThemeText(
   return readableThemeText(background, foreground, 1, target);
 }
 
-function managedThemeBackground(value: string, appearance: ThemeAppearance): ThemeRgbColor {
-  const selected = parseThemeRgbColor(
-    value,
-    appearance === "dark" ? { r: 24, g: 15, b: 27 } : { r: 250, g: 245, b: 250 },
-  );
-  const hsl = themeRgbToHsl(selected);
-  return themeHslToRgb({
-    h: hsl.h,
-    // A background tint should support the selected mode, not turn the whole
-    // app into a high-saturation surface.
-    s: Math.min(hsl.s, appearance === "dark" ? 0.3 : 0.2),
-    l:
-      appearance === "dark"
-        ? Math.min(0.13, Math.max(0.07, hsl.l))
-        : Math.min(0.985, Math.max(0.94, hsl.l)),
-  });
-}
-
-function managedThemeAccent(
-  value: string,
-  appearance: ThemeAppearance,
-  background: ThemeRgbColor,
-): ThemeRgbColor {
-  const selected = parseThemeRgbColor(value, { r: 168, g: 67, b: 112 });
-  const hsl = themeRgbToHsl(selected);
-  const preferredLightness =
-    appearance === "dark"
-      ? Math.min(0.72, Math.max(0.42, hsl.l))
-      : Math.min(0.58, Math.max(0.35, hsl.l));
-  const lightnessRange: readonly [number, number] =
-    appearance === "dark" ? [0.42, 0.82] : [0.22, 0.58];
-  const saturation = Math.min(hsl.s, 0.82);
-  const candidates = Array.from({ length: 61 }, (_, index) => {
-    const lightness =
-      lightnessRange[0] + ((lightnessRange[1] - lightnessRange[0]) * index) / (61 - 1);
-    const color = themeHslToRgb({ h: hsl.h, s: saturation, l: lightness });
-    return { color, lightness, contrast: themeContrastRatio(color, background) };
-  });
-  // Leave a little room for browser color conversion at render time.
-  const readableCandidates = candidates.filter((candidate) => candidate.contrast >= 4.7);
-  const pool = readableCandidates.length > 0 ? readableCandidates : candidates;
-
-  return pool.reduce((best, candidate) => {
-    const distance = Math.abs(candidate.lightness - preferredLightness);
-    const bestDistance = Math.abs(best.lightness - preferredLightness);
-    return distance < bestDistance ||
-      (distance === bestDistance && candidate.contrast > best.contrast)
-      ? candidate
-      : best;
-  }).color;
-}
-
-/**
- * Creates the guided palette used by the basic theme editor. The two user
- * colors control the mood, while dependent roles are generated together so
- * text, surfaces, message actions, code, and terminal UI stay coherent.
- */
-export function createManagedThemeColors(
-  appearance: ThemeAppearance,
-  backgroundValue: string,
-  accentValue: string,
-  options?: {
-    /** Use the seeds exactly as given instead of nudging them into the
-     * readability envelope. Derived foregrounds still adapt for contrast. */
-    exactSeeds?: boolean;
-  },
-): ThemeColors {
-  const defaults = getDefaultThemeColors(appearance);
-  const canvas = options?.exactSeeds
-    ? parseThemeRgbColor(
-        backgroundValue,
-        appearance === "dark" ? { r: 24, g: 15, b: 27 } : { r: 250, g: 245, b: 250 },
-      )
-    : managedThemeBackground(backgroundValue, appearance);
-  const accent = options?.exactSeeds
-    ? parseThemeRgbColor(accentValue, { r: 168, g: 67, b: 112 })
-    : managedThemeAccent(accentValue, appearance, canvas);
-  const text = readableThemeForeground(canvas);
-  const textMuted = standardMutedThemeText(canvas, text);
-  // The top bar is part of the main panel, not a separate chrome layer: it
-  // shares the canvas, and its controls sit on the panel's own surfaces.
-  const chrome = canvas;
-  const sidebar = mixThemeRgbColors(canvas, accent, 0.08);
-  const surfaceRaised = mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.12 : 0.035);
-  const surfaceOverlay = mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.18 : 0.06);
-  const secondary = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.2 : 0.08);
-  const muted = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.13 : 0.06);
-  const mutedForeground = readableThemeText(muted, text, 1, 4.6);
-  const placeholder = readableThemeText(surfaceRaised, text, 1, 4.6);
-  const accentSurface = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.3 : 0.14);
-  const messageSurface = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.36 : 0.18);
-  const toolbarControl = mixThemeRgbColors(chrome, accent, appearance === "dark" ? 0.2 : 0.08);
-  const toolbarBorder = mixThemeRgbColors(chrome, accent, appearance === "dark" ? 0.35 : 0.14);
-  const accentForeground = readableThemeForeground(accent);
-  // Code and terminal are large surfaces: they keep the canvas hue instead of
-  // drifting toward the foreground grey. Code sits just above the canvas —
-  // a whisper of the text tint — and the terminal sits on the canvas itself.
-  const codeBackground = mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.06 : 0.025);
-  const terminalBackground = canvas;
-  const messageActionHover = mixThemeRgbColors(
-    accent,
-    accentForeground === THEME_LIGHT_FOREGROUND || accentForeground === THEME_WHITE_FOREGROUND
-      ? THEME_BLACK_FOREGROUND
-      : THEME_WHITE_FOREGROUND,
-    0.12,
-  );
-
-  // The update family follows the accent instead of inheriting the default
-  // palette's brand color, so generated themes carry their own identity in
-  // update pills and banners. Error and warning stay semantic defaults.
-  const updateSurface = mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.32 : 0.16);
-  const updateForeground = mixThemeRgbColors(
-    accent,
-    appearance === "dark" ? THEME_WHITE_FOREGROUND : THEME_BLACK_FOREGROUND,
-    0.35,
-  );
-
-  return {
-    ...defaults,
-    ...standardStatusColors(canvas),
-    update: themeRgbToThemeColor(accent),
-    updateForeground: themeRgbToThemeColor(updateForeground),
-    updateSurface: themeRgbToThemeColor(updateSurface),
-    canvas: themeRgbToThemeColor(canvas),
-    chrome: themeRgbToThemeColor(chrome),
-    toolbar: themeRgbToThemeColor(chrome),
-    toolbarForeground: themeRgbToThemeColor(text),
-    toolbarBorder: themeRgbToThemeColor(toolbarBorder),
-    toolbarControl: themeRgbToThemeColor(toolbarControl),
-    toolbarControlForeground: themeRgbToThemeColor(text),
-    toolbarControlHover: themeRgbToThemeColor(accentSurface),
-    surface: themeRgbToThemeColor(canvas),
-    surfaceRaised: themeRgbToThemeColor(surfaceRaised),
-    surfaceOverlay: themeRgbToThemeColor(surfaceOverlay),
-    text: themeRgbToThemeColor(text),
-    textMuted: themeRgbToThemeColor(textMuted),
-    // Borders blend through the accent before lightening so control chrome
-    // carries the theme hue like the hand-tuned palettes (#5c345b, #e0d3e1)
-    // instead of flattening to grey.
-    border: themeRgbToThemeColor(
-      mixThemeRgbColors(
-        mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.22 : 0.1),
-        text,
-        0.1,
-      ),
-    ),
-    input: themeRgbToThemeColor(
-      mixThemeRgbColors(
-        mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.3 : 0.14),
-        text,
-        appearance === "dark" ? 0.14 : 0.13,
-      ),
-    ),
-    focus: themeRgbToThemeColor(accent),
-    accent: themeRgbToThemeColor(accent),
-    accentForeground: themeRgbToThemeColor(accentForeground),
-    secondary: themeRgbToThemeColor(secondary),
-    secondaryForeground: themeRgbToThemeColor(readableThemeForeground(secondary)),
-    muted: themeRgbToThemeColor(muted),
-    mutedForeground: themeRgbToThemeColor(mutedForeground),
-    placeholder: themeRgbToThemeColor(placeholder),
-    secondaryLabel: themeRgbToThemeColor(textMuted),
-    iconMuted: themeRgbToThemeColor(textMuted),
-    accentSurface: themeRgbToThemeColor(accentSurface),
-    accentSurfaceForeground: themeRgbToThemeColor(readableThemeForeground(accentSurface)),
-    messageSurface: themeRgbToThemeColor(messageSurface),
-    messageForeground: themeRgbToThemeColor(readableThemeForeground(messageSurface)),
-    messageAction: themeRgbToThemeColor(accent),
-    messageActionForeground: themeRgbToThemeColor(accentForeground),
-    messageActionHover: themeRgbToThemeColor(messageActionHover),
-    codeBackground: themeRgbToThemeColor(codeBackground),
-    codeForeground: themeRgbToThemeColor(readableThemeForeground(codeBackground)),
-    sidebar: themeRgbToThemeColor(sidebar),
-    sidebarForeground: themeRgbToThemeColor(readableThemeForeground(sidebar)),
-    sidebarMutedForeground: themeRgbToThemeColor(standardMutedThemeText(sidebar, text)),
-    sidebarControlSurface: themeRgbToThemeColor(
-      mixThemeRgbColors(sidebar, text, appearance === "dark" ? 0.16 : 0.08),
-    ),
-    sidebarRowHover: themeRgbToThemeColor(mixThemeRgbColors(sidebar, accent, 0.12)),
-    sidebarRowActive: themeRgbToThemeColor(mixThemeRgbColors(sidebar, accent, 0.2)),
-    sidebarRowSelected: themeRgbToThemeColor(mixThemeRgbColors(sidebar, accent, 0.24)),
-    sidebarBorder: themeRgbToThemeColor(
-      mixThemeRgbColors(sidebar, text, appearance === "dark" ? 0.35 : 0.12),
-    ),
-    terminalBackground: themeRgbToThemeColor(terminalBackground),
-    terminalForeground: themeRgbToThemeColor(readableThemeForeground(terminalBackground)),
-    terminalCursor: themeRgbToThemeColor(accent),
-    terminalSelection: themeRgbToThemeColor(
-      mixThemeRgbColors(canvas, accent, appearance === "dark" ? 0.35 : 0.18),
-    ),
-    terminalScrollbar: themeRgbToThemeColor(
-      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.42 : 0.22),
-    ),
-    terminalScrollbarHover: themeRgbToThemeColor(
-      mixThemeRgbColors(canvas, text, appearance === "dark" ? 0.55 : 0.32),
-    ),
-  };
-}
-
 /** Theme-file defaults follow the flagship palette for the requested mode. */
 export function getDefaultThemeColors(appearance: ThemeAppearance): ThemeColors {
   return appearance === "dark" ? T3_CHAT_THEME.variants!.dark! : T3_CHAT_THEME.colors;
diff --git a/apps/web/src/threadSelectionStore.test.ts b/apps/web/src/threadSelectionStore.test.ts
index 3bd97b97d40a..e73f4d96864c 100644
--- a/apps/web/src/threadSelectionStore.test.ts
+++ b/apps/web/src/threadSelectionStore.test.ts
@@ -1,7 +1,10 @@
 import { ThreadId } from "@t3tools/contracts";
 import { beforeEach, describe, expect, it } from "vite-plus/test";
 
-import { useThreadSelectionStore } from "./threadSelectionStore";
+import {
+  getThreadKeysToDeselectAfterDelete,
+  useThreadSelectionStore,
+} from "./threadSelectionStore";
 
 const THREAD_A = ThreadId.make("thread-a");
 const THREAD_B = ThreadId.make("thread-b");
@@ -16,6 +19,59 @@ describe("threadSelectionStore", () => {
     useThreadSelectionStore.getState().clearSelection();
   });
 
+  describe("bulk deletion cleanup", () => {
+    it("clears missing selection rows and completed deletions while retaining a failed thread", () => {
+      const store = useThreadSelectionStore.getState();
+      store.toggleThread(THREAD_A);
+      store.toggleThread(THREAD_B);
+      store.toggleThread(THREAD_C);
+      const selected = [...useThreadSelectionStore.getState().selectedThreadKeys];
+      // A deleted successfully but its shell has not refreshed; B failed;
+      // C was deleted elsewhere and never entered this client's delete loop.
+      const existingThreads = new Set([THREAD_A, THREAD_B]);
+      store.removeFromSelection(
+        getThreadKeysToDeselectAfterDelete(selected, new Set([THREAD_A]), (key) =>
+          existingThreads.has(ThreadId.make(key)),
+        ),
+      );
+
+      expect([...useThreadSelectionStore.getState().selectedThreadKeys]).toEqual([THREAD_B]);
+      expect(useThreadSelectionStore.getState().anchorThreadKey).toBeNull();
+    });
+
+    it("exits selection mode when the last selected thread disappeared elsewhere", () => {
+      const store = useThreadSelectionStore.getState();
+      store.toggleThread(THREAD_A);
+      store.removeFromSelection(
+        getThreadKeysToDeselectAfterDelete([THREAD_A], new Set(), () => false),
+      );
+
+      expect(useThreadSelectionStore.getState().hasSelection()).toBe(false);
+      expect(useThreadSelectionStore.getState().anchorThreadKey).toBeNull();
+    });
+
+    it("keeps unprocessed and hidden live threads and selections added while deletion was pending", () => {
+      const store = useThreadSelectionStore.getState();
+      store.toggleThread(THREAD_A);
+      store.toggleThread(THREAD_B);
+      store.toggleThread(THREAD_C);
+      const selected = [...useThreadSelectionStore.getState().selectedThreadKeys];
+      store.toggleThread(THREAD_D);
+      // Only A completed before interruption. B is unprocessed; C still
+      // has a shell even though its row is outside the rendered page.
+      store.removeFromSelection(
+        getThreadKeysToDeselectAfterDelete(selected, new Set([THREAD_A]), () => true),
+      );
+
+      expect([...useThreadSelectionStore.getState().selectedThreadKeys]).toEqual([
+        THREAD_B,
+        THREAD_C,
+        THREAD_D,
+      ]);
+      expect(useThreadSelectionStore.getState().anchorThreadKey).toBe(THREAD_D);
+    });
+  });
+
   describe("toggleThread", () => {
     it("adds a thread to empty selection", () => {
       useThreadSelectionStore.getState().toggleThread(THREAD_A);
diff --git a/apps/web/src/threadSelectionStore.ts b/apps/web/src/threadSelectionStore.ts
index 2b4022a68fb6..fd7f9366eba8 100644
--- a/apps/web/src/threadSelectionStore.ts
+++ b/apps/web/src/threadSelectionStore.ts
@@ -34,6 +34,15 @@ interface ThreadSelectionStore extends ThreadSelectionState {
 
 const EMPTY_SET = new Set<string>();
 
+/** Clear completed deletions and missing threads, retaining failed or unprocessed threads. */
+export function getThreadKeysToDeselectAfterDelete(
+  selectedThreadKeys: readonly string[],
+  deletedThreadKeys: ReadonlySet<string>,
+  hasThread: (threadKey: string) => boolean,
+): string[] {
+  return selectedThreadKeys.filter((key) => deletedThreadKeys.has(key) || !hasThread(key));
+}
+
 export const useThreadSelectionStore = create<ThreadSelectionStore>((set, get) => ({
   selectedThreadKeys: EMPTY_SET,
   anchorThreadKey: null,
diff --git a/apps/web/src/uiStateStore.test.ts b/apps/web/src/uiStateStore.test.ts
index 304502873539..1a95acbcfbf7 100644
--- a/apps/web/src/uiStateStore.test.ts
+++ b/apps/web/src/uiStateStore.test.ts
@@ -13,6 +13,7 @@ import {
   resolveProjectExpanded,
   setDefaultAdvertisedEndpointKey,
   setProjectExpanded,
+  setSidebarProjectScopeKey,
   setThreadChangedFilesExpanded,
   type UiState,
 } from "./uiStateStore";
@@ -21,6 +22,7 @@ function makeUiState(overrides: Partial<UiState> = {}): UiState {
   return {
     projectExpandedById: {},
     projectOrder: [],
+    sidebarProjectScopeKey: null,
     threadLastVisitedAtById: {},
     threadChangedFilesExpandedById: {},
     defaultAdvertisedEndpointKey: null,
@@ -144,6 +146,15 @@ describe("uiStateStore pure functions", () => {
       defaultAdvertisedEndpointKey: null,
     });
   });
+
+  it("stores the sidebar project scope and resets it to all projects", () => {
+    const scoped = setSidebarProjectScopeKey(makeUiState(), "github.com/pingdotgg/t3code");
+
+    expect(scoped.sidebarProjectScopeKey).toBe("github.com/pingdotgg/t3code");
+    expect(setSidebarProjectScopeKey(scoped, "github.com/pingdotgg/t3code")).toBe(scoped);
+    expect(setSidebarProjectScopeKey(scoped, null).sidebarProjectScopeKey).toBeNull();
+    expect(setSidebarProjectScopeKey(scoped, "").sidebarProjectScopeKey).toBeNull();
+  });
 });
 
 describe("parsePersistedState", () => {
@@ -159,7 +170,7 @@ describe("parsePersistedState", () => {
         invalid: "not-a-date",
       },
       defaultAdvertisedEndpointKey: "desktop-core:lan:http",
-      threadChangedFilesExpansionVersion: 1,
+      threadChangedFilesExpansionVersion: 2,
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
           "turn-1": false,
@@ -177,6 +188,7 @@ describe("parsePersistedState", () => {
         "environment:thread-1": "2026-02-25T12:35:00.000Z",
       },
       defaultAdvertisedEndpointKey: "desktop-core:lan:http",
+      sidebarProjectScopeKey: null,
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
           "turn-1": false,
@@ -186,8 +198,9 @@ describe("parsePersistedState", () => {
     });
   });
 
-  it("ignores changed-file expansion values saved with legacy folder semantics", () => {
+  it.each([undefined, 1])("ignores changed-file expansion version %s", (version) => {
     const parsed = parsePersistedState({
+      ...(version === undefined ? {} : { threadChangedFilesExpansionVersion: version }),
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
           "turn-1": false,
@@ -296,7 +309,8 @@ describe("uiStateStore persistence", () => {
         "environment:thread-1": "2026-02-25T12:35:00.000Z",
       },
       defaultAdvertisedEndpointKey: "desktop-core:lan:http",
-      threadChangedFilesExpansionVersion: 1,
+      sidebarProjectScopeKey: null,
+      threadChangedFilesExpansionVersion: 2,
       threadChangedFilesExpandedById: {
         "environment:thread-1": {
           "turn-1": false,
@@ -309,6 +323,18 @@ describe("uiStateStore persistence", () => {
     });
   });
 
+  it("restores the sidebar project scope across reloads", () => {
+    persistState(makeUiState({ sidebarProjectScopeKey: "github.com/pingdotgg/t3code" }));
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+
+    expect(parsePersistedState(persisted).sidebarProjectScopeKey).toBe(
+      "github.com/pingdotgg/t3code",
+    );
+  });
+
   it("drops the temporary expanded-only migration fallback when rewriting state", () => {
     const migrated = parsePersistedState({
       expandedProjectCwds: ["/repo/a"],
diff --git a/apps/web/src/uiStateStore.ts b/apps/web/src/uiStateStore.ts
index 5d744d540a5a..b14ce917c861 100644
--- a/apps/web/src/uiStateStore.ts
+++ b/apps/web/src/uiStateStore.ts
@@ -3,7 +3,8 @@ import { create } from "zustand";
 import { normalizeProjectPathForComparison } from "./lib/projectPaths";
 
 export const PERSISTED_STATE_KEY = "t3code:ui-state:v1";
-const THREAD_CHANGED_FILES_EXPANSION_VERSION = 1;
+// Version 1 stored card visibility, not folder expansion.
+const THREAD_CHANGED_FILES_EXPANSION_VERSION = 2;
 const LEGACY_PERSISTED_STATE_KEYS = [
   "t3code:renderer-state:v8",
   "t3code:renderer-state:v7",
@@ -25,13 +26,18 @@ export interface PersistedUiState {
   expandedProjectCwds?: string[];
   projectOrderCwds?: string[];
   defaultAdvertisedEndpointKey?: string | null;
-  threadChangedFilesExpansionVersion?: typeof THREAD_CHANGED_FILES_EXPANSION_VERSION;
+  sidebarProjectScopeKey?: string | null;
+  threadChangedFilesExpansionVersion?: number;
   threadChangedFilesExpandedById?: Record<string, Record<string, boolean>>;
 }
 
 export interface UiProjectState {
   projectExpandedById: Record<string, boolean>;
   projectOrder: string[];
+  // Logical project key the sidebar list is scoped to, or null for "all
+  // projects". Lives here so routes that unmount the sidebar (Settings)
+  // cannot reset the filter.
+  sidebarProjectScopeKey: string | null;
 }
 
 export interface UiThreadState {
@@ -48,6 +54,7 @@ export interface UiState extends UiProjectState, UiThreadState, UiEndpointState
 const initialState: UiState = {
   projectExpandedById: {},
   projectOrder: [],
+  sidebarProjectScopeKey: null,
   threadLastVisitedAtById: {},
   threadChangedFilesExpandedById: {},
   defaultAdvertisedEndpointKey: null,
@@ -83,6 +90,10 @@ function sanitizeBooleanRecord(value: unknown): Record<string, boolean> {
   );
 }
 
+function sanitizeOptionalKey(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
 function sanitizeTimestampRecord(value: unknown): Record<string, string> {
   if (!value || typeof value !== "object") {
     return {};
@@ -130,11 +141,8 @@ export function parsePersistedState(parsed: PersistedUiState): UiState {
       parsed.threadChangedFilesExpansionVersion === THREAD_CHANGED_FILES_EXPANSION_VERSION
         ? sanitizePersistedThreadChangedFilesExpanded(parsed.threadChangedFilesExpandedById)
         : {},
-    defaultAdvertisedEndpointKey:
-      typeof parsed.defaultAdvertisedEndpointKey === "string" &&
-      parsed.defaultAdvertisedEndpointKey.length > 0
-        ? parsed.defaultAdvertisedEndpointKey
-        : null,
+    defaultAdvertisedEndpointKey: sanitizeOptionalKey(parsed.defaultAdvertisedEndpointKey),
+    sidebarProjectScopeKey: sanitizeOptionalKey(parsed.sidebarProjectScopeKey),
   };
 }
 
@@ -205,6 +213,7 @@ export function persistState(state: UiState): void {
         projectOrder: state.projectOrder,
         threadLastVisitedAtById: state.threadLastVisitedAtById,
         defaultAdvertisedEndpointKey: state.defaultAdvertisedEndpointKey,
+        sidebarProjectScopeKey: state.sidebarProjectScopeKey,
         threadChangedFilesExpansionVersion: THREAD_CHANGED_FILES_EXPANSION_VERSION,
         threadChangedFilesExpandedById: state.threadChangedFilesExpandedById,
       } satisfies PersistedUiState),
@@ -304,6 +313,17 @@ export function setDefaultAdvertisedEndpointKey(state: UiState, key: string | nu
   };
 }
 
+export function setSidebarProjectScopeKey(state: UiState, projectKey: string | null): UiState {
+  const nextKey = sanitizeOptionalKey(projectKey);
+  if (state.sidebarProjectScopeKey === nextKey) {
+    return state;
+  }
+  return {
+    ...state,
+    sidebarProjectScopeKey: nextKey,
+  };
+}
+
 export function resolveProjectExpanded(
   projectExpandedById: Readonly<Record<string, boolean>>,
   preferenceKeys: readonly string[],
@@ -386,6 +406,7 @@ interface UiStateStore extends UiState {
   markThreadUnread: (threadId: string, latestTurnCompletedAt: string | null | undefined) => void;
   setThreadChangedFilesExpanded: (threadId: string, turnId: string, expanded: boolean) => void;
   setDefaultAdvertisedEndpointKey: (key: string | null) => void;
+  setSidebarProjectScopeKey: (projectKey: string | null) => void;
   setProjectExpanded: (projectIds: string | readonly string[], expanded: boolean) => void;
   reorderProjects: (
     currentProjectOrder: readonly string[],
@@ -404,6 +425,8 @@ export const useUiStateStore = create<UiStateStore>((set) => ({
     set((state) => setThreadChangedFilesExpanded(state, threadId, turnId, expanded)),
   setDefaultAdvertisedEndpointKey: (key) =>
     set((state) => setDefaultAdvertisedEndpointKey(state, key)),
+  setSidebarProjectScopeKey: (projectKey) =>
+    set((state) => setSidebarProjectScopeKey(state, projectKey)),
   setProjectExpanded: (projectIds, expanded) =>
     set((state) => setProjectExpanded(state, projectIds, expanded)),
   reorderProjects: (currentProjectOrder, draggedProjectIds, targetProjectIds) =>
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 955099fba65e..702c18840983 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -80,6 +80,7 @@ const unitTestProject = {
     // run, those async tests can exceed Vitest's default 5s budget.
     hookTimeout: 15_000,
     testTimeout: 15_000,
+    setupFiles: ["../../packages/shared/src/testing/longTempDir.ts"],
   },
 } satisfies TestProjectInlineConfiguration;
 
@@ -268,6 +269,7 @@ export default defineConfig(() => {
     build: {
       outDir: "dist",
       emptyOutDir: true,
+      manifest: true,
       sourcemap: buildSourcemap,
     },
     test: {
diff --git a/docs/README.md b/docs/README.md
index 2e2e55fbbadc..4e6f82bfb826 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,47 +2,55 @@
 
 ## Using T3 Code
 
-- [Install and first run](./user/install.md)
+- [Install T3 Code](./user/install.md)
+- [Messages and context](./user/composer.md)
+- [Working with threads](./user/thread-sidebar.md)
 - [Permission modes](./user/permission-modes.md)
+- [Terminal history](./user/terminal.md)
+- [Source control](./user/source-control.md)
+- [Project settings](./user/project-settings.md)
+- [Appearance and themes](./user/appearance.md)
 - [Keyboard shortcuts](./user/keybindings.md)
-- [Organizing threads](./user/thread-sidebar.md)
-- [Review usage](./user/usage.md)
-- [Customize a project icon](./user/project-settings.md)
-- [Mobile appearance](./user/mobile-appearance.md)
-- [Environment themes](./user/environment-theme.md)
+- [Import browser sessions](./user/browser-import.md)
+- [Usage and limits](./user/usage.md)
+- [Product usage data](./user/telemetry.md)
 - [Remote access](./user/remote-access.md)
-- [Keeping app and server in sync](./user/updating.md)
-- [Source control integrations](./user/source-control.md)
-- [Background service (Linux)](./user/background-service.md)
-- Providers: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md)
-
-Mobile app: [apps/mobile/README.md](../apps/mobile/README.md)
+- [Running in the background](./user/background-service.md)
+- [Updating T3 Code](./user/updating.md)
+- Provider guides: [Codex](./user/providers-codex.md) · [Claude](./user/providers-claude.md) · [OpenCode](./user/providers-opencode.md) · [Antigravity](./user/providers-antigravity.md)
 
 ---
 
 ## Working on T3 Code
 
-Everything below is for maintainers. Setup lives in the [root README](../README.md);
-policy in [CONTRIBUTING.md](../CONTRIBUTING.md); agent rules in [AGENTS.md](../AGENTS.md).
+Start with the [development runbook](./operations/development.md) and
+[contribution policy](../CONTRIBUTING.md).
+
+Internal notes preserve architectural decisions, constraints, and implementation traps that the
+source alone does not explain. Most code changes do not need an internal documentation update. Follow the
+[documentation rules](../AGENTS.md#documentation) before adding one.
 
 - [Architecture overview](./internals/overview.md)
-- [Workspace layout](./internals/workspace-layout.md)
 - [Glossary](./internals/glossary.md)
-- [Scripts](./internals/scripts.md)
 - [Connection runtime](./internals/connection-runtime.md)
-- [Voice input](./internals/voice-input.md)
 - [Providers](./internals/providers.md)
+- [Model classification](./internals/model-manifest.md)
 - [Remote environments](./internals/remote.md)
 - [Server updates](./internals/server-updates.md)
 - [Resource telemetry](./internals/resource-telemetry.md)
 - [Product analytics](./internals/product-analytics.md)
 - [Environment auth](./internals/environment-auth.md)
 - [T3 Connect](./internals/t3-connect.md)
-- [CI gates](./internals/ci.md)
-- [Engineering work artifacts](./internals/work-artifacts.md)
+- [Assistant citations](./internals/assistant-citations.md)
+- [Mobile navigation](./internals/mobile-navigation.md)
+- [Mobile development lifecycle](./internals/mobile-development.md)
+- [Terminal runtime](./internals/terminal-runtime.md)
+- [Voice input](./internals/voice-input.md)
 
 ### Runbooks
 
+- [Development and local builds](./operations/development.md)
+- [T3 Connect setup](./operations/connect-setup.md)
 - [Release](./operations/release.md)
 - [Observability](./operations/observability.md)
 - [Relay observability](./operations/relay-observability.md)
diff --git a/docs/architecture/terminal-renderers.md b/docs/architecture/terminal-renderers.md
deleted file mode 100644
index 4b66a13f68c4..000000000000
--- a/docs/architecture/terminal-renderers.md
+++ /dev/null
@@ -1,42 +0,0 @@
-# Terminal renderers
-
-Terminal sessions remain server-owned PTYs. Clients receive the existing raw byte stream and send
-input and resize events over the existing terminal contracts; renderer choices never cross the
-wire.
-
-## Ghostty alignment
-
-Android and web use the official `libghostty-vt` C ABI for parsing, terminal state, grapheme
-boundaries, keyboard encoding, selection, and scrollback:
-
-- Android links the native shared library and converts render state into a compact JNI snapshot.
-- Web loads a separately cached WebAssembly build and reads render state into a Canvas 2D surface.
-- Both artifacts are built from the revision in
-  `native/libghostty-vt/VERSION`.
-
-The platform adapters deliberately own only platform behavior. Android owns its Kotlin Canvas and
-touch integration. Web owns browser font shaping, the hidden IME textarea, clipboard and DOM input,
-and its Canvas renderer. The web adapter also delegates application mouse encoding, word and line
-selection, and OSC 8 hyperlink metadata to the official ABI. Browser conventions remain available:
-holding Shift bypasses application mouse capture, and the platform link modifier opens hyperlinks.
-React does not participate in terminal frames.
-
-The web runtime is singleton-scoped per browser tab so split terminals share one compiled module
-and memory. Each visible terminal owns and frees its own terminal, render state, row iterator, cell
-iterator, key and mouse encoder, and input event handles. Restoring captured scrollback temporarily
-detaches the PTY callback so historical device queries cannot emit replies into the current shell.
-
-## Updating Ghostty
-
-Update and rebuild Android first, because mobile's `VERSION` file is the single source of truth for
-the upstream pin (the upstream `LICENSE` lives beside it). Then run:
-
-```sh
-pnpm --dir apps/web build:ghostty-wasm
-```
-
-Commit the regenerated web `wasm` artifacts. The build embeds the pinned revision into the binary as
-semver build metadata, and the focused web ABI test reads it back through `ghostty_build_info` and
-compares it against mobile's `VERSION` — so the web vendor directory holds only the artifacts, drift
-cannot hide, and there is no second pin to keep in sync. The same test enforces the artifact budget
-and exercises repeated create/write/free cycles with multi-codepoint graphemes.
diff --git a/docs/internals/assistant-citations.md b/docs/internals/assistant-citations.md
index 77bd53dff8d9..2c49163fadb4 100644
--- a/docs/internals/assistant-citations.md
+++ b/docs/internals/assistant-citations.md
@@ -1,135 +1,29 @@
 # Assistant citations
 
-> For maintainers. Using T3 Code? See [Quote an assistant response](../user/composer.md#quote-an-assistant-response).
-
-Assistant citations store a selected excerpt and its source in ordinary message text. They need
-no database migration, citation table, or sidecar draft metadata. The saved excerpt remains
-available even when the source response is missing or has changed.
-
-## Serialized form
-
-[`AssistantCitation`][contract] defines version 1. [`assistantCitations.ts`][shared] serializes it
-as a Markdown link with the literal label `Assistant quote`:
-
-```text
-[Assistant quote](t3-citation://v1/<environmentId>/<threadId>/<messageId>?text=<quote>&start=<start>&end=<end>&prefix=<prefix>&suffix=<suffix>&comment=<optional-user-comment>)
-```
-
-The formatter percent-encodes each path segment and uses `URLSearchParams` for the query. The
-environment, thread, and message IDs identify the source without a browser origin, so local,
-remote, and tunnel clients share one form. Opening the source still requires access to its
-environment.
-
-The parser accepts only version 1 with exactly three source IDs and one of each selector field;
-`comment` is optional and links without one keep their original format. It rejects credentials,
-ports, malformed encoding, and extra or duplicate query fields. IDs have a 512-character limit,
-the quote and comment each fit in 8,000 UTF-16 code units, offsets are nonnegative safe integers
-with `end > start`, prefix and suffix each fit in 32 code units, and the URI itself is capped at
-160,000 characters. Malformed or unsupported links remain ordinary prompt text everywhere:
-collectors, provider expansion, and readable fallbacks all skip them. Parsing validates the
-payload, not the existence of its source.
-
-## Selection and source matching
-
-[`assistantTextSelection.ts`][selection] captures one native DOM range inside one assistant
-response, including backward and paragraph selections. Empty range endpoints at neighboring blocks
-are narrowed to the first and last selected text nodes before validating the source, so
-triple-click selections that end at the next block still resolve. The text stream follows DOM
-order, inserts line breaks between blocks and at `<br>`, and includes displayed code and link
-text. Controls, hidden subtrees, CSS-generated content, and soft wrapping do not contribute.
-
-`text` keeps the exact selected excerpt, including line breaks and indentation. `start`, `end`,
-`prefix`, and `suffix` use the rendered-text stream after each JavaScript whitespace run collapses
-to one space, without trimming, in UTF-16 code units. Context boundaries avoid splitting
-surrogate pairs.
-
-Resolution uses the same normalization and case-sensitive matching. It checks the saved offsets
-against the quote and context, then searches for a context-matching occurrence if positions have
-moved. A unique quote can still match after its context changes. Multiple context-matching
-occurrences are ambiguous, even if one remains at the saved offsets; the resolver does not guess.
-
-## Composer and clients
-
-[`AssistantSelectionToolbar`][toolbar] offers **Cite in composer** for a selection within one
-response and disables it above the quote limit. It shares [`selectionActions.ts`][actions] with
-the terminal's selection menu: the observer opens actions only after a primary-button release from
-a gesture that started inside the surface, waits out the 500 ms repeat-click window so
-double/triple clicks can finish, anchors to the release point (or the text end for keyboard
-selections), and dismisses on outside interaction, scrolling, or `Escape`. The toolbar registers
-its own element with the observer so interacting with it cannot replace the captured quote.
-
-`ChatView` inserts the serialized link at the last composer cursor. A one-shot editor request then
-opens the comment editor beside the cited source text, carrying the live DOM range for positioning
-and an editing highlight; that range is transient and never becomes part of the citation.
-`withAssistantCitationComment` trims outer whitespace and removes the field when blank; it never
-changes the saved quote or selector. Restoring or pasting a citation does not reopen the editor.
-
-[`ComposerCitationNode`][node] is an inline Lexical `DecoratorNode` holding the quote and comment
-as one atomic chip. Its label shows the comment when present, otherwise a short quote preview; the
-node retains the full serialized source and returns it from `getTextContent()`. Comment edits
-update the citation and serialized source together as one undoable change. The token parser,
-clipboard handling, and cursor mapping treat citations as inline tokens alongside mentions and
-skills, so drafts, stashes, and pastes reconstruct chips from the prompt string alone. Sent
-messages keep the same links; `ChatMarkdown` renders valid citation URIs as read-only
-[`AssistantCitationChip`][chip]s, and the whole chip supplies its serialized value to Markdown
-copy so the displayed label is not duplicated as text.
-
-## Source navigation
-
-[`assistantCitationNavigation.ts`][navigation] routes to the source thread with
-`#assistant-citation=<base64url-encoded citation URI>`; the encoding keeps router hash
-normalization from decoding quote whitespace or source IDs. Each click adds a fresh activation ID
-to navigation state so the same link can reveal its source again after dismissal.
-
-[`useAssistantCitationTarget`][target] loads earlier history (bounded at 20 pages or a repeated
-cursor, with a warning past that), expands a folded turn, and asks the virtual list to mount the
-source row. While positioning, the timeline disables initial end-scroll and scroll maintenance and
-keeps the cited row mounted until measured; the activation ID doubles as the list's data version
-so pinning rows recalculates a stationary Legend list without discarding measurements.
-
-[`AssistantCitationSource`][source] resolves the DOM range, smoothly scrolls to it, and pulses
-only that text through the CSS Highlight API: two 650 ms pulses driven by a registered opacity
-property, with the second settling into a held highlight before fading out. Navigation owns the
-highlight's start time and completion state: range repairs keep the original clock, remounting
-resumes only the remaining time, and an expired or dismissed highlight cannot revive. Reduced
-motion scrolls instantly and holds the highlight without pulsing. Browsers
-without the Highlight API temporarily select the range and remove only that owned selection.
-User navigation or `Escape` cancels pending positioning; missing messages or unmatched text
-produce warnings without changing the saved quote. The separate comment-editing highlight uses
-the same range-repair observer while its editor is open.
-
-Desktop shares the web implementation. Mobile's `ThreadFeed` uses `renderAssistantCitationsAsText`
-to show sent quotes as readable Markdown blockquotes with each user comment below its quote; it
-does not create citations or navigate to sources.
-
-## Provider input and titles
-
-[`ProviderService.sendTurn`][provider] calls `expandAssistantCitationsForProvider` before routing
-to any adapter; persisted messages keep their links. Each distinct serialized link becomes an
-inline `[assistant-quote-N]` marker, and one `<assistant_citations>` block carries JSON entries
-with an `id` and the complete `citation`. The block identifies `citation.text` as quoted reference
-material, not new instructions, and `citation.comment` as the user's comment about that quote.
-JSON encoding escapes `<`, `>`, and `&` so content cannot close the wrapper. The expansion is
-shared by all providers; there is no per-adapter citation handling or source lookup at send time.
-
-The 120,000-character provider input limit applies both before and after expansion:
-[`composerSubmission.ts`][submission] checks the larger length client-side and keeps an over-limit
-draft editable, and the server revalidates the expanded input before dispatch. Expansion does not
-apply to pending user-input answers.
-
-`assistantCitationsToPlainText` supplies readable input for title seeds, stash previews, and the
-server's title and branch-name helpers, which see the quoted text and comment rather than an
-encoded URI.
-
-[contract]: ../../packages/contracts/src/assistantCitations.ts
-[shared]: ../../packages/shared/src/assistantCitations.ts
-[selection]: ../../apps/web/src/lib/assistantTextSelection.ts
-[toolbar]: ../../apps/web/src/components/chat/AssistantSelectionToolbar.tsx
-[actions]: ../../apps/web/src/lib/selectionActions.ts
-[node]: ../../apps/web/src/components/ComposerCitationNode.tsx
-[chip]: ../../apps/web/src/components/chat/AssistantCitationChip.tsx
-[navigation]: ../../apps/web/src/lib/assistantCitationNavigation.ts
-[target]: ../../apps/web/src/components/chat/useAssistantCitationTarget.ts
-[source]: ../../apps/web/src/components/chat/AssistantCitationSource.tsx
-[provider]: ../../apps/server/src/provider/Layers/ProviderService.ts
-[submission]: ../../apps/web/src/components/chat/composerSubmission.ts
+Citations carry the selected excerpt and source identity in ordinary message text.
+Drafts, clipboard copies, stashes, and sent messages keep that representation
+without a separate citation store. The saved quote remains usable when its source
+disappears or changes. The [shared format](../../packages/shared/src/assistantCitations.ts) uses
+stable environment IDs without a browser origin, so moving between local, remote,
+and tunnel connections does not change a citation's identity.
+
+Source navigation is best effort. [Text selectors](../../apps/web/src/lib/assistantTextSelection.ts)
+refer to rendered text after whitespace normalization, measured in UTF-16 units.
+They cannot be applied to raw Markdown. The original excerpt keeps its whitespace;
+normalization is only for locating it. Repeated text needs an unambiguous context
+match, even if one occurrence still sits at the saved offsets. Guessing could
+highlight the wrong claim.
+
+Navigation owns the highlight's lifetime across virtual-row remounts. The source
+row must be fetched, unfolded, mounted, and measured before quote positioning
+takes over from normal timeline scrolling. Remounting must not revive a dismissed
+highlight. The [navigation hash](../../apps/web/src/lib/assistantCitationNavigation.ts)
+uses base64url because router normalization otherwise decodes whitespace and
+source IDs inside the citation URI.
+
+[ProviderService](../../apps/server/src/provider/Layers/ProviderService.ts) expands
+citations before dispatch to any provider adapter. It sends the saved excerpt
+without looking up the source, distinguishes quoted reference material from the
+user's comment, and leaves persisted messages in their original form. Input
+limits apply after expansion as well as before it. A draft that fits as encoded
+links can exceed the provider limit once expanded.
diff --git a/docs/internals/ci.md b/docs/internals/ci.md
deleted file mode 100644
index 67851009f5c2..000000000000
--- a/docs/internals/ci.md
+++ /dev/null
@@ -1,44 +0,0 @@
-# CI quality gates
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-[`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) runs these quality gates on pull requests
-and pushes to `main`:
-
-- **Check**: `vp check` (format and lint; this repo sets `typeCheck: false` in its lint options),
-  then `vpr typecheck` for the workspace type check. The same job
-  builds the desktop pipeline (`vp run build:desktop`) and verifies the preload bundle exists and
-  uses only imports that Electron's sandbox can load. The verifier parses imports, then executes the
-  trusted artifact with controlled bridge stubs to confirm that its required APIs are callable.
-- **Test**: `vp run test` across the workspace.
-- **Mobile Native Static Analysis**: `vp run lint:mobile` on macOS, wrapping
-  `scripts/mobile-native-static-check.ts`. A cheap Linux **Mobile Native Changes** job gates it:
-  the macOS runner only boots when the diff touches `apps/mobile` Swift/Kotlin sources, the
-  SwiftLint/detekt/ktlint configuration, the `Brewfile`, the check script, the root `package.json`
-  that defines `lint:mobile`, or `ci.yml`. Otherwise the job is skipped, which GitHub reports as
-  success for the required check. Renames are matched on both their old and new path. The gate fails
-  open in every other case: if the changed-file list cannot be resolved, GitHub truncates it, or the
-  gate job itself fails, the lint runs.
-- **Release Smoke**: exercises release-only workflow steps through `scripts/release-smoke.ts`, so
-  release breakage surfaces on PRs rather than at tag time.
-
-[`.github/workflows/windows-tests.yml`](../../.github/workflows/windows-tests.yml) is a manual
-Windows lane (`workflow_dispatch` only) on a Blacksmith Windows 2025 runner. The suite does not
-pass on Windows yet, so it is not a required check; it exists so the work to get there can be
-iterated against a real Windows box without one on hand. Dispatch it with `gh workflow run
-windows-tests.yml --ref <branch>`, optionally with `-f package=<dir>` to run one workspace package
-and `-f files="<paths>"` to run specific test files inside it. Once it is green, fold it into
-`ci.yml`.
-
-`.github/workflows/release.yml` builds macOS (`arm64` and `x64`), Linux (`x64`), and Windows (`x64`)
-desktop artifacts from a single `v*.*.*` tag and publishes one GitHub release. It auto-enables
-signing only when platform credentials are present. macOS passkey builds additionally require
-`APPLE_TEAM_ID` and the `MACOS_PROVISIONING_PROFILE` secret; Windows uses Azure Trusted Signing.
-Without the core signing credentials, it still releases unsigned artifacts.
-
-Preflight shares pnpm's lockfile verification results with the desktop build jobs through a small
-artifact. This avoids repeating dependency checks, especially on Windows, without transferring the
-large registry metadata cache. pnpm checks the current lockfile and policy before it reuses a result.
-If the artifact is unavailable, installation runs the checks again.
-
-See [Release Checklist](../operations/release.md) for the full release/signing setup checklist.
diff --git a/docs/internals/connection-runtime.md b/docs/internals/connection-runtime.md
index 1b686c365770..797ff8fe31fe 100644
--- a/docs/internals/connection-runtime.md
+++ b/docs/internals/connection-runtime.md
@@ -1,196 +1,74 @@
-# Connection Runtime
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-The connection runtime is shared by web and mobile. It owns connectivity,
-authentication, retries, transport lifetime, cached environment data, and
-environment-scoped operations.
-
-Web and mobile mount this runtime once at the application root and compose it
-identically: `apps/web/src/connection/runtime.ts` and
-`apps/mobile/src/connection/runtime.ts` differ only in the platform layer they
-supply. There is no legacy connection owner or supported mixed mode.
-
-## Composition
-
-[`connection/layer.ts`][layer] assembles the runtime:
-
-- `ConnectionResolver` ([resolver.ts][resolver]) resolves a catalog entry into a
-  prepared, authenticated endpoint for primary, bearer, relay, or SSH targets.
-- `ConnectionDriver` ([driver.ts][driver]) prepares through the resolver, opens
-  one RPC session, and reports `preparing`, `opening`, and `synchronizing`.
-- `RpcSessionFactory` ([rpc/session.ts][session]) performs one transport
-  attempt. It does not retry. `RpcSession` is the interface it returns,
-  exposing `client`, `initialConfig`, `ready`, `probe`, and `closed`.
-- `EnvironmentRegistry` ([registry.ts][registry]) owns the catalog and the
-  per-environment scopes.
-- `ConnectionOnboarding` and `RelayEnvironmentDiscovery` sit alongside the
-  registry. Startup calls `EnvironmentRegistry.start` and streams platform
-  registrations into `reconcilePlatform`.
-
-The registry creates one environment-scoped supervisor per environment.
-`acquireSupervisor` serializes access per environment, reuses an existing
-supervisor when the catalog entry is unchanged, and closes and recreates the
-scope when it changed. `createServiceScope` builds an `EnvironmentSupervisor`
-bound to a closeable scope and connects it; `run` and `runStream` execute caller
-effects with that supervisor provided.
-
-`EnvironmentSupervisor` owns desired state, retry scheduling, and the active
-session scope. React components do not create connections, transports, retry
-loops, or RPC clients.
-
-## Connection State
-
-The supervisor is the only retry owner.
-
-1. A persisted or platform registration marks an environment as desired.
-2. If the device is offline, the supervisor releases the active session and
-   waits for a signal without consuming retry attempts or running a timer.
-3. When online, it asks the driver for one prepared connection and one RPC
-   session.
-4. Transient failures retry forever with exponential backoff capped at 16
-   seconds (`RETRY_DELAYS_MS`). A connection stable for 30 seconds resets
-   accumulated backoff.
-5. Authentication or configuration failures remain blocked until an external
-   wakeup changes the relevant input.
-6. An involuntary session close keeps the registration and cache, then retries.
-7. Explicit removal closes the session and deletes the registration,
-   credentials, shell cache, and thread cache.
-
-### Wakeups
-
-Wakeup handling differs by phase, in [supervisor.ts][supervisor]:
-
-- During establishment, `waitForEstablishmentInterrupt` consumes and **ignores**
-  plain application activation. Restarting an in-flight attempt because the app
-  came to the foreground would only delay it. The exception is
-  `application-active-reconnect`, which mobile emits after a meaningful
-  background suspension; it interrupts establishment and resets the retry
-  ladder, because the OS may have silently killed the socket underneath the
-  attempt.
-- Credential changes interrupt establishment only for relay targets, where a new
-  credential changes what is being established.
-- Explicit disconnect, explicit retry, and going offline interrupt establishment
-  in every case.
-- While waiting out backoff, application activation resets the retry ladder so a
-  foregrounded app reconnects immediately instead of serving the remaining
-  delay.
-- Once connected, `monitorConnectedLease` handles plain activation by probing
-  the existing session (`lease.session.probe`, with a shorter timeout for
-  mobile's `application-active-probe`) rather than reconnecting; a healthy
-  session survives foregrounding. `application-active-reconnect` skips the probe
-  and replaces the lease outright.
-
-The UI derives `available`, `offline`, `connecting`, `reconnecting`,
-`connected`, and `error` from supervisor state plus explicit data-sync state.
-It does not infer connection health from cached data or the existence of a
-transport object. An environment becomes `connected` after the socket opens and
-the initial config RPC succeeds, proving that the server is responsive. Shell
-and thread synchronization are independent data states. A healthy RPC transport
-with a failed shell subscription is shown as connected with a synchronization
-error, not as a reconnect that is not actually scheduled.
-
-## Data Boundary
-
-Finite requests, durable subscriptions, and commands are separate APIs:
-
-- Query atoms revalidate when the RPC generation changes.
-- Subscription atoms switch to replacement sessions.
-- Subscription failure handling in [rpc/client.ts][client] distinguishes two
-  cases. A transport failure (`isTransportFailure`: every failure is an RPC
-  client error) ends the inner subscription without resubscribing, so the outer
-  stream waits for the supervisor to supply a replacement session. A handled
-  domain failure runs `onExpectedFailure` and, when
-  `retryExpectedFailureAfter` is set, sleeps and resubscribes on the **same**
-  session. A healthy transport is never torn down for a domain failure.
-- Mutations resolve the current environment runtime at execution time.
-- Shell and thread snapshots are available while offline.
-- Sync status is explicit and independent per domain. Shell status is `empty`,
-  `cached`, `synchronizing`, or `live`, with a separate `error` field; there is
-  no `failed` status. Thread status adds `deleted`.
-- Cached shell and thread projections are never allowed to overwrite newer live
-  data during a fast reconnect.
-- Domain atom factories route effects through the environment registry and
-  resolve the current scoped service at execution time. Project and thread
-  commands are Atom factories under `src/state`
-  (`createProjectEnvironmentAtoms`, `createThreadEnvironmentAtoms`), as are the
-  shell and thread state factories (`createEnvironmentShellAtoms`,
-  `createEnvironmentThreadStateAtoms`).
-- Web and mobile own their Atom runtimes, React hooks, and feature composition.
-
-The Promise bridge exists only at the React/Atom boundary. Runtime and business
-logic remain Effect-native.
-
-## Platform Layers
-
-Web and mobile provide:
-
-- network status and network-change streams;
-- application lifecycle wakeups;
-- cloud session credentials;
-- device identity;
-- platform registrations;
-- persistent catalog, credential, shell, and thread stores;
-- HTTP, crypto, and telemetry layers.
-
-Platform layers adapt operating-system capabilities. They do not implement
-connection policy. `EnvironmentOwnedDataCleanup` is part of this contract: on
-removal the registry clears its cache and calls the platform implementation, so
-web clears composer drafts and mobile clears drafts plus the thread outbox.
-
-Mobile cloud sign-out first saves relay drafts and queued messages in the local
-composer store under the owning account. These saved copies retain attachment
-files during cleanup and remain outside the active composer and upload queue.
-Signing back into that account restores them before relay credentials activate.
-Directly paired environments keep their drafts and outbox when cloud sign-out runs.
-
-Mobile composer attachments upload over HTTP while their environment is connected,
-with at most three concurrent transfers. Drafts retain local image data or an owned
-file URI alongside the pending upload ID. Sending verifies and reuses that ID, or
-uploads the local bytes again if it expired. Disconnecting cancels active transfers
-without discarding drafts; reconnecting resumes preparation. Older servers without
-attachment-upload support continue to receive inline images.
-
-## Source Boundaries
-
-Applications must import explicit package subpaths; the package intentionally
-has no root export. The subpaths are documented in
-[packages/client-runtime/README.md](../../packages/client-runtime/README.md),
-with the `exports` map in that package's `package.json` as the authoritative
-list. Files that are not exported are implementation details.
-
-## Application Boundary
-
-The application root mounts the shared connection layer, creates its own Atom
-runtime, and selects the domain atom factories required by that platform. Web
-and mobile may expose different hooks and features without changing connection
-ownership.
-
-Application code must not construct RPC clients, retry loops, or raw
-orchestration commands. Persistence paths belong to the platform registration
-and cache stores, with explicit migration or invalidation policy.
-
-## Verification
-
-Core state-machine tests use `@effect/vitest` and deterministic service layers.
-Required coverage includes:
-
-- offline startup and online wakeup;
-- forever retry with the 16-second cap;
-- explicit retry interrupting backoff;
-- authentication wakeups;
-- involuntary close and reconnect;
-- explicit removal clearing all owned state;
-- relay token reuse and refresh;
-- progressive relay discovery;
-- shell and thread cache hydration;
-- durable subscriptions switching sessions;
-- command metadata and idempotent queued-command metadata.
-
-[layer]: ../../packages/client-runtime/src/connection/layer.ts
-[resolver]: ../../packages/client-runtime/src/connection/resolver.ts
-[driver]: ../../packages/client-runtime/src/connection/driver.ts
-[registry]: ../../packages/client-runtime/src/connection/registry.ts
-[supervisor]: ../../packages/client-runtime/src/connection/supervisor.ts
-[session]: ../../packages/client-runtime/src/rpc/session.ts
-[client]: ../../packages/client-runtime/src/rpc/client.ts
+# Connection runtime
+
+Web, the desktop renderer, and mobile share one connection owner per environment
+in `packages/client-runtime`. Platform code supplies storage, credentials, network
+signals, and application lifecycle events. React views consume the runtime.
+Keeping retries and session lifetime here prevents competing reconnect loops when
+several views need the same environment.
+
+## One transport retry owner
+
+The [supervisor](../../packages/client-runtime/src/connection/supervisor.ts) owns
+transport retry policy; resolving an endpoint and opening an RPC session are single
+attempts. Transient failures retry with capped backoff. Offline states and
+authentication failures wait for a wakeup instead of spending attempts on
+unchanged conditions.
+
+Foregrounding needs different treatment depending on the connection's state.
+It wakes a retry immediately, leaves an ordinary in-flight attempt alone, and
+probes an established session before replacing it. A long mobile background
+suspension forces replacement because the OS can kill a socket without reporting
+closure. Treating every foreground event as a reconnect delays healthy attempts;
+treating every resume as harmless leaves suspended sockets stuck.
+
+The [registry](../../packages/client-runtime/src/connection/registry.ts) scopes
+connections by environment. An involuntary disconnect retains the registration
+and cached data. Explicit removal closes the scope and clears credentials,
+projections, and platform-owned state such as drafts. Cloud-account changes apply
+to relay registrations; they must not discard directly paired environments.
+
+## HTTP authorization
+
+RPC sessions authenticate at socket upgrade, while HTTP requests need current
+credentials from the
+[authorization service](../../packages/client-runtime/src/authorization/service.ts).
+Replacing a healthy socket for HTTP renewal would interrupt conversations and
+change the transport generation without a transport failure. Credential expiry
+does not close the socket, and refresh failure belongs to the HTTP operation.
+
+Session listings must retain unrevoked connected sessions after credential expiry
+so an open connection does not disappear from connection management. This does
+not extend the credential's lifetime. New HTTP requests and socket upgrades still
+require valid credentials.
+
+## Transport health and data freshness are separate
+
+A socket opening is insufficient evidence that the environment is usable. The
+[RPC session](../../packages/client-runtime/src/rpc/session.ts) waits for the
+initial server configuration before becoming ready. Shell and thread data then
+have their own synchronization state. A failed shell subscription can coexist
+with a healthy connection; labeling that state "reconnecting" promises a
+transport retry that will never happen.
+
+Cached projections remain readable offline. They must neither imply a live
+connection nor overwrite newer live data during a reconnect. Loading and
+resuming snapshots belongs to the shared state services, so every view agrees
+on which data is current.
+
+[Thread detail](../../packages/client-runtime/src/state/threads.ts) separates
+subscription lifetime from cache lifetime. Mounted consumers share one live
+stream, which stops when the last consumer unmounts; hidden mounted routes still
+count. A registry-local cache retains state and its replay cursor for five idle
+minutes so back navigation can resume without another snapshot download.
+
+Retain state and cursor together only after an update finishes. Cancellation must
+not advance the cached cursor beyond the applied data, and an old scope must not
+overwrite its successor's cache. Preserve pagination data on reuse, but clear
+canceled loading state.
+
+The [RPC boundary](../../packages/client-runtime/src/rpc/client.ts) resolves
+requests against the current session at execution time. Durable subscriptions
+follow replacement sessions. After a transport failure they wait for the
+supervisor; an expected domain failure may resubscribe on the same healthy
+session. Reconnection does not automatically replay mutations, whose retry and
+idempotency rules belong to the operation.
diff --git a/docs/internals/environment-auth.md b/docs/internals/environment-auth.md
index 98b3df0a0dc8..dc43b4d45c03 100644
--- a/docs/internals/environment-auth.md
+++ b/docs/internals/environment-auth.md
@@ -1,191 +1,60 @@
-# Environment Authentication Profile
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-The environment server and the relay use separate credentials, issuers, and trust
-boundaries. They intentionally use a similar OAuth-shaped model so that permission
-checks and token exchange behavior can be audited against established concepts.
-
-## Authorization Model
-
-Environment authorization is capability-based. A session carries zero or more
-OAuth-style scope strings:
-
-| Scope                   | Permission                                                               |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `orchestration:read`    | Read snapshots, status, events, configuration, and filesystem/VCS state. |
-| `orchestration:operate` | Dispatch user operations and mutate environment-side workspace state.    |
-| `terminal:operate`      | Create, attach, input, resize, clear, restart, and terminate terminals.  |
-| `review:write`          | Read review diff previews used to compose review feedback.               |
-| `access:read`           | Inspect pairing links and client sessions.                               |
-| `access:write`          | Create or revoke pairing links and client sessions.                      |
-| `relay:read`            | Inspect managed relay connectivity.                                      |
-| `relay:write`           | Link, configure, or unlink managed relay connectivity.                   |
-
-Pairing-link lists and access-stream snapshots and updates contain metadata only.
-The raw credential is returned only by the creation request, after the server checks
-`access:write` and the delegated scopes. Web and desktop clients keep that response
-in memory for sharing. They do not recover credentials from access read models.
-
-Ordinary pairing links grant the four client-operation scopes and read access to
-managed relay connectivity:
-`orchestration:read orchestration:operate terminal:operate review:write relay:read`.
-The desktop bootstrap credential and command-line administrative bootstrap
-credentials additionally grant `access:read access:write relay:write`.
-
-## Host file access
-
-Clients with `orchestration:read` can read files anywhere the environment's server account can
-read, following the environment-wide authorization model rather than introducing per-project
-filesystem permissions. `projects.readFile` accepts an absolute path and returns the text of that
-host file; only workspace-relative paths pass its root check, and `projects.writeFile` never
-accepts an absolute path. Clients use this to show files an agent wrote outside the workspace, such
-as a report in a temp directory, read-only.
-
-## Media preview access
-
-Clients with `orchestration:read` can request a `media-file` URL through `assets.createUrl` for
-supported images, videos, HTML, and PDF files anywhere the environment's server account can read.
-A thread ID supplies the workspace for relative paths; absolute paths refer to the environment
-host, not the client.
-
-[`AssetAccess.ts`](../../apps/server/src/assets/AssetAccess.ts) resolves symlinks, requires a regular
-file, and validates the resolved file's literal extension. It opens the file and signs its canonical
-path and device/inode identity for one hour. The token grants access to that exact file, not adjacent
-files or its containing directory. Serving rechecks the canonical path, media type, and opened
-descriptor's identity, then streams full or partial responses from that descriptor. Replacing a
-file atomically requires a freshly signed URL; editing it in place does not. Because the token names
-one file, an HTML document served this way cannot load sibling assets; the directory-scoped
-`workspace-file` resource remains the route for HTML inside the workspace. Uploaded attachments keep
-their separate asset resource.
-
-Signed asset URLs are bearer credentials. Anyone who obtains a URL and can reach the environment
-can fetch that file until it expires. Clients should copy the authored reference, not the temporary
-URL. Responses use `nosniff`; SVG responses retain their restrictive sandbox policy. Video reads
-support byte ranges so playback does not require a complete download first.
-
-Host videos can change in place, so their responses use `private, no-store` and omit `ETag`
-and `Last-Modified`. File metadata cannot prove byte-for-byte identity for `If-Range`; advertising
-those validators would encourage native players to send conditional seeks that require a full
-response. Ordinary range requests receive partial responses. An explicitly supplied `If-Range`
-still falls back to a full response because no strong validator is available. Host image previews
-keep their private cache policy and weak metadata validators.
-
-The server serves media in place without importing it into attachment storage. Deletion makes
-future server reads fail, though an already loaded client or its cache can retain bytes. Native
-viewers may use temporary client-side files for display or explicit sharing; those are not durable
-environment copies.
-
-## Authentication Flows
-
-### Browser Session
-
-`POST /api/auth/browser-session` consumes a one-time bootstrap credential and creates a
-browser session cookie. The cookie is an HTTP transport adapter for the same
-scoped session model; the response never exposes the session secret to browser
-JavaScript.
-
-### Bearer Access Token
-
-Non-browser clients use `POST /oauth/token` with an
-`application/x-www-form-urlencoded` body:
-
-```text
-grant_type=urn:ietf:params:oauth:grant-type:token-exchange
-subject_token=<bootstrap credential>
-subject_token_type=urn:t3:params:oauth:token-type:environment-bootstrap
-requested_token_type=urn:ietf:params:oauth:token-type:access_token
-scope=orchestration:read orchestration:operate terminal:operate review:write relay:read
-```
-
-Clients may additionally submit `client_label`, `client_device_type`, and
-`client_os` extension parameters so the authorized-clients UI can identify the
-device that established the session. These are presentation hints only; the
-environment derives transport metadata such as IP address and user agent from
-the request and does not use these fields for authorization.
-
-The response has the token-exchange shape:
-
-```json
-{
-  "access_token": "<opaque session token>",
-  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
-  "token_type": "Bearer",
-  "expires_in": 2592000,
-  "scope": "orchestration:read orchestration:operate terminal:operate review:write relay:read"
-}
-```
-
-Sessions issued from a plain bearer exchange use the store's
-`DEFAULT_SESSION_TTL` of 30 days. The shorter one-hour `expires_in: 3600` applies
-only to DPoP-bound exchanges, where the token is additionally constrained by a
-proof key. See `SessionStore.ts` and `EnvironmentAuth.ts`.
-
-Requested scopes must be a subset of the one-time bootstrap credential grant.
-An ordinary paired client therefore cannot exchange its grant for
-`access:read`, `access:write`, or `relay:write`.
-
-### DPoP-Bound Access Token
-
-The same `/oauth/token` exchange supports proof-of-possession tokens. A client
-that sends a `DPoP` header has its proof verified by `verifyRequestDpopProof`;
-the resulting JWK thumbprint is stored on the session, which is then issued with
-method `dpop-access-token` and a one-hour TTL instead of the bearer default. An
-invalid proof gets a DPoP challenge header and a credential error rather than a
-bearer token. Newer servers include a safe `dpopFailureReason` category in that
-error. When an older server omits the category, clients mention clock skew as
-one possible cause rather than presenting it as confirmed.
-
-`dpop-access-token` is advertised alongside `browser-session-cookie` and
-`bearer-access-token` in the descriptor's `sessionMethods`
-(`EnvironmentAuthPolicy.ts`), so clients can discover support rather than
-assume it. Relay-brokered clients use this mode so that a leaked token cannot be
-replayed without the corresponding key.
-
-### WebSocket Ticket
-
-`POST /api/auth/websocket-ticket` accepts any authenticated session and returns
-a short-lived, single-purpose WebSocket ticket, issued through
-`EnvironmentAuth.issueWebSocketTicket` with a five-minute default TTL. The
-client presents its bearer or DPoP credential in headers to get the ticket, then
-appends only that ticket to the socket URL as `wsTicket`. This keeps long-lived
-tokens and browser cookies out of WebSocket URLs while letting the handshake
-authenticate.
-
-The ticket carries its session's scopes; each RPC method then enforces
-`orchestration:read`, `orchestration:operate`, `terminal:operate`,
-`review:write`, `relay:write`, or `access:read` as appropriate, through
-`RPC_REQUIRED_SCOPES` in `apps/server/src/auth/RpcAuthorization.ts`. Review feedback submission currently dispatches
-an orchestration operation, so clients performing it also need
-`orchestration:operate`. Creating a ticket is not authorization to call every
-RPC method.
-
-## Standards Alignment
-
-- Bearer access tokens are used through the `Authorization: Bearer` scheme from
-  RFC 6750.
-- The token endpoint profiles the request and response vocabulary from OAuth 2.0
-  Token Exchange (RFC 8693), including `subject_token`, `requested_token_type`,
-  `access_token`, `issued_token_type`, and `token_type`.
-- Scope values follow the OAuth 2.0 scope model from RFC 6749: space-delimited,
-  unordered capabilities with subset checking during exchange.
-
-This is intentionally not a general-purpose OAuth authorization server. The
-environment bootstrap token type is private, the bootstrap cookie and WebSocket
-connection-token routes are product-specific adapters, and the API returns its
-typed `HttpApi` errors rather than implementing every OAuth error response
-surface.
-
-## Upgrade Behavior
-
-Migration `031_AuthAuthorizationScopes` is a hard cutover from role-bearing auth
-records to scoped records. It deletes existing pairing links and sessions while
-leaving non-authentication environment state unchanged. Upgraded clients must
-pair again; old `owner` or `client` credentials are never silently mapped to new
-capabilities.
-
-## Relay Boundary
-
-Relay-managed tunnels use their own tokens and keys. The relay can reuse scope
-parsing and token-exchange conventions, but an environment access token is not a
-relay token and cannot be presented to the relay.
+# Environment authentication
+
+The environment issues its own sessions and enforces their capabilities. Cloud
+identity and relay credentials belong to a separate trust boundary, described in
+[T3 Connect](./t3-connect.md). A relay token is never an environment login.
+
+## Authority survives transport changes
+
+Pairing delegates a set of scopes. Exchanging a bootstrap credential can narrow
+that grant but cannot widen it. Ordinary pairing does not grant access-management
+or relay-management authority. Creating another pairing link requires both
+`access:write` and every scope being delegated. The
+[auth handlers](../../apps/server/src/auth/http.ts) enforce this at issuance;
+client labels and device metadata have no authorization role.
+
+The access read model contains pairing metadata, never recoverable pairing
+secrets. Only the creation response returns the raw credential. Otherwise read
+access to the connections list would become a way to acquire another client's
+authority.
+
+Browser cookies, bearer tokens, and DPoP tokens adapt the same scoped session
+model. DPoP binds a token to a client's proof key; an invalid proof must fail
+rather than fall back to bearer authentication. The OAuth token-exchange
+vocabulary gives these grants a familiar meaning, but the environment does not
+implement a general-purpose OAuth authorization server.
+
+Bearer and DPoP clients obtain short-lived WebSocket tickets through authenticated
+HTTP so long-lived tokens stay out of socket URLs. Browser sessions can
+authenticate the upgrade with their cookie. A successful handshake grants no
+extra authority: [every RPC declares a required
+scope](../../apps/server/src/auth/RpcAuthorization.ts).
+
+Desktop restarts forget the previous local bearer token, so its reusable
+bootstrap grant replaces earlier sessions for the same subject and method.
+Revocation and insertion share a [database
+transaction](../../apps/server/src/persistence/AuthSessions.ts); a failed
+replacement must leave the old credential usable. Pairing and browser sessions
+do not follow this replacement rule.
+
+## The environment is the filesystem boundary
+
+Projects are organizational boundaries, not filesystem sandboxes.
+`orchestration:read` permits reading files the server account can read, including
+absolute paths outside a project. This lets clients display artifacts that an
+agent writes in a temporary directory. Relative paths and writes still follow
+the [workspace path rules](../../apps/server/src/workspace/WorkspaceFileSystem.ts).
+
+Signed asset URLs are bearer credentials. A URL for media on the host grants
+access to one canonical file and its device/inode identity, not its containing directory.
+[Asset access](../../apps/server/src/assets/AssetAccess.ts) rechecks the opened
+file's identity when serving it, so atomic replacement requires a new URL while
+editing the same file in place does not. An HTML file authorized this way cannot
+load sibling assets; directory-scoped workspace previews are a separate grant.
+Clients should share the authored file reference so they do not disclose the
+temporary URL's credential.
+
+Host videos can change in place. Their [HTTP
+responses](../../apps/server/src/http.ts) omit cache validators because file
+metadata cannot prove byte-for-byte identity for `If-Range`. Adding weak
+validators would turn native-player seeks into full downloads.
diff --git a/docs/internals/glossary.md b/docs/internals/glossary.md
index 94d958ba8789..b3f95b210d62 100644
--- a/docs/internals/glossary.md
+++ b/docs/internals/glossary.md
@@ -1,234 +1,66 @@
 # Glossary
 
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-This is a living glossary for T3 Code. It explains what common terms mean in this codebase.
-
-## Table of contents
-
-- [Project and workspace](#project-and-workspace)
-- [Thread timeline](#thread-timeline)
-- [Orchestration](#orchestration)
-- [Provider runtime](#provider-runtime)
-- [External Lead Agent](#external-lead-agent)
-- [Checkpointing](#checkpointing)
-- [Appearance](#appearance)
-
-## Concepts
-
-### Project and workspace
-
-#### Project
-
-The top-level workspace record in the app. In [the orchestration contracts][1], a project has a `workspaceRoot` and a title. It does not contain threads: `OrchestrationProject` and `OrchestrationThread` are separate arrays on the read model, and a project can have zero threads. See [workspace-layout.md][2].
-
-#### Workspace root
-
-The root filesystem path for a project. In [the orchestration model][1], it is the base directory for branches and optional worktrees. See [workspace-layout.md][2].
-
-#### Worktree
-
-A Git worktree used as an isolated workspace for a thread. If a thread has a `worktreePath` in [the contracts][1], it runs there instead of in the main working tree. Git operations live behind the VCS driver contract in `apps/server/src/vcs/VcsDriver.ts`, implemented by [GitVcsDriverCore.ts][3].
-
-### Thread timeline
-
-#### Thread
-
-The main durable unit of conversation and workspace history. In [the orchestration contracts][1], a thread holds messages, activities, checkpoints, and session-related state. See [projector.ts][4].
-
-#### Turn
-
-A single user-to-assistant work cycle inside a thread. It starts with user input and ends when the session leaves `running` status, which [projector.ts][4] treats as the authoritative completion signal (`settledTurnStateForSessionStatus`). Checkpoint and diff work may settle afterward without changing when the turn ended. See [the contracts][1] and [ProviderRuntimeIngestion.ts][5].
-
-#### Activity
-
-A user-visible log item attached to a thread. In [the contracts][1], activities cover important non-message events like approvals, tool actions, and failures. They are projected into thread state in [projector.ts][4].
-
-### Orchestration
-
-Orchestration is the server-side domain layer that turns runtime activity into stable app state. The main entry point is [OrchestrationEngine.ts][7], with core logic in [decider.ts][8] and [projector.ts][4].
-
-#### Aggregate
-
-The domain object a command or event belongs to. In [the contracts][1], that is usually `project` or `thread`. See [decider.ts][8].
-
-#### Command
-
-A typed request to change domain state. In [the contracts][1], commands are validated in [commandInvariants.ts][9] and turned into events by [decider.ts][8].
-Examples include `thread.create`, `thread.turn.start`, and `thread.checkpoint.revert`.
-
-#### Domain Event
-
-A persisted fact that something already happened. In [the contracts][1], events are the source of truth, and [projector.ts][4] shows how they are applied.
-Examples include `thread.created`, `thread.message-sent`, and `thread.turn-diff-completed`.
-
-#### Decider
-
-The pure orchestration logic that turns commands plus current state into events. The core implementation is in [decider.ts][8], with preconditions in [commandInvariants.ts][9].
-
-#### Projection
-
-A read-optimized view derived from events. See [projector.ts][4], [ProjectionPipeline.ts][11], and [ProjectionSnapshotQuery.ts][10].
-
-#### Projector
-
-The logic that applies domain events to the read model or projection tables. See [projector.ts][4] and [ProjectionPipeline.ts][11].
-
-#### Read model
-
-The current materialized view of orchestration state. In [the contracts][1], it holds projects, threads, messages, activities, checkpoints, and session state. See [ProjectionSnapshotQuery.ts][10] and [OrchestrationEngine.ts][7].
-
-#### Reactor
-
-A side-effecting service that handles follow-up work after events or runtime signals. Examples include [CheckpointReactor.ts][6], [ProviderCommandReactor.ts][12], and [ProviderRuntimeIngestion.ts][5].
-
-#### Receipt
-
-A typed signal emitted when an async milestone completes, such as `checkpoint.baseline.captured`, `checkpoint.diff.finalized`, or `turn.processing.quiesced`. Receipts are a test-only mechanism: the production `RuntimeReceiptBusLive` publish is a no-op and only the test layer is PubSub-backed. Do not build production behavior on them. See [RuntimeReceiptBus.ts][13] and [CheckpointReactor.ts][6].
-
-#### Quiesced
-
-"Quiesced" means a turn has gone quiet and stable: follow-up work such as [CheckpointReactor.ts][6] has settled. It appears in [the receipt schema][13], so in practice it is something tests wait on rather than a production signal.
-
-### Provider runtime
-
-The live backend agent implementation and its event stream. The main service is [ProviderService.ts][14], the adapter contract is [ProviderAdapter.ts][15], and the overview is in [providers.md][16].
-
-#### Provider
-
-The backend agent runtime that actually performs work. Six drivers ship built in: Codex, Claude, Cursor, Grok, OpenCode, and Antigravity. See [ProviderService.ts][14], [ProviderAdapter.ts][15], and [CodexAdapter.ts][17] as a representative adapter.
-
-#### Session
-
-The live provider-backed runtime attached to a thread. Session shape is in [the orchestration contracts][1], and lifecycle is managed in [ProviderService.ts][14].
-
-#### Runtime mode
-
-The safety/access mode for a thread or session. [The contracts][1] define four values: `approval-required`, `auto-accept-edits`, `auto`, and `full-access`. See [permission modes][18].
-
-#### Interaction mode
-
-The agent interaction style for a thread. In [the contracts][1], the values are `default` and `plan`.
-
-#### Assistant delivery mode
-
-Controls how assistant text reaches the thread timeline. In [the contracts][1], `streaming` updates incrementally and `buffered` accumulates text. Buffered delivery is not held until the turn completes: it spills once accumulated text would exceed 24,000 characters, and flushes at approval and user-input boundaries. See [ProviderRuntimeIngestion.ts][5].
-
-#### Snapshot
-
-A point-in-time view of state. The word is used in multiple layers, including orchestration, provider, and checkpointing. See [ProjectionSnapshotQuery.ts][10], [ProviderAdapter.ts][15], and [CheckpointStore.ts][19].
-
-#### Usage limits
-
-The rolling subscription quota windows a provider reports for its signed-in account, such as Claude's five-hour and weekly windows or Codex's primary and secondary allowances. Each driver decides in its own `checkProvider` whether it has any and returns them on the snapshot as `usageLimits`; drivers with no notion of subscription usage leave the field absent. Adapters that receive rate-limit telemetry during a turn normalise it into a `ProviderUsageLimitsUpdate` at the boundary, and `ProviderUsageLimitsIngestion` folds it onto the owning instance's snapshot through `ServerProviderShape.applyUsageLimits`, so no central service needs to know a driver kind. See [providerUsageLimits.ts](../../packages/contracts/src/providerUsageLimits.ts) and [makeManagedServerProvider.ts](../../apps/server/src/provider/makeManagedServerProvider.ts).
-
-#### Usage limit source
-
-A read-only quota feed outside this environment's provider CLIs, configured under `settings.usageLimitSources`. The only kind today is a CLIProxyAPI hub, whose `quota-scheduler/status` reports the windows of every pooled account. `UsageLimitSources` polls each source on the provider health interval and publishes `UsageLimitSourceSnapshot`s over the config stream as `usageLimitSourcesUpdated`, gated by a client capability flag the way environment themes are. The management key round-trips through the secret store with a redaction marker on disk. See [UsageLimitSources.ts](../../apps/server/src/usage/UsageLimitSources.ts).
-
-#### Model manifest
-
-The per-driver list of current model slugs that decides which models land in the model picker's legacy section. Bundled at `apps/server/src/provider/model-manifest.json` and refreshed at runtime from the same file on `main`, so classification updates ship as commits instead of releases. See the [provider architecture][16] model manifest section.
-
-### External Lead Agent
-
-#### Lead Agent
+Terms whose meaning matters across T3 Code. Architecture and lifecycle constraints belong in the
+[overview](./overview.md), not in these definitions.
+
+## Workspace and conversation
+
+| Term           | Meaning                                                                                           |
+| -------------- | ------------------------------------------------------------------------------------------------- |
+| Environment    | One running server and the machine, credentials, workspace access, and state it owns.             |
+| Client         | A web, desktop, or mobile UI connected to an environment. The desktop app can also host a server. |
+| Project        | An environment-local workspace record rooted at a directory.                                      |
+| Workspace root | The project's base filesystem directory on the environment.                                       |
+| Worktree       | A separate Git checkout a thread can use instead of the project's main checkout.                  |
+| Thread         | The durable conversation and work history for a project. It survives provider process exits.      |
+| Turn           | One user-to-agent work cycle. Provider work can finish before checkpoint and diff work settles.   |
+| Activity       | A non-message timeline item, such as a tool action, approval, or failure.                         |
+| T3 home        | The base data directory. Runtime state normally lives under its `userdata` directory.             |
+
+## Orchestration
+
+| Term                    | Meaning                                                                                      |
+| ----------------------- | -------------------------------------------------------------------------------------------- |
+| Command                 | A request to change domain state. Accepting it does not mean its side effects have finished. |
+| Event                   | A persisted fact produced by a command.                                                      |
+| Decider                 | The pure logic that turns a command and current state into events.                           |
+| Projection / read model | A view of current state derived from persisted events.                                       |
+| Projector               | The logic that applies events to a read model.                                               |
+| Reactor                 | A worker that performs follow-up work in response to recorded intent or runtime signals.     |
+| Command receipt         | A durable record of a command's result, used to make retries idempotent.                     |
+| Runtime receipt         | A test-only signal that an asynchronous milestone completed.                                 |
+| Quiesced                | The relevant follow-up workers have finished, beyond the provider turn merely ending.        |
+
+## Providers and checkpoints
+
+| Term                | Meaning                                                                                                      |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Provider            | The agent runtime T3 Code controls, such as Codex or Claude Code.                                            |
+| Driver              | The integration for a provider kind.                                                                         |
+| Provider instance   | One configured provider, with its own settings and lifecycle. Multiple instances can use the same driver.    |
+| Adapter             | The boundary translating a provider's native protocol into T3 Code operations and events.                    |
+| Session             | The provider runtime attached to a thread. A session can be stopped and resumed without deleting the thread. |
+| Runtime mode        | The thread's permission policy. See [permission modes](../user/permission-modes.md).                         |
+| Interaction mode    | How the agent approaches the task, such as planning. Separate from permission policy.                        |
+| Checkpoint          | A saved workspace state used for diffs and restore, stored as a hidden Git ref.                              |
+| Checkpoint baseline | The workspace state captured before the work being compared.                                                 |
+| Turn diff           | The workspace changes attributed to one turn.                                                                |
+
+## External Lead Agent
+
+### Lead Agent
 
 The persistent CMD Riker agent that owns its conversation and coordinates delegated work. T3 Code is
 a presentation client for this integration, not the Lead Agent's orchestration authority. See
-[the external Lead Agent architecture][25].
+[the external Lead Agent architecture](./lead-agent.md).
 
-#### Owner
+### Owner
 
 The person directing the external Lead Agent. This term is specific to the CMD Riker boundary; T3's
 general product language continues to use "user."
 
-#### Session View
+### Session View
 
 A presentation-safe snapshot of Lead Agent availability, delegated work, and notices. It is observed
 through T3 but remains projected by CMD Riker and contains no internal workflow identifiers. See
-[the Lead Agent contracts][26].
-
-### Checkpointing
-
-Checkpointing captures workspace state over time so the app can diff turns and restore earlier points. The main pieces are [CheckpointStore.ts][19], [CheckpointDiffQuery.ts][20], and [CheckpointReactor.ts][6].
-
-#### Checkpoint
-
-A saved snapshot of a thread workspace at a particular turn. In practice it is a hidden Git ref in [CheckpointStore.ts][19] plus a projected summary from [ProjectionCheckpoints.ts][21]. Capture and lifecycle work happen in [CheckpointReactor.ts][6].
-
-#### Checkpoint ref
-
-The durable identifier for a filesystem checkpoint, stored as a Git ref. It is typed in [the contracts][1], constructed in [Utils.ts][22], and used by [CheckpointStore.ts][19].
-
-#### Checkpoint baseline
-
-The starting checkpoint for diffing a thread timeline. This flow is surfaced through [RuntimeReceiptBus.ts][13], coordinated in [CheckpointReactor.ts][6], and supported by [Utils.ts][22].
-
-#### Checkpoint diff
-
-The patch difference between two checkpoints. Query logic lives in [CheckpointDiffQuery.ts][20], diff parsing lives in [Diffs.ts][23], and finalization is coordinated by [CheckpointReactor.ts][6].
-
-#### Turn diff
-
-The file patch and changed-file summary for one turn. It is usually computed in [CheckpointDiffQuery.ts][20], represented in [the contracts][1], and recorded into thread state by [projector.ts][4].
-
-### Appearance
-
-#### Environment theme
-
-A theme an environment's machine publishes for clients to follow, one file per theme under `themes/` in that environment's state directory; the filename is the theme id. [environmentTheme.ts][27] watches the directory and streams the set over `subscribeServerConfig`; clients render each as a library card, generating a full palette when the file carries seed colors and using the palette directly when it is a standard exported theme file. A desktop that retints its apps when the system theme changes rewrites its file, so T3 Code follows along without a restart. See [environment-theme.md][28].
-
-#### Default theme
-
-The environment's theme, held in its `settings.json` as `defaultTheme` (with `defaultThemeSetAt`
-as the set-generation) and set with `t3 theme set <id>`. Web and desktop clients apply each set
-once — live when connected, on the next connect otherwise — so setting it switches them, while a
-theme a user picks in Settings afterwards sticks until the next set; mobile keeps its own
-appearance settings. Naming a published [environment theme](#environment-theme) is how a desktop
-ships T3 Code already matching it.
-
-## Practical Shortcuts
-
-- If you see `requested`, think "intent recorded".
-- If you see `completed`, think "result applied".
-- If you see `receipt`, think "async milestone signal, for tests".
-- If you see `checkpoint`, think "workspace snapshot for diff/restore".
-- If you see `quiesced`, think "all relevant follow-up work has gone idle".
-
-## Related Docs
-
-- [Architecture overview][24]
-- [Provider architecture][16]
-- [External Lead Agent][25]
-- [Permission modes][18]
-- [Workspace layout][2]
-
-[1]: ../../packages/contracts/src/orchestration.ts
-[2]: ./workspace-layout.md
-[3]: ../../apps/server/src/vcs/GitVcsDriverCore.ts
-[4]: ../../apps/server/src/orchestration/projector.ts
-[5]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
-[6]: ../../apps/server/src/orchestration/Layers/CheckpointReactor.ts
-[7]: ../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
-[8]: ../../apps/server/src/orchestration/decider.ts
-[9]: ../../apps/server/src/orchestration/commandInvariants.ts
-[10]: ../../apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts
-[11]: ../../apps/server/src/orchestration/Layers/ProjectionPipeline.ts
-[12]: ../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
-[13]: ../../apps/server/src/orchestration/Services/RuntimeReceiptBus.ts
-[14]: ../../apps/server/src/provider/Layers/ProviderService.ts
-[15]: ../../apps/server/src/provider/Services/ProviderAdapter.ts
-[16]: ./providers.md
-[17]: ../../apps/server/src/provider/Layers/CodexAdapter.ts
-[18]: ../user/permission-modes.md
-[19]: ../../apps/server/src/checkpointing/CheckpointStore.ts
-[20]: ../../apps/server/src/checkpointing/CheckpointDiffQuery.ts
-[21]: ../../apps/server/src/persistence/Services/ProjectionCheckpoints.ts
-[22]: ../../apps/server/src/checkpointing/Utils.ts
-[23]: ../../apps/server/src/checkpointing/Diffs.ts
-[24]: ./overview.md
-[25]: ./lead-agent.md
-[26]: ../../packages/contracts/src/leadAgent.ts
-[27]: ../../apps/server/src/environmentTheme.ts
-[28]: ../user/environment-theme.md
+[the Lead Agent contracts](../../packages/contracts/src/leadAgent.ts).
diff --git a/docs/internals/mobile-development.md b/docs/internals/mobile-development.md
index e8923a4bc844..cf9132579229 100644
--- a/docs/internals/mobile-development.md
+++ b/docs/internals/mobile-development.md
@@ -1,50 +1,25 @@
 # Mobile development lifecycle
 
-Ordinary component changes use Metro Fast Refresh. The connection runtime uses
-a stable development-only atom runtime whose writable layer atom receives the
-newly evaluated Effect layer. Its module accepts the update only after installing
-that layer. Existing subscribers observe the new context, and Effect releases the
-previous runtime scope without restarting React Navigation. Production uses an
-ordinary `Atom.runtime` without this hot-update boundary.
-
-Replacing the atom registry itself disposes its old nodes; replacing the managed
-runtime starts its asynchronous disposal. These modules use normal Metro update
-propagation. The app does not call `DevSettings.reload` during their replacement.
-React can still reset state when its normal Fast Refresh rules require it.
-
-Do not reset the shared registry to clean up a connection-runtime edit: registry
-reset removes listeners from unedited mounted consumers. Do not self-accept a
-runtime module while leaving importers attached to its old implementation. A
-hot-update boundary must install fresh behavior through the existing reactive
-dependencies. These boundaries do not make every module-level atom family in the
-app hot-swappable; new runtime singletons still need explicit ownership. Editing
-the registry or managed runtime can still rebuild a much larger dependency graph
-than an ordinary component or connection-runtime edit.
-
-Environment supervisor scopes are children of the connection registry scope.
-The registry's per-environment map supports targeted shutdown, but it cannot be
-the sole owner: a supervisor created after that map's finalizer has run must
-still inherit the closed parent scope. Otherwise interrupted startup or runtime
-replacement can leave a session and WebSocket alive outside the current registry.
-
-The compact Home list owns its minute-based presentation clock in a focus effect.
-Blur clears the interval without a render-driving focus subscription; focus
-refreshes the clock immediately. Other prop or state changes can still render
-the hidden list. Exact snooze-expiry timers remain active, and the visible iPad
-sidebar keeps its own minute updates.
-
-Connection and runtime projections are shared per environment. Thread selection
-consumers should read those atoms instead of repeatedly parsing the same socket
-URL or constructing new connection objects during each render.
-
-The Uniwind dependency patch still recompiles CSS on Metro updates so newly used
-classes are discovered. It fingerprints the generated native stylesheet and
-theme list, then skips development-only global invalidation when that output is
-unchanged. A changed stylesheet or theme list still resets the style caches and
-notifies subscribers. The digest is committed only after initialization succeeds.
-Web and production retain their existing initialization behavior.
-
-After installing or changing the Uniwind patch, restart Metro once with
-`vp run dev:client:reset` from `apps/mobile`. pnpm gives patched packages new
-filesystem paths, and cached transforms can otherwise retain references to the
-previous package. Ordinary development starts should retain the transform cache.
+The [connection runtime's HMR boundary](../../apps/mobile/src/lib/hot-swappable-atom-runtime.ts)
+keeps a stable atom runtime and replaces its Effect layer through a writable atom.
+It accepts the update only after installing the new layer. Otherwise importers
+retain the old behavior even though Metro reports a successful refresh.
+
+Do not reset the shared atom registry to refresh a connection-runtime edit. Reset
+removes listeners from mounted consumers that Metro has no reason to rerender.
+When the registry or managed-runtime module itself changes, normal Metro propagation
+disposes its old resources. This boundary does not make arbitrary module-level atom
+families safe to hot-swap. Production uses an ordinary atom runtime.
+
+[Environment supervisor scopes](../../packages/client-runtime/src/connection/registry.ts)
+are children of the registry scope. The per-environment map supports targeted
+shutdown, but a supervisor created after its cleanup runs would escape it. A closed
+parent scope also closes late arrivals, preventing interrupted startup or runtime
+replacement from leaving a WebSocket alive outside the new registry.
+
+The [Uniwind patch](../../patches/uniwind@1.11.0.patch) still compiles CSS on Metro
+updates so newly used classes are discovered. It skips global style invalidation
+only when the generated stylesheet and theme list are unchanged. Skipping compilation
+would lose new classes; invalidating every consumer for unchanged output makes an
+ordinary component edit refresh the whole app. The fingerprint is recorded only
+after initialization succeeds.
diff --git a/docs/internals/mobile-navigation.md b/docs/internals/mobile-navigation.md
index c2528219ac6b..94bd550d142d 100644
--- a/docs/internals/mobile-navigation.md
+++ b/docs/internals/mobile-navigation.md
@@ -1,138 +1,56 @@
 # Mobile navigation
 
-The iOS Home and thread routes share the root native stack in
-[`Stack.tsx`](../../apps/mobile/src/Stack.tsx). Keeping them in one navigation
-controller lets UIKit animate the header between routes. The iPad sidebar owns
-a separate, single-screen stack; Android uses its own in-flow headers.
-
-Home and the iPad sidebar render their brand and connection status through
-`headerTitle`, with `Threads` retained as the route title. The editor-style native
-bar aligns that title on the leading side. Do not model the brand as a toolbar
-button: on iOS 26.5 UIKit morphs a background-free custom leading item's rectangle
-into the next screen's glass back button, even with distinct item identifiers.
-Using the title slot lets the brand and native back button animate separately.
-
-The connection-status title has a maximum width based on its header's width and
-trailing actions. A long environment name or larger text must not push Settings
-into UIKit's overflow menu. Keep the full status as the accessibility label
-while visually truncating it. The iPad sidebar uses its pane width, not the full
-window width.
-
-On iOS 26, UIKit does not recognize Fabric's custom text views when shaping the
-native scroll-edge fade. The screens patch gives custom title subviews an empty,
-non-interactive native label matching their bounds. This supplies the fade's
-geometry without drawing anything or turning the title back into a toolbar item.
-Check the top scroll fade as well as push/pop when changing these title views.
-
-The react-native-screens patch caches leading, trailing, and center item groups
-independently. A button can belong to only one group: constructing another group
-with the same button removes it from the previous one. Unrelated menu updates
-must therefore preserve the other groups while UIKit may be animating them.
-
-Each cache includes the owning header config, its item values, and custom native
-item identities, so changed content or remounted event emitters still rebuild.
-
-Custom header identifiers require native code generation and a new mobile build;
-an over-the-air JavaScript update alone is insufficient. The Android view manager
-implements the generated identifier setter as a no-op because this behavior is
-specific to iOS 26 and later.
-
-On iOS 26 the full-screen back swipe is UIKit's `interactiveContentPopGestureRecognizer`,
-and react-native-screens makes it wait for any horizontally scrollable ScrollView to
-fail first. Upstream applies that to every horizontal ScrollView regardless of
-position, so a back swipe on a code block or table that is already at its leading
-edge only bounces. The patch narrows the rule to ScrollViews with content still
-hidden to the left; at the leading edge they yield to the pop gesture like plain
-text does.
-
-After changing a dependency patch, refresh CocoaPods before rebuilding an
-existing iOS project. pnpm installs each patch hash in a different directory;
-an old Pods project can keep compiling the previous directory even though Metro
-and `apps/mobile/node_modules` resolve to the new patch.
-
-`ControlPillMenu` resolves semantic icon colors through `withUniwind` and supplies them to every
-iOS `MenuView` action, including nested actions. The menu library's Fabric bridge converts a missing
-`imageColor` to transparent, so callers should use this wrapper instead of
-rendering `MenuView` directly. Explicit colors are preserved, and destructive
-actions default to the theme's danger foreground color. Native stack header menus
-use a separate implementation and do not need this workaround.
+Home and thread routes share the [root native stack](../../apps/mobile/src/Stack.tsx)
+so UIKit can animate the header within one navigation controller. The iPad sidebar
+has its own stack. Splitting Home and threads between controllers loses that
+continuous transition.
+
+## UIKit constraints
+
+The [react-native-screens patch](../../patches/react-native-screens@4.26.2.patch)
+preserves behavior that is easy to break when changing native headers:
+
+- The brand belongs in `headerTitle`. On iOS 26.5, UIKit morphs a background-free
+  leading toolbar item's rectangle into the next screen's glass back button,
+  even when the items have different identifiers.
+- UIKit's scroll-edge fade does not recognize Fabric text views. An empty native
+  label supplies the custom title's geometry. Removing that apparently unused
+  view changes the fade.
+- Leading, trailing, and center item groups need independent caches. A button can
+  belong to only one group; rebuilding an unchanged group can pull its buttons
+  out of a group UIKit is still animating. Cache ownership also includes the
+  header config, whose event emitter changes on remount.
+- A horizontal ScrollView at its leading edge must yield to the full-screen back
+  gesture. Upstream gives every horizontal ScrollView priority, so swiping back
+  on a code block or table can only bounce its content.
+
+The patch adds native header props that require code generation and a new binary.
+Patch rebuild guidance lives in the
+[mobile development README](../../apps/mobile/README.md#development).
 
 ## Native media presentations
 
-`PresentationSource` in `NativePresentation` registers a thumbnail for AVKit,
-image zoom transitions, and UIKit's share sheet. Wrap the thumbnail as its single child
-and pass the stable identifier to the presentation. The registry keeps weak
-references to source views; recycled or compact composer thumbnails can register
-the same identifier. Identifiers must distinguish simultaneously visible attachments.
-The source registration does not own the preview. Android uses a regular view.
-
-On iOS, video previews mount `AVPlayerViewController` temporarily inside the
-registered source and enter full screen through AVKit. AVKit
-owns that zoom, its playback controls, Close button, and interactive dismissal.
-Do not replace AVKit's transition with `preferredTransition`: in the iOS 27
-simulator, that leaves native Close unable to exit full screen. When the source is unavailable,
-the player uses a standard modal presentation. Programmatic entry uses the same
-guarded `enterFullScreenAnimated:completionHandler:` selector as Expo Video;
-if that selector is unavailable, the player also falls back to a standard modal.
-
-`FilePreviewModal` resolves image and PDF sources from a URI, a signed environment asset,
-or a retained composer file. On iOS, Quick Look owns image and document layout, controls,
-zooming, sharing, and interactive dismissal. Its delegate supplies the registered thumbnail
-and its bounds for Quick Look's source-view zoom. Do not layer `preferredTransition` or
-another image scroll view over that presentation: Quick Look coordinates its image gestures
-with the return to the thumbnail. Missing sources use the standard transition, and Reduce
-Motion disables animation. A pending programmatic Close waits until the current presentation
-or cancelled dismissal has settled before starting another transition.
-
-The shared native presenter copies original bytes into its own temporary directory and
-removes that copy after dismissal. Network downloads write to disk, and sharing never edits
-the source attachment. Draft images use their stored upload data rather than a potentially
-expired picker URI. No React Navigation route or custom transition animator is needed.
-
-The same viewer handles message images, markdown images, PDF attachments and links,
-composer thumbnails, and workspace image previews. The workspace PDF web preview has an
-Open PDF action for the native viewer. Android retains its image viewer and uses the
-system chooser for PDFs. Saving images on iOS uses the add-only photo-library permission.
-
-Every full-screen video preview on iOS is AVKit, playing directly from the signed asset
-URL: sent attachments, composer drafts, and file links that point at a video. Inline
-markdown embeds and the workspace file screen play in place with the Expo Video player.
-AVKit handles buffering; the client does not download the entire file or show a separate
-opening overlay before presentation.
-The URL is captured once per preview so credential refresh does not restart playback.
-Media actions (copy path, open in file viewer, save or share) belong to the surface that
-opened the video, a long-press on the thumbnail, so the player carries no
-menu. AVKit has no retry; a failure alerts and closes, re-mints the URL in the background, and the next open plays from the fresh one.
-
-The native presentation promise completes after dismissal. Local draft previews
-hold their file lease until that promise settles. The iOS preview component requests
-native dismissal when its source screen unmounts. Playback pauses in the background.
-AVPlayer activates audio as playback starts. The presenter pauses and releases
-its own player on close, then restores the previous audio-session configuration
-if no other component changed it during playback. It does not deactivate the
-shared session, which may still serve another player or recorder. Android plays every
-video, attachments included, in its React Native modal with the Expo Video player.
-Composer drafts play and share from their local file; other videos stream from the
-signed URL and download only for save or share.
-
-`shareFileFromSource` uses the same source registration to anchor UIKit's activity
-controller. Its promise completes when the native share flow finishes, keeping
-the existing attachment lease and foreground handoff active for that duration.
-Android uses Expo Sharing. On iOS, received and draft video attachments expose
-Save or share through `VideoAttachmentMenu`. The attachment supplies the source
-identifier, and the native share presentation inherits its appearance. AVKit's
-iOS playback controls do not expose a public custom-share-action API.
-
-Video attachment thumbnails use Expo Video's native frame extraction and Expo Image.
-Received attachments use their signed asset URL; drafts retain and resolve their local file
-until extraction ends. Extraction is serial; temporary players never play or change audio settings. Leaving the screen cancels
-pending work; a 15-second limit prevents an unreachable source from holding up the queue.
-The client keeps at most 32 native images, each bounded to 480 pixels per side, keyed by
-environment and attachment identity rather than expiring URLs. Images still displayed keep
-their own references when evicted from that cache.
-
-The asset HTTP route supports single byte ranges for videos so iOS can read metadata and
-frames without first downloading the whole file. Normal downloads keep their full response;
-unsupported ranges and conditional `If-Range` requests also fall back to the full file.
-An older environment without range support may still show the play-card fallback. Thumbnail
-failure never disables playback or sharing.
+iOS delegates full-screen video to [AVKit](../../apps/mobile/modules/t3-native-controls/ios/T3NativeVideoPresentation.swift)
+and images and documents to [Quick Look](../../apps/mobile/modules/t3-native-controls/ios/T3NativeFilePresentation.swift).
+Each framework owns its controls and transition. A separate UIKit zoom transition
+prevents AVKit's native Close action from exiting full screen and interferes with
+Quick Look's interactive return to its thumbnail. The AVKit entry selector is
+guarded, with standard modal presentation as the fallback.
+
+[Thumbnail registration](../../apps/mobile/modules/t3-native-controls/ios/T3NativePresentation.swift)
+holds weak view references for transition and share-sheet anchors. It does not own
+the preview; a source row can disappear while a native presentation is open.
+Identifiers must distinguish attachments that are visible at the same time.
+Native promises complete after dismissal so callers keep local file leases until
+the preview or share flow has finished.
+
+Treat a dismissal request as pending until UIKit finishes its current transition.
+Starting another dismissal while presentation or an interactive dismissal is
+settling can strand the controller. Video cleanup restores the previous audio
+configuration only if it still matches the preview's configuration. It must not
+deactivate the shared audio session, which may belong to another player or recorder.
+
+Video playback holds the first signed asset URL for the lifetime of the preview.
+Following credential refreshes reactively would restart playback. Quick Look copies
+original bytes into its own temporary directory so preview and sharing cannot
+mutate a draft or workspace file.
diff --git a/docs/internals/model-manifest.md b/docs/internals/model-manifest.md
index d5be97afe92b..3892a1df7277 100644
--- a/docs/internals/model-manifest.md
+++ b/docs/internals/model-manifest.md
@@ -1,42 +1,25 @@
 # Model manifest
 
-`apps/server/src/provider/model-manifest.json` is bundled for offline startup and fetched from
-`main` at runtime. A remote fetch replaces the in-memory and on-disk cache only after generic
-catalog references and provider-owned adapter data validate. A failed or invalid fetch keeps the
-last successful remote manifest. The bundle is used when no valid remote cache exists, or when
-the bundle's `updatedAt` is later than the cached manifest's, so a release that edits the manifest
-takes effect before the next successful fetch. Bump `updatedAt` whenever you edit the file.
-
-The top-level provider catalog is generic: models contain presentation metadata, aliases, status,
-an optional badge, and a reusable capability profile. The profile and model `adapter` fields are
-opaque until the owning provider validates them with its own allowlisted schema.
-
-Claude Code uses the manifest as its complete built-in model catalog. To add a Claude model that
-uses an existing profile, add one object to `providers.claudeAgent.models`. Do not add a test or
-change application code. Add or change a profile in the same JSON file only when the model exposes
-a capability combination that does not already exist.
-
-`currentModels.claudeAgent` is retained as a frozen compatibility field for releases that predate
-catalog discovery. New Claude models do not need to be added there. Codex still discovers models
-from its app server and uses `currentModels.codex` only as a legacy-classification overlay.
-
-Claude model entries support:
-
-- `aliases`, `status`, `badge`, and `profile` for client presentation and selection.
-- `adapter.claudeCode.minVersion` and `maxVersionExclusive` for installed-runtime compatibility.
-- Profile-level effort mappings, model suffixes, and context-window metadata for dispatch.
-
-## Test policy
-
-Changing model data does not require tests. Do not add or update tests for a model slug, display
-name, alias, legacy status, version boundary, badge, or profile assignment. The bundled manifest is
-configuration and is validated by its schema when imported.
-
-Add tests only when implementation behavior changes:
-
-- Fetching, caching, fallback, or schema-version handling changes in the manifest service.
-- Provider-neutral profile resolution gains new semantics.
-- A provider adapter gains a new compatibility or dispatch mapping type.
-
-Resolver tests must use synthetic providers and model names so normal JSON edits never create test
-churn.
+The [bundled manifest](../../apps/server/src/provider/model-manifest.json) allows
+offline startup; fetching it from `main` lets model metadata change between
+releases. Failed fetches or invalid data preserve the last usable manifest.
+Remote data must pass both catalog-reference validation and the owning provider's
+adapter validation before replacing the cache.
+
+A newer bundle outranks the cached remote manifest by `updatedAt`, so a release can
+correct model data before the next successful fetch. Bump `updatedAt` whenever the
+file changes. Fetch time cannot establish which copy contains the newer edit.
+
+Generic catalog data describes presentation and capabilities. Each provider owns
+its adapter schema and dispatch mappings. Claude uses the manifest for its entire
+built-in catalog. Adding a model with an existing capability profile is a JSON
+edit; a new profile is needed only for a new capability combination. Codex still
+gets its model list from its app server.
+
+`currentModels.claudeAgent` is frozen for releases that predate catalog discovery.
+Do not extend it when adding Claude models. Codex uses `currentModels.codex` as a
+legacy-classification overlay for discovered models.
+
+Model data is schema-validated configuration. Tests should cover resolver, cache,
+and adapter semantics with synthetic model names, so adding a model never requires
+tests that repeat the configuration.
diff --git a/docs/internals/overview.md b/docs/internals/overview.md
index 3affe10c48f7..7d4f2d0170e1 100644
--- a/docs/internals/overview.md
+++ b/docs/internals/overview.md
@@ -1,179 +1,67 @@
 # Architecture
 
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-T3 Code is a server runtime that owns agent sessions, workspaces, and version control, plus clients
-(web, desktop, mobile) that talk to it over one authenticated Effect RPC WebSocket. The server is the
-execution boundary: every provider process, terminal, git operation, and filesystem read happens
-there, never in the client.
-
-```
-┌────────────────────────────────────────────────┐
-│ Clients: apps/web, apps/desktop, apps/mobile   │
-│ shared runtime: packages/client-runtime        │
-│  connection supervisor, RPC session, Atom state│
-└──────────────────┬─────────────────────────────┘
-                   │ Effect RPC over WebSocket (/ws)
-                   │ contract: packages/contracts
-┌──────────────────▼─────────────────────────────┐
-│ apps/server                                    │
-│  orchestration engine (event-sourced)          │
-│  provider driver registry (6 built-in drivers) │
-│  checkpointing, VCS, terminals, filesystem     │
-└──────────────────┬─────────────────────────────┘
-                   │ per-driver transport
-┌──────────────────▼─────────────────────────────┐
-│ Agent CLIs: Codex, Claude, Cursor, Grok,       │
-│ OpenCode, Antigravity                          │
-└────────────────────────────────────────────────┘
-```
-
-## The RPC boundary
-
-The client/server contract is an Effect RPC group, not a hand-rolled push protocol. [`rpc.ts`][rpc]
-declares `WS_METHODS` and assembles `WsRpcGroup`; each member is either unary or a server stream
-(`stream: true`). Streaming members such as `orchestration.subscribeShell`,
-`orchestration.subscribeThread`, `subscribeServerConfig`, and `terminal.attach` replace what used to
-be a broadcast push bus: a client subscribes to what it needs and the server pushes only on that
-subscription.
-
-[`ws.ts`][ws] serves the group. `websocketRpcRouteLayer` mounts `GET /ws`, authenticates the upgrade
-through `EnvironmentAuth.authenticateWebSocketUpgrade`, then hands the socket to
-`RpcServer.toHttpEffectWebsocket`. Authorization is per method: `RPC_REQUIRED_SCOPE` maps each method
-to a scope, and `authorizeEffect`/`authorizeStream` enforce it. Holding a valid socket is not
-authorization to call everything on it. See [environment-auth.md](./environment-auth.md).
-
-On the client, [`session.ts`][session] opens the socket and builds the typed client.
-`RpcSessionFactory` is the service; a session exposes `client`, `initialConfig`, `ready`, `probe`,
-and `closed`. It performs one attempt and does not retry. Retry, backoff, and offline policy belong
-to the connection supervisor.
-
-## Shared client runtime
-
-`packages/client-runtime` holds every non-visual client concern: connection lifecycle,
-authentication, RPC, cached environment data, and domain state as Atom factories. Web and mobile
-compose it the same way (`apps/web/src/connection/runtime.ts` and
-`apps/mobile/src/connection/runtime.ts` mirror each other, differing only in platform-specific
-background-activity layers) and differ beyond that only in the platform layer they supply and the
-UI they build on top. React components never construct transports, retry loops,
-or RPC clients. See [connection-runtime.md](./connection-runtime.md).
-
-## Orchestration is event-sourced
-
-The server does not mutate app state directly. Clients dispatch typed commands; the engine turns them
-into persisted events; projections derive the read model.
-
-[`OrchestrationEngine.ts`][engine] serializes this. `dispatch` offers a `CommandEnvelope` onto
-`commandQueue` and awaits its result; a single worker fiber takes envelopes one at a time, so command
-processing is totally ordered. For each envelope `processEnvelope`:
-
-1. checks the durable command receipt, making retries idempotent;
-2. runs `decideOrchestrationCommand` ([`decider.ts`][decider]) to produce events from command plus
-   current state, pure and side-effect free;
-3. inside one SQL transaction, appends events to the event store, applies them to the in-memory read
-   model via [`projector.ts`][projector], projects them into persisted tables, and writes the
-   accepted receipt;
-4. after commit, swaps in the new read model, cleans up attachments, and publishes committed events
-   to subscribers. Attachment cleanup failures are logged and do not reject committed commands.
-
-Because persistence and projection share a transaction, the read model cannot durably disagree with
-the event log. On dispatch failure the engine rereads persisted events past the starting sequence and
-reconciles.
-
-Command and event names live in [`orchestration.ts`][contracts]. Some commands are client
-dispatchable (`thread.create`, `thread.turn.start`, `thread.approval.respond`); others are internal
-and produced only by server-side reactors (`thread.message.assistant.delta`,
-`thread.turn.diff.complete`).
-
-A turn is complete when its session leaves `running` status, projected by
-`settledTurnStateForSessionStatus` in [`projector.ts`][projector]. Checkpoint work settling later
-does not define turn end.
-
-Thread settlement is server-owned. Each server's own settings control PR and inactivity
-settlement. Those keys are user preferences, so clients write them to every shared-settings sync
-target (`SHARED_SERVER_SETTING_KEYS` in `packages/client-runtime/src/state/sharedSettings.ts`) and
-warn when another target drifts. A target must have an active connection and advertise the
-`threadAutoSettlement` capability, which signals that the server can hold every shared key.
-[`ThreadSettlementReactor`][settlement] checks threads at startup, when those settings change, and
-once per minute, including when no client is connected. It dispatches the guarded internal
-`thread.auto-settle` command, which uses the existing settlement event lifecycle. Automatic
-settlement excludes live background work and requires a comparable PR timestamp for immediate PR
-settlement. The command carries the latest activity timestamp and rejects any later event for its
-thread after the reactor's snapshot. The sweep looks a branch up from the thread's worktree when it
-still exists, so it shares the per-cwd PR cache the sidebar polls instead of spending a second host
-request. Clients render the persisted settlement state and do not derive settlement from PR or
-inactivity state. A committed `thread.settled` event also lets `ProviderCommandReactor` stop an idle
-provider session.
-
-At turn completion, `CheckpointReactor` refreshes PR discovery when the checkout matches the
-thread's non-default branch. `VcsStatusBroadcaster` requires loaded remote status and permission
-from background policy. `GitManager` retries only a successful "no PR" cache entry for the current
-branch, preserving known PRs and failure backoff without fetching remotes. Remote status reads
-that write the broadcaster cache share a lock per cwd, including the initial status load.
-
-## Drainable workers
-
-Follow-up work runs asynchronously in queue-backed workers built on [`DrainableWorker`][worker]:
-[`ProviderRuntimeIngestion`][ingest] normalizes provider runtime streams into orchestration commands,
-[`ProviderCommandReactor`][cmd] dispatches provider calls in response to intent events,
-[`CheckpointReactor`][checkpoint] captures and reverts workspace checkpoints, and
-[`ThreadSettlementReactor`][settlement] evaluates server-owned automatic settlement rules.
-
-`DrainableWorker` pairs a transactional queue with a transactional count of outstanding items.
-`enqueue` atomically offers and increments; processing always decrements. `drain` retries until the
-count reaches zero, so a test can await "queue empty and current item finished" instead of sleeping.
-Each of these four services exposes `drain` for exactly this.
-
-Runtime receipts are a test-only mechanism. `RuntimeReceiptBusLive` in
-[`RuntimeReceiptBus.ts`][receipts] publishes nothing; only the test layer is PubSub-backed. Do not
-build production behavior on receipts.
-
-## Provider drivers
-
-Six drivers ship built in, registered in [`builtInDrivers.ts`][drivers] as `BUILT_IN_DRIVERS`:
-Codex, Claude, Cursor, Grok, OpenCode, and Antigravity. A driver declares its kind and config schema and creates a
-scoped adapter; `ProviderInstanceRegistry` owns live instances and `ProviderAdapterRegistry` resolves
-an instance to its adapter, so `ProviderService` routes session and turn operations without knowing
-which agent is behind them. See [providers.md](./providers.md).
-
-## Checkpointing
-
-Each turn is bracketed by workspace checkpoints so diffs and reverts are exact. `CheckpointStore`
-captures state as hidden Git refs through the VCS driver's checkpoint operations;
-`CheckpointDiffQuery` answers turn and full-thread diff requests; `CheckpointReactor` coordinates
-baseline capture, completed-turn capture, diff projection, and reverting both the workspace and the
-provider conversation. The storage contract is `VcsCheckpointOps` in
-[`VcsDriver.ts`](../../apps/server/src/vcs/VcsDriver.ts), implemented for Git in the same directory.
-
-## Startup
-
-[`serverRuntimeStartup.ts`][startup] runs a fixed lifecycle: start keybindings, settings, and
-reactors; publish welcome; signal command readiness (logged as `Accepting commands`); wait for the
-HTTP listener via `markHttpListening`; publish ready; fork the heartbeat; then either print headless
-output or open the browser. Command readiness precedes the listener, so a socket that opens can
-already dispatch.
-
-## Related
-
-- [Workspace layout](./workspace-layout.md), [Glossary](./glossary.md)
-- [Mobile navigation headers](./mobile-navigation.md)
-- [Remote environments](./remote.md), [Server updates](./server-updates.md)
-- [Resource telemetry](./resource-telemetry.md)
-- [Product analytics](./product-analytics.md)
-- [Scripts](./scripts.md), [CI gates](./ci.md)
-
-[rpc]: ../../packages/contracts/src/rpc.ts
-[contracts]: ../../packages/contracts/src/orchestration.ts
-[ws]: ../../apps/server/src/ws.ts
-[session]: ../../packages/client-runtime/src/rpc/session.ts
-[startup]: ../../apps/server/src/serverRuntimeStartup.ts
-[engine]: ../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts
-[decider]: ../../apps/server/src/orchestration/decider.ts
-[projector]: ../../apps/server/src/orchestration/projector.ts
-[worker]: ../../packages/shared/src/DrainableWorker.ts
-[ingest]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
-[cmd]: ../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
-[checkpoint]: ../../apps/server/src/orchestration/Layers/CheckpointReactor.ts
-[settlement]: ../../apps/server/src/orchestration/ThreadSettlementReactor.ts
-[receipts]: ../../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts
-[drivers]: ../../apps/server/src/provider/builtInDrivers.ts
+T3 Code keeps execution in the environment that owns the workspace. Web, desktop, and mobile
+clients control it over authenticated RPC. A remote client must never substitute its own filesystem,
+provider credentials, or machine state for the environment's. The desktop app bundles a server,
+but its renderer follows the same boundary.
+
+## Ownership boundaries
+
+Provider processes, terminals, Git, and project files belong to the server. Shared connection and
+domain state belongs in `packages/client-runtime`; clients supply platform services and UI.
+Keeping that logic shared prevents reconnect and multi-environment behavior from diverging between
+web and mobile. See [connection runtime](./connection-runtime.md) and
+[remote environments](./remote.md).
+
+The [RPC contract](../../packages/contracts/src/rpc.ts) is the boundary between independently
+versioned clients and servers. Subscriptions send the state a client needs, so a client viewing one
+thread does not pay for every thread's history. Authentication of a socket does not authorize every
+method on it. See [environment auth](./environment-auth.md).
+
+Provider-specific behavior belongs behind an adapter. Orchestration works with normalized commands
+and events, so adding a provider should not require branches throughout the domain or clients.
+See [provider constraints](./providers.md).
+
+## Durable intent and side effects
+
+The event log is the source of truth for orchestration state. The
+[engine](../../apps/server/src/orchestration/Layers/OrchestrationEngine.ts) serializes commands;
+the [decider](../../apps/server/src/orchestration/decider.ts) produces events without performing
+provider or filesystem work. Events, persisted projections, and the accepted command receipt commit
+in one database transaction. The in-memory state changes and subscribers receive events after that
+commit. This keeps command retries idempotent and prevents a persisted projection from getting
+ahead of the event log.
+
+Reactors perform side effects after intent has been recorded, then feed results back through
+commands. A command acknowledgement therefore means the intent committed, not that the provider,
+checkpoint, or other follow-up work finished. Keep external I/O out of the decider and the database
+transaction.
+
+Persisted events must remain decodable on replay. Changing a schema affects old environments at
+startup as well as live RPC traffic. Compatibility work must account for stored history, not just
+what the newest client sends.
+
+## Turn completion and checkpoints
+
+A turn ending and its follow-up work settling are separate milestones. The
+[projector](../../apps/server/src/orchestration/projector.ts) settles the turn from its session
+status. A late checkpoint or diff must not extend the recorded turn duration or keep the client
+showing provider work as active.
+
+[Checkpoints](../../apps/server/src/checkpointing/CheckpointStore.ts) use hidden Git refs to
+capture workspace state without adding commits to the user's branch. A revert must coordinate
+workspace state with the provider conversation. A provider that cannot roll back its conversation
+must reject that operation before changing the filesystem.
+
+## Waiting for asynchronous work
+
+Tests use [drainable workers](../../packages/shared/src/DrainableWorker.ts) to wait until both the
+queue and its current item have finished. An empty queue alone does not prove the worker is idle.
+
+Runtime receipts mark specific test milestones. Their
+[production layer](../../apps/server/src/orchestration/Layers/RuntimeReceiptBus.ts) is a no-op;
+production behavior must use persisted state and events. These test signals are separate from the
+durable command receipts that make dispatch idempotent.
+
+See the [glossary](./glossary.md) for shared terms and the
+[development runbook](../operations/development.md) for setup and checks.
diff --git a/docs/internals/product-analytics.md b/docs/internals/product-analytics.md
index 3690b10baf92..0e88610ada99 100644
--- a/docs/internals/product-analytics.md
+++ b/docs/internals/product-analytics.md
@@ -1,112 +1,49 @@
 # Product analytics
 
-T3 Code sends anonymous product events from the server to PostHog. The server
-uses the first available hashed Codex account ID, hashed Claude user ID, or
-installation-scoped anonymous ID as the distinct ID. It also keeps the
-telemetry opt-out, event buffer, and batch delivery. Clients do not load the
-PostHog browser SDK.
-
-## Client events
-
-These events use the metadata from the WebSocket connection that caused them.
-The metadata is not a person property or server-global current-client value.
-Two clients connected to one server can report different values at the same
-time.
-
-| Event                   | Description                                                                                                                                          |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `client.connected`      | The server accepted an authenticated WebSocket connection. Reconnects count again. Use this event for connection diagnostics, not active-use counts. |
-| `client.thread.started` | The server accepted a command that created a thread.                                                                                                 |
-| `client.turn.requested` | The server accepted a turn request. This is the standard active-use event.                                                                           |
-
-`provider.turn.sent` stays a provider execution event. It does not receive
-client metadata because a provider turn can continue after the requesting
-client disconnects.
-
-## Recommended properties
-
-Client properties appear on the three client events when the connected client
-reports them. Older clients can omit every client property.
-
-| Property               | Values and meaning                                                                                                                                                                              |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `surface`              | Product client: `web`, `desktop`, or `mobile`.                                                                                                                                                  |
-| `webDeployment`        | Web delivery: `hosted` for the hosted app or `server` for web files served by a T3 server. Web only. This does not describe connection distance.                                                |
-| `clientOs`             | `macOS`, `Windows`, `Linux`, `iOS`, `Android`, `ChromeOS`, `other`, or `unknown`.                                                                                                               |
-| `clientDeviceType`     | `desktop`, `phone`, `tablet`, or `unknown`. This is separate from `surface`.                                                                                                                    |
-| `clientBrowser`        | Normalized browser family. Web only. Browser detection is best effort.                                                                                                                          |
-| `clientAppVersion`     | Version of the connected client.                                                                                                                                                                |
-| `clientOsMajorVersion` | Client OS major version when the native client reports it. Initially mobile only.                                                                                                               |
-| `clientDeviceModel`    | Hardware model when the native client reports it. Initially mobile only. This is not a user-assigned device name.                                                                               |
-| `connectionMethod`     | `direct`, `ssh`, `relay`, or `unknown`. `direct` means that the client connected to the server endpoint without an SSH or relay connection. It does not mean both processes run on one machine. |
-
-Server properties appear on all events, including server boot and background
-events.
-
-| Property           | Values and meaning                                             |
-| ------------------ | -------------------------------------------------------------- |
-| `serverOs`         | Server process OS, normalized to the same names as `clientOs`. |
-| `serverArch`       | Server process architecture.                                   |
-| `serverWslDistro`  | WSL distribution from `WSL_DISTRO_NAME`, when present.         |
-| `serverAppVersion` | T3 server version.                                             |
-| `serverMode`       | Server runtime mode: `desktop` or `web`.                       |
-
-## Legacy properties
-
-Existing property meanings do not change:
-
-- `clientType` describes how the server runs. It is `desktop-app` for a desktop
-  server and `cli-web-client` for a CLI web server. It does not describe the
-  connected client. Use `surface` and `webDeployment` for new reports.
-- `platform`, `arch`, `wsl`, and `t3CodeVersion` describe the server. Use the
-  new `server*` names for new reports.
-- `appVersion` describes the connected client. Use `clientAppVersion` for new
-  reports.
-- Mobile connection events keep `os`, `osMajorVersion`, and `deviceModel`.
-  Use the new `client*` names for new reports.
-
-## PostHog dashboard
-
-Create one saved dashboard named `Client and platform usage`. Set
-`client.turn.requested` as the event for active-use reports. A user can appear
-in several client groups during one period, so do not add breakdown values to
-calculate a total.
-
-Save these insights:
-
-| Insight                         | Configuration                                                                                                                                                                                                                                                                           |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Active users, daily             | Trends, `client.turn.requested`, unique users, daily interval.                                                                                                                                                                                                                          |
-| Active users, weekly            | Trends, `client.turn.requested`, unique users, weekly interval.                                                                                                                                                                                                                         |
-| Active users, monthly           | Trends, `client.turn.requested`, unique users, monthly interval.                                                                                                                                                                                                                        |
-| Client usage                    | Trends, `client.turn.requested`, unique users. Save four filtered series: `surface = desktop`, `surface = mobile`, `surface = web` and `webDeployment = hosted`, and `surface = web` and `webDeployment = server`. Name them Desktop, Native mobile, Hosted web, and Server-served web. |
-| Client OS, active users         | Trends, `client.turn.requested`, unique users, breakdown by `clientOs`.                                                                                                                                                                                                                 |
-| Client OS, turns                | Trends, `client.turn.requested`, total events, breakdown by `clientOs`.                                                                                                                                                                                                                 |
-| Client versus server OS         | Table, `client.turn.requested`, breakdown by `clientOs` and `serverOs`.                                                                                                                                                                                                                 |
-| Connection method, active users | Trends, `client.turn.requested`, unique users, breakdown by `connectionMethod`.                                                                                                                                                                                                         |
-| Connection method, turns        | Trends, `client.turn.requested`, total events, breakdown by `connectionMethod`.                                                                                                                                                                                                         |
-| Mobile devices                  | Table, `client.turn.requested`, filter `surface = mobile`, breakdown by `clientOs`, `clientOsMajorVersion`, and `clientDeviceType`.                                                                                                                                                     |
-| Client version adoption         | Trends, `client.turn.requested`, unique users, breakdown by `clientAppVersion`.                                                                                                                                                                                                         |
-| Server version adoption         | Trends, `client.turn.requested`, unique users, breakdown by `serverAppVersion`.                                                                                                                                                                                                         |
-| Missing metadata                | Table or SQL insight that shows the percentage of `client.turn.requested` events where each of `surface`, `clientOs`, `clientDeviceType`, `clientAppVersion`, and `connectionMethod` is absent. Track `webDeployment` and `clientBrowser` only within `surface = web`.                  |
-
-In PostHog Data management, use the event and property descriptions from this
-document. Mark the recommended properties as verified. Keep `clientType`
-visible with its legacy description so old reports remain understandable.
-
-## Collection and release boundary
-
-Client values are best effort. Invalid values are ignored and never reject a
-connection. Browser clients use user-agent data for broad OS, browser, phone,
-and tablet groups. They do not infer CPU architecture or an exact OS version
-from `navigator.platform`.
-
-This change does not collect URLs, tokens, prompts, IP addresses, or
-user-assigned device names. It measures authenticated product use. It does not
-measure a person who visits the hosted app without connecting to a server.
-
-The new fields start with the first client and server release that contains
-this metadata path. Historical events cannot reliably identify the client OS,
-hosted web use, device type, or connection method when the old client did not
-send those fields. Reports must treat missing values as pre-release or older
-client data instead of backfilling them from server fields.
+The server owns PostHog delivery, opt-out, and identity for every connected client.
+[Identity selection](../../apps/server/src/telemetry/Identify.ts) hashes an available
+provider account ID, falling back to an installation-scoped ID. This identity can
+span several clients; it does not identify a browser session. Clients do not load
+the PostHog browser SDK. Client-use events require an authenticated connection, so
+visiting the hosted app without connecting does not count as product use.
+
+## Attribution boundaries
+
+Client dimensions belong to the event's WebSocket connection. A server-global
+"current client" would misattribute simultaneous web, desktop, and mobile use.
+Provider execution has its own events because a turn can outlive the requesting
+connection.
+
+Keep client and server dimensions separate. A desktop host can serve a phone or a
+remote browser, and a direct connection can cross a network. Older clients omit
+metadata. Missing client values must stay unknown rather than being backfilled
+from server properties. The legacy `clientType` property describes how the server
+runs; use `surface` for the connected client.
+
+## Interpreting events
+
+Use `client.turn.requested` for active-use reports. `client.connected` counts
+reconnects, so network behavior can inflate it. One identity can appear in several
+client groups during a period; adding those groups double-counts users.
+
+Provider send and completion counts need not match. Providers can emit synthetic
+turns without a send request. Collection is best effort, with no scan or backfill
+of provider history.
+
+Token totals cover the main agent. Child agents and model rerouting prevent a turn
+from representing one provider/model combination's full cost. For provider
+comparisons, require complete usage, no observed subagents, and no mixed models;
+compare matching model, effort, interaction mode, and terminal status. Aggregate
+output/input ratios should divide the summed totals. Averaging per-turn ratios
+lets small-input turns dominate.
+
+Unknown counts stay absent. Partial usage contains valid observed counts but
+cannot establish a whole-turn total. Keep these distinctions when changing token
+normalization or building reports.
+
+## Collection boundary
+
+Keep analytics payloads to product metadata and normalized measurements. Do not
+send prompts, authentication material, raw provider payloads, user-assigned device
+names, or conversation identifiers. Client metadata is best effort; invalid values
+must not reject a connection. PostHog person profiles remain disabled.
diff --git a/docs/internals/providers.md b/docs/internals/providers.md
index 3baae679de48..6d7582aad8d5 100644
--- a/docs/internals/providers.md
+++ b/docs/internals/providers.md
@@ -1,391 +1,107 @@
-# Provider architecture
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-A provider is the agent runtime that does the actual work. T3 Code supports several, and the
-orchestration layer does not know which one is behind a thread.
-
-## Built-in drivers
-
-[`builtInDrivers.ts`][drivers] exports `BUILT_IN_DRIVERS` with six entries:
-
-| Driver kind   | Driver source                                 |
-| ------------- | --------------------------------------------- |
-| `codex`       | [`Drivers/CodexDriver.ts`][codex]             |
-| `claudeAgent` | [`Drivers/ClaudeDriver.ts`][claude]           |
-| `cursor`      | [`Drivers/CursorDriver.ts`][cursor]           |
-| `grok`        | [`Drivers/GrokDriver.ts`][grok]               |
-| `opencode`    | [`Drivers/OpenCodeDriver.ts`][opencode]       |
-| `antigravity` | [`Drivers/AntigravityDriver.ts`][antigravity] |
-
-Each driver declares its `driverKind`, a `configSchema`, and a `create` function that builds an
-adapter in a child scope. Adapter implementations live beside them in
-`apps/server/src/provider/Layers/` (`CodexAdapter.ts`, `ClaudeAdapter.ts`, and so on) and conform to
-[`ProviderAdapter.ts`][adapter]. Read the driver plus its adapter to see how a specific agent's
-transport, config, and event shapes are mapped.
-
-## Runtime context
-
-Every adapter uses `apps/server/src/provider/RuntimeInstructions.ts` to identify T3 Code and
-the harness, and describe Markdown image/video embeds. Codex includes it in developer
-instructions; Claude appends it to its system preset; OpenCode sends it in each prompt's
-`system` field. Cursor, Grok, and Antigravity append a separate text block to ACP prompts,
-which have no system-message field. This does not change the stored user message.
-
-Per-turn context includes the current model when known. Codex includes reasoning effort;
-Grok includes it when explicitly selected for the turn. Claude's session-level context omits model and effort because they can
-change during a session. OpenCode variants are not assumed to be reasoning-effort levels.
-
-## Codex async questions
-
-Codex 0.153 exposes `request_user_input_async` through `item/started` and `item/completed`
-notifications. The item has `type: "agentMessage"`, `delivery: "async"`, and a `questions` array.
-Each question has a `title` and an optional `options` array of strings. The tool returns `{"accepted":true}`
-without waiting. This is separate from the `item/tool/requestUserInput` server request.
-See the [Codex tool handler](https://github.com/openai/codex/blob/d979df154cf60e13eafb5453e75b6d84f21c67bf/codex-rs/core/src/tools/handlers/request_user_input_async.rs).
-
-The Codex adapter maps completed question items to `user-input.requested` with
-`responseMode: "message"` and stable request and event IDs. Questions use the existing web,
-desktop, and mobile panels. They stay pending while the turn runs and after it finishes.
-
-The engine reads the request's latest stored activity before deciding a reply. This works after
-startup, when the command snapshot has no activities, and after a resolution leaves the recent
-activity window. The query returns one activity, not the full thread history.
-
-For these requests, the decider saves the resolution and a user message in one transaction.
-The standard turn path delivers the message, including session resume and active-turn input.
-It does not send a JSON-RPC response to Codex. Other providers and blocking Codex questions
-keep their existing response paths.
-
-## Registry and routing
-
-Two registries separate configuration from live processes:
-
-- [`ProviderInstanceRegistry`][instances] keys configured instances by `ProviderInstanceId`. Creating
-  one looks up the driver by `driverKind`, decodes `entry.config` with that driver's schema, opens a
-  child scope, and calls `driver.create`.
-- [`ProviderAdapterRegistry`][registry] resolves an instance ID to its live adapter via
-  `getByInstance`.
-
-[`ProviderService`][service] sits on top. It combines the adapter registry with the provider session
-directory to route session and turn operations for a thread, so callers name a thread, not an agent.
-
-`ProviderService.sendTurn` expands [assistant citations](./assistant-citations.md) into quoted
-reference data before dispatching to any adapter. Bound user comments remain distinct from the quoted
-assistant text. Persisted messages keep their serialized links.
-
-Adding a driver means writing the driver plus adapter and adding it to `BUILT_IN_DRIVERS`. No
-orchestration, contract, or client change is required for the common case.
-
-### Grok health check
-
-`checkGrokProviderStatus` never opens an ACP session. It runs `grok --version`, then `grok models`
-for login state and model slugs, then a single ACP `initialize` and reads models from
-`_meta.modelState`. `authenticate` and `session/new` are skipped on purpose: `authenticate` can open
-a browser login and `session/new` boots every configured MCP server, both of which made background
-probes hang or surprise the user. A failed `initialize` degrades to `warning` with the CLI's model
-list instead of persisting `error` over a working install. The built-in `grok-build` slug is the
-CLI's product name, not an ACP model id. `applyGrokAcpModelSelection` treats it as "keep the
-session's current model" and never sends it in `session/set_model`.
-
-## Antigravity ownership and protocol
-
-[`AntigravityDriver`][antigravity] uses Google's official ACP executable. The instance config
-selects the ACP auth method: `oauth-personal` (default), `oauth-business`, `gemini-api-key`, or
-`agent-platform`. The two OAuth methods share the loopback sign-in flow below. The API key
-methods pass the configured key to the agent as `GEMINI_API_KEY` or `GOOGLE_API_KEY` and never
-open a browser. A GCP project and location are written to the profile's `settings.json` on each
-launch. The driver never reuses CLI credentials or ambient `GOOGLE_*` variables and never falls
-back to another method. Antigravity is disabled by default and supports multiple provider
-instances. The open driver and instance identifiers require no database migration.
-
-### Runtime installation
-
-[`AntigravityInstallation`][antigravity-installation] belongs to the environment, outside
-WebSocket and provider-instance scopes. Instances share an explicit download operation and the
-completed runtime. Client disconnects and instance rebuilds do not cancel installation.
-
-The fixed [release table][antigravity-release] contains official Google URLs, SHA-256 hashes,
-archive sizes, and the exact executable pair for each published host. Downloads stream to disk.
-Lazy `yauzl` entry streams extract only that pair, with member names, types, duplicates, and
-sizes checked. Validation runs ACP `initialize` in a temporary profile without authentication
-or a session. Progress updates are bounded, not sent for every network chunk.
-
-Complete releases live in immutable version directories under the T3 home
-`tools/antigravity-acp/<platform>-<arch>/versions`. An atomic `active.json` change selects the
-release for new processes. Each process holds a version lease until it exits. Updates do not
-replace running executables. Removal refuses active leases or explicit binary paths that still
-reference the managed files. Failure or cancellation removes owned partial files, not the
-previous release or account data.
-
-Resolution order is explicit `binaryPath`, active managed release, then the instance's `PATH`.
-An invalid explicit path fails without fallback. Manual installations are never changed by the
-installer. Every launch pins `ANTIGRAVITY_HARNESS_PATH` to the selected executable's sibling.
-
-### Google profiles and sign-in
-
-Each instance owns a stable profile at
-`<stateDir>/providers/antigravity/<sha256(instanceId)>`.
-[`antigravityAuthSupport.ts`][antigravity-auth-support] sets `GEMINI_HOME` to this directory and
-`AGY_ACP_FORCE_FILE_STORAGE=1` after merging instance environment variables. File storage avoids
-the official macOS keychain entry being shared across instances. Profile directories use mode
-`0700` on POSIX. This is file storage, not an encrypted keychain. Windows uses the host profile's
-filesystem permissions.
-
-The launch environment removes API-key and cloud-billing variables, disables inherited
-environment extension, sets `PYTHONUNBUFFERED=1`, and controls `BROWSER`. A tested Node or
-Electron-as-Node helper prevents the official agent from opening a browser on the environment.
-The same launch factory serves setup, health checks, chat, and text generation.
-
-The official agent prints a non-JSON OAuth line on stderr in version 1.1.1. Earlier versions
-print it on stdout. T3 accepts the exact native prefix on either stream and its browser-helper
-marker on stderr. Fragmented lines are joined and bounded. Other malformed protocol output
-remains fatal. Authorization URLs are validated before use. Other stderr is discarded because
-it can contain OAuth data. Normal work rejects an interactive login request with a
-sign-in-required error instead of waiting for consent. A rejected stderr callback fails pending
-ACP requests and closes the owned process.
-
-[`AntigravityAuth`][antigravity-auth] owns each sign-in process and deadline in the instance
-scope. Only the initiating T3 auth session receives its URL and flow ID or can complete or
-cancel it. Other clients receive busy state without those values. Subscriptions follow
-controller replacement when settings rebuild an instance.
-
-For remote completion, the client sends the full return URL through the typed setup RPC.
-The server validates the pending loopback origin, port, root path, and single matching state
-before forwarding once to the owned listener. It does not probe the listener or follow
-redirects. Google's process owns PKCE, token exchange, refresh, and storage. Callback HTTP
-success is not authentication success. The controller waits for authenticated session setup
-and catalog discovery. Cancellation closes the process instead of sending a synthetic denial.
-
-Auth RPCs `provider.auth.start`, `complete`, `cancel`, `logout`, and `subscribe` require
-`orchestration:operate`. Install `start`, `cancel`, and `remove` use that scope too.
-`provider.install.subscribe` and public provider snapshots require `orchestration:read`.
-[`providerSetup.ts`][provider-setup] defines the operation IDs, states, and safe errors.
-
-Sign-out closes process admission for the instance, stops provider bindings through
-[`ProviderAuthService`][provider-auth-service], then stops owned startup and helper processes.
-A fresh official process calls `initialize` and native `logout` without authenticating.
-Only then does the provider clear auth, models, commands, skills, and workspace metadata.
-Thread history and native session files remain. Settings sign-out and a text-only `/logout`
-use this same path. The command is handled before model prompting or title generation.
-Disabling an instance closes its processes but keeps credentials. Account replacement is
-explicit sign-out followed by sign-in.
-
-### Sessions, models, and client capabilities
-
-[`AntigravityAdapter`][antigravity-adapter] owns one ACP process per active thread. It uses
-native `session/resume` without transcript replay and reapplies the persisted model and
-permission mode after new or resumed setup. An unavailable explicit model fails instead of
-accepting the native default. Steering cancels the previous prompt, waits for its result and
-event drain, then sends the replacement. Native background commands use T3's existing
-background-task state.
-
-The permission mapping is `approval-required` and `auto` to `default`, `auto-accept-edits` to
-`auto_edit`, and `full-access` to `yolo`. Native requests still need replies in `yolo`.
-`interaction_` requests are user questions, not approvals. T3 keeps opaque option IDs in
-`UserInputQuestion.options[].value` and sets `allowCustomAnswer=false`. Both clients preserve
-these values. Ordinary approval replies use only offered option IDs, including `allow_always`
-only when present. Existing providers keep their prior behavior when the optional fields are
-absent.
-
-`showInteractionModeToggle=false` keeps native `/plan` separate from T3 Plan mode.
-`supportsConversationRollback=false` hides unsupported client actions and makes checkpoint
-revert fail before filesystem changes. Checkpoint capture and diffs remain supported.
-
-Automatic status refreshes, reconnects, and workspace checks do not open catalog sessions.
-Health probes use `initialize` only. Disabled instances do not run background probes.
-An explicit `serverRefreshProviders` request with `refreshModels: true` calls the driver's
-optional `refreshModels` operation. Antigravity opens a short-lived catalog session under the
-instance's process admission guard, uses saved credentials, publishes models and commands,
-then closes the process. An interactive login request fails with sign-in required. Web's
-**Refresh provider status** and mobile's **Refresh models** actions request this operation.
-Account access starts unknown and becomes authenticated after successful session setup,
-including an explicit model refresh.
-The [provider snapshot][antigravity-provider] takes models and commands from setup and native
-updates. It preserves returned Gemini model IDs, labels, order, and thinking-level choices.
-ACP `config_option_update` notifications and `session/set_config_option` responses replace
-the instance's model catalog. Child session notifications do not change the root catalog.
-The registry treats a successful empty catalog as authoritative and clears cached metadata
-after sign-out. It must not retain a previous account's models. Cached models do not prove
-current access. The auth response does not supply an email, plan tier, or reliable quota.
-
-Some upstream failures arrive as assistant text followed by `end_turn`. Preserve that message
-without treating model-written text as a structured error or successful task completion.
-
-### Text generation
-
-[`AntigravityTextGeneration`][antigravity-text] implements titles, branch names, commit text,
-and PR text through the same instance and Google sign-in. Each helper uses a temporary empty
-workspace, no injected MCP servers, native `default` mode, and explicit denial of tools and
-questions. Output is bounded, parsed against the existing schemas, and sanitized. Cancellation,
-timeout, and sign-out close the process. Cleanup removes only that helper's verified temporary
-native session files.
-
-The official agent has no verified hard no-tools setting. Global hooks and MCP configuration
-can run before a prompt. Helpers check the profile's `config/hooks.json` and
-`config/mcp_config.json` before launch and reject nonempty, malformed, or oversized
-configuration. `supportsTextGeneration=false` keeps such an instance out of system-model
-pickers. Empty managed profiles are supported. Do not describe prompt-time denial as a native
-sandbox.
-
-## OpenCode server ownership and catalog
-
-Each OpenCode provider instance owns one lazy local server for catalog discovery and
-text-generation helpers through [`OpenCodeServerOwner.ts`][opencode-server-owner]. Concurrent
-borrowers share startup. The server closes 30 seconds after the last borrower releases it, or
-when the provider instance closes. A failed or exited process can be started again on the next
-use. An externally configured OpenCode server remains externally owned.
-
-The local server and its SDK clients use one resolved password. An explicit provider password
-overrides `OPENCODE_SERVER_PASSWORD` in the spawned environment. Without an explicit password,
-the client uses the password from the environment that the process inherits. External servers use
-only their explicit provider password and never inherit the host's local password.
-
-Every server connection must pass the authenticated `/global/health` check before inventory or
-session operations start. The response must contain a valid version at or above 1.14.19. Local
-owners cache this result for the lifetime of the spawned process. External actions check once when
-they create their server connection, not for each model or SDK request.
-
-Chat adapters keep their own server per thread. They register a thread-specific `t3-code` MCP
-connection, while OpenCode stores MCP connections by directory. Sharing these chat servers
-without changing MCP routing would let two threads in one directory replace each other's
-connection.
-
-Chat adapters send the runtime mode as a session ruleset, but upstream OpenCode evaluates
-doom-loop and subagent asks against the agent ruleset only. In full access the adapter answers
-those asks itself so the user never sees an approval they already granted. It replies `once`
-rather than `always` because OpenCode stores `always` grants per directory, and on a shared
-external server that would widen what a supervised thread in the same directory may do.
-
-OpenCode loads its catalog through the HTTP API when an enabled provider instance starts. The
-provider registry keeps the snapshot in memory and persists it in the existing per-instance cache.
-Each `subscribeServerConfig` connection refreshes all providers, so a client reconnect reloads the
-OpenCode catalog from the current helper. The `serverRefreshProviders` request also refreshes it.
-Periodic OpenCode probes remain disabled. OpenCode reads credentials for each inventory request,
-but its native configuration files can remain cached for the lifetime of the helper process. The
-helper closes 30 seconds after its last inventory or text-generation borrower releases it. A
-refresh after that idle period starts a new helper and reads file changes. Repeated refreshes and
-active text-generation work can extend process reuse. Changes to the provider configuration or
-environment replace the instance and start a new discovery. Changes to unrelated settings only
-update snapshot enrichment. Other providers retain their existing refresh policy.
-
-T3 Code does not own an external OpenCode process. Native configuration changes there can require
-an external reload or restart before T3 Code's next refresh sees them.
-
-The shared server's idle shutdown does not clear the catalog. Failed discovery keeps the last
-known models, slash commands, and skills through the registry's existing merge rules. A successful
-empty inventory is authoritative. Existing threads keep their explicit model identifier and
-options when catalog metadata is missing; the catalog is not permission to choose a different
-model for a thread.
-
-## Model manifest
-
-The model picker's legacy section is driven by `apps/server/src/provider/model-manifest.json`, which
-lists the current (non-legacy) model slugs per driver kind. The `ModelManifest` service
-(`apps/server/src/provider/ModelManifest.ts`) refreshes that data from the same file on `main` via
-raw.githubusercontent.com, so moving a model in or out of the legacy section is a commit, not a
-release. Preference order is remote fetch, then the on-disk copy of the last successful fetch (in
-the state directory), then the bundled copy. Fetches are TTL-gated, run concurrently with provider
-probes, respect the `enableProviderUpdateChecks` setting, and never fail a provider check. The
-Codex and Claude drivers apply the classification to every snapshot with `applyModelManifest`;
-driver kinds absent from the manifest have no legacy concept.
-
-## Attachment access
-
-The server stores uploaded attachments in its attachment directory, outside the project workspace.
-`ProviderService` adds the absolute path of each attachment to the turn text, then passes every
-attachment to the provider adapter. Each adapter decides what its provider ingests natively:
-
-- Codex, Claude, Cursor, and Grok send images as native image inputs and skip generic files. For
-  these providers, generic files reach the agent only as file paths in the turn text.
-- Antigravity sends BMP, JPEG, PNG, and WebP images and common audio formats as native blocks,
-  text files as embedded resources, and PDFs as resource links. Other files are rejected with an
-  error instead of being dropped. The session advertises the ACP client file system capability,
-  so workspace reads and writes come back through `fs/read_text_file` and `fs/write_text_file`
-  and are confined to the workspace and the attachments directory.
-- OpenCode sends PNG/JPEG/GIF/WebP images, text files, and PDFs up to 20 MB as native file parts
-  with their real mime type. Everything else (ZIP and other binaries, image formats model APIs
-  reject, oversized files) falls back to the file path in the turn text, like the other providers.
-- Antigravity sends BMP/JPEG/PNG/WebP images as native image blocks, UTF-8 text as embedded
-  resources, and PDFs as local resource links. Text is limited to 1 MiB per file, images to
-  10 MiB each, and all attachments to 50 MiB per turn. Unsupported formats or oversized inputs
-  fail explicitly. Native path permissions still apply to PDFs.
-
-Claude receives the attachment directory as an allowed additional directory. Codex keeps its
-configured sandbox policy, so access depends on that policy and the selected runtime mode. OpenCode
-allows all paths in full-access mode and requests approval for directories outside the workspace in
-restricted modes. Cursor and Grok use their own provider permission rules.
-
-The server does not copy attachments into a project or bypass provider approval rules. If an agent
-cannot read an attachment, the user must approve the access or select a runtime mode that permits it.
-
-Updated attachment schemas tolerate unknown attachment members, but old image-only clients still
-cannot decode messages that contain file attachments. Client file-picking rollouts must account for
-this limit.
-
-Do not run an old image-only server against state that contains file attachments. Replay decodes
-each persisted event before projection. A file-bearing event can make `ProjectionPipeline` bootstrap
-and `OrchestrationEngine` startup fail for the entire environment, not only the affected thread.
-
-## How provider work is requested
-
-Clients never call a provider directly. They dispatch orchestration commands over the RPC method
-`orchestration.dispatchCommand`, defined with the rest of the orchestration surface in
-[`orchestration.ts`][contracts]. The client-dispatchable provider-facing commands are
-`thread.turn.start`, `thread.turn.interrupt`, `thread.approval.respond`,
-`thread.user-input.respond`, `thread.checkpoint.revert`, and `thread.session.stop`, plus the mode
-setters `thread.runtime-mode.set` and `thread.interaction-mode.set`.
-
-The engine persists an event for the command, and a server-side reactor performs the provider call.
-Provider output comes back as internal commands such as `thread.message.assistant.delta` and
-`thread.session.set`, which clients observe through `orchestration.subscribeThread`. See
-[overview.md](./overview.md) for the command/event loop.
-
-## Server-side workers
-
-Provider work flows through three queue-backed workers. All three are built with
-`makeDrainableWorker` from [`DrainableWorker.ts`][worker] and expose `drain` for deterministic test
-synchronization.
-
-1. [`ProviderRuntimeIngestion`][ingest] consumes provider runtime streams and emits orchestration
-   commands.
-2. [`ProviderCommandReactor`][cmd] reacts to orchestration intent events and dispatches provider
-   calls.
-3. [`CheckpointReactor`][checkpoint] captures workspace checkpoints on turn start and completion, and
-   performs reverts.
-
-### Buffered assistant delivery
-
-A thread in `buffered` assistant delivery mode accumulates assistant text instead of streaming each
-delta. The buffer is not held until turn completion. In [`ProviderRuntimeIngestion`][ingest],
-`MAX_BUFFERED_ASSISTANT_CHARS` is 24,000: the append that would exceed it invalidates the buffer and
-spills the whole accumulated text as one delta. The buffer also flushes at interaction boundaries,
-when a request opens (approval) or user input is requested, via
-`flushBufferedAssistantMessagesForTurn`.
-
-[drivers]: ../../apps/server/src/provider/builtInDrivers.ts
-[codex]: ../../apps/server/src/provider/Drivers/CodexDriver.ts
-[claude]: ../../apps/server/src/provider/Drivers/ClaudeDriver.ts
-[cursor]: ../../apps/server/src/provider/Drivers/CursorDriver.ts
-[grok]: ../../apps/server/src/provider/Drivers/GrokDriver.ts
-[opencode]: ../../apps/server/src/provider/Drivers/OpenCodeDriver.ts
-[antigravity]: ../../apps/server/src/provider/Drivers/AntigravityDriver.ts
-[antigravity-adapter]: ../../apps/server/src/provider/Layers/AntigravityAdapter.ts
-[antigravity-provider]: ../../apps/server/src/provider/Layers/AntigravityProvider.ts
-[antigravity-installation]: ../../apps/server/src/provider/AntigravityInstallation.ts
-[antigravity-release]: ../../apps/server/src/provider/antigravityRelease.ts
-[antigravity-auth]: ../../apps/server/src/provider/AntigravityAuth.ts
-[antigravity-auth-support]: ../../apps/server/src/provider/antigravityAuthSupport.ts
-[antigravity-text]: ../../apps/server/src/textGeneration/AntigravityTextGeneration.ts
-[provider-auth-service]: ../../apps/server/src/provider/Layers/ProviderAuthService.ts
-[provider-setup]: ../../packages/contracts/src/providerSetup.ts
-[opencode-server-owner]: ../../apps/server/src/provider/OpenCodeServerOwner.ts
-[adapter]: ../../apps/server/src/provider/Services/ProviderAdapter.ts
-[instances]: ../../apps/server/src/provider/Services/ProviderInstanceRegistry.ts
-[registry]: ../../apps/server/src/provider/Services/ProviderAdapterRegistry.ts
-[service]: ../../apps/server/src/provider/Layers/ProviderService.ts
-[contracts]: ../../packages/contracts/src/orchestration.ts
-[worker]: ../../packages/shared/src/DrainableWorker.ts
-[ingest]: ../../apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
-[cmd]: ../../apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
-[checkpoint]: ../../apps/server/src/orchestration/Layers/CheckpointReactor.ts
+# Provider constraints
+
+Orchestration records intent and state without knowing which provider runs a thread. Provider
+protocols, account ownership, permissions, and capabilities belong at the
+[adapter boundary](../../apps/server/src/provider/Services/ProviderAdapter.ts). Normalize there
+instead of spreading provider checks through reactors and clients.
+
+A driver kind identifies an integration; an instance identifies one configuration and account
+lifecycle. Route work by instance, so two accounts using the same driver do not share mutable
+session or catalog state.
+
+## Process and account isolation
+
+T3-managed OpenCode chat uses one server per thread. Its MCP registrations are directory-scoped, while
+T3's MCP connection is thread-scoped. Sharing a chat server between threads in one directory would
+let them replace each other's connection. Catalog and text-generation work can share the
+[instance-owned helper](../../apps/server/src/provider/OpenCodeServerOwner.ts), which closes
+after an idle period. External OpenCode servers remain externally owned and can require an
+external restart to pick up configuration changes.
+
+OpenCode also stores persistent approval grants per directory. Automatic full-access replies use
+`once` so they cannot widen a supervised thread's permissions on a shared external server.
+See the [adapter](../../apps/server/src/provider/Layers/OpenCodeAdapter.ts).
+
+Antigravity separates account profiles per instance while sharing installed executables across the
+environment. It forces file-based credential storage because the native macOS keychain entry would
+otherwise be shared across instances. The launch environment removes ambient Google credentials,
+so an instance cannot silently use another account or billing project.
+See [profile isolation](../../apps/server/src/provider/antigravityAuthSupport.ts).
+
+The [Antigravity installer](../../apps/server/src/provider/AntigravityInstallation.ts) outlives
+client connections and provider-instance rebuilds. Releases are immutable, with an atomic pointer
+selecting the version for new processes. Running processes hold leases on their version. Updates
+and removal must respect those leases instead of replacing executables under a running agent.
+
+## Setup must not happen as a health-check side effect
+
+Opening a provider session can start MCP servers, run hooks, or launch a login browser.
+[Grok probes](../../apps/server/src/provider/Layers/GrokProvider.ts) avoid authentication and
+session creation for this reason. Antigravity likewise reserves authenticated catalog sessions for
+explicit setup or model refresh; background checks use initialization only.
+
+[Antigravity sign-in](../../apps/server/src/provider/AntigravityAuth.ts) belongs to the initiating
+T3 auth session. The client carries the return URL back to the environment because the provider's
+loopback listener may be on another machine. Forward only the callback for the owned pending flow;
+a successful callback HTTP request is not proof that provider authentication finished. The native
+process owns token exchange and storage.
+
+Antigravity sign-out closes admission to new processes and stops existing processes before clearing account
+metadata. Otherwise a helper or resumed session could retain the old account. Cached model lists
+do not establish current access, and an authoritative empty catalog must clear the old list.
+
+Antigravity text-generation helpers deny tool requests, but native hooks and MCP configuration can
+run before the prompt. They reject profiles with such configuration before launch. Prompt
+instructions and tool denial do not create a native sandbox.
+See [helper constraints](../../apps/server/src/textGeneration/AntigravityTextGeneration.ts).
+
+## Provider updates run only through the owning installer
+
+A one-click update is offered only when the resolved executable's path proves which installer owns
+it. Homebrew and npm are proven by the real path (symlinks followed): a versioned keg or cask under
+`brew --prefix`, or `<prefix>/lib/node_modules/<pkg>/` (Windows: the shim beside `node_modules`).
+Native installer layouts and the global bin directories of pnpm, Bun, and Vite+ may match on either
+the resolved path or its real target, since those installers place real files or their own symlinks
+there. Anything unproven stays manual-only but still reports the version gap. npm updates pin
+`--prefix` because the `npm` on `PATH` can belong to a different Node than the one that owns the
+provider. Homebrew
+compares against `brew info` since casks trail npm by hours; native installs share npm's version
+train, so the registry stays authoritative for them.
+See the [resolver](../../apps/server/src/provider/providerMaintenance.ts).
+
+Ownership is cached per instance and re-read immediately before an update runs. The
+[runner](../../apps/server/src/provider/providerMaintenanceRunner.ts) refuses when the lock key
+changed since the advisory, and reports success only when the refreshed provider is still installed
+with a readable, current version.
+
+## Protocol traps
+
+Codex async questions arrive as notifications and are answered with a new user message. There is
+no pending RPC response to send. Blocking questions still use the request/response path. The
+[adapter](../../apps/server/src/provider/Layers/CodexAdapter.ts) distinguishes them; the
+[decider](../../apps/server/src/orchestration/decider.ts) records an async answer and its user
+message together.
+
+An async question can outlive the turn or a server restart. The engine reads that request's
+durable activity before resolving it because the in-memory command snapshot omits old activities.
+Do not infer that a request has disappeared merely because it is outside the recent window.
+
+Capabilities must describe what the provider can actually do. Antigravity can capture workspace
+checkpoints but cannot roll back its conversation. The [checkpoint boundary](./overview.md#turn-completion-and-checkpoints)
+therefore rejects revert before touching files. Native permission and question option IDs must
+also survive normalization; a display label is not necessarily a valid reply.
+
+## Attachments and stored history
+
+Attachments live outside the project workspace. [ProviderService](../../apps/server/src/provider/Layers/ProviderService.ts)
+puts their environment-local paths in turn input and lets adapters choose native input formats.
+A path in the prompt does not grant filesystem access. Keep provider sandbox and approval rules
+in force; copying uploads into the project to bypass them changes that boundary.
+
+File attachments introduced a replay compatibility limit. Image-only clients cannot decode
+file-bearing messages, and an image-only server can fail the entire environment's startup when
+replaying one such event. Rollouts and downgrades must account for persisted history as well as
+current client support.
+
+Model classification has its own [manifest constraints](./model-manifest.md). Assistant-reference
+handling is documented under [citations](./assistant-citations.md).
diff --git a/docs/internals/remote.md b/docs/internals/remote.md
index d27a0741c2ad..2faf1e930eef 100644
--- a/docs/internals/remote.md
+++ b/docs/internals/remote.md
@@ -1,256 +1,59 @@
-# Remote Architecture
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-Remote environments are shipped, not planned. Direct, bearer-paired, relay-tunneled, Tailscale, and
-desktop-managed SSH access all exist today. This document describes the model they share and where
-each piece lives. For the user-facing setup guide see
-[remote access](../user/remote-access.md).
-
-## The model
-
-T3 has one runtime boundary: a client talks to a T3 server over HTTP and WebSocket, and the server
-owns orchestration, providers, terminals, git, and filesystem operations. Remoteness is expressed at
-the connection layer, never by splitting the runtime.
-
-```text
-┌──────────────────────────────────────────────┐
-│ Client (desktop / mobile / web)              │
-│  known environments, connection supervisor   │
-└───────────────┬──────────────────────────────┘
-                │ resolves one access endpoint
-┌───────────────▼──────────────────────────────┐
-│ Access method                                │
-│  direct ws/wss, relay tunnel,                │
-│  Tailscale serve, desktop-managed ssh        │
-└───────────────┬──────────────────────────────┘
-                │ connects to one T3 server
-┌───────────────▼──────────────────────────────┐
-│ Execution environment = one T3 server        │
-│  identity, providers, projects/threads,      │
-│  terminals, git, filesystem                  │
-└──────────────────────────────────────────────┘
-```
-
-### ExecutionEnvironment
-
-One running T3 server instance. It owns provider availability and auth, model availability, projects
-and threads, terminal processes, filesystem access, git operations, and server settings.
-
-It is identified by a stable `environmentId`, persisted by the server at `<stateDir>/environment-id`
-and generated on first start (`apps/server/src/environment/ServerEnvironment.ts`). Desktop, mobile,
-and web all reason about the same concept.
-
-Initialization publishes a complete ID atomically. Empty or whitespace-only ID files are repaired
-using a retained `<stateDir>/environment-id.recovery` file so concurrent and delayed repairs choose
-the same ID. Existing nonempty ID files remain authoritative.
-
-### Known environments and connection targets
-
-A saved client-side entry for an environment the client knows how to reach. It is not
-server-authored; it is local to a device or client profile. In the hosted web app these entries are
-browser-local. A hosted pairing URL can create one, but it does not give the hosted app a server-side
-control plane or a copy of session state.
-
-[`connection/model.ts`][model] defines four target tags, which are the real access taxonomy:
-
-| Target                    | Used for                                                                 |
-| ------------------------- | ------------------------------------------------------------------------ |
-| `PrimaryConnectionTarget` | The platform-managed local server (desktop backend, CLI-served web app). |
-| `BearerConnectionTarget`  | Any manually paired endpoint reached over direct HTTP/WebSocket.         |
-| `RelayConnectionTarget`   | Managed T3 Connect relay tunnels.                                        |
-| `SshConnectionTarget`     | Desktop-managed SSH environments.                                        |
-
-Bearer, relay, and SSH are persisted; primary is platform-managed. Note that Tailscale is not a
-separate target kind. A Tailscale URL is paired through the ordinary bearer path in
-[`onboarding.ts`][onboarding] (`preparePairingRegistration`), which accepts either a pairing URL or a
-host plus pairing code. Tailscale is an endpoint provider and transport, not a distinct runtime
-concept.
-
-### AdvertisedEndpoint
-
-A server- or desktop-authored candidate endpoint for an environment: a concrete HTTP and WebSocket
-base URL pair, a default/available/unavailable marker, reachability hints (loopback, LAN, private,
-public, tunnel), and compatibility hints such as whether the hosted HTTPS app can use it.
-
-Clients treat advertised endpoints as hints, not proof that a route works from the current device.
-The connection attempt decides.
-
-The UI shows one default endpoint in the network-access summary and keeps the rest behind an advanced
-list. `selectPairingEndpoint` in
-[`ConnectionsSettings.tsx`](../../apps/web/src/components/settings/ConnectionsSettings.tsx) excludes
-unavailable endpoints and then picks, in order:
-
-1. the saved `defaultEndpointKey` override;
-2. the first endpoint marked `isDefault`;
-3. the first endpoint whose reachability is not `loopback`;
-4. the first endpoint compatible with the hosted HTTPS app;
-5. otherwise nothing.
-
-There is no unconditional loopback fallback. A loopback endpoint only wins through an explicit saved
-override or `isDefault`. Persist the override by stable endpoint kind rather than raw URL where
-possible, since LAN addresses change with networks; Tailscale endpoints use provider-specific stable
-keys (`tailscale-ip:`, `tailscale-magicdns:`).
-
-### Endpoint providers
-
-Endpoint providers contribute advertised endpoints without becoming part of the core environment
-model: core owns environments, pairing, and connection lifecycle, and providers return normalized
-`AdvertisedEndpoint` records.
-
-Tailscale is the first provider, and T3 manages more than discovery. When `tailscaleServeEnabled` is
-set, the server acquires a Tailscale serve mapping for its actual listening port at startup with
-`ensureTailscaleServe` and releases it with `disableTailscaleServe` on scope close
-(`apps/server/src/server.ts`, using [`@t3tools/tailscale`](../../packages/tailscale/src/tailscale.ts)).
-Endpoint identifiers are synthesized in `apps/desktop/src/backend/tailscaleEndpointProvider.ts` with
-`private-network` reachability.
-
-### Hosted pairing request
-
-A hosted pairing request is a bootstrap URL for the static web app, not a transport:
-
-```text
-https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
-```
-
-The hosted app reads `host`, takes the token from the URL hash, exchanges it directly with that
-backend, strips the token from browser history, and saves the environment record locally. Helpers
-live in [`shared/remote.ts`](../../packages/shared/src/remote.ts) (`setPairingTokenOnUrl`,
-`getPairingTokenFromUrl`, `stripPairingTokenFromUrl`) and `apps/web/src/hostedPairing.ts`.
-
-Constraints:
-
-- the hosted app does not proxy HTTP or WebSocket traffic;
-- the backend must be directly reachable from the browser;
-- HTTPS pages can only reach HTTPS/WSS backends;
-- HTTP LAN endpoints keep using direct desktop or CLI pairing URLs;
-- the token belongs in the hash so it is never sent to the hosted app origin.
-
-### RepositoryIdentity and Project
-
-`RepositoryIdentity` is a best-effort logical repo grouping across environments, used for UI grouping
-and correlation only, never for routing. `Project` remains environment-local: a local clone and a
-remote clone are different projects that may share a `RepositoryIdentity`, and threads bind to one
-project in one environment.
-
-## Access methods
-
-Access answers one question: how does the client speak WebSocket to a T3 server? It does not answer
-how the server got started or who manages the process.
-
-### Direct WebSocket access
-
-`wss://t3.example.com` or `ws://10.0.0.15:3773`, paired as a bearer target. This is the base model.
-It works for desktop, mobile, and web with no client-side process management. Browser security rules
-are part of it: a hosted HTTPS client cannot connect to plain `ws://` or `http://` LAN backends.
-
-### Relay-tunneled access
-
-Managed T3 Connect relay tunnels use `RelayConnectionTarget` and are the answer when the host is
-behind NAT, inbound ports are unavailable, or mobile must reach a desktop-hosted environment. From
-the client's perspective this is still an ordinary WebSocket connection; the route is mediated. The
-relay Worker only brokers credentials and a managed endpoint; application traffic then flows over
-the provisioned Cloudflare tunnel hostname for the life of the connection, not through the relay
-Worker itself. See [t3-connect.md](./t3-connect.md).
-
-### Tailscale access
-
-A T3-managed `tailscale serve` mapping exposes the server on the tailnet over HTTPS, and the
-resulting private-network endpoints are advertised for pairing. Connection then follows the ordinary
-bearer path.
-
-### Desktop-managed SSH access
-
-SSH is an access and launch helper, not a separate environment type. `DesktopSshEnvironment`
-([apps/desktop/src/ssh/DesktopSshEnvironment.ts][sshenv]) exposes `discoverHosts`,
-`ensureEnvironment`, and `disconnectEnvironment`. It discovers targets from SSH config and known
-hosts, owns password/askpass prompts, and delegates lifecycle to `SshEnvironmentManager` in
-[packages/ssh/src/tunnel.ts][sshtunnel], which resolves the target, launches or reuses the remote T3
-server, opens a local tunnel, checks HTTP readiness, optionally issues a remote pairing token, and
-returns local HTTP/WS endpoints. Disconnect closes the tunnel and stops the remote server if the
-launcher started it; a server that was already running (marked `external`) is left running.
-
-The desktop main process owns this because it can spawn SSH, manage prompts, write launch scripts,
-and clean up forwards. The renderer connects through the forwarded URL like any other environment and
-needs no SSH-specific RPC path.
-
-Failure handling is explicit: SSH auth failure surfaces before an environment is saved, remote launch
-failure includes launcher output where available, forwarded-port failure leaves the environment
-disconnected rather than falling back to an unrelated endpoint, and reconnect restores the SSH bridge
-before reconnecting the WebSocket client.
-
-## Launch methods
-
-Launch answers a different question: how does a T3 server come to exist on the target machine? Keep
-it separate from access.
-
-- **Pre-existing server.** The operator already runs T3 and the client connects directly or through a
-  tunnel.
-- **Desktop-managed remote launch over SSH.** Desktop probes the machine, launches or reuses a remote
-  server, forwards a port, and the renderer connects normally. The saved environment records that it
-  came from SSH launch for reconnect and lifecycle UX only; that metadata never changes the protocol
-  or the identity model.
-- **Client-managed local publish.** A local server is published through the relay with
-  `t3 connect link`, exposing a desktop-hosted environment to mobile without router or firewall
-  changes.
-
-The same `ExecutionEnvironment` can be reached several of these ways. Only the launch and access
-paths differ.
-
-## Security model
-
-Some environments are reachable over untrusted networks, so remote-capable environments require
-explicit authentication, tunnel exposure never relies on obscurity, and saved endpoints carry enough
-auth metadata to reconnect safely.
-
-WebSocket authentication is a dedicated short-lived ticket, not a token in a query string. The client
-presents its long-lived bearer or DPoP credential in HTTP headers to
-`POST /api/auth/websocket-ticket` ([authorization/remote.ts][authremote]), and appends only the
-returned ticket as `wsTicket` on the socket URL. The server issues it through
-`EnvironmentAuth.issueWebSocketTicket`; tickets are tagged `kind: "websocket"` and default to a
-five-minute TTL (`DEFAULT_WEBSOCKET_TOKEN_TTL` in `apps/server/src/auth/SessionStore.ts`). The
-handshake verifies the ticket, and each RPC method still enforces its own scope. See
-[environment-auth.md](./environment-auth.md).
-
-Hosted pairing is 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 reachable from an HTTPS browser context.
-
-## Version coordination
-
-Remote environments stay online while clients move to newer releases. The environment descriptor
-carries the running server version and may advertise a safe replacement path, so the UI can show the
-right action without making the transport responsible for process management. The connection
-supervisor owns the resulting disconnect and reconnect like any other involuntary close. See
-[server-updates.md](./server-updates.md).
-
-## Machine identity
-
-Every environment is drawn with one of a fixed set of machine glyphs (`EnvironmentMachineKind` in
-contracts: server, cloud, desktop, laptop, mac-mini, mac-studio). Two inputs feed it, and the
-precedence lives in one helper, `resolveEnvironmentMachineKind`, so web and mobile cannot drift:
-
-1. `settings.environmentIcon`, a nullable server setting the user picks in Settings → Connections.
-   It is server state rather than client state so every device connecting to that server agrees.
-2. `environment.platform.machine`, detected once at startup by [ServerEnvironmentMachine.ts][machine]
-   (IOKit product name / `hw.model` on macOS, `/sys/class/dmi/id` on Linux with virtualization
-   markers mapped to "cloud"). Absent when there is no signal, so older servers, Windows hosts, and
-   containers decode without it.
-3. A generic server otherwise.
-
-Clients treat the field like any other capability: absent means "use the fallback", never "wait".
-
-## Future work
-
-These remain unbuilt and are listed to keep the model honest:
-
-- third-party tunnel products as additional endpoint providers;
-- a relay-hosted OAuth callback broker (see [t3-connect.md](./t3-connect.md));
-- richer multi-environment UI beyond the current connections list.
-
-[model]: ../../packages/client-runtime/src/connection/model.ts
-[onboarding]: ../../packages/client-runtime/src/connection/onboarding.ts
-[authremote]: ../../packages/client-runtime/src/authorization/remote.ts
-[sshenv]: ../../apps/desktop/src/ssh/DesktopSshEnvironment.ts
-[sshtunnel]: ../../packages/ssh/src/tunnel.ts
-[machine]: ../../apps/server/src/environment/ServerEnvironmentMachine.ts
+# Remote architecture
+
+Each connection joins a client to one environment over HTTP and WebSocket. The
+environment owns providers, execution, files, and durable state. Direct access,
+Tailscale, SSH, and T3 Connect change how the client reaches that server; they do
+not introduce another execution model. See
+[remote access](../user/remote-access.md) for setup.
+
+## Identity is independent of the route
+
+An environment keeps its ID across server restarts and endpoint changes. Saved
+connections are local to a client profile; the server's identity and state are
+not. A repository identity can correlate clones across environments, but never
+routes work between them. A project and its threads belong to one environment.
+
+[Environment ID initialization](../../apps/server/src/environment/ServerEnvironment.ts)
+must publish a complete ID atomically. Repair of an empty ID file retains a
+recovery file so concurrent or delayed initializers choose the same winner.
+Removing that recovery state as ordinary temporary-file cleanup can change the
+identity underneath an already-running server.
+
+Advertised endpoints are reachability hints. Only the connecting device can
+prove that a route works. In particular, a host's loopback address refers to a
+different machine when another device opens it. Endpoint selection must not
+silently fall back to loopback when a shareable endpoint is unavailable.
+
+## Hosted web is a client
+
+The hosted web app stores its connection catalog in the browser and connects
+directly to each environment. It does not proxy traffic or hold server-side
+pairing state. Hosting the UI over HTTPS therefore cannot make a plain HTTP LAN
+backend accessible from that browser context.
+
+A [hosted pairing URL](../../apps/web/src/hostedPairing.ts) identifies the backend
+in its query and carries the pairing secret in its fragment. Fragments stay out
+of requests to the hosted origin. The browser exchanges the secret with the
+environment and strips it from its history. Moving the token into a query
+parameter would disclose it to the wrong origin.
+
+## Access and process ownership are different
+
+Tailscale supplies an endpoint for ordinary pairing, so it needs no separate
+environment type. Authentication remains the environment's responsibility for
+every route. See [environment authentication](./environment-auth.md) and the
+[T3 Connect trust boundary](./t3-connect.md).
+
+SSH can launch a server as well as forward a port. Desktop main owns that
+lifecycle because it can spawn SSH and handle authentication prompts. The
+renderer uses the forwarded endpoint through the shared connection runtime.
+[SSH cleanup](../../packages/ssh/src/tunnel.ts) stops a remote server only if the
+launcher owns it; a server it discovered already running must survive a client
+disconnect. Reconnection restores the forward before opening the application
+transport.
+
+Remote servers can outlive several client releases. Clients must use advertised
+capabilities and handle their absence, rather than assume their own version
+describes the server. Process replacement belongs to the launcher's
+[update protocol](./server-updates.md); the connection runtime handles the
+resulting disconnect.
diff --git a/docs/internals/resource-telemetry.md b/docs/internals/resource-telemetry.md
index 0f3e6674ff79..3ce3a6071948 100644
--- a/docs/internals/resource-telemetry.md
+++ b/docs/internals/resource-telemetry.md
@@ -1,394 +1,50 @@
-# Resource telemetry architecture
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-Status: implemented
-
-## Purpose
-
-Resource telemetry replaces recurring `ps`, PowerShell, `ioreg`, and `pmset`
-subprocess probes with two persistent, direct data sources:
-
-1. a standalone Rust resource-monitor executable that reads process counters
-   through operating-system APIs via `sysinfo`;
-2. Electron main-process APIs for Electron process metrics and host power state.
-
-The native monitor owns bounded in-memory history. The server only merges and
-summarizes that history when diagnostics requests it. Telemetry history is not
-persisted to disk or continuously copied into Node.
-
-## Why a standalone executable
-
-The monitor is intentionally not a Node native addon.
-
-- No N-API, `ffi-rs`, or dynamic-library ABI is loaded into the server process.
-- A monitor crash cannot corrupt the Node runtime.
-- The server can supervise, restart, version-check, and measure the monitor as a
-  normal child process.
-- The same protocol works for the desktop app and the published CLI.
-- Packaging is a single platform executable instead of an addon toolchain plus
-  Node/Electron ABI matrix.
-
-The cost is one persistent child process and NDJSON serialization. That is a
-better failure boundary than repeatedly spawning shell utilities or loading
-native code into Node.
-
-## Runtime topology
-
-### Desktop
-
-```text
-Electron main
-  ├─ powerMonitor
-  ├─ app.getAppMetrics() while diagnostics is open
-  ├─ inherited fd 4, telemetry NDJSON ─────────────┐
-  └─ inherited fd 5, demand-control NDJSON ◀──────┤
-                                                   ▼
-Node server ── stdin/stdout NDJSON ── Rust resource monitor
-     │
-     ├─ ResourceTelemetry Effect service
-     ├─ background power policy projection
-     └─ WebSocket RPC/subscription ── diagnostics UI
-```
-
-### Web, headless, and remote server
-
-Electron telemetry is unavailable. The native monitor still runs beside the
-server and tracks the server process tree. Power fields degrade to `unknown`
-instead of invoking platform shell commands.
-
-### WSL backend limitation
-
-Windows desktop packages currently ship the Windows resource-monitor executable.
-That executable cannot run inside the Linux WSL backend, so a WSL-only backend
-does not receive `resourceMonitorPath` and reports native process telemetry as
-unavailable. Electron host-power telemetry remains available over the inherited
-desktop pipe. Supporting native WSL process telemetry requires publishing a
-Linux sidecar for each supported architecture in the Windows artifact and
-converting its packaged path into the selected distro; the configuration
-deliberately does not pass the Windows `.exe` into WSL as a false fallback.
-
-## Native monitor
-
-The executable lives in `native/resource-monitor`.
-
-It receives schema-compatible commands on stdin and emits one JSON object per
-line on stdout:
-
-- `configure`
-- `setExternalProcesses`
-- `setSampleInterval`
-- `setStreaming`
-- `sampleNow`
-- `readHistory`
-- `shutdown`
-- `hello`
-- `snapshot`
-- `historyChunk`
-- `error`
-
-The protocol version is defined by
-`RESOURCE_MONITOR_PROTOCOL_VERSION` in
-`packages/contracts/src/resourceTelemetry.ts`.
-
-### Collection
-
-The monitor keeps one `sysinfo::System` instance and refreshes it at the
-power-adaptive interval selected by the server. It collects:
-
-- PID and parent PID;
-- process start time and run time;
-- process name and command line;
-- current and cumulative CPU usage;
-- resident and virtual memory;
-- cumulative process I/O counters.
-
-On Linux, task/thread enumeration is disabled. Command lines are refreshed with
-each sample so process replacements remain visible. Disabling task enumeration
-avoids walking every `/proc/<pid>/task/<tid>` directory on each refresh.
-
-### Process-tree selection
-
-Each sample scans the accessible process table, builds the PID/PPID graph, and
-retains:
-
-- the server process;
-- every descendant of the server, including provider-spawned grandchildren such
-  as shells, `node`, `tsgo`, language servers, and other tools;
-- Electron processes supplied as explicit external roots;
-- descendants of those Electron roots;
-- the resource monitor itself, because it is a server child.
-
-Process identity is `(pid, startTimeMs)`, not PID alone. Electron and native
-start times are matched with a two-second tolerance because native start times
-can have coarser platform resolution.
-
-The process list is emitted in depth-first tree order so renderer collapse and
-expansion preserves complete subtrees.
-
-### Native history and streaming
-
-Every native sample is appended to a one-hour in-memory ring bounded to 3,600
-snapshots, 20,000 retained process rows, and 64 MiB of retained history bytes.
-History stays in the sidecar until a `readHistory` request and is returned in
-bounded chunks. The first bound reached wins, so high process counts or large
-process names and command lines shorten the effective history window.
-
-Periodic snapshot streaming is disabled by default. The server enables it only
-while at least one diagnostics subscription is retained. `sampleNow` remains
-available for explicit refreshes and identity validation.
-
-The server adjusts native sampling without restarting the sidecar:
-
-- suspended, locked, low-power, or serious/critical thermal state: 15 seconds;
-- battery: 5 seconds;
-- normal AC: 5 seconds in the background and 1 second while live diagnostics is
-  open;
-- unknown or stale power: 5 seconds in the background and 1 second while live
-  diagnostics is open.
-
-### Sampling limits
-
-This is counter sampling, not syscall tracing.
-
-- A process that starts and exits entirely between samples may not be observed.
-- Cumulative CPU and I/O counters still provide accurate deltas for processes
-  that survive across samples.
-- Exact file paths, individual write syscalls, ETW events, eBPF events, and
-  Endpoint Security events are outside this implementation.
-
-Those deeper tracing systems can be added later as opt-in diagnostic modes
-without changing the public `ResourceTelemetry` model.
-
-## I/O semantics
-
-The monitor preserves platform semantics instead of presenting all counters as
-equivalent:
-
-- Unix-like platforms report storage I/O counters exposed by `sysinfo`.
-- Windows reports all process I/O bytes, not only disk bytes.
-- Operating-system caches can prevent logical application reads or writes from
-  appearing as physical storage bytes.
-
-The UI therefore labels these values as I/O reads and writes and exposes the
-per-process `ioSemantics` value.
-
-Group totals are observed deltas since telemetry startup. Per-process total
-columns are the operating system's cumulative counters for that process.
-
-## Electron telemetry
-
-Electron main owns `DesktopTelemetryPublisher`.
-
-Power events trigger an immediate snapshot. While diagnostics is closed, the
-server sends the configured active and idle host-power intervals to Electron
-(30 seconds and 2 minutes in the balanced profile). During those heartbeats
-Electron reads:
-
-- `powerMonitor.isOnBatteryPower()`;
-- `powerMonitor.getSystemIdleTime()`;
-- `powerMonitor.getSystemIdleState()`;
-- `powerMonitor.getCurrentThermalState()`.
-
-`app.getAppMetrics()` is only called while diagnostics demand is active. Its
-live cadence is 1 second on AC, 5 seconds on battery, and 15 seconds while
-locked, suspended, or thermally constrained.
-
-It also listens for:
-
-- lock and unlock;
-- suspend and resume;
-- AC and battery transitions;
-- thermal-state changes;
-- CPU speed-limit changes.
-
-Suspension stays latched across event-driven snapshots. An explicit resume
-clears it immediately; a periodic heartbeat also clears a stale latch so a
-missed resume event cannot leave telemetry permanently constrained.
-
-Electron does not expose a cross-platform low-power-mode getter, so that field
-remains `unknown`.
-
-The desktop backend is spawned with:
-
-- fd 3 for the existing bootstrap payload;
-- fd 4 for Electron-to-server telemetry NDJSON;
-- fd 5 for server-to-Electron diagnostics-demand NDJSON.
-
-These are private Electron-main/server pipes. They do not use the renderer
-WebSocket and are recreated for every backend restart.
-
-## Server Effect services
-
-The implementation is under `apps/server/src/resourceTelemetry`.
-
-### `ResourceMonitorBinary`
-
-Resolves an executable from:
-
-1. `T3CODE_RESOURCE_MONITOR_PATH`;
-2. desktop bootstrap configuration;
-3. bundled CLI resources;
-4. local Cargo build outputs.
-
-Unsupported platforms, missing binaries, and non-executable binaries use
-schema-backed tagged errors with descriptive messages.
-
-### `NativeTelemetryClient`
-
-Owns the resource-monitor process and protocol.
-
-- validates the hello/version handshake;
-- sends configuration and external process roots;
-- adapts the native interval from host power state;
-- enables streaming only for scoped live subscribers;
-- reads chunked native history on demand;
-- exposes `sampleNow`;
-- serializes commands;
-- supervises process exit and protocol failure;
-- restarts with bounded exponential backoff;
-- opens a circuit after repeated failures;
-- supports explicit retry;
-- publishes health changes immediately.
-
-Snapshot sequence numbers are scoped to a monitor generation. Server ingestion
-uses the monitor restart count as the generation key, so sequence reset after a
-restart cannot freeze telemetry.
-
-### `DesktopTelemetryReceiver`
-
-Reads fd 4, decodes schema-validated messages, stores the latest Electron
-snapshot, and publishes desktop health. It writes diagnostics demand to fd 5
-and gives the first sample a 90-second startup deadline. Once samples arrive,
-the stale deadline stays beyond the slower configured host-power interval with
-30 seconds of scheduling grace, so intentional 2–10 minute idle polling does
-not oscillate the policy between constrained and unconstrained states. Decode
-errors, protocol mismatch, control-write failure, stream failure, stale input,
-and normal stream closure are represented explicitly.
-
-### `ResourceTelemetry`
-
-Merges native and Electron data and owns public telemetry semantics.
-
-- calculates CPU and I/O rates from cumulative native counters;
-- preserves the last native rates during desktop-only updates;
-- classifies backend, Electron, and monitor processes;
-- computes process depth and child relationships;
-- tracks starts, exits, CPU time, and observed I/O;
-- projects power data;
-- acquires native streaming and Electron process metrics only for scoped live
-  subscribers;
-- queries and replays native history only when requested;
-- validates `(pid, startTimeMs)` before process signaling;
-- updates history health even when no further native sample arrives.
-
-Electron and monitor processes are visible but are not valid targets for the
-existing process-signal RPC.
-
-### History projection
-
-`ResourceTelemetryHistory` is a pure on-demand projection. It replays raw native
-snapshots to derive rates, lifecycle counters, buckets, and process summaries.
-Current Electron process metrics are intentionally excluded from historical
-replay so they cannot overwrite older native CPU or memory samples.
-
-### `ResourceAttribution`
-
-Tracks known logical application I/O separately from OS counters. Current
-integration points record successful writes for:
-
-- provider native and canonical event logs;
-- the local server trace sink.
-
-Entries contain component, operation, logical bytes, count, and elapsed time.
-Future persistence paths should call `ResourceAttribution.record` rather than
-adding diagnostics-specific counters.
-
-## Background policy integration
-
-`HostPowerMonitor` consumes `DesktopTelemetryReceiver` directly; observing host
-power does not retain live resource diagnostics or invoke shell probes.
-
-The monitor updates its latest timestamp on every Electron sample but only
-publishes semantic state changes. Increasing idle seconds alone does not cause a
-background-policy broadcast every second.
-
-## Public API and UI
-
-The WebSocket RPC surface provides:
-
-- current snapshot;
-- bounded history;
-- explicit monitor retry;
-- a live snapshot subscription.
-
-The diagnostics page displays:
-
-- aggregate CPU, memory, I/O, and process counts;
-- backend, Electron, and monitor overhead groups;
-- power and thermal state;
-- collector health and restart information;
-- CPU and I/O history;
-- a collapsible live process tree;
-- safe process signaling for backend descendants;
-- instrumented logical application I/O.
-
-Legacy process diagnostics RPCs are projected from the same service so they no
-longer start recurring process-table commands.
-
-## Packaging
-
-Desktop artifact builds compile the Rust target, stage it as
-`resources/resource-monitor/t3-resource-monitor[.exe]`, and pass its path to the
-backend bootstrap.
-
-CLI release jobs upload each active platform monitor artifact and copy it into:
-
-```text
-apps/server/dist/resource-monitor/<platform>-<arch>/
-```
-
-The published server package already includes `dist`, so those executables ship
-with the CLI. Missing platform artifacts degrade native telemetry to
-`unavailable`; the server continues running.
-
-## Resource and failure behavior
-
-Steady state uses:
-
-- one native process;
-- power-adaptive native counter sampling with no periodic Node snapshot stream;
-- event-driven Electron power updates plus profile-driven heartbeats (30–60
-  seconds while active and 2–10 minutes while idle);
-- no `app.getAppMetrics()` calls while diagnostics is closed;
-- no telemetry database;
-- no recurring shell probes;
-- bounded PubSub queues and native ring history.
-
-The diagnostics page exposes the monitor's own process resource usage and
-collection duration so the observer's cost is measurable.
-
-Failures are isolated:
-
-- native failure does not stop the server;
-- Electron telemetry loss does not stop native telemetry;
-- schema/version errors are visible in health;
-- repeated native failures stop automatic restart churn until explicit retry;
-- server and desktop shutdown close their respective streams and child process
-  scopes.
-
-## Future integration points
-
-High-value follow-up work can use the existing service boundaries:
-
-- opt-in file-path attribution through platform-specific tracing;
-- process lifecycle events to reduce the chance of missing very short-lived
-  children;
-- additional `ResourceAttribution` instrumentation for databases, checkpoints,
-  caches, and file synchronization;
-- exported diagnostic bundles;
-- adaptive sample intervals based on diagnostics visibility and active work.
-
-These additions should preserve the current rules: direct platform APIs,
-schema-validated boundaries, explicit metric semantics, bounded retention, and
-no mandatory telemetry persistence.
+# Resource telemetry
+
+Process counters come from a [standalone Rust monitor](../../native/resource-monitor/src/main.rs)
+using `sysinfo`. Electron main supplies host power and Electron process metrics.
+Keeping native collection outside Node isolates collector crashes and avoids a
+Node/Electron addon ABI matrix. Desktop and CLI servers use the same child-process
+protocol. A missing or failed collector leaves the server running.
+
+## Collection cost
+
+The native child owns sampling and bounded in-memory history. The server requests
+continuous snapshots only while diagnostics has live subscribers and fetches
+history on demand. Consuming host power for background scheduling must not retain
+live diagnostics. There is no telemetry database or recurring shell-probe fallback.
+
+History has independent bounds for age, snapshot count, process rows, and retained
+bytes. A count limit alone cannot bound memory when command lines vary in size.
+Large process trees therefore shorten the available history window. Linux task
+enumeration is disabled because walking every `/proc/<pid>/task/<tid>` directory
+makes sampling itself expensive.
+
+Electron power updates travel over private inherited pipes, independent of the
+renderer connection. Power events and slow heartbeats continue with diagnostics
+closed; `app.getAppMetrics()` runs only on live demand. The receiver's stale deadline
+must exceed the slowest configured heartbeat plus scheduling grace, or intentional
+idle polling makes background policy oscillate between constrained and
+unconstrained states. Headless servers leave unavailable power data unknown.
+
+## Measurement traps
+
+- Process identity includes start time because operating systems reuse PIDs.
+  Electron and native start times have different precision, so merging allows a
+  small tolerance. Process signaling rechecks the native identity with a fresh
+  sample.
+- Snapshot sequence numbers belong to a monitor generation. Comparing them across
+  restarts would discard the new monitor's samples until its sequence caught up.
+- Sampling can miss a process that starts and exits between samples. Cumulative
+  counters still yield deltas for processes observed across samples.
+- Windows process I/O includes more than disk traffic. Unix counters report storage
+  I/O, which can differ from logical application reads and writes because of OS
+  caching. Keep instrumented logical I/O separate from these counters.
+- Group totals accumulate observed deltas since telemetry started. Per-process
+  cumulative counters cover the operating system's lifetime for that process.
+- Historical replay uses native samples without current Electron CPU or memory
+  metrics. Merging the latest Electron values would overwrite the past.
+
+A WSL backend needs a Linux monitor even though Electron runs on Windows. Windows
+desktop packages currently supply only the Windows executable, so native process
+telemetry for the WSL backend is unavailable. The inherited Electron power feed
+still works.
diff --git a/docs/internals/scripts.md b/docs/internals/scripts.md
deleted file mode 100644
index 3f8c58601e7f..000000000000
--- a/docs/internals/scripts.md
+++ /dev/null
@@ -1,215 +0,0 @@
-# Scripts
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-## First checkout
-
-T3 Code uses [Vite+](https://viteplus.dev/guide/). Install the global `vp` command, install
-dependencies, then start the dev stack:
-
-```bash
-curl -fsSL https://vite.plus | bash   # Windows: irm https://vite.plus/ps1 | iex
-vp i
-vp run dev
-```
-
-Node 24 is required. Bun is not: the server picks Bun adapters when it detects Bun and falls back to
-Node otherwise, and nothing in contributor setup needs it.
-
-`vp run dev` prints a one-time pairing URL. Open it so the first browser navigation is
-authenticated.
-
-## Dev
-
-- `vp run dev`: Starts contracts, server, and web in watch mode.
-- `vp run dev --share`: Also publishes the web port over HTTPS on this machine's tailnet. The
-  startup pairing URL is built against the shared origin, and the mapping is removed on exit.
-  Shared runs default to Vite's bundled dev mode (`T3CODE_BUNDLED_DEV=1`): a remote browser pays a
-  network round trip per import level in unbundled dev, which turns a cold module graph into
-  minutes of waterfall. Set `T3CODE_BUNDLED_DEV=0` to opt a shared run back out.
-  The web entry loads the app with a dynamic import so React refresh starts before shared UI
-  chunks run. Keep app imports out of that entry. A static import can work on the first load
-  and then fail on reload after Vite splits code for lazy routes.
-  Bundled dev uses Tailwind's watched files to rebuild CSS. Its Vite-only hot-update hook is
-  disabled in this mode because Rolldown does not supply the Vite server or module graph.
-- `vp run dev --browser`: Auto-opens a browser. Off by default. The dev runner writes
-  `T3CODE_NO_BROWSER` itself from this flag, so setting `T3CODE_NO_BROWSER=0` in your environment has
-  no effect; use `--browser`.
-- `vp run dev:server`: Starts just the server. It runs on Node (`node --watch src/bin.ts`), so
-  without Bun present it selects `NodePtyAdapter` and `NodeHttpServer`.
-- `vp run dev:web`: Starts just the Vite dev server for the web app.
-- `vp run dev:desktop`: Starts the Electron shell against the dev server.
-- `vp run dev:marketing`: Starts the Astro marketing site.
-- Pass dev-runner flags directly after the root task name, for example:
-  `vp run dev --home-dir /tmp/t3code-dev`
-
-### Dev state directories
-
-- Dev commands run from a linked **git worktree** default to that worktree's gitignored `.t3`, even
-  when `T3CODE_HOME` is set, storing state in `<worktree>/.t3/userdata`. Pass `--home-dir <path>` to
-  choose another isolated directory explicitly. Submodules are not worktrees and keep the normal
-  precedence.
-- From the **main checkout**, dev commands implicitly use `~/.t3/dev`, keeping development state
-  separate from `~/.t3/userdata`. An explicit `--home-dir <path>` stores state under
-  `<path>/userdata`; the base directory remains available for caches, worktrees, and other shared
-  data.
-
-## Build, check, test
-
-- `vp run build`: Fans out over `apps/*`, `packages/*`, `oxlint-plugin-t3code`, and `scripts`.
-  Workspaces that define a build task run one: desktop, marketing, server (which depends on web), and
-  web. Shared packages are consumed and bundled transitively rather than built separately.
-- `vp run build:desktop`: Builds the desktop pipeline (desktop plus server).
-- `vp run start`: Runs the production server (serves the built web app as static files).
-- `vp check`: Vite+ format, lint, and type checks. This repo sets `typeCheck: false` in its lint
-  options, so workspace type checking runs separately.
-- `vp run typecheck`: Strict TypeScript checks for all packages.
-- `vp run test`: Runs workspace tests.
-- `vp run lint:mobile`: Mobile native static analysis (`scripts/mobile-native-static-check.ts`).
-- `node apps/server/scripts/t3-sqlite-state.ts <query|exec> --base-dir <path> ...`: Inspects or seeds
-  an isolated T3 SQLite database; writes create a private backup first.
-
-## Desktop artifacts
-
-- `vp run dist:desktop:artifact --platform <mac|linux|win> --target <target> --arch <arch>`: Builds a desktop artifact for a specific platform/target/arch.
-- `vp run dist:desktop:dmg`: Builds a shareable macOS `.dmg` into `./release`. Architecture defaults
-  to the host, so this produces an arm64 DMG on Apple Silicon. Use `dist:desktop:dmg:arm64` or
-  `dist:desktop:dmg:x64`, or pass `--arch <arm64|x64|universal>`, to force one.
-- `vp run dist:desktop:linux`: Builds a Linux AppImage into `./release`.
-- `vp run dist:desktop:win`: Builds a Windows NSIS installer into `./release`. `:arm64` and `:x64`
-  variants exist.
-
-### Linux AppImage prerequisites
-
-Linux AppImage packaging compiles the Rust resource monitor and the libsecret browser import
-helper. Install a Rust toolchain, the standard C/C++ build tools, libsecret development headers,
-pkg-config, and ImageMagick before running `vp run dist:desktop:linux`.
-
-Ubuntu and Debian:
-
-```bash
-sudo apt-get update
-sudo apt-get install cargo rustc build-essential libsecret-1-dev pkg-config imagemagick
-```
-
-Fedora:
-
-```bash
-sudo dnf install rust cargo gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick
-```
-
-Arch Linux:
-
-```bash
-sudo pacman -S rust base-devel libsecret pkgconf imagemagick
-```
-
-Linux desktop development also needs the C compiler, pkg-config, and libsecret headers. Its build
-and launch commands compile `native/browser-secret/main.c` into the gitignored native build
-directory. Releases place the executable in `resources/browser-secret`, outside `app.asar`.
-The helper performs a read-only Chromium schema lookup through libsecret and writes the exact
-secret bytes to its stdout pipe. Exit codes are 2 for a missing key, 3 for denied/locked access,
-and 4 for other keyring failures; the desktop importer preserves these distinctions.
-
-The artifact script checks these capabilities before starting the web and desktop builds. If
-anything is unavailable, it reports every failed check together and prints the Ubuntu/Debian
-installation command. The check compiles and links tiny temporary programs, so it also catches
-installed runtime X11 libraries that are missing their development headers or linker symlinks.
-
-### macOS DMG prerequisites
-
-Install the Xcode Command Line Tools and Rust before building a DMG:
-
-```bash
-xcode-select --install
-```
-
-Install Rust from [rustup.rs](https://rustup.rs). The artifact script checks Cargo, Clang, Make,
-`sips`, and `iconutil`. Universal builds additionally require `lipo`. It also verifies that Rust
-has every requested target; add missing targets with:
-
-```bash
-rustup target add aarch64-apple-darwin x86_64-apple-darwin
-```
-
-Unsigned local builds need no Apple credentials. Builds using `--signed` additionally require the
-certificate, provisioning profile, team ID, and notarization configuration described below.
-
-### Windows installer prerequisites
-
-Install Rust from [rustup.rs](https://rustup.rs), Python 3, and Visual Studio Build Tools. In the
-Visual Studio Installer, select **Desktop development with C++** and include:
-
-- MSVC x64/x86 build tools
-- A Windows 10 or Windows 11 SDK
-- MSVC Spectre-mitigated libraries
-
-ARM64 installers require the corresponding MSVC ARM64 build tools and Spectre-mitigated libraries
-instead of the x64/x86 components.
-
-Add the Rust target matching the installer architecture:
-
-```powershell
-rustup target add x86_64-pc-windows-msvc
-# For an arm64 installer:
-rustup target add aarch64-pc-windows-msvc
-```
-
-Windows supplies `tar.exe`; it is checked when `--wsl-prebuild` makes the artifact include the WSL
-runtime. NSIS is downloaded by electron-builder and does not need a separate installation.
-When `T3CODE_DESKTOP_REUSE_RESOURCE_MONITOR=true` points the build at an existing resource monitor,
-the artifact script skips the Rust and Visual Studio checks because it does not compile the monitor.
-Unsigned local builds need no Azure credentials. Builds using `--signed` additionally require the
-Azure Trusted Signing configuration described below.
-
-### Desktop `.dmg` packaging notes
-
-- Default build is unsigned/not notarized for local sharing.
-- The DMG build uses `assets/prod/black-macos-1024.png` as the production app icon source.
-- The DMG chrome follows the release channel: neutral for Latest and the Nightly sky artwork for
-  Nightly. Blueprint artwork remains exclusive to Dev builds. Packaging rasterizes the selected
-  SVG into standard and Retina PNGs inside the disposable staging directory.
-- The Finder window is 540×412 while its background is 540×380; the extra 32px accounts for the
-  title bar included in Finder's window bounds.
-- Desktop production windows load the bundled UI from the `t3code://app/` root URL (not a
-  `127.0.0.1` document URL, and not an explicit `index.html` path).
-- Desktop packaging includes `apps/server/dist` (the `t3` backend) and starts it on loopback with an
-  auth token for WebSocket/API traffic.
-- Your tester can still open it on macOS by right-clicking the app and choosing **Open** on first
-  launch.
-- To keep staging files for debugging package contents, run: `vp run dist:desktop:dmg --keep-stage`
-- To allow code-signing/notarization when configured in CI/secrets, add: `--signed`.
-- Signed macOS builds also require `T3CODE_APPLE_TEAM_ID` and
-  `T3CODE_MACOS_PROVISIONING_PROFILE`. The passkey RP domain is derived from
-  `T3CODE_CLERK_PUBLISHABLE_KEY` unless `T3CODE_CLERK_PASSKEY_RP_DOMAINS` overrides it.
-- Windows `--signed` uses Azure Trusted Signing and expects:
-  `AZURE_TRUSTED_SIGNING_ENDPOINT`, `AZURE_TRUSTED_SIGNING_ACCOUNT_NAME`,
-  `AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME`, and `AZURE_TRUSTED_SIGNING_PUBLISHER_NAME`.
-- Azure authentication env vars are also required (for example service principal with secret):
-  `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`.
-
-## Browser development
-
-`dev` and `dev:web` leave `VITE_HTTP_URL` and `VITE_WS_URL` unset so the browser resolves the backend
-from `window.location.origin`. Vite proxies `/api`, `/ws`, `/oauth`, and `/.well-known` to the
-server, allowing the same bundle to work from localhost or a tailnet hostname.
-
-## Running multiple dev instances
-
-Worktrees derive a preferred port offset from their path.
-
-- Default ports: server `13773`, web `5733`
-- Shifted ports: `base + offset`
-- Example: `T3CODE_DEV_INSTANCE=branch-a vp run dev:desktop`
-
-Offset resolution, in order:
-
-1. `T3CODE_PORT_OFFSET`, which must be a non-negative integer. Negative values are rejected.
-2. `T3CODE_DEV_INSTANCE`. An all-digit value is used directly as the offset; any other non-empty
-   value is hashed into one.
-3. The worktree path hash.
-
-Collision scanning depends on the mode. `dev:web` scans only the web port and shifts only the web
-offset. `dev:server` scans only the server port. `dev` and `dev:desktop` scan both and shift them
-together as one shared offset. Explicit server or dev-URL overrides remove the corresponding port
-from the availability check. Treat the `[dev-runner]` output as authoritative.
diff --git a/docs/internals/server-updates.md b/docs/internals/server-updates.md
index 693a240bbc79..db24428ce54d 100644
--- a/docs/internals/server-updates.md
+++ b/docs/internals/server-updates.md
@@ -1,107 +1,57 @@
-# Server Update Architecture
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-Remote server updates use one stable launcher selected by the platform service manager (systemd on
-Linux, launchd on macOS). Foreground CLI processes do not self-update, and a running server never
-edits its service definition or durable service state.
-
-## Ownership
-
-The service files under `<baseDir>/runtime` are:
-
-- `service-launcher.mjs`, the stable process selected by the service manager;
-- `service-state.json`, the launcher's durable selection state;
-- `versions/<version>`, immutable exact-version npm installs.
-
-The launcher is the only runtime writer of `service-state.json`. `t3 service install` and
-`t3 service update` may replace the launcher and state while the unit is stopped. Server children
-only communicate with the launcher over their inherited IPC channel.
-
-The state contains one active version and, at most, one update record:
-
-- `pending A → B` selects B as a retryable trial;
-- `committed A → B` selects B for ordinary restarts;
-- `rolled-back A → B` or `failed A → B` selects A;
-- invalid state fails closed so the service manager cannot guess at a runtime.
-
-Every write uses same-directory replacement plus file and directory fsync.
-
-## Remote Update
-
-1. The active server installs `t3@<target>` into a unique staging directory.
-2. The target runs `__service-preflight` and verifies that the stable launcher supports its update
-   protocol.
-3. The staging directory is renamed to its immutable version path only after preflight succeeds.
-4. The active child sends `request-update`. The launcher validates the child and target, writes
-   pending state, generates the update ID, then replies `update-accepted`.
-5. After a short response-flush grace period, the launcher stops the active child.
-6. With SQLite quiescent, the launcher snapshots the database, WAL, and shared-memory files.
-7. The launcher starts the target as a trial and gives it the pending update over IPC.
-8. The trial runs migrations, acquires dependencies, binds HTTP, starts every long-running root
-   fiber, and verifies that each root is parked at the activation gate.
-9. The trial sends `prepared`. The launcher durably commits B, deletes the snapshot, then replies
-   `committed`.
-10. The child opens the existing activation gate, accepts commands, and publishes lifecycle ready
-    with the terminal update outcome.
-
-Post-commit startup does not call service `start`, `initialize`, `connect`, `load`, or `acquire`
-operations. It only opens prepared gates and publishes prepared lifecycle state.
-
-The launcher serializes child exits, IPC messages, and timers. A trial must report prepared within
-120 seconds. If the trial exits or times out before prepared, the launcher stops it, restores the
-snapshot, records rollback, and starts A. A durable restore marker makes an interrupted restore
-resume before either version can boot. After commit, B is active and the service manager's normal
-restart policy applies.
-
-## Database Rollback
-
-The launcher snapshots `state.sqlite`, `state.sqlite-wal`, and `state.sqlite-shm` after the old
-server stops and before the trial starts. This makes trial migrations and writes reversible without
-requiring down migrations. The snapshot is retained across launcher restarts and is removed only
-after commit or after both restore and the terminal rollback state are durable.
-
-The protocol version is part of the safety boundary. A target that requires database snapshots is
-blocked when the installed launcher is too old. Upgrade the launcher once with:
-
-```sh
-npx t3@<version> service update
-```
-
-The local command stops the unit, selects the new launcher and exact runtime, then restarts the
-service. Later releases, including releases with migrations, can use the remote trial path.
-
-Snapshots briefly require enough free disk for another copy of the SQLite files. Attachments and
-other files under the state directory are outside this rollback boundary.
-
-## Client Correlation
-
-The update acknowledgement includes the launcher-generated update ID. After reconnecting, clients
-wait for a lifecycle ready event carrying that same ID. `committed` completes the operation only
-when the ready server is the target version. `rolled-back` and `failed` end it immediately with the
-recorded reason. Older servers without an ID retain version-only reconnect behavior.
-
-## Capability and Compatibility
-
-The existing additive RPC and lifecycle schemas remain compatible with older clients. New servers
-advertise remote self-update only when they have valid launcher context and a live IPC channel.
-Desktop-managed servers advertise `desktopAppUpdate` when the desktop telemetry control fd is
-attached. The progress RPC asks the desktop app to check and download, then returns a preparation
-token while the backend is still connected. Only after the client receives that result does it send
-`server.commitDesktopUpdate`. A successful commit closes the connection and must reconnect at the
-prepared version. The desktop app and bundled server versions stay equal because
-`scripts/update-release-package-versions.ts` bumps them together. If install fails, the desktop keeps its windows, restarts stopped backends, and
-replays the failure for the same token. This two-phase handoff prevents backend shutdown from
-dropping the only successful RPC result. Desktop servers without the capability direct the user to
-update the desktop app locally. Other process shapes provide a manual command; the old detached
-foreground respawn path no longer exists.
-
-## Source Map
-
-- Launcher and state machine: `apps/server/src/serviceLauncher.ts`
-- IPC and durable state types: `apps/server/src/cloud/serviceProtocol.ts`
-- Child IPC adapter: `apps/server/src/cloud/serviceLauncherClient.ts`
-- Staging and preflight: `apps/server/src/cloud/pinnedRuntime.ts` and `servicePreflight.ts`
-- Service installation: `apps/server/src/cloud/bootService.ts`
-- Activation boundary: `apps/server/src/serverRuntimeStartup.ts` and `serverActivation.ts`
-- Client outcome correlation: `packages/client-runtime/src/state/server.ts`
+# Server updates
+
+A [stable launcher](../../apps/server/src/serviceLauncher.ts) owns the runtime
+selected by systemd or launchd. It is the only runtime writer of durable service
+state. Server children request updates over inherited IPC; they never rewrite
+their service definition or select their own replacement. Local service commands
+may replace the launcher and state while the service is stopped. Foreground CLI
+processes do not self-update.
+
+Exact-version installs keep restarts independent of npm cache eviction or a moving
+release tag. Installation and preflight happen in staging before publishing an
+immutable runtime. Preflight checks the launcher protocol because a target that
+needs new rollback guarantees cannot safely run under an older launcher. Upgrading
+that launcher requires a local service update.
+
+## Commit boundary
+
+The launcher durably records the pending update before acknowledging it, then
+stops the old child and starts the target as a trial. Service-state writes use
+same-directory replacement with file and directory fsync. Invalid state stops
+startup rather than guessing which runtime to boot.
+
+The trial must finish migrations, acquire dependencies, bind HTTP, and park every
+long-running root at the activation gate before reporting `prepared`. The launcher
+then commits the target version durably and replies `committed`. Only then may the
+child release its gates, accept commands, and publish ready. Keep fallible startup
+acquisitions before this boundary. A listener alone does not prove the runtime is
+ready to commit.
+
+A failed or timed-out trial returns to the old version. After commit, the target
+is authoritative and the service manager's ordinary restart policy applies.
+
+## Database rollback
+
+After the old child exits, the launcher snapshots SQLite's main file, WAL, and
+shared-memory file. This makes trial migrations reversible without down
+migrations. The snapshot is made once per update and survives launcher restarts;
+replacing it during a retry could capture changes from the failed trial.
+
+Rollback stops the trial before restoring. A durable restore marker makes an
+interrupted restore finish before either version boots. Keep the snapshot until
+commit, or until both restoration and the terminal rollback state are durable.
+Attachments and other files outside SQLite are outside this rollback boundary.
+
+## Client acknowledgement
+
+An accepted update is still pending. Clients correlate the launcher's update ID
+with the ready event after reconnecting, then check the outcome and target version.
+A reconnect alone cannot distinguish successful replacement from rollback. Older
+servers without an update ID retain version-only correlation.
+
+Desktop updates have a separate two-phase handoff because installing the app stops
+its bundled backend. Preparation returns a token while the connection is alive;
+the client commits that token only after receiving it. Otherwise backend shutdown
+could lose the only successful RPC result. The client must then observe the
+prepared version after reconnecting. If installation fails, desktop restarts the
+stopped backends and replays the failure for the same token.
diff --git a/docs/internals/t3-code-connect-auth-flow.html b/docs/internals/t3-code-connect-auth-flow.html
deleted file mode 100644
index 038132ee5cbf..000000000000
--- a/docs/internals/t3-code-connect-auth-flow.html
+++ /dev/null
@@ -1,1160 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>T3 Connect Architecture</title>
-    <style>
-      :root {
-        color-scheme: light;
-        --ink: #171717;
-        --muted: #62646b;
-        --hairline: #d8d8dd;
-        --panel: #ffffff;
-        --paper: #f5f5f2;
-        --blue: #1457d9;
-        --green: #1d7d4d;
-        --amber: #a65f00;
-        --red: #b8242c;
-        --violet: #6150b8;
-        --shadow: 0 18px 55px rgba(25, 25, 28, 0.08);
-      }
-
-      * {
-        box-sizing: border-box;
-      }
-
-      body {
-        margin: 0;
-        background:
-          linear-gradient(90deg, rgba(0, 0, 0, 0.035) 1px, transparent 1px),
-          linear-gradient(rgba(0, 0, 0, 0.035) 1px, transparent 1px), var(--paper);
-        background-size: 34px 34px;
-        color: var(--ink);
-        font-family:
-          ui-sans-serif,
-          -apple-system,
-          BlinkMacSystemFont,
-          "Segoe UI",
-          sans-serif;
-        line-height: 1.48;
-      }
-
-      .shell {
-        width: min(1540px, calc(100vw - 40px));
-        margin: 0 auto;
-        padding: 38px 0 72px;
-      }
-
-      header {
-        border-bottom: 2px solid var(--ink);
-        padding-bottom: 24px;
-        margin-bottom: 28px;
-      }
-
-      .eyebrow {
-        color: var(--blue);
-        font-size: 12px;
-        font-weight: 800;
-        letter-spacing: 0.08em;
-        text-transform: uppercase;
-      }
-
-      h1 {
-        max-width: 980px;
-        margin: 8px 0 12px;
-        font-size: clamp(34px, 5vw, 66px);
-        line-height: 0.98;
-      }
-
-      h2 {
-        margin: 0 0 14px;
-        font-size: 26px;
-        line-height: 1.08;
-      }
-
-      h3 {
-        margin: 22px 0 8px;
-        font-size: 17px;
-      }
-
-      p {
-        margin: 0 0 12px;
-      }
-
-      code,
-      .mono {
-        font-family:
-          ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
-      }
-
-      code {
-        border-radius: 4px;
-        background: #f0f0ed;
-        padding: 1px 4px;
-        font-size: 0.92em;
-      }
-
-      .lede {
-        max-width: 1000px;
-        margin: 0;
-        color: var(--muted);
-        font-size: 18px;
-      }
-
-      .grid {
-        display: grid;
-        grid-template-columns: repeat(12, 1fr);
-        gap: 18px;
-      }
-
-      .panel {
-        grid-column: span 12;
-        border: 1px solid var(--hairline);
-        border-radius: 10px;
-        background: var(--panel);
-        box-shadow: var(--shadow);
-        padding: 22px;
-      }
-
-      .half {
-        grid-column: span 6;
-      }
-
-      .callout {
-        border-left: 5px solid var(--blue);
-        background: #eef4ff;
-        padding: 14px 16px;
-        margin-top: 14px;
-      }
-
-      .callout.warning {
-        border-left-color: var(--amber);
-        background: #fff6e6;
-      }
-
-      .badge-row {
-        display: flex;
-        flex-wrap: wrap;
-        gap: 8px;
-        margin-top: 14px;
-      }
-
-      .badge {
-        border: 1px solid var(--hairline);
-        border-radius: 999px;
-        background: #fff;
-        padding: 5px 9px;
-        font-size: 12px;
-        font-weight: 700;
-      }
-
-      .badge.user {
-        border-color: rgba(20, 87, 217, 0.3);
-        color: var(--blue);
-      }
-
-      .badge.env {
-        border-color: rgba(29, 125, 77, 0.3);
-        color: var(--green);
-      }
-
-      .badge.local {
-        border-color: rgba(166, 95, 0, 0.35);
-        color: var(--amber);
-      }
-
-      .diagram {
-        overflow-x: auto;
-        margin: 12px 0 0;
-        border: 1px solid var(--hairline);
-        border-radius: 8px;
-        background: #fbfbf8;
-        color: var(--ink);
-        padding: 18px;
-      }
-
-      .diagram svg {
-        display: block;
-        width: auto !important;
-        min-width: 100%;
-        max-width: none !important;
-        height: auto;
-        margin: 0 auto;
-      }
-
-      table {
-        width: 100%;
-        border-collapse: collapse;
-        font-size: 14px;
-      }
-
-      th,
-      td {
-        border-bottom: 1px solid var(--hairline);
-        padding: 11px 9px;
-        text-align: left;
-        vertical-align: top;
-      }
-
-      th {
-        color: var(--muted);
-        font-size: 12px;
-        letter-spacing: 0.05em;
-        text-transform: uppercase;
-      }
-
-      ul {
-        margin: 8px 0 0;
-        padding-left: 20px;
-      }
-
-      li + li {
-        margin-top: 6px;
-      }
-
-      .flow {
-        display: grid;
-        gap: 10px;
-        margin-top: 12px;
-      }
-
-      .step {
-        border: 1px solid var(--hairline);
-        border-left: 5px solid var(--green);
-        border-radius: 8px;
-        background: #fff;
-        padding: 12px 14px;
-      }
-
-      .step strong {
-        display: block;
-        margin-bottom: 3px;
-      }
-
-      .source-list a {
-        color: var(--blue);
-        font-weight: 700;
-      }
-
-      @media (max-width: 860px) {
-        .half {
-          grid-column: span 12;
-        }
-
-        .shell {
-          width: min(100vw - 24px, 1540px);
-          padding-top: 24px;
-        }
-      }
-    </style>
-  </head>
-  <body>
-    <main class="shell">
-      <header>
-        <div class="eyebrow">Implemented architecture</div>
-        <h1>T3 Connect Control Plane and Managed Endpoint Flow</h1>
-        <p class="lede">
-          T3 Connect links a locally authorized T3 environment to a signed-in cloud user, provisions
-          a managed HTTPS/WSS endpoint for that environment, and brokers proof-bound remote
-          connections. The local environment remains the authority that issues environment access
-          credentials. The hosted relay stores links, reconciles managed endpoint resources,
-          validates signed proofs, and delivers agent-activity notifications.
-        </p>
-        <div class="badge-row">
-          <span class="badge user">Client -> Relay: Clerk bearer or relay DPoP</span>
-          <span class="badge env">Relay -> Environment: relay-signed health and mint proofs</span>
-          <span class="badge env"
-            >Environment -> Relay: environment bearer plus signed activity proof</span
-          >
-          <span class="badge local">Client -> Environment: environment access token plus DPoP</span>
-        </div>
-      </header>
-
-      <section class="grid" aria-label="Architecture summary">
-        <article class="panel half">
-          <h2>Security Invariant</h2>
-          <p>
-            A cloud identity is not an environment login. Remote access requires all of the
-            following:
-          </p>
-          <ul>
-            <li>a Clerk-authenticated T3 Connect user;</li>
-            <li>an active relay link for that user and environment;</li>
-            <li>a DPoP proof key held by the remote client;</li>
-            <li>a relay-signed mint request accepted by the linked local environment; and</li>
-            <li>an environment-issued credential bound to the remote client's DPoP thumbprint.</li>
-          </ul>
-          <div class="callout">
-            The relay cannot mint an environment access token by itself. It can only ask the local
-            environment to mint a short-lived bootstrap credential for an authorized cloud user.
-          </div>
-          <p>During an honest connection flow, the relay cannot act as the remote client:</p>
-          <ul>
-            <li>
-              Normal environment API traffic goes directly from the remote client through the
-              managed endpoint. The relay does not receive the resulting environment access token.
-            </li>
-            <li>
-              The one-time bootstrap credential and resulting environment access token are bound to
-              the remote client's DPoP public-key thumbprint. Redeeming or using them requires
-              request proofs signed by the corresponding private key, which stays on the client.
-            </li>
-            <li>
-              Relay-signed health and mint proofs are short-lived, audience-bound, scoped, and
-              replay-guarded. They are accepted only by the narrow cloud endpoints, not as normal
-              environment API credentials.
-            </li>
-            <li>
-              Environment health and mint responses are signed by the linked environment and bound
-              to the request nonce, so a different process behind the tunnel cannot impersonate the
-              linked environment.
-            </li>
-          </ul>
-          <div class="callout warning">
-            The hosted relay remains a trusted mint broker: it holds the cloud-mint signing key.
-            DPoP prevents credential reuse by the relay or tunnel transport during an honest flow,
-            but it does not make compromise of the relay signing authority harmless.
-          </div>
-        </article>
-
-        <article class="panel half">
-          <h2>Product Boundaries</h2>
-          <p>
-            The generic local connector is called the <strong>relay client</strong>. The current
-            implementation layer uses <code>cloudflared</code>, but that is an internal transport
-            detail rather than the product contract.
-          </p>
-          <ul>
-            <li>
-              The relay Worker owns cloud links, managed endpoint allocations, and notifications.
-            </li>
-            <li>
-              The environment server owns local sessions, environment keys, and access tokens.
-            </li>
-            <li>The relay client exposes only the environment's loopback HTTP server.</li>
-            <li>
-              Web and mobile clients connect directly to the managed environment endpoint after
-              bootstrap.
-            </li>
-          </ul>
-        </article>
-      </section>
-
-      <section class="panel" aria-label="Topology">
-        <h2>Current Topology</h2>
-        <pre class="diagram mermaid">
-flowchart LR
-  subgraph Clients["User-facing clients"]
-    Web["Desktop / hosted web UI"]
-    Mobile["Mobile app"]
-    CLI["Headless CLI"]
-  end
-
-  Clerk["Clerk<br/>user identity and OAuth"]
-
-  subgraph Relay["T3 Code Relay on Cloudflare"]
-    Worker["Relay Worker<br/>HTTP API"]
-    Queue["APNs delivery queue<br/>with dead-letter queue"]
-    Hyperdrive["Hyperdrive"]
-    CF["Cloudflare tunnel + DNS APIs"]
-  end
-
-  DB["PlanetScale Postgres<br/>prod database + stage branches"]
-  APNs["Apple Push Notification service"]
-  Traces["Axiom OTLP traces"]
-
-  subgraph Local["Linked T3 environment"]
-    Env["Environment server<br/>local auth authority"]
-    RelayClient["Relay client<br/>cloudflared implementation"]
-    Secrets["Server secret store<br/>keys + relay config"]
-  end
-
-  Endpoint["Managed HTTPS/WSS endpoint"]
-
-  Web -->|"Clerk bearer / relay DPoP"| Worker
-  Mobile -->|"Clerk bearer / relay DPoP"| Worker
-  CLI -->|"Clerk OAuth bearer"| Worker
-  Web --> Clerk
-  Mobile --> Clerk
-  CLI -->|"PKCE authorization code flow"| Clerk
-  Worker --> Hyperdrive --> DB
-  Worker --> Traces
-  Worker --> CF
-  Worker --> Queue --> APNs
-  Worker --> Endpoint
-  Endpoint --> RelayClient -->|"http://127.0.0.1:port"| Env
-  Env --> Secrets
-  Web -->|"environment token + DPoP<br/>HTTPS / WSS"| Endpoint
-  Mobile -->|"environment token + DPoP<br/>HTTPS / WSS"| Endpoint
-  Env -->|"environment bearer + signed activity proof"| Worker
-        </pre>
-      </section>
-
-      <section class="panel" aria-label="Authentication matrix">
-        <h2>Authentication and Transport Matrix</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Boundary</th>
-              <th>Transport</th>
-              <th>Authentication</th>
-              <th>Purpose</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>Web or mobile -> relay link management</td>
-              <td>HTTPS</td>
-              <td>Clerk session-template bearer token</td>
-              <td>Create a link challenge, submit an environment proof, list links, or unlink.</td>
-            </tr>
-            <tr>
-              <td>CLI -> relay link management</td>
-              <td>HTTPS</td>
-              <td>Clerk OAuth access token obtained with PKCE</td>
-              <td>Reconcile the desired headless cloud link when the server starts.</td>
-            </tr>
-            <tr>
-              <td>Web or mobile -> relay protected client endpoints</td>
-              <td>HTTPS</td>
-              <td>Relay-issued DPoP token plus per-request DPoP proof</td>
-              <td>
-                Check environment status, request a remote connection, and register mobile devices.
-              </td>
-            </tr>
-            <tr>
-              <td>Relay -> managed environment endpoint</td>
-              <td>HTTPS over the managed tunnel</td>
-              <td>Short-lived relay-signed JWT request proof</td>
-              <td>
-                Request a signed health response or ask the local environment to mint a credential.
-              </td>
-            </tr>
-            <tr>
-              <td>Environment -> relay activity publication</td>
-              <td>HTTPS</td>
-              <td>Relay-issued environment bearer credential plus environment-signed JWT proof</td>
-              <td>
-                Publish redacted agent-activity state for push notifications and Live Activities.
-              </td>
-            </tr>
-            <tr>
-              <td>Remote client -> environment</td>
-              <td>HTTPS and WSS over the managed tunnel</td>
-              <td>Environment-issued access token bound to the client DPoP key</td>
-              <td>Use the normal environment HTTP APIs and request a one-time WebSocket ticket.</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="panel" aria-label="Credential ownership">
-        <h2>Credential Ownership</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Credential</th>
-              <th>Created by</th>
-              <th>Stored by</th>
-              <th>Use</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>Clerk session-template JWT</td>
-              <td>Clerk</td>
-              <td>Web or mobile client</td>
-              <td>
-                Authenticate cloud-user relay requests and bootstrap relay DPoP token exchange.
-              </td>
-            </tr>
-            <tr>
-              <td>CLI OAuth access and refresh token</td>
-              <td>Clerk OAuth</td>
-              <td>Local server secret store</td>
-              <td>Authorize headless CLI link reconciliation.</td>
-            </tr>
-            <tr>
-              <td>Environment Ed25519 key pair</td>
-              <td>Local environment server</td>
-              <td>Local server secret store</td>
-              <td>
-                Sign link proofs, health responses, mint responses, and activity publication proofs.
-              </td>
-            </tr>
-            <tr>
-              <td>Relay cloud-mint key pair</td>
-              <td>Relay deployment</td>
-              <td>Private key in relay Worker config; public key installed into the environment</td>
-              <td>Sign relay-to-environment health and mint requests.</td>
-            </tr>
-            <tr>
-              <td>Relay environment bearer credential</td>
-              <td>Relay</td>
-              <td>Hashed in relay Postgres; plaintext in local server secret store</td>
-              <td>Authenticate environment-to-relay agent-activity publication.</td>
-            </tr>
-            <tr>
-              <td>Relay DPoP access token</td>
-              <td>Relay</td>
-              <td>Remote client memory cache</td>
-              <td>
-                Authorize status, connect, and mobile registration endpoints with proof of
-                possession.
-              </td>
-            </tr>
-            <tr>
-              <td>Environment bootstrap credential</td>
-              <td>Local environment server</td>
-              <td>Passed relay -> remote client</td>
-              <td>One-time exchange at the environment <code>/oauth/token</code> endpoint.</td>
-            </tr>
-            <tr>
-              <td>Environment access token</td>
-              <td>Local environment server</td>
-              <td>Remote client</td>
-              <td>Authorize environment HTTP operations and WebSocket ticket issuance.</td>
-            </tr>
-            <tr>
-              <td>WebSocket ticket</td>
-              <td>Local environment server</td>
-              <td>Remote client until consumed</td>
-              <td>Short-lived one-time credential for the WSS upgrade.</td>
-            </tr>
-            <tr>
-              <td>Relay client connector token</td>
-              <td>Cloudflare tunnel API</td>
-              <td>Local server secret store</td>
-              <td>
-                Start the local relay client. It is passed through <code>TUNNEL_TOKEN</code>, not a
-                shell argument.
-              </td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="grid" aria-label="Core flows">
-        <article class="panel">
-          <h2>Flow 1: Link From the Desktop Web UI</h2>
-          <pre class="diagram mermaid">
-sequenceDiagram
-  participant U as Signed-in user
-  participant C as Desktop web UI
-  participant E as Local environment
-  participant R as Relay Worker
-  participant CF as Cloudflare APIs
-  participant RC as Local relay client
-
-  U->>C: Enable T3 Connect for a locally paired environment
-  C->>E: Check relay client availability
-  alt relay client is missing
-    C->>U: Prompt before download and install
-    U->>C: Confirm
-    C->>E: Stream relay-client install RPC
-    E-->>C: Progress stages
-  end
-  C->>R: POST /v1/client/environment-link-challenges (Clerk bearer)
-  R-->>C: Short-lived challenge
-  C->>E: POST /api/connect/link-proof (local relay:write bearer)
-  E->>E: Authenticate, reject forwarded authority, get or create key pair, validate loopback origin
-  E-->>C: Environment-signed link proof
-  C->>R: POST /v1/client/environment-links (Clerk bearer + proof)
-  R->>R: Verify challenge, proof, capabilities, nonce, and loopback origin
-  R->>CF: Reconcile tunnel, ingress, and CNAME
-  R->>R: Upsert user/environment link and issue environment bearer
-  R-->>C: Managed endpoint, relay config, and connector token
-  C->>E: POST /api/connect/relay-config (local relay:write bearer)
-  E->>RC: Start relay client with TUNNEL_TOKEN
-          </pre>
-          <div class="callout">
-            The local link-proof endpoint requires <code>relay:write</code>, rejects forwarded
-            authority headers, and accepts only an exact loopback origin. Environment keypair
-            persistence is atomic across concurrent link attempts.
-          </div>
-          <p>
-            A locally paired mobile client uses the same relay challenge, local proof, relay link,
-            and local relay-config endpoints. The desktop web UI is the surface that checks relay
-            client availability and offers the managed install dialog.
-          </p>
-        </article>
-
-        <article class="panel">
-          <h2>Flow 2: Headless CLI Link</h2>
-          <pre class="diagram mermaid">
-sequenceDiagram
-  participant U as Operator
-  participant CLI as t3 connect CLI
-  participant Clerk as Clerk OAuth
-  participant S as Environment server on next start
-  participant R as Relay Worker
-  participant RC as Local relay client
-
-  U->>CLI: t3 connect link
-  CLI->>CLI: Resolve relay client
-  alt relay client is missing
-    CLI->>U: Confirm managed relay-client install
-    U->>CLI: Confirm
-    CLI->>CLI: Install with terminal progress updates
-  end
-  CLI->>Clerk: Browser PKCE authorization-code flow
-  Clerk-->>CLI: OAuth access and refresh tokens
-  CLI->>CLI: Persist desired cloud-link state
-  U->>S: Start T3 environment server
-  S->>R: Create challenge and submit local signed proof
-  R-->>S: Managed endpoint config and connector token
-  S->>RC: Start relay client
-          </pre>
-          <p>
-            <code>t3 connect login</code> stores authorization without enabling exposure.
-            <code>t3 connect unlink</code> disables exposure while retaining authorization.
-            <code>t3 connect logout</code> also removes the stored CLI authorization.
-          </p>
-        </article>
-
-        <article class="panel">
-          <h2>Flow 3: Remote Connect Bootstrap</h2>
-          <pre class="diagram mermaid">
-sequenceDiagram
-  participant C as Web or mobile client
-  participant Clerk as Clerk
-  participant R as Relay Worker
-  participant E as Managed environment endpoint
-
-  C->>Clerk: Get Clerk session-template JWT
-  C->>R: POST /v1/client/dpop-token (Clerk JWT + DPoP proof)
-  R-->>C: Relay DPoP access token
-  C->>R: POST /v1/environments/:id/connect (relay DPoP)
-  R->>E: POST /api/t3-connect/mint-credential (relay-signed proof)
-  E->>E: Verify relay signer, linked user, scope, lifetime, cnf, and replay guards
-  E-->>R: Bootstrap credential + environment-signed proof
-  R->>R: Verify environment signature, nonce, endpoint, and DPoP binding
-  R-->>C: Managed endpoint + bootstrap credential
-  C->>E: POST /oauth/token (bootstrap credential + DPoP proof)
-  E-->>C: Environment DPoP-bound access token
-  C->>E: POST /api/auth/websocket-ticket
-  E-->>C: One-time WebSocket ticket
-  C->>E: WSS /ws with ticket
-          </pre>
-          <div class="callout">
-            Relay-to-environment control requests disable redirects, use only a reconciled managed
-            endpoint allocation, and require a signed environment response before the relay returns
-            data to the client.
-          </div>
-        </article>
-
-        <article class="panel">
-          <h2>Flow 4: Agent Activity Notifications</h2>
-          <pre class="diagram mermaid">
-sequenceDiagram
-  participant E as Local environment
-  participant R as Relay Worker
-  participant DB as Relay Postgres
-  participant Q as APNs queue
-  participant APNs as Apple Push Notification service
-  participant M as Mobile app
-
-  E->>E: Project publishable thread state and redact failure detail
-  E->>R: POST /v1/environments/:environmentId/threads/:threadId/agent-activity
-  Note over E,R: Environment bearer credential + environment-signed per-state proof
-  R->>R: Verify credential, signature, scope, expiry, and nonce
-  R->>DB: Store current activity row
-  R->>Q: Enqueue push or Live Activity delivery jobs
-  Q->>APNs: Deliver signed APNs request
-  APNs-->>M: Push notification or Live Activity update
-          </pre>
-          <p>
-            The local server publishes a deliberately narrow projection. Failed runs use a fixed
-            redacted summary, and detail strings are capped before publication.
-          </p>
-        </article>
-      </section>
-
-      <section class="grid" aria-label="Managed endpoint lifecycle">
-        <article class="panel half">
-          <h2>Managed Endpoint Reconciliation</h2>
-          <p>
-            Managed endpoint resources are keyed by <code>(userId, environmentId)</code>. The relay
-            reserves a stable hostname and tunnel name before provisioning, then checkpoints the
-            tunnel ID, DNS record ID, and ready state in Postgres.
-          </p>
-          <div class="flow">
-            <div class="step">
-              <strong>1. Reserve deterministic allocation</strong>
-              Hostname and tunnel name derive from relay stage, cloud user, and environment ID.
-            </div>
-            <div class="step">
-              <strong>2. Reuse or create tunnel</strong>
-              Existing named tunnels are reused. Tunnel ingress is rewritten to the validated
-              loopback origin.
-            </div>
-            <div class="step">
-              <strong>3. Reconcile DNS</strong>
-              Existing CNAMEs are updated and duplicate records are removed. Create conflicts are
-              recovered by listing and reconciling the winning record.
-            </div>
-            <div class="step">
-              <strong>4. Mark ready</strong>
-              Connect and status requests use only ready allocations whose hostname still matches
-              the relay-managed namespace.
-            </div>
-          </div>
-        </article>
-
-        <article class="panel half">
-          <h2>Unlink Cleanup</h2>
-          <p>
-            Relay unlink removes the user's managed endpoint allocation before revoking the
-            user/environment link:
-          </p>
-          <ul>
-            <li>delete the managed DNS record if present;</li>
-            <li>delete the Cloudflare tunnel if present;</li>
-            <li>remove the allocation row;</li>
-            <li>revoke the user's environment link; and</li>
-            <li>
-              revoke the environment publication credential only after the final active link for
-              that environment key disappears.
-            </li>
-          </ul>
-          <p>
-            Local unlink stops the relay client and removes the locally persisted relay URL, issuer,
-            linked user, environment publication credential, cloud-mint public key, connector
-            config, and agent-activity preference.
-          </p>
-        </article>
-      </section>
-
-      <section class="panel" aria-label="Cloudflare tunnel operational profile">
-        <h2>Cloudflare Tunnel Operational Profile</h2>
-        <p>
-          Managed tunnels are private application backends, not general-purpose public hosting. The
-          relay provisions one named Cloudflare tunnel and one DNS record per active
-          <code>(userId, environmentId)</code> allocation.
-        </p>
-        <ul>
-          <li>
-            <strong>Lifecycle:</strong> the tunnel is created when an environment is linked, reused
-            across retry-safe reconciliation, kept for the lifetime of that link, and deleted on
-            unlink. If teardown fails, the allocation checkpoint remains so cleanup can be retried.
-          </li>
-          <li>
-            <strong>Origin:</strong> tunnel ingress is restricted to the linked environment server's
-            validated loopback HTTP origin. Arbitrary upstream hosts and raw TCP origins are
-            rejected.
-          </li>
-          <li>
-            <strong>Protocols:</strong> managed endpoints carry HTTPS request/response traffic and
-            WSS connections only. Remote clients use the normal environment HTTP APIs and
-            authenticated WebSocket RPC transport through the tunnel.
-          </li>
-          <li>
-            <strong>Relay-generated traffic:</strong> the hosted relay sends sparse HTTPS health
-            checks and credential-mint requests during status checks and remote connection
-            bootstrap. It does not proxy steady-state remote sessions.
-          </li>
-          <li>
-            <strong>Traffic shape:</strong> expected load is interactive and user-driven. Active
-            remote sessions may keep WebSockets open and exchange terminal, agent, and UI updates;
-            inactive linked environments should carry little or no tunnel traffic.
-          </li>
-          <li>
-            <strong>Capacity planning:</strong> the project is pre-launch, so there is not yet a
-            production bandwidth baseline. Tunnel count grows with active linked user/environment
-            allocations, while bandwidth and concurrent WebSockets grow with active remote use.
-          </li>
-        </ul>
-      </section>
-
-      <section class="panel" aria-label="SSRF and tunnel hardening">
-        <h2>SSRF and Tunnel Hardening</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Risk</th>
-              <th>Implemented control</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>A client asks the relay to tunnel an arbitrary host.</td>
-              <td>
-                The environment and relay both accept managed tunnel origins only for loopback hosts
-                and valid ports.
-              </td>
-            </tr>
-            <tr>
-              <td>A forwarded request tricks local origin validation.</td>
-              <td>
-                The local link-proof handler requires an exact loopback request URL and rejects
-                forwarded host or protocol headers.
-              </td>
-            </tr>
-            <tr>
-              <td>A stored endpoint is replaced with an arbitrary external URL.</td>
-              <td>
-                Connect and status resolve a ready allocation from Postgres and require a hostname
-                under the configured managed endpoint zone.
-              </td>
-            </tr>
-            <tr>
-              <td>A managed endpoint redirects relay egress elsewhere.</td>
-              <td>
-                Relay-to-environment status and mint requests set redirect handling to
-                <code>manual</code>.
-              </td>
-            </tr>
-            <tr>
-              <td>A process behind the tunnel returns attacker-controlled data.</td>
-              <td>
-                The relay verifies environment-signed health and mint responses against the linked
-                environment public key, expected nonce, and request binding.
-              </td>
-            </tr>
-            <tr>
-              <td>A stolen remote access token is replayed.</td>
-              <td>
-                Relay and environment access tokens are DPoP-bound; per-request proofs and replay
-                guards are required.
-              </td>
-            </tr>
-            <tr>
-              <td>The relay client token leaks through process listings or shell parsing.</td>
-              <td>
-                The relay client is spawned without a shell and receives its connector token in
-                <code>TUNNEL_TOKEN</code>.
-              </td>
-            </tr>
-          </tbody>
-        </table>
-        <div class="callout warning">
-          Managed tunnel hostnames live under the configured tunnel DNS zone. Serving them from a
-          dedicated registrable domain with a Public Suffix List entry remains an operational
-          isolation requirement before broad untrusted use.
-        </div>
-      </section>
-
-      <section class="panel" aria-label="Relay HTTP API">
-        <h2>Relay HTTP API</h2>
-        <p>
-          The relay publishes an OpenAPI document at <code>/openapi.json</code>, interactive API
-          docs at <code>/docs</code>, and redirects <code>/</code> to the docs.
-        </p>
-        <table>
-          <thead>
-            <tr>
-              <th>Endpoint</th>
-              <th>Authentication</th>
-              <th>Purpose</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td><code>GET /health</code></td>
-              <td>None</td>
-              <td>Relay health check.</td>
-            </tr>
-            <tr>
-              <td><code>GET /.well-known/oauth-authorization-server</code></td>
-              <td>None</td>
-              <td>Relay OAuth token-exchange discovery metadata.</td>
-            </tr>
-            <tr>
-              <td><code>GET /.well-known/oauth-protected-resource</code></td>
-              <td>None</td>
-              <td>Relay DPoP protected-resource discovery metadata.</td>
-            </tr>
-            <tr>
-              <td><code>GET /v1/environments</code></td>
-              <td>Clerk bearer</td>
-              <td>List environments linked to the signed-in user.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/client/environment-link-challenges</code></td>
-              <td>Clerk bearer</td>
-              <td>Create a short-lived user-bound environment link challenge.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/client/environment-links</code></td>
-              <td>Clerk bearer</td>
-              <td>
-                Verify a local environment proof, reconcile a managed endpoint, and upsert the user
-                link.
-              </td>
-            </tr>
-            <tr>
-              <td><code>DELETE /v1/client/environment-links/:environmentId</code></td>
-              <td>Clerk bearer</td>
-              <td>Remove managed endpoint resources and revoke the user's link.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/client/dpop-token</code></td>
-              <td>Clerk token in token-exchange payload plus DPoP proof</td>
-              <td>Issue a relay DPoP access token for the requested supported scopes.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/environments/:environmentId/status</code></td>
-              <td>Relay DPoP</td>
-              <td>Request and validate a signed environment health response.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/environments/:environmentId/connect</code></td>
-              <td>Relay DPoP</td>
-              <td>Request and validate an environment bootstrap credential.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/mobile/devices</code></td>
-              <td>Relay DPoP</td>
-              <td>Register or update a mobile device for notifications.</td>
-            </tr>
-            <tr>
-              <td><code>POST /v1/mobile/live-activities</code></td>
-              <td>Relay DPoP</td>
-              <td>Register a Live Activity push token.</td>
-            </tr>
-            <tr>
-              <td><code>DELETE /v1/mobile/devices/:deviceId</code></td>
-              <td>Relay DPoP</td>
-              <td>Unregister a mobile device.</td>
-            </tr>
-            <tr>
-              <td>
-                <code>POST /v1/environments/:environmentId/threads/:threadId/agent-activity</code>
-              </td>
-              <td>Environment bearer plus signed publish proof</td>
-              <td>Publish redacted current agent activity for notification delivery.</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="panel" aria-label="Environment HTTP API">
-        <h2>Environment Cloud HTTP API</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Endpoint</th>
-              <th>Authentication</th>
-              <th>Purpose</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td><code>POST /api/connect/link-proof</code></td>
-              <td>Local environment token with <code>relay:write</code></td>
-              <td>Validate local origin and sign an environment link proof.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/connect/relay-config</code></td>
-              <td>Local environment token with <code>relay:write</code></td>
-              <td>Persist linked relay configuration and start the relay client.</td>
-            </tr>
-            <tr>
-              <td><code>GET /api/connect/link-state</code></td>
-              <td>Local environment token with <code>relay:read</code></td>
-              <td>Read the environment's current T3 Connect link state.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/connect/preferences</code></td>
-              <td>Local environment token with <code>relay:write</code></td>
-              <td>Enable or disable agent-activity publication.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/connect/unlink</code></td>
-              <td>Local environment token with <code>relay:write</code></td>
-              <td>Stop the relay client and clear local T3 Connect configuration.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/t3-connect/health</code></td>
-              <td>Relay-signed proof</td>
-              <td>Return a signed environment health response.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/t3-connect/mint-credential</code></td>
-              <td>Relay-signed proof</td>
-              <td>Mint a DPoP-bound one-time bootstrap credential for a remote client.</td>
-            </tr>
-            <tr>
-              <td><code>POST /oauth/token</code></td>
-              <td>Bootstrap credential plus DPoP proof</td>
-              <td>Exchange a bootstrap credential for an environment access token.</td>
-            </tr>
-            <tr>
-              <td><code>POST /api/auth/websocket-ticket</code></td>
-              <td>Environment access token</td>
-              <td>Issue a one-time ticket for the WSS upgrade.</td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="grid" aria-label="Runtime and infrastructure">
-        <article class="panel half">
-          <h2>Relay Client Installation</h2>
-          <p>
-            Desktop web UI availability checks and installs are local WebSocket RPC methods:
-            <code>cloud.getRelayClientStatus</code> and streaming
-            <code>cloud.installRelayClient</code>. The install stream emits the current stage:
-            checking, waiting for lock, downloading, verifying, installing, validating, and
-            activating.
-          </p>
-          <p>
-            The web UI asks for confirmation before installation and displays a custom progress
-            dialog. The CLI invokes the same local relay-client service directly and reports the
-            same progress stages in the terminal.
-          </p>
-        </article>
-
-        <article class="panel half">
-          <h2>Relay Infrastructure</h2>
-          <ul>
-            <li>Cloudflare Worker for the hosted relay HTTP API.</li>
-            <li>PlanetScale Postgres database named <code>t3coderelay</code>.</li>
-            <li>
-              Production uses the shared database; non-production stages use database branches.
-            </li>
-            <li>
-              Cloudflare Hyperdrive with caching disabled and a constrained origin connection limit.
-            </li>
-            <li>Cloudflare tunnel and DNS bindings for managed endpoint reconciliation.</li>
-            <li>Cloudflare APNs delivery queue plus dead-letter queue.</li>
-            <li>A five-minute cron job that prunes expired DPoP replay rows.</li>
-            <li>Axiom OTLP trace dataset, scoped ingest token, and recent-spans view per stage.</li>
-          </ul>
-        </article>
-      </section>
-
-      <section class="panel" aria-label="Deployment configuration">
-        <h2>Deployment Configuration</h2>
-        <table>
-          <thead>
-            <tr>
-              <th>Boundary</th>
-              <th>Configuration</th>
-            </tr>
-          </thead>
-          <tbody>
-            <tr>
-              <td>Relay infrastructure</td>
-              <td>
-                <code>RELAY_API_ZONE_NAME</code>, <code>RELAY_TUNNEL_ZONE_NAME</code>, optional
-                <code>RELAY_DOMAIN</code>, <code>CLERK_PUBLISHABLE_KEY</code>,
-                <code>CLERK_SECRET_KEY</code>, <code>CLERK_JWT_AUDIENCE</code>, and APNs
-                credentials.
-              </td>
-            </tr>
-            <tr>
-              <td>Source-built desktop/server cloud features</td>
-              <td>
-                Optional <code>T3CODE_RELAY_URL</code>, <code>T3CODE_CLERK_PUBLISHABLE_KEY</code>,
-                and <code>T3CODE_CLERK_CLI_OAUTH_CLIENT_ID</code>. Release builds inject public
-                values at build time.
-              </td>
-            </tr>
-            <tr>
-              <td>Web and mobile cloud clients</td>
-              <td>
-                Public Clerk publishable key, Clerk JWT template name, and relay URL. Relay URLs
-                must normalize to an absolute HTTPS origin without credentials, query, fragment, or
-                non-root path.
-              </td>
-            </tr>
-          </tbody>
-        </table>
-      </section>
-
-      <section class="panel" aria-label="Implementation checklist">
-        <h2>Implementation Checklist</h2>
-        <ul>
-          <li>
-            Keep the relay cloud-mint private key hosted-only; install only its public key into
-            environments.
-          </li>
-          <li>
-            Keep environment signing private keys local and persist keypair creation atomically.
-          </li>
-          <li>
-            Require a local <code>relay:write</code> session before linking or changing relay
-            config.
-          </li>
-          <li>Validate relay URLs as secure absolute HTTPS origins before sending credentials.</li>
-          <li>Require loopback-only tunnel origins on both sides of the link-proof boundary.</li>
-          <li>
-            Resolve managed endpoint egress from ready allocation rows, not client-supplied URLs.
-          </li>
-          <li>Disable redirects on relay-to-environment requests.</li>
-          <li>Validate environment-signed response proofs before consuming tunneled responses.</li>
-          <li>Keep tunnel and DNS provisioning retry-safe and deprovision them on unlink.</li>
-          <li>
-            Revoke shared environment publication credentials only after the final active link
-            disappears.
-          </li>
-          <li>Redact and cap local agent failure details before publishing them externally.</li>
-        </ul>
-      </section>
-
-      <section class="panel" aria-label="Standards references">
-        <h2>Standards References</h2>
-        <ul class="source-list">
-          <li>
-            <a href="https://www.rfc-editor.org/rfc/rfc8252">RFC 8252</a>: browser-based OAuth for
-            native apps, used by the CLI PKCE authorization flow.
-          </li>
-          <li>
-            <a href="https://www.rfc-editor.org/rfc/rfc8693">RFC 8693</a>: OAuth token exchange,
-            used for Clerk-token to relay-DPoP-token exchange.
-          </li>
-          <li>
-            <a href="https://www.rfc-editor.org/rfc/rfc9449">RFC 9449</a>: DPoP proof of possession,
-            used for relay and environment access tokens.
-          </li>
-        </ul>
-      </section>
-    </main>
-    <script type="module">
-      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
-
-      mermaid.initialize({
-        startOnLoad: false,
-        securityLevel: "strict",
-        theme: "base",
-        themeVariables: {
-          fontFamily: 'ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
-          primaryColor: "#eef4ff",
-          primaryBorderColor: "#1457d9",
-          primaryTextColor: "#171717",
-          lineColor: "#62646b",
-          signalColor: "#171717",
-          signalTextColor: "#171717",
-          noteBkgColor: "#fff6e6",
-          noteTextColor: "#171717",
-          actorBkg: "#fbfbf8",
-          actorBorder: "#62646b",
-          actorTextColor: "#171717",
-        },
-        flowchart: {
-          htmlLabels: true,
-          curve: "basis",
-          padding: 18,
-        },
-        sequence: {
-          showSequenceNumbers: true,
-          mirrorActors: false,
-          rightAngles: false,
-        },
-      });
-
-      await mermaid.run({ querySelector: ".diagram.mermaid" });
-
-      for (const svg of document.querySelectorAll(".diagram.mermaid svg")) {
-        const viewBox = svg.getAttribute("viewBox");
-        const width = viewBox?.split(/\s+/).map(Number)[2];
-        if (Number.isFinite(width) && width > 0) {
-          svg.style.setProperty("width", `${Math.ceil(width)}px`, "important");
-          svg.style.setProperty("max-width", "none", "important");
-        }
-      }
-    </script>
-  </body>
-</html>
diff --git a/docs/internals/t3-connect.md b/docs/internals/t3-connect.md
index 6f796123e98b..bf02eb3538be 100644
--- a/docs/internals/t3-connect.md
+++ b/docs/internals/t3-connect.md
@@ -1,273 +1,81 @@
 # T3 Connect
 
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-T3 Connect uses one Clerk application for web, desktop, and mobile authentication. The relay verifies
-two kinds of bearer credential: template JWTs generated from the `t3-relay` template with the shared
-`t3-code-relay` audience, and Clerk OAuth tokens issued to the CLI. `verifyRelayClientBearerToken` in
-`infra/relay/src/http/Api.ts` tries the template/session path first and falls back to OAuth
-verification (`acceptsToken: "oauth_token"`), so the CLI's OAuth credential works without a JWT
-template.
-
-For the wider system diagram, see
-[t3-code-connect-auth-flow.html](./t3-code-connect-auth-flow.html).
-
-## Application Keys
-
-T3 Connect is disabled in a fresh clone. To enable it for source builds against the production
-deployment, copy the repository-root example file:
-
-```sh
-cp .env.example .env
-```
-
-`.env.example` carries the production public identifiers (the same values baked into official
-release builds). To target a different Clerk application or relay, set the values yourself in a
-repository-root `.env` or `.env.local` file:
-
-```dotenv
-T3CODE_CLERK_PUBLISHABLE_KEY=<publishable key>
-T3CODE_CLERK_JWT_TEMPLATE=<JWT template name>
-T3CODE_CLERK_CLI_OAUTH_CLIENT_ID=<public OAuth application client ID>
-T3CODE_RELAY_URL=https://relay.example.com
-```
-
-The shared client loader projects these canonical values into framework-specific `VITE_*` and
-`EXPO_PUBLIC_*` aliases. Existing aliases remain accepted as overrides for compatibility, but new
-client configuration should use the canonical names.
-
-Configuration precedence is:
-
-1. Process or CI environment variables.
-2. Repository-root `.env.local`.
-3. Repository-root `.env`.
-
-The Clerk publishable key, JWT template name, CLI OAuth client ID, and relay URL are public
-identifiers, not secrets.
-Web, desktop, mobile, and bundled server builds statically inject the values they consume during
-their build step. A built artifact does not need an environment file at runtime. CI release builds
-should set `T3CODE_CLERK_PUBLISHABLE_KEY`, `T3CODE_CLERK_JWT_TEMPLATE`,
-`T3CODE_CLERK_CLI_OAUTH_CLIENT_ID`, and `T3CODE_RELAY_URL` before building. EAS preview and
-production builds only need the Clerk publishable key, JWT template name, and relay URL in their EAS
-environment.
-
-When any client-facing public value is absent, cloud UI is omitted. The `t3 connect` command group is
-always registered: when the CLI public values are absent, `makeCli` in `apps/server/src/bin.ts`
-registers a hidden fallback `connect` command that reports the missing configuration instead of
-silently vanishing from help. The bundled server still accepts runtime overrides for self-hosted or
-operator-managed deployments.
-
-For a hosted relay deployment, copy `infra/relay/.env.example` to `infra/relay/.env`. The relay
-deployment reads `RELAY_DOMAIN`, `RELAY_API_ZONE_NAME`, `RELAY_TUNNEL_ZONE_NAME`,
-`CLERK_PUBLISHABLE_KEY`, and `CLERK_JWT_AUDIENCE` through Effect `Config`. There are no checked-in
-deployment defaults.
-`vp run --filter t3code-relay deploy` invokes Alchemy from the relay directory, so Alchemy loads
-`infra/relay/.env`. After a successful deployment, the wrapper updates the repository-root `.env`
-with the deployed HTTPS relay URL. The relay still requires
-`CLERK_SECRET_KEY` as an Alchemy secret. Never put `CLERK_SECRET_KEY` in a client application
-environment or commit it to the repository.
-
-The `prod` Alchemy stage owns the retained PlanetScale database. Non-production stages reference
-that database and provision isolated PlanetScale branches, so deploy `prod` before creating a
-personal developer stage.
-
-## Headless CLI OAuth Application
-
-The `t3 connect` commands authorize a headless environment with a separate Clerk OAuth application.
-This uses an OAuth public client with PKCE, so the CLI stores no client secret.
-
-In **Clerk Dashboard > OAuth applications**:
-
-1. Create an OAuth application for the T3 CLI.
-2. Enable the **Public** option so authorization-code exchange uses PKCE.
-3. Add **both** allowed redirect URIs:
-   - `http://127.0.0.1:34338/callback` for the loopback listener;
-   - `https://app.t3.codes/connect/callback` for the hosted out-of-band flow. This is
-     `connectCallbackUrl(DEFAULT_HOSTED_APP_URL)` from `packages/shared/src/connectAuth.ts`, so a
-     custom `T3CODE_HOSTED_APP_URL` means `$T3CODE_HOSTED_APP_URL/connect/callback` instead.
-     Omitting it breaks headless and SSH authorization.
-4. Enable the `openid`, `profile`, and `email` scopes.
-5. Set `T3CODE_CLERK_CLI_OAUTH_CLIENT_ID` in the repository-root `.env` file and release build
-   environment to the generated public client ID.
-
-Both CLI flows start at the hosted `/connect` page (`buildConnectAuthorizeRequestUrl` in
-`packages/shared/src/connectAuth.ts`), which waits for a Clerk session and then forwards the request
-to Clerk's `/oauth/authorize`. The CLI never opens `/oauth/authorize` directly: a signed-out browser
-sent there goes through Clerk's sign-in redirect, which drops the authorize query parameters and
-fails the flow with `unsupported_response_type` or an empty `state` (#5051). The loopback flow marks
-the request with a `port` fragment parameter so the hosted page asks Clerk to redirect the
-authorization code straight to `http://127.0.0.1:<port>/callback`; the out-of-band flow omits it and
-uses the hosted `/connect/callback` page instead. The CLI derives Clerk's frontend API URL from the
-publishable key and calls only the `/oauth/token` endpoint directly. The relay is not involved in
-the OAuth handshake; it only validates the issued Clerk bearer token when the CLI manages an
-environment link.
-
-The connect command group is:
-
-```sh
-t3 connect            # default: onboarding
-t3 connect login
-t3 connect link       # --publish-only
-t3 connect status     # --json
-t3 connect publish    # --disable
-t3 connect unlink
-t3 connect logout
-```
-
-`t3 serve` is a separate top-level command, not a connect subcommand.
-
-`t3 connect login` opens the Clerk authorization flow and stores the CLI credential without enabling
-cloud exposure. `t3 connect link` installs the pinned managed `cloudflared` binary when needed,
-authorizes when needed, and records durable intent to expose the environment. It works without a
-running T3 server. The next `t3 serve` or `t3 start` reconciles the relay link and launches the
-managed tunnel. `t3 connect unlink` records disabled intent immediately, stops a reachable running
-connector, and attempts to revoke the relay-side environment record. It retains the stored CLI
-authorization so `t3 connect link` can re-enable exposure without another browser flow. `t3 connect
-logout` performs the same cleanup and removes the stored CLI authorization.
-
-The background service has an independent lifecycle. Connect setup may offer to install it, but
-logout leaves it running; manage it with `t3 service status`, `install`, `update`, and `uninstall`.
-
-### Headless and SSH authorization
-
-The loopback OAuth callback listener binds to port `34338`. That path only works when a browser on
-the same machine can reach it, so `authorizeCli` in `apps/server/src/cli/connect.ts` automatically
-selects the out-of-band flow when `--headless` is passed or when it detects SSH through
-`SSH_CONNECTION` or `SSH_TTY`. The out-of-band flow prints the hosted `/connect` authorization URL
-and accepts a pasted authorization code, so no port is involved.
-
-Port forwarding is therefore optional, not required. Forward the port only if you specifically want
-the loopback flow over SSH:
-
-```sh
-ssh -L 34338:127.0.0.1:34338 <host>
-```
-
-## JWT Template
-
-In **Clerk Dashboard > JWT templates**, create a template with:
-
-| Setting | Value                        |
-| ------- | ---------------------------- |
-| Name    | `t3-relay`                   |
-| Claims  | `{ "aud": "t3-code-relay" }` |
-
-Set `T3CODE_CLERK_JWT_TEMPLATE=t3-relay` in the repository-root `.env`, and set
-`CLERK_JWT_AUDIENCE=t3-code-relay` in `infra/relay/.env`. Define `CLERK_JWT_TEMPLATE` and
-`CLERK_JWT_AUDIENCE` in the production relay deployment environment as well. The stable `aud` value
-is shared by production and non-production relay stages. The client-facing `T3CODE_RELAY_URL` still
-selects the concrete relay deployment, but changing that URL does not require a JWT template change.
-
-## Desktop OAuth Redirect Allowlist
-
-The desktop app opens OAuth in the system browser and returns to the app with a custom URL scheme.
-In **Clerk Dashboard > Native applications**, enable the Native API and add these entries under the
-mobile SSO redirect allowlist:
-
-```text
-t3code-dev://app/
-t3code://app/
-```
-
-Local desktop development uses `t3code-dev://app`, while packaged builds use `t3code://app`. Add the
-matching origin to each Clerk instance's Backend API `allowed_origins` array as well. The development
-Clerk instance should only need `t3code-dev://app`; the production Clerk instance should only need
-`t3code://app`. `@clerk/electron` owns the native request adapter, encrypted Clerk token persistence,
-external-browser OAuth transport, and callback delivery for initial sign-in and linked-account flows.
-
-There is currently no Dashboard UI for `allowed_origins`. Preserve any existing entries and update
-the instance through the Backend API:
-
-```sh
-curl -X PATCH https://api.clerk.com/v1/instance \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $CLERK_SECRET_KEY" \
-  -d '{"allowed_origins":["t3code://app"]}'
-```
-
-Never put `CLERK_SECRET_KEY` in the desktop app, a client-facing environment file, or a build
-artifact.
-
-## Desktop Passkeys
-
-The production macOS bundle ID is `com.t3tools.t3code`. To enable native passkeys:
-
-1. Create an explicit macOS App ID for `com.t3tools.t3code` in the Apple Developer portal and enable
-   **Associated Domains**.
-2. Create a compatible macOS provisioning profile for that App ID and the certificate used to sign
-   the distributed app.
-3. In Clerk's Native API settings, add an iOS app with the same Apple Team ID and bundle ID. This is
-   also the configuration point for Electron/macOS passkeys.
-4. Confirm Clerk serves `https://<frontend-api>/.well-known/apple-app-site-association` and that
-   `webcredentials.apps` contains `<TEAM_ID>.com.t3tools.t3code`.
-5. Set the local or CI signing configuration described below.
-
-For a local signed build, add these values to `.env.local` or export them before invoking the
-desktop artifact command:
-
-```dotenv
-T3CODE_APPLE_TEAM_ID=ABC1234567
-T3CODE_MACOS_PROVISIONING_PROFILE=/absolute/path/to/t3code.provisionprofile
-# Optional: comma-separated override when Clerk's RP ID differs from the Frontend API hostname.
-T3CODE_CLERK_PASSKEY_RP_DOMAINS=example.clerk.accounts.dev,clerk.example.com
-```
-
-When `T3CODE_CLERK_PASSKEY_RP_DOMAINS` is absent, the build derives the RP domain from
-`T3CODE_CLERK_PUBLISHABLE_KEY`. Signed macOS builds fail early if the Team ID, provisioning profile,
-or RP-domain configuration is missing. The generated main-app entitlements include every configured
-`webcredentials:<domain>` entry; helper apps keep Electron's minimal default entitlements.
-
-The normal `dev:desktop` launcher is unsigned and cannot complete macOS passkey ceremonies. For
-renderer HMR, build and install a signed app first, run the renderer dev server, then launch the
-installed app executable with `VITE_DEV_SERVER_URL` and `T3CODE_PORT` set. Rebuild the signed app
-after native dependency, main-process, preload, entitlement, provisioning, or signing changes;
-renderer-only changes can reuse the installed app.
-
-For the default development ports, run `pnpm dev:web` in one terminal and launch the installed
-binary from another:
-
-```sh
-VITE_DEV_SERVER_URL=http://127.0.0.1:5733 \
-T3CODE_PORT=13773 \
-  "/Applications/T3 Code (Alpha).app/Contents/MacOS/T3 Code (Alpha)"
-```
-
-After changing Associated Domains, bump the build version before rebuilding; macOS may otherwise
-reuse stale Shared Web Credentials metadata for the same app/version pair.
-
-Verify the installed bundle before testing:
-
-```sh
-codesign --verify --deep --strict "/Applications/T3 Code (Alpha).app"
-codesign -d --entitlements :- "/Applications/T3 Code (Alpha).app"
-```
-
-The current mobile UI uses Clerk's native authentication view. If a future mobile browser OAuth
-flow uses a custom redirect URI, add that exact URI to the same allowlist.
-
-## Sign-in Surfaces
-
-Signed-in users manage T3 Connect under **Connections**. The settings sidebar also has dedicated
-controls, rendered by `SettingsSidebarNav.tsx`: `T3ConnectSidebarSignIn` in the footer shows a
-**Sign in to T3 Connect** button while signed out, and `T3ConnectSidebarAvatar` shows a Clerk
-`UserButton` account control while signed in. Both are gated on cloud public configuration.
-Desktop renders the same web bundle, so it has them too. The waitlist enrollment flow from the
-private beta was removed when Connect went GA; sign-up is open unless a Clerk restriction below is
-enabled.
-
-## Restricting Sign-ups: Known-User Allowlist
-
-For a closed deployment where all permitted users are known in advance, restrict sign-up to
-permitted email addresses or domains:
-
-1. In **Clerk Dashboard > Restrictions > Allowlist**, add each permitted email address or email
-   domain.
-2. Enable the allowlist and save.
-3. Alternatively, enable **Restricted mode** when all new users must be explicitly invited or
-   manually created.
-
-Do not enable an empty allowlist: it blocks all new sign-ups.
-
-Clerk allowlists control who can sign up. They do not revoke an existing user's active cloud
-access. To remove an already-created user's access, ban that user in Clerk so their active
-sessions are ended and future sign-ins are rejected.
+T3 Connect uses Clerk for cloud identity. The relay manages environment links,
+credentials for reaching environments, and managed tunnel allocations. After
+bootstrap, clients send application traffic through the environment's tunnel
+hostname; the relay Worker does not proxy their HTTP or WebSocket sessions.
+
+Clerk, deployment, and native authentication setup live in the
+[Connect setup runbook](../operations/connect-setup.md).
+
+## The relay is a trusted broker
+
+An authenticated cloud user still needs an active environment link. The relay
+asks that environment to mint a one-time bootstrap credential bound to the
+client's DPoP key. The client exchanges it directly with the environment for an
+[environment session](./environment-auth.md). The relay never receives that
+session token, and possessing the bootstrap credential alone does not permit
+redeeming it without the client's private key.
+
+Both sides authenticate this exchange. The environment accepts only bounded,
+replay-guarded relay proofs for its own identity, linked user, and requested
+operation. Signed environment responses bind the result to the request nonce;
+mint responses also bind the credential to the client proof key. The relay
+verifies those bindings before returning a credential. This prevents a different
+process behind the tunnel from impersonating the linked environment. The checks
+meet in the
+[environment cloud handlers](../../apps/server/src/cloud/http.ts) and
+[relay connector](../../infra/relay/src/environments/EnvironmentConnector.ts).
+
+The relay holds the signing authority for mint requests. DPoP protects an honest
+exchange from credential reuse; it does not make a compromised relay signing
+key harmless. Keep that trust assumption explicit when changing the protocol.
+
+Managed tunnels expose only a validated loopback HTTP origin. Link proof checks
+reject forwarded authority headers, and the relay resolves endpoints from its
+own managed allocations rather than a caller-supplied URL. Health and mint
+requests must not follow redirects. These restrictions keep endpoint discovery
+from turning into arbitrary relay egress or exposing another service on the
+environment host.
+
+## A link outlives a connector process
+
+CLI authorization, desired exposure, and a running connector have different
+lifetimes. Linking can record intent while the server is stopped. Startup
+reconciles that intent. CLI logout removes the stored cloud credential and
+disables exposure without uninstalling the environment's background service.
+
+Managed allocations belong to a user/environment pair. Provisioning checkpoints
+external tunnel and DNS resources so retries can reconcile partial work. A
+normal shutdown of a CLI-managed link releases its tunnel to avoid paying for
+an idle resource, retaining the hostname reservation for the next startup.
+It also retains the allocation record so the environment remains "offline"
+rather than becoming "not authorized".
+
+Two cases must retain the tunnel across shutdown. A link installed through a
+client has no startup provisioning path and depends on its stored connector
+token. An update handoff immediately starts a replacement server, and replacing
+the tunnel would add routing propagation delay to every update. These exceptions
+belong to [shutdown handling](../../apps/server/src/cloud/http.ts).
+
+Release and unlink claim the allocation generation before deleting external
+resources. A delayed cleanup must not delete a tunnel reused by a concurrent
+restart or relink. Unlink commits authorization revocation before external
+teardown, because a database failure must leave the active link usable. Failed
+teardown retains enough state to retry. See the
+[managed endpoint lifecycle](../../infra/relay/src/environments/ManagedEndpointProvider.ts).
+
+## OAuth traps
+
+Interactive clients and the headless CLI use the same Clerk application but
+different credentials. The relay accepts both session-template JWTs and CLI
+OAuth tokens; requiring a JWT template for the CLI would reject valid logins.
+The CLI is a public OAuth client using PKCE and stores no client secret.
+
+CLI authorization starts on the hosted `/connect` page so sign-in completes
+before entering Clerk's authorize endpoint. Sending a signed-out browser
+straight to that endpoint loses the authorize parameters during the sign-in
+redirect. The [shared flow](../../packages/shared/src/connectAuth.ts) preserves
+PKCE and state for both loopback and pasted-code callbacks. SSH and headless
+sessions use the pasted-code flow because the browser cannot ordinarily reach a
+listener on the remote machine.
diff --git a/docs/internals/terminal-runtime.md b/docs/internals/terminal-runtime.md
new file mode 100644
index 000000000000..ca5f0d46ead6
--- /dev/null
+++ b/docs/internals/terminal-runtime.md
@@ -0,0 +1,44 @@
+# Terminal runtime
+
+The environment server owns PTYs, session lifetime, and retained output. Every
+client, including the desktop renderer, attaches through the environment connection.
+This lets clients reconnect or share a running session. Renderer choices stay local
+to each client and do not change terminal contracts.
+
+## Output and retention
+
+[Terminal history](../../apps/server/src/terminal/Manager.ts) is incremental.
+PTY callbacks append new chunks; live events carry only those chunks. Materializing
+or copying full scrollback on every callback makes output cost grow with retained
+history, so snapshots and coalesced persistence are the materialization boundaries.
+Persistence queues the mutable history buffer and reads its latest value when the
+write runs. Clear, restart, and close must drain writes before completing their
+lifecycle boundary.
+
+Server history is capped at 5,000 lines and 8 MiB of UTF-8 text per terminal, so a
+long unterminated line cannot bypass retention. Eviction removes the oldest output
+without splitting Unicode code points; live output is not truncated. Release
+discarded chunk references immediately, even if array compaction happens later.
+Client buffers have a separate 512 KiB cap. Measure throughput with full scrollback
+when changing this path.
+
+Restoration must read only the bounded tail of current or legacy history files,
+skip any incomplete UTF-8 prefix, and apply the line limit. Close the read handle
+before rewriting the capped file. Reading whole old logs would defeat the memory
+bound during startup.
+
+## Renderer ownership
+
+Android and web use the same `libghostty-vt` C ABI for terminal behavior. Platform
+adapters own drawing and input integration, and React stays out of terminal frames.
+The web adapter shares one WebAssembly instance per browser tab while each terminal
+owns and frees its own handles. The canonical upstream pin is
+[`native/libghostty-vt/VERSION`](../../native/libghostty-vt/VERSION); both native and
+web artifacts must be rebuilt when it changes. Web embeds the revision in its build
+info so the ABI check can detect drift without a second pin.
+
+Restoring scrollback must not send terminal replies to the current shell. Historical
+device queries can otherwise provoke fresh replies that appear as junk at the
+prompt. The server strips query/response traffic from retained history, and the
+[web renderer](../../apps/web/src/terminal/ghostty/core.ts) detaches its PTY writer
+during replay. Preserve both protections when changing retention or renderer code.
diff --git a/docs/internals/voice-input.md b/docs/internals/voice-input.md
index dd37f2a86957..55e3007a4872 100644
--- a/docs/internals/voice-input.md
+++ b/docs/internals/voice-input.md
@@ -1,102 +1,20 @@
 # Voice input
 
-> For maintainers. Using T3 Code? See [voice input on iPhone](../user/composer.md#voice-input-on-iphone).
-
-Voice input produces editable composer text. The current implementation records on the client and
-transcribes locally with Apple's `SpeechAnalyzer` and `SpeechTranscriber` on supported iOS 26+
-devices. Environment-provided transcription and transcription on web and desktop are not implemented.
-
-## Current boundaries
-
-The shared [`VoiceInputController`][controller] in `packages/client-runtime` owns preparation,
-recording, transcription, cancellation, temporary-file cleanup, and insertion into the captured
-draft selection. Applications import it through the [voice-input entry point][voice-input] as
-`@t3tools/client-runtime/voice-input`. Its dependencies separate capture from transcription; the
-controller imports neither React Native nor an Apple transcription API.
-
-The shared [transcription contract][transcription] defines `VoiceTranscriber`,
-`PreparedVoiceTranscription`, and transcription errors. The controller calls `getTranscriber()` once
-at the start of an operation, before asking for microphone permission. Preparation returns a resolved
-locale and a bound `transcribe` function. The controller retains that result for the recording, so a
-selection change cannot prepare with one implementation and transcribe with another.
-
-[`useVoiceInputController`][hook] supplies Expo audio capture, microphone permissions, audio-session
-management, waveform samples, and app and navigation lifecycle handling. It normalizes Expo's
-`mediaServicesDidReset` into a generic recorder error. [`voiceTranscription.ios.ts`][ios] adapts
-`@react-native-ai/apple` through `getLocalVoiceTranscriber()`, capturing the requested device locale
-and binding the prepared transcriber to Apple's resolved locale. The other-platform binding returns
-no local transcriber. That result describes the local implementation, not whether a client could use
-an environment's transcription service.
-
-Mobile's [`voiceInputPresentation.ts`][presentation] maps shared state to toolbar labels and actions.
-Waveform and toolbar rendering stay in mobile. The composer edits draft text without selecting a
-speech vendor.
-Recording captures the draft owner, revision, text, and selection. A late transcript cannot overwrite
-a different or edited draft. Only normal message submission sends the resulting text to an agent.
-
-Each operation passes one `AbortSignal` through preparation and transcription. Cancellation
-invalidates the operation and aborts that signal immediately. Implementations settle their promises
-only after their underlying work stops. The Apple binding checks cancellation between asynchronous
-steps but cannot interrupt an in-flight native request. The controller retains its session until
-that work settles, ignores its result, and cleans up the recording.
-
-## Ownership decisions
-
-The extension boundary distinguishes transcription on the client device from transcription through
-the composer's environment. These constraints apply when adding selectable transcription services:
-
-- Local means the client device, regardless of which machine hosts the environment. A device's lack
-  of local recognition does not prevent it from recording audio for an environment service.
-- Remote service configuration and API keys belong to the environment. The environment calls the
-  external service. Clients receive service identifiers, labels, and availability information, never
-  credential values. Transcription services are independent of coding-agent `providerInstances`;
-  selecting OpenAI for transcription does not select Codex for the thread.
-- The client owns its transcription preference, scoped by stable `environmentId`. Its choices are
-  supported local recognition and the services exposed by the composer's environment. A service ID
-  is meaningful only within that environment. Different clients can make different choices.
-- Resolve and capture the environment, selected service, and locale when an operation starts.
-  Preparation and transcription use the same selection; preference changes affect the next
-  recording. Capture environment identity explicitly rather than recovering it from a draft key.
-  Keep the existing draft-owner and revision checks before inserting text.
-- If the selected option is unavailable, report that state and let the user choose another option.
-  A local failure must not silently upload audio, and a disconnected environment must not redirect
-  a recording to another environment or service.
-- Transcription audio is temporary input, separate from durable chat attachments and messages.
-  Remote adapters need cancellation of upload and transcription where supported, cleanup after
-  success, failure, or cancellation, and the same protection against late results as local transcription.
-
-## Existing integration points
-
-[`ServerSettingsService`][settings] and [`ServerSecretStore`][secrets] provide environment-owned
-configuration and secret persistence. Existing settings redaction handles coding-provider environment
-variables only. Any transcription credential fields need their own explicit separation and redaction
-before settings responses or subscriptions reach client caches.
-
-[`ExecutionEnvironmentCapabilities`][capabilities] handles version skew. Remote transcription must be
-opt-in: a missing transcription capability means unsupported. The authenticated server-config
-subscription and [shared environment state][server-state] already distribute configuration per
-environment. A transcription service catalog belongs behind that capability and authenticated
-boundary. Older servers expose no remote transcription choices.
-
-The [attachment upload contracts][uploads] and [shared upload operations][attachment-state] provide a
-pattern for authorized binary uploads through an environment, including remote connections. Their
-existing chat-attachment retention is not a transcription cleanup policy.
-
-Future service selection and environment requests belong alongside the controller in
-`packages/client-runtime`, with wire contracts in `packages/contracts`. Capture and native local
-recognition remain client-specific. An environment-backed transcriber implements the same shared
-contract, with its environment and service bound when selected. The controller does not own service
-credentials, provider SDKs, or transport selection.
-
-[controller]: ../../packages/client-runtime/src/voice-input/controller.ts
-[voice-input]: ../../packages/client-runtime/src/voice-input/index.ts
-[transcription]: ../../packages/client-runtime/src/voice-input/transcription.ts
-[hook]: ../../apps/mobile/src/features/voice-input/useVoiceInputController.ts
-[presentation]: ../../apps/mobile/src/features/voice-input/voiceInputPresentation.ts
-[ios]: ../../apps/mobile/src/native/voiceTranscription.ios.ts
-[settings]: ../../apps/server/src/serverSettings.ts
-[secrets]: ../../apps/server/src/auth/ServerSecretStore.ts
-[capabilities]: ../../packages/contracts/src/environment.ts
-[server-state]: ../../packages/client-runtime/src/state/server.ts
-[uploads]: ../../packages/contracts/src/assets.ts
-[attachment-state]: ../../packages/client-runtime/src/state/attachments.ts
+Transcription edits a composer draft. It does not submit an agent turn. Audio is
+temporary client input, and only normal message submission sends the resulting
+text. The current implementation transcribes locally on supported iOS devices;
+environment-backed transcription is not implemented.
+
+The [shared controller](../../packages/client-runtime/src/voice-input/controller.ts)
+owns the operation while the client supplies capture and transcription. Preparation
+binds the transcriber and resolved locale for the whole recording. Draft ownership,
+text, and revision are captured before recording and checked before insertion, so
+a late transcript cannot overwrite a draft that was edited or replaced.
+
+Cancellation invalidates a result immediately, but resources stay owned until the
+underlying work settles. Apple's native transcription call cannot be interrupted
+once started. Releasing the session or deleting its recording when the abort signal
+fires would race that work. The [transcription contract](../../packages/client-runtime/src/voice-input/transcription.ts)
+therefore requires implementations to settle only after their work has stopped;
+the [Apple binding](../../apps/mobile/src/native/voiceTranscription.ios.ts) checks
+cancellation between native calls and discards late results.
diff --git a/docs/internals/work-artifacts.md b/docs/internals/work-artifacts.md
deleted file mode 100644
index 157a6174507d..000000000000
--- a/docs/internals/work-artifacts.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Engineering work artifacts
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-Keep planned work out of the source tree. Code search should return the product as it exists, not a mix of current behavior and abandoned intentions.
-
-## Current facts belong in the docs
-
-Put durable architecture, constraints, and operational knowledge in `docs/internals/` or `docs/operations/`. Write these documents in the present tense and update them with the code they describe.
-
-When the reason for a decision will matter after implementation, record it in the relevant internal document. Use a separate decision record under `docs/internals/` only when the rationale does not fit cleanly beside the current architecture.
-
-## Planned work belongs in GitHub
-
-Track active maintainer work in its GitHub issue or project item. The tracking item should state the outcome, constraints, and acceptance criteria, then link the pull requests that implement it. Split large efforts into one durable specification and small work items that can each close independently.
-
-Close completed items. Update or delete invalidated work before starting the next implementation session. External proposals follow [CONTRIBUTING.md](../../CONTRIBUTING.md) and belong in Ideas discussions rather than issues.
-
-## Temporary work stays temporary
-
-Keep agent scratch files, exploratory research, transcripts, and session handoff notes outside the worktree. They are inputs to the work, not project documentation.
-
-`.plans/` is gitignored as a safety net for legacy tools. Its presence does not make it an accepted project artifact. Pull requests must not add implementation plans or temporary research under another name.
-
-A pull request records what changed and why. If a fact must survive after the pull request merges, update the relevant documentation. Otherwise, the tracking item and pull request are the record.
diff --git a/docs/internals/workspace-layout.md b/docs/internals/workspace-layout.md
deleted file mode 100644
index e933e4528915..000000000000
--- a/docs/internals/workspace-layout.md
+++ /dev/null
@@ -1,63 +0,0 @@
-# Workspace layout
-
-> For maintainers. Using T3 Code? See [docs/user](../user/).
-
-A pnpm workspace driven by [vite-plus](https://vite.plus) (`vp`). See [scripts.md](./scripts.md) for
-the task commands.
-
-## apps
-
-- `apps/server` (`t3`): the execution runtime and the published CLI. Owns orchestration, provider
-  drivers, checkpointing, VCS, terminals, filesystem access, auth, and the HTTP + WebSocket surface.
-  Also serves the built web app.
-- `apps/web` (`@t3tools/web`): React + Vite UI. Consumes the shared client runtime and adds routing,
-  components, and web-specific platform layers.
-- `apps/desktop` (`@t3tools/desktop`): Electron shell. Supervises a desktop-scoped `t3` backend,
-  loads the web bundle over the `t3code://` protocol, and owns SSH-managed remote environments.
-- `apps/mobile` (`@t3tools/mobile`): Expo/React Native client. Same client runtime composition as
-  web, different platform layer and UI.
-- `apps/marketing` (`@t3tools/marketing`): Astro marketing site.
-
-## packages
-
-- `packages/contracts` (`@t3tools/contracts`): shared Effect Schema definitions. RPC group,
-  orchestration commands/events/read model, auth scopes, environment descriptors, settings.
-- `packages/shared` (`@t3tools/shared`): framework-agnostic utilities used by server and clients
-  (`DrainableWorker`, git and source-control helpers, relay auth and signing, DPoP, semver, logging,
-  observability, and more).
-- `packages/client-runtime` (`@t3tools/client-runtime`): connection lifecycle, authorization, RPC
-  session, environment registry, and Atom-based domain state shared by web and mobile. See its
-  [README](../../packages/client-runtime/README.md).
-- `packages/ssh` (`@t3tools/ssh`): SSH config parsing, auth prompts, command execution, and the
-  tunnel/environment manager behind desktop-managed SSH environments.
-- `packages/tailscale` (`@t3tools/tailscale`): Tailscale CLI wrapper, including the
-  `ensureTailscaleServe` / `disableTailscaleServe` serve lifecycle the server drives.
-- `packages/effect-acp` (`effect-acp`): Effect client and agent implementation of the Agent Client
-  Protocol, used by ACP-speaking provider drivers.
-- `packages/effect-codex-app-server` (`effect-codex-app-server`): Effect client for the
-  `codex app-server` JSON-RPC protocol.
-
-## infra
-
-- `infra/relay` (`t3code-relay`): the hosted T3 Connect relay, deployed with Alchemy. Handles
-  environment discovery, cloud-side records, and mobile notifications. It is not in the hot path;
-  after connect, client traffic goes directly to the environment. See
-  [t3-connect.md](./t3-connect.md).
-
-## Other top-level directories
-
-- `scripts/`: workspace tooling run through `vp run`. Dev runner, desktop artifact builds, release
-  helpers, mobile static checks and showcase capture, update-manifest merging.
-- `assets/`: brand and app icon sources per channel (`dev`, `nightly`, `prod`).
-- `patches/`: pnpm patches for pinned upstream dependencies.
-- `oxlint-plugin-t3code/`: repo-specific lint rules.
-- `experiments/`: throwaway prototypes. Not part of the shipped build.
-- `docs/`: this documentation tree.
-
-## Import conventions
-
-`@t3tools/shared` and `@t3tools/client-runtime` use explicit subpath exports with no barrel index and
-no root export. Import the narrow path (`@t3tools/shared/DrainableWorker`,
-`@t3tools/client-runtime/state/threads`) rather than the package root. Files that are not exported
-are implementation details. `@t3tools/contracts` does export a root alongside `./settings` and
-`./relay`.
diff --git a/docs/operations/connect-setup.md b/docs/operations/connect-setup.md
new file mode 100644
index 000000000000..49b93e49c9c4
--- /dev/null
+++ b/docs/operations/connect-setup.md
@@ -0,0 +1,126 @@
+# T3 Connect setup
+
+Deployment and client configuration for T3 Connect. The [architecture note](../internals/t3-connect.md)
+explains the trust boundaries; the [relay README](../../infra/relay/README.md#deployment) owns relay
+provisioning instructions.
+
+## Public application configuration
+
+T3 Connect is disabled in a fresh clone. To build against the production deployment, copy the
+repository-root example:
+
+```sh
+cp .env.example .env
+```
+
+For another deployment, set these values in the repository-root `.env` or `.env.local`:
+
+```dotenv
+T3CODE_CLERK_PUBLISHABLE_KEY=<publishable key>
+T3CODE_CLERK_JWT_TEMPLATE=<JWT template name>
+T3CODE_CLERK_CLI_OAUTH_CLIENT_ID=<public OAuth application client ID>
+T3CODE_RELAY_URL=https://relay.example.com
+```
+
+Process variables take precedence over `.env.local`, then `.env`. Use these canonical names;
+the build loader supplies framework-specific aliases. These values are public identifiers.
+`CLERK_SECRET_KEY` belongs only in the relay's secrets, never in client configuration.
+
+Client and bundled-server builds embed the public values, so set them before building.
+EAS preview and production environments need the publishable key, JWT template name, and relay URL.
+Bundled servers also accept runtime overrides for operator-managed deployments.
+
+Copy `infra/relay/.env.example` to `infra/relay/.env` for relay deployment settings.
+Deploy `prod` before personal stages because it owns the retained database that their branches
+depend on. The deploy wrapper writes the resulting relay URL back to the root `.env`.
+
+## CLI OAuth application
+
+In Clerk's OAuth applications settings:
+
+1. Create a public OAuth application for the T3 CLI, using authorization-code exchange with PKCE.
+2. Allow both redirect URIs: `http://127.0.0.1:34338/callback` and
+   `https://app.t3.codes/connect/callback`. A custom `T3CODE_HOSTED_APP_URL` needs its own
+   `/connect/callback` URL. Headless and SSH authorization depend on the hosted redirect.
+3. Enable the `openid`, `profile`, and `email` scopes.
+4. Set `T3CODE_CLERK_CLI_OAUTH_CLIENT_ID` to the generated public client ID in local and release
+   build environments.
+
+## JWT template
+
+Create a Clerk JWT template named `t3-relay` with claims:
+
+```json
+{ "aud": "t3-code-relay" }
+```
+
+Set `T3CODE_CLERK_JWT_TEMPLATE=t3-relay` for clients and
+`CLERK_JWT_AUDIENCE=t3-code-relay` for the relay. The production relay deployment environment
+also defines `CLERK_JWT_TEMPLATE`. The audience stays the same across relay stages; the relay
+URL selects the deployment.
+
+## Desktop OAuth redirects
+
+Enable Clerk's Native API and add the desktop redirects to its SSO redirect allowlist:
+
+```text
+t3code-dev://app/
+t3code://app/
+```
+
+Add the corresponding origin to the Clerk instance's Backend API `allowed_origins` array.
+Development uses `t3code-dev://app`; production uses `t3code://app`. Update the array with
+`PATCH https://api.clerk.com/v1/instance` using the Clerk secret key, preserving existing entries.
+The Clerk Electron integration handles token
+persistence and system-browser callback delivery.
+
+## Desktop passkeys
+
+For a production macOS app with bundle ID `com.t3tools.t3code`:
+
+1. Create an explicit macOS App ID in the Apple Developer portal with **Associated Domains**.
+2. Create a provisioning profile for that App ID and the distribution signing certificate.
+3. In Clerk's Native API settings, add an iOS app with the same Apple Team ID and bundle ID.
+   This setting also configures Electron/macOS passkeys.
+4. Check `https://<frontend-api>/.well-known/apple-app-site-association`. Its
+   `webcredentials.apps` must include `<TEAM_ID>.com.t3tools.t3code`.
+5. Configure signing as described in the [release runbook](./release.md#2-apple-signing--notarization-setup-macos).
+
+Local signed builds additionally use:
+
+```dotenv
+T3CODE_APPLE_TEAM_ID=ABC1234567
+T3CODE_MACOS_PROVISIONING_PROFILE=/absolute/path/to/t3code.provisionprofile
+# Override only when the RP domain differs from the Clerk Frontend API hostname.
+T3CODE_CLERK_PASSKEY_RP_DOMAINS=example.clerk.accounts.dev,clerk.example.com
+```
+
+Without the override, the build derives the RP domain from the Clerk publishable key.
+After changing Associated Domains, bump the build version before rebuilding. macOS can otherwise
+reuse stale Shared Web Credentials metadata for the same app/version pair.
+
+The ordinary `dev:desktop` launcher is unsigned and cannot exercise macOS passkeys. For renderer
+HMR, install a signed build, start `vp run dev:web`, and launch the installed executable with the
+actual web and server ports. For example, with the default ports:
+
+```sh
+VITE_DEV_SERVER_URL=http://127.0.0.1:5733 \
+T3CODE_PORT=13773 \
+  "/Applications/T3 Code (Alpha).app/Contents/MacOS/T3 Code (Alpha)"
+```
+
+Rebuild the signed app after native dependency, main-process, preload, entitlement, provisioning,
+or signing changes. Renderer edits can reuse it. Verify the installed bundle before testing:
+
+```sh
+codesign --verify --deep --strict "/Applications/T3 Code (Alpha).app"
+codesign -d --entitlements :- "/Applications/T3 Code (Alpha).app"
+```
+
+## Restricting sign-ups
+
+Use Clerk's allowlist for permitted email addresses or domains, or Restricted mode for invitation-only
+sign-up. An enabled empty allowlist blocks all new sign-ups.
+
+Sign-up restrictions do not revoke an existing account's access. Ban the account in Clerk when
+its active sessions and future sign-ins must be disabled.
diff --git a/docs/operations/development.md b/docs/operations/development.md
new file mode 100644
index 000000000000..39686807d6dd
--- /dev/null
+++ b/docs/operations/development.md
@@ -0,0 +1,152 @@
+# Development
+
+## First checkout
+
+Install `vp` using the [root README](../../README.md#install-vp). The checkout requires Node 24;
+Bun is optional. From the repository root:
+
+```sh
+vp i
+vp run dev
+```
+
+Open the one-time pairing URL printed by the dev runner. The bare origin does not authenticate
+a new browser.
+
+## Choosing a dev process
+
+Use `vp run dev` for server and web, or `vp run dev:desktop` for the Electron client.
+`dev:server` and `dev:web` start those processes separately.
+See the [mobile README](../../apps/mobile/README.md) for native builds and Metro.
+
+Flags go directly after the task name, for example `vp run dev --home-dir /tmp/t3code-dev`.
+Add `--browser` to open a browser automatically.
+
+### State and ports
+
+Linked worktrees default to their own `.t3/userdata`, even when `T3CODE_HOME` is set.
+The main checkout defaults to `~/.t3/dev/userdata`. An explicit `--home-dir` wins in both cases.
+Never run a development server against the live `~/.t3/userdata`.
+See [test data](../../AGENTS.md#test-data) for copying a consistent database snapshot.
+
+Read ports from the `[dev-runner]` output. Worktrees derive stable preferences from their paths,
+but occupied ports can shift them. `T3CODE_PORT_OFFSET` or `T3CODE_DEV_INSTANCE` can select a
+different preference when needed.
+
+### Sharing and remote debugging
+
+`vp run dev --share` publishes the web port over the machine's tailnet and prints a pairing URL
+for that origin. Give the tester the complete URL, including its token. The dev runner removes
+its mapping on exit.
+
+Leave `VITE_HTTP_URL` and `VITE_WS_URL` unset. Vite proxies the backend through the browser's
+origin so the same build works over localhost and remote connections.
+
+Shared runs enable bundled dev to avoid a network round trip for each import level.
+`T3CODE_BUNDLED_DEV=0` opts out when debugging bundler differences. Two reload traps matter
+when changing this setup:
+
+- The web entry must dynamically import the app so React refresh initializes before application
+  chunks. Static imports can work on first load and fail after a route split.
+- Bundled dev rebuilds Tailwind through watched files. Its ordinary Vite hot-update hook expects
+  a server/module graph that Rolldown does not provide.
+
+The workarounds live in the [web entry](../../apps/web/src/bootstrap.ts) and
+[Tailwind plugin](../../apps/web/vite/tailwind.ts).
+
+## Checks
+
+Run checks for the files and packages you changed:
+
+```sh
+vp test run <files>
+vp lint <files>
+vp run --filter <package> typecheck
+```
+
+Use `vp run lint:mobile` for native mobile changes. CI owns the full suite; see
+[ci.yml](../../.github/workflows/ci.yml) for its current jobs.
+The [manual Windows lane](../../.github/workflows/windows-tests.yml) is available for focused
+Windows investigation while that suite is not a required gate.
+
+### Unused code
+
+`vp run knip:check` checks unused files and dependencies across the repo, then
+unused exports and types in `packages/tailscale` and `packages/effect-codex-app-server`.
+CI enforces both checks.
+Use `vp run knip --workspace apps/web` to audit one workspace, including exports,
+or `vp run knip:production --workspace apps/web` to find code kept alive only by tests.
+The full export audit still has findings and is not a repo-wide CI gate. Extend the
+export check's workspace selectors as more workspaces become clean. Review callers before
+deleting code; production mode can also report development scripts and test fixtures.
+Runtime-discovered entrypoints and dependency exceptions belong in [knip.jsonc](../../knip.jsonc).
+
+## Desktop artifacts
+
+Local artifact builds are unsigned by default and write to `release/`:
+
+```sh
+vp run dist:desktop:dmg
+vp run dist:desktop:linux
+vp run dist:desktop:win
+```
+
+DMGs default to the host architecture. Use `--arch` to choose another target and `--keep-stage`
+to retain packaging files for inspection. Run `vp run dist:desktop:artifact --help` for other
+options.
+
+### Linux AppImage prerequisites
+
+Build on Linux because the browser-secret helper links against the host's libsecret. Install
+Rust, C/C++ build tools, libsecret development headers, pkg-config, and ImageMagick.
+
+Ubuntu and Debian:
+
+```sh
+sudo apt-get update
+sudo apt-get install cargo rustc build-essential libsecret-1-dev pkg-config imagemagick
+```
+
+Fedora:
+
+```sh
+sudo dnf install rust cargo gcc gcc-c++ make libsecret-devel pkgconf-pkg-config ImageMagick
+```
+
+Arch Linux:
+
+```sh
+sudo pacman -S rust base-devel libsecret pkgconf imagemagick
+```
+
+The C toolchain, pkg-config, and libsecret headers are also needed for Linux desktop development.
+
+### macOS DMG prerequisites
+
+Install the Xcode Command Line Tools with `xcode-select --install` and install Rust.
+For a cross-architecture or universal build, add the requested Rust targets:
+
+```sh
+rustup target add aarch64-apple-darwin x86_64-apple-darwin
+```
+
+### Windows installer prerequisites
+
+Install Rust, Python 3, and Visual Studio Build Tools with **Desktop development with C++**.
+Include the Windows SDK and the MSVC build tools and Spectre-mitigated libraries for the target
+architecture. Add its Rust target:
+
+```powershell
+rustup target add x86_64-pc-windows-msvc
+# For an ARM64 installer:
+rustup target add aarch64-pc-windows-msvc
+```
+
+NSIS is downloaded by electron-builder. WSL support additionally needs a Linux node-pty prebuild;
+see the [release runbook](./release.md#windows-payload-topology-and-update-validation).
+
+### Signing and passkeys
+
+Add `--signed` after configuring the platform credentials in the
+[release runbook](./release.md). macOS passkeys need a signed, provisioned app; follow the
+[Connect setup](./connect-setup.md#desktop-passkeys) for local signing and renderer HMR.
diff --git a/docs/operations/release.md b/docs/operations/release.md
index e5a4d3544c35..02f453ab36a5 100644
--- a/docs/operations/release.md
+++ b/docs/operations/release.md
@@ -329,7 +329,7 @@ Checklist:
    - `APPLE_API_KEY`: contents of the downloaded `.p8`
    - `APPLE_API_KEY_ID`: Key ID
    - `APPLE_API_ISSUER`: Issuer ID
-10. Complete the Clerk Native API and AASA setup in [T3 Connect Clerk Setup](../internals/t3-connect.md#desktop-passkeys).
+10. Complete the Clerk Native API and AASA setup in [T3 Connect setup](./connect-setup.md#desktop-passkeys).
 11. Re-run a tag release and confirm macOS artifacts are signed/notarized and contain the expected
     `com.apple.developer.associated-domains` entitlement.
 
diff --git a/docs/user/appearance.md b/docs/user/appearance.md
new file mode 100644
index 000000000000..0300b8fd9946
--- /dev/null
+++ b/docs/user/appearance.md
@@ -0,0 +1,73 @@
+# Appearance and themes
+
+Open **Settings → Appearance** to choose a theme and follow the system appearance or stay in light
+or dark mode. To use different themes for light and dark mode, select the corresponding preview
+within each theme. Appearance preferences are saved separately on each device or browser.
+
+Mobile has its own themes and text, code, and terminal preferences. It does not follow environment
+themes or defaults.
+
+## Motion
+
+The main sidebar, right panel, and terminal drawer open and close immediately by default. Move the
+**Panel animations** slider above 0 ms to add motion, up to 400 ms, unless reduced motion is enabled
+in your operating system. Moving between threads always snaps to the selected thread's panel state
+without replaying its transitions.
+
+## Custom themes
+
+On web and desktop, choose **Create theme** to adjust a palette, or import a T3 Code or VS Code
+theme. The theme editor's color picker lets you select an area of the app to find the color to
+change. Export your theme as JSON to share it.
+
+## Environment themes
+
+Environment themes and defaults come from the server serving your web app or the desktop app's
+main local environment. app.t3.codes and additional connections do not use them.
+
+Select a published theme in **Settings → Appearance** to follow its palette as the server updates
+it. **Duplicate** makes an independent copy you can edit. A saved custom theme with the same ID
+takes precedence. If the server stops publishing the selected theme, T3 Code falls back to its
+standard theme.
+
+Run this on the server to set a default and switch connected clients to it:
+
+```bash
+t3 theme set nightfall
+```
+
+Clients that are offline apply it when they reconnect. Each client applies the setting once;
+choosing another theme afterward sticks until the next `t3 theme set`. Run the command again to
+reapply it, even if the name is unchanged.
+
+`t3 theme clear` removes the default without changing anyone's current theme. `t3 theme show` lists
+the default and published themes.
+
+### Publish a theme
+
+Save a theme exported from T3 Code into `~/.t3/userdata/themes/` on the server, or the `themes`
+directory under your custom state directory. The filename supplies the theme ID: `nightfall.json`
+can be selected with `t3 theme set nightfall`. Keep the filename stable when updating its colors.
+Do not use `system`, `light`, `dark`, or a built-in theme's ID.
+
+For an integration that generates a palette, this shorter format also works:
+
+```json
+{
+  "name": "Nightfall",
+  "appearance": "dark",
+  "canvas": "#1a1b26",
+  "accent": "#7aa2f7",
+  "colors": {
+    "terminalSelection": "#292e42",
+    "error": "#f7768e"
+  }
+}
+```
+
+Set `appearance` to `light` or `dark` and supply hex colors for `canvas` and `accent`. T3 Code
+generates the rest. The optional `colors` overrides use the names in the theme editor's advanced
+view.
+
+Write updates to a temporary file and rename it into place so clients never read a partial theme.
+Invalid files are not published.
diff --git a/docs/user/background-service.md b/docs/user/background-service.md
index a89fc2f7842d..eecd6fa77b3a 100644
--- a/docs/user/background-service.md
+++ b/docs/user/background-service.md
@@ -1,123 +1,81 @@
-# Running T3 Code in the Background
+# Running T3 Code in the background
 
-On Linux and macOS, T3 Code can run as a background service for your user, so it is ready without
-keeping a terminal open.
+On Linux and macOS, T3 Code can run as a service for your user so you do not need
+to keep a terminal open.
 
-## Manage the Service
+## Manage the service
 
-Install it with the latest T3 Code release:
+Run these commands on the machine that will host T3 Code:
 
-```sh
-npx t3@latest service install
-```
-
-Check whether it is installed. On Linux this also checks whether the service is running, enabled
-at startup, and allowed to keep running after logout:
-
-```sh
-npx t3@latest service status
-```
-
-Update or repair it:
-
-```sh
-npx t3@latest service update
-```
-
-The service uses the same T3 Code version as the CLI you run. To install a nightly or an exact
-version, use that version of the CLI:
-
-```sh
-npx t3@nightly service update
-npx t3@1.2.3 service update
-```
-
-The install and update commands refuse to replace a newer service with an older version. Setup
-through T3 Connect leaves a newer service unchanged. To downgrade, select the exact older version
-and pass `--allow-downgrade`:
+| Task                            | Command                           |
+| ------------------------------- | --------------------------------- |
+| Install and start               | `npx t3@latest service install`   |
+| Inspect status and log location | `npx t3@latest service status`    |
+| Update or repair                | `npx t3@latest service update`    |
+| Stop and remove from startup    | `npx t3@latest service uninstall` |
 
-```sh
-npx t3@1.2.3 service update --allow-downgrade
-```
-
-Stop it and remove it from startup:
-
-```sh
-npx t3@latest service uninstall
-```
-
-Updating restarts T3 Code briefly. Let active agent work and terminal commands finish first.
-If a remote update is already in progress, wait for it to finish before retrying a local update.
-
-The service runs a small stable launcher. Exact T3 Code versions are installed separately, so a
-failed remote candidate can return to the previous version without rewriting the service
-definition. The launcher snapshots the database before a remote candidate starts, so database
-updates roll back with the server version. An older launcher may require one local
-`service update` before this is available.
+Uninstalling the service leaves your projects, threads, and settings intact.
 
-## Platform Support
+Install and update use the version of the CLI you invoke. For nightly, use
+`npx t3@nightly service update`; replace `nightly` with an exact version to pin
+one. An older CLI refuses to replace a newer service unless you explicitly add
+`--allow-downgrade`.
 
-**Linux** uses a systemd user unit at `~/.config/systemd/user/t3code.service`. The service starts
-when the machine boots and keeps running after you log out (lingering is enabled during install).
-Setup checks the systemd user manager and enables lingering before installing a runtime or stopping
-an existing service. If that requires administrator permission, setup stops with a recovery command.
+Updating restarts the server. Finish active work first, and wait for any remote
+update already in progress. To match a remote client's version, follow
+[Updating T3 Code](./updating.md).
 
-**macOS** uses a launch agent at `~/Library/LaunchAgents/com.t3tools.t3code.service.plist`. It
-starts when you log in, not when the Mac boots, and it stops when you log out; macOS has no
-equivalent of Linux lingering for user agents. For a Mac that should stay reachable unattended,
-turn on automatic login (System Settings → Users & Groups; unavailable while FileVault is on) and
-keep the Mac from sleeping.
+## Platform support
 
-A few more macOS notes:
+Linux needs systemd user services. Setup enables lingering so T3 Code starts at
+boot and keeps running after logout. If this needs administrator permission,
+setup prints a recovery command before changing the service.
 
-- Installing over SSH needs someone logged in at the Mac's screen to start the agent right away.
-  Without that, the install command reports an error at the final start step, but the agent is
-  fully installed and starts at the next login.
-- macOS may show privacy prompts for protected folders such as Desktop, Documents, or Downloads,
-  attributed to a bare `node` process, or deny access without a prompt. If agent work fails to
-  read those folders, grant Full Disk Access to the node binary listed in the launch agent's
-  `ProgramArguments`.
-- The agent appears under System Settings → General → Login Items. If it was switched off there,
-  or disabled with `launchctl disable`, macOS will not start it at login until you switch it back
-  on.
+macOS starts the service when you log in and stops it when you log out. Keep the
+Mac logged in and awake for unattended remote access. Installing over SSH while
+nobody is logged in at the Mac's screen can fail at the final start step; the
+service is still installed and will start at the next login.
 
-**Windows** is not supported yet.
+Windows background services are not supported.
 
-## Using It with T3 Connect
-
-T3 Connect may offer to install the service during setup so the host stays reachable in the
-background. This is only an onboarding shortcut: the service and T3 Connect are managed separately.
-
-Signing out of T3 Connect does not remove the service. Use `t3 service uninstall` when you no longer
-want T3 Code to start in the background.
+T3 Connect can offer service installation during setup, but the two are managed
+separately. Signing out of T3 Connect does not stop or uninstall the service.
 
 ## Troubleshooting
 
-Run `t3 service status` on the server machine. An installed version alone does not mean the service
-is running or will survive logout. Linux status reports these problems:
+Start with `t3 service status` on the host. It prints the log path and, on Linux,
+checks whether the installed service is running, enabled, and allowed to survive
+logout.
 
-| Code                       | What it means                                                                    | Recovery                                                                                                                                   |
-| -------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `linger-disabled`          | The service stops after your last login session ends and does not start at boot. | Run `sudo loginctl enable-linger "$(id -un)"`, then retry setup as your normal user.                                                       |
-| `linger-unavailable`       | T3 Code could not verify the logout setting.                                     | Run `loginctl show-user "$(id -un)" --property=Linger` and check that systemd-logind is available.                                         |
-| `user-manager-unavailable` | T3 Code cannot reach your systemd user manager.                                  | Run `systemctl --user status` in a login session for the service user. Install your distribution's systemd user-session support if needed. |
-| `service-disabled`         | The service is not enabled to start automatically.                               | Run the repair command shown by `t3 service status`.                                                                                       |
-| `service-stopped`          | The service is installed but is not running.                                     | Read the service log and `systemctl --user status t3code.service`, then run the displayed repair command.                                  |
-
-For an SSH host, run the administrator command in an interactive terminal so sudo can prompt for
-your password:
+If it stops when your SSH session closes, check for `linger-disabled`. An
+administrator can enable lingering with:
 
 ```sh
-ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'
+sudo loginctl enable-linger "$(id -un)"
 ```
 
-Run only the `loginctl` command with sudo. Running `t3` with sudo creates a separate installation and
-Connect identity for root. If an administrator is unavailable, run `t3 serve` in a terminal and
-keep that session open.
+Over SSH, allow sudo to prompt:
 
-The repair command shown by status uses the CLI version, or the installed service version if that
-is newer. An older stable CLI therefore does not recommend downgrading a nightly installation.
-Setup leaves an existing service running if the user-manager or lingering check fails.
+```sh
+ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'
+```
 
-`t3 service status` prints the log path. The adjacent `server.trace.ndjson` file contains detailed
-server traces. For failures after authorization, see [T3 Connect troubleshooting](./remote-access.md#t3-connect-troubleshooting).
+Then retry service setup as your normal user. Run only the `loginctl` command
+with sudo; running T3 Code as root creates a separate installation and Connect
+identity. Without administrator access, run `t3 serve` in a terminal and keep
+that session open.
+
+| Status problem                          | Next step                                                                                                                      |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `linger-unavailable`                    | Run `loginctl show-user "$(id -un)" --property=Linger` and check that systemd-logind is available.                             |
+| `user-manager-unavailable`              | Run `systemctl --user status` in a login session for the service user; check your distribution's systemd user-session support. |
+| `service-disabled` or `service-stopped` | Read the log and `systemctl --user status t3code.service`, then use the repair command printed by T3 Code.                     |
+
+On macOS, check **System Settings → General → Login Items** if the service no
+longer starts at login. If agent work cannot access Desktop, Documents, or
+Downloads, it may need Full Disk Access for the Node executable listed in
+`ProgramArguments` in
+`~/Library/LaunchAgents/com.t3tools.t3code.service.plist`.
+
+For failures after signing in to T3 Connect, see
+[connection troubleshooting](./remote-access.md#t3-connect-troubleshooting).
diff --git a/docs/user/browser-import.md b/docs/user/browser-import.md
index 4c911f6262a3..93f2fad73741 100644
--- a/docs/user/browser-import.md
+++ b/docs/user/browser-import.md
@@ -1,17 +1,21 @@
-# Import browser logins
+# Import browser sessions
 
-In the desktop app, open **Settings → Integrations → Browser profiles → Add profile**
-and choose a browser under **Import from**. The import copies cookies into a T3 Code browser
-profile so you can use existing logins in the preview browser. Changes made afterward stay
-separate from the source browser.
+The desktop app can import cookies from another browser so you can reuse its signed-in sessions
+in the preview browser.
 
-Linux discovery includes Helium and both native and Snap installations of Firefox. Windows
-discovery includes Firefox and Helium builds that still use Windows' standard profile
-encryption. Other Chromium-based browsers on Windows use app-bound cookie encryption and cannot
-be imported. A browser appears once it has a profile with a cookie database. Close the source
-browser before importing; the import wizard will prompt you if it is still running.
+Open **Settings → Integrations → Browser profiles → Add profile**, then choose a browser under
+**Import from**. Close the source browser before importing, and allow an operating-system keyring
+unlock prompt if one appears.
 
-On Linux, Chromium-based browsers use your desktop keyring to protect their cookies. T3 Code
-includes the keyring reader; no separate command-line tool is needed. Allow the desktop unlock
-prompt if one appears. If the keyring cannot be accessed, T3 Code reports that failure when no
-cookies can be imported. Partitioned cookies are skipped.
+This is a one-time copy. Later login changes stay separate between the two browsers, and some
+sites may still require you to sign in again.
+
+On macOS, Safari is also available. Safari protects its cookies with Full Disk Access rather than
+a keychain, so the import wizard asks you to grant it: **Open System Settings** takes you to the
+right pane, and macOS may ask you to quit and reopen T3 Code before the grant applies. You can
+revoke Full Disk Access after the import is done. Only Safari's primary profile is imported; cookies
+kept by additional Safari profiles are not.
+
+On Windows, import supports Firefox and Helium profiles that use standard profile encryption.
+Other Chromium-based browsers use app-bound encryption and cannot be imported. Partitioned cookies
+are skipped on all platforms.
diff --git a/docs/user/composer.md b/docs/user/composer.md
index fce133cd27d8..4a8df5333664 100644
--- a/docs/user/composer.md
+++ b/docs/user/composer.md
@@ -1,236 +1,138 @@
-# Message composer
-
-Messages can contain up to 120,000 characters. If a draft is longer, T3 Code keeps it in the
-composer and shows how many characters need to be removed. Shorten the draft or split it into
-multiple messages, then send again in the same thread.
-
-On mobile, an empty composer shows an interrupt button while the agent is working. Adding text
-or an attachment replaces it with the send button. This applies to both compact and expanded
-composers.
-
-You can attach images up to 10 MB. On servers that support file uploads, you can also
-attach videos, text files, PDFs, ZIP archives, and other files. Each file can be up to the limit advertised
-by the server, capped at 50 MB. Each message can contain up to eight attachments in total. Files
-upload directly to the environment, where your agent can read, copy, or edit them by their file path.
-
-Attachments upload as soon as you add them while connected to a server that supports uploads.
-The send button becomes available after every upload finishes. Failed uploads can be retried or
-removed. On mobile, tap **+** to open
-the photo library from either the compact or expanded composer. When the connected server supports
-file uploads, **+** opens a menu beside the button with **Photo Library** and **Choose Files**.
-Videos use the server's file upload limit. You can also share photos, videos, and files into
-T3 Code from other apps through the system share sheet. Mobile keeps a local copy of each draft
-attachment, so you can still preview it and queue messages while offline. Uploads resume when
-you reconnect. Drafts and queued messages survive app restarts; signing out of T3 Connect keeps
-them on your device until you sign back into the same account. Select a received file on mobile
-to preview it or open the system share options.
-
-Tap an image or PDF before or after sending to open it. On iOS, images zoom from their thumbnail
-into the native viewer. Pinch or double-tap to zoom, and swipe down or tap Close to return.
-Use Share to save a copy or send it to another app. PDFs support page navigation and search.
-PDF links in assistant responses open the same preview. On Android, images open in the image
-viewer and PDFs open the system chooser.
-
-On web and desktop, select a sent PDF or HTML attachment to open it in the file viewer, or use the
-download button beside it to save a copy. Other attached files download when selected.
-
-Select a video attachment before or after sending to play it. Web and desktop use the browser's
-built-in controls. On mobile, videos open in a full-screen player with native playback controls.
-Supported videos show a thumbnail in the conversation and composer.
-Received videos stream from their environment as they play on every platform. Supported formats and
-codecs depend on the browser or device; you can save an unsupported video to open it in another app.
-
-On iOS, the system player zooms from the attachment. Swipe down or tap Close to return to the
-conversation or draft. Touch and hold a video thumbnail, then choose **Save or share** to open
-the system share options. On Android, the same menu is also available inside the preview.
-
-On web and desktop, if you reload before a file finishes uploading, the draft keeps the file's name
-and shows **Attach again** next to it. Attach the file again or remove it, then send.
-
-On web and desktop, HEIC and HEIF photos are automatically converted to JPEG when you drag them into
-the composer or paste them into a message. On iOS, selecting them from **Photo Library** also
-converts them to JPEG. The 10 MB image limit applies to the converted photo.
-
-On web and desktop, an existing thread settles its composer into a single-line resting state when
-the composer loses focus. At wider sizes, scrolling the conversation also rests a focused composer,
-except when scrolling toward the end while already there. When the thread-context strip has room,
-the model and mode controls stay available beside the thread context; otherwise they return when the
-composer is focused. Focus the composer or start typing to expand it again. The conversation keeps
-the expanded composer's space clear above its last message while the composer rests, so expanding it
-again never covers what you scrolled to. New-thread layouts keep the full composer. **Settings → General → Collapse composer** chooses which triggers rest it:
-**On unfocus**, **On scroll**, both, or neither. With neither selected the composer stays expanded.
-
-At phone-sized web or desktop window widths, existing threads animate between their compact and
-expanded layouts. Up to three image attachments remain visible in either resting layout, followed
-by a count when more are attached. At wider sizes, videos, files, and other draft context remain
-visible at their natural height; the phone-sized compact row reveals those details when expanded.
-
-On mobile, the model picker shows each OpenCode model's upstream provider, such as Anthropic,
-GitHub Copilot, or OpenCode Zen, beneath its name. Search by that provider name to narrow the list
-when starting a thread or changing an existing thread's model.
+# Messages and context
 
-## Model defaults
+Give the agent a task in the composer. Add files, quote a previous response, or
+include a skill when the task needs more context.
 
-T3 Code remembers the last provider, model, and model options you selected and reuses that
-selection for new threads. A model configured in a project's settings overrides the remembered
-selection for that project; resetting the project setting returns it to the remembered selection.
+Messages can contain up to 120,000 characters. Longer drafts stay in the composer
+so you can shorten them or split them into several messages.
 
-Model options shown as provider defaults remain display values until you choose them in T3 Code.
-T3 Code only sends options you selected explicitly, so an unset reasoning level or service tier can
-still come from the provider's own configuration.
+## Attach files
 
-## Quote an assistant response
+Attach up to eight files per message. Images can be up to 10 MB; other files can
+be up to 50 MB, subject to the environment's upload support and limit. The agent
+receives them on the environment's machine.
 
-On web and desktop, select text in an assistant response, then choose **Cite in composer** from the
-menu that appears when you release the selection. This inserts an inline quote chip at your cursor
-and opens an optional comment bubble beside the selected text; press `Enter` or choose **Save** to
-attach the comment, or leave it blank to keep just the quote. You can type before and after the
-chip, such as a quote followed by "what do you mean?". A selection must stay within one response
-and fit in 8,000 characters.
+Uploads begin when you add an attachment. All uploads must finish before the
+message can send. Retry or remove a failed upload. On web and desktop, reloading
+before an upload finishes requires you to attach that file again.
 
-The chip shows your comment when it has one, or a short quote preview otherwise. Use the pencil
-button to add or change the comment, and the remove button to delete the quote and its comment from
-the draft. Copying, reloading, and restoring a [stashed prompt](#prompt-stash) keep each comment
-with its quote, and sending tells the agent which words were quoted and which comment you wrote.
-The quoted text and comment count toward the message limit.
+You can drag or paste images into the web or desktop composer. HEIC and HEIF
+photos are converted to JPEG there and when selected from the iOS photo library;
+the image limit applies after conversion. On mobile, you can also send files to
+T3 Code through another app's system share sheet.
 
-Select a chip in the composer or a sent message to open the source thread, scroll to the response,
-and highlight the quoted passage — including in older history. The
-highlight pulses, holds for a moment, then fades on its own; press `Escape` to stop the navigation
-or clear it early. If the source is unavailable or its text has changed, the saved quote stays
-readable and T3 Code shows a warning.
+See [images and videos](#images-and-videos-in-messages) for previewing and saving media.
 
-Mobile shows the full saved quote and its comment in sent messages. It does not offer
-**Cite in composer** or navigation to a quote's source.
+## Queue messages offline on mobile
 
-## Images and videos in messages
+Mobile keeps local copies of draft attachments, so you can preview them and queue
+messages while disconnected. Uploads resume when you reconnect. Drafts and queued
+messages survive app restarts. Signing out of T3 Connect keeps that work on your
+device until you sign back into the same account.
 
-On web, desktop, and mobile, select a link to an image or video to open it inside T3 Code.
-Workspace image and video links open the file viewer. Links to media outside the workspace
-open a media preview.
-Videos opened from the file explorer or a file-viewer tab also play inside T3 Code. They
-stream from the environment as needed, rather than downloading the entire video before playback.
-Paths in inline code, such as `/tmp/recording.mp4`, work the same way. Image embeds stay inline;
-video embeds show a player with the browser's controls, full screen included. Visible video previews load
-an initial frame when supported, but stay paused until you press Play. Video file references use
-a filmstrip icon.
-
-On web and desktop, hover over a preview to see its full file path or original URL. Right-click
-to copy that reference, save the image or video, or copy an image to the clipboard. The video
-player's built-in controls can download a video too. If the player cannot decode a video, its error message
-offers a link to open the source in the browser. Workspace media also offers **Copy relative
-path** and **Open in file viewer**. These actions are available in expanded previews too.
-
-On mobile, touch and hold an inline image or a video thumbnail to see its source,
-copy the path or URL, or choose **Save or share**. Workspace files can open in the file viewer
-from the same menu. Saving downloads a copy only when you request it; it does not change how
-the video buffers during playback. On iOS, touch and hold a file reference in a message to
-copy its full or relative path or open it in the file viewer.
-
-Use Markdown image syntax to embed either kind of media:
-
-```markdown
-![Screenshot](/tmp/screenshot.png)
-![Recording](/tmp/recording.mp4)
-[Open recording](/tmp/recording.mp4)
-```
-
-Relative paths resolve from the thread's workspace. Absolute paths and `file://` links refer to
-the environment's machine, even when you connect remotely or use your phone. Supported media
-can live outside the workspace, including in Downloads or `/tmp`.
-
-T3 Code serves the original file without adding it to attachment storage. If that file is moved
-or deleted, its preview can no longer load from the environment. A browser or device may still
-have a cached copy. Supported video formats and codecs depend on the browser or device.
-
-Bare paths in ordinary prose and paths inside code blocks stay text. Raw HTML `<video>` tags
-are not supported; use the Markdown embed syntax above.
+## Custom models
 
-## Files outside the workspace
+On web and desktop, use Settings → Providers → **Models** to add an unlisted model with a custom
+name and options. Only options supported by the provider integration affect turns. Antigravity
+uses its account catalog and does not support custom models.
 
-When an agent links to a file it wrote outside the workspace, such as a Markdown report in
-`/tmp`, select the link to open it in the file viewer. The viewer shows the file read-only, with
-rendered Markdown available as usual; it cannot edit files outside the workspace. The workspace
-file tree stays hidden because it does not describe the open file. HTML and PDF files outside the
-workspace open the same way as ones inside it. Because such a file is served on its own, an HTML
-page outside the workspace cannot load scripts, styles, or images from files beside it.
+## Model defaults
 
-## HTML and PDF files in the file viewer
+T3 Code remembers your provider, model, and model options for new threads. A
+project's configured model takes precedence; resetting that project setting
+returns to the remembered selection.
 
-On web and desktop, the file viewer shows HTML and PDF files as a rendered page. Use the
-source toggle in the viewer's header to switch an HTML file between the page and its markup; the
-choice persists like the rendered-Markdown toggle. A link to a line always opens the source. HTML
-runs in an isolated frame with no access to your T3 Code session. On desktop, the integrated
-browser remains available from the same header for a full browser view.
+Leaving reasoning level or service tier unset uses the provider's own configuration.
 
-## Changing projects
+## Quote an assistant response
+
+On web and desktop, select text within one assistant response and choose
+**Cite in composer**. You can add a comment about the quote and write instructions
+around it.
+
+Select the quote in a draft or sent message to return to its source. If the source
+is unavailable or has changed, the saved quote remains readable.
 
-On web and desktop, changing the project from a new thread keeps the current environment when that
-project exists there. If it does not, T3 Code selects another environment that has the project.
+Mobile displays saved quotes and comments, but does not create citations or
+navigate to their sources.
 
-## Notices above the composer
+## Recall a sent prompt
 
-On web and desktop, loading and syncing statuses fill the available banner width beside the
-stash tab. Task progress appears above the composer, while the timeline's working timer shows
-only elapsed time.
+Press `ArrowUp` in an empty composer to bring back the last prompt you sent in this thread. Press
+`ArrowUp` again to go further back, and `ArrowDown` to come forward. Moving forward past the newest
+prompt clears the composer. Recall walks the prompts loaded in the thread. Attachments, terminal
+context, and other extras from the original message are not restored, only the text you typed. A
+composer that holds an attachment or a picked element does not count as empty.
 
-On web and desktop, additional notices peek out above the attached banner. Hover over the peek
-to reveal them, or focus **Show other notices** with `Tab` and press `Enter` or `Space`. Press
-`Escape` to close the stack and return focus to that control. On a touchscreen, tap the peek to
-open the stack. Interacting with the attached banner or composer does not open the stack.
+When the composer has text, the arrow keys move the caret as usual. Recall takes over only while
+the text is an unedited recalled prompt, with the caret on the first visual line for `ArrowUp` or
+the last visual line for `ArrowDown`, counting wrapped lines. Editing a recalled prompt turns it
+into a normal draft.
 
 ## Prompt stash
 
-Use the default shortcut, `Cmd+S` on macOS or `Ctrl+S` on Windows and Linux, to stash the current
-prompt and its attachments after all file uploads finish. Restore the entry later from the stash
-menu. Stashes that contain files must be restored in the environment where those files were
-uploaded. Stashed files stay uploaded on the server for 24 hours. If you restore an entry after
-that, the file comes back with **Attach again** next to it. Attach the file again or remove it, then
-send.
+On web and desktop, press `Cmd+S` on macOS or `Ctrl+S` on Windows and Linux to save
+the current prompt and its attachments for later. Wait for uploads to finish first.
+With an empty composer, the same shortcut restores a single stash or opens the
+stash menu when there are several.
+
+Stashes containing uploaded files must be restored in their original environment.
+Those files are retained for 24 hours. After an upload expires, restore the prompt
+and use **Attach again** or remove the missing file before sending.
 
 ## Voice input on iPhone
 
-On supported iPhones with iOS 26 or later, tap the microphone in the composer to record a message.
-An expanded composer keeps your draft visible and flips its bottom toolbar into recording controls
-with waves that respond to your voice. A collapsed composer flips into a compact recording strip
-without changing height. Tap the checkmark to finish and transcribe on your device. The waves fade
-into a transcription status, then the usual
-controls return with the text inserted at the selection where recording started. If the keyboard
-is open when you start, it stays open during voice input. You can review and edit the text before
-you send it.
-
-The first use can download Apple's speech model and needs a network connection. Later transcription
-works offline for that language. A recording can be up to five minutes long. Canceling voice input,
-leaving the screen, or an audio interruption discards the new recording and keeps the existing draft
-and attachments. T3 Code deletes the local audio file after transcription or cancellation. It sends
-only the normal message text when you submit the draft.
+On supported iPhones with iOS 26 or later, use the composer's microphone to record,
+then confirm to transcribe. Text is inserted where your selection was when
+recording started, ready for you to review and edit before sending.
+
+The first use may download Apple's speech model and needs a network connection.
+Later transcription works offline for that language. Recordings can be up to five
+minutes long. Canceling, leaving the screen, or an audio interruption discards the
+recording and preserves your existing draft.
+
+Transcription runs on your device. T3 Code deletes the temporary audio after
+transcription or cancellation; only the message text is sent when you submit.
 
 ## Commands and skills
 
-Type `/` to open the command menu. Type `$` to find and add a skill. Skill rows show their source,
-such as System, Personal, Project, or App.
+Type `/` for commands or `$` to add a skill from the selected environment and
+provider. On mobile, both are also available before starting a thread on
+**New task**.
+
+The slash menu also includes skills unless you turn off **Settings → General →
+Show skills in slash menu**. Only skills enabled for the provider are listed.
+
+Provider commands must start the message to run. T3 Code commands such as
+`/model` and `/plan`, and skill mentions, work on any line.
+
+Send `/compact` in an existing conversation to reduce context usage when the
+provider supports it. Web and desktop also offer compaction from the context meter.
+
+## Images and videos in messages
+
+Select an image or video attachment or link to preview it. Playback support depends
+on your browser or device; save an unsupported video to open it in another app.
 
-On mobile, these menus are available on the **New task** screen before you start a thread. They
-use the skills and commands from the selected environment and provider.
+On web and desktop, right-click media to save it or copy its path or URL. On mobile,
+touch and hold an image or video thumbnail and choose **Save or share**. On iOS,
+return to the thumbnail to open this menu after watching a full-screen video.
 
-In a thread with prior conversation context, send `/compact` to reduce context usage. Web and desktop also offer this action from the context meter, and the work log records token counts when the provider reports them.
+File links refer to the environment's machine, including when you connect remotely.
+Previews use the original file, even outside the workspace. Moving or deleting it
+can break the preview, so save a copy if you need to keep it.
 
-By default, the `/` menu includes skills. To keep this menu command-only, turn off **Show skills in
-slash menu** in **Settings → General**. Skill results use the `/skill:Skill Name` label and add the
-same `$name` skill token to your message. The original skill name remains searchable. If the provider
-also reports that skill as a native slash command, T3 Code hides the duplicate native entry and keeps
-the `/skill:Skill Name` label.
+## Files outside the workspace
 
-A skill token runs the skill wherever it sits in your message. T3 Code sends it to each provider in
-the form that provider runs, so the text before and after the token is kept. Skills that only you may
-start, and never the agent on its own, work the same way. A skill you switched off in the provider's
-settings does not appear in either menu.
+Follow an agent's file link to read a report or other file outside the workspace.
+These files open read-only. An HTML file outside the workspace cannot load scripts,
+styles, or images from neighboring files.
+
+## HTML and PDF files in the file viewer
 
-Provider commands such as `/compact` only run when they open the message, so the `/` menu offers
-them only there. T3 Code's own commands, such as `/model` and `/plan`, and skills stay available on
-any line.
+On web and desktop, HTML and PDF files open as rendered pages. Switch an HTML
+file to source view to read its markup; a link to a specific line opens source
+automatically. HTML previews cannot access your T3 Code session.
 
-On desktop, press `Cmd+Enter` on macOS or `Ctrl+Enter` on Windows and Linux from a new thread to
-start it in the background. T3 Code opens another new thread and shows an **Open** action for the
-thread that started. The new thread keeps the selected workspace mode and base branch. If **New
-worktree** is selected, each background thread creates its own worktree.
+On mobile, select a PDF attachment or link to open it. iOS uses the native viewer;
+Android opens the system chooser.
diff --git a/docs/user/environment-theme.md b/docs/user/environment-theme.md
deleted file mode 100644
index 9988b8377fdc..000000000000
--- a/docs/user/environment-theme.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Environment theme
-
-Some desktops publish the palette they are currently wearing so that apps can match it. When the
-machine running your T3 Code server does that, its themes appear in the theme library alongside
-your own, and T3 Code follows them: change the desktop theme and T3 Code retints with it, without
-a restart.
-
-To use one:
-
-1. Open **Settings**.
-2. Select **Appearance**.
-3. Choose the theme published by your environment.
-
-Like every theme, this is a per-client choice: picking it on your desktop does not change what your
-phone or another browser shows.
-
-The machine can also set the environment's theme:
-
-```bash
-t3 theme set nightfall
-```
-
-Web and desktop clients switch to it — immediately when connected, on their next connect
-otherwise — and a fresh client opens with it. Each client applies a set once, so picking a
-different theme in Settings afterwards sticks until the next `t3 theme set`, and running the same
-set again is how you bring clients back. `t3 theme clear` removes the setting without changing
-what anyone currently has, and `t3 theme show` prints the current theme and everything the
-machine publishes. Only the environment you are anchored to publishes themes, so a remote client
-follows the machine it is connected to, not the device it runs on. T3 Code Mobile keeps its own
-appearance settings and does not follow environment themes.
-
-Select **Duplicate** on a published theme's card to keep a copy you can edit. The published theme
-itself cannot be edited or removed, because the environment rewrites it whenever its own theme
-changes. If the machine stops publishing it, the card disappears and clients using it fall back to
-the standard T3 Code look. A theme you saved always wins over a published one with the same id.
-
-When the theme editor is open, its draft stays visible while published themes change.
-Close the editor to show the latest selected theme.
-
-## Publishing themes
-
-A machine publishes themes by writing files into the `themes` directory of the T3 Code state
-directory (`~/.t3/userdata/themes/` by default). The filename is the theme id — `nightfall.json`
-appears as `nightfall` — and stays stable while the machine rewrites the colors underneath, so
-selections and defaults keep pointing at it.
-
-The filename may not be an appearance keyword (`system`, `light`, `dark`) or a built-in theme's
-id — those names already mean something on every client. Two formats are accepted. A theme
-exported from T3 Code (the **Download** button's output) works as-is, so any theme someone shared
-can be dropped in unchanged. Or, for a desktop that only knows
-its own palette, a short seeded form:
-
-```json
-{
-  "name": "Nightfall",
-  "appearance": "dark",
-  "canvas": "#1a1b26",
-  "accent": "#7aa2f7"
-}
-```
-
-`appearance` is `light` or `dark`, and `canvas` and `accent` are hex colors. T3 Code generates the
-rest of the palette from those two, the same way the guided theme editor does, so the result reads
-as a T3 Code theme wearing your desktop's colors rather than a transplant of another app's.
-
-A machine that knows a role better than a derivation can guess — its terminal palette, its
-semantic colors — can publish that role directly under `colors`, layered over the generated
-palette:
-
-```json
-{
-  "name": "Nightfall",
-  "appearance": "dark",
-  "canvas": "#1a1b26",
-  "accent": "#7aa2f7",
-  "colors": {
-    "terminalSelection": "#292e42",
-    "error": "#f7768e"
-  }
-}
-```
-
-Any of the roles shown in the theme editor's advanced view can be published this way; roles left
-out keep their generated value. A role this version of T3 Code does not know is ignored rather
-than rejected, so publishing a role added by a newer release is safe. An `id` inside the file is
-ignored — the filename decides.
-
-A theme with no usable colors is not listed on that client.
-
-Write each file atomically — write a temporary file beside it and rename — so T3 Code never reads
-a half-written theme. An unreadable or invalid file is simply not published; the machine's other
-themes are unaffected.
diff --git a/docs/user/install.md b/docs/user/install.md
index 7534759fd10c..17e9291bf1a0 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -1,142 +1,106 @@
 # Install T3 Code
 
-T3 Code is a web and desktop GUI for running coding agents on your machine.
+T3 Code runs coding agents on your computer and lets you control them from its
+desktop, web, or mobile app. Set up the machine where the agents will work first.
 
 ## Requirements
 
-Node.js `^22.16 || ^23.11 || >=24.10` on the machine that runs the T3 Code server.
+Command-line use, SSH hosts, and WSL backends need Node.js 22.16+ (22.x), 23.11+
+(23.x), or 24.10 and later. The native desktop app includes its server runtime.
 
-At least one provider runtime, installed and authenticated. You can install Antigravity from
-T3 Code settings. See [Providers](#providers) below.
+You need an installed, authenticated provider before starting a thread. You can
+launch T3 Code and configure providers afterwards.
 
-## Run Without Installing
+## Run without installing
 
 ```bash
 npx t3@latest
 ```
 
-This starts the T3 Code server on your machine and opens the local web app. Use
-`npx t3@latest --help` for the full CLI reference.
+This starts the server and opens the local web app. Run
+`npx t3@latest --help` for command-line options.
 
-If the web or desktop app shows "T3 Code could not load", check your connection and select
-**Reload** to try again.
+## Desktop app
 
-## Open a project in the desktop app
+Download a release from [GitHub Releases](https://github.com/pingdotgg/t3code/releases),
+or use a package manager:
 
-When the T3 Code desktop app is running on the same machine, open the current directory with:
+| Platform           | Install                         |
+| ------------------ | ------------------------------- |
+| Windows            | `winget install T3Tools.T3Code` |
+| macOS              | `brew install --cask t3-code`   |
+| Arch Linux         | `yay -S t3code-bin`             |
+| Arch Linux nightly | `yay -S t3code-nightly-bin`     |
 
-```bash
-npx t3 app
-```
-
-Pass a path to open another directory:
-
-```bash
-npx t3 app ../my-project
-```
-
-The command adds the directory as a project when needed, focuses the desktop app, and opens a new
-thread. It does not launch the desktop app, open a browser, or start a T3 Code server. A background
-server does not count as the desktop app. The command also rejects SSH sessions because a remote
-shell cannot focus a local desktop window. The CLI package and the running desktop app must both
-include `t3 app` support.
-
-## Desktop App
-
-Download the latest release from
-[GitHub Releases](https://github.com/pingdotgg/t3code/releases), or install from a package
-registry.
+### Windows Subsystem for Linux
 
-Windows:
+Choose a WSL distro in **Settings → Connections** to run agents and projects
+there. Install Node.js and provider CLIs inside that distro. T3 Code installs its
+matching server runtime there automatically; the first launch after an app
+update can take longer.
 
-```bash
-winget install T3Tools.T3Code
-```
+### Open a project from a terminal
 
-macOS:
+With the desktop app already running on the same machine:
 
 ```bash
-brew install --cask t3-code
+npx t3 app
 ```
 
-Arch Linux:
+This opens a new thread for the current directory, adding the project if needed.
+Pass a path, such as `npx t3 app ../my-project`, to open another directory. It requires
+the desktop app, so a standalone server or an SSH session is not enough. If the
+command cannot reach the app, start or update the desktop app and try again.
 
-Stable:
+## Mobile app
 
-```bash
-yay -S t3code-bin
-```
-
-Nightly:
-
-```bash
-yay -S t3code-nightly-bin
-```
-
-### Windows Subsystem for Linux
-
-When the desktop app runs a WSL backend, it installs the matching server runtime into
-`~/.t3/wsl-runtime` inside the selected distro. The first launch after installing or updating T3
-Code may take a little longer while that release's runtime is extracted. Later launches reuse the
-Linux-local copy so startup does not depend on reading application files through `/mnt/c`. After a
-successful launch, T3 Code keeps the current runtime and one previous runtime for rollback and
-removes older caches automatically. If a cached runtime stops working, T3 Code launches from the
-application files under `/mnt/c` instead and reinstalls the runtime on the next launch.
+Install T3 Code from the
+[App Store](https://apps.apple.com/us/app/t3-code-remote-claude-more/id6787819824) or
+[Google Play](https://play.google.com/store/apps/details?id=com.t3tools.t3code).
+The phone connects to a server on another machine. Follow
+[remote access](./remote-access.md) to link it through T3 Connect or a pairing URL.
 
 ## Providers
 
-T3 Code uses provider runtimes but does not bundle them. Install and authenticate each
-provider's CLI, or use T3 Code's managed setup for Antigravity.
-
-| Provider    | CLI                                                                                                        | Default binary     | Log in with                        |
-| ----------- | ---------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------- |
-| Codex       | [Codex CLI](https://developers.openai.com/codex/cli)                                                       | `codex`            | `codex login`                      |
-| Claude      | [Claude Code](https://claude.com/product/claude-code)                                                      | `claude`           | `claude auth login`                |
-| Cursor      | [Cursor CLI](https://cursor.com/cli)                                                                       | `cursor-agent`     | `agent login`                      |
-| Grok Build  | [Grok Build CLI](https://x.ai/cli)                                                                         | `grok`             | `grok login`                       |
-| OpenCode    | [OpenCode](https://opencode.ai)                                                                            | `opencode`         | `opencode auth login`              |
-| Antigravity | [Official ACP agent](https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json) | Managed by T3 Code | **Sign in with Google** in T3 Code |
-
-Codex and Claude are on by default. Cursor, Grok Build, OpenCode, and Antigravity are off by
-default. Turn them on in **Settings** > **Providers** when you want to use them.
-
-For Antigravity, select the environment in provider settings, then install and sign in there.
-The runtime and credentials stay on that environment, even when you use a phone or remote
-browser. See [Antigravity setup](./providers-antigravity.md) for Google sign-in, remote callback
-steps, and supported hosts.
-
-Cursor is the one to watch: install Cursor CLI, which provides the `cursor-agent` binary that
-T3 Code looks for, but authenticate with `agent login`, not `cursor-agent login`.
-
-Grok models that support adjustable reasoning show a **Reasoning** control beside the model picker.
-The available levels and default come from the installed Grok Build CLI, so they can vary by model
-and CLI version.
-
-Run CLI login commands on the machine running the T3 Code server, not on the device you browse
-from. Antigravity uses its sign-in controls in T3 Code instead of a CLI login command.
-
-### Binary Discovery
-
-Each provider CLI must be on the server's `PATH`, or have an explicit binary path set in
-**Settings** → the provider instance → **Binary path**. Use the explicit path when a version
-manager or a non-standard install location keeps the CLI off the `PATH` of the shell that
-started T3 Code.
-
-Antigravity can use its managed runtime without a `PATH` entry. Its optional **Binary path**
-overrides the managed runtime and must point to the official ACP executable.
-
-### When Auth Is Needed
-
-Provider auth is required before you start a session with that provider, not before you start
-T3 Code. You can install T3 Code, open it, and add providers afterwards. A provider that is not
-authenticated shows its status and setup instructions in **Settings**.
-
-For multi-account setups, see [Codex](./providers-codex.md), [Claude](./providers-claude.md), and
-[Antigravity](./providers-antigravity.md#accounts-and-removal).
-
-## Next Steps
-
-- [Permission modes](./permission-modes.md): how much T3 Code asks before acting
-- [Remote access](./remote-access.md): connect from a phone, tablet, or another desktop
-- [Keeping T3 Code in sync](./updating.md): client and server version skew
-- [Running in the background](./background-service.md): Linux background service
+Open **Settings → Providers** in the web or desktop app, select the environment,
+and enable the provider you want. Installation, login, and configuration belong
+to that environment's machine, even when you connect from a phone or another
+computer.
+
+| Provider    | Install and authenticate                                                                     |
+| ----------- | -------------------------------------------------------------------------------------------- |
+| Codex       | Install [Codex CLI](https://developers.openai.com/codex/cli), then run `codex login`.        |
+| Claude      | Install [Claude Code](https://claude.com/product/claude-code), then run `claude auth login`. |
+| Cursor      | Install [Cursor CLI](https://cursor.com/cli), then run `agent login`.                        |
+| Grok Build  | Install [Grok Build CLI](https://x.ai/cli), then run `grok login`.                           |
+| OpenCode    | Install [OpenCode](https://opencode.ai), then run `opencode auth login`.                     |
+| Antigravity | Install and sign in with Google from T3 Code's provider settings.                            |
+
+Provider CLIs must be on the server's `PATH`. If T3 Code cannot find one, set its
+**Binary path** in provider settings, especially when using a version manager.
+Cursor's executable is `cursor-agent`, although its login command is
+`agent login`. Antigravity can use its managed runtime without a `PATH` entry.
+
+When a provider CLI is behind its latest release, its provider card shows the
+available version. **Update now** appears only when T3 Code can tell which
+installer owns the CLI (its own update command, Homebrew, or a global npm, pnpm,
+bun, or Vite+ install) and runs that installer. Otherwise update the CLI the same
+way you installed it. Homebrew installs compare against the version Homebrew
+offers, which can trail the npm release by a few hours.
+
+Add another provider instance for a separate account or configuration. Each
+instance can have its own environment variables, such as API keys or a custom
+base URL. Mark secret values as sensitive; after saving, T3 Code does not display
+their original values.
+
+For provider-specific setup and accounts, see [Codex](./providers-codex.md),
+[Claude](./providers-claude.md), [OpenCode](./providers-opencode.md), and
+[Antigravity](./providers-antigravity.md).
+
+## Next steps
+
+- [Working with threads](./thread-sidebar.md): start tasks and organize parallel work.
+- [Permission modes](./permission-modes.md): choose when agents ask before acting.
+- [Remote access](./remote-access.md): connect from another device.
+- [Running in the background](./background-service.md): keep a Linux or macOS host available.
+- [Updating T3 Code](./updating.md): update the app and connected servers.
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index fe97eedadbca..1c90b5351d30 100644
--- a/docs/user/keybindings.md
+++ b/docs/user/keybindings.md
@@ -1,14 +1,13 @@
 # Keybindings
 
-Edit keybindings from **Settings** → **Keybindings**. That page lists every command, its current
-shortcut, whether it is a default or your own, and warns about conflicts.
+Customize shortcuts in **Settings → Keybindings** on web and desktop. That page
+also lists the command IDs and defaults available in your version.
 
-The same configuration lives in `~/.t3/userdata/keybindings.json` on the machine running the
-server, if you prefer editing it directly. T3 Code writes the built-in defaults into that file on
-first run, and adds any new defaults on later startups unless a rule of yours already claims the
-command or the shortcut.
+## Edit the configuration file
 
-The file is a JSON array of rules.
+Keybindings live on the environment's machine, in
+`~/.t3/userdata/keybindings.json` by default. You can edit this file directly.
+It is a JSON array of rules:
 
 ```json
 [
@@ -17,96 +16,63 @@ The file is a JSON array of rules.
 ]
 ```
 
-Invalid rules are ignored. An invalid file is ignored entirely, and the server logs a warning.
+T3 Code creates the file with its defaults and adds new defaults on later startups.
+New defaults do not replace commands you customized. If a new default overlaps one
+of your shortcuts, [rule order](#precedence) decides which runs.
+Invalid rules are ignored; if the file cannot be parsed, T3 Code uses defaults.
 
-## Rule Shape
+## Rule shape
 
-- `key` (required): shortcut string, like `mod+j`, `ctrl+k`, `cmd+shift+d`
-- `command` (required): the command ID to run
-- `when` (optional): boolean expression controlling when the shortcut is active
+Each rule requires a `key` shortcut and a `command` ID. An optional `when`
+expression restricts when it runs.
 
-## Key Syntax
+Project scripts use `script.{id}.run`, such as `script.test.run`.
 
-Modifiers: `mod` (`cmd` on macOS, `ctrl` elsewhere), `cmd` / `meta`, `ctrl` / `control`, `shift`,
-`alt` / `option`.
+## Key syntax
 
-Examples: `mod+j`, `mod+shift+d`, `ctrl+l`, `cmd+k`.
+Join modifiers and a key with `+`, such as `mod+shift+d` or `ctrl+l`.
+`mod` means Command on macOS and Control elsewhere. Other modifiers are
+`cmd` / `meta`, `ctrl` / `control`, `alt` / `option`, and `shift`.
 
-## Commands
+## When conditions
 
-Commands are IDs like `terminal.toggle`, `commandPalette.toggle`, `preview.refresh`, and
-`chat.new`. Project scripts are addressable as `script.{id}.run`, for example `script.test.run`.
+Available context keys are `terminalFocus`, `terminalOpen`, `previewFocus`,
+`previewOpen`, and `modelPickerOpen`. Unknown keys evaluate to `false`.
 
-`filePicker.toggle` opens file search for the active project and defaults to `mod+p`.
-`projectSearch.toggle` searches inside the active project's files and defaults to `mod+shift+f`.
-Repeating either shortcut closes that search, and switching shortcuts replaces the open search.
-`themeEditor.toggle` opens or closes the floating theme editor and defaults to
-`mod+alt+shift+t`. Select a color label to spotlight the elements that use it; select the label
-again to clear the spotlight. The swatch and hex field keep that color selected while you edit it.
-Advanced mode groups related app tokens into a smaller set of color families. Changing a family
-updates its paired text and interaction states while leaving every unrelated imported color intact.
-Use **Inspect** to pick an element in the app and reveal its color token. Inspect disarms after one
-successful pick; its hover glow and badge preview the element and color family that click will select.
-**Cancel** or `Escape` exits Inspect and clears its selection and spotlight.
+Combine keys with `!` for not, `&&` for and, `||` for or, and parentheses:
 
-`rightPanel.toggleMaximized` maximizes or restores the open right panel. It has no default shortcut,
-so add one in **Settings** → **Keybindings** if you want to use it.
-
-`rightPanel.close` closes the active right panel tab and defaults to `mod+w`. Press it again to close
-the next tab. With the terminal focused, `mod+w` closes the terminal instead, and with nothing left
-to close it closes the desktop window as before. Browsers reserve `mod+w` for closing their own tab
-and never pass it to the page, so in a browser rebind this command (and `terminal.close`) to a
-shortcut the browser leaves alone, such as `alt+w`.
-
-`thread.copyReference` copies the active thread's pull request link, or its thread ID when no pull
-request is available. Its default shortcut is `mod+shift+c`, and it does not replace terminal copy
-while the terminal has focus.
-
-`thread.settle` settles the active thread or restores it when it is already settled. Its default
-shortcut is `mod+shift+s`, and it does not run while the terminal has focus.
-
-`thread.pin` pins the active thread to the pinned section of the sidebar, or unpins it when it is
-already pinned. Its default shortcut is `mod+shift+p`, and it does not run while the terminal has
-focus. See [Organizing threads](./thread-sidebar.md) for how pinned threads are ordered.
-
-The command palette searches settings, active thread titles, projects, branches, user messages, and
-final agent responses across connected environments. A setting result opens its exact control or
-section. Message matches show one labeled excerpt while keeping the thread's project, branch, and
-machine context visible. Message search begins after two characters and uses SQLite's ASCII
-case-insensitive matching.
+```json
+{ "key": "mod+j", "command": "terminal.toggle", "when": "terminalOpen && !terminalFocus" }
+```
 
-The full command list and the current defaults are shown in **Settings** → **Keybindings**, which
-always matches the build you are running. Use that rather than a copied list.
+## Precedence
 
-Note that `chat.new` and `chat.newLocal` both create a thread through the same path. A new thread
-inherits the project you were in, along with model and mode selections. Branch, worktree, and
-environment mode always come from your configured defaults, not from the thread you were looking
-at. To keep a worktree, use the explicit "new thread in this worktree" action in the branch
-toolbar. The only difference between the two commands: with the current sidebar and more than one
-project, `chat.new` opens a project chooser first.
+The last rule whose key and condition both match wins, even if it belongs to a
+different command. Put a more specific rule after a general one when they share
+a shortcut.
 
-Background submission from a new thread is the exception. `mod+enter` starts that thread and opens
-another new thread with the same workspace mode and base branch. **New worktree** remains selected,
-but the new thread does not reuse the worktree created for the thread that just started.
+## Commands with special behavior
 
-## `when` Conditions
+`chat.new` may ask you to choose a project when there is more than one.
+`chat.newLocal` skips that chooser. Both use your
+[new-thread defaults](./thread-sidebar.md#start-a-thread).
 
-A `when` expression is evaluated against context keys describing the current UI state. The keys
-the app supplies today are `terminalFocus`, `terminalOpen`, `previewFocus`, `previewOpen`, and
-`modelPickerOpen`. The set is open and grows over time, so treat that as the current list rather
-than a fixed one. Any key the running app does not supply evaluates to `false`.
+## Reserved shortcuts
 
-Operators: `!` (not), `&&` (and), `||` (or), and parentheses.
+In the desktop app, `mod+w` closes the focused terminal or the active right-panel
+tab. When nothing remains to close, it closes the window. In a browser, `mod+w`
+closes the browser tab; rebind `rightPanel.close` and `terminal.close` to an available
+shortcut such as `alt+w`.
 
-Examples:
+Many defaults include `!terminalFocus` so they do not intercept terminal input.
+Keep that condition when remapping them if you want the same behavior.
 
-- `"when": "terminalFocus"`
-- `"when": "terminalOpen && !terminalFocus"`
-- `"when": "!terminalFocus"`
+## Desktop quit shortcut
 
-## Precedence
+Use `Cmd+Q` on macOS or `Ctrl+Q` on Windows and Linux. In the default **Hold** mode,
+hold for 1.2 seconds or press twice within 500 milliseconds. Holding requires
+keyboard repeat; if repeat is disabled, use two presses or the application menu.
 
-- Rules are evaluated in array order.
-- For a key event, the last rule where both `key` matches and `when` evaluates to `true` wins.
-- Precedence is across commands, not only within the same command. A later rule for a different
-  command can take a key away from an earlier one.
+Change **Settings → General → Confirmations → Quit shortcut** to **Direct** for a
+single press or **Double press** for two presses only. Choosing **Quit** from the
+application menu always quits immediately.
diff --git a/docs/user/keyboard-focus.md b/docs/user/keyboard-focus.md
new file mode 100644
index 000000000000..50b9c87c24f3
--- /dev/null
+++ b/docs/user/keyboard-focus.md
@@ -0,0 +1,9 @@
+# Keyboard focus
+
+The command palette keeps focus while open. Closing it returns focus to the composer.
+While the palette or model picker is open, number shortcuts select its entries instead of
+switching threads. Model shortcuts work in Settings as well as the composer.
+See [Keybindings](./keybindings.md) to customize these shortcuts.
+
+If you return to typing while a terminal is starting, the composer keeps focus when the terminal
+becomes ready. Opening or switching to a terminal explicitly still focuses it.
diff --git a/docs/user/mobile-appearance.md b/docs/user/mobile-appearance.md
deleted file mode 100644
index b7e4d57a6ade..000000000000
--- a/docs/user/mobile-appearance.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Mobile appearance
-
-T3 Code Mobile includes the T3 Code, T3 Chat, Grove, Ocean, Ember, and Iris themes. Each theme has
-light and dark colors that apply throughout the app, including code reviews, file previews, the
-terminal, native headers, and sheets.
-
-On supported iOS versions, the new-task and thread composers, working timer, and scroll-to-end
-button use the system glass material. Other platforms use a themed background.
-
-To change themes:
-
-1. Open **Settings**.
-2. Select **Appearance**.
-3. Choose a theme.
-4. Select **System**, **Light**, or **Dark**.
-
-Tap a theme card to use it for both light and dark appearance. To mix themes, tap the light or dark
-preview circle inside a card to change only that appearance.
-
-**System** follows the device appearance automatically. Theme, text, code, and terminal appearance
-preferences are stored on the device.
diff --git a/docs/user/permission-modes.md b/docs/user/permission-modes.md
index f7da2fc32164..3d37850c5e20 100644
--- a/docs/user/permission-modes.md
+++ b/docs/user/permission-modes.md
@@ -1,60 +1,31 @@
-# Permission Modes
+# Permission modes
 
-A permission mode controls how much the agent does on its own and when it stops to ask you.
+Permission modes control when an agent needs your approval to act. Choose a mode in the message
+composer; it applies to that thread.
 
-The mode is set per thread, from the mode control in the message composer. Changing it in one
-thread does not change any other thread. A thread created from inside another thread keeps that
-thread's mode; otherwise new threads start in **Full access** unless you pick something else
-before sending.
+New threads start in **Full access** unless you choose another mode before sending. A thread
+created from another thread inherits its mode.
 
-## The Modes
+| Mode                  | Behavior                                                                              |
+| --------------------- | ------------------------------------------------------------------------------------- |
+| **Supervised**        | Requests approval for commands and file changes.                                      |
+| **Auto-accept edits** | Approves file edits automatically; other actions can still require approval.          |
+| **Auto**              | Uses the provider's automatic review to approve routine actions and ask about others. |
+| **Full access**       | Allows commands and edits without approval prompts.                                   |
 
-**Supervised**: ask before commands and file changes. The agent pauses and shows you what it
-wants to run or edit, and waits for approval. Work outside the workspace is restricted.
+Approve or reject requests in the conversation to let the agent continue. Permission modes do
+not prevent the agent from asking questions about the task.
 
-**Auto-accept edits**: auto-approve edits, ask before other actions. File changes go through
-without prompting; commands and anything else still stop for approval.
+## Provider differences
 
-**Auto**: routine actions proceed without you; risky ones still ask. How this is enforced depends
-on the provider: Codex delegates routine approvals to an AI reviewer, Claude uses its own auto
-permission mode, Cursor uses Smart Auto review, and providers without an equivalent (such as
-OpenCode and Antigravity) fall back to asking, like Supervised.
-
-**Full access**: allow commands and edits without prompts. The default. The agent runs
-unattended until it finishes or asks a question of its own.
-
-Approvals appear inline in the conversation. Approve or reject one and the agent continues from
-there.
+Providers enforce permissions differently. Some read-only actions can proceed in **Supervised**.
+**Auto** uses automatic review on Codex, Claude, and Cursor; providers without an equivalent,
+including OpenCode and Antigravity, fall back to asking.
 
 For Grok, **Always allow this session** remembers the matching command or tool input. Other
-actions still ask for approval. It does not change the thread to **Full access**.
-
-Antigravity uses its own permission policy for each mode. T3 Code still shows any approval or
-question the official agent sends in **Full access**. A remembered approval is available only
-when the agent offers it for that action. Fixed-choice questions require one of the offered
-answers and do not accept custom text.
-
-## Choosing a Mode
-
-Use **Full access** for work in a worktree or a sandbox you can throw away.
-
-Use **Supervised** on a repository where an unwanted command is expensive, or the first time you
-run an unfamiliar task.
-
-**Auto-accept edits** suits refactors where the edits are the point and you only care about the
-shell commands.
-
-## Provider Behavior
-
-Each provider maps these modes onto its own approval and sandbox settings. Codex, for example,
-translates the mode into its approval policy and sandbox level, so **Supervised** runs the CLI
-with prompting enabled and a restricted workspace while **Full access** disables both. Grok
-threads do the same: **Supervised** starts Grok in ask mode even if your Grok CLI config is
-set to always-approve, and **Full access** starts Grok with always-approve. The labels above
-describe what you get; the exact per-provider translation is internal and may change.
+actions still require approval.
 
-Mobile offers the same four modes with the same labels and descriptions.
+Antigravity can still send native approval requests in **Full access**. It only offers remembered
+approvals for actions that support them.
 
-Antigravity's native `/plan` command requests a plan. It does not change the permission mode.
-T3 Code's separate Plan mode control is not available for Antigravity. See
-[Antigravity](./providers-antigravity.md) for setup and thread limits.
+See the [provider guides](./install.md#providers) for setup and provider-specific limits.
diff --git a/docs/user/project-settings.md b/docs/user/project-settings.md
index 604de45258b0..747bc52c07ec 100644
--- a/docs/user/project-settings.md
+++ b/docs/user/project-settings.md
@@ -1,32 +1,18 @@
-# Customize a project icon
+# Project settings
 
-T3 Code selects a project icon automatically. It checks `t3.json`, common favicon and app icon
-paths, and icon links in project HTML files. If it does not find an image, it chooses a built-in
-icon from the saved project name. In web and desktop, this icon stays the same when the sidebar
-shows a repository label such as `owner/repo`.
+Open **Settings → Projects** and select a project to change its preferences.
 
-To choose a different icon or emoji:
+## Project icons
 
-1. Open **Settings** and select **Projects**.
-2. Select the project.
-3. Next to **Project icon**, select **Choose icon**.
-4. Search the full Lucide icon set and choose a color, or switch to **Emoji** and choose or paste
-   an emoji.
-
-To use an image from the project instead, select **Choose file**, search for an image, and select
-it.
-
-T3 Code supports SVG, PNG, ICO, JPEG, GIF, AVIF, and WebP files. The selected path applies to
-each checkout in the project group and appears on your connected clients.
-
-To use automatic detection again, select **Automatic**.
+Choose an icon, emoji, or image from the project to make it easier to recognize. The choice applies
+to every checkout in the project group and appears on connected clients. Choose **Automatic** to
+let T3 Code detect an icon again.
 
 ## Keep the default branch current
 
-Turn on **Automatically pull** in a project's settings to keep its default-branch checkout current.
-T3 Code checks in the background and when the server starts. It uses the branch's configured
-upstream and only performs a fast-forward pull when the checkout has no working-tree changes,
-untracked files, or local commits.
+Enable **Automatically pull** to keep the default-branch checkout up to date with its configured
+upstream.
 
-The pull is skipped if the checkout is on another branch, has no upstream, or contains local work.
-Pull failures do not prevent the server from starting.
+T3 Code only pulls when it can fast-forward and the checkout has no changed files, untracked files,
+or local commits. It skips checkouts on another branch or without an upstream. If a checkout has
+local work, resolve it yourself before automatic pulls can resume.
diff --git a/docs/user/providers-antigravity.md b/docs/user/providers-antigravity.md
index bd84ced3a395..7466cba309ac 100644
--- a/docs/user/providers-antigravity.md
+++ b/docs/user/providers-antigravity.md
@@ -1,196 +1,135 @@
 # Antigravity
 
-T3 Code runs Google's official Antigravity ACP agent. By default it signs in with your personal
-Google account and uses that account's Antigravity access, including access provided by a
-Google AI subscription. It never falls back to a different sign-in method than the one you
-select.
-
-The agent, files, conversation state, and Google credentials stay on the selected environment.
-Your browser or phone controls that environment. Signing in to the Antigravity IDE or CLI does
-not sign in this T3 Code provider.
+T3 Code runs Google's official Antigravity ACP agent on your selected environment.
+It has its own sign-in, separate from the Antigravity IDE or CLI. Google controls
+which models and account access are available through this agent.
 
 ## Set up Antigravity
 
-On web or desktop, open **Settings** > **Providers**, select the device that runs your project,
-then select **Antigravity**. On mobile, open **Settings** > **Environments**, expand the
-environment, then choose **Set up Antigravity**. An existing setup shows **Manage Antigravity**.
-The model picker can open setup for the selected environment too.
-
-1. Choose **Enable Antigravity**. Antigravity is off by default.
-2. Choose **Install Antigravity**. T3 Code downloads the official runtime from Google to that
-   environment. Installation continues if you leave the page or reconnect.
-3. Choose **Sign in with Google**.
-4. Choose **Open sign-in page** on web or desktop, or **Open Google sign-in** on mobile. You can
-   use **Copy sign-in link** to open it in another browser.
-5. Complete Google sign-in. Use the account you use for Antigravity.
-6. Wait for T3 Code to confirm sign-in and load the model choices. Select an Antigravity model
-   in the thread's model picker.
+On web or desktop, open **Settings > Providers**, choose the environment that runs
+your project, and enable Antigravity. Install its runtime there, then choose
+**Sign in with Google** and complete the browser sign-in. Wait for T3 Code to confirm
+account access and load models before starting a thread. Provider setup is not
+available in the mobile app.
 
-Setup requires a connection with permission to operate the environment. If setup is unavailable
-on an older server, update that environment first.
+Installation continues if you leave settings or reconnect. Setup requires
+permission to operate the environment; update an older server if it does not offer
+Antigravity setup.
 
 ### Sign in from a remote device
 
-Google returns to a `127.0.0.1` address on the device running your browser. If that is the same
-machine as the T3 Code environment, sign-in can finish directly.
+Google returns to a `127.0.0.1` address. It can finish directly when your browser is
+on the environment's machine. From another device, the final page will usually
+fail to load because the sign-in listener is on the environment.
 
-On a phone or another computer, the final page will usually fail to load. This is expected.
-Copy the full address from the browser, including everything after `?`, and paste it into the
-return URL field in T3 Code. Choose **Continue** on web or desktop, or **Complete sign-in** on
-mobile. Do not change the address to your server's hostname.
+Copy the full return address, including everything after `?`, into the return URL
+field in the web or desktop client where you started setup, then choose
+**Continue**. Keep the original address; do not replace it with the server's
+hostname. Only that T3 Code sign-in session can finish the attempt. If it expires,
+retry sign-in and use the new link.
 
-Return to the same T3 Code client and environment where you started sign-in. Another client
-can see that sign-in is in progress, but cannot complete that attempt. The setup screen shows
-the expiry time. If it expires, choose **Retry Google sign-in** and use the new link.
-
-The return URL contains a temporary sign-in code. Paste it only into the setup field, not into
-a thread or bug report. T3 Code waits for Google's agent to confirm sign-in. A successful
-callback page alone does not prove account access.
+The return URL contains a temporary sign-in code. Paste it only into the setup
+field. A successful callback page alone does not confirm account access; wait for
+T3 Code's confirmation.
 
 ### Other sign-in methods
 
-**Sign-in method** in the Antigravity provider settings on web or desktop selects how the
-agent authenticates. Mobile shows the selected method and its connect controls.
-
-| Method                     | What you enter                           | How it signs in                 |
-| -------------------------- | ---------------------------------------- | ------------------------------- |
-| Google account             | Nothing                                  | Google sign-in page             |
-| Gemini Enterprise          | GCP project and GCP location             | Google sign-in page             |
-| Gemini API key             | API key                                  | Choose **Connect**. No browser. |
-| Agent Platform (Vertex AI) | API key, or GCP project and GCP location | Choose **Connect**. No browser. |
+Choose **Sign-in method** in the Antigravity provider settings:
 
-Gemini Enterprise resolves your license for the project and location you enter. Agent Platform
-with a project and location uses Application Default Credentials on the environment. API keys
-are stored in plain text in T3 Code settings on that environment and are passed only to the
-Antigravity agent process. Ambient `GEMINI_API_KEY` or `GOOGLE_*` variables on the environment
-are ignored.
+| Method                     | Credentials                                                                                  |
+| -------------------------- | -------------------------------------------------------------------------------------------- |
+| Google account             | Personal Google sign-in in the browser                                                       |
+| Gemini Enterprise          | Browser sign-in, GCP project, and GCP location                                               |
+| Gemini API key             | API key; choose Connect without a browser                                                    |
+| Agent Platform / Vertex AI | API key, or GCP project and location with Application Default Credentials on the environment |
 
-Changing the method stops the instance's sessions. Sign out or disconnect before you switch
-accounts.
+The Antigravity API key field is stored in plain text in settings on the
+environment. The agent uses the method and credentials selected for this instance;
+ambient `GEMINI_API_KEY` and Google credential variables do not override them.
+Changing the method stops the instance's sessions. Sign out before replacing an
+account.
 
 ## Runtime installation
 
-Managed downloads are available for these environment hosts:
-
-| Host    | Architecture  |
-| ------- | ------------- |
-| macOS   | Apple Silicon |
-| Linux   | x64 or ARM64  |
-| Windows | x64 or ARM64  |
-
-Google does not publish a local Intel Mac runtime. Use an Intel Mac as a client connected to
-a supported remote environment.
-
-The current Linux x64 runtime downloads about 682 MB and uses about 2.01 GB after extraction.
-Allow at least 3 GB free for installation. An update keeps the previous runtime too.
-T3 Code does not download it until you choose to install it.
-
-On web or desktop, **Update Antigravity** appears when T3 Code has a newer managed release.
-Running sessions keep their current runtime. New sessions use the installed update.
+Managed installation supports Apple Silicon macOS, Linux x64 or ARM64, and Windows
+x64 or ARM64. Intel Macs can connect to a supported remote environment. Allow
+several GB of free disk space, especially on Linux.
 
 ### Use a manual installation
 
-Download the correct archive from the [official ACP Registry][registry] and extract both the
-ACP executable and its `localharness_external` helper into the same directory. Keep both files
-at the same version and make them executable on macOS or Linux. Windows uses `.exe` files.
+Download the archive for your environment from the [official ACP Registry][registry].
+Extract the ACP executable and its `localharness_external` helper into the same
+directory, at the same version. Make both executable on macOS or Linux; Windows
+uses `.exe` files.
 
-On web or desktop, set **Binary path** in the Antigravity provider settings to the ACP
-executable on the selected environment. Do not point it at the helper or the Antigravity IDE.
-
-A nonempty **Binary path** takes priority. With the field empty, T3 Code uses its managed
-runtime, then an installation on the environment's `PATH`. An invalid explicit path reports
-an error instead of selecting another installation. T3 Code does not update or remove manual
-installations. Clear **Binary path** to use managed installation controls.
+Set **Binary path** to the ACP executable on the environment and update it yourself.
+Leave the field blank to use the managed runtime, or a compatible executable on
+`PATH` if no managed runtime is installed.
 
 ## Models and threads
 
-The current official ACP exposes Gemini models only. T3 Code uses the model IDs and names
-returned for your account, including any model choices with different thinking levels. Models
-available in other Antigravity apps might not be available through this agent.
-The model picker updates when a running session reports new model choices.
-
-New threads use Gemini 3.8 Flash (High) when your account offers it. Older Gemini generations
-stay available under **Legacy models** in the picker.
-
-Threads keep their selected model when you resume them. If that model is no longer available,
-T3 Code asks you to select an available model instead of silently changing it.
-
-Use Antigravity's native `/plan` command to request a plan. T3 Code's separate Plan mode control
-is not available for this provider.
+The model list comes from your Antigravity account and can differ from other
+Antigravity apps. A resumed thread keeps its selected model. If access to that
+model ends, select another available model before continuing.
 
-Project skills should use `.agents/skills`. T3 Code also discovers `.gemini/skills` and the legacy
-`.agent/skills` location. When multiple locations define the same skill name, `.gemini/skills`
-takes precedence, followed by `.agents/skills` and then `.agent/skills`.
+Use Antigravity's native `/plan` command for planning. T3 Code's separate Plan mode
+is unavailable. Tool approvals follow [Permission modes](./permission-modes.md).
+Questions with fixed choices still need one of the offered answers, even in
+**Full access**.
 
-Antigravity reads and edits workspace files through T3 Code. Each write shows up as a file
-change approval with the content, so **Supervised** and **Auto-accept edits** behave the same way
-they do for other providers. Attach images, PDFs, text files, or audio clips to a message and
-the agent receives them directly.
+T3 Code keeps conversation history and file diffs, but Antigravity cannot rewind
+its conversation. Reverting a thread or editing and resubmitting an earlier turn
+is unavailable. Continue with a follow-up message or start a new thread.
 
-When the agent offers **Allow for this thread** on a shell or web tool, T3 Code shows Google's
-prompt injection warning next to that choice. Untrusted content could re-run the same action
-without asking again.
+### Skills and attachments
 
-Antigravity can ask you to choose from a fixed set of answers. Select one of the offered
-choices. These questions do not accept custom text and still appear in **Full access** mode.
-See [Permission modes](./permission-modes.md) for tool approvals.
+Put project skills in `.agents/skills`. T3 Code also reads `.gemini/skills` and the
+legacy `.agent/skills` directory. Among these project locations, the first copy
+wins in this order: `.gemini/skills`, `.agents/skills`, `.agent/skills`. See
+[commands and skills](./composer.md#commands-and-skills) for invoking them.
 
-T3 Code keeps thread history and file diffs. Antigravity does not support conversation rewind,
-so reverting a thread or editing and resubmitting an earlier turn is unavailable. Send a
-follow-up message or start a new thread instead.
+Antigravity accepts images, PDFs, text files, and supported audio formats directly.
+Its limits are 1 MiB per text file, 10 MiB per image, 20 MiB per audio clip, and
+50 MiB total attachments per message. Unsupported formats are rejected. These
+limits can be lower than the general upload limit; uploading a file does not
+mean this provider can use it.
 
 ### Subagents
 
-Subagent launches appear as **Antigravity subagent batch** in **Agents** on web and desktop,
-and in the work log on mobile. One launch can start several agents. The batch stays active
-after launch while the parent turn runs. When that turn ends, the entry becomes idle and
-states that individual agent status is unavailable. Launch errors remain visible.
-The conversation summary counts launches as batches and shows idle or stopped batches
-without a completion checkmark.
-
-The official ACP agent does not send individual child status, names, models, token usage,
-or reply ownership. T3 Code cannot show separate child entries or separate child replies
-from the parent conversation. The launch description is not a child result. Batch entries
-cannot be opened or controlled as separate threads.
+Antigravity groups subagent activity into batches. You cannot open or control
+individual subagents, and an idle batch does not confirm that every child
+succeeded. See [agent work](./thread-sidebar.md#inspect-agent-work) for where to
+inspect activity.
 
 ## Accounts and removal
 
-Each Antigravity provider instance has its own Google sign-in on its environment. Use
-**Add provider** in web or desktop provider settings to create a separate instance for another
-account. To replace an instance's account, sign out first, then sign in again.
-
-| Action                                                                           | Result                                                                                                                        |
-| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Disable Antigravity                                                              | Stops the instance's sessions. Keeps Google sign-in, thread history, and files.                                               |
-| Sign out of Google                                                               | Stops the instance's sessions and removes its saved Google credentials. Keeps thread history and files.                       |
-| Remove downloaded runtime on web or desktop, or Remove managed install on mobile | Removes the runtime shared by Antigravity instances on that environment. Keeps Google credentials, thread history, and files. |
-
-Send `/logout` by itself in an Antigravity thread to sign out that provider instance. This has
-the same effect as **Sign out of Google**, including stopping its other sessions.
+Add an Antigravity provider instance for each Google account in
+**Settings > Providers** on web or desktop. Each has its own sign-in; downloaded
+runtimes are shared on the environment.
 
-Before removing a managed runtime, disable the instances that use it and cancel any active
-installation. T3 Code refuses removal while the runtime is in use. An explicit **Binary path**
-that points into the managed runtime must be cleared first.
+| Action                    | Effect                                                            |
+| ------------------------- | ----------------------------------------------------------------- |
+| Disable                   | Stops the instance's sessions and keeps its Google sign-in.       |
+| Sign out of Google        | Stops the instance's sessions and removes its saved Google login. |
+| Remove downloaded runtime | Removes the shared installation and keeps Google credentials.     |
 
-## Account access and errors
+All three keep thread history and workspace files. Sending `/logout` by itself in
+a thread signs out its instance, including stopping that instance's other sessions.
+Sign out, then sign in again to replace an account.
 
-Google controls account eligibility, models, and usage limits. T3 Code does not report your
-paid-plan tier or remaining subscription quota. See Google's [Antigravity plans][plans] and
-[personal Google sign-in guide][google-setup].
+Before removing a managed runtime, disable its instances and cancel any active
+installation. Clear any explicit binary path pointing into that runtime. Removal
+is refused while the runtime is in use.
 
-After an environment restarts, Google sign-in can show as not checked until an authenticated
-session succeeds. To check account access and reload models, use **Refresh provider status**
-in web or desktop provider settings, or **Refresh models** in the mobile model picker. Refresh
-uses saved Google sign-in and does not open a login page. If sign-in is required, use the
-provider's setup controls. Automatic status checks verify the installation only.
+## Check access and troubleshoot
 
-The packaged runtime can be slow to start, especially on Windows. Health checks, model refresh,
-and sign-out each allow up to 90 seconds before reporting a timeout.
+To check access and reload models, use **Refresh provider status** in web or desktop
+provider settings, or **Refresh models** in mobile thread settings. If asked to
+sign in again, use setup on web or desktop.
 
-If Google reports `SUBSCRIPTION_REQUIRED`, an account restriction, or a usage limit, read the
-provider's message. A finished turn can contain an upstream error instead of completed work.
-Use any retry time Google supplies. T3 Code does not switch to an API key to get past the limit.
+If Google reports `SUBSCRIPTION_REQUIRED`, an account restriction, or a usage limit,
+follow the provider's message and any retry time. See [Google's account plans][plans]
+for eligibility.
 
 [registry]: https://github.com/agentclientprotocol/registry/blob/main/antigravity-acp/agent.json
 [plans]: https://antigravity.google/docs/plans
-[google-setup]: https://antigravity.google/docs/ide/extensions/zed
diff --git a/docs/user/providers-claude.md b/docs/user/providers-claude.md
index 498fa802474d..b43b58e52627 100644
--- a/docs/user/providers-claude.md
+++ b/docs/user/providers-claude.md
@@ -1,236 +1,97 @@
 # Claude
 
-This guide is for people who want to use more than one Claude setup in T3 Code. For Codex, see
-[Codex](./providers-codex.md). For first-time setup, see [Install T3 Code](./install.md).
+T3 Code uses Claude Code's login and configuration. Start with the default provider
+for one account; [provider setup](./install.md#providers) covers installation and
+shared provider settings.
 
-Common reasons:
+## Separate accounts or configurations
 
-- 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
+Use a separate Claude config directory for each account. This also works for named
+presets that need different Claude settings or a router connection.
 
-## 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_CONFIG_DIR path: empty
-```
-
-An empty `CLAUDE_CONFIG_DIR path` means T3 Code uses Claude Code's normal config directory.
-
-When you set this field, T3 Code points Claude Code at that directory with the
-`CLAUDE_CONFIG_DIR` environment variable. It does not change `HOME`, so your system keychain and
-the rest of your environment stay as they are.
-
-## Reduce Context Usage
-
-In Settings, open your Claude provider and set **Auto-compact after** to a token count between
-`100000` and `1000000`. For example, `300000` compacts the conversation into a summary once it
-reaches about 300,000 tokens, without changing the model's context window. Leave the field
-empty to keep Claude Code's default behavior.
-
-On web and desktop, when you return to an older Claude thread with a large context, T3 Code
-offers to compact the conversation before you continue. You can also select **Compact context**
-from the context meter. On every client, you can enter `/compact` in the message composer, and
-Claude can show its own resume prompt when you continue an old session.
-
-## Where Claude Skills Are Loaded
-
-T3 Code looks for Claude skills in the Claude config directory's `skills` folder and
-`<workspace>/.claude/skills`, the two places Claude Code loads them from.
-
-If the same skill name exists in more than one folder, the one in the Claude config directory
-wins, the same way Claude Code resolves it.
-
-A skill set to `off` in Claude Code's `skillOverrides` is left out of both composer menus. A skill
-marked `disable-model-invocation` still appears, because you start it yourself when you pick it.
-Claude Code runs one skill per message; when a message names several, the last one runs directly and
-Claude starts the others through its Skill tool, which refuses skills marked
-`disable-model-invocation`.
-
-## I Want Work And Personal Claude Accounts
-
-Use a different Claude config directory for each account.
-
-Example:
-
-```text
-default config dir           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_CONFIG_DIR path: empty
-```
-
-### Set Up The Second Account
-
-Log in with a separate config directory:
-
-```bash
-mkdir -p ~/.claude_personal_home
-CLAUDE_CONFIG_DIR=~/.claude_personal_home claude auth login
-```
-
-Use `CLAUDE_CONFIG_DIR`, not `HOME`. Setting `HOME` writes the login to
-`~/.claude_personal_home/.claude`, which is not where T3 Code looks.
-
-Then add another Claude provider in T3 Code:
-
-```text
-Display name: Claude Personal
-Binary path: claude
-CLAUDE_CONFIG_DIR 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 config directory for an existing thread. A
-different config directory 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 config directory, so T3 Code keeps separate config directories 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_CONFIG_DIR 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:
+Keep your existing account in the default directory. On the environment's machine,
+create the second login:
 
 ```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
+mkdir -p ~/.claude_personal
+CLAUDE_CONFIG_DIR=~/.claude_personal claude auth login
 ```
 
-Add those to the same provider's Environment variables section if you want stable model choices.
+Add another Claude instance in **Settings > Providers**:
 
-### Verify OpenRouter Is Being Used
+| Instance        | Binary path | CLAUDE_CONFIG_DIR path |
+| --------------- | ----------- | ---------------------- |
+| Claude Work     | `claude`    | Leave empty            |
+| Claude Personal | `claude`    | `~/.claude_personal`   |
 
-Open a Claude session and run:
+An empty config-directory setting uses Claude Code's normal configuration. The
+custom setting changes `CLAUDE_CONFIG_DIR`, leaving `HOME` and the system keychain
+location intact. Use the same variable for the login command. Setting `HOME`
+instead can put credentials where this provider will not find them.
 
-```text
-/status
-```
-
-You should see the Anthropic base URL set to:
+Check the account reported in provider settings after signing in. Existing
+threads can switch only between Claude instances with the same config directory.
+Separate account directories stay isolated, including their local conversation
+state. Claude does not have Codex's shared-home and shadow-home arrangement.
 
-```text
-https://openrouter.ai/api
-```
+For presets that differ only in API keys or endpoints, use the instance's
+**Environment variables**. Variable assignments do not belong in **Launch arguments**.
 
-You can also check the OpenRouter activity dashboard for requests from your API key.
+## Compact long conversations
 
-### Common OpenRouter Mistakes
+Set **Auto-compact after** in the Claude provider settings to an integer between
+`100000` and `1000000`. For example, `300000` asks Claude to summarize at about
+300,000 tokens. This changes when compaction happens, not the model's context
+window. Leave it empty for Claude Code's default.
 
-- 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.
+You can also send `/compact` in an existing conversation. Web and desktop offer
+**Compact context** from the context meter and may suggest it when you return to
+a large older thread. See [commands and skills](./composer.md#commands-and-skills)
+for using composer commands.
 
-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>.
+## Usage limits
 
-## I Want To Use Claude Code Router
+If your Claude subscription runs out of usage mid-turn, the thread shows which
+limit was reached and the remaining wait when Claude provides a reset time.
+Claude Code holds the turn until that window reopens, so it can keep showing as
+working. Wait for the reset, or stop the turn and continue later. The warning's
+timestamp shows when the displayed wait started.
 
-Claude Code Router is useful when you want a local routing layer with more control than a direct
-OpenRouter setup.
+## Skills
 
-T3 Code does not need a special Claude Code Router provider. Treat the router as a Claude
-environment: give a Claude provider its own `CLAUDE_CONFIG_DIR path`, and put whatever variables
-the router tells you to export into that provider's Environment variables section. Mark tokens
-and API keys as sensitive.
+Claude skills come from the config directory's `skills` folder and the project's
+`.claude/skills` folder. If both define the same name, the config-directory copy
+wins. Skills disabled in Claude's settings do not appear in the composer.
 
-```text
-Display name: Claude Router
-Binary path: claude
-CLAUDE_CONFIG_DIR path: ~/.claude_router_home
-```
+Use `$` in the composer to select a skill. Skills marked `disable-model-invocation`
+can still be started by you. Invoke those one per message: Claude directly runs
+only the last named skill and may try to start earlier ones through its Skill
+tool, which refuses skills reserved for manual invocation.
 
-Follow the upstream project's README for the router's own install, startup, and configuration
-steps: <https://github.com/musistudio/claude-code-router>.
+## OpenRouter
 
-## I Want Different Claude Settings, Not A Different Account
+Create a Claude instance with its own config directory, such as
+`~/.claude_openrouter`, and keep **Binary path** set to `claude`. In that instance's
+**Environment variables**, use:
 
-Create another Claude provider with the same account if you want a named preset.
+| Variable               | Value                                     |
+| ---------------------- | ----------------------------------------- |
+| `ANTHROPIC_BASE_URL`   | `https://openrouter.ai/api`               |
+| `ANTHROPIC_AUTH_TOKEN` | Your OpenRouter API key, marked Sensitive |
+| `ANTHROPIC_API_KEY`    | An explicitly empty value                 |
 
-Examples:
+If that Claude config directory has a cached Anthropic login, run `/logout` in a
+Claude Code session using that directory before starting the router setup. Cached
+login credentials can conflict with the router token.
 
-- "Claude Default"
-- "Claude Router"
-- "Claude Experimental"
+Verify requests in OpenRouter's activity dashboard. For model-role overrides and
+current compatibility requirements, use the
+[OpenRouter Claude Code guide](https://openrouter.ai/docs/cookbook/coding-agents/claude-code-integration).
 
-If the preset needs different Claude files, give it a different `CLAUDE_CONFIG_DIR path`. If it needs
-different API keys, base URLs, or router settings, use Environment variables.
+## Other routers
 
-Do not put environment variable assignments in `Launch arguments`.
+A local router uses an ordinary Claude provider instance. Give it a separate
+config directory and put the router's endpoint and credential variables in that
+instance's **Environment variables**. The router must run where the environment
+can reach it. Follow the [Claude Code Router instructions](https://github.com/musistudio/claude-code-router)
+for its installation and routing configuration.
diff --git a/docs/user/providers-codex.md b/docs/user/providers-codex.md
index 5556ef18f119..417287cc0032 100644
--- a/docs/user/providers-codex.md
+++ b/docs/user/providers-codex.md
@@ -1,179 +1,71 @@
 # Codex
 
-This guide is for people who want to use more than one Codex account in T3 Code. For Claude, see
-[Claude](./providers-claude.md). For first-time setup, see [Install T3 Code](./install.md).
+For one account, use the default Codex provider with your normal Codex login.
+[Provider setup](./install.md#providers) covers installation, Settings > Providers,
+and custom binaries or environment variables.
 
-Common reasons:
+## Use multiple accounts
 
-- 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
+A shared Codex home with a shadow home lets work and personal accounts continue
+the same threads. The accounts share Codex sessions and configuration while keeping
+their own login and available models.
 
-## 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
-```
-
-## Send feedback to OpenAI
-
-In an existing Codex thread, send `/feedback` or `/feedback` followed by a description of the
-issue. T3 Code uploads the thread and Codex logs to OpenAI and shows a thread ID that you can copy
-and share with OpenAI employees.
-
-## Answer questions while Codex works
-
-Codex can ask questions without stopping its work. Choose a suggested answer or enter your own
-in the question panel. Questions without suggested answers accept text.
-
-Your answers are sent as a new message. They reach the current turn while Codex is working, or
-start a new turn if it has finished. Unanswered questions stay available after you reconnect.
-This works in the web, desktop, and mobile apps. Codex must support async questions.
-
-## Sub-agent models
-
-The web and desktop Agents panel shows each sub-agent's model and reasoning effort when Codex
-reports them. If Codex does not report either value, T3 Code leaves it out instead of using the
-parent agent's settings.
-
-## Browser and computer activity
-
-Browser and Computer Use calls show their user-facing task title when Codex provides one. Expanded
-activity groups show an icon for every call. Website calls use the active page's favicon when it is
-available, and desktop app calls use the app's native icon on macOS when available. Other hosts use
-a generic fallback glyph.
-
-Collapsed activity groups are summarized by source, such as `Used Chrome integration`, instead of
-showing the underlying tool name. Website favicons and native app icons keep their original colors;
-integrations that provide separate light and dark logos use the logo for the current appearance.
-
-## Approve access to other apps
-
-When a Codex tool needs access to an app such as Safari, T3 Code shows the app name and asks for
-approval. You can approve, decline, or cancel the request from the desktop app, web app, or mobile
-app. Some tools also offer approval for the current session or permanent approval.
-
-## 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:
+Keep your first account in `~/.codex`. On the environment's machine, sign the
+second account into a fresh directory:
 
 ```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
+mkdir -p ~/.codex_personal
+CODEX_HOME=~/.codex_personal codex login
 ```
 
-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.
+Then add a second Codex instance in **Settings > Providers**:
 
-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.
+| Instance       | CODEX_HOME path | Shadow home path    |
+| -------------- | --------------- | ------------------- |
+| Codex Work     | `~/.codex`      | Leave empty         |
+| Codex Personal | `~/.codex`      | `~/.codex_personal` |
 
-## Can I Switch Accounts In An Existing Thread?
+Both instances must use the same **CODEX_HOME path**. T3 Code prepares the shared
+state in the shadow directory; do not populate it by copying your whole Codex
+home.
 
-Yes, when both Codex providers share the same `CODEX_HOME path`.
+The shadow account needs its own `auth.json` file. If Codex uses an OS credential
+store, configure file storage for this setup. See
+[OpenAI's credential storage guide](https://learn.chatgpt.com/docs/auth#credential-storage).
 
-For example:
+Use a completely separate **CODEX_HOME path**, with no shadow home, when you want
+separate Codex sessions and configuration. That instance cannot continue threads
+from the other home.
 
-```text
-Codex Work      CODEX_HOME path: ~/.codex
-Codex Personal  CODEX_HOME path: ~/.codex, Shadow home path: ~/.codex_p
-```
+## Switch accounts in an existing thread
 
-Those two providers are considered compatible for continuation, so the locked model picker can show
-both.
+Choose the other account from the thread's model picker. T3 Code offers compatible
+Codex instances that share the thread's **CODEX_HOME path**. Changing accounts does
+not move the conversation into a separate Codex home.
 
-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 the account is missing from the picker, compare the home paths in provider
+settings. If two instances show the same unexpected account or models, check their
+reported accounts, refresh provider status, and confirm the second instance has
+its own shadow path and login. A shadow-home conflict usually means the directory
+contains a copied Codex setup. Use a fresh shadow directory and sign in again.
 
-## If Both Accounts Look The Same
+## Answer questions while Codex works
 
-If two Codex providers show the same account or the same unexpected model list:
+Codex can ask a question and keep working. Answer it in the thread's question
+panel. The answer becomes a new message: it reaches the active turn, or starts
+another turn if Codex has finished. Unanswered questions survive reconnects.
+This requires a Codex version that supports async questions.
 
-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`.
+## Approve app access
 
-Example cleanup:
+Codex tools can request access to another app. Respond to the named app's request
+in the thread on web, desktop, or mobile. Some tools offer access for one request,
+the current session, or permanently. See [Permission modes](./permission-modes.md)
+for command and file approvals.
 
-```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.
+## Send feedback to OpenAI
 
-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.
+In an existing Codex thread, send `/feedback` with an optional description, for
+example `/feedback The agent stopped before finishing the tests`. This uploads
+the conversation and Codex logs to OpenAI. The returned thread ID can be shared
+with OpenAI support.
diff --git a/docs/user/providers-opencode.md b/docs/user/providers-opencode.md
index a066b038833d..23de99798956 100644
--- a/docs/user/providers-opencode.md
+++ b/docs/user/providers-opencode.md
@@ -1,62 +1,49 @@
 # OpenCode
 
-T3 Code uses the OpenCode setup on the connected environment. With a remote environment, its
-OpenCode login and configuration apply, not the setup on your desktop or phone.
+Install and authenticate OpenCode on the machine running your environment, then
+enable it in **Settings > Providers**. See [provider setup](./install.md#providers).
+T3 Code requires OpenCode 1.14.19 or newer, including when you connect an existing
+OpenCode server.
 
-T3 Code requires OpenCode 1.14.19 or newer. It checks the server version before it loads models or
-starts work. If the check fails, update OpenCode or fix the server URL and password, then refresh
-the provider status. Reconnecting the client also runs the check again.
+## Local or external server
 
-## Server authentication
+Leave **Server URL** empty to let T3 Code start OpenCode locally. A password in
+provider settings applies to both that server and T3 Code's connection. With no
+password setting, the local server uses `OPENCODE_SERVER_PASSWORD` from its
+environment.
 
-Without a server URL, T3 Code starts a local OpenCode server. The process inherits
-`OPENCODE_SERVER_PASSWORD` from the environment. A password in the provider settings overrides
-that environment value for both the local process and T3 Code.
+To use an existing OpenCode server, set **Server URL** and its password in provider
+settings. T3 Code uses only that configured password for an external server; it
+does not forward a local `OPENCODE_SERVER_PASSWORD`. If connection or version checks
+fail, check the URL, credentials, and OpenCode version, then refresh provider status.
 
-With a server URL, T3 Code connects to that external server and uses only the password in the
-provider settings. It does not send a local `OPENCODE_SERVER_PASSWORD` to an external server.
-OpenCode uses this password for HTTP Basic authentication.
+After a lost connection, send another prompt to reconnect to the same OpenCode
+session.
 
-## Stop a turn
+## Approvals
 
-When you select **Stop**, T3 Code stops the main OpenCode session and all nested child sessions.
-T3 Code waits for this cleanup before it marks the turn as stopped or sends the next prompt. It
-does not stop unrelated OpenCode sessions.
+OpenCode follows the shared [permission modes](./permission-modes.md). **Auto** has
+the same rules as **Supervised** because OpenCode has no AI approval reviewer.
+Environment files such as `.env` and `.env.local` need approval in restricted
+modes even though normal file reads do not; `.env.example` is allowed.
 
-Stop reports an error if OpenCode cannot list or stop a child session. When T3 Code closes an
-OpenCode session, it also tries to stop the child sessions, but this teardown is best effort.
+**Allow for workspace** applies to matching requests in other OpenCode sessions
+using the same workspace. It is broader than the current thread, especially on a
+shared external server. Use **Allow once** for a single request. Denying an action
+does not stop the whole turn.
 
-## Refresh the model list
+## Refresh models, commands, and skills
 
-T3 Code loads the model list when an enabled OpenCode provider starts and keeps the list in its
-cache. Reconnecting a client or using a refresh control asks OpenCode for the list again. The
-periodic provider health setting does not refresh OpenCode's catalog.
+After changing an OpenCode login or configuration, use **Refresh provider status**
+in **Settings > Providers** for that environment. On mobile, use **Refresh models**
+in the thread settings. Reconnecting also refreshes the catalog; periodic provider
+health checks do not.
 
-After changing an OpenCode login or configuration outside T3 Code, open **Settings > Providers**,
-select the environment, and choose **Refresh provider status**. Changing the provider's
-configuration in T3 Code also replaces that provider connection.
+Credential changes are read on refresh. Native OpenCode configuration can remain
+cached while the local helper is running. Let it sit for 30 seconds without model
+refreshes or text-generation work, then refresh again to reload the files. Repeated
+refreshes keep the helper alive. An external server may need its own reload or
+restart before T3 Code can see configuration changes.
 
-On mobile, open the thread settings and select **Refresh models**. The control stays disabled while
-the refresh runs and shows an error if the refresh fails.
-
-OpenCode reads credential changes on each model-list request. Native OpenCode configuration files
-can stay cached while the local helper is running. The helper closes after 30 seconds with no
-model-list or text-generation work. Refresh after that idle period to start a new helper and read
-the file changes. Repeated refreshes or active helper work can extend this wait.
-
-T3 Code does not own an external OpenCode server. Native configuration changes on that server can
-require its own reload or restart before a refresh returns the new list.
-
-If a refresh fails, T3 Code keeps the last known models, slash commands, and skills. Fix the
-connection, then refresh again. A successful refresh can remove entries that OpenCode no longer
-offers.
-
-## Continue an existing thread
-
-An existing thread keeps its selected model and options when that model is temporarily absent
-from the catalog. The web picker shows an **Unavailable** row and keeps saved option values visible
-until the model metadata returns. T3 Code does not switch the thread to the first model in the
-list.
-
-The stored selection does not guarantee that OpenCode can still run the model. If the provider
-rejects it, select an available model before trying again.
+Existing threads keep their selected model and options even when it disappears
+from the catalog. If OpenCode rejects that model, select an available one and retry.
diff --git a/docs/user/remote-access.md b/docs/user/remote-access.md
index 50a07b50fd2b..ec2724b4b04e 100644
--- a/docs/user/remote-access.md
+++ b/docs/user/remote-access.md
@@ -1,287 +1,171 @@
-# Remote Access
+# Remote access
 
-Use this when you want to connect to a T3 Code server from another device such as a phone, tablet, or separate desktop app.
+Connect a phone, browser, or another desktop app to T3 Code running on a different
+machine. That machine must stay running and reachable while you work.
 
-## T3 Connect troubleshooting
-
-Run `t3 connect` on the server machine to authorize it and optionally install the background service.
-The authorization message means your sign-in was saved. The server must then start and establish its
-relay link before the machine is reachable.
-
-`t3 connect status` reports saved authorization and link configuration, not a live reachability
-check. If the machine appears offline, run `t3 service status` on it and read the displayed log.
-On Linux, a service that works while SSH is open but stops after logout usually has lingering
-disabled. See [background service troubleshooting](./background-service.md#troubleshooting).
-
-Relay errors include the returned reason and trace ID when available:
-
-| Error                                                            | Next step                                                                                                                                                                   |
-| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `environment_link_limit_exceeded` / managed tunnel limit reached | Unlink an unused environment in T3 Connect, then restart T3 Code on this machine.                                                                                           |
-| `auth_invalid` / `invalid_bearer`                                | Run `t3 connect login`. If the stored credential was revoked, run `t3 connect logout`, then `t3 connect` and restart the server.                                            |
-| Expired or invalid link proof                                    | Check the server's date and time, update T3 Code, and restart it. Include the reason and trace ID if it still fails.                                                        |
-| HTTP 403 without a recognized error response                     | Check relay access and any proxy or firewall restrictions. Include the Cloudflare Ray ID if one was returned; an HTTP status alone does not identify the cause.             |
-| HTTP 408, 429, or 5xx                                            | The server retries temporary failures during startup for up to ten minutes. Check network and relay availability; include the trace ID when reporting a persistent failure. |
-
-Authorization and other permanent 4xx rejections stop the startup link attempt immediately.
-After correcting them, restart the server. For the Linux background service, use
-`systemctl --user restart t3code.service`; for a foreground server, stop it and run `t3 serve` again.
-Keep the diagnostic message and trace ID when reporting a problem. Do not post authorization codes,
-pairing URLs, or the contents of the secrets directory.
-
-## Quick Pairing for a Running Server
-
-If a server is already running on this machine, mint a fresh pairing token and QR code without restarting anything:
-
-```bash
-npx t3 pair
-```
+## T3 Connect
 
-`t3 pair` finds the running server (the shared `~/.t3` install, or the current worktree's dev server when run inside one), issues a one-time pairing token, and prints the pairing URL as a QR code you can scan from your phone.
+T3 Connect makes an environment available to your other devices without setting
+up router forwarding. In the desktop app on the host, open **Settings →
+Connections**, sign in, and enable **T3 Connect** for that environment.
 
-If the server is only bound to loopback, the printed URL is not reachable from another device. Pair over your tailnet instead:
+For a command-line host, run:
 
 ```bash
-npx t3 pair --tailscale
+npx t3@latest connect
 ```
 
-This publishes the server over Tailscale Serve HTTPS (configuring the mapping if needed — it persists until you run `tailscale serve --https=443 off`) and pairs through the `https://machine.tailnet.ts.net/` URL. Use `--tailscale-serve-port` for a different HTTPS port, `--ttl` to change the token lifetime, and `--base-dir` to target a specific data directory.
-
-If no server is running, `t3 pair` says so and points you at `npx t3 serve` or `npx t3 connect`.
-
-## Recommended Setup
-
-Use a trusted private network that meshes your devices together, such as a tailnet.
-
-That gives you:
-
-- a stable address to connect to
-- transport security at the network layer
-- less exposure than opening the server to the public internet
-
-## Enabling Network Access
-
-There are three ways to reach your server from another device: expose the desktop app's backend,
-run a headless server from the CLI, or have the desktop app launch T3 Code over SSH.
-
-### Option 1: Desktop App
-
-If you are already running the desktop app and want to make it reachable from other devices:
-
-1. Open **Settings** → **Connections**.
-2. Under **This environment**, toggle **Network access** on. This will restart the app and run the backend on all network interfaces.
-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.
-
-Pairing codes and share links are available only in the client that created them,
-while its Connections page remains open. After you leave the page or reload it,
-create a new link to share. Other clients can see the active link's name, scopes,
-and expiry, and can revoke it if they have access management permission.
-
-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.
-
-In the mobile app's **Add Environment** form, a numeric IP address without a scheme uses HTTP. Include `https://` explicitly when the backend is served over HTTPS.
-
-### 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 off until you opt in. Turn on **Enable Tailscale HTTPS**
-on the **Tailscale HTTPS** row in **Settings** → **Connections**. 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. Turn the same switch off to stop it.
-
-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.
+Follow the sign-in instructions. Setup offers a
+[background service](./background-service.md); if you decline it, start the
+server with `npx t3 serve`. Saving your sign-in alone does not make the machine
+reachable.
 
-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.
+On your other device, sign in to the same T3 Connect account and choose the
+environment. Over SSH, the CLI prints a browser link and accepts the returned
+authorization code, so you do not need to forward an OAuth callback port.
 
-### Option 2: Headless Server (CLI)
+T3 Connect renews access credentials when needed without disconnecting a healthy
+connection. Pull request diffs and provider settings keep working after the
+previous credential expires. A failed renewal affects that request; it does not
+disconnect an otherwise healthy conversation.
 
-Use this when you want to run the server without a GUI, for example on a remote machine over SSH.
+## Pair over a LAN or private network
 
-Run the server with `t3 serve`.
+Use direct pairing when the other device can reach the host's network address.
 
-```bash
-npx t3 serve --host "$(tailscale ip -4)"
-```
-
-`t3 serve` starts the server without opening a browser and prints:
-
-- a connection string
-- a pairing token
-- a pairing URL
-- a QR code for the pairing URL
-
-From there, connect from another device in either of these ways:
+On a desktop host, open **Settings → Connections**, enable **Network access**,
+then create a pairing link using an address the other device can reach. Changing
+network access restarts the desktop app. You can turn it off in the same place.
 
-- 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:
+For a command-line host, replace `<private-ip>` with the host's LAN or tailnet
+address:
 
 ```bash
-npx t3 serve --tailscale-serve
+npx t3 serve --host <private-ip>
 ```
 
-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:
+If a server is already running, generate a fresh link without restarting it:
 
 ```bash
-npx t3 serve --tailscale-serve --tailscale-serve-port 8443
+npx t3 pair
 ```
 
-Once paired, add projects normally: open the Command Palette and choose **Add Project**, then pick
-the environment the project lives on. Every saved environment is offered, not only the local one.
+Scan the QR code on your phone or paste the pairing URL into **Add environment**
+in the receiving app. Connection settings are under **Settings → Connections**
+on web and desktop and **Settings → Environments** on mobile. A loopback address
+such as `127.0.0.1` reaches only the device opening the link.
 
-### Option 3: Desktop-Managed SSH Launch
+Pairing authorizes that device for future connections. Use a fresh one-time link
+for each new device; you do not need the original token to reconnect. Links
+created in Settings can only be copied from the client that created them while
+its Connections page stays open. If you leave or reload that page, create
+another link to share.
 
-Use this when you want the desktop app to start or reuse T3 Code on another machine over SSH.
+### Tailscale HTTPS
 
-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.
+Join both devices to the same tailnet. In the desktop app, enable **Tailscale
+HTTPS** in **Settings → Connections**. Turn it off there to remove that route.
 
-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.
+To start a command-line server with Tailscale HTTPS:
 
-SSH launch is a desktop feature because it needs local process and SSH access. Once the environment is paired and saved, it uses the same environment list and connection model as direct LAN, Tailscale, HTTPS, or future tunnel-backed environments.
-
-#### SSH Launch Troubleshooting
-
-The desktop SSH launcher connects with a non-interactive `sh` session, writes a small launcher script under `~/.t3/ssh-launch/<host-key>/`, starts or reuses a remote T3 server, and forwards the remote loopback port back to your desktop.
-
-The remote host must have a compatible Node.js runtime. T3 Code uses the server package's `engines.node` requirement:
-
-```text
-^22.16 || ^23.11 || >=24.10
+```bash
+npx t3 serve --tailscale-serve
 ```
 
-During SSH launch, T3 Code first checks whether `node` is on `PATH`. If it is missing, the launcher
-looks in the usual install directories and tries to activate a version manager if it finds one
-(Volta, asdf, mise, fnm, nodenv, nvm). That covers most setups, but a version manager that only
-initializes from an interactive shell profile will not be picked up.
-
-If launch fails with `node: command not found`, a port-scan failure, or a message that the remote Node version does not satisfy the required range, SSH into the host and check the same non-interactive shell path T3 Code uses:
+For an already-running server:
 
 ```bash
-ssh user@example.com 'sh -lc "command -v node && node --version"'
+npx t3 pair --tailscale
 ```
 
-If that does not print a compatible Node version, configure your version manager for non-interactive shells or install a compatible Node binary in one of the searched locations. For example, with nvm you may need a default alias:
+The pairing link uses an address such as `https://machine.tailnet.ts.net/`.
+The mapping created by `pair --tailscale` persists across restarts. Remove its
+default-port mapping with:
 
 ```bash
-nvm alias default 24
+tailscale serve --https=443 off
 ```
 
-With mise, asdf, fnm, or nodenv, make sure the tool's shim directory is installed and resolves to a Node version satisfying the range above without an interactive shell.
+If that port is already in use, choose another with
+`--tailscale-serve-port`. See `npx t3 pair --help` for other pairing options.
 
-If reconnecting after an app update fails, retry the SSH launch once. The launcher now compares its generated runner script, stops stale launcher-managed remote servers, clears the SSH launch PID/port state, and starts a fresh remote server. You should not normally need to delete `~/.t3/ssh-launch` or kill `t3` processes manually.
+### Hosted web app
 
-## Antigravity Google sign-in
+[app.t3.codes](https://app.t3.codes) needs an HTTPS endpoint. It connects directly
+to your server; a hosted pairing link does not make an unreachable backend
+reachable or convert HTTP to HTTPS.
 
-Antigravity runs and saves its Google credentials on the selected environment. You can install
-it and sign in from a remote web, desktop, or mobile client without an SSH login.
+For a plain HTTP LAN endpoint, use the direct pairing URL in a browser that can
+open it, or pair from the desktop app. On mobile, an IP address entered without a
+scheme uses HTTP, so include `https://` when your server uses HTTPS.
 
-Start in **Settings** > **Providers** on web or desktop. On mobile, open **Settings** >
-**Environments**, expand the environment, then choose **Set up Antigravity**.
+## Desktop-managed SSH
 
-After Google sign-in, a remote browser usually reaches a `127.0.0.1` page that cannot load.
-Copy that full address into the return URL field in the same T3 Code client. Choose
-**Continue** on web or desktop, or **Complete sign-in** on mobile. Keep the address unchanged.
-Do not paste the return URL into a thread or bug report.
+In the desktop app, open **Settings → Connections → Add environment**, choose
+**SSH**, and enter a host or SSH alias such as `user@example.com`. T3 Code starts
+or reuses a server there and opens the port forward for you. Projects, provider
+credentials, and agent work stay on the remote machine.
 
-See [Antigravity setup](./providers-antigravity.md) for installation, expiry, and account changes.
+The remote host needs a compatible [Node.js installation](./install.md#requirements)
+and [provider setup](./install.md#providers). If launch cannot find Node or reports
+an incompatible version, check it through a non-interactive SSH session:
 
-## Updating a Remote Server
-
-When the T3 Code web or desktop app and a remote server use different versions, a warning appears in
-the conversation and in **Settings** → **Connections**. Follow the action shown there: T3 Code may
-be able to update and reconnect the server for you, or it may ask you to update the desktop app or
-run a copied command on the server machine.
-
-If T3 Connect cannot connect, check the date and time on both devices, then try again.
-
-Finish active work before updating because the server restarts briefly. For step-by-step guidance,
-see [Keeping T3 Code in Sync](./updating.md).
-
-On a Linux host, you can keep the server running after logout and manage it independently of the
-connection method. See [Running T3 Code in the Background](./background-service.md).
-
-## How Pairing Works
-
-The remote device does not need a long-lived secret up front.
-
-Instead:
-
-1. `t3 serve` issues a one-time owner pairing token.
-2. The remote device exchanges that token with the server.
-3. The server creates an authenticated session for that device.
-
-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
+```bash
+ssh user@example.com 'sh -lc "command -v node && node --version"'
 ```
 
-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.
+Configure your version manager for non-interactive shells if this differs from
+your normal terminal. With nvm, setting a compatible default, such as
+`nvm alias default 24`, can resolve the problem.
 
-Hosted pairing does not proxy traffic through T3 Code. The browser still connects directly to the backend URL in the pairing link.
+If SSH reconnecting fails after an app update, retry the launch once. Removing
+the connection stops a server that T3 Code launched; a server that was already
+running is left alone.
 
-## Managing Access Later
+For Antigravity's Google callback on a remote host, see
+[remote sign-in](./providers-antigravity.md#sign-in-from-a-remote-device).
 
-Use `t3 auth` to manage access after the initial pairing flow.
+## Manage or revoke access
 
-Typical uses:
+On the host, **Settings → Connections** lets authorized administrators create
+pairing links and revoke client sessions. Revoking an unused link prevents new
+pairings; revoke a device's session to remove its existing access. Command-line
+management is available through `npx t3 auth --help`.
 
-- issue additional pairing credentials
-- inspect active sessions
-- revoke old pairing links or sessions
+A session with an open connection stays listed after its access credential
+expires.
 
-Use `t3 auth --help` and the nested subcommand help pages for the full reference.
+To remove an environment from T3 Connect, open your account menu's **T3 Connect**
+page, or **Settings → T3 Connect** on mobile, and choose **Deregister**. This
+revokes its cloud access and frees its host space even when the environment is
+offline or has been wiped.
 
-### Deregister a T3 Connect Environment
+On a command-line host, `t3 connect unlink` disables exposure while retaining
+your login; `t3 connect logout` also clears that login. Background-service
+[removal](./background-service.md#manage-the-service) is separate.
 
-Open your account menu and choose **T3 Connect** to see every environment registered to your
-account. On mobile, open **Settings** → **T3 Connect**. Choose **Deregister** to revoke an
-environment's T3 Connect access, remove any managed tunnel, and free its host space.
+Treat pairing URLs and authorization codes as passwords. Do not include them in
+screenshots, logs, or bug reports.
 
-Deregistration is an account action and does not need a connection to the environment, so it also
-works for a server that was wiped or is no longer reachable. Device-local connect and disconnect
-controls remain in **Settings** → **Connections** on web and desktop or **Settings** →
-**Environments** on mobile.
-
-## Security Notes
+## T3 Connect troubleshooting
 
-- 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.
+Run `t3 connect status` on the host to inspect saved authorization and link
+configuration. It is not a live reachability check. If the environment appears
+offline, run `t3 service status` and read the displayed log. If it disappears
+when SSH closes, see [background-service troubleshooting](./background-service.md#troubleshooting).
+
+| Error                                                     | Recovery                                                                                                                                    |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `environment_link_limit_exceeded` or managed tunnel limit | Deregister an unused environment, then restart T3 Code on the host.                                                                         |
+| `auth_invalid` or `invalid_bearer`                        | Run `t3 connect login`. If credentials were revoked, run `t3 connect logout`, then `t3 connect` again. Restart the server after signing in. |
+| Expired or invalid link proof                             | Check the host's date and time, update T3 Code, then restart it.                                                                            |
+| HTTP 403 without a recognized error                       | Check relay access, proxies, and firewall rules. Keep any Cloudflare Ray ID for a bug report.                                               |
+| HTTP 408, 429, or 5xx                                     | Check network and relay availability. Startup retries temporary failures for up to ten minutes.                                             |
+
+After fixing a permanent rejection, restart the host's server. On Linux, use
+`systemctl --user restart t3code.service` for the background service. For a
+foreground server, stop it and run `t3 serve` again with your usual options.
+Include the diagnostic message and trace ID when reporting a persistent failure.
+
+For a connection that still fails after linking, check the date and time on both
+devices. For server version warnings, follow [Updating T3 Code](./updating.md).
diff --git a/docs/user/source-control.md b/docs/user/source-control.md
index 482b3ccd1f12..2d7ed8badbec 100644
--- a/docs/user/source-control.md
+++ b/docs/user/source-control.md
@@ -1,181 +1,93 @@
-# Source Control Integrations
-
-T3 Code connects to your Git hosting provider so you can create pull requests, review code, and manage repositories without leaving the app.
-
-## 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, in one flow
-- If the local repository has no commits yet, publishing creates the remote and wires it up but does not push. Make a commit, then push normally.
-
-### Manage Code Reviews Without Context Switching
-
-**Create pull requests while you work**
-
-- Push a branch and create a pull request from the Git actions controls in the toolbar
-- T3 Code can suggest titles and descriptions based on your commits
-- With **Repository conventions** selected, generated source control text follows the project's
-  `AGENTS.md` along with recent commit subjects. Claude writers also follow `CLAUDE.md`
-- Supports GitHub Pull Requests, GitLab Merge Requests, Bitbucket Pull Requests, and Azure DevOps Pull Requests
-
-**Stay on top of open reviews**
-
-- See if your current branch already has an open PR/MR
-- When an agent finishes a turn on your thread's branch, T3 Code checks for a newly opened
-  PR/MR if background activity is enabled for that repository. Known reviews keep their normal
-  refresh schedule.
-- Open several reviews from the **Pull requests** page as tabs in the right panel
-- Your authored reviews stay at the top and use the selected sort within their group. By default,
-  see passing and approved reviews first, passing reviews awaiting approval next, and conflicting
-  reviews last. Smaller changes come first within each readiness group, and finished reviews follow
-  open work when all states are visible.
-- Filter the list by author or labels, rank authors by merges in the loaded results, see label and
-  change-size context on each row, and sort the results currently shown by readiness, update time,
-  creation time, or change size. Your filters, search, scope, and sort are restored when you return.
-- Merge now, or on GitHub, GitLab, and Azure DevOps, leave an auto-merge instruction with a chosen
-  strategy while checks are outstanding; see the completed state in the same control after the
-  pull request merges
-- On GitHub, approve fork workflows that are waiting to run and open a revert pull request for a
-  merged change
-- Timeline line counts stay hidden on merge commits, where GitHub's totals include upstream changes
-  brought in from the base branch
-- While working in a thread, open linked reviews in the same compact right-panel tabs without
-  leaving the conversation
-- Show a file tree next to a review's **Code** tab, or a thread's **Diff** panel, to browse the
-  changed files as folders and jump straight to any of them. The toolbar toggle remembers your
-  choice.
-- Enable **Settings → General → Proactive panels** to open a newly linked review automatically and
-  switch to the completed turn's diff when agent work finishes
-- Open the review directly in your browser with one click
-- If T3 Code cannot load a GitHub pull request, including when GitHub rate limits requests, use
-  **Open on GitHub** in the error view
-- Command-click (Control-click on Windows and Linux) a pull request number in the sidebar to open it in your browser instead of in T3 Code
-- Check out a teammate's branch to review code locally
-
-**Fix what you wrote, in place**
-
-- Comment while closing an open pull request or reopening a closed one when the host offers that
-  action
-- Rewrite a pull request's title and description from the review itself, in Markdown, with a
-  preview before you save
-- Rewrite your own comments the same way, wherever they are shown
-- Works on GitHub, GitLab, and Bitbucket. Azure DevOps takes a new title and description; its
-  comments stay read-only here, as they already were
-- On GitHub, put a label on a pull request or take one off from the **Labels** row of the review.
-  Changing labels needs triage access or better on the repository
-
-### 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 (version 2.81.0 or newer) 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
-
-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 tokens instead of a CLI tool. Two options, both set as environment variables on the
-machine running T3 Code.
-
-Recommended, a Bitbucket access token:
+# Source control
+
+T3 Code integrates with GitHub, GitLab, Bitbucket, and Azure DevOps to clone and publish
+repositories, create pull requests, and review changes.
+
+## Connect an account
+
+Install Git and configure authentication on the machine running your T3 Code server. For a remote
+environment, do this on the remote machine. After signing in, open **Settings → Source Control**
+and choose **Rescan**.
+
+### GitHub
+
+Install [GitHub CLI](https://cli.github.com/) 2.81.0 or newer, then sign in:
+
+```bash
+gh auth login
+```
+
+### GitLab
+
+Install [GitLab CLI](https://gitlab.com/gitlab-org/cli), then sign in:
+
+```bash
+glab auth login
+```
+
+### Bitbucket
+
+Set an access token in the server's environment:
 
 ```bash
 export T3CODE_BITBUCKET_ACCESS_TOKEN="your-access-token"
 ```
 
-Or an Atlassian account email plus API token, with read/write access to pull requests and
-repositories, plus read access to your user account (`read:user:bitbucket`, used to verify the
-connection):
+Or use an Atlassian account email and API token with read/write access to repositories and pull
+requests, plus user read access (`read:user:bitbucket`):
 
 ```bash
 export T3CODE_BITBUCKET_EMAIL="you@example.com"
 export T3CODE_BITBUCKET_API_TOKEN="your-token"
 ```
 
-If both are set, the access token wins. Restart T3 Code and verify the connection in **Source
-Control settings**.
+The access token takes precedence if both are configured. Restart the server after changing these
+variables.
+
+### Azure DevOps
+
+Install [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/), add the DevOps extension, and sign in:
+
+```bash
+az extension add --name azure-devops
+az login
+```
+
+## Clone or publish a project
+
+Use **Add Project** in the command palette (`Cmd/Ctrl+K`) to clone a repository. Choose a hosting
+provider or paste a Git URL, then choose where to save it.
 
-### For Azure DevOps
+For a local Git repository without a remote, **Publish Repository** creates a hosted repository,
+adds it as `origin`, and pushes your commits. If there are no commits yet, it creates the remote;
+make your first commit before pushing.
 
-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
-   ```
+## Create a pull request
 
----
+Use a thread's Git actions to commit, push, and create a pull request. T3 Code can generate commit
+messages, review titles, and descriptions from your changes.
 
-## Requirements & Troubleshooting
+Choose the writing style and model in **Settings → Source Control**. **Repository conventions**
+uses the project's instructions and recent commit subjects.
 
-**Git is required** – T3 Code uses Git for all local operations. Ensure `git` is installed on your server.
+## Review and merge
 
-**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.
+Open **Pull requests** to review changes and comments, request reviewers, check out a branch,
+or merge. You can edit review titles and descriptions and your own comments where the host allows it.
+GitLab calls these merge requests.
 
-**Common issues:**
+GitHub, GitLab, and Azure DevOps support auto-merge while checks are outstanding. GitHub also
+supports approving waiting fork workflows and opening a revert pull request for a merged change.
 
-- **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
-- **GitHub says it could not verify sign-in status** – T3 Code needs GitHub CLI 2.81.0 or newer to check sign-in status. Update `gh` (e.g., `brew upgrade gh`), then rescan
-- **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)
+For Azure DevOps, use the host website to view diffs or change comments. Bitbucket does not support
+reopening a declined pull request.
 
-**Need more help?** Check your provider's CLI documentation:
+## Troubleshooting
 
-- [GitHub CLI](https://cli.github.com/)
-- [GitLab CLI](https://gitlab.com/gitlab-org/cli)
-- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/)
+- **Not authenticated:** run the provider's login command on the server, then rescan. For Bitbucket,
+  confirm the running server received the environment variables.
+- **GitHub sign-in cannot be verified:** update GitHub CLI to at least 2.81.0.
+- **Push fails despite a connected account:** check the Git remote's credentials. SSH and HTTPS
+  remotes can require separate setup from the hosting provider's API access.
+- **A review cannot load:** open it on the host website while resolving connectivity, permissions,
+  or rate limits.
diff --git a/docs/user/telemetry.md b/docs/user/telemetry.md
new file mode 100644
index 000000000000..5fd4f91c9327
--- /dev/null
+++ b/docs/user/telemetry.md
@@ -0,0 +1,11 @@
+# Product usage data
+
+The T3 Code server sends product usage events to PostHog, associated with a hashed account or
+installation identifier. Events include the provider, model, reasoning effort, permission mode,
+turn result, duration, and main-agent token totals when available.
+
+Events do not include prompts, responses, file contents, authentication tokens, conversation IDs,
+raw provider events, or child-agent output. Child-agent token use is excluded from the totals.
+
+To disable collection, set `T3CODE_TELEMETRY_ENABLED=false` in the server's environment before
+starting it. This stops product events from being recorded or sent.
diff --git a/docs/user/terminal.md b/docs/user/terminal.md
new file mode 100644
index 000000000000..2e31ddf3b177
--- /dev/null
+++ b/docs/user/terminal.md
@@ -0,0 +1,8 @@
+# Terminal history
+
+Each terminal keeps up to 5,000 lines and 8 MiB of scrollback on its environment
+server. T3 Code removes the oldest output when either limit is reached. A long
+line can be shortened at the start. New terminal output is not truncated.
+
+These limits apply when you reconnect and when T3 Code restores saved terminal
+history. A client can show less scrollback than the server keeps.
diff --git a/docs/user/thread-sidebar.md b/docs/user/thread-sidebar.md
index 204678eb1d2f..e6c89c0343e7 100644
--- a/docs/user/thread-sidebar.md
+++ b/docs/user/thread-sidebar.md
@@ -1,84 +1,73 @@
-# Organizing threads
-
-Pin a thread from its context menu to keep it in the pinned section above your active work.
-`mod+shift+p` pins or unpins the thread you have open. Pinned threads are shown independently of
-their project, including when you connect to more than one environment.
-
-To require confirmation before unpinning, enable **Settings → General → Unpin confirmation**. The
-confirmation applies to the sidebar controls, thread menus, and the `mod+shift+p` shortcut.
-
-Pinned threads still move to **Settled** when they become inactive. They also move when their pull
-request merges if **Auto-settle merged threads** is enabled.
-
-Each server stores its own copy of the automatic settlement settings and checks them even when no
-web, desktop, or mobile client is connected. By default, it settles threads after three days without
-activity and when their pull request merges. An eligible idle thread also settles when its pull
-request closes. An open pull request blocks inactivity settlement. Active work, pending input, and
-live background work keep the thread active. T3 Code settles from a closed or merged pull request
-only when its timestamp is not older than the user's latest activity. If that timestamp is not
-available, the inactivity rule still applies. A manual un-settle also keeps the thread active.
-
-**Settled** lists threads by when their work finished, newest first. A thread you settle yourself
-sorts by the moment you settled it. A thread that settled on its own sorts by its last message or
-turn, not by when the server noticed it was inactive.
-
-Change these rules in **Settings > General**. The change is written to every connected environment
-whose server supports shared settings. An environment that is offline or needs a server update
-keeps its old value and does not appear in mismatch warnings. When a connected environment whose
-server supports shared settings holds a different value, **Settings > General** shows a warning
-that names it. Choose **Apply to all** to write your current values to the environments named in
-the warning. The same applies to the new-thread workspace mode and the source control writing
-style.
-
-A settings change affects future settlement and does not reopen a settled thread. Settings saved
-by older clients on one device no longer control this behavior.
-
-When you un-settle a thread, it returns to the top of the active list so you can find it right
-away. Its timestamps do not change. Other threads keep their positions.
-
-Right-click a pull request link in a thread and choose **Link to thread** to show that pull request
-in the sidebar. The thread settles when the linked pull request merges if **Auto-settle merged
-threads** is enabled. Right-click the same link and choose **Unlink from thread** to remove it.
-
-On web and desktop, drag a pinned thread to change its position. On mobile, open the thread's menu
-and choose **Move up** or **Move down**. The order is stored by the server and appears on your
-other connected devices.
-
-If reordering is unavailable for one environment, update the T3 Code server running in that
-environment. Older servers can still pin and unpin threads, but do not understand synced ordering;
-their pinned threads keep the default newest-first order below the ones you have arranged.
-
-## Panel motion
-
-The main sidebar, right panel, and terminal drawer open and close immediately by default. Under
-**Settings → Appearance → Motion**, move the **Panel animations** slider above 0 ms to add motion.
-The duration can be set up to 400 ms. Clicking the preview replays all three panel transitions; at
-0 ms, it snaps between the same open and closed states.
-
-## Environment icons
-
-When you are connected to more than one environment, every thread that lives somewhere other than
-the machine you are on wears a small icon for that machine at the end of its row: a server, a cloud
-VM, a desktop, a laptop, a Mac mini, or a Mac Studio. In the hosted web app and the mobile app,
-where every environment is remote, each row wears its machine so you can tell them apart at a
-glance. The same icon appears wherever an environment is named: the thread tooltip, the command
-palette, the "Run on" picker, the pull request server filter, the provider settings device tabs,
-and the environment lists under **Settings → Connections**. On mobile it appears in the thread
-lists, the archive, the new-task environment picker, and the Environments and storage settings.
-
-Servers pick the icon themselves from the hardware they run on. A Mac reports its model, a Linux
-machine reports its chassis type and whether it is a virtual machine, and anything without a usable
-signal shows a generic server. To override it, open **Settings → Connections** and choose an icon
-for that environment; **Automatic** goes back to what the server detected. The choice is stored on
-that server, so every device that connects to it sees the same icon.
-
-## Environment artwork
-
-Dev and Nightly environments can identify themselves with artwork at the top of the sidebar and in
-the send button. Choose **Artwork**, **Version pill**, or **None** in Settings under environment
-identification. Artwork is recolored to match each built-in theme. Custom themes use the **Version
-pill** fallback because their colors are not controlled by T3 Code.
-
-To generate a fresh title from the conversation, open a thread's context menu and choose
-**Regenerate title**. While T3 Code is generating it, the action reads **Regenerating…** and cannot
-be selected again. The option is hidden when the connected environment needs a server update.
+# Working with threads
+
+Use a new thread for a separate task. Choose **New worktree** when its code changes
+need a separate branch and working directory.
+
+## Start a thread
+
+On web and desktop, a new thread keeps the current project and carries your model
+and mode selections, unless the destination project has its own model default.
+Its branch and workspace mode come from your configured defaults. To continue in
+an existing worktree, use **New thread in this worktree** from the branch toolbar.
+
+When you change a new thread's project, T3 Code stays in the current environment
+if that project exists there. Otherwise it selects an environment that has it.
+
+### Start in the background
+
+In a desktop browser or the desktop app, press `Cmd+Enter` on macOS or `Ctrl+Enter`
+on Windows and Linux to start a new thread and immediately open another draft. The
+next draft keeps the workspace mode and base branch you selected. With **New
+worktree**, each background submission creates its own worktree.
+
+## Pin and reorder threads
+
+Pin a thread from its menu to keep it above your active work. Drag pinned threads
+to reorder them on web and desktop, or use **Move up** and **Move down** on mobile.
+The order syncs across devices.
+
+Pinning does not prevent automatic settlement. Settling a thread removes its pin.
+
+## Settle finished work
+
+Choose **Settle thread** from its menu to move finished work out of the active list
+without deleting the conversation. **Un-settle thread** restores it to active work
+and prevents automatic settlement until new activity resumes the usual rules.
+
+By default, environments settle inactive threads after three days and settle
+threads whose pull request merged. A closed pull request can also settle an idle
+thread. Work in progress, pending questions or approvals, and live background work
+prevent automatic settlement. An open pull request does not prevent inactivity
+settlement, but an old closed or merged pull request does not settle work you
+resumed after it closed.
+
+Change these rules in **Settings → General**. They continue to run when your apps
+are closed. Changes apply to connected environments that support shared settings;
+offline environments and older servers keep their previous values. If connected
+environments disagree, **Apply to all** copies your current settings to those named
+in the warning. Changing a rule does not reopen already settled threads.
+
+## Link a pull request
+
+On web and desktop, right-click a pull request link in a thread and choose
+**Link to thread**. Use **Unlink from thread** on the same link to remove it.
+The linked pull request participates in automatic settlement.
+
+## Find and reference work
+
+On web and desktop, open the command palette with `Cmd/Ctrl+K` to search threads
+across connected environments. Message search starts after two characters and
+includes your messages and final agent responses.
+
+Use **Settings → Keybindings** to find or customize shortcuts for searching files
+and copying a thread reference. A copied reference uses the thread's pull request
+link when available, otherwise its thread ID. See [keybindings](./keybindings.md)
+for custom configuration.
+
+## Inspect agent work
+
+On web and desktop, use **Agents** to follow work delegated to subagents.
+
+Expand a tool call in the conversation to see its full command and output.
+Summaries shorten shell wrappers and can still describe the latest call after it
+finishes; the call's own result shows its status.
diff --git a/docs/user/tool-activity.md b/docs/user/tool-activity.md
deleted file mode 100644
index 55477f5107dc..000000000000
--- a/docs/user/tool-activity.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Tool activity
-
-Open a tool-group summary in the conversation to see its individual calls. Each row has an icon;
-select a row to inspect its details. Select the group summary again to collapse it.
-
-Long groups scroll inside a bounded area without expanding the whole conversation. Faded edges
-indicate more calls above or below. Short groups use only the space they need.
-Collapsing and reopening a group preserves your reading position and any open call details.
-
-Recognized T3 tools use descriptive labels in both the running summary and individual rows.
-The latest live activity stays in the present tense while the turn continues, such as
-"Running vp" or "Clicking in the preview browser", even after that call has completed.
-Expanded rows follow the call's own state, such as "Clicked" after success.
-When a call has not reported a state yet, the label stays in the present tense.
-Failed, declined, and stopped calls say what happened without implying success.
-Failed calls keep their tool icon with a muted red tint, so a failed command still
-looks like a command. App logos and other multicolor icons keep their artwork and
-show a small muted red failure mark beside the row. Expand the call to inspect its
-output. Runtime errors and warnings keep their stronger styling.
-Preview browser actions use a globe icon. Other T3 tools keep the T3 mark.
-Group summaries count browser actions separately, such as "Used browser 18 times" or
-"Ran 4 commands and used browser 15 times". Browser-only groups also use a globe icon.
-
-Command summaries show the program inside a shell wrapper, such as "Running vp" for
-`/bin/zsh -lc 'vp test run'`. Expanded rows keep the full command.
diff --git a/docs/user/updating.md b/docs/user/updating.md
index 18fc82ad202d..d72df7382f56 100644
--- a/docs/user/updating.md
+++ b/docs/user/updating.md
@@ -1,95 +1,65 @@
-# Keeping T3 Code in Sync
+# Updating T3 Code
 
-The T3 Code web or desktop app and the server it connects to work best when they use the same
-version. If they do not match, T3 Code shows a warning with the right update option for that server.
+The app you use and the server running your agents can be on different machines.
+When a server is behind your web or desktop app, an update notice appears in the
+conversation and **Settings → Connections**. Update the machine named in that
+notice.
 
-## Where to Find the Update
+## Before you update
 
-You may see the warning in either of these places:
+Server updates restart the connection and can interrupt active agents and
+terminal commands. Saved threads, settings, and project files remain.
 
-- above the message box in the current conversation
-- **Settings** → **Connections**, beside the affected connection
+**Settings → General → Continue threads after restarts** is off by default.
+Enable it to resume supported active threads after an update, crash, or machine
+restart. Changes are saved to connected environments that support this setting;
+update older servers first. If a supported environment was offline or has a
+different value, use **Apply to all** in Settings after it connects.
+T3 Code must start again on that machine;
+the setting does not enable automatic startup. Terminal commands may still be
+interrupted, and threads without saved provider resume state need a new message.
+If you previously enabled continuation for updates, enable this setting once
+to allow recovery without a connected client.
 
-Dismissing the conversation warning only hides that reminder for those two versions. It does not
-update the server, and the version difference remains visible in Connections.
+## Update a connected server
 
-## Before You Update
+The offered action depends on how the server runs:
 
-Updating restarts the server, so the connection will disappear briefly. **Settings** → **General**
-has a **Continue threads after server updates** preference. It is off by default. When enabled, the
-update buttons automatically resume supported provider threads after the replacement server is
-ready. Providers with native promptless continuation use it; other providers receive a short
-instruction to continue where they left off. Terminal commands and other running work may still be
-interrupted during the update.
+| Action                     | What to do                                                                                                                                                                                      |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Update server**          | Keep the client open while it installs and reconnects. Supported background services update remotely. For a desktop-hosted server, this also closes and relaunches the desktop app on the host. |
+| **Update the desktop app** | Update the desktop app on the machine running the server, then reopen it if needed.                                                                                                             |
+| **Copy update command**    | Stop the command-line server on its host and relaunch with the copied command, keeping your usual startup options.                                                                              |
 
-The update does not remove saved threads, settings, or project files.
-
-## Choose the Action You See
-
-| Action                     | What to do                                                                                                                                                                                                                                                                                                                                                                    |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Update server**          | Available for the T3 Code Linux background service and for servers run by a current T3 Code desktop app. Select the button and leave T3 Code open while it downloads, installs, restarts, and reconnects. For desktop-app servers this closes and relaunches the desktop app on that machine. If installation fails, the desktop app stays open and reconnects to its server. |
-| **Update the desktop app** | Shown for desktop apps that predate remote updates. Open the T3 Code desktop app on the machine that runs the server and install the app update there. Reopen it if needed.                                                                                                                                                                                                   |
-| **Copy update command**    | Copy the command, open a terminal on the server machine, stop the current T3 Code server, and relaunch it with the copied command and any startup options you normally use.                                                                                                                                                                                                   |
-
-The available action depends on how that server was started. T3 Code does not update connected
-servers silently in the background.
-
-An older background-service launcher may ask you to run the exact
-`npx t3@<version> service update` command on the server machine. That one local update installs the
-rollback support needed for later remote updates, including versions that change the database.
-
-After selecting **Update**, the notice becomes a live status line: **Downloading…** while the new
-version is fetched and verified, then **Restarting…** while the server restarts into it. The same
-status appears in the conversation and in Connections, so navigating between them does not lose the
-update. A failure remains visible with its error and an option to retry.
-
-**Copy update command** gives you `npx t3@<client-version>`, which relaunches the server directly
-at the matching version. Add whatever startup options you normally use.
-
-If the server instead runs as the T3 Code background service, update the service on the host and
-pin the same version:
+For a background service, run the matching version's CLI on the host:
 
 ```sh
 npx t3@<client-version> service update
 ```
 
-`service update` installs the version of the CLI that invoked it, so `npx t3@latest service update`
-only resolves the skew when your client happens to be on the latest release. The exact version from
-the warning always works.
-
-See [Running T3 Code in the Background](./background-service.md) for install, status, and removal
-commands.
-
-## Nightly desktop release notes
+Replace `<client-version>` with the version shown in the notice. Using
+`@latest` only resolves the mismatch if your client is on that release. An older
+service launcher may require this local update before it supports remote updates
+and rollback.
 
-The desktop app shows a compact release-notes preview when a nightly update is available. Changes
-appear newest first within each release. Each release links to its exact page on GitHub, even when
-all changes fit in the preview.
+For a foreground server, the copied command is `npx t3@<client-version>`. Add
+`serve` if you normally run without a browser, and preserve options such as
+`--host` or `--tailscale-serve`. See
+[background services](./background-service.md) for service management.
 
-The preview shows up to eight changes from each of six releases. When it leaves out changes or older
-releases, it shows the exact number and links to the rest. Contributor credits do not count as
-changes.
+## If an update fails
 
-## After the Update
-
-Keep the web or desktop app open while the server restarts. The update completes only after the
-service launcher reports that exact update committed and the replacement server is ready to accept
-commands. A rollback is reported immediately instead of waiting for a generic reconnect timeout.
-
-If a step fails:
+Keep the client open until it reconnects or reports a failure. A failed service
+update can roll back to the previous version. If the update still fails:
 
 1. Retry the offered action once.
-2. Make sure you updated the machine named in the warning, not only the device you are using.
-3. For a command-line server, relaunch it with `npx t3@<client-version>`, replacing
-   `<client-version>` with the client version shown in the warning.
-
-## The Mobile App
+2. Check that you updated the server's machine, not only the device you are using.
+3. For a command-line server, stop it and relaunch the exact version shown in the notice.
 
-The mobile app keeps itself current on its own. When it finds a new version, it downloads it in the
-background and installs it automatically the next time you leave the app. Unsent drafts and queued
-messages are saved before the restart. Only if the app stays open long enough that the update never
-gets that chance does it ask whether to install right away; choosing **Later** is safe and keeps the
-automatic install armed.
+## Mobile updates
 
-For remote connection setup and access troubleshooting, see [Remote Access](./remote-access.md).
+Install App Store or Google Play releases as usual. The mobile app can also
+download updates in the background and apply them when you next leave the app.
+It saves drafts and queued messages before restarting. If you keep the app open
+for a long time, it may ask to install immediately; choosing **Later** leaves the
+update queued for the next suitable moment.
diff --git a/docs/user/usage.md b/docs/user/usage.md
index 558f909a230f..3c29dec8d44d 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -1,36 +1,60 @@
-# Review usage
-
-The Usage page combines Codex, Claude Code, and Grok Build activity from your connected
-environments. It reads the providers' local session history and shows API-equivalent token cost,
-processed tokens, cache savings, provider shares, and model breakdowns. Subscription billing is
-separate from the raw token cost shown here.
-
-Grok Build totals come from persisted session updates. Interactive turns that never wrote a
-completed-turn record will not appear.
-
-The **Limits** view shows how much of each subscription window you have used on Codex and Claude
-Code, per connected environment: the session and weekly windows, plus a per-model weekly window
-such as Fable when your plan has one. Each window is a bar from the moment it opened to its reset,
-filled by the share of quota spent; a thin line marks how far into the window you are, which is
-also where even spending would have put the fill, and the icon beside the label says whether you
-are ahead of, on, or under that pace. Hover a bar for the exact reset time. Limits refresh on the
-provider health-check interval and update live while a turn runs. **Refresh limits** checks every
-connected environment; a failed refresh names the affected environment. API-key accounts have no
-subscription windows and say so; that includes a Claude Code that reaches Anthropic through a proxy
-via `ANTHROPIC_AUTH_TOKEN`, since the CLI then treats itself as an API-key client.
-
-If you pool accounts behind a CLIProxyAPI hub, open **Settings → Providers → Usage providers**
-and choose **Add hub**. Select the device that should connect to the hub; its accounts appear on
-the Limits view. Remove hubs from the same settings section. Each limits row shows its provider
-and instance name, or a small _CLI Proxy_ label for
-hub accounts. When a connected provider reports limits for the same provider and email, its row
-replaces the hub copy, keeping details such as banked reset credits. The hub copy remains visible
-if the connected provider cannot report limits. Enter the hub's URL and management key; the key
-is stored on the server and never sent back to a client. Emails are blurred until clicked, as in
-provider settings.
-
-Use **Past 24h** for an hourly chart covering the exact rolling 24-hour period. The **7 days**,
-**30 days**, and **90 days** ranges use daily resolution. Cost and token toggles update both the
-headline and chart. Refreshing rescans every connected environment and refetches model pricing on
-each of them, so a newly released model that showed $0.00 gets a price without waiting for the daily
-pricing update.
+# Usage and limits
+
+## Understand your usage
+
+**Usage** combines Codex, Claude Code, and Grok Build session history from your connected
+environments. It shows token use, cache savings, model breakdowns, and estimated API-equivalent
+cost. These estimates are not your subscription bill.
+
+Totals depend on the history available on each server. Grok turns without a saved completed-turn
+record are missing from the totals.
+
+On web and desktop, use the environment dropdown to filter costs, tokens, and limits. All
+environments are selected by default. The dropdown shows which environments are still scanning;
+results appear as each one responds.
+
+If recent work is missing or a new model shows no cost, refresh to rescan session history and
+update model pricing.
+
+## Set custom model prices
+
+On web or desktop, open the environment dropdown on **Usage**, then choose **Model prices** to add,
+edit, or reset a model's estimated price. **Apply to** starts with your current Usage filter;
+choose all environments or select individual destinations. Enter the exact model ID and USD
+rates per million input and output tokens. You can enter any model ID, including models
+without public pricing.
+
+Cache read and cache write rates are optional and use the input rate when blank. Enter `0` for
+tokens that are free. Saved prices replace automatic pricing for all of that environment's
+history and are shared with clients connected to it. When environments have different prices,
+cells show **Mixed**. Edit rates directly in the table, then choose **Save changes** to apply all
+edited rows. Untouched cells keep each environment's rate. Select one environment to inspect its
+prices. **Reset to automatic** marks a model's override for removal when you save; you can undo
+it before saving.
+
+Each destination reports whether the change saved. Offline or unavailable environments are
+marked **Not saved**. Reconnect them and choose **Retry failed saves** to finish the same change
+without writing again to environments that already saved. Changes are not queued after you close
+the dialog.
+
+## Track subscription limits
+
+**Usage → Limits** shows quota use and reset times for Codex and Claude subscriptions. It also
+compares quota consumed with time elapsed in each window, so you can judge your pace before the
+next reset.
+
+If a window looks stale, refresh Limits to re-check providers and hubs on connected environments.
+On web and desktop, the environment filter also applies to Limits and refresh. Failed refreshes
+name the affected environment; other environments still refresh.
+
+API-key accounts may not report subscription limits. This also applies to Claude connections
+using a proxy through `ANTHROPIC_AUTH_TOKEN`.
+
+## Connect a CLIProxyAPI hub
+
+To see pooled accounts, open **Settings → Providers → Usage providers → Add hub**. Choose the
+environment that will connect to the hub and enter its URL and management key.
+
+The accounts appear under **Usage → Limits**. This connection supplies usage information; configure
+the provider separately to send agent requests through the hub. Remove the hub from the same
+settings section when you no longer need it.
diff --git a/docs/user/welcome-wizard.md b/docs/user/welcome-wizard.md
new file mode 100644
index 000000000000..9a2aa116670d
--- /dev/null
+++ b/docs/user/welcome-wizard.md
@@ -0,0 +1,62 @@
+# Welcome wizard
+
+T3 Code shows a setup flow when you open a new installation or connect to the
+hosted app for the first time. Existing workspaces skip this flow.
+
+## Choose a connection
+
+- **This computer** runs agents on the computer that hosts T3 Code. It does not
+  require an account.
+- **T3 Connect** connects computers that are signed in to your account. Run
+  `npx t3 connect` on each computer you want to add, then start T3 Code or run
+  `npx t3 serve` so the computer stays available.
+- **Pair a server** connects directly to a server on your network or tailnet.
+  Start the server with `npx t3 serve`, then run `npx t3 pair --tailscale` and
+  paste the pairing link. You can also run `npx t3 serve --host <address>` and
+  use `npx t3 pair` when the server is already reachable on your network.
+
+If T3 Code cannot confirm the workspace during startup, the setup flow shows
+**Still connecting** instead of opening the app. Select **Reload** to try again.
+
+If T3 Code cannot read your saved settings, it shows **Could not read settings**.
+Select **Retry** after storage becomes available. Setup does not replace
+unreadable settings with defaults.
+
+## Check your agents
+
+T3 Code checks the selected computer for Claude Code and Codex. If an agent is
+not installed or signed in, select its action to open a terminal with the
+correct command ready to run. Other providers can be enabled in Settings.
+
+The setup terminal uses the home directory and environment configured for the
+selected provider instance. Sensitive values remain redacted in Settings and
+terminal metadata while the terminal process can use them.
+
+## Import your projects
+
+T3 Code finds directories that Claude Code or Codex has used. The default
+selection includes projects active within the last 30 days. Select **Choose**
+to include older projects or change the selection.
+
+A large or malformed history can reach the scan limit. T3 Code keeps the
+projects it found and warns when projects or conversations may be missing.
+
+Imported projects include Codex and Claude conversations active within the last
+30 days. You can continue those conversations in T3 Code.
+
+Conversation import is best effort. T3 Code keeps the first user prompt and the
+newest remaining visible user and assistant messages, with 200 messages total.
+It omits tool activity and attachments. For Codex, it omits generated setup
+context only when a canonical user event and a valid shared turn ID identify the
+same user turn. Ambiguous legacy or response-only context stays in the imported
+conversation so T3 Code does not remove user text. It reads one conversation at
+a time and skips files larger than 16 MiB. It ignores malformed records and skips
+unreadable or unparseable conversations.
+
+Each import attempt reads up to 100 conversation files and 64 MiB per project,
+with up to 100,000 input records. Run import again to continue a large batch.
+Completed conversations are not imported again. You can continue without the
+remaining history.
+
+You can skip agent setup and project import. Select **Back** to return to a
+previous step.
diff --git a/infra/relay/README.md b/infra/relay/README.md
index 0085c9c5b6b7..37b1a631970d 100644
--- a/infra/relay/README.md
+++ b/infra/relay/README.md
@@ -9,7 +9,7 @@ optional mobile notifications and Live Activities.
 
 The relay is intentionally not in the hot path for normal T3 Code traffic. After a client connects,
 regular API and WebSocket traffic goes directly between that client and the selected environment.
-See the [T3 Connect architecture overview](../../docs/internals/t3-code-connect-auth-flow.html) for the larger system
+See the [T3 Connect architecture note](../../docs/internals/t3-connect.md) for the larger system
 design.
 
 ## Responsibilities
@@ -159,8 +159,6 @@ and hosted web builds.
 
 See:
 
-- [T3 Connect Clerk Setup](../../docs/internals/t3-connect.md) for Clerk keys, JWT templates, and sign-up restrictions
-  setup.
+- [T3 Connect setup](../../docs/operations/connect-setup.md) for Clerk keys, JWT templates, and sign-up restrictions.
 - [Relay Observability](../../docs/operations/relay-observability.md) for deployment tracing and diagnostics.
-- [T3 Connect Architecture Overview](../../docs/internals/t3-code-connect-auth-flow.html) for the full link,
-  connect, endpoint, and notification flows.
+- [T3 Connect architecture](../../docs/internals/t3-connect.md) for environment linking and trust boundaries.
diff --git a/infra/relay/src/agentActivity/AgentActivityPublisher.test.ts b/infra/relay/src/agentActivity/AgentActivityPublisher.test.ts
index 4215f8346544..a70a85a8e6ed 100644
--- a/infra/relay/src/agentActivity/AgentActivityPublisher.test.ts
+++ b/infra/relay/src/agentActivity/AgentActivityPublisher.test.ts
@@ -517,7 +517,7 @@ describe("AgentActivityPublisher", () => {
   });
 
   it.effect(
-    "does not build Live Activity aggregates for links with Live Activities disabled",
+    "delivers notifications without querying activity rows when Live Activities are disabled",
     () => {
       const notificationState: RelayAgentActivityState = {
         ...state,
@@ -549,13 +549,7 @@ describe("AgentActivityPublisher", () => {
                     AgentActivityRows.AgentActivityRows,
                     makeAgentActivityRows({
                       listForUser: () =>
-                        Effect.succeed([
-                          {
-                            ...state,
-                            environmentId: "other-env" as RelayAgentActivityState["environmentId"],
-                            threadId: "other-thread" as RelayAgentActivityState["threadId"],
-                          },
-                        ]),
+                        Effect.die("Notification-only delivery must not read rows"),
                     }),
                   ),
                   Layer.succeed(
diff --git a/infra/relay/src/agentActivity/AgentActivityPublisher.ts b/infra/relay/src/agentActivity/AgentActivityPublisher.ts
index 9b3bcf2298dc..05ad4fd87b14 100644
--- a/infra/relay/src/agentActivity/AgentActivityPublisher.ts
+++ b/infra/relay/src/agentActivity/AgentActivityPublisher.ts
@@ -58,7 +58,9 @@ export const make = Effect.gen(function* () {
     readonly state: RelayAgentActivityState | null;
     readonly nowMs: number;
   }) {
-    const activeStates = yield* rows.listForUser({ userId: input.deliveryUser.userId });
+    const activeStates = input.deliveryUser.liveActivitiesEnabled
+      ? yield* rows.listForUser({ userId: input.deliveryUser.userId })
+      : [];
     const liveActivityAggregate = input.deliveryUser.liveActivitiesEnabled
       ? makeAggregateState({
           activeStates,
diff --git a/infra/relay/src/agentActivity/AgentActivityRows.test.ts b/infra/relay/src/agentActivity/AgentActivityRows.test.ts
index 65b0c2a0a90d..cd57f515f728 100644
--- a/infra/relay/src/agentActivity/AgentActivityRows.test.ts
+++ b/infra/relay/src/agentActivity/AgentActivityRows.test.ts
@@ -19,6 +19,42 @@ const state: RelayAgentActivityState = {
 };
 
 describe("AgentActivityRows", () => {
+  it.effect("validates database JSON objects and ignores invalid activity rows", () => {
+    const queryRows = [
+      { stateJson: null },
+      { stateJson: JSON.stringify(state) },
+      { stateJson: { ...state, phase: "invalid" } },
+      { stateJson: { ...state, unrelated: "ignored" } },
+    ];
+    const db = {
+      select: () => ({
+        from: () => ({
+          innerJoin: () => ({
+            where: () => ({
+              orderBy: () => Effect.succeed(queryRows),
+            }),
+          }),
+        }),
+      }),
+    } as unknown as RelayDb.RelayDb["Service"];
+
+    return Effect.gen(function* () {
+      const rows = yield* AgentActivityRows.AgentActivityRows;
+      expect(yield* rows.listForUser({ userId: "user-2" })).toEqual([state]);
+      expect(
+        yield* rows.getForUserThread({
+          userId: "user-2",
+          environmentId: "env-1",
+          threadId: "thread-1",
+        }),
+      ).toEqual(state);
+    }).pipe(
+      Effect.provide(
+        AgentActivityRows.layer.pipe(Layer.provide(Layer.succeed(RelayDb.RelayDb, db))),
+      ),
+    );
+  });
+
   it.effect("preserves activity context on persistence failures", () => {
     const cause = new Error("database unavailable");
     const failingDb = {
diff --git a/infra/relay/src/agentActivity/AgentActivityRows.ts b/infra/relay/src/agentActivity/AgentActivityRows.ts
index 54ba1df50600..032a61a383ef 100644
--- a/infra/relay/src/agentActivity/AgentActivityRows.ts
+++ b/infra/relay/src/agentActivity/AgentActivityRows.ts
@@ -92,15 +92,12 @@ export class AgentActivityRows extends Context.Service<
 >()("t3code-relay/agentActivity/AgentActivityRows") {}
 
 const decodeJsonString = Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown));
-const encodeJsonValue = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown));
 
 const encodeRelayAgentActivityStateJson = Schema.encodeEffect(
   Schema.fromJsonString(RelayAgentActivityStateSchema),
 );
 
-const decodeRelayAgentActivityStateJson = Schema.decodeUnknownOption(
-  Schema.fromJsonString(RelayAgentActivityStateSchema),
-);
+const decodeRelayAgentActivityState = Schema.decodeUnknownOption(RelayAgentActivityStateSchema);
 
 export const make = Effect.gen(function* () {
   const db = yield* RelayDb.RelayDb;
@@ -229,13 +226,8 @@ export const make = Effect.gen(function* () {
         )
         .orderBy(desc(relayAgentActivityRows.updatedAt))
         .pipe(
-          Effect.flatMap((rows) =>
-            Effect.forEach(rows, (row) => encodeJsonValue(row.stateJson), {
-              concurrency: "unbounded",
-            }),
-          ),
           Effect.map((rows) =>
-            rows.flatMap((row) => Option.toArray(decodeRelayAgentActivityStateJson(row))),
+            rows.flatMap((row) => Option.toArray(decodeRelayAgentActivityState(row.stateJson))),
           ),
           Effect.mapError(
             (cause) =>
@@ -271,14 +263,9 @@ export const make = Effect.gen(function* () {
         )
         .orderBy(desc(relayAgentActivityRows.updatedAt))
         .pipe(
-          Effect.flatMap((rows) =>
-            Effect.forEach(rows, (row) => encodeJsonValue(row.stateJson), {
-              concurrency: "unbounded",
-            }),
-          ),
           Effect.map((rows) => {
             for (const row of rows) {
-              const decoded = decodeRelayAgentActivityStateJson(row);
+              const decoded = decodeRelayAgentActivityState(row.stateJson);
               if (Option.isSome(decoded)) {
                 return decoded.value;
               }
diff --git a/infra/relay/src/agentActivity/ApnsClient.test.ts b/infra/relay/src/agentActivity/ApnsClient.test.ts
index 9f9877533515..03010ce48ce5 100644
--- a/infra/relay/src/agentActivity/ApnsClient.test.ts
+++ b/infra/relay/src/agentActivity/ApnsClient.test.ts
@@ -4,10 +4,13 @@ import { EnvironmentId, ThreadId } from "@t3tools/contracts";
 import type { RelayAgentActivityAggregateState } from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
 import * as DateTime from "effect/DateTime";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
 import * as Redacted from "effect/Redacted";
 import * as Schema from "effect/Schema";
+import * as TestClock from "effect/testing/TestClock";
 import * as HttpClient from "effect/unstable/http/HttpClient";
 import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
@@ -361,4 +364,80 @@ describe("ApnsClient", () => {
       ApnsProviderTokens.__resetApnsProviderTokenCacheForTest();
     }).pipe(Effect.provide(layer));
   });
+
+  for (const requestKind of ["live-activity", "push-notification"] as const) {
+    for (const stage of ["send", "read-response"] as const) {
+      it.effect(`aborts a stalled ${requestKind} ${stage} after ten seconds`, () =>
+        Effect.gen(function* () {
+          const started = yield* Deferred.make<void>();
+          const signals: AbortSignal[] = [];
+          const stalledHttpClient = HttpClient.make((request, _url, signal) => {
+            signals.push(signal);
+            const stall = Deferred.succeed(started, undefined).pipe(Effect.andThen(Effect.never));
+            if (stage === "send") return stall;
+            const response = HttpClientResponse.fromWeb(request, new Response("", { status: 200 }));
+            Object.defineProperty(response, "text", { value: stall });
+            return Effect.succeed(response);
+          });
+          const layer = ApnsClient.layer.pipe(
+            Layer.provide(Layer.succeed(HttpClient.HttpClient, stalledHttpClient)),
+            Layer.provide(
+              Layer.succeed(ApnsProviderTokens.ApnsProviderTokens, {
+                getJwt: () => Effect.succeed("test-jwt"),
+              }),
+            ),
+          );
+          const apns = yield* ApnsClient.ApnsClient.pipe(Effect.provide(layer));
+          const credentials = {
+            teamId: "team-timeout",
+            keyId: "key-timeout",
+            privateKey: Redacted.make("unused-test-key"),
+            bundleId: "com.t3tools.test",
+            environment: "sandbox",
+          } satisfies ApnsCredentials;
+          const send =
+            requestKind === "live-activity"
+              ? apns.sendLiveActivityRequest({
+                  credentials,
+                  issuedAtUnixSeconds: 123,
+                  request: apns.makeLiveActivityRequest({
+                    event: "update",
+                    token: "long-push-token",
+                    state,
+                    nowEpochSeconds: 123,
+                    nowIso: DateTime.formatIso(now),
+                  }),
+                })
+              : apns.sendPushNotificationRequest({
+                  credentials,
+                  issuedAtUnixSeconds: 123,
+                  request: apns.makePushNotificationRequest({
+                    token: "long-push-token",
+                    notification: {
+                      title: "Thread",
+                      body: "Done",
+                      environmentId: "env",
+                      threadId: "thread",
+                      deepLink: "/",
+                    },
+                  }),
+                });
+          const fiber = yield* send.pipe(Effect.flip, Effect.forkChild);
+          yield* Deferred.await(started);
+          yield* TestClock.adjust("10 seconds");
+          expect(signals[0]?.aborted).toBe(true);
+          const error = yield* Fiber.join(fiber);
+          expect(error).toMatchObject({
+            _tag: "ApnsHttpRequestError",
+            requestKind,
+            event: requestKind === "live-activity" ? "update" : null,
+            stage,
+            status: stage === "read-response" ? 200 : null,
+            tokenSuffix: "sh-token",
+            cause: { _tag: "TimeoutError" },
+          });
+        }),
+      );
+    }
+  }
 });
diff --git a/infra/relay/src/agentActivity/ApnsClient.ts b/infra/relay/src/agentActivity/ApnsClient.ts
index c401eb6c2e4e..4276b7062555 100644
--- a/infra/relay/src/agentActivity/ApnsClient.ts
+++ b/infra/relay/src/agentActivity/ApnsClient.ts
@@ -15,6 +15,8 @@ import * as ApnsProviderTokens from "./ApnsProviderTokens.ts";
 export { ApnsJwtEncodingError, ApnsJwtSigningError } from "./apnsJwt.ts";
 
 const LIVE_ACTIVITY_NAME = "AgentActivity";
+// Bound sending and reading separately so neither stage can hold a batch open.
+const APNS_HTTP_STAGE_TIMEOUT = "10 seconds";
 // Updates only flow on domain events, so a healthy agent can be silent for
 // minutes (long tool calls, pending approvals). Two minutes made iOS dim
 // perfectly healthy activities; ten minutes still bounds how long a dead
@@ -246,6 +248,7 @@ export const make = Effect.gen(function* () {
       }),
       HttpClientRequest.bodyJson(input.request.payload),
       Effect.flatMap(httpClient.execute),
+      Effect.timeout(APNS_HTTP_STAGE_TIMEOUT),
       Effect.mapError(
         (cause) =>
           new ApnsHttpRequestError({
@@ -261,6 +264,7 @@ export const make = Effect.gen(function* () {
       ),
     );
     const responseText = yield* response.text.pipe(
+      Effect.timeout(APNS_HTTP_STAGE_TIMEOUT),
       Effect.mapError(
         (cause) =>
           new ApnsHttpRequestError({
@@ -306,6 +310,7 @@ export const make = Effect.gen(function* () {
         }),
         HttpClientRequest.bodyJson(input.request.payload),
         Effect.flatMap(httpClient.execute),
+        Effect.timeout(APNS_HTTP_STAGE_TIMEOUT),
         Effect.mapError(
           (cause) =>
             new ApnsHttpRequestError({
@@ -321,6 +326,7 @@ export const make = Effect.gen(function* () {
         ),
       );
       const responseText = yield* response.text.pipe(
+        Effect.timeout(APNS_HTTP_STAGE_TIMEOUT),
         Effect.mapError(
           (cause) =>
             new ApnsHttpRequestError({
diff --git a/infra/relay/src/agentActivity/ApnsDeliveries.test.ts b/infra/relay/src/agentActivity/ApnsDeliveries.test.ts
index 1c89b56da5c9..e34dcc55e37e 100644
--- a/infra/relay/src/agentActivity/ApnsDeliveries.test.ts
+++ b/infra/relay/src/agentActivity/ApnsDeliveries.test.ts
@@ -5,11 +5,15 @@ import type {
 import * as NodeCryptoLayer from "@effect/platform-node/NodeCrypto";
 import { describe, expect, it } from "@effect/vitest";
 import * as NodeCrypto from "node:crypto";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
 import * as Logger from "effect/Logger";
 import * as Redacted from "effect/Redacted";
 import * as References from "effect/References";
+import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
 import {
   FetchHttpClient,
   HttpClient,
@@ -975,6 +979,79 @@ describe("ApnsDeliveries", () => {
     );
   });
 
+  it.effect("continues a signed delivery batch after an APNs timeout", () =>
+    Effect.gen(function* () {
+      const attempts: Array<DeliveryAttempts.DeliveryAttemptInput> = [];
+      const markedDeliveries: Array<
+        Parameters<LiveActivities.LiveActivities["Service"]["markDelivery"]>[0]
+      > = [];
+      const secondTarget = {
+        ...target,
+        device_id: "device-2",
+        activity_push_token: "second-token",
+      };
+      const jobs = [target, secondTarget].map((device) =>
+        signApnsDeliveryJob({
+          secret: signingConfig.apnsDeliveryJobSigningSecret,
+          payload: makeApnsDeliveryJobPayload({
+            kind: "live_activity_update",
+            userId: device.user_id,
+            deviceId: device.device_id,
+            token: device.activity_push_token!,
+            aggregate,
+            createdAt: "1970-01-01T00:00:00.000Z",
+            expiresAt: "1970-01-01T00:10:00.000Z",
+            jobId: `job-timeout-${device.device_id}`,
+          }),
+        }),
+      );
+      const started = yield* Deferred.make<void>();
+      const results: Array<{ deviceId: string; ok: boolean }> = [];
+      const layer = makeLayer({
+        attempts,
+        markedDeliveries,
+        currentTargets: [target, secondTarget],
+        config: signingConfig,
+        execute: (request) =>
+          request.url.endsWith("/activity-token")
+            ? Deferred.succeed(started, undefined).pipe(Effect.andThen(Effect.never))
+            : Effect.succeed(
+                HttpClientResponse.fromWeb(request, new Response("", { status: 200 })),
+              ),
+      });
+      const batch = yield* Effect.gen(function* () {
+        const deliveries = yield* ApnsDeliveries.ApnsDeliveries;
+        yield* Stream.fromIterable(jobs).pipe(
+          Stream.runForEach((job) =>
+            deliveries.processSignedJob(job).pipe(
+              Effect.tap((result) =>
+                Effect.sync(() => {
+                  results.push(result);
+                }),
+              ),
+            ),
+          ),
+        );
+      }).pipe(Effect.provide(layer), Effect.forkChild);
+
+      yield* Deferred.await(started);
+      yield* TestClock.adjust("10 seconds");
+      yield* Fiber.join(batch);
+      expect(results).toMatchObject([
+        { deviceId: "device-1", ok: false },
+        { deviceId: "device-2", ok: true },
+      ]);
+      expect(attempts).toMatchObject([
+        {
+          sourceJobId: "job-timeout-device-1",
+          apnsReason: expect.stringContaining("request failed"),
+        },
+        { sourceJobId: "job-timeout-device-2", apnsStatus: 200 },
+      ]);
+      expect(markedDeliveries).toMatchObject([{ deviceId: "device-2" }]);
+    }),
+  );
+
   it.effect("processes signed push notification jobs through APNs and records attempts", () => {
     const attempts: Array<DeliveryAttempts.DeliveryAttemptInput> = [];
     const payload = makeApnsDeliveryJobPayload({
diff --git a/infra/relay/src/deploymentConfig.test.ts b/infra/relay/src/deploymentConfig.test.ts
index 44c7627a4daf..f090c70ee22b 100644
--- a/infra/relay/src/deploymentConfig.test.ts
+++ b/infra/relay/src/deploymentConfig.test.ts
@@ -11,17 +11,10 @@ import {
   RelayPublicDomainLabelTooLongError,
   relayPublicDomainForStage,
   relayResourceNameForStage,
-  relayStageSlug,
 } from "./deploymentConfig.ts";
 
 const isRelayPublicDomainLabelTooLongError = Schema.is(RelayPublicDomainLabelTooLongError);
 
-describe("relayStageSlug", () => {
-  it("matches Alchemy physical-name sanitization for default developer stages", () => {
-    expect(relayStageSlug("dev_julius")).toBe("dev-julius");
-  });
-});
-
 describe("relayPublicDomainForStage", () => {
   it("uses the canonical relay hostname for production", () => {
     expect(relayPublicDomainForStage("prod", ".example.com.")).toBe("relay.example.com");
diff --git a/infra/relay/src/deploymentConfig.ts b/infra/relay/src/deploymentConfig.ts
index fe9d37b29988..565e16422dd2 100644
--- a/infra/relay/src/deploymentConfig.ts
+++ b/infra/relay/src/deploymentConfig.ts
@@ -56,7 +56,7 @@ function appendDnsSafeSuffix(prefix: string, suffix: string): string {
  * Alchemy's physical-name helper sanitizes resource names after adding the
  * stage. Keep custom domains and runtime-created resources aligned with it.
  */
-export function relayStageSlug(stage: string): string {
+function relayStageSlug(stage: string): string {
   return stage
     .toLowerCase()
     .replaceAll(/[^a-z0-9-]/g, "-")
diff --git a/knip.jsonc b/knip.jsonc
new file mode 100644
index 000000000000..25706930133b
--- /dev/null
+++ b/knip.jsonc
@@ -0,0 +1,74 @@
+{
+  "$schema": "https://unpkg.com/knip@6/schema.json",
+  // These executables are supplied by the OS or installed separately from npm.
+  "ignoreBinaries": ["eas", "file", "mkfifo", "pkill", "pkg-config", "plutil", "sips"],
+  "workspaces": {
+    ".": {
+      // Keep vendored reference repositories outside the root project.
+      "project": ["*.{js,mjs,cjs,ts,mts,cts}", ".github/**/*.cjs"],
+      "entry": [".github/scripts/thread-transfer-report.cjs"],
+      "vite": { "entry": [".github/**/*.test.cjs"] },
+      "vitest": { "entry": [".github/**/*.test.cjs"] },
+    },
+    "apps/server": {
+      // Vite+ pack entries and the launcher used by installed background services.
+      "entry": [
+        "src/bin.ts!",
+        "src/service-launcher.ts!",
+        "scripts/cli.ts",
+        "src/provider/testFixtures/*.mjs",
+      ],
+      // Native msgpack acceleration and the Vite+ web build prerequisite.
+      "ignoreDependencies": ["msgpackr-extract", "@t3tools/web"],
+    },
+    "apps/desktop": {
+      // Electron loads these bundles by filename rather than importing them.
+      "entry": [
+        "src/main.ts!",
+        "src/preload.ts!",
+        "src/preview-pick-preload.ts!",
+        "src/preview-pip-preload.ts!",
+        "src/preview/Annotation.css!",
+      ],
+      // The injected runtime resolves Playwright by string; release tooling runs
+      // electron-builder from this workspace, outside its package scripts.
+      "ignoreDependencies": ["playwright-core", "electron-builder"],
+    },
+    "apps/web": {
+      // Worktree setup invokes this directly from t3.json.
+      "entry": ["scripts/warm-dep-cache.ts"],
+    },
+    "apps/mobile": {
+      // Expo loads local config plugins by string; Metro handles platform variants.
+      "entry": ["index.ts!", "plugins/*.cjs"],
+      // Fonts are configured as asset paths; Expo autolinks the native packages.
+      "ignoreDependencies": [
+        "@expo-google-fonts/dm-sans",
+        "@t3tools/mobile-review-diff-native",
+        "@t3tools/mobile-terminal-native",
+      ],
+    },
+    "apps/mobile/modules/t3-markdown-text": {
+      // React Native codegen discovers component specifications by filename.
+      "entry": ["src/*NativeComponent.ts!"],
+    },
+    "infra/relay": {
+      "entry": ["alchemy.run.ts!", "src/persistence/schema.ts!"],
+    },
+    "packages/*": {
+      // These workspace packages are private to this monorepo.
+      "includeEntryExports": true,
+    },
+    "packages/effect-acp": {
+      "includeEntryExports": true,
+      "entry": ["test/fixtures/*.ts"],
+      // Generated upstream protocol definitions are retained as a complete set.
+      "ignoreIssues": { "src/_generated/**": ["exports", "types"] },
+    },
+    "packages/effect-codex-app-server": {
+      "includeEntryExports": true,
+      "entry": ["test/fixtures/*.ts"],
+      "ignoreIssues": { "src/_generated/**": ["exports", "types"] },
+    },
+  },
+}
diff --git a/native/resource-monitor/src/main.rs b/native/resource-monitor/src/main.rs
index 0596aea977cd..78ba5a271cd3 100644
--- a/native/resource-monitor/src/main.rs
+++ b/native/resource-monitor/src/main.rs
@@ -346,7 +346,7 @@ impl Collector {
         self.system.refresh_processes_specifics(
             ProcessesToUpdate::All,
             true,
-            process_refresh_kind(),
+            process_discovery_refresh_kind(),
         );
         self.cpu_baseline_refreshed_at = Some(Instant::now());
     }
@@ -361,7 +361,7 @@ impl Collector {
         self.system.refresh_processes_specifics(
             ProcessesToUpdate::All,
             true,
-            process_refresh_kind(),
+            process_discovery_refresh_kind(),
         );
         self.cpu_baseline_refreshed_at = Some(Instant::now());
 
@@ -397,15 +397,57 @@ impl Collector {
         roots.insert(config.root_pid);
         let tracked = select_tracked_pids(&rows, &roots);
         let tracked_process_count = tracked.len();
+        let process_details = if cfg!(target_os = "linux") && !tracked.is_empty() {
+            let monitor_pid = Pid::from_u32(std::process::id());
+            let mut detail_pids = tracked
+                .iter()
+                .copied()
+                .map(Pid::from_u32)
+                .collect::<Vec<_>>();
+            if !tracked.contains(&monitor_pid.as_u32()) {
+                detail_pids.push(monitor_pid);
+            }
+            // Detail fields need no baseline. Drop command data and OS handles after each sample.
+            let mut details = System::new();
+            details.refresh_processes_specifics(
+                ProcessesToUpdate::Some(&detail_pids),
+                true,
+                process_refresh_kind().without_cpu(),
+            );
+            // This process cannot be replaced during collection. Its start time
+            // exposes any boot-epoch shift between the two System instances.
+            let start_time_offset = self.system.process(monitor_pid).and_then(|process| {
+                details.process(monitor_pid).map(|detail| {
+                    i128::from(detail.start_time()) - i128::from(process.start_time())
+                })
+            });
+            Some((details, start_time_offset))
+        } else {
+            None
+        };
+        let sample_details = process_details
+            .as_ref()
+            .map_or(&self.system, |(details, _)| details);
+        let start_time_offset = process_details
+            .as_ref()
+            .map_or(Some(0), |(_, offset)| *offset);
         let mut processes = tracked
             .into_iter()
             .filter_map(|pid| {
                 let process = self.system.process(Pid::from_u32(pid))?;
-                let disk_usage = process.disk_usage();
-                let command = if process.cmd().is_empty() {
+                let details = sample_details.process(Pid::from_u32(pid))?;
+                if !matches_process_start_time(
+                    process.start_time(),
+                    details.start_time(),
+                    start_time_offset?,
+                ) {
+                    return None;
+                }
+                let disk_usage = details.disk_usage();
+                let command = if details.cmd().is_empty() {
                     process.name().to_string_lossy().into_owned()
                 } else {
-                    process
+                    details
                         .cmd()
                         .iter()
                         .map(|part| part.to_string_lossy())
@@ -429,14 +471,15 @@ impl Collector {
                     ),
                     cpu_percent: process.cpu_usage(),
                     cpu_time_ms: process.accumulated_cpu_time(),
-                    resident_bytes: process.memory(),
-                    virtual_bytes: process.virtual_memory(),
+                    resident_bytes: details.memory(),
+                    virtual_bytes: details.virtual_memory(),
                     io_read_bytes: disk_usage.total_read_bytes,
                     io_write_bytes: disk_usage.total_written_bytes,
                     io_semantics: io_semantics(),
                 })
             })
             .collect::<Vec<_>>();
+        drop(process_details);
         processes.sort_by_key(|process| process.pid);
         self.sequence = self.sequence.saturating_add(1);
 
@@ -459,6 +502,15 @@ impl Collector {
     }
 }
 
+// Keep CPU baselines separate. Even a metadata refresh resets Linux process times.
+fn process_discovery_refresh_kind() -> ProcessRefreshKind {
+    if cfg!(target_os = "linux") {
+        ProcessRefreshKind::nothing().with_cpu().without_tasks()
+    } else {
+        process_refresh_kind()
+    }
+}
+
 fn process_refresh_kind() -> ProcessRefreshKind {
     ProcessRefreshKind::nothing()
         .with_memory()
@@ -472,6 +524,10 @@ fn inaccessible_process_count(selected: usize, materialized: usize) -> usize {
     selected.saturating_sub(materialized)
 }
 
+fn matches_process_start_time(discovered: u64, detail: u64, epoch_offset: i128) -> bool {
+    i128::from(detail) - epoch_offset == i128::from(discovered)
+}
+
 fn remaining_cpu_measurement_delay(
     baseline_refreshed_at: Option<Instant>,
     now: Instant,
@@ -889,6 +945,39 @@ mod tests {
         assert!(!matches_external_identity(10_000, Some(9_999)));
     }
 
+    #[test]
+    fn loads_details_when_an_existing_process_becomes_selected() {
+        let mut collector = Collector::new();
+        let mut config = CollectorConfig {
+            root_pid: u32::MAX,
+            sample_interval: None,
+            external_processes: HashMap::new(),
+        };
+        assert!(collector.sample(&config, None).processes.is_empty());
+
+        config.root_pid = std::process::id();
+        let snapshot = collector.sample(&config, None);
+        let process = snapshot
+            .processes
+            .iter()
+            .find(|process| process.pid == config.root_pid)
+            .expect("selected process");
+
+        assert!(!process.command.is_empty());
+        assert!(process.resident_bytes > 0);
+        assert!(process.cpu_percent.is_finite());
+    }
+
+    #[test]
+    fn accepts_clock_shifts_without_accepting_reused_process_starts() {
+        assert!(matches_process_start_time(10_000, 13_600, 3_600));
+        assert!(!matches_process_start_time(10_000, 13_601, 3_600));
+        assert!(matches_process_start_time(10_000, 6_400, -3_600));
+        assert!(!matches_process_start_time(10_000, 6_401, -3_600));
+        assert!(matches_process_start_time(10_000, 10_000, 0));
+        assert!(!matches_process_start_time(10_000, 10_001, 0));
+    }
+
     #[test]
     fn decodes_protocol_commands() {
         let configure = serde_json::from_str::<Command>(
diff --git a/package.json b/package.json
index 46913a435a8a..4fc0dafeb0e9 100644
--- a/package.json
+++ b/package.json
@@ -25,6 +25,9 @@
     "typecheck": "vp run -r --concurrency-limit 2 typecheck",
     "tc": "vp run -r --concurrency-limit 2 typecheck",
     "lint": "vp lint --report-unused-disable-directives",
+    "knip": "knip",
+    "knip:check": "knip --include files,dependencies --no-config-hints && knip --workspace packages/tailscale --workspace packages/effect-codex-app-server --exports --no-config-hints",
+    "knip:production": "knip --production",
     "lint:mobile": "node scripts/mobile-native-static-check.ts",
     "test": "vp run -r test",
     "test:resource-monitor": "cargo test --locked --manifest-path native/resource-monitor/Cargo.toml",
@@ -44,11 +47,10 @@
     "sync:repos": "node scripts/sync-reference-repos.ts"
   },
   "devDependencies": {
-    "@babel/plugin-transform-react-jsx": "7.28.6",
     "@effect/tsgo": "catalog:",
-    "@oxlint/plugins": "^1.63.0",
     "@types/node": "catalog:",
     "@typescript/native-preview": "catalog:",
+    "knip": "6.34.0",
     "vite-plus": "catalog:"
   },
   "engines": {
diff --git a/packages/client-runtime/src/authorization/index.ts b/packages/client-runtime/src/authorization/index.ts
index 6236b5922d82..d232aea0d30a 100644
--- a/packages/client-runtime/src/authorization/index.ts
+++ b/packages/client-runtime/src/authorization/index.ts
@@ -1,7 +1,7 @@
 export * from "./remote.ts";
 export {
   type AuthorizedRemoteEnvironment,
-  type RelayEnvironmentAuthorization,
+  type AuthorizedRemoteHttpEnvironment,
   RemoteEnvironmentAuthorization,
 } from "./service.ts";
 export * as TokenStore from "./tokenStore.ts";
diff --git a/packages/client-runtime/src/authorization/layer.test.ts b/packages/client-runtime/src/authorization/layer.test.ts
index 890a73d16964..5cd2d89d1ac2 100644
--- a/packages/client-runtime/src/authorization/layer.test.ts
+++ b/packages/client-runtime/src/authorization/layer.test.ts
@@ -1,8 +1,16 @@
 import { AuthStandardClientScopes, EnvironmentId } from "@t3tools/contracts";
+import {
+  RelayEnvironmentConnectScope,
+  type RelayEnvironmentConnectResponse,
+} from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
+import * as Clock from "effect/Clock";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
 import * as Ref from "effect/Ref";
 import * as TestClock from "effect/testing/TestClock";
 
@@ -31,10 +39,11 @@ const DESCRIPTOR = {
     repositoryIdentity: true,
   },
 };
-const BOOTSTRAP: RemoteEnvironmentAuthorization.RelayEnvironmentAuthorization = {
+const BOOTSTRAP: RelayEnvironmentConnectResponse = {
   environmentId: ENVIRONMENT_ID,
   endpoint: ENDPOINT,
   credential: "relay-bootstrap",
+  expiresAt: "2026-06-06T01:00:00.000Z",
 };
 
 function recordedFetch(responses: ReadonlyArray<Response>) {
@@ -76,9 +85,31 @@ const authInvalid = () =>
     { status: 401 },
   );
 
+const persistedToken = (
+  input: {
+    readonly environmentId?: EnvironmentId;
+    readonly accessToken?: string;
+    readonly expiresAtEpochMs?: number;
+    readonly dpopThumbprint?: string;
+  } = {},
+) =>
+  new TokenStore.RemoteDpopAccessToken({
+    environmentId: input.environmentId ?? ENVIRONMENT_ID,
+    accountId: "account-1",
+    label: DESCRIPTOR.label,
+    endpoint: ENDPOINT,
+    accessToken: input.accessToken ?? "cached-access-token",
+    expiresAtEpochMs: input.expiresAtEpochMs ?? Number.MAX_SAFE_INTEGER,
+    dpopThumbprint: input.dpopThumbprint ?? "thumbprint-1",
+  });
+
 const makeHarness = Effect.fn("TestRemoteAuthorization.makeHarness")(function* (input: {
   readonly initialToken?: TokenStore.RemoteDpopAccessToken;
   readonly responses: ReadonlyArray<Response>;
+  readonly bootstrap?: RelayEnvironmentConnectResponse;
+  readonly beforeBootstrap?: Effect.Effect<void, ManagedRelay.ManagedRelayClientError>;
+  readonly beforePut?: Effect.Effect<void>;
+  readonly clerkToken?: ClientCapabilities.CloudSession["Service"]["clerkToken"];
 }) {
   const tokens = yield* Ref.make(
     new Map(
@@ -88,6 +119,14 @@ const makeHarness = Effect.fn("TestRemoteAuthorization.makeHarness")(function* (
     ),
   );
   const bootstrapCalls = yield* Ref.make(0);
+  const relayInputs = yield* Ref.make<
+    ReadonlyArray<Parameters<ManagedRelay.ManagedRelayClient["Service"]["connectEnvironment"]>[0]>
+  >([]);
+  const session = yield* Ref.make<Option.Option<ClientCapabilities.CloudSessionIdentity>>(
+    Option.some({ accountId: "account-1" }),
+  );
+  const thumbprint = yield* Ref.make("thumbprint-1");
+  const tokenReads = yield* Queue.unbounded<EnvironmentId>();
   const proofInputs = yield* Ref.make<
     ReadonlyArray<{
       readonly method: string;
@@ -101,13 +140,18 @@ const makeHarness = Effect.fn("TestRemoteAuthorization.makeHarness")(function* (
     get: (environmentId) =>
       Ref.get(tokens).pipe(
         Effect.map((current) => Option.fromUndefinedOr(current.get(environmentId))),
+        Effect.tap(() => Queue.offer(tokenReads, environmentId)),
       ),
     put: (token) =>
-      Ref.update(tokens, (current) => {
-        const next = new Map(current);
-        next.set(token.environmentId, token);
-        return next;
-      }),
+      (input.beforePut ?? Effect.void).pipe(
+        Effect.andThen(
+          Ref.update(tokens, (current) => {
+            const next = new Map(current);
+            next.set(token.environmentId, token);
+            return next;
+          }),
+        ),
+      ),
     remove: (environmentId) =>
       Ref.update(tokens, (current) => {
         const next = new Map(current);
@@ -116,17 +160,47 @@ const makeHarness = Effect.fn("TestRemoteAuthorization.makeHarness")(function* (
       }),
   });
   const signer = ManagedRelay.ManagedRelayDpopSigner.of({
-    thumbprint: Effect.succeed("thumbprint-1"),
+    thumbprint: Ref.get(thumbprint),
     createProof: (proofInput) =>
       Ref.update(proofInputs, (current) => [...current, proofInput]).pipe(
         Effect.as(`proof:${proofInput.url}`),
       ),
   });
+  const unexpected = () => Effect.die("Unexpected relay request");
+  const relay = ManagedRelay.ManagedRelayClient.of({
+    relayUrl: "https://relay.example.test",
+    listEnvironments: unexpected,
+    listDevices: unexpected,
+    createEnvironmentLinkChallenge: unexpected,
+    linkEnvironment: unexpected,
+    unlinkEnvironment: unexpected,
+    getEnvironmentStatus: unexpected,
+    connectEnvironment: (request) =>
+      Effect.gen(function* () {
+        yield* Ref.update(bootstrapCalls, (count) => count + 1);
+        yield* Ref.update(relayInputs, (current) => [...current, request]);
+        yield* input.beforeBootstrap ?? Effect.void;
+        return input.bootstrap ?? BOOTSTRAP;
+      }),
+    registerDevice: unexpected,
+    unregisterDevice: unexpected,
+    registerLiveActivity: unexpected,
+    getAgentActivitySnapshot: unexpected,
+    resetTokenCache: Effect.void,
+  });
   const layer = RemoteEnvironmentAuthorization.layer.pipe(
     Layer.provide(
       Layer.mergeAll(
         remoteHttpClientLayer(fetch.fetchFn),
         Layer.succeed(ManagedRelay.ManagedRelayDpopSigner, signer),
+        Layer.succeed(ManagedRelay.ManagedRelayClient, relay),
+        Layer.succeed(ClientCapabilities.CloudSession, {
+          identity: Ref.get(session),
+          clerkToken: input.clerkToken ?? Effect.succeed("clerk-session"),
+        }),
+        Layer.succeed(ClientCapabilities.RelayDeviceIdentity, {
+          deviceId: Effect.succeed(Option.some("device-1")),
+        }),
         Layer.succeed(TokenStore.RemoteDpopAccessTokenStore, tokenStore),
         Layer.succeed(
           ClientCapabilities.ClientPresentation,
@@ -142,17 +216,16 @@ const makeHarness = Effect.fn("TestRemoteAuthorization.makeHarness")(function* (
       ),
     ),
   );
-  const obtainBootstrap = Ref.update(bootstrapCalls, (count) => count + 1).pipe(
-    Effect.as(BOOTSTRAP),
-  );
-
   return {
     layer,
     tokens,
     bootstrapCalls,
     proofInputs,
     fetch,
-    obtainBootstrap,
+    relayInputs,
+    session,
+    thumbprint,
+    tokenReads,
   };
 });
 
@@ -234,10 +307,11 @@ describe("RemoteEnvironmentAuthorization", () => {
     }),
   );
 
-  it.effect("reuses a valid persisted environment token without contacting the relay", () =>
+  it.effect("reuses a same-account persisted environment token without contacting the relay", () =>
     Effect.gen(function* () {
       const cached = new TokenStore.RemoteDpopAccessToken({
         environmentId: ENVIRONMENT_ID,
+        accountId: "account-1",
         label: DESCRIPTOR.label,
         endpoint: ENDPOINT,
         accessToken: "cached-access-token",
@@ -253,7 +327,6 @@ describe("RemoteEnvironmentAuthorization", () => {
         const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
         return yield* remote.authorizeDpop({
           expectedEnvironmentId: ENVIRONMENT_ID,
-          obtainBootstrap: harness.obtainBootstrap,
         });
       }).pipe(Effect.provide(harness.layer));
 
@@ -271,6 +344,7 @@ describe("RemoteEnvironmentAuthorization", () => {
     Effect.gen(function* () {
       const expired = new TokenStore.RemoteDpopAccessToken({
         environmentId: ENVIRONMENT_ID,
+        accountId: "account-1",
         label: DESCRIPTOR.label,
         endpoint: ENDPOINT,
         accessToken: "expired-access-token",
@@ -290,7 +364,6 @@ describe("RemoteEnvironmentAuthorization", () => {
         const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
         return yield* remote.authorizeDpop({
           expectedEnvironmentId: ENVIRONMENT_ID,
-          obtainBootstrap: harness.obtainBootstrap,
         });
       }).pipe(Effect.provide(harness.layer));
 
@@ -310,6 +383,7 @@ describe("RemoteEnvironmentAuthorization", () => {
     Effect.gen(function* () {
       const cached = new TokenStore.RemoteDpopAccessToken({
         environmentId: ENVIRONMENT_ID,
+        accountId: "account-1",
         label: DESCRIPTOR.label,
         endpoint: ENDPOINT,
         accessToken: "invalid-access-token",
@@ -330,7 +404,6 @@ describe("RemoteEnvironmentAuthorization", () => {
         const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
         return yield* remote.authorizeDpop({
           expectedEnvironmentId: ENVIRONMENT_ID,
-          obtainBootstrap: harness.obtainBootstrap,
         });
       }).pipe(Effect.provide(harness.layer));
 
@@ -355,7 +428,6 @@ describe("RemoteEnvironmentAuthorization", () => {
         const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
         return yield* remote.authorizeDpop({
           expectedEnvironmentId: ENVIRONMENT_ID,
-          obtainBootstrap: harness.obtainBootstrap,
         });
       }).pipe(Effect.provide(harness.layer), Effect.flip);
 
@@ -372,6 +444,7 @@ describe("RemoteEnvironmentAuthorization", () => {
     Effect.gen(function* () {
       const cached = new TokenStore.RemoteDpopAccessToken({
         environmentId: ENVIRONMENT_ID,
+        accountId: "account-1",
         label: DESCRIPTOR.label,
         endpoint: ENDPOINT,
         accessToken: "cached-access-token",
@@ -392,7 +465,6 @@ describe("RemoteEnvironmentAuthorization", () => {
         const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
         return yield* remote.authorizeDpop({
           expectedEnvironmentId: ENVIRONMENT_ID,
-          obtainBootstrap: harness.obtainBootstrap,
         });
       }).pipe(Effect.provide(harness.layer));
 
@@ -407,7 +479,7 @@ describe("RemoteEnvironmentAuthorization", () => {
     }),
   );
 
-  it.effect("does not persist a refreshed token until its websocket ticket succeeds", () =>
+  it.effect("removes a newly refreshed token when websocket ticket authorization fails", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({
         responses: [
@@ -421,7 +493,6 @@ describe("RemoteEnvironmentAuthorization", () => {
         const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
         return yield* remote.authorizeDpop({
           expectedEnvironmentId: ENVIRONMENT_ID,
-          obtainBootstrap: harness.obtainBootstrap,
         });
       }).pipe(Effect.provide(harness.layer), Effect.flip);
 
@@ -430,4 +501,437 @@ describe("RemoteEnvironmentAuthorization", () => {
       expect(harness.fetch.calls).toHaveLength(3);
     }),
   );
+
+  it.effect("uses the current cached HTTP token without a relay request or websocket ticket", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({ initialToken: persistedToken(), responses: [] });
+      const authorized = yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        return yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+      }).pipe(Effect.provide(harness.layer));
+
+      expect(authorized).toEqual({
+        environmentId: ENVIRONMENT_ID,
+        label: DESCRIPTOR.label,
+        httpBaseUrl: ENDPOINT.httpBaseUrl,
+        httpAuthorization: {
+          _tag: "Dpop",
+          accessToken: "cached-access-token",
+          expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
+        },
+      });
+      expect(harness.fetch.calls).toHaveLength(0);
+      expect(yield* Ref.get(harness.bootstrapCalls)).toBe(0);
+      expect(yield* Ref.get(harness.proofInputs)).toEqual([]);
+    }),
+  );
+
+  it.effect(
+    "renews HTTP credentials near expiry through the current cloud account and device",
+    () =>
+      Effect.gen(function* () {
+        const now = yield* Clock.currentTimeMillis;
+        const harness = yield* makeHarness({
+          initialToken: persistedToken({ expiresAtEpochMs: now + 61_000 }),
+          responses: [Response.json(DESCRIPTOR), accessToken("fresh-access-token")],
+        });
+        yield* Effect.gen(function* () {
+          const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+          const before = yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+          expect(before.httpAuthorization.accessToken).toBe("cached-access-token");
+          yield* TestClock.adjust("1 second");
+          const after = yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+          expect(after.httpAuthorization.accessToken).toBe("fresh-access-token");
+          expect(after.httpAuthorization.expiresAtEpochMs).toBe(now + 3_601_000);
+        }).pipe(Effect.provide(harness.layer));
+
+        expect(yield* Ref.get(harness.relayInputs)).toEqual([
+          {
+            environmentId: ENVIRONMENT_ID,
+            clerkToken: "clerk-session",
+            scopes: [RelayEnvironmentConnectScope],
+            deviceId: "device-1",
+          },
+        ]);
+        expect(harness.fetch.calls.map(([url]) => String(url))).toEqual([
+          `${ENDPOINT.httpBaseUrl}/.well-known/t3/environment`,
+          `${ENDPOINT.httpBaseUrl}/oauth/token`,
+        ]);
+        expect(yield* Ref.get(harness.proofInputs)).toEqual([
+          {
+            method: "POST",
+            url: `${ENDPOINT.httpBaseUrl}/oauth/token`,
+          },
+        ]);
+      }),
+  );
+
+  it.effect("does not evict a replacement token when a late request rejects the old one", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        initialToken: persistedToken(),
+        responses: [Response.json(DESCRIPTOR), accessToken("replacement-token")],
+      });
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const initial = yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+        const retry = {
+          expectedEnvironmentId: ENVIRONMENT_ID,
+          rejectedAccessToken: initial.httpAuthorization.accessToken,
+        };
+        const first = yield* remote.authorizeDpopHttp(retry);
+        const late = yield* remote.authorizeDpopHttp(retry);
+        expect(first.httpAuthorization.accessToken).toBe("replacement-token");
+        expect(late).toEqual(first);
+      }).pipe(Effect.provide(harness.layer));
+
+      expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+      expect(harness.fetch.calls).toHaveLength(2);
+      expect((yield* Ref.get(harness.tokens)).get(ENVIRONMENT_ID)?.accessToken).toBe(
+        "replacement-token",
+      );
+    }),
+  );
+
+  it.effect("shares one in-flight renewal between concurrent HTTP requests", () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const release = yield* Deferred.make<void>();
+      const harness = yield* makeHarness({
+        initialToken: persistedToken({ expiresAtEpochMs: 0 }),
+        beforeBootstrap: Deferred.succeed(started, undefined).pipe(
+          Effect.andThen(Deferred.await(release)),
+        ),
+        responses: [Response.json(DESCRIPTOR), accessToken("shared-token")],
+      });
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const requests = yield* Effect.all(
+          Array.from({ length: 6 }, () =>
+            remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID }),
+          ),
+          { concurrency: "unbounded" },
+        ).pipe(Effect.forkChild);
+        yield* Queue.takeN(harness.tokenReads, 6);
+        yield* Deferred.await(started);
+        expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+        yield* Deferred.succeed(release, undefined);
+        const results = yield* Fiber.join(requests);
+        expect(results.map((result) => result.httpAuthorization.accessToken)).toEqual(
+          Array(6).fill("shared-token"),
+        );
+      }).pipe(Effect.provide(harness.layer));
+
+      expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+      expect(harness.fetch.calls).toHaveLength(2);
+    }),
+  );
+
+  it.effect(
+    "shares a failed renewal and allows a later attempt instead of caching its failure",
+    () =>
+      Effect.gen(function* () {
+        const release = yield* Deferred.make<void, ManagedRelay.ManagedRelayClientError>();
+        const failure = new ManagedRelay.ManagedRelayRequestTimeoutError({
+          activity: "Relay environment connection",
+          timeoutMs: ManagedRelay.MANAGED_RELAY_REQUEST_TIMEOUT_MS,
+          traceId: null,
+        });
+        const harness = yield* makeHarness({
+          responses: [],
+          beforeBootstrap: Deferred.await(release),
+        });
+        yield* Effect.gen(function* () {
+          const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+          const requests = yield* Effect.all(
+            Array.from({ length: 6 }, () =>
+              remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID }).pipe(Effect.flip),
+            ),
+            { concurrency: "unbounded" },
+          ).pipe(Effect.forkChild);
+          yield* Queue.takeN(harness.tokenReads, 6);
+          yield* Deferred.fail(release, failure);
+          const failures = yield* Fiber.join(requests);
+          expect(failures).toEqual(
+            Array(6).fill(
+              expect.objectContaining({
+                _tag: "ConnectionTransientError",
+                reason: "timeout",
+              }),
+            ),
+          );
+          expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+          yield* remote
+            .authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID })
+            .pipe(Effect.flip);
+          expect(yield* Ref.get(harness.bootstrapCalls)).toBe(2);
+        }).pipe(Effect.provide(harness.layer));
+        expect(harness.fetch.calls).toHaveLength(0);
+      }),
+  );
+
+  it.effect("does not block another environment behind a pending renewal", () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const release = yield* Deferred.make<void>();
+      const otherEnvironmentId = EnvironmentId.make("environment-2");
+      const harness = yield* makeHarness({
+        initialToken: persistedToken({
+          environmentId: otherEnvironmentId,
+          accessToken: "other-token",
+        }),
+        beforeBootstrap: Deferred.succeed(started, undefined).pipe(
+          Effect.andThen(Deferred.await(release)),
+        ),
+        responses: [Response.json(DESCRIPTOR), accessToken("fresh-token")],
+      });
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const pending = yield* remote
+          .authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID })
+          .pipe(Effect.forkChild);
+        yield* Deferred.await(started);
+        const other = yield* remote.authorizeDpopHttp({
+          expectedEnvironmentId: otherEnvironmentId,
+        });
+        expect(other.httpAuthorization.accessToken).toBe("other-token");
+        yield* Deferred.succeed(release, undefined);
+        yield* Fiber.join(pending);
+      }).pipe(Effect.provide(harness.layer));
+    }),
+  );
+
+  it.effect("does not return or persist credentials after logout during renewal", () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const release = yield* Deferred.make<void>();
+      const harness = yield* makeHarness({
+        beforeBootstrap: Deferred.succeed(started, undefined).pipe(
+          Effect.andThen(Deferred.await(release)),
+        ),
+        responses: [],
+      });
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const pending = yield* remote
+          .authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID })
+          .pipe(Effect.flip, Effect.forkChild);
+        yield* Deferred.await(started);
+        yield* Ref.set(harness.session, Option.none());
+        yield* Deferred.succeed(release, undefined);
+        expect(yield* Fiber.join(pending)).toMatchObject({
+          _tag: "ConnectionBlockedError",
+          reason: "authentication",
+        });
+      }).pipe(Effect.provide(harness.layer));
+      expect((yield* Ref.get(harness.tokens)).size).toBe(0);
+      expect(harness.fetch.calls).toHaveLength(0);
+    }),
+  );
+
+  it.effect("removes an obsolete credential if logout overlaps the persistent write", () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const release = yield* Deferred.make<void>();
+      const harness = yield* makeHarness({
+        beforePut: Deferred.succeed(started, undefined).pipe(
+          Effect.andThen(Deferred.await(release)),
+        ),
+        responses: [Response.json(DESCRIPTOR), accessToken("obsolete-token")],
+      });
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const pending = yield* remote
+          .authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID })
+          .pipe(Effect.flip, Effect.forkChild);
+        yield* Deferred.await(started);
+        yield* Ref.set(harness.session, Option.none());
+        yield* Deferred.succeed(release, undefined);
+        expect(yield* Fiber.join(pending)).toMatchObject({
+          _tag: "ConnectionBlockedError",
+          reason: "authentication",
+        });
+      }).pipe(Effect.provide(harness.layer));
+      expect((yield* Ref.get(harness.tokens)).size).toBe(0);
+    }),
+  );
+
+  it.effect(
+    "renews another account's persisted token after the authorization service restarts",
+    () =>
+      Effect.gen(function* () {
+        const harness = yield* makeHarness({
+          initialToken: persistedToken(),
+          responses: [Response.json(DESCRIPTOR), accessToken("account-2-token")],
+        });
+        const authorize = Effect.gen(function* () {
+          const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+          return yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+        }).pipe(Effect.provide(harness.layer));
+
+        expect((yield* authorize).httpAuthorization.accessToken).toBe("cached-access-token");
+        yield* Ref.set(harness.session, Option.some({ accountId: "account-2" }));
+        expect((yield* authorize).httpAuthorization.accessToken).toBe("account-2-token");
+        expect((yield* Ref.get(harness.tokens)).get(ENVIRONMENT_ID)?.accountId).toBe("account-2");
+
+        yield* Ref.set(harness.session, Option.some({ accountId: "account-2" }));
+        expect((yield* authorize).httpAuthorization.accessToken).toBe("account-2-token");
+        expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+        expect(harness.fetch.calls).toHaveLength(2);
+      }),
+  );
+
+  it.effect("renews a legacy unowned token once and reuses its account-bound replacement", () =>
+    Effect.gen(function* () {
+      const legacy = new TokenStore.RemoteDpopAccessToken({
+        environmentId: ENVIRONMENT_ID,
+        label: DESCRIPTOR.label,
+        endpoint: ENDPOINT,
+        accessToken: "legacy-access-token",
+        expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
+        dpopThumbprint: "thumbprint-1",
+      });
+      const harness = yield* makeHarness({
+        initialToken: legacy,
+        responses: [Response.json(DESCRIPTOR), accessToken("account-bound-token")],
+      });
+      const authorize = Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        return yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+      }).pipe(Effect.provide(harness.layer));
+
+      expect((yield* authorize).httpAuthorization.accessToken).toBe("account-bound-token");
+      expect((yield* Ref.get(harness.tokens)).get(ENVIRONMENT_ID)?.accountId).toBe("account-1");
+      expect((yield* authorize).httpAuthorization.accessToken).toBe("account-bound-token");
+      expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+      expect(harness.fetch.calls).toHaveLength(2);
+    }),
+  );
+
+  it.effect("requires fresh credentials after signing back into the same account", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        initialToken: persistedToken(),
+        responses: [Response.json(DESCRIPTOR), accessToken("new-session-token")],
+      });
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+        yield* Ref.set(harness.session, Option.none());
+        const signedOut = yield* remote
+          .authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID })
+          .pipe(Effect.flip);
+        expect(signedOut).toMatchObject({
+          _tag: "ConnectionBlockedError",
+          reason: "authentication",
+        });
+        yield* Ref.set(harness.session, Option.some({ accountId: "account-1" }));
+        const signedIn = yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+        expect(signedIn.httpAuthorization.accessToken).toBe("new-session-token");
+      }).pipe(Effect.provide(harness.layer));
+      expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+    }),
+  );
+
+  it.effect("renews a cached credential bound to a different signing key", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        initialToken: persistedToken(),
+        responses: [Response.json(DESCRIPTOR), accessToken("new-key-token")],
+      });
+      yield* Ref.set(harness.thumbprint, "thumbprint-2");
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const authorized = yield* remote.authorizeDpopHttp({
+          expectedEnvironmentId: ENVIRONMENT_ID,
+        });
+        expect(authorized.httpAuthorization.accessToken).toBe("new-key-token");
+      }).pipe(Effect.provide(harness.layer));
+      expect((yield* Ref.get(harness.tokens)).get(ENVIRONMENT_ID)?.dpopThumbprint).toBe(
+        "thumbprint-2",
+      );
+    }),
+  );
+
+  it.effect("rejects a relay bootstrap for a different environment before contacting it", () =>
+    Effect.gen(function* () {
+      const harness = yield* makeHarness({
+        responses: [],
+        bootstrap: { ...BOOTSTRAP, environmentId: EnvironmentId.make("wrong-environment") },
+      });
+      const failure = yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        return yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+      }).pipe(Effect.provide(harness.layer), Effect.flip);
+      expect(failure).toMatchObject({ _tag: "ConnectionBlockedError", reason: "configuration" });
+      expect(harness.fetch.calls).toHaveLength(0);
+    }),
+  );
+
+  it.effect("keeps a shared renewal alive when one waiting request is interrupted", () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const release = yield* Deferred.make<void>();
+      const harness = yield* makeHarness({
+        beforeBootstrap: Deferred.succeed(started, undefined).pipe(
+          Effect.andThen(Deferred.await(release)),
+        ),
+        responses: [Response.json(DESCRIPTOR), accessToken("fresh-token")],
+      });
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const pending = yield* remote
+          .authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID })
+          .pipe(Effect.forkChild);
+        yield* Deferred.await(started);
+        const other = yield* remote
+          .authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID })
+          .pipe(Effect.forkChild);
+        yield* Queue.takeN(harness.tokenReads, 2);
+        yield* Fiber.interrupt(pending);
+        yield* Deferred.succeed(release, undefined);
+        const authorized = yield* Fiber.join(other);
+        expect(authorized.httpAuthorization.accessToken).toBe("fresh-token");
+        const cached = yield* remote.authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID });
+        expect(cached).toEqual(authorized);
+      }).pipe(Effect.provide(harness.layer));
+      expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+    }),
+  );
+
+  it.effect("times out a stalled cloud token read so later requests can renew again", () =>
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const reads = yield* Ref.make(0);
+      const harness = yield* makeHarness({
+        clerkToken: Effect.gen(function* () {
+          const read = yield* Ref.updateAndGet(reads, (value) => value + 1);
+          if (read === 1) {
+            yield* Deferred.succeed(started, undefined);
+            return yield* Effect.never;
+          }
+          return "clerk-session";
+        }),
+        responses: [Response.json(DESCRIPTOR), accessToken("fresh-token")],
+      });
+      yield* Effect.gen(function* () {
+        const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
+        const pending = yield* remote
+          .authorizeDpopHttp({ expectedEnvironmentId: ENVIRONMENT_ID })
+          .pipe(Effect.flip, Effect.forkChild);
+        yield* Deferred.await(started);
+        yield* TestClock.adjust("30 seconds");
+        expect(yield* Fiber.join(pending)).toMatchObject({
+          _tag: "ConnectionTransientError",
+          reason: "timeout",
+        });
+        const authorized = yield* remote.authorizeDpopHttp({
+          expectedEnvironmentId: ENVIRONMENT_ID,
+        });
+        expect(authorized.httpAuthorization.accessToken).toBe("fresh-token");
+      }).pipe(Effect.provide(harness.layer));
+      expect(yield* Ref.get(reads)).toBe(2);
+      expect(yield* Ref.get(harness.bootstrapCalls)).toBe(1);
+    }),
+  );
 });
diff --git a/packages/client-runtime/src/authorization/service.ts b/packages/client-runtime/src/authorization/service.ts
index d918dcf0613d..85929f73dd38 100644
--- a/packages/client-runtime/src/authorization/service.ts
+++ b/packages/client-runtime/src/authorization/service.ts
@@ -3,7 +3,8 @@ import {
   EnvironmentId,
   type ExecutionEnvironmentDescriptor,
 } from "@t3tools/contracts";
-import type { RelayManagedEndpoint } from "@t3tools/contracts/relay";
+import { RelayEnvironmentConnectScope } from "@t3tools/contracts/relay";
+import { withRelayClientTracing } from "@t3tools/shared/relayTracing";
 import {
   exchangeRemoteDpopAccessToken,
   type RemoteEnvironmentAuthError,
@@ -12,10 +13,15 @@ import {
 } from "./remote.ts";
 import {
   environmentMismatchError,
+  mapManagedRelayError,
   mapRemoteDpopEnvironmentError,
   mapRemoteEnvironmentError,
 } from "../connection/errors.ts";
-import { ConnectionBlockedError, type ConnectionAttemptError } from "../connection/model.ts";
+import {
+  ConnectionBlockedError,
+  ConnectionTransientError,
+  type ConnectionAttemptError,
+} from "../connection/model.ts";
 import { fetchRemoteEnvironmentDescriptor } from "../environment/descriptor.ts";
 import { environmentEndpointUrl } from "../environment/endpoint.ts";
 import * as ClientCapabilities from "../platform/capabilities.ts";
@@ -24,10 +30,13 @@ import * as TokenStore from "./tokenStore.ts";
 import * as Clock from "effect/Clock";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
 import * as Result from "effect/Result";
+import * as Scope from "effect/Scope";
+import * as Semaphore from "effect/Semaphore";
 import * as HttpClient from "effect/unstable/http/HttpClient";
 
 import {
@@ -35,12 +44,6 @@ import {
   type PreparedHttpAuthorization,
 } from "../connection/model.ts";
 
-export interface RelayEnvironmentAuthorization {
-  readonly environmentId: EnvironmentId;
-  readonly endpoint: RelayManagedEndpoint;
-  readonly credential: string;
-}
-
 export interface AuthorizedRemoteEnvironment {
   readonly environmentId: EnvironmentId;
   readonly label: string;
@@ -49,6 +52,13 @@ export interface AuthorizedRemoteEnvironment {
   readonly httpAuthorization: PreparedHttpAuthorization;
 }
 
+export interface AuthorizedRemoteHttpEnvironment {
+  readonly environmentId: EnvironmentId;
+  readonly label: string;
+  readonly httpBaseUrl: string;
+  readonly httpAuthorization: Extract<PreparedHttpAuthorization, { readonly _tag: "Dpop" }>;
+}
+
 export class RemoteEnvironmentAuthorization extends Context.Service<
   RemoteEnvironmentAuthorization,
   {
@@ -61,16 +71,17 @@ export class RemoteEnvironmentAuthorization extends Context.Service<
     }) => Effect.Effect<AuthorizedRemoteEnvironment, ConnectionAttemptError>;
     readonly authorizeDpop: (input: {
       readonly expectedEnvironmentId: EnvironmentId;
-      readonly obtainBootstrap: Effect.Effect<
-        RelayEnvironmentAuthorization,
-        ConnectionAttemptError
-      >;
     }) => Effect.Effect<AuthorizedRemoteEnvironment, ConnectionAttemptError>;
+    readonly authorizeDpopHttp: (input: {
+      readonly expectedEnvironmentId: EnvironmentId;
+      readonly rejectedAccessToken?: string;
+    }) => Effect.Effect<AuthorizedRemoteHttpEnvironment, ConnectionAttemptError>;
   }
 >()("@t3tools/client-runtime/authorization/service/RemoteEnvironmentAuthorization") {}
 
 const CACHED_ENDPOINT_SOCKET_TIMEOUT_MS = 3_000;
 const BEARER_DESCRIPTOR_CACHE_TTL_MS = 10_000;
+const DPOP_AUTHORIZATION_TIMEOUT_MS = 30_000;
 
 function mapDpopSocketError(error: RemoteEnvironmentAuthError | ConnectionAttemptError) {
   return error._tag === "ConnectionTransientError" || error._tag === "ConnectionBlockedError"
@@ -80,17 +91,36 @@ function mapDpopSocketError(error: RemoteEnvironmentAuthError | ConnectionAttemp
 
 const fetchDescriptor = Effect.fn("clientRuntime.connection.remote.fetchDescriptor")(function* (
   httpBaseUrl: string,
+  connectionMethod: ClientConnectionMethod,
 ) {
   return yield* fetchRemoteEnvironmentDescriptor({ httpBaseUrl }).pipe(
-    Effect.mapError(mapRemoteEnvironmentError),
+    Effect.mapError((error) => mapRemoteEnvironmentError(error, connectionMethod)),
   );
 });
 
 export const make = Effect.gen(function* () {
+  const serviceScope = yield* Scope.Scope;
   const signer = yield* ManagedRelay.ManagedRelayDpopSigner;
+  const relay = yield* ManagedRelay.ManagedRelayClient;
+  const cloudSession = yield* ClientCapabilities.CloudSession;
+  const deviceIdentity = yield* ClientCapabilities.RelayDeviceIdentity;
   const presentation = yield* ClientCapabilities.ClientPresentation;
   const tokenStore = yield* TokenStore.RemoteDpopAccessTokenStore;
   const httpClient = yield* HttpClient.HttpClient;
+  const tokenLock = yield* Semaphore.make(1);
+  const tokenOwners = new Map<
+    EnvironmentId,
+    { readonly accessToken: string; readonly identity: ClientCapabilities.CloudSessionIdentity }
+  >();
+  const pendingTokens = new Map<
+    EnvironmentId,
+    {
+      readonly id: object;
+      readonly identity: ClientCapabilities.CloudSessionIdentity;
+      readonly thumbprint: string;
+      readonly token: Effect.Effect<TokenStore.RemoteDpopAccessToken, ConnectionAttemptError>;
+    }
+  >();
   const bearerDescriptors = yield* Ref.make<
     ReadonlyMap<
       EnvironmentId,
@@ -119,7 +149,7 @@ export const make = Effect.gen(function* () {
         cachedDescriptor.validatedAtEpochMs + BEARER_DESCRIPTOR_CACHE_TTL_MS > now;
       const descriptor = canReuseDescriptor
         ? cachedDescriptor.descriptor
-        : yield* fetchDescriptor(input.httpBaseUrl).pipe(
+        : yield* fetchDescriptor(input.httpBaseUrl, input.connectionMethod).pipe(
             Effect.provideService(HttpClient.HttpClient, httpClient),
           );
       if (descriptor.environmentId !== input.expectedEnvironmentId) {
@@ -191,74 +221,77 @@ export const make = Effect.gen(function* () {
     },
   );
 
-  const authorizeDpop = Effect.fn("clientRuntime.connection.remote.authorizeDpop")(
-    function* (input: {
-      readonly expectedEnvironmentId: Parameters<
-        RemoteEnvironmentAuthorization["Service"]["authorizeDpop"]
-      >[0]["expectedEnvironmentId"];
-      readonly obtainBootstrap: Parameters<
-        RemoteEnvironmentAuthorization["Service"]["authorizeDpop"]
-      >[0]["obtainBootstrap"];
-    }) {
-      const thumbprint = yield* signer.thumbprint.pipe(
-        Effect.mapError(
-          () =>
-            new ConnectionBlockedError({
-              reason: "configuration",
-              detail: "Could not load the environment authorization key.",
-            }),
-        ),
-        Effect.withSpan("environment.authorization.dpopKey.resolve"),
-      );
-      const now = yield* Clock.currentTimeMillis;
-      const cached = yield* tokenStore
-        .get(input.expectedEnvironmentId)
-        .pipe(Effect.withSpan("environment.authorization.accessToken.cache"));
-      if (
-        Option.isSome(cached) &&
-        cached.value.environmentId === input.expectedEnvironmentId &&
-        cached.value.dpopThumbprint === thumbprint &&
-        cached.value.expiresAtEpochMs > now + DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS
-      ) {
-        yield* Effect.annotateCurrentSpan({
-          "connection.remote_token_cache": "hit",
-        });
-        const cachedSocket = yield* createDpopSocketUrl(
-          cached.value,
-          CACHED_ENDPOINT_SOCKET_TIMEOUT_MS,
-        ).pipe(Effect.result);
-        if (Result.isSuccess(cachedSocket)) {
-          return {
-            environmentId: cached.value.environmentId,
-            label: cached.value.label,
-            httpBaseUrl: cached.value.endpoint.httpBaseUrl,
-            socketUrl: cachedSocket.success,
-            httpAuthorization: {
-              _tag: "Dpop" as const,
-              accessToken: cached.value.accessToken,
-              expiresAtEpochMs: cached.value.expiresAtEpochMs,
-            },
-          };
-        }
-        if (cachedSocket.failure._tag === "ConnectionBlockedError") {
-          return yield* mapDpopSocketError(cachedSocket.failure);
-        }
-        yield* tokenStore
-          .remove(input.expectedEnvironmentId)
-          .pipe(Effect.withSpan("environment.authorization.accessToken.remove"));
-      }
+  const sessionChanged = () =>
+    new ConnectionBlockedError({
+      reason: "authentication",
+      detail: "Your cloud sign-in changed. Sign in again to authorize the environment.",
+    });
+
+  const assertSession = Effect.fnUntraced(function* (
+    identity: ClientCapabilities.CloudSessionIdentity,
+  ) {
+    const current = yield* cloudSession.identity;
+    if (Option.isNone(current) || current.value !== identity) {
+      return yield* sessionChanged();
+    }
+  });
 
-      yield* Effect.annotateCurrentSpan({
-        "connection.remote_token_cache": "miss",
+  // Called under tokenLock so a late rejection cannot remove a newer credential.
+  const removeRejectedToken = Effect.fnUntraced(function* (
+    environmentId: EnvironmentId,
+    accessToken: string,
+  ) {
+    const cached = yield* tokenStore.get(environmentId);
+    if (Option.isSome(cached) && cached.value.accessToken === accessToken) {
+      yield* tokenStore.remove(environmentId);
+      tokenOwners.delete(environmentId);
+    }
+  });
+
+  const obtainBootstrap = Effect.fn("relay.connection.bootstrap.obtain")(function* (
+    environmentId: EnvironmentId,
+    identity: ClientCapabilities.CloudSessionIdentity,
+  ) {
+    yield* assertSession(identity);
+    const clerkToken = yield* cloudSession.clerkToken.pipe(
+      Effect.withSpan("relay.connection.cloudSessionToken.resolve"),
+    );
+    const deviceId = yield* deviceIdentity.deviceId.pipe(
+      Effect.withSpan("relay.connection.deviceIdentity.resolve"),
+    );
+    yield* assertSession(identity);
+    const connected = yield* relay
+      .connectEnvironment({
+        clerkToken,
+        scopes: [RelayEnvironmentConnectScope],
+        environmentId,
+        ...(Option.isSome(deviceId) ? { deviceId: deviceId.value } : {}),
+      })
+      .pipe(Effect.mapError(mapManagedRelayError));
+    if (connected.environmentId !== environmentId) {
+      return yield* environmentMismatchError({
+        expected: environmentId,
+        actual: connected.environmentId,
       });
-      const bootstrap = yield* input.obtainBootstrap;
-      const descriptor = yield* fetchDescriptor(bootstrap.endpoint.httpBaseUrl).pipe(
+    }
+    yield* assertSession(identity);
+    return connected;
+  });
+
+  const exchangeDpopToken = Effect.fn("clientRuntime.connection.remote.exchangeDpopToken")(
+    function* (
+      environmentId: EnvironmentId,
+      thumbprint: string,
+      identity: ClientCapabilities.CloudSessionIdentity,
+    ) {
+      const bootstrap = yield* obtainBootstrap(environmentId, identity);
+      const descriptor = yield* fetchDescriptor(bootstrap.endpoint.httpBaseUrl, "relay").pipe(
         Effect.provideService(HttpClient.HttpClient, httpClient),
         Effect.withSpan("environment.authorization.descriptor"),
       );
-      if (descriptor.environmentId !== input.expectedEnvironmentId) {
+      if (descriptor.environmentId !== environmentId) {
         return yield* environmentMismatchError({
-          expected: input.expectedEnvironmentId,
+          expected: environmentId,
           actual: descriptor.environmentId,
         });
       }
@@ -276,6 +309,7 @@ export const make = Effect.gen(function* () {
               }),
           ),
         );
+      yield* assertSession(identity);
       const access = yield* exchangeRemoteDpopAccessToken({
         httpBaseUrl: bootstrap.endpoint.httpBaseUrl,
         credential: bootstrap.credential,
@@ -288,36 +322,186 @@ export const make = Effect.gen(function* () {
         Effect.withSpan("environment.authorization.accessToken.exchange"),
       );
       const issuedAt = yield* Clock.currentTimeMillis;
-      const token = new TokenStore.RemoteDpopAccessToken({
+      return new TokenStore.RemoteDpopAccessToken({
         environmentId: descriptor.environmentId,
+        accountId: identity.accountId,
         label: descriptor.label,
         endpoint: bootstrap.endpoint,
         accessToken: access.access_token,
         expiresAtEpochMs: issuedAt + access.expires_in * 1_000,
         dpopThumbprint: thumbprint,
       });
-      const socketUrl = yield* createDpopSocketUrl(token).pipe(Effect.mapError(mapDpopSocketError));
-      yield* tokenStore
-        .put(token)
-        .pipe(Effect.withSpan("environment.authorization.accessToken.persist"));
-      return {
-        environmentId: descriptor.environmentId,
-        label: descriptor.label,
-        httpBaseUrl: bootstrap.endpoint.httpBaseUrl,
-        socketUrl,
-        httpAuthorization: {
-          _tag: "Dpop" as const,
-          accessToken: token.accessToken,
-          expiresAtEpochMs: token.expiresAtEpochMs,
-        },
-      };
     },
   );
 
+  const getDpopToken = Effect.fn("clientRuntime.connection.remote.getDpopToken")(function* (
+    input: Parameters<RemoteEnvironmentAuthorization["Service"]["authorizeDpopHttp"]>[0],
+  ) {
+    const session = yield* cloudSession.identity;
+    if (Option.isNone(session)) {
+      return yield* sessionChanged();
+    }
+    const identity = session.value;
+    const thumbprint = yield* signer.thumbprint.pipe(
+      Effect.mapError(
+        () =>
+          new ConnectionBlockedError({
+            reason: "configuration",
+            detail: "Could not load the environment authorization key.",
+          }),
+      ),
+      Effect.withSpan("environment.authorization.dpopKey.resolve"),
+    );
+    const selected = yield* tokenLock.withPermits(1)(
+      Effect.gen(function* () {
+        yield* assertSession(identity);
+        const now = yield* Clock.currentTimeMillis;
+        const cached = yield* tokenStore
+          .get(input.expectedEnvironmentId)
+          .pipe(Effect.withSpan("environment.authorization.accessToken.cache"));
+        const owner = tokenOwners.get(input.expectedEnvironmentId);
+        if (
+          Option.isSome(cached) &&
+          cached.value.environmentId === input.expectedEnvironmentId &&
+          cached.value.accountId === identity.accountId &&
+          cached.value.dpopThumbprint === thumbprint &&
+          cached.value.expiresAtEpochMs > now + DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS &&
+          cached.value.accessToken !== input.rejectedAccessToken &&
+          (owner?.accessToken !== cached.value.accessToken || owner.identity === identity)
+        ) {
+          tokenOwners.set(input.expectedEnvironmentId, {
+            accessToken: cached.value.accessToken,
+            identity,
+          });
+          return { token: Effect.succeed(cached.value), fromCache: true };
+        }
+        if (input.rejectedAccessToken !== undefined) {
+          yield* removeRejectedToken(input.expectedEnvironmentId, input.rejectedAccessToken);
+        }
+        const pending = pendingTokens.get(input.expectedEnvironmentId);
+        if (pending?.identity === identity && pending.thumbprint === thumbprint) {
+          return { token: pending.token, fromCache: false };
+        }
+
+        const id = {};
+        const fiber = yield* exchangeDpopToken(
+          input.expectedEnvironmentId,
+          thumbprint,
+          identity,
+        ).pipe(
+          Effect.flatMap((token) =>
+            tokenLock.withPermits(1)(
+              Effect.gen(function* () {
+                yield* assertSession(identity);
+                yield* tokenStore
+                  .put(token)
+                  .pipe(Effect.withSpan("environment.authorization.accessToken.persist"));
+                const current = yield* cloudSession.identity;
+                if (Option.isNone(current) || current.value !== identity) {
+                  yield* removeRejectedToken(input.expectedEnvironmentId, token.accessToken);
+                  return yield* sessionChanged();
+                }
+                tokenOwners.set(input.expectedEnvironmentId, {
+                  accessToken: token.accessToken,
+                  identity,
+                });
+                if (pendingTokens.get(input.expectedEnvironmentId)?.id === id) {
+                  pendingTokens.delete(input.expectedEnvironmentId);
+                }
+                return token;
+              }),
+            ),
+          ),
+          Effect.timeoutOrElse({
+            duration: DPOP_AUTHORIZATION_TIMEOUT_MS,
+            orElse: () =>
+              Effect.fail(
+                new ConnectionTransientError({
+                  reason: "timeout",
+                  detail: "Timed out renewing the environment credential.",
+                }),
+              ),
+          }),
+          Effect.ensuring(
+            tokenLock.withPermits(1)(
+              Effect.sync(() => {
+                if (pendingTokens.get(input.expectedEnvironmentId)?.id === id) {
+                  pendingTokens.delete(input.expectedEnvironmentId);
+                }
+              }),
+            ),
+          ),
+          // One caller's timeout must not cancel renewal for other HTTP requests.
+          Effect.forkIn(serviceScope),
+        );
+        const token = Fiber.join(fiber);
+        pendingTokens.set(input.expectedEnvironmentId, { id, identity, thumbprint, token });
+        return { token, fromCache: false };
+      }),
+    );
+    yield* Effect.annotateCurrentSpan({
+      "connection.remote_token_cache": selected.fromCache ? "hit" : "miss",
+    });
+    const token = yield* selected.token;
+    yield* assertSession(identity);
+    return { token, fromCache: selected.fromCache, identity };
+  });
+
+  const httpAuthorization = (
+    token: TokenStore.RemoteDpopAccessToken,
+  ): AuthorizedRemoteHttpEnvironment => ({
+    environmentId: token.environmentId,
+    label: token.label,
+    httpBaseUrl: token.endpoint.httpBaseUrl,
+    httpAuthorization: {
+      _tag: "Dpop",
+      accessToken: token.accessToken,
+      expiresAtEpochMs: token.expiresAtEpochMs,
+    },
+  });
+
+  const authorizeDpop = Effect.fn("clientRuntime.connection.remote.authorizeDpop")(function* (
+    input: Parameters<RemoteEnvironmentAuthorization["Service"]["authorizeDpop"]>[0],
+  ) {
+    let selected = yield* getDpopToken(input);
+    if (selected.fromCache) {
+      const cachedSocket = yield* createDpopSocketUrl(
+        selected.token,
+        CACHED_ENDPOINT_SOCKET_TIMEOUT_MS,
+      ).pipe(Effect.result);
+      if (Result.isSuccess(cachedSocket)) {
+        yield* assertSession(selected.identity);
+        return { ...httpAuthorization(selected.token), socketUrl: cachedSocket.success };
+      }
+      if (cachedSocket.failure._tag === "ConnectionBlockedError") {
+        return yield* mapDpopSocketError(cachedSocket.failure);
+      }
+      selected = yield* getDpopToken({
+        ...input,
+        rejectedAccessToken: selected.token.accessToken,
+      });
+    }
+    const socket = yield* createDpopSocketUrl(selected.token).pipe(Effect.result);
+    if (Result.isFailure(socket)) {
+      yield* tokenLock.withPermits(1)(
+        removeRejectedToken(input.expectedEnvironmentId, selected.token.accessToken),
+      );
+      return yield* mapDpopSocketError(socket.failure);
+    }
+    yield* assertSession(selected.identity);
+    return { ...httpAuthorization(selected.token), socketUrl: socket.success };
+  });
+
   return RemoteEnvironmentAuthorization.of({
     authorizeBearer,
     authorizeDpop: (input) =>
       authorizeDpop(input).pipe(Effect.withSpan("environment.authorization")),
+    authorizeDpopHttp: (input) =>
+      getDpopToken(input).pipe(
+        Effect.map(({ token }) => httpAuthorization(token)),
+        Effect.withSpan("environment.authorization.http"),
+        withRelayClientTracing,
+      ),
   });
 });
 
diff --git a/packages/client-runtime/src/authorization/tokenStore.ts b/packages/client-runtime/src/authorization/tokenStore.ts
index c490a22da13d..78be32653de7 100644
--- a/packages/client-runtime/src/authorization/tokenStore.ts
+++ b/packages/client-runtime/src/authorization/tokenStore.ts
@@ -12,6 +12,7 @@ export class RemoteDpopAccessToken extends Schema.Class<RemoteDpopAccessToken>(
   "@t3tools/client-runtime/authorization/RemoteDpopAccessToken",
 )({
   environmentId: EnvironmentId,
+  accountId: Schema.optionalKey(Schema.String),
   label: Schema.String,
   endpoint: RelayManagedEndpoint,
   accessToken: Schema.String,
diff --git a/packages/client-runtime/src/connection/errors.test.ts b/packages/client-runtime/src/connection/errors.test.ts
index 771c9490ca3e..a892ceda7767 100644
--- a/packages/client-runtime/src/connection/errors.test.ts
+++ b/packages/client-runtime/src/connection/errors.test.ts
@@ -1,12 +1,40 @@
 import { EnvironmentAuthInvalidError } from "@t3tools/contracts";
-import { RelayAuthInvalidError } from "@t3tools/contracts/relay";
+import {
+  RelayAuthInvalidError,
+  RelayEnvironmentEndpointTimedOutError,
+} from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
 
-import { mapManagedRelayError, mapRemoteDpopEnvironmentError } from "./errors.ts";
+import {
+  mapManagedRelayError,
+  mapRemoteDpopEnvironmentError,
+  mapRemoteEnvironmentError,
+} from "./errors.ts";
 import { DPOP_RETRY_HINT, DPOP_UNKNOWN_HINT } from "../relay/errorPresentation.ts";
 import { ManagedRelayRequestFailedError } from "../relay/managedRelay.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
+import { RemoteEnvironmentAuthFetchError, RemoteEnvironmentAuthTimeoutError } from "../rpc/http.ts";
 
 describe("mapManagedRelayError", () => {
+  it("keeps a timeout reported by the relay distinct from a local network failure", () => {
+    const relayError = new RelayEnvironmentEndpointTimedOutError({
+      code: "environment_endpoint_timed_out",
+      traceId: "trace-server-timeout",
+    });
+    const mapped = mapManagedRelayError(
+      new ManagedRelayRequestFailedError({
+        action: "connect relay environment",
+        cause: relayError,
+        relayError,
+      }),
+    );
+    expect(mapped).toMatchObject({
+      reason: "timeout",
+      detail: "Relay timed out while contacting the environment endpoint.",
+      traceId: "trace-server-timeout",
+    });
+  });
+
   it("presents clock skew as one possible cause for a generic DPoP error", () => {
     const mapped = mapManagedRelayError(
       new ManagedRelayRequestFailedError({
@@ -48,6 +76,34 @@ describe("mapManagedRelayError", () => {
 });
 
 describe("mapRemoteDpopEnvironmentError", () => {
+  it("keeps relay descriptor auth failures distinct from DPoP proof failures", () => {
+    const error = new EnvironmentAuthInvalidError({
+      code: "auth_invalid",
+      reason: "invalid_credential",
+      traceId: "trace-descriptor",
+    });
+    expect(mapRemoteEnvironmentError(error, "relay").message).toBe(
+      "The environment credential is invalid.",
+    );
+    expect(mapRemoteDpopEnvironmentError(error).message).toBe(
+      `The environment credential is invalid. ${DPOP_UNKNOWN_HINT}`,
+    );
+  });
+
+  it.each([
+    new RemoteEnvironmentAuthFetchError({
+      message: "Failed to fetch remote environment endpoint.",
+      cause: new TypeError("Failed to fetch"),
+    }),
+    new RemoteEnvironmentAuthTimeoutError("https://environment.example.test", 10_000),
+  ])("suggests another network when the relay endpoint cannot be reached: $_tag", (error) => {
+    const mapped = mapRemoteDpopEnvironmentError(error);
+    expect(mapped).toMatchObject({
+      _tag: "ConnectionTransientError",
+      detail: `${error.message} ${NETWORK_BLOCKING_HINT}`,
+    });
+  });
+
   it("does not present a generic environment auth error as confirmed clock skew", () => {
     const mapped = mapRemoteDpopEnvironmentError(
       new EnvironmentAuthInvalidError({
diff --git a/packages/client-runtime/src/connection/errors.ts b/packages/client-runtime/src/connection/errors.ts
index ed8a117a6f5c..be7a1822cbde 100644
--- a/packages/client-runtime/src/connection/errors.ts
+++ b/packages/client-runtime/src/connection/errors.ts
@@ -1,8 +1,9 @@
-import type { EnvironmentId } from "@t3tools/contracts";
+import type { ClientConnectionMethod, EnvironmentId } from "@t3tools/contracts";
 import type { RelayProtectedError } from "@t3tools/contracts/relay";
 import type { ManagedRelayClientError } from "../relay/managedRelay.ts";
 import { dpopFailureMessage, relayProtectedErrorMessage } from "../relay/errorPresentation.ts";
 import type { RemoteEnvironmentAuthError } from "../authorization/remote.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import {
   ConnectionBlockedError,
   type ConnectionAttemptError,
@@ -113,7 +114,9 @@ export function mapManagedRelayError(error: ManagedRelayClientError): Connection
 
 export function mapRemoteEnvironmentError(
   error: RemoteEnvironmentAuthError,
+  connectionMethod: ClientConnectionMethod = "direct",
 ): ConnectionAttemptError {
+  const networkHint = connectionMethod === "relay" ? ` ${NETWORK_BLOCKING_HINT}` : "";
   switch (error._tag) {
     case "EnvironmentAuthInvalidError":
       return new ConnectionBlockedError({
@@ -146,12 +149,12 @@ export function mapRemoteEnvironmentError(
     case "RemoteEnvironmentAuthTimeoutError":
       return new ConnectionTransientError({
         reason: "timeout",
-        detail: error.message,
+        detail: `${error.message}${networkHint}`,
       });
     case "RemoteEnvironmentAuthFetchError":
       return new ConnectionTransientError({
         reason: "network",
-        detail: error.message,
+        detail: `${error.message}${networkHint}`,
       });
     case "EnvironmentInternalError":
       return new ConnectionTransientError({
@@ -185,5 +188,5 @@ export function mapRemoteDpopEnvironmentError(
       traceId: error.traceId,
     });
   }
-  return mapRemoteEnvironmentError(error);
+  return mapRemoteEnvironmentError(error, "relay");
 }
diff --git a/packages/client-runtime/src/connection/layer.ts b/packages/client-runtime/src/connection/layer.ts
index 7927151e5d42..43153838df35 100644
--- a/packages/client-runtime/src/connection/layer.ts
+++ b/packages/client-runtime/src/connection/layer.ts
@@ -11,13 +11,9 @@ import * as RelayEnvironmentDiscovery from "../relay/discovery.ts";
 import * as RemoteEnvironmentAuthorization from "../authorization/service.ts";
 import * as RpcSession from "../rpc/session.ts";
 
-const resolverLayer = ConnectionResolver.layer.pipe(
-  Layer.provide(RemoteEnvironmentAuthorization.layer),
-);
-
 export function layerWithOptions(options: RpcSession.RpcSessionOptions) {
   const driverLayer = ConnectionDriver.layer.pipe(
-    Layer.provide(Layer.mergeAll(resolverLayer, RpcSession.layerWithOptions(options))),
+    Layer.provide(Layer.mergeAll(ConnectionResolver.layer, RpcSession.layerWithOptions(options))),
   );
   const registryLayer = EnvironmentRegistry.layer.pipe(Layer.provide(driverLayer));
   const onboardingLayer = ConnectionOnboarding.layer.pipe(Layer.provide(registryLayer));
@@ -37,7 +33,10 @@ export function layerWithOptions(options: RpcSession.RpcSessionOptions) {
       );
     }).pipe(Effect.withSpan("clientRuntime.connection.application.start")),
   );
-  return connectionStartupLayer.pipe(Layer.provideMerge(connectionServicesLayer));
+  return connectionStartupLayer.pipe(
+    Layer.provideMerge(connectionServicesLayer),
+    Layer.provideMerge(RemoteEnvironmentAuthorization.layer),
+  );
 }
 
 export const layer = layerWithOptions({});
diff --git a/packages/client-runtime/src/connection/presentation.test.ts b/packages/client-runtime/src/connection/presentation.test.ts
index e13638a2b41f..80ce8a374a9c 100644
--- a/packages/client-runtime/src/connection/presentation.test.ts
+++ b/packages/client-runtime/src/connection/presentation.test.ts
@@ -10,7 +10,6 @@ import {
 } from "./model.ts";
 import {
   connectionCatalogDisplayUrl,
-  connectionPhaseMessage,
   connectionStatusText,
   connectionStatusTitle,
   presentEnvironmentConnection,
@@ -119,10 +118,6 @@ describe("connection presentation", () => {
     });
   });
 
-  it("gives offline status precedence in global messaging", () => {
-    expect(connectionPhaseMessage("connected", TARGET.label, "offline")).toBe("You are offline");
-  });
-
   it("combines reconnect progress with the latest failure", () => {
     const connection = {
       phase: "reconnecting",
diff --git a/packages/client-runtime/src/connection/presentation.ts b/packages/client-runtime/src/connection/presentation.ts
index 168443deceb4..4093167d333c 100644
--- a/packages/client-runtime/src/connection/presentation.ts
+++ b/packages/client-runtime/src/connection/presentation.ts
@@ -2,7 +2,7 @@ import type { ServerConfig } from "@t3tools/contracts";
 import * as Option from "effect/Option";
 
 import type { ConnectionCatalogEntry } from "./catalog.ts";
-import type { NetworkStatus, SupervisorConnectionState } from "./model.ts";
+import type { SupervisorConnectionState } from "./model.ts";
 
 export type EnvironmentConnectionPhase =
   | "available"
@@ -105,25 +105,3 @@ export function connectionCatalogDisplayUrl(entry: ConnectionCatalogEntry): stri
         : null;
   }
 }
-
-export function connectionPhaseMessage(
-  phase: EnvironmentConnectionPhase,
-  label: string,
-  networkStatus: NetworkStatus,
-): string {
-  if (networkStatus === "offline" || phase === "offline") {
-    return "You are offline";
-  }
-  switch (phase) {
-    case "available":
-      return "Available";
-    case "connecting":
-      return `Connecting to ${label}...`;
-    case "reconnecting":
-      return `Reconnecting to ${label}...`;
-    case "connected":
-      return "Connected";
-    case "error":
-      return "Connection failed";
-  }
-}
diff --git a/packages/client-runtime/src/connection/resolver.test.ts b/packages/client-runtime/src/connection/resolver.test.ts
index 5bfac4faadae..d1fc270f21fe 100644
--- a/packages/client-runtime/src/connection/resolver.test.ts
+++ b/packages/client-runtime/src/connection/resolver.test.ts
@@ -1,5 +1,4 @@
 import { EnvironmentId, type DesktopSshEnvironmentTarget } from "@t3tools/contracts";
-import { RelayEnvironmentConnectScope } from "@t3tools/contracts/relay";
 import { RelayClientTracer } from "@t3tools/shared/relayTracing";
 import { describe, expect, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -8,7 +7,6 @@ import * as Option from "effect/Option";
 import * as Ref from "effect/Ref";
 import * as Tracer from "effect/Tracer";
 
-import * as ManagedRelay from "../relay/managedRelay.ts";
 import * as ConnectionResolver from "./resolver.ts";
 import * as ClientCapabilities from "../platform/capabilities.ts";
 import * as RemoteEnvironmentAuthorization from "../authorization/service.ts";
@@ -35,7 +33,6 @@ const ENVIRONMENT_ID = EnvironmentId.make("environment-1");
 const ENDPOINT = {
   httpBaseUrl: "https://environment.example.test",
   wsBaseUrl: "wss://environment.example.test",
-  providerKind: "cloudflare_tunnel" as const,
 };
 const SSH_TARGET: DesktopSshEnvironmentTarget = {
   alias: "development",
@@ -51,10 +48,6 @@ function catalogEntry(
   return { target, profile };
 }
 
-function unsupported<A>(name: string): Effect.Effect<A> {
-  return Effect.die(new Error(`Unexpected relay call: ${name}`));
-}
-
 function collectingTracer(spans: Array<string>): Tracer.Tracer {
   return Tracer.make({
     span: (options) => {
@@ -69,30 +62,9 @@ function collectingTracer(spans: Array<string>): Tracer.Tracer {
   });
 }
 
-function relayClient(
-  connectEnvironment: ManagedRelay.ManagedRelayClient["Service"]["connectEnvironment"],
-) {
-  return ManagedRelay.ManagedRelayClient.of({
-    relayUrl: "https://relay.example.test",
-    listEnvironments: () => unsupported("listEnvironments"),
-    listDevices: () => unsupported("listDevices"),
-    createEnvironmentLinkChallenge: () => unsupported("createEnvironmentLinkChallenge"),
-    linkEnvironment: () => unsupported("linkEnvironment"),
-    unlinkEnvironment: () => unsupported("unlinkEnvironment"),
-    getEnvironmentStatus: () => unsupported("getEnvironmentStatus"),
-    connectEnvironment,
-    registerDevice: () => unsupported("registerDevice"),
-    unregisterDevice: () => unsupported("unregisterDevice"),
-    registerLiveActivity: () => unsupported("registerLiveActivity"),
-    getAgentActivitySnapshot: () => unsupported("getAgentActivitySnapshot"),
-    resetTokenCache: Effect.void,
-  });
-}
-
 const makeDependencies = Effect.fn("TestConnectionResolver.makeDependencies")((options?: {
   readonly profiles?: ReadonlyArray<ConnectionProfile>;
   readonly credentials?: ReadonlyArray<readonly [string, ConnectionCredential]>;
-  readonly connectEnvironment?: ManagedRelay.ManagedRelayClient["Service"]["connectEnvironment"];
   readonly authorizeBearer?: RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization["Service"]["authorizeBearer"];
   readonly authorizeDpop?: RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization["Service"]["authorizeDpop"];
   readonly primaryBearerToken?: string;
@@ -131,19 +103,18 @@ const makeDependencies = Effect.fn("TestConnectionResolver.makeDependencies")((o
     authorizeDpop:
       options?.authorizeDpop ??
       ((input) =>
-        input.obtainBootstrap.pipe(
-          Effect.as({
-            environmentId: input.expectedEnvironmentId,
-            label: "Authorized relay environment",
-            httpBaseUrl: ENDPOINT.httpBaseUrl,
-            socketUrl: "wss://authorized.example.test/ws?wsTicket=dpop",
-            httpAuthorization: {
-              _tag: "Dpop" as const,
-              accessToken: "dpop-access-token",
-              expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
-            },
-          }),
-        )),
+        Effect.succeed({
+          environmentId: input.expectedEnvironmentId,
+          label: "Authorized relay environment",
+          httpBaseUrl: ENDPOINT.httpBaseUrl,
+          socketUrl: "wss://authorized.example.test/ws?wsTicket=dpop",
+          httpAuthorization: {
+            _tag: "Dpop" as const,
+            accessToken: "dpop-access-token",
+            expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
+          },
+        })),
+    authorizeDpopHttp: () => Effect.die("unused"),
   });
   const ssh = ClientCapabilities.SshEnvironmentGateway.of({
     provision: () => Effect.die("unused"),
@@ -165,10 +136,6 @@ const makeDependencies = Effect.fn("TestConnectionResolver.makeDependencies")((o
   const dependencies = Layer.mergeAll(
     Layer.succeed(ConnectionProfileStore.ConnectionProfileStore, profileStore),
     Layer.succeed(ConnectionCredentialStore.ConnectionCredentialStore, credentialStore),
-    Layer.succeed(
-      ClientCapabilities.CloudSession,
-      ClientCapabilities.CloudSession.of({ clerkToken: Effect.succeed("clerk-session") }),
-    ),
     Layer.succeed(
       ClientCapabilities.PrimaryEnvironmentAuth,
       ClientCapabilities.PrimaryEnvironmentAuth.of({
@@ -182,27 +149,8 @@ const makeDependencies = Effect.fn("TestConnectionResolver.makeDependencies")((o
         scopes: [],
       }),
     ),
-    Layer.succeed(
-      ClientCapabilities.RelayDeviceIdentity,
-      ClientCapabilities.RelayDeviceIdentity.of({
-        deviceId: Effect.succeed(Option.some("device-1")),
-      }),
-    ),
     Layer.succeed(RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization, remote),
     Layer.succeed(ClientCapabilities.SshEnvironmentGateway, ssh),
-    Layer.succeed(
-      ManagedRelay.ManagedRelayClient,
-      relayClient(
-        options?.connectEnvironment ??
-          ((input) =>
-            Effect.succeed({
-              environmentId: input.environmentId,
-              endpoint: ENDPOINT,
-              credential: "relay-bootstrap",
-              expiresAt: "2026-06-06T00:00:00.000Z",
-            })),
-      ),
-    ),
   );
 
   return Effect.succeed(ConnectionResolver.layer.pipe(Layer.provide(dependencies)));
@@ -314,66 +262,27 @@ describe("ConnectionResolver", () => {
     }),
   );
 
-  it.effect("brokers relay credentials with the current cloud session and device identity", () =>
+  it.effect("prepares relay connections with the authorized endpoint and credentials", () =>
     Effect.gen(function* () {
-      const relayInputs = yield* Ref.make<
-        ReadonlyArray<{
-          readonly clerkToken: string;
-          readonly scopes: ReadonlyArray<string>;
-          readonly deviceId?: string;
-        }>
-      >([]);
-      const bootstrapCredentials = yield* Ref.make<ReadonlyArray<string>>([]);
       const target = new RelayConnectionTarget({
         environmentId: ENVIRONMENT_ID,
         label: "Cloud",
       });
-      const brokerLayer = yield* makeDependencies({
-        connectEnvironment: (input) =>
-          Ref.update(relayInputs, (values) => [
-            ...values,
-            {
-              clerkToken: input.clerkToken,
-              scopes: input.scopes,
-              ...(input.deviceId ? { deviceId: input.deviceId } : {}),
-            },
-          ]).pipe(
-            Effect.as({
-              environmentId: input.environmentId,
-              endpoint: ENDPOINT,
-              credential: "relay-bootstrap",
-              expiresAt: "2026-06-06T00:00:00.000Z",
-            }),
-          ),
-        authorizeDpop: (input) =>
-          input.obtainBootstrap.pipe(
-            Effect.tap((bootstrap) =>
-              Ref.update(bootstrapCredentials, (values) => [...values, bootstrap.credential]),
-            ),
-            Effect.as({
-              environmentId: input.expectedEnvironmentId,
-              label: "Cloud",
-              httpBaseUrl: ENDPOINT.httpBaseUrl,
-              socketUrl: "wss://environment.example.test/ws?wsTicket=dpop",
-              httpAuthorization: {
-                _tag: "Dpop" as const,
-                accessToken: "dpop-access-token",
-                expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
-              },
-            }),
-          ),
-      });
+      const brokerLayer = yield* makeDependencies();
       const broker = yield* ConnectionResolver.ConnectionResolver.pipe(Effect.provide(brokerLayer));
 
-      expect((yield* broker.prepare(catalogEntry(target))).socketUrl).toContain("wsTicket=dpop");
-      expect(yield* Ref.get(relayInputs)).toEqual([
-        {
-          clerkToken: "clerk-session",
-          scopes: [RelayEnvironmentConnectScope],
-          deviceId: "device-1",
+      expect(yield* broker.prepare(catalogEntry(target))).toEqual({
+        environmentId: ENVIRONMENT_ID,
+        label: "Authorized relay environment",
+        httpBaseUrl: ENDPOINT.httpBaseUrl,
+        socketUrl: "wss://authorized.example.test/ws?wsTicket=dpop",
+        httpAuthorization: {
+          _tag: "Dpop",
+          accessToken: "dpop-access-token",
+          expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
         },
-      ]);
-      expect(yield* Ref.get(bootstrapCredentials)).toEqual(["relay-bootstrap"]);
+        target,
+      });
     }),
   );
 
@@ -387,20 +296,17 @@ describe("ConnectionResolver", () => {
       });
       const brokerLayer = yield* makeDependencies({
         authorizeDpop: (input) =>
-          input.obtainBootstrap.pipe(
-            Effect.as({
-              environmentId: input.expectedEnvironmentId,
-              label: "Cloud",
-              httpBaseUrl: ENDPOINT.httpBaseUrl,
-              socketUrl: "wss://environment.example.test/ws?wsTicket=dpop",
-              httpAuthorization: {
-                _tag: "Dpop" as const,
-                accessToken: "dpop-access-token",
-                expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
-              },
-            }),
-            Effect.withSpan("test.remote.authorizeDpop"),
-          ),
+          Effect.succeed({
+            environmentId: input.expectedEnvironmentId,
+            label: "Cloud",
+            httpBaseUrl: ENDPOINT.httpBaseUrl,
+            socketUrl: "wss://environment.example.test/ws?wsTicket=dpop",
+            httpAuthorization: {
+              _tag: "Dpop" as const,
+              accessToken: "dpop-access-token",
+              expiresAtEpochMs: Number.MAX_SAFE_INTEGER,
+            },
+          }).pipe(Effect.withSpan("test.remote.authorizeDpop")),
       });
       const broker = yield* ConnectionResolver.ConnectionResolver.pipe(Effect.provide(brokerLayer));
 
@@ -470,27 +376,24 @@ describe("ConnectionResolver", () => {
     }),
   );
 
-  it.effect("classifies relay request timeouts as retryable connection failures", () =>
+  it.effect("preserves relay authorization failure classification and trace details", () =>
     Effect.gen(function* () {
       const target = new RelayConnectionTarget({
         environmentId: ENVIRONMENT_ID,
         label: "Cloud",
       });
+      const authorizationError = new ConnectionTransientError({
+        reason: "timeout",
+        detail: "Relay environment connection timed out.",
+        traceId: "relay-trace",
+      });
       const brokerLayer = yield* makeDependencies({
-        connectEnvironment: () =>
-          Effect.fail(
-            new ManagedRelay.ManagedRelayRequestTimeoutError({
-              activity: "Relay environment connection",
-              timeoutMs: ManagedRelay.MANAGED_RELAY_REQUEST_TIMEOUT_MS,
-              traceId: null,
-            }),
-          ),
+        authorizeDpop: () => Effect.fail(authorizationError),
       });
       const broker = yield* ConnectionResolver.ConnectionResolver.pipe(Effect.provide(brokerLayer));
       const error = yield* Effect.flip(broker.prepare(catalogEntry(target)));
 
-      expect(error).toBeInstanceOf(ConnectionTransientError);
-      expect(error).toMatchObject({ reason: "timeout" });
+      expect(error).toBe(authorizationError);
     }),
   );
 });
diff --git a/packages/client-runtime/src/connection/resolver.ts b/packages/client-runtime/src/connection/resolver.ts
index a786ed9f9d8d..cbffca7b29e9 100644
--- a/packages/client-runtime/src/connection/resolver.ts
+++ b/packages/client-runtime/src/connection/resolver.ts
@@ -1,5 +1,4 @@
 import type { AuthClientPresentationMetadata } from "@t3tools/contracts";
-import { RelayEnvironmentConnectScope } from "@t3tools/contracts/relay";
 import { withRelayClientTracing } from "@t3tools/shared/relayTracing";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
@@ -9,7 +8,6 @@ import * as Schema from "effect/Schema";
 
 import { appendClientConnectionParams } from "../authorization/remote.ts";
 import * as RemoteEnvironmentAuthorization from "../authorization/service.ts";
-import * as ManagedRelay from "../relay/managedRelay.ts";
 import * as ClientCapabilities from "../platform/capabilities.ts";
 import {
   BearerConnectionCredential,
@@ -18,12 +16,7 @@ import {
   SshConnectionProfile,
 } from "./catalog.ts";
 import * as ConnectionCredentialStore from "./credentialStore.ts";
-import {
-  credentialMissingError,
-  environmentMismatchError,
-  mapManagedRelayError,
-  profileMissingError,
-} from "./errors.ts";
+import { credentialMissingError, environmentMismatchError, profileMissingError } from "./errors.ts";
 import type {
   BearerConnectionTarget,
   ConnectionTarget,
@@ -148,38 +141,12 @@ const makeBearerBroker = Effect.fn("clientRuntime.connection.broker.makeBearer")
 });
 
 const makeRelayBroker = Effect.fn("clientRuntime.connection.broker.makeRelay")(function* () {
-  const relay = yield* ManagedRelay.ManagedRelayClient;
-  const session = yield* ClientCapabilities.CloudSession;
-  const identity = yield* ClientCapabilities.RelayDeviceIdentity;
   const remote = yield* RemoteEnvironmentAuthorization.RemoteEnvironmentAuthorization;
 
   return Effect.fnUntraced(
     function* (target: RelayConnectionTarget) {
       const authorized = yield* remote.authorizeDpop({
         expectedEnvironmentId: target.environmentId,
-        obtainBootstrap: Effect.gen(function* () {
-          const clerkToken = yield* session.clerkToken.pipe(
-            Effect.withSpan("relay.connection.cloudSessionToken.resolve"),
-          );
-          const deviceId = yield* identity.deviceId.pipe(
-            Effect.withSpan("relay.connection.deviceIdentity.resolve"),
-          );
-          const connected = yield* relay
-            .connectEnvironment({
-              clerkToken,
-              scopes: [RelayEnvironmentConnectScope],
-              environmentId: target.environmentId,
-              ...(Option.isSome(deviceId) ? { deviceId: deviceId.value } : {}),
-            })
-            .pipe(Effect.mapError(mapManagedRelayError));
-          if (connected.environmentId !== target.environmentId) {
-            return yield* environmentMismatchError({
-              expected: target.environmentId,
-              actual: connected.environmentId,
-            });
-          }
-          return connected;
-        }).pipe(Effect.withSpan("relay.connection.bootstrap.obtain")),
       });
       return {
         environmentId: authorized.environmentId,
diff --git a/packages/client-runtime/src/connection/supervisor.test.ts b/packages/client-runtime/src/connection/supervisor.test.ts
index 8f38633d55f6..2da7a68bd3ca 100644
--- a/packages/client-runtime/src/connection/supervisor.test.ts
+++ b/packages/client-runtime/src/connection/supervisor.test.ts
@@ -1,4 +1,4 @@
-import { EnvironmentId } from "@t3tools/contracts";
+import { AuthStandardClientScopes, EnvironmentId } from "@t3tools/contracts";
 import { RelayClientTracer } from "@t3tools/shared/relayTracing";
 import { describe, expect, it } from "@effect/vitest";
 import * as Deferred from "effect/Deferred";
@@ -11,12 +11,21 @@ import * as SubscriptionRef from "effect/SubscriptionRef";
 import * as TestClock from "effect/testing/TestClock";
 import * as Tracer from "effect/Tracer";
 
+import * as RemoteEnvironmentAuthorization from "../authorization/service.ts";
+import * as TokenStore from "../authorization/tokenStore.ts";
+import * as ClientCapabilities from "../platform/capabilities.ts";
+import {
+  ManagedRelayClient,
+  ManagedRelayDpopSigner,
+  ManagedRelayRequestTimeoutError,
+} from "../relay/managedRelay.ts";
+import { remoteHttpClientLayer } from "../rpc/http.ts";
 import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
+import { fetchEnvironmentSessionState } from "../state/session.ts";
 import type { ConnectionCatalogEntry } from "./catalog.ts";
 import * as Connectivity from "./connectivity.ts";
 import * as ConnectionDriver from "./driver.ts";
 import {
-  DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS,
   ConnectionBlockedError,
   ConnectionTransientError,
   PrimaryConnectionTarget,
@@ -30,6 +39,7 @@ import {
 import * as RpcSession from "../rpc/session.ts";
 import * as EnvironmentSupervisor from "./supervisor.ts";
 import * as ConnectionWakeups from "./wakeups.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 const TARGET = new PrimaryConnectionTarget({
   environmentId: EnvironmentId.make("environment-1"),
@@ -467,6 +477,35 @@ describe("EnvironmentSupervisor", () => {
     }).pipe(Effect.provide(TestClock.layer())),
   );
 
+  it.effect(
+    "shows a network hint for a stalled relay connection and clears it after recovery",
+    () =>
+      Effect.gen(function* () {
+        const harness = yield* makeHarness({
+          prepare: (attempt) =>
+            attempt === 1 ? Effect.never : Effect.succeed(PREPARED_CONNECTION),
+        });
+        const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
+          initiallyDesired: true,
+        }).pipe(Effect.provide(harness.dependencies));
+
+        yield* awaitState(supervisor.state, (state) => state.phase === "connecting");
+        yield* TestClock.adjust("15 seconds");
+        const failed = yield* awaitState(supervisor.state, (state) => state.phase === "backoff");
+        expect(failed.lastFailure?.message).toBe(
+          `Test environment did not respond during connection setup. ${NETWORK_BLOCKING_HINT}`,
+        );
+
+        yield* TestClock.adjust("3 seconds");
+        const recovered = yield* awaitState(
+          supervisor.state,
+          (state) => state.phase === "connected",
+        );
+        expect(recovered.lastFailure).toBeNull();
+        expect(yield* Ref.get(harness.prepareCount)).toBe(2);
+      }).pipe(Effect.provide(TestClock.layer())),
+  );
+
   it.effect("converts unexpected driver defects into retryable failures", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({
@@ -475,7 +514,7 @@ describe("EnvironmentSupervisor", () => {
             ? Effect.die(new Error("Native transport defect."))
             : Effect.succeed(PREPARED_CONNECTION),
       });
-      const supervisor = yield* EnvironmentSupervisor.make(TARGET_ENTRY, {
+      const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
         initiallyDesired: true,
       }).pipe(Effect.provide(harness.dependencies));
 
@@ -1097,183 +1136,220 @@ describe("EnvironmentSupervisor", () => {
     }),
   );
 
-  it.effect("hands off relay authorization after the replacement session is ready", () =>
+  it.effect("keeps a healthy relay session when its HTTP access token expires", () =>
     Effect.gen(function* () {
-      const tokenLifetimeMs = DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS * 2;
-      const replacementStarted = yield* Deferred.make<void>();
-      const releaseReplacement = yield* Deferred.make<void>();
       const harness = yield* makeHarness({
         prepare: (attempt) =>
-          attempt === 2
-            ? Effect.fail(transient("Authorization refresh failed."))
-            : Effect.succeed({
-                ...PREPARED_CONNECTION,
-                target: RELAY_TARGET,
-                httpAuthorization: {
-                  _tag: "Dpop",
-                  accessToken: `access-token-${attempt}`,
-                  expiresAtEpochMs: tokenLifetimeMs * attempt,
-                },
-              }),
-        ready: (attempt) =>
-          attempt === 2
-            ? Deferred.succeed(replacementStarted, undefined).pipe(
-                Effect.andThen(Deferred.await(releaseReplacement)),
-              )
-            : Effect.void,
+          Effect.succeed({
+            ...PREPARED_CONNECTION,
+            target: RELAY_TARGET,
+            httpAuthorization: {
+              _tag: "Dpop",
+              accessToken: `access-token-${attempt}`,
+              expiresAtEpochMs: 3_600_000 * attempt,
+            },
+          }),
       });
       const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
         initiallyDesired: true,
       }).pipe(Effect.provide(harness.dependencies));
 
       yield* awaitState(supervisor.state, (state) => state.phase === "connected");
-      const firstSession = Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session));
-      const firstPrepared = Option.getOrThrow(yield* SubscriptionRef.get(supervisor.prepared));
-      yield* TestClock.adjust(DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS - 1);
-      expect(yield* Ref.get(harness.sessionCount)).toBe(1);
+      const session = Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session));
 
-      yield* TestClock.adjust(1);
-      expect(yield* Ref.get(harness.prepareCount)).toBe(2);
-      expect(yield* Ref.get(harness.sessionCount)).toBe(1);
-      expect(yield* Ref.get(harness.releaseCount)).toBe(0);
-      yield* Effect.yieldNow;
-
-      yield* TestClock.adjust("2999 millis");
-      expect(yield* Ref.get(harness.prepareCount)).toBe(2);
-      yield* TestClock.adjust("1 milli");
-      yield* Deferred.await(replacementStarted);
+      yield* TestClock.adjust("2 hours");
 
-      expect(yield* Ref.get(harness.prepareCount)).toBe(3);
-      expect(yield* Ref.get(harness.sessionCount)).toBe(2);
+      expect(yield* Ref.get(harness.sessionCount)).toBe(1);
       expect(yield* Ref.get(harness.releaseCount)).toBe(0);
+      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session))).toBe(session);
       expect(yield* SubscriptionRef.get(supervisor.state)).toMatchObject({
         phase: "connected",
         generation: 1,
       });
-      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session))).toBe(firstSession);
-      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.prepared))).toBe(
-        firstPrepared,
-      );
-
-      yield* Deferred.succeed(releaseReplacement, undefined);
-      yield* awaitState(
-        supervisor.state,
-        (state) => state.phase === "connected" && state.generation === 2,
-      );
-
-      expect(yield* Ref.get(harness.releaseCount)).toBe(1);
-      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session))).not.toBe(
-        firstSession,
-      );
-      expect(
-        Option.getOrThrow(yield* SubscriptionRef.get(supervisor.prepared)).httpAuthorization,
-      ).toMatchObject({ accessToken: "access-token-3" });
     }).pipe(Effect.provide(TestClock.layer())),
   );
 
-  it.effect("cleans up timed-out replacements and an interrupted retry", () =>
+  it.effect("refreshes HTTP authorization without replacing the active relay session", () =>
     Effect.gen(function* () {
-      const tokenLifetimeMs = DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS * 2;
-      const replacementStarted = yield* Deferred.make<void>();
-      const retryStarted = yield* Deferred.make<void>();
-      const harness = yield* makeHarness({
-        prepare: (attempt) =>
-          Effect.succeed({
-            ...PREPARED_CONNECTION,
-            target: RELAY_TARGET,
-            httpAuthorization: {
-              _tag: "Dpop",
-              accessToken: `access-token-${attempt}`,
-              expiresAtEpochMs: tokenLifetimeMs * attempt,
-            },
+      const endpoint = {
+        httpBaseUrl: TARGET.httpBaseUrl,
+        wsBaseUrl: TARGET.wsBaseUrl,
+        providerKind: "cloudflare_tunnel" as const,
+      };
+      const token = yield* Ref.make(
+        Option.some(
+          new TokenStore.RemoteDpopAccessToken({
+            environmentId: TARGET.environmentId,
+            accountId: "test-account",
+            label: TARGET.label,
+            endpoint,
+            accessToken: "access-token-1",
+            expiresAtEpochMs: 3_600_000,
+            dpopThumbprint: "test-thumbprint",
           }),
-        ready: (attempt) => {
-          if (attempt === 2) {
-            return Deferred.succeed(replacementStarted, undefined).pipe(
-              Effect.andThen(Effect.never),
+        ),
+      );
+      const bootstrapFails = yield* Ref.make(false);
+      const bootstrapCalls = yield* Ref.make(0);
+      const httpPaths: Array<string> = [];
+      const sessionAuthorizations: Array<string | null> = [];
+      const fetchFn = ((input, init) => {
+        const request = new Request(input, init);
+        const pathname = new URL(request.url).pathname;
+        httpPaths.push(pathname);
+        switch (pathname) {
+          case "/.well-known/t3/environment":
+            return Promise.resolve(
+              Response.json({
+                environmentId: TARGET.environmentId,
+                label: TARGET.label,
+                platform: { os: "linux", arch: "x64" },
+                serverVersion: "0.0.0-test",
+                capabilities: { repositoryIdentity: true },
+              }),
+            );
+          case "/oauth/token":
+            return Promise.resolve(
+              Response.json({
+                access_token: "access-token-2",
+                issued_token_type: "urn:ietf:params:oauth:token-type:access_token",
+                token_type: "DPoP",
+                expires_in: 3_600,
+                scope: AuthStandardClientScopes.join(" "),
+              }),
+            );
+          case "/api/auth/websocket-ticket":
+            return Promise.resolve(
+              Response.json({
+                ticket: "ws-ticket",
+                expiresAt: "2026-09-04T01:00:00.000Z",
+              }),
+            );
+          case "/api/auth/session": {
+            const authorization = request.headers.get("authorization");
+            sessionAuthorizations.push(authorization);
+            return Promise.resolve(
+              Response.json({
+                authenticated: authorization === "DPoP access-token-2",
+                auth: {
+                  policy: "loopback-browser",
+                  bootstrapMethods: ["one-time-token"],
+                  sessionMethods: ["dpop-access-token"],
+                  sessionCookieName: "t3_session_test",
+                },
+                scopes: AuthStandardClientScopes,
+              }),
             );
           }
-          if (attempt === 3) {
-            return Deferred.succeed(retryStarted, undefined).pipe(Effect.andThen(Effect.never));
+          default:
+            return Promise.reject(new Error(`Unexpected HTTP request to ${request.url}`));
+        }
+      }) satisfies typeof fetch;
+      const signer = ManagedRelayDpopSigner.of({
+        thumbprint: Effect.succeed("test-thumbprint"),
+        createProof: () => Effect.succeed("test-proof"),
+      });
+      const unused = () => Effect.die("Unexpected relay operation.");
+      const relay = ManagedRelayClient.of({
+        relayUrl: "https://relay.example.test",
+        listEnvironments: unused,
+        listDevices: unused,
+        createEnvironmentLinkChallenge: unused,
+        linkEnvironment: unused,
+        unlinkEnvironment: unused,
+        getEnvironmentStatus: unused,
+        connectEnvironment: Effect.fn("TestConnectionHttp.connectEnvironment")(function* () {
+          yield* Ref.update(bootstrapCalls, (count) => count + 1);
+          if (yield* Ref.get(bootstrapFails)) {
+            return yield* new ManagedRelayRequestTimeoutError({
+              activity: "Relay environment connection",
+              timeoutMs: 6_000,
+              traceId: null,
+            });
           }
-          return Effect.void;
-        },
+          return {
+            environmentId: TARGET.environmentId,
+            endpoint,
+            credential: "relay-bootstrap",
+            expiresAt: "2026-09-04T01:00:00.000Z",
+          };
+        }),
+        registerDevice: unused,
+        unregisterDevice: unused,
+        registerLiveActivity: unused,
+        getAgentActivitySnapshot: unused,
+        resetTokenCache: Effect.void,
+      });
+      const httpLayer = remoteHttpClientLayer(fetchFn);
+      const remoteAuthorization = yield* RemoteEnvironmentAuthorization.make.pipe(
+        Effect.provide(
+          Layer.mergeAll(
+            httpLayer,
+            Layer.succeed(ManagedRelayDpopSigner, signer),
+            Layer.succeed(ManagedRelayClient, relay),
+            Layer.succeed(ClientCapabilities.CloudSession, {
+              identity: Effect.succeed(Option.some({ accountId: "test-account" })),
+              clerkToken: Effect.succeed("clerk-token"),
+            }),
+            Layer.succeed(ClientCapabilities.RelayDeviceIdentity, {
+              deviceId: Effect.succeed(Option.none()),
+            }),
+            TokenStore.layer({
+              get: () => Ref.get(token),
+              put: (value) => Ref.set(token, Option.some(value)),
+              remove: () => Ref.set(token, Option.none()),
+            }),
+            Layer.succeed(ClientCapabilities.ClientPresentation, {
+              metadata: { label: "Test client", deviceType: "desktop" },
+              scopes: AuthStandardClientScopes,
+            }),
+          ),
+        ),
+      );
+      const harness = yield* makeHarness({
+        prepare: () =>
+          remoteAuthorization
+            .authorizeDpop({ expectedEnvironmentId: TARGET.environmentId })
+            .pipe(Effect.map((prepared) => ({ ...prepared, target: RELAY_TARGET }))),
       });
       const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
         initiallyDesired: true,
       }).pipe(Effect.provide(harness.dependencies));
-
       yield* awaitState(supervisor.state, (state) => state.phase === "connected");
-      const firstSession = Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session));
-      yield* TestClock.adjust(DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS);
-      yield* Deferred.await(replacementStarted);
-
-      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session))).toBe(firstSession);
+      const session = Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session));
+      const prepared = Option.getOrThrow(yield* SubscriptionRef.get(supervisor.prepared));
+      const readSession = fetchEnvironmentSessionState({
+        prepared,
+        signer: Option.some(signer),
+        remoteAuthorization: Option.some(remoteAuthorization),
+      }).pipe(Effect.provide(httpLayer));
+
+      yield* TestClock.adjust("2 hours");
+      expect((yield* readSession).authenticated).toBe(true);
+      expect(sessionAuthorizations).toEqual(["DPoP access-token-2"]);
+      expect(yield* Ref.get(bootstrapCalls)).toBe(1);
+      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session))).toBe(session);
       expect(yield* Ref.get(harness.releaseCount)).toBe(0);
-
-      yield* TestClock.adjust("15 seconds");
-      yield* Effect.yieldNow;
-      expect(yield* Ref.get(harness.releaseCount)).toBe(1);
-      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session))).toBe(firstSession);
       expect(yield* SubscriptionRef.get(supervisor.state)).toMatchObject({
         phase: "connected",
         generation: 1,
       });
 
-      yield* TestClock.adjust("3 seconds");
-      yield* Deferred.await(retryStarted);
-      expect(yield* Ref.get(harness.sessionCount)).toBe(3);
-      expect(yield* Ref.get(harness.releaseCount)).toBe(1);
-      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session))).toBe(firstSession);
-
-      yield* supervisor.disconnect;
-      yield* awaitState(supervisor.state, (state) => state.phase === "available");
-
-      expect(yield* Ref.get(harness.releaseCount)).toBe(3);
-      expect(Option.isNone(yield* SubscriptionRef.get(supervisor.session))).toBe(true);
-      expect(Option.isNone(yield* SubscriptionRef.get(supervisor.prepared))).toBe(true);
-    }).pipe(Effect.provide(TestClock.layer())),
-  );
-
-  it.effect("does not keep a relay session past its authorization expiry", () =>
-    Effect.gen(function* () {
-      const tokenLifetimeMs = DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS * 2;
-      const harness = yield* makeHarness({
-        prepare: (attempt) =>
-          attempt === 1
-            ? Effect.succeed({
-                ...PREPARED_CONNECTION,
-                target: RELAY_TARGET,
-                httpAuthorization: {
-                  _tag: "Dpop",
-                  accessToken: "access-token-1",
-                  expiresAtEpochMs: tokenLifetimeMs,
-                },
-              })
-            : Effect.fail(transient("Authorization refresh failed.")),
-      });
-      const supervisor = yield* EnvironmentSupervisor.make(RELAY_ENTRY, {
-        initiallyDesired: true,
-      }).pipe(Effect.provide(harness.dependencies));
-
-      yield* awaitState(supervisor.state, (state) => state.phase === "connected");
-      yield* TestClock.adjust(DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS);
-      yield* Effect.yieldNow;
-      for (const delay of [3_000, 4_000, 8_000, 16_000, 16_000, 13_000]) {
-        yield* TestClock.adjust(delay);
-        yield* Effect.yieldNow;
-      }
-
-      yield* awaitState(supervisor.state, (state) => state.phase === "backoff");
-
+      yield* TestClock.adjust("2 hours");
+      yield* Ref.set(bootstrapFails, true);
+      const failure = yield* readSession.pipe(Effect.flip);
+      expect(failure._tag).toBe("RemoteEnvironmentAuthFetchError");
+      expect(yield* Ref.get(bootstrapCalls)).toBe(2);
+      expect(sessionAuthorizations).toEqual(["DPoP access-token-2"]);
+      expect(httpPaths.filter((path) => path === "/api/auth/websocket-ticket")).toHaveLength(1);
+      expect(httpPaths.filter((path) => path === "/oauth/token")).toHaveLength(1);
       expect(yield* Ref.get(harness.sessionCount)).toBe(1);
-      expect(yield* Ref.get(harness.releaseCount)).toBe(1);
+      expect(yield* Ref.get(harness.releaseCount)).toBe(0);
+      expect(Option.getOrThrow(yield* SubscriptionRef.get(supervisor.session))).toBe(session);
       expect(yield* SubscriptionRef.get(supervisor.state)).toMatchObject({
-        phase: "backoff",
+        phase: "connected",
         generation: 1,
       });
-      expect(Option.isNone(yield* SubscriptionRef.get(supervisor.session))).toBe(true);
-      expect(Option.isNone(yield* SubscriptionRef.get(supervisor.prepared))).toBe(true);
     }).pipe(Effect.provide(TestClock.layer())),
   );
 
diff --git a/packages/client-runtime/src/connection/supervisor.ts b/packages/client-runtime/src/connection/supervisor.ts
index 9d5452344499..0246a21397f4 100644
--- a/packages/client-runtime/src/connection/supervisor.ts
+++ b/packages/client-runtime/src/connection/supervisor.ts
@@ -18,7 +18,6 @@ import type { ConnectionCatalogEntry } from "./catalog.ts";
 import * as Connectivity from "./connectivity.ts";
 import * as ConnectionDriver from "./driver.ts";
 import {
-  DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS,
   type ConnectionAttemptError,
   type ConnectionTarget,
   ConnectionTransientError,
@@ -28,6 +27,7 @@ import {
 } from "./model.ts";
 import * as RpcSession from "../rpc/session.ts";
 import { safeErrorLogAttributes } from "../errors/safeLog.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import * as ConnectionWakeups from "./wakeups.ts";
 
 const RETRY_DELAYS_MS = [3_000, 4_000, 8_000, 16_000] as const;
@@ -60,24 +60,16 @@ interface TracedAttemptFailure {
   readonly attemptSpan: Option.Option<Tracer.Span>;
 }
 
-interface ScopedConnection {
-  readonly attemptSpan: Option.Option<Tracer.Span>;
-  readonly lease: ConnectionDriver.EnvironmentConnectionLease;
-  readonly scope: Scope.Closeable;
-}
-
 type AttemptOutcome =
   | {
       readonly _tag: "Interrupted";
       readonly established: boolean;
-      readonly generation: number;
       readonly stable: boolean;
       readonly resetRetry: boolean;
     }
   | {
       readonly _tag: "Failure";
       readonly established: boolean;
-      readonly generation: number;
       readonly stable: boolean;
       readonly failure: TracedAttemptFailure;
     };
@@ -85,26 +77,17 @@ type AttemptOutcome =
 type EstablishmentEvent =
   | {
       readonly _tag: "Completed";
-      readonly exit: Exit.Exit<ScopedConnection, TracedAttemptFailure>;
+      readonly exit: Exit.Exit<
+        {
+          readonly attemptSpan: Option.Option<Tracer.Span>;
+          readonly lease: ConnectionDriver.EnvironmentConnectionLease;
+        },
+        TracedAttemptFailure
+      >;
     }
   | { readonly _tag: "Interrupted"; readonly resetRetry: boolean }
   | { readonly _tag: "TimedOut" };
 
-type ReplacementPreparationEvent =
-  | { readonly _tag: "Completed"; readonly exit: Exit.Exit<ScopedConnection, TracedAttemptFailure> }
-  | { readonly _tag: "TimedOut" }
-  | { readonly _tag: "AuthorizationExpired" };
-
-type ConnectedLeaseEvent =
-  | {
-      readonly _tag: "ActiveCompleted";
-      readonly exit: Exit.Exit<boolean, TracedAttemptFailure>;
-    }
-  | {
-      readonly _tag: "ReplacementCompleted";
-      readonly exit: Exit.Exit<Option.Option<ScopedConnection>, TracedAttemptFailure>;
-    };
-
 function exitUnlessInterrupted<A, E, R>(
   effect: Effect.Effect<A, E, R>,
 ): Effect.Effect<Exit.Exit<A, E>, never, R> {
@@ -185,18 +168,16 @@ function failureFromExit<A>(
   target: ConnectionTarget,
   exit: Exit.Exit<A, TracedAttemptFailure>,
   established: boolean,
-  generation: number,
   stable: boolean,
 ): AttemptOutcome {
   if (Exit.isSuccess(exit) || Cause.hasInterruptsOnly(exit.cause)) {
-    return { _tag: "Interrupted", established, generation, stable, resetRetry: false };
+    return { _tag: "Interrupted", established, stable, resetRetry: false };
   }
   const typedFailure = exit.cause.reasons.find(Cause.isFailReason);
   if (typedFailure) {
     return {
       _tag: "Failure",
       established,
-      generation,
       stable,
       failure: typedFailure.error,
     };
@@ -204,7 +185,6 @@ function failureFromExit<A>(
   return {
     _tag: "Failure",
     established,
-    generation,
     stable,
     failure: {
       error: new ConnectionTransientError({
@@ -241,6 +221,9 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
   | ConnectionWakeups.ConnectionWakeups
 > {
   const target = entry.target;
+  const setupTimeoutDetail = `${target.label} did not respond during connection setup.${
+    target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : ""
+  }`;
   yield* annotateTarget(target);
 
   const connectivity = yield* Connectivity.Connectivity;
@@ -309,10 +292,9 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
     attempt: number,
     generation: number,
     lastFailure: ConnectionAttemptError | null,
-    publishProgress: boolean,
   ) {
     return yield* driver.connect(entry, (progress) =>
-      publishProgress ? reportProgress(attempt, generation, lastFailure, progress) : Effect.void,
+      reportProgress(attempt, generation, lastFailure, progress),
     );
   });
 
@@ -363,17 +345,16 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
     generation: number,
     lastFailure: ConnectionAttemptError | null,
     pendingRetry: Option.Option<PendingRetryTrace>,
-    publishProgress: boolean,
   ) {
     if (target._tag === "RelayConnectionTarget") {
       return yield* traceRelayEstablishment(
-        establishConnection(attempt, generation, lastFailure, publishProgress),
+        establishConnection(attempt, generation, lastFailure),
         attempt,
         generation,
         pendingRetry,
       );
     }
-    return yield* establishConnection(attempt, generation, lastFailure, publishProgress).pipe(
+    return yield* establishConnection(attempt, generation, lastFailure).pipe(
       Effect.map((lease) => ({
         attemptSpan: Option.none<Tracer.Span>(),
         lease,
@@ -385,37 +366,6 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
     );
   });
 
-  const forkScopedTracedConnection = Effect.fnUntraced(function* (
-    attempt: number,
-    generation: number,
-    lastFailure: ConnectionAttemptError | null,
-    pendingRetry: Option.Option<PendingRetryTrace>,
-    publishProgress: boolean,
-  ) {
-    const parentScope = yield* Scope.Scope;
-    return yield* Effect.uninterruptibleMask((restore) =>
-      Effect.gen(function* () {
-        const connectionScope = yield* Scope.fork(parentScope, "sequential");
-        const fiber = yield* restore(
-          establishTracedConnection(
-            attempt,
-            generation,
-            lastFailure,
-            pendingRetry,
-            publishProgress,
-          ).pipe(
-            Scope.provide(connectionScope),
-            Effect.map(
-              (established) =>
-                ({ ...established, scope: connectionScope }) satisfies ScopedConnection,
-            ),
-          ),
-        ).pipe(Effect.forkChild);
-        return { fiber, scope: connectionScope };
-      }),
-    );
-  });
-
   const waitForEstablishmentInterrupt = Effect.fnUntraced(function* () {
     for (;;) {
       const next = yield* Queue.take(signals);
@@ -537,136 +487,17 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
     }
   });
 
-  const waitForAuthorizationDeadline = Effect.fnUntraced(function* (
-    preparedConnection: PreparedConnection,
-    skewMs: number,
-  ) {
-    const authorization = preparedConnection.httpAuthorization;
-    if (authorization?._tag !== "Dpop") {
-      return yield* Effect.never;
-    }
-    const now = yield* Clock.currentTimeMillis;
-    yield* Effect.sleep(Math.max(0, authorization.expiresAtEpochMs - now - skewMs));
-  });
-
-  const waitForActiveCompletion = Effect.fnUntraced(function* (active: ScopedConnection) {
-    const exit = yield* exitUnlessInterrupted(
-      Effect.raceAllFirst([
-        active.lease.session.closed.pipe(
-          Effect.mapError((error): TracedAttemptFailure => ({
-            error,
-            attemptSpan: active.attemptSpan,
-          })),
-        ),
-        monitorConnectedLease(active.lease).pipe(
-          Effect.mapError((error): TracedAttemptFailure => ({
-            error,
-            attemptSpan: active.attemptSpan,
-          })),
-        ),
-      ]),
-    );
-    return { _tag: "ActiveCompleted", exit } satisfies ConnectedLeaseEvent;
-  });
-
-  const prepareReplacement = Effect.fnUntraced(function* (
-    active: ScopedConnection,
-    generation: number,
-  ) {
-    yield* waitForAuthorizationDeadline(active.lease.prepared, DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS);
-    yield* Effect.logDebug(
-      "Preparing a replacement environment connection before its DPoP token expires.",
-    );
-
-    let failureCount = 0;
-    for (;;) {
-      const candidate = yield* forkScopedTracedConnection(
-        failureCount + 1,
-        generation,
-        null,
-        Option.none(),
-        false,
-      );
-      const replacement = yield* Effect.raceAllFirst([
-        Fiber.await(candidate.fiber).pipe(
-          Effect.map((exit): ReplacementPreparationEvent => ({ _tag: "Completed", exit })),
-        ),
-        waitForAuthorizationDeadline(active.lease.prepared, 0).pipe(
-          Effect.as<ReplacementPreparationEvent>({ _tag: "AuthorizationExpired" }),
-        ),
-        Effect.sleep(CONNECTION_ESTABLISHMENT_TIMEOUT).pipe(
-          Effect.as<ReplacementPreparationEvent>({ _tag: "TimedOut" }),
-        ),
-      ]);
-
-      if (replacement._tag !== "Completed") {
-        yield* Fiber.interrupt(candidate.fiber);
-        yield* Fiber.await(candidate.fiber);
-        yield* Scope.close(candidate.scope, Exit.void).pipe(Effect.ignore);
-      } else if (Exit.isFailure(replacement.exit)) {
-        yield* Scope.close(candidate.scope, Exit.void).pipe(Effect.ignore);
-      }
-      if (replacement._tag === "AuthorizationExpired") {
-        return Option.none<ScopedConnection>();
-      }
-      if (replacement._tag === "Completed" && Exit.isSuccess(replacement.exit)) {
-        return Option.some(replacement.exit.value);
-      }
-
-      let replacementError: ConnectionTransientError;
-      if (replacement._tag === "Completed") {
-        if (Exit.isSuccess(replacement.exit)) {
-          return yield* Effect.die("A successful replacement was not installed.");
-        }
-        const failure = Cause.findErrorOption(replacement.exit.cause);
-        if (Option.isNone(failure) || failure.value.error._tag === "ConnectionBlockedError") {
-          return yield* Effect.failCause(replacement.exit.cause);
-        }
-        replacementError = failure.value.error;
-      } else {
-        replacementError = new ConnectionTransientError({
-          reason: "timeout",
-          detail: `${target.label} did not respond during connection setup.`,
-        });
-      }
-
-      const retryDelay = retryDelayMs(failureCount);
-      failureCount += 1;
-      yield* Effect.logWarning(
-        "Could not prepare a replacement environment connection; keeping the active connection.",
-      ).pipe(
-        Effect.annotateLogs({
-          "authorization.refresh.retry_delay_ms": retryDelay,
-          ...safeErrorLogAttributes(replacementError),
-        }),
-      );
-      const retryBeforeExpiry = yield* Effect.raceFirst(
-        Effect.sleep(retryDelay).pipe(Effect.as(true)),
-        waitForAuthorizationDeadline(active.lease.prepared, 0).pipe(Effect.as(false)),
-      );
-      if (!retryBeforeExpiry) {
-        return Option.none<ScopedConnection>();
-      }
-    }
-  });
-
   const runAttempt = Effect.fnUntraced(function* (
     attempt: number,
-    previousGeneration: number,
+    generation: number,
     lastFailure: ConnectionAttemptError | null,
     pendingRetry: Option.Option<PendingRetryTrace>,
   ) {
-    const initialGeneration = previousGeneration + 1;
     yield* SubscriptionRef.set(prepared, Option.none());
-    const initial = yield* forkScopedTracedConnection(
-      attempt,
-      initialGeneration,
-      lastFailure,
-      pendingRetry,
-      true,
-    );
     const establishment = yield* Effect.raceAllFirst([
-      Fiber.await(initial.fiber).pipe(
+      exitUnlessInterrupted(
+        establishTracedConnection(attempt, generation, lastFailure, pendingRetry),
+      ).pipe(
         Effect.map((exit): EstablishmentEvent => ({
           _tag: "Completed",
           exit,
@@ -683,18 +514,10 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       ),
     ]);
 
-    if (establishment._tag !== "Completed") {
-      yield* Fiber.interrupt(initial.fiber);
-      yield* Fiber.await(initial.fiber);
-      yield* Scope.close(initial.scope, Exit.void).pipe(Effect.ignore);
-    } else if (Exit.isFailure(establishment.exit)) {
-      yield* Scope.close(initial.scope, Exit.void).pipe(Effect.ignore);
-    }
     if (establishment._tag === "Interrupted") {
       return {
         _tag: "Interrupted",
         established: false,
-        generation: previousGeneration,
         stable: false,
         resetRetry: establishment.resetRetry,
       } satisfies AttemptOutcome;
@@ -703,12 +526,11 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       return {
         _tag: "Failure",
         established: false,
-        generation: previousGeneration,
         stable: false,
         failure: {
           error: new ConnectionTransientError({
             reason: "timeout",
-            detail: `${target.label} did not respond during connection setup.`,
+            detail: setupTimeoutDetail,
           }),
           attemptSpan: Option.none(),
         },
@@ -718,7 +540,7 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       const isUnexpectedDefect =
         !Cause.hasInterruptsOnly(establishment.exit.cause) &&
         !establishment.exit.cause.reasons.some(Cause.isFailReason);
-      const outcome = failureFromExit(target, establishment.exit, false, previousGeneration, false);
+      const outcome = failureFromExit(target, establishment.exit, false, false);
       if (isUnexpectedDefect) {
         const defect = establishment.exit.cause.reasons.find(Cause.isDieReason)?.defect;
         yield* Effect.logError("Connection attempt failed with an unexpected defect.").pipe(
@@ -733,20 +555,18 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       return outcome;
     }
 
+    const active = establishment.exit.value;
     const currentIntent = yield* Ref.get(intent);
     if (!currentIntent.desired || currentIntent.network === "offline") {
       return {
         _tag: "Interrupted",
         established: false,
-        generation: previousGeneration,
         stable: false,
         resetRetry: false,
       } satisfies AttemptOutcome;
     }
 
     const connectedAt = yield* Clock.currentTimeMillis;
-    let active = establishment.exit.value;
-    let activeGeneration = initialGeneration;
     yield* SubscriptionRef.set(prepared, Option.some(active.lease.prepared));
     yield* SubscriptionRef.set(session, Option.some(active.lease.session));
     yield* setState({
@@ -755,78 +575,35 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       phase: "connected",
       stage: null,
       attempt,
-      generation: activeGeneration,
+      generation,
       lastFailure: null,
       retryAt: null,
     });
 
-    for (;;) {
-      const connectedEvent = yield* Effect.raceAllFirst([
-        waitForActiveCompletion(active),
-        exitUnlessInterrupted(prepareReplacement(active, activeGeneration + 1)).pipe(
-          Effect.map((exit): ConnectedLeaseEvent => ({ _tag: "ReplacementCompleted", exit })),
-        ),
-      ]);
-      const stable = (yield* Clock.currentTimeMillis) - connectedAt >= BACKOFF_RESET_AFTER_MS;
-      if (connectedEvent._tag === "ActiveCompleted") {
-        if (Exit.isSuccess(connectedEvent.exit)) {
-          return {
-            _tag: "Interrupted",
-            established: true,
-            generation: activeGeneration,
-            stable,
-            resetRetry: connectedEvent.exit.value,
-          } satisfies AttemptOutcome;
-        }
-        return failureFromExit(target, connectedEvent.exit, true, activeGeneration, stable);
-      }
-      if (Exit.isFailure(connectedEvent.exit)) {
-        return failureFromExit(target, connectedEvent.exit, true, activeGeneration, stable);
-      }
-      if (Option.isNone(connectedEvent.exit.value)) {
-        return {
-          _tag: "Interrupted",
-          established: true,
-          generation: activeGeneration,
-          stable,
-          resetRetry: true,
-        } satisfies AttemptOutcome;
-      }
-
-      const candidate = connectedEvent.exit.value.value;
-      const replacementIntent = yield* Ref.get(intent);
-      if (!replacementIntent.desired || replacementIntent.network === "offline") {
-        yield* Scope.close(candidate.scope, Exit.void).pipe(Effect.ignore);
-        return {
-          _tag: "Interrupted",
-          established: true,
-          generation: activeGeneration,
-          stable,
-          resetRetry: false,
-        } satisfies AttemptOutcome;
-      }
-
-      const previous = active;
-      yield* Effect.uninterruptible(
-        Effect.gen(function* () {
-          active = candidate;
-          activeGeneration += 1;
-          yield* SubscriptionRef.set(prepared, Option.some(active.lease.prepared));
-          yield* SubscriptionRef.set(session, Option.some(active.lease.session));
-          yield* setState({
-            desired: true,
-            network: replacementIntent.network,
-            phase: "connected",
-            stage: null,
-            attempt: 1,
-            generation: activeGeneration,
-            lastFailure: null,
-            retryAt: null,
-          });
-          yield* Scope.close(previous.scope, Exit.void).pipe(Effect.ignore);
-        }),
-      );
+    const connectedExit = yield* Effect.raceFirst(
+      active.lease.session.closed.pipe(
+        Effect.mapError((error): TracedAttemptFailure => ({
+          error,
+          attemptSpan: active.attemptSpan,
+        })),
+      ),
+      monitorConnectedLease(active.lease).pipe(
+        Effect.mapError((error): TracedAttemptFailure => ({
+          error,
+          attemptSpan: active.attemptSpan,
+        })),
+      ),
+    ).pipe(exitUnlessInterrupted);
+    const connectedForMs = (yield* Clock.currentTimeMillis) - connectedAt;
+    if (Exit.isSuccess(connectedExit)) {
+      return {
+        _tag: "Interrupted",
+        established: true,
+        stable: connectedForMs >= BACKOFF_RESET_AFTER_MS,
+        resetRetry: connectedExit.value,
+      } satisfies AttemptOutcome;
     }
+    return failureFromExit(target, connectedExit, true, connectedForMs >= BACKOFF_RESET_AFTER_MS);
   }, Effect.ensuring(clearLease));
 
   const waitForRetrySignal = Effect.fnUntraced(function* (delayMs: number) {
@@ -891,14 +668,15 @@ export const make = Effect.fn("EnvironmentSupervisor.make")(function* (
       }
 
       const attempt = failureCount + 1;
+      const nextGeneration = generation + 1;
       const outcome: AttemptOutcome = yield* Effect.scoped(
-        runAttempt(attempt, generation, latestFailure, pendingRetry),
+        runAttempt(attempt, nextGeneration, latestFailure, pendingRetry),
       );
       // Consumed on every iteration so a stale marker can never leak into a
       // later, unrelated failure.
       const failedWakeProbe = yield* Ref.getAndSet(wakeProbeFailed, false);
-      generation = outcome.generation;
       if (outcome.established) {
+        generation = nextGeneration;
         if (outcome.stable) {
           resetRetryLadder();
           latestFailure = null;
diff --git a/packages/client-runtime/src/environment/knownEnvironment.test.ts b/packages/client-runtime/src/environment/knownEnvironment.test.ts
index 66bbb1df7e91..032be152fdbc 100644
--- a/packages/client-runtime/src/environment/knownEnvironment.test.ts
+++ b/packages/client-runtime/src/environment/knownEnvironment.test.ts
@@ -6,7 +6,6 @@ import {
   parseScopedProjectKey,
   parseScopedThreadKey,
   scopedProjectKey,
-  scopedRefKey,
   scopedThreadKey,
   scopeProjectRef,
   scopeThreadRef,
@@ -40,8 +39,6 @@ describe("scoped refs", () => {
   const threadRef = scopeThreadRef(environmentId, ThreadId.make("thread-1"));
 
   it("builds stable scoped project and thread keys", () => {
-    expect(scopedRefKey(projectRef)).toBe("environment-test:project-1");
-    expect(scopedRefKey(threadRef)).toBe("environment-test:thread-1");
     expect(scopedProjectKey(projectRef)).toBe("environment-test:project-1");
     expect(scopedThreadKey(threadRef)).toBe("environment-test:thread-1");
   });
diff --git a/packages/client-runtime/src/environment/scoped.ts b/packages/client-runtime/src/environment/scoped.ts
index 354c548c02de..7894c7ba5329 100644
--- a/packages/client-runtime/src/environment/scoped.ts
+++ b/packages/client-runtime/src/environment/scoped.ts
@@ -22,7 +22,7 @@ export function scopeThreadRef(
   return { environmentId, threadId };
 }
 
-export function scopedRefKey(ref: ScopedProjectRef | ScopedThreadRef): string {
+function scopedRefKey(ref: ScopedProjectRef | ScopedThreadRef): string {
   const localId = "projectId" in ref ? ref.projectId : ref.threadId;
   return `${ref.environmentId}:${localId}`;
 }
diff --git a/packages/client-runtime/src/errors/network.ts b/packages/client-runtime/src/errors/network.ts
new file mode 100644
index 000000000000..1e726bdd4d98
--- /dev/null
+++ b/packages/client-runtime/src/errors/network.ts
@@ -0,0 +1,4 @@
+// A failed request cannot distinguish filtering from an outage. Keep this a
+// possible cause, and suggest a way to check without changing server settings.
+export const NETWORK_BLOCKING_HINT =
+  "Your DNS or firewall may be blocking T3 Connect. Try another network, such as a phone hotspot.";
diff --git a/packages/client-runtime/src/markdownLinks.test.ts b/packages/client-runtime/src/markdownLinks.test.ts
index cf8f9ae2d16e..4aea947b87d6 100644
--- a/packages/client-runtime/src/markdownLinks.test.ts
+++ b/packages/client-runtime/src/markdownLinks.test.ts
@@ -3,7 +3,6 @@ import { describe, expect, it } from "vite-plus/test";
 import {
   fileBasename,
   inlineCodeFilePathCandidate,
-  isConventionalFilePosition,
   parseFileUrlHref,
   parseMarkdownFileLink,
   splitFilePathPosition,
@@ -28,15 +27,6 @@ describe("inlineCodeFilePathCandidate", () => {
   });
 });
 
-describe("isConventionalFilePosition", () => {
-  it("distinguishes extensionless file locations from labels and ports", () => {
-    expect(isConventionalFilePosition("Dockerfile:8:2")).toBe(true);
-    expect(isConventionalFilePosition("Makefile")).toBe(false);
-    expect(isConventionalFilePosition("TODO:12")).toBe(false);
-    expect(isConventionalFilePosition("port:3000")).toBe(false);
-  });
-});
-
 describe("parseFileUrlHref", () => {
   it.each([
     ["file:///Users/julius/project/src/main.ts#L42", "/Users/julius/project/src/main.ts", "#L42"],
@@ -160,7 +150,17 @@ describe("workspaceRelativeFilePath", () => {
     ["/repo/project/src/main.ts", "/repo/project/", "src/main.ts"],
     ["C:\\Users\\mike\\t3code\\apps\\web\\a.ts", "C:/Users/mike/t3code", "apps/web/a.ts"],
     ["/C:/Users/mike/t3code/apps/web/a.ts", "C:/Users/mike/t3code", "apps/web/a.ts"],
-    ["/Repo/Project/src/main.ts", "/repo/project", "src/main.ts"],
+    ["/Repo/Project/src/main.ts", "/repo/project", null],
+    ["/tmp/case/project/probe.txt", "/tmp/case/Project", null],
+    ["//tmp/case/project/probe.txt", "//tmp/case/Project", null],
+    ["/tmp/case/Project/probe.txt", "/tmp/case/Project", "probe.txt"],
+    ["C:/USERS/mike/t3code/main.ts", "c:/users/MIKE/t3code", "main.ts"],
+    ["/C:/USERS/mike/t3code/main.ts", "/c:/users/MIKE/t3code", "main.ts"],
+    ["\\\\server\\share\\PROJECT\\main.ts", "\\\\Server\\Share\\Project", "main.ts"],
+    ["/tmp/repo/file.ts", "/", "tmp/repo/file.ts"],
+    ["C:/Users/MIKE/main.ts", "c:/", "Users/MIKE/main.ts"],
+    ["\\\\server\\SHARE\\file.ts", "\\\\Server\\Share\\", "file.ts"],
+    ["/tmp/repo/file.ts ", "/tmp/repo", "file.ts "],
     ["/tmp/report.ts", "/repo/project", null],
     ["/repo/project-two/a.ts", "/repo/project", null],
     ["/repo/project/a.ts", undefined, null],
diff --git a/packages/client-runtime/src/markdownLinks.ts b/packages/client-runtime/src/markdownLinks.ts
index 81cce1fd7eee..29a337e49c42 100644
--- a/packages/client-runtime/src/markdownLinks.ts
+++ b/packages/client-runtime/src/markdownLinks.ts
@@ -15,7 +15,6 @@ const INLINE_CODE_DISQUALIFIER_PATTERN = /[\s`]/;
 const PATH_SEPARATOR_PATTERN = /[\\/]/;
 const FILE_EXTENSION_PATTERN = /\.[A-Za-z0-9_-]+$/;
 const NUMERIC_DOTTED_PATTERN = /^\d+(?:\.\d+)+$/;
-const BARE_EXTENSIONLESS_POSITION_PATTERN = /^[A-Za-z0-9_-]+(?::\d+){1,2}$/;
 // Standard OS and dev-container roots; deliberately excludes app-route-ish
 // prefixes like /app/ or /chat/ so SPA routes never read as files.
 const POSIX_FILE_ROOT_PREFIXES = [
@@ -152,14 +151,6 @@ function looksLikeHostname(segment: string, hasPosition: boolean): boolean {
   return !hasPosition && COUNTRY_HOSTNAME_TLDS.has(lastLabel);
 }
 
-/** Recognizes conventional extensionless filenames with an explicit line position. */
-export function isConventionalFilePosition(path: string): boolean {
-  return (
-    BARE_EXTENSIONLESS_POSITION_PATTERN.test(path) &&
-    EXTENSIONLESS_FILE_NAMES.has(path.replace(POSITION_SUFFIX_PATTERN, ""))
-  );
-}
-
 /**
  * Picks path-shaped inline code for the client's markdown file-link resolver.
  * It does not resolve paths or turn plain prose and fenced code into links.
@@ -342,6 +333,9 @@ export function workspaceRelativeFilePath(
   const normalizedRoot = stripSlashPrefixedWindowsDrive(
     workspaceRoot.replaceAll("\\", "/"),
   ).replace(/\/+$/, "");
-  if (!normalizedPath.toLowerCase().startsWith(`${normalizedRoot.toLowerCase()}/`)) return null;
+  const caseInsensitive = isWindowsAbsolutePath(stripSlashPrefixedWindowsDrive(workspaceRoot));
+  const pathForCompare = caseInsensitive ? normalizedPath.toLowerCase() : normalizedPath;
+  const rootForCompare = caseInsensitive ? normalizedRoot.toLowerCase() : normalizedRoot;
+  if (!pathForCompare.startsWith(`${rootForCompare}/`)) return null;
   return normalizedPath.slice(normalizedRoot.length + 1);
 }
diff --git a/packages/client-runtime/src/platform/capabilities.ts b/packages/client-runtime/src/platform/capabilities.ts
index a20b7d404b2f..bc793b00565d 100644
--- a/packages/client-runtime/src/platform/capabilities.ts
+++ b/packages/client-runtime/src/platform/capabilities.ts
@@ -21,9 +21,15 @@ export interface ProvisionedSshEnvironment extends PreparedSshEnvironment {
   readonly label: string;
 }
 
+/** Stable for one signed-in session, including same-account token refreshes. */
+export interface CloudSessionIdentity {
+  readonly accountId: string;
+}
+
 export class CloudSession extends Context.Service<
   CloudSession,
   {
+    readonly identity: Effect.Effect<Option.Option<CloudSessionIdentity>>;
     readonly clerkToken: Effect.Effect<string, ConnectionAttemptError>;
   }
 >()("@t3tools/client-runtime/platform/capabilities/CloudSession") {}
diff --git a/packages/client-runtime/src/platform/storageDocument.test.ts b/packages/client-runtime/src/platform/storageDocument.test.ts
index 8ad6b81e12b4..c9ab41e3bf51 100644
--- a/packages/client-runtime/src/platform/storageDocument.test.ts
+++ b/packages/client-runtime/src/platform/storageDocument.test.ts
@@ -1,5 +1,6 @@
 import { EnvironmentId } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
+import * as Schema from "effect/Schema";
 
 import * as TokenStore from "../authorization/tokenStore.ts";
 import {
@@ -16,13 +17,19 @@ import {
   SshConnectionTarget,
 } from "../connection/model.ts";
 import {
+  ConnectionCatalogDocument,
   EMPTY_CONNECTION_CATALOG_DOCUMENT,
+  putRemoteDpopTokenInCatalog,
   registerConnectionInCatalog,
   removeConnectionFromCatalog,
 } from "./storageDocument.ts";
 
 const ENVIRONMENT_ID = EnvironmentId.make("environment-1");
 
+const RELAY_TARGET = new RelayConnectionTarget({
+  environmentId: ENVIRONMENT_ID,
+  label: "Remote",
+});
 const BEARER_TARGET = new BearerConnectionTarget({
   environmentId: ENVIRONMENT_ID,
   label: "Remote",
@@ -52,6 +59,26 @@ const REMOTE_TOKEN = new TokenStore.RemoteDpopAccessToken({
 });
 
 describe("ConnectionCatalogDocument", () => {
+  it.each([
+    { name: "legacy", accountId: undefined },
+    { name: "account-bound", accountId: "account-1" },
+  ])("round-trips a catalog containing a $name DPoP token", ({ accountId }) => {
+    const token = new TokenStore.RemoteDpopAccessToken({
+      ...REMOTE_TOKEN,
+      ...(accountId === undefined ? {} : { accountId }),
+    });
+    const document = {
+      ...EMPTY_CONNECTION_CATALOG_DOCUMENT,
+      targets: [RELAY_TARGET],
+      remoteDpopTokens: [token],
+    };
+    const schema = Schema.fromJsonString(ConnectionCatalogDocument);
+    const restored = Schema.decodeUnknownSync(schema)(Schema.encodeSync(schema)(document));
+
+    expect(restored).toEqual(document);
+    expect(restored.remoteDpopTokens[0]?.accountId).toBe(accountId);
+  });
+
   it("registers a bearer connection as one catalog mutation", () => {
     const document = registerConnectionInCatalog(
       EMPTY_CONNECTION_CATALOG_DOCUMENT,
@@ -117,6 +144,65 @@ describe("ConnectionCatalogDocument", () => {
     );
   });
 
+  it("stores a DPoP token for a registered relay environment", () => {
+    const registered = registerConnectionInCatalog(
+      EMPTY_CONNECTION_CATALOG_DOCUMENT,
+      new RelayConnectionRegistration({ target: RELAY_TARGET }),
+    );
+
+    expect(putRemoteDpopTokenInCatalog(registered, REMOTE_TOKEN)).toEqual({
+      ...registered,
+      remoteDpopTokens: [REMOTE_TOKEN],
+    });
+  });
+
+  it("ignores a late DPoP token after the environment is removed", () => {
+    const registered = registerConnectionInCatalog(
+      EMPTY_CONNECTION_CATALOG_DOCUMENT,
+      new RelayConnectionRegistration({ target: RELAY_TARGET }),
+    );
+    const removed = removeConnectionFromCatalog(registered, RELAY_TARGET);
+
+    expect(putRemoteDpopTokenInCatalog(removed, REMOTE_TOKEN)).toEqual(
+      EMPTY_CONNECTION_CATALOG_DOCUMENT,
+    );
+  });
+
+  it("removes a DPoP token stored before the environment is removed", () => {
+    const registered = registerConnectionInCatalog(
+      EMPTY_CONNECTION_CATALOG_DOCUMENT,
+      new RelayConnectionRegistration({ target: RELAY_TARGET }),
+    );
+    const refreshed = putRemoteDpopTokenInCatalog(registered, REMOTE_TOKEN);
+
+    expect(removeConnectionFromCatalog(refreshed, RELAY_TARGET)).toEqual(
+      EMPTY_CONNECTION_CATALOG_DOCUMENT,
+    );
+  });
+
+  it("does not store DPoP tokens for a different environment or connection kind", () => {
+    const bearer = registerConnectionInCatalog(
+      EMPTY_CONNECTION_CATALOG_DOCUMENT,
+      new BearerConnectionRegistration({
+        target: BEARER_TARGET,
+        profile: BEARER_PROFILE,
+        credential: BEARER_CREDENTIAL,
+      }),
+    );
+    const otherRelay = registerConnectionInCatalog(
+      EMPTY_CONNECTION_CATALOG_DOCUMENT,
+      new RelayConnectionRegistration({
+        target: new RelayConnectionTarget({
+          environmentId: EnvironmentId.make("environment-2"),
+          label: "Other relay",
+        }),
+      }),
+    );
+
+    expect(putRemoteDpopTokenInCatalog(bearer, REMOTE_TOKEN)).toBe(bearer);
+    expect(putRemoteDpopTokenInCatalog(otherRelay, REMOTE_TOKEN)).toBe(otherRelay);
+  });
+
   it("persists the normalized SSH profile beside its target", () => {
     const target = new SshConnectionTarget({
       environmentId: ENVIRONMENT_ID,
diff --git a/packages/client-runtime/src/platform/storageDocument.ts b/packages/client-runtime/src/platform/storageDocument.ts
index 0ba55dfa2fbc..40a008b6c9ac 100644
--- a/packages/client-runtime/src/platform/storageDocument.ts
+++ b/packages/client-runtime/src/platform/storageDocument.ts
@@ -139,3 +139,24 @@ export function removeConnectionFromCatalog(
 ): ConnectionCatalogDocument {
   return removeConnectionMetadata(document, target, true);
 }
+
+export function putRemoteDpopTokenInCatalog(
+  document: ConnectionCatalogDocument,
+  token: TokenStore.RemoteDpopAccessToken,
+): ConnectionCatalogDocument {
+  const registered = document.targets.some(
+    (target) =>
+      target._tag === "RelayConnectionTarget" && target.environmentId === token.environmentId,
+  );
+  if (!registered) {
+    return document;
+  }
+  return {
+    ...document,
+    remoteDpopTokens: replaceCatalogValue(
+      document.remoteDpopTokens,
+      (value) => value.environmentId,
+      token,
+    ),
+  };
+}
diff --git a/packages/client-runtime/src/relay/discovery.test.ts b/packages/client-runtime/src/relay/discovery.test.ts
index 8cb963000bd3..fdbcceb7df86 100644
--- a/packages/client-runtime/src/relay/discovery.test.ts
+++ b/packages/client-runtime/src/relay/discovery.test.ts
@@ -19,6 +19,7 @@ import * as Connectivity from "../connection/connectivity.ts";
 import { ConnectionBlockedError, type NetworkStatus } from "../connection/model.ts";
 import * as ConnectionWakeups from "../connection/wakeups.ts";
 import * as RelayEnvironmentDiscovery from "./discovery.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 const environments = [
   {
@@ -61,6 +62,7 @@ const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* () {
   const listFailure = yield* Ref.make<ManagedRelay.ManagedRelayClientError | null>(null);
   const secondListCall = yield* Deferred.make<void>();
   const clerkToken = yield* Ref.make<string | null>("clerk-token");
+  const sessionIdentity = { accountId: "account-1" };
   const wakeups = yield* SubscriptionRef.make<{
     readonly sequence: number;
     readonly reason: "application-active" | "credentials-changed";
@@ -126,6 +128,11 @@ const makeHarness = Effect.fn("RelayDiscoveryTest.makeHarness")(function* () {
         Layer.succeed(
           ClientCapabilities.CloudSession,
           ClientCapabilities.CloudSession.of({
+            identity: Ref.get(clerkToken).pipe(
+              Effect.map((token) =>
+                token === null ? Option.none() : Option.some(sessionIdentity),
+              ),
+            ),
             clerkToken: Ref.get(clerkToken).pipe(
               Effect.flatMap((token) =>
                 token === null
@@ -282,6 +289,7 @@ describe("RelayEnvironmentDiscovery", () => {
           Layer.mergeAll(
             Layer.succeed(ManagedRelay.ManagedRelayClient, client),
             Layer.succeed(ClientCapabilities.CloudSession, {
+              identity: Effect.succeed(Option.some({ accountId: "account-1" })),
               clerkToken: Effect.succeed("clerk-token"),
             }),
             Layer.succeed(Connectivity.Connectivity, {
@@ -305,7 +313,7 @@ describe("RelayEnvironmentDiscovery", () => {
         expect(Option.getOrThrow(state.error)).toMatchObject({
           _tag: "ConnectionTransientError",
           reason: "timeout",
-          message: "Relay environment listing timed out.",
+          message: `Relay environment listing timed out. ${NETWORK_BLOCKING_HINT}`,
         });
       }).pipe(Effect.provide(layer));
     }),
diff --git a/packages/client-runtime/src/relay/managedRelay.test.ts b/packages/client-runtime/src/relay/managedRelay.test.ts
index fb2feaa61772..2699c4ad0803 100644
--- a/packages/client-runtime/src/relay/managedRelay.test.ts
+++ b/packages/client-runtime/src/relay/managedRelay.test.ts
@@ -1,15 +1,23 @@
 import { EnvironmentId } from "@t3tools/contracts";
-import { RelayEnvironmentStatusScope } from "@t3tools/contracts/relay";
+import {
+  RelayEnvironmentConnectScope,
+  RelayEnvironmentStatusScope,
+} from "@t3tools/contracts/relay";
 import { describe, expect, it } from "@effect/vitest";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
 import * as Tracer from "effect/Tracer";
+import * as Schema from "effect/Schema";
 import * as TestClock from "effect/testing/TestClock";
 
 import * as ManagedRelay from "./managedRelay.ts";
 import { remoteHttpClientLayer } from "../rpc/http.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
+
+const encodeRelayError = Schema.encodeEffect(ManagedRelay.ManagedRelayClientError);
+const decodeRelayError = Schema.decodeUnknownEffect(ManagedRelay.ManagedRelayClientError);
 
 function managedRelayTestLayer(
   fetchFn: typeof globalThis.fetch,
@@ -190,6 +198,102 @@ describe("ManagedRelayClient", () => {
     }).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
   });
 
+  it.effect("uses a cached token while another scope waits for an exchange", () => {
+    const exchangeStarted = Promise.withResolvers<void>();
+    const releaseExchange = Promise.withResolvers<void>();
+    let tokenExchangeCount = 0;
+    const statusTokens: Array<string | null> = [];
+    let persistedTokens: ReadonlyArray<ManagedRelay.ManagedRelayAccessTokenCacheEntry> = [
+      {
+        accountId: "user-1",
+        clientId: "t3-mobile",
+        relayUrl: "https://relay.example.test",
+        thumbprint: "client-thumbprint",
+        scopes: [RelayEnvironmentStatusScope],
+        accessToken: "cached-status-token",
+        expiresAtMillis: Number.MAX_SAFE_INTEGER,
+      },
+    ];
+    const accessTokenStore: ManagedRelay.ManagedRelayAccessTokenStore = {
+      load: Effect.sync(() => persistedTokens),
+      save: (entries) =>
+        Effect.sync(() => {
+          persistedTokens = entries;
+        }),
+      clear: Effect.sync(() => {
+        persistedTokens = [];
+      }),
+    };
+    const fetchFn = ((input, init) => {
+      if (String(input).endsWith("/v1/client/dpop-token")) {
+        tokenExchangeCount += 1;
+        exchangeStarted.resolve();
+        return releaseExchange.promise.then(() =>
+          Response.json({
+            access_token: "expanded-scope-token",
+            issued_token_type: "urn:ietf:params:oauth:token-type:access_token",
+            token_type: "DPoP",
+            expires_in: 1_800,
+            scope: `${RelayEnvironmentStatusScope} ${RelayEnvironmentConnectScope}`,
+          }),
+        );
+      }
+      statusTokens.push(new Headers(init?.headers).get("authorization"));
+      return Promise.resolve(
+        Response.json({
+          environmentId: "env-1",
+          endpoint: {
+            httpBaseUrl: "https://desktop.example.test/",
+            wsBaseUrl: "wss://desktop.example.test/ws",
+            providerKind: "cloudflare_tunnel",
+          },
+          status: "online",
+          checkedAt: "2026-09-04T00:00:00.000Z",
+        }),
+      );
+    }) satisfies typeof globalThis.fetch;
+
+    return Effect.gen(function* () {
+      const relayClient = yield* ManagedRelay.ManagedRelayClient;
+      const statusInput = {
+        clerkToken: clerkToken("user-1", "session-1"),
+        scopes: [RelayEnvironmentStatusScope],
+        environmentId: EnvironmentId.make("env-1"),
+      } as const;
+      const expandedScopeInput = {
+        ...statusInput,
+        scopes: [RelayEnvironmentStatusScope, RelayEnvironmentConnectScope],
+      } as const;
+      const firstMiss = yield* relayClient
+        .getEnvironmentStatus(expandedScopeInput)
+        .pipe(Effect.forkChild);
+      yield* Effect.promise(() => exchangeStarted.promise);
+      const secondMiss = yield* relayClient
+        .getEnvironmentStatus(expandedScopeInput)
+        .pipe(Effect.forkChild);
+
+      const status = yield* relayClient.getEnvironmentStatus(statusInput);
+      expect(status.status).toBe("online");
+      expect(statusTokens).toEqual(["DPoP cached-status-token"]);
+
+      releaseExchange.resolve();
+      yield* Fiber.join(firstMiss);
+      yield* Fiber.join(secondMiss);
+      expect(tokenExchangeCount).toBe(1);
+      expect(persistedTokens.map((token) => token.accessToken)).toEqual([
+        "cached-status-token",
+        "expanded-scope-token",
+      ]);
+      yield* relayClient.resetTokenCache;
+      expect(persistedTokens).toEqual([]);
+      yield* relayClient.getEnvironmentStatus(expandedScopeInput);
+      expect(tokenExchangeCount).toBe(2);
+    }).pipe(
+      Effect.ensuring(Effect.sync(() => releaseExchange.resolve())),
+      Effect.provide(managedRelayTestLayer(fetchFn, undefined, accessTokenStore)),
+    );
+  });
+
   it.effect("reuses a persisted token across runtimes and Clerk session token rotation", () => {
     let tokenExchangeCount = 0;
     let persistedTokens: ReadonlyArray<ManagedRelay.ManagedRelayAccessTokenCacheEntry> = [];
@@ -430,11 +534,44 @@ describe("ManagedRelayClient", () => {
         _tag: "ManagedRelayRequestTimeoutError",
         activity: "Relay environment listing",
         timeoutMs: ManagedRelay.MANAGED_RELAY_REQUEST_TIMEOUT_MS,
-        message: "Relay environment listing timed out.",
+        message: `Relay environment listing timed out. ${NETWORK_BLOCKING_HINT}`,
       });
     }).pipe(Effect.provide(Layer.merge(TestClock.layer(), managedRelayTestLayer(fetchFn))));
   });
 
+  it.effect("suggests checking network filtering when fetch fails without a response", () => {
+    const fetchFn = (() =>
+      Promise.reject(new TypeError("Failed to fetch"))) satisfies typeof globalThis.fetch;
+    return Effect.gen(function* () {
+      const relayClient = yield* ManagedRelay.ManagedRelayClient;
+      const error = yield* relayClient
+        .listEnvironments({ clerkToken: "clerk-token" })
+        .pipe(Effect.flip);
+      expect(error).toMatchObject({
+        _tag: "ManagedRelayRequestFailedError",
+        transportFailed: true,
+        message: `Could not list relay-managed environments. ${NETWORK_BLOCKING_HINT}`,
+      });
+      const encoded = yield* encodeRelayError(error);
+      const decoded = yield* decodeRelayError(encoded);
+      expect(decoded.message).toBe(error.message);
+    }).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
+  });
+
+  it.effect("does not suggest network filtering for an HTTP server error", () => {
+    const fetchFn = (() =>
+      Promise.resolve(
+        new Response("Unavailable", { status: 503 }),
+      )) satisfies typeof globalThis.fetch;
+    return Effect.gen(function* () {
+      const relayClient = yield* ManagedRelay.ManagedRelayClient;
+      const error = yield* relayClient
+        .listEnvironments({ clerkToken: "clerk-token" })
+        .pipe(Effect.flip);
+      expect(error.message).toBe("Could not list relay-managed environments.");
+    }).pipe(Effect.provide(managedRelayTestLayer(fetchFn)));
+  });
+
   it.effect("preserves typed relay trace IDs on client errors", () => {
     const fetchFn = (() =>
       Promise.resolve(
diff --git a/packages/client-runtime/src/relay/managedRelay.ts b/packages/client-runtime/src/relay/managedRelay.ts
index 06769a4372f1..d9f81c356e22 100644
--- a/packages/client-runtime/src/relay/managedRelay.ts
+++ b/packages/client-runtime/src/relay/managedRelay.ts
@@ -44,6 +44,7 @@ import * as SynchronizedRef from "effect/SynchronizedRef";
 import * as HttpClientError from "effect/unstable/http/HttpClientError";
 import type * as HttpMethod from "effect/unstable/http/HttpMethod";
 import * as HttpApiClient from "effect/unstable/httpapi/HttpApiClient";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 export interface ManagedRelayDpopProofInput {
   readonly method: HttpMethod.HttpMethod;
@@ -126,7 +127,7 @@ export class ManagedRelayRequestTimeoutError extends Schema.TaggedErrorClass<Man
   },
 ) {
   override get message(): string {
-    return `${this.activity} timed out.`;
+    return `${this.activity} timed out. ${NETWORK_BLOCKING_HINT}`;
   }
 }
 
@@ -145,13 +146,15 @@ export class ManagedRelayRequestFailedError extends Schema.TaggedErrorClass<Mana
   "ManagedRelayRequestFailedError",
   {
     action: ManagedRelayRequestAction,
+    transportFailed: Schema.optionalKey(Schema.Boolean),
     cause: Schema.Defect(),
     relayError: Schema.optional(RelayProtectedError),
     traceId: Schema.optional(Schema.String),
   },
 ) {
   override get message(): string {
-    return `Could not ${this.action}.`;
+    const message = `Could not ${this.action}.`;
+    return this.transportFailed ? `${message} ${NETWORK_BLOCKING_HINT}` : message;
   }
 }
 
@@ -307,6 +310,8 @@ function relayRequestError(action: ManagedRelayRequestAction) {
   return (cause: RelayHttpRequestError): ManagedRelayClientError =>
     new ManagedRelayRequestFailedError({
       action,
+      transportFailed:
+        HttpClientError.isHttpClientError(cause) && cause.reason._tag === "TransportError",
       cause,
       ...(isRelayProtectedError(cause) ? { relayError: cause, traceId: cause.traceId } : {}),
     });
@@ -546,18 +551,32 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
           expiresAtMillis: nowMillis + response.expires_in * 1_000,
         } satisfies ManagedRelayAccessTokenCacheEntry;
       }
+      const match = {
+        accountId: accountId.value,
+        clientId: options.clientId,
+        relayUrl,
+        thumbprint: input.thumbprint,
+        scopes: input.scopes,
+        nowMillis,
+      };
+      // Cache hits do not need to wait for an unrelated exchange or store write.
+      const cached = (yield* SynchronizedRef.get(cachedTokens)).find((token) =>
+        tokenMatches(token, match),
+      );
+      if (cached) {
+        yield* Effect.annotateCurrentSpan({
+          "relay.token_cache.result": "hit",
+        });
+        return cached;
+      }
       return yield* SynchronizedRef.modifyEffect(cachedTokens, (tokens) =>
         Effect.gen(function* () {
-          const activeTokens = tokens.filter((token) => token.expiresAtMillis > nowMillis + 5_000);
+          const lookupMillis = yield* Clock.currentTimeMillis;
+          const activeTokens = tokens.filter(
+            (token) => token.expiresAtMillis > lookupMillis + 5_000,
+          );
           const cached = activeTokens.find((token) =>
-            tokenMatches(token, {
-              accountId: accountId.value,
-              clientId: options.clientId,
-              relayUrl,
-              thumbprint: input.thumbprint,
-              scopes: input.scopes,
-              nowMillis,
-            }),
+            tokenMatches(token, { ...match, nowMillis: lookupMillis }),
           );
           if (cached) {
             yield* Effect.annotateCurrentSpan({
@@ -576,7 +595,7 @@ export const make = Effect.fn("ManagedRelayClient.make")(function* (
             thumbprint: input.thumbprint,
             scopes: input.scopes,
             accessToken: response.access_token,
-            expiresAtMillis: nowMillis + response.expires_in * 1_000,
+            expiresAtMillis: lookupMillis + response.expires_in * 1_000,
           };
           const nextTokens = [...activeTokens, next];
           if (options.accessTokenStore) {
diff --git a/packages/client-runtime/src/rpc/client.test.ts b/packages/client-runtime/src/rpc/client.test.ts
index 4e6baba8bef4..f2141add930f 100644
--- a/packages/client-runtime/src/rpc/client.test.ts
+++ b/packages/client-runtime/src/rpc/client.test.ts
@@ -3,10 +3,12 @@ import {
   EnvironmentId,
   type RelayClientInstallProgressEvent,
   type ServerConfigStreamEvent,
+  type ServerLifecycleStreamEvent,
   WS_METHODS,
 } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
 import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
@@ -27,7 +29,13 @@ import {
 import * as EnvironmentSupervisor from "../connection/supervisor.ts";
 import * as RpcSession from "../rpc/session.ts";
 import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
-import { EnvironmentRpcRequestObserver, request, runStream, subscribe } from "./client.ts";
+import {
+  EnvironmentRpcRequestObserver,
+  request,
+  runStream,
+  subscribe,
+  subscribeDynamicWithSession,
+} from "./client.ts";
 
 const TARGET = new PrimaryConnectionTarget({
   environmentId: EnvironmentId.make("environment-1"),
@@ -221,6 +229,72 @@ describe("environment RPC", () => {
     }),
   );
 
+  it.effect("keeps the producer session on an old value buffered across a session switch", () =>
+    Effect.gen(function* () {
+      const firstSubscribed = yield* Deferred.make<void>();
+      const secondSubscribed = yield* Deferred.make<void>();
+      const firstValueBlocked = yield* Deferred.make<void>();
+      const releaseFirstValue = yield* Deferred.make<void>();
+      const firstValue = { source: "first", index: 1 } as unknown as ServerLifecycleStreamEvent;
+      const bufferedFirstValue = {
+        source: "first",
+        index: 2,
+      } as unknown as ServerLifecycleStreamEvent;
+      const secondValue = { source: "second", index: 1 } as unknown as ServerLifecycleStreamEvent;
+      const firstClient = {
+        [WS_METHODS.subscribeServerLifecycle]: () =>
+          Stream.fromEffect(Deferred.succeed(firstSubscribed, undefined)).pipe(
+            Stream.drain,
+            Stream.concat(Stream.fromIterable([firstValue, bufferedFirstValue])),
+            Stream.concat(Stream.never),
+          ),
+      } as unknown as WsRpcProtocolClient;
+      const secondClient = {
+        [WS_METHODS.subscribeServerLifecycle]: () =>
+          Stream.fromEffect(Deferred.succeed(secondSubscribed, undefined)).pipe(
+            Stream.drain,
+            Stream.concat(Stream.make(secondValue)),
+            Stream.concat(Stream.never),
+          ),
+      } as unknown as WsRpcProtocolClient;
+      const firstSession = session(firstClient);
+      const secondSession = session(secondClient);
+      const { activeSession, supervisor } = yield* makeHarness();
+
+      const resultFiber = yield* subscribeDynamicWithSession(
+        WS_METHODS.subscribeServerLifecycle,
+        () => Effect.succeed({}),
+      ).pipe(
+        Stream.mapEffect(([producerSession, value]) =>
+          value === firstValue
+            ? Deferred.succeed(firstValueBlocked, undefined).pipe(
+                Effect.andThen(Deferred.await(releaseFirstValue)),
+                Effect.as([producerSession, value] as const),
+              )
+            : Effect.succeed([producerSession, value] as const),
+        ),
+        Stream.take(3),
+        Stream.runCollect,
+        Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
+        Effect.forkChild,
+      );
+
+      yield* SubscriptionRef.set(activeSession, Option.some(firstSession));
+      yield* Deferred.await(firstSubscribed);
+      yield* Deferred.await(firstValueBlocked);
+      yield* SubscriptionRef.set(activeSession, Option.some(secondSession));
+      yield* Deferred.await(secondSubscribed);
+      yield* Deferred.succeed(releaseFirstValue, undefined);
+
+      const result = yield* Fiber.join(resultFiber);
+      expect(result).toEqual([
+        [firstSession, firstValue],
+        [firstSession, bufferedFirstValue],
+        [secondSession, secondValue],
+      ]);
+    }),
+  );
+
   it.effect("keeps durable subscriptions alive across a transport failure and new session", () =>
     Effect.gen(function* () {
       const subscriptions: string[] = [];
diff --git a/packages/client-runtime/src/rpc/client.ts b/packages/client-runtime/src/rpc/client.ts
index c5103c3d3620..1695e9c5bba3 100644
--- a/packages/client-runtime/src/rpc/client.ts
+++ b/packages/client-runtime/src/rpc/client.ts
@@ -179,15 +179,15 @@ interface SubscriptionOptions<TTag extends EnvironmentSubscriptionRpcTag> {
   readonly resubscribe?: Stream.Stream<unknown, never, never>;
 }
 
-export function subscribeDynamic<TTag extends EnvironmentSubscriptionRpcTag>(
+function subscribeDynamicMapped<TTag extends EnvironmentSubscriptionRpcTag, A>(
   tag: TTag,
   makeInput: (session: RpcSession) => Effect.Effect<EnvironmentRpcInput<TTag>>,
+  mapStream: (
+    session: RpcSession,
+    stream: Stream.Stream<EnvironmentRpcStreamValue<TTag>, EnvironmentRpcStreamFailure<TTag>>,
+  ) => Stream.Stream<A, EnvironmentRpcStreamFailure<TTag>>,
   options?: SubscriptionOptions<TTag>,
-): Stream.Stream<
-  EnvironmentRpcStreamValue<TTag>,
-  EnvironmentRpcStreamFailure<TTag>,
-  EnvironmentSupervisor
-> {
+): Stream.Stream<A, EnvironmentRpcStreamFailure<TTag>, EnvironmentSupervisor> {
   return Stream.unwrap(
     Effect.gen(function* () {
       const supervisor = yield* EnvironmentSupervisor;
@@ -217,10 +217,7 @@ export function subscribeDynamic<TTag extends EnvironmentSubscriptionRpcTag>(
                 EnvironmentRpcStreamValue<TTag>,
                 EnvironmentRpcStreamFailure<TTag>
               >;
-              const subscribeToSession = (): Stream.Stream<
-                EnvironmentRpcStreamValue<TTag>,
-                EnvironmentRpcStreamFailure<TTag>
-              > =>
+              const subscribeToSession = (): Stream.Stream<A, EnvironmentRpcStreamFailure<TTag>> =>
                 Stream.suspend(() =>
                   Stream.unwrap(
                     Effect.gen(function* () {
@@ -230,7 +227,7 @@ export function subscribeDynamic<TTag extends EnvironmentSubscriptionRpcTag>(
                         method: tag,
                         input,
                       });
-                      return method(input).pipe(
+                      return mapStream(session, method(input)).pipe(
                         Stream.ensuring(completeObservation),
                         Stream.catchCause((cause) => {
                           const hasOnlyExpectedFailures =
@@ -288,6 +285,36 @@ export function subscribeDynamic<TTag extends EnvironmentSubscriptionRpcTag>(
   );
 }
 
+export function subscribeDynamic<TTag extends EnvironmentSubscriptionRpcTag>(
+  tag: TTag,
+  makeInput: (session: RpcSession) => Effect.Effect<EnvironmentRpcInput<TTag>>,
+  options?: SubscriptionOptions<TTag>,
+): Stream.Stream<
+  EnvironmentRpcStreamValue<TTag>,
+  EnvironmentRpcStreamFailure<TTag>,
+  EnvironmentSupervisor
+> {
+  return subscribeDynamicMapped(tag, makeInput, (_session, stream) => stream, options);
+}
+
+/** Tags each value before `switchMap` can buffer it across a session change. */
+export function subscribeDynamicWithSession<TTag extends EnvironmentSubscriptionRpcTag>(
+  tag: TTag,
+  makeInput: (session: RpcSession) => Effect.Effect<EnvironmentRpcInput<TTag>>,
+  options?: SubscriptionOptions<TTag>,
+): Stream.Stream<
+  readonly [session: RpcSession, value: EnvironmentRpcStreamValue<TTag>],
+  EnvironmentRpcStreamFailure<TTag>,
+  EnvironmentSupervisor
+> {
+  return subscribeDynamicMapped(
+    tag,
+    makeInput,
+    (session, stream) => stream.pipe(Stream.map((value) => [session, value] as const)),
+    options,
+  );
+}
+
 export function subscribe<TTag extends EnvironmentSubscriptionRpcTag>(
   tag: TTag,
   input: EnvironmentRpcInput<TTag>,
diff --git a/packages/client-runtime/src/rpc/session.test.ts b/packages/client-runtime/src/rpc/session.test.ts
index f8f940bc551f..8fe76e6181b8 100644
--- a/packages/client-runtime/src/rpc/session.test.ts
+++ b/packages/client-runtime/src/rpc/session.test.ts
@@ -8,6 +8,7 @@ import {
   ServerConfigStreamEvent,
   type ServerConfigStreamEvent as ServerConfigStreamEventType,
   WS_METHODS,
+  UsageLimitSourceId,
 } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
 import * as Cause from "effect/Cause";
@@ -29,6 +30,7 @@ import {
   ConnectionBlockedError,
   ConnectionTransientError,
   PrimaryConnectionTarget,
+  RelayConnectionTarget,
   type PreparedConnection,
 } from "../connection/model.ts";
 import * as EnvironmentSupervisor from "../connection/supervisor.ts";
@@ -36,6 +38,7 @@ import * as Persistence from "../platform/persistence.ts";
 import * as RpcSession from "./session.ts";
 import { makeEnvironmentServerConfigState } from "../state/server.ts";
 import { applyServerConfigProjection } from "../state/serverConfigProjection.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 
 type SocketEventType = "open" | "message" | "close" | "error";
 type SocketEvent = {
@@ -174,6 +177,29 @@ const THEME_SERVER_CONFIG: ServerConfigType = {
   },
 };
 const ENCODED_THEME_SERVER_CONFIG = encodeServerConfig(THEME_SERVER_CONFIG);
+const SOURCE_SERVER_CONFIG: ServerConfigType = {
+  ...THEME_SERVER_CONFIG,
+  environment: {
+    ...THEME_SERVER_CONFIG.environment,
+    capabilities: { ...THEME_SERVER_CONFIG.environment.capabilities, usageLimitSources: true },
+  },
+};
+const SOURCE_EVENT: ServerConfigStreamEventType = {
+  version: 1,
+  type: "usageLimitSourcesUpdated",
+  payload: {
+    sources: [
+      {
+        id: UsageLimitSourceId.make("proxy"),
+        kind: "cliproxy",
+        label: "Proxy",
+        checkedAt: "2026-09-04T00:00:00Z",
+        accounts: [],
+      },
+    ],
+  },
+};
+
 const LEGACY_SERVER_CONFIG = {
   ...ENCODED_SERVER_CONFIG,
   environment: {
@@ -402,52 +428,133 @@ describe("RpcSessionFactory", () => {
     ),
   );
 
-  it.effect("shares only a config subscription with the same theme opt-in", () =>
+  for (const options of [
+    { environmentThemes: true },
+    { usageLimitSources: true },
+    { environmentThemes: true, usageLimitSources: true },
+  ]) {
+    it.effect(
+      `shares only a config subscription with the same opt-ins: ${JSON.stringify(options)}`,
+      () =>
+        Effect.scoped(
+          Effect.gen(function* () {
+            const { factory, sockets } = yield* makeFactory(options);
+            const session = yield* factory.connect(PREPARED);
+            const readyFiber = yield* Effect.forkChild(session.ready);
+            const socket = yield* awaitSocket(sockets);
+            socket.open();
+            yield* completeInitialConfig(socket, ENCODED_THEME_SERVER_CONFIG, options);
+            yield* Fiber.join(readyFiber);
+
+            const shared = yield* session.subscribeServerConfig(options).pipe(Stream.runHead);
+            expect(shared).toMatchObject({ _tag: "Some", value: { type: "snapshot" } });
+            expect(
+              socket.sent.map((message) => decodeJson(message)).filter(isRpcRequest),
+            ).toHaveLength(1);
+
+            const fallbackFiber = yield* session
+              .subscribeServerConfig({})
+              .pipe(Stream.runHead, Effect.forkChild);
+            const fallbackRequest = yield* awaitRequest(socket, 1);
+            expect(fallbackRequest).toMatchObject({
+              tag: WS_METHODS.subscribeServerConfig,
+              payload: {},
+            });
+            socket.serverMessage(
+              encodeJson({
+                _tag: "Chunk",
+                requestId: fallbackRequest.id,
+                values: [
+                  {
+                    version: 1,
+                    type: "snapshot",
+                    config: ENCODED_THEME_SERVER_CONFIG,
+                  },
+                ],
+              }),
+            );
+            expect(yield* Fiber.join(fallbackFiber)).toMatchObject({
+              _tag: "Some",
+              value: { type: "snapshot" },
+            });
+          }),
+        ),
+    );
+  }
+
+  it.effect.each([
+    { usageLimitSources: true },
+    { environmentThemes: true, usageLimitSources: true },
+  ])("replays usage sources, removal, and capability downgrade with %j", (options) =>
     Effect.scoped(
       Effect.gen(function* () {
-        const { factory, sockets } = yield* makeFactory({ environmentThemes: true });
+        const { factory, sockets } = yield* makeFactory(options);
         const session = yield* factory.connect(PREPARED);
-        const readyFiber = yield* Effect.forkChild(session.ready);
+        const ready = yield* Effect.forkChild(session.ready);
         const socket = yield* awaitSocket(sockets);
         socket.open();
-        yield* completeInitialConfig(socket, ENCODED_THEME_SERVER_CONFIG, {
-          environmentThemes: true,
-        });
-        yield* Fiber.join(readyFiber);
-
-        const shared = yield* session
-          .subscribeServerConfig({ environmentThemes: true })
-          .pipe(Stream.runHead);
-        expect(shared).toMatchObject({ _tag: "Some", value: { type: "snapshot" } });
+        yield* completeInitialConfig(socket, encodeServerConfig(SOURCE_SERVER_CONFIG), options);
+        yield* Fiber.join(ready);
+        const observed = yield* Queue.unbounded<ServerConfigStreamEventType>();
+        yield* session.subscribeServerConfig(options).pipe(
+          Stream.runForEach((event) => Queue.offer(observed, event)),
+          Effect.forkChild,
+        );
+        expect((yield* Queue.take(observed)).type).toBe("snapshot");
+        const themes: ServerConfigStreamEventType[] = options.environmentThemes
+          ? [{ version: 1, type: "environmentThemesUpdated", payload: { themes: [] } }]
+          : [];
+        for (const event of themes) {
+          yield* publishConfigEvents(socket, [event]);
+          expect(yield* Queue.take(observed)).toEqual(event);
+        }
+        const events: ServerConfigStreamEventType[] = [
+          SOURCE_EVENT,
+          { version: 1, type: "usageLimitSourcesUpdated", payload: { sources: [] } },
+          SOURCE_EVENT,
+          { version: 1, type: "snapshot", config: THEME_SERVER_CONFIG },
+        ];
+        for (const event of events) {
+          yield* publishConfigEvents(socket, [event]);
+          expect(yield* Queue.take(observed)).toEqual(event);
+          const started = yield* Deferred.make<void>();
+          const replay = yield* session.subscribeServerConfig(options).pipe(
+            Stream.tap(() => Deferred.succeed(started, undefined)),
+            Stream.takeUntil((item) => item.type === "keybindingsUpdated"),
+            Stream.runCollect,
+            Effect.forkChild,
+          );
+          yield* Deferred.await(started);
+          // A live end marker makes a missing or stale replay event fail without a timeout.
+          const marker: ServerConfigStreamEventType = {
+            version: 1,
+            type: "keybindingsUpdated",
+            payload: { keybindings: [], issues: [] },
+          };
+          yield* publishConfigEvents(socket, [marker]);
+          expect(yield* Queue.take(observed)).toEqual(marker);
+          const replayed = Array.from(yield* Fiber.join(replay));
+          expect(replayed.slice(1)).toEqual([
+            ...themes,
+            ...(event.type === "snapshot" ? [] : [event]),
+            marker,
+          ]);
+          let projection = applyServerConfigProjection(Option.none(), {
+            version: 1,
+            type: "snapshot",
+            config: SOURCE_SERVER_CONFIG,
+          });
+          projection = applyServerConfigProjection(projection, SOURCE_EVENT);
+          for (const item of replayed) projection = applyServerConfigProjection(projection, item);
+          expect(Option.getOrThrow(projection).config.usageLimitSources).toEqual(
+            event.type === "usageLimitSourcesUpdated" && event.payload.sources.length > 0
+              ? event.payload.sources
+              : undefined,
+          );
+        }
         expect(socket.sent.map((message) => decodeJson(message)).filter(isRpcRequest)).toHaveLength(
           1,
         );
-
-        const fallbackFiber = yield* session
-          .subscribeServerConfig({})
-          .pipe(Stream.runHead, Effect.forkChild);
-        const fallbackRequest = yield* awaitRequest(socket, 1);
-        expect(fallbackRequest).toMatchObject({
-          tag: WS_METHODS.subscribeServerConfig,
-          payload: {},
-        });
-        socket.serverMessage(
-          encodeJson({
-            _tag: "Chunk",
-            requestId: fallbackRequest.id,
-            values: [
-              {
-                version: 1,
-                type: "snapshot",
-                config: ENCODED_THEME_SERVER_CONFIG,
-              },
-            ],
-          }),
-        );
-        expect(yield* Fiber.join(fallbackFiber)).toMatchObject({
-          _tag: "Some",
-          value: { type: "snapshot" },
-        });
       }),
     ),
   );
@@ -546,16 +653,20 @@ describe("RpcSessionFactory", () => {
     ),
   );
 
-  it.effect("recovers a slow subscriber after it misses theme deletion", () =>
+  it.effect("recovers a slow subscriber after it misses theme and usage-source deletion", () =>
     Effect.scoped(
       Effect.gen(function* () {
-        const { factory, sockets } = yield* makeFactory({ environmentThemes: true });
+        const { factory, sockets } = yield* makeFactory({
+          environmentThemes: true,
+          usageLimitSources: true,
+        });
         const session = yield* factory.connect(PREPARED);
         const readyFiber = yield* Effect.forkChild(session.ready);
         const socket = yield* awaitSocket(sockets);
         socket.open();
-        yield* completeInitialConfig(socket, ENCODED_THEME_SERVER_CONFIG, {
+        yield* completeInitialConfig(socket, encodeServerConfig(SOURCE_SERVER_CONFIG), {
           environmentThemes: true,
+          usageLimitSources: true,
         });
         yield* Fiber.join(readyFiber);
 
@@ -563,7 +674,7 @@ describe("RpcSessionFactory", () => {
         const releaseSlowSubscriber = yield* Deferred.make<void>();
         let firstEvent = true;
         const slowSubscriber = yield* session
-          .subscribeServerConfig({ environmentThemes: true })
+          .subscribeServerConfig({ environmentThemes: true, usageLimitSources: true })
           .pipe(
             Stream.mapEffect((event) => {
               if (!firstEvent) return Effect.succeed(event);
@@ -573,7 +684,7 @@ describe("RpcSessionFactory", () => {
                 Effect.as(event),
               );
             }),
-            Stream.take(3),
+            Stream.take(4),
             Stream.runCollect,
             Effect.forkChild,
           );
@@ -612,12 +723,18 @@ describe("RpcSessionFactory", () => {
           type: "settingsUpdated",
           payload: { settings: DEFAULT_SERVER_SETTINGS },
         }));
-        const allEvents = [...themeEvents, ...settingsEvents];
+        const sourceEvents: ServerConfigStreamEventType[] = [
+          SOURCE_EVENT,
+          { version: 1, type: "usageLimitSourcesUpdated", payload: { sources: [] } },
+        ];
+        const allEvents = [...themeEvents, ...sourceEvents, ...settingsEvents];
         const observedByFastSubscriber = yield* Queue.unbounded<ServerConfigStreamEventType>();
-        yield* session.subscribeServerConfig({ environmentThemes: true }).pipe(
-          Stream.runForEach((event) => Queue.offer(observedByFastSubscriber, event)),
-          Effect.forkChild,
-        );
+        yield* session
+          .subscribeServerConfig({ environmentThemes: true, usageLimitSources: true })
+          .pipe(
+            Stream.runForEach((event) => Queue.offer(observedByFastSubscriber, event)),
+            Effect.forkChild,
+          );
         expect((yield* Queue.take(observedByFastSubscriber)).type).toBe("snapshot");
         for (const event of allEvents) {
           yield* publishConfigEvents(socket, [event]);
@@ -630,19 +747,23 @@ describe("RpcSessionFactory", () => {
           "snapshot",
           "snapshot",
           "environmentThemesUpdated",
+          "usageLimitSourcesUpdated",
         ]);
         expect(recovered[2]).toMatchObject({ payload: { themes: [] } });
+        expect(recovered[3]).toMatchObject({ payload: { sources: [] } });
 
         let projection = applyServerConfigProjection(Option.none(), {
           version: 1,
           type: "snapshot",
-          config: THEME_SERVER_CONFIG,
+          config: SOURCE_SERVER_CONFIG,
         });
         projection = applyServerConfigProjection(projection, themeEvents[0]!);
+        projection = applyServerConfigProjection(projection, SOURCE_EVENT);
         for (const event of recovered.slice(1)) {
           projection = applyServerConfigProjection(projection, event);
         }
         expect(Option.getOrThrow(projection).config.environmentThemes).toBeUndefined();
+        expect(Option.getOrThrow(projection).config.usageLimitSources).toBeUndefined();
       }),
     ),
   );
@@ -1038,27 +1159,37 @@ describe("RpcSessionFactory", () => {
     ),
   );
 
-  it.effect("fails readiness when the websocket never opens", () =>
-    Effect.gen(function* () {
-      const { factory, sockets } = yield* makeFactory();
-
-      const error = yield* Effect.scoped(
-        Effect.gen(function* () {
-          const session = yield* factory.connect(PREPARED);
-          const readyFiber = yield* Effect.forkChild(Effect.flip(session.ready));
-          yield* awaitSocket(sockets);
+  for (const relay of [false, true]) {
+    it.effect(`fails readiness when the ${relay ? "relay" : "direct"} websocket never opens`, () =>
+      Effect.gen(function* () {
+        const { factory, sockets } = yield* makeFactory();
 
-          yield* TestClock.adjust("15 seconds");
-          return yield* Fiber.join(readyFiber);
-        }),
-      );
+        const error = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const session = yield* factory.connect({
+              ...PREPARED,
+              target: relay
+                ? new RelayConnectionTarget({
+                    environmentId: TARGET.environmentId,
+                    label: TARGET.label,
+                  })
+                : TARGET,
+            });
+            const readyFiber = yield* Effect.forkChild(Effect.flip(session.ready));
+            yield* awaitSocket(sockets);
+
+            yield* TestClock.adjust("15 seconds");
+            return yield* Fiber.join(readyFiber);
+          }),
+        );
 
-      expect(error).toBeInstanceOf(ConnectionTransientError);
-      expect(error).toMatchObject({
-        reason: "transport",
-        message: "Test environment could not establish a WebSocket connection.",
-      });
-      expect(sockets[0]?.readyState).toBe(TestWebSocket.CLOSED);
-    }).pipe(Effect.provide(TestClock.layer())),
-  );
+        expect(error).toBeInstanceOf(ConnectionTransientError);
+        expect(error).toMatchObject({
+          reason: "transport",
+          message: `Test environment could not establish a WebSocket connection.${relay ? ` ${NETWORK_BLOCKING_HINT}` : ""}`,
+        });
+        expect(sockets[0]?.readyState).toBe(TestWebSocket.CLOSED);
+      }).pipe(Effect.provide(TestClock.layer())),
+    );
+  }
 });
diff --git a/packages/client-runtime/src/rpc/session.ts b/packages/client-runtime/src/rpc/session.ts
index 7d975be5c9d3..aeef14968ff8 100644
--- a/packages/client-runtime/src/rpc/session.ts
+++ b/packages/client-runtime/src/rpc/session.ts
@@ -15,6 +15,7 @@ import * as Option from "effect/Option";
 import * as PubSub from "effect/PubSub";
 import * as Ref from "effect/Ref";
 import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
 import type * as Rpc from "effect/unstable/rpc/Rpc";
@@ -24,6 +25,7 @@ import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
 import * as Socket from "effect/unstable/socket/Socket";
 
 import { makeWsRpcProtocolClient, type WsRpcProtocolClient } from "./protocol.ts";
+import { NETWORK_BLOCKING_HINT } from "../errors/network.ts";
 import type {
   ConnectionAttemptError,
   ConnectionTransientError,
@@ -54,6 +56,7 @@ export interface RpcSession {
 
 export interface RpcSessionOptions {
   readonly environmentThemes?: boolean;
+  readonly usageLimitSources?: boolean;
 }
 
 export class RpcSessionFactory extends Context.Service<
@@ -83,11 +86,16 @@ type EnvironmentThemesUpdatedEvent = Extract<
   ServerConfigStreamEvent,
   { readonly type: "environmentThemesUpdated" }
 >;
+type UsageLimitSourcesUpdatedEvent = Extract<
+  ServerConfigStreamEvent,
+  { readonly type: "usageLimitSourcesUpdated" }
+>;
 
 interface ServerConfigReplayState {
   readonly projection: ServerConfigProjection;
   readonly revision: number;
   readonly themesEvent: EnvironmentThemesUpdatedEvent | undefined;
+  readonly sourcesEvent: UsageLimitSourcesUpdatedEvent | undefined;
 }
 
 interface BufferedServerConfigEvent {
@@ -104,11 +112,18 @@ function serverConfigReplayEvents(
     type: "snapshot" as const,
     config: withoutEnvironmentThemes(state.projection.config),
   };
-  return state.themesEvent === undefined ? [snapshot] : [snapshot, state.themesEvent];
+  return [
+    snapshot,
+    ...(state.themesEvent === undefined ? [] : [state.themesEvent]),
+    ...(state.sourcesEvent === undefined ? [] : [state.sourcesEvent]),
+  ];
 }
 
+const isSocketErrorReason = Schema.is(Socket.SocketErrorReason);
+
 function mapSessionRpcError(
   error: InitialConfigError | ProbeError | ServerConfigSubscriptionError,
+  networkHint: string,
 ): ConnectionAttemptError {
   switch (error._tag) {
     case "EnvironmentAuthorizationError":
@@ -125,7 +140,7 @@ function mapSessionRpcError(
     case "RpcClientError":
       return new ConnectionTransientErrorClass({
         reason: "transport",
-        detail: error.message,
+        detail: `${error.message}${isSocketErrorReason(error.reason) ? networkHint : ""}`,
       });
   }
 }
@@ -134,10 +149,16 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
   options: RpcSessionOptions = {},
 ) {
   const webSocketConstructor = yield* Socket.WebSocketConstructor;
-  const serverConfigInput: ServerConfigSubscriptionInput =
-    options.environmentThemes === true ? { environmentThemes: true } : {};
+  const serverConfigInput: ServerConfigSubscriptionInput = {
+    ...(options.environmentThemes === true ? { environmentThemes: true } : {}),
+    ...(options.usageLimitSources === true ? { usageLimitSources: true } : {}),
+  };
 
   const connect = Effect.fnUntraced(function* (connection: PreparedConnection) {
+    const networkHint =
+      connection.target._tag === "RelayConnectionTarget" ? ` ${NETWORK_BLOCKING_HINT}` : "";
+    const mapRpcError = (error: Parameters<typeof mapSessionRpcError>[0]) =>
+      mapSessionRpcError(error, networkHint);
     yield* Effect.annotateCurrentSpan({
       "connection.environment.id": connection.environmentId,
     });
@@ -152,9 +173,11 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
             disconnected,
             new ConnectionTransientErrorClass({
               reason: "transport",
-              detail: wasConnected
-                ? `${connection.label} disconnected.`
-                : `${connection.label} could not establish a WebSocket connection.`,
+              detail: `${
+                wasConnected
+                  ? `${connection.label} disconnected.`
+                  : `${connection.label} could not establish a WebSocket connection.`
+              }${networkHint}`,
             }),
           ),
         ),
@@ -218,6 +241,13 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
                       event.config.environment.capabilities.environmentThemes !== true
                     ? undefined
                     : Option.getOrUndefined(current)?.themesEvent,
+              sourcesEvent:
+                event.type === "usageLimitSourcesUpdated"
+                  ? event
+                  : event.type === "snapshot" &&
+                      event.config.environment.capabilities.usageLimitSources !== true
+                    ? undefined
+                    : Option.getOrUndefined(current)?.sourcesEvent,
             } satisfies ServerConfigReplayState;
             return [
               Option.some({ event, replay: next, revision: next.revision }),
@@ -244,7 +274,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
         }
         return Effect.all([
           Deferred.failCause(serverConfigExit, exit.cause),
-          Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapSessionRpcError)),
+          Deferred.failCause(configSubscriptionClosed, Cause.map(exit.cause, mapRpcError)),
         ]).pipe(Effect.asVoid);
       }),
     );
@@ -252,7 +282,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
     const initialConfig = Effect.raceFirst(
       Deferred.await(initialConfigDeferred),
       Deferred.await(serverConfigExit).pipe(
-        Effect.mapError(mapSessionRpcError),
+        Effect.mapError(mapRpcError),
         Effect.flatMap(() => Effect.fail(configSubscriptionEndedError)),
       ),
     ).pipe(Effect.withSpan("environment.initialSync"));
@@ -311,7 +341,7 @@ export const make = Effect.fn("RpcSessionFactory.make")(function* (
         (config.environment.capabilities.connectionProbe === true
           ? protocolClient[WS_METHODS.serverProbe]({})
           : protocolClient[WS_METHODS.serverGetConfig]({})
-        ).pipe(Effect.mapError(mapSessionRpcError)),
+        ).pipe(Effect.mapError(mapRpcError)),
       ),
       Effect.asVoid,
       Effect.withSpan("clientRuntime.connection.rpcSession.probe"),
diff --git a/packages/client-runtime/src/state/entities.test.ts b/packages/client-runtime/src/state/entities.test.ts
index d3bb6680208a..d02f63c0b69a 100644
--- a/packages/client-runtime/src/state/entities.test.ts
+++ b/packages/client-runtime/src/state/entities.test.ts
@@ -26,6 +26,7 @@ import { createEnvironmentSnapshotAtom } from "./snapshots.ts";
 import { createEnvironmentThreadDetailAtoms } from "./threadDetail.ts";
 import { mergeEnvironmentThread } from "./threadDetail.ts";
 import { createEnvironmentThreadShellAtoms } from "./threadShell.ts";
+import { applyShellStreamEvent } from "./shellReducer.ts";
 
 const ENVIRONMENT_ID = EnvironmentId.make("environment-1");
 const PROJECT_ID = ProjectId.make("project-1");
@@ -149,7 +150,7 @@ function shellState(snapshot: OrchestrationShellSnapshot): EnvironmentShellState
   };
 }
 
-function makeHarness() {
+function makeHarness(environmentIds: ReadonlyArray<EnvironmentId> = [ENVIRONMENT_ID]) {
   const shellStateAtoms = Atom.family((_environmentId: EnvironmentId) =>
     Atom.make(AsyncResult.success(shellState(SNAPSHOT))),
   );
@@ -158,20 +159,20 @@ function makeHarness() {
   );
   const catalogValueAtom = Atom.make({
     isReady: true,
-    entries: new Map([
-      [
-        ENVIRONMENT_ID,
+    entries: new Map(
+      environmentIds.map((environmentId) => [
+        environmentId,
         {
           target: new PrimaryConnectionTarget({
-            environmentId: ENVIRONMENT_ID,
+            environmentId,
             label: "Environment",
             httpBaseUrl: "https://example.test",
             wsBaseUrl: "wss://example.test",
           }),
           profile: Option.none(),
         },
-      ],
-    ]),
+      ]),
+    ),
   });
   const snapshotAtom = createEnvironmentSnapshotAtom(shellStateAtoms);
   const projects = createEnvironmentProjectAtoms({
@@ -188,7 +189,9 @@ function makeHarness() {
 
   return {
     registry: AtomRegistry.make(),
+    catalogValueAtom,
     shellStateAtom: shellStateAtoms(ENVIRONMENT_ID),
+    shellStateAtomForEnvironment: shellStateAtoms,
     threadStateAtom: (threadId: ThreadId) => threadStateAtoms(`${ENVIRONMENT_ID}\u0000${threadId}`),
     projects,
     threadShells,
@@ -279,7 +282,8 @@ describe("environment entity projections", () => {
     const refsByProjectAtom =
       harness.threadShells.environmentThreadRefsByProjectAtom(ENVIRONMENT_ID);
     const threadsAtom = harness.threadShells.threadShellsForProjectRefsAtom([projectRef]);
-    const refs = harness.registry.get(refsByProjectAtom).get(PROJECT_ID);
+    const membership = harness.registry.get(refsByProjectAtom);
+    const refs = membership.get(PROJECT_ID);
     const threads = harness.registry.get(threadsAtom);
 
     expect(threads).toHaveLength(1);
@@ -299,9 +303,158 @@ describe("environment entity projections", () => {
     );
 
     expect(harness.registry.get(refsByProjectAtom).get(PROJECT_ID)).toBe(refs);
+    expect(harness.registry.get(refsByProjectAtom)).toBe(membership);
     expect(harness.registry.get(threadsAtom)).toBe(threads);
   });
 
+  it("shares list values with point reads without retaining one atom per listed thread", () => {
+    const harness = makeHarness();
+    let snapshot: OrchestrationShellSnapshot = {
+      ...SNAPSHOT,
+      threads: Array.from({ length: 200 }, (_, index) => ({
+        ...THREAD_SHELL,
+        id: ThreadId.make(`listed-${index}`),
+      })),
+    };
+    harness.registry.set(harness.shellStateAtom, AsyncResult.success(shellState(snapshot)));
+    const listAtom = harness.threadShells.threadShellsAtom;
+    const projectListAtom = harness.threadShells.threadShellsForProjectRefsAtom([
+      { environmentId: ENVIRONMENT_ID, projectId: PROJECT_ID },
+    ]);
+    const disposeList = harness.registry.mount(listAtom);
+    const disposeProjectList = harness.registry.mount(projectListAtom);
+    try {
+      const before = harness.registry.get(listAtom);
+      expect(before).toHaveLength(200);
+      expect(harness.registry.get(projectListAtom)).toEqual(before);
+      expect(harness.registry.getNodes().size).toBeLessThan(20);
+      const firstAtom = harness.threadShells.threadShellAtom({
+        environmentId: ENVIRONMENT_ID,
+        threadId: snapshot.threads[0]!.id,
+      });
+      expect(harness.registry.get(firstAtom)).toBe(before[0]);
+
+      snapshot = applyShellStreamEvent(snapshot, {
+        kind: "thread-upserted",
+        sequence: 2,
+        thread: { ...snapshot.threads.at(-1)!, title: "Updated last thread" },
+      });
+      harness.registry.set(harness.shellStateAtom, AsyncResult.success(shellState(snapshot)));
+      const after = harness.registry.get(listAtom);
+      expect(after[0]).toBe(before[0]);
+      expect(after.at(-1)).not.toBe(before.at(-1));
+      expect(after.at(-1)?.title).toBe("Updated last thread");
+      expect(harness.registry.get(projectListAtom).at(-1)).toBe(after.at(-1));
+      expect(harness.registry.get(firstAtom)).toBe(after[0]);
+      expect(harness.registry.getNodes().size).toBeLessThan(20);
+    } finally {
+      disposeProjectList();
+      disposeList();
+      harness.registry.dispose();
+    }
+  });
+
+  it("keeps scoped identities and list order across project and environment changes", () => {
+    const remoteEnvironmentId = EnvironmentId.make("remote-environment");
+    const harness = makeHarness([ENVIRONMENT_ID, remoteEnvironmentId]);
+    const listAtom = harness.threadShells.threadShellsAtom;
+    const localRef = { environmentId: ENVIRONMENT_ID, threadId: THREAD_ID };
+    const remoteRef = { environmentId: remoteEnvironmentId, threadId: THREAD_ID };
+    const selectedAtom = harness.threadShells.threadShellsForProjectRefsAtom([
+      { environmentId: remoteEnvironmentId, projectId: PROJECT_ID },
+      { environmentId: ENVIRONMENT_ID, projectId: OTHER_PROJECT_ID },
+      { environmentId: remoteEnvironmentId, projectId: PROJECT_ID },
+      { environmentId: ENVIRONMENT_ID, projectId: PROJECT_ID },
+    ]);
+    const disposeList = harness.registry.mount(listAtom);
+    const disposeSelected = harness.registry.mount(selectedAtom);
+    try {
+      const original = harness.registry.get(listAtom);
+      const local = harness.registry.get(harness.threadShells.threadShellAtom(localRef));
+      const remote = harness.registry.get(harness.threadShells.threadShellAtom(remoteRef));
+      expect(original).toHaveLength(4);
+      expect(original[0]).toBe(local);
+      expect(original[2]).toBe(remote);
+      expect(local).not.toBe(remote);
+      expect(local?.environmentId).toBe(ENVIRONMENT_ID);
+      expect(remote?.environmentId).toBe(remoteEnvironmentId);
+      expect(harness.registry.get(selectedAtom)).toEqual([remote, original[1], local]);
+
+      harness.registry.set(
+        harness.shellStateAtomForEnvironment(remoteEnvironmentId),
+        AsyncResult.success(shellState({ ...SNAPSHOT, threads: SNAPSHOT.threads.toReversed() })),
+      );
+      expect([
+        ...harness.registry
+          .get(harness.threadShells.environmentThreadRefsByProjectAtom(remoteEnvironmentId))
+          .keys(),
+      ]).toEqual([OTHER_PROJECT_ID, PROJECT_ID]);
+      harness.registry.set(
+        harness.shellStateAtomForEnvironment(remoteEnvironmentId),
+        AsyncResult.success(shellState(SNAPSHOT)),
+      );
+
+      let snapshot = applyShellStreamEvent(SNAPSHOT, {
+        kind: "thread-upserted",
+        sequence: 2,
+        thread: { ...THREAD_SHELL, projectId: OTHER_PROJECT_ID, title: "Moved thread" },
+      });
+      harness.registry.set(harness.shellStateAtom, AsyncResult.success(shellState(snapshot)));
+      const moved = harness.registry.get(harness.threadShells.threadShellAtom(localRef));
+      expect(harness.registry.get(selectedAtom)).toEqual([remote, moved, original[1]]);
+      expect(harness.registry.get(listAtom)[2]).toBe(remote);
+
+      snapshot = applyShellStreamEvent(snapshot, {
+        kind: "thread-removed",
+        sequence: 3,
+        threadId: OTHER_THREAD_ID,
+      });
+      harness.registry.set(harness.shellStateAtom, AsyncResult.success(shellState(snapshot)));
+      expect(harness.registry.get(selectedAtom)).toEqual([remote, moved]);
+      expect(
+        harness.registry.get(
+          harness.threadShells.threadShellAtom({
+            environmentId: ENVIRONMENT_ID,
+            threadId: OTHER_THREAD_ID,
+          }),
+        ),
+      ).toBeNull();
+
+      const createdId = ThreadId.make("created-thread");
+      snapshot = applyShellStreamEvent(snapshot, {
+        kind: "thread-upserted",
+        sequence: 4,
+        thread: { ...THREAD_SHELL, id: createdId },
+      });
+      harness.registry.set(harness.shellStateAtom, AsyncResult.success(shellState(snapshot)));
+      const created = harness.registry.get(listAtom)[1];
+      expect(created?.id).toBe(createdId);
+      expect(harness.registry.get(selectedAtom)).toEqual([remote, moved, created]);
+
+      const catalog = harness.registry.get(harness.catalogValueAtom);
+      harness.registry.set(harness.catalogValueAtom, {
+        ...catalog,
+        entries: new Map([...catalog.entries].toReversed()),
+      });
+      expect(harness.registry.get(listAtom)).toEqual([remote, original[3], moved, created]);
+      harness.registry.set(harness.catalogValueAtom, {
+        ...catalog,
+        entries: new Map([[remoteEnvironmentId, catalog.entries.get(remoteEnvironmentId)!]]),
+      });
+      expect(harness.registry.get(listAtom)).toEqual([remote, original[3]]);
+      harness.registry.set(
+        harness.shellStateAtomForEnvironment(remoteEnvironmentId),
+        AsyncResult.success(shellState({ ...SNAPSHOT, threads: [] })),
+      );
+      expect(harness.registry.get(listAtom)).toEqual([]);
+      expect(harness.registry.get(harness.threadShells.threadShellAtom(remoteRef))).toBeNull();
+    } finally {
+      disposeSelected();
+      disposeList();
+      harness.registry.dispose();
+    }
+  });
+
   it("updates only the requested thread detail and preserves untouched field identities", () => {
     const harness = makeHarness();
     const threadRef = {
diff --git a/packages/client-runtime/src/state/environmentHttpAuth.test.ts b/packages/client-runtime/src/state/environmentHttpAuth.test.ts
new file mode 100644
index 000000000000..114b2c67e544
--- /dev/null
+++ b/packages/client-runtime/src/state/environmentHttpAuth.test.ts
@@ -0,0 +1,531 @@
+import { describe, expect, it } from "@effect/vitest";
+import {
+  EnvironmentId,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+  type AuthSessionState,
+  type OrchestrationShellSnapshot,
+  type OrchestrationThreadDetailSnapshot,
+} from "@t3tools/contracts";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import { TestClock } from "effect/testing";
+import type { HttpClient } from "effect/unstable/http";
+
+import { RemoteEnvironmentAuthorization } from "../authorization/service.ts";
+import {
+  ConnectionTransientError,
+  RelayConnectionTarget,
+  type PreparedConnection,
+  type PreparedHttpAuthorization,
+} from "../connection/model.ts";
+import { ManagedRelayDpopSigner, type ManagedRelayDpopProofInput } from "../relay/managedRelay.ts";
+import { remoteHttpClientLayer, type RemoteEnvironmentRequestError } from "../rpc/http.ts";
+import {
+  fetchEnvironmentPullRequestDiff,
+  type PullRequestDiffCredentialRejectedError,
+  PullRequestDiffLoader,
+  pullRequestDiffLoaderLayer,
+} from "./pullRequestDiffHttp.ts";
+import { fetchEnvironmentSessionState } from "./session.ts";
+import { fetchEnvironmentShellSnapshot } from "./shellSnapshotHttp.ts";
+import { fetchEnvironmentThreadSnapshot } from "./threadSnapshotHttp.ts";
+
+const TARGET = new RelayConnectionTarget({
+  environmentId: EnvironmentId.make("environment-1"),
+  label: "Remote environment",
+});
+const PREPARED: PreparedConnection = {
+  environmentId: TARGET.environmentId,
+  label: TARGET.label,
+  httpBaseUrl: "https://previous.example.test",
+  socketUrl: "wss://previous.example.test/ws",
+  httpAuthorization: { _tag: "Dpop", accessToken: "expired-token", expiresAtEpochMs: 0 },
+  target: TARGET,
+};
+const CURRENT_ORIGIN = "https://current.example.test";
+const RENEWED_ORIGIN = "https://renewed.example.test";
+const DIFF = {
+  projectId: ProjectId.make("project-1"),
+  repository: "owner/repository",
+  number: 42,
+};
+const DIFF_RESULT = { patch: "diff --git a/file.ts b/file.ts", truncated: false, nextCursor: null };
+const AUTH = {
+  policy: "remote-reachable",
+  bootstrapMethods: ["one-time-token"],
+  sessionMethods: ["dpop-access-token"],
+  sessionCookieName: "t3_session",
+} satisfies AuthSessionState["auth"];
+const SESSION = {
+  authenticated: true,
+  auth: AUTH,
+  scopes: ["orchestration:read", "orchestration:operate"],
+  sessionMethod: "dpop-access-token",
+} satisfies AuthSessionState;
+const UNAUTHENTICATED_SESSION = { authenticated: false, auth: AUTH } satisfies AuthSessionState;
+const SHELL = {
+  snapshotSequence: 1,
+  projects: [],
+  threads: [],
+  updatedAt: "2026-09-04T00:00:00.000Z",
+} satisfies OrchestrationShellSnapshot;
+const THREAD = {
+  snapshotSequence: 2,
+  thread: {
+    id: ThreadId.make("thread-1"),
+    projectId: ProjectId.make("project-1"),
+    title: "Thread",
+    modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
+    runtimeMode: "full-access",
+    interactionMode: "default",
+    branch: null,
+    worktreePath: null,
+    latestTurn: null,
+    createdAt: "2026-09-04T00:00:00.000Z",
+    updatedAt: "2026-09-04T00:00:00.000Z",
+    archivedAt: null,
+    settledOverride: null,
+    settledAt: null,
+    deletedAt: null,
+    messages: [],
+    proposedPlans: [],
+    activities: [],
+    checkpoints: [],
+    session: null,
+  },
+  page: { beforeCursor: null, hasMore: false, snapshotSequence: 2 },
+} satisfies OrchestrationThreadDetailSnapshot;
+
+function credentialRejectedResponse(reason = "invalid_credential") {
+  return Response.json(
+    {
+      _tag: "EnvironmentAuthInvalidError",
+      code: "auth_invalid",
+      reason,
+      traceId: "trace-rejected",
+    },
+    { status: 401 },
+  );
+}
+
+function makeHarness(reply: (requestNumber: number) => Response | Promise<Response>) {
+  const calls: Array<{ readonly url: string; readonly init: RequestInit }> = [];
+  const authorizations: Array<
+    Parameters<RemoteEnvironmentAuthorization["Service"]["authorizeDpopHttp"]>[0]
+  > = [];
+  const proofs: Array<ManagedRelayDpopProofInput> = [];
+  const remoteAuthorization = RemoteEnvironmentAuthorization.of({
+    authorizeBearer: () => Effect.die("Unexpected bearer connection preparation."),
+    authorizeDpop: () => Effect.die("HTTP requests must not prepare a WebSocket connection."),
+    authorizeDpopHttp: (input) =>
+      Effect.sync(() => {
+        authorizations.push(input);
+        const rejected = input.rejectedAccessToken !== undefined;
+        return {
+          environmentId: TARGET.environmentId,
+          label: TARGET.label,
+          httpBaseUrl: rejected ? RENEWED_ORIGIN : CURRENT_ORIGIN,
+          httpAuthorization: {
+            _tag: "Dpop" as const,
+            accessToken: rejected ? "renewed-token" : "current-token",
+            expiresAtEpochMs: 3_600_000,
+          },
+        };
+      }),
+  });
+  const signer = ManagedRelayDpopSigner.of({
+    thumbprint: Effect.succeed("test-thumbprint"),
+    createProof: (input) =>
+      Effect.sync(() => {
+        proofs.push(input);
+        return `proof-${proofs.length}`;
+      }),
+  });
+  const fetchFn: typeof fetch = async (request, init) => {
+    calls.push({ url: String(request), init: init ?? {} });
+    return reply(calls.length);
+  };
+  return {
+    calls,
+    authorizations,
+    proofs,
+    remoteAuthorization,
+    input: {
+      prepared: PREPARED,
+      signer: Option.some(signer),
+      remoteAuthorization: Option.some(remoteAuthorization),
+    },
+    httpLayer: remoteHttpClientLayer(fetchFn),
+  };
+}
+
+type HttpInput = ReturnType<typeof makeHarness>["input"];
+const LOADERS: ReadonlyArray<{
+  readonly name: string;
+  readonly method: string;
+  readonly path: string;
+  readonly response: unknown;
+  readonly load: (
+    input: HttpInput,
+  ) => Effect.Effect<
+    unknown,
+    RemoteEnvironmentRequestError | PullRequestDiffCredentialRejectedError,
+    HttpClient.HttpClient
+  >;
+}> = [
+  {
+    name: "PR diff",
+    method: "POST",
+    path: "/api/pull-requests/diff",
+    response: DIFF_RESULT,
+    load: (input: HttpInput) => fetchEnvironmentPullRequestDiff({ ...input, diff: DIFF }),
+  },
+  {
+    name: "session permissions",
+    method: "GET",
+    path: "/api/auth/session",
+    response: SESSION,
+    load: fetchEnvironmentSessionState,
+  },
+  {
+    name: "shell snapshot",
+    method: "GET",
+    path: "/api/orchestration/shell",
+    response: SHELL,
+    load: fetchEnvironmentShellSnapshot,
+  },
+  {
+    name: "older thread history",
+    method: "GET",
+    path: "/api/orchestration/threads/thread-1",
+    response: THREAD,
+    load: (input: HttpInput) =>
+      fetchEnvironmentThreadSnapshot({
+        ...input,
+        threadId: THREAD.thread.id,
+        window: { turnLimit: 20, beforeCursor: "older-page" },
+      }),
+  },
+];
+
+describe("authenticated environment HTTP requests", () => {
+  it.effect.each(LOADERS)("uses current relay authorization and endpoint for $name", (loader) =>
+    Effect.gen(function* () {
+      const harness = makeHarness(() => Response.json(loader.response));
+      const result = yield* loader.load(harness.input).pipe(Effect.provide(harness.httpLayer));
+
+      expect(result).toEqual(loader.response);
+      expect(harness.calls).toHaveLength(1);
+      const call = harness.calls[0]!;
+      const url = new URL(call.url);
+      expect(url.origin).toBe(CURRENT_ORIGIN);
+      expect(url.pathname).toBe(loader.path);
+      expect(call.init.method).toBe(loader.method);
+      expect(new Headers(call.init.headers).get("authorization")).toBe("DPoP current-token");
+      expect(new Headers(call.init.headers).get("dpop")).toBe("proof-1");
+      expect(call.init.credentials).toBeUndefined();
+      expect(harness.authorizations).toEqual([{ expectedEnvironmentId: TARGET.environmentId }]);
+      expect(harness.proofs).toEqual([
+        {
+          method: loader.method,
+          url: `${CURRENT_ORIGIN}${loader.path}`,
+          accessToken: "current-token",
+        },
+      ]);
+      if (loader.name === "older thread history") {
+        expect(url.searchParams.get("turnLimit")).toBe("20");
+        expect(url.searchParams.get("beforeCursor")).toBe("older-page");
+      }
+      expect(PREPARED.httpAuthorization).toMatchObject({ accessToken: "expired-token" });
+    }),
+  );
+
+  it.effect("retries a rejected diff once with a new token, endpoint, and proof", () =>
+    Effect.gen(function* () {
+      const harness = makeHarness((requestNumber) =>
+        requestNumber === 1 ? credentialRejectedResponse() : Response.json(DIFF_RESULT),
+      );
+      const result = yield* fetchEnvironmentPullRequestDiff({ ...harness.input, diff: DIFF }).pipe(
+        Effect.provide(harness.httpLayer),
+      );
+
+      expect(result).toEqual(DIFF_RESULT);
+      expect(harness.authorizations).toEqual([
+        { expectedEnvironmentId: TARGET.environmentId },
+        { expectedEnvironmentId: TARGET.environmentId, rejectedAccessToken: "current-token" },
+      ]);
+      expect(harness.calls.map((call) => call.url)).toEqual([
+        `${CURRENT_ORIGIN}/api/pull-requests/diff`,
+        `${RENEWED_ORIGIN}/api/pull-requests/diff`,
+      ]);
+      expect(
+        harness.calls.map((call) => new Headers(call.init.headers).get("authorization")),
+      ).toEqual(["DPoP current-token", "DPoP renewed-token"]);
+      expect(harness.calls.map((call) => new Headers(call.init.headers).get("dpop"))).toEqual([
+        "proof-1",
+        "proof-2",
+      ]);
+      expect(harness.proofs[1]).toEqual({
+        method: "POST",
+        url: `${RENEWED_ORIGIN}/api/pull-requests/diff`,
+        accessToken: "renewed-token",
+      });
+      expect(harness.calls[1]!.init.body).toEqual(harness.calls[0]!.init.body);
+    }),
+  );
+
+  it.effect("uses the authorization service captured by the diff loader layer", () =>
+    Effect.gen(function* () {
+      const harness = makeHarness(() => Response.json(DIFF_RESULT));
+      const loaderLayer = pullRequestDiffLoaderLayer.pipe(
+        Layer.provide(
+          Layer.mergeAll(
+            harness.httpLayer,
+            Layer.succeed(ManagedRelayDpopSigner, Option.getOrThrow(harness.input.signer)),
+            Layer.succeed(RemoteEnvironmentAuthorization, harness.remoteAuthorization),
+          ),
+        ),
+      );
+      const loader = yield* PullRequestDiffLoader.pipe(Effect.provide(loaderLayer));
+      const result = yield* loader.load(PREPARED, DIFF);
+
+      expect(result).toEqual(DIFF_RESULT);
+      expect(new Headers(harness.calls[0]!.init.headers).get("authorization")).toBe(
+        "DPoP current-token",
+      );
+    }),
+  );
+
+  it.effect("preserves the credential rejection after the one recovery attempt fails", () =>
+    Effect.gen(function* () {
+      const harness = makeHarness(() => credentialRejectedResponse());
+      const error = yield* fetchEnvironmentPullRequestDiff({ ...harness.input, diff: DIFF }).pipe(
+        Effect.provide(harness.httpLayer),
+        Effect.flip,
+      );
+
+      expect(error).toMatchObject({
+        _tag: "PullRequestDiffCredentialRejectedError",
+        traceId: "trace-rejected",
+      });
+      expect(harness.calls).toHaveLength(2);
+      expect(harness.authorizations).toHaveLength(2);
+    }),
+  );
+
+  it.effect.each([
+    {
+      name: "insufficient scope",
+      reply: () =>
+        Response.json(
+          {
+            _tag: "EnvironmentScopeRequiredError",
+            code: "insufficient_scope",
+            requiredScope: "orchestration:read",
+            traceId: "trace-scope",
+          },
+          { status: 403 },
+        ),
+      errorTag: "EnvironmentScopeRequiredError",
+    },
+    {
+      name: "missing credential",
+      reply: () => credentialRejectedResponse("missing_credential"),
+      errorTag: "EnvironmentAuthInvalidError",
+    },
+    {
+      name: "Cloudflare 530",
+      reply: () => new Response("error code: 1033", { status: 530 }),
+      errorTag: "RemoteEnvironmentAuthUndeclaredStatusError",
+    },
+    {
+      name: "network failure",
+      reply: () => Promise.reject(new Error("Network unreachable")),
+      errorTag: "RemoteEnvironmentAuthFetchError",
+    },
+  ])("does not renew or retry on $name", ({ reply, errorTag }) =>
+    Effect.gen(function* () {
+      const harness = makeHarness(reply);
+      const error = yield* fetchEnvironmentPullRequestDiff({ ...harness.input, diff: DIFF }).pipe(
+        Effect.provide(harness.httpLayer),
+        Effect.flip,
+      );
+
+      expect(error._tag).toBe(errorTag);
+      expect(harness.calls).toHaveLength(1);
+      expect(harness.authorizations).toEqual([{ expectedEnvironmentId: TARGET.environmentId }]);
+    }),
+  );
+
+  it.effect("recovers a session's unauthenticated 200 response before checking permissions", () =>
+    Effect.gen(function* () {
+      const harness = makeHarness((requestNumber) =>
+        Response.json(requestNumber === 1 ? UNAUTHENTICATED_SESSION : SESSION),
+      );
+      const result = yield* fetchEnvironmentSessionState(harness.input).pipe(
+        Effect.provide(harness.httpLayer),
+      );
+
+      expect(result).toEqual(SESSION);
+      expect(harness.authorizations[1]).toEqual({
+        expectedEnvironmentId: TARGET.environmentId,
+        rejectedAccessToken: "current-token",
+      });
+      expect(harness.calls).toHaveLength(2);
+    }),
+  );
+
+  it.effect("reports persistent session rejection instead of showing missing permissions", () =>
+    Effect.gen(function* () {
+      const harness = makeHarness(() => Response.json(UNAUTHENTICATED_SESSION));
+      const error = yield* fetchEnvironmentSessionState(harness.input).pipe(
+        Effect.provide(harness.httpLayer),
+        Effect.flip,
+      );
+
+      expect(error).toMatchObject({
+        _tag: "RemoteEnvironmentAuthFetchError",
+        message: "The environment rejected the renewed session authorization.",
+      });
+      expect(harness.calls).toHaveLength(2);
+    }),
+  );
+
+  it.effect.each([
+    { name: "cookie", authorization: null },
+    { name: "bearer", authorization: { _tag: "Bearer", token: "bearer-token" } },
+  ] satisfies ReadonlyArray<{ name: string; authorization: PreparedHttpAuthorization | null }>)(
+    "leaves $name sessions unchanged without relay services",
+    ({ authorization }) =>
+      Effect.gen(function* () {
+        const harness = makeHarness(() => Response.json(UNAUTHENTICATED_SESSION));
+        const result = yield* fetchEnvironmentSessionState({
+          prepared: { ...PREPARED, httpAuthorization: authorization },
+          signer: Option.none(),
+        }).pipe(Effect.provide(harness.httpLayer));
+
+        expect(result).toEqual(UNAUTHENTICATED_SESSION);
+        expect(harness.calls).toHaveLength(1);
+        expect(harness.authorizations).toEqual([]);
+        expect(new Headers(harness.calls[0]!.init.headers).get("authorization")).toBe(
+          authorization === null ? null : "Bearer bearer-token",
+        );
+        expect(harness.calls[0]!.init.credentials).toBe(
+          authorization === null ? "include" : undefined,
+        );
+      }),
+  );
+
+  it.effect("keeps the caller's timeout while waiting for renewal", () =>
+    Effect.gen(function* () {
+      const harness = makeHarness(() => Response.json(SESSION));
+      const authorizing = yield* Deferred.make<void>();
+      const remoteAuthorization = RemoteEnvironmentAuthorization.of({
+        ...harness.remoteAuthorization,
+        authorizeDpopHttp: () =>
+          Deferred.succeed(authorizing, undefined).pipe(Effect.andThen(Effect.never)),
+      });
+      const pending = yield* fetchEnvironmentSessionState({
+        ...harness.input,
+        remoteAuthorization: Option.some(remoteAuthorization),
+        timeoutMs: 100,
+      }).pipe(Effect.provide(harness.httpLayer), Effect.flip, Effect.forkChild);
+      yield* Deferred.await(authorizing);
+      yield* TestClock.adjust(100);
+
+      expect(yield* Fiber.join(pending)).toMatchObject({
+        _tag: "RemoteEnvironmentAuthTimeoutError",
+        requestUrl: `${PREPARED.httpBaseUrl}/api/auth/session`,
+        timeoutMs: 100,
+      });
+      expect(harness.calls).toEqual([]);
+    }),
+  );
+
+  it.effect("reports the current endpoint when the total timeout expires during HTTP", () =>
+    Effect.gen(function* () {
+      const requested = Promise.withResolvers<void>();
+      const response = Promise.withResolvers<Response>();
+      const harness = makeHarness(() => {
+        requested.resolve();
+        return response.promise;
+      });
+      const authorizing = yield* Deferred.make<void>();
+      const authorize = yield* Deferred.make<void>();
+      const remoteAuthorization = RemoteEnvironmentAuthorization.of({
+        ...harness.remoteAuthorization,
+        authorizeDpopHttp: (input) =>
+          Deferred.succeed(authorizing, undefined).pipe(
+            Effect.andThen(Deferred.await(authorize)),
+            Effect.andThen(harness.remoteAuthorization.authorizeDpopHttp(input)),
+          ),
+      });
+      const pending = yield* fetchEnvironmentSessionState({
+        ...harness.input,
+        remoteAuthorization: Option.some(remoteAuthorization),
+        timeoutMs: 100,
+      }).pipe(Effect.provide(harness.httpLayer), Effect.flip, Effect.forkChild);
+      yield* Deferred.await(authorizing);
+      yield* TestClock.adjust(25);
+      yield* Deferred.succeed(authorize, undefined);
+      yield* Effect.promise(() => requested.promise);
+      yield* TestClock.adjust(75);
+
+      expect(yield* Fiber.join(pending)).toMatchObject({
+        _tag: "RemoteEnvironmentAuthTimeoutError",
+        requestUrl: `${CURRENT_ORIGIN}/api/auth/session`,
+        timeoutMs: 100,
+      });
+      expect(harness.calls.map((call) => call.url)).toEqual([`${CURRENT_ORIGIN}/api/auth/session`]);
+      expect(harness.authorizations).toHaveLength(1);
+      response.resolve(Response.json(SESSION));
+    }),
+  );
+
+  it.effect("reports renewal failure without sending the expired prepared token", () =>
+    Effect.gen(function* () {
+      const harness = makeHarness(() => Response.json(SESSION));
+      const failure = new ConnectionTransientError({
+        reason: "transport",
+        detail: "Relay unavailable",
+      });
+      const remoteAuthorization = RemoteEnvironmentAuthorization.of({
+        ...harness.remoteAuthorization,
+        authorizeDpopHttp: () => Effect.fail(failure),
+      });
+      const error = yield* fetchEnvironmentSessionState({
+        ...harness.input,
+        remoteAuthorization: Option.some(remoteAuthorization),
+      }).pipe(Effect.provide(harness.httpLayer), Effect.flip);
+
+      expect(error).toMatchObject({
+        _tag: "RemoteEnvironmentAuthFetchError",
+        message: "Could not authorize the environment request.",
+        cause: failure,
+      });
+      expect(harness.calls).toEqual([]);
+      expect(harness.proofs).toEqual([]);
+    }),
+  );
+
+  it.effect("does not fall back to a captured DPoP token when authorization is unavailable", () =>
+    Effect.gen(function* () {
+      const harness = makeHarness(() => Response.json(SESSION));
+      const error = yield* fetchEnvironmentSessionState({
+        prepared: PREPARED,
+        signer: harness.input.signer,
+      }).pipe(Effect.provide(harness.httpLayer), Effect.flip);
+
+      expect(error).toMatchObject({
+        _tag: "RemoteEnvironmentAuthFetchError",
+        message: "No relay authorization service is available for the environment request.",
+      });
+      expect(harness.calls).toEqual([]);
+    }),
+  );
+});
diff --git a/packages/client-runtime/src/state/environmentHttpAuth.ts b/packages/client-runtime/src/state/environmentHttpAuth.ts
index 097708066200..cfc42f560715 100644
--- a/packages/client-runtime/src/state/environmentHttpAuth.ts
+++ b/packages/client-runtime/src/state/environmentHttpAuth.ts
@@ -1,10 +1,18 @@
 import * as Effect from "effect/Effect";
 import * as Option from "effect/Option";
-import { FetchHttpClient, type HttpMethod } from "effect/unstable/http";
+import * as Result from "effect/Result";
+import { FetchHttpClient, type HttpClient, type HttpMethod } from "effect/unstable/http";
 
-import type { PreparedHttpAuthorization } from "../connection/model.ts";
+import type { RemoteEnvironmentAuthorization } from "../authorization/service.ts";
+import type { PreparedConnection, PreparedHttpAuthorization } from "../connection/model.ts";
 import type { ManagedRelayDpopSigner } from "../relay/managedRelay.ts";
-import { RemoteEnvironmentAuthFetchError } from "../rpc/http.ts";
+import {
+  executeEnvironmentHttpRequest,
+  makeEnvironmentHttpApiClient,
+  RemoteEnvironmentAuthFetchError,
+  RemoteEnvironmentAuthTimeoutError,
+  type RemoteEnvironmentRequestError,
+} from "../rpc/http.ts";
 
 export interface EnvironmentHttpAuthHeaders {
   readonly authorization?: string;
@@ -28,8 +36,7 @@ export const withEnvironmentCredentials = <A, E, R>(
     : request;
 
 /**
- * Build the authorization headers for an authenticated environment HTTP
- * request, matching the credential the connection was prepared with:
+ * Build request-bound headers from the current environment credential:
  * - primary/local connections carry no credential,
  * - bearer connections send a static `Bearer` token,
  * - relay connections send a `DPoP` access token with a freshly signed proof
@@ -71,3 +78,106 @@ export const buildEnvironmentAuthHeaders = (
       );
     return { authorization: `DPoP ${authorization.accessToken}`, dpop: proof };
   });
+
+/**
+ * Resolve relay credentials at request time without replacing the live socket.
+ * A rejected credential gets one refresh and retry, with a new request-bound
+ * proof. Cookie and bearer requests keep their existing authentication behavior.
+ */
+export const executeAuthenticatedEnvironmentHttpRequest = Effect.fn(
+  "clientRuntime.state.executeAuthenticatedEnvironmentHttpRequest",
+)(function* <A, E, R>(input: {
+  readonly prepared: PreparedConnection;
+  readonly signer: Option.Option<ManagedRelayDpopSigner["Service"]>;
+  readonly remoteAuthorization?: Option.Option<RemoteEnvironmentAuthorization["Service"]>;
+  readonly method: HttpMethod.HttpMethod;
+  readonly url: (httpBaseUrl: string) => string;
+  readonly timeoutMs: number;
+  readonly request: (input: {
+    readonly client: Effect.Success<ReturnType<typeof makeEnvironmentHttpApiClient>>;
+    readonly headers: EnvironmentHttpAuthHeaders;
+  }) => Effect.Effect<A, E, R>;
+  /** Some endpoints report rejected credentials in a successful response. */
+  readonly isUnauthorizedResponse?: (response: NoInfer<A>) => boolean;
+}): Effect.fn.Return<A, RemoteEnvironmentRequestError, HttpClient.HttpClient | R> {
+  let httpBaseUrl = input.prepared.httpBaseUrl;
+  return yield* Effect.gen(function* () {
+    let rejectedAccessToken: string | undefined;
+    for (;;) {
+      let authorization = input.prepared.httpAuthorization;
+      if (authorization?._tag === "Dpop") {
+        const remote = input.remoteAuthorization;
+        if (remote === undefined || Option.isNone(remote)) {
+          return yield* new RemoteEnvironmentAuthFetchError({
+            message: "No relay authorization service is available for the environment request.",
+            cause: input.prepared.target._tag,
+          });
+        }
+        const current = yield* remote.value
+          .authorizeDpopHttp({
+            expectedEnvironmentId: input.prepared.environmentId,
+            ...(rejectedAccessToken === undefined ? {} : { rejectedAccessToken }),
+          })
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new RemoteEnvironmentAuthFetchError({
+                  message: "Could not authorize the environment request.",
+                  cause,
+                }),
+            ),
+          );
+        httpBaseUrl = current.httpBaseUrl;
+        authorization = current.httpAuthorization;
+      }
+
+      const requestUrl = input.url(httpBaseUrl);
+      const client = yield* makeEnvironmentHttpApiClient(httpBaseUrl);
+      const headers = yield* buildEnvironmentAuthHeaders(
+        authorization,
+        input.method,
+        requestUrl,
+        input.signer,
+      );
+      const result = yield* executeEnvironmentHttpRequest(
+        requestUrl,
+        input.timeoutMs,
+        withEnvironmentCredentials(authorization, input.request({ client, headers })),
+      ).pipe(Effect.result);
+
+      if (Result.isFailure(result)) {
+        if (
+          authorization?._tag === "Dpop" &&
+          rejectedAccessToken === undefined &&
+          result.failure._tag === "EnvironmentAuthInvalidError" &&
+          result.failure.reason === "invalid_credential"
+        ) {
+          rejectedAccessToken = authorization.accessToken;
+          continue;
+        }
+        return yield* result.failure;
+      }
+
+      if (
+        authorization?._tag === "Dpop" &&
+        input.isUnauthorizedResponse?.(result.success) === true
+      ) {
+        if (rejectedAccessToken === undefined) {
+          rejectedAccessToken = authorization.accessToken;
+          continue;
+        }
+        return yield* new RemoteEnvironmentAuthFetchError({
+          message: "The environment rejected the renewed session authorization.",
+          cause: result.success,
+        });
+      }
+      return result.success;
+    }
+  }).pipe(
+    Effect.timeoutOrElse({
+      duration: input.timeoutMs,
+      orElse: () =>
+        Effect.fail(new RemoteEnvironmentAuthTimeoutError(input.url(httpBaseUrl), input.timeoutMs)),
+    }),
+  );
+});
diff --git a/packages/client-runtime/src/state/pullRequestDiffHttp.ts b/packages/client-runtime/src/state/pullRequestDiffHttp.ts
index b6b925917b99..fdb4fcde7ded 100644
--- a/packages/client-runtime/src/state/pullRequestDiffHttp.ts
+++ b/packages/client-runtime/src/state/pullRequestDiffHttp.ts
@@ -10,15 +10,14 @@ import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import { HttpClient } from "effect/unstable/http";
 
+import { RemoteEnvironmentAuthorization } from "../authorization/service.ts";
 import type { PreparedConnection } from "../connection/model.ts";
 import { ManagedRelayDpopSigner } from "../relay/managedRelay.ts";
 import {
-  executeEnvironmentHttpRequest,
-  makeEnvironmentHttpApiClient,
   makeEnvironmentHttpApiUrlBuilder,
   type RemoteEnvironmentRequestError,
 } from "../rpc/http.ts";
-import { buildEnvironmentAuthHeaders, withEnvironmentCredentials } from "./environmentHttpAuth.ts";
+import { executeAuthenticatedEnvironmentHttpRequest } from "./environmentHttpAuth.ts";
 
 const DEFAULT_PULL_REQUEST_DIFF_TIMEOUT_MS = 60_000;
 
@@ -46,26 +45,16 @@ export const fetchEnvironmentPullRequestDiff = Effect.fn(
   readonly prepared: PreparedConnection;
   readonly diff: PullRequestDiffInput;
   readonly signer: Option.Option<ManagedRelayDpopSigner["Service"]>;
+  readonly remoteAuthorization?: Option.Option<RemoteEnvironmentAuthorization["Service"]>;
   readonly timeoutMs?: number;
 }) {
-  const requestUrl = makeEnvironmentHttpApiUrlBuilder(
-    input.prepared.httpBaseUrl,
-  ).pullRequests.diff();
-  const client = yield* makeEnvironmentHttpApiClient(input.prepared.httpBaseUrl);
-  const headers = yield* buildEnvironmentAuthHeaders(
-    input.prepared.httpAuthorization,
-    "POST",
-    requestUrl,
-    input.signer,
-  );
-  return yield* executeEnvironmentHttpRequest(
-    requestUrl,
-    input.timeoutMs ?? DEFAULT_PULL_REQUEST_DIFF_TIMEOUT_MS,
-    withEnvironmentCredentials(
-      input.prepared.httpAuthorization,
-      client.pullRequests.diff({ payload: input.diff, headers }),
-    ),
-  ).pipe(
+  return yield* executeAuthenticatedEnvironmentHttpRequest({
+    ...input,
+    method: "POST",
+    url: (httpBaseUrl) => makeEnvironmentHttpApiUrlBuilder(httpBaseUrl).pullRequests.diff(),
+    timeoutMs: input.timeoutMs ?? DEFAULT_PULL_REQUEST_DIFF_TIMEOUT_MS,
+    request: ({ client, headers }) => client.pullRequests.diff({ payload: input.diff, headers }),
+  }).pipe(
     Effect.mapError((error) =>
       error._tag === "EnvironmentAuthInvalidError" && error.reason === "invalid_credential"
         ? new PullRequestDiffCredentialRejectedError({
@@ -98,11 +87,15 @@ export const pullRequestDiffLoaderLayer: Layer.Layer<
   Effect.gen(function* () {
     const httpClient = yield* HttpClient.HttpClient;
     const signer = yield* Effect.serviceOption(ManagedRelayDpopSigner);
+    const remoteAuthorization = yield* Effect.serviceOption(RemoteEnvironmentAuthorization);
     return PullRequestDiffLoader.of({
       load: (prepared, input) =>
-        fetchEnvironmentPullRequestDiff({ prepared, diff: input, signer }).pipe(
-          Effect.provideService(HttpClient.HttpClient, httpClient),
-        ),
+        fetchEnvironmentPullRequestDiff({
+          prepared,
+          diff: input,
+          signer,
+          remoteAuthorization,
+        }).pipe(Effect.provideService(HttpClient.HttpClient, httpClient)),
     });
   }),
 );
diff --git a/packages/client-runtime/src/state/pullRequests.ts b/packages/client-runtime/src/state/pullRequests.ts
index 6144d8507a9e..d0da18a7226a 100644
--- a/packages/client-runtime/src/state/pullRequests.ts
+++ b/packages/client-runtime/src/state/pullRequests.ts
@@ -75,8 +75,8 @@ export function pullRequestDetailToVcsStatus(
 }
 
 /**
- * Every read shells out to the GitHub CLI, so results are reused for a short while and
- * refreshed explicitly. Mutations run serially per environment: `gh` actions on the same
+ * Reopening a PR within a minute reuses detail and activity. Explicit refreshes and
+ * turn notifications still revalidate. Mutations run serially per environment: actions on the same
  * pull request are order-sensitive, and the detail view refetches after each one.
  */
 export function createPullRequestEnvironmentAtoms<R, E>(
@@ -91,7 +91,7 @@ export function createPullRequestEnvironmentAtoms<R, E>(
   const activity = createEnvironmentRpcQueryAtomFamily(runtime, {
     label: "environment-data:pull-requests:activity",
     tag: WS_METHODS.pullRequestsActivity,
-    staleTimeMs: 15_000,
+    staleTimeMs: 60_000,
     refreshTrigger: ({ environmentId }) => refreshes({ environmentId, input: {} }),
   });
   return {
@@ -118,7 +118,7 @@ export function createPullRequestEnvironmentAtoms<R, E>(
     detail: createEnvironmentRpcQueryAtomFamily(runtime, {
       label: "environment-data:pull-requests:detail",
       tag: WS_METHODS.pullRequestsDetail,
-      staleTimeMs: 15_000,
+      staleTimeMs: 60_000,
       refreshTrigger: ({ environmentId }) => refreshes({ environmentId, input: {} }),
     }),
     activity,
diff --git a/packages/client-runtime/src/state/server.test.ts b/packages/client-runtime/src/state/server.test.ts
index 6567726a4809..878f8c902f91 100644
--- a/packages/client-runtime/src/state/server.test.ts
+++ b/packages/client-runtime/src/state/server.test.ts
@@ -7,8 +7,8 @@ import {
 } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
 import * as Cause from "effect/Cause";
-import * as Duration from "effect/Duration";
 import * as Deferred from "effect/Deferred";
+import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
 import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
@@ -31,13 +31,15 @@ import * as Persistence from "../platform/persistence.ts";
 import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
 import type { RpcSession } from "../rpc/session.ts";
 import {
+  applyServerWelcomeEvent,
+  makeEnvironmentServerWelcomeState,
   makeEnvironmentServerConfigState,
   isLegacyUpdateHandoffLoss,
   matchesServerUpdateReadyEvent,
   matchesServerUpdateResumeEvent,
   nudgeReconnectDuringUpdateRestart,
-  projectServerWelcome,
   resolveServerConfigValue,
+  resolveServerWelcomeState,
   resolveServerUpdateProgressResult,
   serverUpdateStateForProgressEvent,
   serverUpdateStateForServerVersion,
@@ -494,25 +496,227 @@ describe("server state projection", () => {
     expect(Option.getOrThrow(downgraded).config.environmentThemes).toBeUndefined();
   });
 
-  it("retains welcome when a ready event follows in the same stream chunk", () => {
+  it("keeps a current welcome on ready and rejects a buffered welcome from the old session", () => {
+    const firstSession = session({} as WsRpcProtocolClient);
+    const secondSession = session({} as WsRpcProtocolClient);
     const welcome = {
       environment: {} as ServerLifecycleWelcomePayload["environment"],
       cwd: "/repo",
       projectName: "repo",
     } as ServerLifecycleWelcomePayload;
-    const [afterWelcome] = projectServerWelcome(Option.none(), {
+    const initial = {
+      currentSession: firstSession,
+      welcomeSession: firstSession,
+      welcome: null,
+    };
+    const afterWelcome = applyServerWelcomeEvent(initial, firstSession, {
       type: "welcome",
       payload: welcome,
     });
-    const [afterReady, emitted] = projectServerWelcome(afterWelcome, {
+    const afterReady = applyServerWelcomeEvent(afterWelcome, firstSession, {
       type: "ready",
       payload: {},
     });
+    const afterSwitch = { ...afterReady, currentSession: secondSession };
+    const afterBufferedOldWelcome = applyServerWelcomeEvent(afterSwitch, firstSession, {
+      type: "welcome",
+      payload: { ...welcome, cwd: "/stale" },
+    });
 
-    expect(Option.getOrThrow(afterReady)).toBe(welcome);
-    expect(emitted).toEqual([]);
+    expect(afterReady).toBe(afterWelcome);
+    expect(resolveServerWelcomeState(afterReady)).toBe(welcome);
+    expect(afterBufferedOldWelcome).toBe(afterSwitch);
+    expect(resolveServerWelcomeState(afterBufferedOldWelcome)).toBeNull();
   });
 
+  it.effect("checks the authoritative session before accepting a buffered welcome", () =>
+    Effect.gen(function* () {
+      const firstEvents = yield* Queue.unbounded<{
+        readonly type: "welcome" | "ready";
+        readonly payload: unknown;
+      }>();
+      const firstSubscribed = yield* Deferred.make<void>();
+      const firstClient = {
+        [WS_METHODS.subscribeServerLifecycle]: () =>
+          Stream.fromEffect(Deferred.succeed(firstSubscribed, undefined)).pipe(
+            Stream.drain,
+            Stream.concat(Stream.fromQueue(firstEvents)),
+          ),
+      } as unknown as WsRpcProtocolClient;
+      const firstSession = session(firstClient);
+      const secondSession = session({} as WsRpcProtocolClient);
+      const supervisorSession = yield* SubscriptionRef.make(Option.some(firstSession));
+      const supervisor = EnvironmentSupervisor.EnvironmentSupervisor.of({
+        target: TARGET,
+        state: yield* SubscriptionRef.make(AVAILABLE_CONNECTION_STATE),
+        session: supervisorSession,
+        prepared: yield* SubscriptionRef.make(Option.none<PreparedConnection>()),
+        connect: Effect.void,
+        disconnect: Effect.void,
+        retryNow: Effect.void,
+      } satisfies EnvironmentSupervisor.EnvironmentSupervisor["Service"]);
+      const staleWelcome = {
+        environment: {} as ServerLifecycleWelcomePayload["environment"],
+        cwd: "/stale",
+        projectName: "stale",
+      } as ServerLifecycleWelcomePayload;
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const state = yield* makeEnvironmentServerWelcomeState().pipe(
+            Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
+          );
+          yield* Deferred.await(firstSubscribed);
+
+          // Model the point after the ref changed but before either subscriber
+          // processed its publication.
+          supervisorSession.value = Option.some(secondSession);
+          const handled = yield* SubscriptionRef.changes(state).pipe(
+            Stream.filter(
+              (value) => value.currentSession === secondSession || value.welcome === staleWelcome,
+            ),
+            Stream.runHead,
+            Effect.map(Option.getOrThrow),
+            Effect.forkChild,
+          );
+          yield* Queue.offer(firstEvents, { type: "welcome", payload: staleWelcome });
+
+          const next = yield* Fiber.join(handled);
+          expect(next.currentSession).toBe(secondSession);
+          expect(resolveServerWelcomeState(next)).toBeNull();
+        }),
+      );
+    }),
+  );
+
+  it.effect("reads the authoritative session after waiting for the welcome state lock", () =>
+    Effect.gen(function* () {
+      const firstSubscribed = yield* Deferred.make<void>();
+      const firstClient = {
+        [WS_METHODS.subscribeServerLifecycle]: () =>
+          Stream.fromEffect(Deferred.succeed(firstSubscribed, undefined)).pipe(Stream.drain),
+      } as unknown as WsRpcProtocolClient;
+      const secondClient = {
+        [WS_METHODS.subscribeServerLifecycle]: () => Stream.never,
+      } as unknown as WsRpcProtocolClient;
+      const firstSession = session(firstClient);
+      const secondSession = session(secondClient);
+      const thirdSession = session({} as WsRpcProtocolClient);
+      const supervisorSession = yield* SubscriptionRef.make(Option.some(firstSession));
+      const supervisor = EnvironmentSupervisor.EnvironmentSupervisor.of({
+        target: TARGET,
+        state: yield* SubscriptionRef.make(AVAILABLE_CONNECTION_STATE),
+        session: supervisorSession,
+        prepared: yield* SubscriptionRef.make(Option.none<PreparedConnection>()),
+        connect: Effect.void,
+        disconnect: Effect.void,
+        retryNow: Effect.void,
+      } satisfies EnvironmentSupervisor.EnvironmentSupervisor["Service"]);
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const state = yield* makeEnvironmentServerWelcomeState().pipe(
+            Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
+          );
+          yield* Deferred.await(firstSubscribed);
+          const changed = yield* SubscriptionRef.changes(state).pipe(
+            Stream.filter((value) => value.currentSession !== firstSession),
+            Stream.runHead,
+            Effect.map(Option.getOrThrow),
+            Effect.forkChild,
+          );
+
+          yield* state.semaphore.withPermit(
+            Effect.gen(function* () {
+              yield* SubscriptionRef.set(supervisorSession, Option.some(secondSession));
+              yield* Effect.yieldNow;
+              yield* Effect.yieldNow;
+              yield* Effect.yieldNow;
+              supervisorSession.value = Option.some(thirdSession);
+            }),
+          );
+
+          expect((yield* Fiber.join(changed)).currentSession).toBe(thirdSession);
+        }),
+      );
+    }),
+  );
+
+  it.effect("clears a welcome until the reconnected session sends its own", () =>
+    Effect.gen(function* () {
+      const firstEvents = yield* Queue.unbounded<{
+        readonly type: "welcome" | "ready";
+        readonly payload: unknown;
+      }>();
+      const secondEvents = yield* Queue.unbounded<{
+        readonly type: "welcome" | "ready";
+        readonly payload: unknown;
+      }>();
+      const firstClient = {
+        [WS_METHODS.subscribeServerLifecycle]: () => Stream.fromQueue(firstEvents),
+      } as unknown as WsRpcProtocolClient;
+      const secondClient = {
+        [WS_METHODS.subscribeServerLifecycle]: () => Stream.fromQueue(secondEvents),
+      } as unknown as WsRpcProtocolClient;
+      const firstSession = session(firstClient);
+      const secondSession = session(secondClient);
+      const supervisorSession = yield* SubscriptionRef.make(Option.some(firstSession));
+      const supervisor = EnvironmentSupervisor.EnvironmentSupervisor.of({
+        target: TARGET,
+        state: yield* SubscriptionRef.make(AVAILABLE_CONNECTION_STATE),
+        session: supervisorSession,
+        prepared: yield* SubscriptionRef.make(Option.none<PreparedConnection>()),
+        connect: Effect.void,
+        disconnect: Effect.void,
+        retryNow: Effect.void,
+      } satisfies EnvironmentSupervisor.EnvironmentSupervisor["Service"]);
+      const firstWelcome = {
+        environment: {} as ServerLifecycleWelcomePayload["environment"],
+        cwd: "/first",
+        projectName: "first",
+      } as ServerLifecycleWelcomePayload;
+      const secondWelcome = {
+        environment: {} as ServerLifecycleWelcomePayload["environment"],
+        cwd: "/second",
+        projectName: "second",
+      } as ServerLifecycleWelcomePayload;
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const state = yield* makeEnvironmentServerWelcomeState().pipe(
+            Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
+          );
+          const nextResolved = (
+            predicate: (value: ServerLifecycleWelcomePayload | null) => boolean,
+          ) =>
+            SubscriptionRef.changes(state).pipe(
+              Stream.map(resolveServerWelcomeState),
+              Stream.filter(predicate),
+              Stream.runHead,
+              Effect.map(Option.getOrThrow),
+            );
+
+          const first = yield* nextResolved((value) => value === firstWelcome).pipe(
+            Effect.forkChild,
+          );
+          yield* Queue.offer(firstEvents, { type: "welcome", payload: firstWelcome });
+          expect(yield* Fiber.join(first)).toBe(firstWelcome);
+
+          const cleared = yield* nextResolved((value) => value === null).pipe(Effect.forkChild);
+          yield* SubscriptionRef.set(supervisorSession, Option.some(secondSession));
+          expect(yield* Fiber.join(cleared)).toBeNull();
+          expect(resolveServerWelcomeState(yield* SubscriptionRef.get(state))).toBeNull();
+
+          const second = yield* nextResolved((value) => value === secondWelcome).pipe(
+            Effect.forkChild,
+          );
+          yield* Queue.offer(secondEvents, { type: "welcome", payload: secondWelcome });
+          expect(yield* Fiber.join(second)).toBe(secondWelcome);
+        }),
+      );
+    }),
+  );
+
   it("prefers an active session config over cache until a live event arrives", () => {
     const config = (source: string, serverVersion: string) =>
       ({
diff --git a/packages/client-runtime/src/state/server.ts b/packages/client-runtime/src/state/server.ts
index 4a2843abb806..9f94663388ec 100644
--- a/packages/client-runtime/src/state/server.ts
+++ b/packages/client-runtime/src/state/server.ts
@@ -40,8 +40,10 @@ import {
   request,
   runStream,
   subscribe,
+  subscribeDynamicWithSession,
   type EnvironmentRpcInput,
 } from "../rpc/client.ts";
+import type { RpcSession } from "../rpc/session.ts";
 import { followStreamInEnvironment } from "./runtime.ts";
 import {
   applyServerConfigProjection,
@@ -476,21 +478,119 @@ export function serverConfigStateChanges(
   );
 }
 
-export function projectServerWelcome(
-  current: Option.Option<ServerLifecycleWelcomePayload>,
+export function applyServerWelcomeEvent(
+  current: EnvironmentServerWelcomeState,
+  session: RpcSession,
   event: {
     readonly type: "welcome" | "ready";
     readonly payload: unknown;
   },
-): readonly [
-  Option.Option<ServerLifecycleWelcomePayload>,
-  ReadonlyArray<ServerLifecycleWelcomePayload>,
-] {
-  if (event.type !== "welcome") {
-    return [current, []];
-  }
-  const welcome = event.payload as ServerLifecycleWelcomePayload;
-  return [Option.some(welcome), [welcome]];
+): EnvironmentServerWelcomeState {
+  return event.type === "welcome" && current.currentSession === session
+    ? {
+        ...current,
+        welcomeSession: session,
+        welcome: event.payload as ServerLifecycleWelcomePayload,
+      }
+    : current;
+}
+
+export interface EnvironmentServerWelcomeState {
+  readonly currentSession: RpcSession | null;
+  readonly welcomeSession: RpcSession | null;
+  readonly welcome: ServerLifecycleWelcomePayload | null;
+}
+
+export function resolveServerWelcomeState(
+  state: EnvironmentServerWelcomeState,
+): ServerLifecycleWelcomePayload | null {
+  return state.currentSession === state.welcomeSession ? state.welcome : null;
+}
+
+export const makeEnvironmentServerWelcomeState = Effect.fn("EnvironmentServerWelcomeState.make")(
+  function* () {
+    const supervisor = yield* EnvironmentSupervisor;
+    const initialSession = Option.getOrNull(yield* SubscriptionRef.get(supervisor.session));
+    const state = yield* SubscriptionRef.make<EnvironmentServerWelcomeState>({
+      currentSession: initialSession,
+      welcomeSession: null,
+      welcome: null,
+    });
+
+    const updateWithCurrentSession = Effect.fn(
+      "EnvironmentServerWelcomeState.updateWithCurrentSession",
+    )(function* (
+      update: (
+        current: EnvironmentServerWelcomeState,
+        currentSession: RpcSession | null,
+      ) => EnvironmentServerWelcomeState,
+    ) {
+      return yield* SubscriptionRef.modifyEffect(state, (current) =>
+        SubscriptionRef.get(supervisor.session).pipe(
+          Effect.map(
+            (latestSession) =>
+              [undefined, update(current, Option.getOrNull(latestSession))] as const,
+          ),
+        ),
+      );
+    });
+
+    yield* SubscriptionRef.changes(supervisor.session).pipe(
+      Stream.runForEach(() =>
+        updateWithCurrentSession((current, currentSession) => ({
+          ...current,
+          currentSession,
+        })),
+      ),
+      Effect.forkScoped,
+    );
+
+    yield* subscribeDynamicWithSession(
+      WS_METHODS.subscribeServerLifecycle,
+      Effect.fn("EnvironmentServerWelcomeState.makeSubscribeInput")(function* (session) {
+        yield* updateWithCurrentSession((current, currentSession) =>
+          currentSession === session
+            ? {
+                ...current,
+                currentSession,
+                welcomeSession: session,
+                welcome: null,
+              }
+            : { ...current, currentSession },
+        );
+        return {};
+      }),
+    ).pipe(
+      Stream.runForEach(([session, event]) =>
+        updateWithCurrentSession((current, currentSession) =>
+          applyServerWelcomeEvent(
+            {
+              ...current,
+              currentSession,
+            },
+            session,
+            event,
+          ),
+        ),
+      ),
+      Effect.forkScoped,
+    );
+
+    return state;
+  },
+);
+
+export function serverWelcomeStateChanges(environmentId: EnvironmentId) {
+  return followStreamInEnvironment(
+    environmentId,
+    Stream.unwrap(
+      makeEnvironmentServerWelcomeState().pipe(
+        Effect.map((state) =>
+          SubscriptionRef.changes(state).pipe(Stream.map(resolveServerWelcomeState)),
+        ),
+      ),
+    ),
+  );
 }
 
 export function resolveServerConfigValue(
@@ -807,11 +907,53 @@ export function createServerEnvironmentAtoms<R, E>(
       Atom.withLabel(`environment-data:server:settings:${environmentId}`),
     ),
   );
+  const usagePricesAtom = Atom.family((environmentId: EnvironmentId) =>
+    Atom.make((get) => {
+      const overrides = get(settingsValueAtom(environmentId))?.usagePriceOverrides ?? {};
+      // Only changed prices should trigger another transcript scan. Settings
+      // snapshots can recreate the same mapping in a different property order.
+      return JSON.stringify(
+        Object.keys(overrides)
+          .sort()
+          .map((model) => {
+            const price = overrides[model]!;
+            return [
+              model,
+              price.inputCostPerMillionTokens,
+              price.outputCostPerMillionTokens,
+              price.cacheReadCostPerMillionTokens,
+              price.cacheWriteCostPerMillionTokens,
+            ];
+          }),
+      );
+    }).pipe(Atom.withLabel(`environment-data:server:usage-prices:${environmentId}`)),
+  );
   const providersValueAtom = Atom.family((environmentId: EnvironmentId) =>
     Atom.make((get) => get(configValueAtom(environmentId))?.providers ?? null).pipe(
       Atom.withLabel(`environment-data:server:providers:${environmentId}`),
     ),
   );
+  const welcomeStateFamily = Atom.family((environmentId: EnvironmentId) =>
+    runtime
+      .atom(serverWelcomeStateChanges(environmentId), { initialValue: null })
+      .pipe(
+        Atom.setIdleTTL(5 * 60_000),
+        Atom.withLabel(`environment-data:server:welcome-state:${environmentId}`),
+      ),
+  );
+  const welcomeFamily = Atom.family((environmentId: EnvironmentId) =>
+    Atom.make((get) => {
+      const result = get(welcomeStateFamily(environmentId));
+      if (result._tag !== "Success") return result;
+      return result.value === null
+        ? AsyncResult.initial<ServerLifecycleWelcomePayload, never>(result.waiting)
+        : AsyncResult.success(result.value, result);
+    }).pipe(Atom.withLabel(`environment-data:server:welcome:${environmentId}`)),
+  );
+  const welcome = (target: {
+    readonly environmentId: EnvironmentId;
+    readonly input: EnvironmentRpcInput<typeof WS_METHODS.subscribeServerLifecycle>;
+  }) => welcomeFamily(target.environmentId);
 
   return {
     configValueAtom,
@@ -892,16 +1034,10 @@ export function createServerEnvironmentAtoms<R, E>(
       label: "environment-data:server:usage-summary",
       tag: WS_METHODS.serverGetUsageSummary,
       staleTimeMs: 60_000,
+      refreshTrigger: ({ environmentId }) => usagePricesAtom(environmentId),
     }),
     configProjection,
-    welcome: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
-      label: "environment-data:server:welcome",
-      tag: WS_METHODS.subscribeServerLifecycle,
-      transform: (stream) =>
-        stream.pipe(
-          Stream.mapAccum(Option.none<ServerLifecycleWelcomePayload>, projectServerWelcome),
-        ),
-    }),
+    welcome,
     consumeResetCredit: createEnvironmentRpcCommand(runtime, {
       label: "environment-data:server:consume-reset-credit",
       tag: WS_METHODS.providerConsumeResetCredit,
diff --git a/packages/client-runtime/src/state/serverUsage.test.ts b/packages/client-runtime/src/state/serverUsage.test.ts
new file mode 100644
index 000000000000..9cf2667d8bc2
--- /dev/null
+++ b/packages/client-runtime/src/state/serverUsage.test.ts
@@ -0,0 +1,263 @@
+import {
+  DEFAULT_SERVER_SETTINGS,
+  EnvironmentId,
+  UsageDay,
+  USAGE_CONTRACT_VERSION,
+  WS_METHODS,
+  type ServerConfig,
+  type ServerConfigStreamEvent,
+  type ServerSettings,
+  type UsageSummary,
+  type UsageSummaryInput,
+} from "@t3tools/contracts";
+import { expect, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
+import { AsyncResult, Atom, AtomRegistry } from "effect/unstable/reactivity";
+
+import {
+  AVAILABLE_CONNECTION_STATE,
+  PrimaryConnectionTarget,
+  type PreparedConnection,
+  type SupervisorConnectionState,
+} from "../connection/model.ts";
+import { EnvironmentRegistry } from "../connection/registry.ts";
+import { EnvironmentSupervisor } from "../connection/supervisor.ts";
+import { EnvironmentCacheStore } from "../platform/persistence.ts";
+import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
+import type { RpcSession } from "../rpc/session.ts";
+import { createServerEnvironmentAtoms } from "./server.ts";
+
+const TARGET = new PrimaryConnectionTarget({
+  environmentId: EnvironmentId.make("usage-environment"),
+  label: "Usage environment",
+  httpBaseUrl: "https://environment.example.test",
+  wsBaseUrl: "wss://environment.example.test",
+});
+
+const INPUT: UsageSummaryInput = {
+  sinceDay: UsageDay.make("2026-09-01"),
+  untilDay: UsageDay.make("2026-09-04"),
+  timeZone: "UTC",
+};
+
+const CONFIG = {
+  settings: DEFAULT_SERVER_SETTINGS,
+  environment: { serverVersion: "0.0.1", capabilities: {} },
+} as ServerConfig;
+
+const makeHarness = Effect.fn("ServerUsageTest.makeHarness")(function* (
+  beforeRead: (request: number) => Effect.Effect<void> = () => Effect.void,
+) {
+  const events = yield* Queue.unbounded<ServerConfigStreamEvent>();
+  let settings = DEFAULT_SERVER_SETTINGS;
+  let requests = 0;
+  const client = {
+    [WS_METHODS.subscribeServerConfig]: () =>
+      Stream.concat(
+        Stream.make({ version: 1 as const, type: "snapshot" as const, config: CONFIG }),
+        Stream.fromQueue(events),
+      ),
+    [WS_METHODS.serverGetUsageSummary]: (input: UsageSummaryInput) =>
+      Effect.gen(function* () {
+        requests += 1;
+        const price = settings.usagePriceOverrides["custom-model"]?.inputCostPerMillionTokens ?? 0;
+        yield* beforeRead(requests);
+        return {
+          contractVersion: USAGE_CONTRACT_VERSION,
+          readAt: "2026-09-04T12:00:00Z",
+          ...input,
+          buckets: [
+            {
+              day: input.sinceDay,
+              provider: "codex",
+              model: "custom-model",
+              totals: {
+                uncachedInputTokens: 1_000_000,
+                cachedInputTokens: 0,
+                cacheCreationTokens: 0,
+                outputTokens: 0,
+                reasoningTokens: 0,
+              },
+              costUsd: price,
+              cacheSavingsUsd: 0,
+              costSource: price === 0 ? "unpriced" : "modelPriced",
+              records: 1,
+              unpricedRecords: price === 0 ? 1 : 0,
+              sessions: 1,
+            },
+          ],
+          sources: [],
+          pricing: { status: "unavailable", source: "test", fetchedAt: null, knownModels: 0 },
+          scanDurationMs: 0,
+        } satisfies UsageSummary;
+      }),
+  } as unknown as WsRpcProtocolClient;
+  const session: RpcSession = {
+    client,
+    initialConfig: Effect.succeed(CONFIG),
+    subscribeServerConfig: (input) => client.subscribeServerConfig(input),
+    ready: Effect.void,
+    probe: Effect.void,
+    closed: Effect.never,
+  };
+  const supervisor = EnvironmentSupervisor.of({
+    target: TARGET,
+    state: yield* SubscriptionRef.make<SupervisorConnectionState>({
+      ...AVAILABLE_CONNECTION_STATE,
+      phase: "connected",
+    }),
+    session: yield* SubscriptionRef.make(Option.some(session)),
+    prepared: yield* SubscriptionRef.make(Option.none<PreparedConnection>()),
+    connect: Effect.void,
+    disconnect: Effect.void,
+    retryNow: Effect.void,
+  });
+  const environments = EnvironmentRegistry.of({
+    run: (_environmentId, effect) =>
+      Effect.provideService(effect, EnvironmentSupervisor, supervisor),
+    followStream: (_environmentId, stream) =>
+      Stream.provideService(stream, EnvironmentSupervisor, supervisor),
+  } as EnvironmentRegistry["Service"]);
+  const cache = EnvironmentCacheStore.of({
+    loadShell: () => Effect.succeed(Option.none()),
+    saveShell: () => Effect.void,
+    loadThread: () => Effect.succeed(Option.none()),
+    saveThread: () => Effect.void,
+    removeThread: () => Effect.void,
+    loadServerConfig: () => Effect.succeed(Option.none()),
+    saveServerConfig: () => Effect.void,
+    loadVcsRefs: () => Effect.succeed(Option.none()),
+    saveVcsRefs: () => Effect.void,
+    removeVcsRefs: () => Effect.void,
+    clearVcsRefs: () => Effect.void,
+    clear: () => Effect.void,
+  });
+  const runtime = Atom.runtime(
+    Layer.merge(
+      Layer.succeed(EnvironmentRegistry, environments),
+      Layer.succeed(EnvironmentCacheStore, cache),
+    ),
+  );
+  const initialConfigValueAtom = Atom.make(CONFIG);
+  const atoms = createServerEnvironmentAtoms(runtime, {
+    initialConfigValueAtom: () => initialConfigValueAtom,
+  });
+  const registry = yield* Effect.acquireRelease(Effect.sync(AtomRegistry.make), (registry) =>
+    Effect.sync(() => registry.dispose()),
+  );
+  const updateSettings = Effect.fn("ServerUsageTest.updateSettings")(function* (
+    next: ServerSettings,
+  ) {
+    settings = next;
+    yield* Queue.offer(events, {
+      version: 1,
+      type: "settingsUpdated",
+      payload: { settings },
+    });
+    yield* AtomRegistry.toStream(registry, atoms.settingsValueAtom(TARGET.environmentId)).pipe(
+      Stream.filter((current) => current === next),
+      Stream.runHead,
+    );
+  });
+  return {
+    registry,
+    requests: () => requests,
+    updateSettings,
+    summary: (input = INPUT) => atoms.usageSummary({ environmentId: TARGET.environmentId, input }),
+  };
+});
+
+function waitForCost<E>(
+  registry: AtomRegistry.AtomRegistry,
+  atom: Atom.Atom<AsyncResult.AsyncResult<UsageSummary, E>>,
+  cost: number,
+) {
+  return AtomRegistry.toStream(registry, atom).pipe(
+    Stream.filter(
+      (result) =>
+        AsyncResult.isSuccess(result) &&
+        !result.waiting &&
+        result.value.buckets[0]?.costUsd === cost,
+    ),
+    Stream.runHead,
+  );
+}
+
+it.effect("refreshes cached usage windows only when override prices change", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const harness = yield* makeHarness();
+      const current = harness.summary();
+      const previous = harness.summary({ ...INPUT, sinceDay: UsageDay.make("2026-08-01") });
+      const unmountCurrent = harness.registry.mount(current);
+      const unmountPrevious = harness.registry.mount(previous);
+      yield* waitForCost(harness.registry, current, 0);
+      yield* waitForCost(harness.registry, previous, 0);
+      unmountPrevious();
+      expect(harness.requests()).toBe(2);
+
+      const prices = {
+        "custom-model": { inputCostPerMillionTokens: 3, outputCostPerMillionTokens: 9 },
+        "other-model": { inputCostPerMillionTokens: 1, outputCostPerMillionTokens: 2 },
+      };
+      yield* harness.updateSettings({ ...DEFAULT_SERVER_SETTINGS, usagePriceOverrides: prices });
+      yield* waitForCost(harness.registry, current, 3);
+      yield* waitForCost(harness.registry, previous, 3);
+      expect(harness.requests()).toBe(4);
+
+      yield* harness.updateSettings({
+        ...DEFAULT_SERVER_SETTINGS,
+        usagePriceOverrides: {
+          "other-model": { outputCostPerMillionTokens: 2, inputCostPerMillionTokens: 1 },
+          "custom-model": { outputCostPerMillionTokens: 9, inputCostPerMillionTokens: 3 },
+        },
+      });
+      yield* harness.updateSettings({
+        ...DEFAULT_SERVER_SETTINGS,
+        usagePriceOverrides: prices,
+        defaultTheme: "custom-theme",
+      });
+      yield* harness.updateSettings(DEFAULT_SERVER_SETTINGS);
+      yield* waitForCost(harness.registry, current, 0);
+      yield* waitForCost(harness.registry, previous, 0);
+      expect(harness.requests()).toBe(6);
+      unmountCurrent();
+    }),
+  ),
+);
+
+it.effect("restarts a pending usage read after a price change", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const started = yield* Deferred.make<void>();
+      const interrupted = yield* Deferred.make<void>();
+      const harness = yield* makeHarness((request) =>
+        request === 1
+          ? Deferred.succeed(started, undefined).pipe(
+              Effect.andThen(Effect.never),
+              Effect.onInterrupt(() => Deferred.succeed(interrupted, undefined)),
+            )
+          : Effect.void,
+      );
+      const summary = harness.summary();
+      const unmount = harness.registry.mount(summary);
+      yield* Deferred.await(started);
+      yield* harness.updateSettings({
+        ...DEFAULT_SERVER_SETTINGS,
+        usagePriceOverrides: {
+          "custom-model": { inputCostPerMillionTokens: 5, outputCostPerMillionTokens: 10 },
+        },
+      });
+      yield* waitForCost(harness.registry, summary, 5);
+      yield* Deferred.await(interrupted);
+      expect(harness.requests()).toBe(2);
+      unmount();
+    }),
+  ),
+);
diff --git a/packages/client-runtime/src/state/session.ts b/packages/client-runtime/src/state/session.ts
index 43adb980f3ad..5ed60afc8a5e 100644
--- a/packages/client-runtime/src/state/session.ts
+++ b/packages/client-runtime/src/state/session.ts
@@ -6,14 +6,14 @@ import * as SubscriptionRef from "effect/SubscriptionRef";
 import type { HttpClient } from "effect/unstable/http";
 import { AsyncResult, Atom } from "effect/unstable/reactivity";
 
+import { RemoteEnvironmentAuthorization } from "../authorization/service.ts";
 import { EnvironmentRegistry } from "../connection/registry.ts";
 import type { PreparedConnection } from "../connection/model.ts";
 import { EnvironmentSupervisor } from "../connection/supervisor.ts";
 import { environmentEndpointUrl } from "../environment/endpoint.ts";
 import { ManagedRelayDpopSigner } from "../relay/managedRelay.ts";
 import { safeErrorLogAttributes } from "../errors/safeLog.ts";
-import { executeEnvironmentHttpRequest, makeEnvironmentHttpApiClient } from "../rpc/http.ts";
-import { buildEnvironmentAuthHeaders, withEnvironmentCredentials } from "./environmentHttpAuth.ts";
+import { executeAuthenticatedEnvironmentHttpRequest } from "./environmentHttpAuth.ts";
 import { followStreamInEnvironment } from "./runtime.ts";
 
 function initialConfigOption<E>(
@@ -36,29 +36,26 @@ const DEFAULT_SESSION_STATE_TIMEOUT_MS = 6_000;
 
 /**
  * Read the granted scopes of this client's session on one environment via its
- * `/api/auth/session` endpoint, authenticated with whatever credential the
- * connection was prepared with (cookie, bearer, or DPoP).
+ * `/api/auth/session` endpoint, using the connection's authentication method
+ * and refreshing relay credentials when needed.
  */
 export const fetchEnvironmentSessionState = Effect.fn(
   "clientRuntime.state.fetchEnvironmentSessionState",
 )(function* (input: {
   readonly prepared: PreparedConnection;
   readonly signer: Option.Option<ManagedRelayDpopSigner["Service"]>;
+  readonly remoteAuthorization?: Option.Option<RemoteEnvironmentAuthorization["Service"]>;
   readonly timeoutMs?: number;
 }) {
-  const requestUrl = environmentEndpointUrl(input.prepared.httpBaseUrl, "/api/auth/session");
-  const client = yield* makeEnvironmentHttpApiClient(input.prepared.httpBaseUrl);
-  const headers = yield* buildEnvironmentAuthHeaders(
-    input.prepared.httpAuthorization,
-    "GET",
-    requestUrl,
-    input.signer,
-  );
-  return yield* executeEnvironmentHttpRequest(
-    requestUrl,
-    input.timeoutMs ?? DEFAULT_SESSION_STATE_TIMEOUT_MS,
-    withEnvironmentCredentials(input.prepared.httpAuthorization, client.auth.session({ headers })),
-  );
+  return yield* executeAuthenticatedEnvironmentHttpRequest({
+    ...input,
+    method: "GET",
+    url: (httpBaseUrl) => environmentEndpointUrl(httpBaseUrl, "/api/auth/session"),
+    timeoutMs: input.timeoutMs ?? DEFAULT_SESSION_STATE_TIMEOUT_MS,
+    request: ({ client, headers }) => client.auth.session({ headers }),
+    // This endpoint returns 200 with authenticated:false for expired credentials.
+    isUnauthorizedResponse: (response) => !response.authenticated,
+  });
 });
 
 export function createEnvironmentSessionAtoms<R, E>(
@@ -134,7 +131,8 @@ export function createEnvironmentSessionAtoms<R, E>(
         }
         return Effect.gen(function* () {
           const signer = yield* Effect.serviceOption(ManagedRelayDpopSigner);
-          return yield* fetchEnvironmentSessionState({ prepared, signer });
+          const remoteAuthorization = yield* Effect.serviceOption(RemoteEnvironmentAuthorization);
+          return yield* fetchEnvironmentSessionState({ prepared, signer, remoteAuthorization });
         });
       })
       .pipe(
diff --git a/packages/client-runtime/src/state/sharedSettings.test.ts b/packages/client-runtime/src/state/sharedSettings.test.ts
index 8c46a9f33579..8cf0e3bc7f08 100644
--- a/packages/client-runtime/src/state/sharedSettings.test.ts
+++ b/packages/client-runtime/src/state/sharedSettings.test.ts
@@ -2,6 +2,7 @@ import { DEFAULT_SERVER_SETTINGS, EnvironmentId } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
 
 import {
+  filterSharedServerPatch,
   findSharedSettingsMismatches,
   pickSharedServerSettings,
   splitSharedServerPatch,
@@ -11,6 +12,7 @@ import {
 const primaryId = EnvironmentId.make("env-primary");
 const laptopId = EnvironmentId.make("env-laptop");
 const boxId = EnvironmentId.make("env-box");
+const restartCapabilities = { threadRestartContinuation: true };
 
 describe("supportsSharedSettingsSync", () => {
   it("accepts only connected servers that advertise the shared-settings capability", () => {
@@ -40,16 +42,24 @@ describe("splitSharedServerPatch", () => {
     const { sharedPatch, localPatch } = splitSharedServerPatch({
       sidebarAutoSettleAfterDays: 7,
       sidebarAutoSettleOnMerge: false,
+      continueThreadsAfterServerUpdate: true,
       enableAgentBrowserAccess: false,
     });
-    expect(sharedPatch).toEqual({ sidebarAutoSettleAfterDays: 7, sidebarAutoSettleOnMerge: false });
+    expect(sharedPatch).toEqual({
+      sidebarAutoSettleAfterDays: 7,
+      sidebarAutoSettleOnMerge: false,
+      continueThreadsAfterServerUpdate: true,
+    });
     expect(localPatch).toEqual({ enableAgentBrowserAccess: false });
   });
 });
 
 describe("pickSharedServerSettings", () => {
   it("returns only the shared keys", () => {
-    expect(Object.keys(pickSharedServerSettings(DEFAULT_SERVER_SETTINGS)).sort()).toEqual([
+    expect(
+      Object.keys(pickSharedServerSettings(DEFAULT_SERVER_SETTINGS, restartCapabilities)).sort(),
+    ).toEqual([
+      "continueThreadsAfterServerUpdate",
       "defaultThreadEnvMode",
       "newWorktreesStartFromOrigin",
       "sidebarAutoSettleAfterDays",
@@ -59,9 +69,106 @@ describe("pickSharedServerSettings", () => {
   });
 });
 
+describe("filterSharedServerPatch", () => {
+  it.each([true, false])("preserves supported restart preference %s", (enabled) => {
+    const patch = { continueThreadsAfterServerUpdate: enabled, sidebarAutoSettleAfterDays: 7 };
+    expect(filterSharedServerPatch(patch, restartCapabilities)).toEqual(patch);
+  });
+
+  it.each([undefined, {}, { threadRestartContinuation: false }])(
+    "omits only the unsupported restart preference with capabilities %j",
+    (capabilities) => {
+      expect(
+        filterSharedServerPatch(
+          { continueThreadsAfterServerUpdate: true, sidebarAutoSettleAfterDays: 7 },
+          capabilities,
+        ),
+      ).toEqual({ sidebarAutoSettleAfterDays: 7 });
+      expect(pickSharedServerSettings(DEFAULT_SERVER_SETTINGS, capabilities)).not.toHaveProperty(
+        "continueThreadsAfterServerUpdate",
+      );
+    },
+  );
+});
+
 describe("findSharedSettingsMismatches", () => {
   const primarySettings = { ...DEFAULT_SERVER_SETTINGS, sidebarAutoSettleAfterDays: 7 };
 
+  it.each([true, false])(
+    "detects remote restart continuation drift when the preference is %s",
+    (enabled) => {
+      const settings = { ...primarySettings, continueThreadsAfterServerUpdate: enabled };
+      const remoteSettings = { ...settings, continueThreadsAfterServerUpdate: !enabled };
+      const environment = {
+        environmentId: boxId,
+        label: "Remote Box",
+        syncEligible: true,
+        settings: remoteSettings,
+        capabilities: restartCapabilities,
+      };
+      expect(
+        findSharedSettingsMismatches({
+          primaryEnvironmentId: primaryId,
+          primarySettings: settings,
+          primaryCapabilities: restartCapabilities,
+          environments: [environment],
+        }),
+      ).toEqual([{ environmentId: boxId, label: "Remote Box" }]);
+      expect(
+        findSharedSettingsMismatches({
+          primaryEnvironmentId: primaryId,
+          primarySettings: settings,
+          primaryCapabilities: restartCapabilities,
+          environments: [
+            {
+              ...environment,
+              settings: Object.assign(
+                {},
+                remoteSettings,
+                pickSharedServerSettings(settings, restartCapabilities),
+              ),
+            },
+          ],
+        }),
+      ).toEqual([]);
+    },
+  );
+
+  it.each([
+    [undefined, restartCapabilities],
+    [restartCapabilities, undefined],
+    [undefined, undefined],
+  ])(
+    "ignores restart drift unless both servers support it (%j, %j)",
+    (primaryCapabilities, capabilities) => {
+      const environment = {
+        environmentId: boxId,
+        label: "Remote Box",
+        syncEligible: true,
+        capabilities,
+        settings: { ...primarySettings, continueThreadsAfterServerUpdate: true },
+      };
+      const input = {
+        primaryEnvironmentId: primaryId,
+        primarySettings,
+        primaryCapabilities,
+        environments: [environment],
+      };
+      expect(findSharedSettingsMismatches(input)).toEqual([]);
+      expect(
+        findSharedSettingsMismatches({
+          ...input,
+          environments: [
+            {
+              ...environment,
+              settings: { ...environment.settings, sidebarAutoSettleAfterDays: 14 },
+            },
+          ],
+        }),
+      ).toEqual([{ environmentId: boxId, label: "Remote Box" }]);
+    },
+  );
+
   it("lists sync-eligible environments whose shared settings differ", () => {
     const mismatches = findSharedSettingsMismatches({
       primaryEnvironmentId: primaryId,
diff --git a/packages/client-runtime/src/state/sharedSettings.ts b/packages/client-runtime/src/state/sharedSettings.ts
index f3236ef2035a..c578de9c7062 100644
--- a/packages/client-runtime/src/state/sharedSettings.ts
+++ b/packages/client-runtime/src/state/sharedSettings.ts
@@ -21,6 +21,7 @@ import type { EnvironmentConnectionPhase } from "../connection/presentation.ts";
 
 /** Server keys that hold a user preference rather than machine config. */
 export const SHARED_SERVER_SETTING_KEYS = [
+  "continueThreadsAfterServerUpdate",
   "sidebarAutoSettleAfterDays",
   "sidebarAutoSettleOnMerge",
   "defaultThreadEnvMode",
@@ -52,15 +53,27 @@ export function splitSharedServerPatch(patch: ServerSettingsPatch): {
   };
 }
 
-/** The shared subset of one environment's settings, as a patch that can be written elsewhere. */
-export function pickSharedServerSettings(settings: ServerSettings): ServerSettingsPatch {
-  return Struct.pick(settings, SHARED_SERVER_SETTING_KEYS);
+/** Omit restart recovery on servers that cannot persist its preference. */
+export function filterSharedServerPatch(
+  patch: ServerSettingsPatch,
+  capabilities: Pick<ExecutionEnvironmentCapabilities, "threadRestartContinuation"> | undefined,
+): ServerSettingsPatch {
+  return capabilities?.threadRestartContinuation === true
+    ? patch
+    : Struct.omit(patch, ["continueThreadsAfterServerUpdate"]);
+}
+
+/** The shared subset supported by one environment. */
+export function pickSharedServerSettings(
+  settings: ServerSettings,
+  capabilities?: Pick<ExecutionEnvironmentCapabilities, "threadRestartContinuation">,
+): ServerSettingsPatch {
+  return filterSharedServerPatch(Struct.pick(settings, SHARED_SERVER_SETTING_KEYS), capabilities);
 }
 
 /**
  * Whether an environment can participate in shared-settings sync right now.
- * Auto-settlement is the newest feature backed by a shared key, so a server
- * advertising `threadAutoSettlement` can hold every shared key.
+ * Auto-settlement establishes baseline support; newer preferences are filtered separately.
  */
 export function supportsSharedSettingsSync(environment: {
   readonly connection: { readonly phase: EnvironmentConnectionPhase };
@@ -81,12 +94,15 @@ export interface SharedSettingsEnvironment {
   readonly label: string;
   readonly syncEligible: boolean;
   readonly settings: ServerSettings | null;
+  readonly capabilities?:
+    | Pick<ExecutionEnvironmentCapabilities, "threadRestartContinuation">
+    | undefined;
 }
 
 /**
  * Shared-settings sync targets whose values differ from the primary
  * environment's. Other environments are skipped: nothing can be read from or
- * written to them, or their server cannot hold every shared key. With no
+ * written to them, or their server lacks baseline shared-settings support. With no
  * primary settings loaded there is nothing to compare against, so nothing is
  * reported. Callers must pass the real loaded settings, never a default
  * fallback, or "apply to all" would push defaults over real values.
@@ -94,12 +110,18 @@ export interface SharedSettingsEnvironment {
 export function findSharedSettingsMismatches(input: {
   readonly primaryEnvironmentId: EnvironmentId | null;
   readonly primarySettings: ServerSettings | null;
+  readonly primaryCapabilities?:
+    | Pick<ExecutionEnvironmentCapabilities, "threadRestartContinuation">
+    | undefined;
   readonly environments: ReadonlyArray<SharedSettingsEnvironment>;
 }): ReadonlyArray<{ readonly environmentId: EnvironmentId; readonly label: string }> {
   if (input.primaryEnvironmentId === null || input.primarySettings === null) {
     return [];
   }
-  const expected = pickSharedServerSettings(input.primarySettings);
+  const primarySettings = pickSharedServerSettings(
+    input.primarySettings,
+    input.primaryCapabilities,
+  );
   return input.environments.flatMap((environment) => {
     if (
       environment.environmentId === input.primaryEnvironmentId ||
@@ -108,7 +130,11 @@ export function findSharedSettingsMismatches(input: {
     ) {
       return [];
     }
-    const actual = pickSharedServerSettings(environment.settings);
+    const expected = filterSharedServerPatch(primarySettings, environment.capabilities);
+    const actual = filterSharedServerPatch(
+      pickSharedServerSettings(environment.settings, environment.capabilities),
+      input.primaryCapabilities,
+    );
     return Equal.equals(actual, expected)
       ? []
       : [{ environmentId: environment.environmentId, label: environment.label }];
diff --git a/packages/client-runtime/src/state/shellSnapshotHttp.ts b/packages/client-runtime/src/state/shellSnapshotHttp.ts
index b0a492a1305f..aa1ad9081e05 100644
--- a/packages/client-runtime/src/state/shellSnapshotHttp.ts
+++ b/packages/client-runtime/src/state/shellSnapshotHttp.ts
@@ -6,11 +6,11 @@ import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import { HttpClient } from "effect/unstable/http";
 
+import { RemoteEnvironmentAuthorization } from "../authorization/service.ts";
 import type { PreparedConnection } from "../connection/model.ts";
 import { environmentEndpointUrl } from "../environment/endpoint.ts";
 import { ManagedRelayDpopSigner } from "../relay/managedRelay.ts";
-import { executeEnvironmentHttpRequest, makeEnvironmentHttpApiClient } from "../rpc/http.ts";
-import { buildEnvironmentAuthHeaders, withEnvironmentCredentials } from "./environmentHttpAuth.ts";
+import { executeAuthenticatedEnvironmentHttpRequest } from "./environmentHttpAuth.ts";
 
 // Bounded so a pathologically slow endpoint cannot block the (cheaper) socket
 // fallback for long. The cached shell renders while this runs.
@@ -27,24 +27,16 @@ export const fetchEnvironmentShellSnapshot = Effect.fn(
 )(function* (input: {
   readonly prepared: PreparedConnection;
   readonly signer: Option.Option<ManagedRelayDpopSigner["Service"]>;
+  readonly remoteAuthorization?: Option.Option<RemoteEnvironmentAuthorization["Service"]>;
   readonly timeoutMs?: number;
 }) {
-  const requestUrl = environmentEndpointUrl(input.prepared.httpBaseUrl, "/api/orchestration/shell");
-  const client = yield* makeEnvironmentHttpApiClient(input.prepared.httpBaseUrl);
-  const headers = yield* buildEnvironmentAuthHeaders(
-    input.prepared.httpAuthorization,
-    "GET",
-    requestUrl,
-    input.signer,
-  );
-  return yield* executeEnvironmentHttpRequest(
-    requestUrl,
-    input.timeoutMs ?? DEFAULT_SHELL_SNAPSHOT_TIMEOUT_MS,
-    withEnvironmentCredentials(
-      input.prepared.httpAuthorization,
-      client.orchestration.shellSnapshot({ headers }),
-    ),
-  );
+  return yield* executeAuthenticatedEnvironmentHttpRequest({
+    ...input,
+    method: "GET",
+    url: (httpBaseUrl) => environmentEndpointUrl(httpBaseUrl, "/api/orchestration/shell"),
+    timeoutMs: input.timeoutMs ?? DEFAULT_SHELL_SNAPSHOT_TIMEOUT_MS,
+    request: ({ client, headers }) => client.orchestration.shellSnapshot({ headers }),
+  });
 });
 
 /**
@@ -73,9 +65,10 @@ export const shellSnapshotLoaderLayer: Layer.Layer<
     // Resolve the DPoP signer optionally: it is only needed for relay/DPoP
     // connections, so the loader must not hard-require it.
     const signer = yield* Effect.serviceOption(ManagedRelayDpopSigner);
+    const remoteAuthorization = yield* Effect.serviceOption(RemoteEnvironmentAuthorization);
     return ShellSnapshotLoader.of({
       load: (prepared: PreparedConnection) =>
-        fetchEnvironmentShellSnapshot({ prepared, signer }).pipe(
+        fetchEnvironmentShellSnapshot({ prepared, signer, remoteAuthorization }).pipe(
           Effect.map(Option.some<OrchestrationShellSnapshot>),
           Effect.provideService(HttpClient.HttpClient, httpClient),
           Effect.catchCause((cause) =>
diff --git a/packages/client-runtime/src/state/subagentRuntime.test.ts b/packages/client-runtime/src/state/subagentRuntime.test.ts
index e7f6965123b9..d366d7f0d4ee 100644
--- a/packages/client-runtime/src/state/subagentRuntime.test.ts
+++ b/packages/client-runtime/src/state/subagentRuntime.test.ts
@@ -5,10 +5,6 @@ import {
   foldSubagentActivities,
   formatSubagentModelLabel,
   formatSubagentTokenCount,
-  isAgentAttributedToolActivity,
-  isSubagentActivityKind,
-  isTimelineBypassActivity,
-  workflowCardMembers,
 } from "./subagentRuntime.ts";
 
 let sequence = 0;
@@ -557,64 +553,6 @@ describe("deriveAgentPanelModel", () => {
   });
 });
 
-describe("workflowCardMembers", () => {
-  it("orders by urgency (failed, running, waiting) and reports overflow", () => {
-    const roster = fold([
-      activity("task.started", { taskId: "wf-1", taskType: "local_workflow" }),
-      ...[..."abcdefghij"].map((letter, index) =>
-        activity("task.progress", {
-          taskId: `wf-1:wf:${index}`,
-          title: `agent-${letter}`,
-          status: index === 3 ? "failed" : index < 3 ? "completed" : "running",
-          ...(index === 3 ? { error: "died" } : {}),
-          parentAgentId: "wf-1",
-          agentIndex: index,
-          phaseIndex: 0,
-          phaseTitle: "Work",
-        }),
-      ),
-    ]);
-    const model = deriveAgentPanelModel({ agents: roster });
-    const { visible, overflow } = workflowCardMembers(model.workflows[0]!, 8);
-    expect(visible).toHaveLength(8);
-    expect(overflow).toBe(2);
-    expect(visible[0]!.status).toBe("failed");
-    expect(visible.filter((agent) => agent.status === "completed").length).toBeLessThanOrEqual(2);
-  });
-});
-
-describe("timeline predicates", () => {
-  it("recognizes subagent activity kinds as fold input", () => {
-    for (const kind of [
-      "task.started",
-      "task.progress",
-      "task.updated",
-      "task.completed",
-      "tool.progress",
-    ]) {
-      expect(isSubagentActivityKind(kind)).toBe(true);
-    }
-    expect(isSubagentActivityKind("tool.completed")).toBe(false);
-  });
-
-  it("attributed tool rows are re-homed; unattributed rows stay in the timeline", () => {
-    expect(isAgentAttributedToolActivity(activity("tool.completed", { agentId: "task-1" }))).toBe(
-      true,
-    );
-    expect(isAgentAttributedToolActivity(activity("tool.completed", {}))).toBe(false);
-    expect(isAgentAttributedToolActivity(activity("tool.completed", { agentId: "  " }))).toBe(
-      false,
-    );
-  });
-
-  it("timelineBypass rows never render in the parent chat", () => {
-    expect(isTimelineBypassActivity(activity("task.progress", { timelineBypass: true }))).toBe(
-      true,
-    );
-    expect(isTimelineBypassActivity(activity("task.progress", {}))).toBe(false);
-  });
-});
-
 describe("formatSubagentTokenCount", () => {
   it("formats plain counters", () => {
     expect(formatSubagentTokenCount(950)).toBe("950");
diff --git a/packages/client-runtime/src/state/subagentRuntime.ts b/packages/client-runtime/src/state/subagentRuntime.ts
index 532cda20d050..e441de32db48 100644
--- a/packages/client-runtime/src/state/subagentRuntime.ts
+++ b/packages/client-runtime/src/state/subagentRuntime.ts
@@ -861,61 +861,6 @@ export function deriveAgentPanelModel({
   };
 }
 
-/**
- * Members ordered by urgency for the capped inline workflow card: running and
- * failed first, then waiting, then most recently updated.
- */
-export function workflowCardMembers(
-  group: AgentPanelWorkflowGroup,
-  limit: number,
-): { readonly visible: ReadonlyArray<RuntimeSubagent>; readonly overflow: number } {
-  const all = [...group.phases.flatMap((phase) => phase.members), ...group.unphasedMembers];
-  const urgency = (agent: RuntimeSubagent): number => {
-    if (agent.status === "failed") return 0;
-    if (agent.status === "running") return 1;
-    if (agent.status === "waiting") return 2;
-    return 3;
-  };
-  const ordered = all
-    .slice()
-    .sort((a, b) => urgency(a) - urgency(b) || b.updatedAt.localeCompare(a.updatedAt));
-  return {
-    visible: ordered.slice(0, limit),
-    overflow: Math.max(0, ordered.length - limit),
-  };
-}
-
-/** Kinds the timeline should not render as generic rows (fold input only). */
-export function isSubagentActivityKind(kind: string): boolean {
-  return (
-    kind === "task.started" ||
-    kind === "task.progress" ||
-    kind === "task.updated" ||
-    kind === "task.completed" ||
-    kind === "tool.progress"
-  );
-}
-
-/**
- * Quiet-timeline guarantee: tool rows attributed to an owning agent belong in
- * the Agents surface, not the parent chat. Unattributed rows must stay.
- */
-export function isAgentAttributedToolActivity(activity: OrchestrationThreadActivity): boolean {
-  if (typeof activity.payload !== "object" || activity.payload === null) {
-    return false;
-  }
-  const payload = activity.payload as Record<string, unknown>;
-  return typeof payload.agentId === "string" && payload.agentId.trim().length > 0;
-}
-
-/** Timeline-bypassing synthesized rows (Codex children, workflow members). */
-export function isTimelineBypassActivity(activity: OrchestrationThreadActivity): boolean {
-  if (typeof activity.payload !== "object" || activity.payload === null) {
-    return false;
-  }
-  return (activity.payload as Record<string, unknown>).timelineBypass === true;
-}
-
 /**
  * Compact model chip text: strips vendor prefixes/date-or-context suffixes
  * ("claude-sonnet-5[1m]" → "sonnet-5[1m]", "claude-opus-4-20250514" →
diff --git a/packages/client-runtime/src/state/terminal.ts b/packages/client-runtime/src/state/terminal.ts
index 028f7a8c6609..3bc2bca78f0f 100644
--- a/packages/client-runtime/src/state/terminal.ts
+++ b/packages/client-runtime/src/state/terminal.ts
@@ -13,7 +13,7 @@ import { subscribe, type EnvironmentRpcInput } from "../rpc/client.ts";
 import {
   applyTerminalAttachStreamEvent,
   applyTerminalMetadataStreamEvent,
-  EMPTY_TERMINAL_BUFFER_STATE,
+  nextTerminalAttachSeedState,
 } from "./terminalSession.ts";
 
 export function createTerminalEnvironmentAtoms<R, E>(
@@ -40,8 +40,10 @@ export function createTerminalEnvironmentAtoms<R, E>(
     attach: createEnvironmentSubscriptionAtomFamily(runtime, {
       label: "environment-data:terminal:attach",
       subscribe: (input: EnvironmentRpcInput<typeof WS_METHODS.terminalAttach>) =>
-        subscribe(WS_METHODS.terminalAttach, input).pipe(
-          Stream.scan(EMPTY_TERMINAL_BUFFER_STATE, applyTerminalAttachStreamEvent),
+        Stream.suspend(() =>
+          subscribe(WS_METHODS.terminalAttach, input).pipe(
+            Stream.scan(nextTerminalAttachSeedState(), applyTerminalAttachStreamEvent),
+          ),
         ),
     }),
     events: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
diff --git a/packages/client-runtime/src/state/terminalOutput.ts b/packages/client-runtime/src/state/terminalOutput.ts
new file mode 100644
index 000000000000..fcb0389c434b
--- /dev/null
+++ b/packages/client-runtime/src/state/terminalOutput.ts
@@ -0,0 +1,320 @@
+export interface TerminalOutputChunk {
+  /** UTF-16 string offset within this generation and reset. */
+  readonly startOffset: number;
+  readonly data: string;
+  readonly byteLength: number;
+}
+
+export interface TerminalOutputState {
+  readonly generation: number;
+  readonly chunks: ReadonlyArray<TerminalOutputChunk>;
+  readonly retainedBytes: number;
+  readonly resetVersion: number;
+  readonly nextOffset: number;
+}
+
+export interface TerminalOutputCursor {
+  readonly generation: number;
+  readonly resetVersion: number;
+  readonly offset: number;
+}
+
+/** Forces the first `readTerminalOutputUpdate` to resynchronize from a reset. */
+export const INITIAL_TERMINAL_OUTPUT_CURSOR = Object.freeze<TerminalOutputCursor>({
+  generation: -1,
+  resetVersion: -1,
+  offset: 0,
+});
+
+export type TerminalOutputUpdate =
+  | {
+      readonly type: "none";
+      readonly cursor: TerminalOutputCursor;
+    }
+  | {
+      readonly type: "reset";
+      readonly data: string;
+      readonly cursor: TerminalOutputCursor;
+    }
+  | {
+      readonly type: "append";
+      readonly cursor: TerminalOutputCursor;
+      readonly data: string;
+    };
+
+export const DEFAULT_MAX_TERMINAL_BUFFER_BYTES = 512 * 1024;
+const DEFAULT_TERMINAL_CHUNK_BYTES = 16 * 1024;
+const MAX_TERMINAL_OUTPUT_CHUNKS = 1_024;
+const textEncoder = new TextEncoder();
+// A BOM at a retained chunk boundary is terminal data, not an encoding marker.
+const textDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
+
+export const EMPTY_TERMINAL_OUTPUT_STATE = Object.freeze<TerminalOutputState>({
+  generation: 0,
+  chunks: Object.freeze([]),
+  retainedBytes: 0,
+  resetVersion: 0,
+  nextOffset: 0,
+});
+
+interface Utf8Chunk {
+  readonly data: string;
+  readonly byteLength: number;
+}
+
+/**
+ * Split a string into chunks of at most `maxBytes` UTF-8 bytes without cutting
+ * a code point in half. The retained-output budget always supplies a positive
+ * size. Only new output is encoded on live updates.
+ *
+ * A chunk that fits whole is returned as the original string, so the common
+ * small-write path pays one encode and no decode.
+ */
+function splitStringByUtf8Bytes(data: string, maxBytes: number): ReadonlyArray<Utf8Chunk> {
+  if (data.length === 0) return [];
+
+  const encoded = textEncoder.encode(data);
+  if (encoded.byteLength <= maxBytes) {
+    return [{ data, byteLength: encoded.byteLength }];
+  }
+
+  const chunks: Utf8Chunk[] = [];
+  let offset = 0;
+  while (offset < encoded.byteLength) {
+    let end = Math.min(offset + maxBytes, encoded.byteLength);
+    while (end < encoded.byteLength && ((encoded[end] ?? 0) & 0xc0) === 0x80) {
+      end -= 1;
+    }
+    // A degenerate budget smaller than one code point still has to advance:
+    // include the whole code point rather than looping forever.
+    if (end === offset) {
+      end = Math.min(offset + maxBytes, encoded.byteLength);
+      while (end < encoded.byteLength && ((encoded[end] ?? 0) & 0xc0) === 0x80) {
+        end += 1;
+      }
+    }
+    const bytes = encoded.subarray(offset, end);
+    chunks.push({ data: textDecoder.decode(bytes), byteLength: bytes.byteLength });
+    offset = end;
+  }
+
+  return chunks;
+}
+
+function trimBufferToBytes(buffer: string, maxBufferBytes: number): string {
+  if (maxBufferBytes <= 0) {
+    return "";
+  }
+
+  const encoded = textEncoder.encode(buffer);
+  if (encoded.byteLength <= maxBufferBytes) {
+    return buffer;
+  }
+
+  let start = encoded.byteLength - maxBufferBytes;
+  while (start < encoded.length) {
+    const byte = encoded[start];
+    if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {
+      break;
+    }
+    start += 1;
+  }
+
+  return textDecoder.decode(encoded.subarray(start));
+}
+
+function splitOutputChunks(
+  data: string,
+  firstOffset: number,
+  maxChunkBytes = DEFAULT_TERMINAL_CHUNK_BYTES,
+): {
+  readonly chunks: ReadonlyArray<TerminalOutputChunk>;
+  readonly nextOffset: number;
+  readonly byteLength: number;
+} {
+  const split = splitStringByUtf8Bytes(data, maxChunkBytes);
+  let byteLength = 0;
+  let nextOffset = firstOffset;
+  const chunks = split.map((chunk) => {
+    byteLength += chunk.byteLength;
+    const startOffset = nextOffset;
+    nextOffset += chunk.data.length;
+    return {
+      startOffset,
+      data: chunk.data,
+      byteLength: chunk.byteLength,
+    };
+  });
+
+  return {
+    chunks,
+    nextOffset,
+    byteLength,
+  };
+}
+
+/**
+ * Merge adjacent chunks without changing their string positions. A reader can
+ * still append the unread suffix when its cursor falls inside a merged chunk.
+ */
+function compactRetainedChunks(chunks: ReadonlyArray<TerminalOutputChunk>) {
+  const compacted: TerminalOutputChunk[] = [];
+  for (const chunk of chunks) {
+    const previous = compacted.at(-1);
+    if (
+      previous !== undefined &&
+      previous.startOffset + previous.data.length === chunk.startOffset &&
+      previous.byteLength + chunk.byteLength <= DEFAULT_TERMINAL_CHUNK_BYTES
+    ) {
+      compacted[compacted.length - 1] = {
+        startOffset: previous.startOffset,
+        data: `${previous.data}${chunk.data}`,
+        byteLength: previous.byteLength + chunk.byteLength,
+      };
+    } else {
+      compacted.push(chunk);
+    }
+  }
+  return compacted;
+}
+
+// Scan only the removed prefix instead of encoding retained output again.
+function trimOutputChunkStart(
+  chunk: TerminalOutputChunk,
+  bytesToDrop: number,
+): TerminalOutputChunk {
+  let offset = 0;
+  let droppedBytes = 0;
+  while (droppedBytes < bytesToDrop && offset < chunk.data.length) {
+    const codepoint = chunk.data.codePointAt(offset)!;
+    droppedBytes += codepoint <= 0x7f ? 1 : codepoint <= 0x7ff ? 2 : codepoint <= 0xffff ? 3 : 4;
+    offset += codepoint <= 0xffff ? 1 : 2;
+  }
+  return {
+    ...chunk,
+    startOffset: chunk.startOffset + offset,
+    data: chunk.data.slice(offset),
+    byteLength: chunk.byteLength - droppedBytes,
+  };
+}
+
+function appendOutput(
+  current: TerminalOutputState,
+  data: string,
+  maxBufferBytes: number,
+): TerminalOutputState {
+  if (data.length === 0) return current;
+  if (maxBufferBytes <= 0) {
+    return {
+      generation: current.generation,
+      chunks: [],
+      retainedBytes: 0,
+      resetVersion: current.resetVersion + 1,
+      nextOffset: current.nextOffset + data.length,
+    };
+  }
+  const appended = splitOutputChunks(
+    data,
+    current.nextOffset,
+    Math.min(DEFAULT_TERMINAL_CHUNK_BYTES, Math.max(1, maxBufferBytes)),
+  );
+
+  const chunks = [...current.chunks, ...appended.chunks];
+  let retainedBytes = current.retainedBytes + appended.byteLength;
+  let firstRetainedIndex = 0;
+  while (retainedBytes > maxBufferBytes && firstRetainedIndex < chunks.length) {
+    const first = chunks[firstRetainedIndex]!;
+    const bytesToDrop = retainedBytes - maxBufferBytes;
+    if (bytesToDrop < first.byteLength) {
+      const trimmed = trimOutputChunkStart(first, bytesToDrop);
+      retainedBytes -= first.byteLength - trimmed.byteLength;
+      if (trimmed.byteLength > 0) {
+        chunks[firstRetainedIndex] = trimmed;
+      } else {
+        firstRetainedIndex += 1;
+      }
+      break;
+    }
+    retainedBytes -= first.byteLength;
+    firstRetainedIndex += 1;
+  }
+
+  let retainedChunks = firstRetainedIndex === 0 ? chunks : chunks.slice(firstRetainedIndex);
+  if (retainedChunks.length > MAX_TERMINAL_OUTPUT_CHUNKS) {
+    retainedChunks = compactRetainedChunks(retainedChunks);
+    const excessChunks = retainedChunks.length - MAX_TERMINAL_OUTPUT_CHUNKS;
+    if (excessChunks > 0) {
+      for (const chunk of retainedChunks.slice(0, excessChunks)) {
+        retainedBytes -= chunk.byteLength;
+      }
+      retainedChunks = retainedChunks.slice(excessChunks);
+    }
+  }
+
+  return {
+    generation: current.generation,
+    chunks: retainedChunks,
+    retainedBytes,
+    resetVersion: current.resetVersion,
+    nextOffset: appended.nextOffset,
+  };
+}
+
+function resetOutput(
+  current: TerminalOutputState,
+  data: string,
+  maxBufferBytes: number,
+): TerminalOutputState {
+  const retained = trimBufferToBytes(data, maxBufferBytes);
+  const reset = splitOutputChunks(
+    retained,
+    0,
+    Math.min(DEFAULT_TERMINAL_CHUNK_BYTES, Math.max(1, maxBufferBytes)),
+  );
+  return {
+    generation: current.generation,
+    chunks: reset.chunks,
+    retainedBytes: reset.byteLength,
+    resetVersion: current.resetVersion + 1,
+    nextOffset: reset.nextOffset,
+  };
+}
+
+export function terminalOutputText(output: TerminalOutputState): string {
+  return output.chunks.map((chunk) => chunk.data).join("");
+}
+
+export function readTerminalOutputUpdate(
+  output: TerminalOutputState,
+  cursor: TerminalOutputCursor,
+): TerminalOutputUpdate {
+  const nextCursor = {
+    generation: output.generation,
+    resetVersion: output.resetVersion,
+    offset: output.nextOffset,
+  };
+  const firstChunk = output.chunks[0];
+  if (
+    cursor.generation !== output.generation ||
+    cursor.resetVersion !== output.resetVersion ||
+    cursor.offset < (firstChunk?.startOffset ?? output.nextOffset)
+  ) {
+    return { type: "reset", data: terminalOutputText(output), cursor: nextCursor };
+  }
+
+  const appended = output.chunks.filter(
+    (chunk) => chunk.startOffset + chunk.data.length > cursor.offset,
+  );
+  if (appended.length === 0) {
+    return { type: "none", cursor: nextCursor };
+  }
+  return {
+    type: "append",
+    data: appended
+      .map((chunk) => chunk.data.slice(Math.max(0, cursor.offset - chunk.startOffset)))
+      .join(""),
+    cursor: nextCursor,
+  };
+}
+
+export { appendOutput, resetOutput };
diff --git a/packages/client-runtime/src/state/terminalSession.test.ts b/packages/client-runtime/src/state/terminalSession.test.ts
index 85c57592d118..3c9486b288a3 100644
--- a/packages/client-runtime/src/state/terminalSession.test.ts
+++ b/packages/client-runtime/src/state/terminalSession.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vite-plus/test";
+import { describe, expect, it, vi } from "vite-plus/test";
 
 import { EnvironmentId, TerminalSessionSnapshot, ThreadId } from "@t3tools/contracts";
 
@@ -6,8 +6,13 @@ import {
   applyTerminalAttachStreamEvent,
   applyTerminalMetadataStreamEvent,
   combineTerminalSessionState,
+  DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
   EMPTY_TERMINAL_BUFFER_STATE,
+  INITIAL_TERMINAL_OUTPUT_CURSOR,
+  nextTerminalAttachSeedState,
+  readTerminalOutputUpdate,
   selectRunningSubprocessTerminalIds,
+  terminalOutputText,
 } from "./terminalSession.ts";
 
 const TARGET = {
@@ -126,11 +131,49 @@ describe("terminal session reducers", () => {
     );
 
     expect(output).toMatchObject({
-      buffer: "lo world",
       status: "running",
       error: null,
       version: 2,
     });
+    expect(terminalOutputText(output.output)).toBe("lo world");
+  });
+
+  it("does not advance the lifecycle for the initial attach snapshot", () => {
+    const snapshot = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: BASE_SNAPSHOT,
+    });
+
+    expect(snapshot).toMatchObject({ status: "running", lifecycleVersion: 0 });
+  });
+
+  it("advances the lifecycle for a live started snapshot", () => {
+    const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: BASE_SNAPSHOT,
+    });
+    const started = applyTerminalAttachStreamEvent(initial, {
+      type: "snapshot",
+      snapshot: { ...BASE_SNAPSHOT, pid: 456 },
+    });
+
+    expect(started).toMatchObject({ status: "running", lifecycleVersion: 1 });
+  });
+
+  it("advances the lifecycle when a running terminal restarts in place", () => {
+    const snapshot = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: BASE_SNAPSHOT,
+    });
+    const restarted = applyTerminalAttachStreamEvent(snapshot, {
+      type: "restarted",
+      threadId: TARGET.threadId,
+      terminalId: TARGET.terminalId,
+      snapshot: { ...BASE_SNAPSHOT, pid: 456 },
+    });
+
+    expect(snapshot).toMatchObject({ status: "running", lifecycleVersion: 0 });
+    expect(restarted).toMatchObject({ status: "running", lifecycleVersion: 1 });
   });
 
   it("reduces terminal metadata snapshots, upserts, and removals", () => {
@@ -182,6 +225,270 @@ describe("terminal session reducers", () => {
       4,
     );
 
-    expect(state.buffer).toBe("🙂");
+    expect(terminalOutputText(state.output)).toBe("🙂");
+  });
+
+  it("preserves a BOM code point at a new output chunk boundary", () => {
+    const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: { ...BASE_SNAPSHOT, history: "" },
+    });
+    const cursor = readTerminalOutputUpdate(initial.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
+    const data = `${"x".repeat(16_384)}\uFEFF${"y".repeat(20)}`;
+    const state = applyTerminalAttachStreamEvent(initial, {
+      type: "output",
+      threadId: TARGET.threadId,
+      terminalId: TARGET.terminalId,
+      data,
+    });
+
+    expect(terminalOutputText(state.output)).toBe(data);
+    expect(readTerminalOutputUpdate(state.output, cursor)).toMatchObject({ type: "append", data });
+    expect(state.output.retainedBytes).toBe(new TextEncoder().encode(data).byteLength);
+  });
+
+  it("preserves a leading BOM in the retained snapshot tail", () => {
+    const state = applyTerminalAttachStreamEvent(
+      EMPTY_TERMINAL_BUFFER_STATE,
+      { type: "snapshot", snapshot: { ...BASE_SNAPSHOT, history: "discard\uFEFFtail" } },
+      7,
+    );
+
+    expect(terminalOutputText(state.output)).toBe("\uFEFFtail");
+    expect(state.output.retainedBytes).toBe(7);
+  });
+
+  it("trims whole Unicode code points from a partially retained chunk", () => {
+    let state = applyTerminalAttachStreamEvent(
+      EMPTY_TERMINAL_BUFFER_STATE,
+      { type: "snapshot", snapshot: { ...BASE_SNAPSHOT, history: "é界🙂end" } },
+      12,
+    );
+    let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
+    for (const [data, expected, retainedBytes] of [
+      ["x", "界🙂endx", 11],
+      ["yz", "🙂endxyz", 10],
+      ["abc", "endxyzabc", 9],
+    ] as const) {
+      state = applyTerminalAttachStreamEvent(
+        state,
+        { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data },
+        12,
+      );
+      const update = readTerminalOutputUpdate(state.output, cursor);
+      expect(update).toMatchObject({ type: "append", data });
+      expect(terminalOutputText(state.output)).toBe(expected);
+      expect(state.output.retainedBytes).toBe(retainedBytes);
+      cursor = update.cursor;
+    }
+  });
+
+  it("delivers all output when several events arrive before a renderer reads", () => {
+    const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: BASE_SNAPSHOT,
+    });
+    const cursor = readTerminalOutputUpdate(initial.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
+    let state = initial;
+    for (const data of [" one", " two", " three"]) {
+      state = applyTerminalAttachStreamEvent(state, {
+        type: "output",
+        threadId: TARGET.threadId,
+        terminalId: TARGET.terminalId,
+        data,
+      });
+    }
+    const update = readTerminalOutputUpdate(state.output, cursor);
+    expect(update).toMatchObject({ type: "append", data: " one two three" });
+    expect(readTerminalOutputUpdate(state.output, update.cursor).type).toBe("none");
+  });
+
+  it("preserves the byte-limited tail and resets a cursor before a partially trimmed chunk", () => {
+    const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: { ...BASE_SNAPSHOT, history: "" },
+    });
+    const staleCursor = readTerminalOutputUpdate(
+      initial.output,
+      INITIAL_TERMINAL_OUTPUT_CURSOR,
+    ).cursor;
+    const first = applyTerminalAttachStreamEvent(initial, {
+      type: "output",
+      threadId: TARGET.threadId,
+      terminalId: TARGET.terminalId,
+      data: "hello",
+    });
+    const caughtUpCursor = readTerminalOutputUpdate(first.output, staleCursor).cursor;
+    const state = applyTerminalAttachStreamEvent(
+      first,
+      { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data: " world" },
+      8,
+    );
+
+    expect(readTerminalOutputUpdate(state.output, caughtUpCursor)).toMatchObject({
+      type: "append",
+      data: " world",
+    });
+    expect(readTerminalOutputUpdate(state.output, staleCursor)).toMatchObject({
+      type: "reset",
+      data: "lo world",
+    });
+    expect(state.output.retainedBytes).toBe(8);
+  });
+
+  it("does not encode retained history again when appending at the byte limit", () => {
+    let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: { ...BASE_SNAPSHOT, history: "x".repeat(DEFAULT_MAX_TERMINAL_BUFFER_BYTES) },
+    });
+    const data = "y".repeat(8192);
+    const encode = vi.spyOn(TextEncoder.prototype, "encode");
+    try {
+      for (let index = 0; index < 100; index += 1) {
+        state = applyTerminalAttachStreamEvent(state, {
+          type: "output",
+          threadId: TARGET.threadId,
+          terminalId: TARGET.terminalId,
+          data,
+        });
+      }
+      expect(encode.mock.calls.reduce((total, [text]) => total + (text?.length ?? 0), 0)).toBe(
+        data.length * 100,
+      );
+      expect(state.output.retainedBytes).toBe(DEFAULT_MAX_TERMINAL_BUFFER_BYTES);
+    } finally {
+      encode.mockRestore();
+    }
+  });
+
+  it.each([0, -1])("discards output without encoding when the byte budget is %s", (maxBytes) => {
+    const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: BASE_SNAPSHOT,
+    });
+    const cursor = readTerminalOutputUpdate(initial.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
+    const data = "x".repeat(65_536);
+    const encode = vi.spyOn(TextEncoder.prototype, "encode");
+    try {
+      const discarded = applyTerminalAttachStreamEvent(
+        initial,
+        { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data },
+        maxBytes,
+      );
+      expect(encode).not.toHaveBeenCalled();
+      expect(discarded.output.nextOffset).toBe(initial.output.nextOffset + data.length);
+      expect(discarded.output.retainedBytes).toBe(0);
+      expect(readTerminalOutputUpdate(discarded.output, cursor)).toMatchObject({
+        type: "reset",
+        data: "",
+      });
+
+      const empty = applyTerminalAttachStreamEvent(
+        initial,
+        { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data: "" },
+        maxBytes,
+      );
+      expect(empty.output).toBe(initial.output);
+      expect(encode).not.toHaveBeenCalled();
+    } finally {
+      encode.mockRestore();
+    }
+  });
+
+  it("resets for repeated snapshots, clear, and restart even when output text repeats", () => {
+    let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: BASE_SNAPSHOT,
+    });
+    let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
+    state = applyTerminalAttachStreamEvent(state, { type: "snapshot", snapshot: BASE_SNAPSHOT });
+    const repeated = readTerminalOutputUpdate(state.output, cursor);
+    expect(repeated).toMatchObject({ type: "reset", data: "hello" });
+    expect(state.version).toBe(2);
+    cursor = repeated.cursor;
+
+    state = applyTerminalAttachStreamEvent(state, {
+      type: "cleared",
+      threadId: TARGET.threadId,
+      terminalId: TARGET.terminalId,
+    });
+    const cleared = readTerminalOutputUpdate(state.output, cursor);
+    expect(cleared).toMatchObject({ type: "reset", data: "" });
+    state = applyTerminalAttachStreamEvent(state, {
+      type: "restarted",
+      threadId: TARGET.threadId,
+      terminalId: TARGET.terminalId,
+      snapshot: BASE_SNAPSHOT,
+    });
+    expect(readTerminalOutputUpdate(state.output, cleared.cursor)).toMatchObject({
+      type: "reset",
+      data: "hello",
+    });
+    expect(state.lifecycleVersion).toBe(2);
+  });
+
+  it("does not reuse a renderer cursor when a fresh attach has matching counters", () => {
+    const first = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {
+      type: "snapshot",
+      snapshot: BASE_SNAPSHOT,
+    });
+    const cursor = readTerminalOutputUpdate(first.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
+    const next = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {
+      type: "snapshot",
+      snapshot: { ...BASE_SNAPSHOT, history: "other" },
+    });
+    expect(next.output.resetVersion).toBe(first.output.resetVersion);
+    expect(next.output.nextOffset).toBe(first.output.nextOffset);
+    expect(readTerminalOutputUpdate(next.output, cursor)).toMatchObject({
+      type: "reset",
+      data: "other",
+    });
+    expect(next.lifecycleVersion).toBe(0);
+  });
+
+  it("keeps appending while compacting metadata for many small writes", () => {
+    let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: { ...BASE_SNAPSHOT, history: "" },
+    });
+    let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
+    let received = "";
+    for (let index = 0; index < 2500; index += 1) {
+      state = applyTerminalAttachStreamEvent(state, {
+        type: "output",
+        threadId: TARGET.threadId,
+        terminalId: TARGET.terminalId,
+        data: "x",
+      });
+      const update = readTerminalOutputUpdate(state.output, cursor);
+      if (update.type !== "append") throw new Error(`Expected append, received ${update.type}`);
+      received += update.data;
+      cursor = update.cursor;
+    }
+    expect(received).toBe("x".repeat(2500));
+    expect(state.output.chunks.length).toBeLessThan(1024);
+    expect(terminalOutputText(state.output)).toBe(received);
+  });
+
+  it("appends every unread character across a compaction boundary", () => {
+    let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {
+      type: "snapshot",
+      snapshot: { ...BASE_SNAPSHOT, history: "" },
+    });
+    let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;
+    const writes = Array.from({ length: 1200 }, (_, index) => ["x", "é", "界", "🙂"][index % 4]!);
+    for (const [index, data] of writes.entries()) {
+      state = applyTerminalAttachStreamEvent(state, {
+        type: "output",
+        threadId: TARGET.threadId,
+        terminalId: TARGET.terminalId,
+        data,
+      });
+      if (index === 99) cursor = readTerminalOutputUpdate(state.output, cursor).cursor;
+    }
+    expect(readTerminalOutputUpdate(state.output, cursor)).toMatchObject({
+      type: "append",
+      data: writes.slice(100).join(""),
+    });
   });
 });
diff --git a/packages/client-runtime/src/state/terminalSession.ts b/packages/client-runtime/src/state/terminalSession.ts
index ee444e36db41..55cc4eef28f6 100644
--- a/packages/client-runtime/src/state/terminalSession.ts
+++ b/packages/client-runtime/src/state/terminalSession.ts
@@ -6,23 +6,42 @@ import type {
   TerminalSummary,
   ThreadId,
 } from "@t3tools/contracts";
+import {
+  appendOutput,
+  DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
+  EMPTY_TERMINAL_OUTPUT_STATE,
+  resetOutput,
+  type TerminalOutputState,
+} from "./terminalOutput.ts";
+
+export {
+  DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
+  INITIAL_TERMINAL_OUTPUT_CURSOR,
+  readTerminalOutputUpdate,
+  terminalOutputText,
+  type TerminalOutputCursor,
+  type TerminalOutputState,
+  type TerminalOutputUpdate,
+} from "./terminalOutput.ts";
 
 export interface TerminalSessionState {
   readonly summary: TerminalSummary | null;
-  readonly buffer: string;
+  readonly output: TerminalOutputState;
   readonly status: TerminalSessionSnapshot["status"] | "closed";
   readonly error: string | null;
   readonly hasRunningSubprocess: boolean;
   readonly updatedAt: string | null;
   readonly version: number;
+  readonly lifecycleVersion: number;
 }
 
 export interface TerminalBufferState {
-  readonly buffer: string;
+  readonly output: TerminalOutputState;
   readonly status: TerminalSessionSnapshot["status"] | "closed";
   readonly error: string | null;
   readonly updatedAt: string | null;
   readonly version: number;
+  readonly lifecycleVersion: number;
 }
 
 export interface KnownTerminalSessionTarget {
@@ -45,59 +64,50 @@ export function selectRunningSubprocessTerminalIds(
 }
 
 export const EMPTY_TERMINAL_BUFFER_STATE = Object.freeze<TerminalBufferState>({
-  buffer: "",
+  output: EMPTY_TERMINAL_OUTPUT_STATE,
   status: "closed",
   error: null,
   updatedAt: null,
   version: 0,
+  lifecycleVersion: 0,
 });
 
 export const EMPTY_TERMINAL_SESSION_STATE = Object.freeze<TerminalSessionState>({
   summary: null,
-  buffer: "",
+  output: EMPTY_TERMINAL_OUTPUT_STATE,
   status: "closed",
   error: null,
   hasRunningSubprocess: false,
   updatedAt: null,
   version: 0,
+  lifecycleVersion: 0,
 });
 
-export const DEFAULT_MAX_TERMINAL_BUFFER_BYTES = 512 * 1024;
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
+let terminalAttachGeneration = 0;
 
-function trimBufferToBytes(buffer: string, maxBufferBytes: number): string {
-  if (maxBufferBytes <= 0) {
-    return "";
-  }
-
-  const encoded = textEncoder.encode(buffer);
-  if (encoded.byteLength <= maxBufferBytes) {
-    return buffer;
-  }
-
-  let start = encoded.byteLength - maxBufferBytes;
-  while (start < encoded.length) {
-    const byte = encoded[start];
-    if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {
-      break;
-    }
-    start += 1;
-  }
-
-  return textDecoder.decode(encoded.subarray(start));
+/** A reinstalled attach stream must not reuse an old renderer's output cursor. */
+export function nextTerminalAttachSeedState(): TerminalBufferState {
+  return {
+    ...EMPTY_TERMINAL_BUFFER_STATE,
+    output: {
+      ...EMPTY_TERMINAL_OUTPUT_STATE,
+      generation: ++terminalAttachGeneration,
+    },
+  };
 }
 
 export function terminalBufferStateFromSnapshot(
   snapshot: TerminalSessionSnapshot,
   maxBufferBytes: number,
+  current: TerminalBufferState = EMPTY_TERMINAL_BUFFER_STATE,
 ): TerminalBufferState {
   return {
-    buffer: trimBufferToBytes(snapshot.history, maxBufferBytes),
+    output: resetOutput(current.output, snapshot.history, maxBufferBytes),
     status: snapshot.status,
     error: null,
     updatedAt: snapshot.updatedAt,
-    version: 1,
+    version: current.version + 1,
+    lifecycleVersion: current.lifecycleVersion,
   };
 }
 
@@ -113,12 +123,13 @@ export function combineTerminalSessionState(
 ): TerminalSessionState {
   return {
     summary,
-    buffer: buffer.buffer,
+    output: buffer.output,
     status: buffer.version > 0 ? buffer.status : (summary?.status ?? buffer.status),
     error: buffer.error,
     hasRunningSubprocess: summary?.hasRunningSubprocess ?? false,
     updatedAt: latestTimestamp(summary?.updatedAt ?? null, buffer.updatedAt),
     version: buffer.version,
+    lifecycleVersion: buffer.lifecycleVersion,
   };
 }
 
@@ -129,12 +140,20 @@ export function applyTerminalAttachStreamEvent(
 ): TerminalBufferState {
   switch (event.type) {
     case "snapshot":
+      return {
+        ...terminalBufferStateFromSnapshot(event.snapshot, maxBufferBytes, current),
+        lifecycleVersion:
+          current.version === 0 ? current.lifecycleVersion : current.lifecycleVersion + 1,
+      };
     case "restarted":
-      return terminalBufferStateFromSnapshot(event.snapshot, maxBufferBytes);
+      return {
+        ...terminalBufferStateFromSnapshot(event.snapshot, maxBufferBytes, current),
+        lifecycleVersion: current.lifecycleVersion + 1,
+      };
     case "output":
       return {
         ...current,
-        buffer: trimBufferToBytes(`${current.buffer}${event.data}`, maxBufferBytes),
+        output: appendOutput(current.output, event.data, maxBufferBytes),
         status: current.status === "closed" ? "running" : current.status,
         error: null,
         version: current.version + 1,
@@ -142,7 +161,7 @@ export function applyTerminalAttachStreamEvent(
     case "cleared":
       return {
         ...current,
-        buffer: "",
+        output: resetOutput(current.output, "", maxBufferBytes),
         error: null,
         version: current.version + 1,
       };
diff --git a/packages/client-runtime/src/state/threadDetail.ts b/packages/client-runtime/src/state/threadDetail.ts
index 5a2ffa442e04..0233cee0e22e 100644
--- a/packages/client-runtime/src/state/threadDetail.ts
+++ b/packages/client-runtime/src/state/threadDetail.ts
@@ -15,7 +15,6 @@ import type { EnvironmentThread, EnvironmentThreadShell } from "./models.ts";
 import { scopeThread } from "./models.ts";
 import { EMPTY_ENVIRONMENT_THREAD_STATE, type EnvironmentThreadState } from "./threadState.ts";
 import { parseThreadKey, threadKey } from "./entities.ts";
-import { THREAD_STATE_IDLE_TTL_MS } from "./threadRetention.ts";
 
 const EMPTY_MESSAGES: ReadonlyArray<OrchestrationMessage> = Object.freeze([]);
 const EMPTY_ACTIVITIES: ReadonlyArray<OrchestrationThreadActivity> = Object.freeze([]);
@@ -80,10 +79,7 @@ export function createEnvironmentThreadDetailAtoms<E>(
         AsyncResult.value(get(threadStateAtom(ref.environmentId, ref.threadId))),
         () => EMPTY_ENVIRONMENT_THREAD_STATE,
       ),
-    ).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-      Atom.withLabel(`environment-thread-state-value:${key}`),
-    );
+    ).pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-state-value:${key}`));
   });
 
   const threadDetailAtomFamily = Atom.family((key: string) => {
@@ -98,22 +94,19 @@ export function createEnvironmentThreadDetailAtoms<E>(
       previousSource = source;
       previousValue = source === null ? null : scopeThread(ref.environmentId, source);
       return previousValue;
-    }).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-      Atom.withLabel(`environment-thread-detail:${key}`),
-    );
+    }).pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-detail:${key}`));
   });
 
   const threadStatusAtomFamily = Atom.family((key: string) =>
     Atom.make((get) => get(threadStateValueAtomFamily(key)).status).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
+      Atom.setIdleTTL(0),
       Atom.withLabel(`environment-thread-status:${key}`),
     ),
   );
 
   const threadErrorAtomFamily = Atom.family((key: string) =>
     Atom.make((get) => Option.getOrNull(get(threadStateValueAtomFamily(key)).error)).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
+      Atom.setIdleTTL(0),
       Atom.withLabel(`environment-thread-error:${key}`),
     ),
   );
@@ -122,58 +115,40 @@ export function createEnvironmentThreadDetailAtoms<E>(
     Atom.make(
       (get): ReadonlyArray<OrchestrationMessage> =>
         get(threadDetailAtomFamily(key))?.messages ?? EMPTY_MESSAGES,
-    ).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-      Atom.withLabel(`environment-thread-messages:${key}`),
-    ),
+    ).pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-messages:${key}`)),
   );
 
   const threadActivitiesAtomFamily = Atom.family((key: string) =>
     Atom.make(
       (get): ReadonlyArray<OrchestrationThreadActivity> =>
         get(threadDetailAtomFamily(key))?.activities ?? EMPTY_ACTIVITIES,
-    ).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-      Atom.withLabel(`environment-thread-activities:${key}`),
-    ),
+    ).pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-activities:${key}`)),
   );
 
   const threadProposedPlansAtomFamily = Atom.family((key: string) =>
     Atom.make(
       (get): ReadonlyArray<OrchestrationProposedPlan> =>
         get(threadDetailAtomFamily(key))?.proposedPlans ?? EMPTY_PROPOSED_PLANS,
-    ).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-      Atom.withLabel(`environment-thread-proposed-plans:${key}`),
-    ),
+    ).pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-proposed-plans:${key}`)),
   );
 
   const threadCheckpointsAtomFamily = Atom.family((key: string) =>
     Atom.make(
       (get): ReadonlyArray<OrchestrationCheckpointSummary> =>
         get(threadDetailAtomFamily(key))?.checkpoints ?? EMPTY_CHECKPOINTS,
-    ).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-      Atom.withLabel(`environment-thread-checkpoints:${key}`),
-    ),
+    ).pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-checkpoints:${key}`)),
   );
 
   const threadSessionAtomFamily = Atom.family((key: string) =>
     Atom.make(
       (get): OrchestrationSession | null => get(threadDetailAtomFamily(key))?.session ?? null,
-    ).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-      Atom.withLabel(`environment-thread-session:${key}`),
-    ),
+    ).pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-session:${key}`)),
   );
 
   const threadLatestTurnAtomFamily = Atom.family((key: string) =>
     Atom.make(
       (get): OrchestrationLatestTurn | null => get(threadDetailAtomFamily(key))?.latestTurn ?? null,
-    ).pipe(
-      Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-      Atom.withLabel(`environment-thread-latest-turn:${key}`),
-    ),
+    ).pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-latest-turn:${key}`)),
   );
 
   return {
diff --git a/packages/client-runtime/src/state/threadReducer.test.ts b/packages/client-runtime/src/state/threadReducer.test.ts
index 401980997663..1f52eccc94cd 100644
--- a/packages/client-runtime/src/state/threadReducer.test.ts
+++ b/packages/client-runtime/src/state/threadReducer.test.ts
@@ -380,6 +380,40 @@ describe("applyThreadDetailEvent", () => {
       }
     });
 
+    it("keeps imported replies turnless when delivered again", () => {
+      const event = {
+        ...baseEventFields,
+        sequence: 6,
+        occurredAt: "2026-04-01T06:00:00.000Z",
+        aggregateKind: "thread",
+        aggregateId: baseThread.id,
+        type: "thread.message-sent",
+        payload: {
+          threadId: baseThread.id,
+          messageId: MessageId.make("import:codex:session-1:000001"),
+          role: "assistant",
+          text: "Imported reply",
+          turnId: null,
+          streaming: false,
+          createdAt: "2026-03-01T06:00:00.000Z",
+          updatedAt: "2026-03-01T06:00:00.000Z",
+        },
+      } as const;
+
+      const imported = applyThreadDetailEvent(baseThread, event);
+      expect(imported.kind).toBe("updated");
+      if (imported.kind !== "updated") return;
+      expect(imported.thread.latestTurn).toBeNull();
+      expect(imported.thread.checkpoints).toBe(baseThread.checkpoints);
+
+      const repeated = applyThreadDetailEvent(imported.thread, { ...event, sequence: 7 });
+      expect(repeated.kind).toBe("updated");
+      if (repeated.kind !== "updated") return;
+      expect(repeated.thread.messages).toEqual(imported.thread.messages);
+      expect(repeated.thread.latestTurn).toBeNull();
+      expect(repeated.thread.checkpoints).toBe(baseThread.checkpoints);
+    });
+
     it("appends text for streaming messages", () => {
       const threadWithMessage: OrchestrationThread = {
         ...baseThread,
@@ -1129,36 +1163,149 @@ describe("applyThreadDetailEvent", () => {
   });
 
   describe("thread.turn-diff-completed", () => {
-    it("adds a checkpoint and updates latestTurn", () => {
-      const result = applyThreadDetailEvent(baseThread, {
+    it.each([null, "interrupted"] as const)(
+      "adds a checkpoint without replacing a %s turn outcome",
+      (previousState) => {
+        const result = applyThreadDetailEvent(
+          {
+            ...baseThread,
+            latestTurn:
+              previousState === null
+                ? null
+                : {
+                    turnId: TurnId.make("turn-1"),
+                    state: previousState,
+                    requestedAt: "2026-04-01T11:00:00.000Z",
+                    startedAt: "2026-04-01T11:00:00.000Z",
+                    completedAt: "2026-04-01T12:00:00.000Z",
+                    assistantMessageId: null,
+                  },
+          },
+          {
+            ...baseEventFields,
+            sequence: 13,
+            occurredAt: "2026-04-01T12:00:00.000Z",
+            aggregateKind: "thread",
+            aggregateId: ThreadId.make("thread-1"),
+            type: "thread.turn-diff-completed",
+            payload: {
+              threadId: ThreadId.make("thread-1"),
+              turnId: TurnId.make("turn-1"),
+              checkpointTurnCount: 1,
+              checkpointRef: CheckpointRef.make("ref-1"),
+              status: "ready",
+              files: [],
+              assistantMessageId: MessageId.make("msg-3"),
+              completedAt: "2026-04-01T12:00:00.000Z",
+            },
+          },
+        );
+
+        expect(result.kind).toBe("updated");
+        if (result.kind === "updated") {
+          expect(result.thread.checkpoints).toHaveLength(1);
+          expect(result.thread.latestTurn?.turnId).toBe("turn-1");
+          expect(result.thread.latestTurn?.state).toBe(previousState ?? "completed");
+        }
+      },
+    );
+  });
+
+  describe("thread.reverted", () => {
+    it("keeps imported history and removes the first live prompt at checkpoint zero", () => {
+      const threadWithImportedHistory: OrchestrationThread = {
+        ...baseThread,
+        messages: [
+          {
+            id: MessageId.make("import:codex:session-1:000000"),
+            role: "user",
+            text: "Imported prompt",
+            turnId: null,
+            streaming: false,
+            createdAt: "2026-03-01T00:00:00.000Z",
+            updatedAt: "2026-03-01T00:00:00.000Z",
+          },
+          {
+            id: MessageId.make("import:codex:session-1:000001"),
+            role: "assistant",
+            text: "Imported answer",
+            turnId: null,
+            streaming: false,
+            createdAt: "2026-03-01T00:01:00.000Z",
+            updatedAt: "2026-03-01T00:01:00.000Z",
+          },
+          {
+            id: MessageId.make("live-user-message"),
+            role: "user",
+            text: "New work",
+            turnId: null,
+            streaming: false,
+            createdAt: "2026-04-01T01:00:00.000Z",
+            updatedAt: "2026-04-01T01:00:00.000Z",
+          },
+        ],
+      };
+
+      const result = applyThreadDetailEvent(threadWithImportedHistory, {
         ...baseEventFields,
-        sequence: 13,
-        occurredAt: "2026-04-01T12:00:00.000Z",
+        sequence: 14,
+        occurredAt: "2026-04-01T02:00:00.000Z",
         aggregateKind: "thread",
         aggregateId: ThreadId.make("thread-1"),
-        type: "thread.turn-diff-completed",
-        payload: {
-          threadId: ThreadId.make("thread-1"),
-          turnId: TurnId.make("turn-1"),
-          checkpointTurnCount: 1,
-          checkpointRef: CheckpointRef.make("ref-1"),
-          status: "ready",
-          files: [],
-          assistantMessageId: MessageId.make("msg-3"),
-          completedAt: "2026-04-01T12:00:00.000Z",
-        },
+        type: "thread.reverted",
+        payload: { threadId: ThreadId.make("thread-1"), turnCount: 0 },
       });
 
       expect(result.kind).toBe("updated");
       if (result.kind === "updated") {
-        expect(result.thread.checkpoints).toHaveLength(1);
-        expect(result.thread.latestTurn?.turnId).toBe("turn-1");
-        expect(result.thread.latestTurn?.state).toBe("completed");
+        expect(result.thread.messages.map((message) => message.text)).toEqual([
+          "Imported prompt",
+          "Imported answer",
+        ]);
+      }
+    });
+
+    it("fallback-retains the earliest absolute timestamp across offsets", () => {
+      const threadWithOffsetMessages: OrchestrationThread = {
+        ...baseThread,
+        messages: [
+          {
+            id: MessageId.make("earlier-by-offset"),
+            role: "user",
+            text: "Earlier",
+            turnId: null,
+            streaming: false,
+            createdAt: "2026-04-01T10:30:00.000+02:00",
+            updatedAt: "2026-04-01T10:30:00.000+02:00",
+          },
+          {
+            id: MessageId.make("later-in-utc"),
+            role: "user",
+            text: "Later",
+            turnId: null,
+            streaming: false,
+            createdAt: "2026-04-01T09:00:00.000Z",
+            updatedAt: "2026-04-01T09:00:00.000Z",
+          },
+        ],
+      };
+
+      const result = applyThreadDetailEvent(threadWithOffsetMessages, {
+        ...baseEventFields,
+        sequence: 14,
+        occurredAt: "2026-04-01T10:00:00.000Z",
+        aggregateKind: "thread",
+        aggregateId: ThreadId.make("thread-1"),
+        type: "thread.reverted",
+        payload: { threadId: ThreadId.make("thread-1"), turnCount: 1 },
+      });
+
+      expect(result.kind).toBe("updated");
+      if (result.kind === "updated") {
+        expect(result.thread.messages.map((message) => message.id)).toEqual(["earlier-by-offset"]);
       }
     });
-  });
 
-  describe("thread.reverted", () => {
     it("filters entities to retained turns", () => {
       const threadWithData: OrchestrationThread = {
         ...baseThread,
diff --git a/packages/client-runtime/src/state/threadReducer.ts b/packages/client-runtime/src/state/threadReducer.ts
index 690c74bdea0a..c237856f90b1 100644
--- a/packages/client-runtime/src/state/threadReducer.ts
+++ b/packages/client-runtime/src/state/threadReducer.ts
@@ -12,6 +12,8 @@ import type {
   OrchestrationThreadActivity,
   TurnId,
 } from "@t3tools/contracts";
+import { isImportedAgentSessionMessageId } from "@t3tools/contracts";
+import { compareDateTimeStrings } from "@t3tools/shared/dateTime";
 
 export type ThreadDetailReducerResult =
   | { readonly kind: "updated"; readonly thread: OrchestrationThread }
@@ -521,7 +523,10 @@ export function applyThreadDetailEvent(
         (thread.latestTurn === null || thread.latestTurn.turnId === event.payload.turnId)
           ? {
               turnId: event.payload.turnId,
-              state: checkpointStatusToTurnState(event.payload.status),
+              state:
+                thread.latestTurn?.state === "interrupted"
+                  ? "interrupted"
+                  : checkpointStatusToTurnState(event.payload.status),
               requestedAt: thread.latestTurn?.requestedAt ?? event.payload.completedAt,
               startedAt: thread.latestTurn?.startedAt ?? event.payload.completedAt,
               completedAt: event.payload.completedAt,
@@ -548,7 +553,11 @@ export function applyThreadDetailEvent(
       );
 
       const retainedTurnIds = new Set(Arr.map(checkpoints, (entry) => entry.turnId));
-      const messages = retainMessagesAfterRevert(thread.messages, retainedTurnIds);
+      const messages = retainMessagesAfterRevert(
+        thread.messages,
+        retainedTurnIds,
+        event.payload.turnCount,
+      );
       const proposedPlans = pipe(
         thread.proposedPlans,
         Arr.filter((plan) => plan.turnId === null || retainedTurnIds.has(plan.turnId)),
@@ -741,16 +750,42 @@ function rebindCheckpointAssistantMessage(
 function retainMessagesAfterRevert(
   messages: ReadonlyArray<OrchestrationMessage>,
   retainedTurnIds: ReadonlySet<string>,
+  turnCount: number,
 ): OrchestrationMessage[] {
-  // Keep messages that belong to a retained turn, plus system messages and
-  // messages without a turn binding (pre-turn-0 user messages).
-  return Arr.filter(messages, (message) => {
-    if (message.role === "system") {
-      return true;
+  const retainedMessageIds = new Set<string>();
+  for (const message of messages) {
+    if (message.role === "system" || isImportedAgentSessionMessageId(message.id)) {
+      retainedMessageIds.add(message.id);
+    } else if (message.turnId !== null && retainedTurnIds.has(message.turnId)) {
+      retainedMessageIds.add(message.id);
     }
-    if (message.turnId === null) {
-      return true;
+  }
+
+  for (const role of ["user", "assistant"] as const) {
+    const retainedCount = messages.filter(
+      (message) =>
+        message.role === role &&
+        !isImportedAgentSessionMessageId(message.id) &&
+        retainedMessageIds.has(message.id),
+    ).length;
+    const missingCount = Math.max(0, turnCount - retainedCount);
+    const fallbackMessages = messages
+      .filter(
+        (message) =>
+          message.role === role &&
+          !retainedMessageIds.has(message.id) &&
+          (message.turnId === null || retainedTurnIds.has(message.turnId)),
+      )
+      .toSorted(
+        (left, right) =>
+          compareDateTimeStrings(left.createdAt, right.createdAt) ||
+          left.id.localeCompare(right.id),
+      )
+      .slice(0, missingCount);
+    for (const message of fallbackMessages) {
+      retainedMessageIds.add(message.id);
     }
-    return retainedTurnIds.has(message.turnId);
-  });
+  }
+
+  return Arr.filter(messages, (message) => retainedMessageIds.has(message.id));
 }
diff --git a/packages/client-runtime/src/state/threadRetention.ts b/packages/client-runtime/src/state/threadRetention.ts
index 119b963167cd..e921a10d31ad 100644
--- a/packages/client-runtime/src/state/threadRetention.ts
+++ b/packages/client-runtime/src/state/threadRetention.ts
@@ -1,3 +1,3 @@
-// Mobile thread routes unmount during back navigation. Retain the stream-backed
-// state across short subscriber gaps without keeping every opened thread alive.
-export const THREAD_STATE_IDLE_TTL_MS = 5 * 60_000;
+// Keep recent thread snapshots for back navigation. Live subscriptions end
+// when the last detail consumer leaves.
+export const THREAD_SNAPSHOT_IDLE_TTL_MS = 5 * 60_000;
diff --git a/packages/client-runtime/src/state/threadShell.ts b/packages/client-runtime/src/state/threadShell.ts
index 65cee0427eb0..03f92a612e4a 100644
--- a/packages/client-runtime/src/state/threadShell.ts
+++ b/packages/client-runtime/src/state/threadShell.ts
@@ -35,6 +35,26 @@ export function createEnvironmentThreadShellAtoms(input: {
     environmentId: EnvironmentId,
   ) => Atom.Atom<OrchestrationShellSnapshot | null>;
 }) {
+  // Point reads and aggregate lists share values without keeping an atom alive
+  // for every listed thread. Replaced source objects can be collected.
+  const scopedThreads = new WeakMap<
+    OrchestrationThreadShell,
+    Map<EnvironmentId, EnvironmentThreadShell>
+  >();
+  const scopedThread = (environmentId: EnvironmentId, thread: OrchestrationThreadShell) => {
+    let byEnvironment = scopedThreads.get(thread);
+    if (byEnvironment === undefined) {
+      byEnvironment = new Map();
+      scopedThreads.set(thread, byEnvironment);
+    }
+    let value = byEnvironment.get(environmentId);
+    if (value === undefined) {
+      value = scopeThreadShell(environmentId, thread);
+      byEnvironment.set(environmentId, value);
+    }
+    return value;
+  };
+
   const environmentThreadsAtom = Atom.family((environmentId: EnvironmentId) =>
     Atom.make(
       (get): ReadonlyArray<OrchestrationThreadShell> =>
@@ -95,6 +115,16 @@ export function createEnvironmentThreadShellAtoms(input: {
           previousRefs !== undefined && threadRefsEqual(previousRefs, refs) ? previousRefs : refs,
         );
       }
+      const previousProjectIds = [...previous.keys()];
+      if (
+        next.size === previous.size &&
+        [...next].every(
+          ([projectId, refs], index) =>
+            previousProjectIds[index] === projectId && previous.get(projectId) === refs,
+        )
+      ) {
+        return previous;
+      }
       previous = next;
       return previous;
     }).pipe(Atom.withLabel(`environment-thread-refs-by-project:${environmentId}`));
@@ -102,16 +132,9 @@ export function createEnvironmentThreadShellAtoms(input: {
 
   const threadShellAtomFamily = Atom.family((key: string) => {
     const ref = parseThreadKey(key);
-    let previousSource: OrchestrationThreadShell | null = null;
-    let previousValue: EnvironmentThreadShell | null = null;
     return Atom.make((get) => {
       const source = get(environmentThreadIndexAtom(ref.environmentId)).get(ref.threadId) ?? null;
-      if (source === previousSource) {
-        return previousValue;
-      }
-      previousSource = source;
-      previousValue = source === null ? null : scopeThreadShell(ref.environmentId, source);
-      return previousValue;
+      return source === null ? null : scopedThread(ref.environmentId, source);
     }).pipe(Atom.withLabel(`environment-thread-shell:${key}`));
   });
 
@@ -126,15 +149,17 @@ export function createEnvironmentThreadShellAtoms(input: {
           get(environmentThreadRefsByProjectAtom(projectRef.environmentId)).get(
             projectRef.projectId,
           ) ?? EMPTY_SCOPED_THREAD_REFS;
+        if (refs.length === 0) continue;
+        const threads = get(environmentThreadIndexAtom(projectRef.environmentId));
         for (const ref of refs) {
           const key = threadKey(ref);
           if (seen.has(key)) {
             continue;
           }
           seen.add(key);
-          const thread = get(threadShellAtomFamily(key));
-          if (thread !== null) {
-            next.push(thread);
+          const thread = threads.get(ref.threadId);
+          if (thread !== undefined) {
+            next.push(scopedThread(ref.environmentId, thread));
           }
         }
       }
@@ -161,10 +186,12 @@ export function createEnvironmentThreadShellAtoms(input: {
 
   let previousThreadShells: ReadonlyArray<EnvironmentThreadShell> = [];
   const threadShellsAtom = Atom.make((get) => {
-    const next = get(threadRefsAtom).flatMap((ref) => {
-      const thread = get(threadShellAtomFamily(threadKey(ref)));
-      return thread === null ? [] : [thread];
-    });
+    const next: EnvironmentThreadShell[] = [];
+    for (const environmentId of get(input.catalogValueAtom).entries.keys()) {
+      for (const thread of get(environmentThreadsAtom(environmentId))) {
+        next.push(scopedThread(environmentId, thread));
+      }
+    }
     if (arrayElementsEqual(previousThreadShells, next)) {
       return previousThreadShells;
     }
diff --git a/packages/client-runtime/src/state/threadSnapshotHttp.ts b/packages/client-runtime/src/state/threadSnapshotHttp.ts
index 6acc3b5d8a4f..a82d4c1555c1 100644
--- a/packages/client-runtime/src/state/threadSnapshotHttp.ts
+++ b/packages/client-runtime/src/state/threadSnapshotHttp.ts
@@ -6,15 +6,12 @@ import * as Layer from "effect/Layer";
 import * as Option from "effect/Option";
 import { HttpClient } from "effect/unstable/http";
 
+import { RemoteEnvironmentAuthorization } from "../authorization/service.ts";
 import type { PreparedConnection } from "../connection/model.ts";
 import { environmentEndpointUrl } from "../environment/endpoint.ts";
 import { ManagedRelayDpopSigner } from "../relay/managedRelay.ts";
-import {
-  executeEnvironmentHttpRequest,
-  makeEnvironmentHttpApiClient,
-  type RemoteEnvironmentRequestError,
-} from "../rpc/http.ts";
-import { buildEnvironmentAuthHeaders, withEnvironmentCredentials } from "./environmentHttpAuth.ts";
+import type { RemoteEnvironmentRequestError } from "../rpc/http.ts";
+import { executeAuthenticatedEnvironmentHttpRequest } from "./environmentHttpAuth.ts";
 
 // Bounded so a pathologically slow endpoint cannot block the (cheaper) socket
 // fallback for long. The cached thread renders while this runs, so the wait only
@@ -42,25 +39,17 @@ export const fetchEnvironmentThreadSnapshot = Effect.fn(
   readonly prepared: PreparedConnection;
   readonly threadId: ThreadId;
   readonly signer: Option.Option<ManagedRelayDpopSigner["Service"]>;
+  readonly remoteAuthorization?: Option.Option<RemoteEnvironmentAuthorization["Service"]>;
   readonly timeoutMs?: number;
   readonly window?: ThreadSnapshotWindow;
 }) {
-  const requestUrl = environmentEndpointUrl(
-    input.prepared.httpBaseUrl,
-    `/api/orchestration/threads/${input.threadId}`,
-  );
-  const client = yield* makeEnvironmentHttpApiClient(input.prepared.httpBaseUrl);
-  const headers = yield* buildEnvironmentAuthHeaders(
-    input.prepared.httpAuthorization,
-    "GET",
-    requestUrl,
-    input.signer,
-  );
-  return yield* executeEnvironmentHttpRequest(
-    requestUrl,
-    input.timeoutMs ?? DEFAULT_THREAD_SNAPSHOT_TIMEOUT_MS,
-    withEnvironmentCredentials(
-      input.prepared.httpAuthorization,
+  return yield* executeAuthenticatedEnvironmentHttpRequest({
+    ...input,
+    method: "GET",
+    url: (httpBaseUrl) =>
+      environmentEndpointUrl(httpBaseUrl, `/api/orchestration/threads/${input.threadId}`),
+    timeoutMs: input.timeoutMs ?? DEFAULT_THREAD_SNAPSHOT_TIMEOUT_MS,
+    request: ({ client, headers }) =>
       client.orchestration.threadSnapshot({
         params: { threadId: input.threadId },
         payload: {
@@ -71,8 +60,7 @@ export const fetchEnvironmentThreadSnapshot = Effect.fn(
         },
         headers,
       }),
-    ),
-  );
+  });
 });
 
 export type FetchEnvironmentThreadSnapshotError = RemoteEnvironmentRequestError;
@@ -106,12 +94,14 @@ export const threadSnapshotLoaderLayer: Layer.Layer<
     // connections, so the loader must not hard-require it (bearer/primary
     // connections work without one).
     const signer = yield* Effect.serviceOption(ManagedRelayDpopSigner);
+    const remoteAuthorization = yield* Effect.serviceOption(RemoteEnvironmentAuthorization);
     return ThreadSnapshotLoader.of({
       load: (prepared: PreparedConnection, threadId: ThreadId, window?: ThreadSnapshotWindow) =>
         fetchEnvironmentThreadSnapshot({
           prepared,
           threadId,
           signer,
+          remoteAuthorization,
           ...(window !== undefined ? { window } : {}),
         }).pipe(
           Effect.map(Option.some<OrchestrationThreadDetailSnapshot>),
diff --git a/packages/client-runtime/src/state/threads-atoms.test.ts b/packages/client-runtime/src/state/threads-atoms.test.ts
index 0a9b2cd21b18..27229a7aff61 100644
--- a/packages/client-runtime/src/state/threads-atoms.test.ts
+++ b/packages/client-runtime/src/state/threads-atoms.test.ts
@@ -1,26 +1,503 @@
-import { EnvironmentId, ThreadId } from "@t3tools/contracts";
-import { describe, expect, it } from "@effect/vitest";
+import {
+  EnvironmentId,
+  EventId,
+  MessageId,
+  ORCHESTRATION_WS_METHODS,
+  ProjectId,
+  ProviderInstanceId,
+  ThreadId,
+  type OrchestrationThread,
+  type OrchestrationThreadDetailSnapshot,
+  type OrchestrationThreadStreamItem,
+} from "@t3tools/contracts";
+import { afterEach, describe, expect, it, vi } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
-import { Atom } from "effect/unstable/reactivity";
+import * as Option from "effect/Option";
+import * as Queue from "effect/Queue";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
+import { Atom, AtomRegistry } from "effect/unstable/reactivity";
 
-import type { EnvironmentRegistry } from "../connection/registry.ts";
-import type { EnvironmentCacheStore } from "../platform/persistence.ts";
-import { THREAD_STATE_IDLE_TTL_MS } from "./threadRetention.ts";
-import { createEnvironmentThreadStateAtoms, type ThreadSnapshotLoader } from "./threads.ts";
+import type { ConnectionCatalogEntry } from "../connection/catalog.ts";
+import { EnvironmentRegistry } from "../connection/registry.ts";
+import {
+  AVAILABLE_CONNECTION_STATE,
+  PrimaryConnectionTarget,
+  type NetworkStatus,
+  type PreparedConnection,
+  type SupervisorConnectionState,
+} from "../connection/model.ts";
+import { EnvironmentSupervisor } from "../connection/supervisor.ts";
+import { EnvironmentCacheStore } from "../platform/persistence.ts";
+import type { WsRpcProtocolClient } from "../rpc/protocol.ts";
+import type { RpcSession } from "../rpc/session.ts";
+import { createEnvironmentThreadDetailAtoms } from "./threadDetail.ts";
+import { THREAD_SNAPSHOT_IDLE_TTL_MS } from "./threadRetention.ts";
+import type { ThreadSnapshotWindow } from "./threadSnapshotHttp.ts";
+import {
+  createEnvironmentThreadStateAtoms,
+  requestOlderThreadTurns,
+  ThreadSnapshotLoader,
+  type EnvironmentThreadState,
+} from "./threads.ts";
+
+const TARGET = new PrimaryConnectionTarget({
+  environmentId: EnvironmentId.make("environment-1"),
+  label: "Test environment",
+  httpBaseUrl: "https://environment.example.test",
+  wsBaseUrl: "wss://environment.example.test",
+});
+const THREAD_ID = ThreadId.make("thread-1");
+const THREAD: OrchestrationThread = {
+  id: THREAD_ID,
+  projectId: ProjectId.make("project-1"),
+  title: "Cached thread",
+  modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" },
+  runtimeMode: "full-access",
+  interactionMode: "default",
+  branch: "main",
+  worktreePath: null,
+  latestTurn: null,
+  createdAt: "2026-04-01T00:00:00.000Z",
+  updatedAt: "2026-04-01T00:00:00.000Z",
+  archivedAt: null,
+  settledOverride: null,
+  settledAt: null,
+  deletedAt: null,
+  messages: [],
+  proposedPlans: [],
+  activities: [],
+  checkpoints: [],
+  session: null,
+};
+const SNAPSHOT: OrchestrationThreadDetailSnapshot = { snapshotSequence: 7, thread: THREAD };
+
+const CONNECTED_STATE: SupervisorConnectionState = {
+  ...AVAILABLE_CONNECTION_STATE,
+  desired: true,
+  network: "online",
+  phase: "connected",
+  attempt: 1,
+  generation: 1,
+};
+
+const makeHarness = Effect.fn("TestThreadAtoms.makeHarness")(function* (options?: {
+  readonly snapshot?: OrchestrationThreadDetailSnapshot;
+  readonly connected?: boolean;
+}) {
+  const subscriptions = yield* Queue.unbounded<{
+    readonly afterSequence: number | undefined;
+    readonly events: Queue.Queue<OrchestrationThreadStreamItem>;
+    readonly closed: Deferred.Deferred<void>;
+  }>();
+  const olderLoads = yield* Queue.unbounded<{
+    readonly window: ThreadSnapshotWindow;
+    readonly response: Deferred.Deferred<Option.Option<OrchestrationThreadDetailSnapshot>>;
+    readonly closed: Deferred.Deferred<void>;
+  }>();
+  const snapshot = options?.snapshot ?? SNAPSHOT;
+  let httpLoads = 0;
+  let diskLoads = 0;
+  let opened = 0;
+  let active = 0;
+  const client = {
+    [ORCHESTRATION_WS_METHODS.subscribeThread]: (input: { readonly afterSequence?: number }) =>
+      Stream.unwrap(
+        Effect.gen(function* () {
+          const events = yield* Queue.unbounded<OrchestrationThreadStreamItem>();
+          const closed = yield* Deferred.make<void>();
+          yield* Effect.acquireRelease(
+            Effect.sync(() => {
+              opened += 1;
+              active += 1;
+            }),
+            () =>
+              Effect.sync(() => {
+                active -= 1;
+              }).pipe(Effect.andThen(Deferred.succeed(closed, undefined))),
+          );
+          yield* Queue.offer(subscriptions, { afterSequence: input.afterSequence, events, closed });
+          return Stream.fromQueue(events);
+        }),
+      ),
+  } as unknown as WsRpcProtocolClient;
+  const session: RpcSession = {
+    client,
+    initialConfig: Effect.succeed({
+      threadResumeCompletionMarker: true,
+      threadSnapshotPagination: true,
+    } as never),
+    subscribeServerConfig: (input) => client.subscribeServerConfig(input),
+    ready: Effect.void,
+    probe: Effect.void,
+    closed: Effect.never,
+  };
+  const connectionState = yield* SubscriptionRef.make(
+    options?.connected ? CONNECTED_STATE : AVAILABLE_CONNECTION_STATE,
+  );
+  const sessionRef = yield* SubscriptionRef.make(Option.some(session));
+  const supervisor = EnvironmentSupervisor.of({
+    target: TARGET,
+    state: connectionState,
+    session: sessionRef,
+    prepared: yield* SubscriptionRef.make<Option.Option<PreparedConnection>>(
+      Option.some({
+        environmentId: TARGET.environmentId,
+        label: TARGET.label,
+        httpBaseUrl: TARGET.httpBaseUrl,
+        socketUrl: TARGET.wsBaseUrl,
+        httpAuthorization: null,
+        target: TARGET,
+      }),
+    ),
+    connect: Effect.void,
+    disconnect: Effect.void,
+    retryNow: Effect.void,
+  });
+  const environmentRegistry = EnvironmentRegistry.of({
+    entries: yield* SubscriptionRef.make<ReadonlyMap<EnvironmentId, ConnectionCatalogEntry>>(
+      new Map(),
+    ),
+    networkStatus: yield* SubscriptionRef.make<NetworkStatus>("online"),
+    start: Effect.void,
+    register: () => Effect.die("Unexpected environment registration"),
+    registerPlatform: () => Effect.die("Unexpected environment registration"),
+    reconcilePlatform: () => Effect.die("Unexpected environment reconciliation"),
+    remove: () => Effect.die("Unexpected environment removal"),
+    removeRelayEnvironments: () => Effect.die("Unexpected environment removal"),
+    retryNow: () => Effect.void,
+    state: () => SubscriptionRef.get(supervisor.state),
+    stateChanges: () => SubscriptionRef.changes(supervisor.state),
+    run: (_environmentId, effect) =>
+      Effect.provideService(effect, EnvironmentSupervisor, supervisor),
+    runStream: (_environmentId, stream) =>
+      Stream.provideService(stream, EnvironmentSupervisor, supervisor),
+    followStream: (_environmentId, stream) =>
+      Stream.provideService(stream, EnvironmentSupervisor, supervisor),
+  });
+  const runtime = Atom.runtime(
+    Layer.mergeAll(
+      Layer.succeed(EnvironmentRegistry, environmentRegistry),
+      Layer.succeed(
+        EnvironmentCacheStore,
+        EnvironmentCacheStore.of({
+          loadShell: () => Effect.succeed(Option.none()),
+          saveShell: () => Effect.void,
+          loadThread: () =>
+            Effect.sync(() => {
+              diskLoads += 1;
+              return Option.none();
+            }),
+          saveThread: () => Effect.void,
+          removeThread: () => Effect.void,
+          loadServerConfig: () => Effect.succeed(Option.none()),
+          saveServerConfig: () => Effect.void,
+          loadVcsRefs: () => Effect.succeed(Option.none()),
+          saveVcsRefs: () => Effect.void,
+          removeVcsRefs: () => Effect.void,
+          clearVcsRefs: () => Effect.void,
+          clear: () => Effect.void,
+        }),
+      ),
+      Layer.succeed(
+        ThreadSnapshotLoader,
+        ThreadSnapshotLoader.of({
+          load: (_prepared, _threadId, window) => {
+            if (window?.beforeCursor === undefined) {
+              return Effect.sync(() => {
+                httpLoads += 1;
+                return Option.some(snapshot);
+              });
+            }
+            return Effect.gen(function* () {
+              const response =
+                yield* Deferred.make<Option.Option<OrchestrationThreadDetailSnapshot>>();
+              const closed = yield* Deferred.make<void>();
+              yield* Effect.addFinalizer(() => Deferred.succeed(closed, undefined));
+              yield* Queue.offer(olderLoads, { window, response, closed });
+              return yield* Deferred.await(response);
+            }).pipe(Effect.scoped);
+          },
+        }),
+      ),
+    ),
+  );
+  const raw = createEnvironmentThreadStateAtoms(runtime);
+  const details = createEnvironmentThreadDetailAtoms(raw.stateAtom);
+  const ref = { environmentId: TARGET.environmentId, threadId: THREAD_ID };
+  const stateAtom = details.stateAtom(ref);
+  const makeRegistry = Effect.acquireRelease(
+    Effect.sync(() => AtomRegistry.make({ defaultIdleTTL: 60_000, timeoutResolution: 1 })),
+    (registry) => Effect.sync(() => registry.dispose()),
+  );
+  const registry = yield* makeRegistry;
+
+  return {
+    registry,
+    makeRegistry,
+    rawAtoms: raw,
+    stateAtom,
+    details,
+    ref,
+    subscriptions,
+    olderLoads,
+    connectionState,
+    session,
+    sessionRef,
+    counts: () => ({ httpLoads, diskLoads, opened, active }),
+  };
+});
+
+function observeState(
+  registry: AtomRegistry.AtomRegistry,
+  atom: Atom.Atom<EnvironmentThreadState>,
+  predicate: (state: EnvironmentThreadState) => boolean,
+) {
+  return AtomRegistry.toStream(registry, atom).pipe(
+    Stream.filter(predicate),
+    Stream.runHead,
+    Effect.map(Option.getOrThrow),
+  );
+}
+
+function currentThread(
+  registry: AtomRegistry.AtomRegistry,
+  atom: Atom.Atom<EnvironmentThreadState>,
+) {
+  return Option.getOrThrow(registry.get(atom).data);
+}
 
 describe("createEnvironmentThreadStateAtoms", () => {
-  it("retains thread state across short subscriber gaps", () => {
-    const runtime = Atom.runtime(Layer.empty) as unknown as Atom.AtomRuntime<
-      EnvironmentRegistry | EnvironmentCacheStore | ThreadSnapshotLoader,
-      never
-    >;
-    const threads = createEnvironmentThreadStateAtoms(runtime);
-    const environmentId = EnvironmentId.make("environment-1");
-    const threadId = ThreadId.make("thread-1");
-    const atom = threads.stateAtom(environmentId, threadId);
-
-    expect(atom.idleTTL).toBe(THREAD_STATE_IDLE_TTL_MS);
-    expect(threads.stateAtom(environmentId, threadId)).toBe(atom);
-    expect(threads.stateAtom(environmentId, ThreadId.make("thread-2"))).not.toBe(atom);
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
   });
+
+  it.effect("shares one live stream and closes it after the last detail consumer leaves", () =>
+    Effect.gen(function* () {
+      const h = yield* makeHarness();
+      const unmountMessages = h.registry.mount(h.details.messagesAtom(h.ref));
+      const first = yield* Queue.take(h.subscriptions);
+      const unmountStatus = h.registry.mount(h.details.statusAtom(h.ref));
+      expect(h.counts()).toEqual({ httpLoads: 1, diskLoads: 1, opened: 1, active: 1 });
+      unmountMessages();
+      yield* Queue.offer(first.events, { kind: "synchronized" });
+      yield* observeState(h.registry, h.stateAtom, (state) => state.status === "live");
+      expect(h.counts().active).toBe(1);
+      unmountStatus();
+      yield* Deferred.await(first.closed);
+      expect(h.counts().active).toBe(0);
+    }),
+  );
+
+  it.effect("keeps warm data and resumes a completed cursor without loading another snapshot", () =>
+    Effect.gen(function* () {
+      const h = yield* makeHarness();
+      const unmount = h.registry.mount(h.stateAtom);
+      const first = yield* Queue.take(h.subscriptions);
+      yield* Queue.offer(first.events, {
+        kind: "event",
+        event: {
+          type: "thread.message-sent",
+          sequence: 8,
+          eventId: EventId.make("message-1"),
+          aggregateKind: "thread",
+          aggregateId: THREAD_ID,
+          occurredAt: THREAD.createdAt,
+          commandId: null,
+          causationEventId: null,
+          correlationId: null,
+          metadata: {},
+          payload: {
+            threadId: THREAD_ID,
+            messageId: MessageId.make("message-1"),
+            role: "assistant",
+            text: "Retained text",
+            turnId: null,
+            streaming: true,
+            createdAt: THREAD.createdAt,
+            updatedAt: THREAD.createdAt,
+          },
+        },
+      });
+      yield* Queue.offer(first.events, { kind: "synchronized" });
+      yield* observeState(h.registry, h.stateAtom, (state) => state.status === "live");
+      const before = currentThread(h.registry, h.stateAtom);
+      unmount();
+      yield* Deferred.await(first.closed);
+      const remount = h.registry.mount(h.stateAtom);
+      expect(currentThread(h.registry, h.stateAtom)).toBe(before);
+      const next = yield* Queue.take(h.subscriptions);
+      expect(next.afterSequence).toBe(8);
+      expect(h.counts()).toEqual({ httpLoads: 1, diskLoads: 1, opened: 2, active: 1 });
+      remount();
+      yield* Deferred.await(next.closed);
+    }),
+  );
+
+  it.effect.each([
+    { replayed: false, statuses: ["live"] },
+    { replayed: true, statuses: ["live", "synchronizing", "live"] },
+  ])(
+    "keeps a warm resume live until it replays events (replayed: $replayed)",
+    ({ replayed, statuses }) =>
+      Effect.gen(function* () {
+        const h = yield* makeHarness({ connected: true });
+        const unmount = h.registry.mount(h.stateAtom);
+        const first = yield* Queue.take(h.subscriptions);
+        yield* Queue.offer(first.events, { kind: "synchronized" });
+        yield* observeState(h.registry, h.stateAtom, (state) => state.status === "live");
+        unmount();
+        yield* Deferred.await(first.closed);
+
+        const observed: Array<EnvironmentThreadState["status"]> = [];
+        const stop = h.registry.subscribe(h.stateAtom, (state) => observed.push(state.status), {
+          immediate: true,
+        });
+        const remount = h.registry.mount(h.stateAtom);
+        const next = yield* Queue.take(h.subscriptions);
+        expect(next.afterSequence).toBe(7);
+        if (replayed) {
+          yield* Queue.offer(next.events, {
+            kind: "snapshot",
+            snapshot: { snapshotSequence: 9, thread: { ...THREAD, title: "Replayed" } },
+          });
+          yield* observeState(h.registry, h.stateAtom, (state) => state.status === "synchronizing");
+        }
+        yield* Queue.offer(next.events, { kind: "synchronized" });
+        yield* observeState(h.registry, h.stateAtom, (state) => state.status === "live");
+        expect(observed.filter((status, index) => observed[index - 1] !== status)).toEqual(
+          statuses,
+        );
+        stop();
+        remount();
+        yield* Deferred.await(next.closed);
+      }),
+  );
+
+  it.effect("downgrades a warm resume when the connection dropped while away", () =>
+    Effect.gen(function* () {
+      const h = yield* makeHarness({ connected: true });
+      const unmount = h.registry.mount(h.stateAtom);
+      const first = yield* Queue.take(h.subscriptions);
+      yield* Queue.offer(first.events, { kind: "synchronized" });
+      yield* observeState(h.registry, h.stateAtom, (state) => state.status === "live");
+      unmount();
+      yield* Deferred.await(first.closed);
+
+      yield* SubscriptionRef.set(h.sessionRef, Option.none());
+      yield* SubscriptionRef.set(h.connectionState, AVAILABLE_CONNECTION_STATE);
+      const remount = h.registry.mount(h.stateAtom);
+      yield* observeState(h.registry, h.stateAtom, (state) => state.status === "cached");
+      expect(currentThread(h.registry, h.stateAtom)).toBe(THREAD);
+      expect(h.counts().opened).toBe(1);
+
+      yield* SubscriptionRef.set(h.connectionState, CONNECTED_STATE);
+      yield* SubscriptionRef.set(h.sessionRef, Option.some(h.session));
+      const next = yield* Queue.take(h.subscriptions);
+      expect(next.afterSequence).toBe(7);
+      expect(h.registry.get(h.stateAtom).status).toBe("synchronizing");
+      yield* Queue.offer(next.events, { kind: "synchronized" });
+      yield* observeState(h.registry, h.stateAtom, (state) => state.status === "live");
+      remount();
+      yield* Deferred.await(next.closed);
+    }),
+  );
+
+  it.effect("keeps warm data when the raw atom family's weak entry is collected", () =>
+    Effect.gen(function* () {
+      const h = yield* makeHarness();
+      const oldRaw = h.rawAtoms.stateAtom(TARGET.environmentId, THREAD_ID);
+      const unmount = h.registry.mount(h.stateAtom);
+      const first = yield* Queue.take(h.subscriptions);
+      const latest = { ...THREAD, title: "Newer cached thread" };
+      yield* Queue.offer(first.events, {
+        kind: "snapshot",
+        snapshot: { snapshotSequence: 8, thread: latest },
+      });
+      yield* Queue.offer(first.events, { kind: "synchronized" });
+      yield* observeState(h.registry, h.stateAtom, (value) => value.status === "live");
+      unmount();
+      yield* Deferred.await(first.closed);
+
+      // Force the weak-family miss without depending on host GC timing.
+      const deref = WeakRef.prototype.deref;
+      vi.spyOn(WeakRef.prototype, "deref").mockImplementation(function (this: WeakRef<object>) {
+        const value = deref.call(this);
+        return value === oldRaw ? undefined : value;
+      });
+      const remount = h.registry.mount(h.stateAtom);
+      expect(currentThread(h.registry, h.stateAtom)).toBe(latest);
+      const next = yield* Queue.take(h.subscriptions);
+      expect(next.afterSequence).toBe(8);
+      expect(h.counts()).toEqual({ httpLoads: 1, diskLoads: 1, opened: 2, active: 1 });
+      remount();
+      yield* Deferred.await(next.closed);
+    }),
+  );
+
+  it.effect("keeps cached snapshots local to each registry", () =>
+    Effect.gen(function* () {
+      const h = yield* makeHarness();
+      const unmount = h.registry.mount(h.stateAtom);
+      const first = yield* Queue.take(h.subscriptions);
+      unmount();
+      yield* Deferred.await(first.closed);
+      const otherRegistry = yield* h.makeRegistry;
+      const unmountOther = otherRegistry.mount(h.stateAtom);
+      const other = yield* Queue.take(h.subscriptions);
+      expect(h.counts()).toEqual({ httpLoads: 2, diskLoads: 2, opened: 2, active: 1 });
+      unmountOther();
+      yield* Deferred.await(other.closed);
+    }),
+  );
+
+  it.effect("expires the plain snapshot after five idle minutes", () =>
+    Effect.gen(function* () {
+      vi.useFakeTimers({ toFake: ["Date", "setTimeout", "clearTimeout"] });
+      const h = yield* makeHarness();
+      const unmount = h.registry.mount(h.stateAtom);
+      const first = yield* Queue.take(h.subscriptions);
+      unmount();
+      yield* Deferred.await(first.closed);
+      yield* Effect.yieldNow;
+      yield* Effect.promise(() => vi.advanceTimersByTimeAsync(THREAD_SNAPSHOT_IDLE_TTL_MS + 1));
+      const remount = h.registry.mount(h.stateAtom);
+      const next = yield* Queue.take(h.subscriptions);
+      expect(h.counts()).toEqual({ httpLoads: 2, diskLoads: 2, opened: 2, active: 1 });
+      remount();
+      yield* Deferred.await(next.closed);
+    }),
+  );
+
+  it.effect("cancels older-page work on unmount and permits it again on a warm return", () =>
+    Effect.gen(function* () {
+      const h = yield* makeHarness({
+        snapshot: {
+          ...SNAPSHOT,
+          page: { beforeCursor: "older-1", hasMore: true, snapshotSequence: 7 },
+        },
+      });
+      const unmount = h.registry.mount(h.stateAtom);
+      const first = yield* Queue.take(h.subscriptions);
+      expect(requestOlderThreadTurns(TARGET.environmentId, THREAD_ID)).toBe(true);
+      const older = yield* Queue.take(h.olderLoads);
+      expect(Option.getOrThrow(h.registry.get(h.stateAtom).page).loadingOlder).toBe(true);
+      unmount();
+      yield* Deferred.await(first.closed);
+      yield* Deferred.await(older.closed);
+      const remount = h.registry.mount(h.stateAtom);
+      const next = yield* Queue.take(h.subscriptions);
+      expect(Option.getOrThrow(h.registry.get(h.stateAtom).page).loadingOlder).toBe(false);
+      expect(requestOlderThreadTurns(TARGET.environmentId, THREAD_ID)).toBe(true);
+      const retried = yield* Queue.take(h.olderLoads);
+      expect(retried.window.beforeCursor).toBe("older-1");
+      expect(h.counts().httpLoads).toBe(1);
+      remount();
+      yield* Deferred.await(next.closed);
+      yield* Deferred.await(retried.closed);
+    }),
+  );
 });
diff --git a/packages/client-runtime/src/state/threads-sync.test.ts b/packages/client-runtime/src/state/threads-sync.test.ts
index d94ed3a3fd74..619b5f43425d 100644
--- a/packages/client-runtime/src/state/threads-sync.test.ts
+++ b/packages/client-runtime/src/state/threads-sync.test.ts
@@ -11,10 +11,14 @@ import {
   type OrchestrationThreadStreamItem,
 } from "@t3tools/contracts";
 import { describe, expect, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Fiber from "effect/Fiber";
 import * as Option from "effect/Option";
 import * as Queue from "effect/Queue";
 import * as Ref from "effect/Ref";
+import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
 import * as SubscriptionRef from "effect/SubscriptionRef";
 import * as TestClock from "effect/testing/TestClock";
@@ -134,6 +138,9 @@ const makeHarness = Effect.fn("TestEnvironmentThreads.makeHarness")(function* (o
   readonly cached?: OrchestrationThread;
   readonly httpSnapshot?: Option.Option<OrchestrationThreadDetailSnapshot>;
   readonly completionMarker?: boolean;
+  readonly resumeCache?: NonNullable<Parameters<typeof makeEnvironmentThreadState>[1]>;
+  readonly loadCached?: Effect.Effect<Option.Option<OrchestrationThreadDetailSnapshot>>;
+  readonly saveThread?: Persistence.EnvironmentCacheStore["Service"]["saveThread"];
 }) {
   const inputs = yield* Queue.unbounded<TestThreadInput>();
   const observed = yield* Queue.unbounded<EnvironmentThreadState>();
@@ -202,6 +209,7 @@ const makeHarness = Effect.fn("TestEnvironmentThreads.makeHarness")(function* (o
     loadShell: () => Effect.succeed(Option.none()),
     saveShell: () => Effect.void,
     loadThread: (_environmentId, threadId) =>
+      options?.loadCached ??
       Effect.succeed(
         threadId === THREAD_ID && options?.cached !== undefined
           ? Option.some({
@@ -210,8 +218,10 @@ const makeHarness = Effect.fn("TestEnvironmentThreads.makeHarness")(function* (o
             })
           : Option.none(),
       ),
-    saveThread: (_environmentId, thread) =>
-      Ref.update(savedThreads, (current) => [...current, thread]),
+    saveThread: (environmentId, thread) =>
+      Ref.update(savedThreads, (current) => [...current, thread]).pipe(
+        Effect.andThen(options?.saveThread?.(environmentId, thread) ?? Effect.void),
+      ),
     removeThread: (_environmentId, threadId) =>
       Ref.update(removedThreads, (current) => [...current, threadId]),
     loadServerConfig: () => Effect.succeed(Option.none()),
@@ -222,7 +232,7 @@ const makeHarness = Effect.fn("TestEnvironmentThreads.makeHarness")(function* (o
     clearVcsRefs: () => Effect.void,
     clear: () => Effect.void,
   });
-  const threadState = yield* makeEnvironmentThreadState(THREAD_ID).pipe(
+  const threadState = yield* makeEnvironmentThreadState(THREAD_ID, options?.resumeCache).pipe(
     Effect.provideService(EnvironmentSupervisor.EnvironmentSupervisor, supervisor),
     Effect.provideService(Persistence.EnvironmentCacheStore, cache),
     Effect.provideService(ThreadSnapshotLoader, snapshotLoader),
@@ -239,6 +249,7 @@ const makeHarness = Effect.fn("TestEnvironmentThreads.makeHarness")(function* (o
   );
 
   return {
+    threadState,
     inputs,
     observed,
     latest,
@@ -316,6 +327,271 @@ const deleted = (): OrchestrationThreadStreamItem => ({
 });
 
 describe("EnvironmentThreads", () => {
+  for (const source of ["disk", "HTTP"] as const) {
+    it.effect(`does not rewrite an unchanged ${source} snapshot on navigation or warm return`, () =>
+      Effect.gen(function* () {
+        const resumeCache: NonNullable<Parameters<typeof makeEnvironmentThreadState>[1]> = {
+          snapshot: undefined,
+          owner: undefined,
+        };
+        const firstSaved = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const h = yield* makeHarness({
+              resumeCache,
+              ...(source === "disk"
+                ? { cached: BASE_THREAD }
+                : { httpSnapshot: Option.some({ snapshotSequence: 7, thread: BASE_THREAD }) }),
+            });
+            yield* awaitThreadState(h.observed, (value) => value.status === "live");
+            if (source === "HTTP") yield* TestClock.adjust("500 millis");
+            return h.savedThreads;
+          }),
+        );
+        expect(yield* Ref.get(firstSaved)).toHaveLength(source === "disk" ? 0 : 1);
+        const nextSaved = yield* Effect.scoped(
+          Effect.gen(function* () {
+            const h = yield* makeHarness({ resumeCache });
+            yield* awaitThreadState(h.observed, (value) => value.status === "live");
+            return h.savedThreads;
+          }),
+        );
+        expect(yield* Ref.get(nextSaved)).toEqual([]);
+      }),
+    );
+  }
+
+  it.effect("retries a failed background cache write when the scope closes", () =>
+    Effect.gen(function* () {
+      let attempts = 0;
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const h = yield* makeHarness({
+            httpSnapshot: Option.some({ snapshotSequence: 7, thread: BASE_THREAD }),
+            saveThread: () =>
+              Effect.suspend(() => {
+                attempts += 1;
+                return attempts === 1
+                  ? Effect.fail(
+                      new Persistence.ConnectionPersistenceError({
+                        operation: "save-thread",
+                        message: "Test storage failure",
+                      }),
+                    )
+                  : Effect.void;
+              }),
+          });
+          yield* awaitThreadState(h.observed, (value) => value.status === "live");
+          yield* TestClock.adjust("500 millis");
+          expect(attempts).toBe(1);
+        }),
+      );
+      expect(attempts).toBe(2);
+    }),
+  );
+
+  it.effect("flushes newer data after an older background write completes", () =>
+    Effect.gen(function* () {
+      const writing = yield* Deferred.make<void>();
+      const written = yield* Deferred.make<void>();
+      const release = yield* Deferred.make<void>();
+      const saved = yield* Effect.scoped(
+        Effect.gen(function* () {
+          const h = yield* makeHarness({
+            cached: BASE_THREAD,
+            saveThread: (_environmentId, snapshot) =>
+              snapshot.snapshotSequence === 8
+                ? Deferred.succeed(writing, undefined).pipe(
+                    Effect.andThen(Deferred.await(release)),
+                    Effect.andThen(Deferred.succeed(written, undefined)),
+                  )
+                : Effect.void,
+          });
+          yield* Queue.offer(h.inputs, titleUpdated("First update", 8));
+          yield* awaitThreadState(
+            h.observed,
+            (value) => Option.getOrNull(value.data)?.title === "First update",
+          );
+          yield* TestClock.adjust("500 millis");
+          yield* Deferred.await(writing);
+          yield* Queue.offer(h.inputs, titleUpdated("Newer update", 9));
+          yield* awaitThreadState(
+            h.observed,
+            (value) => Option.getOrNull(value.data)?.title === "Newer update",
+          );
+          yield* Deferred.succeed(release, undefined);
+          yield* Deferred.await(written);
+          return h.savedThreads;
+        }),
+      );
+      expect(
+        (yield* Ref.get(saved)).map((snapshot) => [
+          snapshot.snapshotSequence,
+          snapshot.thread.title,
+        ]),
+      ).toEqual([
+        [8, "First update"],
+        [9, "Newer update"],
+      ]);
+    }),
+  );
+
+  it.effect("does not resume past a canceled event whose data was not applied", () =>
+    Effect.gen(function* () {
+      const resumeCache: NonNullable<Parameters<typeof makeEnvironmentThreadState>[1]> = {
+        snapshot: undefined,
+        owner: undefined,
+      };
+      const scope = yield* Effect.acquireRelease(Scope.make(), (scope) =>
+        Scope.close(scope, Exit.void),
+      );
+      const first = yield* makeHarness({
+        httpSnapshot: Option.some({
+          thread: BASE_THREAD,
+          snapshotSequence: CACHED_SNAPSHOT_SEQUENCE,
+        }),
+        resumeCache,
+      }).pipe(Effect.provideService(Scope.Scope, scope));
+      yield* awaitThreadState(first.observed, (value) => value.status === "live");
+      const applying = yield* Deferred.make<void>();
+      const update = titleUpdated("Not applied", 8);
+      if (update.kind !== "event") return yield* Effect.die("Expected an event");
+      Object.defineProperty(update.event.payload, "title", {
+        get: () => {
+          Deferred.doneUnsafe(applying, Exit.void);
+          return "Not applied";
+        },
+      });
+      // The reducer reads the title after it advances the cursor. Hold only
+      // the data write so closing the scope interrupts that exact interval.
+      yield* first.threadState.semaphore.take(1);
+      yield* Queue.offer(first.inputs, update);
+      yield* Deferred.await(applying);
+      yield* Scope.close(scope, Exit.void);
+      yield* first.threadState.semaphore.release(1);
+
+      const resumed = yield* makeHarness({ resumeCache });
+      const state = yield* awaitThreadState(resumed.observed, (value) => value.status === "live");
+      expect(Option.getOrThrow(state.data).title).toBe(BASE_THREAD.title);
+      expect(yield* Ref.get(resumed.lastSubscribeAfterSequence)).toBe(CACHED_SNAPSHOT_SEQUENCE);
+      expect(yield* Ref.get(first.savedThreads)).toEqual([
+        {
+          thread: BASE_THREAD,
+          snapshotSequence: CACHED_SNAPSHOT_SEQUENCE,
+        },
+      ]);
+    }),
+  );
+
+  it.effect("prevents an old scope from replacing its successor's cached data", () =>
+    Effect.gen(function* () {
+      const resumeCache: NonNullable<Parameters<typeof makeEnvironmentThreadState>[1]> = {
+        snapshot: undefined,
+        owner: undefined,
+      };
+      const oldScope = yield* Effect.acquireRelease(Scope.make(), (scope) =>
+        Scope.close(scope, Exit.void),
+      );
+      const old = yield* makeHarness({ cached: BASE_THREAD, resumeCache }).pipe(
+        Effect.provideService(Scope.Scope, oldScope),
+      );
+      yield* awaitThreadState(old.observed, (value) => value.status === "live");
+      const successor = yield* makeHarness({ resumeCache });
+      yield* Queue.offer(successor.inputs, titleUpdated("Successor title", 9));
+      yield* awaitThreadState(
+        successor.observed,
+        (value) => Option.getOrNull(value.data)?.title === "Successor title",
+      );
+      yield* Queue.offer(old.inputs, titleUpdated("Old scope title", 8));
+      yield* awaitThreadState(
+        old.observed,
+        (value) => Option.getOrNull(value.data)?.title === "Old scope title",
+      );
+      yield* Scope.close(oldScope, Exit.void);
+
+      expect(resumeCache.snapshot?.sequence).toBe(9);
+      expect(Option.getOrThrow(resumeCache.snapshot!.state.data).title).toBe("Successor title");
+      expect(yield* Ref.get(old.savedThreads)).toEqual([]);
+    }),
+  );
+
+  it.effect("does not let a delayed cache read replace an initialized successor", () =>
+    Effect.gen(function* () {
+      const resumeCache: NonNullable<Parameters<typeof makeEnvironmentThreadState>[1]> = {
+        snapshot: undefined,
+        owner: undefined,
+      };
+      const loading = yield* Deferred.make<void>();
+      const response = yield* Deferred.make<Option.Option<OrchestrationThreadDetailSnapshot>>();
+      const oldFiber = yield* makeHarness({
+        resumeCache,
+        loadCached: Deferred.succeed(loading, undefined).pipe(
+          Effect.andThen(Deferred.await(response)),
+        ),
+      }).pipe(Effect.forkScoped);
+      yield* Deferred.await(loading);
+      const successor = yield* makeHarness({ cached: BASE_THREAD, resumeCache });
+      yield* awaitThreadState(successor.observed, (value) => value.status === "live");
+      yield* Deferred.succeed(
+        response,
+        Option.some({ snapshotSequence: 3, thread: { ...BASE_THREAD, title: "Old disk data" } }),
+      );
+      const old = yield* Fiber.join(oldFiber);
+      yield* awaitThreadState(old.observed, (value) => value.status === "live");
+
+      expect(resumeCache.snapshot?.sequence).toBe(CACHED_SNAPSHOT_SEQUENCE);
+      expect(Option.getOrThrow(resumeCache.snapshot!.state.data).title).toBe(BASE_THREAD.title);
+    }),
+  );
+
+  it.effect("does not let an old deletion remove its successor's persisted cache", () =>
+    Effect.gen(function* () {
+      const resumeCache: NonNullable<Parameters<typeof makeEnvironmentThreadState>[1]> = {
+        snapshot: undefined,
+        owner: undefined,
+      };
+      const old = yield* makeHarness({ cached: BASE_THREAD, resumeCache });
+      yield* awaitThreadState(old.observed, (value) => value.status === "live");
+      const successor = yield* makeHarness({ resumeCache });
+      yield* Queue.offer(successor.inputs, titleUpdated("Successor title", 9));
+      yield* awaitThreadState(
+        successor.observed,
+        (value) => Option.getOrNull(value.data)?.title === "Successor title",
+      );
+      const update = deleted();
+      if (update.kind !== "event") return yield* Effect.die("Expected an event");
+      yield* Queue.offer(old.inputs, { ...update, event: { ...update.event, sequence: 8 } });
+      yield* awaitThreadState(old.observed, (value) => value.status === "deleted");
+
+      expect(resumeCache.snapshot?.sequence).toBe(9);
+      expect(yield* Ref.get(old.removedThreads)).toEqual([]);
+    }),
+  );
+
+  it.effect("retains a deletion instead of restoring the old disk snapshot", () =>
+    Effect.gen(function* () {
+      const resumeCache: NonNullable<Parameters<typeof makeEnvironmentThreadState>[1]> = {
+        snapshot: undefined,
+        owner: undefined,
+      };
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const first = yield* makeHarness({ cached: BASE_THREAD, resumeCache });
+          const update = deleted();
+          if (update.kind !== "event") return yield* Effect.die("Expected an event");
+          yield* Queue.offer(first.inputs, { ...update, event: { ...update.event, sequence: 8 } });
+          yield* awaitThreadState(first.observed, (value) => value.status === "deleted");
+        }),
+      );
+      const resumed = yield* makeHarness({ cached: BASE_THREAD, resumeCache });
+      const state = yield* awaitThreadState(
+        resumed.observed,
+        (value) => value.status === "deleted",
+      );
+      expect(Option.isNone(state.data)).toBe(true);
+      expect(yield* Ref.get(resumed.loaderCalls)).toBe(0);
+    }),
+  );
+
   it.effect("publishes cached data immediately from a warm cache", () =>
     Effect.gen(function* () {
       const harness = yield* makeHarness({ cached: BASE_THREAD });
diff --git a/packages/client-runtime/src/state/threads.ts b/packages/client-runtime/src/state/threads.ts
index 39561afdb416..cdd07087d06a 100644
--- a/packages/client-runtime/src/state/threads.ts
+++ b/packages/client-runtime/src/state/threads.ts
@@ -27,7 +27,7 @@ import { subscribeDynamic } from "../rpc/client.ts";
 import { ThreadSnapshotLoader, type ThreadSnapshotWindow } from "./threadSnapshotHttp.ts";
 import { parseThreadKey, threadKey } from "./entities.ts";
 import { applyThreadDetailEvent } from "./threadReducer.ts";
-import { THREAD_STATE_IDLE_TTL_MS } from "./threadRetention.ts";
+import { THREAD_SNAPSHOT_IDLE_TTL_MS } from "./threadRetention.ts";
 import { followStreamInEnvironment } from "./runtime.ts";
 import {
   EMPTY_ENVIRONMENT_THREAD_STATE,
@@ -131,40 +131,101 @@ function shouldPersistThread(thread: OrchestrationThread): boolean {
   return status !== "starting" && status !== "running";
 }
 
+interface ThreadResumeSnapshot {
+  readonly state: EnvironmentThreadState;
+  readonly sequence: number;
+  readonly persisted: boolean;
+}
+
+interface ThreadResumeCache {
+  snapshot: ThreadResumeSnapshot | undefined;
+  owner: object | undefined;
+}
+
+function matchesThreadSnapshot(
+  current: ThreadResumeSnapshot,
+  thread: OrchestrationThread | null,
+  sequence: number,
+  page: Pick<EnvironmentThreadPageState, "beforeCursor" | "hasMore"> | undefined,
+): boolean {
+  if (current.sequence !== sequence || Option.getOrNull(current.state.data) !== thread)
+    return false;
+  const currentPage = Option.getOrUndefined(current.state.page);
+  return currentPage === undefined
+    ? page === undefined
+    : page !== undefined &&
+        currentPage.beforeCursor === page.beforeCursor &&
+        currentPage.hasMore === page.hasMore;
+}
+
+// A retained "live" state stays live: the cursor resume that follows only
+// replays what the thread missed, and on servers that send the completion
+// marker the first replayed event moves the status to "synchronizing" on its
+// own. Downgrading here would flash a sync label on every return to a
+// recently viewed thread.
+function cachedThreadState(value: EnvironmentThreadState): EnvironmentThreadState {
+  return {
+    ...value,
+    status:
+      value.status === "deleted" || (value.status === "live" && Option.isSome(value.data))
+        ? value.status
+        : statusWithoutLiveData(value.data),
+    error: Option.none(),
+    page: Option.map(value.page, (page) => ({ ...page, loadingOlder: false })),
+  };
+}
+
 export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make")(function* (
   threadId: ThreadIdType,
+  resumeCache?: ThreadResumeCache,
 ) {
   const supervisor = yield* EnvironmentSupervisor;
   const cache = yield* EnvironmentCacheStore;
   const snapshotLoader = yield* ThreadSnapshotLoader;
   const wakeups = yield* Effect.serviceOption(ConnectionWakeups.ConnectionWakeups);
   const environmentId = supervisor.target.environmentId;
-  const cached = yield* cache.loadThread(environmentId, threadId).pipe(
-    Effect.catch((error) =>
-      Effect.logWarning("Could not load cached thread.").pipe(
-        Effect.annotateLogs({
-          environmentId,
-          threadId,
-          error: error.message,
-        }),
-        Effect.as(Option.none<OrchestrationThreadDetailSnapshot>()),
-      ),
-    ),
-  );
+  const retained = resumeCache?.snapshot;
+  const owner = {};
+  if (resumeCache) resumeCache.owner = owner;
+  const cached =
+    retained === undefined
+      ? yield* cache.loadThread(environmentId, threadId).pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("Could not load cached thread.").pipe(
+              Effect.annotateLogs({
+                environmentId,
+                threadId,
+                error: error.message,
+              }),
+              Effect.as(Option.none<OrchestrationThreadDetailSnapshot>()),
+            ),
+          ),
+        )
+      : Option.none<OrchestrationThreadDetailSnapshot>();
   const cachedThread = Option.map(cached, (snapshot) => snapshot.thread);
-  const state = yield* SubscriptionRef.make<EnvironmentThreadState>({
-    data: cachedThread,
-    status: statusWithoutLiveData(cachedThread),
-    error: Option.none(),
-    // A cached windowed snapshot restores its page cursor so "load earlier"
-    // works while rendering from cache; a cached full snapshot has no page.
-    page: Option.flatMap(cached, (snapshot) => pageStateFromSnapshot(snapshot.page)),
-  });
+  const initialState: EnvironmentThreadState = retained
+    ? cachedThreadState(retained.state)
+    : {
+        data: cachedThread,
+        status: statusWithoutLiveData(cachedThread),
+        error: Option.none(),
+        // A cached windowed snapshot restores its page cursor so "load earlier"
+        // works while rendering from cache; a cached full snapshot has no page.
+        page: Option.flatMap(cached, (snapshot) => pageStateFromSnapshot(snapshot.page)),
+      };
+  const state = yield* SubscriptionRef.make(initialState);
   // Seed the resume cursor from the cached snapshot so a warm cache can catch up
   // via `afterSequence` instead of re-downloading the full thread body.
-  const lastSequence = yield* SubscriptionRef.make(
-    Option.match(cached, { onNone: () => 0, onSome: (snapshot) => snapshot.snapshotSequence }),
-  );
+  const initialSequence =
+    retained?.sequence ??
+    Option.match(cached, { onNone: () => 0, onSome: (snapshot) => snapshot.snapshotSequence });
+  const lastSequence = yield* SubscriptionRef.make(initialSequence);
+  let committed: ThreadResumeSnapshot = {
+    state: initialState,
+    sequence: initialSequence,
+    persisted: retained?.persisted ?? Option.isSome(cached),
+  };
+  if (resumeCache?.owner === owner) resumeCache.snapshot = committed;
   const awaitingCompletion = yield* Ref.make(false);
   // Bumped whenever loaded history may have been rewritten out from under an
   // in-flight older-page fetch (snapshot replacement, revert, deletion). A
@@ -174,6 +235,25 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
   // merges. Without it, a revert or snapshot processed between loadOlderTurns'
   // epoch check and its merge could still slip resurrected history in.
   const applyLock = yield* Semaphore.make(1);
+  // Save only completed data/cursor updates. A canceled scope must not cache
+  // a cursor whose event has not reached the data yet.
+  const remember = Effect.gen(function* () {
+    const current = yield* SubscriptionRef.get(state);
+    const sequence = yield* SubscriptionRef.get(lastSequence);
+    committed = {
+      state: current,
+      sequence,
+      persisted:
+        committed.persisted &&
+        matchesThreadSnapshot(
+          committed,
+          Option.getOrNull(current.data),
+          sequence,
+          Option.getOrUndefined(current.page),
+        ),
+    };
+    if (resumeCache?.owner === owner) resumeCache.snapshot = committed;
+  });
   // Whether the connected server accepts windowed reads; set per subscription
   // from the session config. Gates loadOlderTurns so a reconnect to a
   // pre-pagination server never sends unsupported window parameters.
@@ -190,7 +270,28 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
   const persist = Effect.fn("EnvironmentThreadState.persist")(function* (
     snapshot: OrchestrationThreadDetailSnapshot,
   ) {
+    if (resumeCache !== undefined && resumeCache.owner !== owner) return;
+    if (
+      committed.persisted &&
+      matchesThreadSnapshot(committed, snapshot.thread, snapshot.snapshotSequence, snapshot.page)
+    )
+      return;
     yield* cache.saveThread(environmentId, snapshot).pipe(
+      Effect.tap(() =>
+        Effect.sync(() => {
+          if (
+            !matchesThreadSnapshot(
+              committed,
+              snapshot.thread,
+              snapshot.snapshotSequence,
+              snapshot.page,
+            )
+          )
+            return;
+          committed = { ...committed, persisted: true };
+          if (resumeCache?.owner === owner) resumeCache.snapshot = committed;
+        }),
+      ),
       Effect.catch((error) =>
         Effect.logWarning("Could not persist the thread cache.").pipe(
           Effect.annotateLogs({
@@ -300,6 +401,8 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
       error: Option.none(),
       page: Option.none(),
     });
+    yield* remember;
+    if (resumeCache !== undefined && resumeCache.owner !== owner) return;
     yield* cache.removeThread(environmentId, threadId).pipe(
       Effect.catch((error) =>
         Effect.logWarning("Could not remove the cached thread.").pipe(
@@ -402,7 +505,7 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
   const applyItem = Effect.fn("EnvironmentThreadState.applyItem")(function* (
     item: OrchestrationThreadStreamItem,
   ) {
-    yield* applyLock.withPermits(1)(applyItemLocked(item));
+    yield* applyLock.withPermits(1)(applyItemLocked(item).pipe(Effect.andThen(remember)));
   });
 
   // Merges an older disjoint page below the currently loaded window. All four
@@ -459,6 +562,7 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
         ...(snapshot.page === undefined ? {} : { page: { ...snapshot.page, snapshotSequence } }),
       });
     }
+    yield* remember;
   });
 
   const loadOlderTurns = Effect.fn("EnvironmentThreadState.loadOlderTurns")(function* () {
@@ -551,7 +655,16 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
       service.changes.pipe(Stream.filter(ConnectionWakeups.shouldResubscribeAfterWakeup)),
   });
 
-  yield* setSynchronizing;
+  // Only the first subscription after a warm live resume keeps the retained
+  // status. A replacement session or foreground resubscribe on the same scope
+  // may have missed events, so those show sync progress until confirmed.
+  const resumingLive = yield* Ref.make(initialState.status === "live");
+  const markSynchronizing = Effect.gen(function* () {
+    if (yield* Ref.get(resumingLive)) return;
+    yield* setSynchronizing;
+  });
+
+  yield* markSynchronizing;
   yield* Effect.forkScoped(
     subscribeDynamic(
       ORCHESTRATION_WS_METHODS.subscribeThread,
@@ -572,22 +685,29 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
         const supportsPagination = config.threadSnapshotPagination === true;
         yield* Ref.set(paginationSupported, supportsPagination);
         yield* Ref.set(awaitingCompletion, supportsCompletionMarker);
-        yield* setSynchronizing;
+        yield* markSynchronizing;
+        yield* Ref.set(resumingLive, false);
 
         let current = yield* SubscriptionRef.get(state);
         // A windowed cache resuming against a server without pagination is a
         // trap: afterSequence resume keeps only the window, and the missing
         // older turns can never be loaded (the server has no cursor reads).
         // Drop the window marker and treat the data as needing a full reload.
-        if (!supportsPagination && Option.isSome(current.page)) {
-          yield* Ref.update(historyEpoch, (epoch) => epoch + 1);
-          yield* SubscriptionRef.update(state, (value) => ({
-            ...value,
-            data: Option.none(),
-            status: value.status === "deleted" ? value.status : ("empty" as const),
-            page: Option.none(),
-          }));
-          yield* SubscriptionRef.set(lastSequence, 0);
+        if (!supportsPagination) {
+          yield* applyLock.withPermits(1)(
+            Effect.gen(function* () {
+              if (Option.isNone((yield* SubscriptionRef.get(state)).page)) return;
+              yield* Ref.update(historyEpoch, (epoch) => epoch + 1);
+              yield* SubscriptionRef.update(state, (value) => ({
+                ...value,
+                data: Option.none(),
+                status: value.status === "deleted" ? value.status : ("empty" as const),
+                page: Option.none(),
+              }));
+              yield* SubscriptionRef.set(lastSequence, 0);
+              yield* remember;
+            }),
+          );
           current = yield* SubscriptionRef.get(state);
         }
         if (Option.isNone(current.data) && current.status !== "deleted") {
@@ -663,40 +783,45 @@ export const makeEnvironmentThreadState = Effect.fn("EnvironmentThreadState.make
   yield* Effect.addFinalizer(() => Effect.sync(deregister));
 
   yield* Effect.addFinalizer(() =>
-    Effect.all([SubscriptionRef.get(state), SubscriptionRef.get(lastSequence)]).pipe(
-      Effect.flatMap(([current, snapshotSequence]) =>
-        Option.match(current.data, {
-          onNone: () => Effect.void,
-          onSome: (thread) =>
-            shouldPersistThread(thread)
-              ? persist({
-                  snapshotSequence,
-                  thread,
-                  ...Option.match(current.page, {
-                    onNone: () => ({}),
-                    onSome: (page) =>
-                      ({
-                        page: {
-                          beforeCursor: page.beforeCursor,
-                          hasMore: page.hasMore,
-                          snapshotSequence,
-                        },
-                      }) as const,
-                  }),
-                })
-              : Effect.void,
-        }),
-      ),
-    ),
+    Effect.suspend(() => {
+      const { state: current, sequence: snapshotSequence } = committed;
+      return Option.match(current.data, {
+        onNone: () => Effect.void,
+        onSome: (thread) =>
+          shouldPersistThread(thread)
+            ? persist({
+                snapshotSequence,
+                thread,
+                ...Option.match(current.page, {
+                  onNone: () => ({}),
+                  onSome: (page) =>
+                    ({
+                      page: {
+                        beforeCursor: page.beforeCursor,
+                        hasMore: page.hasMore,
+                        snapshotSequence,
+                      },
+                    }) as const,
+                }),
+              })
+            : Effect.void,
+      });
+    }),
   );
 
   return state;
 });
 
-export function threadStateChanges(environmentId: EnvironmentIdType, threadId: ThreadIdType) {
+export function threadStateChanges(
+  environmentId: EnvironmentIdType,
+  threadId: ThreadIdType,
+  resumeCache?: ThreadResumeCache,
+) {
   return followStreamInEnvironment(
     environmentId,
-    Stream.unwrap(makeEnvironmentThreadState(threadId).pipe(Effect.map(SubscriptionRef.changes))),
+    Stream.unwrap(
+      makeEnvironmentThreadState(threadId, resumeCache).pipe(Effect.map(SubscriptionRef.changes)),
+    ),
   );
 }
 
@@ -706,16 +831,35 @@ export function createEnvironmentThreadStateAtoms<R, E>(
     E
   >,
 ) {
+  // Cache definitions must outlive collectible live-atom definitions. The
+  // registry retains these nodes without retaining environment or RPC scopes.
+  const resumeFamily = Atom.family((key: string) =>
+    Atom.make((): ThreadResumeCache => ({
+      snapshot: undefined,
+      owner: undefined,
+    })).pipe(
+      Atom.setIdleTTL(THREAD_SNAPSHOT_IDLE_TTL_MS),
+      Atom.withLabel(`environment-thread-resume:${key}`),
+    ),
+  );
   const family = Atom.family((key: string) => {
     const { environmentId, threadId } = parseThreadKey(key);
+    const resumeAtom = resumeFamily(key);
     return runtime
-      .atom(threadStateChanges(environmentId, threadId), {
-        initialValue: EMPTY_ENVIRONMENT_THREAD_STATE,
-      })
-      .pipe(
-        Atom.setIdleTTL(THREAD_STATE_IDLE_TTL_MS),
-        Atom.withLabel(`environment-thread-state:${key}`),
-      );
+      .atom(
+        (get) => {
+          get.mount(resumeAtom);
+          const resume = get.once(resumeAtom);
+          const live = threadStateChanges(environmentId, threadId, resume);
+          return resume.snapshot === undefined
+            ? live
+            : Stream.concat(Stream.succeed(cachedThreadState(resume.snapshot.state)), live);
+        },
+        {
+          initialValue: EMPTY_ENVIRONMENT_THREAD_STATE,
+        },
+      )
+      .pipe(Atom.setIdleTTL(0), Atom.withLabel(`environment-thread-state:${key}`));
   });
 
   return {
diff --git a/packages/client-runtime/src/work-log/presentation.test.ts b/packages/client-runtime/src/work-log/presentation.test.ts
index cc5b1c910539..f3febf5e756d 100644
--- a/packages/client-runtime/src/work-log/presentation.test.ts
+++ b/packages/client-runtime/src/work-log/presentation.test.ts
@@ -15,6 +15,40 @@ import {
 } from "./presentation.js";
 
 describe("summarizeToolGroup", () => {
+  it.each(["command", "file-read", "file-change"])(
+    "keeps %s approvals out of tool execution counts",
+    (requestKind) => {
+      const approvals = [
+        {
+          label: "Approval requested",
+          sourceActivityKind: "approval.requested",
+          tone: "info",
+          requestKind,
+        },
+        {
+          label: "Approval resolved",
+          sourceActivityKind: "approval.resolved",
+          tone: "info",
+          requestKind,
+        },
+        {
+          label: "Provider approval response failed",
+          sourceActivityKind: "provider.approval.respond.failed",
+          tone: "error",
+        },
+      ] satisfies WorkLogPresentationEntry[];
+
+      expect(
+        summarizeToolGroup([
+          ...approvals,
+          { label: "Read", tone: "tool", itemType: "dynamic_tool_call" },
+        ]),
+      ).toBe("Received 3 updates and used 1 tool");
+      expect(summarizeToolGroup(approvals)).toBe("Received 3 updates");
+      expect(toolGroupSummaryKind(approvals)).toBe("update");
+    },
+  );
+
   it("deduplicates named sources ahead of ordinary actions", () => {
     const source = { key: "browser-use:chrome", name: "Chrome", kind: "integration" as const };
     expect(
diff --git a/packages/client-runtime/src/work-log/presentation.ts b/packages/client-runtime/src/work-log/presentation.ts
index e27a2d318fef..d47f44566452 100644
--- a/packages/client-runtime/src/work-log/presentation.ts
+++ b/packages/client-runtime/src/work-log/presentation.ts
@@ -313,6 +313,13 @@ export function workLogEntryIsLocalCodeSearch(entry: WorkLogPresentationEntry):
 }
 
 export function toolGroupAction(entry: WorkLogPresentationEntry): ToolGroupAction {
+  if (
+    entry.sourceActivityKind === "approval.requested" ||
+    entry.sourceActivityKind === "approval.resolved" ||
+    entry.sourceActivityKind === "provider.approval.respond.failed"
+  ) {
+    return "update";
+  }
   if (resolveWorkEntryToolPresentation(entry)?.icon === "browser") return "browser";
   if (
     entry.requestKind === "file-read" ||
diff --git a/packages/client-runtime/vite.config.ts b/packages/client-runtime/vite.config.ts
index fcdb97512160..7f4ff74eca29 100644
--- a/packages/client-runtime/vite.config.ts
+++ b/packages/client-runtime/vite.config.ts
@@ -5,5 +5,6 @@ export default defineConfig({
   test: {
     environment: "node",
     include: ["src/**/*.test.ts"],
+    setupFiles: ["../shared/src/testing/longTempDir.ts"],
   },
 });
diff --git a/packages/contracts/src/agentSessions.ts b/packages/contracts/src/agentSessions.ts
new file mode 100644
index 000000000000..ffd90dd79db8
--- /dev/null
+++ b/packages/contracts/src/agentSessions.ts
@@ -0,0 +1,98 @@
+import * as Schema from "effect/Schema";
+import { IsoDateTime, NonNegativeInt, ProjectId, TrimmedNonEmptyString } from "./baseSchemas.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
+
+/** Coding agent home directories the scanner knows how to read. */
+export const AgentSessionSource = Schema.Literals(["claudeAgent", "codex"]);
+export type AgentSessionSource = typeof AgentSessionSource.Type;
+
+/** File identity saved with an imported session so bounded retries can skip unchanged history. */
+export const AgentSessionImportSource = Schema.Struct({
+  provider: AgentSessionSource,
+  providerInstanceId: ProviderInstanceId,
+  providerSessionId: TrimmedNonEmptyString,
+  filePath: TrimmedNonEmptyString,
+  size: NonNegativeInt,
+  mtimeMs: Schema.NullOr(Schema.Number),
+  device: Schema.Number,
+  inode: Schema.NullOr(Schema.Number),
+  birthtimeMs: Schema.NullOr(Schema.Number),
+});
+export type AgentSessionImportSource = typeof AgentSessionImportSource.Type;
+
+/** Imported message ids retain their origin after event metadata is projected into SQLite. */
+export function isImportedAgentSessionMessageId(messageId: string): boolean {
+  return messageId.startsWith("import:");
+}
+
+/**
+ * Empty for now. Kept as a struct so future scan options (source filters,
+ * explicit roots) can be added without a new method.
+ */
+export const AgentSessionScanInput = Schema.Struct({});
+export type AgentSessionScanInput = typeof AgentSessionScanInput.Type;
+
+/**
+ * A directory that at least one agent CLI has run in, suitable for import as a
+ * T3 Code project. `alreadyImported` marks candidates that already have an
+ * active project rooted at the same path.
+ */
+export const AgentSessionProjectCandidate = Schema.Struct({
+  path: TrimmedNonEmptyString,
+  title: TrimmedNonEmptyString,
+  projectId: Schema.optional(ProjectId),
+  sources: Schema.Array(AgentSessionSource),
+  threadCount: NonNegativeInt,
+  lastActiveAt: Schema.NullOr(IsoDateTime),
+  alreadyImported: Schema.Boolean,
+});
+export type AgentSessionProjectCandidate = typeof AgentSessionProjectCandidate.Type;
+
+export const AgentSessionScanResult = Schema.Struct({
+  candidates: Schema.Array(AgentSessionProjectCandidate),
+  scannedAt: IsoDateTime,
+  truncated: Schema.optional(Schema.Boolean),
+});
+export type AgentSessionScanResult = typeof AgentSessionScanResult.Type;
+
+export const AgentSessionImportInput = Schema.Struct({
+  projectId: ProjectId,
+  expectedWorkspaceRoot: Schema.optional(TrimmedNonEmptyString),
+});
+export type AgentSessionImportInput = typeof AgentSessionImportInput.Type;
+
+export class AgentSessionImportProjectNotFoundError extends Schema.TaggedErrorClass<AgentSessionImportProjectNotFoundError>()(
+  "AgentSessionImportProjectNotFoundError",
+  { projectId: ProjectId },
+) {
+  override get message(): string {
+    return `Project '${this.projectId}' does not exist.`;
+  }
+}
+
+export class AgentSessionImportProjectChangedError extends Schema.TaggedErrorClass<AgentSessionImportProjectChangedError>()(
+  "AgentSessionImportProjectChangedError",
+  { projectId: ProjectId },
+) {
+  override get message(): string {
+    return `Project '${this.projectId}' changed directories. Scan for projects again before importing history.`;
+  }
+}
+
+export const AgentSessionImportResult = Schema.Struct({
+  importedCount: NonNegativeInt,
+  skippedCount: NonNegativeInt,
+});
+export type AgentSessionImportResult = typeof AgentSessionImportResult.Type;
+
+export class AgentSessionScanError extends Schema.TaggedErrorClass<AgentSessionScanError>()(
+  "AgentSessionScanError",
+  {
+    operation: Schema.Literals(["read-settings", "read-projects"]),
+    cause: Schema.Defect(),
+  },
+) {
+  override get message(): string {
+    return `Failed to scan agent sessions during ${this.operation}.`;
+  }
+}
diff --git a/packages/contracts/src/browserImport.ts b/packages/contracts/src/browserImport.ts
index 4448ae37b472..2c7eb24821d3 100644
--- a/packages/contracts/src/browserImport.ts
+++ b/packages/contracts/src/browserImport.ts
@@ -25,6 +25,7 @@ export const BROWSER_IMPORT_SOURCE_IDS = [
   "arc",
   "helium",
   "firefox",
+  "safari",
 ] as const;
 
 export const BrowserImportSourceId = Schema.Literals(BROWSER_IMPORT_SOURCE_IDS);
@@ -42,6 +43,7 @@ export const BrowserImportUnavailableReason = Schema.Literals([
   "notInstalled",
   "needsKeychainApproval",
   "keychainItemMissing",
+  "needsFullDiskAccess",
   "browserRunning",
   "unsupportedPlatform",
 ]);
@@ -144,6 +146,8 @@ export const BROWSER_IMPORT_UNAVAILABLE_COPY: Readonly<
   needsKeychainApproval: "Needs Keychain access to read its cookies.",
   keychainItemMissing:
     "No encryption key in your Keychain — sign in to that browser once, then retry.",
+  needsFullDiskAccess:
+    "Give T3 Code Full Disk Access in System Settings → Privacy & Security, then retry.",
   browserRunning: "Quit the browser first so its cookie database can be read.",
   unsupportedPlatform: "Importing from this browser isn't possible on this platform.",
 };
diff --git a/packages/contracts/src/environment.ts b/packages/contracts/src/environment.ts
index f6ffebfd81b2..aa6610dde369 100644
--- a/packages/contracts/src/environment.ts
+++ b/packages/contracts/src/environment.ts
@@ -94,6 +94,8 @@ export const ExecutionEnvironmentCapabilities = Schema.Struct({
   threadSettlement: Schema.optionalKey(Schema.Boolean),
   /** Server evaluates merge and inactivity settlement without a client. */
   threadAutoSettlement: Schema.optionalKey(Schema.Boolean),
+  /** Server persists the opt-in for continuing interrupted threads after restarts. */
+  threadRestartContinuation: Schema.optionalKey(Schema.Boolean),
   /** Server understands thread.snooze / thread.unsnooze commands. Same
       version-skew contract as threadSettlement. */
   threadSnooze: Schema.optionalKey(Schema.Boolean),
@@ -105,6 +107,8 @@ export const ExecutionEnvironmentCapabilities = Schema.Struct({
   /** Server streams quota from configured usage-limit sources. Same
       version-skew contract as environmentThemes. */
   usageLimitSources: Schema.optionalKey(Schema.Boolean),
+  /** Server persists custom model rates and applies them to usage summaries. */
+  usagePriceOverrides: Schema.optionalKey(Schema.Boolean),
   /** Server understands thread.pin / thread.unpin commands. Same
       version-skew contract as threadSettlement. */
   threadPinning: Schema.optionalKey(Schema.Boolean),
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 1a19f5292b65..eb037a30c78c 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -30,6 +30,7 @@ export * from "./t3ProjectFile.ts";
 export * from "./editor.ts";
 export * from "./project.ts";
 export * from "./filesystem.ts";
+export * from "./agentSessions.ts";
 export * from "./assets.ts";
 export * from "./review.ts";
 export * from "./browserImport.ts";
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 798d5a777d5d..a14a4ed0a08a 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -1052,6 +1052,13 @@ export const DesktopPreviewAutomationWaitForInputSchema = Schema.Struct({
   input: PreviewAutomationWaitForInput,
 });
 
+/**
+ * A System Settings pane the app can deep-link to. The identifier crosses IPC
+ * rather than a URL, so the renderer can only reach these known destinations.
+ */
+export const SystemSettingsPaneSchema = Schema.Literals(["full-disk-access"]);
+export type SystemSettingsPane = typeof SystemSettingsPaneSchema.Type;
+
 export interface DesktopBridge {
   getAppBranding: () => DesktopAppBranding | null;
   /** The desktop client's OS platform, read from Electron's preload process. */
@@ -1119,6 +1126,11 @@ export interface DesktopBridge {
     position?: { x: number; y: number },
   ) => Promise<T | null>;
   openExternal: (url: string) => Promise<boolean>;
+  /**
+   * Open a System Settings pane by identifier. Optional: older desktop builds
+   * lack it, and callers no-op when it is missing.
+   */
+  openSystemSettings?: (pane: SystemSettingsPane) => Promise<boolean>;
   /**
    * Probe this desktop machine for installed remote-capable editor CLIs
    * (used for remote open-in-editor deep links). Optional: older desktop
@@ -1267,6 +1279,8 @@ export interface LocalApi {
   };
   shell: {
     openExternal: (url: string) => Promise<void>;
+    /** Opens a known System Settings pane; no-ops outside the desktop app. */
+    openSystemSettings: (pane: SystemSettingsPane) => Promise<void>;
   };
   contextMenu: {
     show: <T extends string>(
diff --git a/packages/contracts/src/model.ts b/packages/contracts/src/model.ts
index d217a0cc2cbb..bce1a766bc9b 100644
--- a/packages/contracts/src/model.ts
+++ b/packages/contracts/src/model.ts
@@ -127,6 +127,22 @@ export const ModelCapabilities = Schema.Struct({
 });
 export type ModelCapabilities = typeof ModelCapabilities.Type;
 
+/**
+ * A user-authored custom model. `name` and `capabilities` are optional so a
+ * bare slug keeps its driver-default presentation; when `capabilities` is
+ * set, its descriptors replace the driver default in the model picker.
+ */
+export const CustomModelEntry = Schema.Struct({
+  slug: TrimmedNonEmptyString,
+  name: Schema.optional(TrimmedNonEmptyString),
+  capabilities: Schema.optional(ModelCapabilities),
+});
+export type CustomModelEntry = typeof CustomModelEntry.Type;
+
+/** On-disk custom model setting: the legacy bare slug, or a full entry. */
+export const CustomModelSetting = Schema.Union([Schema.String, CustomModelEntry]);
+export type CustomModelSetting = typeof CustomModelSetting.Type;
+
 const CODEX_DRIVER_KIND = ProviderDriverKind.make("codex");
 const CLAUDE_DRIVER_KIND = ProviderDriverKind.make("claudeAgent");
 const CURSOR_DRIVER_KIND = ProviderDriverKind.make("cursor");
diff --git a/packages/contracts/src/orchestration.test.ts b/packages/contracts/src/orchestration.test.ts
index d7e33ebb713b..11c21deecddb 100644
--- a/packages/contracts/src/orchestration.test.ts
+++ b/packages/contracts/src/orchestration.test.ts
@@ -1135,6 +1135,21 @@ it.effect("project icon overrides accept Lucide icons, colors, and emoji", () =>
   }),
 );
 
+it.effect("rejects thread history imports without messages", () =>
+  Effect.gen(function* () {
+    const result = yield* Effect.exit(
+      decodeOrchestrationCommand({
+        type: "thread.history.import",
+        commandId: "command-empty-history",
+        threadId: "thread-1",
+        messages: [],
+      }),
+    );
+
+    assert.strictEqual(result._tag, "Failure");
+  }),
+);
+
 it("isProviderSendTurnSupportedImageMimeType accepts raster formats and rejects svg", () => {
   assert.strictEqual(isProviderSendTurnSupportedImageMimeType("image/png"), true);
   assert.strictEqual(isProviderSendTurnSupportedImageMimeType("IMAGE/JPEG"), true);
diff --git a/packages/contracts/src/orchestration.ts b/packages/contracts/src/orchestration.ts
index 17cadc6d1d7f..92e9fe01dd42 100644
--- a/packages/contracts/src/orchestration.ts
+++ b/packages/contracts/src/orchestration.ts
@@ -800,6 +800,7 @@ const ThreadCreateCommand = Schema.Struct({
   branch: Schema.NullOr(TrimmedNonEmptyString),
   worktreePath: Schema.NullOr(TrimmedNonEmptyString),
   createdAt: IsoDateTime,
+  historyImport: Schema.optional(Schema.Literal(true)),
 });
 
 const ThreadDeleteCommand = Schema.Struct({
@@ -1122,6 +1123,20 @@ const ThreadMessageAssistantCompleteCommand = Schema.Struct({
   createdAt: IsoDateTime,
 });
 
+const ThreadHistoryImportCommand = Schema.Struct({
+  type: Schema.Literal("thread.history.import"),
+  commandId: CommandId,
+  threadId: ThreadId,
+  messages: Schema.Array(
+    Schema.Struct({
+      messageId: MessageId,
+      role: Schema.Literals(["user", "assistant"]),
+      text: Schema.String,
+      createdAt: IsoDateTime,
+    }),
+  ).check(Schema.isNonEmpty()),
+});
+
 const ThreadProposedPlanUpsertCommand = Schema.Struct({
   type: Schema.Literal("thread.proposed-plan.upsert"),
   commandId: CommandId,
@@ -1173,6 +1188,7 @@ const InternalOrchestrationCommand = Schema.Union([
   ThreadSessionSetCommand,
   ThreadMessageAssistantDeltaCommand,
   ThreadMessageAssistantCompleteCommand,
+  ThreadHistoryImportCommand,
   ThreadProposedPlanUpsertCommand,
   ThreadTurnDiffCompleteCommand,
   ThreadActivityAppendCommand,
@@ -1473,6 +1489,7 @@ export const OrchestrationEventMetadata = Schema.Struct({
   adapterKey: Schema.optional(TrimmedNonEmptyString),
   requestId: Schema.optional(ApprovalRequestId),
   ingestedAt: Schema.optional(IsoDateTime),
+  historyImport: Schema.optional(Schema.Boolean),
   origin: Schema.optional(OrchestrationClientOrigin),
 });
 export type OrchestrationEventMetadata = typeof OrchestrationEventMetadata.Type;
diff --git a/packages/contracts/src/providerRuntime.test.ts b/packages/contracts/src/providerRuntime.test.ts
index 7563ac155681..9ba30b235fc1 100644
--- a/packages/contracts/src/providerRuntime.test.ts
+++ b/packages/contracts/src/providerRuntime.test.ts
@@ -1,11 +1,65 @@
-import { describe, expect, it } from "vite-plus/test";
+import { describe, expect, expectTypeOf, it } from "vite-plus/test";
 import * as Schema from "effect/Schema";
 
-import { classifyTaskAgentKind, ProviderRuntimeEvent } from "./providerRuntime.ts";
+import {
+  classifyTaskAgentKind,
+  ProviderRuntimeEvent,
+  type ProviderRuntimeEventType,
+} from "./providerRuntime.ts";
 
 const decodeRuntimeEvent = Schema.decodeUnknownSync(ProviderRuntimeEvent);
 
 describe("ProviderRuntimeEvent", () => {
+  it("includes every runtime event in the public event type", () => {
+    expectTypeOf<ProviderRuntimeEvent["type"]>().toEqualTypeOf<ProviderRuntimeEventType>();
+  });
+
+  it("requires input and output totals for complete turn usage", () => {
+    const completeEvent = {
+      type: "turn.completed",
+      eventId: "event-complete-usage",
+      provider: "codex",
+      createdAt: "2026-02-28T00:00:00.000Z",
+      threadId: "thread-1",
+      turnId: "turn-1",
+      payload: {
+        state: "completed",
+        tokenUsage: {
+          usageStatus: "complete",
+          usageScope: "main_agent",
+          hasSubagents: false,
+        },
+      },
+    };
+
+    expect(() => decodeRuntimeEvent(completeEvent)).toThrow();
+    expect(
+      decodeRuntimeEvent({
+        ...completeEvent,
+        payload: {
+          ...completeEvent.payload,
+          tokenUsage: {
+            ...completeEvent.payload.tokenUsage,
+            inputTokens: 10,
+            outputTokens: 2,
+          },
+        },
+      }).type,
+    ).toBe("turn.completed");
+    expect(
+      decodeRuntimeEvent({
+        ...completeEvent,
+        payload: {
+          ...completeEvent.payload,
+          tokenUsage: {
+            ...completeEvent.payload.tokenUsage,
+            usageStatus: "partial",
+          },
+        },
+      }).type,
+    ).toBe("turn.completed");
+  });
+
   it("accepts fork-provided driver kinds as branded slugs", () => {
     const parsed = decodeRuntimeEvent({
       type: "session.started",
diff --git a/packages/contracts/src/providerRuntime.ts b/packages/contracts/src/providerRuntime.ts
index 2f6307d6a57c..0d17f86e1942 100644
--- a/packages/contracts/src/providerRuntime.ts
+++ b/packages/contracts/src/providerRuntime.ts
@@ -186,6 +186,7 @@ const ProviderRuntimeEventType = Schema.Literals([
   "hook.completed",
   "tool.progress",
   "tool.summary",
+  "tool.denied",
   "auth.status",
   "account.updated",
   "account.rate-limits.updated",
@@ -367,6 +368,35 @@ const TurnStartedPayload = Schema.Struct({
 });
 export type TurnStartedPayload = typeof TurnStartedPayload.Type;
 
+/**
+ * Normalized main-agent usage for one turn. Input includes cache reads and
+ * writes. Output includes reasoning, and reasoningTokens is an optional subset.
+ * Complete means the provider supplied full input and output totals. Partial
+ * means every included count is valid, but the full turn total is not known.
+ */
+const TurnTokenUsageCommonFields = {
+  usageScope: Schema.Literal("main_agent"),
+  cachedInputTokens: Schema.optional(NonNegativeInt),
+  cacheCreationTokens: Schema.optional(NonNegativeInt),
+  reasoningTokens: Schema.optional(NonNegativeInt),
+  hasSubagents: Schema.Boolean,
+};
+export const TurnTokenUsage = Schema.Union([
+  Schema.Struct({
+    ...TurnTokenUsageCommonFields,
+    usageStatus: Schema.Literal("complete"),
+    inputTokens: NonNegativeInt,
+    outputTokens: NonNegativeInt,
+  }),
+  Schema.Struct({
+    ...TurnTokenUsageCommonFields,
+    usageStatus: Schema.Literals(["partial", "unavailable"]),
+    inputTokens: Schema.optional(NonNegativeInt),
+    outputTokens: Schema.optional(NonNegativeInt),
+  }),
+]);
+export type TurnTokenUsage = typeof TurnTokenUsage.Type;
+
 const TurnCompletedPayload = Schema.Struct({
   state: RuntimeTurnState,
   stopReason: Schema.optional(Schema.NullOr(TrimmedNonEmptyStringSchema)),
@@ -374,11 +404,13 @@ const TurnCompletedPayload = Schema.Struct({
   modelUsage: Schema.optional(UnknownRecordSchema),
   totalCostUsd: Schema.optional(Schema.Number),
   errorMessage: Schema.optional(TrimmedNonEmptyStringSchema),
+  tokenUsage: Schema.optional(TurnTokenUsage),
 });
 export type TurnCompletedPayload = typeof TurnCompletedPayload.Type;
 
 const TurnAbortedPayload = Schema.Struct({
   reason: TrimmedNonEmptyStringSchema,
+  tokenUsage: Schema.optional(TurnTokenUsage),
 });
 export type TurnAbortedPayload = typeof TurnAbortedPayload.Type;
 
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index b6db99f48e6b..f064dbe8c430 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -28,6 +28,15 @@ import {
   FilesystemBrowseResult,
   FilesystemBrowseError,
 } from "./filesystem.ts";
+import {
+  AgentSessionImportInput,
+  AgentSessionImportProjectChangedError,
+  AgentSessionImportProjectNotFoundError,
+  AgentSessionImportResult,
+  AgentSessionScanInput,
+  AgentSessionScanResult,
+  AgentSessionScanError,
+} from "./agentSessions.ts";
 import {
   AssetAccessError,
   AssetCreateUrlInput,
@@ -247,6 +256,8 @@ export const WS_METHODS = {
 
   // Filesystem methods
   filesystemBrowse: "filesystem.browse",
+  agentSessionsScan: "agentSessions.scan",
+  agentSessionsImport: "agentSessions.import",
   assetsCreateUrl: "assets.createUrl",
   attachmentsCreateUploadUrl: "attachments.createUploadUrl",
   attachmentsDelete: "attachments.delete",
@@ -847,6 +858,23 @@ export const WsFilesystemBrowseRpc = Rpc.make(WS_METHODS.filesystemBrowse, {
   error: Schema.Union([FilesystemBrowseError, EnvironmentAuthorizationError]),
 });
 
+export const WsAgentSessionsScanRpc = Rpc.make(WS_METHODS.agentSessionsScan, {
+  payload: AgentSessionScanInput,
+  success: AgentSessionScanResult,
+  error: Schema.Union([AgentSessionScanError, EnvironmentAuthorizationError]),
+});
+
+export const WsAgentSessionsImportRpc = Rpc.make(WS_METHODS.agentSessionsImport, {
+  payload: AgentSessionImportInput,
+  success: AgentSessionImportResult,
+  error: Schema.Union([
+    AgentSessionImportProjectChangedError,
+    AgentSessionImportProjectNotFoundError,
+    AgentSessionScanError,
+    EnvironmentAuthorizationError,
+  ]),
+});
+
 export const WsAssetsCreateUrlRpc = Rpc.make(WS_METHODS.assetsCreateUrl, {
   payload: AssetCreateUrlInput,
   success: AssetCreateUrlResult,
@@ -1265,6 +1293,8 @@ export const WsRpcGroup = RpcGroup.make(
   WsProjectsWriteFileRpc,
   WsShellOpenInEditorRpc,
   WsFilesystemBrowseRpc,
+  WsAgentSessionsScanRpc,
+  WsAgentSessionsImportRpc,
   WsAssetsCreateUrlRpc,
   WsAttachmentsCreateUploadUrlRpc,
   WsAttachmentsDeleteRpc,
diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts
index ba0d6679cfc2..3ea7bed8f1c4 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -748,8 +748,11 @@ export const ServerLifecycleWelcomePayload = Schema.Struct({
   environment: ExecutionEnvironmentDescriptor,
   cwd: TrimmedNonEmptyString,
   projectName: TrimmedNonEmptyString,
+  bootstrapStatus: Schema.optional(Schema.Literals(["pending", "complete"])),
   bootstrapProjectId: Schema.optional(ProjectId),
   bootstrapThreadId: Schema.optional(ThreadId),
+  bootstrapProjectCreated: Schema.optional(Schema.Boolean),
+  bootstrapThreadCreated: Schema.optional(Schema.Boolean),
 });
 export type ServerLifecycleWelcomePayload = typeof ServerLifecycleWelcomePayload.Type;
 
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
index 5d4c1573ef7e..1673f4ad159b 100644
--- a/packages/contracts/src/settings.test.ts
+++ b/packages/contracts/src/settings.test.ts
@@ -7,7 +7,6 @@ import {
   ClientSettingsPatch,
   ClaudeSettings,
   DEFAULT_SERVER_SETTINGS,
-  defaultEnabledForDriver,
   resolveProviderInstanceEnabled,
   ServerSettings,
   ServerSettingsPatch,
@@ -21,6 +20,92 @@ const decodeServerSettingsPatch = Schema.decodeUnknownSync(ServerSettingsPatch);
 const encodeServerSettings = Schema.encodeSync(ServerSettings);
 const decodeClaudeSettings = Schema.decodeUnknownSync(ClaudeSettings);
 
+describe("ServerSettings usage price overrides", () => {
+  const prices = { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 };
+
+  it("defaults to automatic pricing and round-trips arbitrary model IDs", () => {
+    expect(decodeServerSettings({}).usagePriceOverrides).toEqual({});
+    const settings = decodeServerSettings({
+      usagePriceOverrides: { "  vendor/example-model  ": prices },
+    });
+    expect(encodeServerSettings(settings).usagePriceOverrides).toEqual({
+      "vendor/example-model": prices,
+    });
+  });
+
+  it("accepts zero rates, optional cache rates, and per-model deletion", () => {
+    const overrides = {
+      "example-model": {
+        inputCostPerMillionTokens: 0,
+        outputCostPerMillionTokens: 0,
+        cacheReadCostPerMillionTokens: 0.5,
+        cacheWriteCostPerMillionTokens: 3,
+      },
+      "removed-model": null,
+    };
+    expect(
+      decodeServerSettingsPatch({ usagePriceOverrides: overrides }).usagePriceOverrides,
+    ).toEqual(overrides);
+  });
+
+  it.each([
+    "inputCostPerMillionTokens",
+    "outputCostPerMillionTokens",
+    "cacheReadCostPerMillionTokens",
+    "cacheWriteCostPerMillionTokens",
+  ])("rejects invalid %s rates at the settings boundary", (field) => {
+    for (const value of [-1, Number.NaN, Number.POSITIVE_INFINITY, "2"]) {
+      const usagePriceOverrides = { "example-model": { ...prices, [field]: value } };
+      expect(() => decodeServerSettings({ usagePriceOverrides })).toThrow();
+      expect(() => decodeServerSettingsPatch({ usagePriceOverrides })).toThrow();
+    }
+  });
+
+  it("rejects empty model IDs and incomplete input/output pricing", () => {
+    for (const usagePriceOverrides of [
+      { " ": prices },
+      { "example-model": { inputCostPerMillionTokens: 2 } },
+      { "example-model": { outputCostPerMillionTokens: 8 } },
+    ]) {
+      expect(() => decodeServerSettingsPatch({ usagePriceOverrides })).toThrow();
+    }
+  });
+});
+
+describe("custom model settings", () => {
+  const capabilities = {
+    optionDescriptors: [
+      {
+        id: "effort",
+        label: "Reasoning",
+        type: "select",
+        options: [{ id: "high", label: "High", isDefault: true }],
+      },
+    ],
+  };
+
+  it("accepts legacy bare slugs alongside full entries", () => {
+    const decoded = decodeClaudeSettings({
+      customModels: ["bare-slug", { slug: "named", name: "Named", capabilities }],
+    });
+    expect(decoded.customModels).toEqual([
+      "bare-slug",
+      { slug: "named", name: "Named", capabilities },
+    ]);
+  });
+
+  it("accepts entries at the settings patch boundary", () => {
+    expect(
+      decodeServerSettingsPatch({
+        providers: { codex: { customModels: [{ slug: "x", capabilities }] } },
+      }).providers?.codex?.customModels,
+    ).toEqual([{ slug: "x", capabilities }]);
+    expect(() =>
+      decodeServerSettingsPatch({ providers: { codex: { customModels: [{ name: "no slug" }] } } }),
+    ).toThrow();
+  });
+});
+
 describe("ClaudeSettings auto-compaction", () => {
   it("uses Claude's default threshold when no override is configured", () => {
     expect(decodeClaudeSettings({}).autoCompactWindow).toBe("");
@@ -346,14 +431,6 @@ describe("provider enabled defaults", () => {
     expect(decoded.providers.opencode.enabled).toBe(false);
   });
 
-  it("derives per-driver defaults from the settings schemas", () => {
-    expect(defaultEnabledForDriver(ProviderDriverKind.make("codex"))).toBe(true);
-    expect(defaultEnabledForDriver(ProviderDriverKind.make("cursor"))).toBe(false);
-    expect(defaultEnabledForDriver(ProviderDriverKind.make("grok"))).toBe(false);
-    // Unknown fork drivers stay enabled; their own build decides otherwise.
-    expect(defaultEnabledForDriver(ProviderDriverKind.make("ollama"))).toBe(true);
-  });
-
   it("keeps Cursor enabled when an existing user explicitly opted in", () => {
     const cursor = ProviderDriverKind.make("cursor");
     const cursorId = ProviderInstanceId.make("cursor");
@@ -374,6 +451,10 @@ describe("provider enabled defaults", () => {
     // No flags anywhere: driver default applies.
     expect(resolveProviderInstanceEnabled({ driver: grok, config: {} })).toBe(false);
     expect(resolveProviderInstanceEnabled({ driver: codex, config: {} })).toBe(true);
+    // Unknown fork drivers stay enabled.
+    expect(
+      resolveProviderInstanceEnabled({ driver: ProviderDriverKind.make("ollama"), config: {} }),
+    ).toBe(true);
     // Envelope flag wins over the driver default.
     expect(resolveProviderInstanceEnabled({ driver: grok, enabled: true, config: {} })).toBe(true);
     expect(resolveProviderInstanceEnabled({ driver: codex, enabled: false, config: {} })).toBe(
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index fef3b2992f07..623780c1fb8b 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -6,6 +6,7 @@ import { ForwardCompatibleNullable, TrimmedNonEmptyString, TrimmedString } from
 import { UsageLimitSourceId } from "./usageLimitSourceId.ts";
 import { EnvironmentMachineKind, ThreadEnvMode } from "./environment.ts";
 import {
+  CustomModelSetting,
   DEFAULT_TEXT_GENERATION_MODEL,
   DEFAULT_TEXT_GENERATION_REASONING_EFFORT,
   ProviderOptionSelections,
@@ -255,9 +256,6 @@ export const ClientSettingsSchema = Schema.Struct({
   confirmThreadArchive: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
   confirmThreadDelete: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
   confirmThreadUnpin: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
-  continueThreadsAfterServerUpdate: Schema.Boolean.pipe(
-    Schema.withDecodingDefault(Effect.succeed(false)),
-  ),
   dismissedProviderUpdateNotificationKeys: Schema.Array(TrimmedNonEmptyString).pipe(
     Schema.withDecodingDefault(Effect.succeed([])),
   ),
@@ -288,6 +286,13 @@ export const ClientSettingsSchema = Schema.Struct({
   // Grayscale `-webkit-font-smoothing: antialiased` (thinner strokes);
   // disabling restores the platform's heavier default. No effect off macOS.
   fontSmoothing: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+  // When the first-run welcome wizard finished (or was skipped), as an ISO
+  // timestamp. `null` alone does not mean "show the wizard" — every install
+  // that predates this field decodes to `null` — so the gate also requires an
+  // empty workspace before it treats the client as a fresh install.
+  onboardingCompletedAt: Schema.NullOr(Schema.String).pipe(
+    Schema.withDecodingDefault(Effect.succeed(null)),
+  ),
   // 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
@@ -358,6 +363,20 @@ export const DEFAULT_CLIENT_SETTINGS: ClientSettings = Schema.decodeSync(ClientS
 
 // ── Server Settings (server-authoritative) ────────────────────
 
+const UsageModelTokenPrice = Schema.Number.check(
+  Schema.isFinite(),
+  Schema.isGreaterThanOrEqualTo(0),
+);
+
+/** USD per million tokens. Omitted cache rates use the input rate. */
+export const UsageModelPriceOverride = Schema.Struct({
+  inputCostPerMillionTokens: UsageModelTokenPrice,
+  outputCostPerMillionTokens: UsageModelTokenPrice,
+  cacheReadCostPerMillionTokens: Schema.optionalKey(UsageModelTokenPrice),
+  cacheWriteCostPerMillionTokens: Schema.optionalKey(UsageModelTokenPrice),
+});
+export type UsageModelPriceOverride = typeof UsageModelPriceOverride.Type;
+
 const makeBinaryPathSetting = (fallback: string) =>
   TrimmedString.pipe(
     Schema.decodeTo(
@@ -461,7 +480,7 @@ export const CodexSettings = makeProviderSettingsSchema(
         description: "Additional CLI arguments passed to codex app-server on session start.",
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -499,7 +518,7 @@ export const ClaudeSettings = makeProviderSettingsSchema(
         providerSettingsForm: { placeholder: "~/.claude", clearWhenEmpty: "omit" },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -560,7 +579,7 @@ export const CursorSettings = makeProviderSettingsSchema(
         },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -586,7 +605,7 @@ export const GrokSettings = makeProviderSettingsSchema(
         providerSettingsForm: { placeholder: "grok", clearWhenEmpty: "omit" },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -671,7 +690,7 @@ export const AntigravitySettings = makeProviderSettingsSchema(
         providerSettingsForm: { placeholder: "Automatic", clearWhenEmpty: "persist" },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -721,7 +740,7 @@ export const OpenCodeSettings = makeProviderSettingsSchema(
         },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -821,6 +840,10 @@ export const ServerSettings = Schema.Struct({
     Schema.withDecodingDefault(Effect.succeed(false)),
   ),
   enableProviderUpdateChecks: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
+  // Retain the update-era key; recovery now needs an environment-owned opt-in.
+  continueThreadsAfterServerUpdate: Schema.Boolean.pipe(
+    Schema.withDecodingDefault(Effect.succeed(false)),
+  ),
   /**
    * Whether agents may drive the in-app preview browser. Turning this off
    * withholds the MCP credential, so the `t3-code` server (and with it every
@@ -930,6 +953,10 @@ export const ServerSettings = Schema.Struct({
   usageLimitSources: Schema.Record(UsageLimitSourceId, UsageLimitSourceConfig).pipe(
     Schema.withDecodingDefault(Effect.succeed({})),
   ),
+  /** Exact model IDs, applied to past and future usage on this environment. */
+  usagePriceOverrides: Schema.Record(TrimmedNonEmptyString, UsageModelPriceOverride).pipe(
+    Schema.withDecodingDefault(Effect.succeed({})),
+  ),
 });
 export type ServerSettings = typeof ServerSettings.Type;
 
@@ -955,7 +982,7 @@ export const providerInstanceConfigEnabledFlag = (config: unknown): boolean | un
  * through `DEFAULT_SERVER_SETTINGS`, so the schema's decoding default stays
  * the single source of truth. Unknown (fork) drivers default to enabled.
  */
-export const defaultEnabledForDriver = (driver: ProviderDriverKind): boolean => {
+const defaultEnabledForDriver = (driver: ProviderDriverKind): boolean => {
   const legacyDefaults = DEFAULT_SERVER_SETTINGS.providers as Record<
     string,
     { readonly enabled?: boolean } | undefined
@@ -1036,14 +1063,14 @@ const CodexSettingsPatch = Schema.Struct({
   homePath: Schema.optionalKey(TrimmedString),
   shadowHomePath: Schema.optionalKey(TrimmedString),
   launchArgs: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 const ClaudeSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
   binaryPath: Schema.optionalKey(TrimmedString),
   homePath: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
   launchArgs: Schema.optionalKey(TrimmedString),
   // Validated at the patch boundary so a typo fails the one update with a
   // schema error instead of a generic whole-settings failure.
@@ -1056,13 +1083,13 @@ const CursorSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
   binaryPath: Schema.optionalKey(TrimmedString),
   apiEndpoint: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 const GrokSettingsPatch = Schema.Struct({
   enabled: Schema.optionalKey(Schema.Boolean),
   binaryPath: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 const AntigravitySettingsPatch = Schema.Struct({
@@ -1072,7 +1099,7 @@ const AntigravitySettingsPatch = Schema.Struct({
   gcpProject: Schema.optionalKey(TrimmedString),
   gcpLocation: Schema.optionalKey(TrimmedString),
   binaryPath: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 const OpenCodeSettingsPatch = Schema.Struct({
@@ -1080,13 +1107,14 @@ const OpenCodeSettingsPatch = Schema.Struct({
   binaryPath: Schema.optionalKey(TrimmedString),
   serverUrl: Schema.optionalKey(TrimmedString),
   serverPassword: Schema.optionalKey(TrimmedString),
-  customModels: Schema.optionalKey(Schema.Array(Schema.String)),
+  customModels: Schema.optionalKey(Schema.Array(CustomModelSetting)),
 });
 
 export const ServerSettingsPatch = Schema.Struct({
   // Server settings
   enableLegacyTokenStreaming: Schema.optionalKey(Schema.Boolean),
   enableProviderUpdateChecks: Schema.optionalKey(Schema.Boolean),
+  continueThreadsAfterServerUpdate: Schema.optionalKey(Schema.Boolean),
   enableAgentBrowserAccess: Schema.optionalKey(Schema.Boolean),
   sidebarAutoSettleAfterDays: Schema.optionalKey(Schema.NullOr(SidebarAutoSettleAfterDays)),
   sidebarAutoSettleOnMerge: Schema.optionalKey(Schema.Boolean),
@@ -1141,6 +1169,10 @@ export const ServerSettingsPatch = Schema.Struct({
   usageLimitSources: Schema.optionalKey(
     Schema.Record(UsageLimitSourceId, Schema.NullOr(UsageLimitSourceConfig)),
   ),
+  /** Each entry replaces one model's rates; `null` restores automatic pricing. */
+  usagePriceOverrides: Schema.optionalKey(
+    Schema.Record(TrimmedNonEmptyString, Schema.NullOr(UsageModelPriceOverride)),
+  ),
 });
 export type ServerSettingsPatch = typeof ServerSettingsPatch.Type;
 
@@ -1159,11 +1191,11 @@ export const ClientSettingsPatch = Schema.Struct({
   confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
   confirmThreadDelete: Schema.optionalKey(Schema.Boolean),
   confirmThreadUnpin: Schema.optionalKey(Schema.Boolean),
-  continueThreadsAfterServerUpdate: Schema.optionalKey(Schema.Boolean),
   diffIgnoreWhitespace: Schema.optionalKey(Schema.Boolean),
   diffLayout: Schema.optionalKey(DiffLayout),
   environmentIdentificationMode: Schema.optionalKey(EnvironmentIdentificationMode),
   glassOpacity: Schema.optionalKey(GlassOpacity),
+  onboardingCompletedAt: Schema.optionalKey(Schema.NullOr(Schema.String)),
   fontSizeInterface: Schema.optionalKey(InterfaceFontSize),
   fontSizePrompt: Schema.optionalKey(PromptFontSize),
   fontSizeCode: Schema.optionalKey(CodeFontSize),
diff --git a/packages/contracts/src/terminal.test.ts b/packages/contracts/src/terminal.test.ts
index a08ed4923888..066253602a49 100644
--- a/packages/contracts/src/terminal.test.ts
+++ b/packages/contracts/src/terminal.test.ts
@@ -7,12 +7,18 @@ import {
   TerminalClearInput,
   TerminalCloseInput,
   TerminalEvent,
+  TerminalError,
   TerminalOpenInput,
+  TerminalProviderEnvironmentError,
   TerminalResizeInput,
   TerminalSessionSnapshot,
   TerminalThreadInput,
   TerminalWriteInput,
 } from "./terminal.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
+
+const encodeTerminalError = Schema.encodeUnknownSync(TerminalError);
+const decodeTerminalError = Schema.decodeUnknownSync(TerminalError);
 
 function decodeSync<S extends Schema.Top>(schema: S, input: unknown): Schema.Schema.Type<S> {
   return Schema.decodeUnknownSync(schema as never)(input) as Schema.Schema.Type<S>;
@@ -27,6 +33,28 @@ function decodes<S extends Schema.Top>(schema: S, input: unknown): boolean {
   }
 }
 
+describe("TerminalProviderEnvironmentError", () => {
+  it("round-trips its required cause without exposing it in the message", () => {
+    const cause = { operation: "read-secret", detail: "secret backend unavailable" };
+    const error = new TerminalProviderEnvironmentError({
+      providerInstanceId: ProviderInstanceId.make("codex_work"),
+      cause,
+    });
+    const encoded = encodeTerminalError(error);
+    const decoded = decodeTerminalError(encoded);
+
+    expect(decoded).toMatchObject({
+      _tag: "TerminalProviderEnvironmentError",
+      providerInstanceId: "codex_work",
+      cause,
+    });
+    expect(decoded.message).toBe(
+      "Could not prepare the terminal environment for provider instance: codex_work",
+    );
+    expect(decoded.message).not.toContain("secret backend unavailable");
+  });
+});
+
 describe("TerminalOpenInput", () => {
   it("accepts valid open input", () => {
     expect(
@@ -87,12 +115,14 @@ describe("TerminalOpenInput", () => {
         T3CODE_PROJECT_ROOT: "/tmp/project",
         CUSTOM_FLAG: "1",
       },
+      providerInstanceId: "codex_work",
     });
     expect(parsed.env).toMatchObject({
       T3CODE_PROJECT_ROOT: "/tmp/project",
       CUSTOM_FLAG: "1",
     });
     expect(parsed.worktreePath).toBe("/tmp/project/.t3/worktrees/feature-a");
+    expect(parsed.providerInstanceId).toBe("codex_work");
   });
 
   it("rejects invalid env keys", () => {
@@ -108,6 +138,19 @@ describe("TerminalOpenInput", () => {
       }),
     ).toBe(false);
   });
+
+  it("rejects invalid provider instance ids", () => {
+    for (const providerInstanceId of ["", "1invalid", "invalid id"]) {
+      expect(
+        decodes(TerminalOpenInput, {
+          threadId: "thread-1",
+          terminalId: DEFAULT_TERMINAL_ID,
+          cwd: "/tmp/project",
+          providerInstanceId,
+        }),
+      ).toBe(false);
+    }
+  });
 });
 
 describe("TerminalAttachInput", () => {
diff --git a/packages/contracts/src/terminal.ts b/packages/contracts/src/terminal.ts
index fa5f18211695..36e3d339f521 100644
--- a/packages/contracts/src/terminal.ts
+++ b/packages/contracts/src/terminal.ts
@@ -1,5 +1,6 @@
 import * as Schema from "effect/Schema";
 import { TrimmedNonEmptyString } from "./baseSchemas.ts";
+import { ProviderInstanceId } from "./providerInstance.ts";
 
 /**
  * Client-side id for the first shell opened on a thread. Ids are uniformly
@@ -43,8 +44,9 @@ export const TerminalOpenInput = Schema.Struct({
   cols: Schema.optional(TerminalColsSchema),
   rows: Schema.optional(TerminalRowsSchema),
   env: Schema.optional(TerminalEnvSchema),
+  providerInstanceId: Schema.optional(ProviderInstanceId),
 });
-export type TerminalOpenInput = Schema.Codec.Encoded<typeof TerminalOpenInput>;
+export type TerminalOpenInput = typeof TerminalOpenInput.Type;
 
 export const TerminalAttachInput = Schema.Struct({
   ...TerminalSessionInput.fields,
@@ -53,9 +55,10 @@ export const TerminalAttachInput = Schema.Struct({
   cols: Schema.optional(TerminalColsSchema),
   rows: Schema.optional(TerminalRowsSchema),
   env: Schema.optional(TerminalEnvSchema),
+  providerInstanceId: Schema.optional(ProviderInstanceId),
   restartIfNotRunning: Schema.optional(Schema.Boolean),
 });
-export type TerminalAttachInput = Schema.Codec.Encoded<typeof TerminalAttachInput>;
+export type TerminalAttachInput = typeof TerminalAttachInput.Type;
 
 export const TerminalWriteInput = Schema.Struct({
   ...TerminalSessionInput.fields,
@@ -80,8 +83,9 @@ export const TerminalRestartInput = Schema.Struct({
   cols: TerminalColsSchema,
   rows: TerminalRowsSchema,
   env: Schema.optional(TerminalEnvSchema),
+  providerInstanceId: Schema.optional(ProviderInstanceId),
 });
-export type TerminalRestartInput = Schema.Codec.Encoded<typeof TerminalRestartInput>;
+export type TerminalRestartInput = typeof TerminalRestartInput.Type;
 
 export const TerminalCloseInput = Schema.Struct({
   ...TerminalThreadInput.fields,
@@ -299,6 +303,29 @@ export class TerminalSessionLookupError extends Schema.TaggedErrorClass<Terminal
   }
 }
 
+export class TerminalProviderInstanceNotFoundError extends Schema.TaggedErrorClass<TerminalProviderInstanceNotFoundError>()(
+  "TerminalProviderInstanceNotFoundError",
+  {
+    providerInstanceId: ProviderInstanceId,
+  },
+) {
+  override get message() {
+    return `Provider instance is not available: ${this.providerInstanceId}`;
+  }
+}
+
+export class TerminalProviderEnvironmentError extends Schema.TaggedErrorClass<TerminalProviderEnvironmentError>()(
+  "TerminalProviderEnvironmentError",
+  {
+    providerInstanceId: ProviderInstanceId,
+    cause: Schema.Defect(),
+  },
+) {
+  override get message() {
+    return `Could not prepare the terminal environment for provider instance: ${this.providerInstanceId}`;
+  }
+}
+
 export class TerminalNotRunningError extends Schema.TaggedErrorClass<TerminalNotRunningError>()(
   "TerminalNotRunningError",
   {
@@ -345,6 +372,8 @@ export const TerminalError = Schema.Union([
   TerminalCwdError,
   TerminalHistoryError,
   TerminalSessionLookupError,
+  TerminalProviderInstanceNotFoundError,
+  TerminalProviderEnvironmentError,
   TerminalNotRunningError,
   TerminalWriteError,
   TerminalResizeError,
diff --git a/packages/contracts/src/usage.ts b/packages/contracts/src/usage.ts
index 6e74019d71f7..b003f21fa660 100644
--- a/packages/contracts/src/usage.ts
+++ b/packages/contracts/src/usage.ts
@@ -55,7 +55,7 @@ export type UsageResolution = typeof UsageResolution.Type;
  * Why a bucket's cost is what it is.
  *
  * - `providerReported` - the transcript carried an explicit cost figure.
- * - `modelPriced` - we matched the model against the LiteLLM rate table.
+ * - `modelPriced` - we used a custom price override or the LiteLLM rate table.
  * - `unpriced` - tokens are known, rates are not. Counted in totals, excluded
  *   from cost.
  */
diff --git a/packages/effect-codex-app-server/src/_internal/shared.ts b/packages/effect-codex-app-server/src/_internal/shared.ts
index 34155348abfa..8bcb59467d3d 100644
--- a/packages/effect-codex-app-server/src/_internal/shared.ts
+++ b/packages/effect-codex-app-server/src/_internal/shared.ts
@@ -5,7 +5,7 @@ import * as CodexError from "../errors.ts";
 
 export const JsonRpcId = Schema.Union([Schema.Number, Schema.String]);
 
-export const JsonRpcError = Schema.Struct({
+const JsonRpcError = Schema.Struct({
   code: Schema.Number,
   message: Schema.String,
   data: Schema.optional(Schema.Unknown),
diff --git a/packages/effect-codex-app-server/src/client.ts b/packages/effect-codex-app-server/src/client.ts
index c0cb5b1dc23a..78d719626139 100644
--- a/packages/effect-codex-app-server/src/client.ts
+++ b/packages/effect-codex-app-server/src/client.ts
@@ -84,7 +84,7 @@ type ServerNotificationHandler = (
   payload: unknown,
 ) => Effect.Effect<void, CodexError.CodexAppServerError>;
 
-export const make = Effect.fn("effect-codex-app-server/CodexAppServerClient.make")(function* (
+const make = Effect.fn("effect-codex-app-server/CodexAppServerClient.make")(function* (
   stdio: Stdio.Stdio,
   options: CodexAppServerClientOptions = {},
   terminationError?: Effect.Effect<CodexError.CodexAppServerError>,
@@ -250,11 +250,6 @@ export const make = Effect.fn("effect-codex-app-server/CodexAppServerClient.make
   });
 });
 
-export const layer = (
-  stdio: Stdio.Stdio,
-  options: CodexAppServerClientOptions = {},
-): Layer.Layer<CodexAppServerClient> => Layer.effect(CodexAppServerClient, make(stdio, options));
-
 export const layerChildProcess = (
   handle: ChildProcessSpawner.ChildProcessHandle,
   options: CodexAppServerClientOptions = {},
diff --git a/packages/effect-codex-app-server/src/errors.ts b/packages/effect-codex-app-server/src/errors.ts
index 3803b4d40659..f0bf470c251c 100644
--- a/packages/effect-codex-app-server/src/errors.ts
+++ b/packages/effect-codex-app-server/src/errors.ts
@@ -1,15 +1,15 @@
 import * as Schema from "effect/Schema";
 import type * as SchemaIssue from "effect/SchemaIssue";
 
-export const CodexAppServerRequestOperation = Schema.Literals([
+const CodexAppServerRequestOperation = Schema.Literals([
   "decode-payload",
   "encode-payload",
   "handle-request",
   "receive-response",
 ]);
-export type CodexAppServerRequestOperation = typeof CodexAppServerRequestOperation.Type;
+type CodexAppServerRequestOperation = typeof CodexAppServerRequestOperation.Type;
 
-export const CodexAppServerSchemaIssueKind = Schema.Literals([
+const CodexAppServerSchemaIssueKind = Schema.Literals([
   "Filter",
   "Encoding",
   "Pointer",
@@ -22,9 +22,9 @@ export const CodexAppServerSchemaIssueKind = Schema.Literals([
   "Forbidden",
   "OneOf",
 ]);
-export type CodexAppServerSchemaIssueKind = typeof CodexAppServerSchemaIssueKind.Type;
+type CodexAppServerSchemaIssueKind = typeof CodexAppServerSchemaIssueKind.Type;
 
-export interface CodexAppServerSchemaIssueDiagnostics {
+interface CodexAppServerSchemaIssueDiagnostics {
   readonly issueCount: number;
   readonly issueKinds: ReadonlyArray<CodexAppServerSchemaIssueKind>;
   readonly maximumPathDepth: number;
@@ -62,7 +62,7 @@ const schemaIssueDiagnostics = (root: SchemaIssue.Issue): CodexAppServerSchemaIs
   };
 };
 
-export const CodexAppServerPayloadKind = Schema.Literals([
+const CodexAppServerPayloadKind = Schema.Literals([
   "null",
   "array",
   "string",
@@ -74,7 +74,7 @@ export const CodexAppServerPayloadKind = Schema.Literals([
   "function",
   "undefined",
 ]);
-export type CodexAppServerPayloadKind = typeof CodexAppServerPayloadKind.Type;
+type CodexAppServerPayloadKind = typeof CodexAppServerPayloadKind.Type;
 
 const payloadKind = (payload: unknown): CodexAppServerPayloadKind => {
   if (payload === null) return "null";
@@ -84,8 +84,7 @@ const payloadKind = (payload: unknown): CodexAppServerPayloadKind => {
 
 const protocolMessageFields = ["id", "method", "params", "result", "error"] as const;
 
-export const CodexAppServerProtocolMessageField = Schema.Literals(protocolMessageFields);
-export type CodexAppServerProtocolMessageField = typeof CodexAppServerProtocolMessageField.Type;
+const CodexAppServerProtocolMessageField = Schema.Literals(protocolMessageFields);
 
 export interface CodexAppServerRequestDiagnostics {
   readonly method?: string;
diff --git a/packages/shared/package.json b/packages/shared/package.json
index d9233a2c54c4..d6915120b806 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -223,6 +223,14 @@
       "types": "./src/hostProcess.ts",
       "import": "./src/hostProcess.ts"
     },
+    "./testing/longTempDir": {
+      "types": "./src/testing/longTempDir.ts",
+      "import": "./src/testing/longTempDir.ts"
+    },
+    "./testing/symlinks": {
+      "types": "./src/testing/symlinks.ts",
+      "import": "./src/testing/symlinks.ts"
+    },
     "./httpReadiness": {
       "types": "./src/httpReadiness.ts",
       "import": "./src/httpReadiness.ts"
@@ -258,6 +266,14 @@
     "./nodeSqliteClient": {
       "types": "./src/nodeSqliteClient.ts",
       "import": "./src/nodeSqliteClient.ts"
+    },
+    "./hostClassification": {
+      "types": "./src/hostClassification.ts",
+      "import": "./src/hostClassification.ts"
+    },
+    "./dateTime": {
+      "types": "./src/dateTime.ts",
+      "import": "./src/dateTime.ts"
     }
   },
   "scripts": {
diff --git a/packages/shared/src/composerInlineTokens.test.ts b/packages/shared/src/composerInlineTokens.test.ts
index 81fd6add2056..5ce8f6281184 100644
--- a/packages/shared/src/composerInlineTokens.test.ts
+++ b/packages/shared/src/composerInlineTokens.test.ts
@@ -31,6 +31,26 @@ describe("collectComposerInlineTokens", () => {
     ]);
   });
 
+  it("collects skill names that begin with a digit", () => {
+    expect(collectComposerInlineTokens("Use $2spec next")).toEqual([
+      {
+        type: "skill",
+        value: "2spec",
+        source: "$2spec",
+        start: 4,
+        end: 10,
+      },
+    ]);
+  });
+
+  it("leaves digits-only dollar amounts and compact monetary expressions as text", () => {
+    expect(collectComposerInlineTokens("I'll pay $20 tomorrow")).toEqual([]);
+    expect(collectComposerInlineTokens("Budget is $1_000 total")).toEqual([]);
+    expect(collectComposerInlineTokens("Budget is $20k tomorrow")).toEqual([]);
+    expect(collectComposerInlineTokens("Cost is $100M total")).toEqual([]);
+    expect(collectComposerInlineTokens("Limit is $1e6 here")).toEqual([]);
+  });
+
   it("does not convert incomplete trailing tokens", () => {
     expect(collectComposerInlineTokens("Use $ui")).toEqual([]);
     expect(collectComposerInlineTokens("Inspect @AGENTS.md")).toEqual([]);
diff --git a/packages/shared/src/composerInlineTokens.ts b/packages/shared/src/composerInlineTokens.ts
index 11a5accf37b7..bb39dd599475 100644
--- a/packages/shared/src/composerInlineTokens.ts
+++ b/packages/shared/src/composerInlineTokens.ts
@@ -18,7 +18,15 @@ export interface CollectComposerInlineTokensOptions {
   readonly preserveTrailingFrom?: ReadonlyArray<ComposerInlineToken>;
 }
 
-const SKILL_TOKEN_REGEX = /(^|\s)\$([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s)/g;
+/**
+ * A skill name may start with a digit, but compact monetary amounts and
+ * numeric expressions like "$20", "$20k", "$100M", and "$1e6" must stay prose:
+ * the composer chips any matched `$name` token, known or not. Tokens beginning
+ * with digits must not match numbers with currency/exponent suffixes, and must
+ * contain at least one letter.
+ */
+const SKILL_TOKEN_REGEX =
+  /(^|\s)\$(?![0-9][0-9_]*(?:[kKmMbBtT]|[eE][0-9]+)?(?:\s|$))(?=[a-zA-Z0-9:_-]*[a-zA-Z])([a-zA-Z0-9][a-zA-Z0-9:_-]*)(?=\s)/g;
 const MENTION_TOKEN_REGEX = /(^|\s)@(?:"((?:\\.|[^"\\])*)"|([^\s@"]+))(?=\s)/g;
 /**
  * The label body is bounded rather than `*`. Unbounded, every whitespace in
diff --git a/packages/shared/src/composerTrigger.test.ts b/packages/shared/src/composerTrigger.test.ts
index 50c8cd7c2080..4b2763854457 100644
--- a/packages/shared/src/composerTrigger.test.ts
+++ b/packages/shared/src/composerTrigger.test.ts
@@ -1,20 +1,6 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { serializeComposerFileLink, serializeComposerMentionPath } from "./composerTrigger.ts";
-
-describe("serializeComposerMentionPath", () => {
-  it("keeps simple mention paths unquoted", () => {
-    expect(serializeComposerMentionPath("src/index.ts")).toBe("src/index.ts");
-  });
-
-  it("quotes mention paths containing whitespace", () => {
-    expect(serializeComposerMentionPath("docs/My File.md")).toBe('"docs/My File.md"');
-  });
-
-  it("escapes quoted mention path content", () => {
-    expect(serializeComposerMentionPath('docs/My "File".md')).toBe('"docs/My \\"File\\".md"');
-  });
-});
+import { serializeComposerFileLink } from "./composerTrigger.ts";
 
 describe("serializeComposerFileLink", () => {
   it("uses the basename as the markdown label", () => {
diff --git a/packages/shared/src/composerTrigger.ts b/packages/shared/src/composerTrigger.ts
index dcbdc784934b..c68a9963ffa8 100644
--- a/packages/shared/src/composerTrigger.ts
+++ b/packages/shared/src/composerTrigger.ts
@@ -8,15 +8,6 @@ export interface ComposerTrigger {
   rangeEnd: number;
 }
 
-const SIMPLE_MENTION_PATH_REGEX = /^[^\s@"\\]+$/;
-
-export function serializeComposerMentionPath(path: string): string {
-  if (SIMPLE_MENTION_PATH_REGEX.test(path)) {
-    return path;
-  }
-  return `"${path.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
-}
-
 function composerFileLinkBasename(path: string): string {
   const separatorIndex = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
   return separatorIndex >= 0 ? path.slice(separatorIndex + 1) : path;
diff --git a/packages/shared/src/dateTime.test.ts b/packages/shared/src/dateTime.test.ts
new file mode 100644
index 000000000000..562507de3ac2
--- /dev/null
+++ b/packages/shared/src/dateTime.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from "@effect/vitest";
+
+import { compareDateTimeStrings } from "./dateTime.ts";
+
+describe("compareDateTimeStrings", () => {
+  it("compares valid date-time strings by absolute time", () => {
+    expect(
+      compareDateTimeStrings("2026-09-01T12:00:00.000Z", "2026-09-01T05:00:00.000-07:00"),
+    ).toBe(0);
+    expect(
+      compareDateTimeStrings("2026-09-01T12:00:01.000Z", "2026-09-01T12:00:00.000Z"),
+    ).toBeGreaterThan(0);
+  });
+
+  it.each([
+    ["2024-02-29T12:00:00Z", "2024-02-29T17:30:00+05:30"],
+    ["2000-02-29T00:00:00.100Z", "2000-02-28T20:30:00.1-03:30"],
+    ["0000-01-01T00:00:00.000Z", "+000000-01-01T00:00:00.000+00:00"],
+    ["+010000-01-01T00:00:00.000Z", "9999-12-31T23:00:00.000-01:00"],
+    ["2026-09-01T24:00:00Z", "2026-09-02T00:00:00Z"],
+    ["2026-09-01T24:00:00.0000Z", "2026-09-02T00:00:00.000Z"],
+    ["2024-02-29T24:00:00+05:30", "2024-03-01T00:00:00+05:30"],
+    ["2026-12-31T24:00:00-07:00", "2027-01-01T07:00:00Z"],
+    ["2026-09-01T12:00Z", "2026-09-01T12:00:00.000Z"],
+    ["2026-09-01T05:00-07:00", "2026-09-01T12:00:00Z"],
+    ["2026-09-01T24:00Z", "2026-09-02T00:00:00Z"],
+    ["2026-09-01T24:00+05:30", "2026-09-02T00:00:00+05:30"],
+  ])("preserves equal ISO instants %s and %s", (left, right) => {
+    expect(compareDateTimeStrings(left, right)).toBe(0);
+  });
+
+  it("sorts malformed values before valid values", () => {
+    expect(compareDateTimeStrings("invalid", "2026-09-01T12:00:00.000Z")).toBeLessThan(0);
+    expect(compareDateTimeStrings("2026-09-01T12:00:00.000Z", "invalid")).toBeGreaterThan(0);
+  });
+
+  it.each([
+    "2014-02-30",
+    "2014-03-02",
+    "2014-03-02T00:00:00",
+    "2014-03-02T00:00:00.000",
+    "03/02/2014",
+    "March 2, 2014",
+    "Sun, 02 Mar 2014 00:00:00 GMT",
+    "2014-03-02T00:00:00.000Z\n",
+    "2014-02-30T00:00:00.000Z",
+    "1900-02-29T00:00:00.000-07:00",
+    "2024-04-31T00:00:00.000+05:30",
+    "2024-03-02T12:00:00.000+24:00",
+    "2026-09-01T24:01:00Z",
+    "2026-09-01T24:00:01Z",
+    "2026-09-01T24:00:00.0001Z",
+    "2026-09-01T24:01Z",
+    "2026-09-01T25:00Z",
+  ])("treats %s as malformed without native date guessing", (malformed) => {
+    const valid = "1970-01-01T00:00:00.000Z";
+    expect(compareDateTimeStrings(malformed, valid)).toBeLessThan(0);
+    expect(compareDateTimeStrings(valid, malformed)).toBeGreaterThan(0);
+    expect(compareDateTimeStrings(malformed, "invalid")).toBeLessThan(0);
+    expect(compareDateTimeStrings("invalid", malformed)).toBeGreaterThan(0);
+    expect(compareDateTimeStrings(malformed, malformed)).toBe(0);
+  });
+
+  it("uses code-unit order for malformed date-time strings", () => {
+    expect(compareDateTimeStrings("invalid-a", "invalid-B")).toBeGreaterThan(0);
+    expect(compareDateTimeStrings("invalid-B", "invalid-a")).toBeLessThan(0);
+  });
+
+  it("returns zero for equal malformed date-time strings", () => {
+    expect(compareDateTimeStrings("invalid", "invalid")).toBe(0);
+  });
+
+  it("gives every permutation of mixed values the same order", () => {
+    const early = "2026-09-01T12:00:00.000+14:00";
+    const late = "2026-09-01T00:00:00.000-12:00";
+    const malformed = "2026-09-01T06:invalid";
+    const expected = [malformed, early, late];
+
+    const permutations = [
+      [early, late, malformed],
+      [early, malformed, late],
+      [late, early, malformed],
+      [late, malformed, early],
+      [malformed, early, late],
+      [malformed, late, early],
+    ];
+
+    for (const values of permutations) {
+      expect(values.toSorted(compareDateTimeStrings)).toEqual(expected);
+    }
+  });
+});
diff --git a/packages/shared/src/dateTime.ts b/packages/shared/src/dateTime.ts
new file mode 100644
index 000000000000..544dd2d0d73b
--- /dev/null
+++ b/packages/shared/src/dateTime.ts
@@ -0,0 +1,38 @@
+import * as DateTime from "effect/DateTime";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+
+const isZonedIsoDateTime = Schema.is(
+  Schema.String.check(
+    Schema.isPattern(
+      /^(?:\d{4}|[+-]\d{6})-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12]\d|3[01])T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?|24:00(?::00(?:\.0+)?)?)(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/,
+    ),
+    Schema.isTrimmed(),
+  ),
+);
+
+function parseTimestamp(value: string): number {
+  if (!isZonedIsoDateTime(value)) return Number.NaN;
+
+  // Engines can normalize invalid calendar dates instead of rejecting them.
+  const datePart = value.slice(0, value.indexOf("T"));
+  const date = DateTime.make(`${datePart}T00:00:00.000Z`);
+  if (Option.isNone(date)) return Number.NaN;
+  const parts = DateTime.toPartsUtc(date.value);
+  if (parts.month !== Number(datePart.slice(-5, -3)) || parts.day !== Number(datePart.slice(-2))) {
+    return Number.NaN;
+  }
+  return Date.parse(value);
+}
+
+/** Compare date-time strings by absolute time, with stable handling for malformed stored values. */
+export function compareDateTimeStrings(left: string, right: string): number {
+  const leftTimestamp = parseTimestamp(left);
+  const rightTimestamp = parseTimestamp(right);
+  const leftIsValid = !Number.isNaN(leftTimestamp);
+  const rightIsValid = !Number.isNaN(rightTimestamp);
+
+  if (leftIsValid !== rightIsValid) return leftIsValid ? 1 : -1;
+  if (leftIsValid) return leftTimestamp - rightTimestamp;
+  return left < right ? -1 : left > right ? 1 : 0;
+}
diff --git a/packages/shared/src/favicon.test.ts b/packages/shared/src/favicon.test.ts
index c29727544efa..676f7811011e 100644
--- a/packages/shared/src/favicon.test.ts
+++ b/packages/shared/src/favicon.test.ts
@@ -1,13 +1,52 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import { explicitFaviconUrl, faviconUrlForPage, toolActivityFaviconUrl } from "./favicon.ts";
+import { faviconUrlForOrigin, toolActivityFaviconUrl } from "./favicon.ts";
 
-describe("faviconUrlForPage", () => {
+describe("faviconUrlForOrigin", () => {
+  it.each([
+    "http://192.168.1.10:8080",
+    "http://localhost:3000",
+    "http://home.arpa",
+    "https://printer.local.",
+    "https://api.internal",
+    "https://box.tailnet.ts.net",
+    "http://127.1",
+    "http://0x7f000001",
+    "http://[::]",
+    "http://[::1]",
+    "http://[::ffff:192.168.1.10]",
+    "http://[fd00::1]",
+    "http://[fe80::1]",
+    "http://100.64.0.1",
+    "http://198.51.100.1",
+    "http://[2001:db8::1]",
+    "http://service.test",
+    "http://private.onion",
+    "http://127.1..",
+  ])("does not disclose %s to the favicon provider", (origin) => {
+    expect(faviconUrlForOrigin(origin)).toBeNull();
+  });
+
+  it("keeps the public origin, port and requested size", () => {
+    expect(faviconUrlForOrigin("https://github.com:8443/pingdotgg/t3code?private=query", 64)).toBe(
+      "https://www.google.com/s2/favicons?domain=github.com%3A8443&sz=64",
+    );
+  });
+
+  it.each([null, undefined, "", "invalid URL", "file:///tmp/private", "data:text/plain,private"])(
+    "rejects an invalid or unsupported origin %s",
+    (origin) => {
+      expect(faviconUrlForOrigin(origin)).toBeNull();
+    },
+  );
+});
+
+describe("toolActivityFaviconUrl", () => {
   it("uses the page origin instead of a third-party favicon service", () => {
-    expect(faviconUrlForPage("https://example.com/docs/page?q=1")).toBe(
+    expect(toolActivityFaviconUrl({ pageUrl: "https://example.com/docs/page?q=1" }, "light")).toBe(
       "https://example.com/favicon.ico",
     );
-    expect(faviconUrlForPage("http://localhost:5173/app")).toBe(
+    expect(toolActivityFaviconUrl({ pageUrl: "http://localhost:5173/app" }, "light")).toBe(
       "http://localhost:5173/favicon.ico",
     );
   });
@@ -42,7 +81,17 @@ describe("faviconUrlForPage", () => {
   });
 
   it("accepts provider-supplied image URLs but rejects extension URLs", () => {
-    expect(explicitFaviconUrl("https://example.com/icon.png")).toBe("https://example.com/icon.png");
-    expect(explicitFaviconUrl("chrome-extension://example/_favicon/")).toBeNull();
+    expect(
+      toolActivityFaviconUrl(
+        { pageUrl: "https://example.com/docs", faviconUrl: "https://example.com/icon.png" },
+        "light",
+      ),
+    ).toBe("https://example.com/icon.png");
+    expect(
+      toolActivityFaviconUrl(
+        { pageUrl: "https://example.com/docs", faviconUrl: "chrome-extension://example/_favicon/" },
+        "light",
+      ),
+    ).toBe("https://example.com/favicon.ico");
   });
 });
diff --git a/packages/shared/src/favicon.ts b/packages/shared/src/favicon.ts
index 88bf46a985bc..2c4847115b90 100644
--- a/packages/shared/src/favicon.ts
+++ b/packages/shared/src/favicon.ts
@@ -1,9 +1,11 @@
+import { isPublicFaviconHost } from "./hostClassification.ts";
+
 /**
  * Mirrors Codex's generic Browser Use fallback: ask the page origin for its
  * conventional favicon and let the image element fall back to a browser glyph.
  * Chrome-backed tools can pass their tab's explicit favicon URL separately.
  */
-export function faviconUrlForPage(rawUrl: string | null | undefined, _size = 32): string | null {
+function faviconUrlForPage(rawUrl: string | null | undefined, _size = 32): string | null {
   if (!rawUrl || rawUrl.length > 4096) return null;
   try {
     const pageUrl = new URL(rawUrl);
@@ -38,7 +40,7 @@ function themedFaviconUrlForPage(
 }
 
 /** Accepts image URLs supplied by a trusted provider event. */
-export function explicitFaviconUrl(rawUrl: string | null | undefined): string | null {
+function explicitFaviconUrl(rawUrl: string | null | undefined): string | null {
   if (!rawUrl || rawUrl.length > 4096) return null;
   try {
     const url = new URL(rawUrl);
@@ -79,3 +81,17 @@ export function toolActivityFaviconUrl(
     faviconUrlForPage(icon.pageUrl, size)
   );
 }
+
+/** Return a public favicon URL without disclosing private or reserved hosts. */
+export function faviconUrlForOrigin(rawUrl: string | null | undefined, size = 32): string | null {
+  if (!rawUrl) return null;
+  try {
+    const url = new URL(rawUrl);
+    if (!url.host) return null;
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    if (!isPublicFaviconHost(url.hostname)) return null;
+    return `https://www.google.com/s2/favicons?domain=${encodeURIComponent(url.host)}&sz=${size}`;
+  } catch {
+    return null;
+  }
+}
diff --git a/packages/shared/src/hostClassification.test.ts b/packages/shared/src/hostClassification.test.ts
new file mode 100644
index 000000000000..9fcb1a7667cb
--- /dev/null
+++ b/packages/shared/src/hostClassification.test.ts
@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { isPublicFaviconHost } from "./hostClassification.ts";
+
+describe("isPublicFaviconHost", () => {
+  it("treats public hosts as public", () => {
+    for (const host of [
+      "github.com",
+      "www.google.com",
+      "t3.chat",
+      "sub.domain.example.co.uk",
+      "8.8.8.8",
+      "1.1.1.1",
+      "100.200.1.1",
+      "172.32.0.1",
+      "192.167.1.1",
+      "11.0.0.1",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(true);
+    }
+  });
+
+  it("detects private IPv4 ranges", () => {
+    for (const host of [
+      "0.0.0.0",
+      "10.0.0.1",
+      "10.255.255.255",
+      "127.0.0.1",
+      "192.168.1.10",
+      "172.16.0.1",
+      "172.31.255.255",
+      "169.254.1.1",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+  });
+
+  it("detects the Tailscale 100.64.0.0/10 range", () => {
+    for (const host of ["100.64.0.1", "100.100.100.100", "100.126.17.15", "100.127.255.255"]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+    expect(isPublicFaviconHost("100.63.255.255")).toBe(true);
+    expect(isPublicFaviconHost("100.128.0.1")).toBe(true);
+  });
+
+  it("detects private host names and suffixes", () => {
+    for (const host of [
+      "localhost",
+      "air",
+      "printer.local",
+      "api.internal",
+      "router.home.arpa",
+      "home.arpa",
+      "box.tailnet.ts.net",
+      "AIR.TAILE8BEA7.TS.NET",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+  });
+
+  it("detects private IPv6 addresses", () => {
+    for (const host of ["::1", "[::1]", "fd00::1", "fc00::1", "fe80::1", "FD12:3456::1"]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+    expect(isPublicFaviconHost("2606:4700:4700::1111")).toBe(true);
+  });
+
+  it("detects IPv4-mapped IPv6 addresses in both spellings", () => {
+    for (const host of [
+      "::ffff:192.168.1.10",
+      "::ffff:10.0.0.1",
+      "::ffff:100.126.17.15",
+      "[::ffff:192.168.1.10]",
+      // c0a8:010a is 192.168.1.10, 0a00:0001 is 10.0.0.1.
+      "::ffff:c0a8:010a",
+      "::ffff:a00:1",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+    expect(isPublicFaviconHost("::ffff:8.8.8.8")).toBe(true);
+    expect(isPublicFaviconHost("::ffff:808:808")).toBe(true);
+  });
+
+  it("ignores a trailing DNS root label", () => {
+    for (const host of [
+      "localhost.",
+      "printer.local.",
+      "api.internal.",
+      "box.tailnet.ts.net.",
+      "air.",
+    ]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+    expect(isPublicFaviconHost("github.com.")).toBe(true);
+  });
+
+  it("detects names under .localhost", () => {
+    for (const host of ["app.localhost", "api.app.localhost", "APP.LOCALHOST"]) {
+      expect(isPublicFaviconHost(host), host).toBe(false);
+    }
+  });
+
+  it("treats an empty host as private", () => {
+    expect(isPublicFaviconHost("")).toBe(false);
+    expect(isPublicFaviconHost("   ")).toBe(false);
+  });
+
+  it("rejects malformed IPv4 text as a public host", () => {
+    expect(isPublicFaviconHost("10.0.0.999")).toBe(true);
+    expect(isPublicFaviconHost("10.0.0")).toBe(true);
+  });
+});
diff --git a/packages/shared/src/hostClassification.ts b/packages/shared/src/hostClassification.ts
new file mode 100644
index 000000000000..7191fa78221f
--- /dev/null
+++ b/packages/shared/src/hostClassification.ts
@@ -0,0 +1,149 @@
+export const normalizeHostname = (host: string): string =>
+  host
+    .toLowerCase()
+    .replace(/^\[|\]$/g, "")
+    .replace(/\.+$/u, "");
+
+const parseIpv4Address = (host: string): readonly number[] | null => {
+  const parts = normalizeHostname(host).split(".").map(Number);
+  return parts.length === 4 &&
+    parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)
+    ? parts
+    : null;
+};
+
+const parseIpv4MappedIpv6Address = (host: string): readonly number[] | null => {
+  const normalized = normalizeHostname(host);
+  if (!normalized.startsWith("::ffff:")) return null;
+  const suffix = normalized.slice("::ffff:".length);
+  const dotted = parseIpv4Address(suffix);
+  if (dotted) return dotted;
+  const hextets = suffix.split(":");
+  if (hextets.length !== 2 || hextets.some((part) => !/^[\da-f]{1,4}$/u.test(part))) return null;
+  const high = Number.parseInt(hextets[0]!, 16);
+  const low = Number.parseInt(hextets[1]!, 16);
+  return [high >>> 8, high & 0xff, low >>> 8, low & 0xff];
+};
+
+const parseIpv6Address = (host: string): readonly number[] | null => {
+  const normalized = normalizeHostname(host);
+  if (!normalized.includes(":")) return null;
+  const halves = normalized.split("::");
+  if (halves.length > 2) return null;
+  const head = halves[0] ? halves[0].split(":") : [];
+  const tail = halves[1] ? halves[1].split(":") : [];
+  if ([...head, ...tail].some((part) => !/^[\da-f]{1,4}$/u.test(part))) return null;
+  const missing = 8 - head.length - tail.length;
+  if ((halves.length === 1 && missing !== 0) || (halves.length === 2 && missing < 1)) return null;
+  return [...head, ...Array.from({ length: missing }, () => "0"), ...tail].map((part) =>
+    Number.parseInt(part, 16),
+  );
+};
+
+const ipv6PrefixMatches = (
+  address: readonly number[],
+  prefix: readonly number[],
+  prefixLength: number,
+): boolean => {
+  const fullHextets = Math.floor(prefixLength / 16);
+  if (address.slice(0, fullHextets).some((part, index) => part !== prefix[index])) return false;
+  const remainingBits = prefixLength % 16;
+  if (remainingBits === 0) return true;
+  const mask = (0xffff << (16 - remainingBits)) & 0xffff;
+  return (address[fullHextets]! & mask) === (prefix[fullHextets]! & mask);
+};
+
+const isPrivateIpv4Address = (parts: readonly number[]): boolean =>
+  parts[0] === 0 ||
+  parts[0] === 10 ||
+  parts[0] === 127 ||
+  (parts[0] === 100 && parts[1]! >= 64 && parts[1]! <= 127) ||
+  (parts[0] === 172 && parts[1]! >= 16 && parts[1]! <= 31) ||
+  (parts[0] === 192 && parts[1] === 168) ||
+  (parts[0] === 169 && parts[1] === 254) ||
+  (parts[0] === 198 && parts[1]! >= 18 && parts[1]! <= 19);
+
+const isSpecialPurposeIpv4Address = (parts: readonly number[]): boolean =>
+  isPrivateIpv4Address(parts) ||
+  parts[0]! >= 224 ||
+  // Deliberately suppress the whole protocol-assignment block. IANA marks
+  // .9 and .10 globally reachable, but privacy-safe false negatives are
+  // preferable to disclosing another special-purpose address by mistake.
+  (parts[0] === 192 && parts[1] === 0 && parts[2] === 0) ||
+  (parts[0] === 192 && parts[1] === 0 && parts[2] === 2) ||
+  (parts[0] === 192 && parts[1] === 88 && parts[2] === 99) ||
+  (parts[0] === 198 && parts[1] === 51 && parts[2] === 100) ||
+  (parts[0] === 203 && parts[1] === 0 && parts[2] === 113);
+
+export const isLocalLoopbackHost = (host: string): boolean => {
+  const normalized = normalizeHostname(host);
+  if (normalized === "localhost" || normalized === "::1") return true;
+  return parseIpv4Address(normalized)?.[0] === 127;
+};
+
+export const isPrivateNetworkHost = (host: string): boolean => {
+  const normalized = normalizeHostname(host);
+  if (
+    normalized === "::" ||
+    isLocalLoopbackHost(normalized) ||
+    normalized.endsWith(".localhost") ||
+    normalized.endsWith(".local") ||
+    normalized === "home.arpa" ||
+    normalized.endsWith(".home.arpa") ||
+    (!normalized.includes(".") && !normalized.includes(":"))
+  ) {
+    return true;
+  }
+  if (normalized.endsWith(".ts.net")) return true;
+  const parts = parseIpv4Address(normalized) ?? parseIpv4MappedIpv6Address(normalized);
+  if (parts) return isPrivateIpv4Address(parts);
+  const firstIpv6Token = normalized.split(":", 1)[0] ?? "";
+  if (!normalized.includes(":") || !/^[\da-f]{1,4}$/u.test(firstIpv6Token)) return false;
+  const firstIpv6Hextet = Number.parseInt(firstIpv6Token, 16);
+  return (
+    Number.isInteger(firstIpv6Hextet) &&
+    ((firstIpv6Hextet & 0xfe00) === 0xfc00 || (firstIpv6Hextet & 0xffc0) === 0xfe80)
+  );
+};
+
+/** Whether a hostname is eligible to be disclosed to a public favicon provider. */
+export const isPublicFaviconHost = (host: string): boolean => {
+  // A single trailing dot is a valid absolute DNS name. Repeated trailing
+  // dots are malformed and can conceal legacy numeric forms such as 127.1.
+  if (host.endsWith("..")) return false;
+  const normalized = normalizeHostname(host);
+  if (isPrivateNetworkHost(normalized)) return false;
+  if (
+    [".alt", ".example", ".internal", ".invalid", ".onion", ".test"].some(
+      (suffix) => normalized === suffix.slice(1) || normalized.endsWith(suffix),
+    )
+  ) {
+    return false;
+  }
+  const ipv4 = parseIpv4Address(normalized) ?? parseIpv4MappedIpv6Address(normalized);
+  if (ipv4) return !isSpecialPurposeIpv4Address(ipv4);
+  if (!normalized.includes(":")) return true;
+  const ipv6 = parseIpv6Address(normalized);
+  if (!ipv6) return false;
+  if (ipv6PrefixMatches(ipv6, [0x0064, 0xff9b, 0, 0, 0, 0, 0, 0], 96)) {
+    const embeddedIpv4 = [ipv6[6]! >>> 8, ipv6[6]! & 0xff, ipv6[7]! >>> 8, ipv6[7]! & 0xff];
+    return !isSpecialPurposeIpv4Address(embeddedIpv4);
+  }
+  const first = ipv6[0]!;
+  if ((first & 0xe000) !== 0x2000) return false;
+  if (ipv6PrefixMatches(ipv6, [0x2001, 0, 0, 0, 0, 0, 0, 0], 23)) {
+    const publicProtocolAssignment =
+      (ipv6[1] === 1 &&
+        ipv6.slice(2, 7).every((part) => part === 0) &&
+        [1, 2, 3].includes(ipv6[7]!)) ||
+      ipv6PrefixMatches(ipv6, [0x2001, 3, 0, 0, 0, 0, 0, 0], 32) ||
+      ipv6PrefixMatches(ipv6, [0x2001, 4, 0x0112, 0, 0, 0, 0, 0], 48) ||
+      ipv6PrefixMatches(ipv6, [0x2001, 0x20, 0, 0, 0, 0, 0, 0], 28) ||
+      ipv6PrefixMatches(ipv6, [0x2001, 0x30, 0, 0, 0, 0, 0, 0], 28);
+    return publicProtocolAssignment;
+  }
+  if (ipv6PrefixMatches(ipv6, [0x2001, 0x0db8, 0, 0, 0, 0, 0, 0], 32)) return false;
+  if (ipv6PrefixMatches(ipv6, [0x2002, 0, 0, 0, 0, 0, 0, 0], 16)) return false;
+  if (first === 0x3fff && (ipv6[1]! & 0xf000) === 0) return false;
+  return true;
+};
diff --git a/packages/shared/src/logging.test.ts b/packages/shared/src/logging.test.ts
index 4b19bd291dae..0e294bbe29bf 100644
--- a/packages/shared/src/logging.test.ts
+++ b/packages/shared/src/logging.test.ts
@@ -3,6 +3,7 @@ import * as NodeFS from "node:fs";
 import * as NodeOS from "node:os";
 import * as NodePath from "node:path";
 import { afterEach, describe, expect, it } from "vite-plus/test";
+import { HostProcessPlatform } from "./hostProcess.ts";
 
 import {
   RotatingFileSink,
@@ -10,6 +11,7 @@ import {
   RotatingFileSinkError,
 } from "./logging.ts";
 
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
 const tempDirectories: string[] = [];
 
 const makeTempDirectory = (): string => {
@@ -69,7 +71,10 @@ describe("RotatingFileSink", () => {
     expect((thrown as RotatingFileSinkError).cause).toBeInstanceOf(Error);
   });
 
-  it("only treats a missing log file as an empty current size", () => {
+  // An over-long name is the one stat failure that is neither ENOENT nor a
+  // permission problem on posix. Windows reports it as ENOENT, so the sink
+  // correctly treats it as an absent file and there is nothing to assert.
+  it.skipIf(windowsHost)("only treats a missing log file as an empty current size", () => {
     const directory = makeTempDirectory();
     const filePath = NodePath.join(directory, "a".repeat(300));
 
diff --git a/packages/shared/src/model.test.ts b/packages/shared/src/model.test.ts
index da779442c9c7..d2c64e3d9458 100644
--- a/packages/shared/src/model.test.ts
+++ b/packages/shared/src/model.test.ts
@@ -10,6 +10,8 @@ import {
   getModelSelectionBooleanOptionValue,
   getModelSelectionStringOptionValue,
   getProviderOptionDescriptors,
+  readCustomModelEntries,
+  toCustomModelSetting,
   getProviderOptionBooleanSelectionValue,
   getProviderOptionStringSelectionValue,
 } from "./model.ts";
@@ -192,3 +194,53 @@ describe("applyClaudePromptEffortPrefix", () => {
     );
   });
 });
+
+describe("readCustomModelEntries", () => {
+  const capabilities: ModelCapabilities = {
+    optionDescriptors: [
+      {
+        id: "effort",
+        label: "Reasoning",
+        type: "select",
+        options: [{ id: "high", label: "High", isDefault: true }],
+        currentValue: "high",
+      },
+    ],
+  };
+
+  it("resolves bare slugs and entries, trimming and deduplicating on slug", () => {
+    expect(
+      readCustomModelEntries([
+        " bare ",
+        { slug: "named", name: " Named ", capabilities },
+        "bare",
+        { slug: "named", name: "Second" },
+        "",
+        { name: "no slug" },
+        42,
+      ]),
+    ).toEqual([
+      { slug: "bare", name: "bare", capabilities: null },
+      { slug: "named", name: "Named", capabilities },
+    ]);
+  });
+
+  it("drops unparseable capabilities but keeps the entry", () => {
+    expect(
+      readCustomModelEntries([{ slug: "x", capabilities: { optionDescriptors: "nope" } }]),
+    ).toEqual([{ slug: "x", name: "x", capabilities: null }]);
+    expect(readCustomModelEntries("not a list")).toEqual([]);
+  });
+
+  it("writes the compact stored shape back", () => {
+    expect(toCustomModelSetting({ slug: "x", name: "x", capabilities: null })).toBe("x");
+    expect(
+      toCustomModelSetting({ slug: "x", name: "x", capabilities: { optionDescriptors: [] } }),
+    ).toBe("x");
+    expect(toCustomModelSetting({ slug: "x", name: "X", capabilities })).toEqual({
+      slug: "x",
+      name: "X",
+      capabilities,
+    });
+  });
+});
diff --git a/packages/shared/src/model.ts b/packages/shared/src/model.ts
index cad7c8e8db86..940778fba1ea 100644
--- a/packages/shared/src/model.ts
+++ b/packages/shared/src/model.ts
@@ -1,12 +1,15 @@
 import {
+  type CustomModelSetting,
   MODEL_SLUG_ALIASES_BY_PROVIDER,
-  type ModelCapabilities,
+  ModelCapabilities,
   type ModelSelection,
   ProviderDriverKind,
   ProviderInstanceId,
   type ProviderOptionDescriptor,
   type ProviderOptionSelection,
 } from "@t3tools/contracts";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
 
 const DEFAULT_PROVIDER_DRIVER_KIND = ProviderDriverKind.make("codex");
 
@@ -247,6 +250,76 @@ export function normalizeCustomModelSlug(model: string | null | undefined): stri
   return model.trim() || null;
 }
 
+/** A custom model setting with its optional fields resolved. */
+export interface CustomModelDefinition {
+  readonly slug: string;
+  readonly name: string;
+  readonly capabilities: ModelCapabilities | null;
+}
+
+const decodeCustomModelCapabilities = Schema.decodeUnknownOption(ModelCapabilities);
+
+/**
+ * Read a `customModels` setting into resolved definitions. Accepts the typed
+ * union as well as the opaque `providerInstances[id].config` blob clients see,
+ * so it tolerates bare slugs, malformed rows, and unparseable capabilities
+ * (dropped rather than failing the whole list). Slugs are trimmed and
+ * deduplicated, first occurrence wins; `name` falls back to the slug.
+ */
+export function readCustomModelEntries(value: unknown): CustomModelDefinition[] {
+  if (!Array.isArray(value)) return [];
+  const entries: CustomModelDefinition[] = [];
+  const seen = new Set<string>();
+  for (const raw of value) {
+    const record =
+      typeof raw === "string"
+        ? { slug: raw }
+        : raw !== null && typeof raw === "object"
+          ? (raw as { slug?: unknown; name?: unknown; capabilities?: unknown })
+          : null;
+    if (!record) continue;
+    const slug = normalizeCustomModelSlug(typeof record.slug === "string" ? record.slug : null);
+    if (!slug || seen.has(slug)) continue;
+    seen.add(slug);
+    const name =
+      (typeof record.name === "string" ? normalizeCustomModelSlug(record.name) : null) ?? slug;
+    const capabilities =
+      record.capabilities === undefined || record.capabilities === null
+        ? null
+        : Option.getOrNull(decodeCustomModelCapabilities(record.capabilities));
+    entries.push({
+      slug,
+      name,
+      capabilities: capabilities
+        ? createModelCapabilities({ optionDescriptors: capabilities.optionDescriptors ?? [] })
+        : null,
+    });
+  }
+  return entries;
+}
+
+/** Slugs of a `customModels` setting, in stored order. */
+export function readCustomModelSlugs(value: unknown): string[] {
+  return readCustomModelEntries(value).map((entry) => entry.slug);
+}
+
+/**
+ * Write a definition back to the compact stored shape: a bare slug when it
+ * carries nothing custom, otherwise an entry with only the set fields.
+ */
+export function toCustomModelSetting(entry: CustomModelDefinition): CustomModelSetting {
+  const descriptors = entry.capabilities?.optionDescriptors ?? [];
+  const name = entry.name !== entry.slug ? entry.name : undefined;
+  if (!name && descriptors.length === 0) return entry.slug;
+  return {
+    slug: entry.slug,
+    ...(name ? { name } : {}),
+    ...(descriptors.length > 0
+      ? { capabilities: createModelCapabilities({ optionDescriptors: descriptors }) }
+      : {}),
+  };
+}
+
 export function resolveSelectableModel(
   provider: ProviderDriverKind,
   value: string | null | undefined,
diff --git a/packages/shared/src/orchestrationTiming.test.ts b/packages/shared/src/orchestrationTiming.test.ts
new file mode 100644
index 000000000000..dab35ad3e08c
--- /dev/null
+++ b/packages/shared/src/orchestrationTiming.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { formatDuration } from "./orchestrationTiming.ts";
+
+describe("formatDuration", () => {
+  it.each([
+    [0, "1ms"],
+    [250, "250ms"],
+    [1_500, "1.5s"],
+    [9_950, "10s"],
+    [22_000, "22s"],
+    [60_000, "1m"],
+    [65_000, "1m 5s"],
+    [119_500, "2m"],
+    [3_599_499, "59m 59s"],
+    [3_599_500, "1h"],
+    [3_600_000, "1h"],
+    [3_601_000, "1h 1s"],
+    [3_660_000, "1h 1m"],
+    [3_661_000, "1h 1m 1s"],
+    [7_199_500, "2h"],
+    [25_190_000, "6h 59m 50s"],
+    [90_061_000, "25h 1m 1s"],
+  ])("formats %d ms as %s", (durationMs, expected) => {
+    expect(formatDuration(durationMs)).toBe(expected);
+  });
+
+  it.each([-1, NaN, Infinity, -Infinity])("handles invalid durations: %s", (durationMs) => {
+    expect(formatDuration(durationMs)).toBe("0ms");
+  });
+});
diff --git a/packages/shared/src/orchestrationTiming.ts b/packages/shared/src/orchestrationTiming.ts
index 6914e1320d32..98829ae052ad 100644
--- a/packages/shared/src/orchestrationTiming.ts
+++ b/packages/shared/src/orchestrationTiming.ts
@@ -12,23 +12,20 @@ type SessionActivityState = {
 export function formatDuration(durationMs: number): string {
   if (!Number.isFinite(durationMs) || durationMs < 0) return "0ms";
   if (durationMs < 1_000) return `${Math.max(1, Math.round(durationMs))}ms`;
-  if (durationMs < 10_000) return `${(durationMs / 1_000).toFixed(1)}s`;
-  if (durationMs < 60_000) return `${Math.round(durationMs / 1_000)}s`;
-  const minutes = Math.floor(durationMs / 60_000);
-  const seconds = Math.round((durationMs % 60_000) / 1_000);
-  if (seconds === 0) return `${minutes}m`;
-  if (seconds === 60) return `${minutes + 1}m`;
-  return `${minutes}m ${seconds}s`;
-}
-
-export function formatElapsed(startIso: string, endIso: string | undefined): string | null {
-  if (!endIso) return null;
-  const startedAt = Date.parse(startIso);
-  const endedAt = Date.parse(endIso);
-  if (Number.isNaN(startedAt) || Number.isNaN(endedAt) || endedAt < startedAt) {
-    return null;
+  if (durationMs < 10_000) {
+    const tenths = Math.round(durationMs / 100) / 10;
+    return tenths >= 10 ? "10s" : `${tenths.toFixed(1)}s`;
   }
-  return formatDuration(endedAt - startedAt);
+  if (durationMs < 60_000) return `${Math.round(durationMs / 1_000)}s`;
+  const totalSeconds = Math.round(durationMs / 1_000);
+  const hours = Math.floor(totalSeconds / 3_600);
+  const minutes = Math.floor((totalSeconds % 3_600) / 60);
+  const seconds = totalSeconds % 60;
+  const parts: string[] = [];
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0) parts.push(`${seconds}s`);
+  return parts.join(" ");
 }
 
 export function isLatestTurnSettled(
diff --git a/packages/shared/src/preview.test.ts b/packages/shared/src/preview.test.ts
index fec4203c5334..14139216194e 100644
--- a/packages/shared/src/preview.test.ts
+++ b/packages/shared/src/preview.test.ts
@@ -2,7 +2,6 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   isLoopbackHost,
-  isPreviewableUrl,
   newPreviewTabId,
   normalizePreviewUrl,
   PreviewUrlNormalizationError,
@@ -27,24 +26,6 @@ describe("isLoopbackHost", () => {
   });
 });
 
-describe("isPreviewableUrl", () => {
-  it.each([
-    "http://localhost:5173",
-    "http://127.0.0.1:3000/path",
-    "http://0.0.0.0:8080",
-    "http://[::1]:5173",
-  ])("%s is previewable", (url) => {
-    expect(isPreviewableUrl(url)).toBe(true);
-  });
-
-  it.each(["https://example.com", "ws://localhost:5173", "file:///etc/passwd", "not-a-url", ""])(
-    "%s is not previewable",
-    (url) => {
-      expect(isPreviewableUrl(url)).toBe(false);
-    },
-  );
-});
-
 describe("normalizePreviewUrl", () => {
   it("treats bare loopback hosts as http", () => {
     expect(normalizePreviewUrl("localhost:5173")).toBe("http://localhost:5173/");
diff --git a/packages/shared/src/preview.ts b/packages/shared/src/preview.ts
index 926b30966e52..f0a781290b1c 100644
--- a/packages/shared/src/preview.ts
+++ b/packages/shared/src/preview.ts
@@ -36,17 +36,6 @@ export function isLoopbackHost(host: string): boolean {
   return false;
 }
 
-/** True when a raw URL string looks like a loopback dev URL we can preview. */
-export function isPreviewableUrl(rawUrl: string): boolean {
-  try {
-    const parsed = new URL(rawUrl);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
-    return isLoopbackHost(parsed.hostname);
-  } catch {
-    return false;
-  }
-}
-
 export class PreviewUrlNormalizationError extends Schema.TaggedErrorClass<PreviewUrlNormalizationError>()(
   "PreviewUrlNormalizationError",
   {
diff --git a/packages/shared/src/previewViewport.test.ts b/packages/shared/src/previewViewport.test.ts
index 3222e90d7be5..7a049376c50e 100644
--- a/packages/shared/src/previewViewport.test.ts
+++ b/packages/shared/src/previewViewport.test.ts
@@ -1,11 +1,6 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import {
-  PREVIEW_VIEWPORT_PRESETS,
-  previewViewportLabel,
-  previewViewportPresetOrientation,
-  resolvePreviewViewport,
-} from "./previewViewport.ts";
+import { PREVIEW_VIEWPORT_PRESETS, resolvePreviewViewport } from "./previewViewport.ts";
 
 describe("previewViewport", () => {
   it("resolves fill and exact freeform viewports", () => {
@@ -59,12 +54,4 @@ describe("previewViewport", () => {
       "Nest Hub Max",
     ]);
   });
-
-  it("formats settings for compact UI", () => {
-    expect(previewViewportLabel({ _tag: "fill" })).toBe("Fill panel");
-    expect(previewViewportLabel({ _tag: "freeform", width: 393, height: 852 })).toBe("393 × 852");
-    expect(previewViewportPresetOrientation({ _tag: "freeform", width: 852, height: 393 })).toBe(
-      "landscape",
-    );
-  });
 });
diff --git a/packages/shared/src/previewViewport.ts b/packages/shared/src/previewViewport.ts
index 1d70bca5dfbd..d1e066bee16d 100644
--- a/packages/shared/src/previewViewport.ts
+++ b/packages/shared/src/previewViewport.ts
@@ -173,14 +173,3 @@ export function resolvePreviewViewport(
     height: input.height,
   };
 }
-
-export function previewViewportLabel(viewport: PreviewViewportSetting): string {
-  return viewport._tag === "fill" ? "Fill panel" : `${viewport.width} × ${viewport.height}`;
-}
-
-export function previewViewportPresetOrientation(
-  viewport: PreviewViewportSetting,
-): "portrait" | "landscape" | null {
-  if (viewport._tag === "fill" || viewport.width === viewport.height) return null;
-  return viewport.width > viewport.height ? "landscape" : "portrait";
-}
diff --git a/packages/shared/src/relayAuth.test.ts b/packages/shared/src/relayAuth.test.ts
index 3abff9b52109..4e1f28eefdaa 100644
--- a/packages/shared/src/relayAuth.test.ts
+++ b/packages/shared/src/relayAuth.test.ts
@@ -5,7 +5,6 @@ import {
   ClerkPublishableKeyFrontendApiError,
   clerkFrontendApiHostnameFromPublishableKey,
   clerkFrontendApiUrlFromPublishableKey,
-  isAllowedClerkFrontendApiHostname,
 } from "./relayAuth.ts";
 
 const clerkPublishableKey = (hostname: string): string => `pk_test_${btoa(`${hostname}$`)}`;
@@ -75,14 +74,4 @@ describe("Clerk relay auth", () => {
     });
     expect((error as ClerkPublishableKeyFrontendApiError).cause).toBeInstanceOf(Error);
   });
-
-  it("allows standard Clerk hosts and an exact configured custom hostname", () => {
-    expect(isAllowedClerkFrontendApiHostname("example.clerk.accounts.dev", null)).toBe(true);
-    expect(isAllowedClerkFrontendApiHostname("example.clerk.accounts.com", null)).toBe(true);
-    expect(isAllowedClerkFrontendApiHostname("clerk.t3.codes", "clerk.t3.codes")).toBe(true);
-    expect(isAllowedClerkFrontendApiHostname("attacker.example", "clerk.t3.codes")).toBe(false);
-    expect(isAllowedClerkFrontendApiHostname("nested.clerk.t3.codes", "clerk.t3.codes")).toBe(
-      false,
-    );
-  });
 });
diff --git a/packages/shared/src/relayAuth.ts b/packages/shared/src/relayAuth.ts
index a384db77d8ac..4c5d766c1480 100644
--- a/packages/shared/src/relayAuth.ts
+++ b/packages/shared/src/relayAuth.ts
@@ -81,17 +81,6 @@ export function clerkFrontendApiHostnameFromPublishableKey(publishableKey: strin
   return parseClerkFrontendApi(publishableKey).hostname;
 }
 
-export function isAllowedClerkFrontendApiHostname(
-  hostname: string,
-  configuredHostname: string | null,
-): boolean {
-  return (
-    hostname.endsWith(".clerk.accounts.dev") ||
-    hostname.endsWith(".clerk.accounts.com") ||
-    hostname === configuredHostname
-  );
-}
-
 export function relayClerkTokenOptions(template: string) {
   return {
     template,
diff --git a/packages/shared/src/relayClient.test.ts b/packages/shared/src/relayClient.test.ts
index df39ef0b161d..1d556ed6dc30 100644
--- a/packages/shared/src/relayClient.test.ts
+++ b/packages/shared/src/relayClient.test.ts
@@ -18,6 +18,10 @@ import {
   makeCloudflaredRelayClient,
 } from "./relayClient.ts";
 
+// The suite runs the linux code path against the real filesystem, checking
+// POSIX exec bits that NTFS never reports; the win32 branch skips that check.
+const windowsHost = HostProcessPlatform.defaultValue() === "win32";
+
 const hostRuntimeLayer = (env: Record<string, string> = {}) =>
   Layer.mergeAll(
     Layer.succeed(HostProcessPlatform, "linux"),
@@ -63,102 +67,106 @@ const makeSpawnerLayer = (commands: Array<string>) =>
   );
 
 describe("RelayClient", () => {
-  it.effect("resolves explicit overrides before managed and PATH executables", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-cloudflared-test-",
-      });
-      const overridePath = `${baseDir}/override-cloudflared`;
-      yield* fileSystem.writeFileString(overridePath, "override");
-      yield* fileSystem.chmod(overridePath, 0o755);
-      const manager = yield* makeCloudflaredRelayClient({
-        baseDir,
-      });
+  it.effect.skipIf(windowsHost)(
+    "resolves explicit overrides before managed and PATH executables",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-cloudflared-test-",
+        });
+        const overridePath = `${baseDir}/override-cloudflared`;
+        yield* fileSystem.writeFileString(overridePath, "override");
+        yield* fileSystem.chmod(overridePath, 0o755);
+        const manager = yield* makeCloudflaredRelayClient({
+          baseDir,
+        });
 
-      expect(
-        yield* manager.resolve.pipe(
-          Effect.provideService(
-            ConfigProvider.ConfigProvider,
-            ConfigProvider.fromEnv({
-              env: { PATH: "", T3CODE_CLOUDFLARED_PATH: overridePath },
-            }),
+        expect(
+          yield* manager.resolve.pipe(
+            Effect.provideService(
+              ConfigProvider.ConfigProvider,
+              ConfigProvider.fromEnv({
+                env: { PATH: "", T3CODE_CLOUDFLARED_PATH: overridePath },
+              }),
+            ),
+          ),
+        ).toEqual({
+          status: "available",
+          executablePath: overridePath,
+          source: "override",
+          version: CLOUDFLARED_VERSION,
+        });
+      }).pipe(
+        Effect.scoped,
+        Effect.provide(
+          Layer.mergeAll(
+            NodeServices.layer,
+            makeHttpClientLayer(new Uint8Array()),
+            makeSpawnerLayer([]),
+            hostRuntimeLayer(),
           ),
-        ),
-      ).toEqual({
-        status: "available",
-        executablePath: overridePath,
-        source: "override",
-        version: CLOUDFLARED_VERSION,
-      });
-    }).pipe(
-      Effect.scoped,
-      Effect.provide(
-        Layer.mergeAll(
-          NodeServices.layer,
-          makeHttpClientLayer(new Uint8Array()),
-          makeSpawnerLayer([]),
-          hostRuntimeLayer(),
         ),
       ),
-    ),
   );
 
-  it.effect("downloads, verifies, validates, and atomically installs the managed executable", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-cloudflared-test-",
-      });
-      const bytes = new TextEncoder().encode("test-cloudflared-binary");
-      const manager = yield* makeCloudflaredRelayClient({
-        baseDir,
-        releaseAsset: {
-          url: "https://example.test/cloudflared",
-          sha256: Encoding.encodeHex(sha256(bytes)),
-          archive: "binary",
-        },
-      });
+  it.effect.skipIf(windowsHost)(
+    "downloads, verifies, validates, and atomically installs the managed executable",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-cloudflared-test-",
+        });
+        const bytes = new TextEncoder().encode("test-cloudflared-binary");
+        const manager = yield* makeCloudflaredRelayClient({
+          baseDir,
+          releaseAsset: {
+            url: "https://example.test/cloudflared",
+            sha256: Encoding.encodeHex(sha256(bytes)),
+            archive: "binary",
+          },
+        });
 
-      const progress: Array<string> = [];
-      const installed = yield* manager.installWithProgress((event) =>
-        Effect.sync(() => {
-          if (event.type === "progress") {
-            progress.push(event.stage);
-          }
-        }),
-      );
-      const managedPath = `${baseDir}/tools/cloudflared/${CLOUDFLARED_VERSION}/linux-x64/cloudflared`;
-      expect(installed).toEqual({
-        status: "available",
-        executablePath: managedPath,
-        source: "managed",
-        version: CLOUDFLARED_VERSION,
-      });
-      expect(new TextDecoder().decode(yield* fileSystem.readFile(managedPath))).toBe(
-        "test-cloudflared-binary",
-      );
-      expect(progress).toEqual([
-        "checking",
-        "waiting_for_lock",
-        "downloading",
-        "verifying",
-        "installing",
-        "validating",
-        "activating",
-      ]);
-      expect(yield* manager.resolve).toEqual(installed);
-    }).pipe(
-      Effect.scoped,
-      Effect.provide(
-        Layer.mergeAll(
-          NodeServices.layer,
-          makeHttpClientLayer(new TextEncoder().encode("test-cloudflared-binary")),
-          makeSpawnerLayer([]),
-          hostRuntimeLayer(),
+        const progress: Array<string> = [];
+        const installed = yield* manager.installWithProgress((event) =>
+          Effect.sync(() => {
+            if (event.type === "progress") {
+              progress.push(event.stage);
+            }
+          }),
+        );
+        const managedPath = `${baseDir}/tools/cloudflared/${CLOUDFLARED_VERSION}/linux-x64/cloudflared`;
+        expect(installed).toEqual({
+          status: "available",
+          executablePath: managedPath,
+          source: "managed",
+          version: CLOUDFLARED_VERSION,
+        });
+        expect(new TextDecoder().decode(yield* fileSystem.readFile(managedPath))).toBe(
+          "test-cloudflared-binary",
+        );
+        expect(progress).toEqual([
+          "checking",
+          "waiting_for_lock",
+          "downloading",
+          "verifying",
+          "installing",
+          "validating",
+          "activating",
+        ]);
+        expect(yield* manager.resolve).toEqual(installed);
+      }).pipe(
+        Effect.scoped,
+        Effect.provide(
+          Layer.mergeAll(
+            NodeServices.layer,
+            makeHttpClientLayer(new TextEncoder().encode("test-cloudflared-binary")),
+            makeSpawnerLayer([]),
+            hostRuntimeLayer(),
+          ),
         ),
       ),
-    ),
   );
 
   it.effect("rejects downloads whose checksum does not match the pinned manifest", () =>
@@ -192,7 +200,7 @@ describe("RelayClient", () => {
     ),
   );
 
-  it.effect("serializes concurrent installs within one runtime", () => {
+  it.effect.skipIf(windowsHost)("serializes concurrent installs within one runtime", () => {
     const commands: Array<string> = [];
     const bytes = new TextEncoder().encode("test-cloudflared-binary");
     return Effect.gen(function* () {
@@ -227,45 +235,48 @@ describe("RelayClient", () => {
     );
   });
 
-  it.effect("observes PATH changes after the manager has been constructed", () => {
-    const env = { PATH: "" };
-    return Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const baseDir = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "t3-cloudflared-test-",
-      });
-      const binDir = `${baseDir}/bin`;
-      const executablePath = `${binDir}/cloudflared`;
-      const manager = yield* makeCloudflaredRelayClient({
-        baseDir,
-      });
+  it.effect.skipIf(windowsHost)(
+    "observes PATH changes after the manager has been constructed",
+    () => {
+      const env = { PATH: "" };
+      return Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const baseDir = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "t3-cloudflared-test-",
+        });
+        const binDir = `${baseDir}/bin`;
+        const executablePath = `${binDir}/cloudflared`;
+        const manager = yield* makeCloudflaredRelayClient({
+          baseDir,
+        });
 
-      expect(yield* manager.resolve).toEqual({
-        status: "missing",
-        version: CLOUDFLARED_VERSION,
-      });
+        expect(yield* manager.resolve).toEqual({
+          status: "missing",
+          version: CLOUDFLARED_VERSION,
+        });
 
-      yield* fileSystem.makeDirectory(binDir);
-      yield* fileSystem.writeFileString(executablePath, "cloudflared");
-      yield* fileSystem.chmod(executablePath, 0o755);
-      env.PATH = binDir;
+        yield* fileSystem.makeDirectory(binDir);
+        yield* fileSystem.writeFileString(executablePath, "cloudflared");
+        yield* fileSystem.chmod(executablePath, 0o755);
+        env.PATH = binDir;
 
-      expect(yield* manager.resolve).toEqual({
-        status: "available",
-        executablePath,
-        source: "path",
-        version: CLOUDFLARED_VERSION,
-      });
-    }).pipe(
-      Effect.scoped,
-      Effect.provide(
-        Layer.mergeAll(
-          NodeServices.layer,
-          makeHttpClientLayer(new Uint8Array()),
-          makeSpawnerLayer([]),
-          hostRuntimeLayer(env),
+        expect(yield* manager.resolve).toEqual({
+          status: "available",
+          executablePath,
+          source: "path",
+          version: CLOUDFLARED_VERSION,
+        });
+      }).pipe(
+        Effect.scoped,
+        Effect.provide(
+          Layer.mergeAll(
+            NodeServices.layer,
+            makeHttpClientLayer(new Uint8Array()),
+            makeSpawnerLayer([]),
+            hostRuntimeLayer(env),
+          ),
         ),
-      ),
-    );
-  });
+      );
+    },
+  );
 });
diff --git a/packages/shared/src/searchRanking.test.ts b/packages/shared/src/searchRanking.test.ts
index 7e2ccce6e063..8ddf02ec8498 100644
--- a/packages/shared/src/searchRanking.test.ts
+++ b/packages/shared/src/searchRanking.test.ts
@@ -1,7 +1,6 @@
 import { describe, expect, it } from "vite-plus/test";
 
 import {
-  compareRankedSearchResults,
   insertRankedSearchResult,
   normalizeSearchQuery,
   scoreQueryMatch,
@@ -90,6 +89,5 @@ describe("insertRankedSearchResult", () => {
     insertRankedSearchResult(ranked, { item: "c", score: 30, tieBreaker: "c" }, 2);
 
     expect(ranked.map((entry) => entry.item)).toEqual(["a", "b"]);
-    expect(compareRankedSearchResults(ranked[0]!, ranked[1]!)).toBeLessThan(0);
   });
 });
diff --git a/packages/shared/src/searchRanking.ts b/packages/shared/src/searchRanking.ts
index b2fb2e223d3b..c8ec69e39703 100644
--- a/packages/shared/src/searchRanking.ts
+++ b/packages/shared/src/searchRanking.ts
@@ -135,7 +135,7 @@ export function scoreQueryMatch(input: {
   return null;
 }
 
-export function compareRankedSearchResults<T>(
+function compareRankedSearchResults<T>(
   left: RankedSearchResult<T>,
   right: RankedSearchResult<T>,
 ): number {
diff --git a/packages/shared/src/serverSettings.test.ts b/packages/shared/src/serverSettings.test.ts
index 64b0e1b8337b..31f056c211e9 100644
--- a/packages/shared/src/serverSettings.test.ts
+++ b/packages/shared/src/serverSettings.test.ts
@@ -11,43 +11,34 @@ import { resolveServerBackgroundActivitySettings } from "./backgroundActivitySet
 import { createModelSelection } from "./model.ts";
 import {
   applyServerSettingsPatch,
-  extractPersistedServerObservabilitySettings,
   isModelSelectionProviderEnabled,
-  normalizePersistedServerSettingString,
   parsePersistedServerObservabilitySettings,
   resolveSourceControlWriterModelSelection,
 } from "./serverSettings.ts";
 
 describe("serverSettings helpers", () => {
-  it("normalizes optional persisted strings", () => {
-    expect(normalizePersistedServerSettingString(undefined)).toBeUndefined();
-    expect(normalizePersistedServerSettingString("   ")).toBeUndefined();
-    expect(normalizePersistedServerSettingString("  http://localhost:4318/v1/traces  ")).toBe(
-      "http://localhost:4318/v1/traces",
-    );
-  });
-
-  it("extracts persisted observability settings", () => {
+  it("ignores missing and blank persisted observability URLs", () => {
+    expect(parsePersistedServerObservabilitySettings("{}")).toEqual({
+      otlpTracesUrl: undefined,
+      otlpMetricsUrl: undefined,
+    });
     expect(
-      extractPersistedServerObservabilitySettings({
-        observability: {
-          otlpTracesUrl: "  http://localhost:4318/v1/traces  ",
-          otlpMetricsUrl: "  http://localhost:4318/v1/metrics  ",
-        },
-      }),
+      parsePersistedServerObservabilitySettings(
+        JSON.stringify({ observability: { otlpTracesUrl: "   ", otlpMetricsUrl: "" } }),
+      ),
     ).toEqual({
-      otlpTracesUrl: "http://localhost:4318/v1/traces",
-      otlpMetricsUrl: "http://localhost:4318/v1/metrics",
+      otlpTracesUrl: undefined,
+      otlpMetricsUrl: undefined,
     });
   });
 
-  it("parses lenient persisted settings JSON", () => {
+  it("parses lenient persisted settings JSON and trims observability URLs", () => {
     expect(
       parsePersistedServerObservabilitySettings(
         JSON.stringify({
           observability: {
-            otlpTracesUrl: "http://localhost:4318/v1/traces",
-            otlpMetricsUrl: "http://localhost:4318/v1/metrics",
+            otlpTracesUrl: "  http://localhost:4318/v1/traces  ",
+            otlpMetricsUrl: "  http://localhost:4318/v1/metrics  ",
           },
         }),
       ),
@@ -322,6 +313,28 @@ describe("serverSettings helpers", () => {
     expect(Object.keys(removed.usageLimitSources)).toEqual([hubB]);
   });
 
+  it("replaces and removes individual usage prices without clobbering other models", () => {
+    const prices = { inputCostPerMillionTokens: 2, outputCostPerMillionTokens: 8 };
+    const current = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
+      usagePriceOverrides: { "example-model": { ...prices, cacheReadCostPerMillionTokens: 0.5 } },
+    });
+    const added = applyServerSettingsPatch(current, {
+      usagePriceOverrides: { "other-model": prices },
+    });
+    const replaced = applyServerSettingsPatch(added, {
+      usagePriceOverrides: { "example-model": prices },
+    });
+    expect(replaced.usagePriceOverrides).toEqual({
+      "example-model": prices,
+      "other-model": prices,
+    });
+    const removed = applyServerSettingsPatch(replaced, {
+      usagePriceOverrides: { "example-model": null },
+    });
+    expect(removed.usagePriceOverrides).toEqual({ "other-model": prices });
+    expect(current.usagePriceOverrides["example-model"]?.cacheReadCostPerMillionTokens).toBe(0.5);
+  });
+
   it("stores background activity profiles as a versioned object and syncs legacy aliases", () => {
     const next = applyServerSettingsPatch(DEFAULT_SERVER_SETTINGS, {
       backgroundActivity: {
diff --git a/packages/shared/src/serverSettings.ts b/packages/shared/src/serverSettings.ts
index 67f73f84063a..dc50da2d7627 100644
--- a/packages/shared/src/serverSettings.ts
+++ b/packages/shared/src/serverSettings.ts
@@ -69,14 +69,14 @@ export interface PersistedServerObservabilitySettings {
   readonly otlpMetricsUrl: string | undefined;
 }
 
-export function normalizePersistedServerSettingString(
+function normalizePersistedServerSettingString(
   value: string | null | undefined,
 ): string | undefined {
   const trimmed = value?.trim();
   return trimmed && trimmed.length > 0 ? trimmed : undefined;
 }
 
-export function extractPersistedServerObservabilitySettings(input: {
+function extractPersistedServerObservabilitySettings(input: {
   readonly observability?: {
     readonly otlpTracesUrl?: string;
     readonly otlpMetricsUrl?: string;
@@ -123,10 +123,10 @@ function mergeModelSelectionOptionsById(input: {
 }
 
 /** Upsert each patched entry; `null` removes it. Entries the patch omits are untouched. */
-function mergeUsageLimitSources(
-  current: ServerSettings["usageLimitSources"],
-  patch: NonNullable<ServerSettingsPatch["usageLimitSources"]>,
-): ServerSettings["usageLimitSources"] {
+function mergeSettingsEntries<Value>(
+  current: Readonly<Record<string, Value>>,
+  patch: Readonly<Record<string, Value | null>>,
+): Record<string, Value> {
   const next = new Map(Object.entries(current));
   for (const [id, config] of Object.entries(patch)) {
     if (config === null) {
@@ -135,7 +135,7 @@ function mergeUsageLimitSources(
       next.set(id, config);
     }
   }
-  return Object.fromEntries(next) as ServerSettings["usageLimitSources"];
+  return Object.fromEntries(next);
 }
 
 export function applyServerSettingsPatch(
@@ -150,6 +150,7 @@ export function applyServerSettingsPatch(
     backgroundActivity,
     // Merged per entry below; its `null` removals must not reach deepMerge.
     usageLimitSources: usageLimitSourcesPatch,
+    usagePriceOverrides: usagePriceOverridesPatch,
     ...patchForMerge
   } = patch;
   const currentBackgroundActivity = normalizeServerBackgroundActivitySettings(current);
@@ -208,12 +209,20 @@ export function applyServerSettingsPatch(
       : {}),
     ...(usageLimitSourcesPatch !== undefined
       ? {
-          usageLimitSources: mergeUsageLimitSources(
+          usageLimitSources: mergeSettingsEntries(
             current.usageLimitSources,
             usageLimitSourcesPatch,
           ),
         }
       : {}),
+    ...(usagePriceOverridesPatch !== undefined
+      ? {
+          usagePriceOverrides: mergeSettingsEntries(
+            current.usagePriceOverrides,
+            usagePriceOverridesPatch,
+          ),
+        }
+      : {}),
     ...(patch.sourceControlWriterModelSelection !== undefined
       ? { sourceControlWriterModelSelection: patch.sourceControlWriterModelSelection }
       : {}),
diff --git a/packages/shared/src/shell.test.ts b/packages/shared/src/shell.test.ts
index e3046c03abed..621fe49b3087 100644
--- a/packages/shared/src/shell.test.ts
+++ b/packages/shared/src/shell.test.ts
@@ -2,11 +2,14 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { it as effectIt } from "@effect/vitest";
 import { HostProcessEnvironment, HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as TestClock from "effect/testing/TestClock";
 import { describe, expect, it, vi } from "vite-plus/test";
 
 import {
-  extractPathFromShellOutput,
   CommandAvailability,
+  CommandResolutionCache,
   type CommandAvailabilityChecker,
   isCommandAvailable,
   listLoginShellCandidates,
@@ -35,28 +38,6 @@ const withWindowsEnvironmentMocks = <A, E, R>(
     Effect.provideService(CommandAvailability, commandAvailable),
   );
 
-describe("extractPathFromShellOutput", () => {
-  it("extracts the path between capture markers", () => {
-    expect(
-      extractPathFromShellOutput(
-        "__T3CODE_PATH_START__\n/opt/homebrew/bin:/usr/bin\n__T3CODE_PATH_END__\n",
-      ),
-    ).toBe("/opt/homebrew/bin:/usr/bin");
-  });
-
-  it("ignores shell startup noise around the capture markers", () => {
-    expect(
-      extractPathFromShellOutput(
-        "Welcome to fish\n__T3CODE_PATH_START__\n/opt/homebrew/bin:/usr/bin\n__T3CODE_PATH_END__\nBye\n",
-      ),
-    ).toBe("/opt/homebrew/bin:/usr/bin");
-  });
-
-  it("returns null when the markers are missing", () => {
-    expect(extractPathFromShellOutput("/opt/homebrew/bin /usr/bin")).toBeNull();
-  });
-});
-
 describe("readPathFromLoginShell", () => {
   it("uses a shell-agnostic printenv PATH probe", () => {
     const execFile = vi.fn<
@@ -375,6 +356,123 @@ effectIt.layer(NodeServices.layer)("resolveCommandPath", (it) => {
       expect(result._tag).toBe("Failure");
     }),
   );
+
+  // Records every path the scan stats, without ever reporting a match, so the
+  // walk runs to exhaustion and the probe set can be inspected. Assertions
+  // below count probes rather than naming paths: `Path` is the host's, so the
+  // separator differs between a Windows and a Linux CI runner.
+  const recordProbes = (env: NodeJS.ProcessEnv) =>
+    Effect.gen(function* () {
+      const probed: Array<string> = [];
+      const result = yield* resolveCommandPath("definitely-not-installed", { env }).pipe(
+        Effect.provideService(HostProcessPlatform, "win32"),
+        Effect.provideService(CommandResolutionCache, new Map()),
+        Effect.provide(
+          FileSystem.layerNoop({
+            stat: (filePath) =>
+              Effect.sync(() => {
+                probed.push(filePath);
+                return { type: "Directory" } as FileSystem.File.Info;
+              }),
+          }),
+        ),
+        Effect.result,
+      );
+
+      expect(result._tag).toBe("Failure");
+      return probed;
+    });
+
+  it.effect("visits a repeated PATH directory only once", () =>
+    Effect.gen(function* () {
+      const probed = yield* recordProbes({
+        PATH: "C:\\bin;C:\\other;C:\\bin;C:\\other",
+        PATHEXT: ".COM;.EXE",
+      });
+
+      // Two directories, two extensions, upper and lowercase spellings.
+      expect(probed).toHaveLength(8);
+      expect(new Set(probed).size).toBe(probed.length);
+    }),
+  );
+
+  it.effect("still visits a PATH entry that differs only in case", () =>
+    Effect.gen(function* () {
+      const probed = yield* recordProbes({
+        PATH: "C:\\bin;C:\\BIN",
+        PATHEXT: ".COM;.EXE",
+      });
+
+      // Deliberately not folded together. Windows 10+ can mark a directory
+      // case-sensitive, so the two spellings are not provably one directory and
+      // skipping the second could hide a command that is really there.
+      expect(probed).toHaveLength(8);
+    }),
+  );
+
+  it.effect.each(["audit-command", "audit-command.CMD"])(
+    "resolves lowercase executable files for %s in a case-sensitive Windows PATH directory",
+    (command) =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const cwd = yield* fs.makeTempDirectoryScoped({ prefix: "t3-case-sensitive-path-" });
+        const executable = path.join(cwd, "audit-command.cmd");
+        yield* fs.writeFileString(executable, "@echo off\n");
+
+        const resolved = yield* resolveCommandPath(command, {
+          env: { PATH: cwd, PATHEXT: ".CMD" },
+        }).pipe(
+          Effect.provideService(HostProcessPlatform, "win32"),
+          Effect.provideService(CommandResolutionCache, new Map()),
+          Effect.provideService(FileSystem.FileSystem, {
+            ...fs,
+            // Keep this case-sensitive fixture portable to case-insensitive hosts.
+            stat: (filePath) =>
+              fs.stat(filePath === executable ? filePath : path.join(cwd, "missing")),
+          }),
+        );
+
+        expect(resolved).toBe(executable);
+      }),
+  );
+
+  it.effect("keeps cached misses until expiry while allowing explicit paths", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const cwd = yield* fs.makeTempDirectoryScoped({ prefix: "t3-path-cache-" });
+      const executable = path.join(cwd, "appeared.CMD");
+      const options = { env: { PATH: `${cwd};${cwd}`, PATHEXT: ".CMD" } };
+
+      expect((yield* resolveCommandPath("appeared", options).pipe(Effect.result))._tag).toBe(
+        "Failure",
+      );
+      yield* fs.writeFileString(executable, "@echo off\n");
+      expect((yield* resolveCommandPath("appeared", options).pipe(Effect.result))._tag).toBe(
+        "Failure",
+      );
+      expect(yield* resolveCommandPath(executable, options)).toBe(executable);
+      yield* TestClock.adjust("30 seconds");
+      expect(yield* resolveCommandPath("appeared", options)).toBe(executable);
+    }).pipe(
+      Effect.provideService(HostProcessPlatform, "win32"),
+      Effect.provideService(CommandResolutionCache, new Map()),
+    ),
+  );
+
+  it.effect("keeps upper and lowercase PATHEXT candidates", () =>
+    Effect.gen(function* () {
+      const probed = yield* recordProbes({
+        PATH: "C:\\bin",
+        PATHEXT: ".COM;.EXE;.BAT;.CMD",
+      });
+
+      expect(probed).toHaveLength(8);
+      expect(probed.filter((filePath) => /\.(COM|EXE|BAT|CMD)$/.test(filePath))).toHaveLength(4);
+      expect(probed.filter((filePath) => /\.(com|exe|bat|cmd)$/.test(filePath))).toHaveLength(4);
+    }),
+  );
 });
 
 effectIt.layer(NodeServices.layer)("resolveSpawnCommand", (it) => {
diff --git a/packages/shared/src/shell.ts b/packages/shared/src/shell.ts
index 4c86c8886312..07ac73f8c6a7 100644
--- a/packages/shared/src/shell.ts
+++ b/packages/shared/src/shell.ts
@@ -12,8 +12,6 @@ import * as Path from "effect/Path";
 import { HostProcessEnvironment, HostProcessPlatform } from "./hostProcess.ts";
 import * as Context from "effect/Context";
 
-const PATH_CAPTURE_START = "__T3CODE_PATH_START__";
-const PATH_CAPTURE_END = "__T3CODE_PATH_END__";
 const SHELL_ENV_NAME_PATTERN = /^[A-Z0-9_]+$/;
 const WINDOWS_PATH_DELIMITER = ";";
 const POSIX_PATH_DELIMITER = ":";
@@ -179,18 +177,6 @@ export function listLoginShellCandidates(
   return candidates;
 }
 
-export function extractPathFromShellOutput(output: string): string | null {
-  const startIndex = output.indexOf(PATH_CAPTURE_START);
-  if (startIndex === -1) return null;
-
-  const valueStartIndex = startIndex + PATH_CAPTURE_START.length;
-  const endIndex = output.indexOf(PATH_CAPTURE_END, valueStartIndex);
-  if (endIndex === -1) return null;
-
-  const pathValue = output.slice(valueStartIndex, endIndex).trim();
-  return pathValue.length > 0 ? pathValue : null;
-}
-
 export function readPathFromLoginShell(
   shell: string,
   execFile: ExecFileSyncLike = NodeChildProcess.execFileSync,
@@ -544,7 +530,8 @@ function cacheCommandResolution(
   });
 }
 
-const isExecutableFile = Effect.fn("shell.isExecutableFile")(function* (
+// Trace each command lookup, not every candidate file it probes.
+const isExecutableFile = Effect.fnUntraced(function* (
   filePath: string,
   platform: NodeJS.Platform,
   windowsPathExtensions: ReadonlyArray<string>,
@@ -605,12 +592,15 @@ const resolveCommandPathForPlatform = Effect.fn("shell.resolveCommandPathForPlat
     return cached.resolvedPath;
   }
 
+  // Keep case variants: Windows can make PATH directories case-sensitive.
   const pathEntries: string[] = [];
+  const seenPathEntries = new Set<string>();
   for (const entry of pathValue.split(pathDelimiterForPlatform(platform))) {
     const pathEntry = stripWrappingQuotes(entry.trim());
-    if (pathEntry.length > 0) {
-      pathEntries.push(pathEntry);
-    }
+    if (pathEntry.length === 0 || seenPathEntries.has(pathEntry)) continue;
+
+    seenPathEntries.add(pathEntry);
+    pathEntries.push(pathEntry);
   }
 
   for (const pathEntry of pathEntries) {
diff --git a/packages/shared/src/testing/longTempDir.ts b/packages/shared/src/testing/longTempDir.ts
new file mode 100644
index 000000000000..8a18abb8ce42
--- /dev/null
+++ b/packages/shared/src/testing/longTempDir.ts
@@ -0,0 +1,19 @@
+// @effect-diagnostics nodeBuiltinImport:off - runs once at test setup, outside any Effect runtime.
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import { HostProcessPlatform } from "../hostProcess.ts";
+
+// GitHub's Windows runners hand out the temp directory by its 8.3 short name
+// (C:\Users\RUNNER~1\...). Anything that canonicalises a path, such as git or
+// realpath, reports the long form, so equality checks between a temp path and
+// its canonical form fail. Node reads TEMP/TMP on every os.tmpdir() call, so
+// pointing them at the long form fixes every temp directory the suite makes.
+if (HostProcessPlatform.defaultValue() === "win32") {
+  try {
+    const longForm = NodeFS.realpathSync.native(NodeOS.tmpdir());
+    process.env.TEMP = longForm;
+    process.env.TMP = longForm;
+  } catch {
+    // Leave the host's value alone if it cannot be resolved.
+  }
+}
diff --git a/packages/shared/src/testing/symlinks.ts b/packages/shared/src/testing/symlinks.ts
new file mode 100644
index 000000000000..4e76984ca210
--- /dev/null
+++ b/packages/shared/src/testing/symlinks.ts
@@ -0,0 +1,29 @@
+// @effect-diagnostics nodeBuiltinImport:off - one synchronous probe at module load, outside any Effect runtime.
+import * as NodeFS from "node:fs";
+import * as NodeOS from "node:os";
+import * as NodePath from "node:path";
+
+/**
+ * Whether this host lets an unprivileged process create symlinks. Windows
+ * refuses without Developer Mode or elevation, so tests that plant a symlink
+ * to prove containment or escape detection should `skipIf(!symlinksSupported)`
+ * rather than fail at setup. Probed once per process.
+ */
+export const symlinksSupported: boolean = (() => {
+  let directory: string | undefined;
+  try {
+    directory = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-symlink-probe-"));
+    NodeFS.symlinkSync(NodePath.join(directory, "target"), NodePath.join(directory, "link"));
+    return true;
+  } catch {
+    return false;
+  } finally {
+    // Cleanup must not decide the answer: a transient EPERM/EBUSY on the
+    // probe directory would otherwise throw out of module initialisation.
+    try {
+      if (directory !== undefined) NodeFS.rmSync(directory, { recursive: true, force: true });
+    } catch {
+      // Leave the probe directory behind rather than fail every importer.
+    }
+  }
+})();
diff --git a/packages/shared/src/threadReference.test.ts b/packages/shared/src/threadReference.test.ts
index 693fabc66b16..60600c7e1465 100644
--- a/packages/shared/src/threadReference.test.ts
+++ b/packages/shared/src/threadReference.test.ts
@@ -3,6 +3,32 @@ import { describe, expect, it } from "vite-plus/test";
 import { resolveThreadReferenceCopyTarget } from "./threadReference.ts";
 
 describe("resolveThreadReferenceCopyTarget", () => {
+  it("does not copy another reference while the open panel URL is unavailable", () => {
+    expect(
+      resolveThreadReferenceCopyTarget({
+        threadId: "thread-1",
+        openPanelPullRequestUrl: null,
+        linkedPullRequestUrl: "https://github.com/t3/pr/12",
+        detectedPullRequestUrl: "https://github.com/t3/pr/13",
+      }),
+    ).toBeNull();
+  });
+
+  it("prefers the open panel pull request over linked and detected pull requests", () => {
+    expect(
+      resolveThreadReferenceCopyTarget({
+        threadId: "thread-1",
+        openPanelPullRequestUrl: "https://github.com/t3/pr/14",
+        linkedPullRequestUrl: "https://github.com/t3/pr/12",
+        detectedPullRequestUrl: "https://github.com/t3/pr/13",
+      }),
+    ).toMatchObject({
+      kind: "pull-request",
+      value: "https://github.com/t3/pr/14",
+      successTitle: "PR link copied",
+    });
+  });
+
   it("prefers a durable linked pull request", () => {
     expect(
       resolveThreadReferenceCopyTarget({
diff --git a/packages/shared/src/threadReference.ts b/packages/shared/src/threadReference.ts
index cb4fc9dd5c20..20eac6fba039 100644
--- a/packages/shared/src/threadReference.ts
+++ b/packages/shared/src/threadReference.ts
@@ -8,10 +8,14 @@ export interface ThreadReferenceCopyTarget {
 
 export function resolveThreadReferenceCopyTarget(input: {
   readonly threadId: string;
+  /** Undefined means no PR panel; null means its URL is not available yet. */
+  readonly openPanelPullRequestUrl?: string | null | undefined;
   readonly linkedPullRequestUrl?: string | null;
   readonly detectedPullRequestUrl?: string | null;
-}): ThreadReferenceCopyTarget {
-  const pullRequestUrl = input.linkedPullRequestUrl ?? input.detectedPullRequestUrl;
+}): ThreadReferenceCopyTarget | null {
+  if (input.openPanelPullRequestUrl === null) return null;
+  const pullRequestUrl =
+    input.openPanelPullRequestUrl ?? input.linkedPullRequestUrl ?? input.detectedPullRequestUrl;
   return pullRequestUrl
     ? {
         kind: "pull-request",
diff --git a/packages/shared/src/usageMerge.ts b/packages/shared/src/usageMerge.ts
index 428599d51c74..95982bf507da 100644
--- a/packages/shared/src/usageMerge.ts
+++ b/packages/shared/src/usageMerge.ts
@@ -173,7 +173,7 @@ function bucketTokens(bucket: UsageBucket): number {
   );
 }
 
-function isCompatibleContractVersion(version: number, expected: number): boolean {
+export function isCompatibleUsageContractVersion(version: number, expected: number): boolean {
   return version >= USAGE_MERGE_COMPATIBLE_SINCE && version <= expected;
 }
 
@@ -220,7 +220,9 @@ export function mergeUsage(
   const current: EnvironmentUsage[] = [];
   const staleEnvironments: EnvironmentId[] = [];
   for (const environment of environments) {
-    if (isCompatibleContractVersion(environment.summary.contractVersion, expectedContractVersion)) {
+    if (
+      isCompatibleUsageContractVersion(environment.summary.contractVersion, expectedContractVersion)
+    ) {
       current.push(environment);
     } else {
       staleEnvironments.push(environment.environmentId);
diff --git a/packages/ssh/src/config.test.ts b/packages/ssh/src/config.test.ts
index 0446370337ad..4fd3b7636d3f 100644
--- a/packages/ssh/src/config.test.ts
+++ b/packages/ssh/src/config.test.ts
@@ -1,3 +1,4 @@
+import * as NodePath from "@effect/platform-node/NodePath";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
 import * as Effect from "effect/Effect";
@@ -133,6 +134,6 @@ describe("ssh config", () => {
         "/tmp/home",
       );
       assert.equal(pattern, "/tmp/home/.ssh/config.d/*.conf");
-    }).pipe(Effect.provide(NodeServices.layer)),
+    }).pipe(Effect.provide(NodePath.layerPosix)),
   );
 });
diff --git a/packages/ssh/src/runnerProcess.test.ts b/packages/ssh/src/runnerProcess.test.ts
new file mode 100644
index 000000000000..d89ee5582c35
--- /dev/null
+++ b/packages/ssh/src/runnerProcess.test.ts
@@ -0,0 +1,307 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, describe, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import * as NodeNet from "node:net";
+
+import { buildRemoteT3RunnerScript } from "./tunnel.ts";
+
+const Started = Schema.Struct({
+  pid: Schema.Number,
+  port: Schema.Number,
+  args: Schema.Array(Schema.String),
+});
+const decodeStarted = Schema.decodeUnknownSync(Schema.fromJsonString(Started));
+
+describe.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+  "remote runner process ownership",
+  () => {
+    it.live.each(["npx", "npm"] as const)(
+      "keeps the server PID and graceful shutdown through the %s fallback",
+      (packageManager) =>
+        Effect.gen(function* () {
+          const fs = yield* FileSystem.FileSystem;
+          const path = yield* Path.Path;
+          const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+          const fixture = yield* fs.makeTempDirectoryScoped({ prefix: "t3-runner-" });
+          const bin = path.join(fixture, "bin");
+          const cliPath = path.join(fixture, "installed cli.mjs");
+          const callsPath = path.join(fixture, "package-manager-calls.jsonl");
+          const packageSpec = "t3@0.0.35";
+          yield* fs.makeDirectory(bin);
+          yield* fs.symlink(process.execPath, path.join(bin, "node"));
+          yield* fs.writeFileString(
+            cliPath,
+            `#!/usr/bin/env node
+import * as net from "node:net";
+const server = net.createServer((socket) => {
+  socket.end();
+  server.close();
+});
+process.on("SIGTERM", () => server.close(() => {
+  process.stdout.write("graceful shutdown\\n");
+}));
+server.listen(Number(process.env.T3_TEST_PORT ?? 0), "127.0.0.1", () => {
+  process.stdout.write(JSON.stringify({
+    pid: process.pid,
+    port: server.address().port,
+    args: process.argv.slice(2),
+  }) + "\\n");
+});
+`,
+          );
+          yield* fs.chmod(cliPath, 0o700);
+          yield* fs.writeFileString(
+            path.join(bin, packageManager),
+            `#!/usr/bin/env node
+const fs = require("node:fs");
+const childProcess = require("node:child_process");
+const args = process.argv.slice(2);
+fs.appendFileSync(process.env.T3_TEST_CALLS, JSON.stringify(args) + "\\n");
+if (args.includes("--package")) {
+  process.stdout.write(process.env.T3_TEST_CLI + "\\n");
+} else {
+  const child = childProcess.spawn(process.execPath, [process.env.T3_TEST_CLI, ...args], { stdio: "inherit" });
+  child.once("exit", (code) => { process.exitCode = code ?? 1; });
+}
+`,
+          );
+          yield* fs.chmod(path.join(bin, packageManager), 0o700);
+
+          const runServer = (port = 0) =>
+            Effect.gen(function* () {
+              const child = yield* spawner.spawn(
+                ChildProcess.make("/bin/sh", ["-s", "--", "serve", "a path with spaces"], {
+                  cwd: fixture,
+                  env: {
+                    PATH: bin,
+                    T3_TEST_CLI: cliPath,
+                    T3_TEST_CALLS: callsPath,
+                    T3_TEST_PORT: String(port),
+                  },
+                  detached: false,
+                  stdin: Stream.make(
+                    new TextEncoder().encode(buildRemoteT3RunnerScript({ packageSpec })),
+                  ),
+                }),
+              );
+              const ready = yield* Deferred.make<typeof Started.Type>();
+              const stdout: string[] = [];
+              const output = yield* child.stdout.pipe(
+                Stream.decodeText(),
+                Stream.splitLines,
+                Stream.runForEach((line) =>
+                  Effect.gen(function* () {
+                    stdout.push(line);
+                    if (stdout.length === 1) {
+                      yield* Deferred.succeed(ready, decodeStarted(line));
+                    }
+                  }),
+                ),
+                Effect.forkScoped,
+              );
+              const stderr = yield* child.stderr.pipe(
+                Stream.decodeText(),
+                Stream.mkString,
+                Effect.forkScoped,
+              );
+              const receipt = yield* Effect.raceFirst(
+                Deferred.await(ready),
+                Fiber.join(output).pipe(
+                  Effect.flatMap(() => Fiber.join(stderr)),
+                  Effect.flatMap((message) =>
+                    Effect.die(new Error(`Runner exited before listening: ${message}`)),
+                  ),
+                ),
+              );
+              // A failed PID assertion must still close the owned fixture server, including an npm child.
+              yield* Effect.addFinalizer(() =>
+                Effect.gen(function* () {
+                  if (yield* child.isRunning) {
+                    yield* Effect.callback<void>((resume) => {
+                      const connection = NodeNet.connect(receipt.port, "127.0.0.1");
+                      connection.on("error", () => undefined);
+                      connection.once("close", () => resume(Effect.void));
+                      return Effect.sync(() => connection.destroy());
+                    });
+                    yield* child.exitCode;
+                  }
+                }).pipe(Effect.orDie),
+              );
+              assert.equal(receipt.pid, child.pid);
+              assert.deepEqual(receipt.args, ["serve", "a path with spaces"]);
+              yield* child.kill({ killSignal: "SIGTERM" });
+              assert.equal(yield* child.exitCode, 0);
+              yield* Fiber.join(output);
+              assert.include(stdout, "graceful shutdown");
+              return receipt.port;
+            }).pipe(Effect.scoped);
+
+          const port = yield* runServer();
+          assert.equal(yield* runServer(port), port);
+          const calls = (yield* fs.readFileString(callsPath))
+            .trim()
+            .split("\n")
+            .map((line) => JSON.parse(line));
+          const expectedCall = [
+            ...(packageManager === "npm" ? ["exec"] : []),
+            "--yes",
+            "--package",
+            packageSpec,
+            "--",
+            "sh",
+            "-c",
+            "command -v t3",
+          ];
+          assert.deepEqual(calls, [expectedCall, expectedCall]);
+        }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+    );
+  },
+);
+
+describe.skipIf(HostProcessPlatform.defaultValue() === "win32")(
+  "remote runner install diagnostics",
+  () => {
+    const decodeArguments = Schema.decodeUnknownSync(
+      Schema.fromJsonString(Schema.Array(Schema.String)),
+    );
+    const cases = (["npx", "npm"] as const).flatMap((packageManager) =>
+      (
+        [
+          "etarget",
+          "network",
+          "empty-success",
+          "success",
+          "failed-with-path",
+          "existing-cli",
+          "node-override",
+        ] as const
+      ).map((mode) => ({ packageManager, mode })),
+    );
+
+    it.live.each(cases)("handles $packageManager/$mode", ({ packageManager, mode }) =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+        const fixture = yield* fs.makeTempDirectoryScoped({ prefix: "t3-runner-install-" });
+        const bin = path.join(fixture, "bin");
+        const cliPath = path.join(fixture, "installed cli.mjs");
+        const callsPath = path.join(fixture, "installer-calls.jsonl");
+        const packageSpec = "t3@0.0.39-nightly.20260905.1286";
+        const args = ["serve", "a path with spaces"];
+        yield* fs.makeDirectory(bin);
+        yield* fs.symlink(process.execPath, path.join(bin, "node"));
+        yield* fs.writeFileString(
+          cliPath,
+          `#!/usr/bin/env node
+process.stdout.write(JSON.stringify(process.argv.slice(2)) + "\\n");
+`,
+        );
+        yield* fs.chmod(cliPath, 0o700);
+        yield* fs.writeFileString(callsPath, "");
+        yield* fs.writeFileString(
+          path.join(bin, packageManager),
+          `#!/usr/bin/env node
+const fs = require("node:fs");
+fs.appendFileSync(process.env.T3_TEST_CALLS, JSON.stringify(process.argv.slice(2)) + "\\n");
+const mode = process.env.T3_TEST_MODE;
+if (mode === "success" || mode === "failed-with-path") {
+  process.stdout.write(process.env.T3_TEST_CLI + "\\n");
+}
+if (mode === "etarget" || mode === "failed-with-path") {
+  process.stderr.write("npm error code ETARGET\\nnpm error notarget No matching version found.\\n");
+  process.exitCode = 42;
+} else if (mode === "network") {
+  process.stderr.write("npm error code ENETUNREACH\\n");
+  process.exitCode = 43;
+}
+`,
+        );
+        yield* fs.chmod(path.join(bin, packageManager), 0o700);
+        if (mode === "existing-cli") yield* fs.symlink(cliPath, path.join(bin, "t3"));
+
+        const child = yield* spawner.spawn(
+          ChildProcess.make("/bin/sh", ["-s", "--", ...args], {
+            cwd: fixture,
+            extendEnv: false,
+            env: {
+              PATH: bin,
+              T3_TEST_MODE: mode,
+              T3_TEST_CLI: cliPath,
+              T3_TEST_CALLS: callsPath,
+            },
+            stdin: Stream.make(
+              new TextEncoder().encode(
+                buildRemoteT3RunnerScript({
+                  packageSpec,
+                  ...(mode === "node-override" ? { nodeScriptPath: cliPath } : {}),
+                }),
+              ),
+            ),
+          }),
+        );
+        const { stdout, stderr, exitCode } = yield* Effect.all(
+          {
+            stdout: child.stdout.pipe(Stream.decodeText(), Stream.mkString),
+            stderr: child.stderr.pipe(Stream.decodeText(), Stream.mkString),
+            exitCode: child.exitCode,
+          },
+          { concurrency: "unbounded" },
+        );
+        const installFailed =
+          mode === "etarget" || mode === "network" || mode === "failed-with-path";
+        const missingExecutable = mode === "empty-success";
+        assert.equal(exitCode, installFailed || missingExecutable ? 1 : 0);
+        if (installFailed || missingExecutable) {
+          assert.equal(stdout, "");
+        } else {
+          assert.deepEqual(decodeArguments(stdout), args);
+        }
+        if (installFailed) {
+          const npmError = mode === "network" ? "ENETUNREACH" : "ETARGET";
+          assert.include(stderr, `npm error code ${npmError}\n`);
+          assert.include(stderr, `Remote host could not install ${packageSpec}.`);
+          assert.notInclude(stderr, "Remote host installed");
+          assert.notInclude(stderr, "Install a C toolchain");
+        } else if (missingExecutable) {
+          assert.include(stderr, `Remote host installed ${packageSpec}`);
+          assert.include(stderr, "npm produced no t3 executable");
+          assert.include(stderr, "Install a C toolchain");
+        } else {
+          assert.equal(stderr, "");
+        }
+        const expectedCall = [
+          ...(packageManager === "npm" ? ["exec"] : []),
+          "--yes",
+          "--package",
+          packageSpec,
+          "--",
+          "sh",
+          "-c",
+          "command -v t3",
+        ];
+        const usesInstaller = mode !== "existing-cli" && mode !== "node-override";
+        const calls = yield* fs.readFileString(callsPath);
+        if (usesInstaller) {
+          assert.deepEqual(
+            calls
+              .trim()
+              .split("\n")
+              .map((line) => decodeArguments(line)),
+            [expectedCall],
+          );
+        } else {
+          assert.equal(calls, "");
+        }
+      }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+    );
+  },
+);
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 392885b640c1..4a49cacc2eb8 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -105,8 +105,7 @@ describe("ssh tunnel scripts", () => {
 
     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, 'exec "$T3_CLI_PATH" "$@"');
     assert.include(script, "could not install 't3@latest'");
     assert.include(script, "require_installed_t3_cli npx --yes --package 't3@latest'");
     assert.include(script, "require_installed_t3_cli npm exec --yes --package 't3@latest'");
@@ -141,8 +140,6 @@ describe("ssh tunnel scripts", () => {
       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.include(
       script,
       "require_installed_t3_cli npx --yes --package 't3@nightly; touch /tmp/t3-owned'",
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 0afd1007f8ed..409fd5c7688c 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -433,20 +433,24 @@ fi
 # never becomes ready. Resolve the CLI once up front so that install failure is
 # reported here, with npm's own output on stderr.
 require_installed_t3_cli() {
-  T3_CLI_PATH="$("$@" -- sh -c 'command -v t3' || true)"
+  if ! T3_CLI_PATH="$("$@" -- sh -c 'command -v t3')"; then
+    printf 'Remote host could not install %s. See npm output above for the cause.\\n' @@T3_PACKAGE_SPEC@@ >&2
+    return 1
+  fi
   if [ -n "$T3_CLI_PATH" ]; then
     return 0
   fi
   printf 'Remote host installed %s but npm produced no t3 executable, which usually means a native dependency (node-pty) failed to build. Install a C toolchain on the remote host (Debian/Ubuntu: build-essential, Fedora/RHEL: gcc-c++ make, macOS: xcode-select --install) and try again.\\n' @@T3_PACKAGE_SPEC@@ >&2
   return 1
 }
+# The launcher records this PID, so exec the CLI without an npm wrapper process.
 if command -v npx >/dev/null 2>&1; then
   require_installed_t3_cli npx --yes --package @@T3_PACKAGE_SPEC@@ || exit 1
-  exec npx --yes @@T3_PACKAGE_SPEC@@ "$@"
+  exec "$T3_CLI_PATH" "$@"
 fi
 if command -v npm >/dev/null 2>&1; then
   require_installed_t3_cli npm exec --yes --package @@T3_PACKAGE_SPEC@@ || exit 1
-  exec npm exec --yes @@T3_PACKAGE_SPEC@@ -- "$@"
+  exec "$T3_CLI_PATH" "$@"
 fi
 printf 'Remote host is missing the t3 CLI and could not install @@T3_PACKAGE_SPEC@@ because node/npm/npx are unavailable on PATH. Install Node or configure a supported version manager for non-interactive shells.\\n' >&2
 exit 1
diff --git a/packages/tailscale/src/tailscale.test.ts b/packages/tailscale/src/tailscale.test.ts
index 09d9def21066..102153f6e204 100644
--- a/packages/tailscale/src/tailscale.test.ts
+++ b/packages/tailscale/src/tailscale.test.ts
@@ -8,6 +8,7 @@ import * as Sink from "effect/Sink";
 import * as Stream from "effect/Stream";
 import * as TestClock from "effect/testing/TestClock";
 import { ChildProcessSpawner } from "effect/unstable/process";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 
 import {
   buildTailscaleHttpsBaseUrl,
@@ -98,14 +99,22 @@ function neverFinishingMockHandle() {
   });
 }
 
+// The executable name depends on the host platform (`tailscale.exe` on
+// Windows), so pin it: these tests assert the posix spelling.
+function spawnerLayer(spawner: ChildProcessSpawner.ChildProcessSpawner["Service"]) {
+  return Layer.merge(
+    Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner),
+    Layer.succeed(HostProcessPlatform, "linux"),
+  );
+}
+
 function mockSpawnerLayer(
   handler: (
     command: string,
     args: ReadonlyArray<string>,
   ) => { stdout?: string; stderr?: string; code?: number },
 ) {
-  return Layer.succeed(
-    ChildProcessSpawner.ChildProcessSpawner,
+  return spawnerLayer(
     ChildProcessSpawner.make((command) => {
       const childProcess = command as unknown as {
         readonly command: string;
@@ -194,10 +203,7 @@ describe("tailscale", () => {
       method: "spawn",
       cause: systemCause,
     });
-    const layer = Layer.succeed(
-      ChildProcessSpawner.ChildProcessSpawner,
-      ChildProcessSpawner.make(() => Effect.fail(cause)),
-    );
+    const layer = spawnerLayer(ChildProcessSpawner.make(() => Effect.fail(cause)));
 
     return Effect.gen(function* () {
       const error = yield* readTailscaleStatus.pipe(Effect.flip, Effect.provide(layer));
@@ -218,8 +224,7 @@ describe("tailscale", () => {
     // inside an `Effect.callback` registration, so that throw arrives as a
     // defect rather than a typed error - the shape reproduced here.
     const defect = Object.assign(new Error("spawn tailscale ENOTDIR"), { code: "ENOTDIR" });
-    const layer = Layer.succeed(
-      ChildProcessSpawner.ChildProcessSpawner,
+    const layer = spawnerLayer(
       ChildProcessSpawner.make(() =>
         Effect.callback<never, never>(() => {
           throw defect;
@@ -297,10 +302,7 @@ describe("tailscale", () => {
   it.effect("times out tailscale status through TestClock", () => {
     const layer = Layer.merge(
       TestClock.layer(),
-      Layer.succeed(
-        ChildProcessSpawner.ChildProcessSpawner,
-        ChildProcessSpawner.make(() => Effect.succeed(neverFinishingMockHandle())),
-      ),
+      spawnerLayer(ChildProcessSpawner.make(() => Effect.succeed(neverFinishingMockHandle()))),
     );
 
     return Effect.gen(function* () {
diff --git a/packages/tailscale/src/tailscale.ts b/packages/tailscale/src/tailscale.ts
index d6db5e8bcc59..7f1cf41661fb 100644
--- a/packages/tailscale/src/tailscale.ts
+++ b/packages/tailscale/src/tailscale.ts
@@ -9,8 +9,8 @@ import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
 export const DEFAULT_TAILSCALE_SERVE_PORT = 443;
 export const TAILSCALE_STATUS_TIMEOUT = Duration.millis(1_500);
-export const TAILSCALE_SERVE_TIMEOUT = Duration.seconds(10);
-export const TAILSCALE_PROBE_TIMEOUT = Duration.millis(2_500);
+const TAILSCALE_SERVE_TIMEOUT = Duration.seconds(10);
+const TAILSCALE_PROBE_TIMEOUT = Duration.millis(2_500);
 
 // tailscale is a real executable everywhere (`tailscale.exe` on Windows), so
 // it is always spawned directly rather than through cmd.exe shell mode.
@@ -47,7 +47,7 @@ const STDERR_DIAGNOSTIC_PATTERNS: ReadonlyArray<
 ];
 
 /** Classifies stderr into a safe label, dropping the text itself. */
-export const stderrDiagnosticOf = (stderr: string): TailscaleStderrDiagnostic | undefined => {
+const stderrDiagnosticOf = (stderr: string): TailscaleStderrDiagnostic | undefined => {
   if (stderr.trim().length === 0) {
     return undefined;
   }
@@ -66,7 +66,7 @@ export class TailscaleCommandSpawnError extends Schema.TaggedErrorClass<Tailscal
   }
 }
 
-export class TailscaleCommandOutputError extends Schema.TaggedErrorClass<TailscaleCommandOutputError>()(
+class TailscaleCommandOutputError extends Schema.TaggedErrorClass<TailscaleCommandOutputError>()(
   "TailscaleCommandOutputError",
   {
     ...TailscaleCommandContext,
@@ -137,7 +137,6 @@ const TailscaleStatusJson = Schema.Struct({
   Self: Schema.optional(TailscaleStatusSelf),
 });
 
-export type TailscaleStatusSelf = typeof TailscaleStatusSelf.Type;
 export type TailscaleStatusJson = typeof TailscaleStatusJson.Type;
 
 export interface TailscaleStatus {
diff --git a/patches/@pierre%2Fdiffs@1.3.0-beta.10.patch b/patches/@pierre%2Fdiffs@1.3.0-beta.10.patch
index b342d4b5dd13..5cf80feb3356 100644
--- a/patches/@pierre%2Fdiffs@1.3.0-beta.10.patch
+++ b/patches/@pierre%2Fdiffs@1.3.0-beta.10.patch
@@ -1,3 +1,79 @@
+diff --git a/dist/components/VirtualizedFile.d.ts b/dist/components/VirtualizedFile.d.ts
+--- a/dist/components/VirtualizedFile.d.ts
++++ b/dist/components/VirtualizedFile.d.ts
+@@ -42,7 +42,7 @@ declare class VirtualizedFile<LAnnotation = undefined> extends File<LAnnotation> {
+   private computeApproximateSize;
+   setVisibility(visible: boolean): void;
+   rerender(): void;
+-  applyDocumentChange(textDocument: DiffsTextDocument, newLineAnnotations?: LineAnnotation<LAnnotation>[], shouldUpdateBuffer?: boolean): void;
++  applyDocumentChange(textDocument: DiffsTextDocument, newLineAnnotations?: LineAnnotation<LAnnotation>[], shouldUpdateBuffer?: boolean, startLine?: number): void;
+   protected renderPreparedFile({
+     fileContainer,
+     file,
+diff --git a/dist/components/VirtualizedFile.js b/dist/components/VirtualizedFile.js
+--- a/dist/components/VirtualizedFile.js
++++ b/dist/components/VirtualizedFile.js
+@@ -20,6 +20,7 @@
+ 	cache = {
+ 		heights: /* @__PURE__ */ new Map(),
+ 		checkpoints: [],
++		codeWidth: void 0,
+ 		fileAnnotationHeight: 0
+ 	};
+ 	isVisible = false;
+@@ -31,6 +32,8 @@
+ 		super(options, workerManager, isContainerManaged);
+ 		this.virtualizer = virtualizer;
+ 		this.metrics = metrics;
++		const simpleVirtualizer = this.getSimpleVirtualizer();
++		if (simpleVirtualizer != null) this.resizeManager.onResize = () => simpleVirtualizer.requestHeightReconcile(this);
+ 	}
+ 	setMetrics(metrics, force = false) {
+ 		if (!force && areObjectsEqual(this.metrics, metrics)) return;
+@@ -70,10 +73,12 @@
+ 		if (this.isAdvancedMode()) throw new Error("VirtualizedFile.setThemeType cannot be used inside CodeView. Update CodeView options instead.");
+ 		super.setThemeType(themeType);
+ 	}
+-	resetLayoutCache(recompute = false, resetRenderRange = true) {
++	resetLayoutCache(recompute = false, resetRenderRange = true, startLine = 0) {
+ 		this.layoutDirty = true;
+-		this.cache.fileAnnotationHeight = 0;
+-		if (this.cache.heights.size > 0) this.cache.heights.clear();
++		if (startLine === 0) this.cache.fileAnnotationHeight = 0;
++		// Dropping unchanged wrapped rows moves the viewport before they can be remeasured.
++		if (startLine === 0) this.cache.heights.clear();
++		else for (const lineIndex of this.cache.heights.keys()) if (lineIndex >= startLine) this.cache.heights.delete(lineIndex);
+ 		if (this.cache.checkpoints.length > 0) this.cache.checkpoints.length = 0;
+ 		if (this.renderRange != null && resetRenderRange) this.renderRange = void 0;
+ 		if (recompute && this.isSimpleMode()) this.computeApproximateSize();
+@@ -91,6 +96,13 @@
+ 		if (this.code == null) return hasHeightChange;
+ 		const content = this.code.children[1];
+ 		if (!(content instanceof HTMLElement)) return hasHeightChange;
++		const codeWidth = this.code.getBoundingClientRect().width;
++		if (!(codeWidth > 0)) return hasHeightChange;
++		if (this.cache.codeWidth != null && this.cache.codeWidth !== codeWidth) {
++			this.resetLayoutCache(false, false);
++			hasHeightChange = true;
++		}
++		this.cache.codeWidth = codeWidth;
+ 		const hasFileAnnotations = includesFileAnnotations(this.lineAnnotations);
+ 		if (this.renderRange != null && hasFileAnnotations && shouldRenderFileAnnotations(this.renderRange)) {
+ 			const nextFileAnnotationHeight = measureFileAnnotationHeight(content) ?? 0;
+@@ -287,11 +299,11 @@
+ 		this.forceRenderOverride = true;
+ 		this.virtualizer.instanceChanged(this, false);
+ 	}
+-	applyDocumentChange(textDocument, newLineAnnotations, shouldUpdateBuffer = false) {
++	applyDocumentChange(textDocument, newLineAnnotations, shouldUpdateBuffer = false, startLine = 0) {
+ 		const previousRenderRange = this.renderRange;
+ 		super.applyDocumentChange(textDocument, newLineAnnotations);
+ 		this.getSimpleVirtualizer()?.markDOMDirty();
+-		this.resetLayoutCache(this.isSimpleMode(), false);
++		this.resetLayoutCache(this.isSimpleMode(), false, startLine);
+ 		if (shouldUpdateBuffer && previousRenderRange !== void 0 && this.file !== void 0) {
+ 			const windowSpecs = this.virtualizer.getWindowSpecs();
+ 			const renderRange = this.computeRenderRangeFromWindow(this.file, this.top ?? 0, windowSpecs);
 diff --git a/dist/editor/editor.js b/dist/editor/editor.js
 index ff78e2a..f9df318 100644
 --- a/dist/editor/editor.js
@@ -28,12 +104,18 @@ index ff78e2a..f9df318 100644
  				const gutterRow = resolveGutterTarget(e.composedPath()[0]);
  				if (gutterRow?.dataset.lineType === "change-deletion") {
  					const code = gutterRow.closest("[data-code]");
-@@ -1522,6 +1520,7 @@ var Editor = class {
+@@ -1522,6 +1520,12 @@ var Editor = class {
  			if (gutterEl !== void 0) gutterEl.style.gridRow = "span " + gridRow;
  		}
  		fileInstance.updateRenderCache(dirtyLines, tokenizer.themeType, !didLineCountChange, didLineCountChange);
 +		if (fileInstance.file !== void 0) fileInstance.file.contents = textDocument.getText();
- 		if (didLineCountChange) fileInstance.applyDocumentChange(textDocument, newLineAnnotations, shouldUpdateBuffer);
+-		if (didLineCountChange) fileInstance.applyDocumentChange(textDocument, newLineAnnotations, shouldUpdateBuffer);
++		if (didLineCountChange) {
++			const previousLineCount = change.lineCount - change.lineDelta;
++			// A wider or narrower line-number gutter can rewrap unchanged rows.
++			const layoutStartLine = String(previousLineCount).length === String(change.lineCount).length ? change.startLine : 0;
++			fileInstance.applyDocumentChange(textDocument, newLineAnnotations, shouldUpdateBuffer, layoutStartLine);
++		}
  		if (this.#isDiff && (this.#diffSyle === "unified" || didLineCountChange)) this.#resetCache();
  		if (newLineAnnotations !== void 0) {
 @@ -1788,6 +1787,7 @@ var Editor = class {
@@ -44,6 +126,37 @@ index ff78e2a..f9df318 100644
  		try {
  			this.#fileInstance?.setSelectedLines(range, {
  				notify: false,
+diff --git a/dist/managers/ResizeManager.d.ts b/dist/managers/ResizeManager.d.ts
+--- a/dist/managers/ResizeManager.d.ts
++++ b/dist/managers/ResizeManager.d.ts
+@@ -5,6 +5,8 @@
+   columnVariables?: ResizeManagerColumnVariableMode;
+ }
+ declare class ResizeManager {
++  /** Schedule owner measurement after an observed code or gutter size change. */
++  onResize?: () => void;
+   private static resizeObserver;
+   private static managersByElement;
+   private static getResizeObserver;
+diff --git a/dist/managers/ResizeManager.js b/dist/managers/ResizeManager.js
+--- a/dist/managers/ResizeManager.js
++++ b/dist/managers/ResizeManager.js
+@@ -19,6 +19,7 @@
+ 		for (const [manager, managerEntries] of entriesByManager) manager.handleResizeEntries(managerEntries);
+ 	}
+ 	observedNodes = /* @__PURE__ */ new Map();
++	onResize;
+ 	setup(pre, { disableAnnotations, columnVariables = "apply" }) {
+ 		const annotationUpdates = /* @__PURE__ */ new Set();
+ 		const applyColumnVariables = columnVariables === "apply";
+@@ -212,6 +213,7 @@
+ 		this.applyAnnotationUpdates(annotationUpdates);
+ 		annotationUpdates.clear();
+ 		this.applyColumnUpdates(codeUpdates);
++		if (codeUpdates.size > 0) this.onResize?.();
+ 		codeUpdates.clear();
+ 	}
+ 	applyAnnotationUpdates(annotationUpdates) {
 diff --git a/dist/react/utils/useFileInstance.js b/dist/react/utils/useFileInstance.js
 index e9f62f5..af82a46 100644
 --- a/dist/react/utils/useFileInstance.js
@@ -60,6 +173,46 @@ index e9f62f5..af82a46 100644
  	};
  	return merged;
  }
+diff --git a/dist/renderers/FileRenderer.js b/dist/renderers/FileRenderer.js
+--- a/dist/renderers/FileRenderer.js
++++ b/dist/renderers/FileRenderer.js
+@@ -107,10 +107,10 @@
+ 			result: massiveFile ? void 0 : cache?.result,
+ 			renderRange: void 0
+ 		};
++		this.computedLang = file.lang ?? getFiletypeFromFileName(file.name);
+ 		if (this.workerManager?.isWorkingPool() === true) {
+ 			if (this.renderCache.result == null && !massiveFile) this.workerManager.highlightFileAST(this, file);
+ 		} else if (this.highlighter == null) {
+-			this.computedLang = file.lang ?? getFiletypeFromFileName(file.name);
+ 			this.initializeHighlighter();
+ 		}
+ 	}
+@@ -163,6 +163,8 @@
+ 		if (this.renderCache == null) return;
+ 		const { file, result } = this.renderCache;
+ 		if (result == null) return;
++		this.workerManager?.cleanUpTasks(this);
++		if (file.cacheKey != null) this.workerManager?.evictFileFromCache(file.cacheKey);
+ 		const lineCache = this.lineCache != null && isLineCacheForFile(this.lineCache, file) ? this.lineCache : void 0;
+ 		for (const [line, tokens] of dirtyLines) {
+ 			if (lineCache != null && line < lineCache.lines.length) {
+@@ -268,6 +270,7 @@
+ 		const forcePlainText = !hasContent || isFilePlainText(file) || isFileMassive(lines.length, this.getTokenizeMaxLength());
+ 		const newContent = !areFilesEqual(file, this.renderCache.file);
+ 		const newRenderRange = !areRenderRangesEqual(this.renderCache.renderRange, renderRange);
++		this.computedLang = file.lang ?? getFiletypeFromFileName(file.name);
+ 		if (this.workerManager?.isWorkingPool() === true) {
+ 			if (forcePlainText || this.renderCache.result == null || !this.renderCache.highlighted && (newContent || newRenderRange)) {
+ 				this.renderCache.file = file;
+@@ -278,7 +281,6 @@
+ 			}
+ 			if (!forcePlainText && hasContent && (!this.renderCache.highlighted || forceHighlight)) this.workerManager.highlightFileAST(this, file);
+ 		} else {
+-			this.computedLang = file.lang ?? getFiletypeFromFileName(file.name);
+ 			const hasThemes = this.highlighter != null && areThemesAttached(options.theme);
+ 			const hasLangs = this.highlighter != null && areLanguagesAttached(this.computedLang);
+ 			const canHighlight = !forcePlainText && hasLangs;
 diff --git a/package.json b/package.json
 index ff61c90..1e170e5 100644
 --- a/package.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2a7e45ca8575..bd6ed98740aa 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -92,7 +92,7 @@ patchedDependencies:
   '@expo/metro-config@57.0.12': 96f1a75347e6ea02dc4b7034ace815d8ee39e18b8166ebfb573d9e58328f0dc2
   '@ff-labs/fff-node@0.9.4': ab9ff544009e1891cfe3930105862d3699007f38922a79f3c98d90018deca368
   '@legendapp/list@3.3.5': 03ec41339cd915ecb9a774a6b90cc2197c29038f7db67c4d2e55cd3971e5be43
-  '@pierre/diffs@1.3.0-beta.10': 7ef7cb0cbabb17c15cdb137554068b36f15f6f5265e73fb51452aa3380db91aa
+  '@pierre/diffs@1.3.0-beta.10': 0ccee155b93b63d810e2c1a40c1fd676fb6fbcfa72cf6430dcedf1a3ae475ab4
   '@react-native-ai/apple@0.12.0': 2d09870c2848d185cb05b53ed823a46e12dba519324d8dd8e584e28731990f9d
   '@react-native-menu/menu@2.0.0': f63d256bf6a97a873b5e628eb595bd6ef0075ddd5bdd890fc920f7a6024290dd
   '@react-navigation/native-stack@7.17.6': e667c3cef8c78bb9ff4882ee5bd23a432247b843060a9499eb5f07e9e2295552
@@ -109,21 +109,18 @@ importers:
 
   .:
     devDependencies:
-      '@babel/plugin-transform-react-jsx':
-        specifier: 7.28.6
-        version: 7.28.6(@babel/core@7.29.7)
       '@effect/tsgo':
         specifier: 'catalog:'
         version: 0.13.2
-      '@oxlint/plugins':
-        specifier: ^1.63.0
-        version: 1.68.0
       '@types/node':
         specifier: 24.12.4
         version: 24.12.4
       '@typescript/native-preview':
         specifier: 'catalog:'
         version: 7.0.0-dev.20260604.1
+      knip:
+        specifier: 6.34.0
+        version: 6.34.0
       vite-plus:
         specifier: 'catalog:'
         version: 0.3.0(@types/node@24.12.4)(bufferutil@4.1.0)(esbuild@0.28.1)(jiti@2.7.0)(msw@2.12.11(@types/node@24.12.4)(typescript@6.0.3))(terser@5.48.0)(typescript@6.0.3)(unrun@0.2.39)(utf-8-validate@6.0.6)(yaml@2.9.0)
@@ -206,6 +203,9 @@ importers:
       astro:
         specifier: ^7.0.3
         version: 7.0.3(@astrojs/markdown-remark@7.2.0)(@emnapi/core@1.11.1)(@emnapi/runtime@1.11.1)(@types/node@24.12.4)(aws4fetch@1.0.20)(idb-keyval@6.2.1)(ioredis@5.11.0)(jiti@2.7.0)(rollup@4.61.0)(terser@5.48.0)(typescript@6.0.3)(unrun@0.2.39)(yaml@2.9.0)
+      sharp:
+        specifier: 0.34.5
+        version: 0.34.5
     devDependencies:
       '@astrojs/check':
         specifier: ^0.9.7
@@ -242,7 +242,7 @@ importers:
         version: 1.9.1
       '@pierre/diffs':
         specifier: 'catalog:'
-        version: 1.3.0-beta.10(patch_hash=7ef7cb0cbabb17c15cdb137554068b36f15f6f5265e73fb51452aa3380db91aa)(@shikijs/themes@4.2.0)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+        version: 1.3.0-beta.10(patch_hash=0ccee155b93b63d810e2c1a40c1fd676fb6fbcfa72cf6430dcedf1a3ae475ab4)(@shikijs/themes@4.2.0)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@react-native-ai/apple':
         specifier: 0.12.0
         version: 0.12.0(patch_hash=2d09870c2848d185cb05b53ed823a46e12dba519324d8dd8e584e28731990f9d)(react-native@0.86.3(@babel/core@7.29.7)(@react-native/metro-config@0.86.3(@babel/core@7.29.7)(bufferutil@4.1.0)(utf-8-validate@6.0.6))(@types/react@19.2.16)(bufferutil@4.1.0)(react@19.2.3)(utf-8-validate@6.0.6))
@@ -476,8 +476,8 @@ importers:
   apps/server:
     dependencies:
       '@anthropic-ai/claude-agent-sdk':
-        specifier: ^0.3.170
-        version: 0.3.170(@anthropic-ai/sdk@0.93.0(zod@4.4.3))(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(zod@4.4.3)
+        specifier: ^0.3.260
+        version: 0.3.260(@anthropic-ai/sdk@0.93.0(zod@4.4.3))(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(zod@4.4.3)
       '@effect/platform-bun':
         specifier: 4.0.0-beta.103
         version: 4.0.0-beta.103(bufferutil@4.1.0)(effect@4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6))(utf-8-validate@6.0.6)
@@ -493,9 +493,6 @@ importers:
       '@opencode-ai/sdk':
         specifier: ^1.3.15
         version: 1.15.13
-      '@pierre/diffs':
-        specifier: 'catalog:'
-        version: 1.3.0-beta.10(patch_hash=7ef7cb0cbabb17c15cdb137554068b36f15f6f5265e73fb51452aa3380db91aa)(@shikijs/themes@4.3.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       effect:
         specifier: 4.0.0-beta.103
         version: 4.0.0-beta.103(patch_hash=af36b7948b6f9c56623074662b51dade5699880c1a7c71245de73e13c3185fb6)
@@ -586,7 +583,7 @@ importers:
         version: 1.8.0
       '@pierre/diffs':
         specifier: 'catalog:'
-        version: 1.3.0-beta.10(patch_hash=7ef7cb0cbabb17c15cdb137554068b36f15f6f5265e73fb51452aa3380db91aa)(@shikijs/themes@4.3.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        version: 1.3.0-beta.10(patch_hash=0ccee155b93b63d810e2c1a40c1fd676fb6fbcfa72cf6430dcedf1a3ae475ab4)(@shikijs/themes@4.3.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@pierre/trees':
         specifier: 1.0.0-beta.4
         version: 1.0.0-beta.4(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -690,6 +687,9 @@ importers:
       '@types/react-dom':
         specifier: ~19.2.3
         version: 19.2.3(@types/react@19.2.16)
+      '@types/react-test-renderer':
+        specifier: 19.1.0
+        version: 19.1.0
       '@vercel/config':
         specifier: ^0.3.0
         version: 0.3.0
@@ -702,6 +702,9 @@ importers:
       compression:
         specifier: ^1.8.1
         version: 1.8.1
+      react-test-renderer:
+        specifier: 19.2.6
+        version: 19.2.6(react@19.2.6)
       tailwindcss:
         specifier: 4.3.3
         version: 4.3.3
@@ -1011,8 +1014,8 @@ packages:
   '@alchemy.run/node-utils@0.0.5':
     resolution: {integrity: sha512-5agdhQxWBodxa5hDRyjnpx91RTU3g+qd5fxYB7uNDCaOzB0XC47UU/KHR6zf6jhz/NXf61gJS+vhYwn8NHeRoQ==}
 
-  '@anthropic-ai/claude-agent-sdk@0.3.170':
-    resolution: {integrity: sha512-pAvhfk+iTodXZ6RF18Kz7BEUWFjL7EcR3tKuhUNdPpE1NAYCR3mSHGbafi72JsrNwKEDIs7FU31z3fqhwy8QzA==}
+  '@anthropic-ai/claude-agent-sdk@0.3.260':
+    resolution: {integrity: sha512-PmABtP4Rwd6l95itQrqzguv6rS9uACqikPB9g8BPeWRKZOpy3xpEOjJLYauof3BFk2wNZnfhr0Ttx8ttcZzq0w==}
     engines: {node: '>=18.0.0'}
     peerDependencies:
       '@anthropic-ai/sdk': '>=0.93.0'
@@ -2137,12 +2140,18 @@ packages:
   '@emnapi/core@1.11.1':
     resolution: {integrity: sha512-RSvbQmHzdKzNsLYa/wHrbc3KN4sYLKAdPZxqiM2HATqv/SBk2/ENSHpvXGaLOMcsAyz0poEGqkmmKYG3OWiJEQ==}
 
+  '@emnapi/core@1.11.2':
+    resolution: {integrity: sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA==}
+
   '@emnapi/runtime@1.10.0':
     resolution: {integrity: sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==}
 
   '@emnapi/runtime@1.11.1':
     resolution: {integrity: sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw==}
 
+  '@emnapi/runtime@1.11.2':
+    resolution: {integrity: sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==}
+
   '@emnapi/wasi-threads@1.2.1':
     resolution: {integrity: sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==}
 
@@ -3379,6 +3388,128 @@ packages:
   '@oslojs/encoding@1.1.0':
     resolution: {integrity: sha512-70wQhgYmndg4GCPxPPxPGevRKqTIJ2Nh4OkiMWmDAVYsTQ+Ta7Sq+rPevXyXGdzr30/qZBnyOalCszoMxlyldQ==}
 
+  '@oxc-parser/binding-android-arm-eabi@0.147.0':
+    resolution: {integrity: sha512-fOtoGvIoirkvxQVw9J1WJPxz571XPgLsPf9uhRD+PJteUnvrJHMDmK9pw2yZEGGyismtRoEsp+JcXUdF/JDMDw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [android]
+
+  '@oxc-parser/binding-android-arm64@0.147.0':
+    resolution: {integrity: sha512-emjQHOYJaomo4ykaXQ1EItunr/I94Nk01oqBmU4dSkKSTupIDx6OysVDf2e8Eytm77rb+4ZxzgElyWP7rcEX7A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [android]
+
+  '@oxc-parser/binding-darwin-arm64@0.147.0':
+    resolution: {integrity: sha512-kXvBPJL7RmDPJ2mze/vXPPVQimCDtFr9OFLjf7dyhV5Dx64cgcXh9KKrA1sMWvCObvJll9CZZUO0FBlFwD0l6A==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@oxc-parser/binding-darwin-x64@0.147.0':
+    resolution: {integrity: sha512-mgFF8pLU6R64LbT27lSrtVRspVC/3IcZ0qyIikzmi78Y3Ik2OPnlAHHI0UEBRcC3qmNgtjaef7zkFt7/uPxIcw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [darwin]
+
+  '@oxc-parser/binding-freebsd-x64@0.147.0':
+    resolution: {integrity: sha512-v38aiF11qufOTBcCAKL4skgQf0zJ4NEvRlivq7B5kHrlyvjCLjvNrMtNWDTz1SDUL6/xVsJRmLDxv2e+Cp4oWw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@oxc-parser/binding-linux-arm-gnueabihf@0.147.0':
+    resolution: {integrity: sha512-AeIiBbwUaP0H1+4/qGW9l5qHecS/+XA5iMuieVcGb1T+tyc2dVGspFW13BWk/XrLsiGP/CiDJTJqAPLLCzZHkw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-arm-musleabihf@0.147.0':
+    resolution: {integrity: sha512-/41MKPW4RgPY4DJco0NCF0RYX3IMZaVlRNMNzvhaxRavc7tN3Txm+qllZbh0aMRs0VHdgUlbI8TcAOiTai4TKg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxc-parser/binding-linux-arm64-gnu@0.147.0':
+    resolution: {integrity: sha512-bmpw/RPhVXgZbtb3xBDuwW5s8+LvZYdqcDSX/sP2ltL77aTio3DP/B5ZTwwgoJ6Mr9vJs4RrmgEKW9XkLNUU1g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-parser/binding-linux-arm64-musl@0.147.0':
+    resolution: {integrity: sha512-gd7VX/FDVOw6mjQcu45iIcp4QkgybgJwh3a0OFG2NxmPCj628mQWD96QGu1kK8+mZF9qK4b/gIEyC63vQoB7+Q==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxc-parser/binding-linux-ppc64-gnu@0.147.0':
+    resolution: {integrity: sha512-HnAzcfki7dSUNHf510Q2NmbJlz8Ys7rn8l9l588Pkx0tYe1BHLZnmELIgqizJ4WPhHGSwN8Ce+B/menVxS3odA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-parser/binding-linux-riscv64-gnu@0.147.0':
+    resolution: {integrity: sha512-qlkOL6wT44U+fT5s/+sR6Shx0OdwvQF83JyIPZUxG/ovqZF5/7atOtjH+JPZ5/7ATQLbFBBSmghcy/+2NVB/ew==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-parser/binding-linux-riscv64-musl@0.147.0':
+    resolution: {integrity: sha512-DlefD7L7sMXs/3hIBH23Egk0phj8kG0SA81dVGOQ3S1ekjOlmTLH2E+F2Thwfh1slKx6aH+lNc5fQYAw0GU7/g==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxc-parser/binding-linux-s390x-gnu@0.147.0':
+    resolution: {integrity: sha512-Xqpagk/031IvZ4svrk2FF01YEqM/iN3MJV3SVZadKg/CsGlDCGoREqKHXYnoV5+8SfGe/m6RM1szXFLusTu/Uw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-parser/binding-linux-x64-gnu@0.147.0':
+    resolution: {integrity: sha512-QioQOeUbI4ATUr0S2z88uA3Cds2R3Mm5Ge7U8XNYtlTb2GJF3rWlcj70z0AJhhOlbdm0YgVjqPBldUNbFylDIg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-parser/binding-linux-x64-musl@0.147.0':
+    resolution: {integrity: sha512-NXy1tv/OdC+pPTwf9RiCZWPK53V/Xq/2cjSnjOSyKopajdaDqMIkgtDY+jXZemp2e8px5FeWfY2L2LwhKZQovg==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxc-parser/binding-openharmony-arm64@0.147.0':
+    resolution: {integrity: sha512-GpGWZ6oKz4bjCWW9Mz5pCaGPyk2Aaze6zEoaslIQqpSLtpx5pXj/ap5gUNb5Jn2LIbqWyjkGLX9yv3NMuNcBVQ==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@oxc-parser/binding-win32-arm64-msvc@0.147.0':
+    resolution: {integrity: sha512-a8mlt7CC8z7LUdCfaxhff4kCd+vSjE+NEFL0cxA8ukfuSnvAto/pWTjytW4BuVLnQGcCVdHJwcRKOfs++H+tjw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [arm64]
+    os: [win32]
+
+  '@oxc-parser/binding-win32-ia32-msvc@0.147.0':
+    resolution: {integrity: sha512-M5ViVDBcFLnl2632AuuWuP35zEL5oikK1jTx8r3+902VEDeSNHxFZAB6RZyfZ7MU6Oi5QTOG8MmMkIeHsudSaw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [ia32]
+    os: [win32]
+
+  '@oxc-parser/binding-win32-x64-msvc@0.147.0':
+    resolution: {integrity: sha512-DUaE13OwnUSlHpLZNcC/nuT10ivlWqc5EZgsfgXuAmWYw0r3nDxGeLD1zlGwYwIgVk1/ZMAxoXpV+05stvbHaA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    cpu: [x64]
+    os: [win32]
+
   '@oxc-project/runtime@0.146.0':
     resolution: {integrity: sha512-lbXHIpZ1MmK6zuw5txlMdIZ2waLVUIU5Gnm3sEuwJOiqDfQfbtjeHscatmeBoxbv8+If9LFM6PGh/3DcDWYIYw==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -3392,6 +3523,112 @@ packages:
   '@oxc-project/types@0.146.0':
     resolution: {integrity: sha512-XC0QsnnhVe7sLIWmYmdPw7x5P0h4W8vUU3Nv1ySgWXtvCz8NizoAEpGXA0sOYoJQV2Rl13LgURAHQ5cI5ILCSA==}
 
+  '@oxc-project/types@0.147.0':
+    resolution: {integrity: sha512-IJ3s6ltHLp45S0bh7phkX+gJO7A1Wuz2EaqpAhb8WjqDwbzMiWKHhyyT42tskaWjEYXtHtVCPpnBJVT9+dcRLg==}
+
+  '@oxc-resolver/binding-android-arm-eabi@11.24.2':
+    resolution: {integrity: sha512-y09e0L0SRI2OA2tUIrjBgoV3eH5hvUKXNkJqXmNo5V2WxIjyC7I7aJfRLMEVpA8yi95f90gFDvO0VMgrDw+vwA==}
+    cpu: [arm]
+    os: [android]
+
+  '@oxc-resolver/binding-android-arm64@11.24.2':
+    resolution: {integrity: sha512-cl4icWaZFnLdg8m6qtnh5rBMuGbxc/ptStFHLeCNwr+2cZjkjNwQu/jYRS0CHlnPecOJMpuS5M6/BH+0J/YkEg==}
+    cpu: [arm64]
+    os: [android]
+
+  '@oxc-resolver/binding-darwin-arm64@11.24.2':
+    resolution: {integrity: sha512-At29QEMF6HajbQvgY8K6OXnHD1x9rad74xBEfmCB6ZqCGsdq75aK7tOYcTbOanMy8qdIBrfL3SMr3p/lfSlb9w==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@oxc-resolver/binding-darwin-x64@11.24.2':
+    resolution: {integrity: sha512-A5Kqr1EUj4oIL5CF4WRssq/o5P0Y11cwoFouMRmQ7YnC/A8V93nv1nb7aSU8HwcgmXropjLNkVTl4MN87cu28Q==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@oxc-resolver/binding-freebsd-x64@11.24.2':
+    resolution: {integrity: sha512-R5xkRBRRz7ceH/P5Jrc6G7FmdUdgpLYyESFAUDVTNQ9K0sGPxcp4ljiwEwEqsvNcQ4sYbMRrWcHHBCu7ksAJVw==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@oxc-resolver/binding-linux-arm-gnueabihf@11.24.2':
+    resolution: {integrity: sha512-k/RuYL4L/R58IBn3wT5ma3Wh4k62bp1eYCFRWCmMsasUOqL+H6sW0VGFadEzKWXFFlz+2uIMoeMk9ySSZJHgbg==}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxc-resolver/binding-linux-arm-musleabihf@11.24.2':
+    resolution: {integrity: sha512-bnHAak3ujYfH5pKk4NieFNbvYvernfoQDgwLddbZ3OtMYrem87/qjlA+u+aKG0oZcqSLGCful/6/CEA+aeAgaA==}
+    cpu: [arm]
+    os: [linux]
+
+  '@oxc-resolver/binding-linux-arm64-gnu@11.24.2':
+    resolution: {integrity: sha512-vDT3KHgzYp47gmtNOqL2VNhCyl5Zv643eyxm//A68J8DeUGXrvD1pZFiaT4jSfe+RInfnn1R2yVHye4enx6RnA==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-resolver/binding-linux-arm64-musl@11.24.2':
+    resolution: {integrity: sha512-+kMlQvbzfyEYtu5FcjE4p+ttBLpKW4d/AsAsuE69BxV6V4twZJeIQZFfD8gh/wqglY0MkPSezWXQH0jBV13MUw==}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxc-resolver/binding-linux-ppc64-gnu@11.24.2':
+    resolution: {integrity: sha512-shjfMhmZ3gq9fv/w7bi3PnZlgOPG+2QAOFf0BJF0EgBSIGZ6PMLN2zbGEblTUYB/NKVDRyYhE2ff3dJ1QqNPkA==}
+    cpu: [ppc64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-resolver/binding-linux-riscv64-gnu@11.24.2':
+    resolution: {integrity: sha512-zGelwFR5oRo+b69k8Lrzun86DyUHzfKN6cnjbR9l7Z7NIRznOE/2ZvPa1IUKqAL2PzAXOdwkfVqNvO1H2RlpAw==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-resolver/binding-linux-riscv64-musl@11.24.2':
+    resolution: {integrity: sha512-qxZ1SWCXJY0eyhAlP6Lmo9F2Nrtx7EkYj9oCgL8apDPCwXwCEDA2U697bbT81JIc2IrVjxO4KX6WU2N+oN9Z4w==}
+    cpu: [riscv64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxc-resolver/binding-linux-s390x-gnu@11.24.2':
+    resolution: {integrity: sha512-sGCecF3cx2DFlH4t/z7ApnOnXqN48p5p5mlHDEnHTAukQa2P+qMVE4CwyWE9W+q/m3QJ7kKfGrIjax31f44oFQ==}
+    cpu: [s390x]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-resolver/binding-linux-x64-gnu@11.24.2':
+    resolution: {integrity: sha512-k/VlMMcSzMlahb3/fENM4rTlsJ0s3fFROA0KXPBmKggqmTSaE383sl8F3KCOXPLmVsYfW6hCitMhXCEtNeZxxg==}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
+  '@oxc-resolver/binding-linux-x64-musl@11.24.2':
+    resolution: {integrity: sha512-8hbnZyNi97b/8wapYaIF9+t9GmZKBW2vunaOc3h9HGJptH7b7XpvZqOTBSm/MpTjr7H497BlgOaSfLUdhmy2bw==}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
+  '@oxc-resolver/binding-openharmony-arm64@11.24.2':
+    resolution: {integrity: sha512-MvyGik3a6pVgZ0t/kWlbmFxFLmXQJwgLsY2eYFHLpy0wGwRbfzeIGgDwQ3kXqE30z+kSXennRkCrT7TUvkptNg==}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@oxc-resolver/binding-wasm32-wasi@11.24.2':
+    resolution: {integrity: sha512-vHcssMPwO08RTvj/c0iOBz90attxyG3wQJ0dTcyEQK43LRpcdLWZlV5feBhv6Isn6ahbQIzHbCgfa81+RiML0Q==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+
+  '@oxc-resolver/binding-win32-arm64-msvc@11.24.2':
+    resolution: {integrity: sha512-uokJqro2iBqkFvJdKQLP7d8/BUmFwESQFVmIJUQKj1Xn1a/LysJoe1vmeECLF5b3jsV8CAL5sEMJXX6SdK9Nhg==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@oxc-resolver/binding-win32-x64-msvc@11.24.2':
+    resolution: {integrity: sha512-UqGPmo56KDfLlfXFAFIrNflHT8tFxWGEivWg3Zeyp4Uy2NlKN1FGPr6/BxcLGG3+kZ6Wp14g5Uj+n71boqZfiw==}
+    cpu: [x64]
+    os: [win32]
+
   '@oxfmt/binding-android-arm-eabi@0.64.0':
     resolution: {integrity: sha512-o6uzh/jTOQeAY5TdkAeXdqv7MBRcPxiRA08zrcBtkKj5cSu/FMu0Hl7Q6Fi1KCKyCWZ6lJVjBzdsJvsKltUsGQ==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -6975,6 +7212,9 @@ packages:
   fb-watchman@2.0.2:
     resolution: {integrity: sha512-p5161BqbuCaSnB8jIbzQHOlpgsPmK5rJVDfDKO91Axs5NC1uu3HRQm6wt9cd9/+GtQQIO53JdGXXoyDpTAsgYA==}
 
+  fd-package-json@2.0.0:
+    resolution: {integrity: sha512-jKmm9YtsNXN789RS/0mSzOC1NUq9mkVd65vbSSVsKdjGvYXBuE4oWe2QOEoFeRmJg+lPuZxpmrfFclNhoRMneQ==}
+
   fdir@6.5.0:
     resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
     engines: {node: '>=12.0.0'}
@@ -7037,6 +7277,11 @@ packages:
     resolution: {integrity: sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==}
     engines: {node: '>= 6'}
 
+  formatly@0.7.0:
+    resolution: {integrity: sha512-7CXJtIIA0zy/u12StsYk25qVKxvdLA2ep2sTNxK3ov0mGNIIDqIvAXDSgTnAfDJFsPfWjuz0WjfYSdpvnLA5Tg==}
+    engines: {node: '>=18.3.0'}
+    hasBin: true
+
   forwarded@0.2.0:
     resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
     engines: {node: '>= 0.6'}
@@ -7118,6 +7363,9 @@ packages:
   get-tsconfig@4.14.0:
     resolution: {integrity: sha512-yTb+8DXzDREzgvYmh6s9vHsSVCHeC0G3PI5bEXNBHtmshPnO+S5O7qgLEOn0I5QvMy6kpZN8K1NKGyilLb93wA==}
 
+  get-tsconfig@4.14.3:
+    resolution: {integrity: sha512-++QEw4DIY7WGoukz+/+A/8dGYPT9l9yIadnmSgZ8Rjr3YVSVDipQSO9CdnJo9ePqFqUUqh+wk9uIaoiAwsiPkA==}
+
   get-tsconfig@5.0.0-beta.4:
     resolution: {integrity: sha512-7nF7C9fIPFEMHgEMEfgIlO9wDdZ8CyHw27rWciFZfHvHDReIiPhsYuzPRXsfvBCqFy1l8RRyyWV7QLM+ZhUJsQ==}
     engines: {node: '>=20.20.0'}
@@ -7618,6 +7866,11 @@ packages:
     resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
     engines: {node: '>=6'}
 
+  knip@6.34.0:
+    resolution: {integrity: sha512-bbHIrnGspYwe4EBPjjx+lvkUor0F2qfKQc5BPzPI4SOAImYA+k2ueVpIcF7d/W1LEVT7XoJUPt6zELeGZhXBgA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+
   kubernetes-types@1.30.0:
     resolution: {integrity: sha512-Dew1okvhM/SQcIa2rcgujNndZwU8VnSapDgdxlYoB84ZlpAD43U6KLAFqYo17ykSFGHNPrg0qry0bP+GJd9v7Q==}
 
@@ -8490,6 +8743,13 @@ packages:
   outvariant@1.4.3:
     resolution: {integrity: sha512-+Sl2UErvtsoajRDKCE5/dBz4DIvHXQQnAxtQTF04OJxY0+DyZXSo5P5Bb7XYWOh81syohlYL24hbDwxedPUJCA==}
 
+  oxc-parser@0.147.0:
+    resolution: {integrity: sha512-5xaug6t7GfV3BO5Iv+xHW1rmQkDEQ3BEu3L8g3InsvWO5i8CYGc4tCZ2X985QcwWNycFJam+aOns6Nr2XAThTA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+
+  oxc-resolver@11.24.2:
+    resolution: {integrity: sha512-FY91FiDBj7ls5MsFS9jN3tjz2o0/zsdSsymlakySaBwVJZorHhkWyICLZMKxlu1R9vYo+sd3z1jwb4J8x7bNDw==}
+
   oxfmt@0.64.0:
     resolution: {integrity: sha512-XZ4GFBN/PLbXKq+0zrgpQfPKYuJlUuj+nzZJY7UpIbFMNyefNLCdN9EwViycNqnYcv0wrn0jXcQLlqJp8RCKBg==}
     engines: {node: ^20.19.0 || >=22.12.0}
@@ -8555,6 +8815,9 @@ packages:
   package-manager-detector@1.6.0:
     resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
 
+  package-manager-detector@1.8.0:
+    resolution: {integrity: sha512-yQA4H19AmPEoMUeavPMDIe1higySl/gH/yaQrkT/s07Qp+7pp2hYz30N3z2l5BkjVkF9Ow6o0wjJamm2y7Sn0A==}
+
   pako@1.0.11:
     resolution: {integrity: sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==}
 
@@ -8697,6 +8960,10 @@ packages:
     resolution: {integrity: sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==}
     engines: {node: '>=12'}
 
+  picomatch@4.0.7:
+    resolution: {integrity: sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==}
+    engines: {node: '>=12'}
+
   pkce-challenge@5.0.1:
     resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
     engines: {node: '>=16.20.0'}
@@ -9092,6 +9359,11 @@ packages:
       '@types/react':
         optional: true
 
+  react-test-renderer@19.2.6:
+    resolution: {integrity: sha512-GbS6V23YduFTPiWJ5xICbKEjRcqx1Z90js/V5miqhz7qp/d6xSe9Dd6NjSQODFRdzdsqRMPW82E/sFpPRbY5Mw==}
+    peerDependencies:
+      react: ^19.2.6
+
   react@19.2.3:
     resolution: {integrity: sha512-Ku/hhYbVjOQnXDZFv2+RibmLFGwFdeeKHFcOTlrt7xplBnya5OGn/hIRDsqDiSUcfORsDC7MPxwork8jBwsIWA==}
     engines: {node: '>=0.10.0'}
@@ -9487,6 +9759,10 @@ packages:
     resolution: {integrity: sha512-aqVvWoyO21L23mb+drl4RmMXbf6N7FdHjAhTRA9ZBL7apWBgfWC16KjrASI+1p9GAroljyMHj6fK67i0UiTNvQ==}
     engines: {node: '>= 18'}
 
+  smol-toml@1.8.0:
+    resolution: {integrity: sha512-kCZr2V3ch9i00x8zXRhjUNVcjG9ijES5dDudkXvUVCT5QlJNQWElSJdZqyPemffHoLNUYwOcou0Fy+ojN0uHSQ==}
+    engines: {node: '>= 18'}
+
   source-map-js@1.2.1:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
@@ -9606,6 +9882,10 @@ packages:
     resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
     engines: {node: '>=12'}
 
+  strip-json-comments@5.0.3:
+    resolution: {integrity: sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw==}
+    engines: {node: '>=14.16'}
+
   strnum@2.3.0:
     resolution: {integrity: sha512-ums3KNd42PGyx5xaoVTO1mjU1bH3NpY4vsrVlnv9PNGqQj8wd7rJ6nEypLrJ7z5vxK5RP0yMLo6J/Gsm62DI5Q==}
 
@@ -9838,6 +10118,10 @@ packages:
   ultrahtml@1.6.0:
     resolution: {integrity: sha512-R9fBn90VTJrqqLDwyMph+HGne8eqY1iPfYhPzZrvKpIfwkWZbcYlfpsb8B9dTvBfpy1/hqAD7Wi8EKfP9e8zdw==}
 
+  unbash@4.0.11:
+    resolution: {integrity: sha512-FoSOKV7NEofQSkAefMVHam4ZPKYMxjAydxiV72UFEDNV/YofxjGfiZ2A9pZjdL/lRJzTjcu4PABo1JYJX8N5iQ==}
+    engines: {node: '>=14'}
+
   uncrypto@0.1.3:
     resolution: {integrity: sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q==}
 
@@ -10264,6 +10548,10 @@ packages:
   vscode-uri@3.1.0:
     resolution: {integrity: sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==}
 
+  walk-up-path@4.0.0:
+    resolution: {integrity: sha512-3hu+tD8YzSLGuFYtPRb48vdhKMi0KQV5sn+uWr8+7dMEq/2G/dtLrdDinkLjqq5TIbIBjYJ4Ax/n3YiaW7QM8A==}
+    engines: {node: 20 || >=22}
+
   walker@1.0.8:
     resolution: {integrity: sha512-ts/8E8l5b7kY0vlWLewOkDXMmPdLcVV4GmOQLyxuSswIJsweeFZtAsMF7k1Nszz+TYBQrlYRmzOnr398y1JemQ==}
 
@@ -10527,7 +10815,7 @@ snapshots:
 
   '@alchemy.run/node-utils@0.0.5': {}
 
-  '@anthropic-ai/claude-agent-sdk@0.3.170(@anthropic-ai/sdk@0.93.0(zod@4.4.3))(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(zod@4.4.3)':
+  '@anthropic-ai/claude-agent-sdk@0.3.260(@anthropic-ai/sdk@0.93.0(zod@4.4.3))(@modelcontextprotocol/sdk@1.29.0(zod@4.4.3))(zod@4.4.3)':
     dependencies:
       '@anthropic-ai/sdk': 0.93.0(zod@4.4.3)
       '@modelcontextprotocol/sdk': 1.29.0(zod@4.4.3)
@@ -10611,10 +10899,10 @@ snapshots:
       '@types/hast': 3.0.4
       '@types/mdast': 4.0.4
       js-yaml: 4.2.0
-      picomatch: 4.0.4
+      picomatch: 4.0.7
       retext-smartypants: 6.2.0
       shiki: 4.2.0
-      smol-toml: 1.7.0
+      smol-toml: 1.8.0
       unified: 11.0.5
 
   '@astrojs/language-server@2.16.10(prettier@3.8.3)(typescript@6.0.3)':
@@ -11989,6 +12277,12 @@ snapshots:
       tslib: 2.8.1
     optional: true
 
+  '@emnapi/core@1.11.2':
+    dependencies:
+      '@emnapi/wasi-threads': 1.2.2
+      tslib: 2.8.1
+    optional: true
+
   '@emnapi/runtime@1.10.0':
     dependencies:
       tslib: 2.8.1
@@ -11999,6 +12293,11 @@ snapshots:
       tslib: 2.8.1
     optional: true
 
+  '@emnapi/runtime@1.11.2':
+    dependencies:
+      tslib: 2.8.1
+    optional: true
+
   '@emnapi/wasi-threads@1.2.1':
     dependencies:
       tslib: 2.8.1
@@ -12517,7 +12816,7 @@ snapshots:
       hermes-parser: 0.36.1
       jsc-safe-url: 0.2.4
       lightningcss: 1.33.0
-      picomatch: 4.0.4
+      picomatch: 4.0.7
       postcss: 8.5.15
       resolve-from: 5.0.0
     optionalDependencies:
@@ -12776,8 +13075,7 @@ snapshots:
 
   '@iarna/toml@2.2.5': {}
 
-  '@img/colour@1.1.0':
-    optional: true
+  '@img/colour@1.1.0': {}
 
   '@img/sharp-darwin-arm64@0.34.5':
     optionalDependencies:
@@ -13319,6 +13617,13 @@ snapshots:
       '@tybys/wasm-util': 0.10.3
     optional: true
 
+  '@napi-rs/wasm-runtime@1.1.6(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2)':
+    dependencies:
+      '@emnapi/core': 1.11.2
+      '@emnapi/runtime': 1.11.2
+      '@tybys/wasm-util': 0.10.3
+    optional: true
+
   '@neon-rs/load@0.0.4': {}
 
   '@noble/curves@1.9.1':
@@ -13436,6 +13741,63 @@ snapshots:
 
   '@oslojs/encoding@1.1.0': {}
 
+  '@oxc-parser/binding-android-arm-eabi@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-android-arm64@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-darwin-arm64@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-darwin-x64@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-freebsd-x64@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-arm-gnueabihf@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-arm-musleabihf@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-arm64-gnu@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-arm64-musl@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-ppc64-gnu@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-riscv64-gnu@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-riscv64-musl@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-s390x-gnu@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-x64-gnu@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-linux-x64-musl@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-openharmony-arm64@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-win32-arm64-msvc@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-win32-ia32-msvc@0.147.0':
+    optional: true
+
+  '@oxc-parser/binding-win32-x64-msvc@0.147.0':
+    optional: true
+
   '@oxc-project/runtime@0.146.0': {}
 
   '@oxc-project/types@0.127.0':
@@ -13445,6 +13807,69 @@ snapshots:
 
   '@oxc-project/types@0.146.0': {}
 
+  '@oxc-project/types@0.147.0': {}
+
+  '@oxc-resolver/binding-android-arm-eabi@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-android-arm64@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-darwin-arm64@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-darwin-x64@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-freebsd-x64@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-arm-gnueabihf@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-arm-musleabihf@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-arm64-gnu@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-arm64-musl@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-ppc64-gnu@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-riscv64-gnu@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-riscv64-musl@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-s390x-gnu@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-x64-gnu@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-linux-x64-musl@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-openharmony-arm64@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-wasm32-wasi@11.24.2':
+    dependencies:
+      '@emnapi/core': 1.11.2
+      '@emnapi/runtime': 1.11.2
+      '@napi-rs/wasm-runtime': 1.1.6(@emnapi/core@1.11.2)(@emnapi/runtime@1.11.2)
+    optional: true
+
+  '@oxc-resolver/binding-win32-arm64-msvc@11.24.2':
+    optional: true
+
+  '@oxc-resolver/binding-win32-x64-msvc@11.24.2':
+    optional: true
+
   '@oxfmt/binding-android-arm-eabi@0.64.0':
     optional: true
 
@@ -13603,7 +14028,7 @@ snapshots:
       tslib: 2.8.1
       webcrypto-core: 1.9.2
 
-  '@pierre/diffs@1.3.0-beta.10(patch_hash=7ef7cb0cbabb17c15cdb137554068b36f15f6f5265e73fb51452aa3380db91aa)(@shikijs/themes@4.2.0)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+  '@pierre/diffs@1.3.0-beta.10(patch_hash=0ccee155b93b63d810e2c1a40c1fd676fb6fbcfa72cf6430dcedf1a3ae475ab4)(@shikijs/themes@4.2.0)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       '@pierre/theme': 1.1.0
       '@pierre/theming': 0.0.2(@pierre/theme@1.1.0)(@shikijs/themes@4.2.0)(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(shiki@4.2.0)
@@ -13617,7 +14042,7 @@ snapshots:
     transitivePeerDependencies:
       - '@shikijs/themes'
 
-  '@pierre/diffs@1.3.0-beta.10(patch_hash=7ef7cb0cbabb17c15cdb137554068b36f15f6f5265e73fb51452aa3380db91aa)(@shikijs/themes@4.3.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+  '@pierre/diffs@1.3.0-beta.10(patch_hash=0ccee155b93b63d810e2c1a40c1fd676fb6fbcfa72cf6430dcedf1a3ae475ab4)(@shikijs/themes@4.3.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@pierre/theme': 1.1.0
       '@pierre/theming': 0.0.2(@pierre/theme@1.1.0)(@shikijs/themes@4.3.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)(shiki@4.2.0)
@@ -13873,7 +14298,7 @@ snapshots:
       '@babel/plugin-transform-private-methods': 7.29.7(@babel/core@7.29.7)
       '@babel/plugin-transform-private-property-in-object': 7.29.7(@babel/core@7.29.7)
       '@babel/plugin-transform-react-display-name': 7.29.7(@babel/core@7.29.7)
-      '@babel/plugin-transform-react-jsx': 7.28.6(@babel/core@7.29.7)
+      '@babel/plugin-transform-react-jsx': 7.29.7(@babel/core@7.29.7)
       '@babel/plugin-transform-react-jsx-self': 7.29.7(@babel/core@7.29.7)
       '@babel/plugin-transform-react-jsx-source': 7.29.7(@babel/core@7.29.7)
       '@babel/plugin-transform-regenerator': 7.29.7(@babel/core@7.29.7)
@@ -17054,10 +17479,18 @@ snapshots:
     dependencies:
       bser: 2.1.1
 
+  fd-package-json@2.0.0:
+    dependencies:
+      walk-up-path: 4.0.0
+
   fdir@6.5.0(picomatch@4.0.4):
     optionalDependencies:
       picomatch: 4.0.4
 
+  fdir@6.5.0(picomatch@4.0.7):
+    optionalDependencies:
+      picomatch: 4.0.7
+
   fetch-nodeshim@0.4.10: {}
 
   ffi-rs@1.3.2:
@@ -17135,6 +17568,11 @@ snapshots:
       hasown: 2.0.4
       mime-types: 2.1.35
 
+  formatly@0.7.0:
+    dependencies:
+      fd-package-json: 2.0.0
+      package-manager-detector: 1.8.0
+
   forwarded@0.2.0: {}
 
   fresh@0.5.2: {}
@@ -17223,6 +17661,10 @@ snapshots:
     dependencies:
       resolve-pkg-maps: 1.0.0
 
+  get-tsconfig@4.14.3:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
   get-tsconfig@5.0.0-beta.4:
     dependencies:
       resolve-pkg-maps: 1.0.0
@@ -17791,6 +18233,22 @@ snapshots:
 
   kleur@4.1.5: {}
 
+  knip@6.34.0:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.7)
+      formatly: 0.7.0
+      get-tsconfig: 4.14.3
+      jiti: 2.7.0
+      oxc-parser: 0.147.0
+      oxc-resolver: 11.24.2
+      picomatch: 4.0.7
+      smol-toml: 1.8.0
+      strip-json-comments: 5.0.3
+      tinyglobby: 0.2.17
+      unbash: 4.0.11
+      yaml: 2.9.0
+      zod: 4.4.3
+
   kubernetes-types@1.30.0: {}
 
   lan-network@0.2.1: {}
@@ -19073,6 +19531,52 @@ snapshots:
   outvariant@1.4.3:
     optional: true
 
+  oxc-parser@0.147.0:
+    dependencies:
+      '@oxc-project/types': 0.147.0
+    optionalDependencies:
+      '@oxc-parser/binding-android-arm-eabi': 0.147.0
+      '@oxc-parser/binding-android-arm64': 0.147.0
+      '@oxc-parser/binding-darwin-arm64': 0.147.0
+      '@oxc-parser/binding-darwin-x64': 0.147.0
+      '@oxc-parser/binding-freebsd-x64': 0.147.0
+      '@oxc-parser/binding-linux-arm-gnueabihf': 0.147.0
+      '@oxc-parser/binding-linux-arm-musleabihf': 0.147.0
+      '@oxc-parser/binding-linux-arm64-gnu': 0.147.0
+      '@oxc-parser/binding-linux-arm64-musl': 0.147.0
+      '@oxc-parser/binding-linux-ppc64-gnu': 0.147.0
+      '@oxc-parser/binding-linux-riscv64-gnu': 0.147.0
+      '@oxc-parser/binding-linux-riscv64-musl': 0.147.0
+      '@oxc-parser/binding-linux-s390x-gnu': 0.147.0
+      '@oxc-parser/binding-linux-x64-gnu': 0.147.0
+      '@oxc-parser/binding-linux-x64-musl': 0.147.0
+      '@oxc-parser/binding-openharmony-arm64': 0.147.0
+      '@oxc-parser/binding-win32-arm64-msvc': 0.147.0
+      '@oxc-parser/binding-win32-ia32-msvc': 0.147.0
+      '@oxc-parser/binding-win32-x64-msvc': 0.147.0
+
+  oxc-resolver@11.24.2:
+    optionalDependencies:
+      '@oxc-resolver/binding-android-arm-eabi': 11.24.2
+      '@oxc-resolver/binding-android-arm64': 11.24.2
+      '@oxc-resolver/binding-darwin-arm64': 11.24.2
+      '@oxc-resolver/binding-darwin-x64': 11.24.2
+      '@oxc-resolver/binding-freebsd-x64': 11.24.2
+      '@oxc-resolver/binding-linux-arm-gnueabihf': 11.24.2
+      '@oxc-resolver/binding-linux-arm-musleabihf': 11.24.2
+      '@oxc-resolver/binding-linux-arm64-gnu': 11.24.2
+      '@oxc-resolver/binding-linux-arm64-musl': 11.24.2
+      '@oxc-resolver/binding-linux-ppc64-gnu': 11.24.2
+      '@oxc-resolver/binding-linux-riscv64-gnu': 11.24.2
+      '@oxc-resolver/binding-linux-riscv64-musl': 11.24.2
+      '@oxc-resolver/binding-linux-s390x-gnu': 11.24.2
+      '@oxc-resolver/binding-linux-x64-gnu': 11.24.2
+      '@oxc-resolver/binding-linux-x64-musl': 11.24.2
+      '@oxc-resolver/binding-openharmony-arm64': 11.24.2
+      '@oxc-resolver/binding-wasm32-wasi': 11.24.2
+      '@oxc-resolver/binding-win32-arm64-msvc': 11.24.2
+      '@oxc-resolver/binding-win32-x64-msvc': 11.24.2
+
   oxfmt@0.64.0(vite-plus@0.3.0(@types/node@24.12.4)(bufferutil@4.1.0)(esbuild@0.28.1)(jiti@2.7.0)(msw@2.12.11(@types/node@24.12.4)(typescript@6.0.3))(terser@5.48.0)(typescript@6.0.3)(unrun@0.2.39)(utf-8-validate@6.0.6)(yaml@2.9.0)):
     dependencies:
       tinypool: 2.1.0
@@ -19160,6 +19664,8 @@ snapshots:
 
   package-manager-detector@1.6.0: {}
 
+  package-manager-detector@1.8.0: {}
+
   pako@1.0.11: {}
 
   parse-entities@4.0.2:
@@ -19298,6 +19804,8 @@ snapshots:
 
   picomatch@4.0.4: {}
 
+  picomatch@4.0.7: {}
+
   pkce-challenge@5.0.1: {}
 
   pkg-up@3.1.0:
@@ -19795,6 +20303,12 @@ snapshots:
     optionalDependencies:
       '@types/react': 19.2.16
 
+  react-test-renderer@19.2.6(react@19.2.6):
+    dependencies:
+      react: 19.2.6
+      react-is: 19.2.7
+      scheduler: 0.27.0
+
   react@19.2.3: {}
 
   react@19.2.6: {}
@@ -20276,7 +20790,6 @@ snapshots:
       '@img/sharp-win32-arm64': 0.34.5
       '@img/sharp-win32-ia32': 0.34.5
       '@img/sharp-win32-x64': 0.34.5
-    optional: true
 
   shebang-command@2.0.0:
     dependencies:
@@ -20388,6 +20901,8 @@ snapshots:
 
   smol-toml@1.7.0: {}
 
+  smol-toml@1.8.0: {}
+
   source-map-js@1.2.1: {}
 
   source-map-support@0.5.21:
@@ -20490,6 +21005,8 @@ snapshots:
     dependencies:
       ansi-regex: 6.2.2
 
+  strip-json-comments@5.0.3: {}
+
   strnum@2.3.0: {}
 
   structured-headers@0.4.1: {}
@@ -20706,6 +21223,8 @@ snapshots:
 
   ultrahtml@1.6.0: {}
 
+  unbash@4.0.11: {}
+
   uncrypto@0.1.3: {}
 
   undici-types@7.16.0: {}
@@ -21123,6 +21642,8 @@ snapshots:
 
   vscode-uri@3.1.0: {}
 
+  walk-up-path@4.0.0: {}
+
   walker@1.0.8:
     dependencies:
       makeerror: 1.0.12
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 7d2f9f998617..ee1bd25547f6 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -90,6 +90,7 @@ minimumReleaseAgeExclude:
   - expo-updates@57.0.19
   - expo@57.0.18
   - expo-widgets@57.0.15
+  - "@anthropic-ai/claude-agent-sdk@0.3.260"
 
 overrides:
   # The SDK always receives the user's Claude executable, so its bundled binaries are unused.
diff --git a/scripts/build-desktop-artifact.test.ts b/scripts/build-desktop-artifact.test.ts
index 478f6ee2d21b..affb83eb7506 100644
--- a/scripts/build-desktop-artifact.test.ts
+++ b/scripts/build-desktop-artifact.test.ts
@@ -87,6 +87,7 @@ import {
 } from "./build-desktop-artifact.ts";
 import { BRAND_ASSET_PATHS } from "./lib/brand-assets.ts";
 import { HostProcessArchitecture, HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 // A minimal stand-in for the staged sidecar roots packed into the WSL archive.
 const stageWslRuntimeTreeFixture = Effect.fn("stageWslRuntimeTreeFixture")(function* (
@@ -1039,6 +1040,9 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
     ),
   );
 
+  // The fixture's t3code.exe is a text placeholder, not an executable. These
+  // cases reach the native-load probe, so pin only that host-platform check to
+  // Linux. Host-native paths and the real Windows tar/archive checks still run.
   it.effect("validates every ASAR-unpacked native in the packaged Windows payload", () =>
     Effect.scoped(
       Effect.gen(function* () {
@@ -1067,7 +1071,7 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
         assert.isBelow(result.fileCount, WINDOWS_PACKAGED_PAYLOAD_FILE_LIMIT);
         assert.deepStrictEqual(secondAsar, firstAsar);
       }),
-    ),
+    ).pipe(Effect.provideService(HostProcessPlatform, "linux")),
   );
 
   it.effect("validates the emitted WSL archive and its SHA-256 sidecar", () =>
@@ -1086,7 +1090,7 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
 
         assert.equal(result.packagedAppDir, fixture.packagedAppDir);
       }),
-    ),
+    ).pipe(Effect.provideService(HostProcessPlatform, "linux")),
   );
 
   it.effect("rejects a Windows package missing its expected WSL runtime", () =>
@@ -1234,11 +1238,12 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
         command.args.some((arg) => arg.endsWith("build-browser-secret.mjs")),
       );
       assert.isDefined(helper);
+      const path = yield* Path.Path;
       assert.deepStrictEqual(helper.args.slice(-4), [
         "--arch",
         "x64",
         "--output",
-        "/stage/resources/browser-secret/t3-browser-secret",
+        path.join("/stage/resources", "browser-secret", "t3-browser-secret"),
       ]);
     }).pipe(
       Effect.provide(
@@ -1460,7 +1465,7 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
         assert.instanceOf(error, BundleNotSelfContainedError);
         assert.include(error.output, "t3code-deliberately-missing-package");
       }),
-    ),
+    ).pipe(Effect.provideService(HostProcessPlatform, "linux")),
   );
 
   it.effect("preserves both Linux icon resize failures with structural context", () => {
@@ -1700,7 +1705,7 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
       assert.equal(config.appId, "com.t3tools.t3code");
       assert.equal(mac.entitlements, "/tmp/entitlements.mac.plist");
       assert.equal(mac.provisioningProfile, "/tmp/t3code.provisionprofile");
-      assert.match(String(mac.sign), /\/scripts\/sign-macos\.ts$/);
+      assert.match(String(mac.sign), /[\\/]scripts[\\/]sign-macos\.ts$/);
       assert.deepStrictEqual(mac.protocols, [
         { name: "T3 Code", schemes: ["t3code", "t3code-dev"] },
       ]);
@@ -2191,7 +2196,7 @@ it("keeps the prefix of a UNC path instead of going relative", () => {
   assert.deepStrictEqual(paths[0], "\\\\server\\share\\tmp\\node_modules");
 });
 
-it.effect("rebases packaged links into the isolated tree", () =>
+it.effect.skipIf(!symlinksSupported)("rebases packaged links into the isolated tree", () =>
   Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
diff --git a/scripts/build-desktop-artifact.ts b/scripts/build-desktop-artifact.ts
index 3e40d94dc69a..32b090f7a83b 100644
--- a/scripts/build-desktop-artifact.ts
+++ b/scripts/build-desktop-artifact.ts
@@ -348,7 +348,7 @@ export class LinuxDesktopBuildPrerequisitesMissingError extends Schema.TaggedErr
         ? ["Add the requested Rust target with:", `  rustup target add ${this.rustTarget}`]
         : []),
       "",
-      "For other distributions, see docs/internals/scripts.md#linux-appimage-prerequisites.",
+      "For other distributions, see docs/operations/development.md#linux-appimage-prerequisites.",
       "Then rerun `vp run dist:desktop:linux`.",
     ].join("\n");
   }
@@ -420,7 +420,7 @@ export class WindowsDesktopBuildPrerequisitesMissingError extends Schema.TaggedE
       "Install Rust from https://rustup.rs and add the requested target:",
       `  rustup target add ${this.rustTarget}`,
       "Install Python 3 and the Visual Studio Build Tools components listed in",
-      "docs/internals/scripts.md#windows-installer-prerequisites.",
+      "docs/operations/development.md#windows-installer-prerequisites.",
       "",
       "Then rerun the desktop artifact command.",
     ].join("\n");
diff --git a/scripts/lib/cli-external-packages.test.ts b/scripts/lib/cli-external-packages.test.ts
index 754cd646f17d..e894359eccb5 100644
--- a/scripts/lib/cli-external-packages.test.ts
+++ b/scripts/lib/cli-external-packages.test.ts
@@ -153,21 +153,26 @@ it.layer(NodeServices.layer)("external package dependency closure", (it) => {
   const isRuntimeExternal = (name: string) =>
     CLI_RUNTIME_EXTERNAL_PREFIXES.some((prefix) => name.startsWith(prefix));
 
-  it.effect("finds the runtime-external packages on disk", () =>
-    Effect.gen(function* () {
-      const installed = yield* readInstalledPackages;
-      const found = [...installed.keys()].filter(isRuntimeExternal);
-
-      // Without this the closure check below can pass vacuously: if nothing is
-      // read, nothing is checked. These are the packages whose closure actually
-      // broke WSL, so require them by name.
-      for (const required of ["node-pty", "node-gyp-build-optional-packages", "detect-libc"]) {
-        assert.ok(
-          found.includes(required),
-          `expected ${required} in the pnpm store; the closure check is only meaningful if it can read these (found ${found.length})`,
-        );
-      }
-    }),
+  // A cold walk of the pnpm store can exceed the root timeout when the Windows
+  // lane runs four filesystem-heavy workspace suites at once.
+  it.effect(
+    "finds the runtime-external packages on disk",
+    () =>
+      Effect.gen(function* () {
+        const installed = yield* readInstalledPackages;
+        const found = [...installed.keys()].filter(isRuntimeExternal);
+
+        // Without this the closure check below can pass vacuously: if nothing is
+        // read, nothing is checked. These are the packages whose closure actually
+        // broke WSL, so require them by name.
+        for (const required of ["node-pty", "node-gyp-build-optional-packages", "detect-libc"]) {
+          assert.ok(
+            found.includes(required),
+            `expected ${required} in the pnpm store; the closure check is only meaningful if it can read these (found ${found.length})`,
+          );
+        }
+      }),
+    120_000,
   );
 
   it.effect("keeps every runtime dependency of an external package external too", () =>
diff --git a/scripts/mobile-showcase.test.ts b/scripts/mobile-showcase.test.ts
index 2fd4c1dd8edd..a3f11e3a37c7 100644
--- a/scripts/mobile-showcase.test.ts
+++ b/scripts/mobile-showcase.test.ts
@@ -1,3 +1,5 @@
+// @effect-diagnostics nodeBuiltinImport:off - expectations mirror the host path joins the script under test performs.
+import * as NodePath from "node:path";
 import { assert, it } from "@effect/vitest";
 import { PNG } from "pngjs";
 
@@ -167,8 +169,14 @@ it("expands both appearances into independent upload-ready directories", () => {
       directory: showcaseCaptureDirectory("/captures", capture),
     })),
     [
-      { appearance: "light", directory: "/captures/apple/iphone-test/light/t3-code" },
-      { appearance: "dark", directory: "/captures/apple/iphone-test/dark/t3-code" },
+      {
+        appearance: "light",
+        directory: NodePath.join("/captures", "apple", "iphone-test", "light", "t3-code"),
+      },
+      {
+        appearance: "dark",
+        directory: NodePath.join("/captures", "apple", "iphone-test", "dark", "t3-code"),
+      },
     ],
   );
 });
@@ -192,10 +200,10 @@ it("expands themes into independent upload-ready directories per appearance", ()
       showcaseCaptureDirectory("/captures", capture),
     ),
     [
-      "/captures/apple/iphone-test/light/ocean",
-      "/captures/apple/iphone-test/light/ember",
-      "/captures/apple/iphone-test/dark/ocean",
-      "/captures/apple/iphone-test/dark/ember",
+      NodePath.join("/captures", "apple", "iphone-test", "light", "ocean"),
+      NodePath.join("/captures", "apple", "iphone-test", "light", "ember"),
+      NodePath.join("/captures", "apple", "iphone-test", "dark", "ocean"),
+      NodePath.join("/captures", "apple", "iphone-test", "dark", "ember"),
     ],
   );
 });
diff --git a/scripts/mobile-showcase.ts b/scripts/mobile-showcase.ts
index d6ced75d5db2..6b6adebeb779 100644
--- a/scripts/mobile-showcase.ts
+++ b/scripts/mobile-showcase.ts
@@ -53,7 +53,8 @@ export function resolveAndroidSdkRoot(
   const configured = environment.ANDROID_HOME ?? environment.ANDROID_SDK_ROOT;
   if (configured) return configured;
   const home = environment.HOME ?? environment.USERPROFILE ?? "";
-  return NodePath.join(home, platform === "darwin" ? "Library/Android/sdk" : "Android/Sdk");
+  const path = platform === "win32" ? NodePath.win32 : NodePath.posix;
+  return path.join(home, platform === "darwin" ? "Library/Android/sdk" : "Android/Sdk");
 }
 
 const ANDROID_SDK_ROOT = resolveAndroidSdkRoot(NodeProcess.env);
diff --git a/scripts/mock-update-server.test.ts b/scripts/mock-update-server.test.ts
index 1371ba58f44f..5e060ff9013b 100644
--- a/scripts/mock-update-server.test.ts
+++ b/scripts/mock-update-server.test.ts
@@ -7,6 +7,7 @@ import * as Path from "effect/Path";
 import { HttpClient, HttpRouter } from "effect/unstable/http";
 
 import { makeMockUpdateRouteLayer } from "./mock-update-server.ts";
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 
 const withMockUpdateServer = <A, E, R>(rootRealPath: string, effect: Effect.Effect<A, E, R>) =>
   effect.pipe(
@@ -72,35 +73,37 @@ it.layer(NodeServices.layer)("mock-update-server", (it) => {
     }),
   );
 
-  it.effect("rejects symlinked files that escape the configured root", () =>
-    Effect.gen(function* () {
-      const fileSystem = yield* FileSystem.FileSystem;
-      const path = yield* Path.Path;
-      const root = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "mock-update-server-root-",
-      });
-      const outside = yield* fileSystem.makeTempDirectoryScoped({
-        prefix: "mock-update-server-outside-",
-      });
-      const rootRealPath = yield* fileSystem.realPath(root);
-      const outsideFile = path.join(outside, "outside.yml");
-      const linksDir = path.join(root, "links");
-      const symlinkPath = path.join(linksDir, "outside.yml");
+  it.effect.skipIf(!symlinksSupported)(
+    "rejects symlinked files that escape the configured root",
+    () =>
+      Effect.gen(function* () {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const root = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "mock-update-server-root-",
+        });
+        const outside = yield* fileSystem.makeTempDirectoryScoped({
+          prefix: "mock-update-server-outside-",
+        });
+        const rootRealPath = yield* fileSystem.realPath(root);
+        const outsideFile = path.join(outside, "outside.yml");
+        const linksDir = path.join(root, "links");
+        const symlinkPath = path.join(linksDir, "outside.yml");
 
-      yield* fileSystem.writeFileString(outsideFile, "version: outside\n");
-      yield* fileSystem.makeDirectory(linksDir, { recursive: true });
-      yield* fileSystem.symlink(outsideFile, symlinkPath);
+        yield* fileSystem.writeFileString(outsideFile, "version: outside\n");
+        yield* fileSystem.makeDirectory(linksDir, { recursive: true });
+        yield* fileSystem.symlink(outsideFile, symlinkPath);
 
-      yield* withMockUpdateServer(
-        rootRealPath,
-        Effect.gen(function* () {
-          const client = yield* HttpClient.HttpClient;
-          const response = yield* client.get("/links/outside.yml");
+        yield* withMockUpdateServer(
+          rootRealPath,
+          Effect.gen(function* () {
+            const client = yield* HttpClient.HttpClient;
+            const response = yield* client.get("/links/outside.yml");
 
-          assert.equal(response.status, 404);
-          assert.equal(yield* response.text, "Not Found");
-        }),
-      );
-    }),
+            assert.equal(response.status, 404);
+            assert.equal(yield* response.text, "Not Found");
+          }),
+        );
+      }),
   );
 });
diff --git a/vite.config.ts b/vite.config.ts
index d3aec8e9764b..258555e04b5a 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -19,6 +19,11 @@ export default defineConfig({
     ],
     hookTimeout: 60_000,
     testTimeout: 60_000,
+    setupFiles: [
+      NodeURL.fileURLToPath(
+        new URL("./packages/shared/src/testing/longTempDir.ts", import.meta.url),
+      ),
+    ],
   },
   staged: {
     // Formatter only for now — no lint or typecheck on commit.