diff --git a/.agents/skills/test-t3-mobile/SKILL.md b/.agents/skills/test-t3-mobile/SKILL.md
index f3e3dcfd8ce..98c1c3b2022 100644
--- a/.agents/skills/test-t3-mobile/SKILL.md
+++ b/.agents/skills/test-t3-mobile/SKILL.md
@@ -66,7 +66,7 @@ Use these client origins:
 - Android Emulator: `http://10.0.2.2:<server-port>`
 - Physical device: bind the backend to `0.0.0.0` and use the host's reachable LAN origin
 
-Always enter the complete `http://` origin; the mobile host field otherwise assumes HTTPS. When testing web and mobile together, run `vp run dev --home-dir <base-dir> --host 127.0.0.1` instead and do not launch a second backend over the same base directory.
+Enter the complete `http://` origin to make the test transport explicit. Bare IP addresses default to HTTP, while bare hostnames default to HTTPS. When testing web and mobile together, run `vp run dev --home-dir <base-dir> --host 127.0.0.1` instead and do not launch a second backend over the same base directory.
 
 ## Start or reuse Metro safely
 
diff --git a/.fork/customizations.yaml b/.fork/customizations.yaml
index 51f519cef61..aed9065f3ab 100644
--- a/.fork/customizations.yaml
+++ b/.fork/customizations.yaml
@@ -910,6 +910,15 @@
     those imports to make a conflict go away, because nothing in the fork's
     copy references them any more.
 
+    Same spirit, opposite direction: Sidebar.logic.ts keeps upstream's
+    searchSidebarThreadsByTitle (and its tests) even though nothing in the
+    fork's copy of SidebarV2 renders it. Upstream's inline sidebar thread
+    search (#4769) lives in the chrome this customization replaced, so the
+    2026-08-02 sync deliberately did not adopt its UI; the pure helper stays
+    so a future port into SidebarV2ChromeRows is a design decision, not an
+    archaeology dig. It is an orphan on purpose — do not "clean it up", and
+    do not count its tests as coverage of a rendered path.
+
     The thread list pays for its own scroll gutter. scrollbar-gutter:stable
     reserves the scrollbar inside the list's padding box, so the symmetric px-2
     from Figma 113:3718 spends 8px of air on the left and 8 plus the scrollbar
@@ -1132,16 +1141,15 @@
     index.css. Routing through --fork-font-* keeps the values scoped under the
     fork marker while the fallbacks leave an unmarked build on DM Sans.
     The terminal's font logic lives in custom/terminalFont.ts rather than in
-    the drawer: xterm takes its font from a constructor option instead of the
-    cascade, so --font-mono has to be resolved by hand and the cell grid
-    re-measured once the webfont lands — xterm sizes columns at open(), and a
-    webfont can land after that. The drawer keeps two one-line call sites, and
-    the font-load probe is derived from the resolved stack rather than
-    hardcoded, so it cannot go stale on a face swap and an unmarked build
-    names a local system face and fetches nothing. The re-fit must also
-    propagate to the PTY via resizeTerminal — nothing in the drawer subscribes
-    to onResize, and a re-fit that corrects only xterm's local grid leaves the
-    PTY wrapping to the stale, fallback-measured width.
+    the drawer: the ghostty surface takes its font as a creation option
+    instead of from the cascade, so --font-mono has to be resolved by hand at
+    the mount site. The drawer keeps one one-line call site passing
+    font.family. Unlike the xterm era there is no fork refit shim: the
+    surface itself waits on document.fonts before measuring the cell grid and
+    re-measures on loadingdone, so the webfont-landing-late case is upstream's
+    to handle now. In an unmarked build the cascade read returns upstream's
+    stack and no Geist byte is fetched; the module's fallback only engages
+    when the read comes back empty.
     Geist Mono is listed AHEAD of SF Mono: upstream puts SF Mono first, which
     means on macOS its bundled mono webfont never renders at all. body / pre,
     code are re-declared under
@@ -1167,6 +1175,10 @@
   watch:
     - apps/web/src/index.css
     - apps/web/src/components/ThreadTerminalDrawer.tsx
+    # The fork deleted its own refit shim because the surface waits on
+    # document.fonts before measuring and re-measures on loadingdone. If
+    # upstream stops, the terminal silently measures against fallback metrics.
+    - apps/web/src/terminal/ghostty/surface.ts
     # No fence, but load-bearing: ships the resolved --font-sans / --font-mono
     # into the previewed page — see FORK-CUSTOMIZATION-DECISIONS.md.
     - apps/web/src/browser/annotationTheme.ts
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 07438b251c5..9bc321dac0d 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -30,6 +30,7 @@ body:
         - apps/web
         - apps/server
         - apps/desktop
+        - apps/mobile
         - packages/contracts or packages/shared
         - Build, CI, or release tooling
         - Docs
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index 53aab5166a5..3c9424fb322 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -30,6 +30,7 @@ body:
         - apps/web
         - apps/server
         - apps/desktop
+        - apps/mobile
         - packages/contracts or packages/shared
         - Build, CI, or release tooling
         - Docs
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2fea7cafa3e..4e4d233377a 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -12,6 +12,10 @@ on:
       - custom
       # fork:end ci-on-custom
 
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   check:
     name: Check
@@ -22,6 +26,11 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -75,6 +84,11 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -104,13 +118,20 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/scripts...
 
       - name: Install mobile native static analysis tools
         run: brew bundle install --file apps/mobile/Brewfile
@@ -127,13 +148,20 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/scripts...
 
       - name: Exercise release-only workflow steps
         run: node scripts/release-smoke.ts
diff --git a/.github/workflows/deploy-relay.yml b/.github/workflows/deploy-relay.yml
index 0b297e3ddea..c28225659b8 100644
--- a/.github/workflows/deploy-relay.yml
+++ b/.github/workflows/deploy-relay.yml
@@ -41,13 +41,20 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=t3code-relay...
 
       - name: Deploy production relay stage
         id: deploy
diff --git a/.github/workflows/mobile-eas-preview.yml b/.github/workflows/mobile-eas-preview.yml
index 32e45fef54e..d53602f8f5e 100644
--- a/.github/workflows/mobile-eas-preview.yml
+++ b/.github/workflows/mobile-eas-preview.yml
@@ -2,13 +2,18 @@ name: Mobile EAS Preview
 
 on:
   pull_request:
-    types: [opened, reopened, synchronize, labeled, unlabeled]
+    types: [opened, reopened, synchronize, labeled]
 
 jobs:
   preview:
     name: EAS Preview
-    if: contains(github.event.pull_request.labels.*.name, '🚀 Mobile Continuous Deployment')
+    if: |
+      contains(github.event.pull_request.labels.*.name, '🚀 Mobile Continuous Deployment') &&
+      (github.event.action != 'labeled' || github.event.label.name == '🚀 Mobile Continuous Deployment')
     runs-on: blacksmith-8vcpu-ubuntu-2404
+    concurrency:
+      group: mobile-eas-preview-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
     permissions:
       contents: read
       pull-requests: write
@@ -34,6 +39,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          # No sparse-checkout here: it makes actions/checkout fetch with
+          # --filter=blob:none, and eas-cli archives the project via
+          # `git clone --depth 1 file://<workspace>`, which fails (exit 128)
+          # when the partial clone can't serve the unfetched blobs.
 
       - name: Setup Vite+
         if: steps.expo-token.outputs.present == 'true'
@@ -41,7 +50,9 @@ jobs:
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/mobile...
 
       - name: Expose pnpm
         if: steps.expo-token.outputs.present == 'true'
diff --git a/.github/workflows/mobile-eas-production.yml b/.github/workflows/mobile-eas-production.yml
index 685df85e57c..2e61de6039e 100644
--- a/.github/workflows/mobile-eas-production.yml
+++ b/.github/workflows/mobile-eas-production.yml
@@ -57,6 +57,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          # No sparse-checkout here: it makes actions/checkout fetch with
+          # --filter=blob:none, and eas-cli archives the project via
+          # `git clone --depth 1 file://<workspace>`, which fails (exit 128)
+          # when the partial clone can't serve the unfetched blobs.
 
       - name: Setup Vite+
         if: steps.expo-token.outputs.present == 'true'
@@ -64,7 +68,9 @@ jobs:
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/mobile...
 
       - name: Expose pnpm
         if: steps.expo-token.outputs.present == 'true'
diff --git a/.github/workflows/mobile-showcase-screenshots.yml b/.github/workflows/mobile-showcase-screenshots.yml
index 36dfb61f73f..3eaaf508e31 100644
--- a/.github/workflows/mobile-showcase-screenshots.yml
+++ b/.github/workflows/mobile-showcase-screenshots.yml
@@ -37,13 +37,22 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/mobile...
+              - --filter=@t3tools/scripts...
+              - --filter=t3...
 
       - name: Expose pnpm
         run: |
@@ -77,13 +86,22 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/mobile...
+              - --filter=@t3tools/scripts...
+              - --filter=t3...
 
       - name: Expose pnpm
         run: |
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d2db1451009..da6c0da248d 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -40,6 +40,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - id: check
         name: Compare HEAD to last nightly tag
@@ -89,6 +93,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -197,6 +205,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -274,14 +286,19 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
-          fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=t3...
 
       - name: Build node-pty linux-x64 prebuild
         shell: bash
@@ -364,14 +381,21 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
-          fetch-depth: 0
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
         with:
           node-version-file: package.json
           cache: true
-          run-install: true
+          run-install: |
+            args:
+              - --filter=@t3tools/desktop...
+              - --filter=t3...
+              - --filter=@t3tools/scripts...
 
       - name: Setup Rust
         uses: dtolnay/rust-toolchain@stable
@@ -662,6 +686,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -737,6 +765,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -858,6 +890,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
@@ -972,6 +1008,10 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.app_token.outputs.token }}
           persist-credentials: true
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - id: app_bot
         name: Resolve GitHub App bot identity
@@ -1042,6 +1082,10 @@ jobs:
         uses: actions/checkout@v6
         with:
           ref: ${{ needs.preflight.outputs.ref }}
+          sparse-checkout: |
+            /*
+            !/.repos/
+          sparse-checkout-cone-mode: false
 
       - name: Setup Vite+
         uses: voidzero-dev/setup-vp@v1
diff --git a/apps/desktop/src/app/DesktopAppIdentity.test.ts b/apps/desktop/src/app/DesktopAppIdentity.test.ts
index 8e5c7a86126..86a8677f06a 100644
--- a/apps/desktop/src/app/DesktopAppIdentity.test.ts
+++ b/apps/desktop/src/app/DesktopAppIdentity.test.ts
@@ -54,7 +54,6 @@ const makeElectronAppLayer = (calls: ElectronAppCalls) =>
         calls.setAboutPanelOptions.push(options);
       }),
     setAppUserModelId: () => Effect.void,
-    requestSingleInstanceLock: Effect.succeed(true),
     getAppMetrics: Effect.succeed([]),
     isDefaultProtocolClient: () => Effect.succeed(false),
     setAsDefaultProtocolClient: () => Effect.succeed(true),
diff --git a/apps/desktop/src/app/DesktopAppIdentity.ts b/apps/desktop/src/app/DesktopAppIdentity.ts
index 385e694338d..0be55d633e6 100644
--- a/apps/desktop/src/app/DesktopAppIdentity.ts
+++ b/apps/desktop/src/app/DesktopAppIdentity.ts
@@ -45,6 +45,27 @@ const normalizeCommitHash = (value: string): Option.Option<string> => {
     : Option.none();
 };
 
+export const resolveUserDataPath = Effect.gen(function* () {
+  const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const legacyPath = environment.path.join(
+    environment.appDataDirectory,
+    environment.legacyUserDataDirName,
+  );
+  const legacyPathExists = yield* fileSystem.exists(legacyPath).pipe(
+    Effect.mapError(
+      (cause) =>
+        new DesktopUserDataPathResolutionError({
+          legacyPath,
+          cause,
+        }),
+    ),
+  );
+  return legacyPathExists
+    ? legacyPath
+    : environment.path.join(environment.appDataDirectory, environment.userDataDirName);
+}).pipe(Effect.withSpan("desktop.appIdentity.resolveUserDataPath"));
+
 export const make = Effect.gen(function* () {
   const assets = yield* DesktopAssets.DesktopAssets;
   const electronApp = yield* ElectronApp.ElectronApp;
@@ -90,24 +111,11 @@ export const make = Effect.gen(function* () {
     return commitHash;
   });
 
-  const resolveUserDataPath = Effect.gen(function* () {
-    const legacyPath = environment.path.join(
-      environment.appDataDirectory,
-      environment.legacyUserDataDirName,
-    );
-    const legacyPathExists = yield* fileSystem.exists(legacyPath).pipe(
-      Effect.mapError(
-        (cause) =>
-          new DesktopUserDataPathResolutionError({
-            legacyPath,
-            cause,
-          }),
-      ),
-    );
-    return legacyPathExists
-      ? legacyPath
-      : environment.path.join(environment.appDataDirectory, environment.userDataDirName);
-  }).pipe(Effect.withSpan("desktop.appIdentity.resolveUserDataPath"));
+  const userDataPath = resolveUserDataPath.pipe(
+    Effect.provide(
+      yield* Effect.context<DesktopEnvironment.DesktopEnvironment | FileSystem.FileSystem>(),
+    ),
+  );
 
   const configure = Effect.gen(function* () {
     const commitHash = yield* resolveAboutCommitHash;
@@ -136,7 +144,7 @@ export const make = Effect.gen(function* () {
   }).pipe(Effect.withSpan("desktop.appIdentity.configure"));
 
   return DesktopAppIdentity.of({
-    resolveUserDataPath,
+    resolveUserDataPath: userDataPath,
     configure,
   });
 });
diff --git a/apps/desktop/src/app/DesktopClerk.test.ts b/apps/desktop/src/app/DesktopClerk.test.ts
index 96d1e8cf465..ef0c6db9eac 100644
--- a/apps/desktop/src/app/DesktopClerk.test.ts
+++ b/apps/desktop/src/app/DesktopClerk.test.ts
@@ -33,17 +33,38 @@ vi.mock("@clerk/electron/storage", () => ({
   storage: storageMock,
 }));
 
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as ElectronWindow from "../electron/ElectronWindow.ts";
 import * as DesktopClerk from "./DesktopClerk.ts";
 import * as DesktopEnvironment from "./DesktopEnvironment.ts";
 
-const makeDesktopClerkLayer = (isDevelopment = true) => {
+const makeDesktopClerkLayer = (isDevelopment = true, events: string[] = []) => {
   const environment = DesktopEnvironment.DesktopEnvironment.of({
     stateDir: "/tmp/t3-state",
     isDevelopment,
+    appDataDirectory: "/tmp/app-data",
+    userDataDirName: isDevelopment ? "t3code-dev" : "t3code",
+    legacyUserDataDirName: isDevelopment ? "T3 Code (Dev)" : "T3 Code (Alpha)",
+    path: { join: (...parts: ReadonlyArray<string>) => parts.join("/") },
   } as unknown as DesktopEnvironment.DesktopEnvironment["Service"]);
 
+  const electronApp = {
+    setPath: (name: string, value: string) =>
+      Effect.sync(() => {
+        events.push(`setPath:${name}:${value}`);
+      }),
+  } as unknown as ElectronApp.ElectronApp["Service"];
+
   return DesktopClerk.layer.pipe(
-    Layer.provide(Layer.succeed(DesktopEnvironment.DesktopEnvironment, environment)),
+    Layer.provide(
+      Layer.mergeAll(
+        Layer.succeed(DesktopEnvironment.DesktopEnvironment, environment),
+        Layer.succeed(ElectronApp.ElectronApp, electronApp),
+        FileSystem.layerNoop({ exists: () => Effect.succeed(false) }),
+      ),
+    ),
   );
 };
 
@@ -66,11 +87,15 @@ describe("DesktopClerk", () => {
 
   it.effect("acquires and releases the SDK bridge with the layer", () => {
     const cleanup = vi.fn();
+    const events: string[] = [];
     storageMock.mockReturnValue(storageAdapter);
-    createClerkBridgeMock.mockReturnValue({ cleanup });
+    createClerkBridgeMock.mockImplementation(() => {
+      events.push("createClerkBridge");
+      return { cleanup, isPrimaryInstance: true };
+    });
 
     return Effect.gen(function* () {
-      yield* Effect.scoped(Layer.build(makeDesktopClerkLayer()));
+      yield* Effect.scoped(Layer.build(makeDesktopClerkLayer(true, events)));
 
       assert.deepEqual(createClerkBridgeMock.mock.calls, [
         [
@@ -82,6 +107,10 @@ describe("DesktopClerk", () => {
         ],
       ]);
       assert.equal(cleanup.mock.calls.length, 1);
+      // The bridge acquires Electron's single-instance lock at creation, and
+      // the lock both lives in and creates the userData directory — so the
+      // real path must be set before the bridge exists.
+      assert.deepEqual(events, ["setPath:userData:/tmp/app-data/t3code-dev", "createClerkBridge"]);
       storageMock.mockClear();
       createClerkBridgeMock.mockClear();
     });
@@ -135,11 +164,67 @@ describe("DesktopClerk", () => {
     });
   });
 
+  it.effect("registers the second-instance handler in the primary instance", () => {
+    storageMock.mockReturnValue(storageAdapter);
+    createClerkBridgeMock.mockReturnValue({ cleanup: vi.fn(), isPrimaryInstance: true });
+    const quit = vi.fn();
+    const registeredEvents: string[] = [];
+    const electronApp = {
+      quit: Effect.sync(quit),
+      on: (eventName: string) =>
+        Effect.sync(() => {
+          registeredEvents.push(eventName);
+        }),
+    } as unknown as ElectronApp.ElectronApp["Service"];
+    const electronWindow = {} as ElectronWindow.ElectronWindow["Service"];
+
+    return Effect.gen(function* () {
+      const clerk = yield* DesktopClerk.DesktopClerk;
+      const exit = yield* Effect.exit(Effect.scoped(clerk.configure));
+
+      assert.isTrue(Exit.isSuccess(exit));
+      assert.equal(quit.mock.calls.length, 0);
+      assert.deepEqual(registeredEvents, ["second-instance"]);
+    }).pipe(
+      Effect.provide(makeDesktopClerkLayer()),
+      Effect.provideService(ElectronApp.ElectronApp, electronApp),
+      Effect.provideService(ElectronWindow.ElectronWindow, electronWindow),
+    );
+  });
+
+  it.effect("quits and interrupts startup in a secondary instance", () => {
+    storageMock.mockReturnValue(storageAdapter);
+    createClerkBridgeMock.mockReturnValue({ cleanup: vi.fn(), isPrimaryInstance: false });
+    const quit = vi.fn();
+    const registeredEvents: string[] = [];
+    const electronApp = {
+      quit: Effect.sync(quit),
+      on: (eventName: string) =>
+        Effect.sync(() => {
+          registeredEvents.push(eventName);
+        }),
+    } as unknown as ElectronApp.ElectronApp["Service"];
+    const electronWindow = {} as ElectronWindow.ElectronWindow["Service"];
+
+    return Effect.gen(function* () {
+      const clerk = yield* DesktopClerk.DesktopClerk;
+      const exit = yield* Effect.exit(Effect.scoped(clerk.configure));
+
+      assert.isTrue(Exit.hasInterrupts(exit));
+      assert.equal(quit.mock.calls.length, 1);
+      assert.deepEqual(registeredEvents, []);
+    }).pipe(
+      Effect.provide(makeDesktopClerkLayer()),
+      Effect.provideService(ElectronApp.ElectronApp, electronApp),
+      Effect.provideService(ElectronWindow.ElectronWindow, electronWindow),
+    );
+  });
+
   it.each([
     { isDevelopment: true, scheme: "t3code-dev" },
     { isDevelopment: false, scheme: "t3code" },
   ])("configures the SDK with the $scheme renderer origin", ({ isDevelopment, scheme }) => {
-    const bridge = { cleanup: vi.fn() };
+    const bridge = { cleanup: vi.fn(), isPrimaryInstance: true };
     storageMock.mockReturnValue(storageAdapter);
     createClerkBridgeMock.mockReturnValue(bridge);
 
diff --git a/apps/desktop/src/app/DesktopClerk.ts b/apps/desktop/src/app/DesktopClerk.ts
index 0548f96fc55..af4d53b2b05 100644
--- a/apps/desktop/src/app/DesktopClerk.ts
+++ b/apps/desktop/src/app/DesktopClerk.ts
@@ -14,6 +14,7 @@ import { clerkFrontendApiHostnameFromPublishableKey } from "@t3tools/shared/rela
 import * as ElectronApp from "../electron/ElectronApp.ts";
 import * as ElectronProtocol from "../electron/ElectronProtocol.ts";
 import * as ElectronWindow from "../electron/ElectronWindow.ts";
+import * as DesktopAppIdentity from "./DesktopAppIdentity.ts";
 import * as DesktopEnvironment from "./DesktopEnvironment.ts";
 
 declare const __T3CODE_BUILD_CLERK_PUBLISHABLE_KEY__: string | undefined;
@@ -111,6 +112,17 @@ export function createDesktopClerkBridge(stateDir: string, isDevelopment: boolea
 
 export const make = Effect.gen(function* () {
   const environment = yield* DesktopEnvironment.DesktopEnvironment;
+  const electronApp = yield* ElectronApp.ElectronApp;
+
+  // Electron scopes the single-instance lock to the userData directory and
+  // creates that directory when the lock is acquired. The SDK bridge takes
+  // the lock at creation, so userData must already point at the real
+  // directory here — under the default productName-derived path, acquiring
+  // the lock would create "T3 Code (Alpha)" and make the legacy-install
+  // detection in resolveUserDataPath match on fresh installs.
+  const userDataPath = yield* DesktopAppIdentity.resolveUserDataPath;
+  yield* electronApp.setPath("userData", userDataPath);
+
   // fork:begin fork-clerk-launch-resilience — see .fork/customizations.yaml#fork-clerk-launch-resilience
   // A build with no baked Clerk publishable key cannot sign in, so the
   // bridge is guaranteed dead weight — and a live hazard: createClerkBridge
@@ -123,15 +135,17 @@ export const make = Effect.gen(function* () {
   // including loud initialization AND cleanup failures, which must stay
   // fatal there rather than hide behind a warning — except its redundant
   // scheme re-registration, which createDesktopClerkBridge above suppresses
-  // so a post-"ready" layer build cannot die on it. The singleton-lock
-  // behavior in configure below is bridge-independent either way.
+  // so a post-"ready" layer build cannot die on it. The bridge now also
+  // carries the single-instance lock (acquired at creation), so the keyless
+  // path takes the lock directly in configure below.
+  let bridge: ReturnType<typeof createDesktopClerkBridge> | undefined;
   if (desktopClerkFrontendApiHostname === undefined) {
     yield* Effect.logWarning(
       "No Clerk publishable key in this build; skipping the Clerk bridge (cloud sign-in unavailable).",
     );
   } else {
     // fork:end fork-clerk-launch-resilience
-    yield* Effect.acquireRelease(
+    bridge = yield* Effect.acquireRelease(
       Effect.try({
         try: () => createDesktopClerkBridge(environment.stateDir, environment.isDevelopment),
         catch: (cause) =>
@@ -163,7 +177,20 @@ export const make = Effect.gen(function* () {
       const context = yield* Effect.context<ElectronWindow.ElectronWindow>();
       const runPromise = Effect.runPromiseWith(context);
 
-      if (!(yield* electronApp.requestSingleInstanceLock)) {
+      // The SDK bridge holds Electron's single-instance lock (acquired at
+      // bridge creation) so OAuth deep-link callbacks on Windows/Linux are
+      // forwarded to the running app. In a secondary instance the bridge has
+      // already begun quitting the app; app.quit() is asynchronous, so stop
+      // bootstrap here before whenReady can fire.
+      // fork:begin fork-clerk-launch-resilience — keyless builds have no bridge
+      // With the bridge skipped nothing has taken the lock, so take it
+      // directly; the optional read keeps plain-Node unit imports safe, where
+      // the electron shim exposes no app object.
+      const isPrimaryInstance = bridge
+        ? bridge.isPrimaryInstance
+        : (Electron.app?.requestSingleInstanceLock() ?? true);
+      // fork:end fork-clerk-launch-resilience
+      if (!isPrimaryInstance) {
         yield* electronApp.quit;
         return yield* Effect.interrupt;
       }
diff --git a/apps/desktop/src/app/DesktopClerkForkRegistrarSuppression.test.ts b/apps/desktop/src/app/DesktopClerkForkRegistrarSuppression.test.ts
index 7aef53fb1bb..e388f4e608b 100644
--- a/apps/desktop/src/app/DesktopClerkForkRegistrarSuppression.test.ts
+++ b/apps/desktop/src/app/DesktopClerkForkRegistrarSuppression.test.ts
@@ -55,7 +55,7 @@ describe("DesktopClerk keyed-build registrar suppression", () => {
   });
 
   it("suppresses the bridge's scheme re-registration, then restores the registrar", () => {
-    const bridge = { cleanup: vi.fn() };
+    const bridge = { cleanup: vi.fn(), isPrimaryInstance: true };
     createClerkBridgeMock.mockImplementation(() => {
       // What @clerk/electron does unconditionally when given a renderer.
       // Post-"ready" this throws in a real boot; suppression makes it a
diff --git a/apps/desktop/src/app/DesktopClerkForkSkip.test.ts b/apps/desktop/src/app/DesktopClerkForkSkip.test.ts
index e56a7259fa8..62a07df937a 100644
--- a/apps/desktop/src/app/DesktopClerkForkSkip.test.ts
+++ b/apps/desktop/src/app/DesktopClerkForkSkip.test.ts
@@ -7,20 +7,34 @@
  * a keyless build has nothing to win. Unlike DesktopClerk.test.ts, this file
  * deliberately does NOT define __T3CODE_BUILD_CLERK_PUBLISHABLE_KEY__, so the
  * module under test resolves no hostname and takes the skip path.
+ *
+ * Upstream's bridge acquires Electron's single-instance lock at creation and
+ * configure reads bridge.isPrimaryInstance; with the bridge skipped nothing
+ * has taken the lock, so the fork takes it directly off Electron.app in
+ * configure. The configure tests below pin that behavior on both outcomes —
+ * a suite that only checked the service exists would pass with every keyless
+ * launch silently admitting a second instance.
  */
 
 import { assert, describe, it } from "@effect/vitest";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Logger from "effect/Logger";
-import { vi } from "vite-plus/test";
+import { beforeEach, vi } from "vite-plus/test";
 
-const { createClerkBridgeMock, storageMock } = vi.hoisted(() => ({
+const { createClerkBridgeMock, requestSingleInstanceLockMock, storageMock } = vi.hoisted(() => ({
   createClerkBridgeMock: vi.fn(),
+  requestSingleInstanceLockMock: vi.fn(),
   storageMock: vi.fn(),
 }));
 
+vi.mock("electron", () => ({
+  app: { requestSingleInstanceLock: requestSingleInstanceLockMock },
+}));
+
 vi.mock("@clerk/electron", () => ({
   createClerkBridge: createClerkBridgeMock,
 }));
@@ -29,21 +43,78 @@ vi.mock("@clerk/electron/storage", () => ({
   storage: storageMock,
 }));
 
+import * as ElectronApp from "../electron/ElectronApp.ts";
+import * as ElectronWindow from "../electron/ElectronWindow.ts";
 import * as DesktopClerk from "./DesktopClerk.ts";
 import * as DesktopEnvironment from "./DesktopEnvironment.ts";
 
-const makeDesktopClerkLayer = () => {
+interface ConfigureProbe {
+  readonly registeredEvents: string[];
+  readonly quits: () => number;
+  readonly electronApp: ElectronApp.ElectronApp["Service"];
+}
+
+function configureProbe(): ConfigureProbe {
+  const registeredEvents: string[] = [];
+  let quits = 0;
+  const electronApp = {
+    setPath: () => Effect.void,
+    quit: Effect.sync(() => {
+      quits += 1;
+    }),
+    on: (eventName: string) =>
+      Effect.sync(() => {
+        registeredEvents.push(eventName);
+      }),
+  } as unknown as ElectronApp.ElectronApp["Service"];
+  return { registeredEvents, quits: () => quits, electronApp };
+}
+
+const makeDesktopClerkLayer = (electronApp: ElectronApp.ElectronApp["Service"]) => {
   const environment = DesktopEnvironment.DesktopEnvironment.of({
     stateDir: "/tmp/t3-state",
     isDevelopment: false,
+    appDataDirectory: "/tmp/app-data",
+    userDataDirName: "t3code",
+    legacyUserDataDirName: "T3 Code (Alpha)",
+    path: { join: (...parts: ReadonlyArray<string>) => parts.join("/") },
   } as unknown as DesktopEnvironment.DesktopEnvironment["Service"]);
 
   return DesktopClerk.layer.pipe(
-    Layer.provide(Layer.succeed(DesktopEnvironment.DesktopEnvironment, environment)),
+    Layer.provide(
+      Layer.mergeAll(
+        Layer.succeed(DesktopEnvironment.DesktopEnvironment, environment),
+        Layer.succeed(ElectronApp.ElectronApp, electronApp),
+        FileSystem.layerNoop({ exists: () => Effect.succeed(false) }),
+      ),
+    ),
   );
 };
 
+const runConfigure = (probe: ConfigureProbe) =>
+  Effect.gen(function* () {
+    const context = yield* Effect.scoped(Layer.build(makeDesktopClerkLayer(probe.electronApp)));
+    const service = Context.get(context, DesktopClerk.DesktopClerk);
+    return yield* Effect.exit(
+      Effect.scoped(
+        service.configure.pipe(
+          Effect.provideService(ElectronApp.ElectronApp, probe.electronApp),
+          Effect.provideService(
+            ElectronWindow.ElectronWindow,
+            {} as unknown as ElectronWindow.ElectronWindow["Service"],
+          ),
+        ),
+      ),
+    );
+  });
+
 describe("DesktopClerk keyless-build skip", () => {
+  beforeEach(() => {
+    createClerkBridgeMock.mockReset();
+    requestSingleInstanceLockMock.mockReset();
+    storageMock.mockReset();
+  });
+
   it.effect("skips the bridge, warns, and still provides the service", () => {
     const messages: unknown[] = [];
     const logger = Logger.make(({ message }) => {
@@ -51,9 +122,10 @@ describe("DesktopClerk keyless-build skip", () => {
     });
 
     return Effect.gen(function* () {
-      const context = yield* Effect.scoped(Layer.build(makeDesktopClerkLayer())).pipe(
-        Effect.provide(Logger.layer([logger], { mergeWithExisting: false })),
-      );
+      const probe = configureProbe();
+      const context = yield* Effect.scoped(
+        Layer.build(makeDesktopClerkLayer(probe.electronApp)),
+      ).pipe(Effect.provide(Logger.layer([logger], { mergeWithExisting: false })));
 
       // The bridge was never attempted — the skip is deterministic, not a
       // survived failure.
@@ -64,10 +136,43 @@ describe("DesktopClerk keyless-build skip", () => {
       assert.isTrue(
         messages.some((message) => String(message).includes("skipping the Clerk bridge")),
       );
-      // The service is still provided; its bridge-independent configure
-      // (single-instance lock) must keep working on the degraded path.
       const service = Context.get(context, DesktopClerk.DesktopClerk);
       assert.isDefined(service.configure);
     });
   });
+
+  it.effect("takes the lock directly and keeps the primary instance running", () =>
+    Effect.gen(function* () {
+      requestSingleInstanceLockMock.mockReturnValue(true);
+      const probe = configureProbe();
+
+      const exit = yield* runConfigure(probe);
+
+      // No bridge holds the lock on this path, so configure must have asked
+      // Electron for it — a `?? true` fallback that never asks would admit
+      // every second instance.
+      assert.equal(requestSingleInstanceLockMock.mock.calls.length, 1);
+      assert.isTrue(Exit.isSuccess(exit));
+      assert.equal(probe.quits(), 0);
+      // Deep-link forwarding survives the degraded path: the primary still
+      // listens for second instances.
+      assert.deepEqual(probe.registeredEvents, ["second-instance"]);
+    }),
+  );
+
+  it.effect("quits and interrupts bootstrap when another instance holds the lock", () =>
+    Effect.gen(function* () {
+      requestSingleInstanceLockMock.mockReturnValue(false);
+      const probe = configureProbe();
+
+      const exit = yield* runConfigure(probe);
+
+      assert.equal(requestSingleInstanceLockMock.mock.calls.length, 1);
+      // The secondary instance stops bootstrap before whenReady can fire:
+      // quit, then interrupt — and never registers the handler.
+      assert.equal(probe.quits(), 1);
+      assert.isTrue(Exit.hasInterrupts(exit));
+      assert.deepEqual(probe.registeredEvents, []);
+    }),
+  );
 });
diff --git a/apps/desktop/src/app/DesktopLifecycle.test.ts b/apps/desktop/src/app/DesktopLifecycle.test.ts
index e5ce72f8e48..978e000a7f5 100644
--- a/apps/desktop/src/app/DesktopLifecycle.test.ts
+++ b/apps/desktop/src/app/DesktopLifecycle.test.ts
@@ -29,7 +29,6 @@ describe("DesktopLifecycle", () => {
         setName: () => Effect.void,
         setAboutPanelOptions: () => Effect.void,
         setAppUserModelId: () => Effect.void,
-        requestSingleInstanceLock: Effect.succeed(true),
         getAppMetrics: Effect.succeed([]),
         isDefaultProtocolClient: () => Effect.succeed(false),
         setAsDefaultProtocolClient: () => Effect.succeed(true),
diff --git a/apps/desktop/src/electron/ElectronApp.test.ts b/apps/desktop/src/electron/ElectronApp.test.ts
index 077b343959c..ac14f56ad1a 100644
--- a/apps/desktop/src/electron/ElectronApp.test.ts
+++ b/apps/desktop/src/electron/ElectronApp.test.ts
@@ -14,7 +14,6 @@ const {
   quitMock,
   relaunchMock,
   removeListenerMock,
-  requestSingleInstanceLockMock,
   setAboutPanelOptionsMock,
   setAppUserModelIdMock,
   setAsDefaultProtocolClientMock,
@@ -35,7 +34,6 @@ const {
   quitMock: vi.fn(),
   relaunchMock: vi.fn(),
   removeListenerMock: vi.fn(),
-  requestSingleInstanceLockMock: vi.fn(() => true),
   setAboutPanelOptionsMock: vi.fn(),
   setAppUserModelIdMock: vi.fn(),
   setAsDefaultProtocolClientMock: vi.fn(() => true),
@@ -67,7 +65,6 @@ vi.mock("electron", () => ({
     quit: quitMock,
     relaunch: relaunchMock,
     removeListener: removeListenerMock,
-    requestSingleInstanceLock: requestSingleInstanceLockMock,
     runningUnderARM64Translation: false,
     setAboutPanelOptions: setAboutPanelOptionsMock,
     setAsDefaultProtocolClient: setAsDefaultProtocolClientMock,
diff --git a/apps/desktop/src/electron/ElectronApp.ts b/apps/desktop/src/electron/ElectronApp.ts
index 5f8052f902d..73323617195 100644
--- a/apps/desktop/src/electron/ElectronApp.ts
+++ b/apps/desktop/src/electron/ElectronApp.ts
@@ -56,7 +56,6 @@ export class ElectronApp extends Context.Service<
       options: Electron.AboutPanelOptionsOptions,
     ) => Effect.Effect<void>;
     readonly setAppUserModelId: (id: string) => Effect.Effect<void>;
-    readonly requestSingleInstanceLock: Effect.Effect<boolean>;
     readonly getAppMetrics: Effect.Effect<ReadonlyArray<Electron.ProcessMetric>>;
     readonly isDefaultProtocolClient: (protocol: string) => Effect.Effect<boolean>;
     readonly setAsDefaultProtocolClient: (
@@ -153,7 +152,6 @@ export const make = ElectronApp.of({
     Effect.sync(() => {
       Electron.app.setAppUserModelId(id);
     }),
-  requestSingleInstanceLock: Effect.sync(() => Electron.app.requestSingleInstanceLock()),
   getAppMetrics: Effect.sync(() => Electron.app.getAppMetrics()),
   isDefaultProtocolClient: (protocol) =>
     Effect.sync(() => Electron.app.isDefaultProtocolClient(protocol)),
diff --git a/apps/desktop/src/electron/ElectronProtocol.test.ts b/apps/desktop/src/electron/ElectronProtocol.test.ts
index 92e30000427..2db85dafc4d 100644
--- a/apps/desktop/src/electron/ElectronProtocol.test.ts
+++ b/apps/desktop/src/electron/ElectronProtocol.test.ts
@@ -57,7 +57,7 @@ describe("ElectronProtocol", () => {
           assert.equal(yield* Effect.promise(() => response.text()), "ok");
           assert.include(
             response.headers.get("content-security-policy") ?? "",
-            "script-src 'self' 'unsafe-inline' https://clerk.t3.codes https://challenges.cloudflare.com",
+            "script-src 'self' 'unsafe-inline' 'wasm-unsafe-eval' https://clerk.t3.codes https://challenges.cloudflare.com",
           );
           assert.include(
             response.headers.get("content-security-policy") ?? "",
@@ -212,6 +212,7 @@ describe("ElectronProtocol", () => {
     assert.deepEqual(directives["script-src"], [
       "'self'",
       "'unsafe-inline'",
+      "'wasm-unsafe-eval'",
       "https://clerk.t3.codes",
       "https://challenges.cloudflare.com",
     ]);
diff --git a/apps/desktop/src/electron/ElectronProtocol.ts b/apps/desktop/src/electron/ElectronProtocol.ts
index 03c7ef64fd7..9d5a47806b3 100644
--- a/apps/desktop/src/electron/ElectronProtocol.ts
+++ b/apps/desktop/src/electron/ElectronProtocol.ts
@@ -71,6 +71,7 @@ export function makeDesktopContentSecurityPolicy(input: DesktopProtocolRegistrat
   const scriptSources = [
     "'self'",
     "'unsafe-inline'",
+    "'wasm-unsafe-eval'",
     ...(clerkOrigin ? [clerkOrigin] : []),
     "https://challenges.cloudflare.com",
   ];
diff --git a/apps/desktop/src/telemetry/DesktopTelemetryPublisher.test.ts b/apps/desktop/src/telemetry/DesktopTelemetryPublisher.test.ts
index 475be3da151..36cdcb50b6b 100644
--- a/apps/desktop/src/telemetry/DesktopTelemetryPublisher.test.ts
+++ b/apps/desktop/src/telemetry/DesktopTelemetryPublisher.test.ts
@@ -34,7 +34,6 @@ function makeElectronAppLayer(
     setName: () => Effect.void,
     setAboutPanelOptions: () => Effect.void,
     setAppUserModelId: () => Effect.void,
-    requestSingleInstanceLock: Effect.succeed(true),
     getAppMetrics: Effect.sync(() => {
       onMetricsRead();
       return metrics;
diff --git a/apps/desktop/src/window/DesktopApplicationMenu.test.ts b/apps/desktop/src/window/DesktopApplicationMenu.test.ts
index 34fc4447146..f04a49f82af 100644
--- a/apps/desktop/src/window/DesktopApplicationMenu.test.ts
+++ b/apps/desktop/src/window/DesktopApplicationMenu.test.ts
@@ -39,7 +39,6 @@ const electronAppLayer = Layer.succeed(ElectronApp.ElectronApp, {
   setName: () => Effect.void,
   setAboutPanelOptions: () => Effect.void,
   setAppUserModelId: () => Effect.void,
-  requestSingleInstanceLock: Effect.succeed(true),
   getAppMetrics: Effect.succeed([]),
   isDefaultProtocolClient: () => Effect.succeed(false),
   setAsDefaultProtocolClient: () => Effect.succeed(true),
diff --git a/apps/mobile/app.config.ts b/apps/mobile/app.config.ts
index 4a0c761f2c6..9a51373cfd0 100644
--- a/apps/mobile/app.config.ts
+++ b/apps/mobile/app.config.ts
@@ -161,7 +161,7 @@ const config: ExpoConfig = {
   slug: "t3-code",
   platforms: ["ios", "android"],
   scheme: variant.scheme,
-  version: "0.1.0",
+  version: "1.0.1",
   runtimeVersion: {
     // Fingerprint (not appVersion) so an OTA only reaches binaries whose native
     // project — native deps, config plugins, AND patches/ — matches the update.
@@ -181,6 +181,9 @@ const config: ExpoConfig = {
   ios: {
     icon: variant.assets.iosIcon,
     supportsTablet: true,
+    // Multitasking-capable iPad apps cannot rotate programmatically, so the
+    // showcase capture build requires full screen (see infoPlist below).
+    requireFullScreen: process.env.T3_SHOWCASE_CAPTURE_BUILD === "1",
     bundleIdentifier: iosBundleIdentifier,
     // Pin code signing to the T3 Tools team so non-interactive `expo run:ios`
     // does not fall back to a personal team (which cannot sign app groups,
@@ -197,6 +200,21 @@ const config: ExpoConfig = {
       NSLocalNetworkUsageDescription:
         "Allow T3 Code to connect to T3 Code servers on your local network or tailnet.",
       ITSAppUsesNonExemptEncryption: false,
+      // The App Store screenshot harness rotates the iPad interface from
+      // inside the app (CI denies osascript the Accessibility access that
+      // Simulator menu scripting needs), and iPadOS ignores programmatic
+      // orientation requests for multitasking-capable apps — so the capture
+      // build opts out of multitasking and declares landscape support.
+      ...(process.env.T3_SHOWCASE_CAPTURE_BUILD === "1"
+        ? {
+            "UISupportedInterfaceOrientations~ipad": [
+              "UIInterfaceOrientationPortrait",
+              "UIInterfaceOrientationPortraitUpsideDown",
+              "UIInterfaceOrientationLandscapeLeft",
+              "UIInterfaceOrientationLandscapeRight",
+            ],
+          }
+        : {}),
     },
   },
   android: {
@@ -275,10 +293,12 @@ const config: ExpoConfig = {
       "expo-camera",
       {
         cameraPermission: "Allow T3 Code to access your camera so you can scan pairing QR codes.",
+        microphonePermission: false,
         barcodeScannerEnabled: true,
         recordAudioAndroid: false,
       },
     ],
+    ["expo-image-picker", { photosPermission: false, microphonePermission: false }],
     [
       "expo-splash-screen",
       {
diff --git a/apps/mobile/modules/t3-native-controls/ios/T3NativeControlsModule.swift b/apps/mobile/modules/t3-native-controls/ios/T3NativeControlsModule.swift
index 7781b164a2c..23cf4720d8c 100644
--- a/apps/mobile/modules/t3-native-controls/ios/T3NativeControlsModule.swift
+++ b/apps/mobile/modules/t3-native-controls/ios/T3NativeControlsModule.swift
@@ -1,5 +1,6 @@
 import ExpoModulesCore
 import Security
+import UIKit
 
 public final class T3NativeControlsModule: Module {
   public func definition() -> ModuleDefinition {
@@ -32,6 +33,50 @@ public final class T3NativeControlsModule: Module {
       return arguments[flagIndex + 1]
     }
 
+    Function("getShowcaseOrientation") { () -> String? in
+      let arguments = ProcessInfo.processInfo.arguments
+      guard
+        let flagIndex = arguments.firstIndex(of: "--showcaseOrientation"),
+        arguments.indices.contains(flagIndex + 1)
+      else {
+        return nil as String?
+      }
+      return arguments[flagIndex + 1]
+    }
+
+    // Rotates the interface without Simulator menu UI scripting, which CI
+    // runners cannot perform (osascript is denied Accessibility access there).
+    AsyncFunction("applyShowcaseOrientation") { (orientation: String) in
+      guard #available(iOS 16.0, *) else { return }
+      let mask: UIInterfaceOrientationMask = orientation == "landscape" ? .landscapeRight : .portrait
+      for case let windowScene as UIWindowScene in UIApplication.shared.connectedScenes {
+        windowScene.requestGeometryUpdate(.iOS(interfaceOrientations: mask)) { error in
+          NSLog("T3NativeControls applyShowcaseOrientation(\(orientation)) failed: \(error)")
+        }
+        for window in windowScene.windows {
+          window.rootViewController?.setNeedsUpdateOfSupportedInterfaceOrientations()
+        }
+      }
+    }.runOnQueue(.main)
+
+    // The geometry request above can fail transiently (for example before the
+    // scene is foreground-active), so callers poll this until it settles.
+    // Screen bounds — not the scene's interface orientation — decide the
+    // answer because they match the captured framebuffer: with iPadOS
+    // windowing active, a floating landscape window still reports a portrait
+    // screen, and screenshots would come out portrait.
+    AsyncFunction("getInterfaceOrientation") { () -> String in
+      guard
+        let windowScene = UIApplication.shared.connectedScenes
+          .compactMap({ $0 as? UIWindowScene })
+          .first
+      else {
+        return "unknown"
+      }
+      let bounds = windowScene.screen.coordinateSpace.bounds
+      return bounds.width > bounds.height ? "landscape" : "portrait"
+    }.runOnQueue(.main)
+
     Function("prepareShowcaseCapture") {
       for itemClass in [kSecClassGenericPassword, kSecClassInternetPassword] {
         SecItemDelete([kSecClass as String: itemClass] as CFDictionary)
diff --git a/apps/mobile/modules/t3-terminal/README.md b/apps/mobile/modules/t3-terminal/README.md
index 768e3c0704c..32670b893c7 100644
--- a/apps/mobile/modules/t3-terminal/README.md
+++ b/apps/mobile/modules/t3-terminal/README.md
@@ -40,7 +40,7 @@ fails, run `xcodebuild -downloadComponent MetalToolchain`.
 ## Rebuilding libghostty-vt for Android
 
 The checked-in Android shared libraries and headers are pinned to the revision recorded in
-`Vendor/libghostty-vt/VERSION`. Set `ANDROID_NDK_HOME` and run:
+`native/libghostty-vt/VERSION` at the repository root. Set `ANDROID_NDK_HOME` and run:
 
 ```bash
 apps/mobile/modules/t3-terminal/scripts/build-libghostty-android.sh
diff --git a/apps/mobile/modules/t3-terminal/THIRD_PARTY_NOTICES.md b/apps/mobile/modules/t3-terminal/THIRD_PARTY_NOTICES.md
index 990dd4bbe9c..b06f18eadce 100644
--- a/apps/mobile/modules/t3-terminal/THIRD_PARTY_NOTICES.md
+++ b/apps/mobile/modules/t3-terminal/THIRD_PARTY_NOTICES.md
@@ -18,13 +18,14 @@ Ghostty's MIT license applies to the vendored framework. Keep this notice in syn
 ## Ghostty / libghostty-vt
 
 The Android terminal renderer vendors upstream `libghostty-vt` shared libraries and C headers.
+The web terminal vendors a WebAssembly build from the same revision and uses the same C ABI.
 
 - Upstream project: https://github.com/ghostty-org/ghostty
 - Vendored revision: `9f62873bf195e4d8a762d768a1405a5f2f7b1697`
 - License: MIT
 
-Ghostty's MIT license applies to the vendored Android libraries. Keep this notice in sync when
-updating `Vendor/libghostty-vt`.
+Ghostty's MIT license applies to the vendored Android and web libraries. Keep this notice and both
+artifacts in sync when updating the repository-root `native/libghostty-vt`.
 
 ## MesloLGS NF (Android terminal font)
 
diff --git a/apps/mobile/modules/t3-terminal/android/src/main/cpp/CMakeLists.txt b/apps/mobile/modules/t3-terminal/android/src/main/cpp/CMakeLists.txt
index 0273ff6c864..a43a2981b67 100644
--- a/apps/mobile/modules/t3-terminal/android/src/main/cpp/CMakeLists.txt
+++ b/apps/mobile/modules/t3-terminal/android/src/main/cpp/CMakeLists.txt
@@ -13,7 +13,7 @@ add_library(t3terminal SHARED t3_terminal_jni.cpp)
 
 target_include_directories(
   t3terminal
-  PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/../../../../Vendor/libghostty-vt/include"
+  PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../../../native/libghostty-vt/include"
 )
 
 target_link_options(
diff --git a/apps/mobile/modules/t3-terminal/scripts/build-libghostty-android.sh b/apps/mobile/modules/t3-terminal/scripts/build-libghostty-android.sh
index 7b9aa9b6dc6..55d994d3b36 100755
--- a/apps/mobile/modules/t3-terminal/scripts/build-libghostty-android.sh
+++ b/apps/mobile/modules/t3-terminal/scripts/build-libghostty-android.sh
@@ -4,7 +4,7 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 MODULE_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
-VENDOR_DIR="${MODULE_DIR}/Vendor/libghostty-vt"
+VENDOR_DIR="${MODULE_DIR}/../../../../native/libghostty-vt"
 PATCH_DIR="${SCRIPT_DIR}/libghostty-android-patches"
 
 GHOSTTY_REVISION="${GHOSTTY_REVISION:-9f62873bf195e4d8a762d768a1405a5f2f7b1697}"
diff --git a/apps/mobile/package.json b/apps/mobile/package.json
index 9a5e64aa46f..c12ca979bf2 100644
--- a/apps/mobile/package.json
+++ b/apps/mobile/package.json
@@ -11,7 +11,7 @@
     "start:dev": "APP_VARIANT=development expo start",
     "start:preview": "APP_VARIANT=preview expo start",
     "start:prod": "APP_VARIANT=production expo start",
-    "showcase": "APP_VARIANT=development EXPO_PUBLIC_SHOWCASE=1 expo start --dev-client --scheme t3code-dev --clear",
+    "showcase": "APP_VARIANT=production EXPO_PUBLIC_SHOWCASE=1 expo start --dev-client --scheme t3code --clear",
     "screenshots": "node ../../scripts/mobile-showcase.ts",
     "android": "EXPO_NO_GIT_STATUS=1 expo prebuild --clean --platform android && expo run:android",
     "android:dev": "APP_VARIANT=development EXPO_NO_GIT_STATUS=1 expo prebuild --clean --platform android && REACT_NATIVE_PACKAGER_HOSTNAME=localhost expo run:android",
diff --git a/apps/mobile/src/Stack.tsx b/apps/mobile/src/Stack.tsx
index 76a9399772d..719a6a4ad59 100644
--- a/apps/mobile/src/Stack.tsx
+++ b/apps/mobile/src/Stack.tsx
@@ -15,6 +15,7 @@ import { DynamicColorIOS, Platform, Pressable, ScrollView, StyleSheet } from "re
 import { useResolveClassNames } from "uniwind";
 
 import { AppText as Text } from "./components/AppText";
+import { getCompactBrandHeaderOptions } from "./components/CompactBrandTitle";
 import { ArchivedThreadsRouteScreen } from "./features/archive/ArchivedThreadsRouteScreen";
 import { useAgentNotificationNavigation } from "./features/agent-awareness/notificationNavigation";
 import { ClerkSettingsSheetDetentProvider } from "./features/cloud/ClerkSettingsSheetDetent";
@@ -392,7 +393,7 @@ export const RootStack = createNativeStackNavigator({
         ...GLASS_HEADER_OPTIONS,
         contentStyle: { backgroundColor: "transparent" },
         headerBackVisible: false,
-        title: "Threads",
+        ...getCompactBrandHeaderOptions(),
       },
     }),
     Thread: createNativeStackScreen({
diff --git a/apps/mobile/src/components/AppSymbol.tsx b/apps/mobile/src/components/AppSymbol.tsx
index ac813bdbe0a..d4c7088fe50 100644
--- a/apps/mobile/src/components/AppSymbol.tsx
+++ b/apps/mobile/src/components/AppSymbol.tsx
@@ -22,6 +22,7 @@ import {
   IconChevronUp,
   IconCircleCheck,
   IconCircleXFilled,
+  IconClock,
   IconCopy,
   IconDeviceDesktop,
   IconDots,
@@ -96,6 +97,7 @@ const ANDROID_ICON_BY_SF_SYMBOL: Partial<Record<SFSymbol, Icon>> = {
   camera: IconCamera,
   checkmark: IconCheck,
   "checkmark.circle": IconCircleCheck,
+  clock: IconClock,
   "chevron.down": IconChevronDown,
   "chevron.left": IconChevronLeft,
   "chevron.left.forwardslash.chevron.right": IconCode,
diff --git a/apps/mobile/src/components/CompactBrandTitle.tsx b/apps/mobile/src/components/CompactBrandTitle.tsx
new file mode 100644
index 00000000000..f0710e85d36
--- /dev/null
+++ b/apps/mobile/src/components/CompactBrandTitle.tsx
@@ -0,0 +1,121 @@
+import Constants from "expo-constants";
+import type {
+  NativeStackHeaderItem,
+  NativeStackNavigationOptions,
+} from "@react-navigation/native-stack";
+import { Platform, View } from "react-native";
+
+import { AppText as Text } from "./AppText";
+import { T3Wordmark } from "./T3Wordmark";
+import { IPAD_HOME_TITLE_OFFSET } from "../lib/layoutMetrics";
+import { resolveMobileStageLabel } from "../lib/mobileBranding";
+import { useThemeColor } from "../lib/useThemeColor";
+import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../native/native-glass";
+
+// Native leading items inherit different UIKit margins than title views.
+const IOS_NATIVE_LEADING_TITLE_OFFSET = -6;
+const IPAD_NATIVE_LEADING_TITLE_OFFSET = 7;
+
+/**
+ * Compact brand lockup sized for native navigation bars.
+ */
+export function CompactBrandTitle(
+  props: {
+    readonly nativeLeadingItem?: boolean;
+  } = {},
+) {
+  const iconColor = useThemeColor("--color-icon");
+  const mutedColor = useThemeColor("--color-foreground-muted");
+  const subtleColor = useThemeColor("--color-subtle");
+  const stageLabel = resolveMobileStageLabel(Constants.expoConfig?.extra?.appVariant);
+  const titleOffset =
+    Platform.OS !== "ios"
+      ? 0
+      : props.nativeLeadingItem
+        ? Platform.isPad
+          ? IPAD_NATIVE_LEADING_TITLE_OFFSET
+          : IOS_NATIVE_LEADING_TITLE_OFFSET
+        : Platform.isPad
+          ? IPAD_HOME_TITLE_OFFSET
+          : 0;
+
+  return (
+    <View
+      aria-level={1}
+      accessibilityLabel="T3 Code, Threads"
+      accessible
+      role="heading"
+      style={{
+        alignItems: "center",
+        flexDirection: "row",
+        gap: 6,
+        marginLeft: titleOffset,
+      }}
+    >
+      <T3Wordmark color={iconColor} height={15} />
+      <Text
+        style={{
+          color: mutedColor,
+          fontFamily: "DMSans-Medium",
+          fontSize: 21,
+          letterSpacing: -0.5,
+        }}
+      >
+        Code
+      </Text>
+      <View
+        style={{
+          backgroundColor: subtleColor,
+          borderRadius: 999,
+          paddingHorizontal: 6,
+          paddingVertical: 2,
+        }}
+      >
+        <Text
+          style={{
+            color: mutedColor,
+            fontFamily: "DMSans-Bold",
+            fontSize: 9,
+            letterSpacing: 0.9,
+            textTransform: "uppercase",
+          }}
+        >
+          {stageLabel}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+export function renderCompactBrandTitle() {
+  return <CompactBrandTitle />;
+}
+
+export function renderCompactBrandHeaderItems(): NativeStackHeaderItem[] {
+  return [
+    {
+      element: <CompactBrandTitle nativeLeadingItem />,
+      hidesSharedBackground: true,
+      type: "custom",
+    },
+  ];
+}
+
+export function getCompactBrandHeaderOptions(
+  fallbackTitleStyle?: NativeStackNavigationOptions["headerTitleStyle"],
+): NativeStackNavigationOptions {
+  if (Platform.OS === "ios" && NATIVE_LIQUID_GLASS_SUPPORTED) {
+    return {
+      headerTitle: "Threads",
+      headerTitleStyle: { color: "transparent", fontSize: 18, fontWeight: "800" },
+      title: "Threads",
+      unstable_headerLeftItems: renderCompactBrandHeaderItems,
+    };
+  }
+
+  return {
+    headerTitle: renderCompactBrandTitle,
+    headerTitleStyle: fallbackTitleStyle,
+    title: "Threads",
+  };
+}
diff --git a/apps/mobile/src/components/ProjectFavicon.tsx b/apps/mobile/src/components/ProjectFavicon.tsx
index 772d5e8cc14..d52aa05b446 100644
--- a/apps/mobile/src/components/ProjectFavicon.tsx
+++ b/apps/mobile/src/components/ProjectFavicon.tsx
@@ -1,14 +1,21 @@
 import { SymbolView } from "./AppSymbol";
 import { Image } from "expo-image";
-import { useState } from "react";
+import { useLayoutEffect, useMemo, useState } from "react";
 import { View } from "react-native";
 import type { EnvironmentId } from "@t3tools/contracts";
-import { isProjectFaviconFallbackUrl } from "@t3tools/shared/projectFavicon";
+import {
+  getProjectFaviconCacheKey,
+  isProjectFaviconFallbackUrl,
+} from "@t3tools/shared/projectFavicon";
 import { useThemeColor } from "../lib/useThemeColor";
 import { useAssetUrl } from "../state/assets";
-
-/* ─── Favicon cache (matches web pattern) ────────────────────────────── */
-const loadedFaviconUrls = new Set<string>();
+import {
+  beginProjectFaviconRequest,
+  createProjectFaviconRequest,
+  hasLoadedProjectFavicon,
+  markProjectFaviconFailed,
+  markProjectFaviconLoaded,
+} from "./projectFaviconCache";
 
 /* ─── Component ──────────────────────────────────────────────────────── */
 export function ProjectFavicon(props: {
@@ -26,10 +33,15 @@ export function ProjectFavicon(props: {
       : { _tag: "project-favicon", cwd: props.workspaceRoot },
   );
   const renderableFaviconUrl = isProjectFaviconFallbackUrl(faviconUrl) ? null : faviconUrl;
+  const cacheKey =
+    renderableFaviconUrl && props.workspaceRoot
+      ? getProjectFaviconCacheKey(props.environmentId, props.workspaceRoot, renderableFaviconUrl)
+      : null;
 
   return (
     <ProjectFaviconImage
-      key={faviconUrl}
+      key={cacheKey}
+      cacheKey={cacheKey}
       faviconUrl={renderableFaviconUrl}
       open={props.open}
       projectTitle={props.projectTitle}
@@ -39,18 +51,32 @@ export function ProjectFavicon(props: {
 }
 
 function ProjectFaviconImage(props: {
+  readonly cacheKey: string | null;
   readonly faviconUrl: string | null;
   readonly open?: boolean;
   readonly projectTitle: string;
   readonly size: number;
 }) {
   const iconMuted = useThemeColor("--color-icon-subtle");
+  const faviconRequest = useMemo(
+    () => createProjectFaviconRequest(props.cacheKey, props.faviconUrl),
+    [props.cacheKey, props.faviconUrl],
+  );
+  const [activeFaviconRequest, setActiveFaviconRequest] = useState<typeof faviconRequest>(null);
+  useLayoutEffect(() => {
+    if (faviconRequest === null) return;
+
+    const endRequest = beginProjectFaviconRequest(faviconRequest);
+    setActiveFaviconRequest(faviconRequest);
+    return endRequest;
+  }, [faviconRequest]);
 
   const [status, setStatus] = useState<"loading" | "loaded" | "error">(() =>
-    props.faviconUrl && loadedFaviconUrls.has(props.faviconUrl) ? "loaded" : "loading",
+    hasLoadedProjectFavicon(props.cacheKey) ? "loaded" : "loading",
   );
 
-  const showImage = props.faviconUrl !== null && status === "loaded";
+  const requestIsActive = faviconRequest !== null && activeFaviconRequest === faviconRequest;
+  const showImage = requestIsActive && status === "loaded";
 
   return (
     <View
@@ -72,11 +98,15 @@ function ProjectFaviconImage(props: {
       ) : null}
 
       {/* Favicon image (hidden until loaded) */}
-      {props.faviconUrl ? (
+      {requestIsActive ? (
         <Image
+          key={faviconRequest.faviconUrl}
           source={{
-            uri: props.faviconUrl,
+            uri: faviconRequest.faviconUrl,
+            cacheKey: faviconRequest.cacheKey,
           }}
+          cachePolicy="memory-disk"
+          recyclingKey={faviconRequest.cacheKey}
           accessibilityLabel={`${props.projectTitle} favicon`}
           style={{
             width: props.size,
@@ -86,10 +116,13 @@ function ProjectFaviconImage(props: {
           }}
           contentFit="contain"
           onLoad={() => {
-            if (props.faviconUrl) loadedFaviconUrls.add(props.faviconUrl);
+            if (!markProjectFaviconLoaded(faviconRequest)) return;
             setStatus("loaded");
           }}
-          onError={() => setStatus("error")}
+          onError={() => {
+            if (!markProjectFaviconFailed(faviconRequest)) return;
+            setStatus("error");
+          }}
         />
       ) : null}
     </View>
diff --git a/apps/mobile/src/components/projectFaviconCache.test.ts b/apps/mobile/src/components/projectFaviconCache.test.ts
new file mode 100644
index 00000000000..d0582a8b5f5
--- /dev/null
+++ b/apps/mobile/src/components/projectFaviconCache.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  beginProjectFaviconRequest,
+  createProjectFaviconRequest,
+  hasLoadedProjectFavicon,
+  markProjectFaviconFailed,
+  markProjectFaviconLoaded,
+} from "./projectFaviconCache";
+
+describe("project favicon cache", () => {
+  it("ignores callbacks from a superseded URL", () => {
+    const cacheKey = "environment-1:/workspace:v1-favicon.svg";
+    const expiredUrl = "https://environment.example/api/assets/expired/v1-favicon.svg";
+    const refreshedUrl = "https://environment.example/api/assets/refreshed/v1-favicon.svg";
+
+    const expiredRequest = createProjectFaviconRequest(cacheKey, expiredUrl);
+    const endExpiredRequest = beginProjectFaviconRequest(expiredRequest);
+    markProjectFaviconLoaded(expiredRequest);
+    const refreshedRequest = createProjectFaviconRequest(cacheKey, refreshedUrl);
+    const endRefreshedRequest = beginProjectFaviconRequest(refreshedRequest);
+
+    expect(markProjectFaviconLoaded(expiredRequest)).toBe(false);
+    expect(markProjectFaviconFailed(expiredRequest)).toBe(false);
+    expect(hasLoadedProjectFavicon(cacheKey)).toBe(true);
+    expect(markProjectFaviconFailed(refreshedRequest)).toBe(true);
+    expect(hasLoadedProjectFavicon(cacheKey)).toBe(false);
+
+    endRefreshedRequest();
+    endExpiredRequest();
+  });
+
+  it("evicts the URL that actually failed", () => {
+    const cacheKey = "environment-1:/workspace:v2-favicon.svg";
+    const faviconUrl = "https://environment.example/api/assets/current/v2-favicon.svg";
+    const request = createProjectFaviconRequest(cacheKey, faviconUrl);
+    const endRequest = beginProjectFaviconRequest(request);
+
+    markProjectFaviconLoaded(request);
+
+    expect(markProjectFaviconFailed(request)).toBe(true);
+    expect(hasLoadedProjectFavicon(cacheKey)).toBe(false);
+
+    endRequest();
+  });
+
+  it("does not supersede a request until the next request begins", () => {
+    const cacheKey = "environment-1:/workspace:v3-favicon.svg";
+    const committedUrl = "https://environment.example/api/assets/current/v3-favicon.svg";
+    const abandonedUrl = "https://environment.example/api/assets/abandoned/v3-favicon.svg";
+    const committedRequest = createProjectFaviconRequest(cacheKey, committedUrl);
+    const endCommittedRequest = beginProjectFaviconRequest(committedRequest);
+
+    createProjectFaviconRequest(cacheKey, abandonedUrl);
+
+    expect(markProjectFaviconLoaded(committedRequest)).toBe(true);
+    expect(hasLoadedProjectFavicon(cacheKey)).toBe(true);
+
+    endCommittedRequest();
+  });
+
+  it("requires a cache key before creating a URL-bearing request", () => {
+    const firstUrl = "https://environment.example/api/assets/first/favicon.svg";
+    const secondUrl = "https://environment.example/api/assets/second/favicon.svg";
+
+    expect(createProjectFaviconRequest(null, firstUrl)).toBeNull();
+    expect(createProjectFaviconRequest(null, secondUrl)).toBeNull();
+  });
+
+  it("restores the remaining active URL when a newer request ends", () => {
+    const cacheKey = "environment-1:/workspace:v4-favicon.svg";
+    const firstRequest = createProjectFaviconRequest(
+      cacheKey,
+      "https://environment.example/api/assets/first/v4-favicon.svg",
+    );
+    const secondRequest = createProjectFaviconRequest(
+      cacheKey,
+      "https://environment.example/api/assets/second/v4-favicon.svg",
+    );
+    const endFirstRequest = beginProjectFaviconRequest(firstRequest);
+    const endSecondRequest = beginProjectFaviconRequest(secondRequest);
+
+    expect(markProjectFaviconLoaded(firstRequest)).toBe(false);
+    endSecondRequest();
+    expect(markProjectFaviconLoaded(firstRequest)).toBe(true);
+    endFirstRequest();
+    expect(markProjectFaviconLoaded(firstRequest)).toBe(false);
+  });
+
+  it("bounds remembered loaded revisions", () => {
+    const firstCacheKey = "environment-1:/workspace:revision-0";
+    let lastCacheKey = firstCacheKey;
+
+    for (let revision = 0; revision < 300; revision++) {
+      lastCacheKey = `environment-1:/workspace:revision-${revision}`;
+      const request = createProjectFaviconRequest(
+        lastCacheKey,
+        `https://environment.example/api/assets/revision-${revision}/favicon.svg`,
+      );
+      const endRequest = beginProjectFaviconRequest(request);
+      markProjectFaviconLoaded(request);
+      endRequest();
+    }
+
+    expect(hasLoadedProjectFavicon(firstCacheKey)).toBe(false);
+    expect(hasLoadedProjectFavicon(lastCacheKey)).toBe(true);
+  });
+});
diff --git a/apps/mobile/src/components/projectFaviconCache.ts b/apps/mobile/src/components/projectFaviconCache.ts
new file mode 100644
index 00000000000..da77d7613f2
--- /dev/null
+++ b/apps/mobile/src/components/projectFaviconCache.ts
@@ -0,0 +1,94 @@
+export interface ProjectFaviconRequest {
+  readonly cacheKey: string;
+  readonly faviconUrl: string;
+}
+
+interface ActiveFaviconRequests {
+  readonly urls: Map<string, number>;
+  currentUrl: string;
+}
+
+const MAX_LOADED_FAVICONS = 256;
+const activeFaviconRequests = new Map<string, ActiveFaviconRequests>();
+const loadedFaviconKeys = new Map<string, true>();
+
+export function createProjectFaviconRequest(
+  cacheKey: string,
+  faviconUrl: string,
+): ProjectFaviconRequest;
+export function createProjectFaviconRequest(
+  cacheKey: string | null,
+  faviconUrl: string | null,
+): ProjectFaviconRequest | null;
+export function createProjectFaviconRequest(cacheKey: string | null, faviconUrl: string | null) {
+  if (!cacheKey || !faviconUrl) return null;
+  return { cacheKey, faviconUrl };
+}
+
+export function beginProjectFaviconRequest(request: ProjectFaviconRequest) {
+  let activeRequests = activeFaviconRequests.get(request.cacheKey);
+  if (!activeRequests) {
+    activeRequests = { currentUrl: request.faviconUrl, urls: new Map() };
+    activeFaviconRequests.set(request.cacheKey, activeRequests);
+  }
+
+  const activeCount = activeRequests.urls.get(request.faviconUrl) ?? 0;
+  activeRequests.urls.delete(request.faviconUrl);
+  activeRequests.urls.set(request.faviconUrl, activeCount + 1);
+  activeRequests.currentUrl = request.faviconUrl;
+
+  let ended = false;
+  return () => {
+    if (ended) return;
+    ended = true;
+
+    const remainingCount = (activeRequests.urls.get(request.faviconUrl) ?? 1) - 1;
+    if (remainingCount > 0) {
+      activeRequests.urls.set(request.faviconUrl, remainingCount);
+      return;
+    }
+
+    activeRequests.urls.delete(request.faviconUrl);
+    if (activeRequests.urls.size === 0) {
+      if (activeFaviconRequests.get(request.cacheKey) === activeRequests) {
+        activeFaviconRequests.delete(request.cacheKey);
+      }
+      return;
+    }
+
+    if (activeRequests.currentUrl === request.faviconUrl) {
+      activeRequests.currentUrl = Array.from(activeRequests.urls.keys()).at(-1)!;
+    }
+  };
+}
+
+export function hasLoadedProjectFavicon(cacheKey: string | null) {
+  return cacheKey !== null && loadedFaviconKeys.has(cacheKey);
+}
+
+function isCurrentProjectFaviconRequest(request: ProjectFaviconRequest) {
+  return activeFaviconRequests.get(request.cacheKey)?.currentUrl === request.faviconUrl;
+}
+
+function rememberLoadedProjectFavicon(cacheKey: string) {
+  loadedFaviconKeys.delete(cacheKey);
+  loadedFaviconKeys.set(cacheKey, true);
+
+  if (loadedFaviconKeys.size > MAX_LOADED_FAVICONS) {
+    loadedFaviconKeys.delete(loadedFaviconKeys.keys().next().value!);
+  }
+}
+
+export function markProjectFaviconLoaded(request: ProjectFaviconRequest) {
+  if (!isCurrentProjectFaviconRequest(request)) return false;
+
+  rememberLoadedProjectFavicon(request.cacheKey);
+  return true;
+}
+
+export function markProjectFaviconFailed(request: ProjectFaviconRequest) {
+  if (!isCurrentProjectFaviconRequest(request)) return false;
+
+  loadedFaviconKeys.delete(request.cacheKey);
+  return true;
+}
diff --git a/apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx b/apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx
index 916802e9faf..01440007bc6 100644
--- a/apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx
+++ b/apps/mobile/src/features/archive/ArchivedThreadsScreen.tsx
@@ -29,7 +29,10 @@ import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { relativeTime } from "../../lib/time";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { ThreadSwipeable } from "../home/thread-swipe-actions";
-import { createNativeMailSearchToolbarItem } from "../layout/native-mail-search-toolbar";
+import {
+  createNativeMailSearchToolbarItem,
+  NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED,
+} from "../layout/native-mail-search-toolbar";
 import type { ArchivedThreadGroup, ArchivedThreadSortOrder } from "./archivedThreadList";
 
 export interface ArchivedThreadsHeaderEnvironment {
@@ -70,7 +73,8 @@ function ArchivedThreadsHeader(props: {
   const searchIconColor = useThemeColor("--color-icon");
   const searchTextColor = useThemeColor("--color-foreground");
   const usesNativeChrome = Platform.OS === "ios";
-  const usesCompactMailToolbar = Platform.OS === "ios" && width < 700;
+  const usesCompactMailToolbar =
+    Platform.OS === "ios" && width < 700 && NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED;
   const androidFilterActions = useMemo<MenuAction[]>(
     () => [
       {
@@ -272,7 +276,11 @@ function ArchivedThreadsHeader(props: {
                 ...(usesNativeChrome
                   ? {
                       allowToolbarIntegration: true,
-                      placement: "integratedButton" as const,
+                      // "integratedButton" is an iOS 26 search-bar placement;
+                      // pre-glass iOS keeps the default pull-down placement.
+                      ...(NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED
+                        ? { placement: "integratedButton" as const }
+                        : null),
                     }
                   : {
                       placement: "stacked" as const,
diff --git a/apps/mobile/src/features/cloud/linkEnvironment.ts b/apps/mobile/src/features/cloud/linkEnvironment.ts
index 5d619c688f1..958827ee492 100644
--- a/apps/mobile/src/features/cloud/linkEnvironment.ts
+++ b/apps/mobile/src/features/cloud/linkEnvironment.ts
@@ -134,7 +134,14 @@ function relayProtectedErrorMessage(error: RelayProtectedErrorType): string {
     case "RelayEnvironmentLinkProofInvalidError":
       return `Relay rejected the environment link proof (${error.reason}).`;
     case "RelayEnvironmentConnectNotAuthorizedError":
-      return "Relay rejected the environment connection request.";
+      // "Not authorized" covers non-auth causes too; surface the reason so a
+      // missing link doesn't read as a credential problem.
+      if (error.reason === "environment_link_not_found") {
+        return "Relay has no active link for this environment. The environment server may not have re-established its link yet.";
+      }
+      return error.reason
+        ? `Relay rejected the environment connection request (${error.reason}).`
+        : "Relay rejected the environment connection request.";
     case "RelayEnvironmentEndpointUnavailableError":
       return `Relay could not reach the environment endpoint (${error.reason}).`;
     case "RelayEnvironmentEndpointTimedOutError":
diff --git a/apps/mobile/src/features/connection/pairing.test.ts b/apps/mobile/src/features/connection/pairing.test.ts
index 18b6c71a293..19392768479 100644
--- a/apps/mobile/src/features/connection/pairing.test.ts
+++ b/apps/mobile/src/features/connection/pairing.test.ts
@@ -1,11 +1,32 @@
 import { describe, expect, it } from "vite-plus/test";
 
 import {
+  buildPairingUrl,
   extractPairingUrlFromQrPayload,
   PairingQrPayloadEmptyError,
   parsePairingUrl,
 } from "./pairing";
 
+describe("buildPairingUrl", () => {
+  it("uses HTTP for a schemeless IP address", () => {
+    expect(buildPairingUrl("192.168.1.100:3773", "pairing-token")).toBe(
+      "http://192.168.1.100:3773/#token=pairing-token",
+    );
+  });
+
+  it("keeps HTTPS as the default for a schemeless hostname", () => {
+    expect(buildPairingUrl("remote.example.com", "pairing-token")).toBe(
+      "https://remote.example.com/#token=pairing-token",
+    );
+  });
+
+  it("preserves an explicit scheme for an IP address", () => {
+    expect(buildPairingUrl("https://192.168.1.100:3773", "pairing-token")).toBe(
+      "https://192.168.1.100:3773/#token=pairing-token",
+    );
+  });
+});
+
 describe("extractPairingUrlFromQrPayload", () => {
   it("trims raw pairing urls from qr payloads", () => {
     expect(
diff --git a/apps/mobile/src/features/connection/pairing.ts b/apps/mobile/src/features/connection/pairing.ts
index 910efa7f256..569d00cbdd3 100644
--- a/apps/mobile/src/features/connection/pairing.ts
+++ b/apps/mobile/src/features/connection/pairing.ts
@@ -3,6 +3,21 @@ import * as Schema from "effect/Schema";
 
 const MOBILE_PAIRING_URL_PARAM = "pairingUrl";
 
+function isIpLiteral(host: string): boolean {
+  try {
+    const hostname = new URL(`http://${host}`).hostname.replace(/^\[|\]$/g, "");
+    if (hostname.includes(":")) return true;
+
+    const octets = hostname.split(".");
+    return (
+      octets.length === 4 &&
+      octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255)
+    );
+  } catch {
+    return false;
+  }
+}
+
 export class PairingQrPayloadEmptyError extends Schema.TaggedErrorClass<PairingQrPayloadEmptyError>()(
   "PairingQrPayloadEmptyError",
   {},
@@ -19,7 +34,7 @@ export function buildPairingUrl(host: string, code: string): string {
   if (!c) return h;
 
   try {
-    const url = new URL(h.includes("://") ? h : `https://${h}`);
+    const url = new URL(h.includes("://") ? h : `${isIpLiteral(h) ? "http" : "https"}://${h}`);
     url.hash = new URLSearchParams([["token", c]]).toString();
     return url.toString();
   } catch {
diff --git a/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx b/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
index 012f99536d2..7f5105aac17 100644
--- a/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
+++ b/apps/mobile/src/features/files/ThreadFilesRouteScreen.tsx
@@ -29,7 +29,10 @@ import {
   useAdaptiveWorkspacePaneRole,
   useRegisterWorkspaceInspector,
 } from "../layout/AdaptiveWorkspaceLayout";
-import { createNativeMailSearchToolbarItem } from "../layout/native-mail-search-toolbar";
+import {
+  createNativeMailSearchToolbarItem,
+  NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED,
+} from "../layout/native-mail-search-toolbar";
 import { WorkspaceSidebarToolbar } from "../layout/workspace-sidebar-toolbar";
 import { ReviewHighlighterProvider } from "../review/ReviewHighlighterProvider";
 import { ThreadRouteScreen } from "../threads/ThreadRouteScreen";
@@ -354,7 +357,8 @@ export function ThreadFilesTreeScreen(props: ThreadFilesRouteScreenProps) {
     );
   }
 
-  const usesCompactMailToolbar = Platform.OS === "ios" && !layout.usesSplitView;
+  const usesCompactMailToolbar =
+    Platform.OS === "ios" && !layout.usesSplitView && NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED;
 
   return (
     <>
diff --git a/apps/mobile/src/features/home/HomeHeader.tsx b/apps/mobile/src/features/home/HomeHeader.tsx
index 4265107912b..a209dbd7623 100644
--- a/apps/mobile/src/features/home/HomeHeader.tsx
+++ b/apps/mobile/src/features/home/HomeHeader.tsx
@@ -1,5 +1,6 @@
 import type { EnvironmentId, SidebarThreadSortOrder } from "@t3tools/contracts";
 import type { MenuAction } from "@react-native-menu/menu";
+import Constants from "expo-constants";
 import { NativeHeaderToolbar, NativeStackScreenOptions } from "../../native/StackHeader";
 import { useCallback, useMemo, useRef } from "react";
 import { Platform, Pressable, Text as RNText, TextInput, View } from "react-native";
@@ -9,11 +10,16 @@ import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { ControlPillMenu } from "../../components/ControlPill";
 import { SymbolView } from "../../components/AppSymbol";
 import { T3Wordmark } from "../../components/T3Wordmark";
+import { HOME_HORIZONTAL_INSET } from "../../lib/layoutMetrics";
+import { resolveMobileStageLabel } from "../../lib/mobileBranding";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { useThreadListV2Enabled } from "../threads/use-thread-list-v2-enabled";
 import { useHardwareKeyboardCommand } from "../keyboard/hardwareKeyboardCommands";
 import { withNativeGlassHeaderItem } from "../layout/native-glass-header-items";
-import { createNativeMailSearchToolbarItem } from "../layout/native-mail-search-toolbar";
+import {
+  createNativeMailSearchToolbarItem,
+  NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED,
+} from "../layout/native-mail-search-toolbar";
 import type { HomeProjectSortOrder } from "./homeThreadList";
 import {
   buildHomeListFilterMenu,
@@ -61,6 +67,7 @@ function AndroidHomeHeader(props: HomeHeaderProps) {
   const insets = useSafeAreaInsets();
   const iconColor = useThemeColor("--color-icon");
   const mutedColor = useThemeColor("--color-foreground-muted");
+  const stageLabel = resolveMobileStageLabel(Constants.expoConfig?.extra?.appVariant);
   // Thread List v2 lays the list out in fixed creation order, so the
   // sort/group filter controls would be silently ignored — hide them and
   // key the "customized" icon state off the environment filter alone.
@@ -192,8 +199,9 @@ function AndroidHomeHeader(props: HomeHeaderProps) {
     <>
       <NativeStackScreenOptions options={{ headerShown: false }} />
       <View
-        className="border-b border-header-border bg-header px-4 pb-3"
+        className="border-b border-header-border bg-header pb-3"
         style={{
+          paddingHorizontal: HOME_HORIZONTAL_INSET,
           paddingTop: Math.max(insets.top, 12),
         }}
       >
@@ -207,7 +215,7 @@ function AndroidHomeHeader(props: HomeHeaderProps) {
               </RNText>
               <View className="rounded-full bg-subtle px-2 py-0.75">
                 <RNText className="text-[11px] font-t3-bold tracking-[1.1px] text-foreground-muted uppercase">
-                  Alpha
+                  {stageLabel}
                 </RNText>
               </View>
             </View>
@@ -320,9 +328,11 @@ function IosHomeHeader(props: HomeHeaderProps) {
                   }),
                 ]
               : undefined,
-          unstable_headerToolbarItems:
-            Platform.OS === "ios"
-              ? () => [
+          // The keys below are set per-branch (not `undefined`) so a later
+          // reapply cannot clobber options owned by NativeHeaderToolbar.
+          ...(NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED
+            ? {
+                unstable_headerToolbarItems: () => [
                   createNativeMailSearchToolbarItem({
                     composeButtonId: "home-new-task",
                     composeSystemImageName: "square.and.pencil",
@@ -336,14 +346,14 @@ function IosHomeHeader(props: HomeHeaderProps) {
                     placeholder: "Search",
                     searchTextChangeId: "home-search-text",
                   }),
-                ]
-              : undefined,
-          headerSearchBarOptions:
-            Platform.OS === "ios"
-              ? undefined
-              : {
+                ],
+              }
+            : {
+                // Pre-Liquid-Glass iOS: standard pull-down search in the nav
+                // bar; create + sort live in the plain bottom toolbar below.
+                headerSearchBarOptions: {
                   ref: searchBarRef,
-                  allowToolbarIntegration: true,
+                  autoCapitalize: "none" as const,
                   hideNavigationBar: false,
                   placeholder: "Search",
                   onCancelButtonPress: () => {
@@ -353,21 +363,11 @@ function IosHomeHeader(props: HomeHeaderProps) {
                     props.onSearchQueryChange(event.nativeEvent.text);
                   },
                 },
+              }),
         }}
       />
 
-      {Platform.OS === "ios" ? null : (
-        <NativeHeaderToolbar placement="right">
-          <NativeHeaderToolbar.Button
-            accessibilityLabel="Open settings"
-            icon="gearshape"
-            onPress={props.onOpenSettings}
-            separateBackground
-          />
-        </NativeHeaderToolbar>
-      )}
-
-      {Platform.OS === "ios" ? null : (
+      {NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED ? null : (
         <NativeHeaderToolbar placement="bottom">
           <NativeHeaderToolbar.Menu
             accessibilityLabel="Filter and sort threads"
@@ -421,35 +421,37 @@ function IosHomeHeader(props: HomeHeaderProps) {
               </NativeHeaderToolbar.Menu>
             ) : null}
 
-            <NativeHeaderToolbar.Menu title="Sort projects">
-              <NativeHeaderToolbar.Label>Sort projects</NativeHeaderToolbar.Label>
-              {PROJECT_SORT_OPTIONS.map((option) => (
-                <NativeHeaderToolbar.MenuAction
-                  key={option.value}
-                  isOn={props.projectSortOrder === option.value}
-                  onPress={() => props.onProjectSortOrderChange(option.value)}
-                >
-                  <NativeHeaderToolbar.Label>{option.label}</NativeHeaderToolbar.Label>
-                </NativeHeaderToolbar.MenuAction>
-              ))}
-            </NativeHeaderToolbar.Menu>
+            {threadListV2Enabled ? null : (
+              <NativeHeaderToolbar.Menu title="Sort projects">
+                <NativeHeaderToolbar.Label>Sort projects</NativeHeaderToolbar.Label>
+                {PROJECT_SORT_OPTIONS.map((option) => (
+                  <NativeHeaderToolbar.MenuAction
+                    key={option.value}
+                    isOn={props.projectSortOrder === option.value}
+                    onPress={() => props.onProjectSortOrderChange(option.value)}
+                  >
+                    <NativeHeaderToolbar.Label>{option.label}</NativeHeaderToolbar.Label>
+                  </NativeHeaderToolbar.MenuAction>
+                ))}
+              </NativeHeaderToolbar.Menu>
+            )}
 
-            <NativeHeaderToolbar.Menu title="Sort threads">
-              <NativeHeaderToolbar.Label>Sort threads</NativeHeaderToolbar.Label>
-              {THREAD_SORT_OPTIONS.map((option) => (
-                <NativeHeaderToolbar.MenuAction
-                  key={option.value}
-                  isOn={props.threadSortOrder === option.value}
-                  onPress={() => props.onThreadSortOrderChange(option.value)}
-                >
-                  <NativeHeaderToolbar.Label>{option.label}</NativeHeaderToolbar.Label>
-                </NativeHeaderToolbar.MenuAction>
-              ))}
-            </NativeHeaderToolbar.Menu>
+            {threadListV2Enabled ? null : (
+              <NativeHeaderToolbar.Menu title="Sort threads">
+                <NativeHeaderToolbar.Label>Sort threads</NativeHeaderToolbar.Label>
+                {THREAD_SORT_OPTIONS.map((option) => (
+                  <NativeHeaderToolbar.MenuAction
+                    key={option.value}
+                    isOn={props.threadSortOrder === option.value}
+                    onPress={() => props.onThreadSortOrderChange(option.value)}
+                  >
+                    <NativeHeaderToolbar.Label>{option.label}</NativeHeaderToolbar.Label>
+                  </NativeHeaderToolbar.MenuAction>
+                ))}
+              </NativeHeaderToolbar.Menu>
+            )}
           </NativeHeaderToolbar.Menu>
-          <NativeHeaderToolbar.Spacer width={8} sharesBackground={false} />
-          <NativeHeaderToolbar.SearchBarSlot />
-          <NativeHeaderToolbar.Spacer width={8} sharesBackground={false} />
+          <NativeHeaderToolbar.Spacer flexible />
           <NativeHeaderToolbar.Button
             accessibilityLabel="New task"
             icon="square.and.pencil"
diff --git a/apps/mobile/src/features/home/HomeRouteScreen.tsx b/apps/mobile/src/features/home/HomeRouteScreen.tsx
index c172694b6c5..0aefde99100 100644
--- a/apps/mobile/src/features/home/HomeRouteScreen.tsx
+++ b/apps/mobile/src/features/home/HomeRouteScreen.tsx
@@ -3,6 +3,7 @@ import * as Order from "effect/Order";
 import { useNavigation } from "@react-navigation/native";
 import { useEffect, useMemo, useState } from "react";
 
+import { getCompactBrandHeaderOptions } from "../../components/CompactBrandTitle";
 import { NativeHeaderToolbar, NativeStackScreenOptions } from "../../native/StackHeader";
 import { useProjects, useThreadShells } from "../../state/entities";
 import { usePendingNewTasks } from "../../state/use-pending-new-tasks";
@@ -11,6 +12,7 @@ import { useSavedRemoteConnections } from "../../state/use-remote-environment-re
 import { useAdaptiveWorkspaceLayout } from "../layout/AdaptiveWorkspaceLayout";
 import { WorkspaceEmptyDetail } from "../layout/WorkspaceEmptyDetail";
 import { WorkspaceSidebarToolbar } from "../layout/workspace-sidebar-toolbar";
+import { checkForAppUpdateOnLaunch } from "../updates/app-updates";
 import { AndroidHomeFabLayout } from "./AndroidHomeFab";
 import { HomeScreen } from "./HomeScreen";
 import { HomeHeader } from "./HomeHeader";
@@ -29,8 +31,19 @@ export function HomeRouteScreen() {
   const { savedConnectionsById } = useSavedRemoteConnections();
   const navigation = useNavigation();
   const [searchQuery, setSearchQuery] = useState("");
-  const { archiveThread, confirmDeleteThread, settleThread, unsettleThread } =
-    useThreadListActions();
+
+  useEffect(() => {
+    void checkForAppUpdateOnLaunch();
+  }, []);
+
+  const {
+    archiveThread,
+    confirmDeleteThread,
+    settleThread,
+    snoozeThread,
+    unsnoozeThread,
+    unsettleThread,
+  } = useThreadListActions();
   const pendingTasks = usePendingNewTasks();
   const { openPendingTask, confirmDeletePendingTask } = usePendingTaskListActions();
   const environments = useMemo(() => {
@@ -87,7 +100,9 @@ export function HomeRouteScreen() {
   if (layout.usesSplitView) {
     return (
       <>
-        <NativeStackScreenOptions options={{ title: "", headerTitle: "" }} />
+        <NativeStackScreenOptions
+          options={{ title: "", headerTitle: "", unstable_headerLeftItems: () => [] }}
+        />
         <WorkspaceSidebarToolbar
           afterSidebarButton={
             <NativeHeaderToolbar.Button
@@ -109,8 +124,8 @@ export function HomeRouteScreen() {
       onStartNewTask={() => navigation.navigate("NewTaskSheet", { screen: "NewTask" })}
     >
       <>
-        {/* Restore the compact title in case the split branch blanked it. */}
-        <NativeStackScreenOptions options={{ title: "Threads", headerTitle: "Threads" }} />
+        {/* Restore the compact title after the split branch blanks the detail header. */}
+        <NativeStackScreenOptions options={getCompactBrandHeaderOptions()} />
         <HomeHeader
           environments={environments}
           projects={projectFilterOptions}
@@ -137,6 +152,8 @@ export function HomeRouteScreen() {
           onArchiveThread={archiveThread}
           onDeleteThread={confirmDeleteThread}
           onSettleThread={settleThread}
+          onSnoozeThread={snoozeThread}
+          onUnsnoozeThread={unsnoozeThread}
           onUnsettleThread={unsettleThread}
           onEnvironmentChange={setSelectedEnvironmentId}
           onProjectChange={setSelectedProjectKey}
diff --git a/apps/mobile/src/features/home/HomeScreen.tsx b/apps/mobile/src/features/home/HomeScreen.tsx
index 3c2ee4f7b92..d54fb7d4890 100644
--- a/apps/mobile/src/features/home/HomeScreen.tsx
+++ b/apps/mobile/src/features/home/HomeScreen.tsx
@@ -41,7 +41,12 @@ import {
   ThreadListRow,
   ThreadListShowMoreRow,
 } from "../threads/thread-list-items";
-import { ThreadListV2PendingRow, ThreadListV2Row } from "../threads/thread-list-v2-items";
+import {
+  ThreadListV2PendingRow,
+  ThreadListV2Row,
+  ThreadListV2SettledShelfHeader,
+  ThreadListV2SnoozedShelfHeader,
+} from "../threads/thread-list-v2-items";
 import {
   buildThreadListV2Items,
   buildThreadListV2ListItems,
@@ -100,6 +105,11 @@ interface HomeScreenProps {
   readonly onDeleteThread: (thread: EnvironmentThreadShell) => void;
   /** Resolves true iff the settle was dispatched and succeeded. */
   readonly onSettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
+  readonly onSnoozeThread: (
+    thread: EnvironmentThreadShell,
+    snoozedUntil: string,
+  ) => Promise<boolean>;
+  readonly onUnsnoozeThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
   readonly onUnsettleThread: (thread: EnvironmentThreadShell) => void;
   readonly onSelectPendingTask: (pendingTask: PendingNewTask) => void;
   readonly onDeletePendingTask: (pendingTask: PendingNewTask) => void;
@@ -109,6 +119,7 @@ interface HomeScreenProps {
 /* ─── Layout constants ───────────────────────────────────────────────── */
 
 const ESTIMATED_THREAD_ROW_HEIGHT = 72;
+const PRE_LIQUID_GLASS_BOTTOM_TOOLBAR_HEIGHT = 44;
 /**
  * Top spacing between the list and the Android custom header. The Android
  * header (AndroidHomeHeader) is rendered in-flow above this screen and
@@ -196,6 +207,10 @@ export function HomeScreen(props: HomeScreenProps) {
   const listRef = useRef<LegendListRef | null>(null);
   const insets = useSafeAreaInsets();
   const accentColor = useThemeColor("--color-icon-muted");
+  const iosBottomToolbarClearance =
+    Platform.OS === "ios" && !NATIVE_LIQUID_GLASS_SUPPORTED
+      ? PRE_LIQUID_GLASS_BOTTOM_TOOLBAR_HEIGHT
+      : 0;
   const searchEnvironmentIds = useMemo(
     () =>
       props.selectedEnvironmentId === null
@@ -489,6 +504,18 @@ export function HomeScreen(props: HomeScreenProps) {
     },
     [props.onSettleThread],
   );
+  const handleSnoozeThread = useCallback(
+    (thread: EnvironmentThreadShell, snoozedUntil: string) => {
+      void props.onSnoozeThread(thread, snoozedUntil);
+    },
+    [props.onSnoozeThread],
+  );
+  const handleUnsnoozeThread = useCallback(
+    (thread: EnvironmentThreadShell) => {
+      void props.onUnsnoozeThread(thread);
+    },
+    [props.onUnsnoozeThread],
+  );
   const handleDeleteThread = props.onDeleteThread;
   const handleUnsettleThread = props.onUnsettleThread;
   // The settled tail renders in pages; expansion resets when the filter
@@ -506,6 +533,10 @@ export function HomeScreen(props: HomeScreenProps) {
     () => setSettledVisibleCount((count) => count + THREAD_LIST_V2_SETTLED_PAGE_COUNT),
     [],
   );
+  const [snoozedShelfExpanded, setSnoozedShelfExpanded] = useState(false);
+  const toggleSnoozedShelf = useCallback(() => setSnoozedShelfExpanded((value) => !value), []);
+  const [settledShelfExpanded, setSettledShelfExpanded] = useState(true);
+  const toggleSettledShelf = useCallback(() => setSettledShelfExpanded((value) => !value), []);
   // now is quantized to the minute and ticks so the inactivity auto-settle
   // boundary is actually crossed while the app stays open (mirrors web);
   // without a clock dependency the partition memoizes a frozen "now".
@@ -546,7 +577,15 @@ export function HomeScreen(props: HomeScreenProps) {
   }, [serverConfigs]);
   const threadListV2Layout = useMemo(() => {
     if (!threadListV2Enabled)
-      return { items: [], hiddenSettledCount: 0, snoozedCount: 0, nextSnoozeWakeAt: null };
+      return {
+        items: [],
+        hiddenSettledCount: 0,
+        snoozedCount: 0,
+        snoozedShelfHeaderIndex: null,
+        settledCount: 0,
+        settledShelfHeaderIndex: null,
+        nextSnoozeWakeAt: null,
+      };
     // Settled threads are live shells; archived threads keep their original
     // "hidden from lists" meaning.
     return buildThreadListV2Items({
@@ -561,11 +600,16 @@ export function HomeScreen(props: HomeScreenProps) {
       settledLimit: settledVisibleCount,
       now: `${nowMinute}:00.000Z`,
       snoozeNow: new Date().toISOString(),
+      snoozedShelfExpanded,
+      settledShelfExpanded,
+      selectedThreadKey: null,
     });
   }, [
     changeRequestStateByKey,
     nowMinute,
     snoozeWakeTick,
+    snoozedShelfExpanded,
+    settledShelfExpanded,
     settledVisibleCount,
     settlementEnvironmentIds,
     snoozeEnvironmentIds,
@@ -615,8 +659,15 @@ export function HomeScreen(props: HomeScreenProps) {
       buildThreadListV2ListItems({
         items: threadListV2Layout.items,
         pendingTasks: v2PendingTasks,
+        snoozedCount: threadListV2Layout.snoozedCount,
+        snoozedShelfExpanded,
+        snoozedShelfHeaderIndex: threadListV2Layout.snoozedShelfHeaderIndex,
+        settledCount: threadListV2Layout.settledCount,
+        settledShelfExpanded,
+        settledShelfHeaderIndex: threadListV2Layout.settledShelfHeaderIndex,
+        snoozeLabelNow: `${nowMinute}:00.000Z`,
       }),
-    [threadListV2Layout.items, v2PendingTasks],
+    [settledShelfExpanded, snoozedShelfExpanded, threadListV2Layout, v2PendingTasks],
   );
 
   const renderV2Item = useCallback(
@@ -643,12 +694,32 @@ export function HomeScreen(props: HomeScreenProps) {
           />
         );
       }
+      if (item.type === "v2-snoozed-shelf") {
+        return (
+          <ThreadListV2SnoozedShelfHeader
+            count={item.count}
+            expanded={item.expanded}
+            onToggle={toggleSnoozedShelf}
+          />
+        );
+      }
+      if (item.type === "v2-settled-shelf") {
+        return (
+          <ThreadListV2SettledShelfHeader
+            count={item.count}
+            expanded={item.expanded}
+            onToggle={toggleSettledShelf}
+          />
+        );
+      }
       const thread = item.item.thread;
       return (
         <ThreadListV2Row
           thread={thread}
           variant={item.item.variant}
-          showSettledDivider={item.item.showSettledDivider}
+          snoozed={item.item.snoozed}
+          snoozePresetMinute={nowMinute}
+          snoozeWakeLabelText={item.snoozeWakeLabelText}
           project={
             projectByKey.get(scopedProjectKey(thread.environmentId, thread.projectId)) ?? null
           }
@@ -681,6 +752,9 @@ export function HomeScreen(props: HomeScreenProps) {
           onArchiveThread={props.onArchiveThread}
           settlementSupported={settlementEnvironmentIds.has(thread.environmentId)}
           onSettleThread={handleSettleThread}
+          snoozeSupported={snoozeEnvironmentIds.has(thread.environmentId)}
+          onSnoozeThread={handleSnoozeThread}
+          onUnsnoozeThread={handleUnsnoozeThread}
           onUnsettleThread={handleUnsettleThread}
           onChangeRequestState={handleChangeRequestState}
           projectCwd={
@@ -695,6 +769,8 @@ export function HomeScreen(props: HomeScreenProps) {
       handleChangeRequestState,
       handleDeleteThread,
       handleSettleThread,
+      handleSnoozeThread,
+      handleUnsnoozeThread,
       handleSwipeableClose,
       handleSwipeableWillOpen,
       handleUnsettleThread,
@@ -707,9 +783,13 @@ export function HomeScreen(props: HomeScreenProps) {
       props.savedConnectionsById,
       serverConfigs,
       settlementEnvironmentIds,
+      snoozeEnvironmentIds,
       threadSearchMatchByKey,
+      toggleSettledShelf,
+      toggleSnoozedShelf,
       v2ProjectTitleByProjectKey,
       props.searchQuery,
+      nowMinute,
     ],
   );
   const v2KeyExtractor = useCallback((item: ThreadListV2ListItem) => item.key, []);
@@ -725,6 +805,7 @@ export function HomeScreen(props: HomeScreenProps) {
       serverConfigs,
       savedConnectionsById: props.savedConnectionsById,
       searchQuery: props.searchQuery,
+      snoozePresetMinute: nowMinute,
       threadSearchMatchByKey,
     }),
     [
@@ -733,6 +814,7 @@ export function HomeScreen(props: HomeScreenProps) {
       props.searchQuery,
       props.savedConnectionsById,
       serverConfigs,
+      nowMinute,
       threadSearchMatchByKey,
       v2ProjectTitleByProjectKey,
     ],
@@ -877,7 +959,7 @@ export function HomeScreen(props: HomeScreenProps) {
       <View
         className="flex-1 items-center justify-center bg-screen px-8"
         style={{
-          paddingBottom: Math.max(insets.bottom, 24),
+          paddingBottom: Math.max(insets.bottom, 24) + iosBottomToolbarClearance,
           paddingTop: NATIVE_LIQUID_GLASS_SUPPORTED ? insets.top + 72 : 0,
         }}
       >
@@ -948,31 +1030,11 @@ export function HomeScreen(props: HomeScreenProps) {
   ) : null;
   // Self-contained: v1's listEmpty keys off projectGroups, which ignores the
   // v2 project scope, so it can be null (results elsewhere) while this list
-  // is empty. Search outranks the scope — "No results" names the actionable
-  // fact when a query is active. Snoozed threads outrank the rest: "No
-  // threads yet" over an inbox that is merely all-snoozed reads as data
-  // loss.
-  const v2SnoozedCount = threadListV2Layout.snoozedCount;
+  // is empty. Snoozed threads need no special empty state: their shelf header
+  // is a list row even while collapsed.
   const v2ListEmpty =
-    hasSearchQuery && threadSearch.isPending && v2SnoozedCount === 0 ? null : hasSearchQuery ? (
-      v2SnoozedCount > 0 ? (
-        // The snoozed threads already passed this search filter: "No
-        // results" would claim nothing matched when matches are merely
-        // parked.
-        <EmptyState
-          title={
-            v2SnoozedCount === 1 ? "1 matching thread snoozed" : `All matching threads snoozed`
-          }
-          detail={`Threads matching "${props.searchQuery}" are snoozed and return when their wake time passes.`}
-        />
-      ) : (
-        <EmptyState title="No results" detail={`No threads matching "${props.searchQuery}".`} />
-      )
-    ) : v2SnoozedCount > 0 ? (
-      <EmptyState
-        title={v2SnoozedCount === 1 ? "1 thread snoozed" : `${v2SnoozedCount} threads snoozed`}
-        detail="Snoozed threads return when their wake time passes."
-      />
+    hasSearchQuery && threadSearch.isPending ? null : hasSearchQuery ? (
+      <EmptyState title="No results" detail={`No threads matching "${props.searchQuery}".`} />
     ) : v2ScopedProjectGroup !== null ? (
       <EmptyState
         title={`No threads in ${v2ScopedProjectGroup.title}`}
@@ -993,7 +1055,7 @@ export function HomeScreen(props: HomeScreenProps) {
             extraData={v2ExtraData}
             ListHeaderComponent={v2ListHeader}
             ListFooterComponent={
-              threadListV2Layout.hiddenSettledCount > 0 ? (
+              settledShelfExpanded && threadListV2Layout.hiddenSettledCount > 0 ? (
                 <Pressable
                   accessibilityRole="button"
                   accessibilityLabel={`Show ${Math.min(threadListV2Layout.hiddenSettledCount, THREAD_LIST_V2_SETTLED_PAGE_COUNT)} more settled threads`}
@@ -1019,7 +1081,7 @@ export function HomeScreen(props: HomeScreenProps) {
             contentContainerStyle={{
               paddingBottom:
                 Platform.OS === "ios"
-                  ? Math.max(insets.bottom, 24) + 96
+                  ? Math.max(insets.bottom, 24) + 96 + iosBottomToolbarClearance
                   : Math.max(insets.bottom, 16) + 88,
             }}
           />
@@ -1060,16 +1122,19 @@ export function HomeScreen(props: HomeScreenProps) {
           scrollEventThrottle={16}
           contentContainerStyle={{
             // Android reserves room for the floating new-task FAB
-            // (56 button + 16 gap + bottom inset).
+            // (56 button + 16 gap + bottom inset). Pre-glass iOS shows a
+            // standard 44pt bottom toolbar that overlays the list and is not
+            // reflected in insets while contentInsetAdjustmentBehavior is
+            // "never".
             paddingBottom:
               Platform.OS === "ios"
-                ? Math.max(insets.bottom, 24) + 24
+                ? Math.max(insets.bottom, 24) + 24 + iosBottomToolbarClearance
                 : Math.max(insets.bottom, 16) + 88,
           }}
           scrollIndicatorInsets={
             Platform.OS === "ios"
               ? {
-                  bottom: Math.max(insets.bottom, 16) + 24,
+                  bottom: Math.max(insets.bottom, 16) + 24 + iosBottomToolbarClearance,
                   top: 0,
                 }
               : undefined
diff --git a/apps/mobile/src/features/home/thread-swipe-actions.tsx b/apps/mobile/src/features/home/thread-swipe-actions.tsx
index 186c606ae8f..973c4fae9ce 100644
--- a/apps/mobile/src/features/home/thread-swipe-actions.tsx
+++ b/apps/mobile/src/features/home/thread-swipe-actions.tsx
@@ -1,4 +1,6 @@
 import { SymbolView } from "../../components/AppSymbol";
+import { ControlPillMenu } from "../../components/ControlPill";
+import type { MenuAction } from "@react-native-menu/menu";
 import * as Haptics from "expo-haptics";
 import {
   createContext,
@@ -47,13 +49,67 @@ export const THREAD_SWIPE_SPRING = {
   stiffness: 330,
 };
 
-interface ThreadSwipePrimaryAction {
+interface ThreadSwipeAction {
   readonly accessibilityLabel: string;
   readonly icon: ComponentProps<typeof SymbolView>["name"];
   readonly label: string;
+  readonly menu?: {
+    readonly actions: MenuAction[];
+    readonly onPressAction: NonNullable<ComponentProps<typeof ControlPillMenu>["onPressAction"]>;
+    readonly title?: string;
+  };
   readonly onPress: () => void;
 }
 
+interface ThreadSwipeSecondaryAction extends ThreadSwipeAction {
+  readonly backgroundColor: string;
+}
+
+function swipeActionsWidth(hasSecondaryAction: boolean) {
+  return hasSecondaryAction ? THREAD_SWIPE_ACTIONS_WIDTH : ACTION_ITEM_WIDTH;
+}
+
+/** `undefined` keeps the v1 Delete default; `null` means one action only. */
+function resolveSecondaryAction(input: {
+  readonly close: () => void;
+  readonly onDelete: () => void;
+  readonly secondaryAction: ThreadSwipeAction | null | undefined;
+  readonly threadTitle: string;
+}): ThreadSwipeSecondaryAction | null {
+  if (input.secondaryAction === null) return null;
+  if (input.secondaryAction === undefined) {
+    return {
+      accessibilityLabel: `Delete ${input.threadTitle}`,
+      backgroundColor: "#ff2d55",
+      icon: "trash",
+      label: "Delete",
+      onPress: () => {
+        input.close();
+        input.onDelete();
+      },
+    };
+  }
+  const action = input.secondaryAction;
+  return {
+    ...action,
+    backgroundColor: "#5856d6",
+    menu:
+      action.menu === undefined
+        ? undefined
+        : {
+            ...action.menu,
+            onPressAction: (event) => {
+              input.close();
+              action.menu?.onPressAction(event);
+            },
+          },
+    onPress: () => {
+      input.close();
+      action.onPress();
+    },
+  };
+}
+
 /**
  * Delivers the scroll gate to swipeables via context so that flipping it does
  * NOT re-render whole rows: putting the flag in list extraData/renderItem deps
@@ -173,17 +229,22 @@ export function ThreadSwipeable(props: {
   readonly enabled?: boolean;
   readonly enableTrackpadSwipe?: boolean;
   /**
-   * What a full swipe commits: "delete" (default, v1 behavior — the Delete
-   * button stretches) or "primary" — the advertised primary action fires and
-   * its button stretches instead. A full swipe must always match the action
-   * the stretching button advertises.
+   * What a full swipe commits. Omitted keeps the v1 Delete behavior only when
+   * the built-in Delete secondary action is in use; custom or absent
+   * secondary actions default to the advertised primary action.
    */
   readonly fullSwipeAction?: "delete" | "primary";
   readonly fullSwipeWidth: number;
   readonly onDelete: () => void;
   readonly onSwipeableClose?: (methods: SwipeableMethods) => void;
   readonly onSwipeableWillOpen?: (methods: SwipeableMethods) => void;
-  readonly primaryAction: ThreadSwipePrimaryAction;
+  readonly primaryAction: ThreadSwipeAction;
+  /**
+   * Omitted keeps the v1 destructive Delete action. Explicit null opts out of
+   * a secondary action entirely so a gated Snooze can never fall back to an
+   * unadvertised Delete.
+   */
+  readonly secondaryAction?: ThreadSwipeAction | null;
   /**
    * Identity of the content being wrapped. When a recycled list reuses this
    * component for a different item, the swipeable snaps back to closed so an
@@ -197,7 +258,11 @@ export function ThreadSwipeable(props: {
 }) {
   const swipeableRef = useRef<SwipeableMethods | null>(null);
   const fullSwipeArmedRef = useRef(false);
-  const fullSwipeThreshold = Math.max(THREAD_SWIPE_ACTIONS_WIDTH + 44, props.fullSwipeWidth * 0.58);
+  const hasSecondaryAction = props.secondaryAction !== null;
+  const actionsWidth = swipeActionsWidth(hasSecondaryAction);
+  const fullSwipeThreshold = Math.max(actionsWidth + 44, props.fullSwipeWidth * 0.58);
+  const fullSwipeAction =
+    props.fullSwipeAction ?? (props.secondaryAction === undefined ? "delete" : "primary");
   const close = useCallback(() => swipeableRef.current?.close(), []);
   const gateEnabled = use(SwipeableScrollGateContext);
   const resetKey = props.resetKey;
@@ -251,7 +316,7 @@ export function ThreadSwipeable(props: {
         if (fullSwipeArmedRef.current) {
           fullSwipeArmedRef.current = false;
           methods.close();
-          if (props.fullSwipeAction === "primary") {
+          if (fullSwipeAction === "primary") {
             props.primaryAction.onPress();
           } else {
             props.onDelete();
@@ -264,9 +329,8 @@ export function ThreadSwipeable(props: {
         <ThreadSwipeActions
           backgroundColor={props.backgroundColor}
           compact={props.compactActions === true}
-          fullSwipeAction={props.fullSwipeAction ?? "delete"}
+          fullSwipeAction={fullSwipeAction}
           fullSwipeThreshold={fullSwipeThreshold}
-          onDelete={props.onDelete}
           onFullSwipeArmedChange={handleFullSwipeArmedChange}
           primaryAction={{
             ...props.primaryAction,
@@ -275,12 +339,16 @@ export function ThreadSwipeable(props: {
               props.primaryAction.onPress();
             },
           }}
-          swipeableMethods={methods}
-          threadTitle={props.threadTitle}
+          secondaryAction={resolveSecondaryAction({
+            close: () => methods.close(),
+            onDelete: props.onDelete,
+            secondaryAction: props.secondaryAction,
+            threadTitle: props.threadTitle,
+          })}
           translation={translation}
         />
       )}
-      rightThreshold={THREAD_SWIPE_ACTIONS_WIDTH * 0.42}
+      rightThreshold={actionsWidth * 0.42}
       simultaneousWithExternalGesture={props.simultaneousWithExternalGesture}
     >
       {props.children(close)}
@@ -290,12 +358,14 @@ export function ThreadSwipeable(props: {
 
 function SwipeActionButton(props: {
   readonly accessibilityLabel: string;
+  readonly actionsWidth: number;
   readonly backgroundColor: string;
   readonly compact: boolean;
   readonly entryRange: readonly [number, number];
   readonly fullSwipeThreshold: number;
   readonly icon: ComponentProps<typeof SymbolView>["name"];
   readonly label: string;
+  readonly menu?: ThreadSwipeAction["menu"];
   readonly onPress: () => void;
   readonly stretchesOnFullSwipe: boolean;
   readonly translation: SharedValue<number>;
@@ -305,10 +375,10 @@ function SwipeActionButton(props: {
   const actionStyle = useAnimatedStyle(() => {
     const reveal = Math.max(-props.translation.value, 0);
     const entryProgress = interpolate(reveal, props.entryRange, [0, 1], Extrapolation.CLAMP);
-    const stretch = Math.max(reveal - THREAD_SWIPE_ACTIONS_WIDTH, 0);
+    const stretch = Math.max(reveal - props.actionsWidth, 0);
     const fullSwipeProgress = interpolate(
       reveal,
-      [THREAD_SWIPE_ACTIONS_WIDTH, props.fullSwipeThreshold + 20],
+      [props.actionsWidth, props.fullSwipeThreshold + 20],
       [0, 1],
       Extrapolation.CLAMP,
     );
@@ -327,9 +397,7 @@ function SwipeActionButton(props: {
   });
   const circleStyle = useAnimatedStyle(() => {
     const reveal = Math.max(-props.translation.value, 0);
-    const stretch = props.stretchesOnFullSwipe
-      ? Math.max(reveal - THREAD_SWIPE_ACTIONS_WIDTH, 0)
-      : 0;
+    const stretch = props.stretchesOnFullSwipe ? Math.max(reveal - props.actionsWidth, 0) : 0;
 
     return {
       transform: [{ translateX: -stretch }],
@@ -338,9 +406,7 @@ function SwipeActionButton(props: {
   });
   const iconStyle = useAnimatedStyle(() => {
     const reveal = Math.max(-props.translation.value, 0);
-    const stretch = props.stretchesOnFullSwipe
-      ? Math.max(reveal - THREAD_SWIPE_ACTIONS_WIDTH, 0)
-      : 0;
+    const stretch = props.stretchesOnFullSwipe ? Math.max(reveal - props.actionsWidth, 0) : 0;
     const armedProgress = interpolate(
       reveal,
       [props.fullSwipeThreshold, props.fullSwipeThreshold + 20],
@@ -358,7 +424,7 @@ function SwipeActionButton(props: {
     }
 
     const reveal = Math.max(-props.translation.value, 0);
-    const stretch = Math.max(reveal - THREAD_SWIPE_ACTIONS_WIDTH, 0);
+    const stretch = Math.max(reveal - props.actionsWidth, 0);
     return {
       opacity: interpolate(
         reveal,
@@ -370,6 +436,63 @@ function SwipeActionButton(props: {
     };
   });
 
+  const button = (
+    <Pressable
+      accessibilityLabel={props.accessibilityLabel}
+      accessibilityRole="button"
+      onPress={props.menu === undefined ? props.onPress : undefined}
+      style={({ pressed }) => ({
+        alignItems: "center",
+        height: "100%",
+        justifyContent: "center",
+        opacity: pressed ? 0.72 : 1,
+        width: "100%",
+      })}
+    >
+      <View style={{ height: circleSize, width: circleSize }}>
+        <Animated.View
+          style={[
+            {
+              backgroundColor: props.backgroundColor,
+              borderRadius: 999,
+              height: circleSize,
+              left: 0,
+              position: "absolute",
+              top: 0,
+            },
+            circleStyle,
+          ]}
+        />
+        <Animated.View
+          style={[
+            {
+              alignItems: "center",
+              height: circleSize,
+              justifyContent: "center",
+              left: 0,
+              position: "absolute",
+              top: 0,
+              width: circleSize,
+            },
+            iconStyle,
+          ]}
+        >
+          <SymbolView name={props.icon} size={iconSize} tintColor="#ffffff" type="monochrome" />
+        </Animated.View>
+      </View>
+      <Animated.View
+        style={[
+          { height: 14, justifyContent: "center", paddingTop: props.compact ? 0 : 2 },
+          labelStyle,
+        ]}
+      >
+        <Text className="text-3xs font-t3-medium text-foreground-muted" numberOfLines={1}>
+          {props.label}
+        </Text>
+      </Animated.View>
+    </Pressable>
+  );
+
   return (
     <Animated.View
       style={[
@@ -383,60 +506,18 @@ function SwipeActionButton(props: {
         actionStyle,
       ]}
     >
-      <Pressable
-        accessibilityLabel={props.accessibilityLabel}
-        accessibilityRole="button"
-        onPress={props.onPress}
-        style={({ pressed }) => ({
-          alignItems: "center",
-          height: "100%",
-          justifyContent: "center",
-          opacity: pressed ? 0.72 : 1,
-          width: "100%",
-        })}
-      >
-        <View style={{ height: circleSize, width: circleSize }}>
-          <Animated.View
-            style={[
-              {
-                backgroundColor: props.backgroundColor,
-                borderRadius: 999,
-                height: circleSize,
-                left: 0,
-                position: "absolute",
-                top: 0,
-              },
-              circleStyle,
-            ]}
-          />
-          <Animated.View
-            style={[
-              {
-                alignItems: "center",
-                height: circleSize,
-                justifyContent: "center",
-                left: 0,
-                position: "absolute",
-                top: 0,
-                width: circleSize,
-              },
-              iconStyle,
-            ]}
-          >
-            <SymbolView name={props.icon} size={iconSize} tintColor="#ffffff" type="monochrome" />
-          </Animated.View>
-        </View>
-        <Animated.View
-          style={[
-            { height: 14, justifyContent: "center", paddingTop: props.compact ? 0 : 2 },
-            labelStyle,
-          ]}
+      {props.menu === undefined ? (
+        button
+      ) : (
+        <ControlPillMenu
+          actions={props.menu.actions}
+          onPressAction={props.menu.onPressAction}
+          title={props.menu.title}
+          style={{ height: "100%", width: "100%" }}
         >
-          <Text className="text-3xs font-t3-medium text-foreground-muted" numberOfLines={1}>
-            {props.label}
-          </Text>
-        </Animated.View>
-      </Pressable>
+          {button}
+        </ControlPillMenu>
+      )}
     </Animated.View>
   );
 }
@@ -446,14 +527,14 @@ export function ThreadSwipeActions(props: {
   readonly compact: boolean;
   readonly fullSwipeAction?: "delete" | "primary";
   readonly fullSwipeThreshold: number;
-  readonly onDelete: () => void;
   readonly onFullSwipeArmedChange: (armed: boolean) => void;
-  readonly primaryAction: ThreadSwipePrimaryAction;
-  readonly swipeableMethods: SwipeableMethods;
-  readonly threadTitle: string;
+  readonly primaryAction: ThreadSwipeAction;
+  readonly secondaryAction: ThreadSwipeSecondaryAction | null;
   readonly translation: SharedValue<number>;
 }) {
-  const fullSwipeIsPrimary = props.fullSwipeAction === "primary";
+  const secondaryAction = props.secondaryAction;
+  const fullSwipeIsPrimary = props.fullSwipeAction === "primary" || secondaryAction === null;
+  const actionsWidth = swipeActionsWidth(secondaryAction !== null);
   useAnimatedReaction(
     () => -props.translation.value >= props.fullSwipeThreshold,
     (armed, previous) => {
@@ -470,14 +551,19 @@ export function ThreadSwipeActions(props: {
         backgroundColor: props.backgroundColor,
         flexDirection: "row",
         height: "100%",
-        width: THREAD_SWIPE_ACTIONS_WIDTH,
+        width: actionsWidth,
       }}
     >
       <SwipeActionButton
         accessibilityLabel={props.primaryAction.accessibilityLabel}
+        actionsWidth={actionsWidth}
         backgroundColor="#007aff"
         compact={props.compact}
-        entryRange={[ACTION_ITEM_WIDTH * 0.55, THREAD_SWIPE_ACTIONS_WIDTH * 0.85]}
+        entryRange={
+          secondaryAction === null
+            ? [8, ACTION_ITEM_WIDTH * 0.72]
+            : [ACTION_ITEM_WIDTH * 0.55, THREAD_SWIPE_ACTIONS_WIDTH * 0.85]
+        }
         fullSwipeThreshold={props.fullSwipeThreshold}
         icon={props.primaryAction.icon}
         label={props.primaryAction.label}
@@ -485,21 +571,22 @@ export function ThreadSwipeActions(props: {
         stretchesOnFullSwipe={fullSwipeIsPrimary}
         translation={props.translation}
       />
-      <SwipeActionButton
-        accessibilityLabel={`Delete ${props.threadTitle}`}
-        backgroundColor="#ff2d55"
-        compact={props.compact}
-        entryRange={[8, ACTION_ITEM_WIDTH * 0.72]}
-        fullSwipeThreshold={props.fullSwipeThreshold}
-        icon="trash"
-        label="Delete"
-        onPress={() => {
-          props.swipeableMethods.close();
-          props.onDelete();
-        }}
-        stretchesOnFullSwipe={!fullSwipeIsPrimary}
-        translation={props.translation}
-      />
+      {secondaryAction === null ? null : (
+        <SwipeActionButton
+          accessibilityLabel={secondaryAction.accessibilityLabel}
+          actionsWidth={actionsWidth}
+          backgroundColor={secondaryAction.backgroundColor}
+          compact={props.compact}
+          entryRange={[8, ACTION_ITEM_WIDTH * 0.72]}
+          fullSwipeThreshold={props.fullSwipeThreshold}
+          icon={secondaryAction.icon}
+          label={secondaryAction.label}
+          menu={secondaryAction.menu}
+          onPress={secondaryAction.onPress}
+          stretchesOnFullSwipe={!fullSwipeIsPrimary}
+          translation={props.translation}
+        />
+      )}
     </View>
   );
 }
diff --git a/apps/mobile/src/features/home/useThreadListActions.ts b/apps/mobile/src/features/home/useThreadListActions.ts
index e200eb7acde..0c621a04e38 100644
--- a/apps/mobile/src/features/home/useThreadListActions.ts
+++ b/apps/mobile/src/features/home/useThreadListActions.ts
@@ -1,5 +1,5 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
-import { canSettle } from "@t3tools/client-runtime/state/thread-settled";
+import { canSettle, canSnooze } from "@t3tools/client-runtime/state/thread-settled";
 import * as Cause from "effect/Cause";
 import * as Haptics from "expo-haptics";
 import { useCallback, useRef } from "react";
@@ -22,6 +22,13 @@ function environmentSupportsSettlement(environmentId: EnvironmentThreadShell["en
   );
 }
 
+function environmentSupportsSnooze(environmentId: EnvironmentThreadShell["environmentId"]) {
+  return (
+    appAtomRegistry.get(environmentServerConfigsAtom).get(environmentId)?.environment.capabilities
+      .threadSnooze === true
+  );
+}
+
 type ThreadListAction = "archive" | "unarchive" | "delete" | "settle" | "unsettle";
 
 const ACTION_VERBS: Record<ThreadListAction, string> = {
@@ -192,9 +199,14 @@ export function useThreadListActions(): {
   readonly archiveThread: (thread: EnvironmentThreadShell) => void;
   readonly confirmDeleteThread: (thread: EnvironmentThreadShell) => void;
   readonly settleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
+  readonly snoozeThread: (thread: EnvironmentThreadShell, snoozedUntil: string) => Promise<boolean>;
+  readonly unsnoozeThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
   readonly unsettleThread: (thread: EnvironmentThreadShell) => Promise<boolean>;
 } {
   const executeAction = useThreadActionExecutor();
+  const snoozeMutation = useAtomCommand(threadEnvironment.snooze, { reportFailure: false });
+  const unsnoozeMutation = useAtomCommand(threadEnvironment.unsnooze, { reportFailure: false });
+  const snoozeInFlightThreadKeys = useRef(new Set<string>());
 
   const archiveThread = useCallback(
     (thread: EnvironmentThreadShell) => {
@@ -206,6 +218,94 @@ export function useThreadListActions(): {
     async (thread: EnvironmentThreadShell) => (await executeAction("settle", thread)) === true,
     [executeAction],
   );
+  const snoozeThread = useCallback(
+    async (thread: EnvironmentThreadShell, snoozedUntil: string) => {
+      const key = scopedThreadKey(thread.environmentId, thread.id);
+      if (snoozeInFlightThreadKeys.current.has(key)) {
+        return false;
+      }
+      snoozeInFlightThreadKeys.current.add(key);
+      try {
+        if (!environmentSupportsSnooze(thread.environmentId)) {
+          Alert.alert(
+            "Could not snooze thread",
+            "This environment's server does not support snoozing yet. Update the server to use Snooze.",
+          );
+          return false;
+        }
+        if (!canSnooze(thread, { now: new Date().toISOString() })) {
+          Alert.alert(
+            "Could not snooze thread",
+            thread.hasPendingApprovals || thread.hasPendingUserInput
+              ? "This thread is waiting on you. Respond to the pending request before snoozing it."
+              : "This thread is still starting a turn. Try again once it's running.",
+          );
+          return false;
+        }
+
+        selectionHaptic();
+        const result = await snoozeMutation({
+          environmentId: thread.environmentId,
+          input: {
+            threadId: thread.id,
+            snoozedUntil,
+          },
+        });
+        if (result._tag === "Failure") {
+          const error = Cause.squash(result.cause);
+          Alert.alert(
+            "Could not snooze thread",
+            error instanceof Error && error.message.trim().length > 0
+              ? error.message
+              : "The thread could not be snoozed.",
+          );
+          return false;
+        }
+        return true;
+      } finally {
+        snoozeInFlightThreadKeys.current.delete(key);
+      }
+    },
+    [snoozeMutation],
+  );
+  const unsnoozeThread = useCallback(
+    async (thread: EnvironmentThreadShell) => {
+      const key = scopedThreadKey(thread.environmentId, thread.id);
+      if (snoozeInFlightThreadKeys.current.has(key)) {
+        return false;
+      }
+      snoozeInFlightThreadKeys.current.add(key);
+      try {
+        if (!environmentSupportsSnooze(thread.environmentId)) {
+          Alert.alert(
+            "Could not wake thread",
+            "This environment's server does not support snoozing yet. Update the server to wake this thread.",
+          );
+          return false;
+        }
+
+        selectionHaptic();
+        const result = await unsnoozeMutation({
+          environmentId: thread.environmentId,
+          input: { threadId: thread.id, reason: "user" },
+        });
+        if (result._tag === "Failure") {
+          const error = Cause.squash(result.cause);
+          Alert.alert(
+            "Could not wake thread",
+            error instanceof Error && error.message.trim().length > 0
+              ? error.message
+              : "The thread could not be woken.",
+          );
+          return false;
+        }
+        return true;
+      } finally {
+        snoozeInFlightThreadKeys.current.delete(key);
+      }
+    },
+    [unsnoozeMutation],
+  );
   const unsettleThread = useCallback(
     async (thread: EnvironmentThreadShell) => (await executeAction("unsettle", thread)) === true,
     [executeAction],
@@ -213,7 +313,14 @@ export function useThreadListActions(): {
 
   const confirmDeleteThread = useConfirmDeleteThread(executeAction);
 
-  return { archiveThread, confirmDeleteThread, settleThread, unsettleThread };
+  return {
+    archiveThread,
+    confirmDeleteThread,
+    settleThread,
+    snoozeThread,
+    unsnoozeThread,
+    unsettleThread,
+  };
 }
 
 export function useArchivedThreadListActions(
diff --git a/apps/mobile/src/features/layout/native-mail-search-toolbar.ts b/apps/mobile/src/features/layout/native-mail-search-toolbar.ts
index 820e1222243..8770d96b124 100644
--- a/apps/mobile/src/features/layout/native-mail-search-toolbar.ts
+++ b/apps/mobile/src/features/layout/native-mail-search-toolbar.ts
@@ -1,5 +1,16 @@
 import type { HeaderBarButtonMailSearchToolbarItem } from "react-native-screens";
 
+import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
+
+/**
+ * The patched mail-style toolbar is built natively from iOS 26 Liquid Glass
+ * UIKit (`UIGlassEffect`) with no earlier fallback: pre-26 the native side
+ * silently drops the item and hides the navigation toolbar entirely. Screens
+ * that send it must fall back to standard search/toolbar primitives when this
+ * is false.
+ */
+export const NATIVE_MAIL_SEARCH_TOOLBAR_SUPPORTED = NATIVE_LIQUID_GLASS_SUPPORTED;
+
 type NativeMailSearchToolbarInput = Omit<
   HeaderBarButtonMailSearchToolbarItem,
   "type" | "useFallbackSearchField"
diff --git a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
index f354bcd29ac..49adfe75cb2 100644
--- a/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
+++ b/apps/mobile/src/features/settings/SettingsRouteScreen.tsx
@@ -9,19 +9,10 @@ import { SymbolView } from "../../components/AppSymbol";
 import * as Effect from "effect/Effect";
 import { AsyncResult } from "effect/unstable/reactivity";
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import {
-  ActivityIndicator,
-  Alert,
-  Linking,
-  Platform,
-  Pressable,
-  ScrollView,
-  View,
-} from "react-native";
+import { Alert, Linking, Platform, Pressable, ScrollView, View } from "react-native";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 
 import {
-  type AtomCommandResult,
   isAtomCommandInterrupted,
   reportAtomCommandResult,
   settleAsyncResult,
@@ -47,6 +38,11 @@ import { runtime } from "../../lib/runtime";
 import { useThemeColor } from "../../lib/useThemeColor";
 import { mobilePreferencesAtom, updateMobilePreferencesAtom } from "../../state/preferences";
 import { useThreadListV2Enabled } from "../threads/use-thread-list-v2-enabled";
+import {
+  type AppUpdateCheckState,
+  registerHiddenUpdateTap,
+  runAppUpdateCheck,
+} from "../updates/app-updates";
 import { useSavedRemoteConnections } from "../../state/use-remote-environment-registry";
 import { SettingsRow } from "./components/SettingsRow";
 import { SettingsSection } from "./components/SettingsSection";
@@ -578,12 +574,11 @@ function BetaSettingsSection() {
   );
 }
 
-type UpdateCheckState = "idle" | "checking" | "downloading" | "restarting" | "current";
-
 function AppSettingsSection() {
   const icon = useThemeColor("--color-icon");
-  const [updateState, setUpdateState] = useState<UpdateCheckState>("idle");
+  const [updateState, setUpdateState] = useState<AppUpdateCheckState>("idle");
   const updateInFlight = useRef(false);
+  const hiddenUpdateTapCount = useRef(0);
 
   const version = Constants.expoConfig?.version ?? "0.0.0";
   // Fall back to "production" to match resolveAppVariant in app.config.ts, so a
@@ -591,22 +586,11 @@ function AppSettingsSection() {
   const variant = (Constants.expoConfig?.extra?.appVariant as string | undefined) ?? "production";
   const variantLabel = variant === "production" ? "" : capitalize(variant);
   const versionLabel = variantLabel ? `${version} · ${variantLabel}` : version;
-  // Which JS is actually running: the bundle shipped in the binary, or an OTA
-  // update downloaded on top of it. Surfacing this makes "am I even on the
-  // right build?" answerable at a glance.
-  const bundleLabel = Updates.isEnabled
-    ? Updates.isEmbeddedLaunch
-      ? "Embedded"
-      : Updates.updateId
-        ? `OTA ${Updates.updateId.slice(0, 7)}`
-        : null
-    : null;
-
   const busy =
     updateState === "checking" || updateState === "downloading" || updateState === "restarting";
 
   // "Up to date" is a transient acknowledgement, not a state worth persisting —
-  // drop back to the bundle label so the row keeps answering "what am I running?".
+  // return the version row to its normal, deliberately quiet state.
   useEffect(() => {
     if (updateState !== "current") return;
     const timer = setTimeout(() => setUpdateState("idle"), 3000);
@@ -619,12 +603,24 @@ function AppSettingsSection() {
     if (updateInFlight.current) return;
     updateInFlight.current = true;
     try {
-      await runUpdateCheck(setUpdateState);
+      await runAppUpdateCheck({
+        onFailure: (message) => Alert.alert("Update failed", message),
+        onStateChange: setUpdateState,
+      });
     } finally {
       updateInFlight.current = false;
     }
   }, []);
 
+  const handleVersionPress = useCallback(() => {
+    if (!Updates.isEnabled || updateInFlight.current) return;
+    const tap = registerHiddenUpdateTap(hiddenUpdateTapCount.current);
+    hiddenUpdateTapCount.current = tap.nextCount;
+    if (tap.shouldCheck) {
+      void checkForUpdate();
+    }
+  }, [checkForUpdate]);
+
   const statusLabel =
     updateState === "checking"
       ? "Checking…"
@@ -634,7 +630,7 @@ function AppSettingsSection() {
           ? "Restarting…"
           : updateState === "current"
             ? "Up to date"
-            : bundleLabel;
+            : null;
 
   const versionRow = (
     <View className="flex-row items-center gap-4 p-4">
@@ -652,21 +648,6 @@ function AppSettingsSection() {
           <Text className="text-xs text-foreground-muted/70">{statusLabel}</Text>
         ) : null}
       </View>
-      {Updates.isEnabled ? (
-        <View className="w-[22px] items-center">
-          {busy ? (
-            <ActivityIndicator color={icon} size="small" />
-          ) : (
-            <SymbolView
-              name="arrow.clockwise"
-              size={18}
-              tintColor={icon}
-              type="monochrome"
-              weight="semibold"
-            />
-          )}
-        </View>
-      ) : null}
     </View>
   );
 
@@ -676,10 +657,10 @@ function AppSettingsSection() {
       <SettingsRow icon="doc.text" label="Legal" fullScreenTarget="SettingsLegal" />
       {Updates.isEnabled ? (
         <Pressable
-          accessibilityLabel="Check for updates"
-          accessibilityRole="button"
+          accessibilityLabel={`Version ${versionLabel}`}
+          accessibilityRole="text"
           disabled={busy}
-          onPress={() => void checkForUpdate()}
+          onPress={handleVersionPress}
         >
           {versionRow}
         </Pressable>
@@ -690,52 +671,6 @@ function AppSettingsSection() {
   );
 }
 
-async function runUpdateCheck(setUpdateState: (state: UpdateCheckState) => void): Promise<void> {
-  setUpdateState("checking");
-  const check = await settlePromise(() => Updates.checkForUpdateAsync());
-  if (check._tag === "Failure") {
-    reportUpdateFailure(check, "Could not check for updates.");
-    setUpdateState("idle");
-    return;
-  }
-  // A rollback directive (`eas update:rollback`) arrives as isAvailable: false
-  // with isRollBackToEmbedded: true — there is nothing newer to install, but the
-  // running OTA still has to be dropped for the embedded bundle.
-  if (!check.value.isAvailable && !check.value.isRollBackToEmbedded) {
-    setUpdateState("current");
-    return;
-  }
-
-  setUpdateState("downloading");
-  const fetched = await settlePromise(() => Updates.fetchUpdateAsync());
-  if (fetched._tag === "Failure") {
-    reportUpdateFailure(fetched, "Could not download the update.");
-    setUpdateState("idle");
-    return;
-  }
-  // isNew is always false for a rollback, so it can't be the sole gate here either.
-  if (!fetched.value.isNew && !fetched.value.isRollBackToEmbedded) {
-    setUpdateState("current");
-    return;
-  }
-
-  setUpdateState("restarting");
-  // reloadAsync never resolves on success — the JS context is torn down — so
-  // reaching the failure branch below is the only way this returns.
-  const reloaded = await settlePromise(() => Updates.reloadAsync());
-  if (reloaded._tag === "Failure") {
-    reportUpdateFailure(reloaded, "Downloaded, but could not restart the app.");
-    setUpdateState("idle");
-  }
-}
-
-function reportUpdateFailure(result: AtomCommandResult<unknown, unknown>, fallback: string): void {
-  reportAtomCommandResult(result, { label: "app update check" });
-  if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
-  const error = squashAtomCommandFailure(result);
-  Alert.alert("Update failed", error instanceof Error ? error.message : fallback);
-}
-
 function capitalize(value: string): string {
   return value.length > 0 ? value.charAt(0).toUpperCase() + value.slice(1) : value;
 }
diff --git a/apps/mobile/src/features/showcase/ShowcaseCaptureCoordinator.tsx b/apps/mobile/src/features/showcase/ShowcaseCaptureCoordinator.tsx
index 9a4272824ba..ffeca9671b7 100644
--- a/apps/mobile/src/features/showcase/ShowcaseCaptureCoordinator.tsx
+++ b/apps/mobile/src/features/showcase/ShowcaseCaptureCoordinator.tsx
@@ -9,6 +9,8 @@ import { enqueueThreadOutboxMessage } from "../../state/thread-outbox";
 import { holdEditingQueuedMessage } from "../../state/use-thread-outbox";
 import { useWorkspaceState } from "../../state/workspace";
 import {
+  applyNativeShowcaseOrientation,
+  getNativeShowcaseOrientation,
   getNativeShowcasePairingUrls,
   getNativeShowcaseScene,
   markNativeShowcaseReady,
@@ -47,6 +49,7 @@ export function ShowcaseCaptureCoordinator(props: { readonly pathname: string })
   const [pendingTasksReady, setPendingTasksReady] = useState(false);
   const [requestedScene, setRequestedScene] = useState<ShowcaseScene | null>(null);
   const [readyScene, setReadyScene] = useState<ShowcaseScene | null>(null);
+  const [orientationSettled, setOrientationSettled] = useState(false);
 
   useEffect(() => {
     if (!SHOWCASE_ENABLED || pairingUrls.length > 0) return;
@@ -60,6 +63,25 @@ export function ShowcaseCaptureCoordinator(props: { readonly pathname: string })
     return () => clearInterval(interval);
   }, [pairingUrls.length]);
 
+  useEffect(() => {
+    if (!SHOWCASE_ENABLED || orientationSettled) return;
+    const orientation = getNativeShowcaseOrientation();
+    if (orientation === null) {
+      setOrientationSettled(true);
+      return;
+    }
+
+    let cancelled = false;
+    void retryShowcaseOperation(async () => applyNativeShowcaseOrientation(orientation), {
+      isCancelled: () => cancelled,
+    }).then((applied) => {
+      if (!cancelled && applied) setOrientationSettled(true);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [orientationSettled]);
+
   useEffect(() => {
     if (!SHOWCASE_ENABLED) return;
 
@@ -182,7 +204,10 @@ export function ShowcaseCaptureCoordinator(props: { readonly pathname: string })
       scene === null ||
       requestedScene === null ||
       scene !== requestedScene ||
-      !hasFixture
+      !hasFixture ||
+      // Never report a scene ready while the capture orientation is still
+      // being applied — a screenshot taken early has the wrong dimensions.
+      !orientationSettled
     ) {
       setReadyScene(null);
       return;
@@ -210,7 +235,7 @@ export function ShowcaseCaptureCoordinator(props: { readonly pathname: string })
       if (renderFrame !== null) cancelAnimationFrame(renderFrame);
       if (readyFrame !== null) cancelAnimationFrame(readyFrame);
     };
-  }, [hasFixture, requestedScene, scene]);
+  }, [hasFixture, orientationSettled, requestedScene, scene]);
 
   if (!SHOWCASE_ENABLED || readyScene === null) return null;
 
diff --git a/apps/mobile/src/features/showcase/nativeShowcaseScene.ts b/apps/mobile/src/features/showcase/nativeShowcaseScene.ts
index 1f2e263ebf1..07ca60cf533 100644
--- a/apps/mobile/src/features/showcase/nativeShowcaseScene.ts
+++ b/apps/mobile/src/features/showcase/nativeShowcaseScene.ts
@@ -3,9 +3,14 @@ import { requireOptionalNativeModule } from "expo";
 export const SHOWCASE_SCENES = ["threads", "thread", "terminal", "review", "environments"] as const;
 export type ShowcaseScene = (typeof SHOWCASE_SCENES)[number];
 
+export type ShowcaseOrientation = "portrait" | "landscape";
+
 interface NativeShowcaseControls {
   readonly getShowcasePairingUrl?: () => string | null;
   readonly getShowcaseScene?: () => string | null;
+  readonly getShowcaseOrientation?: () => string | null;
+  readonly applyShowcaseOrientation?: (orientation: ShowcaseOrientation) => Promise<void>;
+  readonly getInterfaceOrientation?: () => Promise<string>;
   readonly prepareShowcaseCapture?: () => void;
   readonly markShowcaseReady?: (scene: ShowcaseScene) => void;
 }
@@ -59,6 +64,35 @@ export function prepareNativeShowcaseCapture(): void {
   }
 }
 
+export function getNativeShowcaseOrientation(): ShowcaseOrientation | null {
+  try {
+    const orientation = nativeShowcaseControls()?.getShowcaseOrientation?.()?.trim();
+    return orientation === "portrait" || orientation === "landscape" ? orientation : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function applyNativeShowcaseOrientation(
+  orientation: ShowcaseOrientation,
+): Promise<boolean> {
+  const controls = nativeShowcaseControls();
+  if (!controls?.applyShowcaseOrientation || !controls.getInterfaceOrientation) {
+    // A development build that predates this helper keeps its default
+    // orientation; report success so callers do not retry forever.
+    return true;
+  }
+  try {
+    await controls.applyShowcaseOrientation(orientation);
+    // The geometry request settles asynchronously; confirm it took effect so
+    // callers can retry attempts made before the scene was foreground-active.
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    return (await controls.getInterfaceOrientation()) === orientation;
+  } catch {
+    return false;
+  }
+}
+
 export function markNativeShowcaseReady(scene: ShowcaseScene): void {
   try {
     nativeShowcaseControls()?.markShowcaseReady?.(scene);
diff --git a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
index f37b5559a4a..6d204e3a8e6 100644
--- a/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
+++ b/apps/mobile/src/features/threads/NewTaskDraftScreen.tsx
@@ -42,7 +42,8 @@ import {
   restoreComposerDraftSnapshot,
   type ComposerDraft,
 } from "../../state/use-composer-drafts";
-import { useProjects } from "../../state/entities";
+import { useEnvironmentServerConfig, useProjects } from "../../state/entities";
+import { buildModelMenuActions, resolveSelectableModelSelection } from "../../lib/modelOptions";
 import { deriveThreadTitleFromPrompt } from "../../lib/projectThreadStartTurn";
 import { armAgentAwarenessLiveActivityForLocalWork } from "../agent-awareness/remoteRegistration";
 import { enqueueThreadOutboxMessage, removeThreadOutboxMessage } from "../../state/thread-outbox";
@@ -90,6 +91,9 @@ export function NewTaskDraftScreen(props: {
   const controlsBottomPadding = isKeyboardVisible ? 8 : Math.max(insets.bottom, 10);
   const { logicalProjects, selectedProject, setProject } = flow;
   const { connectedEnvironments } = useRemoteConnectionStatus();
+  const selectedEnvironmentServerConfig = useEnvironmentServerConfig(
+    selectedProject?.environmentId ?? null,
+  );
   const environmentConnected =
     selectedProject !== null &&
     connectedEnvironments.find(
@@ -539,27 +543,7 @@ export function NewTaskDraftScreen(props: {
   );
 
   const modelMenuActions = useMemo(
-    () =>
-      flow.providerGroups.map((group) => ({
-        id: `provider:${group.providerKey}`,
-        title: group.providerLabel,
-        subtitle: group.models.find(
-          (model) =>
-            flow.selectedModel &&
-            model.selection.instanceId === flow.selectedModel.instanceId &&
-            model.selection.model === flow.selectedModel.model,
-        )?.label,
-        subactions: group.models.map((option) => ({
-          id: `model:${option.key}`,
-          title: option.label,
-          state:
-            flow.selectedModel &&
-            option.selection.instanceId === flow.selectedModel.instanceId &&
-            option.selection.model === flow.selectedModel.model
-              ? ("on" as const)
-              : undefined,
-        })),
-      })),
+    () => buildModelMenuActions(flow.providerGroups, flow.selectedModel),
     [flow.providerGroups, flow.selectedModel],
   );
   const providerOptionDescriptors = useMemo(
@@ -795,7 +779,14 @@ export function NewTaskDraftScreen(props: {
       return;
     }
     const draft = getComposerDraftSnapshot(draftKey);
-    const modelSelection = draft.modelSelection ?? flow.selectedModel;
+    // Snapshot read keeps just-typed selector state; the availability gate
+    // still applies so a stored selection on a disabled provider falls back
+    // to the flow's resolved model.
+    const modelSelection =
+      resolveSelectableModelSelection(
+        selectedEnvironmentServerConfig,
+        draft.modelSelection ?? null,
+      ) ?? flow.selectedModel;
     const workspaceMode = draft.workspaceSelection?.mode ?? flow.workspaceMode;
     const selectedBranchName = draft.workspaceSelection?.branch ?? flow.selectedBranchName;
     const selectedWorktreePath =
@@ -847,7 +838,10 @@ export function NewTaskDraftScreen(props: {
       if (editingPendingTask) {
         flow.finishEditingPendingTask();
       } else {
-        clearComposerDraftContent(draftKey);
+        // Drop the workspace selection with the content: the next task should
+        // re-resolve mode/branch/origin from the server's configured defaults
+        // instead of resurrecting this task's picks.
+        clearComposerDraftContent(draftKey, { clearWorkspaceSelection: true });
       }
       navigation.getParent()?.goBack();
       return;
@@ -905,7 +899,7 @@ export function NewTaskDraftScreen(props: {
       }
       flow.finishEditingPendingTask();
     } else {
-      clearComposerDraftContent(draftKey);
+      clearComposerDraftContent(draftKey, { clearWorkspaceSelection: true });
     }
     navigation.dispatch(
       StackActions.replace("Thread", {
diff --git a/apps/mobile/src/features/threads/ThreadComposer.tsx b/apps/mobile/src/features/threads/ThreadComposer.tsx
index fc45cba4260..aab896efe03 100644
--- a/apps/mobile/src/features/threads/ThreadComposer.tsx
+++ b/apps/mobile/src/features/threads/ThreadComposer.tsx
@@ -53,7 +53,7 @@ import {
 import { ControlPill, ControlPillMenu } from "../../components/ControlPill";
 import { ProviderIcon } from "../../components/ProviderIcon";
 import type { DraftComposerImageAttachment } from "../../lib/composerImages";
-import { buildModelOptions, groupByProvider } from "../../lib/modelOptions";
+import { buildModelMenuActions, buildModelOptions, groupByProvider } from "../../lib/modelOptions";
 import { useScaledTextRole } from "../settings/appearance/useScaledTextRole";
 import type { RemoteClientConnectionState } from "../../lib/connection";
 import {
@@ -606,25 +606,7 @@ export const ThreadComposer = memo(function ThreadComposer(props: ThreadComposer
     [providerOptionDescriptors],
   );
   const modelMenuActions = useMemo(
-    () =>
-      providerGroups.map((group) => ({
-        id: `provider:${group.providerKey}`,
-        title: group.providerLabel,
-        subtitle: group.models.find(
-          (model) =>
-            model.selection.instanceId === currentModelSelection.instanceId &&
-            model.selection.model === currentModelSelection.model,
-        )?.label,
-        subactions: group.models.map((option) => ({
-          id: `model:${option.key}`,
-          title: option.label,
-          state:
-            option.selection.instanceId === currentModelSelection.instanceId &&
-            option.selection.model === currentModelSelection.model
-              ? ("on" as const)
-              : undefined,
-        })),
-      })),
+    () => buildModelMenuActions(providerGroups, currentModelSelection),
     [providerGroups, currentModelSelection],
   );
 
diff --git a/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx b/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
index 36a86ceb1e3..8a7fc2ed6df 100644
--- a/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
+++ b/apps/mobile/src/features/threads/ThreadNavigationSidebar.tsx
@@ -67,7 +67,12 @@ import {
   ThreadListRow,
   ThreadListShowMoreRow,
 } from "./thread-list-items";
-import { ThreadListV2PendingRow, ThreadListV2Row } from "./thread-list-v2-items";
+import {
+  ThreadListV2PendingRow,
+  ThreadListV2Row,
+  ThreadListV2SettledShelfHeader,
+  ThreadListV2SnoozedShelfHeader,
+} from "./thread-list-v2-items";
 import {
   buildThreadListV2Items,
   buildThreadListV2ListItems,
@@ -193,8 +198,14 @@ function ThreadNavigationSidebarPane(
   const openSwipeableRef = useRef<SwipeableMethods | null>(null);
   const headerIsOverContentRef = useRef(false);
   const sidebarScrollGesture = useMemo(() => Gesture.Native(), []);
-  const { archiveThread, confirmDeleteThread, settleThread, unsettleThread } =
-    useThreadListActions();
+  const {
+    archiveThread,
+    confirmDeleteThread,
+    settleThread,
+    snoozeThread,
+    unsnoozeThread,
+    unsettleThread,
+  } = useThreadListActions();
   const threadListV2Enabled = useThreadListV2Enabled();
   const pendingTasks = usePendingNewTasks();
   const { openPendingTask, confirmDeletePendingTask } = usePendingTaskListActions();
@@ -428,6 +439,10 @@ function ThreadNavigationSidebarPane(
     () => setSettledVisibleCount((count) => count + THREAD_LIST_V2_SETTLED_PAGE_COUNT),
     [],
   );
+  const [snoozedShelfExpanded, setSnoozedShelfExpanded] = useState(false);
+  const toggleSnoozedShelf = useCallback(() => setSnoozedShelfExpanded((value) => !value), []);
+  const [settledShelfExpanded, setSettledShelfExpanded] = useState(true);
+  const toggleSettledShelf = useCallback(() => setSettledShelfExpanded((value) => !value), []);
   // now ticks per minute so the inactivity auto-settle boundary is actually
   // crossed while the pane stays open; without a clock dependency the
   // partition memoizes a frozen "now".
@@ -468,7 +483,15 @@ function ThreadNavigationSidebarPane(
   }, [serverConfigs]);
   const threadListV2Layout = useMemo(() => {
     if (!threadListV2Enabled)
-      return { items: [], hiddenSettledCount: 0, snoozedCount: 0, nextSnoozeWakeAt: null };
+      return {
+        items: [],
+        hiddenSettledCount: 0,
+        snoozedCount: 0,
+        snoozedShelfHeaderIndex: null,
+        settledCount: 0,
+        settledShelfHeaderIndex: null,
+        nextSnoozeWakeAt: null,
+      };
     return buildThreadListV2Items({
       threads: threads.filter((thread) => thread.archivedAt === null),
       environmentId: options.selectedEnvironmentId,
@@ -481,11 +504,17 @@ function ThreadNavigationSidebarPane(
       settledLimit: settledVisibleCount,
       now: `${nowMinute}:00.000Z`,
       snoozeNow: new Date().toISOString(),
+      snoozedShelfExpanded,
+      settledShelfExpanded,
+      selectedThreadKey: props.selectedThreadKey ?? null,
     });
   }, [
     changeRequestStateByKey,
     nowMinute,
     snoozeWakeTick,
+    snoozedShelfExpanded,
+    settledShelfExpanded,
+    props.selectedThreadKey,
     options.selectedEnvironmentId,
     props.searchQuery,
     matchedThreadKeys,
@@ -532,8 +561,15 @@ function ThreadNavigationSidebarPane(
     const items: SidebarListItem[] = buildThreadListV2ListItems({
       items: threadListV2Layout.items,
       pendingTasks: v2PendingTasks,
+      snoozedCount: threadListV2Layout.snoozedCount,
+      snoozedShelfExpanded,
+      snoozedShelfHeaderIndex: threadListV2Layout.snoozedShelfHeaderIndex,
+      settledCount: threadListV2Layout.settledCount,
+      settledShelfExpanded,
+      settledShelfHeaderIndex: threadListV2Layout.settledShelfHeaderIndex,
+      snoozeLabelNow: `${nowMinute}:00.000Z`,
     });
-    if (threadListV2Layout.hiddenSettledCount > 0) {
+    if (settledShelfExpanded && threadListV2Layout.hiddenSettledCount > 0) {
       items.push({
         type: "v2-show-more",
         key: "v2-show-more",
@@ -543,10 +579,13 @@ function ThreadNavigationSidebarPane(
     return items;
   }, [
     listLayout.items,
+    nowMinute,
     options.selectedEnvironmentId,
     pendingTasks,
     props.searchQuery,
     selectedProjectRefs,
+    settledShelfExpanded,
+    snoozedShelfExpanded,
     threadListV2Enabled,
     threadListV2Layout,
   ]);
@@ -731,6 +770,7 @@ function ThreadNavigationSidebarPane(
       projectTitleByProjectKey,
       savedConnectionsById,
       serverConfigs,
+      snoozePresetMinute: nowMinute,
       threadSearchMatchByKey,
     }),
     [
@@ -740,6 +780,7 @@ function ThreadNavigationSidebarPane(
       projectTitleByProjectKey,
       savedConnectionsById,
       serverConfigs,
+      nowMinute,
       threadSearchMatchByKey,
     ],
   );
@@ -750,7 +791,8 @@ function ThreadNavigationSidebarPane(
           previous.key === item.key &&
           previous.item.thread === item.item.thread &&
           previous.item.variant === item.item.variant &&
-          previous.item.showSettledDivider === item.item.showSettledDivider
+          previous.item.snoozed === item.item.snoozed &&
+          previous.snoozeWakeLabelText === item.snoozeWakeLabelText
         );
       }
       if (previous.type === "v2-show-more" && item.type === "v2-show-more") {
@@ -762,13 +804,23 @@ function ThreadNavigationSidebarPane(
           previous.showPendingDivider === item.showPendingDivider
         );
       }
+      if (previous.type === "v2-snoozed-shelf" && item.type === "v2-snoozed-shelf") {
+        return previous.count === item.count && previous.expanded === item.expanded;
+      }
+      if (previous.type === "v2-settled-shelf" && item.type === "v2-settled-shelf") {
+        return previous.count === item.count && previous.expanded === item.expanded;
+      }
       if (
         previous.type === "v2-thread" ||
         previous.type === "v2-show-more" ||
         previous.type === "v2-pending" ||
+        previous.type === "v2-snoozed-shelf" ||
+        previous.type === "v2-settled-shelf" ||
         item.type === "v2-thread" ||
         item.type === "v2-show-more" ||
-        item.type === "v2-pending"
+        item.type === "v2-pending" ||
+        item.type === "v2-snoozed-shelf" ||
+        item.type === "v2-settled-shelf"
       ) {
         return false;
       }
@@ -826,7 +878,9 @@ function ThreadNavigationSidebarPane(
             <ThreadListV2Row
               thread={thread}
               variant={item.item.variant}
-              showSettledDivider={item.item.showSettledDivider}
+              snoozed={item.item.snoozed}
+              snoozePresetMinute={nowMinute}
+              snoozeWakeLabelText={item.snoozeWakeLabelText}
               project={projectByKey.get(scopeKey) ?? null}
               projectTitle={projectTitleByProjectKey.get(scopeKey)}
               providerDriver={
@@ -860,6 +914,9 @@ function ThreadNavigationSidebarPane(
               onArchiveThread={archiveThread}
               settlementSupported={settlementEnvironmentIds.has(thread.environmentId)}
               onSettleThread={settleThread}
+              snoozeSupported={snoozeEnvironmentIds.has(thread.environmentId)}
+              onSnoozeThread={snoozeThread}
+              onUnsnoozeThread={unsnoozeThread}
               onUnsettleThread={unsettleThread}
               onChangeRequestState={handleChangeRequestState}
               projectCwd={projectCwdByKey.get(scopeKey) ?? null}
@@ -869,6 +926,24 @@ function ThreadNavigationSidebarPane(
             />
           );
         }
+        case "v2-snoozed-shelf":
+          return (
+            <ThreadListV2SnoozedShelfHeader
+              count={item.count}
+              expanded={item.expanded}
+              onToggle={toggleSnoozedShelf}
+              pane="sidebar"
+            />
+          );
+        case "v2-settled-shelf":
+          return (
+            <ThreadListV2SettledShelfHeader
+              count={item.count}
+              expanded={item.expanded}
+              onToggle={toggleSettledShelf}
+              pane="sidebar"
+            />
+          );
         case "v2-show-more":
           return (
             <Pressable
@@ -984,7 +1059,13 @@ function ThreadNavigationSidebarPane(
       settlementEnvironmentIds,
       showMoreSettled,
       sidebarScrollGesture,
+      snoozeEnvironmentIds,
+      snoozeThread,
+      nowMinute,
+      toggleSettledShelf,
+      toggleSnoozedShelf,
       unsettleThread,
+      unsnoozeThread,
       updateGroupDisplay,
     ],
   );
@@ -1031,30 +1112,19 @@ function ThreadNavigationSidebarPane(
       }),
     [filterIcon, filterMenu, props.onOpenSettings],
   );
-  // "No threads yet" over an inbox that is merely all-snoozed reads as
-  // data loss; name the snoozed threads instead.
-  const snoozedCount = threadListV2Layout.snoozedCount;
+  // Snoozed threads need no special case: the shelf header is a list row
+  // even while collapsed.
   const listEmpty = (
     <Text className="px-2 py-4 text-sm text-foreground-muted">
       {catalogState.isLoadingConnections
         ? "Loading threads…"
         : props.searchQuery.trim().length > 0
-          ? threadSearch.isPending && snoozedCount === 0
+          ? threadSearch.isPending
             ? "Searching thread messages…"
-            : snoozedCount > 0
-              ? // Snoozed matches passed this same search filter — "No
-                // matching threads" would misreport them as nonexistent.
-                snoozedCount === 1
-                ? "1 matching thread snoozed"
-                : "All matching threads snoozed"
-              : "No matching threads"
-          : snoozedCount > 0
-            ? snoozedCount === 1
-              ? "1 thread snoozed"
-              : `${snoozedCount} threads snoozed`
-            : selectedProjectScope !== null
-              ? `No threads in ${selectedProjectScope.title}`
-              : "No threads yet"}
+            : "No matching threads"
+          : selectedProjectScope !== null
+            ? `No threads in ${selectedProjectScope.title}`
+            : "No threads yet"}
     </Text>
   );
 
diff --git a/apps/mobile/src/features/threads/new-task-flow-provider.tsx b/apps/mobile/src/features/threads/new-task-flow-provider.tsx
index 74fe2f4852a..8d4ce7a7fed 100644
--- a/apps/mobile/src/features/threads/new-task-flow-provider.tsx
+++ b/apps/mobile/src/features/threads/new-task-flow-provider.tsx
@@ -22,7 +22,11 @@ import { useEnvironmentServerConfig, useProjects, useThreadShells } from "../../
 import type { TurnCommandMetadata } from "../../lib/commandMetadata";
 import type { DraftComposerImageAttachment } from "../../lib/composerImages";
 import type { ModelOption, ProviderGroup } from "../../lib/modelOptions";
-import { buildModelOptions, groupByProvider } from "../../lib/modelOptions";
+import {
+  buildModelOptions,
+  groupByProvider,
+  resolveSelectableModelSelection,
+} from "../../lib/modelOptions";
 import { groupProjectsByRepository } from "../../lib/repositoryGroups";
 import { scopedProjectKey } from "../../lib/scopedEntities";
 import { appAtomRegistry } from "../../state/atom-registry";
@@ -347,7 +351,11 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) {
   const selectedProjectDraft = useComposerDraft(selectedProjectDraftKey);
   const prompt = selectedProjectDraft.text;
   const attachments = selectedProjectDraft.attachments;
-  const workspaceMode = selectedProjectDraft.workspaceSelection?.mode ?? "local";
+  // The server's configured default decides the mode until the user picks one
+  // explicitly — same resolution web uses for new draft threads.
+  const defaultWorkspaceMode: WorkspaceMode =
+    selectedEnvironmentServerConfig?.settings.defaultThreadEnvMode ?? "local";
+  const workspaceMode = selectedProjectDraft.workspaceSelection?.mode ?? defaultWorkspaceMode;
   const selectedBranchName = selectedProjectDraft.workspaceSelection?.branch ?? null;
   const selectedWorktreePath = selectedProjectDraft.workspaceSelection?.worktreePath ?? null;
   // Keep the user's explicit choice separate from the resolved display value:
@@ -361,22 +369,29 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) {
   const runtimeMode = selectedProjectDraft.runtimeMode ?? DEFAULT_RUNTIME_MODE;
   const interactionMode = selectedProjectDraft.interactionMode ?? DEFAULT_PROVIDER_INTERACTION_MODE;
 
+  // Stored selections (draft and project default) only count while their
+  // provider is usable on the server; otherwise the server's default model
+  // wins instead of silently targeting a disabled provider.
+  const draftModelSelection = resolveSelectableModelSelection(
+    selectedEnvironmentServerConfig,
+    selectedProjectDraft.modelSelection ?? null,
+  );
+  const projectDefaultModelSelection = resolveSelectableModelSelection(
+    selectedEnvironmentServerConfig,
+    selectedProject?.defaultModelSelection ?? null,
+  );
   const modelOptions = useMemo(
     () =>
       buildModelOptions(
         selectedEnvironmentServerConfig,
-        selectedProjectDraft.modelSelection ?? selectedProject?.defaultModelSelection ?? null,
+        draftModelSelection ?? projectDefaultModelSelection,
       ),
-    [
-      selectedEnvironmentServerConfig,
-      selectedProject?.defaultModelSelection,
-      selectedProjectDraft.modelSelection,
-    ],
+    [selectedEnvironmentServerConfig, draftModelSelection, projectDefaultModelSelection],
   );
 
   const selectedModel =
-    selectedProjectDraft.modelSelection ??
-    selectedProject?.defaultModelSelection ??
+    draftModelSelection ??
+    projectDefaultModelSelection ??
     modelOptions.find((option) => option.isDefault)?.selection ??
     modelOptions[0]?.selection ??
     null;
@@ -675,12 +690,20 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) {
       }
       const draft = getComposerDraftSnapshot(selectedProjectDraftKey);
       const text = draft.text.trim();
-      const draftModelSelection = draft.modelSelection ?? selectedModel;
+      // Same availability gate the composer display applies: a stored
+      // selection targeting a disabled provider must not ride into the queue.
+      const draftModelSelection =
+        resolveSelectableModelSelection(
+          selectedEnvironmentServerConfig,
+          draft.modelSelection ?? null,
+        ) ?? selectedModel;
       if (text.length === 0 || !draftModelSelection) {
         return null;
       }
       const workspaceSelection = draft.workspaceSelection;
-      const mode = workspaceSelection?.mode ?? "local";
+      // Fall back to the resolved mode (server default) so queued tasks drain
+      // with the same mode the composer displayed.
+      const mode = workspaceSelection?.mode ?? workspaceMode;
       // When the selection is the stand-in built from the queued snapshot,
       // persist the original (possibly absent) snapshot values — the
       // stand-in's placeholder title/workspaceRoot must never be written back
@@ -722,10 +745,12 @@ export function NewTaskFlowProvider(props: React.PropsWithChildren) {
     [
       editingPendingProject,
       editingPendingTask,
+      selectedEnvironmentServerConfig,
       selectedModel,
       selectedProject,
       selectedProjectDraftKey,
       startFromOrigin,
+      workspaceMode,
     ],
   );
 
diff --git a/apps/mobile/src/features/threads/sidebar-navigation-shell.tsx b/apps/mobile/src/features/threads/sidebar-navigation-shell.tsx
index f0e3f89c07d..4be4089a54d 100644
--- a/apps/mobile/src/features/threads/sidebar-navigation-shell.tsx
+++ b/apps/mobile/src/features/threads/sidebar-navigation-shell.tsx
@@ -11,6 +11,7 @@ import {
 import type { ReactNode } from "react";
 import { Platform, useColorScheme } from "react-native";
 
+import { getCompactBrandHeaderOptions } from "../../components/CompactBrandTitle";
 import { NATIVE_LIQUID_GLASS_SUPPORTED } from "../../native/native-glass";
 import { nativeHeaderScrollEdgeEffects } from "../../native/StackHeader";
 
@@ -35,10 +36,9 @@ const SIDEBAR_SCREEN_OPTIONS: SidebarScreenOptions = {
   headerShadowVisible: false,
   headerShown: true,
   headerStyle: NATIVE_LIQUID_GLASS_SUPPORTED ? { backgroundColor: "transparent" } : undefined,
-  headerTitleStyle: { fontSize: 18, fontWeight: "800" },
+  ...getCompactBrandHeaderOptions({ fontSize: 18, fontWeight: "800" }),
   headerTransparent: NATIVE_LIQUID_GLASS_SUPPORTED,
   scrollEdgeEffects: NATIVE_LIQUID_GLASS_SUPPORTED ? SCROLL_EDGE_EFFECTS : undefined,
-  title: "Threads",
   unstable_navigationItemStyle: NATIVE_LIQUID_GLASS_SUPPORTED ? "editor" : undefined,
 };
 
diff --git a/apps/mobile/src/features/threads/thread-list-items.tsx b/apps/mobile/src/features/threads/thread-list-items.tsx
index 9ac4002a9b0..855713946ff 100644
--- a/apps/mobile/src/features/threads/thread-list-items.tsx
+++ b/apps/mobile/src/features/threads/thread-list-items.tsx
@@ -15,6 +15,7 @@ import { AppText as Text } from "../../components/AppText";
 import { ControlPillMenu } from "../../components/ControlPill";
 import { ProjectFavicon } from "../../components/ProjectFavicon";
 import { cn } from "../../lib/cn";
+import { HOME_HORIZONTAL_INSET } from "../../lib/layoutMetrics";
 import { relativeTime } from "../../lib/time";
 import { useThemeColor } from "../../lib/useThemeColor";
 import type { PendingNewTask } from "../../state/use-pending-new-tasks";
@@ -33,7 +34,7 @@ import { ThreadSearchMatchExcerpt } from "./thread-search-match";
 export type ThreadListVariant = "compact" | "sidebar";
 
 /** Left inset that aligns compact secondary rows with the title column. */
-export const THREAD_LIST_COMPACT_INSET = 20;
+export const THREAD_LIST_COMPACT_INSET = HOME_HORIZONTAL_INSET;
 const SIDEBAR_ROW_RADIUS = 12;
 
 function pullRequestTintColor(
diff --git a/apps/mobile/src/features/threads/thread-list-v2-items.tsx b/apps/mobile/src/features/threads/thread-list-v2-items.tsx
index 6af5795a94a..8d6874c7855 100644
--- a/apps/mobile/src/features/threads/thread-list-v2-items.tsx
+++ b/apps/mobile/src/features/threads/thread-list-v2-items.tsx
@@ -3,11 +3,20 @@ import type {
   EnvironmentThreadShell,
 } from "@t3tools/client-runtime/state/shell";
 import type { EnvironmentThreadSearchMatch } from "@t3tools/client-runtime/state/thread-search";
+import { canSnooze, resolveSnoozePresets } from "@t3tools/client-runtime/state/thread-settled";
 import type { MenuAction } from "@react-native-menu/menu";
-import { memo, useCallback, useEffect, useMemo, type ComponentProps } from "react";
-import { Platform, Pressable, useWindowDimensions, View } from "react-native";
+import { memo, useCallback, useEffect, useMemo, useState, type ComponentProps } from "react";
+import {
+  Alert,
+  Platform,
+  Pressable,
+  useColorScheme,
+  useWindowDimensions,
+  View,
+} from "react-native";
 import type { SwipeableMethods } from "react-native-gesture-handler/ReanimatedSwipeable";
 
+import { SymbolView } from "../../components/AppSymbol";
 import { AppText as Text } from "../../components/AppText";
 import { ControlPillMenu } from "../../components/ControlPill";
 import { ProjectFavicon } from "../../components/ProjectFavicon";
@@ -18,7 +27,13 @@ import { useThemeColor } from "../../lib/useThemeColor";
 import type { PendingNewTask } from "../../state/use-pending-new-tasks";
 import { useThreadPr } from "../../state/use-thread-pr";
 import { ThreadSwipeable } from "../home/thread-swipe-actions";
-import { resolveThreadListV2Status, type ThreadListV2Status } from "./threadListV2";
+import {
+  resolveThreadListV2SnoozeMenuSelection,
+  resolveThreadListV2SnoozeGateExpiryMs,
+  resolveThreadListV2Status,
+  resolveThreadListV2SwipeActions,
+  type ThreadListV2Status,
+} from "./threadListV2";
 import { ThreadSearchMatchExcerpt } from "./thread-search-match";
 
 /**
@@ -62,6 +77,11 @@ const SLIM_MENU_ACTIONS: MenuAction[] = [
   { id: "delete", title: "Delete", image: "trash", attributes: { destructive: true } },
 ];
 
+const SNOOZED_MENU_ACTIONS: MenuAction[] = [
+  { id: "unsnooze", title: "Wake thread", image: "clock" },
+  { id: "delete", title: "Delete", image: "trash", attributes: { destructive: true } },
+];
+
 // Pre-settlement servers: no lifecycle items, archive fills the gap.
 const LEGACY_MENU_ACTIONS: MenuAction[] = [
   { id: "archive", title: "Archive", image: "archivebox" },
@@ -90,6 +110,81 @@ export const ThreadListV2SectionDivider = memo(function ThreadListV2SectionDivid
   );
 });
 
+const SNOOZE_ACCENT_LIGHT = "#2563eb";
+const SNOOZE_ACCENT_DARK = "#60a5fa";
+
+export const ThreadListV2SnoozedShelfHeader = memo(function ThreadListV2SnoozedShelfHeader(props: {
+  readonly count: number;
+  readonly expanded: boolean;
+  readonly onToggle: () => void;
+  readonly pane?: "screen" | "sidebar";
+}) {
+  const colorScheme = useColorScheme();
+  return (
+    <Pressable
+      accessibilityHint={
+        props.expanded ? "Collapses the snoozed threads." : "Expands the snoozed threads."
+      }
+      accessibilityLabel={props.count === 1 ? "1 snoozed thread" : `${props.count} snoozed threads`}
+      accessibilityRole="button"
+      accessibilityState={{ expanded: props.expanded }}
+      className={cn(
+        "mb-1.5 mt-4 flex-row items-center gap-2.5",
+        props.pane === "sidebar" ? "px-3" : "px-5",
+      )}
+      onPress={props.onToggle}
+      style={({ pressed }) => ({ opacity: pressed ? 0.6 : 1 })}
+    >
+      <Text className="text-xs font-t3-medium text-blue-600 dark:text-blue-400">
+        {props.expanded ? "Snoozed" : `Snoozed (${props.count})`}
+      </Text>
+      <View className="h-px flex-1 bg-blue-500/20 dark:bg-blue-400/15" />
+      <SymbolView
+        name={props.expanded ? "chevron.up" : "chevron.down"}
+        size={10}
+        tintColor={colorScheme === "dark" ? SNOOZE_ACCENT_DARK : SNOOZE_ACCENT_LIGHT}
+        type="monochrome"
+      />
+    </Pressable>
+  );
+});
+
+export const ThreadListV2SettledShelfHeader = memo(function ThreadListV2SettledShelfHeader(props: {
+  readonly count: number;
+  readonly expanded: boolean;
+  readonly onToggle: () => void;
+  readonly pane?: "screen" | "sidebar";
+}) {
+  const mutedColor = useThemeColor("--color-foreground-muted");
+  return (
+    <Pressable
+      accessibilityHint={
+        props.expanded ? "Collapses the settled threads." : "Expands the settled threads."
+      }
+      accessibilityLabel={props.count === 1 ? "1 settled thread" : `${props.count} settled threads`}
+      accessibilityRole="button"
+      accessibilityState={{ expanded: props.expanded }}
+      className={cn(
+        "mb-1.5 mt-4 flex-row items-center gap-2.5",
+        props.pane === "sidebar" ? "px-3" : "px-5",
+      )}
+      onPress={props.onToggle}
+      style={({ pressed }) => ({ opacity: pressed ? 0.6 : 1 })}
+    >
+      <Text className="text-xs font-t3-medium text-foreground-tertiary">
+        {props.expanded ? "Settled" : `Settled (${props.count})`}
+      </Text>
+      <View className="h-px flex-1 bg-border" />
+      <SymbolView
+        name={props.expanded ? "chevron.up" : "chevron.down"}
+        size={10}
+        tintColor={mutedColor}
+        type="monochrome"
+      />
+    </Pressable>
+  );
+});
+
 const PENDING_TASK_MENU_ACTIONS: MenuAction[] = [
   { id: "delete", title: "Delete", image: "trash", attributes: { destructive: true } },
 ];
@@ -208,7 +303,14 @@ export const ThreadListV2PendingRow = memo(function ThreadListV2PendingRow(props
 export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
   readonly thread: EnvironmentThreadShell;
   readonly variant: "card" | "slim";
-  readonly showSettledDivider: boolean;
+  /** Snoozed-shelf row: shows its wake time and offers Wake. */
+  readonly snoozed?: boolean;
+  /** Preformatted against the parent minute tick so this memoized row's
+      countdown keeps moving. */
+  readonly snoozeWakeLabelText?: string;
+  /** Parent minute tick passed as a prop so this memoized row refreshes its
+      native snooze menu while mounted. */
+  readonly snoozePresetMinute: string;
   readonly project: EnvironmentProject | null;
   readonly projectTitle?: string;
   readonly providerDriver: string | null;
@@ -231,11 +333,15 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
   readonly onSelectThread: (thread: EnvironmentThreadShell) => void;
   readonly onDeleteThread: (thread: EnvironmentThreadShell) => void;
   readonly onSettleThread: (thread: EnvironmentThreadShell) => void;
+  readonly onSnoozeThread: (thread: EnvironmentThreadShell, snoozedUntil: string) => void;
+  readonly onUnsnoozeThread: (thread: EnvironmentThreadShell) => void;
   readonly onUnsettleThread: (thread: EnvironmentThreadShell) => void;
   readonly onArchiveThread: (thread: EnvironmentThreadShell) => void;
   /** False on environments whose server predates thread.settle/unsettle:
       swipe + menu fall back to Archive instead of failing on use. */
   readonly settlementSupported: boolean;
+  /** False on servers that predate thread.snooze/unsnooze. */
+  readonly snoozeSupported: boolean;
   readonly onSwipeableWillOpen: (methods: SwipeableMethods) => void;
   readonly onSwipeableClose: (methods: SwipeableMethods) => void;
   /** Reports this row's live PR state up so the partition can auto-settle
@@ -258,10 +364,13 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
     onSelectThread,
     onDeleteThread,
     onSettleThread,
+    onSnoozeThread,
+    onUnsnoozeThread,
     onUnsettleThread,
     onArchiveThread,
     onChangeRequestState,
   } = props;
+  const snoozedRow = props.snoozed === true;
 
   const pr = useThreadPr(thread, props.projectCwd ?? props.project?.workspaceRoot ?? null);
   const prState = pr?.state ?? null;
@@ -283,27 +392,94 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
 
   const handleDelete = useCallback(() => onDeleteThread(thread), [onDeleteThread, thread]);
   const handleSettle = useCallback(() => onSettleThread(thread), [onSettleThread, thread]);
+  const handleSnooze = useCallback(
+    (snoozedUntil: string) => onSnoozeThread(thread, snoozedUntil),
+    [onSnoozeThread, thread],
+  );
+  const handleUnsnooze = useCallback(() => onUnsnoozeThread(thread), [onUnsnoozeThread, thread]);
   const handleUnsettle = useCallback(() => onUnsettleThread(thread), [onUnsettleThread, thread]);
   const handleArchive = useCallback(() => onArchiveThread(thread), [onArchiveThread, thread]);
+
+  // Swipe: the v2 primary action is the lifecycle transition. Every settled
+  // row can un-settle — explicit settles clear the override, auto-settled
+  // rows get pinned active until real activity clears the pin.
+  const canUnsettle = variant === "slim";
+  const [snoozeGateTick, bumpSnoozeGateTick] = useState(0);
+  const snoozeGateExpiryMs = props.snoozeSupported
+    ? resolveThreadListV2SnoozeGateExpiryMs(thread, { now: new Date().toISOString() })
+    : null;
+  useEffect(() => {
+    if (snoozeGateExpiryMs === null) return;
+    const delayMs = Math.min(Math.max(0, snoozeGateExpiryMs - Date.now()) + 50, 2_147_483_647);
+    const id = setTimeout(() => bumpSnoozeGateTick((tick) => tick + 1), delayMs);
+    return () => clearTimeout(id);
+  }, [snoozeGateExpiryMs, snoozeGateTick]);
+  const swipeActions = resolveThreadListV2SwipeActions({
+    variant,
+    settlementSupported: props.settlementSupported,
+    snoozeSupported: props.snoozeSupported,
+    snoozable: canSnooze(thread, { now: new Date().toISOString() }),
+    snoozed: snoozedRow,
+  });
+  const snoozePresets = useMemo(
+    () => (swipeActions.secondary === "snooze" ? resolveSnoozePresets(new Date()) : ([] as const)),
+    [props.snoozePresetMinute, swipeActions.secondary],
+  );
+  const snoozePresetActions = useMemo<MenuAction[]>(
+    () =>
+      snoozePresets.map((preset) => ({
+        id: `snooze:${preset.id}`,
+        title: preset.label,
+        subtitle: preset.whenLabel,
+      })),
+    [snoozePresets],
+  );
+  const snoozableCardMenuActions = useMemo<MenuAction[]>(
+    () => [
+      { id: "settle", title: "Settle", image: "checkmark" },
+      {
+        id: "snooze",
+        title: "Snooze",
+        image: "clock",
+        subactions: snoozePresetActions,
+      },
+      { id: "delete", title: "Delete", image: "trash", attributes: { destructive: true } },
+    ],
+    [snoozePresetActions],
+  );
   const handleMenuAction = useCallback(
     ({ nativeEvent }: { readonly nativeEvent: { readonly event: string } }) => {
       if (nativeEvent.event === "settle") handleSettle();
       if (nativeEvent.event === "unsettle") handleUnsettle();
+      if (nativeEvent.event === "unsnooze") handleUnsnooze();
       if (nativeEvent.event === "archive") handleArchive();
       if (nativeEvent.event === "delete") handleDelete();
+      const snoozeSelection = resolveThreadListV2SnoozeMenuSelection({
+        event: nativeEvent.event,
+        displayedPresets: snoozePresets,
+        now: new Date(),
+      });
+      if (snoozeSelection._tag === "selected") {
+        handleSnooze(snoozeSelection.preset.snoozedUntil);
+      } else if (snoozeSelection._tag === "expired") {
+        Alert.alert("Could not snooze thread", "That snooze time has passed. Choose another time.");
+      }
     },
-    [handleArchive, handleDelete, handleSettle, handleUnsettle],
+    [
+      handleArchive,
+      handleDelete,
+      handleSettle,
+      handleSnooze,
+      handleUnsettle,
+      handleUnsnooze,
+      snoozePresets,
+    ],
   );
-
-  // Swipe: the v2 primary action is the lifecycle transition. Every settled
-  // row can un-settle — explicit settles clear the override, auto-settled
-  // rows get pinned active until real activity clears the pin.
-  const canUnsettle = variant === "slim";
   const primaryAction = useMemo(() => {
     // Pre-settlement server: archive is the swipe action, as in v1. (Slim
     // rows cannot occur here — unsupported environments never classify as
     // settled.)
-    if (!props.settlementSupported) {
+    if (swipeActions.primary === "archive") {
       return {
         accessibilityLabel: `Archive ${thread.title}`,
         icon: "archivebox" as const,
@@ -311,7 +487,15 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
         onPress: handleArchive,
       };
     }
-    return canUnsettle
+    if (swipeActions.primary === "unsnooze") {
+      return {
+        accessibilityLabel: `Wake ${thread.title} now`,
+        icon: "clock" as const,
+        label: "Wake",
+        onPress: handleUnsnooze,
+      };
+    }
+    return swipeActions.primary === "unsettle"
       ? {
           accessibilityLabel: `Un-settle ${thread.title}`,
           icon: "arrow.uturn.backward" as const,
@@ -325,13 +509,34 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
           onPress: handleSettle,
         };
   }, [
-    canUnsettle,
     handleArchive,
     handleSettle,
     handleUnsettle,
-    props.settlementSupported,
+    handleUnsnooze,
+    swipeActions.primary,
     thread.title,
   ]);
+  const secondaryAction = useMemo(
+    () =>
+      swipeActions.secondary === "snooze"
+        ? {
+            accessibilityLabel: `Choose when to snooze ${thread.title}`,
+            icon: "clock" as const,
+            label: "Snooze",
+            menu: {
+              actions: snoozePresetActions,
+              onPressAction: handleMenuAction,
+              title: "Snooze until",
+            },
+            onPress: () => undefined,
+          }
+        : null,
+    [handleMenuAction, snoozePresetActions, swipeActions.secondary, thread.title],
+  );
+  const swipeAccessibilityHint =
+    secondaryAction === null
+      ? `Opens the thread. Swipe left to ${primaryAction.label.toLowerCase()}.`
+      : `Opens the thread. Swipe left for ${primaryAction.label.toLowerCase()} and snooze actions.`;
 
   // The sidebar pane fills selected rows with the accent color (matching the
   // v1 sidebar), so every piece of row text needs a white-on-accent variant.
@@ -453,7 +658,7 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
   const rowContent = (close: () => void) =>
     variant === "card" ? (
       <Pressable
-        accessibilityHint={`Opens the thread. Swipe left to ${primaryAction.label.toLowerCase()}.`}
+        accessibilityHint={swipeAccessibilityHint}
         accessibilityLabel={thread.title}
         accessibilityRole="button"
         accessibilityState={{ selected }}
@@ -491,7 +696,7 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
       </Pressable>
     ) : (
       <Pressable
-        accessibilityHint={`Opens the thread. Swipe left to ${primaryAction.label.toLowerCase()}.`}
+        accessibilityHint={swipeAccessibilityHint}
         accessibilityLabel={thread.title}
         accessibilityRole="button"
         accessibilityState={{ selected }}
@@ -551,11 +756,17 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
           <Text
             className={cn(
               "text-sm tabular-nums",
-              selected ? "text-user-bubble-foreground-muted" : "text-foreground-tertiary",
+              selected
+                ? "text-user-bubble-foreground-muted"
+                : snoozedRow
+                  ? "text-blue-600 dark:text-blue-400"
+                  : "text-foreground-tertiary",
             )}
             style={{ fontFamily: MONO_FONT }}
           >
-            {relativeTime(thread.latestUserMessageAt ?? thread.updatedAt ?? thread.createdAt)}
+            {snoozedRow && props.snoozeWakeLabelText !== undefined
+              ? props.snoozeWakeLabelText
+              : relativeTime(thread.latestUserMessageAt ?? thread.updatedAt ?? thread.createdAt)}
           </Text>
         </View>
       </Pressable>
@@ -563,9 +774,6 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
 
   return (
     <>
-      {props.showSettledDivider ? (
-        <ThreadListV2SectionDivider label="Settled" pane={props.pane} />
-      ) : null}
       <ThreadSwipeable
         backgroundColor={sidebarPane ? drawerColor : screenColor}
         compactActions={variant === "slim"}
@@ -574,13 +782,14 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
         }
         enableTrackpadSwipe
         // Full swipe commits the advertised lifecycle action (Settle /
-        // Un-settle), never the destructive delete.
+        // Un-settle), never the secondary snooze action.
         fullSwipeAction="primary"
         fullSwipeWidth={props.fullSwipeWidth ?? windowWidth - 32}
         onDelete={handleDelete}
         onSwipeableClose={props.onSwipeableClose}
         onSwipeableWillOpen={props.onSwipeableWillOpen}
         primaryAction={primaryAction}
+        secondaryAction={secondaryAction}
         resetKey={`${thread.environmentId}:${thread.id}`}
         simultaneousWithExternalGesture={props.simultaneousSwipeGesture}
         threadTitle={thread.title}
@@ -588,11 +797,15 @@ export const ThreadListV2Row = memo(function ThreadListV2Row(props: {
         {(close) => (
           <ControlPillMenu
             actions={
-              !props.settlementSupported
-                ? LEGACY_MENU_ACTIONS
-                : canUnsettle
-                  ? SLIM_MENU_ACTIONS
-                  : CARD_MENU_ACTIONS
+              snoozedRow
+                ? SNOOZED_MENU_ACTIONS
+                : !props.settlementSupported
+                  ? LEGACY_MENU_ACTIONS
+                  : canUnsettle
+                    ? SLIM_MENU_ACTIONS
+                    : swipeActions.secondary === "snooze"
+                      ? snoozableCardMenuActions
+                      : CARD_MENU_ACTIONS
             }
             onPressAction={handleMenuAction}
             shouldOpenOnLongPress
diff --git a/apps/mobile/src/features/threads/threadListV2.test.ts b/apps/mobile/src/features/threads/threadListV2.test.ts
index 90b5897f18e..99b5700f7b0 100644
--- a/apps/mobile/src/features/threads/threadListV2.test.ts
+++ b/apps/mobile/src/features/threads/threadListV2.test.ts
@@ -1,5 +1,6 @@
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-search";
+import { resolveSnoozePresets } from "@t3tools/client-runtime/state/thread-settled";
 import {
   CommandId,
   EnvironmentId,
@@ -16,7 +17,10 @@ import {
   buildThreadListV2Items,
   buildThreadListV2ListItems,
   resolveThreadListV2Enabled,
+  resolveThreadListV2SnoozeMenuSelection,
+  resolveThreadListV2SnoozeGateExpiryMs,
   resolveThreadListV2Status,
+  resolveThreadListV2SwipeActions,
   sortThreadsForListV2,
 } from "./threadListV2";
 
@@ -50,6 +54,54 @@ function makeThread(
 
 const NOW = "2026-06-02T00:00:00.000Z";
 
+describe("resolveThreadListV2SnoozeMenuSelection", () => {
+  it("accepts a displayed evening preset while its wake time is still future", () => {
+    const menuOpenedAt = new Date(2026, 4, 8, 16, 59, 30);
+    const selectedAt = new Date(2026, 4, 8, 17, 0, 30);
+    const displayedPresets = resolveSnoozePresets(menuOpenedAt);
+
+    const selection = resolveThreadListV2SnoozeMenuSelection({
+      event: "snooze:evening",
+      displayedPresets,
+      now: selectedAt,
+    });
+
+    expect(selection).toEqual({
+      _tag: "selected",
+      preset: displayedPresets.find((preset) => preset.id === "evening"),
+    });
+  });
+
+  it("expires a displayed preset once its wake time has passed", () => {
+    const displayedPresets = resolveSnoozePresets(new Date(2026, 4, 8, 16, 59, 30));
+
+    expect(
+      resolveThreadListV2SnoozeMenuSelection({
+        event: "snooze:evening",
+        displayedPresets,
+        now: new Date(2026, 4, 8, 18, 0, 1),
+      }),
+    ).toEqual({ _tag: "expired" });
+  });
+
+  it("recomputes presets that remain available instead of using old timestamps", () => {
+    const displayedPresets = resolveSnoozePresets(new Date(2026, 4, 8, 10));
+    const selectedAt = new Date(2026, 4, 8, 10, 30);
+    const selection = resolveThreadListV2SnoozeMenuSelection({
+      event: "snooze:hour",
+      displayedPresets,
+      now: selectedAt,
+    });
+
+    expect(selection._tag).toBe("selected");
+    if (selection._tag === "selected") {
+      expect(selection.preset.snoozedUntil).toBe(
+        new Date(selectedAt.getTime() + 60 * 60 * 1_000).toISOString(),
+      );
+    }
+  });
+});
+
 describe("resolveThreadListV2Enabled", () => {
   it("defaults on when the device has never chosen", () => {
     expect(resolveThreadListV2Enabled({ preference: undefined, preferencesLoaded: true })).toBe(
@@ -96,6 +148,105 @@ describe("resolveThreadListV2Status", () => {
   });
 });
 
+describe("resolveThreadListV2SwipeActions", () => {
+  it("offers settle and snooze for an active snoozable thread", () => {
+    expect(
+      resolveThreadListV2SwipeActions({
+        variant: "card",
+        settlementSupported: true,
+        snoozeSupported: true,
+        snoozable: true,
+      }),
+    ).toEqual({ primary: "settle", secondary: "snooze" });
+  });
+
+  it("offers un-settle and snooze for settled history", () => {
+    expect(
+      resolveThreadListV2SwipeActions({
+        variant: "slim",
+        settlementSupported: true,
+        snoozeSupported: true,
+        snoozable: true,
+      }),
+    ).toEqual({ primary: "unsettle", secondary: "snooze" });
+  });
+
+  it("omits snooze when the server or thread does not allow it", () => {
+    expect(
+      resolveThreadListV2SwipeActions({
+        variant: "card",
+        settlementSupported: true,
+        snoozeSupported: false,
+        snoozable: true,
+      }),
+    ).toEqual({ primary: "settle", secondary: null });
+    expect(
+      resolveThreadListV2SwipeActions({
+        variant: "card",
+        settlementSupported: true,
+        snoozeSupported: true,
+        snoozable: false,
+      }),
+    ).toEqual({ primary: "settle", secondary: null });
+  });
+
+  it("falls back to archive only for a pre-lifecycle server", () => {
+    expect(
+      resolveThreadListV2SwipeActions({
+        variant: "card",
+        settlementSupported: false,
+        snoozeSupported: false,
+        snoozable: true,
+      }),
+    ).toEqual({ primary: "archive", secondary: null });
+  });
+
+  it("offers wake and no snooze on a snoozed row", () => {
+    expect(
+      resolveThreadListV2SwipeActions({
+        variant: "slim",
+        settlementSupported: true,
+        snoozeSupported: true,
+        snoozable: true,
+        snoozed: true,
+      }),
+    ).toEqual({ primary: "unsnooze", secondary: null });
+  });
+});
+
+describe("resolveThreadListV2SnoozeGateExpiryMs", () => {
+  it("reports when an unadopted turn's grace window lapses", () => {
+    const thread = makeThread({
+      id: ThreadId.make("t"),
+      title: "t",
+      latestUserMessageAt: "2026-06-02T00:00:30.000Z",
+    });
+    expect(resolveThreadListV2SnoozeGateExpiryMs(thread, { now: "2026-06-02T00:01:00.000Z" })).toBe(
+      Date.parse("2026-06-02T00:02:30.000Z"),
+    );
+  });
+
+  it("returns null once the thread is snoozable or when only data can unblock it", () => {
+    expect(
+      resolveThreadListV2SnoozeGateExpiryMs(
+        makeThread({ id: ThreadId.make("ready"), title: "Ready" }),
+        { now: NOW },
+      ),
+    ).toBe(null);
+    expect(
+      resolveThreadListV2SnoozeGateExpiryMs(
+        makeThread({
+          id: ThreadId.make("blocked"),
+          title: "Blocked",
+          hasPendingApprovals: true,
+          latestUserMessageAt: NOW,
+        }),
+        { now: NOW },
+      ),
+    ).toBe(null);
+  });
+});
+
 describe("sortThreadsForListV2", () => {
   it("orders by creation time, newest first, ignoring activity", () => {
     const sorted = sortThreadsForListV2([
@@ -167,6 +318,93 @@ describe("buildThreadListV2Items", () => {
     expect(layout.nextSnoozeWakeAt).toBe("2026-06-02T09:00:00.000Z");
   });
 
+  it("builds snoozed rows between active and settled when the shelf is expanded", () => {
+    const layout = buildThreadListV2Items({
+      threads: [
+        makeThread({ id: ThreadId.make("active"), title: "Active" }),
+        makeThread({
+          id: ThreadId.make("settled"),
+          title: "Settled",
+          settledOverride: "settled",
+          settledAt: NOW,
+        }),
+        makeThread({
+          id: ThreadId.make("later"),
+          title: "Wakes later",
+          snoozedUntil: "2026-06-03T09:00:00.000Z",
+          snoozedAt: "2026-06-01T12:00:00.000Z",
+        }),
+        makeThread({
+          id: ThreadId.make("sooner"),
+          title: "Wakes sooner",
+          snoozedUntil: "2026-06-02T09:00:00.000Z",
+          snoozedAt: "2026-06-01T12:00:00.000Z",
+        }),
+      ],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+      snoozedShelfExpanded: true,
+    });
+
+    expect(layout.items.map((item) => item.thread.id)).toEqual([
+      "active",
+      "sooner",
+      "later",
+      "settled",
+    ]);
+    expect(layout.items.map((item) => item.snoozed)).toEqual([false, true, true, false]);
+    expect(layout.snoozedShelfHeaderIndex).toBe(1);
+    expect(layout.snoozedCount).toBe(2);
+  });
+
+  it("collapses to a header-only shelf", () => {
+    const layout = buildThreadListV2Items({
+      threads: [
+        makeThread({
+          id: ThreadId.make("snoozed"),
+          title: "Snoozed",
+          snoozedUntil: "2026-06-03T09:00:00.000Z",
+          snoozedAt: "2026-06-01T12:00:00.000Z",
+        }),
+      ],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+    });
+
+    expect(layout.items).toEqual([]);
+    expect(layout.snoozedCount).toBe(1);
+    expect(layout.snoozedShelfHeaderIndex).toBe(0);
+  });
+
+  it("keeps the selected thread on a collapsed shelf", () => {
+    const layout = buildThreadListV2Items({
+      threads: [
+        makeThread({
+          id: ThreadId.make("open"),
+          title: "Open",
+          snoozedUntil: "2026-06-03T09:00:00.000Z",
+          snoozedAt: "2026-06-01T12:00:00.000Z",
+        }),
+        makeThread({
+          id: ThreadId.make("other"),
+          title: "Other",
+          snoozedUntil: "2026-06-03T10:00:00.000Z",
+          snoozedAt: "2026-06-01T12:00:00.000Z",
+        }),
+      ],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+      selectedThreadKey: `${environmentId}:open`,
+    });
+
+    expect(layout.items.map((item) => item.thread.id)).toEqual(["open"]);
+    expect(layout.items[0]?.snoozed).toBe(true);
+    expect(layout.snoozedCount).toBe(2);
+  });
+
   it("keeps snoozed threads visible on environments without the snooze capability", () => {
     const layout = buildThreadListV2Items({
       threads: [
@@ -187,8 +425,8 @@ describe("buildThreadListV2Items", () => {
     expect(layout.snoozedCount).toBe(0);
   });
 
-  it("partitions settled threads into a slim tail with one divider", () => {
-    const { items } = buildThreadListV2Items({
+  it("partitions settled threads into a slim shelf", () => {
+    const layout = buildThreadListV2Items({
       threads: [
         makeThread({ id: ThreadId.make("active"), title: "Active" }),
         makeThread({
@@ -209,13 +447,64 @@ describe("buildThreadListV2Items", () => {
       now: NOW,
     });
 
-    expect(items.map((item) => [item.thread.id, item.variant])).toEqual([
+    expect(layout.items.map((item) => [item.thread.id, item.variant])).toEqual([
       ["active", "card"],
       ["settled", "slim"],
       ["settled-2", "slim"],
     ]);
-    expect(items.map((item) => item.showSettledDivider)).toEqual([false, true, false]);
-    expect(items.map((item) => item.isLast)).toEqual([false, false, true]);
+    expect(layout.items.map((item) => item.isLast)).toEqual([false, false, true]);
+    expect(layout.settledCount).toBe(2);
+    expect(layout.settledShelfHeaderIndex).toBe(1);
+  });
+
+  it("collapses settled threads to a counted shelf header", () => {
+    const layout = buildThreadListV2Items({
+      threads: [
+        makeThread({ id: ThreadId.make("active"), title: "Active" }),
+        makeThread({
+          id: ThreadId.make("settled"),
+          title: "Settled",
+          settledOverride: "settled",
+          settledAt: NOW,
+        }),
+      ],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+      settledShelfExpanded: false,
+    });
+
+    expect(layout.items.map((item) => item.thread.id)).toEqual(["active"]);
+    expect(layout.settledCount).toBe(1);
+    expect(layout.settledShelfHeaderIndex).toBe(1);
+  });
+
+  it("keeps the selected settled thread visible when its shelf is collapsed", () => {
+    const layout = buildThreadListV2Items({
+      threads: [
+        makeThread({
+          id: ThreadId.make("selected"),
+          title: "Selected",
+          settledOverride: "settled",
+          settledAt: NOW,
+        }),
+        makeThread({
+          id: ThreadId.make("other"),
+          title: "Other",
+          settledOverride: "settled",
+          settledAt: NOW,
+        }),
+      ],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+      settledShelfExpanded: false,
+      selectedThreadKey: `${environmentId}:selected`,
+    });
+
+    expect(layout.items.map((item) => item.thread.id)).toEqual(["selected"]);
+    expect(layout.settledCount).toBe(2);
+    expect(layout.settledShelfHeaderIndex).toBe(0);
   });
 
   it("keeps cards in creation order while settled sorts by recency", () => {
@@ -420,13 +709,21 @@ describe("buildThreadListV2ListItems", () => {
     const items = buildThreadListV2ListItems({
       items: layout.items,
       pendingTasks: [makePendingTask("queued-1"), makePendingTask("queued-2")],
+      settledCount: layout.settledCount,
+      settledShelfHeaderIndex: layout.settledShelfHeaderIndex,
     });
 
     expect(
       items.map((item) =>
-        item.type === "v2-pending" ? item.pendingTask.title : item.item.thread.id,
+        item.type === "v2-pending"
+          ? item.pendingTask.title
+          : item.type === "v2-thread"
+            ? item.item.thread.id
+            : item.type === "v2-snoozed-shelf"
+              ? "snoozed-shelf"
+              : "settled-shelf",
       ),
-    ).toEqual(["active", "queued-1", "queued-2", "settled"]);
+    ).toEqual(["active", "queued-1", "queued-2", "settled-shelf", "settled"]);
     // Only the leading queued row labels the section, exactly like Settled.
     expect(
       items.filter((item) => item.type === "v2-pending" && item.showPendingDivider),
@@ -448,12 +745,58 @@ describe("buildThreadListV2ListItems", () => {
     expect(items.map((item) => item.type)).toEqual(["v2-thread", "v2-pending"]);
   });
 
-  it("leaves the thread order untouched when nothing is queued", () => {
-    const items = buildThreadListV2ListItems({ items: layout.items, pendingTasks: [] });
+  it("keeps the settled shelf between active and settled rows when nothing is queued", () => {
+    const items = buildThreadListV2ListItems({
+      items: layout.items,
+      pendingTasks: [],
+      settledCount: layout.settledCount,
+      settledShelfHeaderIndex: layout.settledShelfHeaderIndex,
+    });
 
     expect(items.map((item) => item.key)).toEqual([
       `v2-thread:${environmentId}:active`,
+      "v2-settled-shelf",
       `v2-thread:${environmentId}:settled`,
     ]);
   });
+
+  it("places queued tasks before a collapsed snoozed shelf", () => {
+    const snoozedLayout = buildThreadListV2Items({
+      threads: [
+        makeThread({ id: ThreadId.make("active"), title: "active" }),
+        makeThread({
+          id: ThreadId.make("snoozed"),
+          title: "snoozed",
+          snoozedUntil: "2026-06-03T09:00:00.000Z",
+          snoozedAt: "2026-06-01T12:00:00.000Z",
+        }),
+        makeThread({
+          id: ThreadId.make("settled"),
+          title: "settled",
+          settledOverride: "settled",
+          settledAt: NOW,
+        }),
+      ],
+      environmentId: null,
+      searchQuery: "",
+      now: NOW,
+    });
+    const items = buildThreadListV2ListItems({
+      items: snoozedLayout.items,
+      pendingTasks: [makePendingTask("queued")],
+      snoozedCount: snoozedLayout.snoozedCount,
+      snoozedShelfExpanded: false,
+      snoozedShelfHeaderIndex: snoozedLayout.snoozedShelfHeaderIndex,
+      settledCount: snoozedLayout.settledCount,
+      settledShelfHeaderIndex: snoozedLayout.settledShelfHeaderIndex,
+    });
+
+    expect(items.map((item) => item.type)).toEqual([
+      "v2-thread",
+      "v2-pending",
+      "v2-snoozed-shelf",
+      "v2-settled-shelf",
+      "v2-thread",
+    ]);
+  });
 });
diff --git a/apps/mobile/src/features/threads/threadListV2.ts b/apps/mobile/src/features/threads/threadListV2.ts
index 920b7f0b53a..c88aff4ec02 100644
--- a/apps/mobile/src/features/threads/threadListV2.ts
+++ b/apps/mobile/src/features/threads/threadListV2.ts
@@ -1,10 +1,20 @@
-import { effectiveSettled, effectiveSnoozed } from "@t3tools/client-runtime/state/thread-settled";
+import {
+  effectiveSettled,
+  effectiveSnoozed,
+  hasQueuedTurnStart,
+  QUEUED_TURN_START_GRACE_MS,
+  resolveSnoozePresets,
+  snoozeWakeLabel,
+} from "@t3tools/client-runtime/state/thread-settled";
+import type { SnoozePreset } from "@t3tools/client-runtime/state/thread-settled";
 import type { EnvironmentThreadShell } from "@t3tools/client-runtime/state/shell";
 import { threadSearchMatchKey } from "@t3tools/client-runtime/state/thread-search";
 import type { EnvironmentId, ProjectId } from "@t3tools/contracts";
 
 import type { PendingNewTask } from "../../state/use-pending-new-tasks";
 
+export { snoozeWakeLabel };
+
 /**
  * Thread List v2 model, ported from the web sidebar v2
  * (apps/web/src/components/Sidebar.logic.ts + SidebarV2.tsx).
@@ -14,6 +24,76 @@ import type { PendingNewTask } from "../../state/use-pending-new-tasks";
  * unlabeled resting state.
  */
 export type ThreadListV2Status = "approval" | "input" | "working" | "failed" | "ready";
+export type ThreadListV2SwipeAction = "archive" | "settle" | "unsettle" | "snooze" | "unsnooze";
+
+export function resolveThreadListV2SnoozeMenuSelection(input: {
+  readonly event: string;
+  readonly displayedPresets: ReadonlyArray<SnoozePreset>;
+  readonly now: Date;
+}):
+  | { readonly _tag: "selected"; readonly preset: SnoozePreset }
+  | { readonly _tag: "expired" }
+  | { readonly _tag: "not-snooze" } {
+  if (!input.event.startsWith("snooze:")) return { _tag: "not-snooze" };
+
+  const currentPreset = resolveSnoozePresets(input.now).find(
+    (candidate) => input.event === `snooze:${candidate.id}`,
+  );
+  if (currentPreset) return { _tag: "selected", preset: currentPreset };
+
+  const displayedPreset = input.displayedPresets.find(
+    (candidate) => input.event === `snooze:${candidate.id}`,
+  );
+  if (displayedPreset && Date.parse(displayedPreset.snoozedUntil) > input.now.getTime()) {
+    return { _tag: "selected", preset: displayedPreset };
+  }
+  return { _tag: "expired" };
+}
+
+export function resolveThreadListV2SwipeActions(input: {
+  readonly variant: "card" | "slim";
+  readonly settlementSupported: boolean;
+  readonly snoozeSupported: boolean;
+  readonly snoozable: boolean;
+  /** Row is on the snoozed shelf. */
+  readonly snoozed?: boolean;
+}): {
+  readonly primary: Exclude<ThreadListV2SwipeAction, "snooze">;
+  readonly secondary: "snooze" | null;
+} {
+  if (input.snoozed === true) {
+    return { primary: "unsnooze", secondary: null };
+  }
+  const primary = input.settlementSupported
+    ? input.variant === "slim"
+      ? "unsettle"
+      : "settle"
+    : "archive";
+  return {
+    primary,
+    secondary: input.snoozeSupported && input.snoozable ? "snooze" : null,
+  };
+}
+
+/**
+ * The point at which a queued-turn snooze guard expires on its own. Rows arm
+ * a one-shot timer for this boundary so Snooze appears without waiting for an
+ * unrelated render. User-blocked threads return null because only fresh
+ * server data can make them snoozable.
+ */
+export function resolveThreadListV2SnoozeGateExpiryMs(
+  thread: Pick<
+    EnvironmentThreadShell,
+    "hasPendingApprovals" | "hasPendingUserInput" | "latestUserMessageAt" | "latestTurn" | "session"
+  >,
+  options: { readonly now: string },
+): number | null {
+  if (thread.hasPendingApprovals || thread.hasPendingUserInput) return null;
+  if (!hasQueuedTurnStart(thread, options)) return null;
+  const messageAtMs = Date.parse(thread.latestUserMessageAt ?? "");
+  if (Number.isNaN(messageAtMs)) return null;
+  return messageAtMs + QUEUED_TURN_START_GRACE_MS;
+}
 
 // Settled-tail paging: recent history is the common lookup; the deep tail
 // stays behind an explicit Show more. Shared by the compact Home list and
@@ -98,8 +178,8 @@ export function sortThreadsForListV2<T extends { readonly id: string; readonly c
 export interface ThreadListV2Item {
   readonly thread: EnvironmentThreadShell;
   readonly variant: "card" | "slim";
-  /** First settled row after the card block draws the SETTLED divider. */
-  readonly showSettledDivider: boolean;
+  /** Snoozed-shelf row: shows the wake countdown and offers Wake. */
+  readonly snoozed: boolean;
   readonly isLast: boolean;
 }
 
@@ -107,10 +187,16 @@ export interface ThreadListV2Layout {
   readonly items: ThreadListV2Item[];
   /** Settled threads beyond the render limit (behind "Show more"). */
   readonly hiddenSettledCount: number;
-  /** Snoozed threads hidden from the list (visibility parity with web's
-      collapsed Snoozed shelf; mobile has no shelf UI yet). */
+  /** Snoozed threads matching the current filters. */
   readonly snoozedCount: number;
-  /** Soonest wake time among hidden snoozed threads, or null. Callers arm
+  /** Index in `items` where the Snoozed shelf header belongs. The header is
+      still rendered when the shelf is collapsed and no snoozed rows exist. */
+  readonly snoozedShelfHeaderIndex: number | null;
+  /** Total settled threads in scope, including rows hidden by collapse/paging. */
+  readonly settledCount: number;
+  /** Index in `items` where the Settled shelf header belongs. */
+  readonly settledShelfHeaderIndex: number | null;
+  /** Soonest wake time among snoozed threads, or null. Callers arm
       a timeout at this boundary so the list re-partitions the moment a
       snooze expires instead of on the next minute tick. */
   readonly nextSnoozeWakeAt: string | null;
@@ -120,6 +206,8 @@ export interface ThreadListV2ThreadListItem {
   readonly type: "v2-thread";
   readonly key: string;
   readonly item: ThreadListV2Item;
+  /** Precomputed so recycled-list equality can see a minute-tick change. */
+  readonly snoozeWakeLabelText: string | undefined;
 }
 
 export interface ThreadListV2PendingListItem {
@@ -130,28 +218,53 @@ export interface ThreadListV2PendingListItem {
   readonly showPendingDivider: boolean;
 }
 
-export type ThreadListV2ListItem = ThreadListV2ThreadListItem | ThreadListV2PendingListItem;
+export interface ThreadListV2SnoozedShelfListItem {
+  readonly type: "v2-snoozed-shelf";
+  readonly key: "v2-snoozed-shelf";
+  readonly count: number;
+  readonly expanded: boolean;
+}
+
+export interface ThreadListV2SettledShelfListItem {
+  readonly type: "v2-settled-shelf";
+  readonly key: "v2-settled-shelf";
+  readonly count: number;
+  readonly expanded: boolean;
+}
+
+export type ThreadListV2ListItem =
+  | ThreadListV2ThreadListItem
+  | ThreadListV2PendingListItem
+  | ThreadListV2SnoozedShelfListItem
+  | ThreadListV2SettledShelfListItem;
 
 /**
- * Splices queued tasks between the active block and the settled tail, so the
- * list reads active → pending → settled. Queued work sits below the live
- * threads because nothing can happen to it until its environment returns:
- * it is waiting, not asking. Shared by the compact Home list and the iPad
- * sidebar so both order and label the sections identically.
+ * Builds the shared mobile order: active → pending → snoozed shelf → settled.
+ * Pending tasks are waiting rather than asking, and parked work remains
+ * reachable without competing with either the inbox or settled history.
  */
 export function buildThreadListV2ListItems(input: {
   readonly items: ReadonlyArray<ThreadListV2Item>;
   readonly pendingTasks: ReadonlyArray<PendingNewTask>;
+  readonly snoozedCount?: number;
+  readonly snoozedShelfExpanded?: boolean;
+  readonly snoozedShelfHeaderIndex?: number | null;
+  readonly settledCount?: number;
+  readonly settledShelfExpanded?: boolean;
+  readonly settledShelfHeaderIndex?: number | null;
+  readonly snoozeLabelNow?: string;
 }): ThreadListV2ListItem[] {
   const threadItems = input.items.map(
     (item): ThreadListV2ListItem => ({
       type: "v2-thread",
       key: `v2-thread:${item.thread.environmentId}:${item.thread.id}`,
       item,
+      snoozeWakeLabelText:
+        item.snoozed && item.thread.snoozedUntil != null && input.snoozeLabelNow !== undefined
+          ? snoozeWakeLabel(item.thread.snoozedUntil, { now: input.snoozeLabelNow })
+          : undefined,
     }),
   );
-  if (input.pendingTasks.length === 0) return threadItems;
-
   const pendingItems = input.pendingTasks.map(
     (pendingTask, index): ThreadListV2ListItem => ({
       type: "v2-pending",
@@ -160,14 +273,32 @@ export function buildThreadListV2ListItems(input: {
       showPendingDivider: index === 0,
     }),
   );
-  // The settled tail begins at the row that draws the SETTLED divider; with
-  // no settled rows the queued block simply ends the list.
-  const settledStart = threadItems.findIndex(
-    (entry) => entry.type === "v2-thread" && entry.item.showSettledDivider,
-  );
-  return settledStart === -1
-    ? [...threadItems, ...pendingItems]
-    : [...threadItems.slice(0, settledStart), ...pendingItems, ...threadItems.slice(settledStart)];
+  const snoozedCount = input.snoozedCount ?? 0;
+  const snoozedShelfHeaderIndex = input.snoozedShelfHeaderIndex ?? null;
+  const settledCount = input.settledCount ?? 0;
+  const settledShelfHeaderIndex = input.settledShelfHeaderIndex ?? null;
+  const activeEnd = snoozedShelfHeaderIndex ?? settledShelfHeaderIndex ?? threadItems.length;
+  const snoozedEnd = settledShelfHeaderIndex ?? threadItems.length;
+  const result: ThreadListV2ListItem[] = [...threadItems.slice(0, activeEnd), ...pendingItems];
+  if (snoozedShelfHeaderIndex !== null && snoozedCount > 0) {
+    result.push({
+      type: "v2-snoozed-shelf",
+      key: "v2-snoozed-shelf",
+      count: snoozedCount,
+      expanded: input.snoozedShelfExpanded === true,
+    });
+    result.push(...threadItems.slice(snoozedShelfHeaderIndex, snoozedEnd));
+  }
+  if (settledShelfHeaderIndex !== null && settledCount > 0) {
+    result.push({
+      type: "v2-settled-shelf",
+      key: "v2-settled-shelf",
+      count: settledCount,
+      expanded: input.settledShelfExpanded !== false,
+    });
+    result.push(...threadItems.slice(settledShelfHeaderIndex));
+  }
+  return result;
 }
 
 /**
@@ -204,6 +335,13 @@ export function buildThreadListV2Items(input: {
       second-precise, so classifying with the floored minute would hold a
       woken thread hidden for up to a minute. Defaults to `now`. */
   readonly snoozeNow?: string;
+  /** Expands the snoozed shelf into rows. Collapsed is the default. */
+  readonly snoozedShelfExpanded?: boolean;
+  /** Expands the settled shelf into rows. Expanded is the default. */
+  readonly settledShelfExpanded?: boolean;
+  /** The selected thread remains visible on an otherwise collapsed shelf so
+      a split-view detail can never lose its navigation row. */
+  readonly selectedThreadKey?: string | null;
 }): ThreadListV2Layout {
   const now = input.now ?? new Date().toISOString();
   const snoozeNow = input.snoozeNow ?? now;
@@ -215,7 +353,7 @@ export function buildThreadListV2Items(input: {
 
   const active: EnvironmentThreadShell[] = [];
   const settled: EnvironmentThreadShell[] = [];
-  let snoozedCount = 0;
+  const snoozed: EnvironmentThreadShell[] = [];
   let nextSnoozeWakeAt: string | null = null;
   for (const thread of input.threads) {
     // Callers pass live (unarchived) shells; settled threads are among them
@@ -244,7 +382,7 @@ export function buildThreadListV2Items(input: {
     // wakes (or raises its hand — effectiveSnoozed refuses blocked/failed
     // work). Snooze outranks settled classification, same as web.
     if (supportsSnooze && effectiveSnoozed(thread, { now: snoozeNow })) {
-      snoozedCount += 1;
+      snoozed.push(thread);
       if (
         thread.snoozedUntil != null &&
         (nextSnoozeWakeAt === null ||
@@ -265,24 +403,60 @@ export function buildThreadListV2Items(input: {
   }
 
   const orderedActive = sortThreadsForListV2(active);
+  const orderedSnoozed = [...snoozed].sort(
+    (left, right) =>
+      parseTimestampMs(left.snoozedUntil ?? "") - parseTimestampMs(right.snoozedUntil ?? ""),
+  );
+  const selectedThreadKey = input.selectedThreadKey ?? null;
+  const visibleSnoozed =
+    input.snoozedShelfExpanded === true
+      ? orderedSnoozed
+      : orderedSnoozed.filter(
+          (thread) => `${thread.environmentId}:${thread.id}` === selectedThreadKey,
+        );
   const orderedSettled = [...settled].sort(
     (left, right) =>
       firstValidTimestampMs(right.latestUserMessageAt, right.updatedAt) -
       firstValidTimestampMs(left.latestUserMessageAt, left.updatedAt),
   );
   const settledLimit = input.settledLimit ?? Number.POSITIVE_INFINITY;
-  const visibleSettled =
+  const pagedSettled =
     orderedSettled.length > settledLimit ? orderedSettled.slice(0, settledLimit) : orderedSettled;
+  const selectedSettled = orderedSettled
+    .slice(pagedSettled.length)
+    .find((thread) => `${thread.environmentId}:${thread.id}` === selectedThreadKey);
+  if (selectedSettled !== undefined) pagedSettled.push(selectedSettled);
+  const visibleSettled =
+    input.settledShelfExpanded !== false
+      ? pagedSettled
+      : pagedSettled.filter(
+          (thread) => `${thread.environmentId}:${thread.id}` === selectedThreadKey,
+        );
 
   const items: ThreadListV2Item[] = [];
   for (const thread of orderedActive) {
-    items.push({ thread, variant: "card", showSettledDivider: false, isLast: false });
+    items.push({
+      thread,
+      variant: "card",
+      snoozed: false,
+      isLast: false,
+    });
+  }
+  const snoozedShelfHeaderIndex = orderedSnoozed.length > 0 ? items.length : null;
+  for (const thread of visibleSnoozed) {
+    items.push({
+      thread,
+      variant: "slim",
+      snoozed: true,
+      isLast: false,
+    });
   }
-  for (const [index, thread] of visibleSettled.entries()) {
+  const settledShelfHeaderIndex = orderedSettled.length > 0 ? items.length : null;
+  for (const thread of visibleSettled) {
     items.push({
       thread,
       variant: "slim",
-      showSettledDivider: index === 0,
+      snoozed: false,
       isLast: false,
     });
   }
@@ -292,8 +466,11 @@ export function buildThreadListV2Items(input: {
   }
   return {
     items,
-    hiddenSettledCount: orderedSettled.length - visibleSettled.length,
-    snoozedCount,
+    hiddenSettledCount: orderedSettled.length - pagedSettled.length,
+    snoozedCount: orderedSnoozed.length,
+    snoozedShelfHeaderIndex,
+    settledCount: orderedSettled.length,
+    settledShelfHeaderIndex,
     nextSnoozeWakeAt,
   };
 }
diff --git a/apps/mobile/src/features/updates/app-updates.test.ts b/apps/mobile/src/features/updates/app-updates.test.ts
new file mode 100644
index 00000000000..474c99668cd
--- /dev/null
+++ b/apps/mobile/src/features/updates/app-updates.test.ts
@@ -0,0 +1,252 @@
+import { describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  createAppUpdateLaunchCheck,
+  registerHiddenUpdateTap,
+  runAppUpdateCheck,
+  type AppUpdateCheckState,
+  type AppUpdateClient,
+} from "./app-updates";
+
+vi.mock("expo-updates", () => ({
+  isEnabled: true,
+  checkForUpdateAsync: vi.fn(),
+  fetchUpdateAsync: vi.fn(),
+  reloadAsync: vi.fn(),
+}));
+
+function makeUpdateClient(overrides: Partial<AppUpdateClient> = {}): AppUpdateClient {
+  return {
+    isEnabled: true,
+    checkForUpdateAsync: vi.fn(async () => ({
+      isAvailable: false,
+      isRollBackToEmbedded: false,
+    })),
+    fetchUpdateAsync: vi.fn(async () => ({
+      isNew: true,
+      isRollBackToEmbedded: false,
+    })),
+    reloadAsync: vi.fn(async () => {}),
+    ...overrides,
+  };
+}
+
+describe("runAppUpdateCheck", () => {
+  it("downloads and restarts when a new update is available", async () => {
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(async () => ({
+        isAvailable: true,
+        isRollBackToEmbedded: false,
+      })),
+    });
+    const states: AppUpdateCheckState[] = [];
+
+    await runAppUpdateCheck({ client, onStateChange: (state) => states.push(state) });
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(client.fetchUpdateAsync).toHaveBeenCalledOnce();
+    expect(client.reloadAsync).toHaveBeenCalledOnce();
+    expect(states).toEqual(["checking", "downloading", "restarting"]);
+  });
+
+  it("restarts into the embedded bundle for a rollback directive", async () => {
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(async () => ({
+        isAvailable: false,
+        isRollBackToEmbedded: true,
+      })),
+      fetchUpdateAsync: vi.fn(async () => ({
+        isNew: false,
+        isRollBackToEmbedded: true,
+      })),
+    });
+
+    await runAppUpdateCheck({ client });
+
+    expect(client.fetchUpdateAsync).toHaveBeenCalledOnce();
+    expect(client.reloadAsync).toHaveBeenCalledOnce();
+  });
+
+  it("stops quietly when the running bundle is current", async () => {
+    const client = makeUpdateClient();
+    const states: AppUpdateCheckState[] = [];
+
+    await runAppUpdateCheck({ client, onStateChange: (state) => states.push(state) });
+
+    expect(client.fetchUpdateAsync).not.toHaveBeenCalled();
+    expect(client.reloadAsync).not.toHaveBeenCalled();
+    expect(states).toEqual(["checking", "current"]);
+  });
+
+  it("reports manual failures without continuing the update", async () => {
+    const reportError = vi.spyOn(console, "error").mockImplementation(() => {});
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(async () => {
+        throw new Error("offline");
+      }),
+    });
+    const failures: string[] = [];
+    const states: AppUpdateCheckState[] = [];
+
+    await runAppUpdateCheck({
+      client,
+      onFailure: (message) => failures.push(message),
+      onStateChange: (state) => states.push(state),
+    });
+
+    expect(client.fetchUpdateAsync).not.toHaveBeenCalled();
+    expect(failures).toEqual(["offline"]);
+    expect(states).toEqual(["checking", "idle"]);
+    reportError.mockRestore();
+  });
+
+  it("coalesces overlapping launch and manual checks", async () => {
+    let resolveCheck!: (result: {
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }) => void;
+    const checkResult = new Promise<{
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }>((resolve) => {
+      resolveCheck = resolve;
+    });
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(() => checkResult),
+    });
+    const checkOnLaunch = createAppUpdateLaunchCheck(client);
+    const manualStates: AppUpdateCheckState[] = [];
+
+    const launchCheck = checkOnLaunch();
+    const manualCheck = runAppUpdateCheck({
+      client,
+      onStateChange: (state) => manualStates.push(state),
+    });
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(manualStates).toEqual(["checking"]);
+
+    resolveCheck({
+      isAvailable: false,
+      isRollBackToEmbedded: false,
+    });
+    await Promise.all([launchCheck, manualCheck]);
+
+    expect(manualStates).toEqual(["checking", "current"]);
+
+    await runAppUpdateCheck({ client });
+    expect(client.checkForUpdateAsync).toHaveBeenCalledTimes(2);
+  });
+
+  it("forwards failures to a manual check coalesced with the launch check", async () => {
+    const reportError = vi.spyOn(console, "error").mockImplementation(() => {});
+    let rejectCheck!: (error: Error) => void;
+    const checkResult = new Promise<{
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }>((_resolve, reject) => {
+      rejectCheck = reject;
+    });
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(() => checkResult),
+    });
+    const checkOnLaunch = createAppUpdateLaunchCheck(client);
+    const failures: string[] = [];
+    const manualStates: AppUpdateCheckState[] = [];
+
+    const launchCheck = checkOnLaunch();
+    const manualCheck = runAppUpdateCheck({
+      client,
+      onFailure: (message) => failures.push(message),
+      onStateChange: (state) => manualStates.push(state),
+    });
+
+    rejectCheck(new Error("offline"));
+    await Promise.all([launchCheck, manualCheck]);
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(failures).toEqual(["offline"]);
+    expect(manualStates).toEqual(["checking", "idle"]);
+    reportError.mockRestore();
+  });
+
+  it("publishes the in-flight check before a state callback can re-enter", async () => {
+    let resolveCheck!: (result: {
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }) => void;
+    const checkResult = new Promise<{
+      readonly isAvailable: boolean;
+      readonly isRollBackToEmbedded: boolean;
+    }>((resolve) => {
+      resolveCheck = resolve;
+    });
+    const client = makeUpdateClient({
+      checkForUpdateAsync: vi.fn(() => checkResult),
+    });
+    const reentrantStates: AppUpdateCheckState[] = [];
+    let reentrantCheck: Promise<void> | undefined;
+    let didReenter = false;
+
+    const initialCheck = runAppUpdateCheck({
+      client,
+      onStateChange: (state) => {
+        if (state !== "checking" || didReenter) return;
+        didReenter = true;
+        reentrantCheck = runAppUpdateCheck({
+          client,
+          onStateChange: (reentrantState) => reentrantStates.push(reentrantState),
+        });
+      },
+    });
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(reentrantCheck).toBeDefined();
+    expect(reentrantStates).toEqual(["checking"]);
+
+    resolveCheck({
+      isAvailable: false,
+      isRollBackToEmbedded: false,
+    });
+    await Promise.all([initialCheck, reentrantCheck]);
+
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+    expect(reentrantStates).toEqual(["checking", "current"]);
+  });
+});
+
+describe("createAppUpdateLaunchCheck", () => {
+  it("checks at most once for each JavaScript launch", async () => {
+    const client = makeUpdateClient();
+    const checkOnLaunch = createAppUpdateLaunchCheck(client);
+
+    const first = checkOnLaunch();
+    const second = checkOnLaunch();
+    await first;
+
+    expect(second).toBeUndefined();
+    expect(client.checkForUpdateAsync).toHaveBeenCalledOnce();
+  });
+
+  it("does nothing when Expo updates are disabled", () => {
+    const client = makeUpdateClient({ isEnabled: false });
+    const checkOnLaunch = createAppUpdateLaunchCheck(client);
+
+    expect(checkOnLaunch()).toBeUndefined();
+    expect(client.checkForUpdateAsync).not.toHaveBeenCalled();
+  });
+});
+
+describe("registerHiddenUpdateTap", () => {
+  it("unlocks the manual check on the fifth tap", () => {
+    let count = 0;
+
+    for (let tap = 1; tap <= 5; tap += 1) {
+      const result = registerHiddenUpdateTap(count);
+      expect(result.shouldCheck).toBe(tap === 5);
+      count = result.nextCount;
+    }
+
+    expect(count).toBe(0);
+  });
+});
diff --git a/apps/mobile/src/features/updates/app-updates.ts b/apps/mobile/src/features/updates/app-updates.ts
new file mode 100644
index 00000000000..ab896b53c07
--- /dev/null
+++ b/apps/mobile/src/features/updates/app-updates.ts
@@ -0,0 +1,228 @@
+import * as Updates from "expo-updates";
+
+import {
+  type AtomCommandResult,
+  isAtomCommandInterrupted,
+  reportAtomCommandResult,
+  settlePromise,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+
+export type AppUpdateCheckState = "idle" | "checking" | "downloading" | "restarting" | "current";
+
+export interface AppUpdateClient {
+  readonly isEnabled: boolean;
+  readonly checkForUpdateAsync: () => Promise<{
+    readonly isAvailable: boolean;
+    readonly isRollBackToEmbedded: boolean;
+  }>;
+  readonly fetchUpdateAsync: () => Promise<{
+    readonly isNew: boolean;
+    readonly isRollBackToEmbedded: boolean;
+  }>;
+  readonly reloadAsync: () => Promise<void>;
+}
+
+interface AppUpdateCheckOptions {
+  readonly client?: AppUpdateClient;
+  readonly onFailure?: (message: string) => void;
+  readonly onStateChange?: (state: AppUpdateCheckState) => void;
+}
+
+interface AppUpdateCheckProgress {
+  failure: string | undefined;
+  state: AppUpdateCheckState | undefined;
+}
+
+interface AppUpdateCheckInFlight {
+  readonly failureListeners: Set<NonNullable<AppUpdateCheckOptions["onFailure"]>>;
+  readonly progress: AppUpdateCheckProgress;
+  readonly promise: Promise<void>;
+  readonly stateListeners: Set<NonNullable<AppUpdateCheckOptions["onStateChange"]>>;
+}
+
+interface Deferred {
+  readonly promise: Promise<void>;
+  readonly reject: (cause: unknown) => void;
+  readonly resolve: () => void;
+}
+
+const HIDDEN_UPDATE_TAP_COUNT = 5;
+let appUpdateCheckInFlight: AppUpdateCheckInFlight | undefined;
+
+/**
+ * Keeps the manual update affordance discoverable only to someone deliberately
+ * tapping the version row five times.
+ */
+export function registerHiddenUpdateTap(count: number): {
+  readonly nextCount: number;
+  readonly shouldCheck: boolean;
+} {
+  const nextCount = count + 1;
+  if (nextCount >= HIDDEN_UPDATE_TAP_COUNT) {
+    return {
+      nextCount: 0,
+      shouldCheck: true,
+    };
+  }
+  return {
+    nextCount,
+    shouldCheck: false,
+  };
+}
+
+export async function runAppUpdateCheck(options: AppUpdateCheckOptions = {}): Promise<void> {
+  const client = options.client ?? Updates;
+  if (!client.isEnabled) return;
+
+  if (appUpdateCheckInFlight) {
+    await observeAppUpdateCheck(appUpdateCheckInFlight, options);
+    return;
+  }
+
+  const progress: AppUpdateCheckProgress = {
+    failure: undefined,
+    state: undefined,
+  };
+  const failureListeners = new Set<NonNullable<AppUpdateCheckOptions["onFailure"]>>();
+  const stateListeners = new Set<NonNullable<AppUpdateCheckOptions["onStateChange"]>>();
+  if (options.onFailure) failureListeners.add(options.onFailure);
+  if (options.onStateChange) stateListeners.add(options.onStateChange);
+
+  const deferred = createDeferred();
+  const inFlight: AppUpdateCheckInFlight = {
+    failureListeners,
+    progress,
+    promise: deferred.promise,
+    stateListeners,
+  };
+  // Publish the operation before any state listener can synchronously re-enter.
+  appUpdateCheckInFlight = inFlight;
+
+  const execution = performAppUpdateCheck(client, {
+    onFailure: (message) => {
+      progress.failure = message;
+      notifyListeners(failureListeners, message);
+    },
+    onStateChange: (state) => {
+      progress.state = state;
+      notifyListeners(stateListeners, state);
+    },
+  });
+  void execution.then(deferred.resolve, deferred.reject);
+
+  try {
+    await deferred.promise;
+  } finally {
+    if (appUpdateCheckInFlight === inFlight) {
+      appUpdateCheckInFlight = undefined;
+    }
+  }
+}
+
+function createDeferred(): Deferred {
+  let reject!: Deferred["reject"];
+  let resolve!: Deferred["resolve"];
+  const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+    resolve = () => resolvePromise();
+    reject = rejectPromise;
+  });
+  return { promise, reject, resolve };
+}
+
+function notifyListeners<A>(listeners: ReadonlySet<(value: A) => void>, value: A): void {
+  // A listener can synchronously subscribe another caller. Snapshot so that
+  // caller receives only observeAppUpdateCheck's explicit current-value replay.
+  const snapshot = Array.from(listeners);
+  for (const listener of snapshot) listener(value);
+}
+
+async function observeAppUpdateCheck(
+  inFlight: AppUpdateCheckInFlight,
+  options: AppUpdateCheckOptions,
+): Promise<void> {
+  const onFailure = options.onFailure;
+  const onStateChange = options.onStateChange;
+
+  if (onFailure) {
+    inFlight.failureListeners.add(onFailure);
+    if (inFlight.progress.failure) onFailure(inFlight.progress.failure);
+  }
+  if (onStateChange) {
+    inFlight.stateListeners.add(onStateChange);
+    if (inFlight.progress.state) onStateChange(inFlight.progress.state);
+  }
+
+  try {
+    await inFlight.promise;
+  } finally {
+    if (onFailure) inFlight.failureListeners.delete(onFailure);
+    if (onStateChange) inFlight.stateListeners.delete(onStateChange);
+  }
+}
+
+async function performAppUpdateCheck(
+  client: AppUpdateClient,
+  options: AppUpdateCheckOptions,
+): Promise<void> {
+  const setState = options.onStateChange ?? (() => {});
+
+  setState("checking");
+  const check = await settlePromise(() => client.checkForUpdateAsync());
+  if (check._tag === "Failure") {
+    reportUpdateFailure(check, "Could not check for updates.", options.onFailure);
+    setState("idle");
+    return;
+  }
+  // A rollback directive (`eas update:rollback`) arrives as isAvailable: false
+  // with isRollBackToEmbedded: true. The running OTA still has to be dropped.
+  if (!check.value.isAvailable && !check.value.isRollBackToEmbedded) {
+    setState("current");
+    return;
+  }
+
+  setState("downloading");
+  const fetched = await settlePromise(() => client.fetchUpdateAsync());
+  if (fetched._tag === "Failure") {
+    reportUpdateFailure(fetched, "Could not download the update.", options.onFailure);
+    setState("idle");
+    return;
+  }
+  // isNew is always false for a rollback, so it cannot be the sole gate.
+  if (!fetched.value.isNew && !fetched.value.isRollBackToEmbedded) {
+    setState("current");
+    return;
+  }
+
+  setState("restarting");
+  const reloaded = await settlePromise(() => client.reloadAsync());
+  if (reloaded._tag === "Failure") {
+    reportUpdateFailure(reloaded, "Downloaded, but could not restart the app.", options.onFailure);
+    setState("idle");
+  }
+}
+
+function reportUpdateFailure(
+  result: AtomCommandResult<unknown, unknown>,
+  fallback: string,
+  onFailure: AppUpdateCheckOptions["onFailure"],
+): void {
+  reportAtomCommandResult(result, { label: "app update check" });
+  if (result._tag !== "Failure" || isAtomCommandInterrupted(result)) return;
+  const error = squashAtomCommandFailure(result);
+  onFailure?.(error instanceof Error ? error.message : fallback);
+}
+
+export function createAppUpdateLaunchCheck(
+  client: AppUpdateClient = Updates,
+): () => Promise<void> | undefined {
+  let started = false;
+
+  return () => {
+    if (started || !client.isEnabled) return undefined;
+    started = true;
+    return runAppUpdateCheck({ client });
+  };
+}
+
+export const checkForAppUpdateOnLaunch = createAppUpdateLaunchCheck();
diff --git a/apps/mobile/src/lib/composerImages.ts b/apps/mobile/src/lib/composerImages.ts
index 5c79b5b5eb8..f559545c04e 100644
--- a/apps/mobile/src/lib/composerImages.ts
+++ b/apps/mobile/src/lib/composerImages.ts
@@ -65,14 +65,6 @@ export async function pickComposerImages(input: { readonly existingCount: number
     };
   }
 
-  const permission = await imagePicker.requestMediaLibraryPermissionsAsync();
-  if (!permission.granted) {
-    return {
-      images: [],
-      error: "Allow photo library access to attach images.",
-    };
-  }
-
   const result = await imagePicker.launchImageLibraryAsync({
     mediaTypes: ["images"],
     allowsMultipleSelection: true,
diff --git a/apps/mobile/src/lib/layoutMetrics.ts b/apps/mobile/src/lib/layoutMetrics.ts
new file mode 100644
index 00000000000..139fcbb65f3
--- /dev/null
+++ b/apps/mobile/src/lib/layoutMetrics.ts
@@ -0,0 +1,5 @@
+/** Horizontal inset shared by the home header and compact thread list. */
+export const HOME_HORIZONTAL_INSET = 20;
+
+/** Compensates for the tighter native sidebar title margin on iPad. */
+export const IPAD_HOME_TITLE_OFFSET = 10;
diff --git a/apps/mobile/src/lib/mobileBranding.test.ts b/apps/mobile/src/lib/mobileBranding.test.ts
new file mode 100644
index 00000000000..48a84b3f985
--- /dev/null
+++ b/apps/mobile/src/lib/mobileBranding.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { resolveMobileStageLabel } from "./mobileBranding";
+
+describe("resolveMobileStageLabel", () => {
+  it.each([
+    ["development", "Dev"],
+    ["preview", "Nightly"],
+    ["production", "Alpha"],
+    [undefined, "Alpha"],
+  ])("maps %s builds to %s", (appVariant, expected) => {
+    expect(resolveMobileStageLabel(appVariant)).toBe(expected);
+  });
+});
diff --git a/apps/mobile/src/lib/mobileBranding.ts b/apps/mobile/src/lib/mobileBranding.ts
new file mode 100644
index 00000000000..9fd6020831a
--- /dev/null
+++ b/apps/mobile/src/lib/mobileBranding.ts
@@ -0,0 +1,7 @@
+export type MobileStageLabel = "Alpha" | "Dev" | "Nightly";
+
+export function resolveMobileStageLabel(appVariant: unknown): MobileStageLabel {
+  if (appVariant === "development") return "Dev";
+  if (appVariant === "preview") return "Nightly";
+  return "Alpha";
+}
diff --git a/apps/mobile/src/lib/modelOptions.test.ts b/apps/mobile/src/lib/modelOptions.test.ts
index 9a71640b45a..2ec8566b4e4 100644
--- a/apps/mobile/src/lib/modelOptions.test.ts
+++ b/apps/mobile/src/lib/modelOptions.test.ts
@@ -2,9 +2,92 @@ import { describe, expect, it } from "vite-plus/test";
 
 import { ProviderInstanceId, type ServerConfig } from "@t3tools/contracts";
 
-import { buildModelOptions } from "./modelOptions";
+import {
+  buildModelMenuActions,
+  buildModelOptions,
+  groupByProvider,
+  resolveSelectableModelSelection,
+} from "./modelOptions";
 
 describe("mobile model options", () => {
+  it("folds legacy models into a provider-scoped menu", () => {
+    const config = {
+      providers: [
+        {
+          instanceId: "codex",
+          driver: "codex",
+          displayName: "Codex",
+          enabled: true,
+          installed: true,
+          auth: { status: "authenticated" },
+          models: [
+            {
+              slug: "gpt-5.6-sol",
+              name: "GPT-5.6 Sol",
+              isCustom: false,
+              capabilities: null,
+            },
+            {
+              slug: "gpt-5.4",
+              name: "GPT-5.4",
+              isCustom: false,
+              isLegacy: true,
+              capabilities: null,
+            },
+          ],
+        },
+      ],
+    } as unknown as ServerConfig;
+
+    const actions = buildModelMenuActions(groupByProvider(buildModelOptions(config, null)), null);
+
+    expect(actions).toMatchObject([
+      {
+        title: "Codex",
+        subactions: [{ id: "model:codex:gpt-5.6-sol", title: "GPT-5.6 Sol" }],
+      },
+      {
+        id: "legacy-models:codex",
+        title: "Codex legacy models",
+        subactions: [{ id: "model:codex:gpt-5.4", title: "GPT-5.4" }],
+      },
+    ]);
+  });
+
+  it("omits an empty provider menu when every model is legacy", () => {
+    const config = {
+      providers: [
+        {
+          instanceId: "codex",
+          driver: "codex",
+          displayName: "Codex",
+          enabled: true,
+          installed: true,
+          auth: { status: "authenticated" },
+          models: [
+            {
+              slug: "gpt-5.4",
+              name: "GPT-5.4",
+              isCustom: false,
+              isLegacy: true,
+              capabilities: null,
+            },
+          ],
+        },
+      ],
+    } as unknown as ServerConfig;
+
+    expect(
+      buildModelMenuActions(groupByProvider(buildModelOptions(config, null)), null),
+    ).toMatchObject([
+      {
+        id: "legacy-models:codex",
+        title: "Codex legacy models",
+        subactions: [{ id: "model:codex:gpt-5.4" }],
+      },
+    ]);
+  });
+
   it("normalizes a legacy fallback selection against current capabilities", () => {
     const config = {
       providers: [
@@ -49,4 +132,46 @@ describe("mobile model options", () => {
     expect(option?.capabilities?.optionDescriptors?.[0]?.id).toBe("serviceTier");
     expect(option?.selection.options).toEqual([{ id: "serviceTier", value: "default" }]);
   });
+
+  it("rejects stored selections whose provider is not usable", () => {
+    const config = {
+      providers: [
+        {
+          instanceId: "codex",
+          driver: "codex",
+          enabled: true,
+          installed: true,
+          auth: { status: "authenticated" },
+          models: [],
+        },
+        {
+          instanceId: "claudeAgent",
+          driver: "claudeAgent",
+          enabled: false,
+          installed: true,
+          auth: { status: "authenticated" },
+          models: [],
+        },
+      ],
+    } as unknown as ServerConfig;
+
+    const usable = {
+      instanceId: ProviderInstanceId.make("codex"),
+      model: "gpt-5.6-sol",
+    };
+    const disabled = {
+      instanceId: ProviderInstanceId.make("claudeAgent"),
+      model: "claude-sonnet-5",
+    };
+    const removed = {
+      instanceId: ProviderInstanceId.make("codex_personal"),
+      model: "gpt-5.6-sol",
+    };
+
+    expect(resolveSelectableModelSelection(config, usable)).toBe(usable);
+    expect(resolveSelectableModelSelection(config, disabled)).toBeNull();
+    expect(resolveSelectableModelSelection(config, removed)).toBeNull();
+    // No config (environment offline) — nothing to validate against.
+    expect(resolveSelectableModelSelection(null, disabled)).toBe(disabled);
+  });
 });
diff --git a/apps/mobile/src/lib/modelOptions.ts b/apps/mobile/src/lib/modelOptions.ts
index ab859c73b46..951b74f7d51 100644
--- a/apps/mobile/src/lib/modelOptions.ts
+++ b/apps/mobile/src/lib/modelOptions.ts
@@ -3,6 +3,7 @@ import type {
   ModelSelection,
   ServerConfig as T3ServerConfig,
 } from "@t3tools/contracts";
+import type { MenuAction } from "@react-native-menu/menu";
 import {
   buildProviderOptionSelectionsFromDescriptors,
   getProviderOptionDescriptors,
@@ -16,6 +17,7 @@ export type ModelOption = {
   readonly providerLabel: string;
   readonly providerDriver: string;
   readonly isDefault: boolean;
+  readonly isLegacy: boolean;
   readonly capabilities: ModelCapabilities | null;
   readonly selection: ModelSelection;
 };
@@ -58,6 +60,31 @@ function normalizeSelectionOptions(
       };
 }
 
+/**
+ * A stored model selection is only usable when its provider instance is
+ * currently enabled, installed, and authenticated on the server. Returns the
+ * selection unchanged when usable, otherwise `null` so callers fall through to
+ * the server's default model. A missing config (environment offline) cannot be
+ * validated, so stored selections pass through untouched.
+ */
+export function resolveSelectableModelSelection(
+  config: T3ServerConfig | null | undefined,
+  selection: ModelSelection | null,
+): ModelSelection | null {
+  if (!selection || !config) {
+    return selection;
+  }
+  const provider = config.providers.find(
+    (candidate) => candidate.instanceId === selection.instanceId,
+  );
+  return provider &&
+    provider.enabled &&
+    provider.installed &&
+    provider.auth.status !== "unauthenticated"
+    ? selection
+    : null;
+}
+
 export function buildModelOptions(
   config: T3ServerConfig | null | undefined,
   fallbackModelSelection: ModelSelection | null,
@@ -80,6 +107,7 @@ export function buildModelOptions(
         providerLabel,
         providerDriver: provider.driver,
         isDefault: model.isDefault === true,
+        isLegacy: model.isLegacy === true,
         capabilities: model.capabilities,
         selection: normalizeSelectionOptions(
           {
@@ -110,6 +138,7 @@ export function buildModelOptions(
         providerLabel,
         providerDriver: fallbackModelSelection.instanceId,
         isDefault: false,
+        isLegacy: false,
         capabilities: null,
         selection: fallbackModelSelection,
       });
@@ -139,3 +168,53 @@ export function groupByProvider(options: ReadonlyArray<ModelOption>): ReadonlyAr
     models: group.models,
   }));
 }
+
+function modelMenuAction(option: ModelOption, selectedModel: ModelSelection | null): MenuAction {
+  return {
+    id: `model:${option.key}`,
+    title: option.label,
+    state:
+      option.selection.instanceId === selectedModel?.instanceId &&
+      option.selection.model === selectedModel.model
+        ? "on"
+        : undefined,
+  };
+}
+
+export function buildModelMenuActions(
+  groups: ReadonlyArray<ProviderGroup>,
+  selectedModel: ModelSelection | null,
+): MenuAction[] {
+  return groups.flatMap((group) => {
+    const currentModels = group.models.filter((model) => !model.isLegacy);
+    const legacyModels = group.models.filter((model) => model.isLegacy);
+    const selected = group.models.find(
+      (model) =>
+        model.selection.instanceId === selectedModel?.instanceId &&
+        model.selection.model === selectedModel.model,
+    );
+
+    return [
+      ...(currentModels.length > 0
+        ? [
+            {
+              id: `provider:${group.providerKey}`,
+              title: group.providerLabel,
+              subtitle: selected && !selected.isLegacy ? selected.label : undefined,
+              subactions: currentModels.map((option) => modelMenuAction(option, selectedModel)),
+            },
+          ]
+        : []),
+      ...(legacyModels.length > 0
+        ? [
+            {
+              id: `legacy-models:${group.providerKey}`,
+              title: `${group.providerLabel} legacy models`,
+              subtitle: selected?.isLegacy ? selected.label : undefined,
+              subactions: legacyModels.map((option) => modelMenuAction(option, selectedModel)),
+            },
+          ]
+        : []),
+    ];
+  });
+}
diff --git a/apps/mobile/src/native/StackHeader.tsx b/apps/mobile/src/native/StackHeader.tsx
index 78c87119512..a524d515247 100644
--- a/apps/mobile/src/native/StackHeader.tsx
+++ b/apps/mobile/src/native/StackHeader.tsx
@@ -340,7 +340,8 @@ function convertToolbarChild(child: ReactNode): NativeStackHeaderItem | null {
     return {
       type: "spacing",
       spacing: typeof child.props.width === "number" ? child.props.width : 8,
-    };
+      flexible: Boolean(child.props.flexible),
+    } as NativeStackHeaderItem;
   }
 
   return null;
@@ -351,6 +352,11 @@ function collectToolbarItems(children: ReactNode): NativeStackHeaderItem[] {
   Children.forEach(children, (child) => {
     const item = convertToolbarChild(child);
     if (item) {
+      if (item.type === "spacing") {
+        // Native inserts spacing items at `index`, treating a missing index
+        // as 0 — which would move the spacer in front of earlier siblings.
+        (item as { index?: number }).index = items.length;
+      }
       items.push(item);
     }
   });
@@ -364,7 +370,8 @@ function NativeHeaderToolbarRoot(props: {
   const navigation = useNativeStackNavigation();
   const items = useMemo(() => collectToolbarItems(props.children), [props.children]);
 
-  useEffect(() => {
+  // Swap toolbar owners before paint so split and compact headers cannot clear each other.
+  useLayoutEffect(() => {
     if (!navigation) {
       return;
     }
@@ -440,6 +447,7 @@ function NativeHeaderToolbarLabel(_props: { readonly children?: ReactNode }) {
 NativeHeaderToolbarLabel.displayName = "NativeHeaderToolbarLabel";
 
 function NativeHeaderToolbarSpacer(_props: {
+  readonly flexible?: boolean;
   readonly sharesBackground?: boolean;
   readonly width?: number;
 }) {
diff --git a/apps/mobile/src/native/T3ComposerEditor.native.tsx b/apps/mobile/src/native/T3ComposerEditor.native.tsx
index 84d1c22084f..e78f90a7db9 100644
--- a/apps/mobile/src/native/T3ComposerEditor.native.tsx
+++ b/apps/mobile/src/native/T3ComposerEditor.native.tsx
@@ -1,5 +1,6 @@
 import { collectComposerInlineTokens } from "@t3tools/shared/composerInlineTokens";
 import { requireNativeView } from "expo";
+import { TextInputWrapper } from "expo-paste-input";
 import {
   useCallback,
   useEffect,
@@ -9,12 +10,13 @@ import {
   useState,
   type Ref,
 } from "react";
-import type { NativeSyntheticEvent, StyleProp, ViewProps, ViewStyle } from "react-native";
+import type { NativeSyntheticEvent, ViewProps } from "react-native";
 import { Image, StyleSheet } from "react-native";
 
 import { markdownFileIconSource } from "@t3tools/mobile-markdown-text/file-icons";
 import { resolveMarkdownFileIcon } from "@t3tools/mobile-markdown-text/links";
 import { MOBILE_TYPOGRAPHY } from "../lib/typography";
+import { useNativePaste } from "../lib/useNativePaste";
 import { useFontFamily } from "../lib/useFontFamily";
 import { useThemeColor } from "../lib/useThemeColor";
 import {
@@ -117,6 +119,7 @@ export function ComposerEditor({
   const skillBorder = useThemeColor("--color-inline-skill-border");
   const skillText = useThemeColor("--color-inline-skill-foreground");
   const fileTint = useThemeColor("--color-icon-muted");
+  const handlePaste = useNativePaste((uris) => onPasteImages?.(uris));
 
   useImperativeHandle(
     ref,
@@ -221,61 +224,63 @@ export function ComposerEditor({
   const resolvedTextStyle = StyleSheet.flatten(textStyle) ?? {};
   const regularFontFamily = useFontFamily("regular");
   return (
-    <NativeView
-      ref={nativeRef}
-      controlledDocumentJson={controlledDocumentJson}
-      themeJson={themeJson}
-      placeholder={props.placeholder ?? ""}
-      fontFamily={
-        typeof resolvedTextStyle.fontFamily === "string"
-          ? resolvedTextStyle.fontFamily
-          : regularFontFamily
-      }
-      fontSize={
-        typeof resolvedTextStyle.fontSize === "number"
-          ? resolvedTextStyle.fontSize
-          : MOBILE_TYPOGRAPHY.body.fontSize
-      }
-      lineHeight={
-        typeof resolvedTextStyle.lineHeight === "number"
-          ? resolvedTextStyle.lineHeight
-          : MOBILE_TYPOGRAPHY.body.lineHeight
-      }
-      contentInsetVertical={contentInsetVertical}
-      singleLineCentered={props.singleLineCentered ?? false}
-      editable={props.editable ?? true}
-      scrollEnabled={props.scrollEnabled ?? true}
-      autoFocus={props.autoFocus ?? false}
-      autoCorrect={props.autoCorrect ?? true}
-      spellCheck={props.spellCheck ?? true}
-      style={style as StyleProp<ViewStyle>}
-      onComposerChange={(event) => {
-        const acknowledgedEventCount = acceptNativeEvent(
-          event.nativeEvent.eventCount,
-          event.nativeEvent.value,
-          event.nativeEvent.selection,
-        );
-        if (acknowledgedEventCount === false) return;
-        onChangeText(event.nativeEvent.value);
-        onSelectionChange?.(event.nativeEvent.selection);
-        setMostRecentEventCount(acknowledgedEventCount);
-        setNativeEventSequence((sequence) => sequence + 1);
-      }}
-      onComposerSelectionChange={(event) => {
-        const acknowledgedEventCount = acceptNativeEvent(
-          event.nativeEvent.eventCount,
-          event.nativeEvent.value,
-          event.nativeEvent.selection,
-        );
-        if (acknowledgedEventCount === false) return;
-        onSelectionChange?.(event.nativeEvent.selection);
-        setMostRecentEventCount(acknowledgedEventCount);
-        setNativeEventSequence((sequence) => sequence + 1);
-      }}
-      onComposerPasteImages={(event) => onPasteImages?.(event.nativeEvent.uris)}
-      onComposerFocus={onFocus}
-      onComposerBlur={onBlur}
-    />
+    <TextInputWrapper onPaste={handlePaste} style={[{ minHeight: 0 }, style]}>
+      <NativeView
+        ref={nativeRef}
+        controlledDocumentJson={controlledDocumentJson}
+        themeJson={themeJson}
+        placeholder={props.placeholder ?? ""}
+        fontFamily={
+          typeof resolvedTextStyle.fontFamily === "string"
+            ? resolvedTextStyle.fontFamily
+            : regularFontFamily
+        }
+        fontSize={
+          typeof resolvedTextStyle.fontSize === "number"
+            ? resolvedTextStyle.fontSize
+            : MOBILE_TYPOGRAPHY.body.fontSize
+        }
+        lineHeight={
+          typeof resolvedTextStyle.lineHeight === "number"
+            ? resolvedTextStyle.lineHeight
+            : MOBILE_TYPOGRAPHY.body.lineHeight
+        }
+        contentInsetVertical={contentInsetVertical}
+        singleLineCentered={props.singleLineCentered ?? false}
+        editable={props.editable ?? true}
+        scrollEnabled={props.scrollEnabled ?? true}
+        autoFocus={props.autoFocus ?? false}
+        autoCorrect={props.autoCorrect ?? true}
+        spellCheck={props.spellCheck ?? true}
+        style={{ flex: 1, minHeight: 0 }}
+        onComposerChange={(event) => {
+          const acknowledgedEventCount = acceptNativeEvent(
+            event.nativeEvent.eventCount,
+            event.nativeEvent.value,
+            event.nativeEvent.selection,
+          );
+          if (acknowledgedEventCount === false) return;
+          onChangeText(event.nativeEvent.value);
+          onSelectionChange?.(event.nativeEvent.selection);
+          setMostRecentEventCount(acknowledgedEventCount);
+          setNativeEventSequence((sequence) => sequence + 1);
+        }}
+        onComposerSelectionChange={(event) => {
+          const acknowledgedEventCount = acceptNativeEvent(
+            event.nativeEvent.eventCount,
+            event.nativeEvent.value,
+            event.nativeEvent.selection,
+          );
+          if (acknowledgedEventCount === false) return;
+          onSelectionChange?.(event.nativeEvent.selection);
+          setMostRecentEventCount(acknowledgedEventCount);
+          setNativeEventSequence((sequence) => sequence + 1);
+        }}
+        onComposerPasteImages={(event) => onPasteImages?.(event.nativeEvent.uris)}
+        onComposerFocus={onFocus}
+        onComposerBlur={onBlur}
+      />
+    </TextInputWrapper>
   );
 }
 
diff --git a/apps/mobile/src/state/use-composer-drafts.test.ts b/apps/mobile/src/state/use-composer-drafts.test.ts
index fdabe67bc71..fed97e81e08 100644
--- a/apps/mobile/src/state/use-composer-drafts.test.ts
+++ b/apps/mobile/src/state/use-composer-drafts.test.ts
@@ -119,6 +119,36 @@ describe("mobile composer drafts", () => {
     });
   });
 
+  it("drops the workspace selection when clearing a sent new-task draft", () => {
+    const draftKey = "new-task:environment-1:project-1";
+    const draft: ComposerDraft = {
+      text: "send this",
+      attachments: [],
+      modelSelection: {
+        instanceId: ProviderInstanceId.make("codex"),
+        model: "gpt-5.4",
+      },
+      workspaceSelection: {
+        mode: "worktree",
+        branch: "main",
+        worktreePath: null,
+        startFromOrigin: false,
+      },
+    };
+
+    expect(
+      clearComposerDraftContentState({ [draftKey]: draft }, draftKey, {
+        clearWorkspaceSelection: true,
+      }),
+    ).toEqual({
+      [draftKey]: {
+        modelSelection: draft.modelSelection,
+        text: "",
+        attachments: [],
+      },
+    });
+  });
+
   it("reads the latest selector state synchronously for send", () => {
     const draftKey = "environment-1:thread-1";
     const selectedDraft: ComposerDraft = {
diff --git a/apps/mobile/src/state/use-composer-drafts.ts b/apps/mobile/src/state/use-composer-drafts.ts
index cdef999e043..24fa547e272 100644
--- a/apps/mobile/src/state/use-composer-drafts.ts
+++ b/apps/mobile/src/state/use-composer-drafts.ts
@@ -372,14 +372,18 @@ export function updateComposerDraftSettings(
 export function clearComposerDraftContentState(
   current: Record<string, ComposerDraft>,
   draftKey: string,
+  options?: { readonly clearWorkspaceSelection?: boolean },
 ): Record<string, ComposerDraft> {
   const existing = current[draftKey];
   if (!existing) {
     return current;
   }
-  const { importedShareIds: _importedShareIds, ...retained } = existing;
+  const { importedShareIds: _importedShareIds, workspaceSelection, ...retained } = existing;
   const draft = {
     ...retained,
+    ...(options?.clearWorkspaceSelection || workspaceSelection === undefined
+      ? {}
+      : { workspaceSelection }),
     text: "",
     attachments: [],
   };
@@ -526,8 +530,11 @@ export async function restoreComposerDraftSnapshot(
   await persistenceQueue.run(() => writePersistedComposerDrafts(next));
 }
 
-export function clearComposerDraftContent(draftKey: string): void {
-  updateComposerDrafts((current) => clearComposerDraftContentState(current, draftKey));
+export function clearComposerDraftContent(
+  draftKey: string,
+  options?: { readonly clearWorkspaceSelection?: boolean },
+): void {
+  updateComposerDrafts((current) => clearComposerDraftContentState(current, draftKey, options));
 }
 
 export function clearComposerDraft(draftKey: string): void {
diff --git a/apps/server/package.json b/apps/server/package.json
index 48ee9121b51..8e7b5b38591 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -16,7 +16,7 @@
   "type": "module",
   "scripts": {
     "dev": "node --watch src/bin.ts",
-    "build:bundle": "vp pack",
+    "build:bundle": "vp pack && vp pack src/service-launcher.ts --out-dir dist --no-clean",
     "start": "node dist/bin.mjs",
     "typecheck": "tsgo --noEmit",
     "test": "vp test run"
diff --git a/apps/server/scripts/cli.ts b/apps/server/scripts/cli.ts
index 517f633577c..2de5b702a28 100644
--- a/apps/server/scripts/cli.ts
+++ b/apps/server/scripts/cli.ts
@@ -223,7 +223,11 @@ const publishCmd = Command.make(
       const packageJsonPath = path.join(serverDir, "package.json");
 
       // Assert build assets exist
-      for (const relPath of ["dist/bin.mjs", "dist/client/index.html"]) {
+      for (const relPath of [
+        "dist/bin.mjs",
+        "dist/service-launcher.mjs",
+        "dist/client/index.html",
+      ]) {
         const abs = path.join(serverDir, relPath);
         if (!(yield* fs.exists(abs))) {
           return yield* new ServerCliBuildAssetMissingError({ assetPath: abs });
diff --git a/apps/server/src/assets/AssetAccess.test.ts b/apps/server/src/assets/AssetAccess.test.ts
index 42fd3f900e5..568dc3739c0 100644
--- a/apps/server/src/assets/AssetAccess.test.ts
+++ b/apps/server/src/assets/AssetAccess.test.ts
@@ -2,11 +2,13 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { ThreadId } from "@t3tools/contracts";
 import { PROJECT_FAVICON_FALLBACK_MARKER } from "@t3tools/shared/projectFavicon";
 import { describe, expect, it } from "@effect/vitest";
+import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
 import * as PlatformError from "effect/PlatformError";
+import * as TestClock from "effect/testing/TestClock";
 
 import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
 import * as ServerConfig from "../config.ts";
@@ -214,12 +216,21 @@ describe("AssetAccess", () => {
         prefix: "t3-asset-favicon-",
       });
       const faviconPath = path.join(root, "favicon.svg");
-      yield* fileSystem.writeFileString(faviconPath, "<svg />");
+      const initialFavicon = "<svg>a</svg>";
+      const updatedFavicon = "<svg>b</svg>";
+      expect(updatedFavicon).toHaveLength(initialFavicon.length);
+      yield* fileSystem.writeFileString(faviconPath, initialFavicon);
       const canonicalFaviconPath = yield* fileSystem.realPath(faviconPath);
 
       const faviconResult = yield* issueAssetUrl({
         resource: { _tag: "project-favicon", cwd: root },
       });
+      expect(faviconResult.relativeUrl).toMatch(/\/v[0-9a-f]{64}-favicon\.svg$/);
+      expect(
+        yield* issueAssetUrl({
+          resource: { _tag: "project-favicon", cwd: root },
+        }),
+      ).toEqual(faviconResult);
       const faviconSuffix = faviconResult.relativeUrl.slice(`${ASSET_ROUTE_PREFIX}/`.length);
       const faviconSeparatorIndex = faviconSuffix.indexOf("/");
       expect(
@@ -229,6 +240,14 @@ describe("AssetAccess", () => {
         ),
       ).toEqual({ kind: "file", path: canonicalFaviconPath });
 
+      yield* fileSystem.writeFileString(faviconPath, updatedFavicon);
+      const updatedFaviconResult = yield* issueAssetUrl({
+        resource: { _tag: "project-favicon", cwd: root },
+      });
+      expect(
+        updatedFaviconResult.relativeUrl.slice(updatedFaviconResult.relativeUrl.lastIndexOf("/")),
+      ).not.toBe(faviconResult.relativeUrl.slice(faviconResult.relativeUrl.lastIndexOf("/")));
+
       yield* fileSystem.remove(faviconPath);
       const fallbackResult = yield* issueAssetUrl({
         resource: { _tag: "project-favicon", cwd: root },
@@ -245,6 +264,31 @@ describe("AssetAccess", () => {
     }).pipe(Effect.provide(testLayer)),
   );
 
+  it.effect("buckets project favicon expiry after content hashing", () =>
+    Effect.gen(function* () {
+      const crypto = yield* Crypto.Crypto;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fileSystem.makeTempDirectoryScoped({
+        prefix: "t3-asset-favicon-expiry-",
+      });
+      yield* fileSystem.writeFileString(path.join(root, "favicon.svg"), "<svg />");
+
+      const bucketMs = 30 * 60 * 1000;
+      yield* TestClock.setTime(bucketMs - 1);
+      const crossingCrypto = Crypto.make({
+        randomBytes: (size) => new Uint8Array(size),
+        digest: (algorithm, data) =>
+          TestClock.adjust("2 millis").pipe(Effect.andThen(crypto.digest(algorithm, data))),
+      });
+      const result = yield* issueAssetUrl({
+        resource: { _tag: "project-favicon", cwd: root },
+      }).pipe(Effect.provideService(Crypto.Crypto, crossingCrypto));
+
+      expect(result.expiresAt).toBe(3 * bucketMs);
+    }).pipe(Effect.provide(testLayer)),
+  );
+
   it.effect("preserves structured project favicon resolution causes", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
diff --git a/apps/server/src/assets/AssetAccess.ts b/apps/server/src/assets/AssetAccess.ts
index b469e0e315b..c00f7f1a5e3 100644
--- a/apps/server/src/assets/AssetAccess.ts
+++ b/apps/server/src/assets/AssetAccess.ts
@@ -21,7 +21,9 @@ import {
 } from "@t3tools/shared/filePreview";
 import { PROJECT_FAVICON_FALLBACK_MARKER } from "@t3tools/shared/projectFavicon";
 import * as Clock from "effect/Clock";
+import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
 import * as FileSystem from "effect/FileSystem";
 import * as Option from "effect/Option";
 import * as Path from "effect/Path";
@@ -44,6 +46,8 @@ export const ASSET_ROUTE_PREFIX = "/api/assets";
 
 const SIGNING_SECRET_NAME = "asset-access-signing-key";
 const ASSET_TOKEN_TTL_MS = 60 * 60 * 1000;
+const PROJECT_FAVICON_TOKEN_BUCKET_MS = 30 * 60 * 1000;
+const PROJECT_FAVICON_VERSION_PREFIX = "v";
 const PREVIEW_ASSET_EXTENSIONS = new Set([
   ...WORKSPACE_BROWSER_PREVIEW_EXTENSIONS,
   ...WORKSPACE_IMAGE_PREVIEW_EXTENSIONS,
@@ -169,7 +173,7 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
   const fileSystem = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const workspacePaths = yield* WorkspacePaths.WorkspacePaths;
-  const expiresAt = (yield* Clock.currentTimeMillis) + ASSET_TOKEN_TTL_MS;
+  let expiresAt = (yield* Clock.currentTimeMillis) + ASSET_TOKEN_TTL_MS;
   let claims: AssetClaims;
   let fileName: string;
 
@@ -293,18 +297,18 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         ),
       );
       const relativePath = faviconPath ? path.relative(workspaceRoot, faviconPath) : null;
-      if (
-        relativePath &&
-        !(yield* resolveCanonicalWorkspaceFile({ workspaceRoot, relativePath }).pipe(
-          Effect.mapError(
-            (cause) =>
-              new AssetProjectFaviconInspectionError({
-                resource: input.resource,
-                cause,
-              }),
-          ),
-        ))
-      ) {
+      const canonicalFaviconPath = relativePath
+        ? yield* resolveCanonicalWorkspaceFile({ workspaceRoot, relativePath }).pipe(
+            Effect.mapError(
+              (cause) =>
+                new AssetProjectFaviconInspectionError({
+                  resource: input.resource,
+                  cause,
+                }),
+            ),
+          )
+        : null;
+      if (relativePath && !canonicalFaviconPath) {
         return yield* new AssetProjectFaviconNotFoundError({
           resource: input.resource,
         });
@@ -324,7 +328,31 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         relativePath,
         expiresAt,
       };
-      fileName = relativePath ? path.basename(relativePath) : PROJECT_FAVICON_FALLBACK_MARKER;
+      if (relativePath && canonicalFaviconPath) {
+        const crypto = yield* Crypto.Crypto;
+        const faviconBytes = yield* fileSystem.readFile(canonicalFaviconPath).pipe(
+          Effect.mapError(
+            (cause) =>
+              new AssetProjectFaviconInspectionError({
+                resource: input.resource,
+                cause,
+              }),
+          ),
+        );
+        const revision = yield* crypto.digest("SHA-256", faviconBytes).pipe(
+          Effect.map(Encoding.encodeHex),
+          Effect.mapError(
+            (cause) =>
+              new AssetProjectFaviconInspectionError({
+                resource: input.resource,
+                cause,
+              }),
+          ),
+        );
+        fileName = `${PROJECT_FAVICON_VERSION_PREFIX}${revision}-${path.basename(relativePath)}`;
+      } else {
+        fileName = PROJECT_FAVICON_FALLBACK_MARKER;
+      }
       break;
     }
   }
@@ -339,6 +367,13 @@ export const issueAssetUrl = Effect.fn("AssetAccess.issueAssetUrl")(function* (i
         }),
     ),
   );
+  if (claims.kind === "project-favicon") {
+    const issuedAt = yield* Clock.currentTimeMillis;
+    expiresAt =
+      (Math.floor(issuedAt / PROJECT_FAVICON_TOKEN_BUCKET_MS) + 2) *
+      PROJECT_FAVICON_TOKEN_BUCKET_MS;
+    claims = { ...claims, expiresAt };
+  }
   const encodedPayload = base64UrlEncode(encodeAssetClaims(claims));
   const token = `${encodedPayload}.${signPayload(encodedPayload, signingSecret)}`;
   return {
diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts
index 80b1cb4aa1f..fb753b9aa4b 100644
--- a/apps/server/src/auth/RpcAuthorization.ts
+++ b/apps/server/src/auth/RpcAuthorization.ts
@@ -55,6 +55,7 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.sourceControlPublishRepository]: AuthOrchestrationOperateScope,
   [WS_METHODS.projectsListEntries]: AuthOrchestrationReadScope,
   [WS_METHODS.projectsReadFile]: AuthOrchestrationReadScope,
+  [WS_METHODS.projectsSearchContents]: AuthOrchestrationReadScope,
   [WS_METHODS.projectsSearchEntries]: AuthOrchestrationReadScope,
   [WS_METHODS.projectsWriteFile]: AuthOrchestrationOperateScope,
   [WS_METHODS.shellOpenInEditor]: AuthOrchestrationOperateScope,
diff --git a/apps/server/src/bin.ts b/apps/server/src/bin.ts
index 82398748cf2..d1bdcf90997 100644
--- a/apps/server/src/bin.ts
+++ b/apps/server/src/bin.ts
@@ -9,11 +9,13 @@ import * as NetService from "@t3tools/shared/Net";
 import packageJson from "../package.json" with { type: "json" };
 import { authCommand } from "./cli/auth.ts";
 import { connectCommand } from "./cli/connect.ts";
+import { pairCommand } from "./cli/pair.ts";
 import { hasCloudPublicConfig } from "./cloud/publicConfig.ts";
 import { sharedServerCommandFlags } from "./cli/config.ts";
 import { projectCommand } from "./cli/project.ts";
 import { runServerCommand, serveCommand, startCommand } from "./cli/server.ts";
 import { serviceCommand } from "./cli/service.ts";
+import { servicePreflightCommand } from "./cli/servicePreflight.ts";
 
 const CliRuntimeLayer = Layer.mergeAll(NodeServices.layer, NetService.layer);
 
@@ -48,9 +50,11 @@ export const makeCli = ({ cloudEnabled = hasCloudPublicConfig } = {}) =>
     Command.withSubcommands([
       startCommand,
       serveCommand,
+      pairCommand,
       authCommand,
       projectCommand,
       serviceCommand,
+      servicePreflightCommand,
       cloudEnabled ? connectCommand : connectUnavailableCommand,
     ]),
   );
diff --git a/apps/server/src/cli/pair.test.ts b/apps/server/src/cli/pair.test.ts
new file mode 100644
index 00000000000..c4f321a5a61
--- /dev/null
+++ b/apps/server/src/cli/pair.test.ts
@@ -0,0 +1,268 @@
+// @effect-diagnostics nodeBuiltinImport:off - CLI integration exercises Node HTTP and filesystem boundaries.
+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 NodeServices from "@effect/platform-node/NodeServices";
+import * as NetService from "@t3tools/shared/Net";
+import { assert, describe, expect, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as TestConsole from "effect/testing/TestConsole";
+import { Command } from "effect/unstable/cli";
+
+import { cli } from "../bin.ts";
+import {
+  makePersistedServerRuntimeState,
+  persistServerRuntimeState,
+  type PersistedServerRuntimeState,
+} from "../serverRuntimeState.ts";
+import {
+  DevServerNotProxiableError,
+  resolveDirectPairingBaseUrl,
+  resolveTailscaleLocalTarget,
+} from "./pair.ts";
+
+const CliRuntimeLayer = Layer.mergeAll(NodeServices.layer, NetService.layer);
+
+const baseState = {
+  version: 1,
+  pid: 123,
+  port: 3_773,
+  origin: "http://127.0.0.1:3773",
+  startedAt: "2026-06-20T00:00:00.000Z",
+} as const satisfies PersistedServerRuntimeState;
+
+describe("pair base URL selection", () => {
+  it("pairs through the dev web origin when the server fronts a dev server", () => {
+    expect(resolveDirectPairingBaseUrl({ ...baseState, devUrl: "http://localhost:5733/" })).toBe(
+      "http://localhost:5733/",
+    );
+  });
+
+  it("pairs through the bound host when there is no dev server", () => {
+    expect(resolveDirectPairingBaseUrl({ ...baseState, host: "100.64.0.7" })).toBe(
+      "http://100.64.0.7:3773",
+    );
+    expect(resolveDirectPairingBaseUrl(baseState)).toBe("http://localhost:3773");
+  });
+});
+
+describe("pair tailscale local target", () => {
+  it("proxies the dev web port for dev servers", () => {
+    expect(resolveTailscaleLocalTarget({ ...baseState, devUrl: "http://localhost:5733/" })).toEqual(
+      { localPort: 5_733 },
+    );
+    // A dev server on a non-loopback interface must be proxied at that
+    // interface; tailscale serve defaults to 127.0.0.1 otherwise.
+    expect(
+      resolveTailscaleLocalTarget({ ...baseState, devUrl: "http://192.168.1.10:5733/" }),
+    ).toEqual({ localPort: 5_733, localHost: "192.168.1.10" });
+    // URL.hostname keeps IPv6 brackets, so the serve target stays valid.
+    expect(
+      resolveTailscaleLocalTarget({ ...baseState, devUrl: "http://[fd7a:115c::1]:5733/" }),
+    ).toEqual({ localPort: 5_733, localHost: "[fd7a:115c::1]" });
+  });
+
+  it("rejects HTTPS dev URLs, which tailscale serve cannot proxy", () => {
+    expect(
+      resolveTailscaleLocalTarget({ ...baseState, devUrl: "https://localhost:5733/" }),
+    ).toBeInstanceOf(DevServerNotProxiableError);
+  });
+
+  it("proxies the backend port directly otherwise", () => {
+    expect(resolveTailscaleLocalTarget(baseState)).toEqual({ localPort: 3_773 });
+    expect(resolveTailscaleLocalTarget({ ...baseState, host: "0.0.0.0" })).toEqual({
+      localPort: 3_773,
+    });
+    expect(resolveTailscaleLocalTarget({ ...baseState, host: "192.168.1.42" })).toEqual({
+      localPort: 3_773,
+      localHost: "192.168.1.42",
+    });
+  });
+});
+
+const runCli = (args: ReadonlyArray<string>) => Command.runWith(cli, { version: "0.0.0" })(args);
+
+const provideCliTestLayers = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  Effect.provide(effect, Layer.mergeAll(CliRuntimeLayer, TestConsole.layer));
+
+// Console output accumulates across CLI runs within a test, and each
+// Console.log call is one entry — so the latest command's output is the last
+// entry, even when it spans many lines.
+const captureStdout = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  provideCliTestLayers(
+    Effect.gen(function* () {
+      yield* effect;
+      return (
+        (yield* TestConsole.logLines).findLast(
+          (line): line is string => typeof line === "string",
+        ) ?? ""
+      );
+    }),
+  );
+
+const testDescriptor = {
+  environmentId: "pair-test-environment",
+  label: "pair-test",
+  platform: { os: "linux", arch: "x64" },
+  serverVersion: "0.0.1",
+  capabilities: { repositoryIdentity: true },
+};
+
+const withDescriptorServer = <A, E, R>(run: (origin: string) => Effect.Effect<A, E, R>) =>
+  Effect.acquireUseRelease(
+    Effect.callback<NodeHttp.Server>((resume) => {
+      const server = NodeHttp.createServer((request, response) => {
+        if (request.url === "/.well-known/t3/environment") {
+          response.writeHead(200, { "content-type": "application/json" });
+          response.end(JSON.stringify(testDescriptor));
+          return;
+        }
+        response.writeHead(404);
+        response.end();
+      });
+      server.listen(0, "127.0.0.1", () => resume(Effect.succeed(server)));
+    }),
+    (server) => {
+      const address = server.address();
+      if (address === null || typeof address === "string") {
+        return Effect.die(new Error("Expected a TCP address"));
+      }
+      return run(`http://127.0.0.1:${String(address.port)}`);
+    },
+    (server) => Effect.sync(() => server.close()),
+  );
+
+describe("t3 pair", () => {
+  it.effect("mints a token and prints a QR pairing URL for a live server", () =>
+    withDescriptorServer((origin) =>
+      Effect.gen(function* () {
+        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-test-"));
+        const port = Number(new URL(origin).port);
+        const statePath = NodePath.join(baseDir, "userdata", "server-runtime.json");
+        yield* persistServerRuntimeState({
+          path: statePath,
+          state: yield* makePersistedServerRuntimeState({
+            config: { host: "127.0.0.1", devUrl: undefined },
+            port,
+          }),
+        });
+
+        const output = yield* captureStdout(runCli(["pair", "--base-dir", baseDir]));
+
+        assert.include(output, `Pairing with pair-test (${origin})`);
+        assert.include(output, `Pairing URL: ${origin}/pair#token=`);
+        assert.isTrue(output.includes("█") || output.includes("▀") || output.includes("▄"));
+        // Loopback origins are not reachable from a phone; the output must say so.
+        assert.include(output, "only reachable from this machine");
+
+        const token = /#token=([A-Z2-9]+)/.exec(output)?.[1];
+        assert.isString(token);
+
+        // The token must be in the same store the running server reads.
+        const listed = yield* captureStdout(
+          runCli(["auth", "pairing", "list", "--base-dir", baseDir, "--json"]),
+        );
+        // @effect-diagnostics-next-line preferSchemaOverJson:off - CLI JSON output is decoded as a presentation DTO.
+        const credentials = JSON.parse(listed) as ReadonlyArray<{ readonly label?: string }>;
+        assert.equal(credentials.length, 1);
+        assert.equal(credentials[0]?.label, "t3 pair");
+      }),
+    ).pipe(Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("pairs through the recorded dev web URL for dev servers", () =>
+    withDescriptorServer((origin) =>
+      Effect.gen(function* () {
+        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-dev-test-"));
+        const port = Number(new URL(origin).port);
+        const statePath = NodePath.join(baseDir, "dev", "server-runtime.json");
+        yield* persistServerRuntimeState({
+          path: statePath,
+          state: yield* makePersistedServerRuntimeState({
+            config: { host: undefined, devUrl: new URL("http://localhost:5733") },
+            port,
+          }),
+        });
+
+        const output = yield* captureStdout(runCli(["pair", "--base-dir", baseDir]));
+
+        assert.include(output, "Pairing URL: http://localhost:5733/pair#token=");
+      }),
+    ).pipe(Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("directs to t3 serve or t3 connect when no server is running", () =>
+    Effect.gen(function* () {
+      const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-none-test-"));
+
+      const error = yield* provideCliTestLayers(
+        runCli(["pair", "--base-dir", baseDir]).pipe(Effect.flip),
+      );
+
+      const rendered = String(
+        typeof error === "object" && error !== null && "cause" in error ? error.cause : error,
+      );
+      assert.include(rendered, "No running T3 Code server found.");
+      assert.include(rendered, "npx t3 serve");
+      assert.include(rendered, "npx t3 connect");
+    }).pipe(Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("ignores runtime state whose recorded pid is no longer alive", () =>
+    withDescriptorServer((origin) =>
+      Effect.gen(function* () {
+        const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-pid-test-"));
+        const statePath = NodePath.join(baseDir, "userdata", "server-runtime.json");
+        // The origin answers (another server reused the port), but the pid
+        // that wrote this state file is dead — pairing must not mint a token
+        // into the dead server's database.
+        const state = yield* makePersistedServerRuntimeState({
+          config: { host: "127.0.0.1", devUrl: undefined },
+          port: Number(new URL(origin).port),
+        });
+        yield* persistServerRuntimeState({
+          path: statePath,
+          // pid 2**22 + 1 exceeds any default Linux/macOS pid range.
+          state: { ...state, pid: 4_194_305 },
+        });
+
+        const error = yield* provideCliTestLayers(
+          runCli(["pair", "--base-dir", baseDir]).pipe(Effect.flip),
+        );
+
+        const rendered = String(
+          typeof error === "object" && error !== null && "cause" in error ? error.cause : error,
+        );
+        assert.include(rendered, "No running T3 Code server found.");
+      }),
+    ).pipe(Effect.provide(NodeServices.layer)),
+  );
+
+  it.effect("ignores stale runtime state pointing at a dead server", () =>
+    Effect.gen(function* () {
+      const baseDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-pair-stale-test-"));
+      const statePath = NodePath.join(baseDir, "userdata", "server-runtime.json");
+      // A port from the dynamic range with nothing listening: the probe fails
+      // fast with ECONNREFUSED and discovery moves on.
+      yield* persistServerRuntimeState({
+        path: statePath,
+        state: yield* makePersistedServerRuntimeState({
+          config: { host: "127.0.0.1", devUrl: undefined },
+          port: 1,
+        }),
+      });
+
+      const error = yield* provideCliTestLayers(
+        runCli(["pair", "--base-dir", baseDir]).pipe(Effect.flip),
+      );
+
+      const rendered = String(
+        typeof error === "object" && error !== null && "cause" in error ? error.cause : error,
+      );
+      assert.include(rendered, "No running T3 Code server found.");
+    }).pipe(Effect.provide(NodeServices.layer)),
+  );
+});
diff --git a/apps/server/src/cli/pair.ts b/apps/server/src/cli/pair.ts
new file mode 100644
index 00000000000..38fa3be8bb5
--- /dev/null
+++ b/apps/server/src/cli/pair.ts
@@ -0,0 +1,542 @@
+/**
+ * `t3 pair` - mint a pairing token for an already-running server and print it
+ * as a QR code, without restarting anything.
+ *
+ * Discovery reads the `server-runtime.json` a live server persists next to its
+ * database, then confirms the process is actually answering by fetching its
+ * public environment descriptor. Inside a linked git worktree the worktree's
+ * own `.t3` is checked first (matching dev-runner precedence); otherwise the
+ * shared T3 home. `--tailscale` publishes the server over Tailscale Serve
+ * HTTPS and pairs through the tailnet URL instead.
+ */
+import {
+  AuthStandardClientScopes,
+  ExecutionEnvironmentDescriptor,
+  PortSchema,
+} from "@t3tools/contracts";
+import { resolveWorktreeT3Home } from "@t3tools/shared/devHome";
+import {
+  buildTailscaleHttpsBaseUrl,
+  DEFAULT_TAILSCALE_SERVE_PORT,
+  ensureTailscaleServe,
+  readTailscaleStatus,
+} from "@t3tools/tailscale";
+import * as Config from "effect/Config";
+import * as Console from "effect/Console";
+import * as DateTime from "effect/DateTime";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as References from "effect/References";
+import * as Schema from "effect/Schema";
+import { Command, Flag, GlobalFlag } from "effect/unstable/cli";
+import {
+  FetchHttpClient,
+  HttpClient,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/unstable/http";
+
+import * as EnvironmentAuth from "../auth/EnvironmentAuth.ts";
+import * as ServerConfig from "../config.ts";
+import { resolveBaseDir } from "../os-jank.ts";
+import {
+  type PersistedServerRuntimeState,
+  readPersistedServerRuntimeState,
+} from "../serverRuntimeState.ts";
+import {
+  buildPairingUrl,
+  formatHostForUrl,
+  isLoopbackHost,
+  isWildcardHost,
+  renderTerminalQrCode,
+  resolveHeadlessConnectionString,
+} from "../startupAccess.ts";
+import { baseDirFlag, DurationFromString } from "./config.ts";
+
+const WELL_KNOWN_ENVIRONMENT_PATH = "/.well-known/t3/environment";
+const PAIR_PROBE_TIMEOUT = Duration.millis(2_500);
+// Tailscale provisions an HTTPS certificate on the first request to a fresh
+// serve mapping, which can take a few seconds.
+const TAILSCALE_PROBE_ATTEMPTS = 5;
+const TAILSCALE_PROBE_RETRY_DELAY = Duration.seconds(1);
+
+export type PairStateVariant = "userdata" | "dev";
+
+// deriveServerPaths only checks devUrl for undefined-ness when picking the
+// dev-vs-userdata state directory; the value itself is not used.
+const DEV_VARIANT_PLACEHOLDER_URL = new URL("http://localhost");
+
+export class NoRunningServerError extends Schema.TaggedErrorClass<NoRunningServerError>()(
+  "NoRunningServerError",
+  {
+    checkedStatePaths: Schema.Array(Schema.String),
+  },
+) {
+  override get message(): string {
+    return [
+      "No running T3 Code server found.",
+      ...this.checkedStatePaths.map((statePath) => `  checked ${statePath}`),
+      "Start one with `npx t3 serve`, or connect this machine with T3 Connect: `npx t3 connect`.",
+    ].join("\n");
+  }
+}
+
+// Each tailscale failure gets its own class (same reasoning as
+// scripts/lib/dev-share.ts): distinct caller-visible message, distinct remedy.
+export class TailscaleUnavailableError extends Schema.TaggedErrorClass<TailscaleUnavailableError>()(
+  "TailscaleUnavailableError",
+  { cause: Schema.Defect() },
+) {
+  override get message(): string {
+    return "Could not talk to Tailscale. Is tailscaled running? Try `tailscale status`.";
+  }
+}
+
+export class MagicDnsNameMissingError extends Schema.TaggedErrorClass<MagicDnsNameMissingError>()(
+  "MagicDnsNameMissingError",
+  {},
+) {
+  override get message(): string {
+    return "This machine has no MagicDNS name. Run `tailscale up` and enable MagicDNS.";
+  }
+}
+
+export class ServesOtherEnvironmentError extends Schema.TaggedErrorClass<ServesOtherEnvironmentError>()(
+  "ServesOtherEnvironmentError",
+  { servePort: Schema.Number },
+) {
+  override get message(): string {
+    return `Tailscale Serve on HTTPS port ${String(this.servePort)} already fronts a different T3 Code server. Pass --tailscale-serve-port to publish this one on another port.`;
+  }
+}
+
+export class TailscaleServeFailedError extends Schema.TaggedErrorClass<TailscaleServeFailedError>()(
+  "TailscaleServeFailedError",
+  { servePort: Schema.Number, cause: Schema.Defect() },
+) {
+  override get message(): string {
+    return `tailscale serve failed for HTTPS port ${String(this.servePort)}. Run \`tailscale serve --https=${String(this.servePort)} --bg <local-url>\` by hand to see why.`;
+  }
+}
+
+export class ServePortOccupiedError extends Schema.TaggedErrorClass<ServePortOccupiedError>()(
+  "ServePortOccupiedError",
+  { servePort: Schema.Number },
+) {
+  override get message(): string {
+    return `HTTPS port ${String(this.servePort)} on the tailnet already serves something that is not a T3 Code server. Pass --tailscale-serve-port to publish this one on another port.`;
+  }
+}
+
+/** The URL a browser or phone should pair through, absent Tailscale. */
+export const resolveDirectPairingBaseUrl = (state: PersistedServerRuntimeState): string =>
+  state.devUrl ?? resolveHeadlessConnectionString(state.host, state.port);
+
+export class DevServerNotProxiableError extends Schema.TaggedErrorClass<DevServerNotProxiableError>()(
+  "DevServerNotProxiableError",
+  { devUrl: Schema.String },
+) {
+  override get message(): string {
+    return `Tailscale Serve can only proxy plain-HTTP local targets, and this dev server runs at ${this.devUrl}. Pair without --tailscale instead.`;
+  }
+}
+
+const isDevServerNotProxiableError = Schema.is(DevServerNotProxiableError);
+
+/**
+ * The local endpoint Tailscale Serve should proxy to. Dev servers are
+ * single-origin, so the web dev server's port is the one to publish; the
+ * backend rides along behind Vite's proxy. Serve targets are always plain
+ * HTTP, so an HTTPS dev URL cannot be proxied and is rejected.
+ */
+export const resolveTailscaleLocalTarget = (
+  state: PersistedServerRuntimeState,
+): { readonly localPort: number; readonly localHost?: string } | DevServerNotProxiableError => {
+  if (state.devUrl !== undefined) {
+    const devUrl = new URL(state.devUrl);
+    if (devUrl.protocol !== "http:") {
+      return new DevServerNotProxiableError({ devUrl: state.devUrl });
+    }
+    const localPort = devUrl.port.length > 0 ? Number.parseInt(devUrl.port, 10) : 80;
+    return isLoopbackHost(devUrl.hostname)
+      ? { localPort }
+      : { localPort, localHost: devUrl.hostname };
+  }
+  // A server bound to one specific interface does not answer on loopback, so
+  // the proxy has to target that interface directly.
+  if (state.host !== undefined && !isWildcardHost(state.host) && !isLoopbackHost(state.host)) {
+    return { localPort: state.port, localHost: formatHostForUrl(state.host) };
+  }
+  return { localPort: state.port };
+};
+
+export const formatPairOutput = (input: {
+  readonly serverLabel: string;
+  readonly origin: string;
+  readonly pairingUrl: string;
+  readonly token: string;
+  readonly expiresAt: DateTime.Utc;
+  readonly notes: ReadonlyArray<string>;
+}): string =>
+  [
+    `Pairing with ${input.serverLabel} (${input.origin}).`,
+    "",
+    renderTerminalQrCode(input.pairingUrl),
+    "",
+    `Pairing URL: ${input.pairingUrl}`,
+    `Token: ${input.token}`,
+    `Expires: ${DateTime.formatIso(input.expiresAt)}`,
+    ...input.notes.flatMap((note) => ["", `Note: ${note}`]),
+    "",
+  ].join("\n");
+
+/**
+ * Three outcomes, because they drive different decisions: a T3 descriptor
+ * (pair with it), nothing answering (safe to configure Tailscale Serve), or
+ * something answering that is not a T3 server (do NOT overwrite its mapping).
+ */
+type EnvironmentProbeResult =
+  | { readonly _tag: "descriptor"; readonly descriptor: ExecutionEnvironmentDescriptor }
+  | { readonly _tag: "unreachable" }
+  | { readonly _tag: "not-a-t3-server" };
+
+const probeEnvironmentDescriptor = (
+  baseUrl: string,
+): Effect.Effect<EnvironmentProbeResult, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const request = HttpClientRequest.get(new URL(WELL_KNOWN_ENVIRONMENT_PATH, baseUrl).toString());
+    const response = yield* client.execute(request).pipe(
+      Effect.timeout(PAIR_PROBE_TIMEOUT),
+      // Transport failure or timeout: nothing (reachable) is listening there.
+      Effect.mapError(() => ({ _tag: "unreachable" }) as const),
+    );
+    // Bad-gateway family means a proxy (Tailscale Serve) answered for a
+    // backend that is gone — a stale mapping, not a live occupant. Treating
+    // it as unreachable lets `t3 pair --tailscale` repair its own mapping
+    // after the server's port changed.
+    if (response.status === 502 || response.status === 503 || response.status === 504) {
+      return { _tag: "unreachable" } as const;
+    }
+    // Anything else that answered HTTP but not with a valid descriptor is
+    // some other service.
+    const descriptor = yield* HttpClientResponse.filterStatusOk(response).pipe(
+      Effect.flatMap(HttpClientResponse.schemaBodyJson(ExecutionEnvironmentDescriptor)),
+      Effect.mapError(() => ({ _tag: "not-a-t3-server" }) as const),
+    );
+    return { _tag: "descriptor", descriptor } as const;
+  }).pipe(Effect.catch((outcome) => Effect.succeed(outcome)));
+
+// signal 0 delivers nothing; it only reports whether the pid exists. EPERM
+// means it exists but belongs to another user, which still counts as alive.
+const isProcessAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "EPERM";
+  }
+};
+
+interface DiscoveredPairTarget {
+  readonly baseDir: string;
+  readonly variant: PairStateVariant;
+  readonly state: PersistedServerRuntimeState;
+  readonly descriptor: ExecutionEnvironmentDescriptor;
+}
+
+const discoverPairTarget = Effect.fn("pair.discoverPairTarget")(function* (
+  explicitBaseDir: string | undefined,
+) {
+  const bases: Array<string> = [];
+  if (explicitBaseDir !== undefined && explicitBaseDir.trim().length > 0) {
+    bases.push(yield* resolveBaseDir(explicitBaseDir));
+  } else {
+    // Same precedence as dev-runner: inside a linked worktree its own `.t3`
+    // outranks the shared home, so `t3 pair` in a worktree pairs with the dev
+    // server under test rather than the daily-driver install.
+    const worktreeHome = yield* resolveWorktreeT3Home(process.cwd());
+    if (worktreeHome !== undefined) {
+      bases.push(worktreeHome);
+    }
+    const envHome = yield* Config.string("T3CODE_HOME").pipe(Config.option);
+    bases.push(yield* resolveBaseDir(Option.getOrUndefined(envHome)));
+  }
+
+  const checkedStatePaths: Array<string> = [];
+  for (const baseDir of new Set(bases)) {
+    for (const variant of ["userdata", "dev"] as const) {
+      const derivedPaths = yield* ServerConfig.deriveServerPaths(
+        baseDir,
+        variant === "dev" ? DEV_VARIANT_PLACEHOLDER_URL : undefined,
+        {},
+      );
+      const statePath = derivedPaths.serverRuntimeStatePath;
+      checkedStatePaths.push(statePath);
+      const state = yield* readPersistedServerRuntimeState(statePath);
+      if (Option.isNone(state)) {
+        continue;
+      }
+      // The pid check guards against a dead server's state file whose port
+      // was since reused by a different server: pairing would then mint a
+      // token in the old database while the QR code points at the new server.
+      if (!isProcessAlive(state.value.pid)) {
+        continue;
+      }
+      const probed = yield* probeEnvironmentDescriptor(state.value.origin);
+      if (probed._tag !== "descriptor") {
+        continue;
+      }
+      return {
+        baseDir,
+        variant,
+        state: state.value,
+        descriptor: probed.descriptor,
+      } satisfies DiscoveredPairTarget;
+    }
+  }
+  return yield* new NoRunningServerError({ checkedStatePaths });
+});
+
+/**
+ * Server config pointed at the discovered server's state directory, so the
+ * minted token lands in the database the running server reads from. Built by
+ * hand rather than through `resolveServerConfig` to keep the dev-vs-userdata
+ * choice pinned to where the runtime state was actually found, independent of
+ * ambient environment variables.
+ */
+const makePairServerConfig = Effect.fn(function* (input: {
+  readonly target: DiscoveredPairTarget;
+  readonly logLevel: ServerConfig.ServerConfig["Service"]["logLevel"];
+}) {
+  const { baseDir, variant, state } = input.target;
+  // The state-dir variant does not imply dev-ness: a worktree dev server uses
+  // an explicit home and therefore lands in `userdata`. The recorded devUrl is
+  // what actually marks a dev server.
+  const devUrl = state.devUrl !== undefined ? new URL(state.devUrl) : undefined;
+  const derivedPaths = yield* ServerConfig.deriveServerPaths(
+    baseDir,
+    variant === "dev" ? DEV_VARIANT_PLACEHOLDER_URL : undefined,
+    {},
+  );
+  return ServerConfig.make({
+    logLevel: input.logLevel,
+    traceMinLevel: "Info",
+    traceTimingEnabled: false,
+    traceBatchWindowMs: 1_000,
+    traceMaxBytes: 10 * 1024 * 1024,
+    traceMaxFiles: 10,
+    otlpTracesUrl: undefined,
+    otlpMetricsUrl: undefined,
+    otlpExportIntervalMs: 10_000,
+    otlpServiceName: "t3-server",
+    mode: "web",
+    port: state.port,
+    host: state.host,
+    cwd: process.cwd(),
+    baseDir,
+    ...derivedPaths,
+    staticDir: undefined,
+    devUrl,
+    devAllowedOrigins: [],
+    noBrowser: true,
+    startupPresentation: "headless",
+    desktopBootstrapToken: undefined,
+    desktopTelemetryFd: undefined,
+    desktopTelemetryControlFd: undefined,
+    resourceMonitorPath: undefined,
+    autoBootstrapProjectFromCwd: false,
+    logWebSocketEvents: false,
+    tailscaleServeEnabled: false,
+    tailscaleServePort: DEFAULT_TAILSCALE_SERVE_PORT,
+  });
+});
+
+const awaitEnvironmentDescriptor = Effect.fn(function* (baseUrl: string) {
+  let last: EnvironmentProbeResult = { _tag: "unreachable" };
+  for (let attempt = 0; attempt < TAILSCALE_PROBE_ATTEMPTS; attempt += 1) {
+    last = yield* probeEnvironmentDescriptor(baseUrl);
+    if (last._tag === "descriptor") {
+      return last;
+    }
+    yield* Effect.sleep(TAILSCALE_PROBE_RETRY_DELAY);
+  }
+  return last;
+});
+
+const resolveTailscalePairingBase = Effect.fn("pair.resolveTailscalePairingBase")(
+  function* (input: { readonly target: DiscoveredPairTarget; readonly servePort: number }) {
+    const notes: Array<string> = [];
+    const status = yield* readTailscaleStatus.pipe(
+      Effect.mapError((cause) => new TailscaleUnavailableError({ cause })),
+    );
+    if (status.magicDnsName === null) {
+      return yield* new MagicDnsNameMissingError();
+    }
+    const baseUrl = buildTailscaleHttpsBaseUrl({
+      magicDnsName: status.magicDnsName,
+      servePort: input.servePort,
+    });
+
+    // Only an unreachable port, or a mapping already fronting this exact
+    // environment, is safe to (re)configure. Any other responder — T3 or not
+    // — must not have its mapping silently replaced.
+    const existing = yield* probeEnvironmentDescriptor(baseUrl);
+    if (existing._tag === "descriptor") {
+      if (existing.descriptor.environmentId !== input.target.descriptor.environmentId) {
+        return yield* new ServesOtherEnvironmentError({ servePort: input.servePort });
+      }
+      // Matching environment id proves the mapping reaches this server, but
+      // not through which port: for a dev server it may front the backend
+      // (whose /.well-known also answers) while /pair only renders through
+      // the web origin. Reuse as-is for regular servers; fall through and
+      // repoint our own mapping at the web port for dev servers.
+      if (input.target.state.devUrl === undefined) {
+        return { baseUrl, notes };
+      }
+    }
+    if (existing._tag === "not-a-t3-server") {
+      return yield* new ServePortOccupiedError({ servePort: input.servePort });
+    }
+
+    const localTarget = resolveTailscaleLocalTarget(input.target.state);
+    if (isDevServerNotProxiableError(localTarget)) {
+      return yield* localTarget;
+    }
+    yield* ensureTailscaleServe({
+      localPort: localTarget.localPort,
+      servePort: input.servePort,
+      ...(localTarget.localHost !== undefined ? { localHost: localTarget.localHost } : {}),
+    }).pipe(
+      Effect.mapError(
+        (cause) => new TailscaleServeFailedError({ servePort: input.servePort, cause }),
+      ),
+    );
+    notes.push(
+      `Tailscale Serve now maps ${baseUrl} to this server and persists across restarts. Remove it with \`tailscale serve --https=${String(input.servePort)} off\`.`,
+    );
+
+    const probed = yield* awaitEnvironmentDescriptor(baseUrl);
+    if (probed._tag === "descriptor") {
+      if (probed.descriptor.environmentId !== input.target.descriptor.environmentId) {
+        return yield* new ServesOtherEnvironmentError({ servePort: input.servePort });
+      }
+    } else {
+      notes.push(
+        "The HTTPS endpoint has not answered yet. First use can take a moment while Tailscale provisions certificates.",
+      );
+    }
+    return { baseUrl, notes };
+  },
+);
+
+const mintPairingLink = Effect.fn("pair.mintPairingLink")(function* (input: {
+  readonly config: ServerConfig.ServerConfig["Service"];
+  readonly ttl: Option.Option<Duration.Duration>;
+  readonly label: Option.Option<string>;
+}) {
+  return yield* Effect.gen(function* () {
+    const environmentAuth = yield* EnvironmentAuth.EnvironmentAuth;
+    return yield* environmentAuth.createPairingLink({
+      scopes: AuthStandardClientScopes,
+      subject: "one-time-token",
+      label: Option.getOrElse(input.label, () => "t3 pair"),
+      ...(Option.isSome(input.ttl) ? { ttl: input.ttl.value } : {}),
+    });
+  }).pipe(
+    Effect.provide(
+      EnvironmentAuth.runtimeLayer.pipe(
+        Layer.provide(ServerConfig.layer(input.config)),
+        Layer.provide(Layer.succeed(References.MinimumLogLevel, input.config.logLevel)),
+      ),
+    ),
+  );
+});
+
+const ttlFlag = Flag.string("ttl").pipe(
+  Flag.withSchema(DurationFromString),
+  Flag.withDescription(
+    "Token TTL, for example `5m`, `1h`, or `15 minutes`. Defaults to 5 minutes.",
+  ),
+  Flag.optional,
+);
+
+const labelFlag = Flag.string("label").pipe(
+  Flag.withDescription("Optional label shown in the server's connections list."),
+  Flag.optional,
+);
+
+const tailscaleFlag = Flag.boolean("tailscale").pipe(
+  Flag.withDescription(
+    "Publish the server over Tailscale Serve HTTPS and pair through the tailnet URL.",
+  ),
+  Flag.withDefault(false),
+);
+
+const tailscaleServePortFlag = Flag.integer("tailscale-serve-port").pipe(
+  Flag.withSchema(PortSchema),
+  Flag.withDescription("HTTPS port for Tailscale Serve when --tailscale is enabled."),
+  Flag.withDefault(DEFAULT_TAILSCALE_SERVE_PORT),
+);
+
+export const pairCommand = Command.make("pair", {
+  baseDir: baseDirFlag,
+  ttl: ttlFlag,
+  label: labelFlag,
+  tailscale: tailscaleFlag,
+  tailscaleServePort: tailscaleServePortFlag,
+}).pipe(
+  Command.withDescription(
+    "Mint a pairing token for a running T3 Code server and print it as a QR code.",
+  ),
+  Command.withHandler((flags) =>
+    Effect.gen(function* () {
+      const cliLogLevel = yield* GlobalFlag.LogLevel;
+      // Default to Warn so storage/migration chatter cannot bury the QR code;
+      // an explicit --log-level still wins.
+      const logLevel = Option.getOrElse(cliLogLevel, () => "Warn" as const);
+
+      const target = yield* discoverPairTarget(Option.getOrUndefined(flags.baseDir));
+
+      const notes: Array<string> = [];
+      let pairingBaseUrl: string;
+      if (flags.tailscale) {
+        const resolved = yield* resolveTailscalePairingBase({
+          target,
+          servePort: flags.tailscaleServePort,
+        });
+        pairingBaseUrl = resolved.baseUrl;
+        notes.push(...resolved.notes);
+      } else {
+        pairingBaseUrl = resolveDirectPairingBaseUrl(target.state);
+        if (isLoopbackHost(new URL(pairingBaseUrl).hostname)) {
+          notes.push(
+            "This URL is only reachable from this machine. Re-run with --tailscale, or restart the server with a reachable --host.",
+          );
+        }
+        if (target.variant === "dev" && target.state.devUrl === undefined) {
+          notes.push(
+            "This dev server did not record its web URL; restart it so pairing can go through the web origin.",
+          );
+        }
+      }
+
+      const config = yield* makePairServerConfig({ target, logLevel });
+      const issued = yield* mintPairingLink({ config, ttl: flags.ttl, label: flags.label });
+      const pairingUrl = buildPairingUrl(pairingBaseUrl, issued.credential);
+
+      yield* Console.log(
+        formatPairOutput({
+          serverLabel: target.descriptor.label,
+          origin: target.state.origin,
+          pairingUrl,
+          token: issued.credential,
+          expiresAt: issued.expiresAt,
+          notes,
+        }),
+      );
+    }).pipe(Effect.provide(FetchHttpClient.layer)),
+  ),
+);
diff --git a/apps/server/src/cli/project.ts b/apps/server/src/cli/project.ts
index 25733a5e35b..39b3b243112 100644
--- a/apps/server/src/cli/project.ts
+++ b/apps/server/src/cli/project.ts
@@ -337,7 +337,9 @@ const dispatchLiveOrchestrationCommand = (
 
 const getOfflineSnapshot = Effect.fn("getOfflineSnapshot")(function* () {
   const projectionSnapshotQuery = yield* ProjectionSnapshotQuery.ProjectionSnapshotQuery;
-  return yield* projectionSnapshotQuery.getSnapshot();
+  // Project commands only read the project list, so use the lightweight
+  // command read model instead of hydrating every thread body in the database.
+  return yield* projectionSnapshotQuery.getCommandReadModel();
 });
 
 const tryResolveLiveProjectExecutionMode = Effect.fn("tryResolveLiveProjectExecutionMode")(
diff --git a/apps/server/src/cli/servicePreflight.ts b/apps/server/src/cli/servicePreflight.ts
new file mode 100644
index 00000000000..60a457f388a
--- /dev/null
+++ b/apps/server/src/cli/servicePreflight.ts
@@ -0,0 +1,17 @@
+import * as Console from "effect/Console";
+import * as Effect from "effect/Effect";
+import { Command, Flag } from "effect/unstable/cli";
+
+import { runServicePreflight } from "../cloud/servicePreflight.ts";
+
+export const servicePreflightCommand = Command.make("__service-preflight", {
+  databasePath: Flag.string("database-path"),
+  launcherProtocol: Flag.integer("launcher-protocol"),
+}).pipe(
+  Command.withHidden,
+  Command.withHandler(({ databasePath, launcherProtocol }) =>
+    Console.log(JSON.stringify(runServicePreflight({ databasePath, launcherProtocol }))).pipe(
+      Effect.asVoid,
+    ),
+  ),
+);
diff --git a/apps/server/src/cloud/ManagedEndpointRuntime.test.ts b/apps/server/src/cloud/ManagedEndpointRuntime.test.ts
index e0d5924fcc2..b45b5099252 100644
--- a/apps/server/src/cloud/ManagedEndpointRuntime.test.ts
+++ b/apps/server/src/cloud/ManagedEndpointRuntime.test.ts
@@ -96,6 +96,15 @@ describe("CloudManagedEndpointRuntime", () => {
         "2026-06-17T02:00:00Z INF Starting metrics server",
       ),
     ).toBe("debug");
+    // FTL (fatal) and PNC (panic) are more severe than ERR and must surface.
+    expect(
+      ManagedEndpointRuntime.classifyRelayClientOutput(
+        "2026-06-17T02:00:00Z FTL Cannot determine default origin certificate path",
+      ),
+    ).toBe("warning");
+    expect(
+      ManagedEndpointRuntime.classifyRelayClientOutput("2026-06-17T02:00:00Z PNC runtime panic"),
+    ).toBe("warning");
   });
 
   it.effect("starts, deduplicates, rotates, and stops the Cloudflare connector", () =>
diff --git a/apps/server/src/cloud/ManagedEndpointRuntime.ts b/apps/server/src/cloud/ManagedEndpointRuntime.ts
index a1d7112a929..89c0a23783c 100644
--- a/apps/server/src/cloud/ManagedEndpointRuntime.ts
+++ b/apps/server/src/cloud/ManagedEndpointRuntime.ts
@@ -72,7 +72,10 @@ export function classifyRelayClientOutput(line: string): "connected" | "warning"
   if (/\bRegistered tunnel connection\b/iu.test(line)) {
     return "connected";
   }
-  return /\b(?:ERR|WRN)\b/u.test(line) ? "warning" : "debug";
+  // cloudflared uses zerolog level tokens. FTL (fatal) and PNC (panic) are more
+  // severe than ERR, so they must surface at least as loudly — without them a
+  // fatal connector failure would be logged at debug and hidden.
+  return /\b(?:ERR|WRN|FTL|PNC)\b/u.test(line) ? "warning" : "debug";
 }
 
 function runtimeConfigKey(config: RelayManagedEndpointRuntimeConfig): string {
diff --git a/apps/server/src/cloud/bootService.test.ts b/apps/server/src/cloud/bootService.test.ts
index 46e9a1da987..9af69eb1792 100644
--- a/apps/server/src/cloud/bootService.test.ts
+++ b/apps/server/src/cloud/bootService.test.ts
@@ -1,558 +1,151 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { assert, it } from "@effect/vitest";
+import { expect, it } from "@effect/vitest";
+import {
+  HostProcessArguments,
+  HostProcessExecutablePath,
+  HostProcessPlatform,
+} from "@t3tools/shared/hostProcess";
 import * as ConfigProvider from "effect/ConfigProvider";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
 import * as Path from "effect/Path";
-import * as Schema from "effect/Schema";
 import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
 
-import {
-  HostProcessArguments,
-  HostProcessExecutablePath,
-  HostProcessPlatform,
-} from "@t3tools/shared/hostProcess";
-
-import { reconcileService } from "../cli/service.ts";
 import * as ProcessRunner from "../processRunner.ts";
 import * as BootService from "./bootService.ts";
+import { pinnedRuntimePaths } from "./pinnedRuntime.ts";
+import { parseServiceState } from "./serviceProtocol.ts";
 
-const isUnsupportedError = Schema.is(BootService.BootServiceUnsupportedError);
-const isCommandError = Schema.is(BootService.BootServiceCommandError);
-
-interface RecordedCommand {
-  readonly command: string;
-  readonly args: ReadonlyArray<string>;
-}
-
-const makeRecordingRunnerLayer = (
-  commands: Array<RecordedCommand>,
-  options?: {
-    readonly failCommand?: string;
-    readonly failWhen?: (command: string, args: ReadonlyArray<string>) => boolean;
-  },
-) =>
-  Layer.succeed(
-    ProcessRunner.ProcessRunner,
-    ProcessRunner.ProcessRunner.of({
-      run: (input) =>
-        Effect.sync(() => {
-          assert.isUndefined(input.env);
-          commands.push({ command: input.command, args: input.args });
-          const failed =
-            input.command === options?.failCommand ||
-            options?.failWhen?.(input.command, input.args) === true;
-          return {
-            stdout: "",
-            stderr: failed ? `${input.command} exploded` : "",
-            code: ChildProcessSpawner.ExitCode(failed ? 1 : 0),
-            timedOut: false,
-            stdoutTruncated: false,
-            stderrTruncated: false,
-          };
-        }),
-    }),
-  );
-
-const makeHost = (entry: string): BootService.BootServiceHost => ({
-  execPath: "/usr/local/bin/node",
-  cliEntryPath: entry,
-});
-
-const provideHostRefs = (home: string, platform: NodeJS.Platform = "linux") =>
-  Effect.provide(
-    Layer.mergeAll(
-      Layer.succeed(HostProcessPlatform, platform),
-      ConfigProvider.layer(ConfigProvider.fromEnv({ env: { HOME: home } })),
-    ),
-  );
-
-const makeTestContext = Effect.fn("test.makeTestContext")(function* () {
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-  const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-boot-service-test-" });
-  // A real file for the stable-entry cases so status can confirm the entry
-  // point exists.
-  const stableEntry = path.join(root, "bin.mjs");
-  yield* fs.writeFileString(stableEntry, "#!/usr/bin/env node\n");
-  return {
-    fs,
-    path,
-    dirs: {
-      home: root,
-      baseDir: path.join(root, ".t3"),
-      logsDir: path.join(root, ".t3", "userdata", "logs"),
-      stableEntry,
-    },
-  };
-});
-
-it("renders a systemd unit with absolute paths and append-mode logging", () => {
+it("keeps systemd pinned to the stable launcher rather than a versioned server", () => {
   const unit = BootService.renderBootServiceUnit({
-    nodePath: "/usr/local/bin/node",
-    t3EntryPath: "/home/theo/.t3/runtime/versions/0.0.27/node_modules/t3/dist/bin.mjs",
+    nodePath: "/usr/bin/node",
+    launcherPath: "/home/theo/.t3/runtime/service-launcher.mjs",
     baseDir: "/home/theo/.t3",
     logPath: "/home/theo/.t3/userdata/logs/boot-service.log",
     unitPath: "/home/theo/.config/systemd/user/t3code.service",
   });
 
-  assert.equal(
-    unit,
-    [
-      "[Unit]",
-      "Description=T3 Code server",
-      "StartLimitIntervalSec=300",
-      "StartLimitBurst=5",
-      "",
-      "[Service]",
-      "Type=simple",
-      "WorkingDirectory=%h",
-      "Environment=T3CODE_HOME=/home/theo/.t3",
-      "Environment=T3_BOOT_SERVICE_UNIT=t3code.service",
-      "ExecStart=/usr/local/bin/node /home/theo/.t3/runtime/versions/0.0.27/node_modules/t3/dist/bin.mjs serve",
-      "Restart=always",
-      "RestartSec=5",
-      "StandardOutput=append:/home/theo/.t3/userdata/logs/boot-service.log",
-      "StandardError=append:/home/theo/.t3/userdata/logs/boot-service.log",
-      "",
-      "[Install]",
-      "WantedBy=default.target",
-      "",
-    ].join("\n"),
-  );
+  expect(unit).toContain("ExecStart=/usr/bin/node /home/theo/.t3/runtime/service-launcher.mjs");
+  expect(unit).toContain("KillMode=control-group");
+  expect(unit).not.toContain("versions/1.2.3");
 });
 
-it("quotes systemd values containing spaces and escapes percent specifiers", () => {
-  assert.equal(BootService.quoteSystemdValue("/plain/path"), "/plain/path");
-  assert.equal(BootService.quoteSystemdValue("/home/me/T3 Data"), '"/home/me/T3 Data"');
-  assert.equal(BootService.quoteSystemdValue("/opt/100%cpu"), "/opt/100%%cpu");
-
-  const unit = BootService.renderBootServiceUnit({
-    nodePath: "/home/me/my tools/node",
-    t3EntryPath: "/home/me/T3 Data/bin.mjs",
-    baseDir: "/home/me/T3 Data",
-    logPath: "/home/me/100%logs/boot.log",
-    unitPath: "/home/me/.config/systemd/user/t3code.service",
+const makeHarness = Effect.fn("test.make_boot_service_harness")(function* (
+  platform: NodeJS.Platform = "linux",
+  usePinnedLauncher = false,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const home = yield* fs.makeTempDirectoryScoped({ prefix: "t3-boot-service-test-" });
+  const baseDir = path.join(home, ".t3");
+  const sourceLauncher = path.join(home, "service-launcher.mjs");
+  const statePath = path.join(baseDir, "runtime", "service-state.json");
+  yield* fs.writeFileString(sourceLauncher, "export {};\n");
+  const runtime = pinnedRuntimePaths(path, baseDir, "1.2.3");
+  yield* fs.makeDirectory(path.dirname(runtime.entryPath), { recursive: true });
+  yield* fs.writeFileString(runtime.entryPath, "export {};\n");
+  yield* fs.writeFileString(
+    path.join(path.dirname(runtime.entryPath), "service-launcher.mjs"),
+    "export const source = 'pinned runtime';\n",
+  );
+  yield* fs.writeFileString(runtime.sentinelPath, "1.2.3\n");
+
+  const commands: string[] = [];
+  const control: { failCommand: string | undefined } = { failCommand: undefined };
+  const runner = ProcessRunner.ProcessRunner.of({
+    run: (input) =>
+      Effect.sync(() => {
+        const command = `${input.command} ${input.args.join(" ")}`;
+        commands.push(command);
+        return {
+          stdout: input.args[1] === "--version" ? "t3 v1.2.3\n" : "",
+          stderr: "",
+          code: ChildProcessSpawner.ExitCode(command === control.failCommand ? 1 : 0),
+          timedOut: false,
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        };
+      }),
   });
-  assert.include(unit, 'ExecStart="/home/me/my tools/node" "/home/me/T3 Data/bin.mjs" serve');
-  assert.include(unit, 'Environment=T3CODE_HOME="/home/me/T3 Data"');
-  // append: paths take the rest of the line literally (spaces are fine,
-  // quoting is not), but % still goes through specifier expansion.
-  assert.include(unit, "StandardOutput=append:/home/me/100%%logs/boot.log");
-  assert.include(unit, "StandardError=append:/home/me/100%%logs/boot.log");
-});
-
-it("flags package-manager cache entry points as ephemeral", () => {
-  assert.isTrue(
-    BootService.isEphemeralCacheEntry("/home/theo/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs"),
-  );
-  assert.isTrue(
-    BootService.isEphemeralCacheEntry("C:\\Users\\theo\\AppData\\npm-cache\\_npx\\abc\\bin.mjs"),
-  );
-  assert.isTrue(
-    BootService.isEphemeralCacheEntry(
-      "/home/theo/.cache/pnpm/dlx/abc/node_modules/t3/dist/bin.mjs",
-    ),
-  );
-  assert.isTrue(
-    BootService.isEphemeralCacheEntry("/home/theo/.bun/install/cache/t3@0.0.27/dist/bin.mjs"),
-  );
-  assert.isFalse(BootService.isEphemeralCacheEntry("/usr/local/lib/node_modules/t3/dist/bin.mjs"));
-  assert.isFalse(
-    BootService.isEphemeralCacheEntry(
-      "/home/theo/dev/pnpm/dlx-tools/t3/node_modules/t3/dist/bin.mjs",
-    ),
-  );
-  assert.isFalse(
-    BootService.isEphemeralCacheEntry(
-      "/home/theo/.t3/runtime/versions/0.0.27/node_modules/t3/dist/bin.mjs",
+  const service = yield* BootService.make({
+    baseDir,
+    logsDir: path.join(baseDir, "userdata", "logs"),
+    cliVersion: "1.2.3",
+    host: {
+      execPath: "/usr/bin/node",
+      ...(usePinnedLauncher ? {} : { launcherSourcePath: sourceLauncher }),
+    },
+  }).pipe(
+    Effect.provideService(ProcessRunner.ProcessRunner, runner),
+    Effect.provide(
+      Layer.mergeAll(
+        Layer.succeed(HostProcessPlatform, platform),
+        Layer.succeed(HostProcessExecutablePath, "/usr/bin/node"),
+        Layer.succeed(HostProcessArguments, ["/usr/bin/node", path.join(home, "bin.mjs")]),
+        ConfigProvider.layer(ConfigProvider.fromEnv({ env: { HOME: home } })),
+      ),
     ),
   );
+  return { service, fs, statePath, commands, control };
 });
 
-it.layer(NodeServices.layer)("BootService", (it) => {
-  it.effect("reconciles the standalone service once and is then idempotent", () =>
+it.layer(NodeServices.layer)("boot service install", (it) => {
+  it.effect("installs, reports current state, and uninstalls", () =>
     Effect.gen(function* () {
-      const { dirs } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost(dirs.stableEntry),
-      }).pipe(Effect.provide(makeRecordingRunnerLayer(commands)), provideHostRefs(dirs.home));
-
-      const first = yield* reconcileService().pipe(
-        Effect.provideService(BootService.BootService, service),
-      );
-      assert.isTrue(first.changed);
-      if (!first.changed) return;
-      assert.isFalse(first.previouslyInstalled);
-
-      const commandCount = commands.length;
-      const second = yield* reconcileService().pipe(
-        Effect.provideService(BootService.BootService, service),
-      );
-      assert.isFalse(second.changed);
-      assert.lengthOf(commands, commandCount);
-    }),
-  );
-
-  it.effect("installs the unit, enables the service, and enables linger", () =>
-    Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost(dirs.stableEntry),
-      }).pipe(Effect.provide(makeRecordingRunnerLayer(commands)), provideHostRefs(dirs.home));
-
+      const { service, fs, statePath, commands } = yield* makeHarness();
       const plan = yield* service.install;
 
-      // A stable entry point is reused directly — no npm install.
-      assert.equal(plan.t3EntryPath, dirs.stableEntry);
-      assert.deepEqual(
-        commands.map((entry) => [entry.command, ...entry.args].join(" ")),
-        [
-          "systemctl --user daemon-reload",
-          "systemctl --user enable t3code.service",
-          // restart (not enable --now) so repairing a stale unit replaces a
-          // running process instead of leaving the old one until reboot.
-          "systemctl --user restart t3code.service",
-          "loginctl enable-linger",
-        ],
-      );
-
-      const unitPath = path.join(dirs.home, ".config", "systemd", "user", "t3code.service");
-      const unit = yield* fs.readFileString(unitPath);
-      assert.include(unit, `ExecStart=/usr/local/bin/node ${dirs.stableEntry} serve`);
-      assert.include(unit, `Environment=T3CODE_HOME=${dirs.baseDir}`);
-
-      const status = yield* service.status;
-      assert.isTrue(status.supported);
-      assert.isTrue(status.installed);
-      assert.isTrue(status.current);
-
-      const removed = yield* service.uninstall;
-      assert.isTrue(removed);
-      assert.isFalse(yield* fs.exists(unitPath));
-      const statusAfter = yield* service.status;
-      assert.isFalse(statusAfter.installed);
-      const removedAgain = yield* service.uninstall;
-      assert.isFalse(removedAgain);
-    }),
-  );
-
-  it.effect("pins a runtime via npm install when running from the npx cache", () =>
-    Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost("/home/theo/.npm/_npx/abc/node_modules/t3/dist/bin.mjs"),
-      }).pipe(Effect.provide(makeRecordingRunnerLayer(commands)), provideHostRefs(dirs.home));
-
-      const plan = yield* service.install;
-
-      const runtimeDir = path.join(dirs.baseDir, "runtime", "versions", "0.0.27");
-      assert.equal(
-        plan.t3EntryPath,
-        path.join(runtimeDir, "node_modules", "t3", "dist", "bin.mjs"),
-      );
-      assert.deepEqual(commands[0], {
-        command: "npm",
-        args: ["install", "--prefix", runtimeDir, "--no-fund", "--no-audit", "t3@0.0.27"],
+      expect(parseServiceState(yield* fs.readFileString(statePath))).toEqual({
+        protocol: 1,
+        activeVersion: "1.2.3",
       });
-      // Success is recorded via a sentinel so interrupted installs re-run.
-      assert.isTrue(yield* fs.exists(path.join(runtimeDir, ".install-complete")));
-    }),
-  );
-
-  it.effect("reinstalls a pinned runtime when its entry point is missing", () =>
-    Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost("/home/theo/.npm/_npx/abc/node_modules/t3/dist/bin.mjs"),
-      }).pipe(Effect.provide(makeRecordingRunnerLayer(commands)), provideHostRefs(dirs.home));
-
-      const plan = yield* service.install;
-      yield* fs.makeDirectory(path.dirname(plan.t3EntryPath), { recursive: true });
-      yield* fs.writeFileString(plan.t3EntryPath, "#!/usr/bin/env node\n");
-      yield* fs.remove(plan.t3EntryPath);
-      commands.length = 0;
-
-      yield* service.install;
-
-      assert.isTrue(commands.some(({ command }) => command === "npm"));
-    }),
-  );
-
-  it.effect("reads executable metadata from host process references", () =>
-    Effect.gen(function* () {
-      const { dirs } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-      }).pipe(
-        Effect.provide(makeRecordingRunnerLayer(commands)),
-        provideHostRefs(dirs.home),
-        Effect.provideService(HostProcessExecutablePath, "/opt/node/bin/node"),
-        Effect.provideService(HostProcessArguments, ["/opt/node/bin/node", dirs.stableEntry]),
-      );
-
-      const plan = yield* service.install;
-      assert.equal(plan.nodePath, "/opt/node/bin/node");
-      assert.equal(plan.t3EntryPath, dirs.stableEntry);
-    }),
-  );
-
-  it.effect("cleans up and fails when the pinned runtime install fails", () =>
-    Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost("/home/theo/.npm/_npx/abc/node_modules/t3/dist/bin.mjs"),
-      }).pipe(
-        Effect.provide(makeRecordingRunnerLayer(commands, { failCommand: "npm" })),
-        provideHostRefs(dirs.home),
-      );
-
-      const error = yield* service.install.pipe(Effect.flip);
-      assert.isTrue(isCommandError(error));
-      const runtimeDir = path.join(dirs.baseDir, "runtime", "versions", "0.0.27");
-      // The half-installed tree must not be reused by the next attempt.
-      assert.isFalse(yield* fs.exists(runtimeDir));
-      assert.isFalse(yield* fs.exists(path.join(runtimeDir, ".install-complete")));
-    }),
-  );
-
-  it.effect("reports an installed-but-stale unit so the lifecycle can offer a repair", () =>
-    Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost(dirs.stableEntry),
-      }).pipe(Effect.provide(makeRecordingRunnerLayer(commands)), provideHostRefs(dirs.home));
-
-      const unitDir = path.join(dirs.home, ".config", "systemd", "user");
-      yield* fs.makeDirectory(unitDir, { recursive: true });
+      expect(yield* fs.readFileString(plan.launcherPath)).toBe("export {};\n");
+      expect((yield* service.status).current).toBe(true);
       yield* fs.writeFileString(
-        path.join(unitDir, "t3code.service"),
-        "[Service]\nExecStart=/old/node /old/t3 serve\n",
+        statePath,
+        '{"protocol":1,"activeVersion":"1.2.3","update":{"id":"u","fromVersion":"1.2.3","targetVersion":"1.2.4","status":"pending"}}',
       );
-
-      const status = yield* service.status;
-      assert.isTrue(status.supported);
-      assert.isTrue(status.installed);
-      assert.isFalse(status.current);
-    }),
-  );
-
-  it.effect("reports a current unit as stale when its entry point is gone", () =>
-    Effect.gen(function* () {
-      const { dirs, fs } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost(dirs.stableEntry),
-      }).pipe(Effect.provide(makeRecordingRunnerLayer(commands)), provideHostRefs(dirs.home));
-
-      yield* service.install;
-      assert.isTrue((yield* service.status).current);
-
-      // The pinned runtime (or global bin) was deleted to reclaim space; the
-      // unit still matches byte-for-byte but would crashloop at boot.
-      yield* fs.remove(dirs.stableEntry);
-      const status = yield* service.status;
-      assert.isTrue(status.installed);
-      assert.isFalse(status.current);
+      expect((yield* service.status).current).toBe(false);
+      expect(yield* service.uninstall).toBe(true);
+      expect((yield* service.status).installed).toBe(false);
+      expect(commands.some((command) => command.startsWith("npm "))).toBe(false);
     }),
   );
 
-  it.effect("fails on non-Linux platforms without touching the filesystem", () =>
+  it.effect("copies the launcher from the prepared pinned runtime", () =>
     Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost("/usr/local/lib/node_modules/t3/dist/bin.mjs"),
-      }).pipe(
-        Effect.provide(makeRecordingRunnerLayer(commands)),
-        provideHostRefs(dirs.home, "darwin"),
-      );
+      const { service, fs } = yield* makeHarness("linux", true);
+      const plan = yield* service.install;
 
-      const error = yield* service.install.pipe(Effect.flip);
-      assert.isTrue(isUnsupportedError(error));
-      assert.lengthOf(commands, 0);
-      assert.isFalse(
-        yield* fs.exists(path.join(dirs.home, ".config", "systemd", "user", "t3code.service")),
+      expect(yield* fs.readFileString(plan.launcherPath)).toBe(
+        "export const source = 'pinned runtime';\n",
       );
-
-      const status = yield* service.status;
-      assert.isFalse(status.supported);
-      assert.isFalse(status.installed);
     }),
   );
 
-  it.effect("removes the unit file when an activation step fails", () =>
+  it.effect("restarts an installed service when repair fails", () =>
     Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost("/usr/local/lib/node_modules/t3/dist/bin.mjs"),
-      }).pipe(
-        Effect.provide(makeRecordingRunnerLayer(commands, { failCommand: "loginctl" })),
-        provideHostRefs(dirs.home),
-      );
+      const { service, commands, control } = yield* makeHarness();
+      yield* service.install;
+      commands.length = 0;
+      control.failCommand = "systemctl --user daemon-reload";
 
       const error = yield* service.install.pipe(Effect.flip);
-      assert.isTrue(isCommandError(error));
-      // A leftover unit would make status report "installed" even though
-      // linger never happened.
-      assert.isFalse(
-        yield* fs.exists(path.join(dirs.home, ".config", "systemd", "user", "t3code.service")),
-      );
-      const status = yield* service.status;
-      assert.isFalse(status.installed);
-      assert.isTrue(
-        commands.some(
-          ({ command, args }) =>
-            command === "systemctl" && args.join(" ") === "--user disable --now t3code.service",
-        ),
-      );
+      expect(error._tag).toBe("BootServiceCommandError");
+      expect(commands.filter((command) => command.startsWith("systemctl "))).toEqual([
+        "systemctl --user stop t3code.service",
+        "systemctl --user daemon-reload",
+        "systemctl --user restart t3code.service",
+      ]);
     }),
   );
 
-  it.effect("restores the previous unit when a repair cannot activate", () =>
+  it.effect("fails closed off Linux", () =>
     Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const initialCommands: Array<RecordedCommand> = [];
-      const initialService = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost(dirs.stableEntry),
-      }).pipe(
-        Effect.provide(makeRecordingRunnerLayer(initialCommands)),
-        provideHostRefs(dirs.home),
-      );
-      yield* initialService.install;
-
-      const unitPath = path.join(dirs.home, ".config", "systemd", "user", "t3code.service");
-      const previousUnit = yield* fs.readFileString(unitPath);
-      const replacementEntry = path.join(dirs.home, "replacement-bin.mjs");
-      yield* fs.writeFileString(replacementEntry, "#!/usr/bin/env node\n");
-      const repairCommands: Array<RecordedCommand> = [];
-      const repairService = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.28",
-        host: makeHost(replacementEntry),
-      }).pipe(
-        Effect.provide(makeRecordingRunnerLayer(repairCommands, { failCommand: "loginctl" })),
-        provideHostRefs(dirs.home),
-      );
-
-      const error = yield* repairService.install.pipe(Effect.flip);
-
-      assert.isTrue(isCommandError(error));
-      assert.equal(yield* fs.readFileString(unitPath), previousUnit);
-      assert.isTrue(
-        repairCommands.some(
-          ({ command, args }) =>
-            command === "systemctl" && args.join(" ") === "--user restart t3code.service",
-        ),
-      );
-    }),
-  );
-
-  it.effect("keeps the unit when stopping it during uninstall fails", () =>
-    Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const installCommands: Array<RecordedCommand> = [];
-      const installedService = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost(dirs.stableEntry),
-      }).pipe(
-        Effect.provide(makeRecordingRunnerLayer(installCommands)),
-        provideHostRefs(dirs.home),
-      );
-      yield* installedService.install;
-
-      const uninstallCommands: Array<RecordedCommand> = [];
-      const failingService = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost(dirs.stableEntry),
-      }).pipe(
-        Effect.provide(
-          makeRecordingRunnerLayer(uninstallCommands, {
-            failWhen: (command, args) =>
-              command === "systemctl" && args.includes("disable") && args.includes("--now"),
-          }),
-        ),
-        provideHostRefs(dirs.home),
-      );
-
-      const error = yield* failingService.uninstall.pipe(Effect.flip);
-
-      assert.isTrue(isCommandError(error));
-      assert.isTrue(
-        yield* fs.exists(path.join(dirs.home, ".config", "systemd", "user", "t3code.service")),
-      );
-    }),
-  );
-
-  it.effect("appends failed steps to the boot-service log", () =>
-    Effect.gen(function* () {
-      const { dirs, fs, path } = yield* makeTestContext();
-      const commands: Array<RecordedCommand> = [];
-      const service = yield* BootService.make({
-        baseDir: dirs.baseDir,
-        logsDir: dirs.logsDir,
-        cliVersion: "0.0.27",
-        host: makeHost("/usr/local/lib/node_modules/t3/dist/bin.mjs"),
-      }).pipe(
-        Effect.provide(makeRecordingRunnerLayer(commands, { failCommand: "systemctl" })),
-        provideHostRefs(dirs.home),
-      );
-
-      const error = yield* service.install.pipe(Effect.flip);
-      assert.isTrue(isCommandError(error));
-      if (!isCommandError(error)) return;
-      assert.equal(error.exitCode, 1);
-      assert.equal(error.stderrLength, "systemctl exploded".length);
-
-      const logPath = path.join(dirs.logsDir, "boot-service.log");
-      assert.isTrue(yield* fs.exists(logPath));
-      assert.include(yield* fs.readFileString(logPath), "exit code 1");
+      const { service } = yield* makeHarness("darwin");
+      expect((yield* service.status).supported).toBe(false);
+      expect((yield* service.install.pipe(Effect.flip))._tag).toBe("BootServiceUnsupportedError");
     }),
   );
 });
diff --git a/apps/server/src/cloud/bootService.ts b/apps/server/src/cloud/bootService.ts
index d7e13e834f4..9a8481b11b5 100644
--- a/apps/server/src/cloud/bootService.ts
+++ b/apps/server/src/cloud/bootService.ts
@@ -1,5 +1,6 @@
-import * as Context from "effect/Context";
+import { HostProcessExecutablePath, HostProcessPlatform } from "@t3tools/shared/hostProcess";
 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";
@@ -9,58 +10,29 @@ import * as Option from "effect/Option";
 import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 
-import {
-  HostProcessArguments,
-  HostProcessExecutablePath,
-  HostProcessPlatform,
-} from "@t3tools/shared/hostProcess";
-
 import * as ProcessRunner from "../processRunner.ts";
-import { ensurePinnedRuntimeInstalled, pinnedRuntimePaths } from "./pinnedRuntime.ts";
-
-/**
- * Installs T3 Code as a per-user boot service. Linux-only for now: systemd
- * user unit + loginctl enable-linger. The service runs a stable or pinned
- * runtime — never an ephemeral `npx t3` cache whose eviction could break
- * startup.
- */
+import {
+  ensurePinnedRuntimeInstalled,
+  pinnedRuntimePaths,
+  PinnedRuntimeInstallError,
+} from "./pinnedRuntime.ts";
+import {
+  SERVICE_LAUNCHER_FILE,
+  SERVICE_LAUNCHER_PROTOCOL,
+  SERVICE_STATE_FILE,
+  parseServiceState,
+  type ServiceState,
+} from "./serviceProtocol.ts";
 
 const BOOT_SERVICE_NAME = "t3code";
-
 export const BOOT_SERVICE_UNIT_FILE = `${BOOT_SERVICE_NAME}.service`;
 export const BOOT_SERVICE_UNIT_ENV = "T3_BOOT_SERVICE_UNIT";
 
-const EPHEMERAL_CACHE_SEGMENTS = [
-  "/_npx/", // npx
-  "\\_npx\\",
-  "/pnpm/dlx/", // pnpm dlx (~/.cache/pnpm/dlx and $PNPM_HOME/.pnpm/dlx)
-  "/.pnpm/dlx/",
-  "/.bun/install/cache/", // bunx
-];
-
-/**
- * `npx t3` (and pnpm dlx / bunx) run out of ephemeral package-manager
- * caches that can be evicted at any time — a boot service must never point
- * there. Global installs, repo checkouts, and the pinned runtime below are
- * all stable.
- */
-export function isEphemeralCacheEntry(entryPath: string): boolean {
-  return EPHEMERAL_CACHE_SEGMENTS.some((segment) => entryPath.includes(segment));
-}
-
-/**
- * systemd expands `%` specifiers in most directive values, including the
- * `append:` file paths, which take the rest of the line literally and must
- * NOT be quoted.
- */
+/** systemd expands `%` specifiers, including in unquoted append-log paths. */
 export function escapeSystemdSpecifiers(value: string): string {
   return value.replaceAll("%", "%%");
 }
 
-/**
- * systemd word-splits ExecStart and Environment values and expands `%`
- * specifiers, so paths with spaces or percents must be quoted and escaped.
- */
 export function quoteSystemdValue(value: string): string {
   const escaped = escapeSystemdSpecifiers(value);
   return /[\s"'\\]/.test(escaped)
@@ -69,31 +41,19 @@ export function quoteSystemdValue(value: string): string {
 }
 
 export interface BootServicePlan {
-  /** Absolute path of the node binary running this CLI. */
   readonly nodePath: string;
-  /** Absolute path of the pinned t3 entry point the unit will run. */
-  readonly t3EntryPath: string;
+  readonly launcherPath: string;
   readonly baseDir: string;
   readonly logPath: string;
   readonly unitPath: string;
 }
 
-/**
- * Pure so it is testable byte-for-byte. systemd user units run with a
- * minimal environment: every path must be absolute, and the service must
- * not rely on PATH, nvm shims, or shell profiles. Failures land in
- * `logPath` because `systemctl --user` failures are otherwise invisible.
- */
+/** Pure renderer: service units cannot rely on the user's shell or PATH. */
 export function renderBootServiceUnit(plan: BootServicePlan): string {
-  // No After=network-online.target: it does not exist in the systemd *user*
-  // manager, so ordering on it is silently ignored. The server retries its
-  // relay connection, and Restart=always covers early-boot failures.
+  // The user manager has no reliable network-online target; server networking retries itself.
   return [
     "[Unit]",
     "Description=T3 Code server",
-    // Give up after 5 crashes in 5 minutes so a persistently broken install
-    // (deleted runtime, broken workspace) stops instead of restarting every
-    // 5s forever and growing the unrotated append log without bound.
     "StartLimitIntervalSec=300",
     "StartLimitBurst=5",
     "",
@@ -102,7 +62,8 @@ export function renderBootServiceUnit(plan: BootServicePlan): string {
     "WorkingDirectory=%h",
     `Environment=T3CODE_HOME=${quoteSystemdValue(plan.baseDir)}`,
     `Environment=${BOOT_SERVICE_UNIT_ENV}=${BOOT_SERVICE_UNIT_FILE}`,
-    `ExecStart=${quoteSystemdValue(plan.nodePath)} ${quoteSystemdValue(plan.t3EntryPath)} serve`,
+    `ExecStart=${quoteSystemdValue(plan.nodePath)} ${quoteSystemdValue(plan.launcherPath)}`,
+    "KillMode=control-group",
     "Restart=always",
     "RestartSec=5",
     `StandardOutput=append:${escapeSystemdSpecifiers(plan.logPath)}`,
@@ -157,7 +118,6 @@ export type BootServiceError =
 export interface BootServiceStatus {
   readonly supported: boolean;
   readonly installed: boolean;
-  /** False when the installed unit no longer matches what install would write. */
   readonly current: boolean;
   readonly unitPath: string;
   readonly logPath: string;
@@ -166,12 +126,7 @@ export interface BootServiceStatus {
 export class BootService extends Context.Service<
   BootService,
   {
-    /** Installs the pinned runtime + unit, enables linger, starts the service. */
     readonly install: Effect.Effect<BootServicePlan, BootServiceError>;
-    /**
-     * Stops and removes the unit; leaves the pinned runtime for reuse.
-     * Returns whether a unit was actually removed.
-     */
     readonly uninstall: Effect.Effect<boolean, BootServiceError>;
     readonly status: Effect.Effect<BootServiceStatus, BootServiceError>;
   }
@@ -179,7 +134,7 @@ export class BootService extends Context.Service<
 
 export interface BootServiceHost {
   readonly execPath: string;
-  readonly cliEntryPath: string;
+  readonly launcherSourcePath?: string;
 }
 
 export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
@@ -189,23 +144,41 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
   readonly host?: BootServiceHost;
 }) {
   const hostExecPath = yield* HostProcessExecutablePath;
-  const hostArguments = yield* HostProcessArguments;
-  const host = input.host ?? {
-    execPath: hostExecPath,
-    // When running the packed CLI this is dist/bin.mjs; when stable (global
-    // install, repo checkout) the boot service runs this same artifact.
-    cliEntryPath: hostArguments[1] ?? "",
-  };
   const platform = yield* HostProcessPlatform;
   const homeDir = yield* Config.string("HOME").pipe(Config.withDefault(""));
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   const runner = yield* ProcessRunner.ProcessRunner;
+  const host = input.host ?? { execPath: hostExecPath };
 
   const unitDir = path.join(homeDir, ".config", "systemd", "user");
   const unitPath = path.join(unitDir, BOOT_SERVICE_UNIT_FILE);
   const logPath = path.join(input.logsDir, "boot-service.log");
+  const launcherPath = path.join(input.baseDir, "runtime", SERVICE_LAUNCHER_FILE);
+  const statePath = path.join(input.baseDir, "runtime", SERVICE_STATE_FILE);
   const runtimePaths = pinnedRuntimePaths(path, input.baseDir, input.cliVersion);
+  const launcherSourcePath =
+    host.launcherSourcePath ??
+    path.join(path.dirname(runtimePaths.entryPath), SERVICE_LAUNCHER_FILE);
+  const writeDurably = (filePath: string, contents: string) =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const directory = path.dirname(filePath);
+        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;
+        yield* fs.rename(tempPath, filePath);
+        yield* (yield* fs.open(directory, { flag: "r" })).sync;
+      }),
+    ).pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause })));
+  const plan: BootServicePlan = {
+    nodePath: host.execPath,
+    launcherPath,
+    baseDir: input.baseDir,
+    logPath,
+    unitPath,
+  };
 
   const requireSystemdLinux = Effect.gen(function* () {
     if (platform !== "linux" || homeDir === "") {
@@ -244,150 +217,130 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
     );
   });
 
-  /**
-   * Ensures plannedEntryPath exists before the unit points at it. A stable
-   * install (global bin, repo checkout) is used as-is; an ephemeral cache
-   * entry is replaced by `npm install --prefix`-ing the exact running
-   * version into <baseDir>/runtime/versions/<v>. A real install (not a copy
-   * of bin.mjs) because t3 ships native deps like node-pty.
-   */
-  const ensurePinnedRuntime = Effect.gen(function* () {
-    if (!isEphemeralCacheEntry(host.cliEntryPath)) {
-      return;
-    }
+  const install: BootService["Service"]["install"] = Effect.gen(function* () {
+    yield* requireSystemdLinux;
+    yield* fs
+      .makeDirectory(input.logsDir, { recursive: true })
+      .pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause })));
+
+    // Prepare every immutable artifact before stopping the installed unit.
     yield* ensurePinnedRuntimeInstalled({
       baseDir: input.baseDir,
       version: input.cliVersion,
       fs,
       path,
       runner,
+      validate: (runtime) =>
+        runner
+          .run({
+            command: host.execPath,
+            args: [runtime.entryPath, "--version"],
+            timeout: Duration.seconds(30),
+          })
+          .pipe(
+            Effect.mapError(
+              (cause) =>
+                new PinnedRuntimeInstallError({
+                  step: "verifying the pinned t3 runtime",
+                  cause,
+                }),
+            ),
+            Effect.flatMap((result) => {
+              const reportedVersion = /\bv(\S+)\s*$/.exec(result.stdout)?.[1];
+              return result.code === 0 && reportedVersion === input.cliVersion
+                ? Effect.void
+                : Effect.fail(
+                    new PinnedRuntimeInstallError({
+                      step: "verifying the pinned t3 runtime",
+                      exitCode: Number(result.code),
+                      stdoutLength: result.stdout.length,
+                      stderrLength: result.stderr.length,
+                    }),
+                  );
+            }),
+          ),
     }).pipe(
       Effect.mapError((error) =>
-        error.step.startsWith("installing")
+        error._tag === "PinnedRuntimeInstallError"
           ? new BootServiceCommandError({
               step: error.step,
               exitCode: error.exitCode,
               stdoutLength: error.stdoutLength,
               stderrLength: error.stderrLength,
-              cause: error.cause,
+              cause: error,
             })
           : new BootServiceInstallError({ cause: error }),
       ),
-      Effect.tapError((error) =>
-        DateTime.now.pipe(
-          Effect.flatMap((now) =>
-            fs.writeFileString(logPath, `${DateTime.formatIso(now)} ${error.message}\n`, {
-              flag: "a",
-            }),
-          ),
-          Effect.ignore,
-        ),
-      ),
     );
-  });
-
-  // Where the unit will point: derivable without touching the network, so
-  // status can compare units purely; install materializes it first.
-  const plannedEntryPath = isEphemeralCacheEntry(host.cliEntryPath)
-    ? runtimePaths.entryPath
-    : host.cliEntryPath;
-  const plan: BootServicePlan = {
-    nodePath: host.execPath,
-    t3EntryPath: plannedEntryPath,
-    baseDir: input.baseDir,
-    logPath,
-    unitPath,
-  };
-
-  const install: BootService["Service"]["install"] = Effect.gen(function* () {
-    yield* requireSystemdLinux;
-    yield* fs
-      .makeDirectory(input.logsDir, { recursive: true })
+    const launcherSource = yield* fs
+      .readFileString(launcherSourcePath)
       .pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause })));
 
-    yield* ensurePinnedRuntime;
-
-    const previousUnit = yield* fs.exists(unitPath).pipe(
-      Effect.flatMap((exists) =>
-        exists
-          ? fs.readFileString(unitPath).pipe(Effect.map(Option.some))
-          : Effect.succeed(Option.none<string>()),
-      ),
-      Effect.mapError((cause) => new BootServiceInstallError({ cause })),
-    );
-
-    yield* fs.makeDirectory(unitDir, { recursive: true }).pipe(
-      Effect.andThen(fs.writeFileString(unitPath, renderBootServiceUnit(plan))),
-      Effect.mapError((cause) => new BootServiceInstallError({ cause })),
-    );
+    const installed = yield* fs
+      .exists(unitPath)
+      .pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause })));
+    if (installed) {
+      yield* runStep("stopping the installed service", "systemctl", [
+        "--user",
+        "stop",
+        BOOT_SERVICE_UNIT_FILE,
+      ]);
+    }
 
-    // If any activation step fails, remove the unit again: a leftover file
-    // would make service status report it as installed even though it was
-    // never enabled or lingered.
     yield* Effect.gen(function* () {
+      yield* fs
+        .makeDirectory(unitDir, { recursive: true })
+        .pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause })));
+      yield* writeDurably(launcherPath, launcherSource);
+      yield* writeDurably(
+        statePath,
+        // @effect-diagnostics-next-line preferSchemaOverJson:off - fixed launcher-owned document.
+        `${JSON.stringify(
+          {
+            protocol: SERVICE_LAUNCHER_PROTOCOL,
+            activeVersion: input.cliVersion,
+          } satisfies ServiceState,
+          null,
+          2,
+        )}\n`,
+      );
+      yield* writeDurably(unitPath, renderBootServiceUnit(plan));
+
       yield* runStep("reloading systemd user units", "systemctl", ["--user", "daemon-reload"]);
       yield* runStep("enabling the service", "systemctl", [
         "--user",
         "enable",
         BOOT_SERVICE_UNIT_FILE,
       ]);
-      // restart rather than enable --now: --now does not replace an already
-      // running process, so repairing a stale unit would leave the old
-      // server running until reboot. restart also starts a stopped service.
+      yield* runStep("enabling lingering for this user", "loginctl", ["enable-linger"]);
+      // Start last. No administrative state write occurs after this succeeds.
       yield* runStep("starting the service", "systemctl", [
         "--user",
         "restart",
         BOOT_SERVICE_UNIT_FILE,
       ]);
-      // Linger keeps the user manager (and this service) running without an
-      // open session — the whole point on a box reached over SSH. No
-      // username argument: loginctl defaults to the calling user, which is
-      // always right, while $USER can be stale (su without -l) or unset.
-      yield* runStep("enabling lingering for this user", "loginctl", ["enable-linger"]);
-    }).pipe(Effect.tapError(() => rollbackFailedInstall(previousUnit)));
-
+    }).pipe(
+      Effect.tapError(() =>
+        installed
+          ? runStep("restarting the service after a failed update", "systemctl", [
+              "--user",
+              "restart",
+              BOOT_SERVICE_UNIT_FILE,
+            ]).pipe(Effect.ignore)
+          : Effect.void,
+      ),
+    );
     return plan;
   }).pipe(Effect.withSpan("cloud.boot_service.install"));
 
-  // If activation fails partway (e.g. enable succeeds but restart/linger
-  // fails), leave nothing behind: disable removes the enable symlink, remove
-  // deletes the file, daemon-reload clears the stale definition — otherwise a
-  // dangling wants/ symlink logs "Failed to load unit" at every boot and the
-  // next lifecycle command misreports the state.
-  const rollbackFailedInstall = Effect.fn("cloud.boot_service.rollback_failed_install")(function* (
-    previousUnit: Option.Option<string>,
-  ) {
-    if (Option.isSome(previousUnit)) {
-      yield* fs.writeFileString(unitPath, previousUnit.value).pipe(Effect.ignore);
-    } else {
-      yield* runStep("cleaning up the service", "systemctl", [
-        "--user",
-        "disable",
-        "--now",
-        BOOT_SERVICE_UNIT_FILE,
-      ]).pipe(Effect.ignore);
-      yield* fs.remove(unitPath).pipe(Effect.ignore);
-    }
-    yield* runStep("reloading systemd user units", "systemctl", ["--user", "daemon-reload"]).pipe(
-      Effect.ignore,
-    );
-    if (Option.isSome(previousUnit)) {
-      yield* runStep("restoring the previous service", "systemctl", [
-        "--user",
-        "restart",
-        BOOT_SERVICE_UNIT_FILE,
-      ]).pipe(Effect.ignore);
-    }
-  });
-
   const uninstall: BootService["Service"]["uninstall"] = Effect.gen(function* () {
     yield* requireSystemdLinux;
-    const exists = yield* fs
-      .exists(unitPath)
-      .pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause })));
-    if (!exists) {
+    if (
+      !(yield* fs
+        .exists(unitPath)
+        .pipe(Effect.mapError((cause) => new BootServiceInstallError({ cause }))))
+    )
       return false;
-    }
     yield* runStep("stopping the service", "systemctl", [
       "--user",
       "disable",
@@ -405,18 +358,32 @@ export const make = Effect.fn("cloud.boot_service.make")(function* (input: {
     if (platform !== "linux" || homeDir === "") {
       return { supported: false, installed: false, current: false, unitPath, logPath };
     }
-    const unitExists = yield* fs.exists(unitPath);
-    if (!unitExists) {
+    if (!(yield* fs.exists(unitPath))) {
       return { supported: true, installed: false, current: false, unitPath, logPath };
     }
-    const unit = yield* fs.readFileString(unitPath);
-    // A unit is current only if it matches what install would write now (an
-    // older CLI wrote a different runtime/node path) AND the entry point it
-    // references still exists (a pinned runtime under ~/.t3 can be deleted to
-    // reclaim space). Either mismatch makes connect offer a repair.
-    const entryExists = yield* fs.exists(plannedEntryPath);
-    const current = unit === renderBootServiceUnit(plan) && entryExists;
-    return { supported: true, installed: true, current, unitPath, logPath };
+    const [unit, launcherExists, runtimeEntryExists, runtimeSentinel, stateText] =
+      yield* Effect.all([
+        fs.readFileString(unitPath),
+        fs.exists(launcherPath),
+        fs.exists(runtimePaths.entryPath),
+        fs.readFileString(runtimePaths.sentinelPath).pipe(Effect.option),
+        fs.readFileString(statePath).pipe(Effect.option),
+      ]);
+    const state = Option.isSome(stateText) ? parseServiceState(stateText.value) : undefined;
+    return {
+      supported: true,
+      installed: true,
+      current:
+        unit === renderBootServiceUnit(plan) &&
+        launcherExists &&
+        runtimeEntryExists &&
+        Option.isSome(runtimeSentinel) &&
+        runtimeSentinel.value.trim() === input.cliVersion &&
+        state?.activeVersion === input.cliVersion &&
+        state?.update?.status !== "pending",
+      unitPath,
+      logPath,
+    };
   }).pipe(
     Effect.mapError((cause) => new BootServiceInstallError({ cause })),
     Effect.withSpan("cloud.boot_service.status"),
diff --git a/apps/server/src/cloud/pinnedRuntime.test.ts b/apps/server/src/cloud/pinnedRuntime.test.ts
index 9b46c0038ec..e6ec99e7e8c 100644
--- a/apps/server/src/cloud/pinnedRuntime.test.ts
+++ b/apps/server/src/cloud/pinnedRuntime.test.ts
@@ -2,8 +2,8 @@ import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, it } from "@effect/vitest";
 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 Fiber from "effect/Fiber";
 import * as Path from "effect/Path";
 import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
 
@@ -11,119 +11,164 @@ import * as ProcessRunner from "../processRunner.ts";
 import {
   ensurePinnedRuntimeInstalled,
   pinnedRuntimePaths,
-  removePinnedRuntimeInstallation,
+  PinnedRuntimeInstallError,
 } from "./pinnedRuntime.ts";
 
+const successfulRunner = (fs: FileSystem.FileSystem, path: Path.Path) =>
+  ProcessRunner.ProcessRunner.of({
+    run: (input) =>
+      Effect.gen(function* () {
+        const prefixIndex = input.args.indexOf("--prefix");
+        const stagingDir = input.args[prefixIndex + 1];
+        if (stagingDir === undefined) return yield* Effect.die("missing npm --prefix");
+        const entry = path.join(stagingDir, "node_modules", "t3", "dist", "bin.mjs");
+        yield* fs.makeDirectory(path.dirname(entry), { recursive: true }).pipe(Effect.orDie);
+        yield* fs.writeFileString(entry, "export {};\n").pipe(Effect.orDie);
+        return {
+          stdout: "",
+          stderr: "",
+          code: ChildProcessSpawner.ExitCode(0),
+          timedOut: false,
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        };
+      }),
+  });
+
 it.layer(NodeServices.layer)("ensurePinnedRuntimeInstalled", (it) => {
-  it.effect("serializes concurrent installs of the same runtime", () =>
+  it.effect("validates a staging tree before atomically publishing it", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
       const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-pinned-runtime-test-" });
-      const installStarted = yield* Deferred.make<void>();
-      const allowInstallToFinish = yield* Deferred.make<void>();
-      const paths = pinnedRuntimePaths(path, baseDir, "0.0.29");
-      let npmRuns = 0;
+      const finalPaths = pinnedRuntimePaths(path, baseDir, "1.2.3");
+      let validatedDirectory = "";
 
-      const runner = ProcessRunner.ProcessRunner.of({
-        run: (_input) =>
+      const installed = yield* ensurePinnedRuntimeInstalled({
+        baseDir,
+        version: "1.2.3",
+        fs,
+        path,
+        runner: successfulRunner(fs, path),
+        validate: (staging) =>
           Effect.gen(function* () {
-            npmRuns += 1;
-            yield* Deferred.succeed(installStarted, undefined);
-            yield* Deferred.await(allowInstallToFinish);
-            yield* fs
-              .makeDirectory(path.dirname(paths.entryPath), { recursive: true })
-              .pipe(Effect.orDie);
-            yield* fs.writeFileString(paths.entryPath, "export {};\n").pipe(Effect.orDie);
-            return {
-              stdout: "",
-              stderr: "",
-              code: ChildProcessSpawner.ExitCode(0),
-              timedOut: false,
-              stdoutTruncated: false,
-              stderrTruncated: false,
-            };
-          }),
+            validatedDirectory = staging.versionDir;
+            assert.isFalse(yield* fs.exists(finalPaths.versionDir));
+            assert.isTrue(yield* fs.exists(staging.entryPath));
+          }).pipe(Effect.orDie),
       });
-      const install = ensurePinnedRuntimeInstalled({
+
+      assert.notEqual(validatedDirectory, finalPaths.versionDir);
+      assert.deepEqual(installed, finalPaths);
+      assert.isTrue(yield* fs.exists(finalPaths.entryPath));
+      assert.equal(yield* fs.readFileString(finalPaths.sentinelPath), "1.2.3\n");
+    }),
+  );
+
+  it.effect("removes staging and leaves no final runtime when validation fails", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-pinned-runtime-test-" });
+      const finalPaths = pinnedRuntimePaths(path, baseDir, "1.2.3");
+
+      yield* ensurePinnedRuntimeInstalled({
         baseDir,
-        version: "0.0.29",
+        version: "1.2.3",
         fs,
         path,
-        runner,
-      });
+        runner: successfulRunner(fs, path),
+        validate: () =>
+          Effect.fail(new PinnedRuntimeInstallError({ step: "validating the staged runtime" })),
+      }).pipe(Effect.flip);
 
-      const first = yield* Effect.forkChild(install, { startImmediately: true });
-      yield* Deferred.await(installStarted);
-      const second = yield* Effect.forkChild(install, { startImmediately: true });
-      yield* Effect.yieldNow;
-      assert.equal(npmRuns, 1);
+      assert.isFalse(yield* fs.exists(finalPaths.versionDir));
+      assert.deepEqual(
+        (yield* fs.readDirectory(path.dirname(finalPaths.versionDir))).filter((entry) =>
+          entry.startsWith(".staging-"),
+        ),
+        [],
+      );
+    }),
+  );
 
-      yield* Deferred.succeed(allowInstallToFinish, undefined);
-      yield* Fiber.join(first);
-      yield* Fiber.join(second);
+  it.effect("replaces an incomplete pinned runtime", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-pinned-runtime-repair-" });
+      const finalPaths = pinnedRuntimePaths(path, baseDir, "1.2.3");
+      yield* fs.makeDirectory(finalPaths.versionDir, { recursive: true });
+      yield* fs.writeFileString(path.join(finalPaths.versionDir, "partial"), "incomplete\n");
 
-      assert.equal(npmRuns, 1);
-      assert.isTrue(yield* fs.exists(paths.sentinelPath));
-      assert.isTrue(yield* fs.exists(paths.entryPath));
+      yield* ensurePinnedRuntimeInstalled({
+        baseDir,
+        version: "1.2.3",
+        fs,
+        path,
+        runner: successfulRunner(fs, path),
+        validate: () => Effect.void,
+      });
+
+      assert.isFalse(yield* fs.exists(path.join(finalPaths.versionDir, "partial")));
+      assert.isTrue(yield* fs.exists(finalPaths.entryPath));
     }),
   );
 
-  it.effect("waits for an active install before removing its runtime", () =>
+  it.effect("preserves a completed runtime when validation fails", () =>
     Effect.gen(function* () {
       const fs = yield* FileSystem.FileSystem;
       const path = yield* Path.Path;
-      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-pinned-runtime-test-" });
-      const installStarted = yield* Deferred.make<void>();
-      const allowInstallToFinish = yield* Deferred.make<void>();
-      const paths = pinnedRuntimePaths(path, baseDir, "0.0.30");
-      const runner = ProcessRunner.ProcessRunner.of({
-        run: (_input) =>
+      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-pinned-runtime-repair-" });
+      const finalPaths = pinnedRuntimePaths(path, baseDir, "1.2.3");
+      yield* fs.makeDirectory(path.dirname(finalPaths.entryPath), { recursive: true });
+      yield* fs.writeFileString(finalPaths.entryPath, "broken\n");
+      yield* fs.writeFileString(finalPaths.sentinelPath, "1.2.3\n");
+
+      let validations = 0;
+      yield* ensurePinnedRuntimeInstalled({
+        baseDir,
+        version: "1.2.3",
+        fs,
+        path,
+        runner: successfulRunner(fs, path),
+        validate: (paths) =>
           Effect.gen(function* () {
-            yield* Deferred.succeed(installStarted, undefined);
-            yield* Deferred.await(allowInstallToFinish);
-            yield* fs
-              .makeDirectory(path.dirname(paths.entryPath), { recursive: true })
-              .pipe(Effect.orDie);
-            yield* fs.writeFileString(paths.entryPath, "export {};\n").pipe(Effect.orDie);
-            return {
-              stdout: "",
-              stderr: "",
-              code: ChildProcessSpawner.ExitCode(0),
-              timedOut: false,
-              stdoutTruncated: false,
-              stderrTruncated: false,
-            };
+            validations += 1;
+            const source = yield* fs.readFileString(paths.entryPath).pipe(Effect.orDie);
+            if (source === "broken\n") {
+              return yield* new PinnedRuntimeInstallError({ step: "validating the runtime" });
+            }
           }),
-      });
+      }).pipe(Effect.flip);
 
-      const installFiber = yield* Effect.forkChild(
-        ensurePinnedRuntimeInstalled({
-          baseDir,
-          version: "0.0.30",
-          fs,
-          path,
-          runner,
-        }),
-        { startImmediately: true },
-      );
-      yield* Deferred.await(installStarted);
-      const removeFiber = yield* Effect.forkChild(
-        removePinnedRuntimeInstallation({
-          baseDir,
-          version: "0.0.30",
-          fs,
-          path,
-        }),
-        { startImmediately: true },
-      );
-      yield* Effect.yieldNow;
-      assert.isTrue(yield* fs.exists(paths.versionDir));
+      assert.equal(validations, 1);
+      assert.equal(yield* fs.readFileString(finalPaths.entryPath), "broken\n");
+    }),
+  );
+
+  it.effect("removes staging when installation is interrupted", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-pinned-runtime-interrupt-" });
+      const started = yield* Deferred.make<void>();
+      const runner = ProcessRunner.ProcessRunner.of({
+        run: () => Deferred.succeed(started, undefined).pipe(Effect.andThen(Effect.never)),
+      });
+      const install = yield* ensurePinnedRuntimeInstalled({
+        baseDir,
+        version: "1.2.3",
+        fs,
+        path,
+        runner,
+        validate: () => Effect.void,
+      }).pipe(Effect.forkScoped);
 
-      yield* Deferred.succeed(allowInstallToFinish, undefined);
-      yield* Fiber.join(installFiber);
-      yield* Fiber.join(removeFiber);
-      assert.isFalse(yield* fs.exists(paths.versionDir));
+      yield* Deferred.await(started);
+      yield* Fiber.interrupt(install);
+      const versionsDir = path.join(baseDir, "runtime", "versions");
+      assert.deepEqual(yield* fs.readDirectory(versionsDir), []);
     }),
   );
 });
diff --git a/apps/server/src/cloud/pinnedRuntime.ts b/apps/server/src/cloud/pinnedRuntime.ts
index e3e095ce081..ba3b380b0ca 100644
--- a/apps/server/src/cloud/pinnedRuntime.ts
+++ b/apps/server/src/cloud/pinnedRuntime.ts
@@ -3,6 +3,7 @@ import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
 import * as Semaphore from "effect/Semaphore";
 
 import * as ProcessRunner from "../processRunner.ts";
@@ -11,15 +12,14 @@ import * as ProcessRunner from "../processRunner.ts";
  * A pinned runtime is an exact `t3@<version>` npm-installed into
  * <baseDir>/runtime/versions/<version>. The boot service points its systemd
  * unit here, and server self-update installs the target version here before
- * switching over — never `npx t3`, whose cache is ephemeral and whose
+ * switching over, never `npx t3`, whose cache is ephemeral and whose
  * registry fetch at boot would make startup depend on the network.
  */
 
 const PINNED_RUNTIME_DIR = "runtime";
 const PINNED_RUNTIME_INSTALL_TIMEOUT = Duration.minutes(10);
-// Boot-service setup and remote self-update share this module but can be
-// constructed in separate layers. Serialize the complete check/install/
-// sentinel transaction across all callers in this process.
+// Boot-service setup and remote update can construct separate layers. Serialize
+// the complete install transaction across every caller in this process.
 const pinnedRuntimeInstallLock = Semaphore.makeUnsafe(1);
 
 export interface PinnedRuntimePaths {
@@ -58,119 +58,165 @@ export class PinnedRuntimeInstallError extends Schema.TaggedErrorClass<PinnedRun
   }
 }
 
+export class PinnedRuntimePreflightBlockedError extends Schema.TaggedErrorClass<PinnedRuntimePreflightBlockedError>()(
+  "PinnedRuntimePreflightBlockedError",
+  {
+    version: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return this.reason;
+  }
+}
+
 /**
  * Installs `t3@<version>` into the pinned runtime directory unless a complete
  * install is already there, and returns its paths. The sentinel is written
- * only after npm exits 0; checking the entry file alone is not enough — npm
+ * only after npm exits 0; checking the entry file alone is not enough. npm
  * extracts files before running native builds (node-pty), so a killed
  * install leaves a plausible-looking but broken tree behind.
  */
-export const ensurePinnedRuntimeInstalled = Effect.fn("cloud.pinned_runtime.ensure_installed")(
-  function* (input: {
-    readonly baseDir: string;
-    readonly version: string;
-    readonly fs: FileSystem.FileSystem;
-    readonly path: Path.Path;
-    readonly runner: ProcessRunner.ProcessRunner["Service"];
-  }) {
-    const { fs, runner } = input;
-    const paths = pinnedRuntimePaths(input.path, input.baseDir, input.version);
+interface PinnedRuntimeInstallInput {
+  readonly baseDir: string;
+  readonly version: string;
+  readonly fs: FileSystem.FileSystem;
+  readonly path: Path.Path;
+  readonly runner: ProcessRunner.ProcessRunner["Service"];
+  readonly validate: (
+    paths: PinnedRuntimePaths,
+  ) => Effect.Effect<void, PinnedRuntimeInstallError | PinnedRuntimePreflightBlockedError>;
+}
+
+const installPinnedRuntime = Effect.fn("cloud.pinned_runtime.ensure_installed")(function* (
+  input: PinnedRuntimeInstallInput,
+) {
+  const { fs, runner } = input;
+  const paths = pinnedRuntimePaths(input.path, input.baseDir, input.version);
+  const [versionDirExists, entryExists, sentinel] = yield* Effect.all([
+    fs.exists(paths.versionDir),
+    fs.exists(paths.entryPath),
+    fs.readFileString(paths.sentinelPath).pipe(Effect.option),
+  ]).pipe(
+    Effect.mapError(
+      (cause) => new PinnedRuntimeInstallError({ step: "checking the pinned runtime", cause }),
+    ),
+  );
+  const alreadyPinned =
+    entryExists && Option.isSome(sentinel) && sentinel.value.trim() === input.version;
+  if (alreadyPinned) {
+    yield* input.validate(paths);
+    return paths;
+  }
+  if (versionDirExists) {
+    yield* fs.remove(paths.versionDir, { recursive: true, force: true }).pipe(
+      Effect.mapError(
+        (cause) =>
+          new PinnedRuntimeInstallError({
+            step: "removing an incomplete pinned runtime",
+            cause,
+          }),
+      ),
+    );
+  }
+
+  const versionsDir = input.path.dirname(paths.versionDir);
+  yield* fs.makeDirectory(versionsDir, { recursive: true }).pipe(
+    Effect.mapError(
+      (cause) =>
+        new PinnedRuntimeInstallError({
+          step: "preparing the pinned runtime directory",
+          cause,
+        }),
+    ),
+  );
+  const stagingDir = yield* fs
+    .makeTempDirectory({
+      directory: versionsDir,
+      prefix: ".staging-",
+    })
+    .pipe(
+      Effect.mapError(
+        (cause) =>
+          new PinnedRuntimeInstallError({
+            step: "preparing the pinned runtime directory",
+            cause,
+          }),
+      ),
+    );
+  const stagingPaths: PinnedRuntimePaths = {
+    versionDir: stagingDir,
+    entryPath: input.path.join(stagingDir, "node_modules", "t3", "dist", "bin.mjs"),
+    sentinelPath: input.path.join(stagingDir, ".install-complete"),
+  };
 
-    return yield* pinnedRuntimeInstallLock.withPermit(
-      Effect.gen(function* () {
-        const alreadyPinned = yield* Effect.all([
-          fs.exists(paths.sentinelPath),
+  return yield* Effect.gen(function* () {
+    const installStep = "installing the pinned t3 runtime (this can take a few minutes)";
+    yield* runner
+      .run({
+        command: "npm",
+        args: ["install", "--prefix", stagingDir, "--no-fund", "--no-audit", `t3@${input.version}`],
+        // Native dependencies may compile from source on slower machines.
+        timeout: PINNED_RUNTIME_INSTALL_TIMEOUT,
+      })
+      .pipe(
+        Effect.mapError((cause) => new PinnedRuntimeInstallError({ step: installStep, cause })),
+        Effect.filterOrFail(
+          (result) => result.code === 0,
+          (result) =>
+            new PinnedRuntimeInstallError({
+              step: installStep,
+              exitCode: Number(result.code),
+              stdoutLength: result.stdout.length,
+              stderrLength: result.stderr.length,
+            }),
+        ),
+      );
+
+    yield* input.validate(stagingPaths);
+    yield* fs
+      .writeFileString(stagingPaths.sentinelPath, `${input.version}\n`)
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new PinnedRuntimeInstallError({ step: "recording the completed install", cause }),
+        ),
+      );
+    const published = yield* fs.rename(stagingDir, paths.versionDir).pipe(
+      Effect.as(true),
+      Effect.catch((cause) =>
+        Effect.all([
           fs.exists(paths.entryPath),
+          fs.readFileString(paths.sentinelPath).pipe(Effect.option),
         ]).pipe(
-          Effect.map(([sentinelExists, entryExists]) => sentinelExists && entryExists),
-          Effect.mapError(
-            (cause) =>
-              new PinnedRuntimeInstallError({ step: "checking the pinned runtime", cause }),
-          ),
-        );
-        if (alreadyPinned) {
-          return paths;
-        }
-
-        yield* fs.remove(paths.versionDir, { recursive: true, force: true }).pipe(
-          Effect.andThen(fs.makeDirectory(paths.versionDir, { recursive: true })),
           Effect.mapError(
-            (cause) =>
+            (checkCause) =>
               new PinnedRuntimeInstallError({
-                step: "preparing the pinned runtime directory",
-                cause,
+                step: "checking a concurrently published pinned runtime",
+                cause: checkCause,
               }),
           ),
-        );
-
-        const installStep = "installing the pinned t3 runtime (this can take a few minutes)";
-        yield* runner
-          .run({
-            command: "npm",
-            args: [
-              "install",
-              "--prefix",
-              paths.versionDir,
-              "--no-fund",
-              "--no-audit",
-              `t3@${input.version}`,
-            ],
-            // Native deps (node-pty) can compile from source on slow boxes; the
-            // ProcessRunner default of 60s would kill a healthy install.
-            timeout: PINNED_RUNTIME_INSTALL_TIMEOUT,
-          })
-          .pipe(
-            Effect.mapError((cause) => new PinnedRuntimeInstallError({ step: installStep, cause })),
-            Effect.filterOrFail(
-              (result) => result.code === 0,
-              (result) =>
-                new PinnedRuntimeInstallError({
-                  step: installStep,
-                  exitCode: Number(result.code),
-                  stdoutLength: result.stdout.length,
-                  stderrLength: result.stderr.length,
-                }),
-            ),
-            Effect.tapError(() =>
-              fs.remove(paths.versionDir, { recursive: true, force: true }).pipe(Effect.ignore),
-            ),
-          );
-
-        yield* fs
-          .writeFileString(paths.sentinelPath, `${input.version}\n`)
-          .pipe(
-            Effect.mapError(
-              (cause) =>
-                new PinnedRuntimeInstallError({ step: "recording the completed install", cause }),
-            ),
-          );
-
-        return paths;
-      }),
-    );
-  },
-);
-
-/** Removes one pinned runtime while holding the same process-wide lock used
- * by install/check/sentinel work, so cleanup cannot race another caller that
- * is materializing or reusing the runtime tree. */
-export const removePinnedRuntimeInstallation = Effect.fn("cloud.pinned_runtime.remove")(
-  function* (input: {
-    readonly baseDir: string;
-    readonly version: string;
-    readonly fs: FileSystem.FileSystem;
-    readonly path: Path.Path;
-  }) {
-    const paths = pinnedRuntimePaths(input.path, input.baseDir, input.version);
-    yield* pinnedRuntimeInstallLock.withPermit(
-      input.fs
-        .remove(paths.versionDir, { recursive: true, force: true })
-        .pipe(
-          Effect.mapError(
-            (cause) =>
-              new PinnedRuntimeInstallError({ step: "removing the pinned runtime", cause }),
+          Effect.flatMap(([publishedEntryExists, publishedSentinel]) =>
+            publishedEntryExists &&
+            Option.isSome(publishedSentinel) &&
+            publishedSentinel.value.trim() === input.version
+              ? Effect.succeed(false)
+              : Effect.fail(
+                  new PinnedRuntimeInstallError({
+                    step: "publishing the pinned runtime",
+                    cause,
+                  }),
+                ),
           ),
         ),
+      ),
     );
-  },
-);
+    if (!published) yield* input.validate(paths);
+    return paths;
+  }).pipe(
+    Effect.ensuring(fs.remove(stagingDir, { recursive: true, force: true }).pipe(Effect.ignore)),
+  );
+});
+
+export const ensurePinnedRuntimeInstalled = (input: PinnedRuntimeInstallInput) =>
+  pinnedRuntimeInstallLock.withPermit(installPinnedRuntime(input));
diff --git a/apps/server/src/cloud/selfUpdate.test.ts b/apps/server/src/cloud/selfUpdate.test.ts
index 655228c047f..6fe1d5a4a3c 100644
--- a/apps/server/src/cloud/selfUpdate.test.ts
+++ b/apps/server/src/cloud/selfUpdate.test.ts
@@ -1,624 +1,144 @@
 import * as NodeServices from "@effect/platform-node/NodeServices";
-import { assert, it } from "@effect/vitest";
-import * as Duration from "effect/Duration";
+import { expect, it } from "@effect/vitest";
+import { HostProcessExecutablePath } from "@t3tools/shared/hostProcess";
+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 Fiber from "effect/Fiber";
 import * as Path from "effect/Path";
-import * as TestClock from "effect/testing/TestClock";
 import * as ChildProcessSpawner from "effect/unstable/process/ChildProcessSpawner";
 
-import {
-  HostProcessArguments,
-  HostProcessEnvironment,
-  HostProcessExecutablePath,
-  HostProcessPlatform,
-} from "@t3tools/shared/hostProcess";
-
 import * as ServerConfig from "../config.ts";
 import * as ProcessRunner from "../processRunner.ts";
-import {
-  BOOT_SERVICE_UNIT_ENV,
-  BOOT_SERVICE_UNIT_FILE,
-  renderBootServiceUnit,
-} from "./bootService.ts";
-import * as SelfUpdate from "./selfUpdate.ts";
-
-const NODE_PATH = "/usr/local/bin/node";
+import * as ServiceLauncherClient from "./serviceLauncherClient.ts";
+import * as ServerSelfUpdate from "./selfUpdate.ts";
+
+interface HarnessOptions {
+  readonly mode?: "web" | "desktop";
+  readonly managed?: boolean;
+  readonly preflight?: "ready" | "blocked";
+  readonly requestUpdate?: ServiceLauncherClient.ServiceLauncherClient["Service"]["requestUpdate"];
+}
 
-const eventuallyFileString = Effect.fn("test.eventuallyFileString")(function* (
-  filePath: string,
-  expected: string,
+const makeHarness = Effect.fn("test.make_self_update_harness")(function* (
+  options: HarnessOptions = {},
 ) {
   const fs = yield* FileSystem.FileSystem;
-  for (let iteration = 0; iteration < 1_000; iteration += 1) {
-    const contents = yield* fs.readFileString(filePath);
-    if (contents === expected) {
-      return;
-    }
-    // The rollback performs real filesystem I/O on a detached fiber, which
-    // advancing TestClock does not await.
-    yield* Effect.yieldNow;
-  }
-  return yield* Effect.die(new Error(`Expected file contents were not observed at ${filePath}.`));
-});
-
-const eventuallyTrue = Effect.fn("test.eventuallyTrue")(function* (predicate: () => boolean) {
-  for (let iteration = 0; iteration < 1_000; iteration += 1) {
-    if (predicate()) {
-      return;
-    }
-    yield* Effect.yieldNow;
-  }
-  return yield* Effect.die(new Error("Expected condition was not observed."));
-});
-
-interface RecordedCommand {
-  readonly command: string;
-  readonly args: ReadonlyArray<string>;
-}
-
-const makeRecordingRunnerLayer = (
-  commands: Array<RecordedCommand>,
-  options?: {
-    readonly failWhen?: ((command: string, args: ReadonlyArray<string>) => boolean) | undefined;
-    readonly stdoutFor?:
-      | ((command: string, args: ReadonlyArray<string>) => string | undefined)
-      | undefined;
-  },
-) =>
-  Layer.succeed(
-    ProcessRunner.ProcessRunner,
-    ProcessRunner.ProcessRunner.of({
-      run: (input) =>
-        Effect.sync(() => {
-          commands.push({ command: input.command, args: input.args });
-          const failed = options?.failWhen?.(input.command, input.args) === true;
-          const versionFromPath =
-            input.command === NODE_PATH && input.args[1] === "--version"
-              ? /[/\\]runtime[/\\]versions[/\\]([^/\\]+)/.exec(input.args[0] ?? "")?.[1]
-              : undefined;
+  const path = yield* Path.Path;
+  const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-self-update-test-" });
+  const order: string[] = [];
+  const runner = ProcessRunner.ProcessRunner.of({
+    run: (input) =>
+      Effect.gen(function* () {
+        if (input.command === "npm") {
+          order.push("install");
+          const prefix = input.args[input.args.indexOf("--prefix") + 1];
+          if (prefix === undefined) return yield* Effect.die("missing npm prefix");
+          const entry = path.join(prefix, "node_modules", "t3", "dist", "bin.mjs");
+          yield* fs.makeDirectory(path.dirname(entry), { recursive: true }).pipe(Effect.orDie);
+          yield* fs.writeFileString(entry, "export {};\n").pipe(Effect.orDie);
           return {
-            stdout:
-              options?.stdoutFor?.(input.command, input.args) ??
-              (versionFromPath === undefined ? "" : `t3 v${versionFromPath}\n`),
-            stderr: failed ? `${input.command} exploded` : "",
-            code: ChildProcessSpawner.ExitCode(failed ? 1 : 0),
+            stdout: "",
+            stderr: "",
+            code: ChildProcessSpawner.ExitCode(0),
             timedOut: false,
             stdoutTruncated: false,
             stderrTruncated: false,
           };
-        }),
-    }),
-  );
-
-const provideHostRefs = (input: {
-  readonly platform: NodeJS.Platform;
-  readonly env: NodeJS.ProcessEnv;
-  readonly entryPath: string;
-}) =>
-  Effect.provide(
-    Layer.mergeAll(
-      Layer.succeed(HostProcessPlatform, input.platform),
-      Layer.succeed(HostProcessEnvironment, input.env),
-      Layer.succeed(HostProcessExecutablePath, NODE_PATH),
-      Layer.succeed(HostProcessArguments, [NODE_PATH, input.entryPath, "serve"]),
-    ),
-  );
-
-it("recognizes published npm artifacts as swappable entry points", () => {
-  assert.isTrue(SelfUpdate.isPublishedCliEntry("/usr/local/lib/node_modules/t3/dist/bin.mjs"));
-  assert.isTrue(
-    SelfUpdate.isPublishedCliEntry("/home/theo/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs"),
-  );
-  assert.isTrue(
-    SelfUpdate.isPublishedCliEntry(
-      "C:\\Users\\theo\\AppData\\Roaming\\npm\\node_modules\\t3\\dist\\bin.mjs",
-    ),
-  );
-  // Dev checkouts and the desktop bundle run apps/server/dist directly.
-  assert.isFalse(SelfUpdate.isPublishedCliEntry("/home/theo/dev/t3/apps/server/dist/bin.mjs"));
-  assert.isFalse(SelfUpdate.isPublishedCliEntry(""));
-});
-
-it.layer(NodeServices.layer)("resolveServerSelfUpdateCapability", (it) => {
-  const makeHome = Effect.fn("test.makeHome")(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const home = yield* fs.makeTempDirectoryScoped({ prefix: "t3-self-update-test-" });
-    return { fs, path, home };
-  });
-
-  const writeUnitReferencing = Effect.fn("test.writeUnitReferencing")(function* (
-    home: string,
-    entryPath: string,
-  ) {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const unitDir = path.join(home, ".config", "systemd", "user");
-    yield* fs.makeDirectory(unitDir, { recursive: true });
-    yield* fs.writeFileString(
-      path.join(unitDir, "t3code.service"),
-      renderBootServiceUnit({
-        nodePath: NODE_PATH,
-        t3EntryPath: entryPath,
-        baseDir: path.join(home, ".t3"),
-        logPath: path.join(home, ".t3", "userdata", "logs", "boot-service.log"),
-        unitPath: path.join(unitDir, "t3code.service"),
+        }
+        order.push("preflight");
+        const result =
+          options.preflight === "blocked"
+            ? { status: "blocked", version: "1.1.0", reason: "local update required" }
+            : { status: "ready", version: "1.1.0", launcherProtocol: 1 };
+        return {
+          // @effect-diagnostics-next-line preferSchemaOverJson:off - fake child-process stdout.
+          stdout: JSON.stringify(result),
+          stderr: "",
+          code: ChildProcessSpawner.ExitCode(0),
+          timedOut: false,
+          stdoutTruncated: false,
+          stderrTruncated: false,
+        };
       }),
-    );
   });
-
-  it.effect("reports boot-service for the systemd-spawned unit process", () =>
-    Effect.gen(function* () {
-      const { home, path } = yield* makeHome();
-      const entryPath = path.join(home, ".t3/runtime/versions/0.0.28/node_modules/t3/dist/bin.mjs");
-      yield* writeUnitReferencing(home, entryPath);
-      const method = yield* SelfUpdate.resolveServerSelfUpdateCapability({
-        desktopManaged: false,
-      }).pipe(
-        provideHostRefs({
-          platform: "linux",
-          env: {
-            HOME: home,
-            INVOCATION_ID: "abc123",
-            [BOOT_SERVICE_UNIT_ENV]: BOOT_SERVICE_UNIT_FILE,
-          },
-          entryPath,
-        }),
-      );
-      assert.equal(method, "boot-service");
-    }),
-  );
-
-  it.effect("does not claim a systemd process owned by another unit", () =>
-    Effect.gen(function* () {
-      const { home, path } = yield* makeHome();
-      const entryPath = path.join(home, ".t3/runtime/versions/0.0.28/node_modules/t3/dist/bin.mjs");
-      yield* writeUnitReferencing(home, entryPath);
-      const method = yield* SelfUpdate.resolveServerSelfUpdateCapability({
-        desktopManaged: false,
-      }).pipe(
-        provideHostRefs({
-          platform: "linux",
-          env: { HOME: home, INVOCATION_ID: "abc123" },
-          entryPath,
-        }),
-      );
-      assert.isNull(method);
-    }),
-  );
-
-  it.effect("reports respawn for a manual run of the pinned artifact", () =>
-    Effect.gen(function* () {
-      const { home, path } = yield* makeHome();
-      const entryPath = path.join(home, ".t3/runtime/versions/0.0.28/node_modules/t3/dist/bin.mjs");
-      yield* writeUnitReferencing(home, entryPath);
-      // Same unit on disk, but no INVOCATION_ID: restarting the unit would
-      // not replace this process, so it must respawn itself instead.
-      const method = yield* SelfUpdate.resolveServerSelfUpdateCapability({
-        desktopManaged: false,
-      }).pipe(provideHostRefs({ platform: "linux", env: { HOME: home }, entryPath }));
-      assert.equal(method, "respawn");
-    }),
-  );
-
-  it.effect("reports respawn for a foreground npx artifact on darwin", () =>
-    Effect.gen(function* () {
-      const { home } = yield* makeHome();
-      const method = yield* SelfUpdate.resolveServerSelfUpdateCapability({
-        desktopManaged: false,
-      }).pipe(
-        provideHostRefs({
-          platform: "darwin",
-          env: { HOME: home },
-          entryPath: `${home}/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs`,
-        }),
-      );
-      assert.equal(method, "respawn");
-    }),
-  );
-
-  it.effect("reports desktop-managed for desktop-supervised backends", () =>
-    Effect.gen(function* () {
-      const { home, path } = yield* makeHome();
-      // Desktop ownership wins over every process-shape heuristic: even a
-      // systemd-looking pinned artifact belongs to the app that spawned it.
-      const entryPath = path.join(home, ".t3/runtime/versions/0.0.28/node_modules/t3/dist/bin.mjs");
-      yield* writeUnitReferencing(home, entryPath);
-      const method = yield* SelfUpdate.resolveServerSelfUpdateCapability({
-        desktopManaged: true,
-      }).pipe(
-        provideHostRefs({
-          platform: "linux",
-          env: {
-            HOME: home,
-            INVOCATION_ID: "abc123",
-            [BOOT_SERVICE_UNIT_ENV]: BOOT_SERVICE_UNIT_FILE,
-          },
-          entryPath,
-        }),
-      );
-      assert.equal(method, "desktop-managed");
-    }),
-  );
-
-  it.effect("reports no method for dev checkouts and Windows", () =>
-    Effect.gen(function* () {
-      const { home } = yield* makeHome();
-      const devMethod = yield* SelfUpdate.resolveServerSelfUpdateCapability({
-        desktopManaged: false,
-      }).pipe(
-        provideHostRefs({
-          platform: "darwin",
-          env: { HOME: home },
-          entryPath: `${home}/dev/t3/apps/server/dist/bin.mjs`,
-        }),
-      );
-      assert.isNull(devMethod);
-      const windowsMethod = yield* SelfUpdate.resolveServerSelfUpdateCapability({
-        desktopManaged: false,
-      }).pipe(
-        provideHostRefs({
-          platform: "win32",
-          env: { HOME: home },
-          entryPath: "C:\\Users\\theo\\AppData\\Roaming\\npm\\node_modules\\t3\\dist\\bin.mjs",
-        }),
-      );
-      assert.isNull(windowsMethod);
-    }),
-  );
-});
-
-it.layer(NodeServices.layer)("ServerSelfUpdate.update", (it) => {
-  interface RecordedSpawn {
-    readonly command: string;
-    readonly args: ReadonlyArray<string>;
-  }
-
-  const makeContext = Effect.fn("test.makeContext")(function* (options?: {
-    readonly platform?: NodeJS.Platform;
-    readonly bootService?: boolean;
-    readonly desktopManaged?: boolean;
-    readonly entryPath?: string;
-    readonly failWhen?: (command: string, args: ReadonlyArray<string>) => boolean;
-    readonly stdoutFor?: (command: string, args: ReadonlyArray<string>) => string | undefined;
-    readonly failSpawn?: boolean;
-  }) {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const home = yield* fs.makeTempDirectoryScoped({ prefix: "t3-self-update-test-" });
-    const baseDir = path.join(home, ".t3");
-    const entryPath =
-      options?.entryPath ??
-      path.join(home, ".t3/runtime/versions/0.0.28/node_modules/t3/dist/bin.mjs");
-    const env: NodeJS.ProcessEnv =
-      options?.bootService === true
-        ? {
-            HOME: home,
-            INVOCATION_ID: "abc123",
-            [BOOT_SERVICE_UNIT_ENV]: BOOT_SERVICE_UNIT_FILE,
-          }
-        : { HOME: home };
-    if (options?.bootService === true) {
-      const unitDir = path.join(home, ".config", "systemd", "user");
-      yield* fs.makeDirectory(unitDir, { recursive: true });
-      yield* fs.writeFileString(
-        path.join(unitDir, "t3code.service"),
-        renderBootServiceUnit({
-          nodePath: NODE_PATH,
-          t3EntryPath: entryPath,
-          baseDir,
-          logPath: path.join(baseDir, "userdata", "logs", "boot-service.log"),
-          unitPath: path.join(unitDir, "t3code.service"),
-        }),
-      );
-    }
-
-    const commands: Array<RecordedCommand> = [];
-    const spawns: Array<RecordedSpawn> = [];
-    let exited = 0;
-    // layerTest always reports mode "web"; desktop-managed contexts overlay
-    // the mode the desktop app's bootstrap envelope would set.
-    const configLayer =
-      options?.desktopManaged === true
-        ? Layer.effect(
-            ServerConfig.ServerConfig,
-            Effect.gen(function* () {
-              const config = yield* ServerConfig.ServerConfig;
-              return { ...config, mode: "desktop" as const };
-            }),
-          ).pipe(Layer.provide(ServerConfig.layerTest(home, baseDir)))
-        : ServerConfig.layerTest(home, baseDir);
-    const service = yield* SelfUpdate.make({
-      host: {
-        spawnDetached: (command, args) =>
-          Effect.sync(() => spawns.push({ command, args })).pipe(
-            Effect.andThen(
-              options?.failSpawn === true
-                ? Effect.fail(
-                    new ProcessRunner.ProcessSpawnError({
-                      command,
-                      argumentCount: args.length,
-                      cause: new Error("detached spawn failed"),
-                    }),
-                  )
-                : Effect.void,
-            ),
-          ),
-        exitProcess: () => {
-          exited += 1;
-        },
-      },
-    }).pipe(
-      Effect.provide(
-        Layer.mergeAll(
-          makeRecordingRunnerLayer(commands, {
-            failWhen: options?.failWhen,
-            stdoutFor: options?.stdoutFor,
-          }),
-          configLayer,
-        ),
-      ),
-      provideHostRefs({ platform: options?.platform ?? "linux", env, entryPath }),
-    );
-    return {
-      fs,
-      path,
-      home,
-      baseDir,
-      entryPath,
-      commands,
-      spawns,
-      exitCount: () => exited,
-      service,
-    };
+  const launcher = ServiceLauncherClient.ServiceLauncherClient.of({
+    managed: options.managed ?? true,
+    trial: false,
+    requestUpdate:
+      options.requestUpdate ??
+      (() =>
+        Effect.sync(() => {
+          order.push("accept");
+          return "launcher-id";
+        })),
+    prepareTrial: Effect.sync((): undefined => undefined),
   });
-
-  it.effect("rejects dist-tags and other non-exact versions", () =>
-    Effect.gen(function* () {
-      const context = yield* makeContext();
-      const error = yield* context.service.update({ targetVersion: "latest" }).pipe(Effect.flip);
-      assert.include(error.reason, "not an exact t3 version");
-      assert.lengthOf(context.commands, 0);
-    }),
+  const config = yield* ServerConfig.ServerConfig.pipe(
+    Effect.provide(ServerConfig.layerTest(process.cwd(), baseDir)),
   );
-
-  it.effect("refuses to update a desktop-managed backend and points at the app", () =>
-    Effect.gen(function* () {
-      const context = yield* makeContext({ desktopManaged: true, bootService: true });
-      const error = yield* context.service.update({ targetVersion: "0.0.29" }).pipe(Effect.flip);
-      assert.include(error.reason, "desktop app");
-      assert.lengthOf(context.commands, 0);
-      assert.lengthOf(context.spawns, 0);
-    }),
+  const selfUpdate = yield* ServerSelfUpdate.make().pipe(
+    Effect.provideService(ProcessRunner.ProcessRunner, runner),
+    Effect.provideService(ServiceLauncherClient.ServiceLauncherClient, launcher),
+    Effect.provideService(HostProcessExecutablePath, "/usr/bin/node"),
+    Effect.provide(ServerConfig.layer({ ...config, mode: options.mode ?? "web" })),
   );
+  return { selfUpdate, order };
+});
 
-  it.effect("fails without touching anything when no update method applies", () =>
+it.layer(NodeServices.layer)("server self update", (it) => {
+  it.effect("stages and preflights before asking the launcher for an update ID", () =>
     Effect.gen(function* () {
-      const context = yield* makeContext({
-        entryPath: "/home/theo/dev/t3/apps/server/dist/bin.mjs",
+      const { selfUpdate, order } = yield* makeHarness();
+      expect(yield* selfUpdate.update({ targetVersion: "1.1.0" })).toEqual({
+        targetVersion: "1.1.0",
+        method: "boot-service",
+        updateId: "launcher-id",
       });
-      const error = yield* context.service.update({ targetVersion: "0.0.29" }).pipe(Effect.flip);
-      assert.include(error.reason, "cannot update itself");
-      assert.lengthOf(context.commands, 0);
+      expect(order).toEqual(["install", "preflight", "accept"]);
     }),
   );
 
-  it.effect("surfaces a failed npm install and never schedules a restart", () =>
-    Effect.gen(function* () {
-      const context = yield* makeContext({ failWhen: (command) => command === "npm" });
-      const error = yield* context.service.update({ targetVersion: "0.0.29" }).pipe(Effect.flip);
-      assert.equal(error.reason, "Could not install the requested t3 version.");
-      yield* TestClock.adjust(Duration.seconds(10));
-      assert.lengthOf(context.spawns, 0);
-      assert.equal(context.exitCount(), 0);
-    }).pipe(Effect.provide(TestClock.layer())),
-  );
-
-  it.effect("reinstalls the same version after a failed preflight", () =>
-    Effect.gen(function* () {
-      let preflightAttempts = 0;
-      const context = yield* makeContext({
-        failWhen: (command) => {
-          if (command !== NODE_PATH) return false;
-          preflightAttempts += 1;
-          return preflightAttempts === 1;
-        },
-      });
-      const versionDir = context.path.join(context.baseDir, "runtime", "versions", "0.0.29");
-      const entryPath = context.path.join(versionDir, "node_modules", "t3", "dist", "bin.mjs");
-      yield* context.fs.makeDirectory(context.path.dirname(entryPath), { recursive: true });
-      yield* context.fs.writeFileString(entryPath, "export {};\n");
-      yield* context.fs.writeFileString(
-        context.path.join(versionDir, ".install-complete"),
-        "0.0.29\n",
-      );
-
-      const firstError = yield* context.service
-        .update({ targetVersion: "0.0.29" })
-        .pipe(Effect.flip);
-      assert.include(firstError.reason, "failed its version check");
-      assert.isFalse(yield* context.fs.exists(versionDir));
-
-      const result = yield* context.service.update({ targetVersion: "0.0.29" });
-      assert.deepEqual(result, { targetVersion: "0.0.29", method: "respawn" });
-      assert.deepEqual(
-        context.commands.map((entry) => entry.command),
-        [NODE_PATH, "npm", NODE_PATH],
-      );
-    }).pipe(Effect.provide(TestClock.layer())),
-  );
-
-  it.effect("rejects and removes an installed runtime that reports the wrong version", () =>
+  it.effect("rejects invalid versions and desktop-managed servers before staging", () =>
     Effect.gen(function* () {
-      const context = yield* makeContext({
-        stdoutFor: (command, args) =>
-          command === NODE_PATH && args[1] === "--version" ? "t3 v0.0.28\n" : undefined,
-      });
-      const versionDir = context.path.join(context.baseDir, "runtime", "versions", "0.0.29");
-
-      const error = yield* context.service.update({ targetVersion: "0.0.29" }).pipe(Effect.flip);
-
-      assert.include(error.reason, "did not report the requested");
-      assert.isFalse(yield* context.fs.exists(versionDir));
-      assert.lengthOf(context.spawns, 0);
+      const web = yield* makeHarness();
+      expect(
+        (yield* web.selfUpdate.update({ targetVersion: "latest" }).pipe(Effect.flip)).reason,
+      ).toBe("'latest' is not an exact t3 version.");
+      const desktop = yield* makeHarness({ mode: "desktop" });
+      expect(
+        (yield* desktop.selfUpdate.update({ targetVersion: "1.1.0" }).pipe(Effect.flip)).reason,
+      ).toContain("desktop app");
+      expect([...web.order, ...desktop.order]).toEqual([]);
     }),
   );
 
-  it.effect("reports a detached replacement spawn failure and leaves updates retryable", () =>
+  it.effect("preserves the preflight refusal reason", () =>
     Effect.gen(function* () {
-      const context = yield* makeContext({ failSpawn: true });
-
-      const first = yield* context.service.update({ targetVersion: "0.0.29" }).pipe(Effect.flip);
-      assert.include(first.reason, "Could not start the replacement");
-
-      const second = yield* context.service.update({ targetVersion: "0.0.29" }).pipe(Effect.flip);
-      assert.include(second.reason, "Could not start the replacement");
-      assert.notInclude(second.reason, "already in progress");
-      assert.lengthOf(context.spawns, 2);
-      assert.equal(context.exitCount(), 0);
-    }),
-  );
-
-  it.effect("installs, preflights, and respawns a foreground server", () =>
-    Effect.gen(function* () {
-      const context = yield* makeContext();
-      const progress: Array<string> = [];
-      const result = yield* context.service.update({ targetVersion: "0.0.29" }, (stage) =>
-        Effect.sync(() => progress.push(stage)),
-      );
-      assert.deepEqual(result, { targetVersion: "0.0.29", method: "respawn" });
-      assert.deepEqual(progress, ["downloading", "installing"]);
-      assert.lengthOf(context.spawns, 1);
-
-      const concurrentError = yield* context.service
-        .update({ targetVersion: "0.0.30" })
-        .pipe(Effect.flip);
-      assert.include(concurrentError.reason, "already in progress");
-
-      const pinnedEntry = context.path.join(
-        context.baseDir,
-        "runtime/versions/0.0.29/node_modules/t3/dist/bin.mjs",
-      );
-      assert.deepEqual(
-        context.commands.map((entry) => [entry.command, ...entry.args].join(" ")),
-        [
-          `npm install --prefix ${context.path.join(context.baseDir, "runtime/versions/0.0.29")} --no-fund --no-audit t3@0.0.29`,
-          `${NODE_PATH} ${pinnedEntry} --version`,
-        ],
-      );
-
-      // The restart is deferred so the RPC acknowledgement flushes first.
-      yield* TestClock.adjust(Duration.seconds(10));
-      assert.lengthOf(context.spawns, 1);
-      const spawn = context.spawns[0];
-      assert.equal(spawn?.command, "/bin/sh");
-      assert.include(spawn?.args ?? [], pinnedEntry);
-      // The replacement replays the original CLI arguments.
-      assert.include(spawn?.args ?? [], "serve");
-      assert.equal(context.exitCount(), 1);
-    }).pipe(Effect.provide(TestClock.layer())),
-  );
-
-  it.effect("rewrites the systemd unit and restarts the boot service", () =>
-    Effect.gen(function* () {
-      const context = yield* makeContext({ bootService: true });
-      const result = yield* context.service.update({ targetVersion: "0.0.29" });
-      assert.deepEqual(result, { targetVersion: "0.0.29", method: "boot-service" });
-
-      const pinnedEntry = context.path.join(
-        context.baseDir,
-        "runtime/versions/0.0.29/node_modules/t3/dist/bin.mjs",
+      const { selfUpdate } = yield* makeHarness({ preflight: "blocked" });
+      expect((yield* selfUpdate.update({ targetVersion: "1.1.0" }).pipe(Effect.flip)).reason).toBe(
+        "local update required",
       );
-      const unit = yield* context.fs.readFileString(
-        context.path.join(context.home, ".config", "systemd", "user", "t3code.service"),
-      );
-      assert.include(unit, `ExecStart=${NODE_PATH} ${pinnedEntry} serve`);
-      assert.deepEqual(
-        context.commands.map((entry) => entry.command),
-        ["npm", NODE_PATH, "systemctl"],
-      );
-      assert.deepEqual(context.commands[2]?.args, ["--user", "daemon-reload"]);
-
-      // Restart waits until after the update acknowledgement can flush.
-      yield* TestClock.adjust(Duration.seconds(10));
-      assert.deepEqual(context.commands[3], {
-        command: "systemctl",
-        args: ["--user", "restart", "t3code.service"],
-      });
-      assert.lengthOf(context.spawns, 0);
-      // systemd replaces the process; the server must not exit itself.
-      assert.equal(context.exitCount(), 0);
-    }).pipe(Effect.provide(TestClock.layer())),
+    }),
   );
 
-  it.effect("restores the previous unit and permits a retry when systemd restart fails", () =>
+  it.effect("allows only one update at a time", () =>
     Effect.gen(function* () {
-      let failRestart = true;
-      const context = yield* makeContext({
-        bootService: true,
-        failWhen: (command, args) => {
-          if (command !== "systemctl" || args[1] !== "restart" || !failRestart) {
-            return false;
-          }
-          failRestart = false;
-          return true;
-        },
+      const requested = yield* Deferred.make<void>();
+      const accepted = yield* Deferred.make<string>();
+      const { selfUpdate } = yield* makeHarness({
+        requestUpdate: () =>
+          Deferred.succeed(requested, undefined).pipe(Effect.andThen(Deferred.await(accepted))),
       });
-      const unitPath = context.path.join(
-        context.home,
-        ".config",
-        "systemd",
-        "user",
-        BOOT_SERVICE_UNIT_FILE,
-      );
-      const previousUnit = yield* context.fs.readFileString(unitPath);
-
-      const first = yield* context.service.update({ targetVersion: "0.0.29" });
-      assert.deepEqual(first, { targetVersion: "0.0.29", method: "boot-service" });
-      yield* TestClock.adjust(Duration.seconds(10));
-      yield* eventuallyFileString(unitPath, previousUnit);
-      yield* eventuallyTrue(() => context.commands.at(-1)?.args[1] === "daemon-reload");
-      assert.deepEqual(
-        context.commands.slice(-2).map((entry) => entry.args),
-        [
-          ["--user", "restart", BOOT_SERVICE_UNIT_FILE],
-          ["--user", "daemon-reload"],
-        ],
-      );
-
-      const retry = yield* context.service.update({ targetVersion: "0.0.30" });
-      assert.deepEqual(retry, { targetVersion: "0.0.30", method: "boot-service" });
-    }).pipe(Effect.provide(TestClock.layer())),
-  );
-
-  it.effect("restores the previous systemd unit when daemon-reload fails", () =>
-    Effect.gen(function* () {
-      const context = yield* makeContext({
-        bootService: true,
-        failWhen: (command) => command === "systemctl",
+      const first = yield* Effect.forkChild(selfUpdate.update({ targetVersion: "1.1.0" }), {
+        startImmediately: true,
       });
-      const unitPath = context.path.join(
-        context.home,
-        ".config",
-        "systemd",
-        "user",
-        BOOT_SERVICE_UNIT_FILE,
-      );
-      const previousUnit = yield* context.fs.readFileString(unitPath);
-
-      const error = yield* context.service.update({ targetVersion: "0.0.29" }).pipe(Effect.flip);
-      assert.include(error.reason, "Reloading systemd units failed");
-      assert.equal(yield* context.fs.readFileString(unitPath), previousUnit);
-      assert.deepEqual(
-        context.commands.map((entry) => entry.command),
-        ["npm", NODE_PATH, "systemctl", "systemctl"],
+      yield* Deferred.await(requested);
+      expect((yield* selfUpdate.update({ targetVersion: "1.1.1" }).pipe(Effect.flip)).reason).toBe(
+        "A server update is already in progress.",
       );
-
-      yield* TestClock.adjust(Duration.seconds(10));
-      assert.lengthOf(context.spawns, 0);
-      assert.equal(context.exitCount(), 0);
-    }).pipe(Effect.provide(TestClock.layer())),
+      yield* Deferred.succeed(accepted, "launcher-id");
+      expect((yield* Fiber.join(first)).updateId).toBe("launcher-id");
+    }),
   );
 });
diff --git a/apps/server/src/cloud/selfUpdate.ts b/apps/server/src/cloud/selfUpdate.ts
index f786cbea8cf..58bb8411730 100644
--- a/apps/server/src/cloud/selfUpdate.ts
+++ b/apps/server/src/cloud/selfUpdate.ts
@@ -1,7 +1,3 @@
-// @effect-diagnostics nodeBuiltinImport:off
-// node:child_process directly: the foreground-server replacement must be a
-// detached fire-and-forget child that outlives this process, while Effect's
-// ChildProcessSpawner ties every child to a scope that kills it.
 import {
   ServerSelfUpdateError,
   type ServerSelfUpdateCapability,
@@ -9,13 +5,7 @@ import {
   type ServerSelfUpdateProgressStage,
   type ServerSelfUpdateResult,
 } from "@t3tools/contracts";
-import {
-  HostProcessArguments,
-  HostProcessEnvironment,
-  HostProcessExecutablePath,
-  HostProcessPlatform,
-} from "@t3tools/shared/hostProcess";
-import * as NodeChildProcess from "node:child_process";
+import { HostProcessExecutablePath } from "@t3tools/shared/hostProcess";
 import * as Context from "effect/Context";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
@@ -25,208 +15,52 @@ import * as Path from "effect/Path";
 import * as Ref from "effect/Ref";
 
 import * as ServerConfig from "../config.ts";
-import { writeFileStringAtomically } from "../atomicWrite.ts";
 import * as ProcessRunner from "../processRunner.ts";
 import {
-  BOOT_SERVICE_UNIT_ENV,
-  BOOT_SERVICE_UNIT_FILE,
-  quoteSystemdValue,
-  renderBootServiceUnit,
-} from "./bootService.ts";
-import { ensurePinnedRuntimeInstalled, removePinnedRuntimeInstallation } from "./pinnedRuntime.ts";
-
-/**
- * Lets a connected client replace this server with another published `t3`
- * version over RPC — the only update path that works when the user is not at
- * the machine (phone against a home server, relay-managed box). The target
- * version is npm-installed into the pinned runtime and verified before
- * anything restarts, so a failed install leaves the running server untouched.
- */
+  ensurePinnedRuntimeInstalled,
+  PinnedRuntimeInstallError,
+  PinnedRuntimePreflightBlockedError,
+} from "./pinnedRuntime.ts";
+import { decodeServicePreflightResult } from "./servicePreflight.ts";
+import * as ServiceLauncherClient from "./serviceLauncherClient.ts";
+import { isExactServiceVersion, SERVICE_LAUNCHER_PROTOCOL } from "./serviceProtocol.ts";
 
 const PREFLIGHT_TIMEOUT = Duration.seconds(30);
-/** Grace between acknowledging the RPC and killing the process, so the
-    response (and its relay hop) flushes before the socket drops. */
-const RESTART_DELAY = Duration.seconds(2);
-
-/** Exact npm versions only — never dist-tags — so the acknowledgement names
-    the version that was actually installed. Also keeps the value safe to
-    pass to npm and embed in filesystem paths. */
-const EXACT_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
-
-export interface ServerSelfUpdateHost {
-  readonly execPath: string;
-  readonly cliEntryPath: string;
-  /** Original CLI arguments after the entry path, replayed on respawn. */
-  readonly cliArgs: ReadonlyArray<string>;
-  /** Resolves once the foreground replacement process has actually spawned. */
-  readonly spawnDetached: (
-    command: string,
-    args: ReadonlyArray<string>,
-  ) => Effect.Effect<void, ProcessRunner.ProcessSpawnError>;
-  readonly exitProcess: () => void;
-}
-
-function normalizeEntryPath(entryPath: string): string {
-  return entryPath.replaceAll("\\", "/");
-}
 
-/**
- * Only a published npm artifact can be swapped for another version: dev
- * checkouts (apps/server/dist) and the desktop app's bundled backend have no
- * npm identity, and the desktop manages its own updates.
- */
-export function isPublishedCliEntry(entryPath: string): boolean {
-  return normalizeEntryPath(entryPath).includes("/node_modules/t3/dist/");
-}
-
-/**
- * The update path this process can offer, or null when only a manual
- * relaunch works. "desktop-managed" — the T3 Code desktop app spawned this
- * backend and owns its version; only updating the app updates it.
- * "boot-service" — this is the systemd-supervised process from
- * bootService.ts: rewrite the unit and let systemd swap it. "respawn" — a
- * foreground POSIX process running a published artifact: replace it with a
- * detached child. Windows foreground runs are unsupported for now (no
- * equivalent of the detach-and-exec handoff below).
- */
-export const resolveServerSelfUpdateCapability = Effect.fn(
-  "cloud.server_self_update.resolve_capability",
-)(function* (input: {
-  /** True when the desktop app supervises this backend (mode "desktop"). */
+export function resolveServerSelfUpdateCapability(input: {
   readonly desktopManaged: boolean;
-}) {
-  if (input.desktopManaged) {
-    return "desktop-managed" as const;
-  }
-
-  const platform = yield* HostProcessPlatform;
-  const env = yield* HostProcessEnvironment;
-  const hostArguments = yield* HostProcessArguments;
-  const fs = yield* FileSystem.FileSystem;
-  const path = yield* Path.Path;
-
-  const entryPath = hostArguments[1] ?? "";
-  if (entryPath === "") {
-    return null;
-  }
-
-  const homeDir = env.HOME ?? "";
-  if (platform === "linux" && homeDir !== "") {
-    const unitPath = path.join(homeDir, ".config", "systemd", "user", BOOT_SERVICE_UNIT_FILE);
-    const unitReferencesEntry = yield* fs.readFileString(unitPath).pipe(
-      Effect.map((unit) => unit.includes(quoteSystemdValue(entryPath))),
-      Effect.orElseSucceed(() => false),
-    );
-    // INVOCATION_ID only proves that some systemd unit launched us. The
-    // explicit marker written into t3code.service identifies this unit as the
-    // supervisor that will replace the current process when restarted.
-    if (
-      unitReferencesEntry &&
-      (env.INVOCATION_ID ?? "") !== "" &&
-      env[BOOT_SERVICE_UNIT_ENV] === BOOT_SERVICE_UNIT_FILE
-    ) {
-      return "boot-service" as const;
-    }
-
-    // A process owned by another (or a legacy unmarked) systemd unit must not
-    // use the foreground respawn path: Restart=always could otherwise launch
-    // the old unit beside the detached replacement.
-    if ((env.INVOCATION_ID ?? "") !== "") {
-      return null;
-    }
-  }
-
-  if ((platform === "linux" || platform === "darwin") && isPublishedCliEntry(entryPath)) {
-    return "respawn" as const;
-  }
-
-  return null;
-});
+  readonly launcherManaged: boolean;
+}): ServerSelfUpdateCapability | null {
+  if (input.desktopManaged) return "desktop-managed" as const;
+  return input.launcherManaged ? ("boot-service" as const) : null;
+}
 
 export class ServerSelfUpdate extends Context.Service<
   ServerSelfUpdate,
   {
     readonly update: (
       input: ServerSelfUpdateInput,
-      reportProgress?: (stage: ServerSelfUpdateProgressStage) => Effect.Effect<void, never, never>,
+      reportProgress?: (stage: ServerSelfUpdateProgressStage) => Effect.Effect<void>,
     ) => Effect.Effect<ServerSelfUpdateResult, ServerSelfUpdateError>;
   }
 >()("t3/cloud/selfUpdate/ServerSelfUpdate") {}
 
-export const make = Effect.fn("cloud.server_self_update.make")(function* (options?: {
-  readonly host?: Partial<ServerSelfUpdateHost>;
-}) {
+export const make = Effect.fn("cloud.server_self_update.make")(function* () {
   const serverConfig = yield* ServerConfig.ServerConfig;
+  const launcher = yield* ServiceLauncherClient.ServiceLauncherClient;
+  const runner = yield* ProcessRunner.ProcessRunner;
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
-  const runner = yield* ProcessRunner.ProcessRunner;
-  const env = yield* HostProcessEnvironment;
-  const hostExecPath = yield* HostProcessExecutablePath;
-  const hostArguments = yield* HostProcessArguments;
-  const capability: ServerSelfUpdateCapability | null = yield* resolveServerSelfUpdateCapability({
-    desktopManaged: serverConfig.mode === "desktop",
-  });
-
-  const host: ServerSelfUpdateHost = {
-    execPath: options?.host?.execPath ?? hostExecPath,
-    cliEntryPath: options?.host?.cliEntryPath ?? hostArguments[1] ?? "",
-    cliArgs: options?.host?.cliArgs ?? hostArguments.slice(2),
-    spawnDetached:
-      options?.host?.spawnDetached ??
-      ((command, args) =>
-        Effect.callback<void, ProcessRunner.ProcessSpawnError>((resume) => {
-          const spawnError = (cause: unknown) =>
-            new ProcessRunner.ProcessSpawnError({
-              command,
-              argumentCount: args.length,
-              cause,
-            });
-          let child: NodeChildProcess.ChildProcess;
-          try {
-            child = NodeChildProcess.spawn(command, [...args], {
-              detached: true,
-              stdio: "ignore",
-            });
-          } catch (cause) {
-            resume(Effect.fail(spawnError(cause)));
-            return;
-          }
-
-          const onSpawnError = (cause: Error) => resume(Effect.fail(spawnError(cause)));
-          child.once("error", onSpawnError);
-          child.once("spawn", () => {
-            child.removeListener("error", onSpawnError);
-            // Keep asynchronous child errors from becoming uncaught after the
-            // successful spawn handoff has already been acknowledged.
-            child.on("error", () => undefined);
-            child.unref();
-            resume(Effect.void);
-          });
-        })),
-    exitProcess: options?.host?.exitProcess ?? (() => process.exit(0)),
-  };
-
+  const execPath = yield* HostProcessExecutablePath;
   const inFlight = yield* Ref.make(false);
 
+  const capability: ServerSelfUpdateCapability | null =
+    serverConfig.mode === "desktop" ? "desktop-managed" : launcher.managed ? "boot-service" : null;
   const failWith = (reason: string, cause?: unknown) =>
     cause === undefined
       ? new ServerSelfUpdateError({ reason })
       : new ServerSelfUpdateError({ reason, cause });
 
-  /** Deferred so the RPC acknowledgement flushes before the process dies.
-      Detached from the request scope: the triggering connection is exactly
-      what the restart tears down. */
-  const scheduleRestart = (restart: Effect.Effect<void>) =>
-    Effect.sleep(RESTART_DELAY).pipe(
-      Effect.andThen(restart),
-      Effect.forkDetach({ startImmediately: true }),
-    );
-  const writeUnitAtomically = (filePath: string, contents: string) =>
-    writeFileStringAtomically({ filePath, contents }).pipe(
-      Effect.provideService(FileSystem.FileSystem, fs),
-      Effect.provideService(Path.Path, path),
-    );
-
   const update: ServerSelfUpdate["Service"]["update"] = Effect.fn(
     "cloud.server_self_update.update",
   )(function* (input, reportProgress = () => Effect.void) {
@@ -237,199 +71,123 @@ export const make = Effect.fn("cloud.server_self_update.make")(function* (option
     }
     if (capability === null) {
       return yield* failWith(
-        "This server cannot update itself; relaunch it manually with the new version.",
+        "Remote updates require the T3 Code background service. Run `t3 service install` on the server machine.",
       );
     }
-    const activeMethod = capability;
+
     const targetVersion = input.targetVersion.trim();
-    if (!EXACT_VERSION_PATTERN.test(targetVersion)) {
+    if (!isExactServiceVersion(targetVersion)) {
       return yield* failWith(`'${targetVersion}' is not an exact t3 version.`);
     }
-
-    const alreadyRunning = yield* Ref.getAndSet(inFlight, true);
-    if (alreadyRunning) {
+    if (yield* Ref.getAndSet(inFlight, true)) {
       return yield* failWith("A server update is already in progress.");
     }
 
     return yield* Effect.gen(function* () {
       yield* reportProgress("downloading");
-      const runtimePaths = yield* ensurePinnedRuntimeInstalled({
+      const paths = yield* ensurePinnedRuntimeInstalled({
         baseDir: serverConfig.baseDir,
         version: targetVersion,
         fs,
         path,
         runner,
+        validate: (runtime) =>
+          runner
+            .run({
+              command: execPath,
+              args: [
+                runtime.entryPath,
+                "__service-preflight",
+                "--database-path",
+                serverConfig.dbPath,
+                "--launcher-protocol",
+                String(SERVICE_LAUNCHER_PROTOCOL),
+              ],
+              timeout: PREFLIGHT_TIMEOUT,
+            })
+            .pipe(
+              Effect.mapError(
+                (cause) =>
+                  new PinnedRuntimeInstallError({
+                    step: "running the staged service preflight",
+                    cause,
+                  }),
+              ),
+              Effect.flatMap(
+                (
+                  result,
+                ): Effect.Effect<
+                  void,
+                  PinnedRuntimeInstallError | PinnedRuntimePreflightBlockedError
+                > => {
+                  if (result.code !== 0) {
+                    return Effect.fail(
+                      new PinnedRuntimeInstallError({
+                        step: "running the staged service preflight",
+                        exitCode: Number(result.code),
+                        stdoutLength: result.stdout.length,
+                        stderrLength: result.stderr.length,
+                      }),
+                    );
+                  }
+                  let parsed: unknown;
+                  try {
+                    parsed = JSON.parse(result.stdout.trim());
+                  } catch (cause) {
+                    return Effect.fail(
+                      new PinnedRuntimeInstallError({
+                        step: "decoding the staged service preflight",
+                        cause,
+                      }),
+                    );
+                  }
+                  const preflight = decodeServicePreflightResult(parsed);
+                  if (preflight === undefined || preflight.version !== targetVersion) {
+                    return Effect.fail(
+                      new PinnedRuntimeInstallError({
+                        step: "verifying the staged service preflight",
+                      }),
+                    );
+                  }
+                  return preflight.status === "ready"
+                    ? Effect.void
+                    : Effect.fail(
+                        new PinnedRuntimePreflightBlockedError({
+                          version: targetVersion,
+                          reason: preflight.reason,
+                        }),
+                      );
+                },
+              ),
+            ),
       }).pipe(
-        Effect.mapError((error) => failWith("Could not install the requested t3 version.", error)),
+        Effect.mapError((error) =>
+          error._tag === "PinnedRuntimePreflightBlockedError"
+            ? failWith(error.reason, error)
+            : failWith(`Could not prepare t3@${targetVersion}.`, error),
+        ),
       );
 
       yield* reportProgress("installing");
-      // A broken artifact (failed native build, incompatible node) must be
-      // caught while the current server is still alive to report it.
-      const preflight = yield* runner
-        .run({
-          command: host.execPath,
-          args: [runtimePaths.entryPath, "--version"],
-          timeout: PREFLIGHT_TIMEOUT,
-        })
+      const updateId = yield* launcher
+        .requestUpdate({ targetVersion })
         .pipe(
-          Effect.mapError((cause) =>
-            failWith(`Could not verify the installed t3@${targetVersion}.`, cause),
-          ),
-        );
-      // Effect CLI's unstable formatVersion currently emits `${name} v${version}`.
-      // Extract the version token so surrounding presentation changes do not break updates.
-      const reportedVersion = /\bv(\S+)\s*$/.exec(preflight.stdout)?.[1];
-      if (preflight.code !== 0 || reportedVersion !== targetVersion) {
-        // A completed npm install can still be unusable under this Node or on
-        // this machine. Remove its sentinel and tree so a retry of the same
-        // version performs a clean install instead of reusing a known-bad one.
-        yield* removePinnedRuntimeInstallation({
-          baseDir: serverConfig.baseDir,
-          version: targetVersion,
-          fs,
-          path,
-        }).pipe(
           Effect.mapError((error) =>
-            failWith(`Could not remove the failed t3@${targetVersion} installation.`, error),
-          ),
-        );
-        return yield* failWith(
-          preflight.code !== 0
-            ? `The installed t3@${targetVersion} failed its version check (exit code ${String(preflight.code)}).`
-            : `The installed runtime did not report the requested t3@${targetVersion} version.`,
-        );
-      }
-
-      if (activeMethod === "boot-service") {
-        const homeDir = env.HOME ?? "";
-        const unitPath = path.join(homeDir, ".config", "systemd", "user", BOOT_SERVICE_UNIT_FILE);
-        const previousUnit = yield* fs
-          .readFileString(unitPath)
-          .pipe(
-            Effect.mapError((cause) => failWith("Could not read the current systemd unit.", cause)),
-          );
-        // Same shape bootService.install writes, so host lifecycle commands
-        // still recognize the unit as current.
-        const unit = renderBootServiceUnit({
-          nodePath: host.execPath,
-          t3EntryPath: runtimePaths.entryPath,
-          baseDir: serverConfig.baseDir,
-          logPath: path.join(serverConfig.logsDir, "boot-service.log"),
-          unitPath,
-        });
-        yield* writeUnitAtomically(unitPath, unit).pipe(
-          Effect.mapError((cause) => failWith("Could not update the systemd unit.", cause)),
-        );
-
-        const reloadSystemd = Effect.fn("cloud.server_self_update.reload_systemd")(function* () {
-          const reload = yield* runner
-            .run({ command: "systemctl", args: ["--user", "daemon-reload"] })
-            .pipe(Effect.mapError((cause) => failWith("Could not reload systemd units.", cause)));
-          if (reload.code !== 0) {
-            return yield* failWith(
-              `Reloading systemd units failed (exit code ${String(reload.code)}).`,
-            );
-          }
-        });
-
-        yield* reloadSystemd().pipe(
-          Effect.catch((reloadError) =>
-            writeUnitAtomically(unitPath, previousUnit).pipe(
-              Effect.mapError((rollbackCause) =>
-                failWith("Could not restore the previous systemd unit.", {
-                  reloadError,
-                  rollbackCause,
-                }),
-              ),
-              // Systemd should still have the old unit in memory after the
-              // failed reload, but retry after restoring in case it applied a
-              // partial update before returning an error.
-              Effect.andThen(reloadSystemd().pipe(Effect.ignore)),
-              Effect.andThen(Effect.fail(reloadError)),
-            ),
-          ),
-        );
-        yield* Effect.logInfo("Server self-update installed; restarting boot service.", {
-          targetVersion,
-        });
-        // Restart after the acknowledgement has had time to cross any relay
-        // hop. If systemd rejects the handoff, restore the previous unit while
-        // this process is still alive and log the failure for diagnostics.
-        yield* scheduleRestart(
-          Effect.gen(function* () {
-            const restart = yield* runner
-              .run({
-                command: "systemctl",
-                args: ["--user", "restart", BOOT_SERVICE_UNIT_FILE],
-              })
-              .pipe(
-                Effect.mapError((cause) =>
-                  failWith("Could not restart the systemd boot service.", cause),
-                ),
-              );
-            if (restart.code !== 0) {
-              return yield* failWith(
-                `Restarting the systemd boot service failed (exit code ${String(restart.code)}).`,
-              );
-            }
-          }).pipe(
-            Effect.catch((restartError) =>
-              writeUnitAtomically(unitPath, previousUnit).pipe(
-                Effect.andThen(reloadSystemd()),
-                Effect.mapError((rollbackError) =>
-                  failWith("Could not restore the previous systemd unit.", {
-                    restartError,
-                    rollbackError,
-                  }),
-                ),
-                Effect.andThen(Effect.fail(restartError)),
-              ),
-            ),
-            Effect.catch((error) =>
-              Effect.logError("Server self-update could not restart the boot service.").pipe(
-                Effect.annotateLogs({ targetVersion, error: error.reason }),
-              ),
-            ),
-            Effect.ensuring(Ref.set(inFlight, false)),
-          ),
-        );
-      } else {
-        // Spawn the shim before acknowledging the RPC so ENOENT/EACCES and
-        // other launch failures leave this server alive and return a useful
-        // error. The shim itself waits until after the acknowledgement and
-        // deferred exit before binding the replacement server.
-        yield* host
-          .spawnDetached("/bin/sh", [
-            "-c",
-            'sleep 3; exec "$@"',
-            "t3-self-update",
-            host.execPath,
-            runtimePaths.entryPath,
-            ...host.cliArgs,
-          ])
-          .pipe(
-            Effect.mapError((cause) =>
-              failWith("Could not start the replacement t3 process.", cause),
-            ),
-          );
-        yield* Effect.logInfo("Server self-update installed; respawning.", { targetVersion });
-        yield* scheduleRestart(
-          Effect.try({
-            try: () => host.exitProcess(),
-            catch: (cause) => failWith("Could not exit the replaced t3 process.", cause),
-          }).pipe(
-            Effect.catch((error) =>
-              Effect.logError("Server self-update could not exit the replaced process.").pipe(
-                Effect.annotateLogs({ targetVersion, error: error.reason }),
-                Effect.ensuring(Ref.set(inFlight, false)),
-              ),
+            failWith(
+              error._tag === "ServiceLauncherRejectedError"
+                ? error.reason
+                : "Could not ask the service launcher to activate the prepared update.",
+              error,
             ),
           ),
         );
-      }
 
-      return { targetVersion, method: activeMethod };
+      yield* Effect.logInfo("Server update prepared; handing off to the service launcher.", {
+        updateId,
+        targetVersion,
+        runtimePath: paths.entryPath,
+      });
+      return { targetVersion, method: "boot-service" as const, updateId };
     }).pipe(Effect.onError(() => Ref.set(inFlight, false)));
   });
 
diff --git a/apps/server/src/cloud/serviceLauncherClient.test.ts b/apps/server/src/cloud/serviceLauncherClient.test.ts
new file mode 100644
index 00000000000..6b9e926ff8d
--- /dev/null
+++ b/apps/server/src/cloud/serviceLauncherClient.test.ts
@@ -0,0 +1,130 @@
+import { expect, it } from "@effect/vitest";
+import { HostProcessEnvironment } from "@t3tools/shared/hostProcess";
+import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+
+import {
+  SERVICE_LAUNCHER_CONTEXT_ENV,
+  type ServiceLauncherChildMessage,
+  type ServiceLauncherParentMessage,
+} from "./serviceProtocol.ts";
+import * as ServiceLauncherClient from "./serviceLauncherClient.ts";
+
+class FakeLauncherProcess {
+  readonly connected = true;
+  readonly env: Record<string, string | undefined>;
+  readonly sent: ServiceLauncherChildMessage[] = [];
+  readonly #listeners = new Map<string, Set<(...args: ReadonlyArray<unknown>) => void>>();
+
+  constructor(context: unknown) {
+    this.env = { [SERVICE_LAUNCHER_CONTEXT_ENV]: JSON.stringify(context) };
+  }
+
+  send = (message: ServiceLauncherChildMessage, callback?: (error: Error | null) => void) => {
+    this.sent.push(message);
+    callback?.(null);
+    return true;
+  };
+
+  on = (event: "message" | "disconnect", listener: (...args: ReadonlyArray<unknown>) => void) => {
+    const listeners = this.#listeners.get(event) ?? new Set();
+    listeners.add(listener);
+    this.#listeners.set(event, listeners);
+  };
+
+  off = (event: "message" | "disconnect", listener: (...args: ReadonlyArray<unknown>) => void) => {
+    this.#listeners.get(event)?.delete(listener);
+  };
+
+  emit(message: ServiceLauncherParentMessage) {
+    for (const listener of this.#listeners.get("message") ?? []) listener(message);
+  }
+}
+
+const makeClient = (host: FakeLauncherProcess, currentVersion: string) =>
+  ServiceLauncherClient.make({ currentVersion }).pipe(
+    Effect.provideService(ServiceLauncherClient.ServiceLauncherHostProcess, host),
+    Effect.provideService(HostProcessEnvironment, host.env),
+  );
+
+it.effect("waits for the launcher to durably commit the trial update ID", () =>
+  Effect.gen(function* () {
+    const pending = {
+      id: "update-1",
+      fromVersion: "1.0.0",
+      targetVersion: "1.1.0",
+      status: "pending" as const,
+    };
+    const host = new FakeLauncherProcess({
+      protocol: 1,
+      childVersion: "1.1.0",
+      update: pending,
+    });
+    const client = yield* makeClient(host, "1.1.0");
+    const prepared = yield* Effect.forkChild(client.prepareTrial, { startImmediately: true });
+    yield* Effect.yieldNow;
+    expect(host.sent).toEqual([{ type: "prepared", updateId: "update-1" }]);
+
+    const committed = {
+      id: pending.id,
+      fromVersion: pending.fromVersion,
+      targetVersion: pending.targetVersion,
+      status: "committed" as const,
+    };
+    host.emit({ type: "committed", updateId: committed.id });
+    expect(yield* Fiber.join(prepared)).toEqual(committed);
+  }),
+);
+
+it.effect("returns the launcher-generated ID only after update acceptance", () =>
+  Effect.gen(function* () {
+    const host = new FakeLauncherProcess({
+      protocol: 1,
+      childVersion: "1.0.0",
+    });
+    const client = yield* makeClient(host, "1.0.0");
+    const requested = yield* Effect.forkChild(client.requestUpdate({ targetVersion: "1.1.0" }), {
+      startImmediately: true,
+    });
+    yield* Effect.yieldNow;
+    host.emit({
+      type: "update-accepted",
+      updateId: "launcher-id",
+    });
+    expect(yield* Fiber.join(requested)).toBe("launcher-id");
+  }),
+);
+
+it.effect("preserves a launcher rejection as a distinct error", () =>
+  Effect.gen(function* () {
+    const host = new FakeLauncherProcess({ protocol: 1, childVersion: "1.0.0" });
+    const client = yield* makeClient(host, "1.0.0");
+    const requested = yield* Effect.forkChild(client.requestUpdate({ targetVersion: "1.1.0" }), {
+      startImmediately: true,
+    });
+    yield* Effect.yieldNow;
+    host.emit({ type: "update-rejected", reason: "requires local update" });
+    expect(yield* Fiber.join(requested).pipe(Effect.flip)).toMatchObject({
+      _tag: "ServiceLauncherRejectedError",
+      targetVersion: "1.1.0",
+      reason: "requires local update",
+    });
+  }),
+);
+
+it.effect("rejects contradictory trial context instead of leaving activation closed", () =>
+  Effect.gen(function* () {
+    const host = new FakeLauncherProcess({
+      protocol: 1,
+      childVersion: "1.1.0",
+      update: {
+        id: "update-1",
+        fromVersion: "1.0.0",
+        targetVersion: "1.2.0",
+        status: "pending",
+      },
+    });
+    const error = yield* makeClient(host, "1.1.0").pipe(Effect.flip);
+    expect(error.message).toBe("The service launcher supplied invalid startup context.");
+  }),
+);
diff --git a/apps/server/src/cloud/serviceLauncherClient.ts b/apps/server/src/cloud/serviceLauncherClient.ts
new file mode 100644
index 00000000000..760642c29f5
--- /dev/null
+++ b/apps/server/src/cloud/serviceLauncherClient.ts
@@ -0,0 +1,249 @@
+import type { ServerSelfUpdateOutcome } from "@t3tools/contracts";
+import { HostProcessEnvironment } from "@t3tools/shared/hostProcess";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+
+import packageJson from "../../package.json" with { type: "json" };
+import {
+  decodeServiceLauncherContext,
+  decodeServiceLauncherParentMessage,
+  SERVICE_LAUNCHER_CONTEXT_ENV,
+  type ServiceLauncherChildMessage,
+  type ServiceLauncherParentMessage,
+} from "./serviceProtocol.ts";
+
+export class ServiceLauncherClientError extends Schema.TaggedErrorClass<ServiceLauncherClientError>()(
+  "ServiceLauncherClientError",
+  {
+    operation: Schema.Literals([
+      "decode-context",
+      "version-mismatch",
+      "ipc-unavailable",
+      "unmanaged",
+      "send",
+      "disconnect",
+      "timeout",
+    ]),
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    switch (this.operation) {
+      case "decode-context":
+        return "The service launcher supplied invalid startup context.";
+      case "version-mismatch":
+        return "The service launcher started a different t3 version.";
+      case "ipc-unavailable":
+        return "The service launcher IPC channel is unavailable.";
+      case "unmanaged":
+        return "This server is not managed by the launcher.";
+      case "send":
+        return "Could not send a request to the service launcher.";
+      case "disconnect":
+        return "The service launcher disconnected before acknowledging the request.";
+      case "timeout":
+        return "The service launcher did not respond within 30 seconds.";
+    }
+  }
+}
+
+export class ServiceLauncherRejectedError extends Schema.TaggedErrorClass<ServiceLauncherRejectedError>()(
+  "ServiceLauncherRejectedError",
+  {
+    targetVersion: Schema.String,
+    reason: Schema.String,
+  },
+) {
+  override get message(): string {
+    return this.reason;
+  }
+}
+
+interface ServiceLauncherProcess {
+  readonly connected: boolean;
+  readonly send: (
+    message: ServiceLauncherChildMessage,
+    callback?: (error: Error | null) => void,
+  ) => boolean;
+  readonly on: (
+    event: "message" | "disconnect",
+    listener: (...args: ReadonlyArray<unknown>) => void,
+  ) => void;
+  readonly off: (
+    event: "message" | "disconnect",
+    listener: (...args: ReadonlyArray<unknown>) => void,
+  ) => void;
+}
+
+export const ServiceLauncherHostProcess = Context.Reference<ServiceLauncherProcess>(
+  "t3/cloud/serviceLauncherHostProcess",
+  {
+    defaultValue: () => ({
+      connected: process.connected && process.send !== undefined,
+      send: (message, callback) => {
+        if (process.send === undefined) return false;
+        return callback === undefined ? process.send(message) : process.send(message, callback);
+      },
+      on: (event, listener) => {
+        process.on(event, listener);
+      },
+      off: (event, listener) => {
+        process.off(event, listener);
+      },
+    }),
+  },
+);
+
+export class ServiceLauncherClient extends Context.Service<
+  ServiceLauncherClient,
+  {
+    readonly managed: boolean;
+    readonly trial: boolean;
+    readonly requestUpdate: (input: {
+      readonly targetVersion: string;
+    }) => Effect.Effect<string, ServiceLauncherClientError | ServiceLauncherRejectedError>;
+    readonly prepareTrial: Effect.Effect<
+      ServerSelfUpdateOutcome | undefined,
+      ServiceLauncherClientError
+    >;
+  }
+>()("t3/cloud/serviceLauncherClient") {}
+
+const resolveStartup = Effect.fn("cloud.service_launcher_client.resolve_startup")(
+  function* (options?: { readonly currentVersion?: string }) {
+    const host = yield* ServiceLauncherHostProcess;
+    const environment = yield* HostProcessEnvironment;
+    const currentVersion = options?.currentVersion ?? packageJson.version;
+    const rawContext = environment[SERVICE_LAUNCHER_CONTEXT_ENV];
+    const context = rawContext === undefined ? undefined : decodeServiceLauncherContext(rawContext);
+
+    if (rawContext !== undefined && context === undefined) {
+      return yield* new ServiceLauncherClientError({ operation: "decode-context" });
+    }
+    if (context !== undefined && context.childVersion !== currentVersion) {
+      return yield* new ServiceLauncherClientError({ operation: "version-mismatch" });
+    }
+
+    const managed = context !== undefined && host.connected;
+    if (context !== undefined && !managed) {
+      return yield* new ServiceLauncherClientError({ operation: "ipc-unavailable" });
+    }
+
+    return { host, context, managed };
+  },
+);
+
+export const resolveServiceLauncherMode = Effect.fn("cloud.service_launcher_client.resolve_mode")(
+  function* () {
+    const { context, managed } = yield* resolveStartup();
+    return { managed, trial: context?.update?.status === "pending" };
+  },
+);
+
+export const make = Effect.fn("cloud.service_launcher_client.make")(function* (options?: {
+  readonly currentVersion?: string;
+}) {
+  const { host, context, managed } = yield* resolveStartup(options);
+
+  const exchange = (
+    message: ServiceLauncherChildMessage,
+    accept: (reply: ServiceLauncherParentMessage) => boolean,
+  ) =>
+    Effect.callback<ServiceLauncherParentMessage, ServiceLauncherClientError>((resume) => {
+      if (!managed) {
+        resume(Effect.fail(new ServiceLauncherClientError({ operation: "unmanaged" })));
+        return;
+      }
+
+      let settled = false;
+      const cleanup = () => {
+        host.off("message", onMessage);
+        host.off("disconnect", onDisconnect);
+      };
+      const settle = (
+        effect: Effect.Effect<ServiceLauncherParentMessage, ServiceLauncherClientError>,
+      ) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resume(effect);
+      };
+      const onMessage = (...args: ReadonlyArray<unknown>) => {
+        const reply = decodeServiceLauncherParentMessage(args[0]);
+        if (reply !== undefined && accept(reply)) settle(Effect.succeed(reply));
+      };
+      const onDisconnect = () =>
+        settle(Effect.fail(new ServiceLauncherClientError({ operation: "disconnect" })));
+
+      host.on("message", onMessage);
+      host.on("disconnect", onDisconnect);
+      try {
+        host.send(message, (error) => {
+          if (error !== null) {
+            settle(
+              Effect.fail(new ServiceLauncherClientError({ operation: "send", cause: error })),
+            );
+          }
+        });
+      } catch (cause) {
+        settle(Effect.fail(new ServiceLauncherClientError({ operation: "send", cause })));
+      }
+
+      return Effect.sync(cleanup);
+    }).pipe(
+      Effect.timeoutOrElse({
+        duration: "30 seconds",
+        orElse: () => Effect.fail(new ServiceLauncherClientError({ operation: "timeout" })),
+      }),
+    );
+
+  const requestUpdate = (input: { readonly targetVersion: string }) =>
+    exchange(
+      { type: "request-update", ...input },
+      (reply) => reply.type === "update-accepted" || reply.type === "update-rejected",
+    ).pipe(
+      Effect.flatMap((reply) =>
+        reply.type === "update-accepted"
+          ? Effect.succeed(reply.updateId)
+          : reply.type === "update-rejected"
+            ? Effect.fail(
+                new ServiceLauncherRejectedError({
+                  targetVersion: input.targetVersion,
+                  reason: reply.reason,
+                }),
+              )
+            : Effect.die("service launcher returned an impossible update response"),
+      ),
+    );
+
+  const pending = context?.update?.status === "pending" ? context.update : undefined;
+  const outcome =
+    context?.update === undefined || context.update.status === "pending"
+      ? undefined
+      : context.update;
+  const prepareTrial =
+    pending !== undefined
+      ? exchange(
+          { type: "prepared", updateId: pending.id },
+          (reply) => reply.type === "committed" && reply.updateId === pending.id,
+        ).pipe(
+          Effect.flatMap((reply) => {
+            if (reply.type !== "committed") {
+              return Effect.die("service launcher returned an impossible prepared response");
+            }
+            return Effect.succeed({ ...pending, status: "committed" as const });
+          }),
+        )
+      : Effect.succeed(outcome);
+
+  return ServiceLauncherClient.of({
+    managed,
+    trial: pending !== undefined,
+    requestUpdate,
+    prepareTrial,
+  });
+});
+
+export const layer = Layer.effect(ServiceLauncherClient, make());
diff --git a/apps/server/src/cloud/servicePreflight.test.ts b/apps/server/src/cloud/servicePreflight.test.ts
new file mode 100644
index 00000000000..d2ce6db8de8
--- /dev/null
+++ b/apps/server/src/cloud/servicePreflight.test.ts
@@ -0,0 +1,47 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { 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 NodeSqlite from "node:sqlite";
+
+import { migrationManifest } from "../persistence/Migrations.ts";
+import { runServicePreflight } from "./servicePreflight.ts";
+
+it.layer(NodeServices.layer)("service update preflight", (it) => {
+  it.effect("requires exact migration-manifest equality without mutating the database", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-service-preflight-test-" });
+      const databasePath = path.join(root, "state.sqlite");
+      const database = new NodeSqlite.DatabaseSync(databasePath);
+      database.exec("CREATE TABLE effect_sql_migrations (migration_id INTEGER, name TEXT)");
+      const insert = database.prepare(
+        "INSERT INTO effect_sql_migrations (migration_id, name) VALUES (?, ?)",
+      );
+      for (const [id, name] of migrationManifest) insert.run(id, name);
+      database.close();
+
+      expect(runServicePreflight({ databasePath, launcherProtocol: 1, version: "1.2.3" })).toEqual({
+        status: "ready",
+        version: "1.2.3",
+        launcherProtocol: 1,
+      });
+
+      const changed = new NodeSqlite.DatabaseSync(databasePath);
+      changed.exec("DELETE FROM effect_sql_migrations WHERE migration_id = 35");
+      changed.close();
+      const blocked = runServicePreflight({
+        databasePath,
+        launcherProtocol: 1,
+        version: "1.2.3",
+      });
+      expect(blocked.status).toBe("blocked");
+      if (blocked.status === "blocked") {
+        expect(blocked.reason).toContain("npx t3@1.2.3 service update");
+      }
+    }),
+  );
+});
diff --git a/apps/server/src/cloud/servicePreflight.ts b/apps/server/src/cloud/servicePreflight.ts
new file mode 100644
index 00000000000..1843e163881
--- /dev/null
+++ b/apps/server/src/cloud/servicePreflight.ts
@@ -0,0 +1,96 @@
+import * as NodeSqlite from "node:sqlite";
+
+import packageJson from "../../package.json" with { type: "json" };
+import { migrationManifest } from "../persistence/Migrations.ts";
+import { SERVICE_LAUNCHER_PROTOCOL } from "./serviceProtocol.ts";
+
+export type ServicePreflightResult =
+  | {
+      readonly status: "ready";
+      readonly version: string;
+      readonly launcherProtocol: typeof SERVICE_LAUNCHER_PROTOCOL;
+    }
+  | {
+      readonly status: "blocked";
+      readonly version: string;
+      readonly reason: string;
+    };
+
+const localUpdateReason = (version: string) =>
+  `This version includes a database update and cannot be installed remotely. Run \`npx t3@${version} service update\` on the server machine.`;
+
+const isMigrationRow = (
+  value: unknown,
+): value is { readonly migration_id: number; readonly name: string } =>
+  typeof value === "object" &&
+  value !== null &&
+  "migration_id" in value &&
+  typeof value.migration_id === "number" &&
+  "name" in value &&
+  typeof value.name === "string";
+
+export function runServicePreflight(input: {
+  readonly databasePath: string;
+  readonly launcherProtocol: number;
+  readonly version?: string;
+}): ServicePreflightResult {
+  const version = input.version ?? packageJson.version;
+  if (input.launcherProtocol !== SERVICE_LAUNCHER_PROTOCOL) {
+    return {
+      status: "blocked",
+      version,
+      reason:
+        "This release requires a newer T3 Code service launcher. Update it on the server machine.",
+    };
+  }
+
+  try {
+    const database = new NodeSqlite.DatabaseSync(input.databasePath, { readOnly: true });
+    try {
+      const rows: ReadonlyArray<unknown> = database
+        .prepare("SELECT migration_id, name FROM effect_sql_migrations ORDER BY migration_id")
+        .all();
+      const exact =
+        rows.length === migrationManifest.length &&
+        rows.every((row, index) => {
+          const expected = migrationManifest[index];
+          return (
+            isMigrationRow(row) && row.migration_id === expected?.[0] && row.name === expected?.[1]
+          );
+        });
+      if (!exact) return { status: "blocked", version, reason: localUpdateReason(version) };
+    } finally {
+      database.close();
+    }
+  } catch {
+    return { status: "blocked", version, reason: localUpdateReason(version) };
+  }
+
+  return { status: "ready", version, launcherProtocol: SERVICE_LAUNCHER_PROTOCOL };
+}
+
+export function decodeServicePreflightResult(value: unknown): ServicePreflightResult | undefined {
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  if (
+    record.status === "ready" &&
+    record.launcherProtocol === SERVICE_LAUNCHER_PROTOCOL &&
+    typeof record.version === "string"
+  ) {
+    return {
+      status: "ready",
+      version: record.version,
+      launcherProtocol: SERVICE_LAUNCHER_PROTOCOL,
+    };
+  }
+  if (
+    record.status === "blocked" &&
+    typeof record.version === "string" &&
+    typeof record.reason === "string"
+  ) {
+    return { status: "blocked", version: record.version, reason: record.reason };
+  }
+  return undefined;
+}
diff --git a/apps/server/src/cloud/serviceProtocol.ts b/apps/server/src/cloud/serviceProtocol.ts
new file mode 100644
index 00000000000..921bc1447ed
--- /dev/null
+++ b/apps/server/src/cloud/serviceProtocol.ts
@@ -0,0 +1,226 @@
+import type { ServerSelfUpdateOutcome } from "@t3tools/contracts";
+
+export const SERVICE_LAUNCHER_PROTOCOL = 1 as const;
+export const SERVICE_LAUNCHER_CONTEXT_ENV = "T3_SERVICE_LAUNCHER_CONTEXT";
+export const SERVICE_LAUNCHER_FILE = "service-launcher.mjs";
+export const SERVICE_STATE_FILE = "service-state.json";
+
+export interface PendingServiceUpdate {
+  readonly id: string;
+  readonly fromVersion: string;
+  readonly targetVersion: string;
+  readonly status: "pending";
+}
+
+export type ServiceUpdateRecord = PendingServiceUpdate | ServerSelfUpdateOutcome;
+
+export interface ServiceState {
+  readonly protocol: typeof SERVICE_LAUNCHER_PROTOCOL;
+  readonly activeVersion: string;
+  readonly update?: ServiceUpdateRecord;
+}
+
+/** Context is copied from launcher-owned state when a child is spawned. */
+export interface ServiceLauncherContext {
+  readonly protocol: typeof SERVICE_LAUNCHER_PROTOCOL;
+  readonly childVersion: string;
+  readonly update?: ServiceUpdateRecord;
+}
+
+export type ServiceLauncherChildMessage =
+  | {
+      readonly type: "request-update";
+      readonly targetVersion: string;
+    }
+  | {
+      readonly type: "prepared";
+      readonly updateId: string;
+    };
+
+export type ServiceLauncherParentMessage =
+  | {
+      readonly type: "update-accepted";
+      readonly updateId: string;
+    }
+  | {
+      readonly type: "update-rejected";
+      readonly reason: string;
+    }
+  | {
+      readonly type: "committed";
+      readonly updateId: string;
+    };
+
+const SEMVER_NUMBER = "(?:0|[1-9]\\d*)";
+const SEMVER_PRERELEASE = `(?:${SEMVER_NUMBER}|[0-9]*[A-Za-z-][0-9A-Za-z-]*)`;
+const EXACT_SERVICE_VERSION = new RegExp(
+  `^${SEMVER_NUMBER}\\.${SEMVER_NUMBER}\\.${SEMVER_NUMBER}(?:-${SEMVER_PRERELEASE}(?:\\.${SEMVER_PRERELEASE})*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$`,
+);
+
+/** Accepts exact SemVer only: never dist-tags or ranges passed to npm or filesystem paths. */
+export const isExactServiceVersion = (version: string): boolean =>
+  EXACT_SERVICE_VERSION.test(version);
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+export function decodeServiceUpdate(value: unknown): ServiceUpdateRecord | undefined {
+  if (!isRecord(value)) return undefined;
+  const { id, fromVersion, targetVersion, status } = value;
+  if (
+    typeof id !== "string" ||
+    id.trim() === "" ||
+    typeof fromVersion !== "string" ||
+    !isExactServiceVersion(fromVersion) ||
+    typeof targetVersion !== "string" ||
+    !isExactServiceVersion(targetVersion)
+  ) {
+    return undefined;
+  }
+  if (status === "pending") {
+    return { id, fromVersion, targetVersion, status };
+  }
+  if (
+    (status === "committed" || status === "rolled-back" || status === "failed") &&
+    (value.reason === undefined || (typeof value.reason === "string" && value.reason.trim() !== ""))
+  ) {
+    return {
+      id,
+      fromVersion,
+      targetVersion,
+      status,
+      ...(typeof value.reason === "string" ? { reason: value.reason } : {}),
+    };
+  }
+  return undefined;
+}
+
+/** SemVer precedence for exact versions. Build metadata is ignored. */
+export function compareExactServiceVersions(left: string, right: string): number {
+  const parse = (version: string) => {
+    const withoutBuild = version.split("+", 1)[0] ?? version;
+    const separator = withoutBuild.indexOf("-");
+    const core = separator === -1 ? withoutBuild : withoutBuild.slice(0, separator);
+    const prerelease = separator === -1 ? undefined : withoutBuild.slice(separator + 1);
+    const [major = "0", minor = "0", patch = "0"] = core.split(".");
+    return {
+      core: [BigInt(major), BigInt(minor), BigInt(patch)] as const,
+      prerelease: prerelease?.split(".") ?? [],
+    };
+  };
+  const a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < 3; index += 1) {
+    const x = a.core[index] ?? 0n;
+    const y = b.core[index] ?? 0n;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+    return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
+  }
+  const count = Math.max(a.prerelease.length, b.prerelease.length);
+  for (let index = 0; index < count; index += 1) {
+    const x = a.prerelease[index];
+    const y = b.prerelease[index];
+    if (x === undefined || y === undefined) return x === undefined ? -1 : 1;
+    if (x === y) continue;
+    const xNumeric = /^\d+$/.test(x);
+    const yNumeric = /^\d+$/.test(y);
+    if (xNumeric && yNumeric) return BigInt(x) < BigInt(y) ? -1 : 1;
+    if (xNumeric !== yNumeric) return xNumeric ? -1 : 1;
+    return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+export function decodeServiceState(value: unknown): ServiceState | undefined {
+  if (!isRecord(value)) return undefined;
+  const update = value.update === undefined ? undefined : decodeServiceUpdate(value.update);
+  if (
+    value.protocol !== SERVICE_LAUNCHER_PROTOCOL ||
+    typeof value.activeVersion !== "string" ||
+    !isExactServiceVersion(value.activeVersion) ||
+    (value.update !== undefined && update === undefined) ||
+    (update !== undefined &&
+      compareExactServiceVersions(update.targetVersion, update.fromVersion) <= 0) ||
+    (update?.status === "pending" && update.fromVersion !== value.activeVersion) ||
+    (update?.status === "committed" && update.targetVersion !== value.activeVersion) ||
+    ((update?.status === "rolled-back" || update?.status === "failed") &&
+      update.fromVersion !== value.activeVersion)
+  ) {
+    return undefined;
+  }
+  return {
+    protocol: SERVICE_LAUNCHER_PROTOCOL,
+    activeVersion: value.activeVersion,
+    ...(update === undefined ? {} : { update }),
+  };
+}
+
+export function parseServiceState(value: string): ServiceState | undefined {
+  try {
+    return decodeServiceState(JSON.parse(value) as unknown);
+  } catch {
+    return undefined;
+  }
+}
+
+export function decodeServiceLauncherContext(value: string): ServiceLauncherContext | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value) as unknown;
+  } catch {
+    return undefined;
+  }
+  if (
+    !isRecord(parsed) ||
+    parsed.protocol !== SERVICE_LAUNCHER_PROTOCOL ||
+    typeof parsed.childVersion !== "string" ||
+    !isExactServiceVersion(parsed.childVersion)
+  ) {
+    return undefined;
+  }
+  const update = parsed.update === undefined ? undefined : decodeServiceUpdate(parsed.update);
+  if (parsed.update !== undefined && update === undefined) return undefined;
+  const selectedVersion =
+    update?.status === "pending" || update?.status === "committed"
+      ? update.targetVersion
+      : update === undefined
+        ? parsed.childVersion
+        : update.fromVersion;
+  if (parsed.childVersion !== selectedVersion) {
+    return undefined;
+  }
+  return {
+    protocol: SERVICE_LAUNCHER_PROTOCOL,
+    childVersion: parsed.childVersion,
+    ...(update === undefined ? {} : { update }),
+  };
+}
+
+export function decodeServiceLauncherChildMessage(
+  value: unknown,
+): ServiceLauncherChildMessage | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.type === "request-update" && typeof value.targetVersion === "string") {
+    return { type: value.type, targetVersion: value.targetVersion };
+  }
+  return value.type === "prepared" && typeof value.updateId === "string"
+    ? { type: value.type, updateId: value.updateId }
+    : undefined;
+}
+
+export function decodeServiceLauncherParentMessage(
+  value: unknown,
+): ServiceLauncherParentMessage | undefined {
+  if (!isRecord(value)) return undefined;
+  if (value.type === "update-rejected" && typeof value.reason === "string") {
+    return { type: value.type, reason: value.reason };
+  }
+  if (value.type === "update-accepted" && typeof value.updateId === "string") {
+    return { type: value.type, updateId: value.updateId };
+  }
+  return value.type === "committed" && typeof value.updateId === "string"
+    ? { type: value.type, updateId: value.updateId }
+    : undefined;
+}
diff --git a/apps/server/src/environment/ServerEnvironment.ts b/apps/server/src/environment/ServerEnvironment.ts
index 2290450e7d3..a14f89fd031 100644
--- a/apps/server/src/environment/ServerEnvironment.ts
+++ b/apps/server/src/environment/ServerEnvironment.ts
@@ -10,6 +10,7 @@ import * as Schema from "effect/Schema";
 
 import packageJson from "../../package.json" with { type: "json" };
 import { resolveServerSelfUpdateCapability } from "../cloud/selfUpdate.ts";
+import { resolveServiceLauncherMode } from "../cloud/serviceLauncherClient.ts";
 import * as ServerConfig from "../config.ts";
 import * as ProcessRunner from "../processRunner.ts";
 import { resolveServerEnvironmentLabel } from "./ServerEnvironmentLabel.ts";
@@ -125,8 +126,10 @@ export const make = Effect.gen(function* () {
   const environmentId = EnvironmentId.make(environmentIdRaw);
   const cwdBaseName = path.basename(serverConfig.cwd).trim();
   const label = yield* resolveServerEnvironmentLabel({ cwdBaseName });
-  const serverSelfUpdate = yield* resolveServerSelfUpdateCapability({
+  const launcher = yield* resolveServiceLauncherMode();
+  const serverSelfUpdate = resolveServerSelfUpdateCapability({
     desktopManaged: serverConfig.mode === "desktop",
+    launcherManaged: launcher.managed,
   });
 
   const descriptor: ExecutionEnvironmentDescriptor = {
@@ -144,9 +147,7 @@ export const make = Effect.gen(function* () {
       threadSnooze: true,
       threadTitleRegeneration: true,
       ...(serverSelfUpdate === null ? {} : { serverSelfUpdate }),
-      ...(serverSelfUpdate === "boot-service" || serverSelfUpdate === "respawn"
-        ? { serverSelfUpdateProgress: true }
-        : {}),
+      ...(serverSelfUpdate === "boot-service" ? { serverSelfUpdateProgress: true } : {}),
     },
   };
 
diff --git a/apps/server/src/keybindings.test.ts b/apps/server/src/keybindings.test.ts
index 2eef6ac8416..252819adacf 100644
--- a/apps/server/src/keybindings.test.ts
+++ b/apps/server/src/keybindings.test.ts
@@ -198,6 +198,8 @@ it.layer(NodeServices.layer)("keybindings", (it) => {
       assert.equal(defaultsByCommand.get("thread.jump.1"), "mod+1");
       assert.equal(defaultsByCommand.get("thread.jump.9"), "mod+9");
       assert.equal(defaultsByCommand.get("modelPicker.toggle"), "mod+shift+m");
+      assert.equal(defaultsByCommand.get("filePicker.toggle"), "mod+p");
+      assert.equal(defaultsByCommand.get("projectSearch.toggle"), "mod+shift+f");
       assert.equal(defaultsByCommand.get("sidebar.toggle"), "mod+b");
       assert.equal(defaultsByCommand.get("rightPanel.toggle"), "mod+alt+b");
       assert.equal(defaultsByCommand.get("terminal.splitVertical"), "mod+shift+d");
diff --git a/apps/server/src/keybindings.ts b/apps/server/src/keybindings.ts
index 18a78fe3623..53f329e8512 100644
--- a/apps/server/src/keybindings.ts
+++ b/apps/server/src/keybindings.ts
@@ -547,19 +547,24 @@ const make = Effect.gen(function* () {
         });
       }
 
-      const nextConfig = [...customConfig, ...missingDefaults];
-      const cappedConfig =
-        nextConfig.length > MAX_KEYBINDINGS_COUNT
-          ? nextConfig.slice(-MAX_KEYBINDINGS_COUNT)
-          : nextConfig;
-      if (nextConfig.length > MAX_KEYBINDINGS_COUNT) {
-        yield* Effect.logWarning("truncating keybindings config to max entries", {
+      // Startup backfill must never evict persisted user rules: append only
+      // the defaults that fit and skip the rest.
+      const availableSlots = Math.max(0, MAX_KEYBINDINGS_COUNT - customConfig.length);
+      const defaultsToAppend = missingDefaults.slice(0, availableSlots);
+      const skippedDefaults = missingDefaults.slice(availableSlots);
+      if (skippedDefaults.length > 0) {
+        yield* Effect.logWarning("skipping default keybinding backfill at max entries", {
           path: keybindingsConfigPath,
           maxEntries: MAX_KEYBINDINGS_COUNT,
+          commands: skippedDefaults.map((rule) => rule.command),
         });
       }
+      if (defaultsToAppend.length === 0) {
+        yield* Cache.invalidate(resolvedConfigCache, resolvedConfigCacheKey);
+        return;
+      }
 
-      yield* writeConfigAtomically(cappedConfig);
+      yield* writeConfigAtomically([...customConfig, ...defaultsToAppend]);
       yield* Cache.invalidate(resolvedConfigCache, resolvedConfigCacheKey);
     }),
   );
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
index 707c87c43c9..e72a100069f 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.test.ts
@@ -277,6 +277,9 @@ describe("CheckpointReactor", () => {
     readonly seedFilesystemCheckpoints?: boolean;
     readonly projectWorkspaceRoot?: string;
     readonly threadWorktreePath?: string | null;
+    readonly threadBranch?: string | null;
+    readonly secondThreadSharingWorktree?: boolean;
+    readonly localStatusRefName?: string | null;
     readonly providerSessionCwd?: string;
     readonly providerName?: ProviderDriverKind;
     readonly gitStatusRefreshCalls?: Array<string>;
@@ -315,7 +318,8 @@ describe("CheckpointReactor", () => {
             isRepo: true,
             hasPrimaryRemote: false,
             isDefaultRef: true,
-            refName: "main",
+            refName:
+              options?.localStatusRefName !== undefined ? options.localStatusRefName : "main",
             hasWorkingTreeChanges: false,
             workingTree: { files: [], insertions: 0, deletions: 0 },
           }),
@@ -370,22 +374,45 @@ describe("CheckpointReactor", () => {
       }),
     );
     await Effect.runPromise(
-      engine.dispatch({
-        type: "thread.create",
-        commandId: CommandId.make("cmd-thread-create"),
-        threadId: ThreadId.make("thread-1"),
-        projectId: asProjectId("project-1"),
-        title: "Thread",
-        modelSelection: {
-          instanceId: ProviderInstanceId.make("codex"),
-          model: "gpt-5-codex",
-        },
-        interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
-        runtimeMode: "approval-required",
-        branch: null,
-        worktreePath: options?.threadWorktreePath ?? cwd,
-        createdAt,
-      }),
+      engine
+        .dispatch({
+          type: "thread.create",
+          commandId: CommandId.make("cmd-thread-create"),
+          threadId: ThreadId.make("thread-1"),
+          projectId: asProjectId("project-1"),
+          title: "Thread",
+          modelSelection: {
+            instanceId: ProviderInstanceId.make("codex"),
+            model: "gpt-5-codex",
+          },
+          interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+          runtimeMode: "approval-required",
+          branch: options?.threadBranch ?? null,
+          worktreePath: options?.threadWorktreePath ?? cwd,
+          createdAt,
+        })
+        .pipe(
+          options?.secondThreadSharingWorktree
+            ? Effect.andThen(
+                engine.dispatch({
+                  type: "thread.create",
+                  commandId: CommandId.make("cmd-thread-create-2"),
+                  threadId: ThreadId.make("thread-2"),
+                  projectId: asProjectId("project-1"),
+                  title: "Thread 2",
+                  modelSelection: {
+                    instanceId: ProviderInstanceId.make("codex"),
+                    model: "gpt-5-codex",
+                  },
+                  interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE,
+                  runtimeMode: "approval-required",
+                  branch: null,
+                  worktreePath: options?.threadWorktreePath ?? cwd,
+                  createdAt,
+                }),
+              )
+            : Effect.asVoid,
+        ),
     );
 
     if (options?.seedFilesystemCheckpoints ?? true) {
@@ -518,6 +545,86 @@ describe("CheckpointReactor", () => {
     expect(gitStatusRefreshCalls).toEqual([harness.cwd]);
   });
 
+  it("adopts a drifted checkout as the thread branch on a dedicated worktree", async () => {
+    const harness = await createHarness({
+      seedFilesystemCheckpoints: false,
+      threadBranch: "t3code/original-branch",
+      localStatusRefName: "t3code/renamed-by-agent",
+    });
+
+    harness.provider.emit({
+      type: "turn.completed",
+      eventId: EventId.make("evt-turn-completed-branch-drift"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
+      threadId: ThreadId.make("thread-1"),
+      turnId: asTurnId("turn-branch-drift"),
+      payload: { state: "completed" },
+    });
+
+    await harness.drain();
+    await waitForEvent(
+      harness.engine,
+      (event) =>
+        event.type === "thread.meta-updated" &&
+        (event as unknown as { payload: { branch?: string } }).payload.branch ===
+          "t3code/renamed-by-agent",
+    );
+
+    const snapshot = await harness.readModel();
+    const thread = snapshot.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.branch).toBe("t3code/renamed-by-agent");
+  });
+
+  it("does not adopt a drifted checkout when the worktree is shared by another thread", async () => {
+    const harness = await createHarness({
+      seedFilesystemCheckpoints: false,
+      threadBranch: "t3code/original-branch",
+      localStatusRefName: "t3code/renamed-by-agent",
+      secondThreadSharingWorktree: true,
+    });
+
+    harness.provider.emit({
+      type: "turn.completed",
+      eventId: EventId.make("evt-turn-completed-branch-drift-shared"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
+      threadId: ThreadId.make("thread-1"),
+      turnId: asTurnId("turn-branch-drift-shared"),
+      payload: { state: "completed" },
+    });
+
+    await harness.drain();
+
+    const snapshot = await harness.readModel();
+    const thread = snapshot.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.branch).toBe("t3code/original-branch");
+  });
+
+  it("does not adopt a temporary placeholder checkout as the thread branch", async () => {
+    const harness = await createHarness({
+      seedFilesystemCheckpoints: false,
+      threadBranch: "t3code/original-branch",
+      localStatusRefName: "t3code/0a1b2c3d",
+    });
+
+    harness.provider.emit({
+      type: "turn.completed",
+      eventId: EventId.make("evt-turn-completed-branch-drift-temp"),
+      provider: ProviderDriverKind.make("codex"),
+      createdAt: "2026-01-01T00:00:00.000Z",
+      threadId: ThreadId.make("thread-1"),
+      turnId: asTurnId("turn-branch-drift-temp"),
+      payload: { state: "completed" },
+    });
+
+    await harness.drain();
+
+    const snapshot = await harness.readModel();
+    const thread = snapshot.threads.find((entry) => entry.id === ThreadId.make("thread-1"));
+    expect(thread?.branch).toBe("t3code/original-branch");
+  });
+
   it("ignores auxiliary thread turn completion while primary turn is active", async () => {
     const harness = await createHarness({ seedFilesystemCheckpoints: false });
     const createdAt = "2026-01-01T00:00:00.000Z";
diff --git a/apps/server/src/orchestration/Layers/CheckpointReactor.ts b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
index 3ba244ddf2c..95adee0cf7f 100644
--- a/apps/server/src/orchestration/Layers/CheckpointReactor.ts
+++ b/apps/server/src/orchestration/Layers/CheckpointReactor.ts
@@ -8,6 +8,7 @@ import {
   TurnId,
   type OrchestrationEvent,
   type ProviderRuntimeEvent,
+  type VcsStatusLocalResult,
 } from "@t3tools/contracts";
 import * as Cause from "effect/Cause";
 import * as Crypto from "effect/Crypto";
@@ -18,6 +19,7 @@ import * as Option from "effect/Option";
 import type * as PlatformError from "effect/PlatformError";
 import * as Stream from "effect/Stream";
 import { makeDrainableWorker } from "@t3tools/shared/DrainableWorker";
+import { isTemporaryWorktreeBranch } from "@t3tools/shared/git";
 
 import { parseTurnDiffFilesFromUnifiedDiff } from "../../checkpointing/Diffs.ts";
 import {
@@ -27,6 +29,7 @@ import {
 import * as CheckpointStore from "../../checkpointing/CheckpointStore.ts";
 import { ProviderService } from "../../provider/Services/ProviderService.ts";
 import { CheckpointReactor, type CheckpointReactorShape } from "../Services/CheckpointReactor.ts";
+import { forkParked } from "../../serverActivation.ts";
 import { OrchestrationEngineService } from "../Services/OrchestrationEngine.ts";
 import { ProjectionSnapshotQuery } from "../Services/ProjectionSnapshotQuery.ts";
 import { RuntimeReceiptBus } from "../Services/RuntimeReceiptBus.ts";
@@ -534,16 +537,93 @@ const make = Effect.gen(function* () {
       return;
     }
 
-    yield* vcsStatusBroadcaster.refreshLocalStatus(sessionRuntime.value.cwd).pipe(
+    const local = yield* vcsStatusBroadcaster.refreshLocalStatus(sessionRuntime.value.cwd).pipe(
       Effect.catch((error) =>
         Effect.logWarning("failed to refresh local git status after turn completion", {
           threadId: event.threadId,
           turnId: event.turnId ?? null,
           cwd: sessionRuntime.value.cwd,
           detail: error.message,
-        }),
+        }).pipe(Effect.as(null)),
       ),
     );
+    if (local !== null) {
+      yield* followWorktreeBranchDrift({
+        threadId: event.threadId,
+        cwd: sessionRuntime.value.cwd,
+        local,
+      });
+    }
+  });
+
+  // A `git checkout` run inside a thread's dedicated worktree (by an agent or
+  // the user) bypasses T3's commands, so the thread's recorded branch goes
+  // stale. Since #4460 the client only attributes PR state to a thread when
+  // the checked-out branch equals the recorded one, so stale metadata silently
+  // orphans the thread's PR. Follow the drift here: adopt the checked-out
+  // branch as the thread's branch, but only when the worktree belongs to
+  // exactly this thread — for shared cwds the strict matching is the point.
+  const followWorktreeBranchDrift = Effect.fn("followWorktreeBranchDrift")(function* (input: {
+    readonly threadId: ThreadId;
+    readonly cwd: string;
+    readonly local: VcsStatusLocalResult;
+  }) {
+    // Detached HEAD has no branch to adopt; a temporary placeholder checkout
+    // means the first-turn auto-rename is still in flight — don't race it.
+    const checkedOutBranch = input.local.refName;
+    if (checkedOutBranch === null || isTemporaryWorktreeBranch(checkedOutBranch)) {
+      return;
+    }
+
+    yield* Effect.gen(function* () {
+      const thread = yield* projectionSnapshotQuery
+        .getThreadShellById(input.threadId)
+        .pipe(Effect.map(Option.getOrUndefined));
+      if (
+        !thread ||
+        thread.branch === null ||
+        thread.branch === checkedOutBranch ||
+        thread.worktreePath === null ||
+        thread.worktreePath !== input.cwd ||
+        isTemporaryWorktreeBranch(thread.branch)
+      ) {
+        return;
+      }
+
+      const shell = yield* projectionSnapshotQuery.getShellSnapshot();
+      const worktreeIsShared = shell.threads.some(
+        (other) => other.id !== thread.id && other.worktreePath === thread.worktreePath,
+      );
+      if (worktreeIsShared) {
+        return;
+      }
+
+      // expectedBranch makes this a compare-and-swap in the decider: if the
+      // recorded branch moved between our read and the dispatch (rename,
+      // concurrent drift-follow), the stale update is dropped.
+      yield* orchestrationEngine.dispatch({
+        type: "thread.meta.update",
+        commandId: yield* serverCommandId("worktree-branch-drift"),
+        threadId: thread.id,
+        branch: checkedOutBranch,
+        expectedBranch: thread.branch,
+      });
+      yield* Effect.logInfo("thread branch followed worktree checkout", {
+        threadId: thread.id,
+        previousBranch: thread.branch,
+        branch: checkedOutBranch,
+      });
+    }).pipe(
+      Effect.catchCause((cause) => {
+        if (Cause.hasInterruptsOnly(cause)) {
+          return Effect.failCause(cause);
+        }
+        return Effect.logWarning("failed to follow worktree branch drift", {
+          threadId: input.threadId,
+          cause: Cause.pretty(cause),
+        });
+      }),
+    );
   });
 
   const ensurePreTurnBaselineFromDomainTurnStart = Effect.fn(
@@ -833,7 +913,7 @@ const make = Effect.gen(function* () {
   const worker = yield* makeDrainableWorker(processInputSafely);
 
   const start: CheckpointReactorShape["start"] = Effect.fn("start")(function* () {
-    yield* Effect.forkScoped(
+    yield* forkParked(
       Stream.runForEach(orchestrationEngine.streamDomainEvents, (event) => {
         if (
           event.type !== "thread.turn-start-requested" &&
@@ -847,7 +927,7 @@ const make = Effect.gen(function* () {
       }),
     );
 
-    yield* Effect.forkScoped(
+    yield* forkParked(
       Stream.runForEach(providerService.streamEvents, (event) => {
         if (event.type !== "turn.started" && event.type !== "turn.completed") {
           return Effect.void;
diff --git a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
index 6ddc9f18cb3..1135fd579e7 100644
--- a/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
+++ b/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts
@@ -38,6 +38,7 @@ import {
   ProviderCommandReactor,
   type ProviderCommandReactorShape,
 } from "../Services/ProviderCommandReactor.ts";
+import { forkParked, ServerActivation } from "../../serverActivation.ts";
 import {
   resolveSourceControlWriterModelSelection,
   ServerSettingsService,
@@ -899,19 +900,25 @@ const make = Effect.gen(function* () {
       ...(input.title !== undefined ? { title: input.title } : {}),
     });
   });
-  const clearInterruptedThreadTitleRegenerations = Effect.fn(
-    "clearInterruptedThreadTitleRegenerations",
+  const findInterruptedThreadTitleRegenerations = Effect.fn(
+    "findInterruptedThreadTitleRegenerations",
   )(function* () {
     const readModel = yield* projectionSnapshotQuery.getCommandReadModel();
+    return readModel.threads.flatMap((thread) => {
+      const requestId = thread.titleRegeneration?.requestId;
+      return requestId === undefined ? [] : [{ threadId: thread.id, requestId }];
+    });
+  });
+  const clearInterruptedThreadTitleRegenerations = Effect.fn(
+    "clearInterruptedThreadTitleRegenerations",
+  )(function* (
+    interrupted: ReadonlyArray<{ readonly threadId: ThreadId; readonly requestId: CommandId }>,
+  ) {
     yield* Effect.forEach(
-      readModel.threads,
-      (thread) => {
-        const requestId = thread.titleRegeneration?.requestId;
-        if (requestId === undefined) {
-          return Effect.void;
-        }
+      interrupted,
+      ({ threadId, requestId }) => {
         return dispatchThreadTitleRegenerationCompletion({
-          threadId: thread.id,
+          threadId,
           requestId,
         }).pipe(
           Effect.catchCause((cause) => {
@@ -921,7 +928,7 @@ const make = Effect.gen(function* () {
             return Effect.logWarning(
               "provider command reactor failed to clear interrupted title regeneration",
               {
-                threadId: thread.id,
+                threadId,
                 cause: Cause.pretty(cause),
               },
             );
@@ -1304,7 +1311,7 @@ const make = Effect.gen(function* () {
     processDomainEvent(event).pipe(
       Effect.catchCause((cause) => {
         if (Cause.hasInterruptsOnly(cause)) {
-          return Effect.failCause(cause);
+          return Effect.interrupt;
         }
         return Effect.logWarning("provider command reactor failed to process event", {
           eventType: event.type,
@@ -1316,6 +1323,17 @@ const make = Effect.gen(function* () {
   const worker = yield* makeDrainableWorker(processDomainEventSafely);
 
   const start: ProviderCommandReactorShape["start"] = Effect.fn("start")(function* () {
+    const interruptedTitleRegenerations = yield* findInterruptedThreadTitleRegenerations().pipe(
+      Effect.catchCause((cause) => {
+        if (Cause.hasInterruptsOnly(cause)) {
+          return Effect.interrupt;
+        }
+        return Effect.logWarning(
+          "provider command reactor failed to find interrupted title regenerations",
+          { cause: Cause.pretty(cause) },
+        ).pipe(Effect.as([]));
+      }),
+    );
     const processEvent = Effect.fn("processEvent")(function* (event: OrchestrationEvent) {
       if (
         (event.type === "thread.meta-updated" && event.payload.regenerateTitle === true) ||
@@ -1330,14 +1348,14 @@ const make = Effect.gen(function* () {
       }
     });
 
-    yield* Effect.forkScoped(
-      Stream.runForEach(orchestrationEngine.streamDomainEvents, processEvent),
-    );
+    yield* forkParked(Stream.runForEach(orchestrationEngine.streamDomainEvents, processEvent));
 
     // The domain event stream is hot, so work pending before this reactor
     // starts cannot be resumed. Correlated completions only clear the request
     // captured here, leaving any newer request untouched.
-    yield* clearInterruptedThreadTitleRegenerations().pipe(
+    const clearInterrupted = clearInterruptedThreadTitleRegenerations(
+      interruptedTitleRegenerations,
+    ).pipe(
       Effect.catchCause((cause) => {
         if (Cause.hasInterruptsOnly(cause)) {
           return Effect.interrupt;
@@ -1350,6 +1368,12 @@ const make = Effect.gen(function* () {
         );
       }),
     );
+    const activation = yield* ServerActivation;
+    if (activation === undefined) {
+      yield* clearInterrupted;
+    } else {
+      yield* forkParked(clearInterrupted);
+    }
   });
 
   return {
diff --git a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
index a8a51b30260..c8d619270d3 100644
--- a/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
+++ b/apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts
@@ -37,6 +37,7 @@ import {
   ProviderRuntimeIngestionService,
   type ProviderRuntimeIngestionShape,
 } from "../Services/ProviderRuntimeIngestion.ts";
+import { forkParked } from "../../serverActivation.ts";
 import { ServerSettingsService } from "../../serverSettings.ts";
 
 const providerTurnKey = (threadId: ThreadId, turnId: TurnId) => `${threadId}:${turnId}`;
@@ -1804,12 +1805,12 @@ const make = Effect.gen(function* () {
 
   const start: ProviderRuntimeIngestionShape["start"] = () =>
     Effect.gen(function* () {
-      yield* Effect.forkScoped(
+      yield* forkParked(
         Stream.runForEach(providerService.streamEvents, (event) =>
           worker.enqueue({ source: "runtime", event }),
         ),
       );
-      yield* Effect.forkScoped(
+      yield* forkParked(
         Stream.runForEach(orchestrationEngine.streamDomainEvents, (event) => {
           if (event.type !== "thread.turn-start-requested") {
             return Effect.void;
diff --git a/apps/server/src/orchestration/Layers/ThreadDeletionReactor.ts b/apps/server/src/orchestration/Layers/ThreadDeletionReactor.ts
index 7d8a24069a3..a026f5ad81b 100644
--- a/apps/server/src/orchestration/Layers/ThreadDeletionReactor.ts
+++ b/apps/server/src/orchestration/Layers/ThreadDeletionReactor.ts
@@ -12,6 +12,7 @@ import {
   ThreadDeletionReactor,
   type ThreadDeletionReactorShape,
 } from "../Services/ThreadDeletionReactor.ts";
+import { forkParked } from "../../serverActivation.ts";
 
 type ThreadDeletedEvent = Extract<OrchestrationEvent, { type: "thread.deleted" }>;
 
@@ -80,7 +81,7 @@ const make = Effect.gen(function* () {
   const worker = yield* makeDrainableWorker(processThreadDeletedSafely);
 
   const start: ThreadDeletionReactorShape["start"] = Effect.fn("start")(function* () {
-    yield* Effect.forkScoped(
+    yield* forkParked(
       Stream.runForEach(orchestrationEngine.streamDomainEvents, (event) => {
         if (event.type !== "thread.deleted") {
           return Effect.void;
diff --git a/apps/server/src/orchestration/http.ts b/apps/server/src/orchestration/http.ts
index 659665e47b5..9a5c8c0be39 100644
--- a/apps/server/src/orchestration/http.ts
+++ b/apps/server/src/orchestration/http.ts
@@ -32,8 +32,13 @@ export const orchestrationHttpApiLayer = HttpApiBuilder.group(
         Effect.fn("environment.orchestration.snapshot")(function* (args) {
           yield* annotateEnvironmentRequest(args.endpoint.name);
           yield* requireEnvironmentScope(AuthOrchestrationReadScope);
+          // Serve the lightweight command read model (thread bodies empty)
+          // instead of the fully hydrated snapshot. Hydrating every message
+          // and activity payload in the database has OOM-killed servers, and
+          // the route's only consumer (the project CLI) reads projects alone —
+          // UI clients load the shell and per-thread snapshots instead.
           return yield* projectionSnapshotQuery
-            .getSnapshot()
+            .getCommandReadModel()
             .pipe(
               Effect.catch((cause) =>
                 failEnvironmentInternal("orchestration_snapshot_failed", cause),
diff --git a/apps/server/src/os-jank.test.ts b/apps/server/src/os-jank.test.ts
new file mode 100644
index 00000000000..a157efb665f
--- /dev/null
+++ b/apps/server/src/os-jank.test.ts
@@ -0,0 +1,40 @@
+import * as NodeOS from "node:os";
+import { assert, it } from "vite-plus/test";
+
+import { hydratePosixHome } from "./os-jank.ts";
+
+it("hydrates HOME for minimal service environments from the user account", () => {
+  const env: NodeJS.ProcessEnv = {};
+
+  hydratePosixHome(env);
+
+  assert.equal(env.HOME, NodeOS.userInfo().homedir);
+});
+
+it("hydrates HOME independently of a blank process HOME", () => {
+  const originalHome = process.env.HOME;
+  const env: NodeJS.ProcessEnv = { HOME: " " };
+
+  try {
+    process.env.HOME = " ";
+    hydratePosixHome(env);
+  } finally {
+    if (originalHome === undefined) {
+      delete process.env.HOME;
+    } else {
+      process.env.HOME = originalHome;
+    }
+  }
+
+  assert.equal(env.HOME, NodeOS.userInfo().homedir);
+});
+
+it("preserves an explicitly configured HOME", () => {
+  const env: NodeJS.ProcessEnv = { HOME: "/custom/home" };
+
+  hydratePosixHome(env, () => {
+    throw new Error("HOME lookup should not run");
+  });
+
+  assert.equal(env.HOME, "/custom/home");
+});
diff --git a/apps/server/src/os-jank.ts b/apps/server/src/os-jank.ts
index bc72758bc71..18ddbc66c0c 100644
--- a/apps/server/src/os-jank.ts
+++ b/apps/server/src/os-jank.ts
@@ -36,6 +36,18 @@ function hydratePosixPath(env: NodeJS.ProcessEnv, platform: NodeJS.Platform): vo
   }
 }
 
+export function hydratePosixHome(
+  env: NodeJS.ProcessEnv,
+  resolveHomeDir = () => NodeOS.userInfo().homedir,
+): void {
+  if ((env.HOME?.trim() ?? "").length > 0) return;
+
+  const homeDir = resolveHomeDir();
+  if (homeDir.length > 0) {
+    env.HOME = homeDir;
+  }
+}
+
 export const fixPath = Effect.fn("fixPath")(function* (): Effect.fn.Return<
   void,
   never,
@@ -63,6 +75,13 @@ export const fixPath = Effect.fn("fixPath")(function* (): Effect.fn.Return<
 
   if (platform !== "darwin" && platform !== "linux") return;
 
+  yield* Effect.sync(() => hydratePosixHome(env)).pipe(
+    Effect.catchDefect((defect) =>
+      Effect.sync(() => {
+        logPathHydrationWarning("Failed to hydrate HOME from the user account.", defect);
+      }),
+    ),
+  );
   yield* Effect.sync(() => hydratePosixPath(env, platform)).pipe(
     Effect.catchDefect((defect) =>
       Effect.sync(() => {
diff --git a/apps/server/src/persistence/Layers/Sqlite.ts b/apps/server/src/persistence/Layers/Sqlite.ts
index dfd338b7159..3cfdb5c5c76 100644
--- a/apps/server/src/persistence/Layers/Sqlite.ts
+++ b/apps/server/src/persistence/Layers/Sqlite.ts
@@ -7,6 +7,7 @@ import type { SqlError } from "effect/unstable/sql/SqlError";
 
 import { runMigrations } from "../Migrations.ts";
 import { ServerConfig } from "../../config.ts";
+import * as ServiceLauncherClient from "../../cloud/serviceLauncherClient.ts";
 
 type RuntimeSqliteLayerConfig = {
   readonly filename: string;
@@ -30,24 +31,28 @@ const makeRuntimeSqliteLayer = Effect.fn("makeRuntimeSqliteLayer")(function* (
   return clientModule.layer(config);
 }, Layer.unwrap);
 
-const setup = Layer.effectDiscard(
-  Effect.gen(function* () {
-    const sql = yield* SqlClient.SqlClient;
-    yield* sql`PRAGMA journal_mode = WAL;`;
-    yield* sql`PRAGMA foreign_keys = ON;`;
-    yield* runMigrations();
-  }),
-);
+const setup = (trial: boolean) =>
+  Layer.effectDiscard(
+    Effect.gen(function* () {
+      const sql = yield* SqlClient.SqlClient;
+      yield* sql`PRAGMA foreign_keys = ON;`;
+      if (!trial) {
+        yield* sql`PRAGMA journal_mode = WAL;`;
+        yield* runMigrations();
+      }
+    }),
+  );
 
 export const makeSqlitePersistenceLive = Effect.fn("makeSqlitePersistenceLive")(function* (
   dbPath: string,
+  options?: { readonly trial?: boolean },
 ) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
   yield* fs.makeDirectory(path.dirname(dbPath), { recursive: true });
 
   return Layer.provideMerge(
-    setup,
+    setup(options?.trial === true),
     makeRuntimeSqliteLayer({
       filename: dbPath,
       spanAttributes: {
@@ -59,10 +64,14 @@ export const makeSqlitePersistenceLive = Effect.fn("makeSqlitePersistenceLive")(
 }, Layer.unwrap);
 
 export const SqlitePersistenceMemory = Layer.provideMerge(
-  setup,
+  setup(false),
   makeRuntimeSqliteLayer({ filename: ":memory:" }),
 );
 
 export const layerConfig = Layer.unwrap(
-  Effect.map(Effect.service(ServerConfig), ({ dbPath }) => makeSqlitePersistenceLive(dbPath)),
+  Effect.gen(function* () {
+    const { dbPath } = yield* ServerConfig;
+    const launcher = yield* ServiceLauncherClient.resolveServiceLauncherMode();
+    return makeSqlitePersistenceLive(dbPath, { trial: launcher.trial });
+  }),
 );
diff --git a/apps/server/src/persistence/Migrations.ts b/apps/server/src/persistence/Migrations.ts
index 95cb6b17f84..b24aeb503b5 100644
--- a/apps/server/src/persistence/Migrations.ts
+++ b/apps/server/src/persistence/Migrations.ts
@@ -9,8 +9,8 @@
  */
 
 import * as Migrator from "effect/unstable/sql/Migrator";
-import * as Layer from "effect/Layer";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 
 // Import all migrations statically
 import Migration0001 from "./Migrations/001_OrchestrationEvents.ts";
@@ -97,6 +97,8 @@ export const migrationEntries = [
   [35, "ProjectionThreadTitleRegeneration", Migration0035],
 ] as const;
 
+export const migrationManifest = migrationEntries.map(([id, name]) => [id, name] as const);
+
 export const makeMigrationLoader = (throughId?: number) =>
   Migrator.fromRecord(
     Object.fromEntries(
diff --git a/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts b/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
index ab6e5992990..19907ece888 100644
--- a/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
+++ b/apps/server/src/provider/Layers/ClaudeCapabilitiesProbe.test.ts
@@ -9,11 +9,27 @@ import * as Schema from "effect/Schema";
 import {
   buildClaudeCapabilitiesProbeQueryOptions,
   CLAUDE_CAPABILITIES_PROBE_SETTING_SOURCES,
+  isLegacyClaudeModel,
   probeClaudeCapabilities,
 } from "./ClaudeProvider.ts";
 
 const decodeClaudeSettings = Schema.decodeSync(ClaudeSettings);
 
+it("keeps only the Claude 5 family out of legacy models", () => {
+  assert.deepStrictEqual(
+    ["claude-fable-5", "claude-opus-5", "claude-sonnet-5", "claude-opus-4-8"].map((model) => [
+      model,
+      isLegacyClaudeModel(model),
+    ]),
+    [
+      ["claude-fable-5", false],
+      ["claude-opus-5", false],
+      ["claude-sonnet-5", false],
+      ["claude-opus-4-8", true],
+    ],
+  );
+});
+
 it("isolates Claude capability probes without dropping workspace setting sources", () => {
   const abortController = new AbortController();
   const options = buildClaudeCapabilitiesProbeQueryOptions({
diff --git a/apps/server/src/provider/Layers/ClaudeProvider.ts b/apps/server/src/provider/Layers/ClaudeProvider.ts
index 96202ecd952..0e019f003c7 100644
--- a/apps/server/src/provider/Layers/ClaudeProvider.ts
+++ b/apps/server/src/provider/Layers/ClaudeProvider.ts
@@ -56,7 +56,13 @@ const MINIMUM_CLAUDE_FABLE_5_VERSION = "2.1.169";
 const MINIMUM_CLAUDE_OPUS_4_8_VERSION = "2.1.154";
 const MINIMUM_CLAUDE_OPUS_4_7_VERSION = "2.1.111";
 
-const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = [
+const CURRENT_CLAUDE_MODELS = new Set(["claude-fable-5", "claude-opus-5", "claude-sonnet-5"]);
+
+export function isLegacyClaudeModel(model: string): boolean {
+  return !CURRENT_CLAUDE_MODELS.has(model);
+}
+
+const CLAUDE_MODEL_CATALOG: ReadonlyArray<ServerProviderModel> = [
   {
     slug: "claude-fable-5",
     name: "Claude Fable 5",
@@ -309,6 +315,10 @@ const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = [
   },
 ];
 
+const BUILT_IN_MODELS: ReadonlyArray<ServerProviderModel> = CLAUDE_MODEL_CATALOG.map((model) =>
+  isLegacyClaudeModel(model.slug) ? { ...model, isLegacy: true } : model,
+);
+
 function supportsClaudeOpus5(version: string | null | undefined): boolean {
   return version ? compareSemverVersions(version, MINIMUM_CLAUDE_OPUS_5_VERSION) >= 0 : false;
 }
diff --git a/apps/server/src/provider/Layers/CodexProvider.test.ts b/apps/server/src/provider/Layers/CodexProvider.test.ts
index 2aeebdb2ccd..26e77f82a79 100644
--- a/apps/server/src/provider/Layers/CodexProvider.test.ts
+++ b/apps/server/src/provider/Layers/CodexProvider.test.ts
@@ -1,6 +1,25 @@
 import { assert, it } from "@effect/vitest";
 
-import { applyPreferredCodexDefaultModel, mapCodexModelCapabilities } from "./CodexProvider.ts";
+import {
+  applyPreferredCodexDefaultModel,
+  isLegacyCodexModel,
+  mapCodexModelCapabilities,
+} from "./CodexProvider.ts";
+
+it("keeps only the GPT-5.6 Codex family out of legacy models", () => {
+  assert.deepStrictEqual(
+    ["gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol", "gpt-5.4"].map((model) => [
+      model,
+      isLegacyCodexModel(model),
+    ]),
+    [
+      ["gpt-5.6-luna", false],
+      ["gpt-5.6-terra", false],
+      ["gpt-5.6-sol", false],
+      ["gpt-5.4", true],
+    ],
+  );
+});
 
 it("maps current Codex model capability fields", () => {
   const capabilities = mapCodexModelCapabilities({
diff --git a/apps/server/src/provider/Layers/CodexProvider.ts b/apps/server/src/provider/Layers/CodexProvider.ts
index 1ed9c750c18..5c0f76dff4e 100644
--- a/apps/server/src/provider/Layers/CodexProvider.ts
+++ b/apps/server/src/provider/Layers/CodexProvider.ts
@@ -62,6 +62,11 @@ const REASONING_EFFORT_LABELS: Readonly<Record<string, string>> = {
 };
 
 const DEFAULT_SERVICE_TIER_ID = "default";
+const CURRENT_CODEX_MODELS = new Set(["gpt-5.6-luna", "gpt-5.6-terra", "gpt-5.6-sol"]);
+
+export function isLegacyCodexModel(model: string): boolean {
+  return !CURRENT_CODEX_MODELS.has(model);
+}
 
 function reasoningEffortLabel(reasoningEffort: string): string {
   return REASONING_EFFORT_LABELS[reasoningEffort] ?? reasoningEffort;
@@ -190,6 +195,7 @@ function parseCodexModelListResponse(
     name: toDisplayName(model),
     isCustom: false,
     ...(model.isDefault ? { isDefault: true } : {}),
+    ...(isLegacyCodexModel(model.model) ? { isLegacy: true } : {}),
     capabilities: mapCodexModelCapabilities(model),
   }));
 }
diff --git a/apps/server/src/provider/Layers/ProviderSessionReaper.ts b/apps/server/src/provider/Layers/ProviderSessionReaper.ts
index ca396b40596..8eccd52fb2c 100644
--- a/apps/server/src/provider/Layers/ProviderSessionReaper.ts
+++ b/apps/server/src/provider/Layers/ProviderSessionReaper.ts
@@ -11,6 +11,7 @@ import {
   ProviderSessionReaper,
   type ProviderSessionReaperShape,
 } from "../Services/ProviderSessionReaper.ts";
+import { forkParked } from "../../serverActivation.ts";
 import { ProviderService } from "../Services/ProviderService.ts";
 
 const DEFAULT_INACTIVITY_THRESHOLD_MS = 30 * 60 * 1000;
@@ -105,7 +106,7 @@ const makeProviderSessionReaper = (options?: ProviderSessionReaperLiveOptions) =
 
     const start: ProviderSessionReaperShape["start"] = () =>
       Effect.gen(function* () {
-        yield* Effect.forkScoped(
+        yield* forkParked(
           sweep.pipe(
             Effect.catch((error: unknown) =>
               Effect.logWarning("provider.session.reaper.sweep-failed", {
diff --git a/apps/server/src/relay/AgentAwarenessRelay.ts b/apps/server/src/relay/AgentAwarenessRelay.ts
index 58de98f1ca1..2a4de7eda91 100644
--- a/apps/server/src/relay/AgentAwarenessRelay.ts
+++ b/apps/server/src/relay/AgentAwarenessRelay.ts
@@ -44,6 +44,7 @@ import { getOrCreateEnvironmentKeyPairFromSecretStore } from "../cloud/environme
 import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
 import * as OrchestrationEngine from "../orchestration/Services/OrchestrationEngine.ts";
 import * as ProjectionSnapshotQuery from "../orchestration/Services/ProjectionSnapshotQuery.ts";
+import { forkParked } from "../serverActivation.ts";
 
 export class AgentAwarenessRelay extends Context.Service<
   AgentAwarenessRelay,
@@ -599,12 +600,12 @@ export const make = Effect.gen(function* () {
           });
           break;
       }
-      yield* Effect.forkScoped(
+      yield* forkParked(
         Effect.sleep("1 second").pipe(
           Effect.andThen(publishActiveThreadsOnceWhenConfigured(startupState !== "enabled")),
         ),
       );
-      yield* Effect.forkScoped(
+      yield* forkParked(
         Stream.runForEach(orchestrationEngine.streamDomainEvents, (event) => {
           const threadId = eventThreadId(event);
           if (threadId === null) {
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index fff71dbb4e7..74d3fd2d594 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -89,6 +89,7 @@ import * as ProviderRegistry from "./provider/Services/ProviderRegistry.ts";
 import { makeManualOnlyProviderMaintenanceCapabilities } from "./provider/providerMaintenance.ts";
 import * as ServerLifecycleEvents from "./serverLifecycleEvents.ts";
 import * as ServerRuntimeStartup from "./serverRuntimeStartup.ts";
+import * as ServiceLauncherClient from "./cloud/serviceLauncherClient.ts";
 import * as ServerSettings from "./serverSettings.ts";
 import * as TerminalManager from "./terminal/Manager.ts";
 import * as PreviewManager from "./preview/Manager.ts";
@@ -550,10 +551,13 @@ const buildAppUnderTest = (options?: {
       ),
     );
 
-    const servedRoutesLayer = HttpRouter.serve(makeRoutesLayer, {
-      disableListenLog: true,
-      disableLogger: true,
-    }).pipe(
+    const servedRoutesLayer = HttpRouter.serve(
+      makeRoutesLayer.pipe(Layer.provide(ServiceLauncherClient.layer)),
+      {
+        disableListenLog: true,
+        disableLogger: true,
+      },
+    ).pipe(
       Layer.provide(
         Layer.mock(Keybindings.Keybindings)({
           loadConfigState: Effect.succeed({
@@ -1318,6 +1322,39 @@ const getWsServerUrl = (
   });
 
 it.layer(NodeServices.layer)("server router seam", (it) => {
+  it.effect("parks HTTP ingress until command readiness", () =>
+    Effect.gen(function* () {
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const staticDir = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-router-gate-" });
+      yield* fileSystem.writeFileString(path.join(staticDir, "index.html"), "ready");
+      const entered = yield* Deferred.make<void>();
+      const ready = yield* Deferred.make<void>();
+      const completed = yield* Deferred.make<void>();
+
+      yield* buildAppUnderTest({
+        config: { staticDir },
+        layers: {
+          serverRuntimeStartup: {
+            awaitCommandReady: Deferred.succeed(entered, undefined).pipe(
+              Effect.andThen(Deferred.await(ready)),
+            ),
+          },
+        },
+      });
+      const request = yield* HttpClient.get("/").pipe(
+        Effect.tap(() => Deferred.succeed(completed, undefined)),
+        Effect.forkChild,
+      );
+      yield* Deferred.await(entered);
+      assert.isFalse(yield* Deferred.isDone(completed));
+
+      yield* Deferred.succeed(ready, undefined);
+      assert.equal((yield* Fiber.join(request)).status, 200);
+      assert.isTrue(yield* Deferred.isDone(completed));
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("serves static index content for GET / when staticDir is configured", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
@@ -6005,6 +6042,149 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest), TestClock.withLive),
   );
 
+  it.effect("subscribeThread sends a fresh snapshot instead of replaying a large gap", () =>
+    Effect.gen(function* () {
+      let readEventsCalls = 0;
+      const thread = makeDefaultOrchestrationReadModel().threads[0]!;
+
+      yield* buildAppUnderTest({
+        layers: {
+          orchestrationEngine: {
+            // Head is far ahead of the client's afterSequence (gap > 1000).
+            latestSequence: Effect.succeed(100_000),
+            readEvents: () =>
+              Stream.sync(() => {
+                readEventsCalls += 1;
+                return {} as OrchestrationEvent;
+              }),
+          },
+          projectionSnapshotQuery: {
+            getThreadDetailSnapshot: () =>
+              Effect.succeed(Option.some({ snapshotSequence: 100_000, thread })),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const items = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+            threadId: defaultThreadId,
+            afterSequence: 5,
+            requestCompletionMarker: true,
+          }).pipe(Stream.take(2), Stream.runCollect),
+        ),
+      );
+
+      const [first, second] = Array.from(items);
+      // Large gap => fresh thread snapshot, and the global replay never starts.
+      assert.equal(first?.kind, "snapshot");
+      if (first?.kind === "snapshot") {
+        assert.equal(first.snapshot.thread.id, defaultThreadId);
+        assert.equal(first.snapshot.snapshotSequence, 100_000);
+      }
+      assert.equal(second?.kind, "synchronized");
+      assert.equal(readEventsCalls, 0);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("subscribeThread replaces a cursor ahead of the authoritative head", () =>
+    Effect.gen(function* () {
+      let readEventsCalls = 0;
+      const thread = makeDefaultOrchestrationReadModel().threads[0]!;
+
+      yield* buildAppUnderTest({
+        layers: {
+          orchestrationEngine: {
+            latestSequence: Effect.succeed(5),
+            readEvents: () =>
+              Stream.sync(() => {
+                readEventsCalls += 1;
+                return {} as OrchestrationEvent;
+              }),
+          },
+          projectionSnapshotQuery: {
+            getThreadDetailSnapshot: () =>
+              Effect.succeed(Option.some({ snapshotSequence: 5, thread })),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const first = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+            threadId: defaultThreadId,
+            afterSequence: 10,
+          }).pipe(Stream.runHead),
+        ),
+      );
+
+      assert.equal(Option.getOrThrow(first).kind, "snapshot");
+      assert.equal(readEventsCalls, 0);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("subscribeThread bounds catch-up replay to the captured head", () =>
+    Effect.gen(function* () {
+      let replayLimit: number | undefined;
+      const now = "2026-01-01T00:00:00.000Z";
+      const messageEvent = {
+        sequence: 3,
+        eventId: EventId.make("event-replay-message"),
+        aggregateKind: "thread",
+        aggregateId: defaultThreadId,
+        occurredAt: now,
+        commandId: null,
+        causationEventId: null,
+        correlationId: null,
+        metadata: {},
+        type: "thread.message-sent",
+        payload: {
+          threadId: defaultThreadId,
+          messageId: MessageId.make("message-replay"),
+          role: "user",
+          text: "Replayed message",
+          turnId: null,
+          streaming: false,
+          createdAt: now,
+          updatedAt: now,
+        },
+      } satisfies Extract<OrchestrationEvent, { type: "thread.message-sent" }>;
+
+      yield* buildAppUnderTest({
+        layers: {
+          orchestrationEngine: {
+            latestSequence: Effect.succeed(50),
+            readEvents: (_afterSequence, limit) => {
+              replayLimit = limit;
+              return Stream.make(messageEvent);
+            },
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const items = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.subscribeThread]({
+            threadId: defaultThreadId,
+            afterSequence: 0,
+            requestCompletionMarker: true,
+          }).pipe(Stream.take(2), Stream.runCollect),
+        ),
+      );
+
+      const [first, second] = Array.from(items);
+      assert.equal(first?.kind, "event");
+      assert.equal(first?.kind === "event" ? first.event.sequence : null, 3);
+      assert.equal(second?.kind, "synchronized");
+      // The replay is bounded to the head captured before the read, not
+      // Number.MAX_SAFE_INTEGER.
+      assert.equal(replayLimit, 50);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("subscribeShell sends a fresh snapshot instead of replaying a large gap", () =>
     Effect.gen(function* () {
       let readEventsCalls = 0;
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index e0d36e99bc9..05657af6d48 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -1,6 +1,9 @@
 import { EnvironmentHttpApi } from "@t3tools/contracts";
+import * as Duration from "effect/Duration";
+import * as Deferred from "effect/Deferred";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
+import * as Schedule from "effect/Schedule";
 import { FetchHttpClient, HttpRouter, HttpServer } from "effect/unstable/http";
 import * as HttpApiBuilder from "effect/unstable/httpapi/HttpApiBuilder";
 
@@ -89,6 +92,7 @@ import * as CloudManagedEndpointRuntime from "./cloud/ManagedEndpointRuntime.ts"
 import * as CloudCliTokenManager from "./cloud/CliTokenManager.ts";
 import * as CloudCliState from "./cloud/CliState.ts";
 import * as ServerSelfUpdate from "./cloud/selfUpdate.ts";
+import * as ServiceLauncherClient from "./cloud/serviceLauncherClient.ts";
 import * as ProcessDiagnostics from "./diagnostics/ProcessDiagnostics.ts";
 import * as ProcessResourceMonitor from "./diagnostics/ProcessResourceMonitor.ts";
 import * as TraceDiagnostics from "./diagnostics/TraceDiagnostics.ts";
@@ -107,6 +111,7 @@ import { orchestrationHttpApiLayer } from "./orchestration/http.ts";
 import * as NetService from "@t3tools/shared/Net";
 import * as RelayClient from "@t3tools/shared/relayClient";
 import { disableTailscaleServe, ensureTailscaleServe } from "@t3tools/tailscale";
+import { forkParked, ServerActivation } from "./serverActivation.ts";
 
 // Effect's default preemptive shutdown waits 20s before finalizing request scopes.
 // T3's primary transport is long-lived WebSocket RPC, whose Effect scope finalizer
@@ -394,8 +399,12 @@ const RuntimeDependenciesLive = RuntimeCoreDependenciesLive.pipe(
   Layer.provide(NetService.layer),
 );
 
-const RuntimeServicesLive = ServerRuntimeStartup.layer.pipe(
-  Layer.provideMerge(RuntimeDependenciesLive),
+const commandReadinessLayer = HttpRouter.middleware(
+  (httpEffect) =>
+    Effect.flatMap(ServerRuntimeStartup.ServerRuntimeStartup, (startup) =>
+      startup.awaitCommandReady.pipe(Effect.orDie, Effect.andThen(httpEffect)),
+    ),
+  { global: true },
 );
 
 export const makeRoutesLayer = Layer.mergeAll(
@@ -416,6 +425,7 @@ export const makeRoutesLayer = Layer.mergeAll(
 ).pipe(
   Layer.provide(PreviewAutomationBroker.layer),
   Layer.provide(ServerSelfUpdate.layer),
+  Layer.provide(commandReadinessLayer),
   Layer.provide(browserApiCorsLayer),
   Layer.provide(httpCompressionLayer),
 );
@@ -423,6 +433,14 @@ export const makeRoutesLayer = Layer.mergeAll(
 export const makeServerLayer = Layer.unwrap(
   Effect.gen(function* () {
     const config = yield* ServerConfig.ServerConfig;
+    const activation = yield* Deferred.make<void>();
+    const awaitActivation = Deferred.await(activation);
+    const activationLayer = Layer.succeed(ServerActivation, awaitActivation);
+    const runtimeStateParked = yield* Deferred.make<void>();
+    const tailscaleParked = yield* Deferred.make<void>();
+    const cloudLinkParked = yield* Deferred.make<void>();
+    const routesReady = yield* Deferred.make<void>();
+    const launcherLayer = ServiceLauncherClient.layer;
 
     yield* fixPath();
 
@@ -436,6 +454,8 @@ export const makeServerLayer = Layer.unwrap(
     const runtimeStateLayer = Layer.effectDiscard(
       Effect.acquireRelease(
         Effect.gen(function* () {
+          yield* Deferred.succeed(runtimeStateParked, undefined).pipe(Effect.orDie);
+          yield* awaitActivation;
           const server = yield* HttpServer.HttpServer;
           const address = server.address;
           if (typeof address === "string" || !("port" in address)) {
@@ -449,15 +469,26 @@ export const makeServerLayer = Layer.unwrap(
           yield* persistServerRuntimeState({
             path: config.serverRuntimeStatePath,
             state,
-          });
+          }).pipe(
+            Effect.catchCause((cause) =>
+              Effect.logWarning("Failed to persist server runtime state", { cause }),
+            ),
+          );
         }),
-        () => clearPersistedServerRuntimeState(config.serverRuntimeStatePath),
+        () =>
+          clearPersistedServerRuntimeState(config.serverRuntimeStatePath).pipe(
+            Effect.catchCause((cause) =>
+              Effect.logWarning("Failed to clear server runtime state", { cause }),
+            ),
+          ),
       ),
     );
     const tailscaleServeLayer = config.tailscaleServeEnabled
       ? Layer.effectDiscard(
           Effect.acquireRelease(
             Effect.gen(function* () {
+              yield* Deferred.succeed(tailscaleParked, undefined).pipe(Effect.orDie);
+              yield* awaitActivation;
               const server = yield* HttpServer.HttpServer;
               const address = server.address;
               if (typeof address === "string" || !("port" in address)) {
@@ -507,50 +538,80 @@ export const makeServerLayer = Layer.unwrap(
       : Layer.empty;
     const cloudDesiredLinkReconcileLayer = Layer.effectDiscard(
       Effect.gen(function* () {
-        if (!hasCloudPublicConfig) return;
-        // Idle Cloudflare tunnels are billed, so a stopping server releases its
-        // tunnel; the persisted desired link brings one back — same hostname,
-        // fresh tunnel — when the environment starts again. Registered even
-        // when no link is desired yet: a client can link a running server, and
-        // that tunnel needs the same disposal on shutdown.
-        yield* Effect.addFinalizer(() =>
-          releaseManagedTunnelOnShutdown().pipe(
-            Effect.timeout("10 seconds"),
-            Effect.tap((released) =>
-              released ? Effect.logInfo("Released the managed tunnel on shutdown") : Effect.void,
-            ),
-            Effect.catchCause((cause) =>
-              Effect.logWarning(
-                "Failed to release the managed tunnel on shutdown; the next link reuses it",
-                { cause },
+        if (!hasCloudPublicConfig) {
+          yield* Deferred.succeed(cloudLinkParked, undefined).pipe(Effect.orDie);
+          return;
+        }
+        yield* forkParked(
+          Effect.gen(function* () {
+            // Only an activated runtime owns the tunnel cleanup finalizer.
+            yield* Effect.addFinalizer(() =>
+              releaseManagedTunnelOnShutdown().pipe(
+                Effect.timeout("10 seconds"),
+                Effect.tap((released) =>
+                  released
+                    ? Effect.logInfo("Released the managed tunnel on shutdown")
+                    : Effect.void,
+                ),
+                Effect.catchCause((cause) =>
+                  Effect.logWarning(
+                    "Failed to release the managed tunnel on shutdown; the next link reuses it",
+                    { cause },
+                  ),
+                ),
+                Effect.asVoid,
               ),
-            ),
-            Effect.asVoid,
-          ),
-        );
-        if (!(yield* CloudCliState.readCliDesiredCloudLink)) return;
-        const server = yield* HttpServer.HttpServer;
-        const address = server.address;
-        if (typeof address === "string" || !("port" in address)) return;
-        yield* Effect.forkScoped(
-          Effect.sleep("250 millis").pipe(
-            Effect.andThen(reconcileDesiredCloudLink(`http://127.0.0.1:${address.port}`)),
-            Effect.retry({ times: 4 }),
-            Effect.tap(() => Effect.logInfo("T3 Connect desired link reconciled on startup")),
-            Effect.catch((cause) =>
-              Effect.logWarning("Failed to reconcile T3 Connect desired link on startup", {
-                cause,
+            );
+            if (!(yield* CloudCliState.readCliDesiredCloudLink)) return;
+            const server = yield* HttpServer.HttpServer;
+            const address = server.address;
+            if (typeof address === "string" || !("port" in address)) return;
+            yield* Effect.sleep("250 millis").pipe(
+              Effect.andThen(reconcileDesiredCloudLink(`http://127.0.0.1:${address.port}`)),
+              Effect.retry({
+                while: (error) =>
+                  error._tag !== "EnvironmentHttpBadRequestError" &&
+                  error._tag !== "EnvironmentHttpUnauthorizedError" &&
+                  error._tag !== "EnvironmentHttpConflictError",
+                schedule: Schedule.exponential("1 second").pipe(
+                  Schedule.modifyDelay(({ duration }) =>
+                    Effect.succeed(Duration.min(duration, Duration.seconds(30))),
+                  ),
+                  Schedule.upTo({ duration: "10 minutes" }),
+                ),
               }),
-            ),
-          ),
+              Effect.tap(() => Effect.logInfo("T3 Connect desired link reconciled on startup")),
+              Effect.catch((cause) =>
+                Effect.logWarning("Failed to reconcile T3 Connect desired link on startup", {
+                  cause,
+                }),
+              ),
+            );
+          }),
         );
+        yield* Deferred.succeed(cloudLinkParked, undefined).pipe(Effect.orDie);
       }),
     );
 
+    const runtimeServicesLive = ServerRuntimeStartup.layerWithOptions({
+      activate: Deferred.succeed(activation, undefined).pipe(Effect.asVoid),
+      abort: (error) => Deferred.die(activation, error).pipe(Effect.asVoid),
+      awaitAuxiliaryParked: Effect.all(
+        [
+          Deferred.await(runtimeStateParked),
+          Deferred.await(cloudLinkParked),
+          Deferred.await(routesReady),
+          ...(config.tailscaleServeEnabled ? [Deferred.await(tailscaleParked)] : []),
+        ],
+        { concurrency: "unbounded" },
+      ).pipe(Effect.asVoid),
+    }).pipe(Layer.provideMerge(RuntimeDependenciesLive), Layer.provide(launcherLayer));
+
+    const routesLayer = HttpRouter.serve(makeRoutesLayer.pipe(Layer.provide(launcherLayer)), {
+      disableLogger: !config.logWebSocketEvents,
+    }).pipe(Layer.tap(() => Deferred.succeed(routesReady, undefined).pipe(Effect.orDie)));
     const serverApplicationLayer = Layer.mergeAll(
-      HttpRouter.serve(makeRoutesLayer, {
-        disableLogger: !config.logWebSocketEvents,
-      }),
+      routesLayer,
       httpListeningLayer,
       runtimeStateLayer,
       tailscaleServeLayer,
@@ -558,7 +619,8 @@ export const makeServerLayer = Layer.unwrap(
     );
 
     return serverApplicationLayer.pipe(
-      Layer.provideMerge(RuntimeServicesLive),
+      Layer.provideMerge(runtimeServicesLive),
+      Layer.provide(activationLayer),
       Layer.provideMerge(serverRelayBrokerTracingLayer),
       Layer.provideMerge(HttpResponseCompressionLive),
       Layer.provideMerge(HttpServerLive),
@@ -570,5 +632,5 @@ export const makeServerLayer = Layer.unwrap(
   }),
 );
 
-// Important: Only `ServerConfig` should be provided by the CLI layer!!! Don't let other requirements leak into the launch layer.
+// The CLI supplies configuration.
 export const runServer = Layer.launch(makeServerLayer);
diff --git a/apps/server/src/serverActivation.test.ts b/apps/server/src/serverActivation.test.ts
new file mode 100644
index 00000000000..a4f942a95b5
--- /dev/null
+++ b/apps/server/src/serverActivation.test.ts
@@ -0,0 +1,23 @@
+import { expect, it } from "@effect/vitest";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+
+import { forkParked, ServerActivation } from "./serverActivation.ts";
+
+it.effect("proves a root is parked before returning and releases it with one gate", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const activation = yield* Deferred.make<void>();
+      const ran = yield* Deferred.make<void>();
+
+      yield* forkParked(Deferred.succeed(ran, undefined)).pipe(
+        Effect.provideService(ServerActivation, Deferred.await(activation)),
+      );
+      expect(yield* Deferred.isDone(ran)).toBe(false);
+
+      yield* Deferred.succeed(activation, undefined);
+      yield* Deferred.await(ran);
+      expect(yield* Deferred.isDone(ran)).toBe(true);
+    }),
+  ),
+);
diff --git a/apps/server/src/serverActivation.ts b/apps/server/src/serverActivation.ts
new file mode 100644
index 00000000000..c068d55e7e7
--- /dev/null
+++ b/apps/server/src/serverActivation.ts
@@ -0,0 +1,26 @@
+import * as Context from "effect/Context";
+import * as Deferred from "effect/Deferred";
+import * as Effect from "effect/Effect";
+import type * as Scope from "effect/Scope";
+
+export class ServerActivation extends Context.Reference<Effect.Effect<void> | undefined>(
+  "t3/serverActivation",
+  { defaultValue: () => undefined },
+) {}
+
+/** Forks a long-running root before commit and proves it is parked at the activation boundary. */
+export const forkParked = <A, E, R>(
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<void, never, Scope.Scope | R> =>
+  Effect.gen(function* () {
+    const activation = yield* ServerActivation;
+    if (activation === undefined) {
+      yield* Effect.forkScoped(effect);
+      return;
+    }
+    const parked = yield* Deferred.make<void>();
+    yield* Effect.forkScoped(
+      Deferred.succeed(parked, undefined).pipe(Effect.andThen(activation), Effect.andThen(effect)),
+    );
+    yield* Deferred.await(parked);
+  });
diff --git a/apps/server/src/serverRuntimeStartup.ts b/apps/server/src/serverRuntimeStartup.ts
index b52b577c5b5..5db2b75556e 100644
--- a/apps/server/src/serverRuntimeStartup.ts
+++ b/apps/server/src/serverRuntimeStartup.ts
@@ -34,6 +34,8 @@ import * as AnalyticsService from "./telemetry/AnalyticsService.ts";
 import * as ServerEnvironment from "./environment/ServerEnvironment.ts";
 import * as EnvironmentAuth from "./auth/EnvironmentAuth.ts";
 import * as ProviderSessionReaper from "./provider/Services/ProviderSessionReaper.ts";
+import { forkParked } from "./serverActivation.ts";
+import * as ServiceLauncherClient from "./cloud/serviceLauncherClient.ts";
 import {
   formatHeadlessServeOutput,
   formatHostForUrl,
@@ -288,151 +290,161 @@ const runStartupPhase = <A, E, R>(phase: string, effect: Effect.Effect<A, E, R>)
     Effect.withSpan(`server.startup.${phase}`),
   );
 
-export const make = Effect.gen(function* () {
-  const serverConfig = yield* ServerConfig.ServerConfig;
-  const keybindings = yield* Keybindings.Keybindings;
-  const orchestrationReactor = yield* OrchestrationReactor.OrchestrationReactor;
-  const providerSessionReaper = yield* ProviderSessionReaper.ProviderSessionReaper;
-  const lifecycleEvents = yield* ServerLifecycleEvents.ServerLifecycleEvents;
-  const serverSettings = yield* ServerSettings.ServerSettingsService;
-  const serverEnvironment = yield* ServerEnvironment.ServerEnvironment;
-  const crypto = yield* Crypto.Crypto;
+interface StartupOptions {
+  readonly activate?: Effect.Effect<void>;
+  readonly awaitAuxiliaryParked?: Effect.Effect<void>;
+  readonly abort?: (error: ServerRuntimeStartupError) => Effect.Effect<void>;
+}
 
-  const commandGate = yield* makeCommandGate;
-  const httpListening = yield* Deferred.make<void>();
-  const reactorScope = yield* Scope.make("sequential");
-
-  yield* Effect.addFinalizer(() => Scope.close(reactorScope, Exit.void));
-
-  const startup = Effect.gen(function* () {
-    yield* Effect.logDebug("startup phase: starting keybindings runtime");
-    yield* runStartupPhase(
-      "keybindings.start",
-      keybindings.start.pipe(
-        Effect.catch((error) =>
-          Effect.logWarning("failed to start keybindings runtime", {
-            path: error.configPath,
-            detail: error.detail,
-            cause: error.cause,
-          }),
+export const make = (options?: StartupOptions) =>
+  Effect.gen(function* () {
+    const serverConfig = yield* ServerConfig.ServerConfig;
+    const keybindings = yield* Keybindings.Keybindings;
+    const orchestrationReactor = yield* OrchestrationReactor.OrchestrationReactor;
+    const providerSessionReaper = yield* ProviderSessionReaper.ProviderSessionReaper;
+    const lifecycleEvents = yield* ServerLifecycleEvents.ServerLifecycleEvents;
+    const serverSettings = yield* ServerSettings.ServerSettingsService;
+    const serverEnvironment = yield* ServerEnvironment.ServerEnvironment;
+    const crypto = yield* Crypto.Crypto;
+    const launcher = yield* ServiceLauncherClient.ServiceLauncherClient;
+
+    const commandGate = yield* makeCommandGate;
+    const httpListening = yield* Deferred.make<void>();
+    const reactorScope = yield* Scope.make("sequential");
+
+    yield* Effect.addFinalizer(() => Scope.close(reactorScope, Exit.void));
+
+    const startup = Effect.gen(function* () {
+      yield* Effect.logDebug("startup phase: starting keybindings runtime");
+      yield* runStartupPhase(
+        "keybindings.start",
+        keybindings.start.pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("failed to start keybindings runtime", {
+              path: error.configPath,
+              detail: error.detail,
+              cause: error.cause,
+            }),
+          ),
         ),
-        Effect.forkScoped,
-      ),
-    );
+      );
 
-    yield* Effect.logDebug("startup phase: starting server settings runtime");
-    yield* runStartupPhase(
-      "settings.start",
-      serverSettings.start.pipe(
-        Effect.catch((error) =>
-          Effect.logWarning("failed to start server settings runtime", {
-            path: error.settingsPath,
-            operation: error.operation,
-            providerInstanceId: error.providerInstanceId,
-            environmentVariable: error.environmentVariable,
-            cause: error.cause,
-          }),
+      yield* Effect.logDebug("startup phase: starting server settings runtime");
+      yield* runStartupPhase(
+        "settings.start",
+        serverSettings.start.pipe(
+          Effect.catch((error) =>
+            Effect.logWarning("failed to start server settings runtime", {
+              path: error.settingsPath,
+              operation: error.operation,
+              providerInstanceId: error.providerInstanceId,
+              environmentVariable: error.environmentVariable,
+              cause: error.cause,
+            }),
+          ),
         ),
-        Effect.forkScoped,
-      ),
-    );
+      );
 
-    yield* Effect.logDebug("startup phase: starting orchestration reactors");
-    yield* runStartupPhase(
-      "reactors.start",
-      Effect.gen(function* () {
-        yield* orchestrationReactor.start().pipe(Scope.provide(reactorScope));
-        yield* providerSessionReaper.start().pipe(Scope.provide(reactorScope));
-      }),
-    );
+      yield* Effect.logDebug("startup phase: parking orchestration roots at activation");
+      yield* runStartupPhase(
+        "reactors.start",
+        Effect.gen(function* () {
+          yield* orchestrationReactor.start().pipe(Scope.provide(reactorScope));
+          yield* providerSessionReaper.start().pipe(Scope.provide(reactorScope));
+        }),
+      );
 
-    const welcomeBase = yield* resolveWelcomeBase;
-    const environment = yield* serverEnvironment.getDescriptor;
-    yield* Effect.logDebug("startup phase: preparing welcome payload");
-    yield* Effect.logDebug("startup phase: publishing welcome event", {
-      environmentId: environment.environmentId,
-      cwd: welcomeBase.cwd,
-      projectName: welcomeBase.projectName,
-    });
-    yield* runStartupPhase(
-      "welcome.publish",
-      lifecycleEvents.publish({
-        version: 1,
-        type: "welcome",
-        payload: {
-          environment,
-          ...welcomeBase,
-        },
-      }),
-    );
+      const welcomeBase = yield* resolveWelcomeBase;
+      const environment = yield* serverEnvironment.getDescriptor;
+      yield* Effect.logDebug("startup phase: preparing welcome payload");
+
+      if (serverConfig.autoBootstrapProjectFromCwd) {
+        yield* forkParked(
+          runStartupPhase(
+            "welcome.autobootstrap",
+            Effect.gen(function* () {
+              const bootstrapTargets = yield* resolveAutoBootstrapWelcomeTargets.pipe(
+                Effect.provideService(Crypto.Crypto, crypto),
+              );
+              if (!bootstrapTargets.bootstrapProjectId && !bootstrapTargets.bootstrapThreadId) {
+                return;
+              }
+
+              yield* Effect.logDebug("startup phase: publishing bootstrapped welcome event", {
+                environmentId: environment.environmentId,
+                cwd: welcomeBase.cwd,
+                projectName: welcomeBase.projectName,
+                bootstrapProjectId: bootstrapTargets.bootstrapProjectId,
+                bootstrapThreadId: bootstrapTargets.bootstrapThreadId,
+              });
+              yield* lifecycleEvents.publish({
+                version: 1,
+                type: "welcome",
+                payload: {
+                  environment,
+                  ...welcomeBase,
+                  ...bootstrapTargets,
+                },
+              });
+            }).pipe(
+              Effect.catch((cause) =>
+                Effect.logWarning("startup auto-bootstrap welcome failed", {
+                  cause,
+                }),
+              ),
+            ),
+          ),
+        );
+      }
 
-    if (serverConfig.autoBootstrapProjectFromCwd) {
-      yield* Effect.forkScoped(
-        runStartupPhase(
-          "welcome.autobootstrap",
-          Effect.gen(function* () {
-            const bootstrapTargets = yield* resolveAutoBootstrapWelcomeTargets.pipe(
-              Effect.provideService(Crypto.Crypto, crypto),
+      yield* forkParked(
+        Effect.gen(function* () {
+          yield* Effect.logDebug("startup phase: recording startup heartbeat");
+          yield* recordStartupHeartbeat.pipe(
+            Effect.annotateSpans({ "startup.phase": "heartbeat.record" }),
+            Effect.withSpan("server.startup.heartbeat.record"),
+            Effect.ignoreCause({ log: true }),
+          );
+          if (serverConfig.startupPresentation === "headless") {
+            const accessInfo = yield* issueHeadlessServeAccessInfo();
+            yield* runStartupPhase(
+              "headless.output",
+              Console.log(formatHeadlessServeOutput(accessInfo)),
             );
-            if (!bootstrapTargets.bootstrapProjectId && !bootstrapTargets.bootstrapThreadId) {
-              return;
+          } else {
+            const startupBrowserTarget = yield* resolveStartupBrowserTarget;
+            if (serverConfig.mode !== "desktop") {
+              yield* Effect.logInfo(
+                "Authentication required. Open T3 Code using the pairing URL.",
+              ).pipe(Effect.annotateLogs({ pairingUrl: startupBrowserTarget }));
             }
+            yield* runStartupPhase("browser.open", maybeOpenBrowser(startupBrowserTarget));
+          }
+        }),
+      );
 
-            yield* Effect.logDebug("startup phase: publishing bootstrapped welcome event", {
-              environmentId: environment.environmentId,
-              cwd: welcomeBase.cwd,
-              projectName: welcomeBase.projectName,
-              bootstrapProjectId: bootstrapTargets.bootstrapProjectId,
-              bootstrapThreadId: bootstrapTargets.bootstrapThreadId,
-            });
-            yield* lifecycleEvents.publish({
-              version: 1,
-              type: "welcome",
-              payload: {
-                environment,
-                ...welcomeBase,
-                ...bootstrapTargets,
-              },
-            });
-          }).pipe(
-            Effect.catch((cause) =>
-              Effect.logWarning("startup auto-bootstrap welcome failed", {
-                cause,
-              }),
-            ),
-          ),
-        ),
+      yield* Effect.logDebug("startup phase: waiting for http listener");
+      yield* runStartupPhase("http.wait", Deferred.await(httpListening));
+      yield* runStartupPhase(
+        "auxiliary-roots.parked",
+        options?.awaitAuxiliaryParked ?? Effect.void,
       );
-    }
-  }).pipe(
-    Effect.annotateSpans({
-      "server.mode": serverConfig.mode,
-      "server.port": serverConfig.port,
-      "server.host": serverConfig.host ?? "default",
-    }),
-    Effect.withSpan("server.startup", { kind: "server", root: true }),
-  );
 
-  yield* Effect.forkScoped(
-    Effect.gen(function* () {
-      const startupExit = yield* Effect.exit(startup);
-      if (Exit.isFailure(startupExit)) {
-        const error = new ServerRuntimeStartupError({
-          mode: serverConfig.mode,
-          host: serverConfig.host ?? null,
-          port: serverConfig.port,
-          cause: startupExit.cause,
-        });
-        yield* Effect.logError("server runtime startup failed", { cause: startupExit.cause });
-        yield* commandGate.failCommandReady(error);
-        return;
-      }
+      // This is the prepared boundary. Every dependency has been acquired and
+      // every runtime root has confirmed that it is parked before this request.
+      const updateOutcome = yield* launcher.prepareTrial;
+      yield* runStartupPhase(
+        "welcome.publish",
+        lifecycleEvents.publish({
+          version: 1,
+          type: "welcome",
+          payload: { environment, ...welcomeBase },
+        }),
+      );
+      yield* options?.activate ?? Effect.void;
 
       yield* Effect.logDebug("Accepting commands");
       yield* commandGate.signalCommandReady;
-      yield* Effect.logDebug("startup phase: waiting for http listener");
-      yield* runStartupPhase("http.wait", Deferred.await(httpListening));
-      yield* Effect.logDebug("startup phase: publishing ready event");
       yield* runStartupPhase(
         "ready.publish",
         lifecycleEvents.publish({
@@ -440,39 +452,49 @@ export const make = Effect.gen(function* () {
           type: "ready",
           payload: {
             at: DateTime.formatIso(yield* DateTime.now),
-            environment: yield* serverEnvironment.getDescriptor,
+            environment,
+            ...(updateOutcome === undefined ? {} : { updateOutcome }),
           },
         }),
       );
-
-      yield* Effect.logDebug("startup phase: recording startup heartbeat");
-      yield* launchStartupHeartbeat;
-      if (serverConfig.startupPresentation === "headless") {
-        yield* Effect.logDebug("startup phase: headless access info");
-        const accessInfo = yield* issueHeadlessServeAccessInfo();
-        yield* runStartupPhase(
-          "headless.output",
-          Console.log(formatHeadlessServeOutput(accessInfo)),
-        );
-      } else {
-        yield* Effect.logDebug("startup phase: browser open check");
-        const startupBrowserTarget = yield* resolveStartupBrowserTarget;
-        if (serverConfig.mode !== "desktop") {
-          yield* Effect.logInfo(
-            "Authentication required. Open T3 Code using the pairing URL.",
-          ).pipe(Effect.annotateLogs({ pairingUrl: startupBrowserTarget }));
-        }
-        yield* runStartupPhase("browser.open", maybeOpenBrowser(startupBrowserTarget));
-      }
       yield* Effect.logDebug("startup phase: complete");
-    }),
-  );
+    }).pipe(
+      Effect.annotateSpans({
+        "server.mode": serverConfig.mode,
+        "server.port": serverConfig.port,
+        "server.host": serverConfig.host ?? "default",
+      }),
+      Effect.withSpan("server.startup", { kind: "server", root: true }),
+    );
 
-  return {
-    awaitCommandReady: commandGate.awaitCommandReady,
-    markHttpListening: Deferred.succeed(httpListening, undefined),
-    enqueueCommand: commandGate.enqueueCommand,
-  } satisfies ServerRuntimeStartup["Service"];
-});
+    yield* Effect.forkScoped(
+      Effect.exit(startup).pipe(
+        Effect.flatMap((startupExit) => {
+          if (Exit.isSuccess(startupExit)) return Effect.void;
+          const error = new ServerRuntimeStartupError({
+            mode: serverConfig.mode,
+            host: serverConfig.host ?? null,
+            port: serverConfig.port,
+            cause: startupExit.cause,
+          });
+          return Effect.logError("server runtime startup failed", {
+            cause: startupExit.cause,
+          }).pipe(
+            Effect.andThen(commandGate.failCommandReady(error)),
+            Effect.andThen(options?.abort?.(error) ?? Effect.void),
+          );
+        }),
+      ),
+    );
+
+    return {
+      awaitCommandReady: commandGate.awaitCommandReady,
+      markHttpListening: Deferred.succeed(httpListening, undefined),
+      enqueueCommand: commandGate.enqueueCommand,
+    } satisfies ServerRuntimeStartup["Service"];
+  });
+
+export const layerWithOptions = (options?: StartupOptions) =>
+  Layer.effect(ServerRuntimeStartup, make(options));
 
-export const layer = Layer.effect(ServerRuntimeStartup, make);
+export const layer = layerWithOptions();
diff --git a/apps/server/src/serverRuntimeState.test.ts b/apps/server/src/serverRuntimeState.test.ts
index 749fd3062e9..4c2375b29a7 100644
--- a/apps/server/src/serverRuntimeState.test.ts
+++ b/apps/server/src/serverRuntimeState.test.ts
@@ -33,6 +33,7 @@ describe("serverRuntimeState", () => {
         host: "127.0.0.1",
         port: 4_971,
         origin: "http://127.0.0.1:4971",
+        devUrl: "http://localhost:5733/",
         startedAt: "2026-06-20T00:00:00.000Z",
       };
 
@@ -43,6 +44,24 @@ describe("serverRuntimeState", () => {
     }).pipe(Effect.provide(NodeServices.layer)),
   );
 
+  it.effect("records the dev web URL when the server fronts a dev server", () =>
+    Effect.gen(function* () {
+      const state = yield* ServerRuntimeState.makePersistedServerRuntimeState({
+        config: { host: undefined, devUrl: new URL("http://localhost:5733") },
+        port: 13_773,
+      });
+
+      assert.equal(state.devUrl, "http://localhost:5733/");
+      assert.equal(state.origin, "http://127.0.0.1:13773");
+
+      const withoutDev = yield* ServerRuntimeState.makePersistedServerRuntimeState({
+        config: { host: undefined, devUrl: undefined },
+        port: 13_773,
+      });
+      assert.isFalse("devUrl" in withoutDev);
+    }),
+  );
+
   it.effect("treats a missing runtime state file as absent", () =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
diff --git a/apps/server/src/serverRuntimeState.ts b/apps/server/src/serverRuntimeState.ts
index 329b000369a..b32f3814547 100644
--- a/apps/server/src/serverRuntimeState.ts
+++ b/apps/server/src/serverRuntimeState.ts
@@ -14,6 +14,9 @@ export const PersistedServerRuntimeState = Schema.Struct({
   host: Schema.optional(Schema.String),
   port: Schema.Int,
   origin: Schema.String,
+  // Present when the server fronts a dev web server (VITE_DEV_SERVER_URL).
+  // Dev is single-origin: browsers must pair through this URL, not `origin`.
+  devUrl: Schema.optional(Schema.String),
   startedAt: Schema.String,
 });
 export type PersistedServerRuntimeState = typeof PersistedServerRuntimeState.Type;
@@ -45,7 +48,7 @@ const runtimeOriginForConfig = (
 };
 
 export const makePersistedServerRuntimeState = (input: {
-  readonly config: Pick<ServerConfig.ServerConfig["Service"], "host">;
+  readonly config: Pick<ServerConfig.ServerConfig["Service"], "host" | "devUrl">;
   readonly port: number;
 }): Effect.Effect<PersistedServerRuntimeState> =>
   Effect.map(DateTime.now, (now) => ({
@@ -54,6 +57,7 @@ export const makePersistedServerRuntimeState = (input: {
     ...(input.config.host ? { host: input.config.host } : {}),
     port: input.port,
     origin: runtimeOriginForConfig(input.config, input.port),
+    ...(input.config.devUrl ? { devUrl: input.config.devUrl.toString() } : {}),
     startedAt: DateTime.formatIso(now),
   }));
 
diff --git a/apps/server/src/service-launcher.ts b/apps/server/src/service-launcher.ts
new file mode 100644
index 00000000000..10521245162
--- /dev/null
+++ b/apps/server/src/service-launcher.ts
@@ -0,0 +1 @@
+import "./serviceLauncher.ts";
diff --git a/apps/server/src/serviceLauncher.test.ts b/apps/server/src/serviceLauncher.test.ts
new file mode 100644
index 00000000000..21f3618d512
--- /dev/null
+++ b/apps/server/src/serviceLauncher.test.ts
@@ -0,0 +1,199 @@
+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 { Launcher, readServiceState, writeServiceState } from "./serviceLauncher.ts";
+import {
+  compareExactServiceVersions,
+  decodeServiceState,
+  isExactServiceVersion,
+} from "./cloud/serviceProtocol.ts";
+
+it("accepts only exact semantic versions", () => {
+  for (const version of ["0.0.0", "1.2.3", "1.2.3-alpha.1", "1.2.3-0", "1.2.3+001"]) {
+    assert.isTrue(isExactServiceVersion(version), version);
+  }
+  for (const version of ["latest", "01.2.3", "1.2.3-01", "1.2.3-alpha..1", "1.2.3+."]) {
+    assert.isFalse(isExactServiceVersion(version), version);
+  }
+});
+
+it("orders exact semantic versions without treating build metadata as precedence", () => {
+  assert.equal(compareExactServiceVersions("1.2.3", "1.2.3"), 0);
+  assert.equal(compareExactServiceVersions("1.2.4", "1.2.3"), 1);
+  assert.equal(compareExactServiceVersions("2.0.0-alpha.1", "2.0.0-alpha.2"), -1);
+  assert.equal(compareExactServiceVersions("2.0.0-alpha.2", "2.0.0-alpha.beta"), -1);
+  assert.equal(compareExactServiceVersions("2.0.0-alpha-beta", "2.0.0-alpha-alpha"), 1);
+  assert.equal(compareExactServiceVersions("2.0.0", "2.0.0-rc.1"), 1);
+  assert.equal(compareExactServiceVersions("2.0.0+one", "2.0.0+two"), 0);
+});
+
+it("rejects contradictory service state", () => {
+  assert.isUndefined(
+    decodeServiceState({
+      protocol: 1,
+      activeVersion: "0.0.31",
+      update: {
+        id: "update-1",
+        fromVersion: "0.0.30",
+        targetVersion: "0.0.32",
+        status: "pending",
+      },
+    }),
+  );
+
+  assert.isUndefined(
+    decodeServiceState({
+      protocol: 1,
+      activeVersion: "1.0.0",
+      update: {
+        id: "update-2",
+        fromVersion: "1.0.0",
+        targetVersion: "0.9.0",
+        status: "pending",
+      },
+    }),
+  );
+});
+
+it.layer(NodeServices.layer)("service state persistence", (it) => {
+  it.effect("durably replaces and strictly reads one state document", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-service-launcher-test-" });
+      const statePath = path.join(root, "runtime", "service-state.json");
+      const state = {
+        protocol: 1,
+        activeVersion: "0.0.31",
+      } as const;
+
+      yield* Effect.promise(() => writeServiceState(statePath, state));
+      assert.deepEqual(yield* Effect.promise(() => readServiceState(statePath)), state);
+    }),
+  );
+
+  it.effect("serializes shutdown with launcher recovery", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-service-launcher-stop-" });
+      const statePath = path.join(root, "runtime", "service-state.json");
+      const versionDir = path.join(root, "runtime", "versions", "1.0.0");
+      const entryPath = path.join(versionDir, "node_modules", "t3", "dist", "bin.mjs");
+      yield* fs.makeDirectory(path.dirname(entryPath), { recursive: true });
+      yield* fs.writeFileString(entryPath, "setInterval(() => {}, 1_000);\n");
+      yield* fs.writeFileString(path.join(versionDir, ".install-complete"), "1.0.0\n");
+      yield* Effect.promise(() =>
+        writeServiceState(statePath, {
+          protocol: 1,
+          activeVersion: "1.0.0",
+        }),
+      );
+
+      const launcher = new Launcher(root, yield* Effect.promise(() => readServiceState(statePath)));
+      const running = launcher.run();
+      yield* Effect.promise(() => launcher.stop("SIGTERM"));
+      yield* Effect.promise(() => running);
+    }),
+  );
+
+  it.effect("commits only after the trial reports prepared", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-service-launcher-flow-" });
+      const statePath = path.join(root, "runtime", "service-state.json");
+      const childSource = `
+const context = JSON.parse(process.env.T3_SERVICE_LAUNCHER_CONTEXT);
+if (context.update?.status === "pending") {
+  process.send({ type: "prepared", updateId: context.update.id });
+  process.on("message", (message) => {
+    if (message.type === "committed") process.exit(0);
+  });
+} else if (context.update === undefined) {
+  process.send({ type: "request-update", targetVersion: "1.1.0" });
+  setInterval(() => {}, 1_000);
+} else {
+  process.exit(0);
+}
+`;
+      for (const version of ["1.0.0", "1.1.0"]) {
+        const versionDir = path.join(root, "runtime", "versions", version);
+        const entryPath = path.join(versionDir, "node_modules", "t3", "dist", "bin.mjs");
+        yield* fs.makeDirectory(path.dirname(entryPath), { recursive: true });
+        yield* fs.writeFileString(entryPath, childSource);
+        yield* fs.writeFileString(path.join(versionDir, ".install-complete"), `${version}\n`);
+      }
+      yield* Effect.promise(() =>
+        writeServiceState(statePath, {
+          protocol: 1,
+          activeVersion: "1.0.0",
+        }),
+      );
+
+      const launcher = new Launcher(root, yield* Effect.promise(() => readServiceState(statePath)));
+      yield* Effect.promise(() =>
+        launcher.run().then(
+          () => Promise.reject(new Error("launcher unexpectedly completed")),
+          () => Promise.resolve(),
+        ),
+      );
+
+      const state = yield* Effect.promise(() => readServiceState(statePath));
+      assert.equal(state.activeVersion, "1.1.0");
+      assert.equal(state.update?.status, "committed");
+    }),
+  );
+
+  it.effect("rolls back a trial that reports the wrong update ID", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-service-launcher-rollback-" });
+      const statePath = path.join(root, "runtime", "service-state.json");
+      const childSource = `
+const context = JSON.parse(process.env.T3_SERVICE_LAUNCHER_CONTEXT);
+if (context.update?.status === "pending") {
+  process.send({ type: "prepared", updateId: "wrong-update" });
+} else if (context.update === undefined) {
+  process.send({ type: "request-update", targetVersion: "1.1.0" });
+  setInterval(() => {}, 1_000);
+} else {
+  process.exit(0);
+}
+`;
+      for (const version of ["1.0.0", "1.1.0"]) {
+        const versionDir = path.join(root, "runtime", "versions", version);
+        const entryPath = path.join(versionDir, "node_modules", "t3", "dist", "bin.mjs");
+        yield* fs.makeDirectory(path.dirname(entryPath), { recursive: true });
+        yield* fs.writeFileString(entryPath, childSource);
+        yield* fs.writeFileString(path.join(versionDir, ".install-complete"), `${version}\n`);
+      }
+      yield* Effect.promise(() =>
+        writeServiceState(statePath, {
+          protocol: 1,
+          activeVersion: "1.0.0",
+        }),
+      );
+
+      const launcher = new Launcher(root, yield* Effect.promise(() => readServiceState(statePath)));
+      yield* Effect.promise(() =>
+        launcher.run().then(
+          () => Promise.reject(new Error("launcher unexpectedly completed")),
+          () => Promise.resolve(),
+        ),
+      );
+
+      const state = yield* Effect.promise(() => readServiceState(statePath));
+      assert.equal(state.activeVersion, "1.0.0");
+      assert.equal(state.update?.status, "rolled-back");
+      assert.equal(
+        state.update?.status === "rolled-back" ? state.update.reason : undefined,
+        "invalid-prepared",
+      );
+    }),
+  );
+});
diff --git a/apps/server/src/serviceLauncher.ts b/apps/server/src/serviceLauncher.ts
new file mode 100644
index 00000000000..d7ca3357802
--- /dev/null
+++ b/apps/server/src/serviceLauncher.ts
@@ -0,0 +1,458 @@
+// @effect-diagnostics nodeBuiltinImport:off
+// @effect-diagnostics globalDate:off
+// @effect-diagnostics globalTimers:off
+// This file is shipped as a standalone bundle and copied to a stable path by
+// `t3 service update`. Keep runtime imports limited to Node built-ins.
+import * as NodeChildProcess from "node:child_process";
+import * as NodeCrypto from "node:crypto";
+import * as NodeFSP from "node:fs/promises";
+import * as NodePath from "node:path";
+
+import type {
+  PendingServiceUpdate,
+  ServiceLauncherChildMessage,
+  ServiceLauncherContext,
+  ServiceLauncherParentMessage,
+  ServiceState,
+  ServiceUpdateRecord,
+} from "./cloud/serviceProtocol.ts";
+import {
+  compareExactServiceVersions,
+  decodeServiceLauncherChildMessage,
+  isExactServiceVersion,
+  parseServiceState,
+  SERVICE_LAUNCHER_CONTEXT_ENV,
+  SERVICE_LAUNCHER_PROTOCOL,
+  SERVICE_STATE_FILE,
+} from "./cloud/serviceProtocol.ts";
+
+const HANDOFF_DELAY_MS = 2_000;
+const PREPARED_TIMEOUT_MS = 120_000;
+const TERMINATE_GRACE_MS = 5_000;
+
+type TerminalStatus = "committed" | "rolled-back" | "failed";
+type ChildRole = "active" | "trial";
+
+interface ManagedChild {
+  readonly version: string;
+  role: ChildRole;
+  readonly process: NodeChildProcess.ChildProcess;
+}
+
+const runtimePaths = (baseDir: string, version: string) => {
+  const versionDir = NodePath.join(baseDir, "runtime", "versions", version);
+  return {
+    versionDir,
+    entryPath: NodePath.join(versionDir, "node_modules", "t3", "dist", "bin.mjs"),
+    sentinelPath: NodePath.join(versionDir, ".install-complete"),
+  };
+};
+
+export async function readServiceState(filePath: string): Promise<ServiceState> {
+  const contents = await NodeFSP.readFile(filePath, "utf8");
+  const state = parseServiceState(contents);
+  if (state === undefined) throw new Error("Service state is invalid or unsupported.");
+  return state;
+}
+
+/** Durable same-directory replacement used for every runtime state transition. */
+export async function writeServiceState(filePath: string, state: ServiceState): Promise<void> {
+  const directory = NodePath.dirname(filePath);
+  await NodeFSP.mkdir(directory, { recursive: true, mode: 0o700 });
+  const tempPath = NodePath.join(
+    directory,
+    `.${NodePath.basename(filePath)}.${process.pid}.${NodeCrypto.randomUUID()}`,
+  );
+  let handle: NodeFSP.FileHandle | undefined;
+  try {
+    handle = await NodeFSP.open(tempPath, "wx", 0o600);
+    await handle.writeFile(`${JSON.stringify(state, null, 2)}\n`, "utf8");
+    await handle.sync();
+    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();
+    }
+  } finally {
+    await handle?.close().catch(() => undefined);
+    await NodeFSP.rm(tempPath, { force: true }).catch(() => undefined);
+  }
+}
+
+async function runtimeExists(baseDir: string, version: string): Promise<boolean> {
+  const paths = runtimePaths(baseDir, version);
+  try {
+    const [entry, sentinel] = await Promise.all([
+      NodeFSP.stat(paths.entryPath),
+      NodeFSP.readFile(paths.sentinelPath, "utf8"),
+    ]);
+    return entry.isFile() && sentinel.trim() === version;
+  } catch {
+    return false;
+  }
+}
+
+function terminalUpdate<S extends TerminalStatus>(input: {
+  readonly pending: PendingServiceUpdate;
+  readonly status: S;
+  readonly reason?: string;
+}): Exclude<ServiceUpdateRecord, PendingServiceUpdate> & { readonly status: S } {
+  return {
+    id: input.pending.id,
+    fromVersion: input.pending.fromVersion,
+    targetVersion: input.pending.targetVersion,
+    status: input.status,
+    ...(input.reason === undefined ? {} : { reason: input.reason }),
+  };
+}
+
+function sendMessage(
+  child: NodeChildProcess.ChildProcess,
+  message: ServiceLauncherParentMessage,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (!child.connected || child.send === undefined) {
+      reject(new Error("service child IPC is disconnected."));
+      return;
+    }
+    child.send(message, (error) => (error === null ? resolve() : reject(error)));
+  });
+}
+
+function waitForExit(child: NodeChildProcess.ChildProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve();
+  return new Promise((resolve) => child.once("exit", () => resolve()));
+}
+
+async function terminateChild(
+  child: NodeChildProcess.ChildProcess,
+  signal: NodeJS.Signals = "SIGTERM",
+): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  child.kill(signal);
+  const force = setTimeout(() => child.kill("SIGKILL"), TERMINATE_GRACE_MS);
+  try {
+    await waitForExit(child);
+  } finally {
+    clearTimeout(force);
+  }
+}
+
+export class Launcher {
+  readonly #baseDir: string;
+  readonly #statePath: string;
+  #state: ServiceState;
+  #child: ManagedChild | null = null;
+  #timer: NodeJS.Timeout | undefined;
+  #transitions: Promise<void> = Promise.resolve();
+  #stopping = false;
+  #done = false;
+  readonly #completion = Promise.withResolvers<void>();
+
+  constructor(baseDir: string, state: ServiceState) {
+    this.#baseDir = baseDir;
+    this.#statePath = NodePath.join(baseDir, "runtime", SERVICE_STATE_FILE);
+    this.#state = state;
+  }
+
+  async run(): Promise<void> {
+    const onSigterm = () => void this.stop("SIGTERM");
+    const onSigint = () => void this.stop("SIGINT");
+    process.once("SIGTERM", onSigterm);
+    process.once("SIGINT", onSigint);
+    try {
+      this.#enqueue(() => this.#recover());
+      await this.#completion.promise;
+    } finally {
+      process.off("SIGTERM", onSigterm);
+      process.off("SIGINT", onSigint);
+    }
+  }
+
+  #enqueue(transition: () => Promise<void>): void {
+    this.#transitions = this.#transitions
+      .then(transition, transition)
+      .catch((cause: unknown) =>
+        this.#fatal(cause instanceof Error ? cause : new Error(String(cause))),
+      );
+  }
+
+  async #fatal(error: Error): Promise<void> {
+    if (this.#done) return;
+    this.#done = true;
+    this.#stopping = true;
+    this.#clearTimer();
+    const child = this.#child?.process;
+    this.#child = null;
+    if (child !== undefined) await terminateChild(child);
+    this.#completion.reject(error);
+  }
+
+  async stop(signal: NodeJS.Signals): Promise<void> {
+    if (this.#stopping) {
+      await this.#completion.promise.catch(() => undefined);
+      return;
+    }
+    this.#stopping = true;
+    this.#clearTimer();
+    this.#enqueue(async () => {
+      const child = this.#child?.process;
+      this.#child = null;
+      if (child !== undefined) await terminateChild(child, signal);
+      this.#done = true;
+      this.#completion.resolve();
+    });
+    await this.#completion.promise.catch(() => undefined);
+  }
+
+  #clearTimer(): void {
+    clearTimeout(this.#timer);
+    this.#timer = undefined;
+  }
+
+  async #recover(): Promise<void> {
+    const update = this.#state.update;
+    if (update?.status !== "pending") {
+      await this.#startChild(this.#state.activeVersion, "active", update);
+      return;
+    }
+    if (!(await runtimeExists(this.#baseDir, update.targetVersion))) {
+      await this.#returnToPrevious(update, "failed", "target-runtime-missing");
+      return;
+    }
+    await this.#startTrial(update);
+  }
+
+  async #startTrial(pending: PendingServiceUpdate): Promise<void> {
+    try {
+      await this.#startChild(pending.targetVersion, "trial", pending);
+    } catch {
+      await this.#returnToPrevious(pending, "failed", "candidate-start-failed");
+    }
+  }
+
+  async #startChild(version: string, role: ChildRole, update?: ServiceUpdateRecord): Promise<void> {
+    if (this.#stopping) return;
+    if (!(await runtimeExists(this.#baseDir, version))) {
+      throw new Error(`Selected t3@${version} runtime is missing or incomplete.`);
+    }
+    if (this.#stopping) return;
+    const paths = runtimePaths(this.#baseDir, version);
+    const context: ServiceLauncherContext = {
+      protocol: SERVICE_LAUNCHER_PROTOCOL,
+      childVersion: version,
+      ...(update === undefined ? {} : { update }),
+    };
+    const child = NodeChildProcess.spawn(process.execPath, [paths.entryPath, "serve"], {
+      env: { ...process.env, [SERVICE_LAUNCHER_CONTEXT_ENV]: JSON.stringify(context) },
+      stdio: ["inherit", "inherit", "inherit", "ipc"],
+    });
+    await new Promise<void>((resolve, reject) => {
+      const onError = (error: Error) => reject(error);
+      child.once("error", onError);
+      child.once("spawn", () => {
+        child.removeListener("error", onError);
+        child.on("error", (error) => this.#enqueue(() => Promise.reject(error)));
+        resolve();
+      });
+    });
+    if (this.#stopping) {
+      await terminateChild(child);
+      return;
+    }
+
+    const managed: ManagedChild = {
+      version,
+      role,
+      process: child,
+    };
+    this.#child = managed;
+    child.on("message", (value) => {
+      const message = decodeServiceLauncherChildMessage(value);
+      if (message !== undefined) this.#enqueue(() => this.#handleMessage(managed, message));
+    });
+    child.once("exit", (code, signal) =>
+      this.#enqueue(() => this.#handleExit(managed, code, signal)),
+    );
+
+    if (role === "trial") {
+      this.#timer = setTimeout(
+        () => this.#enqueue(() => this.#handlePreparedTimeout(managed)),
+        PREPARED_TIMEOUT_MS,
+      );
+    }
+  }
+
+  async #handleMessage(child: ManagedChild, message: ServiceLauncherChildMessage): Promise<void> {
+    if (this.#child !== child || this.#stopping) return;
+    if (message.type === "request-update") {
+      await this.#handleUpdateRequest(child, message);
+      return;
+    }
+    await this.#handlePrepared(child, message.updateId);
+  }
+
+  async #handleUpdateRequest(
+    child: ManagedChild,
+    message: Extract<ServiceLauncherChildMessage, { readonly type: "request-update" }>,
+  ): Promise<void> {
+    const reject = (reason: string) =>
+      sendMessage(child.process, { type: "update-rejected", reason });
+    if (child.role !== "active") {
+      await reject("Only the active server can request an update.");
+      return;
+    }
+    if (child.version !== this.#state.activeVersion) {
+      await reject("The requesting server is not the selected active version.");
+      return;
+    }
+    if (this.#state.update?.status === "pending") {
+      await reject("Another server update is already pending.");
+      return;
+    }
+    if (!isExactServiceVersion(message.targetVersion)) {
+      await reject("The requested target is not an exact version.");
+      return;
+    }
+    if (compareExactServiceVersions(message.targetVersion, child.version) <= 0) {
+      await reject("Remote updates must select a newer server version.");
+      return;
+    }
+    if (!(await runtimeExists(this.#baseDir, message.targetVersion))) {
+      await reject("The requested target runtime is missing or incomplete.");
+      return;
+    }
+
+    const pending: PendingServiceUpdate = {
+      id: NodeCrypto.randomUUID(),
+      fromVersion: child.version,
+      targetVersion: message.targetVersion,
+      status: "pending",
+    };
+    const next: ServiceState = { ...this.#state, update: pending };
+    await writeServiceState(this.#statePath, next);
+    this.#state = next;
+    await sendMessage(child.process, { type: "update-accepted", updateId: pending.id });
+    this.#timer = setTimeout(() => this.#enqueue(() => this.#beginTrial(child)), HANDOFF_DELAY_MS);
+  }
+
+  async #beginTrial(child: ManagedChild): Promise<void> {
+    const pending = this.#state.update;
+    if (this.#child !== child || child.role !== "active" || pending?.status !== "pending") {
+      return;
+    }
+    this.#timer = undefined;
+    this.#child = null;
+    await terminateChild(child.process);
+    await this.#startTrial(pending);
+  }
+
+  async #handlePrepared(child: ManagedChild, updateId: string): Promise<void> {
+    const pending = this.#state.update;
+    if (
+      child.role !== "trial" ||
+      pending?.status !== "pending" ||
+      pending.id !== updateId ||
+      pending.targetVersion !== child.version
+    ) {
+      if (child.role === "trial" && pending?.status === "pending") {
+        await this.#returnToPrevious(pending, "rolled-back", "invalid-prepared", child);
+        return;
+      }
+      throw new Error("Trial child reported prepared for an unexpected update.");
+    }
+    this.#clearTimer();
+    const committed = terminalUpdate({ pending, status: "committed" });
+    const next: ServiceState = {
+      ...this.#state,
+      activeVersion: pending.targetVersion,
+      update: committed,
+    };
+    await writeServiceState(this.#statePath, next);
+    this.#state = next;
+    child.role = "active";
+    await sendMessage(child.process, { type: "committed", updateId: committed.id });
+  }
+
+  async #handlePreparedTimeout(child: ManagedChild): Promise<void> {
+    const pending = this.#state.update;
+    if (this.#child !== child || child.role !== "trial" || pending?.status !== "pending") {
+      return;
+    }
+    this.#timer = undefined;
+    await this.#returnToPrevious(pending, "rolled-back", "prepared-timeout", child);
+  }
+
+  async #handleExit(
+    child: ManagedChild,
+    code: number | null,
+    signal: NodeJS.Signals | null,
+  ): Promise<void> {
+    if (this.#child !== child || this.#stopping) return;
+    this.#child = null;
+    if (child.role === "trial") {
+      this.#clearTimer();
+      const pending = this.#state.update;
+      if (pending?.status !== "pending") {
+        throw new Error("Trial child exited without matching pending state.");
+      }
+      await this.#returnToPrevious(
+        pending,
+        "rolled-back",
+        `candidate-exited:${String(code ?? signal ?? "unknown")}`,
+      );
+      return;
+    }
+
+    this.#clearTimer();
+    const pending = this.#state.update;
+    if (pending?.status === "pending") {
+      await this.#startTrial(pending);
+      return;
+    }
+    throw new Error(`Active child exited unexpectedly (${String(code ?? signal ?? "unknown")}).`);
+  }
+
+  async #returnToPrevious(
+    pending: PendingServiceUpdate,
+    status: "rolled-back" | "failed",
+    reason: string,
+    child?: ManagedChild,
+  ): Promise<void> {
+    const outcome = terminalUpdate({ pending, status, reason });
+    const next: ServiceState = {
+      ...this.#state,
+      activeVersion: pending.fromVersion,
+      update: outcome,
+    };
+    await writeServiceState(this.#statePath, next);
+    this.#state = next;
+    if (child !== undefined) {
+      this.#child = null;
+      await terminateChild(child.process);
+    }
+    await this.#startChild(next.activeVersion, "active", outcome);
+  }
+}
+
+async function main(): Promise<void> {
+  const baseDir = process.env.T3CODE_HOME?.trim();
+  if (baseDir === undefined || baseDir === "") {
+    throw new Error("T3CODE_HOME is required by the T3 Code service launcher.");
+  }
+  const statePath = NodePath.join(baseDir, "runtime", SERVICE_STATE_FILE);
+  const state = await readServiceState(statePath);
+  await new Launcher(baseDir, state).run();
+}
+
+if (import.meta.main) {
+  main().catch((cause: unknown) => {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    process.stderr.write(`[service-launcher] ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}
diff --git a/apps/server/src/vcs/GitVcsDriverCore.test.ts b/apps/server/src/vcs/GitVcsDriverCore.test.ts
index aab69de6a12..24d53cd4846 100644
--- a/apps/server/src/vcs/GitVcsDriverCore.test.ts
+++ b/apps/server/src/vcs/GitVcsDriverCore.test.ts
@@ -153,6 +153,51 @@ it.effect("uses stable diagnostics for every parsed non-repository command", ()
   }).pipe(Effect.provide(layer));
 });
 
+it.effect("invalidates origin remote cache when a driver mutation adds origin", () =>
+  Effect.gen(function* () {
+    const driver = yield* GitVcsDriver.GitVcsDriver;
+    const cwd = yield* makeTmpDir();
+    const remote = yield* makeTmpDir("git-vcs-driver-remote-");
+    yield* initRepoWithCommit(cwd);
+    yield* git(remote, ["init", "--bare"]);
+
+    const before = yield* driver.statusDetailsLocal(cwd);
+    assert.equal(before.hasOriginRemote, false);
+
+    yield* driver.ensureRemote({ cwd, preferredName: "origin", url: remote });
+
+    const after = yield* driver.statusDetailsLocal(cwd);
+    assert.equal(after.hasOriginRemote, true);
+  }).pipe(Effect.provide(TestLayer)),
+);
+
+it.effect("re-reads origin remote status after cache TTL expiry and bypassed invalidation", () =>
+  Effect.gen(function* () {
+    const driver = yield* GitVcsDriver.GitVcsDriver;
+    const cwd = yield* makeTmpDir();
+    const remote = yield* makeTmpDir("git-vcs-driver-remote-");
+    yield* initRepoWithCommit(cwd);
+    yield* git(remote, ["init", "--bare"]);
+
+    // First call caches hasOriginRemote = false (5-min TTL)
+    assert.equal((yield* driver.statusDetailsLocal(cwd)).hasOriginRemote, false);
+
+    // Add origin via raw git (bypasses invalidation hook)
+    yield* git(cwd, ["remote", "add", "origin", remote]);
+
+    // Cache still has the stale false (TTL not yet expired)
+    const stillCached = yield* driver.statusDetailsLocal(cwd);
+    assert.equal(stillCached.hasOriginRemote, false);
+
+    // Advance past the 5-minute TTL so the cache entry expires
+    yield* TestClock.adjust("6 minutes");
+
+    // After expiry, the next call re-executes and picks up the remote
+    const afterExpiry = yield* driver.statusDetailsLocal(cwd);
+    assert.equal(afterExpiry.hasOriginRemote, true);
+  }).pipe(Effect.provide(TestLayer)),
+);
+
 it.effect("coalesces concurrent ref pages into one repository snapshot", () =>
   Effect.scoped(
     Effect.gen(function* () {
diff --git a/apps/server/src/vcs/GitVcsDriverCore.ts b/apps/server/src/vcs/GitVcsDriverCore.ts
index 3aa7575d590..e44dc048634 100644
--- a/apps/server/src/vcs/GitVcsDriverCore.ts
+++ b/apps/server/src/vcs/GitVcsDriverCore.ts
@@ -61,6 +61,8 @@ const LIST_REFS_SNAPSHOT_CACHE_CAPACITY = 64;
 const LIST_REFS_SNAPSHOT_CACHE_TTL = Duration.minutes(2);
 const LIST_REFS_REFRESH_COALESCE_TTL = Duration.seconds(5);
 const LIST_REFS_REFRESH_FAILURE_COOLDOWN = Duration.seconds(30);
+const STATUS_DEFAULT_BRANCH_CACHE_TTL = Duration.minutes(5);
+const STATUS_ORIGIN_EXISTS_CACHE_TTL = Duration.minutes(5);
 const STATUS_UPSTREAM_REFRESH_ENV = Object.freeze({
   GCM_INTERACTIVE: "never",
   GIT_ASKPASS: "",
@@ -1119,6 +1121,63 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     return Cache.get(refresh ? repositoryPathsRefreshCache : repositoryPathsCache, cacheKey);
   };
 
+  const defaultBranchCache = yield* Cache.makeWith(
+    (gitCommonDir: string) =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fetchCwd =
+          path.basename(gitCommonDir) === ".git" ? path.dirname(gitCommonDir) : gitCommonDir;
+        return yield* executeGit(
+          "GitVcsDriver.statusDetails.defaultBranch",
+          fetchCwd,
+          ["--git-dir", gitCommonDir, "symbolic-ref", "refs/remotes/origin/HEAD"],
+          { allowNonZeroExit: true },
+        ).pipe(
+          Effect.map((result) => {
+            if (result.exitCode !== 0) return null;
+            return parseDefaultBranchFromRemoteHeadRef(result.stdout, "origin");
+          }),
+        );
+      }),
+    {
+      capacity: 2_048,
+      timeToLive: Exit.match({
+        onSuccess: () => STATUS_DEFAULT_BRANCH_CACHE_TTL,
+        onFailure: () => Duration.zero,
+      }),
+    },
+  );
+  const originExistsCache = yield* Cache.makeWith(
+    (gitCommonDir: string) =>
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const fetchCwd =
+          path.basename(gitCommonDir) === ".git" ? path.dirname(gitCommonDir) : gitCommonDir;
+        return yield* executeGit(
+          "GitVcsDriver.statusDetails.originExists",
+          fetchCwd,
+          ["--git-dir", gitCommonDir, "remote", "get-url", "origin"],
+          { allowNonZeroExit: true },
+        ).pipe(Effect.map((result) => result.exitCode === 0));
+      }),
+    {
+      capacity: 2_048,
+      timeToLive: Exit.match({
+        onSuccess: () => STATUS_ORIGIN_EXISTS_CACHE_TTL,
+        onFailure: () => Duration.zero,
+      }),
+    },
+  );
+  const invalidateStatusStaticCaches = (cwd: string) =>
+    Effect.gen(function* () {
+      const repositoryPaths = yield* resolveRepositoryPaths(cwd).pipe(
+        Effect.catchTags({ GitCommandError: () => Effect.succeed(null) }),
+      );
+      const cacheKey = repositoryPaths?.gitCommonDir ?? normalizeRepositoryPathsCacheKey(cwd);
+      yield* Cache.invalidate(defaultBranchCache, cacheKey);
+      yield* Cache.invalidate(originExistsCache, cacheKey);
+    });
+
   const resolveGitCommonDir = Effect.fn("resolveGitCommonDir")(function* (cwd: string) {
     const repositoryPaths = yield* resolveRepositoryPaths(cwd);
     if (repositoryPaths !== null) {
@@ -1517,7 +1576,11 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
       });
     }
 
-    const [numstatStdout, defaultRefResult, hasPrimaryRemote] = yield* Effect.all(
+    const repositoryPaths = yield* resolveRepositoryPaths(cwd).pipe(
+      Effect.catchTags({ GitCommandError: () => Effect.succeed(null) }),
+    );
+    const statusCacheKey = repositoryPaths?.gitCommonDir;
+    const [numstatStdout, defaultBranch, hasPrimaryRemote] = yield* Effect.all(
       [
         executeGitWithStableDiagnostics(
           "GitVcsDriver.statusDetails.numstat",
@@ -1574,21 +1637,16 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
             );
           }),
         ),
-        executeGit(
-          "GitVcsDriver.statusDetails.defaultRef",
-          cwd,
-          ["symbolic-ref", "refs/remotes/origin/HEAD"],
-          { allowNonZeroExit: true },
-        ),
-        originRemoteExists(cwd).pipe(Effect.orElseSucceed(() => false)),
+        statusCacheKey
+          ? Cache.get(defaultBranchCache, statusCacheKey).pipe(Effect.orElseSucceed(() => null))
+          : resolveDefaultBranchName(cwd, "origin").pipe(Effect.orElseSucceed(() => null)),
+        statusCacheKey
+          ? Cache.get(originExistsCache, statusCacheKey).pipe(Effect.orElseSucceed(() => false))
+          : originRemoteExists(cwd).pipe(Effect.orElseSucceed(() => false)),
       ],
       { concurrency: "unbounded" },
     );
     const statusStdout = statusResult.stdout;
-    const defaultBranch =
-      defaultRefResult.exitCode === 0
-        ? defaultRefResult.stdout.trim().replace(/^refs\/remotes\/origin\//, "")
-        : null;
 
     let refName: string | null = null;
     let upstreamRef: string | null = null;
@@ -2809,7 +2867,14 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
     cwd: string,
     effect: Effect.Effect<A, E>,
   ): Effect.Effect<A, E> =>
-    effect.pipe(Effect.ensuring(invalidateListRefsSnapshot(cwd).pipe(Effect.ignore)));
+    effect.pipe(
+      Effect.ensuring(
+        Effect.all([
+          invalidateListRefsSnapshot(cwd).pipe(Effect.ignore),
+          invalidateStatusStaticCaches(cwd).pipe(Effect.ignore),
+        ]),
+      ),
+    );
   const initRepoWithListRefsInvalidation: GitVcsDriver.GitVcsDriver["Service"]["initRepo"] = (
     input,
   ) =>
diff --git a/apps/server/src/workspace/WorkspaceEntries.test.ts b/apps/server/src/workspace/WorkspaceEntries.test.ts
index a08350ed959..d47aaaec826 100644
--- a/apps/server/src/workspace/WorkspaceEntries.test.ts
+++ b/apps/server/src/workspace/WorkspaceEntries.test.ts
@@ -72,7 +72,12 @@ const git = (cwd: string, args: ReadonlyArray<string>, env?: NodeJS.ProcessEnv)
     return result.stdout.trim();
   });
 
-const searchWorkspaceEntries = (input: { cwd: string; query: string; limit: number }) =>
+const searchWorkspaceEntries = (input: {
+  cwd: string;
+  query: string;
+  limit: number;
+  kind?: "file" | "directory";
+}) =>
   Effect.gen(function* () {
     const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
     return yield* workspaceEntries.search(input);
@@ -200,6 +205,62 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceEntries", (it) => {
       }),
     );
 
+    it.effect("applies the file filter before limiting search results", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-file-limit-" });
+        yield* writeTextFile(cwd, "src/index.ts");
+        yield* writeTextFile(cwd, "src/internal.ts");
+
+        const result = yield* searchWorkspaceEntries({
+          cwd,
+          query: "src",
+          limit: 1,
+          kind: "file",
+        });
+
+        expect(result.entries).toEqual([{ path: "src/index.ts", kind: "file" }]);
+        expect(result.truncated).toBe(true);
+      }),
+    );
+
+    it.effect("answers an empty file-filtered query with a bounded file listing", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-empty-query-" });
+        yield* writeTextFile(cwd, "src/index.ts");
+        yield* writeTextFile(cwd, "README.md");
+
+        const result = yield* searchWorkspaceEntries({
+          cwd,
+          query: "",
+          limit: 10,
+          kind: "file",
+        });
+
+        const paths = result.entries.map((entry) => entry.path);
+        expect(paths).toHaveLength(2);
+        expect(paths).toContain("src/index.ts");
+        expect(paths).toContain("README.md");
+        expect(result.entries.every((entry) => entry.kind === "file")).toBe(true);
+      }),
+    );
+
+    it.effect("returns only directories for the directory filter", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-directory-filter-" });
+        yield* writeTextFile(cwd, "src/index.ts");
+
+        const result = yield* searchWorkspaceEntries({
+          cwd,
+          query: "src",
+          limit: 10,
+          kind: "directory",
+        });
+
+        expect(result.entries).toEqual([{ path: "src", kind: "directory" }]);
+        expect(result.truncated).toBe(false);
+      }),
+    );
+
     it.effect("excludes gitignored paths for git repositories", () =>
       Effect.gen(function* () {
         const cwd = yield* makeTempDir({ prefix: "t3code-workspace-gitignore-", git: true });
@@ -292,6 +353,287 @@ it.layer(TestLayer, { excludeTestServices: true })("WorkspaceEntries", (it) => {
     );
   });
 
+  describe("searchContents", () => {
+    it.effect("returns content matches with file paths, line numbers, and ranges", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-search-" });
+        yield* writeTextFile(
+          cwd,
+          "src/shapes.ts",
+          "export const square = 4;\nexport const Square = 16;\nexport const squareSize = 8;\n",
+        );
+        yield* writeTextFile(cwd, "src/other.ts", "const circle = true;\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "Square",
+          limit: 100,
+          caseSensitive: false,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        expect(result.matches.map((match) => [match.path, match.lineNumber])).toEqual([
+          ["src/shapes.ts", 1],
+          ["src/shapes.ts", 2],
+        ]);
+        expect(result.matches[0]?.matchRanges).toEqual([{ start: 13, end: 19 }]);
+        expect(result.truncated).toBe(false);
+      }),
+    );
+
+    it.effect("honors case sensitivity and gitignore rules", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-ignore-", git: true });
+        yield* writeTextFile(cwd, ".gitignore", "ignored.txt\n");
+        yield* writeTextFile(cwd, "src/keep.ts", "square\nSquare\n");
+        yield* writeTextFile(cwd, "ignored.txt", "Square\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "Square",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: false,
+          useRegex: false,
+        });
+
+        expect(result.matches).toHaveLength(1);
+        expect(result.matches[0]).toMatchObject({ path: "src/keep.ts", lineNumber: 2 });
+      }),
+    );
+
+    it.effect("filters whole-word matches by word boundaries without widening ranges", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-whole-word-" });
+        yield* writeTextFile(cwd, "src/words.ts", "note notes denote\nfootnote note\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "note",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        // "notes", "denote", and "footnote" are word-adjacent and excluded;
+        // ranges cover exactly the query, never boundary characters.
+        expect(result.matches).toEqual([
+          expect.objectContaining({
+            path: "src/words.ts",
+            lineNumber: 1,
+            matchRanges: [{ start: 0, end: 4 }],
+          }),
+          expect.objectContaining({
+            path: "src/words.ts",
+            lineNumber: 2,
+            matchRanges: [{ start: 9, end: 13 }],
+          }),
+        ]);
+      }),
+    );
+
+    it.effect("finds later whole-word matches in a file after rejected raw matches", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-late-whole-word-" });
+        yield* writeTextFile(cwd, "src/words.ts", `${"afoo\n".repeat(10)}foo\n`);
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "foo",
+          limit: 1,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        expect(result.matches).toEqual([
+          expect.objectContaining({
+            path: "src/words.ts",
+            lineNumber: 11,
+            matchRanges: [{ start: 0, end: 3 }],
+          }),
+        ]);
+      }),
+    );
+
+    it.effect("treats astral-plane letters as whole word characters", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-astral-word-" });
+        yield* writeTextFile(cwd, "src/words.ts", "𐐀foo foo foo𐐀\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "foo",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        expect(result.matches).toEqual([
+          expect.objectContaining({
+            path: "src/words.ts",
+            lineNumber: 1,
+            matchRanges: [{ start: 6, end: 9 }],
+          }),
+        ]);
+      }),
+    );
+
+    it.effect("matches punctuation-edged whole-word queries including adjacent occurrences", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-punctuation-" });
+        yield* writeTextFile(cwd, "src/words.ts", "-foo- -foo- -foo-\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "-foo-",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: false,
+        });
+
+        // Consuming-boundary regex would swallow the separating spaces and
+        // drop the middle occurrence; boundary post-filtering keeps all three.
+        expect(result.matches).toHaveLength(1);
+        expect(result.matches[0]).toMatchObject({
+          path: "src/words.ts",
+          lineNumber: 1,
+          matchRanges: [
+            { start: 0, end: 5 },
+            { start: 6, end: 11 },
+            { start: 12, end: 17 },
+          ],
+        });
+      }),
+    );
+
+    it.effect("matches punctuation-edged regex queries as whole words", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-regex-punctuation-" });
+        yield* writeTextFile(cwd, "src/words.ts", "foo- foo-\nafoo-b\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "foo-",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: true,
+          useRegex: true,
+        });
+
+        // wholeWord + useRegex must not silently drop non-word-edged patterns
+        // like "foo-", and "afoo-" is excluded because 'a'/'f' are both word
+        // characters at the match's left edge.
+        expect(result.matches).toHaveLength(1);
+        expect(result.matches[0]).toMatchObject({
+          path: "src/words.ts",
+          lineNumber: 1,
+          matchRanges: [
+            { start: 0, end: 4 },
+            { start: 5, end: 9 },
+          ],
+        });
+      }),
+    );
+
+    it.effect("caps matches per file so one dense file cannot fill the page", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-per-file-cap-" });
+        yield* writeTextFile(cwd, "src/dense.ts", "needle\n".repeat(300));
+        yield* writeTextFile(cwd, "src/other.ts", "needle\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "needle",
+          limit: 500,
+          caseSensitive: true,
+          wholeWord: false,
+          useRegex: false,
+        });
+
+        const byPath = new Map<string, number>();
+        for (const match of result.matches) {
+          byPath.set(match.path, (byPath.get(match.path) ?? 0) + 1);
+        }
+        expect(byPath.get("src/dense.ts")).toBe(100);
+        expect(byPath.get("src/other.ts")).toBe(1);
+      }),
+    );
+
+    it.effect("preserves regex escapes during case-insensitive searches", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-regex-" });
+        yield* writeTextFile(cwd, "src/shapes.ts", "Square\nsquare\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "\\SQUARE",
+          limit: 100,
+          caseSensitive: false,
+          wholeWord: false,
+          useRegex: true,
+        });
+
+        expect(result.matches.map((match) => match.lineNumber)).toEqual([1, 2]);
+      }),
+    );
+
+    it.effect("preserves invalid regex errors during case-insensitive searches", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-invalid-regex-" });
+        yield* writeTextFile(cwd, "src/shapes.ts", "foobar\n");
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "foo)bar(",
+          limit: 100,
+          caseSensitive: false,
+          wholeWord: false,
+          useRegex: true,
+        });
+
+        expect(result.regexFallbackError).toBeDefined();
+        expect(result.matches).toEqual([]);
+      }),
+    );
+
+    it.effect("maps multi-byte lines to string-indexed ranges", () =>
+      Effect.gen(function* () {
+        const cwd = yield* makeTempDir({ prefix: "t3code-workspace-content-multibyte-" });
+        yield* writeTextFile(cwd, "src/notes.ts", 'const label = "héllo wörld";\n');
+
+        const workspaceEntries = yield* WorkspaceEntries.WorkspaceEntries;
+        const result = yield* workspaceEntries.searchContents({
+          cwd,
+          query: "wörld",
+          limit: 100,
+          caseSensitive: true,
+          wholeWord: false,
+          useRegex: false,
+        });
+
+        expect(result.matches).toHaveLength(1);
+        const match = result.matches[0]!;
+        const range = match.matchRanges[0]!;
+        expect(match.lineContent.slice(range.start, range.end)).toBe("wörld");
+      }),
+    );
+  });
+
   describe("browse", () => {
     it.effect("returns matching directories and excludes files", () =>
       Effect.gen(function* () {
diff --git a/apps/server/src/workspace/WorkspaceEntries.ts b/apps/server/src/workspace/WorkspaceEntries.ts
index 7501cbe0eab..bb2113dac37 100644
--- a/apps/server/src/workspace/WorkspaceEntries.ts
+++ b/apps/server/src/workspace/WorkspaceEntries.ts
@@ -14,11 +14,14 @@ import type {
   FilesystemBrowseResult,
   ProjectListEntriesInput,
   ProjectListEntriesResult,
+  ProjectSearchContentsInput,
+  ProjectSearchContentsResult,
   ProjectSearchEntriesInput,
   ProjectSearchEntriesResult,
 } from "@t3tools/contracts";
 import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
 import { isExplicitRelativePath, isWindowsAbsolutePath } from "@t3tools/shared/path";
+import { normalizeSearchQuery } from "@t3tools/shared/searchRanking";
 
 import * as WorkspacePaths from "./WorkspacePaths.ts";
 import * as WorkspaceSearchIndex from "./WorkspaceSearchIndex.ts";
@@ -93,6 +96,9 @@ export class WorkspaceEntries extends Context.Service<
     readonly search: (
       input: ProjectSearchEntriesInput,
     ) => Effect.Effect<ProjectSearchEntriesResult, WorkspaceEntriesError>;
+    readonly searchContents: (
+      input: ProjectSearchContentsInput,
+    ) => Effect.Effect<ProjectSearchContentsResult, WorkspaceEntriesError>;
     readonly refresh: (cwd: string) => Effect.Effect<void>;
   }
 >()("t3/workspace/WorkspaceEntries") {}
@@ -148,33 +154,37 @@ export const make = Effect.gen(function* () {
       const normalizedCwd = yield* normalizeWorkspaceRoot(cwd).pipe(
         Effect.orElseSucceed(() => cwd),
       );
-      if (!(yield* RcMap.has(workspaceSearchIndexes.rcMap, normalizedCwd))) {
-        return;
-      }
-      const recoverRefreshFailure = (
-        cause:
-          | WorkspaceSearchIndex.WorkspaceSearchIndexCreateFailed
-          | WorkspaceSearchIndex.WorkspaceSearchIndexScanTimedOut
-          | WorkspaceSearchIndex.WorkspaceSearchIndexRefreshFailed,
-      ) =>
-        Effect.gen(function* () {
-          yield* Effect.logWarning("Failed to refresh workspace search index", {
-            cwd,
-            cause,
+      for (const variant of WorkspaceSearchIndex.WORKSPACE_SEARCH_INDEX_VARIANTS) {
+        const indexKey = WorkspaceSearchIndex.workspaceSearchIndexKey(normalizedCwd, variant);
+        if (!(yield* RcMap.has(workspaceSearchIndexes.rcMap, indexKey))) {
+          continue;
+        }
+        const recoverRefreshFailure = (
+          cause:
+            | WorkspaceSearchIndex.WorkspaceSearchIndexCreateFailed
+            | WorkspaceSearchIndex.WorkspaceSearchIndexScanTimedOut
+            | WorkspaceSearchIndex.WorkspaceSearchIndexRefreshFailed,
+        ) =>
+          Effect.gen(function* () {
+            yield* Effect.logWarning("Failed to refresh workspace search index", {
+              cwd,
+              variant,
+              cause,
+            });
+            yield* workspaceSearchIndexes.invalidate(indexKey);
           });
-          yield* workspaceSearchIndexes.invalidate(normalizedCwd);
-        });
-      yield* Effect.gen(function* () {
-        const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
-        yield* searchIndex.refresh();
-      }).pipe(
-        Effect.provide(workspaceSearchIndexes.get(normalizedCwd)),
-        Effect.catchTags({
-          WorkspaceSearchIndexCreateFailed: recoverRefreshFailure,
-          WorkspaceSearchIndexScanTimedOut: recoverRefreshFailure,
-          WorkspaceSearchIndexRefreshFailed: recoverRefreshFailure,
-        }),
-      );
+        yield* Effect.gen(function* () {
+          const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
+          yield* searchIndex.refresh();
+        }).pipe(
+          Effect.provide(workspaceSearchIndexes.get(indexKey)),
+          Effect.catchTags({
+            WorkspaceSearchIndexCreateFailed: recoverRefreshFailure,
+            WorkspaceSearchIndexScanTimedOut: recoverRefreshFailure,
+            WorkspaceSearchIndexRefreshFailed: recoverRefreshFailure,
+          }),
+        );
+      }
     },
   );
 
@@ -230,28 +240,55 @@ export const make = Effect.gen(function* () {
   const search: WorkspaceEntries["Service"]["search"] = Effect.fn("WorkspaceEntries.search")(
     function* (input) {
       const normalizedCwd = yield* normalizeWorkspaceRoot(input.cwd);
-      const normalizedQuery = input.query
-        .trim()
-        .toLowerCase()
-        .replace(/^[@./]+/, "");
+      const normalizedQuery = normalizeSearchQuery(input.query, {
+        trimLeadingPattern: /^[@./]+/,
+      });
       return yield* Effect.gen(function* () {
         const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
-        return yield* searchIndex.search(normalizedQuery, input.limit);
-      }).pipe(Effect.provide(workspaceSearchIndexes.get(normalizedCwd)));
+        return yield* searchIndex.search(normalizedQuery, input.limit, input.kind);
+      }).pipe(
+        Effect.provide(
+          workspaceSearchIndexes.get(
+            WorkspaceSearchIndex.workspaceSearchIndexKey(normalizedCwd, "paths"),
+          ),
+        ),
+      );
     },
   );
 
+  const searchContents: WorkspaceEntries["Service"]["searchContents"] = Effect.fn(
+    "WorkspaceEntries.searchContents",
+  )(function* (input) {
+    const normalizedCwd = yield* normalizeWorkspaceRoot(input.cwd);
+    return yield* Effect.gen(function* () {
+      const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
+      return yield* searchIndex.searchContents(input);
+    }).pipe(
+      Effect.provide(
+        workspaceSearchIndexes.get(
+          WorkspaceSearchIndex.workspaceSearchIndexKey(normalizedCwd, "content"),
+        ),
+      ),
+    );
+  });
+
   const list: WorkspaceEntries["Service"]["list"] = Effect.fn("WorkspaceEntries.list")(
     function* (input) {
       const normalizedCwd = yield* normalizeWorkspaceRoot(input.cwd);
       return yield* Effect.gen(function* () {
         const searchIndex = yield* WorkspaceSearchIndex.WorkspaceSearchIndex;
         return yield* searchIndex.list();
-      }).pipe(Effect.provide(workspaceSearchIndexes.get(normalizedCwd)));
+      }).pipe(
+        Effect.provide(
+          workspaceSearchIndexes.get(
+            WorkspaceSearchIndex.workspaceSearchIndexKey(normalizedCwd, "paths"),
+          ),
+        ),
+      );
     },
   );
 
-  return WorkspaceEntries.of({ browse, list, refresh, search });
+  return WorkspaceEntries.of({ browse, list, refresh, search, searchContents });
 });
 
 export const layer = Layer.effect(WorkspaceEntries, make).pipe(
diff --git a/apps/server/src/workspace/WorkspaceSearchIndex.test.ts b/apps/server/src/workspace/WorkspaceSearchIndex.test.ts
index 9b7ed4e2453..15572837030 100644
--- a/apps/server/src/workspace/WorkspaceSearchIndex.test.ts
+++ b/apps/server/src/workspace/WorkspaceSearchIndex.test.ts
@@ -1,4 +1,4 @@
-import { FileFinder } from "@ff-labs/fff-node";
+import { FileFinder, type GrepCursor, type GrepOptions, type GrepResult } from "@ff-labs/fff-node";
 import { afterEach, expect, it } from "@effect/vitest";
 import * as Cause from "effect/Cause";
 import * as Effect from "effect/Effect";
@@ -51,6 +51,41 @@ it.effect("keeps returned FileFinder creation diagnostics out of the cause chain
   }),
 );
 
+it.effect("waits for the full content index warmup before returning", () =>
+  Effect.gen(function* () {
+    const waitForIndexReady = vi.fn(async () => ({ ok: true as const, value: true }));
+    const finder = {
+      destroy: vi.fn(),
+      waitForIndexReady,
+    } as unknown as FileFinder;
+    vi.spyOn(FileFinder, "create").mockReturnValueOnce({ ok: true, value: finder });
+
+    yield* Effect.scoped(WorkspaceSearchIndex.make("/workspace/project", "content"));
+
+    expect(waitForIndexReady).toHaveBeenCalledWith(15_000);
+  }),
+);
+
+it.effect("preserves a full-index warmup timeout as a structured error", () =>
+  Effect.gen(function* () {
+    const finder = {
+      destroy: vi.fn(),
+      waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: false })),
+    } as unknown as FileFinder;
+    vi.spyOn(FileFinder, "create").mockReturnValueOnce({ ok: true, value: finder });
+
+    const error = yield* Effect.flip(
+      Effect.scoped(WorkspaceSearchIndex.make("/workspace/project", "content")),
+    );
+
+    expect(error).toMatchObject({
+      _tag: "WorkspaceSearchIndexScanTimedOut",
+      cwd: "/workspace/project",
+      timeout: "15 seconds",
+    });
+  }),
+);
+
 it.effect("preserves FileFinder destroy failures as structured defects", () =>
   Effect.gen(function* () {
     const cause = new Error("native destroy failed");
@@ -58,7 +93,7 @@ it.effect("preserves FileFinder destroy failures as structured defects", () =>
       destroy: vi.fn(() => {
         throw cause;
       }),
-      isScanning: vi.fn(() => false),
+      waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: true })),
     } as unknown as FileFinder;
     vi.spyOn(FileFinder, "create").mockReturnValueOnce({ ok: true, value: finder });
 
@@ -85,12 +120,16 @@ it.effect("preserves search and refresh failures with operation context", () =>
     Effect.gen(function* () {
       const searchCause = new Error("native search failed");
       const refreshCause = new Error("native scan failed");
+      const contentSearchCause = new Error("native grep failed");
       const finder = {
         destroy: vi.fn(),
-        isScanning: vi.fn(() => false),
+        waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: true })),
         mixedSearch: vi.fn(() => {
           throw searchCause;
         }),
+        grep: vi.fn(() => {
+          throw contentSearchCause;
+        }),
         scanFiles: vi.fn(() => {
           throw refreshCause;
         }),
@@ -100,6 +139,15 @@ it.effect("preserves search and refresh failures with operation context", () =>
       const searchIndex = yield* WorkspaceSearchIndex.make("/workspace/project");
       const query = "authorization: Bearer secret-token";
       const searchError = yield* Effect.flip(searchIndex.search(query, 3));
+      const contentSearchError = yield* Effect.flip(
+        searchIndex.searchContents({
+          query,
+          limit: 3,
+          caseSensitive: false,
+          wholeWord: false,
+          useRegex: false,
+        }),
+      );
       const refreshError = yield* Effect.flip(searchIndex.refresh());
 
       expect(searchError).toMatchObject({
@@ -112,6 +160,16 @@ it.effect("preserves search and refresh failures with operation context", () =>
       });
       expect(searchError).not.toHaveProperty("query");
       expect(searchError.message).not.toMatch(/Bearer|secret-token/);
+      expect(contentSearchError).toMatchObject({
+        _tag: "WorkspaceSearchIndexSearchFailed",
+        cwd: "/workspace/project",
+        queryLength: query.length,
+        pageSize: 3,
+        reason: "FileFinder.grep threw unexpectedly.",
+        cause: contentSearchCause,
+      });
+      expect(contentSearchError).not.toHaveProperty("query");
+      expect(contentSearchError.message).not.toMatch(/Bearer|secret-token/);
       expect(refreshError).toMatchObject({
         _tag: "WorkspaceSearchIndexRefreshFailed",
         cwd: "/workspace/project",
@@ -127,7 +185,7 @@ it.effect("keeps returned search diagnostics out of the cause chain", () =>
     Effect.gen(function* () {
       const finder = {
         destroy: vi.fn(),
-        isScanning: vi.fn(() => false),
+        waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: true })),
         mixedSearch: vi.fn(() => ({ ok: false, error: "native query rejected" })),
         scanFiles: vi.fn(() => ({ ok: false, error: "native refresh rejected" })),
       } as unknown as FileFinder;
@@ -157,3 +215,80 @@ it.effect("keeps returned search diagnostics out of the cause chain", () =>
     }),
   ),
 );
+
+it.effect("continues whole-word searches after a filtered grep page", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const nextCursor = {
+        __brand: "GrepCursor",
+        _offset: 1,
+      } as GrepCursor;
+      const grepResult = (
+        lineContent: string,
+        matchRanges: Array<[number, number]>,
+        cursor: GrepCursor | null,
+      ): GrepResult => ({
+        items: [
+          {
+            relativePath: "src/words.ts",
+            fileName: "words.ts",
+            gitStatus: "unmodified",
+            size: lineContent.length,
+            modified: 0,
+            isBinary: false,
+            totalFrecencyScore: 0,
+            accessFrecencyScore: 0,
+            modificationFrecencyScore: 0,
+            lineNumber: 1,
+            col: 0,
+            byteOffset: 0,
+            lineContent,
+            matchRanges,
+          },
+        ],
+        totalMatched: 1,
+        totalFilesSearched: 1,
+        totalFiles: 1,
+        filteredFileCount: 1,
+        nextCursor: cursor,
+      });
+      const grep = vi.fn((_query: string, options?: GrepOptions) =>
+        options?.cursor
+          ? { ok: true as const, value: grepResult("needle", [[0, 6]], null) }
+          : {
+              ok: true as const,
+              value: grepResult("needleSuffix", [[0, 6]], nextCursor),
+            },
+      );
+      const finder = {
+        destroy: vi.fn(),
+        waitForIndexReady: vi.fn(async () => ({ ok: true as const, value: true })),
+        grep,
+      } as unknown as FileFinder;
+      vi.spyOn(FileFinder, "create").mockReturnValueOnce({ ok: true, value: finder });
+
+      const searchIndex = yield* WorkspaceSearchIndex.make("/workspace/project", "content");
+      const result = yield* searchIndex.searchContents({
+        query: "needle",
+        limit: 1,
+        caseSensitive: true,
+        wholeWord: true,
+        useRegex: false,
+      });
+
+      expect(result).toEqual({
+        matches: [
+          {
+            path: "src/words.ts",
+            lineNumber: 1,
+            lineContent: "needle",
+            matchRanges: [{ start: 0, end: 6 }],
+          },
+        ],
+        truncated: false,
+      });
+      expect(grep).toHaveBeenCalledTimes(2);
+      expect(grep.mock.calls[1]?.[1]?.cursor).toBe(nextCursor);
+    }),
+  ),
+);
diff --git a/apps/server/src/workspace/WorkspaceSearchIndex.ts b/apps/server/src/workspace/WorkspaceSearchIndex.ts
index db4d46851e7..8bf36b7a80a 100644
--- a/apps/server/src/workspace/WorkspaceSearchIndex.ts
+++ b/apps/server/src/workspace/WorkspaceSearchIndex.ts
@@ -1,22 +1,36 @@
-import { FileFinder, type MixedItem, type MixedSearchResult } from "@ff-labs/fff-node";
+import {
+  type DirItem,
+  type DirSearchResult,
+  type FileItem,
+  FileFinder,
+  type GrepCursor,
+  type MixedItem,
+  type MixedSearchResult,
+  type Result,
+  type SearchResult,
+} from "@ff-labs/fff-node";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as LayerMap from "effect/LayerMap";
-import * as Schedule from "effect/Schedule";
 import * as Schema from "effect/Schema";
 
 import type {
   ProjectEntry,
+  ProjectEntryKind,
   ProjectListEntriesResult,
+  ProjectSearchContentsInput,
+  ProjectSearchContentsResult,
   ProjectSearchEntriesResult,
 } from "@t3tools/contracts";
 
 const WORKSPACE_INDEX_MAX_ENTRIES = 25_000;
 const WORKSPACE_INDEX_PAGE_SIZE = WORKSPACE_INDEX_MAX_ENTRIES + 2;
 const WORKSPACE_INDEX_SCAN_TIMEOUT = "15 seconds";
+const WORKSPACE_INDEX_SCAN_TIMEOUT_MS = 15_000;
 const WORKSPACE_INDEX_IDLE_TTL = "15 minutes";
-const WORKSPACE_INDEX_SCAN_POLL_INTERVAL = "50 millis";
+const CONTENT_SEARCH_TIME_BUDGET_MS = 250;
+const CONTENT_SEARCH_MAX_MATCHES_PER_FILE = 100;
 
 export class WorkspaceSearchIndexCreateFailed extends Schema.TaggedErrorClass<WorkspaceSearchIndexCreateFailed>()(
   "WorkspaceSearchIndexCreateFailed",
@@ -96,7 +110,11 @@ export class WorkspaceSearchIndex extends Context.Service<
     readonly search: (
       query: string,
       limit: number,
+      kind?: ProjectEntryKind,
     ) => Effect.Effect<ProjectSearchEntriesResult, WorkspaceSearchIndexSearchFailed>;
+    readonly searchContents: (
+      input: Omit<ProjectSearchContentsInput, "cwd">,
+    ) => Effect.Effect<ProjectSearchContentsResult, WorkspaceSearchIndexSearchFailed>;
     readonly refresh: () => Effect.Effect<
       void,
       WorkspaceSearchIndexRefreshFailed | WorkspaceSearchIndexScanTimedOut
@@ -129,6 +147,43 @@ function toProjectEntry(item: MixedItem): ProjectEntry | null {
   };
 }
 
+function toFileEntry(item: FileItem): ProjectEntry | null {
+  const normalizedPath = trimDirectorySeparator(toPosixPath(item.relativePath));
+  return normalizedPath ? { path: normalizedPath, kind: "file" } : null;
+}
+
+function toDirectoryEntry(item: DirItem): ProjectEntry | null {
+  const normalizedPath = trimDirectorySeparator(toPosixPath(item.relativePath));
+  return normalizedPath ? { path: normalizedPath, kind: "directory" } : null;
+}
+
+function mapFileSearchResult(result: SearchResult, limit: number): ProjectSearchEntriesResult {
+  return {
+    entries: result.items
+      .flatMap((item) => {
+        const entry = toFileEntry(item);
+        return entry ? [entry] : [];
+      })
+      .slice(0, limit),
+    truncated: result.totalMatched > limit,
+  };
+}
+
+function mapDirectorySearchResult(
+  result: DirSearchResult,
+  limit: number,
+): ProjectSearchEntriesResult {
+  const entries = result.items.flatMap((item) => {
+    const entry = toDirectoryEntry(item);
+    return entry ? [entry] : [];
+  });
+  const rootDirectoryCount = result.items.some((item) => item.relativePath.length === 0) ? 1 : 0;
+  return {
+    entries: entries.slice(0, limit),
+    truncated: result.totalMatched - rootDirectoryCount > limit,
+  };
+}
+
 function mapMixedSearchResult(
   result: MixedSearchResult,
   limit: number,
@@ -155,6 +210,74 @@ function mapMixedSearchResult(
   };
 }
 
+const WORD_CHARACTER = /[\p{Letter}\p{Mark}\p{Number}_]/u;
+
+function codePointAt(line: string, index: number): string | undefined {
+  const codePoint = line.codePointAt(index);
+  return codePoint === undefined ? undefined : String.fromCodePoint(codePoint);
+}
+
+function codePointBefore(line: string, index: number): string | undefined {
+  if (index <= 0) return undefined;
+  const previousCodeUnit = line.charCodeAt(index - 1);
+  const previousIndex =
+    previousCodeUnit >= 0xdc00 && previousCodeUnit <= 0xdfff ? index - 2 : index - 1;
+  return codePointAt(line, previousIndex);
+}
+
+function buildContentSearchQuery(input: Omit<ProjectSearchContentsInput, "cwd">): {
+  readonly searchQuery: string;
+  readonly regexMode: boolean;
+} {
+  if (input.caseSensitive) {
+    return { searchQuery: input.query, regexMode: input.useRegex };
+  }
+  // Plain mode relies on smart case: an all-lowercase needle matches
+  // case-insensitively. Regex mode needs an explicit inline flag instead.
+  return input.useRegex
+    ? { searchQuery: `(?i)${input.query}`, regexMode: true }
+    : { searchQuery: input.query.toLowerCase(), regexMode: false };
+}
+
+function mapContentMatchRanges(
+  line: string,
+  byteRanges: ReadonlyArray<readonly [number, number]>,
+): Array<{ readonly start: number; readonly end: number }> {
+  const lineBytes = Buffer.from(line);
+  const toStringIndex = (byteOffset: number) => lineBytes.subarray(0, byteOffset).toString().length;
+  return byteRanges.map(([startByte, endByte]) => ({
+    start: toStringIndex(startByte),
+    end: toStringIndex(endByte),
+  }));
+}
+
+/**
+ * Whole-word filtering happens after the grep rather than by wrapping the
+ * pattern in boundary regex: consuming boundaries such as `(?:^|\W)` swallow
+ * the separator between adjacent matches and widen the reported ranges, and
+ * `\b` cannot match punctuation-edged queries at all. Matching VS Code, a
+ * match edge is a word boundary when it touches the line edge, the
+ * neighbouring character is not a word character, or the match's own edge
+ * character is not a word character.
+ */
+function isWholeWordRange(
+  line: string,
+  range: { readonly start: number; readonly end: number },
+): boolean {
+  if (range.end <= range.start) return false;
+  const isWord = (character: string | undefined) =>
+    character !== undefined && WORD_CHARACTER.test(character);
+  const leftIsBoundary =
+    range.start === 0 ||
+    !isWord(codePointBefore(line, range.start)) ||
+    !isWord(codePointAt(line, range.start));
+  const rightIsBoundary =
+    range.end >= line.length ||
+    !isWord(codePointAt(line, range.end)) ||
+    !isWord(codePointBefore(line, range.end));
+  return leftIsBoundary && rightIsBoundary;
+}
+
 function withDirectoryAncestors(entries: ReadonlyArray<ProjectEntry>): ProjectEntry[] {
   const entryByPath = new Map(entries.map((entry) => [entry.path, entry]));
   for (const entry of entries) {
@@ -169,13 +292,19 @@ function withDirectoryAncestors(entries: ReadonlyArray<ProjectEntry>): ProjectEn
   return [...entryByPath.values()];
 }
 
-const createFinder = Effect.fn("WorkspaceSearchIndex.createFinder")(function* (cwd: string) {
+const createFinder = Effect.fn("WorkspaceSearchIndex.createFinder")(function* (
+  cwd: string,
+  variant: WorkspaceSearchIndexVariant,
+) {
   const result = yield* Effect.try({
     try: () =>
       FileFinder.create({
         basePath: cwd,
         disableMmapCache: true,
-        disableContentIndexing: true,
+        // Content indexing costs scan CPU and memory, so only the on-demand
+        // content-search index pays for it; path-only consumers (file tree,
+        // composer path search, file picker) keep the lightweight index.
+        disableContentIndexing: variant !== "content",
         aiMode: false,
         enableFsRootScanning: true,
         enableHomeDirScanning: true,
@@ -194,53 +323,65 @@ const createFinder = Effect.fn("WorkspaceSearchIndex.createFinder")(function* (c
   });
 });
 
-const waitForScan = <E>(cwd: string, finder: FileFinder, onFailure: (cause: unknown) => E) =>
-  Effect.try({
-    try: () => finder.isScanning(),
-    catch: onFailure,
-  }).pipe(
-    Effect.repeat({
-      while: (scanning) => scanning,
-      schedule: Schedule.spaced(WORKSPACE_INDEX_SCAN_POLL_INTERVAL),
-    }),
-    Effect.timeoutOrElse({
-      duration: WORKSPACE_INDEX_SCAN_TIMEOUT,
-      orElse: () =>
-        new WorkspaceSearchIndexScanTimedOut({ cwd, timeout: WORKSPACE_INDEX_SCAN_TIMEOUT }),
-    }),
-    Effect.withSpan("WorkspaceSearchIndex.waitForScan"),
-  );
+const waitForIndexReady = Effect.fn("WorkspaceSearchIndex.waitForIndexReady")(function* <E>(
+  cwd: string,
+  finder: FileFinder,
+  onFailure: (input: { readonly reason: string; readonly cause?: unknown }) => E,
+): Effect.fn.Return<void, E | WorkspaceSearchIndexScanTimedOut> {
+  const result = yield* Effect.tryPromise({
+    try: () => finder.waitForIndexReady(WORKSPACE_INDEX_SCAN_TIMEOUT_MS),
+    catch: (cause) =>
+      onFailure({
+        reason: "FileFinder.waitForIndexReady rejected unexpectedly.",
+        cause,
+      }),
+  });
+  if (!result.ok) {
+    return yield* Effect.fail(onFailure({ reason: result.error }));
+  }
+  if (!result.value) {
+    return yield* new WorkspaceSearchIndexScanTimedOut({
+      cwd,
+      timeout: WORKSPACE_INDEX_SCAN_TIMEOUT,
+    });
+  }
+});
 
-export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (cwd: string) {
-  const finder = yield* Effect.acquireRelease(createFinder(cwd), (finder) =>
+export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (
+  cwd: string,
+  variant: WorkspaceSearchIndexVariant = "paths",
+) {
+  const finder = yield* Effect.acquireRelease(createFinder(cwd, variant), (finder) =>
     Effect.try({
       try: () => finder.destroy(),
       catch: (cause) => new WorkspaceSearchIndexDestroyFailed({ cwd, cause }),
     }).pipe(Effect.orDie),
   );
-  yield* waitForScan(
+  yield* waitForIndexReady(
     cwd,
     finder,
-    (cause) =>
+    ({ reason, cause }) =>
       new WorkspaceSearchIndexCreateFailed({
         cwd,
-        reason: "FileFinder.isScanning threw while creating the index.",
+        reason,
         cause,
       }),
   );
 
-  const runMixedSearch = Effect.fn("WorkspaceSearchIndex.runMixedSearch")(function* (
+  const runSearch = Effect.fn("WorkspaceSearchIndex.runSearch")(function* <A>(
     query: string,
     pageSize: number,
-  ) {
+    operation: "directorySearch" | "fileSearch" | "grep" | "mixedSearch",
+    execute: () => Result<A>,
+  ): Effect.fn.Return<A, WorkspaceSearchIndexSearchFailed> {
     const result = yield* Effect.try({
-      try: () => finder.mixedSearch(query, { pageSize }),
+      try: execute,
       catch: (cause) =>
         new WorkspaceSearchIndexSearchFailed({
           cwd,
           queryLength: query.length,
           pageSize,
-          reason: "FileFinder.mixedSearch threw unexpectedly.",
+          reason: `FileFinder.${operation} threw unexpectedly.`,
           cause,
         }),
     });
@@ -273,13 +414,13 @@ export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (cwd: strin
         reason: result.error,
       });
     }
-    yield* waitForScan(
+    yield* waitForIndexReady(
       cwd,
       finder,
-      (cause) =>
+      ({ reason, cause }) =>
         new WorkspaceSearchIndexRefreshFailed({
           cwd,
-          reason: "FileFinder.isScanning threw while refreshing the index.",
+          reason,
           cause,
         }),
     );
@@ -287,7 +428,9 @@ export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (cwd: strin
 
   const list: WorkspaceSearchIndex["Service"]["list"] = Effect.fn("WorkspaceSearchIndex.list")(
     function* () {
-      const result = yield* runMixedSearch("", WORKSPACE_INDEX_PAGE_SIZE);
+      const result = yield* runSearch("", WORKSPACE_INDEX_PAGE_SIZE, "mixedSearch", () =>
+        finder.mixedSearch("", { pageSize: WORKSPACE_INDEX_PAGE_SIZE }),
+      );
       const mapped = mapMixedSearchResult(result, WORKSPACE_INDEX_MAX_ENTRIES);
       const sortedEntries = withDirectoryAncestors(mapped.entries).toSorted((left, right) =>
         left.path.localeCompare(right.path),
@@ -302,20 +445,112 @@ export const make = Effect.fn("WorkspaceSearchIndex.make")(function* (cwd: strin
 
   const search: WorkspaceSearchIndex["Service"]["search"] = Effect.fn(
     "WorkspaceSearchIndex.search",
-  )(function* (query, limit) {
-    const result = yield* runMixedSearch(query, Math.max(1, limit + 1));
+  )(function* (query, limit, kind) {
+    const pageSize = Math.max(1, limit + 1);
+    if (kind === "file") {
+      const result = yield* runSearch(query, pageSize, "fileSearch", () =>
+        finder.fileSearch(query, { pageSize }),
+      );
+      return mapFileSearchResult(result, limit);
+    }
+    if (kind === "directory") {
+      const result = yield* runSearch(query, pageSize, "directorySearch", () =>
+        finder.directorySearch(query, { pageSize }),
+      );
+      return mapDirectorySearchResult(result, limit);
+    }
+    const result = yield* runSearch(query, pageSize, "mixedSearch", () =>
+      finder.mixedSearch(query, { pageSize }),
+    );
     return mapMixedSearchResult(result, limit);
   });
 
-  return WorkspaceSearchIndex.of({ list, refresh, search });
+  const searchContents: WorkspaceSearchIndex["Service"]["searchContents"] = Effect.fn(
+    "WorkspaceSearchIndex.searchContents",
+  )(function* (input) {
+    const { searchQuery, regexMode } = buildContentSearchQuery(input);
+    const deadline = performance.now() + CONTENT_SEARCH_TIME_BUDGET_MS;
+    // Grep cursors advance by file, so whole-word post-filtering needs enough
+    // raw candidates from the current file before moving to the next one.
+    const rawPageSize = input.wholeWord
+      ? Math.max(input.limit, CONTENT_SEARCH_MAX_MATCHES_PER_FILE)
+      : input.limit;
+    const matches: Array<ProjectSearchContentsResult["matches"][number]> = [];
+    let nextCursor: GrepCursor | null = null;
+    let regexFallbackError: string | undefined;
+
+    do {
+      const remainingTimeBudgetMs = Math.max(1, Math.ceil(deadline - performance.now()));
+      const result = yield* runSearch(input.query, input.limit, "grep", () =>
+        finder.grep(searchQuery, {
+          mode: regexMode ? "regex" : "plain",
+          smartCase: !input.caseSensitive && !regexMode,
+          // A single dense file must not consume the whole result page.
+          maxMatchesPerFile: Math.min(CONTENT_SEARCH_MAX_MATCHES_PER_FILE, rawPageSize),
+          pageSize: rawPageSize,
+          cursor: nextCursor,
+          timeBudgetMs: remainingTimeBudgetMs,
+        }),
+      );
+
+      for (const match of result.items) {
+        const matchRanges = mapContentMatchRanges(match.lineContent, match.matchRanges).filter(
+          (range) => !input.wholeWord || isWholeWordRange(match.lineContent, range),
+        );
+        if (matchRanges.length === 0) continue;
+        matches.push({
+          path: toPosixPath(match.relativePath),
+          lineNumber: match.lineNumber,
+          lineContent: match.lineContent,
+          matchRanges,
+        });
+      }
+      nextCursor = result.nextCursor;
+      regexFallbackError ??= result.regexFallbackError;
+    } while (matches.length < input.limit && nextCursor !== null && performance.now() < deadline);
+
+    return {
+      matches: matches.slice(0, input.limit),
+      truncated: matches.length > input.limit || nextCursor !== null,
+      ...(regexFallbackError !== undefined ? { regexFallbackError } : {}),
+    };
+  });
+
+  return WorkspaceSearchIndex.of({ list, refresh, search, searchContents });
 });
 
+export const WORKSPACE_SEARCH_INDEX_VARIANTS = ["paths", "content"] as const;
+export type WorkspaceSearchIndexVariant = (typeof WORKSPACE_SEARCH_INDEX_VARIANTS)[number];
+
+/**
+ * Composite LayerMap key so the lightweight path index and the on-demand
+ * content-search index of the same workspace are separate resources with
+ * independent lifecycles. "\n" cannot appear in a filesystem path.
+ */
+export const workspaceSearchIndexKey = (cwd: string, variant: WorkspaceSearchIndexVariant) =>
+  `${variant}\n${cwd}`;
+
+function parseWorkspaceSearchIndexKey(key: string): {
+  readonly cwd: string;
+  readonly variant: WorkspaceSearchIndexVariant;
+} {
+  const separatorIndex = key.indexOf("\n");
+  return {
+    variant: key.slice(0, separatorIndex) as WorkspaceSearchIndexVariant,
+    cwd: key.slice(separatorIndex + 1),
+  };
+}
+
 /**
  * A layer factory is required because every index is scoped to a concrete
- * workspace root. WorkspaceSearchIndexMap owns memoization and idle cleanup;
- * using a default cwd here would mix resources from different workspaces.
+ * workspace root and variant. WorkspaceSearchIndexMap owns memoization and
+ * idle cleanup; using a default cwd here would mix resources from different
+ * workspaces.
  */
-export const layer = (cwd: string) => Layer.effect(WorkspaceSearchIndex, make(cwd));
+export const layer = (key: string) => {
+  const { cwd, variant } = parseWorkspaceSearchIndexKey(key);
+  return Layer.effect(WorkspaceSearchIndex, make(cwd, variant));
+};
 
 export class WorkspaceSearchIndexMap extends LayerMap.Service<WorkspaceSearchIndexMap>()(
   "t3/workspace/WorkspaceSearchIndexMap",
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index 935d7edec92..909a51a4cf5 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -37,6 +37,7 @@ import {
   type ProjectFileOperation,
   ProjectListEntriesError,
   ProjectReadFileError,
+  ProjectSearchContentsError,
   ProjectSearchEntriesError,
   ProjectWriteFileError,
   RelayClientInstallFailedError,
@@ -297,6 +298,13 @@ const PROVIDER_STATUS_DEBOUNCE_MS = 200;
 // Matches the event store's default page size (DEFAULT_READ_FROM_SEQUENCE_LIMIT).
 const SHELL_RESUME_MAX_GAP = 1_000;
 
+// Same bound for thread resume. The replay reads the *global* event range and
+// filters per-thread afterwards, so a stale cursor far behind the head would
+// otherwise decode every intervening event's payload — reconnects with cursors
+// hundreds of thousands of events behind have OOM-killed servers on large
+// databases. Past this gap the client is reset with a fresh thread snapshot.
+const THREAD_RESUME_MAX_GAP = 1_000;
+
 function toAuthAccessStreamEvent(
   change: PairingGrantStore.BootstrapCredentialChange | SessionStore.SessionCredentialChange,
   revision: number,
@@ -1280,38 +1288,50 @@ const makeWsRpcLayer = (
               // catch-up followed by the buffered/ongoing live events. Overlapping
               // events are deduped by sequence on the client.
               //
-              // Read the full range after the cursor (not the store's default
-              // page-bounded limit): the range is normally tiny (a fresh HTTP
-              // snapshot sequence) and the per-thread filter runs after reading,
-              // so a global cap could otherwise omit this thread's events.
+              // The replay is bounded to the projection head captured below. The
+              // catch-up range is normally tiny (a fresh HTTP snapshot sequence),
+              // but a stale cached cursor can sit hundreds of thousands of global
+              // events behind — replaying that decodes every intervening event
+              // (including every other thread's tool payloads) only to discard
+              // almost all of them, which has OOM-killed servers on large
+              // databases. A truncated replay would silently drop this thread's
+              // events, so past the gap cap we reset the client with a fresh
+              // thread snapshot instead, exactly like subscribeShell above.
               if (input.afterSequence !== undefined) {
                 const afterSequence = input.afterSequence;
-                const catchUpStream = orchestrationEngine
-                  .readEvents(afterSequence, Number.MAX_SAFE_INTEGER)
-                  .pipe(
-                    Stream.filter(isThisThreadDetailEvent),
-                    Stream.map((event) => ({
-                      kind: "event" as const,
-                      event: projectActivityEvent(event),
-                    })),
-                    Stream.mapError(
-                      (cause) =>
-                        new OrchestrationGetSnapshotError({
-                          message: `Failed to replay thread ${input.threadId} events`,
-                          cause,
-                        }),
-                    ),
-                  );
-                const afterCatchUp =
-                  input.requestCompletionMarker === true
-                    ? Stream.concat(
-                        Stream.fromEffect(
-                          Queue.offer(liveBuffer, { kind: "synchronized" as const }),
-                        ).pipe(Stream.drain),
-                        bufferedLiveStream,
-                      )
-                    : bufferedLiveStream;
-                return Stream.concat(catchUpStream, afterCatchUp);
+                const headSequence = yield* orchestrationEngine.latestSequence;
+                const replayGap = headSequence - afterSequence;
+                if (replayGap >= 0 && replayGap <= THREAD_RESUME_MAX_GAP) {
+                  const catchUpStream = orchestrationEngine
+                    .readEvents(afterSequence, replayGap)
+                    .pipe(
+                      Stream.filter(isThisThreadDetailEvent),
+                      Stream.map((event) => ({
+                        kind: "event" as const,
+                        event: projectActivityEvent(event),
+                      })),
+                      Stream.mapError(
+                        (cause) =>
+                          new OrchestrationGetSnapshotError({
+                            message: `Failed to replay thread ${input.threadId} events`,
+                            cause,
+                          }),
+                      ),
+                    );
+                  const afterCatchUp =
+                    input.requestCompletionMarker === true
+                      ? Stream.concat(
+                          Stream.fromEffect(
+                            Queue.offer(liveBuffer, { kind: "synchronized" as const }),
+                          ).pipe(Stream.drain),
+                          bufferedLiveStream,
+                        )
+                      : bufferedLiveStream;
+                  return Stream.concat(catchUpStream, afterCatchUp);
+                }
+                // Gap too large (or cursor ahead of authoritative state): fall
+                // through to the snapshot path so the client converges from a
+                // fresh thread detail instead of an unbounded replay.
               }
 
               const snapshot = yield* projectionSnapshotQuery
@@ -1597,6 +1617,23 @@ const makeWsRpcLayer = (
             ),
             { "rpc.aggregate": "workspace" },
           ),
+        [WS_METHODS.projectsSearchContents]: (input) =>
+          observeRpcEffect(
+            WS_METHODS.projectsSearchContents,
+            workspaceEntries.searchContents(input).pipe(
+              Effect.mapError(
+                (cause) =>
+                  new ProjectSearchContentsError({
+                    cwd: input.cwd,
+                    queryLength: input.query.length,
+                    limit: input.limit,
+                    ...projectEntriesFailureContext(cause),
+                    cause,
+                  }),
+              ),
+            ),
+            { "rpc.aggregate": "workspace" },
+          ),
         [WS_METHODS.projectsListEntries]: (input) =>
           observeRpcEffect(
             WS_METHODS.projectsListEntries,
diff --git a/apps/web/package.json b/apps/web/package.json
index 1f227d77b16..46dbd802df7 100644
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "build:ghostty-wasm": "bash scripts/build-libghostty-wasm.sh",
     "dev": "vp dev",
     "build": "vp build",
     "preview": "vp preview",
@@ -34,8 +35,6 @@
     "@t3tools/shared": "workspace:*",
     "@tanstack/react-pacer": "^0.19.4",
     "@tanstack/react-router": "^1.160.2",
-    "@xterm/addon-fit": "^0.11.0",
-    "@xterm/xterm": "^6.0.0",
     "class-variance-authority": "^0.7.1",
     "effect": "catalog:",
     "jose": "catalog:",
diff --git a/apps/web/scripts/build-libghostty-wasm.sh b/apps/web/scripts/build-libghostty-wasm.sh
new file mode 100755
index 00000000000..d4b1238bbfc
--- /dev/null
+++ b/apps/web/scripts/build-libghostty-wasm.sh
@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WEB_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+REPO_DIR="$(cd "${WEB_DIR}/../.." && pwd)"
+CANONICAL_VENDOR_DIR="${REPO_DIR}/native/libghostty-vt"
+VENDOR_DIR="${WEB_DIR}/src/terminal/ghostty/vendor"
+
+GHOSTTY_REVISION="$(tr -d '[:space:]' < "${CANONICAL_VENDOR_DIR}/VERSION")"
+GHOSTTY_SOURCE_DIR="${GHOSTTY_SOURCE_DIR:-${HOME}/.cache/t3code/ghostty-${GHOSTTY_REVISION:0:8}}"
+GHOSTTY_ZIG_VERSION="${GHOSTTY_ZIG_VERSION:-0.15.2}"
+GHOSTTY_ZIG="${GHOSTTY_ZIG:-}"
+
+log() {
+  printf '[libghostty-vt-wasm] %s\n' "$*"
+}
+
+die() {
+  printf '[libghostty-vt-wasm] error: %s\n' "$*" >&2
+  exit 1
+}
+
+require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || die "missing required command: $1"
+}
+
+ensure_zig() {
+  if [[ -n "${GHOSTTY_ZIG}" ]]; then
+    [[ -x "${GHOSTTY_ZIG}" ]] || die "GHOSTTY_ZIG is not executable: ${GHOSTTY_ZIG}"
+    return
+  fi
+  if command -v zig >/dev/null 2>&1 && [[ "$(zig version)" == "${GHOSTTY_ZIG_VERSION}" ]]; then
+    GHOSTTY_ZIG="$(command -v zig)"
+    return
+  fi
+
+  local host_os host_arch cache_dir
+  host_os="$(uname -s | tr '[:upper:]' '[:lower:]')"
+  host_arch="$(uname -m)"
+  case "${host_os}" in
+    darwin) host_os="macos" ;;
+    linux) ;;
+    *) die "unsupported host OS for Zig download: ${host_os}" ;;
+  esac
+  case "${host_arch}" in
+    arm64) host_arch="aarch64" ;;
+    aarch64 | x86_64) ;;
+    *) die "unsupported host architecture: ${host_arch}" ;;
+  esac
+
+  cache_dir="${HOME}/.cache/t3code/zig-${GHOSTTY_ZIG_VERSION}"
+  GHOSTTY_ZIG="${cache_dir}/zig"
+  if [[ -x "${GHOSTTY_ZIG}" ]]; then
+    return
+  fi
+
+  require_cmd curl
+  require_cmd tar
+  mkdir -p "${cache_dir}"
+  log "downloading Zig ${GHOSTTY_ZIG_VERSION}"
+  curl -fsSL \
+    "https://ziglang.org/download/${GHOSTTY_ZIG_VERSION}/zig-${host_arch}-${host_os}-${GHOSTTY_ZIG_VERSION}.tar.xz" \
+    | tar -xJ --strip-components=1 -C "${cache_dir}"
+}
+
+ensure_ghostty_source() {
+  require_cmd git
+  if [[ ! -d "${GHOSTTY_SOURCE_DIR}/.git" ]]; then
+    mkdir -p "$(dirname "${GHOSTTY_SOURCE_DIR}")"
+    log "cloning Ghostty ${GHOSTTY_REVISION}"
+    git clone --filter=blob:none --no-checkout https://github.com/ghostty-org/ghostty.git \
+      "${GHOSTTY_SOURCE_DIR}"
+  fi
+
+  # A cached checkout may still be on a previously pinned revision; converge on
+  # the pinned one instead of failing the rebuild.
+  local actual_revision
+  actual_revision="$(git -C "${GHOSTTY_SOURCE_DIR}" rev-parse HEAD 2>/dev/null || echo none)"
+  if [[ "${actual_revision}" != "${GHOSTTY_REVISION}" ]]; then
+    log "checking out Ghostty ${GHOSTTY_REVISION}"
+    git -C "${GHOSTTY_SOURCE_DIR}" fetch --depth=1 origin "${GHOSTTY_REVISION}"
+    git -C "${GHOSTTY_SOURCE_DIR}" checkout --detach "${GHOSTTY_REVISION}"
+  fi
+
+  actual_revision="$(git -C "${GHOSTTY_SOURCE_DIR}" rev-parse HEAD)"
+  [[ "${actual_revision}" == "${GHOSTTY_REVISION}" ]] || \
+    die "expected Ghostty ${GHOSTTY_REVISION}, found ${actual_revision}"
+}
+
+ensure_zig
+ensure_ghostty_source
+
+build_root="$(mktemp -d)"
+trap 'rm -rf "${build_root}"' EXIT
+
+log "building ${GHOSTTY_REVISION} for wasm32-freestanding"
+(
+  cd "${GHOSTTY_SOURCE_DIR}"
+  # The pinned revision rides along as semver build metadata so the artifact
+  # identifies its own provenance through ghostty_build_info(); mobile's
+  # VERSION file stays the single source of truth for the pin.
+  "${GHOSTTY_ZIG}" build \
+    -Demit-lib-vt \
+    -Dtarget=wasm32-freestanding \
+    -Doptimize=ReleaseSmall \
+    -Dstrip=true \
+    -Dlib-version-string="0.1.0-dev+${GHOSTTY_REVISION}" \
+    -p "${build_root}"
+)
+
+mkdir -p "${VENDOR_DIR}"
+cp "${build_root}/bin/ghostty-vt.wasm" "${VENDOR_DIR}/ghostty-vt.wasm"
+"${GHOSTTY_ZIG}" build-exe \
+  "${SCRIPT_DIR}/ghostty-write-pty.zig" \
+  -target wasm32-freestanding \
+  -O ReleaseSmall \
+  -fno-entry \
+  -rdynamic \
+  -femit-bin="${VENDOR_DIR}/ghostty-write-pty.wasm"
+chmod 0644 "${VENDOR_DIR}/ghostty-write-pty.wasm"
+log "wrote ${VENDOR_DIR}/ghostty-vt.wasm"
diff --git a/apps/web/scripts/ghostty-write-pty.zig b/apps/web/scripts/ghostty-write-pty.zig
new file mode 100644
index 00000000000..dbe6688f5e8
--- /dev/null
+++ b/apps/web/scripts/ghostty-write-pty.zig
@@ -0,0 +1,5 @@
+extern "env" fn t3_write_pty(terminal: u32, userdata: u32, data: u32, len: u32) void;
+
+export fn ghostty_write_pty(terminal: u32, userdata: u32, data: u32, len: u32) void {
+    t3_write_pty(terminal, userdata, data, len);
+}
diff --git a/apps/web/src/__fork_guards__/geistTypography.test.ts b/apps/web/src/__fork_guards__/geistTypography.test.ts
index 7b395a6c530..8dc2bbed9cf 100644
--- a/apps/web/src/__fork_guards__/geistTypography.test.ts
+++ b/apps/web/src/__fork_guards__/geistTypography.test.ts
@@ -11,8 +11,8 @@
  * The terminal half is exercised as behaviour against the fork-owned module
  * rather than grepped for inside the drawer: string assertions on an upstream
  * file pin the code's *placement* instead of its effect, and would block moving
- * it. Only the two call sites are checked textually, because a rebase quietly
- * dropping them is precisely the failure this file exists to catch.
+ * it. Only the call site is checked textually, because a rebase quietly
+ * dropping it is precisely the failure this file exists to catch.
  */
 
 import * as NodeFS from "node:fs";
@@ -20,13 +20,7 @@ import * as NodeURL from "node:url";
 import { describe, expect, it } from "vite-plus/test";
 
 import { FORK_MARKER_ATTRIBUTE, FORK_MARKER_VALUE } from "../custom/forkMarker";
-import {
-  FORK_TERMINAL_FONT_FALLBACK,
-  firstFontFamily,
-  refitTerminalWhenFontsReady,
-  terminalFontFamilyFrom,
-  type ForkTerminalFontTarget,
-} from "../custom/terminalFont";
+import { FORK_TERMINAL_FONT_FALLBACK, terminalFontFamilyFrom } from "../custom/terminalFont";
 
 function readSibling(relativePath: string): string {
   return NodeFS.readFileSync(NodeURL.fileURLToPath(new URL(relativePath, import.meta.url)), "utf8");
@@ -43,52 +37,6 @@ function markerBlock(css: string): string {
   return css.slice(start, end);
 }
 
-interface TerminalProbe {
-  readonly target: ForkTerminalFontTarget;
-  /** Every value written to `options.fontFamily`, in order. */
-  readonly writes: string[];
-  readonly scrolls: () => number;
-}
-
-function terminalProbe(fontFamily: string, atBottom = true): TerminalProbe {
-  const writes: string[] = [];
-  let current = fontFamily;
-  let scrolls = 0;
-  return {
-    writes,
-    scrolls: () => scrolls,
-    target: {
-      cols: 80,
-      rows: 24,
-      options: {
-        get fontFamily() {
-          return current;
-        },
-        set fontFamily(value: string) {
-          current = value;
-          writes.push(value);
-        },
-      },
-      buffer: { active: { viewportY: atBottom ? 5 : 0, baseY: 5 } },
-      scrollToBottom: () => {
-        scrolls += 1;
-      },
-    },
-  };
-}
-
-function fakeFonts(loadResult: Promise<FontFace[]> = Promise.resolve([])) {
-  const requested: string[] = [];
-  const fonts = {
-    load: (font: string) => {
-      requested.push(font);
-      return loadResult;
-    },
-    ready: Promise.resolve(),
-  } as unknown as Pick<FontFaceSet, "load" | "ready">;
-  return { requested, fonts };
-}
-
 describe("fork guard: geist-typography", () => {
   it("bundles both Geist faces as dependencies", () => {
     const manifest = JSON.parse(readSibling("../../package.json")) as {
@@ -147,9 +95,24 @@ describe("fork guard: geist-typography", () => {
   });
 
   it("keeps the terminal wired to the fork-owned font module", () => {
+    // The ghostty surface takes its font as a creation option and handles the
+    // webfont re-measure itself; the fork's whole job is resolving --font-mono
+    // at the mount site. Lose this line and the terminal silently reverts to
+    // upstream's SF Mono-first default while the rest of the app is on Geist.
+    // Whitespace-tolerant: the formatter decides whether the literal wraps.
     const drawer = readSibling("../components/ThreadTerminalDrawer.tsx");
-    expect(drawer).toContain("fontFamily: resolveTerminalFontFamily(mount)");
-    expect(drawer).toContain("refitTerminalWhenFontsReady({");
+    expect(drawer).toMatch(/font:\s*\{\s*family:\s*resolveTerminalFontFamily\(mount\)/u);
+  });
+
+  it("keeps upstream's cold-load re-measure, which the fork's shim was deleted for", () => {
+    // The xterm-era refit shim was removed because the surface waits on
+    // document.fonts before measuring the cell grid and re-measures on
+    // loadingdone. If a sync drops either, Geist Mono measures at fallback
+    // advances with the PTY wrapping to a column count nobody re-derived —
+    // silently. This is the tripwire for that upstream dependency.
+    const surface = readSibling("../terminal/ghostty/surface.ts");
+    expect(surface).toContain("document.fonts.load(");
+    expect(surface).toContain('"loadingdone"');
   });
 
   describe("resolved stack", () => {
@@ -160,114 +123,25 @@ describe("fork guard: geist-typography", () => {
       expect(FORK_TERMINAL_FONT_FALLBACK.startsWith('"Geist Mono Variable"')).toBe(true);
     });
 
-    it("prefers the cascade-resolved value when present", () => {
+    it("strips the trailing generic so the surface's glyph fallbacks stay reachable", () => {
+      // The surface appends the Nerd Font fallbacks after whatever family it
+      // is given; a `monospace` generic mid-list would sit ahead of them, a
+      // stack shape upstream never produces. The generic returns at the true
+      // tail via the surface's own fallbacks.
       expect(terminalFontFamilyFrom(' "Geist Mono Variable", monospace ')).toBe(
-        '"Geist Mono Variable", monospace',
-      );
-    });
-
-    it("takes the first family for the font-load probe", () => {
-      expect(firstFontFamily('"Geist Mono Variable", "SF Mono", monospace')).toBe(
         '"Geist Mono Variable"',
       );
-      expect(firstFontFamily("")).toBeNull();
-    });
-  });
-
-  describe("cold-load re-measure", () => {
-    it("probes the resolved family rather than a hardcoded one", async () => {
-      // Hardcoding goes stale on a face swap, and would fetch Geist Mono even in
-      // an unmarked build — breaking the fork's own scoping invariant.
-      const probe = terminalProbe('"Geist Mono Variable", monospace');
-      const { requested, fonts } = fakeFonts();
-      await refitTerminalWhenFontsReady({
-        terminal: probe.target,
-        isCurrent: () => true,
-        fit: () => {},
-        resize: () => {},
-        fonts,
-        scheduleFrame: (callback) => callback(),
-      });
-      expect(requested).toEqual(['12px "Geist Mono Variable"']);
+      expect(FORK_TERMINAL_FONT_FALLBACK.endsWith("monospace")).toBe(false);
     });
 
-    it("re-applies the family so xterm re-measures, then tells the PTY", async () => {
-      // xterm's option setter drops equal writes, so the value has to change
-      // before it changes back. And nothing in the drawer subscribes to
-      // onResize: without the resize call the PTY keeps wrapping to the stale
-      // width while the local grid is corrected.
-      const probe = terminalProbe('"Geist Mono Variable", monospace');
-      const { fonts } = fakeFonts();
-      const resized: Array<[number, number]> = [];
-      let fitted = 0;
-
-      await refitTerminalWhenFontsReady({
-        terminal: probe.target,
-        isCurrent: () => true,
-        fit: () => {
-          fitted += 1;
-        },
-        resize: (cols, rows) => resized.push([cols, rows]),
-        fonts,
-        scheduleFrame: (callback) => callback(),
-      });
-
-      expect(probe.writes.length).toBe(2);
-      expect(probe.writes[0]).not.toBe(probe.writes[1]);
-      expect(probe.writes[1]).toBe('"Geist Mono Variable", monospace');
-      expect(fitted).toBe(1);
-      expect(resized).toEqual([[80, 24]]);
-      expect(probe.scrolls()).toBe(1);
-    });
-
-    it("holds the viewport when it was not pinned to the bottom", async () => {
-      const probe = terminalProbe('"Geist Mono Variable", monospace', false);
-      const { fonts } = fakeFonts();
-      await refitTerminalWhenFontsReady({
-        terminal: probe.target,
-        isCurrent: () => true,
-        fit: () => {},
-        resize: () => {},
-        fonts,
-        scheduleFrame: (callback) => callback(),
-      });
-      expect(probe.scrolls()).toBe(0);
-    });
-
-    it("leaves a torn-down terminal alone", async () => {
-      const probe = terminalProbe('"Geist Mono Variable", monospace');
-      const { fonts } = fakeFonts();
-      const resized: Array<[number, number]> = [];
-      await refitTerminalWhenFontsReady({
-        terminal: probe.target,
-        isCurrent: () => false,
-        fit: () => {},
-        resize: (cols, rows) => resized.push([cols, rows]),
-        fonts,
-        scheduleFrame: (callback) => callback(),
-      });
-      expect(probe.writes).toEqual([]);
-      expect(resized).toEqual([]);
+    it("prefers the cascade-resolved value when present", () => {
+      expect(terminalFontFamilyFrom(' "Geist Mono Variable", "SF Mono" ')).toBe(
+        '"Geist Mono Variable", "SF Mono"',
+      );
     });
 
-    it("survives a webfont that fails to load", async () => {
-      // FontFaceSet.load() rejects if a matching face fails. That must not
-      // surface as an unhandled rejection, and the re-fit should still run —
-      // the fallback metrics are simply the ones that stay correct.
-      const probe = terminalProbe('"Geist Mono Variable", monospace');
-      const { fonts } = fakeFonts(Promise.reject(new Error("404")));
-      let fitted = 0;
-      await refitTerminalWhenFontsReady({
-        terminal: probe.target,
-        isCurrent: () => true,
-        fit: () => {
-          fitted += 1;
-        },
-        resize: () => {},
-        fonts,
-        scheduleFrame: (callback) => callback(),
-      });
-      expect(fitted).toBe(1);
+    it("treats a generics-only stack as empty and falls back", () => {
+      expect(terminalFontFamilyFrom("monospace")).toBe(FORK_TERMINAL_FONT_FALLBACK);
     });
   });
 });
diff --git a/apps/web/src/cloud/linkEnvironment.ts b/apps/web/src/cloud/linkEnvironment.ts
index 22ff986afbd..a245cbc54db 100644
--- a/apps/web/src/cloud/linkEnvironment.ts
+++ b/apps/web/src/cloud/linkEnvironment.ts
@@ -145,7 +145,14 @@ function relayProtectedErrorMessage(error: RelayProtectedErrorType): string {
     case "RelayEnvironmentLinkProofInvalidError":
       return `Relay rejected the environment link proof (${error.reason}).`;
     case "RelayEnvironmentConnectNotAuthorizedError":
-      return "Relay rejected the environment connection request.";
+      // "Not authorized" covers non-auth causes too; surface the reason so a
+      // missing link doesn't read as a credential problem.
+      if (error.reason === "environment_link_not_found") {
+        return "Relay has no active link for this environment. The environment server may not have re-established its link yet.";
+      }
+      return error.reason
+        ? `Relay rejected the environment connection request (${error.reason}).`
+        : "Relay rejected the environment connection request.";
     case "RelayEnvironmentEndpointUnavailableError":
       return `Relay could not reach the environment endpoint (${error.reason}).`;
     case "RelayEnvironmentEndpointTimedOutError":
diff --git a/apps/web/src/components/ChatMarkdown.tsx b/apps/web/src/components/ChatMarkdown.tsx
index d86fe39a77f..985e943cb39 100644
--- a/apps/web/src/components/ChatMarkdown.tsx
+++ b/apps/web/src/components/ChatMarkdown.tsx
@@ -1,5 +1,4 @@
 import { useAtomValue } from "@effect/atom-react";
-import { DiffsHighlighter, getSharedHighlighter, SupportedLanguages } from "@pierre/diffs";
 import {
   CheckIcon,
   ChevronRightIcon,
@@ -57,6 +56,8 @@ import { useOpenInPreferredEditor } from "../editorPreferences";
 import { resolveDiffThemeName, type DiffThemeName } from "../lib/diffRendering";
 import { fnv1a32 } from "../lib/diffRendering";
 import { LRUCache } from "../lib/lruCache";
+import { getSyntaxHighlighterPromise } from "../lib/syntaxHighlighting";
+import { RenderErrorBoundary } from "./RenderErrorBoundary";
 import { useTheme } from "../hooks/useTheme";
 import { getClientSettings } from "../hooks/useSettings";
 import {
@@ -91,27 +92,6 @@ import {
   BrowserPreviewUnavailableError,
 } from "../browser/openFileInPreview";
 
-class CodeHighlightErrorBoundary extends React.Component<
-  { fallback: ReactNode; children: ReactNode },
-  { hasError: boolean }
-> {
-  constructor(props: { fallback: ReactNode; children: ReactNode }) {
-    super(props);
-    this.state = { hasError: false };
-  }
-
-  static getDerivedStateFromError() {
-    return { hasError: true };
-  }
-
-  override render() {
-    if (this.state.hasError) {
-      return this.props.fallback;
-    }
-    return this.props.children;
-  }
-}
-
 interface ChatMarkdownProps {
   text: string;
   cwd: string | undefined;
@@ -147,7 +127,6 @@ const highlightedCodeCache = new LRUCache<string>(
   MAX_HIGHLIGHT_CACHE_ENTRIES,
   MAX_HIGHLIGHT_CACHE_MEMORY_BYTES,
 );
-const highlighterPromiseCache = new Map<string, Promise<DiffsHighlighter>>();
 
 function findTaskListMarkerOffset(markdown: string, listItemStart: number): number | null {
   const firstLineEnd = markdown.indexOf("\n", listItemStart);
@@ -333,27 +312,6 @@ function estimateHighlightedSize(html: string, code: string): number {
   return Math.max(html.length * 2, code.length * 3);
 }
 
-function getHighlighterPromise(language: string): Promise<DiffsHighlighter> {
-  const cached = highlighterPromiseCache.get(language);
-  if (cached) return cached;
-
-  const promise = getSharedHighlighter({
-    themes: [resolveDiffThemeName("dark"), resolveDiffThemeName("light")],
-    langs: [language as SupportedLanguages],
-    preferredHighlighter: "shiki-js",
-  }).catch((err) => {
-    highlighterPromiseCache.delete(language);
-    if (language === "text") {
-      // "text" itself failed — Shiki cannot initialize at all, surface the error
-      throw err;
-    }
-    // Language not supported by Shiki — fall back to "text"
-    return getHighlighterPromise("text");
-  });
-  highlighterPromiseCache.set(language, promise);
-  return promise;
-}
-
 function readInitialWordWrapSetting(): boolean {
   return getClientSettings().wordWrap;
 }
@@ -743,7 +701,7 @@ function UncachedShikiCodeBlock({
   cacheKey,
   isStreaming,
 }: UncachedShikiCodeBlockProps) {
-  const highlighter = use(getHighlighterPromise(language));
+  const highlighter = use(getSyntaxHighlighterPromise(language));
   const highlightedHtml = useMemo(() => {
     try {
       return highlighter.codeToHtml(code, { lang: language, theme: themeName });
@@ -1605,7 +1563,7 @@ function ChatMarkdown({
             fenceTitle={fenceTitle}
             theme={resolvedTheme}
           >
-            <CodeHighlightErrorBoundary fallback={<pre {...props}>{children}</pre>}>
+            <RenderErrorBoundary fallback={<pre {...props}>{children}</pre>}>
               <Suspense fallback={<pre {...props}>{children}</pre>}>
                 <SuspenseShikiCodeBlock
                   className={codeBlock.className}
@@ -1614,7 +1572,7 @@ function ChatMarkdown({
                   isStreaming={isStreaming}
                 />
               </Suspense>
-            </CodeHighlightErrorBoundary>
+            </RenderErrorBoundary>
           </MarkdownCodeBlock>
         );
       },
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 79a58a79f12..b5d9623ed32 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -704,6 +704,19 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     () => drawerTerminalSessions.map((session) => session.target.terminalId),
     [drawerTerminalSessions],
   );
+  // Every client-side id source participates in allocation: the server list
+  // lags fresh opens, and panel terminals are filtered out of the drawer's
+  // sessions — an id collision attaches two viewports to one PTY session.
+  const allocatableTerminalIds = useMemo(
+    () => [
+      ...new Set([
+        ...serverOrderedTerminalIds,
+        ...terminalUiState.terminalIds,
+        ...panelTerminalIds,
+      ]),
+    ],
+    [panelTerminalIds, serverOrderedTerminalIds, terminalUiState.terminalIds],
+  );
   const storeSetTerminalHeight = useTerminalUiStateStore((state) => state.setTerminalHeight);
   const storeSplitTerminal = useTerminalUiStateStore((state) => state.splitTerminal);
   const storeSplitTerminalVertical = useTerminalUiStateStore(
@@ -773,7 +786,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     if (!cwd) {
       return;
     }
-    const terminalId = nextTerminalId(serverOrderedTerminalIds);
+    const terminalId = nextTerminalId(allocatableTerminalIds);
     storeSplitTerminal(threadRef, terminalId);
     bumpFocusRequestId();
     void openTerminal({
@@ -787,11 +800,11 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
       },
     });
   }, [
+    allocatableTerminalIds,
     bumpFocusRequestId,
     cwd,
     effectiveWorktreePath,
     runtimeEnv,
-    serverOrderedTerminalIds,
     storeSplitTerminal,
     threadId,
     threadRef,
@@ -801,7 +814,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     if (!cwd) {
       return;
     }
-    const terminalId = nextTerminalId(serverOrderedTerminalIds);
+    const terminalId = nextTerminalId(allocatableTerminalIds);
     storeSplitTerminalVertical(threadRef, terminalId);
     bumpFocusRequestId();
     void openTerminal({
@@ -815,12 +828,12 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
       },
     });
   }, [
+    allocatableTerminalIds,
     bumpFocusRequestId,
     cwd,
     effectiveWorktreePath,
     openTerminal,
     runtimeEnv,
-    serverOrderedTerminalIds,
     storeSplitTerminalVertical,
     threadId,
     threadRef,
@@ -830,7 +843,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     if (!cwd) {
       return;
     }
-    const terminalId = nextTerminalId(serverOrderedTerminalIds);
+    const terminalId = nextTerminalId(allocatableTerminalIds);
     storeNewTerminal(threadRef, terminalId);
     bumpFocusRequestId();
     void openTerminal({
@@ -847,8 +860,8 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
     bumpFocusRequestId,
     cwd,
     effectiveWorktreePath,
+    allocatableTerminalIds,
     runtimeEnv,
-    serverOrderedTerminalIds,
     storeNewTerminal,
     threadId,
     threadRef,
@@ -1521,6 +1534,10 @@ function ChatViewContent(props: ChatViewProps) {
       ),
     [rightPanelState.surfaces],
   );
+  const allocatableActiveTerminalIds = useMemo(
+    () => [...new Set([...activeKnownTerminalIds, ...panelTerminalIds])],
+    [activeKnownTerminalIds, panelTerminalIds],
+  );
   const previewPanelOpen = activeRightPanelKind === "preview" && isPreviewSupportedInRuntime();
   const rightPanelOpen = rightPanelState.isOpen;
   const canMaximizeRightPanel = rightPanelOpen && !shouldUsePlanSidebarSheet;
@@ -1883,46 +1900,75 @@ function ChatViewContent(props: ChatViewProps) {
   );
   const systemComposerBannerItems = useMemo<ComposerBannerStackItem[]>(() => {
     const items: ComposerBannerStackItem[] = [];
-    const resumingServerUpdate =
-      serverUpdateState.status === "running" && serverUpdateState.stage === "resuming";
-    if (activeEnvironmentUnavailableState && !resumingServerUpdate) {
-      const connection = activeEnvironmentUnavailableState.connection;
-      const isReconnecting =
-        connection.phase === "connecting" || connection.phase === "reconnecting";
-      items.push({
-        id: `environment-unavailable:${activeEnvironmentUnavailableState.environmentId}`,
-        variant: connection.phase === "error" ? "error" : "warning",
-        icon: <WifiOffIcon />,
-        title: `${activeEnvironmentUnavailableState.label}: ${connectionStatusTitle(connection)}`,
-        description:
-          connection.error ??
-          "Reconnect this environment before sending messages or running actions.",
-        actions: (
-          <>
-            <Button
-              size="xs"
-              disabled={isReconnecting}
-              onClick={() =>
-                void handleReconnectActiveEnvironment(
-                  activeEnvironmentUnavailableState.environmentId,
-                )
-              }
-            >
-              {isReconnecting ? "Reconnecting..." : "Reconnect"}
-            </Button>
-            <Button
-              size="xs"
-              variant="outline"
-              onClick={() => void navigate({ to: "/settings/connections" })}
-            >
-              Connections
-            </Button>
-          </>
-        ),
-      });
+    const updateRunning = serverUpdateState.status === "running";
+    const unavailableConnection = activeEnvironmentUnavailableState?.connection ?? null;
+    const environmentReconnecting =
+      unavailableConnection !== null &&
+      (unavailableConnection.phase === "connecting" ||
+        unavailableConnection.phase === "reconnecting");
+    // Reconnecting to a version-skewed server with no update in flight
+    // usually means the server is restarting mid-update and a refresh wiped
+    // the in-memory update state. Fold the reconnect and version banners
+    // into one calm line instead of stacking "Failed to connect" on
+    // "versions differ". A failed update never folds: its error and retry
+    // action must stay visible.
+    const reconnectingThroughVersionSkew =
+      serverUpdateState.status === "idle" && environmentReconnecting && versionMismatch !== null;
+    // While an update runs, transient connect blips are expected (the server
+    // restarts) and the update banner already shows progress. Hard failure
+    // phases still surface so the Reconnect action stays reachable.
+    const suppressUnavailableBanner = updateRunning && environmentReconnecting;
+    if (activeEnvironmentUnavailableState && unavailableConnection && !suppressUnavailableBanner) {
+      if (reconnectingThroughVersionSkew) {
+        items.push({
+          id: `environment-unavailable:${activeEnvironmentUnavailableState.environmentId}`,
+          variant: "default",
+          icon: (
+            <span
+              className="size-1.5 animate-status-pulse rounded-full bg-foreground"
+              aria-hidden="true"
+            />
+          ),
+          title: `${unavailableConnection.phase === "connecting" ? "Connecting" : "Reconnecting"} to ${activeEnvironmentUnavailableState.label}`,
+          description: "It may be finishing an update. One moment.",
+        });
+      } else {
+        items.push({
+          id: `environment-unavailable:${activeEnvironmentUnavailableState.environmentId}`,
+          variant: unavailableConnection.phase === "error" ? "error" : "warning",
+          icon: <WifiOffIcon />,
+          title: `${activeEnvironmentUnavailableState.label}: ${connectionStatusTitle(unavailableConnection)}`,
+          description:
+            unavailableConnection.error ??
+            "Reconnect this environment before sending messages or running actions.",
+          actions: (
+            <>
+              <Button
+                size="xs"
+                disabled={environmentReconnecting}
+                onClick={() =>
+                  void handleReconnectActiveEnvironment(
+                    activeEnvironmentUnavailableState.environmentId,
+                  )
+                }
+              >
+                {environmentReconnecting ? "Reconnecting..." : "Reconnect"}
+              </Button>
+              <Button
+                size="xs"
+                variant="outline"
+                onClick={() => void navigate({ to: "/settings/connections" })}
+              >
+                Connections
+              </Button>
+            </>
+          ),
+        });
+      }
     }
     if (
       serverUpdateEnvironmentId &&
+      !reconnectingThroughVersionSkew &&
       (serverUpdateState.status !== "idle" ||
         (showVersionMismatchBanner && versionMismatch && versionMismatchDismissKey))
     ) {
@@ -1930,8 +1976,15 @@ function ChatViewContent(props: ChatViewProps) {
       const updateFailed = serverUpdateState.status === "failed";
       items.push({
         id: `server-version:${serverUpdateEnvironmentId}`,
-        variant: updateFailed ? "error" : "warning",
-        icon: <TriangleAlertIcon />,
+        variant: updateFailed ? "error" : updateInProgress ? "default" : "warning",
+        icon: updateInProgress ? (
+          <span
+            className="size-1.5 animate-status-pulse rounded-full bg-foreground"
+            aria-hidden="true"
+          />
+        ) : (
+          <TriangleAlertIcon />
+        ),
         title:
           updateInProgress || updateFailed
             ? `${updateFailed ? "Could not update" : "Updating"} ${versionMismatchServerLabel}`
@@ -1940,7 +1993,6 @@ function ChatViewContent(props: ChatViewProps) {
           updateInProgress || updateFailed ? (
             <ServerUpdateProgress
               fromVersion={serverUpdateState.fromVersion}
-              serverLabel={versionMismatchServerLabel}
               state={serverUpdateState}
             />
           ) : versionMismatch ? (
@@ -2593,7 +2645,7 @@ function ChatViewContent(props: ChatViewProps) {
       if (!cwdForOpen) {
         return;
       }
-      const terminalId = nextTerminalId([...activeKnownTerminalIds, ...panelTerminalIds]);
+      const terminalId = nextTerminalId(allocatableActiveTerminalIds);
       storeEnsureTerminal(activeThreadRef, terminalId, { open: true });
       void openTerminal({
         environmentId,
@@ -2612,15 +2664,14 @@ function ChatViewContent(props: ChatViewProps) {
     }
     setTerminalOpen(nextOpen);
   }, [
-    activeKnownTerminalIds,
     activeProject,
     activeThreadId,
     activeThreadRef,
     activeThreadWorktreePath,
+    allocatableActiveTerminalIds,
     environmentId,
     gitCwd,
     openTerminal,
-    panelTerminalIds,
     setTerminalOpen,
     storeEnsureTerminal,
     terminalUiState.terminalIds.length,
@@ -2635,7 +2686,7 @@ function ChatViewContent(props: ChatViewProps) {
       if (!cwdForOpen) {
         return;
       }
-      const terminalId = nextTerminalId(activeKnownTerminalIds);
+      const terminalId = nextTerminalId(allocatableActiveTerminalIds);
       if (direction === "vertical") {
         storeSplitTerminalVertical(activeThreadRef, terminalId);
       } else {
@@ -2658,8 +2709,8 @@ function ChatViewContent(props: ChatViewProps) {
     },
     [
       activeProject,
-      activeKnownTerminalIds,
       activeThreadId,
+      allocatableActiveTerminalIds,
       activeThreadRef,
       openTerminal,
       activeThreadWorktreePath,
@@ -2678,7 +2729,7 @@ function ChatViewContent(props: ChatViewProps) {
     if (!cwdForOpen) {
       return;
     }
-    const terminalId = nextTerminalId(activeKnownTerminalIds);
+    const terminalId = nextTerminalId(allocatableActiveTerminalIds);
     storeNewTerminal(activeThreadRef, terminalId);
     setTerminalFocusRequestId((value) => value + 1);
     void openTerminal({
@@ -2696,8 +2747,8 @@ function ChatViewContent(props: ChatViewProps) {
     });
   }, [
     activeProject,
-    activeKnownTerminalIds,
     activeThreadId,
+    allocatableActiveTerminalIds,
     activeThreadRef,
     openTerminal,
     activeThreadWorktreePath,
@@ -2783,7 +2834,7 @@ function ChatViewContent(props: ChatViewProps) {
         ...(options?.env ? { extraEnv: options.env } : {}),
       });
       const targetTerminalId = shouldCreateNewTerminal
-        ? nextTerminalId(activeKnownTerminalIds)
+        ? nextTerminalId(allocatableActiveTerminalIds)
         : baseTerminalId;
       const openTerminalInput: TerminalOpenInput = shouldCreateNewTerminal
         ? {
@@ -2851,6 +2902,7 @@ function ChatViewContent(props: ChatViewProps) {
       environmentId,
       openTerminal,
       activeKnownTerminalIds,
+      allocatableActiveTerminalIds,
       runningTerminalIds,
       terminalUiState.activeTerminalId,
       writeTerminal,
@@ -3109,7 +3161,7 @@ function ChatViewContent(props: ChatViewProps) {
   const addTerminalSurface = useCallback(() => {
     if (!activeThreadRef || !activeThreadId || !activeProject) return;
     const cwd = gitCwd ?? activeProject.workspaceRoot;
-    const terminalId = nextTerminalId([...activeKnownTerminalIds, ...panelTerminalIds]);
+    const terminalId = nextTerminalId(allocatableActiveTerminalIds);
     useRightPanelStore.getState().openTerminal(activeThreadRef, terminalId);
     setTerminalFocusRequestId((value) => value + 1);
     void openTerminal({
@@ -3126,14 +3178,13 @@ function ChatViewContent(props: ChatViewProps) {
       },
     });
   }, [
-    activeKnownTerminalIds,
     activeProject,
     activeThreadId,
     activeThreadRef,
     activeThreadWorktreePath,
+    allocatableActiveTerminalIds,
     gitCwd,
     openTerminal,
-    panelTerminalIds,
   ]);
   const splitPanelTerminal = useCallback(
     (direction: "horizontal" | "vertical" = "horizontal") => {
@@ -3146,7 +3197,7 @@ function ChatViewContent(props: ChatViewProps) {
       ) {
         return;
       }
-      const terminalId = nextTerminalId([...activeKnownTerminalIds, ...panelTerminalIds]);
+      const terminalId = nextTerminalId(allocatableActiveTerminalIds);
       const cwd = gitCwd ?? activeProject.workspaceRoot;
       useRightPanelStore
         .getState()
@@ -3167,15 +3218,14 @@ function ChatViewContent(props: ChatViewProps) {
       });
     },
     [
-      activeKnownTerminalIds,
       activeProject,
       activeRightPanelSurface,
       activeThreadId,
       activeThreadRef,
       activeThreadWorktreePath,
+      allocatableActiveTerminalIds,
       gitCwd,
       openTerminal,
-      panelTerminalIds,
     ],
   );
   const splitPanelTerminalVertical = useCallback(() => {
@@ -5870,7 +5920,7 @@ function ChatViewContent(props: ChatViewProps) {
                     aria-label="Scroll to end"
                     title="Scroll to end"
                     onClick={() => scrollToEnd(true)}
-                    className="pointer-events-auto flex items-center gap-1.5 rounded-full border border-border/60 bg-card px-3 py-1 text-muted-foreground text-xs shadow-sm transition-colors hover:border-border hover:text-foreground hover:cursor-pointer"
+                    className="chat-composer-glass pointer-events-auto flex items-center gap-1.5 rounded-full border border-border/60 px-3 py-1 text-muted-foreground text-xs shadow-sm transition-colors hover:border-border hover:text-foreground hover:cursor-pointer"
                   >
                     <ChevronDownIcon className="size-3.5" />
                     Scroll to end
diff --git a/apps/web/src/components/CommandPalette.logic.test.ts b/apps/web/src/components/CommandPalette.logic.test.ts
index 5b4accc9fc7..4d591500f5c 100644
--- a/apps/web/src/components/CommandPalette.logic.test.ts
+++ b/apps/web/src/components/CommandPalette.logic.test.ts
@@ -6,9 +6,81 @@ import {
   buildThreadActionItems,
   enumerateCommandPaletteItems,
   filterCommandPaletteGroups,
+  reduceCommandPaletteUiState,
   type CommandPaletteGroup,
 } from "./CommandPalette.logic";
 
+describe("reduceCommandPaletteUiState", () => {
+  const closedState = { open: false, mode: "command", openIntent: null } as const;
+
+  it("toggles each overlay mode open and closed", () => {
+    const filesOpen = reduceCommandPaletteUiState(closedState, {
+      _tag: "ToggleMode",
+      mode: "files",
+    });
+    expect(filesOpen).toEqual({ open: true, mode: "files", openIntent: null });
+
+    const contentOpen = reduceCommandPaletteUiState(filesOpen, {
+      _tag: "ToggleMode",
+      mode: "content",
+    });
+    expect(contentOpen).toEqual({ open: true, mode: "content", openIntent: null });
+
+    expect(
+      reduceCommandPaletteUiState(contentOpen, { _tag: "ToggleMode", mode: "content" }),
+    ).toEqual({ open: false, mode: "command", openIntent: null });
+  });
+
+  it("switches between open modes without closing", () => {
+    const filesOpen = reduceCommandPaletteUiState(closedState, {
+      _tag: "ToggleMode",
+      mode: "files",
+    });
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "ToggleMode", mode: "command" })).toEqual(
+      {
+        open: true,
+        mode: "command",
+        openIntent: null,
+      },
+    );
+  });
+
+  it("routes open intents to command mode", () => {
+    const filesOpen = reduceCommandPaletteUiState(closedState, {
+      _tag: "ToggleMode",
+      mode: "files",
+    });
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "OpenAddProject" })).toEqual({
+      open: true,
+      mode: "command",
+      openIntent: { kind: "add-project" },
+    });
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "OpenNewThreadIn" })).toEqual({
+      open: true,
+      mode: "command",
+      openIntent: { kind: "new-thread-in" },
+    });
+  });
+
+  it("resets to command mode for dialog-driven opens and closes", () => {
+    const filesOpen = reduceCommandPaletteUiState(closedState, {
+      _tag: "ToggleMode",
+      mode: "files",
+    });
+
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "SetOpen", open: false })).toEqual({
+      open: false,
+      mode: "command",
+      openIntent: null,
+    });
+    expect(reduceCommandPaletteUiState(filesOpen, { _tag: "SetOpen", open: true })).toEqual({
+      open: true,
+      mode: "command",
+      openIntent: null,
+    });
+  });
+});
+
 describe("enumerateCommandPaletteItems", () => {
   it("assigns positional jump shortcuts to the first nine displayed items", () => {
     const items = Array.from({ length: 10 }, (_, index) => ({
diff --git a/apps/web/src/components/CommandPalette.logic.ts b/apps/web/src/components/CommandPalette.logic.ts
index 7a07cc48481..eee6ba5886e 100644
--- a/apps/web/src/components/CommandPalette.logic.ts
+++ b/apps/web/src/components/CommandPalette.logic.ts
@@ -15,6 +15,55 @@ export const RECENT_THREAD_LIMIT = 12;
 export const ITEM_ICON_CLASS = "size-4 text-muted-foreground/80";
 export const ADDON_ICON_CLASS = "size-4";
 
+/**
+ * The global search overlay hosts three mutually exclusive surfaces: the
+ * command palette (⌘K), the project file picker (⌘P), and project content
+ * search (⇧⌘F). One reducer owns open/mode state so the surfaces can never
+ * stack and re-triggering a mode's shortcut toggles it closed.
+ */
+export type SearchOverlayMode = "command" | "files" | "content";
+
+export interface CommandPaletteOpenIntent {
+  readonly kind: "add-project" | "new-thread-in";
+}
+
+export interface CommandPaletteUiState {
+  readonly open: boolean;
+  readonly mode: SearchOverlayMode;
+  readonly openIntent: CommandPaletteOpenIntent | null;
+}
+
+export type CommandPaletteUiAction =
+  | { readonly _tag: "SetOpen"; readonly open: boolean }
+  | { readonly _tag: "ToggleMode"; readonly mode: SearchOverlayMode }
+  | { readonly _tag: "OpenAddProject" }
+  | { readonly _tag: "OpenNewThreadIn" }
+  | { readonly _tag: "ClearOpenIntent" };
+
+export function reduceCommandPaletteUiState(
+  state: CommandPaletteUiState,
+  action: CommandPaletteUiAction,
+): CommandPaletteUiState {
+  switch (action._tag) {
+    case "SetOpen":
+      return {
+        open: action.open,
+        mode: "command",
+        openIntent: action.open ? state.openIntent : null,
+      };
+    case "ToggleMode":
+      return state.open && state.mode === action.mode
+        ? { open: false, mode: "command", openIntent: null }
+        : { open: true, mode: action.mode, openIntent: null };
+    case "OpenAddProject":
+      return { open: true, mode: "command", openIntent: { kind: "add-project" } };
+    case "OpenNewThreadIn":
+      return { open: true, mode: "command", openIntent: { kind: "new-thread-in" } };
+    case "ClearOpenIntent":
+      return state.openIntent ? { ...state, openIntent: null } : state;
+  }
+}
+
 export interface CommandPaletteThreadContentMatch {
   readonly source: "user" | "assistant";
   readonly snippet: string;
@@ -26,7 +75,7 @@ export interface CommandPaletteItem {
   readonly value: string;
   readonly searchTerms: ReadonlyArray<string>;
   readonly title: ReactNode;
-  readonly description?: string;
+  readonly description?: ReactNode;
   readonly threadContentMatch?: CommandPaletteThreadContentMatch;
   readonly timestamp?: string;
   readonly icon: ReactNode;
diff --git a/apps/web/src/components/CommandPalette.tsx b/apps/web/src/components/CommandPalette.tsx
index 94870fef3eb..853d317655a 100644
--- a/apps/web/src/components/CommandPalette.tsx
+++ b/apps/web/src/components/CommandPalette.tsx
@@ -28,16 +28,16 @@ import {
 import { useNavigate, useParams } from "@tanstack/react-router";
 import * as Option from "effect/Option";
 import {
-  ArrowDownIcon,
   ArrowLeftIcon,
-  ArrowUpIcon,
   CornerLeftUpIcon,
+  FileSearchIcon,
   FolderIcon,
   FolderPlusIcon,
   LinkIcon,
   MessageSquareIcon,
   SettingsIcon,
   SquarePenIcon,
+  TextSearchIcon,
 } from "lucide-react";
 import {
   useCallback,
@@ -81,7 +81,9 @@ import {
   resolveProjectPathForDispatch,
 } from "../lib/projectPaths";
 import { onOpenCommandPalette } from "../commandPaletteBus";
+import { isPreviewFocused } from "../lib/previewFocus";
 import { isTerminalFocused } from "../lib/terminalFocus";
+import { selectActiveRightPanel, useRightPanelStore } from "../rightPanelStore";
 import { getLatestThreadForProject, sortThreads } from "../lib/threadSort";
 import { cn, isMacPlatform, isWindowsPlatform, newProjectId } from "../lib/utils";
 import { selectThreadTerminalUiState, useTerminalUiStateStore } from "../terminalUiStateStore";
@@ -100,6 +102,7 @@ import {
   buildThreadActionItems,
   enumerateCommandPaletteItems,
   type CommandPaletteActionItem,
+  type CommandPaletteOpenIntent,
   type CommandPaletteSubmenuItem,
   type CommandPaletteView,
   filterCommandPaletteGroups,
@@ -107,24 +110,22 @@ import {
   getCommandPaletteMode,
   ITEM_ICON_CLASS,
   RECENT_THREAD_LIMIT,
+  reduceCommandPaletteUiState,
+  type SearchOverlayMode,
 } from "./CommandPalette.logic";
 import { orderItemsByPreferredIds, sortLogicalProjectsForSidebar } from "./Sidebar.logic";
 import { resolveEnvironmentOptionLabel } from "./BranchToolbar.logic";
+import { CommandPaletteContent } from "./CommandPaletteContent";
 import { CommandPaletteResults } from "./CommandPaletteResults";
 import { AzureDevOpsIcon, BitbucketIcon, GitHubIcon, GitLabIcon } from "./Icons";
 import { ProjectFavicon } from "./ProjectFavicon";
+import { ProjectFilePicker } from "./files/ProjectFilePicker";
+import { ProjectContentSearchDialog } from "./search/ProjectContentSearchDialog";
 import { ThreadRowLeadingStatus, ThreadRowTrailingStatus } from "./ThreadStatusIndicators";
 import { primaryServerKeybindingsAtom, primaryServerProvidersAtom } from "../state/server";
 import { resolveDefaultProviderModelSelection } from "../providerInstances";
 import { resolveShortcutCommand, threadJumpIndexFromCommand } from "../keybindings";
-import {
-  Command,
-  CommandDialog,
-  CommandDialogPopup,
-  CommandFooter,
-  CommandInput,
-  CommandPanel,
-} from "./ui/command";
+import { CommandDialog, CommandDialogPopup } from "./ui/command";
 import { Button } from "./ui/button";
 import { Kbd, KbdGroup } from "./ui/kbd";
 import { stackedThreadToast, toastManager } from "./ui/toast";
@@ -346,50 +347,30 @@ function errorMessage(error: unknown): string {
   return "An error occurred.";
 }
 
-interface CommandPaletteOpenIntent {
-  readonly kind: "add-project" | "new-thread-in";
-}
-
-interface CommandPaletteUiState {
-  readonly open: boolean;
-  readonly openIntent: CommandPaletteOpenIntent | null;
-}
+const OVERLAY_MODE_BY_COMMAND = {
+  "commandPalette.toggle": "command",
+  "filePicker.toggle": "files",
+  "projectSearch.toggle": "content",
+} as const satisfies Partial<Record<string, SearchOverlayMode>>;
 
-type CommandPaletteUiAction =
-  | { readonly _tag: "SetOpen"; readonly open: boolean }
-  | { readonly _tag: "Toggle" }
-  | { readonly _tag: "OpenAddProject" }
-  | { readonly _tag: "OpenNewThreadIn" }
-  | { readonly _tag: "ClearOpenIntent" };
-
-function reduceCommandPaletteUiState(
-  state: CommandPaletteUiState,
-  action: CommandPaletteUiAction,
-): CommandPaletteUiState {
-  switch (action._tag) {
-    case "SetOpen":
-      return {
-        open: action.open,
-        openIntent: action.open ? state.openIntent : null,
-      };
-    case "Toggle":
-      return { open: !state.open, openIntent: null };
-    case "OpenAddProject":
-      return { open: true, openIntent: { kind: "add-project" } };
-    case "OpenNewThreadIn":
-      return { open: true, openIntent: { kind: "new-thread-in" } };
-    case "ClearOpenIntent":
-      return state.openIntent ? { ...state, openIntent: null } : state;
-  }
+function overlayModeForCommand(command: string | null): SearchOverlayMode | null {
+  if (command === null) return null;
+  return command in OVERLAY_MODE_BY_COMMAND
+    ? OVERLAY_MODE_BY_COMMAND[command as keyof typeof OVERLAY_MODE_BY_COMMAND]
+    : null;
 }
 
 export function CommandPalette({ children }: { children: ReactNode }) {
   const [state, dispatch] = useReducer(reduceCommandPaletteUiState, {
     open: false,
+    mode: "command",
     openIntent: null,
   });
   const setOpen = useCallback((open: boolean) => dispatch({ _tag: "SetOpen", open }), []);
-  const toggleOpen = useCallback(() => dispatch({ _tag: "Toggle" }), []);
+  const toggleMode = useCallback(
+    (mode: SearchOverlayMode) => dispatch({ _tag: "ToggleMode", mode }),
+    [],
+  );
   const openAddProject = useCallback(() => dispatch({ _tag: "OpenAddProject" }), []);
   const openNewThreadIn = useCallback(() => dispatch({ _tag: "OpenNewThreadIn" }), []);
   const clearOpenIntent = useCallback(() => dispatch({ _tag: "ClearOpenIntent" }), []);
@@ -405,26 +386,48 @@ export function CommandPalette({ children }: { children: ReactNode }) {
       ? selectThreadTerminalUiState(state.terminalUiStateByThreadKey, routeThreadRef).terminalOpen
       : false,
   );
+  const previewOpen = useRightPanelStore((state) =>
+    routeThreadRef
+      ? selectActiveRightPanel(state.byThreadKey, routeThreadRef) === "preview"
+      : false,
+  );
+
+  useEffect(() => {
+    if (!state.open || state.mode === "command") return;
+    const onEscapeKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.isComposing || event.key !== "Escape") return;
+      event.preventDefault();
+      event.stopPropagation();
+      toggleMode("command");
+    };
+    window.addEventListener("keydown", onEscapeKeyDown, true);
+    return () => window.removeEventListener("keydown", onEscapeKeyDown, true);
+  }, [state.mode, state.open, toggleMode]);
 
   useEffect(() => {
     const onKeyDown = (event: globalThis.KeyboardEvent) => {
       if (event.defaultPrevented) return;
+      // Resolve with the complete shortcut context so customized bindings
+      // using any documented `when` condition (e.g. previewFocus) work.
       const command = resolveShortcutCommand(event, keybindings, {
         context: {
           terminalFocus: isTerminalFocused(),
           terminalOpen,
+          previewFocus: isPreviewFocused(),
+          previewOpen,
         },
       });
-      if (command !== "commandPalette.toggle") {
+      const mode = overlayModeForCommand(command);
+      if (mode === null) {
         return;
       }
       event.preventDefault();
       event.stopPropagation();
-      toggleOpen();
+      toggleMode(mode);
     };
     window.addEventListener("keydown", onKeyDown);
     return () => window.removeEventListener("keydown", onKeyDown);
-  }, [keybindings, terminalOpen, toggleOpen]);
+  }, [keybindings, previewOpen, terminalOpen, toggleMode]);
 
   useEffect(
     () =>
@@ -442,12 +445,24 @@ export function CommandPalette({ children }: { children: ReactNode }) {
 
   return (
     <ComposerHandleContext value={composerHandleRef}>
-      <CommandDialog open={state.open} onOpenChange={setOpen}>
+      <CommandDialog
+        open={state.open}
+        onOpenChange={(open, eventDetails) => {
+          if (!open && eventDetails.reason === "escape-key" && state.mode !== "command") {
+            eventDetails.cancel();
+            toggleMode("command");
+            return;
+          }
+          setOpen(open);
+        }}
+      >
         {children}
         <CommandPaletteDialog
           open={state.open}
+          mode={state.mode}
           openIntent={state.openIntent}
           setOpen={setOpen}
+          openOverlayMode={toggleMode}
           clearOpenIntent={clearOpenIntent}
         />
       </CommandDialog>
@@ -457,31 +472,63 @@ export function CommandPalette({ children }: { children: ReactNode }) {
 
 function CommandPaletteDialog(props: {
   readonly open: boolean;
+  readonly mode: SearchOverlayMode;
   readonly openIntent: CommandPaletteOpenIntent | null;
   readonly setOpen: (open: boolean) => void;
+  readonly openOverlayMode: (mode: SearchOverlayMode) => void;
   readonly clearOpenIntent: () => void;
 }) {
+  const composerHandleRef = useComposerHandleContext();
+
   if (!props.open) {
     return null;
   }
 
   return (
-    <OpenCommandPaletteDialog
-      openIntent={props.openIntent}
-      setOpen={props.setOpen}
-      clearOpenIntent={props.clearOpenIntent}
-    />
+    <CommandDialogPopup
+      aria-label={
+        props.mode === "files"
+          ? "File picker"
+          : props.mode === "content"
+            ? "Search project contents"
+            : "Command palette"
+      }
+      className={cn("overflow-hidden p-0", props.mode === "content" && "h-105")}
+      data-command-palette="true"
+      data-palette-mode={props.mode}
+      data-testid="command-palette"
+      finalFocus={() => {
+        composerHandleRef?.current?.focusAtEnd();
+        return false;
+      }}
+      onBackdropPointerDown={() => {
+        props.setOpen(false);
+      }}
+    >
+      {props.mode === "files" ? (
+        <ProjectFilePicker setOpen={props.setOpen} />
+      ) : props.mode === "content" ? (
+        <ProjectContentSearchDialog onOpenChange={props.setOpen} />
+      ) : (
+        <OpenCommandPaletteDialog
+          openIntent={props.openIntent}
+          setOpen={props.setOpen}
+          openOverlayMode={props.openOverlayMode}
+          clearOpenIntent={props.clearOpenIntent}
+        />
+      )}
+    </CommandDialogPopup>
   );
 }
 
 function OpenCommandPaletteDialog(props: {
   readonly openIntent: CommandPaletteOpenIntent | null;
   readonly setOpen: (open: boolean) => void;
+  readonly openOverlayMode: (mode: SearchOverlayMode) => void;
   readonly clearOpenIntent: () => void;
 }) {
   const navigate = useNavigate();
-  const { clearOpenIntent, openIntent, setOpen } = props;
-  const composerHandleRef = useComposerHandleContext();
+  const { clearOpenIntent, openIntent, openOverlayMode, setOpen } = props;
   const [query, setQuery] = useState("");
   const deferredQuery = useDeferredValue(query);
   const isActionsOnly = deferredQuery.startsWith(">");
@@ -1346,6 +1393,32 @@ function OpenCommandPaletteDialog(props: {
     });
   }
 
+  actionItems.push({
+    kind: "action",
+    value: "action:open-file-picker",
+    searchTerms: ["go to file", "open file", "file picker", "find file", "quick open"],
+    title: "Go to file",
+    icon: <FileSearchIcon className={ITEM_ICON_CLASS} />,
+    keepOpen: true,
+    shortcutCommand: "filePicker.toggle",
+    run: async () => {
+      openOverlayMode("files");
+    },
+  });
+
+  actionItems.push({
+    kind: "action",
+    value: "action:search-project-contents",
+    searchTerms: ["search project", "find in files", "grep", "content search", "text search"],
+    title: "Search project contents",
+    icon: <TextSearchIcon className={ITEM_ICON_CLASS} />,
+    keepOpen: true,
+    shortcutCommand: "projectSearch.toggle",
+    run: async () => {
+      openOverlayMode("content");
+    },
+  });
+
   actionItems.push({
     kind: "action",
     value: "action:add-project",
@@ -2062,236 +2135,189 @@ function OpenCommandPaletteDialog(props: {
     primaryEnvironmentId,
   ]);
 
+  const inputAccessory =
+    addProjectCloneFlow?.step === "repository" ? (
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <Button
+              variant="outline"
+              size="xs"
+              tabIndex={-1}
+              className="absolute inset-e-2.5 top-1/2 gap-1.5 pe-1 ps-2 -translate-y-1/2"
+              aria-label={`${remoteProjectButtonLabel ?? "Continue"} (Enter)`}
+              disabled={!canSubmitRemoteProjectFlow}
+              onMouseDown={(event) => {
+                event.preventDefault();
+              }}
+              onClick={() => {
+                void submitAddProjectCloneFlow();
+              }}
+            />
+          }
+        >
+          <span>{isRemoteProjectPending ? "Working" : remoteProjectButtonLabel}</span>
+          <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
+            <Kbd>Enter</Kbd>
+          </KbdGroup>
+        </TooltipTrigger>
+        <TooltipPopup side="top">{remoteProjectButtonLabel ?? "Continue"} (Enter)</TooltipPopup>
+      </Tooltip>
+    ) : isBrowsing ? (
+      <Tooltip>
+        <TooltipTrigger
+          render={
+            <Button
+              variant="outline"
+              size="xs"
+              tabIndex={-1}
+              className={cn(
+                "absolute inset-e-2.5 top-1/2 pe-1 ps-2 -translate-y-1/2",
+                hasHighlightedBrowseItem ? "gap-1" : "gap-1.5",
+              )}
+              aria-label={`${submitActionLabel} (${addShortcutLabel})`}
+              disabled={
+                !canCreateProjectInEnvironment(browseEnvironment?.connection.phase) ||
+                relativePathNeedsActiveProject ||
+                (isCloneDestinationStep && isRemoteProjectPending)
+              }
+              onMouseDown={(event) => {
+                event.preventDefault();
+              }}
+              onClick={() => {
+                if (relativePathNeedsActiveProject) {
+                  return;
+                }
+                if (isCloneDestinationStep) {
+                  void submitAddProjectCloneFlow(resolvedAddProjectPath);
+                } else {
+                  void handleAddProject(resolvedAddProjectPath);
+                }
+              }}
+            />
+          }
+        >
+          <span>
+            {isCloneDestinationStep && isRemoteProjectPending ? "Cloning" : submitActionLabel}
+          </span>
+          <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
+            <Kbd>{hasHighlightedBrowseItem ? `${submitModifierLabel} Enter` : "Enter"}</Kbd>
+          </KbdGroup>
+        </TooltipTrigger>
+        <TooltipPopup side="top">
+          {submitActionLabel} ({addShortcutLabel})
+        </TooltipPopup>
+      </Tooltip>
+    ) : null;
+
+  const footerActionLabel =
+    addProjectCloneFlow?.step === "repository"
+      ? (remoteProjectButtonLabel ?? "Continue")
+      : !canSubmitBrowsePath || hasHighlightedBrowseItem
+        ? "Select"
+        : undefined;
+
+  const footerTrailing = canOpenProjectFromFileManager ? (
+    <Button
+      variant="ghost"
+      size="xs"
+      className="h-auto px-2 text-muted-foreground text-xs hover:bg-transparent hover:text-foreground"
+      disabled={isPickingProjectFolder}
+      onClick={() => {
+        void handleOpenProjectFromFileManager();
+      }}
+    >
+      {`Open in ${fileManagerName}`}
+    </Button>
+  ) : null;
+
   return (
-    <CommandDialogPopup
+    <CommandPaletteContent
+      key={`${viewStack.length}-${browseGeneration}-${isBrowsing}-${addProjectCloneFlow?.step ?? "none"}`}
       aria-label="Command palette"
-      className="overflow-hidden p-0"
-      data-command-palette="true"
-      data-testid="command-palette"
-      finalFocus={() => {
-        composerHandleRef?.current?.focusAtEnd();
-        return false;
+      autoHighlight={isBrowsing || isRemoteProjectCloneFlow ? false : "always"}
+      footerActionLabel={footerActionLabel}
+      footerTrailing={footerTrailing}
+      inputAccessory={inputAccessory}
+      inputProps={{
+        className:
+          addProjectCloneFlow?.step === "repository"
+            ? "pe-32"
+            : isBrowsing
+              ? willCreateProjectPath
+                ? "pe-36"
+                : "pe-16"
+              : undefined,
+        placeholder: inputPlaceholder,
+        wrapperClassName: isSubmenu
+          ? "[&_[data-slot=autocomplete-start-addon]]:pointer-events-auto"
+          : undefined,
+        ...(isSubmenu
+          ? {
+              startAddon: (
+                <button
+                  type="button"
+                  className="flex cursor-pointer items-center"
+                  aria-label="Back"
+                  onClick={popView}
+                >
+                  <ArrowLeftIcon />
+                </button>
+              ),
+            }
+          : isBrowsing
+            ? { startAddon: <FolderPlusIcon /> }
+            : {}),
+        onKeyDown: handleKeyDown,
       }}
-      onBackdropPointerDown={() => {
-        setOpen(false);
+      mode="none"
+      onItemHighlighted={(value) => {
+        setHighlightedItemValue(typeof value === "string" ? value : null);
       }}
+      onValueChange={handleQueryChange}
+      panelClassName="max-h-[min(28rem,70vh)]"
+      showBackHint={isSubmenu}
+      value={query}
     >
-      <Command
-        key={`${viewStack.length}-${browseGeneration}-${isBrowsing}-${addProjectCloneFlow?.step ?? "none"}`}
-        aria-label="Command palette"
-        autoHighlight={isBrowsing || isRemoteProjectCloneFlow ? false : "always"}
-        mode="none"
-        onItemHighlighted={(value) => {
-          setHighlightedItemValue(typeof value === "string" ? value : null);
-        }}
-        onValueChange={handleQueryChange}
-        value={query}
-      >
-        <div className="relative">
-          <CommandInput
-            className={
-              addProjectCloneFlow?.step === "repository"
-                ? "pe-32"
-                : isBrowsing
-                  ? willCreateProjectPath
-                    ? "pe-36"
-                    : "pe-16"
-                  : undefined
-            }
-            placeholder={inputPlaceholder}
-            wrapperClassName={
-              isSubmenu ? "[&_[data-slot=autocomplete-start-addon]]:pointer-events-auto" : undefined
+      {remoteProjectContext ? (
+        <div className="p-2 pb-0">
+          <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">Repository</div>
+          <div className="flex min-h-8 items-center gap-2 rounded-sm px-2 py-1.5">
+            {remoteProjectContext.icon}
+            <span className="flex min-w-0 flex-1 flex-col">
+              <span className="truncate text-foreground text-sm">{remoteProjectContext.title}</span>
+              <span className="truncate text-muted-foreground/85 text-xs">
+                {remoteProjectContext.description}
+              </span>
+            </span>
+          </div>
+        </div>
+      ) : null}
+      <CommandPaletteResults
+        groups={displayedGroups}
+        highlightedItemValue={highlightedItemValue}
+        isActionsOnly={isActionsOnly}
+        keybindings={keybindings}
+        onExecuteItem={executeItem}
+        {...(addProjectCloneFlow?.step === "repository"
+          ? {
+              emptyStateMessage:
+                addProjectCloneFlow.source === "url"
+                  ? "Enter a Git clone URL and press Enter to continue."
+                  : "Enter a repository path and press Enter to look it up.",
             }
-            {...(isSubmenu
-              ? {
-                  startAddon: (
-                    <button
-                      type="button"
-                      className="flex cursor-pointer items-center"
-                      aria-label="Back"
-                      onClick={popView}
-                    >
-                      <ArrowLeftIcon />
-                    </button>
-                  ),
-                }
-              : isBrowsing && !isSubmenu
+          : addProjectCloneFlow?.step === "confirm"
+            ? { emptyStateMessage: "Choose a destination path and press Enter to clone." }
+            : relativePathNeedsActiveProject
+              ? { emptyStateMessage: "Relative paths require an active project." }
+              : willCreateProjectPath
                 ? {
-                    startAddon: <FolderPlusIcon />,
+                    emptyStateMessage: "Press Enter to create this folder and add it as a project.",
                   }
-                : {})}
-            onKeyDown={handleKeyDown}
-          />
-          {addProjectCloneFlow?.step === "repository" ? (
-            <Tooltip>
-              <TooltipTrigger
-                render={
-                  <Button
-                    variant="outline"
-                    size="xs"
-                    tabIndex={-1}
-                    className="absolute inset-e-2.5 top-1/2 gap-1.5 pe-1 ps-2 -translate-y-1/2"
-                    aria-label={`${remoteProjectButtonLabel ?? "Continue"} (Enter)`}
-                    disabled={!canSubmitRemoteProjectFlow}
-                    onMouseDown={(event) => {
-                      event.preventDefault();
-                    }}
-                    onClick={() => {
-                      void submitAddProjectCloneFlow();
-                    }}
-                  />
-                }
-              >
-                <span>{isRemoteProjectPending ? "Working" : remoteProjectButtonLabel}</span>
-                <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
-                  <Kbd>Enter</Kbd>
-                </KbdGroup>
-              </TooltipTrigger>
-              <TooltipPopup side="top">
-                {remoteProjectButtonLabel ?? "Continue"} (Enter)
-              </TooltipPopup>
-            </Tooltip>
-          ) : isBrowsing ? (
-            <Tooltip>
-              <TooltipTrigger
-                render={
-                  <Button
-                    variant="outline"
-                    size="xs"
-                    tabIndex={-1}
-                    className={cn(
-                      "absolute inset-e-2.5 top-1/2 pe-1 ps-2 -translate-y-1/2",
-                      hasHighlightedBrowseItem ? "gap-1" : "gap-1.5",
-                    )}
-                    aria-label={`${submitActionLabel} (${addShortcutLabel})`}
-                    disabled={
-                      !canCreateProjectInEnvironment(browseEnvironment?.connection.phase) ||
-                      relativePathNeedsActiveProject ||
-                      (isCloneDestinationStep && isRemoteProjectPending)
-                    }
-                    onMouseDown={(event) => {
-                      event.preventDefault();
-                    }}
-                    onClick={() => {
-                      if (relativePathNeedsActiveProject) {
-                        return;
-                      }
-                      if (isCloneDestinationStep) {
-                        void submitAddProjectCloneFlow(resolvedAddProjectPath);
-                      } else {
-                        void handleAddProject(resolvedAddProjectPath);
-                      }
-                    }}
-                  />
-                }
-              >
-                <span>
-                  {isCloneDestinationStep && isRemoteProjectPending ? "Cloning" : submitActionLabel}
-                </span>
-                <KbdGroup className="pointer-events-none -me-0.5 items-center gap-1">
-                  <Kbd>{hasHighlightedBrowseItem ? `${submitModifierLabel} Enter` : "Enter"}</Kbd>
-                </KbdGroup>
-              </TooltipTrigger>
-              <TooltipPopup side="top">
-                {submitActionLabel} ({addShortcutLabel})
-              </TooltipPopup>
-            </Tooltip>
-          ) : null}
-        </div>
-        <CommandPanel className="max-h-[min(28rem,70vh)]">
-          {remoteProjectContext ? (
-            <div className="p-2 pb-0">
-              <div className="px-2 py-1.5 font-medium text-muted-foreground text-xs">
-                Repository
-              </div>
-              <div className="flex min-h-8 items-center gap-2 rounded-sm px-2 py-1.5">
-                {remoteProjectContext.icon}
-                <span className="flex min-w-0 flex-1 flex-col">
-                  <span className="truncate text-foreground text-sm">
-                    {remoteProjectContext.title}
-                  </span>
-                  <span className="truncate text-muted-foreground/85 text-xs">
-                    {remoteProjectContext.description}
-                  </span>
-                </span>
-              </div>
-            </div>
-          ) : null}
-          <CommandPaletteResults
-            groups={displayedGroups}
-            highlightedItemValue={highlightedItemValue}
-            isActionsOnly={isActionsOnly}
-            keybindings={keybindings}
-            onExecuteItem={executeItem}
-            {...(addProjectCloneFlow?.step === "repository"
-              ? {
-                  emptyStateMessage:
-                    addProjectCloneFlow.source === "url"
-                      ? "Enter a Git clone URL and press Enter to continue."
-                      : "Enter a repository path and press Enter to look it up.",
-                }
-              : addProjectCloneFlow?.step === "confirm"
-                ? { emptyStateMessage: "Choose a destination path and press Enter to clone." }
-                : relativePathNeedsActiveProject
-                  ? { emptyStateMessage: "Relative paths require an active project." }
-                  : willCreateProjectPath
-                    ? {
-                        emptyStateMessage:
-                          "Press Enter to create this folder and add it as a project.",
-                      }
-                    : threadSearch.isPending
-                      ? { emptyStateMessage: "Searching thread messages…" }
-                      : {})}
-          />
-        </CommandPanel>
-        <CommandFooter className="gap-3 max-sm:flex-col max-sm:items-start">
-          <div className="flex items-center gap-3">
-            <KbdGroup className="items-center gap-1.5">
-              <Kbd>
-                <ArrowUpIcon />
-              </Kbd>
-              <Kbd>
-                <ArrowDownIcon />
-              </Kbd>
-              <span>Navigate</span>
-            </KbdGroup>
-            {addProjectCloneFlow?.step === "repository" ? (
-              <KbdGroup className="items-center gap-1.5">
-                <Kbd>Enter</Kbd>
-                <span>{remoteProjectButtonLabel ?? "Continue"}</span>
-              </KbdGroup>
-            ) : !canSubmitBrowsePath || hasHighlightedBrowseItem ? (
-              <KbdGroup className="items-center gap-1.5">
-                <Kbd>Enter</Kbd>
-                <span>Select</span>
-              </KbdGroup>
-            ) : null}
-            {isSubmenu ? (
-              <KbdGroup className="items-center gap-1.5">
-                <Kbd>Backspace</Kbd>
-                <span>Back</span>
-              </KbdGroup>
-            ) : null}
-            <KbdGroup className="items-center gap-1.5">
-              <Kbd>Esc</Kbd>
-              <span>Close</span>
-            </KbdGroup>
-          </div>
-          {canOpenProjectFromFileManager ? (
-            <Button
-              variant="ghost"
-              size="xs"
-              className="h-auto px-2 text-muted-foreground text-xs hover:bg-transparent hover:text-foreground"
-              disabled={isPickingProjectFolder}
-              onClick={() => {
-                void handleOpenProjectFromFileManager();
-              }}
-            >
-              {`Open in ${fileManagerName}`}
-            </Button>
-          ) : null}
-        </CommandFooter>
-      </Command>
-    </CommandDialogPopup>
+                : threadSearch.isPending
+                  ? { emptyStateMessage: "Searching thread messages…" }
+                  : {})}
+      />
+    </CommandPaletteContent>
   );
 }
diff --git a/apps/web/src/components/CommandPaletteContent.tsx b/apps/web/src/components/CommandPaletteContent.tsx
new file mode 100644
index 00000000000..af3c1b67170
--- /dev/null
+++ b/apps/web/src/components/CommandPaletteContent.tsx
@@ -0,0 +1,77 @@
+import { ArrowDownIcon, ArrowUpIcon } from "lucide-react";
+import type { ComponentProps, ReactNode } from "react";
+
+import { Command, CommandFooter, CommandInput, CommandPanel } from "./ui/command";
+import { Kbd, KbdGroup } from "./ui/kbd";
+
+type CommandPaletteContentProps = Omit<ComponentProps<typeof Command>, "children"> & {
+  readonly children: ReactNode;
+  readonly escapeLabel?: ReactNode;
+  readonly footerActionLabel?: ReactNode;
+  readonly footerTrailing?: ReactNode;
+  readonly inputAccessory?: ReactNode;
+  readonly inputProps: ComponentProps<typeof CommandInput>;
+  readonly panelClassName?: string;
+  readonly showBackHint?: boolean;
+  readonly testId?: string;
+};
+
+/**
+ * Shared command palette chrome. Palette modes provide their query behavior,
+ * results, and optional input accessory while retaining one input, panel, and
+ * keyboard-hint gutter.
+ */
+export function CommandPaletteContent({
+  children,
+  escapeLabel = "Close",
+  footerActionLabel,
+  footerTrailing,
+  inputAccessory,
+  inputProps,
+  panelClassName,
+  showBackHint,
+  testId,
+  ...commandProps
+}: CommandPaletteContentProps) {
+  return (
+    <div className="contents" data-testid={testId}>
+      <Command {...commandProps}>
+        <div className="relative">
+          <CommandInput {...inputProps} />
+          {inputAccessory}
+        </div>
+        <CommandPanel className={panelClassName}>{children}</CommandPanel>
+        <CommandFooter className="gap-3 max-sm:flex-col max-sm:items-start">
+          <div className="flex items-center gap-3">
+            <KbdGroup className="items-center gap-1.5">
+              <Kbd>
+                <ArrowUpIcon />
+              </Kbd>
+              <Kbd>
+                <ArrowDownIcon />
+              </Kbd>
+              <span>Navigate</span>
+            </KbdGroup>
+            {footerActionLabel !== undefined ? (
+              <KbdGroup className="items-center gap-1.5">
+                <Kbd>Enter</Kbd>
+                <span>{footerActionLabel}</span>
+              </KbdGroup>
+            ) : null}
+            {showBackHint ? (
+              <KbdGroup className="items-center gap-1.5">
+                <Kbd>Backspace</Kbd>
+                <span>Back</span>
+              </KbdGroup>
+            ) : null}
+            <KbdGroup className="items-center gap-1.5">
+              <Kbd>Esc</Kbd>
+              <span>{escapeLabel}</span>
+            </KbdGroup>
+          </div>
+          {footerTrailing}
+        </CommandFooter>
+      </Command>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/ProjectFavicon.test.tsx b/apps/web/src/components/ProjectFavicon.test.tsx
new file mode 100644
index 00000000000..c2fac8beb7e
--- /dev/null
+++ b/apps/web/src/components/ProjectFavicon.test.tsx
@@ -0,0 +1,128 @@
+import type { ComponentType, Dispatch, ReactElement, SetStateAction } from "react";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import type { EnvironmentId } from "@t3tools/contracts";
+
+const testState = vi.hoisted(() => ({
+  faviconUrl: "https://environment.test/api/assets/token-a/v1-20-favicon.svg",
+}));
+
+const hooks = vi.hoisted(() => {
+  let cursor = 0;
+  let slots: unknown[] = [];
+  const nextIndex = () => cursor++;
+
+  return {
+    beginRender() {
+      cursor = 0;
+    },
+    reset() {
+      cursor = 0;
+      slots = [];
+    },
+    useMemoCache(size: number): unknown[] {
+      const index = nextIndex();
+      if (!slots[index]) {
+        slots[index] = Array.from({ length: size }, () => Symbol.for("react.memo_cache_sentinel"));
+      }
+      return slots[index] as unknown[];
+    },
+    useState<T>(initialValue: T | (() => T)): [T, Dispatch<SetStateAction<T>>] {
+      const index = nextIndex();
+      if (index >= slots.length) {
+        slots[index] =
+          typeof initialValue === "function" ? (initialValue as () => T)() : initialValue;
+      }
+      const setValue: Dispatch<SetStateAction<T>> = (nextValue) => {
+        const previous = slots[index] as T;
+        slots[index] =
+          typeof nextValue === "function" ? (nextValue as (value: T) => T)(previous) : nextValue;
+      };
+      return [slots[index] as T, setValue];
+    },
+  };
+});
+
+vi.mock("react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react")>();
+  return {
+    ...actual,
+    useState: hooks.useState,
+  };
+});
+
+vi.mock("react/compiler-runtime", () => ({ c: hooks.useMemoCache }));
+vi.mock("../assets/assetUrls", () => ({
+  useAssetUrl: () => testState.faviconUrl,
+}));
+
+import { ProjectFavicon } from "./ProjectFavicon";
+
+type ProjectFaviconImageProps = {
+  readonly cacheKey: string;
+  readonly src: string;
+  readonly className?: string | undefined;
+  readonly fallbackIcon: ComponentType<{ className?: string }>;
+};
+
+type ImageElement = ReactElement<{
+  readonly src: string;
+  readonly onLoad?: () => void;
+  readonly onError?: () => void;
+}>;
+
+type ProjectFaviconImageElement = ReactElement<{
+  readonly children: [ReactElement | null, ImageElement | null, ImageElement | null];
+}>;
+
+function resolveImageComponent(): {
+  readonly Component: (props: ProjectFaviconImageProps) => ProjectFaviconImageElement;
+  readonly props: ProjectFaviconImageProps;
+} {
+  hooks.beginRender();
+  const element = ProjectFavicon({
+    environmentId: "environment-test" as EnvironmentId,
+    cwd: "/workspace-test",
+  }) as ReactElement<ProjectFaviconImageProps>;
+  hooks.reset();
+
+  return {
+    Component: element.type as (props: ProjectFaviconImageProps) => ProjectFaviconImageElement,
+    props: element.props,
+  };
+}
+
+function renderImage(
+  Component: (props: ProjectFaviconImageProps) => ProjectFaviconImageElement,
+  props: ProjectFaviconImageProps,
+): ProjectFaviconImageElement {
+  hooks.beginRender();
+  return Component(props);
+}
+
+describe("ProjectFavicon", () => {
+  beforeEach(() => {
+    hooks.reset();
+  });
+
+  it("falls back when the displayed favicon fails without discarding a valid older image early", () => {
+    const { Component, props } = resolveImageComponent();
+    const initialLoadingImage = renderImage(Component, props).props.children[2];
+    initialLoadingImage?.props.onLoad?.();
+
+    const refreshedProps = {
+      ...props,
+      src: "https://environment.test/api/assets/token-b/v1-20-favicon.svg",
+    };
+    const refreshing = renderImage(Component, refreshedProps).props.children;
+    expect(refreshing[1]?.props.src).toBe(props.src);
+    refreshing[2]?.props.onError?.();
+
+    const afterRefreshError = renderImage(Component, refreshedProps).props.children;
+    expect(afterRefreshError[1]?.props.src).toBe(props.src);
+    afterRefreshError[1]?.props.onError?.();
+
+    const afterDisplayedError = renderImage(Component, refreshedProps).props.children;
+    expect(afterDisplayedError[0]).not.toBeNull();
+    expect(afterDisplayedError[1]).toBeNull();
+  });
+});
diff --git a/apps/web/src/components/ProjectFavicon.tsx b/apps/web/src/components/ProjectFavicon.tsx
index 201241731fa..1df19a64075 100644
--- a/apps/web/src/components/ProjectFavicon.tsx
+++ b/apps/web/src/components/ProjectFavicon.tsx
@@ -1,12 +1,15 @@
 import type { EnvironmentId } from "@t3tools/contracts";
-import { isProjectFaviconFallbackUrl } from "@t3tools/shared/projectFavicon";
+import {
+  getProjectFaviconCacheKey,
+  isProjectFaviconFallbackUrl,
+} from "@t3tools/shared/projectFavicon";
 import { FolderIcon } from "lucide-react";
 import type { ComponentType } from "react";
 import { useState } from "react";
 import { useAssetUrl } from "../assets/assetUrls";
 import { cn } from "~/lib/utils";
 
-const loadedProjectFaviconSrcs = new Set<string>();
+const loadedProjectFaviconSrcs = new Map<string, string>();
 
 export function ProjectFavicon(input: {
   environmentId: EnvironmentId;
@@ -24,9 +27,12 @@ export function ProjectFavicon(input: {
     return <ProjectFaviconFallback className={input.className} icon={FallbackIcon} />;
   }
 
+  const cacheKey = getProjectFaviconCacheKey(input.environmentId, input.cwd, src);
+
   return (
     <ProjectFaviconImage
-      key={src}
+      key={cacheKey}
+      cacheKey={cacheKey}
       src={src}
       className={input.className}
       fallbackIcon={FallbackIcon}
@@ -45,37 +51,52 @@ function ProjectFaviconFallback({
 }
 
 function ProjectFaviconImage({
+  cacheKey,
   src,
   className,
   fallbackIcon: FallbackIcon,
 }: {
+  readonly cacheKey: string;
   readonly src: string;
   readonly className?: string | undefined;
   readonly fallbackIcon: ComponentType<{ className?: string }>;
 }) {
-  const [status, setStatus] = useState<"loading" | "loaded" | "error">(() =>
-    loadedProjectFaviconSrcs.has(src) ? "loaded" : "loading",
+  const [displayedSrc, setDisplayedSrc] = useState<string | null>(
+    () => loadedProjectFaviconSrcs.get(cacheKey) ?? null,
   );
+  const isLoading = displayedSrc !== src;
+  const handleLoadError = (failedSrc: string) => {
+    if (loadedProjectFaviconSrcs.get(cacheKey) === failedSrc) {
+      loadedProjectFaviconSrcs.delete(cacheKey);
+    }
+    setDisplayedSrc((currentSrc) => (currentSrc === failedSrc ? null : currentSrc));
+  };
 
   return (
     <>
-      {status !== "loaded" ? (
+      {displayedSrc === null ? (
         <ProjectFaviconFallback className={className} icon={FallbackIcon} />
       ) : null}
-      <img
-        src={src}
-        alt=""
-        className={cn(
-          "size-3.5 shrink-0 rounded-sm object-contain",
-          status !== "loaded" && "hidden",
-          className,
-        )}
-        onLoad={() => {
-          loadedProjectFaviconSrcs.add(src);
-          setStatus("loaded");
-        }}
-        onError={() => setStatus("error")}
-      />
+      {displayedSrc ? (
+        <img
+          src={displayedSrc}
+          alt=""
+          className={cn("size-3.5 shrink-0 rounded-sm object-contain", className)}
+          onError={() => handleLoadError(displayedSrc)}
+        />
+      ) : null}
+      {isLoading ? (
+        <img
+          src={src}
+          alt=""
+          className="hidden"
+          onLoad={() => {
+            loadedProjectFaviconSrcs.set(cacheKey, src);
+            setDisplayedSrc(src);
+          }}
+          onError={() => handleLoadError(src)}
+        />
+      ) : null}
     </>
   );
 }
diff --git a/apps/web/src/components/ProjectScriptsControl.test.tsx b/apps/web/src/components/ProjectScriptsControl.test.tsx
new file mode 100644
index 00000000000..d9f3e7e69f0
--- /dev/null
+++ b/apps/web/src/components/ProjectScriptsControl.test.tsx
@@ -0,0 +1,65 @@
+import type { ProjectScript, ResolvedKeybindingsConfig } from "@t3tools/contracts";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vite-plus/test";
+
+import ProjectScriptsControl from "./ProjectScriptsControl";
+
+const EMPTY_KEYBINDINGS: ResolvedKeybindingsConfig = [];
+const PRIMARY_SCRIPT: ProjectScript = {
+  id: "dev",
+  name: "Dev",
+  command: "vp dev",
+  icon: "play",
+  runOnWorktreeCreate: false,
+};
+
+function renderControl(scripts: ReadonlyArray<ProjectScript>) {
+  return renderToStaticMarkup(
+    <ProjectScriptsControl
+      scripts={scripts}
+      keybindings={EMPTY_KEYBINDINGS}
+      onRunScript={() => {}}
+      onAddScript={async () => undefined as never}
+      onUpdateScript={async () => undefined as never}
+      onDeleteScript={async () => undefined as never}
+    />,
+  );
+}
+
+function buttonTag(html: string, ariaLabel: string) {
+  return html.match(new RegExp(`<button[^>]*aria-label="${ariaLabel}"[^>]*>`))?.[0];
+}
+
+function expectResponsiveXsControl(markup: string | undefined) {
+  expect(markup).toBeDefined();
+  expect(markup).toContain("h-7");
+  expect(markup).toContain("gap-1");
+  expect(markup).toContain("text-sm");
+  expect(markup).toContain("sm:h-6");
+  expect(markup).toContain("sm:text-xs");
+  expect(markup).toContain("w-7");
+  expect(markup).toContain("px-0");
+  expect(markup).toContain("sm:w-6");
+  expect(markup).toContain("@3xl/header-actions:w-auto!");
+  expect(markup).toContain("@3xl/header-actions:px-[calc(--spacing(2)-1px)]");
+}
+
+describe("ProjectScriptsControl compact controls", () => {
+  it("keeps the primary Run control compact and expands it with its label", () => {
+    const html = renderControl([PRIMARY_SCRIPT]);
+
+    expectResponsiveXsControl(buttonTag(html, "Run Dev"));
+    expect(html).toContain(
+      'class="sr-only @3xl/header-actions:not-sr-only @3xl/header-actions:ml-0.5"',
+    );
+  });
+
+  it("keeps the standalone Add control compact and expands it with its label", () => {
+    const html = renderControl([]);
+
+    expectResponsiveXsControl(buttonTag(html, "Add action"));
+    expect(html).toContain(
+      'class="sr-only @3xl/header-actions:not-sr-only @3xl/header-actions:ml-0.5"',
+    );
+  });
+});
diff --git a/apps/web/src/components/ProjectScriptsControl.tsx b/apps/web/src/components/ProjectScriptsControl.tsx
index e31404371bc..a4f535c94f0 100644
--- a/apps/web/src/components/ProjectScriptsControl.tsx
+++ b/apps/web/src/components/ProjectScriptsControl.tsx
@@ -347,6 +347,7 @@ export default function ProjectScriptsControl({
                 <Button
                   size="xs"
                   variant="outline"
+                  className="w-7 px-0 sm:w-6 @3xl/header-actions:w-auto! @3xl/header-actions:px-[calc(--spacing(2)-1px)]"
                   aria-label={`Run ${primaryScript.name}`}
                   onClick={() => onRunScript(primaryScript)}
                 />
@@ -451,7 +452,13 @@ export default function ProjectScriptsControl({
         <Tooltip>
           <TooltipTrigger
             render={
-              <Button size="xs" variant="outline" aria-label="Add action" onClick={openAddDialog} />
+              <Button
+                size="xs"
+                variant="outline"
+                className="w-7 px-0 sm:w-6 @3xl/header-actions:w-auto! @3xl/header-actions:px-[calc(--spacing(2)-1px)]"
+                aria-label="Add action"
+                onClick={openAddDialog}
+              />
             }
           >
             <PlusIcon className="size-3.5" />
diff --git a/apps/web/src/components/RenderErrorBoundary.tsx b/apps/web/src/components/RenderErrorBoundary.tsx
new file mode 100644
index 00000000000..29f7d612d94
--- /dev/null
+++ b/apps/web/src/components/RenderErrorBoundary.tsx
@@ -0,0 +1,16 @@
+import { Component, type ReactNode } from "react";
+
+export class RenderErrorBoundary extends Component<
+  { readonly children: ReactNode; readonly fallback: ReactNode },
+  { readonly failed: boolean }
+> {
+  override state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  override render() {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+}
diff --git a/apps/web/src/components/ServerUpdateAction.test.tsx b/apps/web/src/components/ServerUpdateAction.test.tsx
index 17e44b8bae6..4d5669a0a8f 100644
--- a/apps/web/src/components/ServerUpdateAction.test.tsx
+++ b/apps/web/src/components/ServerUpdateAction.test.tsx
@@ -101,11 +101,10 @@ describe("ServerUpdateAction", () => {
 });
 
 describe("ServerUpdateProgress", () => {
-  it("renders the chosen horizontal step rail without an animated spinner", () => {
+  it("renders the monochrome step rail with only the active step highlighted", () => {
     const markup = renderToStaticMarkup(
       <ServerUpdateProgress
         fromVersion="0.0.30"
-        serverLabel="bb-1"
         state={{
           status: "running",
           stage: "resuming",
@@ -119,8 +118,12 @@ describe("ServerUpdateProgress", () => {
     expect(markup).toContain("0.0.31");
     expect(markup).toContain("Download");
     expect(markup).toContain("Install");
-    expect(markup).toContain("Resume");
-    expect(markup).toContain("Waiting for bb-1 to accept commands.");
+    expect(markup).toContain("Resuming");
+    // The wait state is monochrome and calm: no success/warning colors, no
+    // status sentence, one duty-cycled pulse on the active step.
+    expect(markup).not.toContain("text-success");
+    expect(markup).not.toContain("text-primary");
+    expect(markup).toContain("animate-status-pulse");
     expect(markup).not.toContain("animate-spin");
   });
 
@@ -128,7 +131,6 @@ describe("ServerUpdateProgress", () => {
     const markup = renderToStaticMarkup(
       <ServerUpdateProgress
         fromVersion="0.0.30"
-        serverLabel="bb-1"
         state={{
           status: "failed",
           stage: "installing",
@@ -141,5 +143,6 @@ describe("ServerUpdateProgress", () => {
 
     expect(markup).toContain('role="alert"');
     expect(markup).toContain("The package could not be verified.");
+    expect(markup).not.toContain("animate-status-pulse");
   });
 });
diff --git a/apps/web/src/components/ServerUpdateAction.tsx b/apps/web/src/components/ServerUpdateAction.tsx
index 929ea2e56c7..f3b6c694fae 100644
--- a/apps/web/src/components/ServerUpdateAction.tsx
+++ b/apps/web/src/components/ServerUpdateAction.tsx
@@ -15,9 +15,9 @@ import { Button } from "./ui/button";
 import { toastManager } from "./ui/toast";
 
 const UPDATE_STEPS = [
-  { stage: "downloading", label: "Download" },
-  { stage: "installing", label: "Install" },
-  { stage: "resuming", label: "Resume" },
+  { stage: "downloading", label: "Download", activeLabel: "Downloading" },
+  { stage: "installing", label: "Install", activeLabel: "Installing" },
+  { stage: "resuming", label: "Resume", activeLabel: "Resuming" },
 ] as const;
 const pendingUpdateEnvironmentIds = new Set<EnvironmentId>();
 
@@ -25,37 +25,24 @@ function updateFailureMessage(error: unknown): string {
   return error instanceof Error ? error.message : "Server update failed.";
 }
 
-function updateStatusCopy(
-  state: Exclude<ServerUpdateState, { status: "idle" }>,
-  serverLabel: string,
-): string {
-  if (state.status === "failed") {
-    return state.message;
-  }
-  switch (state.stage) {
-    case "downloading":
-      return "Downloading the matching server version.";
-    case "installing":
-      return `Installing and verifying t3@${state.targetVersion}.`;
-    case "resuming":
-      return `Waiting for ${serverLabel} to accept commands.`;
-  }
-}
-
+/**
+ * Monochrome step rail for an in-flight server update. The update is a
+ * wait, not a warning: done steps recede to gray, the active step is the
+ * only bright element and pulses. Failure keeps the rail but surfaces the
+ * error below it.
+ */
 export function ServerUpdateProgress({
   fromVersion,
-  serverLabel,
   state,
 }: {
   readonly fromVersion: string;
-  readonly serverLabel: string;
   readonly state: Exclude<ServerUpdateState, { status: "idle" }>;
 }) {
   const currentIndex = UPDATE_STEPS.findIndex(({ stage }) => stage === state.stage);
 
   return (
     <div className="mt-1 min-w-0 space-y-2.5">
-      <p className="text-xs text-muted-foreground">
+      <p className="text-xs text-muted-foreground/70">
         {fromVersion} <span aria-hidden="true">→</span> {state.targetVersion}
       </p>
       <ol className="flex min-w-0 items-center" aria-label="Server update progress">
@@ -63,6 +50,7 @@ export function ServerUpdateProgress({
           const complete = index < currentIndex;
           const current = index === currentIndex;
           const failed = current && state.status === "failed";
+          const running = current && state.status === "running";
           return (
             <li
               key={step.stage}
@@ -70,36 +58,40 @@ export function ServerUpdateProgress({
                 "flex min-w-0 items-center text-xs font-medium",
                 index < UPDATE_STEPS.length - 1 ? "flex-1" : null,
                 complete
-                  ? "text-success"
+                  ? "text-muted-foreground"
                   : failed
                     ? "text-destructive"
-                    : current
-                      ? "text-primary"
-                      : "text-muted-foreground/60",
+                    : running
+                      ? "animate-status-pulse text-foreground"
+                      : "text-muted-foreground/50",
               )}
-              aria-current={current && state.status === "running" ? "step" : undefined}
+              aria-current={running ? "step" : undefined}
             >
-              <span
-                className={cn(
-                  "grid size-4 shrink-0 place-items-center rounded-full border",
-                  complete
-                    ? "border-success bg-success text-success-foreground"
-                    : failed
-                      ? "border-destructive bg-destructive text-destructive-foreground"
-                      : current
-                        ? "border-primary bg-primary text-primary-foreground"
-                        : "border-muted-foreground/35",
-                )}
-                aria-hidden="true"
-              >
-                {complete ? <CheckIcon className="size-3" strokeWidth={3} /> : null}
-              </span>
-              <span className="ml-1.5 truncate">{step.label}</span>
+              {complete ? (
+                <CheckIcon
+                  className="size-3.5 shrink-0 opacity-70"
+                  strokeWidth={2.5}
+                  aria-hidden="true"
+                />
+              ) : (
+                <span
+                  className={cn(
+                    "size-1.5 shrink-0 rounded-full",
+                    failed
+                      ? "bg-destructive"
+                      : running
+                        ? "bg-foreground"
+                        : "border border-muted-foreground/40",
+                  )}
+                  aria-hidden="true"
+                />
+              )}
+              <span className="ml-1.5 truncate">{running ? step.activeLabel : step.label}</span>
               {index < UPDATE_STEPS.length - 1 ? (
                 <span
                   className={cn(
                     "mx-2 h-px min-w-3 flex-1",
-                    complete ? "bg-success/60" : "bg-border",
+                    complete ? "bg-muted-foreground/40" : "bg-border",
                   )}
                   aria-hidden="true"
                 />
@@ -108,15 +100,11 @@ export function ServerUpdateProgress({
           );
         })}
       </ol>
-      <p
-        className={cn(
-          "text-xs",
-          state.status === "failed" ? "text-destructive" : "text-muted-foreground",
-        )}
-        role={state.status === "failed" ? "alert" : "status"}
-      >
-        {updateStatusCopy(state, serverLabel)}
-      </p>
+      {state.status === "failed" ? (
+        <p className="text-xs text-destructive" role="alert">
+          {state.message}
+        </p>
+      ) : null}
     </div>
   );
 }
diff --git a/apps/web/src/components/Sidebar.logic.test.ts b/apps/web/src/components/Sidebar.logic.test.ts
index 9c1e7c8c563..ac2716a196e 100644
--- a/apps/web/src/components/Sidebar.logic.test.ts
+++ b/apps/web/src/components/Sidebar.logic.test.ts
@@ -20,6 +20,7 @@ import {
   resolveSidebarV2Status,
   resolveThreadStatusPill,
   resolveWorkingStartedAt,
+  searchSidebarThreadsByTitle,
   formatWorkingDurationLabel,
   shouldNavigateAfterProjectRemoval,
   shouldClearThreadSelectionOnMouseDown,
@@ -691,6 +692,26 @@ describe("resolveSidebarV2Status", () => {
   });
 });
 
+describe("searchSidebarThreadsByTitle", () => {
+  const threads = [
+    { id: "thread-1", title: "Fix workspace search", project: "Alpha" },
+    { id: "thread-2", title: "Review providers", project: "Workspace" },
+    { id: "thread-3", title: "WORKTREE cleanup", project: "Beta" },
+  ];
+
+  it("matches thread titles case-insensitively and preserves their order", () => {
+    expect(searchSidebarThreadsByTitle(threads, "work")).toEqual([threads[0], threads[2]]);
+  });
+
+  it("does not match project metadata", () => {
+    expect(searchSidebarThreadsByTitle(threads, "workspace")).toEqual([threads[0]]);
+  });
+
+  it("returns no results for an empty query", () => {
+    expect(searchSidebarThreadsByTitle(threads, "   ")).toEqual([]);
+  });
+});
+
 describe("sortThreadsForSidebarV2", () => {
   const sortable = (input: { id: string; createdAt: string }) => ({
     id: input.id,
diff --git a/apps/web/src/components/Sidebar.logic.ts b/apps/web/src/components/Sidebar.logic.ts
index d11e06c8406..7b8a0eff3ff 100644
--- a/apps/web/src/components/Sidebar.logic.ts
+++ b/apps/web/src/components/Sidebar.logic.ts
@@ -490,6 +490,20 @@ export function sortThreadsForSidebarV2<
   );
 }
 
+/**
+ * Search the already-ordered sidebar thread collection by title only.
+ * Keeping the input order means lifecycle ordering (active, snoozed, settled)
+ * remains stable while the user narrows the list.
+ */
+export function searchSidebarThreadsByTitle<T extends { readonly title: string }>(
+  threads: readonly T[],
+  query: string,
+): T[] {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (normalizedQuery.length === 0) return [];
+  return threads.filter((thread) => thread.title.toLowerCase().includes(normalizedQuery));
+}
+
 type SettledTimestampInput = Pick<
   SidebarThreadSummary,
   "settledAt" | "latestUserMessageAt" | "latestTurn" | "updatedAt"
diff --git a/apps/web/src/components/Sidebar.snooze.test.ts b/apps/web/src/components/Sidebar.snooze.test.ts
index 4a4518a2591..88c1d9ea52d 100644
--- a/apps/web/src/components/Sidebar.snooze.test.ts
+++ b/apps/web/src/components/Sidebar.snooze.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { resolveSnoozePresets, snoozeWakeDescription, snoozeWakeLabel } from "./Sidebar.snooze";
+import { resolveSnoozePresets, snoozeWakeDescription } from "./Sidebar.snooze";
 
 // Local-time constructor so preset math is timezone-stable in tests.
 function localDate(year: number, month: number, day: number, hour: number, minute = 0): Date {
@@ -64,21 +64,6 @@ describe("resolveSnoozePresets", () => {
   });
 });
 
-describe("snoozeWakeLabel", () => {
-  const now = localDate(2026, 4, 8, 10);
-
-  it("formats minutes, hours, and days, rounding up", () => {
-    expect(snoozeWakeLabel(new Date(now.getTime() + 30 * 60_000).toISOString(), now)).toBe("30m");
-    expect(snoozeWakeLabel(new Date(now.getTime() + 90 * 60_000).toISOString(), now)).toBe("2h");
-    expect(snoozeWakeLabel(new Date(now.getTime() + 26 * 3_600_000).toISOString(), now)).toBe("2d");
-  });
-
-  it("reports now for past and malformed wake times", () => {
-    expect(snoozeWakeLabel(new Date(now.getTime() - 1000).toISOString(), now)).toBe("now");
-    expect(snoozeWakeLabel("not-a-date", now)).toBe("now");
-  });
-});
-
 describe("snoozeWakeDescription", () => {
   const now = localDate(2026, 4, 8, 10);
 
diff --git a/apps/web/src/components/Sidebar.snooze.ts b/apps/web/src/components/Sidebar.snooze.ts
index dd56cec7290..adbc361a8ee 100644
--- a/apps/web/src/components/Sidebar.snooze.ts
+++ b/apps/web/src/components/Sidebar.snooze.ts
@@ -1,111 +1,13 @@
-/**
- * Snooze preset resolution for the sidebar snooze menu. Pure functions so
- * the preset math (evening/tomorrow/next-week boundaries) is unit-testable
- * without a DOM.
- *
- * Presets deliberately skew short: agent-thread rhythms are hours (a CI
- * run, a teammate review, the next work session), not days.
- */
+import { snoozeWakeLabel } from "@t3tools/client-runtime/state/thread-settled";
 import { parseTimestampDate } from "../timestampFormat";
 
-type SnoozePresetId = "hour" | "evening" | "tomorrow" | "next-week";
-
-export interface SnoozePreset {
-  readonly id: SnoozePresetId;
-  readonly label: string;
-  /** Menu-row time column. Complements the label instead of repeating it:
-      "Tomorrow" pairs with "9:00 AM", not "tomorrow 9:00 AM". */
-  readonly whenLabel: string;
-  /** ISO wake time. */
-  readonly snoozedUntil: string;
-}
-
-function timeOfDayLabel(date: Date): string {
-  return date.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
-}
-
-const EVENING_HOUR = 18;
-const MORNING_HOUR = 9;
-const HOUR_MS = 60 * 60 * 1_000;
-const DAY_MS = 24 * HOUR_MS;
-
-function atHour(base: Date, hour: number): Date {
-  const next = new Date(base);
-  next.setHours(hour, 0, 0, 0);
-  return next;
-}
-
-// Calendar-day advance instead of adding DAY_MS: fixed millisecond offsets
-// land on the wrong local day across DST transitions (a spring-forward day
-// is 23 hours, so 23:30 + 24h skips the whole next day).
-function addDays(base: Date, days: number): Date {
-  const next = new Date(base);
-  next.setDate(next.getDate() + days);
-  return next;
-}
+export {
+  resolveSnoozePresets,
+  type SnoozePreset,
+} from "@t3tools/client-runtime/state/thread-settled";
+export { snoozeWakeLabel };
 
-/**
- * Presets for "snooze until", computed against local time. "This evening"
- * only appears while it is still meaningfully before evening; after that
- * the list starts at "Tomorrow".
- */
-export function resolveSnoozePresets(now: Date): ReadonlyArray<SnoozePreset> {
-  const inAnHour = new Date(now.getTime() + HOUR_MS);
-  const presets: SnoozePreset[] = [
-    {
-      id: "hour",
-      label: "In 1 hour",
-      whenLabel: timeOfDayLabel(inAnHour),
-      snoozedUntil: inAnHour.toISOString(),
-    },
-  ];
-
-  const evening = atHour(now, EVENING_HOUR);
-  // Suppress the evening preset once it is within an hour (or past): it
-  // would duplicate "In 1 hour" or point at the past.
-  if (evening.getTime() - now.getTime() > HOUR_MS) {
-    presets.push({
-      id: "evening",
-      label: "This evening",
-      whenLabel: timeOfDayLabel(evening),
-      snoozedUntil: evening.toISOString(),
-    });
-  }
-
-  const tomorrow = atHour(addDays(now, 1), MORNING_HOUR);
-  presets.push({
-    id: "tomorrow",
-    label: "Tomorrow",
-    whenLabel: timeOfDayLabel(tomorrow),
-    snoozedUntil: tomorrow.toISOString(),
-  });
-
-  // Next Monday 9:00 (a week out when today is Monday).
-  const daysUntilMonday = (1 - now.getDay() + 7) % 7 || 7;
-  const nextWeek = atHour(addDays(now, daysUntilMonday), MORNING_HOUR);
-  presets.push({
-    id: "next-week",
-    label: "Next week",
-    whenLabel: `${nextWeek.toLocaleDateString(undefined, { weekday: "short" })} ${timeOfDayLabel(nextWeek)}`,
-    snoozedUntil: nextWeek.toISOString(),
-  });
-
-  return presets;
-}
-
-/**
- * Compact "wakes in" label for snoozed rows: "2h", "18h", "3d". Minutes
- * round up so a snooze never reads "0m" while still hidden.
- */
-export function snoozeWakeLabel(snoozedUntil: string, now: Date): string {
-  const wake = parseTimestampDate(snoozedUntil);
-  if (wake === null) return "now";
-  const remainingMs = wake.getTime() - now.getTime();
-  if (remainingMs <= 0) return "now";
-  if (remainingMs < HOUR_MS) return `${Math.max(1, Math.ceil(remainingMs / 60_000))}m`;
-  if (remainingMs < DAY_MS) return `${Math.ceil(remainingMs / HOUR_MS)}h`;
-  return `${Math.ceil(remainingMs / DAY_MS)}d`;
-}
+const DAY_MS = 24 * 60 * 60 * 1_000;
 
 /**
  * Human wake time for menus and toasts: "tomorrow 9:00", "Mon 9:00",
diff --git a/apps/web/src/components/Sidebar.tsx b/apps/web/src/components/Sidebar.tsx
index 98b5dcf84ed..cffab8bd577 100644
--- a/apps/web/src/components/Sidebar.tsx
+++ b/apps/web/src/components/Sidebar.tsx
@@ -133,6 +133,7 @@ import {
   shouldShowArm64IntelBuildWarning,
   shouldToastDesktopUpdateActionResult,
 } from "./desktopUpdate.logic";
+import { showDesktopUpdateDownloadedToast } from "./desktopUpdate.toast";
 import { Alert, AlertAction, AlertDescription, AlertTitle } from "./ui/alert";
 import { Button } from "./ui/button";
 import {
@@ -164,7 +165,6 @@ import {
   SidebarMenuSub,
   SidebarMenuSubButton,
   SidebarMenuSubItem,
-  SidebarSeparator,
   useSidebar,
 } from "./ui/sidebar";
 import { useThreadSelectionStore } from "../threadSelectionStore";
@@ -3509,11 +3509,7 @@ export default function Sidebar() {
         .downloadUpdate()
         .then((result) => {
           if (result.completed) {
-            toastManager.add({
-              type: "success",
-              title: "Update downloaded",
-              description: "Restart the app from the update button to install it.",
-            });
+            showDesktopUpdateDownloadedToast(bridge, result.state);
           }
           if (!shouldToastDesktopUpdateActionResult(result)) return;
           const actionError = getDesktopUpdateActionError(result);
@@ -3634,8 +3630,6 @@ export default function Sidebar() {
             attachProjectListAutoAnimateRef={attachProjectListAutoAnimateRef}
             projectsLength={projects.length}
           />
-
-          <SidebarSeparator />
           <SidebarChromeFooter />
         </>
       )}
diff --git a/apps/web/src/components/SidebarV2.tsx b/apps/web/src/components/SidebarV2.tsx
index e9d61b87363..c19a66f62ea 100644
--- a/apps/web/src/components/SidebarV2.tsx
+++ b/apps/web/src/components/SidebarV2.tsx
@@ -337,9 +337,9 @@ function SidebarV2ThreadTooltip({
       align="start"
       sideOffset={4}
       variant="glass"
-      className="max-w-80 text-left whitespace-normal"
+      className="max-w-80 text-left whitespace-normal [&_[data-slot=tooltip-viewport]]:p-0"
     >
-      <div className="flex min-w-0 max-w-80 flex-col gap-2 px-0.5 py-1.5">
+      <div className="flex min-w-0 max-w-80 flex-col gap-2 p-[var(--floating-content-inset)]">
         <div className="min-w-0 truncate text-xs leading-none font-medium text-foreground">
           {thread.title}
         </div>
@@ -3039,7 +3039,9 @@ export default function SidebarV2() {
                       }
                       snoozeWakeLabelText={
                         section === "snoozed" && thread.snoozedUntil != null
-                          ? snoozeWakeLabel(thread.snoozedUntil, new Date())
+                          ? snoozeWakeLabel(thread.snoozedUntil, {
+                              now: new Date().toISOString(),
+                            })
                           : null
                       }
                       // All sections: a woken thread can classify straight
diff --git a/apps/web/src/components/ThreadTerminalDrawer.test.ts b/apps/web/src/components/ThreadTerminalDrawer.test.ts
index 9f483af3c3b..e60d1d71678 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.test.ts
+++ b/apps/web/src/components/ThreadTerminalDrawer.test.ts
@@ -2,8 +2,10 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   resolveTerminalSelectionActionPosition,
+  shouldHandleTerminalExit,
   shouldHandleTerminalSelectionMouseUp,
   terminalSelectionActionDelayForClickCount,
+  terminalSelectionLineRange,
 } from "./ThreadTerminalDrawer";
 
 describe("resolveTerminalSelectionActionPosition", () => {
@@ -72,4 +74,19 @@ describe("resolveTerminalSelectionActionPosition", () => {
     expect(shouldHandleTerminalSelectionMouseUp(false, 0)).toBe(false);
     expect(shouldHandleTerminalSelectionMouseUp(true, 1)).toBe(false);
   });
+
+  it("uses Ghostty's physical screen range for visually wrapped selections", () => {
+    expect(
+      terminalSelectionLineRange({
+        start: { y: 4 },
+        end: { y: 6 },
+      }),
+    ).toEqual({ lineStart: 5, lineEnd: 7 });
+  });
+
+  it("handles an exit that lands while the terminal surface is still loading", () => {
+    expect(shouldHandleTerminalExit("exited", "running", false)).toBe(true);
+    expect(shouldHandleTerminalExit("exited", "exited", false)).toBe(false);
+    expect(shouldHandleTerminalExit("closed", "running", true)).toBe(false);
+  });
 });
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index b520826acce..da7db66aff2 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -1,9 +1,9 @@
 import { useAtomValue } from "@effect/atom-react";
-import { FitAddon } from "@xterm/addon-fit";
 import {
   isAtomCommandInterrupted,
   squashAtomCommandFailure,
 } from "@t3tools/client-runtime/state/runtime";
+import { type TerminalSessionState } from "@t3tools/client-runtime/state/terminal";
 import {
   Plus,
   SquareSplitHorizontal,
@@ -18,7 +18,6 @@ import {
   type ThreadId,
 } from "@t3tools/contracts";
 import { getTerminalLabel } from "@t3tools/shared/terminalLabels";
-import { Terminal, type ITheme } from "@xterm/xterm";
 import {
   type PointerEvent as ReactPointerEvent,
   type ReactNode,
@@ -35,17 +34,15 @@ import { writeTextToClipboard } from "~/hooks/useCopyToClipboard";
 import { cn } from "~/lib/utils";
 import { type TerminalContextSelection } from "~/lib/terminalContext";
 /* fork:begin geist-typography — see .fork/customizations.yaml#geist-typography */
-import { refitTerminalWhenFontsReady, resolveTerminalFontFamily } from "../custom/terminalFont";
+import { resolveTerminalFontFamily } from "../custom/terminalFont";
 /* fork:end geist-typography */
-import { useOpenInPreferredEditor } from "../editorPreferences";
 import {
-  collectWrappedTerminalLinkLine,
-  extractTerminalLinks,
-  isTerminalLinkActivation,
-  resolvePathLinkTarget,
-  resolveWrappedTerminalLinkRange,
-  wrappedTerminalLinkRangeIntersectsBufferLine,
-} from "../terminal-links";
+  GhosttyTerminalSurface,
+  type GhosttyTerminalSurfaceOptions,
+} from "~/terminal/ghostty/surface";
+import { type GhosttyColor, type GhosttyTheme } from "~/terminal/ghostty/core";
+import { useOpenInPreferredEditor } from "../editorPreferences";
+import { isTerminalLinkActivation, resolvePathLinkTarget } from "../terminal-links";
 import {
   isDiffToggleShortcut,
   isTerminalClearShortcut,
@@ -85,24 +82,34 @@ function clampDrawerHeight(height: number): number {
   return Math.min(Math.max(Math.round(safeHeight), MIN_DRAWER_HEIGHT), maxHeight);
 }
 
-function writeSystemMessage(terminal: Terminal, message: string): void {
+function writeSystemMessage(terminal: GhosttyTerminalSurface, message: string): void {
   terminal.write(`\r\n[terminal] ${message}\r\n`);
 }
 
-function writeTerminalBuffer(terminal: Terminal, buffer: string): void {
-  terminal.write("\u001bc");
-  if (buffer.length > 0) {
-    terminal.write(buffer);
-  }
+function writeTerminalBuffer(terminal: GhosttyTerminalSurface, buffer: string): void {
+  terminal.resetAndWrite(buffer);
 }
 
-function fitTerminalSafely(fitAddon: FitAddon): boolean {
-  try {
-    fitAddon.fit();
-    return true;
-  } catch {
-    return false;
-  }
+function parseTerminalColor(value: string, fallback: GhosttyColor): GhosttyColor {
+  if (typeof document === "undefined") return fallback;
+
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const context = canvas.getContext("2d", { willReadFrequently: true });
+  if (!context) return fallback;
+
+  context.clearRect(0, 0, 1, 1);
+  context.fillStyle = value;
+  context.fillRect(0, 0, 1, 1);
+  const [red, green, blue, alpha] = context.getImageData(0, 0, 1, 1).data;
+  if (alpha === 0) return fallback;
+
+  return {
+    r: red ?? fallback.r,
+    g: green ?? fallback.g,
+    b: blue ?? fallback.b,
+  };
 }
 
 function runtimeEnvSignature(runtimeEnv: Record<string, string> | undefined): string {
@@ -127,7 +134,7 @@ function normalizeComputedColor(value: string | null | undefined, fallback: stri
   return value ?? fallback;
 }
 
-function terminalThemeFromApp(mountElement?: HTMLElement | null): ITheme {
+function terminalThemeFromApp(mountElement?: HTMLElement | null): GhosttyTheme {
   const isDark = document.documentElement.classList.contains("dark");
   const fallbackBackground = isDark ? "rgb(14, 18, 24)" : "rgb(255, 255, 255)";
   const fallbackForeground = isDark ? "rgb(237, 241, 247)" : "rgb(28, 33, 41)";
@@ -146,86 +153,22 @@ function terminalThemeFromApp(mountElement?: HTMLElement | null): ITheme {
     normalizeComputedColor(bodyStyles.color, fallbackForeground),
   );
 
-  if (isDark) {
-    return {
+  return {
+    background: parseTerminalColor(
       background,
+      isDark ? { r: 14, g: 18, b: 24 } : { r: 255, g: 255, b: 255 },
+    ),
+    foreground: parseTerminalColor(
       foreground,
-      cursor: "rgb(180, 203, 255)",
-      selectionBackground: "rgba(180, 203, 255, 0.25)",
-      scrollbarSliderBackground: "rgba(255, 255, 255, 0.1)",
-      scrollbarSliderHoverBackground: "rgba(255, 255, 255, 0.18)",
-      scrollbarSliderActiveBackground: "rgba(255, 255, 255, 0.22)",
-      black: "rgb(24, 30, 38)",
-      red: "rgb(255, 122, 142)",
-      green: "rgb(134, 231, 149)",
-      yellow: "rgb(244, 205, 114)",
-      blue: "rgb(137, 190, 255)",
-      magenta: "rgb(208, 176, 255)",
-      cyan: "rgb(124, 232, 237)",
-      white: "rgb(210, 218, 230)",
-      brightBlack: "rgb(110, 120, 136)",
-      brightRed: "rgb(255, 168, 180)",
-      brightGreen: "rgb(176, 245, 186)",
-      brightYellow: "rgb(255, 224, 149)",
-      brightBlue: "rgb(174, 210, 255)",
-      brightMagenta: "rgb(229, 203, 255)",
-      brightCyan: "rgb(167, 244, 247)",
-      brightWhite: "rgb(244, 247, 252)",
-    };
-  }
-
-  return {
-    background,
-    foreground,
-    cursor: "rgb(38, 56, 78)",
-    selectionBackground: "rgba(37, 63, 99, 0.2)",
-    scrollbarSliderBackground: "rgba(0, 0, 0, 0.15)",
-    scrollbarSliderHoverBackground: "rgba(0, 0, 0, 0.25)",
-    scrollbarSliderActiveBackground: "rgba(0, 0, 0, 0.3)",
-    black: "rgb(44, 53, 66)",
-    red: "rgb(191, 70, 87)",
-    green: "rgb(60, 126, 86)",
-    yellow: "rgb(146, 112, 35)",
-    blue: "rgb(72, 102, 163)",
-    magenta: "rgb(132, 86, 149)",
-    cyan: "rgb(53, 127, 141)",
-    white: "rgb(210, 215, 223)",
-    brightBlack: "rgb(112, 123, 140)",
-    brightRed: "rgb(212, 95, 112)",
-    brightGreen: "rgb(85, 148, 111)",
-    brightYellow: "rgb(173, 133, 45)",
-    brightBlue: "rgb(91, 124, 194)",
-    brightMagenta: "rgb(153, 107, 172)",
-    brightCyan: "rgb(70, 149, 164)",
-    brightWhite: "rgb(236, 240, 246)",
+      isDark ? { r: 237, g: 241, b: 247 } : { r: 28, g: 33, b: 41 },
+    ),
+    cursor: isDark ? { r: 180, g: 203, b: 255 } : { r: 38, g: 56, b: 78 },
+    // Matches the xterm selection overlays this renderer replaced; the text
+    // color underneath is left unchanged for contrast in both themes.
+    selectionBackground: isDark ? "rgba(180, 203, 255, 0.25)" : "rgba(37, 63, 99, 0.2)",
   };
 }
 
-function getTerminalSelectionRect(mountElement: HTMLElement): DOMRect | null {
-  const selection = window.getSelection();
-  if (!selection || selection.rangeCount === 0 || selection.isCollapsed) {
-    return null;
-  }
-
-  const range = selection.getRangeAt(0);
-  const commonAncestor = range.commonAncestorContainer;
-  const selectionRoot =
-    commonAncestor instanceof Element ? commonAncestor : commonAncestor.parentElement;
-  if (!(selectionRoot instanceof Element) || !mountElement.contains(selectionRoot)) {
-    return null;
-  }
-
-  const rects = Array.from(range.getClientRects()).filter(
-    (rect) => rect.width > 0 || rect.height > 0,
-  );
-  if (rects.length > 0) {
-    return rects[rects.length - 1] ?? null;
-  }
-
-  const boundingRect = range.getBoundingClientRect();
-  return boundingRect.width > 0 || boundingRect.height > 0 ? boundingRect : null;
-}
-
 export function resolveTerminalSelectionActionPosition(options: {
   bounds: { left: number; top: number; width: number; height: number };
   selectionRect: { right: number; bottom: number } | null;
@@ -272,6 +215,27 @@ export function shouldHandleTerminalSelectionMouseUp(
   return selectionGestureActive && button === 0;
 }
 
+export function terminalSelectionLineRange(position: {
+  start: { y: number };
+  end: { y: number };
+}): { lineStart: number; lineEnd: number } {
+  const lineStart = position.start.y + 1;
+  return {
+    lineStart,
+    lineEnd: Math.max(lineStart, position.end.y + 1),
+  };
+}
+
+export function shouldHandleTerminalExit(
+  current: TerminalSessionState["status"],
+  synchronized: TerminalSessionState["status"],
+  alreadyHandled: boolean,
+): boolean {
+  return (
+    (current === "closed" || current === "exited") && current !== synchronized && !alreadyHandled
+  );
+}
+
 interface TerminalViewportProps {
   threadRef: ScopedThreadRef;
   threadId: ThreadId;
@@ -312,8 +276,7 @@ export function TerminalViewport({
   keybindings,
 }: TerminalViewportProps) {
   const containerRef = useRef<HTMLDivElement>(null);
-  const terminalRef = useRef<Terminal | null>(null);
-  const fitAddonRef = useRef<FitAddon | null>(null);
+  const terminalRef = useRef<GhosttyTerminalSurface | null>(null);
   const environmentId = threadRef.environmentId;
   const serverConfig = useAtomValue(serverEnvironment.configValueAtom(environmentId));
   const openInPreferredEditor = useOpenInPreferredEditor(
@@ -370,6 +333,24 @@ export function TerminalViewport({
   const terminalBuffer = terminalSession.buffer;
   const terminalError = terminalSession.error;
   const terminalStatus = terminalSession.status;
+  const synchronizedStatusRef = useRef<TerminalSessionState["status"]>("closed");
+  const synchronizeTerminalStatus = useEffectEvent(
+    (terminal: GhosttyTerminalSurface, status: TerminalSessionState["status"]) => {
+      const synchronized = synchronizedStatusRef.current;
+      if (status === "running") {
+        hasHandledExitRef.current = false;
+      } else if (shouldHandleTerminalExit(status, synchronized, hasHandledExitRef.current)) {
+        hasHandledExitRef.current = true;
+        writeSystemMessage(terminal, status === "closed" ? "Terminal closed" : "Process exited");
+        window.setTimeout(() => {
+          if (hasHandledExitRef.current) {
+            handleSessionExited();
+          }
+        }, 0);
+      }
+      synchronizedStatusRef.current = status;
+    },
+  );
   const terminalVersion = terminalSession.version;
   const previousSessionRef = useRef({
     buffer: terminalBuffer,
@@ -377,6 +358,13 @@ export function TerminalViewport({
     status: terminalStatus,
     version: terminalVersion,
   });
+  const latestSessionRef = useRef(previousSessionRef.current);
+  latestSessionRef.current = {
+    buffer: terminalBuffer,
+    error: terminalError,
+    status: terminalStatus,
+    version: terminalVersion,
+  };
 
   useEffect(() => {
     keybindingsRef.current = keybindings;
@@ -387,367 +375,359 @@ export function TerminalViewport({
     if (!mount) return;
 
     const localApi = readLocalApi();
-
-    const fitAddon = new FitAddon();
-    const terminal = new Terminal({
-      cursorBlink: true,
-      lineHeight: 1,
-      fontSize: 12,
-      scrollback: 5_000,
-      /* fork:begin geist-typography — see .fork/customizations.yaml#geist-typography */
-      fontFamily: resolveTerminalFontFamily(mount),
-      /* fork:end geist-typography */
-      theme: terminalThemeFromApp(mount),
-    });
-    terminal.loadAddon(fitAddon);
-    terminal.open(mount);
-    fitTerminalSafely(fitAddon);
-    /* fork:begin geist-typography — see .fork/customizations.yaml#geist-typography */
-    void refitTerminalWhenFontsReady({
-      terminal,
-      // Cleanup nulls the ref before terminal.dispose(), so a late resolve can
-      // never touch a disposed terminal.
-      isCurrent: () => terminalRef.current === terminal,
-      fit: () => fitTerminalSafely(fitAddon),
-      resize: resizeTerminal,
-    });
-    /* fork:end geist-typography */
-
-    terminalRef.current = terminal;
-    fitAddonRef.current = fitAddon;
-    previousSessionRef.current = {
-      buffer: "",
-      status: "closed",
-      error: null,
-      version: 0,
-    };
-
-    const clearSelectionAction = () => {
-      selectionActionRequestIdRef.current += 1;
-      if (selectionActionTimerRef.current !== null) {
-        window.clearTimeout(selectionActionTimerRef.current);
-        selectionActionTimerRef.current = null;
-      }
-    };
-
-    const readSelectionAction = (): {
-      position: { x: number; y: number };
-      clipboardText: string;
-      selection: TerminalContextSelection;
-    } | null => {
-      const activeTerminal = terminalRef.current;
-      const mountElement = containerRef.current;
-      if (!activeTerminal || !mountElement || !activeTerminal.hasSelection()) {
-        return null;
-      }
-      const selectionText = activeTerminal.getSelection();
-      const selectionPosition = activeTerminal.getSelectionPosition();
-      const normalizedText = selectionText.replace(/\r\n/g, "\n").replace(/^\n+|\n+$/g, "");
-      if (!selectionPosition || normalizedText.length === 0) {
+    let cancelled = false;
+    let teardown: (() => void) | null = null;
+    let setupTerminal: GhosttyTerminalSurface | null = null;
+    let setupCleanups: Array<() => void> = [];
+
+    const setup = async (): Promise<(() => void) | null> => {
+      const terminalOptions: GhosttyTerminalSurfaceOptions = {
+        theme: terminalThemeFromApp(mount),
+        /* fork:begin geist-typography — see .fork/customizations.yaml#geist-typography */
+        // The fork's cascade puts Geist Mono in --font-mono; the surface
+        // appends its own glyph fallbacks and re-measures the cell grid when
+        // the webfont lands, so no refit shim is needed here any more.
+        font: { family: resolveTerminalFontFamily(mount) },
+        /* fork:end geist-typography */
+        onData: (data) => handleData(data),
+        onResize: (cols, rows) => void resizeTerminal(cols, rows),
+        onSelectionChange: () => handleSelectionChange(),
+        onCopy: (text) => handleCopy(text),
+        beforeKey: (event) => handleBeforeKey(event),
+        onLinkActivate: (text, event) => handleLinkActivate(text, event),
+      };
+      const terminal = await GhosttyTerminalSurface.create(mount, terminalOptions);
+      if (cancelled) {
+        terminal.dispose();
         return null;
       }
-      const lineStart = selectionPosition.start.y + 1;
-      const lineCount = normalizedText.split("\n").length;
-      const lineEnd = Math.max(lineStart, lineStart + lineCount - 1);
-      const bounds = mountElement.getBoundingClientRect();
-      const selectionRect = getTerminalSelectionRect(mountElement);
-      const position = resolveTerminalSelectionActionPosition({
-        bounds,
-        selectionRect:
-          selectionRect === null
-            ? null
-            : { right: selectionRect.right, bottom: selectionRect.bottom },
-        pointer: selectionPointerRef.current,
-      });
-      return {
-        position,
-        clipboardText: selectionText,
-        selection: {
-          terminalId,
-          terminalLabel: readTerminalLabel(),
-          lineStart,
-          lineEnd,
-          text: normalizedText,
-        },
+      // The theme observer is not installed yet, so re-read the theme in case
+      // the app toggled light/dark while the WASM surface was loading.
+      terminal.setTheme(terminalThemeFromApp(mount));
+      setupTerminal = terminal;
+      terminalRef.current = terminal;
+      const latestSession = latestSessionRef.current;
+      previousSessionRef.current = latestSession;
+      if (latestSession.buffer.length > 0) terminal.resetAndWrite(latestSession.buffer);
+      if (latestSession.error !== null) writeSystemMessage(terminal, latestSession.error);
+      // Attaching to a session that already exited must still run exit handling
+      // once, so mount synchronization starts from the empty "closed" state.
+      // (A session that is "closed" at mount is indistinguishable from one that
+      // never started, so only "exited" triggers the message — as with xterm.)
+      synchronizedStatusRef.current = "closed";
+      synchronizeTerminalStatus(terminal, latestSession.status);
+      if (autoFocus) window.requestAnimationFrame(() => terminal.focus());
+
+      const clearSelectionAction = () => {
+        selectionActionRequestIdRef.current += 1;
+        if (selectionActionTimerRef.current !== null) {
+          window.clearTimeout(selectionActionTimerRef.current);
+          selectionActionTimerRef.current = null;
+        }
       };
-    };
+      setupCleanups.push(clearSelectionAction);
 
-    const showSelectionAction = async () => {
-      if (!localApi) {
-        clearSelectionAction();
-        return;
-      }
-      if (selectionActionMenuOpenRef.current) {
-        return;
-      }
-      const nextAction = readSelectionAction();
-      if (!nextAction) {
-        clearSelectionAction();
-        return;
-      }
-      const requestId = ++selectionActionRequestIdRef.current;
-      selectionActionMenuOpenRef.current = true;
-      const clicked = await localApi.contextMenu
-        .show(
-          [
-            { id: "add-to-chat", label: "Add to chat" },
-            { id: "copy", label: "Copy" },
-          ],
-          nextAction.position,
-        )
-        .finally(() => {
-          selectionActionMenuOpenRef.current = false;
+      const readSelectionAction = (): {
+        position: { x: number; y: number };
+        clipboardText: string;
+        selection: TerminalContextSelection;
+      } | null => {
+        const activeTerminal = terminalRef.current;
+        const mountElement = containerRef.current;
+        if (!activeTerminal || !mountElement || !activeTerminal.hasSelection()) {
+          return null;
+        }
+        const selectionText = activeTerminal.getSelection();
+        const selectionPosition = activeTerminal.getSelectionPosition();
+        const normalizedText = selectionText.replace(/\r\n/g, "\n").replace(/^\n+|\n+$/g, "");
+        if (!selectionPosition || normalizedText.length === 0) {
+          return null;
+        }
+        const { lineStart, lineEnd } = terminalSelectionLineRange(selectionPosition);
+        const bounds = mountElement.getBoundingClientRect();
+        const position = resolveTerminalSelectionActionPosition({
+          bounds,
+          selectionRect: activeTerminal.getSelectionEndClientRect(),
+          pointer: selectionPointerRef.current,
         });
-      if (requestId !== selectionActionRequestIdRef.current || clicked === null) {
-        return;
-      }
-      switch (clicked) {
-        case "add-to-chat":
-          handleAddTerminalContext(nextAction.selection);
-          terminalRef.current?.clearSelection();
-          terminalRef.current?.focus();
+        return {
+          position,
+          clipboardText: selectionText,
+          selection: {
+            terminalId,
+            terminalLabel: readTerminalLabel(),
+            lineStart,
+            lineEnd,
+            text: normalizedText,
+          },
+        };
+      };
+
+      const showSelectionAction = async () => {
+        if (!localApi) {
+          clearSelectionAction();
+          return;
+        }
+        if (selectionActionMenuOpenRef.current) {
           return;
-        case "copy":
-          try {
-            await writeTextToClipboard(nextAction.clipboardText, "terminal selection");
-          } catch (error) {
-            if (requestId !== selectionActionRequestIdRef.current) {
-              return;
+        }
+        const nextAction = readSelectionAction();
+        if (!nextAction) {
+          clearSelectionAction();
+          return;
+        }
+        const requestId = ++selectionActionRequestIdRef.current;
+        selectionActionMenuOpenRef.current = true;
+        const clicked = await localApi.contextMenu
+          .show(
+            [
+              { id: "add-to-chat", label: "Add to chat" },
+              { id: "copy", label: "Copy" },
+            ],
+            nextAction.position,
+          )
+          .finally(() => {
+            selectionActionMenuOpenRef.current = false;
+          });
+        if (requestId !== selectionActionRequestIdRef.current || clicked === null) {
+          return;
+        }
+        switch (clicked) {
+          case "add-to-chat":
+            handleAddTerminalContext(nextAction.selection);
+            terminalRef.current?.clearSelection();
+            terminalRef.current?.focus();
+            return;
+          case "copy":
+            try {
+              await writeTextToClipboard(nextAction.clipboardText, "terminal selection");
+            } catch (error) {
+              if (requestId !== selectionActionRequestIdRef.current) {
+                return;
+              }
+              const activeTerminal = terminalRef.current;
+              if (activeTerminal) {
+                writeSystemMessage(
+                  activeTerminal,
+                  error instanceof Error ? error.message : "Unable to copy terminal selection",
+                );
+              }
             }
-            const activeTerminal = terminalRef.current;
-            if (activeTerminal) {
-              writeSystemMessage(
-                activeTerminal,
-                error instanceof Error ? error.message : "Unable to copy terminal selection",
-              );
+            if (requestId === selectionActionRequestIdRef.current) {
+              terminalRef.current?.focus();
             }
-          }
-          if (requestId === selectionActionRequestIdRef.current) {
-            terminalRef.current?.focus();
-          }
-          return;
-      }
-    };
+            return;
+        }
+      };
 
-    const sendTerminalInput = async (data: string, fallbackError: string) => {
-      const activeTerminal = terminalRef.current;
-      if (!activeTerminal) return;
-      const result = await writeTerminal(data);
-      if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
-        const error = squashAtomCommandFailure(result);
-        writeSystemMessage(activeTerminal, error instanceof Error ? error.message : fallbackError);
-      }
-    };
+      const sendTerminalInput = async (data: string, fallbackError: string) => {
+        const activeTerminal = terminalRef.current;
+        if (!activeTerminal) return;
+        const result = await writeTerminal(data);
+        if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+          const error = squashAtomCommandFailure(result);
+          writeSystemMessage(
+            activeTerminal,
+            error instanceof Error ? error.message : fallbackError,
+          );
+        }
+      };
 
-    terminal.attachCustomKeyEventHandler((event) => {
-      const currentKeybindings = keybindingsRef.current;
-      const options = { context: { terminalFocus: true, terminalOpen: true } };
-      if (
-        isTerminalToggleShortcut(event, currentKeybindings, options) ||
-        isTerminalSplitShortcut(event, currentKeybindings, options) ||
-        isTerminalSplitVerticalShortcut(event, currentKeybindings, options) ||
-        isTerminalNewShortcut(event, currentKeybindings, options) ||
-        isTerminalCloseShortcut(event, currentKeybindings, options) ||
-        isDiffToggleShortcut(event, currentKeybindings, options)
-      ) {
-        return false;
-      }
+      function handleBeforeKey(event: KeyboardEvent): boolean {
+        const currentKeybindings = keybindingsRef.current;
+        const options = { context: { terminalFocus: true, terminalOpen: true } };
+        if (
+          isTerminalToggleShortcut(event, currentKeybindings, options) ||
+          isTerminalSplitShortcut(event, currentKeybindings, options) ||
+          isTerminalSplitVerticalShortcut(event, currentKeybindings, options) ||
+          isTerminalNewShortcut(event, currentKeybindings, options) ||
+          isTerminalCloseShortcut(event, currentKeybindings, options) ||
+          isDiffToggleShortcut(event, currentKeybindings, options)
+        ) {
+          return false;
+        }
 
-      const navigationData = terminalNavigationShortcutData(event);
-      if (navigationData !== null) {
-        event.preventDefault();
-        event.stopPropagation();
-        void sendTerminalInput(navigationData, "Failed to move cursor");
-        return false;
-      }
+        const navigationData = terminalNavigationShortcutData(event);
+        if (navigationData !== null) {
+          event.preventDefault();
+          event.stopPropagation();
+          void sendTerminalInput(navigationData, "Failed to move cursor");
+          return false;
+        }
+
+        const deleteData = terminalDeleteShortcutData(event);
+        if (deleteData !== null) {
+          event.preventDefault();
+          event.stopPropagation();
+          void sendTerminalInput(deleteData, "Failed to delete terminal input");
+          return false;
+        }
 
-      const deleteData = terminalDeleteShortcutData(event);
-      if (deleteData !== null) {
+        if (!isTerminalClearShortcut(event)) return true;
         event.preventDefault();
         event.stopPropagation();
-        void sendTerminalInput(deleteData, "Failed to delete terminal input");
+        void sendTerminalInput("\u000c", "Failed to clear terminal");
         return false;
       }
 
-      if (!isTerminalClearShortcut(event)) return true;
-      event.preventDefault();
-      event.stopPropagation();
-      void sendTerminalInput("\u000c", "Failed to clear terminal");
-      return false;
-    });
-
-    const terminalLinksDisposable = terminal.registerLinkProvider({
-      provideLinks: (bufferLineNumber, callback) => {
-        const activeTerminal = terminalRef.current;
-        if (!activeTerminal) {
-          callback(undefined);
+      function handleLinkActivate(text: string, event: MouseEvent): void {
+        if (!isTerminalLinkActivation(event)) return;
+        const latestTerminal = terminalRef.current;
+        if (!latestTerminal) return;
+        if (/^https?:\/\//u.test(text)) {
+          if (!localApi) {
+            writeSystemMessage(latestTerminal, "Opening links is unavailable in this browser.");
+            return;
+          }
+          const fallbackToBrowser = () => {
+            void localApi.shell.openExternal(text).catch((error: unknown) => {
+              writeSystemMessage(
+                latestTerminal,
+                error instanceof Error ? error.message : "Unable to open link",
+              );
+            });
+          };
+          void openTerminalLinkInPreview({
+            url: text,
+            position: { x: event.clientX, y: event.clientY },
+            threadRef,
+            openPreview,
+            localApi,
+            fallbackToBrowser,
+          });
           return;
         }
+        const target = resolvePathLinkTarget(text, cwd);
+        void (async () => {
+          const result = await openTerminalPath(target);
+          if (result._tag === "Success" || isAtomCommandInterrupted(result)) {
+            return;
+          }
+          const error = squashAtomCommandFailure(result);
+          writeSystemMessage(
+            latestTerminal,
+            error instanceof Error ? error.message : "Unable to open path",
+          );
+        })();
+      }
 
-        const wrappedLine = collectWrappedTerminalLinkLine(bufferLineNumber, (bufferLineIndex) =>
-          activeTerminal.buffer.active.getLine(bufferLineIndex),
-        );
-        if (!wrappedLine) {
-          callback(undefined);
-          return;
-        }
+      function handleCopy(text: string): void {
+        void writeTextToClipboard(text, "terminal selection").catch((error: unknown) => {
+          const activeTerminal = terminalRef.current;
+          if (!activeTerminal) return;
+          writeSystemMessage(
+            activeTerminal,
+            error instanceof Error ? error.message : "Unable to copy terminal selection",
+          );
+        });
+      }
 
-        const links = extractTerminalLinks(wrappedLine.text)
-          .map((match) => ({
-            match,
-            range: resolveWrappedTerminalLinkRange(wrappedLine, match),
-          }))
-          .filter(({ range }) =>
-            wrappedTerminalLinkRangeIntersectsBufferLine(range, bufferLineNumber),
+      function handleData(data: string): void {
+        void (async () => {
+          const result = await writeTerminal(data);
+          if (result._tag === "Success" || isAtomCommandInterrupted(result)) return;
+          const error = squashAtomCommandFailure(result);
+          writeSystemMessage(
+            terminal,
+            error instanceof Error ? error.message : "Terminal write failed",
           );
-        if (links.length === 0) {
-          callback(undefined);
+        })();
+      }
+
+      function handleSelectionChange(): void {
+        if (terminalRef.current?.hasSelection()) {
           return;
         }
+        clearSelectionAction();
+      }
 
-        callback(
-          links.map(({ match, range }) => ({
-            text: match.text,
-            range,
-            activate: (event: MouseEvent) => {
-              if (!isTerminalLinkActivation(event)) return;
-
-              const latestTerminal = terminalRef.current;
-              if (!latestTerminal) return;
-
-              if (match.kind === "url") {
-                if (!localApi) {
-                  writeSystemMessage(
-                    latestTerminal,
-                    "Opening links is unavailable in this browser.",
-                  );
-                  return;
-                }
-                const fallbackToBrowser = () => {
-                  void localApi.shell.openExternal(match.text).catch((error: unknown) => {
-                    writeSystemMessage(
-                      latestTerminal,
-                      error instanceof Error ? error.message : "Unable to open link",
-                    );
-                  });
-                };
-                void openTerminalLinkInPreview({
-                  url: match.text,
-                  position: { x: event.clientX, y: event.clientY },
-                  threadRef,
-                  openPreview,
-                  localApi,
-                  fallbackToBrowser,
-                });
-                return;
-              }
-
-              const target = resolvePathLinkTarget(match.text, cwd);
-              void (async () => {
-                const result = await openTerminalPath(target);
-                if (result._tag === "Success" || isAtomCommandInterrupted(result)) {
-                  return;
-                }
-                const error = squashAtomCommandFailure(result);
-                writeSystemMessage(
-                  latestTerminal,
-                  error instanceof Error ? error.message : "Unable to open path",
-                );
-              })();
-            },
-          })),
+      const handleMouseUp = (event: MouseEvent) => {
+        const shouldHandle = shouldHandleTerminalSelectionMouseUp(
+          selectionGestureActiveRef.current,
+          event.button,
         );
-      },
-    });
-
-    const inputDisposable = terminal.onData((data) => {
-      void (async () => {
-        const result = await writeTerminal(data);
-        if (result._tag === "Success" || isAtomCommandInterrupted(result)) {
+        selectionGestureActiveRef.current = false;
+        if (!shouldHandle) {
           return;
         }
-        const error = squashAtomCommandFailure(result);
-        writeSystemMessage(
-          terminal,
-          error instanceof Error ? error.message : "Terminal write failed",
-        );
-      })();
-    });
+        selectionPointerRef.current = { x: event.clientX, y: event.clientY };
+        const delay = terminalSelectionActionDelayForClickCount(event.detail);
+        selectionActionTimerRef.current = window.setTimeout(() => {
+          selectionActionTimerRef.current = null;
+          window.requestAnimationFrame(() => {
+            void showSelectionAction();
+          });
+        }, delay);
+      };
+      const handlePointerDown = (event: PointerEvent) => {
+        clearSelectionAction();
+        selectionGestureActiveRef.current = event.button === 0;
+      };
+      window.addEventListener("mouseup", handleMouseUp);
+      mount.addEventListener("pointerdown", handlePointerDown);
+      setupCleanups.push(() => {
+        window.removeEventListener("mouseup", handleMouseUp);
+        mount.removeEventListener("pointerdown", handlePointerDown);
+      });
 
-    const selectionDisposable = terminal.onSelectionChange(() => {
-      if (terminalRef.current?.hasSelection()) {
-        return;
-      }
-      clearSelectionAction();
-    });
+      const themeObserver = new MutationObserver(() => {
+        const activeTerminal = terminalRef.current;
+        if (!activeTerminal) return;
+        activeTerminal.setTheme(terminalThemeFromApp(containerRef.current));
+      });
+      themeObserver.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ["class", "style"],
+      });
+      setupCleanups.push(() => themeObserver.disconnect());
 
-    const handleMouseUp = (event: MouseEvent) => {
-      const shouldHandle = shouldHandleTerminalSelectionMouseUp(
-        selectionGestureActiveRef.current,
-        event.button,
-      );
-      selectionGestureActiveRef.current = false;
-      if (!shouldHandle) {
-        return;
-      }
-      selectionPointerRef.current = { x: event.clientX, y: event.clientY };
-      const delay = terminalSelectionActionDelayForClickCount(event.detail);
-      selectionActionTimerRef.current = window.setTimeout(() => {
-        selectionActionTimerRef.current = null;
-        window.requestAnimationFrame(() => {
-          void showSelectionAction();
-        });
-      }, delay);
-    };
-    const handlePointerDown = (event: PointerEvent) => {
-      clearSelectionAction();
-      selectionGestureActiveRef.current = event.button === 0;
+      const fitTimer = window.setTimeout(() => {
+        const activeTerminal = terminalRef.current;
+        if (!activeTerminal) return;
+        const wasAtBottom = activeTerminal.isAtBottom();
+        activeTerminal.fit();
+        if (wasAtBottom) {
+          activeTerminal.scrollToBottom();
+        }
+      }, 30);
+      setupCleanups.push(() => window.clearTimeout(fitTimer));
+
+      const cleanups = setupCleanups;
+      setupCleanups = [];
+      setupTerminal = null;
+      return () => {
+        for (const cleanup of cleanups.toReversed()) cleanup();
+        if (terminalRef.current === terminal) terminalRef.current = null;
+        terminal.dispose();
+      };
     };
-    window.addEventListener("mouseup", handleMouseUp);
-    mount.addEventListener("pointerdown", handlePointerDown);
-
-    const themeObserver = new MutationObserver(() => {
-      const activeTerminal = terminalRef.current;
-      if (!activeTerminal) return;
-      activeTerminal.options.theme = terminalThemeFromApp(containerRef.current);
-      activeTerminal.refresh(0, activeTerminal.rows - 1);
-    });
-    themeObserver.observe(document.documentElement, {
-      attributes: true,
-      attributeFilter: ["class", "style"],
-    });
 
-    const fitTimer = window.setTimeout(() => {
-      const activeTerminal = terminalRef.current;
-      const activeFitAddon = fitAddonRef.current;
-      if (!activeTerminal || !activeFitAddon) return;
-      const wasAtBottom =
-        activeTerminal.buffer.active.viewportY >= activeTerminal.buffer.active.baseY;
-      fitTerminalSafely(activeFitAddon);
-      if (wasAtBottom) {
-        activeTerminal.scrollToBottom();
-      }
-      void resizeTerminal(activeTerminal.cols, activeTerminal.rows);
-    }, 30);
+    void setup()
+      .then((nextTeardown) => {
+        if (cancelled) {
+          nextTeardown?.();
+          return;
+        }
+        teardown = nextTeardown;
+      })
+      .catch((error: unknown) => {
+        for (const cleanup of setupCleanups.toReversed()) cleanup();
+        setupCleanups = [];
+        if (terminalRef.current === setupTerminal) terminalRef.current = null;
+        setupTerminal?.dispose();
+        setupTerminal = null;
+        if (cancelled) return;
+        const message =
+          error instanceof Error ? error.message : "Unable to initialize libghostty-vt";
+        mount.textContent = `${message} — close and reopen the terminal to retry.`;
+      });
 
     return () => {
-      window.clearTimeout(fitTimer);
-      inputDisposable.dispose();
-      selectionDisposable.dispose();
-      terminalLinksDisposable.dispose();
-      if (selectionActionTimerRef.current !== null) {
-        window.clearTimeout(selectionActionTimerRef.current);
-      }
-      window.removeEventListener("mouseup", handleMouseUp);
-      mount.removeEventListener("pointerdown", handlePointerDown);
-      themeObserver.disconnect();
-      terminalRef.current = null;
-      fitAddonRef.current = null;
-      terminal.dispose();
+      cancelled = true;
+      teardown?.();
     };
     // autoFocus is intentionally omitted;
     // it is only read at mount time and must not trigger terminal teardown/recreation.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [cwd, environmentId, runtimeEnvKey, terminalId, threadId, worktreePath]);
 
   useEffect(() => {
@@ -764,6 +744,7 @@ export function TerminalViewport({
     }
 
     const previous = previousSessionRef.current;
+    synchronizeTerminalStatus(terminal, current.status);
     if (current.version === previous.version) {
       return;
     }
@@ -782,25 +763,6 @@ export function TerminalViewport({
       writeSystemMessage(terminal, current.error);
     }
 
-    if (current.status === "running") {
-      hasHandledExitRef.current = false;
-    } else if (
-      (current.status === "closed" || current.status === "exited") &&
-      current.status !== previous.status &&
-      !hasHandledExitRef.current
-    ) {
-      hasHandledExitRef.current = true;
-      writeSystemMessage(
-        terminal,
-        current.status === "closed" ? "Terminal closed" : "Process exited",
-      );
-      window.setTimeout(() => {
-        if (hasHandledExitRef.current) {
-          handleSessionExited();
-        }
-      }, 0);
-    }
-
     if (previous.version === 0 && autoFocus) {
       window.requestAnimationFrame(() => {
         terminal.focus();
@@ -823,15 +785,15 @@ export function TerminalViewport({
 
   useEffect(() => {
     const terminal = terminalRef.current;
-    const fitAddon = fitAddonRef.current;
-    if (!terminal || !fitAddon) return;
-    const wasAtBottom = terminal.buffer.active.viewportY >= terminal.buffer.active.baseY;
+    if (!terminal) return;
+    const wasAtBottom = terminal.isAtBottom();
+    // The surface reports grid changes through onResize, which is the single
+    // channel for PTY resize RPCs; fitting here only refreshes the layout.
     const frame = window.requestAnimationFrame(() => {
-      fitTerminalSafely(fitAddon);
+      terminal.fit();
       if (wasAtBottom) {
         terminal.scrollToBottom();
       }
-      void resizeTerminal(terminal.cols, terminal.rows);
     });
     return () => {
       window.cancelAnimationFrame(frame);
@@ -1290,7 +1252,7 @@ export default function ThreadTerminalDrawer({
 
       {!hasTerminalSidebar && (
         <div className="pointer-events-none absolute right-2 top-2 z-20">
-          <div className="pointer-events-auto inline-flex items-center overflow-hidden rounded-md border border-border/80 bg-background/70">
+          <div className="pointer-events-auto inline-flex items-center overflow-hidden rounded-md border border-border/80 bg-background shadow-xs">
             <TerminalActionButton
               className={`p-1 text-foreground/90 transition-colors ${
                 hasReachedSplitLimit
diff --git a/apps/web/src/components/chat/ComposerBannerStack.tsx b/apps/web/src/components/chat/ComposerBannerStack.tsx
index 699c9cfd9c4..548bd0f4262 100644
--- a/apps/web/src/components/chat/ComposerBannerStack.tsx
+++ b/apps/web/src/components/chat/ComposerBannerStack.tsx
@@ -24,7 +24,7 @@ const exitTransitionStyle = {
 
 export interface ComposerBannerStackItem {
   readonly id: string;
-  readonly variant: "error" | "info" | "success" | "warning";
+  readonly variant: "default" | "error" | "info" | "success" | "warning";
   readonly icon: ReactNode;
   readonly title: ReactNode;
   readonly description?: ReactNode;
diff --git a/apps/web/src/components/chat/ModelListRow.tsx b/apps/web/src/components/chat/ModelListRow.tsx
index e86435561a2..a74a4ebf8c2 100644
--- a/apps/web/src/components/chat/ModelListRow.tsx
+++ b/apps/web/src/components/chat/ModelListRow.tsx
@@ -12,6 +12,7 @@ import { Button } from "../ui/button";
 import { Kbd } from "../ui/kbd";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { cn } from "~/lib/utils";
+import { modelPickerModelKey } from "./modelPickerKeys";
 
 export const ModelListRow = memo(function ModelListRow(props: {
   index: number;
@@ -46,7 +47,7 @@ export const ModelListRow = memo(function ModelListRow(props: {
     <ComboboxItem
       hideIndicator
       index={props.index}
-      value={`${props.instanceId}:${props.model.slug}`}
+      value={modelPickerModelKey(props.instanceId, props.model.slug)}
       disabled={Boolean(props.disabledReason)}
       contentClassName="flex w-full items-center gap-3"
       className={cn(
diff --git a/apps/web/src/components/chat/ModelPickerContent.tsx b/apps/web/src/components/chat/ModelPickerContent.tsx
index d317ee6061c..c58716d843c 100644
--- a/apps/web/src/components/chat/ModelPickerContent.tsx
+++ b/apps/web/src/components/chat/ModelPickerContent.tsx
@@ -6,12 +6,24 @@ import {
 import { resolveSelectableModel } from "@t3tools/shared/model";
 import { LegendList, type LegendListRef } from "@legendapp/list/react";
 import { memo, useMemo, useState, useCallback, useEffect, useLayoutEffect, useRef } from "react";
-import { SearchIcon } from "lucide-react";
+import { ChevronRightIcon, SearchIcon } from "lucide-react";
 import { ModelListRow } from "./ModelListRow";
 import { ModelPickerSidebar } from "./ModelPickerSidebar";
+import {
+  modelPickerLegacySectionKey,
+  modelPickerModelKey,
+  parseModelPickerLegacySectionKey,
+  parseModelPickerModelKey,
+} from "./modelPickerKeys";
 import { isModelPickerNewModel } from "./modelPickerModelHighlights";
 import { buildModelPickerSearchText, scoreModelPickerSearch } from "./modelPickerSearch";
-import { Combobox, ComboboxEmpty, ComboboxInput, ComboboxListVirtualized } from "../ui/combobox";
+import {
+  Combobox,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxListVirtualized,
+} from "../ui/combobox";
 import { ModelEsque } from "./providerIconUtils";
 import {
   modelPickerJumpCommandForIndex,
@@ -39,6 +51,7 @@ type ModelPickerItem = {
   instanceDisplayName: string;
   instanceAccentColor?: string | undefined;
   continuationGroupKey?: string | undefined;
+  isLegacy?: boolean | undefined;
 };
 
 const EMPTY_MODEL_JUMP_LABELS = new Map<string, string>();
@@ -47,20 +60,6 @@ function ModelListSeparator() {
   return <div className="h-0.5" />;
 }
 
-// Split a `${instanceId}:${slug}` combobox key back into its pieces. Slugs
-// can contain colons (e.g. some vendor model ids), so we only split on the
-// first colon — anything after that is the slug.
-function splitInstanceModelKey(key: string): { instanceId: ProviderInstanceId; slug: string } {
-  const colonIndex = key.indexOf(":");
-  if (colonIndex === -1) {
-    return { instanceId: key as ProviderInstanceId, slug: "" };
-  }
-  return {
-    instanceId: key.slice(0, colonIndex) as ProviderInstanceId,
-    slug: key.slice(colonIndex + 1),
-  };
-}
-
 export const ModelPickerContent = memo(function ModelPickerContent(props: {
   /** The instance currently selected in the composer (combobox "value"). */
   activeInstanceId: ProviderInstanceId;
@@ -117,6 +116,16 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       return favorites.length > 0 ? "favorites" : props.activeInstanceId;
     },
   );
+  const [expandedLegacyInstances, setExpandedLegacyInstances] = useState(
+    () =>
+      new Set<ProviderInstanceId>(
+        modelOptionsByInstance
+          .get(props.activeInstanceId)
+          ?.some((model) => model.slug === props.model && model.isLegacy)
+          ? [props.activeInstanceId]
+          : [],
+      ),
+  );
   const keybindings = useMemo<ResolvedKeybindingsConfig>(
     () => providedKeybindings ?? [],
     [providedKeybindings],
@@ -211,6 +220,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
           name: model.name,
           ...(model.shortName ? { shortName: model.shortName } : {}),
           ...(model.subProvider ? { subProvider: model.subProvider } : {}),
+          ...(model.isLegacy ? { isLegacy: true } : {}),
           instanceId,
           driverKind: entry.driverKind,
           instanceDisplayName: entry.displayName,
@@ -366,6 +376,45 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
     selectedInstanceId,
   ]);
 
+  const legacySection = useMemo(() => {
+    if (isSearching || selectedInstanceId === "favorites") {
+      return null;
+    }
+    const currentModels = filteredModels.filter((model) => !model.isLegacy);
+    const legacyModels = filteredModels.filter((model) => model.isLegacy);
+    if (legacyModels.length === 0) {
+      return null;
+    }
+    return {
+      key: modelPickerLegacySectionKey(selectedInstanceId),
+      currentModels,
+      legacyModels,
+      isExpanded: expandedLegacyInstances.has(selectedInstanceId),
+    };
+  }, [expandedLegacyInstances, filteredModels, isSearching, selectedInstanceId]);
+
+  const visibleModels = useMemo(() => {
+    if (!legacySection) {
+      return filteredModels;
+    }
+    return [
+      ...legacySection.currentModels,
+      ...(legacySection.isExpanded ? legacySection.legacyModels : []),
+    ];
+  }, [filteredModels, legacySection]);
+
+  const toggleLegacySection = useCallback((instanceId: ProviderInstanceId) => {
+    setExpandedLegacyInstances((expanded) => {
+      const next = new Set(expanded);
+      if (next.has(instanceId)) {
+        next.delete(instanceId);
+      } else {
+        next.add(instanceId);
+      }
+      return next;
+    });
+  }, []);
+
   const handleModelSelect = useCallback(
     (modelSlug: string, instanceId: ProviderInstanceId) => {
       if (getModelDisabledReason?.(instanceId, modelSlug)) {
@@ -410,7 +459,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       NonNullable<ReturnType<typeof modelPickerJumpCommandForIndex>>
     >();
     let selectableModelIndex = 0;
-    for (const model of filteredModels) {
+    for (const model of visibleModels) {
       if (getModelDisabledReason?.(model.instanceId, model.slug)) {
         continue;
       }
@@ -418,27 +467,44 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       if (!jumpCommand) {
         return mapping;
       }
-      mapping.set(`${model.instanceId}:${model.slug}`, jumpCommand);
+      mapping.set(modelPickerModelKey(model.instanceId, model.slug), jumpCommand);
       selectableModelIndex += 1;
     }
     return mapping;
-  }, [filteredModels, getModelDisabledReason]);
+  }, [getModelDisabledReason, visibleModels]);
   const modelJumpModelKeys = useMemo(
     () => [...modelJumpCommandByKey.keys()],
     [modelJumpCommandByKey],
   );
-  const allModelKeys = useMemo(
-    (): string[] => flatModels.map((model) => `${model.instanceId}:${model.slug}`),
+  const allItemKeys = useMemo(
+    (): string[] => [
+      ...flatModels.map((model) => modelPickerModelKey(model.instanceId, model.slug)),
+      ...new Set(
+        flatModels
+          .filter((model) => model.isLegacy)
+          .map((model) => modelPickerLegacySectionKey(model.instanceId)),
+      ),
+    ],
     [flatModels],
   );
-  const filteredModelKeys = useMemo(
-    (): string[] => filteredModels.map((model) => `${model.instanceId}:${model.slug}`),
-    [filteredModels],
-  );
+  const filteredItemKeys = useMemo((): string[] => {
+    const modelKeys = visibleModels.map((model) =>
+      modelPickerModelKey(model.instanceId, model.slug),
+    );
+    if (!legacySection) {
+      return modelKeys;
+    }
+    modelKeys.splice(legacySection.currentModels.length, 0, legacySection.key);
+    return modelKeys;
+  }, [legacySection, visibleModels]);
   const filteredModelByKey = useMemo(
     (): ReadonlyMap<string, ModelPickerItem> =>
-      new Map(filteredModels.map((model) => [`${model.instanceId}:${model.slug}`, model] as const)),
-    [filteredModels],
+      new Map(
+        visibleModels.map(
+          (model) => [modelPickerModelKey(model.instanceId, model.slug), model] as const,
+        ),
+      ),
+    [visibleModels],
   );
   const updateModelListScrollFades = useCallback(() => {
     const scrollElement = modelListRef.current?.getScrollableNode();
@@ -495,10 +561,13 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       if (!targetModelKey) {
         return;
       }
-      const { instanceId, slug } = splitInstanceModelKey(targetModelKey);
+      const model = parseModelPickerModelKey(targetModelKey);
+      if (!model) {
+        return;
+      }
       event.preventDefault();
       event.stopPropagation();
-      handleModelSelect(slug, instanceId);
+      handleModelSelect(model.slug, model.instanceId);
     };
 
     window.addEventListener("keydown", onWindowKeyDown, true);
@@ -510,7 +579,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
 
   useLayoutEffect(() => {
     setShowTopScrollFade(false);
-    setShowBottomScrollFade(filteredModelKeys.length > 5);
+    setShowBottomScrollFade(filteredItemKeys.length > 5);
     let nestedFrame = 0;
     const frame = window.requestAnimationFrame(() => {
       updateModelListScrollFades();
@@ -520,7 +589,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
       window.cancelAnimationFrame(frame);
       window.cancelAnimationFrame(nestedFrame);
     };
-  }, [filteredModelKeys, updateModelListScrollFades]);
+  }, [filteredItemKeys, updateModelListScrollFades]);
 
   return (
     <TooltipProvider delay={0}>
@@ -548,13 +617,13 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
         {/* Main content area */}
         <Combobox
           inline
-          items={allModelKeys}
-          filteredItems={filteredModelKeys}
+          items={allItemKeys}
+          filteredItems={filteredItemKeys}
           filter={null}
           autoHighlight
           open
           virtualized
-          value={`${props.activeInstanceId}:${props.model}`}
+          value={modelPickerModelKey(props.activeInstanceId, props.model)}
           onItemHighlighted={(modelKey, eventDetails) => {
             highlightedModelKeyRef.current = typeof modelKey === "string" ? modelKey : null;
             if (eventDetails.reason === "keyboard" && eventDetails.index >= 0) {
@@ -568,8 +637,15 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
             if (typeof modelKey !== "string") {
               return;
             }
-            const { instanceId, slug } = splitInstanceModelKey(modelKey);
-            handleModelSelect(slug, instanceId);
+            const legacyInstanceId = parseModelPickerLegacySectionKey(modelKey);
+            if (legacyInstanceId) {
+              toggleLegacySection(legacyInstanceId);
+              return;
+            }
+            const model = parseModelPickerModelKey(modelKey);
+            if (model) {
+              handleModelSelect(model.slug, model.instanceId);
+            }
           }}
         >
           <div
@@ -605,10 +681,17 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
                       ).preventBaseUIHandler?.();
                       e.preventDefault();
                       e.stopPropagation();
-                      const { instanceId, slug } = splitInstanceModelKey(
+                      const legacyInstanceId = parseModelPickerLegacySectionKey(
                         highlightedModelKeyRef.current,
                       );
-                      handleModelSelect(slug, instanceId);
+                      if (legacyInstanceId) {
+                        toggleLegacySection(legacyInstanceId);
+                        return;
+                      }
+                      const model = parseModelPickerModelKey(highlightedModelKeyRef.current);
+                      if (model) {
+                        handleModelSelect(model.slug, model.instanceId);
+                      }
                       return;
                     }
                     e.stopPropagation();
@@ -626,10 +709,35 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
               <ComboboxListVirtualized className="size-full min-w-0 p-0 not-empty:p-0">
                 <LegendList<string>
                   ref={modelListRef}
-                  data={filteredModelKeys}
+                  data={filteredItemKeys}
                   extraData={favoritesSet}
                   keyExtractor={(modelKey) => modelKey}
                   renderItem={({ item: modelKey, index }) => {
+                    if (legacySection?.key === modelKey) {
+                      return (
+                        <ComboboxItem
+                          hideIndicator
+                          index={index}
+                          value={modelKey}
+                          aria-expanded={legacySection.isExpanded}
+                          className="group w-full cursor-pointer rounded-md px-2 py-2"
+                          contentClassName="flex w-full items-center gap-3"
+                        >
+                          <div className="min-w-0 flex-1 text-left">
+                            <div className="text-xs font-medium leading-snug">Legacy models</div>
+                            <div className="mt-1 text-xs font-normal leading-snug text-muted-foreground/70">
+                              {legacySection.legacyModels.length} models
+                            </div>
+                          </div>
+                          <ChevronRightIcon
+                            className={cn(
+                              "size-4 transition-transform",
+                              legacySection.isExpanded && "rotate-90",
+                            )}
+                          />
+                        </ComboboxItem>
+                      );
+                    }
                     const model = filteredModelByKey.get(modelKey);
                     if (!model) {
                       return null;
@@ -645,8 +753,12 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
                         driverKind={model.driverKind}
                         providerDisplayName={model.instanceDisplayName}
                         providerAccentColor={model.instanceAccentColor}
-                        isFavorite={favoritesSet.has(modelKey)}
-                        isSelected={modelKey === `${props.activeInstanceId}:${props.model}`}
+                        isFavorite={favoritesSet.has(
+                          providerModelKey(model.instanceId, model.slug),
+                        )}
+                        isSelected={
+                          modelKey === modelPickerModelKey(props.activeInstanceId, props.model)
+                        }
                         showProvider
                         preferShortName={!isLocked}
                         useTriggerLabel={false}
@@ -657,7 +769,7 @@ export const ModelPickerContent = memo(function ModelPickerContent(props: {
                       />
                     );
                   }}
-                  estimatedItemSize={60}
+                  estimatedItemSize={52}
                   drawDistance={480}
                   recycleItems
                   contentContainerClassName="pl-2 pr-px"
diff --git a/apps/web/src/components/chat/TraitsPicker.tsx b/apps/web/src/components/chat/TraitsPicker.tsx
index 3449270f135..125ea8ccc6e 100644
--- a/apps/web/src/components/chat/TraitsPicker.tsx
+++ b/apps/web/src/components/chat/TraitsPicker.tsx
@@ -494,7 +494,13 @@ export const TraitsPicker = memo(function TraitsPicker({
   });
   const fastModeIcon = showFastModeIcon ? (
     <>
-      <ComposerControlIcon icon={ZapIcon} className="text-foreground/80 opacity-100" />
+      <ComposerControlIcon
+        icon={ZapIcon}
+        className={cn(
+          "fill-current opacity-80",
+          provider === "claudeAgent" ? "text-[#d97757]" : "text-foreground",
+        )}
+      />
       <span className="sr-only">Fast mode on</span>
     </>
   ) : null;
diff --git a/apps/web/src/components/chat/modelPickerKeys.test.ts b/apps/web/src/components/chat/modelPickerKeys.test.ts
new file mode 100644
index 00000000000..e56fcb3d414
--- /dev/null
+++ b/apps/web/src/components/chat/modelPickerKeys.test.ts
@@ -0,0 +1,31 @@
+import { ProviderInstanceId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+import {
+  modelPickerLegacySectionKey,
+  modelPickerModelKey,
+  parseModelPickerLegacySectionKey,
+  parseModelPickerModelKey,
+} from "./modelPickerKeys";
+
+describe("model picker item keys", () => {
+  it("keeps model and legacy section keys distinct for colliding instance names", () => {
+    const modelKey = modelPickerModelKey(ProviderInstanceId.make("legacy-models"), "codex");
+    const sectionKey = modelPickerLegacySectionKey(ProviderInstanceId.make("codex"));
+
+    expect(modelKey).not.toBe(sectionKey);
+    expect(parseModelPickerLegacySectionKey(modelKey)).toBeNull();
+    expect(parseModelPickerModelKey(modelKey)).toEqual({
+      instanceId: "legacy-models",
+      slug: "codex",
+    });
+  });
+
+  it("round-trips arbitrary strings without throwing", () => {
+    const instanceId = ProviderInstanceId.make("custom");
+    const slug = "model:\udfff";
+
+    const key = modelPickerModelKey(instanceId, slug);
+
+    expect(parseModelPickerModelKey(key)).toEqual({ instanceId, slug });
+  });
+});
diff --git a/apps/web/src/components/chat/modelPickerKeys.ts b/apps/web/src/components/chat/modelPickerKeys.ts
new file mode 100644
index 00000000000..0b4f0845e11
--- /dev/null
+++ b/apps/web/src/components/chat/modelPickerKeys.ts
@@ -0,0 +1,47 @@
+import type { ProviderInstanceId } from "@t3tools/contracts";
+
+const MODEL_KEY_PREFIX = "model:";
+const LEGACY_SECTION_KEY_PREFIX = "legacy-models:";
+
+export function modelPickerModelKey(instanceId: ProviderInstanceId, slug: string): string {
+  return `${MODEL_KEY_PREFIX}${instanceId.length}:${instanceId}${slug}`;
+}
+
+export function parseModelPickerModelKey(
+  key: string,
+): { instanceId: ProviderInstanceId; slug: string } | null {
+  if (!key.startsWith(MODEL_KEY_PREFIX)) {
+    return null;
+  }
+  const encoded = key.slice(MODEL_KEY_PREFIX.length);
+  const separatorIndex = encoded.indexOf(":");
+  if (separatorIndex === -1) {
+    return null;
+  }
+
+  const instanceIdLengthText = encoded.slice(0, separatorIndex);
+  if (!/^\d+$/.test(instanceIdLengthText)) {
+    return null;
+  }
+
+  const instanceIdLength = Number(instanceIdLengthText);
+  const value = encoded.slice(separatorIndex + 1);
+  if (!Number.isSafeInteger(instanceIdLength) || instanceIdLength > value.length) {
+    return null;
+  }
+
+  return {
+    instanceId: value.slice(0, instanceIdLength) as ProviderInstanceId,
+    slug: value.slice(instanceIdLength),
+  };
+}
+
+export function modelPickerLegacySectionKey(instanceId: ProviderInstanceId): string {
+  return `${LEGACY_SECTION_KEY_PREFIX}${instanceId}`;
+}
+
+export function parseModelPickerLegacySectionKey(key: string): ProviderInstanceId | null {
+  return key.startsWith(LEGACY_SECTION_KEY_PREFIX)
+    ? (key.slice(LEGACY_SECTION_KEY_PREFIX.length) as ProviderInstanceId)
+    : null;
+}
diff --git a/apps/web/src/components/chat/providerIconUtils.ts b/apps/web/src/components/chat/providerIconUtils.ts
index f9e7a700716..842c616fe1f 100644
--- a/apps/web/src/components/chat/providerIconUtils.ts
+++ b/apps/web/src/components/chat/providerIconUtils.ts
@@ -26,6 +26,7 @@ export type ModelEsque = {
   name: string;
   shortName?: string | undefined;
   subProvider?: string | undefined;
+  isLegacy?: boolean | undefined;
 };
 
 function escapeRegExp(value: string): string {
diff --git a/apps/web/src/components/desktopUpdate.logic.test.ts b/apps/web/src/components/desktopUpdate.logic.test.ts
index b07ae99c058..8d24b34a433 100644
--- a/apps/web/src/components/desktopUpdate.logic.test.ts
+++ b/apps/web/src/components/desktopUpdate.logic.test.ts
@@ -7,6 +7,7 @@ import {
   getDesktopUpdateActionError,
   getDesktopUpdateButtonTooltip,
   getDesktopUpdateInstallConfirmationMessage,
+  getDesktopUpdateReleaseUrl,
   isDesktopUpdateButtonDisabled,
   resolveDesktopUpdateButtonAction,
   shouldShowArm64IntelBuildWarning,
@@ -158,6 +159,23 @@ describe("getDesktopUpdateActionError", () => {
 });
 
 describe("desktop update UI helpers", () => {
+  it("builds the stable release URL for a downloaded version", () => {
+    expect(getDesktopUpdateReleaseUrl("0.0.30")).toBe(
+      "https://github.com/pingdotgg/t3code/releases/tag/v0.0.30",
+    );
+  });
+
+  it("builds the nightly release URL without dropping its version suffix", () => {
+    expect(getDesktopUpdateReleaseUrl("0.0.30-nightly.20260728.931")).toBe(
+      "https://github.com/pingdotgg/t3code/releases/tag/v0.0.30-nightly.20260728.931",
+    );
+  });
+
+  it("omits the release URL when the updater does not report a version", () => {
+    expect(getDesktopUpdateReleaseUrl(null)).toBeNull();
+    expect(getDesktopUpdateReleaseUrl("  ")).toBeNull();
+  });
+
   it("toasts only for actionable updater errors", () => {
     expect(
       shouldToastDesktopUpdateActionResult({
diff --git a/apps/web/src/components/desktopUpdate.logic.ts b/apps/web/src/components/desktopUpdate.logic.ts
index 11c34777a41..dc09d7ca877 100644
--- a/apps/web/src/components/desktopUpdate.logic.ts
+++ b/apps/web/src/components/desktopUpdate.logic.ts
@@ -3,6 +3,24 @@ import { isWindowsPlatform } from "../lib/utils";
 
 export type DesktopUpdateButtonAction = "download" | "install" | "none";
 
+const DESKTOP_RELEASE_TAG_URL = "https://github.com/pingdotgg/t3code/releases/tag";
+
+/**
+ * The main process fills `downloadedVersion` from the updater's `update-downloaded`
+ * event, which is dispatched on its own fiber. A download RPC can therefore resolve
+ * before that write lands, so fall back to the version the download was started for.
+ */
+export function getDesktopUpdateDownloadedVersion(state: DesktopUpdateState): string | null {
+  return state.downloadedVersion ?? state.availableVersion;
+}
+
+/** Release notes for an exact downloaded build; nightly suffixes are part of the tag. */
+export function getDesktopUpdateReleaseUrl(version: string | null): string | null {
+  const normalizedVersion = version?.trim();
+  if (!normalizedVersion) return null;
+  return `${DESKTOP_RELEASE_TAG_URL}/v${encodeURIComponent(normalizedVersion)}`;
+}
+
 export function resolveDesktopUpdateButtonAction(
   state: DesktopUpdateState,
 ): DesktopUpdateButtonAction {
diff --git a/apps/web/src/components/desktopUpdate.toast.test.tsx b/apps/web/src/components/desktopUpdate.toast.test.tsx
new file mode 100644
index 00000000000..369a3cdf431
--- /dev/null
+++ b/apps/web/src/components/desktopUpdate.toast.test.tsx
@@ -0,0 +1,121 @@
+import { isValidElement, type ReactElement, type ReactNode } from "react";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import type { DesktopUpdateState } from "@t3tools/contracts";
+
+const testState = vi.hoisted(() => ({
+  addToast: vi.fn(),
+}));
+
+vi.mock("./ui/toast", () => ({
+  toastManager: { add: testState.addToast },
+}));
+
+import { showDesktopUpdateDownloadedToast } from "./desktopUpdate.toast";
+
+type ClickableElement = ReactElement<{ readonly onClick?: () => void }>;
+
+/** Walks the rendered description, invoking function components, to find the link button. */
+function findReleaseNotesLink(node: ReactNode): ClickableElement | null {
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const found = findReleaseNotesLink(child);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (!isValidElement(node)) return null;
+  const element = node as ReactElement<{ readonly children?: ReactNode }>;
+  if (element.type === "button") return element as ClickableElement;
+  if (typeof element.type === "function") {
+    const render = element.type as (props: unknown) => ReactNode;
+    return findReleaseNotesLink(render(element.props));
+  }
+  return findReleaseNotesLink(element.props.children);
+}
+
+function getDescription(): ReactNode {
+  const toast = testState.addToast.mock.calls[0]?.[0] as { description?: ReactNode } | undefined;
+  return toast?.description ?? null;
+}
+
+function downloadedState(overrides: Partial<DesktopUpdateState> = {}): DesktopUpdateState {
+  return {
+    enabled: true,
+    status: "downloaded",
+    channel: "latest",
+    currentVersion: "0.0.29",
+    hostArch: "arm64",
+    appArch: "arm64",
+    runningUnderArm64Translation: false,
+    availableVersion: "0.0.30",
+    downloadedVersion: "0.0.30",
+    releaseNotes: [],
+    downloadPercent: 100,
+    checkedAt: null,
+    message: null,
+    errorContext: null,
+    canRetry: true,
+    ...overrides,
+  };
+}
+
+describe("showDesktopUpdateDownloadedToast", () => {
+  beforeEach(() => {
+    testState.addToast.mockReset();
+  });
+
+  it("opens the downloaded version's release notes", async () => {
+    const openExternal = vi.fn().mockResolvedValue(true);
+
+    showDesktopUpdateDownloadedToast({ openExternal }, downloadedState());
+    const link = findReleaseNotesLink(getDescription());
+    link?.props.onClick?.();
+    await vi.waitFor(() => {
+      expect(openExternal).toHaveBeenCalledWith(
+        "https://github.com/pingdotgg/t3code/releases/tag/v0.0.30",
+      );
+    });
+    expect(testState.addToast).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to the version the download was started for", async () => {
+    const openExternal = vi.fn().mockResolvedValue(true);
+
+    // The `update-downloaded` event can land after the download RPC resolves.
+    showDesktopUpdateDownloadedToast(
+      { openExternal },
+      downloadedState({ downloadedVersion: null }),
+    );
+    findReleaseNotesLink(getDescription())?.props.onClick?.();
+
+    await vi.waitFor(() => {
+      expect(openExternal).toHaveBeenCalledWith(
+        "https://github.com/pingdotgg/t3code/releases/tag/v0.0.30",
+      );
+    });
+  });
+
+  it("omits the link when the updater reports no version at all", () => {
+    showDesktopUpdateDownloadedToast(
+      { openExternal: vi.fn() },
+      downloadedState({ availableVersion: null, downloadedVersion: null }),
+    );
+
+    expect(findReleaseNotesLink(getDescription())).toBeNull();
+  });
+
+  it.each([
+    ["returns false", vi.fn().mockResolvedValue(false)],
+    ["rejects", vi.fn().mockRejectedValue(new Error("open failed"))],
+  ])("shows an error when opening release notes %s", async (_description, openExternal) => {
+    showDesktopUpdateDownloadedToast({ openExternal }, downloadedState());
+    findReleaseNotesLink(getDescription())?.props.onClick?.();
+
+    await vi.waitFor(() => {
+      expect(testState.addToast).toHaveBeenLastCalledWith({
+        type: "error",
+        title: "Unable to open release notes",
+      });
+    });
+  });
+});
diff --git a/apps/web/src/components/desktopUpdate.toast.tsx b/apps/web/src/components/desktopUpdate.toast.tsx
new file mode 100644
index 00000000000..004a76a81cd
--- /dev/null
+++ b/apps/web/src/components/desktopUpdate.toast.tsx
@@ -0,0 +1,55 @@
+import type { DesktopBridge, DesktopUpdateState } from "@t3tools/contracts";
+import { ArrowRightIcon } from "lucide-react";
+
+import {
+  getDesktopUpdateDownloadedVersion,
+  getDesktopUpdateReleaseUrl,
+} from "./desktopUpdate.logic";
+import { toastManager } from "./ui/toast";
+
+type DesktopUpdateShell = Pick<DesktopBridge, "openExternal">;
+
+function ReleaseNotesLink({
+  shell,
+  releaseUrl,
+}: {
+  shell: DesktopUpdateShell;
+  releaseUrl: string;
+}) {
+  return (
+    <button
+      className="ml-2 inline-flex cursor-pointer items-center gap-1 align-baseline text-muted-foreground underline decoration-dotted underline-offset-4 transition-colors hover:text-foreground"
+      onClick={() => {
+        void (async () => {
+          try {
+            if (await shell.openExternal(releaseUrl)) return;
+          } catch {
+            // Surface rejected IPC calls through the same user-visible fallback.
+          }
+          toastManager.add({ type: "error", title: "Unable to open release notes" });
+        })();
+      }}
+      type="button"
+    >
+      Read more
+      <ArrowRightIcon aria-hidden className="size-3 -rotate-45" strokeWidth={2.25} />
+    </button>
+  );
+}
+
+export function showDesktopUpdateDownloadedToast(
+  shell: DesktopUpdateShell,
+  state: DesktopUpdateState,
+): void {
+  const releaseUrl = getDesktopUpdateReleaseUrl(getDesktopUpdateDownloadedVersion(state));
+  toastManager.add({
+    type: "success",
+    title: "Update downloaded",
+    description: (
+      <>
+        Restart the app from the update button to install it.
+        {releaseUrl ? <ReleaseNotesLink releaseUrl={releaseUrl} shell={shell} /> : null}
+      </>
+    ),
+  });
+}
diff --git a/apps/web/src/components/files/FileBrowserPanel.tsx b/apps/web/src/components/files/FileBrowserPanel.tsx
index 307d4413751..ff658693a70 100644
--- a/apps/web/src/components/files/FileBrowserPanel.tsx
+++ b/apps/web/src/components/files/FileBrowserPanel.tsx
@@ -26,6 +26,10 @@ interface FileBrowserPanelProps {
   environmentId: EnvironmentId;
   cwd: string;
   projectName: string;
+  /** File currently open in the preview pane; revealed and selected in the tree. */
+  selectedPath: string | null;
+  /** Bumped when the same path should be revealed again (e.g. re-opened from search). */
+  selectedPathRevealId: number;
   onOpenFile: (relativePath: string) => void;
 }
 
@@ -98,6 +102,8 @@ export default function FileBrowserPanel({
   environmentId,
   cwd,
   projectName,
+  selectedPath,
+  selectedPathRevealId,
   onOpenFile,
 }: FileBrowserPanelProps) {
   const { resolvedTheme } = useTheme();
@@ -111,6 +117,9 @@ export default function FileBrowserPanel({
   const entryKindsRef = useRef<ReadonlyMap<string, ProjectEntry["kind"]>>(entryKinds);
   const treePaths = useMemo(() => entries.map(treePath), [entries]);
   const previousTreePathsRef = useRef<readonly string[]>([]);
+  const syncingSelectionRef = useRef(false);
+  const treeSelectionPathRef = useRef<string | null>(null);
+  const handledRevealRef = useRef<{ path: string; revealId: number } | null>(null);
 
   // The tree renders rows in shadow DOM and its anchor rect is unreliable, so
   // capture the right-click position ourselves; contextmenu is a composed
@@ -216,7 +225,12 @@ export default function FileBrowserPanel({
     initialExpansion: 1,
     icons: T3_PIERRE_ICONS,
     onSelectionChange: (selectedPaths) => {
+      // The drag controller's selection cache must track every change,
+      // including reveal-driven ones, or drags act on a stale selection.
       dragMention.handleSelectionChange(selectedPaths);
+      // Selection changes driven by the reveal sync below are echoes of an
+      // already-open file, not a request to open it again.
+      if (syncingSelectionRef.current) return;
       // Starting a drag selects the dragged row; that selection is a side
       // effect of the gesture, not a request to open the file.
       if (dragMention.isDragInProgress()) {
@@ -224,6 +238,7 @@ export default function FileBrowserPanel({
       }
       const selectedPath = selectedPaths.at(-1)?.replace(/\/$/, "");
       if (selectedPath && entryKindsRef.current.get(selectedPath) === "file") {
+        treeSelectionPathRef.current = selectedPath;
         onOpenFile(selectedPath);
       }
     },
@@ -247,6 +262,63 @@ export default function FileBrowserPanel({
     model.resetPaths(treePaths);
   }, [entryKinds, model, treePaths]);
 
+  useEffect(() => {
+    if (!selectedPath) {
+      handledRevealRef.current = null;
+      return;
+    }
+    const revealRequest = { path: selectedPath, revealId: selectedPathRevealId };
+    const handledReveal = handledRevealRef.current;
+    // Entry refreshes rebuild treePaths while the same preview stays open.
+    // Replaying a handled reveal would close an active tree search and steal focus.
+    if (
+      handledReveal?.path === revealRequest.path &&
+      handledReveal.revealId === revealRequest.revealId
+    ) {
+      return;
+    }
+    if (entryKinds.get(selectedPath) !== "file") return;
+    const selectedItem = model.getItem(selectedPath);
+    if (!selectedItem) return;
+
+    // A selection that originated inside the tree (clicking a row, possibly
+    // in an active tree search) is already visible; re-revealing it would
+    // close the search and clobber the user's context. Only sync external
+    // opens (file picker, content search, chat links).
+    const selectedInTree = model
+      .getSelectedPaths()
+      .some((path) => path.replace(/\/$/, "") === selectedPath);
+    if (selectedInTree && treeSelectionPathRef.current === selectedPath) {
+      treeSelectionPathRef.current = null;
+      handledRevealRef.current = revealRequest;
+      return;
+    }
+    treeSelectionPathRef.current = null;
+    handledRevealRef.current = revealRequest;
+
+    syncingSelectionRef.current = true;
+    model.closeSearch();
+    for (const path of model.getSelectedPaths()) {
+      model.getItem(path)?.deselect();
+    }
+
+    // Directory rows are registered with a trailing slash (see treePath), so
+    // ancestor lookups must use the same form to expand them.
+    const segments = selectedPath.split("/");
+    let ancestorPath = "";
+    for (const segment of segments.slice(0, -1)) {
+      ancestorPath = ancestorPath ? `${ancestorPath}/${segment}` : segment;
+      const item = model.getItem(`${ancestorPath}/`) ?? model.getItem(ancestorPath);
+      if (item && "expand" in item) item.expand();
+    }
+
+    selectedItem.select();
+    model.scrollToPath(selectedPath, { focus: true, offset: "center" });
+    queueMicrotask(() => {
+      syncingSelectionRef.current = false;
+    });
+  }, [entryKinds, model, selectedPath, selectedPathRevealId, treePaths]);
+
   // Tag tree drags with the composer mention payload. The row is read from
   // the composed event path (the tree's shadow root is open), so this does
   // not depend on running after the tree's own dragstart handler; the drag
diff --git a/apps/web/src/components/files/FilePreviewPanel.tsx b/apps/web/src/components/files/FilePreviewPanel.tsx
index 24e63a6d8ea..a736cf96cd3 100644
--- a/apps/web/src/components/files/FilePreviewPanel.tsx
+++ b/apps/web/src/components/files/FilePreviewPanel.tsx
@@ -51,6 +51,7 @@ import {
   remapFileCommentAnnotations,
 } from "./fileCommentAnnotations";
 import { installFileEditorDismissal } from "./fileEditorDismissal";
+import { resolveCenteredFileLineScrollTop } from "./fileLineReveal";
 import { LocalCommentAnnotation } from "./LocalCommentAnnotation";
 import { projectFileCacheKey, projectFileEditorCacheKey } from "./fileContentRevision";
 import { fileBreadcrumbs } from "./filePath";
@@ -182,25 +183,53 @@ function updateFileLinkReveal(fileContainer: HTMLElement, line: number | null):
     ?.setAttribute(FILE_LINK_REVEAL_ATTRIBUTE, "");
 }
 
+/**
+ * Frames to keep retrying while the file contents or line metrics are not
+ * available yet (fresh mounts hydrate asynchronously).
+ */
+const REVEAL_MAX_ATTEMPTS = 30;
+/**
+ * After scrolling to the target, hold it for a short window so late
+ * programmatic scroll resets (editable-editor focus and state restoration)
+ * cannot silently snap the file back to the top. Real user input cancels the
+ * guard immediately.
+ */
+const REVEAL_GUARD_FRAMES = 20;
+const REVEAL_GUARD_TOLERANCE_PX = 2;
+
+interface FileRevealState {
+  frameId: number | null;
+  cancelGuard: (() => void) | null;
+  handledRequestId: number | null;
+  latestRequestId: number | null;
+}
+
 function useFileLineReveal(
   relativePath: string | null,
   revealLine: number | null,
   revealRequestId: number,
 ): FilePostRender {
-  const [handledRequestIdsByPath] = useState(() => new Map<string, number>());
-  const [latestRequestIdsByPath] = useState(() => new Map<string, number>());
-  const [pendingFramesByPath] = useState(() => new Map<string, number>());
+  const [revealStatesByPath] = useState(() => new Map<string, FileRevealState>());
 
   return useCallback<FilePostRender>(
     (fileContainer, instance, phase) => {
       if (relativePath === null) return;
 
+      const existingState = revealStatesByPath.get(relativePath);
+      const state: FileRevealState = existingState ?? {
+        frameId: null,
+        cancelGuard: null,
+        handledRequestId: null,
+        latestRequestId: null,
+      };
+      if (!existingState) revealStatesByPath.set(relativePath, state);
+
       const cancelPendingReveal = () => {
-        const frameId = pendingFramesByPath.get(relativePath);
-        if (frameId !== undefined) {
-          cancelAnimationFrame(frameId);
-          pendingFramesByPath.delete(relativePath);
+        if (state.frameId !== null) {
+          cancelAnimationFrame(state.frameId);
+          state.frameId = null;
         }
+        state.cancelGuard?.();
       };
 
       if (phase === "unmount") {
@@ -208,18 +237,20 @@ function useFileLineReveal(
         return;
       }
 
+      const contents = instance.file?.contents;
       const targetLine =
-        revealLine === null ? null : clampFileLine(instance.file?.contents ?? "", revealLine);
+        revealLine === null || contents === undefined ? null : clampFileLine(contents, revealLine);
       updateFileLinkReveal(fileContainer, targetLine);
 
       if (!(instance instanceof VirtualizedFile)) return;
 
-      if (latestRequestIdsByPath.get(relativePath) !== revealRequestId) {
+      if (state.latestRequestId !== revealRequestId) {
         cancelPendingReveal();
-        latestRequestIdsByPath.set(relativePath, revealRequestId);
+        state.latestRequestId = revealRequestId;
+        state.handledRequestId = null;
       }
 
-      if (targetLine === null) {
+      if (revealLine === null) {
         fileContainer.style.minHeight = "";
         return;
       }
@@ -230,54 +261,113 @@ function useFileLineReveal(
         Math.max(instance.height, scrollContainer.clientHeight),
       )}px`;
 
-      if (
-        handledRequestIdsByPath.get(relativePath) === revealRequestId ||
-        pendingFramesByPath.has(relativePath)
-      ) {
+      if (state.handledRequestId === revealRequestId || state.frameId !== null) {
         return;
       }
 
-      const reveal = () => {
-        pendingFramesByPath.delete(relativePath);
-        if (
-          latestRequestIdsByPath.get(relativePath) !== revealRequestId ||
-          !fileContainer.isConnected
-        ) {
-          return;
-        }
-
-        const linePosition = instance.getLinePosition(targetLine);
-        if (!linePosition) return;
+      const resolveScrollTarget = (line: number): number | null => {
+        const linePosition = instance.getLinePosition(line);
+        if (!linePosition) return null;
 
+        const scrollContainerRect = scrollContainer.getBoundingClientRect();
         const fileTop =
           scrollContainer.scrollTop +
           fileContainer.getBoundingClientRect().top -
-          scrollContainer.getBoundingClientRect().top;
-        const centeredTop = Math.max(
-          0,
-          fileTop +
-            linePosition.top -
-            Math.max(0, (scrollContainer.clientHeight - linePosition.height) / 2),
-        );
-        const maxScrollTop = Math.max(
-          0,
-          scrollContainer.scrollHeight - scrollContainer.clientHeight,
-        );
+          scrollContainerRect.top;
+        const root = fileContainer.shadowRoot ?? fileContainer;
+        const renderedLineElement = root.querySelector<HTMLElement>(`[data-line="${line}"]`);
+        const renderedLineRect = renderedLineElement?.getBoundingClientRect();
 
-        scrollContainer.scrollTop = Math.min(centeredTop, maxScrollTop);
-        handledRequestIdsByPath.set(relativePath, revealRequestId);
+        return resolveCenteredFileLineScrollTop({
+          scrollTop: scrollContainer.scrollTop,
+          scrollHeight: scrollContainer.scrollHeight,
+          viewportTop: scrollContainerRect.top,
+          viewportHeight: scrollContainer.clientHeight,
+          fileTop,
+          estimatedLine: linePosition,
+          ...(renderedLineRect && renderedLineRect.height > 0
+            ? {
+                renderedLine: {
+                  top: renderedLineRect.top,
+                  height: renderedLineRect.height,
+                },
+              }
+            : {}),
+        });
       };
 
-      pendingFramesByPath.set(relativePath, requestAnimationFrame(reveal));
+      const guardScrollTarget = (line: number) => {
+        let framesLeft = REVEAL_GUARD_FRAMES;
+        let guardFrameId: number | null = null;
+        const cancelGuard = () => {
+          if (guardFrameId !== null) {
+            cancelAnimationFrame(guardFrameId);
+            guardFrameId = null;
+          }
+          scrollContainer.removeEventListener("wheel", cancelGuard);
+          scrollContainer.removeEventListener("touchstart", cancelGuard);
+          scrollContainer.removeEventListener("pointerdown", cancelGuard, true);
+          window.removeEventListener("keydown", cancelGuard, true);
+          if (state.cancelGuard === cancelGuard) state.cancelGuard = null;
+        };
+        scrollContainer.addEventListener("wheel", cancelGuard, { passive: true });
+        scrollContainer.addEventListener("touchstart", cancelGuard, { passive: true });
+        // Pierre stops gutter pointer events from bubbling. Listen in capture
+        // so starting a comment cancels the reveal guard before the row expands.
+        scrollContainer.addEventListener("pointerdown", cancelGuard, {
+          passive: true,
+          capture: true,
+        });
+        window.addEventListener("keydown", cancelGuard, true);
+        const holdTarget = () => {
+          guardFrameId = null;
+          framesLeft -= 1;
+          if (framesLeft <= 0 || !scrollContainer.isConnected) {
+            cancelGuard();
+            return;
+          }
+          const targetTop = resolveScrollTarget(line);
+          if (
+            targetTop !== null &&
+            Math.abs(scrollContainer.scrollTop - targetTop) > REVEAL_GUARD_TOLERANCE_PX
+          ) {
+            scrollContainer.scrollTop = targetTop;
+          }
+          guardFrameId = requestAnimationFrame(holdTarget);
+        };
+        guardFrameId = requestAnimationFrame(holdTarget);
+        state.cancelGuard = cancelGuard;
+      };
+
+      const scheduleReveal = (attempt: number) => {
+        state.frameId = requestAnimationFrame(() => {
+          state.frameId = null;
+          if (state.latestRequestId !== revealRequestId || !fileContainer.isConnected) {
+            return;
+          }
+
+          // Contents and line metrics can lag the first post-render on fresh
+          // mounts; clamping against missing contents would scroll to line 1
+          // and wrongly mark the request handled.
+          const currentContents = instance.file?.contents;
+          const line =
+            currentContents === undefined ? null : clampFileLine(currentContents, revealLine);
+          const targetTop = line === null ? null : resolveScrollTarget(line);
+          if (line === null || targetTop === null) {
+            if (attempt < REVEAL_MAX_ATTEMPTS) scheduleReveal(attempt + 1);
+            return;
+          }
+          updateFileLinkReveal(fileContainer, line);
+
+          scrollContainer.scrollTop = targetTop;
+          state.handledRequestId = revealRequestId;
+          guardScrollTarget(line);
+        });
+      };
+
+      scheduleReveal(0);
     },
-    [
-      handledRequestIdsByPath,
-      latestRequestIdsByPath,
-      pendingFramesByPath,
-      relativePath,
-      revealLine,
-      revealRequestId,
-    ],
+    [revealStatesByPath, relativePath, revealLine, revealRequestId],
   );
 }
 
@@ -963,6 +1053,8 @@ export default function FilePreviewPanel({
               environmentId={environmentId}
               cwd={cwd}
               projectName={projectName}
+              selectedPath={relativePath}
+              selectedPathRevealId={revealRequestId}
               onOpenFile={onOpenFile}
             />
           </aside>
diff --git a/apps/web/src/components/files/ProjectFilePicker.logic.test.ts b/apps/web/src/components/files/ProjectFilePicker.logic.test.ts
new file mode 100644
index 00000000000..2693ac9a072
--- /dev/null
+++ b/apps/web/src/components/files/ProjectFilePicker.logic.test.ts
@@ -0,0 +1,83 @@
+import { assert, describe, it } from "vite-plus/test";
+
+import { getProjectFilePickerMatches } from "./ProjectFilePicker.logic";
+
+function pathsForQuery(entries: Parameters<typeof getProjectFilePickerMatches>[0], query: string) {
+  return getProjectFilePickerMatches(entries, query).map(({ name, path }) => ({ name, path }));
+}
+
+const entries = [
+  { kind: "directory", path: "apps/web/src" },
+  { kind: "file", path: "apps/web/src/index.ts" },
+  { kind: "file", path: "packages/shared/src/index.ts" },
+  { kind: "file", path: "README.md" },
+  { kind: "file", path: ".gitignore" },
+] as const;
+
+describe("getProjectFilePickerMatches", () => {
+  it("returns files only and preserves index order for an empty query", () => {
+    assert.deepEqual(pathsForQuery(entries, ""), [
+      { name: "index.ts", path: "apps/web/src/index.ts" },
+      { name: "index.ts", path: "packages/shared/src/index.ts" },
+      { name: "README.md", path: "README.md" },
+      { name: ".gitignore", path: ".gitignore" },
+    ]);
+  });
+
+  it("preserves the server result order", () => {
+    assert.deepEqual(pathsForQuery(entries, "index"), [
+      { name: "index.ts", path: "apps/web/src/index.ts" },
+      { name: "index.ts", path: "packages/shared/src/index.ts" },
+      { name: "README.md", path: "README.md" },
+      { name: ".gitignore", path: ".gitignore" },
+    ]);
+  });
+
+  it("supports space-separated path tokens and a result limit", () => {
+    assert.deepEqual(
+      getProjectFilePickerMatches(entries, "src index", 1).map(({ name, path }) => ({
+        name,
+        path,
+      })),
+      [{ name: "index.ts", path: "apps/web/src/index.ts" }],
+    );
+  });
+
+  it("matches ordered characters while allowing skipped characters", () => {
+    const fuzzyEntries = [
+      { kind: "file", path: "src/TestFlags.tsx" },
+      { kind: "file", path: "src/SubtestFlow.tsx" },
+      { kind: "file", path: "src/useSubtestFlags.ts" },
+      {
+        kind: "file",
+        path: "src/useSubtestFlags/useTabActivity.ts",
+      },
+    ] as const;
+
+    assert.deepEqual(
+      pathsForQuery(fuzzyEntries, "testf").map(({ name }) => name),
+      ["TestFlags.tsx", "SubtestFlow.tsx", "useSubtestFlags.ts", "useTabActivity.ts"],
+    );
+    assert.deepEqual(getProjectFilePickerMatches(fuzzyEntries, "tsfl")[0], {
+      name: "TestFlags.tsx",
+      nameMatchIndices: [0, 2, 4, 5],
+      path: "src/TestFlags.tsx",
+      pathMatchIndices: [4, 6, 8, 9],
+    });
+  });
+
+  it("uses the first ordered subsequence for highlighting", () => {
+    assert.deepEqual(
+      getProjectFilePickerMatches([{ kind: "file", path: "aabba" }], "aba")[0]?.nameMatchIndices,
+      [0, 2, 4],
+    );
+  });
+
+  it("normalizes path prefixes consistently with server search", () => {
+    assert.deepEqual(
+      getProjectFilePickerMatches([{ kind: "file", path: "src/index.ts" }], "@/src")[0]
+        ?.pathMatchIndices,
+      [0, 1, 2],
+    );
+  });
+});
diff --git a/apps/web/src/components/files/ProjectFilePicker.logic.ts b/apps/web/src/components/files/ProjectFilePicker.logic.ts
new file mode 100644
index 00000000000..048c5373425
--- /dev/null
+++ b/apps/web/src/components/files/ProjectFilePicker.logic.ts
@@ -0,0 +1,73 @@
+import type { ProjectEntry } from "@t3tools/contracts";
+import { normalizeSearchQuery } from "@t3tools/shared/searchRanking";
+
+export const PROJECT_FILE_PICKER_RESULT_LIMIT = 200;
+
+export interface ProjectFilePickerMatch {
+  readonly name: string;
+  readonly nameMatchIndices: ReadonlyArray<number>;
+  readonly path: string;
+  readonly pathMatchIndices: ReadonlyArray<number>;
+}
+
+function fileName(path: string): string {
+  return path.slice(path.lastIndexOf("/") + 1);
+}
+
+/**
+ * First ordered subsequence of `query` inside `value`, as highlight indices.
+ * Returns null when `value` does not contain the subsequence at all — the
+ * entry still renders (the server matched it), just without highlights.
+ */
+function findMatchIndices(value: string, query: string): number[] | null {
+  if (!query) return [];
+
+  const normalizedValue = value.toLowerCase();
+  const indices: number[] = [];
+  let queryIndex = 0;
+
+  for (let valueIndex = 0; valueIndex < normalizedValue.length; valueIndex += 1) {
+    if (normalizedValue[valueIndex] !== query[queryIndex]) continue;
+    indices.push(valueIndex);
+    queryIndex += 1;
+    if (queryIndex === query.length) return indices;
+  }
+
+  return null;
+}
+
+/**
+ * Maps server search results to picker rows. Server ordering is preserved —
+ * ranking already happened there; this pass only filters to files and
+ * computes highlight positions with the same query normalization the server
+ * applied.
+ */
+export function getProjectFilePickerMatches(
+  entries: ReadonlyArray<ProjectEntry>,
+  rawQuery: string,
+  limit = PROJECT_FILE_PICKER_RESULT_LIMIT,
+): ProjectFilePickerMatch[] {
+  if (limit <= 0) return [];
+
+  const query = normalizeSearchQuery(rawQuery, {
+    trimLeadingPattern: /^[@./]+/,
+  }).replaceAll(/\s/g, "");
+  const matches: ProjectFilePickerMatch[] = [];
+
+  for (const entry of entries) {
+    if (entry.kind !== "file") continue;
+
+    const name = fileName(entry.path);
+    const nameMatchIndices = findMatchIndices(name, query);
+    const pathMatchIndices = findMatchIndices(entry.path, query);
+    matches.push({
+      name,
+      nameMatchIndices: nameMatchIndices ?? [],
+      path: entry.path,
+      pathMatchIndices: pathMatchIndices ?? [],
+    });
+    if (matches.length >= limit) break;
+  }
+
+  return matches;
+}
diff --git a/apps/web/src/components/files/ProjectFilePicker.tsx b/apps/web/src/components/files/ProjectFilePicker.tsx
new file mode 100644
index 00000000000..a59e8dd77e4
--- /dev/null
+++ b/apps/web/src/components/files/ProjectFilePicker.tsx
@@ -0,0 +1,163 @@
+import { useAtomValue } from "@effect/atom-react";
+import { useMemo, useState, type ReactNode } from "react";
+
+import { useActiveProjectTarget, type ActiveProjectTarget } from "~/hooks/useActiveProjectTarget";
+import { useTheme } from "~/hooks/useTheme";
+import { useRightPanelStore } from "~/rightPanelStore";
+import { primaryServerKeybindingsAtom } from "~/state/server";
+
+import { PierreEntryIcon } from "../chat/PierreEntryIcon";
+import { CommandPaletteContent } from "../CommandPaletteContent";
+import { type CommandPaletteActionItem } from "../CommandPalette.logic";
+import { CommandPaletteResults } from "../CommandPaletteResults";
+import {
+  getProjectFilePickerMatches,
+  PROJECT_FILE_PICKER_RESULT_LIMIT,
+} from "./ProjectFilePicker.logic";
+import { useProjectFilePickerQuery } from "./projectFilesQueryState";
+
+interface ProjectFilePickerProps {
+  readonly setOpen: (open: boolean) => void;
+}
+
+function HighlightedFuzzyText(props: {
+  readonly active: boolean;
+  readonly indices: ReadonlyArray<number>;
+  readonly value: string;
+}) {
+  if (!props.active) return props.value;
+
+  const parts: ReactNode[] = [];
+  let start = 0;
+  for (const index of props.indices) {
+    if (start < index) parts.push(props.value.slice(start, index));
+    parts.push(
+      <strong className="font-semibold text-foreground" key={index}>
+        {props.value[index]}
+      </strong>,
+    );
+    start = index + 1;
+  }
+  if (start < props.value.length) parts.push(props.value.slice(start));
+
+  return <span className="text-muted-foreground">{parts}</span>;
+}
+
+function getEmptyStateMessage(query: string, error: string | null, isPending: boolean): string {
+  if (error) return error;
+  const isSearching = query.trim().length > 0;
+  if (isPending) return isSearching ? "Searching workspace files…" : "Indexing workspace files…";
+  return isSearching ? "No matching files." : "No files found.";
+}
+
+function EmptyProjectFilePicker() {
+  return (
+    <CommandPaletteContent
+      aria-label="File picker"
+      escapeLabel="Back"
+      footerActionLabel="Open file"
+      inputProps={{ disabled: true, placeholder: "Search files…" }}
+      mode="none"
+      testId="project-file-picker"
+      value=""
+    >
+      <div className="py-10 text-center text-sm text-muted-foreground">
+        Open a project to search its files.
+      </div>
+    </CommandPaletteContent>
+  );
+}
+
+function OpenProjectFilePicker(props: ProjectFilePickerProps & { target: ActiveProjectTarget }) {
+  const { target } = props;
+  const [query, setQuery] = useState("");
+  const [highlightedItemValue, setHighlightedItemValue] = useState<string | null>(null);
+  const result = useProjectFilePickerQuery(
+    target.environmentId,
+    target.cwd,
+    query,
+    PROJECT_FILE_PICKER_RESULT_LIMIT,
+  );
+  const { resolvedTheme } = useTheme();
+  const keybindings = useAtomValue(primaryServerKeybindingsAtom);
+  const matches = useMemo(
+    () => getProjectFilePickerMatches(result.entries, result.matchedQuery),
+    [result.entries, result.matchedQuery],
+  );
+  const hasMatchedQuery = /\S/.test(result.matchedQuery);
+  const items = useMemo<CommandPaletteActionItem[]>(
+    () =>
+      matches.map((match) => ({
+        kind: "action",
+        value: `file:${match.path}`,
+        searchTerms: [match.name, match.path],
+        title: (
+          <HighlightedFuzzyText
+            active={hasMatchedQuery}
+            value={match.name}
+            indices={match.nameMatchIndices}
+          />
+        ),
+        description: (
+          <HighlightedFuzzyText
+            active={hasMatchedQuery}
+            value={match.path}
+            indices={match.pathMatchIndices}
+          />
+        ),
+        icon: <PierreEntryIcon pathValue={match.path} kind="file" theme={resolvedTheme} />,
+        run: async () => {
+          useRightPanelStore.getState().openFile(target.threadRef, match.path);
+        },
+      })),
+    [hasMatchedQuery, matches, resolvedTheme, target.threadRef],
+  );
+
+  const emptyStateMessage = getEmptyStateMessage(query, result.error, result.isPending);
+
+  return (
+    <CommandPaletteContent
+      aria-label="File picker"
+      autoHighlight="always"
+      escapeLabel="Back"
+      footerActionLabel="Open file"
+      inputProps={{ placeholder: "Search files…" }}
+      mode="none"
+      onItemHighlighted={(value) => {
+        setHighlightedItemValue(typeof value === "string" ? value : null);
+      }}
+      onValueChange={(value) => {
+        setHighlightedItemValue(null);
+        setQuery(value);
+      }}
+      panelClassName="max-h-[min(34rem,76vh)]"
+      testId="project-file-picker"
+      value={query}
+    >
+      <CommandPaletteResults
+        groups={
+          items.length > 0 ? [{ value: "project-files", label: target.projectName, items }] : []
+        }
+        highlightedItemValue={highlightedItemValue}
+        isActionsOnly={false}
+        keybindings={keybindings}
+        onExecuteItem={(item) => {
+          if (item.kind !== "action") return;
+          props.setOpen(false);
+          void item.run();
+        }}
+        emptyStateMessage={emptyStateMessage}
+      />
+    </CommandPaletteContent>
+  );
+}
+
+export function ProjectFilePicker(props: ProjectFilePickerProps) {
+  const target = useActiveProjectTarget();
+
+  if (!target) {
+    return <EmptyProjectFilePicker />;
+  }
+
+  return <OpenProjectFilePicker setOpen={props.setOpen} target={target} />;
+}
diff --git a/apps/web/src/components/files/fileLineReveal.test.ts b/apps/web/src/components/files/fileLineReveal.test.ts
new file mode 100644
index 00000000000..3a63168d5d3
--- /dev/null
+++ b/apps/web/src/components/files/fileLineReveal.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { resolveCenteredFileLineScrollTop } from "./fileLineReveal";
+
+describe("resolveCenteredFileLineScrollTop", () => {
+  it("centers an estimated virtualized line position", () => {
+    expect(
+      resolveCenteredFileLineScrollTop({
+        scrollTop: 0,
+        scrollHeight: 2_000,
+        viewportTop: 100,
+        viewportHeight: 400,
+        fileTop: 20,
+        estimatedLine: { top: 1_000, height: 20 },
+      }),
+    ).toBe(830);
+  });
+
+  it("corrects a stale estimate from the rendered line geometry", () => {
+    expect(
+      resolveCenteredFileLineScrollTop({
+        scrollTop: 830,
+        scrollHeight: 2_000,
+        viewportTop: 100,
+        viewportHeight: 400,
+        fileTop: 20,
+        estimatedLine: { top: 1_000, height: 20 },
+        renderedLine: { top: 620, height: 20 },
+      }),
+    ).toBe(1_160);
+  });
+});
diff --git a/apps/web/src/components/files/fileLineReveal.ts b/apps/web/src/components/files/fileLineReveal.ts
new file mode 100644
index 00000000000..fd066ae205b
--- /dev/null
+++ b/apps/web/src/components/files/fileLineReveal.ts
@@ -0,0 +1,24 @@
+interface LineGeometry {
+  readonly top: number;
+  readonly height: number;
+}
+
+interface CenteredFileLineScrollInput {
+  readonly scrollTop: number;
+  readonly scrollHeight: number;
+  readonly viewportTop: number;
+  readonly viewportHeight: number;
+  readonly fileTop: number;
+  readonly estimatedLine: LineGeometry;
+  readonly renderedLine?: LineGeometry;
+}
+
+export function resolveCenteredFileLineScrollTop(input: CenteredFileLineScrollInput): number {
+  const lineTop =
+    input.renderedLine === undefined
+      ? input.fileTop + input.estimatedLine.top
+      : input.scrollTop + input.renderedLine.top - input.viewportTop;
+  const lineHeight = input.renderedLine?.height ?? input.estimatedLine.height;
+  const centeredTop = Math.max(0, lineTop - Math.max(0, (input.viewportHeight - lineHeight) / 2));
+  return Math.min(centeredTop, Math.max(0, input.scrollHeight - input.viewportHeight));
+}
diff --git a/apps/web/src/components/files/projectFilesQueryState.ts b/apps/web/src/components/files/projectFilesQueryState.ts
index 0d3fb8dd941..d165c1d1a7a 100644
--- a/apps/web/src/components/files/projectFilesQueryState.ts
+++ b/apps/web/src/components/files/projectFilesQueryState.ts
@@ -11,6 +11,7 @@ import { useCallback } from "react";
 
 import { appAtomRegistry } from "~/rpc/atomRegistry";
 import { projectEnvironment } from "~/state/projects";
+import { useProjectPathSearch } from "~/state/queries";
 import { executeAtomQuery } from "@t3tools/client-runtime/state/runtime";
 
 const EMPTY_PROJECT_FILE_PATH = "";
@@ -136,6 +137,32 @@ export function useProjectEntriesQuery(
   };
 }
 
+/**
+ * Backing query for the project file picker: a debounced, bounded, file-only
+ * server search. An empty query is a valid request — the index answers it
+ * with frecency-ordered files, so the picker's initial view is recent files
+ * without transferring the full workspace listing. `matchedQuery` is the
+ * query the returned entries were computed for, so the caller can highlight
+ * against results instead of half-typed input.
+ */
+export function useProjectFilePickerQuery(
+  environmentId: EnvironmentId,
+  cwd: string,
+  query: string,
+  limit: number,
+) {
+  const search = useProjectPathSearch({ environmentId, cwd, query, kind: "file" }, limit, {
+    allowEmptyQuery: true,
+  });
+
+  return {
+    entries: search.isPending ? [] : search.entries,
+    error: search.error,
+    isPending: search.isPending,
+    matchedQuery: search.searchedQuery,
+  };
+}
+
 export function useProjectFileQuery(
   environmentId: EnvironmentId,
   cwd: string,
diff --git a/apps/web/src/components/search/HighlightedSearchLine.tsx b/apps/web/src/components/search/HighlightedSearchLine.tsx
new file mode 100644
index 00000000000..9d529622776
--- /dev/null
+++ b/apps/web/src/components/search/HighlightedSearchLine.tsx
@@ -0,0 +1,183 @@
+import { getFiletypeFromFileName } from "@pierre/diffs";
+import type { ProjectContentMatch } from "@t3tools/contracts";
+import { memo, Suspense, use, useMemo, type CSSProperties } from "react";
+
+import { resolveDiffThemeName } from "~/lib/diffRendering";
+import { getSyntaxHighlighterPromise } from "~/lib/syntaxHighlighting";
+
+import { RenderErrorBoundary } from "../RenderErrorBoundary";
+
+interface Range {
+  readonly start: number;
+  readonly end: number;
+}
+
+interface CodeToken {
+  readonly content: string;
+  readonly offset: number;
+  readonly color?: string;
+  readonly fontStyle?: number;
+}
+
+interface Segment {
+  readonly content: string;
+  readonly isMatch: boolean;
+  readonly start: number;
+  readonly end: number;
+  readonly token: CodeToken;
+}
+
+function normalizeRanges(match: ProjectContentMatch): Range[] {
+  const ranges = match.matchRanges
+    .map((range) => ({
+      start: Math.max(0, Math.min(match.lineContent.length, range.start)),
+      end: Math.max(0, Math.min(match.lineContent.length, range.end)),
+    }))
+    .filter((range) => range.end > range.start)
+    .toSorted((left, right) => left.start - right.start);
+
+  const merged: Array<{ start: number; end: number }> = [];
+  for (const range of ranges) {
+    const previous = merged.at(-1);
+    if (previous && range.start <= previous.end) {
+      previous.end = Math.max(previous.end, range.end);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+}
+
+function splitToken(line: string, token: CodeToken, ranges: ReadonlyArray<Range>): Segment[] {
+  const segments: Segment[] = [];
+  const tokenEnd = token.offset + token.content.length;
+  let cursor = token.offset;
+
+  for (const range of ranges) {
+    if (range.end <= cursor) continue;
+    if (range.start >= tokenEnd) break;
+
+    const matchStart = Math.max(cursor, range.start);
+    if (matchStart > cursor) {
+      segments.push({
+        content: line.slice(cursor, matchStart),
+        isMatch: false,
+        start: cursor,
+        end: matchStart,
+        token,
+      });
+    }
+
+    const matchEnd = Math.min(tokenEnd, range.end);
+    segments.push({
+      content: line.slice(matchStart, matchEnd),
+      isMatch: true,
+      start: matchStart,
+      end: matchEnd,
+      token,
+    });
+    cursor = matchEnd;
+  }
+
+  if (cursor < tokenEnd) {
+    segments.push({
+      content: line.slice(cursor, tokenEnd),
+      isMatch: false,
+      start: cursor,
+      end: tokenEnd,
+      token,
+    });
+  }
+  return segments;
+}
+
+function tokenStyle(token: CodeToken): CSSProperties {
+  const fontStyle = token.fontStyle ?? 0;
+  return {
+    ...(token.color ? { color: token.color } : {}),
+    ...(fontStyle & 1 ? { fontStyle: "italic" } : {}),
+    ...(fontStyle & 2 ? { fontWeight: 700 } : {}),
+    ...(fontStyle & 4 ? { textDecoration: "underline" } : {}),
+  };
+}
+
+function HighlightedTokens(props: {
+  readonly line: string;
+  readonly ranges: ReadonlyArray<Range>;
+  readonly tokens: ReadonlyArray<CodeToken>;
+}) {
+  return props.tokens
+    .flatMap((token) => splitToken(props.line, token, props.ranges))
+    .map((segment) =>
+      segment.isMatch ? (
+        <mark
+          className="rounded-[2px] bg-primary/25 text-inherit"
+          key={`${segment.start}:${segment.end}:match`}
+          style={tokenStyle(segment.token)}
+        >
+          {segment.content}
+        </mark>
+      ) : (
+        <span key={`${segment.start}:${segment.end}:code`} style={tokenStyle(segment.token)}>
+          {segment.content}
+        </span>
+      ),
+    );
+}
+
+function SyntaxHighlightedTokens(props: {
+  readonly line: string;
+  readonly language: string;
+  readonly ranges: ReadonlyArray<Range>;
+  readonly theme: "light" | "dark";
+}) {
+  const highlighter = use(getSyntaxHighlighterPromise(props.language));
+  const tokens = useMemo(() => {
+    try {
+      return highlighter.codeToTokens(props.line, {
+        lang: props.language,
+        theme: resolveDiffThemeName(props.theme),
+      }).tokens[0];
+    } catch {
+      return undefined;
+    }
+  }, [highlighter, props.language, props.line, props.theme]);
+
+  return tokens ? (
+    <HighlightedTokens line={props.line} ranges={props.ranges} tokens={tokens} />
+  ) : (
+    <HighlightedTokens
+      line={props.line}
+      ranges={props.ranges}
+      tokens={[{ content: props.line, offset: 0 }]}
+    />
+  );
+}
+
+export const HighlightedSearchLine = memo(function HighlightedSearchLine(props: {
+  readonly match: ProjectContentMatch;
+  readonly path: string;
+  readonly theme: "light" | "dark";
+}) {
+  const ranges = useMemo(() => normalizeRanges(props.match), [props.match]);
+  const fallback = (
+    <HighlightedTokens
+      line={props.match.lineContent}
+      ranges={ranges}
+      tokens={[{ content: props.match.lineContent, offset: 0 }]}
+    />
+  );
+
+  return (
+    <RenderErrorBoundary fallback={fallback}>
+      <Suspense fallback={fallback}>
+        <SyntaxHighlightedTokens
+          line={props.match.lineContent}
+          language={getFiletypeFromFileName(props.path)}
+          ranges={ranges}
+          theme={props.theme}
+        />
+      </Suspense>
+    </RenderErrorBoundary>
+  );
+});
diff --git a/apps/web/src/components/search/ProjectContentSearchDialog.tsx b/apps/web/src/components/search/ProjectContentSearchDialog.tsx
new file mode 100644
index 00000000000..1890aab7fa7
--- /dev/null
+++ b/apps/web/src/components/search/ProjectContentSearchDialog.tsx
@@ -0,0 +1,315 @@
+import type { ProjectContentMatch } from "@t3tools/contracts";
+import { LoaderCircle } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+
+import { useActiveProjectTarget, type ActiveProjectTarget } from "~/hooks/useActiveProjectTarget";
+import { useTheme } from "~/hooks/useTheme";
+import { cn } from "~/lib/utils";
+import { useRightPanelStore } from "~/rightPanelStore";
+import { useProjectContentSearch } from "~/state/queries";
+
+import { PierreEntryIcon } from "../chat/PierreEntryIcon";
+import { CommandPaletteContent } from "../CommandPaletteContent";
+import { ScrollArea } from "../ui/scroll-area";
+import { HighlightedSearchLine } from "./HighlightedSearchLine";
+
+interface ProjectContentSearchDialogProps {
+  readonly onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Result rows are syntax highlighted, so mounting all 500 possible rows at
+ * once stalls the UI. Rows render in windows that grow as the sentinel at the
+ * bottom of the list scrolls into view (or keyboard navigation moves past
+ * the rendered window).
+ */
+const VISIBLE_MATCH_WINDOW = 100;
+
+interface MatchGroup {
+  readonly path: string;
+  readonly matches: ReadonlyArray<ProjectContentMatch & { readonly resultIndex: number }>;
+}
+
+function splitPath(path: string): { readonly name: string; readonly directory: string } {
+  const separator = path.lastIndexOf("/");
+  return separator === -1
+    ? { name: path, directory: "" }
+    : { name: path.slice(separator + 1), directory: path.slice(0, separator) };
+}
+
+function groupMatches(matches: ReadonlyArray<ProjectContentMatch>): MatchGroup[] {
+  const groups = new Map<string, Array<ProjectContentMatch & { readonly resultIndex: number }>>();
+  matches.forEach((match, resultIndex) => {
+    const group = groups.get(match.path);
+    const indexedMatch = { ...match, resultIndex };
+    if (group) {
+      group.push(indexedMatch);
+    } else {
+      groups.set(match.path, [indexedMatch]);
+    }
+  });
+  return [...groups].map(([path, groupedMatches]) => ({ path, matches: groupedMatches }));
+}
+
+function SearchOptionButton(props: {
+  readonly active: boolean;
+  readonly label: string;
+  readonly onClick: () => void;
+  readonly children: ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      aria-label={props.label}
+      aria-pressed={props.active}
+      title={props.label}
+      className={cn(
+        "flex size-8 shrink-0 items-center justify-center rounded-[5px] font-mono text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground",
+        props.active && "bg-accent text-foreground shadow-sm",
+      )}
+      onClick={props.onClick}
+    >
+      {props.children}
+    </button>
+  );
+}
+
+function EmptyContentSearchDialog() {
+  return (
+    <CommandPaletteContent
+      aria-label="Search project contents"
+      escapeLabel="Back"
+      footerActionLabel="Open file"
+      inputProps={{ disabled: true, placeholder: "Search project contents…" }}
+      mode="none"
+      panelClassName="flex min-h-0 flex-1 items-center justify-center px-6 text-center text-sm text-muted-foreground"
+      testId="project-content-search"
+      value=""
+    >
+      Open a project to search its files.
+    </CommandPaletteContent>
+  );
+}
+
+function OpenContentSearchDialog(props: {
+  readonly onOpenChange: (open: boolean) => void;
+  readonly target: ActiveProjectTarget;
+}) {
+  const { target } = props;
+  const { resolvedTheme } = useTheme();
+  const [query, setQuery] = useState("");
+  const [caseSensitive, setCaseSensitive] = useState(false);
+  const [wholeWord, setWholeWord] = useState(false);
+  const [useRegex, setUseRegex] = useState(false);
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  const [visibleCount, setVisibleCount] = useState(VISIBLE_MATCH_WINDOW);
+
+  const search = useProjectContentSearch({
+    environmentId: target.environmentId,
+    cwd: target.cwd,
+    query,
+    caseSensitive,
+    wholeWord,
+    useRegex,
+  });
+  const canOpenMatches = !search.isPending;
+  const matches = search.matches;
+  const visibleMatches = useMemo(() => matches.slice(0, visibleCount), [matches, visibleCount]);
+  const groups = useMemo(() => groupMatches(visibleMatches), [visibleMatches]);
+
+  useEffect(() => {
+    setSelectedIndex(0);
+    setVisibleCount(VISIBLE_MATCH_WINDOW);
+  }, [matches]);
+
+  useEffect(() => {
+    if (selectedIndex >= visibleCount) {
+      setVisibleCount(selectedIndex + VISIBLE_MATCH_WINDOW);
+      return;
+    }
+    document
+      .querySelector<HTMLElement>(`[data-content-search-result="${selectedIndex}"]`)
+      ?.scrollIntoView({ block: "nearest" });
+  }, [selectedIndex, visibleCount]);
+
+  const observeLoadMoreSentinel = useCallback((sentinel: HTMLElement | null) => {
+    if (!sentinel) return;
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) {
+        setVisibleCount((current) => current + VISIBLE_MATCH_WINDOW);
+      }
+    });
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, []);
+
+  const openMatch = (match: ProjectContentMatch) => {
+    if (!canOpenMatches) return;
+    props.onOpenChange(false);
+    useRightPanelStore.getState().openFile(target.threadRef, match.path, match.lineNumber);
+  };
+  const fileCount = useMemo(() => new Set(matches.map((match) => match.path)).size, [matches]);
+  const showSearchStatus =
+    search.hasQuery || search.isPending || search.error !== null || search.invalidRegex;
+
+  return (
+    <CommandPaletteContent
+      aria-label={`Search file contents in ${target.projectName}`}
+      escapeLabel="Back"
+      footerActionLabel="Open file"
+      inputAccessory={
+        <div className="absolute inset-e-2.5 top-1/2 flex shrink-0 -translate-y-1/2 items-center gap-0.5 rounded-md border bg-muted/30 p-0.5">
+          <SearchOptionButton
+            active={caseSensitive}
+            label="Match case"
+            onClick={() => setCaseSensitive((current) => !current)}
+          >
+            Aa
+          </SearchOptionButton>
+          <SearchOptionButton
+            active={wholeWord}
+            label="Match whole word"
+            onClick={() => setWholeWord((current) => !current)}
+          >
+            <span className="underline decoration-2 underline-offset-2">ab</span>
+          </SearchOptionButton>
+          <SearchOptionButton
+            active={useRegex}
+            label="Use regular expression"
+            onClick={() => setUseRegex((current) => !current)}
+          >
+            .*
+          </SearchOptionButton>
+        </div>
+      }
+      inputProps={{
+        className: "pe-30",
+        placeholder: `Search in ${target.projectName}`,
+        onKeyDown: (event) => {
+          if (event.key === "ArrowDown" && matches.length > 0) {
+            event.preventDefault();
+            setSelectedIndex((current) => (current + 1) % matches.length);
+          } else if (event.key === "ArrowUp" && matches.length > 0) {
+            event.preventDefault();
+            setSelectedIndex((current) => (current - 1 + matches.length) % matches.length);
+          } else if (event.key === "Enter") {
+            // While a newer query is debouncing or in flight, the visible
+            // matches belong to the previous query; opening one would jump
+            // to a result the user did not ask for.
+            if (!canOpenMatches) {
+              event.preventDefault();
+              return;
+            }
+            const match = matches[selectedIndex];
+            if (match) {
+              event.preventDefault();
+              openMatch(match);
+            }
+          }
+        },
+      }}
+      mode="none"
+      onValueChange={setQuery}
+      panelClassName="flex min-h-0 flex-1 flex-col"
+      testId="project-content-search"
+      value={query}
+    >
+      {showSearchStatus ? (
+        <div className="flex h-9 shrink-0 items-center border-b px-3 text-xs text-muted-foreground">
+          {search.isPending ? (
+            <span className="flex items-center gap-2">
+              <LoaderCircle className="size-3.5 animate-spin" /> Searching…
+            </span>
+          ) : search.error ? (
+            <span className="text-destructive">{search.error}</span>
+          ) : search.invalidRegex ? (
+            <span className="text-destructive">Invalid regular expression</span>
+          ) : (
+            `${matches.length.toLocaleString()}${search.truncated ? "+" : ""} results in ${fileCount.toLocaleString()} files`
+          )}
+        </div>
+      ) : null}
+
+      {matches.length === 0 ? (
+        <div className="flex flex-1 items-center justify-center px-6 text-center text-sm text-muted-foreground">
+          {search.hasQuery && !search.isPending && !search.error
+            ? "No results found."
+            : "Type to search across your project."}
+        </div>
+      ) : (
+        <ScrollArea className="min-h-0 flex-1" scrollFade>
+          <div className="py-2">
+            {groups.map((group) => {
+              const path = splitPath(group.path);
+              return (
+                <section className="pb-2" key={group.path}>
+                  <div className="sticky top-0 z-10 flex h-8 items-center gap-2 bg-popover/95 px-3 text-xs backdrop-blur-sm">
+                    <PierreEntryIcon
+                      pathValue={group.path}
+                      kind="file"
+                      theme={resolvedTheme}
+                      className="size-3.5"
+                    />
+                    <span className="font-medium text-foreground">{path.name}</span>
+                    {path.directory ? (
+                      <span className="min-w-0 truncate text-muted-foreground">
+                        {path.directory}
+                      </span>
+                    ) : null}
+                    <span className="ml-auto rounded-full bg-muted px-1.5 py-0.5 tabular-nums text-[10px] text-muted-foreground">
+                      {group.matches.length}
+                    </span>
+                  </div>
+                  {group.matches.map((match) => (
+                    <button
+                      type="button"
+                      key={`${match.path}:${match.lineNumber}:${match.resultIndex}`}
+                      data-content-search-result={match.resultIndex}
+                      className={cn(
+                        "flex h-7 w-full min-w-0 items-center gap-3 px-3 text-left font-mono text-xs hover:bg-accent/60 disabled:pointer-events-none",
+                        match.resultIndex === selectedIndex && "bg-accent text-accent-foreground",
+                      )}
+                      disabled={!canOpenMatches}
+                      onMouseEnter={() => setSelectedIndex(match.resultIndex)}
+                      onClick={() => openMatch(match)}
+                    >
+                      <span className="w-10 shrink-0 text-right tabular-nums text-muted-foreground/70">
+                        {match.lineNumber}
+                      </span>
+                      <span className="min-w-0 flex-1 truncate whitespace-pre">
+                        <HighlightedSearchLine
+                          match={match}
+                          path={group.path}
+                          theme={resolvedTheme}
+                        />
+                      </span>
+                    </button>
+                  ))}
+                </section>
+              );
+            })}
+            {matches.length > visibleCount ? (
+              <div ref={observeLoadMoreSentinel} className="h-8" aria-hidden="true" />
+            ) : null}
+          </div>
+        </ScrollArea>
+      )}
+    </CommandPaletteContent>
+  );
+}
+
+export function ProjectContentSearchDialog(props: ProjectContentSearchDialogProps) {
+  const target = useActiveProjectTarget();
+
+  return target ? (
+    <OpenContentSearchDialog
+      // Reset the query and options whenever the workspace changes.
+      key={`${target.environmentId}:${target.cwd}`}
+      onOpenChange={props.onOpenChange}
+      target={target}
+    />
+  ) : (
+    <EmptyContentSearchDialog />
+  );
+}
diff --git a/apps/web/src/components/settings/BetaSettingsPanel.tsx b/apps/web/src/components/settings/BetaSettingsPanel.tsx
index 5a1ac036077..740d3048f0e 100644
--- a/apps/web/src/components/settings/BetaSettingsPanel.tsx
+++ b/apps/web/src/components/settings/BetaSettingsPanel.tsx
@@ -8,6 +8,7 @@ import {
 import { Input } from "../ui/input";
 import { Switch } from "../ui/switch";
 import { SettingsPageContainer, SettingsRow, SettingsSection } from "./settingsLayout";
+import { searchableSetting } from "./settingsSearch";
 
 const AUTO_SETTLE_MIN_DAYS = 1;
 const AUTO_SETTLE_MAX_DAYS = 90;
@@ -65,7 +66,7 @@ export function BetaSettingsPanel() {
     <SettingsPageContainer>
       <SettingsSection title="Beta features">
         <SettingsRow
-          title="Sidebar v2"
+          {...searchableSetting("sidebar-v2")}
           description="One flat thread list in creation order. Active work renders as rich cards; settled threads collapse to compact rows. Settling requires an up-to-date server — on older servers threads simply stay active. Switch back any time."
           control={
             <Switch
@@ -85,7 +86,7 @@ export function BetaSettingsPanel() {
         {sidebarV2Enabled ? (
           <>
             <SettingsRow
-              title="Auto-settle inactive threads"
+              title={searchableSetting("auto-settle-inactive-threads").title}
               description="Threads with no activity for this long settle automatically. Threads on merged or closed PRs always settle."
               control={
                 <Switch
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 98ab7a128de..640412e4a6d 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -49,6 +49,7 @@ import {
   SettingsSection,
   useRelativeTimeTick,
 } from "./settingsLayout";
+import { searchableSetting } from "./settingsSearch";
 import { Input } from "../ui/input";
 import { Checkbox } from "../ui/checkbox";
 import {
@@ -1434,7 +1435,6 @@ function SavedBackendListRow({
             <div className="max-w-md">
               <ServerUpdateProgress
                 fromVersion={serverUpdateState.fromVersion}
-                serverLabel={`${environment.label} server`}
                 state={serverUpdateState}
               />
             </div>
@@ -3011,7 +3011,6 @@ export function ConnectionsSettings() {
                   primaryServerUpdateState.status !== "idle" ? (
                     <ServerUpdateProgress
                       fromVersion={primaryServerUpdateState.fromVersion}
-                      serverLabel={primaryEnvironment?.label ?? "this server"}
                       state={primaryServerUpdateState}
                     />
                   ) : primaryVersionMismatch ? (
@@ -3353,7 +3352,7 @@ export function ConnectionsSettings() {
       )}
 
       <SettingsSection
-        title="Remote environments"
+        {...searchableSetting("remote-environments")}
         headerAction={
           <Dialog
             open={addBackendDialogOpen}
diff --git a/apps/web/src/components/settings/KeybindingsSettings.tsx b/apps/web/src/components/settings/KeybindingsSettings.tsx
index 67c33c9b942..edbd3f36a0c 100644
--- a/apps/web/src/components/settings/KeybindingsSettings.tsx
+++ b/apps/web/src/components/settings/KeybindingsSettings.tsx
@@ -70,6 +70,7 @@ import {
   whenAstToExpression,
 } from "./KeybindingsSettings.logic";
 import { SettingsPageContainer, SettingsSection } from "./settingsLayout";
+import { searchableSetting } from "./settingsSearch";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { useAtomCommand } from "../../state/use-atom-command";
 
@@ -1230,7 +1231,7 @@ export function KeybindingsSettingsPanel() {
   return (
     <SettingsPageContainer className="max-w-5xl">
       <SettingsSection
-        title="Keybindings"
+        {...searchableSetting("keybindings")}
         headerAction={
           <div className="flex items-center gap-1.5">
             <ExpandableHeaderSearch
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index eaf189b09b9..e1d42c1b4d8 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -139,6 +139,7 @@ import {
   SettingsSection,
   useRelativeTimeTick,
 } from "./settingsLayout";
+import { searchableSetting } from "./settingsSearch";
 import { ProjectFavicon } from "../ProjectFavicon";
 import { useAtomCommand } from "../../state/use-atom-command";
 
@@ -986,9 +987,9 @@ export function AppearanceSettingsPanel() {
 
   return (
     <SettingsPageContainer>
-      <SettingsSection title="Appearance">
+      <SettingsSection id="appearance" title="Appearance">
         <SettingsRow
-          title="Theme"
+          {...searchableSetting("theme")}
           description="Choose how T3 Code looks across the app."
           resetAction={
             /* fork:begin fork-cool-dark-theme — see .fork/customizations.yaml#fork-cool-dark-theme */
@@ -1032,7 +1033,7 @@ export function AppearanceSettingsPanel() {
         />
 
         <SettingsRow
-          title="Glass opacity"
+          {...searchableSetting("setting-glass-opacity")}
           description="Control how transparent glass surfaces are. Higher values make menus, dialogs, and the composer more solid."
           resetAction={
             settings.glassOpacity !== DEFAULT_UNIFIED_SETTINGS.glassOpacity ? (
@@ -1079,7 +1080,7 @@ export function AppearanceSettingsPanel() {
 
         {showEnvironmentIdentification ? (
           <SettingsRow
-            title="Environment identification"
+            {...searchableSetting("environment-identification")}
             description="Choose how Dev and Nightly environments are identified."
             resetAction={
               settings.environmentIdentificationMode !== DEFAULT_ENVIRONMENT_IDENTIFICATION_MODE ? (
@@ -1120,7 +1121,7 @@ export function AppearanceSettingsPanel() {
         ) : null}
 
         <SettingsRow
-          title="Word wrap"
+          {...searchableSetting("word-wrap")}
           description="Wrap long lines in code blocks, tables, diffs, and file previews by default."
           resetAction={
             settings.wordWrap !== DEFAULT_UNIFIED_SETTINGS.wordWrap ? (
@@ -1204,7 +1205,7 @@ export function GeneralSettingsPanel() {
     <SettingsPageContainer>
       <SettingsSection title="General">
         <SettingsRow
-          title="Project Grouping"
+          {...searchableSetting("project-grouping")}
           description="Combine matching repositories across environments."
           resetAction={
             settings.sidebarProjectGroupingMode !==
@@ -1234,13 +1235,13 @@ export function GeneralSettingsPanel() {
                   ),
                 });
               }}
-              aria-label="Project Grouping"
+              aria-label="Project grouping"
             />
           }
         />
 
         <SettingsRow
-          title="Time format"
+          {...searchableSetting("time-format")}
           description="System default follows your browser or OS clock preference."
           resetAction={
             settings.timestampFormat !== DEFAULT_UNIFIED_SETTINGS.timestampFormat ? (
@@ -1282,7 +1283,7 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="Hide whitespace changes"
+          {...searchableSetting("hide-whitespace-changes")}
           description="Set whether the diff panel ignores whitespace-only edits by default."
           resetAction={
             settings.diffIgnoreWhitespace !== DEFAULT_UNIFIED_SETTINGS.diffIgnoreWhitespace ? (
@@ -1308,7 +1309,7 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="Assistant output"
+          {...searchableSetting("assistant-output")}
           description="Show token-by-token output while a response is in progress."
           resetAction={
             settings.enableAssistantStreaming !==
@@ -1335,7 +1336,7 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="Provider update checks"
+          {...searchableSetting("provider-update-checks")}
           description="Check installed provider CLIs for newer available versions."
           resetAction={
             settings.enableProviderUpdateChecks !==
@@ -1444,7 +1445,7 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="Auto-open task panel"
+          {...searchableSetting("auto-open-task-panel")}
           description="Open the right-side plan and task panel automatically when steps appear."
           resetAction={
             settings.autoOpenPlanSidebar !== DEFAULT_UNIFIED_SETTINGS.autoOpenPlanSidebar ? (
@@ -1470,7 +1471,7 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="New threads"
+          {...searchableSetting("new-threads")}
           description="Pick the default workspace mode for newly created draft threads."
           resetAction={
             settings.defaultThreadEnvMode !== DEFAULT_UNIFIED_SETTINGS.defaultThreadEnvMode ||
@@ -1517,7 +1518,7 @@ export function GeneralSettingsPanel() {
         {settings.defaultThreadEnvMode === "worktree" ? (
           <SettingsRow
             className="bg-muted/20 sm:pl-9"
-            title="Start from origin"
+            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 !==
@@ -1546,7 +1547,7 @@ export function GeneralSettingsPanel() {
         ) : null}
 
         <SettingsRow
-          title="Add project starts in"
+          {...searchableSetting("add-project-starts-in")}
           description='Leave empty to use "~/" when the Add Project browser opens.'
           resetAction={
             settings.addProjectBaseDirectory !==
@@ -1574,7 +1575,7 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="Archive confirmation"
+          {...searchableSetting("archive-confirmation")}
           description="Require a second click on the inline archive action before a thread is archived."
           resetAction={
             settings.confirmThreadArchive !== DEFAULT_UNIFIED_SETTINGS.confirmThreadArchive ? (
@@ -1600,7 +1601,7 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="Delete confirmation"
+          {...searchableSetting("delete-confirmation")}
           description="Ask before deleting a thread and its chat history."
           resetAction={
             settings.confirmThreadDelete !== DEFAULT_UNIFIED_SETTINGS.confirmThreadDelete ? (
@@ -1626,7 +1627,7 @@ export function GeneralSettingsPanel() {
         />
 
         <SettingsRow
-          title="Text generation model"
+          {...searchableSetting("text-generation-model")}
           description="Default model for generated text like thread titles and source control content. Source control settings can override it with a dedicated source control writer model."
           resetAction={
             isTextGenerationModelDirty ? (
@@ -1710,7 +1711,7 @@ export function GeneralSettingsPanel() {
           />
         )}
         <SettingsRow
-          title="Diagnostics"
+          {...searchableSetting("diagnostics")}
           description={diagnosticsDescription}
           control={
             <Button render={<Link to="/settings/diagnostics" />} size="xs" variant="outline">
@@ -2025,7 +2026,7 @@ export function ProviderSettingsPanel() {
   return (
     <SettingsPageContainer>
       <SettingsSection
-        title="Providers"
+        {...searchableSetting("providers")}
         headerAction={
           <div className="flex items-center gap-1.5">
             <ProviderLastChecked lastCheckedAt={lastCheckedAt} />
@@ -2354,7 +2355,10 @@ export function ArchivedThreadsPanel() {
   return (
     <SettingsPageContainer>
       {archivedGroups.length === 0 ? (
-        <SettingsSection title="Archived threads">
+        <SettingsSection
+          id={isLoadingArchive ? undefined : searchableSetting("archive").id}
+          title={searchableSetting("archive").title}
+        >
           <SettingsRow
             title={
               <span className="inline-flex items-center gap-2">
@@ -2378,9 +2382,10 @@ export function ArchivedThreadsPanel() {
           />
         </SettingsSection>
       ) : (
-        archivedGroups.map(({ project, threads: projectThreads }) => (
+        archivedGroups.map(({ project, threads: projectThreads }, index) => (
           <SettingsSection
             key={project.id}
+            id={index === 0 ? searchableSetting("archive").id : undefined}
             title={project.name}
             icon={<ProjectFavicon environmentId={project.environmentId} cwd={project.cwd} />}
           >
diff --git a/apps/web/src/components/settings/SettingsSidebarNav.tsx b/apps/web/src/components/settings/SettingsSidebarNav.tsx
index 748662623f4..d9d381c02ab 100644
--- a/apps/web/src/components/settings/SettingsSidebarNav.tsx
+++ b/apps/web/src/components/settings/SettingsSidebarNav.tsx
@@ -1,4 +1,12 @@
-import { useCallback, type ComponentType } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+  type KeyboardEvent,
+} from "react";
 import {
   ArchiveIcon,
   ArrowLeftIcon,
@@ -8,10 +16,15 @@ import {
   KeyboardIcon,
   Link2Icon,
   PaletteIcon,
+  SearchIcon,
   Settings2Icon,
+  XIcon,
 } from "lucide-react";
-import { useCanGoBack, useNavigate } from "@tanstack/react-router";
+import { useCanGoBack, useLocation, useNavigate } from "@tanstack/react-router";
 
+import { Button } from "../ui/button";
+import { Input } from "../ui/input";
+import { Kbd } from "../ui/kbd";
 import {
   SidebarContent,
   SidebarFooter,
@@ -22,45 +35,149 @@ import {
   useSidebar,
 } from "../ui/sidebar";
 import { T3ConnectSidebarAvatar, T3ConnectSidebarSignIn } from "../clerk/T3ConnectSidebarSignIn";
+import { scrollToSettingsTarget } from "./settingsLayout";
+import {
+  searchSettings,
+  SETTINGS_SECTION_LABELS,
+  type SettingsPath,
+  type SettingsSearchItem,
+} from "./settingsSearch";
 
-export type SettingsSectionPath =
-  | "/settings/general"
-  | "/settings/appearance"
-  | "/settings/keybindings"
-  | "/settings/providers"
-  | "/settings/source-control"
-  | "/settings/connections"
-  | "/settings/beta"
-  | "/settings/archived";
+const SETTINGS_SECTION_ICONS: Readonly<
+  Record<SettingsPath, ComponentType<{ className?: string }>>
+> = {
+  "/settings/general": Settings2Icon,
+  "/settings/appearance": PaletteIcon,
+  "/settings/keybindings": KeyboardIcon,
+  "/settings/providers": BotIcon,
+  "/settings/source-control": GitBranchIcon,
+  "/settings/connections": Link2Icon,
+  "/settings/beta": FlaskConicalIcon,
+  "/settings/archived": ArchiveIcon,
+};
 
 export const SETTINGS_NAV_ITEMS: ReadonlyArray<{
   label: string;
-  to: SettingsSectionPath;
+  to: SettingsPath;
   icon: ComponentType<{ className?: string }>;
-}> = [
-  { label: "General", to: "/settings/general", icon: Settings2Icon },
-  { label: "Appearance", to: "/settings/appearance", icon: PaletteIcon },
-  { label: "Keybindings", to: "/settings/keybindings", icon: KeyboardIcon },
-  { label: "Providers", to: "/settings/providers", icon: BotIcon },
-  { label: "Source Control", to: "/settings/source-control", icon: GitBranchIcon },
-  { label: "Connections", to: "/settings/connections", icon: Link2Icon },
-  { label: "Beta", to: "/settings/beta", icon: FlaskConicalIcon },
-  { label: "Archive", to: "/settings/archived", icon: ArchiveIcon },
-];
+}> = (Object.keys(SETTINGS_SECTION_LABELS) as SettingsPath[]).map((to) => ({
+  to,
+  label: SETTINGS_SECTION_LABELS[to],
+  icon: SETTINGS_SECTION_ICONS[to],
+}));
+
+function SettingsSectionIcon({ to }: { to: SettingsPath }) {
+  const Icon = SETTINGS_SECTION_ICONS[to];
+  return <Icon className="mt-0.5 size-3.5 shrink-0 text-sidebar-muted-foreground/60" />;
+}
 
 export function SettingsSidebarNav({ pathname }: { pathname: string }) {
   const navigate = useNavigate();
+  const currentHash = useLocation({ select: (location) => location.hash });
   const canGoBack = useCanGoBack();
-  const { isMobile, setOpenMobile } = useSidebar();
+  const { isMobile, setOpenMobile, open, setOpen } = useSidebar();
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const [query, setQuery] = useState("");
+  const [activeResultIndex, setActiveResultIndex] = useState(0);
+  const results = useMemo(() => searchSettings(query), [query]);
+  const isSearching = query.trim().length > 0;
+  const hasResults = results.length > 0;
+
+  useEffect(() => {
+    const result = results[activeResultIndex];
+    if (!result) return;
+    document
+      .getElementById(`settings-search-result-${result.id}`)
+      ?.scrollIntoView({ block: "nearest" });
+  }, [activeResultIndex, results]);
+
+  useEffect(() => {
+    const handleKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.key !== "/" || event.metaKey || event.ctrlKey || event.altKey) return;
+
+      const target = event.target;
+      if (
+        target instanceof HTMLElement &&
+        (target.tagName === "INPUT" ||
+          target.tagName === "TEXTAREA" ||
+          target.isContentEditable ||
+          // Keep focus inside open dialogs and popups instead of escaping
+          // their focus trap into the sidebar search.
+          target.closest('[role="dialog"], [aria-modal="true"], [data-slot$="popup"]') !== null)
+      ) {
+        return;
+      }
+
+      event.preventDefault();
+      if (isMobile) {
+        setOpenMobile(true);
+      } else if (!open) {
+        setOpen(true);
+      }
+      requestAnimationFrame(() => {
+        searchInputRef.current?.focus();
+        searchInputRef.current?.select();
+      });
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [isMobile, open, setOpen, setOpenMobile]);
+
   const handleSectionClick = useCallback(
-    (to: SettingsSectionPath) => {
+    (to: SettingsPath) => {
       if (isMobile) {
         setOpenMobile(false);
       }
-      void navigate({ to, replace: true });
+      void navigate({ to, hash: "", replace: true, hashScrollIntoView: false });
     },
     [isMobile, navigate, setOpenMobile],
   );
+  const clearSearch = useCallback(() => {
+    setQuery("");
+    setActiveResultIndex(0);
+  }, []);
+  const handleSearchResultClick = useCallback(
+    (item: SettingsSearchItem) => {
+      clearSearch();
+      if (isMobile) {
+        setOpenMobile(false);
+      }
+      const targetId = item.targetId ?? item.id;
+      if (pathname === item.to && currentHash.replace(/^#/, "") === targetId) {
+        scrollToSettingsTarget(targetId);
+        return;
+      }
+      void navigate({ to: item.to, hash: targetId, replace: true, hashScrollIntoView: false });
+    },
+    [clearSearch, currentHash, isMobile, navigate, pathname, setOpenMobile],
+  );
+  const handleSearchKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === "Escape" && isSearching) {
+        event.preventDefault();
+        event.stopPropagation();
+        clearSearch();
+        return;
+      }
+      if (results.length === 0) return;
+      if (event.key === "ArrowDown") {
+        event.preventDefault();
+        setActiveResultIndex((index) => (index + 1) % results.length);
+        return;
+      }
+      if (event.key === "ArrowUp") {
+        event.preventDefault();
+        setActiveResultIndex((index) => (index - 1 + results.length) % results.length);
+        return;
+      }
+      if (event.key === "Enter") {
+        event.preventDefault();
+        const result = results[activeResultIndex];
+        if (result) handleSearchResultClick(result);
+      }
+    },
+    [activeResultIndex, clearSearch, handleSearchResultClick, isSearching, results],
+  );
   const handleBackClick = useCallback(() => {
     if (isMobile) {
       setOpenMobile(false);
@@ -75,27 +192,111 @@ export function SettingsSidebarNav({ pathname }: { pathname: string }) {
   return (
     <>
       <SidebarContent className="overflow-x-hidden">
-        <SidebarGroup className="p-2">
-          <SidebarMenu>
-            {SETTINGS_NAV_ITEMS.map((item) => {
-              const Icon = item.icon;
-              const isActive = pathname === item.to;
-              return (
-                <SidebarMenuItem key={item.to}>
-                  <SidebarMenuButton
-                    isActive={isActive}
-                    onClick={() => handleSectionClick(item.to)}
-                  >
-                    <Icon />
-                    <span className="truncate">{item.label}</span>
-                  </SidebarMenuButton>
-                </SidebarMenuItem>
-              );
-            })}
+        <SidebarGroup className="gap-2 p-[var(--sidebar-content-inset)]">
+          <div className="flex h-8 items-center gap-2 rounded-md px-2 py-1.5 text-sm font-medium text-sidebar-muted-foreground hover:bg-sidebar-row-hover hover:text-sidebar-foreground">
+            <SearchIcon className="size-4 shrink-0 text-sidebar-muted-foreground/80" />
+            <Input
+              ref={searchInputRef}
+              nativeInput
+              unstyled
+              type="search"
+              value={query}
+              onChange={(event) => {
+                setQuery(event.currentTarget.value);
+                setActiveResultIndex(0);
+              }}
+              onKeyDown={handleSearchKeyDown}
+              placeholder="Search"
+              aria-label="Search settings"
+              role="combobox"
+              aria-autocomplete="list"
+              aria-expanded={isSearching && hasResults}
+              aria-controls={isSearching && hasResults ? "settings-search-results" : undefined}
+              aria-activedescendant={
+                isSearching && results[activeResultIndex]
+                  ? `settings-search-result-${results[activeResultIndex].id}`
+                  : undefined
+              }
+              className="min-w-0 flex-1 [&_[data-slot=input]]:h-auto [&_[data-slot=input]]:p-0 [&_[data-slot=input]]:leading-normal [&_[data-slot=input]]:text-sm [&_[data-slot=input]]:font-medium [&_[data-slot=input]]:text-sidebar-foreground [&_[data-slot=input]]:placeholder:text-sidebar-muted-foreground"
+            />
+            {isSearching ? (
+              <Button
+                type="button"
+                size="icon-xs"
+                variant="ghost"
+                className="size-5 shrink-0 rounded-sm text-sidebar-muted-foreground hover:bg-sidebar-control-surface hover:text-sidebar-foreground"
+                aria-label="Clear settings search"
+                onClick={() => {
+                  clearSearch();
+                  searchInputRef.current?.focus();
+                }}
+              >
+                <XIcon className="size-3" />
+              </Button>
+            ) : (
+              <Kbd className="mr-px h-4 min-w-0 rounded-sm bg-sidebar-control-surface px-1.5 text-[10px] text-sidebar-muted-foreground ring-1 ring-sidebar-border">
+                /
+              </Kbd>
+            )}
+          </div>
+          {isSearching && results.length === 0 ? (
+            <p
+              role="status"
+              className="px-2 py-6 text-center text-xs text-sidebar-muted-foreground"
+            >
+              No settings found
+            </p>
+          ) : null}
+          <SidebarMenu
+            id={isSearching && hasResults ? "settings-search-results" : undefined}
+            role={isSearching && hasResults ? "listbox" : undefined}
+            aria-label={isSearching && hasResults ? "Settings search results" : undefined}
+          >
+            {isSearching
+              ? results.map((item, index) => (
+                  <SidebarMenuItem key={item.id} role="presentation">
+                    <SidebarMenuButton
+                      id={`settings-search-result-${item.id}`}
+                      role="option"
+                      aria-selected={index === activeResultIndex}
+                      tabIndex={-1}
+                      size="sm"
+                      isActive={index === activeResultIndex}
+                      className="h-auto min-h-10 items-start gap-2 rounded-md px-2 py-2 text-left hover:bg-sidebar-row-hover hover:text-sidebar-foreground"
+                      onMouseMove={() => setActiveResultIndex(index)}
+                      onClick={() => handleSearchResultClick(item)}
+                    >
+                      <SettingsSectionIcon to={item.to} />
+                      <span className="min-w-0 flex-1">
+                        <span className="block truncate text-sm font-medium text-sidebar-foreground">
+                          {item.title}
+                        </span>
+                        <span className="block truncate text-[11px] text-sidebar-muted-foreground/75">
+                          {SETTINGS_SECTION_LABELS[item.to]}
+                        </span>
+                      </span>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                ))
+              : SETTINGS_NAV_ITEMS.map((item) => {
+                  const Icon = item.icon;
+                  const isActive = pathname === item.to;
+                  return (
+                    <SidebarMenuItem key={item.to}>
+                      <SidebarMenuButton
+                        isActive={isActive}
+                        onClick={() => handleSectionClick(item.to)}
+                      >
+                        <Icon />
+                        <span className="truncate">{item.label}</span>
+                      </SidebarMenuButton>
+                    </SidebarMenuItem>
+                  );
+                })}
           </SidebarMenu>
         </SidebarGroup>
       </SidebarContent>
-      <SidebarFooter className="p-2">
+      <SidebarFooter className="p-[var(--sidebar-content-inset)]">
         <T3ConnectSidebarSignIn />
         <div className="flex items-center gap-1">
           <SidebarMenu className="min-w-0 flex-1">
diff --git a/apps/web/src/components/settings/SourceControlSettings.tsx b/apps/web/src/components/settings/SourceControlSettings.tsx
index cf6da231cdf..10b54f6d7af 100644
--- a/apps/web/src/components/settings/SourceControlSettings.tsx
+++ b/apps/web/src/components/settings/SourceControlSettings.tsx
@@ -55,6 +55,7 @@ import {
 import { RedactedSensitiveText } from "./RedactedSensitiveText";
 import { SourceControlWritingSettingsSection } from "./SourceControlWritingSettings";
 import { SettingResetButton, SettingsPageContainer, SettingsSection } from "./settingsLayout";
+import { searchableSetting } from "./settingsSearch";
 
 const EMPTY_DISCOVERY_RESULT: SourceControlDiscoveryResult = {
   versionControlSystems: [],
@@ -474,7 +475,7 @@ function EmptySourceControlDiscovery({
   const hasError = error !== null;
 
   return (
-    <SettingsSection title="Server environment">
+    <SettingsSection id={searchableSetting("source-control").id} title="Server environment">
       <Empty className="min-h-88">
         <EmptyMedia variant="icon">
           <GitPullRequestIcon />
@@ -517,8 +518,8 @@ export function SourceControlSettingsPanel() {
         }),
   );
   const result = discovery.data ?? EMPTY_DISCOVERY_RESULT;
-  const hasDiscoveryItems =
-    result.versionControlSystems.length > 0 || result.sourceControlProviders.length > 0;
+  const hasVersionControlSystems = result.versionControlSystems.length > 0;
+  const hasDiscoveryItems = hasVersionControlSystems || result.sourceControlProviders.length > 0;
   const isInitialScanPending = discovery.isPending && discovery.data === null;
   const handleScan = () => {
     discovery.refresh();
@@ -552,8 +553,12 @@ export function SourceControlSettingsPanel() {
         </>
       ) : hasDiscoveryItems ? (
         <>
-          {result.versionControlSystems.length > 0 ? (
-            <SettingsSection title="Version Control" headerAction={scanButton}>
+          {hasVersionControlSystems ? (
+            <SettingsSection
+              id={searchableSetting("source-control").id}
+              title="Version Control"
+              headerAction={scanButton}
+            >
               {result.versionControlSystems.map((item) => (
                 <DiscoveryItemRow key={`vcs:${item.kind}`} item={item}>
                   {item.kind === "git" ? <GitFetchIntervalSettings /> : undefined}
@@ -564,8 +569,9 @@ export function SourceControlSettingsPanel() {
 
           {result.sourceControlProviders.length > 0 ? (
             <SettingsSection
+              id={hasVersionControlSystems ? undefined : searchableSetting("source-control").id}
               title="Source Control Providers"
-              headerAction={result.versionControlSystems.length === 0 ? scanButton : null}
+              headerAction={hasVersionControlSystems ? null : scanButton}
             >
               {result.sourceControlProviders.map((item) => (
                 <DiscoveryItemRow key={`provider:${item.kind}`} item={item} />
diff --git a/apps/web/src/components/settings/settingsLayout.test.tsx b/apps/web/src/components/settings/settingsLayout.test.tsx
new file mode 100644
index 00000000000..714a77dbb56
--- /dev/null
+++ b/apps/web/src/components/settings/settingsLayout.test.tsx
@@ -0,0 +1,100 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vite-plus/test";
+
+import {
+  scrollToSettingsTarget,
+  SettingsRow,
+  SettingsSearchTargetProvider,
+} from "./settingsLayout";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("settings search targets", () => {
+  it("does not persist destination styling in the rendered row", () => {
+    const markup = renderToStaticMarkup(
+      <SettingsSearchTargetProvider targetId="word-wrap">
+        <SettingsRow id="word-wrap" title="Word wrap" description="Wrap long lines." />
+        <SettingsRow id="time-format" title="Time format" description="Choose a clock." />
+      </SettingsSearchTargetProvider>,
+    );
+
+    expect(markup).toContain('id="word-wrap" tabindex="-1"');
+    expect(markup).not.toContain("data-settings-search-target");
+    expect(markup).not.toContain("settings-search-target-pulse");
+  });
+
+  it("scrolls directly to a section header and restarts the destination pulse", () => {
+    const sectionScrollIntoView = vi.fn();
+    const headerScrollIntoView = vi.fn();
+    const focus = vi.fn();
+    const remove = vi.fn();
+    const add = vi.fn();
+    const addEventListener = vi.fn();
+    const target = {
+      tagName: "SECTION",
+      firstElementChild: { scrollIntoView: headerScrollIntoView },
+      scrollIntoView: sectionScrollIntoView,
+      focus,
+      classList: { remove, add },
+      addEventListener,
+      offsetWidth: 100,
+    } as unknown as HTMLElement;
+    vi.stubGlobal("document", {
+      getElementById: vi.fn(() => target),
+    });
+    vi.stubGlobal("window", {
+      matchMedia: vi.fn(() => ({ matches: false })),
+    });
+
+    expect(scrollToSettingsTarget("providers")).toBe(true);
+    expect(headerScrollIntoView).toHaveBeenCalledWith({
+      behavior: "smooth",
+      block: "center",
+    });
+    expect(sectionScrollIntoView).not.toHaveBeenCalled();
+    expect(focus).toHaveBeenCalledWith({ preventScroll: true });
+    expect(remove).toHaveBeenCalledWith("settings-search-target-pulse");
+    expect(add).toHaveBeenCalledWith("settings-search-target-pulse");
+    expect(addEventListener).toHaveBeenCalledWith("blur", expect.any(Function), { once: true });
+  });
+
+  it("does not animate the destination when reduced motion is requested", () => {
+    const scrollIntoView = vi.fn();
+    const focus = vi.fn();
+    const remove = vi.fn();
+    const add = vi.fn();
+    const target = {
+      tagName: "DIV",
+      firstElementChild: null,
+      scrollIntoView,
+      focus,
+      classList: { remove, add },
+      offsetWidth: 100,
+    } as unknown as HTMLElement;
+    vi.stubGlobal("document", {
+      getElementById: vi.fn(() => target),
+    });
+    vi.stubGlobal("window", {
+      matchMedia: vi.fn(() => ({ matches: true })),
+    });
+
+    expect(scrollToSettingsTarget("word-wrap")).toBe(true);
+    expect(scrollIntoView).toHaveBeenCalledWith({
+      behavior: "auto",
+      block: "center",
+    });
+    expect(focus).toHaveBeenCalledWith({ preventScroll: true });
+    expect(remove).toHaveBeenCalledWith("settings-search-target-pulse");
+    expect(add).not.toHaveBeenCalled();
+  });
+
+  it("leaves not-yet-mounted destinations to their mount lifecycle", () => {
+    vi.stubGlobal("document", {
+      getElementById: vi.fn(() => null),
+    });
+
+    expect(scrollToSettingsTarget("archive")).toBe(false);
+  });
+});
diff --git a/apps/web/src/components/settings/settingsLayout.tsx b/apps/web/src/components/settings/settingsLayout.tsx
index bc35949280d..238fddbc48a 100644
--- a/apps/web/src/components/settings/settingsLayout.tsx
+++ b/apps/web/src/components/settings/settingsLayout.tsx
@@ -1,10 +1,83 @@
 import { Undo2Icon } from "lucide-react";
-import { type ComponentPropsWithoutRef, type ReactNode, useEffect, useState } from "react";
+import { useLocation, useNavigate } from "@tanstack/react-router";
+import {
+  createContext,
+  type ComponentPropsWithoutRef,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
 
 import { cn } from "../../lib/utils";
 import { Button } from "../ui/button";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 
+interface SettingsSearchTargetContextValue {
+  readonly targetId: string | null;
+  readonly onTargetHandled: () => void;
+}
+
+const noop = () => undefined;
+const SettingsSearchTargetContext = createContext<SettingsSearchTargetContextValue>({
+  targetId: null,
+  onTargetHandled: noop,
+});
+
+export function SettingsSearchTargetProvider({
+  targetId,
+  onTargetHandled = noop,
+  children,
+}: {
+  targetId: string | null;
+  onTargetHandled?: () => void;
+  children: ReactNode;
+}) {
+  const value = useMemo(() => ({ targetId, onTargetHandled }), [onTargetHandled, targetId]);
+  return <SettingsSearchTargetContext value={value}>{children}</SettingsSearchTargetContext>;
+}
+
+function scrollAndFocusSettingsTarget(target: HTMLElement): void {
+  const prefersReducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const scrollTarget =
+    target.tagName === "SECTION" && target.firstElementChild
+      ? (target.firstElementChild as HTMLElement)
+      : target;
+
+  scrollTarget.scrollIntoView({
+    behavior: prefersReducedMotion ? "auto" : "smooth",
+    block: "center",
+  });
+  target.focus({ preventScroll: true });
+  target.classList.remove("settings-search-target-pulse");
+  if (prefersReducedMotion) return;
+  void target.offsetWidth;
+  target.classList.add("settings-search-target-pulse");
+  // The class also suppresses the focus outline (the pulse is the destination
+  // indicator), so drop it once the element is no longer the destination.
+  target.addEventListener("blur", () => target.classList.remove("settings-search-target-pulse"), {
+    once: true,
+  });
+}
+
+function useSettingsSearchTarget<T extends HTMLElement>(id: string | undefined) {
+  const { targetId, onTargetHandled } = useContext(SettingsSearchTargetContext);
+  const isSearchTarget = id !== undefined && id === targetId;
+  const targetRef = useCallback(
+    (target: T | null) => {
+      if (target && isSearchTarget) {
+        scrollAndFocusSettingsTarget(target);
+        onTargetHandled();
+      }
+    },
+    [isSearchTarget, onTargetHandled],
+  );
+
+  return targetRef;
+}
+
 /** Re-render every `intervalMs`; return a stable timestamp snapshot for render-time relative labels. */
 export function useRelativeTimeTick(intervalMs = 1_000) {
   const [nowMs, setNowMs] = useState(() => Date.now());
@@ -28,8 +101,15 @@ export function SettingsSection({
   headerAction?: ReactNode;
   children: ReactNode;
 }) {
+  const targetRef = useSettingsSearchTarget<HTMLElement>(sectionProps.id);
+
   return (
-    <section {...sectionProps} className={cn("space-y-3", className)}>
+    <section
+      {...sectionProps}
+      ref={targetRef}
+      tabIndex={sectionProps.id ? -1 : sectionProps.tabIndex}
+      className={cn("space-y-3", className)}
+    >
       <div className="flex min-h-8 items-center justify-between gap-4 px-3 sm:px-4">
         <h2 className="flex items-center gap-2 text-lg font-semibold tracking-[-0.025em] text-foreground">
           {icon}
@@ -59,9 +139,13 @@ export function SettingsRow({
   control?: ReactNode;
   children?: ReactNode;
 }) {
+  const targetRef = useSettingsSearchTarget<HTMLDivElement>(rowProps.id);
+
   return (
     <div
       {...rowProps}
+      ref={targetRef}
+      tabIndex={rowProps.id ? -1 : rowProps.tabIndex}
       className={cn("rounded-xl px-3 sm:px-4", children ? "pt-3 pb-1" : "py-3", className)}
     >
       <div className="flex flex-col gap-3 sm:grid sm:grid-cols-[minmax(0,1fr)_minmax(10rem,auto)] sm:items-center sm:gap-8">
@@ -119,11 +203,27 @@ export function SettingsPageContainer({
   children: ReactNode;
   className?: string;
 }) {
+  const navigate = useNavigate();
+  const hash = useLocation({ select: (location) => location.hash });
+  const targetId = hash.replace(/^#/, "") || null;
+  const clearTargetHash = useCallback(() => {
+    void navigate({ hash: "", replace: true, resetScroll: false, hashScrollIntoView: false });
+  }, [navigate]);
+
   return (
-    <div className="settings-page-scroll-fade scrollbar-gutter-both flex-1 overflow-y-auto px-4 pt-10 pb-7 sm:px-8 sm:pt-12 sm:pb-10">
-      <div className={cn("mx-auto flex w-full max-w-4xl flex-col gap-12", className)}>
-        {children}
+    <SettingsSearchTargetProvider targetId={targetId} onTargetHandled={clearTargetHash}>
+      <div className="settings-page-scroll-fade scrollbar-gutter-both flex-1 overflow-y-auto px-4 pt-10 pb-7 sm:px-8 sm:pt-12 sm:pb-10">
+        <div className={cn("mx-auto flex w-full max-w-4xl flex-col gap-12", className)}>
+          {children}
+        </div>
       </div>
-    </div>
+    </SettingsSearchTargetProvider>
   );
 }
+
+export function scrollToSettingsTarget(targetId: string): boolean {
+  const target = document.getElementById(targetId);
+  if (!target) return false;
+  scrollAndFocusSettingsTarget(target);
+  return true;
+}
diff --git a/apps/web/src/components/settings/settingsSearch.test.ts b/apps/web/src/components/settings/settingsSearch.test.ts
new file mode 100644
index 00000000000..464f92547e5
--- /dev/null
+++ b/apps/web/src/components/settings/settingsSearch.test.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  searchableSetting,
+  searchSettings,
+  SETTINGS_SEARCH_ITEMS,
+  type SettingsSearchItem,
+} from "./settingsSearch";
+
+const ITEMS: ReadonlyArray<SettingsSearchItem> = [
+  {
+    id: "word-wrap",
+    title: "Word wrap",
+    to: "/settings/general",
+  },
+  {
+    id: "network-access",
+    title: "Network access",
+    to: "/settings/connections",
+  },
+  {
+    id: "providers",
+    title: "Providers",
+    to: "/settings/providers",
+  },
+  {
+    id: "provider-updates",
+    title: "Update checks",
+    to: "/settings/general",
+  },
+  {
+    id: "automatic-updates",
+    title: "Automatic updates",
+    to: "/settings/general",
+  },
+];
+
+describe("searchSettings", () => {
+  it("matches only setting titles", () => {
+    expect(searchSettings("word", ITEMS).map((item) => item.id)).toEqual(["word-wrap"]);
+    expect(searchSettings("network", ITEMS).map((item) => item.id)).toEqual(["network-access"]);
+    expect(searchSettings("connections", ITEMS)).toEqual([]);
+    expect(searchSettings("claude", ITEMS)).toEqual([]);
+  });
+
+  it("matches normalized title substrings", () => {
+    expect(searchSettings("  WORD   WRAP  ", ITEMS).map((item) => item.id)).toEqual(["word-wrap"]);
+    expect(searchSettings("work")).toEqual([]);
+  });
+
+  it("keeps catalog order for multiple title matches", () => {
+    expect(searchSettings("update", ITEMS).map((item) => item.id)).toEqual([
+      "provider-updates",
+      "automatic-updates",
+    ]);
+  });
+
+  it("returns no results for an empty query", () => {
+    expect(searchSettings("   ", ITEMS)).toEqual([]);
+  });
+
+  it("keeps catalog result ids unique", () => {
+    const ids = SETTINGS_SEARCH_ITEMS.map((item) => item.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("serves anchor props to panels from the catalog", () => {
+    expect(searchableSetting("word-wrap")).toEqual({ id: "word-wrap", title: "Word wrap" });
+    expect(searchableSetting("archive")).toEqual({ id: "archive", title: "Archived threads" });
+  });
+
+  it("routes appearance settings to their current section", () => {
+    expect(searchSettings("theme")[0]).toMatchObject({
+      id: "theme",
+      to: "/settings/appearance",
+    });
+    expect(searchSettings("word wrap")[0]).toMatchObject({
+      id: "word-wrap",
+      to: "/settings/appearance",
+    });
+    expect(searchSettings("environment identification")[0]).toMatchObject({
+      id: "environment-identification",
+      to: "/settings/appearance",
+      targetId: "appearance",
+    });
+  });
+});
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
new file mode 100644
index 00000000000..4ead6eff4d7
--- /dev/null
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -0,0 +1,203 @@
+export type SettingsPath =
+  | "/settings/general"
+  | "/settings/appearance"
+  | "/settings/keybindings"
+  | "/settings/providers"
+  | "/settings/source-control"
+  | "/settings/connections"
+  | "/settings/beta"
+  | "/settings/archived";
+
+export interface SettingsSearchItem {
+  readonly id: string;
+  readonly title: string;
+  readonly to: SettingsPath;
+  readonly targetId?: string;
+}
+
+/**
+ * Section labels in sidebar order. The sidebar nav and the search-result
+ * subtitles both render from this record, so each label exists once.
+ */
+export const SETTINGS_SECTION_LABELS: Readonly<Record<SettingsPath, string>> = {
+  "/settings/general": "General",
+  "/settings/appearance": "Appearance",
+  "/settings/keybindings": "Keybindings",
+  "/settings/providers": "Providers",
+  "/settings/source-control": "Source Control",
+  "/settings/connections": "Connections",
+  "/settings/beta": "Beta",
+  "/settings/archived": "Archive",
+};
+
+/**
+ * Every searchable setting, in result order. This catalog is the single
+ * source of truth for anchor ids and visible titles: panels render both via
+ * `searchableSetting`, so a retitle (or, later, a translation pass) happens
+ * here once instead of separately in the panel and the index.
+ */
+export const SETTINGS_SEARCH_ITEMS = [
+  {
+    id: "theme",
+    title: "Theme",
+    to: "/settings/appearance",
+  },
+  {
+    // Prefixed because the slider control already owns the `glass-opacity` id.
+    id: "setting-glass-opacity",
+    title: "Glass opacity",
+    to: "/settings/appearance",
+  },
+  {
+    id: "environment-identification",
+    title: "Environment identification",
+    to: "/settings/appearance",
+    // The setting is stage-dependent, so its parent section is the stable destination.
+    targetId: "appearance",
+  },
+  {
+    id: "word-wrap",
+    title: "Word wrap",
+    to: "/settings/appearance",
+  },
+  {
+    id: "project-grouping",
+    title: "Project grouping",
+    to: "/settings/general",
+  },
+  {
+    id: "time-format",
+    title: "Time format",
+    to: "/settings/general",
+  },
+  {
+    id: "hide-whitespace-changes",
+    title: "Hide whitespace changes",
+    to: "/settings/general",
+  },
+  {
+    id: "assistant-output",
+    title: "Assistant output",
+    to: "/settings/general",
+  },
+  {
+    id: "provider-update-checks",
+    title: "Provider update checks",
+    to: "/settings/general",
+  },
+  {
+    id: "auto-open-task-panel",
+    title: "Auto-open task panel",
+    to: "/settings/general",
+  },
+  {
+    id: "new-threads",
+    title: "New threads",
+    to: "/settings/general",
+  },
+  {
+    id: "start-from-origin",
+    title: "Start from origin",
+    to: "/settings/general",
+    targetId: "new-threads",
+  },
+  {
+    id: "add-project-starts-in",
+    title: "Add project starts in",
+    to: "/settings/general",
+  },
+  {
+    id: "archive-confirmation",
+    title: "Archive confirmation",
+    to: "/settings/general",
+  },
+  {
+    id: "delete-confirmation",
+    title: "Delete confirmation",
+    to: "/settings/general",
+  },
+  {
+    id: "text-generation-model",
+    title: "Text generation model",
+    to: "/settings/general",
+  },
+  {
+    id: "diagnostics",
+    title: "Diagnostics",
+    to: "/settings/general",
+  },
+  {
+    id: "keybindings",
+    title: "Keybindings",
+    to: "/settings/keybindings",
+  },
+  {
+    id: "providers",
+    title: "Providers",
+    to: "/settings/providers",
+  },
+  {
+    id: "source-control",
+    title: "Source control",
+    to: "/settings/source-control",
+  },
+  {
+    id: "remote-environments",
+    title: "Remote environments",
+    to: "/settings/connections",
+  },
+  {
+    id: "sidebar-v2",
+    title: "Sidebar v2",
+    to: "/settings/beta",
+  },
+  {
+    id: "auto-settle-inactive-threads",
+    title: "Auto-settle inactive threads",
+    to: "/settings/beta",
+    targetId: "sidebar-v2",
+  },
+  {
+    id: "archive",
+    title: "Archived threads",
+    to: "/settings/archived",
+  },
+] as const satisfies ReadonlyArray<SettingsSearchItem>;
+
+export type SettingsSearchItemId = (typeof SETTINGS_SEARCH_ITEMS)[number]["id"];
+
+const SEARCH_ITEMS_BY_ID = Object.fromEntries(
+  SETTINGS_SEARCH_ITEMS.map((item) => [item.id, item]),
+) as Readonly<Record<SettingsSearchItemId, SettingsSearchItem>>;
+
+/**
+ * `id` and `title` props for the element a search item anchors to. Panels
+ * spread (or pick from) this instead of restating the strings, so the catalog
+ * and the rendered settings cannot drift apart.
+ */
+export function searchableSetting(id: SettingsSearchItemId): {
+  readonly id: string;
+  readonly title: string;
+} {
+  const { id: anchorId, title } = SEARCH_ITEMS_BY_ID[id];
+  return { id: anchorId, title };
+}
+
+function normalizeSearchText(value: string): string {
+  return value
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLocaleLowerCase()
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function searchSettings(
+  query: string,
+  items: ReadonlyArray<SettingsSearchItem> = SETTINGS_SEARCH_ITEMS,
+): ReadonlyArray<SettingsSearchItem> {
+  const normalizedQuery = normalizeSearchText(query);
+  if (normalizedQuery.length === 0) return [];
+
+  return items.filter((item) => normalizeSearchText(item.title).includes(normalizedQuery));
+}
diff --git a/apps/web/src/components/sidebar/SidebarChrome.tsx b/apps/web/src/components/sidebar/SidebarChrome.tsx
index 212138d687b..0ff223c27d8 100644
--- a/apps/web/src/components/sidebar/SidebarChrome.tsx
+++ b/apps/web/src/components/sidebar/SidebarChrome.tsx
@@ -138,7 +138,7 @@ export const SidebarChromeFooter = memo(function SidebarChromeFooter() {
   }, [isMobile, navigate, setOpenMobile]);
 
   return (
-    <SidebarFooter className="p-2">
+    <SidebarFooter className="p-[var(--sidebar-content-inset)]">
       <SidebarProviderUpdatePill />
       <SidebarUpdatePill />
       <SidebarMenu>
diff --git a/apps/web/src/components/sidebar/SidebarUpdatePill.tsx b/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
index 0603a9da085..fb95dc11a4c 100644
--- a/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
+++ b/apps/web/src/components/sidebar/SidebarUpdatePill.tsx
@@ -14,6 +14,7 @@ import {
   shouldShowDesktopUpdateButton,
   shouldToastDesktopUpdateActionResult,
 } from "../desktopUpdate.logic";
+import { showDesktopUpdateDownloadedToast } from "../desktopUpdate.toast";
 import { Alert, AlertDescription, AlertTitle } from "../ui/alert";
 import { Separator } from "../ui/separator";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
@@ -80,11 +81,7 @@ export function SidebarUpdatePill() {
         .downloadUpdate()
         .then((result) => {
           if (result.completed) {
-            toastManager.add({
-              type: "success",
-              title: "Update downloaded",
-              description: "Restart the app from the update button to install it.",
-            });
+            showDesktopUpdateDownloadedToast(bridge, result.state);
           }
           if (!shouldToastDesktopUpdateActionResult(result)) return;
           const actionError = getDesktopUpdateActionError(result);
diff --git a/apps/web/src/components/ui/button.test.tsx b/apps/web/src/components/ui/button.test.tsx
new file mode 100644
index 00000000000..341d85b42bb
--- /dev/null
+++ b/apps/web/src/components/ui/button.test.tsx
@@ -0,0 +1,31 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vite-plus/test";
+import { FlaskConicalIcon } from "lucide-react";
+
+import { Button } from "./button";
+
+describe("button geometry tokens", () => {
+  it("uses the shared control radius and an opaque semantic icon color", () => {
+    const html = renderToStaticMarkup(
+      <Button size="icon-xs" variant="outline" aria-label="Run tests">
+        <FlaskConicalIcon />
+      </Button>,
+    );
+
+    expect(html).toContain("rounded-[var(--control-radius)]");
+    expect(html).toContain("[--control-icon-color:var(--muted-foreground)]");
+    expect(html).toContain("text-[var(--control-icon-color)]");
+    expect(html).not.toContain("opacity-80");
+  });
+
+  it("keeps compact icon buttons square at every breakpoint", () => {
+    const html = renderToStaticMarkup(
+      <Button size="icon-xs" aria-label="Add action">
+        <span>+</span>
+      </Button>,
+    );
+
+    expect(html).toContain("size-7");
+    expect(html).toContain("sm:size-6");
+  });
+});
diff --git a/apps/web/src/components/ui/button.tsx b/apps/web/src/components/ui/button.tsx
index f6d09f7799a..778574ba010 100644
--- a/apps/web/src/components/ui/button.tsx
+++ b/apps/web/src/components/ui/button.tsx
@@ -8,7 +8,7 @@ import type * as React from "react";
 import { cn } from "~/lib/utils";
 
 const buttonVariants = cva(
-  "[&_svg]:-mx-0.5 relative inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-lg border font-medium text-base outline-none transition-shadow before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] pointer-coarse:after:absolute pointer-coarse:after:size-full pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-64 sm:text-sm [&_svg:not([class*='opacity-'])]:opacity-80 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+  "[--control-icon-color:currentColor] [&_svg]:-mx-0.5 relative inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-[var(--control-radius)] border font-medium text-base outline-none transition-shadow before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--control-radius)-1px)] pointer-coarse:after:absolute pointer-coarse:after:size-full pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background disabled:pointer-events-none disabled:opacity-64 sm:text-sm [&_svg:not([class*='text-'])]:text-[var(--control-icon-color)] [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
   {
     defaultVariants: {
       size: "default",
@@ -23,11 +23,11 @@ const buttonVariants = cva(
         "icon-xl":
           "size-11 sm:size-10 [&_svg:not([class*='size-'])]:size-5 sm:[&_svg:not([class*='size-'])]:size-4.5",
         "icon-xs":
-          "size-7 rounded-md before:rounded-[calc(var(--radius-md)-1px)] sm:size-6 not-in-data-[slot=input-group]:[&_svg:not([class*='size-'])]:size-4 sm:not-in-data-[slot=input-group]:[&_svg:not([class*='size-'])]:size-3.5",
+          "size-7 sm:size-6 not-in-data-[slot=input-group]:[&_svg:not([class*='size-'])]:size-4 sm:not-in-data-[slot=input-group]:[&_svg:not([class*='size-'])]:size-3.5",
         lg: "h-10 px-[calc(--spacing(3.5)-1px)] sm:h-9",
         sm: "h-8 gap-1.5 px-[calc(--spacing(2.5)-1px)] sm:h-7",
         xl: "h-11 px-[calc(--spacing(4)-1px)] text-lg sm:h-10 sm:text-base [&_svg:not([class*='size-'])]:size-5 sm:[&_svg:not([class*='size-'])]:size-4.5",
-        xs: "h-7 gap-1 rounded-md px-[calc(--spacing(2)-1px)] text-sm before:rounded-[calc(var(--radius-md)-1px)] sm:h-6 sm:text-xs [&_svg:not([class*='size-'])]:size-4 sm:[&_svg:not([class*='size-'])]:size-3.5",
+        xs: "h-7 gap-1 px-[calc(--spacing(2)-1px)] text-sm sm:h-6 sm:text-xs [&_svg:not([class*='size-'])]:size-4 sm:[&_svg:not([class*='size-'])]:size-3.5",
       },
       variant: {
         default:
@@ -37,10 +37,10 @@ const buttonVariants = cva(
         "destructive-outline":
           "border-input bg-popover not-dark:bg-clip-padding text-destructive-foreground shadow-xs/5 not-disabled:not-active:not-data-pressed:before:shadow-[0_1px_--theme(--color-black/4%)] dark:bg-input/32 dark:not-disabled:before:shadow-[0_-1px_--theme(--color-white/2%)] dark:not-disabled:not-active:not-data-pressed:before:shadow-[0_-1px_--theme(--color-white/6%)] [:disabled,:active,[data-pressed]]:shadow-none [:hover,[data-pressed]]:border-destructive/32 [:hover,[data-pressed]]:bg-destructive/4",
         ghost:
-          "border-transparent text-foreground data-pressed:bg-accent [:hover,[data-pressed]]:bg-accent [&_svg:not([class*='text-'])]:text-muted-foreground",
+          "[--control-icon-color:var(--muted-foreground)] border-transparent text-foreground data-pressed:bg-accent [:hover,[data-pressed]]:bg-accent",
         link: "border-transparent underline-offset-4 [:hover,[data-pressed]]:underline",
         outline:
-          "border-input bg-popover not-dark:bg-clip-padding text-foreground shadow-xs/5 not-disabled:not-active:not-data-pressed:before:shadow-[0_1px_--theme(--color-black/4%)] dark:bg-input/32 dark:not-disabled:before:shadow-[0_-1px_--theme(--color-white/2%)] dark:not-disabled:not-active:not-data-pressed:before:shadow-[0_-1px_--theme(--color-white/6%)] [:disabled,:active,[data-pressed]]:shadow-none [:hover,[data-pressed]]:bg-accent/50 dark:[:hover,[data-pressed]]:bg-input/64 [&_svg:not([class*='text-'])]:text-muted-foreground",
+          "[--control-icon-color:var(--muted-foreground)] border-input bg-popover not-dark:bg-clip-padding text-foreground shadow-xs/5 not-disabled:not-active:not-data-pressed:before:shadow-[0_1px_--theme(--color-black/4%)] dark:bg-input/32 dark:not-disabled:before:shadow-[0_-1px_--theme(--color-white/2%)] dark:not-disabled:not-active:not-data-pressed:before:shadow-[0_-1px_--theme(--color-white/6%)] [:disabled,:active,[data-pressed]]:shadow-none [:hover,[data-pressed]]:bg-accent/50 dark:[:hover,[data-pressed]]:bg-input/64",
         secondary:
           "border-transparent bg-secondary text-secondary-foreground [:active,[data-pressed]]:bg-secondary/80 [:hover,[data-pressed]]:bg-secondary/90",
       },
diff --git a/apps/web/src/components/ui/command.test.tsx b/apps/web/src/components/ui/command.test.tsx
new file mode 100644
index 00000000000..bd03b2712d3
--- /dev/null
+++ b/apps/web/src/components/ui/command.test.tsx
@@ -0,0 +1,31 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vite-plus/test";
+
+import { Command, CommandFooter, CommandInput } from "./command";
+
+describe("command compact geometry", () => {
+  it("keeps shell selectors on the wrapper and direct-input padding on AutocompleteInput", () => {
+    const html = renderToStaticMarkup(
+      <Command>
+        <CommandInput placeholder="Search commands" />
+      </Command>,
+    );
+    const shellClass = html.match(/class="([^"]*px-\[var\(--command-shell-inset\)[^"]*)"/)?.[1];
+    const inputClass = html.match(/class="([^"]*has-focus-visible:ring-0[^"]*)"/)?.[1];
+
+    expect(shellClass).toContain(
+      "[&amp;_[data-slot=autocomplete-start-addon]]:ps-[calc(var(--command-shell-inset)+0.0625rem)]",
+    );
+    expect(shellClass).not.toContain("sm:*:data-[slot=autocomplete-input]");
+    expect(inputClass).toContain(
+      "sm:*:data-[slot=autocomplete-input]:ps-[calc(var(--command-shell-inset)+1.5rem)]!",
+    );
+  });
+
+  it("uses the semantic footer inset without changing compact vertical padding", () => {
+    const html = renderToStaticMarkup(<CommandFooter>Shortcuts</CommandFooter>);
+
+    expect(html).toContain("px-[var(--command-content-inset)]");
+    expect(html).toContain("py-2.5");
+  });
+});
diff --git a/apps/web/src/components/ui/command.tsx b/apps/web/src/components/ui/command.tsx
index 53999c20f0d..0a713b769ec 100644
--- a/apps/web/src/components/ui/command.tsx
+++ b/apps/web/src/components/ui/command.tsx
@@ -103,11 +103,16 @@ function CommandInput({
   wrapperClassName?: string | undefined;
 }) {
   return (
-    <div className={cn("px-1.25 py-1.5", wrapperClassName)}>
+    <div
+      className={cn(
+        "px-[var(--command-shell-inset)] py-1.5 [&_[data-slot=autocomplete-start-addon]]:ps-[calc(var(--command-shell-inset)+0.0625rem)]",
+        wrapperClassName,
+      )}
+    >
       <AutocompleteInput
         autoFocus
         className={cn(
-          "border-transparent! bg-transparent! shadow-none before:hidden has-focus-visible:ring-0 placeholder:text-muted-foreground/80 *:data-[slot=autocomplete-input]:ps-9! sm:*:data-[slot=autocomplete-input]:ps-8.5!",
+          "border-transparent! bg-transparent! shadow-none before:hidden has-focus-visible:ring-0 placeholder:text-muted-foreground/80 *:data-[slot=autocomplete-input]:ps-9! sm:*:data-[slot=autocomplete-input]:ps-[calc(var(--command-shell-inset)+1.5rem)]!",
           className,
         )}
         placeholder={placeholder}
@@ -211,7 +216,7 @@ function CommandFooter({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
       className={cn(
-        "relative flex items-center justify-between gap-2 rounded-b-[calc(var(--radius-2xl)-1px)] bg-foreground/[0.025] px-4 py-2.5 font-medium text-sm text-muted-foreground [&_[data-slot=kbd-group]]:font-sans [&_[data-slot=kbd]]:bg-foreground/[0.08] [&_[data-slot=kbd]]:text-foreground [&_[data-slot=kbd]]:ring-0",
+        "relative flex items-center justify-between gap-2 rounded-b-[calc(var(--radius-2xl)-1px)] bg-foreground/[0.025] px-[var(--command-content-inset)] py-2.5 font-medium text-sm text-muted-foreground [&_[data-slot=kbd-group]]:font-sans [&_[data-slot=kbd]]:bg-foreground/[0.08] [&_[data-slot=kbd]]:text-foreground [&_[data-slot=kbd]]:ring-0",
         className,
       )}
       data-slot="command-footer"
diff --git a/apps/web/src/components/ui/sidebar.test.tsx b/apps/web/src/components/ui/sidebar.test.tsx
index b57ff200510..e2d29d607e1 100644
--- a/apps/web/src/components/ui/sidebar.test.tsx
+++ b/apps/web/src/components/ui/sidebar.test.tsx
@@ -55,12 +55,15 @@ describe("sidebar interactive cursors", () => {
 
     expect(html).toContain('data-slot="sidebar-menu-button"');
     expect(html).toContain("h-8");
-    expect(html).toContain("rounded-md");
-    expect(html).toContain("px-2");
+    expect(html).toContain("rounded-[var(--control-radius)]");
+    expect(html).toContain("px-[var(--sidebar-row-content-inset)]");
     expect(html).toContain("py-1.5");
     expect(html).toContain("]:size-4");
     expect(html).toContain("]:shrink-0");
     expect(html).toContain("cursor-pointer");
+    expect(html).toContain("gap-[var(--sidebar-control-gap)]");
+    expect(html).toContain("text-[var(--sidebar-icon-color)]");
+    expect(html).not.toContain("[&amp;&gt;svg]:opacity-60");
   });
 
   it("applies the shared default treatment to icon-only menu buttons", () => {
diff --git a/apps/web/src/components/ui/sidebar.tsx b/apps/web/src/components/ui/sidebar.tsx
index f9a00437825..ddc7310430f 100644
--- a/apps/web/src/components/ui/sidebar.tsx
+++ b/apps/web/src/components/ui/sidebar.tsx
@@ -712,7 +712,10 @@ function SidebarContent({
 function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
   return (
     <div
-      className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
+      className={cn(
+        "relative flex w-full min-w-0 flex-col p-[var(--sidebar-content-inset)]",
+        className,
+      )}
       data-sidebar="group"
       data-slot="sidebar-group"
       {...props}
@@ -792,7 +795,7 @@ function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
 }
 
 const sidebarMenuButtonVariants = cva(
-  "peer/menu-button flex w-full cursor-pointer items-center gap-2 overflow-hidden text-left outline-hidden ring-ring transition-[width,height,padding] hover:bg-sidebar-row-hover hover:text-sidebar-foreground focus-visible:ring-2 active:bg-sidebar-row-active active:text-sidebar-foreground disabled:pointer-events-none disabled:opacity-50 group-has-data-[sidebar=menu-action]/menu-item:pe-8 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-row-selected data-[active=true]:font-medium data-[active=true]:text-sidebar-foreground data-[state=open]:hover:bg-sidebar-row-hover data-[state=open]:hover:text-sidebar-foreground group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! [&>span:last-child]:truncate [&>svg:not([class*='size-'])]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-muted-foreground [&>svg]:opacity-60 hover:[&>svg]:text-sidebar-foreground hover:[&>svg]:opacity-100 active:[&>svg]:text-sidebar-foreground active:[&>svg]:opacity-100 data-[active=true]:[&>svg]:text-sidebar-foreground data-[active=true]:[&>svg]:opacity-100",
+  "peer/menu-button flex w-full cursor-pointer items-center gap-[var(--sidebar-control-gap)] overflow-hidden text-left outline-hidden ring-ring transition-[width,height,padding] hover:bg-sidebar-row-hover hover:text-sidebar-foreground focus-visible:ring-2 active:bg-sidebar-row-active active:text-sidebar-foreground disabled:pointer-events-none disabled:opacity-50 group-has-data-[sidebar=menu-action]/menu-item:pe-8 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[active=true]:bg-sidebar-row-selected data-[active=true]:font-medium data-[active=true]:text-sidebar-foreground data-[state=open]:hover:bg-sidebar-row-hover data-[state=open]:hover:text-sidebar-foreground group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-[var(--sidebar-content-inset)]! [&>span:last-child]:truncate [&>svg:not([class*='size-'])]:size-4 [&>svg]:shrink-0 [&>svg]:text-[var(--sidebar-icon-color)] hover:[&>svg]:text-sidebar-foreground active:[&>svg]:text-sidebar-foreground data-[active=true]:[&>svg]:text-sidebar-foreground",
   {
     defaultVariants: {
       size: "default",
@@ -800,8 +803,9 @@ const sidebarMenuButtonVariants = cva(
     },
     variants: {
       size: {
-        default: "h-8 rounded-md px-2.5 py-1.5 text-sm",
-        icon: "size-8 justify-center rounded-md p-0",
+        default:
+          "h-8 rounded-[var(--control-radius)] px-[var(--sidebar-row-content-inset)] py-1.5 text-sm",
+        icon: "size-8 justify-center rounded-[var(--control-radius)] p-0",
         lg: "h-12 rounded-lg p-2 text-sm group-data-[collapsible=icon]:p-0!",
         sm: "h-7 rounded-lg p-2 text-xs",
       },
diff --git a/apps/web/src/custom/icons/lucide-phosphor.tsx b/apps/web/src/custom/icons/lucide-phosphor.tsx
index 03be2e5c889..9556c73c931 100644
--- a/apps/web/src/custom/icons/lucide-phosphor.tsx
+++ b/apps/web/src/custom/icons/lucide-phosphor.tsx
@@ -87,6 +87,7 @@ import {
   Eyedropper as PhEyedropper,
   File as PhFile,
   FileCode as PhFileCode,
+  FileMagnifyingGlass as PhFileMagnifyingGlass,
   Files as PhFiles,
   Flask as PhFlask,
   Folder as PhFolder,
@@ -114,6 +115,7 @@ import {
   Link as PhLink,
   LinkSimple as PhLinkSimple,
   ListChecks as PhListChecks,
+  ListMagnifyingGlass as PhListMagnifyingGlass,
   Lock as PhLock,
   LockOpen as PhLockOpen,
   MagnifyingGlass as PhMagnifyingGlass,
@@ -274,6 +276,10 @@ export const Files = icon("files", PhFiles, "duotone");
 export const FileDiff = icon("file-diff", PhGitDiff, "duotone");
 export const FileDiffIcon = icon("file-diff", PhGitDiff, "duotone");
 export const FileJsonIcon = icon("file-json", PhFileCode, "duotone");
+export const FileSearchIcon = icon("file-search", PhFileMagnifyingGlass, "duotone");
+// Text search — phosphor has no text-magnifier; the list-lines magnifier is
+// the closest read of "search within content".
+export const TextSearchIcon = icon("text-search", PhListMagnifyingGlass, "duotone");
 export const ClipboardList = icon("clipboard-list", PhClipboardText, "duotone");
 export const CopyIcon = icon("copy", PhCopy, "duotone");
 export const ArchiveIcon = icon("archive", PhArchive, "duotone");
diff --git a/apps/web/src/custom/terminalFont.ts b/apps/web/src/custom/terminalFont.ts
index dace9a8e012..4f02085c303 100644
--- a/apps/web/src/custom/terminalFont.ts
+++ b/apps/web/src/custom/terminalFont.ts
@@ -2,148 +2,52 @@
  * Fork-owned terminal typography, Tier 1 — see
  * `.fork/customizations.yaml#geist-typography`.
  *
- * xterm takes its font from a constructor option, not the cascade, so the
- * fork's `--font-mono` has to be resolved by hand and re-applied once the
- * webfont actually lands. That is the whole reason this module exists. Keeping
- * it out of `ThreadTerminalDrawer`'s mount effect leaves that ~1.5k-line
- * upstream hot path with two one-line call sites instead of forty lines of
- * fork logic, and lets the behaviour be tested without a DOM (the web unit
- * project runs on `environment: "node"`).
+ * The ghostty surface takes its font from a creation option, not the cascade,
+ * so the fork's `--font-mono` has to be resolved by hand at the mount site.
+ * That is the whole reason this module exists. The surface itself waits for
+ * the webfont and re-measures the cell grid when it lands, so unlike the
+ * xterm era there is no refit shim here — just the cascade read and its
+ * degraded-path fallback, testable without a DOM (the web unit project runs
+ * on `environment: "node"`).
  */
 
-/**
- * Size for the `FontFaceSet.load()` shorthand. Syntactically required and
- * irrelevant to matching — the family selects the face, the size does not.
- */
-const FONT_LOAD_PROBE_SIZE = "12px";
-
-/**
- * Any family other than the one being applied. xterm's option setter drops
- * equal writes, so re-applying the resolved stack has to be preceded by a
- * different value to register as a change. See `remeasure` below.
- */
-const REMEASURE_BOUNCE_FAMILY = "monospace";
-
 /**
  * Used when the cascade read comes back empty — a detached mount, or the fork
  * marker not yet stamped. It leads with Geist Mono on purpose: font fallback
  * is per-family and skips families that aren't loaded, so naming the bundled
  * face first costs nothing when it is missing, and avoids the degraded path
  * quietly landing the terminal on SF Mono while the rest of the app is on
- * Geist. JetBrains Mono is kept as upstream's bundled Linux fallback.
+ * Geist. JetBrains Mono is kept as upstream's bundled Linux fallback. No
+ * trailing `monospace`: the surface appends its own glyph fallbacks (which
+ * end in the generic), and a generic mid-list would sit ahead of the Nerd
+ * Font faces — see {@link terminalFontFamilyFrom}.
  */
 export const FORK_TERMINAL_FONT_FALLBACK =
-  '"Geist Mono Variable", "Geist Mono", "SF Mono", "SFMono-Regular", "JetBrains Mono", Consolas, "Liberation Mono", Menlo, monospace';
+  '"Geist Mono Variable", "Geist Mono", "SF Mono", "SFMono-Regular", "JetBrains Mono", Consolas, "Liberation Mono", Menlo';
+
+/**
+ * The cascade stacks end in the `monospace` generic, but the surface appends
+ * its glyph fallbacks (Symbols Nerd Font et al, then `monospace`) after
+ * whatever it is given. Handing over a stack with a generic mid-list is a
+ * shape upstream's own default never produces — per-character fallback
+ * should walk past a generic whose face lacks the glyph, but "should" is not
+ * a place to leave prompt glyphs. Trim it; the surface restores the generic
+ * at the true tail.
+ */
+function stripTrailingGenericFamilies(stack: string): string {
+  const families = stack.split(",").map((family) => family.trim());
+  while (families.length > 0 && families[families.length - 1]?.toLowerCase() === "monospace") {
+    families.pop();
+  }
+  return families.join(", ");
+}
 
 /** Pure half of {@link resolveTerminalFontFamily}, so it can be tested without a DOM. */
 export function terminalFontFamilyFrom(resolvedVariable: string): string {
-  return resolvedVariable.trim() || FORK_TERMINAL_FONT_FALLBACK;
+  return stripTrailingGenericFamilies(resolvedVariable.trim()) || FORK_TERMINAL_FONT_FALLBACK;
 }
 
 /** Reads the cascade-resolved `--font-mono` off `element`. */
 export function resolveTerminalFontFamily(element: Element): string {
   return terminalFontFamilyFrom(getComputedStyle(element).getPropertyValue("--font-mono"));
 }
-
-/**
- * First family of a CSS font stack, for use in a `font` shorthand. Computed
- * custom properties preserve the authored text, so a multi-word family arrives
- * already quoted.
- */
-export function firstFontFamily(stack: string): string | null {
-  const first = stack.split(",")[0]?.trim();
-  return first ? first : null;
-}
-
-/**
- * The slice of xterm's `Terminal` this module touches. `fontFamily` is optional
- * because `ITerminalOptions` declares it that way.
- */
-export interface ForkTerminalFontTarget {
-  readonly cols: number;
-  readonly rows: number;
-  readonly options: { fontFamily?: string | undefined };
-  readonly buffer: { readonly active: { readonly viewportY: number; readonly baseY: number } };
-  scrollToBottom: () => void;
-}
-
-export interface RefitTerminalWhenFontsReadyArgs {
-  readonly terminal: ForkTerminalFontTarget;
-  /** False once the terminal has been torn down, so a late resolve is dropped. */
-  readonly isCurrent: () => boolean;
-  /** Upstream's `fitTerminalSafely(fitAddon)`. */
-  readonly fit: () => void;
-  /** Upstream's `resizeTerminal`, propagating the new geometry to the PTY. */
-  readonly resize: (cols: number, rows: number) => unknown;
-  readonly fonts?: Pick<FontFaceSet, "load" | "ready"> | undefined;
-  readonly scheduleFrame?: ((callback: () => void) => void) | undefined;
-}
-
-function defaultScheduleFrame(callback: () => void): void {
-  if (typeof requestAnimationFrame === "function") {
-    requestAnimationFrame(callback);
-    return;
-  }
-  callback();
-}
-
-/**
- * xterm sizes its cell grid at `open()`. With a webfont that can happen before
- * the face has landed, leaving the grid measured against the fallback metrics —
- * measurably so: Geist Mono renders at the unknown-font fallback width until it
- * loads, and wider afterwards. This re-measures once the fonts settle and then
- * propagates the corrected geometry, both locally and to the PTY.
- */
-export async function refitTerminalWhenFontsReady(
-  args: RefitTerminalWhenFontsReadyArgs,
-): Promise<void> {
-  const fonts = args.fonts ?? globalThis.document?.fonts;
-  if (!fonts) return;
-
-  // Set from `resolveTerminalFontFamily` at the call site; if some future
-  // upstream refactor stops passing one there is no resolved stack to restore,
-  // and xterm's own default already measured correctly.
-  const fontFamily = args.terminal.options.fontFamily;
-  if (!fontFamily) return;
-
-  const probe = firstFontFamily(fontFamily);
-  if (probe) {
-    // Derived from the family we actually resolved rather than hardcoded, for
-    // two reasons. It cannot go stale when the mono face changes; and in an
-    // unmarked, pure-upstream build it names a local system face with no
-    // `@font-face` rule, so nothing is fetched and the fork's "an unmarked
-    // build never pulls a Geist byte" invariant holds.
-    //
-    // `load()` rejects if a matching face fails to load. An unhandled
-    // rejection would be pure noise here: a missing webfont just means the
-    // fallback metrics were already correct.
-    await fonts.load(`${FONT_LOAD_PROBE_SIZE} ${probe}`).catch(() => []);
-  }
-  await fonts.ready;
-  if (!args.isCurrent()) return;
-
-  // xterm's option setter drops equal writes — `_setupOptions` guards with
-  // `if (this.rawOptions[propName] !== value)` — so re-assigning the same stack
-  // fires no change event and nothing re-measures. Bounce through another
-  // family to force it. Both writes are in one task, so nothing paints between.
-  args.terminal.options.fontFamily = REMEASURE_BOUNCE_FAMILY;
-  args.terminal.options.fontFamily = fontFamily;
-
-  // Fit on the next frame rather than inline: that avoids betting on xterm
-  // re-measuring synchronously inside the setter, and mirrors the frame
-  // upstream already uses at its `drawerHeight`/`resizeEpoch` fit site.
-  (args.scheduleFrame ?? defaultScheduleFrame)(() => {
-    if (!args.isCurrent()) return;
-    // Mirrors the fit/propagate sequence upstream uses at both of its own fit
-    // sites: nothing in the drawer subscribes to `onResize`, so the PTY only
-    // learns the new column count if we tell it. Without this the corrected
-    // grid is narrower than the width the PTY is still wrapping to.
-    const active = args.terminal.buffer.active;
-    const wasAtBottom = active.viewportY >= active.baseY;
-    args.fit();
-    if (wasAtBottom) {
-      args.terminal.scrollToBottom();
-    }
-    void args.resize(args.terminal.cols, args.terminal.rows);
-  });
-}
diff --git a/apps/web/src/hooks/useActiveProjectTarget.ts b/apps/web/src/hooks/useActiveProjectTarget.ts
new file mode 100644
index 00000000000..560bba54f73
--- /dev/null
+++ b/apps/web/src/hooks/useActiveProjectTarget.ts
@@ -0,0 +1,41 @@
+import { scopeThreadRef } from "@t3tools/client-runtime/environment";
+import type { EnvironmentId, ScopedThreadRef } from "@t3tools/contracts";
+
+import { useProjects } from "~/state/entities";
+
+import { useHandleNewThread } from "./useHandleNewThread";
+
+export interface ActiveProjectTarget {
+  readonly environmentId: EnvironmentId;
+  readonly cwd: string;
+  readonly projectName: string;
+  readonly threadRef: ScopedThreadRef;
+}
+
+/**
+ * Resolves the project workspace behind the active thread (or draft) so
+ * project-scoped surfaces like the file picker and content search know which
+ * workspace to query and which thread's right panel opens their results.
+ */
+export function useActiveProjectTarget(): ActiveProjectTarget | null {
+  const { activeDraftThread, activeThread } = useHandleNewThread();
+  const projects = useProjects();
+  const thread = activeThread ?? activeDraftThread;
+  const threadId = activeThread?.id ?? activeDraftThread?.threadId;
+  const project = thread
+    ? projects.find(
+        (candidate) =>
+          candidate.environmentId === thread.environmentId && candidate.id === thread.projectId,
+      )
+    : null;
+  const cwd = thread?.worktreePath ?? project?.workspaceRoot;
+
+  if (!thread || !threadId || !project || !cwd) return null;
+
+  return {
+    environmentId: project.environmentId,
+    cwd,
+    projectName: project.title,
+    threadRef: scopeThreadRef(thread.environmentId, threadId),
+  };
+}
diff --git a/apps/web/src/hooks/useHandleNewThread.ts b/apps/web/src/hooks/useHandleNewThread.ts
index 74ad952e5a2..547d8287012 100644
--- a/apps/web/src/hooks/useHandleNewThread.ts
+++ b/apps/web/src/hooks/useHandleNewThread.ts
@@ -190,7 +190,7 @@ export function useNewThreadHandler() {
             reusableStoredDraftThread.draftId,
             {
               threadId: reusableStoredDraftThread.threadId,
-              ...(workspaceContext ?? {}),
+              ...workspaceContext,
               ...(carryRuntimeMode ? { runtimeMode: carryRuntimeMode } : {}),
               ...(carryInteractionMode ? { interactionMode: carryInteractionMode } : {}),
             },
diff --git a/apps/web/src/index.css b/apps/web/src/index.css
index 60f240aec99..6d6375bb5d6 100644
--- a/apps/web/src/index.css
+++ b/apps/web/src/index.css
@@ -79,6 +79,18 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
   --app-scrollbar-width: 6px;
   --app-scrollbar-thumb: rgb(217 217 217);
   --app-scrollbar-thumb-hover: rgb(191 191 191);
+  /*
+   * Compact UI geometry. Keep these values semantic so sidebar, palette,
+   * tooltip, and toolbar controls cannot quietly drift apart.
+   */
+  --control-radius: 0.5rem;
+  --sidebar-content-inset: 0.5rem;
+  --sidebar-control-gap: 0.5rem;
+  --sidebar-icon-color: color-mix(in srgb, var(--sidebar-muted-foreground) 60%, var(--sidebar));
+  --sidebar-row-content-inset: 0.625rem;
+  --command-shell-inset: 0.5rem;
+  --command-content-inset: 1rem;
+  --floating-content-inset: 0.75rem;
   --glass-blur: 12px;
   --glass-opacity: 80%;
   --glass-saturation: 1.14;
@@ -404,6 +416,28 @@ html[data-mobile-composer-route-transition="true"]::view-transition-old(t3-mobil
       var(--app-scrollbar-width) 100%;
   }
 
+  @keyframes settings-search-target-pulse {
+    0%,
+    100% {
+      box-shadow: 0 0 0 0 transparent;
+    }
+    50% {
+      box-shadow: 0 0 0 2px color-mix(in oklab, var(--color-primary) 70%, transparent);
+    }
+  }
+
+  .settings-page-scroll-fade div.settings-search-target-pulse,
+  .settings-page-scroll-fade section.settings-search-target-pulse > div:first-child {
+    animation: settings-search-target-pulse 650ms ease-in-out 2;
+    border-radius: 0.75rem;
+  }
+
+  /* The pulse is the destination indicator; without it (reduced motion), the
+     focus outline takes over, so exactly one indicator shows at a time. */
+  .settings-page-scroll-fade .settings-search-target-pulse:focus {
+    outline: none;
+  }
+
   .workspace-titlebar-controls {
     position: absolute;
     top: var(--workspace-controls-top);
@@ -1095,6 +1129,36 @@ code {
   background: var(--app-scrollbar-thumb-hover);
 }
 
+.t3-ghostty-canvas {
+  cursor: text;
+}
+
+.t3-ghostty-scrollbar {
+  position: absolute;
+  z-index: 1;
+  top: 4px;
+  right: 1px;
+  bottom: 4px;
+  width: var(--app-scrollbar-width);
+  cursor: default;
+  touch-action: none;
+}
+
+.t3-ghostty-scrollbar-thumb {
+  position: absolute;
+  top: 0;
+  right: 1px;
+  left: 1px;
+  border-radius: 3px;
+  background: var(--app-scrollbar-thumb);
+  transition: background-color 120ms ease-out;
+}
+
+.t3-ghostty-scrollbar:hover .t3-ghostty-scrollbar-thumb,
+.t3-ghostty-scrollbar:focus-visible .t3-ghostty-scrollbar-thumb {
+  background: var(--app-scrollbar-thumb-hover);
+}
+
 .model-picker-list::-webkit-scrollbar-track {
   margin-block: 0.5rem;
 }
@@ -1147,20 +1211,6 @@ code {
   display: none;
 }
 
-/* Terminal drawer scrollbar parity with chat */
-.thread-terminal-drawer .xterm .xterm-scrollable-element > .scrollbar.vertical {
-  width: 6px !important;
-}
-
-.thread-terminal-drawer .xterm .xterm-scrollable-element > .scrollbar > .slider {
-  border-radius: 3px;
-}
-
-.thread-terminal-drawer .xterm .xterm-scrollable-element > .scrollbar.vertical > .slider {
-  width: 6px !important;
-  left: 0 !important;
-}
-
 /* Reasoning select -- clickable label surface */
 label:has(> select#reasoning-effort) {
   position: relative;
diff --git a/apps/web/src/keybindings.test.ts b/apps/web/src/keybindings.test.ts
index c0d326edd55..703077e3ef3 100644
--- a/apps/web/src/keybindings.test.ts
+++ b/apps/web/src/keybindings.test.ts
@@ -118,6 +118,16 @@ const DEFAULT_BINDINGS = compile([
     command: "commandPalette.toggle",
     whenAst: whenNot(whenIdentifier("terminalFocus")),
   },
+  {
+    shortcut: modShortcut("p"),
+    command: "filePicker.toggle",
+    whenAst: whenNot(whenIdentifier("terminalFocus")),
+  },
+  {
+    shortcut: modShortcut("f", { shiftKey: true }),
+    command: "projectSearch.toggle",
+    whenAst: whenNot(whenIdentifier("terminalFocus")),
+  },
   {
     shortcut: modShortcut("m", { shiftKey: true }),
     command: "modelPicker.toggle",
@@ -327,6 +337,14 @@ describe("shortcutLabelForCommand", () => {
       shortcutLabelForCommand(DEFAULT_BINDINGS, "commandPalette.toggle", "MacIntel"),
       "⌘K",
     );
+    assert.strictEqual(
+      shortcutLabelForCommand(DEFAULT_BINDINGS, "filePicker.toggle", "MacIntel"),
+      "⌘P",
+    );
+    assert.strictEqual(
+      shortcutLabelForCommand(DEFAULT_BINDINGS, "projectSearch.toggle", "MacIntel"),
+      "⇧⌘F",
+    );
     assert.strictEqual(
       shortcutLabelForCommand(DEFAULT_BINDINGS, "modelPicker.toggle", "Linux"),
       "Ctrl+Shift+M",
@@ -514,6 +532,40 @@ describe("chat/editor shortcuts", () => {
     );
   });
 
+  it("matches filePicker.toggle shortcut outside terminal focus", () => {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "p", metaKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { terminalFocus: false },
+      }),
+      "filePicker.toggle",
+    );
+    assert.notStrictEqual(
+      resolveShortcutCommand(event({ key: "p", metaKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { terminalFocus: true },
+      }),
+      "filePicker.toggle",
+    );
+  });
+
+  it("matches projectSearch.toggle shortcut outside terminal focus", () => {
+    assert.strictEqual(
+      resolveShortcutCommand(event({ key: "f", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { terminalFocus: false },
+      }),
+      "projectSearch.toggle",
+    );
+    assert.notStrictEqual(
+      resolveShortcutCommand(event({ key: "f", metaKey: true, shiftKey: true }), DEFAULT_BINDINGS, {
+        platform: "MacIntel",
+        context: { terminalFocus: true },
+      }),
+      "projectSearch.toggle",
+    );
+  });
+
   it("matches diff.toggle shortcut outside terminal focus", () => {
     assert.isTrue(
       isDiffToggleShortcut(event({ key: "d", metaKey: true }), DEFAULT_BINDINGS, {
diff --git a/apps/web/src/lib/syntaxHighlighting.test.ts b/apps/web/src/lib/syntaxHighlighting.test.ts
new file mode 100644
index 00000000000..1f7ce756b60
--- /dev/null
+++ b/apps/web/src/lib/syntaxHighlighting.test.ts
@@ -0,0 +1,28 @@
+import type { DiffsHighlighter } from "@pierre/diffs";
+import { expect, it, vi } from "vite-plus/test";
+
+const { getSharedHighlighter } = vi.hoisted(() => ({
+  getSharedHighlighter: vi.fn(),
+}));
+
+vi.mock("@pierre/diffs", () => ({
+  getSharedHighlighter,
+}));
+
+import { getSyntaxHighlighterPromise } from "./syntaxHighlighting";
+
+it("caches the recovered text highlighter for unsupported languages", async () => {
+  const textHighlighter = {} as DiffsHighlighter;
+  getSharedHighlighter.mockImplementation(({ langs }: { langs: string[] }) =>
+    langs[0] === "text"
+      ? Promise.resolve(textHighlighter)
+      : Promise.reject(new Error("unsupported language")),
+  );
+
+  const first = getSyntaxHighlighterPromise("unsupported-test-language");
+  await expect(first).resolves.toBe(textHighlighter);
+  const second = getSyntaxHighlighterPromise("unsupported-test-language");
+
+  expect(second).toBe(first);
+  expect(getSharedHighlighter).toHaveBeenCalledTimes(2);
+});
diff --git a/apps/web/src/lib/syntaxHighlighting.ts b/apps/web/src/lib/syntaxHighlighting.ts
new file mode 100644
index 00000000000..171725617e8
--- /dev/null
+++ b/apps/web/src/lib/syntaxHighlighting.ts
@@ -0,0 +1,30 @@
+import {
+  getSharedHighlighter,
+  type DiffsHighlighter,
+  type SupportedLanguages,
+} from "@pierre/diffs";
+
+import { resolveDiffThemeName } from "./diffRendering";
+
+const highlighterPromiseCache = new Map<string, Promise<DiffsHighlighter>>();
+
+export function getSyntaxHighlighterPromise(language: string): Promise<DiffsHighlighter> {
+  const cached = highlighterPromiseCache.get(language);
+  if (cached) return cached;
+
+  const promise = getSharedHighlighter({
+    themes: [resolveDiffThemeName("dark"), resolveDiffThemeName("light")],
+    langs: [language as SupportedLanguages],
+    preferredHighlighter: "shiki-js",
+  }).catch((error) => {
+    if (language === "text") {
+      highlighterPromiseCache.delete(language);
+      // "text" itself failed — Shiki cannot initialize at all, surface the error
+      throw error;
+    }
+    // Language not supported by Shiki — fall back to "text"
+    return getSyntaxHighlighterPromise("text");
+  });
+  highlighterPromiseCache.set(language, promise);
+  return promise;
+}
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index 66dd70bd186..e2b31a08254 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -8,7 +8,6 @@ import { createHashHistory, createBrowserHistory } from "@tanstack/react-router"
 import "@fontsource-variable/dm-sans/index.css";
 import "@fontsource/jetbrains-mono/400.css";
 import "@fontsource/jetbrains-mono/500.css";
-import "@xterm/xterm/css/xterm.css";
 import "./index.css";
 /* fork:begin fork-marker — see .fork/customizations.yaml#fork-marker */
 import "./theme.custom.css";
diff --git a/apps/web/src/modelSelection.test.ts b/apps/web/src/modelSelection.test.ts
index e8fc8a244d0..a35fb752b44 100644
--- a/apps/web/src/modelSelection.test.ts
+++ b/apps/web/src/modelSelection.test.ts
@@ -55,6 +55,24 @@ function settingsWithProviderInstances(): UnifiedSettings {
 }
 
 describe("instance-scoped model selection", () => {
+  it("preserves server-provided legacy model metadata", () => {
+    const baseProvider = provider({
+      instanceId: "claudeAgent",
+      models: ["claude-opus-4-8"],
+    });
+    const providers = [
+      {
+        ...baseProvider,
+        models: [{ ...baseProvider.models[0]!, isLegacy: true }],
+      },
+    ];
+    const stock = deriveProviderInstanceEntries(providers)[0]!;
+
+    expect(getAppModelOptionsForInstance(settingsWithProviderInstances(), stock)[0]?.isLegacy).toBe(
+      true,
+    );
+  });
+
   it("keeps custom models on the provider instance that declared them", () => {
     const providers = [
       provider({
diff --git a/apps/web/src/modelSelection.ts b/apps/web/src/modelSelection.ts
index 72c5eb14cc2..2763245299d 100644
--- a/apps/web/src/modelSelection.ts
+++ b/apps/web/src/modelSelection.ts
@@ -76,6 +76,7 @@ export interface AppModelOption {
   subProvider?: string;
   isCustom: boolean;
   isDefault?: boolean;
+  isLegacy?: boolean;
 }
 
 function toAppModelOption(model: ServerProvider["models"][number]): AppModelOption {
@@ -87,6 +88,7 @@ function toAppModelOption(model: ServerProvider["models"][number]): AppModelOpti
   if (model.shortName) option.shortName = model.shortName;
   if (model.subProvider) option.subProvider = model.subProvider;
   if (model.isDefault) option.isDefault = true;
+  if (model.isLegacy) option.isLegacy = true;
   return option;
 }
 
diff --git a/apps/web/src/state/projects.ts b/apps/web/src/state/projects.ts
index 7a879988328..d4e1098a364 100644
--- a/apps/web/src/state/projects.ts
+++ b/apps/web/src/state/projects.ts
@@ -1,11 +1,24 @@
 import { createEnvironmentProjectAtoms } from "@t3tools/client-runtime/state/projects";
 import { createProjectEnvironmentAtoms } from "@t3tools/client-runtime/state/projects";
+import { createEnvironmentRpcQueryAtomFamily } from "@t3tools/client-runtime/state/runtime";
+import { WS_METHODS } from "@t3tools/contracts";
 
 import { environmentCatalog } from "../connection/catalog";
 import { connectionAtomRuntime } from "../connection/runtime";
 import { environmentSnapshotAtom } from "./shell";
 
 export const projectEnvironment = createProjectEnvironmentAtoms(connectionAtomRuntime);
+/**
+ * Web-only: project content search backs the ⇧⌘F dialog, which has no mobile
+ * surface, so the atom family lives here instead of the shared client-runtime
+ * project atoms consumed by the mobile app.
+ */
+export const projectContentSearch = createEnvironmentRpcQueryAtomFamily(connectionAtomRuntime, {
+  label: "environment-data:projects:search-contents",
+  tag: WS_METHODS.projectsSearchContents,
+  staleTimeMs: 5_000,
+  idleTtlMs: 60_000,
+});
 export const environmentProjects = createEnvironmentProjectAtoms({
   catalogValueAtom: environmentCatalog.catalogValueAtom,
   snapshotAtom: environmentSnapshotAtom,
diff --git a/apps/web/src/state/queries.test.ts b/apps/web/src/state/queries.test.ts
new file mode 100644
index 00000000000..f8887dfb8ef
--- /dev/null
+++ b/apps/web/src/state/queries.test.ts
@@ -0,0 +1,25 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vite-plus/test";
+
+import { areProjectPathSearchTargetsEqual } from "./queries";
+
+describe("areProjectPathSearchTargetsEqual", () => {
+  const target = {
+    environmentId: EnvironmentId.make("environment-a"),
+    cwd: "/project-a",
+    query: "index",
+  };
+
+  it("requires the environment, workspace, query, and entry kind to match", () => {
+    expect(areProjectPathSearchTargetsEqual(target, target)).toBe(true);
+    expect(
+      areProjectPathSearchTargetsEqual(target, {
+        ...target,
+        environmentId: EnvironmentId.make("environment-b"),
+      }),
+    ).toBe(false);
+    expect(areProjectPathSearchTargetsEqual(target, { ...target, cwd: "/project-b" })).toBe(false);
+    expect(areProjectPathSearchTargetsEqual(target, { ...target, query: "readme" })).toBe(false);
+    expect(areProjectPathSearchTargetsEqual(target, { ...target, kind: "file" })).toBe(false);
+  });
+});
diff --git a/apps/web/src/state/queries.ts b/apps/web/src/state/queries.ts
index a9564c2fd64..2a095b8f584 100644
--- a/apps/web/src/state/queries.ts
+++ b/apps/web/src/state/queries.ts
@@ -12,6 +12,8 @@ import { type VcsRefTarget } from "@t3tools/client-runtime/state/vcs";
 import type {
   EnvironmentId,
   OrchestrationThread,
+  ProjectContentMatch,
+  ProjectEntryKind,
   ThreadId,
   VcsListRefsResult,
   VcsRef,
@@ -24,16 +26,19 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { appAtomRegistry } from "../rpc/atomRegistry";
 import { orchestrationEnvironment } from "./orchestration";
 import { isPaginatedBranchesNextPagePending } from "./paginatedBranches";
-import { projectEnvironment } from "./projects";
+import { projectContentSearch, projectEnvironment } from "./projects";
 import { useEnvironmentQuery } from "./query";
 import { useEnvironmentThread } from "./threads";
 import { vcsEnvironment } from "./vcs";
 
-const COMPOSER_PATH_SEARCH_DEBOUNCE_MS = 120;
+const PROJECT_PATH_SEARCH_DEBOUNCE_MS = 120;
 const COMPOSER_PATH_SEARCH_LIMIT = 80;
+const PROJECT_CONTENT_SEARCH_DEBOUNCE_MS = 120;
+const PROJECT_CONTENT_SEARCH_LIMIT = 500;
 const THREAD_SEARCH_DEBOUNCE_MS = 200;
 const VCS_REF_LIST_LIMIT = 100;
 const EMPTY_REFS: ReadonlyArray<VcsRef> = [];
+const EMPTY_CONTENT_MATCHES: ReadonlyArray<ProjectContentMatch> = [];
 const INITIAL_BRANCH_CURSORS = [undefined] as const;
 const EMPTY_THREAD_SEARCH_MATCHES: ReadonlyArray<EnvironmentThreadSearchMatch> = Object.freeze([]);
 const EMPTY_THREAD_SEARCH_ATOM = Atom.make({
@@ -229,26 +234,50 @@ export function usePaginatedBranches(target: VcsRefTarget) {
   };
 }
 
-export function useComposerPathSearch(target: ComposerPathSearchTarget) {
+type ProjectPathSearchTarget = ComposerPathSearchTarget & {
+  readonly kind?: ProjectEntryKind | undefined;
+};
+
+export function areProjectPathSearchTargetsEqual(
+  left: ProjectPathSearchTarget,
+  right: ProjectPathSearchTarget,
+): boolean {
+  return (
+    left.environmentId === right.environmentId &&
+    left.cwd === right.cwd &&
+    left.query === right.query &&
+    left.kind === right.kind
+  );
+}
+
+export function useProjectPathSearch(
+  target: ProjectPathSearchTarget,
+  limit: number,
+  options?: { readonly allowEmptyQuery?: boolean },
+) {
+  const allowEmptyQuery = options?.allowEmptyQuery === true;
   const normalizedTarget = useMemo(
     () => ({
       environmentId: target.environmentId,
       cwd: target.cwd,
-      query: target.query?.trim() ?? "",
+      query: target.query == null ? null : target.query.trim(),
+      kind: target.kind,
     }),
-    [target.cwd, target.environmentId, target.query],
+    [target.cwd, target.environmentId, target.kind, target.query],
   );
-  const debouncedTarget = useDebouncedValue(normalizedTarget, COMPOSER_PATH_SEARCH_DEBOUNCE_MS);
+  const debouncedTarget = useDebouncedValue(normalizedTarget, PROJECT_PATH_SEARCH_DEBOUNCE_MS);
   const result = useEnvironmentQuery(
     debouncedTarget.environmentId !== null &&
       debouncedTarget.cwd !== null &&
-      debouncedTarget.query.length > 0
+      debouncedTarget.query !== null &&
+      (allowEmptyQuery || debouncedTarget.query.length > 0)
       ? projectEnvironment.searchEntries({
           environmentId: debouncedTarget.environmentId,
           input: {
             cwd: debouncedTarget.cwd,
             query: debouncedTarget.query,
-            limit: COMPOSER_PATH_SEARCH_LIMIT,
+            limit,
+            ...(debouncedTarget.kind ? { kind: debouncedTarget.kind } : {}),
           },
         })
       : null,
@@ -257,11 +286,61 @@ export function useComposerPathSearch(target: ComposerPathSearchTarget) {
   return {
     entries: result.data?.entries ?? [],
     error: result.error,
-    isPending: normalizedTarget.query !== debouncedTarget.query || result.isPending,
+    isPending:
+      !areProjectPathSearchTargetsEqual(normalizedTarget, debouncedTarget) || result.isPending,
+    searchedQuery: debouncedTarget.query ?? "",
     refresh: result.refresh,
   };
 }
 
+export function useComposerPathSearch(target: ComposerPathSearchTarget) {
+  return useProjectPathSearch(target, COMPOSER_PATH_SEARCH_LIMIT);
+}
+
+interface ProjectContentSearchTarget {
+  readonly environmentId: EnvironmentId | null;
+  readonly cwd: string | null;
+  readonly query: string;
+  readonly caseSensitive: boolean;
+  readonly wholeWord: boolean;
+  readonly useRegex: boolean;
+}
+
+export function useProjectContentSearch(target: ProjectContentSearchTarget) {
+  // Whitespace is significant in content queries; trimming is only used to
+  // decide whether the input is blank.
+  const query = target.query;
+  const hasQuery = query.trim().length > 0;
+  const debouncedQuery = useDebouncedValue(query, PROJECT_CONTENT_SEARCH_DEBOUNCE_MS);
+  const result = useEnvironmentQuery(
+    target.environmentId !== null &&
+      target.cwd !== null &&
+      hasQuery &&
+      debouncedQuery.trim().length > 0
+      ? projectContentSearch({
+          environmentId: target.environmentId,
+          input: {
+            cwd: target.cwd,
+            query: debouncedQuery,
+            limit: PROJECT_CONTENT_SEARCH_LIMIT,
+            caseSensitive: target.caseSensitive,
+            wholeWord: target.wholeWord,
+            useRegex: target.useRegex,
+          },
+        })
+      : null,
+  );
+
+  return {
+    matches: result.data?.matches ?? EMPTY_CONTENT_MATCHES,
+    error: result.error,
+    isPending: hasQuery && (query !== debouncedQuery || result.isPending),
+    hasQuery,
+    truncated: result.data?.truncated ?? false,
+    invalidRegex: target.useRegex && result.data?.regexFallbackError !== undefined,
+  };
+}
+
 export function useCheckpointDiff(
   target: CheckpointDiffTarget,
   options?: { readonly enabled?: boolean },
diff --git a/apps/web/src/terminal/ghostty/README.md b/apps/web/src/terminal/ghostty/README.md
new file mode 100644
index 00000000000..37e1c52fb0c
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/README.md
@@ -0,0 +1,19 @@
+# Ghostty web terminal
+
+This directory is the browser adapter for the same official `libghostty-vt` C ABI used by Android.
+It is intentionally not an xterm compatibility layer.
+
+- `runtime.ts` owns the singleton WebAssembly instance and runtime ABI layouts.
+- `ghostty-write-pty.wasm` is a 112-byte callback trampoline for terminal-generated PTY replies.
+- `core.ts` owns per-terminal Ghostty handles and translates the C ABI into render snapshots.
+- `renderer.ts` batches backgrounds and style runs into a Canvas 2D frame.
+- `surface.ts` owns browser input, IME, selection, scrolling, sizing, links, and cursor blinking.
+- `fonts/` vendors the symbols-only Nerd Font (MIT) the surface registers lazily, so
+  prompt glyphs render without a locally installed Nerd Font.
+- `vendor/` holds only the artifacts, reproducibly generated by
+  `apps/web/scripts/build-libghostty-wasm.sh`. The upstream pin and license live once, at
+  `native/libghostty-vt/` at the repository root; the wasm embeds the pinned revision
+  in its build info and the ABI test verifies it against mobile's `VERSION`.
+
+Keep browser behavior here and terminal transport in the existing client runtime. Do not add React
+state to the render loop. Both WASM artifacts are ordinary read-only assets, not executables.
diff --git a/apps/web/src/terminal/ghostty/core.ts b/apps/web/src/terminal/ghostty/core.ts
new file mode 100644
index 00000000000..204a94b6a8c
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/core.ts
@@ -0,0 +1,1189 @@
+import {
+  type GhosttyKeyboardLayoutMap,
+  ghosttyKeyForCode,
+  ghosttyUnshiftedCodepoint,
+  loadGhosttyKeyboardLayoutMap,
+} from "./keyCodes";
+import { GhosttyRuntime, loadGhosttyRuntime } from "./runtime";
+
+const GHOSTTY_SUCCESS = 0;
+const GHOSTTY_OUT_OF_SPACE = -3;
+const MAX_SCROLLBACK_ROWS = 10_000;
+// wasm32 C ABI layout for GhosttyTerminalSelectionFormatOptions at the
+// libghostty-vt revision pinned alongside this module.
+const SELECTION_FORMAT_OPTIONS_SIZE = 16;
+
+const RENDER_DATA = {
+  cols: 1,
+  rows: 2,
+  dirty: 3,
+  rowIterator: 4,
+  background: 5,
+  foreground: 6,
+  cursor: 7,
+  cursorHasValue: 8,
+  cursorStyle: 10,
+  cursorVisible: 11,
+  cursorBlinking: 12,
+  cursorInViewport: 14,
+  cursorX: 15,
+  cursorY: 16,
+} as const;
+
+const ROW_DATA = {
+  dirty: 1,
+  raw: 2,
+  cells: 3,
+} as const;
+
+const CELL_DATA = {
+  raw: 1,
+  style: 2,
+  graphemesLength: 3,
+  graphemes: 4,
+  background: 5,
+  foreground: 6,
+  selected: 7,
+} as const;
+
+const RAW_CELL_DATA = {
+  wide: 3,
+} as const;
+
+export const GHOSTTY_CELL_WIDE = {
+  narrow: 0,
+  wide: 1,
+  spacerTail: 2,
+  spacerHead: 3,
+} as const;
+
+export interface GhosttyColor {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+}
+
+export interface GhosttyTheme {
+  readonly foreground: GhosttyColor;
+  readonly background: GhosttyColor;
+  readonly cursor: GhosttyColor;
+  /** CSS color the renderer overlays on selected cells; not sent to Ghostty. */
+  readonly selectionBackground?: string;
+}
+
+export interface GhosttyCell {
+  readonly text: string;
+  readonly wide: number;
+  readonly foreground: GhosttyColor;
+  readonly background: GhosttyColor;
+  readonly bold: boolean;
+  readonly italic: boolean;
+  readonly invisible: boolean;
+  readonly strikethrough: boolean;
+  readonly overline: boolean;
+  readonly underline: boolean;
+  readonly selected: boolean;
+}
+
+export interface GhosttyRow {
+  readonly cells: readonly GhosttyCell[];
+  readonly text: string;
+  readonly isWrapContinuation: boolean;
+  /** Whether this row soft-wraps onto the next row. */
+  readonly wrapsToNext: boolean;
+}
+
+export interface GhosttySnapshot {
+  readonly cols: number;
+  readonly rows: number;
+  readonly foreground: GhosttyColor;
+  readonly background: GhosttyColor;
+  readonly cursor: GhosttyColor;
+  readonly cursorX: number;
+  readonly cursorY: number;
+  readonly cursorVisible: boolean;
+  readonly cursorBlinking: boolean;
+  readonly cursorStyle: number;
+  readonly dirtyRows: ReadonlySet<number>;
+  readonly rowData: readonly GhosttyRow[];
+}
+
+export interface GhosttySelectionRange {
+  readonly viewport: {
+    readonly start: { readonly x: number; readonly y: number };
+    readonly end: { readonly x: number; readonly y: number };
+  };
+  readonly screen: {
+    readonly start: { readonly x: number; readonly y: number };
+    readonly end: { readonly x: number; readonly y: number };
+  };
+}
+
+export interface GhosttyScrollbar {
+  readonly total: number;
+  readonly offset: number;
+  readonly len: number;
+}
+
+/** Grid position tagged with its Ghostty coordinate space: 1 viewport, 2 screen. */
+export interface GhosttyPointInput {
+  readonly x: number;
+  readonly y: number;
+  readonly tag?: 1 | 2;
+}
+
+export interface GhosttyMouseInput {
+  readonly action: "press" | "release" | "motion";
+  readonly button: number | null;
+  readonly mods: number;
+  readonly x: number;
+  readonly y: number;
+  readonly screenWidth: number;
+  readonly screenHeight: number;
+  readonly cellWidth: number;
+  readonly cellHeight: number;
+  readonly paddingLeft: number;
+  readonly paddingRight: number;
+  readonly paddingTop: number;
+  readonly paddingBottom: number;
+  readonly anyButtonPressed: boolean;
+}
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+function blend(foreground: GhosttyColor, background: GhosttyColor): GhosttyColor {
+  const channel = (front: number, back: number) => Math.floor((front * 155 + back * 100) / 255);
+  return {
+    r: channel(foreground.r, background.r),
+    g: channel(foreground.g, background.g),
+    b: channel(foreground.b, background.b),
+  };
+}
+
+function sameColor(left: GhosttyColor, right: GhosttyColor): boolean {
+  return left.r === right.r && left.g === right.g && left.b === right.b;
+}
+
+export class GhosttyTerminalCore {
+  private readonly runtime: GhosttyRuntime;
+  private terminalSlot = 0;
+  private terminal = 0;
+  private renderStateSlot = 0;
+  private renderState = 0;
+  private rowIteratorSlot = 0;
+  private rowCellsSlot = 0;
+  private keyEncoderSlot = 0;
+  private keyEncoder = 0;
+  private keyEventSlot = 0;
+  private keyEvent = 0;
+  private mouseEncoderSlot = 0;
+  private mouseEncoder = 0;
+  private mouseEventSlot = 0;
+  private mouseEvent = 0;
+  private ptyWriterId = 0;
+  private ptyWriter: ((data: string) => void) | null = null;
+  private scratch = 0;
+  private style = 0;
+  private scrollbar = 0;
+  private rows: GhosttyRow[] = [];
+  private disposed = false;
+  private keyboardLayoutMap: GhosttyKeyboardLayoutMap | undefined;
+
+  private constructor(runtime: GhosttyRuntime) {
+    this.runtime = runtime;
+    void loadGhosttyKeyboardLayoutMap().then((layoutMap) => {
+      if (!this.disposed) this.keyboardLayoutMap = layoutMap;
+    });
+  }
+
+  static async create(
+    cols: number,
+    rows: number,
+    cellWidth: number,
+    cellHeight: number,
+    theme: GhosttyTheme,
+    onPtyData: (data: string) => void,
+  ): Promise<GhosttyTerminalCore> {
+    const core = new GhosttyTerminalCore(await loadGhosttyRuntime());
+    try {
+      core.initialize(cols, rows, cellWidth, cellHeight, theme, onPtyData);
+      return core;
+    } catch (error) {
+      core.dispose();
+      throw error;
+    }
+  }
+
+  private initialize(
+    cols: number,
+    rows: number,
+    cellWidth: number,
+    cellHeight: number,
+    theme: GhosttyTheme,
+    onPtyData: (data: string) => void,
+  ): void {
+    const optionsSize = this.runtime.layout("GhosttyTerminalOptions").size;
+    const options = this.runtime.alloc(optionsSize);
+    this.runtime.setField(options, "GhosttyTerminalOptions", "cols", cols);
+    this.runtime.setField(options, "GhosttyTerminalOptions", "rows", rows);
+    this.runtime.setField(options, "GhosttyTerminalOptions", "max_scrollback", MAX_SCROLLBACK_ROWS);
+    this.terminalSlot = this.runtime.allocOpaque();
+    const terminalResult = this.runtime.call("ghostty_terminal_new", 0, this.terminalSlot, options);
+    this.runtime.free(options, optionsSize);
+    this.assertSuccess("ghostty_terminal_new", terminalResult);
+    this.terminal = this.runtime.readPointer(this.terminalSlot);
+    this.ptyWriter = onPtyData;
+    this.ptyWriterId = this.runtime.attachPtyWriter(this.terminal, onPtyData);
+
+    this.renderStateSlot = this.runtime.allocOpaque();
+    this.assertSuccess(
+      "ghostty_render_state_new",
+      this.runtime.call("ghostty_render_state_new", 0, this.renderStateSlot),
+    );
+    this.renderState = this.runtime.readPointer(this.renderStateSlot);
+
+    this.rowIteratorSlot = this.runtime.allocOpaque();
+    this.assertSuccess(
+      "ghostty_render_state_row_iterator_new",
+      this.runtime.call("ghostty_render_state_row_iterator_new", 0, this.rowIteratorSlot),
+    );
+    this.rowCellsSlot = this.runtime.allocOpaque();
+    this.assertSuccess(
+      "ghostty_render_state_row_cells_new",
+      this.runtime.call("ghostty_render_state_row_cells_new", 0, this.rowCellsSlot),
+    );
+
+    this.keyEncoderSlot = this.runtime.allocOpaque();
+    this.assertSuccess(
+      "ghostty_key_encoder_new",
+      this.runtime.call("ghostty_key_encoder_new", 0, this.keyEncoderSlot),
+    );
+    this.keyEncoder = this.runtime.readPointer(this.keyEncoderSlot);
+    this.keyEventSlot = this.runtime.allocOpaque();
+    this.assertSuccess(
+      "ghostty_key_event_new",
+      this.runtime.call("ghostty_key_event_new", 0, this.keyEventSlot),
+    );
+    this.keyEvent = this.runtime.readPointer(this.keyEventSlot);
+
+    this.mouseEncoderSlot = this.runtime.allocOpaque();
+    this.assertSuccess(
+      "ghostty_mouse_encoder_new",
+      this.runtime.call("ghostty_mouse_encoder_new", 0, this.mouseEncoderSlot),
+    );
+    this.mouseEncoder = this.runtime.readPointer(this.mouseEncoderSlot);
+    this.mouseEventSlot = this.runtime.allocOpaque();
+    this.assertSuccess(
+      "ghostty_mouse_event_new",
+      this.runtime.call("ghostty_mouse_event_new", 0, this.mouseEventSlot),
+    );
+    this.mouseEvent = this.runtime.readPointer(this.mouseEventSlot);
+
+    this.scratch = this.runtime.alloc(16);
+    const styleSize = this.runtime.layout("GhosttyStyle").size;
+    this.style = this.runtime.alloc(styleSize);
+    this.runtime.setField(this.style, "GhosttyStyle", "size", styleSize);
+    this.scrollbar = this.runtime.alloc(this.runtime.layout("GhosttyTerminalScrollbar").size);
+    this.setTheme(theme);
+    this.resize(cols, rows, cellWidth, cellHeight);
+  }
+
+  write(data: string | Uint8Array): void {
+    this.ensureActive();
+    const bytes = typeof data === "string" ? encoder.encode(data) : data;
+    if (bytes.length === 0) return;
+    const pointer = this.runtime.alloc(bytes.length);
+    this.runtime.bytes(pointer, bytes.length).set(bytes);
+    this.runtime.call("ghostty_terminal_vt_write", this.terminal, pointer, bytes.length);
+    this.runtime.free(pointer, bytes.length);
+  }
+
+  resetAndWrite(data: string): void {
+    this.ensureActive();
+    this.runtime.call("ghostty_terminal_reset", this.terminal);
+    this.rows = [];
+    if (data.length === 0) return;
+    const writer = this.ptyWriter;
+    if (this.ptyWriterId !== 0) {
+      this.runtime.detachPtyWriter(this.terminal, this.ptyWriterId);
+      this.ptyWriterId = 0;
+    }
+    try {
+      this.write(data);
+    } finally {
+      if (writer !== null && !this.disposed) {
+        this.ptyWriterId = this.runtime.attachPtyWriter(this.terminal, writer);
+      }
+    }
+  }
+
+  resize(cols: number, rows: number, cellWidth: number, cellHeight: number): void {
+    this.ensureActive();
+    this.assertSuccess(
+      "ghostty_terminal_resize",
+      this.runtime.call(
+        "ghostty_terminal_resize",
+        this.terminal,
+        Math.max(1, Math.min(65_535, cols)),
+        Math.max(1, Math.min(65_535, rows)),
+        Math.max(1, Math.round(cellWidth)),
+        Math.max(1, Math.round(cellHeight)),
+      ),
+    );
+  }
+
+  setTheme(theme: GhosttyTheme): void {
+    this.ensureActive();
+    const color = this.runtime.alloc(3);
+    for (const [option, value] of [
+      [11, theme.foreground],
+      [12, theme.background],
+      [13, theme.cursor],
+    ] as const) {
+      this.runtime.bytes(color, 3).set([value.r, value.g, value.b]);
+      this.runtime.call("ghostty_terminal_set", this.terminal, option, color);
+    }
+    this.runtime.free(color, 3);
+  }
+
+  scroll(deltaRows: number): void {
+    this.ensureActive();
+    const layout = this.runtime.layout("GhosttyTerminalScrollViewport");
+    const scroll = this.runtime.alloc(layout.size);
+    this.runtime.setField(scroll, "GhosttyTerminalScrollViewport", "tag", 2);
+    const value = layout.fields.value!;
+    this.runtime.view(scroll + value.offset, value.size).setInt32(0, deltaRows, true);
+    this.runtime.call("ghostty_terminal_scroll_viewport", this.terminal, scroll);
+    this.runtime.free(scroll, layout.size);
+  }
+
+  scrollToBottom(): void {
+    this.ensureActive();
+    const layout = this.runtime.layout("GhosttyTerminalScrollViewport");
+    const scroll = this.runtime.alloc(layout.size);
+    this.runtime.setField(scroll, "GhosttyTerminalScrollViewport", "tag", 1);
+    this.runtime.call("ghostty_terminal_scroll_viewport", this.terminal, scroll);
+    this.runtime.free(scroll, layout.size);
+  }
+
+  isViewportActive(): boolean {
+    this.ensureActive();
+    this.runtime.bytes(this.scratch, 1)[0] = 0;
+    return (
+      this.runtime.call("ghostty_terminal_get", this.terminal, 32, this.scratch) ===
+        GHOSTTY_SUCCESS && this.runtime.bytes(this.scratch, 1)[0] !== 0
+    );
+  }
+
+  scrollbarState(): GhosttyScrollbar | null {
+    this.ensureActive();
+    const layout = this.runtime.layout("GhosttyTerminalScrollbar");
+    this.runtime.bytes(this.scrollbar, layout.size).fill(0);
+    if (
+      this.runtime.call("ghostty_terminal_get", this.terminal, 9, this.scrollbar) !==
+      GHOSTTY_SUCCESS
+    ) {
+      return null;
+    }
+    return {
+      total: this.runtime.readField(this.scrollbar, "GhosttyTerminalScrollbar", "total"),
+      offset: this.runtime.readField(this.scrollbar, "GhosttyTerminalScrollbar", "offset"),
+      len: this.runtime.readField(this.scrollbar, "GhosttyTerminalScrollbar", "len"),
+    };
+  }
+
+  isMouseTracking(): boolean {
+    this.ensureActive();
+    this.runtime.bytes(this.scratch, 1)[0] = 0;
+    return (
+      this.runtime.call("ghostty_terminal_get", this.terminal, 11, this.scratch) ===
+        GHOSTTY_SUCCESS && this.runtime.bytes(this.scratch, 1)[0] !== 0
+    );
+  }
+
+  isMouseAnyEventTracking(): boolean {
+    this.ensureActive();
+    this.runtime.bytes(this.scratch, 1)[0] = 0;
+    return (
+      this.runtime.call("ghostty_terminal_mode_get", this.terminal, 1003, this.scratch) ===
+        GHOSTTY_SUCCESS && this.runtime.bytes(this.scratch, 1)[0] !== 0
+    );
+  }
+
+  isAlternateScreen(): boolean {
+    this.ensureActive();
+    this.runtime.bytes(this.scratch, 4).fill(0);
+    return (
+      this.runtime.call("ghostty_terminal_get", this.terminal, 6, this.scratch) ===
+        GHOSTTY_SUCCESS && this.runtime.view(this.scratch, 4).getUint32(0, true) === 1
+    );
+  }
+
+  isApplicationCursorKeys(): boolean {
+    this.ensureActive();
+    this.runtime.bytes(this.scratch, 1)[0] = 0;
+    return (
+      this.runtime.call("ghostty_terminal_mode_get", this.terminal, 1, this.scratch) ===
+        GHOSTTY_SUCCESS && this.runtime.bytes(this.scratch, 1)[0] !== 0
+    );
+  }
+
+  encodeKey(event: KeyboardEvent, action: "press" | "release" = "press"): string {
+    this.ensureActive();
+    this.runtime.call("ghostty_key_encoder_setopt_from_terminal", this.keyEncoder, this.terminal);
+    this.runtime.call(
+      "ghostty_key_event_set_action",
+      this.keyEvent,
+      action === "release" ? 0 : event.repeat ? 2 : 1,
+    );
+    this.runtime.call("ghostty_key_event_set_key", this.keyEvent, ghosttyKeyForCode(event.code));
+    const mods =
+      (event.shiftKey ? 1 : 0) |
+      (event.ctrlKey ? 1 << 1 : 0) |
+      (event.altKey ? 1 << 2 : 0) |
+      (event.metaKey ? 1 << 3 : 0) |
+      (event.getModifierState("CapsLock") ? 1 << 4 : 0) |
+      (event.getModifierState("NumLock") ? 1 << 5 : 0);
+    this.runtime.call("ghostty_key_event_set_mods", this.keyEvent, mods);
+    this.runtime.call("ghostty_key_event_set_consumed_mods", this.keyEvent, 0);
+    this.runtime.call("ghostty_key_event_set_composing", this.keyEvent, event.isComposing ? 1 : 0);
+    this.runtime.call(
+      "ghostty_key_event_set_unshifted_codepoint",
+      this.keyEvent,
+      ghosttyUnshiftedCodepoint(event, this.keyboardLayoutMap),
+    );
+
+    const text = event.key.length === 1 ? event.key : "";
+    const textBytes = encoder.encode(text);
+    const textPointer = textBytes.length === 0 ? 0 : this.runtime.alloc(textBytes.length);
+    if (textPointer !== 0) this.runtime.bytes(textPointer, textBytes.length).set(textBytes);
+    this.runtime.call("ghostty_key_event_set_utf8", this.keyEvent, textPointer, textBytes.length);
+
+    const written = this.runtime.call("ghostty_wasm_alloc_usize");
+    const encoded = this.encodeOutput(written, (output, outputSize) =>
+      this.runtime.call(
+        "ghostty_key_encoder_encode",
+        this.keyEncoder,
+        this.keyEvent,
+        output,
+        outputSize,
+        written,
+      ),
+    );
+    this.runtime.call("ghostty_wasm_free_usize", written);
+    if (textPointer !== 0) this.runtime.free(textPointer, textBytes.length);
+    return encoded;
+  }
+
+  encodePaste(data: string): string {
+    this.ensureActive();
+    const input = encoder.encode(data);
+    if (input.length === 0) return "";
+    const inputPointer = this.runtime.alloc(input.length);
+    this.runtime.bytes(inputPointer, input.length).set(input);
+    this.runtime.bytes(this.scratch, 1)[0] = 0;
+    const bracketed =
+      this.runtime.call("ghostty_terminal_mode_get", this.terminal, 2004, this.scratch) ===
+        GHOSTTY_SUCCESS && this.runtime.bytes(this.scratch, 1)[0] !== 0;
+    const written = this.runtime.call("ghostty_wasm_alloc_usize");
+    let encoded = "";
+    const sizeResult = this.runtime.call(
+      "ghostty_paste_encode",
+      inputPointer,
+      input.length,
+      bracketed ? 1 : 0,
+      0,
+      0,
+      written,
+    );
+    const outputSize = this.runtime.view(written, 4).getUint32(0, true);
+    if (sizeResult === GHOSTTY_OUT_OF_SPACE && outputSize > 0) {
+      const output = this.runtime.alloc(outputSize);
+      const result = this.runtime.call(
+        "ghostty_paste_encode",
+        inputPointer,
+        input.length,
+        bracketed ? 1 : 0,
+        output,
+        outputSize,
+        written,
+      );
+      const outputLength = this.runtime.view(written, 4).getUint32(0, true);
+      encoded =
+        result === GHOSTTY_SUCCESS ? decoder.decode(this.runtime.bytes(output, outputLength)) : "";
+      this.runtime.free(output, outputSize);
+    }
+    this.runtime.call("ghostty_wasm_free_usize", written);
+    this.runtime.free(inputPointer, input.length);
+    return encoded;
+  }
+
+  encodeMouse(input: GhosttyMouseInput): string {
+    this.ensureActive();
+    this.runtime.call(
+      "ghostty_mouse_encoder_setopt_from_terminal",
+      this.mouseEncoder,
+      this.terminal,
+    );
+
+    const sizeLayout = this.runtime.layout("GhosttyMouseEncoderSize");
+    const size = this.runtime.alloc(sizeLayout.size);
+    for (const [field, value] of [
+      ["size", sizeLayout.size],
+      ["screen_width", input.screenWidth],
+      ["screen_height", input.screenHeight],
+      ["cell_width", input.cellWidth],
+      ["cell_height", input.cellHeight],
+      ["padding_top", input.paddingTop],
+      ["padding_bottom", input.paddingBottom],
+      ["padding_right", input.paddingRight],
+      ["padding_left", input.paddingLeft],
+    ] as const) {
+      this.runtime.setField(size, "GhosttyMouseEncoderSize", field, Math.max(0, Math.round(value)));
+    }
+    this.runtime.call("ghostty_mouse_encoder_setopt", this.mouseEncoder, 2, size);
+    this.runtime.free(size, sizeLayout.size);
+
+    this.runtime.bytes(this.scratch, 1)[0] = input.anyButtonPressed ? 1 : 0;
+    this.runtime.call("ghostty_mouse_encoder_setopt", this.mouseEncoder, 3, this.scratch);
+    this.runtime.bytes(this.scratch, 1)[0] = 1;
+    this.runtime.call("ghostty_mouse_encoder_setopt", this.mouseEncoder, 4, this.scratch);
+
+    this.runtime.call(
+      "ghostty_mouse_event_set_action",
+      this.mouseEvent,
+      input.action === "press" ? 0 : input.action === "release" ? 1 : 2,
+    );
+    if (input.button === null) {
+      this.runtime.call("ghostty_mouse_event_clear_button", this.mouseEvent);
+    } else {
+      this.runtime.call("ghostty_mouse_event_set_button", this.mouseEvent, input.button);
+    }
+    this.runtime.call("ghostty_mouse_event_set_mods", this.mouseEvent, input.mods);
+    const positionLayout = this.runtime.layout("GhosttyMousePosition");
+    const position = this.runtime.alloc(positionLayout.size);
+    const positionView = this.runtime.view(position, positionLayout.size);
+    positionView.setFloat32(positionLayout.fields.x!.offset, input.x, true);
+    positionView.setFloat32(positionLayout.fields.y!.offset, input.y, true);
+    this.runtime.call("ghostty_mouse_event_set_position", this.mouseEvent, position);
+    this.runtime.free(position, positionLayout.size);
+
+    const written = this.runtime.call("ghostty_wasm_alloc_usize");
+    const encoded = this.encodeOutput(written, (output, outputSize) =>
+      this.runtime.call(
+        "ghostty_mouse_encoder_encode",
+        this.mouseEncoder,
+        this.mouseEvent,
+        output,
+        outputSize,
+        written,
+      ),
+    );
+    this.runtime.call("ghostty_wasm_free_usize", written);
+    return encoded;
+  }
+
+  setSelection(anchor: GhosttyPointInput, end: GhosttyPointInput): void {
+    this.ensureActive();
+    const selectionLayout = this.runtime.layout("GhosttySelection");
+    const gridRefSize = this.runtime.layout("GhosttyGridRef").size;
+    const selection = this.runtime.alloc(selectionLayout.size);
+    let start = 0;
+    let endRef = 0;
+    try {
+      this.runtime.setField(selection, "GhosttySelection", "size", selectionLayout.size);
+      start = this.gridRef(anchor.x, anchor.y, anchor.tag ?? 1);
+      endRef = this.gridRef(end.x, end.y, end.tag ?? 1);
+      const startField = selectionLayout.fields.start!;
+      const endField = selectionLayout.fields.end!;
+      this.runtime
+        .bytes(selection + startField.offset, startField.size)
+        .set(this.runtime.bytes(start, startField.size));
+      this.runtime
+        .bytes(selection + endField.offset, endField.size)
+        .set(this.runtime.bytes(endRef, endField.size));
+      this.runtime.call("ghostty_terminal_set", this.terminal, 21, selection);
+    } finally {
+      this.runtime.free(start, gridRefSize);
+      this.runtime.free(endRef, gridRefSize);
+      this.runtime.free(selection, selectionLayout.size);
+    }
+  }
+
+  selectAll(): void {
+    this.ensureActive();
+    const layout = this.runtime.layout("GhosttySelection");
+    const selection = this.runtime.alloc(layout.size);
+    this.runtime.setField(selection, "GhosttySelection", "size", layout.size);
+    if (
+      this.runtime.call("ghostty_terminal_select_all", this.terminal, selection) === GHOSTTY_SUCCESS
+    ) {
+      this.runtime.call("ghostty_terminal_set", this.terminal, 21, selection);
+    }
+    this.runtime.free(selection, layout.size);
+  }
+
+  selectWord(col: number, row: number): GhosttySelectionRange | null {
+    return this.selectAt(
+      "GhosttyTerminalSelectWordOptions",
+      "ghostty_terminal_select_word",
+      col,
+      row,
+    );
+  }
+
+  selectLine(col: number, row: number): GhosttySelectionRange | null {
+    return this.selectAt(
+      "GhosttyTerminalSelectLineOptions",
+      "ghostty_terminal_select_line",
+      col,
+      row,
+    );
+  }
+
+  hyperlinkAt(col: number, row: number): string | null {
+    this.ensureActive();
+    const ref = this.gridRef(col, row);
+    const written = this.runtime.call("ghostty_wasm_alloc_usize");
+    const sizeResult = this.runtime.call("ghostty_grid_ref_hyperlink_uri", ref, 0, 0, written);
+    const outputSize = this.runtime.view(written, 4).getUint32(0, true);
+    let hyperlink: string | null = null;
+    if (sizeResult === GHOSTTY_OUT_OF_SPACE && outputSize > 0) {
+      const output = this.runtime.alloc(outputSize);
+      const result = this.runtime.call(
+        "ghostty_grid_ref_hyperlink_uri",
+        ref,
+        output,
+        outputSize,
+        written,
+      );
+      const outputLength = this.runtime.view(written, 4).getUint32(0, true);
+      if (result === GHOSTTY_SUCCESS && outputLength > 0) {
+        hyperlink = decoder.decode(this.runtime.bytes(output, outputLength));
+      }
+      this.runtime.free(output, outputSize);
+    }
+    this.runtime.call("ghostty_wasm_free_usize", written);
+    this.runtime.free(ref, this.runtime.layout("GhosttyGridRef").size);
+    return hyperlink;
+  }
+
+  clearSelection(): void {
+    this.ensureActive();
+    this.runtime.call("ghostty_terminal_set", this.terminal, 21, 0);
+  }
+
+  snapshot(): GhosttySnapshot {
+    this.ensureActive();
+    this.assertSuccess(
+      "ghostty_render_state_update",
+      this.runtime.call("ghostty_render_state_update", this.renderState, this.terminal),
+    );
+    const cols = this.getU16(RENDER_DATA.cols);
+    const rowCount = this.getU16(RENDER_DATA.rows);
+    const dirty = this.getU32(RENDER_DATA.dirty);
+    const foreground = this.getColor(RENDER_DATA.foreground, { r: 229, g: 231, b: 235 });
+    const background = this.getColor(RENDER_DATA.background, { r: 0, g: 0, b: 0 });
+    const cursorHasValue = this.getBool(RENDER_DATA.cursorHasValue);
+    const cursor = cursorHasValue ? this.getColor(RENDER_DATA.cursor, foreground) : foreground;
+    const cursorInViewport = this.getBool(RENDER_DATA.cursorInViewport);
+    const cursorVisible = this.getBool(RENDER_DATA.cursorVisible) && cursorInViewport;
+    const cursorX = cursorInViewport ? this.getU16(RENDER_DATA.cursorX) : -1;
+    const cursorY = cursorInViewport ? this.getU16(RENDER_DATA.cursorY) : -1;
+
+    if (this.rows.length !== rowCount || this.rows.some((row) => row.cells.length !== cols)) {
+      this.rows = Array.from({ length: rowCount }, () => ({
+        cells: Array.from({ length: cols }, () => this.emptyCell(foreground, background)),
+        text: "",
+        isWrapContinuation: false,
+        wrapsToNext: false,
+      }));
+    }
+
+    const dirtyRows = new Set<number>();
+    if (dirty !== 0) {
+      this.assertSuccess(
+        "ghostty_render_state_get(row iterator)",
+        this.runtime.call(
+          "ghostty_render_state_get",
+          this.renderState,
+          RENDER_DATA.rowIterator,
+          this.rowIteratorSlot,
+        ),
+      );
+      const iterator = this.runtime.readPointer(this.rowIteratorSlot);
+      let rowIndex = 0;
+      while (
+        rowIndex < rowCount &&
+        this.runtime.call("ghostty_render_state_row_iterator_next", iterator) !== 0
+      ) {
+        const rowDirty = dirty === 2 || this.getRowBool(iterator, ROW_DATA.dirty);
+        if (rowDirty) {
+          this.rows[rowIndex] = this.readRow(iterator, cols, foreground, background);
+          dirtyRows.add(rowIndex);
+          this.runtime.bytes(this.scratch, 1)[0] = 0;
+          this.runtime.call("ghostty_render_state_row_set", iterator, 0, this.scratch);
+        }
+        rowIndex += 1;
+      }
+      this.runtime.view(this.scratch, 4).setUint32(0, 0, true);
+      this.runtime.call("ghostty_render_state_set", this.renderState, 0, this.scratch);
+    }
+
+    return {
+      cols,
+      rows: rowCount,
+      foreground,
+      background,
+      cursor,
+      cursorX,
+      cursorY,
+      cursorVisible,
+      cursorBlinking: this.getBool(RENDER_DATA.cursorBlinking),
+      cursorStyle: this.getU32(RENDER_DATA.cursorStyle),
+      dirtyRows,
+      rowData: this.rows,
+    };
+  }
+
+  selectionText(): string {
+    this.ensureActive();
+    const options = this.runtime.alloc(SELECTION_FORMAT_OPTIONS_SIZE);
+    const optionsView = this.runtime.view(options, SELECTION_FORMAT_OPTIONS_SIZE);
+    optionsView.setUint32(0, SELECTION_FORMAT_OPTIONS_SIZE, true);
+    optionsView.setUint32(4, 0, true);
+    optionsView.setUint8(8, 1);
+    optionsView.setUint8(9, 1);
+    optionsView.setUint32(12, 0, true);
+    const written = this.runtime.call("ghostty_wasm_alloc_usize");
+    const sizeResult = this.runtime.call(
+      "ghostty_terminal_selection_format_buf",
+      this.terminal,
+      options,
+      0,
+      0,
+      written,
+    );
+    const outputSize = this.runtime.view(written, 4).getUint32(0, true);
+    let text = "";
+    if (sizeResult === GHOSTTY_OUT_OF_SPACE && outputSize > 0) {
+      const output = this.runtime.alloc(outputSize);
+      const result = this.runtime.call(
+        "ghostty_terminal_selection_format_buf",
+        this.terminal,
+        options,
+        output,
+        outputSize,
+        written,
+      );
+      const outputLength = this.runtime.view(written, 4).getUint32(0, true);
+      if (result === GHOSTTY_SUCCESS) {
+        text = decoder.decode(this.runtime.bytes(output, outputLength));
+      }
+      this.runtime.free(output, outputSize);
+    }
+    this.runtime.call("ghostty_wasm_free_usize", written);
+    this.runtime.free(options, SELECTION_FORMAT_OPTIONS_SIZE);
+    return text;
+  }
+
+  viewportPointToScreen(col: number, row: number): { x: number; y: number } | null {
+    return this.convertPoint(col, row, 1, 2);
+  }
+
+  screenPointToViewport(col: number, row: number): { x: number; y: number } | null {
+    return this.convertPoint(col, row, 2, 1);
+  }
+
+  private convertPoint(
+    col: number,
+    row: number,
+    fromTag: 1 | 2,
+    toTag: 1 | 2,
+  ): { x: number; y: number } | null {
+    this.ensureActive();
+    const ref = this.gridRef(col, row, fromTag);
+    const point = this.pointFromGridRef(ref, toTag);
+    this.runtime.free(ref, this.runtime.layout("GhosttyGridRef").size);
+    return point;
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.mouseEvent) this.runtime.call("ghostty_mouse_event_free", this.mouseEvent);
+    if (this.mouseEncoder) this.runtime.call("ghostty_mouse_encoder_free", this.mouseEncoder);
+    if (this.keyEvent) this.runtime.call("ghostty_key_event_free", this.keyEvent);
+    if (this.keyEncoder) this.runtime.call("ghostty_key_encoder_free", this.keyEncoder);
+    if (this.rowCellsSlot) {
+      const cells = this.runtime.readPointer(this.rowCellsSlot);
+      if (cells) this.runtime.call("ghostty_render_state_row_cells_free", cells);
+    }
+    if (this.rowIteratorSlot) {
+      const iterator = this.runtime.readPointer(this.rowIteratorSlot);
+      if (iterator) this.runtime.call("ghostty_render_state_row_iterator_free", iterator);
+    }
+    if (this.renderState) this.runtime.call("ghostty_render_state_free", this.renderState);
+    if (this.terminal) {
+      if (this.ptyWriterId) this.runtime.detachPtyWriter(this.terminal, this.ptyWriterId);
+      this.runtime.call("ghostty_terminal_free", this.terminal);
+    }
+    if (this.style) this.runtime.free(this.style, this.runtime.layout("GhosttyStyle").size);
+    if (this.scrollbar) {
+      this.runtime.free(this.scrollbar, this.runtime.layout("GhosttyTerminalScrollbar").size);
+    }
+    if (this.scratch) this.runtime.free(this.scratch, 16);
+    for (const slot of [
+      this.mouseEventSlot,
+      this.mouseEncoderSlot,
+      this.keyEventSlot,
+      this.keyEncoderSlot,
+      this.rowCellsSlot,
+      this.rowIteratorSlot,
+      this.renderStateSlot,
+      this.terminalSlot,
+    ]) {
+      this.runtime.freeOpaque(slot);
+    }
+  }
+
+  private encodeOutput(
+    written: number,
+    encode: (output: number, outputSize: number) => number,
+  ): string {
+    const sizeResult = encode(0, 0);
+    const outputSize = this.runtime.view(written, 4).getUint32(0, true);
+    if (sizeResult === GHOSTTY_SUCCESS && outputSize === 0) return "";
+    if (sizeResult !== GHOSTTY_OUT_OF_SPACE || outputSize === 0) return "";
+
+    const output = this.runtime.alloc(outputSize);
+    const result = encode(output, outputSize);
+    const outputLength = this.runtime.view(written, 4).getUint32(0, true);
+    const encoded =
+      result === GHOSTTY_SUCCESS ? decoder.decode(this.runtime.bytes(output, outputLength)) : "";
+    this.runtime.free(output, outputSize);
+    return encoded;
+  }
+
+  private readRow(
+    iterator: number,
+    cols: number,
+    defaultForeground: GhosttyColor,
+    defaultBackground: GhosttyColor,
+  ): GhosttyRow {
+    this.assertSuccess(
+      "ghostty_render_state_row_get(raw)",
+      this.runtime.call("ghostty_render_state_row_get", iterator, ROW_DATA.raw, this.scratch),
+    );
+    const rawRow = this.runtime.view(this.scratch, 8).getBigUint64(0, true);
+    this.runtime.bytes(this.scratch + 8, 1)[0] = 0;
+    this.assertSuccess(
+      "ghostty_row_get(wrap continuation)",
+      this.runtime.call("ghostty_row_get", rawRow, 2, this.scratch + 8),
+    );
+    const isWrapContinuation = this.runtime.bytes(this.scratch + 8, 1)[0] !== 0;
+    this.runtime.bytes(this.scratch + 8, 1)[0] = 0;
+    this.assertSuccess(
+      "ghostty_row_get(wrap)",
+      this.runtime.call("ghostty_row_get", rawRow, 1, this.scratch + 8),
+    );
+    const wrapsToNext = this.runtime.bytes(this.scratch + 8, 1)[0] !== 0;
+
+    this.assertSuccess(
+      "ghostty_render_state_row_get(cells)",
+      this.runtime.call(
+        "ghostty_render_state_row_get",
+        iterator,
+        ROW_DATA.cells,
+        this.rowCellsSlot,
+      ),
+    );
+    const cellsIterator = this.runtime.readPointer(this.rowCellsSlot);
+    const cells: GhosttyCell[] = [];
+    while (
+      cells.length < cols &&
+      this.runtime.call("ghostty_render_state_row_cells_next", cellsIterator) !== 0
+    ) {
+      let foreground = this.getCellColor(cellsIterator, CELL_DATA.foreground, defaultForeground);
+      let background = this.getCellColor(cellsIterator, CELL_DATA.background, defaultBackground);
+      const styleSize = this.runtime.layout("GhosttyStyle").size;
+      this.runtime.bytes(this.style, styleSize).fill(0);
+      this.runtime.setField(this.style, "GhosttyStyle", "size", styleSize);
+      this.runtime.call(
+        "ghostty_render_state_row_cells_get",
+        cellsIterator,
+        CELL_DATA.style,
+        this.style,
+      );
+      const inverse = this.runtime.readField(this.style, "GhosttyStyle", "inverse") !== 0;
+      if (inverse) [foreground, background] = [background, foreground];
+      if (this.runtime.readField(this.style, "GhosttyStyle", "faint") !== 0) {
+        foreground = blend(foreground, background);
+      }
+      const graphemeLength = this.getCellU32(cellsIterator, CELL_DATA.graphemesLength);
+      let text = "";
+      if (graphemeLength > 0) {
+        const bufferSize = graphemeLength * 4;
+        const codepoints = this.runtime.alloc(bufferSize);
+        if (
+          this.runtime.call(
+            "ghostty_render_state_row_cells_get",
+            cellsIterator,
+            CELL_DATA.graphemes,
+            codepoints,
+          ) === GHOSTTY_SUCCESS
+        ) {
+          // Read through a DataView: the byte-array allocator guarantees no
+          // 4-byte alignment, which a Uint32Array view would require.
+          const codepointView = this.runtime.view(codepoints, bufferSize);
+          const codes: number[] = [];
+          for (let index = 0; index < graphemeLength; index += 1) {
+            codes.push(codepointView.getUint32(index * 4, true));
+          }
+          text = String.fromCodePoint(...codes);
+        }
+        this.runtime.free(codepoints, bufferSize);
+      }
+      let wide = 0;
+      if (text.length === 0 && cells.at(-1)?.text.length) {
+        this.assertSuccess(
+          "ghostty_render_state_row_cells_get(raw)",
+          this.runtime.call(
+            "ghostty_render_state_row_cells_get",
+            cellsIterator,
+            CELL_DATA.raw,
+            this.scratch,
+          ),
+        );
+        const rawCell = this.runtime.view(this.scratch, 8).getBigUint64(0, true);
+        this.runtime.view(this.scratch + 8, 4).setUint32(0, 0, true);
+        this.assertSuccess(
+          "ghostty_cell_get(wide)",
+          this.runtime.call("ghostty_cell_get", rawCell, RAW_CELL_DATA.wide, this.scratch + 8),
+        );
+        wide = this.runtime.view(this.scratch + 8, 4).getUint32(0, true);
+      }
+      cells.push({
+        text,
+        wide,
+        foreground,
+        background,
+        bold: this.runtime.readField(this.style, "GhosttyStyle", "bold") !== 0,
+        italic: this.runtime.readField(this.style, "GhosttyStyle", "italic") !== 0,
+        invisible: this.runtime.readField(this.style, "GhosttyStyle", "invisible") !== 0,
+        strikethrough: this.runtime.readField(this.style, "GhosttyStyle", "strikethrough") !== 0,
+        overline: this.runtime.readField(this.style, "GhosttyStyle", "overline") !== 0,
+        underline: this.runtime.readField(this.style, "GhosttyStyle", "underline") !== 0,
+        selected: this.getCellBool(cellsIterator, CELL_DATA.selected),
+      });
+    }
+    while (cells.length < cols) cells.push(this.emptyCell(defaultForeground, defaultBackground));
+    return {
+      cells,
+      text: cells
+        .map((cell) => cell.text || " ")
+        .join("")
+        .trimEnd(),
+      isWrapContinuation,
+      wrapsToNext,
+    };
+  }
+
+  private gridRef(col: number, row: number, tag: 1 | 2 = 1): number {
+    const pointLayout = this.runtime.layout("GhosttyPoint");
+    const point = this.runtime.alloc(pointLayout.size);
+    this.runtime.setField(point, "GhosttyPoint", "tag", tag);
+    const pointValue = pointLayout.fields.value!;
+    const valueOffset = pointValue.offset;
+    const view = this.runtime.view(point + valueOffset, pointValue.size);
+    view.setUint16(0, Math.max(0, col), true);
+    view.setUint32(4, Math.max(0, row), true);
+    const gridRefSize = this.runtime.layout("GhosttyGridRef").size;
+    const gridRef = this.runtime.alloc(gridRefSize);
+    this.runtime.setField(gridRef, "GhosttyGridRef", "size", gridRefSize);
+    const result = this.runtime.call("ghostty_terminal_grid_ref", this.terminal, point, gridRef);
+    this.runtime.free(point, pointLayout.size);
+    if (result !== GHOSTTY_SUCCESS) {
+      this.runtime.free(gridRef, gridRefSize);
+      this.assertSuccess("ghostty_terminal_grid_ref", result);
+    }
+    return gridRef;
+  }
+
+  private selectAt(
+    optionsName: "GhosttyTerminalSelectWordOptions" | "GhosttyTerminalSelectLineOptions",
+    operation: "ghostty_terminal_select_word" | "ghostty_terminal_select_line",
+    col: number,
+    row: number,
+  ): GhosttySelectionRange | null {
+    this.ensureActive();
+    const optionsLayout = this.runtime.layout(optionsName);
+    const selectionLayout = this.runtime.layout("GhosttySelection");
+    const options = this.runtime.alloc(optionsLayout.size);
+    let ref = 0;
+    let selection = 0;
+    let range: GhosttySelectionRange | null = null;
+    try {
+      this.runtime.setField(options, optionsName, "size", optionsLayout.size);
+      ref = this.gridRef(col, row);
+      const refField = optionsLayout.fields.ref!;
+      this.runtime
+        .bytes(options + refField.offset, refField.size)
+        .set(this.runtime.bytes(ref, refField.size));
+      selection = this.runtime.alloc(selectionLayout.size);
+      this.runtime.setField(selection, "GhosttySelection", "size", selectionLayout.size);
+      const result = this.runtime.call(operation, this.terminal, options, selection);
+      if (result === GHOSTTY_SUCCESS) {
+        const start = selection + selectionLayout.fields.start!.offset;
+        const end = selection + selectionLayout.fields.end!.offset;
+        const viewportStart = this.pointFromGridRef(start, 1);
+        const viewportEnd = this.pointFromGridRef(end, 1);
+        const screenStart = this.pointFromGridRef(start, 2);
+        const screenEnd = this.pointFromGridRef(end, 2);
+        if (viewportStart && viewportEnd && screenStart && screenEnd) {
+          range = {
+            viewport: { start: viewportStart, end: viewportEnd },
+            screen: { start: screenStart, end: screenEnd },
+          };
+        }
+        this.runtime.call("ghostty_terminal_set", this.terminal, 21, selection);
+      }
+    } finally {
+      this.runtime.free(selection, selectionLayout.size);
+      this.runtime.free(ref, this.runtime.layout("GhosttyGridRef").size);
+      this.runtime.free(options, optionsLayout.size);
+    }
+    return range;
+  }
+
+  private pointFromGridRef(ref: number, tag: 1 | 2): { x: number; y: number } | null {
+    const coordinateLayout = this.runtime.layout("GhosttyPointCoordinate");
+    const coordinate = this.runtime.alloc(coordinateLayout.size);
+    const result = this.runtime.call(
+      "ghostty_terminal_point_from_grid_ref",
+      this.terminal,
+      ref,
+      tag,
+      coordinate,
+    );
+    const point =
+      result === GHOSTTY_SUCCESS
+        ? {
+            x: this.runtime.readField(coordinate, "GhosttyPointCoordinate", "x"),
+            y: this.runtime.readField(coordinate, "GhosttyPointCoordinate", "y"),
+          }
+        : null;
+    this.runtime.free(coordinate, coordinateLayout.size);
+    return point;
+  }
+
+  private getU16(data: number): number {
+    this.runtime.bytes(this.scratch, 2).fill(0);
+    this.assertSuccess(
+      "ghostty_render_state_get",
+      this.runtime.call("ghostty_render_state_get", this.renderState, data, this.scratch),
+    );
+    return this.runtime.view(this.scratch, 2).getUint16(0, true);
+  }
+
+  private getU32(data: number): number {
+    this.runtime.bytes(this.scratch, 4).fill(0);
+    this.assertSuccess(
+      "ghostty_render_state_get",
+      this.runtime.call("ghostty_render_state_get", this.renderState, data, this.scratch),
+    );
+    return this.runtime.view(this.scratch, 4).getUint32(0, true);
+  }
+
+  private getBool(data: number): boolean {
+    this.runtime.bytes(this.scratch, 1)[0] = 0;
+    this.assertSuccess(
+      "ghostty_render_state_get",
+      this.runtime.call("ghostty_render_state_get", this.renderState, data, this.scratch),
+    );
+    return this.runtime.bytes(this.scratch, 1)[0] !== 0;
+  }
+
+  private getColor(data: number, fallback: GhosttyColor): GhosttyColor {
+    this.runtime.bytes(this.scratch, 3).fill(0);
+    const result = this.runtime.call(
+      "ghostty_render_state_get",
+      this.renderState,
+      data,
+      this.scratch,
+    );
+    return result === GHOSTTY_SUCCESS ? this.readColor(this.scratch) : fallback;
+  }
+
+  private getRowBool(iterator: number, data: number): boolean {
+    this.runtime.bytes(this.scratch, 1)[0] = 0;
+    return (
+      this.runtime.call("ghostty_render_state_row_get", iterator, data, this.scratch) ===
+        GHOSTTY_SUCCESS && this.runtime.bytes(this.scratch, 1)[0] !== 0
+    );
+  }
+
+  private getCellU32(iterator: number, data: number): number {
+    this.runtime.bytes(this.scratch, 4).fill(0);
+    const result = this.runtime.call(
+      "ghostty_render_state_row_cells_get",
+      iterator,
+      data,
+      this.scratch,
+    );
+    return result === GHOSTTY_SUCCESS ? this.runtime.view(this.scratch, 4).getUint32(0, true) : 0;
+  }
+
+  private getCellBool(iterator: number, data: number): boolean {
+    this.runtime.bytes(this.scratch, 1)[0] = 0;
+    return (
+      this.runtime.call("ghostty_render_state_row_cells_get", iterator, data, this.scratch) ===
+        GHOSTTY_SUCCESS && this.runtime.bytes(this.scratch, 1)[0] !== 0
+    );
+  }
+
+  private getCellColor(iterator: number, data: number, fallback: GhosttyColor): GhosttyColor {
+    this.runtime.bytes(this.scratch, 3).fill(0);
+    const result = this.runtime.call(
+      "ghostty_render_state_row_cells_get",
+      iterator,
+      data,
+      this.scratch,
+    );
+    return result === GHOSTTY_SUCCESS ? this.readColor(this.scratch) : fallback;
+  }
+
+  private readColor(pointer: number): GhosttyColor {
+    const bytes = this.runtime.bytes(pointer, 3);
+    return { r: bytes[0] ?? 0, g: bytes[1] ?? 0, b: bytes[2] ?? 0 };
+  }
+
+  private emptyCell(foreground: GhosttyColor, background: GhosttyColor): GhosttyCell {
+    return {
+      text: "",
+      wide: 0,
+      foreground,
+      background,
+      bold: false,
+      italic: false,
+      invisible: false,
+      strikethrough: false,
+      overline: false,
+      underline: false,
+      selected: false,
+    };
+  }
+
+  private assertSuccess(operation: string, result: number): void {
+    if (result !== GHOSTTY_SUCCESS) throw new Error(`${operation} failed with result ${result}`);
+  }
+
+  private ensureActive(): void {
+    if (this.disposed) throw new Error("libghostty-vt terminal has been disposed");
+  }
+}
+
+export function ghosttyColorsEqual(left: GhosttyColor, right: GhosttyColor): boolean {
+  return sameColor(left, right);
+}
diff --git a/apps/web/src/terminal/ghostty/fonts/LICENSE b/apps/web/src/terminal/ghostty/fonts/LICENSE
new file mode 100644
index 00000000000..06eb073d6b5
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/fonts/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Ryan L McIntyre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/apps/web/src/terminal/ghostty/fonts/SymbolsNerdFontMono-Regular.woff2 b/apps/web/src/terminal/ghostty/fonts/SymbolsNerdFontMono-Regular.woff2
new file mode 100644
index 00000000000..1e2127fadb9
Binary files /dev/null and b/apps/web/src/terminal/ghostty/fonts/SymbolsNerdFontMono-Regular.woff2 differ
diff --git a/apps/web/src/terminal/ghostty/keyCodes.test.ts b/apps/web/src/terminal/ghostty/keyCodes.test.ts
new file mode 100644
index 00000000000..d6fc0cca45e
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/keyCodes.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { ghosttyKeyForCode, ghosttyUnshiftedCodepoint } from "./keyCodes";
+
+describe("ghosttyKeyForCode", () => {
+  it("keeps the tail of the pinned Ghostty key enum in order", () => {
+    expect(ghosttyKeyForCode("F25")).toBe(ghosttyKeyForCode("F24") + 1);
+    expect(ghosttyKeyForCode("PrintScreen")).toBe(ghosttyKeyForCode("FnLock") + 1);
+    expect(ghosttyKeyForCode("Pause")).toBe(ghosttyKeyForCode("ScrollLock") + 1);
+    expect(ghosttyKeyForCode("Paste")).toBe(ghosttyKeyForCode("Cut") + 1);
+  });
+});
+
+describe("ghosttyUnshiftedCodepoint", () => {
+  it("provides the logical base character for Kitty keyboard encoding", () => {
+    expect(ghosttyUnshiftedCodepoint({ code: "KeyC", key: "c", shiftKey: false })).toBe(
+      "c".codePointAt(0),
+    );
+    expect(ghosttyUnshiftedCodepoint({ code: "KeyC", key: "C", shiftKey: true })).toBe(
+      "c".codePointAt(0),
+    );
+    expect(ghosttyUnshiftedCodepoint({ code: "Digit1", key: "!", shiftKey: true })).toBe(
+      "1".codePointAt(0),
+    );
+    expect(ghosttyUnshiftedCodepoint({ code: "Slash", key: "?", shiftKey: true })).toBe(
+      "/".codePointAt(0),
+    );
+    expect(ghosttyUnshiftedCodepoint({ code: "Digit1", key: "&", shiftKey: false })).toBe(
+      "&".codePointAt(0),
+    );
+    expect(ghosttyUnshiftedCodepoint({ code: "Enter", key: "Enter", shiftKey: false })).toBe(0);
+  });
+
+  it("reports unknown instead of the shifted character without layout data", () => {
+    expect(ghosttyUnshiftedCodepoint({ code: "Digit7", key: "/", shiftKey: true })).toBe(0);
+    expect(ghosttyUnshiftedCodepoint({ code: "KeyD", key: "Д", shiftKey: true })).toBe(
+      "д".codePointAt(0),
+    );
+  });
+
+  it("prefers the active browser layout over US physical key positions", () => {
+    const layoutMap = new Map([
+      ["Digit1", "&"],
+      ["KeyC", "j"],
+    ]);
+    expect(ghosttyUnshiftedCodepoint({ code: "Digit1", key: "1", shiftKey: true }, layoutMap)).toBe(
+      "&".codePointAt(0),
+    );
+    expect(ghosttyUnshiftedCodepoint({ code: "KeyC", key: "J", shiftKey: true }, layoutMap)).toBe(
+      "j".codePointAt(0),
+    );
+  });
+});
diff --git a/apps/web/src/terminal/ghostty/keyCodes.ts b/apps/web/src/terminal/ghostty/keyCodes.ts
new file mode 100644
index 00000000000..a82c748b274
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/keyCodes.ts
@@ -0,0 +1,258 @@
+// This order mirrors GhosttyKey in ghostty/vt/key/event.h. The values are
+// intentionally derived from the official W3C-aligned enum instead of
+// maintaining a second keyboard protocol.
+const ghosttyKeyboardCodes = [
+  "Unidentified",
+  "Backquote",
+  "Backslash",
+  "BracketLeft",
+  "BracketRight",
+  "Comma",
+  "Digit0",
+  "Digit1",
+  "Digit2",
+  "Digit3",
+  "Digit4",
+  "Digit5",
+  "Digit6",
+  "Digit7",
+  "Digit8",
+  "Digit9",
+  "Equal",
+  "IntlBackslash",
+  "IntlRo",
+  "IntlYen",
+  "KeyA",
+  "KeyB",
+  "KeyC",
+  "KeyD",
+  "KeyE",
+  "KeyF",
+  "KeyG",
+  "KeyH",
+  "KeyI",
+  "KeyJ",
+  "KeyK",
+  "KeyL",
+  "KeyM",
+  "KeyN",
+  "KeyO",
+  "KeyP",
+  "KeyQ",
+  "KeyR",
+  "KeyS",
+  "KeyT",
+  "KeyU",
+  "KeyV",
+  "KeyW",
+  "KeyX",
+  "KeyY",
+  "KeyZ",
+  "Minus",
+  "Period",
+  "Quote",
+  "Semicolon",
+  "Slash",
+  "AltLeft",
+  "AltRight",
+  "Backspace",
+  "CapsLock",
+  "ContextMenu",
+  "ControlLeft",
+  "ControlRight",
+  "Enter",
+  "MetaLeft",
+  "MetaRight",
+  "ShiftLeft",
+  "ShiftRight",
+  "Space",
+  "Tab",
+  "Convert",
+  "KanaMode",
+  "NonConvert",
+  "Delete",
+  "End",
+  "Help",
+  "Home",
+  "Insert",
+  "PageDown",
+  "PageUp",
+  "ArrowDown",
+  "ArrowLeft",
+  "ArrowRight",
+  "ArrowUp",
+  "NumLock",
+  "Numpad0",
+  "Numpad1",
+  "Numpad2",
+  "Numpad3",
+  "Numpad4",
+  "Numpad5",
+  "Numpad6",
+  "Numpad7",
+  "Numpad8",
+  "Numpad9",
+  "NumpadAdd",
+  "NumpadBackspace",
+  "NumpadClear",
+  "NumpadClearEntry",
+  "NumpadComma",
+  "NumpadDecimal",
+  "NumpadDivide",
+  "NumpadEnter",
+  "NumpadEqual",
+  "NumpadMemoryAdd",
+  "NumpadMemoryClear",
+  "NumpadMemoryRecall",
+  "NumpadMemoryStore",
+  "NumpadMemorySubtract",
+  "NumpadMultiply",
+  "NumpadParenLeft",
+  "NumpadParenRight",
+  "NumpadSubtract",
+  "NumpadSeparator",
+  "NumpadArrowUp",
+  "NumpadArrowDown",
+  "NumpadArrowRight",
+  "NumpadArrowLeft",
+  "NumpadBegin",
+  "NumpadHome",
+  "NumpadEnd",
+  "NumpadInsert",
+  "NumpadDelete",
+  "NumpadPageUp",
+  "NumpadPageDown",
+  "Escape",
+  "F1",
+  "F2",
+  "F3",
+  "F4",
+  "F5",
+  "F6",
+  "F7",
+  "F8",
+  "F9",
+  "F10",
+  "F11",
+  "F12",
+  "F13",
+  "F14",
+  "F15",
+  "F16",
+  "F17",
+  "F18",
+  "F19",
+  "F20",
+  "F21",
+  "F22",
+  "F23",
+  "F24",
+  "F25",
+  "Fn",
+  "FnLock",
+  "PrintScreen",
+  "ScrollLock",
+  "Pause",
+  "BrowserBack",
+  "BrowserFavorites",
+  "BrowserForward",
+  "BrowserHome",
+  "BrowserRefresh",
+  "BrowserSearch",
+  "BrowserStop",
+  "Eject",
+  "LaunchApp1",
+  "LaunchApp2",
+  "LaunchMail",
+  "MediaPlayPause",
+  "MediaSelect",
+  "MediaStop",
+  "MediaTrackNext",
+  "MediaTrackPrevious",
+  "Power",
+  "Sleep",
+  "AudioVolumeDown",
+  "AudioVolumeMute",
+  "AudioVolumeUp",
+  "WakeUp",
+  "Copy",
+  "Cut",
+  "Paste",
+] as const;
+
+const codeToGhosttyKey = new Map<string, number>(
+  ghosttyKeyboardCodes.map((code, index) => [code, index]),
+);
+
+export function ghosttyKeyForCode(code: string): number {
+  return codeToGhosttyKey.get(code) ?? 0;
+}
+
+export interface GhosttyKeyboardLayoutMap {
+  get(code: string): string | undefined;
+}
+
+const shiftedToUnshiftedCharacter = new Map<string, string>([
+  ["!", "1"],
+  ["@", "2"],
+  ["#", "3"],
+  ["$", "4"],
+  ["%", "5"],
+  ["^", "6"],
+  ["&", "7"],
+  ["*", "8"],
+  ["(", "9"],
+  [")", "0"],
+  ["~", "`"],
+  ["_", "-"],
+  ["+", "="],
+  ["{", "["],
+  ["}", "]"],
+  ["|", "\\"],
+  [":", ";"],
+  ['"', "'"],
+  ["<", ","],
+  [">", "."],
+  ["?", "/"],
+]);
+
+let keyboardLayoutMapPromise: Promise<GhosttyKeyboardLayoutMap | undefined> | undefined;
+
+export function loadGhosttyKeyboardLayoutMap(): Promise<GhosttyKeyboardLayoutMap | undefined> {
+  if (keyboardLayoutMapPromise) return keyboardLayoutMapPromise;
+  const browserNavigator = globalThis.navigator as
+    | (Navigator & {
+        readonly keyboard?: {
+          getLayoutMap(): Promise<GhosttyKeyboardLayoutMap>;
+        };
+      })
+    | undefined;
+  const keyboard = browserNavigator?.keyboard;
+  const promise = keyboard?.getLayoutMap().catch(() => undefined) ?? Promise.resolve(undefined);
+  keyboardLayoutMapPromise = promise;
+  return promise;
+}
+
+export function ghosttyUnshiftedCodepoint(
+  event: Pick<KeyboardEvent, "code" | "key" | "shiftKey">,
+  layoutMap?: GhosttyKeyboardLayoutMap,
+): number {
+  if ([...event.key].length !== 1) return 0;
+  const layoutCharacter = layoutMap?.get(event.code);
+  if (layoutCharacter && [...layoutCharacter].length === 1) {
+    return layoutCharacter.codePointAt(0) ?? 0;
+  }
+  if (/^[A-Z]$/u.test(event.key)) return event.key.charCodeAt(0) + 32;
+  if (event.shiftKey) {
+    const unshiftedCharacter = shiftedToUnshiftedCharacter.get(event.key);
+    if (unshiftedCharacter) return unshiftedCharacter.codePointAt(0) ?? 0;
+    const lowercase = event.key.toLowerCase();
+    if (lowercase !== event.key && [...lowercase].length === 1) {
+      return lowercase.codePointAt(0) ?? 0;
+    }
+    // Without layout data the unshifted form of a shifted key is unknowable;
+    // reporting the shifted character as unshifted corrupts Kitty alternate keys.
+    return 0;
+  }
+  return event.key.codePointAt(0) ?? 0;
+}
diff --git a/apps/web/src/terminal/ghostty/renderer.test.ts b/apps/web/src/terminal/ghostty/renderer.test.ts
new file mode 100644
index 00000000000..e4d292a2c33
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/renderer.test.ts
@@ -0,0 +1,175 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import { GHOSTTY_CELL_WIDE, type GhosttyCell, type GhosttySnapshot } from "./core";
+import {
+  ghosttyTextRunEnd,
+  measureGhosttyCell,
+  renderGhosttySnapshot,
+  terminalGridSize,
+} from "./renderer";
+
+const cell = (text: string, wide = 0): GhosttyCell => ({
+  text,
+  wide,
+  foreground: { r: 255, g: 255, b: 255 },
+  background: { r: 0, g: 0, b: 0 },
+  bold: false,
+  italic: false,
+  invisible: false,
+  strikethrough: false,
+  overline: false,
+  underline: false,
+  selected: false,
+});
+
+describe("terminalGridSize", () => {
+  it("matches the mobile renderer's cell-and-padding sizing model", () => {
+    expect(terminalGridSize(808, 408, { width: 10, height: 20, baseline: 15 }, 4)).toEqual({
+      cols: 80,
+      rows: 20,
+    });
+  });
+
+  it("never sends an invalid zero-sized terminal to libghostty", () => {
+    expect(terminalGridSize(0, 0, { width: 10, height: 20, baseline: 15 }, 4)).toEqual({
+      cols: 1,
+      rows: 1,
+    });
+  });
+});
+
+describe("measureGhosttyCell", () => {
+  it("uses descender-aware metrics and the mobile terminal line-height", () => {
+    const measureText = (text: string) =>
+      text === "M"
+        ? { width: 7.2, actualBoundingBoxAscent: 9, actualBoundingBoxDescent: 0 }
+        : { width: 14.4, actualBoundingBoxAscent: 9, actualBoundingBoxDescent: 3 };
+    const context = {
+      font: "",
+      measureText,
+    } as unknown as CanvasRenderingContext2D;
+
+    expect(measureGhosttyCell(context, 12, "monospace")).toEqual({
+      width: 7.2,
+      height: 16,
+      baseline: 11,
+    });
+  });
+});
+
+describe("ghosttyTextRunEnd", () => {
+  it("includes wide spacer tails in the visual clip without rendering spaces", () => {
+    const cells = [
+      cell("界", GHOSTTY_CELL_WIDE.wide),
+      cell("", GHOSTTY_CELL_WIDE.spacerTail),
+      cell("🙂", GHOSTTY_CELL_WIDE.wide),
+      cell("", GHOSTTY_CELL_WIDE.spacerTail),
+      cell(""),
+    ];
+    expect(ghosttyTextRunEnd(cells, 0, () => true)).toBe(4);
+  });
+});
+
+describe("renderGhosttySnapshot", () => {
+  it("constrains text runs and cursor glyphs to their terminal cells", () => {
+    const fillTextCalls: unknown[][] = [];
+    const context = {
+      canvas: { width: 200, height: 40 },
+      beginPath: () => {},
+      clip: () => {},
+      fillRect: () => {},
+      fillText: (...args: unknown[]) => fillTextCalls.push(args),
+      rect: () => {},
+      resetTransform: () => {},
+      restore: () => {},
+      save: () => {},
+      set fillStyle(_value: string) {},
+      set font(_value: string) {},
+      set textBaseline(_value: string) {},
+    } as unknown as CanvasRenderingContext2D;
+    const cells = [cell("a"), cell("b"), cell("x")];
+    const snapshot: GhosttySnapshot = {
+      cols: 3,
+      rows: 1,
+      foreground: { r: 255, g: 255, b: 255 },
+      background: { r: 0, g: 0, b: 0 },
+      cursor: { r: 255, g: 255, b: 255 },
+      cursorX: 2,
+      cursorY: 0,
+      cursorVisible: true,
+      cursorBlinking: false,
+      cursorStyle: 1,
+      dirtyRows: new Set([0]),
+      rowData: [{ cells, text: "abx", isWrapContinuation: false, wrapsToNext: false }],
+    };
+
+    renderGhosttySnapshot({
+      context,
+      snapshot,
+      metrics: { width: 7.2, height: 16, baseline: 11 },
+      fontSize: 12,
+      fontFamily: "monospace",
+      padding: 4,
+      forceFull: false,
+      cursorOn: true,
+    });
+
+    expect(fillTextCalls).toEqual([
+      ["abx", 4, 15, 21.6],
+      ["x", 18.4, 15, 7.2],
+    ]);
+  });
+
+  it("repaints the previous cursor row after the cursor moves", () => {
+    const clearedRows: number[] = [];
+    const context = {
+      canvas: { width: 200, height: 80 },
+      beginPath: () => {},
+      clip: () => {},
+      fillRect: (_left: number, top: number, _width: number, height: number) => {
+        if (height === 16) clearedRows.push(top);
+      },
+      fillText: () => {},
+      rect: () => {},
+      resetTransform: () => {},
+      restore: () => {},
+      save: () => {},
+      set fillStyle(_value: string) {},
+      set font(_value: string) {},
+      set textBaseline(_value: string) {},
+    } as unknown as CanvasRenderingContext2D;
+    const snapshot: GhosttySnapshot = {
+      cols: 1,
+      rows: 3,
+      foreground: { r: 255, g: 255, b: 255 },
+      background: { r: 0, g: 0, b: 0 },
+      cursor: { r: 255, g: 255, b: 255 },
+      cursorX: 0,
+      cursorY: 2,
+      cursorVisible: true,
+      cursorBlinking: false,
+      cursorStyle: 1,
+      dirtyRows: new Set(),
+      rowData: [0, 1, 2].map(() => ({
+        cells: [cell("")],
+        text: "",
+        isWrapContinuation: false,
+        wrapsToNext: false,
+      })),
+    };
+
+    renderGhosttySnapshot({
+      context,
+      snapshot,
+      metrics: { width: 7.2, height: 16, baseline: 11 },
+      fontSize: 12,
+      fontFamily: "monospace",
+      padding: 4,
+      forceFull: false,
+      cursorOn: true,
+      previousCursorY: 0,
+    });
+
+    expect(clearedRows).toEqual([4, 36, 36]);
+  });
+});
diff --git a/apps/web/src/terminal/ghostty/renderer.ts b/apps/web/src/terminal/ghostty/renderer.ts
new file mode 100644
index 00000000000..0cb7d6f535d
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/renderer.ts
@@ -0,0 +1,255 @@
+import {
+  GHOSTTY_CELL_WIDE,
+  ghosttyColorsEqual,
+  type GhosttyCell,
+  type GhosttyColor,
+  type GhosttySnapshot,
+} from "./core";
+
+export interface GhosttyCellMetrics {
+  readonly width: number;
+  readonly height: number;
+  readonly baseline: number;
+}
+
+const DEFAULT_SELECTION_BACKGROUND = "rgba(72, 122, 191, 0.35)";
+
+function cssColor(color: GhosttyColor): string {
+  return `rgb(${color.r}, ${color.g}, ${color.b})`;
+}
+
+function sameTextStyle(left: GhosttyCell, right: GhosttyCell): boolean {
+  // Selection deliberately does not participate: it only tints the background
+  // overlay, and splitting a text run at a selection boundary visibly shifts
+  // glyph spacing whenever the face's true advance differs from the cell width.
+  return (
+    ghosttyColorsEqual(left.foreground, right.foreground) &&
+    left.bold === right.bold &&
+    left.italic === right.italic &&
+    left.invisible === right.invisible
+  );
+}
+
+export function ghosttyTextRunEnd(
+  cells: readonly GhosttyCell[],
+  start: number,
+  sameStyle: (cell: GhosttyCell) => boolean,
+): number {
+  let end = start + 1;
+  while (end < cells.length) {
+    const next = cells[end];
+    if (!next) break;
+    if (next.wide === GHOSTTY_CELL_WIDE.spacerTail) {
+      end += 1;
+      continue;
+    }
+    if (next.text.length === 0 || !sameStyle(next)) break;
+    end += 1;
+  }
+  return end;
+}
+
+function fontForCell(cell: GhosttyCell, fontSize: number, fontFamily: string): string {
+  const style = cell.italic ? "italic" : "normal";
+  const weight = cell.bold ? "700" : "400";
+  return `${style} ${weight} ${fontSize}px ${fontFamily}`;
+}
+
+export function measureGhosttyCell(
+  context: CanvasRenderingContext2D,
+  fontSize: number,
+  fontFamily: string,
+): GhosttyCellMetrics {
+  context.font = `normal 400 ${fontSize}px ${fontFamily}`;
+  const widthMeasurement = context.measureText("M");
+  const verticalMeasurement = context.measureText("Mg");
+  const ascent = verticalMeasurement.actualBoundingBoxAscent || fontSize;
+  const descent = verticalMeasurement.actualBoundingBoxDescent;
+  const glyphHeight = ascent + descent;
+  const height = Math.max(1, Math.round(fontSize * 1.35), Math.ceil(glyphHeight));
+  return {
+    width: Math.max(1, widthMeasurement.width),
+    height,
+    baseline: Math.round((height - glyphHeight) / 2 + ascent),
+  };
+}
+
+export function terminalGridSize(
+  width: number,
+  height: number,
+  metrics: GhosttyCellMetrics,
+  padding: number,
+): { cols: number; rows: number } {
+  return {
+    cols: Math.max(1, Math.floor((width - padding * 2) / metrics.width)),
+    rows: Math.max(1, Math.floor((height - padding * 2) / metrics.height)),
+  };
+}
+
+export function renderGhosttySnapshot(options: {
+  readonly context: CanvasRenderingContext2D;
+  readonly snapshot: GhosttySnapshot;
+  readonly metrics: GhosttyCellMetrics;
+  readonly fontSize: number;
+  readonly fontFamily: string;
+  readonly padding: number;
+  readonly forceFull: boolean;
+  readonly cursorOn: boolean;
+  readonly previousCursorY?: number | null;
+  readonly focused?: boolean;
+  readonly selectionBackground?: string;
+  /** Vertical origin of row 0; defaults to the horizontal padding. */
+  readonly originY?: number;
+}): void {
+  const {
+    context,
+    snapshot,
+    metrics,
+    fontSize,
+    fontFamily,
+    padding,
+    forceFull,
+    cursorOn,
+    previousCursorY,
+  } = options;
+  const focused = options.focused ?? true;
+  const selectionBackground = options.selectionBackground ?? DEFAULT_SELECTION_BACKGROUND;
+  const originY = options.originY ?? padding;
+  const rowsToDraw = forceFull
+    ? Array.from({ length: snapshot.rows }, (_, index) => index)
+    : [...snapshot.dirtyRows];
+  if (
+    previousCursorY !== null &&
+    previousCursorY !== undefined &&
+    previousCursorY >= 0 &&
+    !rowsToDraw.includes(previousCursorY)
+  ) {
+    rowsToDraw.push(previousCursorY);
+  }
+  if (snapshot.cursorVisible && snapshot.cursorY >= 0 && !rowsToDraw.includes(snapshot.cursorY)) {
+    rowsToDraw.push(snapshot.cursorY);
+  }
+
+  if (forceFull) {
+    context.save();
+    context.resetTransform();
+    context.fillStyle = cssColor(snapshot.background);
+    context.fillRect(0, 0, context.canvas.width, context.canvas.height);
+    context.restore();
+  }
+
+  context.textBaseline = "alphabetic";
+  for (const rowIndex of rowsToDraw) {
+    const row = snapshot.rowData[rowIndex];
+    if (!row) continue;
+    const top = originY + rowIndex * metrics.height;
+
+    context.fillStyle = cssColor(snapshot.background);
+    context.fillRect(padding, top, snapshot.cols * metrics.width, metrics.height);
+
+    let backgroundStart = 0;
+    while (backgroundStart < row.cells.length) {
+      const first = row.cells[backgroundStart];
+      if (!first) break;
+      let backgroundEnd = backgroundStart + 1;
+      while (backgroundEnd < row.cells.length) {
+        const next = row.cells[backgroundEnd];
+        if (
+          !next ||
+          next.selected !== first.selected ||
+          !ghosttyColorsEqual(next.background, first.background)
+        ) {
+          break;
+        }
+        backgroundEnd += 1;
+      }
+      if (first.selected || !ghosttyColorsEqual(first.background, snapshot.background)) {
+        const left = padding + backgroundStart * metrics.width;
+        const width = (backgroundEnd - backgroundStart) * metrics.width;
+        if (!ghosttyColorsEqual(first.background, snapshot.background)) {
+          context.fillStyle = cssColor(first.background);
+          context.fillRect(left, top, width, metrics.height);
+        }
+        if (first.selected) {
+          context.fillStyle = selectionBackground;
+          context.fillRect(left, top, width, metrics.height);
+        }
+      }
+      backgroundStart = backgroundEnd;
+    }
+
+    let runStart = 0;
+    while (runStart < row.cells.length) {
+      const first = row.cells[runStart];
+      if (!first) break;
+      if (first.text.length === 0) {
+        runStart += 1;
+        continue;
+      }
+      const runEnd = ghosttyTextRunEnd(row.cells, runStart, (cell) => sameTextStyle(cell, first));
+      const text = row.cells
+        .slice(runStart, runEnd)
+        .map((cell) => cell.text)
+        .join("");
+      if (!first.invisible && text.trim().length > 0) {
+        context.save();
+        context.beginPath();
+        context.rect(
+          padding + runStart * metrics.width,
+          top,
+          (runEnd - runStart) * metrics.width,
+          metrics.height,
+        );
+        context.clip();
+        context.font = fontForCell(first, fontSize, fontFamily);
+        context.fillStyle = cssColor(first.foreground);
+        context.fillText(
+          text,
+          padding + runStart * metrics.width,
+          top + metrics.baseline,
+          (runEnd - runStart) * metrics.width,
+        );
+        context.restore();
+      }
+      runStart = runEnd;
+    }
+
+    for (let column = 0; column < row.cells.length; column += 1) {
+      const cell = row.cells[column];
+      if (!cell || (!cell.underline && !cell.strikethrough && !cell.overline)) continue;
+      context.fillStyle = cssColor(cell.foreground);
+      const left = padding + column * metrics.width;
+      if (cell.underline) context.fillRect(left, top + metrics.height - 2, metrics.width, 1);
+      if (cell.strikethrough) {
+        context.fillRect(left, top + Math.floor(metrics.height * 0.55), metrics.width, 1);
+      }
+      if (cell.overline) context.fillRect(left, top + 1, metrics.width, 1);
+    }
+  }
+
+  if (cursorOn && snapshot.cursorVisible && snapshot.cursorX >= 0 && snapshot.cursorY >= 0) {
+    const left = padding + snapshot.cursorX * metrics.width;
+    const top = originY + snapshot.cursorY * metrics.height;
+    context.fillStyle = cssColor(snapshot.cursor);
+    if (!focused) {
+      // An unfocused terminal draws a hollow cursor so the active pane is obvious.
+      context.strokeStyle = cssColor(snapshot.cursor);
+      context.strokeRect(left + 0.5, top + 0.5, metrics.width - 1, metrics.height - 1);
+    } else if (snapshot.cursorStyle === 0) {
+      context.fillRect(left, top, 2, metrics.height);
+    } else if (snapshot.cursorStyle === 2) {
+      context.fillRect(left, top + metrics.height - 2, metrics.width, 2);
+    } else if (snapshot.cursorStyle === 3) {
+      context.strokeStyle = cssColor(snapshot.cursor);
+      context.strokeRect(left + 0.5, top + 0.5, metrics.width - 1, metrics.height - 1);
+    } else {
+      context.fillRect(left, top, metrics.width, metrics.height);
+      const cell = snapshot.rowData[snapshot.cursorY]?.cells[snapshot.cursorX];
+      if (cell?.text) {
+        context.font = fontForCell(cell, fontSize, fontFamily);
+        context.fillStyle = cssColor(snapshot.background);
+        context.fillText(cell.text, left, top + metrics.baseline, metrics.width);
+      }
+    }
+  }
+}
diff --git a/apps/web/src/terminal/ghostty/runtime.ts b/apps/web/src/terminal/ghostty/runtime.ts
new file mode 100644
index 00000000000..aca82e7cc3c
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/runtime.ts
@@ -0,0 +1,221 @@
+import ghosttyWasmUrl from "./vendor/ghostty-vt.wasm?url";
+import ghosttyWritePtyWasmUrl from "./vendor/ghostty-write-pty.wasm?url&no-inline";
+
+type WasmFunction = (...args: Array<number | bigint>) => number;
+
+interface TypeField {
+  readonly offset: number;
+  readonly size: number;
+  readonly type: string;
+}
+
+interface TypeLayout {
+  readonly size: number;
+  readonly align: number;
+  readonly fields: Readonly<Record<string, TypeField>>;
+}
+
+type TypeLayouts = Readonly<Record<string, TypeLayout>>;
+
+const textDecoder = new TextDecoder();
+
+export class GhosttyRuntime {
+  readonly memory: WebAssembly.Memory;
+  readonly layouts: TypeLayouts;
+  private readonly exports: WebAssembly.Exports;
+  private readonly ptyWriters = new Map<number, (data: string) => void>();
+  private nextPtyWriterId = 1;
+  private writePtyFunctionIndex = 0;
+
+  private constructor(instance: WebAssembly.Instance) {
+    this.exports = instance.exports;
+    const memory = instance.exports.memory;
+    if (!(memory instanceof WebAssembly.Memory)) {
+      throw new Error("libghostty-vt did not export WebAssembly memory");
+    }
+    this.memory = memory;
+    const jsonPointer = this.call("ghostty_type_json");
+    const bytes = new Uint8Array(memory.buffer);
+    let end = jsonPointer;
+    while (end < bytes.length && bytes[end] !== 0) end += 1;
+    this.layouts = JSON.parse(textDecoder.decode(bytes.subarray(jsonPointer, end))) as TypeLayouts;
+  }
+
+  static async load(): Promise<GhosttyRuntime> {
+    const response = await fetch(ghosttyWasmUrl);
+    if (!response.ok) {
+      throw new Error(`Unable to load libghostty-vt (${response.status})`);
+    }
+    let instance: WebAssembly.Instance | undefined;
+    const imports = {
+      env: {
+        log: (pointer: number, length: number) => {
+          if (!instance) return;
+          const memory = instance.exports.memory;
+          if (!(memory instanceof WebAssembly.Memory)) return;
+          const message = textDecoder.decode(new Uint8Array(memory.buffer, pointer, length));
+          console.debug("[libghostty-vt]", message);
+        },
+      },
+    };
+    const result = await WebAssembly.instantiate(await response.arrayBuffer(), imports);
+    instance = result.instance;
+    const runtime = new GhosttyRuntime(result.instance);
+    await runtime.installWritePtyTrampoline();
+    return runtime;
+  }
+
+  call(name: string, ...args: Array<number | bigint>): number {
+    const fn = this.exports[name];
+    if (typeof fn !== "function") {
+      throw new Error(`libghostty-vt export is unavailable: ${name}`);
+    }
+    return (fn as WasmFunction)(...args);
+  }
+
+  layout(name: string): TypeLayout {
+    const layout = this.layouts[name];
+    if (!layout) throw new Error(`libghostty-vt type layout is unavailable: ${name}`);
+    return layout;
+  }
+
+  alloc(size: number): number {
+    const pointer = this.call("ghostty_wasm_alloc_u8_array", size);
+    if (pointer === 0) throw new Error(`libghostty-vt failed to allocate ${size} bytes`);
+    new Uint8Array(this.memory.buffer, pointer, size).fill(0);
+    return pointer;
+  }
+
+  free(pointer: number, size: number): void {
+    if (pointer !== 0) this.call("ghostty_wasm_free_u8_array", pointer, size);
+  }
+
+  allocOpaque(): number {
+    const pointer = this.call("ghostty_wasm_alloc_opaque");
+    if (pointer === 0) throw new Error("libghostty-vt failed to allocate an opaque pointer");
+    // The slot is uninitialized until a *_new call writes it; zero it so dispose
+    // paths that run after a partial initialization never free a garbage pointer.
+    new DataView(this.memory.buffer).setUint32(pointer, 0, true);
+    return pointer;
+  }
+
+  freeOpaque(pointer: number): void {
+    if (pointer !== 0) this.call("ghostty_wasm_free_opaque", pointer);
+  }
+
+  readPointer(slot: number): number {
+    return new DataView(this.memory.buffer).getUint32(slot, true);
+  }
+
+  attachPtyWriter(terminal: number, writer: (data: string) => void): number {
+    if (this.writePtyFunctionIndex === 0) {
+      throw new Error("libghostty-vt PTY callback trampoline is unavailable");
+    }
+    const id = this.nextPtyWriterId++;
+    this.ptyWriters.set(id, writer);
+    this.call("ghostty_terminal_set", terminal, 0, id);
+    this.call("ghostty_terminal_set", terminal, 1, this.writePtyFunctionIndex);
+    return id;
+  }
+
+  detachPtyWriter(terminal: number, id: number): void {
+    this.call("ghostty_terminal_set", terminal, 1, 0);
+    this.call("ghostty_terminal_set", terminal, 0, 0);
+    this.ptyWriters.delete(id);
+  }
+
+  view(pointer: number, size?: number): DataView {
+    return new DataView(this.memory.buffer, pointer, size);
+  }
+
+  bytes(pointer: number, size: number): Uint8Array {
+    return new Uint8Array(this.memory.buffer, pointer, size);
+  }
+
+  setField(pointer: number, structName: string, fieldName: string, value: number): void {
+    const field = this.layout(structName).fields[fieldName];
+    if (!field) throw new Error(`libghostty-vt field is unavailable: ${structName}.${fieldName}`);
+    const view = this.view(pointer + field.offset, field.size);
+    switch (field.type) {
+      case "bool":
+      case "u8":
+        view.setUint8(0, value);
+        return;
+      case "u16":
+        view.setUint16(0, value, true);
+        return;
+      case "i32":
+        view.setInt32(0, value, true);
+        return;
+      case "u32":
+      case "enum":
+        view.setUint32(0, value, true);
+        return;
+      case "u64":
+        view.setBigUint64(0, BigInt(value), true);
+        return;
+      default:
+        throw new Error(`Unsupported libghostty-vt field type: ${field.type}`);
+    }
+  }
+
+  readField(pointer: number, structName: string, fieldName: string): number {
+    const field = this.layout(structName).fields[fieldName];
+    if (!field) throw new Error(`libghostty-vt field is unavailable: ${structName}.${fieldName}`);
+    const view = this.view(pointer + field.offset, field.size);
+    switch (field.type) {
+      case "bool":
+      case "u8":
+        return view.getUint8(0);
+      case "u16":
+        return view.getUint16(0, true);
+      case "i32":
+        return view.getInt32(0, true);
+      case "u32":
+      case "enum":
+        return view.getUint32(0, true);
+      case "u64":
+        return Number(view.getBigUint64(0, true));
+      default:
+        throw new Error(`Unsupported libghostty-vt field type: ${field.type}`);
+    }
+  }
+
+  private async installWritePtyTrampoline(): Promise<void> {
+    const response = await fetch(ghosttyWritePtyWasmUrl);
+    if (!response.ok) {
+      throw new Error(`Unable to load the libghostty-vt PTY trampoline (${response.status})`);
+    }
+    const result = await WebAssembly.instantiate(await response.arrayBuffer(), {
+      env: {
+        t3_write_pty: (_terminal: number, userdata: number, pointer: number, length: number) => {
+          const writer = this.ptyWriters.get(userdata);
+          if (!writer || length === 0) return;
+          writer(textDecoder.decode(new Uint8Array(this.memory.buffer, pointer, length)));
+        },
+      },
+    });
+    const trampoline = result.instance.exports.ghostty_write_pty;
+    const table = this.exports.__indirect_function_table;
+    if (typeof trampoline !== "function" || !(table instanceof WebAssembly.Table)) {
+      throw new Error("libghostty-vt did not expose its callback table");
+    }
+    const index = table.length;
+    // grow-then-set instead of grow(1, fn): WebKit stores a grow init value
+    // with broken type information and every later call_indirect through the
+    // entry traps with a signature mismatch. table.set canonicalizes correctly.
+    table.grow(1);
+    table.set(index, trampoline);
+    this.writePtyFunctionIndex = index;
+  }
+}
+
+let runtimePromise: Promise<GhosttyRuntime> | null = null;
+
+export function loadGhosttyRuntime(): Promise<GhosttyRuntime> {
+  runtimePromise ??= GhosttyRuntime.load().catch((error) => {
+    runtimePromise = null;
+    throw error;
+  });
+  return runtimePromise;
+}
diff --git a/apps/web/src/terminal/ghostty/runtimeAbi.test.ts b/apps/web/src/terminal/ghostty/runtimeAbi.test.ts
new file mode 100644
index 00000000000..b77cfd32bdd
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/runtimeAbi.test.ts
@@ -0,0 +1,561 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import wasmDataUrl from "./vendor/ghostty-vt.wasm?inline";
+import writePtyWasmDataUrl from "./vendor/ghostty-write-pty.wasm?inline";
+import pinnedVersion from "../../../../../native/libghostty-vt/VERSION?raw";
+import { ghosttyKeyForCode } from "./keyCodes";
+
+type WasmFunction = (...args: number[]) => number;
+
+function decodeWasmDataUrl(dataUrl: string): Uint8Array {
+  const encoded = dataUrl.split(",", 2)[1];
+  if (!encoded) throw new Error("The vendored Ghostty WASM data URL is invalid");
+  return Uint8Array.from(atob(encoded), (character) => character.charCodeAt(0));
+}
+
+describe("vendored libghostty-vt WebAssembly", () => {
+  it("stays pinned to the canonical revision and size budget", async () => {
+    const wasm = decodeWasmDataUrl(wasmDataUrl);
+    expect(wasm.byteLength).toBeLessThan(750_000);
+
+    // The artifact carries its own provenance: the build embeds the pinned
+    // revision as semver build metadata, so the repository's canonical VERSION
+    // file is the single source of truth and drift is caught here without a copy.
+    const result = await WebAssembly.instantiate(wasm.buffer as ArrayBuffer, {
+      env: { log: () => {} },
+    });
+    const instance = result instanceof WebAssembly.Instance ? result : result.instance;
+    const memory = instance.exports.memory as WebAssembly.Memory;
+    const call = (name: string, ...args: number[]) =>
+      (instance.exports[name] as WasmFunction)(...args);
+    const out = call("ghostty_wasm_alloc_u8_array", 8);
+    expect(call("ghostty_build_info", 10, out)).toBe(0);
+    const view = new DataView(memory.buffer, out, 8);
+    const embeddedRevision = new TextDecoder().decode(
+      new Uint8Array(memory.buffer, view.getUint32(0, true), view.getUint32(4, true)),
+    );
+    call("ghostty_wasm_free_u8_array", out, 8);
+    expect(embeddedRevision).toBe(pinnedVersion.trim());
+  });
+
+  it("creates, writes multi-codepoint graphemes, and frees repeated terminals", async () => {
+    const bytes = decodeWasmDataUrl(wasmDataUrl);
+    let memory: WebAssembly.Memory | null = null;
+    const instantiated = await WebAssembly.instantiate(bytes.buffer as ArrayBuffer, {
+      env: {
+        log: () => {},
+      },
+    });
+    const instance =
+      instantiated instanceof WebAssembly.Instance ? instantiated : instantiated.instance;
+    const exports = instance.exports;
+    memory = exports.memory as WebAssembly.Memory;
+    const call = (name: string, ...args: number[]) => (exports[name] as WasmFunction)(...args);
+    const jsonPointer = call("ghostty_type_json");
+    const jsonBytes = new Uint8Array(memory.buffer, jsonPointer);
+    const jsonEnd = jsonBytes.indexOf(0);
+    const layouts = JSON.parse(new TextDecoder().decode(jsonBytes.subarray(0, jsonEnd))) as Record<
+      string,
+      { size: number }
+    >;
+    const optionsSize = layouts.GhosttyTerminalOptions?.size;
+    expect(optionsSize).toBe(8);
+    if (optionsSize === undefined) throw new Error("GhosttyTerminalOptions layout is missing");
+
+    for (let iteration = 0; iteration < 25; iteration += 1) {
+      const options = call("ghostty_wasm_alloc_u8_array", optionsSize);
+      const optionsView = new DataView(memory.buffer, options, optionsSize);
+      optionsView.setUint16(0, 80, true);
+      optionsView.setUint16(2, 24, true);
+      optionsView.setUint32(4, 5_000, true);
+      const terminalSlot = call("ghostty_wasm_alloc_opaque");
+      expect(call("ghostty_terminal_new", 0, terminalSlot, options)).toBe(0);
+      const terminal = new DataView(memory.buffer).getUint32(terminalSlot, true);
+
+      const input = new TextEncoder().encode("e\u0301 👨‍👩‍👧‍👦 العربية\r\n");
+      const inputPointer = call("ghostty_wasm_alloc_u8_array", input.length);
+      new Uint8Array(memory.buffer, inputPointer, input.length).set(input);
+      call("ghostty_terminal_vt_write", terminal, inputPointer, input.length);
+      call("ghostty_wasm_free_u8_array", inputPointer, input.length);
+      call("ghostty_terminal_free", terminal);
+      call("ghostty_wasm_free_opaque", terminalSlot);
+      call("ghostty_wasm_free_u8_array", options, optionsSize);
+    }
+  });
+
+  it("reports and scrolls the viewport with Ghostty's scrollbar state", async () => {
+    const result = await WebAssembly.instantiate(
+      decodeWasmDataUrl(wasmDataUrl).buffer as ArrayBuffer,
+      { env: { log: () => {} } },
+    );
+    const instance = result instanceof WebAssembly.Instance ? result : result.instance;
+    const memory = instance.exports.memory as WebAssembly.Memory;
+    const call = (name: string, ...args: number[]) =>
+      (instance.exports[name] as WasmFunction)(...args);
+    const alloc = (size: number) => call("ghostty_wasm_alloc_u8_array", size);
+    const options = alloc(8);
+    const optionsView = new DataView(memory.buffer, options, 8);
+    optionsView.setUint16(0, 80, true);
+    optionsView.setUint16(2, 10, true);
+    optionsView.setUint32(4, 1_000, true);
+    const terminalSlot = call("ghostty_wasm_alloc_opaque");
+    expect(call("ghostty_terminal_new", 0, terminalSlot, options)).toBe(0);
+    const terminal = new DataView(memory.buffer).getUint32(terminalSlot, true);
+    const input = new TextEncoder().encode(
+      Array.from({ length: 50 }, (_, index) => `${index + 1}\r\n`).join(""),
+    );
+    const inputPointer = alloc(input.length);
+    new Uint8Array(memory.buffer, inputPointer, input.length).set(input);
+    call("ghostty_terminal_vt_write", terminal, inputPointer, input.length);
+
+    const scrollbar = alloc(24);
+    const scrollbarView = new DataView(memory.buffer, scrollbar, 24);
+    expect(call("ghostty_terminal_get", terminal, 9, scrollbar)).toBe(0);
+    expect([0, 8, 16].map((offset) => Number(scrollbarView.getBigUint64(offset, true)))).toEqual([
+      51, 41, 10,
+    ]);
+
+    const scroll = alloc(24);
+    const scrollView = new DataView(memory.buffer, scroll, 24);
+    scrollView.setUint32(0, 2, true);
+    scrollView.setInt32(8, -5, true);
+    call("ghostty_terminal_scroll_viewport", terminal, scroll);
+    expect(call("ghostty_terminal_get", terminal, 9, scrollbar)).toBe(0);
+    expect(Number(scrollbarView.getBigUint64(8, true))).toBe(36);
+
+    call("ghostty_wasm_free_u8_array", scroll, 24);
+    call("ghostty_wasm_free_u8_array", scrollbar, 24);
+    call("ghostty_wasm_free_u8_array", inputPointer, input.length);
+    call("ghostty_terminal_free", terminal);
+    call("ghostty_wasm_free_opaque", terminalSlot);
+    call("ghostty_wasm_free_u8_array", options, 8);
+  });
+
+  it("routes terminal-generated replies through the shared callback table", async () => {
+    const mainResult = await WebAssembly.instantiate(
+      decodeWasmDataUrl(wasmDataUrl).buffer as ArrayBuffer,
+      { env: { log: () => {} } },
+    );
+    const main = mainResult instanceof WebAssembly.Instance ? mainResult : mainResult.instance;
+    const memory = main.exports.memory as WebAssembly.Memory;
+    let reply = "";
+    const trampolineResult = await WebAssembly.instantiate(
+      decodeWasmDataUrl(writePtyWasmDataUrl).buffer as ArrayBuffer,
+      {
+        env: {
+          t3_write_pty: (_terminal: number, _userdata: number, pointer: number, length: number) => {
+            reply += new TextDecoder().decode(new Uint8Array(memory.buffer, pointer, length));
+          },
+        },
+      },
+    );
+    const trampoline =
+      trampolineResult instanceof WebAssembly.Instance
+        ? trampolineResult
+        : trampolineResult.instance;
+    const table = main.exports.__indirect_function_table as WebAssembly.Table;
+    const callbackIndex = table.length;
+    table.grow(1, trampoline.exports.ghostty_write_pty as CallableFunction);
+    const call = (name: string, ...args: number[]) => (main.exports[name] as WasmFunction)(...args);
+    const options = call("ghostty_wasm_alloc_u8_array", 8);
+    const optionsView = new DataView(memory.buffer, options, 8);
+    optionsView.setUint16(0, 80, true);
+    optionsView.setUint16(2, 24, true);
+    const terminalSlot = call("ghostty_wasm_alloc_opaque");
+    expect(call("ghostty_terminal_new", 0, terminalSlot, options)).toBe(0);
+    const terminal = new DataView(memory.buffer).getUint32(terminalSlot, true);
+    call("ghostty_terminal_set", terminal, 0, 1);
+    call("ghostty_terminal_set", terminal, 1, callbackIndex);
+    const query = new TextEncoder().encode("\u001b[5n");
+    const queryPointer = call("ghostty_wasm_alloc_u8_array", query.length);
+    new Uint8Array(memory.buffer, queryPointer, query.length).set(query);
+    call("ghostty_terminal_vt_write", terminal, queryPointer, query.length);
+
+    expect(reply).toBe("\u001b[0n");
+    reply = "";
+    call("ghostty_terminal_set", terminal, 1, 0);
+    call("ghostty_terminal_set", terminal, 0, 0);
+    call("ghostty_terminal_vt_write", terminal, queryPointer, query.length);
+    expect(reply).toBe("");
+    call("ghostty_terminal_set", terminal, 0, 1);
+    call("ghostty_terminal_set", terminal, 1, callbackIndex);
+    call("ghostty_terminal_vt_write", terminal, queryPointer, query.length);
+    expect(reply).toBe("\u001b[0n");
+    call("ghostty_wasm_free_u8_array", queryPointer, query.length);
+    call("ghostty_terminal_free", terminal);
+    call("ghostty_wasm_free_opaque", terminalSlot);
+    call("ghostty_wasm_free_u8_array", options, 8);
+  });
+
+  it("formats the active selection with Ghostty's copy semantics", async () => {
+    const result = await WebAssembly.instantiate(
+      decodeWasmDataUrl(wasmDataUrl).buffer as ArrayBuffer,
+      { env: { log: () => {} } },
+    );
+    const instance = result instanceof WebAssembly.Instance ? result : result.instance;
+    const memory = instance.exports.memory as WebAssembly.Memory;
+    const call = (name: string, ...args: number[]) =>
+      (instance.exports[name] as WasmFunction)(...args);
+    const options = call("ghostty_wasm_alloc_u8_array", 8);
+    const optionsView = new DataView(memory.buffer, options, 8);
+    optionsView.setUint16(0, 80, true);
+    optionsView.setUint16(2, 24, true);
+    const terminalSlot = call("ghostty_wasm_alloc_opaque");
+    expect(call("ghostty_terminal_new", 0, terminalSlot, options)).toBe(0);
+    const terminal = new DataView(memory.buffer).getUint32(terminalSlot, true);
+    const input = new TextEncoder().encode("a\r\n\r\nb");
+    const inputPointer = call("ghostty_wasm_alloc_u8_array", input.length);
+    new Uint8Array(memory.buffer, inputPointer, input.length).set(input);
+    call("ghostty_terminal_vt_write", terminal, inputPointer, input.length);
+
+    const selection = call("ghostty_wasm_alloc_u8_array", 32);
+    new DataView(memory.buffer, selection, 32).setUint32(0, 32, true);
+    expect(call("ghostty_terminal_select_all", terminal, selection)).toBe(0);
+    expect(call("ghostty_terminal_set", terminal, 21, selection)).toBe(0);
+    const formatOptions = call("ghostty_wasm_alloc_u8_array", 16);
+    const formatView = new DataView(memory.buffer, formatOptions, 16);
+    formatView.setUint32(0, 16, true);
+    formatView.setUint8(8, 1);
+    formatView.setUint8(9, 1);
+    const written = call("ghostty_wasm_alloc_usize");
+    expect(
+      call("ghostty_terminal_selection_format_buf", terminal, formatOptions, 0, 0, written),
+    ).toBe(-3);
+    const outputSize = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    const output = call("ghostty_wasm_alloc_u8_array", outputSize);
+    expect(
+      call(
+        "ghostty_terminal_selection_format_buf",
+        terminal,
+        formatOptions,
+        output,
+        outputSize,
+        written,
+      ),
+    ).toBe(0);
+    expect(new TextDecoder().decode(new Uint8Array(memory.buffer, output, outputSize))).toBe(
+      "a\n\nb",
+    );
+
+    call("ghostty_wasm_free_u8_array", output, outputSize);
+    call("ghostty_wasm_free_usize", written);
+    call("ghostty_wasm_free_u8_array", formatOptions, 16);
+    call("ghostty_wasm_free_u8_array", selection, 32);
+    call("ghostty_wasm_free_u8_array", inputPointer, input.length);
+    call("ghostty_terminal_free", terminal);
+    call("ghostty_wasm_free_opaque", terminalSlot);
+    call("ghostty_wasm_free_u8_array", options, 8);
+  });
+
+  it("uses Ghostty for mouse encoding, word selection, and OSC 8 hit testing", async () => {
+    const result = await WebAssembly.instantiate(
+      decodeWasmDataUrl(wasmDataUrl).buffer as ArrayBuffer,
+      { env: { log: () => {} } },
+    );
+    const instance = result instanceof WebAssembly.Instance ? result : result.instance;
+    const memory = instance.exports.memory as WebAssembly.Memory;
+    const call = (name: string, ...args: number[]) =>
+      (instance.exports[name] as WasmFunction)(...args);
+    const alloc = (size: number) => call("ghostty_wasm_alloc_u8_array", size);
+    const free = (pointer: number, size: number) =>
+      call("ghostty_wasm_free_u8_array", pointer, size);
+
+    const terminalOptions = alloc(8);
+    const terminalOptionsView = new DataView(memory.buffer, terminalOptions, 8);
+    terminalOptionsView.setUint16(0, 80, true);
+    terminalOptionsView.setUint16(2, 24, true);
+    const terminalSlot = call("ghostty_wasm_alloc_opaque");
+    expect(call("ghostty_terminal_new", 0, terminalSlot, terminalOptions)).toBe(0);
+    const terminal = new DataView(memory.buffer).getUint32(terminalSlot, true);
+    const input = new TextEncoder().encode(
+      "\u001b[?1000h\u001b[?1006h\u001b]8;;https://t3.codes/docs\u001b\\linked\u001b]8;;\u001b\\ plain",
+    );
+    const inputPointer = alloc(input.length);
+    new Uint8Array(memory.buffer, inputPointer, input.length).set(input);
+    call("ghostty_terminal_vt_write", terminal, inputPointer, input.length);
+
+    const modeFlag = alloc(1);
+    new Uint8Array(memory.buffer, modeFlag, 1)[0] = 0;
+    expect(call("ghostty_terminal_get", terminal, 11, modeFlag)).toBe(0);
+    expect(new Uint8Array(memory.buffer, modeFlag, 1)[0]).toBe(1);
+    new Uint8Array(memory.buffer, modeFlag, 1)[0] = 1;
+    expect(call("ghostty_terminal_mode_get", terminal, 1003, modeFlag)).toBe(0);
+    expect(new Uint8Array(memory.buffer, modeFlag, 1)[0]).toBe(0);
+    const anyEventInput = new TextEncoder().encode("\u001b[?1003h");
+    const anyEventPointer = alloc(anyEventInput.length);
+    new Uint8Array(memory.buffer, anyEventPointer, anyEventInput.length).set(anyEventInput);
+    call("ghostty_terminal_vt_write", terminal, anyEventPointer, anyEventInput.length);
+    expect(call("ghostty_terminal_mode_get", terminal, 1003, modeFlag)).toBe(0);
+    expect(new Uint8Array(memory.buffer, modeFlag, 1)[0]).toBe(1);
+    const anyEventReset = new TextEncoder().encode("\u001b[?1003l\u001b[?1000h");
+    const anyEventResetPointer = alloc(anyEventReset.length);
+    new Uint8Array(memory.buffer, anyEventResetPointer, anyEventReset.length).set(anyEventReset);
+    call("ghostty_terminal_vt_write", terminal, anyEventResetPointer, anyEventReset.length);
+    expect(call("ghostty_terminal_mode_get", terminal, 1003, modeFlag)).toBe(0);
+    expect(new Uint8Array(memory.buffer, modeFlag, 1)[0]).toBe(0);
+    free(anyEventResetPointer, anyEventReset.length);
+    free(anyEventPointer, anyEventInput.length);
+    free(modeFlag, 1);
+
+    const point = alloc(24);
+    const pointView = new DataView(memory.buffer, point, 24);
+    pointView.setUint32(0, 1, true);
+    pointView.setUint16(8, 1, true);
+    pointView.setUint32(12, 0, true);
+    const gridRef = alloc(12);
+    new DataView(memory.buffer, gridRef, 12).setUint32(0, 12, true);
+    expect(call("ghostty_terminal_grid_ref", terminal, point, gridRef)).toBe(0);
+
+    const written = call("ghostty_wasm_alloc_usize");
+    expect(call("ghostty_grid_ref_hyperlink_uri", gridRef, 0, 0, written)).toBe(-3);
+    const hyperlinkSize = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    const hyperlink = alloc(hyperlinkSize);
+    expect(call("ghostty_grid_ref_hyperlink_uri", gridRef, hyperlink, hyperlinkSize, written)).toBe(
+      0,
+    );
+    expect(new TextDecoder().decode(new Uint8Array(memory.buffer, hyperlink, hyperlinkSize))).toBe(
+      "https://t3.codes/docs",
+    );
+
+    const wordOptions = alloc(24);
+    const wordOptionsView = new DataView(memory.buffer, wordOptions, 24);
+    wordOptionsView.setUint32(0, 24, true);
+    new Uint8Array(memory.buffer, wordOptions + 4, 12).set(
+      new Uint8Array(memory.buffer, gridRef, 12),
+    );
+    const selection = alloc(32);
+    new DataView(memory.buffer, selection, 32).setUint32(0, 32, true);
+    expect(call("ghostty_terminal_select_word", terminal, wordOptions, selection)).toBe(0);
+    expect(call("ghostty_terminal_set", terminal, 21, selection)).toBe(0);
+    const formatOptions = alloc(16);
+    const formatView = new DataView(memory.buffer, formatOptions, 16);
+    formatView.setUint32(0, 16, true);
+    formatView.setUint8(8, 1);
+    formatView.setUint8(9, 1);
+    expect(
+      call("ghostty_terminal_selection_format_buf", terminal, formatOptions, 0, 0, written),
+    ).toBe(-3);
+    const selectionSize = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    const selectionText = alloc(selectionSize);
+    expect(
+      call(
+        "ghostty_terminal_selection_format_buf",
+        terminal,
+        formatOptions,
+        selectionText,
+        selectionSize,
+        written,
+      ),
+    ).toBe(0);
+    expect(
+      new TextDecoder().decode(new Uint8Array(memory.buffer, selectionText, selectionSize)),
+    ).toBe("linked");
+
+    const lineOptions = alloc(28);
+    const lineOptionsView = new DataView(memory.buffer, lineOptions, 28);
+    lineOptionsView.setUint32(0, 28, true);
+    new Uint8Array(memory.buffer, lineOptions + 4, 12).set(
+      new Uint8Array(memory.buffer, gridRef, 12),
+    );
+    expect(call("ghostty_terminal_select_line", terminal, lineOptions, selection)).toBe(0);
+    expect(call("ghostty_terminal_set", terminal, 21, selection)).toBe(0);
+    expect(
+      call("ghostty_terminal_selection_format_buf", terminal, formatOptions, 0, 0, written),
+    ).toBe(-3);
+    const lineSelectionSize = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    const lineSelectionText = alloc(lineSelectionSize);
+    expect(
+      call(
+        "ghostty_terminal_selection_format_buf",
+        terminal,
+        formatOptions,
+        lineSelectionText,
+        lineSelectionSize,
+        written,
+      ),
+    ).toBe(0);
+    expect(
+      new TextDecoder().decode(new Uint8Array(memory.buffer, lineSelectionText, lineSelectionSize)),
+    ).toBe("linked plain");
+
+    const mouseEncoderSlot = call("ghostty_wasm_alloc_opaque");
+    const mouseEventSlot = call("ghostty_wasm_alloc_opaque");
+    expect(call("ghostty_mouse_encoder_new", 0, mouseEncoderSlot)).toBe(0);
+    expect(call("ghostty_mouse_event_new", 0, mouseEventSlot)).toBe(0);
+    const view = new DataView(memory.buffer);
+    const mouseEncoder = view.getUint32(mouseEncoderSlot, true);
+    const mouseEvent = view.getUint32(mouseEventSlot, true);
+    call("ghostty_mouse_encoder_setopt_from_terminal", mouseEncoder, terminal);
+    const mouseSize = alloc(36);
+    const mouseSizeView = new DataView(memory.buffer, mouseSize, 36);
+    for (const [offset, value] of [
+      [0, 36],
+      [4, 800],
+      [8, 480],
+      [12, 10],
+      [16, 20],
+    ] as const) {
+      mouseSizeView.setUint32(offset, value, true);
+    }
+    call("ghostty_mouse_encoder_setopt", mouseEncoder, 2, mouseSize);
+    call("ghostty_mouse_event_set_action", mouseEvent, 0);
+    call("ghostty_mouse_event_set_button", mouseEvent, 1);
+    const mousePosition = new DataView(new ArrayBuffer(8));
+    mousePosition.setFloat32(0, 15, true);
+    mousePosition.setFloat32(4, 25, true);
+    const mousePositionPointer = alloc(8);
+    new Uint8Array(memory.buffer, mousePositionPointer, 8).set(
+      new Uint8Array(mousePosition.buffer),
+    );
+    call("ghostty_mouse_event_set_position", mouseEvent, mousePositionPointer);
+    const mouseOutput = alloc(128);
+    expect(
+      call("ghostty_mouse_encoder_encode", mouseEncoder, mouseEvent, mouseOutput, 128, written),
+    ).toBe(0);
+    const mouseOutputSize = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    expect(
+      new TextDecoder().decode(new Uint8Array(memory.buffer, mouseOutput, mouseOutputSize)),
+    ).toBe("\u001b[<0;2;2M");
+
+    call("ghostty_mouse_event_free", mouseEvent);
+    call("ghostty_mouse_encoder_free", mouseEncoder);
+    call("ghostty_wasm_free_opaque", mouseEventSlot);
+    call("ghostty_wasm_free_opaque", mouseEncoderSlot);
+    free(mousePositionPointer, 8);
+    free(mouseOutput, 128);
+    free(mouseSize, 36);
+    free(lineSelectionText, lineSelectionSize);
+    free(lineOptions, 28);
+    free(selectionText, selectionSize);
+    free(formatOptions, 16);
+    free(selection, 32);
+    free(wordOptions, 24);
+    free(hyperlink, hyperlinkSize);
+    call("ghostty_wasm_free_usize", written);
+    free(gridRef, 12);
+    free(point, 24);
+    free(inputPointer, input.length);
+    call("ghostty_terminal_free", terminal);
+    call("ghostty_wasm_free_opaque", terminalSlot);
+    free(terminalOptions, 8);
+  });
+
+  it("encodes modified printable keys in Kitty keyboard mode", async () => {
+    const result = await WebAssembly.instantiate(
+      decodeWasmDataUrl(wasmDataUrl).buffer as ArrayBuffer,
+      { env: { log: () => {} } },
+    );
+    const instance = result instanceof WebAssembly.Instance ? result : result.instance;
+    const memory = instance.exports.memory as WebAssembly.Memory;
+    const call = (name: string, ...args: number[]) =>
+      (instance.exports[name] as WasmFunction)(...args);
+    const alloc = (size: number) => call("ghostty_wasm_alloc_u8_array", size);
+    const free = (pointer: number, size: number) =>
+      call("ghostty_wasm_free_u8_array", pointer, size);
+
+    const terminalOptions = alloc(8);
+    const terminalOptionsView = new DataView(memory.buffer, terminalOptions, 8);
+    terminalOptionsView.setUint16(0, 80, true);
+    terminalOptionsView.setUint16(2, 24, true);
+    const terminalSlot = call("ghostty_wasm_alloc_opaque");
+    expect(call("ghostty_terminal_new", 0, terminalSlot, terminalOptions)).toBe(0);
+    const terminal = new DataView(memory.buffer).getUint32(terminalSlot, true);
+    const kittyMode = new TextEncoder().encode("\u001b[>1u");
+    const kittyModePointer = alloc(kittyMode.length);
+    new Uint8Array(memory.buffer, kittyModePointer, kittyMode.length).set(kittyMode);
+    call("ghostty_terminal_vt_write", terminal, kittyModePointer, kittyMode.length);
+
+    const encoderSlot = call("ghostty_wasm_alloc_opaque");
+    const eventSlot = call("ghostty_wasm_alloc_opaque");
+    expect(call("ghostty_key_encoder_new", 0, encoderSlot)).toBe(0);
+    expect(call("ghostty_key_event_new", 0, eventSlot)).toBe(0);
+    const view = new DataView(memory.buffer);
+    const keyEncoder = view.getUint32(encoderSlot, true);
+    const keyEvent = view.getUint32(eventSlot, true);
+    call("ghostty_key_encoder_setopt_from_terminal", keyEncoder, terminal);
+    call("ghostty_key_event_set_action", keyEvent, 1);
+    call("ghostty_key_event_set_key", keyEvent, ghosttyKeyForCode("KeyC"));
+    call("ghostty_key_event_set_mods", keyEvent, 1 << 1);
+    call("ghostty_key_event_set_consumed_mods", keyEvent, 0);
+    call("ghostty_key_event_set_composing", keyEvent, 0);
+    call("ghostty_key_event_set_unshifted_codepoint", keyEvent, "c".codePointAt(0)!);
+    const text = new TextEncoder().encode("c");
+    const textPointer = alloc(text.length);
+    new Uint8Array(memory.buffer, textPointer, text.length).set(text);
+    call("ghostty_key_event_set_utf8", keyEvent, textPointer, text.length);
+
+    const written = call("ghostty_wasm_alloc_usize");
+    expect(call("ghostty_key_encoder_encode", keyEncoder, keyEvent, 0, 0, written)).toBe(-3);
+    const outputSize = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    const output = alloc(outputSize);
+    expect(
+      call("ghostty_key_encoder_encode", keyEncoder, keyEvent, output, outputSize, written),
+    ).toBe(0);
+    const outputLength = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    expect(new TextDecoder().decode(new Uint8Array(memory.buffer, output, outputLength))).toBe(
+      "\u001b[99;5u",
+    );
+
+    const remappedText = new TextEncoder().encode("j");
+    const remappedTextPointer = alloc(remappedText.length);
+    new Uint8Array(memory.buffer, remappedTextPointer, remappedText.length).set(remappedText);
+    call("ghostty_key_event_set_unshifted_codepoint", keyEvent, "j".codePointAt(0)!);
+    call("ghostty_key_event_set_utf8", keyEvent, remappedTextPointer, remappedText.length);
+    expect(call("ghostty_key_encoder_encode", keyEncoder, keyEvent, 0, 0, written)).toBe(-3);
+    const remappedOutputSize = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    const remappedOutput = alloc(remappedOutputSize);
+    expect(
+      call(
+        "ghostty_key_encoder_encode",
+        keyEncoder,
+        keyEvent,
+        remappedOutput,
+        remappedOutputSize,
+        written,
+      ),
+    ).toBe(0);
+    const remappedOutputLength = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    expect(
+      new TextDecoder().decode(new Uint8Array(memory.buffer, remappedOutput, remappedOutputLength)),
+    ).toBe("\u001b[106;5u");
+
+    // Without the Kitty report-event-types flag a release encodes nothing, so
+    // the surface's keyup handler stays silent for legacy sessions.
+    call("ghostty_key_event_set_action", keyEvent, 0);
+    expect(call("ghostty_key_encoder_encode", keyEncoder, keyEvent, 0, 0, written)).toBe(0);
+    expect(new DataView(memory.buffer, written, 4).getUint32(0, true)).toBe(0);
+
+    // With report-event-types enabled the same release encodes an event-typed code.
+    const reportEvents = new TextEncoder().encode("\u001b[>3u");
+    const reportEventsPointer = alloc(reportEvents.length);
+    new Uint8Array(memory.buffer, reportEventsPointer, reportEvents.length).set(reportEvents);
+    call("ghostty_terminal_vt_write", terminal, reportEventsPointer, reportEvents.length);
+    call("ghostty_key_encoder_setopt_from_terminal", keyEncoder, terminal);
+    expect(call("ghostty_key_encoder_encode", keyEncoder, keyEvent, 0, 0, written)).toBe(-3);
+    const releaseSize = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    const releaseOutput = alloc(releaseSize);
+    expect(
+      call("ghostty_key_encoder_encode", keyEncoder, keyEvent, releaseOutput, releaseSize, written),
+    ).toBe(0);
+    const releaseLength = new DataView(memory.buffer, written, 4).getUint32(0, true);
+    expect(
+      new TextDecoder().decode(new Uint8Array(memory.buffer, releaseOutput, releaseLength)),
+    ).toBe("\u001b[106;5:3u");
+    free(releaseOutput, releaseSize);
+    free(reportEventsPointer, reportEvents.length);
+
+    free(remappedOutput, remappedOutputSize);
+    free(remappedTextPointer, remappedText.length);
+    free(output, outputSize);
+    call("ghostty_wasm_free_usize", written);
+    free(textPointer, text.length);
+    call("ghostty_key_event_free", keyEvent);
+    call("ghostty_key_encoder_free", keyEncoder);
+    call("ghostty_wasm_free_opaque", eventSlot);
+    call("ghostty_wasm_free_opaque", encoderSlot);
+    free(kittyModePointer, kittyMode.length);
+    call("ghostty_terminal_free", terminal);
+    call("ghostty_wasm_free_opaque", terminalSlot);
+    free(terminalOptions, 8);
+  });
+});
diff --git a/apps/web/src/terminal/ghostty/surface.test.ts b/apps/web/src/terminal/ghostty/surface.test.ts
new file mode 100644
index 00000000000..1cb9502649b
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/surface.test.ts
@@ -0,0 +1,383 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import type { GhosttyCell, GhosttyRow } from "./core";
+import {
+  DEFAULT_TERMINAL_FONT_FAMILY,
+  DEFAULT_TERMINAL_FONT_SIZE,
+  advanceTerminalSelectionClickSequence,
+  ghosttyMouseButton,
+  isTerminalAltGraphText,
+  isTerminalCompositionCommitInput,
+  isTerminalCopyShortcut,
+  isTerminalLinkPointerGesture,
+  isTerminalPasteShortcut,
+  shouldReportTerminalMouse,
+  terminalScrollbarGeometry,
+  terminalScrollbarOffsetAtPointer,
+  terminalLinkAtColumn,
+  terminalLinkAtPosition,
+  terminalContentOriginY,
+  terminalFontFamily,
+  terminalFontSize,
+  terminalWheelArrowData,
+  terminalWheelDeltaRows,
+} from "./surface";
+
+const cell = (text: string): GhosttyCell => ({
+  text,
+  wide: 0,
+  foreground: { r: 255, g: 255, b: 255 },
+  background: { r: 0, g: 0, b: 0 },
+  bold: false,
+  italic: false,
+  invisible: false,
+  strikethrough: false,
+  overline: false,
+  underline: false,
+  selected: false,
+});
+
+describe("isTerminalAltGraphText", () => {
+  it("defers printable AltGr output to the textarea input event", () => {
+    expect(
+      isTerminalAltGraphText({
+        key: "@",
+        getModifierState: (modifier) => modifier === "AltGraph",
+      }),
+    ).toBe(true);
+    expect(
+      isTerminalAltGraphText({
+        key: "ArrowRight",
+        getModifierState: (modifier) => modifier === "AltGraph",
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("terminalLinkAtColumn", () => {
+  it("maps terminal cells to UTF-16 offsets after a wide emoji", () => {
+    const cells = [
+      cell("🙂"),
+      cell(""),
+      ...Array.from("https://t3.codes", (character) => cell(character)),
+    ];
+    const row: GhosttyRow = {
+      cells,
+      text: cells
+        .map((value) => value.text || " ")
+        .join("")
+        .trimEnd(),
+      isWrapContinuation: false,
+      wrapsToNext: false,
+    };
+
+    expect(terminalLinkAtColumn(row, 2)).toBe("https://t3.codes");
+    expect(terminalLinkAtColumn(row, cells.length - 1)).toBe("https://t3.codes");
+    expect(terminalLinkAtColumn(row, 0)).toBeNull();
+  });
+
+  it("uses shared path matching and reconstructs soft-wrapped links", () => {
+    const row = (text: string, isWrapContinuation: boolean, wrapsToNext = false): GhosttyRow => ({
+      cells: Array.from(text.padEnd(16), (character) => cell(character)),
+      text: text.trimEnd(),
+      isWrapContinuation,
+      wrapsToNext,
+    });
+    const rows = [
+      row("https://example.", false),
+      row("com/reference", true),
+      row("~/project/file", false),
+      row("C:\\repo\\file.ts", false),
+    ];
+
+    expect(terminalLinkAtPosition(rows, 0, 8)).toBe("https://example.com/reference");
+    expect(terminalLinkAtPosition(rows, 1, 4)).toBe("https://example.com/reference");
+    expect(terminalLinkAtPosition(rows, 2, 2)).toBe("~/project/file");
+    expect(terminalLinkAtPosition(rows, 3, 4)).toBe("C:\\repo\\file.ts");
+  });
+
+  it("refuses links truncated at the viewport edges instead of mis-resolving", () => {
+    const row = (text: string, isWrapContinuation: boolean, wrapsToNext = false): GhosttyRow => ({
+      cells: Array.from(text.padEnd(16), (character) => cell(character)),
+      text: text.trimEnd(),
+      isWrapContinuation,
+      wrapsToNext,
+    });
+    // The head of the wrapped line scrolled above the viewport.
+    const headCut = [row("ple.com/missing", true), row("head", true)];
+    expect(terminalLinkAtPosition(headCut, 0, 4)).toBeNull();
+    // The bottom row soft-wraps on below the viewport.
+    const tailCut = [row("https://t3.codes", false, true)];
+    expect(terminalLinkAtPosition(tailCut, 0, 8)).toBeNull();
+    // A partial bottom row is provably complete and still resolves.
+    const complete = [row("https://t3.codes", false), row("", false)];
+    expect(terminalLinkAtPosition(complete, 0, 8)).toBe("https://t3.codes");
+    // A wide grapheme earlier in the row must not break truncation detection:
+    // the soft-wrap flag decides, not string-length-versus-cell-count.
+    const wideFull: GhosttyRow = {
+      cells: [
+        { ...cell("🙂"), wide: 1 },
+        { ...cell(""), wide: 2 },
+        ...Array.from("https://t3.code", (character) => cell(character)),
+      ],
+      text: "🙂 https://t3.code",
+      isWrapContinuation: false,
+      wrapsToNext: true,
+    };
+    expect(terminalLinkAtPosition([wideFull], 0, 8)).toBeNull();
+    // Unwritten trailing cells prove the bottom row is complete.
+    const unwrittenTail: GhosttyRow = {
+      cells: [
+        ...Array.from("https://t3.codes", (character) => cell(character)),
+        cell(""),
+        cell(""),
+      ],
+      text: "https://t3.codes",
+      isWrapContinuation: false,
+      wrapsToNext: false,
+    };
+    expect(terminalLinkAtPosition([unwrittenTail], 0, 8)).toBe("https://t3.codes");
+  });
+});
+
+describe("isTerminalCopyShortcut", () => {
+  const event = (overrides: Partial<Parameters<typeof isTerminalCopyShortcut>[0]> = {}) => ({
+    ctrlKey: false,
+    key: "c",
+    metaKey: false,
+    shiftKey: false,
+    ...overrides,
+  });
+
+  it("keeps Ctrl+C available for SIGINT on macOS", () => {
+    expect(isTerminalCopyShortcut(event({ ctrlKey: true }), "MacIntel")).toBe(false);
+    expect(isTerminalCopyShortcut(event({ metaKey: true }), "MacIntel")).toBe(true);
+  });
+
+  it("uses the conventional Ctrl+Shift+C shortcut elsewhere", () => {
+    expect(isTerminalCopyShortcut(event({ ctrlKey: true }), "Linux x86_64")).toBe(false);
+    expect(isTerminalCopyShortcut(event({ ctrlKey: true, shiftKey: true }), "Linux x86_64")).toBe(
+      true,
+    );
+  });
+
+  it("uses the produced character instead of the physical key position", () => {
+    expect(isTerminalCopyShortcut(event({ key: "C", metaKey: true }), "MacIntel")).toBe(true);
+    expect(isTerminalCopyShortcut(event({ key: "j", metaKey: true }), "MacIntel")).toBe(false);
+  });
+});
+
+describe("isTerminalPasteShortcut", () => {
+  const event = (overrides: Partial<Parameters<typeof isTerminalPasteShortcut>[0]> = {}) => ({
+    ctrlKey: false,
+    key: "v",
+    metaKey: false,
+    shiftKey: false,
+    ...overrides,
+  });
+
+  it("uses Cmd+V on macOS", () => {
+    expect(isTerminalPasteShortcut(event({ metaKey: true }), "MacIntel")).toBe(true);
+    expect(isTerminalPasteShortcut(event({ ctrlKey: true }), "MacIntel")).toBe(false);
+  });
+
+  it("preserves Ctrl+V and uses Ctrl+Shift+V elsewhere", () => {
+    expect(isTerminalPasteShortcut(event({ ctrlKey: true }), "Linux x86_64")).toBe(false);
+    expect(isTerminalPasteShortcut(event({ ctrlKey: true, shiftKey: true }), "Linux x86_64")).toBe(
+      true,
+    );
+  });
+});
+
+describe("isTerminalCompositionCommitInput", () => {
+  it("identifies browser composition follow-up input", () => {
+    expect(isTerminalCompositionCommitInput({ inputType: "" })).toBe(true);
+    expect(isTerminalCompositionCommitInput({ inputType: "insertCompositionText" })).toBe(true);
+    expect(isTerminalCompositionCommitInput({ inputType: "insertFromComposition" })).toBe(true);
+  });
+
+  it("keeps a fast repeated input as legitimate text", () => {
+    expect(isTerminalCompositionCommitInput({ inputType: "insertText" })).toBe(false);
+  });
+});
+
+describe("application mouse reporting", () => {
+  const event = (overrides: Partial<Parameters<typeof shouldReportTerminalMouse>[1]> = {}) => ({
+    ctrlKey: false,
+    metaKey: false,
+    shiftKey: false,
+    ...overrides,
+  });
+
+  it("keeps Shift and link activation modifiers available to the browser", () => {
+    expect(shouldReportTerminalMouse(true, event())).toBe(true);
+    expect(shouldReportTerminalMouse(true, event({ shiftKey: true }))).toBe(false);
+    expect(shouldReportTerminalMouse(true, event({ ctrlKey: true }))).toBe(false);
+    expect(shouldReportTerminalMouse(true, event({ metaKey: true }))).toBe(false);
+    expect(shouldReportTerminalMouse(false, event())).toBe(false);
+  });
+
+  it("maps browser buttons to Ghostty's button enum", () => {
+    expect([0, 1, 2, 3, 4, 5].map(ghosttyMouseButton)).toEqual([1, 3, 2, 4, 5, null]);
+  });
+});
+
+describe("terminal font resolution", () => {
+  it("keeps the glyph fallbacks behind a custom text face", () => {
+    expect(terminalFontFamily()).toBe(DEFAULT_TERMINAL_FONT_FAMILY);
+    expect(terminalFontFamily("  ")).toBe(DEFAULT_TERMINAL_FONT_FAMILY);
+    const custom = terminalFontFamily('"Fira Code"');
+    expect(custom.startsWith('"Fira Code", ')).toBe(true);
+    expect(custom).toContain('"Symbols Nerd Font Mono"');
+    expect(custom.endsWith("monospace")).toBe(true);
+  });
+
+  it("clamps requested font sizes to the supported range", () => {
+    expect(terminalFontSize()).toBe(DEFAULT_TERMINAL_FONT_SIZE);
+    expect(terminalFontSize(Number.NaN)).toBe(DEFAULT_TERMINAL_FONT_SIZE);
+    expect(terminalFontSize(13.4)).toBe(13);
+    expect(terminalFontSize(2)).toBe(6);
+    expect(terminalFontSize(90)).toBe(32);
+  });
+});
+
+describe("terminalContentOriginY", () => {
+  it("stays top-anchored like a fresh terminal until scrollback exists", () => {
+    expect(terminalContentOriginY(100, 4, 5, 16, false)).toBe(4);
+  });
+
+  it("pins the grid to the bottom by moving the sub-row slack above row 0", () => {
+    // 100px mount, 4px padding, 5 rows of 16px: 92 - 80 = 12px slack on top.
+    expect(terminalContentOriginY(100, 4, 5, 16, true)).toBe(16);
+    // Exact fit keeps the origin at the padding.
+    expect(terminalContentOriginY(88, 4, 5, 16, true)).toBe(4);
+    // A mount smaller than the grid never pushes the origin above the padding.
+    expect(terminalContentOriginY(80, 4, 5, 16, true)).toBe(4);
+  });
+
+  it("keeps the prompt stationary while a drag crosses row boundaries", () => {
+    // Growing the mount pixel by pixel: the bottom edge (origin + rows*cell)
+    // tracks the mount bottom exactly until a new row fits.
+    for (let height = 88; height < 104; height += 1) {
+      const rows = Math.max(1, Math.floor((height - 8) / 16));
+      const origin = terminalContentOriginY(height, 4, rows, 16, true);
+      expect(origin + rows * 16).toBe(height - 4);
+    }
+  });
+});
+
+describe("terminalWheelDeltaRows", () => {
+  it("converts line-mode deltas into whole rows", () => {
+    const result = terminalWheelDeltaRows({ deltaY: 3, deltaMode: 1 }, 16, 24, 0);
+    expect(result.rows).toBe(3);
+    expect(result.remainder).toBe(0);
+  });
+
+  it("accumulates fractional pixel deltas across events", () => {
+    let remainder = 0;
+    let scrolled = 0;
+    for (let index = 0; index < 4; index += 1) {
+      const result = terminalWheelDeltaRows({ deltaY: 5, deltaMode: 0 }, 16, 24, remainder);
+      remainder = result.remainder;
+      scrolled += result.rows;
+    }
+    expect(scrolled).toBe(1);
+    expect(remainder).toBeCloseTo(4 / 16);
+  });
+
+  it("keeps direction for negative page-mode deltas", () => {
+    const result = terminalWheelDeltaRows({ deltaY: -1, deltaMode: 2 }, 16, 24, 0);
+    expect(result.rows).toBe(-24);
+    expect(result.remainder).toBe(0);
+  });
+});
+
+describe("terminalWheelArrowData", () => {
+  it("emits one arrow per row honoring application cursor keys", () => {
+    expect(terminalWheelArrowData(-2, false)).toBe("\u001b[A\u001b[A");
+    expect(terminalWheelArrowData(3, false)).toBe("\u001b[B\u001b[B\u001b[B");
+    expect(terminalWheelArrowData(-1, true)).toBe("\u001bOA");
+    expect(terminalWheelArrowData(0, true)).toBe("");
+  });
+});
+
+describe("isTerminalLinkPointerGesture", () => {
+  it("uses Command on macOS and Control elsewhere", () => {
+    expect(isTerminalLinkPointerGesture({ ctrlKey: false, metaKey: true }, "MacIntel")).toBe(true);
+    expect(isTerminalLinkPointerGesture({ ctrlKey: true, metaKey: false }, "MacIntel")).toBe(false);
+    expect(isTerminalLinkPointerGesture({ ctrlKey: true, metaKey: false }, "Linux x86_64")).toBe(
+      true,
+    );
+    expect(isTerminalLinkPointerGesture({ ctrlKey: false, metaKey: true }, "Linux x86_64")).toBe(
+      false,
+    );
+  });
+});
+
+describe("advanceTerminalSelectionClickSequence", () => {
+  it("recognizes stationary double and triple pointer presses without PointerEvent.detail", () => {
+    const first = advanceTerminalSelectionClickSequence(null, {
+      clientX: 20,
+      clientY: 30,
+      timeStamp: 1_000,
+    });
+    const second = advanceTerminalSelectionClickSequence(first, {
+      clientX: 22,
+      clientY: 29,
+      timeStamp: 1_200,
+    });
+    const third = advanceTerminalSelectionClickSequence(second, {
+      clientX: 21,
+      clientY: 31,
+      timeStamp: 1_400,
+    });
+
+    expect([first.count, second.count, third.count]).toEqual([1, 2, 3]);
+  });
+
+  it("starts over after movement, delay, or a completed triple click", () => {
+    const previous = { count: 3, time: 1_000, x: 20, y: 30 };
+    expect(
+      advanceTerminalSelectionClickSequence(previous, {
+        clientX: 20,
+        clientY: 30,
+        timeStamp: 1_100,
+      }).count,
+    ).toBe(1);
+    expect(
+      advanceTerminalSelectionClickSequence(previous, {
+        clientX: 30,
+        clientY: 30,
+        timeStamp: 1_100,
+      }).count,
+    ).toBe(1);
+    expect(
+      advanceTerminalSelectionClickSequence(previous, {
+        clientX: 20,
+        clientY: 30,
+        timeStamp: 1_501,
+      }).count,
+    ).toBe(1);
+  });
+});
+
+describe("terminal scrollbar", () => {
+  it("maps Ghostty's viewport state to a proportional thumb", () => {
+    expect(terminalScrollbarGeometry({ total: 100, offset: 40, len: 20 }, 200)).toEqual({
+      thumbHeight: 40,
+      thumbTop: 80,
+      maxOffset: 80,
+    });
+    expect(terminalScrollbarGeometry({ total: 100, offset: 0, len: 100 }, 200)).toBeNull();
+  });
+
+  it("keeps the thumb usable for large scrollback and maps dragging back to rows", () => {
+    const state = { total: 10_000, offset: 0, len: 20 };
+    expect(terminalScrollbarGeometry(state, 200)).toEqual({
+      thumbHeight: 18,
+      thumbTop: 0,
+      maxOffset: 9_980,
+    });
+    expect(terminalScrollbarOffsetAtPointer(state, 200, 191, 9)).toBe(9_980);
+  });
+});
diff --git a/apps/web/src/terminal/ghostty/surface.ts b/apps/web/src/terminal/ghostty/surface.ts
new file mode 100644
index 00000000000..86c1ad5329c
--- /dev/null
+++ b/apps/web/src/terminal/ghostty/surface.ts
@@ -0,0 +1,1393 @@
+import { isMacPlatform } from "../../lib/utils";
+import { collectWrappedTerminalLinkLine, extractTerminalLinks } from "../../terminal-links";
+import {
+  GhosttyTerminalCore,
+  type GhosttyScrollbar,
+  type GhosttySnapshot,
+  type GhosttyTheme,
+} from "./core";
+import {
+  measureGhosttyCell,
+  renderGhosttySnapshot,
+  terminalGridSize,
+  type GhosttyCellMetrics,
+} from "./renderer";
+import symbolsFontUrl from "./fonts/SymbolsNerdFontMono-Regular.woff2?url";
+
+export const DEFAULT_TERMINAL_FONT_SIZE = 12;
+const MIN_TERMINAL_FONT_SIZE = 6;
+const MAX_TERMINAL_FONT_SIZE = 32;
+// The glyph fallbacks only supply symbols the text faces are missing (powerline
+// separators, devicons, and other private-use prompt symbols), so shells
+// configured for a locally installed Nerd Font keep their prompt glyphs no
+// matter which text face is active.
+const TERMINAL_GLYPH_FALLBACKS =
+  '"Symbols Nerd Font Mono", "Symbols Nerd Font", "JetBrainsMono Nerd Font", ' +
+  '"JetBrainsMono NF", "FiraCode Nerd Font", "Hack Nerd Font", "MesloLGS NF", ' +
+  '"CaskaydiaCove Nerd Font", "PowerlineSymbols", monospace';
+// SF Mono where the platform has it (macOS), otherwise the bundled JetBrains
+// Mono webfont, so the default rendering is identical everywhere else.
+export const DEFAULT_TERMINAL_FONT_FAMILY =
+  '"SF Mono", "SFMono-Regular", "JetBrains Mono", ' + TERMINAL_GLYPH_FALLBACKS;
+const CONTENT_PADDING = 4;
+const MIN_SCROLLBAR_THUMB_HEIGHT = 18;
+
+/** Requested terminal font; omitted fields fall back to the defaults. */
+export interface GhosttyTerminalFont {
+  readonly family?: string;
+  readonly size?: number;
+}
+
+let symbolsFontLoad: Promise<void> | null = null;
+
+/**
+ * Register the bundled symbols-only Nerd Font once per page. It loads lazily
+ * with the first terminal, and because it carries no regular text glyphs it
+ * composes with any text face without changing metrics — prompt symbols and
+ * devicons render even on machines without a locally installed Nerd Font.
+ */
+function ensureTerminalSymbolsFont(): Promise<void> {
+  if (symbolsFontLoad !== null) return symbolsFontLoad;
+  symbolsFontLoad = (async () => {
+    try {
+      const face = new FontFace("Symbols Nerd Font Mono", `url(${symbolsFontUrl})`);
+      document.fonts.add(await face.load());
+    } catch {
+      // Locally installed fallback faces still apply.
+    }
+  })();
+  return symbolsFontLoad;
+}
+
+export function terminalFontFamily(family?: string): string {
+  const custom = family?.trim();
+  if (!custom) return DEFAULT_TERMINAL_FONT_FAMILY;
+  // A custom face keeps the glyph fallbacks so prompt symbols stay covered.
+  return `${custom}, ${TERMINAL_GLYPH_FALLBACKS}`;
+}
+
+export function terminalFontSize(size?: number): number {
+  if (size === undefined || !Number.isFinite(size)) return DEFAULT_TERMINAL_FONT_SIZE;
+  return Math.max(MIN_TERMINAL_FONT_SIZE, Math.min(MAX_TERMINAL_FONT_SIZE, Math.round(size)));
+}
+
+/**
+ * Vertical origin of the grid inside the mount. While content is shorter than
+ * the viewport the grid sits at the top like a fresh terminal. Once scrollback
+ * exists the prompt lives on the bottom row, so the grid anchors to the bottom
+ * edge instead: the sub-row remainder moves above row 0 and resizing within a
+ * row boundary keeps the prompt pinned instead of snapping up and down.
+ */
+export function terminalContentOriginY(
+  mountHeight: number,
+  padding: number,
+  rows: number,
+  cellHeight: number,
+  anchorBottom: boolean,
+): number {
+  if (!anchorBottom) return padding;
+  const slack = mountHeight - padding * 2 - rows * cellHeight;
+  return padding + Math.max(0, slack);
+}
+
+export interface TerminalScrollbarGeometry {
+  readonly thumbHeight: number;
+  readonly thumbTop: number;
+  readonly maxOffset: number;
+}
+
+export function terminalScrollbarGeometry(
+  state: GhosttyScrollbar,
+  trackHeight: number,
+): TerminalScrollbarGeometry | null {
+  const total = Math.max(0, state.total);
+  const len = Math.max(0, Math.min(state.len, total));
+  const maxOffset = Math.max(0, total - len);
+  if (trackHeight <= 0 || len <= 0 || maxOffset === 0) return null;
+  const thumbHeight = Math.min(
+    trackHeight,
+    Math.max(MIN_SCROLLBAR_THUMB_HEIGHT, (trackHeight * len) / total),
+  );
+  const travel = Math.max(0, trackHeight - thumbHeight);
+  const offset = Math.max(0, Math.min(state.offset, maxOffset));
+  return {
+    thumbHeight,
+    thumbTop: travel * (offset / maxOffset),
+    maxOffset,
+  };
+}
+
+export function terminalScrollbarOffsetAtPointer(
+  state: GhosttyScrollbar,
+  trackHeight: number,
+  pointerY: number,
+  pointerOffset: number,
+): number {
+  const geometry = terminalScrollbarGeometry(state, trackHeight);
+  if (geometry === null) return 0;
+  const travel = Math.max(0, trackHeight - geometry.thumbHeight);
+  if (travel === 0) return 0;
+  const thumbTop = Math.max(0, Math.min(pointerY - pointerOffset, travel));
+  return Math.round((thumbTop / travel) * geometry.maxOffset);
+}
+
+function terminalRowText(row: GhosttySnapshot["rowData"][number], trimRight: boolean): string {
+  const text = row.cells.map((cell) => cell.text || " ").join("");
+  return trimRight ? text.trimEnd() : text;
+}
+
+function terminalColumnOffset(row: GhosttySnapshot["rowData"][number], column: number): number {
+  let offset = 0;
+  for (let cellIndex = 0; cellIndex < column; cellIndex += 1) {
+    offset += row.cells[cellIndex]?.text.length || 1;
+  }
+  return offset;
+}
+
+export function terminalLinkAtPosition(
+  rows: GhosttySnapshot["rowData"],
+  rowIndex: number,
+  column: number,
+): string | null {
+  const wrappedLine = collectWrappedTerminalLinkLine(rowIndex + 1, (index) => {
+    const row = rows[index];
+    if (!row) return null;
+    return {
+      isWrapped: row.isWrapContinuation,
+      translateToString: (trimRight = false) => terminalRowText(row, trimRight),
+    };
+  });
+  if (!wrappedLine) return null;
+  // Only viewport rows are available: a wrapped line whose head scrolled above
+  // the viewport would resolve a truncated match into a wrong link.
+  const firstSegment = wrappedLine.segments[0];
+  if (firstSegment && rows[firstSegment.bufferLineNumber - 1]?.isWrapContinuation) {
+    return null;
+  }
+  const segment = wrappedLine.segments.find((value) => value.bufferLineNumber === rowIndex + 1);
+  const row = rows[rowIndex];
+  if (!segment || !row) return null;
+  const lastSegment = wrappedLine.segments.at(-1);
+  const lastRow = lastSegment ? rows[lastSegment.bufferLineNumber - 1] : undefined;
+  // Ghostty's soft-wrap flag is authoritative: when the last collected row
+  // still wraps onward, its continuation is outside the viewport.
+  const continuesBelowViewport = lastRow !== undefined && lastRow.wrapsToNext;
+  const offset = segment.startIndex + terminalColumnOffset(row, column);
+  for (const match of extractTerminalLinks(wrappedLine.text)) {
+    if (offset >= match.start && offset < match.end) {
+      // A truncated tail must not activate as a complete link.
+      if (match.end === wrappedLine.text.length && continuesBelowViewport) return null;
+      return match.text;
+    }
+  }
+  return null;
+}
+
+export function terminalLinkAtColumn(row: GhosttySnapshot["rowData"][number], column: number) {
+  return terminalLinkAtPosition([row], 0, column);
+}
+
+export function isTerminalCopyShortcut(
+  event: Pick<KeyboardEvent, "ctrlKey" | "key" | "metaKey" | "shiftKey">,
+  platform = navigator.platform,
+) {
+  if (event.key.toLowerCase() !== "c") return false;
+  return isMacPlatform(platform) ? event.metaKey : event.ctrlKey && event.shiftKey;
+}
+
+export function isTerminalPasteShortcut(
+  event: Pick<KeyboardEvent, "ctrlKey" | "key" | "metaKey" | "shiftKey">,
+  platform = navigator.platform,
+) {
+  if (event.key.toLowerCase() !== "v") return false;
+  return isMacPlatform(platform) ? event.metaKey : event.ctrlKey && event.shiftKey;
+}
+
+export function isTerminalCompositionCommitInput(event: Pick<InputEvent, "inputType">): boolean {
+  return (
+    event.inputType === "" ||
+    event.inputType === "insertCompositionText" ||
+    event.inputType === "insertFromComposition"
+  );
+}
+
+export function isTerminalAltGraphText(
+  event: Pick<KeyboardEvent, "getModifierState" | "key">,
+): boolean {
+  return event.getModifierState("AltGraph") && [...event.key].length === 1;
+}
+
+export function shouldReportTerminalMouse(
+  tracking: boolean,
+  event: Pick<MouseEvent, "ctrlKey" | "metaKey" | "shiftKey">,
+): boolean {
+  return tracking && !event.shiftKey && !event.ctrlKey && !event.metaKey;
+}
+
+export function terminalWheelDeltaRows(
+  event: Pick<WheelEvent, "deltaY" | "deltaMode">,
+  cellHeight: number,
+  viewportRows: number,
+  remainder: number,
+): { readonly rows: number; readonly remainder: number } {
+  // deltaMode: 0 pixels, 1 lines, 2 pages.
+  const pixels =
+    event.deltaMode === 1
+      ? event.deltaY * cellHeight
+      : event.deltaMode === 2
+        ? event.deltaY * viewportRows * cellHeight
+        : event.deltaY;
+  const total = remainder + pixels / cellHeight;
+  const rows = Math.trunc(total);
+  return { rows, remainder: total - rows };
+}
+
+export function terminalWheelArrowData(rows: number, applicationCursorKeys: boolean): string {
+  if (rows === 0) return "";
+  const sequence =
+    rows < 0
+      ? applicationCursorKeys
+        ? "\u001bOA"
+        : "\u001b[A"
+      : applicationCursorKeys
+        ? "\u001bOB"
+        : "\u001b[B";
+  return sequence.repeat(Math.abs(rows));
+}
+
+export function isTerminalLinkPointerGesture(
+  event: Pick<MouseEvent, "ctrlKey" | "metaKey">,
+  platform = navigator.platform,
+): boolean {
+  return isMacPlatform(platform)
+    ? event.metaKey && !event.ctrlKey
+    : event.ctrlKey && !event.metaKey;
+}
+
+export function ghosttyMouseButton(button: number): number | null {
+  switch (button) {
+    case 0:
+      return 1;
+    case 1:
+      return 3;
+    case 2:
+      return 2;
+    case 3:
+      return 4;
+    case 4:
+      return 5;
+    default:
+      return null;
+  }
+}
+
+export interface TerminalSelectionClickSequence {
+  readonly count: number;
+  readonly time: number;
+  readonly x: number;
+  readonly y: number;
+}
+
+export function advanceTerminalSelectionClickSequence(
+  previous: TerminalSelectionClickSequence | null,
+  event: Pick<PointerEvent, "clientX" | "clientY" | "timeStamp">,
+): TerminalSelectionClickSequence {
+  const repeats =
+    previous !== null &&
+    event.timeStamp - previous.time <= 500 &&
+    Math.hypot(event.clientX - previous.x, event.clientY - previous.y) <= 4;
+  return {
+    count: repeats ? (previous.count >= 3 ? 1 : previous.count + 1) : 1,
+    time: event.timeStamp,
+    x: event.clientX,
+    y: event.clientY,
+  };
+}
+
+export interface GhosttySelectionPosition {
+  readonly start: { readonly x: number; readonly y: number };
+  readonly end: { readonly x: number; readonly y: number };
+}
+
+export interface GhosttyTerminalSurfaceOptions {
+  readonly theme: GhosttyTheme;
+  readonly font?: GhosttyTerminalFont;
+  readonly onData: (data: string) => void;
+  readonly onResize: (cols: number, rows: number) => void;
+  readonly onSelectionChange: () => void;
+  readonly onCopy: (text: string) => void;
+  readonly beforeKey: (event: KeyboardEvent) => boolean;
+  readonly onLinkActivate: (text: string, event: MouseEvent) => void;
+}
+
+export class GhosttyTerminalSurface {
+  readonly canvas: HTMLCanvasElement;
+  readonly input: HTMLTextAreaElement;
+  readonly scrollbar: HTMLDivElement;
+  cols = 1;
+  rows = 1;
+
+  private readonly mount: HTMLElement;
+  private readonly context: CanvasRenderingContext2D;
+  private readonly core: GhosttyTerminalCore;
+  private readonly options: GhosttyTerminalSurfaceOptions;
+  private metrics: GhosttyCellMetrics;
+  private fontFamily: string;
+  private fontSize: number;
+  private fontEpoch = 0;
+  private readonly resizeObserver: ResizeObserver;
+  private readonly scrollbarThumb: HTMLDivElement;
+  private snapshot: GhosttySnapshot | null = null;
+  private frame = 0;
+  private cursorTimer: number | null = null;
+  private compositionInputToSuppress: string | null = null;
+  private compositionSuppressionTimer: number | null = null;
+  private cursorOn = true;
+  private renderedCursorY: number | null = null;
+  private forceFullRender = true;
+  private scrollbarDirty = true;
+  private scrollbarState: GhosttyScrollbar | null = null;
+  private scrollbarPointerId: number | null = null;
+  private scrollbarPointerOffset = 0;
+  private disposed = false;
+  private resizeNotifyTimer: number | null = null;
+  private originY = CONTENT_PADDING;
+  private mountHeight = 0;
+  private selectionEnd: { x: number; y: number } | null = null;
+  private selectionAnchorScreen: { x: number; y: number } | null = null;
+  private selectionEndScreen: { x: number; y: number } | null = null;
+  private selectionMode: "cell" | "word" | "line" = "cell";
+  // Word/line selection base in screen coordinates so streaming output cannot
+  // shift the origin of a drag selection.
+  private selectionBase: {
+    start: { x: number; y: number };
+    end: { x: number; y: number };
+  } | null = null;
+  private selectionScrollTimer: number | null = null;
+  private selectionScrollDelta = 0;
+  private selectionPointer: { x: number; y: number } | null = null;
+  private mouseReportingPointerId: number | null = null;
+  private mouseReportingButton: number | null = null;
+  private linkActivationPointerId: number | null = null;
+  private selectionClickSequence: TerminalSelectionClickSequence | null = null;
+  private selectionMoved = false;
+  private composing = false;
+  private focused = false;
+  private resizeNotified = false;
+  private canvasConfigured = false;
+  private theme: GhosttyTheme;
+  private readonly suppressedKeyCodes = new Set<string>();
+  private pasteShortcutToken = 0;
+  private wheelRemainder = 0;
+  private dprMedia: MediaQueryList | null = null;
+  private inputLeft = -1;
+  private inputTop = -1;
+
+  private constructor(
+    mount: HTMLElement,
+    canvas: HTMLCanvasElement,
+    input: HTMLTextAreaElement,
+    scrollbar: HTMLDivElement,
+    scrollbarThumb: HTMLDivElement,
+    context: CanvasRenderingContext2D,
+    core: GhosttyTerminalCore,
+    metrics: GhosttyCellMetrics,
+    options: GhosttyTerminalSurfaceOptions,
+  ) {
+    this.mount = mount;
+    this.canvas = canvas;
+    this.input = input;
+    this.scrollbar = scrollbar;
+    this.scrollbarThumb = scrollbarThumb;
+    this.context = context;
+    this.core = core;
+    this.metrics = metrics;
+    this.options = options;
+    this.theme = options.theme;
+    this.fontFamily = terminalFontFamily(options.font?.family);
+    this.fontSize = terminalFontSize(options.font?.size);
+    this.resizeObserver = new ResizeObserver(() => this.fit());
+    this.installEvents();
+    this.watchDevicePixelRatio();
+    document.fonts.addEventListener("loadingdone", this.onFontsLoaded);
+    this.resizeObserver.observe(mount);
+  }
+
+  static async create(
+    mount: HTMLElement,
+    options: GhosttyTerminalSurfaceOptions,
+  ): Promise<GhosttyTerminalSurface> {
+    const canvas = document.createElement("canvas");
+    canvas.className = "t3-ghostty-canvas";
+    canvas.style.cssText = "display:block;width:100%;height:100%;";
+    canvas.setAttribute("aria-hidden", "true");
+
+    const input = document.createElement("textarea");
+    input.className = "t3-ghostty-input";
+    input.setAttribute("aria-label", "Terminal input");
+    input.autocapitalize = "off";
+    input.autocomplete = "off";
+    input.spellcheck = false;
+    input.style.cssText =
+      "position:absolute;left:4px;top:4px;width:1px;height:1px;opacity:0;padding:0;border:0;resize:none;pointer-events:none;";
+
+    const scrollbar = document.createElement("div");
+    scrollbar.className = "t3-ghostty-scrollbar";
+    scrollbar.setAttribute("role", "scrollbar");
+    scrollbar.setAttribute("aria-label", "Terminal scrollback");
+    scrollbar.setAttribute("aria-orientation", "vertical");
+    scrollbar.tabIndex = 0;
+    scrollbar.hidden = true;
+    const scrollbarThumb = document.createElement("div");
+    scrollbarThumb.className = "t3-ghostty-scrollbar-thumb";
+    scrollbar.append(scrollbarThumb);
+    mount.replaceChildren(canvas, input, scrollbar);
+
+    const context = canvas.getContext("2d", { alpha: false });
+    if (!context) throw new Error("Canvas 2D is unavailable");
+    const fontFamily = terminalFontFamily(options.font?.family);
+    const fontSize = terminalFontSize(options.font?.size);
+    try {
+      // Cell metrics must come from the faces that will render; measuring before
+      // the bundled webfonts load would size the grid from a fallback font.
+      await ensureTerminalSymbolsFont();
+      await document.fonts.load(`${fontSize}px ${fontFamily}`);
+    } catch {
+      // Metrics fall back to whichever faces are already available.
+    }
+    const metrics = measureGhosttyCell(context, fontSize, fontFamily);
+    const grid = terminalGridSize(mount.clientWidth, mount.clientHeight, metrics, CONTENT_PADDING);
+    const core = await GhosttyTerminalCore.create(
+      grid.cols,
+      grid.rows,
+      metrics.width,
+      metrics.height,
+      options.theme,
+      options.onData,
+    );
+    const surface = new GhosttyTerminalSurface(
+      mount,
+      canvas,
+      input,
+      scrollbar,
+      scrollbarThumb,
+      context,
+      core,
+      metrics,
+      options,
+    );
+    surface.fit();
+    surface.requestRender();
+    return surface;
+  }
+
+  write(data: string): void {
+    if (this.disposed) return;
+    this.core.write(data);
+    // Restart the blink cycle from the visible phase so the cursor never sits
+    // invisible through a stream of output or a burst of typing echo.
+    this.cursorOn = true;
+    this.scrollbarDirty = true;
+    this.requestRender();
+  }
+
+  resetAndWrite(data: string): void {
+    if (this.disposed) return;
+    this.core.resetAndWrite(data);
+    this.forceFullRender = true;
+    this.scrollbarDirty = true;
+    this.requestRender();
+  }
+
+  setTheme(theme: GhosttyTheme): void {
+    if (this.disposed) return;
+    this.theme = theme;
+    this.core.setTheme(theme);
+    this.forceFullRender = true;
+    this.requestRender();
+  }
+
+  async setFont(font: GhosttyTerminalFont): Promise<void> {
+    if (this.disposed) return;
+    const fontFamily = terminalFontFamily(font.family);
+    const fontSize = terminalFontSize(font.size);
+    // The fields only change together with their metrics after the load, and
+    // the epoch lets the newest overlapping call win regardless of load order.
+    const epoch = ++this.fontEpoch;
+    try {
+      await document.fonts.load(`${fontSize}px ${fontFamily}`);
+    } catch {
+      // Metrics fall back to whichever faces are already available.
+    }
+    if (this.disposed || epoch !== this.fontEpoch) return;
+    this.fontFamily = fontFamily;
+    this.fontSize = fontSize;
+    this.applyFontMetrics();
+  }
+
+  private applyFontMetrics(): void {
+    this.metrics = measureGhosttyCell(this.context, this.fontSize, this.fontFamily);
+    this.core.resize(this.cols, this.rows, this.metrics.width, this.metrics.height);
+    // Cached IME textarea coordinates are stale in the new cell geometry.
+    this.inputLeft = -1;
+    this.inputTop = -1;
+    this.forceFullRender = true;
+    this.scrollbarDirty = true;
+    this.fit();
+    this.requestRender();
+  }
+
+  private readonly onFontsLoaded = () => {
+    if (this.disposed) return;
+    // A face that finished loading after the initial measurement changes glyph
+    // advances; re-measure and refit so the grid matches what actually renders.
+    const metrics = measureGhosttyCell(this.context, this.fontSize, this.fontFamily);
+    if (
+      metrics.width === this.metrics.width &&
+      metrics.height === this.metrics.height &&
+      metrics.baseline === this.metrics.baseline
+    ) {
+      return;
+    }
+    this.applyFontMetrics();
+  };
+
+  fit(): boolean {
+    if (this.disposed) return false;
+    const width = this.mount.clientWidth;
+    const height = this.mount.clientHeight;
+    if (width <= 0 || height <= 0) return false;
+    const ratio = window.devicePixelRatio || 1;
+    const pixelWidth = Math.max(1, Math.round(width * ratio));
+    const pixelHeight = Math.max(1, Math.round(height * ratio));
+    let shouldRender = false;
+    // The DPR transform must be installed even when the target size happens to
+    // equal the canvas default 300x150 backing store, so the first fit always
+    // schedules a canvas configuration.
+    if (
+      this.canvas.width !== pixelWidth ||
+      this.canvas.height !== pixelHeight ||
+      !this.canvasConfigured
+    ) {
+      this.canvas.width = pixelWidth;
+      this.canvas.height = pixelHeight;
+      this.context.setTransform(ratio, 0, 0, ratio, 0, 0);
+      this.canvasConfigured = true;
+      this.forceFullRender = true;
+      this.scrollbarDirty = true;
+      shouldRender = true;
+    }
+    const grid = terminalGridSize(width, height, this.metrics, CONTENT_PADDING);
+    this.mountHeight = height;
+    // onResize is the only PTY resize channel, so the first successful fit must
+    // notify even when the measured grid equals the 1x1 construction sentinel.
+    if (grid.cols !== this.cols || grid.rows !== this.rows || !this.resizeNotified) {
+      this.cols = grid.cols;
+      this.rows = grid.rows;
+      this.core.resize(grid.cols, grid.rows, this.metrics.width, this.metrics.height);
+      this.notifyResize();
+      this.forceFullRender = true;
+      this.scrollbarDirty = true;
+      shouldRender = true;
+    }
+    // Rendering synchronously keeps the repaint inside the same frame as the
+    // layout change: ResizeObserver fires before paint, so the browser never
+    // composites the old backing store stretched into the new element box.
+    if (shouldRender) this.renderFrame();
+    return true;
+  }
+
+  /**
+   * The local grid reflows immediately, but the PTY only hears about settled
+   * dimensions: notifying on every drag step makes the shell reprint its
+   * prompt mid-drag, which reads as jitter.
+   */
+  private notifyResize(): void {
+    this.resizeNotified = true;
+    if (this.resizeNotifyTimer !== null) window.clearTimeout(this.resizeNotifyTimer);
+    this.resizeNotifyTimer = window.setTimeout(() => {
+      this.resizeNotifyTimer = null;
+      if (!this.disposed) this.options.onResize(this.cols, this.rows);
+    }, 150);
+  }
+
+  focus(): void {
+    this.input.focus({ preventScroll: true });
+  }
+
+  hasSelection(): boolean {
+    return this.core.selectionText().length > 0;
+  }
+
+  getSelection(): string {
+    return this.core.selectionText();
+  }
+
+  getSelectionPosition(): GhosttySelectionPosition | null {
+    if (!this.selectionAnchorScreen || !this.selectionEndScreen || !this.hasSelection())
+      return null;
+    const before =
+      this.selectionAnchorScreen.y < this.selectionEndScreen.y ||
+      (this.selectionAnchorScreen.y === this.selectionEndScreen.y &&
+        this.selectionAnchorScreen.x <= this.selectionEndScreen.x);
+    return before
+      ? { start: this.selectionAnchorScreen, end: this.selectionEndScreen }
+      : { start: this.selectionEndScreen, end: this.selectionAnchorScreen };
+  }
+
+  getSelectionEndClientRect(): { readonly right: number; readonly bottom: number } | null {
+    const position = this.getSelectionPosition();
+    if (!position) return null;
+    const viewportEnd = this.core.screenPointToViewport(position.end.x, position.end.y);
+    if (!viewportEnd) return null;
+    const bounds = this.canvas.getBoundingClientRect();
+    return {
+      right: bounds.left + CONTENT_PADDING + (viewportEnd.x + 1) * this.metrics.width,
+      bottom: bounds.top + this.originY + (viewportEnd.y + 1) * this.metrics.height,
+    };
+  }
+
+  clearSelection(): void {
+    this.core.clearSelection();
+    this.selectionEnd = null;
+    this.selectionAnchorScreen = null;
+    this.selectionEndScreen = null;
+    this.selectionMode = "cell";
+    this.selectionBase = null;
+    this.setSelectionAutoscroll(0);
+    this.options.onSelectionChange();
+    // Selection highlights span rows Ghostty may not mark dirty for this change.
+    this.forceFullRender = true;
+    this.requestRender();
+  }
+
+  scrollToBottom(): void {
+    this.core.scrollToBottom();
+    this.forceFullRender = true;
+    this.scrollbarDirty = true;
+    this.requestRender();
+  }
+
+  isAtBottom(): boolean {
+    return this.core.isViewportActive();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.resizeObserver.disconnect();
+    document.fonts.removeEventListener("loadingdone", this.onFontsLoaded);
+    this.dprMedia?.removeEventListener("change", this.onDevicePixelRatioChange);
+    this.dprMedia = null;
+    if (this.selectionScrollTimer !== null) window.clearInterval(this.selectionScrollTimer);
+    if (this.resizeNotifyTimer !== null) {
+      window.clearTimeout(this.resizeNotifyTimer);
+      this.resizeNotifyTimer = null;
+      // Flush the settled dimensions so the PTY keeps the final size even when
+      // the surface unmounts inside the debounce window.
+      this.options.onResize(this.cols, this.rows);
+    }
+    if (this.frame !== 0) window.cancelAnimationFrame(this.frame);
+    if (this.cursorTimer !== null) window.clearTimeout(this.cursorTimer);
+    if (this.compositionSuppressionTimer !== null) {
+      window.clearTimeout(this.compositionSuppressionTimer);
+    }
+    this.removeEvents();
+    this.core.dispose();
+    if (
+      this.canvas.parentElement === this.mount ||
+      this.input.parentElement === this.mount ||
+      this.scrollbar.parentElement === this.mount
+    ) {
+      this.canvas.remove();
+      this.input.remove();
+      this.scrollbar.remove();
+    }
+  }
+
+  private readonly onKeyDown = (event: KeyboardEvent) => {
+    // Presses handled outside the terminal must also swallow their release:
+    // beforeKey runs side effects (keybindings, navigation sends), so it cannot
+    // be consulted again on keyup, and Kitty report-event-types sessions would
+    // otherwise receive a release for a press the shell never saw.
+    if (isTerminalAltGraphText(event) || !this.options.beforeKey(event)) {
+      this.suppressedKeyCodes.add(event.code);
+      return;
+    }
+    if (isTerminalCopyShortcut(event) && this.hasSelection()) {
+      event.preventDefault();
+      this.suppressedKeyCodes.add(event.code);
+      this.options.onCopy(this.getSelection());
+      return;
+    }
+    if (isTerminalPasteShortcut(event)) {
+      this.suppressedKeyCodes.add(event.code);
+      const clipboard = navigator.clipboard;
+      if (typeof clipboard?.readText === "function") {
+        // Race the async clipboard read against the browser's own paste event:
+        // the native event (dispatched synchronously with the default action)
+        // always claims the token first when it fires, and the read covers
+        // browsers whose paste shortcut produces no paste event. Not preventing
+        // the default keeps the native path alive when the read is denied.
+        const token = ++this.pasteShortcutToken;
+        void clipboard.readText().then(
+          (text) => {
+            if (this.disposed || this.pasteShortcutToken !== token) return;
+            this.pasteShortcutToken += 1;
+            if (text.length > 0) this.options.onData(this.core.encodePaste(text));
+          },
+          () => {
+            // Clipboard read denied; the native paste event remains the path.
+          },
+        );
+      }
+      return;
+    }
+    // keyCode 229 is Safari's only signal that this keydown opens an IME
+    // composition; encoding it would double the committed text.
+    if (event.isComposing || this.composing || event.key === "Process" || event.keyCode === 229) {
+      return;
+    }
+    const data = this.core.encodeKey(event);
+    if (data.length === 0) return;
+    this.suppressedKeyCodes.delete(event.code);
+    event.preventDefault();
+    event.stopPropagation();
+    this.options.onData(data);
+  };
+
+  private readonly onKeyUp = (event: KeyboardEvent) => {
+    if (this.suppressedKeyCodes.delete(event.code)) return;
+    if (event.isComposing || this.composing || event.key === "Process" || event.keyCode === 229) {
+      return;
+    }
+    // Ghostty's encoder only emits release codes when the terminal enabled the
+    // Kitty report-event-types flag, so legacy sessions send nothing here.
+    const data = this.core.encodeKey(event, "release");
+    if (data.length === 0) return;
+    event.preventDefault();
+    event.stopPropagation();
+    this.options.onData(data);
+  };
+
+  private readonly onFocus = () => {
+    this.focused = true;
+    this.cursorOn = true;
+    this.requestRender();
+  };
+
+  private readonly onBlur = () => {
+    this.focused = false;
+    // Suppressions survive blur deliberately: a shortcut that moves focus (for
+    // example terminal-toggle) must still swallow its own keyup if focus comes
+    // back before release. Stale entries are harmless — an encoding keydown
+    // always removes its code first.
+    // The steady unfocused hollow cursor must not inherit an off blink phase.
+    this.cursorOn = true;
+    this.requestRender();
+  };
+
+  private readonly onDevicePixelRatioChange = () => {
+    this.watchDevicePixelRatio();
+    this.fit();
+  };
+
+  private watchDevicePixelRatio(): void {
+    this.dprMedia?.removeEventListener("change", this.onDevicePixelRatioChange);
+    // A resolution media query only fires once for the ratio it was created at,
+    // so re-arm it after every change (monitor moves, browser zoom).
+    this.dprMedia = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+    this.dprMedia.addEventListener("change", this.onDevicePixelRatioChange);
+  }
+
+  private readonly onPaste = (event: ClipboardEvent) => {
+    // Always suppress the browser's default insertion: content the textarea
+    // would receive (for example an html-only clipboard converted to text)
+    // leaks through onInput without bracketed-paste encoding.
+    event.preventDefault();
+    const data = event.clipboardData?.getData("text/plain") ?? "";
+    if (data.length === 0) return;
+    // The native paste won the race with actual text; a pending clipboard read
+    // must not double. An empty native paste leaves the read as the only path.
+    this.pasteShortcutToken += 1;
+    this.options.onData(this.core.encodePaste(data));
+  };
+
+  private readonly onCompositionStart = () => {
+    this.clearCompositionInputSuppression();
+    this.composing = true;
+  };
+
+  private readonly onCompositionEnd = (event: CompositionEvent) => {
+    this.composing = false;
+    const data = this.input.value || event.data;
+    if (data.length > 0) this.options.onData(data);
+    this.input.value = "";
+    this.compositionInputToSuppress = data;
+    this.compositionSuppressionTimer = window.setTimeout(() => {
+      this.compositionInputToSuppress = null;
+      this.compositionSuppressionTimer = null;
+    }, 100);
+  };
+
+  private readonly onInput = (event: Event) => {
+    const inputEvent = event as InputEvent;
+    if (this.composing || inputEvent.isComposing) return;
+    const data = this.input.value || inputEvent.data || "";
+    if (data === this.compositionInputToSuppress && isTerminalCompositionCommitInput(inputEvent)) {
+      this.clearCompositionInputSuppression();
+      this.input.value = "";
+      return;
+    }
+    this.clearCompositionInputSuppression();
+    if (data.length > 0) this.options.onData(data);
+    this.input.value = "";
+  };
+
+  private clearCompositionInputSuppression(): void {
+    if (this.compositionSuppressionTimer !== null) {
+      window.clearTimeout(this.compositionSuppressionTimer);
+      this.compositionSuppressionTimer = null;
+    }
+    this.compositionInputToSuppress = null;
+  }
+
+  private readonly onPointerDown = (event: PointerEvent) => {
+    this.focus();
+    if (shouldReportTerminalMouse(this.core.isMouseTracking(), event)) {
+      const button = ghosttyMouseButton(event.button);
+      if (button === null) return;
+      event.preventDefault();
+      event.stopPropagation();
+      this.mouseReportingPointerId = event.pointerId;
+      this.mouseReportingButton = button;
+      this.sendMouse("press", button, event);
+      this.canvas.setPointerCapture(event.pointerId);
+      return;
+    }
+    if (event.button !== 0) return;
+    if (isTerminalLinkPointerGesture(event)) {
+      event.preventDefault();
+      event.stopPropagation();
+      this.linkActivationPointerId = event.pointerId;
+      this.canvas.setPointerCapture(event.pointerId);
+      return;
+    }
+    const cell = this.cellAt(event.clientX, event.clientY);
+    this.selectionMoved = false;
+    this.selectionClickSequence = advanceTerminalSelectionClickSequence(
+      this.selectionClickSequence,
+      event,
+    );
+    const clickCount = this.selectionClickSequence.count;
+    this.selectionMode = clickCount >= 3 ? "line" : clickCount === 2 ? "word" : "cell";
+    const range =
+      this.selectionMode === "line"
+        ? this.core.selectLine(cell.x, cell.y)
+        : this.selectionMode === "word"
+          ? this.core.selectWord(cell.x, cell.y)
+          : null;
+    if (range) {
+      this.selectionBase = range.screen;
+      this.selectionEnd = range.viewport.end;
+      this.selectionAnchorScreen = range.screen.start;
+      this.selectionEndScreen = range.screen.end;
+      this.options.onSelectionChange();
+    } else {
+      this.selectionMode = "cell";
+      this.selectionBase = null;
+      this.selectionEnd = cell;
+      const screen = this.core.viewportPointToScreen(cell.x, cell.y);
+      this.selectionAnchorScreen = screen;
+      this.selectionEndScreen = screen;
+      if (screen) {
+        this.core.setSelection({ ...screen, tag: 2 }, { ...screen, tag: 2 });
+      } else {
+        this.core.setSelection(cell, cell);
+      }
+    }
+    this.forceFullRender = true;
+    this.canvas.setPointerCapture(event.pointerId);
+    this.requestRender();
+  };
+
+  private readonly onPointerMove = (event: PointerEvent) => {
+    if (this.linkActivationPointerId === event.pointerId) return;
+    // Hover motion is only reportable in any-event tracking (DEC 1003); normal and
+    // button-event tracking never report motion without a captured pressed button.
+    if (
+      this.mouseReportingPointerId === event.pointerId ||
+      shouldReportTerminalMouse(this.core.isMouseAnyEventTracking(), event)
+    ) {
+      event.preventDefault();
+      this.canvas.style.cursor = "default";
+      this.sendMouse("motion", this.buttonFromButtons(event.buttons), event);
+      return;
+    }
+    if (!this.selectionAnchorScreen || !this.canvas.hasPointerCapture(event.pointerId)) {
+      this.updateHoverCursor(event);
+      return;
+    }
+    this.selectionPointer = { x: event.clientX, y: event.clientY };
+    const bounds = this.canvas.getBoundingClientRect();
+    this.setSelectionAutoscroll(
+      event.clientY < bounds.top ? -1 : event.clientY > bounds.bottom ? 1 : 0,
+    );
+    const cell = this.cellAt(event.clientX, event.clientY);
+    if (cell.x === this.selectionEnd?.x && cell.y === this.selectionEnd.y) return;
+    this.extendSelectionTo(event.clientX, event.clientY);
+  };
+
+  private extendSelectionTo(clientX: number, clientY: number): void {
+    const anchorScreen = this.selectionAnchorScreen;
+    if (anchorScreen === null) return;
+    const cell = this.cellAt(clientX, clientY);
+    this.selectionMoved = true;
+    this.selectionEnd = cell;
+    const range =
+      this.selectionMode === "line"
+        ? this.core.selectLine(cell.x, cell.y)
+        : this.selectionMode === "word"
+          ? this.core.selectWord(cell.x, cell.y)
+          : null;
+    const cellScreen = this.core.viewportPointToScreen(cell.x, cell.y);
+    if (cellScreen === null) return;
+    const base = this.selectionBase;
+    const beforeBase =
+      base !== null &&
+      (cellScreen.y < base.start.y ||
+        (cellScreen.y === base.start.y && cellScreen.x < base.start.x));
+    const anchor = base === null ? anchorScreen : beforeBase ? base.end : base.start;
+    const end = range === null ? cellScreen : beforeBase ? range.screen.start : range.screen.end;
+    this.selectionAnchorScreen = anchor;
+    this.selectionEndScreen = end;
+    this.core.setSelection({ ...anchor, tag: 2 }, { ...end, tag: 2 });
+    this.options.onSelectionChange();
+    this.forceFullRender = true;
+    this.requestRender();
+  }
+
+  private setSelectionAutoscroll(delta: number): void {
+    this.selectionScrollDelta = delta;
+    if (delta === 0) {
+      if (this.selectionScrollTimer !== null) {
+        window.clearInterval(this.selectionScrollTimer);
+        this.selectionScrollTimer = null;
+      }
+      return;
+    }
+    if (this.selectionScrollTimer !== null) return;
+    // Dragging past the edge scrolls the viewport and keeps extending the
+    // selection into the newly revealed rows, like xterm's drag scroller.
+    this.selectionScrollTimer = window.setInterval(() => {
+      if (this.disposed || this.selectionScrollDelta === 0) return;
+      this.scrollViewport(this.selectionScrollDelta);
+      const pointer = this.selectionPointer;
+      if (pointer) this.extendSelectionTo(pointer.x, pointer.y);
+    }, 80);
+  }
+
+  private updateHoverCursor(event: PointerEvent): void {
+    const overLink =
+      isTerminalLinkPointerGesture(event) && this.linkAt(event.clientX, event.clientY) !== null;
+    const cursor = overLink ? "pointer" : "";
+    if (this.canvas.style.cursor !== cursor) this.canvas.style.cursor = cursor;
+  }
+
+  private readonly onPointerUp = (event: PointerEvent) => {
+    this.setSelectionAutoscroll(0);
+    if (this.linkActivationPointerId === event.pointerId) {
+      event.preventDefault();
+      event.stopPropagation();
+      this.linkActivationPointerId = null;
+      if (this.canvas.hasPointerCapture(event.pointerId)) {
+        this.canvas.releasePointerCapture(event.pointerId);
+      }
+      if (event.type !== "pointercancel") {
+        const link = this.linkAt(event.clientX, event.clientY);
+        if (link) this.options.onLinkActivate(link, event);
+      }
+      return;
+    }
+    if (this.mouseReportingPointerId === event.pointerId) {
+      event.preventDefault();
+      event.stopPropagation();
+      this.sendMouse("release", this.mouseReportingButton, event);
+      this.mouseReportingPointerId = null;
+      this.mouseReportingButton = null;
+      if (this.canvas.hasPointerCapture(event.pointerId)) {
+        this.canvas.releasePointerCapture(event.pointerId);
+      }
+      return;
+    }
+    if (this.canvas.hasPointerCapture(event.pointerId)) {
+      this.canvas.releasePointerCapture(event.pointerId);
+    }
+    if (event.button !== 0) return;
+    if (!this.selectionMoved && this.selectionMode === "cell") {
+      this.clearSelection();
+    }
+    this.options.onSelectionChange();
+  };
+
+  private readonly onWheel = (event: WheelEvent) => {
+    if (event.deltaY === 0) return;
+    event.preventDefault();
+    const delta = terminalWheelDeltaRows(
+      event,
+      this.metrics.height,
+      this.rows,
+      this.wheelRemainder,
+    );
+    this.wheelRemainder = delta.remainder;
+    if (delta.rows === 0) return;
+    const magnitude = Math.abs(delta.rows);
+    if (shouldReportTerminalMouse(this.core.isMouseTracking(), event)) {
+      const button = delta.rows < 0 ? 4 : 5;
+      for (let index = 0; index < magnitude; index += 1) {
+        this.sendMouse("press", button, event);
+      }
+      return;
+    }
+    if (this.core.isAlternateScreen()) {
+      // The alternate screen has no scrollback: translate wheel motion into
+      // arrow keys so full-screen apps like vim and less scroll, matching xterm.
+      this.options.onData(terminalWheelArrowData(delta.rows, this.core.isApplicationCursorKeys()));
+      return;
+    }
+    this.scrollViewport(delta.rows);
+  };
+
+  private readonly onMouseDown = (event: MouseEvent) => {
+    if (event.button === 0) event.preventDefault();
+    this.focus();
+  };
+
+  private readonly onContextMenu = (event: MouseEvent) => {
+    if (shouldReportTerminalMouse(this.core.isMouseTracking(), event)) {
+      event.preventDefault();
+    }
+  };
+
+  private readonly onScrollbarPointerDown = (event: PointerEvent) => {
+    if (event.button !== 0) return;
+    const state = this.readScrollbarState();
+    if (state === null) return;
+    const bounds = this.scrollbar.getBoundingClientRect();
+    const geometry = terminalScrollbarGeometry(state, bounds.height);
+    if (geometry === null) return;
+    event.preventDefault();
+    event.stopPropagation();
+    this.scrollbarPointerId = event.pointerId;
+    this.scrollbarPointerOffset =
+      event.target === this.scrollbarThumb
+        ? event.clientY - bounds.top - geometry.thumbTop
+        : geometry.thumbHeight / 2;
+    this.scrollbar.setPointerCapture(event.pointerId);
+    this.scrollbarToPointer(event.clientY, bounds);
+  };
+
+  private readonly onScrollbarPointerMove = (event: PointerEvent) => {
+    if (event.pointerId !== this.scrollbarPointerId || this.scrollbarState === null) return;
+    event.preventDefault();
+    this.scrollbarToPointer(event.clientY, this.scrollbar.getBoundingClientRect());
+  };
+
+  private readonly onScrollbarPointerUp = (event: PointerEvent) => {
+    if (event.pointerId !== this.scrollbarPointerId) return;
+    event.preventDefault();
+    this.scrollbarPointerId = null;
+    if (this.scrollbar.hasPointerCapture(event.pointerId)) {
+      this.scrollbar.releasePointerCapture(event.pointerId);
+    }
+  };
+
+  private readonly onScrollbarKeyDown = (event: KeyboardEvent) => {
+    const state = this.readScrollbarState();
+    if (state === null) return;
+    let delta = 0;
+    switch (event.key) {
+      case "ArrowUp":
+        delta = -1;
+        break;
+      case "ArrowDown":
+        delta = 1;
+        break;
+      case "PageUp":
+        delta = -Math.max(1, state.len);
+        break;
+      case "PageDown":
+        delta = Math.max(1, state.len);
+        break;
+      case "Home":
+        delta = -state.offset;
+        break;
+      case "End":
+        delta = state.total - state.len - state.offset;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    this.scrollViewport(delta);
+  };
+
+  private installEvents(): void {
+    this.input.addEventListener("keydown", this.onKeyDown);
+    this.input.addEventListener("keyup", this.onKeyUp);
+    this.input.addEventListener("focus", this.onFocus);
+    this.input.addEventListener("blur", this.onBlur);
+    this.input.addEventListener("input", this.onInput);
+    this.input.addEventListener("paste", this.onPaste);
+    this.input.addEventListener("compositionstart", this.onCompositionStart);
+    this.input.addEventListener("compositionend", this.onCompositionEnd);
+    this.canvas.addEventListener("pointerdown", this.onPointerDown);
+    this.canvas.addEventListener("pointermove", this.onPointerMove);
+    this.canvas.addEventListener("pointerup", this.onPointerUp);
+    this.canvas.addEventListener("pointercancel", this.onPointerUp);
+    this.canvas.addEventListener("wheel", this.onWheel, { passive: false });
+    this.canvas.addEventListener("mousedown", this.onMouseDown);
+    this.canvas.addEventListener("contextmenu", this.onContextMenu);
+    this.scrollbar.addEventListener("pointerdown", this.onScrollbarPointerDown);
+    this.scrollbar.addEventListener("pointermove", this.onScrollbarPointerMove);
+    this.scrollbar.addEventListener("pointerup", this.onScrollbarPointerUp);
+    this.scrollbar.addEventListener("pointercancel", this.onScrollbarPointerUp);
+    this.scrollbar.addEventListener("keydown", this.onScrollbarKeyDown);
+  }
+
+  private removeEvents(): void {
+    this.input.removeEventListener("keydown", this.onKeyDown);
+    this.input.removeEventListener("keyup", this.onKeyUp);
+    this.input.removeEventListener("focus", this.onFocus);
+    this.input.removeEventListener("blur", this.onBlur);
+    this.input.removeEventListener("input", this.onInput);
+    this.input.removeEventListener("paste", this.onPaste);
+    this.input.removeEventListener("compositionstart", this.onCompositionStart);
+    this.input.removeEventListener("compositionend", this.onCompositionEnd);
+    this.canvas.removeEventListener("pointerdown", this.onPointerDown);
+    this.canvas.removeEventListener("pointermove", this.onPointerMove);
+    this.canvas.removeEventListener("pointerup", this.onPointerUp);
+    this.canvas.removeEventListener("pointercancel", this.onPointerUp);
+    this.canvas.removeEventListener("wheel", this.onWheel);
+    this.canvas.removeEventListener("mousedown", this.onMouseDown);
+    this.canvas.removeEventListener("contextmenu", this.onContextMenu);
+    this.scrollbar.removeEventListener("pointerdown", this.onScrollbarPointerDown);
+    this.scrollbar.removeEventListener("pointermove", this.onScrollbarPointerMove);
+    this.scrollbar.removeEventListener("pointerup", this.onScrollbarPointerUp);
+    this.scrollbar.removeEventListener("pointercancel", this.onScrollbarPointerUp);
+    this.scrollbar.removeEventListener("keydown", this.onScrollbarKeyDown);
+  }
+
+  private scrollViewport(deltaRows: number): void {
+    let delta = Math.trunc(deltaRows);
+    const state = this.readScrollbarState();
+    if (state !== null) {
+      const maxOffset = Math.max(0, state.total - state.len);
+      const offset = Math.max(0, Math.min(state.offset + delta, maxOffset));
+      delta = offset - state.offset;
+      this.scrollbarState = { ...state, offset };
+    }
+    if (delta === 0) return;
+    this.core.scroll(delta);
+    this.forceFullRender = true;
+    this.scrollbarDirty = true;
+    this.requestRender();
+  }
+
+  private scrollbarToPointer(clientY: number, bounds: DOMRect): void {
+    const state = this.scrollbarState;
+    if (state === null) return;
+    const offset = terminalScrollbarOffsetAtPointer(
+      state,
+      bounds.height,
+      clientY - bounds.top,
+      this.scrollbarPointerOffset,
+    );
+    this.scrollViewport(offset - state.offset);
+  }
+
+  private updateScrollbar(): void {
+    const state = this.readScrollbarState();
+    const geometry =
+      state === null
+        ? null
+        : terminalScrollbarGeometry(
+            state,
+            Math.max(0, this.mount.clientHeight - CONTENT_PADDING * 2),
+          );
+    this.scrollbar.hidden = geometry === null;
+    if (state === null || geometry === null) return;
+    this.scrollbar.setAttribute("aria-valuemin", "0");
+    this.scrollbar.setAttribute("aria-valuemax", String(geometry.maxOffset));
+    this.scrollbar.setAttribute(
+      "aria-valuenow",
+      String(Math.max(0, Math.min(state.offset, geometry.maxOffset))),
+    );
+    this.scrollbarThumb.style.height = `${geometry.thumbHeight}px`;
+    this.scrollbarThumb.style.transform = `translateY(${geometry.thumbTop}px)`;
+  }
+
+  private readScrollbarState(): GhosttyScrollbar | null {
+    const state = this.core.scrollbarState();
+    this.scrollbarState = state;
+    return state;
+  }
+
+  private requestRender(): void {
+    if (this.disposed || this.frame !== 0) return;
+    this.frame = window.requestAnimationFrame(() => {
+      this.frame = 0;
+      this.renderFrame();
+    });
+  }
+
+  private renderFrame(): void {
+    if (this.disposed) return;
+    if (this.frame !== 0) {
+      window.cancelAnimationFrame(this.frame);
+      this.frame = 0;
+    }
+    this.snapshot = this.core.snapshot();
+    if (!this.snapshot.cursorBlinking) this.cursorOn = true;
+    // The origin only moves together with a forced full repaint: partial
+    // dirty-row redraws must never composite rows at a shifted origin over
+    // rows painted at the previous one. Bottom anchoring starts once
+    // scrollback exists, i.e. when the prompt actually lives at the bottom.
+    const scrollState = this.readScrollbarState();
+    const anchorBottom = scrollState !== null && scrollState.total > scrollState.len;
+    const nextOriginY = terminalContentOriginY(
+      this.mountHeight,
+      CONTENT_PADDING,
+      this.rows,
+      this.metrics.height,
+      anchorBottom,
+    );
+    if (nextOriginY !== this.originY) {
+      this.originY = nextOriginY;
+      this.forceFullRender = true;
+    }
+    renderGhosttySnapshot({
+      context: this.context,
+      snapshot: this.snapshot,
+      metrics: this.metrics,
+      fontSize: this.fontSize,
+      fontFamily: this.fontFamily,
+      padding: CONTENT_PADDING,
+      originY: this.originY,
+      forceFull: this.forceFullRender,
+      cursorOn: this.cursorOn,
+      previousCursorY: this.renderedCursorY,
+      focused: this.focused,
+      ...(this.theme.selectionBackground !== undefined
+        ? { selectionBackground: this.theme.selectionBackground }
+        : {}),
+    });
+    this.positionInput();
+    this.renderedCursorY =
+      this.cursorOn && this.snapshot.cursorVisible && this.snapshot.cursorY >= 0
+        ? this.snapshot.cursorY
+        : null;
+    if (this.scrollbarDirty) {
+      this.scrollbarDirty = false;
+      this.updateScrollbar();
+    }
+    this.forceFullRender = false;
+    this.scheduleCursorBlink();
+  }
+
+  private scheduleCursorBlink(): void {
+    if (this.cursorTimer !== null) window.clearTimeout(this.cursorTimer);
+    this.cursorTimer = null;
+    // An unfocused surface shows a steady hollow cursor instead of blinking.
+    if (!this.focused || !this.snapshot?.cursorBlinking || !this.snapshot.cursorVisible) return;
+    this.cursorTimer = window.setTimeout(() => {
+      this.cursorTimer = null;
+      this.cursorOn = !this.cursorOn;
+      this.requestRender();
+    }, 500);
+  }
+
+  private positionInput(): void {
+    const snapshot = this.snapshot;
+    if (!snapshot || !snapshot.cursorVisible || snapshot.cursorX < 0 || snapshot.cursorY < 0) {
+      return;
+    }
+    // The IME candidate window anchors to the textarea, so it must follow the
+    // terminal cursor for composition to appear where the user is typing.
+    const left = CONTENT_PADDING + snapshot.cursorX * this.metrics.width;
+    const top = this.originY + snapshot.cursorY * this.metrics.height;
+    if (left === this.inputLeft && top === this.inputTop) return;
+    this.inputLeft = left;
+    this.inputTop = top;
+    this.input.style.left = `${left}px`;
+    this.input.style.top = `${top}px`;
+    this.input.style.height = `${this.metrics.height}px`;
+  }
+
+  private cellAt(clientX: number, clientY: number): { x: number; y: number } {
+    const bounds = this.canvas.getBoundingClientRect();
+    return {
+      x: Math.max(
+        0,
+        Math.min(
+          this.cols - 1,
+          Math.floor((clientX - bounds.left - CONTENT_PADDING) / this.metrics.width),
+        ),
+      ),
+      y: Math.max(
+        0,
+        Math.min(
+          this.rows - 1,
+          Math.floor((clientY - bounds.top - this.originY) / this.metrics.height),
+        ),
+      ),
+    };
+  }
+
+  private linkAt(clientX: number, clientY: number): string | null {
+    if (!this.snapshot) return null;
+    const cell = this.cellAt(clientX, clientY);
+    const explicitHyperlink = this.core.hyperlinkAt(cell.x, cell.y);
+    if (explicitHyperlink) return explicitHyperlink;
+    return terminalLinkAtPosition(this.snapshot.rowData, cell.y, cell.x);
+  }
+
+  private sendMouse(
+    action: "press" | "release" | "motion",
+    button: number | null,
+    event: MouseEvent,
+  ): void {
+    const bounds = this.canvas.getBoundingClientRect();
+    const data = this.core.encodeMouse({
+      action,
+      button,
+      mods:
+        (event.shiftKey ? 1 : 0) |
+        (event.ctrlKey ? 1 << 1 : 0) |
+        (event.altKey ? 1 << 2 : 0) |
+        (event.metaKey ? 1 << 3 : 0),
+      x: Math.max(0, event.clientX - bounds.left),
+      y: Math.max(0, event.clientY - bounds.top),
+      screenWidth: bounds.width,
+      screenHeight: bounds.height,
+      cellWidth: this.metrics.width,
+      cellHeight: this.metrics.height,
+      paddingLeft: CONTENT_PADDING,
+      paddingRight: CONTENT_PADDING,
+      paddingTop: this.originY,
+      paddingBottom: Math.max(0, bounds.height - this.originY - this.rows * this.metrics.height),
+      anyButtonPressed: event.buttons !== 0,
+    });
+    if (data.length > 0) this.options.onData(data);
+  }
+
+  private buttonFromButtons(buttons: number): number | null {
+    if ((buttons & 1) !== 0) return 1;
+    if ((buttons & 4) !== 0) return 3;
+    if ((buttons & 2) !== 0) return 2;
+    if ((buttons & 8) !== 0) return 4;
+    if ((buttons & 16) !== 0) return 5;
+    return null;
+  }
+}
diff --git a/apps/web/src/terminal/ghostty/vendor/ghostty-vt.wasm b/apps/web/src/terminal/ghostty/vendor/ghostty-vt.wasm
new file mode 100644
index 00000000000..a8e2405adef
Binary files /dev/null and b/apps/web/src/terminal/ghostty/vendor/ghostty-vt.wasm differ
diff --git a/apps/web/src/terminal/ghostty/vendor/ghostty-write-pty.wasm b/apps/web/src/terminal/ghostty/vendor/ghostty-write-pty.wasm
new file mode 100644
index 00000000000..66835717dd8
Binary files /dev/null and b/apps/web/src/terminal/ghostty/vendor/ghostty-write-pty.wasm differ
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index c286803a60a..20a699a19c6 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -128,6 +128,7 @@ const allowedHosts = [".ts.net", ...configuredAllowedHosts];
 
 export default defineConfig(() => {
   return {
+    assetsInclude: ["**/*.wasm"],
     plugins: [
       // Fork-only: lets `src/overrides/**` shadow upstream modules so this
       // fork's UI changes live in files upstream never touches. Must come
diff --git a/assets/prod/app-icon.icon/Assets/text.svg b/assets/prod/app-icon.icon/Assets/text.svg
index b12706fdfc2..0b1825f2ef4 100644
--- a/assets/prod/app-icon.icon/Assets/text.svg
+++ b/assets/prod/app-icon.icon/Assets/text.svg
@@ -1,3 +1,3 @@
-<svg width="77" height="47" viewBox="0 0 77 47" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M14.56 45.5V8.58H1.69082e-06V-3.09944e-06H39.65V8.58H25.09V45.5H14.56ZM57.8454 46.28C54.6821 46.28 51.5404 45.8683 48.4204 45.045C45.3004 44.1783 42.6571 42.965 40.4904 41.405L44.5854 33.345C46.3188 34.6017 48.3338 35.5983 50.6304 36.335C52.9271 37.0717 55.2454 37.44 57.5854 37.44C60.2288 37.44 62.3088 36.92 63.8254 35.88C65.3421 34.84 66.1004 33.41 66.1004 31.59C66.1004 29.8567 65.4288 28.4917 64.0854 27.495C62.7421 26.4983 60.5754 26 57.5854 26H52.7754V19.045L65.4504 4.68L66.6204 8.45H42.7654V-3.09944e-06H74.6154V6.825L62.0054 21.19L56.6754 18.135H59.7304C65.3204 18.135 69.5454 19.3917 72.4054 21.905C75.2654 24.4183 76.6954 27.6467 76.6954 31.59C76.6954 34.1467 76.0238 36.5517 74.6804 38.805C73.3371 41.015 71.2788 42.8133 68.5054 44.2C65.7321 45.5867 62.1788 46.28 57.8454 46.28Z" fill="white"/>
+<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <path d="M33.4509 93V47.56H15.5309V37H64.3309V47.56H46.4109V93H33.4509ZM86.7253 93.96C82.832 93.96 78.9653 93.4533 75.1253 92.44C71.2853 91.3733 68.032 89.88 65.3653 87.96L70.4053 78.04C72.5386 79.5867 75.0186 80.8133 77.8453 81.72C80.672 82.6267 83.5253 83.08 86.4053 83.08C89.6586 83.08 92.2186 82.44 94.0853 81.16C95.952 79.88 96.8853 78.12 96.8853 75.88C96.8853 73.7467 96.0586 72.0667 94.4053 70.84C92.752 69.6133 90.0853 69 86.4053 69H80.4853V60.44L96.0853 42.76L97.5253 47.4H68.1653V37H107.365V45.4L91.8453 63.08L85.2853 59.32H89.0453C95.9253 59.32 101.125 60.8667 104.645 63.96C108.165 67.0533 109.925 71.0267 109.925 75.88C109.925 79.0267 109.099 81.9867 107.445 84.76C105.792 87.48 103.259 89.6933 99.8453 91.4C96.432 93.1067 92.0586 93.96 86.7253 93.96Z" fill="white"/>
 </svg>
diff --git a/assets/prod/app-icon.icon/icon.json b/assets/prod/app-icon.icon/icon.json
index 8c12c022ef8..6976a6a724c 100644
--- a/assets/prod/app-icon.icon/icon.json
+++ b/assets/prod/app-icon.icon/icon.json
@@ -9,7 +9,7 @@
           "image-name": "text.svg",
           "name": "Text",
           "position": {
-            "scale": 10,
+            "scale": 8.5,
             "translation-in-points": [0, 0]
           }
         }
diff --git a/assets/prod/black-ios-1024.png b/assets/prod/black-ios-1024.png
index a8a458337ab..bfc80410aad 100644
Binary files a/assets/prod/black-ios-1024.png and b/assets/prod/black-ios-1024.png differ
diff --git a/assets/prod/black-macos-1024.png b/assets/prod/black-macos-1024.png
index f5b68b1a6d4..6a0fe10d3da 100644
Binary files a/assets/prod/black-macos-1024.png and b/assets/prod/black-macos-1024.png differ
diff --git a/assets/prod/black-universal-1024.png b/assets/prod/black-universal-1024.png
index a8a458337ab..bfc80410aad 100644
Binary files a/assets/prod/black-universal-1024.png and b/assets/prod/black-universal-1024.png differ
diff --git a/assets/prod/t3-black-web-apple-touch-180.png b/assets/prod/t3-black-web-apple-touch-180.png
index 2e30aecbc72..327a8ac55fa 100644
Binary files a/assets/prod/t3-black-web-apple-touch-180.png and b/assets/prod/t3-black-web-apple-touch-180.png differ
diff --git a/assets/prod/t3-black-web-favicon-16x16.png b/assets/prod/t3-black-web-favicon-16x16.png
index c175f2c87a2..6ba6d92c037 100644
Binary files a/assets/prod/t3-black-web-favicon-16x16.png and b/assets/prod/t3-black-web-favicon-16x16.png differ
diff --git a/assets/prod/t3-black-web-favicon-32x32.png b/assets/prod/t3-black-web-favicon-32x32.png
index fe6fb545b85..fb354d60ace 100644
Binary files a/assets/prod/t3-black-web-favicon-32x32.png and b/assets/prod/t3-black-web-favicon-32x32.png differ
diff --git a/assets/prod/t3-black-web-favicon.ico b/assets/prod/t3-black-web-favicon.ico
index a0fe86da92f..5fac0d8b24e 100644
Binary files a/assets/prod/t3-black-web-favicon.ico and b/assets/prod/t3-black-web-favicon.ico differ
diff --git a/assets/prod/t3-black-windows.ico b/assets/prod/t3-black-windows.ico
index a0fe86da92f..5fac0d8b24e 100644
Binary files a/assets/prod/t3-black-windows.ico and b/assets/prod/t3-black-windows.ico differ
diff --git a/docs/architecture/terminal-renderers.md b/docs/architecture/terminal-renderers.md
new file mode 100644
index 00000000000..4b66a13f68c
--- /dev/null
+++ b/docs/architecture/terminal-renderers.md
@@ -0,0 +1,42 @@
+# 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/server-updates.md b/docs/internals/server-updates.md
index 1e017737148..f0a0034c3ee 100644
--- a/docs/internals/server-updates.md
+++ b/docs/internals/server-updates.md
@@ -2,139 +2,87 @@
 
 > For maintainers. Using T3 Code? See [docs/user](../user/).
 
-T3 Code can update a connected server to the exact version of the client that detected version
-drift. This path exists primarily for remote environments, where the user may not have a terminal
-open on the server machine.
-
-The feature has three boundaries:
-
-- the server advertises whether and how it can be replaced;
-- the client chooses the matching user action;
-- the server installs and verifies the replacement before handing off the process.
-
-## Detection and Presentation
-
-`ExecutionEnvironmentDescriptor` includes the server version and an optional
-`capabilities.serverSelfUpdate` value. Progress-capable servers also advertise
-`capabilities.serverSelfUpdateProgress`. The client compares the server version with `APP_VERSION`
-after loading server config.
-
-The optional capability is intentionally backward compatible. An older server does not know about
-the field, so a missing value means the client must offer a manual relaunch instead of sending an
-unknown RPC.
-
-The shared `ServerUpdateAction` is rendered in both user-facing version-drift surfaces:
-
-- the conversation banner in `ChatView`;
-- primary and saved environment rows in **Settings** → **Connections**.
-
-Both surfaces target the client's exact version. When the reconnected server reports that version,
-the mismatch and action disappear.
-
-The operation state lives in `packages/client-runtime`, keyed by environment. Both web surfaces read
-the same `downloading`, `installing`, or `resuming` state, so route changes do not own or cancel the
-operation.
-
-## Capability Selection
-
-The server resolves its capability once at startup and publishes it in the environment descriptor.
-
-| Advertised value  | Process shape                                                                                 | Client behavior                                                       |
-| ----------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `boot-service`    | Linux server running under the T3-managed systemd user service                                | Call the update RPC; the service unit is replaced and restarted.      |
-| `respawn`         | Published npm CLI running in the foreground on macOS or Linux                                 | Call the update RPC; the process hands off to a detached replacement. |
-| `desktop-managed` | Backend supervised by the desktop app                                                         | Tell the user to update the desktop app on the server machine.        |
-| absent            | Older server, development checkout, Windows foreground process, or an unrecognized supervisor | Offer the exact manual relaunch command.                              |
-
-Desktop ownership takes precedence over process-shape detection. A desktop-managed backend must
-never spawn a second CLI server beside the app-owned process. Likewise, a process launched by an
-unrecognized systemd unit does not claim the foreground respawn path because its supervisor could
-bring the old version back.
-
-## Update Flow
-
-```mermaid
-flowchart TD
-    A[Client detects different versions] --> B{Advertised update path}
-    B -->|desktop-managed| C[Update desktop app on server machine]
-    B -->|missing| D[Copy exact manual relaunch command]
-    B -->|boot-service or respawn| E{Progress capability}
-    E -->|present| F[server.updateServerWithProgress]
-    E -->|missing| G[server.updateServer fallback]
-    F --> H[Install exact t3 version in pinned runtime]
-    G --> H
-    H --> I[Run version preflight]
-    I -->|bad code or version| J[Remove candidate runtime and keep current server]
-    I -->|cannot run preflight| J2[Keep candidate and current server]
-    I -->|passes| K{Handoff method}
-    K -->|boot-service| L[Rewrite and restart T3 systemd unit]
-    K -->|respawn| M[Start delayed replacement and exit current process]
-    L --> N[Reconnect with fresh backoff]
-    M --> N
-    N --> O[Replacement publishes ready at target version]
-```
+Remote server updates use one stable systemd launcher. Foreground CLI processes do not self-update,
+and a running server never edits its systemd unit or durable service state.
+
+## Ownership
+
+The service files under `<baseDir>/runtime` are:
+
+- `service-launcher.mjs`, the stable process selected by systemd;
+- `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.
 
-Both update RPCs require the environment's `orchestration:operate` authorization scope. Their
-payload accepts only an exact npm version, including an exact prerelease version; dist-tags such as
-`latest` and `nightly` are rejected. The unary `server.updateServer` method remains available so a
-new client can still repair skew with an older server.
+The state contains one active version and, at most, one update record:
 
-The update service permits one update at a time. It installs `t3@<version>` under
-`<baseDir>/runtime/versions/<version>` and writes an install-complete sentinel only after npm exits
-successfully. Boot-service setup and self-update share the same process-wide installation lock, so
-they cannot mutate a pinned runtime concurrently.
+- `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 systemd cannot guess at a runtime.
 
-Before any restart, the current Node executable runs the replacement with `--version`. A failed
-install, failed preflight, or wrong reported version leaves the current server running.
+Every write uses same-directory replacement plus file and directory fsync.
 
-Candidate cleanup is narrower than "any failed preflight". The candidate runtime is removed only when
-the preflight process actually completes and reports a bad exit code or the wrong version: that is
-the case where a completed npm install produced an unusable tree, so retrying the same version must
-perform a clean install rather than reuse it. If the preflight cannot run at all, for example a spawn
-error or the `PREFLIGHT_TIMEOUT` elapsing, the update fails before reaching cleanup and the candidate
-directory is left in place.
+## Remote Update
 
-## Host Service Lifecycle
+1. The active server installs `t3@<target>` into a unique staging directory.
+2. The target runs `__service-preflight` against the active database in read-only mode.
+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. The launcher starts the target as a trial and gives it the pending update over IPC.
+7. The trial acquires dependencies, binds HTTP, starts every long-running root fiber, and verifies
+   that each root is parked at the activation gate. It does not run migrations.
+8. The trial sends `prepared`. The launcher durably commits B before replying `committed`.
+9. The child opens the existing activation gate, accepts commands, and publishes lifecycle ready
+   with the terminal update outcome.
 
-The systemd user service is a host lifecycle concern, not a T3 Connect resource. The standalone
-`t3 service install`, `uninstall`, `update`, and `status` commands own it. Install and update both
-reconcile the unit through `BootService`; running `npx t3@latest service update` therefore pins and
-activates the latest CLI release without requiring a connected client.
+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 `t3 connect` onboarding flow may offer service installation, but it calls the same reconciliation
-operation as `t3 service install`. Connect logout only disables cloud access and clears its
-authorization; it does not uninstall the host service.
+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 records rollback and
+starts A. After commit, B is active and normal systemd restart policy applies.
 
-## Process Handoff
+## Migration Boundary
+
+Remote update preflight requires exact equality between the database's applied `(id, name)` rows
+and the target release's migration manifest. A target with a missing, additional, renamed, or
+unknown migration is blocked. Remote updates never migrate or downgrade a database.
+
+This deliberately means any release containing a migration requires a local service update:
+
+```sh
+npx t3@<version> service update
+```
 
-For `boot-service`, the server atomically rewrites the T3-managed user unit to point at the verified
-runtime and reloads systemd. It acknowledges the handoff, then restarts the unit after the same
-short grace period used by foreground respawn. A rejected deferred restart restores the previous
-unit and is logged by the still-running process.
+The local command stops the unit, selects the new launcher and exact runtime, then restarts the
+service. Its normal server startup may run migrations.
 
-For `respawn`, the server starts a detached, delayed replacement that replays the original CLI
-arguments. It then acknowledges the request and schedules the current process to exit. The delays
-give the acknowledgement time to cross direct or relayed connections before the socket closes.
+## Client Correlation
 
-Progress-capable servers emit `downloading` before installing the pinned runtime and `installing`
-before preflight and handoff. A terminal stream event acknowledges that restart is scheduled. The
-client then enters `resuming`, waits for the replacement lifecycle stream to publish `ready` with
-the target version, and only then completes the operation. It watches for the intentional
-disconnect's first backoff state and requests one fresh retry, which clears historical backoff debt
-without adding a separate reconnect loop.
+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.
 
-## Release Invariant
+## Capability and Compatibility
 
-The exact client version must exist as the `t3` npm package before a client carrying that version is
-published. The release workflow therefore makes the GitHub release depend on CLI publication, and
-the hosted web deployment depends on that release. See [Release Checklist](../operations/release.md#server-self-update-release-invariant).
+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 direct the user to update the desktop app. Other process shapes provide a
+manual command; the old detached foreground respawn path no longer exists.
 
 ## Source Map
 
-- Capability contract: `packages/contracts/src/environment.ts`
-- Update RPC contract: `packages/contracts/src/server.ts` and `packages/contracts/src/rpc.ts`
-- Capability detection and handoff: `apps/server/src/cloud/selfUpdate.ts`
-- Host service commands: `apps/server/src/cli/service.ts`
-- Pinned runtime installation: `apps/server/src/cloud/pinnedRuntime.ts`
-- Client version comparison: `apps/web/src/versionSkew.ts`
-- Shared update action: `apps/web/src/components/ServerUpdateAction.tsx`
+- 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`
diff --git a/docs/operations/mobile-app-store-screenshots.md b/docs/operations/mobile-app-store-screenshots.md
index 27891cb5d63..f271e54098a 100644
--- a/docs/operations/mobile-app-store-screenshots.md
+++ b/docs/operations/mobile-app-store-screenshots.md
@@ -43,7 +43,7 @@ Captures wait for the real environment snapshot to hydrate and for the requested
 active. Both platforms record readiness in the simulator/emulator app container. A final settle
 delay allows native terminal and Git review data to finish rendering.
 
-A full capture regenerates the selected native project with Expo's clean development prebuild before
+A full capture regenerates the selected native project with Expo's clean production prebuild before
 building it. Use --skip-build for repeated captures after the first build.
 
 The harness uses fixed Metro port `8199`, which separates it from Expo's normal default port but is
@@ -61,7 +61,7 @@ The default matrix is:
 | ----------------------------- | ------------------------- | ----------------- | ----------------------------------------- |
 | `apple/iphone-6.9/dark/`      | iPhone 17 Pro Max         | 1320×2868         | App Store Connect iPhone 6.9-inch         |
 | `apple/iphone-6.5/dark/`      | disposable iPhone 14 Plus | 1284×2778         | App Store Connect iPhone 6.5-inch         |
-| `apple/ipad-13/dark/`         | iPad Pro 13-inch (M5)     | 2064×2752         | App Store Connect iPad 13-inch            |
+| `apple/ipad-13/dark/`         | iPad Pro 13-inch (M5)     | 2752×2064         | App Store Connect iPad 13-inch, landscape |
 | `google-play/phone/dark/`     | Pixel AVD at 420 dpi      | 1080×1920         | Google Play phone, portrait 9:16          |
 | `google-play/tablet-7/dark/`  | Pixel AVD at 600dp width  | 1080×1920         | Google Play 7-inch tablet, portrait 9:16  |
 | `google-play/tablet-10/dark/` | Pixel AVD at 800dp width  | 1440×2560         | Google Play 10-inch tablet, portrait 9:16 |
@@ -86,7 +86,8 @@ A light-only run writes the same tree under `light/`; `--appearance both` writes
 folders.
 
 Edit [mobile-showcase.config.ts](../../scripts/mobile-showcase.config.ts) to change simulator or AVD
-names, light/dark appearance, scenes, output directory, capture delay, Android ABI, or viewport.
+names, light/dark appearance, iOS orientation, scenes, output directory, capture delay, Android ABI,
+or viewport.
 
 ## Capture in GitHub Actions
 
diff --git a/docs/operations/release.md b/docs/operations/release.md
index 9b33e94cc60..89c4006bafd 100644
--- a/docs/operations/release.md
+++ b/docs/operations/release.md
@@ -187,8 +187,10 @@ the **Update server** action targeting a package version that does not exist yet
 
 For a release smoke test, confirm `npm view t3@<version> version` returns the expected version, then
 connect the new client to a server on the previous version and verify that the update action
-reconnects to the matching server. Test one automatic path and the manual or desktop-managed
-guidance when those environments are available.
+reconnects to the matching server. Use releases with identical migration manifests for the
+automatic path. When the manifest changed, verify that the remote action stops before restart and
+shows the exact local `npx t3@<version> service update` command. Also test the manual or
+desktop-managed guidance when those environments are available.
 
 ## Desktop auto-update notes
 
diff --git a/docs/user/background-service.md b/docs/user/background-service.md
index 8f1f68dc065..0ab5b2013c7 100644
--- a/docs/user/background-service.md
+++ b/docs/user/background-service.md
@@ -31,6 +31,10 @@ npx t3@latest service uninstall
 
 Updating restarts T3 Code briefly. Let active agent work and terminal commands finish first.
 
+The systemd unit 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 unit. Releases
+that change the database must be installed with the local `service update` command above.
+
 ## Using It with T3 Connect
 
 T3 Connect may offer to install the service during setup so the host stays reachable after you log
diff --git a/docs/user/keybindings.md b/docs/user/keybindings.md
index 95f487f45f3..d94d3dc2dba 100644
--- a/docs/user/keybindings.md
+++ b/docs/user/keybindings.md
@@ -37,6 +37,10 @@ Examples: `mod+j`, `mod+shift+d`, `ctrl+l`, `cmd+k`.
 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`.
 
+`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.
+
 The command palette searches active thread titles, projects, branches, user messages, and final
 agent responses across connected environments. Message matches show one labeled excerpt while
 keeping the thread's project, branch, and machine context visible. Message search begins after two
diff --git a/docs/user/remote-access.md b/docs/user/remote-access.md
index 3881c5be3a4..05418022d23 100644
--- a/docs/user/remote-access.md
+++ b/docs/user/remote-access.md
@@ -2,6 +2,26 @@
 
 Use this when you want to connect to a T3 Code server from another device such as a phone, tablet, or separate desktop app.
 
+## 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 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.
+
+If the server is only bound to loopback, the printed URL is not reachable from another device. Pair over your tailnet instead:
+
+```bash
+npx t3 pair --tailscale
+```
+
+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.
@@ -38,6 +58,8 @@ available. You can set another endpoint as the default from the expanded endpoin
 
 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.
diff --git a/docs/user/updating.md b/docs/user/updating.md
index 8e1fac81854..a0cc0e5d1e0 100644
--- a/docs/user/updating.md
+++ b/docs/user/updating.md
@@ -24,13 +24,17 @@ The update does not remove saved threads, settings, or project files.
 
 | Action                     | What to do                                                                                                                                                                  |
 | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Update server**          | Select the button and leave T3 Code open. It prepares the matching version, restarts the server, and reconnects automatically. This can take several minutes.               |
+| **Update server**          | Available for the T3 Code Linux background service. Select the button and leave T3 Code open while it prepares, tests, restarts, and reconnects.                            |
 | **Update the desktop app** | 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.
 
+If the requested version includes a database update, remote installation stops before restart and
+asks you to run the exact `npx t3@<version> service update` command on the server machine. This is
+an intentional rollback-safety boundary.
+
 After selecting **Update server**, the warning becomes a three-step progress rail:
 **Download**, **Install**, and **Resume**. The same progress appears in the conversation and in
 Connections, so navigating between them does not lose the update. A failed step remains visible
@@ -56,8 +60,8 @@ commands.
 ## After the Update
 
 Keep the web or desktop app open while the server restarts. The update completes only after the
-replacement server reports the requested version and is ready to accept commands. The warning and
-progress rail then disappear.
+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:
 
diff --git a/infra/relay/src/environments/EnvironmentConnector.ts b/infra/relay/src/environments/EnvironmentConnector.ts
index db662aee94d..d840f809e5a 100644
--- a/infra/relay/src/environments/EnvironmentConnector.ts
+++ b/infra/relay/src/environments/EnvironmentConnector.ts
@@ -13,6 +13,7 @@ import {
   RelayEnvironmentMintResponse,
   RelayEnvironmentMintResponseProofPayload,
   RelayCloudMintCredentialProofPayload,
+  RelayEnvironmentConnectNotAuthorizedReason,
   type RelayEnvironmentConnectResponse,
   type RelayEnvironmentStatusResponse,
 } from "@t3tools/contracts/relay";
@@ -44,21 +45,8 @@ import * as ManagedEndpointAllocations from "./ManagedEndpointAllocations.ts";
 import * as RelayConfiguration from "../Config.ts";
 import { isManagedEndpointHostname } from "../deploymentConfig.ts";
 
-export const EnvironmentConnectNotAuthorizedReason = Schema.Literals([
-  "client_proof_key_thumbprint_missing",
-  "environment_link_not_found",
-  "endpoint_provider_not_managed",
-  "managed_endpoint_allocation_not_found",
-  "managed_endpoint_base_domain_not_configured",
-  "managed_endpoint_allocation_not_ready",
-  "managed_endpoint_hostname_invalid",
-  "managed_endpoint_mismatch",
-]);
-export type EnvironmentConnectNotAuthorizedReason =
-  typeof EnvironmentConnectNotAuthorizedReason.Type;
-
 function environmentConnectNotAuthorizedReasonMessage(
-  reason: EnvironmentConnectNotAuthorizedReason,
+  reason: RelayEnvironmentConnectNotAuthorizedReason,
 ): string {
   switch (reason) {
     case "client_proof_key_thumbprint_missing":
@@ -85,7 +73,7 @@ export class EnvironmentConnectNotAuthorized extends Schema.TaggedErrorClass<Env
   {
     environmentId: Schema.String,
     operation: Schema.Literals(["connect", "status"]),
-    reason: EnvironmentConnectNotAuthorizedReason,
+    reason: RelayEnvironmentConnectNotAuthorizedReason,
   },
 ) {
   override get message(): string {
diff --git a/infra/relay/src/http/Api.ts b/infra/relay/src/http/Api.ts
index 7510b4a8d41..50bcff665a9 100644
--- a/infra/relay/src/http/Api.ts
+++ b/infra/relay/src/http/Api.ts
@@ -778,9 +778,10 @@ export const dpopClientApi = HttpApiBuilder.group(
           },
           mapRelayCommonApiErrors("invalid_dpop"),
           mapErrorTags({
-            EnvironmentConnectNotAuthorized: (_error, traceId) =>
+            EnvironmentConnectNotAuthorized: (error, traceId) =>
               new RelayEnvironmentConnectNotAuthorizedError({
                 code: "environment_connect_not_authorized",
+                reason: error.reason,
                 traceId,
               }),
             EnvironmentMintRequestFailed: (_error, traceId) =>
@@ -820,9 +821,10 @@ export const dpopClientApi = HttpApiBuilder.group(
           },
           mapRelayCommonApiErrors("invalid_dpop"),
           mapErrorTags({
-            EnvironmentConnectNotAuthorized: (_error, traceId) =>
+            EnvironmentConnectNotAuthorized: (error, traceId) =>
               new RelayEnvironmentConnectNotAuthorizedError({
                 code: "environment_connect_not_authorized",
+                reason: error.reason,
                 traceId,
               }),
             EnvironmentMintRequestFailed: (_error, traceId) =>
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/LICENSE b/native/libghostty-vt/LICENSE
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/LICENSE
rename to native/libghostty-vt/LICENSE
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/VERSION b/native/libghostty-vt/VERSION
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/VERSION
rename to native/libghostty-vt/VERSION
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt.h b/native/libghostty-vt/include/ghostty/vt.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt.h
rename to native/libghostty-vt/include/ghostty/vt.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/allocator.h b/native/libghostty-vt/include/ghostty/vt/allocator.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/allocator.h
rename to native/libghostty-vt/include/ghostty/vt/allocator.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/build_info.h b/native/libghostty-vt/include/ghostty/vt/build_info.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/build_info.h
rename to native/libghostty-vt/include/ghostty/vt/build_info.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/color.h b/native/libghostty-vt/include/ghostty/vt/color.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/color.h
rename to native/libghostty-vt/include/ghostty/vt/color.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/device.h b/native/libghostty-vt/include/ghostty/vt/device.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/device.h
rename to native/libghostty-vt/include/ghostty/vt/device.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/focus.h b/native/libghostty-vt/include/ghostty/vt/focus.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/focus.h
rename to native/libghostty-vt/include/ghostty/vt/focus.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/formatter.h b/native/libghostty-vt/include/ghostty/vt/formatter.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/formatter.h
rename to native/libghostty-vt/include/ghostty/vt/formatter.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/grid_ref.h b/native/libghostty-vt/include/ghostty/vt/grid_ref.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/grid_ref.h
rename to native/libghostty-vt/include/ghostty/vt/grid_ref.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/grid_ref_tracked.h b/native/libghostty-vt/include/ghostty/vt/grid_ref_tracked.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/grid_ref_tracked.h
rename to native/libghostty-vt/include/ghostty/vt/grid_ref_tracked.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key.h b/native/libghostty-vt/include/ghostty/vt/key.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key.h
rename to native/libghostty-vt/include/ghostty/vt/key.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key/encoder.h b/native/libghostty-vt/include/ghostty/vt/key/encoder.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key/encoder.h
rename to native/libghostty-vt/include/ghostty/vt/key/encoder.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key/event.h b/native/libghostty-vt/include/ghostty/vt/key/event.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/key/event.h
rename to native/libghostty-vt/include/ghostty/vt/key/event.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/kitty_graphics.h b/native/libghostty-vt/include/ghostty/vt/kitty_graphics.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/kitty_graphics.h
rename to native/libghostty-vt/include/ghostty/vt/kitty_graphics.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/modes.h b/native/libghostty-vt/include/ghostty/vt/modes.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/modes.h
rename to native/libghostty-vt/include/ghostty/vt/modes.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse.h b/native/libghostty-vt/include/ghostty/vt/mouse.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse.h
rename to native/libghostty-vt/include/ghostty/vt/mouse.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse/encoder.h b/native/libghostty-vt/include/ghostty/vt/mouse/encoder.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse/encoder.h
rename to native/libghostty-vt/include/ghostty/vt/mouse/encoder.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse/event.h b/native/libghostty-vt/include/ghostty/vt/mouse/event.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/mouse/event.h
rename to native/libghostty-vt/include/ghostty/vt/mouse/event.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/osc.h b/native/libghostty-vt/include/ghostty/vt/osc.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/osc.h
rename to native/libghostty-vt/include/ghostty/vt/osc.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/paste.h b/native/libghostty-vt/include/ghostty/vt/paste.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/paste.h
rename to native/libghostty-vt/include/ghostty/vt/paste.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/point.h b/native/libghostty-vt/include/ghostty/vt/point.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/point.h
rename to native/libghostty-vt/include/ghostty/vt/point.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/render.h b/native/libghostty-vt/include/ghostty/vt/render.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/render.h
rename to native/libghostty-vt/include/ghostty/vt/render.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/screen.h b/native/libghostty-vt/include/ghostty/vt/screen.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/screen.h
rename to native/libghostty-vt/include/ghostty/vt/screen.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/selection.h b/native/libghostty-vt/include/ghostty/vt/selection.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/selection.h
rename to native/libghostty-vt/include/ghostty/vt/selection.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/sgr.h b/native/libghostty-vt/include/ghostty/vt/sgr.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/sgr.h
rename to native/libghostty-vt/include/ghostty/vt/sgr.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/size_report.h b/native/libghostty-vt/include/ghostty/vt/size_report.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/size_report.h
rename to native/libghostty-vt/include/ghostty/vt/size_report.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/style.h b/native/libghostty-vt/include/ghostty/vt/style.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/style.h
rename to native/libghostty-vt/include/ghostty/vt/style.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/sys.h b/native/libghostty-vt/include/ghostty/vt/sys.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/sys.h
rename to native/libghostty-vt/include/ghostty/vt/sys.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/terminal.h b/native/libghostty-vt/include/ghostty/vt/terminal.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/terminal.h
rename to native/libghostty-vt/include/ghostty/vt/terminal.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/types.h b/native/libghostty-vt/include/ghostty/vt/types.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/types.h
rename to native/libghostty-vt/include/ghostty/vt/types.h
diff --git a/apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/wasm.h b/native/libghostty-vt/include/ghostty/vt/wasm.h
similarity index 100%
rename from apps/mobile/modules/t3-terminal/Vendor/libghostty-vt/include/ghostty/vt/wasm.h
rename to native/libghostty-vt/include/ghostty/vt/wasm.h
diff --git a/oxlint-plugin-t3code/test/utils.ts b/oxlint-plugin-t3code/test/utils.ts
index eb91d32d7d4..740da8a4f2b 100644
--- a/oxlint-plugin-t3code/test/utils.ts
+++ b/oxlint-plugin-t3code/test/utils.ts
@@ -9,6 +9,17 @@ import * as Predicate from "effect/Predicate";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import * as NodeModule from "node:module";
+
+// oxlint is only a transitive dependency (via vite-plus), so its bin placement
+// varies by package manager: pnpm hoists it into the virtual store, while
+// other layouts expose vite-plus's LSP-only wrapper instead. Resolve the real
+// package through vite-plus rather than hardcoding either layout, and do it at
+// module scope so a broken install fails once with a resolution error instead
+// of as an opaque defect in every test.
+const oxlintPackageJsonPath = NodeModule.createRequire(
+  NodeModule.createRequire(import.meta.url).resolve("vite-plus/package.json"),
+).resolve("oxlint/package.json");
 
 class OxlintFixtureFailure extends Data.TaggedError("OxlintFixtureFailure")<{
   readonly exitCode: number;
@@ -93,14 +104,7 @@ export const createOxlintRuleHarness = (
     const configPath = path.join(fixtureDir, ".oxlintrc.json");
     const sourcePath = path.join(fixtureDir, options.filename ?? "fixture.ts");
     const repoRoot = path.join(import.meta.dirname, "..", "..");
-    const oxlintBin = path.join(
-      repoRoot,
-      "node_modules",
-      ".pnpm",
-      "node_modules",
-      ".bin",
-      "oxlint",
-    );
+    const oxlintBin = path.join(path.dirname(oxlintPackageJsonPath), "bin", "oxlint");
     const pluginPath = path.join(repoRoot, "oxlint-plugin-t3code", "index.ts");
 
     yield* fs.writeFileString(
@@ -112,8 +116,13 @@ export const createOxlintRuleHarness = (
     );
     yield* fs.writeFileString(sourcePath, source);
 
+    // Run through the current Node binary: oxlint's bin is an extensionless
+    // shebang script, which Windows cannot spawn directly and which would
+    // otherwise pick up whatever node is first on PATH.
     const output = yield* spawnAndCollectOutput(
-      ChildProcess.make(oxlintBin, ["--config", configPath, sourcePath], { cwd: repoRoot }),
+      ChildProcess.make(process.execPath, [oxlintBin, "--config", configPath, sourcePath], {
+        cwd: repoRoot,
+      }),
     );
 
     if (output.exitCode !== 0) {
diff --git a/packages/client-runtime/src/rpc/session.test.ts b/packages/client-runtime/src/rpc/session.test.ts
index 71649ad94dd..751453f82f6 100644
--- a/packages/client-runtime/src/rpc/session.test.ts
+++ b/packages/client-runtime/src/rpc/session.test.ts
@@ -287,6 +287,40 @@ describe("RpcSessionFactory", () => {
     }),
   );
 
+  it.effect("reaches ready when a newer server sends unknown config members", () =>
+    Effect.gen(function* () {
+      const { factory, sockets } = yield* makeFactory();
+      const session = yield* factory.connect(PREPARED);
+      const readyFiber = yield* Effect.forkChild(session.ready);
+      const socket = yield* awaitSocket(sockets);
+      socket.open();
+
+      const shortcut = {
+        key: "p",
+        metaKey: false,
+        ctrlKey: false,
+        shiftKey: false,
+        altKey: false,
+        modKey: true,
+      };
+      yield* completeInitialConfig(socket, {
+        ...ENCODED_SERVER_CONFIG,
+        keybindings: [
+          { command: "someFuture.toggle", shortcut },
+          { command: "terminal.toggle", shortcut },
+        ],
+        issues: [{ kind: "keybindings.future-issue", message: "From a newer server" }],
+        availableEditors: ["some-future-editor", "zed"],
+      });
+      yield* Fiber.join(readyFiber);
+
+      const config = yield* session.initialConfig;
+      expect(config.keybindings).toEqual([{ command: "terminal.toggle", shortcut }]);
+      expect(config.issues).toEqual([]);
+      expect(config.availableEditors).toEqual(["zed"]);
+    }),
+  );
+
   it.effect("uses the legacy config RPC for probes when the server lacks the capability", () =>
     Effect.scoped(
       Effect.gen(function* () {
diff --git a/packages/client-runtime/src/state/server.test.ts b/packages/client-runtime/src/state/server.test.ts
index 12925a99867..d764b729fc3 100644
--- a/packages/client-runtime/src/state/server.test.ts
+++ b/packages/client-runtime/src/state/server.test.ts
@@ -29,11 +29,13 @@ import {
   applyServerConfigProjection,
   makeEnvironmentServerConfigState,
   isLegacyUpdateHandoffLoss,
+  matchesServerUpdateReadyEvent,
   projectServerWelcome,
   resolveServerConfigValue,
   resolveServerUpdateProgressResult,
   serverUpdateStateForProgressEvent,
   serverUpdateStateForServerVersion,
+  validateServerUpdateReadyEvent,
 } from "./server.ts";
 
 const CONFIG = {
@@ -173,6 +175,40 @@ describe("server state projection", () => {
     expect(serverUpdateStateForServerVersion(failed, "0.0.31")).toEqual({ status: "idle" });
   });
 
+  it.effect("correlates launcher outcomes and fails immediately after rollback", () =>
+    Effect.gen(function* () {
+      const result = {
+        targetVersion: "0.0.31",
+        method: "boot-service" as const,
+        updateId: "update-1",
+      };
+      const ready = (status: "committed" | "rolled-back") =>
+        ({
+          version: 1 as const,
+          sequence: 1,
+          type: "ready" as const,
+          payload: {
+            at: "2026-08-01T00:00:00.000Z",
+            environment: { serverVersion: status === "committed" ? "0.0.31" : "0.0.30" },
+            updateOutcome: {
+              id: "update-1",
+              fromVersion: "0.0.30",
+              targetVersion: "0.0.31",
+              status,
+              ...(status === "rolled-back" ? { reason: "prepared-timeout" } : {}),
+            },
+          },
+        }) as Parameters<typeof matchesServerUpdateReadyEvent>[1];
+
+      expect(matchesServerUpdateReadyEvent(result, ready("committed"))).toBe(true);
+      yield* validateServerUpdateReadyEvent(result, ready("committed"));
+      const rollback = yield* Effect.flip(
+        validateServerUpdateReadyEvent(result, ready("rolled-back")),
+      );
+      expect(rollback.message).toBe("prepared-timeout");
+    }),
+  );
+
   it("applies every config category to the projected snapshot", () => {
     const snapshot = applyServerConfigProjection(Option.none(), {
       version: 1,
diff --git a/packages/client-runtime/src/state/server.ts b/packages/client-runtime/src/state/server.ts
index edd1893f739..12639c4ed7b 100644
--- a/packages/client-runtime/src/state/server.ts
+++ b/packages/client-runtime/src/state/server.ts
@@ -3,6 +3,7 @@ import {
   type ServerConfig,
   type ServerConfigStreamEvent,
   type ServerLifecycleWelcomePayload,
+  type ServerLifecycleStreamReadyEvent,
   type ServerSelfUpdateProgressEvent,
   type ServerSelfUpdateResult,
   WS_METHODS,
@@ -97,6 +98,57 @@ export class ServerUpdateProgressIncompleteError extends Schema.TaggedErrorClass
   }
 }
 
+export class ServerUpdateTerminalError extends Schema.TaggedErrorClass<ServerUpdateTerminalError>()(
+  "ServerUpdateTerminalError",
+  {
+    targetVersion: Schema.String,
+    status: Schema.Literals(["committed", "rolled-back", "failed"]),
+    reason: Schema.optional(Schema.String),
+  },
+) {
+  override get message(): string {
+    return this.reason ?? `The t3@${this.targetVersion} update ${this.status}.`;
+  }
+}
+
+// Covers the 120-second trial deadline and a final restart of the previous
+// version when the trial rolls back.
+const SERVER_UPDATE_RESUME_TIMEOUT = Duration.minutes(4);
+
+export function matchesServerUpdateReadyEvent(
+  result: ServerSelfUpdateResult,
+  event: ServerLifecycleStreamReadyEvent,
+): boolean {
+  return result.updateId === undefined
+    ? event.payload.environment.serverVersion === result.targetVersion
+    : event.payload.updateOutcome?.id === result.updateId;
+}
+
+export function validateServerUpdateReadyEvent(
+  result: ServerSelfUpdateResult,
+  event: ServerLifecycleStreamReadyEvent,
+): Effect.Effect<void, ServerUpdateTerminalError> {
+  if (result.updateId === undefined) return Effect.void;
+  const outcome = event.payload.updateOutcome;
+  if (
+    outcome?.id === result.updateId &&
+    outcome.status === "committed" &&
+    outcome.targetVersion === result.targetVersion &&
+    event.payload.environment.serverVersion === result.targetVersion
+  ) {
+    return Effect.void;
+  }
+  return Effect.fail(
+    new ServerUpdateTerminalError({
+      targetVersion: result.targetVersion,
+      status: outcome?.status ?? "failed",
+      reason:
+        outcome?.reason ??
+        "The service launcher resumed without committing the requested server version.",
+    }),
+  );
+}
+
 export function serverUpdateStateForProgressEvent(
   fromVersion: string,
   targetVersion: string,
@@ -554,11 +606,11 @@ export function createServerEnvironmentAtoms<R, E>(
           .followStream(target.environmentId, subscribe(WS_METHODS.subscribeServerLifecycle, {}))
           .pipe(
             Stream.filter(
-              (event) =>
-                event.type === "ready" && event.payload.environment.serverVersion === targetVersion,
+              (event): event is ServerLifecycleStreamReadyEvent =>
+                event.type === "ready" && matchesServerUpdateReadyEvent(result, event),
             ),
             Stream.runHead,
-            Effect.timeoutOption(Duration.seconds(120)),
+            Effect.timeoutOption(SERVER_UPDATE_RESUME_TIMEOUT),
             Effect.map(Option.flatten),
           );
         if (Option.isNone(resumed)) {
@@ -567,6 +619,7 @@ export function createServerEnvironmentAtoms<R, E>(
             targetVersion,
           });
         }
+        yield* validateServerUpdateReadyEvent(result, resumed.value);
 
         atomRegistry.set(stateAtom, IDLE_SERVER_UPDATE_STATE);
         return result;
diff --git a/packages/client-runtime/src/state/threadSettled.test.ts b/packages/client-runtime/src/state/threadSettled.test.ts
index 99d906c00fa..a7dd4b1eab8 100644
--- a/packages/client-runtime/src/state/threadSettled.test.ts
+++ b/packages/client-runtime/src/state/threadSettled.test.ts
@@ -115,13 +115,15 @@ describe("effectiveSettled", () => {
             // Settled iff nothing blocks (pending work / live session) AND
             // the override says settled, or (with no override) a merged PR
             // or staleness auto-settles. The "active" pin suppresses both
-            // auto signals.
+            // auto signals, and an open PR suppresses the inactivity path:
+            // a thread with a PR out for review is never done, however quiet.
             expected:
               pending === undefined &&
               !running &&
               (settledOverride === "settled" ||
                 (settledOverride === null &&
-                  (changeRequestState === "merged" || inactivity === "stale"))),
+                  (changeRequestState === "merged" ||
+                    (changeRequestState !== "open" && inactivity === "stale")))),
           })),
         ),
       ),
@@ -176,6 +178,26 @@ describe("effectiveSettled", () => {
     }
   });
 
+  it("never auto-settles a stale thread with an open change request", () => {
+    const stale = makeShell({ activityAt: STALE });
+    expect(
+      effectiveSettled(stale, {
+        now: NOW,
+        autoSettleAfterDays: 3,
+        changeRequestState: "open",
+      }),
+    ).toBe(false);
+    // An explicit user settle still wins: open PR only blocks the auto path.
+    const settled = makeShell({ settledOverride: "settled", activityAt: STALE });
+    expect(
+      effectiveSettled(settled, {
+        now: NOW,
+        autoSettleAfterDays: 3,
+        changeRequestState: "open",
+      }),
+    ).toBe(true);
+  });
+
   it("keeps an explicitly un-settled merged-PR thread active", () => {
     const shell = makeShell({
       settledOverride: "active",
diff --git a/packages/client-runtime/src/state/threadSettled.ts b/packages/client-runtime/src/state/threadSettled.ts
index 3a98b9d2f27..595b1303bea 100644
--- a/packages/client-runtime/src/state/threadSettled.ts
+++ b/packages/client-runtime/src/state/threadSettled.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics globalDate:off -- UI snooze presets use local calendar boundaries and Intl labels.
 import type { OrchestrationThreadShell } from "@t3tools/contracts";
 
 export type ChangeRequestStateLike = "open" | "closed" | "merged";
@@ -221,7 +222,8 @@ export function threadWokeAt(
  * override. Past the blockers, the explicit user override (thread.settle /
  * thread.unsettle commands, projected into settledOverride + settledAt)
  * wins in both directions; without one, a thread auto-settles on a
- * merged/closed PR immediately or on inactivity past the window. The server
+ * merged/closed PR immediately or on inactivity past the window — except
+ * that an open PR blocks the inactivity path entirely. The server
  * un-settles on real activity (user message, session start, approval/
  * user-input request), so an override never goes stale silently.
  */
@@ -259,6 +261,11 @@ export function effectiveSettled(
   if (options.changeRequestState === "merged" || options.changeRequestState === "closed") {
     return true;
   }
+  // An open PR is unfinished business regardless of how long the thread has
+  // been quiet: review can take days, and hiding the thread would bury the
+  // work waiting on it. Only merge/close (above) or an explicit user settle
+  // resolves it.
+  if (options.changeRequestState === "open") return false;
   if (options.autoSettleAfterDays === null) return false;
 
   const lastActivityAt = threadLastActivityAt(shell);
@@ -272,3 +279,100 @@ export function effectiveSettled(
     Date.parse(lastActivityAt) < Date.parse(options.now) - options.autoSettleAfterDays * DAY_MS
   );
 }
+
+const HOUR_MS = 60 * 60 * 1_000;
+const EVENING_HOUR = 18;
+const MORNING_HOUR = 9;
+
+export type SnoozePresetId = "hour" | "evening" | "tomorrow" | "next-week";
+
+export interface SnoozePreset {
+  readonly id: SnoozePresetId;
+  readonly label: string;
+  /** Menu-row time column. Complements the label instead of repeating it:
+      "Tomorrow" pairs with "9:00 AM", not "tomorrow 9:00 AM". */
+  readonly whenLabel: string;
+  /** ISO wake time. */
+  readonly snoozedUntil: string;
+}
+
+function snoozeTimeOfDayLabel(date: Date): string {
+  return date.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
+}
+
+function snoozeAtHour(base: Date, hour: number): Date {
+  const next = new Date(base);
+  next.setHours(hour, 0, 0, 0);
+  return next;
+}
+
+// Calendar-day advance instead of adding DAY_MS: fixed millisecond offsets
+// land on the wrong local day across DST transitions (a spring-forward day
+// is 23 hours, so 23:30 + 24h skips the whole next day).
+function addSnoozeDays(base: Date, days: number): Date {
+  const next = new Date(base);
+  next.setDate(next.getDate() + days);
+  return next;
+}
+
+/**
+ * Shared "snooze until" choices for every client. "This evening" only
+ * appears while it is meaningfully before evening; after that the list
+ * starts at "Tomorrow".
+ */
+export function resolveSnoozePresets(now: Date): ReadonlyArray<SnoozePreset> {
+  const inAnHour = new Date(now.getTime() + HOUR_MS);
+  const presets: SnoozePreset[] = [
+    {
+      id: "hour",
+      label: "In 1 hour",
+      whenLabel: snoozeTimeOfDayLabel(inAnHour),
+      snoozedUntil: inAnHour.toISOString(),
+    },
+  ];
+
+  const evening = snoozeAtHour(now, EVENING_HOUR);
+  if (evening.getTime() - now.getTime() > HOUR_MS) {
+    presets.push({
+      id: "evening",
+      label: "This evening",
+      whenLabel: snoozeTimeOfDayLabel(evening),
+      snoozedUntil: evening.toISOString(),
+    });
+  }
+
+  const tomorrow = snoozeAtHour(addSnoozeDays(now, 1), MORNING_HOUR);
+  presets.push({
+    id: "tomorrow",
+    label: "Tomorrow",
+    whenLabel: snoozeTimeOfDayLabel(tomorrow),
+    snoozedUntil: tomorrow.toISOString(),
+  });
+
+  const daysUntilMonday = (1 - now.getDay() + 7) % 7 || 7;
+  const nextWeek = snoozeAtHour(addSnoozeDays(now, daysUntilMonday), MORNING_HOUR);
+  presets.push({
+    id: "next-week",
+    label: "Next week",
+    whenLabel: `${nextWeek.toLocaleDateString(undefined, { weekday: "short" })} ${snoozeTimeOfDayLabel(nextWeek)}`,
+    snoozedUntil: nextWeek.toISOString(),
+  });
+
+  return presets;
+}
+
+/**
+ * Compact "wakes in" label for snoozed rows: "2h", "18h", "3d". Minutes
+ * round up so a snooze never reads "0m" while still hidden. Shared by web
+ * and mobile so the same wake time never reads differently per client.
+ */
+export function snoozeWakeLabel(snoozedUntil: string, options: { readonly now: string }): string {
+  const wakeMs = Date.parse(snoozedUntil);
+  const nowMs = Date.parse(options.now);
+  if (Number.isNaN(wakeMs) || Number.isNaN(nowMs)) return "now";
+  const remainingMs = wakeMs - nowMs;
+  if (remainingMs <= 0) return "now";
+  if (remainingMs < HOUR_MS) return `${Math.max(1, Math.ceil(remainingMs / 60_000))}m`;
+  if (remainingMs < DAY_MS) return `${Math.ceil(remainingMs / HOUR_MS)}h`;
+  return `${Math.ceil(remainingMs / DAY_MS)}d`;
+}
diff --git a/packages/client-runtime/src/state/threadSnoozed.test.ts b/packages/client-runtime/src/state/threadSnoozed.test.ts
index c26d23e264c..2c1c58d37a1 100644
--- a/packages/client-runtime/src/state/threadSnoozed.test.ts
+++ b/packages/client-runtime/src/state/threadSnoozed.test.ts
@@ -1,3 +1,4 @@
+// @effect-diagnostics globalDate:off -- Tests exercise local calendar snooze boundaries.
 import { ThreadId } from "@t3tools/contracts";
 import { TurnId } from "@t3tools/contracts";
 import { describe, expect, it } from "vite-plus/test";
@@ -5,6 +6,8 @@ import { describe, expect, it } from "vite-plus/test";
 import {
   canSnooze,
   effectiveSnoozed,
+  resolveSnoozePresets,
+  snoozeWakeLabel,
   threadRaisedHandWhileSnoozed,
   threadWokeAt,
   type ThreadSnoozeShell,
@@ -15,6 +18,10 @@ const SNOOZED_AT = "2026-04-10T09:00:00.000Z";
 const FUTURE_WAKE = "2026-04-11T09:00:00.000Z";
 const PAST_WAKE = "2026-04-10T10:00:00.000Z";
 
+function localDate(year: number, month: number, day: number, hour: number, minute = 0): Date {
+  return new Date(year, month - 1, day, hour, minute, 0, 0);
+}
+
 function makeShell(input: {
   readonly snoozedUntil?: string | null;
   readonly snoozedAt?: string | null;
@@ -235,3 +242,53 @@ describe("threadWokeAt", () => {
     ).toBe("2026-04-10T09:30:00.000Z");
   });
 });
+
+describe("snoozeWakeLabel", () => {
+  const now = "2026-06-02T00:00:00.000Z";
+
+  it("formats remaining time coarsely, rounding up", () => {
+    expect(snoozeWakeLabel("2026-06-02T00:30:00.000Z", { now })).toBe("30m");
+    expect(snoozeWakeLabel("2026-06-02T01:30:00.000Z", { now })).toBe("2h");
+    expect(snoozeWakeLabel("2026-06-03T02:00:00.000Z", { now })).toBe("2d");
+  });
+
+  it("never reads zero or negative while still snoozed", () => {
+    expect(snoozeWakeLabel("2026-06-02T00:00:30.000Z", { now })).toBe("1m");
+    expect(snoozeWakeLabel("2026-06-01T23:59:59.000Z", { now })).toBe("now");
+    expect(snoozeWakeLabel("not-a-date", { now })).toBe("now");
+    expect(snoozeWakeLabel("2026-06-02T09:00:00.000Z", { now: "bad" })).toBe("now");
+  });
+});
+
+describe("resolveSnoozePresets", () => {
+  it("offers the shared desktop and mobile choices", () => {
+    const presets = resolveSnoozePresets(localDate(2026, 4, 8, 10));
+    expect(presets.map((preset) => preset.id)).toEqual([
+      "hour",
+      "evening",
+      "tomorrow",
+      "next-week",
+    ]);
+    expect(presets.find((preset) => preset.id === "evening")?.label).toBe("This evening");
+    expect(
+      new Date(presets.find((preset) => preset.id === "tomorrow")!.snoozedUntil).getHours(),
+    ).toBe(9);
+  });
+
+  it("drops the evening choice once evening is near or past", () => {
+    expect(resolveSnoozePresets(localDate(2026, 4, 8, 17, 30)).map((preset) => preset.id)).toEqual([
+      "hour",
+      "tomorrow",
+      "next-week",
+    ]);
+  });
+
+  it("puts next week on the following Monday", () => {
+    const nextWeek = new Date(
+      resolveSnoozePresets(localDate(2026, 4, 6, 10)).find((preset) => preset.id === "next-week")!
+        .snoozedUntil,
+    );
+    expect(nextWeek.getDay()).toBe(1);
+    expect(nextWeek.getDate()).toBe(13);
+  });
+});
diff --git a/packages/contracts/src/baseSchemas.ts b/packages/contracts/src/baseSchemas.ts
index a8fa565cef4..9a63f22c9ef 100644
--- a/packages/contracts/src/baseSchemas.ts
+++ b/packages/contracts/src/baseSchemas.ts
@@ -1,4 +1,5 @@
 import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 import * as Schema from "effect/Schema";
 import * as SchemaTransformation from "effect/SchemaTransformation";
 
@@ -20,6 +21,30 @@ export const PortSchema = Schema.Int.check(Schema.isBetween({ minimum: 1, maximu
 export const IsoDateTime = Schema.String;
 export type IsoDateTime = typeof IsoDateTime.Type;
 
+/**
+ * Wire codec for server→client arrays whose element unions grow over time
+ * (new literal members, new struct variants). Decoding drops elements the
+ * current build cannot decode instead of failing the whole payload — a client
+ * has to keep decoding configs sent by servers newer than itself, and
+ * rejecting the payload would take down the connection over data the client
+ * couldn't act on anyway. Encoding is the plain array encoding.
+ */
+export const ForwardCompatibleArray = <Element extends Schema.Top>(element: Element) => {
+  const decodeElement = Schema.decodeUnknownOption(element as never);
+  return Schema.Array(Schema.Unknown).pipe(
+    Schema.decodeTo(
+      Schema.Array(element),
+      SchemaTransformation.transform<ReadonlyArray<Element["Encoded"]>, ReadonlyArray<unknown>>({
+        decode: (values) =>
+          values.filter((value) => Option.isSome(decodeElement(value))) as ReadonlyArray<
+            Element["Encoded"]
+          >,
+        encode: (values) => values,
+      }),
+    ),
+  );
+};
+
 /**
  * Construct a branded identifier. Enforces non-empty trimmed strings
  */
diff --git a/packages/contracts/src/environment.ts b/packages/contracts/src/environment.ts
index 5d4238994fb..b49860c6388 100644
--- a/packages/contracts/src/environment.ts
+++ b/packages/contracts/src/environment.ts
@@ -20,9 +20,9 @@ export const ExecutionEnvironmentPlatform = Schema.Struct({
 });
 export type ExecutionEnvironmentPlatform = typeof ExecutionEnvironmentPlatform.Type;
 
-/** How a server can replace itself with another version when asked over RPC:
-    "boot-service" rewrites the systemd user unit and restarts it; "respawn"
-    installs the target version and respawns the foreground process. */
+/** How a server can replace itself with another version when asked over RPC.
+    New servers only advertise the stable launcher-backed "boot-service" path;
+    "respawn" remains decodable for compatibility with older servers. */
 export const ServerSelfUpdateMethod = Schema.Literals(["boot-service", "respawn"]);
 export type ServerSelfUpdateMethod = typeof ServerSelfUpdateMethod.Type;
 
diff --git a/packages/contracts/src/keybindings.test.ts b/packages/contracts/src/keybindings.test.ts
index 33ecd38039f..ec8c839be95 100644
--- a/packages/contracts/src/keybindings.test.ts
+++ b/packages/contracts/src/keybindings.test.ts
@@ -20,6 +20,7 @@ const decode = <S extends Schema.Top>(
   >;
 
 const decodeResolvedRule = Schema.decodeUnknownEffect(ResolvedKeybindingRule as never);
+const encodeResolvedKeybindings = Schema.encodeEffect(ResolvedKeybindingsConfig);
 
 it.effect("parses keybinding rules", () =>
   Effect.gen(function* () {
@@ -59,6 +60,18 @@ it.effect("parses keybinding rules", () =>
     });
     assert.strictEqual(parsedCommandPalette.command, "commandPalette.toggle");
 
+    const parsedFilePicker = yield* decode(KeybindingRule, {
+      key: "mod+p",
+      command: "filePicker.toggle",
+    });
+    assert.strictEqual(parsedFilePicker.command, "filePicker.toggle");
+
+    const parsedProjectSearch = yield* decode(KeybindingRule, {
+      key: "mod+shift+f",
+      command: "projectSearch.toggle",
+    });
+    assert.strictEqual(parsedProjectSearch.command, "projectSearch.toggle");
+
     const parsedLocal = yield* decode(KeybindingRule, {
       key: "mod+shift+n",
       command: "chat.newLocal",
@@ -173,6 +186,70 @@ it.effect("parses resolved keybindings arrays", () =>
   }),
 );
 
+const shortcut = {
+  key: "p",
+  metaKey: false,
+  ctrlKey: false,
+  shiftKey: false,
+  altKey: false,
+  modKey: true,
+};
+
+it.effect("drops resolved rules with commands this build does not know", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decode(ResolvedKeybindingsConfig, [
+      { command: "terminal.toggle", shortcut },
+      { command: "someFuture.toggle", shortcut },
+      { command: "filePicker.toggle", shortcut },
+    ]);
+    assert.deepEqual(
+      parsed.map((rule) => rule.command),
+      ["terminal.toggle", "filePicker.toggle"],
+    );
+  }),
+);
+
+it.effect("drops resolved rules with unknown when-node types", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decode(ResolvedKeybindingsConfig, [
+      {
+        command: "terminal.toggle",
+        shortcut,
+        whenAst: { type: "xor", left: 1, right: 2 },
+      },
+      { command: "terminal.split", shortcut },
+    ]);
+    assert.deepEqual(
+      parsed.map((rule) => rule.command),
+      ["terminal.split"],
+    );
+  }),
+);
+
+it.effect("drops malformed resolved rule entries", () =>
+  Effect.gen(function* () {
+    const parsed = yield* decode(ResolvedKeybindingsConfig, [
+      "garbage",
+      { command: "terminal.toggle", shortcut },
+      null,
+    ]);
+    assert.deepEqual(
+      parsed.map((rule) => rule.command),
+      ["terminal.toggle"],
+    );
+  }),
+);
+
+it.effect("encodes resolved keybindings to the plain wire shape", () =>
+  Effect.gen(function* () {
+    const rules = [{ command: "terminal.toggle" as const, shortcut }];
+    const encoded = yield* encodeResolvedKeybindings(rules);
+    assert.deepEqual(encoded, rules);
+    const roundTripped = yield* decode(ResolvedKeybindingsConfig, encoded);
+    assert.deepEqual(roundTripped, rules);
+  }),
+);
+
 it.effect("drops unknown fields in resolved keybinding rules", () =>
   decodeResolvedRule({
     command: "terminal.toggle",
diff --git a/packages/contracts/src/keybindings.ts b/packages/contracts/src/keybindings.ts
index d966c1e7e61..88867bd8a9c 100644
--- a/packages/contracts/src/keybindings.ts
+++ b/packages/contracts/src/keybindings.ts
@@ -1,5 +1,5 @@
 import * as Schema from "effect/Schema";
-import { TrimmedString } from "./baseSchemas.ts";
+import { ForwardCompatibleArray, TrimmedString } from "./baseSchemas.ts";
 
 export const MAX_KEYBINDING_VALUE_LENGTH = 64;
 export const MAX_KEYBINDING_WHEN_LENGTH = 256;
@@ -63,6 +63,8 @@ const STATIC_KEYBINDING_COMMANDS = [
   "preview.zoomOut",
   "preview.resetZoom",
   "commandPalette.toggle",
+  "filePicker.toggle",
+  "projectSearch.toggle",
   "composer.stash",
   "chat.new",
   "chat.newLocal",
@@ -153,7 +155,14 @@ export const ResolvedKeybindingRule = Schema.Struct({
 }).annotate({ parseOptions: { onExcessProperty: "ignore" } });
 export type ResolvedKeybindingRule = typeof ResolvedKeybindingRule.Type;
 
-export const ResolvedKeybindingsConfig = Schema.Array(ResolvedKeybindingRule).check(
+/**
+ * The command set grows over time, so a client may receive rules it cannot
+ * represent (a command or `when` node added after that client shipped).
+ * Decoding drops those rules instead of failing the whole payload —
+ * rejecting the config would take down the connection over a shortcut the
+ * client couldn't dispatch anyway.
+ */
+export const ResolvedKeybindingsConfig = ForwardCompatibleArray(ResolvedKeybindingRule).check(
   Schema.isMaxLength(MAX_KEYBINDINGS_COUNT),
 );
 export type ResolvedKeybindingsConfig = typeof ResolvedKeybindingsConfig.Type;
diff --git a/packages/contracts/src/project.test.ts b/packages/contracts/src/project.test.ts
index ea9d5a90e7c..8e6771cba88 100644
--- a/packages/contracts/src/project.test.ts
+++ b/packages/contracts/src/project.test.ts
@@ -3,10 +3,40 @@ import { describe, expect, it } from "vite-plus/test";
 
 import {
   ProjectReadFileError,
+  ProjectSearchContentsError,
+  ProjectSearchContentsInput,
   ProjectSearchEntriesError,
+  ProjectSearchEntriesInput,
   ProjectWriteFileError,
 } from "./project.ts";
 
+const decodeSearchEntriesInput = Schema.decodeUnknownSync(ProjectSearchEntriesInput);
+const decodeSearchContentsInput = Schema.decodeUnknownSync(ProjectSearchContentsInput);
+
+describe("project search inputs", () => {
+  it("allows an empty entries query for bounded frecency browsing", () => {
+    const decoded = decodeSearchEntriesInput({
+      cwd: "/workspace",
+      query: "   ",
+      limit: 10,
+      kind: "file",
+    });
+    expect(decoded.query).toBe("");
+  });
+
+  it("preserves whitespace in content search queries", () => {
+    const decoded = decodeSearchContentsInput({
+      cwd: "/workspace",
+      query: " foo ",
+      limit: 10,
+      caseSensitive: false,
+      wholeWord: false,
+      useRegex: false,
+    });
+    expect(decoded.query).toBe(" foo ");
+  });
+});
+
 describe("project RPC errors", () => {
   it("derives stable messages from structured request context while retaining causes", () => {
     const cause = new Error("sensitive platform detail");
@@ -39,6 +69,18 @@ describe("project RPC errors", () => {
     expect(readError.message).toBe("Failed to read workspace file 'src/index.ts' in '/workspace'.");
     expect(readError.message).not.toContain(cause.message);
     expect(readError.cause).toBe(cause);
+
+    const contentSearchError = new ProjectSearchContentsError({
+      cwd: "/workspace",
+      queryLength: "authorization: Bearer secret-token".length,
+      limit: 100,
+      failure: "search_index_search_failed",
+      cause,
+    });
+    expect(contentSearchError.message).toBe("Failed to search workspace contents in '/workspace'.");
+    expect(contentSearchError.message).not.toContain(cause.message);
+    expect(contentSearchError).not.toHaveProperty("query");
+    expect(contentSearchError.cause).toBe(cause);
   });
 
   it("decodes legacy message-only errors during rolling upgrades", () => {
diff --git a/packages/contracts/src/project.ts b/packages/contracts/src/project.ts
index d59b9770ad3..a1b11df73b2 100644
--- a/packages/contracts/src/project.ts
+++ b/packages/contracts/src/project.ts
@@ -1,19 +1,29 @@
 import * as Schema from "effect/Schema";
-import { NonNegativeInt, PositiveInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
+import {
+  NonNegativeInt,
+  PositiveInt,
+  TrimmedNonEmptyString,
+  TrimmedString,
+} from "./baseSchemas.ts";
 
 const PROJECT_SEARCH_ENTRIES_MAX_LIMIT = 200;
+const PROJECT_SEARCH_CONTENTS_MAX_LIMIT = 500;
 const PROJECT_WRITE_FILE_PATH_MAX_LENGTH = 512;
 const PROJECT_READ_FILE_PATH_MAX_LENGTH = 512;
 
+export const ProjectEntryKind = Schema.Literals(["file", "directory"]);
+export type ProjectEntryKind = typeof ProjectEntryKind.Type;
+
 export const ProjectSearchEntriesInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
-  query: TrimmedNonEmptyString.check(Schema.isMaxLength(256)),
+  // An empty query is a bounded browse: the index returns frecency-ordered
+  // entries, which the file picker uses for its initial results.
+  query: TrimmedString.check(Schema.isMaxLength(256)),
   limit: PositiveInt.check(Schema.isLessThanOrEqualTo(PROJECT_SEARCH_ENTRIES_MAX_LIMIT)),
+  kind: Schema.optional(ProjectEntryKind),
 });
 export type ProjectSearchEntriesInput = typeof ProjectSearchEntriesInput.Type;
 
-const ProjectEntryKind = Schema.Literals(["file", "directory"]);
-
 export const ProjectEntry = Schema.Struct({
   path: TrimmedNonEmptyString,
   kind: ProjectEntryKind,
@@ -26,6 +36,39 @@ export const ProjectSearchEntriesResult = Schema.Struct({
 });
 export type ProjectSearchEntriesResult = typeof ProjectSearchEntriesResult.Type;
 
+export const ProjectSearchContentsInput = Schema.Struct({
+  cwd: TrimmedNonEmptyString,
+  // Whitespace is significant in content queries (" foo", regex trailing
+  // spaces), so the query is deliberately not trimmed on the wire.
+  query: Schema.String.check(Schema.isNonEmpty(), Schema.isMaxLength(256)),
+  limit: PositiveInt.check(Schema.isLessThanOrEqualTo(PROJECT_SEARCH_CONTENTS_MAX_LIMIT)),
+  caseSensitive: Schema.Boolean,
+  wholeWord: Schema.Boolean,
+  useRegex: Schema.Boolean,
+});
+export type ProjectSearchContentsInput = typeof ProjectSearchContentsInput.Type;
+
+export const ProjectContentMatchRange = Schema.Struct({
+  start: NonNegativeInt,
+  end: NonNegativeInt,
+});
+export type ProjectContentMatchRange = typeof ProjectContentMatchRange.Type;
+
+export const ProjectContentMatch = Schema.Struct({
+  path: TrimmedNonEmptyString,
+  lineNumber: PositiveInt,
+  lineContent: Schema.String,
+  matchRanges: Schema.Array(ProjectContentMatchRange),
+});
+export type ProjectContentMatch = typeof ProjectContentMatch.Type;
+
+export const ProjectSearchContentsResult = Schema.Struct({
+  matches: Schema.Array(ProjectContentMatch),
+  truncated: Schema.Boolean,
+  regexFallbackError: Schema.optional(Schema.String),
+});
+export type ProjectSearchContentsResult = typeof ProjectSearchContentsResult.Type;
+
 export const ProjectListEntriesInput = Schema.Struct({
   cwd: TrimmedNonEmptyString,
 });
@@ -94,6 +137,37 @@ export class ProjectSearchEntriesError extends Schema.TaggedErrorClass<ProjectSe
   }
 }
 
+export class ProjectSearchContentsError extends Schema.TaggedErrorClass<ProjectSearchContentsError>()(
+  "ProjectSearchContentsError",
+  {
+    cwd: Schema.optional(TrimmedNonEmptyString),
+    queryLength: Schema.optional(NonNegativeInt),
+    limit: Schema.optional(PositiveInt),
+    failure: Schema.optional(ProjectEntriesFailure),
+    normalizedCwd: Schema.optional(TrimmedNonEmptyString),
+    timeout: Schema.optional(TrimmedNonEmptyString),
+    detail: Schema.optional(TrimmedNonEmptyString),
+    message: TrimmedNonEmptyString,
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  // @effect-diagnostics-next-line overriddenSchemaConstructor:off
+  constructor(
+    props: ProjectEntriesFailureContext & {
+      readonly cwd: string;
+      readonly queryLength: number;
+      readonly limit: number;
+    },
+  ) {
+    super({
+      ...props,
+      message:
+        decodedProjectErrorMessage(props) ??
+        `Failed to search workspace contents in '${props.cwd}'.`,
+    } as any);
+  }
+}
+
 export class ProjectListEntriesError extends Schema.TaggedErrorClass<ProjectListEntriesError>()(
   "ProjectListEntriesError",
   {
diff --git a/packages/contracts/src/relay.ts b/packages/contracts/src/relay.ts
index ff9a9e3ac61..52f7d7d4355 100644
--- a/packages/contracts/src/relay.ts
+++ b/packages/contracts/src/relay.ts
@@ -371,16 +371,34 @@ export class RelayEnvironmentLinkProofInvalidError extends Schema.TaggedErrorCla
   }
 }
 
+export const RelayEnvironmentConnectNotAuthorizedReason = Schema.Literals([
+  "client_proof_key_thumbprint_missing",
+  "environment_link_not_found",
+  "endpoint_provider_not_managed",
+  "managed_endpoint_allocation_not_found",
+  "managed_endpoint_base_domain_not_configured",
+  "managed_endpoint_allocation_not_ready",
+  "managed_endpoint_hostname_invalid",
+  "managed_endpoint_mismatch",
+]);
+export type RelayEnvironmentConnectNotAuthorizedReason =
+  typeof RelayEnvironmentConnectNotAuthorizedReason.Type;
+
 export class RelayEnvironmentConnectNotAuthorizedError extends Schema.TaggedErrorClass<RelayEnvironmentConnectNotAuthorizedError>()(
   "RelayEnvironmentConnectNotAuthorizedError",
   {
     code: Schema.Literal("environment_connect_not_authorized"),
+    // Optional so responses from relays deployed before the reason was
+    // threaded through still decode.
+    reason: Schema.optional(RelayEnvironmentConnectNotAuthorizedReason),
     traceId: TrimmedNonEmptyString,
   },
   { httpApiStatus: 403 },
 ) {
   override get message(): string {
-    return "Relay environment connection is not authorized";
+    return this.reason
+      ? `Relay environment connection is not authorized: ${this.reason}`
+      : "Relay environment connection is not authorized";
   }
 }
 
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index 17fbd57ddad..400011f8843 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -76,6 +76,9 @@ import {
   ProjectReadFileError,
   ProjectReadFileInput,
   ProjectReadFileResult,
+  ProjectSearchContentsError,
+  ProjectSearchContentsInput,
+  ProjectSearchContentsResult,
   ProjectSearchEntriesError,
   ProjectSearchEntriesInput,
   ProjectSearchEntriesResult,
@@ -166,6 +169,7 @@ export const WS_METHODS = {
   projectsRemove: "projects.remove",
   projectsListEntries: "projects.listEntries",
   projectsReadFile: "projects.readFile",
+  projectsSearchContents: "projects.searchContents",
   projectsSearchEntries: "projects.searchEntries",
   projectsWriteFile: "projects.writeFile",
 
@@ -438,6 +442,12 @@ export const WsProjectsSearchEntriesRpc = Rpc.make(WS_METHODS.projectsSearchEntr
   error: Schema.Union([ProjectSearchEntriesError, EnvironmentAuthorizationError]),
 });
 
+export const WsProjectsSearchContentsRpc = Rpc.make(WS_METHODS.projectsSearchContents, {
+  payload: ProjectSearchContentsInput,
+  success: ProjectSearchContentsResult,
+  error: Schema.Union([ProjectSearchContentsError, EnvironmentAuthorizationError]),
+});
+
 export const WsProjectsListEntriesRpc = Rpc.make(WS_METHODS.projectsListEntries, {
   payload: ProjectListEntriesInput,
   success: ProjectListEntriesResult,
@@ -801,6 +811,7 @@ export const WsRpcGroup = RpcGroup.make(
   WsSourceControlPublishRepositoryRpc,
   WsProjectsListEntriesRpc,
   WsProjectsReadFileRpc,
+  WsProjectsSearchContentsRpc,
   WsProjectsSearchEntriesRpc,
   WsProjectsWriteFileRpc,
   WsShellOpenInEditorRpc,
diff --git a/packages/contracts/src/server.test.ts b/packages/contracts/src/server.test.ts
index c906f86f4dc..eaf1578aae7 100644
--- a/packages/contracts/src/server.test.ts
+++ b/packages/contracts/src/server.test.ts
@@ -1,9 +1,11 @@
 import * as Schema from "effect/Schema";
 import { describe, expect, it } from "vite-plus/test";
 
-import { ServerProvider } from "./server.ts";
+import { ServerConfig, ServerProvider, ServerUpsertKeybindingResult } from "./server.ts";
 
 const decodeServerProvider = Schema.decodeUnknownSync(ServerProvider);
+const decodeUpsertKeybindingResult = Schema.decodeUnknownSync(ServerUpsertKeybindingResult);
+const decodeAvailableEditors = Schema.decodeUnknownSync(ServerConfig.fields.availableEditors);
 
 describe("ServerProvider", () => {
   it("defaults capability arrays when decoding provider snapshots", () => {
@@ -71,4 +73,50 @@ describe("ServerProvider", () => {
 
     expect(parsed.continuation?.groupKey).toBe("codex:home:/Users/julius/.codex");
   });
+
+  it("decodes optional legacy model metadata", () => {
+    const parsed = decodeServerProvider({
+      instanceId: "codex",
+      driver: "codex",
+      enabled: true,
+      installed: true,
+      version: "1.0.0",
+      status: "ready",
+      auth: { status: "authenticated" },
+      checkedAt: "2026-04-10T00:00:00.000Z",
+      models: [
+        {
+          slug: "gpt-5.4",
+          name: "GPT-5.4",
+          isCustom: false,
+          isLegacy: true,
+          capabilities: null,
+        },
+      ],
+    });
+
+    expect(parsed.models[0]?.isLegacy).toBe(true);
+  });
+});
+
+describe("server config forward compatibility", () => {
+  it("drops config issues with kinds this build does not know", () => {
+    const parsed = decodeUpsertKeybindingResult({
+      keybindings: [],
+      issues: [
+        { kind: "keybindings.invalid-entry", message: "Bad entry", index: 2 },
+        { kind: "keybindings.future-issue", message: "From a newer server" },
+      ],
+    });
+
+    expect(parsed.issues).toEqual([
+      { kind: "keybindings.invalid-entry", message: "Bad entry", index: 2 },
+    ]);
+  });
+
+  it("drops editor ids this build does not know", () => {
+    const parsed = decodeAvailableEditors(["zed", "some-future-editor", "vscode"]);
+
+    expect(parsed).toEqual(["zed", "vscode"]);
+  });
 });
diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts
index e083523bbdf..fc322db6206 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -3,6 +3,7 @@ import * as Schema from "effect/Schema";
 import { ExecutionEnvironmentDescriptor, ServerSelfUpdateMethod } from "./environment.ts";
 import { ServerAuthDescriptor } from "./auth.ts";
 import {
+  ForwardCompatibleArray,
   IsoDateTime,
   NonNegativeInt,
   PositiveInt,
@@ -38,7 +39,9 @@ export const ServerConfigIssue = Schema.Union([
 ]);
 export type ServerConfigIssue = typeof ServerConfigIssue.Type;
 
-const ServerConfigIssues = Schema.Array(ServerConfigIssue);
+// Issue kinds grow over time; older clients must not fail the whole config
+// decode over a kind they cannot render.
+const ServerConfigIssues = ForwardCompatibleArray(ServerConfigIssue);
 
 export const ServerProviderState = Schema.Literals(["ready", "warning", "error", "disabled"]);
 export type ServerProviderState = typeof ServerProviderState.Type;
@@ -65,6 +68,7 @@ export const ServerProviderModel = Schema.Struct({
   subProvider: Schema.optional(TrimmedNonEmptyString),
   isCustom: Schema.Boolean,
   isDefault: Schema.optional(Schema.Boolean),
+  isLegacy: Schema.optional(Schema.Boolean),
   capabilities: Schema.NullOr(ModelCapabilities),
 });
 export type ServerProviderModel = typeof ServerProviderModel.Type;
@@ -417,7 +421,9 @@ export const ServerConfig = Schema.Struct({
   keybindings: ResolvedKeybindingsConfig,
   issues: ServerConfigIssues,
   providers: ServerProviders,
-  availableEditors: Schema.Array(EditorId),
+  // Editor ids grow over time; drop ones this build does not know rather than
+  // failing the whole config decode.
+  availableEditors: ForwardCompatibleArray(EditorId),
   observability: ServerObservability,
   settings: ServerSettings,
   /** Whether shell subscriptions can emit an opt-in catch-up completion marker. */
@@ -516,9 +522,21 @@ export const ServerConfigStreamEvent = Schema.Union([
 ]);
 export type ServerConfigStreamEvent = typeof ServerConfigStreamEvent.Type;
 
+/** Terminal selection recorded by the service launcher for one update. */
+export const ServerSelfUpdateOutcome = Schema.Struct({
+  id: TrimmedNonEmptyString,
+  fromVersion: TrimmedNonEmptyString,
+  targetVersion: TrimmedNonEmptyString,
+  status: Schema.Literals(["committed", "rolled-back", "failed"]),
+  reason: Schema.optionalKey(TrimmedNonEmptyString),
+});
+export type ServerSelfUpdateOutcome = typeof ServerSelfUpdateOutcome.Type;
+
 export const ServerLifecycleReadyPayload = Schema.Struct({
   at: IsoDateTime,
   environment: ExecutionEnvironmentDescriptor,
+  /** Present when this process resumed a launcher-managed update. */
+  updateOutcome: Schema.optionalKey(ServerSelfUpdateOutcome),
 });
 export type ServerLifecycleReadyPayload = typeof ServerLifecycleReadyPayload.Type;
 
@@ -589,6 +607,8 @@ export type ServerSelfUpdateInput = typeof ServerSelfUpdateInput.Type;
 export const ServerSelfUpdateResult = Schema.Struct({
   targetVersion: TrimmedNonEmptyString,
   method: ServerSelfUpdateMethod,
+  /** Launcher-generated correlation ID. Absent when talking to older servers. */
+  updateId: Schema.optionalKey(TrimmedNonEmptyString),
 });
 export type ServerSelfUpdateResult = typeof ServerSelfUpdateResult.Type;
 
diff --git a/packages/shared/src/keybindings.ts b/packages/shared/src/keybindings.ts
index 0688cf07254..6add9f47844 100644
--- a/packages/shared/src/keybindings.ts
+++ b/packages/shared/src/keybindings.ts
@@ -35,6 +35,8 @@ export const DEFAULT_KEYBINDINGS: ReadonlyArray<KeybindingRule> = [
   { key: "mod+-", command: "preview.zoomOut", when: "previewFocus" },
   { key: "mod+0", command: "preview.resetZoom", when: "previewFocus" },
   { key: "mod+k", command: "commandPalette.toggle", when: "!terminalFocus" },
+  { key: "mod+p", command: "filePicker.toggle", when: "!terminalFocus" },
+  { key: "mod+shift+f", command: "projectSearch.toggle", when: "!terminalFocus" },
   { key: "mod+s", command: "composer.stash", when: "!terminalFocus" },
   { key: "mod+n", command: "chat.new", when: "!terminalFocus" },
   { key: "mod+shift+o", command: "chat.new", when: "!terminalFocus" },
diff --git a/packages/shared/src/projectFavicon.test.ts b/packages/shared/src/projectFavicon.test.ts
index 0011b2fc7c9..1df17cc7fe5 100644
--- a/packages/shared/src/projectFavicon.test.ts
+++ b/packages/shared/src/projectFavicon.test.ts
@@ -1,8 +1,32 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { isProjectFaviconFallbackUrl, PROJECT_FAVICON_FALLBACK_MARKER } from "./projectFavicon.ts";
+import {
+  getProjectFaviconCacheKey,
+  isProjectFaviconFallbackUrl,
+  PROJECT_FAVICON_FALLBACK_MARKER,
+} from "./projectFavicon.ts";
 
 describe("project favicon", () => {
+  it("uses the project and versioned filename as the cache identity", () => {
+    const firstUrl = "https://environment.example/api/assets/first-signed-token/v1-20-favicon.svg";
+    const refreshedUrl =
+      "https://environment.example/api/assets/refreshed-signed-token/v1-20-favicon.svg";
+
+    expect(getProjectFaviconCacheKey("environment-1", "/workspace", firstUrl)).toBe(
+      getProjectFaviconCacheKey("environment-1", "/workspace", refreshedUrl),
+    );
+    expect(getProjectFaviconCacheKey("environment-1", "/workspace", firstUrl)).not.toBe(
+      getProjectFaviconCacheKey(
+        "environment-1",
+        "/workspace",
+        "https://environment.example/api/assets/refreshed-signed-token/v2-20-favicon.svg",
+      ),
+    );
+    expect(getProjectFaviconCacheKey("environment-1", "/workspace", firstUrl)).not.toBe(
+      getProjectFaviconCacheKey("environment-2", "/workspace", firstUrl),
+    );
+  });
+
   it("identifies fallback asset URLs by their dedicated filename", () => {
     expect(
       isProjectFaviconFallbackUrl(
diff --git a/packages/shared/src/projectFavicon.ts b/packages/shared/src/projectFavicon.ts
index 2e46429b6c1..eebc1a8a1b6 100644
--- a/packages/shared/src/projectFavicon.ts
+++ b/packages/shared/src/projectFavicon.ts
@@ -1,5 +1,22 @@
 export const PROJECT_FAVICON_FALLBACK_MARKER = "project-favicon-missing";
 
+export function getProjectFaviconCacheKey(
+  environmentId: string,
+  workspaceRoot: string,
+  url: string,
+) {
+  let revision = url;
+
+  try {
+    const pathname = new URL(url, "https://t3.invalid").pathname;
+    revision = pathname.slice(pathname.lastIndexOf("/") + 1);
+  } catch {
+    // Keep the full value as a safe fallback for malformed URLs.
+  }
+
+  return JSON.stringify([environmentId, workspaceRoot, revision]);
+}
+
 export function isProjectFaviconFallbackUrl(url: string | null | undefined): boolean {
   if (!url) return false;
 
diff --git a/packages/shared/src/schemaJson.test.ts b/packages/shared/src/schemaJson.test.ts
index c808a9b7c51..4a4d16da0b3 100644
--- a/packages/shared/src/schemaJson.test.ts
+++ b/packages/shared/src/schemaJson.test.ts
@@ -57,6 +57,15 @@ Done.`),
     expect(() => decodeLenientJson('{ "enabled": true,, }')).toThrow();
   });
 
+  it("preserves commas before brackets inside string values", () => {
+    // A comma inside a string value that happens to precede `}`/`]` must not
+    // be stripped as if it were a trailing comma.
+    expect(decodeLenientJson('{"note":"a,]"}')).toEqual({ note: "a,]" });
+    expect(decodeLenientJson('{"list":["x,}"]}')).toEqual({ list: ["x,}"] });
+    // Genuine trailing commas are still removed.
+    expect(decodeLenientJson('{"values":[1, 2,],}')).toEqual({ values: [1, 2] });
+  });
+
   it("formats schema failures with paths without exposing invalid values", () => {
     const decodeCredential = decodeJsonResult(Schema.Struct({ token: Schema.Number }));
     const decoded = decodeCredential('{"token":"credential=secret-value"}');
diff --git a/packages/shared/src/schemaJson.ts b/packages/shared/src/schemaJson.ts
index 04d26d9c229..77b1fa5d548 100644
--- a/packages/shared/src/schemaJson.ts
+++ b/packages/shared/src/schemaJson.ts
@@ -190,8 +190,14 @@ const parseLenientJsonGetter = SchemaGetter.onSome((input: string) => {
     (match, stringLiteral: string | undefined) => (stringLiteral ? match : ""),
   );
 
-  // Strip trailing commas before `}` or `]`.
-  stripped = stripped.replace(/,(\s*[}\]])/g, "$1");
+  // Strip trailing commas before `}` or `]`. The alternation preserves quoted
+  // strings so a comma inside a string value (e.g. `{"note":"a,]"}`) is not
+  // mistaken for a trailing comma and removed.
+  stripped = stripped.replace(
+    /("(?:[^"\\]|\\.)*")|,(\s*[}\]])/g,
+    (match, stringLiteral: string | undefined, bracket: string | undefined) =>
+      stringLiteral ? match : (bracket ?? ""),
+  );
 
   return decodeJsonString(stripped).pipe(
     Effect.map(Option.some),
diff --git a/packages/shared/src/semver.test.ts b/packages/shared/src/semver.test.ts
index 8cbbc150fc9..ed3e1896aaf 100644
--- a/packages/shared/src/semver.test.ts
+++ b/packages/shared/src/semver.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { compareSemverVersions, normalizeSemverVersion, satisfiesSemverRange } from "./semver.ts";
+import {
+  compareSemverVersions,
+  normalizeSemverVersion,
+  parseSemver,
+  satisfiesSemverRange,
+} from "./semver.ts";
 
 describe("semver helpers", () => {
   it("matches supported range groups", () => {
@@ -18,6 +23,25 @@ describe("semver helpers", () => {
     expect(normalizeSemverVersion("2.1")).toBe("2.1.0");
   });
 
+  it("normalizes and parses shorthand major-only versions", () => {
+    expect(normalizeSemverVersion("20")).toBe("20.0.0");
+    expect(normalizeSemverVersion("v18")).toBe("v18.0.0");
+    expect(normalizeSemverVersion("20-rc.1")).toBe("20.0.0-rc.1");
+    expect(parseSemver("20")).toEqual({ major: 20, minor: 0, patch: 0, prerelease: [] });
+  });
+
+  it("compares shorthand versions numerically instead of lexically", () => {
+    // Regression: "20" vs "9" previously fell back to string comparison, which
+    // ordered "20" before "9" ("2" < "9").
+    expect(compareSemverVersions("20", "9")).toBeGreaterThan(0);
+    expect(compareSemverVersions("18", "18.0.0")).toBe(0);
+  });
+
+  it("still rejects non-numeric shorthand and keeps empty input empty", () => {
+    expect(parseSemver("abc")).toBeNull();
+    expect(normalizeSemverVersion("")).toBe("");
+  });
+
   it("compares prerelease versions before stable versions", () => {
     expect(compareSemverVersions("2.1.111-beta.1", "2.1.111")).toBeLessThan(0);
   });
diff --git a/packages/shared/src/semver.ts b/packages/shared/src/semver.ts
index 1a73e33042f..a765b065fc6 100644
--- a/packages/shared/src/semver.ts
+++ b/packages/shared/src/semver.ts
@@ -17,7 +17,12 @@ export function normalizeSemverVersion(version: string): string {
     }
   }
 
-  if (segments.length === 2) {
+  // Pad shorthand versions ("20" or "20.1") up to three segments so major-only
+  // and minor-only inputs parse and compare numerically. This matches
+  // satisfiesSemverRange, which already treats a missing minor/patch as 0. The
+  // length > 0 guard keeps empty/garbage input empty (parseSemver still
+  // rejects it), and inputs with more than three segments are left untouched.
+  while (segments.length > 0 && segments.length < 3) {
     segments.push("0");
   }
 
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 7328b07b226..24722edd5c5 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -35,19 +35,19 @@ catalogs:
       version: 0.2.2
 
 overrides:
-  '@clerk/backend': 3.13.0
-  '@clerk/clerk-js': 6.25.7
+  '@clerk/backend': 3.14.0
+  '@clerk/clerk-js': 6.25.12
   '@clerk/clerk-js>@base-org/account': '-'
   '@clerk/clerk-js>@coinbase/wallet-sdk': '-'
   '@clerk/clerk-js>@solana/wallet-adapter-base': '-'
   '@clerk/clerk-js>@solana/wallet-adapter-react': '-'
   '@clerk/clerk-js>@solana/wallet-standard': '-'
   '@clerk/clerk-js>@wallet-standard/core': '-'
-  '@clerk/electron': 0.0.18
+  '@clerk/electron': 0.0.24
   '@clerk/electron-passkeys': 0.0.3
-  '@clerk/expo': 4.0.2
-  '@clerk/react': 6.12.7
-  '@clerk/shared': 4.25.7
+  '@clerk/expo': 4.1.2
+  '@clerk/react': 6.12.9
+  '@clerk/shared': 4.25.9
   '@effect/atom-react': 4.0.0-beta.102
   '@effect/platform-bun': 4.0.0-beta.102
   '@effect/platform-node': 4.0.0-beta.102
@@ -111,8 +111,8 @@ importers:
   apps/desktop:
     dependencies:
       '@clerk/electron':
-        specifier: 0.0.18
-        version: 0.0.18(@clerk/electron-passkeys@0.0.3)(electron-store@8.2.0)(electron@41.5.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        specifier: 0.0.24
+        version: 0.0.24(@clerk/electron-passkeys@0.0.3)(electron-store@8.2.0)(electron@41.5.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@clerk/electron-passkeys':
         specifier: 0.0.3
         version: 0.0.3
@@ -197,8 +197,8 @@ importers:
         specifier: ^0.7.1
         version: 0.7.1(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3)
       '@clerk/expo':
-        specifier: 4.0.2
-        version: 4.0.2(expo-auth-session@56.0.14(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3))(expo-constants@56.0.18)(expo-crypto@56.0.4(expo@56.0.12))(expo-secure-store@56.0.4(expo@56.0.12))(expo-web-browser@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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)))(expo@56.0.12)(react-dom@19.2.3(react@19.2.3))(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3)(typescript@6.0.3)
+        specifier: 4.1.2
+        version: 4.1.2(expo-auth-session@56.0.14(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3))(expo-constants@56.0.18)(expo-crypto@56.0.4(expo@56.0.12))(expo-secure-store@56.0.4(expo@56.0.12))(expo-web-browser@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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)))(expo@56.0.12)(react-dom@19.2.3(react@19.2.3))(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3)(typescript@6.0.3)
       '@effect/atom-react':
         specifier: 4.0.0-beta.102
         version: 4.0.0-beta.102(effect@4.0.0-beta.102(patch_hash=71215759e1ac0a7f65d7b75d816986687ae6c3a6cba02d928d184ca71790d488))(react@19.2.3)(scheduler@0.27.0)
@@ -514,11 +514,11 @@ importers:
         specifier: ^1.4.1
         version: 1.5.0(@types/react@19.2.16)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@clerk/electron':
-        specifier: 0.0.18
-        version: 0.0.18(@clerk/electron-passkeys@0.0.3)(electron-store@8.2.0)(electron@41.5.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        specifier: 0.0.24
+        version: 0.0.24(@clerk/electron-passkeys@0.0.3)(electron-store@8.2.0)(electron@41.5.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@clerk/react':
-        specifier: 6.12.7
-        version: 6.12.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        specifier: 6.12.9
+        version: 6.12.9(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@dnd-kit/core':
         specifier: ^6.3.1
         version: 6.3.1(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
@@ -579,12 +579,6 @@ importers:
       '@tanstack/react-router':
         specifier: ^1.160.2
         version: 1.170.10(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@xterm/addon-fit':
-        specifier: ^0.11.0
-        version: 0.11.0
-      '@xterm/xterm':
-        specifier: ^6.0.0
-        version: 6.0.0
       class-variance-authority:
         specifier: ^0.7.1
         version: 0.7.1
@@ -677,8 +671,8 @@ importers:
   infra/relay:
     dependencies:
       '@clerk/backend':
-        specifier: 3.13.0
-        version: 3.13.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+        specifier: 3.14.0
+        version: 3.14.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@effect/sql-pg':
         specifier: 4.0.0-beta.102
         version: 4.0.0-beta.102(effect@4.0.0-beta.102(patch_hash=71215759e1ac0a7f65d7b75d816986687ae6c3a6cba02d928d184ca71790d488))
@@ -1704,12 +1698,12 @@ packages:
     resolution: {integrity: sha512-EYlRokl8szrP9Z25qT5aepMdBjzBvHF9ZEhzIiUBc9guz/T31EqRgvD0QSgZcpE93xiwrr+OkB4nz0BZyF6fSA==}
     engines: {node: '>= 20.12.0'}
 
-  '@clerk/backend@3.13.0':
-    resolution: {integrity: sha512-kYOgeR48iXYypudpYITE0L2yxi4TeFXU+ISAOULlVgOcurw8qnm1/JEuK6Mr2IFUbRS9hcHk1HVO0Ceo0XmL8Q==}
+  '@clerk/backend@3.14.0':
+    resolution: {integrity: sha512-WsphTvDFHDuQilKI7dyVE5qmt7USu8qSrujAq6SqpEHbVFfNBfINDNuzxlF9M2skOTfHFfgiTE8Jjb1egIBGLg==}
     engines: {node: '>=20.9.0'}
 
-  '@clerk/clerk-js@6.25.7':
-    resolution: {integrity: sha512-GOnbEUzPKAdsdCodZsHhku2YloBBuwLGx5UP0VeezUj73wKLwlSYMlVPuntsJoY7c8+lVrMCY9LQWYVZ7VMLBw==}
+  '@clerk/clerk-js@6.25.12':
+    resolution: {integrity: sha512-N91mFKenMF5e+LRQ0NsqFb8bw+icbwnF8MzjzS4cux72xG4Gekh772tiLIetbURe44Srgjw5lj8jkWbt+yH/FA==}
     engines: {node: '>=20.9.0'}
 
   '@clerk/electron-passkeys-darwin-arm64@0.0.3':
@@ -1736,8 +1730,8 @@ packages:
     resolution: {integrity: sha512-OHhIe88qDL+FxyBalXdXNHAS5eEramr6Rerp+6iNkfkjqT8rx4hHNmfpmjg5/T1/am8QfknbOBZkqoXZlCrjPg==}
     engines: {node: '>=20.9.0'}
 
-  '@clerk/electron@0.0.18':
-    resolution: {integrity: sha512-0lWiITlTxCviglPfPSu+uhERnQyXroiWrSMRpZcEO3FgBt3bnrpfgZUrXW8iaLoUYJrFP2byF7bHJPRwEPVXEw==}
+  '@clerk/electron@0.0.24':
+    resolution: {integrity: sha512-xORO51KLzCqmRQ4IVsa+Amp1M5NjG28QnvsaRBq1v4CUEjH8vAXDKCPiPBKAE+HuQB6HUhzYmzUkyTw2FcDonw==}
     engines: {node: '>=20.9.0'}
     peerDependencies:
       '@clerk/electron-passkeys': 0.0.3
@@ -1753,8 +1747,8 @@ packages:
       react-dom:
         optional: true
 
-  '@clerk/expo@4.0.2':
-    resolution: {integrity: sha512-afBdV2bLRM55p5L7FoAGV/wCamLxXusjIBPmNo+TwAYabU0oUokMsm+0++xWDA0nxzMt/O08Oj+xAGEtE+Qvxg==}
+  '@clerk/expo@4.1.2':
+    resolution: {integrity: sha512-ZyGozbbizcGwEyK0CEXsPHnHnQoaa2CbTsXAqWBygzKEZyFjLjCHwQsQBKj6WgjAgn8mtw2ByIP9qLpItZffgw==}
     engines: {node: '>=20.9.0'}
     peerDependencies:
       '@clerk/expo-google-signin': '>=0.1.0'
@@ -1792,15 +1786,15 @@ packages:
       react-dom:
         optional: true
 
-  '@clerk/react@6.12.7':
-    resolution: {integrity: sha512-K8CK0tS7My/3RT5sAIJTjYgnH0xU+K4Jdnhi76xQdAY4agD/M07BbrBMWXEE0xUEDst2PqPfX660V1LRLOsxOQ==}
+  '@clerk/react@6.12.9':
+    resolution: {integrity: sha512-lQ1UOJhHGDweLCDf4IgT5r3rgkch1Gx21hNqK2/kOohJrJd/XM89fq2F7VK9Kg/Byc14TsfCh64Dm8ej2MyRWw==}
     engines: {node: '>=20.9.0'}
     peerDependencies:
       react: ^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0
       react-dom: ^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0
 
-  '@clerk/shared@4.25.7':
-    resolution: {integrity: sha512-FfBbDeFkxwDuz/2YcVs4DhyZ0VxnqNtdbO0Tn/lkLAiDvFFspWw+PDYqo7LQiBymEQaOQkb094dX21WWnZbmlA==}
+  '@clerk/shared@4.25.9':
+    resolution: {integrity: sha512-nw3maGzqPrwmUKjGffOM9Zvw24IyOllq0TkQGzsTfQX312WLu2u5CNvjKntMb6Ok6kXa1Zdc77zmPLn1/EAIFA==}
     engines: {node: '>=20.9.0'}
     peerDependencies:
       react: ^18.0.0 || ~19.0.3 || ~19.1.4 || ~19.2.3 || ~19.3.0-0
@@ -5178,12 +5172,6 @@ packages:
     resolution: {integrity: sha512-A9gOqLdi6cV4ibazAjcQufGj0B1y/vDqYrcuP6d/6x8P27gRS8643Dj9o1dEKtB6O7fwxb2FgBmJS2mX7gpvdw==}
     engines: {node: '>=14.6'}
 
-  '@xterm/addon-fit@0.11.0':
-    resolution: {integrity: sha512-jYcgT6xtVYhnhgxh3QgYDnnNMYTcf8ElbxxFzX0IZo+vabQqSPAjC3c1wJrKB5E19VwQei89QCiZZP86DCPF7g==}
-
-  '@xterm/xterm@6.0.0':
-    resolution: {integrity: sha512-TQwDdQGtwwDt+2cgKDLn0IRaSxYu1tSUjgKarSDkUM0ZNiSRXFpjxEsvc/Zgc5kq5omJ+V0a8/kIM2WD3sMOYg==}
-
   '@yuuang/ffi-rs-android-arm64@1.3.2':
     resolution: {integrity: sha512-eDYLT0kVBkp7e2BwdRDmt6N1rkeDPUHDefk3ZX0/nok+GLsqfy1WBoSL3Yg7HVXN1EyW8OBVc2uK8Zq8HbmaSA==}
     engines: {node: '>= 12'}
@@ -11534,18 +11522,18 @@ snapshots:
       fast-wrap-ansi: 0.2.2
       sisteransi: 1.0.5
 
-  '@clerk/backend@3.13.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+  '@clerk/backend@3.14.0(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
-      '@clerk/shared': 4.25.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@clerk/shared': 4.25.9(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       standardwebhooks: 1.0.0
       tslib: 2.8.1
     transitivePeerDependencies:
       - react
       - react-dom
 
-  '@clerk/clerk-js@6.25.7(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+  '@clerk/clerk-js@6.25.12(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
-      '@clerk/shared': 4.25.7(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@clerk/shared': 4.25.9(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@stripe/stripe-js': 5.6.0
       '@swc/helpers': 0.5.21
       '@tanstack/query-core': 5.100.14
@@ -11560,9 +11548,9 @@ snapshots:
       - react
       - react-dom
 
-  '@clerk/clerk-js@6.25.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+  '@clerk/clerk-js@6.25.12(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
-      '@clerk/shared': 4.25.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@clerk/shared': 4.25.9(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       '@stripe/stripe-js': 5.6.0
       '@swc/helpers': 0.5.21
       '@tanstack/query-core': 5.100.14
@@ -11596,11 +11584,11 @@ snapshots:
       '@clerk/electron-passkeys-win32-arm64-msvc': 0.0.3
       '@clerk/electron-passkeys-win32-x64-msvc': 0.0.3
 
-  '@clerk/electron@0.0.18(@clerk/electron-passkeys@0.0.3)(electron-store@8.2.0)(electron@41.5.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+  '@clerk/electron@0.0.24(@clerk/electron-passkeys@0.0.3)(electron-store@8.2.0)(electron@41.5.0)(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
-      '@clerk/clerk-js': 6.25.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@clerk/react': 6.12.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
-      '@clerk/shared': 4.25.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@clerk/clerk-js': 6.25.12(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@clerk/react': 6.12.9(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@clerk/shared': 4.25.9(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       electron: 41.5.0
       react: 19.2.6
       tslib: 2.8.1
@@ -11609,11 +11597,11 @@ snapshots:
       electron-store: 8.2.0
       react-dom: 19.2.6(react@19.2.6)
 
-  '@clerk/expo@4.0.2(expo-auth-session@56.0.14(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3))(expo-constants@56.0.18)(expo-crypto@56.0.4(expo@56.0.12))(expo-secure-store@56.0.4(expo@56.0.12))(expo-web-browser@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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)))(expo@56.0.12)(react-dom@19.2.3(react@19.2.3))(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3)(typescript@6.0.3)':
+  '@clerk/expo@4.1.2(expo-auth-session@56.0.14(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3))(expo-constants@56.0.18)(expo-crypto@56.0.4(expo@56.0.12))(expo-secure-store@56.0.4(expo@56.0.12))(expo-web-browser@56.0.5(expo@56.0.12)(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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)))(expo@56.0.12)(react-dom@19.2.3(react@19.2.3))(react-native@0.85.3(@babel/core@7.29.7)(@react-native/metro-config@0.85.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))(react@19.2.3)(typescript@6.0.3)':
     dependencies:
-      '@clerk/clerk-js': 6.25.7(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@clerk/react': 6.12.7(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      '@clerk/shared': 4.25.7(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@clerk/clerk-js': 6.25.12(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@clerk/react': 6.12.9(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@clerk/shared': 4.25.9(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@expo/config-plugins': 56.0.9(typescript@6.0.3)
       base-64: 1.0.0
       expo: 56.0.12(8895228379997a2a064f9644cda56ed0)
@@ -11632,21 +11620,21 @@ snapshots:
       - supports-color
       - typescript
 
-  '@clerk/react@6.12.7(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+  '@clerk/react@6.12.9(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
-      '@clerk/shared': 4.25.7(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      '@clerk/shared': 4.25.9(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
       tslib: 2.8.1
 
-  '@clerk/react@6.12.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+  '@clerk/react@6.12.9(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
-      '@clerk/shared': 4.25.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
+      '@clerk/shared': 4.25.9(react-dom@19.2.6(react@19.2.6))(react@19.2.6)
       react: 19.2.6
       react-dom: 19.2.6(react@19.2.6)
       tslib: 2.8.1
 
-  '@clerk/shared@4.25.7(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
+  '@clerk/shared@4.25.9(react-dom@19.2.3(react@19.2.3))(react@19.2.3)':
     dependencies:
       '@tanstack/query-core': 5.100.14
       dequal: 2.0.3
@@ -11656,7 +11644,7 @@ snapshots:
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
 
-  '@clerk/shared@4.25.7(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
+  '@clerk/shared@4.25.9(react-dom@19.2.6(react@19.2.6))(react@19.2.6)':
     dependencies:
       '@tanstack/query-core': 5.100.14
       dequal: 2.0.3
@@ -15314,10 +15302,6 @@ snapshots:
 
   '@xmldom/xmldom@0.9.10': {}
 
-  '@xterm/addon-fit@0.11.0': {}
-
-  '@xterm/xterm@6.0.0': {}
-
   '@yuuang/ffi-rs-android-arm64@1.3.2':
     optional: true
 
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index d41e50e8784..79736c894e1 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -23,13 +23,13 @@ allowBuilds:
   workerd: false
 
 catalog:
-  "@clerk/backend": 3.13.0
-  "@clerk/clerk-js": 6.25.7
-  "@clerk/electron": 0.0.18
+  "@clerk/backend": 3.14.0
+  "@clerk/clerk-js": 6.25.12
+  "@clerk/electron": 0.0.24
   "@clerk/electron-passkeys": 0.0.3
-  "@clerk/expo": 4.0.2
-  "@clerk/react": 6.12.7
-  "@clerk/shared": 4.25.7
+  "@clerk/expo": 4.1.2
+  "@clerk/react": 6.12.9
+  "@clerk/shared": 4.25.9
   "@effect/atom-react": 4.0.0-beta.102
   "@effect/openapi-generator": 4.0.0-beta.102
   "@effect/platform-bun": 4.0.0-beta.102
@@ -52,12 +52,12 @@ catalog:
   yaml: ^2.9.0
 
 minimumReleaseAgeExclude:
-  - "@clerk/backend@3.13.0"
-  - "@clerk/clerk-js@6.25.7"
-  - "@clerk/electron@0.0.18"
-  - "@clerk/expo@4.0.2"
-  - "@clerk/react@6.12.7"
-  - "@clerk/shared@4.25.7"
+  - "@clerk/backend@3.14.0"
+  - "@clerk/clerk-js@6.25.12"
+  - "@clerk/electron@0.0.24"
+  - "@clerk/expo@4.1.2"
+  - "@clerk/react@6.12.9"
+  - "@clerk/shared@4.25.9"
   - "@distilled.cloud/aws@0.30.2"
   - "@distilled.cloud/axiom@0.30.2"
   - "@distilled.cloud/cloudflare@0.30.2"
diff --git a/scripts/build-desktop-artifact.test.ts b/scripts/build-desktop-artifact.test.ts
index 3e637aa2e9a..d965e34408f 100644
--- a/scripts/build-desktop-artifact.test.ts
+++ b/scripts/build-desktop-artifact.test.ts
@@ -351,6 +351,11 @@ it.layer(NodeServices.layer)("build-desktop-artifact", (it) => {
       assert.notProperty(mac, "asarUnpack");
       assert.notProperty(linux, "asarUnpack");
       assert.deepStrictEqual(win.asarUnpack, WINDOWS_ASAR_UNPACK);
+      // Linux must register the renderer schemes so the generated .desktop
+      // entry advertises MimeType=x-scheme-handler/t3code; for OAuth deep links.
+      assert.deepStrictEqual((linux.linux as Record<string, unknown>).protocols, [
+        { name: "T3 Code", schemes: ["t3code", "t3code-dev"] },
+      ]);
       for (const config of [mac, linux, win]) {
         assert.deepStrictEqual(config.electronLanguages, DESKTOP_ELECTRON_LANGUAGES);
         assert.deepStrictEqual(config.files, DESKTOP_FILE_EXCLUSIONS);
diff --git a/scripts/build-desktop-artifact.ts b/scripts/build-desktop-artifact.ts
index c259455f489..ff328ce772b 100644
--- a/scripts/build-desktop-artifact.ts
+++ b/scripts/build-desktop-artifact.ts
@@ -1612,6 +1612,15 @@ export const createBuildConfig = Effect.fn("createBuildConfig")(function* (
       executableName: "n3code",
       icon: "icons",
       category: "Development",
+      // electron-builder turns these into MimeType=x-scheme-handler/<scheme>;
+      // in the .desktop entry (Exec already gets %U), so browsers can hand
+      // t3code:// OAuth callbacks to the app.
+      protocols: [
+        {
+          name: "T3 Code",
+          schemes: ["t3code", "t3code-dev"],
+        },
+      ],
       desktop: {
         entry: {
           StartupWMClass: "t3code-fork",
diff --git a/scripts/mobile-showcase-environment.ts b/scripts/mobile-showcase-environment.ts
index 9c04c7e9dd1..f7854675351 100644
--- a/scripts/mobile-showcase-environment.ts
+++ b/scripts/mobile-showcase-environment.ts
@@ -1,4 +1,4 @@
-// @effect-diagnostics nodeBuiltinImport:off globalDate:off - This host-side fixture creates an isolated local T3 environment.
+// @effect-diagnostics nodeBuiltinImport:off globalTimers:off globalDate:off - This host-side fixture creates an isolated local T3 environment.
 import * as NodeChildProcess from "node:child_process";
 import * as NodeFSP from "node:fs/promises";
 import * as NodePath from "node:path";
@@ -387,6 +387,48 @@ function insertThread(
     .run(input.id, isWorking ? "running" : "ready", isWorking ? turnId : null, updatedAt);
 }
 
+const SEEDED_PROJECTION_TABLES = [
+  "projection_pending_approvals",
+  "projection_thread_proposed_plans",
+  "projection_thread_activities",
+  "projection_thread_messages",
+  "projection_thread_sessions",
+  "projection_turns",
+  "projection_threads",
+  "projection_projects",
+  "projection_state",
+] as const;
+
+function hasSeedableSchema(dbPath: string): boolean {
+  let database: NodeSqlite.DatabaseSync;
+  try {
+    database = new NodeSqlite.DatabaseSync(dbPath, { readOnly: true });
+  } catch {
+    return false;
+  }
+  try {
+    const row = database
+      .prepare(
+        `SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name IN (${SEEDED_PROJECTION_TABLES.map(() => "?").join(", ")})`,
+      )
+      .get(...SEEDED_PROJECTION_TABLES) as { count: number };
+    return row.count === SEEDED_PROJECTION_TABLES.length;
+  } catch {
+    return false;
+  } finally {
+    database.close();
+  }
+}
+
+async function waitForSeedableSchema(dbPath: string, timeoutMs = 60_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (hasSeedableSchema(dbPath)) return;
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`The environment server did not migrate ${dbPath} within ${timeoutMs}ms.`);
+}
+
 function seedDatabase(
   dbPath: string,
   workspaceRoots: ReadonlyMap<string, string>,
@@ -401,17 +443,7 @@ function seedDatabase(
   const database = new NodeSqlite.DatabaseSync(dbPath, { timeout: 30_000 });
   try {
     database.exec("BEGIN IMMEDIATE");
-    for (const table of [
-      "projection_pending_approvals",
-      "projection_thread_proposed_plans",
-      "projection_thread_activities",
-      "projection_thread_messages",
-      "projection_thread_sessions",
-      "projection_turns",
-      "projection_threads",
-      "projection_projects",
-      "projection_state",
-    ]) {
+    for (const table of SEEDED_PROJECTION_TABLES) {
       database.exec(`DELETE FROM ${table}`);
     }
     const insertProject = database.prepare(
@@ -594,6 +626,9 @@ export async function seedShowcaseEnvironment(input: {
         });
       }),
   );
+  // The environment server begins listening before it finishes migrating the
+  // database, so wait for the schema before deleting from and reseeding it.
+  await waitForSeedableSchema(dbPath);
   seedDatabase(dbPath, workspaceRoots, projects, threads, now);
 
   const terminalDirectory = NodePath.join(input.baseDir, "userdata", "logs", "terminals");
diff --git a/scripts/mobile-showcase.config.ts b/scripts/mobile-showcase.config.ts
index 3237933bec8..7f112396838 100644
--- a/scripts/mobile-showcase.config.ts
+++ b/scripts/mobile-showcase.config.ts
@@ -25,6 +25,8 @@ export interface ShowcaseIosDevice {
   readonly simulatorDeviceType?: string;
   /** Appearance used when the CLI does not pass --appearance. */
   readonly appearance: ShowcaseAppearance;
+  /** Orientation applied by the capture harness. Defaults to portrait. */
+  readonly orientation?: "portrait" | "landscape";
   readonly scenes: ReadonlyArray<ShowcaseScene>;
   readonly storeAsset: ShowcaseStoreAssetSpec;
 }
@@ -122,12 +124,13 @@ const config: ShowcaseConfig = {
       simulator: "iPad Pro 13-inch (M5)",
       simulatorDeviceType: "com.apple.CoreSimulator.SimDeviceType.iPad-Pro-13-inch-M5-16GB",
       appearance: "dark",
+      orientation: "landscape",
       scenes: ["thread", "terminal", "review", "threads", "environments"],
       storeAsset: {
         store: "apple",
         directory: "apple/ipad-13",
-        width: 2064,
-        height: 2752,
+        width: 2752,
+        height: 2064,
         minimumUploadCount: 1,
         maximumUploadCount: 10,
       },
diff --git a/scripts/mobile-showcase.test.ts b/scripts/mobile-showcase.test.ts
index 242c9ebdb67..16fb3e230bb 100644
--- a/scripts/mobile-showcase.test.ts
+++ b/scripts/mobile-showcase.test.ts
@@ -216,17 +216,18 @@ it("configures every default device with an exact upload-ready store target", ()
   assert.deepStrictEqual(
     showcaseConfig.devices.map((device) => [
       device.id,
+      device.platform === "ios" ? (device.orientation ?? "portrait") : null,
       device.storeAsset.directory,
       device.storeAsset.width,
       device.storeAsset.height,
     ]),
     [
-      ["iphone-6.9", "apple/iphone-6.9", 1320, 2868],
-      ["iphone-6.5", "apple/iphone-6.5", 1284, 2778],
-      ["ipad-13", "apple/ipad-13", 2064, 2752],
-      ["pixel", "google-play/phone", 1080, 1920],
-      ["android-tablet-7", "google-play/tablet-7", 1080, 1920],
-      ["android-tablet-10", "google-play/tablet-10", 1440, 2560],
+      ["iphone-6.9", "portrait", "apple/iphone-6.9", 1320, 2868],
+      ["iphone-6.5", "portrait", "apple/iphone-6.5", 1284, 2778],
+      ["ipad-13", "landscape", "apple/ipad-13", 2752, 2064],
+      ["pixel", null, "google-play/phone", 1080, 1920],
+      ["android-tablet-7", null, "google-play/tablet-7", 1080, 1920],
+      ["android-tablet-10", null, "google-play/tablet-10", 1440, 2560],
     ],
   );
 });
@@ -244,22 +245,19 @@ it("selects a reachable LAN IPv4 address", () => {
 });
 
 it("maps capture scenes to the real application routes", () => {
-  assert.equal(showcaseSceneUrl("threads", "environment-1"), "t3code-dev://");
-  assert.equal(
-    showcaseSceneUrl("environments", "environment-1"),
-    "t3code-dev://settings/environments",
-  );
+  assert.equal(showcaseSceneUrl("threads", "environment-1"), "t3code://");
+  assert.equal(showcaseSceneUrl("environments", "environment-1"), "t3code://settings/environments");
   assert.equal(
     showcaseSceneUrl("thread", "environment-1"),
-    "t3code-dev://threads/environment-1/remote-command-center",
+    "t3code://threads/environment-1/remote-command-center",
   );
   assert.equal(
     showcaseSceneUrl("terminal", "environment-1"),
-    "t3code-dev://threads/environment-1/remote-command-center/terminal?terminalId=term-1",
+    "t3code://threads/environment-1/remote-command-center/terminal?terminalId=term-1",
   );
   assert.equal(
     showcaseSceneUrl("review", "environment-1"),
-    "t3code-dev://threads/environment-1/remote-command-center/review",
+    "t3code://threads/environment-1/remote-command-center/review",
   );
 });
 
diff --git a/scripts/mobile-showcase.ts b/scripts/mobile-showcase.ts
index 85304aecd86..d9991f42361 100644
--- a/scripts/mobile-showcase.ts
+++ b/scripts/mobile-showcase.ts
@@ -31,14 +31,14 @@ import {
 
 const REPO_ROOT = NodePath.resolve(NodePath.dirname(NodeURL.fileURLToPath(import.meta.url)), "..");
 const MOBILE_ROOT = NodePath.join(REPO_ROOT, "apps/mobile");
-const ANDROID_PACKAGE = "com.t3tools.t3code.dev";
-const APP_SCHEME = "t3code-dev";
+const ANDROID_PACKAGE = "com.t3tools.t3code";
+const APP_SCHEME = "t3code";
 const IOS_READY_FILENAME = "T3ShowcaseReadyScene";
 const SERVER_HOST = "0.0.0.0";
 const IOS_SIMULATOR_ARCH = NodeProcess.arch === "arm64" ? "arm64" : "x86_64";
 const IOS_APP_PATH = NodePath.join(
   MOBILE_ROOT,
-  ".showcase/ios-derived-data/Build/Products/Debug-iphonesimulator/T3CodeDev.app",
+  ".showcase/ios-derived-data/Build/Products/Debug-iphonesimulator/T3Code.app",
 );
 const ANDROID_APK_PATH = NodePath.join(
   MOBILE_ROOT,
@@ -58,8 +58,11 @@ const ANDROID_SDK_ROOT = resolveAndroidSdkRoot(NodeProcess.env);
 const MOBILE_BUILD_ENV = {
   ...NodeProcess.env,
   ANDROID_HOME: ANDROID_SDK_ROOT,
-  APP_VARIANT: "development",
+  APP_VARIANT: "production",
   EXPO_NO_GIT_STATUS: "1",
+  // Lets the capture build require full screen on iPad so the app can rotate
+  // itself to landscape (see app.config.ts).
+  T3_SHOWCASE_CAPTURE_BUILD: "1",
   JAVA_HOME:
     NodeProcess.env.JAVA_HOME ??
     (NodeProcess.platform === "darwin"
@@ -500,6 +503,23 @@ async function waitForPort(port: number, label = "Process", timeoutMs = 60_000):
   throw new Error(`${label} did not begin listening on port ${port} within ${timeoutMs}ms.`);
 }
 
+async function waitForFileContent(
+  filePath: string,
+  label: string,
+  timeoutMs = 60_000,
+): Promise<string> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const content = await NodeFSP.readFile(filePath, "utf8").then(
+      (value) => value.trim(),
+      () => "",
+    );
+    if (content) return content;
+    await delay(250);
+  }
+  throw new Error(`${label} was not written to ${filePath} within ${timeoutMs}ms.`);
+}
+
 async function reserveAvailablePort(): Promise<number> {
   return await new Promise<number>((resolve, reject) => {
     const server = NodeNet.createServer();
@@ -664,9 +684,9 @@ async function buildIos(): Promise<string> {
     "xcodebuild",
     [
       "-workspace",
-      NodePath.join(MOBILE_ROOT, "ios/T3CodeDev.xcworkspace"),
+      NodePath.join(MOBILE_ROOT, "ios/T3Code.xcworkspace"),
       "-scheme",
-      "T3CodeDev",
+      "T3Code",
       "-configuration",
       "Debug",
       "-sdk",
@@ -775,6 +795,60 @@ async function normalizeIosSimulator(appearance: ShowcaseAppearance, udid: strin
   ]);
 }
 
+// iPadOS 26 windowing ("Chamois") runs UIRequiresFullScreen apps in a fixed
+// portrait compatibility window, which defeats the in-app landscape rotation
+// the capture build relies on. Switch the device to Full Screen Apps mode
+// (Settings > Multitasking & Gestures) and restart SpringBoard to apply it.
+async function ensureIosFullScreenAppsMode(udid: string): Promise<void> {
+  const current = await commandOutput("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "read",
+    "com.apple.springboard",
+    "SBChamoisWindowingEnabled",
+  ]).catch(() => "");
+  if (current.trim() === "0") return;
+  // The Settings toggle writes all three keys; SBChamoisWindowingEnabled
+  // alone is not honored on a freshly created device.
+  for (const key of [
+    "SBChamoisWindowingEnabled",
+    "SBMedusaMultitaskingEnabled",
+    "SBFlexibleWindowingPreviouslyEnabledAutomaticStageCreation",
+  ]) {
+    await runCommand("xcrun", [
+      "simctl",
+      "spawn",
+      udid,
+      "defaults",
+      "write",
+      "com.apple.springboard",
+      key,
+      "-bool",
+      "false",
+    ]);
+  }
+  // A SpringBoard restart is not enough on a freshly created simulator (the
+  // first CI run captured with windowing still active), so reboot the device
+  // and verify the mode actually stuck.
+  await runCommand("xcrun", ["simctl", "shutdown", udid]);
+  await runCommand("xcrun", ["simctl", "boot", udid]);
+  await runCommand("xcrun", ["simctl", "bootstatus", udid, "-b"]);
+  const applied = await commandOutput("xcrun", [
+    "simctl",
+    "spawn",
+    udid,
+    "defaults",
+    "read",
+    "com.apple.springboard",
+    "SBChamoisWindowingEnabled",
+  ]).catch(() => "");
+  if (applied.trim() !== "0") {
+    throw new Error(`Simulator ${udid} did not switch to Full Screen Apps mode.`);
+  }
+}
+
 async function iosAppContainer(udid: string): Promise<string> {
   return (
     await commandOutput("xcrun", ["simctl", "get_app_container", udid, ANDROID_PACKAGE, "data"])
@@ -819,6 +893,9 @@ async function captureIos(
   }
   await runCommand("xcrun", ["simctl", "boot", simulator.udid]);
   await runCommand("xcrun", ["simctl", "bootstatus", simulator.udid, "-b"]);
+  if (capture.device.orientation === "landscape") {
+    await ensureIosFullScreenAppsMode(simulator.udid);
+  }
   await normalizeIosSimulator(capture.appearance, simulator.udid);
   if (appPath) {
     await runCommand("xcrun", ["simctl", "uninstall", simulator.udid, ANDROID_PACKAGE]).catch(
@@ -869,6 +946,10 @@ async function captureIos(
       JSON.stringify(pairingUrls),
       "--showcaseScene",
       firstScene,
+      // The app rotates itself; Simulator menu UI scripting needs macOS
+      // Accessibility permission that CI runners do not grant to osascript.
+      "--showcaseOrientation",
+      capture.device.orientation ?? "portrait",
     ]);
   };
   await NodeFSP.rm(readyPath, { force: true });
@@ -900,6 +981,15 @@ async function captureIos(
       `${scene}.png`,
     );
     await runCommand("xcrun", ["simctl", "io", simulator.udid, "screenshot", destination]);
+    if (capture.device.orientation === "landscape") {
+      // A headless simulator keeps its display portrait while the rotated app
+      // renders sideways inside it; with Simulator.app attached the display
+      // itself rotates. Only post-rotate the former.
+      const { width, height } = readPngDimensions(await NodeFSP.readFile(destination));
+      if (height > width) {
+        await runCommand("sips", ["--rotate", "270", destination]);
+      }
+    }
     await finalizeCapture(destination, capture.device);
   }
 }
@@ -1225,12 +1315,12 @@ async function main(): Promise<void> {
       showcaseServers.push(server);
       await waitForPort(port, `${environment.label} server`);
       await seedShowcaseEnvironment({ baseDir, projectIds: environment.projectIds });
-      const environmentId = (
-        await NodeFSP.readFile(NodePath.join(baseDir, "userdata", "environment-id"), "utf8")
-      ).trim();
-      if (!environmentId) {
-        throw new Error(`${environment.label} did not persist an environment id.`);
-      }
+      // The server begins listening before the ServerEnvironment layer
+      // persists the environment id, so poll rather than read once.
+      const environmentId = await waitForFileContent(
+        NodePath.join(baseDir, "userdata", "environment-id"),
+        `${environment.label} environment id`,
+      );
       showcaseEnvironments.push({ baseDir, environmentId, label: environment.label, port });
     }