diff --git a/.gitattributes b/.gitattributes
index 705bd8f43e00..00b0e5eccb98 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,2 +1,5 @@
 # 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
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 3d4bf10c050e..22947b977491 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -104,8 +104,12 @@ jobs:
       - 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
@@ -152,8 +156,12 @@ jobs:
         continue-on-error: true
         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/desktop' --filter '!@t3tools/monorepo' test
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index bc52f977a058..e35c99aaa7a8 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -237,6 +237,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
 
@@ -568,6 +570,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 d72f86069e5e..669a15a11b73 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -89,13 +89,9 @@ Long-term maintainability is a core priority. If you add new functionality, firs
 
 ### Provider Adapter Pattern
 
-All providers implement a unified adapter interface (`ProviderAdapterShape`) in `apps/server/src/provider/Services/`. Each adapter declares:
+All providers implement `ProviderAdapterShape` in `apps/server/src/provider/Services/ProviderAdapter.ts`. Capabilities declare `sessionModelSwitch` (`"in-session"` or `"unsupported"`), optional `promptlessTurnContinuation`, and optional `supportsConversationRollback`. Adapters without native history rewind must explicitly set `supportsConversationRollback: false` so checkpoints reject rewind before restoring files.
 
-- `transport` — how it communicates (`app-server-json-rpc`, `sdk-cli-server`, `acp-stdio`, `http-sse`, `cli-headless-json`, `cli-persistent-json`, `sdk-query`)
-- `sessionModelSwitch` — `"in-session"`, `"restart-session"`, or `"unsupported"`
-- `modelDiscovery` — `"native"`, `"acp-or-config"`, `"config-or-static"`, `"session-native"`, or `"unsupported"`
-
-Adapters are registered in `provider/Layers/ProviderAdapterRegistry.ts` and looked up by provider kind at runtime. Complex providers have dedicated process managers (e.g. `codexAppServerManager.ts`, `geminiCliServerManager.ts`, `ampServerManager.ts`).
+`provider/builtInDrivers.ts` registers built-in drivers; the adapter registry resolves providers and their configured instances. Transport and model discovery are driver implementation details, not adapter capability fields. Complex providers have dedicated process managers, while ACP providers share the runtime in `provider/acp/`.
 
 ### Key Server Modules
 
@@ -164,3 +160,15 @@ agents.
   examples of idiomatic usage, tests, module structure, and API design.
 - When writing relay infrastructure code with Alchemy, inspect `.repos/alchemy-effect/` for examples of
   idiomatic usage, tests, module structure, and API design.
+
+## 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.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cd14d4b951c2..dad7d8294ade 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ First off, thank you for considering contributing to this fork! It's people like
 
 ## Developer Setup
 
-See the [maintainer scripts guide](docs/internals/scripts.md#first-checkout) for the initial checkout,
+See the [maintainer scripts guide](docs/operations/development.md#first-checkout) for the initial checkout,
 development commands, tests, and platform-specific desktop packaging prerequisites.
 
 This fork is maintained in [aaditagrawal/t3code](https://github.com/aaditagrawal/t3code) and focuses on expanding provider support, preserving usage and limit monitoring, and improving the core orchestration and persistence layers.
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/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 b74e621bd583..cfa672914936 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:"]);
@@ -42,6 +60,7 @@ export function parseSafeExternalUrl(rawUrl: unknown): Option.Option<string> {
 export interface ElectronShellShape {
   readonly openExternal: (rawUrl: unknown) => Effect.Effect<boolean>;
   readonly openPath: (path: string) => Effect.Effect<void>;
+  readonly openSystemSettings: (pane: SystemSettingsPane) => Effect.Effect<boolean>;
   readonly copyText: (text: string) => Effect.Effect<void>;
 }
 
@@ -62,6 +81,13 @@ export const make = ElectronShell.of({
         ),
     }),
   openPath: (path) => Effect.promise(() => Electron.shell.openPath(path)).pipe(Effect.asVoid),
+  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/ipc/DesktopIpcHandlers.ts b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
index 39be03c95897..33f9c82814b9 100644
--- a/apps/desktop/src/ipc/DesktopIpcHandlers.ts
+++ b/apps/desktop/src/ipc/DesktopIpcHandlers.ts
@@ -41,6 +41,7 @@ import {
   listLogFiles,
   openLogDir,
   openExternal,
+  openSystemSettings,
   probeRemoteEditors,
   pickFolder,
   pickProjectFavicon,
@@ -102,6 +103,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
   yield* ipc.handle(listLogFiles);
   yield* ipc.handle(readLogFile);
   yield* ipc.handle(openLogDir);
+  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 22a00c103d34..f3bba0d45a1c 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 63e1068c55c5..d91b43be213a 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";
@@ -400,6 +401,16 @@ export const openLogDir = 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/preload.ts b/apps/desktop/src/preload.ts
index 5331fffdf922..8e41710a350a 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -120,6 +120,8 @@ contextBridge.exposeInMainWorld("desktopBridge", {
   listLogFiles: () => ipcRenderer.invoke(IpcChannels.LOG_LIST_CHANNEL),
   readLogFile: (filename) => ipcRenderer.invoke(IpcChannels.LOG_READ_CHANNEL, filename),
   openLogDir: () => ipcRenderer.invoke(IpcChannels.LOG_OPEN_DIR_CHANNEL),
+  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/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.test.ts b/apps/desktop/src/settings/DesktopClientSettings.test.ts
index 5a658090f1d2..fe5d05cee464 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,
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/window/DesktopWindow.test.ts b/apps/desktop/src/window/DesktopWindow.test.ts
index 56e00b715203..9ad1171598f8 100644
--- a/apps/desktop/src/window/DesktopWindow.test.ts
+++ b/apps/desktop/src/window/DesktopWindow.test.ts
@@ -281,6 +281,7 @@ function makeTestLayer(input: {
               return true;
             }),
           openPath: () => Effect.void,
+          openSystemSettings: () => Effect.succeed(true),
           copyText: () => Effect.void,
         } satisfies ElectronShell.ElectronShell["Service"]),
         electronThemeLayer,
@@ -382,6 +383,7 @@ const makeSplashScenario = (createOutcomes: readonly (Electron.BrowserWindow | n
           Layer.succeed(ElectronShell.ElectronShell, {
             openExternal: () => Effect.succeed(true),
             openPath: () => Effect.void,
+            openSystemSettings: () => Effect.succeed(true),
             copyText: () => Effect.void,
           } satisfies ElectronShell.ElectronShell["Service"]),
           electronThemeLayer,
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/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 cd28b446ccf1..a4fdc966b9d8 100644
--- a/apps/marketing/src/pages/index.astro
+++ b/apps/marketing/src/pages/index.astro
@@ -355,6 +355,7 @@ const screenshot = await getImage({
 
 <script>
   import { fetchLatestRelease, RELEASES_URL, type ReleaseAsset } from "../lib/releases";
+  import { startHomeMotion } from "../lib/homeMotion";
 
   type Platform = { os: "mac" | "win" | "linux"; label: string };
 
@@ -419,6 +420,14 @@ const screenshot = await getImage({
   }
 
   init();
+
+  const hero = document.querySelector<HTMLElement>(".hero");
+  const field = document.querySelector<HTMLElement>(".hero-float");
+  const endorsements = document.querySelector<HTMLElement>(".endorsement-carousel");
+  const caret = document.querySelector<HTMLElement>(".caret");
+  if (hero && field && endorsements && caret) {
+    startHomeMotion({ hero, field, endorsements, caret });
+  }
 </script>
 
 <style>
@@ -590,12 +599,14 @@ const screenshot = await getImage({
   :global([data-platform="linux"]) .dl-icon--linux { display: block; }
   :global(html:not([data-platform])) .dl-icon--apple { display: block; }
 
-  /* Harness marks stay in their final positions after the entry animation. */
+  /* Marks enter once, then drift while visible and lean toward the pointer. */
   .hero-float {
     position: absolute;
     inset: 0;
     pointer-events: none;
     z-index: 1;
+    --px: 0px;
+    --py: 0px;
   }
 
   .hero-float-mark {
@@ -605,6 +616,8 @@ const screenshot = await getImage({
     width: var(--s);
     height: var(--s);
     margin-left: calc(var(--s) / -2);
+    translate: calc(var(--px) * var(--depth)) calc(var(--py) * var(--depth));
+    transition: translate var(--parallax-duration, 0s) cubic-bezier(0.2, 0.7, 0.2, 1);
   }
 
   .hero-float-card {
@@ -618,7 +631,10 @@ const screenshot = await getImage({
     box-shadow:
       0 20px 48px -16px rgba(0, 0, 0, 0.65),
       0 2px 0 0 rgba(255, 255, 255, 0.04) inset;
-    animation: mark-in 1s cubic-bezier(0.2, 0.7, 0.2, 1) var(--d) both;
+    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 {
@@ -637,16 +653,21 @@ const screenshot = await getImage({
     from { opacity: 0; transform: translate(var(--fx), var(--fy)) rotate(calc(var(--rot) + 24deg)) scale(0.6); }
     to { opacity: 1; transform: translate(0, 0) rotate(var(--rot)) scale(1); }
   }
+  @keyframes mark-drift {
+    0%, 100% { transform: translate(0, 0) rotate(var(--rot)); }
+    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; --d: 620ms; --fx: -40px; --fy: -80px; }
-  .hf-antigravity { --x: min(300px, 19vw); --y: 20px; --s: 64px; --rot: -5deg; --d: 580ms; --fx: 40px; --fy: -80px; }
-  .hf-claude   { --x: max(-560px, -38vw); --y: 128px; --s: 96px; --rot: -8deg; --d: 380ms; --fx: -160px; --fy: -40px; --tint: rgba(217, 119, 87, 0.22); }
-  .hf-codex    { --x: min(560px, 38vw); --y: 128px; --s: 96px; --rot: 7deg; --d: 460ms; --fx: 160px; --fy: -40px; }
-  .hf-grok     { --x: max(-440px, -30vw); --y: 440px; --s: 80px; --rot: 4deg; --d: 540ms; --fx: -120px; --fy: 80px; }
-  .hf-cursor   { --x: min(440px, 30vw); --y: 440px; --s: 80px; --rot: -5deg; --d: 700ms; --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 { translate: none; transition: none; }
   }
 
   @media (max-width: 1180px) {
@@ -988,6 +1009,16 @@ const screenshot = await getImage({
     width: 7px; height: 14px;
     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 {
diff --git a/apps/mobile/README.md b/apps/mobile/README.md
index a8c2e8aef393..b6dbdad57daf 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/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/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/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/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/use-project-actions.ts b/apps/mobile/src/features/threads/use-project-actions.ts
index fe3916819240..bb0dce57ff71 100644
--- a/apps/mobile/src/features/threads/use-project-actions.ts
+++ b/apps/mobile/src/features/threads/use-project-actions.ts
@@ -156,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 08e939e9b4bd..0668efa30053 100644
--- a/apps/mobile/src/features/usage/UsageLimitsSection.tsx
+++ b/apps/mobile/src/features/usage/UsageLimitsSection.tsx
@@ -7,6 +7,7 @@ import type {
   ServerProviderResetCredits,
   ServerProviderUsageWindow,
   UsageLimitSourceAccount,
+  UsageProviderKind,
 } from "@t3tools/contracts";
 import {
   collectLimitSources,
@@ -22,30 +23,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 +74,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 +88,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 +110,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 +209,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 +217,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 +239,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 +269,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 +280,93 @@ function SourceAccountLimits(props: {
   );
 }
 
+/**
+ * Re-probes every provider (and usage-limit source) on each connected
+ * environment; the fresh snapshots then arrive over the config stream.
+ * Countdowns and pace anchor to `now` rather than ticking, so a refresh also
+ * re-anchors the clock: quota and elapsed time move together, or not at all.
+ * 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) => results[index]?._tag === "Failure")
+          .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[];
+}) {
+  const { now } = props;
   const presentations = useAtomValue(environmentPresentations.presentationsAtom);
   const groups = collectLimitsGroups(presentations);
   const sources = collectLimitSources(presentations);
-  // Anchored once per mount on purpose: countdowns must not tick.
-  const [now] = useState(() => 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 +389,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 6e913b4999d8..17841cbd74fa 100644
--- a/apps/mobile/src/features/usage/UsageRouteScreen.tsx
+++ b/apps/mobile/src/features/usage/UsageRouteScreen.tsx
@@ -17,26 +17,46 @@ 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 { 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),
@@ -45,6 +65,7 @@ export function UsageRouteScreen() {
   const { days: windowDays, window } = windowSelection;
   const isPast24Hours = windowDays === 1;
   const { merged, environments, isPending, isPartial, refresh } = useUsage(window);
+  const limits = useRefreshLimits();
 
   const days = useMemo(
     () => enumerateDays(window.sinceDay, window.untilDay),
@@ -73,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,
@@ -103,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}
-        />
-
-        <UsageCoverageNotice environments={environments} merged={merged} isPartial={isPartial} />
+        <SegmentedControl options={TAB_OPTIONS} selected={tab} onSelect={setTab} role="tab" />
 
-        {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>
@@ -151,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>
@@ -191,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;
@@ -203,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 ? (
@@ -262,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/attachmentUpload.ts b/apps/mobile/src/lib/attachmentUpload.ts
index 6c970a4fc08b..b6b5e3a8d635 100644
--- a/apps/mobile/src/lib/attachmentUpload.ts
+++ b/apps/mobile/src/lib/attachmentUpload.ts
@@ -33,8 +33,8 @@ 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`.
@@ -149,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 =
@@ -306,7 +304,6 @@ export async function prepareTurnAttachments(input: {
     attachments,
     draftAttachments,
     pendingAttachmentIds,
-    releaseUploads: () => releasePendingAttachmentUploads(environmentId, pendingAttachmentIds),
   });
 
   if (input.attachments.length === 0 || (files.length === 0 && !input.supportsImageUploads)) {
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/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 fe6fc55b776c..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,15 +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) => {
-        throw new ThreadOutboxManagerError({
-          operation: "clear-environment-load",
-          environmentId,
-          threadId: null,
-          messageId: null,
-          cause,
+      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,
+          });
         });
-      });
       const allMessages = flattenQueuedThreadMessages(
         groupQueuedThreadMessages([...persisted, ...currentMessages()]),
       );
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 7eae154c2762..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,20 +86,21 @@ export const expoThreadOutboxStorage: ThreadOutboxStorage = {
         try {
           messages.push(decodeQueuedThreadMessage(JSON.parse(await entry.text()) as unknown));
         } catch (cause) {
-          // A partial queue hides attachment owners from cleanup. Keep all
-          // records untouched until every persisted message can be read.
-          throw new ThreadOutboxStorageError({
-            operation: "read-message",
-            environmentId: null,
-            threadId: null,
-            messageId: null,
-            fileName: entry.name,
-            cause,
-          });
+          // Recover readable messages without treating their attachment
+          // owners as the complete inventory needed for cleanup.
+          errors.push(
+            new ThreadOutboxStorageError({
+              operation: "read-message",
+              environmentId: null,
+              threadId: null,
+              messageId: null,
+              fileName: entry.name,
+              cause,
+            }),
+          );
         }
       }
     } catch (cause) {
-      if (cause instanceof ThreadOutboxStorageError) throw cause;
       throw new ThreadOutboxStorageError({
         operation: "load",
         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 a4d89246c4c3..c426d552a7e7 100644
--- a/apps/mobile/src/state/thread-outbox.test.ts
+++ b/apps/mobile/src/state/thread-outbox.test.ts
@@ -13,8 +13,44 @@ 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 {
-    constructor(readonly name: string) {}
+    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);
@@ -26,13 +62,7 @@ vi.mock("expo-file-system", () => {
 
   return {
     File,
-    Directory: class {
-      create() {}
-
-      list() {
-        return Array.from(outboxFiles.keys(), (name) => new File(name));
-      }
-    },
+    Directory,
     Paths: { document: "/documents" },
   };
 });
@@ -52,7 +82,12 @@ import {
   type QueuedThreadMessage,
 } from "./thread-outbox-model";
 import { createThreadOutboxManager, ThreadOutboxManagerError } from "./thread-outbox-manager";
-import { expoThreadOutboxStorage, type ThreadOutboxStorage } from "./thread-outbox-storage";
+import {
+  expoThreadOutboxStorage,
+  ThreadOutboxStorageError,
+  type ThreadOutboxLoadResult,
+  type ThreadOutboxStorage,
+} from "./thread-outbox-storage";
 
 function queuedMessage(input: {
   readonly environmentId?: string;
@@ -73,7 +108,7 @@ function queuedMessage(input: {
 
 describe("thread outbox", () => {
   it.each(["read", "json", "schema"] as const)(
-    "does not load a partial outbox after a record %s failure",
+    "recovers usable messages without permitting cleanup after a record %s failure",
     async (failure) => {
       onTestFinished(() => outboxFiles.clear());
       const first = queuedMessage({
@@ -81,10 +116,11 @@ describe("thread outbox", () => {
         createdAt: "2026-06-08T10:00:01.000Z",
       });
       const second = queuedMessage({
+        environmentId: "environment-2",
         messageId: "message-2",
         createdAt: "2026-06-08T10:00:02.000Z",
       });
-      outboxFiles.set("message-1.json", JSON.stringify(encodeQueuedThreadMessage(first)));
+      // Put the unreadable record first to check that later records still load.
       outboxFiles.set(
         "message-2.json",
         failure === "read"
@@ -93,14 +129,52 @@ describe("thread outbox", () => {
             ? "{"
             : 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" }],
+      });
 
-      await expect(expoThreadOutboxStorage.load()).rejects.toMatchObject({
-        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(expoThreadOutboxStorage.load()).resolves.toEqual([first, 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: [],
+      });
     },
   );
 
@@ -138,6 +212,59 @@ describe("thread outbox", () => {
     });
   });
 
+  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",
@@ -335,7 +462,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => undefined,
         remove: async () => undefined,
       },
@@ -382,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) => {
@@ -418,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,
@@ -451,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);
       },
@@ -501,7 +628,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => writeBlocked,
         remove: async () => undefined,
       },
@@ -530,7 +657,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => {
           throw writeCause;
         },
@@ -561,7 +688,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => {
           throw new Error("disk full");
         },
@@ -593,7 +720,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => {
           if (failNextWrite) {
             failNextWrite = false;
@@ -630,7 +757,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async () => undefined,
         remove: async () => undefined,
       },
@@ -654,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);
       },
@@ -689,7 +816,7 @@ describe("thread outbox", () => {
     const manager = createThreadOutboxManager({
       registry,
       storage: {
-        load: async () => [],
+        load: async () => ({ messages: [], errors: [] }),
         write: async (message) => {
           writes.push(message.text);
         },
@@ -733,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") {
@@ -777,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);
         },
@@ -826,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();
@@ -876,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);
         },
@@ -915,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);
         },
@@ -979,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);
         },
@@ -1022,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 68d901546fef..e355e0e6dd7f 100644
--- a/apps/mobile/src/state/use-composer-drafts.test.ts
+++ b/apps/mobile/src/state/use-composer-drafts.test.ts
@@ -1748,7 +1748,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-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 651d6499c659..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);
       }
@@ -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;
     },
@@ -904,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 cde6a2782fcf..a3432d231d80 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/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 96e1c445c7dc..443e29cae956 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", () =>
@@ -759,7 +785,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)),
   );
@@ -818,7 +844,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/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 fa87c5ce4e84..1e2d5c60e9c9 100644
--- a/apps/server/src/auth/SessionStore.test.ts
+++ b/apps/server/src/auth/SessionStore.test.ts
@@ -5,6 +5,8 @@ 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";
 
@@ -44,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",
@@ -420,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 b315bdf87c7f..f4e5e3c487ac 100644
--- a/apps/server/src/auth/SessionStore.ts
+++ b/apps/server/src/auth/SessionStore.ts
@@ -482,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,
@@ -515,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,
@@ -525,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,
         }),
       );
     });
@@ -599,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(
@@ -882,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/cli/config.test.ts b/apps/server/src/cli/config.test.ts
index 93d95c414934..462a699a5a21 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/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/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/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 6d1a913a72cf..99ad409bd4a9 100644
--- a/apps/server/src/environment/ServerEnvironment.test.ts
+++ b/apps/server/src/environment/ServerEnvironment.test.ts
@@ -167,6 +167,7 @@ it.layer(NodeServices.layer)("ServerEnvironmentLive", (it) => {
       expect(second.capabilities.fileAttachments).toEqual({ maxUploadBytes: 50 * 1024 * 1024 });
       expect(second.capabilities.pullRequests).toBe(true);
       expect(second.capabilities.pullRequestSummary).toBe(true);
+      expect(second.capabilities.usagePriceOverrides).toBe(true);
       expect(second.capabilities.threadTitleRegeneration).toBe(true);
       expect(second.capabilities.threadPullRequestLinking).toBe(true);
       expect(second.capabilities.agentActivityPublishing).toBe(false);
diff --git a/apps/server/src/environment/ServerEnvironment.ts b/apps/server/src/environment/ServerEnvironment.ts
index df3380afab54..560b94462089 100644
--- a/apps/server/src/environment/ServerEnvironment.ts
+++ b/apps/server/src/environment/ServerEnvironment.ts
@@ -220,9 +220,11 @@ export const make = Effect.gen(function* () {
       pullRequestSummary: 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 7fe8ee8834f8..7677627b2c41 100644
--- a/apps/server/src/http.ts
+++ b/apps/server/src/http.ts
@@ -579,15 +579,20 @@ const handleStaticAndDevRequest = Effect.fn("handleStaticAndDevRequest")(
       }
     }
     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 =
-      /^assets\/.+-[\w-]{8}\.[^/]+$/.test(relativePath) && immutableBuildAssets.has(relativePath);
+      !isHtml &&
+      /^assets\/.+-[\w-]{8}\.[^/]+$/.test(relativePath) &&
+      immutableBuildAssets.has(relativePath);
     const headers: Record<string, string> = {
       "Cache-Control": immutable ? "public, max-age=31536000, immutable" : "no-cache",
     };
-    const modifiedAt = Option.getOrUndefined(fileInfo.mtime);
+    // 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;
@@ -612,17 +617,14 @@ const handleStaticAndDevRequest = Effect.fn("handleStaticAndDevRequest")(
         : ifModifiedSince !== undefined &&
           modifiedAt !== undefined &&
           Date.parse(modifiedAt.toUTCString()) <= Date.parse(ifModifiedSince);
-    if (unchanged) {
+    if (!isHtml && unchanged) {
       return HttpServerResponse.empty({
         status: 304,
         headers: { ...headers, Vary: "Accept-Encoding" },
       });
     }
 
-    const contentType =
-      path.extname(filePath) === ".html"
-        ? "text/html; charset=utf-8"
-        : (Mime.getType(filePath) ?? "application/octet-stream");
+    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), {
diff --git a/apps/server/src/keybindings.test.ts b/apps/server/src/keybindings.test.ts
index 6c32235c27f8..160755a8f9b2 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);
@@ -511,31 +512,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 031e17145ff5..1487cfdc57f6 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,
@@ -590,6 +591,244 @@ describe("CheckpointReactor", () => {
     }),
   );
 
+  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.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-untracked"),
+      payload: { reason: "Interrupted before the turn started." },
+    });
+    await harness.drain();
+
+    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(false);
+  });
+
   it("refreshes local git status state on turn completion using the session cwd", async () => {
     const gitStatusRefreshCalls: string[] = [];
     const harness = await createHarness({
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
index 6b29f0fee012..22a151224f6b 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
@@ -36,7 +36,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";
@@ -188,8 +187,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
@@ -199,7 +196,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,
@@ -220,15 +217,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;
@@ -363,9 +358,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;
@@ -422,75 +417,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);
@@ -758,7 +694,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,
@@ -896,25 +832,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* (
@@ -959,7 +876,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) =>
@@ -1007,8 +930,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/ProjectionPipeline.ts b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
index 1b4d92d3b956..05ad2d761c46 100644
--- a/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
+++ b/apps/server/src/orchestration/Layers/ProjectionPipeline.ts
@@ -1583,7 +1583,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,
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
index 19cab50f233c..bf1c059f7f81 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts
@@ -39,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";
@@ -181,7 +185,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";
@@ -1217,6 +1221,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;
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
index 559a9d6f4bce..73f65da488cb 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<
@@ -395,6 +397,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);
   };
 
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts
index 923e8c16f540..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,6 +20,7 @@ import {
   type OrchestrationCommand,
   ProjectId,
   ProviderItemId,
+  RuntimeRequestId,
   type ServerSettings,
   ThreadId,
   TurnId,
@@ -29,6 +31,7 @@ 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";
@@ -44,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";
@@ -257,9 +263,15 @@ 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(
@@ -284,6 +296,8 @@ 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)),
@@ -360,6 +374,12 @@ describe("ProviderRuntimeIngestion", () => {
       engine,
       dispatch,
       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,
@@ -2334,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 = {
@@ -3177,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 e480f7111407..12b1a93ba1cc 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
@@ -37,7 +37,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";
@@ -1003,7 +1005,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}`)),
@@ -1978,6 +1982,47 @@ const make = Effect.gen(function* () {
         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,
@@ -2061,7 +2106,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
@@ -2271,4 +2321,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.ts b/apps/server/src/orchestration/LiveStreamBudget.ts
index 3e3d3112859a..e86127b2b2df 100644
--- a/apps/server/src/orchestration/LiveStreamBudget.ts
+++ b/apps/server/src/orchestration/LiveStreamBudget.ts
@@ -93,7 +93,7 @@ export const makeLiveStreamBudget = Effect.fn("makeLiveStreamBudget")(function*
       return Effect.succeed(item);
     });
 
-  // Replace one coalescing batch atomically. Both raw and projected payloads
+  // 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>>,
diff --git a/apps/server/src/orchestration/ThreadLiveEventCoalescer.ts b/apps/server/src/orchestration/ThreadLiveEventCoalescer.ts
index c7f2155b4b38..2831746d3e3d 100644
--- a/apps/server/src/orchestration/ThreadLiveEventCoalescer.ts
+++ b/apps/server/src/orchestration/ThreadLiveEventCoalescer.ts
@@ -130,7 +130,7 @@ export const makeThreadLiveEventCoalescer = Effect.fn("makeThreadLiveEventCoales
         pendingUpdates,
         coalesceLiveToolUpdatedEvents(pendingUpdates.map((item) => item.value)).map((event) => ({
           kind: "event" as const,
-          event: projectActivityEvent(event),
+          event,
         })),
         (item) => item.event,
       );
@@ -167,7 +167,8 @@ export const makeThreadLiveEventCoalescer = Effect.fn("makeThreadLiveEventCoales
             Effect.gen(function* () {
               yield* budget.check;
               if (input.kind === "event") {
-                yield* budget.retain(input.event).pipe(
+                // 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,
                 );
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 fd6e11f86b15..56c5e7abc980 100644
--- a/apps/server/src/orchestration/projector.ts
+++ b/apps/server/src/orchestration/projector.ts
@@ -64,7 +64,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;
 }
 
@@ -749,7 +749,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 b47f148f0761..aebbb839e5ce 100644
--- a/apps/server/src/persistence/AuthSessions.ts
+++ b/apps/server/src/persistence/AuthSessions.ts
@@ -69,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;
 
@@ -282,7 +283,7 @@ export const make = Effect.gen(function* () {
   const listActiveSessionRows = SqlSchema.findAll({
     Request: ListActiveAuthSessionsInput,
     Result: AuthSessionRawDbRow,
-    execute: ({ now }) =>
+    execute: ({ now, connectedSessionIds = [] }) =>
       sql`
         SELECT
           session_id AS "sessionId",
@@ -301,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
       `,
   });
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/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/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..2f8654bd2514 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,72 @@ 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: yield* fs.realPath(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: yield* fs.realPath(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: yield* fs.realPath(externalExecutable),
+        });
+        expect(
+          yield* isolated.installation.resolve(executableName, { PATH: externalDirectory }),
+        ).toMatchObject({
+          source: "override",
+          executablePath: yield* fs.realPath(externalExecutable),
+        });
+      }),
   );
 
   it.effect("keeps leased releases available while new sessions resolve the new release", () =>
@@ -770,20 +792,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 +834,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 135ddda9899a..3b10a65c83a7 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";
 
 /**
@@ -136,4 +138,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 cd505e03a9e5..eeabb8ee119c 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/Drivers/AmpDriver.ts b/apps/server/src/provider/Drivers/AmpDriver.ts
index 2c37d6faba68..b257d4a66a00 100644
--- a/apps/server/src/provider/Drivers/AmpDriver.ts
+++ b/apps/server/src/provider/Drivers/AmpDriver.ts
@@ -114,7 +114,7 @@ export const AmpDriver: ProviderDriver<GenericProviderSettings, AmpDriverEnv> =
       );
 
       const snapshot = yield* makeManagedServerProvider<GenericProviderSettings>({
-        maintenanceCapabilities: MAINTENANCE_CAPABILITIES,
+        resolveMaintenance: () => Effect.succeed(MAINTENANCE_CAPABILITIES),
         getSettings: Effect.succeed(effectiveConfig),
         streamSettings: Stream.never,
         haveSettingsChanged: () => false,
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..56cb1cb06f08 100644
--- a/apps/server/src/provider/Drivers/ClaudeDriver.ts
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -48,6 +48,7 @@ import { withInstanceIdentity } from "./instanceIdentity.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
 import {
   enrichProviderSnapshotWithVersionAdvisory,
+  makeCachedProviderMaintenanceResolution,
   makePackageManagedProviderMaintenanceResolver,
   normalizeCommandPath,
   resolveProviderMaintenanceCapabilitiesEffect,
@@ -76,11 +77,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,
   },
 });
@@ -122,10 +120,16 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv> = {
         instanceId,
       });
       const effectiveConfig = { ...config, enabled } satisfies ClaudeSettings;
-      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 continuationGroupKey = yield* makeClaudeContinuationGroupKey(effectiveConfig);
       const stampIdentity = withInstanceIdentity({
         instanceId,
@@ -189,7 +193,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 +206,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 902e408724c6..55a507b77eae 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",
@@ -56,4 +64,10 @@ describe("planClaudeSkillDispatch", () => {
       skillName: "review",
     });
   });
+
+  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 27281643e8ae..9adc8164391f 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..2fb7f6badd5a
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CodexDriver.test.ts
@@ -0,0 +1,223 @@
+// @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 { layerTest as codexResetCreditLayerTest } from "../Layers/codexResetCredit.ts";
+import { NoOpProviderEventLoggers, ProviderEventLoggers } from "../Layers/ProviderEventLoggers.ts";
+import * as ModelManifest from "../ModelManifest.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-" })
+          .pipe(Effect.flatMap((directory) => fs.realPath(directory)));
+        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,
+      ),
+    );
+  }
+});
diff --git a/apps/server/src/provider/Drivers/CodexDriver.ts b/apps/server/src/provider/Drivers/CodexDriver.ts
index 04dad8d9c784..d7fd1e9c5698 100644
--- a/apps/server/src/provider/Drivers/CodexDriver.ts
+++ b/apps/server/src/provider/Drivers/CodexDriver.ts
@@ -55,7 +55,9 @@ import { withInstanceIdentity } from "./instanceIdentity.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
 import {
   enrichProviderSnapshotWithVersionAdvisory,
+  makeCachedProviderMaintenanceResolution,
   makePackageManagedProviderMaintenanceResolver,
+  normalizeCommandPath,
   resolveProviderMaintenanceCapabilitiesEffect,
 } from "../providerMaintenance.ts";
 import {
@@ -71,12 +73,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 +127,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;
@@ -138,10 +159,19 @@ export const CodexDriver: ProviderDriver<CodexSettings, CodexDriverEnv> = {
         enabled,
         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 +207,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 +220,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/CopilotDriver.ts b/apps/server/src/provider/Drivers/CopilotDriver.ts
index 22b7691f2fd2..87306444f256 100644
--- a/apps/server/src/provider/Drivers/CopilotDriver.ts
+++ b/apps/server/src/provider/Drivers/CopilotDriver.ts
@@ -121,7 +121,7 @@ export const CopilotDriver: ProviderDriver<CopilotSettings, CopilotDriverEnv> =
       );
 
       const snapshot = yield* makeManagedServerProvider<CopilotSettings>({
-        maintenanceCapabilities: MAINTENANCE_CAPABILITIES,
+        resolveMaintenance: () => Effect.succeed(MAINTENANCE_CAPABILITIES),
         getSettings: Effect.succeed(effectiveConfig),
         streamSettings: Stream.never,
         haveSettingsChanged: () => false,
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..06a2739c5197
--- /dev/null
+++ b/apps/server/src/provider/Drivers/CursorDriver.test.ts
@@ -0,0 +1,96 @@
+// @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)(
+    "keeps SDK updates manual even when a Cursor CLI executable exists",
+    () =>
+      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.packageName).toBe("@cursor/sdk");
+        expect(capabilities.update).toBeNull();
+        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 ae067b3392fd..49640f853ca7 100644
--- a/apps/server/src/provider/Drivers/CursorDriver.ts
+++ b/apps/server/src/provider/Drivers/CursorDriver.ts
@@ -32,10 +32,7 @@ import {
 } from "../ProviderDriver.ts";
 import { withInstanceIdentity } from "./instanceIdentity.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
-import {
-  makeManualOnlyProviderMaintenanceCapabilities,
-  makeStaticProviderMaintenanceResolver,
-} from "../providerMaintenance.ts";
+import { makeManualOnlyProviderMaintenanceCapabilities } from "../providerMaintenance.ts";
 import {
   haveProviderSnapshotSettingsChanged,
   makeProviderSnapshotSettingsSource,
@@ -48,12 +45,10 @@ const DRIVER_KIND = ProviderDriverKind.make("cursor");
 const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
 // The fork drives Cursor through @cursor/sdk rather than the `cursor-agent`
 // CLI, so updates stay manual instead of shelling out to `cursor-agent update`.
-const UPDATE = makeStaticProviderMaintenanceResolver(
-  makeManualOnlyProviderMaintenanceCapabilities({
-    provider: DRIVER_KIND,
-    packageName: "@cursor/sdk",
-  }),
-);
+const MAINTENANCE_CAPABILITIES = makeManualOnlyProviderMaintenanceCapabilities({
+  provider: DRIVER_KIND,
+  packageName: "@cursor/sdk",
+});
 
 export type CursorDriverEnv =
   | BackgroundPolicy.BackgroundPolicy
@@ -93,7 +88,7 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
         continuationGroupKey: continuationIdentity.continuationKey,
       });
       const effectiveConfig = { ...config, enabled } satisfies CursorSettings;
-      const maintenanceCapabilities = UPDATE.resolve();
+      const maintenanceCapabilities = MAINTENANCE_CAPABILITIES;
 
       const adapter = yield* makeCursorAdapter(effectiveConfig, {
         environment: processEnv,
@@ -108,7 +103,7 @@ export const CursorDriver: ProviderDriver<CursorSettings, CursorDriverEnv> = {
 
       const snapshotSettings = makeProviderSnapshotSettingsSource(effectiveConfig, serverSettings);
       const snapshot = yield* makeManagedServerProvider<ProviderSnapshotSettings<CursorSettings>>({
-        maintenanceCapabilities,
+        resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
         getSettings: snapshotSettings.getSettings,
         streamSettings: snapshotSettings.streamSettings,
         haveSettingsChanged: haveProviderSnapshotSettingsChanged,
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/DroidDriver.ts b/apps/server/src/provider/Drivers/DroidDriver.ts
index d5cbd52017a8..a9e23e2015fc 100644
--- a/apps/server/src/provider/Drivers/DroidDriver.ts
+++ b/apps/server/src/provider/Drivers/DroidDriver.ts
@@ -32,6 +32,7 @@ import type { ServerProviderDraft } from "../providerSnapshot.ts";
 import { mergeProviderInstanceEnvironment } from "../ProviderInstanceEnvironment.ts";
 import {
   enrichProviderSnapshotWithVersionAdvisory,
+  makeCachedProviderMaintenanceResolution,
   makePackageManagedProviderMaintenanceResolver,
   resolveProviderMaintenanceCapabilitiesEffect,
 } from "../providerMaintenance.ts";
@@ -42,7 +43,6 @@ const SNAPSHOT_REFRESH_INTERVAL = Duration.minutes(5);
 const UPDATE = makePackageManagedProviderMaintenanceResolver({
   provider: DRIVER_KIND,
   npmPackageName: "droid",
-  homebrewFormula: null,
   nativeUpdate: null,
 });
 
@@ -111,10 +111,16 @@ export const DroidDriver: ProviderDriver<DroidSettings, DroidDriverEnv> = {
         continuationGroupKey: continuationIdentity.continuationKey,
       });
       const effectiveConfig = { ...config, enabled } satisfies DroidSettings;
-      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, yield* FileSystem.FileSystem),
+          Effect.provideService(Path.Path, yield* Path.Path),
+        ),
+      );
 
       const adapter = yield* makeDroidAdapter(effectiveConfig, {
         instanceId,
@@ -125,7 +131,7 @@ export const DroidDriver: ProviderDriver<DroidSettings, DroidDriverEnv> = {
         Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
       );
       const snapshot = yield* makeManagedServerProvider<DroidSettings>({
-        maintenanceCapabilities,
+        resolveMaintenance,
         getSettings: Effect.succeed(effectiveConfig),
         streamSettings: Stream.never,
         haveSettingsChanged: () => false,
@@ -133,7 +139,10 @@ export const DroidDriver: ProviderDriver<DroidSettings, DroidDriverEnv> = {
           makePendingDroidProvider(settings).pipe(Effect.map(stampIdentity)),
         checkProvider,
         enrichSnapshot: ({ snapshot, publishSnapshot }) =>
-          enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities).pipe(
+          resolveMaintenance().pipe(
+            Effect.flatMap((maintenanceCapabilities) =>
+              enrichProviderSnapshotWithVersionAdvisory(snapshot, maintenanceCapabilities),
+            ),
             Effect.provideService(HttpClient.HttpClient, httpClient),
             Effect.flatMap((enrichedSnapshot) => publishSnapshot(enrichedSnapshot)),
           ),
diff --git a/apps/server/src/provider/Drivers/GeminiCliDriver.ts b/apps/server/src/provider/Drivers/GeminiCliDriver.ts
index 4ccc14905b30..db4917db2ca9 100644
--- a/apps/server/src/provider/Drivers/GeminiCliDriver.ts
+++ b/apps/server/src/provider/Drivers/GeminiCliDriver.ts
@@ -116,7 +116,7 @@ export const GeminiCliDriver: ProviderDriver<GenericProviderSettings, GeminiCliD
       );
 
       const snapshot = yield* makeManagedServerProvider<GenericProviderSettings>({
-        maintenanceCapabilities: MAINTENANCE_CAPABILITIES,
+        resolveMaintenance: () => Effect.succeed(MAINTENANCE_CAPABILITIES),
         getSettings: Effect.succeed(effectiveConfig),
         streamSettings: Stream.never,
         haveSettingsChanged: () => false,
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/KiloDriver.ts b/apps/server/src/provider/Drivers/KiloDriver.ts
index 7e5a8a6f6261..f945373d1962 100644
--- a/apps/server/src/provider/Drivers/KiloDriver.ts
+++ b/apps/server/src/provider/Drivers/KiloDriver.ts
@@ -114,7 +114,7 @@ export const KiloDriver: ProviderDriver<KiloSettings, KiloDriverEnv> = {
       );
 
       const snapshot = yield* makeManagedServerProvider<KiloSettings>({
-        maintenanceCapabilities: MAINTENANCE_CAPABILITIES,
+        resolveMaintenance: () => Effect.succeed(MAINTENANCE_CAPABILITIES),
         getSettings: Effect.succeed(effectiveConfig),
         streamSettings: Stream.never,
         haveSettingsChanged: () => false,
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/Drivers/StandardAcpCliDriver.ts b/apps/server/src/provider/Drivers/StandardAcpCliDriver.ts
index 9d439351f91a..3ab367045ed4 100644
--- a/apps/server/src/provider/Drivers/StandardAcpCliDriver.ts
+++ b/apps/server/src/provider/Drivers/StandardAcpCliDriver.ts
@@ -189,7 +189,7 @@ export function makeStandardAcpCliDriver<Settings extends StandardAcpCliSettings
           Effect.provideService(Path.Path, path),
         );
         const snapshot = yield* makeManagedServerProvider<StandardAcpCliProviderConfig>({
-          maintenanceCapabilities,
+          resolveMaintenance: () => Effect.succeed(maintenanceCapabilities),
           getSettings: Effect.succeed(providerConfig),
           streamSettings: Stream.never,
           haveSettingsChanged: () => false,
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..8982d525d9bc 100644
--- a/apps/server/src/provider/Layers/AntigravityAdapter.test.ts
+++ b/apps/server/src/provider/Layers/AntigravityAdapter.test.ts
@@ -1,3 +1,4 @@
+import { symlinksSupported } from "@t3tools/shared/testing/symlinks";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { expect, it } from "@effect/vitest";
 import {
@@ -421,7 +422,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",
@@ -1262,6 +1264,38 @@ it.layer(layer)("AntigravityAdapter", (it) => {
       }).pipe(Effect.flip);
       expect(escape._tag).toBe("AcpRequestError");
       expect(yield* fs.exists(path.join(outside, "escape.txt"))).toBe(false);
+      if (symlinksSupported) {
+        const linkedDirectory = path.join(cwd, "outside-link");
+        yield* fs.symlink(outside, linkedDirectory);
+        const linkedEscape = yield* write({
+          sessionId: nativeSessionId,
+          path: path.join(linkedDirectory, "missing", "escape.txt"),
+          content: "nope",
+        }).pipe(Effect.flip);
+        expect(linkedEscape._tag).toBe("AcpRequestError");
+        expect(yield* fs.exists(path.join(outside, "missing"))).toBe(false);
+        const outsideFile = path.join(outside, "existing.txt");
+        yield* fs.writeFileString(outsideFile, "unchanged");
+        const linkedFile = path.join(cwd, "file-link");
+        yield* fs.symlink(outsideFile, linkedFile);
+        expect(
+          (yield* write({ sessionId: nativeSessionId, path: linkedFile, content: "nope" }).pipe(
+            Effect.flip,
+          ))._tag,
+        ).toBe("AcpRequestError");
+        expect(
+          (yield* read({ sessionId: nativeSessionId, path: linkedFile }).pipe(Effect.flip))._tag,
+        ).toBe("AcpRequestError");
+        expect(yield* fs.readFileString(outsideFile)).toBe("unchanged");
+        const dangling = path.join(cwd, "dangling");
+        yield* fs.symlink(path.join(outside, "absent.txt"), dangling);
+        expect(
+          (yield* write({ sessionId: nativeSessionId, path: dangling, content: "nope" }).pipe(
+            Effect.flip,
+          ))._tag,
+        ).toBe("AcpRequestError");
+        expect(yield* fs.exists(path.join(outside, "absent.txt"))).toBe(false);
+      }
       const missing = yield* read({
         sessionId: nativeSessionId,
         path: path.join(cwd, "missing.txt"),
diff --git a/apps/server/src/provider/Layers/AntigravityAdapter.ts b/apps/server/src/provider/Layers/AntigravityAdapter.ts
index aa7d4c6a6755..aeff81f2caef 100644
--- a/apps/server/src/provider/Layers/AntigravityAdapter.ts
+++ b/apps/server/src/provider/Layers/AntigravityAdapter.ts
@@ -230,11 +230,51 @@ const resolveClientFilePath = Effect.fn("AntigravityAdapter.resolveClientFilePat
   }) {
     const { path } = input;
     const resolved = path.resolve(input.requestPath);
-    // Follow symlinks on the parent so a link out of the workspace cannot escape it.
-    const parent = yield* input.fileSystem
-      .realPath(path.dirname(resolved))
-      .pipe(Effect.orElseSucceed(() => path.dirname(resolved)));
-    const real = path.join(parent, path.basename(resolved));
+    // Resolve the target itself, or its nearest existing ancestor for new files.
+    // This also follows host aliases such as /var -> /private/var before adding
+    // missing directories, and rejects dangling symlinks instead of following
+    // them after the containment check.
+    let candidate = resolved;
+    const missingParts: Array<string> = [];
+    let real: string;
+    for (;;) {
+      const canonical = yield* input.fileSystem.realPath(candidate).pipe(
+        Effect.map(Option.some),
+        Effect.catch((error) =>
+          error.reason._tag === "NotFound"
+            ? Effect.succeed(Option.none<string>())
+            : Effect.fail(
+                EffectAcpErrors.AcpRequestError.invalidParams(
+                  `Cannot resolve '${input.requestPath}'.`,
+                ),
+              ),
+        ),
+      );
+      if (Option.isSome(canonical)) {
+        real = path.join(canonical.value, ...missingParts);
+        break;
+      }
+      const link = yield* input.fileSystem.readLink(candidate).pipe(
+        Effect.map(Option.some),
+        Effect.catch((error) =>
+          error.reason._tag === "NotFound"
+            ? Effect.succeed(Option.none<string>())
+            : Effect.fail(
+                EffectAcpErrors.AcpRequestError.invalidParams(
+                  `Cannot resolve '${input.requestPath}'.`,
+                ),
+              ),
+        ),
+      );
+      const parent = path.dirname(candidate);
+      if (Option.isSome(link) || parent === candidate) {
+        return yield* EffectAcpErrors.AcpRequestError.invalidParams(
+          `Cannot resolve '${input.requestPath}'.`,
+        );
+      }
+      missingParts.unshift(path.basename(candidate));
+      candidate = parent;
+    }
     const roots = yield* Effect.forEach(input.allowedRoots, (root) =>
       input.fileSystem.realPath(root).pipe(Effect.orElseSucceed(() => root)),
     );
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 4a8daa4b621c..60b61d01431a 100644
--- a/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeAdapter.test.ts
@@ -23,6 +23,7 @@ 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";
@@ -3489,10 +3490,14 @@ describe("ClaudeAdapterLive", () => {
     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 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,
@@ -3538,7 +3543,6 @@ describe("ClaudeAdapterLive", () => {
           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" },
@@ -3585,6 +3589,21 @@ describe("ClaudeAdapterLive", () => {
       ]) {
         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",
@@ -3642,15 +3661,15 @@ describe("ClaudeAdapterLive", () => {
         session_id: "session",
         uuid: "retry",
       } as unknown as SDKMessage);
-      yield* Effect.yieldNow;
-      yield* Effect.yieldNow;
+      const runtimeEvents = Array.from(yield* Fiber.join(runtimeEventsFiber));
 
       const warnings = runtimeEvents.filter((event) => event.type === "runtime.warning");
-      // Exactly three warnings: the high-priority notification, the
+      // 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.",
@@ -3678,6 +3697,528 @@ describe("ClaudeAdapterLive", () => {
           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: [] });
+
+      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;
+
+      assert.equal(runtimeEvents.filter((event) => event.type === "runtime.warning").length, 1);
+
+      runtimeEventsFiber.interruptUnsafe();
+    }).pipe(
+      Effect.provideService(Random.Random, makeDeterministicRandomService()),
+      Effect.provide(harness.layer),
+    );
+  });
+
+  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);
+
+      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: "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" }],
+        },
+      } as unknown as SDKMessage);
+      yield* drainSdkMessages;
+      harness.query.emit({ ...rejected, uuid: "rate-limit-synthetic-2" } as unknown as SDKMessage);
+      yield* drainSdkMessages;
+
+      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("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, 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, 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);
+      }
+      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: "rate_limit_event",
+          rate_limit_info: { status: "rejected", rateLimitType },
+          session_id: "sdk-session-unmapped-limit",
+          uuid: `rejected-${rateLimitType}`,
+        } as unknown as SDKMessage);
+      }
+      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: "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* drainSdkMessages;
+      assert.deepEqual(
+        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.",
+        ],
+      );
+      assert.equal(
+        runtimeEvents.filter((event) => event.type === "account.rate-limits.updated").length,
+        1,
+      );
       runtimeEventsFiber.interruptUnsafe();
     }).pipe(
       Effect.provideService(Random.Random, makeDeterministicRandomService()),
diff --git a/apps/server/src/provider/Layers/ClaudeAdapter.ts b/apps/server/src/provider/Layers/ClaudeAdapter.ts
index 2a4064fe4597..549a9a11eec1 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,
@@ -327,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;
 }
 
@@ -503,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);
 }
@@ -3662,6 +3714,14 @@ 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.
       // `background_tasks_changed` is a roster snapshot ({tasks: [...]}); the
@@ -3670,7 +3730,6 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
       // 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 "model_refusal_fallback":
       case "local_command_output":
       case "plugin_install":
       case "commands_changed":
@@ -3802,16 +3861,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;
     }
   });
@@ -4695,6 +4790,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
         lastKnownTotalProcessedTokens: undefined,
         lastAssistantUuid: resumeState?.resumeSessionAt,
         lastThreadStartedId: undefined,
+        announcedUsageLimits: undefined,
         stopped: false,
       };
       yield* Ref.set(contextRef, context);
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 c16fdfda153d..5beebee18759 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.test.ts
@@ -1877,6 +1877,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 bdee68387fba..d1981b33d47d 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.ts
@@ -787,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":
@@ -1325,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;
@@ -1334,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(
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/CursorProvider.test.ts b/apps/server/src/provider/Layers/CursorProvider.test.ts
index c795078ae2b1..445dbfbc1d02 100644
--- a/apps/server/src/provider/Layers/CursorProvider.test.ts
+++ b/apps/server/src/provider/Layers/CursorProvider.test.ts
@@ -153,11 +153,15 @@ describe("CursorProvider SDK", () => {
           parameters: [],
         },
       ],
-      ["custom-cursor"],
+      [
+        "custom-cursor",
+        { slug: "custom-named", name: "Named model", capabilities: { optionDescriptors: [] } },
+      ],
     );
     expect(models.map((model) => [model.slug, model.name, model.isCustom])).toEqual([
       ["composer-2.5", "Composer 2.5", false],
       ["custom-cursor", "custom-cursor", true],
+      ["custom-named", "Named model", true],
     ]);
   });
 
@@ -212,7 +216,24 @@ describe("CursorProvider SDK", () => {
 });
 
 describe("Cursor skills", () => {
-  it("discovers recursive project skills with project precedence", async () =>
+  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);
+    }
+  });
+  it("treats a symlinked skill outside the root as a package boundary", async () =>
     await runNode(
       Effect.gen(function* () {
         const fileSystem = yield* FileSystem.FileSystem;
@@ -221,10 +242,64 @@ describe("Cursor skills", () => {
           directory: NodeOS.tmpdir(),
           prefix: "cursor-skills-home-",
         });
-        const workspace = yield* fileSystem.makeTempDirectory({
+        const workspace = yield* fileSystem
+          .makeTempDirectory({
+            directory: NodeOS.tmpdir(),
+            prefix: "cursor-skills-workspace-",
+          })
+          .pipe(Effect.flatMap((directory) => fileSystem.realPath(directory)));
+        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("discovers recursive project skills with project precedence", 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-workspace-",
+          prefix: "cursor-skills-home-",
         });
+        const workspace = yield* fileSystem
+          .makeTempDirectory({
+            directory: NodeOS.tmpdir(),
+            prefix: "cursor-skills-workspace-",
+          })
+          .pipe(Effect.flatMap((directory) => fileSystem.realPath(directory)));
         const writeSkill = Effect.fn("writeCursorSkill")(function* (
           root: string,
           name: string,
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 93382f842231..fb0e9aa9ef2d 100644
--- a/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
+++ b/apps/server/src/provider/Layers/OpenCodeAdapter.test.ts
@@ -49,6 +49,7 @@ import {
   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>()(
@@ -6401,30 +6402,32 @@ 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", () =>
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 1fbfe9f9d844..189971bc0eed 100644
--- a/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
+++ b/apps/server/src/provider/Layers/ProviderInstanceRegistryLive.test.ts
@@ -24,6 +24,7 @@
  */
 import { describe, expect, it } from "@effect/vitest";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as Path from "effect/Path";
 import {
   type ClaudeSettings,
   type CodexSettings,
@@ -214,15 +215,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;
@@ -451,14 +456,16 @@ 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/.claude",
+        `claude:home:${(yield* Path.Path).resolve("/home/julius/.claude-work", ".claude")}`,
       );
 
       const cursorSnapshot = yield* cursor!.snapshot.getSnapshot;
diff --git a/apps/server/src/provider/Layers/ProviderRegistry.test.ts b/apps/server/src/provider/Layers/ProviderRegistry.test.ts
index 4c44556ddbbd..ee1830d0a0d6 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";
@@ -49,7 +50,11 @@ import {
 } 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";
@@ -351,6 +356,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) => {
@@ -909,6 +929,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"),
@@ -1100,10 +1300,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),
@@ -1192,10 +1395,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,
@@ -1381,10 +1587,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),
@@ -1405,10 +1614,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)),
@@ -1529,10 +1741,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),
@@ -1580,18 +1795,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,
@@ -1659,10 +1866,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),
@@ -1706,31 +1916,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, [
@@ -1767,10 +1969,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,
@@ -1861,10 +2066,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,
@@ -2558,9 +2766,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}/.claude`],
+            [(yield* Path.Path).resolve(claudeConfigDir, ".claude")],
           );
         }).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..2fd4278f3c57 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";
@@ -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 76f1c81a27da..0123cc3c0a7e 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 {
@@ -82,6 +84,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);
@@ -428,6 +440,7 @@ function makeProviderServiceLayer(
   const layer = it.layer(
     Layer.mergeAll(
       makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(defaultServerSettingsLayer),
@@ -455,6 +468,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();
@@ -480,6 +613,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),
@@ -522,6 +656,7 @@ it.effect("ProviderServiceLive flushes deferred completions 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),
@@ -658,6 +793,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),
@@ -741,6 +877,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const providerLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(providerAdapterLayer),
         Layer.provide(directoryLayer),
         Layer.provide(serverSettingsLayer),
@@ -810,6 +947,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),
@@ -928,7 +1066,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) {
@@ -982,6 +1120,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),
@@ -1102,6 +1241,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),
@@ -1167,6 +1307,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const firstProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
         ),
@@ -1194,7 +1335,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,
         });
@@ -1227,6 +1368,7 @@ it.effect(
         Layer.provide(runtimeRepositoryLayer),
       );
       const secondProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
         ),
@@ -1264,7 +1406,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);
       }
@@ -1278,6 +1420,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;
@@ -1337,7 +1534,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");
@@ -1407,7 +1604,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);
       }
@@ -1684,7 +1881,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);
@@ -1747,7 +1944,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",
       });
 
@@ -1826,7 +2023,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);
@@ -1852,7 +2049,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);
       }
@@ -1871,7 +2068,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",
       });
 
@@ -1906,7 +2103,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);
       }
@@ -1922,7 +2119,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",
       });
 
@@ -1938,7 +2135,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"));
       }
     }),
   );
@@ -1953,7 +2150,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({
@@ -1983,7 +2180,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",
       });
 
@@ -1994,7 +2191,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",
       });
 
@@ -2021,7 +2218,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",
       });
 
@@ -2046,7 +2243,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);
       }
@@ -2062,7 +2259,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",
@@ -2093,7 +2290,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", [
@@ -2257,6 +2454,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(runtimeRepositoryLayer),
       );
       const firstProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
         ),
@@ -2278,7 +2476,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));
@@ -2296,6 +2494,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
         Layer.provide(runtimeRepositoryLayer),
       );
       const secondProviderLayer = makeProviderServiceLive().pipe(
+        Layer.provide(NodeServices.layer),
         Layer.provide(
           Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
         ),
@@ -2319,7 +2518,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));
@@ -2335,7 +2534,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);
       }
@@ -2365,6 +2564,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           Layer.provide(runtimeRepositoryLayer),
         );
         const firstProviderLayer = makeProviderServiceLive().pipe(
+          Layer.provide(NodeServices.layer),
           Layer.provide(
             Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, firstRegistry),
           ),
@@ -2386,7 +2586,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));
@@ -2399,6 +2599,7 @@ routing.layer("ProviderServiceLive routing", (it) => {
           Layer.provide(runtimeRepositoryLayer),
         );
         const secondProviderLayer = makeProviderServiceLive().pipe(
+          Layer.provide(NodeServices.layer),
           Layer.provide(
             Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistry, secondRegistry),
           ),
@@ -2437,7 +2638,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);
         }
@@ -2631,7 +2832,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",
       });
 
@@ -2709,7 +2910,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",
         });
 
@@ -4048,7 +4249,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",
       });
 
@@ -4097,7 +4298,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 461f19952557..ab5748252766 100644
--- a/apps/server/src/provider/Layers/ProviderService.ts
+++ b/apps/server/src/provider/Layers/ProviderService.ts
@@ -35,6 +35,7 @@ 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";
@@ -55,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 {
   ProviderAdapterSendTurnInput,
   ProviderAdapterShape,
@@ -226,6 +231,7 @@ function toRuntimePayloadFromSession(
   session: ProviderSession,
   extra?: {
     readonly modelSelection?: unknown;
+    readonly continueAfterServerUpdate?: TurnId;
     readonly lastRuntimeEvent?: string;
     readonly lastRuntimeEventAt?: string;
   },
@@ -235,6 +241,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
@@ -321,6 +330,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>();
@@ -834,6 +844,7 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
     threadId: ThreadId,
     extra?: {
       readonly modelSelection?: unknown;
+      readonly continueAfterServerUpdate?: TurnId;
       readonly lastRuntimeEvent?: string;
       readonly lastRuntimeEventAt?: string;
     },
@@ -1233,6 +1244,20 @@ 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);
@@ -1438,6 +1463,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,
         },
@@ -1738,6 +1766,8 @@ const makeProviderService = Effect.fn("makeProviderService")(function* (
           status: "stopped",
           runtimePayload: {
             activeTurnId: null,
+            continueAfterServerUpdate: null,
+            continueAfterServerUpdatePrepared: null,
           },
         });
         yield* analytics.record("provider.session.stopped", {
@@ -1947,6 +1977,10 @@ 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) {
@@ -1974,6 +2008,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/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/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/cursor/CursorSdkMappings.ts b/apps/server/src/provider/cursor/CursorSdkMappings.ts
index aa925407f3c3..6b20e2cfe8ea 100644
--- a/apps/server/src/provider/cursor/CursorSdkMappings.ts
+++ b/apps/server/src/provider/cursor/CursorSdkMappings.ts
@@ -1,4 +1,5 @@
 import type {
+  CustomModelSetting,
   ModelCapabilities,
   ProviderOptionDescriptor,
   ProviderOptionSelection,
@@ -243,7 +244,7 @@ export function buildCursorCapabilitiesFromSdkModel(
 
 export function buildCursorDiscoveredModelsFromSdkModels(
   models: ReadonlyArray<CursorSdkModelListItem>,
-  customModels: ReadonlyArray<string> = [],
+  customModels: ReadonlyArray<CustomModelSetting> = [],
 ): ReadonlyArray<ServerProviderModel> {
   const seen = new Set<string>();
   const discovered = models.flatMap((model) => {
diff --git a/apps/server/src/provider/makeManagedServerProvider.test.ts b/apps/server/src/provider/makeManagedServerProvider.test.ts
index b47c812025c6..385532c146d9 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,
@@ -312,7 +312,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,
@@ -354,7 +354,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,
@@ -398,7 +398,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,
@@ -431,7 +431,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,
@@ -472,7 +472,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,
@@ -528,7 +528,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,
@@ -596,7 +596,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 5ec58ef22f82..0fe6665c4ecb 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/providerMaintenance.test.ts b/apps/server/src/provider/providerMaintenance.test.ts
index 5683da2c1a82..062dbaa9de4b 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,24 +9,35 @@ 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),
-    Effect.map((id) => NodePath.join(NodeOS.tmpdir(), `${name}-${id}`)),
+    Effect.map((id) => NodePath.join(NodeFS.realpathSync(NodeOS.tmpdir()), `${name}-${id}`)),
   );
 const isNativeTestCommandPath =
   (expectedPathSegment: string) =>
@@ -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,525 @@ 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.skipIf(!symlinksSupported)(
+    "upgrades the Homebrew cask that owns the binary and compares against its version",
     () =>
       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 caskBinary = NodePath.join(
+          tempDir,
+          "Caskroom",
+          "package-tool",
+          "0.148.0",
+          "package-tool",
+        );
+        writeExecutable(caskBinary);
+        const link = NodePath.join(tempDir, "bin", "package-tool");
+        NodeFS.mkdirSync(NodePath.dirname(link), { recursive: true });
+        NodeFS.symlinkSync(caskBinary, 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({ casks: [{ version: "0.148.0,42" }] });
+            }),
+          ),
+        );
+
+        expect(spawned).toEqual([
+          [brewPath, "--prefix"],
+          [brewPath, "info", "--json=v2", "package-tool"],
+        ]);
         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: "brew upgrade --cask package-tool",
+            executable: brewPath,
+            args: ["upgrade", "--cask", "package-tool"],
+            lockKey: "homebrew",
           },
         });
       }),
   );
 
-  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..d812f1ab7989 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,316 @@ 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;
+  const homebrew = homebrewOwnershipFromCommandPath(context.realCommandPath);
+  if (homebrew) {
+    const brewPath = yield* resolveCommandPath("brew", { env: context.env }).pipe(
+      Effect.catchTags({ CommandResolutionError: () => Effect.succeed(null) }),
+    );
+    if (!brewPath) {
+      return manual;
+    }
+    // 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 (
-      nativeUpdate &&
-      commandPaths.some((commandPath) => nativeUpdate.isCommandPath(commandPath))
+      !realBrewPrefix ||
+      normalizeCommandPath(realBrewPrefix) !== normalizeCommandPath(homebrew.prefix)
     ) {
-      return (
-        makeNativeProviderMaintenanceCapabilities(definition) ??
-        makeNpmGlobalProviderMaintenanceCapabilities(definition)
-      );
-    }
-    if (commandPaths.some(isVitePlusGlobalCommandPath)) {
-      return makeVitePlusGlobalProviderMaintenanceCapabilities(definition);
-    }
-    if (commandPaths.some(isBunGlobalCommandPath)) {
-      return makeBunGlobalProviderMaintenanceCapabilities(definition);
-    }
-    if (commandPaths.some(isPnpmGlobalCommandPath)) {
-      return makePnpmGlobalProviderMaintenanceCapabilities(definition);
-    }
-    if (commandPaths.some(isNpmGlobalCommandPath)) {
-      return makeNpmGlobalProviderMaintenanceCapabilities(definition);
-    }
-    if (commandPaths.some(isHomebrewCommandPath)) {
-      return makeHomebrewProviderMaintenanceCapabilities(definition);
+      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 +521,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 +654,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 4ac4401ffe27..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,7 +274,10 @@ 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",
           },
@@ -337,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(
@@ -351,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/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 c2ae3bf608fe..97dc7f7b409d 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/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 4a1961e5fb66..16d954f84cb0 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -199,6 +199,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");
@@ -1691,14 +1692,14 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       const fileSystem = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
       const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-static-cache-" });
-      const indexPath = path.join(staticDir, "index.html");
-      yield* fileSystem.writeFileString(indexPath, "<html>first build</html>");
+      const assetPath = path.join(staticDir, "app.js");
+      yield* fileSystem.writeFileString(assetPath, 'export const build = "first";');
       yield* buildAppUnderTest({ config: { staticDir } });
 
-      const initial = yield* HttpClient.get("/");
+      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 build");
+      assert.include(yield* initial.text, "first");
       const etag = initial.headers.etag;
       assert.isDefined(etag);
       assert.isDefined(initial.headers["last-modified"]);
@@ -1709,30 +1710,70 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         { "if-none-match": "*" },
         { "if-modified-since": initial.headers["last-modified"]! },
       ]) {
-        const response = yield* HttpClient.get("/", { headers });
+        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("/", {
+      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 build");
+      assert.include(yield* mismatched.text, "first");
 
-      yield* fileSystem.writeFileString(indexPath, "<html>the next build is available</html>");
-      const changed = yield* HttpClient.get("/", { headers: { "if-none-match": etag! } });
+      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;
@@ -1858,12 +1899,18 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       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;
@@ -1880,7 +1927,10 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
             ),
         open: (filePath, options) =>
           fileSystem
-            .open(filePath, options)
+            .open(
+              filePath === afterOpenPath && windowsHost ? afterOpenSnapshotPath : filePath,
+              options,
+            )
             .pipe(
               Effect.tap(() => (filePath === afterOpenPath ? replaceOnce(filePath) : Effect.void)),
             ),
@@ -1911,8 +1961,8 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       const fileSystem = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
       const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-static-close-" });
-      const filePath = path.join(staticDir, "index.html");
-      const body = "<p>file content</p>".repeat(1024);
+      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>();
@@ -1957,14 +2007,14 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
         Effect.provideService(FileSystem.FileSystem, trackedFileSystem),
       );
 
-      const get = yield* HttpClient.get("/");
+      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("/", { headers: { "accept-encoding": "gzip" } });
+      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, "");
@@ -1972,7 +2022,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       assert.equal(active.size, 0);
       assert.equal(bodyReads, readsAfterGet);
 
-      const unchanged = yield* HttpClient.get("/", {
+      const unchanged = yield* HttpClient.get("/app.txt", {
         headers: { "if-none-match": get.headers.etag! },
       });
       assert.equal(unchanged.status, 304);
@@ -1981,7 +2031,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       assert.equal(bodyReads, readsAfterGet);
 
       blockAfterOpen = true;
-      const cancelled = yield* HttpClient.get("/").pipe(Effect.forkChild);
+      const cancelled = yield* HttpClient.get("/app.txt").pipe(Effect.forkChild);
       yield* Deferred.await(blocked);
       assert.equal(active.size, 1);
       yield* Fiber.interrupt(cancelled);
@@ -6315,7 +6365,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;
@@ -7866,6 +7916,106 @@ 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: {
+              subscribeDomainEvents: Effect.succeed(
+                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]!;
@@ -8631,10 +8781,8 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
                   return;
                 }
                 assertTrue(threadResult._tag === "Success");
-                // Fork thread subscriptions still replay `thread.deleted` on
-                // catch-up so clients can drop local state without waiting for
-                // the shell `thread-removed` frame. Upstream only emits the
-                // synchronized marker here.
+                // The fork also delivers deletion to the detail subscriber so a
+                // cached thread is removed without waiting on the shell stream.
                 assert.deepEqual(threadResult.success, [
                   { kind: "event", event: deleted },
                   { kind: "synchronized" },
diff --git a/apps/server/src/serverRuntimeStartup.reconcile.test.ts b/apps/server/src/serverRuntimeStartup.reconcile.test.ts
index 31de4e11b4b7..b545d94d2d81 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,22 +11,28 @@ 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");
 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,
@@ -72,6 +79,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"];
@@ -96,7 +104,14 @@ const runReconciliation = (input: {
       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", () => {
@@ -137,7 +152,7 @@ it.effect("marks active running sessions that have persisted resume state", () =
       upsert: (binding) => Effect.sync(() => upserts.push(binding)),
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     }),
     Effect.tap((marked) =>
       Effect.sync(() => {
@@ -146,169 +161,186 @@ 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,
+              ),
             ),
+          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", () => {
@@ -360,7 +392,7 @@ it.effect("does not continue archived or deleted marked sessions", () => {
       upsert: () => Effect.void,
       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 })),
@@ -415,7 +447,7 @@ it.effect("retries continuation preparation before settling a persistent failure
       upsert: () => Effect.void,
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) => {
       if (command.type !== "thread.session.set") {
@@ -486,7 +518,7 @@ it.effect("reconciles multiple active and archived orphans but skips live sessio
       upsert: (binding) => Effect.sync(() => upserts.push(binding)),
       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 })),
@@ -520,6 +552,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 },
           );
@@ -564,7 +597,7 @@ it.effect(
         upsert: () => Effect.fail(writeFailure),
         getProvider: () => Effect.die("unused"),
         listThreadIds: () => Effect.die("unused"),
-        listBindings: () => Effect.die("unused"),
+        listBindings: () => Effect.succeed([]),
       },
       dispatch: (command) =>
         Effect.sync(() => dispatched.push(command)).pipe(
@@ -601,7 +634,7 @@ it.effect("retries failed projections and continues after a persistent failure",
       upsert: () => Effect.void,
       getProvider: () => Effect.die("unused"),
       listThreadIds: () => Effect.die("unused"),
-      listBindings: () => Effect.die("unused"),
+      listBindings: () => Effect.succeed([]),
     },
     dispatch: (command) => {
       if (command.type !== "thread.session.set") {
@@ -650,7 +683,7 @@ it.effect("does not fail startup when the live provider session inventory cannot
       upsert: () => 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,
@@ -661,7 +694,283 @@ it.effect("does not fail startup when the live provider session inventory cannot
       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);
+          }),
+        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);
+            }),
+          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;
+          }),
+        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.ts b/apps/server/src/serverRuntimeStartup.ts
index 064796b2810b..a34d1bdbde91 100644
--- a/apps/server/src/serverRuntimeStartup.ts
+++ b/apps/server/src/serverRuntimeStartup.ts
@@ -394,6 +394,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 +424,7 @@ const clearContinuationMarkers = (
                 runtimePayload: {
                   ...readRuntimePayload(binding.runtimePayload),
                   [SERVER_UPDATE_CONTINUATION_KEY]: null,
+                  continueAfterServerUpdatePrepared: null,
                 },
               }),
           }),
@@ -443,17 +445,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 +520,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 +551,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 +601,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 +613,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 +679,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);
         }),
       );
diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts
index 82ed8525b9b5..4526e2c988a4 100644
--- a/apps/server/src/serverSettings.test.ts
+++ b/apps/server/src/serverSettings.test.ts
@@ -272,6 +272,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* () {
diff --git a/apps/server/src/serviceLauncher.ts b/apps/server/src/serviceLauncher.ts
index 44ee6c94bff2..afd1fc842f69 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/terminal/Manager.test.ts b/apps/server/src/terminal/Manager.test.ts
index ad1865373254..b74ef83ed786 100644
--- a/apps/server/src/terminal/Manager.test.ts
+++ b/apps/server/src/terminal/Manager.test.ts
@@ -1687,6 +1687,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, {
diff --git a/apps/server/src/terminal/Manager.ts b/apps/server/src/terminal/Manager.ts
index 2070a50a9233..132f164d21ac 100644
--- a/apps/server/src/terminal/Manager.ts
+++ b/apps/server/src/terminal/Manager.ts
@@ -1274,6 +1274,10 @@ function createTerminalSpawnEnv(
       scrubbed[key] = value;
     }
   }
+  // Both PTY backends feed truecolor-capable terminal clients.
+  if (scrubbed.COLORTERM === undefined || scrubbed.COLORTERM === "") {
+    scrubbed.COLORTERM = "truecolor";
+  }
   return scrubbed;
 }
 
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 669104419582..b8f3345377e2 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..742515de65bc 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;
   },
@@ -199,7 +142,10 @@ function withFakeCodexEnv<A, E, R>(
     const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-codex-text-" });
     const codexPath = yield* makeFakeCodexBinary(tempDir, input);
     const config = decodeCodexSettings({ binaryPath: codexPath, launchArgs: input.launchArgs });
-    const textGeneration = yield* makeCodexTextGeneration(config, input.environment);
+    const textGeneration = yield* makeCodexTextGeneration(
+      config,
+      input.environment ? { ...process.env, ...input.environment } : undefined,
+    );
     return yield* effectFn(textGeneration);
   }).pipe(Effect.scoped);
 }
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/usage/UsageService.test.ts b/apps/server/src/usage/UsageService.test.ts
index 63b74510e29e..9d728c88cf42 100644
--- a/apps/server/src/usage/UsageService.test.ts
+++ b/apps/server/src/usage/UsageService.test.ts
@@ -9,9 +9,11 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { HostProcessEnvironment } from "@t3tools/shared/hostProcess";
 import { UsageDay, 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";
@@ -21,7 +23,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",
@@ -29,7 +31,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`;
@@ -96,6 +98,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;
@@ -114,6 +159,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 7c446ae14f96..0e6b0c1eecd6 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,
@@ -44,7 +45,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,
@@ -232,24 +233,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);
@@ -379,10 +378,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));
@@ -406,7 +410,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",
@@ -455,9 +462,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,
@@ -466,6 +474,7 @@ export const make = Effect.gen(function* () {
       resolution: input.resolution ?? "day",
       ...hourlyWindow,
       rates,
+      priceOverrides: createOverrideRateTable(settings.usagePriceOverrides),
     });
 
     const sources: UsageSource[] = [];
@@ -547,13 +556,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,
@@ -561,10 +573,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);
@@ -576,7 +590,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..d45dfe2dd09b 100644
--- a/apps/server/src/usage/usagePricing.test.ts
+++ b/apps/server/src/usage/usagePricing.test.ts
@@ -1,6 +1,13 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import { lookupRate, normalizeModelName, parseRateTable } from "./usagePricing.ts";
+import {
+  cacheSavingsUsd,
+  createOverrideRateTable,
+  lookupRate,
+  normalizeModelName,
+  parseRateTable,
+  priceUsage,
+} from "./usagePricing.ts";
 
 const rate = (input: number, cacheRead?: number) => ({
   input_cost_per_token: input,
@@ -9,6 +16,73 @@ const rate = (input: number, cacheRead?: number) => ({
 });
 
 describe("usage pricing", () => {
+  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 existing model-name normalization contract", () => {
     expect(normalizeModelName(" Anthropic/Claude-Opus-5 ")).toBe("claude-opus-5");
   });
diff --git a/apps/server/src/usage/usagePricing.ts b/apps/server/src/usage/usagePricing.ts
index a7beecb1f552..5ca75a68cb32 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;
@@ -168,12 +191,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 +214,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/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/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/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 a756688c190c..64670342f454 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,
@@ -725,19 +725,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":
@@ -746,11 +760,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());
@@ -864,13 +878,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);
           }
@@ -893,16 +907,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 = (
@@ -910,7 +925,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") {
@@ -1438,6 +1453,7 @@ const makeWsRpcLayer = (
               const liveStream = yield* orchestrationEngine.subscribeDomainEvents;
               yield* Effect.forkScoped(
                 liveStream.pipe(
+                  Stream.map(toShellEvent),
                   Stream.runForEach((event) =>
                     liveBudget.retain({ kind: "event" as const, event }, event).pipe(
                       Effect.flatMap((item) => Queue.offer(liveBuffer, item)),
diff --git a/apps/server/vite.config.ts b/apps/server/vite.config.ts
index 86841304b569..3007072a2b1c 100644
--- a/apps/server/vite.config.ts
+++ b/apps/server/vite.config.ts
@@ -97,6 +97,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/src/appSettings.ts b/apps/web/src/appSettings.ts
index e5e808e21453..5186aaed5e51 100644
--- a/apps/web/src/appSettings.ts
+++ b/apps/web/src/appSettings.ts
@@ -1,3 +1,4 @@
+import { readCustomModelSlugs } from "@t3tools/shared/model";
 import { useCallback, useMemo } from "react";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
@@ -284,14 +285,14 @@ function withUnifiedCompatSettings(
     sidebarProjectSortOrder: unifiedSettings.sidebarProjectSortOrder,
     sidebarThreadSortOrder: unifiedSettings.sidebarThreadSortOrder,
     timestampFormat: unifiedSettings.timestampFormat,
-    customCodexModels: [...unifiedSettings.providers.codex.customModels],
-    customCopilotModels: [...unifiedSettings.providers.copilot.customModels],
-    customClaudeModels: [...unifiedSettings.providers.claudeAgent.customModels],
-    customCursorModels: [...unifiedSettings.providers.cursor.customModels],
-    customOpencodeModels: [...unifiedSettings.providers.opencode.customModels],
-    customGeminiCliModels: [...unifiedSettings.providers.geminiCli.customModels],
-    customAmpModels: [...unifiedSettings.providers.amp.customModels],
-    customKiloModels: [...unifiedSettings.providers.kilo.customModels],
+    customCodexModels: readCustomModelSlugs(unifiedSettings.providers.codex.customModels),
+    customCopilotModels: readCustomModelSlugs(unifiedSettings.providers.copilot.customModels),
+    customClaudeModels: readCustomModelSlugs(unifiedSettings.providers.claudeAgent.customModels),
+    customCursorModels: readCustomModelSlugs(unifiedSettings.providers.cursor.customModels),
+    customOpencodeModels: readCustomModelSlugs(unifiedSettings.providers.opencode.customModels),
+    customGeminiCliModels: readCustomModelSlugs(unifiedSettings.providers.geminiCli.customModels),
+    customAmpModels: readCustomModelSlugs(unifiedSettings.providers.amp.customModels),
+    customKiloModels: readCustomModelSlugs(unifiedSettings.providers.kilo.customModels),
   });
 }
 
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/components/AppSidebarLayout.tsx b/apps/web/src/components/AppSidebarLayout.tsx
index 834e1d0efeda..4a4f8faf181f 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";
@@ -143,6 +147,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);
@@ -211,42 +217,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 18a6c5115eeb..f4551a93088e 100644
--- a/apps/web/src/components/ChatMarkdown.test.tsx
+++ b/apps/web/src/components/ChatMarkdown.test.tsx
@@ -72,7 +72,82 @@ function codeButton(renderer: ReactTestRenderer, label: string) {
   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");
@@ -262,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 deaa68ebdaee..614c404d978e 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,
@@ -1133,16 +1134,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}
@@ -2871,7 +2873,10 @@ const CHAT_MARKDOWN_COMPONENTS = {
         fenceTitle={fenceTitle}
         theme={resolvedTheme}
       >
-        <RenderErrorBoundary fallback={<pre {...props}>{children}</pre>}>
+        <RenderErrorBoundary
+          resetKeys={[codeBlock.code, language, diffThemeName, isStreaming]}
+          fallback={<pre {...props}>{children}</pre>}
+        >
           <Suspense fallback={<pre {...props}>{children}</pre>}>
             <SuspenseShikiCodeBlock
               className={codeBlock.className}
diff --git a/apps/web/src/components/ChatView.logic.test.ts b/apps/web/src/components/ChatView.logic.test.ts
index c8afd10d3725..c67ea3f3d5c3 100644
--- a/apps/web/src/components/ChatView.logic.test.ts
+++ b/apps/web/src/components/ChatView.logic.test.ts
@@ -41,6 +41,7 @@ import {
   resolveComposerInteractionMode,
   resolveComposerProviderSelection,
   resolveDraftPromotionNavigationTarget,
+  resolveProactiveTurnDiffAction,
   resolveThreadMetadataUpdateForNextTurn,
   resolveSendEnvMode,
   resolveDraftHeroState,
@@ -159,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", () => {
diff --git a/apps/web/src/components/ChatView.logic.ts b/apps/web/src/components/ChatView.logic.ts
index 4a0b9f576103..10c2fd4710ee 100644
--- a/apps/web/src/components/ChatView.logic.ts
+++ b/apps/web/src/components/ChatView.logic.ts
@@ -121,6 +121,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,
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 620ff57aaed3..71f895d1a8fc 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -1,7 +1,6 @@
 import {
   type AssistantCitation,
   type ApprovalRequestId,
-  type AssetResource,
   type ChatFileAttachment,
   DEFAULT_MODEL,
   type EnvironmentId,
@@ -105,6 +104,7 @@ import {
   deriveWorkLogEntries,
   hasActionableProposedPlan,
   isLatestTurnSettled,
+  selectHandoffImageResources,
   type TimelineEntriesProjection,
 } from "../session-logic";
 import { type LegendListRef } from "@legendapp/list/react";
@@ -222,6 +222,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";
@@ -386,6 +387,7 @@ import {
   resolveComposerInteractionMode,
   resolveComposerProviderSelection,
   resolveDraftHeroState,
+  resolveProactiveTurnDiffAction,
   resolveThreadMetadataUpdateForNextTurn,
   resolveSendEnvMode,
   revokeBlobPreviewUrl,
@@ -444,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"] = [];
@@ -2768,40 +2769,20 @@ export default function ChatView(props: ChatViewProps) {
     },
     [activeThreadRef, downloadFileAttachment],
   );
-  const serverAttachmentResources = useMemo(() => {
-    const resources = new Map<string, Extract<AssetResource, { readonly _tag: "attachment" }>>();
-    for (const message of serverMessages ?? []) {
-      for (const attachment of message.attachments ?? []) {
-        if (resources.has(attachment.id)) continue;
-        resources.set(
-          attachment.id,
-          attachment.type === "file"
-            ? {
-                _tag: "attachment",
-                attachmentId: attachment.id,
-                fileName: attachment.name,
-                mimeType: attachment.mimeType,
-              }
-            : { _tag: "attachment", attachmentId: attachment.id },
-        );
-      }
-    }
-    return [...resources.values()];
-  }, [serverMessages]);
-  const serverAttachmentIds = useMemo(
-    () => serverAttachmentResources.map((resource) => resource.attachmentId),
-    [serverAttachmentResources],
+  const serverAttachmentResources = useMemo(
+    () => 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 [];
@@ -3946,18 +3927,21 @@ export default function ChatView(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");
@@ -3969,6 +3953,7 @@ export default function ChatView(props: ChatViewProps) {
     activeRunningTurnId,
     activeThreadKey,
     activeThreadRef,
+    activeRightPanelSurface?.kind,
     clientSettingsHydrated,
     gitStatusQuery.data?.isRepo,
     isServerThread,
@@ -4821,6 +4806,10 @@ export default function ChatView(props: ChatViewProps) {
     requestAnimationFrame(() => positionAnchor(12));
   }, []);
 
+  const onToolOutputCollapsedAtEnd = useCallback(() => {
+    composerRef.current?.restoreAfterTimelineReachedEnd();
+  }, []);
+
   const onIsAtEndChange = useCallback((isAtEnd: boolean) => {
     if (
       !isAtEnd &&
@@ -5137,16 +5126,24 @@ export default function ChatView(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;
@@ -7896,6 +7893,7 @@ export default function ChatView(props: ChatViewProps) {
                 contentInsetEndAdjustment={composerTimelineInset}
                 liveFollowEnabled={timelineLiveFollowEnabled}
                 onIsAtEndChange={onIsAtEndChange}
+                onToolOutputCollapsedAtEnd={onToolOutputCollapsedAtEnd}
                 onManualNavigation={cancelTimelineLiveFollowForUserNavigation}
                 hideEmptyPlaceholder={isDraftHeroState || threadDetailLoading}
                 topFadeEnabled={!hasTimelineTopBanner}
@@ -7986,6 +7984,7 @@ export default function ChatView(props: ChatViewProps) {
                             activeThreadId={activeThreadId}
                             activeThreadEnvironmentId={activeThread?.environmentId}
                             activeThread={activeThread}
+                            promptHistoryMessages={timelineMessages}
                             isServerThread={isServerThread}
                             isLocalDraftThread={isLocalDraftThread}
                             forceExpandedOnMobile={forceExpandedMobileComposer && isDraftHeroState}
diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index a7403d952f2b..fcb08822f4bd 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -71,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";
@@ -510,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}
@@ -632,11 +636,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,
         });
@@ -2291,19 +2299,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 9066bee077c7..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],
   );
diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index bad0e1b4ffe0..87f5f1ba56f8 100644
--- a/apps/web/src/components/DiffPanel.tsx
+++ b/apps/web/src/components/DiffPanel.tsx
@@ -800,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];
@@ -810,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>
diff --git a/apps/web/src/components/DiffWorkerPoolProvider.tsx b/apps/web/src/components/DiffWorkerPoolProvider.tsx
index 0f497a24cf5d..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, useState, 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();
 
@@ -49,16 +97,17 @@ function DiffWorkerThemeSync({ themeName }: { themeName: DiffThemeName }) {
 // 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 [ready, setReady] = useState(
-    () => !workerPool || workerPool.isInitialized() || !workerPool.isWorkingPool(),
-  );
+  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) setReady(true);
+      if (mounted) setReadyPool(workerPool);
     };
     // Failed pools use Pierre's existing main-thread highlighter.
     void workerPool.initialize().then(finish, finish);
@@ -87,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} />
       <DiffWorkerReady>{children}</DiffWorkerReady>
-    </WorkerPoolContextProvider>
+    </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 19dd902c9a60..f751a04f32d1 100644
--- a/apps/web/src/components/LegacySidebar.tsx
+++ b/apps/web/src/components/LegacySidebar.tsx
@@ -172,7 +172,7 @@ import {
   useSidebar,
 } from "./ui/sidebar";
 import { useThreadSelectionStore } from "../threadSelectionStore";
-import { openCommandPalette } from "../commandPaletteBus";
+import { isCommandPaletteOpen, openCommandPalette } from "../commandPaletteBus";
 import {
   archiveSelectedThreadEntries,
   buildMultiSelectThreadContextMenuItems,
@@ -3516,7 +3516,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.ts b/apps/web/src/components/ProviderUpdateLaunchNotification.logic.ts
index ea853d4e553d..6d6cdccad886 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>,
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 62204d9d4a31..bf3d37d0edc2 100644
--- a/apps/web/src/components/Sidebar.logic.test.ts
+++ b/apps/web/src/components/Sidebar.logic.test.ts
@@ -29,6 +29,7 @@ import {
   formatWorkingDurationLabel,
   shouldNavigateAfterProjectRemoval,
   shouldClearThreadSelectionOnMouseDown,
+  shouldRecedeSidebarThread,
   sortLogicalProjectsForSidebar,
   sortSettledThreadsForSidebar,
   pinOrderKeyBetween,
@@ -295,6 +296,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();
diff --git a/apps/web/src/components/Sidebar.logic.ts b/apps/web/src/components/Sidebar.logic.ts
index 6a2d44da1a79..8e88aea37f4c 100644
--- a/apps/web/src/components/Sidebar.logic.ts
+++ b/apps/web/src/components/Sidebar.logic.ts
@@ -532,6 +532,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"
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index f2e50cebcb9d..9a355c4fc683 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -109,14 +109,18 @@ import { legacyProjectCwdPreferenceKey, useUiStateStore } from "../uiStateStore"
 import { 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 {
+  useAllEnvironmentProjectSnapshotsReady,
+  useProjects,
+  useThreadShells,
+} from "../state/entities";
 import { environmentServerConfigsAtom, primaryServerKeybindingsAtom } from "../state/server";
 import { vcsEnvironment } from "../state/vcs";
 import { threadEnvironment } from "../state/threads";
@@ -149,6 +153,7 @@ import {
   resolveSidebarThreadStatus,
   searchSidebarThreadsByTitle,
   shouldCreateNewThreadInCurrentProject,
+  shouldRecedeSidebarThread,
   resolveWorkingStartedAt,
   sortLogicalProjectsForSidebar,
   sortPinnedThreadsForSidebar,
@@ -879,6 +884,8 @@ const SidebarV2Row = memo(function SidebarV2Row(props: {
   // flag 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:
@@ -892,17 +899,16 @@ const SidebarV2Row = memo(function SidebarV2Row(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.
@@ -1215,21 +1221,23 @@ const SidebarV2Row = memo(function SidebarV2Row(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/v2-row:text-foreground",
-              props.isActive || isWoke
-                ? "text-foreground"
-                : isUnread
-                  ? "text-muted-foreground"
-                  : "text-secondary-label/70",
+              "truncate group-hover/sidebar-row:text-foreground",
+              shouldRecede
+                ? "text-secondary-label/70"
+                : props.isActive || isWoke
+                  ? "text-foreground"
+                  : isUnread
+                    ? "text-muted-foreground"
+                    : "text-secondary-label/70",
             ),
         isRegeneratingTitle && "opacity-[0.55]",
       )}
@@ -2141,7 +2149,11 @@ export default function SidebarV2() {
 
   // 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(
@@ -2205,11 +2217,15 @@ export default function SidebarV2() {
           ),
     [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
@@ -2254,10 +2270,18 @@ export default function SidebarV2() {
     },
     [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);
     },
@@ -3540,7 +3564,9 @@ export default function SidebarV2() {
   );
   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: {
@@ -3757,10 +3783,18 @@ export default function SidebarV2() {
                   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);
                   }}
@@ -3811,6 +3845,24 @@ export default function SidebarV2() {
                           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",
@@ -3831,6 +3883,9 @@ export default function SidebarV2() {
                             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
@@ -3849,7 +3904,8 @@ export default function SidebarV2() {
                               <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.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index 89cdc3649acd..9f4956aae682 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -516,7 +516,10 @@ export function TerminalViewport({
       // never started, so only "exited" triggers the message — as with xterm.)
       synchronizedStatusRef.current = "closed";
       synchronizeTerminalStatus(terminal, latestSession.status);
-      if (autoFocus && visibleRef.current) 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 =
@@ -870,10 +873,10 @@ 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(() => {
@@ -904,24 +907,14 @@ export function TerminalViewport({
       writeSystemMessage(terminal, current.error);
     }
 
-    if (previous.version === 0 && autoFocus && visibleRef.current) {
-      window.requestAnimationFrame(() => {
-        terminal.focus();
-      });
-    }
     previousSessionRef.current = current;
-  }, [autoFocus, terminalOutput, terminalError, terminalStatus, terminalVersion]);
+  }, [terminalOutput, terminalError, terminalStatus, terminalVersion]);
 
   useEffect(() => {
     if (!autoFocus || !visible) return;
-    const terminal = terminalRef.current;
-    if (!terminal) return;
-    const frame = window.requestAnimationFrame(() => {
-      terminal.focus();
-    });
-    return () => {
-      window.cancelAnimationFrame(frame);
-    };
+    // 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(() => {
@@ -944,6 +937,7 @@ export function TerminalViewport({
   return (
     <div
       ref={containerRef}
+      tabIndex={-1}
       className="relative h-full w-full overflow-hidden bg-[var(--terminal-background)]"
     />
   );
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 eb6debc7db13..9e2b99179ce9 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,
@@ -798,7 +799,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";
@@ -1076,7 +1082,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;
@@ -1143,6 +1149,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;
@@ -1283,6 +1291,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     activeThreadId,
     activeThreadEnvironmentId: _activeThreadEnvironmentId,
     activeThread,
+    promptHistoryMessages,
     isServerThread: _isServerThread,
     isLocalDraftThread: _isLocalDraftThread,
     forceExpandedOnMobile,
@@ -1752,6 +1761,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,
   );
@@ -1759,8 +1770,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,
@@ -1772,7 +1789,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 =
@@ -2323,7 +2339,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
@@ -2474,7 +2490,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       COMPOSER_SCROLL_GESTURE_RESET_MS,
     );
     setIsComposerScrollCollapsed(false);
-  }, []);
+  }, [setIsComposerScrollCollapsed]);
 
   const onPromptChange = useCallback(
     (
@@ -2502,6 +2518,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,
@@ -2761,7 +2783,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       activeElement.blur();
     }
     setIsComposerFocused(false);
-  }, [isMobileViewport]);
+  }, [isMobileViewport, setIsComposerFocused]);
 
   const shouldBlurMobileComposerOnSubmit = useCallback(() => {
     if (!isMobileViewport) return false;
@@ -2921,7 +2943,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
@@ -2953,6 +3054,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({
@@ -3659,7 +3763,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
@@ -3748,6 +3852,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
     canTrackComposerScrollGesture,
     getTimelineScrollableNode,
     isTimelineAtLogicalEnd,
+    setIsComposerScrollCollapsed,
   ]);
 
   const restingHiddenBlockCount = composerControlsInStrip ? restingControlsHiddenBlockCount : 0;
@@ -4342,7 +4447,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.
@@ -4434,7 +4539,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       }
       desktopOutsidePointerInFlightRef.current = false;
     };
-  }, [isComposerFocused, isMobileViewport, scheduleComposerCollapseCheck]);
+  }, [isComposerFocused, isMobileViewport, scheduleComposerCollapseCheck, setIsComposerFocused]);
 
   useEffect(() => {
     return () => {
@@ -4463,7 +4568,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       setIsComposerFocused(true);
     }
     setIsComposerModelPickerOpen(true);
-  }, [composerControlsHidden]);
+  }, [composerControlsHidden, setIsComposerFocused, setIsComposerScrollCollapsed]);
 
   useImperativeHandle(
     composerRef,
@@ -4474,9 +4579,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();
@@ -4620,6 +4723,7 @@ export const ChatComposer = memo(function ChatComposer(props: ChatComposerProps)
       interactionMode,
       planModeUiEnabled,
       compactThreadContext,
+      restoreAfterTimelineReachedEnd,
     ],
   );
 
diff --git a/apps/web/src/components/chat/ComposerActivityStatus.tsx b/apps/web/src/components/chat/ComposerActivityStatus.tsx
index 3d6f5b763b95..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 />
+      <ComposerBanner.Icon ref={observeVisibleAnimation}>
+        <LoaderCircleIcon className="motion-safe:visible-animate-spin" />
       </ComposerBanner.Icon>
       <ComposerBanner.Content>
         <span
diff --git a/apps/web/src/components/chat/ComposerServerUpdateStatus.tsx b/apps/web/src/components/chat/ComposerServerUpdateStatus.tsx
index 60a998cbeab9..4c5aa60ff06a 100644
--- a/apps/web/src/components/chat/ComposerServerUpdateStatus.tsx
+++ b/apps/web/src/components/chat/ComposerServerUpdateStatus.tsx
@@ -2,6 +2,7 @@ import type { ServerUpdateState } from "@t3tools/client-runtime/state/server";
 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,7 +13,13 @@ export function ComposerServerUpdateIcon({
   readonly status: ServerUpdateState["status"];
 }) {
   if (status === "running") {
-    return <LoaderCircleIcon aria-hidden />;
+    return (
+      <LoaderCircleIcon
+        aria-hidden
+        ref={observeVisibleAnimation}
+        className="motion-safe:visible-animate-spin"
+      />
+    );
   }
   if (status === "failed") {
     return <CircleAlertIcon aria-hidden className="text-error" />;
diff --git a/apps/web/src/components/chat/MessagesTimeline.test.tsx b/apps/web/src/components/chat/MessagesTimeline.test.tsx
index b3448d7d88b7..6c3e9dbe6111 100644
--- a/apps/web/src/components/chat/MessagesTimeline.test.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.test.tsx
@@ -1,9 +1,18 @@
 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";
+import { useAssetUrls } from "../../assets/assetUrls";
+
+vi.mock("../../assets/assetUrls", async (importOriginal) => {
+  const original = await importOriginal<typeof import("../../assets/assetUrls")>();
+  return { ...original, useAssetUrls: vi.fn(original.useAssetUrls) };
+});
 
 vi.mock("@legendapp/list/react", async () => {
   const legendListTestId = "legend-list";
@@ -237,6 +246,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"),
@@ -379,9 +475,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");
   });
@@ -732,6 +827,59 @@ describe("MessagesTimeline", () => {
     ).not.toContain('data-maintain-scroll-at-end="enabled"');
   });
 
+  it("resolves assistant attachment URLs on the mounted row without history-wide previews", () => {
+    const entry = buildAssistantTimelineEntry("Stored output");
+    vi.mocked(useAssetUrls).mockReturnValue([
+      "https://assets.example/chart-fresh.png",
+      "https://assets.example/report-fresh.pdf",
+    ]);
+    try {
+      const markup = renderToStaticMarkup(
+        <MessagesTimeline
+          {...buildProps()}
+          timelineEntries={[
+            {
+              ...entry,
+              message: {
+                ...entry.message,
+                attachments: [
+                  {
+                    type: "image",
+                    id: "stored-image",
+                    name: "chart.png",
+                    mimeType: "image/png",
+                    sizeBytes: 10,
+                  },
+                  {
+                    type: "file",
+                    id: "stored-file",
+                    name: "report.pdf",
+                    mimeType: "application/pdf",
+                    sizeBytes: 20,
+                  },
+                ],
+              },
+            },
+          ]}
+        />,
+      );
+      expect(useAssetUrls).toHaveBeenLastCalledWith(ACTIVE_THREAD_ENVIRONMENT_ID, [
+        { _tag: "attachment", attachmentId: "stored-image" },
+        {
+          _tag: "attachment",
+          attachmentId: "stored-file",
+          fileName: "report.pdf",
+          mimeType: "application/pdf",
+        },
+      ]);
+      expect(markup).toContain('src="https://assets.example/chart-fresh.png"');
+      expect(markup).toContain('href="https://assets.example/report-fresh.pdf"');
+      expect(markup).toContain('download="report.pdf"');
+    } finally {
+      vi.mocked(useAssetUrls).mockReset();
+    }
+  });
+
   it("renders proactive assistant image and file attachments", () => {
     const entry = buildAssistantTimelineEntry("Cron output");
     const markup = renderToStaticMarkup(
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index 11bff1f9073b..a28e5dca3521 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -22,7 +22,9 @@ import {
 } from "@t3tools/client-runtime/state/subagentRuntime";
 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,
@@ -53,7 +55,6 @@ import {
   workLogEntryIsToolLike,
 } from "../../session-logic";
 import {
-  type ChatAttachment,
   type ChatFileAttachment,
   type ChatImageAttachment,
   type ChatMessage,
@@ -105,9 +106,9 @@ import {
   buildExpandedImagePreview,
   ExpandedImagePreview,
 } from "./ExpandedImagePreview";
+import { useMessageAttachmentPreviews } from "./useMessageAttachmentPreviews";
 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";
@@ -209,7 +210,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;
@@ -233,7 +234,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 = (
@@ -337,6 +338,7 @@ interface MessagesTimelineProps {
    */
   liveFollowEnabled: boolean;
   onIsAtEndChange: (isAtEnd: boolean) => void;
+  onToolOutputCollapsedAtEnd?: () => void;
   onManualNavigation: () => void;
   hideEmptyPlaceholder?: boolean;
   topFadeEnabled?: boolean;
@@ -384,6 +386,7 @@ export const MessagesTimeline = memo(function MessagesTimeline({
   contentInsetEndAdjustment,
   liveFollowEnabled,
   onIsAtEndChange,
+  onToolOutputCollapsedAtEnd,
   onManualNavigation,
   hideEmptyPlaceholder = false,
   topFadeEnabled = false,
@@ -418,24 +421,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;
@@ -468,7 +479,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)) {
@@ -479,7 +490,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
@@ -1235,9 +1246,13 @@ function UserVideoAttachment({ file }: { readonly file: ChatFileAttachment }) {
 
 function UserTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "message" }> }) {
   const ctx = use(TimelineRowCtx);
+  const messageWithPreviews = useMessageAttachmentPreviews(
+    ctx.activeThreadEnvironmentId,
+    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));
@@ -1504,7 +1519,7 @@ function AssistantTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "mess
             onImageExpand={ctx.onImageExpand}
           />
         </AssistantCitationSource>
-        <MessageAttachments attachments={row.message.attachments ?? []} />
+        <MessageAttachments message={row.message} />
         <AssistantChangedFilesSection
           turnSummary={row.assistantTurnDiffSummary}
           routeThreadKey={ctx.routeThreadKey}
@@ -1524,10 +1539,11 @@ function AssistantTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "mess
   );
 }
 
-function MessageAttachments(props: { attachments: ReadonlyArray<ChatAttachment> }) {
+function MessageAttachments(props: { message: ChatMessage }) {
   const ctx = use(TimelineRowCtx);
-  const images = props.attachments.filter(isImageAttachment);
-  const files = props.attachments.filter(isFileAttachment);
+  const message = useMessageAttachmentPreviews(ctx.activeThreadEnvironmentId, props.message);
+  const images = (message.attachments ?? []).filter(isImageAttachment);
+  const files = (message.attachments ?? []).filter(isFileAttachment);
   return (
     <>
       {images.length > 0 ? (
@@ -1729,12 +1745,21 @@ 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 ? (
-            "Setting up worktree…"
+            <>
+              Setting up worktree…
+              <ActivityShimmerOverlay>Setting up worktree…</ActivityShimmerOverlay>
+            </>
           ) : isCompacting ? (
-            <CompactingLabel />
+            <>
+              <CompactingLabel />
+              <ActivityShimmerOverlay>
+                <CompactingLabel />
+              </ActivityShimmerOverlay>
+            </>
           ) : row.createdAt ? (
             <>
               Working for <WorkingTimer createdAt={row.createdAt} />
@@ -1754,7 +1779,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>
   );
@@ -1774,7 +1799,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);
@@ -1814,7 +1839,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],
@@ -1842,6 +1871,7 @@ const WorkGroupSection = memo(function WorkGroupSection({
             workspaceRoot={workspaceRoot}
             isExpandedToolGroupEntry={false}
             displayLabel={displayLabel}
+            onToggleEntry={onToggleStandaloneEntry}
           />
         ))}
       </div>
@@ -1878,7 +1908,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(() => {
@@ -1988,6 +2021,19 @@ function ExpandedWorkGroupEntries({
 
 const workEntryKey = (entry: TimelineWorkEntry) => entry.id;
 
+function ActivityShimmerOverlay({ children }: { children: ReactNode }) {
+  return (
+    <span
+      aria-hidden
+      className="live-activity-focus pointer-events-none absolute inset-y-0 select-none"
+    >
+      <span className="live-activity-focus-counter block">
+        <span className="live-activity-focus-aligned block text-foreground">{children}</span>
+      </span>
+    </span>
+  );
+}
+
 const failedToolIconClassName = "text-tool-error-icon/40";
 
 /** Image icons and the gradient computer-use mark cannot take a currentColor
@@ -2004,21 +2050,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="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}
       />
+      {showShimmer ? (
+        <ActivityShimmerOverlay>
+          <LiveActivityContent label={label} iconName={iconName} toolIcon={toolIcon} highlighted />
+        </ActivityShimmerOverlay>
+      ) : null}
     </div>
   );
 }
@@ -2029,12 +2090,16 @@ function LiveActivityContent({
   toolIcon,
   failed = false,
   announceFailure = false,
+  active = false,
+  highlighted = false,
 }: {
   label: string;
   iconName: WorkEntryIconName | undefined;
   toolIcon?: ToolActivityIcon | undefined;
   failed?: boolean;
   announceFailure?: boolean;
+  active?: boolean;
+  highlighted?: boolean;
 }) {
   const showTrailingFailureMark =
     failed && iconName !== undefined && !toolIconAcceptsTint(iconName, toolIcon);
@@ -2044,14 +2109,14 @@ function LiveActivityContent({
       className={cn(
         "flex min-h-6 min-w-0 items-center gap-1.5 py-0.5",
         iconName ? "px-0.5" : "px-1",
-        "text-secondary-label",
+        highlighted ? "text-foreground" : "text-secondary-label",
       )}
     >
       {iconName ? (
         <span
           className={cn(
             "flex size-6 shrink-0 items-center justify-center",
-            failed ? failedToolIconClassName : "text-icon-muted",
+            failed ? failedToolIconClassName : highlighted ? "text-foreground" : "text-icon-muted",
           )}
           role={announceFailure ? "img" : undefined}
           aria-label={announceFailure ? "Tool call failed" : undefined}
@@ -2060,11 +2125,11 @@ function LiveActivityContent({
             icon={toolIcon}
             fallbackName={iconName}
             className="block size-4 shrink-0 stroke-[1.8]"
-            muted
+            muted={!highlighted}
           />
         </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", failedToolIconClassName)} />
       ) : null}
@@ -2090,6 +2155,7 @@ function LiveWorkEntryTimelineRow({ row }: { row: Extract<TimelineRow, { kind: "
         iconName={workEntryIconName(row.entry)}
         toolIcon={row.entry.toolIcon ?? row.entry.toolSource?.icon}
         failed={failed}
+        active={row.active}
       />
     </button>
   );
@@ -2197,30 +2263,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}
     />
   );
@@ -2663,15 +2720,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 {
@@ -3135,6 +3184,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.
@@ -3147,6 +3197,7 @@ const SimpleWorkEntryRow = memo(function SimpleWorkEntryRow(props: {
       workspaceRoot={workspaceRoot}
       isExpandedToolGroupEntry={isExpandedToolGroupEntry}
       displayLabel={displayLabel}
+      onToggleEntry={props.onToggleEntry}
     />
   );
 });
@@ -3156,6 +3207,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);
@@ -3166,9 +3218,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/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/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/chat/useMessageAttachmentPreviews.test.tsx b/apps/web/src/components/chat/useMessageAttachmentPreviews.test.tsx
new file mode 100644
index 000000000000..403f46ddab2d
--- /dev/null
+++ b/apps/web/src/components/chat/useMessageAttachmentPreviews.test.tsx
@@ -0,0 +1,138 @@
+import { EnvironmentId, MessageId } from "@t3tools/contracts";
+import { act } from "react";
+import { create, type ReactTestRenderer } from "react-test-renderer";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import type { ChatMessage } from "../../types";
+import { useAssetUrls } from "../../assets/assetUrls";
+import {
+  selectMessagePreviewResources,
+  useMessageAttachmentPreviews,
+} from "./useMessageAttachmentPreviews";
+
+vi.mock("../../assets/assetUrls", () => ({ useAssetUrls: vi.fn(() => []) }));
+
+const environmentId = EnvironmentId.make("remote-environment");
+const image = {
+  type: "image",
+  id: "image",
+  name: "chart.png",
+  mimeType: "image/png",
+  sizeBytes: 10,
+} as const;
+const file = {
+  type: "file",
+  id: "file",
+  name: "report.pdf",
+  mimeType: "application/pdf",
+  sizeBytes: 20,
+} as const;
+const video = { ...file, id: "video", name: "demo.mp4", mimeType: "video/mp4" };
+const message: ChatMessage = {
+  id: MessageId.make("assistant-message"),
+  role: "assistant",
+  text: "Result",
+  streaming: true,
+  createdAt: "2026-09-05T00:00:00.000Z",
+  updatedAt: "2026-09-05T00:00:00.000Z",
+  turnId: null,
+  attachments: [image, file, video],
+};
+
+beforeEach(() => vi.mocked(useAssetUrls).mockReset().mockReturnValue([]));
+
+describe("mounted message attachment previews", () => {
+  it("requests assistant images and file links with download metadata, leaving video loading on demand", () => {
+    expect(selectMessagePreviewResources(message)).toEqual([
+      { _tag: "attachment", attachmentId: "image" },
+      {
+        _tag: "attachment",
+        attachmentId: "file",
+        fileName: "report.pdf",
+        mimeType: "application/pdf",
+      },
+    ]);
+    expect(selectMessagePreviewResources({ ...message, role: "user" })).toEqual([
+      { _tag: "attachment", attachmentId: "image" },
+    ]);
+  });
+
+  it("preserves local previews and does not acquire unavailable or unknown files", () => {
+    expect(
+      selectMessagePreviewResources({
+        ...message,
+        attachments: [
+          { ...image, previewUrl: "blob:local-image" },
+          { ...image, id: "inline-image", previewUrl: "data:image/png;base64,AAAA" },
+          { ...file, previewUrl: "blob:local-file" },
+          { ...file, id: "pending-file", downloadable: false },
+          {
+            type: "future-format",
+            id: "future",
+            name: "future.bin",
+            mimeType: "application/octet-stream",
+            sizeBytes: 1,
+          },
+        ],
+      }),
+    ).toEqual([]);
+  });
+
+  it.each(["assistant", "user"] as const)(
+    "binds renewed URLs for a mounted %s row and preserves immutable streaming previews",
+    async (role) => {
+      const source = { ...message, role };
+      const projected: ChatMessage[] = [];
+      function Row({ value }: { value: ChatMessage }) {
+        const preview = useMessageAttachmentPreviews(environmentId, value);
+        projected.push(preview);
+        return null;
+      }
+      let renderer: ReactTestRenderer | undefined;
+      try {
+        vi.mocked(useAssetUrls).mockReturnValue([
+          "https://assets/image-v1",
+          "https://assets/file-v1",
+        ]);
+        await act(async () => {
+          renderer = create(<Row value={source} />);
+        });
+        const first = projected.at(-1)!;
+        expect(first.attachments?.[0]).toMatchObject({ previewUrl: "https://assets/image-v1" });
+        if (role === "assistant")
+          expect(first.attachments?.[1]).toMatchObject({ previewUrl: "https://assets/file-v1" });
+        expect(source.attachments?.[0]).not.toHaveProperty("previewUrl");
+        expect(useAssetUrls).toHaveBeenLastCalledWith(
+          environmentId,
+          selectMessagePreviewResources(source),
+        );
+
+        await act(async () => {
+          renderer?.update(<Row value={{ ...source, text: "Result streaming" }} />);
+        });
+        expect(projected.at(-1)?.attachments).toBe(first.attachments);
+
+        vi.mocked(useAssetUrls).mockReturnValue([
+          "https://assets/image-v2",
+          "https://assets/file-v2",
+        ]);
+        await act(async () => {
+          renderer?.update(<Row value={source} />);
+        });
+        expect(projected.at(-1)?.attachments?.[0]).toMatchObject({
+          previewUrl: "https://assets/image-v2",
+        });
+        expect(first.attachments?.[0]).toMatchObject({ previewUrl: "https://assets/image-v1" });
+
+        vi.mocked(useAssetUrls).mockReturnValue([null, null]);
+        await act(async () => {
+          renderer?.update(<Row value={{ ...source }} />);
+        });
+        expect(projected.at(-1)?.attachments).toBe(source.attachments);
+      } finally {
+        await act(async () => {
+          renderer?.unmount();
+        });
+      }
+    },
+  );
+});
diff --git a/apps/web/src/components/chat/useMessageAttachmentPreviews.ts b/apps/web/src/components/chat/useMessageAttachmentPreviews.ts
new file mode 100644
index 000000000000..d77b7ba04775
--- /dev/null
+++ b/apps/web/src/components/chat/useMessageAttachmentPreviews.ts
@@ -0,0 +1,59 @@
+import { useMemo, useState } from "react";
+import type { AssetResource, EnvironmentId } from "@t3tools/contracts";
+import { useAssetUrls } from "../../assets/assetUrls";
+import {
+  createMessageAttachmentPreviewProjector,
+  selectMessageImageResources,
+} from "../../session-logic";
+import { isFileAttachment, isVideoAttachment, type ChatMessage } from "../../types";
+
+type AttachmentResource = Extract<AssetResource, { readonly _tag: "attachment" }>;
+
+/** File links need URLs only on assistant rows; user files and videos load on demand. */
+export function selectMessagePreviewResources(
+  message: Pick<ChatMessage, "role" | "attachments">,
+): ReadonlyArray<AttachmentResource> {
+  const images = selectMessageImageResources(message.attachments);
+  if (message.role !== "assistant") return images;
+  const resources = new Map(images.map((resource) => [resource.attachmentId, resource]));
+  for (const attachment of message.attachments ?? []) {
+    if (
+      !isFileAttachment(attachment) ||
+      isVideoAttachment(attachment) ||
+      attachment.downloadable === false
+    )
+      continue;
+    if (attachment.previewUrl?.startsWith("blob:") || attachment.previewUrl?.startsWith("data:"))
+      continue;
+    resources.set(attachment.id, {
+      _tag: "attachment",
+      attachmentId: attachment.id,
+      fileName: attachment.name,
+      mimeType: attachment.mimeType,
+    });
+  }
+  return resources.size === images.length ? images : [...resources.values()];
+}
+
+/** Mounted rows acquire previews; immutable projection preserves streaming row reuse. */
+export function useMessageAttachmentPreviews(
+  environmentId: EnvironmentId,
+  message: ChatMessage,
+): ChatMessage {
+  const { role, attachments } = message;
+  const resources = useMemo(
+    () => selectMessagePreviewResources({ role, attachments }),
+    [role, attachments],
+  );
+  const previewUrls = useAssetUrls(environmentId, resources);
+  const [projectPreviews] = useState(createMessageAttachmentPreviewProjector);
+  return useMemo(() => {
+    const urlsById = new Map(
+      resources.flatMap((resource, index) => {
+        const url = previewUrls[index];
+        return url ? [[resource.attachmentId, url] as const] : [];
+      }),
+    );
+    return projectPreviews(message, (attachment) => urlsById.get(attachment.id));
+  }, [previewUrls, projectPreviews, resources, message]);
+}
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/StyledDiffCodeView.test.tsx b/apps/web/src/components/diffs/StyledDiffCodeView.test.tsx
index 8bb710143d48..6a746b40f9af 100644
--- a/apps/web/src/components/diffs/StyledDiffCodeView.test.tsx
+++ b/apps/web/src/components/diffs/StyledDiffCodeView.test.tsx
@@ -9,6 +9,7 @@ import { useWorkerPool, type CodeViewProps } from "@pierre/diffs/react";
 import { WorkerPoolManager, type WorkerRequest, type WorkerResponse } from "@pierre/diffs/worker";
 import {
   act,
+  StrictMode,
   useEffect,
   useImperativeHandle,
   useLayoutEffect,
@@ -149,6 +150,14 @@ function Views({ count }: { count: number }) {
   );
 }
 
+function renderViews(count: number) {
+  return (
+    <StrictMode>
+      <Views count={count} />
+    </StrictMode>
+  );
+}
+
 describe("StyledDiffCodeView", () => {
   beforeEach(() => {
     testState.codeViewClassName = null;
@@ -208,6 +217,7 @@ describe("code-view worker lifecycle", () => {
     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)),
     );
@@ -226,14 +236,16 @@ describe("code-view worker lifecycle", () => {
   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, shares one pool, disposes the last view, and reopens without resetting siblings", async () => {
+  it("starts on demand, keeps quick reopens warm, and expires the last closed pool", async () => {
     await act(async () => {
-      renderer = create(<Views count={0} />);
+      renderer = create(renderViews(0));
     });
     const mounted = renderer!;
     const button = mounted.root.findByType("button");
@@ -241,7 +253,7 @@ describe("code-view worker lifecycle", () => {
     expect(testState.pools.size).toBe(0);
     await act(async () => {
       (button.props as { onClick(): void }).onClick();
-      mounted.update(<Views count={1} />);
+      mounted.update(renderViews(1));
     });
     const pool = [...testState.pools.keys()][0]!;
     await act(async () => testState.pools.get(pool));
@@ -252,25 +264,39 @@ describe("code-view worker lifecycle", () => {
     );
     expect(testState.requests.filter((request) => request.type === "file")).toHaveLength(0);
 
-    await act(async () => mounted.update(<Views count={2} />));
+    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(testState.renderPools).toEqual([pool, pool]);
+    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",
     );
 
-    await act(async () => mounted.update(<Views count={1} />));
+    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(<Views count={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(<Views count={1} />));
+    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);
@@ -285,7 +311,7 @@ describe("code-view worker lifecycle", () => {
   it("renders through Pierre's main-thread fallback when worker creation fails", async () => {
     testState.failWorkers = true;
     await act(async () => {
-      renderer = create(<Views count={1} />);
+      renderer = create(renderViews(1));
     });
     const pool = [...testState.pools.keys()][0]!;
     await act(async () => {
@@ -309,7 +335,7 @@ describe("code-view worker lifecycle", () => {
       testState.onInitializationHeld = resolve;
     });
     await act(async () => {
-      renderer = create(<Views count={2} />);
+      renderer = create(renderViews(2));
     });
     const pool = [...testState.pools.keys()][0]!;
     const pending = testState.pools.get(pool)!;
@@ -319,10 +345,11 @@ describe("code-view worker lifecycle", () => {
     expect(renderer!.root.findAllByProps({ role: "status" })).toHaveLength(2);
     expect(testState.renderPools).toHaveLength(0);
 
-    await act(async () => renderer!.update(<Views count={1} />));
+    await act(async () => renderer!.update(renderViews(1)));
     expect(pool.getStats().totalWorkers).toBe(2);
     expect(testState.terminations).toHaveLength(0);
-    await act(async () => renderer!.update(<Views count={0} />));
+    await act(async () => renderer!.update(renderViews(0)));
+    await vi.advanceTimersByTimeAsync(30_000);
     await pending;
     await Promise.all(testState.terminations);
     await act(async () => {
diff --git a/apps/web/src/components/files/FilePreviewPanel.tsx b/apps/web/src/components/files/FilePreviewPanel.tsx
index a702c4c1abd7..3f0c92742ca7 100644
--- a/apps/web/src/components/files/FilePreviewPanel.tsx
+++ b/apps/web/src/components/files/FilePreviewPanel.tsx
@@ -47,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";
 
@@ -72,9 +71,8 @@ import {
   setMarkdownTaskChecked,
   shouldShowFileExplorer,
 } from "./filePreviewMode";
-import { FileSaveCoordinator } from "./fileSaveCoordinator";
+import { useFileSaveCoordinator } from "./useFileSaveCoordinator";
 import {
-  confirmProjectFileQueryData,
   getOptimisticProjectFileQueryData,
   setProjectFileQueryData,
   useProjectFileQuery,
@@ -101,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}
@@ -613,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,
@@ -774,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"),
   );
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..808a58fc144c
--- /dev/null
+++ b/apps/web/src/components/files/fileEditorHighlight.test.ts
@@ -0,0 +1,267 @@
+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);
+  // Pierre schedules pool broadcasts through the rAF → setImmediate stub.
+  // Drain those callbacks before unstubbing or cancelAnimationFrame is gone.
+  await new Promise<void>((resolve) => setImmediate(resolve));
+  vi.unstubAllGlobals();
+});
+
+describe("editable file highlighting", { timeout: 60_000 }, () => {
+  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/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/preview/PreviewAutomationHosts.tsx b/apps/web/src/components/preview/PreviewAutomationHosts.tsx
index c73e595b703c..f57bdbbe46ac 100644
--- a/apps/web/src/components/preview/PreviewAutomationHosts.tsx
+++ b/apps/web/src/components/preview/PreviewAutomationHosts.tsx
@@ -76,6 +76,7 @@ import {
   resolvePreviewAutomationOpenTab,
   resolvePreviewAutomationTarget,
 } from "./previewAutomationTarget";
+import { resolveHostWaitBudgetMs, waitForHostReadiness } from "./previewAutomationHostBudget";
 import { isPreviewViewportReady } from "./previewViewportReadiness";
 import { shouldRollbackPreviewViewport } from "./previewViewportRollback";
 
@@ -95,25 +96,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 +319,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,
@@ -381,7 +385,7 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
             readyTabId,
             runtimeTabId,
             request.operation,
-            request.timeoutMs,
+            hostDeadlineMs,
           );
           return {
             bridge,
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 506d59dc6457..aa2d278ce249 100644
--- a/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestCodeTab.tsx
@@ -1138,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];
@@ -1148,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>
diff --git a/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx b/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
index 4a3af4b02c52..76e50b60003b 100644
--- a/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestDetailPanel.tsx
@@ -228,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);
 
@@ -524,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>>>({});
@@ -568,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 }),
   );
@@ -699,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?.({
@@ -713,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
@@ -2143,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
index f7d477e9afad..36a4c8b15c1c 100644
--- a/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx
+++ b/apps/web/src/components/pullRequest/PullRequestLinkPreview.tsx
@@ -84,7 +84,7 @@ export function PullRequestLinkPreview({
   return (
     <PreviewCard open={open} onOpenChange={setOpen}>
       <PreviewCardTrigger render={trigger} delay={350} closeDelay={120} />
-      <PreviewCardPopup className="w-80 max-w-[calc(100vw-2rem)] p-3">
+      <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}
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/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 9d0794aadb8b..9eac49c6ede4 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/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 44cbb56292fc..7537a30505b8 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 b53dc5b8cb38..0b23fb2d2072 100644
--- a/apps/web/src/components/settings/DiagnosticsSettings.tsx
+++ b/apps/web/src/components/settings/DiagnosticsSettings.tsx
@@ -36,6 +36,7 @@ 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";
@@ -599,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/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/ProjectSettingsPanel.tsx b/apps/web/src/components/settings/ProjectSettingsPanel.tsx
index 2dc05382e791..d6b6f98d23a2 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 689ebb42e884..39e908b2ca15 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.tsx
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -27,6 +27,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";
@@ -99,16 +104,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);
 }
 
 /**
@@ -130,9 +132,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) =>
@@ -140,15 +147,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];
 }
 
@@ -468,7 +473,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.
@@ -509,8 +514,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);
   };
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/ProviderSettingsPanel.tsx b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
index d7a49bd4f099..709d2d5eb67f 100644
--- a/apps/web/src/components/settings/ProviderSettingsPanel.tsx
+++ b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
@@ -49,11 +49,9 @@ import {
   connectionPhasePingClassName,
 } from "../ConnectionStatusDot";
 import {
-  canOneClickUpdateProviderCandidate,
-  collectProviderUpdateCandidates,
-  hasOneClickUpdateProviderCandidate,
+  isProviderSettingsUpdateCandidate,
   isProviderUpdateActive,
-  type ProviderUpdateCandidate,
+  type ProviderSettingsUpdateCandidate,
 } from "../ProviderUpdateLaunchNotification.logic";
 import { Button } from "../ui/button";
 import {
@@ -72,6 +70,7 @@ 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";
@@ -80,7 +79,6 @@ 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,
@@ -191,8 +189,10 @@ function ProviderSettingsPlaceholder({
   readonly children?: ReactNode;
 }) {
   return (
-    <SettingsSection {...searchableSetting("providers")} variant="plain">
-      {deviceTabs}
+    <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,
@@ -323,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 = 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"
@@ -355,7 +358,7 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
                       <span className="sr-only">
                         {detail}, {statusText}
                       </span>
-                    </button>
+                    </Toggle>
                   }
                 />
                 <TooltipPopup side="top">
@@ -364,7 +367,7 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
               </Tooltip>
             );
           })}
-        </div>
+        </ToggleGroup>
       </ScrollArea>
     ) : null;
 
@@ -569,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) =>
@@ -631,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,
@@ -660,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;
       });
     },
@@ -867,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 =
+    const updateCandidate = providerUpdateCandidateByInstanceId.get(row.instanceId);
+    const isInstanceUpdateRunning =
       updateCandidate !== undefined &&
-      (updatingProviderDrivers.has(updateCandidate.driver) ||
-        serverProviders.some(
-          (provider) =>
-            provider.driver === updateCandidate.driver && isProviderUpdateActive(provider),
-        ));
-    const showInlineUpdateButton =
-      updateCandidate !== undefined &&
-      hasOneClickUpdateProviderCandidate(updateCandidate, serverProviders);
-    const canRunInlineUpdate =
-      updateCandidate !== undefined &&
-      canOneClickUpdateProviderCandidate(updateCandidate, serverProviders) &&
-      !updatingProviderDrivers.has(updateCandidate.driver);
+      (updatingProviderInstanceIds.has(updateCandidate.instanceId) ||
+        isProviderUpdateActive(updateCandidate));
+    const showInlineUpdateButton = updateCandidate !== undefined;
+    const canRunInlineUpdate = updateCandidate !== undefined && !isInstanceUpdateRunning;
     const modelPreferences = settings.providerModelPreferences?.[row.instanceId] ?? {
       hiddenModels: [],
       modelOrder: [],
@@ -971,18 +965,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} />
@@ -1031,9 +1026,7 @@ export function EnvironmentProviderSettings({
               </>
             )}
           </div>
-        }
-      >
-        {deviceTabs}
+        </div>
         {readOnly ? (
           <div className={cn(providerCardClassName, "overflow-hidden")}>
             <SettingsRow
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 961f72653b75..ac3ada53e5e5 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -565,7 +565,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
@@ -2322,7 +2322,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
@@ -2452,12 +2452,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:
@@ -2473,7 +2474,7 @@ export function GeneralSettingsPanel() {
               onCheckedChange={(checked) =>
                 updateSettings({ continueThreadsAfterServerUpdate: Boolean(checked) })
               }
-              aria-label="Continue threads after server updates"
+              aria-label="Continue threads after restarts"
             />
           }
         />
@@ -2614,37 +2615,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")}
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/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index 8e5ffb24ea87..7c71fc3923ec 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -219,9 +219,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/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 b1a57582bc9f..77f85953984c 100644
--- a/apps/web/src/components/usage/UsageLimits.tsx
+++ b/apps/web/src/components/usage/UsageLimits.tsx
@@ -426,10 +426,18 @@ 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);
+  const selected =
+    selectedEnvironmentIds === null
+      ? presentations
+      : new Map([...presentations].filter(([id]) => selectedEnvironmentIds.has(id)));
+  const groups = collectLimitsGroups(selected);
+  const sources = collectLimitSources(selected);
   // Anchored once per mount on purpose: countdowns must not tick (see below).
   const [now] = useState(() => Date.now());
 
@@ -437,7 +445,7 @@ export function UsageLimitsSection() {
     <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.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 4b62df374122..e957002115ab 100644
--- a/apps/web/src/components/usage/UsagePage.tsx
+++ b/apps/web/src/components/usage/UsagePage.tsx
@@ -1,12 +1,27 @@
-import type { UsageProviderKind } from "@t3tools/contracts";
-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 { usePrimaryEnvironmentId } 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";
@@ -23,6 +38,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";
@@ -36,6 +59,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";
 
@@ -65,19 +89,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 primaryEnvironmentId = usePrimaryEnvironmentId();
+  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],
@@ -114,12 +138,12 @@ export function UsagePage() {
     });
   };
   const refreshWindow = () => {
-    // On Limits the button re-probes every provider (and usage-limit source)
-    // on the primary environment; the live snapshots then flow in over the
-    // config stream, so nothing else needs to move.
     if (showingLimits) {
-      if (primaryEnvironmentId) {
-        void refreshProviders({ environmentId: primaryEnvironmentId, input: {} });
+      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: {} });
+        }
       }
       return;
     }
@@ -140,21 +164,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"
@@ -197,7 +231,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) => {
@@ -260,25 +294,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">
@@ -544,10 +577,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,
@@ -567,7 +598,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>
       ))}
@@ -586,66 +617,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/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/connection/platform.ts b/apps/web/src/connection/platform.ts
index 231048b5c35a..19dde5368332 100644
--- a/apps/web/src/connection/platform.ts
+++ b/apps/web/src/connection/platform.ts
@@ -183,6 +183,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/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/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.ts b/apps/web/src/hooks/useSettings.ts
index cc95b92e8acb..da57708bcc83 100644
--- a/apps/web/src/hooks/useSettings.ts
+++ b/apps/web/src/hooks/useSettings.ts
@@ -1,3 +1,4 @@
+import { readCustomModelEntries } from "@t3tools/shared/model";
 /**
  * Environment-scoped settings hooks.
  *
@@ -26,6 +27,7 @@ import {
 } from "@t3tools/contracts/settings";
 import { safeErrorLogAttributes } from "@t3tools/client-runtime/errors";
 import {
+  filterSharedServerPatch,
   findSharedSettingsMismatches,
   pickSharedServerSettings,
   splitSharedServerPatch,
@@ -45,7 +47,7 @@ import { isHostedStaticApp } from "~/hostedPairing";
 import { primaryServerSettingsAtom, serverEnvironment } from "~/state/server";
 import { useEnvironments, usePrimaryEnvironment } from "~/state/environments";
 import { useAtomCommand } from "~/state/use-atom-command";
-import { normalizeCustomModelSlugs } from "~/modelSelection";
+import { normalizeCustomModelEntries } from "~/modelSelection";
 import { useTheme } from "./useTheme";
 
 const CLIENT_SETTINGS_PERSISTENCE_ERROR_SCOPE = "[CLIENT_SETTINGS]";
@@ -245,12 +247,14 @@ export function buildLegacyServerSettingsMigrationPatch(
   legacySettings: Record<string, unknown>,
 ): ServerSettingsPatch {
   const customCopilotModels = Array.isArray(legacySettings.customCopilotModels)
-    ? normalizeCustomModelSlugs(
-        legacySettings.customCopilotModels.filter(
-          (model): model is string => typeof model === "string",
+    ? normalizeCustomModelEntries(
+        readCustomModelEntries(
+          legacySettings.customCopilotModels.filter(
+            (model): model is string => typeof model === "string",
+          ),
         ),
         new Set(),
-      )
+      ).map((entry) => entry.slug)
     : undefined;
   const copilotPatch = {
     ...(typeof legacySettings.copilotCliPath === "string"
@@ -423,18 +427,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],
-  );
-}
-
 export function shouldWarnWhenLocalServerSettingsCannotPersist(
   localPatch: ServerSettingsPatch,
   environmentId: EnvironmentId | null,
@@ -456,7 +448,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);
@@ -464,11 +456,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 (environmentId && Object.keys(localPatch).length > 0) {
           void persistServerSettings({
@@ -479,26 +471,38 @@ function useUpdateSettingsTarget(environmentId: EnvironmentId | null) {
           warnUnsaved();
         }
         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;
@@ -513,6 +517,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
@@ -532,28 +537,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 };
 }
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 54bb5b70d5fa..68b0101be28a 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -425,6 +425,117 @@ 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 {
+  from {
+    transform: translateX(0);
+  }
+  to {
+    transform: translateX(100%);
+  }
+}
+
+@keyframes live-activity-focus-counter {
+  from {
+    transform: translateX(0);
+  }
+  to {
+    transform: translateX(-100%);
+  }
+}
+
+@utility live-activity-focus {
+  --live-activity-focus-width: 4.5rem;
+
+  right: auto;
+  left: calc(-1 * var(--live-activity-focus-width));
+  width: calc(100% + var(--live-activity-focus-width) + var(--live-activity-focus-width));
+  -webkit-mask-image: linear-gradient(
+    to right,
+    transparent 0,
+    rgb(0 0 0 / 12%) 0.675rem,
+    rgb(0 0 0 / 55%) 1.575rem,
+    black 2.25rem,
+    rgb(0 0 0 / 55%) 2.925rem,
+    rgb(0 0 0 / 12%) 3.825rem,
+    transparent var(--live-activity-focus-width),
+    transparent 100%
+  );
+  -webkit-mask-repeat: no-repeat;
+  mask-image: linear-gradient(
+    to right,
+    transparent 0,
+    rgb(0 0 0 / 12%) 0.675rem,
+    rgb(0 0 0 / 55%) 1.575rem,
+    black 2.25rem,
+    rgb(0 0 0 / 55%) 2.925rem,
+    rgb(0 0 0 / 12%) 3.825rem,
+    transparent var(--live-activity-focus-width),
+    transparent 100%
+  );
+  mask-repeat: no-repeat;
+  animation: live-activity-focus 2.2s linear infinite;
+  animation-play-state: var(--visible-animation-state, paused);
+  will-change: var(--visible-animation-will-change, auto);
+
+  @media (prefers-reduced-motion: reduce), (forced-colors: active) {
+    animation: none;
+    opacity: 0;
+    will-change: auto;
+  }
+}
+
+@utility live-activity-focus-counter {
+  width: 100%;
+  animation: live-activity-focus-counter 2.2s linear infinite;
+  animation-play-state: var(--visible-animation-state, paused);
+  will-change: var(--visible-animation-will-change, auto);
+
+  @media (prefers-reduced-motion: reduce), (forced-colors: active) {
+    animation: none;
+    will-change: auto;
+  }
+}
+
+@utility live-activity-focus-aligned {
+  width: calc(100% - var(--live-activity-focus-width) - var(--live-activity-focus-width));
+  margin-left: var(--live-activity-focus-width);
+}
+
 @property --assistant-citation-highlight-opacity {
   syntax: "<number>";
   inherits: true;
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/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..4ff195083d51 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>,
+export 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;
     }
@@ -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/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/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/routes/_chat.pull-requests.tsx b/apps/web/src/routes/_chat.pull-requests.tsx
index bcc22daa4a9d..a9537423a7f0 100644
--- a/apps/web/src/routes/_chat.pull-requests.tsx
+++ b/apps/web/src/routes/_chat.pull-requests.tsx
@@ -826,7 +826,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 +838,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 +851,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 +951,7 @@ function PullRequestsRouteView() {
         environmentKey,
         scope: scopeKey,
         query: sentQuery,
-        data,
+        data: { ...data, entries: ordered?.key === filterKey ? ordered.entries : data.entries },
         ...(partitions === undefined ? {} : { partitions }),
       };
     });
@@ -1017,7 +1013,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 +1041,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 +1085,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 +1130,7 @@ function PullRequestsRouteView() {
   // host's rate limit.
   useLiveRefresh(
     () => {
-      refreshList();
-      authoredQuery.refresh();
-      reviewingQuery.refresh();
+      refreshList(true);
     },
     { enabled: pullRequestsSupported },
   );
@@ -1209,54 +1220,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 +1270,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 +1596,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 +1662,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 +1950,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 +2215,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 +2296,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/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 6040d416277e..08d4c5f6ebe8 100644
--- a/apps/web/src/session-logic.test.ts
+++ b/apps/web/src/session-logic.test.ts
@@ -22,6 +22,8 @@ import {
   hasActionableProposedPlan,
   isLatestTurnSettled,
   PROVIDER_OPTIONS,
+  selectHandoffImageResources,
+  selectMessageImageResources,
   workEntryIndicatesToolFailure,
   workEntryIndicatesToolNeutralStatus,
   workEntryIndicatesToolSuccess,
@@ -2110,6 +2112,128 @@ 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"),
diff --git a/apps/web/src/session-logic.ts b/apps/web/src/session-logic.ts
index cc117f639919..6d2231e95269 100644
--- a/apps/web/src/session-logic.ts
+++ b/apps/web/src/session-logic.ts
@@ -12,6 +12,7 @@ import { extractToolActivityPresentation } from "@t3tools/client-runtime/work-lo
 import {
   ApprovalRequestId,
   isToolLifecycleItemType,
+  type AssetResource,
   type OrchestrationLatestTurn,
   type OrchestrationThreadActivity,
   type OrchestrationProposedPlanId,
@@ -24,16 +25,19 @@ import {
   type TurnId,
 } from "@t3tools/contracts";
 
-import type {
-  ChatAttachment,
-  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 { formatDuration, formatElapsed } from "@t3tools/shared/orchestrationTiming";
+
 export type ProviderPickerKind = ProviderDriverKind;
 
 export const PROVIDER_OPTIONS: Array<{
@@ -378,32 +382,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">;
 
@@ -988,6 +966,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;
@@ -1909,6 +1895,43 @@ function mergeTimelineEntrySuffix(
   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<
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/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 359be7d79839..be65400c9800 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({
@@ -94,6 +98,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
@@ -104,7 +117,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(
@@ -114,10 +127,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
         ? []
         : [
@@ -129,16 +142,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/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 6f4d0e163da4..98418c167aa5 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -83,6 +83,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;
 
diff --git a/docs/README.md b/docs/README.md
index ce2187ee865f..4e6f82bfb826 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,48 +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)
-- [Anonymous usage data](./user/telemetry.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 e84d9ed4d703..797ff8fe31fe 100644
--- a/docs/internals/connection-runtime.md
+++ b/docs/internals/connection-runtime.md
@@ -1,211 +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.
-
-### Thread detail ownership
-
-Mounted detail consumers share one live thread subscription. The subscription
-ends when the last consumer leaves. Hidden routes that remain mounted still
-count as consumers.
-
-A separate registry-local atom retains the last thread state and replay cursor
-for five idle minutes. A warm mount renders that state and resumes the stream
-without another snapshot download. The cache holds completed state and cursor
-updates together. It retains pagination data but clears canceled loading state.
-An ownership token prevents an old scope from replacing its successor's cache.
-Closing a thread skips snapshots that were already saved. Changed snapshots and
-failed background writes still get a final save attempt.
-
-## 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;
-- thread stream shutdown, warm resume, and snapshot expiry;
-- 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 068fcfa68a90..dc43b4d45c03 100644
--- a/docs/internals/environment-auth.md
+++ b/docs/internals/environment-auth.md
@@ -1,197 +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`.
-
-The reusable `desktop-bootstrap` grant replaces active sessions with the same
-subject and authentication method. Revocation and insertion share one database
-transaction, so a failed insertion preserves the previous credential. This also
-removes stale local desktop entries from earlier launches. Browser-cookie sessions
-and sessions issued through pairing links are not replaced.
-
-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 b69c78db3298..f7cb61259c0e 100644
--- a/docs/internals/glossary.md
+++ b/docs/internals/glossary.md
@@ -1,211 +1,47 @@
 # 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)
-- [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.
-
-### 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 difference between two checkpoints. [CheckpointDiffQuery.ts][20] reads full patches on demand. [CheckpointReactor.ts][6] uses NUL-delimited Git numstat output for automatic file summaries, parsed by [Diffs.ts][23].
-
-#### 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][25] 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][26].
-
-#### 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]
-- [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]: ../../apps/server/src/environmentTheme.ts
-[26]: ../user/environment-theme.md
+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.                                                                |
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 b1116986bf32..0e88610ada99 100644
--- a/docs/internals/product-analytics.md
+++ b/docs/internals/product-analytics.md
@@ -1,177 +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.
-
-## Provider turn events
-
-`provider.turn.completed` records one anonymous event when a provider emits a
-canonical completed or aborted turn. The event reports normalized main-agent
-token counts when the provider supplies enough data.
-
-| Property              | Values and meaning                                                                                                              |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `provider`            | Provider driver, such as `codex`, `claudeAgent`, or `opencode`. Use this as the harness breakdown.                              |
-| `model`               | Selected or provider-reported model when known. This is metadata, not proof that one model produced every token.                |
-| `effort`              | Selected or provider-reported reasoning effort when known.                                                                      |
-| `interactionMode`     | Turn interaction mode, `default` or `plan`, when known.                                                                         |
-| `runtimeMode`         | Session permission mode when known.                                                                                             |
-| `mixedModels`         | `true` when T3 Code observed `model.rerouted` during the turn. This does not split token counts by model.                       |
-| `durationMs`          | Time from the observed turn start or accepted send request to the terminal event. Omitted when start metadata is not available. |
-| `terminalStatus`      | `completed`, `failed`, `interrupted`, or `cancelled`.                                                                           |
-| `usageStatus`         | `complete`, `partial`, or `unavailable`.                                                                                        |
-| `usageScope`          | `main_agent`. Child-agent token use is not included.                                                                            |
-| `hasSubagents`        | Whether the adapter observed child agents during the turn. Omitted when the adapter does not provide a normalized usage report. |
-| `inputTokens`         | Total main-agent input tokens. This includes uncached input, cache reads, and cache creation or writes.                         |
-| `cachedInputTokens`   | Cache-read tokens. This is a subset of `inputTokens`.                                                                           |
-| `cacheCreationTokens` | Cache creation or write tokens. This is a subset of `inputTokens`.                                                              |
-| `outputTokens`        | Total main-agent output tokens, including reasoning tokens.                                                                     |
-| `reasoningTokens`     | Reasoning tokens when the provider reports them separately. This is a subset of `outputTokens`.                                 |
-
-`complete` means the provider supplied full input and output totals for the
-turn. `partial` means each included count is valid, but T3 Code did not observe
-the full turn. This can happen after an interruption, provider failure, or
-reconnect. `unavailable` means the provider did not supply trustworthy counts.
-Numeric properties are omitted when their values are unknown. They are not set
-to zero.
-
-Codex uses deltas from its cumulative token totals, and falls back to the
-newest response's `last` usage when no prior total exists or the total was
-reset. Claude uses the final result's per-turn `usage` value and does not use
-cumulative `modelUsage`.
-OpenCode sums unique main-session step totals. Cursor, Grok, and Antigravity
-usage stays `unavailable` until their ACP token fields and scope are verified.
-
-The completed event count does not have to match `provider.turn.sent`. For
-example, Claude can emit synthetic turns without a matching send request.
-Duplicate terminal events for the same provider instance, thread, and turn
-produce one analytics event.
-
-Collection is best effort and starts with the first server release that
-contains this event. T3 Code does not scan provider history or backfill older
-turns.
-
-## 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.
-
-Create a second saved dashboard named `Provider token efficiency`. Start each
-token insight with these filters:
-
-- `usageStatus = complete`
-- `hasSubagents = false`
-- `mixedModels = false`
-
-Break down input tokens, output tokens, and their ratio by `provider`. Compare
-the same `model`, `effort`, `interactionMode`, and `terminalStatus`. Without
-these filters, model choice, reasoning level, plan mode, failures, and child
-agents can look like harness differences. Keep separate views for median turn
-usage and aggregate `sum(outputTokens) / sum(inputTokens)`. Do not average each
-turn's ratio because small-input turns can dominate that result.
-
-## 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, authentication tokens, prompts, IP
-addresses, or user-assigned device names. The token event does not include
-thread IDs, turn IDs, provider instance IDs, event IDs, request IDs, raw
-provider payloads, or child-agent output. It does not scan provider history on
-disk or start external work. 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 7e4e1444de10..fdf58ab18068 100644
--- a/docs/internals/providers.md
+++ b/docs/internals/providers.md
@@ -1,415 +1,118 @@
-# 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 sixteen entries, in registration order:
-
-| Driver kind   | Driver source                                 |
-| ------------- | --------------------------------------------- |
-| `acp`         | [`Drivers/AcpDriver.ts`][acp]                 |
-| `codex`       | [`Drivers/CodexDriver.ts`][codex]             |
-| `claudeAgent` | [`Drivers/ClaudeDriver.ts`][claude]           |
-| `cursor`      | [`Drivers/CursorDriver.ts`][cursor]           |
-| `droid`       | [`Drivers/DroidDriver.ts`][droid]             |
-| `fx`          | [`Drivers/FxDriver.ts`][fx]                   |
-| `grok`        | [`Drivers/GrokDriver.ts`][grok]               |
-| `opencode`    | [`Drivers/OpenCodeDriver.ts`][opencode]       |
-| `antigravity` | [`Drivers/AntigravityDriver.ts`][antigravity] |
-| `amp`         | [`Drivers/AmpDriver.ts`][amp]                 |
-| `copilot`     | [`Drivers/CopilotDriver.ts`][copilot]         |
-| `geminiCli`   | [`Drivers/GeminiCliDriver.ts`][geminicli]     |
-| `hermes`      | [`Drivers/HermesDriver.ts`][hermes]           |
-| `kilo`        | [`Drivers/KiloDriver.ts`][kilo]               |
-| `ohMyPi`      | [`Drivers/OhMyPiDriver.ts`][ohmypi]           |
-| `pi`          | [`Drivers/PiDriver.ts`][pi]                   |
-
-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
-
-Native OpenCode event logs skip text deltas and running tool snapshots. Pending, completed,
-and failed tool states remain, including final output and errors. This filter does not change
-events sent to clients or orchestration storage.
-
-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
-[acp]: ../../apps/server/src/provider/Drivers/AcpDriver.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
-[droid]: ../../apps/server/src/provider/Drivers/DroidDriver.ts
-[fx]: ../../apps/server/src/provider/Drivers/FxDriver.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
-[amp]: ../../apps/server/src/provider/Drivers/AmpDriver.ts
-[copilot]: ../../apps/server/src/provider/Drivers/CopilotDriver.ts
-[geminicli]: ../../apps/server/src/provider/Drivers/GeminiCliDriver.ts
-[hermes]: ../../apps/server/src/provider/Drivers/HermesDriver.ts
-[kilo]: ../../apps/server/src/provider/Drivers/KiloDriver.ts
-[ohmypi]: ../../apps/server/src/provider/Drivers/OhMyPiDriver.ts
-[pi]: ../../apps/server/src/provider/Drivers/PiDriver.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).
+
+## Fork adapter boundaries
+
+The [driver registry](../../apps/server/src/provider/builtInDrivers.ts) includes the fork
+providers. Cursor uses its SDK rather than upstream ACP; transport-specific upstream fixes
+need equivalent SDK handling. Keep SDK models, account configuration, and usage events intact.
+Do not infer conversation rewind from filesystem checkpoint support.
+
+Legacy provider names remain decodable when replaying persisted fork events. New aggregate
+replay queries must use the same normalization and boundary redaction as global replay.
+Migration identifiers retain the deployed fork lineage even where upstream uses different IDs.
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 c22ce4460a75..000000000000
--- a/docs/internals/scripts.md
+++ /dev/null
@@ -1,216 +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.
-  Vite's experimental bundled dev mode remains available as an explicit
-  `T3CODE_BUNDLED_DEV=1` opt-in. The default shared path uses standard dev serving for reliability.
-  A remote browser pays a network round trip per import level in unbundled dev, which can turn a
-  cold module graph into minutes of waterfall; set `T3CODE_BUNDLED_DEV=1` when that matters.
-  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 checks verify that the required executables are available and that the
-requested Rust standard library target is installed.
-
-### 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
index addfa1ce093a..ca5f0d46ead6 100644
--- a/docs/internals/terminal-runtime.md
+++ b/docs/internals/terminal-runtime.md
@@ -1,52 +1,44 @@
 # Terminal runtime
 
-The environment server owns terminal processes, retained output history, and
-session lifecycle. Web, desktop, and mobile clients attach to the same
-server-owned session over the environment RPC connection. The desktop renderer
-does not own a separate PTY. Clients can reconnect to a running PTY or share
-it with another client.
-
-## Output path
-
-PTY output follows this path:
-
-```text
-PTY callback
-  -> ordered process-event drain
-  -> bounded retained-history append
-  -> live terminal output event
-  -> coalesced history persistence
-```
-
-Live output events contain only the new PTY data. Full retained history is
-materialized only when the server returns a snapshot or when the coalescing
-persistence worker writes the latest state.
-
-Retained history is limited to 5,000 lines and 8 MiB of UTF-8 text per terminal.
-The server discards the oldest output when either limit is reached. A byte
-cutoff can shorten the oldest retained line, but does not split a Unicode code
-point. Live output is not truncated.
-
-History uses small chunks with byte and newline counts. Appending output scans
-the new text and any removed chunk prefix, not the full retained history.
-Empty lines, incomplete final lines, and trailing newlines remain unchanged
-within the limits. Split surrogate pairs are joined before byte eviction.
-
-Discard each chunk's string reference as soon as it leaves retained history.
-Array compaction can run later. Shared web and mobile client state retains at
-most 512 KiB, so each client can display less scrollback than the server keeps.
-
-Measure sustained-output changes against a full retained history so terminal
-throughput does not regress unnoticed.
-
-## Persistence
-
-History persistence is keyed by terminal session and coalesces pending writes.
-The worker reads the newest bounded-history state after its debounce instead
-of receiving a newly materialized full string for every PTY callback. Clear,
-restart, close, and final flush operations still force the latest state to
-disk before their lifecycle boundary completes.
-
-Restoration reads at most the last 8 MiB from current and legacy history files.
-It skips an incomplete UTF-8 code point at the start and applies the line limit
-before rewriting oversized files. File handles close before that rewrite.
+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..76edcb1e82f1
--- /dev/null
+++ b/docs/operations/development.md
@@ -0,0 +1,141 @@
+# 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 the [isolated fixture guide](../../.agents/skills/test-t3-app/references/sqlite-fixtures.md) for preparing test data.
+
+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 use standard dev serving by default. Set `T3CODE_BUNDLED_DEV=1` to opt into
+bundled dev when network round trips dominate startup. 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
+```
+
+Run the workspace `vp check` and `vp run typecheck` before completing a change.
+Use `vp run lint:mobile` for native mobile changes. 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.
+
+## 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 181e651e59d1..44f5404da075 100644
--- a/docs/operations/release.md
+++ b/docs/operations/release.md
@@ -321,7 +321,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 f158eb8f185e..4a8df5333664 100644
--- a/docs/user/composer.md
+++ b/docs/user/composer.md
@@ -1,240 +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.
+
+## Model defaults
 
-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.
+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.
 
-## HTML and PDF files in the file viewer
+Leaving reasoning level or service tier unset uses the provider's own configuration.
 
-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.
+## Quote an assistant response
 
-## Changing projects
+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.
 
-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.
+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.
 
-## Notices above the composer
+Mobile displays saved quotes and comments, but does not create citations or
+navigate to their sources.
 
-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.
+## Recall a sent prompt
 
-Loading, syncing, and server-update icons are static. Live tool labels do not shimmer.
+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. When the composer is empty and the stash
-has one entry, press the shortcut again to restore it. The shortcut opens the stash menu if there
-are multiple entries or the entry's images are still saving. You can also open the menu from the
-stash badge. 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 2334f189cccf..059634fd1aae 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -1,152 +1,115 @@
 # 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 runs the upstream distribution and opens the local web app. To retain this fork's additional providers, use its desktop release. 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 this fork from [GitHub Releases](https://github.com/aaditagrawal/t3code/releases).
+The package-manager commands below install the upstream distribution:
 
-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:
-
-```bash
-winget install T3Tools.T3Code
-```
-
-macOS:
+### Windows Subsystem for Linux
 
-```bash
-brew install --cask t3-code
-```
+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.
 
-Arch Linux:
+### Open a project from a terminal
 
-Stable:
+With the desktop app already running on the same machine:
 
 ```bash
-yay -S t3code-bin
+npx t3 app
 ```
 
-Nightly:
+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.
 
-```bash
-yay -S t3code-nightly-bin
-```
+## Mobile app
 
-### 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 |
-| Oh My Pi    | [Oh My Pi](https://github.com/can1357/oh-my-pi)                                                            | `omp`              | `omp`, then `/login`               |
-| Pi          | [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)                           | `pi-acp`           | `pi`                               |
-| Hermes      | [Hermes Agent](https://github.com/NousResearch/hermes-agent)                                               | `hermes-acp`       | `hermes-acp --setup`               |
-| Fx          | [Fx](https://fx.sh)                                                                                        | `fx`               | `fx acp`                           |
-| ACP Agent   | Any stdio [ACP agent](https://agentclientprotocol.com/get-started/agents)                                  | user-configured    | agent-owned                        |
-
-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`.
-
-Install Oh My Pi with its [official installer](https://omp.sh) or with
-`bun install -g @oh-my-pi/pi-coding-agent`. T3 Code starts its native stdio ACP mode as `omp acp`;
-do not add `acp` to the configured binary path. API keys and `OMP_PROFILE` overrides can be set on
-the provider instance's **Environment** tab.
-
-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      | Uses the Cursor SDK. Set `CURSOR_API_KEY` in the provider instance environment.              |
+| 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.
+
+### Additional fork providers
+
+The fork also supports Droid, Amp, Copilot, Gemini CLI, Kilo, Oh My Pi, Pi, Hermes, Fx,
+and configurable ACP agents. Enable and configure each instance under **Settings → Providers**
+on the machine that runs it. Keep credentials and configuration scoped to that instance.
+
+Oh My Pi starts as `omp acp`; configure the executable as `omp`, without adding the subcommand.
+Use the configurable ACP provider for other agents that expose stdio ACP.
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index 303d25131935..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,109 +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`.
+```json
+{ "key": "mod+j", "command": "terminal.toggle", "when": "terminalOpen && !terminalFocus" }
+```
 
-`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.
+## Precedence
 
-`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.
+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.
 
-`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.
+## Commands with special behavior
 
-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.
+`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).
 
-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.
+## Reserved shortcuts
 
-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.
+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`.
 
-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.
+Many defaults include `!terminalFocus` so they do not intercept terminal input.
+Keep that condition when remapping them if you want the same behavior.
 
 ## Desktop quit shortcut
 
-Use `Cmd+Q` on macOS or `Ctrl+Q` on Windows and Linux. In the default **Hold** mode, hold the
-shortcut for 1.2 seconds or press it twice within 500 milliseconds. The second press quits
-immediately. You can keep Command or Control held between presses, or release both keys.
-
-Hold mode needs keyboard repeat. If holding does not quit, use two quick presses or choose
-**Quit** from the application menu.
-
-Change **Quit shortcut** in **Settings** → **General** → **Confirmations**. **Direct** quits on
-the first press. **Double press** requires two quick presses and does not accept a hold. The
-application menu's **Quit** action always quits immediately.
-
-## `when` Conditions
-
-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`.
-
-Operators: `!` (not), `&&` (and), `||` (or), and parentheses.
-
-Examples:
-
-- `"when": "terminalFocus"`
-- `"when": "terminalOpen && !terminalFocus"`
-- `"when": "!terminalFocus"`
-
-## 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 db05ccb8ed69..7466cba309ac 100644
--- a/docs/user/providers-antigravity.md
+++ b/docs/user/providers-antigravity.md
@@ -1,198 +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**. Provider setup is not available in the mobile app.
-
-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**. 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 the web or desktop client where you started setup. Choose **Continue**. 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.
-
-| 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 | 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.
-
-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.
+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.
 
-## Account access and errors
+| 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.     |
 
-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].
+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.
 
-After an environment restarts, Google sign-in can show as not checked until an authenticated
-session succeeds. You can continue an existing thread. Antigravity checks saved Google sign-in
-when the session starts. An unchecked status does not require signing in again.
+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.
 
-To check account access and reload models on web or desktop, open **Settings** > **Providers**
-and select the circular arrow beside **Checked** at the top of the page. Its tooltip says
-**Refresh provider status**. On mobile, use **Refresh models** in the 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 on web or desktop. 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 141aa2926add..23de99798956 100644
--- a/docs/user/providers-opencode.md
+++ b/docs/user/providers-opencode.md
@@ -1,93 +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.
 
 ## Approvals
 
-In **Supervised** and **Auto** modes, OpenCode can read normal project files, search files, load
-skills, and update its task list without approval. Files such as `.env` and `.env.local` still
-require approval. `.env.example` does not. OpenCode does not have an AI approval reviewer, so
-**Auto** uses the same permission rules as **Supervised**.
+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.
 
-OpenCode asks before it runs commands, edits files, accesses the web, or accesses directories
-outside the workspace. **Auto-accept edits** also permits file edits without approval.
-**Full access** permits all these actions. Questions that need your answer can still appear.
+**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.
 
-An **Approval** badge means OpenCode needs a decision. Open the thread to see the action and
-choose one of these options:
+## Refresh models, commands, and skills
 
-- **Allow once** permits this request.
-- **Allow for workspace** permits matching requests in other OpenCode sessions in the same
-  workspace. It is not limited to the current thread.
-- **Deny** rejects this request. Use **Stop** to stop the whole turn.
+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.
 
-If a connection error prevents the reply, the approval stays available so you can try again.
+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.
 
-## Progress
-
-T3 Code shows OpenCode's response text and tool results while work runs. The web and desktop apps
-also show its task-list progress. A task-list update does not require approval.
-
-If the OpenCode connection closes unexpectedly, T3 Code shows an error. Send another prompt to
-reconnect to the same OpenCode session.
-
-## Stop a turn
-
-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. After Stop succeeds, pending approvals and questions
-are cleared.
-
-Stop reports an error if OpenCode cannot stop the main session or 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.
-
-## Refresh the model list
-
-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 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.
-
-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 5a83d6161fe9..3f9f36992c34 100644
--- a/docs/user/remote-access.md
+++ b/docs/user/remote-access.md
@@ -1,296 +1,175 @@
-# 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
-
-- Always set `--auth-token` before exposing the server outside localhost.
-  - When you control the process launcher, prefer sending the auth token in a JSON envelope via `--bootstrap-fd <fd>`.
-    With `--bootstrap-fd <fd>`, the launcher starts the server first, then sends a one-shot JSON envelope over the inherited file descriptor. This allows the auth token to be delivered without putting it in process environment or command-line arguments.
-- Treat the token like a password.
-- Prefer binding to trusted interfaces (LAN IP or Tailnet IP) instead of opening all interfaces unless needed.
-
-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.
-
-After an app restart, the desktop app replaces its previous
-local credential. Old local desktop entries are removed from **Authorized clients**
-automatically. Paired phones, browsers, and remote desktop clients keep their access.
-
-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.
+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.
 
-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.
+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.
 
-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.
+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.
 
-### Option 2: Headless Server (CLI)
+## Pair over a LAN or private network
 
-Use this when you want to run the server without a GUI, for example on a remote machine over SSH.
+Use direct pairing when the other device can reach the host's network address.
 
-Run the server with `t3 serve`.
+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.
 
-```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:
-
-- 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.
-
-### Option 3: Desktop-Managed SSH Launch
-
-Use this when you want the desktop app to start or reuse T3 Code on another machine over SSH.
-
-1. Open **Settings** → **Connections**.
-2. Under **Remote Environments**, choose **Add environment**.
-3. Select the SSH launch flow.
-4. Enter the SSH target, such as `user@example.com`.
-5. Confirm the launch. The desktop app probes the host, starts or reuses a remote T3 server, opens a local port forward, and saves the environment.
-
-After setup, the renderer connects to a local forwarded HTTP/WebSocket endpoint. The remote host still owns the actual T3 server, projects, files, git state, terminals, and provider sessions.
+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.
 
-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.
+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.
 
-#### SSH Launch Troubleshooting
+### Tailscale HTTPS
 
-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.
+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.
 
-The remote host must have a compatible Node.js runtime. T3 Code uses the server package's `engines.node` requirement:
+To start a command-line server with Tailscale HTTPS:
 
-```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 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.
-
-## Antigravity Google sign-in
-
-Antigravity runs and saves its Google credentials on the selected environment. You can install
-it and sign in from a remote web or desktop client without an SSH login.
-
-Start in **Settings** > **Providers**, select the environment, then choose **Antigravity**.
-Provider setup is not available in the mobile app.
-
-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 and choose
-**Continue**. Keep the address unchanged. Do not paste the return URL into a thread or bug report.
-
-See [Antigravity setup](./providers-antigravity.md) for installation, expiry, and account changes.
-
-## 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 that port is already in use, choose another with
+`--tailscale-serve-port`. See `npx t3 pair --help` for other pairing options.
 
-If T3 Connect cannot connect, check the date and time on both devices, then try again.
+### Hosted web app
 
-Finish active work before updating because the server restarts briefly. For step-by-step guidance,
-see [Keeping T3 Code in Sync](./updating.md).
+[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.
 
-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).
+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.
 
-## How Pairing Works
+## Desktop-managed SSH
 
-The remote device does not need a long-lived secret up front.
+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.
 
-Instead:
+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:
 
-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).
+
+Bind direct servers to a trusted LAN or tailnet interface. Custom process launchers can pass
+their authentication token through `--bootstrap-fd` rather than command-line arguments; see
+[authentication constraints](../internals/environment-auth.md) for the server boundary.
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
index c8726202bf35..5fd4f91c9327 100644
--- a/docs/user/telemetry.md
+++ b/docs/user/telemetry.md
@@ -1,15 +1,11 @@
-# Anonymous usage data
+# Product usage data
 
-The T3 server sends anonymous product events to PostHog. These events include
-the provider, model, reasoning effort, permission mode, turn result, duration,
-and normalized main-agent token totals when the provider reports them.
+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.
 
-T3 Code does not send prompts, responses, file contents, raw provider events,
-thread IDs, turn IDs, provider instance IDs, authentication tokens, or child
-agent output. Token totals can be complete, partial, or unavailable. Child
-agent token use is not included.
+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.
 
-Set `T3CODE_TELEMETRY_ENABLED=false` before you start the T3 server to stop
-product events from being recorded or sent. The server still derives an
-anonymous identifier during startup and can create its local fallback
-identifier file.
+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/thread-sidebar.md b/docs/user/thread-sidebar.md
index 1932e9ce2a45..e6c89c0343e7 100644
--- a/docs/user/thread-sidebar.md
+++ b/docs/user/thread-sidebar.md
@@ -1,88 +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 does not block 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.
-
-A thread whose composer holds unsent text or attachments shows an amber tint and a pen icon in the
-sidebar, the same marks a new-thread draft uses. On web and desktop, hover the row and choose the
-**X** to discard that draft without opening the thread.
-
-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 fceedc3c2560..a0231856ef69 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -1,35 +1,58 @@
-# 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. 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 every provider and hub.
+
+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/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/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/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/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/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..42cd7a35e473 100644
--- a/packages/client-runtime/src/markdownLinks.test.ts
+++ b/packages/client-runtime/src/markdownLinks.test.ts
@@ -160,7 +160,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..2e455655d005 100644
--- a/packages/client-runtime/src/markdownLinks.ts
+++ b/packages/client-runtime/src/markdownLinks.ts
@@ -342,6 +342,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 95ee3af08ad4..3e0ff9a127de 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 4cba8064f207..2699c4ad0803 100644
--- a/packages/client-runtime/src/relay/managedRelay.test.ts
+++ b/packages/client-runtime/src/relay/managedRelay.test.ts
@@ -9,10 +9,15 @@ 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,
@@ -529,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 d74130322619..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 } : {}),
     });
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/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 8a7aacbdc76a..7f673acfee11 100644
--- a/packages/client-runtime/src/state/pullRequests.ts
+++ b/packages/client-runtime/src/state/pullRequests.ts
@@ -87,8 +87,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>(
@@ -103,7 +103,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 {
@@ -130,7 +130,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.ts b/packages/client-runtime/src/state/server.ts
index b4b908a0e9d0..3da64fdf33a9 100644
--- a/packages/client-runtime/src/state/server.ts
+++ b/packages/client-runtime/src/state/server.ts
@@ -807,6 +807,27 @@ 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}`),
@@ -892,6 +913,7 @@ 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, {
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/threadReducer.test.ts b/packages/client-runtime/src/state/threadReducer.test.ts
index 401980997663..9a9be9b4da09 100644
--- a/packages/client-runtime/src/state/threadReducer.test.ts
+++ b/packages/client-runtime/src/state/threadReducer.test.ts
@@ -1129,33 +1129,52 @@ describe("applyThreadDetailEvent", () => {
   });
 
   describe("thread.turn-diff-completed", () => {
-    it("adds a checkpoint and updates latestTurn", () => {
-      const result = applyThreadDetailEvent(baseThread, {
-        ...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("completed");
-      }
-    });
+    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", () => {
diff --git a/packages/client-runtime/src/state/threadReducer.ts b/packages/client-runtime/src/state/threadReducer.ts
index af47f73c4866..e8872bccf6ed 100644
--- a/packages/client-runtime/src/state/threadReducer.ts
+++ b/packages/client-runtime/src/state/threadReducer.ts
@@ -524,7 +524,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,
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/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/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 4ae705453a8d..c7a532c168b0 100644
--- a/packages/contracts/src/environment.ts
+++ b/packages/contracts/src/environment.ts
@@ -97,6 +97,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),
@@ -108,6 +110,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/ipc.ts b/packages/contracts/src/ipc.ts
index 69e7040104b2..fdd6d02eadf3 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
@@ -1271,6 +1283,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 a6c31043cc5c..c79f988d669c 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/providerRuntime.test.ts b/packages/contracts/src/providerRuntime.test.ts
index 362b72317ddd..4e5dbebcaa39 100644
--- a/packages/contracts/src/providerRuntime.test.ts
+++ b/packages/contracts/src/providerRuntime.test.ts
@@ -1,7 +1,12 @@
-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, RuntimeEventRaw } from "./providerRuntime.ts";
+import {
+  classifyTaskAgentKind,
+  ProviderRuntimeEvent,
+  RuntimeEventRaw,
+  type ProviderRuntimeEventType,
+} from "./providerRuntime.ts";
 
 const decodeRuntimeEvent = Schema.decodeUnknownSync(ProviderRuntimeEvent);
 const decodeRuntimeEventRaw = Schema.decodeUnknownSync(RuntimeEventRaw);
@@ -25,6 +30,10 @@ 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",
diff --git a/packages/contracts/src/providerRuntime.ts b/packages/contracts/src/providerRuntime.ts
index bb4b6e3893a7..41d0465d10ea 100644
--- a/packages/contracts/src/providerRuntime.ts
+++ b/packages/contracts/src/providerRuntime.ts
@@ -204,6 +204,7 @@ const ProviderRuntimeEventType = Schema.Literals([
   "hook.completed",
   "tool.progress",
   "tool.summary",
+  "tool.denied",
   "auth.status",
   "account.updated",
   "account.rate-limits.updated",
diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts
index 2e1582611c30..3942d1249ee3 100644
--- a/packages/contracts/src/settings.test.ts
+++ b/packages/contracts/src/settings.test.ts
@@ -23,6 +23,92 @@ const encodeServerSettings = Schema.encodeSync(ServerSettings);
 const decodeOhMyPiSettings = Schema.decodeUnknownSync(OhMyPiSettings);
 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("");
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 3e573b97390a..1dac9e54d271 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,
@@ -258,9 +259,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([])),
   ),
@@ -366,6 +364,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(
@@ -469,7 +481,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 } }),
     ),
@@ -507,7 +519,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 } }),
     ),
@@ -565,7 +577,7 @@ export const CursorSettings = makeProviderSettingsSchema(
         providerSettingsForm: { hidden: true },
       }),
     ),
-    customModels: Schema.Array(Schema.String).pipe(
+    customModels: Schema.Array(CustomModelSetting).pipe(
       Schema.withDecodingDefault(Effect.succeed([])),
       Schema.annotateKey({ providerSettingsForm: { hidden: true } }),
     ),
@@ -591,7 +603,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 } }),
     ),
@@ -676,7 +688,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 } }),
     ),
@@ -726,7 +738,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 } }),
     ),
@@ -1092,6 +1104,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
@@ -1210,6 +1226,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;
 
@@ -1316,14 +1336,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.
@@ -1343,13 +1363,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({
@@ -1359,7 +1379,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({
@@ -1367,7 +1387,7 @@ 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)),
 });
 
 const DroidSettingsPatch = Schema.Struct({
@@ -1386,6 +1406,7 @@ 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),
@@ -1449,6 +1470,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;
 
@@ -1467,7 +1492,6 @@ 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),
diff --git a/packages/contracts/src/usage.ts b/packages/contracts/src/usage.ts
index 8c099ddb33aa..c36a4557c294 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/shared/package.json b/packages/shared/package.json
index 5eb57dc1d499..4c28f7adfff3 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -227,6 +227,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"
@@ -262,6 +270,10 @@
     "./nodeSqliteClient": {
       "types": "./src/nodeSqliteClient.ts",
       "import": "./src/nodeSqliteClient.ts"
+    },
+    "./hostClassification": {
+      "types": "./src/hostClassification.ts",
+      "import": "./src/hostClassification.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/favicon.test.ts b/packages/shared/src/favicon.test.ts
index c29727544efa..ce80a079b3fd 100644
--- a/packages/shared/src/favicon.test.ts
+++ b/packages/shared/src/favicon.test.ts
@@ -1,6 +1,50 @@
 import { describe, expect, it } from "@effect/vitest";
 
-import { explicitFaviconUrl, faviconUrlForPage, toolActivityFaviconUrl } from "./favicon.ts";
+import {
+  explicitFaviconUrl,
+  faviconUrlForOrigin,
+  faviconUrlForPage,
+  toolActivityFaviconUrl,
+} from "./favicon.ts";
+
+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("faviconUrlForPage", () => {
   it("uses the page origin instead of a third-party favicon service", () => {
diff --git a/packages/shared/src/favicon.ts b/packages/shared/src/favicon.ts
index 88bf46a985bc..a3286b28e99a 100644
--- a/packages/shared/src/favicon.ts
+++ b/packages/shared/src/favicon.ts
@@ -1,3 +1,5 @@
+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.
@@ -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..7703421d5c29
--- /dev/null
+++ b/packages/shared/src/orchestrationTiming.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { formatDuration, formatElapsed } 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");
+  });
+});
+
+describe("formatElapsed", () => {
+  it("formats a long run across midnight", () => {
+    expect(formatElapsed("2026-09-03T22:00:00Z", "2026-09-04T04:59:50Z")).toBe("6h 59m 50s");
+  });
+});
diff --git a/packages/shared/src/orchestrationTiming.ts b/packages/shared/src/orchestrationTiming.ts
index 6914e1320d32..956226e19a7d 100644
--- a/packages/shared/src/orchestrationTiming.ts
+++ b/packages/shared/src/orchestrationTiming.ts
@@ -12,13 +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 < 10_000) {
+    const tenths = Math.round(durationMs / 100) / 10;
+    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`;
+  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 formatElapsed(startIso: string, endIso: string | undefined): string | null {
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/serverSettings.test.ts b/packages/shared/src/serverSettings.test.ts
index 64b0e1b8337b..1f847412b6c7 100644
--- a/packages/shared/src/serverSettings.test.ts
+++ b/packages/shared/src/serverSettings.test.ts
@@ -322,6 +322,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..dfd5b742e4e4 100644
--- a/packages/shared/src/serverSettings.ts
+++ b/packages/shared/src/serverSettings.ts
@@ -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 392b13910f01..119e59e1b191 100644
--- a/packages/shared/src/shell.test.ts
+++ b/packages/shared/src/shell.test.ts
@@ -2,11 +2,15 @@ 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,
@@ -391,6 +395,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 29c0c67cd84a..a5483dd434fc 100644
--- a/packages/shared/src/shell.ts
+++ b/packages/shared/src/shell.ts
@@ -552,7 +552,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>,
@@ -613,12 +614,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..7dda675ee95c
--- /dev/null
+++ b/packages/ssh/src/runnerProcess.test.ts
@@ -0,0 +1,167 @@
+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),
+    );
+  },
+);
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..04dbce65af60 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -440,13 +440,14 @@ require_installed_t3_cli() {
   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/patches/@pierre%2Fdiffs@1.3.0-beta.10.patch b/patches/@pierre%2Fdiffs@1.3.0-beta.10.patch
index b342d4b5dd13..3b558fe56552 100644
--- a/patches/@pierre%2Fdiffs@1.3.0-beta.10.patch
+++ b/patches/@pierre%2Fdiffs@1.3.0-beta.10.patch
@@ -60,6 +60,18 @@ 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
+@@ -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) {
 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 463f2bc78939..90f1ce7fb510 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': c087c47b657c44ddce2b0ec8237d675086414134e91829c4b4edd009ec86893e
   '@react-native-ai/apple@0.12.0': 2d09870c2848d185cb05b53ed823a46e12dba519324d8dd8e584e28731990f9d
   '@react-native-menu/menu@2.0.0': f63d256bf6a97a873b5e628eb595bd6ef0075ddd5bdd890fc920f7a6024290dd
   '@react-navigation/native-stack@7.17.6': e667c3cef8c78bb9ff4882ee5bd23a432247b843060a9499eb5f07e9e2295552
@@ -248,7 +248,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=c087c47b657c44ddce2b0ec8237d675086414134e91829c4b4edd009ec86893e)(@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))
@@ -604,7 +604,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=c087c47b657c44ddce2b0ec8237d675086414134e91829c4b4edd009ec86893e)(@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)
@@ -13872,7 +13872,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=c087c47b657c44ddce2b0ec8237d675086414134e91829c4b4edd009ec86893e)(@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)
@@ -13886,7 +13886,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=c087c47b657c44ddce2b0ec8237d675086414134e91829c4b4edd009ec86893e)(@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)
diff --git a/scripts/build-desktop-artifact.test.ts b/scripts/build-desktop-artifact.test.ts
index 4021c9b23167..200145ff5c21 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* (
@@ -1069,6 +1070,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* () {
@@ -1097,7 +1101,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", () =>
@@ -1116,7 +1120,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", () =>
@@ -1264,11 +1268,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(
@@ -1495,7 +1500,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", () => {
@@ -1735,7 +1740,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"] },
       ]);
@@ -2229,7 +2234,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 2f06bd8e9325..725ab95eb4c3 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 de5b9b8e5cbe..07c5647da1a4 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 6ac0bd310f88..f0281071c775 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";
 
@@ -171,8 +173,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"),
+      },
     ],
   );
 });
@@ -196,10 +204,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 0f482ca79f94..af3ba1bd513b 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 d6bdd264035e..47eeddbde552 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -21,6 +21,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.