From 201b3d187354a840f3c3eef6abe6e2cef9136aae Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:06:52 -0700
Subject: [PATCH 01/74] feat(web): support hosted pairing links

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .plans/19-remote-endpoints-hosted-static.md   | 350 ++++++++++++++++++
 .../components/auth/PairingRouteSurface.tsx   |  99 +++++
 .../settings/ConnectionsSettings.tsx          |  17 +-
 apps/web/src/environments/runtime/service.ts  |   6 +-
 apps/web/src/hostedPairing.test.ts            |  52 +++
 apps/web/src/hostedPairing.ts                 |  49 +++
 apps/web/src/localApi.ts                      |  47 ++-
 apps/web/src/routes/__root.tsx                |  79 +++-
 apps/web/src/routes/_chat.tsx                 |   5 +-
 apps/web/src/routes/pair.tsx                  |  18 +-
 apps/web/src/routes/settings.tsx              |   5 +-
 apps/web/vite.config.ts                       |   2 +
 12 files changed, 704 insertions(+), 25 deletions(-)
 create mode 100644 .plans/19-remote-endpoints-hosted-static.md
 create mode 100644 apps/web/src/hostedPairing.test.ts
 create mode 100644 apps/web/src/hostedPairing.ts

diff --git a/.plans/19-remote-endpoints-hosted-static.md b/.plans/19-remote-endpoints-hosted-static.md
new file mode 100644
index 00000000000..2fa0bc70211
--- /dev/null
+++ b/.plans/19-remote-endpoints-hosted-static.md
@@ -0,0 +1,350 @@
+# Remote Endpoints and Hosted Static App Plan
+
+## Purpose
+
+Make remote access feel first-class while keeping the free DIY path open.
+
+The immediate product goal is:
+
+- users can expose a backend through LAN, their own Tailscale, MagicDNS, a manual HTTPS endpoint, or later T3 Tunnel
+- users can generate a hosted pairing link for `app.t3.codes`
+- the hosted app can pair, persist, reconnect, and operate against saved environments without requiring a backend at the hosted app origin
+- all transports reuse the same backend auth, WebSocket runtime, saved environment registry, and pairing UX
+
+This plan intentionally leaves the paid T3 cloud tunnel fabric out of scope. It defines the OSS foundation that T3 Tunnel should later plug into.
+
+## Current State
+
+Already present or in progress:
+
+- Server auth distinguishes bootstrap credentials from session credentials.
+- One-time pairing credentials can be exchanged for browser sessions or bearer sessions.
+- Saved remote environments store `httpBaseUrl`, `wsBaseUrl`, and a bearer token.
+- Remote environment WebSocket connections use a short-lived WebSocket token.
+- Pairing URLs can carry tokens in the URL fragment.
+- Hosted `/pair?host=...#token=...` can add a saved environment.
+- Hosted static startup can avoid assuming the page origin is the backend.
+
+Main gaps:
+
+- Reachability is represented ad hoc as `endpointUrl`, manual host input, or saved environment URLs.
+- Desktop exposure, hosted pairing, manual remote environments, and future tunnels do not share one endpoint model.
+- Tailscale/MagicDNS endpoints are not detected or surfaced.
+- Hosted-static empty/offline states are still thin.
+- Browser compatibility is not explicitly modeled, especially HTTPS hosted app to HTTP backend mixed-content failure.
+
+## Core Decision: Add `AdvertisedEndpoint`
+
+Add a new first-class contract instead of extending the environment descriptor.
+
+### Why not extend `ExecutionEnvironmentDescriptor`
+
+`ExecutionEnvironmentDescriptor` answers: "What environment is this?"
+
+Examples:
+
+- environment id
+- label
+- platform
+- server version
+- capabilities
+
+`AdvertisedEndpoint` answers: "How can a client reach this environment right now?"
+
+Examples:
+
+- loopback URL
+- LAN URL
+- Tailscale IP URL
+- MagicDNS/Serve URL
+- manual URL
+- future T3 Tunnel URL
+- browser compatibility and exposure level
+
+Those are different lifecycles. One environment can have many endpoints, endpoints can appear/disappear as network interfaces change, and the same descriptor is returned regardless of which endpoint the client used. Extending the descriptor would blur environment identity with transport reachability and make saved environments harder to reason about.
+
+### Target Contract
+
+Add a schema in `packages/contracts`, likely `remoteAccess.ts`:
+
+```ts
+type AdvertisedEndpointProvider =
+  | "loopback"
+  | "lan"
+  | "tailscale-ip"
+  | "tailscale-magicdns"
+  | "manual"
+  | "t3-tunnel";
+
+type AdvertisedEndpointVisibility = "local" | "private-network" | "tailnet" | "public";
+
+type AdvertisedEndpointCompatibility = {
+  hostedHttpsApp: "compatible" | "mixed-content-blocked" | "untrusted-certificate" | "unknown";
+  desktopApp: "compatible" | "unknown";
+};
+
+type AdvertisedEndpoint = {
+  id: string;
+  provider: AdvertisedEndpointProvider;
+  label: string;
+  httpBaseUrl: string;
+  wsBaseUrl: string;
+  visibility: AdvertisedEndpointVisibility;
+  compatibility: AdvertisedEndpointCompatibility;
+  source: "server" | "desktop" | "user";
+  status: "available" | "unavailable" | "unknown";
+  isDefault?: boolean;
+};
+```
+
+Keep the contract schema-only. All classification logic belongs in `packages/shared`, `apps/server`, `apps/desktop`, or `apps/web`.
+
+## HTTP/WS and HTTPS/WSS Readiness
+
+The codebase is partially ready, but the UX and compatibility model are not explicit enough.
+
+What is ready:
+
+- Remote target parsing already derives `ws://` from `http://` and `wss://` from `https://`.
+- Saved environments store both HTTP and WebSocket base URLs.
+- Remote auth uses bearer tokens instead of cookies, so cross-origin hosted clients are viable.
+- WebSocket connections can use a dynamically issued `wsToken`.
+- Server CORS support exists for browser remote auth endpoints.
+
+What is not solved by code alone:
+
+- `https://app.t3.codes` cannot reliably call `http://...` or `ws://...` endpoints because browsers block mixed content.
+- `wss://100.x.y.z:3773` needs a certificate the browser trusts. A raw Tailscale IP does not solve certificate trust.
+- LAN `http://192.168.x.y:3773` is usable from another desktop/native context but not from the hosted HTTPS app.
+- The UI needs to explain why an endpoint is copyable for desktop pairing but not hosted-app compatible.
+
+Policy:
+
+- Support both HTTP/WS and HTTPS/WSS at the runtime layer.
+- Mark endpoint compatibility at the product layer.
+- Generate `app.t3.codes` links only from endpoints that are likely hosted-browser compatible, or show a warning with an explicit fallback.
+
+## Architecture
+
+### Endpoint Sources
+
+Endpoint records can come from several providers:
+
+1. **Server runtime**
+   - headless bind host and port
+   - server-known explicit advertised host config
+
+2. **Desktop shell**
+   - loopback backend URL
+   - LAN exposure state
+   - network interface discovery
+   - Tailscale CLI/status discovery
+
+3. **User configuration**
+   - manually added hostnames
+   - preferred endpoint labels
+   - hidden/disabled endpoints
+
+4. **Future cloud provider**
+   - T3 Tunnel endpoint
+   - billing/account status
+   - tunnel lifecycle state
+
+### Endpoint Registry
+
+Create a central runtime registry:
+
+- `packages/contracts/src/remoteAccess.ts`
+- `packages/shared/src/remoteAccess.ts` for URL normalization and compatibility classification
+- `apps/server/src/remoteAccess/*` for server/headless endpoints
+- `apps/desktop/src/remoteAccess/*` for desktop-discovered endpoints
+- `apps/web/src/environments/endpoints/*` for client-side display and pairing selection
+
+The web app should consume endpoint records and not care whether they came from LAN, Tailscale, or a future tunnel.
+
+### Pairing Link Generation
+
+Move hosted pairing link generation to endpoint-driven input:
+
+```ts
+buildHostedPairingUrl({
+  endpoint: AdvertisedEndpoint,
+  token,
+});
+```
+
+Generated URL:
+
+```text
+https://app.t3.codes/pair?host=<encoded endpoint httpBaseUrl>#token=<one-time token>
+```
+
+Use fragment tokens by default. Continue accepting `?token=` for compatibility.
+
+## Phase 1: Endpoint Abstraction
+
+### Goals
+
+- Centralize URL normalization, protocol derivation, and compatibility checks.
+- Replace ad hoc desktop `endpointUrl` pairing logic with endpoint selection.
+- Preserve all current remote behavior.
+
+### Tasks
+
+1. Add `AdvertisedEndpoint` schemas to `packages/contracts`.
+2. Add shared helpers:
+   - normalize HTTP base URL
+   - derive WebSocket base URL
+   - classify loopback/private/LAN/Tailscale/public host
+   - classify hosted HTTPS compatibility
+3. Add server endpoint discovery:
+   - loopback endpoint
+   - configured non-loopback endpoint
+   - explicit advertised host override
+4. Add desktop endpoint discovery:
+   - local loopback
+   - LAN exposure endpoint
+   - endpoint status labels
+5. Add WebSocket/API method or existing config field for endpoint snapshots.
+6. Refactor settings connections UI:
+   - render endpoint rows
+   - endpoint picker for pairing link copy
+   - show compatibility warnings
+7. Refactor hosted link builder to accept endpoint records.
+8. Add tests for URL normalization and compatibility classification.
+
+### Acceptance Criteria
+
+- Existing LAN/network access UI still works.
+- Pairing links are generated from endpoint records.
+- Loopback endpoints never produce hosted pairing links silently.
+- HTTP private-network endpoints are marked incompatible with `app.t3.codes`.
+- No remote environment runtime changes are required for existing saved environments.
+
+## Phase 2: BYO Tailscale/MagicDNS
+
+### Goals
+
+- Detect free DIY Tailscale reachability.
+- Surface Tailscale endpoints as normal advertised endpoints.
+- Keep users in control of their own tailnet.
+
+### Tasks
+
+1. Detect Tailscale IPs from network interfaces:
+   - IPv4 `100.64.0.0/10`
+   - mark as `provider: "tailscale-ip"`
+2. Add optional desktop-side `tailscale status --json` discovery:
+   - MagicDNS hostname
+   - Tailscale Serve/Funnel HTTPS endpoint if discoverable
+   - graceful failure if CLI is missing
+3. Add manual Tailscale endpoint override:
+   - hostname
+   - label
+   - preferred/default flag
+4. Show Tailscale endpoint rows in settings:
+   - raw IP HTTP endpoint: desktop-compatible, hosted-app likely blocked
+   - HTTPS MagicDNS/Serve endpoint: hosted-compatible if URL is HTTPS
+5. Generate pairing links using selected Tailscale endpoint.
+6. Document DIY setup:
+   - local desktop-to-desktop over Tailscale
+   - hosted app requirements
+   - why HTTPS matters
+
+### Acceptance Criteria
+
+- A machine on Tailscale shows a Tailscale endpoint without paid features.
+- Users can copy a Tailscale-hosted pairing link when the endpoint is HTTPS-compatible.
+- Users can still copy token-only/manual values when endpoint compatibility is unknown.
+- Tailscale is optional and never required for regular LAN/loopback use.
+
+## Phase 3: Hosted Static App Completion
+
+### Goals
+
+- `app.t3.codes` works as a real client shell.
+- It can pair, persist, reconnect, and clearly explain offline/incompatible states.
+
+### Tasks
+
+1. Finish hosted-static root behavior:
+   - no primary backend required
+   - saved environment hydration before initial routing decisions
+   - first saved environment selected as active
+2. Add hosted empty state:
+   - no saved environments
+   - paste pairing URL
+   - add host + token
+3. Add offline saved environment UI:
+   - last connected
+   - reconnect
+   - remove
+   - copy/add alternate endpoint
+4. Audit primary-backend assumptions:
+   - command palette
+   - settings pages
+   - server config atom defaults
+   - keybindings
+   - provider/model lists
+   - update/desktop-only affordances
+5. Add route tests for:
+   - hosted `/pair?host=...#token=...`
+   - hosted root with no saved environments
+   - hosted root with saved environment
+   - primary backend unavailable but saved environment present
+6. Add deployment hardening:
+   - SPA fallback
+   - strict CSP
+   - no third-party scripts
+   - no query token logging
+   - disable or hide source maps in production if needed
+7. Add browser error messages:
+   - mixed content
+   - unreachable backend
+   - CORS failure
+   - certificate failure
+
+### Acceptance Criteria
+
+- `app.t3.codes` can pair a reachable HTTPS backend and reconnect after reload.
+- A saved environment can be used without any backend at `app.t3.codes`.
+- Offline machines show a useful state instead of a generic boot error.
+- HTTP endpoints are still supported in desktop/native/local contexts.
+- Hosted HTTPS app only promises compatibility for HTTPS/WSS endpoints.
+
+## Phase 4: Future T3 Tunnel Provider
+
+Not part of the current implementation, but the endpoint abstraction should make it straightforward.
+
+Future tunnel provider responsibilities:
+
+- create endpoint with `provider: "t3-tunnel"`
+- surface tunnel status
+- provide stable HTTPS URL
+- use existing backend pairing/session auth
+- never bypass server auth
+
+The tunnel fabric can later be Pipenet-derived, Tailscale-derived, or another reverse tunnel implementation. The rest of T3 Code should only see an `AdvertisedEndpoint`.
+
+## Security Checklist
+
+- Pairing tokens are short-lived and one-time.
+- Generated hosted pairing links put tokens in the fragment.
+- The backend remains the authorization boundary.
+- Endpoint discovery never disables backend auth.
+- Hosted app does not silently downgrade to HTTP.
+- Tunnel/public endpoints require explicit user action.
+- Client sessions remain revocable.
+- Endpoint URLs and request logs must avoid recording pairing tokens.
+- Future cloud tunnel must authenticate tunnel creation and tunnel data connections separately from backend pairing.
+
+## Verification
+
+Each implementation PR should run:
+
+- `bun fmt`
+- `bun lint`
+- `bun typecheck`
+- focused tests for changed backend/web behavior
+- backend tests for any server-side endpoint discovery or auth changes using `bun run test`, never `bun test`
+
diff --git a/apps/web/src/components/auth/PairingRouteSurface.tsx b/apps/web/src/components/auth/PairingRouteSurface.tsx
index f583af72ec4..46349ca1faf 100644
--- a/apps/web/src/components/auth/PairingRouteSurface.tsx
+++ b/apps/web/src/components/auth/PairingRouteSurface.tsx
@@ -2,11 +2,13 @@ import type { AuthSessionState } from "@t3tools/contracts";
 import React, { startTransition, useEffect, useRef, useState, useCallback } from "react";
 
 import { APP_DISPLAY_NAME } from "../../branding";
+import { addSavedEnvironment } from "../../environments/runtime";
 import {
   peekPairingTokenFromUrl,
   stripPairingTokenFromUrl,
   submitServerAuthCredential,
 } from "../../environments/primary";
+import { readHostedPairingRequest } from "../../hostedPairing";
 import { Button } from "../ui/button";
 import { Input } from "../ui/input";
 
@@ -159,6 +161,103 @@ export function PairingRouteSurface({
   );
 }
 
+export function HostedPairingRouteSurface() {
+  const hostedPairingRequestRef = useRef(readHostedPairingRequest());
+  const [status, setStatus] = useState<"pairing" | "paired" | "error">("pairing");
+  const [message, setMessage] = useState("Connecting to this backend.");
+  const submitAttemptedRef = useRef(false);
+
+  const submitHostedPairingRequest = useCallback(async () => {
+    const request = hostedPairingRequestRef.current;
+
+    if (!request) {
+      setStatus("error");
+      setMessage("This pairing link is missing its backend host or token.");
+      return;
+    }
+
+    setStatus("pairing");
+    setMessage("Connecting to this backend.");
+
+    try {
+      const record = await addSavedEnvironment({
+        label: request.label,
+        host: request.host,
+        pairingCode: request.token,
+      });
+      setStatus("paired");
+      setMessage(`${record.label} is saved in this browser.`);
+    } catch (error) {
+      setStatus("error");
+      setMessage(errorMessageFromUnknown(error));
+    }
+  }, []);
+
+  useEffect(() => {
+    if (submitAttemptedRef.current) {
+      return;
+    }
+    submitAttemptedRef.current = true;
+
+    stripPairingTokenFromUrl();
+    void submitHostedPairingRequest();
+  }, [submitHostedPairingRequest]);
+
+  const request = hostedPairingRequestRef.current;
+
+  return (
+    <div className="relative flex min-h-screen items-center justify-center overflow-hidden bg-background px-4 py-10 text-foreground sm:px-6">
+      <div className="pointer-events-none absolute inset-0 opacity-80">
+        <div className="absolute inset-x-0 top-0 h-44 bg-[radial-gradient(44rem_16rem_at_top,color-mix(in_srgb,var(--color-emerald-500)_14%,transparent),transparent)]" />
+        <div className="absolute inset-y-0 left-0 w-72 bg-[radial-gradient(28rem_18rem_at_left,color-mix(in_srgb,var(--color-sky-500)_10%,transparent),transparent)]" />
+        <div className="absolute inset-0 bg-[linear-gradient(145deg,color-mix(in_srgb,var(--background)_90%,var(--color-black))_0%,var(--background)_55%)]" />
+      </div>
+
+      <section className="relative w-full max-w-xl rounded-2xl border border-border/80 bg-card/90 p-6 shadow-2xl shadow-black/20 backdrop-blur-md sm:p-8">
+        <p className="text-[11px] font-semibold tracking-[0.18em] text-muted-foreground uppercase">
+          {APP_DISPLAY_NAME}
+        </p>
+        <h1 className="mt-3 text-2xl font-semibold tracking-tight sm:text-3xl">
+          {status === "paired"
+            ? "Backend paired"
+            : status === "error"
+              ? "Pairing failed"
+              : "Pairing backend"}
+        </h1>
+        <p className="mt-2 text-sm leading-relaxed text-muted-foreground">{message}</p>
+
+        {request ? (
+          <div className="mt-5 rounded-lg border border-border/70 bg-background/55 px-3 py-3 text-xs leading-relaxed text-muted-foreground">
+            Host: <span className="font-mono text-foreground/80">{request.host}</span>
+          </div>
+        ) : null}
+
+        {status === "error" ? (
+          <div className="mt-5 rounded-lg border border-destructive/30 bg-destructive/6 px-3 py-2 text-sm text-destructive">
+            Verify the backend is reachable from this browser, supports CORS for hosted clients, and
+            is served over HTTPS when opening this page from HTTPS.
+          </div>
+        ) : null}
+
+        <div className="mt-6 flex flex-wrap gap-2">
+          <Button
+            disabled={status === "pairing"}
+            size="sm"
+            onClick={() => void submitHostedPairingRequest()}
+          >
+            {status === "pairing" ? "Pairing..." : "Try again"}
+          </Button>
+          {status === "paired" ? (
+            <Button size="sm" variant="outline" onClick={() => (window.location.href = "/")}>
+              Open app
+            </Button>
+          ) : null}
+        </div>
+      </section>
+    </div>
+  );
+}
+
 function errorMessageFromUnknown(error: unknown): string {
   if (error instanceof Error && error.message.trim().length > 0) {
     return error.message;
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 880c4376e2c..50af9f88596 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -9,6 +9,7 @@ import {
 import { DateTime } from "effect";
 
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
+import { buildHostedPairingUrl } from "../../hostedPairing";
 import { cn } from "../../lib/utils";
 import { formatElapsedDurationLabel, formatExpiresInLabel } from "../../timestampFormat";
 import {
@@ -249,6 +250,13 @@ function resolveDesktopPairingUrl(endpointUrl: string, credential: string): stri
   return setPairingTokenOnUrl(url, credential).toString();
 }
 
+function resolveHostedPairingUrl(endpointUrl: string, credential: string): string {
+  return buildHostedPairingUrl({
+    host: endpointUrl,
+    token: credential,
+  });
+}
+
 function resolveCurrentOriginPairingUrl(credential: string): string {
   const url = new URL("/pair", window.location.href);
   return setPairingTokenOnUrl(url, credential).toString();
@@ -278,9 +286,16 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
     () => resolveCurrentOriginPairingUrl(pairingLink.credential),
     [pairingLink.credential],
   );
+  const hostedPairingUrl = useMemo(
+    () =>
+      endpointUrl != null && endpointUrl !== ""
+        ? resolveHostedPairingUrl(endpointUrl, pairingLink.credential)
+        : null,
+    [endpointUrl, pairingLink.credential],
+  );
   const shareablePairingUrl =
     endpointUrl != null && endpointUrl !== ""
-      ? resolveDesktopPairingUrl(endpointUrl, pairingLink.credential)
+      ? (hostedPairingUrl ?? resolveDesktopPairingUrl(endpointUrl, pairingLink.credential))
       : isLoopbackHostname(window.location.hostname)
         ? null
         : currentOriginPairingUrl;
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index d724eeff333..ec920e9a7be 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -905,6 +905,10 @@ function createPrimaryEnvironmentConnection(): EnvironmentConnection {
   );
 }
 
+function maybeCreatePrimaryEnvironmentConnection(): EnvironmentConnection | null {
+  return getPrimaryKnownEnvironment() ? createPrimaryEnvironmentConnection() : null;
+}
+
 async function ensureSavedEnvironmentConnection(
   record: SavedEnvironmentRecord,
   options?: {
@@ -1170,7 +1174,7 @@ export function startEnvironmentConnectionService(queryClient: QueryClient): ()
     },
   );
 
-  createPrimaryEnvironmentConnection();
+  maybeCreatePrimaryEnvironmentConnection();
 
   const unsubscribeSavedEnvironments = useSavedEnvironmentRegistryStore.subscribe(() => {
     if (!hasSavedEnvironmentRegistryHydrated()) {
diff --git a/apps/web/src/hostedPairing.test.ts b/apps/web/src/hostedPairing.test.ts
new file mode 100644
index 00000000000..f347ca46ab5
--- /dev/null
+++ b/apps/web/src/hostedPairing.test.ts
@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  buildHostedPairingUrl,
+  hasHostedPairingRequest,
+  readHostedPairingRequest,
+} from "./hostedPairing";
+
+describe("hostedPairing", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("reads hosted pairing host and query token parameters", () => {
+    const url = new URL("https://app.t3.codes/pair?host=100.64.1.2:3773&token=ABCD1234");
+
+    expect(readHostedPairingRequest(url)).toEqual({
+      host: "100.64.1.2:3773",
+      token: "ABCD1234",
+      label: "",
+    });
+    expect(hasHostedPairingRequest(url)).toBe(true);
+  });
+
+  it("prefers hash tokens so generated hosted links do not put credentials in search params", () => {
+    vi.stubEnv("VITE_HOSTED_APP_URL", "https://preview.t3.codes");
+
+    const url = new URL(
+      buildHostedPairingUrl({
+        host: "https://backend.example.com:3773",
+        token: "pairing-token",
+        label: "Workstation",
+      }),
+    );
+
+    expect(url.origin).toBe("https://preview.t3.codes");
+    expect(url.pathname).toBe("/pair");
+    expect(url.searchParams.get("host")).toBe("https://backend.example.com:3773");
+    expect(url.searchParams.get("label")).toBe("Workstation");
+    expect(url.searchParams.has("token")).toBe(false);
+    expect(url.hash).toBe("#token=pairing-token");
+  });
+
+  it("ignores incomplete hosted pairing requests", () => {
+    expect(
+      hasHostedPairingRequest(new URL("https://app.t3.codes/pair?host=backend.example.com")),
+    ).toBe(false);
+    expect(hasHostedPairingRequest(new URL("https://app.t3.codes/pair?token=ABCD1234"))).toBe(
+      false,
+    );
+  });
+});
diff --git a/apps/web/src/hostedPairing.ts b/apps/web/src/hostedPairing.ts
new file mode 100644
index 00000000000..9855c01be2b
--- /dev/null
+++ b/apps/web/src/hostedPairing.ts
@@ -0,0 +1,49 @@
+import { getPairingTokenFromUrl, setPairingTokenOnUrl } from "./pairingUrl";
+
+const DEFAULT_HOSTED_APP_URL = "https://app.t3.codes";
+
+export interface HostedPairingRequest {
+  readonly host: string;
+  readonly token: string;
+  readonly label: string;
+}
+
+function configuredHostedAppUrl(): string {
+  return import.meta.env.VITE_HOSTED_APP_URL?.trim() || DEFAULT_HOSTED_APP_URL;
+}
+
+export function readHostedPairingRequest(url: URL = new URL(window.location.href)) {
+  const host = url.searchParams.get("host")?.trim() ?? "";
+  const token = getPairingTokenFromUrl(url)?.trim() ?? "";
+  const label = url.searchParams.get("label")?.trim() ?? "";
+
+  if (!host || !token) {
+    return null;
+  }
+
+  return {
+    host,
+    token,
+    label,
+  } satisfies HostedPairingRequest;
+}
+
+export function hasHostedPairingRequest(url: URL = new URL(window.location.href)): boolean {
+  return readHostedPairingRequest(url) !== null;
+}
+
+export function buildHostedPairingUrl(input: {
+  readonly host: string;
+  readonly token: string;
+  readonly label?: string | null;
+}): string {
+  const url = new URL("/pair", configuredHostedAppUrl());
+  url.searchParams.set("host", input.host);
+
+  const label = input.label?.trim();
+  if (label) {
+    url.searchParams.set("label", label);
+  }
+
+  return setPairingTokenOnUrl(url, input.token).toString();
+}
diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index c872a5f1030..17fa75af675 100644
--- a/apps/web/src/localApi.ts
+++ b/apps/web/src/localApi.ts
@@ -13,6 +13,7 @@ import {
   getPrimaryEnvironmentConnection,
   resetEnvironmentServiceForTests,
 } from "./environments/runtime";
+import { getPrimaryKnownEnvironment } from "./environments/primary";
 import { type WsRpcClient } from "./rpc/wsRpcClient";
 import { showContextMenuFallback } from "./contextMenuFallback";
 import {
@@ -27,7 +28,11 @@ import {
 
 let cachedApi: LocalApi | undefined;
 
-export function createLocalApi(rpcClient: WsRpcClient): LocalApi {
+function unavailableLocalBackendError(): Error {
+  return new Error("Local backend API is unavailable before a backend is paired.");
+}
+
+function createBrowserLocalApi(rpcClient?: WsRpcClient): LocalApi {
   return {
     dialogs: {
       pickFolder: async (options) => {
@@ -42,7 +47,10 @@ export function createLocalApi(rpcClient: WsRpcClient): LocalApi {
       },
     },
     shell: {
-      openInEditor: (cwd, editor) => rpcClient.shell.openInEditor({ cwd, editor }),
+      openInEditor: (cwd, editor) =>
+        rpcClient
+          ? rpcClient.shell.openInEditor({ cwd, editor })
+          : Promise.reject(unavailableLocalBackendError()),
       openExternal: async (url) => {
         if (window.desktopBridge) {
           const opened = await window.desktopBridge.openExternal(url);
@@ -111,16 +119,34 @@ export function createLocalApi(rpcClient: WsRpcClient): LocalApi {
       },
     },
     server: {
-      getConfig: rpcClient.server.getConfig,
-      refreshProviders: rpcClient.server.refreshProviders,
-      upsertKeybinding: rpcClient.server.upsertKeybinding,
-      getSettings: rpcClient.server.getSettings,
-      updateSettings: rpcClient.server.updateSettings,
-      discoverSourceControl: rpcClient.server.discoverSourceControl,
+      getConfig: () =>
+        rpcClient ? rpcClient.server.getConfig() : Promise.reject(unavailableLocalBackendError()),
+      refreshProviders: () =>
+        rpcClient
+          ? rpcClient.server.refreshProviders()
+          : Promise.reject(unavailableLocalBackendError()),
+      upsertKeybinding: (input) =>
+        rpcClient
+          ? rpcClient.server.upsertKeybinding(input)
+          : Promise.reject(unavailableLocalBackendError()),
+      getSettings: () =>
+        rpcClient ? rpcClient.server.getSettings() : Promise.reject(unavailableLocalBackendError()),
+      updateSettings: (patch) =>
+        rpcClient
+          ? rpcClient.server.updateSettings(patch)
+          : Promise.reject(unavailableLocalBackendError()),
+      discoverSourceControl: (input) =>
+        rpcClient
+          ? rpcClient.server.discoverSourceControl(input)
+          : Promise.reject(unavailableLocalBackendError()),
     },
   };
 }
 
+export function createLocalApi(rpcClient: WsRpcClient): LocalApi {
+  return createBrowserLocalApi(rpcClient);
+}
+
 export function readLocalApi(): LocalApi | undefined {
   if (typeof window === "undefined") return undefined;
   if (cachedApi) return cachedApi;
@@ -130,7 +156,10 @@ export function readLocalApi(): LocalApi | undefined {
     return cachedApi;
   }
 
-  cachedApi = createLocalApi(getPrimaryEnvironmentConnection().client);
+  const primaryEnvironment = getPrimaryKnownEnvironment();
+  cachedApi = primaryEnvironment
+    ? createLocalApi(getPrimaryEnvironmentConnection().client)
+    : createBrowserLocalApi();
   return cachedApi;
 }
 
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 87e8667901d..fb33c6ae238 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -46,26 +46,52 @@ import { syncBrowserChromeTheme } from "../hooks/useTheme";
 import {
   ensureEnvironmentConnectionBootstrapped,
   getPrimaryEnvironmentConnection,
+  listSavedEnvironmentRecords,
+  waitForSavedEnvironmentRegistryHydration,
   startEnvironmentConnectionService,
+  useSavedEnvironmentRegistryStore,
 } from "../environments/runtime";
 import { configureClientTracing } from "../observability/clientTracing";
 import {
   ensurePrimaryEnvironmentReady,
+  getPrimaryKnownEnvironment,
   resolveInitialServerAuthGateState,
   updatePrimaryEnvironmentDescriptor,
 } from "../environments/primary";
+import { hasHostedPairingRequest } from "../hostedPairing";
 
 export const Route = createRootRouteWithContext<{
   queryClient: QueryClient;
 }>()({
-  beforeLoad: async () => {
-    const [, authGateState] = await Promise.all([
-      ensurePrimaryEnvironmentReady(),
-      resolveInitialServerAuthGateState(),
-    ]);
-    return {
-      authGateState,
-    };
+  beforeLoad: async ({ location }) => {
+    if (location.pathname === "/pair" && hasHostedPairingRequest(new URL(window.location.href))) {
+      return {
+        authGateState: {
+          status: "hosted-pairing",
+        } as const,
+      };
+    }
+
+    try {
+      const [, authGateState] = await Promise.all([
+        ensurePrimaryEnvironmentReady(),
+        resolveInitialServerAuthGateState(),
+      ]);
+      return {
+        authGateState,
+      };
+    } catch (error) {
+      if (location.pathname === "/pair") {
+        throw error;
+      }
+
+      await waitForSavedEnvironmentRegistryHydration();
+      return {
+        authGateState: {
+          status: "hosted-static",
+        } as const,
+      };
+    }
   },
   component: RootRouteView,
   errorComponent: RootRouteErrorView,
@@ -91,7 +117,7 @@ function RootRouteView() {
     return <Outlet />;
   }
 
-  if (authGateState.status !== "authenticated") {
+  if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
     return <Outlet />;
   }
   return (
@@ -100,6 +126,7 @@ function RootRouteView() {
         <AuthenticatedTracingBootstrap />
         <ServerStateBootstrap />
         <EnvironmentConnectionManagerBootstrap />
+        <HostedStaticEnvironmentBootstrap />
         <EventRouter />
         <WebSocketConnectionCoordinator />
         <SlowRpcAckToastCoordinator />
@@ -115,6 +142,32 @@ function RootRouteView() {
   );
 }
 
+function HostedStaticEnvironmentBootstrap() {
+  const savedEnvironmentCount = useSavedEnvironmentRegistryStore(
+    (state) => Object.keys(state.byId).length,
+  );
+
+  useEffect(() => {
+    if (getPrimaryKnownEnvironment()) {
+      return;
+    }
+
+    const currentActiveEnvironmentId = useStore.getState().activeEnvironmentId;
+    if (currentActiveEnvironmentId) {
+      return;
+    }
+
+    const firstSavedEnvironment = listSavedEnvironmentRecords()[0];
+    if (!firstSavedEnvironment) {
+      return;
+    }
+
+    useStore.getState().setActiveEnvironmentId(firstSavedEnvironment.environmentId);
+  }, [savedEnvironmentCount]);
+
+  return null;
+}
+
 function RootRouteErrorView({ error, reset }: ErrorComponentProps) {
   const message = errorMessage(error);
   const details = errorDetails(error);
@@ -187,7 +240,13 @@ function errorDetails(error: unknown): string {
 }
 
 function ServerStateBootstrap() {
-  useEffect(() => startServerStateSync(getPrimaryEnvironmentConnection().client.server), []);
+  useEffect(() => {
+    if (!getPrimaryKnownEnvironment()) {
+      return;
+    }
+
+    return startServerStateSync(getPrimaryEnvironmentConnection().client.server);
+  }, []);
 
   return null;
 }
diff --git a/apps/web/src/routes/_chat.tsx b/apps/web/src/routes/_chat.tsx
index fb8191f4480..da22d7e6028 100644
--- a/apps/web/src/routes/_chat.tsx
+++ b/apps/web/src/routes/_chat.tsx
@@ -108,7 +108,10 @@ function ChatRouteLayout() {
 
 export const Route = createFileRoute("/_chat")({
   beforeLoad: async ({ context }) => {
-    if (context.authGateState.status !== "authenticated") {
+    if (
+      context.authGateState.status !== "authenticated" &&
+      context.authGateState.status !== "hosted-static"
+    ) {
       throw redirect({ to: "/pair", replace: true });
     }
   },
diff --git a/apps/web/src/routes/pair.tsx b/apps/web/src/routes/pair.tsx
index 6925dac69cc..6575cd1bafa 100644
--- a/apps/web/src/routes/pair.tsx
+++ b/apps/web/src/routes/pair.tsx
@@ -1,11 +1,21 @@
 import { createFileRoute, redirect, useNavigate } from "@tanstack/react-router";
 
-import { PairingPendingSurface, PairingRouteSurface } from "../components/auth/PairingRouteSurface";
+import {
+  HostedPairingRouteSurface,
+  PairingPendingSurface,
+  PairingRouteSurface,
+} from "../components/auth/PairingRouteSurface";
 
 export const Route = createFileRoute("/pair")({
   beforeLoad: async ({ context }) => {
     const { authGateState } = context;
-    if (authGateState.status === "authenticated") {
+    if (authGateState.status === "hosted-pairing") {
+      return {
+        authGateState,
+      };
+    }
+
+    if (authGateState.status === "authenticated" || authGateState.status === "hosted-static") {
       throw redirect({ to: "/", replace: true });
     }
     return {
@@ -24,6 +34,10 @@ function PairRouteView() {
     return null;
   }
 
+  if (authGateState.status === "hosted-pairing") {
+    return <HostedPairingRouteSurface />;
+  }
+
   return (
     <PairingRouteSurface
       auth={authGateState.auth}
diff --git a/apps/web/src/routes/settings.tsx b/apps/web/src/routes/settings.tsx
index c78d129a46a..ec98e7ee363 100644
--- a/apps/web/src/routes/settings.tsx
+++ b/apps/web/src/routes/settings.tsx
@@ -104,7 +104,10 @@ function SettingsRouteLayout() {
 
 export const Route = createFileRoute("/settings")({
   beforeLoad: async ({ context, location }) => {
-    if (context.authGateState.status !== "authenticated") {
+    if (
+      context.authGateState.status !== "authenticated" &&
+      context.authGateState.status !== "hosted-static"
+    ) {
       throw redirect({ to: "/pair", replace: true });
     }
 
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index d4042c2e88e..90d8689c81c 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -9,6 +9,7 @@ const port = Number(process.env.PORT ?? 5733);
 const host = process.env.HOST?.trim() || "localhost";
 const configuredHttpUrl = process.env.VITE_HTTP_URL?.trim();
 const configuredWsUrl = process.env.VITE_WS_URL?.trim();
+const configuredHostedAppUrl = process.env.VITE_HOSTED_APP_URL?.trim();
 const sourcemapEnv = process.env.T3CODE_WEB_SOURCEMAP?.trim().toLowerCase();
 
 const buildSourcemap =
@@ -68,6 +69,7 @@ export default defineConfig({
     "import.meta.env.VITE_HTTP_URL": JSON.stringify(configuredHttpUrl ?? ""),
     // In dev mode, tell the web app where the WebSocket server lives
     "import.meta.env.VITE_WS_URL": JSON.stringify(configuredWsUrl ?? ""),
+    "import.meta.env.VITE_HOSTED_APP_URL": JSON.stringify(configuredHostedAppUrl ?? ""),
     "import.meta.env.APP_VERSION": JSON.stringify(pkg.version),
   },
   resolve: {

From 9033cb38ada7011e108065cfe25f94ef44dbda31 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:43:08 -0700
Subject: [PATCH 02/74] fix(web): keep hosted pairing to secure endpoints

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .../settings/ConnectionsSettings.tsx          | 15 +-----
 .../components/settings/pairingUrls.test.ts   | 24 ++++++++++
 .../src/components/settings/pairingUrls.ts    | 20 ++++++++
 .../service.threadSubscriptions.test.ts       | 47 +++++++++++++++----
 apps/web/src/environments/runtime/service.ts  |  2 +-
 5 files changed, 83 insertions(+), 25 deletions(-)
 create mode 100644 apps/web/src/components/settings/pairingUrls.test.ts
 create mode 100644 apps/web/src/components/settings/pairingUrls.ts

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 50af9f88596..f6ab384d9fb 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -9,9 +9,9 @@ import {
 import { DateTime } from "effect";
 
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
-import { buildHostedPairingUrl } from "../../hostedPairing";
 import { cn } from "../../lib/utils";
 import { formatElapsedDurationLabel, formatExpiresInLabel } from "../../timestampFormat";
+import { resolveDesktopPairingUrl, resolveHostedPairingUrl } from "./pairingUrls";
 import {
   SettingsPageContainer,
   SettingsRow,
@@ -244,19 +244,6 @@ function removeDesktopClientSession(
   return current.filter((clientSession) => clientSession.sessionId !== sessionId);
 }
 
-function resolveDesktopPairingUrl(endpointUrl: string, credential: string): string {
-  const url = new URL(endpointUrl);
-  url.pathname = "/pair";
-  return setPairingTokenOnUrl(url, credential).toString();
-}
-
-function resolveHostedPairingUrl(endpointUrl: string, credential: string): string {
-  return buildHostedPairingUrl({
-    host: endpointUrl,
-    token: credential,
-  });
-}
-
 function resolveCurrentOriginPairingUrl(credential: string): string {
   const url = new URL("/pair", window.location.href);
   return setPairingTokenOnUrl(url, credential).toString();
diff --git a/apps/web/src/components/settings/pairingUrls.test.ts b/apps/web/src/components/settings/pairingUrls.test.ts
new file mode 100644
index 00000000000..b32f5c51b32
--- /dev/null
+++ b/apps/web/src/components/settings/pairingUrls.test.ts
@@ -0,0 +1,24 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { resolveDesktopPairingUrl, resolveHostedPairingUrl } from "./pairingUrls";
+
+describe("settings pairing URL helpers", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("uses direct backend pairing URLs for HTTP endpoints", () => {
+    expect(resolveHostedPairingUrl("http://192.168.1.44:3773", "PAIRCODE")).toBeNull();
+    expect(resolveDesktopPairingUrl("http://192.168.1.44:3773", "PAIRCODE")).toBe(
+      "http://192.168.1.44:3773/pair#token=PAIRCODE",
+    );
+  });
+
+  it("uses hosted pairing URLs for HTTPS endpoints", () => {
+    vi.stubEnv("VITE_HOSTED_APP_URL", "https://preview.t3.codes");
+
+    expect(resolveHostedPairingUrl("https://host.tailnet.example.ts.net:3773", "PAIRCODE")).toBe(
+      "https://preview.t3.codes/pair?host=https%3A%2F%2Fhost.tailnet.example.ts.net%3A3773#token=PAIRCODE",
+    );
+  });
+});
diff --git a/apps/web/src/components/settings/pairingUrls.ts b/apps/web/src/components/settings/pairingUrls.ts
new file mode 100644
index 00000000000..891fe04ad6b
--- /dev/null
+++ b/apps/web/src/components/settings/pairingUrls.ts
@@ -0,0 +1,20 @@
+import { buildHostedPairingUrl } from "../../hostedPairing";
+import { setPairingTokenOnUrl } from "../../pairingUrl";
+
+export function resolveDesktopPairingUrl(endpointUrl: string, credential: string): string {
+  const url = new URL(endpointUrl);
+  url.pathname = "/pair";
+  return setPairingTokenOnUrl(url, credential).toString();
+}
+
+export function resolveHostedPairingUrl(endpointUrl: string, credential: string): string | null {
+  const url = new URL(endpointUrl);
+  if (url.protocol !== "https:") {
+    return null;
+  }
+
+  return buildHostedPairingUrl({
+    host: endpointUrl,
+    token: credential,
+  });
+}
diff --git a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
index efecfdca8e9..eb5f9d7b20e 100644
--- a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
+++ b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
@@ -16,22 +16,14 @@ const mockCreateWsRpcClient = vi.fn();
 const mockWaitForSavedEnvironmentRegistryHydration = vi.fn();
 const mockListSavedEnvironmentRecords = vi.fn();
 const mockSavedEnvironmentRegistrySubscribe = vi.fn();
+const mockGetPrimaryKnownEnvironment = vi.hoisted(() => vi.fn());
 
 function MockWsTransport() {
   return undefined;
 }
 
 vi.mock("../primary", () => ({
-  getPrimaryKnownEnvironment: vi.fn(() => ({
-    id: "env-1",
-    label: "Primary environment",
-    source: "window-origin",
-    target: {
-      httpBaseUrl: "http://127.0.0.1:3000/",
-      wsBaseUrl: "ws://127.0.0.1:3000/",
-    },
-    environmentId: EnvironmentId.make("env-1"),
-  })),
+  getPrimaryKnownEnvironment: mockGetPrimaryKnownEnvironment,
 }));
 
 vi.mock("./catalog", () => ({
@@ -145,6 +137,16 @@ describe("retainThreadDetailSubscription", () => {
     vi.useFakeTimers();
     vi.resetModules();
     vi.clearAllMocks();
+    mockGetPrimaryKnownEnvironment.mockReturnValue({
+      id: "env-1",
+      label: "Primary environment",
+      source: "window-origin",
+      target: {
+        httpBaseUrl: "http://127.0.0.1:3000/",
+        wsBaseUrl: "ws://127.0.0.1:3000/",
+      },
+      environmentId: EnvironmentId.make("env-1"),
+    });
 
     mockThreadUnsubscribe.mockImplementation(() => undefined);
     mockSubscribeThread.mockImplementation(() => mockThreadUnsubscribe);
@@ -204,6 +206,31 @@ describe("retainThreadDetailSubscription", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("does not start the primary connection until the known environment has an id", async () => {
+    mockGetPrimaryKnownEnvironment.mockReturnValue({
+      id: "env-1",
+      label: "Primary environment",
+      source: "window-origin",
+      target: {
+        httpBaseUrl: "http://127.0.0.1:3000/",
+        wsBaseUrl: "ws://127.0.0.1:3000/",
+      },
+    });
+    const {
+      listEnvironmentConnections,
+      resetEnvironmentServiceForTests,
+      startEnvironmentConnectionService,
+    } = await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+
+    expect(mockCreateEnvironmentConnection).not.toHaveBeenCalled();
+    expect(listEnvironmentConnections()).toEqual([]);
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
   it("keeps non-idle thread detail subscriptions attached until the thread becomes idle", async () => {
     const {
       retainThreadDetailSubscription,
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index ec920e9a7be..6c58f9e8a53 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -906,7 +906,7 @@ function createPrimaryEnvironmentConnection(): EnvironmentConnection {
 }
 
 function maybeCreatePrimaryEnvironmentConnection(): EnvironmentConnection | null {
-  return getPrimaryKnownEnvironment() ? createPrimaryEnvironmentConnection() : null;
+  return getPrimaryKnownEnvironment()?.environmentId ? createPrimaryEnvironmentConnection() : null;
 }
 
 async function ensureSavedEnvironmentConnection(

From 94acd222c5c812ccd4b19e10d4664eafc5e45977 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:55:24 -0700
Subject: [PATCH 03/74] docs(remote): document hosted pairing constraints

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .docs/remote-architecture.md | 26 ++++++++++++++++++++++++++
 REMOTE.md                    | 16 ++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/.docs/remote-architecture.md b/.docs/remote-architecture.md
index 32e35d7cafa..8e5ed37928e 100644
--- a/.docs/remote-architecture.md
+++ b/.docs/remote-architecture.md
@@ -93,6 +93,8 @@ Examples:
 
 A known environment may or may not know the target `environmentId` before first successful connect.
 
+In the hosted web app, known environments are browser-local. A hosted pairing URL can create the saved entry, but it does not give the hosted app a server-side control plane or a copy of the session state.
+
 ### AccessEndpoint
 
 An `AccessEndpoint` is one concrete way to reach a known environment.
@@ -108,6 +110,26 @@ A single environment may have many endpoints:
 
 The environment stays the same. Only the access path changes.
 
+### Hosted pairing request
+
+A hosted pairing request is a bootstrap URL for the static web app, not a transport.
+
+Example:
+
+```text
+https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
+```
+
+The hosted app reads the `host` parameter and pairing token, exchanges the token directly with that backend, then saves the resulting environment record in browser local storage.
+
+Important constraints:
+
+- the hosted app does not proxy HTTP or WebSocket traffic
+- the backend must still be reachable directly from the browser
+- HTTPS pages can only connect to HTTPS/WSS backends
+- HTTP LAN endpoints should keep using direct desktop or CLI pairing URLs
+- the token belongs in the URL hash so it is not sent to the hosted app origin
+
 ### RepositoryIdentity
 
 `RepositoryIdentity` remains a best-effort logical repo grouping mechanism across environments.
@@ -151,6 +173,8 @@ Benefits:
 - no client-specific process management required
 - best fit for hosted or self-managed remote T3 deployments
 
+Browser security rules are part of this access method. A hosted HTTPS web client can connect to `wss://` backends, but it cannot connect to plain `ws://` or `http://` LAN backends because that would be mixed content.
+
 ### 2. Tunneled WebSocket access
 
 Examples:
@@ -267,6 +291,8 @@ T3 already supports a WebSocket auth token on the server. That should become a f
 
 For publicly reachable environments, authenticated access should be treated as required.
 
+Hosted pairing should be treated as a client-side convenience only. The hosted app must not receive pairing tokens through query parameters, must not store pairing state server-side, and must not imply that an HTTP backend is safe or reachable from an HTTPS browser context.
+
 ## Relationship to Zed
 
 Zed is a useful reference implementation for managed remote launch and reconnect behavior.
diff --git a/REMOTE.md b/REMOTE.md
index 30dc562792f..cec7b0ecccb 100644
--- a/REMOTE.md
+++ b/REMOTE.md
@@ -47,6 +47,7 @@ From there, connect from another device in either of these ways:
 - scan the QR code on your phone
 - in the desktop app, enter the full pairing URL
 - in the desktop app, enter the host and token separately
+- in the hosted web app, open a hosted pairing URL when the backend is reachable over HTTPS
 
 Use `t3 serve --help` for the full flag reference. It supports the same general startup options as the normal server command, including an optional `cwd` argument.
 
@@ -67,6 +68,20 @@ Instead:
 
 After pairing, future access is session-based. You do not need to keep reusing the original token unless you are pairing a new device.
 
+## Hosted Web App Pairing
+
+The hosted web app at `https://app.t3.codes` can save a remote backend in browser local storage from a URL like:
+
+```text
+https://app.t3.codes/pair?host=https://backend.example.com:3773#token=PAIRCODE
+```
+
+Use hosted pairing when the backend is reachable from the browser over HTTPS/WSS. This includes a backend behind a trusted HTTPS tunnel or another HTTPS endpoint you operate.
+
+Do not use hosted pairing for plain HTTP LAN URLs such as `http://192.168.x.y:3773`. Browsers block an HTTPS page from connecting to an insecure HTTP or WS backend. For those endpoints, use the direct pairing URL shown by the desktop app or CLI from a client that can open that HTTP URL directly.
+
+Hosted pairing does not proxy traffic through T3 Code. The browser still connects directly to the backend URL in the pairing link.
+
 ## Managing Access Later
 
 Use `t3 auth` to manage access after the initial pairing flow.
@@ -84,4 +99,5 @@ Use `t3 auth --help` and the nested subcommand help pages for the full reference
 - Treat pairing URLs and pairing tokens like passwords.
 - Prefer binding `--host` to a trusted private address, such as a Tailnet IP, instead of exposing the server broadly.
 - Anyone with a valid pairing credential can create a session until that credential expires or is revoked.
+- Hosted pairing links keep the credential in the URL hash so it is not sent to the hosted app server, but it can still be exposed through browser history, screenshots, logs, or copy/paste.
 - Use `t3 auth` to revoke credentials or sessions you no longer trust.

From 9813692378bf777e0fa7059fe9e9e954693b8b41 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 23:34:48 -0700
Subject: [PATCH 04/74] fix(web): treat hosted app as static

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .gitignore                          |  1 +
 apps/web/src/hostedPairing.test.ts  | 14 ++++++++
 apps/web/src/hostedPairing.ts       | 21 +++++++++++
 apps/web/src/routes/__root.tsx      | 43 +++++++++++++++-------
 apps/web/src/routes/_chat.index.tsx | 55 +++++++++++++++++++++++++++++
 apps/web/src/vite-env.d.ts          |  3 ++
 apps/web/vercel.json                |  8 +++++
 apps/web/vite.config.ts             | 10 +++++-
 8 files changed, 141 insertions(+), 14 deletions(-)
 create mode 100644 apps/web/vercel.json

diff --git a/.gitignore b/.gitignore
index 6c48782f9ac..9e14e917910 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,3 +22,4 @@ apps/web/src/components/__screenshots__
 __screenshots__/
 .tanstack
 squashfs-root/
+.vercel
diff --git a/apps/web/src/hostedPairing.test.ts b/apps/web/src/hostedPairing.test.ts
index f347ca46ab5..ef2b2eb5279 100644
--- a/apps/web/src/hostedPairing.test.ts
+++ b/apps/web/src/hostedPairing.test.ts
@@ -3,6 +3,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   buildHostedPairingUrl,
   hasHostedPairingRequest,
+  isHostedStaticApp,
   readHostedPairingRequest,
 } from "./hostedPairing";
 
@@ -49,4 +50,17 @@ describe("hostedPairing", () => {
       false,
     );
   });
+
+  it("detects the hosted static app only when no backend URL is configured", () => {
+    vi.stubEnv("VITE_HOSTED_APP_URL", "https://preview.t3.codes");
+    vi.stubEnv("VITE_HTTP_URL", "");
+    vi.stubEnv("VITE_WS_URL", "");
+
+    expect(isHostedStaticApp(new URL("https://preview.t3.codes/"))).toBe(true);
+    expect(isHostedStaticApp(new URL("https://preview.t3.codes/pair"))).toBe(true);
+    expect(isHostedStaticApp(new URL("https://backend.example.com/"))).toBe(false);
+
+    vi.stubEnv("VITE_HTTP_URL", "https://backend.example.com");
+    expect(isHostedStaticApp(new URL("https://preview.t3.codes/"))).toBe(false);
+  });
 });
diff --git a/apps/web/src/hostedPairing.ts b/apps/web/src/hostedPairing.ts
index 9855c01be2b..a44cfa70834 100644
--- a/apps/web/src/hostedPairing.ts
+++ b/apps/web/src/hostedPairing.ts
@@ -12,6 +12,27 @@ function configuredHostedAppUrl(): string {
   return import.meta.env.VITE_HOSTED_APP_URL?.trim() || DEFAULT_HOSTED_APP_URL;
 }
 
+function configuredBackendUrl(): string {
+  return import.meta.env.VITE_HTTP_URL?.trim() || import.meta.env.VITE_WS_URL?.trim() || "";
+}
+
+function originFromUrl(value: string): string | null {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+export function isHostedStaticApp(url: URL = new URL(window.location.href)): boolean {
+  if (configuredBackendUrl()) {
+    return false;
+  }
+
+  const hostedOrigin = originFromUrl(configuredHostedAppUrl());
+  return hostedOrigin !== null && url.origin === hostedOrigin;
+}
+
 export function readHostedPairingRequest(url: URL = new URL(window.location.href)) {
   const host = url.searchParams.get("host")?.trim() ?? "";
   const token = getPairingTokenFromUrl(url)?.trim() ?? "";
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index fb33c6ae238..df62be29dfa 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -58,7 +58,7 @@ import {
   resolveInitialServerAuthGateState,
   updatePrimaryEnvironmentDescriptor,
 } from "../environments/primary";
-import { hasHostedPairingRequest } from "../hostedPairing";
+import { hasHostedPairingRequest, isHostedStaticApp } from "../hostedPairing";
 
 export const Route = createRootRouteWithContext<{
   queryClient: QueryClient;
@@ -72,6 +72,15 @@ export const Route = createRootRouteWithContext<{
       };
     }
 
+    if (isHostedStaticApp(new URL(window.location.href))) {
+      await waitForSavedEnvironmentRegistryHydration();
+      return {
+        authGateState: {
+          status: "hosted-static",
+        } as const,
+      };
+    }
+
     try {
       const [, authGateState] = await Promise.all([
         ensurePrimaryEnvironmentReady(),
@@ -103,6 +112,7 @@ export const Route = createRootRouteWithContext<{
 function RootRouteView() {
   const pathname = useLocation({ select: (location) => location.pathname });
   const { authGateState } = Route.useRouteContext();
+  const primaryEnvironmentAuthenticated = authGateState.status === "authenticated";
 
   useEffect(() => {
     const frame = window.requestAnimationFrame(() => {
@@ -120,23 +130,30 @@ function RootRouteView() {
   if (authGateState.status !== "authenticated" && authGateState.status !== "hosted-static") {
     return <Outlet />;
   }
+
+  const appShell = (
+    <CommandPalette>
+      <AppSidebarLayout>
+        <Outlet />
+      </AppSidebarLayout>
+    </CommandPalette>
+  );
+
   return (
     <ToastProvider>
       <AnchoredToastProvider>
-        <AuthenticatedTracingBootstrap />
-        <ServerStateBootstrap />
+        {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
+        {primaryEnvironmentAuthenticated ? <ServerStateBootstrap /> : null}
         <EnvironmentConnectionManagerBootstrap />
         <HostedStaticEnvironmentBootstrap />
-        <EventRouter />
-        <WebSocketConnectionCoordinator />
-        <SlowRpcAckToastCoordinator />
-        <WebSocketConnectionSurface>
-          <CommandPalette>
-            <AppSidebarLayout>
-              <Outlet />
-            </AppSidebarLayout>
-          </CommandPalette>
-        </WebSocketConnectionSurface>
+        {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
+        {primaryEnvironmentAuthenticated ? <WebSocketConnectionCoordinator /> : null}
+        {primaryEnvironmentAuthenticated ? <SlowRpcAckToastCoordinator /> : null}
+        {primaryEnvironmentAuthenticated ? (
+          <WebSocketConnectionSurface>{appShell}</WebSocketConnectionSurface>
+        ) : (
+          appShell
+        )}
       </AnchoredToastProvider>
     </ToastProvider>
   );
diff --git a/apps/web/src/routes/_chat.index.tsx b/apps/web/src/routes/_chat.index.tsx
index 43f06177a74..98a125bdfe4 100644
--- a/apps/web/src/routes/_chat.index.tsx
+++ b/apps/web/src/routes/_chat.index.tsx
@@ -1,11 +1,66 @@
 import { createFileRoute } from "@tanstack/react-router";
+import { LinkIcon, PlusIcon } from "lucide-react";
 
 import { NoActiveThreadState } from "../components/NoActiveThreadState";
+import { Button } from "../components/ui/button";
+import { Empty, EmptyDescription, EmptyHeader, EmptyTitle } from "../components/ui/empty";
+import { SidebarInset, SidebarTrigger } from "../components/ui/sidebar";
+import { useSavedEnvironmentRegistryStore } from "../environments/runtime";
+import { APP_DISPLAY_NAME } from "~/branding";
 
 function ChatIndexRouteView() {
+  const { authGateState } = Route.useRouteContext();
+  const savedEnvironmentCount = useSavedEnvironmentRegistryStore(
+    (state) => Object.keys(state.byId).length,
+  );
+
+  if (authGateState.status === "hosted-static" && savedEnvironmentCount === 0) {
+    return <HostedStaticOnboardingState />;
+  }
+
   return <NoActiveThreadState />;
 }
 
 export const Route = createFileRoute("/_chat/")({
   component: ChatIndexRouteView,
 });
+
+function HostedStaticOnboardingState() {
+  return (
+    <SidebarInset className="h-dvh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground">
+      <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-x-hidden bg-background">
+        <header className="border-b border-border px-3 py-2 sm:px-5 sm:py-3">
+          <div className="flex items-center gap-2">
+            <SidebarTrigger className="size-7 shrink-0 md:hidden" />
+            <span className="text-sm font-medium text-foreground md:text-muted-foreground/60">
+              {APP_DISPLAY_NAME}
+            </span>
+          </div>
+        </header>
+
+        <Empty className="flex-1">
+          <div className="w-full max-w-xl rounded-3xl border border-border/55 bg-card/20 px-8 py-12 shadow-sm/5">
+            <EmptyHeader className="max-w-none">
+              <div className="mx-auto mb-5 flex size-11 items-center justify-center rounded-xl border border-border/70 bg-background/70 text-muted-foreground">
+                <LinkIcon className="size-5" />
+              </div>
+              <EmptyTitle className="text-foreground text-xl">
+                Connect an environment to get started
+              </EmptyTitle>
+              <EmptyDescription className="mt-2 text-sm leading-relaxed text-muted-foreground/78">
+                Open a pairing link from your T3 Code desktop app or add a reachable backend
+                manually. Your saved environments stay in this browser.
+              </EmptyDescription>
+              <div className="mt-6 flex justify-center">
+                <Button render={<a href="/settings/connections" />} size="sm">
+                  <PlusIcon className="size-4" />
+                  Add environment
+                </Button>
+              </div>
+            </EmptyHeader>
+          </div>
+        </Empty>
+      </div>
+    </SidebarInset>
+  );
+}
diff --git a/apps/web/src/vite-env.d.ts b/apps/web/src/vite-env.d.ts
index 1d7d41db1bc..99c5a65d85e 100644
--- a/apps/web/src/vite-env.d.ts
+++ b/apps/web/src/vite-env.d.ts
@@ -3,6 +3,9 @@
 import type { DesktopBridge, LocalApi } from "@t3tools/contracts";
 
 interface ImportMetaEnv {
+  readonly VITE_HTTP_URL: string;
+  readonly VITE_WS_URL: string;
+  readonly VITE_HOSTED_APP_URL: string;
   readonly APP_VERSION: string;
 }
 
diff --git a/apps/web/vercel.json b/apps/web/vercel.json
new file mode 100644
index 00000000000..1323cdac34c
--- /dev/null
+++ b/apps/web/vercel.json
@@ -0,0 +1,8 @@
+{
+  "rewrites": [
+    {
+      "source": "/(.*)",
+      "destination": "/index.html"
+    }
+  ]
+}
diff --git a/apps/web/vite.config.ts b/apps/web/vite.config.ts
index 90d8689c81c..cea7ce71ec9 100644
--- a/apps/web/vite.config.ts
+++ b/apps/web/vite.config.ts
@@ -9,7 +9,15 @@ const port = Number(process.env.PORT ?? 5733);
 const host = process.env.HOST?.trim() || "localhost";
 const configuredHttpUrl = process.env.VITE_HTTP_URL?.trim();
 const configuredWsUrl = process.env.VITE_WS_URL?.trim();
-const configuredHostedAppUrl = process.env.VITE_HOSTED_APP_URL?.trim();
+const configuredHostedAppUrl = (() => {
+  if (process.env.VERCEL_ENV === "production" && process.env.VERCEL_PROJECT_PRODUCTION_URL) {
+    return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`;
+  }
+  if (process.env.VERCEL_URL) {
+    return `https://${process.env.VERCEL_URL}`;
+  }
+  return process.env.VITE_HOSTED_APP_URL?.trim();
+})();
 const sourcemapEnv = process.env.T3CODE_WEB_SOURCEMAP?.trim().toLowerCase();
 
 const buildSourcemap =

From e227b7874a20f81a62f170cc5950eee5d06d9958 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:13:05 -0700
Subject: [PATCH 05/74] feat(remote): add advertised endpoint registry

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/package.json                     |   1 +
 apps/desktop/src/main.ts                      |  31 +-
 apps/desktop/src/preload.ts                   |   2 +
 apps/desktop/src/serverExposure.test.ts       |  97 +++++-
 apps/desktop/src/serverExposure.ts            |  95 +++++-
 .../settings/ConnectionsSettings.tsx          | 278 ++++++++++++------
 .../settings/SettingsPanels.browser.tsx       |   2 +
 apps/web/src/localApi.test.ts                 |   1 +
 bun.lock                                      |   1 +
 .../src/advertisedEndpoint.test.ts            |  61 ++++
 .../client-runtime/src/advertisedEndpoint.ts  |  78 +++++
 packages/client-runtime/src/index.ts          |   1 +
 packages/contracts/src/index.ts               |   1 +
 packages/contracts/src/ipc.ts                 |   2 +
 packages/contracts/src/remoteAccess.ts        |  68 +++++
 15 files changed, 634 insertions(+), 85 deletions(-)
 create mode 100644 packages/client-runtime/src/advertisedEndpoint.test.ts
 create mode 100644 packages/client-runtime/src/advertisedEndpoint.ts
 create mode 100644 packages/contracts/src/remoteAccess.ts

diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 34a061ffc70..db4f478798d 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -20,6 +20,7 @@
     "electron-updater": "^6.6.2"
   },
   "devDependencies": {
+    "@t3tools/client-runtime": "workspace:*",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/shared": "workspace:*",
     "@types/node": "catalog:",
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index c5507c6fb03..c5713d2035b 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -55,7 +55,10 @@ import {
 } from "./clientPersistence.ts";
 import { isBackendReadinessAborted, waitForHttpReady } from "./backendReadiness.ts";
 import { showDesktopConfirmDialog } from "./confirmDialog.ts";
-import { resolveDesktopServerExposure } from "./serverExposure.ts";
+import {
+  resolveDesktopCoreAdvertisedEndpoints,
+  resolveDesktopServerExposure,
+} from "./serverExposure.ts";
 import { syncShellEnvironment } from "./syncShellEnvironment.ts";
 import { waitForBackendStartupReady } from "./backendStartupReadiness.ts";
 import { getAutoUpdateDisabledReason, shouldBroadcastDownloadProgress } from "./updateState.ts";
@@ -102,6 +105,7 @@ const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secr
 const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
+const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
 const BASE_DIR = process.env.T3CODE_HOME?.trim() || Path.join(OS.homedir(), ".t3");
 const STATE_DIR = Path.join(BASE_DIR, "userdata");
 const DESKTOP_SETTINGS_PATH = Path.join(STATE_DIR, "desktop-settings.json");
@@ -297,6 +301,7 @@ function backendChildEnv(): NodeJS.ProcessEnv {
   delete env.T3CODE_DESKTOP_WS_URL;
   delete env.T3CODE_DESKTOP_LAN_ACCESS;
   delete env.T3CODE_DESKTOP_LAN_HOST;
+  delete env.T3CODE_DESKTOP_HTTPS_ENDPOINTS;
   return env;
 }
 
@@ -308,6 +313,20 @@ function getDesktopServerExposureState(): DesktopServerExposureState {
   };
 }
 
+function getDesktopAdvertisedEndpoints() {
+  const exposure = resolveDesktopServerExposure({
+    mode: desktopServerExposureMode,
+    port: backendPort,
+    networkInterfaces: OS.networkInterfaces(),
+    ...(backendAdvertisedHost ? { advertisedHostOverride: backendAdvertisedHost } : {}),
+  });
+  return resolveDesktopCoreAdvertisedEndpoints({
+    port: backendPort,
+    exposure,
+    customHttpsEndpointUrls: resolveCustomHttpsEndpointUrls(),
+  });
+}
+
 function getDesktopSecretStorage() {
   return {
     isEncryptionAvailable: () => safeStorage.isEncryptionAvailable(),
@@ -321,6 +340,13 @@ function resolveAdvertisedHostOverride(): string | undefined {
   return override && override.length > 0 ? override : undefined;
 }
 
+function resolveCustomHttpsEndpointUrls(): readonly string[] {
+  return (process.env.T3CODE_DESKTOP_HTTPS_ENDPOINTS ?? "")
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
 async function applyDesktopServerExposureMode(
   mode: DesktopServerExposureMode,
   options?: { readonly persist?: boolean; readonly rejectIfUnavailable?: boolean },
@@ -1669,6 +1695,9 @@ function registerIpcHandlers(): void {
     return nextState;
   });
 
+  ipcMain.removeHandler(GET_ADVERTISED_ENDPOINTS_CHANNEL);
+  ipcMain.handle(GET_ADVERTISED_ENDPOINTS_CHANNEL, async () => getDesktopAdvertisedEndpoints());
+
   ipcMain.removeHandler(PICK_FOLDER_CHANNEL);
   ipcMain.handle(PICK_FOLDER_CHANNEL, async (_event, rawOptions: unknown) => {
     const owner = BrowserWindow.getFocusedWindow() ?? mainWindow;
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index a6756048725..e918e782ab9 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -24,6 +24,7 @@ const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secr
 const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
+const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
 
 contextBridge.exposeInMainWorld("desktopBridge", {
   getAppBranding: () => {
@@ -53,6 +54,7 @@ contextBridge.exposeInMainWorld("desktopBridge", {
     ipcRenderer.invoke(REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId),
   getServerExposureState: () => ipcRenderer.invoke(GET_SERVER_EXPOSURE_STATE_CHANNEL),
   setServerExposureMode: (mode) => ipcRenderer.invoke(SET_SERVER_EXPOSURE_MODE_CHANNEL, mode),
+  getAdvertisedEndpoints: () => ipcRenderer.invoke(GET_ADVERTISED_ENDPOINTS_CHANNEL),
   pickFolder: (options) => ipcRenderer.invoke(PICK_FOLDER_CHANNEL, options),
   confirm: (message) => ipcRenderer.invoke(CONFIRM_CHANNEL, message),
   setTheme: (theme) => ipcRenderer.invoke(SET_THEME_CHANNEL, theme),
diff --git a/apps/desktop/src/serverExposure.test.ts b/apps/desktop/src/serverExposure.test.ts
index c83bbc210e0..86e9d3a6558 100644
--- a/apps/desktop/src/serverExposure.test.ts
+++ b/apps/desktop/src/serverExposure.test.ts
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";
 
-import { resolveDesktopServerExposure, resolveLanAdvertisedHost } from "./serverExposure.ts";
+import {
+  resolveDesktopCoreAdvertisedEndpoints,
+  resolveDesktopServerExposure,
+  resolveLanAdvertisedHost,
+} from "./serverExposure.ts";
 
 describe("resolveLanAdvertisedHost", () => {
   it("prefers an explicit host override", () => {
@@ -74,6 +78,97 @@ describe("resolveLanAdvertisedHost", () => {
   });
 });
 
+describe("resolveDesktopCoreAdvertisedEndpoints", () => {
+  it("advertises loopback and LAN endpoints without provider-specific assumptions", () => {
+    const exposure = resolveDesktopServerExposure({
+      mode: "network-accessible",
+      port: 3773,
+      networkInterfaces: {
+        en0: [
+          {
+            address: "192.168.1.44",
+            family: "IPv4",
+            internal: false,
+            netmask: "255.255.255.0",
+            cidr: "192.168.1.44/24",
+            mac: "00:00:00:00:00:00",
+          },
+        ],
+      },
+    });
+
+    expect(
+      resolveDesktopCoreAdvertisedEndpoints({
+        port: 3773,
+        exposure,
+        customHttpsEndpointUrls: ["https://desktop.example.ts.net"],
+      }),
+    ).toEqual([
+      {
+        id: "desktop-loopback:3773",
+        label: "This machine",
+        provider: {
+          id: "desktop-core",
+          label: "Desktop",
+          kind: "core",
+          isAddon: false,
+        },
+        httpBaseUrl: "http://127.0.0.1:3773/",
+        wsBaseUrl: "ws://127.0.0.1:3773/",
+        reachability: "loopback",
+        compatibility: {
+          hostedHttpsApp: "mixed-content-blocked",
+          desktopApp: "compatible",
+        },
+        source: "desktop-core",
+        status: "available",
+        description: "Loopback endpoint for this desktop app.",
+      },
+      {
+        id: "desktop-lan:http://192.168.1.44:3773",
+        label: "Local network",
+        provider: {
+          id: "desktop-core",
+          label: "Desktop",
+          kind: "core",
+          isAddon: false,
+        },
+        httpBaseUrl: "http://192.168.1.44:3773/",
+        wsBaseUrl: "ws://192.168.1.44:3773/",
+        reachability: "lan",
+        compatibility: {
+          hostedHttpsApp: "mixed-content-blocked",
+          desktopApp: "compatible",
+        },
+        source: "desktop-core",
+        status: "available",
+        isDefault: true,
+        description: "Reachable from devices on the same network.",
+      },
+      {
+        id: "manual:https://desktop.example.ts.net",
+        label: "Custom HTTPS",
+        provider: {
+          id: "manual",
+          label: "Manual",
+          kind: "manual",
+          isAddon: false,
+        },
+        httpBaseUrl: "https://desktop.example.ts.net/",
+        wsBaseUrl: "wss://desktop.example.ts.net/",
+        reachability: "public",
+        compatibility: {
+          hostedHttpsApp: "compatible",
+          desktopApp: "compatible",
+        },
+        source: "user",
+        status: "unknown",
+        description: "User-configured HTTPS endpoint for this desktop backend.",
+      },
+    ]);
+  });
+});
+
 describe("resolveDesktopServerExposure", () => {
   it("keeps the desktop server loopback-only when local-only mode is selected", () => {
     expect(
diff --git a/apps/desktop/src/serverExposure.ts b/apps/desktop/src/serverExposure.ts
index 65c99b60e13..fb6b284b9ef 100644
--- a/apps/desktop/src/serverExposure.ts
+++ b/apps/desktop/src/serverExposure.ts
@@ -1,5 +1,13 @@
 import type { NetworkInterfaceInfo } from "node:os";
-import type { DesktopServerExposureMode } from "@t3tools/contracts";
+import {
+  createAdvertisedEndpoint,
+  type CreateAdvertisedEndpointInput,
+} from "@t3tools/client-runtime";
+import type {
+  AdvertisedEndpoint,
+  AdvertisedEndpointProvider,
+  DesktopServerExposureMode,
+} from "@t3tools/contracts";
 
 const DESKTOP_LOOPBACK_HOST = "127.0.0.1";
 const DESKTOP_LAN_BIND_HOST = "0.0.0.0";
@@ -13,6 +21,26 @@ export interface DesktopServerExposure {
   readonly advertisedHost: string | null;
 }
 
+export interface DesktopAdvertisedEndpointInput {
+  readonly port: number;
+  readonly exposure: DesktopServerExposure;
+  readonly customHttpsEndpointUrls?: readonly string[];
+}
+
+const DESKTOP_CORE_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
+  id: "desktop-core",
+  label: "Desktop",
+  kind: "core",
+  isAddon: false,
+};
+
+const DESKTOP_MANUAL_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
+  id: "manual",
+  label: "Manual",
+  kind: "manual",
+  isAddon: false,
+};
+
 const normalizeOptionalHost = (value: string | undefined): string | undefined => {
   const normalized = value?.trim();
   return normalized && normalized.length > 0 ? normalized : undefined;
@@ -78,3 +106,68 @@ export function resolveDesktopServerExposure(input: {
     advertisedHost,
   };
 }
+
+function createDesktopEndpoint(
+  input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
+): AdvertisedEndpoint {
+  return createAdvertisedEndpoint({
+    ...input,
+    provider: DESKTOP_CORE_ENDPOINT_PROVIDER,
+    source: "desktop-core",
+  });
+}
+
+function createManualEndpoint(
+  input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
+): AdvertisedEndpoint {
+  return createAdvertisedEndpoint({
+    ...input,
+    provider: DESKTOP_MANUAL_ENDPOINT_PROVIDER,
+    source: "user",
+  });
+}
+
+export function resolveDesktopCoreAdvertisedEndpoints(
+  input: DesktopAdvertisedEndpointInput,
+): readonly AdvertisedEndpoint[] {
+  const endpoints: AdvertisedEndpoint[] = [
+    createDesktopEndpoint({
+      id: `desktop-loopback:${input.port}`,
+      label: "This machine",
+      httpBaseUrl: input.exposure.localHttpUrl,
+      reachability: "loopback",
+      status: "available",
+      description: "Loopback endpoint for this desktop app.",
+    }),
+  ];
+
+  if (input.exposure.endpointUrl) {
+    endpoints.push(
+      createDesktopEndpoint({
+        id: `desktop-lan:${input.exposure.endpointUrl}`,
+        label: "Local network",
+        httpBaseUrl: input.exposure.endpointUrl,
+        reachability: "lan",
+        status: "available",
+        isDefault: true,
+        description: "Reachable from devices on the same network.",
+      }),
+    );
+  }
+
+  for (const customEndpointUrl of input.customHttpsEndpointUrls ?? []) {
+    endpoints.push(
+      createManualEndpoint({
+        id: `manual:${customEndpointUrl}`,
+        label: "Custom HTTPS",
+        httpBaseUrl: customEndpointUrl,
+        reachability: "public",
+        hostedHttpsCompatibility: "compatible",
+        status: "unknown",
+        description: "User-configured HTTPS endpoint for this desktop backend.",
+      }),
+    );
+  }
+
+  return endpoints;
+}
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index f6ab384d9fb..3328952c7b6 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -3,6 +3,7 @@ import { memo, useCallback, useEffect, useMemo, useState } from "react";
 import {
   type AuthClientSession,
   type AuthPairingLink,
+  type AdvertisedEndpoint,
   type DesktopServerExposureState,
   type EnvironmentId,
 } from "@t3tools/contracts";
@@ -244,6 +245,31 @@ function removeDesktopClientSession(
   return current.filter((clientSession) => clientSession.sessionId !== sessionId);
 }
 
+function selectPairingEndpoint(
+  endpoints: ReadonlyArray<AdvertisedEndpoint>,
+): AdvertisedEndpoint | null {
+  const availableEndpoints = endpoints.filter((endpoint) => endpoint.status !== "unavailable");
+  return (
+    availableEndpoints.find((endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible") ??
+    availableEndpoints.find((endpoint) => endpoint.isDefault) ??
+    availableEndpoints.find((endpoint) => endpoint.reachability !== "loopback") ??
+    null
+  );
+}
+
+function resolveAdvertisedEndpointPairingUrl(
+  endpoint: AdvertisedEndpoint,
+  credential: string,
+): string {
+  if (endpoint.compatibility.hostedHttpsApp === "compatible") {
+    return (
+      resolveHostedPairingUrl(endpoint.httpBaseUrl, credential) ??
+      resolveDesktopPairingUrl(endpoint.httpBaseUrl, credential)
+    );
+  }
+  return resolveDesktopPairingUrl(endpoint.httpBaseUrl, credential);
+}
+
 function resolveCurrentOriginPairingUrl(credential: string): string {
   const url = new URL("/pair", window.location.href);
   return setPairingTokenOnUrl(url, credential).toString();
@@ -252,6 +278,7 @@ function resolveCurrentOriginPairingUrl(credential: string): string {
 type PairingLinkListRowProps = {
   pairingLink: ServerPairingLinkRecord;
   endpointUrl: string | null | undefined;
+  endpoints: ReadonlyArray<AdvertisedEndpoint>;
   revokingPairingLinkId: string | null;
   onRevoke: (id: string) => void;
 };
@@ -259,6 +286,7 @@ type PairingLinkListRowProps = {
 const PairingLinkListRow = memo(function PairingLinkListRow({
   pairingLink,
   endpointUrl,
+  endpoints,
   revokingPairingLinkId,
   onRevoke,
 }: PairingLinkListRowProps) {
@@ -280,12 +308,17 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
         : null,
     [endpointUrl, pairingLink.credential],
   );
+  const endpointPairingUrl = useMemo(() => {
+    const endpoint = selectPairingEndpoint(endpoints);
+    return endpoint ? resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential) : null;
+  }, [endpoints, pairingLink.credential]);
   const shareablePairingUrl =
-    endpointUrl != null && endpointUrl !== ""
+    endpointPairingUrl ??
+    (endpointUrl != null && endpointUrl !== ""
       ? (hostedPairingUrl ?? resolveDesktopPairingUrl(endpointUrl, pairingLink.credential))
       : isLoopbackHostname(window.location.hostname)
         ? null
-        : currentOriginPairingUrl;
+        : currentOriginPairingUrl);
   const copyValue = shareablePairingUrl ?? pairingLink.credential;
   const canCopyToClipboard =
     typeof window !== "undefined" &&
@@ -622,6 +655,7 @@ const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderActio
 
 type PairingClientsListProps = {
   endpointUrl: string | null | undefined;
+  endpoints: ReadonlyArray<AdvertisedEndpoint>;
   isLoading: boolean;
   pairingLinks: ReadonlyArray<ServerPairingLinkRecord>;
   clientSessions: ReadonlyArray<ServerClientSessionRecord>;
@@ -633,6 +667,7 @@ type PairingClientsListProps = {
 
 const PairingClientsList = memo(function PairingClientsList({
   endpointUrl,
+  endpoints,
   isLoading,
   pairingLinks,
   clientSessions,
@@ -648,6 +683,7 @@ const PairingClientsList = memo(function PairingClientsList({
           key={pairingLink.id}
           pairingLink={pairingLink}
           endpointUrl={endpointUrl}
+          endpoints={endpoints}
           revokingPairingLinkId={revokingPairingLinkId}
           onRevoke={onRevokePairingLink}
         />
@@ -671,6 +707,58 @@ const PairingClientsList = memo(function PairingClientsList({
   );
 });
 
+type AdvertisedEndpointListRowProps = {
+  endpoint: AdvertisedEndpoint;
+};
+
+const endpointCompatibilityLabel = (endpoint: AdvertisedEndpoint): string => {
+  if (endpoint.compatibility.hostedHttpsApp === "compatible") {
+    return "Works with hosted app";
+  }
+  if (endpoint.compatibility.hostedHttpsApp === "mixed-content-blocked") {
+    return "Desktop or direct browser only";
+  }
+  if (endpoint.compatibility.hostedHttpsApp === "requires-configuration") {
+    return "Needs HTTPS setup";
+  }
+  return "Compatibility unknown";
+};
+
+const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
+  endpoint,
+}: AdvertisedEndpointListRowProps) {
+  return (
+    <div className={ITEM_ROW_CLASSNAME}>
+      <div className={ITEM_ROW_INNER_CLASSNAME}>
+        <div className="min-w-0 flex-1 space-y-1">
+          <div className="flex min-h-5 items-center gap-1.5">
+            <ConnectionStatusDot
+              tooltipText={`${endpoint.provider.label} · ${endpoint.reachability}`}
+              dotClassName={
+                endpoint.compatibility.hostedHttpsApp === "compatible"
+                  ? "bg-success"
+                  : "bg-muted-foreground/40"
+              }
+            />
+            <h3 className="text-sm font-medium text-foreground">{endpoint.label}</h3>
+            {endpoint.provider.isAddon ? (
+              <span className="rounded-md border border-border/50 bg-muted/50 px-1 py-0.5 text-[10px] text-muted-foreground/80">
+                Add-on
+              </span>
+            ) : null}
+          </div>
+          <p className="truncate text-xs text-muted-foreground" title={endpoint.httpBaseUrl}>
+            {endpoint.httpBaseUrl}
+          </p>
+        </div>
+        <p className="shrink-0 text-xs text-muted-foreground">
+          {endpointCompatibilityLabel(endpoint)}
+        </p>
+      </div>
+    </div>
+  );
+});
+
 type SavedBackendListRowProps = {
   environmentId: EnvironmentId;
   reconnectingEnvironmentId: EnvironmentId | null;
@@ -776,6 +864,9 @@ export function ConnectionsSettings() {
 
   const [desktopServerExposureState, setDesktopServerExposureState] =
     useState<DesktopServerExposureState | null>(null);
+  const [desktopAdvertisedEndpoints, setDesktopAdvertisedEndpoints] = useState<
+    ReadonlyArray<AdvertisedEndpoint>
+  >([]);
   const [desktopServerExposureError, setDesktopServerExposureError] = useState<string | null>(null);
   const [desktopPairingLinks, setDesktopPairingLinks] = useState<
     ReadonlyArray<ServerPairingLinkRecord>
@@ -1107,8 +1198,21 @@ export function ConnectionsSettings() {
             error instanceof Error ? error.message : "Failed to load network exposure state.";
           setDesktopServerExposureError(message);
         });
+      void desktopBridge
+        .getAdvertisedEndpoints()
+        .then((endpoints) => {
+          if (cancelled) return;
+          setDesktopAdvertisedEndpoints(endpoints);
+        })
+        .catch((error: unknown) => {
+          if (cancelled) return;
+          const message =
+            error instanceof Error ? error.message : "Failed to load reachable endpoints.";
+          setDesktopServerExposureError(message);
+        });
     } else {
       setDesktopServerExposureState(null);
+      setDesktopAdvertisedEndpoints([]);
       setDesktopServerExposureError(null);
     }
 
@@ -1125,6 +1229,7 @@ export function ConnectionsSettings() {
     setDesktopClientSessions([]);
     setDesktopAccessManagementError(null);
     setDesktopServerExposureState(null);
+    setDesktopAdvertisedEndpoints([]);
     setDesktopServerExposureError(null);
   }, [canManageLocalBackend]);
   const visibleDesktopPairingLinks = useMemo(
@@ -1137,87 +1242,95 @@ export function ConnectionsSettings() {
         <>
           <SettingsSection title="Manage local backend">
             {desktopBridge ? (
-              <SettingsRow
-                title="Network access"
-                description={
-                  desktopServerExposureState?.endpointUrl
-                    ? `Reachable at ${desktopServerExposureState.endpointUrl}`
-                    : desktopServerExposureState?.mode === "network-accessible"
-                      ? desktopServerExposureState.advertisedHost
-                        ? `Exposed on all interfaces. Pairing links use ${desktopServerExposureState.advertisedHost}.`
-                        : "Exposed on all interfaces."
-                      : desktopServerExposureState
-                        ? "Limited to this machine."
-                        : "Loading…"
-                }
-                status={
-                  desktopServerExposureError ? (
-                    <span className="block text-destructive">{desktopServerExposureError}</span>
-                  ) : null
-                }
-                control={
-                  <AlertDialog
-                    open={pendingDesktopServerExposureMode !== null}
-                    onOpenChange={(open) => {
-                      if (isUpdatingDesktopServerExposure) return;
-                      if (!open) setPendingDesktopServerExposureMode(null);
-                    }}
-                  >
-                    <Switch
-                      checked={desktopServerExposureState?.mode === "network-accessible"}
-                      disabled={!desktopServerExposureState || isUpdatingDesktopServerExposure}
-                      onCheckedChange={(checked) => {
-                        setPendingDesktopServerExposureMode(
-                          checked ? "network-accessible" : "local-only",
-                        );
+              <>
+                <SettingsRow
+                  title="Network access"
+                  description={
+                    desktopServerExposureState?.endpointUrl
+                      ? `Reachable at ${desktopServerExposureState.endpointUrl}`
+                      : desktopServerExposureState?.mode === "network-accessible"
+                        ? desktopServerExposureState.advertisedHost
+                          ? `Exposed on all interfaces. Pairing links use ${desktopServerExposureState.advertisedHost}.`
+                          : "Exposed on all interfaces."
+                        : desktopServerExposureState
+                          ? "Limited to this machine."
+                          : "Loading…"
+                  }
+                  status={
+                    desktopServerExposureError ? (
+                      <span className="block text-destructive">{desktopServerExposureError}</span>
+                    ) : null
+                  }
+                  control={
+                    <AlertDialog
+                      open={pendingDesktopServerExposureMode !== null}
+                      onOpenChange={(open) => {
+                        if (isUpdatingDesktopServerExposure) return;
+                        if (!open) setPendingDesktopServerExposureMode(null);
                       }}
-                      aria-label="Enable network access"
-                    />
-                    <AlertDialogPopup>
-                      <AlertDialogHeader>
-                        <AlertDialogTitle>
-                          {pendingDesktopServerExposureMode === "network-accessible"
-                            ? "Enable network access?"
-                            : "Disable network access?"}
-                        </AlertDialogTitle>
-                        <AlertDialogDescription>
-                          {pendingDesktopServerExposureMode === "network-accessible"
-                            ? "T3 Code will restart to expose this environment over the network."
-                            : "T3 Code will restart and limit this environment back to this machine."}
-                        </AlertDialogDescription>
-                      </AlertDialogHeader>
-                      <AlertDialogFooter>
-                        <AlertDialogClose
-                          disabled={isUpdatingDesktopServerExposure}
-                          render={
-                            <Button variant="outline" disabled={isUpdatingDesktopServerExposure} />
-                          }
-                        >
-                          Cancel
-                        </AlertDialogClose>
-                        <Button
-                          onClick={handleConfirmDesktopServerExposureChange}
-                          disabled={
-                            pendingDesktopServerExposureMode === null ||
-                            isUpdatingDesktopServerExposure
-                          }
-                        >
-                          {isUpdatingDesktopServerExposure ? (
-                            <>
-                              <Spinner className="size-3.5" />
-                              Restarting…
-                            </>
-                          ) : pendingDesktopServerExposureMode === "network-accessible" ? (
-                            "Restart and enable"
-                          ) : (
-                            "Restart and disable"
-                          )}
-                        </Button>
-                      </AlertDialogFooter>
-                    </AlertDialogPopup>
-                  </AlertDialog>
-                }
-              />
+                    >
+                      <Switch
+                        checked={desktopServerExposureState?.mode === "network-accessible"}
+                        disabled={!desktopServerExposureState || isUpdatingDesktopServerExposure}
+                        onCheckedChange={(checked) => {
+                          setPendingDesktopServerExposureMode(
+                            checked ? "network-accessible" : "local-only",
+                          );
+                        }}
+                        aria-label="Enable network access"
+                      />
+                      <AlertDialogPopup>
+                        <AlertDialogHeader>
+                          <AlertDialogTitle>
+                            {pendingDesktopServerExposureMode === "network-accessible"
+                              ? "Enable network access?"
+                              : "Disable network access?"}
+                          </AlertDialogTitle>
+                          <AlertDialogDescription>
+                            {pendingDesktopServerExposureMode === "network-accessible"
+                              ? "T3 Code will restart to expose this environment over the network."
+                              : "T3 Code will restart and limit this environment back to this machine."}
+                          </AlertDialogDescription>
+                        </AlertDialogHeader>
+                        <AlertDialogFooter>
+                          <AlertDialogClose
+                            disabled={isUpdatingDesktopServerExposure}
+                            render={
+                              <Button
+                                variant="outline"
+                                disabled={isUpdatingDesktopServerExposure}
+                              />
+                            }
+                          >
+                            Cancel
+                          </AlertDialogClose>
+                          <Button
+                            onClick={handleConfirmDesktopServerExposureChange}
+                            disabled={
+                              pendingDesktopServerExposureMode === null ||
+                              isUpdatingDesktopServerExposure
+                            }
+                          >
+                            {isUpdatingDesktopServerExposure ? (
+                              <>
+                                <Spinner className="size-3.5" />
+                                Restarting…
+                              </>
+                            ) : pendingDesktopServerExposureMode === "network-accessible" ? (
+                              "Restart and enable"
+                            ) : (
+                              "Restart and disable"
+                            )}
+                          </Button>
+                        </AlertDialogFooter>
+                      </AlertDialogPopup>
+                    </AlertDialog>
+                  }
+                />
+                {desktopAdvertisedEndpoints.map((endpoint) => (
+                  <AdvertisedEndpointListRow key={endpoint.id} endpoint={endpoint} />
+                ))}
+              </>
             ) : (
               <SettingsRow
                 title="Network access"
@@ -1267,6 +1380,7 @@ export function ConnectionsSettings() {
               ) : null}
               <PairingClientsList
                 endpointUrl={desktopServerExposureState?.endpointUrl}
+                endpoints={desktopAdvertisedEndpoints}
                 isLoading={isLoadingDesktopAccessManagement}
                 pairingLinks={visibleDesktopPairingLinks}
                 clientSessions={desktopClientSessions}
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 51cfe653279..1acb72163c9 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -260,6 +260,7 @@ function makeClientSession(input: {
 
 const createDesktopBridgeStub = (overrides?: {
   readonly serverExposureState?: Awaited<ReturnType<DesktopBridge["getServerExposureState"]>>;
+  readonly advertisedEndpoints?: Awaited<ReturnType<DesktopBridge["getAdvertisedEndpoints"]>>;
   readonly setServerExposureMode?: DesktopBridge["setServerExposureMode"];
   readonly setUpdateChannel?: DesktopBridge["setUpdateChannel"];
 }): DesktopBridge => {
@@ -309,6 +310,7 @@ const createDesktopBridgeStub = (overrides?: {
         endpointUrl: mode === "network-accessible" ? "http://192.168.1.44:3773" : null,
         advertisedHost: mode === "network-accessible" ? "192.168.1.44" : null,
       })),
+    getAdvertisedEndpoints: vi.fn().mockResolvedValue(overrides?.advertisedEndpoints ?? []),
     pickFolder: vi.fn().mockResolvedValue(null),
     confirm: vi.fn().mockResolvedValue(false),
     setTheme: vi.fn().mockResolvedValue(undefined),
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index b627286199c..9b46acdb99c 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -183,6 +183,7 @@ function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridg
       endpointUrl: null,
       advertisedHost: null,
     }),
+    getAdvertisedEndpoints: async () => [],
     pickFolder: async () => null,
     confirm: async () => true,
     setTheme: async () => undefined,
diff --git a/bun.lock b/bun.lock
index c7aeb59b76f..e1b9d456398 100644
--- a/bun.lock
+++ b/bun.lock
@@ -21,6 +21,7 @@
         "electron-updater": "^6.6.2",
       },
       "devDependencies": {
+        "@t3tools/client-runtime": "workspace:*",
         "@t3tools/contracts": "workspace:*",
         "@t3tools/shared": "workspace:*",
         "@types/node": "catalog:",
diff --git a/packages/client-runtime/src/advertisedEndpoint.test.ts b/packages/client-runtime/src/advertisedEndpoint.test.ts
new file mode 100644
index 00000000000..1cbfde87bd3
--- /dev/null
+++ b/packages/client-runtime/src/advertisedEndpoint.test.ts
@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  classifyHostedHttpsCompatibility,
+  createAdvertisedEndpoint,
+  deriveWsBaseUrl,
+  normalizeHttpBaseUrl,
+} from "./advertisedEndpoint.ts";
+
+const coreProvider = {
+  id: "desktop-core",
+  label: "Desktop",
+  kind: "core",
+  isAddon: false,
+} as const;
+
+describe("advertised endpoint helpers", () => {
+  it("normalizes HTTP and WebSocket base URLs", () => {
+    expect(normalizeHttpBaseUrl("https://example.com/path?x=1#hash")).toBe("https://example.com/");
+    expect(normalizeHttpBaseUrl("wss://example.com/socket")).toBe("https://example.com/");
+    expect(deriveWsBaseUrl("https://example.com/api")).toBe("wss://example.com/");
+    expect(deriveWsBaseUrl("http://127.0.0.1:3773")).toBe("ws://127.0.0.1:3773/");
+  });
+
+  it("marks HTTP endpoints as blocked from hosted HTTPS apps", () => {
+    expect(classifyHostedHttpsCompatibility("http://192.168.1.44:3773")).toBe(
+      "mixed-content-blocked",
+    );
+    expect(classifyHostedHttpsCompatibility("https://desktop.example.com", "compatible")).toBe(
+      "compatible",
+    );
+  });
+
+  it("creates provider-neutral endpoint records", () => {
+    expect(
+      createAdvertisedEndpoint({
+        id: "lan:http://192.168.1.44:3773",
+        label: "LAN",
+        provider: coreProvider,
+        httpBaseUrl: "http://192.168.1.44:3773",
+        reachability: "lan",
+        source: "desktop-core",
+        isDefault: true,
+      }),
+    ).toEqual({
+      id: "lan:http://192.168.1.44:3773",
+      label: "LAN",
+      provider: coreProvider,
+      httpBaseUrl: "http://192.168.1.44:3773/",
+      wsBaseUrl: "ws://192.168.1.44:3773/",
+      reachability: "lan",
+      compatibility: {
+        hostedHttpsApp: "mixed-content-blocked",
+        desktopApp: "compatible",
+      },
+      source: "desktop-core",
+      status: "available",
+      isDefault: true,
+    });
+  });
+});
diff --git a/packages/client-runtime/src/advertisedEndpoint.ts b/packages/client-runtime/src/advertisedEndpoint.ts
new file mode 100644
index 00000000000..314d8272c81
--- /dev/null
+++ b/packages/client-runtime/src/advertisedEndpoint.ts
@@ -0,0 +1,78 @@
+import type {
+  AdvertisedEndpoint,
+  AdvertisedEndpointHostedHttpsCompatibility,
+  AdvertisedEndpointProvider,
+  AdvertisedEndpointReachability,
+  AdvertisedEndpointSource,
+  AdvertisedEndpointStatus,
+} from "@t3tools/contracts";
+
+export interface CreateAdvertisedEndpointInput {
+  readonly id: string;
+  readonly label: string;
+  readonly provider: AdvertisedEndpointProvider;
+  readonly httpBaseUrl: string;
+  readonly reachability: AdvertisedEndpointReachability;
+  readonly hostedHttpsCompatibility?: AdvertisedEndpointHostedHttpsCompatibility;
+  readonly desktopCompatibility?: "compatible" | "unknown";
+  readonly source: AdvertisedEndpointSource;
+  readonly status?: AdvertisedEndpointStatus;
+  readonly isDefault?: boolean;
+  readonly description?: string;
+}
+
+export function normalizeHttpBaseUrl(rawValue: string): string {
+  const url = new URL(rawValue);
+  if (url.protocol === "ws:") {
+    url.protocol = "http:";
+  } else if (url.protocol === "wss:") {
+    url.protocol = "https:";
+  }
+
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Endpoint must use HTTP or HTTPS. Received ${url.protocol}`);
+  }
+
+  url.pathname = "/";
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+export function deriveWsBaseUrl(httpBaseUrl: string): string {
+  const url = new URL(normalizeHttpBaseUrl(httpBaseUrl));
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.toString();
+}
+
+export function classifyHostedHttpsCompatibility(
+  httpBaseUrl: string,
+  fallback: AdvertisedEndpointHostedHttpsCompatibility = "unknown",
+): AdvertisedEndpointHostedHttpsCompatibility {
+  const url = new URL(normalizeHttpBaseUrl(httpBaseUrl));
+  if (url.protocol === "http:") {
+    return "mixed-content-blocked";
+  }
+  return fallback === "mixed-content-blocked" ? "unknown" : fallback;
+}
+
+export function createAdvertisedEndpoint(input: CreateAdvertisedEndpointInput): AdvertisedEndpoint {
+  const httpBaseUrl = normalizeHttpBaseUrl(input.httpBaseUrl);
+  return {
+    id: input.id,
+    label: input.label,
+    provider: input.provider,
+    httpBaseUrl,
+    wsBaseUrl: deriveWsBaseUrl(httpBaseUrl),
+    reachability: input.reachability,
+    compatibility: {
+      hostedHttpsApp:
+        input.hostedHttpsCompatibility ?? classifyHostedHttpsCompatibility(httpBaseUrl),
+      desktopApp: input.desktopCompatibility ?? "compatible",
+    },
+    source: input.source,
+    status: input.status ?? "available",
+    ...(input.isDefault === undefined ? {} : { isDefault: input.isDefault }),
+    ...(input.description === undefined ? {} : { description: input.description }),
+  };
+}
diff --git a/packages/client-runtime/src/index.ts b/packages/client-runtime/src/index.ts
index f6f5b82758c..cb7472dff51 100644
--- a/packages/client-runtime/src/index.ts
+++ b/packages/client-runtime/src/index.ts
@@ -1,3 +1,4 @@
+export * from "./advertisedEndpoint.ts";
 export * from "./knownEnvironment.ts";
 export * from "./scoped.ts";
 export * from "./sourceControlDiscoveryState.ts";
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index a0ccc624a5e..1a3647eb314 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -1,6 +1,7 @@
 export * from "./baseSchemas.ts";
 export * from "./auth.ts";
 export * from "./environment.ts";
+export * from "./remoteAccess.ts";
 export * from "./ipc.ts";
 export * from "./terminal.ts";
 export * from "./provider.ts";
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 35539a86e33..5826238e942 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -53,6 +53,7 @@ import type {
   OrchestrationThreadStreamItem,
 } from "./orchestration.ts";
 import type { EnvironmentId } from "./baseSchemas.ts";
+import type { AdvertisedEndpoint } from "./remoteAccess.ts";
 import { EditorId } from "./editor.ts";
 import { ServerSettings, type ClientSettings, type ServerSettingsPatch } from "./settings.ts";
 import type { SourceControlDiscoveryResult } from "./sourceControl.ts";
@@ -162,6 +163,7 @@ export interface DesktopBridge {
   removeSavedEnvironmentSecret: (environmentId: EnvironmentId) => Promise<void>;
   getServerExposureState: () => Promise<DesktopServerExposureState>;
   setServerExposureMode: (mode: DesktopServerExposureMode) => Promise<DesktopServerExposureState>;
+  getAdvertisedEndpoints: () => Promise<readonly AdvertisedEndpoint[]>;
   pickFolder: (options?: PickFolderOptions) => Promise<string | null>;
   confirm: (message: string) => Promise<boolean>;
   setTheme: (theme: DesktopTheme) => Promise<void>;
diff --git a/packages/contracts/src/remoteAccess.ts b/packages/contracts/src/remoteAccess.ts
new file mode 100644
index 00000000000..70a20d7aeb4
--- /dev/null
+++ b/packages/contracts/src/remoteAccess.ts
@@ -0,0 +1,68 @@
+import { Schema } from "effect";
+
+import { TrimmedNonEmptyString } from "./baseSchemas.ts";
+
+export const AdvertisedEndpointProviderKind = Schema.Literals([
+  "core",
+  "private-network",
+  "tunnel",
+  "manual",
+]);
+export type AdvertisedEndpointProviderKind = typeof AdvertisedEndpointProviderKind.Type;
+
+export const AdvertisedEndpointReachability = Schema.Literals([
+  "loopback",
+  "lan",
+  "private-network",
+  "public",
+]);
+export type AdvertisedEndpointReachability = typeof AdvertisedEndpointReachability.Type;
+
+export const AdvertisedEndpointHostedHttpsCompatibility = Schema.Literals([
+  "compatible",
+  "mixed-content-blocked",
+  "requires-configuration",
+  "unknown",
+]);
+export type AdvertisedEndpointHostedHttpsCompatibility =
+  typeof AdvertisedEndpointHostedHttpsCompatibility.Type;
+
+export const AdvertisedEndpointStatus = Schema.Literals(["available", "unavailable", "unknown"]);
+export type AdvertisedEndpointStatus = typeof AdvertisedEndpointStatus.Type;
+
+export const AdvertisedEndpointSource = Schema.Literals([
+  "desktop-core",
+  "desktop-addon",
+  "server",
+  "user",
+]);
+export type AdvertisedEndpointSource = typeof AdvertisedEndpointSource.Type;
+
+export const AdvertisedEndpointProvider = Schema.Struct({
+  id: TrimmedNonEmptyString,
+  label: TrimmedNonEmptyString,
+  kind: AdvertisedEndpointProviderKind,
+  isAddon: Schema.Boolean,
+});
+export type AdvertisedEndpointProvider = typeof AdvertisedEndpointProvider.Type;
+
+export const AdvertisedEndpointCompatibility = Schema.Struct({
+  hostedHttpsApp: AdvertisedEndpointHostedHttpsCompatibility,
+  desktopApp: Schema.Literals(["compatible", "unknown"]),
+});
+export type AdvertisedEndpointCompatibility = typeof AdvertisedEndpointCompatibility.Type;
+
+export const AdvertisedEndpoint = Schema.Struct({
+  id: TrimmedNonEmptyString,
+  label: TrimmedNonEmptyString,
+  provider: AdvertisedEndpointProvider,
+  httpBaseUrl: TrimmedNonEmptyString,
+  wsBaseUrl: TrimmedNonEmptyString,
+  reachability: AdvertisedEndpointReachability,
+  compatibility: AdvertisedEndpointCompatibility,
+  source: AdvertisedEndpointSource,
+  status: AdvertisedEndpointStatus,
+  isDefault: Schema.optional(Schema.Boolean),
+  description: Schema.optional(TrimmedNonEmptyString),
+});
+export type AdvertisedEndpoint = typeof AdvertisedEndpoint.Type;

From 19ef98837077c6ecf67548d29648ac9f2a6f2b75 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:55:58 -0700
Subject: [PATCH 06/74] docs(remote): describe advertised endpoint selection

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .docs/remote-architecture.md | 22 ++++++++++++++++++++++
 REMOTE.md                    | 10 +++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/.docs/remote-architecture.md b/.docs/remote-architecture.md
index 8e5ed37928e..ecaf45de1a7 100644
--- a/.docs/remote-architecture.md
+++ b/.docs/remote-architecture.md
@@ -110,6 +110,28 @@ A single environment may have many endpoints:
 
 The environment stays the same. Only the access path changes.
 
+### AdvertisedEndpoint
+
+An `AdvertisedEndpoint` is a server or desktop-authored candidate endpoint for an environment. It is how the backend tells the client which URLs may be useful for pairing and reconnecting.
+
+`AdvertisedEndpoint` is deliberately narrower than the full access model:
+
+- it describes a concrete HTTP and WebSocket base URL pair
+- it can mark the endpoint as default, available, or unavailable
+- it includes reachability hints such as loopback, LAN, private, public, or tunnel
+- it includes compatibility hints such as whether the endpoint can be used from the hosted HTTPS app
+
+Clients should treat advertised endpoints as hints, not as proof that a route works from the current device. The final connection attempt still decides whether the endpoint is reachable.
+
+Endpoint selection should prefer:
+
+1. endpoints compatible with the hosted HTTPS app
+2. explicitly default endpoints
+3. non-loopback endpoints
+4. loopback endpoints only for same-machine clients
+
+This keeps endpoint discovery centralized without making any one provider, such as Tailscale or a future tunnel service, part of the core environment model.
+
 ### Hosted pairing request
 
 A hosted pairing request is a bootstrap URL for the static web app, not a transport.
diff --git a/REMOTE.md b/REMOTE.md
index cec7b0ecccb..f2e9bd9aefc 100644
--- a/REMOTE.md
+++ b/REMOTE.md
@@ -22,9 +22,17 @@ If you are already running the desktop app and want to make it reachable from ot
 
 1. Open **Settings** → **Connections**.
 2. Under **Manage Local Backend**, toggle **Network access** on. This will restart the app and run the backend on all network interfaces.
-3. The settings panel will show the address the server is reachable at (e.g. `http://192.168.x.y:3773`).
+3. The settings panel will show reachable endpoints for the backend. At minimum this includes the local LAN HTTP endpoint when network access is enabled.
 4. Use **Create Link** to generate a pairing link you can share with another device.
 
+The app chooses the best reachable endpoint for pairing links:
+
+- HTTPS/WSS-compatible endpoints are preferred because they work from `https://app.t3.codes`.
+- Non-loopback HTTP endpoints are used for direct LAN pairing when HTTPS is not available.
+- Loopback-only endpoints are not useful for another device unless that device is the same machine.
+
+If the copied link points directly at `http://192.168.x.y:3773`, open it from a client that can reach that LAN address. If it points at `https://app.t3.codes/pair?...`, the hosted web app will save the environment and connect directly to the backend URL in the link.
+
 ### Option 2: Headless Server (CLI)
 
 Use this when you want to run the server without a GUI, for example on a remote machine over SSH.

From 6c4db9a7f607862361c290c97cda12aa775ba431 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 20:21:31 -0700
Subject: [PATCH 07/74] fix(web): hide endpoint rows when network access is
 disabled

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .../settings/ConnectionsSettings.tsx          |  7 +-
 .../settings/SettingsPanels.browser.tsx       | 70 +++++++++++++++++++
 2 files changed, 75 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 3328952c7b6..9326bdd1faf 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1236,6 +1236,9 @@ export function ConnectionsSettings() {
     () => desktopPairingLinks.filter((pairingLink) => pairingLink.role === "client"),
     [desktopPairingLinks],
   );
+  const visibleDesktopAdvertisedEndpoints = isLocalBackendNetworkAccessible
+    ? desktopAdvertisedEndpoints
+    : [];
   return (
     <SettingsPageContainer>
       {canManageLocalBackend ? (
@@ -1327,7 +1330,7 @@ export function ConnectionsSettings() {
                     </AlertDialog>
                   }
                 />
-                {desktopAdvertisedEndpoints.map((endpoint) => (
+                {visibleDesktopAdvertisedEndpoints.map((endpoint) => (
                   <AdvertisedEndpointListRow key={endpoint.id} endpoint={endpoint} />
                 ))}
               </>
@@ -1380,7 +1383,7 @@ export function ConnectionsSettings() {
               ) : null}
               <PairingClientsList
                 endpointUrl={desktopServerExposureState?.endpointUrl}
-                endpoints={desktopAdvertisedEndpoints}
+                endpoints={visibleDesktopAdvertisedEndpoints}
                 isLoading={isLoadingDesktopAccessManagement}
                 pairingLinks={visibleDesktopPairingLinks}
                 clientSessions={desktopClientSessions}
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 1acb72163c9..a08d0a42cdc 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -433,6 +433,76 @@ describe("GeneralSettingsPanel observability", () => {
       .toBeInTheDocument();
   });
 
+  it("hides advertised endpoint rows when desktop network access is disabled", async () => {
+    window.desktopBridge = createDesktopBridgeStub({
+      serverExposureState: {
+        mode: "local-only",
+        endpointUrl: null,
+        advertisedHost: null,
+      },
+      advertisedEndpoints: [
+        {
+          id: "loopback",
+          label: "This machine",
+          provider: {
+            id: "desktop-core",
+            label: "Desktop",
+            kind: "manual",
+            isAddon: false,
+          },
+          httpBaseUrl: "http://127.0.0.1:3773/",
+          wsBaseUrl: "ws://127.0.0.1:3773/",
+          reachability: "loopback",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-core",
+          status: "available",
+          isDefault: true,
+        },
+        {
+          id: "tailscale-ip",
+          label: "Tailscale IP",
+          provider: {
+            id: "tailscale",
+            label: "Tailscale",
+            kind: "private-network",
+            isAddon: true,
+          },
+          httpBaseUrl: "http://100.105.39.17:3773/",
+          wsBaseUrl: "ws://100.105.39.17:3773/",
+          reachability: "private-network",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-addon",
+          status: "available",
+        },
+      ],
+    });
+    authAccessHarness.setSnapshot({
+      pairingLinks: [],
+      clientSessions: [],
+    });
+    setServerConfigSnapshot(createBaseServerConfig());
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <ConnectionsSettings />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect.element(page.getByText("Limited to this machine.")).toBeInTheDocument();
+    await expect
+      .element(page.getByRole("heading", { name: "This machine", exact: true }))
+      .not.toBeInTheDocument();
+    await expect
+      .element(page.getByRole("heading", { name: "Tailscale IP", exact: true }))
+      .not.toBeInTheDocument();
+  });
+
   it("shows diagnostics inside About with a single logs-folder action", async () => {
     setServerConfigSnapshot(createBaseServerConfig());
 

From e11c88db7f21dc633e2e4b07b38dd6366620ae38 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 21:06:01 -0700
Subject: [PATCH 08/74] feat(web): make advertised endpoint defaults explicit

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .docs/remote-architecture.md                  |   6 +-
 REMOTE.md                                     |   6 +-
 .../settings/ConnectionsSettings.tsx          | 337 ++++++++++++++----
 .../settings/SettingsPanels.browser.tsx       | 102 +++++-
 .../components/settings/settingsLayout.tsx    |   2 +-
 apps/web/src/uiStateStore.test.ts             |  25 ++
 apps/web/src/uiStateStore.ts                  |  28 +-
 7 files changed, 424 insertions(+), 82 deletions(-)

diff --git a/.docs/remote-architecture.md b/.docs/remote-architecture.md
index ecaf45de1a7..1748df5db65 100644
--- a/.docs/remote-architecture.md
+++ b/.docs/remote-architecture.md
@@ -123,7 +123,11 @@ An `AdvertisedEndpoint` is a server or desktop-authored candidate endpoint for a
 
 Clients should treat advertised endpoints as hints, not as proof that a route works from the current device. The final connection attempt still decides whether the endpoint is reachable.
 
-Endpoint selection should prefer:
+The UI presents one default advertised endpoint in the network-access summary and keeps the rest behind an expandable advanced list. The default controls pairing QR codes and primary copy actions. Users can override it, but that override is a UI preference, not backend configuration.
+
+Persist the override by stable endpoint kind rather than raw URL whenever possible. For example, a LAN endpoint should be stored as the desktop LAN endpoint preference, not as `192.168.x.y`, because the address can change when the user switches networks. Provider endpoints should use provider-specific stable keys such as Tailscale IP or Tailscale MagicDNS HTTPS. Custom endpoints may fall back to their concrete identity.
+
+When no user default is saved, endpoint selection should prefer:
 
 1. endpoints compatible with the hosted HTTPS app
 2. explicitly default endpoints
diff --git a/REMOTE.md b/REMOTE.md
index f2e9bd9aefc..f5ddccaa85a 100644
--- a/REMOTE.md
+++ b/REMOTE.md
@@ -22,10 +22,12 @@ If you are already running the desktop app and want to make it reachable from ot
 
 1. Open **Settings** → **Connections**.
 2. Under **Manage Local Backend**, toggle **Network access** on. This will restart the app and run the backend on all network interfaces.
-3. The settings panel will show reachable endpoints for the backend. At minimum this includes the local LAN HTTP endpoint when network access is enabled.
+3. The settings panel will show the default reachable endpoint, with a `+N` control when more endpoints are available. Expand it to inspect alternatives such as loopback, LAN, private-network, or HTTPS endpoints.
 4. Use **Create Link** to generate a pairing link you can share with another device.
 
-The app chooses the best reachable endpoint for pairing links:
+The default endpoint controls the QR code and primary copy action for pairing links. You can change it from the expanded endpoint list. The preference is stored by endpoint type, so choosing the local LAN endpoint survives normal IP address changes when you move between networks.
+
+When no user default is saved, the app chooses the best reachable endpoint for pairing links:
 
 - HTTPS/WSS-compatible endpoints are preferred because they work from `https://app.t3.codes`.
 - Non-loopback HTTP endpoints are used for direct LAN pairing when HTTPS is not available.
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 9326bdd1faf..31253781930 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1,5 +1,5 @@
-import { PlusIcon, QrCodeIcon } from "lucide-react";
-import { memo, useCallback, useEffect, useMemo, useState } from "react";
+import { ChevronDownIcon, PlusIcon, QrCodeIcon } from "lucide-react";
+import { type ReactNode, memo, useCallback, useEffect, useMemo, useState } from "react";
 import {
   type AuthClientSession,
   type AuthPairingLink,
@@ -46,6 +46,8 @@ import { Switch } from "../ui/switch";
 import { stackedThreadToast, toastManager } from "../ui/toast";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { Button } from "../ui/button";
+import { Group, GroupSeparator } from "../ui/group";
+import { Menu, MenuItem, MenuPopup, MenuTrigger } from "../ui/menu";
 import { Textarea } from "../ui/textarea";
 import { setPairingTokenOnUrl } from "../../pairingUrl";
 import {
@@ -69,6 +71,7 @@ import {
   reconnectSavedEnvironment,
   removeSavedEnvironment,
 } from "~/environments/runtime";
+import { useUiStateStore } from "~/uiStateStore";
 
 const accessTimestampFormatter = new Intl.DateTimeFormat(undefined, {
   dateStyle: "medium",
@@ -164,6 +167,7 @@ function getSavedBackendStatusTooltip(
 
 /** Direct row in the card – same pattern as the Provider / ACP-agent list rows. */
 const ITEM_ROW_CLASSNAME = "border-t border-border/60 px-4 py-4 first:border-t-0 sm:px-5";
+const ENDPOINT_ROW_CLASSNAME = "border-t border-border/60 px-4 py-2.5 first:border-t-0 sm:px-5";
 
 const ITEM_ROW_INNER_CLASSNAME =
   "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between";
@@ -247,8 +251,17 @@ function removeDesktopClientSession(
 
 function selectPairingEndpoint(
   endpoints: ReadonlyArray<AdvertisedEndpoint>,
+  defaultEndpointKey?: string | null,
 ): AdvertisedEndpoint | null {
   const availableEndpoints = endpoints.filter((endpoint) => endpoint.status !== "unavailable");
+  if (defaultEndpointKey) {
+    const selectedEndpoint = availableEndpoints.find(
+      (endpoint) => endpointDefaultPreferenceKey(endpoint) === defaultEndpointKey,
+    );
+    if (selectedEndpoint) {
+      return selectedEndpoint;
+    }
+  }
   return (
     availableEndpoints.find((endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible") ??
     availableEndpoints.find((endpoint) => endpoint.isDefault) ??
@@ -257,6 +270,30 @@ function selectPairingEndpoint(
   );
 }
 
+function endpointDefaultPreferenceKey(endpoint: AdvertisedEndpoint): string {
+  if (endpoint.id.startsWith("desktop-loopback:")) {
+    return "desktop-core:loopback:http";
+  }
+  if (endpoint.id.startsWith("desktop-lan:")) {
+    return "desktop-core:lan:http";
+  }
+  if (endpoint.id.startsWith("tailscale-ip:")) {
+    return "tailscale:ip:http";
+  }
+  if (endpoint.id.startsWith("tailscale-magicdns:")) {
+    return "tailscale:magicdns:https";
+  }
+
+  let scheme = "unknown";
+  try {
+    scheme = new URL(endpoint.httpBaseUrl).protocol.replace(/:$/u, "");
+  } catch {
+    // Keep the stored preference stable even if a custom endpoint is malformed.
+  }
+
+  return `${endpoint.provider.id}:${endpoint.reachability}:${scheme}:${endpoint.label}`;
+}
+
 function resolveAdvertisedEndpointPairingUrl(
   endpoint: AdvertisedEndpoint,
   credential: string,
@@ -279,6 +316,7 @@ type PairingLinkListRowProps = {
   pairingLink: ServerPairingLinkRecord;
   endpointUrl: string | null | undefined;
   endpoints: ReadonlyArray<AdvertisedEndpoint>;
+  defaultEndpointKey: string | null;
   revokingPairingLinkId: string | null;
   onRevoke: (id: string) => void;
 };
@@ -287,6 +325,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
   pairingLink,
   endpointUrl,
   endpoints,
+  defaultEndpointKey,
   revokingPairingLinkId,
   onRevoke,
 }: PairingLinkListRowProps) {
@@ -309,9 +348,20 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
     [endpointUrl, pairingLink.credential],
   );
   const endpointPairingUrl = useMemo(() => {
-    const endpoint = selectPairingEndpoint(endpoints);
+    const endpoint = selectPairingEndpoint(endpoints, defaultEndpointKey);
     return endpoint ? resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential) : null;
-  }, [endpoints, pairingLink.credential]);
+  }, [defaultEndpointKey, endpoints, pairingLink.credential]);
+  const endpointCopyOptions = useMemo(
+    () =>
+      endpoints
+        .filter((endpoint) => endpoint.status !== "unavailable")
+        .map((endpoint) => ({
+          key: endpointDefaultPreferenceKey(endpoint),
+          label: endpoint.label,
+          url: resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential),
+        })),
+    [endpoints, pairingLink.credential],
+  );
   const shareablePairingUrl =
     endpointPairingUrl ??
     (endpointUrl != null && endpointUrl !== ""
@@ -319,37 +369,54 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
       : isLoopbackHostname(window.location.hostname)
         ? null
         : currentOriginPairingUrl);
-  const copyValue = shareablePairingUrl ?? pairingLink.credential;
+  const revealValue = shareablePairingUrl ?? pairingLink.credential;
   const canCopyToClipboard =
     typeof window !== "undefined" &&
     window.isSecureContext &&
     navigator.clipboard?.writeText != null;
 
-  const { copyToClipboard, isCopied } = useCopyToClipboard({
-    onCopy: () => {
+  const { copyToClipboard } = useCopyToClipboard<"code" | "link">({
+    onCopy: (kind) => {
       toastManager.add({
         type: "success",
-        title: shareablePairingUrl ? "Pairing URL copied" : "Pairing token copied",
-        description: shareablePairingUrl
-          ? "Open it in the client you want to pair to this environment."
-          : "Paste it into another client with this backend's reachable host.",
+        title: kind === "link" ? "Pairing URL copied" : "Pairing code copied",
+        description:
+          kind === "link"
+            ? "Open it in the client you want to pair to this environment."
+            : "Paste it into another client to finish pairing.",
       });
     },
-    onError: (error) => {
+    onError: (error, kind) => {
       setIsRevealDialogOpen(true);
       toastManager.add(
         stackedThreadToast({
           type: "error",
-          title: canCopyToClipboard ? "Could not copy pairing URL" : "Clipboard copy unavailable",
+          title: canCopyToClipboard
+            ? kind === "link"
+              ? "Could not copy pairing URL"
+              : "Could not copy pairing code"
+            : "Clipboard copy unavailable",
           description: canCopyToClipboard ? error.message : "Showing the full value instead.",
         }),
       );
     },
   });
 
-  const handleCopy = useCallback(() => {
-    copyToClipboard(copyValue, undefined);
-  }, [copyToClipboard, copyValue]);
+  const copyPairingValue = useCallback(
+    (value: string, kind: "code" | "link") => {
+      copyToClipboard(value, kind);
+    },
+    [copyToClipboard],
+  );
+
+  const handleCopyCode = useCallback(() => {
+    copyPairingValue(pairingLink.credential, "code");
+  }, [copyPairingValue, pairingLink.credential]);
+
+  const handleCopyDefaultLink = useCallback(() => {
+    if (!shareablePairingUrl) return;
+    copyPairingValue(shareablePairingUrl, "link");
+  }, [copyPairingValue, shareablePairingUrl]);
 
   const expiresAbsolute = formatAccessTimestamp(pairingLink.expiresAt);
 
@@ -412,27 +479,71 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
           <Dialog open={isRevealDialogOpen} onOpenChange={setIsRevealDialogOpen}>
             {canCopyToClipboard ? (
-              <Button size="xs" variant="outline" onClick={handleCopy}>
-                {isCopied ? "Copied" : shareablePairingUrl ? "Copy" : "Copy token"}
-              </Button>
+              <>
+                <Button size="xs" variant="outline" onClick={handleCopyCode}>
+                  Copy code
+                </Button>
+                {shareablePairingUrl ? (
+                  endpointCopyOptions.length > 1 ? (
+                    <Group aria-label="Copy pairing URL">
+                      <Button size="xs" variant="outline" onClick={handleCopyDefaultLink}>
+                        Copy pairing URL
+                      </Button>
+                      <GroupSeparator />
+                      <Menu>
+                        <MenuTrigger
+                          render={
+                            <Button
+                              size="icon-xs"
+                              variant="outline"
+                              aria-label="Pairing URL copy options"
+                            />
+                          }
+                        >
+                          <ChevronDownIcon className="size-3.5" />
+                        </MenuTrigger>
+                        <MenuPopup align="end" className="min-w-52">
+                          {endpointCopyOptions.map((option) => (
+                            <MenuItem
+                              key={option.key}
+                              onClick={() => copyPairingValue(option.url, "link")}
+                            >
+                              <span className="min-w-0 flex-1">
+                                <span className="block truncate">{option.label}</span>
+                                <span className="block truncate text-[11px] text-muted-foreground">
+                                  Pairing URL
+                                </span>
+                              </span>
+                            </MenuItem>
+                          ))}
+                        </MenuPopup>
+                      </Menu>
+                    </Group>
+                  ) : (
+                    <Button size="xs" variant="outline" onClick={handleCopyDefaultLink}>
+                      Copy pairing URL
+                    </Button>
+                  )
+                ) : null}
+              </>
             ) : (
               <DialogTrigger render={<Button size="xs" variant="outline" />}>
-                {shareablePairingUrl ? "Show link" : "Show token"}
+                {shareablePairingUrl ? "Show link" : "Show code"}
               </DialogTrigger>
             )}
             <DialogPopup className="max-w-md">
               <DialogHeader>
-                <DialogTitle>{shareablePairingUrl ? "Pairing link" : "Pairing token"}</DialogTitle>
+                <DialogTitle>{shareablePairingUrl ? "Pairing link" : "Pairing code"}</DialogTitle>
                 <DialogDescription>
                   {shareablePairingUrl
                     ? "Clipboard copy is unavailable here. Open or manually copy this full pairing URL on the device you want to connect."
-                    : "Clipboard copy is unavailable here. Manually copy this token and pair from another client using this backend's reachable host."}
+                    : "Clipboard copy is unavailable here. Manually copy this code into another client."}
                 </DialogDescription>
               </DialogHeader>
               <DialogPanel className="space-y-4">
                 <Textarea
                   readOnly
-                  value={copyValue}
+                  value={revealValue}
                   rows={shareablePairingUrl ? 4 : 3}
                   className="text-xs leading-relaxed"
                   onFocus={(event) => event.currentTarget.select()}
@@ -455,8 +566,8 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                   Done
                 </Button>
                 {canCopyToClipboard ? (
-                  <Button variant="outline" size="xs" onClick={handleCopy}>
-                    {isCopied ? "Copied" : "Copy again"}
+                  <Button variant="outline" size="xs" onClick={handleCopyCode}>
+                    Copy code
                   </Button>
                 ) : null}
               </DialogFooter>
@@ -656,6 +767,7 @@ const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderActio
 type PairingClientsListProps = {
   endpointUrl: string | null | undefined;
   endpoints: ReadonlyArray<AdvertisedEndpoint>;
+  defaultEndpointKey: string | null;
   isLoading: boolean;
   pairingLinks: ReadonlyArray<ServerPairingLinkRecord>;
   clientSessions: ReadonlyArray<ServerClientSessionRecord>;
@@ -668,6 +780,7 @@ type PairingClientsListProps = {
 const PairingClientsList = memo(function PairingClientsList({
   endpointUrl,
   endpoints,
+  defaultEndpointKey,
   isLoading,
   pairingLinks,
   clientSessions,
@@ -684,6 +797,7 @@ const PairingClientsList = memo(function PairingClientsList({
           pairingLink={pairingLink}
           endpointUrl={endpointUrl}
           endpoints={endpoints}
+          defaultEndpointKey={defaultEndpointKey}
           revokingPairingLinkId={revokingPairingLinkId}
           onRevoke={onRevokePairingLink}
         />
@@ -709,56 +823,80 @@ const PairingClientsList = memo(function PairingClientsList({
 
 type AdvertisedEndpointListRowProps = {
   endpoint: AdvertisedEndpoint;
-};
-
-const endpointCompatibilityLabel = (endpoint: AdvertisedEndpoint): string => {
-  if (endpoint.compatibility.hostedHttpsApp === "compatible") {
-    return "Works with hosted app";
-  }
-  if (endpoint.compatibility.hostedHttpsApp === "mixed-content-blocked") {
-    return "Desktop or direct browser only";
-  }
-  if (endpoint.compatibility.hostedHttpsApp === "requires-configuration") {
-    return "Needs HTTPS setup";
-  }
-  return "Compatibility unknown";
+  isDefault: boolean;
+  onSetDefault: (endpoint: AdvertisedEndpoint) => void;
 };
 
 const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
   endpoint,
+  isDefault,
+  onSetDefault,
 }: AdvertisedEndpointListRowProps) {
   return (
-    <div className={ITEM_ROW_CLASSNAME}>
-      <div className={ITEM_ROW_INNER_CLASSNAME}>
-        <div className="min-w-0 flex-1 space-y-1">
-          <div className="flex min-h-5 items-center gap-1.5">
-            <ConnectionStatusDot
-              tooltipText={`${endpoint.provider.label} · ${endpoint.reachability}`}
-              dotClassName={
-                endpoint.compatibility.hostedHttpsApp === "compatible"
-                  ? "bg-success"
-                  : "bg-muted-foreground/40"
-              }
-            />
-            <h3 className="text-sm font-medium text-foreground">{endpoint.label}</h3>
-            {endpoint.provider.isAddon ? (
-              <span className="rounded-md border border-border/50 bg-muted/50 px-1 py-0.5 text-[10px] text-muted-foreground/80">
-                Add-on
-              </span>
-            ) : null}
-          </div>
-          <p className="truncate text-xs text-muted-foreground" title={endpoint.httpBaseUrl}>
+    <div className={ENDPOINT_ROW_CLASSNAME}>
+      <div className="flex min-h-6 min-w-0 flex-col gap-2 sm:-my-0.5 sm:flex-row sm:items-center">
+        <div className="flex min-w-0 items-baseline gap-3">
+          <h3 className="shrink-0 text-sm leading-5 font-medium text-foreground">
+            {endpoint.label}
+          </h3>
+          <p
+            className="min-w-0 truncate text-xs leading-5 text-muted-foreground"
+            title={endpoint.httpBaseUrl}
+          >
             {endpoint.httpBaseUrl}
           </p>
         </div>
-        <p className="shrink-0 text-xs text-muted-foreground">
-          {endpointCompatibilityLabel(endpoint)}
-        </p>
+        <div className="ml-auto flex min-h-6 shrink-0 items-center justify-end gap-2">
+          {isDefault ? (
+            <span className="rounded-md border border-primary/30 bg-primary/10 px-1 py-0.5 text-[10px] text-primary">
+              Default
+            </span>
+          ) : null}
+          {!isDefault ? (
+            <Button size="xs" variant="outline" onClick={() => onSetDefault(endpoint)}>
+              Set as default
+            </Button>
+          ) : null}
+        </div>
       </div>
     </div>
   );
 });
 
+function NetworkAccessDescription({
+  endpoint,
+  hiddenEndpointCount,
+  expanded,
+  onToggleExpanded,
+  fallback,
+}: {
+  endpoint: AdvertisedEndpoint | null;
+  hiddenEndpointCount: number;
+  expanded: boolean;
+  onToggleExpanded: () => void;
+  fallback: ReactNode;
+}) {
+  if (!endpoint) {
+    return fallback;
+  }
+
+  return (
+    <span className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
+      <span className="min-w-0 truncate">Reachable at {endpoint.httpBaseUrl}</span>
+      {hiddenEndpointCount > 0 ? (
+        <button
+          type="button"
+          className="inline-flex h-5 shrink-0 items-center rounded-md border border-border/60 px-1.5 text-[11px] font-medium text-muted-foreground hover:bg-accent hover:text-foreground"
+          onClick={onToggleExpanded}
+          aria-expanded={expanded}
+        >
+          {expanded ? "Hide" : `+${hiddenEndpointCount}`}
+        </button>
+      ) : null}
+    </span>
+  );
+}
+
 type SavedBackendListRowProps = {
   environmentId: EnvironmentId;
   reconnectingEnvironmentId: EnvironmentId | null;
@@ -903,6 +1041,13 @@ export function ConnectionsSettings() {
   const [pendingDesktopServerExposureMode, setPendingDesktopServerExposureMode] = useState<
     DesktopServerExposureState["mode"] | null
   >(null);
+  const [isAdvertisedEndpointListExpanded, setIsAdvertisedEndpointListExpanded] = useState(false);
+  const defaultAdvertisedEndpointKey = useUiStateStore(
+    (state) => state.defaultAdvertisedEndpointKey,
+  );
+  const setDefaultAdvertisedEndpointKey = useUiStateStore(
+    (state) => state.setDefaultAdvertisedEndpointKey,
+  );
   const canManageLocalBackend = currentSessionRole === "owner";
   const isLocalBackendNetworkAccessible = desktopBridge
     ? desktopServerExposureState?.mode === "network-accessible"
@@ -1236,9 +1381,23 @@ export function ConnectionsSettings() {
     () => desktopPairingLinks.filter((pairingLink) => pairingLink.role === "client"),
     [desktopPairingLinks],
   );
-  const visibleDesktopAdvertisedEndpoints = isLocalBackendNetworkAccessible
-    ? desktopAdvertisedEndpoints
-    : [];
+  const visibleDesktopAdvertisedEndpoints = useMemo(
+    () => (isLocalBackendNetworkAccessible ? desktopAdvertisedEndpoints : []),
+    [desktopAdvertisedEndpoints, isLocalBackendNetworkAccessible],
+  );
+  const defaultDesktopAdvertisedEndpoint = useMemo(
+    () => selectPairingEndpoint(visibleDesktopAdvertisedEndpoints, defaultAdvertisedEndpointKey),
+    [defaultAdvertisedEndpointKey, visibleDesktopAdvertisedEndpoints],
+  );
+  const defaultDesktopAdvertisedEndpointKey = defaultDesktopAdvertisedEndpoint
+    ? endpointDefaultPreferenceKey(defaultDesktopAdvertisedEndpoint)
+    : null;
+  const handleSetDefaultAdvertisedEndpoint = useCallback(
+    (endpoint: AdvertisedEndpoint) => {
+      setDefaultAdvertisedEndpointKey(endpointDefaultPreferenceKey(endpoint));
+    },
+    [setDefaultAdvertisedEndpointKey],
+  );
   return (
     <SettingsPageContainer>
       {canManageLocalBackend ? (
@@ -1249,15 +1408,30 @@ export function ConnectionsSettings() {
                 <SettingsRow
                   title="Network access"
                   description={
-                    desktopServerExposureState?.endpointUrl
-                      ? `Reachable at ${desktopServerExposureState.endpointUrl}`
-                      : desktopServerExposureState?.mode === "network-accessible"
-                        ? desktopServerExposureState.advertisedHost
-                          ? `Exposed on all interfaces. Pairing links use ${desktopServerExposureState.advertisedHost}.`
-                          : "Exposed on all interfaces."
-                        : desktopServerExposureState
-                          ? "Limited to this machine."
-                          : "Loading…"
+                    isLocalBackendNetworkAccessible ? (
+                      <NetworkAccessDescription
+                        endpoint={defaultDesktopAdvertisedEndpoint}
+                        hiddenEndpointCount={Math.max(
+                          visibleDesktopAdvertisedEndpoints.length - 1,
+                          0,
+                        )}
+                        expanded={isAdvertisedEndpointListExpanded}
+                        onToggleExpanded={() =>
+                          setIsAdvertisedEndpointListExpanded((expanded) => !expanded)
+                        }
+                        fallback={
+                          desktopServerExposureState?.endpointUrl
+                            ? `Reachable at ${desktopServerExposureState.endpointUrl}`
+                            : desktopServerExposureState?.advertisedHost
+                              ? `Exposed on all interfaces. Pairing links use ${desktopServerExposureState.advertisedHost}.`
+                              : "Exposed on all interfaces."
+                        }
+                      />
+                    ) : desktopServerExposureState ? (
+                      "Limited to this machine."
+                    ) : (
+                      "Loading…"
+                    )
                   }
                   status={
                     desktopServerExposureError ? (
@@ -1330,9 +1504,19 @@ export function ConnectionsSettings() {
                     </AlertDialog>
                   }
                 />
-                {visibleDesktopAdvertisedEndpoints.map((endpoint) => (
-                  <AdvertisedEndpointListRow key={endpoint.id} endpoint={endpoint} />
-                ))}
+                {isAdvertisedEndpointListExpanded
+                  ? visibleDesktopAdvertisedEndpoints.map((endpoint) => {
+                      const endpointKey = endpointDefaultPreferenceKey(endpoint);
+                      return (
+                        <AdvertisedEndpointListRow
+                          key={endpoint.id}
+                          endpoint={endpoint}
+                          isDefault={endpointKey === defaultDesktopAdvertisedEndpointKey}
+                          onSetDefault={handleSetDefaultAdvertisedEndpoint}
+                        />
+                      );
+                    })
+                  : null}
               </>
             ) : (
               <SettingsRow
@@ -1384,6 +1568,7 @@ export function ConnectionsSettings() {
               <PairingClientsList
                 endpointUrl={desktopServerExposureState?.endpointUrl}
                 endpoints={visibleDesktopAdvertisedEndpoints}
+                defaultEndpointKey={defaultDesktopAdvertisedEndpointKey}
                 isLoading={isLoadingDesktopAccessManagement}
                 pairingLinks={visibleDesktopPairingLinks}
                 clientSessions={desktopClientSessions}
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index a08d0a42cdc..3230b070756 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -21,6 +21,7 @@ import { render } from "vitest-browser-react";
 import { __resetLocalApiForTests } from "../../localApi";
 import { AppAtomRegistryProvider, resetAppAtomRegistryForTests } from "../../rpc/atomRegistry";
 import { resetServerStateForTests, setServerConfigSnapshot } from "../../rpc/serverState";
+import { useUiStateStore } from "../../uiStateStore";
 import { ConnectionsSettings } from "./ConnectionsSettings";
 import { GeneralSettingsPanel } from "./SettingsPanels";
 import { SourceControlSettingsPanel } from "./SourceControlSettings";
@@ -347,6 +348,7 @@ describe("GeneralSettingsPanel observability", () => {
     resetServerStateForTests();
     await __resetLocalApiForTests();
     localStorage.clear();
+    useUiStateStore.setState({ defaultAdvertisedEndpointKey: null });
     authAccessHarness.reset();
   });
 
@@ -503,6 +505,104 @@ describe("GeneralSettingsPanel observability", () => {
       .not.toBeInTheDocument();
   });
 
+  it("collapses advertised endpoints behind the network access summary", async () => {
+    window.desktopBridge = createDesktopBridgeStub({
+      serverExposureState: {
+        mode: "network-accessible",
+        endpointUrl: "http://192.168.86.39:3773",
+        advertisedHost: "192.168.86.39",
+      },
+      advertisedEndpoints: [
+        {
+          id: "desktop-loopback:3773",
+          label: "This machine",
+          provider: {
+            id: "desktop-core",
+            label: "Desktop",
+            kind: "manual",
+            isAddon: false,
+          },
+          httpBaseUrl: "http://127.0.0.1:3773/",
+          wsBaseUrl: "ws://127.0.0.1:3773/",
+          reachability: "loopback",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-core",
+          status: "available",
+        },
+        {
+          id: "desktop-lan:http://192.168.86.39:3773",
+          label: "Local network",
+          provider: {
+            id: "desktop-core",
+            label: "Desktop",
+            kind: "manual",
+            isAddon: false,
+          },
+          httpBaseUrl: "http://192.168.86.39:3773/",
+          wsBaseUrl: "ws://192.168.86.39:3773/",
+          reachability: "lan",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-core",
+          status: "available",
+          isDefault: true,
+        },
+        {
+          id: "tailscale-ip:http://100.105.39.17:3773",
+          label: "Tailscale IP",
+          provider: {
+            id: "tailscale",
+            label: "Tailscale",
+            kind: "private-network",
+            isAddon: true,
+          },
+          httpBaseUrl: "http://100.105.39.17:3773/",
+          wsBaseUrl: "ws://100.105.39.17:3773/",
+          reachability: "private-network",
+          compatibility: {
+            hostedHttpsApp: "mixed-content-blocked",
+            desktopApp: "compatible",
+          },
+          source: "desktop-addon",
+          status: "available",
+        },
+      ],
+    });
+    authAccessHarness.setSnapshot({
+      pairingLinks: [],
+      clientSessions: [],
+    });
+    setServerConfigSnapshot(createBaseServerConfig());
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <ConnectionsSettings />
+      </AppAtomRegistryProvider>,
+    );
+
+    await expect
+      .element(page.getByText("Reachable at http://192.168.86.39:3773/"))
+      .toBeInTheDocument();
+    await expect.element(page.getByRole("button", { name: "+2" })).toBeInTheDocument();
+    await expect
+      .element(page.getByRole("heading", { name: "Local network", exact: true }))
+      .not.toBeInTheDocument();
+
+    await page.getByRole("button", { name: "+2" }).click();
+
+    await expect
+      .element(page.getByRole("heading", { name: "Local network", exact: true }))
+      .toBeInTheDocument();
+    await expect.element(page.getByText("Default", { exact: true })).toBeInTheDocument();
+    await page.getByRole("button", { name: "Set as default" }).first().click();
+    await expect.element(page.getByText("Reachable at http://127.0.0.1:3773/")).toBeInTheDocument();
+  });
+
   it("shows diagnostics inside About with a single logs-folder action", async () => {
     setServerConfigSnapshot(createBaseServerConfig());
 
@@ -638,7 +738,7 @@ describe("GeneralSettingsPanel observability", () => {
       .element(page.getByText("Client · Mobile · iOS · Safari · 192.168.1.88"))
       .toBeInTheDocument();
     await expect
-      .element(page.getByRole("button", { name: /^(Copy|Show link)$/ }))
+      .element(page.getByRole("button", { name: /^(Copy code|Show link)$/ }))
       .toBeInTheDocument();
     await expect.element(page.getByText("Revoke others")).toBeInTheDocument();
   });
diff --git a/apps/web/src/components/settings/settingsLayout.tsx b/apps/web/src/components/settings/settingsLayout.tsx
index 98769aca747..c464165bb3e 100644
--- a/apps/web/src/components/settings/settingsLayout.tsx
+++ b/apps/web/src/components/settings/settingsLayout.tsx
@@ -52,7 +52,7 @@ export function SettingsRow({
   children,
 }: {
   title: ReactNode;
-  description: string;
+  description: ReactNode;
   status?: ReactNode;
   resetAction?: ReactNode;
   control?: ReactNode;
diff --git a/apps/web/src/uiStateStore.test.ts b/apps/web/src/uiStateStore.test.ts
index ca5ed2b4b18..3e6aaebc0dc 100644
--- a/apps/web/src/uiStateStore.test.ts
+++ b/apps/web/src/uiStateStore.test.ts
@@ -10,6 +10,7 @@ import {
   type PersistedUiState,
   persistState,
   reorderProjects,
+  setDefaultAdvertisedEndpointKey,
   setProjectExpanded,
   setThreadChangedFilesExpanded,
   syncProjects,
@@ -23,6 +24,7 @@ function makeUiState(overrides: Partial<UiState> = {}): UiState {
     projectOrder: [],
     threadLastVisitedAtById: {},
     threadChangedFilesExpandedById: {},
+    defaultAdvertisedEndpointKey: null,
     ...overrides,
   };
 }
@@ -102,6 +104,18 @@ describe("uiStateStore pure functions", () => {
     expect(next).toBe(initialState);
   });
 
+  it("setDefaultAdvertisedEndpointKey stores endpoint preference by stable key", () => {
+    const initialState = makeUiState();
+
+    const next = setDefaultAdvertisedEndpointKey(initialState, "desktop-core:lan:http");
+
+    expect(next.defaultAdvertisedEndpointKey).toBe("desktop-core:lan:http");
+    expect(setDefaultAdvertisedEndpointKey(next, "desktop-core:lan:http")).toBe(next);
+    expect(setDefaultAdvertisedEndpointKey(next, "")).toMatchObject({
+      defaultAdvertisedEndpointKey: null,
+    });
+  });
+
   it("reorderProjects moves all member keys of a multi-member group together", () => {
     const keyALocal = "env-local:proj-a";
     const keyARemote = "env-remote:proj-a";
@@ -554,6 +568,17 @@ describe("uiStateStore persistence round-trip", () => {
     expect(rehydrated.projectOrder).toEqual([projectC.key, projectA.key, projectB.key]);
   });
 
+  it("persists the default advertised endpoint preference", () => {
+    const state = setDefaultAdvertisedEndpointKey(makeUiState(), "desktop-core:lan:http");
+
+    persistState(state);
+
+    const persisted = JSON.parse(
+      localStorageStub.getItem(PERSISTED_STATE_KEY) ?? "{}",
+    ) as PersistedUiState;
+    expect(persisted.defaultAdvertisedEndpointKey).toBe("desktop-core:lan:http");
+  });
+
   it("preserves expand state across restart when project's logical key changes", () => {
     // After restart, in-memory previousExpandedById is empty, so the
     // previousLogicalKey-to-state bridge in syncProjects cannot help. The
diff --git a/apps/web/src/uiStateStore.ts b/apps/web/src/uiStateStore.ts
index 8bd65ffc56a..b76f5f6859a 100644
--- a/apps/web/src/uiStateStore.ts
+++ b/apps/web/src/uiStateStore.ts
@@ -19,6 +19,7 @@ export interface PersistedUiState {
   collapsedProjectCwds?: string[];
   expandedProjectCwds?: string[];
   projectOrderCwds?: string[];
+  defaultAdvertisedEndpointKey?: string | null;
   threadChangedFilesExpandedById?: Record<string, Record<string, boolean>>;
 }
 
@@ -32,7 +33,11 @@ export interface UiThreadState {
   threadChangedFilesExpandedById: Record<string, Record<string, boolean>>;
 }
 
-export interface UiState extends UiProjectState, UiThreadState {}
+export interface UiEndpointState {
+  defaultAdvertisedEndpointKey: string | null;
+}
+
+export interface UiState extends UiProjectState, UiThreadState, UiEndpointState {}
 
 export interface SyncProjectInput {
   /** Physical project key (env + cwd). Used for manual sort order. */
@@ -52,6 +57,7 @@ const initialState: UiState = {
   projectOrder: [],
   threadLastVisitedAtById: {},
   threadChangedFilesExpandedById: {},
+  defaultAdvertisedEndpointKey: null,
 };
 
 const persistedCollapsedProjectCwds = new Set<string>();
@@ -88,6 +94,11 @@ function readPersistedState(): UiState {
     hydratePersistedProjectState(parsed);
     return {
       ...initialState,
+      defaultAdvertisedEndpointKey:
+        typeof parsed.defaultAdvertisedEndpointKey === "string" &&
+        parsed.defaultAdvertisedEndpointKey.length > 0
+          ? parsed.defaultAdvertisedEndpointKey
+          : null,
       threadChangedFilesExpandedById: sanitizePersistedThreadChangedFilesExpanded(
         parsed.threadChangedFilesExpandedById,
       ),
@@ -179,6 +190,7 @@ export function persistState(state: UiState): void {
         collapsedProjectCwds,
         expandedProjectCwds,
         projectOrderCwds,
+        defaultAdvertisedEndpointKey: state.defaultAdvertisedEndpointKey,
         threadChangedFilesExpandedById,
       } satisfies PersistedUiState),
     );
@@ -532,6 +544,17 @@ export function setThreadChangedFilesExpanded(
   };
 }
 
+export function setDefaultAdvertisedEndpointKey(state: UiState, key: string | null): UiState {
+  const nextKey = key && key.length > 0 ? key : null;
+  if (state.defaultAdvertisedEndpointKey === nextKey) {
+    return state;
+  }
+  return {
+    ...state,
+    defaultAdvertisedEndpointKey: nextKey,
+  };
+}
+
 export function toggleProject(state: UiState, projectId: string): UiState {
   const expanded = state.projectExpandedById[projectId] ?? true;
   return {
@@ -606,6 +629,7 @@ interface UiStateStore extends UiState {
   markThreadUnread: (threadId: string, latestTurnCompletedAt: string | null | undefined) => void;
   clearThreadUi: (threadId: string) => void;
   setThreadChangedFilesExpanded: (threadId: string, turnId: string, expanded: boolean) => void;
+  setDefaultAdvertisedEndpointKey: (key: string | null) => void;
   toggleProject: (projectId: string) => void;
   setProjectExpanded: (projectId: string, expanded: boolean) => void;
   reorderProjects: (
@@ -625,6 +649,8 @@ export const useUiStateStore = create<UiStateStore>((set) => ({
   clearThreadUi: (threadId) => set((state) => clearThreadUi(state, threadId)),
   setThreadChangedFilesExpanded: (threadId, turnId, expanded) =>
     set((state) => setThreadChangedFilesExpanded(state, threadId, turnId, expanded)),
+  setDefaultAdvertisedEndpointKey: (key) =>
+    set((state) => setDefaultAdvertisedEndpointKey(state, key)),
   toggleProject: (projectId) => set((state) => toggleProject(state, projectId)),
   setProjectExpanded: (projectId, expanded) =>
     set((state) => setProjectExpanded(state, projectId, expanded)),

From 88006a44161dcd313e1d7001e78e12066f404c5e Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:13:05 -0700
Subject: [PATCH 09/74] feat(remote): add advertised endpoint registry

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .../settings/ConnectionsSettings.tsx          | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 31253781930..2d3bb458f43 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -307,6 +307,28 @@ function resolveAdvertisedEndpointPairingUrl(
   return resolveDesktopPairingUrl(endpoint.httpBaseUrl, credential);
 }
 
+function selectPairingEndpoint(
+  endpoints: ReadonlyArray<AdvertisedEndpoint>,
+): AdvertisedEndpoint | null {
+  const availableEndpoints = endpoints.filter((endpoint) => endpoint.status !== "unavailable");
+  return (
+    availableEndpoints.find((endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible") ??
+    availableEndpoints.find((endpoint) => endpoint.isDefault) ??
+    availableEndpoints.find((endpoint) => endpoint.reachability !== "loopback") ??
+    null
+  );
+}
+
+function resolveAdvertisedEndpointPairingUrl(
+  endpoint: AdvertisedEndpoint,
+  credential: string,
+): string {
+  if (endpoint.compatibility.hostedHttpsApp === "compatible") {
+    return resolveHostedPairingUrl(endpoint.httpBaseUrl, credential);
+  }
+  return resolveDesktopPairingUrl(endpoint.httpBaseUrl, credential);
+}
+
 function resolveCurrentOriginPairingUrl(credential: string): string {
   const url = new URL("/pair", window.location.href);
   return setPairingTokenOnUrl(url, credential).toString();

From 32be0a0b23bc5cf1a429550638307cb934e2a17c Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:15:22 -0700
Subject: [PATCH 10/74] feat(desktop): add tailscale endpoint addon

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/main.ts                      |  10 +-
 .../src/tailscaleEndpointProvider.test.ts     |  86 ++++++++++
 apps/desktop/src/tailscaleEndpointProvider.ts | 155 ++++++++++++++++++
 3 files changed, 249 insertions(+), 2 deletions(-)
 create mode 100644 apps/desktop/src/tailscaleEndpointProvider.test.ts
 create mode 100644 apps/desktop/src/tailscaleEndpointProvider.ts

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index c5713d2035b..9d4888b5811 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -79,6 +79,7 @@ import {
 import { isArm64HostRunningIntelBuild, resolveDesktopRuntimeInfo } from "./runtimeArch.ts";
 import { resolveDesktopAppBranding } from "./appBranding.ts";
 import { bindFirstRevealTrigger, type RevealSubscription } from "./windowReveal.ts";
+import { resolveTailscaleAdvertisedEndpoints } from "./tailscaleEndpointProvider.ts";
 
 syncShellEnvironment();
 
@@ -313,18 +314,23 @@ function getDesktopServerExposureState(): DesktopServerExposureState {
   };
 }
 
-function getDesktopAdvertisedEndpoints() {
+async function getDesktopAdvertisedEndpoints() {
   const exposure = resolveDesktopServerExposure({
     mode: desktopServerExposureMode,
     port: backendPort,
     networkInterfaces: OS.networkInterfaces(),
     ...(backendAdvertisedHost ? { advertisedHostOverride: backendAdvertisedHost } : {}),
   });
-  return resolveDesktopCoreAdvertisedEndpoints({
+  const coreEndpoints = resolveDesktopCoreAdvertisedEndpoints({
     port: backendPort,
     exposure,
     customHttpsEndpointUrls: resolveCustomHttpsEndpointUrls(),
   });
+  const tailscaleEndpoints = await resolveTailscaleAdvertisedEndpoints({
+    port: backendPort,
+    networkInterfaces: OS.networkInterfaces(),
+  });
+  return [...coreEndpoints, ...tailscaleEndpoints];
 }
 
 function getDesktopSecretStorage() {
diff --git a/apps/desktop/src/tailscaleEndpointProvider.test.ts b/apps/desktop/src/tailscaleEndpointProvider.test.ts
new file mode 100644
index 00000000000..e3fe3b88204
--- /dev/null
+++ b/apps/desktop/src/tailscaleEndpointProvider.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  isTailscaleIpv4Address,
+  parseTailscaleMagicDnsName,
+  resolveTailscaleAdvertisedEndpoints,
+} from "./tailscaleEndpointProvider.ts";
+
+describe("tailscale endpoint provider", () => {
+  it("detects Tailnet IPv4 addresses", () => {
+    expect(isTailscaleIpv4Address("100.64.0.1")).toBe(true);
+    expect(isTailscaleIpv4Address("100.127.255.254")).toBe(true);
+    expect(isTailscaleIpv4Address("100.128.0.1")).toBe(false);
+    expect(isTailscaleIpv4Address("192.168.1.44")).toBe(false);
+  });
+
+  it("parses MagicDNS names from tailscale status", () => {
+    expect(
+      parseTailscaleMagicDnsName(JSON.stringify({ Self: { DNSName: "desktop.tail.ts.net." } })),
+    ).toBe("desktop.tail.ts.net");
+    expect(parseTailscaleMagicDnsName("{}")).toBeNull();
+    expect(parseTailscaleMagicDnsName("not-json")).toBeNull();
+  });
+
+  it("resolves Tailscale endpoints as add-on advertised endpoints", async () => {
+    await expect(
+      resolveTailscaleAdvertisedEndpoints({
+        port: 3773,
+        networkInterfaces: {
+          tailscale0: [
+            {
+              address: "100.100.100.100",
+              family: "IPv4",
+              internal: false,
+              netmask: "255.192.0.0",
+              cidr: "100.100.100.100/10",
+              mac: "00:00:00:00:00:00",
+            },
+          ],
+        },
+        statusJson: JSON.stringify({ Self: { DNSName: "desktop.tail.ts.net." } }),
+      }),
+    ).resolves.toEqual([
+      {
+        id: "tailscale-ip:http://100.100.100.100:3773",
+        label: "Tailscale IP",
+        provider: {
+          id: "tailscale",
+          label: "Tailscale",
+          kind: "private-network",
+          isAddon: true,
+        },
+        httpBaseUrl: "http://100.100.100.100:3773/",
+        wsBaseUrl: "ws://100.100.100.100:3773/",
+        reachability: "private-network",
+        compatibility: {
+          hostedHttpsApp: "mixed-content-blocked",
+          desktopApp: "compatible",
+        },
+        source: "desktop-addon",
+        status: "available",
+        description: "Reachable from devices on the same Tailnet.",
+      },
+      {
+        id: "tailscale-magicdns:https://desktop.tail.ts.net",
+        label: "Tailscale HTTPS",
+        provider: {
+          id: "tailscale",
+          label: "Tailscale",
+          kind: "private-network",
+          isAddon: true,
+        },
+        httpBaseUrl: "https://desktop.tail.ts.net/",
+        wsBaseUrl: "wss://desktop.tail.ts.net/",
+        reachability: "private-network",
+        compatibility: {
+          hostedHttpsApp: "requires-configuration",
+          desktopApp: "compatible",
+        },
+        source: "desktop-addon",
+        status: "unknown",
+        description: "MagicDNS hostname. Configure Tailscale Serve for HTTPS access.",
+      },
+    ]);
+  });
+});
diff --git a/apps/desktop/src/tailscaleEndpointProvider.ts b/apps/desktop/src/tailscaleEndpointProvider.ts
new file mode 100644
index 00000000000..e92e8bee772
--- /dev/null
+++ b/apps/desktop/src/tailscaleEndpointProvider.ts
@@ -0,0 +1,155 @@
+import * as ChildProcess from "node:child_process";
+import type { NetworkInterfaceInfo } from "node:os";
+
+import {
+  createAdvertisedEndpoint,
+  type CreateAdvertisedEndpointInput,
+} from "@t3tools/client-runtime";
+import type { AdvertisedEndpoint, AdvertisedEndpointProvider } from "@t3tools/contracts";
+
+const TAILSCALE_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
+  id: "tailscale",
+  label: "Tailscale",
+  kind: "private-network",
+  isAddon: true,
+};
+
+const TAILSCALE_STATUS_TIMEOUT_MS = 1_500;
+
+interface TailscaleStatusSelf {
+  readonly DNSName?: unknown;
+  readonly TailscaleIPs?: unknown;
+}
+
+interface TailscaleStatusJson {
+  readonly Self?: TailscaleStatusSelf;
+}
+
+function createTailscaleEndpoint(
+  input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
+): AdvertisedEndpoint {
+  return createAdvertisedEndpoint({
+    ...input,
+    provider: TAILSCALE_ENDPOINT_PROVIDER,
+    source: "desktop-addon",
+  });
+}
+
+export function isTailscaleIpv4Address(address: string): boolean {
+  const parts = address.split(".");
+  if (parts.length !== 4) {
+    return false;
+  }
+  const [first, second, third, fourth] = parts.map((part) => Number.parseInt(part, 10));
+  if (
+    first === undefined ||
+    second === undefined ||
+    third === undefined ||
+    fourth === undefined ||
+    [first, second, third, fourth].some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return false;
+  }
+  return first === 100 && second >= 64 && second <= 127;
+}
+
+export function resolveTailscaleIpAdvertisedEndpoints(input: {
+  readonly port: number;
+  readonly networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>;
+}): readonly AdvertisedEndpoint[] {
+  const seen = new Set<string>();
+  const endpoints: AdvertisedEndpoint[] = [];
+
+  for (const interfaceAddresses of Object.values(input.networkInterfaces)) {
+    if (!interfaceAddresses) continue;
+
+    for (const address of interfaceAddresses) {
+      if (address.internal) continue;
+      if (address.family !== "IPv4") continue;
+      if (!isTailscaleIpv4Address(address.address)) continue;
+      if (seen.has(address.address)) continue;
+      seen.add(address.address);
+
+      endpoints.push(
+        createTailscaleEndpoint({
+          id: `tailscale-ip:http://${address.address}:${input.port}`,
+          label: "Tailscale IP",
+          httpBaseUrl: `http://${address.address}:${input.port}`,
+          reachability: "private-network",
+          status: "available",
+          description: "Reachable from devices on the same Tailnet.",
+        }),
+      );
+    }
+  }
+
+  return endpoints;
+}
+
+export function parseTailscaleMagicDnsName(rawStatusJson: string): string | null {
+  let parsed: TailscaleStatusJson;
+  try {
+    parsed = JSON.parse(rawStatusJson) as TailscaleStatusJson;
+  } catch {
+    return null;
+  }
+
+  const dnsName = parsed.Self?.DNSName;
+  if (typeof dnsName !== "string") {
+    return null;
+  }
+
+  const normalized = dnsName.trim().replace(/\.$/u, "");
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function resolveTailscaleMagicDnsAdvertisedEndpoint(input: {
+  readonly dnsName: string | null;
+}): AdvertisedEndpoint | null {
+  if (!input.dnsName) {
+    return null;
+  }
+
+  return createTailscaleEndpoint({
+    id: `tailscale-magicdns:https://${input.dnsName}`,
+    label: "Tailscale HTTPS",
+    httpBaseUrl: `https://${input.dnsName}`,
+    reachability: "private-network",
+    hostedHttpsCompatibility: "requires-configuration",
+    status: "unknown",
+    description: "MagicDNS hostname. Configure Tailscale Serve for HTTPS access.",
+  });
+}
+
+async function readTailscaleStatusJson(): Promise<string | null> {
+  return await new Promise((resolve) => {
+    const child = ChildProcess.execFile(
+      "tailscale",
+      ["status", "--json"],
+      { timeout: TAILSCALE_STATUS_TIMEOUT_MS, windowsHide: true },
+      (error, stdout) => {
+        if (error) {
+          resolve(null);
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+    child.once("error", () => resolve(null));
+  });
+}
+
+export async function resolveTailscaleAdvertisedEndpoints(input: {
+  readonly port: number;
+  readonly networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>;
+  readonly statusJson?: string | null;
+}): Promise<readonly AdvertisedEndpoint[]> {
+  const ipEndpoints = resolveTailscaleIpAdvertisedEndpoints(input);
+  const statusJson =
+    input.statusJson === undefined ? await readTailscaleStatusJson() : input.statusJson;
+  const magicDnsEndpoint = resolveTailscaleMagicDnsAdvertisedEndpoint({
+    dnsName: statusJson ? parseTailscaleMagicDnsName(statusJson) : null,
+  });
+
+  return magicDnsEndpoint ? [...ipEndpoints, magicDnsEndpoint] : ipEndpoints;
+}

From 9d50f37cfc987a98650986e741593038a3cc8cef Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:48:32 -0700
Subject: [PATCH 11/74] fix(web): dedupe advertised pairing helpers

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .../settings/ConnectionsSettings.tsx          | 22 -------------------
 1 file changed, 22 deletions(-)

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 2d3bb458f43..31253781930 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -307,28 +307,6 @@ function resolveAdvertisedEndpointPairingUrl(
   return resolveDesktopPairingUrl(endpoint.httpBaseUrl, credential);
 }
 
-function selectPairingEndpoint(
-  endpoints: ReadonlyArray<AdvertisedEndpoint>,
-): AdvertisedEndpoint | null {
-  const availableEndpoints = endpoints.filter((endpoint) => endpoint.status !== "unavailable");
-  return (
-    availableEndpoints.find((endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible") ??
-    availableEndpoints.find((endpoint) => endpoint.isDefault) ??
-    availableEndpoints.find((endpoint) => endpoint.reachability !== "loopback") ??
-    null
-  );
-}
-
-function resolveAdvertisedEndpointPairingUrl(
-  endpoint: AdvertisedEndpoint,
-  credential: string,
-): string {
-  if (endpoint.compatibility.hostedHttpsApp === "compatible") {
-    return resolveHostedPairingUrl(endpoint.httpBaseUrl, credential);
-  }
-  return resolveDesktopPairingUrl(endpoint.httpBaseUrl, credential);
-}
-
 function resolveCurrentOriginPairingUrl(credential: string): string {
   const url = new URL("/pair", window.location.href);
   return setPairingTokenOnUrl(url, credential).toString();

From 09f37262c9ac627f8680c93b4b084c7cf687cc40 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:56:39 -0700
Subject: [PATCH 12/74] docs(remote): document tailscale endpoint add-on

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .docs/remote-architecture.md | 17 +++++++++++++++++
 REMOTE.md                    | 14 ++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/.docs/remote-architecture.md b/.docs/remote-architecture.md
index 1748df5db65..89b3d41ea0c 100644
--- a/.docs/remote-architecture.md
+++ b/.docs/remote-architecture.md
@@ -136,6 +136,21 @@ When no user default is saved, endpoint selection should prefer:
 
 This keeps endpoint discovery centralized without making any one provider, such as Tailscale or a future tunnel service, part of the core environment model.
 
+### Endpoint providers
+
+Endpoint providers are add-ons that contribute advertised endpoints for the current environment.
+
+The provider boundary is intentionally outside the core environment model:
+
+- core owns `ExecutionEnvironment`, saved environments, pairing, and connection lifecycle
+- providers discover or synthesize endpoints
+- providers return normalized `AdvertisedEndpoint` records
+- the UI and pairing logic select from those records without knowing provider-specific commands
+
+The first provider is Tailscale. It can discover Tailnet IP and MagicDNS addresses from the local machine and publish them as additional endpoint candidates. Future providers, such as a hosted tunnel service, should plug into the same shape rather than adding a separate remote environment path.
+
+Provider-specific confidence should remain a hint. A Tailscale endpoint still needs a successful browser or desktop connection before the client treats it as connected.
+
 ### Hosted pairing request
 
 A hosted pairing request is a bootstrap URL for the static web app, not a transport.
@@ -220,6 +235,8 @@ This is especially useful when:
 - mobile must reach a desktop-hosted environment
 - a machine should be reachable without exposing raw LAN or public ports
 
+Tailscale-backed access sits here architecturally even though the current implementation is endpoint discovery rather than a T3-managed tunnel. It contributes private-network endpoints and lets the existing HTTP/WebSocket client path do the actual connection.
+
 ### 3. Desktop-managed SSH access
 
 SSH is an access and launch helper, not a separate environment type.
diff --git a/REMOTE.md b/REMOTE.md
index f5ddccaa85a..afe22bd6040 100644
--- a/REMOTE.md
+++ b/REMOTE.md
@@ -35,6 +35,20 @@ When no user default is saved, the app chooses the best reachable endpoint for p
 
 If the copied link points directly at `http://192.168.x.y:3773`, open it from a client that can reach that LAN address. If it points at `https://app.t3.codes/pair?...`, the hosted web app will save the environment and connect directly to the backend URL in the link.
 
+### Tailscale Endpoints
+
+When the desktop app can detect Tailscale, it adds Tailnet endpoints to the reachable endpoint list.
+
+Depending on your Tailscale setup, this may include:
+
+- the machine's `100.x.y.z` Tailnet IP
+- a MagicDNS name
+- an HTTPS MagicDNS endpoint when Tailscale HTTPS is available for the machine
+
+The Tailscale support is an endpoint provider add-on. The core remote model still works without Tailscale: LAN HTTP endpoints, custom HTTPS endpoints, future tunnels, and SSH-launched environments all use the same saved environment and pairing flow.
+
+For `https://app.t3.codes`, prefer an HTTPS Tailnet or other HTTPS endpoint. A plain `http://100.x.y.z:3773` endpoint can still work from a desktop client or another browser page served over HTTP, but it will not work from the hosted HTTPS app because of browser mixed-content rules.
+
 ### Option 2: Headless Server (CLI)
 
 Use this when you want to run the server without a GUI, for example on a remote machine over SSH.

From f5624f661ab8aa924d729cbc0b7003064c87ab14 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 21:38:19 -0700
Subject: [PATCH 13/74] fix(desktop): include port in tailscale https endpoint

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/tailscaleEndpointProvider.test.ts | 6 +++---
 apps/desktop/src/tailscaleEndpointProvider.ts      | 7 +++++--
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/tailscaleEndpointProvider.test.ts b/apps/desktop/src/tailscaleEndpointProvider.test.ts
index e3fe3b88204..d228a2c3bf1 100644
--- a/apps/desktop/src/tailscaleEndpointProvider.test.ts
+++ b/apps/desktop/src/tailscaleEndpointProvider.test.ts
@@ -62,7 +62,7 @@ describe("tailscale endpoint provider", () => {
         description: "Reachable from devices on the same Tailnet.",
       },
       {
-        id: "tailscale-magicdns:https://desktop.tail.ts.net",
+        id: "tailscale-magicdns:https://desktop.tail.ts.net:3773",
         label: "Tailscale HTTPS",
         provider: {
           id: "tailscale",
@@ -70,8 +70,8 @@ describe("tailscale endpoint provider", () => {
           kind: "private-network",
           isAddon: true,
         },
-        httpBaseUrl: "https://desktop.tail.ts.net/",
-        wsBaseUrl: "wss://desktop.tail.ts.net/",
+        httpBaseUrl: "https://desktop.tail.ts.net:3773/",
+        wsBaseUrl: "wss://desktop.tail.ts.net:3773/",
         reachability: "private-network",
         compatibility: {
           hostedHttpsApp: "requires-configuration",
diff --git a/apps/desktop/src/tailscaleEndpointProvider.ts b/apps/desktop/src/tailscaleEndpointProvider.ts
index e92e8bee772..75e3096d6b2 100644
--- a/apps/desktop/src/tailscaleEndpointProvider.ts
+++ b/apps/desktop/src/tailscaleEndpointProvider.ts
@@ -105,15 +105,17 @@ export function parseTailscaleMagicDnsName(rawStatusJson: string): string | null
 
 export function resolveTailscaleMagicDnsAdvertisedEndpoint(input: {
   readonly dnsName: string | null;
+  readonly port: number;
 }): AdvertisedEndpoint | null {
   if (!input.dnsName) {
     return null;
   }
 
+  const httpBaseUrl = `https://${input.dnsName}:${input.port}`;
   return createTailscaleEndpoint({
-    id: `tailscale-magicdns:https://${input.dnsName}`,
+    id: `tailscale-magicdns:${httpBaseUrl}`,
     label: "Tailscale HTTPS",
-    httpBaseUrl: `https://${input.dnsName}`,
+    httpBaseUrl,
     reachability: "private-network",
     hostedHttpsCompatibility: "requires-configuration",
     status: "unknown",
@@ -149,6 +151,7 @@ export async function resolveTailscaleAdvertisedEndpoints(input: {
     input.statusJson === undefined ? await readTailscaleStatusJson() : input.statusJson;
   const magicDnsEndpoint = resolveTailscaleMagicDnsAdvertisedEndpoint({
     dnsName: statusJson ? parseTailscaleMagicDnsName(statusJson) : null,
+    port: input.port,
   });
 
   return magicDnsEndpoint ? [...ipEndpoints, magicDnsEndpoint] : ipEndpoints;

From b124bf8fdee516e9afbbdc13a39fc8ed10cc88a3 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 14 Apr 2026 14:46:21 -0700
Subject: [PATCH 14/74] Add remote SSH environment launch support

- Discover SSH hosts and persist SSH targets
- Bootstrap tunneled SSH sessions with desktop password prompts
- Extend IPC and storage tests for SSH metadata
---
 apps/desktop/src/clientPersistence.test.ts    |    6 +
 apps/desktop/src/clientPersistence.ts         |   15 +-
 apps/desktop/src/main.ts                      |  297 +++++
 apps/desktop/src/preload.ts                   |   32 +
 apps/desktop/src/sshEnvironment.test.ts       |  196 ++++
 apps/desktop/src/sshEnvironment.ts            | 1013 +++++++++++++++++
 apps/web/src/clientPersistenceStorage.test.ts |    6 +
 apps/web/src/clientPersistenceStorage.ts      |   17 +-
 .../desktop/SshPasswordPromptDialog.tsx       |  114 ++
 .../settings/ConnectionsSettings.tsx          |  567 ++++++++-
 .../settings/SettingsPanels.browser.tsx       |  113 ++
 apps/web/src/components/ui/dialog.tsx         |    4 +-
 apps/web/src/environments/remote/api.ts       |    6 +
 apps/web/src/environments/runtime/catalog.ts  |    2 +
 apps/web/src/environments/runtime/index.ts    |    1 +
 .../service.addSavedEnvironment.test.ts       |  106 +-
 apps/web/src/environments/runtime/service.ts  |  469 ++++++--
 apps/web/src/localApi.test.ts                 |   18 +
 apps/web/src/routes/__root.tsx                |    2 +
 packages/contracts/src/ipc.ts                 |   47 +
 20 files changed, 2862 insertions(+), 169 deletions(-)
 create mode 100644 apps/desktop/src/sshEnvironment.test.ts
 create mode 100644 apps/desktop/src/sshEnvironment.ts
 create mode 100644 apps/web/src/components/desktop/SshPasswordPromptDialog.tsx

diff --git a/apps/desktop/src/clientPersistence.test.ts b/apps/desktop/src/clientPersistence.test.ts
index 71b6b7df4e8..285c0d75a9b 100644
--- a/apps/desktop/src/clientPersistence.test.ts
+++ b/apps/desktop/src/clientPersistence.test.ts
@@ -71,6 +71,12 @@ const savedRegistryRecord: PersistedSavedEnvironmentRecord = {
   wsBaseUrl: "wss://remote.example.com/",
   createdAt: "2026-04-09T00:00:00.000Z",
   lastConnectedAt: "2026-04-09T01:00:00.000Z",
+  desktopSsh: {
+    alias: "devbox",
+    hostname: "devbox.example.com",
+    username: "julius",
+    port: 22,
+  },
 };
 
 describe("clientPersistence", () => {
diff --git a/apps/desktop/src/clientPersistence.ts b/apps/desktop/src/clientPersistence.ts
index ad08a0036f1..09a3494dbc7 100644
--- a/apps/desktop/src/clientPersistence.ts
+++ b/apps/desktop/src/clientPersistence.ts
@@ -57,6 +57,12 @@ function isPersistedSavedEnvironmentStorageRecord(
     typeof value.wsBaseUrl === "string" &&
     typeof value.createdAt === "string" &&
     (value.lastConnectedAt === null || typeof value.lastConnectedAt === "string") &&
+    (value.desktopSsh === undefined ||
+      (Predicate.isObject(value.desktopSsh) &&
+        typeof value.desktopSsh.alias === "string" &&
+        typeof value.desktopSsh.hostname === "string" &&
+        (value.desktopSsh.username === null || typeof value.desktopSsh.username === "string") &&
+        (value.desktopSsh.port === null || typeof value.desktopSsh.port === "number"))) &&
     (value.encryptedBearerToken === undefined || typeof value.encryptedBearerToken === "string")
   );
 }
@@ -77,7 +83,7 @@ function readSavedEnvironmentRegistryDocument(filePath: string): SavedEnvironmen
 function toPersistedSavedEnvironmentRecord(
   record: PersistedSavedEnvironmentStorageRecord,
 ): PersistedSavedEnvironmentRecord {
-  return {
+  const nextRecord = {
     environmentId: record.environmentId,
     label: record.label,
     httpBaseUrl: record.httpBaseUrl,
@@ -85,6 +91,7 @@ function toPersistedSavedEnvironmentRecord(
     createdAt: record.createdAt,
     lastConnectedAt: record.lastConnectedAt,
   };
+  return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
 }
 
 export function readClientSettings(settingsPath: string): ClientSettings | null {
@@ -134,6 +141,7 @@ export function writeSavedEnvironmentRegistry(
             wsBaseUrl: record.wsBaseUrl,
             createdAt: record.createdAt,
             lastConnectedAt: record.lastConnectedAt,
+            ...(record.desktopSsh ? { desktopSsh: record.desktopSsh } : {}),
             encryptedBearerToken,
           }
         : record;
@@ -189,7 +197,7 @@ export function writeSavedEnvironmentSecret(input: {
       const encryptedBearerToken = input.secretStorage
         .encryptString(input.secret)
         .toString("base64");
-      return {
+      const nextRecord = {
         environmentId: record.environmentId,
         label: record.label,
         httpBaseUrl: record.httpBaseUrl,
@@ -197,7 +205,8 @@ export function writeSavedEnvironmentSecret(input: {
         createdAt: record.createdAt,
         lastConnectedAt: record.lastConnectedAt,
         encryptedBearerToken,
-      } satisfies PersistedSavedEnvironmentStorageRecord;
+      };
+      return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
     }),
   } satisfies SavedEnvironmentRegistryDocument);
   return found;
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 9d4888b5811..30e811ed746 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -20,7 +20,13 @@ import {
 } from "electron";
 import type { MenuItemConstructorOptions, OpenDialogOptions } from "electron";
 import type {
+  AuthBearerBootstrapResult,
+  AuthSessionState,
+  AuthWebSocketTokenResult,
   ClientSettings,
+  DesktopSshPasswordPromptRequest,
+  ExecutionEnvironmentDescriptor,
+  DesktopSshEnvironmentTarget,
   DesktopTheme,
   DesktopAppBranding,
   DesktopServerExposureMode,
@@ -59,6 +65,7 @@ import {
   resolveDesktopCoreAdvertisedEndpoints,
   resolveDesktopServerExposure,
 } from "./serverExposure.ts";
+import { DesktopSshEnvironmentManager } from "./sshEnvironment.ts";
 import { syncShellEnvironment } from "./syncShellEnvironment.ts";
 import { waitForBackendStartupReady } from "./backendStartupReadiness.ts";
 import { getAutoUpdateDisabledReason, shouldBroadcastDownloadProgress } from "./updateState.ts";
@@ -104,6 +111,14 @@ const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-re
 const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:get-saved-environment-secret";
 const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secret";
 const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
+const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
+const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
+const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
+const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
+const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
+const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
+const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
+const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
 const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
@@ -162,6 +177,7 @@ function resolvePickFolderDefaultPath(rawOptions: unknown): string | undefined {
 }
 const DESKTOP_LOOPBACK_HOST = "127.0.0.1";
 const DESKTOP_REQUIRED_PORT_PROBE_HOSTS = ["0.0.0.0", "::"] as const;
+const SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
 const TITLEBAR_HEIGHT = 40;
 const TITLEBAR_COLOR = "#01000000"; // #00000000 does not work correctly on Linux
 const TITLEBAR_LIGHT_SYMBOL_COLOR = "#1f2937";
@@ -206,6 +222,12 @@ type LinuxDesktopNamedApp = Electron.App & {
   setDesktopName?: (desktopName: string) => void;
 };
 
+interface PendingSshPasswordPrompt {
+  readonly resolve: (password: string | null) => void;
+  readonly reject: (error: Error) => void;
+  readonly timeout: ReturnType<typeof setTimeout>;
+}
+
 let mainWindow: BrowserWindow | null = null;
 let backendProcess: ChildProcess.ChildProcess | null = null;
 let backendPort = 0;
@@ -229,6 +251,7 @@ let restoreStdIoCapture: (() => void) | null = null;
 let backendObservabilitySettings = readPersistedBackendObservabilitySettings();
 let desktopSettings = readDesktopSettings(DESKTOP_SETTINGS_PATH, app.getVersion());
 let desktopServerExposureMode: DesktopServerExposureMode = desktopSettings.serverExposureMode;
+const pendingSshPasswordPrompts = new Map<string, PendingSshPasswordPrompt>();
 
 let destructiveMenuIconCache: Electron.NativeImage | null | undefined;
 const expectedBackendExitChildren = new WeakSet<ChildProcess.ChildProcess>();
@@ -405,6 +428,7 @@ function relaunchDesktopApp(reason: string): void {
           `desktop relaunch backend shutdown warning message=${formatErrorMessage(error)}`,
         );
       })
+      .then(() => desktopSshEnvironmentManager.dispose().catch(() => undefined))
       .finally(() => {
         restoreStdIoCapture?.();
         if (isDevelopment) {
@@ -467,6 +491,128 @@ function getSafeTheme(rawTheme: unknown): DesktopTheme | null {
   return null;
 }
 
+function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarget | null {
+  if (typeof rawTarget !== "object" || rawTarget === null) {
+    return null;
+  }
+
+  const target = rawTarget as Partial<DesktopSshEnvironmentTarget>;
+  if (typeof target.alias !== "string" || typeof target.hostname !== "string") {
+    return null;
+  }
+  if (
+    target.username !== null &&
+    target.username !== undefined &&
+    typeof target.username !== "string"
+  ) {
+    return null;
+  }
+  if (target.port !== null && target.port !== undefined && !Number.isInteger(target.port)) {
+    return null;
+  }
+
+  return {
+    alias: target.alias.trim(),
+    hostname: target.hostname.trim(),
+    username: target.username?.trim() || null,
+    port: target.port ?? null,
+  };
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname
+    .trim()
+    .toLowerCase()
+    .replace(/^\[(.*)\]$/, "$1");
+  return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
+}
+
+function resolveLoopbackSshHttpUrl(rawHttpBaseUrl: unknown, pathname: string): URL {
+  if (typeof rawHttpBaseUrl !== "string" || rawHttpBaseUrl.trim().length === 0) {
+    throw new Error("Invalid SSH forwarded http base URL.");
+  }
+
+  let baseUrl: URL;
+  try {
+    baseUrl = new URL(rawHttpBaseUrl);
+  } catch {
+    throw new Error("Invalid SSH forwarded http base URL.");
+  }
+
+  if (!isLoopbackHostname(baseUrl.hostname)) {
+    throw new Error("SSH desktop bridge only supports loopback forwarded URLs.");
+  }
+
+  const url = new URL(baseUrl.toString());
+  url.pathname = pathname;
+  url.search = "";
+  url.hash = "";
+  return url;
+}
+
+async function readRemoteFetchErrorMessage(
+  response: Response,
+  fallbackMessage: string,
+): Promise<string> {
+  const text = await response.text();
+  if (!text) {
+    return fallbackMessage;
+  }
+
+  try {
+    const parsed = JSON.parse(text) as { readonly error?: string };
+    if (typeof parsed.error === "string" && parsed.error.trim().length > 0) {
+      return parsed.error;
+    }
+  } catch {
+    // Fall back to the raw text below.
+  }
+
+  return text;
+}
+
+async function fetchLoopbackSshJson<T>(input: {
+  readonly httpBaseUrl: unknown;
+  readonly pathname: string;
+  readonly method?: "GET" | "POST";
+  readonly bearerToken?: unknown;
+  readonly body?: unknown;
+}): Promise<T> {
+  const requestUrl = resolveLoopbackSshHttpUrl(input.httpBaseUrl, input.pathname).toString();
+  const bearerToken =
+    typeof input.bearerToken === "string" && input.bearerToken.trim().length > 0
+      ? input.bearerToken
+      : null;
+
+  let response: Response;
+  try {
+    response = await fetch(requestUrl, {
+      method: input.method ?? "GET",
+      headers: {
+        ...(input.body !== undefined ? { "content-type": "application/json" } : {}),
+        ...(bearerToken ? { authorization: `Bearer ${bearerToken}` } : {}),
+      },
+      ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
+    });
+  } catch (error) {
+    throw new Error(
+      `Failed to reach SSH forwarded endpoint ${requestUrl} (${error instanceof Error ? error.message : String(error)}).`,
+      { cause: error },
+    );
+  }
+
+  if (!response.ok) {
+    throw new Error(
+      await readRemoteFetchErrorMessage(
+        response,
+        `SSH forwarded request failed (${response.status}).`,
+      ),
+    );
+  }
+
+  return (await response.json()) as T;
+}
+
 async function waitForBackendHttpReady(
   baseUrl: string,
   options?: Parameters<typeof waitForHttpReady>[1],
@@ -661,6 +807,56 @@ let updateInstallInFlight = false;
 let updaterConfigured = false;
 let updateState: DesktopUpdateState = initialUpdateState();
 
+function rejectPendingSshPasswordPrompts(message: string): void {
+  for (const [requestId, pending] of pendingSshPasswordPrompts) {
+    clearTimeout(pending.timeout);
+    pendingSshPasswordPrompts.delete(requestId);
+    pending.reject(new Error(message));
+  }
+}
+
+async function requestSshPasswordFromRenderer(input: {
+  readonly destination: string;
+  readonly username: string | null;
+  readonly prompt: string;
+}): Promise<string | null> {
+  const window = mainWindow;
+  if (!window || window.isDestroyed()) {
+    throw new Error("T3 Code window is not available for SSH authentication.");
+  }
+
+  const request: DesktopSshPasswordPromptRequest = {
+    requestId: Crypto.randomUUID(),
+    destination: input.destination,
+    username: input.username,
+    prompt: input.prompt,
+  };
+
+  return await new Promise<string | null>((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      pendingSshPasswordPrompts.delete(request.requestId);
+      reject(new Error(`SSH authentication timed out for ${input.destination}.`));
+    }, SSH_PASSWORD_PROMPT_TIMEOUT_MS);
+    timeout.unref();
+
+    pendingSshPasswordPrompts.set(request.requestId, {
+      resolve,
+      reject,
+      timeout,
+    });
+
+    window.webContents.send(SSH_PASSWORD_PROMPT_CHANNEL, request);
+    if (window.isMinimized()) {
+      window.restore();
+    }
+    window.focus();
+  });
+}
+
+const desktopSshEnvironmentManager = new DesktopSshEnvironmentManager({
+  passwordProvider: requestSshPasswordFromRenderer,
+});
+
 function resolveUpdaterErrorContext(): DesktopUpdateErrorContext {
   if (updateInstallInFlight) return "install";
   if (updateDownloadInFlight) return "download";
@@ -1679,6 +1875,101 @@ function registerIpcHandlers(): void {
     },
   );
 
+  ipcMain.removeHandler(DISCOVER_SSH_HOSTS_CHANNEL);
+  ipcMain.handle(DISCOVER_SSH_HOSTS_CHANNEL, async () =>
+    desktopSshEnvironmentManager.discoverHosts(),
+  );
+
+  ipcMain.removeHandler(ENSURE_SSH_ENVIRONMENT_CHANNEL);
+  ipcMain.handle(
+    ENSURE_SSH_ENVIRONMENT_CHANNEL,
+    async (_event, rawTarget: unknown, rawOptions: unknown) => {
+      const target = getSafeDesktopSshTarget(rawTarget);
+      if (!target) {
+        throw new Error("Invalid desktop SSH target.");
+      }
+
+      const issuePairingToken =
+        typeof rawOptions === "object" &&
+        rawOptions !== null &&
+        "issuePairingToken" in rawOptions &&
+        (rawOptions as { issuePairingToken?: unknown }).issuePairingToken === true;
+
+      return await desktopSshEnvironmentManager.ensureEnvironment(target, {
+        issuePairingToken,
+      });
+    },
+  );
+
+  ipcMain.removeHandler(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL);
+  ipcMain.handle(
+    FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL,
+    async (_event, rawHttpBaseUrl: unknown) =>
+      fetchLoopbackSshJson<ExecutionEnvironmentDescriptor>({
+        httpBaseUrl: rawHttpBaseUrl,
+        pathname: "/.well-known/t3/environment",
+      }),
+  );
+
+  ipcMain.removeHandler(BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL);
+  ipcMain.handle(
+    BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL,
+    async (_event, rawHttpBaseUrl: unknown, rawCredential: unknown) =>
+      fetchLoopbackSshJson<AuthBearerBootstrapResult>({
+        httpBaseUrl: rawHttpBaseUrl,
+        pathname: "/api/auth/bootstrap/bearer",
+        method: "POST",
+        body: {
+          credential: rawCredential,
+        },
+      }),
+  );
+
+  ipcMain.removeHandler(FETCH_SSH_SESSION_STATE_CHANNEL);
+  ipcMain.handle(
+    FETCH_SSH_SESSION_STATE_CHANNEL,
+    async (_event, rawHttpBaseUrl: unknown, rawBearerToken: unknown) =>
+      fetchLoopbackSshJson<AuthSessionState>({
+        httpBaseUrl: rawHttpBaseUrl,
+        pathname: "/api/auth/session",
+        bearerToken: rawBearerToken,
+      }),
+  );
+
+  ipcMain.removeHandler(ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL);
+  ipcMain.handle(
+    ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL,
+    async (_event, rawHttpBaseUrl: unknown, rawBearerToken: unknown) =>
+      fetchLoopbackSshJson<AuthWebSocketTokenResult>({
+        httpBaseUrl: rawHttpBaseUrl,
+        pathname: "/api/auth/ws-token",
+        method: "POST",
+        bearerToken: rawBearerToken,
+      }),
+  );
+
+  ipcMain.removeHandler(RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL);
+  ipcMain.handle(
+    RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL,
+    async (_event, rawRequestId: unknown, rawPassword: unknown) => {
+      if (typeof rawRequestId !== "string" || rawRequestId.trim().length === 0) {
+        throw new Error("Invalid SSH password prompt id.");
+      }
+      if (rawPassword !== null && typeof rawPassword !== "string") {
+        throw new Error("Invalid SSH password prompt response.");
+      }
+
+      const pending = pendingSshPasswordPrompts.get(rawRequestId);
+      if (!pending) {
+        throw new Error("SSH password prompt is no longer pending.");
+      }
+
+      clearTimeout(pending.timeout);
+      pendingSshPasswordPrompts.delete(rawRequestId);
+      pending.resolve(rawPassword);
+    },
+  );
+
   ipcMain.removeHandler(GET_SERVER_EXPOSURE_STATE_CHANNEL);
   ipcMain.handle(GET_SERVER_EXPOSURE_STATE_CHANNEL, async () => getDesktopServerExposureState());
 
@@ -2054,6 +2345,9 @@ function createWindow(): BrowserWindow {
   }
 
   window.on("closed", () => {
+    rejectPendingSshPasswordPrompts(
+      "SSH authentication was cancelled because the app window closed.",
+    );
     if (mainWindow === window) {
       mainWindow = null;
     }
@@ -2145,6 +2439,7 @@ app.on("before-quit", () => {
   clearUpdatePollTimer();
   cancelBackendReadinessWait();
   stopBackend();
+  void desktopSshEnvironmentManager.dispose().catch(() => undefined);
   restoreStdIoCapture?.();
 });
 
@@ -2194,6 +2489,7 @@ if (process.platform !== "win32") {
     clearUpdatePollTimer();
     cancelBackendReadinessWait();
     stopBackend();
+    void desktopSshEnvironmentManager.dispose().catch(() => undefined);
     restoreStdIoCapture?.();
     app.quit();
   });
@@ -2204,6 +2500,7 @@ if (process.platform !== "win32") {
     writeDesktopLogHeader("SIGTERM received");
     clearUpdatePollTimer();
     stopBackend();
+    void desktopSshEnvironmentManager.dispose().catch(() => undefined);
     restoreStdIoCapture?.();
     app.quit();
   });
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index e918e782ab9..fdfaf20813f 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -22,6 +22,14 @@ const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-re
 const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:get-saved-environment-secret";
 const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secret";
 const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
+const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
+const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
+const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
+const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
+const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
+const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
+const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
+const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
 const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
@@ -52,6 +60,30 @@ contextBridge.exposeInMainWorld("desktopBridge", {
     ipcRenderer.invoke(SET_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId, secret),
   removeSavedEnvironmentSecret: (environmentId) =>
     ipcRenderer.invoke(REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId),
+  discoverSshHosts: () => ipcRenderer.invoke(DISCOVER_SSH_HOSTS_CHANNEL),
+  ensureSshEnvironment: (target, options) =>
+    ipcRenderer.invoke(ENSURE_SSH_ENVIRONMENT_CHANNEL, target, options),
+  fetchSshEnvironmentDescriptor: (httpBaseUrl) =>
+    ipcRenderer.invoke(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, httpBaseUrl),
+  bootstrapSshBearerSession: (httpBaseUrl, credential) =>
+    ipcRenderer.invoke(BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL, httpBaseUrl, credential),
+  fetchSshSessionState: (httpBaseUrl, bearerToken) =>
+    ipcRenderer.invoke(FETCH_SSH_SESSION_STATE_CHANNEL, httpBaseUrl, bearerToken),
+  issueSshWebSocketToken: (httpBaseUrl, bearerToken) =>
+    ipcRenderer.invoke(ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL, httpBaseUrl, bearerToken),
+  onSshPasswordPrompt: (listener) => {
+    const wrappedListener = (_event: Electron.IpcRendererEvent, request: unknown) => {
+      if (typeof request !== "object" || request === null) return;
+      listener(request as Parameters<typeof listener>[0]);
+    };
+
+    ipcRenderer.on(SSH_PASSWORD_PROMPT_CHANNEL, wrappedListener);
+    return () => {
+      ipcRenderer.removeListener(SSH_PASSWORD_PROMPT_CHANNEL, wrappedListener);
+    };
+  },
+  resolveSshPasswordPrompt: (requestId, password) =>
+    ipcRenderer.invoke(RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL, requestId, password),
   getServerExposureState: () => ipcRenderer.invoke(GET_SERVER_EXPOSURE_STATE_CHANNEL),
   setServerExposureMode: (mode) => ipcRenderer.invoke(SET_SERVER_EXPOSURE_MODE_CHANNEL, mode),
   getAdvertisedEndpoints: () => ipcRenderer.invoke(GET_ADVERTISED_ENDPOINTS_CHANNEL),
diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
new file mode 100644
index 00000000000..fa5bca6a0db
--- /dev/null
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -0,0 +1,196 @@
+import * as FS from "node:fs";
+import * as OS from "node:os";
+import * as Path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { __test, discoverDesktopSshHosts } from "./sshEnvironment";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of tempDirectories.splice(0)) {
+    FS.rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function makeTempHomeDir(): string {
+  const directory = FS.mkdtempSync(Path.join(OS.tmpdir(), "t3-ssh-env-test-"));
+  tempDirectories.push(directory);
+  return directory;
+}
+
+describe("sshEnvironment", () => {
+  it("discovers ssh config hosts across included files", async () => {
+    const homeDir = makeTempHomeDir();
+    const sshDir = Path.join(homeDir, ".ssh");
+    FS.mkdirSync(Path.join(sshDir, "config.d"), { recursive: true });
+    FS.writeFileSync(
+      Path.join(sshDir, "config"),
+      ["Host devbox", "  HostName devbox.example.com", "Include config.d/*.conf", ""].join("\n"),
+      "utf8",
+    );
+    FS.writeFileSync(
+      Path.join(sshDir, "config.d", "team.conf"),
+      [
+        "Host staging",
+        "  HostName staging.example.com",
+        "Host *",
+        "  ServerAliveInterval 30",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+    FS.writeFileSync(
+      Path.join(sshDir, "known_hosts"),
+      [
+        "known.example.com ssh-ed25519 AAAA",
+        "|1|hashed|entry ssh-ed25519 AAAA",
+        "[bastion.example.com]:2222 ssh-ed25519 AAAA",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+
+    await expect(discoverDesktopSshHosts({ homeDir })).resolves.toEqual([
+      {
+        alias: "bastion.example.com",
+        hostname: "bastion.example.com",
+        username: null,
+        port: null,
+        source: "known-hosts",
+      },
+      {
+        alias: "devbox",
+        hostname: "devbox",
+        username: null,
+        port: null,
+        source: "ssh-config",
+      },
+      {
+        alias: "known.example.com",
+        hostname: "known.example.com",
+        username: null,
+        port: null,
+        source: "known-hosts",
+      },
+      {
+        alias: "staging",
+        hostname: "staging",
+        username: null,
+        port: null,
+        source: "ssh-config",
+      },
+    ]);
+  });
+
+  it("parses known_hosts entries without returning hashed hosts", () => {
+    expect(
+      __test.parseKnownHostsHostnames(
+        [
+          "github.com ssh-ed25519 AAAA",
+          "gitlab.com,gitlab-alias ssh-ed25519 BBBB",
+          "|1|hashed|entry ssh-ed25519 CCCC",
+          "@cert-authority *.example.com ssh-ed25519 DDDD",
+          "[ssh.example.com]:2200 ssh-ed25519 EEEE",
+          "",
+        ].join("\n"),
+      ),
+    ).toEqual(["github.com", "gitlab-alias", "gitlab.com", "ssh.example.com"]);
+  });
+
+  it("parses resolved ssh config output into a target", () => {
+    expect(
+      __test.parseSshResolveOutput(
+        "devbox",
+        ["hostname devbox.example.com", "user julius", "port 2222", ""].join("\n"),
+      ),
+    ).toEqual({
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    });
+  });
+
+  it("builds interactive ssh args without forcing batch mode", () => {
+    expect(
+      __test.baseSshArgs(
+        {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 2222,
+        },
+        { batchMode: "no" },
+      ),
+    ).toEqual(["-o", "BatchMode=no", "-o", "ConnectTimeout=10", "-p", "2222"]);
+  });
+
+  it("creates askpass env for desktop ssh prompts", () => {
+    const askpassDirectory = Path.join(makeTempHomeDir(), "askpass");
+    const env = __test.buildSshChildEnvironment({
+      authSecret: "super-secret",
+      interactiveAuth: true,
+      askpassDirectory,
+      platform: "linux",
+      baseEnv: {},
+    });
+
+    expect(env.SSH_ASKPASS).toBe(Path.join(askpassDirectory, "ssh-askpass.sh"));
+    expect(env.SSH_ASKPASS_REQUIRE).toBe("force");
+    expect(env.T3_SSH_AUTH_SECRET).toBe("super-secret");
+    expect(env.DISPLAY).toBe("t3code");
+    expect(FS.existsSync(Path.join(askpassDirectory, "ssh-askpass.sh"))).toBe(true);
+    expect(FS.readFileSync(Path.join(askpassDirectory, "ssh-askpass.sh"), "utf8")).toContain(
+      'printf "%s\\n" "$T3_SSH_AUTH_SECRET"',
+    );
+  });
+
+  it("builds a windows askpass launcher pair", () => {
+    const descriptor = __test.buildSshAskpassHelperDescriptor({
+      directory: "C:\\temp\\t3code-ssh-askpass",
+      platform: "win32",
+    });
+
+    expect(descriptor.launcherPath).toBe("C:\\temp\\t3code-ssh-askpass\\ssh-askpass.cmd");
+    expect(descriptor.files.map((file) => Path.win32.basename(file.path))).toEqual([
+      "ssh-askpass.cmd",
+      "ssh-askpass.ps1",
+    ]);
+  });
+
+  it("builds a remote t3 runner with npx and npm fallbacks", () => {
+    const script = __test.buildRemoteT3RunnerScript();
+
+    expect(script).toContain('exec t3 "$@"');
+    expect(script).toContain('exec npx --yes t3 "$@"');
+    expect(script).toContain('exec npm exec --yes t3 -- "$@"');
+    expect(script).toContain("could not find npx or npm on PATH");
+  });
+
+  it("uses the remote t3 runner for launch and pairing scripts", () => {
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+
+    expect(__test.buildRemoteLaunchScript()).toContain('"$RUNNER_FILE" serve --host 127.0.0.1');
+    expect(__test.buildRemotePairingScript(target)).toContain(
+      '"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json',
+    );
+  });
+
+  it("detects ssh auth failures from common permission denied messages", () => {
+    expect(
+      __test.isSshAuthFailure(
+        new Error(
+          "julius@100.65.180.100: Permission denied (publickey,password,keyboard-interactive).",
+        ),
+      ),
+    ).toBe(true);
+    expect(__test.isSshAuthFailure(new Error("Connection timed out"))).toBe(false);
+  });
+});
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
new file mode 100644
index 00000000000..e197645fd99
--- /dev/null
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -0,0 +1,1013 @@
+import * as ChildProcess from "node:child_process";
+import * as Crypto from "node:crypto";
+import * as FS from "node:fs";
+import * as OS from "node:os";
+import * as Path from "node:path";
+import * as Net from "node:net";
+
+import type {
+  DesktopDiscoveredSshHost,
+  DesktopSshEnvironmentBootstrap,
+  DesktopSshEnvironmentTarget,
+} from "@t3tools/contracts";
+
+import { waitForHttpReady } from "./backendReadiness";
+
+const DEFAULT_REMOTE_PORT = 3773;
+const REMOTE_PORT_SCAN_WINDOW = 200;
+const SSH_ASKPASS_DIR_NAME = "t3code-ssh-askpass";
+const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
+const SSH_READY_TIMEOUT_MS = 20_000;
+
+interface SshTunnelEntry {
+  readonly key: string;
+  readonly target: DesktopSshEnvironmentTarget;
+  readonly remotePort: number;
+  readonly localPort: number;
+  readonly httpBaseUrl: string;
+  readonly wsBaseUrl: string;
+  readonly process: ChildProcess.ChildProcess;
+}
+
+interface SshCommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+interface SshAskpassFile {
+  readonly path: string;
+  readonly contents: string;
+  readonly mode?: number;
+}
+
+interface SshAskpassHelperDescriptor {
+  readonly launcherPath: string;
+  readonly files: ReadonlyArray<SshAskpassFile>;
+}
+
+interface SshAuthOptions {
+  readonly authSecret?: string | null;
+  readonly batchMode?: "yes" | "no";
+  readonly interactiveAuth?: boolean;
+}
+
+interface DesktopSshPasswordRequest {
+  readonly destination: string;
+  readonly username: string | null;
+  readonly prompt: string;
+  readonly attempt: number;
+}
+
+interface DesktopSshEnvironmentManagerOptions {
+  readonly passwordProvider?: (request: DesktopSshPasswordRequest) => Promise<string | null>;
+}
+
+const NO_HOSTS = [] as const;
+
+function stripInlineComment(line: string): string {
+  const hashIndex = line.indexOf("#");
+  return (hashIndex >= 0 ? line.slice(0, hashIndex) : line).trim();
+}
+
+function splitDirectiveArgs(value: string): ReadonlyArray<string> {
+  return value
+    .trim()
+    .split(/\s+/u)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function hasSshPattern(value: string): boolean {
+  return value.includes("*") || value.includes("?") || value.startsWith("!");
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function globToRegExp(pattern: string): RegExp {
+  return new RegExp(
+    `^${escapeRegex(pattern).replace(/\\\*/gu, ".*").replace(/\\\?/gu, ".")}$`,
+    "u",
+  );
+}
+
+function expandGlob(pattern: string): ReadonlyArray<string> {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return FS.existsSync(pattern) ? [pattern] : NO_HOSTS;
+  }
+
+  const directory = Path.dirname(pattern);
+  const basePattern = Path.basename(pattern);
+  if (!FS.existsSync(directory)) {
+    return NO_HOSTS;
+  }
+
+  const matcher = globToRegExp(basePattern);
+  return FS.readdirSync(directory)
+    .filter((entry) => matcher.test(entry))
+    .map((entry) => Path.join(directory, entry))
+    .filter((entry) => FS.existsSync(entry))
+    .toSorted((left, right) => left.localeCompare(right));
+}
+
+function collectSshConfigAliasesFromFile(
+  filePath: string,
+  visited = new Set<string>(),
+): ReadonlyArray<string> {
+  const resolvedPath = Path.resolve(filePath);
+  if (visited.has(resolvedPath) || !FS.existsSync(resolvedPath)) {
+    return NO_HOSTS;
+  }
+  visited.add(resolvedPath);
+
+  const aliases = new Set<string>();
+  const directory = Path.dirname(resolvedPath);
+  const raw = FS.readFileSync(resolvedPath, "utf8");
+
+  for (const line of raw.split(/\r?\n/u)) {
+    const stripped = stripInlineComment(line);
+    if (stripped.length === 0) {
+      continue;
+    }
+
+    const [directive = "", ...rawArgs] = splitDirectiveArgs(stripped);
+    const normalizedDirective = directive.toLowerCase();
+    if (normalizedDirective === "include") {
+      for (const includePattern of rawArgs) {
+        const resolvedPattern = Path.isAbsolute(includePattern)
+          ? includePattern
+          : Path.resolve(directory, includePattern);
+        for (const includedPath of expandGlob(resolvedPattern)) {
+          for (const alias of collectSshConfigAliasesFromFile(includedPath, visited)) {
+            aliases.add(alias);
+          }
+        }
+      }
+      continue;
+    }
+
+    if (normalizedDirective !== "host") {
+      continue;
+    }
+
+    for (const alias of rawArgs) {
+      if (alias.length === 0 || hasSshPattern(alias)) {
+        continue;
+      }
+      aliases.add(alias);
+    }
+  }
+
+  return [...aliases].toSorted((left, right) => left.localeCompare(right));
+}
+
+function parseKnownHostsHostnames(raw: string): ReadonlyArray<string> {
+  const hostnames = new Set<string>();
+
+  for (const line of raw.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const withoutMarker = trimmed.startsWith("@")
+      ? trimmed.split(/\s+/u).slice(1).join(" ")
+      : trimmed;
+    const [hostField = ""] = withoutMarker.split(/\s+/u);
+    if (hostField.length === 0 || hostField.startsWith("|")) {
+      continue;
+    }
+
+    for (const rawHost of hostField.split(",")) {
+      const host =
+        /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost)?.[1] ?? rawHost.replace(/:.*$/u, "").trim();
+      if (host.length === 0 || hasSshPattern(host)) {
+        continue;
+      }
+      hostnames.add(host);
+    }
+  }
+
+  return [...hostnames].toSorted((left, right) => left.localeCompare(right));
+}
+
+function readKnownHostsHostnames(filePath: string): ReadonlyArray<string> {
+  if (!FS.existsSync(filePath)) {
+    return NO_HOSTS;
+  }
+
+  return parseKnownHostsHostnames(FS.readFileSync(filePath, "utf8"));
+}
+
+function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
+  const values = new Map<string, string>();
+  for (const line of stdout.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    const [key, ...rest] = trimmed.split(/\s+/u);
+    if (!key || rest.length === 0 || values.has(key)) {
+      continue;
+    }
+    values.set(key, rest.join(" ").trim());
+  }
+
+  const hostname = values.get("hostname")?.trim() || alias;
+  const username = values.get("user")?.trim() || null;
+  const rawPort = values.get("port")?.trim() ?? "";
+  const parsedPort = Number.parseInt(rawPort, 10);
+
+  return {
+    alias,
+    hostname,
+    username,
+    port: Number.isInteger(parsedPort) ? parsedPort : null,
+  };
+}
+
+async function findAvailableLocalPort(): Promise<number> {
+  return await new Promise<number>((resolve, reject) => {
+    const server = Net.createServer();
+    server.unref();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close(() => reject(new Error("Unable to allocate a local tunnel port.")));
+        return;
+      }
+      const { port } = address;
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(port);
+      });
+    });
+  });
+}
+
+function targetConnectionKey(target: DesktopSshEnvironmentTarget): string {
+  return `${target.alias}\u0000${target.hostname}\u0000${target.username ?? ""}\u0000${target.port ?? ""}`;
+}
+
+function remoteStateKey(target: DesktopSshEnvironmentTarget): string {
+  return Crypto.createHash("sha256").update(targetConnectionKey(target)).digest("hex").slice(0, 16);
+}
+
+function buildSshHostSpec(target: DesktopSshEnvironmentTarget): string {
+  const destination = target.alias.trim() || target.hostname.trim();
+  if (destination.length === 0) {
+    throw new Error("SSH target is missing its alias/hostname.");
+  }
+  return target.username ? `${target.username}@${destination}` : destination;
+}
+
+function getDefaultSshAskpassDirectory(): string {
+  return Path.join(OS.tmpdir(), SSH_ASKPASS_DIR_NAME);
+}
+
+function buildPosixSshAskpassScript(): string {
+  return [
+    "#!/bin/sh",
+    "set -eu",
+    'PROMPT="${1:-SSH authentication}"',
+    'if [ "${T3_SSH_AUTH_SECRET+x}" = "x" ]; then',
+    '  printf "%s\\n" "$T3_SSH_AUTH_SECRET"',
+    "  exit 0",
+    "fi",
+    "if command -v osascript >/dev/null 2>&1; then",
+    "  T3_SSH_ASKPASS_PROMPT=\"$PROMPT\" /usr/bin/osascript <<'APPLESCRIPT'",
+    'set promptText to system attribute "T3_SSH_ASKPASS_PROMPT"',
+    "try",
+    '  set dialogResult to display dialog promptText default answer "" with hidden answer buttons {"Cancel", "OK"} default button "OK" cancel button "Cancel"',
+    "  text returned of dialogResult",
+    "on error number -128",
+    "  error number -128",
+    "end try",
+    "APPLESCRIPT",
+    "  exit $?",
+    "fi",
+    "if command -v zenity >/dev/null 2>&1; then",
+    '  zenity --password --title="SSH authentication" --text="$PROMPT"',
+    "  exit $?",
+    "fi",
+    "if command -v kdialog >/dev/null 2>&1; then",
+    '  kdialog --title "SSH authentication" --password "$PROMPT"',
+    "  exit $?",
+    "fi",
+    "if command -v ssh-askpass >/dev/null 2>&1; then",
+    '  ssh-askpass "$PROMPT"',
+    "  exit $?",
+    "fi",
+    "printf 'Unable to open an SSH password prompt on this desktop.\\n' >&2",
+    "exit 1",
+    "",
+  ].join("\n");
+}
+
+function buildWindowsSshAskpassScript(): string {
+  return [
+    "if ($env:T3_SSH_AUTH_SECRET -ne $null) {",
+    "  [Console]::Out.WriteLine($env:T3_SSH_AUTH_SECRET)",
+    "  exit 0",
+    "}",
+    "Add-Type -AssemblyName System.Windows.Forms",
+    "[System.Windows.Forms.Application]::EnableVisualStyles()",
+    '$prompt = if ($args.Length -gt 0 -and $args[0]) { $args[0] } else { "SSH authentication" }',
+    "$form = New-Object System.Windows.Forms.Form",
+    '$form.Text = "SSH authentication"',
+    "$form.Width = 420",
+    "$form.Height = 185",
+    '$form.StartPosition = "CenterScreen"',
+    '$form.FormBorderStyle = "FixedDialog"',
+    "$form.MaximizeBox = $false",
+    "$form.MinimizeBox = $false",
+    "$form.TopMost = $true",
+    "$label = New-Object System.Windows.Forms.Label",
+    "$label.Left = 16",
+    "$label.Top = 16",
+    "$label.Width = 372",
+    "$label.Height = 34",
+    "$label.Text = $prompt",
+    "$textbox = New-Object System.Windows.Forms.TextBox",
+    "$textbox.Left = 16",
+    "$textbox.Top = 60",
+    "$textbox.Width = 372",
+    "$textbox.UseSystemPasswordChar = $true",
+    "$okButton = New-Object System.Windows.Forms.Button",
+    '$okButton.Text = "OK"',
+    "$okButton.Left = 232",
+    "$okButton.Top = 100",
+    "$okButton.Width = 75",
+    "$cancelButton = New-Object System.Windows.Forms.Button",
+    '$cancelButton.Text = "Cancel"',
+    "$cancelButton.Left = 313",
+    "$cancelButton.Top = 100",
+    "$cancelButton.Width = 75",
+    "$okButton.DialogResult = [System.Windows.Forms.DialogResult]::OK",
+    "$cancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel",
+    "$form.AcceptButton = $okButton",
+    "$form.CancelButton = $cancelButton",
+    "$form.Controls.Add($label)",
+    "$form.Controls.Add($textbox)",
+    "$form.Controls.Add($okButton)",
+    "$form.Controls.Add($cancelButton)",
+    "$result = $form.ShowDialog()",
+    "if ($result -ne [System.Windows.Forms.DialogResult]::OK) { exit 1 }",
+    "[Console]::Out.WriteLine($textbox.Text)",
+    "",
+  ].join("\r\n");
+}
+
+function buildSshAskpassHelperDescriptor(input?: {
+  readonly directory?: string;
+  readonly platform?: NodeJS.Platform;
+}): SshAskpassHelperDescriptor {
+  const platform = input?.platform ?? process.platform;
+  const directory = input?.directory ?? getDefaultSshAskpassDirectory();
+  const pathModule = platform === "win32" ? Path.win32 : Path.posix;
+
+  if (platform === "win32") {
+    const powershellPath = pathModule.join(directory, "ssh-askpass.ps1");
+    return {
+      launcherPath: pathModule.join(directory, "ssh-askpass.cmd"),
+      files: [
+        {
+          path: pathModule.join(directory, "ssh-askpass.cmd"),
+          contents: [
+            "@echo off",
+            'powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0ssh-askpass.ps1" %*',
+            "",
+          ].join("\r\n"),
+        },
+        {
+          path: powershellPath,
+          contents: buildWindowsSshAskpassScript(),
+        },
+      ],
+    };
+  }
+
+  return {
+    launcherPath: pathModule.join(directory, "ssh-askpass.sh"),
+    files: [
+      {
+        path: pathModule.join(directory, "ssh-askpass.sh"),
+        contents: buildPosixSshAskpassScript(),
+        mode: 0o700,
+      },
+    ],
+  };
+}
+
+function ensureSshAskpassHelpers(input?: {
+  readonly directory?: string;
+  readonly platform?: NodeJS.Platform;
+}): string {
+  const descriptor = buildSshAskpassHelperDescriptor(input);
+  const platform = input?.platform ?? process.platform;
+  FS.mkdirSync(Path.dirname(descriptor.launcherPath), { recursive: true });
+
+  for (const file of descriptor.files) {
+    const current =
+      FS.existsSync(file.path) && FS.statSync(file.path).isFile()
+        ? FS.readFileSync(file.path, "utf8")
+        : null;
+    if (current !== file.contents) {
+      FS.writeFileSync(file.path, file.contents, "utf8");
+    }
+    if (file.mode !== undefined && platform !== "win32") {
+      FS.chmodSync(file.path, file.mode);
+    }
+  }
+
+  return descriptor.launcherPath;
+}
+
+function buildSshChildEnvironment(input?: {
+  readonly interactiveAuth?: boolean;
+  readonly baseEnv?: NodeJS.ProcessEnv;
+  readonly askpassDirectory?: string;
+  readonly authSecret?: string | null;
+  readonly platform?: NodeJS.Platform;
+}): NodeJS.ProcessEnv {
+  const baseEnv = { ...(input?.baseEnv ?? process.env) };
+  if (!input?.interactiveAuth) {
+    return baseEnv;
+  }
+
+  const platform = input?.platform ?? process.platform;
+  const askpassInput =
+    input?.askpassDirectory === undefined
+      ? { platform }
+      : {
+          directory: input.askpassDirectory,
+          platform,
+        };
+  return {
+    ...baseEnv,
+    SSH_ASKPASS: ensureSshAskpassHelpers(askpassInput),
+    SSH_ASKPASS_REQUIRE: "force",
+    ...(input?.authSecret === undefined ? {} : { T3_SSH_AUTH_SECRET: input.authSecret ?? "" }),
+    ...(platform === "win32" || baseEnv.DISPLAY ? {} : { DISPLAY: "t3code" }),
+  };
+}
+
+function baseSshArgs(
+  target: DesktopSshEnvironmentTarget,
+  input?: { readonly batchMode?: "yes" | "no" },
+): string[] {
+  return [
+    "-o",
+    `BatchMode=${input?.batchMode ?? "no"}`,
+    "-o",
+    "ConnectTimeout=10",
+    ...(target.port !== null ? ["-p", String(target.port)] : []),
+  ];
+}
+
+function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
+  const cleaned = stderr.trim();
+  return cleaned.length > 0 ? cleaned : fallbackMessage;
+}
+
+function isSshAuthFailure(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /permission denied|authentication failed|keyboard-interactive/u.test(
+    message.toLowerCase(),
+  );
+}
+
+async function runSshCommand(
+  target: DesktopSshEnvironmentTarget,
+  input?: {
+    readonly preHostArgs?: ReadonlyArray<string>;
+    readonly remoteCommandArgs?: ReadonlyArray<string>;
+    readonly stdin?: string;
+    readonly signal?: AbortSignal;
+    readonly authSecret?: string | null;
+    readonly batchMode?: "yes" | "no";
+    readonly interactiveAuth?: boolean;
+  },
+): Promise<SshCommandResult> {
+  const hostSpec = buildSshHostSpec(target);
+
+  return await new Promise<SshCommandResult>((resolve, reject) => {
+    const childEnvironment =
+      input?.interactiveAuth === undefined
+        ? buildSshChildEnvironment()
+        : buildSshChildEnvironment({
+            interactiveAuth: input.interactiveAuth,
+            ...(input.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+          });
+    const child = ChildProcess.spawn(
+      "ssh",
+      [
+        ...baseSshArgs(target, {
+          batchMode: input?.batchMode ?? (input?.interactiveAuth ? "no" : "yes"),
+        }),
+        ...(input?.preHostArgs ?? []),
+        hostSpec,
+        ...(input?.remoteCommandArgs ?? []),
+      ],
+      {
+        env: childEnvironment,
+        stdio: "pipe",
+      },
+    );
+
+    let stdout = "";
+    let stderr = "";
+
+    const onAbort = () => {
+      child.kill("SIGTERM");
+      reject(new Error(`SSH command aborted for ${hostSpec}.`));
+    };
+
+    input?.signal?.addEventListener("abort", onAbort, { once: true });
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk: string) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk: string) => {
+      stderr += chunk;
+    });
+    child.once("error", (error) => {
+      input?.signal?.removeEventListener("abort", onAbort);
+      reject(error);
+    });
+    child.once("close", (code) => {
+      input?.signal?.removeEventListener("abort", onAbort);
+      if (code === 0) {
+        resolve({ stdout, stderr });
+        return;
+      }
+      reject(
+        new Error(
+          normalizeSshErrorMessage(stderr, `SSH command failed for ${hostSpec} (exit ${code}).`),
+        ),
+      );
+    });
+
+    if (input?.stdin !== undefined) {
+      child.stdin?.end(input.stdin);
+      return;
+    }
+    child.stdin?.end();
+  });
+}
+
+async function resolveDesktopSshTarget(alias: string): Promise<DesktopSshEnvironmentTarget> {
+  const trimmedAlias = alias.trim();
+  if (trimmedAlias.length === 0) {
+    throw new Error("SSH host alias is required.");
+  }
+
+  try {
+    const result = await runSshCommand(
+      {
+        alias: trimmedAlias,
+        hostname: trimmedAlias,
+        username: null,
+        port: null,
+      },
+      { preHostArgs: ["-G"] },
+    );
+    return parseSshResolveOutput(trimmedAlias, result.stdout);
+  } catch {
+    return {
+      alias: trimmedAlias,
+      hostname: trimmedAlias,
+      username: null,
+      port: null,
+    };
+  }
+}
+
+function buildRemoteLaunchScript(): string {
+  const runnerScript = buildRemoteT3RunnerScript();
+  return `
+set -eu
+STATE_KEY="$1"
+STATE_DIR="$HOME/.t3/ssh-launch/$STATE_KEY"
+SERVER_HOME="$STATE_DIR/server-home"
+PORT_FILE="$STATE_DIR/port"
+PID_FILE="$STATE_DIR/pid"
+LOG_FILE="$STATE_DIR/server.log"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+mkdir -p "$STATE_DIR" "$SERVER_HOME"
+cat >"$RUNNER_FILE" <<'SH'
+${runnerScript}
+SH
+chmod 700 "$RUNNER_FILE"
+pick_port() {
+  node - "$PORT_FILE" <<'NODE'
+const fs = require("node:fs");
+const net = require("node:net");
+const filePath = process.argv[2];
+const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8").trim() : "";
+const preferred = Number.parseInt(raw, 10);
+const start = Number.isInteger(preferred) ? preferred : ${DEFAULT_REMOTE_PORT};
+const end = start + ${REMOTE_PORT_SCAN_WINDOW};
+
+function tryPort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => {
+      server.close((error) => resolve(error ? false : port));
+    });
+  });
+}
+
+(async () => {
+  for (let port = start; port < end; port += 1) {
+    const available = await tryPort(port);
+    if (available) {
+      process.stdout.write(String(port));
+      return;
+    }
+  }
+  process.exit(1);
+})().catch(() => process.exit(1));
+NODE
+}
+REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
+if [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+  :
+else
+  REMOTE_PORT="$(pick_port)"
+  nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
+  REMOTE_PID="$!"
+  printf '%s\\n' "$REMOTE_PID" >"$PID_FILE"
+  printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+fi
+printf '{"remotePort":%s}\\n' "$REMOTE_PORT"
+`.trimStart();
+}
+
+function buildRemoteT3RunnerScript(): string {
+  return [
+    "#!/bin/sh",
+    "set -eu",
+    "if command -v t3 >/dev/null 2>&1; then",
+    '  exec t3 "$@"',
+    "fi",
+    "if command -v npx >/dev/null 2>&1; then",
+    '  exec npx --yes t3 "$@"',
+    "fi",
+    "if command -v npm >/dev/null 2>&1; then",
+    '  exec npm exec --yes t3 -- "$@"',
+    "fi",
+    "printf 'Remote host is missing the t3 CLI and could not find npx or npm on PATH.\\n' >&2",
+    "exit 1",
+  ].join("\n");
+}
+
+function buildRemotePairingScript(target: DesktopSshEnvironmentTarget): string {
+  const runnerScript = buildRemoteT3RunnerScript();
+  return `
+set -eu
+STATE_DIR="$HOME/.t3/ssh-launch/${remoteStateKey(target)}"
+SERVER_HOME="$STATE_DIR/server-home"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+mkdir -p "$STATE_DIR" "$SERVER_HOME"
+cat >"$RUNNER_FILE" <<'SH'
+${runnerScript}
+SH
+chmod 700 "$RUNNER_FILE"
+"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json
+`.trimStart();
+}
+
+async function launchOrReuseRemoteServer(
+  target: DesktopSshEnvironmentTarget,
+  input?: SshAuthOptions,
+): Promise<number> {
+  const result = await runSshCommand(target, {
+    remoteCommandArgs: ["sh", "-s", "--", remoteStateKey(target)],
+    stdin: buildRemoteLaunchScript(),
+    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+  });
+  const line = result.stdout
+    .trim()
+    .split(/\r?\n/u)
+    .map((entry) => entry.trim())
+    .findLast((entry) => entry.length > 0);
+  if (!line) {
+    throw new Error("SSH launch did not return a remote port.");
+  }
+
+  const parsed = JSON.parse(line) as { remotePort?: unknown };
+  if (typeof parsed.remotePort !== "number" || !Number.isInteger(parsed.remotePort)) {
+    throw new Error("SSH launch returned an invalid remote port.");
+  }
+  return parsed.remotePort;
+}
+
+async function issueRemotePairingToken(
+  target: DesktopSshEnvironmentTarget,
+  input?: SshAuthOptions,
+): Promise<string> {
+  const result = await runSshCommand(target, {
+    remoteCommandArgs: ["sh", "-s"],
+    stdin: buildRemotePairingScript(target),
+    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+  });
+  const parsed = JSON.parse(result.stdout) as { credential?: unknown };
+  if (typeof parsed.credential !== "string" || parsed.credential.trim().length === 0) {
+    throw new Error("SSH pairing command returned an invalid credential.");
+  }
+  return parsed.credential;
+}
+
+async function stopTunnel(entry: SshTunnelEntry): Promise<void> {
+  const child = entry.process;
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return;
+  }
+
+  await new Promise<void>((resolve) => {
+    let settled = false;
+    let forceKillTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const settle = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      child.off("exit", onExit);
+      if (forceKillTimer) {
+        clearTimeout(forceKillTimer);
+      }
+      resolve();
+    };
+
+    const onExit = () => {
+      settle();
+    };
+
+    child.once("exit", onExit);
+    child.kill("SIGTERM");
+    forceKillTimer = setTimeout(() => {
+      if (child.exitCode === null && child.signalCode === null) {
+        child.kill("SIGKILL");
+      }
+    }, TUNNEL_SHUTDOWN_TIMEOUT_MS);
+    forceKillTimer.unref();
+  });
+}
+
+export async function discoverDesktopSshHosts(input?: {
+  readonly homeDir?: string;
+}): Promise<readonly DesktopDiscoveredSshHost[]> {
+  const sshDirectory = Path.join(input?.homeDir ?? OS.homedir(), ".ssh");
+  const configAliases = collectSshConfigAliasesFromFile(Path.join(sshDirectory, "config"));
+  const knownHosts = readKnownHostsHostnames(Path.join(sshDirectory, "known_hosts"));
+  const discovered = new Map<string, DesktopDiscoveredSshHost>();
+
+  for (const alias of configAliases) {
+    discovered.set(alias, {
+      alias,
+      hostname: alias,
+      username: null,
+      port: null,
+      source: "ssh-config",
+    });
+  }
+
+  for (const hostname of knownHosts) {
+    if (discovered.has(hostname)) {
+      continue;
+    }
+    discovered.set(hostname, {
+      alias: hostname,
+      hostname,
+      username: null,
+      port: null,
+      source: "known-hosts",
+    });
+  }
+
+  return [...discovered.values()].toSorted((left, right) => left.alias.localeCompare(right.alias));
+}
+
+export class DesktopSshEnvironmentManager {
+  private readonly tunnels = new Map<string, SshTunnelEntry>();
+  private readonly authSecrets = new Map<string, string>();
+
+  constructor(private readonly options: DesktopSshEnvironmentManagerOptions = {}) {}
+
+  private async promptForPassword(
+    target: DesktopSshEnvironmentTarget,
+    attempt: number,
+  ): Promise<string> {
+    const passwordProvider = this.options.passwordProvider;
+    if (!passwordProvider) {
+      throw new Error(`SSH authentication failed for ${buildSshHostSpec(target)}.`);
+    }
+
+    const password = await passwordProvider({
+      attempt,
+      destination: target.alias.trim() || target.hostname.trim(),
+      username: target.username,
+      prompt: `Enter the SSH password for ${buildSshHostSpec(target)}.`,
+    });
+    if (password === null) {
+      throw new Error(`SSH authentication cancelled for ${buildSshHostSpec(target)}.`);
+    }
+    return password;
+  }
+
+  private async runWithSshAuth<T>(
+    key: string,
+    target: DesktopSshEnvironmentTarget,
+    operation: (authOptions: SshAuthOptions) => Promise<T>,
+  ): Promise<T> {
+    let authSecret = this.authSecrets.get(key) ?? null;
+    let promptCount = 0;
+
+    while (true) {
+      try {
+        return await operation(
+          authSecret === null
+            ? {
+                batchMode: this.options.passwordProvider ? "yes" : "no",
+                interactiveAuth: !this.options.passwordProvider,
+              }
+            : {
+                authSecret,
+                batchMode: "no",
+                interactiveAuth: true,
+              },
+        );
+      } catch (error) {
+        if (!isSshAuthFailure(error)) {
+          throw error;
+        }
+
+        if (!this.options.passwordProvider) {
+          throw error;
+        }
+
+        if (authSecret !== null) {
+          this.authSecrets.delete(key);
+        }
+        if (promptCount >= 2) {
+          throw error;
+        }
+
+        promptCount += 1;
+        authSecret = await this.promptForPassword(target, promptCount);
+        this.authSecrets.set(key, authSecret);
+      }
+    }
+  }
+
+  async discoverHosts(): Promise<readonly DesktopDiscoveredSshHost[]> {
+    return await discoverDesktopSshHosts();
+  }
+
+  async ensureEnvironment(
+    target: DesktopSshEnvironmentTarget,
+    options?: { readonly issuePairingToken?: boolean },
+  ): Promise<DesktopSshEnvironmentBootstrap> {
+    const resolvedTarget = await resolveDesktopSshTarget(target.alias || target.hostname);
+    const key = targetConnectionKey(resolvedTarget);
+    let entry = this.tunnels.get(key) ?? null;
+
+    if (entry !== null) {
+      try {
+        await waitForHttpReady(entry.httpBaseUrl, { timeoutMs: 2_000 });
+      } catch {
+        await stopTunnel(entry).catch(() => undefined);
+        this.tunnels.delete(key);
+        entry = null;
+      }
+    }
+
+    if (entry === null) {
+      const remotePort = await this.runWithSshAuth(key, resolvedTarget, (authOptions) =>
+        launchOrReuseRemoteServer(resolvedTarget, authOptions),
+      );
+      const localPort = await findAvailableLocalPort();
+      const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
+      const wsBaseUrl = `ws://127.0.0.1:${localPort}/`;
+      entry = await this.runWithSshAuth(key, resolvedTarget, async (authOptions) => {
+        const process = ChildProcess.spawn(
+          "ssh",
+          [
+            ...baseSshArgs(resolvedTarget, { batchMode: authOptions.batchMode ?? "no" }),
+            "-o",
+            "ExitOnForwardFailure=yes",
+            "-o",
+            "ServerAliveInterval=15",
+            "-o",
+            "ServerAliveCountMax=3",
+            "-N",
+            "-L",
+            `${localPort}:127.0.0.1:${remotePort}`,
+            buildSshHostSpec(resolvedTarget),
+          ],
+          {
+            env: buildSshChildEnvironment({
+              ...(authOptions.authSecret === undefined
+                ? {}
+                : { authSecret: authOptions.authSecret }),
+              ...(authOptions.interactiveAuth === undefined
+                ? {}
+                : { interactiveAuth: authOptions.interactiveAuth }),
+            }),
+            stdio: "pipe",
+          },
+        );
+        const nextEntry: SshTunnelEntry = {
+          key,
+          target: resolvedTarget,
+          remotePort,
+          localPort,
+          httpBaseUrl,
+          wsBaseUrl,
+          process,
+        };
+        const tunnelReady = new Promise<void>((resolve, reject) => {
+          let stderr = "";
+          process.stderr?.setEncoding("utf8");
+          process.stderr?.on("data", (chunk: string) => {
+            stderr += chunk;
+          });
+          process.once("error", (error) => {
+            this.tunnels.delete(key);
+            reject(error);
+          });
+          process.once("exit", (code) => {
+            this.tunnels.delete(key);
+            reject(
+              new Error(
+                normalizeSshErrorMessage(
+                  stderr,
+                  `SSH tunnel exited unexpectedly for ${resolvedTarget.alias} (exit ${code ?? "unknown"}).`,
+                ),
+              ),
+            );
+          });
+          waitForHttpReady(httpBaseUrl, { timeoutMs: SSH_READY_TIMEOUT_MS })
+            .then(() => resolve())
+            .catch((error) => reject(error));
+        });
+        this.tunnels.set(key, nextEntry);
+        try {
+          await tunnelReady;
+          return nextEntry;
+        } catch (error) {
+          await stopTunnel(nextEntry).catch(() => undefined);
+          this.tunnels.delete(key);
+          throw error;
+        }
+      });
+    }
+
+    const pairingToken = options?.issuePairingToken
+      ? await this.runWithSshAuth(key, entry.target, (authOptions) =>
+          issueRemotePairingToken(entry.target, authOptions),
+        )
+      : null;
+
+    return {
+      target: entry.target,
+      httpBaseUrl: entry.httpBaseUrl,
+      wsBaseUrl: entry.wsBaseUrl,
+      pairingToken,
+    };
+  }
+
+  async dispose(): Promise<void> {
+    const entries = [...this.tunnels.values()];
+    this.tunnels.clear();
+    await Promise.all(entries.map((entry) => stopTunnel(entry).catch(() => undefined)));
+  }
+}
+
+export const __test = {
+  baseSshArgs,
+  buildRemoteLaunchScript,
+  buildRemotePairingScript,
+  buildRemoteT3RunnerScript,
+  buildSshAskpassHelperDescriptor,
+  buildSshChildEnvironment,
+  isSshAuthFailure,
+  collectSshConfigAliasesFromFile,
+  parseKnownHostsHostnames,
+  parseSshResolveOutput,
+};
diff --git a/apps/web/src/clientPersistenceStorage.test.ts b/apps/web/src/clientPersistenceStorage.test.ts
index a74ce18ac30..e02168e09b3 100644
--- a/apps/web/src/clientPersistenceStorage.test.ts
+++ b/apps/web/src/clientPersistenceStorage.test.ts
@@ -10,6 +10,12 @@ const savedRegistryRecord: PersistedSavedEnvironmentRecord = {
   wsBaseUrl: "wss://remote.example.com/",
   createdAt: "2026-04-09T00:00:00.000Z",
   lastConnectedAt: null,
+  desktopSsh: {
+    alias: "devbox",
+    hostname: "devbox.example.com",
+    username: "julius",
+    port: 22,
+  },
 };
 
 function createLocalStorageStub(): Storage {
diff --git a/apps/web/src/clientPersistenceStorage.ts b/apps/web/src/clientPersistenceStorage.ts
index 70f51d5c30a..30c949b37ac 100644
--- a/apps/web/src/clientPersistenceStorage.ts
+++ b/apps/web/src/clientPersistenceStorage.ts
@@ -19,6 +19,14 @@ const BrowserSavedEnvironmentRecordSchema = Schema.Struct({
   wsBaseUrl: Schema.String,
   createdAt: Schema.String,
   lastConnectedAt: Schema.NullOr(Schema.String),
+  desktopSsh: Schema.optionalKey(
+    Schema.Struct({
+      alias: Schema.String,
+      hostname: Schema.String,
+      username: Schema.NullOr(Schema.String),
+      port: Schema.NullOr(Schema.Number),
+    }),
+  ),
   bearerToken: Schema.optionalKey(Schema.String),
 });
 type BrowserSavedEnvironmentRecord = typeof BrowserSavedEnvironmentRecordSchema.Type;
@@ -37,7 +45,7 @@ function hasWindow(): boolean {
 function toPersistedSavedEnvironmentRecord(
   record: PersistedSavedEnvironmentRecord,
 ): PersistedSavedEnvironmentRecord {
-  return {
+  const nextRecord = {
     environmentId: record.environmentId,
     label: record.label,
     httpBaseUrl: record.httpBaseUrl,
@@ -45,6 +53,7 @@ function toPersistedSavedEnvironmentRecord(
     createdAt: record.createdAt,
     lastConnectedAt: record.lastConnectedAt,
   };
+  return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
 }
 
 export function readBrowserClientSettings(): ClientSettings | null {
@@ -135,6 +144,7 @@ export function writeBrowserSavedEnvironmentRegistry(
             wsBaseUrl: record.wsBaseUrl,
             createdAt: record.createdAt,
             lastConnectedAt: record.lastConnectedAt,
+            ...(record.desktopSsh ? { desktopSsh: record.desktopSsh } : {}),
             bearerToken,
           }
         : toPersistedSavedEnvironmentRecord(record);
@@ -166,7 +176,7 @@ export function writeBrowserSavedEnvironmentSecret(
         return record;
       }
       found = true;
-      return {
+      const nextRecord = {
         environmentId: record.environmentId,
         label: record.label,
         httpBaseUrl: record.httpBaseUrl,
@@ -174,7 +184,8 @@ export function writeBrowserSavedEnvironmentSecret(
         createdAt: record.createdAt,
         lastConnectedAt: record.lastConnectedAt,
         bearerToken: secret,
-      } satisfies BrowserSavedEnvironmentRecord;
+      };
+      return record.desktopSsh ? { ...nextRecord, desktopSsh: record.desktopSsh } : nextRecord;
     }),
   });
   return found;
diff --git a/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
new file mode 100644
index 00000000000..4066544c633
--- /dev/null
+++ b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
@@ -0,0 +1,114 @@
+import type { DesktopSshPasswordPromptRequest } from "@t3tools/contracts";
+import { useEffect, useRef, useState } from "react";
+
+import { Button } from "../ui/button";
+import {
+  Dialog,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogPanel,
+  DialogPopup,
+  DialogTitle,
+} from "../ui/dialog";
+import { Input } from "../ui/input";
+
+function describeSshTarget(request: DesktopSshPasswordPromptRequest): string {
+  return request.username ? `${request.username}@${request.destination}` : request.destination;
+}
+
+export function SshPasswordPromptDialog() {
+  const [queue, setQueue] = useState<readonly DesktopSshPasswordPromptRequest[]>([]);
+  const [password, setPassword] = useState("");
+  const currentRequest = queue[0] ?? null;
+  const inputRef = useRef<HTMLInputElement | null>(null);
+
+  useEffect(() => {
+    const bridge = window.desktopBridge;
+    if (!bridge?.onSshPasswordPrompt) {
+      return;
+    }
+
+    return bridge.onSshPasswordPrompt((request) => {
+      setQueue((currentQueue) => [...currentQueue, request]);
+    });
+  }, []);
+
+  useEffect(() => {
+    setPassword("");
+    if (!currentRequest) {
+      return;
+    }
+
+    const frame = window.requestAnimationFrame(() => {
+      inputRef.current?.focus();
+      inputRef.current?.select();
+    });
+    return () => {
+      window.cancelAnimationFrame(frame);
+    };
+  }, [currentRequest]);
+
+  const respond = async (nextPassword: string | null) => {
+    if (!currentRequest) {
+      return;
+    }
+
+    const requestId = currentRequest.requestId;
+    setQueue((currentQueue) => currentQueue.slice(1));
+    setPassword("");
+    try {
+      await window.desktopBridge?.resolveSshPasswordPrompt(requestId, nextPassword);
+    } catch (error) {
+      console.error("Failed to resolve SSH password prompt.", error);
+    }
+  };
+
+  const target = currentRequest ? describeSshTarget(currentRequest) : null;
+
+  return (
+    <Dialog
+      open={currentRequest !== null}
+      onOpenChange={(open) => {
+        if (!open) {
+          void respond(null);
+        }
+      }}
+    >
+      <DialogPopup className="max-w-md" showCloseButton={false}>
+        <DialogHeader>
+          <DialogTitle>SSH Password Required</DialogTitle>
+          <DialogDescription>
+            T3 needs your SSH password to connect to{" "}
+            {target ? <code>{target}</code> : "the remote host"}. The password is passed to the
+            local SSH process for this connection attempt and is not saved by T3 Code.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel className="space-y-3" scrollFade={false}>
+          <div className="space-y-2">
+            <p className="text-sm font-medium text-foreground">{currentRequest?.prompt}</p>
+            <Input
+              ref={inputRef}
+              autoComplete="current-password"
+              name="ssh-password"
+              type="password"
+              value={password}
+              onChange={(event) => setPassword(event.target.value)}
+            />
+          </div>
+          <p className="text-sm text-muted-foreground">
+            Use SSH keys to avoid repeated password prompts on new SSH sessions.
+          </p>
+        </DialogPanel>
+        <DialogFooter>
+          <Button variant="outline" onClick={() => void respond(null)}>
+            Cancel
+          </Button>
+          <Button onClick={() => void respond(password)} type="button">
+            Continue
+          </Button>
+        </DialogFooter>
+      </DialogPopup>
+    </Dialog>
+  );
+}
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 31253781930..061feb4add5 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1,9 +1,11 @@
-import { ChevronDownIcon, PlusIcon, QrCodeIcon } from "lucide-react";
+import { ChevronDownIcon, PlusIcon, QrCodeIcon, RefreshCwIcon } from "lucide-react";
 import { type ReactNode, memo, useCallback, useEffect, useMemo, useState } from "react";
 import {
   type AuthClientSession,
   type AuthPairingLink,
   type AdvertisedEndpoint,
+  type DesktopDiscoveredSshHost,
+  type DesktopSshEnvironmentTarget,
   type DesktopServerExposureState,
   type EnvironmentId,
 } from "@t3tools/contracts";
@@ -30,6 +32,7 @@ import {
   DialogTitle,
   DialogTrigger,
 } from "../ui/dialog";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible";
 import {
   AlertDialog,
   AlertDialogClose,
@@ -67,6 +70,7 @@ import {
   useSavedEnvironmentRegistryStore,
   useSavedEnvironmentRuntimeStore,
   addSavedEnvironment,
+  connectDesktopSshEnvironment,
   getPrimaryEnvironmentConnection,
   reconnectSavedEnvironment,
   removeSavedEnvironment,
@@ -165,6 +169,69 @@ function getSavedBackendStatusTooltip(
     : "Not connected yet.";
 }
 
+function formatDesktopSshTarget(target: NonNullable<SavedEnvironmentRecord["desktopSsh"]>): string {
+  const authority = target.username ? `${target.username}@${target.hostname}` : target.hostname;
+  return target.port ? `${authority}:${target.port}` : authority;
+}
+
+function parseManualDesktopSshTarget(input: {
+  readonly host: string;
+  readonly username: string;
+  readonly port: string;
+}): DesktopSshEnvironmentTarget {
+  const rawHost = input.host.trim();
+  if (rawHost.length === 0) {
+    throw new Error("SSH host or alias is required.");
+  }
+
+  let hostname = rawHost;
+  let username = input.username.trim() || null;
+  let port: number | null = null;
+
+  const atIndex = hostname.lastIndexOf("@");
+  if (atIndex > 0) {
+    const inlineUsername = hostname.slice(0, atIndex).trim();
+    hostname = hostname.slice(atIndex + 1).trim();
+    if (!username && inlineUsername.length > 0) {
+      username = inlineUsername;
+    }
+  }
+
+  const bracketedHostMatch = /^\[([^\]]+)\](?::(\d+))?$/u.exec(hostname);
+  if (bracketedHostMatch) {
+    hostname = bracketedHostMatch[1]!.trim();
+    if (bracketedHostMatch[2]) {
+      port = Number.parseInt(bracketedHostMatch[2], 10);
+    }
+  } else {
+    const colonSegments = hostname.split(":");
+    if (colonSegments.length === 2 && /^\d+$/u.test(colonSegments[1] ?? "")) {
+      hostname = colonSegments[0]!.trim();
+      port = Number.parseInt(colonSegments[1]!, 10);
+    }
+  }
+
+  const rawPort = input.port.trim();
+  if (rawPort.length > 0) {
+    port = Number.parseInt(rawPort, 10);
+  }
+
+  if (hostname.length === 0) {
+    throw new Error("SSH host or alias is required.");
+  }
+
+  if (port !== null && (!Number.isInteger(port) || port <= 0 || port > 65_535)) {
+    throw new Error("SSH port must be between 1 and 65535.");
+  }
+
+  return {
+    alias: hostname,
+    hostname,
+    username,
+    port,
+  };
+}
+
 /** Direct row in the card – same pattern as the Provider / ACP-agent list rows. */
 const ITEM_ROW_CLASSNAME = "border-t border-border/60 px-4 py-4 first:border-t-0 sm:px-5";
 const ENDPOINT_ROW_CLASSNAME = "border-t border-border/60 px-4 py-2.5 first:border-t-0 sm:px-5";
@@ -933,6 +1000,7 @@ function SavedBackendListRow({
   const descriptorLabel = runtime?.descriptor?.label ?? null;
   const statusTooltip = getSavedBackendStatusTooltip(runtime, record, nowMs);
   const metadataBits = [
+    record.desktopSsh ? `SSH ${formatDesktopSshTarget(record.desktopSsh)}` : null,
     roleLabel,
     record.lastConnectedAt
       ? `Last connected ${formatAccessTimestamp(record.lastConnectedAt)}`
@@ -983,6 +1051,59 @@ function SavedBackendListRow({
   );
 }
 
+interface DesktopSshHostRowProps {
+  target: DesktopDiscoveredSshHost;
+  savedRecord: SavedEnvironmentRecord | null;
+  connectingHostAlias: string | null;
+  onConnect: (target: DesktopDiscoveredSshHost) => void;
+}
+
+const DesktopSshHostRow = memo(function DesktopSshHostRow({
+  target,
+  savedRecord,
+  connectingHostAlias,
+  onConnect,
+}: DesktopSshHostRowProps) {
+  const address = formatDesktopSshTarget(target);
+  const secondaryBits = [target.source === "ssh-config" ? "SSH config" : "Known hosts", address];
+  const buttonLabel =
+    connectingHostAlias === target.alias ? "Connecting…" : savedRecord ? "Reconnect" : "Connect";
+
+  return (
+    <div className={ITEM_ROW_CLASSNAME}>
+      <div className={ITEM_ROW_INNER_CLASSNAME}>
+        <div className="min-w-0 flex-1 space-y-1">
+          <div className="flex min-h-5 items-center gap-1.5">
+            <h3 className="text-sm font-medium text-foreground">{target.alias}</h3>
+          </div>
+          <p className="text-xs text-muted-foreground">{secondaryBits.join(" · ")}</p>
+          {savedRecord ? (
+            <p className="text-xs text-muted-foreground">
+              Saved as {savedRecord.label}
+              {savedRecord.lastConnectedAt
+                ? ` · Last connected ${formatAccessTimestamp(savedRecord.lastConnectedAt)}`
+                : ""}
+            </p>
+          ) : null}
+        </div>
+        <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
+          <Button
+            size="xs"
+            variant="outline"
+            disabled={connectingHostAlias === target.alias}
+            onClick={() => onConnect(target)}
+          >
+            {connectingHostAlias === target.alias ? (
+              <RefreshCwIcon className="size-3 animate-spin" />
+            ) : null}
+            {buttonLabel}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+});
+
 export function ConnectionsSettings() {
   const desktopBridge = window.desktopBridge;
   const [currentSessionRole, setCurrentSessionRole] = useState<"owner" | "client" | null>(
@@ -999,6 +1120,26 @@ export function ConnectionsSettings() {
         .map((record) => record.environmentId),
     [savedEnvironmentsById],
   );
+  const savedDesktopSshEnvironmentsByAlias = useMemo(
+    () =>
+      Object.values(savedEnvironmentsById).reduce<Record<string, SavedEnvironmentRecord>>(
+        (accumulator, record) => {
+          if (record.desktopSsh?.alias) {
+            accumulator[record.desktopSsh.alias] = record;
+          }
+          return accumulator;
+        },
+        {},
+      ),
+    [savedEnvironmentsById],
+  );
+  const [discoveredSshHosts, setDiscoveredSshHosts] = useState<
+    ReadonlyArray<DesktopDiscoveredSshHost>
+  >([]);
+  const [hasLoadedDiscoveredSshHosts, setHasLoadedDiscoveredSshHosts] = useState(false);
+  const [isLoadingDiscoveredSshHosts, setIsLoadingDiscoveredSshHosts] = useState(false);
+  const [discoveredSshHostsError, setDiscoveredSshHostsError] = useState<string | null>(null);
+  const [connectingSshHostAlias, setConnectingSshHostAlias] = useState<string | null>(null);
 
   const [desktopServerExposureState, setDesktopServerExposureState] =
     useState<DesktopServerExposureState | null>(null);
@@ -1024,13 +1165,17 @@ export function ConnectionsSettings() {
   >(null);
   const [isRevokingOtherDesktopClients, setIsRevokingOtherDesktopClients] = useState(false);
   const [addBackendDialogOpen, setAddBackendDialogOpen] = useState(false);
-  const [savedBackendMode, setSavedBackendMode] = useState<"pairing-url" | "host-code">(
+  const [savedBackendMode, setSavedBackendMode] = useState<"pairing-url" | "host-code" | "ssh">(
     "pairing-url",
   );
   const [savedBackendLabel, setSavedBackendLabel] = useState("");
   const [savedBackendPairingUrl, setSavedBackendPairingUrl] = useState("");
   const [savedBackendHost, setSavedBackendHost] = useState("");
   const [savedBackendPairingCode, setSavedBackendPairingCode] = useState("");
+  const [savedBackendSshHost, setSavedBackendSshHost] = useState("");
+  const [savedBackendSshUsername, setSavedBackendSshUsername] = useState("");
+  const [savedBackendSshPort, setSavedBackendSshPort] = useState("");
+  const [isManualSshFormOpen, setIsManualSshFormOpen] = useState(false);
   const [savedBackendError, setSavedBackendError] = useState<string | null>(null);
   const [isAddingSavedBackend, setIsAddingSavedBackend] = useState(false);
   const [reconnectingSavedEnvironmentId, setReconnectingSavedEnvironmentId] =
@@ -1158,6 +1303,47 @@ export function ConnectionsSettings() {
   }, []);
 
   const handleAddSavedBackend = useCallback(async () => {
+    if (savedBackendMode === "ssh") {
+      setIsAddingSavedBackend(true);
+      setSavedBackendError(null);
+      try {
+        const target = parseManualDesktopSshTarget({
+          host: savedBackendSshHost,
+          username: savedBackendSshUsername,
+          port: savedBackendSshPort,
+        });
+        const record = await connectDesktopSshEnvironment(target, {
+          label: savedBackendLabel,
+        });
+        setSavedBackendLabel("");
+        setSavedBackendPairingUrl("");
+        setSavedBackendHost("");
+        setSavedBackendPairingCode("");
+        setSavedBackendSshHost("");
+        setSavedBackendSshUsername("");
+        setSavedBackendSshPort("");
+        setIsManualSshFormOpen(false);
+        setAddBackendDialogOpen(false);
+        toastManager.add({
+          type: "success",
+          title: "Environment connected",
+          description: `${record.label} is ready over an SSH-managed tunnel.`,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
+        setIsManualSshFormOpen(true);
+        setSavedBackendError(message);
+        toastManager.add({
+          type: "error",
+          title: "Could not connect SSH host",
+          description: message,
+        });
+      } finally {
+        setIsAddingSavedBackend(false);
+      }
+      return;
+    }
+
     setIsAddingSavedBackend(true);
     setSavedBackendError(null);
     try {
@@ -1174,6 +1360,10 @@ export function ConnectionsSettings() {
       setSavedBackendPairingUrl("");
       setSavedBackendHost("");
       setSavedBackendPairingCode("");
+      setSavedBackendSshHost("");
+      setSavedBackendSshUsername("");
+      setSavedBackendSshPort("");
+      setIsManualSshFormOpen(false);
       setAddBackendDialogOpen(false);
       toastManager.add({
         type: "success",
@@ -1199,6 +1389,9 @@ export function ConnectionsSettings() {
     savedBackendMode,
     savedBackendPairingCode,
     savedBackendPairingUrl,
+    savedBackendSshHost,
+    savedBackendSshPort,
+    savedBackendSshUsername,
   ]);
 
   const handleReconnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
@@ -1241,6 +1434,90 @@ export function ConnectionsSettings() {
     }
   }, []);
 
+  const loadDiscoveredSshHosts = useCallback(async () => {
+    if (!desktopBridge) {
+      setDiscoveredSshHosts([]);
+      setHasLoadedDiscoveredSshHosts(false);
+      setDiscoveredSshHostsError(null);
+      return;
+    }
+
+    setIsLoadingDiscoveredSshHosts(true);
+    setDiscoveredSshHostsError(null);
+    try {
+      const hosts = await desktopBridge.discoverSshHosts();
+      setDiscoveredSshHosts(hosts);
+      setHasLoadedDiscoveredSshHosts(true);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to discover SSH hosts.";
+      setDiscoveredSshHostsError(message);
+      setHasLoadedDiscoveredSshHosts(true);
+    } finally {
+      setIsLoadingDiscoveredSshHosts(false);
+    }
+  }, [desktopBridge]);
+
+  const handleConnectSshHost = useCallback(
+    async (target: DesktopSshEnvironmentTarget, label?: string) => {
+      setConnectingSshHostAlias(target.alias);
+      if (savedBackendMode === "ssh") {
+        setSavedBackendError(null);
+      } else {
+        setDiscoveredSshHostsError(null);
+      }
+      try {
+        const record = await connectDesktopSshEnvironment(
+          target,
+          label === undefined ? undefined : { label },
+        );
+        setSavedBackendLabel("");
+        setSavedBackendSshHost("");
+        setSavedBackendSshUsername("");
+        setSavedBackendSshPort("");
+        setAddBackendDialogOpen(false);
+        toastManager.add({
+          type: "success",
+          title: savedDesktopSshEnvironmentsByAlias[target.alias]
+            ? "Environment reconnected"
+            : "Environment connected",
+          description: `${record.label} is ready over an SSH-managed tunnel.`,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
+        if (savedBackendMode === "ssh") {
+          setSavedBackendError(message);
+        } else {
+          setDiscoveredSshHostsError(message);
+        }
+        toastManager.add({
+          type: "error",
+          title: "Could not connect SSH host",
+          description: message,
+        });
+      } finally {
+        setConnectingSshHostAlias(null);
+      }
+    },
+    [savedBackendMode, savedDesktopSshEnvironmentsByAlias],
+  );
+
+  useEffect(() => {
+    if (!desktopBridge || !addBackendDialogOpen || savedBackendMode !== "ssh") {
+      return;
+    }
+    if (hasLoadedDiscoveredSshHosts || isLoadingDiscoveredSshHosts) {
+      return;
+    }
+    void loadDiscoveredSshHosts();
+  }, [
+    addBackendDialogOpen,
+    desktopBridge,
+    hasLoadedDiscoveredSshHosts,
+    isLoadingDiscoveredSshHosts,
+    loadDiscoveredSshHosts,
+    savedBackendMode,
+  ]);
+
   useEffect(() => {
     if (desktopBridge) {
       setCurrentSessionRole("owner");
@@ -1598,6 +1875,7 @@ export function ConnectionsSettings() {
               setAddBackendDialogOpen(open);
               if (!open) {
                 setSavedBackendError(null);
+                setIsManualSshFormOpen(false);
               }
             }}
           >
@@ -1609,7 +1887,7 @@ export function ConnectionsSettings() {
                 </Button>
               }
             />
-            <DialogPopup>
+            <DialogPopup className="sm:max-w-3xl">
               <DialogHeader>
                 <DialogTitle>Add Environment</DialogTitle>
                 <DialogDescription>Pair another environment to this client.</DialogDescription>
@@ -1640,6 +1918,21 @@ export function ConnectionsSettings() {
                   >
                     Host + code
                   </button>
+                  {desktopBridge ? (
+                    <button
+                      type="button"
+                      className={cn(
+                        "flex-1 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
+                        savedBackendMode === "ssh"
+                          ? "bg-background text-foreground shadow-xs"
+                          : "text-muted-foreground hover:text-foreground",
+                      )}
+                      disabled={isAddingSavedBackend}
+                      onClick={() => setSavedBackendMode("ssh")}
+                    >
+                      SSH
+                    </button>
+                  ) : null}
                 </div>
               </DialogHeader>
               <DialogPanel>
@@ -1648,25 +1941,30 @@ export function ConnectionsSettings() {
                     <p className="text-xs text-muted-foreground">
                       Enter the full pairing URL from the environment you want to connect to.
                     </p>
-                  ) : (
+                  ) : savedBackendMode === "host-code" ? (
                     <p className="text-xs text-muted-foreground">
                       Enter the backend host and pairing code separately.
                     </p>
+                  ) : (
+                    <p className="text-xs text-muted-foreground">
+                      Connect over SSH using an existing alias from <code>~/.ssh/config</code> or
+                      enter a host directly. T3 uses your current SSH agent and config.
+                    </p>
                   )}
-                  <div className="space-y-3">
-                    <label className="block">
-                      <span className="mb-1.5 block text-xs font-medium text-foreground">
-                        Label
-                      </span>
-                      <Input
-                        value={savedBackendLabel}
-                        onChange={(event) => setSavedBackendLabel(event.target.value)}
-                        placeholder="My backend (optional)"
-                        disabled={isAddingSavedBackend}
-                        spellCheck={false}
-                      />
-                    </label>
-                    {savedBackendMode === "pairing-url" ? (
+                  {savedBackendMode === "pairing-url" ? (
+                    <div className="space-y-3">
+                      <label className="block">
+                        <span className="mb-1.5 block text-xs font-medium text-foreground">
+                          Label
+                        </span>
+                        <Input
+                          value={savedBackendLabel}
+                          onChange={(event) => setSavedBackendLabel(event.target.value)}
+                          placeholder="My backend (optional)"
+                          disabled={isAddingSavedBackend}
+                          spellCheck={false}
+                        />
+                      </label>
                       <label className="block">
                         <span className="mb-1.5 block text-xs font-medium text-foreground">
                           Pairing URL
@@ -1682,47 +1980,206 @@ export function ConnectionsSettings() {
                           The full URL including the pairing token.
                         </span>
                       </label>
-                    ) : (
-                      <>
-                        <label className="block">
-                          <span className="mb-1.5 block text-xs font-medium text-foreground">
-                            Host
-                          </span>
-                          <Input
-                            value={savedBackendHost}
-                            onChange={(event) => setSavedBackendHost(event.target.value)}
-                            placeholder="https://backend.example.com"
-                            disabled={isAddingSavedBackend}
-                            spellCheck={false}
+                    </div>
+                  ) : savedBackendMode === "host-code" ? (
+                    <div className="space-y-3">
+                      <label className="block">
+                        <span className="mb-1.5 block text-xs font-medium text-foreground">
+                          Label
+                        </span>
+                        <Input
+                          value={savedBackendLabel}
+                          onChange={(event) => setSavedBackendLabel(event.target.value)}
+                          placeholder="My backend (optional)"
+                          disabled={isAddingSavedBackend}
+                          spellCheck={false}
+                        />
+                      </label>
+                      <label className="block">
+                        <span className="mb-1.5 block text-xs font-medium text-foreground">
+                          Host
+                        </span>
+                        <Input
+                          value={savedBackendHost}
+                          onChange={(event) => setSavedBackendHost(event.target.value)}
+                          placeholder="https://backend.example.com"
+                          disabled={isAddingSavedBackend}
+                          spellCheck={false}
+                        />
+                      </label>
+                      <label className="block">
+                        <span className="mb-1.5 block text-xs font-medium text-foreground">
+                          Pairing code
+                        </span>
+                        <Input
+                          value={savedBackendPairingCode}
+                          onChange={(event) => setSavedBackendPairingCode(event.target.value)}
+                          placeholder="Pairing code"
+                          disabled={isAddingSavedBackend}
+                          spellCheck={false}
+                        />
+                      </label>
+                    </div>
+                  ) : (
+                    <div className="space-y-4">
+                      <div className="flex items-start justify-between gap-3">
+                        <div className="min-w-0">
+                          <h3 className="text-sm font-medium text-foreground">Discovered hosts</h3>
+                          <p className="text-xs text-muted-foreground">
+                            From <code>~/.ssh/config</code> and <code>known_hosts</code>.
+                          </p>
+                        </div>
+                        <Button
+                          size="xs"
+                          variant="outline"
+                          disabled={isLoadingDiscoveredSshHosts}
+                          onClick={() => void loadDiscoveredSshHosts()}
+                        >
+                          {isLoadingDiscoveredSshHosts ? (
+                            <RefreshCwIcon className="size-3 animate-spin" />
+                          ) : (
+                            <RefreshCwIcon className="size-3" />
+                          )}
+                          Refresh
+                        </Button>
+                      </div>
+                      {discoveredSshHostsError ? (
+                        <p className="text-xs text-destructive">{discoveredSshHostsError}</p>
+                      ) : null}
+                      <div>
+                        {discoveredSshHosts.map((target) => (
+                          <DesktopSshHostRow
+                            key={`${target.alias}:${target.hostname}:${target.port ?? ""}`}
+                            target={target}
+                            savedRecord={savedDesktopSshEnvironmentsByAlias[target.alias] ?? null}
+                            connectingHostAlias={connectingSshHostAlias}
+                            onConnect={(nextTarget) => void handleConnectSshHost(nextTarget)}
                           />
-                        </label>
-                        <label className="block">
-                          <span className="mb-1.5 block text-xs font-medium text-foreground">
-                            Pairing code
-                          </span>
-                          <Input
-                            value={savedBackendPairingCode}
-                            onChange={(event) => setSavedBackendPairingCode(event.target.value)}
-                            placeholder="Pairing code"
-                            disabled={isAddingSavedBackend}
-                            spellCheck={false}
+                        ))}
+                        {hasLoadedDiscoveredSshHosts &&
+                        !isLoadingDiscoveredSshHosts &&
+                        discoveredSshHosts.length === 0 ? (
+                          <div className={ITEM_ROW_CLASSNAME}>
+                            <p className="text-xs text-muted-foreground">
+                              No SSH hosts were discovered from <code>~/.ssh/config</code> or{" "}
+                              <code>known_hosts</code>.
+                            </p>
+                          </div>
+                        ) : null}
+                      </div>
+                      {savedBackendError ? (
+                        <p className="text-xs text-destructive">{savedBackendError}</p>
+                      ) : null}
+                      <Collapsible open={isManualSshFormOpen} onOpenChange={setIsManualSshFormOpen}>
+                        <CollapsibleTrigger
+                          className={cn(
+                            "flex w-full items-center justify-between gap-3 rounded-md border border-border/60 px-4 py-3 text-left transition-colors hover:bg-muted/35",
+                            isManualSshFormOpen && "bg-muted/20",
+                          )}
+                        >
+                          <div className="min-w-0">
+                            <p className="text-sm font-medium text-foreground">
+                              Enter a host manually
+                            </p>
+                            <p className="text-xs text-muted-foreground">
+                              Use an alias or enter host, username, and port directly.
+                            </p>
+                          </div>
+                          <ChevronDownIcon
+                            className={cn(
+                              "size-4 shrink-0 text-muted-foreground transition-transform duration-200",
+                              isManualSshFormOpen && "rotate-180",
+                            )}
                           />
-                        </label>
-                      </>
-                    )}
-                  </div>
-                  {savedBackendError ? (
+                        </CollapsibleTrigger>
+                        <CollapsibleContent className="pt-4">
+                          <div className="space-y-3">
+                            <label className="block">
+                              <span className="mb-1.5 block text-xs font-medium text-foreground">
+                                Label
+                              </span>
+                              <Input
+                                value={savedBackendLabel}
+                                onChange={(event) => setSavedBackendLabel(event.target.value)}
+                                placeholder="My backend (optional)"
+                                disabled={isAddingSavedBackend}
+                                spellCheck={false}
+                              />
+                            </label>
+                            <label className="block">
+                              <span className="mb-1.5 block text-xs font-medium text-foreground">
+                                SSH host or alias
+                              </span>
+                              <Input
+                                value={savedBackendSshHost}
+                                onChange={(event) => setSavedBackendSshHost(event.target.value)}
+                                placeholder="devbox or devbox.example.com"
+                                disabled={isAddingSavedBackend}
+                                spellCheck={false}
+                              />
+                            </label>
+                            <div className="grid gap-3 sm:grid-cols-2">
+                              <label className="block">
+                                <span className="mb-1.5 block text-xs font-medium text-foreground">
+                                  Username
+                                </span>
+                                <Input
+                                  value={savedBackendSshUsername}
+                                  onChange={(event) =>
+                                    setSavedBackendSshUsername(event.target.value)
+                                  }
+                                  placeholder="julius"
+                                  disabled={isAddingSavedBackend}
+                                  spellCheck={false}
+                                />
+                              </label>
+                              <label className="block">
+                                <span className="mb-1.5 block text-xs font-medium text-foreground">
+                                  Port
+                                </span>
+                                <Input
+                                  value={savedBackendSshPort}
+                                  onChange={(event) => setSavedBackendSshPort(event.target.value)}
+                                  placeholder="22"
+                                  inputMode="numeric"
+                                  disabled={isAddingSavedBackend}
+                                  spellCheck={false}
+                                />
+                              </label>
+                            </div>
+                            <span className="block text-[11px] text-muted-foreground">
+                              Uses your existing SSH keys, agent, and config. Password and
+                              keyboard-interactive prompts open through your system SSH dialog when
+                              needed.
+                            </span>
+                            <Button
+                              variant="outline"
+                              className="w-full"
+                              disabled={isAddingSavedBackend}
+                              onClick={() => void handleAddSavedBackend()}
+                            >
+                              <PlusIcon className="size-3.5" />
+                              {isAddingSavedBackend ? "Connecting…" : "Connect SSH host"}
+                            </Button>
+                          </div>
+                        </CollapsibleContent>
+                      </Collapsible>
+                    </div>
+                  )}
+                  {savedBackendMode !== "ssh" && savedBackendError ? (
                     <p className="text-xs text-destructive">{savedBackendError}</p>
                   ) : null}
-                  <Button
-                    variant="outline"
-                    className="w-full"
-                    disabled={isAddingSavedBackend}
-                    onClick={() => void handleAddSavedBackend()}
-                  >
-                    <PlusIcon className="size-3.5" />
-                    {isAddingSavedBackend ? "Adding…" : "Add Backend"}
-                  </Button>
+                  {savedBackendMode !== "ssh" ? (
+                    <Button
+                      variant="outline"
+                      className="w-full"
+                      disabled={isAddingSavedBackend}
+                      onClick={() => void handleAddSavedBackend()}
+                    >
+                      <PlusIcon className="size-3.5" />
+                      {isAddingSavedBackend ? "Adding…" : "Add Backend"}
+                    </Button>
+                  ) : null}
                 </div>
               </DialogPanel>
             </DialogPopup>
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 3230b070756..801f23f5abf 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -116,6 +116,8 @@ const authAccessHarness = vi.hoisted(() => {
   };
 });
 
+const mockConnectDesktopSshEnvironment = vi.fn();
+
 vi.mock("../../environments/runtime", () => {
   const primaryConnection = {
     kind: "primary" as const,
@@ -153,6 +155,7 @@ vi.mock("../../environments/runtime", () => {
       new URL(path, "http://localhost:3000").toString(),
     waitForSavedEnvironmentRegistryHydration: async () => undefined,
     addSavedEnvironment: vi.fn(),
+    connectDesktopSshEnvironment: mockConnectDesktopSshEnvironment,
     disconnectSavedEnvironment: vi.fn(),
     ensureEnvironmentConnectionBootstrapped: async () => undefined,
     getPrimaryEnvironmentConnection: () => primaryConnection,
@@ -260,6 +263,7 @@ function makeClientSession(input: {
 }
 
 const createDesktopBridgeStub = (overrides?: {
+  readonly discoverSshHosts?: DesktopBridge["discoverSshHosts"];
   readonly serverExposureState?: Awaited<ReturnType<DesktopBridge["getServerExposureState"]>>;
   readonly advertisedEndpoints?: Awaited<ReturnType<DesktopBridge["getAdvertisedEndpoints"]>>;
   readonly setServerExposureMode?: DesktopBridge["setServerExposureMode"];
@@ -297,6 +301,50 @@ const createDesktopBridgeStub = (overrides?: {
     getSavedEnvironmentSecret: vi.fn().mockResolvedValue(null),
     setSavedEnvironmentSecret: vi.fn().mockResolvedValue(true),
     removeSavedEnvironmentSecret: vi.fn().mockResolvedValue(undefined),
+    discoverSshHosts: overrides?.discoverSshHosts ?? vi.fn().mockResolvedValue([]),
+    ensureSshEnvironment: vi.fn().mockImplementation(async (target) => ({
+      target,
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      pairingToken: "ssh-pairing-token",
+    })),
+    fetchSshEnvironmentDescriptor: vi.fn().mockResolvedValue({
+      environmentId: "environment-ssh",
+      label: "SSH environment",
+      platform: {
+        os: "linux",
+        arch: "x64",
+      },
+      serverVersion: "0.0.0-test",
+      capabilities: {
+        repositoryIdentity: true,
+      },
+    }),
+    bootstrapSshBearerSession: vi.fn().mockResolvedValue({
+      authenticated: true,
+      role: "owner",
+      sessionMethod: "bearer-session-token",
+      expiresAt: "2026-05-01T12:00:00.000Z",
+      sessionToken: "ssh-bearer-token",
+    }),
+    fetchSshSessionState: vi.fn().mockResolvedValue({
+      authenticated: true,
+      auth: {
+        policy: "remote-reachable",
+        bootstrapMethods: ["one-time-token"],
+        sessionMethods: ["browser-session-cookie", "bearer-session-token"],
+        sessionCookieName: "t3_session",
+      },
+      role: "owner",
+      sessionMethod: "bearer-session-token",
+      expiresAt: "2026-05-01T12:00:00.000Z",
+    }),
+    issueSshWebSocketToken: vi.fn().mockResolvedValue({
+      token: "ssh-ws-token",
+      expiresAt: "2026-05-01T12:05:00.000Z",
+    }),
+    onSshPasswordPrompt: vi.fn(() => () => {}),
+    resolveSshPasswordPrompt: vi.fn().mockResolvedValue(undefined),
     getServerExposureState: vi.fn().mockResolvedValue(
       overrides?.serverExposureState ?? {
         mode: "local-only",
@@ -350,6 +398,7 @@ describe("GeneralSettingsPanel observability", () => {
     localStorage.clear();
     useUiStateStore.setState({ defaultAdvertisedEndpointKey: null });
     authAccessHarness.reset();
+    mockConnectDesktopSshEnvironment.mockReset();
   });
 
   afterEach(async () => {
@@ -854,6 +903,70 @@ describe("GeneralSettingsPanel observability", () => {
       .toBeInTheDocument();
   });
 
+  it("adds desktop ssh environments from the add-environment dialog", async () => {
+    const discoverSshHosts = vi.fn().mockResolvedValue([
+      {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+        source: "ssh-config" as const,
+      },
+    ]);
+    window.desktopBridge = createDesktopBridgeStub({
+      discoverSshHosts,
+    });
+    mockConnectDesktopSshEnvironment.mockResolvedValue({
+      environmentId: EnvironmentId.make("environment-devbox"),
+      label: "Build box",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      createdAt: "2036-04-07T00:00:00.000Z",
+      lastConnectedAt: "2036-04-07T00:00:00.000Z",
+      desktopSsh: {
+        alias: "devbox.example.com",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 2222,
+      },
+    });
+
+    setServerConfigSnapshot(createBaseServerConfig());
+
+    mounted = await render(
+      <AppAtomRegistryProvider>
+        <ConnectionsSettings />
+      </AppAtomRegistryProvider>,
+    );
+
+    await page.getByRole("button", { name: "Add environment", exact: true }).click();
+    await expect.element(page.getByText("Add Environment")).toBeInTheDocument();
+    await page.getByRole("button", { name: "SSH", exact: true }).click();
+    await vi.waitFor(() => {
+      expect(discoverSshHosts).toHaveBeenCalledTimes(1);
+    });
+    await expect.element(page.getByText("devbox")).toBeInTheDocument();
+
+    await page.getByText("Enter a host manually").click();
+    await page.getByLabelText("Label").fill("Build box");
+    await page.getByLabelText("SSH host or alias").fill("devbox.example.com");
+    await page.getByLabelText("Username").fill("julius");
+    await page.getByLabelText("Port").fill("2222");
+    await page.getByRole("button", { name: "Connect SSH host", exact: true }).click();
+
+    await vi.waitFor(() => {
+      expect(mockConnectDesktopSshEnvironment).toHaveBeenCalledWith(
+        {
+          alias: "devbox.example.com",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 2222,
+        },
+        { label: "Build box" },
+      );
+    });
+  });
+
   it("opens the logs folder in the preferred editor", async () => {
     const openInEditor = vi.fn<LocalApi["shell"]["openInEditor"]>().mockResolvedValue(undefined);
     window.nativeApi = {
diff --git a/apps/web/src/components/ui/dialog.tsx b/apps/web/src/components/ui/dialog.tsx
index 080ac809975..bebe1b0ee03 100644
--- a/apps/web/src/components/ui/dialog.tsx
+++ b/apps/web/src/components/ui/dialog.tsx
@@ -24,7 +24,7 @@ function DialogBackdrop({ className, ...props }: DialogPrimitive.Backdrop.Props)
   return (
     <DialogPrimitive.Backdrop
       className={cn(
-        "fixed inset-0 z-50 bg-black/32 backdrop-blur-sm transition-all duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0",
+        "fixed inset-0 z-50 transition-all duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0",
         className,
       )}
       data-slot="dialog-backdrop"
@@ -37,7 +37,7 @@ function DialogViewport({ className, ...props }: DialogPrimitive.Viewport.Props)
   return (
     <DialogPrimitive.Viewport
       className={cn(
-        "fixed inset-0 z-50 grid grid-rows-[1fr_auto_3fr] justify-items-center p-4",
+        "fixed inset-0 z-50 grid grid-rows-[1fr_auto_3fr] justify-items-center bg-white/48 p-4 backdrop-blur-[2px] dark:bg-black/28",
         className,
       )}
       data-slot="dialog-viewport"
diff --git a/apps/web/src/environments/remote/api.ts b/apps/web/src/environments/remote/api.ts
index 50b593975d3..5d56a0b4204 100644
--- a/apps/web/src/environments/remote/api.ts
+++ b/apps/web/src/environments/remote/api.ts
@@ -15,6 +15,12 @@ class RemoteEnvironmentAuthHttpError extends Error {
   }
 }
 
+export function isRemoteEnvironmentAuthHttpError(
+  error: unknown,
+): error is RemoteEnvironmentAuthHttpError {
+  return error instanceof RemoteEnvironmentAuthHttpError;
+}
+
 function remoteEndpointUrl(httpBaseUrl: string, pathname: string): string {
   const url = new URL(httpBaseUrl);
   url.pathname = pathname;
diff --git a/apps/web/src/environments/runtime/catalog.ts b/apps/web/src/environments/runtime/catalog.ts
index 6aecf80f804..839e967ddfa 100644
--- a/apps/web/src/environments/runtime/catalog.ts
+++ b/apps/web/src/environments/runtime/catalog.ts
@@ -18,6 +18,7 @@ export interface SavedEnvironmentRecord {
   readonly httpBaseUrl: string;
   readonly createdAt: string;
   readonly lastConnectedAt: string | null;
+  readonly desktopSsh?: PersistedSavedEnvironmentRecord["desktopSsh"];
 }
 
 interface SavedEnvironmentRegistryState {
@@ -44,6 +45,7 @@ function toPersistedSavedEnvironmentRecord(
     wsBaseUrl: record.wsBaseUrl,
     createdAt: record.createdAt,
     lastConnectedAt: record.lastConnectedAt,
+    ...(record.desktopSsh ? { desktopSsh: record.desktopSsh } : {}),
   };
 }
 
diff --git a/apps/web/src/environments/runtime/index.ts b/apps/web/src/environments/runtime/index.ts
index 8c813f10826..0192fb6026d 100644
--- a/apps/web/src/environments/runtime/index.ts
+++ b/apps/web/src/environments/runtime/index.ts
@@ -16,6 +16,7 @@ export {
 
 export {
   addSavedEnvironment,
+  connectDesktopSshEnvironment,
   disconnectSavedEnvironment,
   ensureEnvironmentConnectionBootstrapped,
   getPrimaryEnvironmentConnection,
diff --git a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
index 9bcbc4f7133..54afb6c6f47 100644
--- a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
+++ b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
@@ -4,11 +4,15 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 const mockResolveRemotePairingTarget = vi.fn();
 const mockFetchRemoteEnvironmentDescriptor = vi.fn();
 const mockBootstrapRemoteBearerSession = vi.fn();
+const mockBootstrapSshBearerSession = vi.fn();
 const mockPersistSavedEnvironmentRecord = vi.fn();
 const mockWriteSavedEnvironmentBearerToken = vi.fn();
 const mockSetSavedEnvironmentRegistry = vi.fn();
 const mockUpsert = vi.fn();
 const mockListSavedEnvironmentRecords = vi.fn();
+const mockEnsureSshEnvironment = vi.fn();
+const mockFetchSshEnvironmentDescriptor = vi.fn();
+const mockCreateEnvironmentConnection = vi.fn();
 
 vi.mock("../remote/target", () => ({
   resolveRemotePairingTarget: mockResolveRemotePairingTarget,
@@ -18,6 +22,7 @@ vi.mock("../remote/api", () => ({
   bootstrapRemoteBearerSession: mockBootstrapRemoteBearerSession,
   fetchRemoteEnvironmentDescriptor: mockFetchRemoteEnvironmentDescriptor,
   fetchRemoteSessionState: vi.fn(),
+  isRemoteEnvironmentAuthHttpError: vi.fn(() => false),
   resolveRemoteWebSocketConnectionUrl: vi.fn(),
 }));
 
@@ -55,18 +60,37 @@ vi.mock("./catalog", () => ({
 }));
 
 vi.mock("./connection", () => ({
-  createEnvironmentConnection: vi.fn(),
+  createEnvironmentConnection: mockCreateEnvironmentConnection,
 }));
 
 describe("addSavedEnvironment", () => {
   beforeEach(() => {
     vi.resetModules();
     vi.clearAllMocks();
-    mockResolveRemotePairingTarget.mockReturnValue({
-      httpBaseUrl: "https://remote.example.com/",
-      wsBaseUrl: "wss://remote.example.com/",
-      credential: "pairing-code",
+    vi.stubGlobal("window", {
+      desktopBridge: {
+        ensureSshEnvironment: mockEnsureSshEnvironment,
+        fetchSshEnvironmentDescriptor: mockFetchSshEnvironmentDescriptor,
+        bootstrapSshBearerSession: mockBootstrapSshBearerSession,
+        fetchSshSessionState: vi.fn(),
+        issueSshWebSocketToken: vi.fn(),
+      },
     });
+    mockResolveRemotePairingTarget.mockImplementation(
+      (input: { host?: string; pairingCode?: string }) => ({
+        httpBaseUrl: input.host
+          ? input.host.endsWith("/")
+            ? input.host
+            : `${input.host}/`
+          : "https://remote.example.com/",
+        wsBaseUrl: input.host
+          ? input.host.replace(/^http/u, "ws").endsWith("/")
+            ? input.host.replace(/^http/u, "ws")
+            : `${input.host.replace(/^http/u, "ws")}/`
+          : "wss://remote.example.com/",
+        credential: input.pairingCode ?? "pairing-code",
+      }),
+    );
     mockFetchRemoteEnvironmentDescriptor.mockResolvedValue({
       environmentId: EnvironmentId.make("environment-1"),
       label: "Remote environment",
@@ -75,10 +99,40 @@ describe("addSavedEnvironment", () => {
       sessionToken: "bearer-token",
       role: "owner",
     });
+    mockFetchSshEnvironmentDescriptor.mockResolvedValue({
+      environmentId: EnvironmentId.make("environment-1"),
+      label: "Remote environment",
+    });
+    mockBootstrapSshBearerSession.mockResolvedValue({
+      sessionToken: "ssh-bearer-token",
+      role: "owner",
+    });
     mockPersistSavedEnvironmentRecord.mockResolvedValue(undefined);
     mockWriteSavedEnvironmentBearerToken.mockResolvedValue(false);
     mockSetSavedEnvironmentRegistry.mockResolvedValue(undefined);
     mockListSavedEnvironmentRecords.mockReturnValue([]);
+    mockCreateEnvironmentConnection.mockImplementation(
+      (input: { knownEnvironment: { environmentId: EnvironmentId }; client: unknown }) => ({
+        kind: "saved",
+        environmentId: input.knownEnvironment.environmentId,
+        knownEnvironment: input.knownEnvironment,
+        client: input.client,
+        ensureBootstrapped: async () => undefined,
+        reconnect: async () => undefined,
+        dispose: async () => undefined,
+      }),
+    );
+    mockEnsureSshEnvironment.mockResolvedValue({
+      target: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      pairingToken: "ssh-pairing-code",
+    });
   });
 
   it("rolls back persisted metadata when bearer token persistence fails", async () => {
@@ -102,4 +156,46 @@ describe("addSavedEnvironment", () => {
 
     await resetEnvironmentServiceForTests();
   });
+
+  it("bootstraps a desktop ssh environment through the desktop bridge", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+
+    const { connectDesktopSshEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await expect(
+      connectDesktopSshEnvironment({
+        alias: "devbox",
+        hostname: "devbox",
+        username: null,
+        port: null,
+      }),
+    ).rejects.toThrow();
+
+    expect(mockEnsureSshEnvironment).toHaveBeenCalledWith(
+      {
+        alias: "devbox",
+        hostname: "devbox",
+        username: null,
+        port: null,
+      },
+      { issuePairingToken: true },
+    );
+    expect(mockResolveRemotePairingTarget).toHaveBeenCalledWith({
+      host: "http://127.0.0.1:3774/",
+      pairingCode: "ssh-pairing-code",
+    });
+    expect(mockFetchSshEnvironmentDescriptor).toHaveBeenCalledWith("http://127.0.0.1:3774/");
+    expect(mockBootstrapSshBearerSession).toHaveBeenCalledWith(
+      "http://127.0.0.1:3774/",
+      "ssh-pairing-code",
+    );
+    expect(mockFetchRemoteEnvironmentDescriptor).not.toHaveBeenCalled();
+    expect(mockBootstrapRemoteBearerSession).not.toHaveBeenCalled();
+    expect(mockUpsert.mock.invocationCallOrder[0]).toBeLessThan(
+      mockCreateEnvironmentConnection.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
 });
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 6c58f9e8a53..be20cbd1fd5 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -1,5 +1,7 @@
 import {
   type AuthSessionRole,
+  type DesktopSshEnvironmentBootstrap,
+  type DesktopSshEnvironmentTarget,
   type EnvironmentId,
   type OrchestrationEvent,
   type OrchestrationShellSnapshot,
@@ -33,6 +35,7 @@ import {
   bootstrapRemoteBearerSession,
   fetchRemoteEnvironmentDescriptor,
   fetchRemoteSessionState,
+  isRemoteEnvironmentAuthHttpError,
   resolveRemoteWebSocketConnectionUrl,
 } from "../remote/api";
 import { resolveRemotePairingTarget } from "../remote/target";
@@ -85,6 +88,7 @@ type ThreadDetailSubscriptionEntry = {
 };
 
 const environmentConnections = new Map<EnvironmentId, EnvironmentConnection>();
+const pendingSavedEnvironmentConnections = new Map<EnvironmentId, Promise<EnvironmentConnection>>();
 const environmentConnectionListeners = new Set<() => void>();
 const threadDetailSubscriptions = new Map<string, ThreadDetailSubscriptionEntry>();
 const lastAppliedProjectionVersionByEnvironment = new Map<
@@ -491,6 +495,163 @@ function isoNow(): string {
   return new Date().toISOString();
 }
 
+function serializeSavedEnvironmentRecord(record: SavedEnvironmentRecord) {
+  return {
+    environmentId: record.environmentId,
+    label: record.label,
+    httpBaseUrl: record.httpBaseUrl,
+    wsBaseUrl: record.wsBaseUrl,
+    createdAt: record.createdAt,
+    lastConnectedAt: record.lastConnectedAt,
+    ...(record.desktopSsh ? { desktopSsh: record.desktopSsh } : {}),
+  } as const;
+}
+
+function isDesktopSshTargetEqual(
+  left: DesktopSshEnvironmentTarget | undefined,
+  right: DesktopSshEnvironmentTarget | undefined,
+): boolean {
+  if (!left || !right) {
+    return false;
+  }
+
+  return (
+    left.alias === right.alias &&
+    left.hostname === right.hostname &&
+    left.username === right.username &&
+    left.port === right.port
+  );
+}
+
+function findSavedEnvironmentRecordByDesktopSshTarget(
+  target: DesktopSshEnvironmentTarget | undefined,
+): SavedEnvironmentRecord | null {
+  if (!target) {
+    return null;
+  }
+
+  return (
+    listSavedEnvironmentRecords().find((record) =>
+      isDesktopSshTargetEqual(record.desktopSsh, target),
+    ) ?? null
+  );
+}
+
+async function persistSavedEnvironmentRegistryRollback(): Promise<void> {
+  await ensureLocalApi().persistence.setSavedEnvironmentRegistry(
+    listSavedEnvironmentRecords().map((entry) => serializeSavedEnvironmentRecord(entry)),
+  );
+}
+
+async function resolveDesktopSshEnvironmentBootstrap(
+  target: DesktopSshEnvironmentTarget,
+  options?: { readonly issuePairingToken?: boolean },
+): Promise<DesktopSshEnvironmentBootstrap> {
+  const desktopBridge = window.desktopBridge;
+  if (!desktopBridge) {
+    throw new Error("SSH launch is only available in the desktop app.");
+  }
+
+  return await desktopBridge.ensureSshEnvironment(target, options);
+}
+
+function getDesktopSshBridge() {
+  const desktopBridge = window.desktopBridge;
+  if (!desktopBridge) {
+    throw new Error("SSH launch is only available in the desktop app.");
+  }
+  return desktopBridge;
+}
+
+async function fetchDesktopSshEnvironmentDescriptor(httpBaseUrl: string) {
+  return await getDesktopSshBridge().fetchSshEnvironmentDescriptor(httpBaseUrl);
+}
+
+async function bootstrapDesktopSshBearerSession(httpBaseUrl: string, credential: string) {
+  return await getDesktopSshBridge().bootstrapSshBearerSession(httpBaseUrl, credential);
+}
+
+async function fetchDesktopSshSessionState(httpBaseUrl: string, bearerToken: string) {
+  return await getDesktopSshBridge().fetchSshSessionState(httpBaseUrl, bearerToken);
+}
+
+async function resolveDesktopSshWebSocketConnectionUrl(
+  wsBaseUrl: string,
+  httpBaseUrl: string,
+  bearerToken: string,
+) {
+  const issued = await getDesktopSshBridge().issueSshWebSocketToken(httpBaseUrl, bearerToken);
+  const url = new URL(wsBaseUrl, window.location.origin);
+  url.searchParams.set("wsToken", issued.token);
+  return url.toString();
+}
+
+async function prepareSavedEnvironmentRecordForConnection(
+  record: SavedEnvironmentRecord,
+  options?: { readonly issuePairingToken?: boolean },
+): Promise<{
+  readonly record: SavedEnvironmentRecord;
+  readonly pairingToken: string | null;
+}> {
+  if (!record.desktopSsh) {
+    return { record, pairingToken: null };
+  }
+
+  const bootstrap = await resolveDesktopSshEnvironmentBootstrap(record.desktopSsh, options);
+  const nextRecord: SavedEnvironmentRecord = {
+    ...record,
+    httpBaseUrl: bootstrap.httpBaseUrl,
+    wsBaseUrl: bootstrap.wsBaseUrl,
+    desktopSsh: bootstrap.target,
+  };
+
+  if (
+    nextRecord.httpBaseUrl !== record.httpBaseUrl ||
+    nextRecord.wsBaseUrl !== record.wsBaseUrl ||
+    !isDesktopSshTargetEqual(nextRecord.desktopSsh, record.desktopSsh)
+  ) {
+    await persistSavedEnvironmentRecord(nextRecord);
+    useSavedEnvironmentRegistryStore.getState().upsert(nextRecord);
+  }
+
+  return {
+    record: nextRecord,
+    pairingToken: bootstrap.pairingToken,
+  };
+}
+
+async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Promise<{
+  readonly record: SavedEnvironmentRecord;
+  readonly bearerToken: string;
+  readonly role: AuthSessionRole | null;
+}> {
+  const prepared = await prepareSavedEnvironmentRecordForConnection(record, {
+    issuePairingToken: true,
+  });
+  if (!prepared.pairingToken) {
+    throw new Error("Desktop SSH launch did not return a pairing token.");
+  }
+
+  const bearerSession = await bootstrapDesktopSshBearerSession(
+    prepared.record.httpBaseUrl,
+    prepared.pairingToken,
+  );
+  const didPersistBearerToken = await writeSavedEnvironmentBearerToken(
+    prepared.record.environmentId,
+    bearerSession.sessionToken,
+  );
+  if (!didPersistBearerToken) {
+    await persistSavedEnvironmentRegistryRollback();
+    throw new Error("Unable to persist saved environment credentials.");
+  }
+
+  return {
+    record: prepared.record,
+    bearerToken: bearerSession.sessionToken,
+    role: bearerSession.role ?? null,
+  };
+}
+
 function setRuntimeConnecting(environmentId: EnvironmentId) {
   useSavedEnvironmentRuntimeStore.getState().patch(environmentId, {
     connectionState: "connecting",
@@ -802,35 +963,46 @@ function createPrimaryEnvironmentClient(
 }
 
 function createSavedEnvironmentClient(
-  record: SavedEnvironmentRecord,
+  environmentId: EnvironmentId,
   bearerToken: string,
 ): WsRpcClient {
-  useSavedEnvironmentRuntimeStore.getState().ensure(record.environmentId);
+  useSavedEnvironmentRuntimeStore.getState().ensure(environmentId);
 
   return createWsRpcClient(
     new WsTransport(
-      () =>
-        resolveRemoteWebSocketConnectionUrl({
-          wsBaseUrl: record.wsBaseUrl,
-          httpBaseUrl: record.httpBaseUrl,
-          bearerToken,
-        }),
+      async () => {
+        const record = getSavedEnvironmentRecord(environmentId);
+        if (!record) {
+          throw new Error(`Saved environment ${environmentId} not found.`);
+        }
+        return record.desktopSsh
+          ? await resolveDesktopSshWebSocketConnectionUrl(
+              record.wsBaseUrl,
+              record.httpBaseUrl,
+              bearerToken,
+            )
+          : await resolveRemoteWebSocketConnectionUrl({
+              wsBaseUrl: record.wsBaseUrl,
+              httpBaseUrl: record.httpBaseUrl,
+              bearerToken,
+            });
+      },
       {
         onAttempt: () => {
-          setRuntimeConnecting(record.environmentId);
+          setRuntimeConnecting(environmentId);
         },
         onOpen: () => {
-          setRuntimeConnected(record.environmentId);
+          setRuntimeConnected(environmentId);
         },
         onError: (message: string) => {
-          useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
+          useSavedEnvironmentRuntimeStore.getState().patch(environmentId, {
             connectionState: "error",
             lastError: message,
             lastErrorAt: isoNow(),
           });
         },
         onClose: (details: { readonly code: number; readonly reason: string }) => {
-          setRuntimeDisconnected(record.environmentId, details.reason);
+          setRuntimeDisconnected(environmentId, details.reason);
         },
       },
     ),
@@ -838,18 +1010,25 @@ function createSavedEnvironmentClient(
 }
 
 async function refreshSavedEnvironmentMetadata(
-  record: SavedEnvironmentRecord,
+  environmentId: EnvironmentId,
   bearerToken: string,
   client: WsRpcClient,
   roleHint?: AuthSessionRole | null,
   configHint?: ServerConfig | null,
 ): Promise<void> {
+  const record = getSavedEnvironmentRecord(environmentId);
+  if (!record) {
+    throw new Error(`Saved environment ${environmentId} not found.`);
+  }
+
   const [serverConfig, sessionState] = await Promise.all([
     configHint ? Promise.resolve(configHint) : client.server.getConfig(),
-    fetchRemoteSessionState({
-      httpBaseUrl: record.httpBaseUrl,
-      bearerToken,
-    }),
+    record.desktopSsh
+      ? fetchDesktopSshSessionState(record.httpBaseUrl, bearerToken)
+      : fetchRemoteSessionState({
+          httpBaseUrl: record.httpBaseUrl,
+          bearerToken,
+        }),
   ]);
 
   useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
@@ -923,69 +1102,124 @@ async function ensureSavedEnvironmentConnection(
     return existing;
   }
 
-  const bearerToken =
-    options?.bearerToken ?? (await readSavedEnvironmentBearerToken(record.environmentId));
-  if (!bearerToken) {
-    useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
-      authState: "requires-auth",
-      role: null,
-      connectionState: "disconnected",
-      lastError: "Saved environment is missing its saved credential. Pair it again.",
-      lastErrorAt: isoNow(),
-    });
-    throw new Error("Saved environment is missing its saved credential.");
+  const pending = pendingSavedEnvironmentConnections.get(record.environmentId);
+  if (pending) {
+    return pending;
   }
 
-  const client = options?.client ?? createSavedEnvironmentClient(record, bearerToken);
-  const knownEnvironment = createKnownEnvironment({
-    id: record.environmentId,
-    label: record.label,
-    source: "manual",
-    target: {
-      httpBaseUrl: record.httpBaseUrl,
-      wsBaseUrl: record.wsBaseUrl,
-    },
-  });
-  const connection = createEnvironmentConnection({
-    kind: "saved",
-    knownEnvironment: {
-      ...knownEnvironment,
-      environmentId: record.environmentId,
-    },
-    client,
-    refreshMetadata: async () => {
-      await refreshSavedEnvironmentMetadata(record, bearerToken, client);
-    },
-    onConfigSnapshot: (config) => {
-      useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
-        descriptor: config.environment,
-        serverConfig: config,
-      });
-    },
-    onWelcome: (payload) => {
-      useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
-        descriptor: payload.environment,
-      });
-    },
-    ...createEnvironmentConnectionHandlers(),
-  });
-
-  registerConnection(connection);
+  const nextConnection = (async () => {
+    let activeRecord = record;
+    let roleHint = options?.role ?? null;
+    let bearerToken =
+      options?.bearerToken ?? (await readSavedEnvironmentBearerToken(record.environmentId));
+    if (!bearerToken) {
+      if (record.desktopSsh) {
+        const issued = await issueDesktopSshBearerSession(record);
+        activeRecord = issued.record;
+        bearerToken = issued.bearerToken;
+        roleHint = issued.role;
+      } else {
+        useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
+          authState: "requires-auth",
+          role: null,
+          connectionState: "disconnected",
+          lastError: "Saved environment is missing its saved credential. Pair it again.",
+          lastErrorAt: isoNow(),
+        });
+        throw new Error("Saved environment is missing its saved credential.");
+      }
+    } else {
+      const prepared = await prepareSavedEnvironmentRecordForConnection(record);
+      activeRecord = prepared.record;
+    }
 
-  try {
-    await refreshSavedEnvironmentMetadata(
-      record,
-      bearerToken,
+    const activeBearerToken = bearerToken;
+    const client =
+      options?.client ??
+      createSavedEnvironmentClient(activeRecord.environmentId, activeBearerToken);
+    const knownEnvironment = createKnownEnvironment({
+      id: activeRecord.environmentId,
+      label: activeRecord.label,
+      source: "manual",
+      target: {
+        httpBaseUrl: activeRecord.httpBaseUrl,
+        wsBaseUrl: activeRecord.wsBaseUrl,
+      },
+    });
+    const connection = createEnvironmentConnection({
+      kind: "saved",
+      knownEnvironment: {
+        ...knownEnvironment,
+        environmentId: activeRecord.environmentId,
+      },
       client,
-      options?.role ?? null,
-      options?.serverConfig ?? null,
-    );
-    return connection;
-  } catch (error) {
-    setRuntimeError(record.environmentId, error);
-    await removeConnection(record.environmentId).catch(() => false);
-    throw error;
-  }
+      refreshMetadata: async () => {
+        await refreshSavedEnvironmentMetadata(
+          activeRecord.environmentId,
+          activeBearerToken,
+          client,
+        );
+      },
+      onConfigSnapshot: (config) => {
+        useSavedEnvironmentRuntimeStore.getState().patch(activeRecord.environmentId, {
+          descriptor: config.environment,
+          serverConfig: config,
+        });
+      },
+      onWelcome: (payload) => {
+        useSavedEnvironmentRuntimeStore.getState().patch(activeRecord.environmentId, {
+          descriptor: payload.environment,
+        });
+      },
+      ...createEnvironmentConnectionHandlers(),
+    });
+
+    registerConnection(connection);
+
+    try {
+      try {
+        await refreshSavedEnvironmentMetadata(
+          activeRecord.environmentId,
+          activeBearerToken,
+          client,
+          roleHint,
+          options?.serverConfig ?? null,
+        );
+      } catch (error) {
+        if (
+          !record.desktopSsh ||
+          !isRemoteEnvironmentAuthHttpError(error) ||
+          error.status !== 401
+        ) {
+          throw error;
+        }
+
+        const issued = await issueDesktopSshBearerSession(activeRecord);
+        activeRecord = issued.record;
+        bearerToken = issued.bearerToken;
+        roleHint = issued.role;
+        await removeConnection(activeRecord.environmentId).catch(() => false);
+        pendingSavedEnvironmentConnections.delete(activeRecord.environmentId);
+        return await ensureSavedEnvironmentConnection(activeRecord, {
+          bearerToken,
+          role: roleHint,
+          serverConfig: options?.serverConfig ?? null,
+        });
+      }
+      return connection;
+    } catch (error) {
+      setRuntimeError(activeRecord.environmentId, error);
+      await removeConnection(activeRecord.environmentId).catch(() => false);
+      throw error;
+    }
+  })();
+
+  pendingSavedEnvironmentConnections.set(record.environmentId, nextConnection);
+  return await nextConnection.finally(() => {
+    if (pendingSavedEnvironmentConnections.get(record.environmentId) === nextConnection) {
+      pendingSavedEnvironmentConnections.delete(record.environmentId);
+    }
+  });
 }
 
 async function syncSavedEnvironmentConnections(
@@ -1063,8 +1297,22 @@ export async function reconnectSavedEnvironment(environmentId: EnvironmentId): P
 
   setRuntimeConnecting(environmentId);
   try {
+    if (record.desktopSsh) {
+      await prepareSavedEnvironmentRecordForConnection(record);
+    }
     await connection.reconnect();
   } catch (error) {
+    if (record.desktopSsh) {
+      const issued = await issueDesktopSshBearerSession(
+        getSavedEnvironmentRecord(environmentId) ?? record,
+      );
+      await removeConnection(environmentId).catch(() => false);
+      await ensureSavedEnvironmentConnection(issued.record, {
+        bearerToken: issued.bearerToken,
+        role: issued.role,
+      });
+      return;
+    }
     setRuntimeError(environmentId, error);
     throw error;
   }
@@ -1081,33 +1329,40 @@ export async function addSavedEnvironment(input: {
   readonly pairingUrl?: string;
   readonly host?: string;
   readonly pairingCode?: string;
+  readonly desktopSsh?: DesktopSshEnvironmentTarget;
 }): Promise<SavedEnvironmentRecord> {
   const resolvedTarget = resolveRemotePairingTarget({
     ...(input.pairingUrl !== undefined ? { pairingUrl: input.pairingUrl } : {}),
     ...(input.host !== undefined ? { host: input.host } : {}),
     ...(input.pairingCode !== undefined ? { pairingCode: input.pairingCode } : {}),
   });
-  const descriptor = await fetchRemoteEnvironmentDescriptor({
-    httpBaseUrl: resolvedTarget.httpBaseUrl,
-  });
+  const descriptor = input.desktopSsh
+    ? await fetchDesktopSshEnvironmentDescriptor(resolvedTarget.httpBaseUrl)
+    : await fetchRemoteEnvironmentDescriptor({
+        httpBaseUrl: resolvedTarget.httpBaseUrl,
+      });
   const environmentId = descriptor.environmentId;
-
-  if (environmentConnections.has(environmentId)) {
-    throw new Error("This environment is already connected.");
-  }
-
-  const bearerSession = await bootstrapRemoteBearerSession({
-    httpBaseUrl: resolvedTarget.httpBaseUrl,
-    credential: resolvedTarget.credential,
-  });
+  const existingRecord =
+    getSavedEnvironmentRecord(environmentId) ??
+    findSavedEnvironmentRecordByDesktopSshTarget(input.desktopSsh);
+
+  const bearerSession = input.desktopSsh
+    ? await bootstrapDesktopSshBearerSession(resolvedTarget.httpBaseUrl, resolvedTarget.credential)
+    : await bootstrapRemoteBearerSession({
+        httpBaseUrl: resolvedTarget.httpBaseUrl,
+        credential: resolvedTarget.credential,
+      });
 
   const record: SavedEnvironmentRecord = {
     environmentId,
-    label: input.label.trim() || descriptor.label,
+    label: input.label.trim() || existingRecord?.label || descriptor.label,
     wsBaseUrl: resolvedTarget.wsBaseUrl,
     httpBaseUrl: resolvedTarget.httpBaseUrl,
-    createdAt: isoNow(),
+    createdAt: existingRecord?.createdAt ?? isoNow(),
     lastConnectedAt: isoNow(),
+    ...((input.desktopSsh ?? existingRecord?.desktopSsh)
+      ? { desktopSsh: input.desktopSsh ?? existingRecord?.desktopSsh }
+      : {}),
   };
 
   await persistSavedEnvironmentRecord(record);
@@ -1116,26 +1371,37 @@ export async function addSavedEnvironment(input: {
     bearerSession.sessionToken,
   );
   if (!didPersistBearerToken) {
-    await ensureLocalApi().persistence.setSavedEnvironmentRegistry(
-      listSavedEnvironmentRecords().map((entry) => ({
-        environmentId: entry.environmentId,
-        label: entry.label,
-        httpBaseUrl: entry.httpBaseUrl,
-        wsBaseUrl: entry.wsBaseUrl,
-        createdAt: entry.createdAt,
-        lastConnectedAt: entry.lastConnectedAt,
-      })),
-    );
+    await persistSavedEnvironmentRegistryRollback();
     throw new Error("Unable to persist saved environment credentials.");
   }
+  useSavedEnvironmentRegistryStore.getState().upsert(record);
+  await removeConnection(environmentId).catch(() => false);
   await ensureSavedEnvironmentConnection(record, {
     bearerToken: bearerSession.sessionToken,
     role: bearerSession.role,
   });
-  useSavedEnvironmentRegistryStore.getState().upsert(record);
   return record;
 }
 
+export async function connectDesktopSshEnvironment(
+  target: DesktopSshEnvironmentTarget,
+  options?: { label?: string },
+): Promise<SavedEnvironmentRecord> {
+  const bootstrap = await resolveDesktopSshEnvironmentBootstrap(target, {
+    issuePairingToken: true,
+  });
+  if (!bootstrap.pairingToken) {
+    throw new Error("Desktop SSH launch did not return a pairing token.");
+  }
+
+  return await addSavedEnvironment({
+    label: options?.label?.trim() || bootstrap.target.alias,
+    host: bootstrap.httpBaseUrl,
+    pairingCode: bootstrap.pairingToken,
+    desktopSsh: bootstrap.target,
+  });
+}
+
 export async function ensureEnvironmentConnectionBootstrapped(
   environmentId: EnvironmentId,
 ): Promise<void> {
@@ -1211,6 +1477,7 @@ export function startEnvironmentConnectionService(queryClient: QueryClient): ()
 export async function resetEnvironmentServiceForTests(): Promise<void> {
   stopActiveService();
   lastAppliedProjectionVersionByEnvironment.clear();
+  pendingSavedEnvironmentConnections.clear();
   for (const key of Array.from(threadDetailSubscriptions.keys())) {
     disposeThreadDetailSubscriptionByKey(key);
   }
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 9b46acdb99c..ab548c23d59 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -173,6 +173,24 @@ function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridg
     getSavedEnvironmentSecret: async () => null,
     setSavedEnvironmentSecret: async () => true,
     removeSavedEnvironmentSecret: async () => undefined,
+    discoverSshHosts: async () => [],
+    ensureSshEnvironment: async () => {
+      throw new Error("ensureSshEnvironment not implemented in test");
+    },
+    fetchSshEnvironmentDescriptor: async () => {
+      throw new Error("fetchSshEnvironmentDescriptor not implemented in test");
+    },
+    bootstrapSshBearerSession: async () => {
+      throw new Error("bootstrapSshBearerSession not implemented in test");
+    },
+    fetchSshSessionState: async () => {
+      throw new Error("fetchSshSessionState not implemented in test");
+    },
+    issueSshWebSocketToken: async () => {
+      throw new Error("issueSshWebSocketToken not implemented in test");
+    },
+    onSshPasswordPrompt: () => () => undefined,
+    resolveSshPasswordPrompt: async () => undefined,
     getServerExposureState: async () => ({
       mode: "local-only",
       endpointUrl: null,
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index df62be29dfa..7c38d77853a 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -13,6 +13,7 @@ import { QueryClient, useQueryClient } from "@tanstack/react-query";
 import { APP_DISPLAY_NAME } from "../branding";
 import { AppSidebarLayout } from "../components/AppSidebarLayout";
 import { CommandPalette } from "../components/CommandPalette";
+import { SshPasswordPromptDialog } from "../components/desktop/SshPasswordPromptDialog";
 import {
   SlowRpcAckToastCoordinator,
   WebSocketConnectionCoordinator,
@@ -145,6 +146,7 @@ function RootRouteView() {
         {primaryEnvironmentAuthenticated ? <AuthenticatedTracingBootstrap /> : null}
         {primaryEnvironmentAuthenticated ? <ServerStateBootstrap /> : null}
         <EnvironmentConnectionManagerBootstrap />
+        <SshPasswordPromptDialog />
         <HostedStaticEnvironmentBootstrap />
         {primaryEnvironmentAuthenticated ? <EventRouter /> : null}
         {primaryEnvironmentAuthenticated ? <WebSocketConnectionCoordinator /> : null}
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 5826238e942..c693f00bab0 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -53,8 +53,10 @@ import type {
   OrchestrationThreadStreamItem,
 } from "./orchestration.ts";
 import type { EnvironmentId } from "./baseSchemas.ts";
+import type { AuthBearerBootstrapResult, AuthSessionState, AuthWebSocketTokenResult } from "./auth.ts";
 import type { AdvertisedEndpoint } from "./remoteAccess.ts";
 import { EditorId } from "./editor.ts";
+import type { ExecutionEnvironmentDescriptor } from "./environment.ts";
 import { ServerSettings, type ClientSettings, type ServerSettingsPatch } from "./settings.ts";
 import type { SourceControlDiscoveryResult } from "./sourceControl.ts";
 
@@ -128,6 +130,33 @@ export interface DesktopEnvironmentBootstrap {
   bootstrapToken?: string;
 }
 
+export interface DesktopSshEnvironmentTarget {
+  alias: string;
+  hostname: string;
+  username: string | null;
+  port: number | null;
+}
+
+export type DesktopSshHostSource = "ssh-config" | "known-hosts";
+
+export interface DesktopDiscoveredSshHost extends DesktopSshEnvironmentTarget {
+  source: DesktopSshHostSource;
+}
+
+export interface DesktopSshEnvironmentBootstrap {
+  target: DesktopSshEnvironmentTarget;
+  httpBaseUrl: string;
+  wsBaseUrl: string;
+  pairingToken: string | null;
+}
+
+export interface DesktopSshPasswordPromptRequest {
+  requestId: string;
+  destination: string;
+  username: string | null;
+  prompt: string;
+}
+
 export interface PersistedSavedEnvironmentRecord {
   environmentId: EnvironmentId;
   label: string;
@@ -135,6 +164,7 @@ export interface PersistedSavedEnvironmentRecord {
   httpBaseUrl: string;
   createdAt: string;
   lastConnectedAt: string | null;
+  desktopSsh?: DesktopSshEnvironmentTarget;
 }
 
 export type DesktopServerExposureMode = "local-only" | "network-accessible";
@@ -161,6 +191,23 @@ export interface DesktopBridge {
   getSavedEnvironmentSecret: (environmentId: EnvironmentId) => Promise<string | null>;
   setSavedEnvironmentSecret: (environmentId: EnvironmentId, secret: string) => Promise<boolean>;
   removeSavedEnvironmentSecret: (environmentId: EnvironmentId) => Promise<void>;
+  discoverSshHosts: () => Promise<readonly DesktopDiscoveredSshHost[]>;
+  ensureSshEnvironment: (
+    target: DesktopSshEnvironmentTarget,
+    options?: { issuePairingToken?: boolean },
+  ) => Promise<DesktopSshEnvironmentBootstrap>;
+  fetchSshEnvironmentDescriptor: (httpBaseUrl: string) => Promise<ExecutionEnvironmentDescriptor>;
+  bootstrapSshBearerSession: (
+    httpBaseUrl: string,
+    credential: string,
+  ) => Promise<AuthBearerBootstrapResult>;
+  fetchSshSessionState: (httpBaseUrl: string, bearerToken: string) => Promise<AuthSessionState>;
+  issueSshWebSocketToken: (
+    httpBaseUrl: string,
+    bearerToken: string,
+  ) => Promise<AuthWebSocketTokenResult>;
+  onSshPasswordPrompt: (listener: (request: DesktopSshPasswordPromptRequest) => void) => () => void;
+  resolveSshPasswordPrompt: (requestId: string, password: string | null) => Promise<void>;
   getServerExposureState: () => Promise<DesktopServerExposureState>;
   setServerExposureMode: (mode: DesktopServerExposureMode) => Promise<DesktopServerExposureState>;
   getAdvertisedEndpoints: () => Promise<readonly AdvertisedEndpoint[]>;

From a6dbab6fe5f0144f438f5ec8544a35d82d7b010b Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 14 Apr 2026 15:44:54 -0700
Subject: [PATCH 15/74] Harden remote SSH environment recovery

- Validate SSH targets and known-host parsing more strictly
- Retry desktop SSH session refresh on auth failures
- Preserve saved registry state when bearer persistence fails
---
 apps/desktop/src/main.ts                      |  19 +-
 apps/desktop/src/sshEnvironment.test.ts       |  22 +-
 apps/desktop/src/sshEnvironment.ts            |  32 ++-
 .../settings/SettingsPanels.browser.tsx       |   2 +-
 apps/web/src/environments/runtime/catalog.ts  |   2 +-
 .../service.addSavedEnvironment.test.ts       | 248 +++++++++++++++++-
 apps/web/src/environments/runtime/service.ts  |  93 +++++--
 7 files changed, 359 insertions(+), 59 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 30e811ed746..5d0514518a9 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -511,9 +511,15 @@ function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarge
     return null;
   }
 
+  const alias = target.alias.trim();
+  const hostname = target.hostname.trim();
+  if (alias.length === 0 || hostname.length === 0) {
+    return null;
+  }
+
   return {
-    alias: target.alias.trim(),
-    hostname: target.hostname.trim(),
+    alias,
+    hostname,
     username: target.username?.trim() || null,
     port: target.port ?? null,
   };
@@ -602,12 +608,11 @@ async function fetchLoopbackSshJson<T>(input: {
   }
 
   if (!response.ok) {
-    throw new Error(
-      await readRemoteFetchErrorMessage(
-        response,
-        `SSH forwarded request failed (${response.status}).`,
-      ),
+    const message = await readRemoteFetchErrorMessage(
+      response,
+      `SSH forwarded request failed (${response.status}).`,
     );
+    throw new Error(`[ssh_http:${response.status}] ${message}`);
   }
 
   return (await response.json()) as T;
diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index fa5bca6a0db..d0f9c4c2d39 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -93,10 +93,19 @@ describe("sshEnvironment", () => {
           "|1|hashed|entry ssh-ed25519 CCCC",
           "@cert-authority *.example.com ssh-ed25519 DDDD",
           "[ssh.example.com]:2200 ssh-ed25519 EEEE",
+          "::1 ssh-ed25519 FFFF",
+          "2001:db8::1 ssh-ed25519 GGGG",
           "",
         ].join("\n"),
       ),
-    ).toEqual(["github.com", "gitlab-alias", "gitlab.com", "ssh.example.com"]);
+    ).toEqual([
+      "::1",
+      "2001:db8::1",
+      "github.com",
+      "gitlab-alias",
+      "gitlab.com",
+      "ssh.example.com",
+    ]);
   });
 
   it("parses resolved ssh config output into a target", () => {
@@ -177,12 +186,23 @@ describe("sshEnvironment", () => {
       port: 2222,
     } as const;
 
+    expect(__test.buildRemoteLaunchScript()).toContain(
+      '[ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null',
+    );
     expect(__test.buildRemoteLaunchScript()).toContain('"$RUNNER_FILE" serve --host 127.0.0.1');
     expect(__test.buildRemotePairingScript(target)).toContain(
       '"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json',
     );
   });
 
+  it("reads the last non-empty ssh output line", () => {
+    expect(
+      __test.getLastNonEmptyOutputLine(
+        ["Welcome to the host", "", '{"credential":"pairing-token"}', ""].join("\n"),
+      ),
+    ).toBe('{"credential":"pairing-token"}');
+  });
+
   it("detects ssh auth failures from common permission denied messages", () => {
     expect(
       __test.isSshAuthFailure(
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index e197645fd99..c62473ba066 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -180,8 +180,10 @@ function parseKnownHostsHostnames(raw: string): ReadonlyArray<string> {
     }
 
     for (const rawHost of hostField.split(",")) {
-      const host =
-        /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost)?.[1] ?? rawHost.replace(/:.*$/u, "").trim();
+      const bracketMatch = /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost);
+      const host = (
+        bracketMatch?.[1] ?? (rawHost.includes(":") ? rawHost : rawHost.replace(/:.*$/u, ""))
+      ).trim();
       if (host.length === 0 || hasSshPattern(host)) {
         continue;
       }
@@ -640,7 +642,7 @@ NODE
 }
 REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
 REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
-if [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
   :
 else
   REMOTE_PORT="$(pick_port)"
@@ -653,6 +655,16 @@ printf '{"remotePort":%s}\\n' "$REMOTE_PORT"
 `.trimStart();
 }
 
+function getLastNonEmptyOutputLine(stdout: string): string | null {
+  return (
+    stdout
+      .trim()
+      .split(/\r?\n/u)
+      .map((entry) => entry.trim())
+      .findLast((entry) => entry.length > 0) ?? null
+  );
+}
+
 function buildRemoteT3RunnerScript(): string {
   return [
     "#!/bin/sh",
@@ -698,11 +710,7 @@ async function launchOrReuseRemoteServer(
     ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
     ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
   });
-  const line = result.stdout
-    .trim()
-    .split(/\r?\n/u)
-    .map((entry) => entry.trim())
-    .findLast((entry) => entry.length > 0);
+  const line = getLastNonEmptyOutputLine(result.stdout);
   if (!line) {
     throw new Error("SSH launch did not return a remote port.");
   }
@@ -725,7 +733,12 @@ async function issueRemotePairingToken(
     ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
     ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
   });
-  const parsed = JSON.parse(result.stdout) as { credential?: unknown };
+  const line = getLastNonEmptyOutputLine(result.stdout);
+  if (!line) {
+    throw new Error("SSH pairing did not return a credential.");
+  }
+
+  const parsed = JSON.parse(line) as { credential?: unknown };
   if (typeof parsed.credential !== "string" || parsed.credential.trim().length === 0) {
     throw new Error("SSH pairing command returned an invalid credential.");
   }
@@ -1006,6 +1019,7 @@ export const __test = {
   buildRemoteT3RunnerScript,
   buildSshAskpassHelperDescriptor,
   buildSshChildEnvironment,
+  getLastNonEmptyOutputLine,
   isSshAuthFailure,
   collectSshConfigAliasesFromFile,
   parseKnownHostsHostnames,
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 801f23f5abf..feca8f0090c 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -116,7 +116,7 @@ const authAccessHarness = vi.hoisted(() => {
   };
 });
 
-const mockConnectDesktopSshEnvironment = vi.fn();
+const mockConnectDesktopSshEnvironment = vi.hoisted(() => vi.fn());
 
 vi.mock("../../environments/runtime", () => {
   const primaryConnection = {
diff --git a/apps/web/src/environments/runtime/catalog.ts b/apps/web/src/environments/runtime/catalog.ts
index 839e967ddfa..bf260ab5711 100644
--- a/apps/web/src/environments/runtime/catalog.ts
+++ b/apps/web/src/environments/runtime/catalog.ts
@@ -35,7 +35,7 @@ interface SavedEnvironmentRegistryStore extends SavedEnvironmentRegistryState {
 let savedEnvironmentRegistryHydrated = false;
 let savedEnvironmentRegistryHydrationPromise: Promise<void> | null = null;
 
-function toPersistedSavedEnvironmentRecord(
+export function toPersistedSavedEnvironmentRecord(
   record: SavedEnvironmentRecord,
 ): PersistedSavedEnvironmentRecord {
   return {
diff --git a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
index 54afb6c6f47..f1632087b95 100644
--- a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
+++ b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
@@ -1,18 +1,51 @@
 import { EnvironmentId } from "@t3tools/contracts";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
+let mockSavedRecords: Array<Record<string, unknown>> = [];
+
 const mockResolveRemotePairingTarget = vi.fn();
 const mockFetchRemoteEnvironmentDescriptor = vi.fn();
 const mockBootstrapRemoteBearerSession = vi.fn();
 const mockBootstrapSshBearerSession = vi.fn();
+const mockFetchSshSessionState = vi.fn();
 const mockPersistSavedEnvironmentRecord = vi.fn();
 const mockWriteSavedEnvironmentBearerToken = vi.fn();
 const mockSetSavedEnvironmentRegistry = vi.fn();
-const mockUpsert = vi.fn();
-const mockListSavedEnvironmentRecords = vi.fn();
+const mockGetSavedEnvironmentRecord = vi.fn((environmentId: EnvironmentId) => {
+  return mockSavedRecords.find((record) => record.environmentId === environmentId) ?? null;
+});
+const mockReadSavedEnvironmentBearerToken = vi.fn();
+const mockRemoveSavedEnvironmentBearerToken = vi.fn();
+const mockPatchRuntime = vi.fn();
+const mockClearRuntime = vi.fn();
+const mockRegistrySetState = vi.fn((next: { byId: Record<string, Record<string, unknown>> }) => {
+  mockSavedRecords = Object.values(next.byId);
+});
+const mockRemove = vi.fn((environmentId: EnvironmentId) => {
+  mockSavedRecords = mockSavedRecords.filter((record) => record.environmentId !== environmentId);
+});
+const mockMarkConnected = vi.fn((environmentId: EnvironmentId, connectedAt: string) => {
+  mockSavedRecords = mockSavedRecords.map((record) =>
+    record.environmentId === environmentId ? { ...record, lastConnectedAt: connectedAt } : record,
+  );
+});
+const mockUpsert = vi.fn((record: Record<string, unknown>) => {
+  mockSavedRecords = [
+    ...mockSavedRecords.filter((entry) => entry.environmentId !== record.environmentId),
+    record,
+  ];
+});
+const mockListSavedEnvironmentRecords = vi.fn(() => mockSavedRecords);
 const mockEnsureSshEnvironment = vi.fn();
 const mockFetchSshEnvironmentDescriptor = vi.fn();
+const mockToPersistedSavedEnvironmentRecord = vi.fn((record) => record);
 const mockCreateEnvironmentConnection = vi.fn();
+const mockClientGetConfig = vi.fn(async () => ({
+  environment: {
+    environmentId: EnvironmentId.make("environment-1"),
+    label: "Remote environment",
+  },
+}));
 
 vi.mock("../remote/target", () => ({
   resolveRemotePairingTarget: mockResolveRemotePairingTarget,
@@ -35,24 +68,27 @@ vi.mock("~/localApi", () => ({
 }));
 
 vi.mock("./catalog", () => ({
-  getSavedEnvironmentRecord: vi.fn(),
+  getSavedEnvironmentRecord: mockGetSavedEnvironmentRecord,
   hasSavedEnvironmentRegistryHydrated: vi.fn(),
   listSavedEnvironmentRecords: mockListSavedEnvironmentRecords,
   persistSavedEnvironmentRecord: mockPersistSavedEnvironmentRecord,
-  readSavedEnvironmentBearerToken: vi.fn(),
-  removeSavedEnvironmentBearerToken: vi.fn(),
+  readSavedEnvironmentBearerToken: mockReadSavedEnvironmentBearerToken,
+  removeSavedEnvironmentBearerToken: mockRemoveSavedEnvironmentBearerToken,
+  toPersistedSavedEnvironmentRecord: mockToPersistedSavedEnvironmentRecord,
   useSavedEnvironmentRegistryStore: {
     getState: () => ({
       upsert: mockUpsert,
-      remove: vi.fn(),
-      markConnected: vi.fn(),
+      remove: mockRemove,
+      markConnected: mockMarkConnected,
     }),
+    setState: mockRegistrySetState,
+    subscribe: vi.fn(() => () => {}),
   },
   useSavedEnvironmentRuntimeStore: {
     getState: () => ({
       ensure: vi.fn(),
-      patch: vi.fn(),
-      clear: vi.fn(),
+      patch: mockPatchRuntime,
+      clear: mockClearRuntime,
     }),
   },
   waitForSavedEnvironmentRegistryHydration: vi.fn(),
@@ -63,16 +99,32 @@ vi.mock("./connection", () => ({
   createEnvironmentConnection: mockCreateEnvironmentConnection,
 }));
 
+vi.mock("../../rpc/wsRpcClient", () => ({
+  createWsRpcClient: vi.fn(() => ({
+    server: {
+      getConfig: mockClientGetConfig,
+    },
+    orchestration: {
+      subscribeThread: vi.fn(() => () => {}),
+    },
+  })),
+}));
+
+vi.mock("../../rpc/wsTransport", () => ({
+  WsTransport: vi.fn(),
+}));
+
 describe("addSavedEnvironment", () => {
   beforeEach(() => {
     vi.resetModules();
     vi.clearAllMocks();
+    mockSavedRecords = [];
     vi.stubGlobal("window", {
       desktopBridge: {
         ensureSshEnvironment: mockEnsureSshEnvironment,
         fetchSshEnvironmentDescriptor: mockFetchSshEnvironmentDescriptor,
         bootstrapSshBearerSession: mockBootstrapSshBearerSession,
-        fetchSshSessionState: vi.fn(),
+        fetchSshSessionState: mockFetchSshSessionState,
         issueSshWebSocketToken: vi.fn(),
       },
     });
@@ -110,7 +162,12 @@ describe("addSavedEnvironment", () => {
     mockPersistSavedEnvironmentRecord.mockResolvedValue(undefined);
     mockWriteSavedEnvironmentBearerToken.mockResolvedValue(false);
     mockSetSavedEnvironmentRegistry.mockResolvedValue(undefined);
-    mockListSavedEnvironmentRecords.mockReturnValue([]);
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockRemoveSavedEnvironmentBearerToken.mockResolvedValue(undefined);
+    mockFetchSshSessionState.mockResolvedValue({
+      authenticated: true,
+      role: "owner",
+    });
     mockCreateEnvironmentConnection.mockImplementation(
       (input: { knownEnvironment: { environmentId: EnvironmentId }; client: unknown }) => ({
         kind: "saved",
@@ -122,6 +179,12 @@ describe("addSavedEnvironment", () => {
         dispose: async () => undefined,
       }),
     );
+    mockClientGetConfig.mockResolvedValue({
+      environment: {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+      },
+    });
     mockEnsureSshEnvironment.mockResolvedValue({
       target: {
         alias: "devbox",
@@ -157,6 +220,165 @@ describe("addSavedEnvironment", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("removes an older ssh record when the same target returns a new environment id", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    mockFetchSshEnvironmentDescriptor.mockResolvedValue({
+      environmentId: EnvironmentId.make("environment-2"),
+      label: "Remote environment",
+    });
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Old ssh environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+
+    const { addSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await expect(
+      addSavedEnvironment({
+        label: "Remote environment",
+        host: "http://127.0.0.1:3774/",
+        pairingCode: "ssh-pairing-code",
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      }),
+    ).resolves.toMatchObject({
+      environmentId: EnvironmentId.make("environment-2"),
+    });
+
+    expect(mockUpsert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        environmentId: EnvironmentId.make("environment-2"),
+      }),
+    );
+    expect(mockRemove).toHaveBeenCalledWith(EnvironmentId.make("environment-1"));
+    expect(mockRemoveSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("retries desktop ssh session refresh when the forwarded endpoint returns ssh_http 401", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    mockBootstrapSshBearerSession
+      .mockResolvedValueOnce({
+        sessionToken: "ssh-bearer-token",
+        role: "owner",
+      })
+      .mockResolvedValueOnce({
+        sessionToken: "ssh-bearer-token-2",
+        role: "owner",
+      });
+    mockFetchSshSessionState
+      .mockRejectedValueOnce(new Error("[ssh_http:401] Unauthorized"))
+      .mockResolvedValueOnce({
+        authenticated: true,
+        role: "owner",
+      });
+
+    const { connectDesktopSshEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await expect(
+      connectDesktopSshEnvironment({
+        alias: "devbox",
+        hostname: "devbox",
+        username: null,
+        port: null,
+      }),
+    ).resolves.toMatchObject({
+      environmentId: EnvironmentId.make("environment-1"),
+    });
+
+    expect(mockEnsureSshEnvironment).toHaveBeenCalled();
+    expect(mockBootstrapSshBearerSession).toHaveBeenCalledTimes(2);
+    expect(mockFetchSshSessionState).toHaveBeenCalledTimes(2);
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("marks desktop ssh reconnect failures as runtime errors when bearer recovery fails", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+
+    const connection = {
+      kind: "saved" as const,
+      environmentId: EnvironmentId.make("environment-1"),
+      knownEnvironment: {
+        environmentId: EnvironmentId.make("environment-1"),
+      },
+      client: {},
+      ensureBootstrapped: async () => undefined,
+      reconnect: vi.fn(async () => {
+        throw new Error("socket closed");
+      }),
+      dispose: async () => undefined,
+    };
+    mockCreateEnvironmentConnection.mockReturnValue(connection);
+
+    const { addSavedEnvironment, reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await addSavedEnvironment({
+      label: "Remote environment",
+      host: "http://127.0.0.1:3774/",
+      pairingCode: "ssh-pairing-code",
+      desktopSsh: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+    });
+
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(false);
+
+    await expect(reconnectSavedEnvironment(EnvironmentId.make("environment-1"))).rejects.toThrow(
+      "Unable to persist saved environment credentials.",
+    );
+
+    expect(mockPatchRuntime).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      expect.objectContaining({
+        connectionState: "error",
+        lastError: "Unable to persist saved environment credentials.",
+      }),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
   it("bootstraps a desktop ssh environment through the desktop bridge", async () => {
     mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
 
@@ -170,7 +392,9 @@ describe("addSavedEnvironment", () => {
         username: null,
         port: null,
       }),
-    ).rejects.toThrow();
+    ).resolves.toMatchObject({
+      environmentId: EnvironmentId.make("environment-1"),
+    });
 
     expect(mockEnsureSshEnvironment).toHaveBeenCalledWith(
       {
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index be20cbd1fd5..aa81a47b904 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -47,6 +47,7 @@ import {
   readSavedEnvironmentBearerToken,
   removeSavedEnvironmentBearerToken,
   type SavedEnvironmentRecord,
+  toPersistedSavedEnvironmentRecord,
   useSavedEnvironmentRegistryStore,
   useSavedEnvironmentRuntimeStore,
   waitForSavedEnvironmentRegistryHydration,
@@ -112,6 +113,7 @@ let needsProviderInvalidation = false;
 const THREAD_DETAIL_SUBSCRIPTION_IDLE_EVICTION_MS = 15 * 60 * 1000;
 const MAX_CACHED_THREAD_DETAIL_SUBSCRIPTIONS = 32;
 const NOOP = () => undefined;
+const SSH_HTTP_STATUS_RE = /^\[ssh_http:(\d+)\]\s/u;
 
 function compareAppliedProjectionVersion(
   left: { readonly sequence: number; readonly updatedAt: string | null },
@@ -495,16 +497,22 @@ function isoNow(): string {
   return new Date().toISOString();
 }
 
-function serializeSavedEnvironmentRecord(record: SavedEnvironmentRecord) {
-  return {
-    environmentId: record.environmentId,
-    label: record.label,
-    httpBaseUrl: record.httpBaseUrl,
-    wsBaseUrl: record.wsBaseUrl,
-    createdAt: record.createdAt,
-    lastConnectedAt: record.lastConnectedAt,
-    ...(record.desktopSsh ? { desktopSsh: record.desktopSsh } : {}),
-  } as const;
+function readSshHttpErrorStatus(error: unknown): number | null {
+  if (!(error instanceof Error)) {
+    return null;
+  }
+
+  const match = SSH_HTTP_STATUS_RE.exec(error.message);
+  if (!match) {
+    return null;
+  }
+
+  const parsed = Number.parseInt(match[1] ?? "", 10);
+  return Number.isInteger(parsed) ? parsed : null;
+}
+
+function isSshHttpAuthError(error: unknown, status: number): boolean {
+  return readSshHttpErrorStatus(error) === status;
 }
 
 function isDesktopSshTargetEqual(
@@ -537,10 +545,28 @@ function findSavedEnvironmentRecordByDesktopSshTarget(
   );
 }
 
-async function persistSavedEnvironmentRegistryRollback(): Promise<void> {
+function buildSavedEnvironmentRegistryById(
+  records: ReadonlyArray<SavedEnvironmentRecord>,
+): Record<EnvironmentId, SavedEnvironmentRecord> {
+  return Object.fromEntries(records.map((record) => [record.environmentId, record])) as Record<
+    EnvironmentId,
+    SavedEnvironmentRecord
+  >;
+}
+
+function snapshotSavedEnvironmentRegistry(): ReadonlyArray<SavedEnvironmentRecord> {
+  return listSavedEnvironmentRecords();
+}
+
+async function persistSavedEnvironmentRegistryRollback(
+  records: ReadonlyArray<SavedEnvironmentRecord>,
+): Promise<void> {
   await ensureLocalApi().persistence.setSavedEnvironmentRegistry(
-    listSavedEnvironmentRecords().map((entry) => serializeSavedEnvironmentRecord(entry)),
+    records.map((entry) => toPersistedSavedEnvironmentRecord(entry)),
   );
+  useSavedEnvironmentRegistryStore.setState({
+    byId: buildSavedEnvironmentRegistryById(records),
+  });
 }
 
 async function resolveDesktopSshEnvironmentBootstrap(
@@ -625,6 +651,7 @@ async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Pro
   readonly bearerToken: string;
   readonly role: AuthSessionRole | null;
 }> {
+  const registrySnapshot = snapshotSavedEnvironmentRegistry();
   const prepared = await prepareSavedEnvironmentRecordForConnection(record, {
     issuePairingToken: true,
   });
@@ -641,7 +668,7 @@ async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Pro
     bearerSession.sessionToken,
   );
   if (!didPersistBearerToken) {
-    await persistSavedEnvironmentRegistryRollback();
+    await persistSavedEnvironmentRegistryRollback(registrySnapshot);
     throw new Error("Unable to persist saved environment credentials.");
   }
 
@@ -1186,11 +1213,10 @@ async function ensureSavedEnvironmentConnection(
           options?.serverConfig ?? null,
         );
       } catch (error) {
-        if (
-          !record.desktopSsh ||
-          !isRemoteEnvironmentAuthHttpError(error) ||
-          error.status !== 401
-        ) {
+        const isAuthError = activeRecord.desktopSsh
+          ? isSshHttpAuthError(error, 401)
+          : isRemoteEnvironmentAuthHttpError(error) && error.status === 401;
+        if (!isAuthError) {
           throw error;
         }
 
@@ -1303,15 +1329,20 @@ export async function reconnectSavedEnvironment(environmentId: EnvironmentId): P
     await connection.reconnect();
   } catch (error) {
     if (record.desktopSsh) {
-      const issued = await issueDesktopSshBearerSession(
-        getSavedEnvironmentRecord(environmentId) ?? record,
-      );
-      await removeConnection(environmentId).catch(() => false);
-      await ensureSavedEnvironmentConnection(issued.record, {
-        bearerToken: issued.bearerToken,
-        role: issued.role,
-      });
-      return;
+      try {
+        const issued = await issueDesktopSshBearerSession(
+          getSavedEnvironmentRecord(environmentId) ?? record,
+        );
+        await removeConnection(environmentId).catch(() => false);
+        await ensureSavedEnvironmentConnection(issued.record, {
+          bearerToken: issued.bearerToken,
+          role: issued.role,
+        });
+        return;
+      } catch (recoveryError) {
+        setRuntimeError(environmentId, recoveryError);
+        throw recoveryError;
+      }
     }
     setRuntimeError(environmentId, error);
     throw error;
@@ -1342,9 +1373,12 @@ export async function addSavedEnvironment(input: {
         httpBaseUrl: resolvedTarget.httpBaseUrl,
       });
   const environmentId = descriptor.environmentId;
+  const registrySnapshot = snapshotSavedEnvironmentRegistry();
   const existingRecord =
     getSavedEnvironmentRecord(environmentId) ??
     findSavedEnvironmentRecordByDesktopSshTarget(input.desktopSsh);
+  const staleDesktopSshRecord =
+    existingRecord && existingRecord.environmentId !== environmentId ? existingRecord : null;
 
   const bearerSession = input.desktopSsh
     ? await bootstrapDesktopSshBearerSession(resolvedTarget.httpBaseUrl, resolvedTarget.credential)
@@ -1371,10 +1405,13 @@ export async function addSavedEnvironment(input: {
     bearerSession.sessionToken,
   );
   if (!didPersistBearerToken) {
-    await persistSavedEnvironmentRegistryRollback();
+    await persistSavedEnvironmentRegistryRollback(registrySnapshot);
     throw new Error("Unable to persist saved environment credentials.");
   }
   useSavedEnvironmentRegistryStore.getState().upsert(record);
+  if (staleDesktopSshRecord) {
+    await removeSavedEnvironment(staleDesktopSshRecord.environmentId);
+  }
   await removeConnection(environmentId).catch(() => false);
   await ensureSavedEnvironmentConnection(record, {
     bearerToken: bearerSession.sessionToken,

From c349ef52a93a7c4f7aad876cf4215646aeab54b7 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 14 Apr 2026 19:29:33 -0700
Subject: [PATCH 16/74] Respect desktop release channel for SSH bootstrap

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/main.ts                |  8 +++-
 apps/desktop/src/sshEnvironment.test.ts | 27 +++++++++--
 apps/desktop/src/sshEnvironment.ts      | 60 ++++++++++++++++++++-----
 3 files changed, 79 insertions(+), 16 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 5d0514518a9..24e1b5b48a2 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -65,7 +65,7 @@ import {
   resolveDesktopCoreAdvertisedEndpoints,
   resolveDesktopServerExposure,
 } from "./serverExposure.ts";
-import { DesktopSshEnvironmentManager } from "./sshEnvironment.ts";
+import { DesktopSshEnvironmentManager, resolveRemoteT3CliPackageSpec } from "./sshEnvironment.ts";
 import { syncShellEnvironment } from "./syncShellEnvironment.ts";
 import { waitForBackendStartupReady } from "./backendStartupReadiness.ts";
 import { getAutoUpdateDisabledReason, shouldBroadcastDownloadProgress } from "./updateState.ts";
@@ -860,6 +860,12 @@ async function requestSshPasswordFromRenderer(input: {
 
 const desktopSshEnvironmentManager = new DesktopSshEnvironmentManager({
   passwordProvider: requestSshPasswordFromRenderer,
+  resolveCliPackageSpec: () =>
+    resolveRemoteT3CliPackageSpec({
+      appVersion: app.getVersion(),
+      updateChannel: desktopSettings.updateChannel,
+      isDevelopment,
+    }),
 });
 
 function resolveUpdaterErrorContext(): DesktopUpdateErrorContext {
diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index d0f9c4c2d39..9fd8ab7830f 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -173,9 +173,24 @@ describe("sshEnvironment", () => {
     const script = __test.buildRemoteT3RunnerScript();
 
     expect(script).toContain('exec t3 "$@"');
-    expect(script).toContain('exec npx --yes t3 "$@"');
-    expect(script).toContain('exec npm exec --yes t3 -- "$@"');
-    expect(script).toContain("could not find npx or npm on PATH");
+    expect(script).toContain('exec npx --yes t3@latest "$@"');
+    expect(script).toContain('exec npm exec --yes t3@latest -- "$@"');
+    expect(script).toContain("could not install t3@latest");
+  });
+
+  it("resolves the remote t3 package spec from the desktop release channel", () => {
+    expect(
+      __test.resolveRemoteT3CliPackageSpec({
+        appVersion: "0.0.17",
+        updateChannel: "latest",
+      }),
+    ).toBe("t3@0.0.17");
+    expect(
+      __test.resolveRemoteT3CliPackageSpec({
+        appVersion: "0.0.17-nightly.20260415.44",
+        updateChannel: "nightly",
+      }),
+    ).toBe("t3@nightly");
   });
 
   it("uses the remote t3 runner for launch and pairing scripts", () => {
@@ -190,9 +205,15 @@ describe("sshEnvironment", () => {
       '[ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null',
     );
     expect(__test.buildRemoteLaunchScript()).toContain('"$RUNNER_FILE" serve --host 127.0.0.1');
+    expect(__test.buildRemoteLaunchScript({ packageSpec: "t3@nightly" })).toContain(
+      'exec npx --yes t3@nightly "$@"',
+    );
     expect(__test.buildRemotePairingScript(target)).toContain(
       '"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json',
     );
+    expect(__test.buildRemotePairingScript(target, { packageSpec: "t3@nightly" })).toContain(
+      'exec npm exec --yes t3@nightly -- "$@"',
+    );
   });
 
   it("reads the last non-empty ssh output line", () => {
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index c62473ba066..7144d8b8bd5 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -9,6 +9,7 @@ import type {
   DesktopDiscoveredSshHost,
   DesktopSshEnvironmentBootstrap,
   DesktopSshEnvironmentTarget,
+  DesktopUpdateChannel,
 } from "@t3tools/contracts";
 
 import { waitForHttpReady } from "./backendReadiness";
@@ -18,6 +19,7 @@ const REMOTE_PORT_SCAN_WINDOW = 200;
 const SSH_ASKPASS_DIR_NAME = "t3code-ssh-askpass";
 const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
 const SSH_READY_TIMEOUT_MS = 20_000;
+const STABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+$/u;
 
 interface SshTunnelEntry {
   readonly key: string;
@@ -60,6 +62,7 @@ interface DesktopSshPasswordRequest {
 
 interface DesktopSshEnvironmentManagerOptions {
   readonly passwordProvider?: (request: DesktopSshPasswordRequest) => Promise<string | null>;
+  readonly resolveCliPackageSpec?: () => string;
 }
 
 const NO_HOSTS = [] as const;
@@ -591,8 +594,8 @@ async function resolveDesktopSshTarget(alias: string): Promise<DesktopSshEnviron
   }
 }
 
-function buildRemoteLaunchScript(): string {
-  const runnerScript = buildRemoteT3RunnerScript();
+function buildRemoteLaunchScript(input?: { readonly packageSpec?: string }): string {
+  const runnerScript = buildRemoteT3RunnerScript(input);
   return `
 set -eu
 STATE_KEY="$1"
@@ -665,7 +668,25 @@ function getLastNonEmptyOutputLine(stdout: string): string | null {
   );
 }
 
-function buildRemoteT3RunnerScript(): string {
+export function resolveRemoteT3CliPackageSpec(input: {
+  readonly appVersion: string;
+  readonly updateChannel: DesktopUpdateChannel;
+  readonly isDevelopment?: boolean;
+}): string {
+  if (input.updateChannel === "nightly") {
+    return "t3@nightly";
+  }
+
+  const appVersion = input.appVersion.trim();
+  if (!input.isDevelopment && STABLE_T3_VERSION_PATTERN.test(appVersion)) {
+    return `t3@${appVersion}`;
+  }
+
+  return "t3@latest";
+}
+
+function buildRemoteT3RunnerScript(input?: { readonly packageSpec?: string }): string {
+  const packageSpec = input?.packageSpec?.trim() || "t3@latest";
   return [
     "#!/bin/sh",
     "set -eu",
@@ -673,18 +694,21 @@ function buildRemoteT3RunnerScript(): string {
     '  exec t3 "$@"',
     "fi",
     "if command -v npx >/dev/null 2>&1; then",
-    '  exec npx --yes t3 "$@"',
+    `  exec npx --yes ${packageSpec} "$@"`,
     "fi",
     "if command -v npm >/dev/null 2>&1; then",
-    '  exec npm exec --yes t3 -- "$@"',
+    `  exec npm exec --yes ${packageSpec} -- "$@"`,
     "fi",
-    "printf 'Remote host is missing the t3 CLI and could not find npx or npm on PATH.\\n' >&2",
+    `printf 'Remote host is missing the t3 CLI and could not install ${packageSpec} because npx and npm are unavailable on PATH.\\n' >&2`,
     "exit 1",
   ].join("\n");
 }
 
-function buildRemotePairingScript(target: DesktopSshEnvironmentTarget): string {
-  const runnerScript = buildRemoteT3RunnerScript();
+function buildRemotePairingScript(
+  target: DesktopSshEnvironmentTarget,
+  input?: { readonly packageSpec?: string },
+): string {
+  const runnerScript = buildRemoteT3RunnerScript(input);
   return `
 set -eu
 STATE_DIR="$HOME/.t3/ssh-launch/${remoteStateKey(target)}"
@@ -702,10 +726,11 @@ chmod 700 "$RUNNER_FILE"
 async function launchOrReuseRemoteServer(
   target: DesktopSshEnvironmentTarget,
   input?: SshAuthOptions,
+  runner?: { readonly packageSpec?: string },
 ): Promise<number> {
   const result = await runSshCommand(target, {
     remoteCommandArgs: ["sh", "-s", "--", remoteStateKey(target)],
-    stdin: buildRemoteLaunchScript(),
+    stdin: buildRemoteLaunchScript(runner),
     ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
     ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
     ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
@@ -725,10 +750,11 @@ async function launchOrReuseRemoteServer(
 async function issueRemotePairingToken(
   target: DesktopSshEnvironmentTarget,
   input?: SshAuthOptions,
+  runner?: { readonly packageSpec?: string },
 ): Promise<string> {
   const result = await runSshCommand(target, {
     remoteCommandArgs: ["sh", "-s"],
-    stdin: buildRemotePairingScript(target),
+    stdin: buildRemotePairingScript(target, runner),
     ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
     ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
     ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
@@ -898,6 +924,7 @@ export class DesktopSshEnvironmentManager {
   ): Promise<DesktopSshEnvironmentBootstrap> {
     const resolvedTarget = await resolveDesktopSshTarget(target.alias || target.hostname);
     const key = targetConnectionKey(resolvedTarget);
+    const packageSpec = this.options.resolveCliPackageSpec?.();
     let entry = this.tunnels.get(key) ?? null;
 
     if (entry !== null) {
@@ -912,7 +939,11 @@ export class DesktopSshEnvironmentManager {
 
     if (entry === null) {
       const remotePort = await this.runWithSshAuth(key, resolvedTarget, (authOptions) =>
-        launchOrReuseRemoteServer(resolvedTarget, authOptions),
+        launchOrReuseRemoteServer(
+          resolvedTarget,
+          authOptions,
+          packageSpec === undefined ? undefined : { packageSpec },
+        ),
       );
       const localPort = await findAvailableLocalPort();
       const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
@@ -993,7 +1024,11 @@ export class DesktopSshEnvironmentManager {
 
     const pairingToken = options?.issuePairingToken
       ? await this.runWithSshAuth(key, entry.target, (authOptions) =>
-          issueRemotePairingToken(entry.target, authOptions),
+          issueRemotePairingToken(
+            entry.target,
+            authOptions,
+            packageSpec === undefined ? undefined : { packageSpec },
+          ),
         )
       : null;
 
@@ -1017,6 +1052,7 @@ export const __test = {
   buildRemoteLaunchScript,
   buildRemotePairingScript,
   buildRemoteT3RunnerScript,
+  resolveRemoteT3CliPackageSpec,
   buildSshAskpassHelperDescriptor,
   buildSshChildEnvironment,
   getLastNonEmptyOutputLine,

From d2d82f5ac5c4eeeeeb3482a4bc96d6ee7eb559ab Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 14 Apr 2026 19:57:23 -0700
Subject: [PATCH 17/74] Pin nightly SSH bootstrap to desktop version

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/sshEnvironment.test.ts |  7 +++++++
 apps/desktop/src/sshEnvironment.ts      | 10 +++-------
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index 9fd8ab7830f..6d2ec174ec7 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -190,6 +190,13 @@ describe("sshEnvironment", () => {
         appVersion: "0.0.17-nightly.20260415.44",
         updateChannel: "nightly",
       }),
+    ).toBe("t3@0.0.17-nightly.20260415.44");
+    expect(
+      __test.resolveRemoteT3CliPackageSpec({
+        appVersion: "0.0.0-dev",
+        updateChannel: "nightly",
+        isDevelopment: true,
+      }),
     ).toBe("t3@nightly");
   });
 
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 7144d8b8bd5..d81c91a1735 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -19,7 +19,7 @@ const REMOTE_PORT_SCAN_WINDOW = 200;
 const SSH_ASKPASS_DIR_NAME = "t3code-ssh-askpass";
 const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
 const SSH_READY_TIMEOUT_MS = 20_000;
-const STABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+$/u;
+const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
 
 interface SshTunnelEntry {
   readonly key: string;
@@ -673,16 +673,12 @@ export function resolveRemoteT3CliPackageSpec(input: {
   readonly updateChannel: DesktopUpdateChannel;
   readonly isDevelopment?: boolean;
 }): string {
-  if (input.updateChannel === "nightly") {
-    return "t3@nightly";
-  }
-
   const appVersion = input.appVersion.trim();
-  if (!input.isDevelopment && STABLE_T3_VERSION_PATTERN.test(appVersion)) {
+  if (!input.isDevelopment && PUBLISHABLE_T3_VERSION_PATTERN.test(appVersion)) {
     return `t3@${appVersion}`;
   }
 
-  return "t3@latest";
+  return input.updateChannel === "nightly" ? "t3@nightly" : "t3@latest";
 }
 
 function buildRemoteT3RunnerScript(input?: { readonly packageSpec?: string }): string {

From 5ec3e43fd545dee13bc2cf9febe9f6dfcf0561f4 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 15 Apr 2026 13:38:58 -0700
Subject: [PATCH 18/74] Address SSH launch review feedback

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/sshEnvironment.test.ts       |  61 ++++++-
 apps/desktop/src/sshEnvironment.ts            | 153 +++++++++++++-----
 .../service.addSavedEnvironment.test.ts       | 137 +++++++++++++++-
 apps/web/src/environments/runtime/service.ts  |  46 ++++--
 4 files changed, 345 insertions(+), 52 deletions(-)

diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index 6d2ec174ec7..e26cc7da820 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -1,8 +1,9 @@
 import * as FS from "node:fs";
+import { EventEmitter } from "node:events";
 import * as OS from "node:os";
 import * as Path from "node:path";
 
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { __test, discoverDesktopSshHosts } from "./sshEnvironment";
 
@@ -93,6 +94,7 @@ describe("sshEnvironment", () => {
           "|1|hashed|entry ssh-ed25519 CCCC",
           "@cert-authority *.example.com ssh-ed25519 DDDD",
           "[ssh.example.com]:2200 ssh-ed25519 EEEE",
+          "port.example.com:22 ssh-ed25519 HHHH",
           "::1 ssh-ed25519 FFFF",
           "2001:db8::1 ssh-ed25519 GGGG",
           "",
@@ -104,10 +106,17 @@ describe("sshEnvironment", () => {
       "github.com",
       "gitlab-alias",
       "gitlab.com",
+      "port.example.com",
       "ssh.example.com",
     ]);
   });
 
+  it("expands tilde-prefixed ssh config include patterns", () => {
+    expect(
+      __test.resolveSshConfigIncludePattern("~/.ssh/config.d/*.conf", "/tmp/project", "/tmp/home"),
+    ).toBe("/tmp/home/.ssh/config.d/*.conf");
+  });
+
   it("parses resolved ssh config output into a target", () => {
     expect(
       __test.parseSshResolveOutput(
@@ -240,5 +249,55 @@ describe("sshEnvironment", () => {
       ),
     ).toBe(true);
     expect(__test.isSshAuthFailure(new Error("Connection timed out"))).toBe(false);
+    expect(__test.isSshAuthFailure(new Error("mkdir: Permission denied"))).toBe(false);
+  });
+
+  it("settles tunnel shutdown if the child exits before the exit listener attaches", async () => {
+    vi.useFakeTimers();
+
+    class RaceChildProcess extends EventEmitter {
+      exitCode: number | null = null;
+      signalCode: NodeJS.Signals | null = null;
+
+      override once(eventName: string | symbol, listener: (...args: any[]) => void): this {
+        if (eventName === "exit") {
+          this.exitCode = 0;
+          return this;
+        }
+        return super.once(eventName, listener);
+      }
+
+      kill(): boolean {
+        return true;
+      }
+    }
+
+    try {
+      const child = new RaceChildProcess();
+      const stopPromise = __test
+        .stopTunnel({
+          key: "devbox",
+          target: {
+            alias: "devbox",
+            hostname: "devbox.example.com",
+            username: "julius",
+            port: 22,
+          },
+          remotePort: 3773,
+          localPort: 3774,
+          httpBaseUrl: "http://127.0.0.1:3774/",
+          wsBaseUrl: "ws://127.0.0.1:3774/",
+          process: child as never,
+        })
+        .then(() => "resolved");
+
+      await vi.runAllTimersAsync();
+
+      await expect(Promise.race([stopPromise, Promise.resolve("pending")])).resolves.toBe(
+        "resolved",
+      );
+    } finally {
+      vi.useRealTimers();
+    }
   });
 });
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index d81c91a1735..ed20e840baa 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -80,6 +80,21 @@ function splitDirectiveArgs(value: string): ReadonlyArray<string> {
     .filter((entry) => entry.length > 0);
 }
 
+function expandHomePath(input: string, homeDir: string = OS.homedir()): string {
+  return input.replace(/^~(?=$|\/|\\)/u, homeDir);
+}
+
+function resolveSshConfigIncludePattern(
+  includePattern: string,
+  directory: string,
+  homeDir: string = OS.homedir(),
+): string {
+  const expandedPattern = expandHomePath(includePattern, homeDir);
+  return Path.isAbsolute(expandedPattern)
+    ? expandedPattern
+    : Path.resolve(directory, expandedPattern);
+}
+
 function hasSshPattern(value: string): boolean {
   return value.includes("*") || value.includes("?") || value.startsWith("!");
 }
@@ -138,9 +153,7 @@ function collectSshConfigAliasesFromFile(
     const normalizedDirective = directive.toLowerCase();
     if (normalizedDirective === "include") {
       for (const includePattern of rawArgs) {
-        const resolvedPattern = Path.isAbsolute(includePattern)
-          ? includePattern
-          : Path.resolve(directory, includePattern);
+        const resolvedPattern = resolveSshConfigIncludePattern(includePattern, directory);
         for (const includedPath of expandGlob(resolvedPattern)) {
           for (const alias of collectSshConfigAliasesFromFile(includedPath, visited)) {
             aliases.add(alias);
@@ -165,6 +178,21 @@ function collectSshConfigAliasesFromFile(
   return [...aliases].toSorted((left, right) => left.localeCompare(right));
 }
 
+function normalizeKnownHostsHostname(rawHost: string): string {
+  const bracketMatch = /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost);
+  if (bracketMatch?.[1]) {
+    return bracketMatch[1];
+  }
+
+  if (!rawHost.includes(":")) {
+    return rawHost;
+  }
+
+  const firstColonIndex = rawHost.indexOf(":");
+  const lastColonIndex = rawHost.lastIndexOf(":");
+  return firstColonIndex === lastColonIndex ? rawHost.slice(0, lastColonIndex) : rawHost;
+}
+
 function parseKnownHostsHostnames(raw: string): ReadonlyArray<string> {
   const hostnames = new Set<string>();
 
@@ -183,10 +211,7 @@ function parseKnownHostsHostnames(raw: string): ReadonlyArray<string> {
     }
 
     for (const rawHost of hostField.split(",")) {
-      const bracketMatch = /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost);
-      const host = (
-        bracketMatch?.[1] ?? (rawHost.includes(":") ? rawHost : rawHost.replace(/:.*$/u, ""))
-      ).trim();
+      const host = normalizeKnownHostsHostname(rawHost).trim();
       if (host.length === 0 || hasSshPattern(host)) {
         continue;
       }
@@ -482,8 +507,13 @@ function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): stri
 
 function isSshAuthFailure(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
-  return /permission denied|authentication failed|keyboard-interactive/u.test(
-    message.toLowerCase(),
+  const normalized = message.toLowerCase();
+  return (
+    /permission denied \((?:publickey|password|keyboard-interactive|hostbased|gssapi-with-mic)[^)]+\)/u.test(
+      normalized,
+    ) ||
+    /authentication failed/u.test(normalized) ||
+    /too many authentication failures/u.test(normalized)
   );
 }
 
@@ -776,6 +806,7 @@ async function stopTunnel(entry: SshTunnelEntry): Promise<void> {
   await new Promise<void>((resolve) => {
     let settled = false;
     let forceKillTimer: ReturnType<typeof setTimeout> | null = null;
+    let hardStopTimer: ReturnType<typeof setTimeout> | null = null;
 
     const settle = () => {
       if (settled) {
@@ -786,6 +817,9 @@ async function stopTunnel(entry: SshTunnelEntry): Promise<void> {
       if (forceKillTimer) {
         clearTimeout(forceKillTimer);
       }
+      if (hardStopTimer) {
+        clearTimeout(hardStopTimer);
+      }
       resolve();
     };
 
@@ -794,11 +828,22 @@ async function stopTunnel(entry: SshTunnelEntry): Promise<void> {
     };
 
     child.once("exit", onExit);
-    child.kill("SIGTERM");
+    if (child.exitCode !== null || child.signalCode !== null) {
+      settle();
+      return;
+    }
+    if (!child.kill("SIGTERM")) {
+      settle();
+      return;
+    }
     forceKillTimer = setTimeout(() => {
       if (child.exitCode === null && child.signalCode === null) {
         child.kill("SIGKILL");
       }
+      hardStopTimer = setTimeout(() => {
+        settle();
+      }, 1_000);
+      hardStopTimer.unref();
     }, TUNNEL_SHUTDOWN_TIMEOUT_MS);
     forceKillTimer.unref();
   });
@@ -840,10 +885,17 @@ export async function discoverDesktopSshHosts(input?: {
 
 export class DesktopSshEnvironmentManager {
   private readonly tunnels = new Map<string, SshTunnelEntry>();
+  private readonly pendingTunnelEntries = new Map<string, Promise<SshTunnelEntry>>();
   private readonly authSecrets = new Map<string, string>();
 
   constructor(private readonly options: DesktopSshEnvironmentManagerOptions = {}) {}
 
+  private deleteTunnelIfCurrent(entry: SshTunnelEntry): void {
+    if (this.tunnels.get(entry.key) === entry) {
+      this.tunnels.delete(entry.key);
+    }
+  }
+
   private async promptForPassword(
     target: DesktopSshEnvironmentTarget,
     attempt: number,
@@ -921,19 +973,50 @@ export class DesktopSshEnvironmentManager {
     const resolvedTarget = await resolveDesktopSshTarget(target.alias || target.hostname);
     const key = targetConnectionKey(resolvedTarget);
     const packageSpec = this.options.resolveCliPackageSpec?.();
+    const entry = await this.ensureTunnelEntry(key, resolvedTarget, packageSpec);
+
+    const pairingToken = options?.issuePairingToken
+      ? await this.runWithSshAuth(key, entry.target, (authOptions) =>
+          issueRemotePairingToken(
+            entry.target,
+            authOptions,
+            packageSpec === undefined ? undefined : { packageSpec },
+          ),
+        )
+      : null;
+
+    return {
+      target: entry.target,
+      httpBaseUrl: entry.httpBaseUrl,
+      wsBaseUrl: entry.wsBaseUrl,
+      pairingToken,
+    };
+  }
+
+  private async ensureTunnelEntry(
+    key: string,
+    resolvedTarget: DesktopSshEnvironmentTarget,
+    packageSpec?: string,
+  ): Promise<SshTunnelEntry> {
     let entry = this.tunnels.get(key) ?? null;
 
     if (entry !== null) {
       try {
         await waitForHttpReady(entry.httpBaseUrl, { timeoutMs: 2_000 });
+        return entry;
       } catch {
         await stopTunnel(entry).catch(() => undefined);
-        this.tunnels.delete(key);
+        this.deleteTunnelIfCurrent(entry);
         entry = null;
       }
     }
 
-    if (entry === null) {
+    const pending = this.pendingTunnelEntries.get(key);
+    if (pending) {
+      return await pending;
+    }
+
+    const nextEntry = (async () => {
       const remotePort = await this.runWithSshAuth(key, resolvedTarget, (authOptions) =>
         launchOrReuseRemoteServer(
           resolvedTarget,
@@ -944,7 +1027,7 @@ export class DesktopSshEnvironmentManager {
       const localPort = await findAvailableLocalPort();
       const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
       const wsBaseUrl = `ws://127.0.0.1:${localPort}/`;
-      entry = await this.runWithSshAuth(key, resolvedTarget, async (authOptions) => {
+      return await this.runWithSshAuth(key, resolvedTarget, async (authOptions) => {
         const process = ChildProcess.spawn(
           "ssh",
           [
@@ -972,7 +1055,7 @@ export class DesktopSshEnvironmentManager {
             stdio: "pipe",
           },
         );
-        const nextEntry: SshTunnelEntry = {
+        const tunnelEntry: SshTunnelEntry = {
           key,
           target: resolvedTarget,
           remotePort,
@@ -988,11 +1071,11 @@ export class DesktopSshEnvironmentManager {
             stderr += chunk;
           });
           process.once("error", (error) => {
-            this.tunnels.delete(key);
+            this.deleteTunnelIfCurrent(tunnelEntry);
             reject(error);
           });
           process.once("exit", (code) => {
-            this.tunnels.delete(key);
+            this.deleteTunnelIfCurrent(tunnelEntry);
             reject(
               new Error(
                 normalizeSshErrorMessage(
@@ -1006,39 +1089,29 @@ export class DesktopSshEnvironmentManager {
             .then(() => resolve())
             .catch((error) => reject(error));
         });
-        this.tunnels.set(key, nextEntry);
+        this.tunnels.set(key, tunnelEntry);
         try {
           await tunnelReady;
-          return nextEntry;
+          return tunnelEntry;
         } catch (error) {
-          await stopTunnel(nextEntry).catch(() => undefined);
-          this.tunnels.delete(key);
+          await stopTunnel(tunnelEntry).catch(() => undefined);
+          this.deleteTunnelIfCurrent(tunnelEntry);
           throw error;
         }
       });
-    }
-
-    const pairingToken = options?.issuePairingToken
-      ? await this.runWithSshAuth(key, entry.target, (authOptions) =>
-          issueRemotePairingToken(
-            entry.target,
-            authOptions,
-            packageSpec === undefined ? undefined : { packageSpec },
-          ),
-        )
-      : null;
-
-    return {
-      target: entry.target,
-      httpBaseUrl: entry.httpBaseUrl,
-      wsBaseUrl: entry.wsBaseUrl,
-      pairingToken,
-    };
+    })();
+    this.pendingTunnelEntries.set(key, nextEntry);
+    return await nextEntry.finally(() => {
+      if (this.pendingTunnelEntries.get(key) === nextEntry) {
+        this.pendingTunnelEntries.delete(key);
+      }
+    });
   }
 
   async dispose(): Promise<void> {
     const entries = [...this.tunnels.values()];
     this.tunnels.clear();
+    this.pendingTunnelEntries.clear();
     await Promise.all(entries.map((entry) => stopTunnel(entry).catch(() => undefined)));
   }
 }
@@ -1054,6 +1127,10 @@ export const __test = {
   getLastNonEmptyOutputLine,
   isSshAuthFailure,
   collectSshConfigAliasesFromFile,
+  expandHomePath,
+  normalizeKnownHostsHostname,
   parseKnownHostsHostnames,
   parseSshResolveOutput,
+  resolveSshConfigIncludePattern,
+  stopTunnel,
 };
diff --git a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
index f1632087b95..a6ee6c5d222 100644
--- a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
+++ b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
@@ -6,6 +6,9 @@ let mockSavedRecords: Array<Record<string, unknown>> = [];
 const mockResolveRemotePairingTarget = vi.fn();
 const mockFetchRemoteEnvironmentDescriptor = vi.fn();
 const mockBootstrapRemoteBearerSession = vi.fn();
+const mockFetchRemoteSessionState = vi.fn();
+const mockIsRemoteEnvironmentAuthHttpError = vi.fn((_: unknown) => false);
+const mockResolveRemoteWebSocketConnectionUrl = vi.fn();
 const mockBootstrapSshBearerSession = vi.fn();
 const mockFetchSshSessionState = vi.fn();
 const mockPersistSavedEnvironmentRecord = vi.fn();
@@ -54,9 +57,9 @@ vi.mock("../remote/target", () => ({
 vi.mock("../remote/api", () => ({
   bootstrapRemoteBearerSession: mockBootstrapRemoteBearerSession,
   fetchRemoteEnvironmentDescriptor: mockFetchRemoteEnvironmentDescriptor,
-  fetchRemoteSessionState: vi.fn(),
-  isRemoteEnvironmentAuthHttpError: vi.fn(() => false),
-  resolveRemoteWebSocketConnectionUrl: vi.fn(),
+  fetchRemoteSessionState: mockFetchRemoteSessionState,
+  isRemoteEnvironmentAuthHttpError: mockIsRemoteEnvironmentAuthHttpError,
+  resolveRemoteWebSocketConnectionUrl: mockResolveRemoteWebSocketConnectionUrl,
 }));
 
 vi.mock("~/localApi", () => ({
@@ -151,6 +154,14 @@ describe("addSavedEnvironment", () => {
       sessionToken: "bearer-token",
       role: "owner",
     });
+    mockFetchRemoteSessionState.mockResolvedValue({
+      authenticated: true,
+      role: "owner",
+    });
+    mockIsRemoteEnvironmentAuthHttpError.mockReturnValue(false);
+    mockResolveRemoteWebSocketConnectionUrl.mockResolvedValue(
+      "wss://remote.example.com/?wsToken=remote-token",
+    );
     mockFetchSshEnvironmentDescriptor.mockResolvedValue({
       environmentId: EnvironmentId.make("environment-1"),
       label: "Remote environment",
@@ -220,6 +231,37 @@ describe("addSavedEnvironment", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("restores unrelated saved environments when credential persistence rollback runs", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-existing"),
+        label: "Existing environment",
+        httpBaseUrl: "https://existing.example.com/",
+        wsBaseUrl: "wss://existing.example.com/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+      },
+    ];
+
+    const { addSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await expect(
+      addSavedEnvironment({
+        label: "Remote environment",
+        host: "remote.example.com",
+        pairingCode: "123456",
+      }),
+    ).rejects.toThrow("Unable to persist saved environment credentials.");
+
+    expect(mockSetSavedEnvironmentRegistry).toHaveBeenCalledWith([
+      expect.objectContaining({
+        environmentId: EnvironmentId.make("environment-existing"),
+      }),
+    ]);
+
+    await resetEnvironmentServiceForTests();
+  });
+
   it("removes an older ssh record when the same target returns a new environment id", async () => {
     mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
     mockFetchSshEnvironmentDescriptor.mockResolvedValue({
@@ -313,6 +355,95 @@ describe("addSavedEnvironment", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("does not attempt desktop ssh bearer recovery for non-ssh saved environments", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    const authError = {
+      status: 401,
+      message: "Unauthorized",
+    };
+    mockFetchRemoteSessionState.mockRejectedValueOnce(authError);
+    mockIsRemoteEnvironmentAuthHttpError.mockImplementation(
+      (error: unknown) => error === authError,
+    );
+
+    const { addSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await expect(
+      addSavedEnvironment({
+        label: "Remote environment",
+        host: "remote.example.com",
+        pairingCode: "123456",
+      }),
+    ).rejects.toThrow("Saved environment credential expired. Pair it again.");
+
+    expect(mockEnsureSshEnvironment).not.toHaveBeenCalled();
+    expect(mockBootstrapSshBearerSession).not.toHaveBeenCalled();
+    expect(mockRemoveSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("only registers the retried ssh connection after bearer re-issuance succeeds", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    mockBootstrapSshBearerSession
+      .mockResolvedValueOnce({
+        sessionToken: "ssh-bearer-token",
+        role: "owner",
+      })
+      .mockResolvedValueOnce({
+        sessionToken: "ssh-bearer-token-2",
+        role: "owner",
+      });
+    mockFetchSshSessionState
+      .mockRejectedValueOnce(new Error("[ssh_http:401] Unauthorized"))
+      .mockResolvedValueOnce({
+        authenticated: true,
+        role: "owner",
+      });
+
+    const createdConnections: Array<{
+      readonly environmentId: EnvironmentId;
+      readonly dispose: ReturnType<typeof vi.fn>;
+    }> = [];
+    mockCreateEnvironmentConnection.mockImplementation(
+      (input: { knownEnvironment: { environmentId: EnvironmentId }; client: unknown }) => {
+        const connection = {
+          kind: "saved" as const,
+          environmentId: input.knownEnvironment.environmentId,
+          knownEnvironment: input.knownEnvironment,
+          client: input.client,
+          ensureBootstrapped: async () => undefined,
+          reconnect: async () => undefined,
+          dispose: vi.fn(async () => undefined),
+        };
+        createdConnections.push(connection);
+        return connection;
+      },
+    );
+
+    const {
+      connectDesktopSshEnvironment,
+      listEnvironmentConnections,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    await connectDesktopSshEnvironment({
+      alias: "devbox",
+      hostname: "devbox",
+      username: null,
+      port: null,
+    });
+
+    expect(createdConnections).toHaveLength(2);
+    expect(createdConnections[0]?.dispose).toHaveBeenCalledTimes(1);
+    expect(listEnvironmentConnections()).toHaveLength(1);
+    expect(listEnvironmentConnections()[0]).toBe(createdConnections[1]);
+
+    await resetEnvironmentServiceForTests();
+  });
+
   it("marks desktop ssh reconnect failures as runtime errors when bearer recovery fails", async () => {
     mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
 
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index aa81a47b904..1ff8b662afd 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -554,18 +554,36 @@ function buildSavedEnvironmentRegistryById(
   >;
 }
 
-function snapshotSavedEnvironmentRegistry(): ReadonlyArray<SavedEnvironmentRecord> {
-  return listSavedEnvironmentRecords();
+type SavedEnvironmentRegistrySnapshot = ReadonlyMap<EnvironmentId, SavedEnvironmentRecord | null>;
+
+function snapshotSavedEnvironmentRegistry(
+  environmentIds: ReadonlyArray<EnvironmentId>,
+): SavedEnvironmentRegistrySnapshot {
+  return new Map(
+    environmentIds.map((environmentId) => [
+      environmentId,
+      getSavedEnvironmentRecord(environmentId) ?? null,
+    ]),
+  );
 }
 
 async function persistSavedEnvironmentRegistryRollback(
-  records: ReadonlyArray<SavedEnvironmentRecord>,
+  snapshot: SavedEnvironmentRegistrySnapshot,
 ): Promise<void> {
+  const byId = buildSavedEnvironmentRegistryById(listSavedEnvironmentRecords());
+  for (const [environmentId, record] of snapshot) {
+    if (record) {
+      byId[environmentId] = record;
+      continue;
+    }
+    delete byId[environmentId];
+  }
+  const records = Object.values(byId);
   await ensureLocalApi().persistence.setSavedEnvironmentRegistry(
     records.map((entry) => toPersistedSavedEnvironmentRecord(entry)),
   );
   useSavedEnvironmentRegistryStore.setState({
-    byId: buildSavedEnvironmentRegistryById(records),
+    byId,
   });
 }
 
@@ -651,7 +669,7 @@ async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Pro
   readonly bearerToken: string;
   readonly role: AuthSessionRole | null;
 }> {
-  const registrySnapshot = snapshotSavedEnvironmentRegistry();
+  const registrySnapshot = snapshotSavedEnvironmentRegistry([record.environmentId]);
   const prepared = await prepareSavedEnvironmentRecordForConnection(record, {
     issuePairingToken: true,
   });
@@ -1201,8 +1219,6 @@ async function ensureSavedEnvironmentConnection(
       ...createEnvironmentConnectionHandlers(),
     });
 
-    registerConnection(connection);
-
     try {
       try {
         await refreshSavedEnvironmentMetadata(
@@ -1219,12 +1235,18 @@ async function ensureSavedEnvironmentConnection(
         if (!isAuthError) {
           throw error;
         }
+        if (!activeRecord.desktopSsh) {
+          await removeSavedEnvironmentBearerToken(activeRecord.environmentId);
+          throw new Error("Saved environment credential expired. Pair it again.", {
+            cause: error,
+          });
+        }
 
         const issued = await issueDesktopSshBearerSession(activeRecord);
         activeRecord = issued.record;
         bearerToken = issued.bearerToken;
         roleHint = issued.role;
-        await removeConnection(activeRecord.environmentId).catch(() => false);
+        await connection.dispose().catch(() => undefined);
         pendingSavedEnvironmentConnections.delete(activeRecord.environmentId);
         return await ensureSavedEnvironmentConnection(activeRecord, {
           bearerToken,
@@ -1232,10 +1254,14 @@ async function ensureSavedEnvironmentConnection(
           serverConfig: options?.serverConfig ?? null,
         });
       }
+      registerConnection(connection);
       return connection;
     } catch (error) {
       setRuntimeError(activeRecord.environmentId, error);
-      await removeConnection(activeRecord.environmentId).catch(() => false);
+      const removed = await removeConnection(activeRecord.environmentId).catch(() => false);
+      if (!removed) {
+        await connection.dispose().catch(() => undefined);
+      }
       throw error;
     }
   })();
@@ -1373,7 +1399,7 @@ export async function addSavedEnvironment(input: {
         httpBaseUrl: resolvedTarget.httpBaseUrl,
       });
   const environmentId = descriptor.environmentId;
-  const registrySnapshot = snapshotSavedEnvironmentRegistry();
+  const registrySnapshot = snapshotSavedEnvironmentRegistry([environmentId]);
   const existingRecord =
     getSavedEnvironmentRecord(environmentId) ??
     findSavedEnvironmentRecordByDesktopSshTarget(input.desktopSsh);

From afb00cf257eb7984b1e11a39dc30b488a22f7ef2 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 15 Apr 2026 14:45:08 -0700
Subject: [PATCH 19/74] Use nightly remote T3 CLI in development

- Resolve dev remote package specs to `t3@nightly`
- Cover the dev fallback in sshEnvironment tests
---
 apps/desktop/src/sshEnvironment.test.ts | 7 +++++++
 apps/desktop/src/sshEnvironment.ts      | 4 ++++
 2 files changed, 11 insertions(+)

diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index e26cc7da820..2b4f0cadc88 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -207,6 +207,13 @@ describe("sshEnvironment", () => {
         isDevelopment: true,
       }),
     ).toBe("t3@nightly");
+    expect(
+      __test.resolveRemoteT3CliPackageSpec({
+        appVersion: "0.0.0-dev",
+        updateChannel: "latest",
+        isDevelopment: true,
+      }),
+    ).toBe("t3@nightly");
   });
 
   it("uses the remote t3 runner for launch and pairing scripts", () => {
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index ed20e840baa..249f8bbda3a 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -708,6 +708,10 @@ export function resolveRemoteT3CliPackageSpec(input: {
     return `t3@${appVersion}`;
   }
 
+  if (input.isDevelopment) {
+    return "t3@nightly";
+  }
+
   return input.updateChannel === "nightly" ? "t3@nightly" : "t3@latest";
 }
 

From 5f143204383d0ef57d02dfff658a62ce109173b4 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 15 Apr 2026 15:52:00 -0700
Subject: [PATCH 20/74] Improve SSH launch diagnostics

- surface stdout when remote launch or pairing fails
- report parse errors and invalid remote port or credential values
---
 apps/desktop/src/sshEnvironment.ts | 46 ++++++++++++++++++++++++------
 1 file changed, 37 insertions(+), 9 deletions(-)

diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 249f8bbda3a..bdca2f7cda2 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -678,7 +678,11 @@ REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
 if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
   :
 else
-  REMOTE_PORT="$(pick_port)"
+  REMOTE_PORT="$(pick_port)" || true
+  if [ -z "$REMOTE_PORT" ]; then
+    printf 'Failed to find an available port on the remote host. Ensure node is available on PATH.\\n' >&2
+    exit 1
+  fi
   nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
   REMOTE_PID="$!"
   printf '%s\\n' "$REMOTE_PID" >"$PID_FILE"
@@ -767,12 +771,24 @@ async function launchOrReuseRemoteServer(
   });
   const line = getLastNonEmptyOutputLine(result.stdout);
   if (!line) {
-    throw new Error("SSH launch did not return a remote port.");
+    throw new Error(
+      `SSH launch did not return a remote port. stdout=${JSON.stringify(result.stdout)}`,
+    );
   }
 
-  const parsed = JSON.parse(line) as { remotePort?: unknown };
+  let parsed: { remotePort?: unknown };
+  try {
+    parsed = JSON.parse(line) as { remotePort?: unknown };
+  } catch (cause) {
+    throw new Error(
+      `SSH launch returned unparseable output. line=${JSON.stringify(line)} stdout=${JSON.stringify(result.stdout)}`,
+      { cause },
+    );
+  }
   if (typeof parsed.remotePort !== "number" || !Number.isInteger(parsed.remotePort)) {
-    throw new Error("SSH launch returned an invalid remote port.");
+    throw new Error(
+      `SSH launch returned an invalid remote port. parsed=${JSON.stringify(parsed)} stdout=${JSON.stringify(result.stdout)}`,
+    );
   }
   return parsed.remotePort;
 }
@@ -789,14 +805,26 @@ async function issueRemotePairingToken(
     ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
     ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
   });
-  const line = getLastNonEmptyOutputLine(result.stdout);
-  if (!line) {
-    throw new Error("SSH pairing did not return a credential.");
+  const stdout = result.stdout.trim();
+  if (!stdout) {
+    throw new Error(
+      `SSH pairing did not return a credential. stdout=${JSON.stringify(result.stdout)}`,
+    );
   }
 
-  const parsed = JSON.parse(line) as { credential?: unknown };
+  let parsed: { credential?: unknown };
+  try {
+    parsed = JSON.parse(stdout) as { credential?: unknown };
+  } catch (cause) {
+    throw new Error(
+      `SSH pairing returned unparseable output. stdout=${JSON.stringify(result.stdout)}`,
+      { cause },
+    );
+  }
   if (typeof parsed.credential !== "string" || parsed.credential.trim().length === 0) {
-    throw new Error("SSH pairing command returned an invalid credential.");
+    throw new Error(
+      `SSH pairing command returned an invalid credential. parsed=${JSON.stringify(parsed)} stdout=${JSON.stringify(result.stdout)}`,
+    );
   }
   return parsed.credential;
 }

From 30bdfb4779a2122e97cc92014e57886c9e9a05e1 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 15 Apr 2026 17:06:00 -0700
Subject: [PATCH 21/74] Tighten SSH setup dialog scrolling

- Add a capped scroll area for discovered SSH hosts
- Keep the manual SSH form always visible and simplify the dialog layout
- Ensure the scroll area viewport respects inherited max height
---
 .../settings/ConnectionsSettings.tsx          | 192 ++++++++----------
 apps/web/src/components/ui/scroll-area.tsx    |   2 +-
 2 files changed, 88 insertions(+), 106 deletions(-)

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 061feb4add5..848c8370933 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -32,7 +32,7 @@ import {
   DialogTitle,
   DialogTrigger,
 } from "../ui/dialog";
-import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../ui/collapsible";
+import { ScrollArea } from "../ui/scroll-area";
 import {
   AlertDialog,
   AlertDialogClose,
@@ -1175,7 +1175,6 @@ export function ConnectionsSettings() {
   const [savedBackendSshHost, setSavedBackendSshHost] = useState("");
   const [savedBackendSshUsername, setSavedBackendSshUsername] = useState("");
   const [savedBackendSshPort, setSavedBackendSshPort] = useState("");
-  const [isManualSshFormOpen, setIsManualSshFormOpen] = useState(false);
   const [savedBackendError, setSavedBackendError] = useState<string | null>(null);
   const [isAddingSavedBackend, setIsAddingSavedBackend] = useState(false);
   const [reconnectingSavedEnvironmentId, setReconnectingSavedEnvironmentId] =
@@ -1322,7 +1321,7 @@ export function ConnectionsSettings() {
         setSavedBackendSshHost("");
         setSavedBackendSshUsername("");
         setSavedBackendSshPort("");
-        setIsManualSshFormOpen(false);
+
         setAddBackendDialogOpen(false);
         toastManager.add({
           type: "success",
@@ -1331,7 +1330,7 @@ export function ConnectionsSettings() {
         });
       } catch (error) {
         const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
-        setIsManualSshFormOpen(true);
+
         setSavedBackendError(message);
         toastManager.add({
           type: "error",
@@ -1363,7 +1362,6 @@ export function ConnectionsSettings() {
       setSavedBackendSshHost("");
       setSavedBackendSshUsername("");
       setSavedBackendSshPort("");
-      setIsManualSshFormOpen(false);
       setAddBackendDialogOpen(false);
       toastManager.add({
         type: "success",
@@ -1875,7 +1873,6 @@ export function ConnectionsSettings() {
               setAddBackendDialogOpen(open);
               if (!open) {
                 setSavedBackendError(null);
-                setIsManualSshFormOpen(false);
               }
             }}
           >
@@ -1887,7 +1884,7 @@ export function ConnectionsSettings() {
                 </Button>
               }
             />
-            <DialogPopup className="sm:max-w-3xl">
+            <DialogPopup className="max-h-[80dvh] sm:max-w-3xl">
               <DialogHeader>
                 <DialogTitle>Add Environment</DialogTitle>
                 <DialogDescription>Pair another environment to this client.</DialogDescription>
@@ -2046,124 +2043,109 @@ export function ConnectionsSettings() {
                       {discoveredSshHostsError ? (
                         <p className="text-xs text-destructive">{discoveredSshHostsError}</p>
                       ) : null}
-                      <div>
-                        {discoveredSshHosts.map((target) => (
-                          <DesktopSshHostRow
-                            key={`${target.alias}:${target.hostname}:${target.port ?? ""}`}
-                            target={target}
-                            savedRecord={savedDesktopSshEnvironmentsByAlias[target.alias] ?? null}
-                            connectingHostAlias={connectingSshHostAlias}
-                            onConnect={(nextTarget) => void handleConnectSshHost(nextTarget)}
-                          />
-                        ))}
-                        {hasLoadedDiscoveredSshHosts &&
-                        !isLoadingDiscoveredSshHosts &&
-                        discoveredSshHosts.length === 0 ? (
-                          <div className={ITEM_ROW_CLASSNAME}>
-                            <p className="text-xs text-muted-foreground">
-                              No SSH hosts were discovered from <code>~/.ssh/config</code> or{" "}
-                              <code>known_hosts</code>.
-                            </p>
-                          </div>
-                        ) : null}
-                      </div>
+                      <ScrollArea scrollFade className="max-h-64">
+                        <div>
+                          {discoveredSshHosts.map((target) => (
+                            <DesktopSshHostRow
+                              key={`${target.alias}:${target.hostname}:${target.port ?? ""}`}
+                              target={target}
+                              savedRecord={savedDesktopSshEnvironmentsByAlias[target.alias] ?? null}
+                              connectingHostAlias={connectingSshHostAlias}
+                              onConnect={(nextTarget) => void handleConnectSshHost(nextTarget)}
+                            />
+                          ))}
+                          {hasLoadedDiscoveredSshHosts &&
+                          !isLoadingDiscoveredSshHosts &&
+                          discoveredSshHosts.length === 0 ? (
+                            <div className={ITEM_ROW_CLASSNAME}>
+                              <p className="text-xs text-muted-foreground">
+                                No SSH hosts were discovered from <code>~/.ssh/config</code> or{" "}
+                                <code>known_hosts</code>.
+                              </p>
+                            </div>
+                          ) : null}
+                        </div>
+                      </ScrollArea>
                       {savedBackendError ? (
                         <p className="text-xs text-destructive">{savedBackendError}</p>
                       ) : null}
-                      <Collapsible open={isManualSshFormOpen} onOpenChange={setIsManualSshFormOpen}>
-                        <CollapsibleTrigger
-                          className={cn(
-                            "flex w-full items-center justify-between gap-3 rounded-md border border-border/60 px-4 py-3 text-left transition-colors hover:bg-muted/35",
-                            isManualSshFormOpen && "bg-muted/20",
-                          )}
-                        >
-                          <div className="min-w-0">
-                            <p className="text-sm font-medium text-foreground">
-                              Enter a host manually
-                            </p>
-                            <p className="text-xs text-muted-foreground">
-                              Use an alias or enter host, username, and port directly.
-                            </p>
-                          </div>
-                          <ChevronDownIcon
-                            className={cn(
-                              "size-4 shrink-0 text-muted-foreground transition-transform duration-200",
-                              isManualSshFormOpen && "rotate-180",
-                            )}
-                          />
-                        </CollapsibleTrigger>
-                        <CollapsibleContent className="pt-4">
-                          <div className="space-y-3">
+                      <div className="border-t border-border/60 pt-4">
+                        <h3 className="mb-1 text-sm font-medium text-foreground">
+                          Enter a host manually
+                        </h3>
+                        <p className="mb-3 text-xs text-muted-foreground">
+                          Use an alias or enter host, username, and port directly.
+                        </p>
+                        <div className="space-y-3">
+                          <label className="block">
+                            <span className="mb-1.5 block text-xs font-medium text-foreground">
+                              Label
+                            </span>
+                            <Input
+                              value={savedBackendLabel}
+                              onChange={(event) => setSavedBackendLabel(event.target.value)}
+                              placeholder="My backend (optional)"
+                              disabled={isAddingSavedBackend}
+                              spellCheck={false}
+                            />
+                          </label>
+                          <label className="block">
+                            <span className="mb-1.5 block text-xs font-medium text-foreground">
+                              SSH host or alias
+                            </span>
+                            <Input
+                              value={savedBackendSshHost}
+                              onChange={(event) => setSavedBackendSshHost(event.target.value)}
+                              placeholder="devbox or devbox.example.com"
+                              disabled={isAddingSavedBackend}
+                              spellCheck={false}
+                            />
+                          </label>
+                          <div className="grid gap-3 sm:grid-cols-2">
                             <label className="block">
                               <span className="mb-1.5 block text-xs font-medium text-foreground">
-                                Label
+                                Username
                               </span>
                               <Input
-                                value={savedBackendLabel}
-                                onChange={(event) => setSavedBackendLabel(event.target.value)}
-                                placeholder="My backend (optional)"
+                                value={savedBackendSshUsername}
+                                onChange={(event) =>
+                                  setSavedBackendSshUsername(event.target.value)
+                                }
+                                placeholder="julius"
                                 disabled={isAddingSavedBackend}
                                 spellCheck={false}
                               />
                             </label>
                             <label className="block">
                               <span className="mb-1.5 block text-xs font-medium text-foreground">
-                                SSH host or alias
+                                Port
                               </span>
                               <Input
-                                value={savedBackendSshHost}
-                                onChange={(event) => setSavedBackendSshHost(event.target.value)}
-                                placeholder="devbox or devbox.example.com"
+                                value={savedBackendSshPort}
+                                onChange={(event) => setSavedBackendSshPort(event.target.value)}
+                                placeholder="22"
+                                inputMode="numeric"
                                 disabled={isAddingSavedBackend}
                                 spellCheck={false}
                               />
                             </label>
-                            <div className="grid gap-3 sm:grid-cols-2">
-                              <label className="block">
-                                <span className="mb-1.5 block text-xs font-medium text-foreground">
-                                  Username
-                                </span>
-                                <Input
-                                  value={savedBackendSshUsername}
-                                  onChange={(event) =>
-                                    setSavedBackendSshUsername(event.target.value)
-                                  }
-                                  placeholder="julius"
-                                  disabled={isAddingSavedBackend}
-                                  spellCheck={false}
-                                />
-                              </label>
-                              <label className="block">
-                                <span className="mb-1.5 block text-xs font-medium text-foreground">
-                                  Port
-                                </span>
-                                <Input
-                                  value={savedBackendSshPort}
-                                  onChange={(event) => setSavedBackendSshPort(event.target.value)}
-                                  placeholder="22"
-                                  inputMode="numeric"
-                                  disabled={isAddingSavedBackend}
-                                  spellCheck={false}
-                                />
-                              </label>
-                            </div>
-                            <span className="block text-[11px] text-muted-foreground">
-                              Uses your existing SSH keys, agent, and config. Password and
-                              keyboard-interactive prompts open through your system SSH dialog when
-                              needed.
-                            </span>
-                            <Button
-                              variant="outline"
-                              className="w-full"
-                              disabled={isAddingSavedBackend}
-                              onClick={() => void handleAddSavedBackend()}
-                            >
-                              <PlusIcon className="size-3.5" />
-                              {isAddingSavedBackend ? "Connecting…" : "Connect SSH host"}
-                            </Button>
                           </div>
-                        </CollapsibleContent>
-                      </Collapsible>
+                          <span className="block text-[11px] text-muted-foreground">
+                            Uses your existing SSH keys, agent, and config. Password and
+                            keyboard-interactive prompts open through your system SSH dialog when
+                            needed.
+                          </span>
+                          <Button
+                            variant="outline"
+                            className="w-full"
+                            disabled={isAddingSavedBackend}
+                            onClick={() => void handleAddSavedBackend()}
+                          >
+                            <PlusIcon className="size-3.5" />
+                            {isAddingSavedBackend ? "Connecting…" : "Connect SSH host"}
+                          </Button>
+                        </div>
+                      </div>
                     </div>
                   )}
                   {savedBackendMode !== "ssh" && savedBackendError ? (
diff --git a/apps/web/src/components/ui/scroll-area.tsx b/apps/web/src/components/ui/scroll-area.tsx
index 4d38c6dd19a..37ffbb185a2 100644
--- a/apps/web/src/components/ui/scroll-area.tsx
+++ b/apps/web/src/components/ui/scroll-area.tsx
@@ -23,7 +23,7 @@ function ScrollArea({
     >
       <ScrollAreaPrimitive.Viewport
         className={cn(
-          "h-full overflow-y-auto overscroll-contain rounded-[inherit] outline-none transition-shadows focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-has-overflow-x:overscroll-x-contain",
+          "h-full max-h-[inherit] overflow-y-auto overscroll-contain rounded-[inherit] outline-none transition-shadows focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background data-has-overflow-x:overscroll-x-contain",
           scrollFade &&
             "mask-t-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-y-start)))] mask-b-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-y-end)))] mask-l-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-start)))] mask-r-from-[calc(100%-min(var(--fade-size),var(--scroll-area-overflow-x-end)))] [--fade-size:1.5rem]",
           scrollbarGutter && "[scrollbar-gutter:stable]",

From 4b788044cfbcafb1ca7373e68f125bbe605b4260 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 17 Apr 2026 11:45:35 -0700
Subject: [PATCH 22/74] Format settings and IPC imports

- No functional change
- Keep staged code style consistent
---
 apps/web/src/components/settings/ConnectionsSettings.tsx | 4 +---
 packages/contracts/src/ipc.ts                            | 6 +++++-
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 848c8370933..95e504207d9 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -2108,9 +2108,7 @@ export function ConnectionsSettings() {
                               </span>
                               <Input
                                 value={savedBackendSshUsername}
-                                onChange={(event) =>
-                                  setSavedBackendSshUsername(event.target.value)
-                                }
+                                onChange={(event) => setSavedBackendSshUsername(event.target.value)}
                                 placeholder="julius"
                                 disabled={isAddingSavedBackend}
                                 spellCheck={false}
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index c693f00bab0..9002a7cf10b 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -53,7 +53,11 @@ import type {
   OrchestrationThreadStreamItem,
 } from "./orchestration.ts";
 import type { EnvironmentId } from "./baseSchemas.ts";
-import type { AuthBearerBootstrapResult, AuthSessionState, AuthWebSocketTokenResult } from "./auth.ts";
+import type {
+  AuthBearerBootstrapResult,
+  AuthSessionState,
+  AuthWebSocketTokenResult,
+} from "./auth.ts";
 import type { AdvertisedEndpoint } from "./remoteAccess.ts";
 import { EditorId } from "./editor.ts";
 import type { ExecutionEnvironmentDescriptor } from "./environment.ts";

From f67c6dd56c32fa1fceefbc294b88186bc2ce9469 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 17 Apr 2026 14:00:44 -0700
Subject: [PATCH 23/74] Extract desktop SSH bridge into dedicated class

- Move SSH IPC handlers and password prompt state out of main.ts
- Keep SSH environment launch and auth flow owned by sshEnvironment.ts
---
 apps/desktop/src/main.ts           | 306 +--------------------------
 apps/desktop/src/sshEnvironment.ts | 326 +++++++++++++++++++++++++++++
 2 files changed, 335 insertions(+), 297 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 24e1b5b48a2..74baa16c54d 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -20,13 +20,7 @@ import {
 } from "electron";
 import type { MenuItemConstructorOptions, OpenDialogOptions } from "electron";
 import type {
-  AuthBearerBootstrapResult,
-  AuthSessionState,
-  AuthWebSocketTokenResult,
   ClientSettings,
-  DesktopSshPasswordPromptRequest,
-  ExecutionEnvironmentDescriptor,
-  DesktopSshEnvironmentTarget,
   DesktopTheme,
   DesktopAppBranding,
   DesktopServerExposureMode,
@@ -65,7 +59,7 @@ import {
   resolveDesktopCoreAdvertisedEndpoints,
   resolveDesktopServerExposure,
 } from "./serverExposure.ts";
-import { DesktopSshEnvironmentManager, resolveRemoteT3CliPackageSpec } from "./sshEnvironment.ts";
+import { DesktopSshEnvironmentBridge, resolveRemoteT3CliPackageSpec } from "./sshEnvironment.ts";
 import { syncShellEnvironment } from "./syncShellEnvironment.ts";
 import { waitForBackendStartupReady } from "./backendStartupReadiness.ts";
 import { getAutoUpdateDisabledReason, shouldBroadcastDownloadProgress } from "./updateState.ts";
@@ -111,14 +105,6 @@ const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-re
 const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:get-saved-environment-secret";
 const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secret";
 const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
-const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
-const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
-const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
-const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
-const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
-const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
-const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
-const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
 const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
@@ -177,7 +163,6 @@ function resolvePickFolderDefaultPath(rawOptions: unknown): string | undefined {
 }
 const DESKTOP_LOOPBACK_HOST = "127.0.0.1";
 const DESKTOP_REQUIRED_PORT_PROBE_HOSTS = ["0.0.0.0", "::"] as const;
-const SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
 const TITLEBAR_HEIGHT = 40;
 const TITLEBAR_COLOR = "#01000000"; // #00000000 does not work correctly on Linux
 const TITLEBAR_LIGHT_SYMBOL_COLOR = "#1f2937";
@@ -222,12 +207,6 @@ type LinuxDesktopNamedApp = Electron.App & {
   setDesktopName?: (desktopName: string) => void;
 };
 
-interface PendingSshPasswordPrompt {
-  readonly resolve: (password: string | null) => void;
-  readonly reject: (error: Error) => void;
-  readonly timeout: ReturnType<typeof setTimeout>;
-}
-
 let mainWindow: BrowserWindow | null = null;
 let backendProcess: ChildProcess.ChildProcess | null = null;
 let backendPort = 0;
@@ -251,7 +230,6 @@ let restoreStdIoCapture: (() => void) | null = null;
 let backendObservabilitySettings = readPersistedBackendObservabilitySettings();
 let desktopSettings = readDesktopSettings(DESKTOP_SETTINGS_PATH, app.getVersion());
 let desktopServerExposureMode: DesktopServerExposureMode = desktopSettings.serverExposureMode;
-const pendingSshPasswordPrompts = new Map<string, PendingSshPasswordPrompt>();
 
 let destructiveMenuIconCache: Electron.NativeImage | null | undefined;
 const expectedBackendExitChildren = new WeakSet<ChildProcess.ChildProcess>();
@@ -428,7 +406,7 @@ function relaunchDesktopApp(reason: string): void {
           `desktop relaunch backend shutdown warning message=${formatErrorMessage(error)}`,
         );
       })
-      .then(() => desktopSshEnvironmentManager.dispose().catch(() => undefined))
+      .then(() => desktopSshEnvironmentBridge.dispose().catch(() => undefined))
       .finally(() => {
         restoreStdIoCapture?.();
         if (isDevelopment) {
@@ -491,133 +469,6 @@ function getSafeTheme(rawTheme: unknown): DesktopTheme | null {
   return null;
 }
 
-function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarget | null {
-  if (typeof rawTarget !== "object" || rawTarget === null) {
-    return null;
-  }
-
-  const target = rawTarget as Partial<DesktopSshEnvironmentTarget>;
-  if (typeof target.alias !== "string" || typeof target.hostname !== "string") {
-    return null;
-  }
-  if (
-    target.username !== null &&
-    target.username !== undefined &&
-    typeof target.username !== "string"
-  ) {
-    return null;
-  }
-  if (target.port !== null && target.port !== undefined && !Number.isInteger(target.port)) {
-    return null;
-  }
-
-  const alias = target.alias.trim();
-  const hostname = target.hostname.trim();
-  if (alias.length === 0 || hostname.length === 0) {
-    return null;
-  }
-
-  return {
-    alias,
-    hostname,
-    username: target.username?.trim() || null,
-    port: target.port ?? null,
-  };
-}
-
-function isLoopbackHostname(hostname: string): boolean {
-  const normalized = hostname
-    .trim()
-    .toLowerCase()
-    .replace(/^\[(.*)\]$/, "$1");
-  return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
-}
-
-function resolveLoopbackSshHttpUrl(rawHttpBaseUrl: unknown, pathname: string): URL {
-  if (typeof rawHttpBaseUrl !== "string" || rawHttpBaseUrl.trim().length === 0) {
-    throw new Error("Invalid SSH forwarded http base URL.");
-  }
-
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawHttpBaseUrl);
-  } catch {
-    throw new Error("Invalid SSH forwarded http base URL.");
-  }
-
-  if (!isLoopbackHostname(baseUrl.hostname)) {
-    throw new Error("SSH desktop bridge only supports loopback forwarded URLs.");
-  }
-
-  const url = new URL(baseUrl.toString());
-  url.pathname = pathname;
-  url.search = "";
-  url.hash = "";
-  return url;
-}
-
-async function readRemoteFetchErrorMessage(
-  response: Response,
-  fallbackMessage: string,
-): Promise<string> {
-  const text = await response.text();
-  if (!text) {
-    return fallbackMessage;
-  }
-
-  try {
-    const parsed = JSON.parse(text) as { readonly error?: string };
-    if (typeof parsed.error === "string" && parsed.error.trim().length > 0) {
-      return parsed.error;
-    }
-  } catch {
-    // Fall back to the raw text below.
-  }
-
-  return text;
-}
-
-async function fetchLoopbackSshJson<T>(input: {
-  readonly httpBaseUrl: unknown;
-  readonly pathname: string;
-  readonly method?: "GET" | "POST";
-  readonly bearerToken?: unknown;
-  readonly body?: unknown;
-}): Promise<T> {
-  const requestUrl = resolveLoopbackSshHttpUrl(input.httpBaseUrl, input.pathname).toString();
-  const bearerToken =
-    typeof input.bearerToken === "string" && input.bearerToken.trim().length > 0
-      ? input.bearerToken
-      : null;
-
-  let response: Response;
-  try {
-    response = await fetch(requestUrl, {
-      method: input.method ?? "GET",
-      headers: {
-        ...(input.body !== undefined ? { "content-type": "application/json" } : {}),
-        ...(bearerToken ? { authorization: `Bearer ${bearerToken}` } : {}),
-      },
-      ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
-    });
-  } catch (error) {
-    throw new Error(
-      `Failed to reach SSH forwarded endpoint ${requestUrl} (${error instanceof Error ? error.message : String(error)}).`,
-      { cause: error },
-    );
-  }
-
-  if (!response.ok) {
-    const message = await readRemoteFetchErrorMessage(
-      response,
-      `SSH forwarded request failed (${response.status}).`,
-    );
-    throw new Error(`[ssh_http:${response.status}] ${message}`);
-  }
-
-  return (await response.json()) as T;
-}
-
 async function waitForBackendHttpReady(
   baseUrl: string,
   options?: Parameters<typeof waitForHttpReady>[1],
@@ -812,54 +663,8 @@ let updateInstallInFlight = false;
 let updaterConfigured = false;
 let updateState: DesktopUpdateState = initialUpdateState();
 
-function rejectPendingSshPasswordPrompts(message: string): void {
-  for (const [requestId, pending] of pendingSshPasswordPrompts) {
-    clearTimeout(pending.timeout);
-    pendingSshPasswordPrompts.delete(requestId);
-    pending.reject(new Error(message));
-  }
-}
-
-async function requestSshPasswordFromRenderer(input: {
-  readonly destination: string;
-  readonly username: string | null;
-  readonly prompt: string;
-}): Promise<string | null> {
-  const window = mainWindow;
-  if (!window || window.isDestroyed()) {
-    throw new Error("T3 Code window is not available for SSH authentication.");
-  }
-
-  const request: DesktopSshPasswordPromptRequest = {
-    requestId: Crypto.randomUUID(),
-    destination: input.destination,
-    username: input.username,
-    prompt: input.prompt,
-  };
-
-  return await new Promise<string | null>((resolve, reject) => {
-    const timeout = setTimeout(() => {
-      pendingSshPasswordPrompts.delete(request.requestId);
-      reject(new Error(`SSH authentication timed out for ${input.destination}.`));
-    }, SSH_PASSWORD_PROMPT_TIMEOUT_MS);
-    timeout.unref();
-
-    pendingSshPasswordPrompts.set(request.requestId, {
-      resolve,
-      reject,
-      timeout,
-    });
-
-    window.webContents.send(SSH_PASSWORD_PROMPT_CHANNEL, request);
-    if (window.isMinimized()) {
-      window.restore();
-    }
-    window.focus();
-  });
-}
-
-const desktopSshEnvironmentManager = new DesktopSshEnvironmentManager({
-  passwordProvider: requestSshPasswordFromRenderer,
+const desktopSshEnvironmentBridge = new DesktopSshEnvironmentBridge({
+  getMainWindow: () => mainWindow,
   resolveCliPackageSpec: () =>
     resolveRemoteT3CliPackageSpec({
       appVersion: app.getVersion(),
@@ -1886,100 +1691,7 @@ function registerIpcHandlers(): void {
     },
   );
 
-  ipcMain.removeHandler(DISCOVER_SSH_HOSTS_CHANNEL);
-  ipcMain.handle(DISCOVER_SSH_HOSTS_CHANNEL, async () =>
-    desktopSshEnvironmentManager.discoverHosts(),
-  );
-
-  ipcMain.removeHandler(ENSURE_SSH_ENVIRONMENT_CHANNEL);
-  ipcMain.handle(
-    ENSURE_SSH_ENVIRONMENT_CHANNEL,
-    async (_event, rawTarget: unknown, rawOptions: unknown) => {
-      const target = getSafeDesktopSshTarget(rawTarget);
-      if (!target) {
-        throw new Error("Invalid desktop SSH target.");
-      }
-
-      const issuePairingToken =
-        typeof rawOptions === "object" &&
-        rawOptions !== null &&
-        "issuePairingToken" in rawOptions &&
-        (rawOptions as { issuePairingToken?: unknown }).issuePairingToken === true;
-
-      return await desktopSshEnvironmentManager.ensureEnvironment(target, {
-        issuePairingToken,
-      });
-    },
-  );
-
-  ipcMain.removeHandler(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL);
-  ipcMain.handle(
-    FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL,
-    async (_event, rawHttpBaseUrl: unknown) =>
-      fetchLoopbackSshJson<ExecutionEnvironmentDescriptor>({
-        httpBaseUrl: rawHttpBaseUrl,
-        pathname: "/.well-known/t3/environment",
-      }),
-  );
-
-  ipcMain.removeHandler(BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL);
-  ipcMain.handle(
-    BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL,
-    async (_event, rawHttpBaseUrl: unknown, rawCredential: unknown) =>
-      fetchLoopbackSshJson<AuthBearerBootstrapResult>({
-        httpBaseUrl: rawHttpBaseUrl,
-        pathname: "/api/auth/bootstrap/bearer",
-        method: "POST",
-        body: {
-          credential: rawCredential,
-        },
-      }),
-  );
-
-  ipcMain.removeHandler(FETCH_SSH_SESSION_STATE_CHANNEL);
-  ipcMain.handle(
-    FETCH_SSH_SESSION_STATE_CHANNEL,
-    async (_event, rawHttpBaseUrl: unknown, rawBearerToken: unknown) =>
-      fetchLoopbackSshJson<AuthSessionState>({
-        httpBaseUrl: rawHttpBaseUrl,
-        pathname: "/api/auth/session",
-        bearerToken: rawBearerToken,
-      }),
-  );
-
-  ipcMain.removeHandler(ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL);
-  ipcMain.handle(
-    ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL,
-    async (_event, rawHttpBaseUrl: unknown, rawBearerToken: unknown) =>
-      fetchLoopbackSshJson<AuthWebSocketTokenResult>({
-        httpBaseUrl: rawHttpBaseUrl,
-        pathname: "/api/auth/ws-token",
-        method: "POST",
-        bearerToken: rawBearerToken,
-      }),
-  );
-
-  ipcMain.removeHandler(RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL);
-  ipcMain.handle(
-    RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL,
-    async (_event, rawRequestId: unknown, rawPassword: unknown) => {
-      if (typeof rawRequestId !== "string" || rawRequestId.trim().length === 0) {
-        throw new Error("Invalid SSH password prompt id.");
-      }
-      if (rawPassword !== null && typeof rawPassword !== "string") {
-        throw new Error("Invalid SSH password prompt response.");
-      }
-
-      const pending = pendingSshPasswordPrompts.get(rawRequestId);
-      if (!pending) {
-        throw new Error("SSH password prompt is no longer pending.");
-      }
-
-      clearTimeout(pending.timeout);
-      pendingSshPasswordPrompts.delete(rawRequestId);
-      pending.resolve(rawPassword);
-    },
-  );
+  desktopSshEnvironmentBridge.registerIpcHandlers(ipcMain);
 
   ipcMain.removeHandler(GET_SERVER_EXPOSURE_STATE_CHANNEL);
   ipcMain.handle(GET_SERVER_EXPOSURE_STATE_CHANNEL, async () => getDesktopServerExposureState());
@@ -2356,7 +2068,7 @@ function createWindow(): BrowserWindow {
   }
 
   window.on("closed", () => {
-    rejectPendingSshPasswordPrompts(
+    desktopSshEnvironmentBridge.cancelPendingPasswordPrompts(
       "SSH authentication was cancelled because the app window closed.",
     );
     if (mainWindow === window) {
@@ -2450,7 +2162,7 @@ app.on("before-quit", () => {
   clearUpdatePollTimer();
   cancelBackendReadinessWait();
   stopBackend();
-  void desktopSshEnvironmentManager.dispose().catch(() => undefined);
+  void desktopSshEnvironmentBridge.dispose().catch(() => undefined);
   restoreStdIoCapture?.();
 });
 
@@ -2500,7 +2212,7 @@ if (process.platform !== "win32") {
     clearUpdatePollTimer();
     cancelBackendReadinessWait();
     stopBackend();
-    void desktopSshEnvironmentManager.dispose().catch(() => undefined);
+    void desktopSshEnvironmentBridge.dispose().catch(() => undefined);
     restoreStdIoCapture?.();
     app.quit();
   });
@@ -2511,7 +2223,7 @@ if (process.platform !== "win32") {
     writeDesktopLogHeader("SIGTERM received");
     clearUpdatePollTimer();
     stopBackend();
-    void desktopSshEnvironmentManager.dispose().catch(() => undefined);
+    void desktopSshEnvironmentBridge.dispose().catch(() => undefined);
     restoreStdIoCapture?.();
     app.quit();
   });
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index bdca2f7cda2..7c423a7e79e 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -6,10 +6,15 @@ import * as Path from "node:path";
 import * as Net from "node:net";
 
 import type {
+  AuthBearerBootstrapResult,
+  AuthSessionState,
+  AuthWebSocketTokenResult,
   DesktopDiscoveredSshHost,
   DesktopSshEnvironmentBootstrap,
   DesktopSshEnvironmentTarget,
+  DesktopSshPasswordPromptRequest,
   DesktopUpdateChannel,
+  ExecutionEnvironmentDescriptor,
 } from "@t3tools/contracts";
 
 import { waitForHttpReady } from "./backendReadiness";
@@ -21,6 +26,16 @@ const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
 const SSH_READY_TIMEOUT_MS = 20_000;
 const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
 
+const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
+const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
+const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
+const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
+const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
+const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
+const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
+const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
+const DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
+
 interface SshTunnelEntry {
   readonly key: string;
   readonly target: DesktopSshEnvironmentTarget;
@@ -1148,6 +1163,317 @@ export class DesktopSshEnvironmentManager {
   }
 }
 
+function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarget | null {
+  if (typeof rawTarget !== "object" || rawTarget === null) {
+    return null;
+  }
+
+  const target = rawTarget as Partial<DesktopSshEnvironmentTarget>;
+  if (typeof target.alias !== "string" || typeof target.hostname !== "string") {
+    return null;
+  }
+  if (
+    target.username !== null &&
+    target.username !== undefined &&
+    typeof target.username !== "string"
+  ) {
+    return null;
+  }
+  if (target.port !== null && target.port !== undefined && !Number.isInteger(target.port)) {
+    return null;
+  }
+
+  const alias = target.alias.trim();
+  const hostname = target.hostname.trim();
+  if (alias.length === 0 || hostname.length === 0) {
+    return null;
+  }
+
+  return {
+    alias,
+    hostname,
+    username: target.username?.trim() || null,
+    port: target.port ?? null,
+  };
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname
+    .trim()
+    .toLowerCase()
+    .replace(/^\[(.*)\]$/, "$1");
+  return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
+}
+
+function resolveLoopbackSshHttpUrl(rawHttpBaseUrl: unknown, pathname: string): URL {
+  if (typeof rawHttpBaseUrl !== "string" || rawHttpBaseUrl.trim().length === 0) {
+    throw new Error("Invalid SSH forwarded http base URL.");
+  }
+
+  let baseUrl: URL;
+  try {
+    baseUrl = new URL(rawHttpBaseUrl);
+  } catch {
+    throw new Error("Invalid SSH forwarded http base URL.");
+  }
+
+  if (!isLoopbackHostname(baseUrl.hostname)) {
+    throw new Error("SSH desktop bridge only supports loopback forwarded URLs.");
+  }
+
+  const url = new URL(baseUrl.toString());
+  url.pathname = pathname;
+  url.search = "";
+  url.hash = "";
+  return url;
+}
+
+async function readRemoteFetchErrorMessage(
+  response: Response,
+  fallbackMessage: string,
+): Promise<string> {
+  const text = await response.text();
+  if (!text) {
+    return fallbackMessage;
+  }
+
+  try {
+    const parsed = JSON.parse(text) as { readonly error?: string };
+    if (typeof parsed.error === "string" && parsed.error.trim().length > 0) {
+      return parsed.error;
+    }
+  } catch {
+    // Fall back to the raw text below.
+  }
+
+  return text;
+}
+
+async function fetchLoopbackSshJson<T>(input: {
+  readonly httpBaseUrl: unknown;
+  readonly pathname: string;
+  readonly method?: "GET" | "POST";
+  readonly bearerToken?: unknown;
+  readonly body?: unknown;
+}): Promise<T> {
+  const requestUrl = resolveLoopbackSshHttpUrl(input.httpBaseUrl, input.pathname).toString();
+  const bearerToken =
+    typeof input.bearerToken === "string" && input.bearerToken.trim().length > 0
+      ? input.bearerToken
+      : null;
+
+  let response: Response;
+  try {
+    response = await fetch(requestUrl, {
+      method: input.method ?? "GET",
+      headers: {
+        ...(input.body !== undefined ? { "content-type": "application/json" } : {}),
+        ...(bearerToken ? { authorization: `Bearer ${bearerToken}` } : {}),
+      },
+      ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
+    });
+  } catch (error) {
+    throw new Error(
+      `Failed to reach SSH forwarded endpoint ${requestUrl} (${error instanceof Error ? error.message : String(error)}).`,
+      { cause: error },
+    );
+  }
+
+  if (!response.ok) {
+    const message = await readRemoteFetchErrorMessage(
+      response,
+      `SSH forwarded request failed (${response.status}).`,
+    );
+    throw new Error(`[ssh_http:${response.status}] ${message}`);
+  }
+
+  return (await response.json()) as T;
+}
+
+/** Minimal subset of Electron's BrowserWindow used by the SSH bridge. */
+export interface DesktopSshBridgeWindow {
+  isDestroyed(): boolean;
+  isMinimized(): boolean;
+  restore(): void;
+  focus(): void;
+  readonly webContents: {
+    send(channel: string, ...args: readonly unknown[]): void;
+  };
+}
+
+/** Minimal subset of Electron's ipcMain used by the SSH bridge. */
+export interface DesktopSshBridgeIpcMain {
+  removeHandler(channel: string): void;
+  handle(
+    channel: string,
+    listener: (event: unknown, ...args: readonly unknown[]) => unknown | Promise<unknown>,
+  ): void;
+}
+
+export interface DesktopSshEnvironmentBridgeOptions {
+  readonly getMainWindow: () => DesktopSshBridgeWindow | null;
+  readonly resolveCliPackageSpec: () => string;
+  readonly passwordPromptTimeoutMs?: number;
+}
+
+interface PendingSshPasswordPrompt {
+  readonly resolve: (password: string | null) => void;
+  readonly reject: (error: Error) => void;
+  readonly timeout: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Wires the SSH environment manager to Electron IPC, owning the renderer-facing
+ * password prompt state so `main.ts` only needs to register, cancel, and dispose.
+ */
+export class DesktopSshEnvironmentBridge {
+  private readonly options: DesktopSshEnvironmentBridgeOptions;
+  private readonly manager: DesktopSshEnvironmentManager;
+  private readonly pendingPrompts = new Map<string, PendingSshPasswordPrompt>();
+  private readonly passwordPromptTimeoutMs: number;
+
+  constructor(options: DesktopSshEnvironmentBridgeOptions) {
+    this.options = options;
+    this.passwordPromptTimeoutMs =
+      options.passwordPromptTimeoutMs ?? DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS;
+    this.manager = new DesktopSshEnvironmentManager({
+      passwordProvider: (request) => this.requestPasswordFromRenderer(request),
+      resolveCliPackageSpec: options.resolveCliPackageSpec,
+    });
+  }
+
+  registerIpcHandlers(ipcMain: DesktopSshBridgeIpcMain): void {
+    ipcMain.removeHandler(DISCOVER_SSH_HOSTS_CHANNEL);
+    ipcMain.handle(DISCOVER_SSH_HOSTS_CHANNEL, async () => this.manager.discoverHosts());
+
+    ipcMain.removeHandler(ENSURE_SSH_ENVIRONMENT_CHANNEL);
+    ipcMain.handle(ENSURE_SSH_ENVIRONMENT_CHANNEL, async (_event, rawTarget, rawOptions) => {
+      const target = getSafeDesktopSshTarget(rawTarget);
+      if (!target) {
+        throw new Error("Invalid desktop SSH target.");
+      }
+
+      const issuePairingToken =
+        typeof rawOptions === "object" &&
+        rawOptions !== null &&
+        "issuePairingToken" in rawOptions &&
+        (rawOptions as { issuePairingToken?: unknown }).issuePairingToken === true;
+
+      return await this.manager.ensureEnvironment(target, { issuePairingToken });
+    });
+
+    ipcMain.removeHandler(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL);
+    ipcMain.handle(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, async (_event, rawHttpBaseUrl) =>
+      fetchLoopbackSshJson<ExecutionEnvironmentDescriptor>({
+        httpBaseUrl: rawHttpBaseUrl,
+        pathname: "/.well-known/t3/environment",
+      }),
+    );
+
+    ipcMain.removeHandler(BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL);
+    ipcMain.handle(
+      BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL,
+      async (_event, rawHttpBaseUrl, rawCredential) =>
+        fetchLoopbackSshJson<AuthBearerBootstrapResult>({
+          httpBaseUrl: rawHttpBaseUrl,
+          pathname: "/api/auth/bootstrap/bearer",
+          method: "POST",
+          body: { credential: rawCredential },
+        }),
+    );
+
+    ipcMain.removeHandler(FETCH_SSH_SESSION_STATE_CHANNEL);
+    ipcMain.handle(
+      FETCH_SSH_SESSION_STATE_CHANNEL,
+      async (_event, rawHttpBaseUrl, rawBearerToken) =>
+        fetchLoopbackSshJson<AuthSessionState>({
+          httpBaseUrl: rawHttpBaseUrl,
+          pathname: "/api/auth/session",
+          bearerToken: rawBearerToken,
+        }),
+    );
+
+    ipcMain.removeHandler(ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL);
+    ipcMain.handle(
+      ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL,
+      async (_event, rawHttpBaseUrl, rawBearerToken) =>
+        fetchLoopbackSshJson<AuthWebSocketTokenResult>({
+          httpBaseUrl: rawHttpBaseUrl,
+          pathname: "/api/auth/ws-token",
+          method: "POST",
+          bearerToken: rawBearerToken,
+        }),
+    );
+
+    ipcMain.removeHandler(RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL);
+    ipcMain.handle(
+      RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL,
+      async (_event, rawRequestId, rawPassword) => {
+        if (typeof rawRequestId !== "string" || rawRequestId.trim().length === 0) {
+          throw new Error("Invalid SSH password prompt id.");
+        }
+        if (rawPassword !== null && typeof rawPassword !== "string") {
+          throw new Error("Invalid SSH password prompt response.");
+        }
+
+        const pending = this.pendingPrompts.get(rawRequestId);
+        if (!pending) {
+          throw new Error("SSH password prompt is no longer pending.");
+        }
+
+        clearTimeout(pending.timeout);
+        this.pendingPrompts.delete(rawRequestId);
+        pending.resolve(rawPassword);
+      },
+    );
+  }
+
+  cancelPendingPasswordPrompts(reason: string): void {
+    for (const [requestId, pending] of this.pendingPrompts) {
+      clearTimeout(pending.timeout);
+      this.pendingPrompts.delete(requestId);
+      pending.reject(new Error(reason));
+    }
+  }
+
+  async dispose(): Promise<void> {
+    this.cancelPendingPasswordPrompts("SSH environment bridge disposed.");
+    await this.manager.dispose();
+  }
+
+  private async requestPasswordFromRenderer(
+    input: DesktopSshPasswordRequest,
+  ): Promise<string | null> {
+    const window = this.options.getMainWindow();
+    if (!window || window.isDestroyed()) {
+      throw new Error("T3 Code window is not available for SSH authentication.");
+    }
+
+    const request: DesktopSshPasswordPromptRequest = {
+      requestId: Crypto.randomUUID(),
+      destination: input.destination,
+      username: input.username,
+      prompt: input.prompt,
+    };
+
+    return await new Promise<string | null>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingPrompts.delete(request.requestId);
+        reject(new Error(`SSH authentication timed out for ${input.destination}.`));
+      }, this.passwordPromptTimeoutMs);
+      timeout.unref();
+
+      this.pendingPrompts.set(request.requestId, { resolve, reject, timeout });
+
+      window.webContents.send(SSH_PASSWORD_PROMPT_CHANNEL, request);
+      if (window.isMinimized()) {
+        window.restore();
+      }
+      window.focus();
+    });
+  }
+}
+
 export const __test = {
   baseSshArgs,
   buildRemoteLaunchScript,

From 140ba2ae57d72377319060925f18debdda43ad1d Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 17 Apr 2026 14:50:36 -0700
Subject: [PATCH 24/74] Extract SSH launch scripts

- Externalize askpass, remote launch, and runner helpers into script assets
- Copy SSH scripts into `dist-electron` for packaging
- Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/sshEnvironment.ts            | 237 ++++--------------
 apps/desktop/src/sshScripts/askpass-posix.sh  |  33 +++
 .../src/sshScripts/askpass-windows.cmd        |   2 +
 .../src/sshScripts/askpass-windows.ps1        |  48 ++++
 apps/desktop/src/sshScripts/remote-launch.sh  |  34 +++
 apps/desktop/src/sshScripts/remote-pairing.sh |  10 +
 .../src/sshScripts/remote-pick-port.cjs       |  31 +++
 apps/desktop/src/sshScripts/remote-runner.sh  |  13 +
 apps/desktop/tsdown.config.ts                 |   1 +
 9 files changed, 225 insertions(+), 184 deletions(-)
 create mode 100644 apps/desktop/src/sshScripts/askpass-posix.sh
 create mode 100644 apps/desktop/src/sshScripts/askpass-windows.cmd
 create mode 100644 apps/desktop/src/sshScripts/askpass-windows.ps1
 create mode 100644 apps/desktop/src/sshScripts/remote-launch.sh
 create mode 100644 apps/desktop/src/sshScripts/remote-pairing.sh
 create mode 100644 apps/desktop/src/sshScripts/remote-pick-port.cjs
 create mode 100644 apps/desktop/src/sshScripts/remote-runner.sh

diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 7c423a7e79e..12a790968c4 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -315,97 +315,48 @@ function getDefaultSshAskpassDirectory(): string {
   return Path.join(OS.tmpdir(), SSH_ASKPASS_DIR_NAME);
 }
 
+const SSH_SCRIPTS_DIR = Path.join(__dirname, "sshScripts");
+const sshScriptCache = new Map<string, string>();
+
+function readSshScriptTemplate(fileName: string): string {
+  const cached = sshScriptCache.get(fileName);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const contents = FS.readFileSync(Path.join(SSH_SCRIPTS_DIR, fileName), "utf8");
+  sshScriptCache.set(fileName, contents);
+  return contents;
+}
+
+function stripTrailingNewlines(value: string): string {
+  return value.replace(/\n+$/u, "");
+}
+
+function applyScriptPlaceholders(
+  template: string,
+  replacements: Readonly<Record<string, string>>,
+): string {
+  let result = template;
+  for (const [token, value] of Object.entries(replacements)) {
+    result = result.replaceAll(`@@${token}@@`, value);
+  }
+  return result;
+}
+
+function toCrlf(value: string): string {
+  return value.replace(/\r?\n/gu, "\r\n");
+}
+
 function buildPosixSshAskpassScript(): string {
-  return [
-    "#!/bin/sh",
-    "set -eu",
-    'PROMPT="${1:-SSH authentication}"',
-    'if [ "${T3_SSH_AUTH_SECRET+x}" = "x" ]; then',
-    '  printf "%s\\n" "$T3_SSH_AUTH_SECRET"',
-    "  exit 0",
-    "fi",
-    "if command -v osascript >/dev/null 2>&1; then",
-    "  T3_SSH_ASKPASS_PROMPT=\"$PROMPT\" /usr/bin/osascript <<'APPLESCRIPT'",
-    'set promptText to system attribute "T3_SSH_ASKPASS_PROMPT"',
-    "try",
-    '  set dialogResult to display dialog promptText default answer "" with hidden answer buttons {"Cancel", "OK"} default button "OK" cancel button "Cancel"',
-    "  text returned of dialogResult",
-    "on error number -128",
-    "  error number -128",
-    "end try",
-    "APPLESCRIPT",
-    "  exit $?",
-    "fi",
-    "if command -v zenity >/dev/null 2>&1; then",
-    '  zenity --password --title="SSH authentication" --text="$PROMPT"',
-    "  exit $?",
-    "fi",
-    "if command -v kdialog >/dev/null 2>&1; then",
-    '  kdialog --title "SSH authentication" --password "$PROMPT"',
-    "  exit $?",
-    "fi",
-    "if command -v ssh-askpass >/dev/null 2>&1; then",
-    '  ssh-askpass "$PROMPT"',
-    "  exit $?",
-    "fi",
-    "printf 'Unable to open an SSH password prompt on this desktop.\\n' >&2",
-    "exit 1",
-    "",
-  ].join("\n");
+  return readSshScriptTemplate("askpass-posix.sh");
 }
 
 function buildWindowsSshAskpassScript(): string {
-  return [
-    "if ($env:T3_SSH_AUTH_SECRET -ne $null) {",
-    "  [Console]::Out.WriteLine($env:T3_SSH_AUTH_SECRET)",
-    "  exit 0",
-    "}",
-    "Add-Type -AssemblyName System.Windows.Forms",
-    "[System.Windows.Forms.Application]::EnableVisualStyles()",
-    '$prompt = if ($args.Length -gt 0 -and $args[0]) { $args[0] } else { "SSH authentication" }',
-    "$form = New-Object System.Windows.Forms.Form",
-    '$form.Text = "SSH authentication"',
-    "$form.Width = 420",
-    "$form.Height = 185",
-    '$form.StartPosition = "CenterScreen"',
-    '$form.FormBorderStyle = "FixedDialog"',
-    "$form.MaximizeBox = $false",
-    "$form.MinimizeBox = $false",
-    "$form.TopMost = $true",
-    "$label = New-Object System.Windows.Forms.Label",
-    "$label.Left = 16",
-    "$label.Top = 16",
-    "$label.Width = 372",
-    "$label.Height = 34",
-    "$label.Text = $prompt",
-    "$textbox = New-Object System.Windows.Forms.TextBox",
-    "$textbox.Left = 16",
-    "$textbox.Top = 60",
-    "$textbox.Width = 372",
-    "$textbox.UseSystemPasswordChar = $true",
-    "$okButton = New-Object System.Windows.Forms.Button",
-    '$okButton.Text = "OK"',
-    "$okButton.Left = 232",
-    "$okButton.Top = 100",
-    "$okButton.Width = 75",
-    "$cancelButton = New-Object System.Windows.Forms.Button",
-    '$cancelButton.Text = "Cancel"',
-    "$cancelButton.Left = 313",
-    "$cancelButton.Top = 100",
-    "$cancelButton.Width = 75",
-    "$okButton.DialogResult = [System.Windows.Forms.DialogResult]::OK",
-    "$cancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel",
-    "$form.AcceptButton = $okButton",
-    "$form.CancelButton = $cancelButton",
-    "$form.Controls.Add($label)",
-    "$form.Controls.Add($textbox)",
-    "$form.Controls.Add($okButton)",
-    "$form.Controls.Add($cancelButton)",
-    "$result = $form.ShowDialog()",
-    "if ($result -ne [System.Windows.Forms.DialogResult]::OK) { exit 1 }",
-    "[Console]::Out.WriteLine($textbox.Text)",
-    "",
-  ].join("\r\n");
+  return toCrlf(readSshScriptTemplate("askpass-windows.ps1"));
+}
+
+function buildWindowsSshAskpassLauncherScript(): string {
+  return toCrlf(readSshScriptTemplate("askpass-windows.cmd"));
 }
 
 function buildSshAskpassHelperDescriptor(input?: {
@@ -423,11 +374,7 @@ function buildSshAskpassHelperDescriptor(input?: {
       files: [
         {
           path: pathModule.join(directory, "ssh-askpass.cmd"),
-          contents: [
-            "@echo off",
-            'powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0ssh-askpass.ps1" %*',
-            "",
-          ].join("\r\n"),
+          contents: buildWindowsSshAskpassLauncherScript(),
         },
         {
           path: powershellPath,
@@ -640,73 +587,14 @@ async function resolveDesktopSshTarget(alias: string): Promise<DesktopSshEnviron
 }
 
 function buildRemoteLaunchScript(input?: { readonly packageSpec?: string }): string {
-  const runnerScript = buildRemoteT3RunnerScript(input);
-  return `
-set -eu
-STATE_KEY="$1"
-STATE_DIR="$HOME/.t3/ssh-launch/$STATE_KEY"
-SERVER_HOME="$STATE_DIR/server-home"
-PORT_FILE="$STATE_DIR/port"
-PID_FILE="$STATE_DIR/pid"
-LOG_FILE="$STATE_DIR/server.log"
-RUNNER_FILE="$STATE_DIR/run-t3.sh"
-mkdir -p "$STATE_DIR" "$SERVER_HOME"
-cat >"$RUNNER_FILE" <<'SH'
-${runnerScript}
-SH
-chmod 700 "$RUNNER_FILE"
-pick_port() {
-  node - "$PORT_FILE" <<'NODE'
-const fs = require("node:fs");
-const net = require("node:net");
-const filePath = process.argv[2];
-const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8").trim() : "";
-const preferred = Number.parseInt(raw, 10);
-const start = Number.isInteger(preferred) ? preferred : ${DEFAULT_REMOTE_PORT};
-const end = start + ${REMOTE_PORT_SCAN_WINDOW};
-
-function tryPort(port) {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-    server.unref();
-    server.once("error", () => resolve(false));
-    server.listen(port, "127.0.0.1", () => {
-      server.close((error) => resolve(error ? false : port));
-    });
+  return applyScriptPlaceholders(readSshScriptTemplate("remote-launch.sh"), {
+    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
+    T3_PICK_PORT_SCRIPT: stripTrailingNewlines(readSshScriptTemplate("remote-pick-port.cjs")),
+    T3_DEFAULT_REMOTE_PORT: String(DEFAULT_REMOTE_PORT),
+    T3_REMOTE_PORT_SCAN_WINDOW: String(REMOTE_PORT_SCAN_WINDOW),
   });
 }
 
-(async () => {
-  for (let port = start; port < end; port += 1) {
-    const available = await tryPort(port);
-    if (available) {
-      process.stdout.write(String(port));
-      return;
-    }
-  }
-  process.exit(1);
-})().catch(() => process.exit(1));
-NODE
-}
-REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
-REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
-if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
-  :
-else
-  REMOTE_PORT="$(pick_port)" || true
-  if [ -z "$REMOTE_PORT" ]; then
-    printf 'Failed to find an available port on the remote host. Ensure node is available on PATH.\\n' >&2
-    exit 1
-  fi
-  nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
-  REMOTE_PID="$!"
-  printf '%s\\n' "$REMOTE_PID" >"$PID_FILE"
-  printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
-fi
-printf '{"remotePort":%s}\\n' "$REMOTE_PORT"
-`.trimStart();
-}
-
 function getLastNonEmptyOutputLine(stdout: string): string | null {
   return (
     stdout
@@ -736,40 +624,21 @@ export function resolveRemoteT3CliPackageSpec(input: {
 
 function buildRemoteT3RunnerScript(input?: { readonly packageSpec?: string }): string {
   const packageSpec = input?.packageSpec?.trim() || "t3@latest";
-  return [
-    "#!/bin/sh",
-    "set -eu",
-    "if command -v t3 >/dev/null 2>&1; then",
-    '  exec t3 "$@"',
-    "fi",
-    "if command -v npx >/dev/null 2>&1; then",
-    `  exec npx --yes ${packageSpec} "$@"`,
-    "fi",
-    "if command -v npm >/dev/null 2>&1; then",
-    `  exec npm exec --yes ${packageSpec} -- "$@"`,
-    "fi",
-    `printf 'Remote host is missing the t3 CLI and could not install ${packageSpec} because npx and npm are unavailable on PATH.\\n' >&2`,
-    "exit 1",
-  ].join("\n");
+  return stripTrailingNewlines(
+    applyScriptPlaceholders(readSshScriptTemplate("remote-runner.sh"), {
+      T3_PACKAGE_SPEC: packageSpec,
+    }),
+  );
 }
 
 function buildRemotePairingScript(
   target: DesktopSshEnvironmentTarget,
   input?: { readonly packageSpec?: string },
 ): string {
-  const runnerScript = buildRemoteT3RunnerScript(input);
-  return `
-set -eu
-STATE_DIR="$HOME/.t3/ssh-launch/${remoteStateKey(target)}"
-SERVER_HOME="$STATE_DIR/server-home"
-RUNNER_FILE="$STATE_DIR/run-t3.sh"
-mkdir -p "$STATE_DIR" "$SERVER_HOME"
-cat >"$RUNNER_FILE" <<'SH'
-${runnerScript}
-SH
-chmod 700 "$RUNNER_FILE"
-"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json
-`.trimStart();
+  return applyScriptPlaceholders(readSshScriptTemplate("remote-pairing.sh"), {
+    T3_STATE_KEY: remoteStateKey(target),
+    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
+  });
 }
 
 async function launchOrReuseRemoteServer(
diff --git a/apps/desktop/src/sshScripts/askpass-posix.sh b/apps/desktop/src/sshScripts/askpass-posix.sh
new file mode 100644
index 00000000000..d06bde82221
--- /dev/null
+++ b/apps/desktop/src/sshScripts/askpass-posix.sh
@@ -0,0 +1,33 @@
+#!/bin/sh
+set -eu
+PROMPT="${1:-SSH authentication}"
+if [ "${T3_SSH_AUTH_SECRET+x}" = "x" ]; then
+  printf "%s\n" "$T3_SSH_AUTH_SECRET"
+  exit 0
+fi
+if command -v osascript >/dev/null 2>&1; then
+  T3_SSH_ASKPASS_PROMPT="$PROMPT" /usr/bin/osascript <<'APPLESCRIPT'
+set promptText to system attribute "T3_SSH_ASKPASS_PROMPT"
+try
+  set dialogResult to display dialog promptText default answer "" with hidden answer buttons {"Cancel", "OK"} default button "OK" cancel button "Cancel"
+  text returned of dialogResult
+on error number -128
+  error number -128
+end try
+APPLESCRIPT
+  exit $?
+fi
+if command -v zenity >/dev/null 2>&1; then
+  zenity --password --title="SSH authentication" --text="$PROMPT"
+  exit $?
+fi
+if command -v kdialog >/dev/null 2>&1; then
+  kdialog --title "SSH authentication" --password "$PROMPT"
+  exit $?
+fi
+if command -v ssh-askpass >/dev/null 2>&1; then
+  ssh-askpass "$PROMPT"
+  exit $?
+fi
+printf 'Unable to open an SSH password prompt on this desktop.\n' >&2
+exit 1
diff --git a/apps/desktop/src/sshScripts/askpass-windows.cmd b/apps/desktop/src/sshScripts/askpass-windows.cmd
new file mode 100644
index 00000000000..6421710215a
--- /dev/null
+++ b/apps/desktop/src/sshScripts/askpass-windows.cmd
@@ -0,0 +1,2 @@
+@echo off
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0ssh-askpass.ps1" %*
diff --git a/apps/desktop/src/sshScripts/askpass-windows.ps1 b/apps/desktop/src/sshScripts/askpass-windows.ps1
new file mode 100644
index 00000000000..277821d387f
--- /dev/null
+++ b/apps/desktop/src/sshScripts/askpass-windows.ps1
@@ -0,0 +1,48 @@
+if ($env:T3_SSH_AUTH_SECRET -ne $null) {
+  [Console]::Out.WriteLine($env:T3_SSH_AUTH_SECRET)
+  exit 0
+}
+Add-Type -AssemblyName System.Windows.Forms
+[System.Windows.Forms.Application]::EnableVisualStyles()
+$prompt = if ($args.Length -gt 0 -and $args[0]) { $args[0] } else { "SSH authentication" }
+$form = New-Object System.Windows.Forms.Form
+$form.Text = "SSH authentication"
+$form.Width = 420
+$form.Height = 185
+$form.StartPosition = "CenterScreen"
+$form.FormBorderStyle = "FixedDialog"
+$form.MaximizeBox = $false
+$form.MinimizeBox = $false
+$form.TopMost = $true
+$label = New-Object System.Windows.Forms.Label
+$label.Left = 16
+$label.Top = 16
+$label.Width = 372
+$label.Height = 34
+$label.Text = $prompt
+$textbox = New-Object System.Windows.Forms.TextBox
+$textbox.Left = 16
+$textbox.Top = 60
+$textbox.Width = 372
+$textbox.UseSystemPasswordChar = $true
+$okButton = New-Object System.Windows.Forms.Button
+$okButton.Text = "OK"
+$okButton.Left = 232
+$okButton.Top = 100
+$okButton.Width = 75
+$cancelButton = New-Object System.Windows.Forms.Button
+$cancelButton.Text = "Cancel"
+$cancelButton.Left = 313
+$cancelButton.Top = 100
+$cancelButton.Width = 75
+$okButton.DialogResult = [System.Windows.Forms.DialogResult]::OK
+$cancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel
+$form.AcceptButton = $okButton
+$form.CancelButton = $cancelButton
+$form.Controls.Add($label)
+$form.Controls.Add($textbox)
+$form.Controls.Add($okButton)
+$form.Controls.Add($cancelButton)
+$result = $form.ShowDialog()
+if ($result -ne [System.Windows.Forms.DialogResult]::OK) { exit 1 }
+[Console]::Out.WriteLine($textbox.Text)
diff --git a/apps/desktop/src/sshScripts/remote-launch.sh b/apps/desktop/src/sshScripts/remote-launch.sh
new file mode 100644
index 00000000000..ebe50c8bfaf
--- /dev/null
+++ b/apps/desktop/src/sshScripts/remote-launch.sh
@@ -0,0 +1,34 @@
+set -eu
+STATE_KEY="$1"
+STATE_DIR="$HOME/.t3/ssh-launch/$STATE_KEY"
+SERVER_HOME="$STATE_DIR/server-home"
+PORT_FILE="$STATE_DIR/port"
+PID_FILE="$STATE_DIR/pid"
+LOG_FILE="$STATE_DIR/server.log"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+mkdir -p "$STATE_DIR" "$SERVER_HOME"
+cat >"$RUNNER_FILE" <<'SH'
+@@T3_RUNNER_SCRIPT@@
+SH
+chmod 700 "$RUNNER_FILE"
+pick_port() {
+  node - "$PORT_FILE" "@@T3_DEFAULT_REMOTE_PORT@@" "@@T3_REMOTE_PORT_SCAN_WINDOW@@" <<'NODE'
+@@T3_PICK_PORT_SCRIPT@@
+NODE
+}
+REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
+if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+  :
+else
+  REMOTE_PORT="$(pick_port)" || true
+  if [ -z "$REMOTE_PORT" ]; then
+    printf 'Failed to find an available port on the remote host. Ensure node is available on PATH.\n' >&2
+    exit 1
+  fi
+  nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
+  REMOTE_PID="$!"
+  printf '%s\n' "$REMOTE_PID" >"$PID_FILE"
+  printf '%s\n' "$REMOTE_PORT" >"$PORT_FILE"
+fi
+printf '{"remotePort":%s}\n' "$REMOTE_PORT"
diff --git a/apps/desktop/src/sshScripts/remote-pairing.sh b/apps/desktop/src/sshScripts/remote-pairing.sh
new file mode 100644
index 00000000000..4e9d850e103
--- /dev/null
+++ b/apps/desktop/src/sshScripts/remote-pairing.sh
@@ -0,0 +1,10 @@
+set -eu
+STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
+SERVER_HOME="$STATE_DIR/server-home"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+mkdir -p "$STATE_DIR" "$SERVER_HOME"
+cat >"$RUNNER_FILE" <<'SH'
+@@T3_RUNNER_SCRIPT@@
+SH
+chmod 700 "$RUNNER_FILE"
+"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json
diff --git a/apps/desktop/src/sshScripts/remote-pick-port.cjs b/apps/desktop/src/sshScripts/remote-pick-port.cjs
new file mode 100644
index 00000000000..8021fedb43d
--- /dev/null
+++ b/apps/desktop/src/sshScripts/remote-pick-port.cjs
@@ -0,0 +1,31 @@
+const fs = require("node:fs");
+const net = require("node:net");
+const filePath = process.argv[2];
+const defaultPort = Number.parseInt(process.argv[3] ?? "", 10);
+const scanWindow = Number.parseInt(process.argv[4] ?? "", 10);
+const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8").trim() : "";
+const preferred = Number.parseInt(raw, 10);
+const start = Number.isInteger(preferred) ? preferred : defaultPort;
+const end = start + scanWindow;
+
+function tryPort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => {
+      server.close((error) => resolve(error ? false : port));
+    });
+  });
+}
+
+(async () => {
+  for (let port = start; port < end; port += 1) {
+    const available = await tryPort(port);
+    if (available) {
+      process.stdout.write(String(port));
+      return;
+    }
+  }
+  process.exit(1);
+})().catch(() => process.exit(1));
diff --git a/apps/desktop/src/sshScripts/remote-runner.sh b/apps/desktop/src/sshScripts/remote-runner.sh
new file mode 100644
index 00000000000..c9a1b2164e2
--- /dev/null
+++ b/apps/desktop/src/sshScripts/remote-runner.sh
@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+if command -v t3 >/dev/null 2>&1; then
+  exec t3 "$@"
+fi
+if command -v npx >/dev/null 2>&1; then
+  exec npx --yes @@T3_PACKAGE_SPEC@@ "$@"
+fi
+if command -v npm >/dev/null 2>&1; then
+  exec npm exec --yes @@T3_PACKAGE_SPEC@@ -- "$@"
+fi
+printf 'Remote host is missing the t3 CLI and could not install @@T3_PACKAGE_SPEC@@ because npx and npm are unavailable on PATH.\n' >&2
+exit 1
diff --git a/apps/desktop/tsdown.config.ts b/apps/desktop/tsdown.config.ts
index 74067b127d0..2efcad6feec 100644
--- a/apps/desktop/tsdown.config.ts
+++ b/apps/desktop/tsdown.config.ts
@@ -13,6 +13,7 @@ export default defineConfig([
     entry: ["src/main.ts"],
     clean: true,
     noExternal: (id) => id.startsWith("@t3tools/") || id.startsWith("effect-acp"),
+    copy: [{ from: "src/sshScripts/*", to: "dist-electron/sshScripts" }],
   },
   {
     ...shared,

From d1cb067f94da7f69521796d24845bb16b7a74e5c Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 17 Apr 2026 14:55:28 -0700
Subject: [PATCH 25/74] Simplify ssh askpass to require cached secret

- Remove native password prompts from posix and Windows scripts
- Fail loudly when T3_SSH_AUTH_SECRET is missing
---
 apps/desktop/src/sshScripts/askpass-posix.sh  | 31 ++---------
 .../src/sshScripts/askpass-windows.ps1        | 52 +++----------------
 2 files changed, 11 insertions(+), 72 deletions(-)

diff --git a/apps/desktop/src/sshScripts/askpass-posix.sh b/apps/desktop/src/sshScripts/askpass-posix.sh
index d06bde82221..56e3bc5b253 100644
--- a/apps/desktop/src/sshScripts/askpass-posix.sh
+++ b/apps/desktop/src/sshScripts/askpass-posix.sh
@@ -1,33 +1,10 @@
 #!/bin/sh
-set -eu
-PROMPT="${1:-SSH authentication}"
+# Invoked by ssh via SSH_ASKPASS when T3 Code re-runs ssh with a cached password
+# from the renderer's in-app prompt. We never expose a native dialog here — if
+# T3_SSH_AUTH_SECRET is missing, that's a caller bug and we fail loudly.
 if [ "${T3_SSH_AUTH_SECRET+x}" = "x" ]; then
   printf "%s\n" "$T3_SSH_AUTH_SECRET"
   exit 0
 fi
-if command -v osascript >/dev/null 2>&1; then
-  T3_SSH_ASKPASS_PROMPT="$PROMPT" /usr/bin/osascript <<'APPLESCRIPT'
-set promptText to system attribute "T3_SSH_ASKPASS_PROMPT"
-try
-  set dialogResult to display dialog promptText default answer "" with hidden answer buttons {"Cancel", "OK"} default button "OK" cancel button "Cancel"
-  text returned of dialogResult
-on error number -128
-  error number -128
-end try
-APPLESCRIPT
-  exit $?
-fi
-if command -v zenity >/dev/null 2>&1; then
-  zenity --password --title="SSH authentication" --text="$PROMPT"
-  exit $?
-fi
-if command -v kdialog >/dev/null 2>&1; then
-  kdialog --title "SSH authentication" --password "$PROMPT"
-  exit $?
-fi
-if command -v ssh-askpass >/dev/null 2>&1; then
-  ssh-askpass "$PROMPT"
-  exit $?
-fi
-printf 'Unable to open an SSH password prompt on this desktop.\n' >&2
+printf 'T3 Code ssh-askpass invoked without T3_SSH_AUTH_SECRET.\n' >&2
 exit 1
diff --git a/apps/desktop/src/sshScripts/askpass-windows.ps1 b/apps/desktop/src/sshScripts/askpass-windows.ps1
index 277821d387f..c24cfc21998 100644
--- a/apps/desktop/src/sshScripts/askpass-windows.ps1
+++ b/apps/desktop/src/sshScripts/askpass-windows.ps1
@@ -1,48 +1,10 @@
-if ($env:T3_SSH_AUTH_SECRET -ne $null) {
+# Invoked by ssh via SSH_ASKPASS (through ssh-askpass.cmd) when T3 Code re-runs
+# ssh with a cached password from the renderer's in-app prompt. We never expose
+# a native dialog here — if T3_SSH_AUTH_SECRET is missing, that's a caller bug
+# and we fail loudly.
+if ($null -ne $env:T3_SSH_AUTH_SECRET) {
   [Console]::Out.WriteLine($env:T3_SSH_AUTH_SECRET)
   exit 0
 }
-Add-Type -AssemblyName System.Windows.Forms
-[System.Windows.Forms.Application]::EnableVisualStyles()
-$prompt = if ($args.Length -gt 0 -and $args[0]) { $args[0] } else { "SSH authentication" }
-$form = New-Object System.Windows.Forms.Form
-$form.Text = "SSH authentication"
-$form.Width = 420
-$form.Height = 185
-$form.StartPosition = "CenterScreen"
-$form.FormBorderStyle = "FixedDialog"
-$form.MaximizeBox = $false
-$form.MinimizeBox = $false
-$form.TopMost = $true
-$label = New-Object System.Windows.Forms.Label
-$label.Left = 16
-$label.Top = 16
-$label.Width = 372
-$label.Height = 34
-$label.Text = $prompt
-$textbox = New-Object System.Windows.Forms.TextBox
-$textbox.Left = 16
-$textbox.Top = 60
-$textbox.Width = 372
-$textbox.UseSystemPasswordChar = $true
-$okButton = New-Object System.Windows.Forms.Button
-$okButton.Text = "OK"
-$okButton.Left = 232
-$okButton.Top = 100
-$okButton.Width = 75
-$cancelButton = New-Object System.Windows.Forms.Button
-$cancelButton.Text = "Cancel"
-$cancelButton.Left = 313
-$cancelButton.Top = 100
-$cancelButton.Width = 75
-$okButton.DialogResult = [System.Windows.Forms.DialogResult]::OK
-$cancelButton.DialogResult = [System.Windows.Forms.DialogResult]::Cancel
-$form.AcceptButton = $okButton
-$form.CancelButton = $cancelButton
-$form.Controls.Add($label)
-$form.Controls.Add($textbox)
-$form.Controls.Add($okButton)
-$form.Controls.Add($cancelButton)
-$result = $form.ShowDialog()
-if ($result -ne [System.Windows.Forms.DialogResult]::OK) { exit 1 }
-[Console]::Out.WriteLine($textbox.Text)
+[Console]::Error.WriteLine("T3 Code ssh-askpass invoked without T3_SSH_AUTH_SECRET.")
+exit 1

From b6faa167f13a529f2291db110775430e926cef31 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 17 Apr 2026 15:26:05 -0700
Subject: [PATCH 26/74] Fix PR CI failures

- use type-only imports required by verbatim module syntax
- fix SSH desktop build/typecheck regressions and auth test isolation
- tighten browser test selectors for the add-environment dialog

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/sshEnvironment.test.ts       |  2 +-
 apps/desktop/src/sshEnvironment.ts            | 42 ++++++++++++-------
 apps/server/src/server.test.ts                |  8 ++--
 .../settings/SettingsPanels.browser.tsx       |  8 +++-
 packages/contracts/src/ipc.ts                 |  3 +-
 5 files changed, 40 insertions(+), 23 deletions(-)

diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index 2b4f0cadc88..fe7274b8b90 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -5,7 +5,7 @@ import * as Path from "node:path";
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { __test, discoverDesktopSshHosts } from "./sshEnvironment";
+import { __test, discoverDesktopSshHosts } from "./sshEnvironment.ts";
 
 const tempDirectories: string[] = [];
 
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 12a790968c4..16a75dc8cb6 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -17,7 +17,7 @@ import type {
   ExecutionEnvironmentDescriptor,
 } from "@t3tools/contracts";
 
-import { waitForHttpReady } from "./backendReadiness";
+import { waitForHttpReady } from "./backendReadiness.ts";
 
 const DEFAULT_REMOTE_PORT = 3773;
 const REMOTE_PORT_SCAN_WINDOW = 200;
@@ -101,13 +101,13 @@ function expandHomePath(input: string, homeDir: string = OS.homedir()): string {
 
 function resolveSshConfigIncludePattern(
   includePattern: string,
-  directory: string,
+  _directory: string,
   homeDir: string = OS.homedir(),
 ): string {
   const expandedPattern = expandHomePath(includePattern, homeDir);
   return Path.isAbsolute(expandedPattern)
     ? expandedPattern
-    : Path.resolve(directory, expandedPattern);
+    : Path.resolve(Path.join(homeDir, ".ssh"), expandedPattern);
 }
 
 function hasSshPattern(value: string): boolean {
@@ -147,6 +147,7 @@ function expandGlob(pattern: string): ReadonlyArray<string> {
 function collectSshConfigAliasesFromFile(
   filePath: string,
   visited = new Set<string>(),
+  homeDir: string = OS.homedir(),
 ): ReadonlyArray<string> {
   const resolvedPath = Path.resolve(filePath);
   if (visited.has(resolvedPath) || !FS.existsSync(resolvedPath)) {
@@ -168,9 +169,9 @@ function collectSshConfigAliasesFromFile(
     const normalizedDirective = directive.toLowerCase();
     if (normalizedDirective === "include") {
       for (const includePattern of rawArgs) {
-        const resolvedPattern = resolveSshConfigIncludePattern(includePattern, directory);
+        const resolvedPattern = resolveSshConfigIncludePattern(includePattern, directory, homeDir);
         for (const includedPath of expandGlob(resolvedPattern)) {
-          for (const alias of collectSshConfigAliasesFromFile(includedPath, visited)) {
+          for (const alias of collectSshConfigAliasesFromFile(includedPath, visited, homeDir)) {
             aliases.add(alias);
           }
         }
@@ -689,8 +690,8 @@ async function issueRemotePairingToken(
     ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
     ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
   });
-  const stdout = result.stdout.trim();
-  if (!stdout) {
+  const line = getLastNonEmptyOutputLine(result.stdout);
+  if (!line) {
     throw new Error(
       `SSH pairing did not return a credential. stdout=${JSON.stringify(result.stdout)}`,
     );
@@ -698,10 +699,10 @@ async function issueRemotePairingToken(
 
   let parsed: { credential?: unknown };
   try {
-    parsed = JSON.parse(stdout) as { credential?: unknown };
+    parsed = JSON.parse(line) as { credential?: unknown };
   } catch (cause) {
     throw new Error(
-      `SSH pairing returned unparseable output. stdout=${JSON.stringify(result.stdout)}`,
+      `SSH pairing returned unparseable output. line=${JSON.stringify(line)} stdout=${JSON.stringify(result.stdout)}`,
       { cause },
     );
   }
@@ -768,8 +769,13 @@ async function stopTunnel(entry: SshTunnelEntry): Promise<void> {
 export async function discoverDesktopSshHosts(input?: {
   readonly homeDir?: string;
 }): Promise<readonly DesktopDiscoveredSshHost[]> {
-  const sshDirectory = Path.join(input?.homeDir ?? OS.homedir(), ".ssh");
-  const configAliases = collectSshConfigAliasesFromFile(Path.join(sshDirectory, "config"));
+  const homeDir = input?.homeDir ?? OS.homedir();
+  const sshDirectory = Path.join(homeDir, ".ssh");
+  const configAliases = collectSshConfigAliasesFromFile(
+    Path.join(sshDirectory, "config"),
+    new Set<string>(),
+    homeDir,
+  );
   const knownHosts = readKnownHostsHostnames(Path.join(sshDirectory, "known_hosts"));
   const discovered = new Map<string, DesktopDiscoveredSshHost>();
 
@@ -803,8 +809,11 @@ export class DesktopSshEnvironmentManager {
   private readonly tunnels = new Map<string, SshTunnelEntry>();
   private readonly pendingTunnelEntries = new Map<string, Promise<SshTunnelEntry>>();
   private readonly authSecrets = new Map<string, string>();
+  private readonly options: DesktopSshEnvironmentManagerOptions;
 
-  constructor(private readonly options: DesktopSshEnvironmentManagerOptions = {}) {}
+  constructor(options: DesktopSshEnvironmentManagerOptions = {}) {
+    this.options = options;
+  }
 
   private deleteTunnelIfCurrent(entry: SshTunnelEntry): void {
     if (this.tunnels.get(entry.key) === entry) {
@@ -886,7 +895,12 @@ export class DesktopSshEnvironmentManager {
     target: DesktopSshEnvironmentTarget,
     options?: { readonly issuePairingToken?: boolean },
   ): Promise<DesktopSshEnvironmentBootstrap> {
-    const resolvedTarget = await resolveDesktopSshTarget(target.alias || target.hostname);
+    const baseResolved = await resolveDesktopSshTarget(target.alias || target.hostname);
+    const resolvedTarget: DesktopSshEnvironmentTarget = {
+      ...baseResolved,
+      ...(target.username !== null ? { username: target.username } : {}),
+      ...(target.port !== null ? { port: target.port } : {}),
+    };
     const key = targetConnectionKey(resolvedTarget);
     const packageSpec = this.options.resolveCliPackageSpec?.();
     const entry = await this.ensureTunnelEntry(key, resolvedTarget, packageSpec);
@@ -1003,7 +1017,7 @@ export class DesktopSshEnvironmentManager {
           });
           waitForHttpReady(httpBaseUrl, { timeoutMs: SSH_READY_TIMEOUT_MS })
             .then(() => resolve())
-            .catch((error) => reject(error));
+            .catch((error: unknown) => reject(error));
         });
         this.tunnels.set(key, tunnelEntry);
         try {
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index a1064752e29..0cd23abc950 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -213,10 +213,8 @@ const browserOtlpTracingLayer = Layer.mergeAll(
   Layer.succeed(HttpClient.TracerDisabledWhen, () => true),
 );
 
-const authTestLayer = ServerAuthLive.pipe(
-  Layer.provide(SqlitePersistenceMemory),
-  Layer.provide(ServerSecretStoreLive),
-);
+const makeAuthTestLayer = () =>
+  ServerAuthLive.pipe(Layer.provide(SqlitePersistenceMemory), Layer.provide(ServerSecretStoreLive));
 
 const makeBrowserOtlpPayload = (spanName: string) =>
   Effect.gen(function* () {
@@ -643,7 +641,7 @@ const buildAppUnderTest = (options?: {
           ...options?.layers?.repositoryIdentityResolver,
         }),
       ),
-      Layer.provideMerge(authTestLayer),
+      Layer.provideMerge(makeAuthTestLayer()),
       Layer.provide(workspaceAndProjectServicesLayer),
       Layer.provideMerge(FetchHttpClient.layer),
       Layer.provide(layerConfig),
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index feca8f0090c..f1a07492a60 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -940,12 +940,16 @@ describe("GeneralSettingsPanel observability", () => {
     );
 
     await page.getByRole("button", { name: "Add environment", exact: true }).click();
-    await expect.element(page.getByText("Add Environment")).toBeInTheDocument();
+    await expect
+      .element(page.getByRole("heading", { name: "Add Environment", exact: true }))
+      .toBeInTheDocument();
     await page.getByRole("button", { name: "SSH", exact: true }).click();
     await vi.waitFor(() => {
       expect(discoverSshHosts).toHaveBeenCalledTimes(1);
     });
-    await expect.element(page.getByText("devbox")).toBeInTheDocument();
+    await expect
+      .element(page.getByRole("heading", { name: "devbox", exact: true }))
+      .toBeInTheDocument();
 
     await page.getByText("Enter a host manually").click();
     await page.getByLabelText("Label").fill("Build box");
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 9002a7cf10b..f15dfdb9703 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -61,7 +61,8 @@ import type {
 import type { AdvertisedEndpoint } from "./remoteAccess.ts";
 import { EditorId } from "./editor.ts";
 import type { ExecutionEnvironmentDescriptor } from "./environment.ts";
-import { ServerSettings, type ClientSettings, type ServerSettingsPatch } from "./settings.ts";
+import type { ClientSettings } from "./settings.ts";
+import { ServerSettings, ServerSettingsPatch } from "./settings.ts";
 import type { SourceControlDiscoveryResult } from "./sourceControl.ts";
 
 export interface ContextMenuItem<T extends string = string> {

From 2fed370f35c72c7f83f223f4afecfe99af3092a0 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 26 Apr 2026 19:57:23 -0700
Subject: [PATCH 27/74] docs(remote): document desktop ssh launch

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .docs/remote-architecture.md | 11 +++++++++++
 REMOTE.md                    | 14 ++++++++++++++
 2 files changed, 25 insertions(+)

diff --git a/.docs/remote-architecture.md b/.docs/remote-architecture.md
index 89b3d41ea0c..75274095a12 100644
--- a/.docs/remote-architecture.md
+++ b/.docs/remote-architecture.md
@@ -252,6 +252,8 @@ After that, the renderer should still connect using an ordinary WebSocket URL ag
 
 This keeps the renderer transport model consistent with every other access method.
 
+The desktop main process owns the SSH bridge because it can spawn local SSH processes, manage askpass prompts, write temporary launch scripts, and clean up forwards. The renderer receives a saved environment record and connects through the forwarded URL; it should not need SSH-specific RPC paths for normal environment traffic.
+
 ## Launch methods
 
 Launch methods answer a different question:
@@ -294,6 +296,15 @@ The recommended T3 flow is:
 4. Desktop establishes local port forwarding.
 5. Renderer connects to the forwarded WebSocket endpoint as a normal environment.
 
+The saved environment should remember that it was created by desktop SSH launch only for reconnect and lifecycle UX. That metadata should not change the server protocol or the environment identity model.
+
+Failure handling should be explicit:
+
+- SSH authentication failure should surface before any environment is saved
+- remote launch failure should include remote logs or the launcher command output when available
+- forwarded-port failure should leave the saved environment disconnected rather than falling back to an unrelated endpoint
+- reconnect should attempt to restore the SSH bridge before reconnecting the normal WebSocket client
+
 ### 3. Client-managed local publish
 
 This is the inverse of remote launch: a local T3 server is already running, and the client publishes it through a tunnel.
diff --git a/REMOTE.md b/REMOTE.md
index afe22bd6040..2d7edb1c15e 100644
--- a/REMOTE.md
+++ b/REMOTE.md
@@ -80,6 +80,20 @@ Use `t3 serve --help` for the full flag reference. It supports the same general
 > For now, use `t3 project ...` on the server machine instead.
 > Full GUI support for remote project management is coming soon.
 
+### Option 3: Desktop-Managed SSH Launch
+
+Use this when you want the desktop app to start or reuse T3 Code on another machine over SSH.
+
+1. Open **Settings** → **Connections**.
+2. Under **Remote Environments**, choose **Add environment**.
+3. Select the SSH launch flow.
+4. Enter the SSH target, such as `user@example.com`.
+5. Confirm the launch. The desktop app probes the host, starts or reuses a remote T3 server, opens a local port forward, and saves the environment.
+
+After setup, the renderer connects to a local forwarded HTTP/WebSocket endpoint. The remote host still owns the actual T3 server, projects, files, git state, terminals, and provider sessions.
+
+SSH launch is a desktop feature because it needs local process and SSH access. Once the environment is paired and saved, it uses the same environment list and connection model as direct LAN, Tailscale, HTTPS, or future tunnel-backed environments.
+
 ## How Pairing Works
 
 The remote device does not need a long-lived secret up front.

From 7f60bbf878d7988a897b312f2cbbccd8f7360d45 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Mon, 27 Apr 2026 18:37:13 -0700
Subject: [PATCH 28/74] Delay SSH tunnel disposal until pending setup settles

- Fix auth-failure matching for permission denied variants
- Allow remote port picker to run without a state file path
- Dispose only after pending tunnel creation resolves
---
 apps/desktop/src/sshEnvironment.test.ts       | 66 ++++++++++++++++++-
 apps/desktop/src/sshEnvironment.ts            |  8 ++-
 .../src/sshScripts/remote-pick-port.cjs       |  2 +-
 3 files changed, 71 insertions(+), 5 deletions(-)

diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index fe7274b8b90..6fcc0e783ea 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -5,9 +5,10 @@ import * as Path from "node:path";
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-import { __test, discoverDesktopSshHosts } from "./sshEnvironment.ts";
+import { __test, DesktopSshEnvironmentManager, discoverDesktopSshHosts } from "./sshEnvironment.ts";
 
 const tempDirectories: string[] = [];
+type TunnelEntry = Parameters<typeof __test.stopTunnel>[0];
 
 afterEach(() => {
   for (const directory of tempDirectories.splice(0)) {
@@ -255,10 +256,17 @@ describe("sshEnvironment", () => {
         ),
       ),
     ).toBe(true);
+    expect(__test.isSshAuthFailure(new Error("Permission denied (publickey)."))).toBe(true);
     expect(__test.isSshAuthFailure(new Error("Connection timed out"))).toBe(false);
     expect(__test.isSshAuthFailure(new Error("mkdir: Permission denied"))).toBe(false);
   });
 
+  it("allows the remote port picker to run without a state file path", () => {
+    expect(__test.readSshScriptTemplate("remote-pick-port.cjs")).toContain(
+      'const filePath = process.argv[2] ?? "";',
+    );
+  });
+
   it("settles tunnel shutdown if the child exits before the exit listener attaches", async () => {
     vi.useFakeTimers();
 
@@ -307,4 +315,60 @@ describe("sshEnvironment", () => {
       vi.useRealTimers();
     }
   });
+
+  it("waits for pending tunnel creation before disposing completed tunnels", async () => {
+    class ControlledChildProcess extends EventEmitter {
+      exitCode: number | null = null;
+      signalCode: NodeJS.Signals | null = null;
+      readonly killSignals: Array<NodeJS.Signals | undefined> = [];
+
+      kill(signal?: NodeJS.Signals | number): boolean {
+        this.killSignals.push(typeof signal === "string" ? signal : undefined);
+        this.signalCode = "SIGTERM";
+        this.emit("exit", null, this.signalCode);
+        return true;
+      }
+    }
+
+    let resolvePending!: (entry: TunnelEntry) => void;
+    const child = new ControlledChildProcess();
+    const entry: TunnelEntry = {
+      key: "devbox",
+      target: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+      remotePort: 3773,
+      localPort: 3774,
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      process: child as never,
+    };
+    const manager = new DesktopSshEnvironmentManager();
+    const internals = manager as unknown as {
+      pendingTunnelEntries: Map<string, Promise<TunnelEntry>>;
+      tunnels: Map<string, TunnelEntry>;
+    };
+    const pending = new Promise<TunnelEntry>((resolve) => {
+      resolvePending = resolve;
+    }).then((completedEntry) => {
+      internals.tunnels.set(completedEntry.key, completedEntry);
+      return completedEntry;
+    });
+    internals.pendingTunnelEntries.set(entry.key, pending);
+
+    const disposePromise = manager.dispose();
+    await Promise.resolve();
+
+    expect(child.killSignals).toEqual([]);
+
+    resolvePending(entry);
+    await disposePromise;
+
+    expect(child.killSignals).toEqual(["SIGTERM"]);
+    expect(internals.tunnels.size).toBe(0);
+    expect(internals.pendingTunnelEntries.size).toBe(0);
+  });
 });
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 16a75dc8cb6..eb57b8b37e2 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -472,7 +472,7 @@ function isSshAuthFailure(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
   const normalized = message.toLowerCase();
   return (
-    /permission denied \((?:publickey|password|keyboard-interactive|hostbased|gssapi-with-mic)[^)]+\)/u.test(
+    /permission denied \((?:publickey|password|keyboard-interactive|hostbased|gssapi-with-mic)[^)]*\)/u.test(
       normalized,
     ) ||
     /authentication failed/u.test(normalized) ||
@@ -1019,13 +1019,12 @@ export class DesktopSshEnvironmentManager {
             .then(() => resolve())
             .catch((error: unknown) => reject(error));
         });
-        this.tunnels.set(key, tunnelEntry);
         try {
           await tunnelReady;
+          this.tunnels.set(key, tunnelEntry);
           return tunnelEntry;
         } catch (error) {
           await stopTunnel(tunnelEntry).catch(() => undefined);
-          this.deleteTunnelIfCurrent(tunnelEntry);
           throw error;
         }
       });
@@ -1039,6 +1038,8 @@ export class DesktopSshEnvironmentManager {
   }
 
   async dispose(): Promise<void> {
+    const pending = [...this.pendingTunnelEntries.values()];
+    await Promise.allSettled(pending);
     const entries = [...this.tunnels.values()];
     this.tunnels.clear();
     this.pendingTunnelEntries.clear();
@@ -1372,6 +1373,7 @@ export const __test = {
   normalizeKnownHostsHostname,
   parseKnownHostsHostnames,
   parseSshResolveOutput,
+  readSshScriptTemplate,
   resolveSshConfigIncludePattern,
   stopTunnel,
 };
diff --git a/apps/desktop/src/sshScripts/remote-pick-port.cjs b/apps/desktop/src/sshScripts/remote-pick-port.cjs
index 8021fedb43d..7051beae895 100644
--- a/apps/desktop/src/sshScripts/remote-pick-port.cjs
+++ b/apps/desktop/src/sshScripts/remote-pick-port.cjs
@@ -1,6 +1,6 @@
 const fs = require("node:fs");
 const net = require("node:net");
-const filePath = process.argv[2];
+const filePath = process.argv[2] ?? "";
 const defaultPort = Number.parseInt(process.argv[3] ?? "", 10);
 const scanWindow = Number.parseInt(process.argv[4] ?? "", 10);
 const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8").trim() : "";

From 1d6d98bc42abb5d3dea1933fb3af40f6db2dce09 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Mon, 27 Apr 2026 22:24:40 -0700
Subject: [PATCH 29/74] Add Tailscale Serve pairing support

- add desktop and server settings for hosted HTTPS pairing
- resolve and probe MagicDNS endpoints via shared Tailscale helpers
- update remote pairing docs and UI to surface the new setup flow
---
 REMOTE.md                                     |   29 +-
 apps/desktop/package.json                     |    2 +
 apps/desktop/src/desktopSettings.test.ts      |   62 +
 apps/desktop/src/desktopSettings.ts           |   30 +
 apps/desktop/src/main.ts                      |   42 +
 apps/desktop/src/preload.ts                   |    3 +
 .../src/tailscaleEndpointProvider.test.ts     |   52 +-
 apps/desktop/src/tailscaleEndpointProvider.ts |  138 +-
 apps/server/package.json                      |    1 +
 apps/server/src/cli-config.test.ts            |   36 +
 apps/server/src/cli.test.ts                   |    2 +
 apps/server/src/cli.ts                        |   47 +
 apps/server/src/config.ts                     |    4 +
 .../Layers/ServerEnvironment.test.ts          |    2 +
 apps/server/src/server.test.ts                |    2 +
 apps/server/src/server.ts                     |   25 +
 .../settings/ConnectionsSettings.tsx          | 1352 +++++++++++++----
 .../settings/SettingsPanels.browser.tsx       |   19 +
 apps/web/src/components/ui/alert-dialog.tsx   |    4 +-
 apps/web/src/environments/remote/api.test.ts  |   13 +
 apps/web/src/environments/remote/target.ts    |   11 +
 apps/web/src/localApi.test.ts                 |   11 +
 apps/web/vercel.json                          |    2 +
 bun.lock                                      |   20 +
 packages/contracts/src/ipc.ts                 |    6 +
 packages/tailscale/package.json               |   28 +
 packages/tailscale/src/index.ts               |    1 +
 packages/tailscale/src/tailscale.test.ts      |  120 ++
 packages/tailscale/src/tailscale.ts           |  291 ++++
 packages/tailscale/tsconfig.json              |   17 +
 scripts/apply-web-brand-assets.ts             |   56 +
 scripts/lib/brand-assets.test.ts              |   45 +
 scripts/lib/brand-assets.ts                   |   83 +-
 turbo.json                                    |    2 +
 34 files changed, 2111 insertions(+), 447 deletions(-)
 create mode 100644 packages/tailscale/package.json
 create mode 100644 packages/tailscale/src/index.ts
 create mode 100644 packages/tailscale/src/tailscale.test.ts
 create mode 100644 packages/tailscale/src/tailscale.ts
 create mode 100644 packages/tailscale/tsconfig.json
 create mode 100644 scripts/apply-web-brand-assets.ts
 create mode 100644 scripts/lib/brand-assets.test.ts

diff --git a/REMOTE.md b/REMOTE.md
index 2d7edb1c15e..61a1cc3b5cc 100644
--- a/REMOTE.md
+++ b/REMOTE.md
@@ -27,10 +27,12 @@ If you are already running the desktop app and want to make it reachable from ot
 
 The default endpoint controls the QR code and primary copy action for pairing links. You can change it from the expanded endpoint list. The preference is stored by endpoint type, so choosing the local LAN endpoint survives normal IP address changes when you move between networks.
 
-When no user default is saved, the app chooses the best reachable endpoint for pairing links:
+When no user default is saved, the app uses the built-in LAN endpoint for pairing links when
+available. You can set another endpoint as the default from the expanded endpoint list.
 
-- HTTPS/WSS-compatible endpoints are preferred because they work from `https://app.t3.codes`.
-- Non-loopback HTTP endpoints are used for direct LAN pairing when HTTPS is not available.
+- HTTPS/WSS-compatible endpoints work from `https://app.t3.codes`, but are not made the default
+  automatically.
+- Non-loopback HTTP endpoints are useful for direct LAN pairing.
 - Loopback-only endpoints are not useful for another device unless that device is the same machine.
 
 If the copied link points directly at `http://192.168.x.y:3773`, open it from a client that can reach that LAN address. If it points at `https://app.t3.codes/pair?...`, the hosted web app will save the environment and connect directly to the backend URL in the link.
@@ -43,7 +45,13 @@ Depending on your Tailscale setup, this may include:
 
 - the machine's `100.x.y.z` Tailnet IP
 - a MagicDNS name
-- an HTTPS MagicDNS endpoint when Tailscale HTTPS is available for the machine
+- an HTTPS MagicDNS endpoint when Tailscale Serve is configured for this backend
+
+The Tailscale HTTPS endpoint uses the clean MagicDNS URL, such as
+`https://machine.tailnet.ts.net/`, and is disabled until the app verifies that the URL reaches this
+backend. Use **Setup** on the Tailscale HTTPS row to opt in. The desktop app restarts the backend
+with the same server-side behavior as `t3 serve --tailscale-serve`, then the server asks Tailscale
+Serve to proxy HTTPS traffic to the local backend.
 
 The Tailscale support is an endpoint provider add-on. The core remote model still works without Tailscale: LAN HTTP endpoints, custom HTTPS endpoints, future tunnels, and SSH-launched environments all use the same saved environment and pairing flow.
 
@@ -75,6 +83,19 @@ From there, connect from another device in either of these ways:
 
 Use `t3 serve --help` for the full flag reference. It supports the same general startup options as the normal server command, including an optional `cwd` argument.
 
+For hosted web pairing over Tailscale HTTPS, opt in to Tailscale Serve:
+
+```bash
+npx t3 serve --tailscale-serve
+```
+
+By default this configures Tailscale Serve on HTTPS port 443 and advertises
+`https://machine.tailnet.ts.net/`. Advanced users can choose a different HTTPS port:
+
+```bash
+npx t3 serve --tailscale-serve --tailscale-serve-port 8443
+```
+
 > Note
 > The GUIs do not currently support adding projects on remote environments.
 > For now, use `t3 project ...` on the server machine instead.
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index db4f478798d..0e2aadaa00b 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -15,6 +15,7 @@
     "smoke-test": "node scripts/smoke-test.mjs"
   },
   "dependencies": {
+    "@effect/platform-node": "catalog:",
     "effect": "catalog:",
     "electron": "40.9.3",
     "electron-updater": "^6.6.2"
@@ -23,6 +24,7 @@
     "@t3tools/client-runtime": "workspace:*",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/shared": "workspace:*",
+    "@t3tools/tailscale": "workspace:*",
     "@types/node": "catalog:",
     "effect-acp": "workspace:*",
     "tsdown": "catalog:",
diff --git a/apps/desktop/src/desktopSettings.test.ts b/apps/desktop/src/desktopSettings.test.ts
index 9b467d22cab..c012e39b5f1 100644
--- a/apps/desktop/src/desktopSettings.test.ts
+++ b/apps/desktop/src/desktopSettings.test.ts
@@ -9,6 +9,7 @@ import {
   readDesktopSettings,
   resolveDefaultDesktopSettings,
   setDesktopServerExposurePreference,
+  setDesktopTailscaleServePreference,
   setDesktopUpdateChannelPreference,
   writeDesktopSettings,
 } from "./desktopSettings.ts";
@@ -35,6 +36,8 @@ describe("desktopSettings", () => {
   it("defaults packaged nightly builds to the nightly update channel", () => {
     expect(resolveDefaultDesktopSettings("0.0.17-nightly.20260415.1")).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "nightly",
       updateChannelConfiguredByUser: false,
     });
@@ -45,12 +48,16 @@ describe("desktopSettings", () => {
 
     writeDesktopSettings(settingsPath, {
       serverExposureMode: "network-accessible",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 8443,
       updateChannel: "latest",
       updateChannelConfiguredByUser: true,
     });
 
     expect(readDesktopSettings(settingsPath, "0.0.17")).toEqual({
       serverExposureMode: "network-accessible",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 8443,
       updateChannel: "latest",
       updateChannelConfiguredByUser: true,
     });
@@ -61,6 +68,8 @@ describe("desktopSettings", () => {
       setDesktopServerExposurePreference(
         {
           serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
           updateChannel: "latest",
           updateChannelConfiguredByUser: false,
         },
@@ -68,6 +77,29 @@ describe("desktopSettings", () => {
       ),
     ).toEqual({
       serverExposureMode: "network-accessible",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
+      updateChannel: "latest",
+      updateChannelConfiguredByUser: false,
+    });
+  });
+
+  it("persists the requested Tailscale Serve preference", () => {
+    expect(
+      setDesktopTailscaleServePreference(
+        {
+          serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: false,
+        },
+        { enabled: true, port: 8443 },
+      ),
+    ).toEqual({
+      serverExposureMode: "local-only",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 8443,
       updateChannel: "latest",
       updateChannelConfiguredByUser: false,
     });
@@ -78,6 +110,8 @@ describe("desktopSettings", () => {
       setDesktopUpdateChannelPreference(
         {
           serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
           updateChannel: "latest",
           updateChannelConfiguredByUser: false,
         },
@@ -85,6 +119,8 @@ describe("desktopSettings", () => {
       ),
     ).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "nightly",
       updateChannelConfiguredByUser: true,
     });
@@ -103,6 +139,8 @@ describe("desktopSettings", () => {
 
     expect(readDesktopSettings(settingsPath, "0.0.17-nightly.20260415.1")).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "nightly",
       updateChannelConfiguredByUser: false,
     });
@@ -121,6 +159,8 @@ describe("desktopSettings", () => {
 
     expect(readDesktopSettings(settingsPath, "0.0.17-nightly.20260415.1")).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "nightly",
       updateChannelConfiguredByUser: false,
     });
@@ -140,8 +180,30 @@ describe("desktopSettings", () => {
 
     expect(readDesktopSettings(settingsPath, "0.0.17-nightly.20260415.1")).toEqual({
       serverExposureMode: "local-only",
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       updateChannel: "latest",
       updateChannelConfiguredByUser: true,
     });
   });
+
+  it("falls back to the default Tailscale Serve port when the persisted port is invalid", () => {
+    const settingsPath = makeSettingsPath();
+    fs.writeFileSync(
+      settingsPath,
+      JSON.stringify({
+        tailscaleServeEnabled: true,
+        tailscaleServePort: 0,
+      }),
+      "utf8",
+    );
+
+    expect(readDesktopSettings(settingsPath, "0.0.17")).toEqual({
+      serverExposureMode: "local-only",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 443,
+      updateChannel: "latest",
+      updateChannelConfiguredByUser: false,
+    });
+  });
 });
diff --git a/apps/desktop/src/desktopSettings.ts b/apps/desktop/src/desktopSettings.ts
index 6ece5189cce..854c363e09d 100644
--- a/apps/desktop/src/desktopSettings.ts
+++ b/apps/desktop/src/desktopSettings.ts
@@ -6,12 +6,18 @@ import { resolveDefaultDesktopUpdateChannel } from "./updateChannels.ts";
 
 export interface DesktopSettings {
   readonly serverExposureMode: DesktopServerExposureMode;
+  readonly tailscaleServeEnabled: boolean;
+  readonly tailscaleServePort: number;
   readonly updateChannel: DesktopUpdateChannel;
   readonly updateChannelConfiguredByUser: boolean;
 }
 
+export const DEFAULT_TAILSCALE_SERVE_PORT = 443;
+
 export const DEFAULT_DESKTOP_SETTINGS: DesktopSettings = {
   serverExposureMode: "local-only",
+  tailscaleServeEnabled: false,
+  tailscaleServePort: DEFAULT_TAILSCALE_SERVE_PORT,
   updateChannel: "latest",
   updateChannelConfiguredByUser: false,
 };
@@ -35,6 +41,26 @@ export function setDesktopServerExposurePreference(
       };
 }
 
+export function setDesktopTailscaleServePreference(
+  settings: DesktopSettings,
+  input: { readonly enabled: boolean; readonly port?: number },
+): DesktopSettings {
+  const port = normalizeTailscaleServePort(input.port);
+  return settings.tailscaleServeEnabled === input.enabled && settings.tailscaleServePort === port
+    ? settings
+    : {
+        ...settings,
+        tailscaleServeEnabled: input.enabled,
+        tailscaleServePort: port,
+      };
+}
+
+export function normalizeTailscaleServePort(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 65_535
+    ? value
+    : DEFAULT_TAILSCALE_SERVE_PORT;
+}
+
 export function setDesktopUpdateChannelPreference(
   settings: DesktopSettings,
   requestedChannel: DesktopUpdateChannel,
@@ -57,6 +83,8 @@ export function readDesktopSettings(settingsPath: string, appVersion: string): D
     const raw = FS.readFileSync(settingsPath, "utf8");
     const parsed = JSON.parse(raw) as {
       readonly serverExposureMode?: unknown;
+      readonly tailscaleServeEnabled?: unknown;
+      readonly tailscaleServePort?: unknown;
       readonly updateChannel?: unknown;
       readonly updateChannelConfiguredByUser?: unknown;
     };
@@ -72,6 +100,8 @@ export function readDesktopSettings(settingsPath: string, appVersion: string): D
     return {
       serverExposureMode:
         parsed.serverExposureMode === "network-accessible" ? "network-accessible" : "local-only",
+      tailscaleServeEnabled: parsed.tailscaleServeEnabled === true,
+      tailscaleServePort: normalizeTailscaleServePort(parsed.tailscaleServePort),
       updateChannel:
         updateChannelConfiguredByUser && parsedUpdateChannel !== null
           ? parsedUpdateChannel
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 74baa16c54d..f80f34b2640 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -41,6 +41,7 @@ import {
   DEFAULT_DESKTOP_SETTINGS,
   readDesktopSettings,
   setDesktopServerExposurePreference,
+  setDesktopTailscaleServePreference,
   setDesktopUpdateChannelPreference,
   writeDesktopSettings,
 } from "./desktopSettings.ts";
@@ -107,6 +108,7 @@ const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secr
 const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
+const SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
 const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
 const BASE_DIR = process.env.T3CODE_HOME?.trim() || Path.join(OS.homedir(), ".t3");
 const STATE_DIR = Path.join(BASE_DIR, "userdata");
@@ -304,6 +306,8 @@ function backendChildEnv(): NodeJS.ProcessEnv {
   delete env.T3CODE_DESKTOP_LAN_ACCESS;
   delete env.T3CODE_DESKTOP_LAN_HOST;
   delete env.T3CODE_DESKTOP_HTTPS_ENDPOINTS;
+  delete env.T3CODE_TAILSCALE_SERVE;
+  delete env.T3CODE_TAILSCALE_SERVE_PORT;
   return env;
 }
 
@@ -312,6 +316,8 @@ function getDesktopServerExposureState(): DesktopServerExposureState {
     mode: desktopServerExposureMode,
     endpointUrl: backendEndpointUrl,
     advertisedHost: backendAdvertisedHost,
+    tailscaleServeEnabled: desktopSettings.tailscaleServeEnabled,
+    tailscaleServePort: desktopSettings.tailscaleServePort,
   };
 }
 
@@ -329,6 +335,8 @@ async function getDesktopAdvertisedEndpoints() {
   });
   const tailscaleEndpoints = await resolveTailscaleAdvertisedEndpoints({
     port: backendPort,
+    serveEnabled: desktopSettings.tailscaleServeEnabled,
+    servePort: desktopSettings.tailscaleServePort,
     networkInterfaces: OS.networkInterfaces(),
   });
   return [...coreEndpoints, ...tailscaleEndpoints];
@@ -394,6 +402,16 @@ async function applyDesktopServerExposureMode(
   return getDesktopServerExposureState();
 }
 
+async function applyDesktopTailscaleServeEnabled(input: {
+  readonly enabled: boolean;
+  readonly port?: number;
+}): Promise<DesktopServerExposureState> {
+  desktopSettings = setDesktopTailscaleServePreference(desktopSettings, input);
+  writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
+  relaunchDesktopApp(input.enabled ? "tailscale-serve-enabled" : "tailscale-serve-disabled");
+  return getDesktopServerExposureState();
+}
+
 function relaunchDesktopApp(reason: string): void {
   writeDesktopLogHeader(`desktop relaunch requested reason=${reason}`);
   setImmediate(() => {
@@ -1446,6 +1464,8 @@ function startBackend(): void {
         t3Home: BASE_DIR,
         host: backendBindHost,
         desktopBootstrapToken: backendBootstrapToken,
+        tailscaleServeEnabled: desktopSettings.tailscaleServeEnabled,
+        tailscaleServePort: desktopSettings.tailscaleServePort,
         ...(backendObservabilitySettings.otlpTracesUrl
           ? { otlpTracesUrl: backendObservabilitySettings.otlpTracesUrl }
           : {}),
@@ -1715,6 +1735,28 @@ function registerIpcHandlers(): void {
     return nextState;
   });
 
+  ipcMain.removeHandler(SET_TAILSCALE_SERVE_ENABLED_CHANNEL);
+  ipcMain.handle(SET_TAILSCALE_SERVE_ENABLED_CHANNEL, async (_event, rawInput: unknown) => {
+    if (typeof rawInput !== "object" || rawInput === null) {
+      throw new Error("Invalid Tailscale Serve input.");
+    }
+    const input = rawInput as { readonly enabled?: unknown; readonly port?: unknown };
+    if (typeof input.enabled !== "boolean") {
+      throw new Error("Invalid Tailscale Serve input.");
+    }
+    const nextSettings = setDesktopTailscaleServePreference(desktopSettings, {
+      enabled: input.enabled,
+      ...(typeof input.port === "number" ? { port: input.port } : {}),
+    });
+    if (nextSettings === desktopSettings) {
+      return getDesktopServerExposureState();
+    }
+    return applyDesktopTailscaleServeEnabled({
+      enabled: input.enabled,
+      port: nextSettings.tailscaleServePort,
+    });
+  });
+
   ipcMain.removeHandler(GET_ADVERTISED_ENDPOINTS_CHANNEL);
   ipcMain.handle(GET_ADVERTISED_ENDPOINTS_CHANNEL, async () => getDesktopAdvertisedEndpoints());
 
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index fdfaf20813f..d9ae6ed936a 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -32,6 +32,7 @@ const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
 const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
+const SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
 const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
 
 contextBridge.exposeInMainWorld("desktopBridge", {
@@ -86,6 +87,8 @@ contextBridge.exposeInMainWorld("desktopBridge", {
     ipcRenderer.invoke(RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL, requestId, password),
   getServerExposureState: () => ipcRenderer.invoke(GET_SERVER_EXPOSURE_STATE_CHANNEL),
   setServerExposureMode: (mode) => ipcRenderer.invoke(SET_SERVER_EXPOSURE_MODE_CHANNEL, mode),
+  setTailscaleServeEnabled: (input) =>
+    ipcRenderer.invoke(SET_TAILSCALE_SERVE_ENABLED_CHANNEL, input),
   getAdvertisedEndpoints: () => ipcRenderer.invoke(GET_ADVERTISED_ENDPOINTS_CHANNEL),
   pickFolder: (options) => ipcRenderer.invoke(PICK_FOLDER_CHANNEL, options),
   confirm: (message) => ipcRenderer.invoke(CONFIRM_CHANNEL, message),
diff --git a/apps/desktop/src/tailscaleEndpointProvider.test.ts b/apps/desktop/src/tailscaleEndpointProvider.test.ts
index d228a2c3bf1..2e92b7ee5d3 100644
--- a/apps/desktop/src/tailscaleEndpointProvider.test.ts
+++ b/apps/desktop/src/tailscaleEndpointProvider.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { Effect } from "effect";
 
 import {
   isTailscaleIpv4Address,
@@ -14,12 +15,14 @@ describe("tailscale endpoint provider", () => {
     expect(isTailscaleIpv4Address("192.168.1.44")).toBe(false);
   });
 
-  it("parses MagicDNS names from tailscale status", () => {
+  it("parses MagicDNS names from tailscale status", async () => {
     expect(
-      parseTailscaleMagicDnsName(JSON.stringify({ Self: { DNSName: "desktop.tail.ts.net." } })),
+      Effect.runSync(
+        parseTailscaleMagicDnsName(JSON.stringify({ Self: { DNSName: "desktop.tail.ts.net." } })),
+      ),
     ).toBe("desktop.tail.ts.net");
-    expect(parseTailscaleMagicDnsName("{}")).toBeNull();
-    expect(parseTailscaleMagicDnsName("not-json")).toBeNull();
+    expect(Effect.runSync(parseTailscaleMagicDnsName("{}"))).toBeNull();
+    await expect(Effect.runPromise(parseTailscaleMagicDnsName("not-json"))).rejects.toBeDefined();
   });
 
   it("resolves Tailscale endpoints as add-on advertised endpoints", async () => {
@@ -62,7 +65,7 @@ describe("tailscale endpoint provider", () => {
         description: "Reachable from devices on the same Tailnet.",
       },
       {
-        id: "tailscale-magicdns:https://desktop.tail.ts.net:3773",
+        id: "tailscale-magicdns:https://desktop.tail.ts.net/",
         label: "Tailscale HTTPS",
         provider: {
           id: "tailscale",
@@ -70,17 +73,50 @@ describe("tailscale endpoint provider", () => {
           kind: "private-network",
           isAddon: true,
         },
-        httpBaseUrl: "https://desktop.tail.ts.net:3773/",
-        wsBaseUrl: "wss://desktop.tail.ts.net:3773/",
+        httpBaseUrl: "https://desktop.tail.ts.net/",
+        wsBaseUrl: "wss://desktop.tail.ts.net/",
         reachability: "private-network",
         compatibility: {
           hostedHttpsApp: "requires-configuration",
           desktopApp: "compatible",
         },
         source: "desktop-addon",
-        status: "unknown",
+        status: "unavailable",
         description: "MagicDNS hostname. Configure Tailscale Serve for HTTPS access.",
       },
     ]);
   });
+
+  it("marks the Tailscale HTTPS endpoint available after Serve is enabled and reachable", async () => {
+    await expect(
+      resolveTailscaleAdvertisedEndpoints({
+        port: 3773,
+        networkInterfaces: {},
+        statusJson: JSON.stringify({ Self: { DNSName: "desktop.tail.ts.net." } }),
+        serveEnabled: true,
+        probe: async () => true,
+      }),
+    ).resolves.toEqual([
+      {
+        id: "tailscale-magicdns:https://desktop.tail.ts.net/",
+        label: "Tailscale HTTPS",
+        provider: {
+          id: "tailscale",
+          label: "Tailscale",
+          kind: "private-network",
+          isAddon: true,
+        },
+        httpBaseUrl: "https://desktop.tail.ts.net/",
+        wsBaseUrl: "wss://desktop.tail.ts.net/",
+        reachability: "private-network",
+        compatibility: {
+          hostedHttpsApp: "compatible",
+          desktopApp: "compatible",
+        },
+        source: "desktop-addon",
+        status: "available",
+        description: "HTTPS endpoint served by Tailscale Serve.",
+      },
+    ]);
+  });
 });
diff --git a/apps/desktop/src/tailscaleEndpointProvider.ts b/apps/desktop/src/tailscaleEndpointProvider.ts
index 75e3096d6b2..053eac5d442 100644
--- a/apps/desktop/src/tailscaleEndpointProvider.ts
+++ b/apps/desktop/src/tailscaleEndpointProvider.ts
@@ -1,11 +1,24 @@
-import * as ChildProcess from "node:child_process";
 import type { NetworkInterfaceInfo } from "node:os";
 
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeServices from "@effect/platform-node/NodeServices";
 import {
   createAdvertisedEndpoint,
   type CreateAdvertisedEndpointInput,
 } from "@t3tools/client-runtime";
 import type { AdvertisedEndpoint, AdvertisedEndpointProvider } from "@t3tools/contracts";
+import {
+  buildTailscaleHttpsBaseUrl,
+  isTailscaleIpv4Address,
+  parseTailscaleMagicDnsName,
+  probeTailscaleHttpsEndpoint,
+  readTailscaleStatus,
+} from "@t3tools/tailscale";
+import { Effect, Layer } from "effect";
+
+export { isTailscaleIpv4Address, parseTailscaleMagicDnsName } from "@t3tools/tailscale";
+
+const TailscaleDesktopLayer = Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici);
 
 const TAILSCALE_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
   id: "tailscale",
@@ -14,17 +27,6 @@ const TAILSCALE_ENDPOINT_PROVIDER: AdvertisedEndpointProvider = {
   isAddon: true,
 };
 
-const TAILSCALE_STATUS_TIMEOUT_MS = 1_500;
-
-interface TailscaleStatusSelf {
-  readonly DNSName?: unknown;
-  readonly TailscaleIPs?: unknown;
-}
-
-interface TailscaleStatusJson {
-  readonly Self?: TailscaleStatusSelf;
-}
-
 function createTailscaleEndpoint(
   input: Omit<CreateAdvertisedEndpointInput, "provider" | "source">,
 ): AdvertisedEndpoint {
@@ -35,24 +37,6 @@ function createTailscaleEndpoint(
   });
 }
 
-export function isTailscaleIpv4Address(address: string): boolean {
-  const parts = address.split(".");
-  if (parts.length !== 4) {
-    return false;
-  }
-  const [first, second, third, fourth] = parts.map((part) => Number.parseInt(part, 10));
-  if (
-    first === undefined ||
-    second === undefined ||
-    third === undefined ||
-    fourth === undefined ||
-    [first, second, third, fourth].some((part) => !Number.isInteger(part) || part < 0 || part > 255)
-  ) {
-    return false;
-  }
-  return first === 100 && second >= 64 && second <= 127;
-}
-
 export function resolveTailscaleIpAdvertisedEndpoints(input: {
   readonly port: number;
   readonly networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>;
@@ -86,72 +70,72 @@ export function resolveTailscaleIpAdvertisedEndpoints(input: {
   return endpoints;
 }
 
-export function parseTailscaleMagicDnsName(rawStatusJson: string): string | null {
-  let parsed: TailscaleStatusJson;
-  try {
-    parsed = JSON.parse(rawStatusJson) as TailscaleStatusJson;
-  } catch {
-    return null;
-  }
-
-  const dnsName = parsed.Self?.DNSName;
-  if (typeof dnsName !== "string") {
-    return null;
-  }
-
-  const normalized = dnsName.trim().replace(/\.$/u, "");
-  return normalized.length > 0 ? normalized : null;
-}
-
-export function resolveTailscaleMagicDnsAdvertisedEndpoint(input: {
+export async function resolveTailscaleMagicDnsAdvertisedEndpoint(input: {
   readonly dnsName: string | null;
-  readonly port: number;
-}): AdvertisedEndpoint | null {
+  readonly serveEnabled: boolean;
+  readonly servePort?: number;
+  readonly probe?: (baseUrl: string) => Promise<boolean>;
+}): Promise<AdvertisedEndpoint | null> {
   if (!input.dnsName) {
     return null;
   }
 
-  const httpBaseUrl = `https://${input.dnsName}:${input.port}`;
+  const httpBaseUrl = buildTailscaleHttpsBaseUrl({
+    magicDnsName: input.dnsName,
+    ...(input.servePort === undefined ? {} : { servePort: input.servePort }),
+  });
+  const isReachable = input.serveEnabled
+    ? await (input.probe?.(httpBaseUrl) ??
+        Effect.runPromise(
+          probeTailscaleHttpsEndpoint({ baseUrl: httpBaseUrl }).pipe(
+            Effect.provide(TailscaleDesktopLayer),
+          ),
+        ))
+    : false;
+
   return createTailscaleEndpoint({
     id: `tailscale-magicdns:${httpBaseUrl}`,
     label: "Tailscale HTTPS",
     httpBaseUrl,
     reachability: "private-network",
-    hostedHttpsCompatibility: "requires-configuration",
-    status: "unknown",
-    description: "MagicDNS hostname. Configure Tailscale Serve for HTTPS access.",
-  });
-}
-
-async function readTailscaleStatusJson(): Promise<string | null> {
-  return await new Promise((resolve) => {
-    const child = ChildProcess.execFile(
-      "tailscale",
-      ["status", "--json"],
-      { timeout: TAILSCALE_STATUS_TIMEOUT_MS, windowsHide: true },
-      (error, stdout) => {
-        if (error) {
-          resolve(null);
-          return;
-        }
-        resolve(stdout);
-      },
-    );
-    child.once("error", () => resolve(null));
+    hostedHttpsCompatibility: isReachable ? "compatible" : "requires-configuration",
+    status: isReachable ? "available" : "unavailable",
+    description: isReachable
+      ? "HTTPS endpoint served by Tailscale Serve."
+      : "MagicDNS hostname. Configure Tailscale Serve for HTTPS access.",
   });
 }
 
 export async function resolveTailscaleAdvertisedEndpoints(input: {
   readonly port: number;
+  readonly serveEnabled?: boolean;
+  readonly servePort?: number;
   readonly networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>;
   readonly statusJson?: string | null;
+  readonly probe?: (baseUrl: string) => Promise<boolean>;
 }): Promise<readonly AdvertisedEndpoint[]> {
   const ipEndpoints = resolveTailscaleIpAdvertisedEndpoints(input);
-  const statusJson =
-    input.statusJson === undefined ? await readTailscaleStatusJson() : input.statusJson;
-  const magicDnsEndpoint = resolveTailscaleMagicDnsAdvertisedEndpoint({
-    dnsName: statusJson ? parseTailscaleMagicDnsName(statusJson) : null,
-    port: input.port,
+  const dnsName =
+    input.statusJson === undefined
+      ? await Effect.runPromise(
+          readTailscaleStatus.pipe(
+            Effect.map((status) => status.magicDnsName),
+            Effect.catch(() => Effect.succeed(null)),
+            Effect.provide(TailscaleDesktopLayer),
+          ),
+        )
+      : input.statusJson
+        ? await Effect.runPromise(
+            parseTailscaleMagicDnsName(input.statusJson).pipe(
+              Effect.catch(() => Effect.succeed(null)),
+            ),
+          )
+        : null;
+  const magicDnsEndpoint = await resolveTailscaleMagicDnsAdvertisedEndpoint({
+    dnsName,
+    serveEnabled: input.serveEnabled === true,
+    ...(input.servePort === undefined ? {} : { servePort: input.servePort }),
+    ...(input.probe === undefined ? {} : { probe: input.probe }),
   });
 
   return magicDnsEndpoint ? [...ipEndpoints, magicDnsEndpoint] : ipEndpoints;
diff --git a/apps/server/package.json b/apps/server/package.json
index 13a8124cb26..c562e0401e4 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -40,6 +40,7 @@
     "@effect/vitest": "catalog:",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/shared": "workspace:*",
+    "@t3tools/tailscale": "workspace:*",
     "@t3tools/web": "workspace:*",
     "@types/bun": "catalog:",
     "@types/node": "catalog:",
diff --git a/apps/server/src/cli-config.test.ts b/apps/server/src/cli-config.test.ts
index 5adece73020..2e13d33aabf 100644
--- a/apps/server/src/cli-config.test.ts
+++ b/apps/server/src/cli-config.test.ts
@@ -46,6 +46,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -87,6 +89,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -108,6 +112,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.some(true),
           logWebSocketEvents: Option.some(true),
+          tailscaleServeEnabled: Option.some(true),
+          tailscaleServePort: Option.some(8443),
         },
         Option.some("Debug"),
       ).pipe(
@@ -149,6 +155,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: true,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: true,
+        tailscaleServePort: 8443,
       });
     }),
   );
@@ -161,6 +169,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         noBrowser: true,
         autoBootstrapProjectFromCwd: true,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
       const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:4173"));
 
@@ -176,6 +186,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.some(false),
           logWebSocketEvents: Option.some(false),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -212,6 +224,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -229,6 +243,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         noBrowser: true,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
         otlpTracesUrl: "http://localhost:4318/v1/traces",
         otlpMetricsUrl: "http://localhost:4318/v1/metrics",
       });
@@ -246,6 +262,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -281,6 +299,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
       assert.equal(join(baseDir, "dev"), resolved.stateDir);
     }),
@@ -305,6 +325,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -346,6 +368,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         noBrowser: false,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
       const derivedPaths = yield* deriveServerPaths(baseDir, new URL("http://127.0.0.1:4173"));
 
@@ -361,6 +385,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.some("Debug"),
       ).pipe(
@@ -399,6 +425,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: true,
         logWebSocketEvents: true,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -432,6 +460,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
       ).pipe(
@@ -463,6 +493,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
@@ -485,6 +517,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
           bootstrapFd: Option.none(),
           autoBootstrapProjectFromCwd: Option.none(),
           logWebSocketEvents: Option.none(),
+          tailscaleServeEnabled: Option.none(),
+          tailscaleServePort: Option.none(),
         },
         Option.none(),
         {
@@ -522,6 +556,8 @@ it.layer(NodeServices.layer)("cli config resolution", (it) => {
         desktopBootstrapToken: undefined,
         autoBootstrapProjectFromCwd: false,
         logWebSocketEvents: false,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       });
     }),
   );
diff --git a/apps/server/src/cli.test.ts b/apps/server/src/cli.test.ts
index 7ebde01067a..3ef8c441959 100644
--- a/apps/server/src/cli.test.ts
+++ b/apps/server/src/cli.test.ts
@@ -76,6 +76,8 @@ const makeCliTestServerConfig = (baseDir: string) =>
       desktopBootstrapToken: undefined,
       autoBootstrapProjectFromCwd: false,
       logWebSocketEvents: false,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
     } satisfies ServerConfigShape;
   });
 
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts
index 4fc23a1ded0..bcf8bee861c 100644
--- a/apps/server/src/cli.ts
+++ b/apps/server/src/cli.ts
@@ -78,6 +78,8 @@ const BootstrapEnvelopeSchema = Schema.Struct({
   desktopBootstrapToken: Schema.optional(Schema.String),
   autoBootstrapProjectFromCwd: Schema.optional(Schema.Boolean),
   logWebSocketEvents: Schema.optional(Schema.Boolean),
+  tailscaleServeEnabled: Schema.optional(Schema.Boolean),
+  tailscaleServePort: Schema.optional(PortSchema),
   otlpTracesUrl: Schema.optional(Schema.String),
   otlpMetricsUrl: Schema.optional(Schema.String),
 });
@@ -126,6 +128,17 @@ const logWebSocketEventsFlag = Flag.boolean("log-websocket-events").pipe(
   Flag.withAlias("log-ws-events"),
   Flag.optional,
 );
+const tailscaleServeFlag = Flag.boolean("tailscale-serve").pipe(
+  Flag.withDescription(
+    "Configure Tailscale Serve to expose this backend over HTTPS on the Tailnet.",
+  ),
+  Flag.optional,
+);
+const tailscaleServePortFlag = Flag.integer("tailscale-serve-port").pipe(
+  Flag.withSchema(PortSchema),
+  Flag.withDescription("HTTPS port for Tailscale Serve when --tailscale-serve is enabled."),
+  Flag.optional,
+);
 
 const EnvServerConfig = Config.all({
   logLevel: Config.logLevel("T3CODE_LOG_LEVEL").pipe(Config.withDefault("Info")),
@@ -174,6 +187,14 @@ const EnvServerConfig = Config.all({
     Config.option,
     Config.map(Option.getOrUndefined),
   ),
+  tailscaleServeEnabled: Config.boolean("T3CODE_TAILSCALE_SERVE").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
+  tailscaleServePort: Config.port("T3CODE_TAILSCALE_SERVE_PORT").pipe(
+    Config.option,
+    Config.map(Option.getOrUndefined),
+  ),
 });
 
 interface CliServerFlags {
@@ -187,6 +208,8 @@ interface CliServerFlags {
   readonly bootstrapFd: Option.Option<number>;
   readonly autoBootstrapProjectFromCwd: Option.Option<boolean>;
   readonly logWebSocketEvents: Option.Option<boolean>;
+  readonly tailscaleServeEnabled: Option.Option<boolean>;
+  readonly tailscaleServePort: Option.Option<number>;
 }
 
 interface CliAuthLocationFlags {
@@ -233,6 +256,8 @@ export const resolveServerConfig = (
       bootstrapFd: flags.bootstrapFd ?? Option.none(),
       autoBootstrapProjectFromCwd: flags.autoBootstrapProjectFromCwd ?? Option.none(),
       logWebSocketEvents: flags.logWebSocketEvents ?? Option.none(),
+      tailscaleServeEnabled: flags.tailscaleServeEnabled ?? Option.none(),
+      tailscaleServePort: flags.tailscaleServePort ?? Option.none(),
     } satisfies CliServerFlags;
     const bootstrapFd = Option.getOrUndefined(normalizedFlags.bootstrapFd) ?? env.bootstrapFd;
     const bootstrapEnvelope =
@@ -323,6 +348,22 @@ export const resolveServerConfig = (
       ),
       () => Boolean(devUrl),
     );
+    const tailscaleServeEnabled = Option.getOrElse(
+      resolveOptionPrecedence(
+        normalizedFlags.tailscaleServeEnabled,
+        Option.fromUndefinedOr(env.tailscaleServeEnabled),
+        Option.fromUndefinedOr(bootstrap?.tailscaleServeEnabled),
+      ),
+      () => false,
+    );
+    const tailscaleServePort = Option.getOrElse(
+      resolveOptionPrecedence(
+        normalizedFlags.tailscaleServePort,
+        Option.fromUndefinedOr(env.tailscaleServePort),
+        Option.fromUndefinedOr(bootstrap?.tailscaleServePort),
+      ),
+      () => 443,
+    );
     const staticDir = devUrl ? undefined : yield* resolveStaticDir();
     const host = Option.getOrElse(
       resolveOptionPrecedence(
@@ -365,6 +406,8 @@ export const resolveServerConfig = (
       desktopBootstrapToken,
       autoBootstrapProjectFromCwd,
       logWebSocketEvents,
+      tailscaleServeEnabled,
+      tailscaleServePort,
     };
 
     return config;
@@ -386,6 +429,8 @@ const resolveCliAuthConfig = (
       bootstrapFd: Option.none(),
       autoBootstrapProjectFromCwd: Option.none(),
       logWebSocketEvents: Option.none(),
+      tailscaleServeEnabled: Option.none(),
+      tailscaleServePort: Option.none(),
     },
     cliLogLevel,
   );
@@ -766,6 +811,8 @@ const sharedServerCommandFlags = {
   bootstrapFd: bootstrapFdFlag,
   autoBootstrapProjectFromCwd: autoBootstrapProjectFromCwdFlag,
   logWebSocketEvents: logWebSocketEventsFlag,
+  tailscaleServeEnabled: tailscaleServeFlag,
+  tailscaleServePort: tailscaleServePortFlag,
 } as const;
 
 const authLocationFlags = sharedServerLocationFlags;
diff --git a/apps/server/src/config.ts b/apps/server/src/config.ts
index 7840c761151..4d8e1cb7e79 100644
--- a/apps/server/src/config.ts
+++ b/apps/server/src/config.ts
@@ -65,6 +65,8 @@ export interface ServerConfigShape extends ServerDerivedPaths {
   readonly desktopBootstrapToken: string | undefined;
   readonly autoBootstrapProjectFromCwd: boolean;
   readonly logWebSocketEvents: boolean;
+  readonly tailscaleServeEnabled: boolean;
+  readonly tailscaleServePort: number;
 }
 
 export const deriveServerPaths = Effect.fn(function* (
@@ -158,6 +160,8 @@ export class ServerConfig extends Context.Service<ServerConfig, ServerConfigShap
           mode: "web",
           autoBootstrapProjectFromCwd: false,
           logWebSocketEvents: false,
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 443,
           port: 0,
           host: undefined,
           desktopBootstrapToken: undefined,
diff --git a/apps/server/src/environment/Layers/ServerEnvironment.test.ts b/apps/server/src/environment/Layers/ServerEnvironment.test.ts
index b899a4f9870..6b9ab90481c 100644
--- a/apps/server/src/environment/Layers/ServerEnvironment.test.ts
+++ b/apps/server/src/environment/Layers/ServerEnvironment.test.ts
@@ -30,6 +30,8 @@ const makeServerConfig = Effect.fn(function* (baseDir: string) {
     mode: "web",
     autoBootstrapProjectFromCwd: false,
     logWebSocketEvents: false,
+    tailscaleServeEnabled: false,
+    tailscaleServePort: 443,
     port: 0,
     host: undefined,
     desktopBootstrapToken: undefined,
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index 0cd23abc950..fcbf4d50010 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -371,6 +371,8 @@ const buildAppUnderTest = (options?: {
       desktopBootstrapToken: defaultDesktopBootstrapToken,
       autoBootstrapProjectFromCwd: false,
       logWebSocketEvents: false,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
       ...options?.config,
     };
     const layerConfig = Layer.succeed(ServerConfig, config);
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 4b31543e594..2b49113172e 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -81,6 +81,7 @@ import {
   orchestrationSnapshotRouteLayer,
 } from "./orchestration/http.ts";
 import { NetService } from "@t3tools/shared/Net";
+import { ensureTailscaleServe } from "@t3tools/tailscale";
 
 const PtyAdapterLive = Layer.unwrap(
   Effect.gen(function* () {
@@ -326,6 +327,29 @@ export const makeServerLayer = Layer.unwrap(
         () => clearPersistedServerRuntimeState(config.serverRuntimeStatePath),
       ),
     );
+    const tailscaleServeLayer = config.tailscaleServeEnabled
+      ? Layer.effectDiscard(
+          ensureTailscaleServe({
+            localPort: config.port,
+            servePort: config.tailscaleServePort,
+            localHost: "127.0.0.1",
+          }).pipe(
+            Effect.tap(() =>
+              Effect.logInfo("Tailscale Serve configured", {
+                localPort: config.port,
+                servePort: config.tailscaleServePort,
+              }),
+            ),
+            Effect.catch((cause) =>
+              Effect.logWarning("Failed to configure Tailscale Serve", {
+                cause,
+                localPort: config.port,
+                servePort: config.tailscaleServePort,
+              }),
+            ),
+          ),
+        )
+      : Layer.empty;
 
     const serverApplicationLayer = Layer.mergeAll(
       HttpRouter.serve(makeRoutesLayer, {
@@ -333,6 +357,7 @@ export const makeServerLayer = Layer.unwrap(
       }),
       httpListeningLayer,
       runtimeStateLayer,
+      tailscaleServeLayer,
     );
 
     return serverApplicationLayer.pipe(
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 95e504207d9..41ab20310ba 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1,5 +1,17 @@
-import { ChevronDownIcon, PlusIcon, QrCodeIcon, RefreshCwIcon } from "lucide-react";
-import { type ReactNode, memo, useCallback, useEffect, useMemo, useState } from "react";
+import {
+  ChevronDownIcon,
+  PlusIcon,
+  QrCodeIcon,
+  RefreshCwIcon,
+} from "lucide-react";
+import {
+  type ReactNode,
+  memo,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
 import {
   type AuthClientSession,
   type AuthPairingLink,
@@ -13,8 +25,14 @@ import { DateTime } from "effect";
 
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { cn } from "../../lib/utils";
-import { formatElapsedDurationLabel, formatExpiresInLabel } from "../../timestampFormat";
-import { resolveDesktopPairingUrl, resolveHostedPairingUrl } from "./pairingUrls";
+import {
+  formatElapsedDurationLabel,
+  formatExpiresInLabel,
+} from "../../timestampFormat";
+import {
+  resolveDesktopPairingUrl,
+  resolveHostedPairingUrl,
+} from "./pairingUrls";
 import {
   SettingsPageContainer,
   SettingsRow,
@@ -24,6 +42,7 @@ import {
 import { Input } from "../ui/input";
 import {
   Dialog,
+  DialogClose,
   DialogFooter,
   DialogDescription,
   DialogHeader,
@@ -77,6 +96,8 @@ import {
 } from "~/environments/runtime";
 import { useUiStateStore } from "~/uiStateStore";
 
+const DEFAULT_TAILSCALE_SERVE_PORT = 443;
+
 const accessTimestampFormatter = new Intl.DateTimeFormat(undefined, {
   dateStyle: "medium",
   timeStyle: "short",
@@ -111,7 +132,9 @@ function ConnectionStatusDot({
           )}
         />
       ) : null}
-      <span className={cn("relative inline-flex size-2 rounded-full", dotClassName)} />
+      <span
+        className={cn("relative inline-flex size-2 rounded-full", dotClassName)}
+      />
     </>
   );
 
@@ -137,7 +160,10 @@ function ConnectionStatusDot({
   return (
     <Tooltip>
       <TooltipTrigger render={dot} />
-      <TooltipPopup side="top" className="max-w-80 whitespace-pre-wrap leading-tight">
+      <TooltipPopup
+        side="top"
+        className="max-w-80 whitespace-pre-wrap leading-tight"
+      >
         {tooltipText}
       </TooltipPopup>
     </Tooltip>
@@ -153,7 +179,9 @@ function getSavedBackendStatusTooltip(
 
   if (connectionState === "connected") {
     const connectedAt = runtime?.connectedAt ?? record.lastConnectedAt;
-    return connectedAt ? `Connected for ${formatElapsedDurationLabel(connectedAt, nowMs)}` : null;
+    return connectedAt
+      ? `Connected for ${formatElapsedDurationLabel(connectedAt, nowMs)}`
+      : null;
   }
 
   if (connectionState === "connecting") {
@@ -169,8 +197,12 @@ function getSavedBackendStatusTooltip(
     : "Not connected yet.";
 }
 
-function formatDesktopSshTarget(target: NonNullable<SavedEnvironmentRecord["desktopSsh"]>): string {
-  const authority = target.username ? `${target.username}@${target.hostname}` : target.hostname;
+function formatDesktopSshTarget(
+  target: NonNullable<SavedEnvironmentRecord["desktopSsh"]>,
+): string {
+  const authority = target.username
+    ? `${target.username}@${target.hostname}`
+    : target.hostname;
   return target.port ? `${authority}:${target.port}` : authority;
 }
 
@@ -220,7 +252,10 @@ function parseManualDesktopSshTarget(input: {
     throw new Error("SSH host or alias is required.");
   }
 
-  if (port !== null && (!Number.isInteger(port) || port <= 0 || port > 65_535)) {
+  if (
+    port !== null &&
+    (!Number.isInteger(port) || port <= 0 || port > 65_535)
+  ) {
     throw new Error("SSH port must be between 1 and 65535.");
   }
 
@@ -233,19 +268,26 @@ function parseManualDesktopSshTarget(input: {
 }
 
 /** Direct row in the card – same pattern as the Provider / ACP-agent list rows. */
-const ITEM_ROW_CLASSNAME = "border-t border-border/60 px-4 py-4 first:border-t-0 sm:px-5";
-const ENDPOINT_ROW_CLASSNAME = "border-t border-border/60 px-4 py-2.5 first:border-t-0 sm:px-5";
+const ITEM_ROW_CLASSNAME =
+  "border-t border-border/60 px-4 py-4 first:border-t-0 sm:px-5";
+const ENDPOINT_ROW_CLASSNAME =
+  "border-t border-border/60 px-4 py-2.5 first:border-t-0 sm:px-5";
 
 const ITEM_ROW_INNER_CLASSNAME =
   "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between";
 
-function sortDesktopPairingLinks(links: ReadonlyArray<ServerPairingLinkRecord>) {
+function sortDesktopPairingLinks(
+  links: ReadonlyArray<ServerPairingLinkRecord>,
+) {
   return [...links].toSorted(
-    (left, right) => new Date(right.createdAt).getTime() - new Date(left.createdAt).getTime(),
+    (left, right) =>
+      new Date(right.createdAt).getTime() - new Date(left.createdAt).getTime(),
   );
 }
 
-function sortDesktopClientSessions(sessions: ReadonlyArray<ServerClientSessionRecord>) {
+function sortDesktopClientSessions(
+  sessions: ReadonlyArray<ServerClientSessionRecord>,
+) {
   return [...sessions].toSorted((left, right) => {
     if (left.current !== right.current) {
       return left.current ? -1 : 1;
@@ -253,11 +295,15 @@ function sortDesktopClientSessions(sessions: ReadonlyArray<ServerClientSessionRe
     if (left.connected !== right.connected) {
       return left.connected ? -1 : 1;
     }
-    return new Date(right.issuedAt).getTime() - new Date(left.issuedAt).getTime();
+    return (
+      new Date(right.issuedAt).getTime() - new Date(left.issuedAt).getTime()
+    );
   });
 }
 
-function toDesktopPairingLinkRecord(pairingLink: AuthPairingLink): ServerPairingLinkRecord {
+function toDesktopPairingLinkRecord(
+  pairingLink: AuthPairingLink,
+): ServerPairingLinkRecord {
   return {
     ...pairingLink,
     createdAt: DateTime.formatIso(pairingLink.createdAt),
@@ -265,7 +311,9 @@ function toDesktopPairingLinkRecord(pairingLink: AuthPairingLink): ServerPairing
   };
 }
 
-function toDesktopClientSessionRecord(clientSession: AuthClientSession): ServerClientSessionRecord {
+function toDesktopClientSessionRecord(
+  clientSession: AuthClientSession,
+): ServerClientSessionRecord {
   return {
     ...clientSession,
     issuedAt: DateTime.formatIso(clientSession.issuedAt),
@@ -281,7 +329,9 @@ function upsertDesktopPairingLink(
   current: ReadonlyArray<ServerPairingLinkRecord>,
   next: ServerPairingLinkRecord,
 ) {
-  const existingIndex = current.findIndex((pairingLink) => pairingLink.id === next.id);
+  const existingIndex = current.findIndex(
+    (pairingLink) => pairingLink.id === next.id,
+  );
   if (existingIndex === -1) {
     return sortDesktopPairingLinks([...current, next]);
   }
@@ -290,7 +340,10 @@ function upsertDesktopPairingLink(
   return sortDesktopPairingLinks(updated);
 }
 
-function removeDesktopPairingLink(current: ReadonlyArray<ServerPairingLinkRecord>, id: string) {
+function removeDesktopPairingLink(
+  current: ReadonlyArray<ServerPairingLinkRecord>,
+  id: string,
+) {
   return current.filter((pairingLink) => pairingLink.id !== id);
 }
 
@@ -313,30 +366,43 @@ function removeDesktopClientSession(
   current: ReadonlyArray<ServerClientSessionRecord>,
   sessionId: ServerClientSessionRecord["sessionId"],
 ) {
-  return current.filter((clientSession) => clientSession.sessionId !== sessionId);
+  return current.filter(
+    (clientSession) => clientSession.sessionId !== sessionId,
+  );
 }
 
 function selectPairingEndpoint(
   endpoints: ReadonlyArray<AdvertisedEndpoint>,
   defaultEndpointKey?: string | null,
 ): AdvertisedEndpoint | null {
-  const availableEndpoints = endpoints.filter((endpoint) => endpoint.status !== "unavailable");
+  const availableEndpoints = endpoints.filter(
+    (endpoint) => endpoint.status !== "unavailable",
+  );
   if (defaultEndpointKey) {
     const selectedEndpoint = availableEndpoints.find(
-      (endpoint) => endpointDefaultPreferenceKey(endpoint) === defaultEndpointKey,
+      (endpoint) =>
+        endpointDefaultPreferenceKey(endpoint) === defaultEndpointKey,
     );
     if (selectedEndpoint) {
       return selectedEndpoint;
     }
   }
   return (
-    availableEndpoints.find((endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible") ??
     availableEndpoints.find((endpoint) => endpoint.isDefault) ??
-    availableEndpoints.find((endpoint) => endpoint.reachability !== "loopback") ??
+    availableEndpoints.find(
+      (endpoint) => endpoint.reachability !== "loopback",
+    ) ??
+    availableEndpoints.find(
+      (endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible",
+    ) ??
     null
   );
 }
 
+function isTailscaleHttpsEndpoint(endpoint: AdvertisedEndpoint): boolean {
+  return endpoint.id.startsWith("tailscale-magicdns:");
+}
+
 function endpointDefaultPreferenceKey(endpoint: AdvertisedEndpoint): string {
   if (endpoint.id.startsWith("desktop-loopback:")) {
     return "desktop-core:loopback:http";
@@ -347,7 +413,7 @@ function endpointDefaultPreferenceKey(endpoint: AdvertisedEndpoint): string {
   if (endpoint.id.startsWith("tailscale-ip:")) {
     return "tailscale:ip:http";
   }
-  if (endpoint.id.startsWith("tailscale-magicdns:")) {
+  if (isTailscaleHttpsEndpoint(endpoint)) {
     return "tailscale:magicdns:https";
   }
 
@@ -379,6 +445,15 @@ function resolveCurrentOriginPairingUrl(credential: string): string {
   return setPairingTokenOnUrl(url, credential).toString();
 }
 
+function isHostedAppPairingUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.pathname === "/pair" && url.searchParams.has("host");
+  } catch {
+    return false;
+  }
+}
+
 type PairingLinkListRowProps = {
   pairingLink: ServerPairingLinkRecord;
   endpointUrl: string | null | undefined;
@@ -416,27 +491,44 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
   );
   const endpointPairingUrl = useMemo(() => {
     const endpoint = selectPairingEndpoint(endpoints, defaultEndpointKey);
-    return endpoint ? resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential) : null;
+    return endpoint
+      ? resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential)
+      : null;
   }, [defaultEndpointKey, endpoints, pairingLink.credential]);
   const endpointCopyOptions = useMemo(
     () =>
       endpoints
         .filter((endpoint) => endpoint.status !== "unavailable")
-        .map((endpoint) => ({
-          key: endpointDefaultPreferenceKey(endpoint),
-          label: endpoint.label,
-          url: resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential),
-        })),
+        .map((endpoint) => {
+          const url = resolveAdvertisedEndpointPairingUrl(
+            endpoint,
+            pairingLink.credential,
+          );
+          return {
+            key: endpointDefaultPreferenceKey(endpoint),
+            label: endpoint.label,
+            url,
+            detail: isHostedAppPairingUrl(url)
+              ? "Hosted app link"
+              : "Backend pairing URL",
+          };
+        }),
     [endpoints, pairingLink.credential],
   );
   const shareablePairingUrl =
     endpointPairingUrl ??
     (endpointUrl != null && endpointUrl !== ""
-      ? (hostedPairingUrl ?? resolveDesktopPairingUrl(endpointUrl, pairingLink.credential))
+      ? (hostedPairingUrl ??
+        resolveDesktopPairingUrl(endpointUrl, pairingLink.credential))
       : isLoopbackHostname(window.location.hostname)
         ? null
         : currentOriginPairingUrl);
   const revealValue = shareablePairingUrl ?? pairingLink.credential;
+  const isShareableHostedAppPairingUrl =
+    shareablePairingUrl !== null && isHostedAppPairingUrl(shareablePairingUrl);
+  const copyLinkLabel = isShareableHostedAppPairingUrl
+    ? "Copy hosted app link"
+    : "Copy pairing URL";
   const canCopyToClipboard =
     typeof window !== "undefined" &&
     window.isSecureContext &&
@@ -463,7 +555,9 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
               ? "Could not copy pairing URL"
               : "Could not copy pairing code"
             : "Clipboard copy unavailable",
-          description: canCopyToClipboard ? error.message : "Showing the full value instead.",
+          description: canCopyToClipboard
+            ? error.message
+            : "Showing the full value instead.",
         }),
       );
     },
@@ -503,7 +597,9 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
               tooltipText={`Link created at ${formatAccessTimestamp(pairingLink.createdAt)}`}
               dotClassName="bg-amber-400"
             />
-            <h3 className="text-sm font-medium text-foreground">{primaryLabel}</h3>
+            <h3 className="text-sm font-medium text-foreground">
+              {primaryLabel}
+            </h3>
             <Popover>
               {shareablePairingUrl ? (
                 <>
@@ -521,7 +617,12 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                   >
                     <QrCodeIcon aria-hidden className="size-3" />
                   </PopoverTrigger>
-                  <PopoverPopup side="top" align="start" tooltipStyle className="w-max">
+                  <PopoverPopup
+                    side="top"
+                    align="start"
+                    tooltipStyle
+                    className="w-max"
+                  >
                     <QRCodeSvg
                       value={shareablePairingUrl}
                       size={88}
@@ -535,16 +636,23 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
             </Popover>
           </div>
           <p className="text-xs text-muted-foreground" title={expiresAbsolute}>
-            {[roleLabel, formatExpiresInLabel(pairingLink.expiresAt, nowMs)].join(" · ")}
+            {[
+              roleLabel,
+              formatExpiresInLabel(pairingLink.expiresAt, nowMs),
+            ].join(" · ")}
           </p>
           {shareablePairingUrl === null ? (
             <p className="text-[11px] text-muted-foreground/70">
-              Copy the token and pair from another client using this backend&apos;s reachable host.
+              Copy the token and pair from another client using this
+              backend&apos;s reachable host.
             </p>
           ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
-          <Dialog open={isRevealDialogOpen} onOpenChange={setIsRevealDialogOpen}>
+          <Dialog
+            open={isRevealDialogOpen}
+            onOpenChange={setIsRevealDialogOpen}
+          >
             {canCopyToClipboard ? (
               <>
                 <Button size="xs" variant="outline" onClick={handleCopyCode}>
@@ -553,8 +661,12 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                 {shareablePairingUrl ? (
                   endpointCopyOptions.length > 1 ? (
                     <Group aria-label="Copy pairing URL">
-                      <Button size="xs" variant="outline" onClick={handleCopyDefaultLink}>
-                        Copy pairing URL
+                      <Button
+                        size="xs"
+                        variant="outline"
+                        onClick={handleCopyDefaultLink}
+                      >
+                        {copyLinkLabel}
                       </Button>
                       <GroupSeparator />
                       <Menu>
@@ -573,12 +685,16 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                           {endpointCopyOptions.map((option) => (
                             <MenuItem
                               key={option.key}
-                              onClick={() => copyPairingValue(option.url, "link")}
+                              onClick={() =>
+                                copyPairingValue(option.url, "link")
+                              }
                             >
                               <span className="min-w-0 flex-1">
-                                <span className="block truncate">{option.label}</span>
+                                <span className="block truncate">
+                                  {option.label}
+                                </span>
                                 <span className="block truncate text-[11px] text-muted-foreground">
-                                  Pairing URL
+                                  {option.detail}
                                 </span>
                               </span>
                             </MenuItem>
@@ -587,8 +703,12 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                       </Menu>
                     </Group>
                   ) : (
-                    <Button size="xs" variant="outline" onClick={handleCopyDefaultLink}>
-                      Copy pairing URL
+                    <Button
+                      size="xs"
+                      variant="outline"
+                      onClick={handleCopyDefaultLink}
+                    >
+                      {copyLinkLabel}
                     </Button>
                   )
                 ) : null}
@@ -600,10 +720,18 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
             )}
             <DialogPopup className="max-w-md">
               <DialogHeader>
-                <DialogTitle>{shareablePairingUrl ? "Pairing link" : "Pairing code"}</DialogTitle>
+                <DialogTitle>
+                  {shareablePairingUrl
+                    ? isShareableHostedAppPairingUrl
+                      ? "Hosted app pairing link"
+                      : "Pairing link"
+                    : "Pairing code"}
+                </DialogTitle>
                 <DialogDescription>
                   {shareablePairingUrl
-                    ? "Clipboard copy is unavailable here. Open or manually copy this full pairing URL on the device you want to connect."
+                    ? isShareableHostedAppPairingUrl
+                      ? "Clipboard copy is unavailable here. Open or manually copy this hosted app link on the device you want to connect."
+                      : "Clipboard copy is unavailable here. Open or manually copy this full pairing URL on the device you want to connect."
                     : "Clipboard copy is unavailable here. Manually copy this code into another client."}
                 </DialogDescription>
               </DialogHeader>
@@ -629,7 +757,10 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                 ) : null}
               </DialogPanel>
               <DialogFooter variant="bare">
-                <Button variant="outline" onClick={() => setIsRevealDialogOpen(false)}>
+                <Button
+                  variant="outline"
+                  onClick={() => setIsRevealDialogOpen(false)}
+                >
                   Done
                 </Button>
                 {canCopyToClipboard ? (
@@ -678,7 +809,8 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
   const roleLabel = clientSession.role === "owner" ? "Owner" : "Client";
   const deviceInfoBits = [
     clientSession.client.deviceType !== "unknown"
-      ? clientSession.client.deviceType[0]?.toUpperCase() + clientSession.client.deviceType.slice(1)
+      ? clientSession.client.deviceType[0]?.toUpperCase() +
+        clientSession.client.deviceType.slice(1)
       : null,
     clientSession.client.os ?? null,
     clientSession.client.browser ?? null,
@@ -686,7 +818,9 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
   ].filter((value): value is string => value !== null);
   const primaryLabel =
     clientSession.client.label ??
-    ([clientSession.client.os, clientSession.client.browser].filter(Boolean).join(" · ") ||
+    ([clientSession.client.os, clientSession.client.browser]
+      .filter(Boolean)
+      .join(" · ") ||
       clientSession.subject);
 
   return (
@@ -699,7 +833,9 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
               dotClassName={isLive ? "bg-success" : "bg-muted-foreground/30"}
               pingClassName={isLive ? "bg-success/60 duration-2000" : null}
             />
-            <h3 className="text-sm font-medium text-foreground">{primaryLabel}</h3>
+            <h3 className="text-sm font-medium text-foreground">
+              {primaryLabel}
+            </h3>
             {clientSession.current ? (
               <span className="text-[10px] text-muted-foreground/80 rounded-md border border-border/50 bg-muted/50 px-1 py-0.5">
                 This device
@@ -718,7 +854,9 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
               disabled={revokingClientSessionId === clientSession.sessionId}
               onClick={() => void onRevokeSession(clientSession.sessionId)}
             >
-              {revokingClientSessionId === clientSession.sessionId ? "Revoking…" : "Revoke"}
+              {revokingClientSessionId === clientSession.sessionId
+                ? "Revoking…"
+                : "Revoke"}
             </Button>
           ) : null}
         </div>
@@ -733,103 +871,112 @@ type AuthorizedClientsHeaderActionProps = {
   onRevokeOtherClients: () => void;
 };
 
-const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderAction({
-  clientSessions,
-  isRevokingOtherClients,
-  onRevokeOtherClients,
-}: AuthorizedClientsHeaderActionProps) {
-  const [dialogOpen, setDialogOpen] = useState(false);
-  const [pairingLabel, setPairingLabel] = useState("");
-  const [isCreatingPairingLink, setIsCreatingPairingLink] = useState(false);
-
-  const handleCreatePairingLink = useCallback(async () => {
-    setIsCreatingPairingLink(true);
-    try {
-      await createServerPairingCredential(pairingLabel);
-      setPairingLabel("");
-      setDialogOpen(false);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to create pairing URL.";
-      toastManager.add(
-        stackedThreadToast({
-          type: "error",
-          title: "Could not create pairing URL",
-          description: message,
-        }),
-      );
-    } finally {
-      setIsCreatingPairingLink(false);
-    }
-  }, [pairingLabel]);
+const AuthorizedClientsHeaderAction = memo(
+  function AuthorizedClientsHeaderAction({
+    clientSessions,
+    isRevokingOtherClients,
+    onRevokeOtherClients,
+  }: AuthorizedClientsHeaderActionProps) {
+    const [dialogOpen, setDialogOpen] = useState(false);
+    const [pairingLabel, setPairingLabel] = useState("");
+    const [isCreatingPairingLink, setIsCreatingPairingLink] = useState(false);
+
+    const handleCreatePairingLink = useCallback(async () => {
+      setIsCreatingPairingLink(true);
+      try {
+        await createServerPairingCredential(pairingLabel);
+        setPairingLabel("");
+        setDialogOpen(false);
+      } catch (error) {
+        const message =
+          error instanceof Error
+            ? error.message
+            : "Failed to create pairing URL.";
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not create pairing URL",
+            description: message,
+          }),
+        );
+      } finally {
+        setIsCreatingPairingLink(false);
+      }
+    }, [pairingLabel]);
 
-  return (
-    <div className="flex items-center gap-2">
-      <Button
-        size="xs"
-        variant="destructive-outline"
-        disabled={
-          isRevokingOtherClients || clientSessions.every((clientSession) => clientSession.current)
-        }
-        onClick={() => void onRevokeOtherClients()}
-      >
-        {isRevokingOtherClients ? "Revoking…" : "Revoke others"}
-      </Button>
-      <Dialog
-        open={dialogOpen}
-        onOpenChange={(open) => {
-          setDialogOpen(open);
-          if (!open) {
-            setPairingLabel("");
-          }
-        }}
-      >
-        <DialogTrigger
-          render={
-            <Button size="xs" variant="default">
-              <PlusIcon className="size-3" />
-              Create link
-            </Button>
+    return (
+      <div className="flex items-center gap-2">
+        <Button
+          size="xs"
+          variant="destructive-outline"
+          disabled={
+            isRevokingOtherClients ||
+            clientSessions.every((clientSession) => clientSession.current)
           }
-        />
-        <DialogPopup className="max-w-sm">
-          <DialogHeader>
-            <DialogTitle>Create pairing link</DialogTitle>
-            <DialogDescription>
-              Generate a one-time link that another device can use to pair with this backend as an
-              authorized client.
-            </DialogDescription>
-          </DialogHeader>
-          <DialogPanel>
-            <label className="block">
-              <span className="mb-1.5 block text-xs font-medium text-foreground">
-                Client label (optional)
-              </span>
-              <Input
-                value={pairingLabel}
-                onChange={(event) => setPairingLabel(event.target.value)}
-                placeholder="e.g. Living room iPad"
+          onClick={() => void onRevokeOtherClients()}
+        >
+          {isRevokingOtherClients ? "Revoking…" : "Revoke others"}
+        </Button>
+        <Dialog
+          open={dialogOpen}
+          onOpenChange={(open) => {
+            setDialogOpen(open);
+            if (!open) {
+              setPairingLabel("");
+            }
+          }}
+        >
+          <DialogTrigger
+            render={
+              <Button size="xs" variant="default">
+                <PlusIcon className="size-3" />
+                Create link
+              </Button>
+            }
+          />
+          <DialogPopup className="max-w-sm">
+            <DialogHeader>
+              <DialogTitle>Create pairing link</DialogTitle>
+              <DialogDescription>
+                Generate a one-time link that another device can use to pair
+                with this backend as an authorized client.
+              </DialogDescription>
+            </DialogHeader>
+            <DialogPanel>
+              <label className="block">
+                <span className="mb-1.5 block text-xs font-medium text-foreground">
+                  Client label (optional)
+                </span>
+                <Input
+                  value={pairingLabel}
+                  onChange={(event) => setPairingLabel(event.target.value)}
+                  placeholder="e.g. Living room iPad"
+                  disabled={isCreatingPairingLink}
+                  autoFocus
+                />
+              </label>
+            </DialogPanel>
+            <DialogFooter variant="bare">
+              <Button
+                variant="outline"
                 disabled={isCreatingPairingLink}
-                autoFocus
-              />
-            </label>
-          </DialogPanel>
-          <DialogFooter variant="bare">
-            <Button
-              variant="outline"
-              disabled={isCreatingPairingLink}
-              onClick={() => setDialogOpen(false)}
-            >
-              Cancel
-            </Button>
-            <Button disabled={isCreatingPairingLink} onClick={() => void handleCreatePairingLink()}>
-              {isCreatingPairingLink ? "Creating…" : "Create link"}
-            </Button>
-          </DialogFooter>
-        </DialogPopup>
-      </Dialog>
-    </div>
-  );
-});
+                onClick={() => setDialogOpen(false)}
+              >
+                Cancel
+              </Button>
+              <Button
+                disabled={isCreatingPairingLink}
+                onClick={() => void handleCreatePairingLink()}
+              >
+                {isCreatingPairingLink ? "Creating…" : "Create link"}
+              </Button>
+            </DialogFooter>
+          </DialogPopup>
+        </Dialog>
+      </div>
+    );
+  },
+);
 
 type PairingClientsListProps = {
   endpointUrl: string | null | undefined;
@@ -841,7 +988,9 @@ type PairingClientsListProps = {
   revokingPairingLinkId: string | null;
   revokingClientSessionId: string | null;
   onRevokePairingLink: (id: string) => void;
-  onRevokeClientSession: (sessionId: ServerClientSessionRecord["sessionId"]) => void;
+  onRevokeClientSession: (
+    sessionId: ServerClientSessionRecord["sessionId"],
+  ) => void;
 };
 
 const PairingClientsList = memo(function PairingClientsList({
@@ -879,9 +1028,13 @@ const PairingClientsList = memo(function PairingClientsList({
         />
       ))}
 
-      {pairingLinks.length === 0 && clientSessions.length === 0 && !isLoading ? (
+      {pairingLinks.length === 0 &&
+      clientSessions.length === 0 &&
+      !isLoading ? (
         <div className={ITEM_ROW_CLASSNAME}>
-          <p className="text-xs text-muted-foreground/60">No pairing links or client sessions.</p>
+          <p className="text-xs text-muted-foreground/60">
+            No pairing links or client sessions.
+          </p>
         </div>
       ) : null}
     </>
@@ -892,26 +1045,45 @@ type AdvertisedEndpointListRowProps = {
   endpoint: AdvertisedEndpoint;
   isDefault: boolean;
   onSetDefault: (endpoint: AdvertisedEndpoint) => void;
+  onSetupTailscaleServe: (endpoint: AdvertisedEndpoint) => void;
+  onDisableTailscaleServe: (endpoint: AdvertisedEndpoint) => void;
+  isUpdatingTailscaleServe: boolean;
 };
 
 const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
   endpoint,
   isDefault,
   onSetDefault,
+  onSetupTailscaleServe,
+  onDisableTailscaleServe,
+  isUpdatingTailscaleServe,
 }: AdvertisedEndpointListRowProps) {
+  const isAvailable = endpoint.status === "available";
+  const needsTailscaleSetup =
+    isTailscaleHttpsEndpoint(endpoint) && endpoint.status !== "available";
+  const canDisableTailscaleServe =
+    isTailscaleHttpsEndpoint(endpoint) && endpoint.status === "available";
+  const shouldShowEndpointUrl = !needsTailscaleSetup;
   return (
-    <div className={ENDPOINT_ROW_CLASSNAME}>
+    <div className={cn(ENDPOINT_ROW_CLASSNAME, !isAvailable && "bg-muted/24")}>
       <div className="flex min-h-6 min-w-0 flex-col gap-2 sm:-my-0.5 sm:flex-row sm:items-center">
         <div className="flex min-w-0 items-baseline gap-3">
           <h3 className="shrink-0 text-sm leading-5 font-medium text-foreground">
             {endpoint.label}
           </h3>
-          <p
-            className="min-w-0 truncate text-xs leading-5 text-muted-foreground"
-            title={endpoint.httpBaseUrl}
-          >
-            {endpoint.httpBaseUrl}
-          </p>
+          {shouldShowEndpointUrl ? (
+            <p
+              className="min-w-0 truncate text-xs leading-5 text-muted-foreground"
+              title={endpoint.httpBaseUrl}
+            >
+              {endpoint.httpBaseUrl}
+            </p>
+          ) : null}
+          {!isAvailable ? (
+            <span className="shrink-0 rounded-md border border-border/70 px-1 py-0.5 text-[10px] text-muted-foreground">
+              Setup required
+            </span>
+          ) : null}
         </div>
         <div className="ml-auto flex min-h-6 shrink-0 items-center justify-end gap-2">
           {isDefault ? (
@@ -919,8 +1091,32 @@ const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
               Default
             </span>
           ) : null}
-          {!isDefault ? (
-            <Button size="xs" variant="outline" onClick={() => onSetDefault(endpoint)}>
+          {needsTailscaleSetup ? (
+            <Button
+              size="xs"
+              variant="outline"
+              onClick={() => onSetupTailscaleServe(endpoint)}
+              disabled={isUpdatingTailscaleServe}
+            >
+              {isUpdatingTailscaleServe ? "Restarting…" : "Setup"}
+            </Button>
+          ) : null}
+          {canDisableTailscaleServe ? (
+            <Button
+              size="xs"
+              variant="destructive-outline"
+              onClick={() => onDisableTailscaleServe(endpoint)}
+              disabled={isUpdatingTailscaleServe}
+            >
+              {isUpdatingTailscaleServe ? "Restarting…" : "Disable"}
+            </Button>
+          ) : null}
+          {!needsTailscaleSetup && !isDefault ? (
+            <Button
+              size="xs"
+              variant="outline"
+              onClick={() => onSetDefault(endpoint)}
+            >
               Set as default
             </Button>
           ) : null}
@@ -947,19 +1143,34 @@ function NetworkAccessDescription({
     return fallback;
   }
 
+  const summary = (
+    <>
+      <span className="min-w-0 truncate">{endpoint.httpBaseUrl}</span>
+      {hiddenEndpointCount > 0 ? (
+        <span className="shrink-0 text-xs font-medium">
+          {expanded ? "Hide" : `+${hiddenEndpointCount}`}
+        </span>
+      ) : null}
+    </>
+  );
+
   return (
-    <span className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
-      <span className="min-w-0 truncate">Reachable at {endpoint.httpBaseUrl}</span>
+    <span className="inline-flex min-w-0 max-w-full items-baseline gap-1">
+      <span className="shrink-0">Reachable at</span>
       {hiddenEndpointCount > 0 ? (
         <button
           type="button"
-          className="inline-flex h-5 shrink-0 items-center rounded-md border border-border/60 px-1.5 text-[11px] font-medium text-muted-foreground hover:bg-accent hover:text-foreground"
+          className="inline-flex min-w-0 max-w-full items-baseline gap-2 border-b border-dotted border-muted-foreground/60 text-left text-muted-foreground underline-offset-4 hover:border-foreground hover:text-foreground"
           onClick={onToggleExpanded}
           aria-expanded={expanded}
         >
-          {expanded ? "Hide" : `+${hiddenEndpointCount}`}
+          {summary}
         </button>
-      ) : null}
+      ) : (
+        <span className="inline-flex min-w-0 max-w-full items-baseline gap-2">
+          {summary}
+        </span>
+      )}
     </span>
   );
 }
@@ -980,8 +1191,12 @@ function SavedBackendListRow({
   onRemove,
 }: SavedBackendListRowProps) {
   const nowMs = useRelativeTimeTick(1_000);
-  const record = useSavedEnvironmentRegistryStore((state) => state.byId[environmentId] ?? null);
-  const runtime = useSavedEnvironmentRuntimeStore((state) => state.byId[environmentId] ?? null);
+  const record = useSavedEnvironmentRegistryStore(
+    (state) => state.byId[environmentId] ?? null,
+  );
+  const runtime = useSavedEnvironmentRuntimeStore(
+    (state) => state.byId[environmentId] ?? null,
+  );
 
   if (!record) {
     return null;
@@ -996,11 +1211,17 @@ function SavedBackendListRow({
         : connectionState === "error"
           ? "bg-destructive"
           : "bg-muted-foreground/40";
-  const roleLabel = runtime?.role ? (runtime.role === "owner" ? "Owner" : "Client") : null;
+  const roleLabel = runtime?.role
+    ? runtime.role === "owner"
+      ? "Owner"
+      : "Client"
+    : null;
   const descriptorLabel = runtime?.descriptor?.label ?? null;
   const statusTooltip = getSavedBackendStatusTooltip(runtime, record, nowMs);
   const metadataBits = [
-    record.desktopSsh ? `SSH ${formatDesktopSshTarget(record.desktopSsh)}` : null,
+    record.desktopSsh
+      ? `SSH ${formatDesktopSshTarget(record.desktopSsh)}`
+      : null,
     roleLabel,
     record.lastConnectedAt
       ? `Last connected ${formatAccessTimestamp(record.lastConnectedAt)}`
@@ -1016,16 +1237,24 @@ function SavedBackendListRow({
               tooltipText={statusTooltip}
               dotClassName={stateDotClassName}
               pingClassName={
-                connectionState === "connecting" ? "bg-warning/60 duration-2000" : null
+                connectionState === "connecting"
+                  ? "bg-warning/60 duration-2000"
+                  : null
               }
             />
-            <h3 className="text-sm font-medium text-foreground">{record.label}</h3>
+            <h3 className="text-sm font-medium text-foreground">
+              {record.label}
+            </h3>
           </div>
           {metadataBits.length > 0 ? (
-            <p className="text-xs text-muted-foreground">{metadataBits.join(" · ")}</p>
+            <p className="text-xs text-muted-foreground">
+              {metadataBits.join(" · ")}
+            </p>
           ) : null}
           {descriptorLabel && descriptorLabel !== record.label ? (
-            <p className="text-xs text-muted-foreground">Server label: {descriptorLabel}</p>
+            <p className="text-xs text-muted-foreground">
+              Server label: {descriptorLabel}
+            </p>
           ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
@@ -1035,7 +1264,9 @@ function SavedBackendListRow({
             disabled={reconnectingEnvironmentId === environmentId}
             onClick={() => void onReconnect(environmentId)}
           >
-            {reconnectingEnvironmentId === environmentId ? "Reconnecting…" : "Reconnect"}
+            {reconnectingEnvironmentId === environmentId
+              ? "Reconnecting…"
+              : "Reconnect"}
           </Button>
           <Button
             size="xs"
@@ -1065,18 +1296,29 @@ const DesktopSshHostRow = memo(function DesktopSshHostRow({
   onConnect,
 }: DesktopSshHostRowProps) {
   const address = formatDesktopSshTarget(target);
-  const secondaryBits = [target.source === "ssh-config" ? "SSH config" : "Known hosts", address];
+  const secondaryBits = [
+    target.source === "ssh-config" ? "SSH config" : "Known hosts",
+    address,
+  ];
   const buttonLabel =
-    connectingHostAlias === target.alias ? "Connecting…" : savedRecord ? "Reconnect" : "Connect";
+    connectingHostAlias === target.alias
+      ? "Connecting…"
+      : savedRecord
+        ? "Reconnect"
+        : "Connect";
 
   return (
     <div className={ITEM_ROW_CLASSNAME}>
       <div className={ITEM_ROW_INNER_CLASSNAME}>
         <div className="min-w-0 flex-1 space-y-1">
           <div className="flex min-h-5 items-center gap-1.5">
-            <h3 className="text-sm font-medium text-foreground">{target.alias}</h3>
+            <h3 className="text-sm font-medium text-foreground">
+              {target.alias}
+            </h3>
           </div>
-          <p className="text-xs text-muted-foreground">{secondaryBits.join(" · ")}</p>
+          <p className="text-xs text-muted-foreground">
+            {secondaryBits.join(" · ")}
+          </p>
           {savedRecord ? (
             <p className="text-xs text-muted-foreground">
               Saved as {savedRecord.label}
@@ -1106,13 +1348,19 @@ const DesktopSshHostRow = memo(function DesktopSshHostRow({
 
 export function ConnectionsSettings() {
   const desktopBridge = window.desktopBridge;
-  const [currentSessionRole, setCurrentSessionRole] = useState<"owner" | "client" | null>(
-    desktopBridge ? "owner" : null,
-  );
+  const [currentSessionRole, setCurrentSessionRole] = useState<
+    "owner" | "client" | null
+  >(desktopBridge ? "owner" : null);
   const [currentAuthPolicy, setCurrentAuthPolicy] = useState<
-    "desktop-managed-local" | "loopback-browser" | "remote-reachable" | "unsafe-no-auth" | null
+    | "desktop-managed-local"
+    | "loopback-browser"
+    | "remote-reachable"
+    | "unsafe-no-auth"
+    | null
   >(desktopBridge ? null : null);
-  const savedEnvironmentsById = useSavedEnvironmentRegistryStore((state) => state.byId);
+  const savedEnvironmentsById = useSavedEnvironmentRegistryStore(
+    (state) => state.byId,
+  );
   const savedEnvironmentIds = useMemo(
     () =>
       Object.values(savedEnvironmentsById)
@@ -1122,52 +1370,60 @@ export function ConnectionsSettings() {
   );
   const savedDesktopSshEnvironmentsByAlias = useMemo(
     () =>
-      Object.values(savedEnvironmentsById).reduce<Record<string, SavedEnvironmentRecord>>(
-        (accumulator, record) => {
-          if (record.desktopSsh?.alias) {
-            accumulator[record.desktopSsh.alias] = record;
-          }
-          return accumulator;
-        },
-        {},
-      ),
+      Object.values(savedEnvironmentsById).reduce<
+        Record<string, SavedEnvironmentRecord>
+      >((accumulator, record) => {
+        if (record.desktopSsh?.alias) {
+          accumulator[record.desktopSsh.alias] = record;
+        }
+        return accumulator;
+      }, {}),
     [savedEnvironmentsById],
   );
   const [discoveredSshHosts, setDiscoveredSshHosts] = useState<
     ReadonlyArray<DesktopDiscoveredSshHost>
   >([]);
-  const [hasLoadedDiscoveredSshHosts, setHasLoadedDiscoveredSshHosts] = useState(false);
-  const [isLoadingDiscoveredSshHosts, setIsLoadingDiscoveredSshHosts] = useState(false);
-  const [discoveredSshHostsError, setDiscoveredSshHostsError] = useState<string | null>(null);
-  const [connectingSshHostAlias, setConnectingSshHostAlias] = useState<string | null>(null);
+  const [hasLoadedDiscoveredSshHosts, setHasLoadedDiscoveredSshHosts] =
+    useState(false);
+  const [isLoadingDiscoveredSshHosts, setIsLoadingDiscoveredSshHosts] =
+    useState(false);
+  const [discoveredSshHostsError, setDiscoveredSshHostsError] = useState<
+    string | null
+  >(null);
+  const [connectingSshHostAlias, setConnectingSshHostAlias] = useState<
+    string | null
+  >(null);
 
   const [desktopServerExposureState, setDesktopServerExposureState] =
     useState<DesktopServerExposureState | null>(null);
   const [desktopAdvertisedEndpoints, setDesktopAdvertisedEndpoints] = useState<
     ReadonlyArray<AdvertisedEndpoint>
   >([]);
-  const [desktopServerExposureError, setDesktopServerExposureError] = useState<string | null>(null);
+  const [desktopServerExposureError, setDesktopServerExposureError] = useState<
+    string | null
+  >(null);
   const [desktopPairingLinks, setDesktopPairingLinks] = useState<
     ReadonlyArray<ServerPairingLinkRecord>
   >([]);
   const [desktopClientSessions, setDesktopClientSessions] = useState<
     ReadonlyArray<ServerClientSessionRecord>
   >([]);
-  const [desktopAccessManagementError, setDesktopAccessManagementError] = useState<string | null>(
-    null,
-  );
-  const [isLoadingDesktopAccessManagement, setIsLoadingDesktopAccessManagement] = useState(false);
-  const [revokingDesktopPairingLinkId, setRevokingDesktopPairingLinkId] = useState<string | null>(
-    null,
-  );
-  const [revokingDesktopClientSessionId, setRevokingDesktopClientSessionId] = useState<
-    string | null
-  >(null);
-  const [isRevokingOtherDesktopClients, setIsRevokingOtherDesktopClients] = useState(false);
+  const [desktopAccessManagementError, setDesktopAccessManagementError] =
+    useState<string | null>(null);
+  const [
+    isLoadingDesktopAccessManagement,
+    setIsLoadingDesktopAccessManagement,
+  ] = useState(false);
+  const [revokingDesktopPairingLinkId, setRevokingDesktopPairingLinkId] =
+    useState<string | null>(null);
+  const [revokingDesktopClientSessionId, setRevokingDesktopClientSessionId] =
+    useState<string | null>(null);
+  const [isRevokingOtherDesktopClients, setIsRevokingOtherDesktopClients] =
+    useState(false);
   const [addBackendDialogOpen, setAddBackendDialogOpen] = useState(false);
-  const [savedBackendMode, setSavedBackendMode] = useState<"pairing-url" | "host-code" | "ssh">(
-    "pairing-url",
-  );
+  const [savedBackendMode, setSavedBackendMode] = useState<
+    "pairing-url" | "host-code" | "ssh"
+  >("pairing-url");
   const [savedBackendLabel, setSavedBackendLabel] = useState("");
   const [savedBackendPairingUrl, setSavedBackendPairingUrl] = useState("");
   const [savedBackendHost, setSavedBackendHost] = useState("");
@@ -1175,17 +1431,37 @@ export function ConnectionsSettings() {
   const [savedBackendSshHost, setSavedBackendSshHost] = useState("");
   const [savedBackendSshUsername, setSavedBackendSshUsername] = useState("");
   const [savedBackendSshPort, setSavedBackendSshPort] = useState("");
-  const [savedBackendError, setSavedBackendError] = useState<string | null>(null);
+  const [savedBackendError, setSavedBackendError] = useState<string | null>(
+    null,
+  );
   const [isAddingSavedBackend, setIsAddingSavedBackend] = useState(false);
   const [reconnectingSavedEnvironmentId, setReconnectingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
   const [removingSavedEnvironmentId, setRemovingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
-  const [isUpdatingDesktopServerExposure, setIsUpdatingDesktopServerExposure] = useState(false);
-  const [pendingDesktopServerExposureMode, setPendingDesktopServerExposureMode] = useState<
-    DesktopServerExposureState["mode"] | null
-  >(null);
-  const [isAdvertisedEndpointListExpanded, setIsAdvertisedEndpointListExpanded] = useState(false);
+  const [isUpdatingDesktopServerExposure, setIsUpdatingDesktopServerExposure] =
+    useState(false);
+  const [isUpdatingTailscaleServe, setIsUpdatingTailscaleServe] =
+    useState(false);
+  const [pendingTailscaleServeEndpoint, setPendingTailscaleServeEndpoint] =
+    useState<AdvertisedEndpoint | null>(null);
+  const [disableTailscaleServeDialogOpen, setDisableTailscaleServeDialogOpen] =
+    useState(false);
+  const [
+    pendingDisableTailscaleServeEndpoint,
+    setPendingDisableTailscaleServeEndpoint,
+  ] = useState<AdvertisedEndpoint | null>(null);
+  const [tailscaleServePortInput, setTailscaleServePortInput] = useState(
+    String(DEFAULT_TAILSCALE_SERVE_PORT),
+  );
+  const [
+    pendingDesktopServerExposureMode,
+    setPendingDesktopServerExposureMode,
+  ] = useState<DesktopServerExposureState["mode"] | null>(null);
+  const [
+    isAdvertisedEndpointListExpanded,
+    setIsAdvertisedEndpointListExpanded,
+  ] = useState(false);
   const defaultAdvertisedEndpointKey = useUiStateStore(
     (state) => state.defaultAdvertisedEndpointKey,
   );
@@ -1196,6 +1472,33 @@ export function ConnectionsSettings() {
   const isLocalBackendNetworkAccessible = desktopBridge
     ? desktopServerExposureState?.mode === "network-accessible"
     : currentAuthPolicy === "remote-reachable";
+  const trimmedTailscaleServePortInput = tailscaleServePortInput.trim();
+  const parsedTailscaleServePort = Number(trimmedTailscaleServePortInput);
+  const isTailscaleServePortValid =
+    /^\d+$/u.test(trimmedTailscaleServePortInput) &&
+    Number.isInteger(parsedTailscaleServePort) &&
+    parsedTailscaleServePort >= 1 &&
+    parsedTailscaleServePort <= 65_535;
+
+  const pendingTailscaleServeBaseUrl = useMemo(() => {
+    if (!pendingTailscaleServeEndpoint) return null;
+    if (!isTailscaleServePortValid)
+      return pendingTailscaleServeEndpoint.httpBaseUrl;
+    if (parsedTailscaleServePort === DEFAULT_TAILSCALE_SERVE_PORT) {
+      return pendingTailscaleServeEndpoint.httpBaseUrl;
+    }
+    try {
+      const url = new URL(pendingTailscaleServeEndpoint.httpBaseUrl);
+      url.port = String(parsedTailscaleServePort);
+      return url.toString().replace(/\/$/u, "");
+    } catch {
+      return pendingTailscaleServeEndpoint.httpBaseUrl;
+    }
+  }, [
+    isTailscaleServePortValid,
+    parsedTailscaleServePort,
+    pendingTailscaleServeEndpoint,
+  ]);
 
   const handleDesktopServerExposureChange = useCallback(
     async (checked: boolean) => {
@@ -1211,7 +1514,9 @@ export function ConnectionsSettings() {
         setIsUpdatingDesktopServerExposure(false);
       } catch (error) {
         const message =
-          error instanceof Error ? error.message : "Failed to update network exposure.";
+          error instanceof Error
+            ? error.message
+            : "Failed to update network exposure.";
         setPendingDesktopServerExposureMode(null);
         setDesktopServerExposureError(message);
         toastManager.add(
@@ -1233,13 +1538,98 @@ export function ConnectionsSettings() {
     void handleDesktopServerExposureChange(checked);
   }, [handleDesktopServerExposureChange, pendingDesktopServerExposureMode]);
 
+  const handleConfirmTailscaleServeSetup = useCallback(async () => {
+    if (!desktopBridge) return;
+    if (!isTailscaleServePortValid) return;
+    setIsUpdatingTailscaleServe(true);
+    setDesktopServerExposureError(null);
+    try {
+      const nextState = await desktopBridge.setTailscaleServeEnabled({
+        enabled: true,
+        port: parsedTailscaleServePort,
+      });
+      setDesktopServerExposureState(nextState);
+      setPendingTailscaleServeEndpoint(null);
+    } catch (error) {
+      const message =
+        error instanceof Error
+          ? error.message
+          : "Failed to configure Tailscale HTTPS.";
+      setDesktopServerExposureError(message);
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not set up Tailscale HTTPS",
+          description: message,
+        }),
+      );
+    } finally {
+      setIsUpdatingTailscaleServe(false);
+    }
+  }, [desktopBridge, isTailscaleServePortValid, parsedTailscaleServePort]);
+
+  const handleStartTailscaleServeSetup = useCallback(
+    (endpoint: AdvertisedEndpoint) => {
+      setTailscaleServePortInput(
+        String(
+          desktopServerExposureState?.tailscaleServePort ??
+            DEFAULT_TAILSCALE_SERVE_PORT,
+        ),
+      );
+      setPendingTailscaleServeEndpoint(endpoint);
+    },
+    [desktopServerExposureState?.tailscaleServePort],
+  );
+
+  const handleConfirmTailscaleServeDisable = useCallback(async () => {
+    if (!desktopBridge) return;
+    setIsUpdatingTailscaleServe(true);
+    setDesktopServerExposureError(null);
+    try {
+      const nextState = await desktopBridge.setTailscaleServeEnabled({
+        enabled: false,
+        port:
+          desktopServerExposureState?.tailscaleServePort ??
+          DEFAULT_TAILSCALE_SERVE_PORT,
+      });
+      setDesktopServerExposureState(nextState);
+      setDisableTailscaleServeDialogOpen(false);
+    } catch (error) {
+      const message =
+        error instanceof Error
+          ? error.message
+          : "Failed to disable Tailscale HTTPS.";
+      setDesktopServerExposureError(message);
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not disable Tailscale HTTPS",
+          description: message,
+        }),
+      );
+    } finally {
+      setIsUpdatingTailscaleServe(false);
+    }
+  }, [desktopBridge, desktopServerExposureState?.tailscaleServePort]);
+
+  const handleStartTailscaleServeDisable = useCallback(
+    (endpoint: AdvertisedEndpoint) => {
+      setPendingDisableTailscaleServeEndpoint(endpoint);
+      setDisableTailscaleServeDialogOpen(true);
+    },
+    [],
+  );
+
   const handleRevokeDesktopPairingLink = useCallback(async (id: string) => {
     setRevokingDesktopPairingLinkId(id);
     setDesktopAccessManagementError(null);
     try {
       await revokeServerPairingLink(id);
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to revoke pairing link.";
+      const message =
+        error instanceof Error
+          ? error.message
+          : "Failed to revoke pairing link.";
       setDesktopAccessManagementError(message);
       toastManager.add(
         stackedThreadToast({
@@ -1260,7 +1650,10 @@ export function ConnectionsSettings() {
       try {
         await revokeServerClientSession(sessionId);
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Failed to revoke client access.";
+        const message =
+          error instanceof Error
+            ? error.message
+            : "Failed to revoke client access.";
         setDesktopAccessManagementError(message);
         toastManager.add(
           stackedThreadToast({
@@ -1283,11 +1676,18 @@ export function ConnectionsSettings() {
       const revokedCount = await revokeOtherServerClientSessions();
       toastManager.add({
         type: "success",
-        title: revokedCount === 1 ? "Revoked 1 other client" : `Revoked ${revokedCount} clients`,
-        description: "Other paired clients will need a new pairing link before reconnecting.",
+        title:
+          revokedCount === 1
+            ? "Revoked 1 other client"
+            : `Revoked ${revokedCount} clients`,
+        description:
+          "Other paired clients will need a new pairing link before reconnecting.",
       });
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to revoke other clients.";
+      const message =
+        error instanceof Error
+          ? error.message
+          : "Failed to revoke other clients.";
       setDesktopAccessManagementError(message);
       toastManager.add(
         stackedThreadToast({
@@ -1329,7 +1729,10 @@ export function ConnectionsSettings() {
           description: `${record.label} is ready over an SSH-managed tunnel.`,
         });
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
+        const message =
+          error instanceof Error
+            ? error.message
+            : "Failed to connect SSH host.";
 
         setSavedBackendError(message);
         toastManager.add({
@@ -1369,7 +1772,8 @@ export function ConnectionsSettings() {
         description: `${record.label} is now saved and will reconnect on app startup.`,
       });
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to add backend.";
+      const message =
+        error instanceof Error ? error.message : "Failed to add backend.";
       setSavedBackendError(message);
       toastManager.add(
         stackedThreadToast({
@@ -1392,45 +1796,55 @@ export function ConnectionsSettings() {
     savedBackendSshUsername,
   ]);
 
-  const handleReconnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
-    setReconnectingSavedEnvironmentId(environmentId);
-    setSavedBackendError(null);
-    try {
-      await reconnectSavedEnvironment(environmentId);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to reconnect backend.";
-      setSavedBackendError(message);
-      toastManager.add(
-        stackedThreadToast({
-          type: "error",
-          title: "Could not reconnect backend",
-          description: message,
-        }),
-      );
-    } finally {
-      setReconnectingSavedEnvironmentId(null);
-    }
-  }, []);
+  const handleReconnectSavedBackend = useCallback(
+    async (environmentId: EnvironmentId) => {
+      setReconnectingSavedEnvironmentId(environmentId);
+      setSavedBackendError(null);
+      try {
+        await reconnectSavedEnvironment(environmentId);
+      } catch (error) {
+        const message =
+          error instanceof Error
+            ? error.message
+            : "Failed to reconnect backend.";
+        setSavedBackendError(message);
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not reconnect backend",
+            description: message,
+          }),
+        );
+      } finally {
+        setReconnectingSavedEnvironmentId(null);
+      }
+    },
+    [],
+  );
 
-  const handleRemoveSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
-    setRemovingSavedEnvironmentId(environmentId);
-    setSavedBackendError(null);
-    try {
-      await removeSavedEnvironment(environmentId);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to remove backend.";
-      setSavedBackendError(message);
-      toastManager.add(
-        stackedThreadToast({
-          type: "error",
-          title: "Could not remove backend",
-          description: message,
-        }),
-      );
-    } finally {
-      setRemovingSavedEnvironmentId(null);
-    }
-  }, []);
+  const handleRemoveSavedBackend = useCallback(
+    async (environmentId: EnvironmentId) => {
+      setRemovingSavedEnvironmentId(environmentId);
+      setSavedBackendError(null);
+      try {
+        await removeSavedEnvironment(environmentId);
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Failed to remove backend.";
+        setSavedBackendError(message);
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not remove backend",
+            description: message,
+          }),
+        );
+      } finally {
+        setRemovingSavedEnvironmentId(null);
+      }
+    },
+    [],
+  );
 
   const loadDiscoveredSshHosts = useCallback(async () => {
     if (!desktopBridge) {
@@ -1447,7 +1861,10 @@ export function ConnectionsSettings() {
       setDiscoveredSshHosts(hosts);
       setHasLoadedDiscoveredSshHosts(true);
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to discover SSH hosts.";
+      const message =
+        error instanceof Error
+          ? error.message
+          : "Failed to discover SSH hosts.";
       setDiscoveredSshHostsError(message);
       setHasLoadedDiscoveredSshHosts(true);
     } finally {
@@ -1481,7 +1898,10 @@ export function ConnectionsSettings() {
           description: `${record.label} is ready over an SSH-managed tunnel.`,
         });
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
+        const message =
+          error instanceof Error
+            ? error.message
+            : "Failed to connect SSH host.";
         if (savedBackendMode === "ssh") {
           setSavedBackendError(message);
         } else {
@@ -1526,7 +1946,9 @@ export function ConnectionsSettings() {
     void fetchSessionState()
       .then((session) => {
         if (cancelled) return;
-        setCurrentSessionRole(session.authenticated ? (session.role ?? null) : null);
+        setCurrentSessionRole(
+          session.authenticated ? (session.role ?? null) : null,
+        );
         setCurrentAuthPolicy(session.auth.policy);
       })
       .catch(() => {
@@ -1559,22 +1981,27 @@ export function ConnectionsSettings() {
             case "snapshot":
               setDesktopPairingLinks(
                 sortDesktopPairingLinks(
-                  event.payload.pairingLinks.map((pairingLink: AuthPairingLink) =>
-                    toDesktopPairingLinkRecord(pairingLink),
+                  event.payload.pairingLinks.map(
+                    (pairingLink: AuthPairingLink) =>
+                      toDesktopPairingLinkRecord(pairingLink),
                   ),
                 ),
               );
               setDesktopClientSessions(
                 sortDesktopClientSessions(
-                  event.payload.clientSessions.map((clientSession: AuthClientSession) =>
-                    toDesktopClientSessionRecord(clientSession),
+                  event.payload.clientSessions.map(
+                    (clientSession: AuthClientSession) =>
+                      toDesktopClientSessionRecord(clientSession),
                   ),
                 ),
               );
               break;
             case "pairingLinkUpserted":
               setDesktopPairingLinks((current) =>
-                upsertDesktopPairingLink(current, toDesktopPairingLinkRecord(event.payload)),
+                upsertDesktopPairingLink(
+                  current,
+                  toDesktopPairingLinkRecord(event.payload),
+                ),
               );
               break;
             case "pairingLinkRemoved":
@@ -1584,7 +2011,10 @@ export function ConnectionsSettings() {
               break;
             case "clientUpserted":
               setDesktopClientSessions((current) =>
-                upsertDesktopClientSession(current, toDesktopClientSessionRecord(event.payload)),
+                upsertDesktopClientSession(
+                  current,
+                  toDesktopClientSessionRecord(event.payload),
+                ),
               );
               break;
             case "clientRemoved":
@@ -1615,7 +2045,9 @@ export function ConnectionsSettings() {
         .catch((error: unknown) => {
           if (cancelled) return;
           const message =
-            error instanceof Error ? error.message : "Failed to load network exposure state.";
+            error instanceof Error
+              ? error.message
+              : "Failed to load network exposure state.";
           setDesktopServerExposureError(message);
         });
       void desktopBridge
@@ -1627,7 +2059,9 @@ export function ConnectionsSettings() {
         .catch((error: unknown) => {
           if (cancelled) return;
           const message =
-            error instanceof Error ? error.message : "Failed to load reachable endpoints.";
+            error instanceof Error
+              ? error.message
+              : "Failed to load reachable endpoints.";
           setDesktopServerExposureError(message);
         });
     } else {
@@ -1653,16 +2087,55 @@ export function ConnectionsSettings() {
     setDesktopServerExposureError(null);
   }, [canManageLocalBackend]);
   const visibleDesktopPairingLinks = useMemo(
-    () => desktopPairingLinks.filter((pairingLink) => pairingLink.role === "client"),
+    () =>
+      desktopPairingLinks.filter(
+        (pairingLink) => pairingLink.role === "client",
+      ),
     [desktopPairingLinks],
   );
-  const visibleDesktopAdvertisedEndpoints = useMemo(
-    () => (isLocalBackendNetworkAccessible ? desktopAdvertisedEndpoints : []),
+  const tailscaleHttpsEndpoint = useMemo(
+    () => desktopAdvertisedEndpoints.find(isTailscaleHttpsEndpoint) ?? null,
+    [desktopAdvertisedEndpoints],
+  );
+  const visibleDesktopNetworkAdvertisedEndpoints = useMemo(
+    () =>
+      isLocalBackendNetworkAccessible
+        ? desktopAdvertisedEndpoints.filter(
+            (endpoint) => !isTailscaleHttpsEndpoint(endpoint),
+          )
+        : [],
     [desktopAdvertisedEndpoints, isLocalBackendNetworkAccessible],
   );
+  const visibleDesktopAdvertisedEndpoints = useMemo(
+    () =>
+      tailscaleHttpsEndpoint
+        ? [...visibleDesktopNetworkAdvertisedEndpoints, tailscaleHttpsEndpoint]
+        : visibleDesktopNetworkAdvertisedEndpoints,
+    [tailscaleHttpsEndpoint, visibleDesktopNetworkAdvertisedEndpoints],
+  );
+  const isLocalBackendRemotelyReachable =
+    isLocalBackendNetworkAccessible ||
+    tailscaleHttpsEndpoint?.status === "available";
+  const defaultDesktopNetworkAdvertisedEndpoint = useMemo(
+    () =>
+      selectPairingEndpoint(
+        visibleDesktopNetworkAdvertisedEndpoints,
+        defaultAdvertisedEndpointKey,
+      ),
+    [defaultAdvertisedEndpointKey, visibleDesktopNetworkAdvertisedEndpoints],
+  );
   const defaultDesktopAdvertisedEndpoint = useMemo(
-    () => selectPairingEndpoint(visibleDesktopAdvertisedEndpoints, defaultAdvertisedEndpointKey),
-    [defaultAdvertisedEndpointKey, visibleDesktopAdvertisedEndpoints],
+    () =>
+      defaultDesktopNetworkAdvertisedEndpoint ??
+      selectPairingEndpoint(
+        tailscaleHttpsEndpoint ? [tailscaleHttpsEndpoint] : [],
+        defaultAdvertisedEndpointKey,
+      ),
+    [
+      defaultAdvertisedEndpointKey,
+      defaultDesktopNetworkAdvertisedEndpoint,
+      tailscaleHttpsEndpoint,
+    ],
   );
   const defaultDesktopAdvertisedEndpointKey = defaultDesktopAdvertisedEndpoint
     ? endpointDefaultPreferenceKey(defaultDesktopAdvertisedEndpoint)
@@ -1685,14 +2158,16 @@ export function ConnectionsSettings() {
                   description={
                     isLocalBackendNetworkAccessible ? (
                       <NetworkAccessDescription
-                        endpoint={defaultDesktopAdvertisedEndpoint}
+                        endpoint={defaultDesktopNetworkAdvertisedEndpoint}
                         hiddenEndpointCount={Math.max(
-                          visibleDesktopAdvertisedEndpoints.length - 1,
+                          visibleDesktopNetworkAdvertisedEndpoints.length - 1,
                           0,
                         )}
                         expanded={isAdvertisedEndpointListExpanded}
                         onToggleExpanded={() =>
-                          setIsAdvertisedEndpointListExpanded((expanded) => !expanded)
+                          setIsAdvertisedEndpointListExpanded(
+                            (expanded) => !expanded,
+                          )
                         }
                         fallback={
                           desktopServerExposureState?.endpointUrl
@@ -1710,7 +2185,9 @@ export function ConnectionsSettings() {
                   }
                   status={
                     desktopServerExposureError ? (
-                      <span className="block text-destructive">{desktopServerExposureError}</span>
+                      <span className="block text-destructive">
+                        {desktopServerExposureError}
+                      </span>
                     ) : null
                   }
                   control={
@@ -1722,8 +2199,14 @@ export function ConnectionsSettings() {
                       }}
                     >
                       <Switch
-                        checked={desktopServerExposureState?.mode === "network-accessible"}
-                        disabled={!desktopServerExposureState || isUpdatingDesktopServerExposure}
+                        checked={
+                          desktopServerExposureState?.mode ===
+                          "network-accessible"
+                        }
+                        disabled={
+                          !desktopServerExposureState ||
+                          isUpdatingDesktopServerExposure
+                        }
                         onCheckedChange={(checked) => {
                           setPendingDesktopServerExposureMode(
                             checked ? "network-accessible" : "local-only",
@@ -1734,12 +2217,14 @@ export function ConnectionsSettings() {
                       <AlertDialogPopup>
                         <AlertDialogHeader>
                           <AlertDialogTitle>
-                            {pendingDesktopServerExposureMode === "network-accessible"
+                            {pendingDesktopServerExposureMode ===
+                            "network-accessible"
                               ? "Enable network access?"
                               : "Disable network access?"}
                           </AlertDialogTitle>
                           <AlertDialogDescription>
-                            {pendingDesktopServerExposureMode === "network-accessible"
+                            {pendingDesktopServerExposureMode ===
+                            "network-accessible"
                               ? "T3 Code will restart to expose this environment over the network."
                               : "T3 Code will restart and limit this environment back to this machine."}
                           </AlertDialogDescription>
@@ -1757,6 +2242,11 @@ export function ConnectionsSettings() {
                             Cancel
                           </AlertDialogClose>
                           <Button
+                            variant={
+                              pendingDesktopServerExposureMode === "local-only"
+                                ? "destructive"
+                                : "default"
+                            }
                             onClick={handleConfirmDesktopServerExposureChange}
                             disabled={
                               pendingDesktopServerExposureMode === null ||
@@ -1768,7 +2258,8 @@ export function ConnectionsSettings() {
                                 <Spinner className="size-3.5" />
                                 Restarting…
                               </>
-                            ) : pendingDesktopServerExposureMode === "network-accessible" ? (
+                            ) : pendingDesktopServerExposureMode ===
+                              "network-accessible" ? (
                               "Restart and enable"
                             ) : (
                               "Restart and disable"
@@ -1780,18 +2271,192 @@ export function ConnectionsSettings() {
                   }
                 />
                 {isAdvertisedEndpointListExpanded
-                  ? visibleDesktopAdvertisedEndpoints.map((endpoint) => {
-                      const endpointKey = endpointDefaultPreferenceKey(endpoint);
+                  ? visibleDesktopNetworkAdvertisedEndpoints.map((endpoint) => {
+                      const endpointKey =
+                        endpointDefaultPreferenceKey(endpoint);
                       return (
                         <AdvertisedEndpointListRow
                           key={endpoint.id}
                           endpoint={endpoint}
-                          isDefault={endpointKey === defaultDesktopAdvertisedEndpointKey}
+                          isDefault={
+                            endpointKey === defaultDesktopAdvertisedEndpointKey
+                          }
                           onSetDefault={handleSetDefaultAdvertisedEndpoint}
+                          onSetupTailscaleServe={handleStartTailscaleServeSetup}
+                          onDisableTailscaleServe={
+                            handleStartTailscaleServeDisable
+                          }
+                          isUpdatingTailscaleServe={isUpdatingTailscaleServe}
                         />
                       );
                     })
                   : null}
+                <SettingsRow
+                  title="Tailscale HTTPS"
+                  description={
+                    tailscaleHttpsEndpoint
+                      ? tailscaleHttpsEndpoint.status === "available"
+                        ? tailscaleHttpsEndpoint.httpBaseUrl
+                        : "Use Tailscale Serve to expose this backend through a MagicDNS HTTPS URL."
+                      : "Start Tailscale to set up HTTPS access through MagicDNS."
+                  }
+                  control={
+                    tailscaleHttpsEndpoint ? (
+                      <Switch
+                        checked={tailscaleHttpsEndpoint.status === "available"}
+                        disabled={isUpdatingTailscaleServe}
+                        onCheckedChange={(checked) => {
+                          if (checked) {
+                            handleStartTailscaleServeSetup(
+                              tailscaleHttpsEndpoint,
+                            );
+                            return;
+                          }
+                          handleStartTailscaleServeDisable(
+                            tailscaleHttpsEndpoint,
+                          );
+                        }}
+                        aria-label="Enable Tailscale HTTPS"
+                      />
+                    ) : null
+                  }
+                />
+                <AlertDialog
+                  open={disableTailscaleServeDialogOpen}
+                  onOpenChange={(open) => {
+                    if (isUpdatingTailscaleServe) return;
+                    setDisableTailscaleServeDialogOpen(open);
+                  }}
+                  onOpenChangeComplete={(open) => {
+                    if (!open) {
+                      setPendingDisableTailscaleServeEndpoint(null);
+                    }
+                  }}
+                >
+                  <AlertDialogPopup>
+                    <AlertDialogHeader>
+                      <AlertDialogTitle>
+                        Disable Tailscale HTTPS?
+                      </AlertDialogTitle>
+                      <AlertDialogDescription>
+                        T3 Code will restart the local backend without Tailscale
+                        Serve.
+                      </AlertDialogDescription>
+                    </AlertDialogHeader>
+                    <AlertDialogFooter>
+                      <AlertDialogClose
+                        disabled={isUpdatingTailscaleServe}
+                        render={
+                          <Button
+                            variant="outline"
+                            disabled={isUpdatingTailscaleServe}
+                          />
+                        }
+                      >
+                        Cancel
+                      </AlertDialogClose>
+                      <Button
+                        variant="destructive"
+                        onClick={() =>
+                          void handleConfirmTailscaleServeDisable()
+                        }
+                        disabled={isUpdatingTailscaleServe}
+                      >
+                        {isUpdatingTailscaleServe ? (
+                          <>
+                            <Spinner className="size-3.5" />
+                            Restarting…
+                          </>
+                        ) : (
+                          "Restart and disable"
+                        )}
+                      </Button>
+                    </AlertDialogFooter>
+                  </AlertDialogPopup>
+                </AlertDialog>
+                <Dialog
+                  open={pendingTailscaleServeEndpoint !== null}
+                  onOpenChange={(open) => {
+                    if (isUpdatingTailscaleServe) return;
+                    if (!open) setPendingTailscaleServeEndpoint(null);
+                  }}
+                >
+                  <DialogPopup className="max-w-md">
+                    <DialogHeader>
+                      <DialogTitle>Set up Tailscale HTTPS?</DialogTitle>
+                      <DialogDescription>
+                        T3 Code will restart the local backend with Tailscale
+                        Serve enabled and ask Tailscale to proxy HTTPS traffic
+                        to this backend.
+                      </DialogDescription>
+                    </DialogHeader>
+                    <DialogPanel className="space-y-4">
+                      <label className="block">
+                        <span className="text-sm font-medium text-foreground">
+                          HTTPS port
+                        </span>
+                        <Input
+                          className="mt-2"
+                          type="number"
+                          inputMode="numeric"
+                          min={1}
+                          max={65_535}
+                          step={1}
+                          value={tailscaleServePortInput}
+                          onChange={(event) =>
+                            setTailscaleServePortInput(event.target.value)
+                          }
+                          disabled={isUpdatingTailscaleServe}
+                        />
+                      </label>
+                      {!isTailscaleServePortValid ? (
+                        <p className="mt-2 text-xs text-destructive">
+                          Enter a port from 1 to 65535.
+                        </p>
+                      ) : null}
+                      <div className="rounded-md border border-border/70 bg-muted/20 px-3 py-2">
+                        <p className="text-xs font-medium text-muted-foreground">
+                          HTTPS endpoint
+                        </p>
+                        <p
+                          className="mt-1 truncate text-sm text-foreground"
+                          title={pendingTailscaleServeBaseUrl ?? undefined}
+                        >
+                          {pendingTailscaleServeBaseUrl ??
+                            "Pending MagicDNS endpoint"}
+                        </p>
+                      </div>
+                    </DialogPanel>
+                    <DialogFooter>
+                      <DialogClose
+                        disabled={isUpdatingTailscaleServe}
+                        render={
+                          <Button
+                            variant="outline"
+                            disabled={isUpdatingTailscaleServe}
+                          />
+                        }
+                      >
+                        Cancel
+                      </DialogClose>
+                      <Button
+                        onClick={() => void handleConfirmTailscaleServeSetup()}
+                        disabled={
+                          isUpdatingTailscaleServe || !isTailscaleServePortValid
+                        }
+                      >
+                        {isUpdatingTailscaleServe ? (
+                          <>
+                            <Spinner className="size-3.5" />
+                            Restarting…
+                          </>
+                        ) : (
+                          "Enable"
+                        )}
+                      </Button>
+                    </DialogFooter>
+                  </DialogPopup>
+                </Dialog>
               </>
             ) : (
               <SettingsRow
@@ -1815,8 +2480,8 @@ export function ConnectionsSettings() {
                       }
                     />
                     <TooltipPopup side="top">
-                      Network exposure changes restart the backend and must be controlled where the
-                      server process is launched.
+                      Network exposure changes restart the backend and must be
+                      controlled where the server process is launched.
                     </TooltipPopup>
                   </Tooltip>
                 }
@@ -1824,7 +2489,7 @@ export function ConnectionsSettings() {
             )}
           </SettingsSection>
 
-          {isLocalBackendNetworkAccessible ? (
+          {isLocalBackendRemotelyReachable ? (
             <SettingsSection
               title="Authorized clients"
               headerAction={
@@ -1837,7 +2502,9 @@ export function ConnectionsSettings() {
             >
               {desktopAccessManagementError ? (
                 <div className={ITEM_ROW_CLASSNAME}>
-                  <p className="text-xs text-destructive">{desktopAccessManagementError}</p>
+                  <p className="text-xs text-destructive">
+                    {desktopAccessManagementError}
+                  </p>
                 </div>
               ) : null}
               <PairingClientsList
@@ -1887,7 +2554,9 @@ export function ConnectionsSettings() {
             <DialogPopup className="max-h-[80dvh] sm:max-w-3xl">
               <DialogHeader>
                 <DialogTitle>Add Environment</DialogTitle>
-                <DialogDescription>Pair another environment to this client.</DialogDescription>
+                <DialogDescription>
+                  Pair another environment to this client.
+                </DialogDescription>
                 <div className="flex gap-1 rounded-lg border border-border/60 bg-muted/50 p-1">
                   <button
                     type="button"
@@ -1936,7 +2605,8 @@ export function ConnectionsSettings() {
                 <div className="space-y-4">
                   {savedBackendMode === "pairing-url" ? (
                     <p className="text-xs text-muted-foreground">
-                      Enter the full pairing URL from the environment you want to connect to.
+                      Enter the full pairing URL from the environment you want
+                      to connect to.
                     </p>
                   ) : savedBackendMode === "host-code" ? (
                     <p className="text-xs text-muted-foreground">
@@ -1944,8 +2614,9 @@ export function ConnectionsSettings() {
                     </p>
                   ) : (
                     <p className="text-xs text-muted-foreground">
-                      Connect over SSH using an existing alias from <code>~/.ssh/config</code> or
-                      enter a host directly. T3 uses your current SSH agent and config.
+                      Connect over SSH using an existing alias from{" "}
+                      <code>~/.ssh/config</code> or enter a host directly. T3
+                      uses your current SSH agent and config.
                     </p>
                   )}
                   {savedBackendMode === "pairing-url" ? (
@@ -1956,7 +2627,9 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendLabel}
-                          onChange={(event) => setSavedBackendLabel(event.target.value)}
+                          onChange={(event) =>
+                            setSavedBackendLabel(event.target.value)
+                          }
                           placeholder="My backend (optional)"
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -1968,7 +2641,9 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendPairingUrl}
-                          onChange={(event) => setSavedBackendPairingUrl(event.target.value)}
+                          onChange={(event) =>
+                            setSavedBackendPairingUrl(event.target.value)
+                          }
                           placeholder="https://backend.example.com/pair#token=..."
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -1986,7 +2661,9 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendLabel}
-                          onChange={(event) => setSavedBackendLabel(event.target.value)}
+                          onChange={(event) =>
+                            setSavedBackendLabel(event.target.value)
+                          }
                           placeholder="My backend (optional)"
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -1998,7 +2675,9 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendHost}
-                          onChange={(event) => setSavedBackendHost(event.target.value)}
+                          onChange={(event) =>
+                            setSavedBackendHost(event.target.value)
+                          }
                           placeholder="https://backend.example.com"
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -2010,7 +2689,9 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendPairingCode}
-                          onChange={(event) => setSavedBackendPairingCode(event.target.value)}
+                          onChange={(event) =>
+                            setSavedBackendPairingCode(event.target.value)
+                          }
                           placeholder="Pairing code"
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -2021,9 +2702,12 @@ export function ConnectionsSettings() {
                     <div className="space-y-4">
                       <div className="flex items-start justify-between gap-3">
                         <div className="min-w-0">
-                          <h3 className="text-sm font-medium text-foreground">Discovered hosts</h3>
+                          <h3 className="text-sm font-medium text-foreground">
+                            Discovered hosts
+                          </h3>
                           <p className="text-xs text-muted-foreground">
-                            From <code>~/.ssh/config</code> and <code>known_hosts</code>.
+                            From <code>~/.ssh/config</code> and{" "}
+                            <code>known_hosts</code>.
                           </p>
                         </div>
                         <Button
@@ -2041,7 +2725,9 @@ export function ConnectionsSettings() {
                         </Button>
                       </div>
                       {discoveredSshHostsError ? (
-                        <p className="text-xs text-destructive">{discoveredSshHostsError}</p>
+                        <p className="text-xs text-destructive">
+                          {discoveredSshHostsError}
+                        </p>
                       ) : null}
                       <ScrollArea scrollFade className="max-h-64">
                         <div>
@@ -2049,9 +2735,15 @@ export function ConnectionsSettings() {
                             <DesktopSshHostRow
                               key={`${target.alias}:${target.hostname}:${target.port ?? ""}`}
                               target={target}
-                              savedRecord={savedDesktopSshEnvironmentsByAlias[target.alias] ?? null}
+                              savedRecord={
+                                savedDesktopSshEnvironmentsByAlias[
+                                  target.alias
+                                ] ?? null
+                              }
                               connectingHostAlias={connectingSshHostAlias}
-                              onConnect={(nextTarget) => void handleConnectSshHost(nextTarget)}
+                              onConnect={(nextTarget) =>
+                                void handleConnectSshHost(nextTarget)
+                              }
                             />
                           ))}
                           {hasLoadedDiscoveredSshHosts &&
@@ -2059,7 +2751,8 @@ export function ConnectionsSettings() {
                           discoveredSshHosts.length === 0 ? (
                             <div className={ITEM_ROW_CLASSNAME}>
                               <p className="text-xs text-muted-foreground">
-                                No SSH hosts were discovered from <code>~/.ssh/config</code> or{" "}
+                                No SSH hosts were discovered from{" "}
+                                <code>~/.ssh/config</code> or{" "}
                                 <code>known_hosts</code>.
                               </p>
                             </div>
@@ -2067,14 +2760,17 @@ export function ConnectionsSettings() {
                         </div>
                       </ScrollArea>
                       {savedBackendError ? (
-                        <p className="text-xs text-destructive">{savedBackendError}</p>
+                        <p className="text-xs text-destructive">
+                          {savedBackendError}
+                        </p>
                       ) : null}
                       <div className="border-t border-border/60 pt-4">
                         <h3 className="mb-1 text-sm font-medium text-foreground">
                           Enter a host manually
                         </h3>
                         <p className="mb-3 text-xs text-muted-foreground">
-                          Use an alias or enter host, username, and port directly.
+                          Use an alias or enter host, username, and port
+                          directly.
                         </p>
                         <div className="space-y-3">
                           <label className="block">
@@ -2083,7 +2779,9 @@ export function ConnectionsSettings() {
                             </span>
                             <Input
                               value={savedBackendLabel}
-                              onChange={(event) => setSavedBackendLabel(event.target.value)}
+                              onChange={(event) =>
+                                setSavedBackendLabel(event.target.value)
+                              }
                               placeholder="My backend (optional)"
                               disabled={isAddingSavedBackend}
                               spellCheck={false}
@@ -2095,7 +2793,9 @@ export function ConnectionsSettings() {
                             </span>
                             <Input
                               value={savedBackendSshHost}
-                              onChange={(event) => setSavedBackendSshHost(event.target.value)}
+                              onChange={(event) =>
+                                setSavedBackendSshHost(event.target.value)
+                              }
                               placeholder="devbox or devbox.example.com"
                               disabled={isAddingSavedBackend}
                               spellCheck={false}
@@ -2108,7 +2808,9 @@ export function ConnectionsSettings() {
                               </span>
                               <Input
                                 value={savedBackendSshUsername}
-                                onChange={(event) => setSavedBackendSshUsername(event.target.value)}
+                                onChange={(event) =>
+                                  setSavedBackendSshUsername(event.target.value)
+                                }
                                 placeholder="julius"
                                 disabled={isAddingSavedBackend}
                                 spellCheck={false}
@@ -2120,7 +2822,9 @@ export function ConnectionsSettings() {
                               </span>
                               <Input
                                 value={savedBackendSshPort}
-                                onChange={(event) => setSavedBackendSshPort(event.target.value)}
+                                onChange={(event) =>
+                                  setSavedBackendSshPort(event.target.value)
+                                }
                                 placeholder="22"
                                 inputMode="numeric"
                                 disabled={isAddingSavedBackend}
@@ -2129,9 +2833,9 @@ export function ConnectionsSettings() {
                             </label>
                           </div>
                           <span className="block text-[11px] text-muted-foreground">
-                            Uses your existing SSH keys, agent, and config. Password and
-                            keyboard-interactive prompts open through your system SSH dialog when
-                            needed.
+                            Uses your existing SSH keys, agent, and config.
+                            Password and keyboard-interactive prompts open
+                            through your system SSH dialog when needed.
                           </span>
                           <Button
                             variant="outline"
@@ -2140,14 +2844,18 @@ export function ConnectionsSettings() {
                             onClick={() => void handleAddSavedBackend()}
                           >
                             <PlusIcon className="size-3.5" />
-                            {isAddingSavedBackend ? "Connecting…" : "Connect SSH host"}
+                            {isAddingSavedBackend
+                              ? "Connecting…"
+                              : "Connect SSH host"}
                           </Button>
                         </div>
                       </div>
                     </div>
                   )}
                   {savedBackendMode !== "ssh" && savedBackendError ? (
-                    <p className="text-xs text-destructive">{savedBackendError}</p>
+                    <p className="text-xs text-destructive">
+                      {savedBackendError}
+                    </p>
                   ) : null}
                   {savedBackendMode !== "ssh" ? (
                     <Button
@@ -2180,8 +2888,8 @@ export function ConnectionsSettings() {
         {savedEnvironmentIds.length === 0 ? (
           <div className={ITEM_ROW_CLASSNAME}>
             <p className="text-xs text-muted-foreground">
-              No remote environments yet. Click &ldquo;Add environment&rdquo; to pair another
-              environment.
+              No remote environments yet. Click &ldquo;Add environment&rdquo; to
+              pair another environment.
             </p>
           </div>
         ) : null}
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index f1a07492a60..241a6cf4255 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -350,6 +350,8 @@ const createDesktopBridgeStub = (overrides?: {
         mode: "local-only",
         endpointUrl: null,
         advertisedHost: null,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       },
     ),
     setServerExposureMode:
@@ -358,7 +360,16 @@ const createDesktopBridgeStub = (overrides?: {
         mode,
         endpointUrl: mode === "network-accessible" ? "http://192.168.1.44:3773" : null,
         advertisedHost: mode === "network-accessible" ? "192.168.1.44" : null,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       })),
+    setTailscaleServeEnabled: vi.fn().mockImplementation(async (input) => ({
+      mode: overrides?.serverExposureState?.mode ?? "network-accessible",
+      endpointUrl: overrides?.serverExposureState?.endpointUrl ?? "http://192.168.1.44:3773",
+      advertisedHost: overrides?.serverExposureState?.advertisedHost ?? "192.168.1.44",
+      tailscaleServeEnabled: input.enabled,
+      tailscaleServePort: input.port ?? 443,
+    })),
     getAdvertisedEndpoints: vi.fn().mockResolvedValue(overrides?.advertisedEndpoints ?? []),
     pickFolder: vi.fn().mockResolvedValue(null),
     confirm: vi.fn().mockResolvedValue(false),
@@ -490,6 +501,8 @@ describe("GeneralSettingsPanel observability", () => {
         mode: "local-only",
         endpointUrl: null,
         advertisedHost: null,
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       },
       advertisedEndpoints: [
         {
@@ -560,6 +573,8 @@ describe("GeneralSettingsPanel observability", () => {
         mode: "network-accessible",
         endpointUrl: "http://192.168.86.39:3773",
         advertisedHost: "192.168.86.39",
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       },
       advertisedEndpoints: [
         {
@@ -682,6 +697,8 @@ describe("GeneralSettingsPanel observability", () => {
         mode: "network-accessible",
         endpointUrl: "http://192.168.1.44:3773",
         advertisedHost: "192.168.1.44",
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       },
     });
     let pairingLinks: Array<AuthAccessSnapshot["pairingLinks"][number]> = [];
@@ -798,6 +815,8 @@ describe("GeneralSettingsPanel observability", () => {
         mode: "network-accessible",
         endpointUrl: "http://192.168.1.44:3773",
         advertisedHost: "192.168.1.44",
+        tailscaleServeEnabled: false,
+        tailscaleServePort: 443,
       },
     });
     let clientSessions: Array<AuthAccessSnapshot["clientSessions"][number]> = [
diff --git a/apps/web/src/components/ui/alert-dialog.tsx b/apps/web/src/components/ui/alert-dialog.tsx
index 5c65f261f59..84bcff96316 100644
--- a/apps/web/src/components/ui/alert-dialog.tsx
+++ b/apps/web/src/components/ui/alert-dialog.tsx
@@ -18,7 +18,7 @@ function AlertDialogBackdrop({ className, ...props }: AlertDialogPrimitive.Backd
   return (
     <AlertDialogPrimitive.Backdrop
       className={cn(
-        "fixed inset-0 z-50 bg-black/32 backdrop-blur-sm transition-all duration-200 ease-out data-ending-style:opacity-0 data-starting-style:opacity-0",
+        "fixed inset-0 z-50 transition-all duration-200 data-ending-style:opacity-0 data-starting-style:opacity-0",
         className,
       )}
       data-slot="alert-dialog-backdrop"
@@ -31,7 +31,7 @@ function AlertDialogViewport({ className, ...props }: AlertDialogPrimitive.Viewp
   return (
     <AlertDialogPrimitive.Viewport
       className={cn(
-        "fixed inset-0 z-50 grid grid-rows-[1fr_auto_3fr] justify-items-center p-4",
+        "fixed inset-0 z-50 grid grid-rows-[1fr_auto_3fr] justify-items-center bg-white/48 p-4 backdrop-blur-[2px] dark:bg-black/28",
         className,
       )}
       data-slot="alert-dialog-viewport"
diff --git a/apps/web/src/environments/remote/api.test.ts b/apps/web/src/environments/remote/api.test.ts
index bbff762412f..d760714d8ec 100644
--- a/apps/web/src/environments/remote/api.test.ts
+++ b/apps/web/src/environments/remote/api.test.ts
@@ -48,6 +48,19 @@ describe("remote environment api", () => {
     });
   });
 
+  it("derives backend urls and token from a hosted app pairing link", () => {
+    expect(
+      resolveRemotePairingTarget({
+        pairingUrl:
+          "https://app.t3.codes/pair?host=https%3A%2F%2Fdesktop.tailnet.ts.net%3A44342%2F#token=pairing-token",
+      }),
+    ).toEqual({
+      credential: "pairing-token",
+      httpBaseUrl: "https://desktop.tailnet.ts.net:44342/",
+      wsBaseUrl: "wss://desktop.tailnet.ts.net:44342/",
+    });
+  });
+
   it("derives backend urls from a host and pairing code", () => {
     expect(
       resolveRemotePairingTarget({
diff --git a/apps/web/src/environments/remote/target.ts b/apps/web/src/environments/remote/target.ts
index 311450d5faf..ad925f014c6 100644
--- a/apps/web/src/environments/remote/target.ts
+++ b/apps/web/src/environments/remote/target.ts
@@ -1,4 +1,5 @@
 import { getPairingTokenFromUrl } from "../../pairingUrl";
+import { readHostedPairingRequest } from "../../hostedPairing";
 
 export interface ResolvedRemotePairingTarget {
   readonly credential: string;
@@ -57,6 +58,16 @@ export function resolveRemotePairingTarget(input: {
   const pairingUrl = input.pairingUrl?.trim() ?? "";
   if (pairingUrl.length > 0) {
     const url = new URL(pairingUrl, window.location.origin);
+    const hostedPairingRequest = readHostedPairingRequest(url);
+    if (hostedPairingRequest) {
+      const hostedBackendUrl = normalizeRemoteBaseUrl(hostedPairingRequest.host);
+      return {
+        credential: hostedPairingRequest.token,
+        httpBaseUrl: toHttpBaseUrl(hostedBackendUrl),
+        wsBaseUrl: toWsBaseUrl(hostedBackendUrl),
+      };
+    }
+
     const credential = getPairingTokenFromUrl(url) ?? "";
     if (!credential) {
       throw new Error("Pairing URL is missing its token.");
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index ab548c23d59..726c5116119 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -195,11 +195,22 @@ function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridg
       mode: "local-only",
       endpointUrl: null,
       advertisedHost: null,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
     }),
     setServerExposureMode: async () => ({
       mode: "local-only",
       endpointUrl: null,
       advertisedHost: null,
+      tailscaleServeEnabled: false,
+      tailscaleServePort: 443,
+    }),
+    setTailscaleServeEnabled: async (input) => ({
+      mode: "local-only",
+      endpointUrl: null,
+      advertisedHost: null,
+      tailscaleServeEnabled: input.enabled,
+      tailscaleServePort: input.port ?? 443,
     }),
     getAdvertisedEndpoints: async () => [],
     pickFolder: async () => null,
diff --git a/apps/web/vercel.json b/apps/web/vercel.json
index 1323cdac34c..ecfa7a47fc9 100644
--- a/apps/web/vercel.json
+++ b/apps/web/vercel.json
@@ -1,4 +1,6 @@
 {
+  "buildCommand": "turbo build --filter @t3tools/web && bun ../../scripts/apply-web-brand-assets.ts production",
+  "installCommand": "bun add -g turbo && bun install --filter '@t3tools/contracts' --filter '@t3tools/client-runtime' --filter '@t3tools/scripts' --filter '@t3tools/web'",
   "rewrites": [
     {
       "source": "/(.*)",
diff --git a/bun.lock b/bun.lock
index e1b9d456398..11a9cb95c33 100644
--- a/bun.lock
+++ b/bun.lock
@@ -16,6 +16,7 @@
       "name": "@t3tools/desktop",
       "version": "0.0.21",
       "dependencies": {
+        "@effect/platform-node": "catalog:",
         "effect": "catalog:",
         "electron": "40.9.3",
         "electron-updater": "^6.6.2",
@@ -24,6 +25,7 @@
         "@t3tools/client-runtime": "workspace:*",
         "@t3tools/contracts": "workspace:*",
         "@t3tools/shared": "workspace:*",
+        "@t3tools/tailscale": "workspace:*",
         "@types/node": "catalog:",
         "effect-acp": "workspace:*",
         "tsdown": "catalog:",
@@ -64,6 +66,7 @@
         "@effect/vitest": "catalog:",
         "@t3tools/contracts": "workspace:*",
         "@t3tools/shared": "workspace:*",
+        "@t3tools/tailscale": "workspace:*",
         "@t3tools/web": "workspace:*",
         "@types/bun": "catalog:",
         "@types/node": "catalog:",
@@ -199,6 +202,21 @@
         "vitest": "catalog:",
       },
     },
+    "packages/tailscale": {
+      "name": "@t3tools/tailscale",
+      "version": "0.0.0-alpha.1",
+      "dependencies": {
+        "@effect/platform-node": "catalog:",
+        "effect": "catalog:",
+      },
+      "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@effect/vitest": "catalog:",
+        "@types/node": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:",
+      },
+    },
     "scripts": {
       "name": "@t3tools/scripts",
       "dependencies": {
@@ -742,6 +760,8 @@
 
     "@t3tools/shared": ["@t3tools/shared@workspace:packages/shared"],
 
+    "@t3tools/tailscale": ["@t3tools/tailscale@workspace:packages/tailscale"],
+
     "@t3tools/web": ["@t3tools/web@workspace:apps/web"],
 
     "@tailwindcss/node": ["@tailwindcss/node@4.2.1", "", { "dependencies": { "@jridgewell/remapping": "^2.3.5", "enhanced-resolve": "^5.19.0", "jiti": "^2.6.1", "lightningcss": "1.31.1", "magic-string": "^0.30.21", "source-map-js": "^1.2.1", "tailwindcss": "4.2.1" } }, "sha512-jlx6sLk4EOwO6hHe1oCGm1Q4AN/s0rSrTTPBGPM0/RQ6Uylwq17FuU8IeJJKEjtc6K6O07zsvP+gDO6MMWo7pg=="],
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index f15dfdb9703..4b934f20344 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -178,6 +178,8 @@ export interface DesktopServerExposureState {
   mode: DesktopServerExposureMode;
   endpointUrl: string | null;
   advertisedHost: string | null;
+  tailscaleServeEnabled: boolean;
+  tailscaleServePort: number;
 }
 
 export interface PickFolderOptions {
@@ -215,6 +217,10 @@ export interface DesktopBridge {
   resolveSshPasswordPrompt: (requestId: string, password: string | null) => Promise<void>;
   getServerExposureState: () => Promise<DesktopServerExposureState>;
   setServerExposureMode: (mode: DesktopServerExposureMode) => Promise<DesktopServerExposureState>;
+  setTailscaleServeEnabled: (input: {
+    readonly enabled: boolean;
+    readonly port?: number;
+  }) => Promise<DesktopServerExposureState>;
   getAdvertisedEndpoints: () => Promise<readonly AdvertisedEndpoint[]>;
   pickFolder: (options?: PickFolderOptions) => Promise<string | null>;
   confirm: (message: string) => Promise<boolean>;
diff --git a/packages/tailscale/package.json b/packages/tailscale/package.json
new file mode 100644
index 00000000000..7088559c74a
--- /dev/null
+++ b/packages/tailscale/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@t3tools/tailscale",
+  "version": "0.0.0-alpha.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "prepare": "effect-language-service patch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@effect/platform-node": "catalog:",
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/language-service": "catalog:",
+    "@effect/vitest": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
diff --git a/packages/tailscale/src/index.ts b/packages/tailscale/src/index.ts
new file mode 100644
index 00000000000..b6cba8d7b43
--- /dev/null
+++ b/packages/tailscale/src/index.ts
@@ -0,0 +1 @@
+export * from "./tailscale.ts";
diff --git a/packages/tailscale/src/tailscale.test.ts b/packages/tailscale/src/tailscale.test.ts
new file mode 100644
index 00000000000..7bcad80664f
--- /dev/null
+++ b/packages/tailscale/src/tailscale.test.ts
@@ -0,0 +1,120 @@
+import { assert, describe, it } from "@effect/vitest";
+import { Effect, Layer, Sink, Stream } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  buildTailscaleHttpsBaseUrl,
+  ensureTailscaleServe,
+  isTailscaleIpv4Address,
+  parseTailscaleMagicDnsName,
+  parseTailscaleStatus,
+  readTailscaleStatus,
+} from "./tailscale.ts";
+
+const encoder = new TextEncoder();
+const tailscaleStatusJson = `{"Self":{"DNSName":"desktop.tail.ts.net.","TailscaleIPs":["100.100.100.100","fd7a:115c:a1e0::1","192.168.1.20"]}}`;
+const tailscaleStatusWithSingleIpJson = `{"Self":{"DNSName":"desktop.tail.ts.net.","TailscaleIPs":["100.90.1.2"]}}`;
+
+function mockHandle(result: { stdout?: string; stderr?: string; code?: number }) {
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(1),
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(result.code ?? 0)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    unref: Effect.succeed(Effect.void),
+    stdin: Sink.drain,
+    stdout: Stream.make(encoder.encode(result.stdout ?? "")),
+    stderr: Stream.make(encoder.encode(result.stderr ?? "")),
+    all: Stream.empty,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+  });
+}
+
+function mockSpawnerLayer(
+  handler: (
+    command: string,
+    args: ReadonlyArray<string>,
+  ) => { stdout?: string; stderr?: string; code?: number },
+) {
+  return Layer.succeed(
+    ChildProcessSpawner.ChildProcessSpawner,
+    ChildProcessSpawner.make((command) => {
+      const childProcess = command as unknown as {
+        readonly command: string;
+        readonly args: ReadonlyArray<string>;
+      };
+      return Effect.succeed(mockHandle(handler(childProcess.command, childProcess.args)));
+    }),
+  );
+}
+
+describe("tailscale", () => {
+  it.effect("detects Tailnet IPv4 addresses", () =>
+    Effect.sync(() => {
+      assert.equal(isTailscaleIpv4Address("100.64.0.1"), true);
+      assert.equal(isTailscaleIpv4Address("100.127.255.254"), true);
+      assert.equal(isTailscaleIpv4Address("100.128.0.1"), false);
+      assert.equal(isTailscaleIpv4Address("192.168.1.44"), false);
+    }),
+  );
+
+  it.effect("parses MagicDNS names from tailscale status", () =>
+    Effect.gen(function* () {
+      const dnsName = yield* parseTailscaleMagicDnsName(tailscaleStatusJson);
+      assert.equal(dnsName, "desktop.tail.ts.net");
+      assert.equal(yield* parseTailscaleMagicDnsName("{}"), null);
+    }),
+  );
+
+  it.effect("parses status facts", () =>
+    Effect.gen(function* () {
+      const status = yield* parseTailscaleStatus(tailscaleStatusJson);
+      assert.deepEqual(status, {
+        magicDnsName: "desktop.tail.ts.net",
+        tailnetIpv4Addresses: ["100.100.100.100"],
+      });
+    }),
+  );
+
+  it.effect("builds clean HTTPS base URLs", () =>
+    Effect.sync(() => {
+      assert.equal(
+        buildTailscaleHttpsBaseUrl({ magicDnsName: "desktop.tail.ts.net" }),
+        "https://desktop.tail.ts.net/",
+      );
+      assert.equal(
+        buildTailscaleHttpsBaseUrl({ magicDnsName: "desktop.tail.ts.net", servePort: 8443 }),
+        "https://desktop.tail.ts.net:8443/",
+      );
+    }),
+  );
+
+  it.effect("reads tailscale status through the process spawner service", () => {
+    const layer = mockSpawnerLayer((command, args) => {
+      assert.equal(command, "tailscale");
+      assert.deepEqual(args, ["status", "--json"]);
+      return {
+        stdout: tailscaleStatusWithSingleIpJson,
+      };
+    });
+
+    return Effect.gen(function* () {
+      const status = yield* readTailscaleStatus.pipe(Effect.provide(layer));
+      assert.deepEqual(status, {
+        magicDnsName: "desktop.tail.ts.net",
+        tailnetIpv4Addresses: ["100.90.1.2"],
+      });
+    });
+  });
+
+  it.effect("configures tailscale serve through the process spawner service", () => {
+    const layer = mockSpawnerLayer((command, args) => {
+      assert.equal(command, "tailscale");
+      assert.deepEqual(args, ["serve", "--bg", "--https=8443", "http://127.0.0.1:13773"]);
+      return {};
+    });
+
+    return ensureTailscaleServe({ localPort: 13773, servePort: 8443 }).pipe(Effect.provide(layer));
+  });
+});
diff --git a/packages/tailscale/src/tailscale.ts b/packages/tailscale/src/tailscale.ts
new file mode 100644
index 00000000000..46d1183667e
--- /dev/null
+++ b/packages/tailscale/src/tailscale.ts
@@ -0,0 +1,291 @@
+import { Data, Effect, Option, Schema, Stream } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+export const DEFAULT_TAILSCALE_SERVE_PORT = 443;
+export const TAILSCALE_STATUS_TIMEOUT_MS = 1_500;
+export const TAILSCALE_SERVE_TIMEOUT_MS = 10_000;
+export const TAILSCALE_PROBE_TIMEOUT_MS = 2_500;
+
+export class TailscaleCommandError extends Data.TaggedError("TailscaleCommandError")<{
+  readonly command: readonly string[];
+  readonly message: string;
+  readonly exitCode: number | null;
+  readonly stderr: string;
+}> {}
+
+export class TailscaleStatusParseError extends Data.TaggedError("TailscaleStatusParseError")<{
+  readonly cause: unknown;
+}> {}
+
+export class TailscaleUnavailableError extends Data.TaggedError("TailscaleUnavailableError")<{
+  readonly reason: string;
+}> {}
+
+const TailscaleStatusSelf = Schema.Struct({
+  DNSName: Schema.optional(Schema.Unknown),
+  TailscaleIPs: Schema.optional(Schema.Unknown),
+});
+
+const TailscaleStatusJson = Schema.Struct({
+  Self: Schema.optional(TailscaleStatusSelf),
+});
+
+export type TailscaleStatusSelf = typeof TailscaleStatusSelf.Type;
+export type TailscaleStatusJson = typeof TailscaleStatusJson.Type;
+
+export interface TailscaleStatus {
+  readonly magicDnsName: string | null;
+  readonly tailnetIpv4Addresses: readonly string[];
+}
+
+const collectStdout = <E>(stream: Stream.Stream<Uint8Array, E>): Effect.Effect<string, E> =>
+  stream.pipe(
+    Stream.decodeText(),
+    Stream.runFold(
+      () => "",
+      (acc, chunk) => acc + chunk,
+    ),
+  );
+
+const collectStderr = collectStdout;
+
+const tailscaleCommandError = (
+  args: readonly string[],
+  message: string,
+  exitCode: number | null,
+  stderr = "",
+): TailscaleCommandError =>
+  new TailscaleCommandError({
+    command: ["tailscale", ...args],
+    message,
+    exitCode,
+    stderr,
+  });
+
+const decodeTailscaleStatusJson = Schema.decodeEffect(Schema.fromJsonString(TailscaleStatusJson));
+
+function normalizeMagicDnsName(status: TailscaleStatusJson): string | null {
+  const dnsName = status.Self?.DNSName;
+  if (typeof dnsName !== "string") {
+    return null;
+  }
+
+  const normalized = dnsName.trim().replace(/\.$/u, "");
+  return normalized.length > 0 ? normalized : null;
+}
+
+export const parseTailscaleMagicDnsName = (
+  rawStatusJson: string,
+): Effect.Effect<string | null, TailscaleStatusParseError> =>
+  decodeTailscaleStatusJson(rawStatusJson).pipe(
+    Effect.mapError((cause) => new TailscaleStatusParseError({ cause })),
+    Effect.map(normalizeMagicDnsName),
+  );
+
+export function isTailscaleIpv4Address(address: string): boolean {
+  const parts = address.split(".");
+  if (parts.length !== 4) {
+    return false;
+  }
+  const [first, second, third, fourth] = parts.map((part) => Number.parseInt(part, 10));
+  if (
+    first === undefined ||
+    second === undefined ||
+    third === undefined ||
+    fourth === undefined ||
+    [first, second, third, fourth].some((part) => !Number.isInteger(part) || part < 0 || part > 255)
+  ) {
+    return false;
+  }
+  return first === 100 && second >= 64 && second <= 127;
+}
+
+export const parseTailscaleStatus = (
+  rawStatusJson: string,
+): Effect.Effect<TailscaleStatus, TailscaleStatusParseError> =>
+  decodeTailscaleStatusJson(rawStatusJson).pipe(
+    Effect.mapError((cause) => new TailscaleStatusParseError({ cause })),
+    Effect.map((parsed) => {
+      const rawIps = parsed.Self?.TailscaleIPs;
+      const tailnetIpv4Addresses = Array.isArray(rawIps)
+        ? rawIps
+            .filter((address): address is string => typeof address === "string")
+            .filter(isTailscaleIpv4Address)
+        : [];
+
+      return {
+        magicDnsName: normalizeMagicDnsName(parsed),
+        tailnetIpv4Addresses,
+      };
+    }),
+  );
+
+export const readTailscaleStatus: Effect.Effect<
+  TailscaleStatus,
+  TailscaleCommandError | TailscaleStatusParseError,
+  ChildProcessSpawner.ChildProcessSpawner
+> = Effect.gen(function* () {
+  const args = ["status", "--json"];
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner
+    .spawn(
+      ChildProcess.make("tailscale", args, {
+        shell: process.platform === "win32",
+      }),
+    )
+    .pipe(
+      Effect.mapError((cause) =>
+        tailscaleCommandError(
+          args,
+          cause instanceof Error ? cause.message : "Failed to spawn tailscale status.",
+          null,
+        ),
+      ),
+    );
+  const [stdout, stderr, exitCode] = yield* Effect.all(
+    [
+      collectStdout(child.stdout),
+      collectStderr(child.stderr),
+      child.exitCode.pipe(Effect.map(Number)),
+    ],
+    { concurrency: "unbounded" },
+  ).pipe(
+    Effect.mapError((cause) =>
+      tailscaleCommandError(
+        args,
+        cause instanceof Error ? cause.message : "Failed to run tailscale status.",
+        null,
+      ),
+    ),
+  );
+  if (exitCode !== 0) {
+    return yield* tailscaleCommandError(
+      args,
+      `Tailscale status exited with code ${exitCode}.`,
+      exitCode,
+      stderr,
+    );
+  }
+  return yield* parseTailscaleStatus(stdout);
+}).pipe(
+  Effect.scoped,
+  Effect.timeoutOption(TAILSCALE_STATUS_TIMEOUT_MS),
+  Effect.flatMap((result) =>
+    Option.match(result, {
+      onNone: () =>
+        Effect.fail(
+          tailscaleCommandError(["status", "--json"], "Tailscale status timed out.", null),
+        ),
+      onSome: Effect.succeed,
+    }),
+  ),
+);
+
+export function buildTailscaleHttpsBaseUrl(input: {
+  readonly magicDnsName: string;
+  readonly servePort?: number;
+}): string {
+  const url = new URL(`https://${input.magicDnsName}`);
+  const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
+  if (servePort !== DEFAULT_TAILSCALE_SERVE_PORT) {
+    url.port = String(servePort);
+  }
+  url.pathname = "/";
+  return url.toString();
+}
+
+export const ensureTailscaleServe = (input: {
+  readonly localPort: number;
+  readonly servePort?: number;
+  readonly localHost?: string;
+}): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> => {
+  const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
+  const localHost = input.localHost ?? "127.0.0.1";
+  const args = ["serve", "--bg", `--https=${servePort}`, `http://${localHost}:${input.localPort}`];
+  return Effect.gen(function* () {
+    const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const child = yield* spawner
+      .spawn(
+        ChildProcess.make("tailscale", args, {
+          shell: process.platform === "win32",
+        }),
+      )
+      .pipe(
+        Effect.mapError((cause) =>
+          tailscaleCommandError(
+            args,
+            cause instanceof Error ? cause.message : "Failed to spawn tailscale serve.",
+            null,
+          ),
+        ),
+      );
+    const [stderr, exitCode] = yield* Effect.all(
+      [collectStderr(child.stderr), child.exitCode.pipe(Effect.map(Number))],
+      { concurrency: "unbounded" },
+    ).pipe(
+      Effect.mapError((cause) =>
+        tailscaleCommandError(
+          args,
+          cause instanceof Error ? cause.message : "Failed to run tailscale serve.",
+          null,
+        ),
+      ),
+    );
+    if (exitCode !== 0) {
+      return yield* tailscaleCommandError(
+        args,
+        `Tailscale serve exited with code ${exitCode}.`,
+        exitCode,
+        stderr,
+      );
+    }
+  }).pipe(
+    Effect.scoped,
+    Effect.timeoutOption(TAILSCALE_SERVE_TIMEOUT_MS),
+    Effect.flatMap((result) =>
+      Option.match(result, {
+        onNone: () => Effect.fail(tailscaleCommandError(args, "Tailscale serve timed out.", null)),
+        onSome: Effect.succeed,
+      }),
+    ),
+  );
+};
+
+export const probeTailscaleHttpsEndpoint = (input: {
+  readonly baseUrl: string;
+  readonly timeoutMs?: number;
+}): Effect.Effect<boolean, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const response = yield* Effect.gen(function* () {
+      const url = new URL("/.well-known/t3/environment", input.baseUrl);
+      const request = HttpClientRequest.get(url.toString());
+      return yield* client.execute(request);
+    }).pipe(Effect.timeoutOption(input.timeoutMs ?? TAILSCALE_PROBE_TIMEOUT_MS));
+
+    return Option.match(response, {
+      onNone: () => false,
+      onSome: (httpResponse) => httpResponse.status >= 200 && httpResponse.status < 300,
+    });
+  }).pipe(Effect.catch(() => Effect.succeed(false)));
+
+export const resolveTailscaleHttpsBaseUrl = (
+  input: {
+    readonly servePort?: number;
+  } = {},
+): Effect.Effect<
+  string | null,
+  TailscaleCommandError | TailscaleStatusParseError,
+  ChildProcessSpawner.ChildProcessSpawner
+> =>
+  readTailscaleStatus.pipe(
+    Effect.map((status) =>
+      status.magicDnsName
+        ? buildTailscaleHttpsBaseUrl({
+            magicDnsName: status.magicDnsName,
+            ...(input.servePort === undefined ? {} : { servePort: input.servePort }),
+          })
+        : null,
+    ),
+  );
diff --git a/packages/tailscale/tsconfig.json b/packages/tailscale/tsconfig.json
new file mode 100644
index 00000000000..2f8e6d4df6d
--- /dev/null
+++ b/packages/tailscale/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "diagnosticSeverity": {
+          "importFromBarrel": "error",
+          "anyUnknownInErrorContext": "warning",
+          "instanceOfSchema": "warning",
+          "deterministicKeys": "warning"
+        }
+      }
+    ]
+  },
+  "include": ["src"]
+}
diff --git a/scripts/apply-web-brand-assets.ts b/scripts/apply-web-brand-assets.ts
new file mode 100644
index 00000000000..1bbdd237c22
--- /dev/null
+++ b/scripts/apply-web-brand-assets.ts
@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Effect, FileSystem, Option, Path } from "effect";
+import { Argument, Command } from "effect/unstable/cli";
+import { resolveWebIconOverrides, type WebAssetBrand } from "./lib/brand-assets.ts";
+
+const WEB_ASSET_BRANDS = [
+  "development",
+  "production",
+] as const satisfies ReadonlyArray<WebAssetBrand>;
+
+export const applyWebBrandAssets = Effect.fn("applyWebBrandAssets")(function* (
+  brand: WebAssetBrand,
+  targetDirectory: string,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const repoRoot = yield* path.fromFileUrl(new URL("..", import.meta.url));
+
+  yield* Effect.forEach(
+    resolveWebIconOverrides(brand, targetDirectory),
+    (override) =>
+      fs.copyFile(
+        path.join(repoRoot, override.sourceRelativePath),
+        path.join(repoRoot, override.targetRelativePath),
+      ),
+    { concurrency: "unbounded" },
+  );
+});
+
+export const applyWebBrandAssetsCommand = Command.make(
+  "apply-web-brand-assets",
+  {
+    brand: Argument.choice("brand", WEB_ASSET_BRANDS).pipe(
+      Argument.withDescription("Asset brand to copy into the hosted web output directory."),
+    ),
+    targetDirectory: Argument.string("target-directory").pipe(
+      Argument.withDescription("Output directory that contains the hosted web build assets."),
+      Argument.optional,
+    ),
+  },
+  ({ brand, targetDirectory }) =>
+    applyWebBrandAssets(
+      brand,
+      Option.getOrElse(targetDirectory, () => "apps/web/dist"),
+    ),
+).pipe(Command.withDescription("Copy web brand assets into a built hosted web app."));
+
+if (import.meta.main) {
+  Command.run(applyWebBrandAssetsCommand, { version: "0.0.0" }).pipe(
+    Effect.provide(NodeServices.layer),
+    NodeRuntime.runMain,
+  );
+}
diff --git a/scripts/lib/brand-assets.test.ts b/scripts/lib/brand-assets.test.ts
new file mode 100644
index 00000000000..8c85455185e
--- /dev/null
+++ b/scripts/lib/brand-assets.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  BRAND_ASSET_PATHS,
+  DEVELOPMENT_ICON_OVERRIDES,
+  PUBLISH_ICON_OVERRIDES,
+  resolveWebIconOverrides,
+} from "./brand-assets.ts";
+
+describe("brand-assets", () => {
+  it("maps server publish web assets to production icons", () => {
+    expect(PUBLISH_ICON_OVERRIDES).toEqual([
+      {
+        sourceRelativePath: BRAND_ASSET_PATHS.productionWebFaviconIco,
+        targetRelativePath: "dist/client/favicon.ico",
+      },
+      {
+        sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon16Png,
+        targetRelativePath: "dist/client/favicon-16x16.png",
+      },
+      {
+        sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon32Png,
+        targetRelativePath: "dist/client/favicon-32x32.png",
+      },
+      {
+        sourceRelativePath: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
+        targetRelativePath: "dist/client/apple-touch-icon.png",
+      },
+    ]);
+  });
+
+  it("maps server build web assets to development icons", () => {
+    expect(DEVELOPMENT_ICON_OVERRIDES[0]).toEqual({
+      sourceRelativePath: BRAND_ASSET_PATHS.developmentWebFaviconIco,
+      targetRelativePath: "dist/client/favicon.ico",
+    });
+  });
+
+  it("can target hosted web dist directly", () => {
+    expect(resolveWebIconOverrides("production", "apps/web/dist")).toContainEqual({
+      sourceRelativePath: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
+      targetRelativePath: "apps/web/dist/apple-touch-icon.png",
+    });
+  });
+});
diff --git a/scripts/lib/brand-assets.ts b/scripts/lib/brand-assets.ts
index 6cc777e22b8..56c44cbbd5d 100644
--- a/scripts/lib/brand-assets.ts
+++ b/scripts/lib/brand-assets.ts
@@ -19,45 +19,60 @@ export const BRAND_ASSET_PATHS = {
   developmentWebAppleTouchIconPng: "assets/dev/blueprint-web-apple-touch-180.png",
 } as const;
 
+export type WebAssetBrand = "development" | "production";
+
 export interface IconOverride {
   readonly sourceRelativePath: string;
   readonly targetRelativePath: string;
 }
 
-export const DEVELOPMENT_ICON_OVERRIDES: ReadonlyArray<IconOverride> = [
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.developmentWebFaviconIco,
-    targetRelativePath: "dist/client/favicon.ico",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.developmentWebFavicon16Png,
-    targetRelativePath: "dist/client/favicon-16x16.png",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.developmentWebFavicon32Png,
-    targetRelativePath: "dist/client/favicon-32x32.png",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.developmentWebAppleTouchIconPng,
-    targetRelativePath: "dist/client/apple-touch-icon.png",
-  },
-];
+const WEB_ICON_TARGET_FILENAMES = {
+  faviconIco: "favicon.ico",
+  favicon16Png: "favicon-16x16.png",
+  favicon32Png: "favicon-32x32.png",
+  appleTouchIconPng: "apple-touch-icon.png",
+} as const;
 
-export const PUBLISH_ICON_OVERRIDES: ReadonlyArray<IconOverride> = [
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebFaviconIco,
-    targetRelativePath: "dist/client/favicon.ico",
+const WEB_ICON_SOURCE_PATHS_BY_BRAND = {
+  development: {
+    faviconIco: BRAND_ASSET_PATHS.developmentWebFaviconIco,
+    favicon16Png: BRAND_ASSET_PATHS.developmentWebFavicon16Png,
+    favicon32Png: BRAND_ASSET_PATHS.developmentWebFavicon32Png,
+    appleTouchIconPng: BRAND_ASSET_PATHS.developmentWebAppleTouchIconPng,
   },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon16Png,
-    targetRelativePath: "dist/client/favicon-16x16.png",
+  production: {
+    faviconIco: BRAND_ASSET_PATHS.productionWebFaviconIco,
+    favicon16Png: BRAND_ASSET_PATHS.productionWebFavicon16Png,
+    favicon32Png: BRAND_ASSET_PATHS.productionWebFavicon32Png,
+    appleTouchIconPng: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
   },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebFavicon32Png,
-    targetRelativePath: "dist/client/favicon-32x32.png",
-  },
-  {
-    sourceRelativePath: BRAND_ASSET_PATHS.productionWebAppleTouchIconPng,
-    targetRelativePath: "dist/client/apple-touch-icon.png",
-  },
-];
+} as const satisfies Record<WebAssetBrand, Record<keyof typeof WEB_ICON_TARGET_FILENAMES, string>>;
+
+export function resolveWebIconOverrides(
+  brand: WebAssetBrand,
+  targetDirectory: string,
+): ReadonlyArray<IconOverride> {
+  const sourcePaths = WEB_ICON_SOURCE_PATHS_BY_BRAND[brand];
+  return [
+    {
+      sourceRelativePath: sourcePaths.faviconIco,
+      targetRelativePath: `${targetDirectory}/${WEB_ICON_TARGET_FILENAMES.faviconIco}`,
+    },
+    {
+      sourceRelativePath: sourcePaths.favicon16Png,
+      targetRelativePath: `${targetDirectory}/${WEB_ICON_TARGET_FILENAMES.favicon16Png}`,
+    },
+    {
+      sourceRelativePath: sourcePaths.favicon32Png,
+      targetRelativePath: `${targetDirectory}/${WEB_ICON_TARGET_FILENAMES.favicon32Png}`,
+    },
+    {
+      sourceRelativePath: sourcePaths.appleTouchIconPng,
+      targetRelativePath: `${targetDirectory}/${WEB_ICON_TARGET_FILENAMES.appleTouchIconPng}`,
+    },
+  ];
+}
+
+export const DEVELOPMENT_ICON_OVERRIDES = resolveWebIconOverrides("development", "dist/client");
+
+export const PUBLISH_ICON_OVERRIDES = resolveWebIconOverrides("production", "dist/client");
diff --git a/turbo.json b/turbo.json
index e6ebeee912f..0b19d93c4ae 100644
--- a/turbo.json
+++ b/turbo.json
@@ -11,6 +11,8 @@
     "T3CODE_NO_BROWSER",
     "T3CODE_HOME",
     "T3CODE_AUTH_TOKEN",
+    "T3CODE_TAILSCALE_SERVE",
+    "T3CODE_TAILSCALE_SERVE_PORT",
     "T3CODE_DESKTOP_WS_URL",
     "T3CODE_TRACE_MIN_LEVEL",
     "T3CODE_TRACE_TIMING_ENABLED",

From 2ece6122cb0824520b3f66ae59fc978140603d47 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Mon, 27 Apr 2026 23:54:23 -0700
Subject: [PATCH 30/74] Harden pairing and SSH prompt flows

- Preserve Tailscale Serve port when toggling exposure
- Prevent reused hosted pairing tokens and double SSH responses
- Refine endpoint compatibility for HTTP custom URLs
---
 apps/desktop/src/desktopSettings.test.ts      |   21 +
 apps/desktop/src/desktopSettings.ts           |    5 +-
 apps/desktop/src/main.ts                      |   19 +-
 apps/desktop/src/serverExposure.test.ts       |   25 +-
 apps/desktop/src/serverExposure.ts            |    8 +-
 .../components/auth/PairingRouteSurface.tsx   |   28 +-
 .../desktop/SshPasswordPromptDialog.tsx       |   92 +-
 .../settings/ConnectionsSettings.tsx          | 1009 ++++++-----------
 8 files changed, 466 insertions(+), 741 deletions(-)

diff --git a/apps/desktop/src/desktopSettings.test.ts b/apps/desktop/src/desktopSettings.test.ts
index c012e39b5f1..cc58dc810ef 100644
--- a/apps/desktop/src/desktopSettings.test.ts
+++ b/apps/desktop/src/desktopSettings.test.ts
@@ -105,6 +105,27 @@ describe("desktopSettings", () => {
     });
   });
 
+  it("preserves the configured Tailscale Serve port when no new port is requested", () => {
+    expect(
+      setDesktopTailscaleServePreference(
+        {
+          serverExposureMode: "local-only",
+          tailscaleServeEnabled: false,
+          tailscaleServePort: 8443,
+          updateChannel: "latest",
+          updateChannelConfiguredByUser: false,
+        },
+        { enabled: true },
+      ),
+    ).toEqual({
+      serverExposureMode: "local-only",
+      tailscaleServeEnabled: true,
+      tailscaleServePort: 8443,
+      updateChannel: "latest",
+      updateChannelConfiguredByUser: false,
+    });
+  });
+
   it("persists the requested nightly update channel", () => {
     expect(
       setDesktopUpdateChannelPreference(
diff --git a/apps/desktop/src/desktopSettings.ts b/apps/desktop/src/desktopSettings.ts
index 854c363e09d..5a61faef803 100644
--- a/apps/desktop/src/desktopSettings.ts
+++ b/apps/desktop/src/desktopSettings.ts
@@ -45,7 +45,10 @@ export function setDesktopTailscaleServePreference(
   settings: DesktopSettings,
   input: { readonly enabled: boolean; readonly port?: number },
 ): DesktopSettings {
-  const port = normalizeTailscaleServePort(input.port);
+  const port =
+    input.port === undefined
+      ? settings.tailscaleServePort
+      : normalizeTailscaleServePort(input.port);
   return settings.tailscaleServeEnabled === input.enabled && settings.tailscaleServePort === port
     ? settings
     : {
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index f80f34b2640..005cc1e43f6 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -38,6 +38,7 @@ import { RotatingFileSink } from "@t3tools/shared/logging";
 import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
 import { DEFAULT_DESKTOP_BACKEND_PORT, resolveDesktopBackendPort } from "./backendPort.ts";
 import {
+  type DesktopSettings,
   DEFAULT_DESKTOP_SETTINGS,
   readDesktopSettings,
   setDesktopServerExposurePreference,
@@ -402,13 +403,14 @@ async function applyDesktopServerExposureMode(
   return getDesktopServerExposureState();
 }
 
-async function applyDesktopTailscaleServeEnabled(input: {
-  readonly enabled: boolean;
-  readonly port?: number;
-}): Promise<DesktopServerExposureState> {
-  desktopSettings = setDesktopTailscaleServePreference(desktopSettings, input);
+async function applyDesktopTailscaleServeEnabled(
+  nextSettings: DesktopSettings,
+): Promise<DesktopServerExposureState> {
+  desktopSettings = nextSettings;
   writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
-  relaunchDesktopApp(input.enabled ? "tailscale-serve-enabled" : "tailscale-serve-disabled");
+  relaunchDesktopApp(
+    desktopSettings.tailscaleServeEnabled ? "tailscale-serve-enabled" : "tailscale-serve-disabled",
+  );
   return getDesktopServerExposureState();
 }
 
@@ -1751,10 +1753,7 @@ function registerIpcHandlers(): void {
     if (nextSettings === desktopSettings) {
       return getDesktopServerExposureState();
     }
-    return applyDesktopTailscaleServeEnabled({
-      enabled: input.enabled,
-      port: nextSettings.tailscaleServePort,
-    });
+    return applyDesktopTailscaleServeEnabled(nextSettings);
   });
 
   ipcMain.removeHandler(GET_ADVERTISED_ENDPOINTS_CHANNEL);
diff --git a/apps/desktop/src/serverExposure.test.ts b/apps/desktop/src/serverExposure.test.ts
index 86e9d3a6558..3c101628e04 100644
--- a/apps/desktop/src/serverExposure.test.ts
+++ b/apps/desktop/src/serverExposure.test.ts
@@ -101,7 +101,10 @@ describe("resolveDesktopCoreAdvertisedEndpoints", () => {
       resolveDesktopCoreAdvertisedEndpoints({
         port: 3773,
         exposure,
-        customHttpsEndpointUrls: ["https://desktop.example.ts.net"],
+        customHttpsEndpointUrls: [
+          "https://desktop.example.ts.net",
+          "http://desktop.example.test:3773",
+        ],
       }),
     ).toEqual([
       {
@@ -165,6 +168,26 @@ describe("resolveDesktopCoreAdvertisedEndpoints", () => {
         status: "unknown",
         description: "User-configured HTTPS endpoint for this desktop backend.",
       },
+      {
+        id: "manual:http://desktop.example.test:3773",
+        label: "Custom HTTPS",
+        provider: {
+          id: "manual",
+          label: "Manual",
+          kind: "manual",
+          isAddon: false,
+        },
+        httpBaseUrl: "http://desktop.example.test:3773/",
+        wsBaseUrl: "ws://desktop.example.test:3773/",
+        reachability: "public",
+        compatibility: {
+          hostedHttpsApp: "mixed-content-blocked",
+          desktopApp: "compatible",
+        },
+        source: "user",
+        status: "unknown",
+        description: "User-configured HTTPS endpoint for this desktop backend.",
+      },
     ]);
   });
 });
diff --git a/apps/desktop/src/serverExposure.ts b/apps/desktop/src/serverExposure.ts
index fb6b284b9ef..332f34cfeeb 100644
--- a/apps/desktop/src/serverExposure.ts
+++ b/apps/desktop/src/serverExposure.ts
@@ -49,6 +49,10 @@ const normalizeOptionalHost = (value: string | undefined): string | undefined =>
 const isUsableLanIpv4Address = (address: string): boolean =>
   !address.startsWith("127.") && !address.startsWith("169.254.");
 
+function isHttpsEndpointUrl(value: string): boolean {
+  return new URL(value).protocol === "https:";
+}
+
 export function resolveLanAdvertisedHost(
   networkInterfaces: NodeJS.Dict<NetworkInterfaceInfo[]>,
   explicitHost: string | undefined,
@@ -162,7 +166,9 @@ export function resolveDesktopCoreAdvertisedEndpoints(
         label: "Custom HTTPS",
         httpBaseUrl: customEndpointUrl,
         reachability: "public",
-        hostedHttpsCompatibility: "compatible",
+        ...(isHttpsEndpointUrl(customEndpointUrl)
+          ? ({ hostedHttpsCompatibility: "compatible" } as const)
+          : {}),
         status: "unknown",
         description: "User-configured HTTPS endpoint for this desktop backend.",
       }),
diff --git a/apps/web/src/components/auth/PairingRouteSurface.tsx b/apps/web/src/components/auth/PairingRouteSurface.tsx
index 46349ca1faf..d301d6f4105 100644
--- a/apps/web/src/components/auth/PairingRouteSurface.tsx
+++ b/apps/web/src/components/auth/PairingRouteSurface.tsx
@@ -166,6 +166,7 @@ export function HostedPairingRouteSurface() {
   const [status, setStatus] = useState<"pairing" | "paired" | "error">("pairing");
   const [message, setMessage] = useState("Connecting to this backend.");
   const submitAttemptedRef = useRef(false);
+  const tokenSubmittedRef = useRef(false);
 
   const submitHostedPairingRequest = useCallback(async () => {
     const request = hostedPairingRequestRef.current;
@@ -176,8 +177,15 @@ export function HostedPairingRouteSurface() {
       return;
     }
 
+    if (tokenSubmittedRef.current) {
+      setStatus("error");
+      setMessage("This one-time pairing token was already submitted. Request a new pairing link.");
+      return;
+    }
+
     setStatus("pairing");
     setMessage("Connecting to this backend.");
+    tokenSubmittedRef.current = true;
 
     try {
       const record = await addSavedEnvironment({
@@ -189,7 +197,9 @@ export function HostedPairingRouteSurface() {
       setMessage(`${record.label} is saved in this browser.`);
     } catch (error) {
       setStatus("error");
-      setMessage(errorMessageFromUnknown(error));
+      setMessage(
+        `${errorMessageFromUnknown(error)} Request a new pairing link before trying again.`,
+      );
     }
   }, []);
 
@@ -240,13 +250,15 @@ export function HostedPairingRouteSurface() {
         ) : null}
 
         <div className="mt-6 flex flex-wrap gap-2">
-          <Button
-            disabled={status === "pairing"}
-            size="sm"
-            onClick={() => void submitHostedPairingRequest()}
-          >
-            {status === "pairing" ? "Pairing..." : "Try again"}
-          </Button>
+          {status === "pairing" ? (
+            <Button disabled size="sm">
+              Pairing...
+            </Button>
+          ) : !tokenSubmittedRef.current ? (
+            <Button size="sm" onClick={() => void submitHostedPairingRequest()}>
+              Try again
+            </Button>
+          ) : null}
           {status === "paired" ? (
             <Button size="sm" variant="outline" onClick={() => (window.location.href = "/")}>
               Open app
diff --git a/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
index 4066544c633..1bc08b1bfd7 100644
--- a/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
+++ b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
@@ -20,8 +20,10 @@ function describeSshTarget(request: DesktopSshPasswordPromptRequest): string {
 export function SshPasswordPromptDialog() {
   const [queue, setQueue] = useState<readonly DesktopSshPasswordPromptRequest[]>([]);
   const [password, setPassword] = useState("");
+  const [isResponding, setIsResponding] = useState(false);
   const currentRequest = queue[0] ?? null;
   const inputRef = useRef<HTMLInputElement | null>(null);
+  const isRespondingRef = useRef(false);
 
   useEffect(() => {
     const bridge = window.desktopBridge;
@@ -50,17 +52,24 @@ export function SshPasswordPromptDialog() {
   }, [currentRequest]);
 
   const respond = async (nextPassword: string | null) => {
-    if (!currentRequest) {
+    if (!currentRequest || isRespondingRef.current) {
       return;
     }
 
     const requestId = currentRequest.requestId;
-    setQueue((currentQueue) => currentQueue.slice(1));
-    setPassword("");
+    isRespondingRef.current = true;
+    setIsResponding(true);
     try {
       await window.desktopBridge?.resolveSshPasswordPrompt(requestId, nextPassword);
     } catch (error) {
       console.error("Failed to resolve SSH password prompt.", error);
+    } finally {
+      setQueue((currentQueue) =>
+        currentQueue[0]?.requestId === requestId ? currentQueue.slice(1) : currentQueue,
+      );
+      setPassword("");
+      isRespondingRef.current = false;
+      setIsResponding(false);
     }
   };
 
@@ -76,38 +85,51 @@ export function SshPasswordPromptDialog() {
       }}
     >
       <DialogPopup className="max-w-md" showCloseButton={false}>
-        <DialogHeader>
-          <DialogTitle>SSH Password Required</DialogTitle>
-          <DialogDescription>
-            T3 needs your SSH password to connect to{" "}
-            {target ? <code>{target}</code> : "the remote host"}. The password is passed to the
-            local SSH process for this connection attempt and is not saved by T3 Code.
-          </DialogDescription>
-        </DialogHeader>
-        <DialogPanel className="space-y-3" scrollFade={false}>
-          <div className="space-y-2">
-            <p className="text-sm font-medium text-foreground">{currentRequest?.prompt}</p>
-            <Input
-              ref={inputRef}
-              autoComplete="current-password"
-              name="ssh-password"
-              type="password"
-              value={password}
-              onChange={(event) => setPassword(event.target.value)}
-            />
-          </div>
-          <p className="text-sm text-muted-foreground">
-            Use SSH keys to avoid repeated password prompts on new SSH sessions.
-          </p>
-        </DialogPanel>
-        <DialogFooter>
-          <Button variant="outline" onClick={() => void respond(null)}>
-            Cancel
-          </Button>
-          <Button onClick={() => void respond(password)} type="button">
-            Continue
-          </Button>
-        </DialogFooter>
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            void respond(password);
+          }}
+        >
+          <DialogHeader>
+            <DialogTitle>SSH Password Required</DialogTitle>
+            <DialogDescription>
+              T3 needs your SSH password to connect to{" "}
+              {target ? <code>{target}</code> : "the remote host"}. The password is passed to the
+              local SSH process for this connection attempt and is not saved by T3 Code.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogPanel className="space-y-3" scrollFade={false}>
+            <div className="space-y-2">
+              <p className="text-sm font-medium text-foreground">{currentRequest?.prompt}</p>
+              <Input
+                ref={inputRef}
+                autoComplete="current-password"
+                disabled={isResponding}
+                name="ssh-password"
+                type="password"
+                value={password}
+                onChange={(event) => setPassword(event.target.value)}
+              />
+            </div>
+            <p className="text-sm text-muted-foreground">
+              Use SSH keys to avoid repeated password prompts on new SSH sessions.
+            </p>
+          </DialogPanel>
+          <DialogFooter>
+            <Button
+              disabled={isResponding}
+              type="button"
+              variant="outline"
+              onClick={() => void respond(null)}
+            >
+              Cancel
+            </Button>
+            <Button disabled={isResponding} type="submit">
+              Continue
+            </Button>
+          </DialogFooter>
+        </form>
       </DialogPopup>
     </Dialog>
   );
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 41ab20310ba..033c8a45b44 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1,17 +1,5 @@
-import {
-  ChevronDownIcon,
-  PlusIcon,
-  QrCodeIcon,
-  RefreshCwIcon,
-} from "lucide-react";
-import {
-  type ReactNode,
-  memo,
-  useCallback,
-  useEffect,
-  useMemo,
-  useState,
-} from "react";
+import { ChevronDownIcon, PlusIcon, QrCodeIcon, RefreshCwIcon } from "lucide-react";
+import { type ReactNode, memo, useCallback, useEffect, useMemo, useState } from "react";
 import {
   type AuthClientSession,
   type AuthPairingLink,
@@ -25,14 +13,8 @@ import { DateTime } from "effect";
 
 import { useCopyToClipboard } from "../../hooks/useCopyToClipboard";
 import { cn } from "../../lib/utils";
-import {
-  formatElapsedDurationLabel,
-  formatExpiresInLabel,
-} from "../../timestampFormat";
-import {
-  resolveDesktopPairingUrl,
-  resolveHostedPairingUrl,
-} from "./pairingUrls";
+import { formatElapsedDurationLabel, formatExpiresInLabel } from "../../timestampFormat";
+import { resolveDesktopPairingUrl, resolveHostedPairingUrl } from "./pairingUrls";
 import {
   SettingsPageContainer,
   SettingsRow,
@@ -132,9 +114,7 @@ function ConnectionStatusDot({
           )}
         />
       ) : null}
-      <span
-        className={cn("relative inline-flex size-2 rounded-full", dotClassName)}
-      />
+      <span className={cn("relative inline-flex size-2 rounded-full", dotClassName)} />
     </>
   );
 
@@ -160,10 +140,7 @@ function ConnectionStatusDot({
   return (
     <Tooltip>
       <TooltipTrigger render={dot} />
-      <TooltipPopup
-        side="top"
-        className="max-w-80 whitespace-pre-wrap leading-tight"
-      >
+      <TooltipPopup side="top" className="max-w-80 whitespace-pre-wrap leading-tight">
         {tooltipText}
       </TooltipPopup>
     </Tooltip>
@@ -179,9 +156,7 @@ function getSavedBackendStatusTooltip(
 
   if (connectionState === "connected") {
     const connectedAt = runtime?.connectedAt ?? record.lastConnectedAt;
-    return connectedAt
-      ? `Connected for ${formatElapsedDurationLabel(connectedAt, nowMs)}`
-      : null;
+    return connectedAt ? `Connected for ${formatElapsedDurationLabel(connectedAt, nowMs)}` : null;
   }
 
   if (connectionState === "connecting") {
@@ -197,12 +172,8 @@ function getSavedBackendStatusTooltip(
     : "Not connected yet.";
 }
 
-function formatDesktopSshTarget(
-  target: NonNullable<SavedEnvironmentRecord["desktopSsh"]>,
-): string {
-  const authority = target.username
-    ? `${target.username}@${target.hostname}`
-    : target.hostname;
+function formatDesktopSshTarget(target: NonNullable<SavedEnvironmentRecord["desktopSsh"]>): string {
+  const authority = target.username ? `${target.username}@${target.hostname}` : target.hostname;
   return target.port ? `${authority}:${target.port}` : authority;
 }
 
@@ -252,10 +223,7 @@ function parseManualDesktopSshTarget(input: {
     throw new Error("SSH host or alias is required.");
   }
 
-  if (
-    port !== null &&
-    (!Number.isInteger(port) || port <= 0 || port > 65_535)
-  ) {
+  if (port !== null && (!Number.isInteger(port) || port <= 0 || port > 65_535)) {
     throw new Error("SSH port must be between 1 and 65535.");
   }
 
@@ -268,26 +236,19 @@ function parseManualDesktopSshTarget(input: {
 }
 
 /** Direct row in the card – same pattern as the Provider / ACP-agent list rows. */
-const ITEM_ROW_CLASSNAME =
-  "border-t border-border/60 px-4 py-4 first:border-t-0 sm:px-5";
-const ENDPOINT_ROW_CLASSNAME =
-  "border-t border-border/60 px-4 py-2.5 first:border-t-0 sm:px-5";
+const ITEM_ROW_CLASSNAME = "border-t border-border/60 px-4 py-4 first:border-t-0 sm:px-5";
+const ENDPOINT_ROW_CLASSNAME = "border-t border-border/60 px-4 py-2.5 first:border-t-0 sm:px-5";
 
 const ITEM_ROW_INNER_CLASSNAME =
   "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between";
 
-function sortDesktopPairingLinks(
-  links: ReadonlyArray<ServerPairingLinkRecord>,
-) {
+function sortDesktopPairingLinks(links: ReadonlyArray<ServerPairingLinkRecord>) {
   return [...links].toSorted(
-    (left, right) =>
-      new Date(right.createdAt).getTime() - new Date(left.createdAt).getTime(),
+    (left, right) => new Date(right.createdAt).getTime() - new Date(left.createdAt).getTime(),
   );
 }
 
-function sortDesktopClientSessions(
-  sessions: ReadonlyArray<ServerClientSessionRecord>,
-) {
+function sortDesktopClientSessions(sessions: ReadonlyArray<ServerClientSessionRecord>) {
   return [...sessions].toSorted((left, right) => {
     if (left.current !== right.current) {
       return left.current ? -1 : 1;
@@ -295,15 +256,11 @@ function sortDesktopClientSessions(
     if (left.connected !== right.connected) {
       return left.connected ? -1 : 1;
     }
-    return (
-      new Date(right.issuedAt).getTime() - new Date(left.issuedAt).getTime()
-    );
+    return new Date(right.issuedAt).getTime() - new Date(left.issuedAt).getTime();
   });
 }
 
-function toDesktopPairingLinkRecord(
-  pairingLink: AuthPairingLink,
-): ServerPairingLinkRecord {
+function toDesktopPairingLinkRecord(pairingLink: AuthPairingLink): ServerPairingLinkRecord {
   return {
     ...pairingLink,
     createdAt: DateTime.formatIso(pairingLink.createdAt),
@@ -311,9 +268,7 @@ function toDesktopPairingLinkRecord(
   };
 }
 
-function toDesktopClientSessionRecord(
-  clientSession: AuthClientSession,
-): ServerClientSessionRecord {
+function toDesktopClientSessionRecord(clientSession: AuthClientSession): ServerClientSessionRecord {
   return {
     ...clientSession,
     issuedAt: DateTime.formatIso(clientSession.issuedAt),
@@ -329,9 +284,7 @@ function upsertDesktopPairingLink(
   current: ReadonlyArray<ServerPairingLinkRecord>,
   next: ServerPairingLinkRecord,
 ) {
-  const existingIndex = current.findIndex(
-    (pairingLink) => pairingLink.id === next.id,
-  );
+  const existingIndex = current.findIndex((pairingLink) => pairingLink.id === next.id);
   if (existingIndex === -1) {
     return sortDesktopPairingLinks([...current, next]);
   }
@@ -340,10 +293,7 @@ function upsertDesktopPairingLink(
   return sortDesktopPairingLinks(updated);
 }
 
-function removeDesktopPairingLink(
-  current: ReadonlyArray<ServerPairingLinkRecord>,
-  id: string,
-) {
+function removeDesktopPairingLink(current: ReadonlyArray<ServerPairingLinkRecord>, id: string) {
   return current.filter((pairingLink) => pairingLink.id !== id);
 }
 
@@ -366,22 +316,17 @@ function removeDesktopClientSession(
   current: ReadonlyArray<ServerClientSessionRecord>,
   sessionId: ServerClientSessionRecord["sessionId"],
 ) {
-  return current.filter(
-    (clientSession) => clientSession.sessionId !== sessionId,
-  );
+  return current.filter((clientSession) => clientSession.sessionId !== sessionId);
 }
 
 function selectPairingEndpoint(
   endpoints: ReadonlyArray<AdvertisedEndpoint>,
   defaultEndpointKey?: string | null,
 ): AdvertisedEndpoint | null {
-  const availableEndpoints = endpoints.filter(
-    (endpoint) => endpoint.status !== "unavailable",
-  );
+  const availableEndpoints = endpoints.filter((endpoint) => endpoint.status !== "unavailable");
   if (defaultEndpointKey) {
     const selectedEndpoint = availableEndpoints.find(
-      (endpoint) =>
-        endpointDefaultPreferenceKey(endpoint) === defaultEndpointKey,
+      (endpoint) => endpointDefaultPreferenceKey(endpoint) === defaultEndpointKey,
     );
     if (selectedEndpoint) {
       return selectedEndpoint;
@@ -389,12 +334,8 @@ function selectPairingEndpoint(
   }
   return (
     availableEndpoints.find((endpoint) => endpoint.isDefault) ??
-    availableEndpoints.find(
-      (endpoint) => endpoint.reachability !== "loopback",
-    ) ??
-    availableEndpoints.find(
-      (endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible",
-    ) ??
+    availableEndpoints.find((endpoint) => endpoint.reachability !== "loopback") ??
+    availableEndpoints.find((endpoint) => endpoint.compatibility.hostedHttpsApp === "compatible") ??
     null
   );
 }
@@ -491,26 +432,19 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
   );
   const endpointPairingUrl = useMemo(() => {
     const endpoint = selectPairingEndpoint(endpoints, defaultEndpointKey);
-    return endpoint
-      ? resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential)
-      : null;
+    return endpoint ? resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential) : null;
   }, [defaultEndpointKey, endpoints, pairingLink.credential]);
   const endpointCopyOptions = useMemo(
     () =>
       endpoints
         .filter((endpoint) => endpoint.status !== "unavailable")
         .map((endpoint) => {
-          const url = resolveAdvertisedEndpointPairingUrl(
-            endpoint,
-            pairingLink.credential,
-          );
+          const url = resolveAdvertisedEndpointPairingUrl(endpoint, pairingLink.credential);
           return {
             key: endpointDefaultPreferenceKey(endpoint),
             label: endpoint.label,
             url,
-            detail: isHostedAppPairingUrl(url)
-              ? "Hosted app link"
-              : "Backend pairing URL",
+            detail: isHostedAppPairingUrl(url) ? "Hosted app link" : "Backend pairing URL",
           };
         }),
     [endpoints, pairingLink.credential],
@@ -518,8 +452,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
   const shareablePairingUrl =
     endpointPairingUrl ??
     (endpointUrl != null && endpointUrl !== ""
-      ? (hostedPairingUrl ??
-        resolveDesktopPairingUrl(endpointUrl, pairingLink.credential))
+      ? (hostedPairingUrl ?? resolveDesktopPairingUrl(endpointUrl, pairingLink.credential))
       : isLoopbackHostname(window.location.hostname)
         ? null
         : currentOriginPairingUrl);
@@ -555,9 +488,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
               ? "Could not copy pairing URL"
               : "Could not copy pairing code"
             : "Clipboard copy unavailable",
-          description: canCopyToClipboard
-            ? error.message
-            : "Showing the full value instead.",
+          description: canCopyToClipboard ? error.message : "Showing the full value instead.",
         }),
       );
     },
@@ -597,9 +528,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
               tooltipText={`Link created at ${formatAccessTimestamp(pairingLink.createdAt)}`}
               dotClassName="bg-amber-400"
             />
-            <h3 className="text-sm font-medium text-foreground">
-              {primaryLabel}
-            </h3>
+            <h3 className="text-sm font-medium text-foreground">{primaryLabel}</h3>
             <Popover>
               {shareablePairingUrl ? (
                 <>
@@ -617,12 +546,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                   >
                     <QrCodeIcon aria-hidden className="size-3" />
                   </PopoverTrigger>
-                  <PopoverPopup
-                    side="top"
-                    align="start"
-                    tooltipStyle
-                    className="w-max"
-                  >
+                  <PopoverPopup side="top" align="start" tooltipStyle className="w-max">
                     <QRCodeSvg
                       value={shareablePairingUrl}
                       size={88}
@@ -636,23 +560,16 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
             </Popover>
           </div>
           <p className="text-xs text-muted-foreground" title={expiresAbsolute}>
-            {[
-              roleLabel,
-              formatExpiresInLabel(pairingLink.expiresAt, nowMs),
-            ].join(" · ")}
+            {[roleLabel, formatExpiresInLabel(pairingLink.expiresAt, nowMs)].join(" · ")}
           </p>
           {shareablePairingUrl === null ? (
             <p className="text-[11px] text-muted-foreground/70">
-              Copy the token and pair from another client using this
-              backend&apos;s reachable host.
+              Copy the token and pair from another client using this backend&apos;s reachable host.
             </p>
           ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
-          <Dialog
-            open={isRevealDialogOpen}
-            onOpenChange={setIsRevealDialogOpen}
-          >
+          <Dialog open={isRevealDialogOpen} onOpenChange={setIsRevealDialogOpen}>
             {canCopyToClipboard ? (
               <>
                 <Button size="xs" variant="outline" onClick={handleCopyCode}>
@@ -661,11 +578,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                 {shareablePairingUrl ? (
                   endpointCopyOptions.length > 1 ? (
                     <Group aria-label="Copy pairing URL">
-                      <Button
-                        size="xs"
-                        variant="outline"
-                        onClick={handleCopyDefaultLink}
-                      >
+                      <Button size="xs" variant="outline" onClick={handleCopyDefaultLink}>
                         {copyLinkLabel}
                       </Button>
                       <GroupSeparator />
@@ -685,14 +598,10 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                           {endpointCopyOptions.map((option) => (
                             <MenuItem
                               key={option.key}
-                              onClick={() =>
-                                copyPairingValue(option.url, "link")
-                              }
+                              onClick={() => copyPairingValue(option.url, "link")}
                             >
                               <span className="min-w-0 flex-1">
-                                <span className="block truncate">
-                                  {option.label}
-                                </span>
+                                <span className="block truncate">{option.label}</span>
                                 <span className="block truncate text-[11px] text-muted-foreground">
                                   {option.detail}
                                 </span>
@@ -703,11 +612,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                       </Menu>
                     </Group>
                   ) : (
-                    <Button
-                      size="xs"
-                      variant="outline"
-                      onClick={handleCopyDefaultLink}
-                    >
+                    <Button size="xs" variant="outline" onClick={handleCopyDefaultLink}>
                       {copyLinkLabel}
                     </Button>
                   )
@@ -757,10 +662,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
                 ) : null}
               </DialogPanel>
               <DialogFooter variant="bare">
-                <Button
-                  variant="outline"
-                  onClick={() => setIsRevealDialogOpen(false)}
-                >
+                <Button variant="outline" onClick={() => setIsRevealDialogOpen(false)}>
                   Done
                 </Button>
                 {canCopyToClipboard ? (
@@ -809,8 +711,7 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
   const roleLabel = clientSession.role === "owner" ? "Owner" : "Client";
   const deviceInfoBits = [
     clientSession.client.deviceType !== "unknown"
-      ? clientSession.client.deviceType[0]?.toUpperCase() +
-        clientSession.client.deviceType.slice(1)
+      ? clientSession.client.deviceType[0]?.toUpperCase() + clientSession.client.deviceType.slice(1)
       : null,
     clientSession.client.os ?? null,
     clientSession.client.browser ?? null,
@@ -818,9 +719,7 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
   ].filter((value): value is string => value !== null);
   const primaryLabel =
     clientSession.client.label ??
-    ([clientSession.client.os, clientSession.client.browser]
-      .filter(Boolean)
-      .join(" · ") ||
+    ([clientSession.client.os, clientSession.client.browser].filter(Boolean).join(" · ") ||
       clientSession.subject);
 
   return (
@@ -833,9 +732,7 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
               dotClassName={isLive ? "bg-success" : "bg-muted-foreground/30"}
               pingClassName={isLive ? "bg-success/60 duration-2000" : null}
             />
-            <h3 className="text-sm font-medium text-foreground">
-              {primaryLabel}
-            </h3>
+            <h3 className="text-sm font-medium text-foreground">{primaryLabel}</h3>
             {clientSession.current ? (
               <span className="text-[10px] text-muted-foreground/80 rounded-md border border-border/50 bg-muted/50 px-1 py-0.5">
                 This device
@@ -854,9 +751,7 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
               disabled={revokingClientSessionId === clientSession.sessionId}
               onClick={() => void onRevokeSession(clientSession.sessionId)}
             >
-              {revokingClientSessionId === clientSession.sessionId
-                ? "Revoking…"
-                : "Revoke"}
+              {revokingClientSessionId === clientSession.sessionId ? "Revoking…" : "Revoke"}
             </Button>
           ) : null}
         </div>
@@ -871,112 +766,103 @@ type AuthorizedClientsHeaderActionProps = {
   onRevokeOtherClients: () => void;
 };
 
-const AuthorizedClientsHeaderAction = memo(
-  function AuthorizedClientsHeaderAction({
-    clientSessions,
-    isRevokingOtherClients,
-    onRevokeOtherClients,
-  }: AuthorizedClientsHeaderActionProps) {
-    const [dialogOpen, setDialogOpen] = useState(false);
-    const [pairingLabel, setPairingLabel] = useState("");
-    const [isCreatingPairingLink, setIsCreatingPairingLink] = useState(false);
-
-    const handleCreatePairingLink = useCallback(async () => {
-      setIsCreatingPairingLink(true);
-      try {
-        await createServerPairingCredential(pairingLabel);
-        setPairingLabel("");
-        setDialogOpen(false);
-      } catch (error) {
-        const message =
-          error instanceof Error
-            ? error.message
-            : "Failed to create pairing URL.";
-        toastManager.add(
-          stackedThreadToast({
-            type: "error",
-            title: "Could not create pairing URL",
-            description: message,
-          }),
-        );
-      } finally {
-        setIsCreatingPairingLink(false);
-      }
-    }, [pairingLabel]);
+const AuthorizedClientsHeaderAction = memo(function AuthorizedClientsHeaderAction({
+  clientSessions,
+  isRevokingOtherClients,
+  onRevokeOtherClients,
+}: AuthorizedClientsHeaderActionProps) {
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [pairingLabel, setPairingLabel] = useState("");
+  const [isCreatingPairingLink, setIsCreatingPairingLink] = useState(false);
+
+  const handleCreatePairingLink = useCallback(async () => {
+    setIsCreatingPairingLink(true);
+    try {
+      await createServerPairingCredential(pairingLabel);
+      setPairingLabel("");
+      setDialogOpen(false);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to create pairing URL.";
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not create pairing URL",
+          description: message,
+        }),
+      );
+    } finally {
+      setIsCreatingPairingLink(false);
+    }
+  }, [pairingLabel]);
 
-    return (
-      <div className="flex items-center gap-2">
-        <Button
-          size="xs"
-          variant="destructive-outline"
-          disabled={
-            isRevokingOtherClients ||
-            clientSessions.every((clientSession) => clientSession.current)
+  return (
+    <div className="flex items-center gap-2">
+      <Button
+        size="xs"
+        variant="destructive-outline"
+        disabled={
+          isRevokingOtherClients || clientSessions.every((clientSession) => clientSession.current)
+        }
+        onClick={() => void onRevokeOtherClients()}
+      >
+        {isRevokingOtherClients ? "Revoking…" : "Revoke others"}
+      </Button>
+      <Dialog
+        open={dialogOpen}
+        onOpenChange={(open) => {
+          setDialogOpen(open);
+          if (!open) {
+            setPairingLabel("");
           }
-          onClick={() => void onRevokeOtherClients()}
-        >
-          {isRevokingOtherClients ? "Revoking…" : "Revoke others"}
-        </Button>
-        <Dialog
-          open={dialogOpen}
-          onOpenChange={(open) => {
-            setDialogOpen(open);
-            if (!open) {
-              setPairingLabel("");
-            }
-          }}
-        >
-          <DialogTrigger
-            render={
-              <Button size="xs" variant="default">
-                <PlusIcon className="size-3" />
-                Create link
-              </Button>
-            }
-          />
-          <DialogPopup className="max-w-sm">
-            <DialogHeader>
-              <DialogTitle>Create pairing link</DialogTitle>
-              <DialogDescription>
-                Generate a one-time link that another device can use to pair
-                with this backend as an authorized client.
-              </DialogDescription>
-            </DialogHeader>
-            <DialogPanel>
-              <label className="block">
-                <span className="mb-1.5 block text-xs font-medium text-foreground">
-                  Client label (optional)
-                </span>
-                <Input
-                  value={pairingLabel}
-                  onChange={(event) => setPairingLabel(event.target.value)}
-                  placeholder="e.g. Living room iPad"
-                  disabled={isCreatingPairingLink}
-                  autoFocus
-                />
-              </label>
-            </DialogPanel>
-            <DialogFooter variant="bare">
-              <Button
-                variant="outline"
-                disabled={isCreatingPairingLink}
-                onClick={() => setDialogOpen(false)}
-              >
-                Cancel
-              </Button>
-              <Button
+        }}
+      >
+        <DialogTrigger
+          render={
+            <Button size="xs" variant="default">
+              <PlusIcon className="size-3" />
+              Create link
+            </Button>
+          }
+        />
+        <DialogPopup className="max-w-sm">
+          <DialogHeader>
+            <DialogTitle>Create pairing link</DialogTitle>
+            <DialogDescription>
+              Generate a one-time link that another device can use to pair with this backend as an
+              authorized client.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogPanel>
+            <label className="block">
+              <span className="mb-1.5 block text-xs font-medium text-foreground">
+                Client label (optional)
+              </span>
+              <Input
+                value={pairingLabel}
+                onChange={(event) => setPairingLabel(event.target.value)}
+                placeholder="e.g. Living room iPad"
                 disabled={isCreatingPairingLink}
-                onClick={() => void handleCreatePairingLink()}
-              >
-                {isCreatingPairingLink ? "Creating…" : "Create link"}
-              </Button>
-            </DialogFooter>
-          </DialogPopup>
-        </Dialog>
-      </div>
-    );
-  },
-);
+                autoFocus
+              />
+            </label>
+          </DialogPanel>
+          <DialogFooter variant="bare">
+            <Button
+              variant="outline"
+              disabled={isCreatingPairingLink}
+              onClick={() => setDialogOpen(false)}
+            >
+              Cancel
+            </Button>
+            <Button disabled={isCreatingPairingLink} onClick={() => void handleCreatePairingLink()}>
+              {isCreatingPairingLink ? "Creating…" : "Create link"}
+            </Button>
+          </DialogFooter>
+        </DialogPopup>
+      </Dialog>
+    </div>
+  );
+});
 
 type PairingClientsListProps = {
   endpointUrl: string | null | undefined;
@@ -988,9 +874,7 @@ type PairingClientsListProps = {
   revokingPairingLinkId: string | null;
   revokingClientSessionId: string | null;
   onRevokePairingLink: (id: string) => void;
-  onRevokeClientSession: (
-    sessionId: ServerClientSessionRecord["sessionId"],
-  ) => void;
+  onRevokeClientSession: (sessionId: ServerClientSessionRecord["sessionId"]) => void;
 };
 
 const PairingClientsList = memo(function PairingClientsList({
@@ -1028,13 +912,9 @@ const PairingClientsList = memo(function PairingClientsList({
         />
       ))}
 
-      {pairingLinks.length === 0 &&
-      clientSessions.length === 0 &&
-      !isLoading ? (
+      {pairingLinks.length === 0 && clientSessions.length === 0 && !isLoading ? (
         <div className={ITEM_ROW_CLASSNAME}>
-          <p className="text-xs text-muted-foreground/60">
-            No pairing links or client sessions.
-          </p>
+          <p className="text-xs text-muted-foreground/60">No pairing links or client sessions.</p>
         </div>
       ) : null}
     </>
@@ -1059,8 +939,7 @@ const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
   isUpdatingTailscaleServe,
 }: AdvertisedEndpointListRowProps) {
   const isAvailable = endpoint.status === "available";
-  const needsTailscaleSetup =
-    isTailscaleHttpsEndpoint(endpoint) && endpoint.status !== "available";
+  const needsTailscaleSetup = isTailscaleHttpsEndpoint(endpoint) && endpoint.status !== "available";
   const canDisableTailscaleServe =
     isTailscaleHttpsEndpoint(endpoint) && endpoint.status === "available";
   const shouldShowEndpointUrl = !needsTailscaleSetup;
@@ -1112,11 +991,7 @@ const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
             </Button>
           ) : null}
           {!needsTailscaleSetup && !isDefault ? (
-            <Button
-              size="xs"
-              variant="outline"
-              onClick={() => onSetDefault(endpoint)}
-            >
+            <Button size="xs" variant="outline" onClick={() => onSetDefault(endpoint)}>
               Set as default
             </Button>
           ) : null}
@@ -1167,9 +1042,7 @@ function NetworkAccessDescription({
           {summary}
         </button>
       ) : (
-        <span className="inline-flex min-w-0 max-w-full items-baseline gap-2">
-          {summary}
-        </span>
+        <span className="inline-flex min-w-0 max-w-full items-baseline gap-2">{summary}</span>
       )}
     </span>
   );
@@ -1191,12 +1064,8 @@ function SavedBackendListRow({
   onRemove,
 }: SavedBackendListRowProps) {
   const nowMs = useRelativeTimeTick(1_000);
-  const record = useSavedEnvironmentRegistryStore(
-    (state) => state.byId[environmentId] ?? null,
-  );
-  const runtime = useSavedEnvironmentRuntimeStore(
-    (state) => state.byId[environmentId] ?? null,
-  );
+  const record = useSavedEnvironmentRegistryStore((state) => state.byId[environmentId] ?? null);
+  const runtime = useSavedEnvironmentRuntimeStore((state) => state.byId[environmentId] ?? null);
 
   if (!record) {
     return null;
@@ -1211,17 +1080,11 @@ function SavedBackendListRow({
         : connectionState === "error"
           ? "bg-destructive"
           : "bg-muted-foreground/40";
-  const roleLabel = runtime?.role
-    ? runtime.role === "owner"
-      ? "Owner"
-      : "Client"
-    : null;
+  const roleLabel = runtime?.role ? (runtime.role === "owner" ? "Owner" : "Client") : null;
   const descriptorLabel = runtime?.descriptor?.label ?? null;
   const statusTooltip = getSavedBackendStatusTooltip(runtime, record, nowMs);
   const metadataBits = [
-    record.desktopSsh
-      ? `SSH ${formatDesktopSshTarget(record.desktopSsh)}`
-      : null,
+    record.desktopSsh ? `SSH ${formatDesktopSshTarget(record.desktopSsh)}` : null,
     roleLabel,
     record.lastConnectedAt
       ? `Last connected ${formatAccessTimestamp(record.lastConnectedAt)}`
@@ -1237,24 +1100,16 @@ function SavedBackendListRow({
               tooltipText={statusTooltip}
               dotClassName={stateDotClassName}
               pingClassName={
-                connectionState === "connecting"
-                  ? "bg-warning/60 duration-2000"
-                  : null
+                connectionState === "connecting" ? "bg-warning/60 duration-2000" : null
               }
             />
-            <h3 className="text-sm font-medium text-foreground">
-              {record.label}
-            </h3>
+            <h3 className="text-sm font-medium text-foreground">{record.label}</h3>
           </div>
           {metadataBits.length > 0 ? (
-            <p className="text-xs text-muted-foreground">
-              {metadataBits.join(" · ")}
-            </p>
+            <p className="text-xs text-muted-foreground">{metadataBits.join(" · ")}</p>
           ) : null}
           {descriptorLabel && descriptorLabel !== record.label ? (
-            <p className="text-xs text-muted-foreground">
-              Server label: {descriptorLabel}
-            </p>
+            <p className="text-xs text-muted-foreground">Server label: {descriptorLabel}</p>
           ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
@@ -1264,9 +1119,7 @@ function SavedBackendListRow({
             disabled={reconnectingEnvironmentId === environmentId}
             onClick={() => void onReconnect(environmentId)}
           >
-            {reconnectingEnvironmentId === environmentId
-              ? "Reconnecting…"
-              : "Reconnect"}
+            {reconnectingEnvironmentId === environmentId ? "Reconnecting…" : "Reconnect"}
           </Button>
           <Button
             size="xs"
@@ -1296,29 +1149,18 @@ const DesktopSshHostRow = memo(function DesktopSshHostRow({
   onConnect,
 }: DesktopSshHostRowProps) {
   const address = formatDesktopSshTarget(target);
-  const secondaryBits = [
-    target.source === "ssh-config" ? "SSH config" : "Known hosts",
-    address,
-  ];
+  const secondaryBits = [target.source === "ssh-config" ? "SSH config" : "Known hosts", address];
   const buttonLabel =
-    connectingHostAlias === target.alias
-      ? "Connecting…"
-      : savedRecord
-        ? "Reconnect"
-        : "Connect";
+    connectingHostAlias === target.alias ? "Connecting…" : savedRecord ? "Reconnect" : "Connect";
 
   return (
     <div className={ITEM_ROW_CLASSNAME}>
       <div className={ITEM_ROW_INNER_CLASSNAME}>
         <div className="min-w-0 flex-1 space-y-1">
           <div className="flex min-h-5 items-center gap-1.5">
-            <h3 className="text-sm font-medium text-foreground">
-              {target.alias}
-            </h3>
+            <h3 className="text-sm font-medium text-foreground">{target.alias}</h3>
           </div>
-          <p className="text-xs text-muted-foreground">
-            {secondaryBits.join(" · ")}
-          </p>
+          <p className="text-xs text-muted-foreground">{secondaryBits.join(" · ")}</p>
           {savedRecord ? (
             <p className="text-xs text-muted-foreground">
               Saved as {savedRecord.label}
@@ -1348,19 +1190,13 @@ const DesktopSshHostRow = memo(function DesktopSshHostRow({
 
 export function ConnectionsSettings() {
   const desktopBridge = window.desktopBridge;
-  const [currentSessionRole, setCurrentSessionRole] = useState<
-    "owner" | "client" | null
-  >(desktopBridge ? "owner" : null);
+  const [currentSessionRole, setCurrentSessionRole] = useState<"owner" | "client" | null>(
+    desktopBridge ? "owner" : null,
+  );
   const [currentAuthPolicy, setCurrentAuthPolicy] = useState<
-    | "desktop-managed-local"
-    | "loopback-browser"
-    | "remote-reachable"
-    | "unsafe-no-auth"
-    | null
+    "desktop-managed-local" | "loopback-browser" | "remote-reachable" | "unsafe-no-auth" | null
   >(desktopBridge ? null : null);
-  const savedEnvironmentsById = useSavedEnvironmentRegistryStore(
-    (state) => state.byId,
-  );
+  const savedEnvironmentsById = useSavedEnvironmentRegistryStore((state) => state.byId);
   const savedEnvironmentIds = useMemo(
     () =>
       Object.values(savedEnvironmentsById)
@@ -1370,60 +1206,52 @@ export function ConnectionsSettings() {
   );
   const savedDesktopSshEnvironmentsByAlias = useMemo(
     () =>
-      Object.values(savedEnvironmentsById).reduce<
-        Record<string, SavedEnvironmentRecord>
-      >((accumulator, record) => {
-        if (record.desktopSsh?.alias) {
-          accumulator[record.desktopSsh.alias] = record;
-        }
-        return accumulator;
-      }, {}),
+      Object.values(savedEnvironmentsById).reduce<Record<string, SavedEnvironmentRecord>>(
+        (accumulator, record) => {
+          if (record.desktopSsh?.alias) {
+            accumulator[record.desktopSsh.alias] = record;
+          }
+          return accumulator;
+        },
+        {},
+      ),
     [savedEnvironmentsById],
   );
   const [discoveredSshHosts, setDiscoveredSshHosts] = useState<
     ReadonlyArray<DesktopDiscoveredSshHost>
   >([]);
-  const [hasLoadedDiscoveredSshHosts, setHasLoadedDiscoveredSshHosts] =
-    useState(false);
-  const [isLoadingDiscoveredSshHosts, setIsLoadingDiscoveredSshHosts] =
-    useState(false);
-  const [discoveredSshHostsError, setDiscoveredSshHostsError] = useState<
-    string | null
-  >(null);
-  const [connectingSshHostAlias, setConnectingSshHostAlias] = useState<
-    string | null
-  >(null);
+  const [hasLoadedDiscoveredSshHosts, setHasLoadedDiscoveredSshHosts] = useState(false);
+  const [isLoadingDiscoveredSshHosts, setIsLoadingDiscoveredSshHosts] = useState(false);
+  const [discoveredSshHostsError, setDiscoveredSshHostsError] = useState<string | null>(null);
+  const [connectingSshHostAlias, setConnectingSshHostAlias] = useState<string | null>(null);
 
   const [desktopServerExposureState, setDesktopServerExposureState] =
     useState<DesktopServerExposureState | null>(null);
   const [desktopAdvertisedEndpoints, setDesktopAdvertisedEndpoints] = useState<
     ReadonlyArray<AdvertisedEndpoint>
   >([]);
-  const [desktopServerExposureError, setDesktopServerExposureError] = useState<
-    string | null
-  >(null);
+  const [desktopServerExposureError, setDesktopServerExposureError] = useState<string | null>(null);
   const [desktopPairingLinks, setDesktopPairingLinks] = useState<
     ReadonlyArray<ServerPairingLinkRecord>
   >([]);
   const [desktopClientSessions, setDesktopClientSessions] = useState<
     ReadonlyArray<ServerClientSessionRecord>
   >([]);
-  const [desktopAccessManagementError, setDesktopAccessManagementError] =
-    useState<string | null>(null);
-  const [
-    isLoadingDesktopAccessManagement,
-    setIsLoadingDesktopAccessManagement,
-  ] = useState(false);
-  const [revokingDesktopPairingLinkId, setRevokingDesktopPairingLinkId] =
-    useState<string | null>(null);
-  const [revokingDesktopClientSessionId, setRevokingDesktopClientSessionId] =
-    useState<string | null>(null);
-  const [isRevokingOtherDesktopClients, setIsRevokingOtherDesktopClients] =
-    useState(false);
+  const [desktopAccessManagementError, setDesktopAccessManagementError] = useState<string | null>(
+    null,
+  );
+  const [isLoadingDesktopAccessManagement, setIsLoadingDesktopAccessManagement] = useState(false);
+  const [revokingDesktopPairingLinkId, setRevokingDesktopPairingLinkId] = useState<string | null>(
+    null,
+  );
+  const [revokingDesktopClientSessionId, setRevokingDesktopClientSessionId] = useState<
+    string | null
+  >(null);
+  const [isRevokingOtherDesktopClients, setIsRevokingOtherDesktopClients] = useState(false);
   const [addBackendDialogOpen, setAddBackendDialogOpen] = useState(false);
-  const [savedBackendMode, setSavedBackendMode] = useState<
-    "pairing-url" | "host-code" | "ssh"
-  >("pairing-url");
+  const [savedBackendMode, setSavedBackendMode] = useState<"pairing-url" | "host-code" | "ssh">(
+    "pairing-url",
+  );
   const [savedBackendLabel, setSavedBackendLabel] = useState("");
   const [savedBackendPairingUrl, setSavedBackendPairingUrl] = useState("");
   const [savedBackendHost, setSavedBackendHost] = useState("");
@@ -1431,37 +1259,24 @@ export function ConnectionsSettings() {
   const [savedBackendSshHost, setSavedBackendSshHost] = useState("");
   const [savedBackendSshUsername, setSavedBackendSshUsername] = useState("");
   const [savedBackendSshPort, setSavedBackendSshPort] = useState("");
-  const [savedBackendError, setSavedBackendError] = useState<string | null>(
-    null,
-  );
+  const [savedBackendError, setSavedBackendError] = useState<string | null>(null);
   const [isAddingSavedBackend, setIsAddingSavedBackend] = useState(false);
   const [reconnectingSavedEnvironmentId, setReconnectingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
   const [removingSavedEnvironmentId, setRemovingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
-  const [isUpdatingDesktopServerExposure, setIsUpdatingDesktopServerExposure] =
-    useState(false);
-  const [isUpdatingTailscaleServe, setIsUpdatingTailscaleServe] =
-    useState(false);
+  const [isUpdatingDesktopServerExposure, setIsUpdatingDesktopServerExposure] = useState(false);
+  const [isUpdatingTailscaleServe, setIsUpdatingTailscaleServe] = useState(false);
   const [pendingTailscaleServeEndpoint, setPendingTailscaleServeEndpoint] =
     useState<AdvertisedEndpoint | null>(null);
-  const [disableTailscaleServeDialogOpen, setDisableTailscaleServeDialogOpen] =
-    useState(false);
-  const [
-    pendingDisableTailscaleServeEndpoint,
-    setPendingDisableTailscaleServeEndpoint,
-  ] = useState<AdvertisedEndpoint | null>(null);
+  const [disableTailscaleServeDialogOpen, setDisableTailscaleServeDialogOpen] = useState(false);
   const [tailscaleServePortInput, setTailscaleServePortInput] = useState(
     String(DEFAULT_TAILSCALE_SERVE_PORT),
   );
-  const [
-    pendingDesktopServerExposureMode,
-    setPendingDesktopServerExposureMode,
-  ] = useState<DesktopServerExposureState["mode"] | null>(null);
-  const [
-    isAdvertisedEndpointListExpanded,
-    setIsAdvertisedEndpointListExpanded,
-  ] = useState(false);
+  const [pendingDesktopServerExposureMode, setPendingDesktopServerExposureMode] = useState<
+    DesktopServerExposureState["mode"] | null
+  >(null);
+  const [isAdvertisedEndpointListExpanded, setIsAdvertisedEndpointListExpanded] = useState(false);
   const defaultAdvertisedEndpointKey = useUiStateStore(
     (state) => state.defaultAdvertisedEndpointKey,
   );
@@ -1482,8 +1297,7 @@ export function ConnectionsSettings() {
 
   const pendingTailscaleServeBaseUrl = useMemo(() => {
     if (!pendingTailscaleServeEndpoint) return null;
-    if (!isTailscaleServePortValid)
-      return pendingTailscaleServeEndpoint.httpBaseUrl;
+    if (!isTailscaleServePortValid) return pendingTailscaleServeEndpoint.httpBaseUrl;
     if (parsedTailscaleServePort === DEFAULT_TAILSCALE_SERVE_PORT) {
       return pendingTailscaleServeEndpoint.httpBaseUrl;
     }
@@ -1494,11 +1308,7 @@ export function ConnectionsSettings() {
     } catch {
       return pendingTailscaleServeEndpoint.httpBaseUrl;
     }
-  }, [
-    isTailscaleServePortValid,
-    parsedTailscaleServePort,
-    pendingTailscaleServeEndpoint,
-  ]);
+  }, [isTailscaleServePortValid, parsedTailscaleServePort, pendingTailscaleServeEndpoint]);
 
   const handleDesktopServerExposureChange = useCallback(
     async (checked: boolean) => {
@@ -1514,9 +1324,7 @@ export function ConnectionsSettings() {
         setIsUpdatingDesktopServerExposure(false);
       } catch (error) {
         const message =
-          error instanceof Error
-            ? error.message
-            : "Failed to update network exposure.";
+          error instanceof Error ? error.message : "Failed to update network exposure.";
         setPendingDesktopServerExposureMode(null);
         setDesktopServerExposureError(message);
         toastManager.add(
@@ -1552,9 +1360,7 @@ export function ConnectionsSettings() {
       setPendingTailscaleServeEndpoint(null);
     } catch (error) {
       const message =
-        error instanceof Error
-          ? error.message
-          : "Failed to configure Tailscale HTTPS.";
+        error instanceof Error ? error.message : "Failed to configure Tailscale HTTPS.";
       setDesktopServerExposureError(message);
       toastManager.add(
         stackedThreadToast({
@@ -1571,10 +1377,7 @@ export function ConnectionsSettings() {
   const handleStartTailscaleServeSetup = useCallback(
     (endpoint: AdvertisedEndpoint) => {
       setTailscaleServePortInput(
-        String(
-          desktopServerExposureState?.tailscaleServePort ??
-            DEFAULT_TAILSCALE_SERVE_PORT,
-        ),
+        String(desktopServerExposureState?.tailscaleServePort ?? DEFAULT_TAILSCALE_SERVE_PORT),
       );
       setPendingTailscaleServeEndpoint(endpoint);
     },
@@ -1588,17 +1391,12 @@ export function ConnectionsSettings() {
     try {
       const nextState = await desktopBridge.setTailscaleServeEnabled({
         enabled: false,
-        port:
-          desktopServerExposureState?.tailscaleServePort ??
-          DEFAULT_TAILSCALE_SERVE_PORT,
+        port: desktopServerExposureState?.tailscaleServePort ?? DEFAULT_TAILSCALE_SERVE_PORT,
       });
       setDesktopServerExposureState(nextState);
       setDisableTailscaleServeDialogOpen(false);
     } catch (error) {
-      const message =
-        error instanceof Error
-          ? error.message
-          : "Failed to disable Tailscale HTTPS.";
+      const message = error instanceof Error ? error.message : "Failed to disable Tailscale HTTPS.";
       setDesktopServerExposureError(message);
       toastManager.add(
         stackedThreadToast({
@@ -1612,13 +1410,9 @@ export function ConnectionsSettings() {
     }
   }, [desktopBridge, desktopServerExposureState?.tailscaleServePort]);
 
-  const handleStartTailscaleServeDisable = useCallback(
-    (endpoint: AdvertisedEndpoint) => {
-      setPendingDisableTailscaleServeEndpoint(endpoint);
-      setDisableTailscaleServeDialogOpen(true);
-    },
-    [],
-  );
+  const handleStartTailscaleServeDisable = useCallback((_endpoint: AdvertisedEndpoint) => {
+    setDisableTailscaleServeDialogOpen(true);
+  }, []);
 
   const handleRevokeDesktopPairingLink = useCallback(async (id: string) => {
     setRevokingDesktopPairingLinkId(id);
@@ -1626,10 +1420,7 @@ export function ConnectionsSettings() {
     try {
       await revokeServerPairingLink(id);
     } catch (error) {
-      const message =
-        error instanceof Error
-          ? error.message
-          : "Failed to revoke pairing link.";
+      const message = error instanceof Error ? error.message : "Failed to revoke pairing link.";
       setDesktopAccessManagementError(message);
       toastManager.add(
         stackedThreadToast({
@@ -1650,10 +1441,7 @@ export function ConnectionsSettings() {
       try {
         await revokeServerClientSession(sessionId);
       } catch (error) {
-        const message =
-          error instanceof Error
-            ? error.message
-            : "Failed to revoke client access.";
+        const message = error instanceof Error ? error.message : "Failed to revoke client access.";
         setDesktopAccessManagementError(message);
         toastManager.add(
           stackedThreadToast({
@@ -1676,18 +1464,11 @@ export function ConnectionsSettings() {
       const revokedCount = await revokeOtherServerClientSessions();
       toastManager.add({
         type: "success",
-        title:
-          revokedCount === 1
-            ? "Revoked 1 other client"
-            : `Revoked ${revokedCount} clients`,
-        description:
-          "Other paired clients will need a new pairing link before reconnecting.",
+        title: revokedCount === 1 ? "Revoked 1 other client" : `Revoked ${revokedCount} clients`,
+        description: "Other paired clients will need a new pairing link before reconnecting.",
       });
     } catch (error) {
-      const message =
-        error instanceof Error
-          ? error.message
-          : "Failed to revoke other clients.";
+      const message = error instanceof Error ? error.message : "Failed to revoke other clients.";
       setDesktopAccessManagementError(message);
       toastManager.add(
         stackedThreadToast({
@@ -1729,10 +1510,7 @@ export function ConnectionsSettings() {
           description: `${record.label} is ready over an SSH-managed tunnel.`,
         });
       } catch (error) {
-        const message =
-          error instanceof Error
-            ? error.message
-            : "Failed to connect SSH host.";
+        const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
 
         setSavedBackendError(message);
         toastManager.add({
@@ -1772,8 +1550,7 @@ export function ConnectionsSettings() {
         description: `${record.label} is now saved and will reconnect on app startup.`,
       });
     } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Failed to add backend.";
+      const message = error instanceof Error ? error.message : "Failed to add backend.";
       setSavedBackendError(message);
       toastManager.add(
         stackedThreadToast({
@@ -1796,55 +1573,45 @@ export function ConnectionsSettings() {
     savedBackendSshUsername,
   ]);
 
-  const handleReconnectSavedBackend = useCallback(
-    async (environmentId: EnvironmentId) => {
-      setReconnectingSavedEnvironmentId(environmentId);
-      setSavedBackendError(null);
-      try {
-        await reconnectSavedEnvironment(environmentId);
-      } catch (error) {
-        const message =
-          error instanceof Error
-            ? error.message
-            : "Failed to reconnect backend.";
-        setSavedBackendError(message);
-        toastManager.add(
-          stackedThreadToast({
-            type: "error",
-            title: "Could not reconnect backend",
-            description: message,
-          }),
-        );
-      } finally {
-        setReconnectingSavedEnvironmentId(null);
-      }
-    },
-    [],
-  );
+  const handleReconnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
+    setReconnectingSavedEnvironmentId(environmentId);
+    setSavedBackendError(null);
+    try {
+      await reconnectSavedEnvironment(environmentId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to reconnect backend.";
+      setSavedBackendError(message);
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not reconnect backend",
+          description: message,
+        }),
+      );
+    } finally {
+      setReconnectingSavedEnvironmentId(null);
+    }
+  }, []);
 
-  const handleRemoveSavedBackend = useCallback(
-    async (environmentId: EnvironmentId) => {
-      setRemovingSavedEnvironmentId(environmentId);
-      setSavedBackendError(null);
-      try {
-        await removeSavedEnvironment(environmentId);
-      } catch (error) {
-        const message =
-          error instanceof Error ? error.message : "Failed to remove backend.";
-        setSavedBackendError(message);
-        toastManager.add(
-          stackedThreadToast({
-            type: "error",
-            title: "Could not remove backend",
-            description: message,
-          }),
-        );
-      } finally {
-        setRemovingSavedEnvironmentId(null);
-      }
-    },
-    [],
-  );
+  const handleRemoveSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
+    setRemovingSavedEnvironmentId(environmentId);
+    setSavedBackendError(null);
+    try {
+      await removeSavedEnvironment(environmentId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to remove backend.";
+      setSavedBackendError(message);
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not remove backend",
+          description: message,
+        }),
+      );
+    } finally {
+      setRemovingSavedEnvironmentId(null);
+    }
+  }, []);
 
   const loadDiscoveredSshHosts = useCallback(async () => {
     if (!desktopBridge) {
@@ -1861,10 +1628,7 @@ export function ConnectionsSettings() {
       setDiscoveredSshHosts(hosts);
       setHasLoadedDiscoveredSshHosts(true);
     } catch (error) {
-      const message =
-        error instanceof Error
-          ? error.message
-          : "Failed to discover SSH hosts.";
+      const message = error instanceof Error ? error.message : "Failed to discover SSH hosts.";
       setDiscoveredSshHostsError(message);
       setHasLoadedDiscoveredSshHosts(true);
     } finally {
@@ -1898,10 +1662,7 @@ export function ConnectionsSettings() {
           description: `${record.label} is ready over an SSH-managed tunnel.`,
         });
       } catch (error) {
-        const message =
-          error instanceof Error
-            ? error.message
-            : "Failed to connect SSH host.";
+        const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
         if (savedBackendMode === "ssh") {
           setSavedBackendError(message);
         } else {
@@ -1946,9 +1707,7 @@ export function ConnectionsSettings() {
     void fetchSessionState()
       .then((session) => {
         if (cancelled) return;
-        setCurrentSessionRole(
-          session.authenticated ? (session.role ?? null) : null,
-        );
+        setCurrentSessionRole(session.authenticated ? (session.role ?? null) : null);
         setCurrentAuthPolicy(session.auth.policy);
       })
       .catch(() => {
@@ -1981,27 +1740,22 @@ export function ConnectionsSettings() {
             case "snapshot":
               setDesktopPairingLinks(
                 sortDesktopPairingLinks(
-                  event.payload.pairingLinks.map(
-                    (pairingLink: AuthPairingLink) =>
-                      toDesktopPairingLinkRecord(pairingLink),
+                  event.payload.pairingLinks.map((pairingLink: AuthPairingLink) =>
+                    toDesktopPairingLinkRecord(pairingLink),
                   ),
                 ),
               );
               setDesktopClientSessions(
                 sortDesktopClientSessions(
-                  event.payload.clientSessions.map(
-                    (clientSession: AuthClientSession) =>
-                      toDesktopClientSessionRecord(clientSession),
+                  event.payload.clientSessions.map((clientSession: AuthClientSession) =>
+                    toDesktopClientSessionRecord(clientSession),
                   ),
                 ),
               );
               break;
             case "pairingLinkUpserted":
               setDesktopPairingLinks((current) =>
-                upsertDesktopPairingLink(
-                  current,
-                  toDesktopPairingLinkRecord(event.payload),
-                ),
+                upsertDesktopPairingLink(current, toDesktopPairingLinkRecord(event.payload)),
               );
               break;
             case "pairingLinkRemoved":
@@ -2011,10 +1765,7 @@ export function ConnectionsSettings() {
               break;
             case "clientUpserted":
               setDesktopClientSessions((current) =>
-                upsertDesktopClientSession(
-                  current,
-                  toDesktopClientSessionRecord(event.payload),
-                ),
+                upsertDesktopClientSession(current, toDesktopClientSessionRecord(event.payload)),
               );
               break;
             case "clientRemoved":
@@ -2045,9 +1796,7 @@ export function ConnectionsSettings() {
         .catch((error: unknown) => {
           if (cancelled) return;
           const message =
-            error instanceof Error
-              ? error.message
-              : "Failed to load network exposure state.";
+            error instanceof Error ? error.message : "Failed to load network exposure state.";
           setDesktopServerExposureError(message);
         });
       void desktopBridge
@@ -2059,9 +1808,7 @@ export function ConnectionsSettings() {
         .catch((error: unknown) => {
           if (cancelled) return;
           const message =
-            error instanceof Error
-              ? error.message
-              : "Failed to load reachable endpoints.";
+            error instanceof Error ? error.message : "Failed to load reachable endpoints.";
           setDesktopServerExposureError(message);
         });
     } else {
@@ -2087,10 +1834,7 @@ export function ConnectionsSettings() {
     setDesktopServerExposureError(null);
   }, [canManageLocalBackend]);
   const visibleDesktopPairingLinks = useMemo(
-    () =>
-      desktopPairingLinks.filter(
-        (pairingLink) => pairingLink.role === "client",
-      ),
+    () => desktopPairingLinks.filter((pairingLink) => pairingLink.role === "client"),
     [desktopPairingLinks],
   );
   const tailscaleHttpsEndpoint = useMemo(
@@ -2100,9 +1844,7 @@ export function ConnectionsSettings() {
   const visibleDesktopNetworkAdvertisedEndpoints = useMemo(
     () =>
       isLocalBackendNetworkAccessible
-        ? desktopAdvertisedEndpoints.filter(
-            (endpoint) => !isTailscaleHttpsEndpoint(endpoint),
-          )
+        ? desktopAdvertisedEndpoints.filter((endpoint) => !isTailscaleHttpsEndpoint(endpoint))
         : [],
     [desktopAdvertisedEndpoints, isLocalBackendNetworkAccessible],
   );
@@ -2114,14 +1856,10 @@ export function ConnectionsSettings() {
     [tailscaleHttpsEndpoint, visibleDesktopNetworkAdvertisedEndpoints],
   );
   const isLocalBackendRemotelyReachable =
-    isLocalBackendNetworkAccessible ||
-    tailscaleHttpsEndpoint?.status === "available";
+    isLocalBackendNetworkAccessible || tailscaleHttpsEndpoint?.status === "available";
   const defaultDesktopNetworkAdvertisedEndpoint = useMemo(
     () =>
-      selectPairingEndpoint(
-        visibleDesktopNetworkAdvertisedEndpoints,
-        defaultAdvertisedEndpointKey,
-      ),
+      selectPairingEndpoint(visibleDesktopNetworkAdvertisedEndpoints, defaultAdvertisedEndpointKey),
     [defaultAdvertisedEndpointKey, visibleDesktopNetworkAdvertisedEndpoints],
   );
   const defaultDesktopAdvertisedEndpoint = useMemo(
@@ -2131,11 +1869,7 @@ export function ConnectionsSettings() {
         tailscaleHttpsEndpoint ? [tailscaleHttpsEndpoint] : [],
         defaultAdvertisedEndpointKey,
       ),
-    [
-      defaultAdvertisedEndpointKey,
-      defaultDesktopNetworkAdvertisedEndpoint,
-      tailscaleHttpsEndpoint,
-    ],
+    [defaultAdvertisedEndpointKey, defaultDesktopNetworkAdvertisedEndpoint, tailscaleHttpsEndpoint],
   );
   const defaultDesktopAdvertisedEndpointKey = defaultDesktopAdvertisedEndpoint
     ? endpointDefaultPreferenceKey(defaultDesktopAdvertisedEndpoint)
@@ -2165,9 +1899,7 @@ export function ConnectionsSettings() {
                         )}
                         expanded={isAdvertisedEndpointListExpanded}
                         onToggleExpanded={() =>
-                          setIsAdvertisedEndpointListExpanded(
-                            (expanded) => !expanded,
-                          )
+                          setIsAdvertisedEndpointListExpanded((expanded) => !expanded)
                         }
                         fallback={
                           desktopServerExposureState?.endpointUrl
@@ -2185,9 +1917,7 @@ export function ConnectionsSettings() {
                   }
                   status={
                     desktopServerExposureError ? (
-                      <span className="block text-destructive">
-                        {desktopServerExposureError}
-                      </span>
+                      <span className="block text-destructive">{desktopServerExposureError}</span>
                     ) : null
                   }
                   control={
@@ -2199,14 +1929,8 @@ export function ConnectionsSettings() {
                       }}
                     >
                       <Switch
-                        checked={
-                          desktopServerExposureState?.mode ===
-                          "network-accessible"
-                        }
-                        disabled={
-                          !desktopServerExposureState ||
-                          isUpdatingDesktopServerExposure
-                        }
+                        checked={desktopServerExposureState?.mode === "network-accessible"}
+                        disabled={!desktopServerExposureState || isUpdatingDesktopServerExposure}
                         onCheckedChange={(checked) => {
                           setPendingDesktopServerExposureMode(
                             checked ? "network-accessible" : "local-only",
@@ -2217,14 +1941,12 @@ export function ConnectionsSettings() {
                       <AlertDialogPopup>
                         <AlertDialogHeader>
                           <AlertDialogTitle>
-                            {pendingDesktopServerExposureMode ===
-                            "network-accessible"
+                            {pendingDesktopServerExposureMode === "network-accessible"
                               ? "Enable network access?"
                               : "Disable network access?"}
                           </AlertDialogTitle>
                           <AlertDialogDescription>
-                            {pendingDesktopServerExposureMode ===
-                            "network-accessible"
+                            {pendingDesktopServerExposureMode === "network-accessible"
                               ? "T3 Code will restart to expose this environment over the network."
                               : "T3 Code will restart and limit this environment back to this machine."}
                           </AlertDialogDescription>
@@ -2258,8 +1980,7 @@ export function ConnectionsSettings() {
                                 <Spinner className="size-3.5" />
                                 Restarting…
                               </>
-                            ) : pendingDesktopServerExposureMode ===
-                              "network-accessible" ? (
+                            ) : pendingDesktopServerExposureMode === "network-accessible" ? (
                               "Restart and enable"
                             ) : (
                               "Restart and disable"
@@ -2272,20 +1993,15 @@ export function ConnectionsSettings() {
                 />
                 {isAdvertisedEndpointListExpanded
                   ? visibleDesktopNetworkAdvertisedEndpoints.map((endpoint) => {
-                      const endpointKey =
-                        endpointDefaultPreferenceKey(endpoint);
+                      const endpointKey = endpointDefaultPreferenceKey(endpoint);
                       return (
                         <AdvertisedEndpointListRow
                           key={endpoint.id}
                           endpoint={endpoint}
-                          isDefault={
-                            endpointKey === defaultDesktopAdvertisedEndpointKey
-                          }
+                          isDefault={endpointKey === defaultDesktopAdvertisedEndpointKey}
                           onSetDefault={handleSetDefaultAdvertisedEndpoint}
                           onSetupTailscaleServe={handleStartTailscaleServeSetup}
-                          onDisableTailscaleServe={
-                            handleStartTailscaleServeDisable
-                          }
+                          onDisableTailscaleServe={handleStartTailscaleServeDisable}
                           isUpdatingTailscaleServe={isUpdatingTailscaleServe}
                         />
                       );
@@ -2307,14 +2023,10 @@ export function ConnectionsSettings() {
                         disabled={isUpdatingTailscaleServe}
                         onCheckedChange={(checked) => {
                           if (checked) {
-                            handleStartTailscaleServeSetup(
-                              tailscaleHttpsEndpoint,
-                            );
+                            handleStartTailscaleServeSetup(tailscaleHttpsEndpoint);
                             return;
                           }
-                          handleStartTailscaleServeDisable(
-                            tailscaleHttpsEndpoint,
-                          );
+                          handleStartTailscaleServeDisable(tailscaleHttpsEndpoint);
                         }}
                         aria-label="Enable Tailscale HTTPS"
                       />
@@ -2327,39 +2039,24 @@ export function ConnectionsSettings() {
                     if (isUpdatingTailscaleServe) return;
                     setDisableTailscaleServeDialogOpen(open);
                   }}
-                  onOpenChangeComplete={(open) => {
-                    if (!open) {
-                      setPendingDisableTailscaleServeEndpoint(null);
-                    }
-                  }}
                 >
                   <AlertDialogPopup>
                     <AlertDialogHeader>
-                      <AlertDialogTitle>
-                        Disable Tailscale HTTPS?
-                      </AlertDialogTitle>
+                      <AlertDialogTitle>Disable Tailscale HTTPS?</AlertDialogTitle>
                       <AlertDialogDescription>
-                        T3 Code will restart the local backend without Tailscale
-                        Serve.
+                        T3 Code will restart the local backend without Tailscale Serve.
                       </AlertDialogDescription>
                     </AlertDialogHeader>
                     <AlertDialogFooter>
                       <AlertDialogClose
                         disabled={isUpdatingTailscaleServe}
-                        render={
-                          <Button
-                            variant="outline"
-                            disabled={isUpdatingTailscaleServe}
-                          />
-                        }
+                        render={<Button variant="outline" disabled={isUpdatingTailscaleServe} />}
                       >
                         Cancel
                       </AlertDialogClose>
                       <Button
                         variant="destructive"
-                        onClick={() =>
-                          void handleConfirmTailscaleServeDisable()
-                        }
+                        onClick={() => void handleConfirmTailscaleServeDisable()}
                         disabled={isUpdatingTailscaleServe}
                       >
                         {isUpdatingTailscaleServe ? (
@@ -2385,16 +2082,13 @@ export function ConnectionsSettings() {
                     <DialogHeader>
                       <DialogTitle>Set up Tailscale HTTPS?</DialogTitle>
                       <DialogDescription>
-                        T3 Code will restart the local backend with Tailscale
-                        Serve enabled and ask Tailscale to proxy HTTPS traffic
-                        to this backend.
+                        T3 Code will restart the local backend with Tailscale Serve enabled and ask
+                        Tailscale to proxy HTTPS traffic to this backend.
                       </DialogDescription>
                     </DialogHeader>
                     <DialogPanel className="space-y-4">
                       <label className="block">
-                        <span className="text-sm font-medium text-foreground">
-                          HTTPS port
-                        </span>
+                        <span className="text-sm font-medium text-foreground">HTTPS port</span>
                         <Input
                           className="mt-2"
                           type="number"
@@ -2403,9 +2097,7 @@ export function ConnectionsSettings() {
                           max={65_535}
                           step={1}
                           value={tailscaleServePortInput}
-                          onChange={(event) =>
-                            setTailscaleServePortInput(event.target.value)
-                          }
+                          onChange={(event) => setTailscaleServePortInput(event.target.value)}
                           disabled={isUpdatingTailscaleServe}
                         />
                       </label>
@@ -2415,35 +2107,25 @@ export function ConnectionsSettings() {
                         </p>
                       ) : null}
                       <div className="rounded-md border border-border/70 bg-muted/20 px-3 py-2">
-                        <p className="text-xs font-medium text-muted-foreground">
-                          HTTPS endpoint
-                        </p>
+                        <p className="text-xs font-medium text-muted-foreground">HTTPS endpoint</p>
                         <p
                           className="mt-1 truncate text-sm text-foreground"
                           title={pendingTailscaleServeBaseUrl ?? undefined}
                         >
-                          {pendingTailscaleServeBaseUrl ??
-                            "Pending MagicDNS endpoint"}
+                          {pendingTailscaleServeBaseUrl ?? "Pending MagicDNS endpoint"}
                         </p>
                       </div>
                     </DialogPanel>
                     <DialogFooter>
                       <DialogClose
                         disabled={isUpdatingTailscaleServe}
-                        render={
-                          <Button
-                            variant="outline"
-                            disabled={isUpdatingTailscaleServe}
-                          />
-                        }
+                        render={<Button variant="outline" disabled={isUpdatingTailscaleServe} />}
                       >
                         Cancel
                       </DialogClose>
                       <Button
                         onClick={() => void handleConfirmTailscaleServeSetup()}
-                        disabled={
-                          isUpdatingTailscaleServe || !isTailscaleServePortValid
-                        }
+                        disabled={isUpdatingTailscaleServe || !isTailscaleServePortValid}
                       >
                         {isUpdatingTailscaleServe ? (
                           <>
@@ -2480,8 +2162,8 @@ export function ConnectionsSettings() {
                       }
                     />
                     <TooltipPopup side="top">
-                      Network exposure changes restart the backend and must be
-                      controlled where the server process is launched.
+                      Network exposure changes restart the backend and must be controlled where the
+                      server process is launched.
                     </TooltipPopup>
                   </Tooltip>
                 }
@@ -2502,9 +2184,7 @@ export function ConnectionsSettings() {
             >
               {desktopAccessManagementError ? (
                 <div className={ITEM_ROW_CLASSNAME}>
-                  <p className="text-xs text-destructive">
-                    {desktopAccessManagementError}
-                  </p>
+                  <p className="text-xs text-destructive">{desktopAccessManagementError}</p>
                 </div>
               ) : null}
               <PairingClientsList
@@ -2554,9 +2234,7 @@ export function ConnectionsSettings() {
             <DialogPopup className="max-h-[80dvh] sm:max-w-3xl">
               <DialogHeader>
                 <DialogTitle>Add Environment</DialogTitle>
-                <DialogDescription>
-                  Pair another environment to this client.
-                </DialogDescription>
+                <DialogDescription>Pair another environment to this client.</DialogDescription>
                 <div className="flex gap-1 rounded-lg border border-border/60 bg-muted/50 p-1">
                   <button
                     type="button"
@@ -2605,8 +2283,7 @@ export function ConnectionsSettings() {
                 <div className="space-y-4">
                   {savedBackendMode === "pairing-url" ? (
                     <p className="text-xs text-muted-foreground">
-                      Enter the full pairing URL from the environment you want
-                      to connect to.
+                      Enter the full pairing URL from the environment you want to connect to.
                     </p>
                   ) : savedBackendMode === "host-code" ? (
                     <p className="text-xs text-muted-foreground">
@@ -2614,9 +2291,8 @@ export function ConnectionsSettings() {
                     </p>
                   ) : (
                     <p className="text-xs text-muted-foreground">
-                      Connect over SSH using an existing alias from{" "}
-                      <code>~/.ssh/config</code> or enter a host directly. T3
-                      uses your current SSH agent and config.
+                      Connect over SSH using an existing alias from <code>~/.ssh/config</code> or
+                      enter a host directly. T3 uses your current SSH agent and config.
                     </p>
                   )}
                   {savedBackendMode === "pairing-url" ? (
@@ -2627,9 +2303,7 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendLabel}
-                          onChange={(event) =>
-                            setSavedBackendLabel(event.target.value)
-                          }
+                          onChange={(event) => setSavedBackendLabel(event.target.value)}
                           placeholder="My backend (optional)"
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -2641,9 +2315,7 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendPairingUrl}
-                          onChange={(event) =>
-                            setSavedBackendPairingUrl(event.target.value)
-                          }
+                          onChange={(event) => setSavedBackendPairingUrl(event.target.value)}
                           placeholder="https://backend.example.com/pair#token=..."
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -2661,9 +2333,7 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendLabel}
-                          onChange={(event) =>
-                            setSavedBackendLabel(event.target.value)
-                          }
+                          onChange={(event) => setSavedBackendLabel(event.target.value)}
                           placeholder="My backend (optional)"
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -2675,9 +2345,7 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendHost}
-                          onChange={(event) =>
-                            setSavedBackendHost(event.target.value)
-                          }
+                          onChange={(event) => setSavedBackendHost(event.target.value)}
                           placeholder="https://backend.example.com"
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -2689,9 +2357,7 @@ export function ConnectionsSettings() {
                         </span>
                         <Input
                           value={savedBackendPairingCode}
-                          onChange={(event) =>
-                            setSavedBackendPairingCode(event.target.value)
-                          }
+                          onChange={(event) => setSavedBackendPairingCode(event.target.value)}
                           placeholder="Pairing code"
                           disabled={isAddingSavedBackend}
                           spellCheck={false}
@@ -2702,12 +2368,9 @@ export function ConnectionsSettings() {
                     <div className="space-y-4">
                       <div className="flex items-start justify-between gap-3">
                         <div className="min-w-0">
-                          <h3 className="text-sm font-medium text-foreground">
-                            Discovered hosts
-                          </h3>
+                          <h3 className="text-sm font-medium text-foreground">Discovered hosts</h3>
                           <p className="text-xs text-muted-foreground">
-                            From <code>~/.ssh/config</code> and{" "}
-                            <code>known_hosts</code>.
+                            From <code>~/.ssh/config</code> and <code>known_hosts</code>.
                           </p>
                         </div>
                         <Button
@@ -2725,9 +2388,7 @@ export function ConnectionsSettings() {
                         </Button>
                       </div>
                       {discoveredSshHostsError ? (
-                        <p className="text-xs text-destructive">
-                          {discoveredSshHostsError}
-                        </p>
+                        <p className="text-xs text-destructive">{discoveredSshHostsError}</p>
                       ) : null}
                       <ScrollArea scrollFade className="max-h-64">
                         <div>
@@ -2735,15 +2396,9 @@ export function ConnectionsSettings() {
                             <DesktopSshHostRow
                               key={`${target.alias}:${target.hostname}:${target.port ?? ""}`}
                               target={target}
-                              savedRecord={
-                                savedDesktopSshEnvironmentsByAlias[
-                                  target.alias
-                                ] ?? null
-                              }
+                              savedRecord={savedDesktopSshEnvironmentsByAlias[target.alias] ?? null}
                               connectingHostAlias={connectingSshHostAlias}
-                              onConnect={(nextTarget) =>
-                                void handleConnectSshHost(nextTarget)
-                              }
+                              onConnect={(nextTarget) => void handleConnectSshHost(nextTarget)}
                             />
                           ))}
                           {hasLoadedDiscoveredSshHosts &&
@@ -2751,8 +2406,7 @@ export function ConnectionsSettings() {
                           discoveredSshHosts.length === 0 ? (
                             <div className={ITEM_ROW_CLASSNAME}>
                               <p className="text-xs text-muted-foreground">
-                                No SSH hosts were discovered from{" "}
-                                <code>~/.ssh/config</code> or{" "}
+                                No SSH hosts were discovered from <code>~/.ssh/config</code> or{" "}
                                 <code>known_hosts</code>.
                               </p>
                             </div>
@@ -2760,17 +2414,14 @@ export function ConnectionsSettings() {
                         </div>
                       </ScrollArea>
                       {savedBackendError ? (
-                        <p className="text-xs text-destructive">
-                          {savedBackendError}
-                        </p>
+                        <p className="text-xs text-destructive">{savedBackendError}</p>
                       ) : null}
                       <div className="border-t border-border/60 pt-4">
                         <h3 className="mb-1 text-sm font-medium text-foreground">
                           Enter a host manually
                         </h3>
                         <p className="mb-3 text-xs text-muted-foreground">
-                          Use an alias or enter host, username, and port
-                          directly.
+                          Use an alias or enter host, username, and port directly.
                         </p>
                         <div className="space-y-3">
                           <label className="block">
@@ -2779,9 +2430,7 @@ export function ConnectionsSettings() {
                             </span>
                             <Input
                               value={savedBackendLabel}
-                              onChange={(event) =>
-                                setSavedBackendLabel(event.target.value)
-                              }
+                              onChange={(event) => setSavedBackendLabel(event.target.value)}
                               placeholder="My backend (optional)"
                               disabled={isAddingSavedBackend}
                               spellCheck={false}
@@ -2793,9 +2442,7 @@ export function ConnectionsSettings() {
                             </span>
                             <Input
                               value={savedBackendSshHost}
-                              onChange={(event) =>
-                                setSavedBackendSshHost(event.target.value)
-                              }
+                              onChange={(event) => setSavedBackendSshHost(event.target.value)}
                               placeholder="devbox or devbox.example.com"
                               disabled={isAddingSavedBackend}
                               spellCheck={false}
@@ -2808,9 +2455,7 @@ export function ConnectionsSettings() {
                               </span>
                               <Input
                                 value={savedBackendSshUsername}
-                                onChange={(event) =>
-                                  setSavedBackendSshUsername(event.target.value)
-                                }
+                                onChange={(event) => setSavedBackendSshUsername(event.target.value)}
                                 placeholder="julius"
                                 disabled={isAddingSavedBackend}
                                 spellCheck={false}
@@ -2822,9 +2467,7 @@ export function ConnectionsSettings() {
                               </span>
                               <Input
                                 value={savedBackendSshPort}
-                                onChange={(event) =>
-                                  setSavedBackendSshPort(event.target.value)
-                                }
+                                onChange={(event) => setSavedBackendSshPort(event.target.value)}
                                 placeholder="22"
                                 inputMode="numeric"
                                 disabled={isAddingSavedBackend}
@@ -2833,9 +2476,9 @@ export function ConnectionsSettings() {
                             </label>
                           </div>
                           <span className="block text-[11px] text-muted-foreground">
-                            Uses your existing SSH keys, agent, and config.
-                            Password and keyboard-interactive prompts open
-                            through your system SSH dialog when needed.
+                            Uses your existing SSH keys, agent, and config. Password and
+                            keyboard-interactive prompts open through your system SSH dialog when
+                            needed.
                           </span>
                           <Button
                             variant="outline"
@@ -2844,18 +2487,14 @@ export function ConnectionsSettings() {
                             onClick={() => void handleAddSavedBackend()}
                           >
                             <PlusIcon className="size-3.5" />
-                            {isAddingSavedBackend
-                              ? "Connecting…"
-                              : "Connect SSH host"}
+                            {isAddingSavedBackend ? "Connecting…" : "Connect SSH host"}
                           </Button>
                         </div>
                       </div>
                     </div>
                   )}
                   {savedBackendMode !== "ssh" && savedBackendError ? (
-                    <p className="text-xs text-destructive">
-                      {savedBackendError}
-                    </p>
+                    <p className="text-xs text-destructive">{savedBackendError}</p>
                   ) : null}
                   {savedBackendMode !== "ssh" ? (
                     <Button
@@ -2888,8 +2527,8 @@ export function ConnectionsSettings() {
         {savedEnvironmentIds.length === 0 ? (
           <div className={ITEM_ROW_CLASSNAME}>
             <p className="text-xs text-muted-foreground">
-              No remote environments yet. Click &ldquo;Add environment&rdquo; to
-              pair another environment.
+              No remote environments yet. Click &ldquo;Add environment&rdquo; to pair another
+              environment.
             </p>
           </div>
         ) : null}

From d586b5f593f42af9f71021c543284e614fe3d9e6 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 28 Apr 2026 09:30:19 -0700
Subject: [PATCH 31/74] Handle malformed custom endpoints in pairing flow

- Ignore invalid custom HTTPS endpoint URLs when building desktop exposure
- Reset pairing submission state after backend errors and clarify retry guidance
- Add coverage for malformed endpoint inputs
---
 apps/desktop/src/serverExposure.test.ts       |  1 +
 apps/desktop/src/serverExposure.ts            | 36 +++++++++++--------
 .../components/auth/PairingRouteSurface.tsx   |  3 +-
 3 files changed, 25 insertions(+), 15 deletions(-)

diff --git a/apps/desktop/src/serverExposure.test.ts b/apps/desktop/src/serverExposure.test.ts
index 3c101628e04..d12375e0cbf 100644
--- a/apps/desktop/src/serverExposure.test.ts
+++ b/apps/desktop/src/serverExposure.test.ts
@@ -104,6 +104,7 @@ describe("resolveDesktopCoreAdvertisedEndpoints", () => {
         customHttpsEndpointUrls: [
           "https://desktop.example.ts.net",
           "http://desktop.example.test:3773",
+          "not-a-url",
         ],
       }),
     ).toEqual([
diff --git a/apps/desktop/src/serverExposure.ts b/apps/desktop/src/serverExposure.ts
index 332f34cfeeb..035e2e155ae 100644
--- a/apps/desktop/src/serverExposure.ts
+++ b/apps/desktop/src/serverExposure.ts
@@ -50,7 +50,11 @@ const isUsableLanIpv4Address = (address: string): boolean =>
   !address.startsWith("127.") && !address.startsWith("169.254.");
 
 function isHttpsEndpointUrl(value: string): boolean {
-  return new URL(value).protocol === "https:";
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
 }
 
 export function resolveLanAdvertisedHost(
@@ -160,19 +164,23 @@ export function resolveDesktopCoreAdvertisedEndpoints(
   }
 
   for (const customEndpointUrl of input.customHttpsEndpointUrls ?? []) {
-    endpoints.push(
-      createManualEndpoint({
-        id: `manual:${customEndpointUrl}`,
-        label: "Custom HTTPS",
-        httpBaseUrl: customEndpointUrl,
-        reachability: "public",
-        ...(isHttpsEndpointUrl(customEndpointUrl)
-          ? ({ hostedHttpsCompatibility: "compatible" } as const)
-          : {}),
-        status: "unknown",
-        description: "User-configured HTTPS endpoint for this desktop backend.",
-      }),
-    );
+    try {
+      endpoints.push(
+        createManualEndpoint({
+          id: `manual:${customEndpointUrl}`,
+          label: "Custom HTTPS",
+          httpBaseUrl: customEndpointUrl,
+          reachability: "public",
+          ...(isHttpsEndpointUrl(customEndpointUrl)
+            ? ({ hostedHttpsCompatibility: "compatible" } as const)
+            : {}),
+          status: "unknown",
+          description: "User-configured HTTPS endpoint for this desktop backend.",
+        }),
+      );
+    } catch {
+      // Ignore malformed user-configured endpoints without dropping valid endpoints.
+    }
   }
 
   return endpoints;
diff --git a/apps/web/src/components/auth/PairingRouteSurface.tsx b/apps/web/src/components/auth/PairingRouteSurface.tsx
index d301d6f4105..3e5493771eb 100644
--- a/apps/web/src/components/auth/PairingRouteSurface.tsx
+++ b/apps/web/src/components/auth/PairingRouteSurface.tsx
@@ -196,9 +196,10 @@ export function HostedPairingRouteSurface() {
       setStatus("paired");
       setMessage(`${record.label} is saved in this browser.`);
     } catch (error) {
+      tokenSubmittedRef.current = false;
       setStatus("error");
       setMessage(
-        `${errorMessageFromUnknown(error)} Request a new pairing link before trying again.`,
+        `${errorMessageFromUnknown(error)} If the backend accepted this one-time token, request a new pairing link before retrying.`,
       );
     }
   }, []);

From 713e7effd7b95f9dcd1176c024ada2e8cf50d3fd Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 28 Apr 2026 10:02:51 -0700
Subject: [PATCH 32/74] Update release smoke to include tailscale package

- Relax settings UI text assertions to match reachable URLs
- Add `packages/tailscale/package.json` to release smoke coverage
---
 .../src/components/settings/SettingsPanels.browser.tsx | 10 +++-------
 scripts/release-smoke.ts                               |  1 +
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 241a6cf4255..eaff6939fc0 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -649,9 +649,7 @@ describe("GeneralSettingsPanel observability", () => {
       </AppAtomRegistryProvider>,
     );
 
-    await expect
-      .element(page.getByText("Reachable at http://192.168.86.39:3773/"))
-      .toBeInTheDocument();
+    await expect.element(page.getByText("http://192.168.86.39:3773/")).toBeInTheDocument();
     await expect.element(page.getByRole("button", { name: "+2" })).toBeInTheDocument();
     await expect
       .element(page.getByRole("heading", { name: "Local network", exact: true }))
@@ -664,7 +662,7 @@ describe("GeneralSettingsPanel observability", () => {
       .toBeInTheDocument();
     await expect.element(page.getByText("Default", { exact: true })).toBeInTheDocument();
     await page.getByRole("button", { name: "Set as default" }).first().click();
-    await expect.element(page.getByText("Reachable at http://127.0.0.1:3773/")).toBeInTheDocument();
+    await expect.element(page.getByText("http://127.0.0.1:3773/").first()).toBeInTheDocument();
   });
 
   it("shows diagnostics inside About with a single logs-folder action", async () => {
@@ -917,9 +915,7 @@ describe("GeneralSettingsPanel observability", () => {
     await vi.waitFor(() => {
       expect(desktopBridge.setServerExposureMode).toHaveBeenCalledWith("network-accessible");
     });
-    await expect
-      .element(page.getByText("Reachable at http://192.168.1.44:3773"))
-      .toBeInTheDocument();
+    await expect.element(page.getByText("http://192.168.1.44:3773")).toBeInTheDocument();
   });
 
   it("adds desktop ssh environments from the add-environment dialog", async () => {
diff --git a/scripts/release-smoke.ts b/scripts/release-smoke.ts
index 7aff0a2f655..8260edde7f6 100644
--- a/scripts/release-smoke.ts
+++ b/scripts/release-smoke.ts
@@ -24,6 +24,7 @@ const workspaceFiles = [
   "packages/client-runtime/package.json",
   "packages/contracts/package.json",
   "packages/shared/package.json",
+  "packages/tailscale/package.json",
   "packages/effect-acp/package.json",
   "packages/effect-codex-app-server/package.json",
   "scripts/package.json",

From 83f7489f29f2af7eaddccd74ec88b25ad545b3b4 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 28 Apr 2026 11:34:52 -0700
Subject: [PATCH 33/74] Extract SSH helpers into shared package

- Move SSH parsing and discovery logic into `@t3tools/ssh`
- Reuse the shared helpers from the desktop app and release smoke checks
- Add coverage for host discovery, parsing, and package spec resolution
---
 apps/desktop/package.json          |   1 +
 apps/desktop/src/sshEnvironment.ts | 325 ++--------------------------
 bun.lock                           |  18 ++
 packages/ssh/package.json          |  28 +++
 packages/ssh/src/index.ts          |   1 +
 packages/ssh/src/ssh.test.ts       | 233 ++++++++++++++++++++
 packages/ssh/src/ssh.ts            | 335 +++++++++++++++++++++++++++++
 packages/ssh/tsconfig.json         |  17 ++
 scripts/release-smoke.ts           |   1 +
 9 files changed, 654 insertions(+), 305 deletions(-)
 create mode 100644 packages/ssh/package.json
 create mode 100644 packages/ssh/src/index.ts
 create mode 100644 packages/ssh/src/ssh.test.ts
 create mode 100644 packages/ssh/src/ssh.ts
 create mode 100644 packages/ssh/tsconfig.json

diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 0e2aadaa00b..9e4e5eec28c 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -24,6 +24,7 @@
     "@t3tools/client-runtime": "workspace:*",
     "@t3tools/contracts": "workspace:*",
     "@t3tools/shared": "workspace:*",
+    "@t3tools/ssh": "workspace:*",
     "@t3tools/tailscale": "workspace:*",
     "@types/node": "catalog:",
     "effect-acp": "workspace:*",
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index eb57b8b37e2..7c6fc68f9a8 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -13,18 +13,34 @@ import type {
   DesktopSshEnvironmentBootstrap,
   DesktopSshEnvironmentTarget,
   DesktopSshPasswordPromptRequest,
-  DesktopUpdateChannel,
   ExecutionEnvironmentDescriptor,
 } from "@t3tools/contracts";
+import {
+  DEFAULT_REMOTE_PORT,
+  baseSshArgs,
+  buildSshHostSpec,
+  collectSshConfigAliasesFromFile,
+  discoverSshHosts,
+  getLastNonEmptyOutputLine,
+  isSshAuthFailure,
+  normalizeSshErrorMessage,
+  parseKnownHostsHostnames,
+  parseSshResolveOutput,
+  remoteStateKey,
+  resolveRemoteT3CliPackageSpec,
+  resolveSshConfigIncludePattern,
+  targetConnectionKey,
+} from "@t3tools/ssh";
+import { Effect } from "effect";
 
 import { waitForHttpReady } from "./backendReadiness.ts";
 
-const DEFAULT_REMOTE_PORT = 3773;
+export { resolveRemoteT3CliPackageSpec };
+
 const REMOTE_PORT_SCAN_WINDOW = 200;
 const SSH_ASKPASS_DIR_NAME = "t3code-ssh-askpass";
 const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
 const SSH_READY_TIMEOUT_MS = 20_000;
-const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
 
 const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
 const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
@@ -80,199 +96,6 @@ interface DesktopSshEnvironmentManagerOptions {
   readonly resolveCliPackageSpec?: () => string;
 }
 
-const NO_HOSTS = [] as const;
-
-function stripInlineComment(line: string): string {
-  const hashIndex = line.indexOf("#");
-  return (hashIndex >= 0 ? line.slice(0, hashIndex) : line).trim();
-}
-
-function splitDirectiveArgs(value: string): ReadonlyArray<string> {
-  return value
-    .trim()
-    .split(/\s+/u)
-    .map((entry) => entry.trim())
-    .filter((entry) => entry.length > 0);
-}
-
-function expandHomePath(input: string, homeDir: string = OS.homedir()): string {
-  return input.replace(/^~(?=$|\/|\\)/u, homeDir);
-}
-
-function resolveSshConfigIncludePattern(
-  includePattern: string,
-  _directory: string,
-  homeDir: string = OS.homedir(),
-): string {
-  const expandedPattern = expandHomePath(includePattern, homeDir);
-  return Path.isAbsolute(expandedPattern)
-    ? expandedPattern
-    : Path.resolve(Path.join(homeDir, ".ssh"), expandedPattern);
-}
-
-function hasSshPattern(value: string): boolean {
-  return value.includes("*") || value.includes("?") || value.startsWith("!");
-}
-
-function escapeRegex(value: string): string {
-  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
-}
-
-function globToRegExp(pattern: string): RegExp {
-  return new RegExp(
-    `^${escapeRegex(pattern).replace(/\\\*/gu, ".*").replace(/\\\?/gu, ".")}$`,
-    "u",
-  );
-}
-
-function expandGlob(pattern: string): ReadonlyArray<string> {
-  if (!pattern.includes("*") && !pattern.includes("?")) {
-    return FS.existsSync(pattern) ? [pattern] : NO_HOSTS;
-  }
-
-  const directory = Path.dirname(pattern);
-  const basePattern = Path.basename(pattern);
-  if (!FS.existsSync(directory)) {
-    return NO_HOSTS;
-  }
-
-  const matcher = globToRegExp(basePattern);
-  return FS.readdirSync(directory)
-    .filter((entry) => matcher.test(entry))
-    .map((entry) => Path.join(directory, entry))
-    .filter((entry) => FS.existsSync(entry))
-    .toSorted((left, right) => left.localeCompare(right));
-}
-
-function collectSshConfigAliasesFromFile(
-  filePath: string,
-  visited = new Set<string>(),
-  homeDir: string = OS.homedir(),
-): ReadonlyArray<string> {
-  const resolvedPath = Path.resolve(filePath);
-  if (visited.has(resolvedPath) || !FS.existsSync(resolvedPath)) {
-    return NO_HOSTS;
-  }
-  visited.add(resolvedPath);
-
-  const aliases = new Set<string>();
-  const directory = Path.dirname(resolvedPath);
-  const raw = FS.readFileSync(resolvedPath, "utf8");
-
-  for (const line of raw.split(/\r?\n/u)) {
-    const stripped = stripInlineComment(line);
-    if (stripped.length === 0) {
-      continue;
-    }
-
-    const [directive = "", ...rawArgs] = splitDirectiveArgs(stripped);
-    const normalizedDirective = directive.toLowerCase();
-    if (normalizedDirective === "include") {
-      for (const includePattern of rawArgs) {
-        const resolvedPattern = resolveSshConfigIncludePattern(includePattern, directory, homeDir);
-        for (const includedPath of expandGlob(resolvedPattern)) {
-          for (const alias of collectSshConfigAliasesFromFile(includedPath, visited, homeDir)) {
-            aliases.add(alias);
-          }
-        }
-      }
-      continue;
-    }
-
-    if (normalizedDirective !== "host") {
-      continue;
-    }
-
-    for (const alias of rawArgs) {
-      if (alias.length === 0 || hasSshPattern(alias)) {
-        continue;
-      }
-      aliases.add(alias);
-    }
-  }
-
-  return [...aliases].toSorted((left, right) => left.localeCompare(right));
-}
-
-function normalizeKnownHostsHostname(rawHost: string): string {
-  const bracketMatch = /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost);
-  if (bracketMatch?.[1]) {
-    return bracketMatch[1];
-  }
-
-  if (!rawHost.includes(":")) {
-    return rawHost;
-  }
-
-  const firstColonIndex = rawHost.indexOf(":");
-  const lastColonIndex = rawHost.lastIndexOf(":");
-  return firstColonIndex === lastColonIndex ? rawHost.slice(0, lastColonIndex) : rawHost;
-}
-
-function parseKnownHostsHostnames(raw: string): ReadonlyArray<string> {
-  const hostnames = new Set<string>();
-
-  for (const line of raw.split(/\r?\n/u)) {
-    const trimmed = line.trim();
-    if (trimmed.length === 0 || trimmed.startsWith("#")) {
-      continue;
-    }
-
-    const withoutMarker = trimmed.startsWith("@")
-      ? trimmed.split(/\s+/u).slice(1).join(" ")
-      : trimmed;
-    const [hostField = ""] = withoutMarker.split(/\s+/u);
-    if (hostField.length === 0 || hostField.startsWith("|")) {
-      continue;
-    }
-
-    for (const rawHost of hostField.split(",")) {
-      const host = normalizeKnownHostsHostname(rawHost).trim();
-      if (host.length === 0 || hasSshPattern(host)) {
-        continue;
-      }
-      hostnames.add(host);
-    }
-  }
-
-  return [...hostnames].toSorted((left, right) => left.localeCompare(right));
-}
-
-function readKnownHostsHostnames(filePath: string): ReadonlyArray<string> {
-  if (!FS.existsSync(filePath)) {
-    return NO_HOSTS;
-  }
-
-  return parseKnownHostsHostnames(FS.readFileSync(filePath, "utf8"));
-}
-
-function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
-  const values = new Map<string, string>();
-  for (const line of stdout.split(/\r?\n/u)) {
-    const trimmed = line.trim();
-    if (trimmed.length === 0) {
-      continue;
-    }
-    const [key, ...rest] = trimmed.split(/\s+/u);
-    if (!key || rest.length === 0 || values.has(key)) {
-      continue;
-    }
-    values.set(key, rest.join(" ").trim());
-  }
-
-  const hostname = values.get("hostname")?.trim() || alias;
-  const username = values.get("user")?.trim() || null;
-  const rawPort = values.get("port")?.trim() ?? "";
-  const parsedPort = Number.parseInt(rawPort, 10);
-
-  return {
-    alias,
-    hostname,
-    username,
-    port: Number.isInteger(parsedPort) ? parsedPort : null,
-  };
-}
-
 async function findAvailableLocalPort(): Promise<number> {
   return await new Promise<number>((resolve, reject) => {
     const server = Net.createServer();
@@ -296,22 +119,6 @@ async function findAvailableLocalPort(): Promise<number> {
   });
 }
 
-function targetConnectionKey(target: DesktopSshEnvironmentTarget): string {
-  return `${target.alias}\u0000${target.hostname}\u0000${target.username ?? ""}\u0000${target.port ?? ""}`;
-}
-
-function remoteStateKey(target: DesktopSshEnvironmentTarget): string {
-  return Crypto.createHash("sha256").update(targetConnectionKey(target)).digest("hex").slice(0, 16);
-}
-
-function buildSshHostSpec(target: DesktopSshEnvironmentTarget): string {
-  const destination = target.alias.trim() || target.hostname.trim();
-  if (destination.length === 0) {
-    throw new Error("SSH target is missing its alias/hostname.");
-  }
-  return target.username ? `${target.username}@${destination}` : destination;
-}
-
 function getDefaultSshAskpassDirectory(): string {
   return Path.join(OS.tmpdir(), SSH_ASKPASS_DIR_NAME);
 }
@@ -450,36 +257,6 @@ function buildSshChildEnvironment(input?: {
   };
 }
 
-function baseSshArgs(
-  target: DesktopSshEnvironmentTarget,
-  input?: { readonly batchMode?: "yes" | "no" },
-): string[] {
-  return [
-    "-o",
-    `BatchMode=${input?.batchMode ?? "no"}`,
-    "-o",
-    "ConnectTimeout=10",
-    ...(target.port !== null ? ["-p", String(target.port)] : []),
-  ];
-}
-
-function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
-  const cleaned = stderr.trim();
-  return cleaned.length > 0 ? cleaned : fallbackMessage;
-}
-
-function isSshAuthFailure(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error);
-  const normalized = message.toLowerCase();
-  return (
-    /permission denied \((?:publickey|password|keyboard-interactive|hostbased|gssapi-with-mic)[^)]*\)/u.test(
-      normalized,
-    ) ||
-    /authentication failed/u.test(normalized) ||
-    /too many authentication failures/u.test(normalized)
-  );
-}
-
 async function runSshCommand(
   target: DesktopSshEnvironmentTarget,
   input?: {
@@ -596,33 +373,6 @@ function buildRemoteLaunchScript(input?: { readonly packageSpec?: string }): str
   });
 }
 
-function getLastNonEmptyOutputLine(stdout: string): string | null {
-  return (
-    stdout
-      .trim()
-      .split(/\r?\n/u)
-      .map((entry) => entry.trim())
-      .findLast((entry) => entry.length > 0) ?? null
-  );
-}
-
-export function resolveRemoteT3CliPackageSpec(input: {
-  readonly appVersion: string;
-  readonly updateChannel: DesktopUpdateChannel;
-  readonly isDevelopment?: boolean;
-}): string {
-  const appVersion = input.appVersion.trim();
-  if (!input.isDevelopment && PUBLISHABLE_T3_VERSION_PATTERN.test(appVersion)) {
-    return `t3@${appVersion}`;
-  }
-
-  if (input.isDevelopment) {
-    return "t3@nightly";
-  }
-
-  return input.updateChannel === "nightly" ? "t3@nightly" : "t3@latest";
-}
-
 function buildRemoteT3RunnerScript(input?: { readonly packageSpec?: string }): string {
   const packageSpec = input?.packageSpec?.trim() || "t3@latest";
   return stripTrailingNewlines(
@@ -769,40 +519,7 @@ async function stopTunnel(entry: SshTunnelEntry): Promise<void> {
 export async function discoverDesktopSshHosts(input?: {
   readonly homeDir?: string;
 }): Promise<readonly DesktopDiscoveredSshHost[]> {
-  const homeDir = input?.homeDir ?? OS.homedir();
-  const sshDirectory = Path.join(homeDir, ".ssh");
-  const configAliases = collectSshConfigAliasesFromFile(
-    Path.join(sshDirectory, "config"),
-    new Set<string>(),
-    homeDir,
-  );
-  const knownHosts = readKnownHostsHostnames(Path.join(sshDirectory, "known_hosts"));
-  const discovered = new Map<string, DesktopDiscoveredSshHost>();
-
-  for (const alias of configAliases) {
-    discovered.set(alias, {
-      alias,
-      hostname: alias,
-      username: null,
-      port: null,
-      source: "ssh-config",
-    });
-  }
-
-  for (const hostname of knownHosts) {
-    if (discovered.has(hostname)) {
-      continue;
-    }
-    discovered.set(hostname, {
-      alias: hostname,
-      hostname,
-      username: null,
-      port: null,
-      source: "known-hosts",
-    });
-  }
-
-  return [...discovered.values()].toSorted((left, right) => left.alias.localeCompare(right.alias));
+  return await Effect.runPromise(discoverSshHosts(input));
 }
 
 export class DesktopSshEnvironmentManager {
@@ -1369,8 +1086,6 @@ export const __test = {
   getLastNonEmptyOutputLine,
   isSshAuthFailure,
   collectSshConfigAliasesFromFile,
-  expandHomePath,
-  normalizeKnownHostsHostname,
   parseKnownHostsHostnames,
   parseSshResolveOutput,
   readSshScriptTemplate,
diff --git a/bun.lock b/bun.lock
index 11a9cb95c33..d5e33cb55f5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -25,6 +25,7 @@
         "@t3tools/client-runtime": "workspace:*",
         "@t3tools/contracts": "workspace:*",
         "@t3tools/shared": "workspace:*",
+        "@t3tools/ssh": "workspace:*",
         "@t3tools/tailscale": "workspace:*",
         "@types/node": "catalog:",
         "effect-acp": "workspace:*",
@@ -202,6 +203,21 @@
         "vitest": "catalog:",
       },
     },
+    "packages/ssh": {
+      "name": "@t3tools/ssh",
+      "version": "0.0.0-alpha.1",
+      "dependencies": {
+        "@t3tools/contracts": "workspace:*",
+        "effect": "catalog:",
+      },
+      "devDependencies": {
+        "@effect/language-service": "catalog:",
+        "@effect/vitest": "catalog:",
+        "@types/node": "catalog:",
+        "typescript": "catalog:",
+        "vitest": "catalog:",
+      },
+    },
     "packages/tailscale": {
       "name": "@t3tools/tailscale",
       "version": "0.0.0-alpha.1",
@@ -760,6 +776,8 @@
 
     "@t3tools/shared": ["@t3tools/shared@workspace:packages/shared"],
 
+    "@t3tools/ssh": ["@t3tools/ssh@workspace:packages/ssh"],
+
     "@t3tools/tailscale": ["@t3tools/tailscale@workspace:packages/tailscale"],
 
     "@t3tools/web": ["@t3tools/web@workspace:apps/web"],
diff --git a/packages/ssh/package.json b/packages/ssh/package.json
new file mode 100644
index 00000000000..b32dd4a3af0
--- /dev/null
+++ b/packages/ssh/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@t3tools/ssh",
+  "version": "0.0.0-alpha.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "prepare": "effect-language-service patch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@t3tools/contracts": "workspace:*",
+    "effect": "catalog:"
+  },
+  "devDependencies": {
+    "@effect/language-service": "catalog:",
+    "@effect/vitest": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
diff --git a/packages/ssh/src/index.ts b/packages/ssh/src/index.ts
new file mode 100644
index 00000000000..c373cc08e84
--- /dev/null
+++ b/packages/ssh/src/index.ts
@@ -0,0 +1 @@
+export * from "./ssh.ts";
diff --git a/packages/ssh/src/ssh.test.ts b/packages/ssh/src/ssh.test.ts
new file mode 100644
index 00000000000..908cc64031b
--- /dev/null
+++ b/packages/ssh/src/ssh.test.ts
@@ -0,0 +1,233 @@
+import * as FS from "node:fs";
+import * as OS from "node:os";
+import * as Path from "node:path";
+
+import { assert, describe, it } from "@effect/vitest";
+import { Effect } from "effect";
+
+import {
+  baseSshArgs,
+  discoverSshHosts,
+  getLastNonEmptyOutputLine,
+  isSshAuthFailure,
+  parseKnownHostsHostnames,
+  parseSshResolveOutput,
+  resolveRemoteT3CliPackageSpec,
+  resolveSshConfigIncludePattern,
+} from "./ssh.ts";
+
+const tempDirectories: string[] = [];
+
+function makeTempHomeDir(): string {
+  const directory = FS.mkdtempSync(Path.join(OS.tmpdir(), "t3-ssh-test-"));
+  tempDirectories.push(directory);
+  return directory;
+}
+
+describe("ssh", () => {
+  it.effect("discovers ssh config hosts across included files", () =>
+    Effect.acquireUseRelease(
+      Effect.sync(makeTempHomeDir),
+      (homeDir) =>
+        Effect.gen(function* () {
+          const sshDir = Path.join(homeDir, ".ssh");
+          FS.mkdirSync(Path.join(sshDir, "config.d"), { recursive: true });
+          FS.writeFileSync(
+            Path.join(sshDir, "config"),
+            ["Host devbox", "  HostName devbox.example.com", "Include config.d/*.conf", ""].join(
+              "\n",
+            ),
+            "utf8",
+          );
+          FS.writeFileSync(
+            Path.join(sshDir, "config.d", "team.conf"),
+            [
+              "Host staging",
+              "  HostName staging.example.com",
+              "Host *",
+              "  ServerAliveInterval 30",
+              "",
+            ].join("\n"),
+            "utf8",
+          );
+          FS.writeFileSync(
+            Path.join(sshDir, "known_hosts"),
+            [
+              "known.example.com ssh-ed25519 AAAA",
+              "|1|hashed|entry ssh-ed25519 AAAA",
+              "[bastion.example.com]:2222 ssh-ed25519 AAAA",
+              "",
+            ].join("\n"),
+            "utf8",
+          );
+
+          const hosts = yield* discoverSshHosts({ homeDir });
+          assert.deepEqual(hosts, [
+            {
+              alias: "bastion.example.com",
+              hostname: "bastion.example.com",
+              username: null,
+              port: null,
+              source: "known-hosts",
+            },
+            {
+              alias: "devbox",
+              hostname: "devbox",
+              username: null,
+              port: null,
+              source: "ssh-config",
+            },
+            {
+              alias: "known.example.com",
+              hostname: "known.example.com",
+              username: null,
+              port: null,
+              source: "known-hosts",
+            },
+            {
+              alias: "staging",
+              hostname: "staging",
+              username: null,
+              port: null,
+              source: "ssh-config",
+            },
+          ]);
+        }),
+      (homeDir) => Effect.sync(() => FS.rmSync(homeDir, { recursive: true, force: true })),
+    ),
+  );
+
+  it.effect("parses known_hosts entries without returning hashed hosts", () =>
+    Effect.sync(() => {
+      assert.deepEqual(
+        parseKnownHostsHostnames(
+          [
+            "github.com ssh-ed25519 AAAA",
+            "gitlab.com,gitlab-alias ssh-ed25519 BBBB",
+            "|1|hashed|entry ssh-ed25519 CCCC",
+            "@cert-authority *.example.com ssh-ed25519 DDDD",
+            "[ssh.example.com]:2200 ssh-ed25519 EEEE",
+            "port.example.com:22 ssh-ed25519 HHHH",
+            "::1 ssh-ed25519 FFFF",
+            "2001:db8::1 ssh-ed25519 GGGG",
+            "",
+          ].join("\n"),
+        ),
+        [
+          "::1",
+          "2001:db8::1",
+          "github.com",
+          "gitlab-alias",
+          "gitlab.com",
+          "port.example.com",
+          "ssh.example.com",
+        ],
+      );
+    }),
+  );
+
+  it.effect("expands tilde-prefixed ssh config include patterns", () =>
+    Effect.sync(() => {
+      assert.equal(
+        resolveSshConfigIncludePattern("~/.ssh/config.d/*.conf", "/tmp/project", "/tmp/home"),
+        "/tmp/home/.ssh/config.d/*.conf",
+      );
+    }),
+  );
+
+  it.effect("parses resolved ssh config output into a target", () =>
+    Effect.sync(() => {
+      assert.deepEqual(
+        parseSshResolveOutput(
+          "devbox",
+          ["hostname devbox.example.com", "user julius", "port 2222", ""].join("\n"),
+        ),
+        {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 2222,
+        },
+      );
+    }),
+  );
+
+  it.effect("builds interactive ssh args without forcing batch mode", () =>
+    Effect.sync(() => {
+      assert.deepEqual(
+        baseSshArgs(
+          {
+            alias: "devbox",
+            hostname: "devbox.example.com",
+            username: "julius",
+            port: 2222,
+          },
+          { batchMode: "no" },
+        ),
+        ["-o", "BatchMode=no", "-o", "ConnectTimeout=10", "-p", "2222"],
+      );
+    }),
+  );
+
+  it.effect("resolves the remote t3 package spec from the desktop release channel", () =>
+    Effect.sync(() => {
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.17",
+          updateChannel: "latest",
+        }),
+        "t3@0.0.17",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.17-nightly.20260415.44",
+          updateChannel: "nightly",
+        }),
+        "t3@0.0.17-nightly.20260415.44",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.0-dev",
+          updateChannel: "nightly",
+          isDevelopment: true,
+        }),
+        "t3@nightly",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.0-dev",
+          updateChannel: "latest",
+          isDevelopment: true,
+        }),
+        "t3@nightly",
+      );
+    }),
+  );
+
+  it.effect("reads the last non-empty ssh output line", () =>
+    Effect.sync(() => {
+      assert.equal(
+        getLastNonEmptyOutputLine(
+          ["Welcome to the host", "", '{"credential":"pairing-token"}', ""].join("\n"),
+        ),
+        '{"credential":"pairing-token"}',
+      );
+    }),
+  );
+
+  it.effect("detects ssh auth failures from common permission denied messages", () =>
+    Effect.sync(() => {
+      assert.equal(
+        isSshAuthFailure(
+          new Error(
+            "julius@100.65.180.100: Permission denied (publickey,password,keyboard-interactive).",
+          ),
+        ),
+        true,
+      );
+      assert.equal(isSshAuthFailure(new Error("Permission denied (publickey).")), true);
+      assert.equal(isSshAuthFailure(new Error("Connection timed out")), false);
+      assert.equal(isSshAuthFailure(new Error("mkdir: Permission denied")), false);
+    }),
+  );
+});
diff --git a/packages/ssh/src/ssh.ts b/packages/ssh/src/ssh.ts
new file mode 100644
index 00000000000..b0f95014bd8
--- /dev/null
+++ b/packages/ssh/src/ssh.ts
@@ -0,0 +1,335 @@
+import * as Crypto from "node:crypto";
+import * as FS from "node:fs";
+import * as OS from "node:os";
+import * as Path from "node:path";
+
+import type {
+  DesktopDiscoveredSshHost,
+  DesktopSshEnvironmentTarget,
+  DesktopUpdateChannel,
+} from "@t3tools/contracts";
+
+import { Data, Effect } from "effect";
+
+export const DEFAULT_REMOTE_PORT = 3773;
+
+const NO_HOSTS = [] as const;
+const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+
+export class SshHostDiscoveryError extends Data.TaggedError("SshHostDiscoveryError")<{
+  readonly message: string;
+  readonly cause: unknown;
+}> {}
+
+function stripInlineComment(line: string): string {
+  const hashIndex = line.indexOf("#");
+  return (hashIndex >= 0 ? line.slice(0, hashIndex) : line).trim();
+}
+
+function splitDirectiveArgs(value: string): ReadonlyArray<string> {
+  return value
+    .trim()
+    .split(/\s+/u)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function expandHomePath(input: string, homeDir: string = OS.homedir()): string {
+  return input.replace(/^~(?=$|\/|\\)/u, homeDir);
+}
+
+export function resolveSshConfigIncludePattern(
+  includePattern: string,
+  _directory: string,
+  homeDir: string = OS.homedir(),
+): string {
+  const expandedPattern = expandHomePath(includePattern, homeDir);
+  return Path.isAbsolute(expandedPattern)
+    ? expandedPattern
+    : Path.resolve(Path.join(homeDir, ".ssh"), expandedPattern);
+}
+
+function hasSshPattern(value: string): boolean {
+  return value.includes("*") || value.includes("?") || value.startsWith("!");
+}
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+function globToRegExp(pattern: string): RegExp {
+  return new RegExp(
+    `^${escapeRegex(pattern).replace(/\\\*/gu, ".*").replace(/\\\?/gu, ".")}$`,
+    "u",
+  );
+}
+
+function expandGlob(pattern: string): ReadonlyArray<string> {
+  if (!pattern.includes("*") && !pattern.includes("?")) {
+    return FS.existsSync(pattern) ? [pattern] : NO_HOSTS;
+  }
+
+  const directory = Path.dirname(pattern);
+  const basePattern = Path.basename(pattern);
+  if (!FS.existsSync(directory)) {
+    return NO_HOSTS;
+  }
+
+  const matcher = globToRegExp(basePattern);
+  return FS.readdirSync(directory)
+    .filter((entry) => matcher.test(entry))
+    .map((entry) => Path.join(directory, entry))
+    .filter((entry) => FS.existsSync(entry))
+    .toSorted((left, right) => left.localeCompare(right));
+}
+
+export function collectSshConfigAliasesFromFile(
+  filePath: string,
+  visited = new Set<string>(),
+  homeDir: string = OS.homedir(),
+): ReadonlyArray<string> {
+  const resolvedPath = Path.resolve(filePath);
+  if (visited.has(resolvedPath) || !FS.existsSync(resolvedPath)) {
+    return NO_HOSTS;
+  }
+  visited.add(resolvedPath);
+
+  const aliases = new Set<string>();
+  const directory = Path.dirname(resolvedPath);
+  const raw = FS.readFileSync(resolvedPath, "utf8");
+
+  for (const line of raw.split(/\r?\n/u)) {
+    const stripped = stripInlineComment(line);
+    if (stripped.length === 0) {
+      continue;
+    }
+
+    const [directive = "", ...rawArgs] = splitDirectiveArgs(stripped);
+    const normalizedDirective = directive.toLowerCase();
+    if (normalizedDirective === "include") {
+      for (const includePattern of rawArgs) {
+        const resolvedPattern = resolveSshConfigIncludePattern(includePattern, directory, homeDir);
+        for (const includedPath of expandGlob(resolvedPattern)) {
+          for (const alias of collectSshConfigAliasesFromFile(includedPath, visited, homeDir)) {
+            aliases.add(alias);
+          }
+        }
+      }
+      continue;
+    }
+
+    if (normalizedDirective !== "host") {
+      continue;
+    }
+
+    for (const alias of rawArgs) {
+      if (alias.length === 0 || hasSshPattern(alias)) {
+        continue;
+      }
+      aliases.add(alias);
+    }
+  }
+
+  return [...aliases].toSorted((left, right) => left.localeCompare(right));
+}
+
+function normalizeKnownHostsHostname(rawHost: string): string {
+  const bracketMatch = /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost);
+  if (bracketMatch?.[1]) {
+    return bracketMatch[1];
+  }
+
+  if (!rawHost.includes(":")) {
+    return rawHost;
+  }
+
+  const firstColonIndex = rawHost.indexOf(":");
+  const lastColonIndex = rawHost.lastIndexOf(":");
+  return firstColonIndex === lastColonIndex ? rawHost.slice(0, lastColonIndex) : rawHost;
+}
+
+export function parseKnownHostsHostnames(raw: string): ReadonlyArray<string> {
+  const hostnames = new Set<string>();
+
+  for (const line of raw.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const withoutMarker = trimmed.startsWith("@")
+      ? trimmed.split(/\s+/u).slice(1).join(" ")
+      : trimmed;
+    const [hostField = ""] = withoutMarker.split(/\s+/u);
+    if (hostField.length === 0 || hostField.startsWith("|")) {
+      continue;
+    }
+
+    for (const rawHost of hostField.split(",")) {
+      const host = normalizeKnownHostsHostname(rawHost).trim();
+      if (host.length === 0 || hasSshPattern(host)) {
+        continue;
+      }
+      hostnames.add(host);
+    }
+  }
+
+  return [...hostnames].toSorted((left, right) => left.localeCompare(right));
+}
+
+function readKnownHostsHostnames(filePath: string): ReadonlyArray<string> {
+  if (!FS.existsSync(filePath)) {
+    return NO_HOSTS;
+  }
+
+  return parseKnownHostsHostnames(FS.readFileSync(filePath, "utf8"));
+}
+
+export function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
+  const values = new Map<string, string>();
+  for (const line of stdout.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    const [key, ...rest] = trimmed.split(/\s+/u);
+    if (!key || rest.length === 0 || values.has(key)) {
+      continue;
+    }
+    values.set(key, rest.join(" ").trim());
+  }
+
+  const hostname = values.get("hostname")?.trim() || alias;
+  const username = values.get("user")?.trim() || null;
+  const rawPort = values.get("port")?.trim() ?? "";
+  const parsedPort = Number.parseInt(rawPort, 10);
+
+  return {
+    alias,
+    hostname,
+    username,
+    port: Number.isInteger(parsedPort) ? parsedPort : null,
+  };
+}
+
+export function targetConnectionKey(target: DesktopSshEnvironmentTarget): string {
+  return `${target.alias}\u0000${target.hostname}\u0000${target.username ?? ""}\u0000${target.port ?? ""}`;
+}
+
+export function remoteStateKey(target: DesktopSshEnvironmentTarget): string {
+  return Crypto.createHash("sha256").update(targetConnectionKey(target)).digest("hex").slice(0, 16);
+}
+
+export function buildSshHostSpec(target: DesktopSshEnvironmentTarget): string {
+  const destination = target.alias.trim() || target.hostname.trim();
+  if (destination.length === 0) {
+    throw new Error("SSH target is missing its alias/hostname.");
+  }
+  return target.username ? `${target.username}@${destination}` : destination;
+}
+
+export function baseSshArgs(
+  target: DesktopSshEnvironmentTarget,
+  input?: { readonly batchMode?: "yes" | "no" },
+): string[] {
+  return [
+    "-o",
+    `BatchMode=${input?.batchMode ?? "no"}`,
+    "-o",
+    "ConnectTimeout=10",
+    ...(target.port !== null ? ["-p", String(target.port)] : []),
+  ];
+}
+
+export function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
+  const cleaned = stderr.trim();
+  return cleaned.length > 0 ? cleaned : fallbackMessage;
+}
+
+export function isSshAuthFailure(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+  return (
+    /permission denied \((?:publickey|password|keyboard-interactive|hostbased|gssapi-with-mic)[^)]*\)/u.test(
+      normalized,
+    ) ||
+    /authentication failed/u.test(normalized) ||
+    /too many authentication failures/u.test(normalized)
+  );
+}
+
+export function getLastNonEmptyOutputLine(stdout: string): string | null {
+  return (
+    stdout
+      .trim()
+      .split(/\r?\n/u)
+      .map((entry) => entry.trim())
+      .findLast((entry) => entry.length > 0) ?? null
+  );
+}
+
+export function resolveRemoteT3CliPackageSpec(input: {
+  readonly appVersion: string;
+  readonly updateChannel: DesktopUpdateChannel;
+  readonly isDevelopment?: boolean;
+}): string {
+  const appVersion = input.appVersion.trim();
+  if (!input.isDevelopment && PUBLISHABLE_T3_VERSION_PATTERN.test(appVersion)) {
+    return `t3@${appVersion}`;
+  }
+
+  if (input.isDevelopment) {
+    return "t3@nightly";
+  }
+
+  return input.updateChannel === "nightly" ? "t3@nightly" : "t3@latest";
+}
+
+export const discoverSshHosts = (input?: {
+  readonly homeDir?: string;
+}): Effect.Effect<readonly DesktopDiscoveredSshHost[], SshHostDiscoveryError> =>
+  Effect.try({
+    try: () => {
+      const homeDir = input?.homeDir ?? OS.homedir();
+      const sshDirectory = Path.join(homeDir, ".ssh");
+      const configAliases = collectSshConfigAliasesFromFile(
+        Path.join(sshDirectory, "config"),
+        new Set<string>(),
+        homeDir,
+      );
+      const knownHosts = readKnownHostsHostnames(Path.join(sshDirectory, "known_hosts"));
+      const discovered = new Map<string, DesktopDiscoveredSshHost>();
+
+      for (const alias of configAliases) {
+        discovered.set(alias, {
+          alias,
+          hostname: alias,
+          username: null,
+          port: null,
+          source: "ssh-config",
+        });
+      }
+
+      for (const hostname of knownHosts) {
+        if (discovered.has(hostname)) {
+          continue;
+        }
+        discovered.set(hostname, {
+          alias: hostname,
+          hostname,
+          username: null,
+          port: null,
+          source: "known-hosts",
+        });
+      }
+
+      return [...discovered.values()].toSorted((left, right) =>
+        left.alias.localeCompare(right.alias),
+      );
+    },
+    catch: (cause) =>
+      new SshHostDiscoveryError({
+        message: "Failed to discover SSH hosts.",
+        cause,
+      }),
+  });
diff --git a/packages/ssh/tsconfig.json b/packages/ssh/tsconfig.json
new file mode 100644
index 00000000000..2f8e6d4df6d
--- /dev/null
+++ b/packages/ssh/tsconfig.json
@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "@effect/language-service",
+        "diagnosticSeverity": {
+          "importFromBarrel": "error",
+          "anyUnknownInErrorContext": "warning",
+          "instanceOfSchema": "warning",
+          "deterministicKeys": "warning"
+        }
+      }
+    ]
+  },
+  "include": ["src"]
+}
diff --git a/scripts/release-smoke.ts b/scripts/release-smoke.ts
index 8260edde7f6..27308134f1a 100644
--- a/scripts/release-smoke.ts
+++ b/scripts/release-smoke.ts
@@ -24,6 +24,7 @@ const workspaceFiles = [
   "packages/client-runtime/package.json",
   "packages/contracts/package.json",
   "packages/shared/package.json",
+  "packages/ssh/package.json",
   "packages/tailscale/package.json",
   "packages/effect-acp/package.json",
   "packages/effect-codex-app-server/package.json",

From 8c487d87ba410a8bccae758bf3a57a7870608572 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 28 Apr 2026 11:54:58 -0700
Subject: [PATCH 34/74] Split SSH helpers into dedicated modules

- Add auth, command, config, and tunnel exports
- Update desktop SSH environment imports
- Add tests for auth and command helpers
---
 apps/desktop/src/sshEnvironment.ts            |  32 ++---
 packages/ssh/package.json                     |  22 +++-
 packages/ssh/src/auth.test.ts                 |  22 ++++
 packages/ssh/src/auth.ts                      |  18 +++
 packages/ssh/src/command.test.ts              |  91 ++++++++++++++
 packages/ssh/src/command.ts                   |  88 +++++++++++++
 .../ssh/src/{ssh.test.ts => config.test.ts}   | 111 +----------------
 packages/ssh/src/{ssh.ts => config.ts}        | 117 +-----------------
 packages/ssh/src/errors.ts                    |   6 +
 packages/ssh/src/index.ts                     |   6 +-
 packages/ssh/src/tunnel.ts                    |   6 +
 11 files changed, 273 insertions(+), 246 deletions(-)
 create mode 100644 packages/ssh/src/auth.test.ts
 create mode 100644 packages/ssh/src/auth.ts
 create mode 100644 packages/ssh/src/command.test.ts
 create mode 100644 packages/ssh/src/command.ts
 rename packages/ssh/src/{ssh.test.ts => config.test.ts} (54%)
 rename packages/ssh/src/{ssh.ts => config.ts} (63%)
 create mode 100644 packages/ssh/src/errors.ts
 create mode 100644 packages/ssh/src/tunnel.ts

diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 7c6fc68f9a8..d3db8654da4 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -15,27 +15,28 @@ import type {
   DesktopSshPasswordPromptRequest,
   ExecutionEnvironmentDescriptor,
 } from "@t3tools/contracts";
+import { isSshAuthFailure, type SshPasswordRequest } from "@t3tools/ssh/auth";
 import {
-  DEFAULT_REMOTE_PORT,
   baseSshArgs,
   buildSshHostSpec,
-  collectSshConfigAliasesFromFile,
-  discoverSshHosts,
   getLastNonEmptyOutputLine,
-  isSshAuthFailure,
-  normalizeSshErrorMessage,
-  parseKnownHostsHostnames,
   parseSshResolveOutput,
   remoteStateKey,
   resolveRemoteT3CliPackageSpec,
-  resolveSshConfigIncludePattern,
   targetConnectionKey,
-} from "@t3tools/ssh";
+} from "@t3tools/ssh/command";
+import {
+  collectSshConfigAliasesFromFile,
+  discoverSshHosts,
+  parseKnownHostsHostnames,
+  resolveSshConfigIncludePattern,
+} from "@t3tools/ssh/config";
+import { DEFAULT_REMOTE_PORT, normalizeSshErrorMessage } from "@t3tools/ssh/tunnel";
 import { Effect } from "effect";
 
 import { waitForHttpReady } from "./backendReadiness.ts";
 
-export { resolveRemoteT3CliPackageSpec };
+export { resolveRemoteT3CliPackageSpec } from "@t3tools/ssh/command";
 
 const REMOTE_PORT_SCAN_WINDOW = 200;
 const SSH_ASKPASS_DIR_NAME = "t3code-ssh-askpass";
@@ -84,15 +85,8 @@ interface SshAuthOptions {
   readonly interactiveAuth?: boolean;
 }
 
-interface DesktopSshPasswordRequest {
-  readonly destination: string;
-  readonly username: string | null;
-  readonly prompt: string;
-  readonly attempt: number;
-}
-
 interface DesktopSshEnvironmentManagerOptions {
-  readonly passwordProvider?: (request: DesktopSshPasswordRequest) => Promise<string | null>;
+  readonly passwordProvider?: (request: SshPasswordRequest) => Promise<string | null>;
   readonly resolveCliPackageSpec?: () => string;
 }
 
@@ -1042,9 +1036,7 @@ export class DesktopSshEnvironmentBridge {
     await this.manager.dispose();
   }
 
-  private async requestPasswordFromRenderer(
-    input: DesktopSshPasswordRequest,
-  ): Promise<string | null> {
+  private async requestPasswordFromRenderer(input: SshPasswordRequest): Promise<string | null> {
     const window = this.options.getMainWindow();
     if (!window || window.isDestroyed()) {
       throw new Error("T3 Code window is not available for SSH authentication.");
diff --git a/packages/ssh/package.json b/packages/ssh/package.json
index b32dd4a3af0..9f1984294f0 100644
--- a/packages/ssh/package.json
+++ b/packages/ssh/package.json
@@ -4,9 +4,25 @@
   "private": true,
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+    "./auth": {
+      "types": "./src/auth.ts",
+      "import": "./src/auth.ts"
+    },
+    "./command": {
+      "types": "./src/command.ts",
+      "import": "./src/command.ts"
+    },
+    "./config": {
+      "types": "./src/config.ts",
+      "import": "./src/config.ts"
+    },
+    "./errors": {
+      "types": "./src/errors.ts",
+      "import": "./src/errors.ts"
+    },
+    "./tunnel": {
+      "types": "./src/tunnel.ts",
+      "import": "./src/tunnel.ts"
     }
   },
   "scripts": {
diff --git a/packages/ssh/src/auth.test.ts b/packages/ssh/src/auth.test.ts
new file mode 100644
index 00000000000..a72c5ef1fc0
--- /dev/null
+++ b/packages/ssh/src/auth.test.ts
@@ -0,0 +1,22 @@
+import { assert, describe, it } from "@effect/vitest";
+import { Effect } from "effect";
+
+import { isSshAuthFailure } from "./auth.ts";
+
+describe("ssh auth", () => {
+  it.effect("detects ssh auth failures from common permission denied messages", () =>
+    Effect.sync(() => {
+      assert.equal(
+        isSshAuthFailure(
+          new Error(
+            "julius@100.65.180.100: Permission denied (publickey,password,keyboard-interactive).",
+          ),
+        ),
+        true,
+      );
+      assert.equal(isSshAuthFailure(new Error("Permission denied (publickey).")), true);
+      assert.equal(isSshAuthFailure(new Error("Connection timed out")), false);
+      assert.equal(isSshAuthFailure(new Error("mkdir: Permission denied")), false);
+    }),
+  );
+});
diff --git a/packages/ssh/src/auth.ts b/packages/ssh/src/auth.ts
new file mode 100644
index 00000000000..a961b5b1189
--- /dev/null
+++ b/packages/ssh/src/auth.ts
@@ -0,0 +1,18 @@
+export interface SshPasswordRequest {
+  readonly destination: string;
+  readonly username: string | null;
+  readonly prompt: string;
+  readonly attempt: number;
+}
+
+export function isSshAuthFailure(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  const normalized = message.toLowerCase();
+  return (
+    /permission denied \((?:publickey|password|keyboard-interactive|hostbased|gssapi-with-mic)[^)]*\)/u.test(
+      normalized,
+    ) ||
+    /authentication failed/u.test(normalized) ||
+    /too many authentication failures/u.test(normalized)
+  );
+}
diff --git a/packages/ssh/src/command.test.ts b/packages/ssh/src/command.test.ts
new file mode 100644
index 00000000000..1532cc7d3b0
--- /dev/null
+++ b/packages/ssh/src/command.test.ts
@@ -0,0 +1,91 @@
+import { assert, describe, it } from "@effect/vitest";
+import { Effect } from "effect";
+
+import {
+  baseSshArgs,
+  getLastNonEmptyOutputLine,
+  parseSshResolveOutput,
+  resolveRemoteT3CliPackageSpec,
+} from "./command.ts";
+
+describe("ssh command", () => {
+  it.effect("parses resolved ssh config output into a target", () =>
+    Effect.sync(() => {
+      assert.deepEqual(
+        parseSshResolveOutput(
+          "devbox",
+          ["hostname devbox.example.com", "user julius", "port 2222", ""].join("\n"),
+        ),
+        {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 2222,
+        },
+      );
+    }),
+  );
+
+  it.effect("builds interactive ssh args without forcing batch mode", () =>
+    Effect.sync(() => {
+      assert.deepEqual(
+        baseSshArgs(
+          {
+            alias: "devbox",
+            hostname: "devbox.example.com",
+            username: "julius",
+            port: 2222,
+          },
+          { batchMode: "no" },
+        ),
+        ["-o", "BatchMode=no", "-o", "ConnectTimeout=10", "-p", "2222"],
+      );
+    }),
+  );
+
+  it.effect("resolves the remote t3 package spec from the desktop release channel", () =>
+    Effect.sync(() => {
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.17",
+          updateChannel: "latest",
+        }),
+        "t3@0.0.17",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.17-nightly.20260415.44",
+          updateChannel: "nightly",
+        }),
+        "t3@0.0.17-nightly.20260415.44",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.0-dev",
+          updateChannel: "nightly",
+          isDevelopment: true,
+        }),
+        "t3@nightly",
+      );
+      assert.equal(
+        resolveRemoteT3CliPackageSpec({
+          appVersion: "0.0.0-dev",
+          updateChannel: "latest",
+          isDevelopment: true,
+        }),
+        "t3@nightly",
+      );
+    }),
+  );
+
+  it.effect("reads the last non-empty ssh output line", () =>
+    Effect.sync(() => {
+      assert.equal(
+        getLastNonEmptyOutputLine(
+          ["Welcome to the host", "", '{"credential":"pairing-token"}', ""].join("\n"),
+        ),
+        '{"credential":"pairing-token"}',
+      );
+    }),
+  );
+});
diff --git a/packages/ssh/src/command.ts b/packages/ssh/src/command.ts
new file mode 100644
index 00000000000..c73195fcbac
--- /dev/null
+++ b/packages/ssh/src/command.ts
@@ -0,0 +1,88 @@
+import * as Crypto from "node:crypto";
+
+import type { DesktopSshEnvironmentTarget, DesktopUpdateChannel } from "@t3tools/contracts";
+
+const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+
+export function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
+  const values = new Map<string, string>();
+  for (const line of stdout.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) {
+      continue;
+    }
+    const [key, ...rest] = trimmed.split(/\s+/u);
+    if (!key || rest.length === 0 || values.has(key)) {
+      continue;
+    }
+    values.set(key, rest.join(" ").trim());
+  }
+
+  const hostname = values.get("hostname")?.trim() || alias;
+  const username = values.get("user")?.trim() || null;
+  const rawPort = values.get("port")?.trim() ?? "";
+  const parsedPort = Number.parseInt(rawPort, 10);
+
+  return {
+    alias,
+    hostname,
+    username,
+    port: Number.isInteger(parsedPort) ? parsedPort : null,
+  };
+}
+
+export function targetConnectionKey(target: DesktopSshEnvironmentTarget): string {
+  return `${target.alias}\u0000${target.hostname}\u0000${target.username ?? ""}\u0000${target.port ?? ""}`;
+}
+
+export function remoteStateKey(target: DesktopSshEnvironmentTarget): string {
+  return Crypto.createHash("sha256").update(targetConnectionKey(target)).digest("hex").slice(0, 16);
+}
+
+export function buildSshHostSpec(target: DesktopSshEnvironmentTarget): string {
+  const destination = target.alias.trim() || target.hostname.trim();
+  if (destination.length === 0) {
+    throw new Error("SSH target is missing its alias/hostname.");
+  }
+  return target.username ? `${target.username}@${destination}` : destination;
+}
+
+export function baseSshArgs(
+  target: DesktopSshEnvironmentTarget,
+  input?: { readonly batchMode?: "yes" | "no" },
+): string[] {
+  return [
+    "-o",
+    `BatchMode=${input?.batchMode ?? "no"}`,
+    "-o",
+    "ConnectTimeout=10",
+    ...(target.port !== null ? ["-p", String(target.port)] : []),
+  ];
+}
+
+export function getLastNonEmptyOutputLine(stdout: string): string | null {
+  return (
+    stdout
+      .trim()
+      .split(/\r?\n/u)
+      .map((entry) => entry.trim())
+      .findLast((entry) => entry.length > 0) ?? null
+  );
+}
+
+export function resolveRemoteT3CliPackageSpec(input: {
+  readonly appVersion: string;
+  readonly updateChannel: DesktopUpdateChannel;
+  readonly isDevelopment?: boolean;
+}): string {
+  const appVersion = input.appVersion.trim();
+  if (!input.isDevelopment && PUBLISHABLE_T3_VERSION_PATTERN.test(appVersion)) {
+    return `t3@${appVersion}`;
+  }
+
+  if (input.isDevelopment) {
+    return "t3@nightly";
+  }
+
+  return input.updateChannel === "nightly" ? "t3@nightly" : "t3@latest";
+}
diff --git a/packages/ssh/src/ssh.test.ts b/packages/ssh/src/config.test.ts
similarity index 54%
rename from packages/ssh/src/ssh.test.ts
rename to packages/ssh/src/config.test.ts
index 908cc64031b..184d9fb0415 100644
--- a/packages/ssh/src/ssh.test.ts
+++ b/packages/ssh/src/config.test.ts
@@ -6,25 +6,16 @@ import { assert, describe, it } from "@effect/vitest";
 import { Effect } from "effect";
 
 import {
-  baseSshArgs,
   discoverSshHosts,
-  getLastNonEmptyOutputLine,
-  isSshAuthFailure,
   parseKnownHostsHostnames,
-  parseSshResolveOutput,
-  resolveRemoteT3CliPackageSpec,
   resolveSshConfigIncludePattern,
-} from "./ssh.ts";
-
-const tempDirectories: string[] = [];
+} from "./config.ts";
 
 function makeTempHomeDir(): string {
-  const directory = FS.mkdtempSync(Path.join(OS.tmpdir(), "t3-ssh-test-"));
-  tempDirectories.push(directory);
-  return directory;
+  return FS.mkdtempSync(Path.join(OS.tmpdir(), "t3-ssh-test-"));
 }
 
-describe("ssh", () => {
+describe("ssh config", () => {
   it.effect("discovers ssh config hosts across included files", () =>
     Effect.acquireUseRelease(
       Effect.sync(makeTempHomeDir),
@@ -134,100 +125,4 @@ describe("ssh", () => {
       );
     }),
   );
-
-  it.effect("parses resolved ssh config output into a target", () =>
-    Effect.sync(() => {
-      assert.deepEqual(
-        parseSshResolveOutput(
-          "devbox",
-          ["hostname devbox.example.com", "user julius", "port 2222", ""].join("\n"),
-        ),
-        {
-          alias: "devbox",
-          hostname: "devbox.example.com",
-          username: "julius",
-          port: 2222,
-        },
-      );
-    }),
-  );
-
-  it.effect("builds interactive ssh args without forcing batch mode", () =>
-    Effect.sync(() => {
-      assert.deepEqual(
-        baseSshArgs(
-          {
-            alias: "devbox",
-            hostname: "devbox.example.com",
-            username: "julius",
-            port: 2222,
-          },
-          { batchMode: "no" },
-        ),
-        ["-o", "BatchMode=no", "-o", "ConnectTimeout=10", "-p", "2222"],
-      );
-    }),
-  );
-
-  it.effect("resolves the remote t3 package spec from the desktop release channel", () =>
-    Effect.sync(() => {
-      assert.equal(
-        resolveRemoteT3CliPackageSpec({
-          appVersion: "0.0.17",
-          updateChannel: "latest",
-        }),
-        "t3@0.0.17",
-      );
-      assert.equal(
-        resolveRemoteT3CliPackageSpec({
-          appVersion: "0.0.17-nightly.20260415.44",
-          updateChannel: "nightly",
-        }),
-        "t3@0.0.17-nightly.20260415.44",
-      );
-      assert.equal(
-        resolveRemoteT3CliPackageSpec({
-          appVersion: "0.0.0-dev",
-          updateChannel: "nightly",
-          isDevelopment: true,
-        }),
-        "t3@nightly",
-      );
-      assert.equal(
-        resolveRemoteT3CliPackageSpec({
-          appVersion: "0.0.0-dev",
-          updateChannel: "latest",
-          isDevelopment: true,
-        }),
-        "t3@nightly",
-      );
-    }),
-  );
-
-  it.effect("reads the last non-empty ssh output line", () =>
-    Effect.sync(() => {
-      assert.equal(
-        getLastNonEmptyOutputLine(
-          ["Welcome to the host", "", '{"credential":"pairing-token"}', ""].join("\n"),
-        ),
-        '{"credential":"pairing-token"}',
-      );
-    }),
-  );
-
-  it.effect("detects ssh auth failures from common permission denied messages", () =>
-    Effect.sync(() => {
-      assert.equal(
-        isSshAuthFailure(
-          new Error(
-            "julius@100.65.180.100: Permission denied (publickey,password,keyboard-interactive).",
-          ),
-        ),
-        true,
-      );
-      assert.equal(isSshAuthFailure(new Error("Permission denied (publickey).")), true);
-      assert.equal(isSshAuthFailure(new Error("Connection timed out")), false);
-      assert.equal(isSshAuthFailure(new Error("mkdir: Permission denied")), false);
-    }),
-  );
 });
diff --git a/packages/ssh/src/ssh.ts b/packages/ssh/src/config.ts
similarity index 63%
rename from packages/ssh/src/ssh.ts
rename to packages/ssh/src/config.ts
index b0f95014bd8..17291f481d1 100644
--- a/packages/ssh/src/ssh.ts
+++ b/packages/ssh/src/config.ts
@@ -1,25 +1,14 @@
-import * as Crypto from "node:crypto";
 import * as FS from "node:fs";
 import * as OS from "node:os";
 import * as Path from "node:path";
 
-import type {
-  DesktopDiscoveredSshHost,
-  DesktopSshEnvironmentTarget,
-  DesktopUpdateChannel,
-} from "@t3tools/contracts";
+import type { DesktopDiscoveredSshHost } from "@t3tools/contracts";
 
-import { Data, Effect } from "effect";
+import { Effect } from "effect";
 
-export const DEFAULT_REMOTE_PORT = 3773;
+import { SshHostDiscoveryError } from "./errors.ts";
 
 const NO_HOSTS = [] as const;
-const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
-
-export class SshHostDiscoveryError extends Data.TaggedError("SshHostDiscoveryError")<{
-  readonly message: string;
-  readonly cause: unknown;
-}> {}
 
 function stripInlineComment(line: string): string {
   const hashIndex = line.indexOf("#");
@@ -185,106 +174,6 @@ function readKnownHostsHostnames(filePath: string): ReadonlyArray<string> {
   return parseKnownHostsHostnames(FS.readFileSync(filePath, "utf8"));
 }
 
-export function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
-  const values = new Map<string, string>();
-  for (const line of stdout.split(/\r?\n/u)) {
-    const trimmed = line.trim();
-    if (trimmed.length === 0) {
-      continue;
-    }
-    const [key, ...rest] = trimmed.split(/\s+/u);
-    if (!key || rest.length === 0 || values.has(key)) {
-      continue;
-    }
-    values.set(key, rest.join(" ").trim());
-  }
-
-  const hostname = values.get("hostname")?.trim() || alias;
-  const username = values.get("user")?.trim() || null;
-  const rawPort = values.get("port")?.trim() ?? "";
-  const parsedPort = Number.parseInt(rawPort, 10);
-
-  return {
-    alias,
-    hostname,
-    username,
-    port: Number.isInteger(parsedPort) ? parsedPort : null,
-  };
-}
-
-export function targetConnectionKey(target: DesktopSshEnvironmentTarget): string {
-  return `${target.alias}\u0000${target.hostname}\u0000${target.username ?? ""}\u0000${target.port ?? ""}`;
-}
-
-export function remoteStateKey(target: DesktopSshEnvironmentTarget): string {
-  return Crypto.createHash("sha256").update(targetConnectionKey(target)).digest("hex").slice(0, 16);
-}
-
-export function buildSshHostSpec(target: DesktopSshEnvironmentTarget): string {
-  const destination = target.alias.trim() || target.hostname.trim();
-  if (destination.length === 0) {
-    throw new Error("SSH target is missing its alias/hostname.");
-  }
-  return target.username ? `${target.username}@${destination}` : destination;
-}
-
-export function baseSshArgs(
-  target: DesktopSshEnvironmentTarget,
-  input?: { readonly batchMode?: "yes" | "no" },
-): string[] {
-  return [
-    "-o",
-    `BatchMode=${input?.batchMode ?? "no"}`,
-    "-o",
-    "ConnectTimeout=10",
-    ...(target.port !== null ? ["-p", String(target.port)] : []),
-  ];
-}
-
-export function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
-  const cleaned = stderr.trim();
-  return cleaned.length > 0 ? cleaned : fallbackMessage;
-}
-
-export function isSshAuthFailure(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error);
-  const normalized = message.toLowerCase();
-  return (
-    /permission denied \((?:publickey|password|keyboard-interactive|hostbased|gssapi-with-mic)[^)]*\)/u.test(
-      normalized,
-    ) ||
-    /authentication failed/u.test(normalized) ||
-    /too many authentication failures/u.test(normalized)
-  );
-}
-
-export function getLastNonEmptyOutputLine(stdout: string): string | null {
-  return (
-    stdout
-      .trim()
-      .split(/\r?\n/u)
-      .map((entry) => entry.trim())
-      .findLast((entry) => entry.length > 0) ?? null
-  );
-}
-
-export function resolveRemoteT3CliPackageSpec(input: {
-  readonly appVersion: string;
-  readonly updateChannel: DesktopUpdateChannel;
-  readonly isDevelopment?: boolean;
-}): string {
-  const appVersion = input.appVersion.trim();
-  if (!input.isDevelopment && PUBLISHABLE_T3_VERSION_PATTERN.test(appVersion)) {
-    return `t3@${appVersion}`;
-  }
-
-  if (input.isDevelopment) {
-    return "t3@nightly";
-  }
-
-  return input.updateChannel === "nightly" ? "t3@nightly" : "t3@latest";
-}
-
 export const discoverSshHosts = (input?: {
   readonly homeDir?: string;
 }): Effect.Effect<readonly DesktopDiscoveredSshHost[], SshHostDiscoveryError> =>
diff --git a/packages/ssh/src/errors.ts b/packages/ssh/src/errors.ts
new file mode 100644
index 00000000000..0eab86f7104
--- /dev/null
+++ b/packages/ssh/src/errors.ts
@@ -0,0 +1,6 @@
+import { Data } from "effect";
+
+export class SshHostDiscoveryError extends Data.TaggedError("SshHostDiscoveryError")<{
+  readonly message: string;
+  readonly cause: unknown;
+}> {}
diff --git a/packages/ssh/src/index.ts b/packages/ssh/src/index.ts
index c373cc08e84..9b208f0ddaa 100644
--- a/packages/ssh/src/index.ts
+++ b/packages/ssh/src/index.ts
@@ -1 +1,5 @@
-export * from "./ssh.ts";
+export * from "./auth.ts";
+export * from "./command.ts";
+export * from "./config.ts";
+export * from "./errors.ts";
+export * from "./tunnel.ts";
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
new file mode 100644
index 00000000000..81d8cbc8add
--- /dev/null
+++ b/packages/ssh/src/tunnel.ts
@@ -0,0 +1,6 @@
+export const DEFAULT_REMOTE_PORT = 3773;
+
+export function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
+  const cleaned = stderr.trim();
+  return cleaned.length > 0 ? cleaned : fallbackMessage;
+}

From 4a954ddc81b32df2cc88b671ded27596a723f174 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 28 Apr 2026 13:59:42 -0700
Subject: [PATCH 35/74] Gate pair route fallback to hosted static app

- Avoid showing the hosted pairing flow outside the static app
- Keep the existing error boundary behavior for local builds
---
 apps/web/src/routes/__root.tsx | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 7c38d77853a..d4ba56f3c51 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -94,6 +94,9 @@ export const Route = createRootRouteWithContext<{
       if (location.pathname === "/pair") {
         throw error;
       }
+      if (!isHostedStaticApp(new URL(window.location.href))) {
+        throw error;
+      }
 
       await waitForSavedEnvironmentRegistryHydration();
       return {

From 6f0810bb7a8a4dcc0fee504f94160e78bba394cb Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 28 Apr 2026 14:07:09 -0700
Subject: [PATCH 36/74] Disable Tailscale Serve on server shutdown

- Factor Tailscale command execution into a reusable helper
- Add tests for `tailscale serve off`
- Ensure hosted pairing UI cleans up Tailscale Serve after startup
---
 apps/server/src/server.ts                | 55 ++++++++++++++-------
 packages/tailscale/src/tailscale.test.ts | 11 +++++
 packages/tailscale/src/tailscale.ts      | 63 +++++++++++++++++-------
 3 files changed, 92 insertions(+), 37 deletions(-)

diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 2b49113172e..9925791f865 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -81,7 +81,7 @@ import {
   orchestrationSnapshotRouteLayer,
 } from "./orchestration/http.ts";
 import { NetService } from "@t3tools/shared/Net";
-import { ensureTailscaleServe } from "@t3tools/tailscale";
+import { disableTailscaleServe, ensureTailscaleServe } from "@t3tools/tailscale";
 
 const PtyAdapterLive = Layer.unwrap(
   Effect.gen(function* () {
@@ -329,24 +329,43 @@ export const makeServerLayer = Layer.unwrap(
     );
     const tailscaleServeLayer = config.tailscaleServeEnabled
       ? Layer.effectDiscard(
-          ensureTailscaleServe({
-            localPort: config.port,
-            servePort: config.tailscaleServePort,
-            localHost: "127.0.0.1",
-          }).pipe(
-            Effect.tap(() =>
-              Effect.logInfo("Tailscale Serve configured", {
-                localPort: config.port,
-                servePort: config.tailscaleServePort,
-              }),
-            ),
-            Effect.catch((cause) =>
-              Effect.logWarning("Failed to configure Tailscale Serve", {
-                cause,
-                localPort: config.port,
-                servePort: config.tailscaleServePort,
-              }),
+          Effect.acquireRelease(
+            ensureTailscaleServe({
+              localPort: config.port,
+              servePort: config.tailscaleServePort,
+              localHost: "127.0.0.1",
+            }).pipe(
+              Effect.as(true),
+              Effect.tap(() =>
+                Effect.logInfo("Tailscale Serve configured", {
+                  localPort: config.port,
+                  servePort: config.tailscaleServePort,
+                }),
+              ),
+              Effect.catch((cause) =>
+                Effect.logWarning("Failed to configure Tailscale Serve", {
+                  cause,
+                  localPort: config.port,
+                  servePort: config.tailscaleServePort,
+                }).pipe(Effect.as(false)),
+              ),
             ),
+            (configured) =>
+              configured
+                ? disableTailscaleServe.pipe(
+                    Effect.tap(() =>
+                      Effect.logInfo("Tailscale Serve disabled", {
+                        servePort: config.tailscaleServePort,
+                      }),
+                    ),
+                    Effect.catch((cause) =>
+                      Effect.logWarning("Failed to disable Tailscale Serve", {
+                        cause,
+                        servePort: config.tailscaleServePort,
+                      }),
+                    ),
+                  )
+                : Effect.void,
           ),
         )
       : Layer.empty;
diff --git a/packages/tailscale/src/tailscale.test.ts b/packages/tailscale/src/tailscale.test.ts
index 7bcad80664f..788ea836dfc 100644
--- a/packages/tailscale/src/tailscale.test.ts
+++ b/packages/tailscale/src/tailscale.test.ts
@@ -4,6 +4,7 @@ import { ChildProcessSpawner } from "effect/unstable/process";
 
 import {
   buildTailscaleHttpsBaseUrl,
+  disableTailscaleServe,
   ensureTailscaleServe,
   isTailscaleIpv4Address,
   parseTailscaleMagicDnsName,
@@ -117,4 +118,14 @@ describe("tailscale", () => {
 
     return ensureTailscaleServe({ localPort: 13773, servePort: 8443 }).pipe(Effect.provide(layer));
   });
+
+  it.effect("disables tailscale serve through the process spawner service", () => {
+    const layer = mockSpawnerLayer((command, args) => {
+      assert.equal(command, "tailscale");
+      assert.deepEqual(args, ["serve", "off"]);
+      return {};
+    });
+
+    return disableTailscaleServe.pipe(Effect.provide(layer));
+  });
 });
diff --git a/packages/tailscale/src/tailscale.ts b/packages/tailscale/src/tailscale.ts
index 46d1183667e..ff944299d71 100644
--- a/packages/tailscale/src/tailscale.ts
+++ b/packages/tailscale/src/tailscale.ts
@@ -195,15 +195,17 @@ export function buildTailscaleHttpsBaseUrl(input: {
   return url.toString();
 }
 
-export const ensureTailscaleServe = (input: {
-  readonly localPort: number;
-  readonly servePort?: number;
-  readonly localHost?: string;
-}): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> => {
-  const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
-  const localHost = input.localHost ?? "127.0.0.1";
-  const args = ["serve", "--bg", `--https=${servePort}`, `http://${localHost}:${input.localPort}`];
-  return Effect.gen(function* () {
+const runTailscaleCommand = (
+  args: readonly string[],
+  input: {
+    readonly spawnMessage: string;
+    readonly runMessage: string;
+    readonly exitMessage: (exitCode: number) => string;
+    readonly timeoutMessage: string;
+    readonly timeoutMs: number;
+  },
+): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function* () {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const child = yield* spawner
       .spawn(
@@ -215,7 +217,7 @@ export const ensureTailscaleServe = (input: {
         Effect.mapError((cause) =>
           tailscaleCommandError(
             args,
-            cause instanceof Error ? cause.message : "Failed to spawn tailscale serve.",
+            cause instanceof Error ? cause.message : input.spawnMessage,
             null,
           ),
         ),
@@ -227,31 +229,54 @@ export const ensureTailscaleServe = (input: {
       Effect.mapError((cause) =>
         tailscaleCommandError(
           args,
-          cause instanceof Error ? cause.message : "Failed to run tailscale serve.",
+          cause instanceof Error ? cause.message : input.runMessage,
           null,
         ),
       ),
     );
     if (exitCode !== 0) {
-      return yield* tailscaleCommandError(
-        args,
-        `Tailscale serve exited with code ${exitCode}.`,
-        exitCode,
-        stderr,
-      );
+      return yield* tailscaleCommandError(args, input.exitMessage(exitCode), exitCode, stderr);
     }
   }).pipe(
     Effect.scoped,
-    Effect.timeoutOption(TAILSCALE_SERVE_TIMEOUT_MS),
+    Effect.timeoutOption(input.timeoutMs),
     Effect.flatMap((result) =>
       Option.match(result, {
-        onNone: () => Effect.fail(tailscaleCommandError(args, "Tailscale serve timed out.", null)),
+        onNone: () => Effect.fail(tailscaleCommandError(args, input.timeoutMessage, null)),
         onSome: Effect.succeed,
       }),
     ),
   );
+
+export const ensureTailscaleServe = (input: {
+  readonly localPort: number;
+  readonly servePort?: number;
+  readonly localHost?: string;
+}): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> => {
+  const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
+  const localHost = input.localHost ?? "127.0.0.1";
+  const args = ["serve", "--bg", `--https=${servePort}`, `http://${localHost}:${input.localPort}`];
+  return runTailscaleCommand(args, {
+    spawnMessage: "Failed to spawn tailscale serve.",
+    runMessage: "Failed to run tailscale serve.",
+    exitMessage: (exitCode) => `Tailscale serve exited with code ${exitCode}.`,
+    timeoutMessage: "Tailscale serve timed out.",
+    timeoutMs: TAILSCALE_SERVE_TIMEOUT_MS,
+  });
 };
 
+export const disableTailscaleServe: Effect.Effect<
+  void,
+  TailscaleCommandError,
+  ChildProcessSpawner.ChildProcessSpawner
+> = runTailscaleCommand(["serve", "off"], {
+  spawnMessage: "Failed to spawn tailscale serve off.",
+  runMessage: "Failed to run tailscale serve off.",
+  exitMessage: (exitCode) => `Tailscale serve off exited with code ${exitCode}.`,
+  timeoutMessage: "Tailscale serve off timed out.",
+  timeoutMs: TAILSCALE_SERVE_TIMEOUT_MS,
+});
+
 export const probeTailscaleHttpsEndpoint = (input: {
   readonly baseUrl: string;
   readonly timeoutMs?: number;

From 8117b652b835ccd73639659c943d4934cb40bb2d Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 28 Apr 2026 17:44:04 -0700
Subject: [PATCH 37/74] Refactor SSH desktop pairing onto shared runtime

- Move SSH auth, config, and tunnel logic into `packages/ssh`
- Wire `apps/desktop` to the shared Effect runtime
- Add tests for config, auth, and tunnel behavior
---
 apps/desktop/src/sshEnvironment.test.ts |  294 +------
 apps/desktop/src/sshEnvironment.ts      | 1016 ++++-------------------
 bun.lock                                |    2 +
 packages/ssh/package.json               |    2 +
 packages/ssh/src/auth.test.ts           |   47 +-
 packages/ssh/src/auth.ts                |  187 +++++
 packages/ssh/src/command.ts             |  193 +++++
 packages/ssh/src/config.test.ts         |  155 ++--
 packages/ssh/src/config.ts              |  188 +++--
 packages/ssh/src/errors.ts              |   40 +
 packages/ssh/src/index.ts               |    5 -
 packages/ssh/src/tunnel.test.ts         |   44 +
 packages/ssh/src/tunnel.ts              |  851 +++++++++++++++++++
 13 files changed, 1707 insertions(+), 1317 deletions(-)
 delete mode 100644 packages/ssh/src/index.ts
 create mode 100644 packages/ssh/src/tunnel.test.ts

diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index 6fcc0e783ea..cb6281b9ccc 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -1,14 +1,12 @@
 import * as FS from "node:fs";
-import { EventEmitter } from "node:events";
 import * as OS from "node:os";
 import * as Path from "node:path";
 
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 
-import { __test, DesktopSshEnvironmentManager, discoverDesktopSshHosts } from "./sshEnvironment.ts";
+import { discoverDesktopSshHosts } from "./sshEnvironment.ts";
 
 const tempDirectories: string[] = [];
-type TunnelEntry = Parameters<typeof __test.stopTunnel>[0];
 
 afterEach(() => {
   for (const directory of tempDirectories.splice(0)) {
@@ -23,7 +21,7 @@ function makeTempHomeDir(): string {
 }
 
 describe("sshEnvironment", () => {
-  it("discovers ssh config hosts across included files", async () => {
+  it("wires desktop host discovery through the ssh package runtime", async () => {
     const homeDir = makeTempHomeDir();
     const sshDir = Path.join(homeDir, ".ssh");
     FS.mkdirSync(Path.join(sshDir, "config.d"), { recursive: true });
@@ -85,290 +83,4 @@ describe("sshEnvironment", () => {
       },
     ]);
   });
-
-  it("parses known_hosts entries without returning hashed hosts", () => {
-    expect(
-      __test.parseKnownHostsHostnames(
-        [
-          "github.com ssh-ed25519 AAAA",
-          "gitlab.com,gitlab-alias ssh-ed25519 BBBB",
-          "|1|hashed|entry ssh-ed25519 CCCC",
-          "@cert-authority *.example.com ssh-ed25519 DDDD",
-          "[ssh.example.com]:2200 ssh-ed25519 EEEE",
-          "port.example.com:22 ssh-ed25519 HHHH",
-          "::1 ssh-ed25519 FFFF",
-          "2001:db8::1 ssh-ed25519 GGGG",
-          "",
-        ].join("\n"),
-      ),
-    ).toEqual([
-      "::1",
-      "2001:db8::1",
-      "github.com",
-      "gitlab-alias",
-      "gitlab.com",
-      "port.example.com",
-      "ssh.example.com",
-    ]);
-  });
-
-  it("expands tilde-prefixed ssh config include patterns", () => {
-    expect(
-      __test.resolveSshConfigIncludePattern("~/.ssh/config.d/*.conf", "/tmp/project", "/tmp/home"),
-    ).toBe("/tmp/home/.ssh/config.d/*.conf");
-  });
-
-  it("parses resolved ssh config output into a target", () => {
-    expect(
-      __test.parseSshResolveOutput(
-        "devbox",
-        ["hostname devbox.example.com", "user julius", "port 2222", ""].join("\n"),
-      ),
-    ).toEqual({
-      alias: "devbox",
-      hostname: "devbox.example.com",
-      username: "julius",
-      port: 2222,
-    });
-  });
-
-  it("builds interactive ssh args without forcing batch mode", () => {
-    expect(
-      __test.baseSshArgs(
-        {
-          alias: "devbox",
-          hostname: "devbox.example.com",
-          username: "julius",
-          port: 2222,
-        },
-        { batchMode: "no" },
-      ),
-    ).toEqual(["-o", "BatchMode=no", "-o", "ConnectTimeout=10", "-p", "2222"]);
-  });
-
-  it("creates askpass env for desktop ssh prompts", () => {
-    const askpassDirectory = Path.join(makeTempHomeDir(), "askpass");
-    const env = __test.buildSshChildEnvironment({
-      authSecret: "super-secret",
-      interactiveAuth: true,
-      askpassDirectory,
-      platform: "linux",
-      baseEnv: {},
-    });
-
-    expect(env.SSH_ASKPASS).toBe(Path.join(askpassDirectory, "ssh-askpass.sh"));
-    expect(env.SSH_ASKPASS_REQUIRE).toBe("force");
-    expect(env.T3_SSH_AUTH_SECRET).toBe("super-secret");
-    expect(env.DISPLAY).toBe("t3code");
-    expect(FS.existsSync(Path.join(askpassDirectory, "ssh-askpass.sh"))).toBe(true);
-    expect(FS.readFileSync(Path.join(askpassDirectory, "ssh-askpass.sh"), "utf8")).toContain(
-      'printf "%s\\n" "$T3_SSH_AUTH_SECRET"',
-    );
-  });
-
-  it("builds a windows askpass launcher pair", () => {
-    const descriptor = __test.buildSshAskpassHelperDescriptor({
-      directory: "C:\\temp\\t3code-ssh-askpass",
-      platform: "win32",
-    });
-
-    expect(descriptor.launcherPath).toBe("C:\\temp\\t3code-ssh-askpass\\ssh-askpass.cmd");
-    expect(descriptor.files.map((file) => Path.win32.basename(file.path))).toEqual([
-      "ssh-askpass.cmd",
-      "ssh-askpass.ps1",
-    ]);
-  });
-
-  it("builds a remote t3 runner with npx and npm fallbacks", () => {
-    const script = __test.buildRemoteT3RunnerScript();
-
-    expect(script).toContain('exec t3 "$@"');
-    expect(script).toContain('exec npx --yes t3@latest "$@"');
-    expect(script).toContain('exec npm exec --yes t3@latest -- "$@"');
-    expect(script).toContain("could not install t3@latest");
-  });
-
-  it("resolves the remote t3 package spec from the desktop release channel", () => {
-    expect(
-      __test.resolveRemoteT3CliPackageSpec({
-        appVersion: "0.0.17",
-        updateChannel: "latest",
-      }),
-    ).toBe("t3@0.0.17");
-    expect(
-      __test.resolveRemoteT3CliPackageSpec({
-        appVersion: "0.0.17-nightly.20260415.44",
-        updateChannel: "nightly",
-      }),
-    ).toBe("t3@0.0.17-nightly.20260415.44");
-    expect(
-      __test.resolveRemoteT3CliPackageSpec({
-        appVersion: "0.0.0-dev",
-        updateChannel: "nightly",
-        isDevelopment: true,
-      }),
-    ).toBe("t3@nightly");
-    expect(
-      __test.resolveRemoteT3CliPackageSpec({
-        appVersion: "0.0.0-dev",
-        updateChannel: "latest",
-        isDevelopment: true,
-      }),
-    ).toBe("t3@nightly");
-  });
-
-  it("uses the remote t3 runner for launch and pairing scripts", () => {
-    const target = {
-      alias: "devbox",
-      hostname: "devbox.example.com",
-      username: "julius",
-      port: 2222,
-    } as const;
-
-    expect(__test.buildRemoteLaunchScript()).toContain(
-      '[ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null',
-    );
-    expect(__test.buildRemoteLaunchScript()).toContain('"$RUNNER_FILE" serve --host 127.0.0.1');
-    expect(__test.buildRemoteLaunchScript({ packageSpec: "t3@nightly" })).toContain(
-      'exec npx --yes t3@nightly "$@"',
-    );
-    expect(__test.buildRemotePairingScript(target)).toContain(
-      '"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json',
-    );
-    expect(__test.buildRemotePairingScript(target, { packageSpec: "t3@nightly" })).toContain(
-      'exec npm exec --yes t3@nightly -- "$@"',
-    );
-  });
-
-  it("reads the last non-empty ssh output line", () => {
-    expect(
-      __test.getLastNonEmptyOutputLine(
-        ["Welcome to the host", "", '{"credential":"pairing-token"}', ""].join("\n"),
-      ),
-    ).toBe('{"credential":"pairing-token"}');
-  });
-
-  it("detects ssh auth failures from common permission denied messages", () => {
-    expect(
-      __test.isSshAuthFailure(
-        new Error(
-          "julius@100.65.180.100: Permission denied (publickey,password,keyboard-interactive).",
-        ),
-      ),
-    ).toBe(true);
-    expect(__test.isSshAuthFailure(new Error("Permission denied (publickey)."))).toBe(true);
-    expect(__test.isSshAuthFailure(new Error("Connection timed out"))).toBe(false);
-    expect(__test.isSshAuthFailure(new Error("mkdir: Permission denied"))).toBe(false);
-  });
-
-  it("allows the remote port picker to run without a state file path", () => {
-    expect(__test.readSshScriptTemplate("remote-pick-port.cjs")).toContain(
-      'const filePath = process.argv[2] ?? "";',
-    );
-  });
-
-  it("settles tunnel shutdown if the child exits before the exit listener attaches", async () => {
-    vi.useFakeTimers();
-
-    class RaceChildProcess extends EventEmitter {
-      exitCode: number | null = null;
-      signalCode: NodeJS.Signals | null = null;
-
-      override once(eventName: string | symbol, listener: (...args: any[]) => void): this {
-        if (eventName === "exit") {
-          this.exitCode = 0;
-          return this;
-        }
-        return super.once(eventName, listener);
-      }
-
-      kill(): boolean {
-        return true;
-      }
-    }
-
-    try {
-      const child = new RaceChildProcess();
-      const stopPromise = __test
-        .stopTunnel({
-          key: "devbox",
-          target: {
-            alias: "devbox",
-            hostname: "devbox.example.com",
-            username: "julius",
-            port: 22,
-          },
-          remotePort: 3773,
-          localPort: 3774,
-          httpBaseUrl: "http://127.0.0.1:3774/",
-          wsBaseUrl: "ws://127.0.0.1:3774/",
-          process: child as never,
-        })
-        .then(() => "resolved");
-
-      await vi.runAllTimersAsync();
-
-      await expect(Promise.race([stopPromise, Promise.resolve("pending")])).resolves.toBe(
-        "resolved",
-      );
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
-  it("waits for pending tunnel creation before disposing completed tunnels", async () => {
-    class ControlledChildProcess extends EventEmitter {
-      exitCode: number | null = null;
-      signalCode: NodeJS.Signals | null = null;
-      readonly killSignals: Array<NodeJS.Signals | undefined> = [];
-
-      kill(signal?: NodeJS.Signals | number): boolean {
-        this.killSignals.push(typeof signal === "string" ? signal : undefined);
-        this.signalCode = "SIGTERM";
-        this.emit("exit", null, this.signalCode);
-        return true;
-      }
-    }
-
-    let resolvePending!: (entry: TunnelEntry) => void;
-    const child = new ControlledChildProcess();
-    const entry: TunnelEntry = {
-      key: "devbox",
-      target: {
-        alias: "devbox",
-        hostname: "devbox.example.com",
-        username: "julius",
-        port: 22,
-      },
-      remotePort: 3773,
-      localPort: 3774,
-      httpBaseUrl: "http://127.0.0.1:3774/",
-      wsBaseUrl: "ws://127.0.0.1:3774/",
-      process: child as never,
-    };
-    const manager = new DesktopSshEnvironmentManager();
-    const internals = manager as unknown as {
-      pendingTunnelEntries: Map<string, Promise<TunnelEntry>>;
-      tunnels: Map<string, TunnelEntry>;
-    };
-    const pending = new Promise<TunnelEntry>((resolve) => {
-      resolvePending = resolve;
-    }).then((completedEntry) => {
-      internals.tunnels.set(completedEntry.key, completedEntry);
-      return completedEntry;
-    });
-    internals.pendingTunnelEntries.set(entry.key, pending);
-
-    const disposePromise = manager.dispose();
-    await Promise.resolve();
-
-    expect(child.killSignals).toEqual([]);
-
-    resolvePending(entry);
-    await disposePromise;
-
-    expect(child.killSignals).toEqual(["SIGTERM"]);
-    expect(internals.tunnels.size).toBe(0);
-    expect(internals.pendingTunnelEntries.size).toBe(0);
-  });
 });
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index d3db8654da4..92fa57cf708 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -1,601 +1,115 @@
-import * as ChildProcess from "node:child_process";
 import * as Crypto from "node:crypto";
-import * as FS from "node:fs";
-import * as OS from "node:os";
-import * as Path from "node:path";
-import * as Net from "node:net";
 
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { NetService } from "@t3tools/shared/Net";
 import type {
   AuthBearerBootstrapResult,
   AuthSessionState,
   AuthWebSocketTokenResult,
   DesktopDiscoveredSshHost,
-  DesktopSshEnvironmentBootstrap,
   DesktopSshEnvironmentTarget,
   DesktopSshPasswordPromptRequest,
   ExecutionEnvironmentDescriptor,
 } from "@t3tools/contracts";
-import { isSshAuthFailure, type SshPasswordRequest } from "@t3tools/ssh/auth";
 import {
-  baseSshArgs,
-  buildSshHostSpec,
-  getLastNonEmptyOutputLine,
-  parseSshResolveOutput,
-  remoteStateKey,
-  resolveRemoteT3CliPackageSpec,
-  targetConnectionKey,
-} from "@t3tools/ssh/command";
+  SshPasswordPrompt,
+  type SshPasswordPromptShape,
+  type SshPasswordRequest,
+} from "@t3tools/ssh/auth";
+import { discoverSshHosts } from "@t3tools/ssh/config";
+import { SshPasswordPromptError } from "@t3tools/ssh/errors";
 import {
-  collectSshConfigAliasesFromFile,
-  discoverSshHosts,
-  parseKnownHostsHostnames,
-  resolveSshConfigIncludePattern,
-} from "@t3tools/ssh/config";
-import { DEFAULT_REMOTE_PORT, normalizeSshErrorMessage } from "@t3tools/ssh/tunnel";
-import { Effect } from "effect";
-
-import { waitForHttpReady } from "./backendReadiness.ts";
+  fetchLoopbackSshJson,
+  SshEnvironmentManager,
+} from "@t3tools/ssh/tunnel";
+import { Effect, Exit, Layer, ManagedRuntime, Scope } from "effect";
 
 export { resolveRemoteT3CliPackageSpec } from "@t3tools/ssh/command";
 
-const REMOTE_PORT_SCAN_WINDOW = 200;
-const SSH_ASKPASS_DIR_NAME = "t3code-ssh-askpass";
-const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
-const SSH_READY_TIMEOUT_MS = 20_000;
-
 const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
 const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
-const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
-const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
+const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL =
+  "desktop:fetch-ssh-environment-descriptor";
+const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL =
+  "desktop:bootstrap-ssh-bearer-session";
 const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
 const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
 const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
-const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
+const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL =
+  "desktop:resolve-ssh-password-prompt";
 const DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
 
-interface SshTunnelEntry {
-  readonly key: string;
-  readonly target: DesktopSshEnvironmentTarget;
-  readonly remotePort: number;
-  readonly localPort: number;
-  readonly httpBaseUrl: string;
-  readonly wsBaseUrl: string;
-  readonly process: ChildProcess.ChildProcess;
-}
-
-interface SshCommandResult {
-  readonly stdout: string;
-  readonly stderr: string;
-}
-
-interface SshAskpassFile {
-  readonly path: string;
-  readonly contents: string;
-  readonly mode?: number;
-}
-
-interface SshAskpassHelperDescriptor {
-  readonly launcherPath: string;
-  readonly files: ReadonlyArray<SshAskpassFile>;
-}
-
-interface SshAuthOptions {
-  readonly authSecret?: string | null;
-  readonly batchMode?: "yes" | "no";
-  readonly interactiveAuth?: boolean;
-}
-
 interface DesktopSshEnvironmentManagerOptions {
-  readonly passwordProvider?: (request: SshPasswordRequest) => Promise<string | null>;
+  readonly passwordProvider?: (
+    request: SshPasswordRequest,
+  ) => Promise<string | null>;
   readonly resolveCliPackageSpec?: () => string;
 }
 
-async function findAvailableLocalPort(): Promise<number> {
-  return await new Promise<number>((resolve, reject) => {
-    const server = Net.createServer();
-    server.unref();
-    server.once("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      if (!address || typeof address === "string") {
-        server.close(() => reject(new Error("Unable to allocate a local tunnel port.")));
-        return;
-      }
-      const { port } = address;
-      server.close((error) => {
-        if (error) {
-          reject(error);
-          return;
-        }
-        resolve(port);
-      });
-    });
-  });
-}
-
-function getDefaultSshAskpassDirectory(): string {
-  return Path.join(OS.tmpdir(), SSH_ASKPASS_DIR_NAME);
-}
-
-const SSH_SCRIPTS_DIR = Path.join(__dirname, "sshScripts");
-const sshScriptCache = new Map<string, string>();
-
-function readSshScriptTemplate(fileName: string): string {
-  const cached = sshScriptCache.get(fileName);
-  if (cached !== undefined) {
-    return cached;
-  }
-  const contents = FS.readFileSync(Path.join(SSH_SCRIPTS_DIR, fileName), "utf8");
-  sshScriptCache.set(fileName, contents);
-  return contents;
-}
-
-function stripTrailingNewlines(value: string): string {
-  return value.replace(/\n+$/u, "");
-}
-
-function applyScriptPlaceholders(
-  template: string,
-  replacements: Readonly<Record<string, string>>,
-): string {
-  let result = template;
-  for (const [token, value] of Object.entries(replacements)) {
-    result = result.replaceAll(`@@${token}@@`, value);
-  }
-  return result;
-}
-
-function toCrlf(value: string): string {
-  return value.replace(/\r?\n/gu, "\r\n");
-}
-
-function buildPosixSshAskpassScript(): string {
-  return readSshScriptTemplate("askpass-posix.sh");
-}
-
-function buildWindowsSshAskpassScript(): string {
-  return toCrlf(readSshScriptTemplate("askpass-windows.ps1"));
-}
-
-function buildWindowsSshAskpassLauncherScript(): string {
-  return toCrlf(readSshScriptTemplate("askpass-windows.cmd"));
-}
-
-function buildSshAskpassHelperDescriptor(input?: {
-  readonly directory?: string;
-  readonly platform?: NodeJS.Platform;
-}): SshAskpassHelperDescriptor {
-  const platform = input?.platform ?? process.platform;
-  const directory = input?.directory ?? getDefaultSshAskpassDirectory();
-  const pathModule = platform === "win32" ? Path.win32 : Path.posix;
-
-  if (platform === "win32") {
-    const powershellPath = pathModule.join(directory, "ssh-askpass.ps1");
-    return {
-      launcherPath: pathModule.join(directory, "ssh-askpass.cmd"),
-      files: [
-        {
-          path: pathModule.join(directory, "ssh-askpass.cmd"),
-          contents: buildWindowsSshAskpassLauncherScript(),
-        },
-        {
-          path: powershellPath,
-          contents: buildWindowsSshAskpassScript(),
-        },
-      ],
-    };
-  }
-
-  return {
-    launcherPath: pathModule.join(directory, "ssh-askpass.sh"),
-    files: [
-      {
-        path: pathModule.join(directory, "ssh-askpass.sh"),
-        contents: buildPosixSshAskpassScript(),
-        mode: 0o700,
-      },
-    ],
-  };
-}
-
-function ensureSshAskpassHelpers(input?: {
-  readonly directory?: string;
-  readonly platform?: NodeJS.Platform;
-}): string {
-  const descriptor = buildSshAskpassHelperDescriptor(input);
-  const platform = input?.platform ?? process.platform;
-  FS.mkdirSync(Path.dirname(descriptor.launcherPath), { recursive: true });
-
-  for (const file of descriptor.files) {
-    const current =
-      FS.existsSync(file.path) && FS.statSync(file.path).isFile()
-        ? FS.readFileSync(file.path, "utf8")
-        : null;
-    if (current !== file.contents) {
-      FS.writeFileSync(file.path, file.contents, "utf8");
-    }
-    if (file.mode !== undefined && platform !== "win32") {
-      FS.chmodSync(file.path, file.mode);
-    }
-  }
-
-  return descriptor.launcherPath;
-}
-
-function buildSshChildEnvironment(input?: {
-  readonly interactiveAuth?: boolean;
-  readonly baseEnv?: NodeJS.ProcessEnv;
-  readonly askpassDirectory?: string;
-  readonly authSecret?: string | null;
-  readonly platform?: NodeJS.Platform;
-}): NodeJS.ProcessEnv {
-  const baseEnv = { ...(input?.baseEnv ?? process.env) };
-  if (!input?.interactiveAuth) {
-    return baseEnv;
-  }
-
-  const platform = input?.platform ?? process.platform;
-  const askpassInput =
-    input?.askpassDirectory === undefined
-      ? { platform }
-      : {
-          directory: input.askpassDirectory,
-          platform,
-        };
-  return {
-    ...baseEnv,
-    SSH_ASKPASS: ensureSshAskpassHelpers(askpassInput),
-    SSH_ASKPASS_REQUIRE: "force",
-    ...(input?.authSecret === undefined ? {} : { T3_SSH_AUTH_SECRET: input.authSecret ?? "" }),
-    ...(platform === "win32" || baseEnv.DISPLAY ? {} : { DISPLAY: "t3code" }),
-  };
-}
-
-async function runSshCommand(
-  target: DesktopSshEnvironmentTarget,
-  input?: {
-    readonly preHostArgs?: ReadonlyArray<string>;
-    readonly remoteCommandArgs?: ReadonlyArray<string>;
-    readonly stdin?: string;
-    readonly signal?: AbortSignal;
-    readonly authSecret?: string | null;
-    readonly batchMode?: "yes" | "no";
-    readonly interactiveAuth?: boolean;
-  },
-): Promise<SshCommandResult> {
-  const hostSpec = buildSshHostSpec(target);
-
-  return await new Promise<SshCommandResult>((resolve, reject) => {
-    const childEnvironment =
-      input?.interactiveAuth === undefined
-        ? buildSshChildEnvironment()
-        : buildSshChildEnvironment({
-            interactiveAuth: input.interactiveAuth,
-            ...(input.authSecret === undefined ? {} : { authSecret: input.authSecret }),
-          });
-    const child = ChildProcess.spawn(
-      "ssh",
-      [
-        ...baseSshArgs(target, {
-          batchMode: input?.batchMode ?? (input?.interactiveAuth ? "no" : "yes"),
-        }),
-        ...(input?.preHostArgs ?? []),
-        hostSpec,
-        ...(input?.remoteCommandArgs ?? []),
-      ],
-      {
-        env: childEnvironment,
-        stdio: "pipe",
-      },
-    );
-
-    let stdout = "";
-    let stderr = "";
-
-    const onAbort = () => {
-      child.kill("SIGTERM");
-      reject(new Error(`SSH command aborted for ${hostSpec}.`));
-    };
-
-    input?.signal?.addEventListener("abort", onAbort, { once: true });
-    child.stdout?.setEncoding("utf8");
-    child.stderr?.setEncoding("utf8");
-    child.stdout?.on("data", (chunk: string) => {
-      stdout += chunk;
-    });
-    child.stderr?.on("data", (chunk: string) => {
-      stderr += chunk;
-    });
-    child.once("error", (error) => {
-      input?.signal?.removeEventListener("abort", onAbort);
-      reject(error);
-    });
-    child.once("close", (code) => {
-      input?.signal?.removeEventListener("abort", onAbort);
-      if (code === 0) {
-        resolve({ stdout, stderr });
-        return;
-      }
-      reject(
-        new Error(
-          normalizeSshErrorMessage(stderr, `SSH command failed for ${hostSpec} (exit ${code}).`),
-        ),
-      );
-    });
-
-    if (input?.stdin !== undefined) {
-      child.stdin?.end(input.stdin);
-      return;
-    }
-    child.stdin?.end();
-  });
-}
-
-async function resolveDesktopSshTarget(alias: string): Promise<DesktopSshEnvironmentTarget> {
-  const trimmedAlias = alias.trim();
-  if (trimmedAlias.length === 0) {
-    throw new Error("SSH host alias is required.");
-  }
-
-  try {
-    const result = await runSshCommand(
-      {
-        alias: trimmedAlias,
-        hostname: trimmedAlias,
-        username: null,
-        port: null,
-      },
-      { preHostArgs: ["-G"] },
-    );
-    return parseSshResolveOutput(trimmedAlias, result.stdout);
-  } catch {
-    return {
-      alias: trimmedAlias,
-      hostname: trimmedAlias,
-      username: null,
-      port: null,
-    };
-  }
-}
-
-function buildRemoteLaunchScript(input?: { readonly packageSpec?: string }): string {
-  return applyScriptPlaceholders(readSshScriptTemplate("remote-launch.sh"), {
-    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
-    T3_PICK_PORT_SCRIPT: stripTrailingNewlines(readSshScriptTemplate("remote-pick-port.cjs")),
-    T3_DEFAULT_REMOTE_PORT: String(DEFAULT_REMOTE_PORT),
-    T3_REMOTE_PORT_SCAN_WINDOW: String(REMOTE_PORT_SCAN_WINDOW),
-  });
-}
-
-function buildRemoteT3RunnerScript(input?: { readonly packageSpec?: string }): string {
-  const packageSpec = input?.packageSpec?.trim() || "t3@latest";
-  return stripTrailingNewlines(
-    applyScriptPlaceholders(readSshScriptTemplate("remote-runner.sh"), {
-      T3_PACKAGE_SPEC: packageSpec,
-    }),
+const sshRuntime = ManagedRuntime.make(
+  Layer.mergeAll(
+    NodeServices.layer,
+    NodeHttpClient.layerUndici,
+    NetService.layer,
+  ),
+);
+
+function createDesktopSshRuntime(
+  passwordPrompt: SshPasswordPromptShape,
+  scope: Scope.Scope,
+  options: DesktopSshEnvironmentManagerOptions,
+) {
+  return ManagedRuntime.make(
+    Layer.mergeAll(
+      NodeServices.layer,
+      NodeHttpClient.layerUndici,
+      NetService.layer,
+      Layer.succeed(Scope.Scope, scope),
+      Layer.succeed(SshPasswordPrompt, SshPasswordPrompt.of(passwordPrompt)),
+      SshEnvironmentManager.layer(
+        options.resolveCliPackageSpec === undefined
+          ? {}
+          : { resolveCliPackageSpec: options.resolveCliPackageSpec },
+      ),
+    ),
   );
 }
 
-function buildRemotePairingScript(
-  target: DesktopSshEnvironmentTarget,
-  input?: { readonly packageSpec?: string },
-): string {
-  return applyScriptPlaceholders(readSshScriptTemplate("remote-pairing.sh"), {
-    T3_STATE_KEY: remoteStateKey(target),
-    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
-  });
-}
-
-async function launchOrReuseRemoteServer(
-  target: DesktopSshEnvironmentTarget,
-  input?: SshAuthOptions,
-  runner?: { readonly packageSpec?: string },
-): Promise<number> {
-  const result = await runSshCommand(target, {
-    remoteCommandArgs: ["sh", "-s", "--", remoteStateKey(target)],
-    stdin: buildRemoteLaunchScript(runner),
-    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
-    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
-    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
-  });
-  const line = getLastNonEmptyOutputLine(result.stdout);
-  if (!line) {
-    throw new Error(
-      `SSH launch did not return a remote port. stdout=${JSON.stringify(result.stdout)}`,
-    );
-  }
-
-  let parsed: { remotePort?: unknown };
-  try {
-    parsed = JSON.parse(line) as { remotePort?: unknown };
-  } catch (cause) {
-    throw new Error(
-      `SSH launch returned unparseable output. line=${JSON.stringify(line)} stdout=${JSON.stringify(result.stdout)}`,
-      { cause },
-    );
-  }
-  if (typeof parsed.remotePort !== "number" || !Number.isInteger(parsed.remotePort)) {
-    throw new Error(
-      `SSH launch returned an invalid remote port. parsed=${JSON.stringify(parsed)} stdout=${JSON.stringify(result.stdout)}`,
-    );
-  }
-  return parsed.remotePort;
-}
-
-async function issueRemotePairingToken(
-  target: DesktopSshEnvironmentTarget,
-  input?: SshAuthOptions,
-  runner?: { readonly packageSpec?: string },
-): Promise<string> {
-  const result = await runSshCommand(target, {
-    remoteCommandArgs: ["sh", "-s"],
-    stdin: buildRemotePairingScript(target, runner),
-    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
-    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
-    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
-  });
-  const line = getLastNonEmptyOutputLine(result.stdout);
-  if (!line) {
-    throw new Error(
-      `SSH pairing did not return a credential. stdout=${JSON.stringify(result.stdout)}`,
-    );
-  }
-
-  let parsed: { credential?: unknown };
-  try {
-    parsed = JSON.parse(line) as { credential?: unknown };
-  } catch (cause) {
-    throw new Error(
-      `SSH pairing returned unparseable output. line=${JSON.stringify(line)} stdout=${JSON.stringify(result.stdout)}`,
-      { cause },
-    );
-  }
-  if (typeof parsed.credential !== "string" || parsed.credential.trim().length === 0) {
-    throw new Error(
-      `SSH pairing command returned an invalid credential. parsed=${JSON.stringify(parsed)} stdout=${JSON.stringify(result.stdout)}`,
-    );
-  }
-  return parsed.credential;
-}
-
-async function stopTunnel(entry: SshTunnelEntry): Promise<void> {
-  const child = entry.process;
-  if (child.exitCode !== null || child.signalCode !== null) {
-    return;
-  }
-
-  await new Promise<void>((resolve) => {
-    let settled = false;
-    let forceKillTimer: ReturnType<typeof setTimeout> | null = null;
-    let hardStopTimer: ReturnType<typeof setTimeout> | null = null;
-
-    const settle = () => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      child.off("exit", onExit);
-      if (forceKillTimer) {
-        clearTimeout(forceKillTimer);
-      }
-      if (hardStopTimer) {
-        clearTimeout(hardStopTimer);
-      }
-      resolve();
-    };
-
-    const onExit = () => {
-      settle();
-    };
-
-    child.once("exit", onExit);
-    if (child.exitCode !== null || child.signalCode !== null) {
-      settle();
-      return;
-    }
-    if (!child.kill("SIGTERM")) {
-      settle();
-      return;
-    }
-    forceKillTimer = setTimeout(() => {
-      if (child.exitCode === null && child.signalCode === null) {
-        child.kill("SIGKILL");
-      }
-      hardStopTimer = setTimeout(() => {
-        settle();
-      }, 1_000);
-      hardStopTimer.unref();
-    }, TUNNEL_SHUTDOWN_TIMEOUT_MS);
-    forceKillTimer.unref();
-  });
-}
-
 export async function discoverDesktopSshHosts(input?: {
   readonly homeDir?: string;
 }): Promise<readonly DesktopDiscoveredSshHost[]> {
-  return await Effect.runPromise(discoverSshHosts(input));
+  return await sshRuntime.runPromise(discoverSshHosts(input ?? {}));
 }
 
 export class DesktopSshEnvironmentManager {
-  private readonly tunnels = new Map<string, SshTunnelEntry>();
-  private readonly pendingTunnelEntries = new Map<string, Promise<SshTunnelEntry>>();
-  private readonly authSecrets = new Map<string, string>();
-  private readonly options: DesktopSshEnvironmentManagerOptions;
+  private readonly runtime: ReturnType<typeof createDesktopSshRuntime>;
+  private readonly scope: Scope.Scope;
 
   constructor(options: DesktopSshEnvironmentManagerOptions = {}) {
-    this.options = options;
-  }
-
-  private deleteTunnelIfCurrent(entry: SshTunnelEntry): void {
-    if (this.tunnels.get(entry.key) === entry) {
-      this.tunnels.delete(entry.key);
-    }
-  }
-
-  private async promptForPassword(
-    target: DesktopSshEnvironmentTarget,
-    attempt: number,
-  ): Promise<string> {
-    const passwordProvider = this.options.passwordProvider;
-    if (!passwordProvider) {
-      throw new Error(`SSH authentication failed for ${buildSshHostSpec(target)}.`);
-    }
-
-    const password = await passwordProvider({
-      attempt,
-      destination: target.alias.trim() || target.hostname.trim(),
-      username: target.username,
-      prompt: `Enter the SSH password for ${buildSshHostSpec(target)}.`,
-    });
-    if (password === null) {
-      throw new Error(`SSH authentication cancelled for ${buildSshHostSpec(target)}.`);
-    }
-    return password;
-  }
-
-  private async runWithSshAuth<T>(
-    key: string,
-    target: DesktopSshEnvironmentTarget,
-    operation: (authOptions: SshAuthOptions) => Promise<T>,
-  ): Promise<T> {
-    let authSecret = this.authSecrets.get(key) ?? null;
-    let promptCount = 0;
-
-    while (true) {
-      try {
-        return await operation(
-          authSecret === null
-            ? {
-                batchMode: this.options.passwordProvider ? "yes" : "no",
-                interactiveAuth: !this.options.passwordProvider,
-              }
-            : {
-                authSecret,
-                batchMode: "no",
-                interactiveAuth: true,
-              },
-        );
-      } catch (error) {
-        if (!isSshAuthFailure(error)) {
-          throw error;
-        }
-
-        if (!this.options.passwordProvider) {
-          throw error;
-        }
-
-        if (authSecret !== null) {
-          this.authSecrets.delete(key);
-        }
-        if (promptCount >= 2) {
-          throw error;
+    const passwordPrompt: SshPasswordPromptShape = {
+      isAvailable: options.passwordProvider !== undefined,
+      request: (request) => {
+        const passwordProvider = options.passwordProvider;
+        if (!passwordProvider) {
+          return Effect.succeed(null);
         }
 
-        promptCount += 1;
-        authSecret = await this.promptForPassword(target, promptCount);
-        this.authSecrets.set(key, authSecret);
-      }
-    }
+        return Effect.tryPromise({
+          try: () => passwordProvider(request),
+          catch: (cause) =>
+            new SshPasswordPromptError({
+              message:
+                cause instanceof Error
+                  ? cause.message
+                  : "SSH password prompt failed.",
+              cause,
+            }),
+        });
+      },
+    };
+    this.scope = Effect.runSync(Scope.make());
+    this.runtime = createDesktopSshRuntime(passwordPrompt, this.scope, options);
   }
 
   async discoverHosts(): Promise<readonly DesktopDiscoveredSshHost[]> {
@@ -605,160 +119,23 @@ export class DesktopSshEnvironmentManager {
   async ensureEnvironment(
     target: DesktopSshEnvironmentTarget,
     options?: { readonly issuePairingToken?: boolean },
-  ): Promise<DesktopSshEnvironmentBootstrap> {
-    const baseResolved = await resolveDesktopSshTarget(target.alias || target.hostname);
-    const resolvedTarget: DesktopSshEnvironmentTarget = {
-      ...baseResolved,
-      ...(target.username !== null ? { username: target.username } : {}),
-      ...(target.port !== null ? { port: target.port } : {}),
-    };
-    const key = targetConnectionKey(resolvedTarget);
-    const packageSpec = this.options.resolveCliPackageSpec?.();
-    const entry = await this.ensureTunnelEntry(key, resolvedTarget, packageSpec);
-
-    const pairingToken = options?.issuePairingToken
-      ? await this.runWithSshAuth(key, entry.target, (authOptions) =>
-          issueRemotePairingToken(
-            entry.target,
-            authOptions,
-            packageSpec === undefined ? undefined : { packageSpec },
-          ),
-        )
-      : null;
-
-    return {
-      target: entry.target,
-      httpBaseUrl: entry.httpBaseUrl,
-      wsBaseUrl: entry.wsBaseUrl,
-      pairingToken,
-    };
-  }
-
-  private async ensureTunnelEntry(
-    key: string,
-    resolvedTarget: DesktopSshEnvironmentTarget,
-    packageSpec?: string,
-  ): Promise<SshTunnelEntry> {
-    let entry = this.tunnels.get(key) ?? null;
-
-    if (entry !== null) {
-      try {
-        await waitForHttpReady(entry.httpBaseUrl, { timeoutMs: 2_000 });
-        return entry;
-      } catch {
-        await stopTunnel(entry).catch(() => undefined);
-        this.deleteTunnelIfCurrent(entry);
-        entry = null;
-      }
-    }
-
-    const pending = this.pendingTunnelEntries.get(key);
-    if (pending) {
-      return await pending;
-    }
-
-    const nextEntry = (async () => {
-      const remotePort = await this.runWithSshAuth(key, resolvedTarget, (authOptions) =>
-        launchOrReuseRemoteServer(
-          resolvedTarget,
-          authOptions,
-          packageSpec === undefined ? undefined : { packageSpec },
-        ),
-      );
-      const localPort = await findAvailableLocalPort();
-      const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
-      const wsBaseUrl = `ws://127.0.0.1:${localPort}/`;
-      return await this.runWithSshAuth(key, resolvedTarget, async (authOptions) => {
-        const process = ChildProcess.spawn(
-          "ssh",
-          [
-            ...baseSshArgs(resolvedTarget, { batchMode: authOptions.batchMode ?? "no" }),
-            "-o",
-            "ExitOnForwardFailure=yes",
-            "-o",
-            "ServerAliveInterval=15",
-            "-o",
-            "ServerAliveCountMax=3",
-            "-N",
-            "-L",
-            `${localPort}:127.0.0.1:${remotePort}`,
-            buildSshHostSpec(resolvedTarget),
-          ],
-          {
-            env: buildSshChildEnvironment({
-              ...(authOptions.authSecret === undefined
-                ? {}
-                : { authSecret: authOptions.authSecret }),
-              ...(authOptions.interactiveAuth === undefined
-                ? {}
-                : { interactiveAuth: authOptions.interactiveAuth }),
-            }),
-            stdio: "pipe",
-          },
-        );
-        const tunnelEntry: SshTunnelEntry = {
-          key,
-          target: resolvedTarget,
-          remotePort,
-          localPort,
-          httpBaseUrl,
-          wsBaseUrl,
-          process,
-        };
-        const tunnelReady = new Promise<void>((resolve, reject) => {
-          let stderr = "";
-          process.stderr?.setEncoding("utf8");
-          process.stderr?.on("data", (chunk: string) => {
-            stderr += chunk;
-          });
-          process.once("error", (error) => {
-            this.deleteTunnelIfCurrent(tunnelEntry);
-            reject(error);
-          });
-          process.once("exit", (code) => {
-            this.deleteTunnelIfCurrent(tunnelEntry);
-            reject(
-              new Error(
-                normalizeSshErrorMessage(
-                  stderr,
-                  `SSH tunnel exited unexpectedly for ${resolvedTarget.alias} (exit ${code ?? "unknown"}).`,
-                ),
-              ),
-            );
-          });
-          waitForHttpReady(httpBaseUrl, { timeoutMs: SSH_READY_TIMEOUT_MS })
-            .then(() => resolve())
-            .catch((error: unknown) => reject(error));
-        });
-        try {
-          await tunnelReady;
-          this.tunnels.set(key, tunnelEntry);
-          return tunnelEntry;
-        } catch (error) {
-          await stopTunnel(tunnelEntry).catch(() => undefined);
-          throw error;
-        }
-      });
-    })();
-    this.pendingTunnelEntries.set(key, nextEntry);
-    return await nextEntry.finally(() => {
-      if (this.pendingTunnelEntries.get(key) === nextEntry) {
-        this.pendingTunnelEntries.delete(key);
-      }
-    });
+  ) {
+    return await this.runtime.runPromise(
+      Effect.service(SshEnvironmentManager).pipe(
+        Effect.flatMap((manager) => manager.ensureEnvironment(target, options)),
+      ),
+    );
   }
 
   async dispose(): Promise<void> {
-    const pending = [...this.pendingTunnelEntries.values()];
-    await Promise.allSettled(pending);
-    const entries = [...this.tunnels.values()];
-    this.tunnels.clear();
-    this.pendingTunnelEntries.clear();
-    await Promise.all(entries.map((entry) => stopTunnel(entry).catch(() => undefined)));
+    await this.runtime.runPromise(Scope.close(this.scope, Exit.void));
+    await this.runtime.dispose();
   }
 }
 
-function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarget | null {
+function getSafeDesktopSshTarget(
+  rawTarget: unknown,
+): DesktopSshEnvironmentTarget | null {
   if (typeof rawTarget !== "object" || rawTarget === null) {
     return null;
   }
@@ -774,7 +151,11 @@ function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarge
   ) {
     return null;
   }
-  if (target.port !== null && target.port !== undefined && !Number.isInteger(target.port)) {
+  if (
+    target.port !== null &&
+    target.port !== undefined &&
+    !Number.isInteger(target.port)
+  ) {
     return null;
   }
 
@@ -792,99 +173,6 @@ function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarge
   };
 }
 
-function isLoopbackHostname(hostname: string): boolean {
-  const normalized = hostname
-    .trim()
-    .toLowerCase()
-    .replace(/^\[(.*)\]$/, "$1");
-  return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
-}
-
-function resolveLoopbackSshHttpUrl(rawHttpBaseUrl: unknown, pathname: string): URL {
-  if (typeof rawHttpBaseUrl !== "string" || rawHttpBaseUrl.trim().length === 0) {
-    throw new Error("Invalid SSH forwarded http base URL.");
-  }
-
-  let baseUrl: URL;
-  try {
-    baseUrl = new URL(rawHttpBaseUrl);
-  } catch {
-    throw new Error("Invalid SSH forwarded http base URL.");
-  }
-
-  if (!isLoopbackHostname(baseUrl.hostname)) {
-    throw new Error("SSH desktop bridge only supports loopback forwarded URLs.");
-  }
-
-  const url = new URL(baseUrl.toString());
-  url.pathname = pathname;
-  url.search = "";
-  url.hash = "";
-  return url;
-}
-
-async function readRemoteFetchErrorMessage(
-  response: Response,
-  fallbackMessage: string,
-): Promise<string> {
-  const text = await response.text();
-  if (!text) {
-    return fallbackMessage;
-  }
-
-  try {
-    const parsed = JSON.parse(text) as { readonly error?: string };
-    if (typeof parsed.error === "string" && parsed.error.trim().length > 0) {
-      return parsed.error;
-    }
-  } catch {
-    // Fall back to the raw text below.
-  }
-
-  return text;
-}
-
-async function fetchLoopbackSshJson<T>(input: {
-  readonly httpBaseUrl: unknown;
-  readonly pathname: string;
-  readonly method?: "GET" | "POST";
-  readonly bearerToken?: unknown;
-  readonly body?: unknown;
-}): Promise<T> {
-  const requestUrl = resolveLoopbackSshHttpUrl(input.httpBaseUrl, input.pathname).toString();
-  const bearerToken =
-    typeof input.bearerToken === "string" && input.bearerToken.trim().length > 0
-      ? input.bearerToken
-      : null;
-
-  let response: Response;
-  try {
-    response = await fetch(requestUrl, {
-      method: input.method ?? "GET",
-      headers: {
-        ...(input.body !== undefined ? { "content-type": "application/json" } : {}),
-        ...(bearerToken ? { authorization: `Bearer ${bearerToken}` } : {}),
-      },
-      ...(input.body !== undefined ? { body: JSON.stringify(input.body) } : {}),
-    });
-  } catch (error) {
-    throw new Error(
-      `Failed to reach SSH forwarded endpoint ${requestUrl} (${error instanceof Error ? error.message : String(error)}).`,
-      { cause: error },
-    );
-  }
-
-  if (!response.ok) {
-    const message = await readRemoteFetchErrorMessage(
-      response,
-      `SSH forwarded request failed (${response.status}).`,
-    );
-    throw new Error(`[ssh_http:${response.status}] ${message}`);
-  }
-
-  return (await response.json()) as T;
-}
-
 /** Minimal subset of Electron's BrowserWindow used by the SSH bridge. */
 export interface DesktopSshBridgeWindow {
   isDestroyed(): boolean;
@@ -901,7 +189,10 @@ export interface DesktopSshBridgeIpcMain {
   removeHandler(channel: string): void;
   handle(
     channel: string,
-    listener: (event: unknown, ...args: readonly unknown[]) => unknown | Promise<unknown>,
+    listener: (
+      event: unknown,
+      ...args: readonly unknown[]
+    ) => unknown | Promise<unknown>,
   ): void;
 }
 
@@ -939,72 +230,93 @@ export class DesktopSshEnvironmentBridge {
 
   registerIpcHandlers(ipcMain: DesktopSshBridgeIpcMain): void {
     ipcMain.removeHandler(DISCOVER_SSH_HOSTS_CHANNEL);
-    ipcMain.handle(DISCOVER_SSH_HOSTS_CHANNEL, async () => this.manager.discoverHosts());
+    ipcMain.handle(DISCOVER_SSH_HOSTS_CHANNEL, async () =>
+      this.manager.discoverHosts(),
+    );
 
     ipcMain.removeHandler(ENSURE_SSH_ENVIRONMENT_CHANNEL);
-    ipcMain.handle(ENSURE_SSH_ENVIRONMENT_CHANNEL, async (_event, rawTarget, rawOptions) => {
-      const target = getSafeDesktopSshTarget(rawTarget);
-      if (!target) {
-        throw new Error("Invalid desktop SSH target.");
-      }
+    ipcMain.handle(
+      ENSURE_SSH_ENVIRONMENT_CHANNEL,
+      async (_event, rawTarget, rawOptions) => {
+        const target = getSafeDesktopSshTarget(rawTarget);
+        if (!target) {
+          throw new Error("Invalid desktop SSH target.");
+        }
 
-      const issuePairingToken =
-        typeof rawOptions === "object" &&
-        rawOptions !== null &&
-        "issuePairingToken" in rawOptions &&
-        (rawOptions as { issuePairingToken?: unknown }).issuePairingToken === true;
+        const issuePairingToken =
+          typeof rawOptions === "object" &&
+          rawOptions !== null &&
+          "issuePairingToken" in rawOptions &&
+          (rawOptions as { issuePairingToken?: unknown }).issuePairingToken ===
+            true;
 
-      return await this.manager.ensureEnvironment(target, { issuePairingToken });
-    });
+        return await this.manager.ensureEnvironment(target, {
+          issuePairingToken,
+        });
+      },
+    );
 
     ipcMain.removeHandler(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL);
-    ipcMain.handle(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, async (_event, rawHttpBaseUrl) =>
-      fetchLoopbackSshJson<ExecutionEnvironmentDescriptor>({
-        httpBaseUrl: rawHttpBaseUrl,
-        pathname: "/.well-known/t3/environment",
-      }),
+    ipcMain.handle(
+      FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL,
+      async (_event, rawHttpBaseUrl) =>
+        sshRuntime.runPromise(
+          fetchLoopbackSshJson<ExecutionEnvironmentDescriptor>({
+            httpBaseUrl: rawHttpBaseUrl,
+            pathname: "/.well-known/t3/environment",
+          }),
+        ),
     );
 
     ipcMain.removeHandler(BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL);
     ipcMain.handle(
       BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL,
       async (_event, rawHttpBaseUrl, rawCredential) =>
-        fetchLoopbackSshJson<AuthBearerBootstrapResult>({
-          httpBaseUrl: rawHttpBaseUrl,
-          pathname: "/api/auth/bootstrap/bearer",
-          method: "POST",
-          body: { credential: rawCredential },
-        }),
+        sshRuntime.runPromise(
+          fetchLoopbackSshJson<AuthBearerBootstrapResult>({
+            httpBaseUrl: rawHttpBaseUrl,
+            pathname: "/api/auth/bootstrap/bearer",
+            method: "POST",
+            body: { credential: rawCredential },
+          }),
+        ),
     );
 
     ipcMain.removeHandler(FETCH_SSH_SESSION_STATE_CHANNEL);
     ipcMain.handle(
       FETCH_SSH_SESSION_STATE_CHANNEL,
       async (_event, rawHttpBaseUrl, rawBearerToken) =>
-        fetchLoopbackSshJson<AuthSessionState>({
-          httpBaseUrl: rawHttpBaseUrl,
-          pathname: "/api/auth/session",
-          bearerToken: rawBearerToken,
-        }),
+        sshRuntime.runPromise(
+          fetchLoopbackSshJson<AuthSessionState>({
+            httpBaseUrl: rawHttpBaseUrl,
+            pathname: "/api/auth/session",
+            bearerToken: rawBearerToken,
+          }),
+        ),
     );
 
     ipcMain.removeHandler(ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL);
     ipcMain.handle(
       ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL,
       async (_event, rawHttpBaseUrl, rawBearerToken) =>
-        fetchLoopbackSshJson<AuthWebSocketTokenResult>({
-          httpBaseUrl: rawHttpBaseUrl,
-          pathname: "/api/auth/ws-token",
-          method: "POST",
-          bearerToken: rawBearerToken,
-        }),
+        sshRuntime.runPromise(
+          fetchLoopbackSshJson<AuthWebSocketTokenResult>({
+            httpBaseUrl: rawHttpBaseUrl,
+            pathname: "/api/auth/ws-token",
+            method: "POST",
+            bearerToken: rawBearerToken,
+          }),
+        ),
     );
 
     ipcMain.removeHandler(RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL);
     ipcMain.handle(
       RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL,
       async (_event, rawRequestId, rawPassword) => {
-        if (typeof rawRequestId !== "string" || rawRequestId.trim().length === 0) {
+        if (
+          typeof rawRequestId !== "string" ||
+          rawRequestId.trim().length === 0
+        ) {
           throw new Error("Invalid SSH password prompt id.");
         }
         if (rawPassword !== null && typeof rawPassword !== "string") {
@@ -1036,10 +348,14 @@ export class DesktopSshEnvironmentBridge {
     await this.manager.dispose();
   }
 
-  private async requestPasswordFromRenderer(input: SshPasswordRequest): Promise<string | null> {
+  private async requestPasswordFromRenderer(
+    input: SshPasswordRequest,
+  ): Promise<string | null> {
     const window = this.options.getMainWindow();
     if (!window || window.isDestroyed()) {
-      throw new Error("T3 Code window is not available for SSH authentication.");
+      throw new Error(
+        "T3 Code window is not available for SSH authentication.",
+      );
     }
 
     const request: DesktopSshPasswordPromptRequest = {
@@ -1052,7 +368,9 @@ export class DesktopSshEnvironmentBridge {
     return await new Promise<string | null>((resolve, reject) => {
       const timeout = setTimeout(() => {
         this.pendingPrompts.delete(request.requestId);
-        reject(new Error(`SSH authentication timed out for ${input.destination}.`));
+        reject(
+          new Error(`SSH authentication timed out for ${input.destination}.`),
+        );
       }, this.passwordPromptTimeoutMs);
       timeout.unref();
 
@@ -1066,21 +384,3 @@ export class DesktopSshEnvironmentBridge {
     });
   }
 }
-
-export const __test = {
-  baseSshArgs,
-  buildRemoteLaunchScript,
-  buildRemotePairingScript,
-  buildRemoteT3RunnerScript,
-  resolveRemoteT3CliPackageSpec,
-  buildSshAskpassHelperDescriptor,
-  buildSshChildEnvironment,
-  getLastNonEmptyOutputLine,
-  isSshAuthFailure,
-  collectSshConfigAliasesFromFile,
-  parseKnownHostsHostnames,
-  parseSshResolveOutput,
-  readSshScriptTemplate,
-  resolveSshConfigIncludePattern,
-  stopTunnel,
-};
diff --git a/bun.lock b/bun.lock
index d5e33cb55f5..899b275bbf5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -208,10 +208,12 @@
       "version": "0.0.0-alpha.1",
       "dependencies": {
         "@t3tools/contracts": "workspace:*",
+        "@t3tools/shared": "workspace:*",
         "effect": "catalog:",
       },
       "devDependencies": {
         "@effect/language-service": "catalog:",
+        "@effect/platform-node": "catalog:",
         "@effect/vitest": "catalog:",
         "@types/node": "catalog:",
         "typescript": "catalog:",
diff --git a/packages/ssh/package.json b/packages/ssh/package.json
index 9f1984294f0..08793e67c1c 100644
--- a/packages/ssh/package.json
+++ b/packages/ssh/package.json
@@ -32,10 +32,12 @@
   },
   "dependencies": {
     "@t3tools/contracts": "workspace:*",
+    "@t3tools/shared": "workspace:*",
     "effect": "catalog:"
   },
   "devDependencies": {
     "@effect/language-service": "catalog:",
+    "@effect/platform-node": "catalog:",
     "@effect/vitest": "catalog:",
     "@types/node": "catalog:",
     "typescript": "catalog:",
diff --git a/packages/ssh/src/auth.test.ts b/packages/ssh/src/auth.test.ts
index a72c5ef1fc0..f9fe311450d 100644
--- a/packages/ssh/src/auth.test.ts
+++ b/packages/ssh/src/auth.test.ts
@@ -1,7 +1,12 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
-import { Effect } from "effect";
+import { Effect, FileSystem, Path } from "effect";
 
-import { isSshAuthFailure } from "./auth.ts";
+import {
+  buildSshAskpassHelperDescriptor,
+  buildSshChildEnvironment,
+  isSshAuthFailure,
+} from "./auth.ts";
 
 describe("ssh auth", () => {
   it.effect("detects ssh auth failures from common permission denied messages", () =>
@@ -19,4 +24,42 @@ describe("ssh auth", () => {
       assert.equal(isSshAuthFailure(new Error("mkdir: Permission denied")), false);
     }),
   );
+
+  it.effect("creates askpass env for cached password prompts", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const directory = yield* fs.makeTempDirectoryScoped({ prefix: "t3-ssh-askpass-test-" });
+      const env = yield* buildSshChildEnvironment({
+        authSecret: "super-secret",
+        interactiveAuth: true,
+        askpassDirectory: directory,
+        platform: "linux",
+        baseEnv: {},
+      });
+
+      const askpassPath = path.join(directory, "ssh-askpass.sh");
+      assert.equal(env.SSH_ASKPASS, askpassPath);
+      assert.equal(env.SSH_ASKPASS_REQUIRE, "force");
+      assert.equal(env.T3_SSH_AUTH_SECRET, "super-secret");
+      assert.equal(env.DISPLAY, "t3code");
+      assert.equal(yield* fs.exists(askpassPath), true);
+      assert.include(yield* fs.readFileString(askpassPath), 'printf "%s\\n" "$T3_SSH_AUTH_SECRET"');
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
+  );
+
+  it.effect("builds a windows askpass launcher pair", () =>
+    Effect.gen(function* () {
+      const descriptor = yield* buildSshAskpassHelperDescriptor({
+        directory: "C:\\temp\\t3code-ssh-askpass",
+        platform: "win32",
+      }).pipe(Effect.provide(NodeServices.layer));
+
+      assert.equal(descriptor.launcherPath, "C:\\temp\\t3code-ssh-askpass\\ssh-askpass.cmd");
+      assert.deepEqual(
+        descriptor.files.map((file) => file.path.split("\\").at(-1)),
+        ["ssh-askpass.cmd", "ssh-askpass.ps1"],
+      );
+    }),
+  );
 });
diff --git a/packages/ssh/src/auth.ts b/packages/ssh/src/auth.ts
index a961b5b1189..7cb2de11ef5 100644
--- a/packages/ssh/src/auth.ts
+++ b/packages/ssh/src/auth.ts
@@ -1,3 +1,7 @@
+import { Context, Effect, FileSystem, Layer, Path, PlatformError } from "effect";
+
+import { SshPasswordPromptError } from "./errors.ts";
+
 export interface SshPasswordRequest {
   readonly destination: string;
   readonly username: string | null;
@@ -5,6 +9,189 @@ export interface SshPasswordRequest {
   readonly attempt: number;
 }
 
+export interface SshAskpassFile {
+  readonly path: string;
+  readonly contents: string;
+  readonly mode?: number;
+}
+
+export interface SshAskpassHelperDescriptor {
+  readonly launcherPath: string;
+  readonly files: ReadonlyArray<SshAskpassFile>;
+}
+
+export interface SshAuthOptions {
+  readonly authSecret?: string | null;
+  readonly batchMode?: "yes" | "no";
+  readonly interactiveAuth?: boolean;
+}
+
+export interface SshPasswordPromptShape {
+  readonly isAvailable: boolean;
+  readonly request: (
+    request: SshPasswordRequest,
+  ) => Effect.Effect<string | null, SshPasswordPromptError>;
+}
+
+export class SshPasswordPrompt extends Context.Service<SshPasswordPrompt, SshPasswordPromptShape>()(
+  "@t3tools/ssh/SshPasswordPrompt",
+) {
+  static readonly disabledLayer = Layer.succeed(
+    SshPasswordPrompt,
+    SshPasswordPrompt.of({
+      isAvailable: false,
+      request: () => Effect.succeed(null),
+    }),
+  );
+}
+
+export interface SshChildEnvironmentOptions {
+  readonly interactiveAuth?: boolean;
+  readonly baseEnv?: NodeJS.ProcessEnv;
+  readonly askpassDirectory?: string;
+  readonly authSecret?: string | null;
+  readonly platform?: NodeJS.Platform;
+}
+
+const SSH_ASKPASS_DIR_NAME = "t3code-ssh-askpass";
+
+function joinSshAskpassPath(
+  directory: string,
+  fileName: string,
+  platform: NodeJS.Platform,
+): string {
+  const trimmed = directory.replace(/[\\/]+$/u, "");
+  return platform === "win32" ? `${trimmed}\\${fileName}` : `${trimmed}/${fileName}`;
+}
+
+export const ASKPASS_POSIX_SCRIPT = `#!/bin/sh
+# Invoked by ssh via SSH_ASKPASS when T3 Code re-runs ssh with a cached password
+# from the renderer's in-app prompt. We never expose a native dialog here - if
+# T3_SSH_AUTH_SECRET is missing, that's a caller bug and we fail loudly.
+if [ "\${T3_SSH_AUTH_SECRET+x}" = "x" ]; then
+  printf "%s\\n" "$T3_SSH_AUTH_SECRET"
+  exit 0
+fi
+printf 'T3 Code ssh-askpass invoked without T3_SSH_AUTH_SECRET.\\n' >&2
+exit 1
+`;
+
+export const ASKPASS_WINDOWS_LAUNCHER_SCRIPT = `@echo off\r
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0ssh-askpass.ps1" %*\r
+`;
+
+export const ASKPASS_WINDOWS_SCRIPT = `# Invoked by ssh via SSH_ASKPASS (through ssh-askpass.cmd) when T3 Code re-runs\r
+# ssh with a cached password from the renderer's in-app prompt. We never expose\r
+# a native dialog here - if T3_SSH_AUTH_SECRET is missing, that's a caller bug\r
+# and we fail loudly.\r
+if ($null -ne $env:T3_SSH_AUTH_SECRET) {\r
+  [Console]::Out.WriteLine($env:T3_SSH_AUTH_SECRET)\r
+  exit 0\r
+}\r
+[Console]::Error.WriteLine("T3 Code ssh-askpass invoked without T3_SSH_AUTH_SECRET.")\r
+exit 1\r
+`;
+
+export const getDefaultSshAskpassDirectory = Effect.fn("ssh/auth.getDefaultSshAskpassDirectory")(
+  function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const parentDirectory = yield* fs.makeTempDirectory({ prefix: "t3code-ssh-runtime-" });
+    return path.join(parentDirectory, SSH_ASKPASS_DIR_NAME);
+  },
+);
+
+export const buildSshAskpassHelperDescriptor = Effect.fn(
+  "ssh/auth.buildSshAskpassHelperDescriptor",
+)(function* (input: {
+  readonly directory: string;
+  readonly platform?: NodeJS.Platform;
+}): Effect.fn.Return<SshAskpassHelperDescriptor, never, Path.Path> {
+  const platform = input.platform ?? process.platform;
+  const path = yield* Path.Path;
+  const directory = input.directory;
+
+  if (platform === "win32") {
+    const powershellPath = joinSshAskpassPath(directory, "ssh-askpass.ps1", platform);
+    return {
+      launcherPath: joinSshAskpassPath(directory, "ssh-askpass.cmd", platform),
+      files: [
+        {
+          path: joinSshAskpassPath(directory, "ssh-askpass.cmd", platform),
+          contents: ASKPASS_WINDOWS_LAUNCHER_SCRIPT,
+        },
+        {
+          path: powershellPath,
+          contents: ASKPASS_WINDOWS_SCRIPT,
+        },
+      ],
+    };
+  }
+
+  return {
+    launcherPath: path.join(directory, "ssh-askpass.sh"),
+    files: [
+      {
+        path: path.join(directory, "ssh-askpass.sh"),
+        contents: ASKPASS_POSIX_SCRIPT,
+        mode: 0o700,
+      },
+    ],
+  };
+});
+
+export const ensureSshAskpassHelpers = Effect.fn("ssh/auth.ensureSshAskpassHelpers")(
+  function* (input: {
+    readonly directory: string;
+    readonly platform?: NodeJS.Platform;
+  }): Effect.fn.Return<string, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path> {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+    const descriptor = yield* buildSshAskpassHelperDescriptor(input);
+    const platform = input.platform ?? process.platform;
+
+    yield* fs.makeDirectory(path.dirname(descriptor.launcherPath), { recursive: true });
+
+    for (const file of descriptor.files) {
+      const existing = yield* fs.exists(file.path);
+      const current = existing ? yield* fs.readFileString(file.path) : null;
+      if (current !== file.contents) {
+        yield* fs.writeFileString(file.path, file.contents);
+      }
+      if (file.mode !== undefined && platform !== "win32") {
+        yield* fs.chmod(file.path, file.mode);
+      }
+    }
+
+    return descriptor.launcherPath;
+  },
+);
+
+export const buildSshChildEnvironment = Effect.fn("ssh/auth.buildSshChildEnvironment")(function* (
+  input: SshChildEnvironmentOptions = {},
+): Effect.fn.Return<
+  NodeJS.ProcessEnv,
+  PlatformError.PlatformError,
+  FileSystem.FileSystem | Path.Path
+> {
+  const baseEnv = { ...(input.baseEnv ?? process.env) };
+  if (!input.interactiveAuth) {
+    return baseEnv;
+  }
+
+  const platform = input.platform ?? process.platform;
+  const directory = input.askpassDirectory ?? (yield* getDefaultSshAskpassDirectory());
+  const sshAskpass = yield* ensureSshAskpassHelpers({ directory, platform });
+
+  return {
+    ...baseEnv,
+    SSH_ASKPASS: sshAskpass,
+    SSH_ASKPASS_REQUIRE: "force",
+    ...(input.authSecret === undefined ? {} : { T3_SSH_AUTH_SECRET: input.authSecret ?? "" }),
+    ...(platform === "win32" || baseEnv.DISPLAY ? {} : { DISPLAY: "t3code" }),
+  };
+});
+
 export function isSshAuthFailure(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error);
   const normalized = message.toLowerCase();
diff --git a/packages/ssh/src/command.ts b/packages/ssh/src/command.ts
index c73195fcbac..6b8299d0e9a 100644
--- a/packages/ssh/src/command.ts
+++ b/packages/ssh/src/command.ts
@@ -1,9 +1,27 @@
 import * as Crypto from "node:crypto";
 
 import type { DesktopSshEnvironmentTarget, DesktopUpdateChannel } from "@t3tools/contracts";
+import { Effect, FileSystem, Path, Scope, Stream } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import { buildSshChildEnvironment, type SshAuthOptions } from "./auth.ts";
+import { SshCommandError, SshInvalidTargetError } from "./errors.ts";
 
 const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
 
+const encoder = new TextEncoder();
+
+export interface SshCommandResult {
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+export interface RunSshCommandOptions extends SshAuthOptions {
+  readonly preHostArgs?: ReadonlyArray<string>;
+  readonly remoteCommandArgs?: ReadonlyArray<string>;
+  readonly stdin?: string;
+}
+
 export function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
   const values = new Map<string, string>();
   for (const line of stdout.split(/\r?\n/u)) {
@@ -47,6 +65,17 @@ export function buildSshHostSpec(target: DesktopSshEnvironmentTarget): string {
   return target.username ? `${target.username}@${destination}` : destination;
 }
 
+export const buildSshHostSpecEffect = (
+  target: DesktopSshEnvironmentTarget,
+): Effect.Effect<string, SshInvalidTargetError> =>
+  Effect.try({
+    try: () => buildSshHostSpec(target),
+    catch: (cause) =>
+      new SshInvalidTargetError({
+        message: cause instanceof Error ? cause.message : "SSH target is invalid.",
+      }),
+  });
+
 export function baseSshArgs(
   target: DesktopSshEnvironmentTarget,
   input?: { readonly batchMode?: "yes" | "no" },
@@ -70,6 +99,170 @@ export function getLastNonEmptyOutputLine(stdout: string): string | null {
   );
 }
 
+export const collectProcessOutput = <E>(
+  stream: Stream.Stream<Uint8Array, E>,
+): Effect.Effect<string, E> =>
+  stream.pipe(
+    Stream.decodeText(),
+    Stream.runFold(
+      () => "",
+      (acc, chunk) => acc + chunk,
+    ),
+  );
+
+function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
+  const cleaned = stderr.trim();
+  return cleaned.length > 0 ? cleaned : fallbackMessage;
+}
+
+function stdinStream(input: string | undefined) {
+  return input === undefined ? Stream.empty : Stream.make(encoder.encode(input));
+}
+
+const runSshCommandInScope = Effect.fn("ssh/command.runSshCommand.inScope")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input: RunSshCommandOptions,
+  commandScope: Scope.Scope,
+): Effect.fn.Return<
+  SshCommandResult,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  const hostSpec = yield* buildSshHostSpecEffect(target);
+  const environment = yield* buildSshChildEnvironment({
+    ...(input.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+    ...(input.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+  }).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshCommandError({
+          command: ["ssh"],
+          exitCode: null,
+          stderr: "",
+          message: "Failed to prepare SSH authentication helpers.",
+          cause,
+        }),
+    ),
+  );
+  const args = [
+    ...baseSshArgs(target, {
+      batchMode: input.batchMode ?? (input.interactiveAuth ? "no" : "yes"),
+    }),
+    ...(input.preHostArgs ?? []),
+    hostSpec,
+    ...(input.remoteCommandArgs ?? []),
+  ];
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner
+    .spawn(
+      ChildProcess.make("ssh", args, {
+        env: environment,
+        shell: process.platform === "win32",
+        stdin: {
+          stream: stdinStream(input.stdin),
+          endOnDone: true,
+        },
+      }),
+    )
+    .pipe(
+      Effect.provideService(Scope.Scope, commandScope),
+      Effect.mapError(
+        (cause) =>
+          new SshCommandError({
+            command: ["ssh", ...args],
+            exitCode: null,
+            stderr: "",
+            message:
+              cause instanceof Error
+                ? cause.message
+                : `Failed to spawn SSH command for ${hostSpec}.`,
+            cause,
+          }),
+      ),
+    );
+
+  const [stdout, stderr, exitCode] = yield* Effect.all(
+    [
+      collectProcessOutput(child.stdout),
+      collectProcessOutput(child.stderr),
+      child.exitCode.pipe(Effect.map(Number)),
+    ],
+    { concurrency: "unbounded" },
+  ).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshCommandError({
+          command: ["ssh", ...args],
+          exitCode: null,
+          stderr: "",
+          message:
+            cause instanceof Error ? cause.message : `Failed to run SSH command for ${hostSpec}.`,
+          cause,
+        }),
+    ),
+  );
+
+  if (exitCode !== 0) {
+    return yield* new SshCommandError({
+      command: ["ssh", ...args],
+      exitCode,
+      stderr,
+      message: normalizeSshErrorMessage(
+        stderr,
+        `SSH command failed for ${hostSpec} (exit ${exitCode}).`,
+      ),
+    });
+  }
+
+  return { stdout, stderr };
+});
+
+export const runSshCommand = Effect.fn("ssh/command.runSshCommand")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input: RunSshCommandOptions = {},
+): Effect.fn.Return<
+  SshCommandResult,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  return yield* Effect.scopedWith((commandScope) =>
+    runSshCommandInScope(target, input, commandScope),
+  );
+});
+
+export const resolveSshTarget = Effect.fn("ssh/command.resolveSshTarget")(function* (
+  alias: string,
+): Effect.fn.Return<
+  DesktopSshEnvironmentTarget,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  const trimmedAlias = alias.trim();
+  if (trimmedAlias.length === 0) {
+    return yield* new SshInvalidTargetError({ message: "SSH host alias is required." });
+  }
+
+  return yield* runSshCommand(
+    {
+      alias: trimmedAlias,
+      hostname: trimmedAlias,
+      username: null,
+      port: null,
+    },
+    { preHostArgs: ["-G"] },
+  ).pipe(
+    Effect.map((result) => parseSshResolveOutput(trimmedAlias, result.stdout)),
+    Effect.catch(() =>
+      Effect.succeed({
+        alias: trimmedAlias,
+        hostname: trimmedAlias,
+        username: null,
+        port: null,
+      }),
+    ),
+  );
+});
+
 export function resolveRemoteT3CliPackageSpec(input: {
   readonly appVersion: string;
   readonly updateChannel: DesktopUpdateChannel;
diff --git a/packages/ssh/src/config.test.ts b/packages/ssh/src/config.test.ts
index 184d9fb0415..91f8f62c070 100644
--- a/packages/ssh/src/config.test.ts
+++ b/packages/ssh/src/config.test.ts
@@ -1,9 +1,6 @@
-import * as FS from "node:fs";
-import * as OS from "node:os";
-import * as Path from "node:path";
-
+import * as NodeServices from "@effect/platform-node/NodeServices";
 import { assert, describe, it } from "@effect/vitest";
-import { Effect } from "effect";
+import { Effect, FileSystem, Path } from "effect";
 
 import {
   discoverSshHosts,
@@ -11,81 +8,77 @@ import {
   resolveSshConfigIncludePattern,
 } from "./config.ts";
 
-function makeTempHomeDir(): string {
-  return FS.mkdtempSync(Path.join(OS.tmpdir(), "t3-ssh-test-"));
+function makeTempHomeDir() {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    return yield* fs.makeTempDirectoryScoped({ prefix: "t3-ssh-test-" });
+  });
 }
 
 describe("ssh config", () => {
   it.effect("discovers ssh config hosts across included files", () =>
-    Effect.acquireUseRelease(
-      Effect.sync(makeTempHomeDir),
-      (homeDir) =>
-        Effect.gen(function* () {
-          const sshDir = Path.join(homeDir, ".ssh");
-          FS.mkdirSync(Path.join(sshDir, "config.d"), { recursive: true });
-          FS.writeFileSync(
-            Path.join(sshDir, "config"),
-            ["Host devbox", "  HostName devbox.example.com", "Include config.d/*.conf", ""].join(
-              "\n",
-            ),
-            "utf8",
-          );
-          FS.writeFileSync(
-            Path.join(sshDir, "config.d", "team.conf"),
-            [
-              "Host staging",
-              "  HostName staging.example.com",
-              "Host *",
-              "  ServerAliveInterval 30",
-              "",
-            ].join("\n"),
-            "utf8",
-          );
-          FS.writeFileSync(
-            Path.join(sshDir, "known_hosts"),
-            [
-              "known.example.com ssh-ed25519 AAAA",
-              "|1|hashed|entry ssh-ed25519 AAAA",
-              "[bastion.example.com]:2222 ssh-ed25519 AAAA",
-              "",
-            ].join("\n"),
-            "utf8",
-          );
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const homeDir = yield* makeTempHomeDir();
+      const sshDir = path.join(homeDir, ".ssh");
+      yield* fs.makeDirectory(path.join(sshDir, "config.d"), { recursive: true });
+      yield* fs.writeFileString(
+        path.join(sshDir, "config"),
+        ["Host devbox", "  HostName devbox.example.com", "Include config.d/*.conf", ""].join("\n"),
+      );
+      yield* fs.writeFileString(
+        path.join(sshDir, "config.d", "team.conf"),
+        [
+          "Host staging",
+          "  HostName staging.example.com",
+          "Host *",
+          "  ServerAliveInterval 30",
+          "",
+        ].join("\n"),
+      );
+      yield* fs.writeFileString(
+        path.join(sshDir, "known_hosts"),
+        [
+          "known.example.com ssh-ed25519 AAAA",
+          "|1|hashed|entry ssh-ed25519 AAAA",
+          "[bastion.example.com]:2222 ssh-ed25519 AAAA",
+          "",
+        ].join("\n"),
+      );
 
-          const hosts = yield* discoverSshHosts({ homeDir });
-          assert.deepEqual(hosts, [
-            {
-              alias: "bastion.example.com",
-              hostname: "bastion.example.com",
-              username: null,
-              port: null,
-              source: "known-hosts",
-            },
-            {
-              alias: "devbox",
-              hostname: "devbox",
-              username: null,
-              port: null,
-              source: "ssh-config",
-            },
-            {
-              alias: "known.example.com",
-              hostname: "known.example.com",
-              username: null,
-              port: null,
-              source: "known-hosts",
-            },
-            {
-              alias: "staging",
-              hostname: "staging",
-              username: null,
-              port: null,
-              source: "ssh-config",
-            },
-          ]);
-        }),
-      (homeDir) => Effect.sync(() => FS.rmSync(homeDir, { recursive: true, force: true })),
-    ),
+      const hosts = yield* discoverSshHosts({ homeDir });
+      assert.deepEqual(hosts, [
+        {
+          alias: "bastion.example.com",
+          hostname: "bastion.example.com",
+          username: null,
+          port: null,
+          source: "known-hosts",
+        },
+        {
+          alias: "devbox",
+          hostname: "devbox",
+          username: null,
+          port: null,
+          source: "ssh-config",
+        },
+        {
+          alias: "known.example.com",
+          hostname: "known.example.com",
+          username: null,
+          port: null,
+          source: "known-hosts",
+        },
+        {
+          alias: "staging",
+          hostname: "staging",
+          username: null,
+          port: null,
+          source: "ssh-config",
+        },
+      ]);
+    }).pipe(Effect.provide(NodeServices.layer), Effect.scoped),
   );
 
   it.effect("parses known_hosts entries without returning hashed hosts", () =>
@@ -118,11 +111,13 @@ describe("ssh config", () => {
   );
 
   it.effect("expands tilde-prefixed ssh config include patterns", () =>
-    Effect.sync(() => {
-      assert.equal(
-        resolveSshConfigIncludePattern("~/.ssh/config.d/*.conf", "/tmp/project", "/tmp/home"),
-        "/tmp/home/.ssh/config.d/*.conf",
+    Effect.gen(function* () {
+      const pattern = yield* resolveSshConfigIncludePattern(
+        "~/.ssh/config.d/*.conf",
+        "/tmp/project",
+        "/tmp/home",
       );
-    }),
+      assert.equal(pattern, "/tmp/home/.ssh/config.d/*.conf");
+    }).pipe(Effect.provide(NodeServices.layer)),
   );
 });
diff --git a/packages/ssh/src/config.ts b/packages/ssh/src/config.ts
index 17291f481d1..24f29e745ac 100644
--- a/packages/ssh/src/config.ts
+++ b/packages/ssh/src/config.ts
@@ -1,14 +1,10 @@
-import * as FS from "node:fs";
-import * as OS from "node:os";
-import * as Path from "node:path";
-
 import type { DesktopDiscoveredSshHost } from "@t3tools/contracts";
 
-import { Effect } from "effect";
+import { Effect, FileSystem, Path, PlatformError } from "effect";
 
 import { SshHostDiscoveryError } from "./errors.ts";
 
-const NO_HOSTS = [] as const;
+const NO_HOSTS: ReadonlyArray<string> = [] as const;
 
 function stripInlineComment(line: string): string {
   const hashIndex = line.indexOf("#");
@@ -23,20 +19,21 @@ function splitDirectiveArgs(value: string): ReadonlyArray<string> {
     .filter((entry) => entry.length > 0);
 }
 
-function expandHomePath(input: string, homeDir: string = OS.homedir()): string {
+function expandHomePath(input: string, homeDir: string): string {
   return input.replace(/^~(?=$|\/|\\)/u, homeDir);
 }
 
-export function resolveSshConfigIncludePattern(
+export const resolveSshConfigIncludePattern = Effect.fnUntraced(function* (
   includePattern: string,
   _directory: string,
-  homeDir: string = OS.homedir(),
-): string {
+  homeDir: string,
+) {
+  const path = yield* Path.Path;
   const expandedPattern = expandHomePath(includePattern, homeDir);
-  return Path.isAbsolute(expandedPattern)
+  return path.isAbsolute(expandedPattern)
     ? expandedPattern
-    : Path.resolve(Path.join(homeDir, ".ssh"), expandedPattern);
-}
+    : path.resolve(path.join(homeDir, ".ssh"), expandedPattern);
+});
 
 function hasSshPattern(value: string): boolean {
   return value.includes("*") || value.includes("?") || value.startsWith("!");
@@ -53,39 +50,54 @@ function globToRegExp(pattern: string): RegExp {
   );
 }
 
-function expandGlob(pattern: string): ReadonlyArray<string> {
+const expandGlob = Effect.fnUntraced(function* (pattern: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
   if (!pattern.includes("*") && !pattern.includes("?")) {
-    return FS.existsSync(pattern) ? [pattern] : NO_HOSTS;
+    return (yield* fs.exists(pattern)) ? [pattern] : NO_HOSTS;
   }
 
-  const directory = Path.dirname(pattern);
-  const basePattern = Path.basename(pattern);
-  if (!FS.existsSync(directory)) {
+  const directory = path.dirname(pattern);
+  const basePattern = path.basename(pattern);
+  if (!(yield* fs.exists(directory))) {
     return NO_HOSTS;
   }
 
   const matcher = globToRegExp(basePattern);
-  return FS.readdirSync(directory)
-    .filter((entry) => matcher.test(entry))
-    .map((entry) => Path.join(directory, entry))
-    .filter((entry) => FS.existsSync(entry))
-    .toSorted((left, right) => left.localeCompare(right));
-}
+  const entries = yield* fs.readDirectory(directory);
+  const matchedPaths: string[] = [];
+  for (const entry of entries) {
+    if (!matcher.test(entry)) {
+      continue;
+    }
+    const entryPath = path.join(directory, entry);
+    if (yield* fs.exists(entryPath)) {
+      matchedPaths.push(entryPath);
+    }
+  }
+  return matchedPaths.toSorted((left, right) => left.localeCompare(right));
+});
 
-export function collectSshConfigAliasesFromFile(
+export const collectSshConfigAliasesFromFile = Effect.fnUntraced(function* (
   filePath: string,
   visited = new Set<string>(),
-  homeDir: string = OS.homedir(),
-): ReadonlyArray<string> {
-  const resolvedPath = Path.resolve(filePath);
-  if (visited.has(resolvedPath) || !FS.existsSync(resolvedPath)) {
+  homeDir: string,
+): Effect.fn.Return<
+  ReadonlyArray<string>,
+  PlatformError.PlatformError,
+  FileSystem.FileSystem | Path.Path
+> {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const resolvedPath = path.resolve(filePath);
+  if (visited.has(resolvedPath) || !(yield* fs.exists(resolvedPath))) {
     return NO_HOSTS;
   }
   visited.add(resolvedPath);
 
   const aliases = new Set<string>();
-  const directory = Path.dirname(resolvedPath);
-  const raw = FS.readFileSync(resolvedPath, "utf8");
+  const directory = path.dirname(resolvedPath);
+  const raw = yield* fs.readFileString(resolvedPath);
 
   for (const line of raw.split(/\r?\n/u)) {
     const stripped = stripInlineComment(line);
@@ -97,9 +109,19 @@ export function collectSshConfigAliasesFromFile(
     const normalizedDirective = directive.toLowerCase();
     if (normalizedDirective === "include") {
       for (const includePattern of rawArgs) {
-        const resolvedPattern = resolveSshConfigIncludePattern(includePattern, directory, homeDir);
-        for (const includedPath of expandGlob(resolvedPattern)) {
-          for (const alias of collectSshConfigAliasesFromFile(includedPath, visited, homeDir)) {
+        const resolvedPattern = yield* resolveSshConfigIncludePattern(
+          includePattern,
+          directory,
+          homeDir,
+        );
+        const includedPaths = yield* expandGlob(resolvedPattern);
+        for (const includedPath of includedPaths) {
+          const includedAliases = yield* collectSshConfigAliasesFromFile(
+            includedPath,
+            visited,
+            homeDir,
+          );
+          for (const alias of includedAliases) {
             aliases.add(alias);
           }
         }
@@ -120,7 +142,7 @@ export function collectSshConfigAliasesFromFile(
   }
 
   return [...aliases].toSorted((left, right) => left.localeCompare(right));
-}
+});
 
 function normalizeKnownHostsHostname(rawHost: string): string {
   const bracketMatch = /^\[([^\]]+)\]:(\d+)$/u.exec(rawHost);
@@ -166,59 +188,63 @@ export function parseKnownHostsHostnames(raw: string): ReadonlyArray<string> {
   return [...hostnames].toSorted((left, right) => left.localeCompare(right));
 }
 
-function readKnownHostsHostnames(filePath: string): ReadonlyArray<string> {
-  if (!FS.existsSync(filePath)) {
+const readKnownHostsHostnames = Effect.fnUntraced(function* (filePath: string) {
+  const fs = yield* FileSystem.FileSystem;
+  if (!(yield* fs.exists(filePath))) {
     return NO_HOSTS;
   }
+  return parseKnownHostsHostnames(yield* fs.readFileString(filePath));
+});
+
+export const discoverSshHosts = Effect.fnUntraced(
+  function* (input: { readonly homeDir?: string }) {
+    const path = yield* Path.Path;
+    const homeDir = input?.homeDir ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
+    if (homeDir.trim().length === 0) {
+      return [];
+    }
 
-  return parseKnownHostsHostnames(FS.readFileSync(filePath, "utf8"));
-}
-
-export const discoverSshHosts = (input?: {
-  readonly homeDir?: string;
-}): Effect.Effect<readonly DesktopDiscoveredSshHost[], SshHostDiscoveryError> =>
-  Effect.try({
-    try: () => {
-      const homeDir = input?.homeDir ?? OS.homedir();
-      const sshDirectory = Path.join(homeDir, ".ssh");
-      const configAliases = collectSshConfigAliasesFromFile(
-        Path.join(sshDirectory, "config"),
-        new Set<string>(),
-        homeDir,
-      );
-      const knownHosts = readKnownHostsHostnames(Path.join(sshDirectory, "known_hosts"));
-      const discovered = new Map<string, DesktopDiscoveredSshHost>();
-
-      for (const alias of configAliases) {
-        discovered.set(alias, {
-          alias,
-          hostname: alias,
-          username: null,
-          port: null,
-          source: "ssh-config",
-        });
-      }
+    const sshDirectory = path.join(homeDir, ".ssh");
+    const configAliases = yield* collectSshConfigAliasesFromFile(
+      path.join(sshDirectory, "config"),
+      new Set<string>(),
+      homeDir,
+    );
+    const knownHosts = yield* readKnownHostsHostnames(path.join(sshDirectory, "known_hosts"));
+    const discovered = new Map<string, DesktopDiscoveredSshHost>();
+
+    for (const alias of configAliases) {
+      discovered.set(alias, {
+        alias,
+        hostname: alias,
+        username: null,
+        port: null,
+        source: "ssh-config",
+      });
+    }
 
-      for (const hostname of knownHosts) {
-        if (discovered.has(hostname)) {
-          continue;
-        }
-        discovered.set(hostname, {
-          alias: hostname,
-          hostname,
-          username: null,
-          port: null,
-          source: "known-hosts",
-        });
+    for (const hostname of knownHosts) {
+      if (discovered.has(hostname)) {
+        continue;
       }
+      discovered.set(hostname, {
+        alias: hostname,
+        hostname,
+        username: null,
+        port: null,
+        source: "known-hosts",
+      });
+    }
 
-      return [...discovered.values()].toSorted((left, right) =>
-        left.alias.localeCompare(right.alias),
-      );
-    },
-    catch: (cause) =>
+    return [...discovered.values()].toSorted((left, right) =>
+      left.alias.localeCompare(right.alias),
+    );
+  },
+  Effect.mapError(
+    (cause) =>
       new SshHostDiscoveryError({
         message: "Failed to discover SSH hosts.",
         cause,
       }),
-  });
+  ),
+);
diff --git a/packages/ssh/src/errors.ts b/packages/ssh/src/errors.ts
index 0eab86f7104..b902ef82721 100644
--- a/packages/ssh/src/errors.ts
+++ b/packages/ssh/src/errors.ts
@@ -4,3 +4,43 @@ export class SshHostDiscoveryError extends Data.TaggedError("SshHostDiscoveryErr
   readonly message: string;
   readonly cause: unknown;
 }> {}
+
+export class SshInvalidTargetError extends Data.TaggedError("SshInvalidTargetError")<{
+  readonly message: string;
+}> {}
+
+export class SshCommandError extends Data.TaggedError("SshCommandError")<{
+  readonly message: string;
+  readonly command: readonly string[];
+  readonly exitCode: number | null;
+  readonly stderr: string;
+  readonly cause?: unknown;
+}> {}
+
+export class SshLaunchError extends Data.TaggedError("SshLaunchError")<{
+  readonly message: string;
+  readonly stdout: string;
+  readonly cause?: unknown;
+}> {}
+
+export class SshPairingError extends Data.TaggedError("SshPairingError")<{
+  readonly message: string;
+  readonly stdout: string;
+  readonly cause?: unknown;
+}> {}
+
+export class SshHttpBridgeError extends Data.TaggedError("SshHttpBridgeError")<{
+  readonly message: string;
+  readonly status?: number;
+  readonly cause?: unknown;
+}> {}
+
+export class SshReadinessError extends Data.TaggedError("SshReadinessError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+export class SshPasswordPromptError extends Data.TaggedError("SshPasswordPromptError")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
diff --git a/packages/ssh/src/index.ts b/packages/ssh/src/index.ts
deleted file mode 100644
index 9b208f0ddaa..00000000000
--- a/packages/ssh/src/index.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-export * from "./auth.ts";
-export * from "./command.ts";
-export * from "./config.ts";
-export * from "./errors.ts";
-export * from "./tunnel.ts";
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
new file mode 100644
index 00000000000..796306dc2f7
--- /dev/null
+++ b/packages/ssh/src/tunnel.test.ts
@@ -0,0 +1,44 @@
+import { assert, describe, it } from "@effect/vitest";
+
+import {
+  buildRemoteLaunchScript,
+  buildRemotePairingScript,
+  buildRemoteT3RunnerScript,
+  REMOTE_PICK_PORT_SCRIPT,
+} from "./tunnel.ts";
+
+describe("ssh tunnel scripts", () => {
+  it("builds the remote t3 runner with npx and npm fallbacks", () => {
+    const script = buildRemoteT3RunnerScript();
+
+    assert.include(script, 'exec t3 "$@"');
+    assert.include(script, 'exec npx --yes t3@latest "$@"');
+    assert.include(script, 'exec npm exec --yes t3@latest -- "$@"');
+    assert.include(script, "could not install t3@latest");
+  });
+
+  it("uses the remote t3 runner for launch and pairing scripts", () => {
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+
+    assert.include(
+      buildRemoteLaunchScript(),
+      '[ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null',
+    );
+    assert.include(buildRemoteLaunchScript(), '"$RUNNER_FILE" serve --host 127.0.0.1');
+    assert.include(buildRemoteLaunchScript({ packageSpec: "t3@nightly" }), "t3@nightly");
+    assert.include(
+      buildRemotePairingScript(target),
+      '"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json',
+    );
+    assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
+  });
+
+  it("allows the remote port picker to run without a state file path", () => {
+    assert.include(REMOTE_PICK_PORT_SCRIPT, 'const filePath = process.argv[2] ?? "";');
+  });
+});
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 81d8cbc8add..64c1e2f6231 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -1,6 +1,857 @@
+import type {
+  DesktopSshEnvironmentBootstrap,
+  DesktopSshEnvironmentTarget,
+} from "@t3tools/contracts";
+import { type NetError, NetService } from "@t3tools/shared/Net";
+import {
+  Deferred,
+  Context,
+  Duration,
+  Effect,
+  Exit,
+  FileSystem,
+  Layer,
+  Path,
+  Schema,
+  Scope,
+  Schedule,
+} from "effect";
+import { HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+
+import {
+  buildSshChildEnvironment,
+  type SshAuthOptions,
+  SshPasswordPrompt,
+  isSshAuthFailure,
+} from "./auth.ts";
+import {
+  baseSshArgs,
+  buildSshHostSpecEffect,
+  collectProcessOutput,
+  getLastNonEmptyOutputLine,
+  remoteStateKey,
+  resolveSshTarget,
+  runSshCommand,
+  targetConnectionKey,
+} from "./command.ts";
+import {
+  SshCommandError,
+  SshHttpBridgeError,
+  SshInvalidTargetError,
+  SshLaunchError,
+  SshPairingError,
+  SshPasswordPromptError,
+  SshReadinessError,
+} from "./errors.ts";
+
 export const DEFAULT_REMOTE_PORT = 3773;
+const REMOTE_PORT_SCAN_WINDOW = 200;
+const SSH_READY_TIMEOUT_MS = 20_000;
+const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
+
+export interface SshEnvironmentManagerOptions {
+  readonly resolveCliPackageSpec?: () => string;
+}
+
+interface SshTunnelEntry {
+  readonly key: string;
+  readonly target: DesktopSshEnvironmentTarget;
+  readonly remotePort: number;
+  readonly localPort: number;
+  readonly httpBaseUrl: string;
+  readonly wsBaseUrl: string;
+  readonly process: ChildProcessSpawner.ChildProcessHandle;
+}
+
+type SshEnvironmentEffectContext =
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | Path.Path
+  | HttpClient.HttpClient
+  | NetService
+  | SshPasswordPrompt;
+
+type SshEnvironmentEffectError =
+  | SshCommandError
+  | SshInvalidTargetError
+  | SshLaunchError
+  | SshPairingError
+  | SshReadinessError
+  | SshPasswordPromptError
+  | NetError;
+
+interface SshAuthOperationInput<T> {
+  readonly key: string;
+  readonly target: DesktopSshEnvironmentTarget;
+  readonly operation: (
+    authOptions: SshAuthOptions,
+  ) => Effect.Effect<T, SshEnvironmentEffectError, SshEnvironmentEffectContext>;
+}
+
+interface SshAuthAttemptInput<T> extends SshAuthOperationInput<T> {
+  readonly promptCount: number;
+  readonly authSecret: string | null;
+}
+
+export interface SshEnvironmentManagerShape {
+  readonly ensureEnvironment: (
+    target: DesktopSshEnvironmentTarget,
+    options?: { readonly issuePairingToken?: boolean },
+  ) => Effect.Effect<
+    DesktopSshEnvironmentBootstrap,
+    SshEnvironmentEffectError,
+    SshEnvironmentEffectContext
+  >;
+}
+
+const RemoteLaunchResult = Schema.Struct({
+  remotePort: Schema.Number,
+});
+
+const RemotePairingResult = Schema.Struct({
+  credential: Schema.String,
+});
+
+const RemoteHttpError = Schema.Struct({
+  error: Schema.optional(Schema.String),
+});
+
+const decodeRemoteLaunchResult = Schema.decodeEffect(Schema.fromJsonString(RemoteLaunchResult));
+const decodeRemotePairingResult = Schema.decodeEffect(Schema.fromJsonString(RemotePairingResult));
+const decodeRemoteHttpError = Schema.decodeEffect(Schema.fromJsonString(RemoteHttpError));
 
 export function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
   const cleaned = stderr.trim();
   return cleaned.length > 0 ? cleaned : fallbackMessage;
 }
+
+function stripTrailingNewlines(value: string): string {
+  return value.replace(/\n+$/u, "");
+}
+
+function applyScriptPlaceholders(
+  template: string,
+  replacements: Readonly<Record<string, string>>,
+): string {
+  let result = template;
+  for (const [token, value] of Object.entries(replacements)) {
+    result = result.replaceAll(`@@${token}@@`, value);
+  }
+  return result;
+}
+
+export const REMOTE_PICK_PORT_SCRIPT = `const fs = require("node:fs");
+const net = require("node:net");
+const filePath = process.argv[2] ?? "";
+const defaultPort = Number.parseInt(process.argv[3] ?? "", 10);
+const scanWindow = Number.parseInt(process.argv[4] ?? "", 10);
+const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8").trim() : "";
+const preferred = Number.parseInt(raw, 10);
+const start = Number.isInteger(preferred) ? preferred : defaultPort;
+const end = start + scanWindow;
+
+function tryPort(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.unref();
+    server.once("error", () => resolve(false));
+    server.listen(port, "127.0.0.1", () => {
+      server.close((error) => resolve(error ? false : port));
+    });
+  });
+}
+
+(async () => {
+  for (let port = start; port < end; port += 1) {
+    const available = await tryPort(port);
+    if (available) {
+      process.stdout.write(String(port));
+      return;
+    }
+  }
+  process.exit(1);
+})().catch(() => process.exit(1));
+`;
+
+export const REMOTE_RUNNER_SCRIPT = `#!/bin/sh
+set -eu
+if command -v t3 >/dev/null 2>&1; then
+  exec t3 "$@"
+fi
+if command -v npx >/dev/null 2>&1; then
+  exec npx --yes @@T3_PACKAGE_SPEC@@ "$@"
+fi
+if command -v npm >/dev/null 2>&1; then
+  exec npm exec --yes @@T3_PACKAGE_SPEC@@ -- "$@"
+fi
+printf 'Remote host is missing the t3 CLI and could not install @@T3_PACKAGE_SPEC@@ because npx and npm are unavailable on PATH.\\n' >&2
+exit 1
+`;
+
+export const REMOTE_LAUNCH_SCRIPT = `set -eu
+STATE_KEY="$1"
+STATE_DIR="$HOME/.t3/ssh-launch/$STATE_KEY"
+SERVER_HOME="$STATE_DIR/server-home"
+PORT_FILE="$STATE_DIR/port"
+PID_FILE="$STATE_DIR/pid"
+LOG_FILE="$STATE_DIR/server.log"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+mkdir -p "$STATE_DIR" "$SERVER_HOME"
+cat >"$RUNNER_FILE" <<'SH'
+@@T3_RUNNER_SCRIPT@@
+SH
+chmod 700 "$RUNNER_FILE"
+pick_port() {
+  node - "$PORT_FILE" "@@T3_DEFAULT_REMOTE_PORT@@" "@@T3_REMOTE_PORT_SCAN_WINDOW@@" <<'NODE'
+@@T3_PICK_PORT_SCRIPT@@
+NODE
+}
+REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
+if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+  :
+else
+  REMOTE_PORT="$(pick_port)" || true
+  if [ -z "$REMOTE_PORT" ]; then
+    printf 'Failed to find an available port on the remote host. Ensure node is available on PATH.\\n' >&2
+    exit 1
+  fi
+  nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
+  REMOTE_PID="$!"
+  printf '%s\\n' "$REMOTE_PID" >"$PID_FILE"
+  printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+fi
+printf '{"remotePort":%s}\\n' "$REMOTE_PORT"
+`;
+
+export const REMOTE_PAIRING_SCRIPT = `set -eu
+STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
+SERVER_HOME="$STATE_DIR/server-home"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+mkdir -p "$STATE_DIR" "$SERVER_HOME"
+cat >"$RUNNER_FILE" <<'SH'
+@@T3_RUNNER_SCRIPT@@
+SH
+chmod 700 "$RUNNER_FILE"
+"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json
+`;
+
+export function buildRemoteT3RunnerScript(input?: { readonly packageSpec?: string }): string {
+  const packageSpec = input?.packageSpec?.trim() || "t3@latest";
+  return stripTrailingNewlines(
+    applyScriptPlaceholders(REMOTE_RUNNER_SCRIPT, {
+      T3_PACKAGE_SPEC: packageSpec,
+    }),
+  );
+}
+
+export function buildRemoteLaunchScript(input?: { readonly packageSpec?: string }): string {
+  return applyScriptPlaceholders(REMOTE_LAUNCH_SCRIPT, {
+    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
+    T3_PICK_PORT_SCRIPT: stripTrailingNewlines(REMOTE_PICK_PORT_SCRIPT),
+    T3_DEFAULT_REMOTE_PORT: String(DEFAULT_REMOTE_PORT),
+    T3_REMOTE_PORT_SCAN_WINDOW: String(REMOTE_PORT_SCAN_WINDOW),
+  });
+}
+
+export function buildRemotePairingScript(
+  target: DesktopSshEnvironmentTarget,
+  input?: { readonly packageSpec?: string },
+): string {
+  return applyScriptPlaceholders(REMOTE_PAIRING_SCRIPT, {
+    T3_STATE_KEY: remoteStateKey(target),
+    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
+  });
+}
+
+export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemoteServer")(
+  function* (
+    target: DesktopSshEnvironmentTarget,
+    input?: SshAuthOptions,
+    runner?: { readonly packageSpec?: string },
+  ): Effect.fn.Return<
+    number,
+    SshCommandError | SshInvalidTargetError | SshLaunchError,
+    ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+  > {
+    const result = yield* runSshCommand(target, {
+      remoteCommandArgs: ["sh", "-s", "--", remoteStateKey(target)],
+      stdin: buildRemoteLaunchScript(runner),
+      ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+      ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+      ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+    });
+    const line = getLastNonEmptyOutputLine(result.stdout);
+    if (!line) {
+      return yield* new SshLaunchError({
+        message: "SSH launch did not return a remote port.",
+        stdout: result.stdout,
+      });
+    }
+    const parsed = yield* decodeRemoteLaunchResult(line).pipe(
+      Effect.mapError(
+        (cause) =>
+          new SshLaunchError({
+            message: "SSH launch returned unparseable output.",
+            stdout: result.stdout,
+            cause,
+          }),
+      ),
+    );
+    if (!Number.isInteger(parsed.remotePort)) {
+      return yield* new SshLaunchError({
+        message: `SSH launch returned an invalid remote port: ${String(parsed.remotePort)}.`,
+        stdout: result.stdout,
+      });
+    }
+    return parsed.remotePort;
+  },
+);
+
+export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingToken")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input?: SshAuthOptions,
+  runner?: { readonly packageSpec?: string },
+): Effect.fn.Return<
+  string,
+  SshCommandError | SshInvalidTargetError | SshPairingError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  const result = yield* runSshCommand(target, {
+    remoteCommandArgs: ["sh", "-s"],
+    stdin: buildRemotePairingScript(target, runner),
+    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+  });
+  const line = getLastNonEmptyOutputLine(result.stdout);
+  if (!line) {
+    return yield* new SshPairingError({
+      message: "SSH pairing did not return a credential.",
+      stdout: result.stdout,
+    });
+  }
+  const parsed = yield* decodeRemotePairingResult(line).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshPairingError({
+          message: "SSH pairing returned unparseable output.",
+          stdout: result.stdout,
+          cause,
+        }),
+    ),
+  );
+  if (parsed.credential.trim().length === 0) {
+    return yield* new SshPairingError({
+      message: "SSH pairing command returned an invalid credential.",
+      stdout: result.stdout,
+    });
+  }
+  return parsed.credential;
+});
+
+export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(function* (input: {
+  readonly baseUrl: string;
+  readonly timeoutMs?: number;
+  readonly intervalMs?: number;
+  readonly path?: string;
+}): Effect.fn.Return<void, SshReadinessError, HttpClient.HttpClient> {
+  const timeoutMs = input.timeoutMs ?? 30_000;
+  const intervalMs = input.intervalMs ?? 100;
+  const maxRetries = Math.max(0, Math.ceil(timeoutMs / intervalMs));
+  const requestUrl = new URL(input.path ?? "/", input.baseUrl).toString();
+  const client = (yield* HttpClient.HttpClient).pipe(
+    HttpClient.filterStatusOk,
+    HttpClient.retry({
+      schedule: Schedule.spaced(Duration.millis(intervalMs)),
+      times: maxRetries,
+    }),
+  );
+
+  yield* client.execute(HttpClientRequest.get(requestUrl)).pipe(
+    Effect.asVoid,
+    Effect.mapError(
+      (cause) =>
+        new SshReadinessError({
+          message: `Timed out waiting for backend readiness at ${input.baseUrl}.`,
+          cause,
+        }),
+    ),
+  );
+});
+
+function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname
+    .trim()
+    .toLowerCase()
+    .replace(/^\[(.*)\]$/, "$1");
+  return normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost";
+}
+
+function resolveLoopbackSshHttpUrl(
+  rawHttpBaseUrl: unknown,
+  pathname: string,
+): Effect.Effect<URL, SshHttpBridgeError> {
+  return Effect.try({
+    try: () => {
+      if (typeof rawHttpBaseUrl !== "string" || rawHttpBaseUrl.trim().length === 0) {
+        throw new Error("Invalid SSH forwarded http base URL.");
+      }
+      const baseUrl = new URL(rawHttpBaseUrl);
+      if (!isLoopbackHostname(baseUrl.hostname)) {
+        throw new Error("SSH desktop bridge only supports loopback forwarded URLs.");
+      }
+      const url = new URL(baseUrl.toString());
+      url.pathname = pathname;
+      url.search = "";
+      url.hash = "";
+      return url;
+    },
+    catch: (cause) =>
+      new SshHttpBridgeError({
+        message: cause instanceof Error ? cause.message : "Invalid SSH forwarded http base URL.",
+        cause,
+      }),
+  });
+}
+
+export const fetchLoopbackSshJson = Effect.fn("ssh/tunnel.fetchLoopbackSshJson")(function* <
+  T,
+>(input: {
+  readonly httpBaseUrl: unknown;
+  readonly pathname: string;
+  readonly method?: "GET" | "POST";
+  readonly bearerToken?: unknown;
+  readonly body?: unknown;
+}): Effect.fn.Return<T, SshHttpBridgeError, HttpClient.HttpClient> {
+  const requestUrl = yield* resolveLoopbackSshHttpUrl(input.httpBaseUrl, input.pathname);
+  const bearerToken =
+    typeof input.bearerToken === "string" && input.bearerToken.trim().length > 0
+      ? input.bearerToken
+      : null;
+
+  const request = (
+    input.method === "POST"
+      ? HttpClientRequest.post(requestUrl.toString())
+      : HttpClientRequest.get(requestUrl.toString())
+  ).pipe(
+    input.body === undefined ? (req) => req : HttpClientRequest.bodyJsonUnsafe(input.body),
+    bearerToken
+      ? HttpClientRequest.setHeader("authorization", `Bearer ${bearerToken}`)
+      : (req) => req,
+  );
+  const client = yield* HttpClient.HttpClient;
+  const response = yield* client.execute(request).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshHttpBridgeError({
+          message: `Failed to reach SSH forwarded endpoint ${requestUrl.toString()}.`,
+          cause,
+        }),
+    ),
+  );
+  if (response.status < 200 || response.status >= 300) {
+    const text = yield* response.text.pipe(Effect.catch(() => Effect.succeed("")));
+    const parsedError = yield* decodeRemoteHttpError(text).pipe(
+      Effect.catch(() => Effect.succeed(null)),
+    );
+    const message =
+      parsedError?.error && parsedError.error.trim().length > 0
+        ? parsedError.error
+        : text || `SSH forwarded request failed (${response.status}).`;
+    return yield* new SshHttpBridgeError({
+      status: response.status,
+      message: `[ssh_http:${response.status}] ${message}`,
+    });
+  }
+  return (yield* response.json.pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshHttpBridgeError({
+          message: `SSH forwarded endpoint ${requestUrl.toString()} returned invalid JSON.`,
+          cause,
+        }),
+    ),
+  )) as T;
+});
+
+const reserveLocalTunnelPort = Effect.fn("ssh/tunnel.reserveLocalTunnelPort")(function* () {
+  const net = yield* NetService;
+  return yield* net.reserveLoopbackPort();
+});
+
+const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input: {
+  readonly key: string;
+  readonly resolvedTarget: DesktopSshEnvironmentTarget;
+  readonly remotePort: number;
+  readonly localPort: number;
+  readonly httpBaseUrl: string;
+  readonly wsBaseUrl: string;
+  readonly authOptions: SshAuthOptions;
+}): Effect.fn.Return<
+  SshTunnelEntry,
+  SshCommandError | SshInvalidTargetError | SshReadinessError,
+  | ChildProcessSpawner.ChildProcessSpawner
+  | FileSystem.FileSystem
+  | Path.Path
+  | HttpClient.HttpClient
+  | Scope.Scope
+> {
+  const hostSpec = yield* buildSshHostSpecEffect(input.resolvedTarget);
+  const childEnvironment = yield* buildSshChildEnvironment({
+    ...(input.authOptions.authSecret === undefined
+      ? {}
+      : { authSecret: input.authOptions.authSecret }),
+    ...(input.authOptions.interactiveAuth === undefined
+      ? {}
+      : { interactiveAuth: input.authOptions.interactiveAuth }),
+  }).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshCommandError({
+          command: ["ssh"],
+          exitCode: null,
+          stderr: "",
+          message: "Failed to prepare SSH authentication helpers.",
+          cause,
+        }),
+    ),
+  );
+  const args = [
+    ...baseSshArgs(input.resolvedTarget, {
+      batchMode: input.authOptions.batchMode ?? "no",
+    }),
+    "-o",
+    "ExitOnForwardFailure=yes",
+    "-o",
+    "ServerAliveInterval=15",
+    "-o",
+    "ServerAliveCountMax=3",
+    "-N",
+    "-L",
+    `${input.localPort}:127.0.0.1:${input.remotePort}`,
+    hostSpec,
+  ];
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const child = yield* spawner
+    .spawn(
+      ChildProcess.make("ssh", args, {
+        env: childEnvironment,
+        shell: process.platform === "win32",
+      }),
+    )
+    .pipe(
+      Effect.mapError(
+        (cause) =>
+          new SshCommandError({
+            command: ["ssh", ...args],
+            exitCode: null,
+            stderr: "",
+            message:
+              cause instanceof Error
+                ? cause.message
+                : `Failed to spawn SSH tunnel for ${input.resolvedTarget.alias}.`,
+            cause,
+          }),
+      ),
+    );
+  const tunnelEntry: SshTunnelEntry = {
+    key: input.key,
+    target: input.resolvedTarget,
+    remotePort: input.remotePort,
+    localPort: input.localPort,
+    httpBaseUrl: input.httpBaseUrl,
+    wsBaseUrl: input.wsBaseUrl,
+    process: child,
+  };
+  const exitFailure = Effect.all(
+    [collectProcessOutput(child.stderr), child.exitCode.pipe(Effect.map(Number))],
+    { concurrency: "unbounded" },
+  ).pipe(
+    Effect.mapError(
+      (cause) =>
+        new SshCommandError({
+          command: ["ssh", ...args],
+          exitCode: null,
+          stderr: "",
+          message:
+            cause instanceof Error
+              ? cause.message
+              : `Failed to monitor SSH tunnel for ${input.resolvedTarget.alias}.`,
+          cause,
+        }),
+    ),
+    Effect.flatMap(([stderr, exitCode]) =>
+      Effect.fail(
+        new SshCommandError({
+          command: ["ssh", ...args],
+          exitCode,
+          stderr,
+          message: normalizeSshErrorMessage(
+            stderr,
+            `SSH tunnel exited unexpectedly for ${input.resolvedTarget.alias} (exit ${exitCode}).`,
+          ),
+        }),
+      ),
+    ),
+  );
+  yield* Effect.raceFirst(
+    waitForHttpReady({
+      baseUrl: input.httpBaseUrl,
+      timeoutMs: SSH_READY_TIMEOUT_MS,
+    }),
+    exitFailure,
+  ).pipe(
+    Effect.onExit((exit) =>
+      Exit.isSuccess(exit)
+        ? Effect.void
+        : child
+            .kill({
+              killSignal: "SIGTERM",
+              forceKillAfter: TUNNEL_SHUTDOWN_TIMEOUT_MS,
+            })
+            .pipe(Effect.ignore),
+    ),
+  );
+  return tunnelEntry;
+});
+
+const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.make")(function* (
+  options: SshEnvironmentManagerOptions = {},
+): Effect.fn.Return<SshEnvironmentManagerShape, never, Scope.Scope> {
+  const tunnelScope = yield* Scope.Scope;
+  const tunnels = new Map<string, SshTunnelEntry>();
+  const pendingTunnelEntries = new Map<
+    string,
+    Deferred.Deferred<SshTunnelEntry, SshEnvironmentEffectError>
+  >();
+  const authSecrets = new Map<string, string>();
+
+  const deleteTunnelIfCurrent = (entry: SshTunnelEntry): void => {
+    if (tunnels.get(entry.key) === entry) {
+      tunnels.delete(entry.key);
+    }
+  };
+
+  const promptForPassword = Effect.fn("ssh/tunnel.promptForPassword")(function* (
+    target: DesktopSshEnvironmentTarget,
+    attempt: number,
+  ): Effect.fn.Return<string, SshInvalidTargetError | SshPasswordPromptError, SshPasswordPrompt> {
+    const promptService = yield* SshPasswordPrompt;
+    const hostSpec = yield* buildSshHostSpecEffect(target);
+    if (!promptService.isAvailable) {
+      return yield* new SshPasswordPromptError({
+        message: `SSH authentication failed for ${hostSpec}.`,
+      });
+    }
+
+    const password = yield* promptService.request({
+      attempt,
+      destination: target.alias.trim() || target.hostname.trim(),
+      username: target.username,
+      prompt: `Enter the SSH password for ${hostSpec}.`,
+    });
+    if (password === null) {
+      return yield* new SshPasswordPromptError({
+        message: `SSH authentication cancelled for ${hostSpec}.`,
+      });
+    }
+    return password;
+  });
+
+  const handleSshAuthFailure = Effect.fn("ssh/tunnel.runWithSshAuthAttempt.handleFailure")(
+    function* <T>(
+      input: SshAuthAttemptInput<T> & {
+        readonly error: SshEnvironmentEffectError;
+      },
+    ): Effect.fn.Return<T, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+      if (!isSshAuthFailure(input.error)) {
+        return yield* input.error;
+      }
+
+      const promptService = yield* SshPasswordPrompt;
+      if (!promptService.isAvailable) {
+        return yield* input.error;
+      }
+      if (input.authSecret !== null) {
+        authSecrets.delete(input.key);
+      }
+      if (input.promptCount >= 2) {
+        return yield* input.error;
+      }
+
+      const nextPromptCount = input.promptCount + 1;
+      const nextAuthSecret = yield* promptForPassword(input.target, nextPromptCount);
+      authSecrets.set(input.key, nextAuthSecret);
+      return yield* runWithSshAuthAttempt({
+        ...input,
+        promptCount: nextPromptCount,
+        authSecret: nextAuthSecret,
+      });
+    },
+  );
+
+  const runWithSshAuthAttempt = Effect.fn("ssh/tunnel.runWithSshAuthAttempt")(function* <T>(
+    input: SshAuthAttemptInput<T>,
+  ): Effect.fn.Return<T, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    const promptService = yield* SshPasswordPrompt;
+    const authOptions =
+      input.authSecret === null
+        ? {
+            batchMode: promptService.isAvailable ? ("yes" as const) : ("no" as const),
+            interactiveAuth: !promptService.isAvailable,
+          }
+        : {
+            authSecret: input.authSecret,
+            batchMode: "no" as const,
+            interactiveAuth: true,
+          };
+
+    return yield* input
+      .operation(authOptions)
+      .pipe(Effect.catch((error) => handleSshAuthFailure({ ...input, error })));
+  });
+
+  const runWithSshAuth = Effect.fn("ssh/tunnel.runWithSshAuth")(function* <T>(
+    input: SshAuthOperationInput<T>,
+  ): Effect.fn.Return<T, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    return yield* runWithSshAuthAttempt({
+      ...input,
+      promptCount: 0,
+      authSecret: authSecrets.get(input.key) ?? null,
+    });
+  });
+
+  const createTunnelEntry = Effect.fn("ssh/tunnel.ensureTunnelEntry.create")(function* (input: {
+    readonly key: string;
+    readonly resolvedTarget: DesktopSshEnvironmentTarget;
+    readonly packageSpec?: string;
+  }): Effect.fn.Return<SshTunnelEntry, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    const remotePort = yield* runWithSshAuth({
+      key: input.key,
+      target: input.resolvedTarget,
+      operation: (authOptions) =>
+        launchOrReuseRemoteServer(
+          input.resolvedTarget,
+          authOptions,
+          input.packageSpec === undefined ? undefined : { packageSpec: input.packageSpec },
+        ),
+    });
+    const localPort = yield* reserveLocalTunnelPort();
+    const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
+    const wsBaseUrl = `ws://127.0.0.1:${localPort}/`;
+    const tunnelEntry = yield* runWithSshAuth({
+      key: input.key,
+      target: input.resolvedTarget,
+      operation: (authOptions) =>
+        startSshTunnel({
+          key: input.key,
+          resolvedTarget: input.resolvedTarget,
+          remotePort,
+          localPort,
+          httpBaseUrl,
+          wsBaseUrl,
+          authOptions,
+        }).pipe(Effect.provideService(Scope.Scope, tunnelScope)),
+    });
+    tunnels.set(input.key, tunnelEntry);
+    return tunnelEntry;
+  });
+
+  const ensureTunnelEntry = Effect.fn("ssh/tunnel.ensureTunnelEntry")(function* (
+    key: string,
+    resolvedTarget: DesktopSshEnvironmentTarget,
+    packageSpec?: string,
+  ): Effect.fn.Return<SshTunnelEntry, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    let entry = tunnels.get(key) ?? null;
+
+    if (entry !== null) {
+      const readinessExit = yield* Effect.exit(
+        waitForHttpReady({ baseUrl: entry.httpBaseUrl, timeoutMs: 2_000 }),
+      );
+      if (Exit.isSuccess(readinessExit)) {
+        return entry;
+      }
+      yield* entry.process
+        .kill({
+          killSignal: "SIGTERM",
+          forceKillAfter: TUNNEL_SHUTDOWN_TIMEOUT_MS,
+        })
+        .pipe(Effect.ignore);
+      deleteTunnelIfCurrent(entry);
+      entry = null;
+    }
+
+    const pending = pendingTunnelEntries.get(key);
+    if (pending) {
+      return yield* Deferred.await(pending);
+    }
+
+    const deferred = yield* Deferred.make<SshTunnelEntry, SshEnvironmentEffectError>();
+    pendingTunnelEntries.set(key, deferred);
+
+    return yield* createTunnelEntry({
+      key,
+      resolvedTarget,
+      ...(packageSpec === undefined ? {} : { packageSpec }),
+    }).pipe(
+      Effect.onExit((exit) =>
+        Effect.sync(() => {
+          if (pendingTunnelEntries.get(key) === deferred) {
+            pendingTunnelEntries.delete(key);
+          }
+        }).pipe(Effect.andThen(Deferred.done(deferred, exit))),
+      ),
+    );
+  });
+
+  const ensureEnvironment = Effect.fn("ssh/tunnel.ensureEnvironment")(function* (
+    target: DesktopSshEnvironmentTarget,
+    requestOptions?: { readonly issuePairingToken?: boolean },
+  ): Effect.fn.Return<
+    DesktopSshEnvironmentBootstrap,
+    SshEnvironmentEffectError,
+    SshEnvironmentEffectContext
+  > {
+    const baseResolved = yield* resolveSshTarget(target.alias || target.hostname);
+    const resolvedTarget: DesktopSshEnvironmentTarget = {
+      ...baseResolved,
+      ...(target.username !== null ? { username: target.username } : {}),
+      ...(target.port !== null ? { port: target.port } : {}),
+    };
+    const key = targetConnectionKey(resolvedTarget);
+    const packageSpec = options.resolveCliPackageSpec?.();
+    const entry = yield* ensureTunnelEntry(key, resolvedTarget, packageSpec);
+
+    const pairingToken = requestOptions?.issuePairingToken
+      ? yield* runWithSshAuth({
+          key,
+          target: entry.target,
+          operation: (authOptions) =>
+            issueRemotePairingToken(
+              entry.target,
+              authOptions,
+              packageSpec === undefined ? undefined : { packageSpec },
+            ),
+        })
+      : null;
+
+    return {
+      target: entry.target,
+      httpBaseUrl: entry.httpBaseUrl,
+      wsBaseUrl: entry.wsBaseUrl,
+      pairingToken,
+    };
+  });
+
+  return SshEnvironmentManager.of({ ensureEnvironment });
+});
+
+export class SshEnvironmentManager extends Context.Service<
+  SshEnvironmentManager,
+  SshEnvironmentManagerShape
+>()("@t3tools/ssh/SshEnvironmentManager") {
+  static readonly layer = (options: SshEnvironmentManagerOptions = {}) =>
+    Layer.effect(SshEnvironmentManager, makeSshEnvironmentManager(options));
+}

From 7b50a39125fd7933ca948514f01079ba8b83b3d7 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 28 Apr 2026 21:13:31 -0700
Subject: [PATCH 38/74] Refine hosted pairing and SSH connection flows

- Simplify add-environment dialog around remote and SSH pairing
- Auto-detect pairing URLs and improve SSH prompt handling
- Add coverage for tunnel and connection parsing behavior
---
 apps/desktop/src/sshEnvironment.ts            | 113 +--
 .../desktop/SshPasswordPromptDialog.tsx       |  65 +-
 .../settings/ConnectionsSettings.tsx          | 684 +++++++++---------
 packages/ssh/src/tunnel.test.ts               |  48 ++
 packages/ssh/src/tunnel.ts                    |  15 +-
 5 files changed, 483 insertions(+), 442 deletions(-)

diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 92fa57cf708..97bad24d056 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -19,40 +19,28 @@ import {
 } from "@t3tools/ssh/auth";
 import { discoverSshHosts } from "@t3tools/ssh/config";
 import { SshPasswordPromptError } from "@t3tools/ssh/errors";
-import {
-  fetchLoopbackSshJson,
-  SshEnvironmentManager,
-} from "@t3tools/ssh/tunnel";
+import { fetchLoopbackSshJson, SshEnvironmentManager } from "@t3tools/ssh/tunnel";
 import { Effect, Exit, Layer, ManagedRuntime, Scope } from "effect";
 
 export { resolveRemoteT3CliPackageSpec } from "@t3tools/ssh/command";
 
 const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
 const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
-const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL =
-  "desktop:fetch-ssh-environment-descriptor";
-const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL =
-  "desktop:bootstrap-ssh-bearer-session";
+const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
+const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
 const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
 const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
 const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
-const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL =
-  "desktop:resolve-ssh-password-prompt";
+const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
 const DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
 
 interface DesktopSshEnvironmentManagerOptions {
-  readonly passwordProvider?: (
-    request: SshPasswordRequest,
-  ) => Promise<string | null>;
+  readonly passwordProvider?: (request: SshPasswordRequest) => Promise<string | null>;
   readonly resolveCliPackageSpec?: () => string;
 }
 
 const sshRuntime = ManagedRuntime.make(
-  Layer.mergeAll(
-    NodeServices.layer,
-    NodeHttpClient.layerUndici,
-    NetService.layer,
-  ),
+  Layer.mergeAll(NodeServices.layer, NodeHttpClient.layerUndici, NetService.layer),
 );
 
 function createDesktopSshRuntime(
@@ -99,10 +87,7 @@ export class DesktopSshEnvironmentManager {
           try: () => passwordProvider(request),
           catch: (cause) =>
             new SshPasswordPromptError({
-              message:
-                cause instanceof Error
-                  ? cause.message
-                  : "SSH password prompt failed.",
+              message: cause instanceof Error ? cause.message : "SSH password prompt failed.",
               cause,
             }),
         });
@@ -133,9 +118,7 @@ export class DesktopSshEnvironmentManager {
   }
 }
 
-function getSafeDesktopSshTarget(
-  rawTarget: unknown,
-): DesktopSshEnvironmentTarget | null {
+function getSafeDesktopSshTarget(rawTarget: unknown): DesktopSshEnvironmentTarget | null {
   if (typeof rawTarget !== "object" || rawTarget === null) {
     return null;
   }
@@ -151,11 +134,7 @@ function getSafeDesktopSshTarget(
   ) {
     return null;
   }
-  if (
-    target.port !== null &&
-    target.port !== undefined &&
-    !Number.isInteger(target.port)
-  ) {
+  if (target.port !== null && target.port !== undefined && !Number.isInteger(target.port)) {
     return null;
   }
 
@@ -189,10 +168,7 @@ export interface DesktopSshBridgeIpcMain {
   removeHandler(channel: string): void;
   handle(
     channel: string,
-    listener: (
-      event: unknown,
-      ...args: readonly unknown[]
-    ) => unknown | Promise<unknown>,
+    listener: (event: unknown, ...args: readonly unknown[]) => unknown | Promise<unknown>,
   ): void;
 }
 
@@ -230,42 +206,34 @@ export class DesktopSshEnvironmentBridge {
 
   registerIpcHandlers(ipcMain: DesktopSshBridgeIpcMain): void {
     ipcMain.removeHandler(DISCOVER_SSH_HOSTS_CHANNEL);
-    ipcMain.handle(DISCOVER_SSH_HOSTS_CHANNEL, async () =>
-      this.manager.discoverHosts(),
-    );
+    ipcMain.handle(DISCOVER_SSH_HOSTS_CHANNEL, async () => this.manager.discoverHosts());
 
     ipcMain.removeHandler(ENSURE_SSH_ENVIRONMENT_CHANNEL);
-    ipcMain.handle(
-      ENSURE_SSH_ENVIRONMENT_CHANNEL,
-      async (_event, rawTarget, rawOptions) => {
-        const target = getSafeDesktopSshTarget(rawTarget);
-        if (!target) {
-          throw new Error("Invalid desktop SSH target.");
-        }
+    ipcMain.handle(ENSURE_SSH_ENVIRONMENT_CHANNEL, async (_event, rawTarget, rawOptions) => {
+      const target = getSafeDesktopSshTarget(rawTarget);
+      if (!target) {
+        throw new Error("Invalid desktop SSH target.");
+      }
 
-        const issuePairingToken =
-          typeof rawOptions === "object" &&
-          rawOptions !== null &&
-          "issuePairingToken" in rawOptions &&
-          (rawOptions as { issuePairingToken?: unknown }).issuePairingToken ===
-            true;
+      const issuePairingToken =
+        typeof rawOptions === "object" &&
+        rawOptions !== null &&
+        "issuePairingToken" in rawOptions &&
+        (rawOptions as { issuePairingToken?: unknown }).issuePairingToken === true;
 
-        return await this.manager.ensureEnvironment(target, {
-          issuePairingToken,
-        });
-      },
-    );
+      return await this.manager.ensureEnvironment(target, {
+        issuePairingToken,
+      });
+    });
 
     ipcMain.removeHandler(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL);
-    ipcMain.handle(
-      FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL,
-      async (_event, rawHttpBaseUrl) =>
-        sshRuntime.runPromise(
-          fetchLoopbackSshJson<ExecutionEnvironmentDescriptor>({
-            httpBaseUrl: rawHttpBaseUrl,
-            pathname: "/.well-known/t3/environment",
-          }),
-        ),
+    ipcMain.handle(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, async (_event, rawHttpBaseUrl) =>
+      sshRuntime.runPromise(
+        fetchLoopbackSshJson<ExecutionEnvironmentDescriptor>({
+          httpBaseUrl: rawHttpBaseUrl,
+          pathname: "/.well-known/t3/environment",
+        }),
+      ),
     );
 
     ipcMain.removeHandler(BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL);
@@ -313,10 +281,7 @@ export class DesktopSshEnvironmentBridge {
     ipcMain.handle(
       RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL,
       async (_event, rawRequestId, rawPassword) => {
-        if (
-          typeof rawRequestId !== "string" ||
-          rawRequestId.trim().length === 0
-        ) {
+        if (typeof rawRequestId !== "string" || rawRequestId.trim().length === 0) {
           throw new Error("Invalid SSH password prompt id.");
         }
         if (rawPassword !== null && typeof rawPassword !== "string") {
@@ -348,14 +313,10 @@ export class DesktopSshEnvironmentBridge {
     await this.manager.dispose();
   }
 
-  private async requestPasswordFromRenderer(
-    input: SshPasswordRequest,
-  ): Promise<string | null> {
+  private async requestPasswordFromRenderer(input: SshPasswordRequest): Promise<string | null> {
     const window = this.options.getMainWindow();
     if (!window || window.isDestroyed()) {
-      throw new Error(
-        "T3 Code window is not available for SSH authentication.",
-      );
+      throw new Error("T3 Code window is not available for SSH authentication.");
     }
 
     const request: DesktopSshPasswordPromptRequest = {
@@ -368,9 +329,7 @@ export class DesktopSshEnvironmentBridge {
     return await new Promise<string | null>((resolve, reject) => {
       const timeout = setTimeout(() => {
         this.pendingPrompts.delete(request.requestId);
-        reject(
-          new Error(`SSH authentication timed out for ${input.destination}.`),
-        );
+        reject(new Error(`SSH authentication timed out for ${input.destination}.`));
       }, this.passwordPromptTimeoutMs);
       timeout.unref();
 
diff --git a/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
index 1bc08b1bfd7..00df682700a 100644
--- a/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
+++ b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
@@ -1,5 +1,5 @@
 import type { DesktopSshPasswordPromptRequest } from "@t3tools/contracts";
-import { useEffect, useRef, useState } from "react";
+import { useEffect, useId, useRef, useState } from "react";
 
 import { Button } from "../ui/button";
 import {
@@ -24,6 +24,7 @@ export function SshPasswordPromptDialog() {
   const currentRequest = queue[0] ?? null;
   const inputRef = useRef<HTMLInputElement | null>(null);
   const isRespondingRef = useRef(false);
+  const formId = useId();
 
   useEffect(() => {
     const bridge = window.desktopBridge;
@@ -85,21 +86,23 @@ export function SshPasswordPromptDialog() {
       }}
     >
       <DialogPopup className="max-w-md" showCloseButton={false}>
-        <form
-          onSubmit={(event) => {
-            event.preventDefault();
-            void respond(password);
-          }}
-        >
-          <DialogHeader>
-            <DialogTitle>SSH Password Required</DialogTitle>
-            <DialogDescription>
-              T3 needs your SSH password to connect to{" "}
-              {target ? <code>{target}</code> : "the remote host"}. The password is passed to the
-              local SSH process for this connection attempt and is not saved by T3 Code.
-            </DialogDescription>
-          </DialogHeader>
-          <DialogPanel className="space-y-3" scrollFade={false}>
+        <DialogHeader>
+          <DialogTitle>SSH Password Required</DialogTitle>
+          <DialogDescription>
+            T3 needs your SSH password to connect to{" "}
+            {target ? <code>{target}</code> : "the remote host"}. The password is passed to the
+            local SSH process for this connection attempt and is not saved by T3 Code.
+          </DialogDescription>
+        </DialogHeader>
+        <DialogPanel className="space-y-3" scrollFade={false}>
+          <form
+            className="space-y-3"
+            id={formId}
+            onSubmit={(event) => {
+              event.preventDefault();
+              void respond(password);
+            }}
+          >
             <div className="space-y-2">
               <p className="text-sm font-medium text-foreground">{currentRequest?.prompt}</p>
               <Input
@@ -115,21 +118,21 @@ export function SshPasswordPromptDialog() {
             <p className="text-sm text-muted-foreground">
               Use SSH keys to avoid repeated password prompts on new SSH sessions.
             </p>
-          </DialogPanel>
-          <DialogFooter>
-            <Button
-              disabled={isResponding}
-              type="button"
-              variant="outline"
-              onClick={() => void respond(null)}
-            >
-              Cancel
-            </Button>
-            <Button disabled={isResponding} type="submit">
-              Continue
-            </Button>
-          </DialogFooter>
-        </form>
+          </form>
+        </DialogPanel>
+        <DialogFooter>
+          <Button
+            disabled={isResponding}
+            type="button"
+            variant="outline"
+            onClick={() => void respond(null)}
+          >
+            Cancel
+          </Button>
+          <Button disabled={isResponding} form={formId} type="submit">
+            Continue
+          </Button>
+        </DialogFooter>
       </DialogPopup>
     </Dialog>
   );
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 033c8a45b44..a53ad22ab50 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -1,5 +1,21 @@
-import { ChevronDownIcon, PlusIcon, QrCodeIcon, RefreshCwIcon } from "lucide-react";
-import { type ReactNode, memo, useCallback, useEffect, useMemo, useState } from "react";
+import {
+  ChevronDownIcon,
+  ChevronsLeftRightEllipsisIcon,
+  PlusIcon,
+  QrCodeIcon,
+  RefreshCwIcon,
+  TerminalIcon,
+} from "lucide-react";
+import {
+  type ReactNode,
+  memo,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import {
   type AuthClientSession,
   type AuthPairingLink,
@@ -53,7 +69,8 @@ import { Button } from "../ui/button";
 import { Group, GroupSeparator } from "../ui/group";
 import { Menu, MenuItem, MenuPopup, MenuTrigger } from "../ui/menu";
 import { Textarea } from "../ui/textarea";
-import { setPairingTokenOnUrl } from "../../pairingUrl";
+import { getPairingTokenFromUrl, setPairingTokenOnUrl } from "../../pairingUrl";
+import { readHostedPairingRequest } from "../../hostedPairing";
 import {
   createServerPairingCredential,
   fetchSessionState,
@@ -147,6 +164,35 @@ function ConnectionStatusDot({
   );
 }
 
+function AnimatedHeight({ children }: { readonly children: ReactNode }) {
+  const contentRef = useRef<HTMLDivElement>(null);
+  const [height, setHeight] = useState<number | null>(null);
+
+  useLayoutEffect(() => {
+    const element = contentRef.current;
+    if (!element) return;
+
+    const updateHeight = () => {
+      const nextHeight = element.getBoundingClientRect().height;
+      setHeight((currentHeight) => (currentHeight === nextHeight ? currentHeight : nextHeight));
+    };
+
+    updateHeight();
+    const resizeObserver = new ResizeObserver(updateHeight);
+    resizeObserver.observe(element);
+    return () => resizeObserver.disconnect();
+  }, []);
+
+  return (
+    <div
+      className="overflow-hidden transition-[height] duration-200 ease-out motion-reduce:transition-none"
+      style={height === null ? undefined : { height }}
+    >
+      <div ref={contentRef}>{children}</div>
+    </div>
+  );
+}
+
 function getSavedBackendStatusTooltip(
   runtime: SavedEnvironmentRuntimeState | null,
   record: SavedEnvironmentRecord,
@@ -235,6 +281,66 @@ function parseManualDesktopSshTarget(input: {
   };
 }
 
+function parsePairingUrlFields(
+  input: string,
+): { readonly host: string; readonly pairingCode: string } | null {
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+
+  try {
+    const urlLikeInput =
+      /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//u.test(trimmed) || trimmed.startsWith("//")
+        ? trimmed
+        : `https://${trimmed}`;
+    const url = new URL(urlLikeInput, window.location.origin);
+    const hostedPairingRequest = readHostedPairingRequest(url);
+    if (hostedPairingRequest) {
+      return {
+        host: hostedPairingRequest.host,
+        pairingCode: hostedPairingRequest.token,
+      };
+    }
+
+    const pairingCode = getPairingTokenFromUrl(url);
+    if (!pairingCode) return null;
+    return {
+      host: url.origin,
+      pairingCode,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function parseRemotePairingFields(input: { readonly host: string; readonly pairingCode: string }): {
+  readonly host: string;
+  readonly pairingCode: string;
+} {
+  const parsedPairingUrl = parsePairingUrlFields(input.host);
+  if (parsedPairingUrl) return parsedPairingUrl;
+
+  const host = input.host.trim();
+  const pairingCode = input.pairingCode.trim();
+  if (!host) {
+    throw new Error("Enter a backend host.");
+  }
+  if (!pairingCode) {
+    throw new Error("Enter a pairing code.");
+  }
+  return { host, pairingCode };
+}
+
+function formatDesktopSshConnectionError(error: unknown): string {
+  const fallback = "Failed to connect SSH host.";
+  const rawMessage = error instanceof Error ? error.message : fallback;
+  const withoutIpcPrefix = rawMessage.replace(
+    /^Error invoking remote method 'desktop:ensure-ssh-environment':\s*/u,
+    "",
+  );
+  const withoutTaggedErrorPrefix = withoutIpcPrefix.replace(/^Ssh[A-Za-z]+Error:\s*/u, "");
+  return withoutTaggedErrorPrefix.trim() || fallback;
+}
+
 /** Direct row in the card – same pattern as the Provider / ACP-agent list rows. */
 const ITEM_ROW_CLASSNAME = "border-t border-border/60 px-4 py-4 first:border-t-0 sm:px-5";
 const ENDPOINT_ROW_CLASSNAME = "border-t border-border/60 px-4 py-2.5 first:border-t-0 sm:px-5";
@@ -1137,38 +1243,25 @@ function SavedBackendListRow({
 
 interface DesktopSshHostRowProps {
   target: DesktopDiscoveredSshHost;
-  savedRecord: SavedEnvironmentRecord | null;
   connectingHostAlias: string | null;
   onConnect: (target: DesktopDiscoveredSshHost) => void;
 }
 
 const DesktopSshHostRow = memo(function DesktopSshHostRow({
   target,
-  savedRecord,
   connectingHostAlias,
   onConnect,
 }: DesktopSshHostRowProps) {
   const address = formatDesktopSshTarget(target);
-  const secondaryBits = [target.source === "ssh-config" ? "SSH config" : "Known hosts", address];
-  const buttonLabel =
-    connectingHostAlias === target.alias ? "Connecting…" : savedRecord ? "Reconnect" : "Connect";
+  const showAddress = address !== target.alias;
+  const buttonLabel = connectingHostAlias === target.alias ? "Adding…" : "Add environment";
 
   return (
-    <div className={ITEM_ROW_CLASSNAME}>
+    <div className="border-t border-border/60 px-4 py-3 first:border-t-0 sm:px-5">
       <div className={ITEM_ROW_INNER_CLASSNAME}>
-        <div className="min-w-0 flex-1 space-y-1">
-          <div className="flex min-h-5 items-center gap-1.5">
-            <h3 className="text-sm font-medium text-foreground">{target.alias}</h3>
-          </div>
-          <p className="text-xs text-muted-foreground">{secondaryBits.join(" · ")}</p>
-          {savedRecord ? (
-            <p className="text-xs text-muted-foreground">
-              Saved as {savedRecord.label}
-              {savedRecord.lastConnectedAt
-                ? ` · Last connected ${formatAccessTimestamp(savedRecord.lastConnectedAt)}`
-                : ""}
-            </p>
-          ) : null}
+        <div className="min-w-0 flex-1">
+          <h3 className="truncate text-sm font-medium text-foreground">{target.alias}</h3>
+          {showAddress ? <p className="truncate text-xs text-muted-foreground">{address}</p> : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
           <Button
@@ -1217,6 +1310,16 @@ export function ConnectionsSettings() {
       ),
     [savedEnvironmentsById],
   );
+  const savedDesktopSshEnvironmentKeys = useMemo(() => {
+    const keys = new Set<string>();
+    for (const record of Object.values(savedEnvironmentsById)) {
+      const target = record.desktopSsh;
+      if (!target) continue;
+      keys.add(target.alias);
+      keys.add(formatDesktopSshTarget(target));
+    }
+    return keys;
+  }, [savedEnvironmentsById]);
   const [discoveredSshHosts, setDiscoveredSshHosts] = useState<
     ReadonlyArray<DesktopDiscoveredSshHost>
   >([]);
@@ -1249,11 +1352,7 @@ export function ConnectionsSettings() {
   >(null);
   const [isRevokingOtherDesktopClients, setIsRevokingOtherDesktopClients] = useState(false);
   const [addBackendDialogOpen, setAddBackendDialogOpen] = useState(false);
-  const [savedBackendMode, setSavedBackendMode] = useState<"pairing-url" | "host-code" | "ssh">(
-    "pairing-url",
-  );
-  const [savedBackendLabel, setSavedBackendLabel] = useState("");
-  const [savedBackendPairingUrl, setSavedBackendPairingUrl] = useState("");
+  const [savedBackendMode, setSavedBackendMode] = useState<"remote" | "ssh">("remote");
   const [savedBackendHost, setSavedBackendHost] = useState("");
   const [savedBackendPairingCode, setSavedBackendPairingCode] = useState("");
   const [savedBackendSshHost, setSavedBackendSshHost] = useState("");
@@ -1261,6 +1360,17 @@ export function ConnectionsSettings() {
   const [savedBackendSshPort, setSavedBackendSshPort] = useState("");
   const [savedBackendError, setSavedBackendError] = useState<string | null>(null);
   const [isAddingSavedBackend, setIsAddingSavedBackend] = useState(false);
+  const unsavedDiscoveredSshHosts = useMemo(
+    () =>
+      discoveredSshHosts.filter((target) => {
+        const address = formatDesktopSshTarget(target);
+        return (
+          !savedDesktopSshEnvironmentKeys.has(target.alias) &&
+          !savedDesktopSshEnvironmentKeys.has(address)
+        );
+      }),
+    [discoveredSshHosts, savedDesktopSshEnvironmentKeys],
+  );
   const [reconnectingSavedEnvironmentId, setReconnectingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
   const [removingSavedEnvironmentId, setRemovingSavedEnvironmentId] =
@@ -1492,11 +1602,7 @@ export function ConnectionsSettings() {
           username: savedBackendSshUsername,
           port: savedBackendSshPort,
         });
-        const record = await connectDesktopSshEnvironment(target, {
-          label: savedBackendLabel,
-        });
-        setSavedBackendLabel("");
-        setSavedBackendPairingUrl("");
+        const record = await connectDesktopSshEnvironment(target, { label: "" });
         setSavedBackendHost("");
         setSavedBackendPairingCode("");
         setSavedBackendSshHost("");
@@ -1510,14 +1616,8 @@ export function ConnectionsSettings() {
           description: `${record.label} is ready over an SSH-managed tunnel.`,
         });
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
-
+        const message = formatDesktopSshConnectionError(error);
         setSavedBackendError(message);
-        toastManager.add({
-          type: "error",
-          title: "Could not connect SSH host",
-          description: message,
-        });
       } finally {
         setIsAddingSavedBackend(false);
       }
@@ -1527,17 +1627,14 @@ export function ConnectionsSettings() {
     setIsAddingSavedBackend(true);
     setSavedBackendError(null);
     try {
+      const remotePairingInput = parseRemotePairingFields({
+        host: savedBackendHost,
+        pairingCode: savedBackendPairingCode,
+      });
       const record = await addSavedEnvironment({
-        label: savedBackendLabel,
-        ...(savedBackendMode === "pairing-url"
-          ? { pairingUrl: savedBackendPairingUrl }
-          : {
-              host: savedBackendHost,
-              pairingCode: savedBackendPairingCode,
-            }),
+        label: "",
+        ...remotePairingInput,
       });
-      setSavedBackendLabel("");
-      setSavedBackendPairingUrl("");
       setSavedBackendHost("");
       setSavedBackendPairingCode("");
       setSavedBackendSshHost("");
@@ -1564,10 +1661,8 @@ export function ConnectionsSettings() {
     }
   }, [
     savedBackendHost,
-    savedBackendLabel,
     savedBackendMode,
     savedBackendPairingCode,
-    savedBackendPairingUrl,
     savedBackendSshHost,
     savedBackendSshPort,
     savedBackendSshUsername,
@@ -1649,7 +1744,6 @@ export function ConnectionsSettings() {
           target,
           label === undefined ? undefined : { label },
         );
-        setSavedBackendLabel("");
         setSavedBackendSshHost("");
         setSavedBackendSshUsername("");
         setSavedBackendSshPort("");
@@ -1662,17 +1756,12 @@ export function ConnectionsSettings() {
           description: `${record.label} is ready over an SSH-managed tunnel.`,
         });
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Failed to connect SSH host.";
+        const message = formatDesktopSshConnectionError(error);
         if (savedBackendMode === "ssh") {
           setSavedBackendError(message);
         } else {
           setDiscoveredSshHostsError(message);
         }
-        toastManager.add({
-          type: "error",
-          title: "Could not connect SSH host",
-          description: message,
-        });
       } finally {
         setConnectingSshHostAlias(null);
       }
@@ -1880,6 +1969,199 @@ export function ConnectionsSettings() {
     },
     [setDefaultAdvertisedEndpointKey],
   );
+  const handleSavedBackendHostChange = useCallback((value: string) => {
+    const parsedPairingUrl = parsePairingUrlFields(value);
+    if (parsedPairingUrl) {
+      setSavedBackendHost(parsedPairingUrl.host);
+      setSavedBackendPairingCode(parsedPairingUrl.pairingCode);
+      return;
+    }
+    setSavedBackendHost(value);
+  }, []);
+
+  const renderConnectionModeCard = (input: {
+    readonly mode: "remote" | "ssh";
+    readonly title: string;
+    readonly description: string;
+    readonly icon?: ReactNode;
+  }) => {
+    const selected = savedBackendMode === input.mode;
+    return (
+      <button
+        type="button"
+        aria-pressed={selected}
+        className={cn(
+          "group flex min-h-24 items-start gap-3 rounded-lg border p-4 text-left",
+          selected ? "border-primary/50 bg-primary/5" : "border-border/60 hover:bg-muted/40",
+        )}
+        disabled={isAddingSavedBackend}
+        onClick={() => {
+          setSavedBackendMode(input.mode);
+        }}
+      >
+        {input.icon ? (
+          <span
+            className={cn(
+              "mt-0.5 flex size-8 shrink-0 items-center justify-center rounded-md border",
+              selected
+                ? "border-primary/30 bg-primary/10 text-primary"
+                : "border-border/70 bg-background text-muted-foreground group-hover:text-foreground",
+            )}
+          >
+            {input.icon}
+          </span>
+        ) : null}
+        <span className="min-w-0">
+          <span className="block text-sm font-medium text-foreground">{input.title}</span>
+          <span className="mt-1 block text-xs leading-relaxed text-muted-foreground">
+            {input.description}
+          </span>
+        </span>
+      </button>
+    );
+  };
+
+  const renderRemoteFields = () => (
+    <div className="space-y-3">
+      <div className="grid gap-3 sm:grid-cols-[minmax(0,1fr)_10rem]">
+        <label className="block">
+          <span className="mb-1.5 block text-xs font-medium text-foreground">Host</span>
+          <Input
+            value={savedBackendHost}
+            onChange={(event) => handleSavedBackendHostChange(event.target.value)}
+            placeholder="backend.example.com"
+            disabled={isAddingSavedBackend}
+            spellCheck={false}
+          />
+        </label>
+        <label className="block">
+          <span className="mb-1.5 block text-xs font-medium text-foreground">Pairing code</span>
+          <Input
+            value={savedBackendPairingCode}
+            onChange={(event) => setSavedBackendPairingCode(event.target.value)}
+            placeholder="PAIRCODE"
+            disabled={isAddingSavedBackend}
+            spellCheck={false}
+          />
+        </label>
+      </div>
+      <div>
+        <span className="mt-1 block text-[11px] text-muted-foreground">
+          Paste a full pairing URL here to fill both fields automatically.
+        </span>
+      </div>
+    </div>
+  );
+  const renderRemoteModeBody = () => (
+    <div className="space-y-4">
+      {renderRemoteFields()}
+      {savedBackendError ? <p className="text-xs text-destructive">{savedBackendError}</p> : null}
+      <Button
+        variant="outline"
+        className="w-full"
+        disabled={isAddingSavedBackend}
+        onClick={() => void handleAddSavedBackend()}
+      >
+        <PlusIcon className="size-3.5" />
+        {isAddingSavedBackend ? "Adding…" : "Add environment"}
+      </Button>
+    </div>
+  );
+  const renderSshFields = () => (
+    <div className="space-y-4">
+      <div className="space-y-3">
+        <label className="block">
+          <span className="mb-1.5 block text-xs font-medium text-foreground">
+            SSH host or alias
+          </span>
+          <Input
+            value={savedBackendSshHost}
+            onChange={(event) => setSavedBackendSshHost(event.target.value)}
+            placeholder="Search hosts or type devbox"
+            disabled={isAddingSavedBackend}
+            spellCheck={false}
+          />
+        </label>
+        <div className="grid gap-3 sm:grid-cols-[minmax(0,1fr)_7rem]">
+          <label className="block">
+            <span className="mb-1.5 block text-xs font-medium text-foreground">Username</span>
+            <Input
+              value={savedBackendSshUsername}
+              onChange={(event) => setSavedBackendSshUsername(event.target.value)}
+              placeholder="julius"
+              disabled={isAddingSavedBackend}
+              spellCheck={false}
+            />
+          </label>
+          <label className="block">
+            <span className="mb-1.5 block text-xs font-medium text-foreground">Port</span>
+            <Input
+              value={savedBackendSshPort}
+              onChange={(event) => setSavedBackendSshPort(event.target.value)}
+              placeholder="22"
+              inputMode="numeric"
+              disabled={isAddingSavedBackend}
+              spellCheck={false}
+            />
+          </label>
+        </div>
+        {savedBackendError || discoveredSshHostsError ? (
+          <div className="rounded-md border border-destructive/30 bg-destructive/5 px-3 py-2 text-xs text-destructive">
+            {savedBackendError ?? discoveredSshHostsError}
+          </div>
+        ) : null}
+        <Button
+          variant="outline"
+          className="w-full"
+          disabled={isAddingSavedBackend}
+          onClick={() => void handleAddSavedBackend()}
+        >
+          <PlusIcon className="size-3.5" />
+          {isAddingSavedBackend ? "Adding…" : "Add environment"}
+        </Button>
+      </div>
+      <div className="overflow-hidden rounded-lg border border-border/60">
+        <div className="flex items-center justify-between gap-3 border-b border-border/60 bg-muted/30 px-3 py-2">
+          <div className="min-w-0">
+            <p className="text-xs font-medium text-foreground">Suggested hosts</p>
+            <p className="text-[11px] text-muted-foreground">From SSH config and known hosts</p>
+          </div>
+          <Button
+            size="xs"
+            variant="ghost"
+            disabled={isLoadingDiscoveredSshHosts}
+            onClick={() => void loadDiscoveredSshHosts()}
+          >
+            {isLoadingDiscoveredSshHosts ? (
+              <RefreshCwIcon className="size-3 animate-spin" />
+            ) : (
+              <RefreshCwIcon className="size-3" />
+            )}
+            Refresh
+          </Button>
+        </div>
+        <ScrollArea scrollFade className="max-h-56">
+          <div>
+            {unsavedDiscoveredSshHosts.map((target) => (
+              <DesktopSshHostRow
+                key={`${target.alias}:${target.hostname}:${target.port ?? ""}`}
+                target={target}
+                connectingHostAlias={connectingSshHostAlias}
+                onConnect={(nextTarget) => void handleConnectSshHost(nextTarget)}
+              />
+            ))}
+            {hasLoadedDiscoveredSshHosts &&
+            !isLoadingDiscoveredSshHosts &&
+            unsavedDiscoveredSshHosts.length === 0 ? (
+              <div className={ITEM_ROW_CLASSNAME}>
+                <p className="text-xs text-muted-foreground">No new SSH hosts were discovered.</p>
+              </div>
+            ) : null}
+          </div>
+        </ScrollArea>
+      </div>
+    </div>
+  );
   return (
     <SettingsPageContainer>
       {canManageLocalBackend ? (
@@ -2235,278 +2517,28 @@ export function ConnectionsSettings() {
               <DialogHeader>
                 <DialogTitle>Add Environment</DialogTitle>
                 <DialogDescription>Pair another environment to this client.</DialogDescription>
-                <div className="flex gap-1 rounded-lg border border-border/60 bg-muted/50 p-1">
-                  <button
-                    type="button"
-                    className={cn(
-                      "flex-1 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
-                      savedBackendMode === "pairing-url"
-                        ? "bg-background text-foreground shadow-xs"
-                        : "text-muted-foreground hover:text-foreground",
-                    )}
-                    disabled={isAddingSavedBackend}
-                    onClick={() => setSavedBackendMode("pairing-url")}
-                  >
-                    Pairing URL
-                  </button>
-                  <button
-                    type="button"
-                    className={cn(
-                      "flex-1 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
-                      savedBackendMode === "host-code"
-                        ? "bg-background text-foreground shadow-xs"
-                        : "text-muted-foreground hover:text-foreground",
-                    )}
-                    disabled={isAddingSavedBackend}
-                    onClick={() => setSavedBackendMode("host-code")}
-                  >
-                    Host + code
-                  </button>
-                  {desktopBridge ? (
-                    <button
-                      type="button"
-                      className={cn(
-                        "flex-1 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
-                        savedBackendMode === "ssh"
-                          ? "bg-background text-foreground shadow-xs"
-                          : "text-muted-foreground hover:text-foreground",
-                      )}
-                      disabled={isAddingSavedBackend}
-                      onClick={() => setSavedBackendMode("ssh")}
-                    >
-                      SSH
-                    </button>
-                  ) : null}
-                </div>
               </DialogHeader>
               <DialogPanel>
                 <div className="space-y-4">
-                  {savedBackendMode === "pairing-url" ? (
-                    <p className="text-xs text-muted-foreground">
-                      Enter the full pairing URL from the environment you want to connect to.
-                    </p>
-                  ) : savedBackendMode === "host-code" ? (
-                    <p className="text-xs text-muted-foreground">
-                      Enter the backend host and pairing code separately.
-                    </p>
-                  ) : (
-                    <p className="text-xs text-muted-foreground">
-                      Connect over SSH using an existing alias from <code>~/.ssh/config</code> or
-                      enter a host directly. T3 uses your current SSH agent and config.
-                    </p>
-                  )}
-                  {savedBackendMode === "pairing-url" ? (
-                    <div className="space-y-3">
-                      <label className="block">
-                        <span className="mb-1.5 block text-xs font-medium text-foreground">
-                          Label
-                        </span>
-                        <Input
-                          value={savedBackendLabel}
-                          onChange={(event) => setSavedBackendLabel(event.target.value)}
-                          placeholder="My backend (optional)"
-                          disabled={isAddingSavedBackend}
-                          spellCheck={false}
-                        />
-                      </label>
-                      <label className="block">
-                        <span className="mb-1.5 block text-xs font-medium text-foreground">
-                          Pairing URL
-                        </span>
-                        <Input
-                          value={savedBackendPairingUrl}
-                          onChange={(event) => setSavedBackendPairingUrl(event.target.value)}
-                          placeholder="https://backend.example.com/pair#token=..."
-                          disabled={isAddingSavedBackend}
-                          spellCheck={false}
-                        />
-                        <span className="mt-1 block text-[11px] text-muted-foreground">
-                          The full URL including the pairing token.
-                        </span>
-                      </label>
-                    </div>
-                  ) : savedBackendMode === "host-code" ? (
-                    <div className="space-y-3">
-                      <label className="block">
-                        <span className="mb-1.5 block text-xs font-medium text-foreground">
-                          Label
-                        </span>
-                        <Input
-                          value={savedBackendLabel}
-                          onChange={(event) => setSavedBackendLabel(event.target.value)}
-                          placeholder="My backend (optional)"
-                          disabled={isAddingSavedBackend}
-                          spellCheck={false}
-                        />
-                      </label>
-                      <label className="block">
-                        <span className="mb-1.5 block text-xs font-medium text-foreground">
-                          Host
-                        </span>
-                        <Input
-                          value={savedBackendHost}
-                          onChange={(event) => setSavedBackendHost(event.target.value)}
-                          placeholder="https://backend.example.com"
-                          disabled={isAddingSavedBackend}
-                          spellCheck={false}
-                        />
-                      </label>
-                      <label className="block">
-                        <span className="mb-1.5 block text-xs font-medium text-foreground">
-                          Pairing code
-                        </span>
-                        <Input
-                          value={savedBackendPairingCode}
-                          onChange={(event) => setSavedBackendPairingCode(event.target.value)}
-                          placeholder="Pairing code"
-                          disabled={isAddingSavedBackend}
-                          spellCheck={false}
-                        />
-                      </label>
-                    </div>
-                  ) : (
-                    <div className="space-y-4">
-                      <div className="flex items-start justify-between gap-3">
-                        <div className="min-w-0">
-                          <h3 className="text-sm font-medium text-foreground">Discovered hosts</h3>
-                          <p className="text-xs text-muted-foreground">
-                            From <code>~/.ssh/config</code> and <code>known_hosts</code>.
-                          </p>
-                        </div>
-                        <Button
-                          size="xs"
-                          variant="outline"
-                          disabled={isLoadingDiscoveredSshHosts}
-                          onClick={() => void loadDiscoveredSshHosts()}
-                        >
-                          {isLoadingDiscoveredSshHosts ? (
-                            <RefreshCwIcon className="size-3 animate-spin" />
-                          ) : (
-                            <RefreshCwIcon className="size-3" />
-                          )}
-                          Refresh
-                        </Button>
-                      </div>
-                      {discoveredSshHostsError ? (
-                        <p className="text-xs text-destructive">{discoveredSshHostsError}</p>
-                      ) : null}
-                      <ScrollArea scrollFade className="max-h-64">
-                        <div>
-                          {discoveredSshHosts.map((target) => (
-                            <DesktopSshHostRow
-                              key={`${target.alias}:${target.hostname}:${target.port ?? ""}`}
-                              target={target}
-                              savedRecord={savedDesktopSshEnvironmentsByAlias[target.alias] ?? null}
-                              connectingHostAlias={connectingSshHostAlias}
-                              onConnect={(nextTarget) => void handleConnectSshHost(nextTarget)}
-                            />
-                          ))}
-                          {hasLoadedDiscoveredSshHosts &&
-                          !isLoadingDiscoveredSshHosts &&
-                          discoveredSshHosts.length === 0 ? (
-                            <div className={ITEM_ROW_CLASSNAME}>
-                              <p className="text-xs text-muted-foreground">
-                                No SSH hosts were discovered from <code>~/.ssh/config</code> or{" "}
-                                <code>known_hosts</code>.
-                              </p>
-                            </div>
-                          ) : null}
-                        </div>
-                      </ScrollArea>
-                      {savedBackendError ? (
-                        <p className="text-xs text-destructive">{savedBackendError}</p>
-                      ) : null}
-                      <div className="border-t border-border/60 pt-4">
-                        <h3 className="mb-1 text-sm font-medium text-foreground">
-                          Enter a host manually
-                        </h3>
-                        <p className="mb-3 text-xs text-muted-foreground">
-                          Use an alias or enter host, username, and port directly.
-                        </p>
-                        <div className="space-y-3">
-                          <label className="block">
-                            <span className="mb-1.5 block text-xs font-medium text-foreground">
-                              Label
-                            </span>
-                            <Input
-                              value={savedBackendLabel}
-                              onChange={(event) => setSavedBackendLabel(event.target.value)}
-                              placeholder="My backend (optional)"
-                              disabled={isAddingSavedBackend}
-                              spellCheck={false}
-                            />
-                          </label>
-                          <label className="block">
-                            <span className="mb-1.5 block text-xs font-medium text-foreground">
-                              SSH host or alias
-                            </span>
-                            <Input
-                              value={savedBackendSshHost}
-                              onChange={(event) => setSavedBackendSshHost(event.target.value)}
-                              placeholder="devbox or devbox.example.com"
-                              disabled={isAddingSavedBackend}
-                              spellCheck={false}
-                            />
-                          </label>
-                          <div className="grid gap-3 sm:grid-cols-2">
-                            <label className="block">
-                              <span className="mb-1.5 block text-xs font-medium text-foreground">
-                                Username
-                              </span>
-                              <Input
-                                value={savedBackendSshUsername}
-                                onChange={(event) => setSavedBackendSshUsername(event.target.value)}
-                                placeholder="julius"
-                                disabled={isAddingSavedBackend}
-                                spellCheck={false}
-                              />
-                            </label>
-                            <label className="block">
-                              <span className="mb-1.5 block text-xs font-medium text-foreground">
-                                Port
-                              </span>
-                              <Input
-                                value={savedBackendSshPort}
-                                onChange={(event) => setSavedBackendSshPort(event.target.value)}
-                                placeholder="22"
-                                inputMode="numeric"
-                                disabled={isAddingSavedBackend}
-                                spellCheck={false}
-                              />
-                            </label>
-                          </div>
-                          <span className="block text-[11px] text-muted-foreground">
-                            Uses your existing SSH keys, agent, and config. Password and
-                            keyboard-interactive prompts open through your system SSH dialog when
-                            needed.
-                          </span>
-                          <Button
-                            variant="outline"
-                            className="w-full"
-                            disabled={isAddingSavedBackend}
-                            onClick={() => void handleAddSavedBackend()}
-                          >
-                            <PlusIcon className="size-3.5" />
-                            {isAddingSavedBackend ? "Connecting…" : "Connect SSH host"}
-                          </Button>
-                        </div>
-                      </div>
-                    </div>
-                  )}
-                  {savedBackendMode !== "ssh" && savedBackendError ? (
-                    <p className="text-xs text-destructive">{savedBackendError}</p>
-                  ) : null}
-                  {savedBackendMode !== "ssh" ? (
-                    <Button
-                      variant="outline"
-                      className="w-full"
-                      disabled={isAddingSavedBackend}
-                      onClick={() => void handleAddSavedBackend()}
-                    >
-                      <PlusIcon className="size-3.5" />
-                      {isAddingSavedBackend ? "Adding…" : "Add Backend"}
-                    </Button>
-                  ) : null}
+                  <div className="grid gap-3 sm:grid-cols-2">
+                    {renderConnectionModeCard({
+                      mode: "remote",
+                      title: "Remote link",
+                      description: "Enter a backend host and pairing code.",
+                      icon: <ChevronsLeftRightEllipsisIcon aria-hidden className="size-4" />,
+                    })}
+                    {desktopBridge
+                      ? renderConnectionModeCard({
+                          mode: "ssh",
+                          title: "SSH",
+                          description: "Use local SSH config, agent, and tunnels for the backend.",
+                          icon: <TerminalIcon aria-hidden className="size-4" />,
+                        })
+                      : null}
+                  </div>
+                  <AnimatedHeight>
+                    {savedBackendMode === "ssh" ? renderSshFields() : renderRemoteModeBody()}
+                  </AnimatedHeight>
                 </div>
               </DialogPanel>
             </DialogPopup>
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 796306dc2f7..ba3f6e6d83e 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -1,12 +1,33 @@
 import { assert, describe, it } from "@effect/vitest";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Effect, Layer, Sink, Stream } from "effect";
+import { ChildProcessSpawner } from "effect/unstable/process";
 
 import {
   buildRemoteLaunchScript,
   buildRemotePairingScript,
   buildRemoteT3RunnerScript,
+  issueRemotePairingToken,
   REMOTE_PICK_PORT_SCRIPT,
 } from "./tunnel.ts";
 
+const makeSuccessfulProcess = (stdout: string) => {
+  const stdoutStream = Stream.make(new TextEncoder().encode(stdout));
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(123),
+    stdout: stdoutStream,
+    stderr: Stream.empty,
+    all: stdoutStream,
+    exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
+    isRunning: Effect.succeed(false),
+    kill: () => Effect.void,
+    stdin: Sink.drain,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    unref: Effect.succeed(Effect.void),
+  });
+};
+
 describe("ssh tunnel scripts", () => {
   it("builds the remote t3 runner with npx and npm fallbacks", () => {
     const script = buildRemoteT3RunnerScript();
@@ -41,4 +62,31 @@ describe("ssh tunnel scripts", () => {
   it("allows the remote port picker to run without a state file path", () => {
     assert.include(REMOTE_PICK_PORT_SCRIPT, 'const filePath = process.argv[2] ?? "";');
   });
+
+  it.effect("accepts pretty-printed pairing JSON from the remote CLI", () => {
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+    const spawner = ChildProcessSpawner.make(() =>
+      Effect.succeed(
+        makeSuccessfulProcess(`{
+  "id": "88941235-6ed5-4184-a2ff-5339e2075958",
+  "credential": "LCL4R2TPHDKQ",
+  "role": "client",
+  "expiresAt": "2026-04-29T01:01:20.994Z"
+}
+
+`),
+      ),
+    );
+    const spawnerLayer = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner);
+    const processLayer = Layer.merge(NodeServices.layer, spawnerLayer);
+    return Effect.gen(function* () {
+      const credential = yield* issueRemotePairingToken(target);
+      assert.equal(credential, "LCL4R2TPHDKQ");
+    }).pipe(Effect.provide(processLayer));
+  });
 });
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 64c1e2f6231..afd08c5b631 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -3,6 +3,7 @@ import type {
   DesktopSshEnvironmentTarget,
 } from "@t3tools/contracts";
 import { type NetError, NetService } from "@t3tools/shared/Net";
+import { fromLenientJson } from "@t3tools/shared/schemaJson";
 import {
   Deferred,
   Context,
@@ -117,8 +118,8 @@ const RemoteHttpError = Schema.Struct({
   error: Schema.optional(Schema.String),
 });
 
-const decodeRemoteLaunchResult = Schema.decodeEffect(Schema.fromJsonString(RemoteLaunchResult));
-const decodeRemotePairingResult = Schema.decodeEffect(Schema.fromJsonString(RemotePairingResult));
+const decodeRemoteLaunchResult = Schema.decodeEffect(fromLenientJson(RemoteLaunchResult));
+const decodeRemotePairingResult = Schema.decodeEffect(fromLenientJson(RemotePairingResult));
 const decodeRemoteHttpError = Schema.decodeEffect(Schema.fromJsonString(RemoteHttpError));
 
 export function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): string {
@@ -282,14 +283,13 @@ export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemo
       ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
       ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
     });
-    const line = getLastNonEmptyOutputLine(result.stdout);
-    if (!line) {
+    if (!getLastNonEmptyOutputLine(result.stdout)) {
       return yield* new SshLaunchError({
         message: "SSH launch did not return a remote port.",
         stdout: result.stdout,
       });
     }
-    const parsed = yield* decodeRemoteLaunchResult(line).pipe(
+    const parsed = yield* decodeRemoteLaunchResult(result.stdout).pipe(
       Effect.mapError(
         (cause) =>
           new SshLaunchError({
@@ -325,14 +325,13 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
     ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
     ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
   });
-  const line = getLastNonEmptyOutputLine(result.stdout);
-  if (!line) {
+  if (!getLastNonEmptyOutputLine(result.stdout)) {
     return yield* new SshPairingError({
       message: "SSH pairing did not return a credential.",
       stdout: result.stdout,
     });
   }
-  const parsed = yield* decodeRemotePairingResult(line).pipe(
+  const parsed = yield* decodeRemotePairingResult(result.stdout).pipe(
     Effect.mapError(
       (cause) =>
         new SshPairingError({

From db06e1fff1a0c43305ee4a9fc3e4d5b870687b56 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 13:14:52 -0700
Subject: [PATCH 39/74] Add hosted SSH pairing state handling

- Support remote T3 runner selection for hosted pairing
- Surface SSH/environment disconnect states in the UI
- Improve websocket snapshot and password prompt error handling
---
 apps/desktop/src/main.ts                      |  50 +++-
 apps/desktop/src/preload.ts                   |   3 +
 apps/desktop/src/sshEnvironment.ts            |  50 +++-
 apps/server/src/server.test.ts                |  29 +++
 apps/server/src/ws.ts                         |   3 +
 apps/web/src/components/ChatView.tsx          |  59 ++++-
 .../WebSocketConnectionSurface.logic.test.ts  |   1 +
 .../components/WebSocketConnectionSurface.tsx |  16 +-
 apps/web/src/components/chat/ChatComposer.tsx |  25 +-
 .../chat/ComposerPrimaryActions.tsx           |  29 ++-
 .../desktop/SshPasswordPromptDialog.tsx       | 120 +++++++--
 .../settings/ConnectionsSettings.tsx          |  90 +++++--
 .../settings/SettingsPanels.browser.tsx       |   1 +
 apps/web/src/environments/runtime/catalog.ts  |  18 ++
 .../service.addSavedEnvironment.test.ts       | 243 +++++++++++++++++-
 .../service.threadSubscriptions.test.ts       |   1 +
 apps/web/src/environments/runtime/service.ts  |  73 +++++-
 apps/web/src/localApi.test.ts                 |   1 +
 apps/web/src/rpc/protocol.ts                  |  66 +++--
 apps/web/src/rpc/wsConnectionState.test.ts    |   5 +-
 apps/web/src/rpc/wsConnectionState.ts         |  48 +++-
 apps/web/src/rpc/wsTransport.test.ts          |  53 +++-
 apps/web/src/rpc/wsTransport.ts               |   9 +-
 packages/contracts/src/ipc.ts                 |   2 +
 packages/ssh/src/command.test.ts              |  62 ++++-
 packages/ssh/src/command.ts                   |  20 +-
 packages/ssh/src/tunnel.test.ts               | 120 ++++++++-
 packages/ssh/src/tunnel.ts                    | 231 ++++++++++++++---
 28 files changed, 1268 insertions(+), 160 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 005cc1e43f6..af939cb768c 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -36,6 +36,7 @@ import { autoUpdater } from "electron-updater";
 import type { ContextMenuItem } from "@t3tools/contracts";
 import { RotatingFileSink } from "@t3tools/shared/logging";
 import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
+import type { RemoteT3RunnerOptions } from "@t3tools/ssh/tunnel";
 import { DEFAULT_DESKTOP_BACKEND_PORT, resolveDesktopBackendPort } from "./backendPort.ts";
 import {
   type DesktopSettings,
@@ -119,6 +120,12 @@ const SAVED_ENVIRONMENT_REGISTRY_PATH = Path.join(STATE_DIR, "saved-environments
 const DESKTOP_SCHEME = "t3";
 const ROOT_DIR = Path.resolve(__dirname, "../../..");
 const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
+// Dev-only SSH launcher override. Set this to an absolute path on the SSH host
+// for a built server entry, for example:
+// "/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs"
+const DEV_REMOTE_T3_SERVER_ENTRY_PATH =
+  process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ??
+  "/Users/julius/Developer/t3code/apps/server/dist/bin.mjs";
 const desktopAppBranding: DesktopAppBranding = resolveDesktopAppBranding({
   isDevelopment,
   appVersion: app.getVersion(),
@@ -365,7 +372,10 @@ function resolveCustomHttpsEndpointUrls(): readonly string[] {
 
 async function applyDesktopServerExposureMode(
   mode: DesktopServerExposureMode,
-  options?: { readonly persist?: boolean; readonly rejectIfUnavailable?: boolean },
+  options?: {
+    readonly persist?: boolean;
+    readonly rejectIfUnavailable?: boolean;
+  },
 ): Promise<DesktopServerExposureState> {
   const advertisedHostOverride = resolveAdvertisedHostOverride();
   const requestedMode = mode;
@@ -685,12 +695,18 @@ let updateState: DesktopUpdateState = initialUpdateState();
 
 const desktopSshEnvironmentBridge = new DesktopSshEnvironmentBridge({
   getMainWindow: () => mainWindow,
-  resolveCliPackageSpec: () =>
-    resolveRemoteT3CliPackageSpec({
-      appVersion: app.getVersion(),
-      updateChannel: desktopSettings.updateChannel,
-      isDevelopment,
-    }),
+  resolveCliRunner: (): RemoteT3RunnerOptions => {
+    if (isDevelopment && DEV_REMOTE_T3_SERVER_ENTRY_PATH.length > 0) {
+      return { nodeScriptPath: DEV_REMOTE_T3_SERVER_ENTRY_PATH };
+    }
+    return {
+      packageSpec: resolveRemoteT3CliPackageSpec({
+        appVersion: app.getVersion(),
+        updateChannel: desktopSettings.updateChannel,
+        isDevelopment,
+      }),
+    };
+  },
 });
 
 function resolveUpdaterErrorContext(): DesktopUpdateErrorContext {
@@ -1244,7 +1260,10 @@ async function checkForUpdates(reason: string): Promise<boolean> {
   }
 }
 
-async function downloadAvailableUpdate(): Promise<{ accepted: boolean; completed: boolean }> {
+async function downloadAvailableUpdate(): Promise<{
+  accepted: boolean;
+  completed: boolean;
+}> {
   if (!updaterConfigured || updateDownloadInFlight || updateState.status !== "available") {
     return { accepted: false, completed: false };
   }
@@ -1266,7 +1285,10 @@ async function downloadAvailableUpdate(): Promise<{ accepted: boolean; completed
   }
 }
 
-async function installDownloadedUpdate(): Promise<{ accepted: boolean; completed: boolean }> {
+async function installDownloadedUpdate(): Promise<{
+  accepted: boolean;
+  completed: boolean;
+}> {
   if (isQuitting || !updaterConfigured || updateState.status !== "downloaded") {
     return { accepted: false, completed: false };
   }
@@ -1742,7 +1764,10 @@ function registerIpcHandlers(): void {
     if (typeof rawInput !== "object" || rawInput === null) {
       throw new Error("Invalid Tailscale Serve input.");
     }
-    const input = rawInput as { readonly enabled?: unknown; readonly port?: unknown };
+    const input = rawInput as {
+      readonly enabled?: unknown;
+      readonly port?: unknown;
+    };
     if (typeof input.enabled !== "boolean") {
       throw new Error("Invalid Tailscale Serve input.");
     }
@@ -2049,7 +2074,10 @@ function createWindow(): BrowserWindow {
     const externalUrl = getSafeExternalUrl(params.linkURL);
     if (externalUrl) {
       menuTemplate.push(
-        { label: "Copy Link", click: () => clipboard.writeText(params.linkURL) },
+        {
+          label: "Copy Link",
+          click: () => clipboard.writeText(params.linkURL),
+        },
         { type: "separator" },
       );
     }
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index d9ae6ed936a..c094cbada2a 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -24,6 +24,7 @@ const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secr
 const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
 const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
 const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
+const DISCONNECT_SSH_ENVIRONMENT_CHANNEL = "desktop:disconnect-ssh-environment";
 const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
 const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
 const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
@@ -64,6 +65,8 @@ contextBridge.exposeInMainWorld("desktopBridge", {
   discoverSshHosts: () => ipcRenderer.invoke(DISCOVER_SSH_HOSTS_CHANNEL),
   ensureSshEnvironment: (target, options) =>
     ipcRenderer.invoke(ENSURE_SSH_ENVIRONMENT_CHANNEL, target, options),
+  disconnectSshEnvironment: (target) =>
+    ipcRenderer.invoke(DISCONNECT_SSH_ENVIRONMENT_CHANNEL, target),
   fetchSshEnvironmentDescriptor: (httpBaseUrl) =>
     ipcRenderer.invoke(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, httpBaseUrl),
   bootstrapSshBearerSession: (httpBaseUrl, credential) =>
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 97bad24d056..e636e87d6d8 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -19,13 +19,18 @@ import {
 } from "@t3tools/ssh/auth";
 import { discoverSshHosts } from "@t3tools/ssh/config";
 import { SshPasswordPromptError } from "@t3tools/ssh/errors";
-import { fetchLoopbackSshJson, SshEnvironmentManager } from "@t3tools/ssh/tunnel";
+import {
+  fetchLoopbackSshJson,
+  SshEnvironmentManager,
+  type RemoteT3RunnerOptions,
+} from "@t3tools/ssh/tunnel";
 import { Effect, Exit, Layer, ManagedRuntime, Scope } from "effect";
 
 export { resolveRemoteT3CliPackageSpec } from "@t3tools/ssh/command";
 
 const DISCOVER_SSH_HOSTS_CHANNEL = "desktop:discover-ssh-hosts";
 const ENSURE_SSH_ENVIRONMENT_CHANNEL = "desktop:ensure-ssh-environment";
+const DISCONNECT_SSH_ENVIRONMENT_CHANNEL = "desktop:disconnect-ssh-environment";
 const FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL = "desktop:fetch-ssh-environment-descriptor";
 const BOOTSTRAP_SSH_BEARER_SESSION_CHANNEL = "desktop:bootstrap-ssh-bearer-session";
 const FETCH_SSH_SESSION_STATE_CHANNEL = "desktop:fetch-ssh-session-state";
@@ -37,6 +42,7 @@ const DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
 interface DesktopSshEnvironmentManagerOptions {
   readonly passwordProvider?: (request: SshPasswordRequest) => Promise<string | null>;
   readonly resolveCliPackageSpec?: () => string;
+  readonly resolveCliRunner?: () => RemoteT3RunnerOptions;
 }
 
 const sshRuntime = ManagedRuntime.make(
@@ -55,11 +61,14 @@ function createDesktopSshRuntime(
       NetService.layer,
       Layer.succeed(Scope.Scope, scope),
       Layer.succeed(SshPasswordPrompt, SshPasswordPrompt.of(passwordPrompt)),
-      SshEnvironmentManager.layer(
-        options.resolveCliPackageSpec === undefined
+      SshEnvironmentManager.layer({
+        ...(options.resolveCliPackageSpec === undefined
           ? {}
-          : { resolveCliPackageSpec: options.resolveCliPackageSpec },
-      ),
+          : { resolveCliPackageSpec: options.resolveCliPackageSpec }),
+        ...(options.resolveCliRunner === undefined
+          ? {}
+          : { resolveCliRunner: options.resolveCliRunner }),
+      }),
     ),
   );
 }
@@ -112,6 +121,14 @@ export class DesktopSshEnvironmentManager {
     );
   }
 
+  async disconnectEnvironment(target: DesktopSshEnvironmentTarget): Promise<void> {
+    await this.runtime.runPromise(
+      Effect.service(SshEnvironmentManager).pipe(
+        Effect.flatMap((manager) => manager.disconnectEnvironment(target)),
+      ),
+    );
+  }
+
   async dispose(): Promise<void> {
     await this.runtime.runPromise(Scope.close(this.scope, Exit.void));
     await this.runtime.dispose();
@@ -174,7 +191,8 @@ export interface DesktopSshBridgeIpcMain {
 
 export interface DesktopSshEnvironmentBridgeOptions {
   readonly getMainWindow: () => DesktopSshBridgeWindow | null;
-  readonly resolveCliPackageSpec: () => string;
+  readonly resolveCliPackageSpec?: () => string;
+  readonly resolveCliRunner?: () => RemoteT3RunnerOptions;
   readonly passwordPromptTimeoutMs?: number;
 }
 
@@ -200,7 +218,12 @@ export class DesktopSshEnvironmentBridge {
       options.passwordPromptTimeoutMs ?? DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS;
     this.manager = new DesktopSshEnvironmentManager({
       passwordProvider: (request) => this.requestPasswordFromRenderer(request),
-      resolveCliPackageSpec: options.resolveCliPackageSpec,
+      ...(options.resolveCliPackageSpec === undefined
+        ? {}
+        : { resolveCliPackageSpec: options.resolveCliPackageSpec }),
+      ...(options.resolveCliRunner === undefined
+        ? {}
+        : { resolveCliRunner: options.resolveCliRunner }),
     });
   }
 
@@ -226,6 +249,16 @@ export class DesktopSshEnvironmentBridge {
       });
     });
 
+    ipcMain.removeHandler(DISCONNECT_SSH_ENVIRONMENT_CHANNEL);
+    ipcMain.handle(DISCONNECT_SSH_ENVIRONMENT_CHANNEL, async (_event, rawTarget) => {
+      const target = getSafeDesktopSshTarget(rawTarget);
+      if (!target) {
+        throw new Error("Invalid desktop SSH target.");
+      }
+
+      await this.manager.disconnectEnvironment(target);
+    });
+
     ipcMain.removeHandler(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL);
     ipcMain.handle(FETCH_SSH_ENVIRONMENT_DESCRIPTOR_CHANNEL, async (_event, rawHttpBaseUrl) =>
       sshRuntime.runPromise(
@@ -290,7 +323,7 @@ export class DesktopSshEnvironmentBridge {
 
         const pending = this.pendingPrompts.get(rawRequestId);
         if (!pending) {
-          throw new Error("SSH password prompt is no longer pending.");
+          throw new Error("SSH password prompt expired. Try connecting again.");
         }
 
         clearTimeout(pending.timeout);
@@ -324,6 +357,7 @@ export class DesktopSshEnvironmentBridge {
       destination: input.destination,
       username: input.username,
       prompt: input.prompt,
+      expiresAt: new Date(Date.now() + this.passwordPromptTimeoutMs).toISOString(),
     };
 
     return await new Promise<string | null>((resolve, reject) => {
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index fcbf4d50010..1e8f7cf0ebf 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -75,6 +75,7 @@ import {
   type ProjectionSnapshotQueryShape,
 } from "./orchestration/Services/ProjectionSnapshotQuery.ts";
 import { SqlitePersistenceMemory } from "./persistence/Layers/Sqlite.ts";
+import { PersistenceSqlError } from "./persistence/Errors.ts";
 import {
   ProviderRegistry,
   type ProviderRegistryShape,
@@ -3100,6 +3101,34 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("routes websocket rpc orchestration shell snapshot errors", () =>
+    Effect.gen(function* () {
+      const projectionError = new PersistenceSqlError({
+        operation: "ProjectionSnapshotQuery.getShellSnapshot:test",
+        detail: "failed to read projection shell snapshot",
+      });
+      yield* buildAppUnderTest({
+        layers: {
+          projectionSnapshotQuery: {
+            getShellSnapshot: () => Effect.fail(projectionError),
+          },
+        },
+      });
+
+      const wsUrl = yield* getWsServerUrl("/ws");
+      const result = yield* Effect.scoped(
+        withWsRpcClient(wsUrl, (client) =>
+          client[ORCHESTRATION_WS_METHODS.subscribeShell]({}).pipe(Stream.runCollect),
+        ).pipe(Effect.result),
+      );
+
+      assertTrue(result._tag === "Failure");
+      assertTrue(result.failure._tag === "OrchestrationGetSnapshotError");
+      assertTrue(result.failure.cause instanceof Error);
+      assert.include(result.failure.cause.message, projectionError.message);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect("enriches replayed project events with repository identity metadata", () =>
     Effect.gen(function* () {
       const repositoryIdentity = {
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index c3827d98bf6..bc05a328281 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -670,6 +670,9 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
             ORCHESTRATION_WS_METHODS.subscribeShell,
             Effect.gen(function* () {
               const snapshot = yield* projectionSnapshotQuery.getShellSnapshot().pipe(
+                Effect.tapError((cause) =>
+                  Effect.logError("orchestration shell snapshot load failed", { cause }),
+                ),
                 Effect.mapError(
                   (cause) =>
                     new OrchestrationGetSnapshotError({
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 40cd1b42105..937b17a64ba 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -104,7 +104,7 @@ import { BranchToolbar } from "./BranchToolbar";
 import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings";
 import PlanSidebar from "./PlanSidebar";
 import ThreadTerminalDrawer from "./ThreadTerminalDrawer";
-import { ChevronDownIcon } from "lucide-react";
+import { ChevronDownIcon, WifiOffIcon } from "lucide-react";
 import { cn, randomUUID } from "~/lib/utils";
 import { stackedThreadToast, toastManager } from "./ui/toast";
 import { decodeProjectScriptKeybindingRule } from "~/lib/projectScriptKeybindings";
@@ -180,6 +180,8 @@ import {
 import { sanitizeThreadErrorMessage } from "~/rpc/transportError";
 import { retainThreadDetailSubscription } from "../environments/runtime/service";
 import { RightPanelSheet } from "./RightPanelSheet";
+import { Alert, AlertAction, AlertDescription, AlertTitle } from "./ui/alert";
+import { Button } from "./ui/button";
 
 const IMAGE_ONLY_BOOTSTRAP_PROMPT =
   "[User attached one or more images without additional text. Respond using the conversation context and the attached image(s).]";
@@ -187,6 +189,10 @@ const EMPTY_ACTIVITIES: OrchestrationThreadActivity[] = [];
 const EMPTY_PROPOSED_PLANS: Thread["proposedPlans"] = [];
 const EMPTY_PROVIDERS: ServerProvider[] = [];
 const EMPTY_PENDING_USER_INPUT_ANSWERS: Record<string, PendingUserInputDraftAnswer> = {};
+type EnvironmentUnavailableState = {
+  readonly label: string;
+  readonly connectionState: "connecting" | "disconnected" | "error";
+};
 
 type ThreadPlanCatalogEntry = Pick<Thread, "id" | "proposedPlans">;
 
@@ -855,6 +861,37 @@ export default function ChatView(props: ChatViewProps) {
   const primaryEnvironmentId = usePrimaryEnvironmentId();
   const savedEnvironmentRegistry = useSavedEnvironmentRegistryStore((s) => s.byId);
   const savedEnvironmentRuntimeById = useSavedEnvironmentRuntimeStore((s) => s.byId);
+  const activeSavedEnvironmentRecord =
+    activeThread && activeThread.environmentId !== primaryEnvironmentId
+      ? (savedEnvironmentRegistry[activeThread.environmentId] ?? null)
+      : null;
+  const activeSavedEnvironmentRuntime = activeSavedEnvironmentRecord
+    ? (savedEnvironmentRuntimeById[activeSavedEnvironmentRecord.environmentId] ?? null)
+    : null;
+  const activeSavedEnvironmentConnectionState = activeSavedEnvironmentRecord
+    ? (activeSavedEnvironmentRuntime?.connectionState ?? "disconnected")
+    : "connected";
+  const activeEnvironmentUnavailable =
+    activeSavedEnvironmentRecord !== null && activeSavedEnvironmentConnectionState !== "connected";
+  const activeEnvironmentUnavailableLabel = activeSavedEnvironmentRecord
+    ? resolveEnvironmentOptionLabel({
+        isPrimary: false,
+        environmentId: activeSavedEnvironmentRecord.environmentId,
+        runtimeLabel: activeSavedEnvironmentRuntime?.descriptor?.label ?? null,
+        savedLabel: activeSavedEnvironmentRecord.label,
+      })
+    : null;
+  const activeEnvironmentUnavailableState: EnvironmentUnavailableState | null =
+    activeEnvironmentUnavailable && activeEnvironmentUnavailableLabel
+      ? {
+          label: activeEnvironmentUnavailableLabel,
+          connectionState:
+            activeSavedEnvironmentConnectionState === "connecting" ||
+            activeSavedEnvironmentConnectionState === "error"
+              ? activeSavedEnvironmentConnectionState
+              : "disconnected",
+        }
+      : null;
   const projectGroupingSettings = useSettings((settings) => ({
     sidebarProjectGroupingMode: settings.sidebarProjectGroupingMode,
     sidebarProjectGroupingOverrides: settings.sidebarProjectGroupingOverrides,
@@ -2354,6 +2391,13 @@ export default function ChatView(props: ChatViewProps) {
       const localApi = readLocalApi();
       if (!api || !localApi || !activeThread || isRevertingCheckpoint) return;
 
+      if (activeEnvironmentUnavailable && activeEnvironmentUnavailableLabel) {
+        setThreadError(
+          activeThread.id,
+          `Reconnect ${activeEnvironmentUnavailableLabel} before reverting checkpoints.`,
+        );
+        return;
+      }
       if (phase === "running" || isSendBusy || isConnecting) {
         setThreadError(activeThread.id, "Interrupt the current turn before reverting checkpoints.");
         return;
@@ -2389,6 +2433,8 @@ export default function ChatView(props: ChatViewProps) {
     },
     [
       activeThread,
+      activeEnvironmentUnavailable,
+      activeEnvironmentUnavailableLabel,
       environmentId,
       isConnecting,
       isRevertingCheckpoint,
@@ -2401,7 +2447,15 @@ export default function ChatView(props: ChatViewProps) {
   const onSend = async (e?: { preventDefault: () => void }) => {
     e?.preventDefault();
     const api = readEnvironmentApi(environmentId);
-    if (!api || !activeThread || isSendBusy || isConnecting || sendInFlightRef.current) return;
+    if (
+      !api ||
+      !activeThread ||
+      isSendBusy ||
+      isConnecting ||
+      activeEnvironmentUnavailable ||
+      sendInFlightRef.current
+    )
+      return;
     if (activePendingProgress) {
       onAdvanceActivePendingUserInput();
       return;
@@ -3398,6 +3452,7 @@ export default function ChatView(props: ChatViewProps) {
               isConnecting={isConnecting}
               isSendBusy={isSendBusy}
               isPreparingWorktree={isPreparingWorktree}
+              environmentUnavailable={activeEnvironmentUnavailableState}
               activePendingApproval={activePendingApproval}
               pendingApprovals={pendingApprovals}
               pendingUserInputs={pendingUserInputs}
diff --git a/apps/web/src/components/WebSocketConnectionSurface.logic.test.ts b/apps/web/src/components/WebSocketConnectionSurface.logic.test.ts
index aed81ab01c7..9a7e484dc20 100644
--- a/apps/web/src/components/WebSocketConnectionSurface.logic.test.ts
+++ b/apps/web/src/components/WebSocketConnectionSurface.logic.test.ts
@@ -8,6 +8,7 @@ function makeStatus(overrides: Partial<WsConnectionStatus> = {}): WsConnectionSt
     attemptCount: 0,
     closeCode: null,
     closeReason: null,
+    connectionLabel: null,
     connectedAt: null,
     disconnectedAt: null,
     hasConnected: false,
diff --git a/apps/web/src/components/WebSocketConnectionSurface.tsx b/apps/web/src/components/WebSocketConnectionSurface.tsx
index e0bb560980a..b54bd865c8b 100644
--- a/apps/web/src/components/WebSocketConnectionSurface.tsx
+++ b/apps/web/src/components/WebSocketConnectionSurface.tsx
@@ -53,8 +53,16 @@ function describeExhaustedToast(): string {
   return "Retries exhausted trying to reconnect";
 }
 
-function buildReconnectTitle(_status: WsConnectionStatus): string {
-  return "Disconnected from T3 Server";
+function getConnectionDisplayName(status: WsConnectionStatus): string {
+  return status.connectionLabel?.trim() || "T3 Server";
+}
+
+function buildReconnectTitle(status: WsConnectionStatus): string {
+  return `Disconnected from ${getConnectionDisplayName(status)}`;
+}
+
+function buildRecoveredTitle(status: WsConnectionStatus): string {
+  return `Reconnected to ${getConnectionDisplayName(status)}`;
 }
 
 function describeRecoveredToast(
@@ -297,7 +305,7 @@ export function WebSocketConnectionCoordinator() {
               },
               description: describeExhaustedToast(),
               timeout: 0,
-              title: "Disconnected from T3 Server",
+              title: buildReconnectTitle(status),
               type: "error",
             })
           : stackedThreadToast({
@@ -334,7 +342,7 @@ export function WebSocketConnectionCoordinator() {
     ) {
       const successToast = {
         description: describeRecoveredToast(previousDisconnectedAt, status.connectedAt),
-        title: "Reconnected to T3 Server",
+        title: buildRecoveredTitle(status),
         type: "success" as const,
         timeout: 0,
         data: {
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index 2b7f62e8af7..8d0ad171dba 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -289,6 +289,7 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
   promptHasText: boolean;
   isSendBusy: boolean;
   isConnecting: boolean;
+  isEnvironmentUnavailable: boolean;
   hasSendableContent: boolean;
   onPreviousPendingQuestion: () => void;
   onInterrupt: () => void;
@@ -308,6 +309,7 @@ const ComposerFooterPrimaryActions = memo(function ComposerFooterPrimaryActions(
         promptHasText={props.promptHasText}
         isSendBusy={props.isSendBusy}
         isConnecting={props.isConnecting}
+        isEnvironmentUnavailable={props.isEnvironmentUnavailable}
         isPreparingWorktree={props.isPreparingWorktree}
         hasSendableContent={props.hasSendableContent}
         onPreviousPendingQuestion={props.onPreviousPendingQuestion}
@@ -379,6 +381,10 @@ export interface ChatComposerProps {
   isConnecting: boolean;
   isSendBusy: boolean;
   isPreparingWorktree: boolean;
+  environmentUnavailable: {
+    readonly label: string;
+    readonly connectionState: "connecting" | "disconnected" | "error";
+  } | null;
 
   // Pending approvals / inputs
   activePendingApproval: PendingApproval | null;
@@ -486,6 +492,7 @@ export const ChatComposer = memo(
       isConnecting,
       isSendBusy,
       isPreparingWorktree,
+      environmentUnavailable,
       activePendingApproval,
       pendingApprovals,
       pendingUserInputs,
@@ -1821,6 +1828,7 @@ export const ChatComposer = memo(
             className={cn(
               "rounded-[20px] border bg-card transition-colors duration-200 has-focus-visible:border-ring/45",
               isDragOverComposer ? "border-primary/70 bg-accent/30" : "border-border",
+              environmentUnavailable ? "opacity-75" : null,
               composerProviderState.composerSurfaceClassName,
             )}
           >
@@ -1970,11 +1978,19 @@ export const ChatComposer = memo(
                       ? "Type your own answer, or leave this blank to use the selected option"
                       : showPlanFollowUpPrompt && activeProposedPlan
                         ? "Add feedback to refine the plan, or leave this blank to implement it"
-                        : phase === "disconnected"
-                          ? "Ask for follow-up changes or attach images"
-                          : "Ask anything, @tag files/folders, or use / to show available commands"
+                        : environmentUnavailable
+                          ? `${environmentUnavailable.label} is ${
+                              environmentUnavailable.connectionState === "connecting"
+                                ? "connecting"
+                                : "disconnected"
+                            }`
+                          : phase === "disconnected"
+                            ? "Ask for follow-up changes or attach images"
+                            : "Ask anything, @tag files/folders, or use / to show available commands"
+                }
+                disabled={
+                  isConnecting || isComposerApprovalState || environmentUnavailable !== null
                 }
-                disabled={isConnecting || isComposerApprovalState}
               />
             </div>
 
@@ -2080,6 +2096,7 @@ export const ChatComposer = memo(
                     promptHasText={prompt.trim().length > 0}
                     isSendBusy={isSendBusy}
                     isConnecting={isConnecting}
+                    isEnvironmentUnavailable={environmentUnavailable !== null}
                     isPreparingWorktree={isPreparingWorktree}
                     hasSendableContent={composerSendState.hasSendableContent}
                     onPreviousPendingQuestion={onPreviousActivePendingUserInputQuestion}
diff --git a/apps/web/src/components/chat/ComposerPrimaryActions.tsx b/apps/web/src/components/chat/ComposerPrimaryActions.tsx
index 2bc40fe6ae8..61833fecaa8 100644
--- a/apps/web/src/components/chat/ComposerPrimaryActions.tsx
+++ b/apps/web/src/components/chat/ComposerPrimaryActions.tsx
@@ -20,6 +20,7 @@ interface ComposerPrimaryActionsProps {
   promptHasText: boolean;
   isSendBusy: boolean;
   isConnecting: boolean;
+  isEnvironmentUnavailable: boolean;
   isPreparingWorktree: boolean;
   hasSendableContent: boolean;
   onPreviousPendingQuestion: () => void;
@@ -53,6 +54,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
   promptHasText,
   isSendBusy,
   isConnecting,
+  isEnvironmentUnavailable,
   isPreparingWorktree,
   hasSendableContent,
   onPreviousPendingQuestion,
@@ -91,6 +93,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
           size="sm"
           className={cn("rounded-full", compact ? "px-3" : "px-4")}
           disabled={
+            isEnvironmentUnavailable ||
             pendingAction.isResponding ||
             (pendingAction.isLastQuestion ? !pendingAction.isComplete : !pendingAction.canAdvance)
           }
@@ -128,7 +131,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
           type="submit"
           size="sm"
           className={cn("rounded-full", compact ? "h-9 px-3 sm:h-8" : "h-9 px-4 sm:h-8")}
-          disabled={isSendBusy || isConnecting}
+          disabled={isSendBusy || isConnecting || isEnvironmentUnavailable}
         >
           {isConnecting || isSendBusy ? "Sending..." : "Refine"}
         </Button>
@@ -141,7 +144,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
           type="submit"
           size="sm"
           className="h-9 rounded-l-full rounded-r-none px-4 sm:h-8"
-          disabled={isSendBusy || isConnecting}
+          disabled={isSendBusy || isConnecting || isEnvironmentUnavailable}
         >
           {isConnecting || isSendBusy ? "Sending..." : "Implement"}
         </Button>
@@ -153,7 +156,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
                 variant="default"
                 className="h-9 rounded-l-none rounded-r-full border-l-white/12 px-2 sm:h-8"
                 aria-label="Implementation actions"
-                disabled={isSendBusy || isConnecting}
+                disabled={isSendBusy || isConnecting || isEnvironmentUnavailable}
               />
             }
           >
@@ -161,7 +164,7 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
           </MenuTrigger>
           <MenuPopup align="end" side="top">
             <MenuItem
-              disabled={isSendBusy || isConnecting}
+              disabled={isSendBusy || isConnecting || isEnvironmentUnavailable}
               onClick={() => void onImplementPlanInNewThread()}
             >
               Implement in a new thread
@@ -176,15 +179,17 @@ export const ComposerPrimaryActions = memo(function ComposerPrimaryActions({
     <button
       type="submit"
       className="flex h-9 w-9 enabled:cursor-pointer items-center justify-center rounded-full bg-primary/90 text-primary-foreground transition-all duration-150 hover:bg-primary hover:scale-105 disabled:pointer-events-none disabled:opacity-30 disabled:hover:scale-100 sm:h-8 sm:w-8"
-      disabled={isSendBusy || isConnecting || !hasSendableContent}
+      disabled={isSendBusy || isConnecting || isEnvironmentUnavailable || !hasSendableContent}
       aria-label={
-        isConnecting
-          ? "Connecting"
-          : isPreparingWorktree
-            ? "Preparing worktree"
-            : isSendBusy
-              ? "Sending"
-              : "Send message"
+        isEnvironmentUnavailable
+          ? "Environment disconnected"
+          : isConnecting
+            ? "Connecting"
+            : isPreparingWorktree
+              ? "Preparing worktree"
+              : isSendBusy
+                ? "Sending"
+                : "Send message"
       }
     >
       {isConnecting || isSendBusy ? (
diff --git a/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
index 00df682700a..7a20badf02b 100644
--- a/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
+++ b/apps/web/src/components/desktop/SshPasswordPromptDialog.tsx
@@ -17,10 +17,23 @@ function describeSshTarget(request: DesktopSshPasswordPromptRequest): string {
   return request.username ? `${request.username}@${request.destination}` : request.destination;
 }
 
+function formatRemainingSeconds(seconds: number): string {
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}
+
+function getPromptErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : "SSH password prompt failed.";
+  return message.includes("expired") || message.includes("no longer pending")
+    ? "This SSH password prompt expired. Try connecting again."
+    : message;
+}
+
 export function SshPasswordPromptDialog() {
   const [queue, setQueue] = useState<readonly DesktopSshPasswordPromptRequest[]>([]);
   const [password, setPassword] = useState("");
   const [isResponding, setIsResponding] = useState(false);
+  const [now, setNow] = useState(() => Date.now());
+  const [responseError, setResponseError] = useState<string | null>(null);
   const currentRequest = queue[0] ?? null;
   const inputRef = useRef<HTMLInputElement | null>(null);
   const isRespondingRef = useRef(false);
@@ -39,10 +52,12 @@ export function SshPasswordPromptDialog() {
 
   useEffect(() => {
     setPassword("");
+    setResponseError(null);
     if (!currentRequest) {
       return;
     }
 
+    setNow(Date.now());
     const frame = window.requestAnimationFrame(() => {
       inputRef.current?.focus();
       inputRef.current?.select();
@@ -52,28 +67,83 @@ export function SshPasswordPromptDialog() {
     };
   }, [currentRequest]);
 
+  useEffect(() => {
+    if (!currentRequest) {
+      return;
+    }
+
+    const interval = window.setInterval(() => {
+      setNow(Date.now());
+    }, 1_000);
+    return () => {
+      window.clearInterval(interval);
+    };
+  }, [currentRequest]);
+
+  const expiresAtMs = currentRequest ? Date.parse(currentRequest.expiresAt) : Number.NaN;
+  const remainingMs = Number.isFinite(expiresAtMs) ? Math.max(0, expiresAtMs - now) : null;
+  const isExpired = remainingMs !== null && remainingMs <= 0;
+  const remainingSeconds = remainingMs === null ? null : Math.ceil(remainingMs / 1_000);
+  const remainingLabel =
+    remainingSeconds === null ? null : formatRemainingSeconds(remainingSeconds);
+
+  useEffect(() => {
+    if (isExpired) {
+      setResponseError("This SSH password prompt expired. Try connecting again.");
+    }
+  }, [isExpired]);
+
+  const removeCurrentPrompt = (requestId: string) => {
+    setQueue((currentQueue) =>
+      currentQueue[0]?.requestId === requestId ? currentQueue.slice(1) : currentQueue,
+    );
+    setPassword("");
+    setResponseError(null);
+  };
+
   const respond = async (nextPassword: string | null) => {
     if (!currentRequest || isRespondingRef.current) {
       return;
     }
 
     const requestId = currentRequest.requestId;
+    if (nextPassword !== null && isExpired) {
+      setResponseError("This SSH password prompt expired. Try connecting again.");
+      return;
+    }
+
     isRespondingRef.current = true;
     setIsResponding(true);
+    setResponseError(null);
     try {
       await window.desktopBridge?.resolveSshPasswordPrompt(requestId, nextPassword);
+      removeCurrentPrompt(requestId);
     } catch (error) {
-      console.error("Failed to resolve SSH password prompt.", error);
+      if (nextPassword === null) {
+        removeCurrentPrompt(requestId);
+      } else {
+        setResponseError(getPromptErrorMessage(error));
+      }
     } finally {
-      setQueue((currentQueue) =>
-        currentQueue[0]?.requestId === requestId ? currentQueue.slice(1) : currentQueue,
-      );
-      setPassword("");
       isRespondingRef.current = false;
       setIsResponding(false);
     }
   };
 
+  const dismissExpiredPrompt = () => {
+    if (currentRequest) {
+      removeCurrentPrompt(currentRequest.requestId);
+    }
+  };
+
+  const cancelPrompt = () => {
+    if (isExpired) {
+      dismissExpiredPrompt();
+      return;
+    }
+    void respond(null);
+  };
+
   const target = currentRequest ? describeSshTarget(currentRequest) : null;
 
   return (
@@ -81,7 +151,7 @@ export function SshPasswordPromptDialog() {
       open={currentRequest !== null}
       onOpenChange={(open) => {
         if (!open) {
-          void respond(null);
+          cancelPrompt();
         }
       }}
     >
@@ -104,32 +174,44 @@ export function SshPasswordPromptDialog() {
             }}
           >
             <div className="space-y-2">
-              <p className="text-sm font-medium text-foreground">{currentRequest?.prompt}</p>
+              <div className="flex items-center justify-between gap-3">
+                <p className="text-sm font-medium text-foreground">{currentRequest?.prompt}</p>
+                {remainingLabel ? (
+                  <span
+                    className={
+                      isExpired
+                        ? "shrink-0 text-xs font-medium text-destructive"
+                        : "shrink-0 text-xs text-muted-foreground"
+                    }
+                  >
+                    {isExpired ? "Expired" : remainingLabel}
+                  </span>
+                ) : null}
+              </div>
               <Input
                 ref={inputRef}
                 autoComplete="current-password"
-                disabled={isResponding}
+                disabled={isResponding || isExpired}
                 name="ssh-password"
                 type="password"
                 value={password}
                 onChange={(event) => setPassword(event.target.value)}
               />
             </div>
-            <p className="text-sm text-muted-foreground">
-              Use SSH keys to avoid repeated password prompts on new SSH sessions.
-            </p>
+            {responseError ? (
+              <p className="text-sm text-destructive">{responseError}</p>
+            ) : (
+              <p className="text-sm text-muted-foreground">
+                Use SSH keys to avoid repeated password prompts on new SSH sessions.
+              </p>
+            )}
           </form>
         </DialogPanel>
         <DialogFooter>
-          <Button
-            disabled={isResponding}
-            type="button"
-            variant="outline"
-            onClick={() => void respond(null)}
-          >
-            Cancel
+          <Button disabled={isResponding} type="button" variant="outline" onClick={cancelPrompt}>
+            {isExpired ? "Dismiss" : "Cancel"}
           </Button>
-          <Button disabled={isResponding} form={formId} type="submit">
+          <Button disabled={isResponding || isExpired} form={formId} type="submit">
             Continue
           </Button>
         </DialogFooter>
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index a53ad22ab50..bfba67f12a6 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -89,6 +89,7 @@ import {
   useSavedEnvironmentRuntimeStore,
   addSavedEnvironment,
   connectDesktopSshEnvironment,
+  disconnectSavedEnvironment,
   getPrimaryEnvironmentConnection,
   reconnectSavedEnvironment,
   removeSavedEnvironment,
@@ -171,16 +172,33 @@ function AnimatedHeight({ children }: { readonly children: ReactNode }) {
   useLayoutEffect(() => {
     const element = contentRef.current;
     if (!element) return;
+    let firstFrameId: number | null = null;
+    let secondFrameId: number | null = null;
 
     const updateHeight = () => {
-      const nextHeight = element.getBoundingClientRect().height;
+      const nextHeight = Math.ceil(element.scrollHeight || element.getBoundingClientRect().height);
       setHeight((currentHeight) => (currentHeight === nextHeight ? currentHeight : nextHeight));
     };
+    const updateHeightAfterPaint = () => {
+      updateHeight();
+      firstFrameId = window.requestAnimationFrame(() => {
+        updateHeight();
+        secondFrameId = window.requestAnimationFrame(updateHeight);
+      });
+    };
 
-    updateHeight();
-    const resizeObserver = new ResizeObserver(updateHeight);
+    updateHeightAfterPaint();
+    const resizeObserver = new ResizeObserver(updateHeightAfterPaint);
     resizeObserver.observe(element);
-    return () => resizeObserver.disconnect();
+    return () => {
+      resizeObserver.disconnect();
+      if (firstFrameId !== null) {
+        window.cancelAnimationFrame(firstFrameId);
+      }
+      if (secondFrameId !== null) {
+        window.cancelAnimationFrame(secondFrameId);
+      }
+    };
   }, []);
 
   return (
@@ -1157,16 +1175,20 @@ function NetworkAccessDescription({
 type SavedBackendListRowProps = {
   environmentId: EnvironmentId;
   reconnectingEnvironmentId: EnvironmentId | null;
+  disconnectingEnvironmentId: EnvironmentId | null;
   removingEnvironmentId: EnvironmentId | null;
-  onReconnect: (environmentId: EnvironmentId) => void;
+  onConnect: (environmentId: EnvironmentId) => void;
+  onDisconnect: (environmentId: EnvironmentId) => void;
   onRemove: (environmentId: EnvironmentId) => void;
 };
 
 function SavedBackendListRow({
   environmentId,
   reconnectingEnvironmentId,
+  disconnectingEnvironmentId,
   removingEnvironmentId,
-  onReconnect,
+  onConnect,
+  onDisconnect,
   onRemove,
 }: SavedBackendListRowProps) {
   const nowMs = useRelativeTimeTick(1_000);
@@ -1178,6 +1200,10 @@ function SavedBackendListRow({
   }
 
   const connectionState = runtime?.connectionState ?? "disconnected";
+  const isConnected = connectionState === "connected";
+  const isConnecting =
+    connectionState === "connecting" || reconnectingEnvironmentId === environmentId;
+  const isDisconnecting = disconnectingEnvironmentId === environmentId;
   const stateDotClassName =
     connectionState === "connected"
       ? "bg-success"
@@ -1188,6 +1214,7 @@ function SavedBackendListRow({
           : "bg-muted-foreground/40";
   const roleLabel = runtime?.role ? (runtime.role === "owner" ? "Owner" : "Client") : null;
   const descriptorLabel = runtime?.descriptor?.label ?? null;
+  const displayLabel = descriptorLabel ?? record.label;
   const statusTooltip = getSavedBackendStatusTooltip(runtime, record, nowMs);
   const metadataBits = [
     record.desktopSsh ? `SSH ${formatDesktopSshTarget(record.desktopSsh)}` : null,
@@ -1209,23 +1236,28 @@ function SavedBackendListRow({
                 connectionState === "connecting" ? "bg-warning/60 duration-2000" : null
               }
             />
-            <h3 className="text-sm font-medium text-foreground">{record.label}</h3>
+            <h3 className="text-sm font-medium text-foreground">{displayLabel}</h3>
           </div>
           {metadataBits.length > 0 ? (
             <p className="text-xs text-muted-foreground">{metadataBits.join(" · ")}</p>
           ) : null}
-          {descriptorLabel && descriptorLabel !== record.label ? (
-            <p className="text-xs text-muted-foreground">Server label: {descriptorLabel}</p>
-          ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
           <Button
             size="xs"
             variant="outline"
-            disabled={reconnectingEnvironmentId === environmentId}
-            onClick={() => void onReconnect(environmentId)}
+            disabled={isConnected ? isDisconnecting : isConnecting}
+            onClick={() =>
+              void (isConnected ? onDisconnect(environmentId) : onConnect(environmentId))
+            }
           >
-            {reconnectingEnvironmentId === environmentId ? "Reconnecting…" : "Reconnect"}
+            {isConnected
+              ? isDisconnecting
+                ? "Disconnecting…"
+                : "Disconnect"
+              : isConnecting
+                ? "Connecting…"
+                : "Connect"}
           </Button>
           <Button
             size="xs"
@@ -1373,6 +1405,8 @@ export function ConnectionsSettings() {
   );
   const [reconnectingSavedEnvironmentId, setReconnectingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
+  const [disconnectingSavedEnvironmentId, setDisconnectingSavedEnvironmentId] =
+    useState<EnvironmentId | null>(null);
   const [removingSavedEnvironmentId, setRemovingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
   const [isUpdatingDesktopServerExposure, setIsUpdatingDesktopServerExposure] = useState(false);
@@ -1668,18 +1702,18 @@ export function ConnectionsSettings() {
     savedBackendSshUsername,
   ]);
 
-  const handleReconnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
+  const handleConnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
     setReconnectingSavedEnvironmentId(environmentId);
     setSavedBackendError(null);
     try {
       await reconnectSavedEnvironment(environmentId);
     } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to reconnect backend.";
+      const message = error instanceof Error ? error.message : "Failed to connect backend.";
       setSavedBackendError(message);
       toastManager.add(
         stackedThreadToast({
           type: "error",
-          title: "Could not reconnect backend",
+          title: "Could not connect backend",
           description: message,
         }),
       );
@@ -1688,6 +1722,26 @@ export function ConnectionsSettings() {
     }
   }, []);
 
+  const handleDisconnectSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
+    setDisconnectingSavedEnvironmentId(environmentId);
+    setSavedBackendError(null);
+    try {
+      await disconnectSavedEnvironment(environmentId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to disconnect backend.";
+      setSavedBackendError(message);
+      toastManager.add(
+        stackedThreadToast({
+          type: "error",
+          title: "Could not disconnect backend",
+          description: message,
+        }),
+      );
+    } finally {
+      setDisconnectingSavedEnvironmentId(null);
+    }
+  }, []);
+
   const handleRemoveSavedBackend = useCallback(async (environmentId: EnvironmentId) => {
     setRemovingSavedEnvironmentId(environmentId);
     setSavedBackendError(null);
@@ -2550,8 +2604,10 @@ export function ConnectionsSettings() {
             key={environmentId}
             environmentId={environmentId}
             reconnectingEnvironmentId={reconnectingSavedEnvironmentId}
+            disconnectingEnvironmentId={disconnectingSavedEnvironmentId}
             removingEnvironmentId={removingSavedEnvironmentId}
-            onReconnect={handleReconnectSavedBackend}
+            onConnect={handleConnectSavedBackend}
+            onDisconnect={handleDisconnectSavedBackend}
             onRemove={handleRemoveSavedBackend}
           />
         ))}
diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index eaff6939fc0..14a6e76edc1 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -308,6 +308,7 @@ const createDesktopBridgeStub = (overrides?: {
       wsBaseUrl: "ws://127.0.0.1:3774/",
       pairingToken: "ssh-pairing-token",
     })),
+    disconnectSshEnvironment: vi.fn().mockResolvedValue(undefined),
     fetchSshEnvironmentDescriptor: vi.fn().mockResolvedValue({
       environmentId: "environment-ssh",
       label: "SSH environment",
diff --git a/apps/web/src/environments/runtime/catalog.ts b/apps/web/src/environments/runtime/catalog.ts
index bf260ab5711..7ece1ccb0ca 100644
--- a/apps/web/src/environments/runtime/catalog.ts
+++ b/apps/web/src/environments/runtime/catalog.ts
@@ -29,6 +29,7 @@ interface SavedEnvironmentRegistryStore extends SavedEnvironmentRegistryState {
   readonly upsert: (record: SavedEnvironmentRecord) => void;
   readonly remove: (environmentId: EnvironmentId) => void;
   readonly markConnected: (environmentId: EnvironmentId, connectedAt: string) => void;
+  readonly rename: (environmentId: EnvironmentId, label: string) => void;
   readonly reset: () => void;
 }
 
@@ -150,6 +151,23 @@ export const useSavedEnvironmentRegistryStore = create<SavedEnvironmentRegistryS
       persistSavedEnvironmentRegistryState(byId);
       return { byId };
     }),
+  rename: (environmentId, label) =>
+    set((state) => {
+      const existing = state.byId[environmentId];
+      const nextLabel = label.trim();
+      if (!existing || nextLabel.length === 0 || existing.label === nextLabel) {
+        return state;
+      }
+      const byId = {
+        ...state.byId,
+        [environmentId]: {
+          ...existing,
+          label: nextLabel,
+        },
+      };
+      persistSavedEnvironmentRegistryState(byId);
+      return { byId };
+    }),
   reset: () => {
     persistSavedEnvironmentRegistryState({});
     set({
diff --git a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
index a6ee6c5d222..ca75f2a522d 100644
--- a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
+++ b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
@@ -1,5 +1,5 @@
 import { EnvironmentId } from "@t3tools/contracts";
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 let mockSavedRecords: Array<Record<string, unknown>> = [];
 
@@ -32,6 +32,11 @@ const mockMarkConnected = vi.fn((environmentId: EnvironmentId, connectedAt: stri
     record.environmentId === environmentId ? { ...record, lastConnectedAt: connectedAt } : record,
   );
 });
+const mockRename = vi.fn((environmentId: EnvironmentId, label: string) => {
+  mockSavedRecords = mockSavedRecords.map((record) =>
+    record.environmentId === environmentId ? { ...record, label } : record,
+  );
+});
 const mockUpsert = vi.fn((record: Record<string, unknown>) => {
   mockSavedRecords = [
     ...mockSavedRecords.filter((entry) => entry.environmentId !== record.environmentId),
@@ -40,6 +45,7 @@ const mockUpsert = vi.fn((record: Record<string, unknown>) => {
 });
 const mockListSavedEnvironmentRecords = vi.fn(() => mockSavedRecords);
 const mockEnsureSshEnvironment = vi.fn();
+const mockDisconnectSshEnvironment = vi.fn();
 const mockFetchSshEnvironmentDescriptor = vi.fn();
 const mockToPersistedSavedEnvironmentRecord = vi.fn((record) => record);
 const mockCreateEnvironmentConnection = vi.fn();
@@ -83,6 +89,7 @@ vi.mock("./catalog", () => ({
       upsert: mockUpsert,
       remove: mockRemove,
       markConnected: mockMarkConnected,
+      rename: mockRename,
     }),
     setState: mockRegistrySetState,
     subscribe: vi.fn(() => () => {}),
@@ -118,6 +125,10 @@ vi.mock("../../rpc/wsTransport", () => ({
 }));
 
 describe("addSavedEnvironment", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   beforeEach(() => {
     vi.resetModules();
     vi.clearAllMocks();
@@ -125,6 +136,7 @@ describe("addSavedEnvironment", () => {
     vi.stubGlobal("window", {
       desktopBridge: {
         ensureSshEnvironment: mockEnsureSshEnvironment,
+        disconnectSshEnvironment: mockDisconnectSshEnvironment,
         fetchSshEnvironmentDescriptor: mockFetchSshEnvironmentDescriptor,
         bootstrapSshBearerSession: mockBootstrapSshBearerSession,
         fetchSshSessionState: mockFetchSshSessionState,
@@ -207,6 +219,7 @@ describe("addSavedEnvironment", () => {
       wsBaseUrl: "ws://127.0.0.1:3774/",
       pairingToken: "ssh-pairing-code",
     });
+    mockDisconnectSshEnvironment.mockResolvedValue(undefined);
   });
 
   it("rolls back persisted metadata when bearer token persistence fails", async () => {
@@ -262,6 +275,41 @@ describe("addSavedEnvironment", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("persists the server label after saved environment metadata refresh", async () => {
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+    mockClientGetConfig.mockResolvedValue({
+      environment: {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Julius's Mac mini",
+      },
+    });
+
+    const { addSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await expect(
+      addSavedEnvironment({
+        label: "100.65.180.100",
+        host: "remote.example.com",
+        pairingCode: "123456",
+      }),
+    ).resolves.toMatchObject({
+      environmentId: EnvironmentId.make("environment-1"),
+    });
+
+    expect(mockRename).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      "Julius's Mac mini",
+    );
+    expect(mockSavedRecords).toEqual([
+      expect.objectContaining({
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Julius's Mac mini",
+      }),
+    ]);
+
+    await resetEnvironmentServiceForTests();
+  });
+
   it("removes an older ssh record when the same target returns a new environment id", async () => {
     mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
     mockFetchSshEnvironmentDescriptor.mockResolvedValue({
@@ -553,4 +601,197 @@ describe("addSavedEnvironment", () => {
 
     await resetEnvironmentServiceForTests();
   });
+
+  it("disconnects the desktop ssh process before removing a saved ssh environment", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+
+    const { removeSavedEnvironment, resetEnvironmentServiceForTests } = await import("./service");
+
+    await removeSavedEnvironment(EnvironmentId.make("environment-1"));
+
+    expect(mockDisconnectSshEnvironment).toHaveBeenCalledWith({
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 22,
+    });
+    expect(mockRemove).toHaveBeenCalledWith(EnvironmentId.make("environment-1"));
+    expect(mockRemoveSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+    );
+    expect(mockDisconnectSshEnvironment.mock.invocationCallOrder[0]).toBeLessThan(
+      mockRemove.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("disconnects a saved ssh environment without removing its saved record", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+
+    const { disconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await disconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+
+    expect(mockDisconnectSshEnvironment).toHaveBeenCalledWith({
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 22,
+    });
+    expect(mockRemove).not.toHaveBeenCalled();
+    expect(mockRemoveSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("keeps remote environment credentials when disconnecting a non-ssh saved environment", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "https://remote.example.com/",
+        wsBaseUrl: "wss://remote.example.com/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+      },
+    ];
+
+    const { disconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await disconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+
+    expect(mockDisconnectSshEnvironment).not.toHaveBeenCalled();
+    expect(mockRemove).not.toHaveBeenCalled();
+    expect(mockRemoveSavedEnvironmentBearerToken).not.toHaveBeenCalled();
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("reissues ssh pairing credentials when connecting after a manual ssh disconnect", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockWriteSavedEnvironmentBearerToken.mockResolvedValue(true);
+
+    const { reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await reconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+
+    expect(mockEnsureSshEnvironment).toHaveBeenCalledWith(
+      {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+      { issuePairingToken: true },
+    );
+    expect(mockBootstrapSshBearerSession).toHaveBeenCalledWith(
+      "http://127.0.0.1:3774/",
+      "ssh-pairing-code",
+    );
+    expect(mockWriteSavedEnvironmentBearerToken).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      "ssh-bearer-token",
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
+  it("times out a saved ssh reconnect when desktop bootstrap never settles", async () => {
+    vi.useFakeTimers();
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "http://127.0.0.1:3774/",
+        wsBaseUrl: "ws://127.0.0.1:3774/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+        desktopSsh: {
+          alias: "devbox",
+          hostname: "devbox.example.com",
+          username: "julius",
+          port: 22,
+        },
+      },
+    ];
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockEnsureSshEnvironment.mockReturnValue(new Promise(() => undefined));
+
+    const { reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    const reconnectPromise = reconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+    const reconnectAssertion = expect(reconnectPromise).rejects.toThrow(
+      "Timed out starting SSH environment for devbox.",
+    );
+    await vi.advanceTimersByTimeAsync(70_000);
+    await reconnectAssertion;
+    expect(mockPatchRuntime).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      expect.objectContaining({
+        connectionState: "connecting",
+      }),
+    );
+    expect(mockPatchRuntime).toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      expect.objectContaining({
+        connectionState: "error",
+        lastError: "Timed out starting SSH environment for devbox.",
+      }),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
 });
diff --git a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
index eb5f9d7b20e..0025e710e63 100644
--- a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
+++ b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
@@ -39,6 +39,7 @@ vi.mock("./catalog", () => ({
       upsert: vi.fn(),
       remove: vi.fn(),
       markConnected: vi.fn(),
+      rename: vi.fn(),
     }),
   },
   useSavedEnvironmentRuntimeStore: {
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 1ff8b662afd..b365cfd20c5 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -114,6 +114,7 @@ const THREAD_DETAIL_SUBSCRIPTION_IDLE_EVICTION_MS = 15 * 60 * 1000;
 const MAX_CACHED_THREAD_DETAIL_SUBSCRIPTIONS = 32;
 const NOOP = () => undefined;
 const SSH_HTTP_STATUS_RE = /^\[ssh_http:(\d+)\]\s/u;
+const SAVED_ENVIRONMENT_CONNECT_TIMEOUT_MS = 70_000;
 
 function compareAppliedProjectionVersion(
   left: { readonly sequence: number; readonly updatedAt: string | null },
@@ -596,7 +597,10 @@ async function resolveDesktopSshEnvironmentBootstrap(
     throw new Error("SSH launch is only available in the desktop app.");
   }
 
-  return await desktopBridge.ensureSshEnvironment(target, options);
+  return await withDesktopSshBootstrapTimeout(
+    target,
+    desktopBridge.ensureSshEnvironment(target, options),
+  );
 }
 
 function getDesktopSshBridge() {
@@ -738,6 +742,36 @@ function setRuntimeError(environmentId: EnvironmentId, error: unknown) {
   });
 }
 
+function getDesktopSshTargetDisplayName(target: DesktopSshEnvironmentTarget): string {
+  return target.alias.trim() || target.hostname.trim() || "SSH host";
+}
+
+function createDesktopSshBootstrapTimeoutError(target: DesktopSshEnvironmentTarget): Error {
+  return new Error(
+    `Timed out starting SSH environment for ${getDesktopSshTargetDisplayName(target)}.`,
+  );
+}
+
+async function withDesktopSshBootstrapTimeout<T>(
+  target: DesktopSshEnvironmentTarget,
+  operation: Promise<T>,
+): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  const timeout = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(createDesktopSshBootstrapTimeoutError(target));
+    }, SAVED_ENVIRONMENT_CONNECT_TIMEOUT_MS);
+  });
+
+  try {
+    return await Promise.race([operation, timeout]);
+  } finally {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+  }
+}
+
 function coalesceOrchestrationUiEvents(
   events: ReadonlyArray<OrchestrationEvent>,
 ): OrchestrationEvent[] {
@@ -1003,8 +1037,13 @@ function createPrimaryEnvironmentClient(
       `Unable to resolve websocket URL for ${knownEnvironment?.label ?? "primary environment"}.`,
     );
   }
+  const connectionLabel = knownEnvironment?.label ?? null;
 
-  return createWsRpcClient(new WsTransport(wsBaseUrl));
+  return createWsRpcClient(
+    new WsTransport(wsBaseUrl, {
+      getConnectionLabel: () => connectionLabel,
+    }),
+  );
 }
 
 function createSavedEnvironmentClient(
@@ -1033,6 +1072,7 @@ function createSavedEnvironmentClient(
             });
       },
       {
+        getConnectionLabel: () => getSavedEnvironmentRecord(environmentId)?.label ?? null,
         onAttempt: () => {
           setRuntimeConnecting(environmentId);
         },
@@ -1082,6 +1122,9 @@ async function refreshSavedEnvironmentMetadata(
     serverConfig,
     role: sessionState.authenticated ? (sessionState.role ?? roleHint ?? null) : null,
   });
+  useSavedEnvironmentRegistryStore
+    .getState()
+    .rename(record.environmentId, serverConfig.environment.label);
 }
 
 function registerConnection(connection: EnvironmentConnection): EnvironmentConnection {
@@ -1326,13 +1369,18 @@ export function getPrimaryEnvironmentConnection(): EnvironmentConnection {
 }
 
 export async function disconnectSavedEnvironment(environmentId: EnvironmentId): Promise<void> {
+  const record = getSavedEnvironmentRecord(environmentId);
   const connection = environmentConnections.get(environmentId);
-  if (connection?.kind !== "saved") {
-    return;
+
+  if (connection?.kind === "saved") {
+    await removeConnection(environmentId).catch(() => false);
   }
+  setRuntimeDisconnected(environmentId);
 
-  useSavedEnvironmentRuntimeStore.getState().clear(environmentId);
-  await removeConnection(environmentId).catch(() => false);
+  if (record?.desktopSsh && typeof window !== "undefined") {
+    await window.desktopBridge?.disconnectSshEnvironment(record.desktopSsh);
+    await removeSavedEnvironmentBearerToken(environmentId);
+  }
 }
 
 export async function reconnectSavedEnvironment(environmentId: EnvironmentId): Promise<void> {
@@ -1343,8 +1391,14 @@ export async function reconnectSavedEnvironment(environmentId: EnvironmentId): P
 
   const connection = environmentConnections.get(environmentId);
   if (!connection) {
-    await ensureSavedEnvironmentConnection(record);
-    return;
+    setRuntimeConnecting(environmentId);
+    try {
+      await ensureSavedEnvironmentConnection(record);
+      return;
+    } catch (error) {
+      setRuntimeError(environmentId, error);
+      throw error;
+    }
   }
 
   setRuntimeConnecting(environmentId);
@@ -1376,9 +1430,10 @@ export async function reconnectSavedEnvironment(environmentId: EnvironmentId): P
 }
 
 export async function removeSavedEnvironment(environmentId: EnvironmentId): Promise<void> {
+  await disconnectSavedEnvironment(environmentId);
   useSavedEnvironmentRegistryStore.getState().remove(environmentId);
+  useSavedEnvironmentRuntimeStore.getState().clear(environmentId);
   await removeSavedEnvironmentBearerToken(environmentId);
-  await disconnectSavedEnvironment(environmentId);
 }
 
 export async function addSavedEnvironment(input: {
diff --git a/apps/web/src/localApi.test.ts b/apps/web/src/localApi.test.ts
index 726c5116119..4582f748980 100644
--- a/apps/web/src/localApi.test.ts
+++ b/apps/web/src/localApi.test.ts
@@ -177,6 +177,7 @@ function makeDesktopBridge(overrides: Partial<DesktopBridge> = {}): DesktopBridg
     ensureSshEnvironment: async () => {
       throw new Error("ensureSshEnvironment not implemented in test");
     },
+    disconnectSshEnvironment: async () => undefined,
     fetchSshEnvironmentDescriptor: async () => {
       throw new Error("fetchSshEnvironmentDescriptor not implemented in test");
     },
diff --git a/apps/web/src/rpc/protocol.ts b/apps/web/src/rpc/protocol.ts
index 0a4288df391..213f671528f 100644
--- a/apps/web/src/rpc/protocol.ts
+++ b/apps/web/src/rpc/protocol.ts
@@ -14,15 +14,25 @@ import {
   recordWsConnectionClosed,
   recordWsConnectionErrored,
   recordWsConnectionOpened,
+  type WsConnectionMetadata,
   WS_RECONNECT_MAX_RETRIES,
 } from "./wsConnectionState";
 
+export interface WsProtocolCloseContext {
+  readonly intentional: boolean;
+}
+
 export interface WsProtocolLifecycleHandlers {
+  readonly getConnectionLabel?: () => string | null;
+  readonly isCloseIntentional?: () => boolean;
   readonly isActive?: () => boolean;
   readonly onAttempt?: (socketUrl: string) => void;
   readonly onOpen?: () => void;
   readonly onError?: (message: string) => void;
-  readonly onClose?: (details: { readonly code: number; readonly reason: string }) => void;
+  readonly onClose?: (
+    details: { readonly code: number; readonly reason: string },
+    context: WsProtocolCloseContext,
+  ) => void;
 }
 
 export const makeWsRpcProtocolClient = RpcClient.make(WsRpcGroup);
@@ -48,27 +58,46 @@ function resolveWsRpcSocketUrl(rawUrl: string): string {
   return resolved.toString();
 }
 
-function defaultLifecycleHandlers(): Required<WsProtocolLifecycleHandlers> {
+function resolveConnectionMetadata(handlers?: WsProtocolLifecycleHandlers): WsConnectionMetadata {
+  return {
+    connectionLabel: handlers?.getConnectionLabel?.() ?? null,
+  };
+}
+
+type ComposedWsProtocolLifecycleHandlers = Required<
+  Pick<WsProtocolLifecycleHandlers, "isActive" | "onAttempt" | "onOpen" | "onError" | "onClose">
+>;
+
+function defaultLifecycleHandlers(
+  handlers?: WsProtocolLifecycleHandlers,
+): ComposedWsProtocolLifecycleHandlers {
   return {
     isActive: () => true,
-    onAttempt: recordWsConnectionAttempt,
-    onOpen: recordWsConnectionOpened,
+    onAttempt: (socketUrl) => {
+      recordWsConnectionAttempt(socketUrl, resolveConnectionMetadata(handlers));
+    },
+    onOpen: () => {
+      recordWsConnectionOpened(resolveConnectionMetadata(handlers));
+    },
     onError: (message) => {
       clearAllTrackedRpcRequests();
       recordWsConnectionErrored(message);
     },
-    onClose: (details) => {
+    onClose: (details, context) => {
       clearAllTrackedRpcRequests();
-      recordWsConnectionClosed(details);
+      if (context.intentional) {
+        return;
+      }
+      recordWsConnectionClosed(details, resolveConnectionMetadata(handlers));
     },
   };
 }
 
 function composeLifecycleHandlers(
   handlers?: WsProtocolLifecycleHandlers,
-): Required<WsProtocolLifecycleHandlers> {
-  const defaults = defaultLifecycleHandlers();
-  const isActive = handlers?.isActive ?? (() => true);
+): ComposedWsProtocolLifecycleHandlers {
+  const defaults = defaultLifecycleHandlers(handlers);
+  const isActive = handlers?.isActive ?? defaults.isActive;
 
   return {
     isActive,
@@ -93,12 +122,12 @@ function composeLifecycleHandlers(
       defaults.onError(message);
       handlers?.onError?.(message);
     },
-    onClose: (details) => {
+    onClose: (details, context) => {
       if (!isActive()) {
         return;
       }
-      defaults.onClose(details);
-      handlers?.onClose?.(details);
+      defaults.onClose(details, context);
+      handlers?.onClose?.(details, context);
     },
   };
 }
@@ -144,10 +173,15 @@ export function createWsRpcProtocolLayer(
       socket.addEventListener(
         "close",
         (event) => {
-          lifecycle.onClose({
-            code: event.code,
-            reason: event.reason,
-          });
+          lifecycle.onClose(
+            {
+              code: event.code,
+              reason: event.reason,
+            },
+            {
+              intentional: handlers?.isCloseIntentional?.() ?? false,
+            },
+          );
         },
         { once: true },
       );
diff --git a/apps/web/src/rpc/wsConnectionState.test.ts b/apps/web/src/rpc/wsConnectionState.test.ts
index fb0b9d85aef..1e65faa930e 100644
--- a/apps/web/src/rpc/wsConnectionState.test.ts
+++ b/apps/web/src/rpc/wsConnectionState.test.ts
@@ -45,7 +45,9 @@ describe("wsConnectionState", () => {
   });
 
   it("schedules the next retry after a failed websocket attempt", () => {
-    recordWsConnectionAttempt("ws://localhost:3020/ws");
+    recordWsConnectionAttempt("ws://localhost:3020/ws", {
+      connectionLabel: "Remote Mac",
+    });
     recordWsConnectionErrored("Unable to connect to the T3 server WebSocket.");
 
     const firstRetryDelayMs = getWsReconnectDelayMsForRetry(0);
@@ -54,6 +56,7 @@ describe("wsConnectionState", () => {
     }
 
     expect(getWsConnectionStatus()).toMatchObject({
+      connectionLabel: "Remote Mac",
       nextRetryAt: new Date(Date.now() + firstRetryDelayMs).toISOString(),
       reconnectAttemptCount: 1,
       reconnectPhase: "waiting",
diff --git a/apps/web/src/rpc/wsConnectionState.ts b/apps/web/src/rpc/wsConnectionState.ts
index d3050a2b4c9..1f649bdb356 100644
--- a/apps/web/src/rpc/wsConnectionState.ts
+++ b/apps/web/src/rpc/wsConnectionState.ts
@@ -16,6 +16,7 @@ export interface WsConnectionStatus {
   readonly attemptCount: number;
   readonly closeCode: number | null;
   readonly closeReason: string | null;
+  readonly connectionLabel: string | null;
   readonly connectedAt: string | null;
   readonly disconnectedAt: string | null;
   readonly hasConnected: boolean;
@@ -34,6 +35,7 @@ const INITIAL_WS_CONNECTION_STATUS = Object.freeze<WsConnectionStatus>({
   attemptCount: 0,
   closeCode: null,
   closeReason: null,
+  connectionLabel: null,
   connectedAt: null,
   disconnectedAt: null,
   hasConnected: false,
@@ -65,6 +67,15 @@ function updateWsConnectionStatus(
   return nextStatus;
 }
 
+export interface WsConnectionMetadata {
+  readonly connectionLabel?: string | null;
+}
+
+function normalizeConnectionLabel(label: string | null | undefined): string | null {
+  const normalized = label?.trim();
+  return normalized ? normalized : null;
+}
+
 export function getWsConnectionStatus(): WsConnectionStatus {
   return appAtomRegistry.get(wsConnectionStatusAtom);
 }
@@ -85,10 +96,15 @@ export function getWsConnectionUiState(status: WsConnectionStatus): WsConnection
   return "reconnecting";
 }
 
-export function recordWsConnectionAttempt(socketUrl: string): WsConnectionStatus {
+export function recordWsConnectionAttempt(
+  socketUrl: string,
+  metadata?: WsConnectionMetadata,
+): WsConnectionStatus {
+  const connectionLabel = normalizeConnectionLabel(metadata?.connectionLabel);
   return updateWsConnectionStatus((current) => ({
     ...current,
     attemptCount: current.attemptCount + 1,
+    connectionLabel: connectionLabel ?? current.connectionLabel,
     nextRetryAt: null,
     phase: "connecting",
     reconnectAttemptCount: current.phase === "connected" ? 1 : current.reconnectAttemptCount + 1,
@@ -97,11 +113,13 @@ export function recordWsConnectionAttempt(socketUrl: string): WsConnectionStatus
   }));
 }
 
-export function recordWsConnectionOpened(): WsConnectionStatus {
+export function recordWsConnectionOpened(metadata?: WsConnectionMetadata): WsConnectionStatus {
+  const connectionLabel = normalizeConnectionLabel(metadata?.connectionLabel);
   return updateWsConnectionStatus((current) => ({
     ...current,
     closeCode: null,
     closeReason: null,
+    connectionLabel: connectionLabel ?? current.connectionLabel,
     connectedAt: isoNow(),
     disconnectedAt: null,
     hasConnected: true,
@@ -121,15 +139,23 @@ export function recordWsConnectionErrored(message?: string | null): WsConnection
   );
 }
 
-export function recordWsConnectionClosed(details?: {
-  readonly code?: number;
-  readonly reason?: string;
-}): WsConnectionStatus {
+export function recordWsConnectionClosed(
+  details?: {
+    readonly code?: number;
+    readonly reason?: string;
+  },
+  metadata?: WsConnectionMetadata,
+): WsConnectionStatus {
+  const connectionLabel = normalizeConnectionLabel(metadata?.connectionLabel);
   return updateWsConnectionStatus((current) =>
-    applyDisconnectState(current, {
-      closeCode: details?.code ?? current.closeCode,
-      closeReason: details?.reason?.trim() ? details.reason : current.closeReason,
-    }),
+    applyDisconnectState(
+      current,
+      {
+        closeCode: details?.code ?? current.closeCode,
+        closeReason: details?.reason?.trim() ? details.reason : current.closeReason,
+      },
+      connectionLabel === null ? undefined : { connectionLabel },
+    ),
   );
 }
 
@@ -173,6 +199,7 @@ function applyDisconnectState(
   updates: Partial<
     Pick<WsConnectionStatus, "closeCode" | "closeReason" | "lastError" | "lastErrorAt">
   >,
+  metadata?: WsConnectionMetadata,
 ): WsConnectionStatus {
   const disconnectedAt = current.disconnectedAt ?? isoNow();
   const nextRetryDelayMs =
@@ -183,6 +210,7 @@ function applyDisconnectState(
   return {
     ...current,
     ...updates,
+    connectionLabel: normalizeConnectionLabel(metadata?.connectionLabel) ?? current.connectionLabel,
     disconnectedAt,
     nextRetryAt:
       nextRetryDelayMs === null
diff --git a/apps/web/src/rpc/wsTransport.test.ts b/apps/web/src/rpc/wsTransport.test.ts
index c9632d3f78d..522e15cd928 100644
--- a/apps/web/src/rpc/wsTransport.test.ts
+++ b/apps/web/src/rpc/wsTransport.test.ts
@@ -284,10 +284,15 @@ describe("WsTransport", () => {
     socket.close(1012, "service restart");
 
     await waitFor(() => {
-      expect(onClose).toHaveBeenCalledWith({
-        code: 1012,
-        reason: "service restart",
-      });
+      expect(onClose).toHaveBeenCalledWith(
+        {
+          code: 1012,
+          reason: "service restart",
+        },
+        {
+          intentional: false,
+        },
+      );
       expect(getWsConnectionStatus()).toMatchObject({
         attemptCount: 2,
         closeReason: "service restart",
@@ -298,6 +303,46 @@ describe("WsTransport", () => {
     await transport.dispose();
   });
 
+  it("does not report an intentional dispose as a reconnectable disconnect", async () => {
+    const onClose = vi.fn();
+    const transport = createTransport("ws://localhost:3020", {
+      getConnectionLabel: () => "Remote Mac mini",
+      onClose,
+    });
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(1);
+    });
+
+    const socket = getSocket();
+    socket.open();
+
+    await waitFor(() => {
+      expect(getWsConnectionStatus()).toMatchObject({
+        connectionLabel: "Remote Mac mini",
+        hasConnected: true,
+        phase: "connected",
+      });
+    });
+
+    await transport.dispose();
+
+    expect(onClose).toHaveBeenCalledWith(
+      {
+        code: 1000,
+        reason: "",
+      },
+      {
+        intentional: true,
+      },
+    );
+    expect(getWsConnectionStatus()).toMatchObject({
+      connectionLabel: "Remote Mac mini",
+      phase: "connected",
+      reconnectPhase: "idle",
+    });
+  });
+
   it("reconnects the websocket session without disposing the transport", async () => {
     const transport = createTransport("ws://localhost:3020");
 
diff --git a/apps/web/src/rpc/wsTransport.ts b/apps/web/src/rpc/wsTransport.ts
index 0b90b22431f..746a65cd071 100644
--- a/apps/web/src/rpc/wsTransport.ts
+++ b/apps/web/src/rpc/wsTransport.ts
@@ -52,6 +52,7 @@ export class WsTransport {
   private readonly lifecycleHandlers: WsProtocolLifecycleHandlers | undefined;
   private disposed = false;
   private hasReportedTransportDisconnect = false;
+  private intentionalCloseDepth = 0;
   private reconnectChain: Promise<void> = Promise.resolve();
   private nextSessionId = 0;
   private activeSessionId = 0;
@@ -211,7 +212,9 @@ export class WsTransport {
   }
 
   private closeSession(session: TransportSession) {
+    this.intentionalCloseDepth += 1;
     return session.runtime.runPromise(Scope.close(session.clientScope, Exit.void)).finally(() => {
+      this.intentionalCloseDepth -= 1;
       session.runtime.dispose();
     });
   }
@@ -224,7 +227,11 @@ export class WsTransport {
       Layer.mergeAll(
         createWsRpcProtocolLayer(this.url, {
           ...this.lifecycleHandlers,
-          isActive: () => !this.disposed && this.activeSessionId === sessionId,
+          isActive: () => this.activeSessionId === sessionId || this.disposed,
+          isCloseIntentional: () =>
+            this.disposed ||
+            this.intentionalCloseDepth > 0 ||
+            this.lifecycleHandlers?.isCloseIntentional?.() === true,
         }),
         ClientTracingLive,
       ),
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 4b934f20344..538f36227c4 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -160,6 +160,7 @@ export interface DesktopSshPasswordPromptRequest {
   destination: string;
   username: string | null;
   prompt: string;
+  expiresAt: string;
 }
 
 export interface PersistedSavedEnvironmentRecord {
@@ -203,6 +204,7 @@ export interface DesktopBridge {
     target: DesktopSshEnvironmentTarget,
     options?: { issuePairingToken?: boolean },
   ) => Promise<DesktopSshEnvironmentBootstrap>;
+  disconnectSshEnvironment: (target: DesktopSshEnvironmentTarget) => Promise<void>;
   fetchSshEnvironmentDescriptor: (httpBaseUrl: string) => Promise<ExecutionEnvironmentDescriptor>;
   bootstrapSshBearerSession: (
     httpBaseUrl: string,
diff --git a/packages/ssh/src/command.test.ts b/packages/ssh/src/command.test.ts
index 1532cc7d3b0..22e93b69c43 100644
--- a/packages/ssh/src/command.test.ts
+++ b/packages/ssh/src/command.test.ts
@@ -1,13 +1,42 @@
 import { assert, describe, it } from "@effect/vitest";
-import { Effect } from "effect";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { Duration, Effect, Fiber, Layer, Result, Sink, Stream } from "effect";
+import { TestClock } from "effect/testing";
+import { ChildProcessSpawner } from "effect/unstable/process";
 
 import {
   baseSshArgs,
   getLastNonEmptyOutputLine,
   parseSshResolveOutput,
   resolveRemoteT3CliPackageSpec,
+  runSshCommand,
 } from "./command.ts";
 
+const makeNeverFinishingProcess = () => {
+  let finish: ((exitCode: ChildProcessSpawner.ExitCode) => void) | null = null;
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(123),
+    stdout: Stream.empty,
+    stderr: Stream.empty,
+    all: Stream.empty,
+    exitCode: Effect.callback<ChildProcessSpawner.ExitCode>((resume) => {
+      finish = (exitCode) => resume(Effect.succeed(exitCode));
+      return Effect.sync(() => {
+        finish = null;
+      });
+    }),
+    isRunning: Effect.succeed(true),
+    kill: () =>
+      Effect.sync(() => {
+        finish?.(ChildProcessSpawner.ExitCode(143));
+      }),
+    stdin: Sink.drain,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    unref: Effect.succeed(Effect.void),
+  });
+};
+
 describe("ssh command", () => {
   it.effect("parses resolved ssh config output into a target", () =>
     Effect.sync(() => {
@@ -88,4 +117,35 @@ describe("ssh command", () => {
       );
     }),
   );
+
+  it.effect("fails commands that never finish", () => {
+    const spawner = ChildProcessSpawner.make(() => Effect.succeed(makeNeverFinishingProcess()));
+    const spawnerLayer = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner);
+    const processLayer = Layer.mergeAll(NodeServices.layer, spawnerLayer, TestClock.layer());
+
+    return Effect.gen(function* () {
+      const fiber = yield* Effect.forkChild(
+        Effect.result(
+          runSshCommand(
+            {
+              alias: "devbox",
+              hostname: "devbox.example.com",
+              username: "julius",
+              port: 2222,
+            },
+            { timeoutMs: 1 },
+          ),
+        ),
+      );
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust(Duration.millis(1));
+
+      const result = yield* Fiber.join(fiber);
+
+      assert.isTrue(Result.isFailure(result));
+      if (Result.isFailure(result)) {
+        assert.include(result.failure.message, "SSH command timed out after 1ms.");
+      }
+    }).pipe(Effect.provide(processLayer));
+  });
 });
diff --git a/packages/ssh/src/command.ts b/packages/ssh/src/command.ts
index 6b8299d0e9a..b43484119b7 100644
--- a/packages/ssh/src/command.ts
+++ b/packages/ssh/src/command.ts
@@ -1,13 +1,14 @@
 import * as Crypto from "node:crypto";
 
 import type { DesktopSshEnvironmentTarget, DesktopUpdateChannel } from "@t3tools/contracts";
-import { Effect, FileSystem, Path, Scope, Stream } from "effect";
+import { Duration, Effect, FileSystem, Option, Path, Scope, Stream } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
 import { buildSshChildEnvironment, type SshAuthOptions } from "./auth.ts";
 import { SshCommandError, SshInvalidTargetError } from "./errors.ts";
 
 const PUBLISHABLE_T3_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u;
+const DEFAULT_SSH_COMMAND_TIMEOUT_MS = 60_000;
 
 const encoder = new TextEncoder();
 
@@ -20,6 +21,7 @@ export interface RunSshCommandOptions extends SshAuthOptions {
   readonly preHostArgs?: ReadonlyArray<string>;
   readonly remoteCommandArgs?: ReadonlyArray<string>;
   readonly stdin?: string;
+  readonly timeoutMs?: number;
 }
 
 export function parseSshResolveOutput(alias: string, stdout: string): DesktopSshEnvironmentTarget {
@@ -227,6 +229,22 @@ export const runSshCommand = Effect.fn("ssh/command.runSshCommand")(function* (
 > {
   return yield* Effect.scopedWith((commandScope) =>
     runSshCommandInScope(target, input, commandScope),
+  ).pipe(
+    Effect.timeoutOption(Duration.millis(input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS)),
+    Effect.flatMap((result) =>
+      Option.match(result, {
+        onSome: Effect.succeed,
+        onNone: () =>
+          Effect.fail(
+            new SshCommandError({
+              command: ["ssh"],
+              exitCode: null,
+              stderr: "",
+              message: `SSH command timed out after ${input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS}ms.`,
+            }),
+          ),
+      }),
+    ),
   );
 });
 
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index ba3f6e6d83e..28f501679b8 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -1,14 +1,19 @@
 import { assert, describe, it } from "@effect/vitest";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import { NetService } from "@t3tools/shared/Net";
 import { Effect, Layer, Sink, Stream } from "effect";
-import { ChildProcessSpawner } from "effect/unstable/process";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
+import { SshPasswordPrompt } from "./auth.ts";
 import {
   buildRemoteLaunchScript,
   buildRemotePairingScript,
+  buildRemoteStopScript,
   buildRemoteT3RunnerScript,
   issueRemotePairingToken,
   REMOTE_PICK_PORT_SCRIPT,
+  SshEnvironmentManager,
 } from "./tunnel.ts";
 
 const makeSuccessfulProcess = (stdout: string) => {
@@ -28,16 +33,70 @@ const makeSuccessfulProcess = (stdout: string) => {
   });
 };
 
+const makeRunningProcess = (onKill: () => void) => {
+  let finish: ((exitCode: ChildProcessSpawner.ExitCode) => void) | null = null;
+  return ChildProcessSpawner.makeHandle({
+    pid: ChildProcessSpawner.ProcessId(123),
+    stdout: Stream.empty,
+    stderr: Stream.empty,
+    all: Stream.empty,
+    exitCode: Effect.callback<ChildProcessSpawner.ExitCode>((resume) => {
+      finish = (exitCode) => resume(Effect.succeed(exitCode));
+      return Effect.sync(() => {
+        finish = null;
+      });
+    }),
+    isRunning: Effect.succeed(true),
+    kill: () =>
+      Effect.sync(() => {
+        onKill();
+        finish?.(ChildProcessSpawner.ExitCode(143));
+      }),
+    stdin: Sink.drain,
+    getInputFd: () => Sink.drain,
+    getOutputFd: () => Stream.empty,
+    unref: Effect.succeed(Effect.void),
+  });
+};
+
+const testHttpClient = HttpClient.make((request) =>
+  Effect.succeed(HttpClientResponse.fromWeb(request, new Response("", { status: 200 }))),
+);
+
+const testNetService = NetService.of({
+  canListenOnHost: () => Effect.succeed(true),
+  isPortAvailableOnLoopback: () => Effect.succeed(true),
+  reserveLoopbackPort: () => Effect.succeed(41_773),
+  findAvailablePort: (preferred) => Effect.succeed(preferred),
+});
+
+function commandArgs(command: ChildProcess.Command): ReadonlyArray<string> {
+  return command._tag === "StandardCommand" ? command.args : [];
+}
+
 describe("ssh tunnel scripts", () => {
   it("builds the remote t3 runner with npx and npm fallbacks", () => {
     const script = buildRemoteT3RunnerScript();
 
+    assert.include(script, "T3_NODE_SCRIPT_PATH=''");
     assert.include(script, 'exec t3 "$@"');
     assert.include(script, 'exec npx --yes t3@latest "$@"');
     assert.include(script, 'exec npm exec --yes t3@latest -- "$@"');
     assert.include(script, "could not install t3@latest");
   });
 
+  it("builds the remote t3 runner with a node script override", () => {
+    const script = buildRemoteT3RunnerScript({
+      nodeScriptPath: "/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs",
+    });
+
+    assert.include(
+      script,
+      "T3_NODE_SCRIPT_PATH='/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs'",
+    );
+    assert.include(script, 'exec node "$T3_NODE_SCRIPT_PATH" "$@"');
+  });
+
   it("uses the remote t3 runner for launch and pairing scripts", () => {
     const target = {
       alias: "devbox",
@@ -50,6 +109,8 @@ describe("ssh tunnel scripts", () => {
       buildRemoteLaunchScript(),
       '[ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null',
     );
+    assert.include(buildRemoteLaunchScript(), "RUNNER_CHANGED=1");
+    assert.include(buildRemoteLaunchScript(), 'kill "$REMOTE_PID" 2>/dev/null || true');
     assert.include(buildRemoteLaunchScript(), '"$RUNNER_FILE" serve --host 127.0.0.1');
     assert.include(buildRemoteLaunchScript({ packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
@@ -57,6 +118,8 @@ describe("ssh tunnel scripts", () => {
       '"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json',
     );
     assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
+    assert.include(buildRemoteStopScript(target), 'kill "$REMOTE_PID" 2>/dev/null || true');
+    assert.include(buildRemoteStopScript(target), 'rm -f "$PID_FILE" "$PORT_FILE"');
   });
 
   it("allows the remote port picker to run without a state file path", () => {
@@ -89,4 +152,59 @@ describe("ssh tunnel scripts", () => {
       assert.equal(credential, "LCL4R2TPHDKQ");
     }).pipe(Effect.provide(processLayer));
   });
+
+  it.effect("closes the tunnel scope and starts fresh after disconnect", () => {
+    const spawnedCommands: Array<ReadonlyArray<string>> = [];
+    let tunnelKillCount = 0;
+    let stopCommandCount = 0;
+    const spawner = ChildProcessSpawner.make((command) =>
+      Effect.sync(() => {
+        const args = commandArgs(command);
+        spawnedCommands.push(args);
+        if (args.includes("-N")) {
+          return makeRunningProcess(() => {
+            tunnelKillCount += 1;
+          });
+        }
+        if (args.includes("sh") && args.includes("--")) {
+          return makeSuccessfulProcess('{"remotePort":3773}\n');
+        }
+        if (args.includes("sh")) {
+          stopCommandCount += 1;
+          return makeSuccessfulProcess('{"stopped":true}\n');
+        }
+        return makeSuccessfulProcess("\n");
+      }),
+    );
+    const layer = Layer.mergeAll(
+      NodeServices.layer,
+      Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner),
+      Layer.succeed(HttpClient.HttpClient, testHttpClient),
+      Layer.succeed(NetService, testNetService),
+      SshPasswordPrompt.disabledLayer,
+      SshEnvironmentManager.layer(),
+    );
+    const target = {
+      alias: "devbox",
+      hostname: "devbox.example.com",
+      username: "julius",
+      port: 2222,
+    } as const;
+
+    return Effect.gen(function* () {
+      const manager = yield* SshEnvironmentManager;
+
+      const first = yield* manager.ensureEnvironment(target);
+      assert.equal(first.httpBaseUrl, "http://127.0.0.1:41773/");
+
+      yield* manager.disconnectEnvironment(target);
+      assert.equal(tunnelKillCount, 1);
+      assert.equal(stopCommandCount, 1);
+
+      yield* manager.ensureEnvironment(target);
+
+      assert.equal(spawnedCommands.filter((args) => args.includes("-N")).length, 2);
+      assert.equal(tunnelKillCount, 1);
+    }).pipe(Effect.provide(layer), Effect.scoped);
+  });
 });
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index afd08c5b631..5a5f2842f47 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -51,8 +51,14 @@ const REMOTE_PORT_SCAN_WINDOW = 200;
 const SSH_READY_TIMEOUT_MS = 20_000;
 const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
 
+export interface RemoteT3RunnerOptions {
+  readonly packageSpec?: string;
+  readonly nodeScriptPath?: string | null;
+}
+
 export interface SshEnvironmentManagerOptions {
   readonly resolveCliPackageSpec?: () => string;
+  readonly resolveCliRunner?: () => RemoteT3RunnerOptions;
 }
 
 interface SshTunnelEntry {
@@ -63,6 +69,7 @@ interface SshTunnelEntry {
   readonly httpBaseUrl: string;
   readonly wsBaseUrl: string;
   readonly process: ChildProcessSpawner.ChildProcessHandle;
+  readonly scope: Scope.Scope;
 }
 
 type SshEnvironmentEffectContext =
@@ -82,6 +89,15 @@ type SshEnvironmentEffectError =
   | SshPasswordPromptError
   | NetError;
 
+function makeSshTunnelCancelledError(target: DesktopSshEnvironmentTarget): SshCommandError {
+  return new SshCommandError({
+    command: ["ssh"],
+    exitCode: null,
+    stderr: "",
+    message: `SSH environment connection was cancelled for ${target.alias || target.hostname}.`,
+  });
+}
+
 interface SshAuthOperationInput<T> {
   readonly key: string;
   readonly target: DesktopSshEnvironmentTarget;
@@ -104,6 +120,9 @@ export interface SshEnvironmentManagerShape {
     SshEnvironmentEffectError,
     SshEnvironmentEffectContext
   >;
+  readonly disconnectEnvironment: (
+    target: DesktopSshEnvironmentTarget,
+  ) => Effect.Effect<void, SshEnvironmentEffectError, SshEnvironmentEffectContext>;
 }
 
 const RemoteLaunchResult = Schema.Struct({
@@ -131,6 +150,10 @@ function stripTrailingNewlines(value: string): string {
   return value.replace(/\n+$/u, "");
 }
 
+function shellSingleQuote(value: string): string {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
 function applyScriptPlaceholders(
   template: string,
   replacements: Readonly<Record<string, string>>,
@@ -177,6 +200,10 @@ function tryPort(port) {
 
 export const REMOTE_RUNNER_SCRIPT = `#!/bin/sh
 set -eu
+T3_NODE_SCRIPT_PATH=@@T3_NODE_SCRIPT_PATH@@
+if [ -n "$T3_NODE_SCRIPT_PATH" ]; then
+  exec node "$T3_NODE_SCRIPT_PATH" "$@"
+fi
 if command -v t3 >/dev/null 2>&1; then
   exec t3 "$@"
 fi
@@ -198,10 +225,20 @@ PORT_FILE="$STATE_DIR/port"
 PID_FILE="$STATE_DIR/pid"
 LOG_FILE="$STATE_DIR/server.log"
 RUNNER_FILE="$STATE_DIR/run-t3.sh"
+RUNNER_NEXT="$STATE_DIR/run-t3.next.$$"
 mkdir -p "$STATE_DIR" "$SERVER_HOME"
-cat >"$RUNNER_FILE" <<'SH'
+cleanup_runner_next() {
+  rm -f "$RUNNER_NEXT"
+}
+trap cleanup_runner_next EXIT
+cat >"$RUNNER_NEXT" <<'SH'
 @@T3_RUNNER_SCRIPT@@
 SH
+RUNNER_CHANGED=0
+if [ ! -f "$RUNNER_FILE" ] || ! cmp -s "$RUNNER_NEXT" "$RUNNER_FILE"; then
+  RUNNER_CHANGED=1
+fi
+mv "$RUNNER_NEXT" "$RUNNER_FILE"
 chmod 700 "$RUNNER_FILE"
 pick_port() {
   node - "$PORT_FILE" "@@T3_DEFAULT_REMOTE_PORT@@" "@@T3_REMOTE_PORT_SCAN_WINDOW@@" <<'NODE'
@@ -211,8 +248,16 @@ NODE
 REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
 REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
 if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
-  :
+  if [ "$RUNNER_CHANGED" -eq 1 ]; then
+    kill "$REMOTE_PID" 2>/dev/null || true
+    REMOTE_PID=""
+    REMOTE_PORT=""
+  fi
 else
+  REMOTE_PID=""
+  REMOTE_PORT=""
+fi
+if [ -z "$REMOTE_PID" ] || [ -z "$REMOTE_PORT" ]; then
   REMOTE_PORT="$(pick_port)" || true
   if [ -z "$REMOTE_PORT" ]; then
     printf 'Failed to find an available port on the remote host. Ensure node is available on PATH.\\n' >&2
@@ -238,16 +283,30 @@ chmod 700 "$RUNNER_FILE"
 "$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json
 `;
 
-export function buildRemoteT3RunnerScript(input?: { readonly packageSpec?: string }): string {
+export const REMOTE_STOP_SCRIPT = `set -eu
+STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
+PID_FILE="$STATE_DIR/pid"
+PORT_FILE="$STATE_DIR/port"
+REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+if [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+  kill "$REMOTE_PID" 2>/dev/null || true
+fi
+rm -f "$PID_FILE" "$PORT_FILE"
+printf '{"stopped":true}\\n'
+`;
+
+export function buildRemoteT3RunnerScript(input?: RemoteT3RunnerOptions): string {
   const packageSpec = input?.packageSpec?.trim() || "t3@latest";
+  const nodeScriptPath = input?.nodeScriptPath?.trim() || "";
   return stripTrailingNewlines(
     applyScriptPlaceholders(REMOTE_RUNNER_SCRIPT, {
       T3_PACKAGE_SPEC: packageSpec,
+      T3_NODE_SCRIPT_PATH: shellSingleQuote(nodeScriptPath),
     }),
   );
 }
 
-export function buildRemoteLaunchScript(input?: { readonly packageSpec?: string }): string {
+export function buildRemoteLaunchScript(input?: RemoteT3RunnerOptions): string {
   return applyScriptPlaceholders(REMOTE_LAUNCH_SCRIPT, {
     T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
     T3_PICK_PORT_SCRIPT: stripTrailingNewlines(REMOTE_PICK_PORT_SCRIPT),
@@ -258,7 +317,7 @@ export function buildRemoteLaunchScript(input?: { readonly packageSpec?: string
 
 export function buildRemotePairingScript(
   target: DesktopSshEnvironmentTarget,
-  input?: { readonly packageSpec?: string },
+  input?: RemoteT3RunnerOptions,
 ): string {
   return applyScriptPlaceholders(REMOTE_PAIRING_SCRIPT, {
     T3_STATE_KEY: remoteStateKey(target),
@@ -266,11 +325,17 @@ export function buildRemotePairingScript(
   });
 }
 
+export function buildRemoteStopScript(target: DesktopSshEnvironmentTarget): string {
+  return applyScriptPlaceholders(REMOTE_STOP_SCRIPT, {
+    T3_STATE_KEY: remoteStateKey(target),
+  });
+}
+
 export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemoteServer")(
   function* (
     target: DesktopSshEnvironmentTarget,
     input?: SshAuthOptions,
-    runner?: { readonly packageSpec?: string },
+    runner?: RemoteT3RunnerOptions,
   ): Effect.fn.Return<
     number,
     SshCommandError | SshInvalidTargetError | SshLaunchError,
@@ -312,7 +377,7 @@ export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemo
 export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingToken")(function* (
   target: DesktopSshEnvironmentTarget,
   input?: SshAuthOptions,
-  runner?: { readonly packageSpec?: string },
+  runner?: RemoteT3RunnerOptions,
 ): Effect.fn.Return<
   string,
   SshCommandError | SshInvalidTargetError | SshPairingError,
@@ -350,6 +415,23 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
   return parsed.credential;
 });
 
+export const stopRemoteServer = Effect.fn("ssh/tunnel.stopRemoteServer")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input?: SshAuthOptions,
+): Effect.fn.Return<
+  void,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  yield* runSshCommand(target, {
+    remoteCommandArgs: ["sh", "-s"],
+    stdin: buildRemoteStopScript(target),
+    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+  });
+});
+
 export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(function* (input: {
   readonly baseUrl: string;
   readonly timeoutMs?: number;
@@ -533,6 +615,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     hostSpec,
   ];
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const scope = yield* Scope.Scope;
   const child = yield* spawner
     .spawn(
       ChildProcess.make("ssh", args, {
@@ -563,6 +646,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     httpBaseUrl: input.httpBaseUrl,
     wsBaseUrl: input.wsBaseUrl,
     process: child,
+    scope,
   };
   const exitFailure = Effect.all(
     [collectProcessOutput(child.stderr), child.exitCode.pipe(Effect.map(Number))],
@@ -619,7 +703,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
 const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.make")(function* (
   options: SshEnvironmentManagerOptions = {},
 ): Effect.fn.Return<SshEnvironmentManagerShape, never, Scope.Scope> {
-  const tunnelScope = yield* Scope.Scope;
+  const managerScope = yield* Scope.Scope;
   const tunnels = new Map<string, SshTunnelEntry>();
   const pendingTunnelEntries = new Map<
     string,
@@ -627,11 +711,21 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
   >();
   const authSecrets = new Map<string, string>();
 
-  const deleteTunnelIfCurrent = (entry: SshTunnelEntry): void => {
-    if (tunnels.get(entry.key) === entry) {
-      tunnels.delete(entry.key);
-    }
-  };
+  const closeTunnelEntry = Effect.fn("ssh/tunnel.closeTunnelEntry")(function* (
+    entry: SshTunnelEntry,
+  ) {
+    yield* Scope.close(entry.scope, Exit.void).pipe(Effect.ignore);
+  });
+
+  yield* Scope.addFinalizer(
+    managerScope,
+    Effect.sync(() => [...tunnels.values()]).pipe(
+      Effect.flatMap((entries) =>
+        Effect.forEach(entries, closeTunnelEntry, { concurrency: "unbounded" }),
+      ),
+      Effect.ignore,
+    ),
+  );
 
   const promptForPassword = Effect.fn("ssh/tunnel.promptForPassword")(function* (
     target: DesktopSshEnvironmentTarget,
@@ -725,21 +819,18 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
   const createTunnelEntry = Effect.fn("ssh/tunnel.ensureTunnelEntry.create")(function* (input: {
     readonly key: string;
     readonly resolvedTarget: DesktopSshEnvironmentTarget;
-    readonly packageSpec?: string;
+    readonly runner?: RemoteT3RunnerOptions;
   }): Effect.fn.Return<SshTunnelEntry, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
     const remotePort = yield* runWithSshAuth({
       key: input.key,
       target: input.resolvedTarget,
       operation: (authOptions) =>
-        launchOrReuseRemoteServer(
-          input.resolvedTarget,
-          authOptions,
-          input.packageSpec === undefined ? undefined : { packageSpec: input.packageSpec },
-        ),
+        launchOrReuseRemoteServer(input.resolvedTarget, authOptions, input.runner),
     });
     const localPort = yield* reserveLocalTunnelPort();
     const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
     const wsBaseUrl = `ws://127.0.0.1:${localPort}/`;
+    const entryScope = yield* Scope.make("sequential");
     const tunnelEntry = yield* runWithSshAuth({
       key: input.key,
       target: input.resolvedTarget,
@@ -752,16 +843,59 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
           httpBaseUrl,
           wsBaseUrl,
           authOptions,
-        }).pipe(Effect.provideService(Scope.Scope, tunnelScope)),
-    });
+        }).pipe(Effect.provideService(Scope.Scope, entryScope)),
+    }).pipe(
+      Effect.onExit((exit) =>
+        Exit.isSuccess(exit) ? Effect.void : Scope.close(entryScope, Exit.void).pipe(Effect.ignore),
+      ),
+    );
     tunnels.set(input.key, tunnelEntry);
+    const spawnerService = yield* ChildProcessSpawner.ChildProcessSpawner;
+    const fileSystemService = yield* FileSystem.FileSystem;
+    const pathService = yield* Path.Path;
+    yield* Scope.addFinalizer(
+      entryScope,
+      Effect.gen(function* () {
+        if (tunnels.get(tunnelEntry.key) !== tunnelEntry) {
+          return;
+        }
+        tunnels.delete(tunnelEntry.key);
+        const authSecret = authSecrets.get(tunnelEntry.key) ?? null;
+        yield* Effect.all(
+          [
+            tunnelEntry.process.kill({
+              killSignal: "SIGTERM",
+              forceKillAfter: TUNNEL_SHUTDOWN_TIMEOUT_MS,
+            }),
+            stopRemoteServer(
+              tunnelEntry.target,
+              authSecret === null
+                ? {
+                    batchMode: "yes",
+                    interactiveAuth: false,
+                  }
+                : {
+                    authSecret,
+                    batchMode: "no",
+                    interactiveAuth: true,
+                  },
+            ).pipe(
+              Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawnerService),
+              Effect.provideService(FileSystem.FileSystem, fileSystemService),
+              Effect.provideService(Path.Path, pathService),
+            ),
+          ],
+          { concurrency: "unbounded" },
+        ).pipe(Effect.ignore);
+      }).pipe(Effect.ignore),
+    );
     return tunnelEntry;
   });
 
   const ensureTunnelEntry = Effect.fn("ssh/tunnel.ensureTunnelEntry")(function* (
     key: string,
     resolvedTarget: DesktopSshEnvironmentTarget,
-    packageSpec?: string,
+    runner?: RemoteT3RunnerOptions,
   ): Effect.fn.Return<SshTunnelEntry, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
     let entry = tunnels.get(key) ?? null;
 
@@ -772,13 +906,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       if (Exit.isSuccess(readinessExit)) {
         return entry;
       }
-      yield* entry.process
-        .kill({
-          killSignal: "SIGTERM",
-          forceKillAfter: TUNNEL_SHUTDOWN_TIMEOUT_MS,
-        })
-        .pipe(Effect.ignore);
-      deleteTunnelIfCurrent(entry);
+      yield* closeTunnelEntry(entry);
       entry = null;
     }
 
@@ -793,7 +921,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     return yield* createTunnelEntry({
       key,
       resolvedTarget,
-      ...(packageSpec === undefined ? {} : { packageSpec }),
+      ...(runner === undefined ? {} : { runner }),
     }).pipe(
       Effect.onExit((exit) =>
         Effect.sync(() => {
@@ -821,18 +949,15 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     };
     const key = targetConnectionKey(resolvedTarget);
     const packageSpec = options.resolveCliPackageSpec?.();
-    const entry = yield* ensureTunnelEntry(key, resolvedTarget, packageSpec);
+    const runner =
+      options.resolveCliRunner?.() ?? (packageSpec === undefined ? undefined : { packageSpec });
+    const entry = yield* ensureTunnelEntry(key, resolvedTarget, runner);
 
     const pairingToken = requestOptions?.issuePairingToken
       ? yield* runWithSshAuth({
           key,
           target: entry.target,
-          operation: (authOptions) =>
-            issueRemotePairingToken(
-              entry.target,
-              authOptions,
-              packageSpec === undefined ? undefined : { packageSpec },
-            ),
+          operation: (authOptions) => issueRemotePairingToken(entry.target, authOptions, runner),
         })
       : null;
 
@@ -844,7 +969,37 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     };
   });
 
-  return SshEnvironmentManager.of({ ensureEnvironment });
+  const disconnectEnvironment = Effect.fn("ssh/tunnel.disconnectEnvironment")(function* (
+    target: DesktopSshEnvironmentTarget,
+  ): Effect.fn.Return<void, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    const baseResolved = yield* resolveSshTarget(target.alias || target.hostname);
+    const resolvedTarget: DesktopSshEnvironmentTarget = {
+      ...baseResolved,
+      ...(target.username !== null ? { username: target.username } : {}),
+      ...(target.port !== null ? { port: target.port } : {}),
+    };
+    const key = targetConnectionKey(resolvedTarget);
+    const entry = tunnels.get(key) ?? null;
+    if (entry !== null) {
+      yield* closeTunnelEntry(entry);
+    }
+    const pending = pendingTunnelEntries.get(key);
+    if (pending) {
+      pendingTunnelEntries.delete(key);
+      yield* Deferred.fail(pending, makeSshTunnelCancelledError(resolvedTarget)).pipe(
+        Effect.ignore,
+      );
+    }
+    if (entry === null) {
+      yield* runWithSshAuth({
+        key,
+        target: resolvedTarget,
+        operation: (authOptions) => stopRemoteServer(resolvedTarget, authOptions),
+      });
+    }
+  });
+
+  return SshEnvironmentManager.of({ ensureEnvironment, disconnectEnvironment });
 });
 
 export class SshEnvironmentManager extends Context.Service<

From 860d6335921d4e44a32a182b39546cebc8398f34 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 14:58:23 -0700
Subject: [PATCH 40/74] Log SSH tunnel lifecycle and surface bootstrap failures

- Add structured logging around SSH command, tunnel, and pairing flows
- Let desktop SSH bootstrap failures propagate instead of timing out locally
- Update reconnect test to expect the underlying SSH timeout error
---
 .../service.addSavedEnvironment.test.ts       |  14 +-
 apps/web/src/environments/runtime/service.ts  |  36 +--
 packages/ssh/src/command.ts                   |  60 ++++-
 packages/ssh/src/tunnel.ts                    | 242 +++++++++++++++++-
 4 files changed, 288 insertions(+), 64 deletions(-)

diff --git a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
index ca75f2a522d..ca021cc5d41 100644
--- a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
+++ b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
@@ -748,8 +748,7 @@ describe("addSavedEnvironment", () => {
     await resetEnvironmentServiceForTests();
   });
 
-  it("times out a saved ssh reconnect when desktop bootstrap never settles", async () => {
-    vi.useFakeTimers();
+  it("surfaces desktop ssh bootstrap failures during saved ssh reconnect", async () => {
     mockSavedRecords = [
       {
         environmentId: EnvironmentId.make("environment-1"),
@@ -767,17 +766,14 @@ describe("addSavedEnvironment", () => {
       },
     ];
     mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
-    mockEnsureSshEnvironment.mockReturnValue(new Promise(() => undefined));
+    mockEnsureSshEnvironment.mockRejectedValue(new Error("SSH command timed out after 60000ms."));
 
     const { reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
       await import("./service");
 
-    const reconnectPromise = reconnectSavedEnvironment(EnvironmentId.make("environment-1"));
-    const reconnectAssertion = expect(reconnectPromise).rejects.toThrow(
-      "Timed out starting SSH environment for devbox.",
+    await expect(reconnectSavedEnvironment(EnvironmentId.make("environment-1"))).rejects.toThrow(
+      "SSH command timed out after 60000ms.",
     );
-    await vi.advanceTimersByTimeAsync(70_000);
-    await reconnectAssertion;
     expect(mockPatchRuntime).toHaveBeenCalledWith(
       EnvironmentId.make("environment-1"),
       expect.objectContaining({
@@ -788,7 +784,7 @@ describe("addSavedEnvironment", () => {
       EnvironmentId.make("environment-1"),
       expect.objectContaining({
         connectionState: "error",
-        lastError: "Timed out starting SSH environment for devbox.",
+        lastError: "SSH command timed out after 60000ms.",
       }),
     );
 
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index b365cfd20c5..4a873f33341 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -114,7 +114,6 @@ const THREAD_DETAIL_SUBSCRIPTION_IDLE_EVICTION_MS = 15 * 60 * 1000;
 const MAX_CACHED_THREAD_DETAIL_SUBSCRIPTIONS = 32;
 const NOOP = () => undefined;
 const SSH_HTTP_STATUS_RE = /^\[ssh_http:(\d+)\]\s/u;
-const SAVED_ENVIRONMENT_CONNECT_TIMEOUT_MS = 70_000;
 
 function compareAppliedProjectionVersion(
   left: { readonly sequence: number; readonly updatedAt: string | null },
@@ -597,10 +596,7 @@ async function resolveDesktopSshEnvironmentBootstrap(
     throw new Error("SSH launch is only available in the desktop app.");
   }
 
-  return await withDesktopSshBootstrapTimeout(
-    target,
-    desktopBridge.ensureSshEnvironment(target, options),
-  );
+  return await desktopBridge.ensureSshEnvironment(target, options);
 }
 
 function getDesktopSshBridge() {
@@ -742,36 +738,6 @@ function setRuntimeError(environmentId: EnvironmentId, error: unknown) {
   });
 }
 
-function getDesktopSshTargetDisplayName(target: DesktopSshEnvironmentTarget): string {
-  return target.alias.trim() || target.hostname.trim() || "SSH host";
-}
-
-function createDesktopSshBootstrapTimeoutError(target: DesktopSshEnvironmentTarget): Error {
-  return new Error(
-    `Timed out starting SSH environment for ${getDesktopSshTargetDisplayName(target)}.`,
-  );
-}
-
-async function withDesktopSshBootstrapTimeout<T>(
-  target: DesktopSshEnvironmentTarget,
-  operation: Promise<T>,
-): Promise<T> {
-  let timeoutId: ReturnType<typeof setTimeout> | null = null;
-  const timeout = new Promise<never>((_, reject) => {
-    timeoutId = setTimeout(() => {
-      reject(createDesktopSshBootstrapTimeoutError(target));
-    }, SAVED_ENVIRONMENT_CONNECT_TIMEOUT_MS);
-  });
-
-  try {
-    return await Promise.race([operation, timeout]);
-  } finally {
-    if (timeoutId !== null) {
-      clearTimeout(timeoutId);
-    }
-  }
-}
-
 function coalesceOrchestrationUiEvents(
   events: ReadonlyArray<OrchestrationEvent>,
 ): OrchestrationEvent[] {
diff --git a/packages/ssh/src/command.ts b/packages/ssh/src/command.ts
index b43484119b7..cadba077602 100644
--- a/packages/ssh/src/command.ts
+++ b/packages/ssh/src/command.ts
@@ -117,6 +117,15 @@ function normalizeSshErrorMessage(stderr: string, fallbackMessage: string): stri
   return cleaned.length > 0 ? cleaned : fallbackMessage;
 }
 
+function sshTargetLogFields(target: DesktopSshEnvironmentTarget) {
+  return {
+    alias: target.alias,
+    hostname: target.hostname,
+    username: target.username,
+    port: target.port,
+  };
+}
+
 function stdinStream(input: string | undefined) {
   return input === undefined ? Stream.empty : Stream.make(encoder.encode(input));
 }
@@ -155,6 +164,12 @@ const runSshCommandInScope = Effect.fn("ssh/command.runSshCommand.inScope")(func
     ...(input.remoteCommandArgs ?? []),
   ];
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  yield* Effect.logDebug("ssh.command.start", {
+    ...sshTargetLogFields(target),
+    command: ["ssh", ...args],
+    hasStdin: input.stdin !== undefined,
+    timeoutMs: input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS,
+  });
   const child = yield* spawner
     .spawn(
       ChildProcess.make("ssh", args, {
@@ -205,6 +220,12 @@ const runSshCommandInScope = Effect.fn("ssh/command.runSshCommand.inScope")(func
   );
 
   if (exitCode !== 0) {
+    yield* Effect.logWarning("ssh.command.failed", {
+      ...sshTargetLogFields(target),
+      command: ["ssh", ...args],
+      exitCode,
+      stderr,
+    });
     return yield* new SshCommandError({
       command: ["ssh", ...args],
       exitCode,
@@ -216,6 +237,10 @@ const runSshCommandInScope = Effect.fn("ssh/command.runSshCommand.inScope")(func
     });
   }
 
+  yield* Effect.logDebug("ssh.command.succeeded", {
+    ...sshTargetLogFields(target),
+    command: ["ssh", ...args],
+  });
   return { stdout, stderr };
 });
 
@@ -235,14 +260,21 @@ export const runSshCommand = Effect.fn("ssh/command.runSshCommand")(function* (
       Option.match(result, {
         onSome: Effect.succeed,
         onNone: () =>
-          Effect.fail(
-            new SshCommandError({
+          Effect.gen(function* () {
+            yield* Effect.logWarning("ssh.command.timedOut", {
+              ...sshTargetLogFields(target),
+              timeoutMs: input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS,
+              remoteCommandArgs: input.remoteCommandArgs ?? [],
+              preHostArgs: input.preHostArgs ?? [],
+              hasStdin: input.stdin !== undefined,
+            });
+            return yield* new SshCommandError({
               command: ["ssh"],
               exitCode: null,
               stderr: "",
               message: `SSH command timed out after ${input.timeoutMs ?? DEFAULT_SSH_COMMAND_TIMEOUT_MS}ms.`,
-            }),
-          ),
+            });
+          }),
       }),
     ),
   );
@@ -260,6 +292,7 @@ export const resolveSshTarget = Effect.fn("ssh/command.resolveSshTarget")(functi
     return yield* new SshInvalidTargetError({ message: "SSH host alias is required." });
   }
 
+  yield* Effect.logDebug("ssh.target.resolve.start", { alias: trimmedAlias });
   return yield* runSshCommand(
     {
       alias: trimmedAlias,
@@ -270,13 +303,18 @@ export const resolveSshTarget = Effect.fn("ssh/command.resolveSshTarget")(functi
     { preHostArgs: ["-G"] },
   ).pipe(
     Effect.map((result) => parseSshResolveOutput(trimmedAlias, result.stdout)),
-    Effect.catch(() =>
-      Effect.succeed({
-        alias: trimmedAlias,
-        hostname: trimmedAlias,
-        username: null,
-        port: null,
-      }),
+    Effect.tap((target) =>
+      Effect.logDebug("ssh.target.resolve.succeeded", sshTargetLogFields(target)),
+    ),
+    Effect.catch((cause) =>
+      Effect.logDebug("ssh.target.resolve.fallback", { alias: trimmedAlias, cause }).pipe(
+        Effect.as({
+          alias: trimmedAlias,
+          hostname: trimmedAlias,
+          username: null,
+          port: null,
+        }),
+      ),
     ),
   );
 });
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 5a5f2842f47..ce09f7366b9 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -12,6 +12,7 @@ import {
   Exit,
   FileSystem,
   Layer,
+  Option,
   Path,
   Schema,
   Scope,
@@ -98,6 +99,25 @@ function makeSshTunnelCancelledError(target: DesktopSshEnvironmentTarget): SshCo
   });
 }
 
+function sshTargetLogFields(target: DesktopSshEnvironmentTarget) {
+  return {
+    alias: target.alias,
+    hostname: target.hostname,
+    username: target.username,
+    port: target.port,
+  };
+}
+
+function sshRunnerLogFields(runner: RemoteT3RunnerOptions | undefined) {
+  if (runner?.nodeScriptPath?.trim()) {
+    return { runner: "node-script", nodeScriptPath: runner.nodeScriptPath.trim() };
+  }
+  if (runner?.packageSpec?.trim()) {
+    return { runner: "package", packageSpec: runner.packageSpec.trim() };
+  }
+  return { runner: "default" };
+}
+
 interface SshAuthOperationInput<T> {
   readonly key: string;
   readonly target: DesktopSshEnvironmentTarget;
@@ -341,6 +361,11 @@ export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemo
     SshCommandError | SshInvalidTargetError | SshLaunchError,
     ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
   > {
+    yield* Effect.logInfo("ssh.remoteServer.launch.start", {
+      ...sshTargetLogFields(target),
+      ...sshRunnerLogFields(runner),
+      stateKey: remoteStateKey(target),
+    });
     const result = yield* runSshCommand(target, {
       remoteCommandArgs: ["sh", "-s", "--", remoteStateKey(target)],
       stdin: buildRemoteLaunchScript(runner),
@@ -370,6 +395,11 @@ export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemo
         stdout: result.stdout,
       });
     }
+    yield* Effect.logInfo("ssh.remoteServer.launch.ready", {
+      ...sshTargetLogFields(target),
+      remotePort: parsed.remotePort,
+      stateKey: remoteStateKey(target),
+    });
     return parsed.remotePort;
   },
 );
@@ -383,6 +413,10 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
   SshCommandError | SshInvalidTargetError | SshPairingError,
   ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
 > {
+  yield* Effect.logInfo("ssh.remoteServer.pairingToken.start", {
+    ...sshTargetLogFields(target),
+    stateKey: remoteStateKey(target),
+  });
   const result = yield* runSshCommand(target, {
     remoteCommandArgs: ["sh", "-s"],
     stdin: buildRemotePairingScript(target, runner),
@@ -412,6 +446,10 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
       stdout: result.stdout,
     });
   }
+  yield* Effect.logInfo("ssh.remoteServer.pairingToken.created", {
+    ...sshTargetLogFields(target),
+    stateKey: remoteStateKey(target),
+  });
   return parsed.credential;
 });
 
@@ -423,6 +461,10 @@ export const stopRemoteServer = Effect.fn("ssh/tunnel.stopRemoteServer")(functio
   SshCommandError | SshInvalidTargetError,
   ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
 > {
+  yield* Effect.logInfo("ssh.remoteServer.stop.start", {
+    ...sshTargetLogFields(target),
+    stateKey: remoteStateKey(target),
+  });
   yield* runSshCommand(target, {
     remoteCommandArgs: ["sh", "-s"],
     stdin: buildRemoteStopScript(target),
@@ -430,6 +472,10 @@ export const stopRemoteServer = Effect.fn("ssh/tunnel.stopRemoteServer")(functio
     ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
     ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
   });
+  yield* Effect.logInfo("ssh.remoteServer.stop.succeeded", {
+    ...sshTargetLogFields(target),
+    stateKey: remoteStateKey(target),
+  });
 });
 
 export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(function* (input: {
@@ -442,24 +488,44 @@ export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(functio
   const intervalMs = input.intervalMs ?? 100;
   const maxRetries = Math.max(0, Math.ceil(timeoutMs / intervalMs));
   const requestUrl = new URL(input.path ?? "/", input.baseUrl).toString();
-  const client = (yield* HttpClient.HttpClient).pipe(
-    HttpClient.filterStatusOk,
-    HttpClient.retry({
-      schedule: Schedule.spaced(Duration.millis(intervalMs)),
-      times: maxRetries,
-    }),
-  );
+  const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk);
+
+  yield* Effect.logInfo("ssh.tunnel.httpReady.start", {
+    baseUrl: input.baseUrl,
+    requestUrl,
+    timeoutMs,
+    intervalMs,
+  });
 
-  yield* client.execute(HttpClientRequest.get(requestUrl)).pipe(
+  const result = yield* client.execute(HttpClientRequest.get(requestUrl)).pipe(
     Effect.asVoid,
     Effect.mapError(
       (cause) =>
         new SshReadinessError({
-          message: `Timed out waiting for backend readiness at ${input.baseUrl}.`,
+          message: `Backend readiness probe failed at ${input.baseUrl}.`,
           cause,
         }),
     ),
+    Effect.retry({
+      schedule: Schedule.spaced(Duration.millis(intervalMs)),
+      times: maxRetries,
+    }),
+    Effect.timeoutOption(Duration.millis(timeoutMs)),
   );
+
+  return yield* Option.match(result, {
+    onSome: () =>
+      Effect.logInfo("ssh.tunnel.httpReady.succeeded", {
+        baseUrl: input.baseUrl,
+        requestUrl,
+      }),
+    onNone: () =>
+      Effect.fail(
+        new SshReadinessError({
+          message: `Timed out waiting ${timeoutMs}ms for backend readiness at ${input.baseUrl}.`,
+        }),
+      ),
+  });
 });
 
 function isLoopbackHostname(hostname: string): boolean {
@@ -616,6 +682,12 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
   ];
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const scope = yield* Scope.Scope;
+  yield* Effect.logInfo("ssh.tunnel.spawn.start", {
+    ...sshTargetLogFields(input.resolvedTarget),
+    localPort: input.localPort,
+    remotePort: input.remotePort,
+    httpBaseUrl: input.httpBaseUrl,
+  });
   const child = yield* spawner
     .spawn(
       ChildProcess.make("ssh", args, {
@@ -638,6 +710,12 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
           }),
       ),
     );
+  yield* Effect.logInfo("ssh.tunnel.spawn.succeeded", {
+    ...sshTargetLogFields(input.resolvedTarget),
+    localPort: input.localPort,
+    remotePort: input.remotePort,
+    httpBaseUrl: input.httpBaseUrl,
+  });
   const tunnelEntry: SshTunnelEntry = {
     key: input.key,
     target: input.resolvedTarget,
@@ -686,6 +764,23 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     }),
     exitFailure,
   ).pipe(
+    Effect.tap(() =>
+      Effect.logInfo("ssh.tunnel.ready", {
+        ...sshTargetLogFields(input.resolvedTarget),
+        localPort: input.localPort,
+        remotePort: input.remotePort,
+        httpBaseUrl: input.httpBaseUrl,
+      }),
+    ),
+    Effect.tapError((cause) =>
+      Effect.logWarning("ssh.tunnel.ready.failed", {
+        ...sshTargetLogFields(input.resolvedTarget),
+        localPort: input.localPort,
+        remotePort: input.remotePort,
+        httpBaseUrl: input.httpBaseUrl,
+        cause,
+      }),
+    ),
     Effect.onExit((exit) =>
       Exit.isSuccess(exit)
         ? Effect.void
@@ -714,7 +809,19 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
   const closeTunnelEntry = Effect.fn("ssh/tunnel.closeTunnelEntry")(function* (
     entry: SshTunnelEntry,
   ) {
+    yield* Effect.logInfo("ssh.tunnel.close.start", {
+      ...sshTargetLogFields(entry.target),
+      key: entry.key,
+      localPort: entry.localPort,
+      remotePort: entry.remotePort,
+    });
     yield* Scope.close(entry.scope, Exit.void).pipe(Effect.ignore);
+    yield* Effect.logInfo("ssh.tunnel.close.succeeded", {
+      ...sshTargetLogFields(entry.target),
+      key: entry.key,
+      localPort: entry.localPort,
+      remotePort: entry.remotePort,
+    });
   });
 
   yield* Scope.addFinalizer(
@@ -734,11 +841,19 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     const promptService = yield* SshPasswordPrompt;
     const hostSpec = yield* buildSshHostSpecEffect(target);
     if (!promptService.isAvailable) {
+      yield* Effect.logWarning("ssh.auth.passwordPrompt.unavailable", {
+        ...sshTargetLogFields(target),
+        attempt,
+      });
       return yield* new SshPasswordPromptError({
         message: `SSH authentication failed for ${hostSpec}.`,
       });
     }
 
+    yield* Effect.logInfo("ssh.auth.passwordPrompt.request", {
+      ...sshTargetLogFields(target),
+      attempt,
+    });
     const password = yield* promptService.request({
       attempt,
       destination: target.alias.trim() || target.hostname.trim(),
@@ -746,10 +861,18 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       prompt: `Enter the SSH password for ${hostSpec}.`,
     });
     if (password === null) {
+      yield* Effect.logWarning("ssh.auth.passwordPrompt.cancelled", {
+        ...sshTargetLogFields(target),
+        attempt,
+      });
       return yield* new SshPasswordPromptError({
         message: `SSH authentication cancelled for ${hostSpec}.`,
       });
     }
+    yield* Effect.logInfo("ssh.auth.passwordPrompt.received", {
+      ...sshTargetLogFields(target),
+      attempt,
+    });
     return password;
   });
 
@@ -763,6 +886,12 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
         return yield* input.error;
       }
 
+      yield* Effect.logWarning("ssh.auth.failed", {
+        ...sshTargetLogFields(input.target),
+        key: input.key,
+        promptCount: input.promptCount,
+        cause: input.error,
+      });
       const promptService = yield* SshPasswordPrompt;
       if (!promptService.isAvailable) {
         return yield* input.error;
@@ -821,15 +950,31 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     readonly resolvedTarget: DesktopSshEnvironmentTarget;
     readonly runner?: RemoteT3RunnerOptions;
   }): Effect.fn.Return<SshTunnelEntry, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    yield* Effect.logInfo("ssh.environment.tunnel.create.start", {
+      ...sshTargetLogFields(input.resolvedTarget),
+      ...sshRunnerLogFields(input.runner),
+      key: input.key,
+    });
     const remotePort = yield* runWithSshAuth({
       key: input.key,
       target: input.resolvedTarget,
       operation: (authOptions) =>
         launchOrReuseRemoteServer(input.resolvedTarget, authOptions, input.runner),
     });
+    yield* Effect.logInfo("ssh.environment.remotePort.ready", {
+      ...sshTargetLogFields(input.resolvedTarget),
+      key: input.key,
+      remotePort,
+    });
     const localPort = yield* reserveLocalTunnelPort();
     const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
     const wsBaseUrl = `ws://127.0.0.1:${localPort}/`;
+    yield* Effect.logInfo("ssh.environment.localPort.reserved", {
+      ...sshTargetLogFields(input.resolvedTarget),
+      key: input.key,
+      localPort,
+      remotePort,
+    });
     const entryScope = yield* Scope.make("sequential");
     const tunnelEntry = yield* runWithSshAuth({
       key: input.key,
@@ -859,6 +1004,12 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
         if (tunnels.get(tunnelEntry.key) !== tunnelEntry) {
           return;
         }
+        yield* Effect.logInfo("ssh.environment.tunnel.finalizer.start", {
+          ...sshTargetLogFields(tunnelEntry.target),
+          key: tunnelEntry.key,
+          localPort: tunnelEntry.localPort,
+          remotePort: tunnelEntry.remotePort,
+        });
         tunnels.delete(tunnelEntry.key);
         const authSecret = authSecrets.get(tunnelEntry.key) ?? null;
         yield* Effect.all(
@@ -887,8 +1038,20 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
           ],
           { concurrency: "unbounded" },
         ).pipe(Effect.ignore);
+        yield* Effect.logInfo("ssh.environment.tunnel.finalizer.succeeded", {
+          ...sshTargetLogFields(tunnelEntry.target),
+          key: tunnelEntry.key,
+          localPort: tunnelEntry.localPort,
+          remotePort: tunnelEntry.remotePort,
+        });
       }).pipe(Effect.ignore),
     );
+    yield* Effect.logInfo("ssh.environment.tunnel.create.succeeded", {
+      ...sshTargetLogFields(input.resolvedTarget),
+      key: input.key,
+      localPort,
+      remotePort,
+    });
     return tunnelEntry;
   });
 
@@ -900,18 +1063,41 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     let entry = tunnels.get(key) ?? null;
 
     if (entry !== null) {
+      yield* Effect.logDebug("ssh.environment.tunnel.existing.check", {
+        ...sshTargetLogFields(resolvedTarget),
+        key,
+        localPort: entry.localPort,
+        remotePort: entry.remotePort,
+      });
       const readinessExit = yield* Effect.exit(
         waitForHttpReady({ baseUrl: entry.httpBaseUrl, timeoutMs: 2_000 }),
       );
       if (Exit.isSuccess(readinessExit)) {
+        yield* Effect.logInfo("ssh.environment.tunnel.reused", {
+          ...sshTargetLogFields(resolvedTarget),
+          key,
+          localPort: entry.localPort,
+          remotePort: entry.remotePort,
+        });
         return entry;
       }
+      yield* Effect.logWarning("ssh.environment.tunnel.existing.stale", {
+        ...sshTargetLogFields(resolvedTarget),
+        key,
+        localPort: entry.localPort,
+        remotePort: entry.remotePort,
+        cause: readinessExit.cause,
+      });
       yield* closeTunnelEntry(entry);
       entry = null;
     }
 
     const pending = pendingTunnelEntries.get(key);
     if (pending) {
+      yield* Effect.logInfo("ssh.environment.tunnel.pending.await", {
+        ...sshTargetLogFields(resolvedTarget),
+        key,
+      });
       return yield* Deferred.await(pending);
     }
 
@@ -923,6 +1109,13 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       resolvedTarget,
       ...(runner === undefined ? {} : { runner }),
     }).pipe(
+      Effect.tapError((cause) =>
+        Effect.logWarning("ssh.environment.tunnel.create.failed", {
+          ...sshTargetLogFields(resolvedTarget),
+          key,
+          cause,
+        }),
+      ),
       Effect.onExit((exit) =>
         Effect.sync(() => {
           if (pendingTunnelEntries.get(key) === deferred) {
@@ -941,6 +1134,10 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     SshEnvironmentEffectError,
     SshEnvironmentEffectContext
   > {
+    yield* Effect.logInfo("ssh.environment.ensure.start", {
+      ...sshTargetLogFields(target),
+      issuePairingToken: requestOptions?.issuePairingToken === true,
+    });
     const baseResolved = yield* resolveSshTarget(target.alias || target.hostname);
     const resolvedTarget: DesktopSshEnvironmentTarget = {
       ...baseResolved,
@@ -948,9 +1145,18 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       ...(target.port !== null ? { port: target.port } : {}),
     };
     const key = targetConnectionKey(resolvedTarget);
+    yield* Effect.logInfo("ssh.environment.target.resolved", {
+      ...sshTargetLogFields(resolvedTarget),
+      key,
+    });
     const packageSpec = options.resolveCliPackageSpec?.();
     const runner =
       options.resolveCliRunner?.() ?? (packageSpec === undefined ? undefined : { packageSpec });
+    yield* Effect.logDebug("ssh.environment.runner.resolved", {
+      ...sshTargetLogFields(resolvedTarget),
+      ...sshRunnerLogFields(runner),
+      key,
+    });
     const entry = yield* ensureTunnelEntry(key, resolvedTarget, runner);
 
     const pairingToken = requestOptions?.issuePairingToken
@@ -961,6 +1167,13 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
         })
       : null;
 
+    yield* Effect.logInfo("ssh.environment.ensure.succeeded", {
+      ...sshTargetLogFields(entry.target),
+      key,
+      localPort: entry.localPort,
+      remotePort: entry.remotePort,
+      issuedPairingToken: pairingToken !== null,
+    });
     return {
       target: entry.target,
       httpBaseUrl: entry.httpBaseUrl,
@@ -972,6 +1185,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
   const disconnectEnvironment = Effect.fn("ssh/tunnel.disconnectEnvironment")(function* (
     target: DesktopSshEnvironmentTarget,
   ): Effect.fn.Return<void, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
+    yield* Effect.logInfo("ssh.environment.disconnect.start", sshTargetLogFields(target));
     const baseResolved = yield* resolveSshTarget(target.alias || target.hostname);
     const resolvedTarget: DesktopSshEnvironmentTarget = {
       ...baseResolved,
@@ -980,6 +1194,12 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     };
     const key = targetConnectionKey(resolvedTarget);
     const entry = tunnels.get(key) ?? null;
+    yield* Effect.logDebug("ssh.environment.disconnect.targetResolved", {
+      ...sshTargetLogFields(resolvedTarget),
+      key,
+      hasTunnel: entry !== null,
+      hasPendingTunnel: pendingTunnelEntries.has(key),
+    });
     if (entry !== null) {
       yield* closeTunnelEntry(entry);
     }
@@ -997,6 +1217,10 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
         operation: (authOptions) => stopRemoteServer(resolvedTarget, authOptions),
       });
     }
+    yield* Effect.logInfo("ssh.environment.disconnect.succeeded", {
+      ...sshTargetLogFields(resolvedTarget),
+      key,
+    });
   });
 
   return SshEnvironmentManager.of({ ensureEnvironment, disconnectEnvironment });

From 9ec937808e1aeff4fe796d9bda7d562b2a020a84 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 17:23:50 -0700
Subject: [PATCH 41/74] Improve SSH tunnel failure diagnostics

- tail remote server logs on readiness failures
- log tunnel command, PID, and local port state
- capture last HTTP probe failure on timeout
---
 packages/ssh/src/tunnel.ts | 196 ++++++++++++++++++++++++++++++-------
 1 file changed, 163 insertions(+), 33 deletions(-)

diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index ce09f7366b9..a61ed2b47d3 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -14,9 +14,11 @@ import {
   Layer,
   Option,
   Path,
+  Ref,
   Schema,
   Scope,
   Schedule,
+  Stream,
 } from "effect";
 import { HttpClient, HttpClientRequest } from "effect/unstable/http";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
@@ -315,6 +317,14 @@ rm -f "$PID_FILE" "$PORT_FILE"
 printf '{"stopped":true}\\n'
 `;
 
+const REMOTE_LOG_TAIL_SCRIPT = `set -eu
+STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
+LOG_FILE="$STATE_DIR/server.log"
+if [ -f "$LOG_FILE" ]; then
+  tail -n 80 "$LOG_FILE" 2>/dev/null || true
+fi
+`;
+
 export function buildRemoteT3RunnerScript(input?: RemoteT3RunnerOptions): string {
   const packageSpec = input?.packageSpec?.trim() || "t3@latest";
   const nodeScriptPath = input?.nodeScriptPath?.trim() || "";
@@ -351,6 +361,12 @@ export function buildRemoteStopScript(target: DesktopSshEnvironmentTarget): stri
   });
 }
 
+function buildRemoteLogTailScript(target: DesktopSshEnvironmentTarget): string {
+  return applyScriptPlaceholders(REMOTE_LOG_TAIL_SCRIPT, {
+    T3_STATE_KEY: remoteStateKey(target),
+  });
+}
+
 export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemoteServer")(
   function* (
     target: DesktopSshEnvironmentTarget,
@@ -478,6 +494,25 @@ export const stopRemoteServer = Effect.fn("ssh/tunnel.stopRemoteServer")(functio
   });
 });
 
+const readRemoteServerLogTail = Effect.fn("ssh/tunnel.readRemoteServerLogTail")(function* (
+  target: DesktopSshEnvironmentTarget,
+  input?: SshAuthOptions,
+): Effect.fn.Return<
+  string,
+  SshCommandError | SshInvalidTargetError,
+  ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
+> {
+  const result = yield* runSshCommand(target, {
+    remoteCommandArgs: ["sh", "-s"],
+    stdin: buildRemoteLogTailScript(target),
+    timeoutMs: 10_000,
+    ...(input?.authSecret === undefined ? {} : { authSecret: input.authSecret }),
+    ...(input?.batchMode === undefined ? {} : { batchMode: input.batchMode }),
+    ...(input?.interactiveAuth === undefined ? {} : { interactiveAuth: input.interactiveAuth }),
+  });
+  return result.stdout.trim();
+});
+
 export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(function* (input: {
   readonly baseUrl: string;
   readonly timeoutMs?: number;
@@ -488,7 +523,9 @@ export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(functio
   const intervalMs = input.intervalMs ?? 100;
   const maxRetries = Math.max(0, Math.ceil(timeoutMs / intervalMs));
   const requestUrl = new URL(input.path ?? "/", input.baseUrl).toString();
-  const client = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk);
+  const client = yield* HttpClient.HttpClient;
+  const lastProbeFailure = yield* Ref.make<unknown>(null);
+  let attempt = 0;
 
   yield* Effect.logInfo("ssh.tunnel.httpReady.start", {
     baseUrl: input.baseUrl,
@@ -497,15 +534,46 @@ export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(functio
     intervalMs,
   });
 
-  const result = yield* client.execute(HttpClientRequest.get(requestUrl)).pipe(
-    Effect.asVoid,
-    Effect.mapError(
-      (cause) =>
-        new SshReadinessError({
-          message: `Backend readiness probe failed at ${input.baseUrl}.`,
-          cause,
-        }),
+  const probe = Effect.gen(function* () {
+    attempt += 1;
+    const response = yield* client.execute(HttpClientRequest.get(requestUrl)).pipe(
+      Effect.mapError(
+        (cause) =>
+          new SshReadinessError({
+            message: `Backend readiness probe failed at ${requestUrl}.`,
+            cause,
+          }),
+      ),
+    );
+    if (response.status >= 200 && response.status < 300) {
+      return;
+    }
+    const text = yield* response.text.pipe(Effect.catch(() => Effect.succeed("")));
+    return yield* new SshReadinessError({
+      message: `Backend readiness probe returned HTTP ${response.status} at ${requestUrl}.`,
+      cause: {
+        status: response.status,
+        body: text.slice(0, 1_000),
+      },
+    });
+  }).pipe(
+    Effect.mapError((cause) =>
+      cause instanceof SshReadinessError
+        ? cause
+        : new SshReadinessError({
+            message: `Backend readiness probe failed at ${requestUrl}.`,
+            cause,
+          }),
+    ),
+    Effect.tapError((cause) =>
+      Ref.set(lastProbeFailure, {
+        attempt,
+        cause,
+      }),
     ),
+  );
+
+  const result = yield* probe.pipe(
     Effect.retry({
       schedule: Schedule.spaced(Duration.millis(intervalMs)),
       times: maxRetries,
@@ -518,13 +586,24 @@ export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(functio
       Effect.logInfo("ssh.tunnel.httpReady.succeeded", {
         baseUrl: input.baseUrl,
         requestUrl,
+        attempts: attempt,
       }),
     onNone: () =>
-      Effect.fail(
-        new SshReadinessError({
+      Effect.gen(function* () {
+        const lastFailure = yield* Ref.get(lastProbeFailure);
+        yield* Effect.logWarning("ssh.tunnel.httpReady.timedOut", {
+          baseUrl: input.baseUrl,
+          requestUrl,
+          timeoutMs,
+          intervalMs,
+          attempts: attempt,
+          lastFailure,
+        });
+        return yield* new SshReadinessError({
           message: `Timed out waiting ${timeoutMs}ms for backend readiness at ${input.baseUrl}.`,
-        }),
-      ),
+          cause: lastFailure,
+        });
+      }),
   });
 });
 
@@ -643,6 +722,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
   | FileSystem.FileSystem
   | Path.Path
   | HttpClient.HttpClient
+  | NetService
   | Scope.Scope
 > {
   const hostSpec = yield* buildSshHostSpecEffect(input.resolvedTarget);
@@ -675,15 +755,18 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     "ServerAliveInterval=15",
     "-o",
     "ServerAliveCountMax=3",
+    "-n",
     "-N",
     "-L",
     `${input.localPort}:127.0.0.1:${input.remotePort}`,
     hostSpec,
   ];
+  const tunnelCommand = ["ssh", ...args];
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const scope = yield* Scope.Scope;
   yield* Effect.logInfo("ssh.tunnel.spawn.start", {
     ...sshTargetLogFields(input.resolvedTarget),
+    command: tunnelCommand,
     localPort: input.localPort,
     remotePort: input.remotePort,
     httpBaseUrl: input.httpBaseUrl,
@@ -693,13 +776,17 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
       ChildProcess.make("ssh", args, {
         env: childEnvironment,
         shell: process.platform === "win32",
+        stdin: {
+          stream: Stream.empty,
+          endOnDone: true,
+        },
       }),
     )
     .pipe(
       Effect.mapError(
         (cause) =>
           new SshCommandError({
-            command: ["ssh", ...args],
+            command: tunnelCommand,
             exitCode: null,
             stderr: "",
             message:
@@ -712,6 +799,8 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     );
   yield* Effect.logInfo("ssh.tunnel.spawn.succeeded", {
     ...sshTargetLogFields(input.resolvedTarget),
+    command: tunnelCommand,
+    pid: child.pid,
     localPort: input.localPort,
     remotePort: input.remotePort,
     httpBaseUrl: input.httpBaseUrl,
@@ -733,7 +822,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     Effect.mapError(
       (cause) =>
         new SshCommandError({
-          command: ["ssh", ...args],
+          command: tunnelCommand,
           exitCode: null,
           stderr: "",
           message:
@@ -743,19 +832,27 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
           cause,
         }),
     ),
-    Effect.flatMap(([stderr, exitCode]) =>
-      Effect.fail(
-        new SshCommandError({
-          command: ["ssh", ...args],
-          exitCode,
+    Effect.flatMap(([stderr, exitCode]) => {
+      const error = new SshCommandError({
+        command: tunnelCommand,
+        exitCode,
+        stderr,
+        message: normalizeSshErrorMessage(
           stderr,
-          message: normalizeSshErrorMessage(
-            stderr,
-            `SSH tunnel exited unexpectedly for ${input.resolvedTarget.alias} (exit ${exitCode}).`,
-          ),
-        }),
-      ),
-    ),
+          `SSH tunnel exited unexpectedly for ${input.resolvedTarget.alias} (exit ${exitCode}).`,
+        ),
+      });
+      return Effect.logWarning("ssh.tunnel.process.exited", {
+        ...sshTargetLogFields(input.resolvedTarget),
+        command: tunnelCommand,
+        pid: child.pid,
+        localPort: input.localPort,
+        remotePort: input.remotePort,
+        httpBaseUrl: input.httpBaseUrl,
+        exitCode,
+        stderr,
+      }).pipe(Effect.andThen(Effect.fail(error)));
+    }),
   );
   yield* Effect.raceFirst(
     waitForHttpReady({
@@ -767,18 +864,51 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     Effect.tap(() =>
       Effect.logInfo("ssh.tunnel.ready", {
         ...sshTargetLogFields(input.resolvedTarget),
+        command: tunnelCommand,
+        pid: child.pid,
         localPort: input.localPort,
         remotePort: input.remotePort,
         httpBaseUrl: input.httpBaseUrl,
       }),
     ),
     Effect.tapError((cause) =>
-      Effect.logWarning("ssh.tunnel.ready.failed", {
-        ...sshTargetLogFields(input.resolvedTarget),
-        localPort: input.localPort,
-        remotePort: input.remotePort,
-        httpBaseUrl: input.httpBaseUrl,
-        cause,
+      Effect.gen(function* () {
+        const net = yield* NetService;
+        const processRunningExit = yield* Effect.exit(child.isRunning);
+        const localPortAvailableExit = yield* Effect.exit(
+          net.canListenOnHost(input.localPort, "127.0.0.1"),
+        );
+        const remoteLogTailExit = yield* Effect.exit(
+          readRemoteServerLogTail(input.resolvedTarget, input.authOptions),
+        );
+        const processRunning = Exit.isSuccess(processRunningExit) ? processRunningExit.value : null;
+        const localPortAvailable = Exit.isSuccess(localPortAvailableExit)
+          ? localPortAvailableExit.value
+          : null;
+        const remoteLogTail = Exit.isSuccess(remoteLogTailExit)
+          ? remoteLogTailExit.value || null
+          : null;
+        yield* Effect.logWarning("ssh.tunnel.ready.failed", {
+          ...sshTargetLogFields(input.resolvedTarget),
+          command: tunnelCommand,
+          pid: child.pid,
+          processRunning,
+          ...(Exit.isSuccess(processRunningExit)
+            ? {}
+            : { processRunningError: processRunningExit.cause }),
+          localPort: input.localPort,
+          localPortListening: localPortAvailable === null ? null : !localPortAvailable,
+          remotePort: input.remotePort,
+          httpBaseUrl: input.httpBaseUrl,
+          ...(Exit.isSuccess(localPortAvailableExit)
+            ? {}
+            : { localPortProbeError: localPortAvailableExit.cause }),
+          ...(remoteLogTail === null ? {} : { remoteLogTail }),
+          ...(Exit.isSuccess(remoteLogTailExit)
+            ? {}
+            : { remoteLogTailError: remoteLogTailExit.cause }),
+          cause,
+        });
       }),
     ),
     Effect.onExit((exit) =>

From b7f144b89128c9e1067ab15d49e4abbcf85409bb Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 19:50:29 -0700
Subject: [PATCH 42/74] Improve hosted pairing and reconnect flows

- Add desktop SSH cancellation handling for environment setup
- Let chat reconnect a saved environment from the unavailable state
- Refine connections UI for hosted pairing links, network access, and favicon fallbacks
---
 apps/desktop/src/preload.ts                   |  23 +-
 apps/desktop/src/sshEnvironment.ts            |  23 +-
 apps/web/src/components/ChatView.tsx          |  30 +
 apps/web/src/components/ProjectFavicon.tsx    |  26 +-
 .../settings/ConnectionsSettings.tsx          | 851 ++++++++++--------
 apps/web/src/environments/runtime/service.ts  |   1 +
 apps/web/src/store.test.ts                    |  34 +
 apps/web/src/store.ts                         |  17 +
 packages/ssh/src/tunnel.test.ts               |  36 +-
 packages/ssh/src/tunnel.ts                    | 240 +++--
 10 files changed, 858 insertions(+), 423 deletions(-)

diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index c094cbada2a..b3b553fe214 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -35,6 +35,23 @@ const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
 const SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
 const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
+const SSH_PASSWORD_PROMPT_CANCELLED_RESULT = "ssh-password-prompt-cancelled";
+
+function unwrapEnsureSshEnvironmentResult(result: unknown) {
+  if (
+    typeof result === "object" &&
+    result !== null &&
+    "type" in result &&
+    result.type === SSH_PASSWORD_PROMPT_CANCELLED_RESULT
+  ) {
+    const message =
+      "message" in result && typeof result.message === "string"
+        ? result.message
+        : "SSH authentication cancelled.";
+    throw new Error(message);
+  }
+  return result as Awaited<ReturnType<DesktopBridge["ensureSshEnvironment"]>>;
+}
 
 contextBridge.exposeInMainWorld("desktopBridge", {
   getAppBranding: () => {
@@ -63,8 +80,10 @@ contextBridge.exposeInMainWorld("desktopBridge", {
   removeSavedEnvironmentSecret: (environmentId) =>
     ipcRenderer.invoke(REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL, environmentId),
   discoverSshHosts: () => ipcRenderer.invoke(DISCOVER_SSH_HOSTS_CHANNEL),
-  ensureSshEnvironment: (target, options) =>
-    ipcRenderer.invoke(ENSURE_SSH_ENVIRONMENT_CHANNEL, target, options),
+  ensureSshEnvironment: async (target, options) =>
+    unwrapEnsureSshEnvironmentResult(
+      await ipcRenderer.invoke(ENSURE_SSH_ENVIRONMENT_CHANNEL, target, options),
+    ),
   disconnectSshEnvironment: (target) =>
     ipcRenderer.invoke(DISCONNECT_SSH_ENVIRONMENT_CHANNEL, target),
   fetchSshEnvironmentDescriptor: (httpBaseUrl) =>
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index e636e87d6d8..c4c288aade1 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -38,6 +38,7 @@ const ISSUE_SSH_WEBSOCKET_TOKEN_CHANNEL = "desktop:issue-ssh-websocket-token";
 const SSH_PASSWORD_PROMPT_CHANNEL = "desktop:ssh-password-prompt";
 const RESOLVE_SSH_PASSWORD_PROMPT_CHANNEL = "desktop:resolve-ssh-password-prompt";
 const DEFAULT_SSH_PASSWORD_PROMPT_TIMEOUT_MS = 3 * 60 * 1000;
+const SSH_PASSWORD_PROMPT_CANCELLED_RESULT = "ssh-password-prompt-cancelled";
 
 interface DesktopSshEnvironmentManagerOptions {
   readonly passwordProvider?: (request: SshPasswordRequest) => Promise<string | null>;
@@ -202,6 +203,12 @@ interface PendingSshPasswordPrompt {
   readonly timeout: ReturnType<typeof setTimeout>;
 }
 
+function isSshPasswordPromptCancellation(error: unknown): error is SshPasswordPromptError {
+  return (
+    error instanceof SshPasswordPromptError && error.message.toLowerCase().includes("cancelled")
+  );
+}
+
 /**
  * Wires the SSH environment manager to Electron IPC, owning the renderer-facing
  * password prompt state so `main.ts` only needs to register, cancel, and dispose.
@@ -244,9 +251,19 @@ export class DesktopSshEnvironmentBridge {
         "issuePairingToken" in rawOptions &&
         (rawOptions as { issuePairingToken?: unknown }).issuePairingToken === true;
 
-      return await this.manager.ensureEnvironment(target, {
-        issuePairingToken,
-      });
+      try {
+        return await this.manager.ensureEnvironment(target, {
+          issuePairingToken,
+        });
+      } catch (error) {
+        if (isSshPasswordPromptCancellation(error)) {
+          return {
+            type: SSH_PASSWORD_PROMPT_CANCELLED_RESULT,
+            message: error.message,
+          };
+        }
+        throw error;
+      }
     });
 
     ipcMain.removeHandler(DISCONNECT_SSH_ENVIRONMENT_CHANNEL);
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 937b17a64ba..7685c0f419d 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -121,6 +121,7 @@ import { resolveAppModelSelectionForInstance } from "../modelSelection";
 import { isTerminalFocused } from "../lib/terminalFocus";
 import { deriveLogicalProjectKeyFromSettings } from "../logicalProject";
 import {
+  reconnectSavedEnvironment,
   useSavedEnvironmentRegistryStore,
   useSavedEnvironmentRuntimeStore,
 } from "../environments/runtime";
@@ -190,6 +191,7 @@ const EMPTY_PROPOSED_PLANS: Thread["proposedPlans"] = [];
 const EMPTY_PROVIDERS: ServerProvider[] = [];
 const EMPTY_PENDING_USER_INPUT_ANSWERS: Record<string, PendingUserInputDraftAnswer> = {};
 type EnvironmentUnavailableState = {
+  readonly environmentId: EnvironmentId;
   readonly label: string;
   readonly connectionState: "connecting" | "disconnected" | "error";
 };
@@ -884,6 +886,7 @@ export default function ChatView(props: ChatViewProps) {
   const activeEnvironmentUnavailableState: EnvironmentUnavailableState | null =
     activeEnvironmentUnavailable && activeEnvironmentUnavailableLabel
       ? {
+          environmentId: activeSavedEnvironmentRecord.environmentId,
           label: activeEnvironmentUnavailableLabel,
           connectionState:
             activeSavedEnvironmentConnectionState === "connecting" ||
@@ -892,6 +895,33 @@ export default function ChatView(props: ChatViewProps) {
               : "disconnected",
         }
       : null;
+  const [reconnectingEnvironmentId, setReconnectingEnvironmentId] = useState<EnvironmentId | null>(
+    null,
+  );
+  const handleReconnectActiveEnvironment = useCallback(
+    async (environmentId: EnvironmentId, label: string) => {
+      setReconnectingEnvironmentId(environmentId);
+      try {
+        await reconnectSavedEnvironment(environmentId);
+        toastManager.add({
+          type: "success",
+          title: "Environment reconnected",
+          description: `${label} is ready.`,
+        });
+      } catch (error) {
+        toastManager.add(
+          stackedThreadToast({
+            type: "error",
+            title: "Could not reconnect environment",
+            description: error instanceof Error ? error.message : "Failed to reconnect.",
+          }),
+        );
+      } finally {
+        setReconnectingEnvironmentId(null);
+      }
+    },
+    [],
+  );
   const projectGroupingSettings = useSettings((settings) => ({
     sidebarProjectGroupingMode: settings.sidebarProjectGroupingMode,
     sidebarProjectGroupingOverrides: settings.sidebarProjectGroupingOverrides,
diff --git a/apps/web/src/components/ProjectFavicon.tsx b/apps/web/src/components/ProjectFavicon.tsx
index 38e07f59ced..ad47e01bb11 100644
--- a/apps/web/src/components/ProjectFavicon.tsx
+++ b/apps/web/src/components/ProjectFavicon.tsx
@@ -10,15 +10,29 @@ export function ProjectFavicon(input: {
   cwd: string;
   className?: string;
 }) {
-  const src = resolveEnvironmentHttpUrl({
-    environmentId: input.environmentId,
-    pathname: "/api/project-favicon",
-    searchParams: { cwd: input.cwd },
-  });
+  const src = (() => {
+    try {
+      return resolveEnvironmentHttpUrl({
+        environmentId: input.environmentId,
+        pathname: "/api/project-favicon",
+        searchParams: { cwd: input.cwd },
+      });
+    } catch {
+      return null;
+    }
+  })();
   const [status, setStatus] = useState<"loading" | "loaded" | "error">(() =>
-    loadedProjectFaviconSrcs.has(src) ? "loaded" : "loading",
+    src && loadedProjectFaviconSrcs.has(src) ? "loaded" : "loading",
   );
 
+  if (!src) {
+    return (
+      <FolderIcon
+        className={`size-3.5 shrink-0 text-muted-foreground/50 ${input.className ?? ""}`}
+      />
+    );
+  }
+
   return (
     <>
       {status !== "loaded" ? (
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index bfba67f12a6..efdb7ab65fa 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -67,7 +67,15 @@ import { stackedThreadToast, toastManager } from "../ui/toast";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
 import { Button } from "../ui/button";
 import { Group, GroupSeparator } from "../ui/group";
-import { Menu, MenuItem, MenuPopup, MenuTrigger } from "../ui/menu";
+import {
+  Menu,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuItem,
+  MenuPopup,
+  MenuSeparator,
+  MenuTrigger,
+} from "../ui/menu";
 import { Textarea } from "../ui/textarea";
 import { getPairingTokenFromUrl, setPairingTokenOnUrl } from "../../pairingUrl";
 import { readHostedPairingRequest } from "../../hostedPairing";
@@ -366,6 +374,23 @@ const ENDPOINT_ROW_CLASSNAME = "border-t border-border/60 px-4 py-2.5 first:bord
 const ITEM_ROW_INNER_CLASSNAME =
   "flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between";
 
+type AccessSectionPresentation = "current" | "endpoint-rail";
+
+function accessRowClassName(_presentation: AccessSectionPresentation) {
+  return ITEM_ROW_CLASSNAME;
+}
+
+function endpointRowClassName(presentation: AccessSectionPresentation, isAvailable: boolean) {
+  if (presentation === "endpoint-rail") {
+    return cn(
+      "relative border-t border-border/60 px-4 py-3 first:border-t-0 sm:px-5",
+      !isAvailable && "bg-muted/20",
+    );
+  }
+
+  return cn(ENDPOINT_ROW_CLASSNAME, !isAvailable && "bg-muted/24");
+}
+
 function sortDesktopPairingLinks(links: ReadonlyArray<ServerPairingLinkRecord>) {
   return [...links].toSorted(
     (left, right) => new Date(right.createdAt).getTime() - new Date(left.createdAt).getTime(),
@@ -524,6 +549,7 @@ type PairingLinkListRowProps = {
   endpointUrl: string | null | undefined;
   endpoints: ReadonlyArray<AdvertisedEndpoint>;
   defaultEndpointKey: string | null;
+  presentation?: AccessSectionPresentation;
   revokingPairingLinkId: string | null;
   onRevoke: (id: string) => void;
 };
@@ -533,6 +559,7 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
   endpointUrl,
   endpoints,
   defaultEndpointKey,
+  presentation = "current",
   revokingPairingLinkId,
   onRevoke,
 }: PairingLinkListRowProps) {
@@ -583,23 +610,27 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
   const revealValue = shareablePairingUrl ?? pairingLink.credential;
   const isShareableHostedAppPairingUrl =
     shareablePairingUrl !== null && isHostedAppPairingUrl(shareablePairingUrl);
-  const copyLinkLabel = isShareableHostedAppPairingUrl
-    ? "Copy hosted app link"
-    : "Copy pairing URL";
   const canCopyToClipboard =
     typeof window !== "undefined" &&
     window.isSecureContext &&
     navigator.clipboard?.writeText != null;
 
-  const { copyToClipboard } = useCopyToClipboard<"code" | "link">({
+  const { copyToClipboard } = useCopyToClipboard<"code" | "hosted-link" | "link">({
     onCopy: (kind) => {
       toastManager.add({
         type: "success",
-        title: kind === "link" ? "Pairing URL copied" : "Pairing code copied",
+        title:
+          kind === "hosted-link"
+            ? "Hosted app link copied"
+            : kind === "link"
+              ? "Pairing URL copied"
+              : "Pairing code copied",
         description:
-          kind === "link"
-            ? "Open it in the client you want to pair to this environment."
-            : "Paste it into another client to finish pairing.",
+          kind === "hosted-link"
+            ? "Open it in the browser on the device you want to connect."
+            : kind === "link"
+              ? "Open it in the client you want to pair to this environment."
+              : "Paste it into another client to finish pairing.",
       });
     },
     onError: (error, kind) => {
@@ -608,9 +639,11 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
         stackedThreadToast({
           type: "error",
           title: canCopyToClipboard
-            ? kind === "link"
-              ? "Could not copy pairing URL"
-              : "Could not copy pairing code"
+            ? kind === "hosted-link"
+              ? "Could not copy hosted app link"
+              : kind === "link"
+                ? "Could not copy pairing URL"
+                : "Could not copy pairing code"
             : "Clipboard copy unavailable",
           description: canCopyToClipboard ? error.message : "Showing the full value instead.",
         }),
@@ -619,32 +652,119 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
   });
 
   const copyPairingValue = useCallback(
-    (value: string, kind: "code" | "link") => {
+    (value: string, kind: "code" | "hosted-link" | "link") => {
       copyToClipboard(value, kind);
     },
     [copyToClipboard],
   );
 
+  const copyKindForUrl = useCallback(
+    (url: string): "hosted-link" | "link" => (isHostedAppPairingUrl(url) ? "hosted-link" : "link"),
+    [],
+  );
+
   const handleCopyCode = useCallback(() => {
     copyPairingValue(pairingLink.credential, "code");
   }, [copyPairingValue, pairingLink.credential]);
 
   const handleCopyDefaultLink = useCallback(() => {
     if (!shareablePairingUrl) return;
-    copyPairingValue(shareablePairingUrl, "link");
-  }, [copyPairingValue, shareablePairingUrl]);
+    copyPairingValue(shareablePairingUrl, copyKindForUrl(shareablePairingUrl));
+  }, [copyKindForUrl, copyPairingValue, shareablePairingUrl]);
 
   const expiresAbsolute = formatAccessTimestamp(pairingLink.expiresAt);
 
   const roleLabel = pairingLink.role === "owner" ? "Owner" : "Client";
   const primaryLabel = pairingLink.label ?? `${roleLabel} link`;
+  const defaultEndpointCopyOption =
+    endpointCopyOptions.find((option) => option.key === defaultEndpointKey) ??
+    endpointCopyOptions[0] ??
+    null;
+  const defaultEndpointCopyLabel = defaultEndpointCopyOption?.label ?? "URL";
+  const backendEndpointCopyOptions = endpointCopyOptions.filter(
+    (option) => !isHostedAppPairingUrl(option.url),
+  );
+  const hostedEndpointCopyOptions = endpointCopyOptions.filter((option) =>
+    isHostedAppPairingUrl(option.url),
+  );
+  const renderEndpointMenuItems = (
+    options: typeof endpointCopyOptions = endpointCopyOptions,
+    renderDetail = true,
+  ) =>
+    options.map((option) => (
+      <MenuItem
+        key={option.key}
+        onClick={() => copyPairingValue(option.url, copyKindForUrl(option.url))}
+      >
+        <span className="min-w-0 flex-1">
+          <span className="block truncate">{option.label}</span>
+          {renderDetail ? (
+            <span className="block truncate text-[11px] text-muted-foreground">
+              {option.detail}
+            </span>
+          ) : null}
+        </span>
+      </MenuItem>
+    ));
+  const renderPairingCodeMenuItem = (renderDetail = true) => (
+    <MenuItem onClick={handleCopyCode}>
+      <span className="min-w-0 flex-1">
+        <span className="block truncate">Copy code</span>
+        {renderDetail ? (
+          <span className="block truncate text-[11px] text-muted-foreground">Token only</span>
+        ) : null}
+      </span>
+    </MenuItem>
+  );
+  const renderCompactEndpointGroup = (
+    label: string,
+    options: typeof endpointCopyOptions,
+    includeSeparator: boolean,
+  ) =>
+    options.length > 0 ? (
+      <>
+        {includeSeparator ? <MenuSeparator /> : null}
+        <MenuGroup>
+          <MenuGroupLabel>{label}</MenuGroupLabel>
+          {renderEndpointMenuItems(options, false)}
+        </MenuGroup>
+      </>
+    ) : null;
+  const renderGroupedCopyMenuItems = (options?: { codeFirst?: boolean }) => (
+    <>
+      {options?.codeFirst ? (
+        <>
+          <MenuGroup>
+            <MenuGroupLabel>Pairing code</MenuGroupLabel>
+            {renderPairingCodeMenuItem(false)}
+          </MenuGroup>
+          {endpointCopyOptions.length > 0 ? <MenuSeparator /> : null}
+        </>
+      ) : null}
+      {renderCompactEndpointGroup("Pairing URLs", backendEndpointCopyOptions, false)}
+      {renderCompactEndpointGroup(
+        "Hosted app link",
+        hostedEndpointCopyOptions,
+        backendEndpointCopyOptions.length > 0,
+      )}
+      {!options?.codeFirst ? (
+        <>
+          {endpointCopyOptions.length > 0 ? <MenuSeparator /> : null}
+          <MenuGroup>
+            <MenuGroupLabel>Pairing code</MenuGroupLabel>
+            {renderPairingCodeMenuItem(false)}
+          </MenuGroup>
+        </>
+      ) : null}
+    </>
+  );
 
   if (expiresAtMs <= nowMs) {
     return null;
   }
 
   return (
-    <div className={ITEM_ROW_CLASSNAME}>
+    <div className={accessRowClassName(presentation)}>
       <div className={ITEM_ROW_INNER_CLASSNAME}>
         <div className="min-w-0 flex-1 space-y-1">
           <div className="flex min-h-5 items-center gap-1.5">
@@ -696,51 +816,42 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
           <Dialog open={isRevealDialogOpen} onOpenChange={setIsRevealDialogOpen}>
             {canCopyToClipboard ? (
               <>
-                <Button size="xs" variant="outline" onClick={handleCopyCode}>
-                  Copy code
-                </Button>
                 {shareablePairingUrl ? (
-                  endpointCopyOptions.length > 1 ? (
-                    <Group aria-label="Copy pairing URL">
-                      <Button size="xs" variant="outline" onClick={handleCopyDefaultLink}>
-                        {copyLinkLabel}
-                      </Button>
-                      <GroupSeparator />
-                      <Menu>
-                        <MenuTrigger
-                          render={
-                            <Button
-                              size="icon-xs"
-                              variant="outline"
-                              aria-label="Pairing URL copy options"
-                            />
-                          }
-                        >
-                          <ChevronDownIcon className="size-3.5" />
-                        </MenuTrigger>
-                        <MenuPopup align="end" className="min-w-52">
-                          {endpointCopyOptions.map((option) => (
-                            <MenuItem
-                              key={option.key}
-                              onClick={() => copyPairingValue(option.url, "link")}
-                            >
-                              <span className="min-w-0 flex-1">
-                                <span className="block truncate">{option.label}</span>
-                                <span className="block truncate text-[11px] text-muted-foreground">
-                                  {option.detail}
-                                </span>
-                              </span>
-                            </MenuItem>
-                          ))}
-                        </MenuPopup>
-                      </Menu>
-                    </Group>
-                  ) : (
-                    <Button size="xs" variant="outline" onClick={handleCopyDefaultLink}>
-                      {copyLinkLabel}
+                  <Group aria-label="Copy selected endpoint">
+                    <Button
+                      size="xs"
+                      variant="outline"
+                      className="max-w-56"
+                      title={`Copy pairing URL for: ${defaultEndpointCopyLabel}`}
+                      onClick={handleCopyDefaultLink}
+                    >
+                      <span className="truncate">
+                        Copy pairing URL for: {defaultEndpointCopyLabel}
+                      </span>
                     </Button>
-                  )
-                ) : null}
+                    <GroupSeparator />
+                    <Menu>
+                      <MenuTrigger
+                        render={
+                          <Button
+                            size="icon-xs"
+                            variant="outline"
+                            aria-label="Choose endpoint to copy"
+                          />
+                        }
+                      >
+                        <ChevronDownIcon className="size-3.5" />
+                      </MenuTrigger>
+                      <MenuPopup align="end" className="min-w-60">
+                        {renderGroupedCopyMenuItems()}
+                      </MenuPopup>
+                    </Menu>
+                  </Group>
+                ) : (
+                  <Button size="xs" variant="outline" onClick={handleCopyCode}>
+                    Copy code
+                  </Button>
+                )}
               </>
             ) : (
               <DialogTrigger render={<Button size="xs" variant="outline" />}>
@@ -813,12 +924,14 @@ const PairingLinkListRow = memo(function PairingLinkListRow({
 
 type ConnectedClientListRowProps = {
   clientSession: ServerClientSessionRecord;
+  presentation?: AccessSectionPresentation;
   revokingClientSessionId: string | null;
   onRevokeSession: (sessionId: ServerClientSessionRecord["sessionId"]) => void;
 };
 
 const ConnectedClientListRow = memo(function ConnectedClientListRow({
   clientSession,
+  presentation = "current",
   revokingClientSessionId,
   onRevokeSession,
 }: ConnectedClientListRowProps) {
@@ -847,7 +960,7 @@ const ConnectedClientListRow = memo(function ConnectedClientListRow({
       clientSession.subject);
 
   return (
-    <div className={ITEM_ROW_CLASSNAME}>
+    <div className={accessRowClassName(presentation)}>
       <div className={ITEM_ROW_INNER_CLASSNAME}>
         <div className="min-w-0 flex-1 space-y-1">
           <div className="flex min-h-5 items-center gap-1.5">
@@ -992,6 +1105,7 @@ type PairingClientsListProps = {
   endpointUrl: string | null | undefined;
   endpoints: ReadonlyArray<AdvertisedEndpoint>;
   defaultEndpointKey: string | null;
+  presentation?: AccessSectionPresentation;
   isLoading: boolean;
   pairingLinks: ReadonlyArray<ServerPairingLinkRecord>;
   clientSessions: ReadonlyArray<ServerClientSessionRecord>;
@@ -1005,6 +1119,7 @@ const PairingClientsList = memo(function PairingClientsList({
   endpointUrl,
   endpoints,
   defaultEndpointKey,
+  presentation = "current",
   isLoading,
   pairingLinks,
   clientSessions,
@@ -1022,6 +1137,7 @@ const PairingClientsList = memo(function PairingClientsList({
           endpointUrl={endpointUrl}
           endpoints={endpoints}
           defaultEndpointKey={defaultEndpointKey}
+          presentation={presentation}
           revokingPairingLinkId={revokingPairingLinkId}
           onRevoke={onRevokePairingLink}
         />
@@ -1031,13 +1147,14 @@ const PairingClientsList = memo(function PairingClientsList({
         <ConnectedClientListRow
           key={clientSession.sessionId}
           clientSession={clientSession}
+          presentation={presentation}
           revokingClientSessionId={revokingClientSessionId}
           onRevokeSession={onRevokeClientSession}
         />
       ))}
 
       {pairingLinks.length === 0 && clientSessions.length === 0 && !isLoading ? (
-        <div className={ITEM_ROW_CLASSNAME}>
+        <div className={accessRowClassName(presentation)}>
           <p className="text-xs text-muted-foreground/60">No pairing links or client sessions.</p>
         </div>
       ) : null}
@@ -1048,6 +1165,7 @@ const PairingClientsList = memo(function PairingClientsList({
 type AdvertisedEndpointListRowProps = {
   endpoint: AdvertisedEndpoint;
   isDefault: boolean;
+  presentation?: AccessSectionPresentation;
   onSetDefault: (endpoint: AdvertisedEndpoint) => void;
   onSetupTailscaleServe: (endpoint: AdvertisedEndpoint) => void;
   onDisableTailscaleServe: (endpoint: AdvertisedEndpoint) => void;
@@ -1057,6 +1175,7 @@ type AdvertisedEndpointListRowProps = {
 const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
   endpoint,
   isDefault,
+  presentation = "current",
   onSetDefault,
   onSetupTailscaleServe,
   onDisableTailscaleServe,
@@ -1067,8 +1186,12 @@ const AdvertisedEndpointListRow = memo(function AdvertisedEndpointListRow({
   const canDisableTailscaleServe =
     isTailscaleHttpsEndpoint(endpoint) && endpoint.status === "available";
   const shouldShowEndpointUrl = !needsTailscaleSetup;
+  const isEndpointRail = presentation === "endpoint-rail";
   return (
-    <div className={cn(ENDPOINT_ROW_CLASSNAME, !isAvailable && "bg-muted/24")}>
+    <div className={endpointRowClassName(presentation, isAvailable)}>
+      {isEndpointRail && isDefault ? (
+        <span className="absolute inset-y-2 left-0 w-1 rounded-r-full bg-primary" aria-hidden />
+      ) : null}
       <div className="flex min-h-6 min-w-0 flex-col gap-2 sm:-my-0.5 sm:flex-row sm:items-center">
         <div className="flex min-w-0 items-baseline gap-3">
           <h3 className="shrink-0 text-sm leading-5 font-medium text-foreground">
@@ -1410,6 +1533,7 @@ export function ConnectionsSettings() {
   const [removingSavedEnvironmentId, setRemovingSavedEnvironmentId] =
     useState<EnvironmentId | null>(null);
   const [isUpdatingDesktopServerExposure, setIsUpdatingDesktopServerExposure] = useState(false);
+  const [isDesktopServerExposureDialogOpen, setIsDesktopServerExposureDialogOpen] = useState(false);
   const [isUpdatingTailscaleServe, setIsUpdatingTailscaleServe] = useState(false);
   const [pendingTailscaleServeEndpoint, setPendingTailscaleServeEndpoint] =
     useState<AdvertisedEndpoint | null>(null);
@@ -1464,12 +1588,12 @@ export function ConnectionsSettings() {
           checked ? "network-accessible" : "local-only",
         );
         setDesktopServerExposureState(nextState);
-        setPendingDesktopServerExposureMode(null);
+        setIsDesktopServerExposureDialogOpen(false);
         setIsUpdatingDesktopServerExposure(false);
       } catch (error) {
         const message =
           error instanceof Error ? error.message : "Failed to update network exposure.";
-        setPendingDesktopServerExposureMode(null);
+        setIsDesktopServerExposureDialogOpen(false);
         setDesktopServerExposureError(message);
         toastManager.add(
           stackedThreadToast({
@@ -2216,6 +2340,147 @@ export function ConnectionsSettings() {
       </div>
     </div>
   );
+  const renderNetworkAccessToggle = () => (
+    <Switch
+      checked={desktopServerExposureState?.mode === "network-accessible"}
+      disabled={!desktopServerExposureState || isUpdatingDesktopServerExposure}
+      onCheckedChange={(checked) => {
+        setPendingDesktopServerExposureMode(checked ? "network-accessible" : "local-only");
+        setIsDesktopServerExposureDialogOpen(true);
+      }}
+      aria-label="Enable network access"
+    />
+  );
+  const renderEndpointRows = (presentation: AccessSectionPresentation) =>
+    isAdvertisedEndpointListExpanded
+      ? visibleDesktopNetworkAdvertisedEndpoints.map((endpoint) => {
+          const endpointKey = endpointDefaultPreferenceKey(endpoint);
+          return (
+            <AdvertisedEndpointListRow
+              key={endpoint.id}
+              endpoint={endpoint}
+              isDefault={endpointKey === defaultDesktopAdvertisedEndpointKey}
+              presentation={presentation}
+              onSetDefault={handleSetDefaultAdvertisedEndpoint}
+              onSetupTailscaleServe={handleStartTailscaleServeSetup}
+              onDisableTailscaleServe={handleStartTailscaleServeDisable}
+              isUpdatingTailscaleServe={isUpdatingTailscaleServe}
+            />
+          );
+        })
+      : null;
+  const renderTailscaleRow = () => (
+    <SettingsRow
+      title="Tailscale HTTPS"
+      description={
+        tailscaleHttpsEndpoint
+          ? tailscaleHttpsEndpoint.status === "available"
+            ? tailscaleHttpsEndpoint.httpBaseUrl
+            : "Use Tailscale Serve to expose this backend through a MagicDNS HTTPS URL."
+          : "Start Tailscale to set up HTTPS access through MagicDNS."
+      }
+      control={
+        tailscaleHttpsEndpoint ? (
+          <Switch
+            checked={tailscaleHttpsEndpoint.status === "available"}
+            disabled={isUpdatingTailscaleServe}
+            onCheckedChange={(checked) => {
+              if (checked) {
+                handleStartTailscaleServeSetup(tailscaleHttpsEndpoint);
+                return;
+              }
+              handleStartTailscaleServeDisable(tailscaleHttpsEndpoint);
+            }}
+            aria-label="Enable Tailscale HTTPS"
+          />
+        ) : null
+      }
+    />
+  );
+  const renderAuthorizedClients = (presentation: AccessSectionPresentation) => (
+    <>
+      {desktopAccessManagementError ? (
+        <div className={accessRowClassName(presentation)}>
+          <p className="text-xs text-destructive">{desktopAccessManagementError}</p>
+        </div>
+      ) : null}
+      <PairingClientsList
+        endpointUrl={desktopServerExposureState?.endpointUrl}
+        endpoints={visibleDesktopAdvertisedEndpoints}
+        defaultEndpointKey={defaultDesktopAdvertisedEndpointKey}
+        presentation={presentation}
+        isLoading={isLoadingDesktopAccessManagement}
+        pairingLinks={visibleDesktopPairingLinks}
+        clientSessions={desktopClientSessions}
+        revokingPairingLinkId={revokingDesktopPairingLinkId}
+        revokingClientSessionId={revokingDesktopClientSessionId}
+        onRevokePairingLink={handleRevokeDesktopPairingLink}
+        onRevokeClientSession={handleRevokeDesktopClientSession}
+      />
+    </>
+  );
+  const renderNetworkAccessRow = () => (
+    <SettingsRow
+      title="Network access"
+      description={
+        isLocalBackendNetworkAccessible ? (
+          <NetworkAccessDescription
+            endpoint={defaultDesktopNetworkAdvertisedEndpoint}
+            hiddenEndpointCount={Math.max(visibleDesktopNetworkAdvertisedEndpoints.length - 1, 0)}
+            expanded={isAdvertisedEndpointListExpanded}
+            onToggleExpanded={() => setIsAdvertisedEndpointListExpanded((expanded) => !expanded)}
+            fallback={
+              desktopServerExposureState?.endpointUrl
+                ? `Reachable at ${desktopServerExposureState.endpointUrl}`
+                : desktopServerExposureState?.advertisedHost
+                  ? `Exposed on all interfaces. Pairing links use ${desktopServerExposureState.advertisedHost}.`
+                  : "Exposed on all interfaces."
+            }
+          />
+        ) : desktopServerExposureState ? (
+          "Limited to this machine."
+        ) : (
+          "Loading…"
+        )
+      }
+      status={
+        desktopServerExposureError ? (
+          <span className="block text-destructive">{desktopServerExposureError}</span>
+        ) : null
+      }
+      control={renderNetworkAccessToggle()}
+    />
+  );
+  const renderDisabledNetworkAccessRow = () => (
+    <SettingsRow
+      title="Network access"
+      description={
+        currentAuthPolicy === "remote-reachable"
+          ? "This backend is already configured for remote access. Network exposure changes must be made where the server is launched."
+          : "This backend is only reachable on this machine. Restart it with a non-loopback host to enable remote pairing."
+      }
+      control={
+        <Tooltip>
+          <TooltipTrigger
+            render={
+              <span className="inline-flex">
+                <Switch
+                  checked={isLocalBackendNetworkAccessible}
+                  disabled
+                  aria-label="Enable network access"
+                />
+              </span>
+            }
+          />
+          <TooltipPopup side="top">
+            Network exposure changes restart the backend and must be controlled where the server
+            process is launched.
+          </TooltipPopup>
+        </Tooltip>
+      }
+    />
+  );
+
   return (
     <SettingsPageContainer>
       {canManageLocalBackend ? (
@@ -2223,287 +2488,12 @@ export function ConnectionsSettings() {
           <SettingsSection title="Manage local backend">
             {desktopBridge ? (
               <>
-                <SettingsRow
-                  title="Network access"
-                  description={
-                    isLocalBackendNetworkAccessible ? (
-                      <NetworkAccessDescription
-                        endpoint={defaultDesktopNetworkAdvertisedEndpoint}
-                        hiddenEndpointCount={Math.max(
-                          visibleDesktopNetworkAdvertisedEndpoints.length - 1,
-                          0,
-                        )}
-                        expanded={isAdvertisedEndpointListExpanded}
-                        onToggleExpanded={() =>
-                          setIsAdvertisedEndpointListExpanded((expanded) => !expanded)
-                        }
-                        fallback={
-                          desktopServerExposureState?.endpointUrl
-                            ? `Reachable at ${desktopServerExposureState.endpointUrl}`
-                            : desktopServerExposureState?.advertisedHost
-                              ? `Exposed on all interfaces. Pairing links use ${desktopServerExposureState.advertisedHost}.`
-                              : "Exposed on all interfaces."
-                        }
-                      />
-                    ) : desktopServerExposureState ? (
-                      "Limited to this machine."
-                    ) : (
-                      "Loading…"
-                    )
-                  }
-                  status={
-                    desktopServerExposureError ? (
-                      <span className="block text-destructive">{desktopServerExposureError}</span>
-                    ) : null
-                  }
-                  control={
-                    <AlertDialog
-                      open={pendingDesktopServerExposureMode !== null}
-                      onOpenChange={(open) => {
-                        if (isUpdatingDesktopServerExposure) return;
-                        if (!open) setPendingDesktopServerExposureMode(null);
-                      }}
-                    >
-                      <Switch
-                        checked={desktopServerExposureState?.mode === "network-accessible"}
-                        disabled={!desktopServerExposureState || isUpdatingDesktopServerExposure}
-                        onCheckedChange={(checked) => {
-                          setPendingDesktopServerExposureMode(
-                            checked ? "network-accessible" : "local-only",
-                          );
-                        }}
-                        aria-label="Enable network access"
-                      />
-                      <AlertDialogPopup>
-                        <AlertDialogHeader>
-                          <AlertDialogTitle>
-                            {pendingDesktopServerExposureMode === "network-accessible"
-                              ? "Enable network access?"
-                              : "Disable network access?"}
-                          </AlertDialogTitle>
-                          <AlertDialogDescription>
-                            {pendingDesktopServerExposureMode === "network-accessible"
-                              ? "T3 Code will restart to expose this environment over the network."
-                              : "T3 Code will restart and limit this environment back to this machine."}
-                          </AlertDialogDescription>
-                        </AlertDialogHeader>
-                        <AlertDialogFooter>
-                          <AlertDialogClose
-                            disabled={isUpdatingDesktopServerExposure}
-                            render={
-                              <Button
-                                variant="outline"
-                                disabled={isUpdatingDesktopServerExposure}
-                              />
-                            }
-                          >
-                            Cancel
-                          </AlertDialogClose>
-                          <Button
-                            variant={
-                              pendingDesktopServerExposureMode === "local-only"
-                                ? "destructive"
-                                : "default"
-                            }
-                            onClick={handleConfirmDesktopServerExposureChange}
-                            disabled={
-                              pendingDesktopServerExposureMode === null ||
-                              isUpdatingDesktopServerExposure
-                            }
-                          >
-                            {isUpdatingDesktopServerExposure ? (
-                              <>
-                                <Spinner className="size-3.5" />
-                                Restarting…
-                              </>
-                            ) : pendingDesktopServerExposureMode === "network-accessible" ? (
-                              "Restart and enable"
-                            ) : (
-                              "Restart and disable"
-                            )}
-                          </Button>
-                        </AlertDialogFooter>
-                      </AlertDialogPopup>
-                    </AlertDialog>
-                  }
-                />
-                {isAdvertisedEndpointListExpanded
-                  ? visibleDesktopNetworkAdvertisedEndpoints.map((endpoint) => {
-                      const endpointKey = endpointDefaultPreferenceKey(endpoint);
-                      return (
-                        <AdvertisedEndpointListRow
-                          key={endpoint.id}
-                          endpoint={endpoint}
-                          isDefault={endpointKey === defaultDesktopAdvertisedEndpointKey}
-                          onSetDefault={handleSetDefaultAdvertisedEndpoint}
-                          onSetupTailscaleServe={handleStartTailscaleServeSetup}
-                          onDisableTailscaleServe={handleStartTailscaleServeDisable}
-                          isUpdatingTailscaleServe={isUpdatingTailscaleServe}
-                        />
-                      );
-                    })
-                  : null}
-                <SettingsRow
-                  title="Tailscale HTTPS"
-                  description={
-                    tailscaleHttpsEndpoint
-                      ? tailscaleHttpsEndpoint.status === "available"
-                        ? tailscaleHttpsEndpoint.httpBaseUrl
-                        : "Use Tailscale Serve to expose this backend through a MagicDNS HTTPS URL."
-                      : "Start Tailscale to set up HTTPS access through MagicDNS."
-                  }
-                  control={
-                    tailscaleHttpsEndpoint ? (
-                      <Switch
-                        checked={tailscaleHttpsEndpoint.status === "available"}
-                        disabled={isUpdatingTailscaleServe}
-                        onCheckedChange={(checked) => {
-                          if (checked) {
-                            handleStartTailscaleServeSetup(tailscaleHttpsEndpoint);
-                            return;
-                          }
-                          handleStartTailscaleServeDisable(tailscaleHttpsEndpoint);
-                        }}
-                        aria-label="Enable Tailscale HTTPS"
-                      />
-                    ) : null
-                  }
-                />
-                <AlertDialog
-                  open={disableTailscaleServeDialogOpen}
-                  onOpenChange={(open) => {
-                    if (isUpdatingTailscaleServe) return;
-                    setDisableTailscaleServeDialogOpen(open);
-                  }}
-                >
-                  <AlertDialogPopup>
-                    <AlertDialogHeader>
-                      <AlertDialogTitle>Disable Tailscale HTTPS?</AlertDialogTitle>
-                      <AlertDialogDescription>
-                        T3 Code will restart the local backend without Tailscale Serve.
-                      </AlertDialogDescription>
-                    </AlertDialogHeader>
-                    <AlertDialogFooter>
-                      <AlertDialogClose
-                        disabled={isUpdatingTailscaleServe}
-                        render={<Button variant="outline" disabled={isUpdatingTailscaleServe} />}
-                      >
-                        Cancel
-                      </AlertDialogClose>
-                      <Button
-                        variant="destructive"
-                        onClick={() => void handleConfirmTailscaleServeDisable()}
-                        disabled={isUpdatingTailscaleServe}
-                      >
-                        {isUpdatingTailscaleServe ? (
-                          <>
-                            <Spinner className="size-3.5" />
-                            Restarting…
-                          </>
-                        ) : (
-                          "Restart and disable"
-                        )}
-                      </Button>
-                    </AlertDialogFooter>
-                  </AlertDialogPopup>
-                </AlertDialog>
-                <Dialog
-                  open={pendingTailscaleServeEndpoint !== null}
-                  onOpenChange={(open) => {
-                    if (isUpdatingTailscaleServe) return;
-                    if (!open) setPendingTailscaleServeEndpoint(null);
-                  }}
-                >
-                  <DialogPopup className="max-w-md">
-                    <DialogHeader>
-                      <DialogTitle>Set up Tailscale HTTPS?</DialogTitle>
-                      <DialogDescription>
-                        T3 Code will restart the local backend with Tailscale Serve enabled and ask
-                        Tailscale to proxy HTTPS traffic to this backend.
-                      </DialogDescription>
-                    </DialogHeader>
-                    <DialogPanel className="space-y-4">
-                      <label className="block">
-                        <span className="text-sm font-medium text-foreground">HTTPS port</span>
-                        <Input
-                          className="mt-2"
-                          type="number"
-                          inputMode="numeric"
-                          min={1}
-                          max={65_535}
-                          step={1}
-                          value={tailscaleServePortInput}
-                          onChange={(event) => setTailscaleServePortInput(event.target.value)}
-                          disabled={isUpdatingTailscaleServe}
-                        />
-                      </label>
-                      {!isTailscaleServePortValid ? (
-                        <p className="mt-2 text-xs text-destructive">
-                          Enter a port from 1 to 65535.
-                        </p>
-                      ) : null}
-                      <div className="rounded-md border border-border/70 bg-muted/20 px-3 py-2">
-                        <p className="text-xs font-medium text-muted-foreground">HTTPS endpoint</p>
-                        <p
-                          className="mt-1 truncate text-sm text-foreground"
-                          title={pendingTailscaleServeBaseUrl ?? undefined}
-                        >
-                          {pendingTailscaleServeBaseUrl ?? "Pending MagicDNS endpoint"}
-                        </p>
-                      </div>
-                    </DialogPanel>
-                    <DialogFooter>
-                      <DialogClose
-                        disabled={isUpdatingTailscaleServe}
-                        render={<Button variant="outline" disabled={isUpdatingTailscaleServe} />}
-                      >
-                        Cancel
-                      </DialogClose>
-                      <Button
-                        onClick={() => void handleConfirmTailscaleServeSetup()}
-                        disabled={isUpdatingTailscaleServe || !isTailscaleServePortValid}
-                      >
-                        {isUpdatingTailscaleServe ? (
-                          <>
-                            <Spinner className="size-3.5" />
-                            Restarting…
-                          </>
-                        ) : (
-                          "Enable"
-                        )}
-                      </Button>
-                    </DialogFooter>
-                  </DialogPopup>
-                </Dialog>
+                {renderNetworkAccessRow()}
+                {renderEndpointRows("endpoint-rail")}
+                {renderTailscaleRow()}
               </>
             ) : (
-              <SettingsRow
-                title="Network access"
-                description={
-                  currentAuthPolicy === "remote-reachable"
-                    ? "This backend is already configured for remote access. Network exposure changes must be made where the server is launched."
-                    : "This backend is only reachable on this machine. Restart it with a non-loopback host to enable remote pairing."
-                }
-                control={
-                  <Tooltip>
-                    <TooltipTrigger
-                      render={
-                        <span className="inline-flex">
-                          <Switch
-                            checked={isLocalBackendNetworkAccessible}
-                            disabled
-                            aria-label="Enable network access"
-                          />
-                        </span>
-                      }
-                    />
-                    <TooltipPopup side="top">
-                      Network exposure changes restart the backend and must be controlled where the
-                      server process is launched.
-                    </TooltipPopup>
-                  </Tooltip>
-                }
-              />
+              renderDisabledNetworkAccessRow()
             )}
           </SettingsSection>
 
@@ -2518,25 +2508,166 @@ export function ConnectionsSettings() {
                 />
               }
             >
-              {desktopAccessManagementError ? (
-                <div className={ITEM_ROW_CLASSNAME}>
-                  <p className="text-xs text-destructive">{desktopAccessManagementError}</p>
-                </div>
-              ) : null}
-              <PairingClientsList
-                endpointUrl={desktopServerExposureState?.endpointUrl}
-                endpoints={visibleDesktopAdvertisedEndpoints}
-                defaultEndpointKey={defaultDesktopAdvertisedEndpointKey}
-                isLoading={isLoadingDesktopAccessManagement}
-                pairingLinks={visibleDesktopPairingLinks}
-                clientSessions={desktopClientSessions}
-                revokingPairingLinkId={revokingDesktopPairingLinkId}
-                revokingClientSessionId={revokingDesktopClientSessionId}
-                onRevokePairingLink={handleRevokeDesktopPairingLink}
-                onRevokeClientSession={handleRevokeDesktopClientSession}
-              />
+              {renderAuthorizedClients("current")}
             </SettingsSection>
           ) : null}
+          <AlertDialog
+            open={isDesktopServerExposureDialogOpen}
+            onOpenChange={(open) => {
+              if (isUpdatingDesktopServerExposure) return;
+              setIsDesktopServerExposureDialogOpen(open);
+            }}
+            onOpenChangeComplete={(open) => {
+              if (!open) setPendingDesktopServerExposureMode(null);
+            }}
+          >
+            <AlertDialogPopup>
+              <AlertDialogHeader>
+                <AlertDialogTitle>
+                  {pendingDesktopServerExposureMode === "network-accessible"
+                    ? "Enable network access?"
+                    : "Disable network access?"}
+                </AlertDialogTitle>
+                <AlertDialogDescription>
+                  {pendingDesktopServerExposureMode === "network-accessible"
+                    ? "T3 Code will restart to expose this environment over the network."
+                    : "T3 Code will restart and limit this environment back to this machine."}
+                </AlertDialogDescription>
+              </AlertDialogHeader>
+              <AlertDialogFooter>
+                <AlertDialogClose
+                  disabled={isUpdatingDesktopServerExposure}
+                  render={<Button variant="outline" disabled={isUpdatingDesktopServerExposure} />}
+                >
+                  Cancel
+                </AlertDialogClose>
+                <Button
+                  variant={
+                    pendingDesktopServerExposureMode === "local-only" ? "destructive" : "default"
+                  }
+                  onClick={handleConfirmDesktopServerExposureChange}
+                  disabled={
+                    pendingDesktopServerExposureMode === null || isUpdatingDesktopServerExposure
+                  }
+                >
+                  {isUpdatingDesktopServerExposure ? (
+                    <>
+                      <Spinner className="size-3.5" />
+                      Restarting…
+                    </>
+                  ) : pendingDesktopServerExposureMode === "network-accessible" ? (
+                    "Restart and enable"
+                  ) : (
+                    "Restart and disable"
+                  )}
+                </Button>
+              </AlertDialogFooter>
+            </AlertDialogPopup>
+          </AlertDialog>
+          <AlertDialog
+            open={disableTailscaleServeDialogOpen}
+            onOpenChange={(open) => {
+              if (isUpdatingTailscaleServe) return;
+              setDisableTailscaleServeDialogOpen(open);
+            }}
+          >
+            <AlertDialogPopup>
+              <AlertDialogHeader>
+                <AlertDialogTitle>Disable Tailscale HTTPS?</AlertDialogTitle>
+                <AlertDialogDescription>
+                  T3 Code will restart the local backend without Tailscale Serve.
+                </AlertDialogDescription>
+              </AlertDialogHeader>
+              <AlertDialogFooter>
+                <AlertDialogClose
+                  disabled={isUpdatingTailscaleServe}
+                  render={<Button variant="outline" disabled={isUpdatingTailscaleServe} />}
+                >
+                  Cancel
+                </AlertDialogClose>
+                <Button
+                  variant="destructive"
+                  onClick={() => void handleConfirmTailscaleServeDisable()}
+                  disabled={isUpdatingTailscaleServe}
+                >
+                  {isUpdatingTailscaleServe ? (
+                    <>
+                      <Spinner className="size-3.5" />
+                      Restarting…
+                    </>
+                  ) : (
+                    "Restart and disable"
+                  )}
+                </Button>
+              </AlertDialogFooter>
+            </AlertDialogPopup>
+          </AlertDialog>
+          <Dialog
+            open={pendingTailscaleServeEndpoint !== null}
+            onOpenChange={(open) => {
+              if (isUpdatingTailscaleServe) return;
+              if (!open) setPendingTailscaleServeEndpoint(null);
+            }}
+          >
+            <DialogPopup className="max-w-md">
+              <DialogHeader>
+                <DialogTitle>Set up Tailscale HTTPS?</DialogTitle>
+                <DialogDescription>
+                  T3 Code will restart the local backend with Tailscale Serve enabled and ask
+                  Tailscale to proxy HTTPS traffic to this backend.
+                </DialogDescription>
+              </DialogHeader>
+              <DialogPanel className="space-y-4">
+                <label className="block">
+                  <span className="text-sm font-medium text-foreground">HTTPS port</span>
+                  <Input
+                    className="mt-2"
+                    type="number"
+                    inputMode="numeric"
+                    min={1}
+                    max={65_535}
+                    step={1}
+                    value={tailscaleServePortInput}
+                    onChange={(event) => setTailscaleServePortInput(event.target.value)}
+                    disabled={isUpdatingTailscaleServe}
+                  />
+                </label>
+                {!isTailscaleServePortValid ? (
+                  <p className="mt-2 text-xs text-destructive">Enter a port from 1 to 65535.</p>
+                ) : null}
+                <div className="rounded-md border border-border/70 bg-muted/20 px-3 py-2">
+                  <p className="text-xs font-medium text-muted-foreground">HTTPS endpoint</p>
+                  <p
+                    className="mt-1 truncate text-sm text-foreground"
+                    title={pendingTailscaleServeBaseUrl ?? undefined}
+                  >
+                    {pendingTailscaleServeBaseUrl ?? "Pending MagicDNS endpoint"}
+                  </p>
+                </div>
+              </DialogPanel>
+              <DialogFooter>
+                <DialogClose
+                  disabled={isUpdatingTailscaleServe}
+                  render={<Button variant="outline" disabled={isUpdatingTailscaleServe} />}
+                >
+                  Cancel
+                </DialogClose>
+                <Button
+                  onClick={() => void handleConfirmTailscaleServeSetup()}
+                  disabled={isUpdatingTailscaleServe || !isTailscaleServePortValid}
+                >
+                  {isUpdatingTailscaleServe ? (
+                    <>
+                      <Spinner className="size-3.5" />
+                      Restarting…
+                    </>
+                  ) : (
+                    "Enable"
+                  )}
+                </Button>
+              </DialogFooter>
+            </DialogPopup>
+          </Dialog>
         </>
       ) : (
         <SettingsSection title="Local backend access">
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 4a873f33341..c79fa209b12 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -1399,6 +1399,7 @@ export async function removeSavedEnvironment(environmentId: EnvironmentId): Prom
   await disconnectSavedEnvironment(environmentId);
   useSavedEnvironmentRegistryStore.getState().remove(environmentId);
   useSavedEnvironmentRuntimeStore.getState().clear(environmentId);
+  useStore.getState().removeEnvironmentState(environmentId);
   await removeSavedEnvironmentBearerToken(environmentId);
 }
 
diff --git a/apps/web/src/store.test.ts b/apps/web/src/store.test.ts
index 99ddf4ca091..59ebd0cea0c 100644
--- a/apps/web/src/store.test.ts
+++ b/apps/web/src/store.test.ts
@@ -16,6 +16,7 @@ import { describe, expect, it } from "vitest";
 import {
   applyOrchestrationEvent,
   applyOrchestrationEvents,
+  removeEnvironmentState,
   selectEnvironmentState,
   selectProjectsAcrossEnvironments,
   selectThreadByRef,
@@ -246,6 +247,39 @@ function makeEvent<T extends OrchestrationEvent["type"]>(
   } as Extract<OrchestrationEvent, { type: T }>;
 }
 
+describe("environment state removal", () => {
+  it("drops local state for removed environments", () => {
+    const removedThread = makeThread({
+      environmentId: remoteEnvironmentId,
+      id: ThreadId.make("thread-removed"),
+    });
+    const keptThread = makeThread({ id: ThreadId.make("thread-kept") });
+    const removedState = makeState(removedThread).environmentStateById[remoteEnvironmentId]!;
+    const keptState = makeState(keptThread).environmentStateById[localEnvironmentId]!;
+    const state: AppState = {
+      activeEnvironmentId: remoteEnvironmentId,
+      environmentStateById: {
+        [remoteEnvironmentId]: removedState,
+        [localEnvironmentId]: keptState,
+      },
+    };
+
+    const next = removeEnvironmentState(state, remoteEnvironmentId);
+
+    expect(next.activeEnvironmentId).toBeNull();
+    expect(next.environmentStateById[remoteEnvironmentId]).toBeUndefined();
+    expect(next.environmentStateById[localEnvironmentId]).toBe(keptState);
+  });
+
+  it("preserves active environment when removing a different environment", () => {
+    const state = makeState(makeThread());
+
+    const next = removeEnvironmentState(state, remoteEnvironmentId);
+
+    expect(next).toBe(state);
+  });
+});
+
 describe("thread selection memoization", () => {
   it("returns stable thread references for repeated reads of the same state", () => {
     const thread = makeThread({
diff --git a/apps/web/src/store.ts b/apps/web/src/store.ts
index e3012a8c8b7..921054df34f 100644
--- a/apps/web/src/store.ts
+++ b/apps/web/src/store.ts
@@ -1905,6 +1905,20 @@ export function setActiveEnvironmentId(state: AppState, environmentId: Environme
   };
 }
 
+export function removeEnvironmentState(state: AppState, environmentId: EnvironmentId): AppState {
+  if (!state.environmentStateById[environmentId] && state.activeEnvironmentId !== environmentId) {
+    return state;
+  }
+
+  const { [environmentId]: _removed, ...environmentStateById } = state.environmentStateById;
+  return {
+    ...state,
+    activeEnvironmentId:
+      state.activeEnvironmentId === environmentId ? null : state.activeEnvironmentId,
+    environmentStateById,
+  };
+}
+
 export function setThreadBranch(
   state: AppState,
   threadRef: ScopedThreadRef,
@@ -1930,6 +1944,7 @@ export function setThreadBranch(
 
 interface AppStore extends AppState {
   setActiveEnvironmentId: (environmentId: EnvironmentId) => void;
+  removeEnvironmentState: (environmentId: EnvironmentId) => void;
   syncServerShellSnapshot: (
     snapshot: OrchestrationShellSnapshot,
     environmentId: EnvironmentId,
@@ -1953,6 +1968,8 @@ export const useStore = create<AppStore>((set) => ({
   ...initialState,
   setActiveEnvironmentId: (environmentId) =>
     set((state) => setActiveEnvironmentId(state, environmentId)),
+  removeEnvironmentState: (environmentId) =>
+    set((state) => removeEnvironmentState(state, environmentId)),
   syncServerShellSnapshot: (snapshot, environmentId) =>
     set((state) => syncServerShellSnapshot(state, snapshot, environmentId)),
   syncServerThreadDetail: (thread, environmentId) =>
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 28f501679b8..0ca49907571 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -1,7 +1,8 @@
 import { assert, describe, it } from "@effect/vitest";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import { NetService } from "@t3tools/shared/Net";
-import { Effect, Layer, Sink, Stream } from "effect";
+import { Duration, Effect, Fiber, Layer, Result, Sink, Stream } from "effect";
+import { TestClock } from "effect/testing";
 import { HttpClient, HttpClientResponse } from "effect/unstable/http";
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 
@@ -14,6 +15,7 @@ import {
   issueRemotePairingToken,
   REMOTE_PICK_PORT_SCRIPT,
   SshEnvironmentManager,
+  waitForHttpReady,
 } from "./tunnel.ts";
 
 const makeSuccessfulProcess = (stdout: string) => {
@@ -63,6 +65,8 @@ const testHttpClient = HttpClient.make((request) =>
   Effect.succeed(HttpClientResponse.fromWeb(request, new Response("", { status: 200 }))),
 );
 
+const hangingHttpClient = HttpClient.make(() => Effect.never);
+
 const testNetService = NetService.of({
   canListenOnHost: () => Effect.succeed(true),
   isPortAvailableOnLoopback: () => Effect.succeed(true),
@@ -111,7 +115,9 @@ describe("ssh tunnel scripts", () => {
     );
     assert.include(buildRemoteLaunchScript(), "RUNNER_CHANGED=1");
     assert.include(buildRemoteLaunchScript(), 'kill "$REMOTE_PID" 2>/dev/null || true');
+    assert.include(buildRemoteLaunchScript(), "wait_ready");
     assert.include(buildRemoteLaunchScript(), '"$RUNNER_FILE" serve --host 127.0.0.1');
+    assert.include(buildRemoteLaunchScript(), "Remote T3 server did not become ready");
     assert.include(buildRemoteLaunchScript({ packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
       buildRemotePairingScript(target),
@@ -126,6 +132,34 @@ describe("ssh tunnel scripts", () => {
     assert.include(REMOTE_PICK_PORT_SCRIPT, 'const filePath = process.argv[2] ?? "";');
   });
 
+  it.effect("bounds each HTTP readiness probe so retries cannot hang on one request", () =>
+    Effect.gen(function* () {
+      const fiber = yield* Effect.forkChild(
+        Effect.result(
+          waitForHttpReady({
+            baseUrl: "http://127.0.0.1:41773/",
+            timeoutMs: 1_000,
+            intervalMs: 100,
+            probeTimeoutMs: 250,
+          }),
+        ),
+      );
+      yield* Effect.yieldNow;
+      yield* TestClock.adjust(Duration.millis(1_000));
+
+      const result = yield* Fiber.join(fiber);
+
+      assert.isTrue(Result.isFailure(result));
+      if (Result.isFailure(result)) {
+        assert.include(result.failure.message, "Timed out waiting 1000ms");
+      }
+    }).pipe(
+      Effect.provide(
+        Layer.merge(TestClock.layer(), Layer.succeed(HttpClient.HttpClient, hangingHttpClient)),
+      ),
+    ),
+  );
+
   it.effect("accepts pretty-printed pairing JSON from the remote CLI", () => {
     const target = {
       alias: "devbox",
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index a61ed2b47d3..aef361d41a6 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -52,7 +52,10 @@ import {
 export const DEFAULT_REMOTE_PORT = 3773;
 const REMOTE_PORT_SCAN_WINDOW = 200;
 const SSH_READY_TIMEOUT_MS = 20_000;
+const SSH_READY_PROBE_TIMEOUT_MS = 1_000;
 const TUNNEL_SHUTDOWN_TIMEOUT_MS = 2_000;
+const REMOTE_READY_TIMEOUT_MS = 15_000;
+const REMOTE_REUSE_READY_TIMEOUT_MS = 2_000;
 
 export interface RemoteT3RunnerOptions {
   readonly packageSpec?: string;
@@ -187,6 +190,36 @@ function applyScriptPlaceholders(
   return result;
 }
 
+function describeReadinessCause(cause: unknown): unknown {
+  if (cause instanceof SshReadinessError) {
+    return {
+      _tag: cause._tag,
+      message: cause.message,
+      ...(cause.cause === undefined ? {} : { cause: describeReadinessCause(cause.cause) }),
+    };
+  }
+  if (cause instanceof Error) {
+    return {
+      name: cause.name,
+      message: cause.message,
+      ...(cause.cause === undefined ? {} : { cause: describeReadinessCause(cause.cause) }),
+    };
+  }
+  if (typeof cause !== "object" || cause === null) {
+    return cause;
+  }
+
+  const record = cause as Readonly<Record<string, unknown>>;
+  return {
+    ...(typeof record._tag === "string" ? { _tag: record._tag } : {}),
+    ...(typeof record.message === "string" ? { message: record.message } : {}),
+    ...(typeof record.reason === "object" && record.reason !== null
+      ? { reason: describeReadinessCause(record.reason) }
+      : {}),
+    ...(record.cause === undefined ? {} : { cause: describeReadinessCause(record.cause) }),
+  };
+}
+
 export const REMOTE_PICK_PORT_SCRIPT = `const fs = require("node:fs");
 const net = require("node:net");
 const filePath = process.argv[2] ?? "";
@@ -220,6 +253,54 @@ function tryPort(port) {
 })().catch(() => process.exit(1));
 `;
 
+export const REMOTE_WAIT_READY_SCRIPT = `const http = require("node:http");
+const port = Number.parseInt(process.argv[2] ?? "", 10);
+const timeoutMs = Number.parseInt(process.argv[3] ?? "", 10);
+const probeTimeoutMs = Number.parseInt(process.argv[4] ?? "", 10);
+if (!Number.isInteger(port) || !Number.isInteger(timeoutMs) || !Number.isInteger(probeTimeoutMs)) {
+  process.exit(1);
+}
+const deadline = Date.now() + timeoutMs;
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function probe() {
+  return new Promise((resolve) => {
+    const request = http.get(
+      {
+        hostname: "127.0.0.1",
+        port,
+        path: "/",
+        timeout: probeTimeoutMs,
+      },
+      (response) => {
+        response.resume();
+        response.once("end", () => {
+          resolve(response.statusCode >= 200 && response.statusCode < 300);
+        });
+      },
+    );
+    request.once("timeout", () => {
+      request.destroy();
+      resolve(false);
+    });
+    request.once("error", () => resolve(false));
+  });
+}
+
+(async () => {
+  while (Date.now() < deadline) {
+    if (await probe()) {
+      process.exit(0);
+    }
+    await sleep(100);
+  }
+  process.exit(1);
+})().catch(() => process.exit(1));
+`;
+
 export const REMOTE_RUNNER_SCRIPT = `#!/bin/sh
 set -eu
 T3_NODE_SCRIPT_PATH=@@T3_NODE_SCRIPT_PATH@@
@@ -267,11 +348,30 @@ pick_port() {
 @@T3_PICK_PORT_SCRIPT@@
 NODE
 }
+wait_ready() {
+  node - "$REMOTE_PORT" "$1" "@@T3_READY_PROBE_TIMEOUT_MS@@" <<'NODE'
+@@T3_WAIT_READY_SCRIPT@@
+NODE
+}
+wait_for_pid_exit() {
+  PID_TO_WAIT="$1"
+  WAIT_COUNT=0
+  while kill -0 "$PID_TO_WAIT" 2>/dev/null && [ "$WAIT_COUNT" -lt 20 ]; do
+    WAIT_COUNT=$((WAIT_COUNT + 1))
+    sleep 0.1
+  done
+}
 REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
 REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
 if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
   if [ "$RUNNER_CHANGED" -eq 1 ]; then
     kill "$REMOTE_PID" 2>/dev/null || true
+    wait_for_pid_exit "$REMOTE_PID"
+    REMOTE_PID=""
+    REMOTE_PORT=""
+  elif ! wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
+    kill "$REMOTE_PID" 2>/dev/null || true
+    wait_for_pid_exit "$REMOTE_PID"
     REMOTE_PID=""
     REMOTE_PORT=""
   fi
@@ -289,6 +389,14 @@ if [ -z "$REMOTE_PID" ] || [ -z "$REMOTE_PORT" ]; then
   REMOTE_PID="$!"
   printf '%s\\n' "$REMOTE_PID" >"$PID_FILE"
   printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+  if ! wait_ready "@@T3_READY_TIMEOUT_MS@@"; then
+    printf 'Remote T3 server did not become ready on 127.0.0.1:%s.\\n' "$REMOTE_PORT" >&2
+    tail -n 80 "$LOG_FILE" >&2 2>/dev/null || true
+    kill "$REMOTE_PID" 2>/dev/null || true
+    wait_for_pid_exit "$REMOTE_PID"
+    rm -f "$PID_FILE" "$PORT_FILE"
+    exit 1
+  fi
 fi
 printf '{"remotePort":%s}\\n' "$REMOTE_PORT"
 `;
@@ -312,6 +420,11 @@ PORT_FILE="$STATE_DIR/port"
 REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
 if [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
   kill "$REMOTE_PID" 2>/dev/null || true
+  WAIT_COUNT=0
+  while kill -0 "$REMOTE_PID" 2>/dev/null && [ "$WAIT_COUNT" -lt 20 ]; do
+    WAIT_COUNT=$((WAIT_COUNT + 1))
+    sleep 0.1
+  done
 fi
 rm -f "$PID_FILE" "$PORT_FILE"
 printf '{"stopped":true}\\n'
@@ -340,8 +453,12 @@ export function buildRemoteLaunchScript(input?: RemoteT3RunnerOptions): string {
   return applyScriptPlaceholders(REMOTE_LAUNCH_SCRIPT, {
     T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
     T3_PICK_PORT_SCRIPT: stripTrailingNewlines(REMOTE_PICK_PORT_SCRIPT),
+    T3_WAIT_READY_SCRIPT: stripTrailingNewlines(REMOTE_WAIT_READY_SCRIPT),
     T3_DEFAULT_REMOTE_PORT: String(DEFAULT_REMOTE_PORT),
     T3_REMOTE_PORT_SCAN_WINDOW: String(REMOTE_PORT_SCAN_WINDOW),
+    T3_READY_TIMEOUT_MS: String(REMOTE_READY_TIMEOUT_MS),
+    T3_REUSE_READY_TIMEOUT_MS: String(REMOTE_REUSE_READY_TIMEOUT_MS),
+    T3_READY_PROBE_TIMEOUT_MS: String(SSH_READY_PROBE_TIMEOUT_MS),
   });
 }
 
@@ -429,7 +546,7 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
   SshCommandError | SshInvalidTargetError | SshPairingError,
   ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
 > {
-  yield* Effect.logInfo("ssh.remoteServer.pairingToken.start", {
+  yield* Effect.logDebug("ssh.remoteServer.pairingToken.start", {
     ...sshTargetLogFields(target),
     stateKey: remoteStateKey(target),
   });
@@ -462,7 +579,7 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
       stdout: result.stdout,
     });
   }
-  yield* Effect.logInfo("ssh.remoteServer.pairingToken.created", {
+  yield* Effect.logDebug("ssh.remoteServer.pairingToken.created", {
     ...sshTargetLogFields(target),
     stateKey: remoteStateKey(target),
   });
@@ -517,46 +634,79 @@ export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(functio
   readonly baseUrl: string;
   readonly timeoutMs?: number;
   readonly intervalMs?: number;
+  readonly probeTimeoutMs?: number;
   readonly path?: string;
 }): Effect.fn.Return<void, SshReadinessError, HttpClient.HttpClient> {
   const timeoutMs = input.timeoutMs ?? 30_000;
   const intervalMs = input.intervalMs ?? 100;
-  const maxRetries = Math.max(0, Math.ceil(timeoutMs / intervalMs));
+  const probeTimeoutMs = input.probeTimeoutMs ?? SSH_READY_PROBE_TIMEOUT_MS;
+  const retryPolicy = Schedule.spaced(Duration.millis(intervalMs)).pipe(
+    Schedule.take(Math.max(0, Math.ceil(timeoutMs / intervalMs))),
+  );
   const requestUrl = new URL(input.path ?? "/", input.baseUrl).toString();
   const client = yield* HttpClient.HttpClient;
   const lastProbeFailure = yield* Ref.make<unknown>(null);
   let attempt = 0;
 
-  yield* Effect.logInfo("ssh.tunnel.httpReady.start", {
+  yield* Effect.logDebug("ssh.tunnel.httpReady.start", {
     baseUrl: input.baseUrl,
     requestUrl,
     timeoutMs,
     intervalMs,
+    probeTimeoutMs,
   });
 
-  const probe = Effect.gen(function* () {
-    attempt += 1;
-    const response = yield* client.execute(HttpClientRequest.get(requestUrl)).pipe(
-      Effect.mapError(
-        (cause) =>
-          new SshReadinessError({
-            message: `Backend readiness probe failed at ${requestUrl}.`,
-            cause,
+  const readinessClient = client.pipe(
+    HttpClient.filterStatusOk,
+    HttpClient.transform((effect) =>
+      Effect.gen(function* () {
+        attempt += 1;
+        const responseOption = yield* effect.pipe(
+          Effect.timeoutOption(Duration.millis(probeTimeoutMs)),
+          Effect.mapError(
+            (cause) =>
+              new SshReadinessError({
+                message: `Backend readiness probe failed at ${requestUrl}.`,
+                cause,
+              }),
+          ),
+        );
+        return yield* Option.match(responseOption, {
+          onSome: Effect.succeed,
+          onNone: () =>
+            Effect.fail(
+              new SshReadinessError({
+                message: `Backend readiness probe exceeded ${probeTimeoutMs}ms at ${requestUrl}.`,
+                cause: {
+                  kind: "probe-timeout",
+                  attempt,
+                  probeTimeoutMs,
+                },
+              }),
+            ),
+        });
+      }).pipe(
+        Effect.mapError((cause) =>
+          cause instanceof SshReadinessError
+            ? cause
+            : new SshReadinessError({
+                message: `Backend readiness probe failed at ${requestUrl}.`,
+                cause,
+              }),
+        ),
+        Effect.tapError((cause) =>
+          Ref.set(lastProbeFailure, {
+            attempt,
+            cause: describeReadinessCause(cause),
           }),
+        ),
       ),
-    );
-    if (response.status >= 200 && response.status < 300) {
-      return;
-    }
-    const text = yield* response.text.pipe(Effect.catch(() => Effect.succeed("")));
-    return yield* new SshReadinessError({
-      message: `Backend readiness probe returned HTTP ${response.status} at ${requestUrl}.`,
-      cause: {
-        status: response.status,
-        body: text.slice(0, 1_000),
-      },
-    });
-  }).pipe(
+    ),
+    HttpClient.tap((response) => response.text.pipe(Effect.ignore)),
+    HttpClient.retry(retryPolicy),
+  );
+
+  const result = yield* readinessClient.execute(HttpClientRequest.get(requestUrl)).pipe(
     Effect.mapError((cause) =>
       cause instanceof SshReadinessError
         ? cause
@@ -565,25 +715,12 @@ export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(functio
             cause,
           }),
     ),
-    Effect.tapError((cause) =>
-      Ref.set(lastProbeFailure, {
-        attempt,
-        cause,
-      }),
-    ),
-  );
-
-  const result = yield* probe.pipe(
-    Effect.retry({
-      schedule: Schedule.spaced(Duration.millis(intervalMs)),
-      times: maxRetries,
-    }),
     Effect.timeoutOption(Duration.millis(timeoutMs)),
   );
 
   return yield* Option.match(result, {
     onSome: () =>
-      Effect.logInfo("ssh.tunnel.httpReady.succeeded", {
+      Effect.logDebug("ssh.tunnel.httpReady.succeeded", {
         baseUrl: input.baseUrl,
         requestUrl,
         attempts: attempt,
@@ -596,6 +733,7 @@ export const waitForHttpReady = Effect.fn("ssh/tunnel.waitForHttpReady")(functio
           requestUrl,
           timeoutMs,
           intervalMs,
+          probeTimeoutMs,
           attempts: attempt,
           lastFailure,
         });
@@ -764,7 +902,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
   const tunnelCommand = ["ssh", ...args];
   const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const scope = yield* Scope.Scope;
-  yield* Effect.logInfo("ssh.tunnel.spawn.start", {
+  yield* Effect.logDebug("ssh.tunnel.spawn.start", {
     ...sshTargetLogFields(input.resolvedTarget),
     command: tunnelCommand,
     localPort: input.localPort,
@@ -797,7 +935,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
           }),
       ),
     );
-  yield* Effect.logInfo("ssh.tunnel.spawn.succeeded", {
+  yield* Effect.logDebug("ssh.tunnel.spawn.succeeded", {
     ...sshTargetLogFields(input.resolvedTarget),
     command: tunnelCommand,
     pid: child.pid,
@@ -939,7 +1077,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
   const closeTunnelEntry = Effect.fn("ssh/tunnel.closeTunnelEntry")(function* (
     entry: SshTunnelEntry,
   ) {
-    yield* Effect.logInfo("ssh.tunnel.close.start", {
+    yield* Effect.logDebug("ssh.tunnel.close.start", {
       ...sshTargetLogFields(entry.target),
       key: entry.key,
       localPort: entry.localPort,
@@ -1080,7 +1218,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     readonly resolvedTarget: DesktopSshEnvironmentTarget;
     readonly runner?: RemoteT3RunnerOptions;
   }): Effect.fn.Return<SshTunnelEntry, SshEnvironmentEffectError, SshEnvironmentEffectContext> {
-    yield* Effect.logInfo("ssh.environment.tunnel.create.start", {
+    yield* Effect.logDebug("ssh.environment.tunnel.create.start", {
       ...sshTargetLogFields(input.resolvedTarget),
       ...sshRunnerLogFields(input.runner),
       key: input.key,
@@ -1091,7 +1229,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       operation: (authOptions) =>
         launchOrReuseRemoteServer(input.resolvedTarget, authOptions, input.runner),
     });
-    yield* Effect.logInfo("ssh.environment.remotePort.ready", {
+    yield* Effect.logDebug("ssh.environment.remotePort.ready", {
       ...sshTargetLogFields(input.resolvedTarget),
       key: input.key,
       remotePort,
@@ -1099,7 +1237,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     const localPort = yield* reserveLocalTunnelPort();
     const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
     const wsBaseUrl = `ws://127.0.0.1:${localPort}/`;
-    yield* Effect.logInfo("ssh.environment.localPort.reserved", {
+    yield* Effect.logDebug("ssh.environment.localPort.reserved", {
       ...sshTargetLogFields(input.resolvedTarget),
       key: input.key,
       localPort,
@@ -1134,7 +1272,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
         if (tunnels.get(tunnelEntry.key) !== tunnelEntry) {
           return;
         }
-        yield* Effect.logInfo("ssh.environment.tunnel.finalizer.start", {
+        yield* Effect.logDebug("ssh.environment.tunnel.finalizer.start", {
           ...sshTargetLogFields(tunnelEntry.target),
           key: tunnelEntry.key,
           localPort: tunnelEntry.localPort,
@@ -1168,7 +1306,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
           ],
           { concurrency: "unbounded" },
         ).pipe(Effect.ignore);
-        yield* Effect.logInfo("ssh.environment.tunnel.finalizer.succeeded", {
+        yield* Effect.logDebug("ssh.environment.tunnel.finalizer.succeeded", {
           ...sshTargetLogFields(tunnelEntry.target),
           key: tunnelEntry.key,
           localPort: tunnelEntry.localPort,
@@ -1176,7 +1314,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
         });
       }).pipe(Effect.ignore),
     );
-    yield* Effect.logInfo("ssh.environment.tunnel.create.succeeded", {
+    yield* Effect.logDebug("ssh.environment.tunnel.create.succeeded", {
       ...sshTargetLogFields(input.resolvedTarget),
       key: input.key,
       localPort,
@@ -1203,7 +1341,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
         waitForHttpReady({ baseUrl: entry.httpBaseUrl, timeoutMs: 2_000 }),
       );
       if (Exit.isSuccess(readinessExit)) {
-        yield* Effect.logInfo("ssh.environment.tunnel.reused", {
+        yield* Effect.logDebug("ssh.environment.tunnel.reused", {
           ...sshTargetLogFields(resolvedTarget),
           key,
           localPort: entry.localPort,
@@ -1224,7 +1362,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
 
     const pending = pendingTunnelEntries.get(key);
     if (pending) {
-      yield* Effect.logInfo("ssh.environment.tunnel.pending.await", {
+      yield* Effect.logDebug("ssh.environment.tunnel.pending.await", {
         ...sshTargetLogFields(resolvedTarget),
         key,
       });
@@ -1275,7 +1413,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       ...(target.port !== null ? { port: target.port } : {}),
     };
     const key = targetConnectionKey(resolvedTarget);
-    yield* Effect.logInfo("ssh.environment.target.resolved", {
+    yield* Effect.logDebug("ssh.environment.target.resolved", {
       ...sshTargetLogFields(resolvedTarget),
       key,
     });

From cb6507e54e4ca00c652ebf29fcc3b850e94feed6 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 20:28:58 -0700
Subject: [PATCH 43/74] Update settings panel tests for pairing and SSH flow

- Match the new pairing URL button label
- Scope Add Environment assertions to the dialog and updated SSH flow
---
 .../settings/SettingsPanels.browser.tsx       | 22 ++++++++++---------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/apps/web/src/components/settings/SettingsPanels.browser.tsx b/apps/web/src/components/settings/SettingsPanels.browser.tsx
index 14a6e76edc1..4630f6e7c4c 100644
--- a/apps/web/src/components/settings/SettingsPanels.browser.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.browser.tsx
@@ -803,7 +803,7 @@ describe("GeneralSettingsPanel observability", () => {
       .element(page.getByText("Client · Mobile · iOS · Safari · 192.168.1.88"))
       .toBeInTheDocument();
     await expect
-      .element(page.getByRole("button", { name: /^(Copy code|Show link)$/ }))
+      .element(page.getByRole("button", { name: /^Copy pairing URL for:/ }))
       .toBeInTheDocument();
     await expect.element(page.getByText("Revoke others")).toBeInTheDocument();
   });
@@ -956,10 +956,11 @@ describe("GeneralSettingsPanel observability", () => {
     );
 
     await page.getByRole("button", { name: "Add environment", exact: true }).click();
+    const addEnvironmentDialog = page.getByRole("dialog", { name: "Add Environment" });
     await expect
-      .element(page.getByRole("heading", { name: "Add Environment", exact: true }))
+      .element(addEnvironmentDialog.getByRole("heading", { name: "Add Environment", exact: true }))
       .toBeInTheDocument();
-    await page.getByRole("button", { name: "SSH", exact: true }).click();
+    await addEnvironmentDialog.getByRole("button", { name: /^SSH\b/ }).click();
     await vi.waitFor(() => {
       expect(discoverSshHosts).toHaveBeenCalledTimes(1);
     });
@@ -967,12 +968,13 @@ describe("GeneralSettingsPanel observability", () => {
       .element(page.getByRole("heading", { name: "devbox", exact: true }))
       .toBeInTheDocument();
 
-    await page.getByText("Enter a host manually").click();
-    await page.getByLabelText("Label").fill("Build box");
-    await page.getByLabelText("SSH host or alias").fill("devbox.example.com");
-    await page.getByLabelText("Username").fill("julius");
-    await page.getByLabelText("Port").fill("2222");
-    await page.getByRole("button", { name: "Connect SSH host", exact: true }).click();
+    await addEnvironmentDialog.getByLabelText("SSH host or alias").fill("devbox.example.com");
+    await addEnvironmentDialog.getByLabelText("Username").fill("julius");
+    await addEnvironmentDialog.getByLabelText("Port").fill("2222");
+    await addEnvironmentDialog
+      .getByRole("button", { name: "Add environment", exact: true })
+      .first()
+      .click();
 
     await vi.waitFor(() => {
       expect(mockConnectDesktopSshEnvironment).toHaveBeenCalledWith(
@@ -982,7 +984,7 @@ describe("GeneralSettingsPanel observability", () => {
           username: "julius",
           port: 2222,
         },
-        { label: "Build box" },
+        { label: "" },
       );
     });
   });

From ae941e66167782c5135b8099e5a364f7348c8e2e Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 20:47:22 -0700
Subject: [PATCH 44/74] Remove hardcoded dev remote server path

- Default the remote T3 server entry path to an empty string
- Rely on `T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH` when set
---
 apps/desktop/src/main.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index af939cb768c..9c097fc9bd1 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -124,8 +124,7 @@ const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
 // for a built server entry, for example:
 // "/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs"
 const DEV_REMOTE_T3_SERVER_ENTRY_PATH =
-  process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ??
-  "/Users/julius/Developer/t3code/apps/server/dist/bin.mjs";
+  process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ?? "";
 const desktopAppBranding: DesktopAppBranding = resolveDesktopAppBranding({
   isDevelopment,
   appVersion: app.getVersion(),

From 7125fa1c8bed970168acecaffb612a74e45776d8 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 21:09:19 -0700
Subject: [PATCH 45/74] Simplify hosted pairing and Tailscale serve cleanup

- Remove desktop SSH launch scripts and bundled copy step
- Make endpoint labels and server exposure detection host-aware
- Clear Tailscale Serve using the active MagicDNS name
---
 apps/desktop/src/serverExposure.test.ts       |  4 +-
 apps/desktop/src/serverExposure.ts            | 11 ++--
 apps/desktop/src/sshScripts/askpass-posix.sh  | 10 ----
 .../src/sshScripts/askpass-windows.cmd        |  2 -
 .../src/sshScripts/askpass-windows.ps1        | 10 ----
 apps/desktop/src/sshScripts/remote-launch.sh  | 34 ------------
 apps/desktop/src/sshScripts/remote-pairing.sh | 10 ----
 .../src/sshScripts/remote-pick-port.cjs       | 31 -----------
 apps/desktop/src/sshScripts/remote-runner.sh  | 13 -----
 apps/desktop/tsdown.config.ts                 |  1 -
 apps/server/src/server.ts                     | 55 +++++++++++--------
 apps/web/src/routes/__root.tsx                | 30 +++-------
 packages/tailscale/src/tailscale.test.ts      | 21 ++++++-
 packages/tailscale/src/tailscale.ts           | 48 ++++++++++++----
 14 files changed, 103 insertions(+), 177 deletions(-)
 delete mode 100644 apps/desktop/src/sshScripts/askpass-posix.sh
 delete mode 100644 apps/desktop/src/sshScripts/askpass-windows.cmd
 delete mode 100644 apps/desktop/src/sshScripts/askpass-windows.ps1
 delete mode 100644 apps/desktop/src/sshScripts/remote-launch.sh
 delete mode 100644 apps/desktop/src/sshScripts/remote-pairing.sh
 delete mode 100644 apps/desktop/src/sshScripts/remote-pick-port.cjs
 delete mode 100644 apps/desktop/src/sshScripts/remote-runner.sh

diff --git a/apps/desktop/src/serverExposure.test.ts b/apps/desktop/src/serverExposure.test.ts
index d12375e0cbf..4e284ef42bd 100644
--- a/apps/desktop/src/serverExposure.test.ts
+++ b/apps/desktop/src/serverExposure.test.ts
@@ -171,7 +171,7 @@ describe("resolveDesktopCoreAdvertisedEndpoints", () => {
       },
       {
         id: "manual:http://desktop.example.test:3773",
-        label: "Custom HTTPS",
+        label: "Custom endpoint",
         provider: {
           id: "manual",
           label: "Manual",
@@ -187,7 +187,7 @@ describe("resolveDesktopCoreAdvertisedEndpoints", () => {
         },
         source: "user",
         status: "unknown",
-        description: "User-configured HTTPS endpoint for this desktop backend.",
+        description: "User-configured endpoint for this desktop backend.",
       },
     ]);
   });
diff --git a/apps/desktop/src/serverExposure.ts b/apps/desktop/src/serverExposure.ts
index 035e2e155ae..b73b850ad13 100644
--- a/apps/desktop/src/serverExposure.ts
+++ b/apps/desktop/src/serverExposure.ts
@@ -165,17 +165,18 @@ export function resolveDesktopCoreAdvertisedEndpoints(
 
   for (const customEndpointUrl of input.customHttpsEndpointUrls ?? []) {
     try {
+      const isHttpsEndpoint = isHttpsEndpointUrl(customEndpointUrl);
       endpoints.push(
         createManualEndpoint({
           id: `manual:${customEndpointUrl}`,
-          label: "Custom HTTPS",
+          label: isHttpsEndpoint ? "Custom HTTPS" : "Custom endpoint",
           httpBaseUrl: customEndpointUrl,
           reachability: "public",
-          ...(isHttpsEndpointUrl(customEndpointUrl)
-            ? ({ hostedHttpsCompatibility: "compatible" } as const)
-            : {}),
+          ...(isHttpsEndpoint ? ({ hostedHttpsCompatibility: "compatible" } as const) : {}),
           status: "unknown",
-          description: "User-configured HTTPS endpoint for this desktop backend.",
+          description: isHttpsEndpoint
+            ? "User-configured HTTPS endpoint for this desktop backend."
+            : "User-configured endpoint for this desktop backend.",
         }),
       );
     } catch {
diff --git a/apps/desktop/src/sshScripts/askpass-posix.sh b/apps/desktop/src/sshScripts/askpass-posix.sh
deleted file mode 100644
index 56e3bc5b253..00000000000
--- a/apps/desktop/src/sshScripts/askpass-posix.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/sh
-# Invoked by ssh via SSH_ASKPASS when T3 Code re-runs ssh with a cached password
-# from the renderer's in-app prompt. We never expose a native dialog here — if
-# T3_SSH_AUTH_SECRET is missing, that's a caller bug and we fail loudly.
-if [ "${T3_SSH_AUTH_SECRET+x}" = "x" ]; then
-  printf "%s\n" "$T3_SSH_AUTH_SECRET"
-  exit 0
-fi
-printf 'T3 Code ssh-askpass invoked without T3_SSH_AUTH_SECRET.\n' >&2
-exit 1
diff --git a/apps/desktop/src/sshScripts/askpass-windows.cmd b/apps/desktop/src/sshScripts/askpass-windows.cmd
deleted file mode 100644
index 6421710215a..00000000000
--- a/apps/desktop/src/sshScripts/askpass-windows.cmd
+++ /dev/null
@@ -1,2 +0,0 @@
-@echo off
-powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0ssh-askpass.ps1" %*
diff --git a/apps/desktop/src/sshScripts/askpass-windows.ps1 b/apps/desktop/src/sshScripts/askpass-windows.ps1
deleted file mode 100644
index c24cfc21998..00000000000
--- a/apps/desktop/src/sshScripts/askpass-windows.ps1
+++ /dev/null
@@ -1,10 +0,0 @@
-# Invoked by ssh via SSH_ASKPASS (through ssh-askpass.cmd) when T3 Code re-runs
-# ssh with a cached password from the renderer's in-app prompt. We never expose
-# a native dialog here — if T3_SSH_AUTH_SECRET is missing, that's a caller bug
-# and we fail loudly.
-if ($null -ne $env:T3_SSH_AUTH_SECRET) {
-  [Console]::Out.WriteLine($env:T3_SSH_AUTH_SECRET)
-  exit 0
-}
-[Console]::Error.WriteLine("T3 Code ssh-askpass invoked without T3_SSH_AUTH_SECRET.")
-exit 1
diff --git a/apps/desktop/src/sshScripts/remote-launch.sh b/apps/desktop/src/sshScripts/remote-launch.sh
deleted file mode 100644
index ebe50c8bfaf..00000000000
--- a/apps/desktop/src/sshScripts/remote-launch.sh
+++ /dev/null
@@ -1,34 +0,0 @@
-set -eu
-STATE_KEY="$1"
-STATE_DIR="$HOME/.t3/ssh-launch/$STATE_KEY"
-SERVER_HOME="$STATE_DIR/server-home"
-PORT_FILE="$STATE_DIR/port"
-PID_FILE="$STATE_DIR/pid"
-LOG_FILE="$STATE_DIR/server.log"
-RUNNER_FILE="$STATE_DIR/run-t3.sh"
-mkdir -p "$STATE_DIR" "$SERVER_HOME"
-cat >"$RUNNER_FILE" <<'SH'
-@@T3_RUNNER_SCRIPT@@
-SH
-chmod 700 "$RUNNER_FILE"
-pick_port() {
-  node - "$PORT_FILE" "@@T3_DEFAULT_REMOTE_PORT@@" "@@T3_REMOTE_PORT_SCAN_WINDOW@@" <<'NODE'
-@@T3_PICK_PORT_SCRIPT@@
-NODE
-}
-REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
-REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
-if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
-  :
-else
-  REMOTE_PORT="$(pick_port)" || true
-  if [ -z "$REMOTE_PORT" ]; then
-    printf 'Failed to find an available port on the remote host. Ensure node is available on PATH.\n' >&2
-    exit 1
-  fi
-  nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
-  REMOTE_PID="$!"
-  printf '%s\n' "$REMOTE_PID" >"$PID_FILE"
-  printf '%s\n' "$REMOTE_PORT" >"$PORT_FILE"
-fi
-printf '{"remotePort":%s}\n' "$REMOTE_PORT"
diff --git a/apps/desktop/src/sshScripts/remote-pairing.sh b/apps/desktop/src/sshScripts/remote-pairing.sh
deleted file mode 100644
index 4e9d850e103..00000000000
--- a/apps/desktop/src/sshScripts/remote-pairing.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-set -eu
-STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
-SERVER_HOME="$STATE_DIR/server-home"
-RUNNER_FILE="$STATE_DIR/run-t3.sh"
-mkdir -p "$STATE_DIR" "$SERVER_HOME"
-cat >"$RUNNER_FILE" <<'SH'
-@@T3_RUNNER_SCRIPT@@
-SH
-chmod 700 "$RUNNER_FILE"
-"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json
diff --git a/apps/desktop/src/sshScripts/remote-pick-port.cjs b/apps/desktop/src/sshScripts/remote-pick-port.cjs
deleted file mode 100644
index 7051beae895..00000000000
--- a/apps/desktop/src/sshScripts/remote-pick-port.cjs
+++ /dev/null
@@ -1,31 +0,0 @@
-const fs = require("node:fs");
-const net = require("node:net");
-const filePath = process.argv[2] ?? "";
-const defaultPort = Number.parseInt(process.argv[3] ?? "", 10);
-const scanWindow = Number.parseInt(process.argv[4] ?? "", 10);
-const raw = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8").trim() : "";
-const preferred = Number.parseInt(raw, 10);
-const start = Number.isInteger(preferred) ? preferred : defaultPort;
-const end = start + scanWindow;
-
-function tryPort(port) {
-  return new Promise((resolve) => {
-    const server = net.createServer();
-    server.unref();
-    server.once("error", () => resolve(false));
-    server.listen(port, "127.0.0.1", () => {
-      server.close((error) => resolve(error ? false : port));
-    });
-  });
-}
-
-(async () => {
-  for (let port = start; port < end; port += 1) {
-    const available = await tryPort(port);
-    if (available) {
-      process.stdout.write(String(port));
-      return;
-    }
-  }
-  process.exit(1);
-})().catch(() => process.exit(1));
diff --git a/apps/desktop/src/sshScripts/remote-runner.sh b/apps/desktop/src/sshScripts/remote-runner.sh
deleted file mode 100644
index c9a1b2164e2..00000000000
--- a/apps/desktop/src/sshScripts/remote-runner.sh
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/bin/sh
-set -eu
-if command -v t3 >/dev/null 2>&1; then
-  exec t3 "$@"
-fi
-if command -v npx >/dev/null 2>&1; then
-  exec npx --yes @@T3_PACKAGE_SPEC@@ "$@"
-fi
-if command -v npm >/dev/null 2>&1; then
-  exec npm exec --yes @@T3_PACKAGE_SPEC@@ -- "$@"
-fi
-printf 'Remote host is missing the t3 CLI and could not install @@T3_PACKAGE_SPEC@@ because npx and npm are unavailable on PATH.\n' >&2
-exit 1
diff --git a/apps/desktop/tsdown.config.ts b/apps/desktop/tsdown.config.ts
index 2efcad6feec..74067b127d0 100644
--- a/apps/desktop/tsdown.config.ts
+++ b/apps/desktop/tsdown.config.ts
@@ -13,7 +13,6 @@ export default defineConfig([
     entry: ["src/main.ts"],
     clean: true,
     noExternal: (id) => id.startsWith("@t3tools/") || id.startsWith("effect-acp"),
-    copy: [{ from: "src/sshScripts/*", to: "dist-electron/sshScripts" }],
   },
   {
     ...shared,
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 9925791f865..cebb334bfb4 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -330,38 +330,47 @@ export const makeServerLayer = Layer.unwrap(
     const tailscaleServeLayer = config.tailscaleServeEnabled
       ? Layer.effectDiscard(
           Effect.acquireRelease(
-            ensureTailscaleServe({
-              localPort: config.port,
-              servePort: config.tailscaleServePort,
-              localHost: "127.0.0.1",
-            }).pipe(
-              Effect.as(true),
-              Effect.tap(() =>
-                Effect.logInfo("Tailscale Serve configured", {
-                  localPort: config.port,
-                  servePort: config.tailscaleServePort,
-                }),
-              ),
-              Effect.catch((cause) =>
-                Effect.logWarning("Failed to configure Tailscale Serve", {
-                  cause,
-                  localPort: config.port,
-                  servePort: config.tailscaleServePort,
-                }).pipe(Effect.as(false)),
-              ),
-            ),
+            Effect.gen(function* () {
+              const server = yield* HttpServer.HttpServer;
+              const address = server.address;
+              if (typeof address === "string" || !("port" in address)) {
+                return null;
+              }
+
+              const localPort = address.port;
+              return yield* ensureTailscaleServe({
+                localPort,
+                servePort: config.tailscaleServePort,
+                localHost: "127.0.0.1",
+              }).pipe(
+                Effect.as({ localPort, servePort: config.tailscaleServePort }),
+                Effect.tap(() =>
+                  Effect.logInfo("Tailscale Serve configured", {
+                    localPort,
+                    servePort: config.tailscaleServePort,
+                  }),
+                ),
+                Effect.catch((cause) =>
+                  Effect.logWarning("Failed to configure Tailscale Serve", {
+                    cause,
+                    localPort,
+                    servePort: config.tailscaleServePort,
+                  }).pipe(Effect.as(null)),
+                ),
+              );
+            }),
             (configured) =>
               configured
-                ? disableTailscaleServe.pipe(
+                ? disableTailscaleServe({ servePort: configured.servePort }).pipe(
                     Effect.tap(() =>
                       Effect.logInfo("Tailscale Serve disabled", {
-                        servePort: config.tailscaleServePort,
+                        servePort: configured.servePort,
                       }),
                     ),
                     Effect.catch((cause) =>
                       Effect.logWarning("Failed to disable Tailscale Serve", {
                         cause,
-                        servePort: config.tailscaleServePort,
+                        servePort: configured.servePort,
                       }),
                     ),
                   )
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index d4ba56f3c51..58617589dfa 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -82,29 +82,13 @@ export const Route = createRootRouteWithContext<{
       };
     }
 
-    try {
-      const [, authGateState] = await Promise.all([
-        ensurePrimaryEnvironmentReady(),
-        resolveInitialServerAuthGateState(),
-      ]);
-      return {
-        authGateState,
-      };
-    } catch (error) {
-      if (location.pathname === "/pair") {
-        throw error;
-      }
-      if (!isHostedStaticApp(new URL(window.location.href))) {
-        throw error;
-      }
-
-      await waitForSavedEnvironmentRegistryHydration();
-      return {
-        authGateState: {
-          status: "hosted-static",
-        } as const,
-      };
-    }
+    const [, authGateState] = await Promise.all([
+      ensurePrimaryEnvironmentReady(),
+      resolveInitialServerAuthGateState(),
+    ]);
+    return {
+      authGateState,
+    };
   },
   component: RootRouteView,
   errorComponent: RootRouteErrorView,
diff --git a/packages/tailscale/src/tailscale.test.ts b/packages/tailscale/src/tailscale.test.ts
index 788ea836dfc..cd4ddbb7c92 100644
--- a/packages/tailscale/src/tailscale.test.ts
+++ b/packages/tailscale/src/tailscale.test.ts
@@ -120,12 +120,29 @@ describe("tailscale", () => {
   });
 
   it.effect("disables tailscale serve through the process spawner service", () => {
+    const commands: {
+      readonly command: string;
+      readonly args: ReadonlyArray<string>;
+    }[] = [];
     const layer = mockSpawnerLayer((command, args) => {
+      commands.push({ command, args });
       assert.equal(command, "tailscale");
-      assert.deepEqual(args, ["serve", "off"]);
+      if (args[0] === "status") {
+        assert.deepEqual(args, ["status", "--json"]);
+        return {
+          stdout: tailscaleStatusJson,
+        };
+      }
+      assert.deepEqual(args, ["serve", "clear", "desktop.tail.ts.net:8443"]);
       return {};
     });
 
-    return disableTailscaleServe.pipe(Effect.provide(layer));
+    return Effect.gen(function* () {
+      yield* disableTailscaleServe({ servePort: 8443 }).pipe(Effect.provide(layer));
+      assert.deepEqual(commands, [
+        { command: "tailscale", args: ["status", "--json"] },
+        { command: "tailscale", args: ["serve", "clear", "desktop.tail.ts.net:8443"] },
+      ]);
+    });
   });
 });
diff --git a/packages/tailscale/src/tailscale.ts b/packages/tailscale/src/tailscale.ts
index ff944299d71..f7b6c4ed569 100644
--- a/packages/tailscale/src/tailscale.ts
+++ b/packages/tailscale/src/tailscale.ts
@@ -265,17 +265,43 @@ export const ensureTailscaleServe = (input: {
   });
 };
 
-export const disableTailscaleServe: Effect.Effect<
-  void,
-  TailscaleCommandError,
-  ChildProcessSpawner.ChildProcessSpawner
-> = runTailscaleCommand(["serve", "off"], {
-  spawnMessage: "Failed to spawn tailscale serve off.",
-  runMessage: "Failed to run tailscale serve off.",
-  exitMessage: (exitCode) => `Tailscale serve off exited with code ${exitCode}.`,
-  timeoutMessage: "Tailscale serve off timed out.",
-  timeoutMs: TAILSCALE_SERVE_TIMEOUT_MS,
-});
+export const disableTailscaleServe = (
+  input: {
+    readonly servePort?: number;
+  } = {},
+): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function* () {
+    const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
+    const status = yield* readTailscaleStatus.pipe(
+      Effect.mapError((error) =>
+        tailscaleCommandError(
+          ["status", "--json"],
+          "Cannot clear Tailscale Serve because status could not be read.",
+          null,
+          error instanceof Error ? error.message : String(error),
+        ),
+      ),
+    );
+    if (!status.magicDnsName) {
+      return yield* tailscaleCommandError(
+        ["serve", "clear"],
+        "Cannot clear Tailscale Serve because MagicDNS name is unavailable.",
+        null,
+      );
+    }
+
+    const service =
+      servePort === DEFAULT_TAILSCALE_SERVE_PORT
+        ? status.magicDnsName
+        : `${status.magicDnsName}:${servePort}`;
+    return yield* runTailscaleCommand(["serve", "clear", service], {
+      spawnMessage: "Failed to spawn tailscale serve clear.",
+      runMessage: "Failed to run tailscale serve clear.",
+      exitMessage: (exitCode) => `Tailscale serve clear exited with code ${exitCode}.`,
+      timeoutMessage: "Tailscale serve clear timed out.",
+      timeoutMs: TAILSCALE_SERVE_TIMEOUT_MS,
+    });
+  });
 
 export const probeTailscaleHttpsEndpoint = (input: {
   readonly baseUrl: string;

From 7cbca6755f2328e6a5555aec9cd32028b5d710fa Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 21:32:07 -0700
Subject: [PATCH 46/74] Cancel stale saved environment reconnects

- drop pending saved-environment connects on disconnect
- ignore stale WebSocket close events after transport disposal
---
 .../service.addSavedEnvironment.test.ts       |  65 +++++
 apps/web/src/environments/runtime/service.ts  | 274 +++++++++++-------
 apps/web/src/rpc/wsTransport.test.ts          |  34 +++
 apps/web/src/rpc/wsTransport.ts               |   2 +-
 4 files changed, 263 insertions(+), 112 deletions(-)

diff --git a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
index ca021cc5d41..3d9a51d833c 100644
--- a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
+++ b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
@@ -702,6 +702,71 @@ describe("addSavedEnvironment", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("cancels a pending saved environment connection when disconnected", async () => {
+    mockSavedRecords = [
+      {
+        environmentId: EnvironmentId.make("environment-1"),
+        label: "Remote environment",
+        httpBaseUrl: "https://remote.example.com/",
+        wsBaseUrl: "wss://remote.example.com/",
+        createdAt: "2026-04-14T00:00:00.000Z",
+        lastConnectedAt: null,
+      },
+    ];
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue("bearer-token");
+    const dispose = vi.fn(async () => undefined);
+    mockCreateEnvironmentConnection.mockImplementation(
+      (input: { knownEnvironment: { environmentId: EnvironmentId }; client: unknown }) => ({
+        kind: "saved" as const,
+        environmentId: input.knownEnvironment.environmentId,
+        knownEnvironment: input.knownEnvironment,
+        client: input.client,
+        ensureBootstrapped: async () => undefined,
+        reconnect: async () => undefined,
+        dispose,
+      }),
+    );
+    let resolveSessionState!: (value: {
+      readonly authenticated: true;
+      readonly role: "owner";
+    }) => void;
+    mockFetchRemoteSessionState.mockReturnValue(
+      new Promise((resolve) => {
+        resolveSessionState = resolve;
+      }),
+    );
+
+    const {
+      disconnectSavedEnvironment,
+      listEnvironmentConnections,
+      reconnectSavedEnvironment,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    const reconnectPromise = reconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+    await vi.waitFor(() => {
+      expect(mockFetchRemoteSessionState).toHaveBeenCalledOnce();
+    });
+
+    await disconnectSavedEnvironment(EnvironmentId.make("environment-1"));
+    resolveSessionState({
+      authenticated: true,
+      role: "owner",
+    });
+    await expect(reconnectPromise).resolves.toBeUndefined();
+
+    expect(listEnvironmentConnections()).toHaveLength(0);
+    expect(dispose).toHaveBeenCalledOnce();
+    expect(mockPatchRuntime).not.toHaveBeenCalledWith(
+      EnvironmentId.make("environment-1"),
+      expect.objectContaining({
+        connectionState: "error",
+      }),
+    );
+
+    await resetEnvironmentServiceForTests();
+  });
+
   it("reissues ssh pairing credentials when connecting after a manual ssh disconnect", async () => {
     mockSavedRecords = [
       {
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index c79fa209b12..f8e15ff517d 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -63,6 +63,7 @@ import {
 } from "~/store";
 import { useTerminalStateStore } from "~/terminalStateStore";
 import { useUiStateStore } from "~/uiStateStore";
+import type { WsProtocolCloseContext } from "../../rpc/protocol";
 import { WsTransport } from "../../rpc/wsTransport";
 import { createWsRpcClient, type WsRpcClient } from "../../rpc/wsRpcClient";
 import {
@@ -89,7 +90,28 @@ type ThreadDetailSubscriptionEntry = {
 };
 
 const environmentConnections = new Map<EnvironmentId, EnvironmentConnection>();
-const pendingSavedEnvironmentConnections = new Map<EnvironmentId, Promise<EnvironmentConnection>>();
+class SavedEnvironmentConnectionCancelledError extends Error {
+  constructor(environmentId: EnvironmentId) {
+    super(`Saved environment ${environmentId} connection was cancelled.`);
+    this.name = "SavedEnvironmentConnectionCancelledError";
+  }
+}
+
+function isSavedEnvironmentConnectionCancelledError(
+  error: unknown,
+): error is SavedEnvironmentConnectionCancelledError {
+  return error instanceof SavedEnvironmentConnectionCancelledError;
+}
+
+interface PendingSavedEnvironmentConnection {
+  cancelled: boolean;
+  readonly promise: Promise<EnvironmentConnection>;
+}
+
+const pendingSavedEnvironmentConnections = new Map<
+  EnvironmentId,
+  PendingSavedEnvironmentConnection
+>();
 const environmentConnectionListeners = new Set<() => void>();
 const threadDetailSubscriptions = new Map<string, ThreadDetailSubscriptionEntry>();
 const lastAppliedProjectionVersionByEnvironment = new Map<
@@ -1052,7 +1074,13 @@ function createSavedEnvironmentClient(
             lastErrorAt: isoNow(),
           });
         },
-        onClose: (details: { readonly code: number; readonly reason: string }) => {
+        onClose: (
+          details: { readonly code: number; readonly reason: string },
+          context: WsProtocolCloseContext,
+        ) => {
+          if (context.intentional) {
+            return;
+          }
           setRuntimeDisconnected(environmentId, details.reason);
         },
       },
@@ -1158,126 +1186,139 @@ async function ensureSavedEnvironmentConnection(
 
   const pending = pendingSavedEnvironmentConnections.get(record.environmentId);
   if (pending) {
-    return pending;
-  }
-
-  const nextConnection = (async () => {
-    let activeRecord = record;
-    let roleHint = options?.role ?? null;
-    let bearerToken =
-      options?.bearerToken ?? (await readSavedEnvironmentBearerToken(record.environmentId));
-    if (!bearerToken) {
-      if (record.desktopSsh) {
-        const issued = await issueDesktopSshBearerSession(record);
-        activeRecord = issued.record;
-        bearerToken = issued.bearerToken;
-        roleHint = issued.role;
+    return pending.promise;
+  }
+
+  const pendingEntry: PendingSavedEnvironmentConnection = {
+    cancelled: false,
+    promise: Promise.resolve().then(async () => {
+      let activeRecord = record;
+      let roleHint = options?.role ?? null;
+      let bearerToken =
+        options?.bearerToken ?? (await readSavedEnvironmentBearerToken(record.environmentId));
+      if (!bearerToken) {
+        if (record.desktopSsh) {
+          const issued = await issueDesktopSshBearerSession(record);
+          activeRecord = issued.record;
+          bearerToken = issued.bearerToken;
+          roleHint = issued.role;
+        } else {
+          useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
+            authState: "requires-auth",
+            role: null,
+            connectionState: "disconnected",
+            lastError: "Saved environment is missing its saved credential. Pair it again.",
+            lastErrorAt: isoNow(),
+          });
+          throw new Error("Saved environment is missing its saved credential.");
+        }
       } else {
-        useSavedEnvironmentRuntimeStore.getState().patch(record.environmentId, {
-          authState: "requires-auth",
-          role: null,
-          connectionState: "disconnected",
-          lastError: "Saved environment is missing its saved credential. Pair it again.",
-          lastErrorAt: isoNow(),
-        });
-        throw new Error("Saved environment is missing its saved credential.");
+        const prepared = await prepareSavedEnvironmentRecordForConnection(record);
+        activeRecord = prepared.record;
       }
-    } else {
-      const prepared = await prepareSavedEnvironmentRecordForConnection(record);
-      activeRecord = prepared.record;
-    }
 
-    const activeBearerToken = bearerToken;
-    const client =
-      options?.client ??
-      createSavedEnvironmentClient(activeRecord.environmentId, activeBearerToken);
-    const knownEnvironment = createKnownEnvironment({
-      id: activeRecord.environmentId,
-      label: activeRecord.label,
-      source: "manual",
-      target: {
-        httpBaseUrl: activeRecord.httpBaseUrl,
-        wsBaseUrl: activeRecord.wsBaseUrl,
-      },
-    });
-    const connection = createEnvironmentConnection({
-      kind: "saved",
-      knownEnvironment: {
-        ...knownEnvironment,
-        environmentId: activeRecord.environmentId,
-      },
-      client,
-      refreshMetadata: async () => {
-        await refreshSavedEnvironmentMetadata(
-          activeRecord.environmentId,
-          activeBearerToken,
-          client,
-        );
-      },
-      onConfigSnapshot: (config) => {
-        useSavedEnvironmentRuntimeStore.getState().patch(activeRecord.environmentId, {
-          descriptor: config.environment,
-          serverConfig: config,
-        });
-      },
-      onWelcome: (payload) => {
-        useSavedEnvironmentRuntimeStore.getState().patch(activeRecord.environmentId, {
-          descriptor: payload.environment,
-        });
-      },
-      ...createEnvironmentConnectionHandlers(),
-    });
+      const activeBearerToken = bearerToken;
+      const client =
+        options?.client ??
+        createSavedEnvironmentClient(activeRecord.environmentId, activeBearerToken);
+      const knownEnvironment = createKnownEnvironment({
+        id: activeRecord.environmentId,
+        label: activeRecord.label,
+        source: "manual",
+        target: {
+          httpBaseUrl: activeRecord.httpBaseUrl,
+          wsBaseUrl: activeRecord.wsBaseUrl,
+        },
+      });
+      const connection = createEnvironmentConnection({
+        kind: "saved",
+        knownEnvironment: {
+          ...knownEnvironment,
+          environmentId: activeRecord.environmentId,
+        },
+        client,
+        refreshMetadata: async () => {
+          await refreshSavedEnvironmentMetadata(
+            activeRecord.environmentId,
+            activeBearerToken,
+            client,
+          );
+        },
+        onConfigSnapshot: (config) => {
+          useSavedEnvironmentRuntimeStore.getState().patch(activeRecord.environmentId, {
+            descriptor: config.environment,
+            serverConfig: config,
+          });
+        },
+        onWelcome: (payload) => {
+          useSavedEnvironmentRuntimeStore.getState().patch(activeRecord.environmentId, {
+            descriptor: payload.environment,
+          });
+        },
+        ...createEnvironmentConnectionHandlers(),
+      });
 
-    try {
       try {
-        await refreshSavedEnvironmentMetadata(
-          activeRecord.environmentId,
-          activeBearerToken,
-          client,
-          roleHint,
-          options?.serverConfig ?? null,
-        );
+        try {
+          await refreshSavedEnvironmentMetadata(
+            activeRecord.environmentId,
+            activeBearerToken,
+            client,
+            roleHint,
+            options?.serverConfig ?? null,
+          );
+        } catch (error) {
+          const isAuthError = activeRecord.desktopSsh
+            ? isSshHttpAuthError(error, 401)
+            : isRemoteEnvironmentAuthHttpError(error) && error.status === 401;
+          if (!isAuthError) {
+            throw error;
+          }
+          if (!activeRecord.desktopSsh) {
+            await removeSavedEnvironmentBearerToken(activeRecord.environmentId);
+            throw new Error("Saved environment credential expired. Pair it again.", {
+              cause: error,
+            });
+          }
+
+          const issued = await issueDesktopSshBearerSession(activeRecord);
+          activeRecord = issued.record;
+          bearerToken = issued.bearerToken;
+          roleHint = issued.role;
+          await connection.dispose().catch(() => undefined);
+          pendingSavedEnvironmentConnections.delete(activeRecord.environmentId);
+          return await ensureSavedEnvironmentConnection(activeRecord, {
+            bearerToken,
+            role: roleHint,
+            serverConfig: options?.serverConfig ?? null,
+          });
+        }
+        if (
+          pendingEntry.cancelled ||
+          pendingSavedEnvironmentConnections.get(activeRecord.environmentId) !== pendingEntry
+        ) {
+          await connection.dispose().catch(() => undefined);
+          throw new SavedEnvironmentConnectionCancelledError(activeRecord.environmentId);
+        }
+        registerConnection(connection);
+        return connection;
       } catch (error) {
-        const isAuthError = activeRecord.desktopSsh
-          ? isSshHttpAuthError(error, 401)
-          : isRemoteEnvironmentAuthHttpError(error) && error.status === 401;
-        if (!isAuthError) {
+        if (error instanceof SavedEnvironmentConnectionCancelledError) {
           throw error;
         }
-        if (!activeRecord.desktopSsh) {
-          await removeSavedEnvironmentBearerToken(activeRecord.environmentId);
-          throw new Error("Saved environment credential expired. Pair it again.", {
-            cause: error,
-          });
+        setRuntimeError(activeRecord.environmentId, error);
+        const removed = await removeConnection(activeRecord.environmentId).catch(() => false);
+        if (!removed) {
+          await connection.dispose().catch(() => undefined);
         }
-
-        const issued = await issueDesktopSshBearerSession(activeRecord);
-        activeRecord = issued.record;
-        bearerToken = issued.bearerToken;
-        roleHint = issued.role;
-        await connection.dispose().catch(() => undefined);
-        pendingSavedEnvironmentConnections.delete(activeRecord.environmentId);
-        return await ensureSavedEnvironmentConnection(activeRecord, {
-          bearerToken,
-          role: roleHint,
-          serverConfig: options?.serverConfig ?? null,
-        });
+        throw error;
       }
-      registerConnection(connection);
-      return connection;
-    } catch (error) {
-      setRuntimeError(activeRecord.environmentId, error);
-      const removed = await removeConnection(activeRecord.environmentId).catch(() => false);
-      if (!removed) {
-        await connection.dispose().catch(() => undefined);
-      }
-      throw error;
-    }
-  })();
+    }),
+  };
 
-  pendingSavedEnvironmentConnections.set(record.environmentId, nextConnection);
-  return await nextConnection.finally(() => {
-    if (pendingSavedEnvironmentConnections.get(record.environmentId) === nextConnection) {
+  pendingSavedEnvironmentConnections.set(record.environmentId, pendingEntry);
+  return await pendingEntry.promise.finally(() => {
+    if (pendingSavedEnvironmentConnections.get(record.environmentId) === pendingEntry) {
       pendingSavedEnvironmentConnections.delete(record.environmentId);
     }
   });
@@ -1336,6 +1377,11 @@ export function getPrimaryEnvironmentConnection(): EnvironmentConnection {
 
 export async function disconnectSavedEnvironment(environmentId: EnvironmentId): Promise<void> {
   const record = getSavedEnvironmentRecord(environmentId);
+  const pendingConnection = pendingSavedEnvironmentConnections.get(environmentId);
+  if (pendingConnection) {
+    pendingConnection.cancelled = true;
+    pendingSavedEnvironmentConnections.delete(environmentId);
+  }
   const connection = environmentConnections.get(environmentId);
 
   if (connection?.kind === "saved") {
@@ -1362,6 +1408,9 @@ export async function reconnectSavedEnvironment(environmentId: EnvironmentId): P
       await ensureSavedEnvironmentConnection(record);
       return;
     } catch (error) {
+      if (isSavedEnvironmentConnectionCancelledError(error)) {
+        return;
+      }
       setRuntimeError(environmentId, error);
       throw error;
     }
@@ -1386,6 +1435,9 @@ export async function reconnectSavedEnvironment(environmentId: EnvironmentId): P
         });
         return;
       } catch (recoveryError) {
+        if (isSavedEnvironmentConnectionCancelledError(recoveryError)) {
+          return;
+        }
         setRuntimeError(environmentId, recoveryError);
         throw recoveryError;
       }
diff --git a/apps/web/src/rpc/wsTransport.test.ts b/apps/web/src/rpc/wsTransport.test.ts
index 522e15cd928..4fe6ed254ed 100644
--- a/apps/web/src/rpc/wsTransport.test.ts
+++ b/apps/web/src/rpc/wsTransport.test.ts
@@ -463,6 +463,40 @@ describe("WsTransport", () => {
     await transport.dispose();
   });
 
+  it("ignores stale socket close events after the transport is disposed", async () => {
+    const onClose = vi.fn();
+    const transport = createTransport("ws://localhost:3020", { onClose });
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(1);
+    });
+
+    const firstSocket = getSocket();
+    firstSocket.open();
+
+    await waitFor(() => {
+      expect(getWsConnectionStatus()).toMatchObject({
+        hasConnected: true,
+        phase: "connected",
+      });
+    });
+
+    await transport.reconnect();
+
+    await waitFor(() => {
+      expect(sockets).toHaveLength(2);
+    });
+
+    const secondSocket = getSocket();
+    secondSocket.open();
+    await transport.dispose();
+
+    onClose.mockClear();
+    firstSocket.close(1006, "stale close after dispose");
+
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
   it("marks unary requests as slow until the first server ack arrives", async () => {
     const slowAckThresholdMs = 25;
     setSlowRpcAckThresholdMsForTests(slowAckThresholdMs);
diff --git a/apps/web/src/rpc/wsTransport.ts b/apps/web/src/rpc/wsTransport.ts
index 746a65cd071..6d89be6afa5 100644
--- a/apps/web/src/rpc/wsTransport.ts
+++ b/apps/web/src/rpc/wsTransport.ts
@@ -227,7 +227,7 @@ export class WsTransport {
       Layer.mergeAll(
         createWsRpcProtocolLayer(this.url, {
           ...this.lifecycleHandlers,
-          isActive: () => this.activeSessionId === sessionId || this.disposed,
+          isActive: () => this.activeSessionId === sessionId,
           isCloseIntentional: () =>
             this.disposed ||
             this.intentionalCloseDepth > 0 ||

From 5f3fd6a7290c400f70c95802bae3301776ffc2ca Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Wed, 29 Apr 2026 23:42:21 -0700
Subject: [PATCH 47/74] Surface keybindings in server config updates

- Include resolved keybindings in the websocket payload
- Share keybinding compilation logic and defaults in `packages/shared`
- Update client state and tests to use the streamed keybindings
---
 apps/server/src/keybindings.ts                | 292 +-----------------
 apps/server/src/server.test.ts                |   2 +-
 apps/server/src/ws.ts                         |   1 +
 .../components/KeybindingsToast.browser.tsx   |   2 +-
 apps/web/src/rpc/serverState.test.ts          |  23 ++
 apps/web/src/rpc/serverState.ts               |  10 +-
 packages/contracts/src/server.ts              |   1 +
 packages/shared/package.json                  |   4 +
 packages/shared/src/keybindings.ts            | 283 +++++++++++++++++
 9 files changed, 336 insertions(+), 282 deletions(-)
 create mode 100644 packages/shared/src/keybindings.ts

diff --git a/apps/server/src/keybindings.ts b/apps/server/src/keybindings.ts
index 165b2edeb0c..4d7ee887a90 100644
--- a/apps/server/src/keybindings.ts
+++ b/apps/server/src/keybindings.ts
@@ -13,14 +13,10 @@ import {
   KeybindingShortcut,
   KeybindingWhenNode,
   MAX_KEYBINDINGS_COUNT,
-  MODEL_PICKER_JUMP_KEYBINDING_COMMANDS,
-  MAX_WHEN_EXPRESSION_DEPTH,
   ResolvedKeybindingRule,
   ResolvedKeybindingsConfig,
-  THREAD_JUMP_KEYBINDING_COMMANDS,
   type ServerConfigIssue,
 } from "@t3tools/contracts";
-import type { Mutable } from "effect/Types";
 import {
   Array,
   Cache,
@@ -48,278 +44,20 @@ import * as Semaphore from "effect/Semaphore";
 import { ServerConfig } from "./config.ts";
 import { writeFileStringAtomically } from "./atomicWrite.ts";
 import { fromLenientJson } from "@t3tools/shared/schemaJson";
-
-type WhenToken =
-  | { type: "identifier"; value: string }
-  | { type: "not" }
-  | { type: "and" }
-  | { type: "or" }
-  | { type: "lparen" }
-  | { type: "rparen" };
-
-export const DEFAULT_KEYBINDINGS: ReadonlyArray<KeybindingRule> = [
-  { key: "mod+j", command: "terminal.toggle" },
-  { key: "mod+d", command: "terminal.split", when: "terminalFocus" },
-  { key: "mod+n", command: "terminal.new", when: "terminalFocus" },
-  { key: "mod+w", command: "terminal.close", when: "terminalFocus" },
-  { key: "mod+d", command: "diff.toggle", when: "!terminalFocus" },
-  { key: "mod+k", command: "commandPalette.toggle", when: "!terminalFocus" },
-  { key: "mod+n", command: "chat.new", when: "!terminalFocus" },
-  { key: "mod+shift+o", command: "chat.new", when: "!terminalFocus" },
-  { key: "mod+shift+n", command: "chat.newLocal", when: "!terminalFocus" },
-  { key: "mod+shift+m", command: "modelPicker.toggle", when: "!terminalFocus" },
-  { key: "mod+o", command: "editor.openFavorite" },
-  { key: "mod+shift+[", command: "thread.previous" },
-  { key: "mod+shift+]", command: "thread.next" },
-  ...THREAD_JUMP_KEYBINDING_COMMANDS.map((command, index) => ({
-    key: `mod+${index + 1}`,
-    command,
-  })),
-  ...MODEL_PICKER_JUMP_KEYBINDING_COMMANDS.map((command, index) => ({
-    key: `mod+${index + 1}`,
-    command,
-    when: "modelPickerOpen",
-  })),
-];
-
-function normalizeKeyToken(token: string): string {
-  if (token === "space") return " ";
-  if (token === "esc") return "escape";
-  return token;
-}
-
-/** @internal - Exported for testing */
-export function parseKeybindingShortcut(value: string): KeybindingShortcut | null {
-  const rawTokens = value
-    .toLowerCase()
-    .split("+")
-    .map((token) => token.trim());
-  const tokens = [...rawTokens];
-  let trailingEmptyCount = 0;
-  while (tokens[tokens.length - 1] === "") {
-    trailingEmptyCount += 1;
-    tokens.pop();
-  }
-  if (trailingEmptyCount > 0) {
-    tokens.push("+");
-  }
-  if (tokens.some((token) => token.length === 0)) {
-    return null;
-  }
-  if (tokens.length === 0) return null;
-
-  let key: string | null = null;
-  let metaKey = false;
-  let ctrlKey = false;
-  let shiftKey = false;
-  let altKey = false;
-  let modKey = false;
-
-  for (const token of tokens) {
-    switch (token) {
-      case "cmd":
-      case "meta":
-        metaKey = true;
-        break;
-      case "ctrl":
-      case "control":
-        ctrlKey = true;
-        break;
-      case "shift":
-        shiftKey = true;
-        break;
-      case "alt":
-      case "option":
-        altKey = true;
-        break;
-      case "mod":
-        modKey = true;
-        break;
-      default: {
-        if (key !== null) return null;
-        key = normalizeKeyToken(token);
-      }
-    }
-  }
-
-  if (key === null) return null;
-  return {
-    key,
-    metaKey,
-    ctrlKey,
-    shiftKey,
-    altKey,
-    modKey,
-  };
-}
-
-function tokenizeWhenExpression(expression: string): WhenToken[] | null {
-  const tokens: WhenToken[] = [];
-  let index = 0;
-
-  while (index < expression.length) {
-    const current = expression[index];
-    if (!current) break;
-
-    if (/\s/.test(current)) {
-      index += 1;
-      continue;
-    }
-    if (expression.startsWith("&&", index)) {
-      tokens.push({ type: "and" });
-      index += 2;
-      continue;
-    }
-    if (expression.startsWith("||", index)) {
-      tokens.push({ type: "or" });
-      index += 2;
-      continue;
-    }
-    if (current === "!") {
-      tokens.push({ type: "not" });
-      index += 1;
-      continue;
-    }
-    if (current === "(") {
-      tokens.push({ type: "lparen" });
-      index += 1;
-      continue;
-    }
-    if (current === ")") {
-      tokens.push({ type: "rparen" });
-      index += 1;
-      continue;
-    }
-
-    const identifier = /^[A-Za-z_][A-Za-z0-9_.-]*/.exec(expression.slice(index));
-    if (!identifier) {
-      return null;
-    }
-    tokens.push({ type: "identifier", value: identifier[0] });
-    index += identifier[0].length;
-  }
-
-  return tokens;
-}
-
-function parseKeybindingWhenExpression(expression: string): KeybindingWhenNode | null {
-  const tokens = tokenizeWhenExpression(expression);
-  if (!tokens || tokens.length === 0) return null;
-  let index = 0;
-
-  const parsePrimary = (depth: number): KeybindingWhenNode | null => {
-    if (depth > MAX_WHEN_EXPRESSION_DEPTH) {
-      return null;
-    }
-    const token = tokens[index];
-    if (!token) return null;
-
-    if (token.type === "identifier") {
-      index += 1;
-      return { type: "identifier", name: token.value };
-    }
-
-    if (token.type === "lparen") {
-      index += 1;
-      const expressionNode = parseOr(depth + 1);
-      const closeToken = tokens[index];
-      if (!expressionNode || !closeToken || closeToken.type !== "rparen") {
-        return null;
-      }
-      index += 1;
-      return expressionNode;
-    }
-
-    return null;
-  };
-
-  const parseUnary = (depth: number): KeybindingWhenNode | null => {
-    let notCount = 0;
-    while (tokens[index]?.type === "not") {
-      index += 1;
-      notCount += 1;
-      if (notCount > MAX_WHEN_EXPRESSION_DEPTH) {
-        return null;
-      }
-    }
-
-    let node = parsePrimary(depth);
-    if (!node) return null;
-
-    while (notCount > 0) {
-      node = { type: "not", node };
-      notCount -= 1;
-    }
-
-    return node;
-  };
-
-  const parseAnd = (depth: number): KeybindingWhenNode | null => {
-    let left = parseUnary(depth);
-    if (!left) return null;
-
-    while (tokens[index]?.type === "and") {
-      index += 1;
-      const right = parseUnary(depth);
-      if (!right) return null;
-      left = { type: "and", left, right };
-    }
-
-    return left;
-  };
-
-  const parseOr = (depth: number): KeybindingWhenNode | null => {
-    let left = parseAnd(depth);
-    if (!left) return null;
-
-    while (tokens[index]?.type === "or") {
-      index += 1;
-      const right = parseAnd(depth);
-      if (!right) return null;
-      left = { type: "or", left, right };
-    }
-
-    return left;
-  };
-
-  const ast = parseOr(0);
-  if (!ast || index !== tokens.length) return null;
-  return ast;
-}
-
-/** @internal - Exported for testing */
-export function compileResolvedKeybindingRule(rule: KeybindingRule): ResolvedKeybindingRule | null {
-  const shortcut = parseKeybindingShortcut(rule.key);
-  if (!shortcut) return null;
-
-  if (rule.when !== undefined) {
-    const whenAst = parseKeybindingWhenExpression(rule.when);
-    if (!whenAst) return null;
-    return {
-      command: rule.command,
-      shortcut,
-      whenAst,
-    };
-  }
-
-  return {
-    command: rule.command,
-    shortcut,
-  };
-}
-
-export function compileResolvedKeybindingsConfig(
-  config: KeybindingsConfig,
-): ResolvedKeybindingsConfig {
-  const compiled: Mutable<ResolvedKeybindingsConfig> = [];
-  for (const rule of config) {
-    const result = Schema.decodeExit(ResolvedKeybindingFromConfig)(rule);
-    if (result._tag === "Success") {
-      compiled.push(result.value);
-    }
-  }
-  return compiled;
-}
+import {
+  DEFAULT_KEYBINDINGS,
+  DEFAULT_RESOLVED_KEYBINDINGS,
+  compileResolvedKeybindingRule,
+  compileResolvedKeybindingsConfig,
+  parseKeybindingShortcut,
+} from "@t3tools/shared/keybindings";
+
+export {
+  DEFAULT_KEYBINDINGS,
+  compileResolvedKeybindingRule,
+  compileResolvedKeybindingsConfig,
+  parseKeybindingShortcut,
+};
 
 export const ResolvedKeybindingFromConfig = KeybindingRule.pipe(
   Schema.decodeTo(
@@ -412,8 +150,6 @@ function encodeWhenAst(node: KeybindingWhenNode): string {
   }
 }
 
-const DEFAULT_RESOLVED_KEYBINDINGS = compileResolvedKeybindingsConfig(DEFAULT_KEYBINDINGS);
-
 const RawKeybindingsEntries = fromLenientJson(Schema.Array(Schema.Unknown));
 const KeybindingsConfigJson = Schema.fromJsonString(KeybindingsConfig);
 const PrettyJsonString = SchemaGetter.parseJson<string>().compose(
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index 1e8f7cf0ebf..dc5ff915b6b 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -2012,7 +2012,7 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
       assert.deepEqual(second, {
         version: 1,
         type: "keybindingsUpdated",
-        payload: { issues: [] },
+        payload: { keybindings: [], issues: [] },
       });
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index bc05a328281..5860485b11c 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -992,6 +992,7 @@ const makeWsRpcLayer = (currentSessionId: AuthSessionId) =>
                   version: 1 as const,
                   type: "keybindingsUpdated" as const,
                   payload: {
+                    keybindings: event.keybindings,
                     issues: event.issues,
                   },
                 })),
diff --git a/apps/web/src/components/KeybindingsToast.browser.tsx b/apps/web/src/components/KeybindingsToast.browser.tsx
index c9d081b3fa6..b6df9712bb1 100644
--- a/apps/web/src/components/KeybindingsToast.browser.tsx
+++ b/apps/web/src/components/KeybindingsToast.browser.tsx
@@ -289,7 +289,7 @@ function sendServerConfigUpdatedPush(issues: ServerConfig["issues"]) {
   rpcHarness.emitStreamValue(WS_METHODS.subscribeServerConfig, {
     version: 1,
     type: "keybindingsUpdated",
-    payload: { issues },
+    payload: { keybindings: fixture.serverConfig.keybindings, issues },
   });
 }
 
diff --git a/apps/web/src/rpc/serverState.test.ts b/apps/web/src/rpc/serverState.test.ts
index 04c9c9e8f12..506ef84eeaa 100644
--- a/apps/web/src/rpc/serverState.test.ts
+++ b/apps/web/src/rpc/serverState.test.ts
@@ -10,10 +10,12 @@ import {
   type ServerLifecycleStreamEvent,
   type ServerProvider,
 } from "@t3tools/contracts";
+import { DEFAULT_RESOLVED_KEYBINDINGS } from "@t3tools/shared/keybindings";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
   getServerConfig,
+  getServerKeybindings,
   onProvidersUpdated,
   onServerConfigUpdated,
   onWelcome,
@@ -141,6 +143,11 @@ afterEach(() => {
 });
 
 describe("serverState", () => {
+  it("uses default keybindings before a server config snapshot is available", () => {
+    expect(getServerConfig()).toBeNull();
+    expect(getServerKeybindings()).toEqual(DEFAULT_RESOLVED_KEYBINDINGS);
+  });
+
   it("bootstraps the server config snapshot and replays it to late subscribers", async () => {
     serverApi.getConfig.mockResolvedValueOnce(baseServerConfig);
 
@@ -271,10 +278,25 @@ describe("serverState", () => {
       },
     ];
 
+    const nextKeybindings = [
+      {
+        command: "commandPalette.toggle",
+        shortcut: {
+          key: "p",
+          metaKey: false,
+          ctrlKey: false,
+          shiftKey: false,
+          altKey: false,
+          modKey: true,
+        },
+      },
+    ] as const;
+
     emitServerConfigEvent({
       version: 1,
       type: "keybindingsUpdated",
       payload: {
+        keybindings: nextKeybindings,
         issues: [{ kind: "keybindings.malformed-config", message: "bad json" }],
       },
     });
@@ -299,6 +321,7 @@ describe("serverState", () => {
     await waitFor(() => {
       expect(getServerConfig()).toEqual({
         ...baseServerConfig,
+        keybindings: nextKeybindings,
         issues: [{ kind: "keybindings.malformed-config", message: "bad json" }],
         providers: nextProviders,
         settings: {
diff --git a/apps/web/src/rpc/serverState.ts b/apps/web/src/rpc/serverState.ts
index 35472a96ed5..0a49ee1e225 100644
--- a/apps/web/src/rpc/serverState.ts
+++ b/apps/web/src/rpc/serverState.ts
@@ -10,6 +10,7 @@ import {
   type ServerProviderUpdatedPayload,
   type ServerSettings,
 } from "@t3tools/contracts";
+import { DEFAULT_RESOLVED_KEYBINDINGS } from "@t3tools/shared/keybindings";
 import { Atom } from "effect/unstable/reactivity";
 import { useCallback, useRef } from "react";
 
@@ -42,12 +43,12 @@ function toServerConfigUpdatedPayload(config: ServerConfig): ServerConfigUpdated
 }
 
 const EMPTY_AVAILABLE_EDITORS: ReadonlyArray<EditorId> = [];
-const EMPTY_KEYBINDINGS: ServerConfig["keybindings"] = [];
 const EMPTY_SERVER_PROVIDERS: ReadonlyArray<ServerProvider> = [];
 
 const selectAvailableEditors = (config: ServerConfig | null): ReadonlyArray<EditorId> =>
   config?.availableEditors ?? EMPTY_AVAILABLE_EDITORS;
-const selectKeybindings = (config: ServerConfig | null) => config?.keybindings ?? EMPTY_KEYBINDINGS;
+const selectKeybindings = (config: ServerConfig | null) =>
+  config?.keybindings ?? DEFAULT_RESOLVED_KEYBINDINGS;
 const selectKeybindingsConfigPath = (config: ServerConfig | null) =>
   config?.keybindingsConfigPath ?? null;
 const selectObservability = (config: ServerConfig | null) => config?.observability ?? null;
@@ -74,6 +75,10 @@ export function getServerConfig(): ServerConfig | null {
   return appAtomRegistry.get(serverConfigAtom);
 }
 
+export function getServerKeybindings(): ServerConfig["keybindings"] {
+  return selectKeybindings(getServerConfig());
+}
+
 export function getServerConfigUpdatedNotification(): ServerConfigUpdatedNotification | null {
   return appAtomRegistry.get(serverConfigUpdatedAtom);
 }
@@ -97,6 +102,7 @@ export function applyServerConfigEvent(event: ServerConfigStreamEvent): void {
       }
       const nextConfig = {
         ...latestServerConfig,
+        keybindings: event.payload.keybindings,
         issues: event.payload.issues,
       } satisfies ServerConfig;
       resolveServerConfig(nextConfig);
diff --git a/packages/contracts/src/server.ts b/packages/contracts/src/server.ts
index 1381faf5dfc..a3d07ea69c2 100644
--- a/packages/contracts/src/server.ts
+++ b/packages/contracts/src/server.ts
@@ -198,6 +198,7 @@ export const ServerConfigUpdatedPayload = Schema.Struct({
 export type ServerConfigUpdatedPayload = typeof ServerConfigUpdatedPayload.Type;
 
 export const ServerConfigKeybindingsUpdatedPayload = Schema.Struct({
+  keybindings: ResolvedKeybindingsConfig,
   issues: ServerConfigIssues,
 });
 export type ServerConfigKeybindingsUpdatedPayload =
diff --git a/packages/shared/package.json b/packages/shared/package.json
index da0f24b77aa..d407a78af58 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -75,6 +75,10 @@
     "./path": {
       "types": "./src/path.ts",
       "import": "./src/path.ts"
+    },
+    "./keybindings": {
+      "types": "./src/keybindings.ts",
+      "import": "./src/keybindings.ts"
     }
   },
   "scripts": {
diff --git a/packages/shared/src/keybindings.ts b/packages/shared/src/keybindings.ts
new file mode 100644
index 00000000000..c67ad784fe1
--- /dev/null
+++ b/packages/shared/src/keybindings.ts
@@ -0,0 +1,283 @@
+import {
+  type KeybindingRule,
+  type KeybindingShortcut,
+  type KeybindingWhenNode,
+  MAX_KEYBINDINGS_COUNT,
+  MAX_WHEN_EXPRESSION_DEPTH,
+  MODEL_PICKER_JUMP_KEYBINDING_COMMANDS,
+  type ResolvedKeybindingRule,
+  type ResolvedKeybindingsConfig,
+  THREAD_JUMP_KEYBINDING_COMMANDS,
+} from "@t3tools/contracts";
+
+type WhenToken =
+  | { type: "identifier"; value: string }
+  | { type: "not" }
+  | { type: "and" }
+  | { type: "or" }
+  | { type: "lparen" }
+  | { type: "rparen" };
+
+export const DEFAULT_KEYBINDINGS: ReadonlyArray<KeybindingRule> = [
+  { key: "mod+j", command: "terminal.toggle" },
+  { key: "mod+d", command: "terminal.split", when: "terminalFocus" },
+  { key: "mod+n", command: "terminal.new", when: "terminalFocus" },
+  { key: "mod+w", command: "terminal.close", when: "terminalFocus" },
+  { key: "mod+d", command: "diff.toggle", when: "!terminalFocus" },
+  { key: "mod+k", command: "commandPalette.toggle", when: "!terminalFocus" },
+  { key: "mod+n", command: "chat.new", when: "!terminalFocus" },
+  { key: "mod+shift+o", command: "chat.new", when: "!terminalFocus" },
+  { key: "mod+shift+n", command: "chat.newLocal", when: "!terminalFocus" },
+  { key: "mod+shift+m", command: "modelPicker.toggle", when: "!terminalFocus" },
+  { key: "mod+o", command: "editor.openFavorite" },
+  { key: "mod+shift+[", command: "thread.previous" },
+  { key: "mod+shift+]", command: "thread.next" },
+  ...THREAD_JUMP_KEYBINDING_COMMANDS.map((command, index) => ({
+    key: `mod+${index + 1}`,
+    command,
+  })),
+  ...MODEL_PICKER_JUMP_KEYBINDING_COMMANDS.map((command, index) => ({
+    key: `mod+${index + 1}`,
+    command,
+    when: "modelPickerOpen",
+  })),
+];
+
+function normalizeKeyToken(token: string): string {
+  if (token === "space") return " ";
+  if (token === "esc") return "escape";
+  return token;
+}
+
+export function parseKeybindingShortcut(value: string): KeybindingShortcut | null {
+  const rawTokens = value
+    .toLowerCase()
+    .split("+")
+    .map((token) => token.trim());
+  const tokens = [...rawTokens];
+  let trailingEmptyCount = 0;
+  while (tokens[tokens.length - 1] === "") {
+    trailingEmptyCount += 1;
+    tokens.pop();
+  }
+  if (trailingEmptyCount > 0) {
+    tokens.push("+");
+  }
+  if (tokens.some((token) => token.length === 0)) {
+    return null;
+  }
+  if (tokens.length === 0) return null;
+
+  let key: string | null = null;
+  let metaKey = false;
+  let ctrlKey = false;
+  let shiftKey = false;
+  let altKey = false;
+  let modKey = false;
+
+  for (const token of tokens) {
+    switch (token) {
+      case "cmd":
+      case "meta":
+        metaKey = true;
+        break;
+      case "ctrl":
+      case "control":
+        ctrlKey = true;
+        break;
+      case "shift":
+        shiftKey = true;
+        break;
+      case "alt":
+      case "option":
+        altKey = true;
+        break;
+      case "mod":
+        modKey = true;
+        break;
+      default: {
+        if (key !== null) return null;
+        key = normalizeKeyToken(token);
+      }
+    }
+  }
+
+  if (key === null) return null;
+  return {
+    key,
+    metaKey,
+    ctrlKey,
+    shiftKey,
+    altKey,
+    modKey,
+  };
+}
+
+function tokenizeWhenExpression(expression: string): WhenToken[] | null {
+  const tokens: WhenToken[] = [];
+  let index = 0;
+
+  while (index < expression.length) {
+    const current = expression[index];
+    if (!current) break;
+
+    if (/\s/.test(current)) {
+      index += 1;
+      continue;
+    }
+    if (expression.startsWith("&&", index)) {
+      tokens.push({ type: "and" });
+      index += 2;
+      continue;
+    }
+    if (expression.startsWith("||", index)) {
+      tokens.push({ type: "or" });
+      index += 2;
+      continue;
+    }
+    if (current === "!") {
+      tokens.push({ type: "not" });
+      index += 1;
+      continue;
+    }
+    if (current === "(") {
+      tokens.push({ type: "lparen" });
+      index += 1;
+      continue;
+    }
+    if (current === ")") {
+      tokens.push({ type: "rparen" });
+      index += 1;
+      continue;
+    }
+
+    const identifier = /^[A-Za-z_][A-Za-z0-9_.-]*/.exec(expression.slice(index));
+    if (!identifier) {
+      return null;
+    }
+    tokens.push({ type: "identifier", value: identifier[0] });
+    index += identifier[0].length;
+  }
+
+  return tokens;
+}
+
+function parseKeybindingWhenExpression(expression: string): KeybindingWhenNode | null {
+  const tokens = tokenizeWhenExpression(expression);
+  if (!tokens || tokens.length === 0) return null;
+  let index = 0;
+
+  const parsePrimary = (depth: number): KeybindingWhenNode | null => {
+    if (depth > MAX_WHEN_EXPRESSION_DEPTH) {
+      return null;
+    }
+    const token = tokens[index];
+    if (!token) return null;
+
+    if (token.type === "identifier") {
+      index += 1;
+      return { type: "identifier", name: token.value };
+    }
+
+    if (token.type === "lparen") {
+      index += 1;
+      const expressionNode = parseOr(depth + 1);
+      const closeToken = tokens[index];
+      if (!expressionNode || !closeToken || closeToken.type !== "rparen") {
+        return null;
+      }
+      index += 1;
+      return expressionNode;
+    }
+
+    return null;
+  };
+
+  const parseUnary = (depth: number): KeybindingWhenNode | null => {
+    let notCount = 0;
+    while (tokens[index]?.type === "not") {
+      index += 1;
+      notCount += 1;
+      if (notCount > MAX_WHEN_EXPRESSION_DEPTH) {
+        return null;
+      }
+    }
+
+    let node = parsePrimary(depth);
+    if (!node) return null;
+
+    while (notCount > 0) {
+      node = { type: "not", node };
+      notCount -= 1;
+    }
+
+    return node;
+  };
+
+  const parseAnd = (depth: number): KeybindingWhenNode | null => {
+    let left = parseUnary(depth);
+    if (!left) return null;
+
+    while (tokens[index]?.type === "and") {
+      index += 1;
+      const right = parseUnary(depth);
+      if (!right) return null;
+      left = { type: "and", left, right };
+    }
+
+    return left;
+  };
+
+  const parseOr = (depth: number): KeybindingWhenNode | null => {
+    let left = parseAnd(depth);
+    if (!left) return null;
+
+    while (tokens[index]?.type === "or") {
+      index += 1;
+      const right = parseAnd(depth);
+      if (!right) return null;
+      left = { type: "or", left, right };
+    }
+
+    return left;
+  };
+
+  const ast = parseOr(0);
+  if (!ast || index !== tokens.length) return null;
+  return ast;
+}
+
+export function compileResolvedKeybindingRule(rule: KeybindingRule): ResolvedKeybindingRule | null {
+  const shortcut = parseKeybindingShortcut(rule.key);
+  if (!shortcut) return null;
+
+  if (rule.when !== undefined) {
+    const whenAst = parseKeybindingWhenExpression(rule.when);
+    if (!whenAst) return null;
+    return {
+      command: rule.command,
+      shortcut,
+      whenAst,
+    };
+  }
+
+  return {
+    command: rule.command,
+    shortcut,
+  };
+}
+
+export function compileResolvedKeybindingsConfig(
+  config: ReadonlyArray<KeybindingRule>,
+): ResolvedKeybindingsConfig {
+  const compiled: ResolvedKeybindingRule[] = [];
+  for (const rule of config) {
+    const result = compileResolvedKeybindingRule(rule);
+    if (result) {
+      compiled.push(result);
+    }
+  }
+  return compiled.slice(-MAX_KEYBINDINGS_COUNT);
+}
+
+export const DEFAULT_RESOLVED_KEYBINDINGS = compileResolvedKeybindingsConfig(DEFAULT_KEYBINDINGS);

From d7eb1b89b836906a24dc674601cbb3f69bb28c20 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 15:25:07 -0700
Subject: [PATCH 48/74] Surface version mismatch warnings in composer and
 settings

- Add shared version-skew helpers and websocket hinting
- Show composer and connections warnings when client/server versions drift
- Extract stacked composer banners for reusable alerts
---
 apps/web/src/branding.ts                      |   2 +-
 apps/web/src/components/ChatView.tsx          | 127 ++++++++++++++++--
 .../components/chat/ComposerBannerStack.tsx   | 104 ++++++++++++++
 .../settings/ConnectionsSettings.tsx          |  26 ++++
 apps/web/src/environments/runtime/service.ts  |  23 +++-
 apps/web/src/rpc/protocol.ts                  |   4 +-
 apps/web/src/rpc/wsConnectionState.test.ts    |  29 ++++
 apps/web/src/rpc/wsConnectionState.ts         |  23 +++-
 apps/web/src/versionSkew.test.ts              |  52 +++++++
 apps/web/src/versionSkew.ts                   |  54 ++++++++
 10 files changed, 423 insertions(+), 21 deletions(-)
 create mode 100644 apps/web/src/components/chat/ComposerBannerStack.tsx
 create mode 100644 apps/web/src/versionSkew.test.ts
 create mode 100644 apps/web/src/versionSkew.ts

diff --git a/apps/web/src/branding.ts b/apps/web/src/branding.ts
index 99775a4c55d..061d5b78a8a 100644
--- a/apps/web/src/branding.ts
+++ b/apps/web/src/branding.ts
@@ -15,4 +15,4 @@ export const APP_STAGE_LABEL =
   injectedDesktopAppBranding?.stageLabel ?? (import.meta.env.DEV ? "Dev" : "Alpha");
 export const APP_DISPLAY_NAME =
   injectedDesktopAppBranding?.displayName ?? `${APP_BASE_NAME} (${APP_STAGE_LABEL})`;
-export const APP_VERSION = import.meta.env.APP_VERSION || "0.0.0";
+export const APP_VERSION = "0.0.20"; // import.meta.env.APP_VERSION || "0.0.0";
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 7685c0f419d..7cdc2f2db24 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -104,7 +104,7 @@ import { BranchToolbar } from "./BranchToolbar";
 import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings";
 import PlanSidebar from "./PlanSidebar";
 import ThreadTerminalDrawer from "./ThreadTerminalDrawer";
-import { ChevronDownIcon, WifiOffIcon } from "lucide-react";
+import { ChevronDownIcon, TriangleAlertIcon, WifiOffIcon } from "lucide-react";
 import { cn, randomUUID } from "~/lib/utils";
 import { stackedThreadToast, toastManager } from "./ui/toast";
 import { decodeProjectScriptKeybindingRule } from "~/lib/projectScriptKeybindings";
@@ -149,6 +149,7 @@ import { NoActiveThreadState } from "./NoActiveThreadState";
 import { resolveEffectiveEnvMode, resolveEnvironmentOptionLabel } from "./BranchToolbar.logic";
 import { ProviderStatusBanner } from "./chat/ProviderStatusBanner";
 import { ThreadErrorBanner } from "./chat/ThreadErrorBanner";
+import { ComposerBannerStack, type ComposerBannerStackItem } from "./chat/ComposerBannerStack";
 import {
   MAX_HIDDEN_MOUNTED_TERMINAL_THREADS,
   buildExpiredTerminalContextToastCopy,
@@ -181,8 +182,8 @@ import {
 import { sanitizeThreadErrorMessage } from "~/rpc/transportError";
 import { retainThreadDetailSubscription } from "../environments/runtime/service";
 import { RightPanelSheet } from "./RightPanelSheet";
-import { Alert, AlertAction, AlertDescription, AlertTitle } from "./ui/alert";
 import { Button } from "./ui/button";
+import { resolveServerConfigVersionMismatch } from "../versionSkew";
 
 const IMAGE_ONLY_BOOTSTRAP_PROMPT =
   "[User attached one or more images without additional text. Respond using the conversation context and the attached image(s).]";
@@ -875,6 +876,7 @@ export default function ChatView(props: ChatViewProps) {
     : "connected";
   const activeEnvironmentUnavailable =
     activeSavedEnvironmentRecord !== null && activeSavedEnvironmentConnectionState !== "connected";
+  const activeSavedEnvironmentId = activeSavedEnvironmentRecord?.environmentId ?? null;
   const activeEnvironmentUnavailableLabel = activeSavedEnvironmentRecord
     ? resolveEnvironmentOptionLabel({
         isPrimary: false,
@@ -883,18 +885,30 @@ export default function ChatView(props: ChatViewProps) {
         savedLabel: activeSavedEnvironmentRecord.label,
       })
     : null;
-  const activeEnvironmentUnavailableState: EnvironmentUnavailableState | null =
-    activeEnvironmentUnavailable && activeEnvironmentUnavailableLabel
-      ? {
-          environmentId: activeSavedEnvironmentRecord.environmentId,
-          label: activeEnvironmentUnavailableLabel,
-          connectionState:
-            activeSavedEnvironmentConnectionState === "connecting" ||
-            activeSavedEnvironmentConnectionState === "error"
-              ? activeSavedEnvironmentConnectionState
-              : "disconnected",
-        }
-      : null;
+  const activeEnvironmentUnavailableState = useMemo<EnvironmentUnavailableState | null>(() => {
+    if (
+      !activeEnvironmentUnavailable ||
+      !activeEnvironmentUnavailableLabel ||
+      !activeSavedEnvironmentId
+    ) {
+      return null;
+    }
+
+    return {
+      environmentId: activeSavedEnvironmentId,
+      label: activeEnvironmentUnavailableLabel,
+      connectionState:
+        activeSavedEnvironmentConnectionState === "connecting" ||
+        activeSavedEnvironmentConnectionState === "error"
+          ? activeSavedEnvironmentConnectionState
+          : "disconnected",
+    };
+  }, [
+    activeEnvironmentUnavailable,
+    activeEnvironmentUnavailableLabel,
+    activeSavedEnvironmentConnectionState,
+    activeSavedEnvironmentId,
+  ]);
   const [reconnectingEnvironmentId, setReconnectingEnvironmentId] = useState<EnvironmentId | null>(
     null,
   );
@@ -1122,6 +1136,90 @@ export default function ChatView(props: ChatViewProps) {
     primaryEnvironmentId && activeThread?.environmentId === primaryEnvironmentId
       ? primaryServerConfig
       : (activeEnvRuntimeState?.serverConfig ?? primaryServerConfig);
+  const versionMismatch = resolveServerConfigVersionMismatch(serverConfig);
+  const versionMismatchDismissKey =
+    versionMismatch && activeThread
+      ? `${activeThread.environmentId}:${versionMismatch.clientVersion}:${versionMismatch.serverVersion}`
+      : null;
+  const [dismissedVersionMismatchKey, setDismissedVersionMismatchKey] = useState<string | null>(
+    null,
+  );
+  const showVersionMismatchBanner =
+    versionMismatch !== null && versionMismatchDismissKey !== dismissedVersionMismatchKey;
+  const composerBannerItems = useMemo<ComposerBannerStackItem[]>(() => {
+    const items: ComposerBannerStackItem[] = [];
+    if (activeEnvironmentUnavailableState) {
+      items.push({
+        id: `environment-unavailable:${activeEnvironmentUnavailableState.environmentId}`,
+        variant:
+          activeEnvironmentUnavailableState.connectionState === "error" ? "error" : "warning",
+        icon: <WifiOffIcon />,
+        title: (
+          <>
+            {activeEnvironmentUnavailableState.label} is{" "}
+            {activeEnvironmentUnavailableState.connectionState === "connecting"
+              ? "connecting"
+              : "disconnected"}
+          </>
+        ),
+        description: "Reconnect this environment before sending messages or running actions.",
+        actions: (
+          <>
+            <Button
+              size="xs"
+              disabled={
+                activeEnvironmentUnavailableState.connectionState === "connecting" ||
+                reconnectingEnvironmentId === activeEnvironmentUnavailableState.environmentId
+              }
+              onClick={() =>
+                void handleReconnectActiveEnvironment(
+                  activeEnvironmentUnavailableState.environmentId,
+                  activeEnvironmentUnavailableState.label,
+                )
+              }
+            >
+              {activeEnvironmentUnavailableState.connectionState === "connecting" ||
+              reconnectingEnvironmentId === activeEnvironmentUnavailableState.environmentId
+                ? "Reconnecting..."
+                : "Reconnect"}
+            </Button>
+            <Button
+              size="xs"
+              variant="outline"
+              onClick={() => void navigate({ to: "/settings/connections" })}
+            >
+              Connections
+            </Button>
+          </>
+        ),
+      });
+    }
+    if (showVersionMismatchBanner && versionMismatch && versionMismatchDismissKey) {
+      items.push({
+        id: `version-mismatch:${versionMismatchDismissKey}`,
+        variant: "warning",
+        icon: <TriangleAlertIcon />,
+        title: "Client and server versions differ",
+        description: (
+          <>
+            Client {versionMismatch.clientVersion} is connected to server{" "}
+            {versionMismatch.serverVersion}. Sync them if RPC calls or reconnects fail.
+          </>
+        ),
+        dismissLabel: "Dismiss version mismatch warning",
+        onDismiss: () => setDismissedVersionMismatchKey(versionMismatchDismissKey),
+      });
+    }
+    return items;
+  }, [
+    activeEnvironmentUnavailableState,
+    handleReconnectActiveEnvironment,
+    navigate,
+    reconnectingEnvironmentId,
+    showVersionMismatchBanner,
+    versionMismatch,
+    versionMismatchDismissKey,
+  ]);
   const providerStatuses = serverConfig?.providers ?? EMPTY_PROVIDERS;
   const unlockedSelectedProvider = resolveSelectableProvider(
     providerStatuses,
@@ -3466,6 +3564,7 @@ export default function ChatView(props: ChatViewProps) {
                 : "pb-[calc(env(safe-area-inset-bottom)+0.75rem)] sm:pb-[calc(env(safe-area-inset-bottom)+1rem)]",
             )}
           >
+            <ComposerBannerStack items={composerBannerItems} />
             <ChatComposer
               ref={composerRef}
               composerDraftTarget={composerDraftTarget}
diff --git a/apps/web/src/components/chat/ComposerBannerStack.tsx b/apps/web/src/components/chat/ComposerBannerStack.tsx
new file mode 100644
index 00000000000..693bda1b526
--- /dev/null
+++ b/apps/web/src/components/chat/ComposerBannerStack.tsx
@@ -0,0 +1,104 @@
+import type { ReactNode } from "react";
+import { XIcon } from "lucide-react";
+
+import { cn } from "~/lib/utils";
+import { Alert, AlertAction, AlertDescription, AlertTitle } from "../ui/alert";
+import { Button } from "../ui/button";
+
+export interface ComposerBannerStackItem {
+  readonly id: string;
+  readonly variant: "error" | "info" | "success" | "warning";
+  readonly icon: ReactNode;
+  readonly title: ReactNode;
+  readonly description?: ReactNode;
+  readonly actions?: ReactNode;
+  readonly dismissLabel?: string;
+  readonly onDismiss?: () => void;
+}
+
+interface ComposerBannerStackProps {
+  readonly className?: string;
+  readonly items: ReadonlyArray<ComposerBannerStackItem>;
+}
+
+export function ComposerBannerStack({ className, items }: ComposerBannerStackProps) {
+  if (items.length === 0) {
+    return null;
+  }
+
+  const frontItem = items[0];
+  if (!frontItem) {
+    return null;
+  }
+  const stackedItems = items.slice(1);
+  const hasStack = stackedItems.length > 0;
+
+  return (
+    <div className={cn("group/banner-stack mx-auto mb-2 max-w-208", className)}>
+      <div
+        className={cn(
+          "relative",
+          hasStack ? "group-hover/banner-stack:z-50 group-focus-within/banner-stack:z-50" : null,
+        )}
+      >
+        {hasStack ? (
+          <div
+            className={cn(
+              "pointer-events-none absolute inset-x-0 -top-3 z-0 mx-auto h-3 rounded-t-xl",
+              "border border-b-0 border-warning/24 bg-background/96 shadow-[0_6px_18px_rgba(0,0,0,0.06)]",
+              "transition-opacity duration-150 ease-out",
+              "group-hover/banner-stack:opacity-0 group-focus-within/banner-stack:opacity-0",
+            )}
+            style={{ width: "96%" }}
+            aria-hidden="true"
+          />
+        ) : null}
+        <div className="relative z-10">
+          <ComposerBannerStackAlert item={frontItem} />
+        </div>
+        {hasStack ? (
+          <div
+            className={cn(
+              "pointer-events-none absolute inset-x-0 bottom-[calc(100%+0.5rem)] z-20 space-y-2 opacity-0",
+              "transition-[opacity,transform] duration-150 ease-out",
+              "translate-y-1 transform-gpu will-change-[opacity,transform]",
+              "group-hover/banner-stack:pointer-events-auto group-hover/banner-stack:translate-y-0 group-hover/banner-stack:opacity-100",
+              "group-focus-within/banner-stack:pointer-events-auto group-focus-within/banner-stack:translate-y-0 group-focus-within/banner-stack:opacity-100",
+            )}
+          >
+            {stackedItems.map((item) => (
+              <div key={item.id}>
+                <ComposerBannerStackAlert item={item} />
+              </div>
+            ))}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function ComposerBannerStackAlert({ item }: { readonly item: ComposerBannerStackItem }) {
+  return (
+    <Alert variant={item.variant}>
+      {item.icon}
+      <AlertTitle>{item.title}</AlertTitle>
+      {item.description ? <AlertDescription>{item.description}</AlertDescription> : null}
+      {item.actions || item.onDismiss ? (
+        <AlertAction>
+          {item.actions}
+          {item.onDismiss ? (
+            <Button
+              size="icon-xs"
+              variant="ghost"
+              aria-label={item.dismissLabel ?? "Dismiss warning"}
+              onClick={item.onDismiss}
+            >
+              <XIcon className="size-3.5" />
+            </Button>
+          ) : null}
+        </AlertAction>
+      ) : null}
+    </Alert>
+  );
+}
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index efdb7ab65fa..54d8575410e 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -5,6 +5,7 @@ import {
   QrCodeIcon,
   RefreshCwIcon,
   TerminalIcon,
+  TriangleAlertIcon,
 } from "lucide-react";
 import {
   type ReactNode,
@@ -103,6 +104,8 @@ import {
   removeSavedEnvironment,
 } from "~/environments/runtime";
 import { useUiStateStore } from "~/uiStateStore";
+import { resolveServerConfigVersionMismatch } from "~/versionSkew";
+import { useServerConfig } from "~/rpc/serverState";
 
 const DEFAULT_TAILSCALE_SERVE_PORT = 443;
 
@@ -1339,6 +1342,7 @@ function SavedBackendListRow({
   const descriptorLabel = runtime?.descriptor?.label ?? null;
   const displayLabel = descriptorLabel ?? record.label;
   const statusTooltip = getSavedBackendStatusTooltip(runtime, record, nowMs);
+  const versionMismatch = resolveServerConfigVersionMismatch(runtime?.serverConfig);
   const metadataBits = [
     record.desktopSsh ? `SSH ${formatDesktopSshTarget(record.desktopSsh)}` : null,
     roleLabel,
@@ -1364,6 +1368,13 @@ function SavedBackendListRow({
           {metadataBits.length > 0 ? (
             <p className="text-xs text-muted-foreground">{metadataBits.join(" · ")}</p>
           ) : null}
+          {versionMismatch ? (
+            <p className="flex items-center gap-1 text-warning text-xs">
+              <TriangleAlertIcon className="size-3.5 shrink-0" />
+              Version drift: client {versionMismatch.clientVersion}, server{" "}
+              {versionMismatch.serverVersion}.
+            </p>
+          ) : null}
         </div>
         <div className="flex w-full shrink-0 items-center gap-2 sm:w-auto sm:justify-end">
           <Button
@@ -1544,6 +1555,8 @@ export function ConnectionsSettings() {
   const [pendingDesktopServerExposureMode, setPendingDesktopServerExposureMode] = useState<
     DesktopServerExposureState["mode"] | null
   >(null);
+  const primaryServerConfig = useServerConfig();
+  const primaryVersionMismatch = resolveServerConfigVersionMismatch(primaryServerConfig);
   const [isAdvertisedEndpointListExpanded, setIsAdvertisedEndpointListExpanded] = useState(false);
   const defaultAdvertisedEndpointKey = useUiStateStore(
     (state) => state.defaultAdvertisedEndpointKey,
@@ -2486,6 +2499,19 @@ export function ConnectionsSettings() {
       {canManageLocalBackend ? (
         <>
           <SettingsSection title="Manage local backend">
+            {primaryVersionMismatch ? (
+              <SettingsRow
+                title="Version drift"
+                description={
+                  <span className="flex items-center gap-1 text-warning">
+                    <TriangleAlertIcon className="size-3.5 shrink-0" />
+                    Client {primaryVersionMismatch.clientVersion}, server{" "}
+                    {primaryVersionMismatch.serverVersion}. Sync them if RPC calls or reconnects
+                    fail.
+                  </span>
+                }
+              />
+            ) : null}
             {desktopBridge ? (
               <>
                 {renderNetworkAccessRow()}
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index f8e15ff517d..71d03c32103 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -64,8 +64,10 @@ import {
 import { useTerminalStateStore } from "~/terminalStateStore";
 import { useUiStateStore } from "~/uiStateStore";
 import type { WsProtocolCloseContext } from "../../rpc/protocol";
+import { getServerConfig } from "../../rpc/serverState";
 import { WsTransport } from "../../rpc/wsTransport";
 import { createWsRpcClient, type WsRpcClient } from "../../rpc/wsRpcClient";
+import { appendVersionMismatchHint, resolveServerConfigVersionMismatch } from "../../versionSkew";
 import {
   deriveLogicalProjectKeyFromSettings,
   derivePhysicalProjectKey,
@@ -1030,6 +1032,8 @@ function createPrimaryEnvironmentClient(
   return createWsRpcClient(
     new WsTransport(wsBaseUrl, {
       getConnectionLabel: () => connectionLabel,
+      getVersionMismatchHint: () =>
+        resolveServerConfigVersionMismatch(getServerConfig())?.hint ?? null,
     }),
   );
 }
@@ -1061,6 +1065,10 @@ function createSavedEnvironmentClient(
       },
       {
         getConnectionLabel: () => getSavedEnvironmentRecord(environmentId)?.label ?? null,
+        getVersionMismatchHint: () =>
+          resolveServerConfigVersionMismatch(
+            useSavedEnvironmentRuntimeStore.getState().byId[environmentId]?.serverConfig,
+          )?.hint ?? null,
         onAttempt: () => {
           setRuntimeConnecting(environmentId);
         },
@@ -1068,9 +1076,12 @@ function createSavedEnvironmentClient(
           setRuntimeConnected(environmentId);
         },
         onError: (message: string) => {
+          const mismatch = resolveServerConfigVersionMismatch(
+            useSavedEnvironmentRuntimeStore.getState().byId[environmentId]?.serverConfig,
+          );
           useSavedEnvironmentRuntimeStore.getState().patch(environmentId, {
             connectionState: "error",
-            lastError: message,
+            lastError: appendVersionMismatchHint(message, mismatch),
             lastErrorAt: isoNow(),
           });
         },
@@ -1081,7 +1092,15 @@ function createSavedEnvironmentClient(
           if (context.intentional) {
             return;
           }
-          setRuntimeDisconnected(environmentId, details.reason);
+          setRuntimeDisconnected(
+            environmentId,
+            appendVersionMismatchHint(
+              details.reason,
+              resolveServerConfigVersionMismatch(
+                useSavedEnvironmentRuntimeStore.getState().byId[environmentId]?.serverConfig,
+              ),
+            ),
+          );
         },
       },
     ),
diff --git a/apps/web/src/rpc/protocol.ts b/apps/web/src/rpc/protocol.ts
index 213f671528f..28a6a29288b 100644
--- a/apps/web/src/rpc/protocol.ts
+++ b/apps/web/src/rpc/protocol.ts
@@ -24,6 +24,7 @@ export interface WsProtocolCloseContext {
 
 export interface WsProtocolLifecycleHandlers {
   readonly getConnectionLabel?: () => string | null;
+  readonly getVersionMismatchHint?: () => string | null;
   readonly isCloseIntentional?: () => boolean;
   readonly isActive?: () => boolean;
   readonly onAttempt?: (socketUrl: string) => void;
@@ -61,6 +62,7 @@ function resolveWsRpcSocketUrl(rawUrl: string): string {
 function resolveConnectionMetadata(handlers?: WsProtocolLifecycleHandlers): WsConnectionMetadata {
   return {
     connectionLabel: handlers?.getConnectionLabel?.() ?? null,
+    versionMismatchHint: handlers?.getVersionMismatchHint?.() ?? null,
   };
 }
 
@@ -81,7 +83,7 @@ function defaultLifecycleHandlers(
     },
     onError: (message) => {
       clearAllTrackedRpcRequests();
-      recordWsConnectionErrored(message);
+      recordWsConnectionErrored(message, resolveConnectionMetadata(handlers));
     },
     onClose: (details, context) => {
       clearAllTrackedRpcRequests();
diff --git a/apps/web/src/rpc/wsConnectionState.test.ts b/apps/web/src/rpc/wsConnectionState.test.ts
index 1e65faa930e..b836789609e 100644
--- a/apps/web/src/rpc/wsConnectionState.test.ts
+++ b/apps/web/src/rpc/wsConnectionState.test.ts
@@ -63,6 +63,35 @@ describe("wsConnectionState", () => {
     });
   });
 
+  it("adds a version mismatch hint to websocket errors when metadata includes one", () => {
+    recordWsConnectionAttempt("ws://localhost:3020/ws", {
+      connectionLabel: "Remote Mac",
+    });
+    recordWsConnectionErrored("Unable to connect to the T3 server WebSocket.", {
+      versionMismatchHint: "Version mismatch. Try syncing the client and server.",
+    });
+
+    expect(getWsConnectionStatus()).toMatchObject({
+      lastError:
+        "Unable to connect to the T3 server WebSocket. Hint: Version mismatch. Try syncing the client and server.",
+    });
+  });
+
+  it("adds a version mismatch hint to websocket close reasons when metadata includes one", () => {
+    recordWsConnectionAttempt("ws://localhost:3020/ws");
+    recordWsConnectionOpened();
+    recordWsConnectionClosed(
+      { code: 1006, reason: "socket closed" },
+      {
+        versionMismatchHint: "Version mismatch. Try syncing the client and server.",
+      },
+    );
+
+    expect(getWsConnectionStatus()).toMatchObject({
+      closeReason: "socket closed Hint: Version mismatch. Try syncing the client and server.",
+    });
+  });
+
   it("marks the reconnect cycle as exhausted after the final attempt fails", () => {
     for (let attempt = 0; attempt < WS_RECONNECT_MAX_ATTEMPTS; attempt += 1) {
       recordWsConnectionAttempt("ws://localhost:3020/ws");
diff --git a/apps/web/src/rpc/wsConnectionState.ts b/apps/web/src/rpc/wsConnectionState.ts
index 1f649bdb356..bc8a5a78607 100644
--- a/apps/web/src/rpc/wsConnectionState.ts
+++ b/apps/web/src/rpc/wsConnectionState.ts
@@ -69,6 +69,7 @@ function updateWsConnectionStatus(
 
 export interface WsConnectionMetadata {
   readonly connectionLabel?: string | null;
+  readonly versionMismatchHint?: string | null;
 }
 
 function normalizeConnectionLabel(label: string | null | undefined): string | null {
@@ -130,10 +131,24 @@ export function recordWsConnectionOpened(metadata?: WsConnectionMetadata): WsCon
   }));
 }
 
-export function recordWsConnectionErrored(message?: string | null): WsConnectionStatus {
+function appendHint(message: string | null | undefined, hint: string | null | undefined) {
+  const normalizedMessage = message?.trim();
+  const normalizedHint = hint?.trim();
+  if (!normalizedMessage) {
+    return normalizedHint ? `Hint: ${normalizedHint}` : null;
+  }
+  return normalizedHint ? `${normalizedMessage} Hint: ${normalizedHint}` : normalizedMessage;
+}
+
+export function recordWsConnectionErrored(
+  message?: string | null,
+  metadata?: WsConnectionMetadata,
+): WsConnectionStatus {
   return updateWsConnectionStatus((current) =>
     applyDisconnectState(current, {
-      lastError: message?.trim() ? message : current.lastError,
+      lastError:
+        appendHint(message, metadata?.versionMismatchHint) ??
+        appendHint(current.lastError, metadata?.versionMismatchHint),
       lastErrorAt: isoNow(),
     }),
   );
@@ -152,7 +167,9 @@ export function recordWsConnectionClosed(
       current,
       {
         closeCode: details?.code ?? current.closeCode,
-        closeReason: details?.reason?.trim() ? details.reason : current.closeReason,
+        closeReason:
+          appendHint(details?.reason, metadata?.versionMismatchHint) ??
+          appendHint(current.closeReason, metadata?.versionMismatchHint),
       },
       connectionLabel === null ? undefined : { connectionLabel },
     ),
diff --git a/apps/web/src/versionSkew.test.ts b/apps/web/src/versionSkew.test.ts
new file mode 100644
index 00000000000..e6debf26953
--- /dev/null
+++ b/apps/web/src/versionSkew.test.ts
@@ -0,0 +1,52 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vitest";
+
+import { APP_VERSION } from "./branding";
+import {
+  appendVersionMismatchHint,
+  resolveServerConfigVersionMismatch,
+  resolveVersionMismatch,
+} from "./versionSkew";
+
+describe("versionSkew", () => {
+  it("does not warn when versions match", () => {
+    expect(resolveVersionMismatch(APP_VERSION)).toBeNull();
+  });
+
+  it("returns a mismatch when the server version differs from the client", () => {
+    expect(resolveVersionMismatch("9.9.9")).toEqual({
+      clientVersion: APP_VERSION,
+      serverVersion: "9.9.9",
+      hint: "Version mismatch. Try syncing the client and server to the same T3 Code version.",
+    });
+  });
+
+  it("reads the server version from config descriptors", () => {
+    expect(
+      resolveServerConfigVersionMismatch({
+        environment: {
+          environmentId: EnvironmentId.make("environment-1"),
+          label: "Remote",
+          platform: {
+            os: "darwin",
+            arch: "arm64",
+          },
+          serverVersion: "9.9.9",
+          capabilities: {
+            repositoryIdentity: true,
+          },
+        },
+      }),
+    ).toMatchObject({
+      serverVersion: "9.9.9",
+    });
+  });
+
+  it("appends a hint to connection errors when versions differ", () => {
+    const mismatch = resolveVersionMismatch("9.9.9");
+
+    expect(appendVersionMismatchHint("Socket closed.", mismatch)).toBe(
+      "Socket closed. Hint: Version mismatch. Try syncing the client and server to the same T3 Code version.",
+    );
+  });
+});
diff --git a/apps/web/src/versionSkew.ts b/apps/web/src/versionSkew.ts
new file mode 100644
index 00000000000..311afddcf7f
--- /dev/null
+++ b/apps/web/src/versionSkew.ts
@@ -0,0 +1,54 @@
+import type { ServerConfig } from "@t3tools/contracts";
+
+import { APP_VERSION } from "./branding";
+
+export interface VersionMismatch {
+  readonly clientVersion: string;
+  readonly serverVersion: string;
+  readonly hint: string;
+}
+
+function normalizeVersion(version: string | null | undefined): string | null {
+  const trimmed = version?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : null;
+}
+
+export function resolveVersionMismatch(
+  serverVersion: string | null | undefined,
+): VersionMismatch | null {
+  const normalizedClientVersion = normalizeVersion(APP_VERSION);
+  const normalizedServerVersion = normalizeVersion(serverVersion);
+  if (
+    !normalizedClientVersion ||
+    !normalizedServerVersion ||
+    normalizedClientVersion === normalizedServerVersion
+  ) {
+    return null;
+  }
+
+  return {
+    clientVersion: normalizedClientVersion,
+    serverVersion: normalizedServerVersion,
+    hint: "Version mismatch. Try syncing the client and server to the same T3 Code version.",
+  };
+}
+
+export function resolveServerConfigVersionMismatch(
+  serverConfig: Pick<ServerConfig, "environment"> | null | undefined,
+): VersionMismatch | null {
+  return resolveVersionMismatch(serverConfig?.environment.serverVersion);
+}
+
+export function appendVersionMismatchHint(
+  message: string | null | undefined,
+  mismatch: VersionMismatch | null | undefined,
+): string | null {
+  const normalizedMessage = normalizeVersion(message);
+  if (!normalizedMessage) {
+    return mismatch?.hint ?? null;
+  }
+  if (!mismatch) {
+    return normalizedMessage;
+  }
+  return `${normalizedMessage} Hint: ${mismatch.hint}`;
+}

From b177f59b16cb04d671a7e423bddd5e57d5e0f0fc Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 16:54:40 -0700
Subject: [PATCH 49/74] Animate composer banner dismissals

- Add exit transitions for stacked composer banners
- Layer composer above the banner stack to keep it clickable
- Read the web app version from `import.meta.env.APP_VERSION`
---
 apps/web/src/branding.ts                      |   2 +-
 apps/web/src/components/ChatView.tsx          | 146 +++++++++---------
 .../components/chat/ComposerBannerStack.tsx   |  99 +++++++++++-
 3 files changed, 168 insertions(+), 79 deletions(-)

diff --git a/apps/web/src/branding.ts b/apps/web/src/branding.ts
index 061d5b78a8a..99775a4c55d 100644
--- a/apps/web/src/branding.ts
+++ b/apps/web/src/branding.ts
@@ -15,4 +15,4 @@ export const APP_STAGE_LABEL =
   injectedDesktopAppBranding?.stageLabel ?? (import.meta.env.DEV ? "Dev" : "Alpha");
 export const APP_DISPLAY_NAME =
   injectedDesktopAppBranding?.displayName ?? `${APP_BASE_NAME} (${APP_STAGE_LABEL})`;
-export const APP_VERSION = "0.0.20"; // import.meta.env.APP_VERSION || "0.0.0";
+export const APP_VERSION = import.meta.env.APP_VERSION || "0.0.0";
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 7cdc2f2db24..13488e254d9 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -3564,76 +3564,82 @@ export default function ChatView(props: ChatViewProps) {
                 : "pb-[calc(env(safe-area-inset-bottom)+0.75rem)] sm:pb-[calc(env(safe-area-inset-bottom)+1rem)]",
             )}
           >
-            <ComposerBannerStack items={composerBannerItems} />
-            <ChatComposer
-              ref={composerRef}
-              composerDraftTarget={composerDraftTarget}
-              environmentId={environmentId}
-              routeKind={routeKind}
-              routeThreadRef={routeThreadRef}
-              draftId={draftId}
-              activeThreadId={activeThreadId}
-              activeThreadEnvironmentId={activeThread?.environmentId}
-              activeThread={activeThread}
-              isServerThread={isServerThread}
-              isLocalDraftThread={isLocalDraftThread}
-              phase={phase}
-              isConnecting={isConnecting}
-              isSendBusy={isSendBusy}
-              isPreparingWorktree={isPreparingWorktree}
-              environmentUnavailable={activeEnvironmentUnavailableState}
-              activePendingApproval={activePendingApproval}
-              pendingApprovals={pendingApprovals}
-              pendingUserInputs={pendingUserInputs}
-              activePendingProgress={activePendingProgress}
-              activePendingResolvedAnswers={activePendingResolvedAnswers}
-              activePendingIsResponding={activePendingIsResponding}
-              activePendingDraftAnswers={activePendingDraftAnswers}
-              activePendingQuestionIndex={activePendingQuestionIndex}
-              respondingRequestIds={respondingRequestIds}
-              showPlanFollowUpPrompt={showPlanFollowUpPrompt}
-              activeProposedPlan={activeProposedPlan}
-              activePlan={activePlan as { turnId?: TurnId } | null}
-              sidebarProposedPlan={sidebarProposedPlan as { turnId?: TurnId } | null}
-              planSidebarLabel={planSidebarLabel}
-              planSidebarOpen={planSidebarOpen}
-              runtimeMode={runtimeMode}
-              interactionMode={interactionMode}
-              lockedProvider={lockedProvider}
-              providerStatuses={providerStatuses as ServerProvider[]}
-              activeProjectDefaultModelSelection={activeProject?.defaultModelSelection}
-              activeThreadModelSelection={activeThread?.modelSelection}
-              activeThreadActivities={activeThread?.activities}
-              resolvedTheme={resolvedTheme}
-              settings={settings}
-              keybindings={keybindings}
-              terminalOpen={Boolean(terminalState.terminalOpen)}
-              gitCwd={gitCwd}
-              promptRef={promptRef}
-              composerImagesRef={composerImagesRef}
-              composerTerminalContextsRef={composerTerminalContextsRef}
-              shouldAutoScrollRef={isAtEndRef}
-              scheduleStickToBottom={scrollToEnd}
-              onSend={onSend}
-              onInterrupt={onInterrupt}
-              onImplementPlanInNewThread={onImplementPlanInNewThread}
-              onRespondToApproval={onRespondToApproval}
-              onSelectActivePendingUserInputOption={onSelectActivePendingUserInputOption}
-              onAdvanceActivePendingUserInput={onAdvanceActivePendingUserInput}
-              onPreviousActivePendingUserInputQuestion={onPreviousActivePendingUserInputQuestion}
-              onChangeActivePendingUserInputCustomAnswer={
-                onChangeActivePendingUserInputCustomAnswer
-              }
-              onProviderModelSelect={onProviderModelSelect}
-              toggleInteractionMode={toggleInteractionMode}
-              handleRuntimeModeChange={handleRuntimeModeChange}
-              handleInteractionModeChange={handleInteractionModeChange}
-              togglePlanSidebar={togglePlanSidebar}
-              focusComposer={focusComposer}
-              scheduleComposerFocus={scheduleComposerFocus}
-              setThreadError={setThreadError}
-              onExpandImage={onExpandTimelineImage}
-            />
+            <div className="relative isolate">
+              <ComposerBannerStack className="relative z-0" items={composerBannerItems} />
+              <div className="relative z-10">
+                <ChatComposer
+                  ref={composerRef}
+                  composerDraftTarget={composerDraftTarget}
+                  environmentId={environmentId}
+                  routeKind={routeKind}
+                  routeThreadRef={routeThreadRef}
+                  draftId={draftId}
+                  activeThreadId={activeThreadId}
+                  activeThreadEnvironmentId={activeThread?.environmentId}
+                  activeThread={activeThread}
+                  isServerThread={isServerThread}
+                  isLocalDraftThread={isLocalDraftThread}
+                  phase={phase}
+                  isConnecting={isConnecting}
+                  isSendBusy={isSendBusy}
+                  isPreparingWorktree={isPreparingWorktree}
+                  environmentUnavailable={activeEnvironmentUnavailableState}
+                  activePendingApproval={activePendingApproval}
+                  pendingApprovals={pendingApprovals}
+                  pendingUserInputs={pendingUserInputs}
+                  activePendingProgress={activePendingProgress}
+                  activePendingResolvedAnswers={activePendingResolvedAnswers}
+                  activePendingIsResponding={activePendingIsResponding}
+                  activePendingDraftAnswers={activePendingDraftAnswers}
+                  activePendingQuestionIndex={activePendingQuestionIndex}
+                  respondingRequestIds={respondingRequestIds}
+                  showPlanFollowUpPrompt={showPlanFollowUpPrompt}
+                  activeProposedPlan={activeProposedPlan}
+                  activePlan={activePlan as { turnId?: TurnId } | null}
+                  sidebarProposedPlan={sidebarProposedPlan as { turnId?: TurnId } | null}
+                  planSidebarLabel={planSidebarLabel}
+                  planSidebarOpen={planSidebarOpen}
+                  runtimeMode={runtimeMode}
+                  interactionMode={interactionMode}
+                  lockedProvider={lockedProvider}
+                  providerStatuses={providerStatuses as ServerProvider[]}
+                  activeProjectDefaultModelSelection={activeProject?.defaultModelSelection}
+                  activeThreadModelSelection={activeThread?.modelSelection}
+                  activeThreadActivities={activeThread?.activities}
+                  resolvedTheme={resolvedTheme}
+                  settings={settings}
+                  keybindings={keybindings}
+                  terminalOpen={Boolean(terminalState.terminalOpen)}
+                  gitCwd={gitCwd}
+                  promptRef={promptRef}
+                  composerImagesRef={composerImagesRef}
+                  composerTerminalContextsRef={composerTerminalContextsRef}
+                  shouldAutoScrollRef={isAtEndRef}
+                  scheduleStickToBottom={scrollToEnd}
+                  onSend={onSend}
+                  onInterrupt={onInterrupt}
+                  onImplementPlanInNewThread={onImplementPlanInNewThread}
+                  onRespondToApproval={onRespondToApproval}
+                  onSelectActivePendingUserInputOption={onSelectActivePendingUserInputOption}
+                  onAdvanceActivePendingUserInput={onAdvanceActivePendingUserInput}
+                  onPreviousActivePendingUserInputQuestion={
+                    onPreviousActivePendingUserInputQuestion
+                  }
+                  onChangeActivePendingUserInputCustomAnswer={
+                    onChangeActivePendingUserInputCustomAnswer
+                  }
+                  onProviderModelSelect={onProviderModelSelect}
+                  toggleInteractionMode={toggleInteractionMode}
+                  handleRuntimeModeChange={handleRuntimeModeChange}
+                  handleInteractionModeChange={handleInteractionModeChange}
+                  togglePlanSidebar={togglePlanSidebar}
+                  focusComposer={focusComposer}
+                  scheduleComposerFocus={scheduleComposerFocus}
+                  setThreadError={setThreadError}
+                  onExpandImage={onExpandTimelineImage}
+                />
+              </div>
+            </div>
             {isGitRepo && (
               <BranchToolbar
                 environmentId={activeThread.environmentId}
diff --git a/apps/web/src/components/chat/ComposerBannerStack.tsx b/apps/web/src/components/chat/ComposerBannerStack.tsx
index 693bda1b526..c59c251ab7c 100644
--- a/apps/web/src/components/chat/ComposerBannerStack.tsx
+++ b/apps/web/src/components/chat/ComposerBannerStack.tsx
@@ -1,10 +1,28 @@
-import type { ReactNode } from "react";
+import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from "react";
 import { XIcon } from "lucide-react";
 
 import { cn } from "~/lib/utils";
 import { Alert, AlertAction, AlertDescription, AlertTitle } from "../ui/alert";
 import { Button } from "../ui/button";
 
+const DISMISS_TRANSITION_MS = 220;
+const frontExitStyle = {
+  opacity: 0,
+  transform: "translate3d(0, 4rem, 0)",
+} satisfies CSSProperties;
+const stackedExitStyle = {
+  opacity: 0,
+  transform: "translate3d(0, 7rem, 0)",
+} satisfies CSSProperties;
+const restingStyle = {
+  opacity: 1,
+  transform: "translate3d(0, 0, 0)",
+} satisfies CSSProperties;
+const exitTransitionStyle = {
+  transition: `transform ${DISMISS_TRANSITION_MS}ms ease-in, opacity ${DISMISS_TRANSITION_MS}ms ease-in`,
+  willChange: "transform, opacity",
+} satisfies CSSProperties;
+
 export interface ComposerBannerStackItem {
   readonly id: string;
   readonly variant: "error" | "info" | "success" | "warning";
@@ -22,6 +40,23 @@ interface ComposerBannerStackProps {
 }
 
 export function ComposerBannerStack({ className, items }: ComposerBannerStackProps) {
+  const [exitingItemId, setExitingItemId] = useState<string | null>(null);
+  const dismissTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => {
+    if (exitingItemId && !items.some((item) => item.id === exitingItemId)) {
+      setExitingItemId(null);
+    }
+  }, [exitingItemId, items]);
+
+  useEffect(() => {
+    return () => {
+      if (dismissTimeoutRef.current) {
+        clearTimeout(dismissTimeoutRef.current);
+      }
+    };
+  }, []);
+
   if (items.length === 0) {
     return null;
   }
@@ -32,6 +67,21 @@ export function ComposerBannerStack({ className, items }: ComposerBannerStackPro
   }
   const stackedItems = items.slice(1);
   const hasStack = stackedItems.length > 0;
+  const showCollapsedStackCap = hasStack && exitingItemId !== frontItem.id;
+
+  const requestDismiss = (item: ComposerBannerStackItem) => {
+    if (!item.onDismiss || exitingItemId) {
+      return;
+    }
+    setExitingItemId(item.id);
+    if (dismissTimeoutRef.current) {
+      clearTimeout(dismissTimeoutRef.current);
+    }
+    dismissTimeoutRef.current = setTimeout(() => {
+      dismissTimeoutRef.current = null;
+      item.onDismiss?.();
+    }, DISMISS_TRANSITION_MS);
+  };
 
   return (
     <div className={cn("group/banner-stack mx-auto mb-2 max-w-208", className)}>
@@ -41,7 +91,7 @@ export function ComposerBannerStack({ className, items }: ComposerBannerStackPro
           hasStack ? "group-hover/banner-stack:z-50 group-focus-within/banner-stack:z-50" : null,
         )}
       >
-        {hasStack ? (
+        {showCollapsedStackCap ? (
           <div
             className={cn(
               "pointer-events-none absolute inset-x-0 -top-3 z-0 mx-auto h-3 rounded-t-xl",
@@ -53,8 +103,21 @@ export function ComposerBannerStack({ className, items }: ComposerBannerStackPro
             aria-hidden="true"
           />
         ) : null}
-        <div className="relative z-10">
-          <ComposerBannerStackAlert item={frontItem} />
+        <div
+          className={cn(
+            "relative z-10",
+            exitingItemId === frontItem.id ? "pointer-events-none" : null,
+          )}
+          style={{
+            ...exitTransitionStyle,
+            ...(exitingItemId === frontItem.id ? frontExitStyle : restingStyle),
+          }}
+        >
+          <ComposerBannerStackAlert
+            item={frontItem}
+            exiting={exitingItemId === frontItem.id}
+            onDismissRequest={() => requestDismiss(frontItem)}
+          />
         </div>
         {hasStack ? (
           <div
@@ -67,8 +130,19 @@ export function ComposerBannerStack({ className, items }: ComposerBannerStackPro
             )}
           >
             {stackedItems.map((item) => (
-              <div key={item.id}>
-                <ComposerBannerStackAlert item={item} />
+              <div
+                key={item.id}
+                className={cn(exitingItemId === item.id ? "pointer-events-none" : null)}
+                style={{
+                  ...exitTransitionStyle,
+                  ...(exitingItemId === item.id ? stackedExitStyle : restingStyle),
+                }}
+              >
+                <ComposerBannerStackAlert
+                  item={item}
+                  exiting={exitingItemId === item.id}
+                  onDismissRequest={() => requestDismiss(item)}
+                />
               </div>
             ))}
           </div>
@@ -78,7 +152,15 @@ export function ComposerBannerStack({ className, items }: ComposerBannerStackPro
   );
 }
 
-function ComposerBannerStackAlert({ item }: { readonly item: ComposerBannerStackItem }) {
+function ComposerBannerStackAlert({
+  item,
+  exiting,
+  onDismissRequest,
+}: {
+  readonly item: ComposerBannerStackItem;
+  readonly exiting: boolean;
+  readonly onDismissRequest: () => void;
+}) {
   return (
     <Alert variant={item.variant}>
       {item.icon}
@@ -92,7 +174,8 @@ function ComposerBannerStackAlert({ item }: { readonly item: ComposerBannerStack
               size="icon-xs"
               variant="ghost"
               aria-label={item.dismissLabel ?? "Dismiss warning"}
-              onClick={item.onDismiss}
+              disabled={exiting}
+              onClick={onDismissRequest}
             >
               <XIcon className="size-3.5" />
             </Button>

From 6747e7fdd82a2994702066e2895ee6ef98560c9a Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 18:01:40 -0700
Subject: [PATCH 50/74] Handle missing hosted pairing config and disable
 tailscale serve

- Show an error state when the hosted pairing link lacks backend data
- Switch Tailscale cleanup to `serve --https=<port> off` and update tests
---
 .../components/auth/PairingRouteSurface.tsx   | 10 ++++--
 packages/tailscale/src/tailscale.test.ts      | 11 ++-----
 packages/tailscale/src/tailscale.ts           | 32 +++----------------
 3 files changed, 15 insertions(+), 38 deletions(-)

diff --git a/apps/web/src/components/auth/PairingRouteSurface.tsx b/apps/web/src/components/auth/PairingRouteSurface.tsx
index 3e5493771eb..4ae7b6574c0 100644
--- a/apps/web/src/components/auth/PairingRouteSurface.tsx
+++ b/apps/web/src/components/auth/PairingRouteSurface.tsx
@@ -163,8 +163,14 @@ export function PairingRouteSurface({
 
 export function HostedPairingRouteSurface() {
   const hostedPairingRequestRef = useRef(readHostedPairingRequest());
-  const [status, setStatus] = useState<"pairing" | "paired" | "error">("pairing");
-  const [message, setMessage] = useState("Connecting to this backend.");
+  const [status, setStatus] = useState<"pairing" | "paired" | "error">(() =>
+    hostedPairingRequestRef.current ? "pairing" : "error",
+  );
+  const [message, setMessage] = useState(() =>
+    hostedPairingRequestRef.current
+      ? "Connecting to this backend."
+      : "This pairing link is missing its backend host or token.",
+  );
   const submitAttemptedRef = useRef(false);
   const tokenSubmittedRef = useRef(false);
 
diff --git a/packages/tailscale/src/tailscale.test.ts b/packages/tailscale/src/tailscale.test.ts
index cd4ddbb7c92..149525a03f4 100644
--- a/packages/tailscale/src/tailscale.test.ts
+++ b/packages/tailscale/src/tailscale.test.ts
@@ -127,21 +127,14 @@ describe("tailscale", () => {
     const layer = mockSpawnerLayer((command, args) => {
       commands.push({ command, args });
       assert.equal(command, "tailscale");
-      if (args[0] === "status") {
-        assert.deepEqual(args, ["status", "--json"]);
-        return {
-          stdout: tailscaleStatusJson,
-        };
-      }
-      assert.deepEqual(args, ["serve", "clear", "desktop.tail.ts.net:8443"]);
+      assert.deepEqual(args, ["serve", "--https=8443", "off"]);
       return {};
     });
 
     return Effect.gen(function* () {
       yield* disableTailscaleServe({ servePort: 8443 }).pipe(Effect.provide(layer));
       assert.deepEqual(commands, [
-        { command: "tailscale", args: ["status", "--json"] },
-        { command: "tailscale", args: ["serve", "clear", "desktop.tail.ts.net:8443"] },
+        { command: "tailscale", args: ["serve", "--https=8443", "off"] },
       ]);
     });
   });
diff --git a/packages/tailscale/src/tailscale.ts b/packages/tailscale/src/tailscale.ts
index f7b6c4ed569..e90299d3ac1 100644
--- a/packages/tailscale/src/tailscale.ts
+++ b/packages/tailscale/src/tailscale.ts
@@ -272,33 +272,11 @@ export const disableTailscaleServe = (
 ): Effect.Effect<void, TailscaleCommandError, ChildProcessSpawner.ChildProcessSpawner> =>
   Effect.gen(function* () {
     const servePort = input.servePort ?? DEFAULT_TAILSCALE_SERVE_PORT;
-    const status = yield* readTailscaleStatus.pipe(
-      Effect.mapError((error) =>
-        tailscaleCommandError(
-          ["status", "--json"],
-          "Cannot clear Tailscale Serve because status could not be read.",
-          null,
-          error instanceof Error ? error.message : String(error),
-        ),
-      ),
-    );
-    if (!status.magicDnsName) {
-      return yield* tailscaleCommandError(
-        ["serve", "clear"],
-        "Cannot clear Tailscale Serve because MagicDNS name is unavailable.",
-        null,
-      );
-    }
-
-    const service =
-      servePort === DEFAULT_TAILSCALE_SERVE_PORT
-        ? status.magicDnsName
-        : `${status.magicDnsName}:${servePort}`;
-    return yield* runTailscaleCommand(["serve", "clear", service], {
-      spawnMessage: "Failed to spawn tailscale serve clear.",
-      runMessage: "Failed to run tailscale serve clear.",
-      exitMessage: (exitCode) => `Tailscale serve clear exited with code ${exitCode}.`,
-      timeoutMessage: "Tailscale serve clear timed out.",
+    return yield* runTailscaleCommand(["serve", `--https=${servePort}`, "off"], {
+      spawnMessage: "Failed to spawn tailscale serve off.",
+      runMessage: "Failed to run tailscale serve off.",
+      exitMessage: (exitCode) => `Tailscale serve off exited with code ${exitCode}.`,
+      timeoutMessage: "Tailscale serve off timed out.",
       timeoutMs: TAILSCALE_SERVE_TIMEOUT_MS,
     });
   });

From 46278bbd9184f897e1e3609b547228a28d786b7b Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 18:32:13 -0700
Subject: [PATCH 51/74] Address remaining PR review feedback

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/web/src/components/ChatView.tsx          |  2 ++
 apps/web/src/components/chat/ChatComposer.tsx |  4 +++-
 .../settings/ConnectionsSettings.tsx          | 24 +++++++++++++------
 packages/ssh/src/tunnel.test.ts               | 16 ++++++++++---
 packages/ssh/src/tunnel.ts                    |  2 +-
 5 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 13488e254d9..9dfd1ac3419 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -3204,6 +3204,7 @@ export default function ChatView(props: ChatViewProps) {
       !isServerThread ||
       isSendBusy ||
       isConnecting ||
+      activeEnvironmentUnavailable ||
       sendInFlightRef.current
     ) {
       return;
@@ -3318,6 +3319,7 @@ export default function ChatView(props: ChatViewProps) {
     activeThreadBranch,
     activeThread,
     beginLocalDispatch,
+    activeEnvironmentUnavailable,
     isConnecting,
     isSendBusy,
     isServerThread,
diff --git a/apps/web/src/components/chat/ChatComposer.tsx b/apps/web/src/components/chat/ChatComposer.tsx
index 8d0ad171dba..9bc2174a043 100644
--- a/apps/web/src/components/chat/ChatComposer.tsx
+++ b/apps/web/src/components/chat/ChatComposer.tsx
@@ -1989,7 +1989,9 @@ export const ChatComposer = memo(
                             : "Ask anything, @tag files/folders, or use / to show available commands"
                 }
                 disabled={
-                  isConnecting || isComposerApprovalState || environmentUnavailable !== null
+                  isConnecting ||
+                  isComposerApprovalState ||
+                  (environmentUnavailable !== null && activePendingProgress === null)
                 }
               />
             </div>
diff --git a/apps/web/src/components/settings/ConnectionsSettings.tsx b/apps/web/src/components/settings/ConnectionsSettings.tsx
index 54d8575410e..fe0a0cb5816 100644
--- a/apps/web/src/components/settings/ConnectionsSettings.tsx
+++ b/apps/web/src/components/settings/ConnectionsSettings.tsx
@@ -190,11 +190,26 @@ function AnimatedHeight({ children }: { readonly children: ReactNode }) {
       const nextHeight = Math.ceil(element.scrollHeight || element.getBoundingClientRect().height);
       setHeight((currentHeight) => (currentHeight === nextHeight ? currentHeight : nextHeight));
     };
+    const cancelPendingFrames = () => {
+      if (firstFrameId !== null) {
+        window.cancelAnimationFrame(firstFrameId);
+        firstFrameId = null;
+      }
+      if (secondFrameId !== null) {
+        window.cancelAnimationFrame(secondFrameId);
+        secondFrameId = null;
+      }
+    };
     const updateHeightAfterPaint = () => {
+      cancelPendingFrames();
       updateHeight();
       firstFrameId = window.requestAnimationFrame(() => {
+        firstFrameId = null;
         updateHeight();
-        secondFrameId = window.requestAnimationFrame(updateHeight);
+        secondFrameId = window.requestAnimationFrame(() => {
+          secondFrameId = null;
+          updateHeight();
+        });
       });
     };
 
@@ -203,12 +218,7 @@ function AnimatedHeight({ children }: { readonly children: ReactNode }) {
     resizeObserver.observe(element);
     return () => {
       resizeObserver.disconnect();
-      if (firstFrameId !== null) {
-        window.cancelAnimationFrame(firstFrameId);
-      }
-      if (secondFrameId !== null) {
-        window.cancelAnimationFrame(secondFrameId);
-      }
+      cancelPendingFrames();
     };
   }, []);
 
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 0ca49907571..4df9e4dd1af 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -84,9 +84,19 @@ describe("ssh tunnel scripts", () => {
 
     assert.include(script, "T3_NODE_SCRIPT_PATH=''");
     assert.include(script, 'exec t3 "$@"');
-    assert.include(script, 'exec npx --yes t3@latest "$@"');
-    assert.include(script, 'exec npm exec --yes t3@latest -- "$@"');
-    assert.include(script, "could not install t3@latest");
+    assert.include(script, "exec npx --yes 't3@latest' \"$@\"");
+    assert.include(script, "exec npm exec --yes 't3@latest' -- \"$@\"");
+    assert.include(script, "could not install 't3@latest'");
+  });
+
+  it("shell-quotes package specs in the remote t3 runner", () => {
+    const script = buildRemoteT3RunnerScript({
+      packageSpec: "t3@nightly; touch /tmp/t3-owned",
+    });
+
+    assert.include(script, "exec npx --yes 't3@nightly; touch /tmp/t3-owned' \"$@\"");
+    assert.include(script, "exec npm exec --yes 't3@nightly; touch /tmp/t3-owned' -- \"$@\"");
+    assert.notInclude(script, "exec npx --yes t3@nightly; touch /tmp/t3-owned");
   });
 
   it("builds the remote t3 runner with a node script override", () => {
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index aef361d41a6..9ac4f220ac8 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -439,7 +439,7 @@ fi
 `;
 
 export function buildRemoteT3RunnerScript(input?: RemoteT3RunnerOptions): string {
-  const packageSpec = input?.packageSpec?.trim() || "t3@latest";
+  const packageSpec = shellSingleQuote(input?.packageSpec?.trim() || "t3@latest");
   const nodeScriptPath = input?.nodeScriptPath?.trim() || "";
   return stripTrailingNewlines(
     applyScriptPlaceholders(REMOTE_RUNNER_SCRIPT, {

From 27be1e1591e79b3211443bd7e9fc5c8a70143729 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 18:53:45 -0700
Subject: [PATCH 52/74] Reuse live remote T3 server for SSH launch

Co-authored-by: codex <codex@users.noreply.github.com>
---
 packages/ssh/src/tunnel.test.ts | 22 +++++++++-
 packages/ssh/src/tunnel.ts      | 71 ++++++++++++++++++++++++++++++---
 2 files changed, 86 insertions(+), 7 deletions(-)

diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 4df9e4dd1af..03d980fccb0 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -131,11 +131,29 @@ describe("ssh tunnel scripts", () => {
     assert.include(buildRemoteLaunchScript({ packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
       buildRemotePairingScript(target),
-      '"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json',
+      '"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json',
     );
+    assert.include(buildRemotePairingScript(target), 'BASE_DIR_FILE="$STATE_DIR/base-dir"');
     assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
+    assert.include(
+      buildRemoteStopScript(target),
+      'if [ "$REMOTE_MANAGED" != "external" ] && [ -n "$REMOTE_PID" ]',
+    );
     assert.include(buildRemoteStopScript(target), 'kill "$REMOTE_PID" 2>/dev/null || true');
-    assert.include(buildRemoteStopScript(target), 'rm -f "$PID_FILE" "$PORT_FILE"');
+    assert.include(
+      buildRemoteStopScript(target),
+      'rm -f "$PID_FILE" "$PORT_FILE" "$BASE_DIR_FILE" "$MANAGED_FILE"',
+    );
+    assert.include(
+      buildRemoteLaunchScript(),
+      'DEFAULT_RUNTIME_FILE="$DEFAULT_SERVER_HOME/userdata/server-runtime.json"',
+    );
+    assert.include(buildRemoteLaunchScript(), "resolve_default_runtime_port()");
+    assert.include(buildRemoteLaunchScript(), "printf 'external\\n' >\"$MANAGED_FILE\"");
+    assert.isBelow(
+      buildRemoteLaunchScript().indexOf('DEFAULT_REMOTE_PORT="$(resolve_default_runtime_port'),
+      buildRemoteLaunchScript().indexOf('elif [ -n "$REMOTE_PID" ]'),
+    );
   });
 
   it("allows the remote port picker to run without a state file path", () => {
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 9ac4f220ac8..e54faba2fd8 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -324,8 +324,12 @@ export const REMOTE_LAUNCH_SCRIPT = `set -eu
 STATE_KEY="$1"
 STATE_DIR="$HOME/.t3/ssh-launch/$STATE_KEY"
 SERVER_HOME="$STATE_DIR/server-home"
+DEFAULT_SERVER_HOME="$HOME/.t3"
+DEFAULT_RUNTIME_FILE="$DEFAULT_SERVER_HOME/userdata/server-runtime.json"
 PORT_FILE="$STATE_DIR/port"
 PID_FILE="$STATE_DIR/pid"
+BASE_DIR_FILE="$STATE_DIR/base-dir"
+MANAGED_FILE="$STATE_DIR/managed"
 LOG_FILE="$STATE_DIR/server.log"
 RUNNER_FILE="$STATE_DIR/run-t3.sh"
 RUNNER_NEXT="$STATE_DIR/run-t3.next.$$"
@@ -361,23 +365,70 @@ wait_for_pid_exit() {
     sleep 0.1
   done
 }
+resolve_default_runtime_port() {
+  node - "$DEFAULT_RUNTIME_FILE" <<'NODE'
+const fs = require("node:fs");
+const runtimePath = process.argv[2] ?? "";
+try {
+  const runtime = JSON.parse(fs.readFileSync(runtimePath, "utf8"));
+  const pid = Number(runtime.pid);
+  const port = Number(runtime.port);
+  if (!Number.isInteger(pid) || !Number.isInteger(port)) {
+    process.exit(1);
+  }
+  const origin = new URL(String(runtime.origin ?? ""));
+  if (origin.protocol !== "http:" || !["127.0.0.1", "localhost"].includes(origin.hostname)) {
+    process.exit(1);
+  }
+  process.kill(pid, 0);
+  process.stdout.write(String(port));
+} catch {
+  process.exit(1);
+}
+NODE
+}
 REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
 REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
-if [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
+DEFAULT_REMOTE_PORT="$(resolve_default_runtime_port 2>/dev/null || true)"
+if [ -n "$DEFAULT_REMOTE_PORT" ]; then
+  REMOTE_PORT="$DEFAULT_REMOTE_PORT"
+  if wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
+    printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+    printf '%s\\n' "$DEFAULT_SERVER_HOME" >"$BASE_DIR_FILE"
+    printf 'external\\n' >"$MANAGED_FILE"
+    REMOTE_PID=""
+    REMOTE_MANAGED="external"
+  else
+    REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
+    REMOTE_PORT="$(cat "$PORT_FILE" 2>/dev/null || true)"
+    REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
+  fi
+fi
+if [ "$REMOTE_MANAGED" = "external" ]; then
+  if [ -z "$REMOTE_PORT" ] || ! wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
+    REMOTE_PID=""
+    REMOTE_PORT=""
+    REMOTE_MANAGED=""
+  fi
+elif [ -n "$REMOTE_PID" ] && [ -n "$REMOTE_PORT" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
   if [ "$RUNNER_CHANGED" -eq 1 ]; then
     kill "$REMOTE_PID" 2>/dev/null || true
     wait_for_pid_exit "$REMOTE_PID"
     REMOTE_PID=""
     REMOTE_PORT=""
+    REMOTE_MANAGED=""
   elif ! wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
     kill "$REMOTE_PID" 2>/dev/null || true
     wait_for_pid_exit "$REMOTE_PID"
     REMOTE_PID=""
     REMOTE_PORT=""
+    REMOTE_MANAGED=""
   fi
 else
   REMOTE_PID=""
   REMOTE_PORT=""
+  REMOTE_MANAGED=""
 fi
 if [ -z "$REMOTE_PID" ] || [ -z "$REMOTE_PORT" ]; then
   REMOTE_PORT="$(pick_port)" || true
@@ -389,12 +440,14 @@ if [ -z "$REMOTE_PID" ] || [ -z "$REMOTE_PORT" ]; then
   REMOTE_PID="$!"
   printf '%s\\n' "$REMOTE_PID" >"$PID_FILE"
   printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
+  printf '%s\\n' "$SERVER_HOME" >"$BASE_DIR_FILE"
+  printf 'managed\\n' >"$MANAGED_FILE"
   if ! wait_ready "@@T3_READY_TIMEOUT_MS@@"; then
     printf 'Remote T3 server did not become ready on 127.0.0.1:%s.\\n' "$REMOTE_PORT" >&2
     tail -n 80 "$LOG_FILE" >&2 2>/dev/null || true
     kill "$REMOTE_PID" 2>/dev/null || true
     wait_for_pid_exit "$REMOTE_PID"
-    rm -f "$PID_FILE" "$PORT_FILE"
+    rm -f "$PID_FILE" "$PORT_FILE" "$BASE_DIR_FILE" "$MANAGED_FILE"
     exit 1
   fi
 fi
@@ -404,21 +457,29 @@ printf '{"remotePort":%s}\\n' "$REMOTE_PORT"
 export const REMOTE_PAIRING_SCRIPT = `set -eu
 STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
 SERVER_HOME="$STATE_DIR/server-home"
+BASE_DIR_FILE="$STATE_DIR/base-dir"
 RUNNER_FILE="$STATE_DIR/run-t3.sh"
 mkdir -p "$STATE_DIR" "$SERVER_HOME"
 cat >"$RUNNER_FILE" <<'SH'
 @@T3_RUNNER_SCRIPT@@
 SH
 chmod 700 "$RUNNER_FILE"
-"$RUNNER_FILE" auth pairing create --base-dir "$SERVER_HOME" --json
+PAIRING_BASE_DIR="$(cat "$BASE_DIR_FILE" 2>/dev/null || true)"
+if [ -z "$PAIRING_BASE_DIR" ]; then
+  PAIRING_BASE_DIR="$SERVER_HOME"
+fi
+"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json
 `;
 
 export const REMOTE_STOP_SCRIPT = `set -eu
 STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
 PID_FILE="$STATE_DIR/pid"
 PORT_FILE="$STATE_DIR/port"
+BASE_DIR_FILE="$STATE_DIR/base-dir"
+MANAGED_FILE="$STATE_DIR/managed"
+REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
 REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
-if [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+if [ "$REMOTE_MANAGED" != "external" ] && [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
   kill "$REMOTE_PID" 2>/dev/null || true
   WAIT_COUNT=0
   while kill -0 "$REMOTE_PID" 2>/dev/null && [ "$WAIT_COUNT" -lt 20 ]; do
@@ -426,7 +487,7 @@ if [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
     sleep 0.1
   done
 fi
-rm -f "$PID_FILE" "$PORT_FILE"
+rm -f "$PID_FILE" "$PORT_FILE" "$BASE_DIR_FILE" "$MANAGED_FILE"
 printf '{"stopped":true}\\n'
 `;
 

From d5f5d82878f20da31729b1d19a7c966be537cf95 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 20:13:27 -0700
Subject: [PATCH 53/74] Persist version mismatch dismissals per environment

- Store dismissed version mismatch banners in local storage
- Show the connected server label for multi-environment setups
- Cover dismissal keying with tests

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/web/src/branding.ts             |  2 +-
 apps/web/src/components/ChatView.tsx | 45 ++++++++++++++++---
 apps/web/src/versionSkew.test.ts     | 26 +++++++++++
 apps/web/src/versionSkew.ts          | 64 +++++++++++++++++++++++++++-
 4 files changed, 130 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/branding.ts b/apps/web/src/branding.ts
index 99775a4c55d..061d5b78a8a 100644
--- a/apps/web/src/branding.ts
+++ b/apps/web/src/branding.ts
@@ -15,4 +15,4 @@ export const APP_STAGE_LABEL =
   injectedDesktopAppBranding?.stageLabel ?? (import.meta.env.DEV ? "Dev" : "Alpha");
 export const APP_DISPLAY_NAME =
   injectedDesktopAppBranding?.displayName ?? `${APP_BASE_NAME} (${APP_STAGE_LABEL})`;
-export const APP_VERSION = import.meta.env.APP_VERSION || "0.0.0";
+export const APP_VERSION = "0.0.20"; // import.meta.env.APP_VERSION || "0.0.0";
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 9dfd1ac3419..0760c356cbe 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -183,7 +183,12 @@ import { sanitizeThreadErrorMessage } from "~/rpc/transportError";
 import { retainThreadDetailSubscription } from "../environments/runtime/service";
 import { RightPanelSheet } from "./RightPanelSheet";
 import { Button } from "./ui/button";
-import { resolveServerConfigVersionMismatch } from "../versionSkew";
+import {
+  buildVersionMismatchDismissalKey,
+  dismissVersionMismatch,
+  isVersionMismatchDismissed,
+  resolveServerConfigVersionMismatch,
+} from "../versionSkew";
 
 const IMAGE_ONLY_BOOTSTRAP_PROMPT =
   "[User attached one or more images without additional text. Respond using the conversation context and the attached image(s).]";
@@ -1139,13 +1144,39 @@ export default function ChatView(props: ChatViewProps) {
   const versionMismatch = resolveServerConfigVersionMismatch(serverConfig);
   const versionMismatchDismissKey =
     versionMismatch && activeThread
-      ? `${activeThread.environmentId}:${versionMismatch.clientVersion}:${versionMismatch.serverVersion}`
+      ? buildVersionMismatchDismissalKey(activeThread.environmentId, versionMismatch)
       : null;
   const [dismissedVersionMismatchKey, setDismissedVersionMismatchKey] = useState<string | null>(
     null,
   );
+  const versionMismatchDismissed =
+    versionMismatchDismissKey === dismissedVersionMismatchKey ||
+    isVersionMismatchDismissed(versionMismatchDismissKey);
   const showVersionMismatchBanner =
-    versionMismatch !== null && versionMismatchDismissKey !== dismissedVersionMismatchKey;
+    versionMismatch !== null && versionMismatchDismissKey !== null && !versionMismatchDismissed;
+  const hasMultipleRegisteredEnvironments = Object.keys(savedEnvironmentRegistry).length > 0;
+  const versionMismatchServerLabel = useMemo(() => {
+    if (!hasMultipleRegisteredEnvironments || !activeThread) {
+      return "server";
+    }
+
+    const isPrimary = activeThread.environmentId === primaryEnvironmentId;
+    const savedRecord = savedEnvironmentRegistry[activeThread.environmentId];
+    const runtimeState = savedEnvironmentRuntimeById[activeThread.environmentId];
+    return `${resolveEnvironmentOptionLabel({
+      isPrimary,
+      environmentId: activeThread.environmentId,
+      runtimeLabel: runtimeState?.descriptor?.label ?? serverConfig?.environment.label ?? null,
+      savedLabel: savedRecord?.label ?? null,
+    })} server`;
+  }, [
+    activeThread,
+    hasMultipleRegisteredEnvironments,
+    primaryEnvironmentId,
+    savedEnvironmentRegistry,
+    savedEnvironmentRuntimeById,
+    serverConfig?.environment.label,
+  ]);
   const composerBannerItems = useMemo<ComposerBannerStackItem[]>(() => {
     const items: ComposerBannerStackItem[] = [];
     if (activeEnvironmentUnavailableState) {
@@ -1202,12 +1233,15 @@ export default function ChatView(props: ChatViewProps) {
         title: "Client and server versions differ",
         description: (
           <>
-            Client {versionMismatch.clientVersion} is connected to server{" "}
+            Client {versionMismatch.clientVersion} is connected to {versionMismatchServerLabel}{" "}
             {versionMismatch.serverVersion}. Sync them if RPC calls or reconnects fail.
           </>
         ),
         dismissLabel: "Dismiss version mismatch warning",
-        onDismiss: () => setDismissedVersionMismatchKey(versionMismatchDismissKey),
+        onDismiss: () => {
+          dismissVersionMismatch(versionMismatchDismissKey);
+          setDismissedVersionMismatchKey(versionMismatchDismissKey);
+        },
       });
     }
     return items;
@@ -1219,6 +1253,7 @@ export default function ChatView(props: ChatViewProps) {
     showVersionMismatchBanner,
     versionMismatch,
     versionMismatchDismissKey,
+    versionMismatchServerLabel,
   ]);
   const providerStatuses = serverConfig?.providers ?? EMPTY_PROVIDERS;
   const unlockedSelectedProvider = resolveSelectableProvider(
diff --git a/apps/web/src/versionSkew.test.ts b/apps/web/src/versionSkew.test.ts
index e6debf26953..01c4985565a 100644
--- a/apps/web/src/versionSkew.test.ts
+++ b/apps/web/src/versionSkew.test.ts
@@ -4,6 +4,9 @@ import { describe, expect, it } from "vitest";
 import { APP_VERSION } from "./branding";
 import {
   appendVersionMismatchHint,
+  buildVersionMismatchDismissalKey,
+  dismissVersionMismatch,
+  isVersionMismatchDismissed,
   resolveServerConfigVersionMismatch,
   resolveVersionMismatch,
 } from "./versionSkew";
@@ -42,6 +45,29 @@ describe("versionSkew", () => {
     });
   });
 
+  it("keys dismissals by environment, client version, and server version", () => {
+    const environmentId = EnvironmentId.make("environment-dismissal");
+    const key = buildVersionMismatchDismissalKey(environmentId, {
+      clientVersion: APP_VERSION,
+      serverVersion: "9.9.9",
+    });
+
+    expect(key).toBe(`${environmentId}:${APP_VERSION}:9.9.9`);
+    expect(isVersionMismatchDismissed(key)).toBe(false);
+
+    dismissVersionMismatch(key);
+
+    expect(isVersionMismatchDismissed(key)).toBe(true);
+    expect(
+      isVersionMismatchDismissed(
+        buildVersionMismatchDismissalKey(environmentId, {
+          clientVersion: APP_VERSION,
+          serverVersion: "9.9.10",
+        }),
+      ),
+    ).toBe(false);
+  });
+
   it("appends a hint to connection errors when versions differ", () => {
     const mismatch = resolveVersionMismatch("9.9.9");
 
diff --git a/apps/web/src/versionSkew.ts b/apps/web/src/versionSkew.ts
index 311afddcf7f..cb0116c8550 100644
--- a/apps/web/src/versionSkew.ts
+++ b/apps/web/src/versionSkew.ts
@@ -1,6 +1,8 @@
-import type { ServerConfig } from "@t3tools/contracts";
+import type { EnvironmentId, ServerConfig } from "@t3tools/contracts";
+import * as Schema from "effect/Schema";
 
 import { APP_VERSION } from "./branding";
+import { getLocalStorageItem, setLocalStorageItem } from "./hooks/useLocalStorage";
 
 export interface VersionMismatch {
   readonly clientVersion: string;
@@ -8,6 +10,14 @@ export interface VersionMismatch {
   readonly hint: string;
 }
 
+export const VERSION_MISMATCH_DISMISSALS_STORAGE_KEY = "t3code:version-mismatch-dismissals:v1";
+
+const VersionMismatchDismissalsSchema = Schema.Struct({
+  keys: Schema.Array(Schema.String),
+});
+
+type VersionMismatchDismissals = typeof VersionMismatchDismissalsSchema.Type;
+
 function normalizeVersion(version: string | null | undefined): string | null {
   const trimmed = version?.trim();
   return trimmed && trimmed.length > 0 ? trimmed : null;
@@ -39,6 +49,58 @@ export function resolveServerConfigVersionMismatch(
   return resolveVersionMismatch(serverConfig?.environment.serverVersion);
 }
 
+export function buildVersionMismatchDismissalKey(
+  environmentId: EnvironmentId,
+  mismatch: Pick<VersionMismatch, "clientVersion" | "serverVersion">,
+): string {
+  return `${environmentId}:${mismatch.clientVersion}:${mismatch.serverVersion}`;
+}
+
+function readVersionMismatchDismissals(): VersionMismatchDismissals {
+  try {
+    return (
+      getLocalStorageItem(
+        VERSION_MISMATCH_DISMISSALS_STORAGE_KEY,
+        VersionMismatchDismissalsSchema,
+      ) ?? { keys: [] }
+    );
+  } catch {
+    return { keys: [] };
+  }
+}
+
+function writeVersionMismatchDismissals(document: VersionMismatchDismissals): void {
+  try {
+    setLocalStorageItem(
+      VERSION_MISMATCH_DISMISSALS_STORAGE_KEY,
+      document,
+      VersionMismatchDismissalsSchema,
+    );
+  } catch {
+    // Dismissal state is best-effort UI state; a storage failure should not block the banner.
+  }
+}
+
+export function isVersionMismatchDismissed(dismissalKey: string | null | undefined): boolean {
+  if (!dismissalKey) {
+    return false;
+  }
+  return readVersionMismatchDismissals().keys.includes(dismissalKey);
+}
+
+export function dismissVersionMismatch(dismissalKey: string | null | undefined): void {
+  if (!dismissalKey) {
+    return;
+  }
+  const document = readVersionMismatchDismissals();
+  if (document.keys.includes(dismissalKey)) {
+    return;
+  }
+  writeVersionMismatchDismissals({
+    keys: [...document.keys, dismissalKey],
+  });
+}
+
 export function appendVersionMismatchHint(
   message: string | null | undefined,
   mismatch: VersionMismatch | null | undefined,

From 2a220f16485ad40b999110dbf4ddcbd88cf91689 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 20:14:50 -0700
Subject: [PATCH 54/74] Format desktop main process entrypoint

- Reflow long imports and IPC handlers
- Keep desktop main.ts consistent with project formatting
---
 apps/desktop/src/main.ts | 587 +++++++++++++++++++++++++++------------
 1 file changed, 409 insertions(+), 178 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 9c097fc9bd1..920453756fe 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -37,7 +37,10 @@ import type { ContextMenuItem } from "@t3tools/contracts";
 import { RotatingFileSink } from "@t3tools/shared/logging";
 import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
 import type { RemoteT3RunnerOptions } from "@t3tools/ssh/tunnel";
-import { DEFAULT_DESKTOP_BACKEND_PORT, resolveDesktopBackendPort } from "./backendPort.ts";
+import {
+  DEFAULT_DESKTOP_BACKEND_PORT,
+  resolveDesktopBackendPort,
+} from "./backendPort.ts";
 import {
   type DesktopSettings,
   DEFAULT_DESKTOP_SETTINGS,
@@ -56,16 +59,25 @@ import {
   writeSavedEnvironmentRegistry,
   writeSavedEnvironmentSecret,
 } from "./clientPersistence.ts";
-import { isBackendReadinessAborted, waitForHttpReady } from "./backendReadiness.ts";
+import {
+  isBackendReadinessAborted,
+  waitForHttpReady,
+} from "./backendReadiness.ts";
 import { showDesktopConfirmDialog } from "./confirmDialog.ts";
 import {
   resolveDesktopCoreAdvertisedEndpoints,
   resolveDesktopServerExposure,
 } from "./serverExposure.ts";
-import { DesktopSshEnvironmentBridge, resolveRemoteT3CliPackageSpec } from "./sshEnvironment.ts";
+import {
+  DesktopSshEnvironmentBridge,
+  resolveRemoteT3CliPackageSpec,
+} from "./sshEnvironment.ts";
 import { syncShellEnvironment } from "./syncShellEnvironment.ts";
 import { waitForBackendStartupReady } from "./backendStartupReadiness.ts";
-import { getAutoUpdateDisabledReason, shouldBroadcastDownloadProgress } from "./updateState.ts";
+import {
+  getAutoUpdateDisabledReason,
+  shouldBroadcastDownloadProgress,
+} from "./updateState.ts";
 import { doesVersionMatchDesktopUpdateChannel } from "./updateChannels.ts";
 import { ServerListeningDetector } from "./serverListeningDetector.ts";
 import {
@@ -80,9 +92,15 @@ import {
   reduceDesktopUpdateStateOnNoUpdate,
   reduceDesktopUpdateStateOnUpdateAvailable,
 } from "./updateMachine.ts";
-import { isArm64HostRunningIntelBuild, resolveDesktopRuntimeInfo } from "./runtimeArch.ts";
+import {
+  isArm64HostRunningIntelBuild,
+  resolveDesktopRuntimeInfo,
+} from "./runtimeArch.ts";
 import { resolveDesktopAppBranding } from "./appBranding.ts";
-import { bindFirstRevealTrigger, type RevealSubscription } from "./windowReveal.ts";
+import {
+  bindFirstRevealTrigger,
+  type RevealSubscription,
+} from "./windowReveal.ts";
 import { resolveTailscaleAdvertisedEndpoints } from "./tailscaleEndpointProvider.ts";
 
 syncShellEnvironment();
@@ -100,23 +118,34 @@ const UPDATE_DOWNLOAD_CHANNEL = "desktop:update-download";
 const UPDATE_INSTALL_CHANNEL = "desktop:update-install";
 const UPDATE_CHECK_CHANNEL = "desktop:update-check";
 const GET_APP_BRANDING_CHANNEL = "desktop:get-app-branding";
-const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL = "desktop:get-local-environment-bootstrap";
+const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL =
+  "desktop:get-local-environment-bootstrap";
 const GET_CLIENT_SETTINGS_CHANNEL = "desktop:get-client-settings";
 const SET_CLIENT_SETTINGS_CHANNEL = "desktop:set-client-settings";
-const GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:get-saved-environment-registry";
-const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-registry";
-const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:get-saved-environment-secret";
-const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secret";
-const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
+const GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL =
+  "desktop:get-saved-environment-registry";
+const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL =
+  "desktop:set-saved-environment-registry";
+const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL =
+  "desktop:get-saved-environment-secret";
+const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL =
+  "desktop:set-saved-environment-secret";
+const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL =
+  "desktop:remove-saved-environment-secret";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
-const SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
+const SET_TAILSCALE_SERVE_ENABLED_CHANNEL =
+  "desktop:set-tailscale-serve-enabled";
 const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
-const BASE_DIR = process.env.T3CODE_HOME?.trim() || Path.join(OS.homedir(), ".t3");
+const BASE_DIR =
+  process.env.T3CODE_HOME?.trim() || Path.join(OS.homedir(), ".t3");
 const STATE_DIR = Path.join(BASE_DIR, "userdata");
 const DESKTOP_SETTINGS_PATH = Path.join(STATE_DIR, "desktop-settings.json");
 const CLIENT_SETTINGS_PATH = Path.join(STATE_DIR, "client-settings.json");
-const SAVED_ENVIRONMENT_REGISTRY_PATH = Path.join(STATE_DIR, "saved-environments.json");
+const SAVED_ENVIRONMENT_REGISTRY_PATH = Path.join(
+  STATE_DIR,
+  "saved-environments.json",
+);
 const DESKTOP_SCHEME = "t3";
 const ROOT_DIR = Path.resolve(__dirname, "../../..");
 const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
@@ -124,17 +153,24 @@ const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
 // for a built server entry, for example:
 // "/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs"
 const DEV_REMOTE_T3_SERVER_ENTRY_PATH =
-  process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ?? "";
+  "/Users/julius/Developer/t3code/apps/server/dist/bin.mjs";
+process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ?? "";
 const desktopAppBranding: DesktopAppBranding = resolveDesktopAppBranding({
   isDevelopment,
   appVersion: app.getVersion(),
 });
 const APP_DISPLAY_NAME = desktopAppBranding.displayName;
-const APP_USER_MODEL_ID = isDevelopment ? "com.t3tools.t3code.dev" : "com.t3tools.t3code";
-const LINUX_DESKTOP_ENTRY_NAME = isDevelopment ? "t3code-dev.desktop" : "t3code.desktop";
+const APP_USER_MODEL_ID = isDevelopment
+  ? "com.t3tools.t3code.dev"
+  : "com.t3tools.t3code";
+const LINUX_DESKTOP_ENTRY_NAME = isDevelopment
+  ? "t3code-dev.desktop"
+  : "t3code.desktop";
 const LINUX_WM_CLASS = isDevelopment ? "t3code-dev" : "t3code";
 const USER_DATA_DIR_NAME = isDevelopment ? "t3code-dev" : "t3code";
-const LEGACY_USER_DATA_DIR_NAME = isDevelopment ? "T3 Code (Dev)" : "T3 Code (Alpha)";
+const LEGACY_USER_DATA_DIR_NAME = isDevelopment
+  ? "T3 Code (Dev)"
+  : "T3 Code (Alpha)";
 const COMMIT_HASH_PATTERN = /^[0-9a-f]{7,40}$/i;
 const COMMIT_HASH_DISPLAY_LENGTH = 12;
 const LOG_DIR = Path.join(STATE_DIR, "logs");
@@ -177,11 +213,16 @@ const TITLEBAR_COLOR = "#01000000"; // #00000000 does not work correctly on Linu
 const TITLEBAR_LIGHT_SYMBOL_COLOR = "#1f2937";
 const TITLEBAR_DARK_SYMBOL_COLOR = "#f8fafc";
 
-function normalizeContextMenuItems(source: readonly ContextMenuItem[]): ContextMenuItem[] {
+function normalizeContextMenuItems(
+  source: readonly ContextMenuItem[],
+): ContextMenuItem[] {
   const normalizedItems: ContextMenuItem[] = [];
 
   for (const sourceItem of source) {
-    if (typeof sourceItem.id !== "string" || typeof sourceItem.label !== "string") {
+    if (
+      typeof sourceItem.id !== "string" ||
+      typeof sourceItem.label !== "string"
+    ) {
       continue;
     }
 
@@ -237,8 +278,12 @@ let desktopLogSink: RotatingFileSink | null = null;
 let backendLogSink: RotatingFileSink | null = null;
 let restoreStdIoCapture: (() => void) | null = null;
 let backendObservabilitySettings = readPersistedBackendObservabilitySettings();
-let desktopSettings = readDesktopSettings(DESKTOP_SETTINGS_PATH, app.getVersion());
-let desktopServerExposureMode: DesktopServerExposureMode = desktopSettings.serverExposureMode;
+let desktopSettings = readDesktopSettings(
+  DESKTOP_SETTINGS_PATH,
+  app.getVersion(),
+);
+let desktopServerExposureMode: DesktopServerExposureMode =
+  desktopSettings.serverExposureMode;
 
 let destructiveMenuIconCache: Electron.NativeImage | null | undefined;
 const expectedBackendExitChildren = new WeakSet<ChildProcess.ChildProcess>();
@@ -274,14 +319,21 @@ function readPersistedBackendObservabilitySettings(): {
     if (!FS.existsSync(SERVER_SETTINGS_PATH)) {
       return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
     }
-    return parsePersistedServerObservabilitySettings(FS.readFileSync(SERVER_SETTINGS_PATH, "utf8"));
+    return parsePersistedServerObservabilitySettings(
+      FS.readFileSync(SERVER_SETTINGS_PATH, "utf8"),
+    );
   } catch (error) {
-    console.warn("[desktop] failed to read persisted backend observability settings", error);
+    console.warn(
+      "[desktop] failed to read persisted backend observability settings",
+      error,
+    );
     return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
   }
 }
 
-function resolveConfiguredDesktopBackendPort(rawPort: string | undefined): number | undefined {
+function resolveConfiguredDesktopBackendPort(
+  rawPort: string | undefined,
+): number | undefined {
   if (!rawPort) {
     return undefined;
   }
@@ -333,7 +385,9 @@ async function getDesktopAdvertisedEndpoints() {
     mode: desktopServerExposureMode,
     port: backendPort,
     networkInterfaces: OS.networkInterfaces(),
-    ...(backendAdvertisedHost ? { advertisedHostOverride: backendAdvertisedHost } : {}),
+    ...(backendAdvertisedHost
+      ? { advertisedHostOverride: backendAdvertisedHost }
+      : {}),
   });
   const coreEndpoints = resolveDesktopCoreAdvertisedEndpoints({
     port: backendPort,
@@ -387,7 +441,9 @@ async function applyDesktopServerExposureMode(
 
   if (requestedMode === "network-accessible" && exposure.endpointUrl === null) {
     if (options?.rejectIfUnavailable) {
-      throw new Error("No reachable network address is available for this desktop right now.");
+      throw new Error(
+        "No reachable network address is available for this desktop right now.",
+      );
     }
     exposure = resolveDesktopServerExposure({
       mode: "local-only",
@@ -398,7 +454,10 @@ async function applyDesktopServerExposureMode(
   }
 
   desktopServerExposureMode = exposure.mode;
-  desktopSettings = setDesktopServerExposurePreference(desktopSettings, requestedMode);
+  desktopSettings = setDesktopServerExposurePreference(
+    desktopSettings,
+    requestedMode,
+  );
   backendBindHost = exposure.bindHost;
   backendHttpUrl = exposure.localHttpUrl;
   backendWsUrl = exposure.localWsUrl;
@@ -418,7 +477,9 @@ async function applyDesktopTailscaleServeEnabled(
   desktopSettings = nextSettings;
   writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
   relaunchDesktopApp(
-    desktopSettings.tailscaleServeEnabled ? "tailscale-serve-enabled" : "tailscale-serve-disabled",
+    desktopSettings.tailscaleServeEnabled
+      ? "tailscale-serve-enabled"
+      : "tailscale-serve-disabled",
   );
   return getDesktopServerExposureState();
 }
@@ -453,10 +514,15 @@ function relaunchDesktopApp(reason: string): void {
 
 function writeDesktopLogHeader(message: string): void {
   if (!desktopLogSink) return;
-  desktopLogSink.write(`[${logTimestamp()}] [${logScope("desktop")}] ${message}\n`);
+  desktopLogSink.write(
+    `[${logTimestamp()}] [${logScope("desktop")}] ${message}\n`,
+  );
 }
 
-function writeBackendSessionBoundary(phase: "START" | "END", details: string): void {
+function writeBackendSessionBoundary(
+  phase: "START" | "END",
+  details: string,
+): void {
   if (!backendLogSink) return;
   const normalizedDetails = sanitizeLogValue(details);
   backendLogSink.write(
@@ -523,7 +589,9 @@ function cancelBackendReadinessWait(): void {
   backendReadinessAbortController = null;
 }
 
-async function waitForBackendWindowReady(baseUrl: string): Promise<"listening" | "http"> {
+async function waitForBackendWindowReady(
+  baseUrl: string,
+): Promise<"listening" | "http"> {
   return await waitForBackendStartupReady({
     listeningPromise: backendListeningDetector?.promise ?? null,
     waitForHttpReady: () =>
@@ -536,7 +604,11 @@ async function waitForBackendWindowReady(baseUrl: string): Promise<"listening" |
 
 function ensureInitialBackendWindowOpen(): void {
   const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;
-  if (isDevelopment || existingWindow !== null || backendInitialWindowOpenInFlight !== null) {
+  if (
+    isDevelopment ||
+    existingWindow !== null ||
+    backendInitialWindowOpenInFlight !== null
+  ) {
     return;
   }
 
@@ -556,7 +628,10 @@ function ensureInitialBackendWindowOpen(): void {
       writeDesktopLogHeader(
         `bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
       );
-      console.warn("[desktop] backend readiness check timed out during packaged bootstrap", error);
+      console.warn(
+        "[desktop] backend readiness check timed out during packaged bootstrap",
+        error,
+      );
     })
     .finally(() => {
       if (backendInitialWindowOpenInFlight === nextOpen) {
@@ -575,7 +650,10 @@ function writeDesktopStreamChunk(
   if (!desktopLogSink) return;
   const buffer = Buffer.isBuffer(chunk)
     ? chunk
-    : Buffer.from(String(chunk), typeof chunk === "string" ? encoding : undefined);
+    : Buffer.from(
+        String(chunk),
+        typeof chunk === "string" ? encoding : undefined,
+      );
   desktopLogSink.write(`[${logTimestamp()}] [${logScope(streamName)}] `);
   desktopLogSink.write(buffer);
   if (buffer.length === 0 || buffer[buffer.length - 1] !== 0x0a) {
@@ -584,7 +662,11 @@ function writeDesktopStreamChunk(
 }
 
 function installStdIoCapture(): void {
-  if (!app.isPackaged || desktopLogSink === null || restoreStdIoCapture !== null) {
+  if (
+    !app.isPackaged ||
+    desktopLogSink === null ||
+    restoreStdIoCapture !== null
+  ) {
     return;
   }
 
@@ -592,13 +674,17 @@ function installStdIoCapture(): void {
   const originalStderrWrite = process.stderr.write.bind(process.stderr);
 
   const patchWrite =
-    (streamName: "stdout" | "stderr", originalWrite: typeof process.stdout.write) =>
+    (
+      streamName: "stdout" | "stderr",
+      originalWrite: typeof process.stdout.write,
+    ) =>
     (
       chunk: string | Uint8Array,
       encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
       callback?: (error?: Error | null) => void,
     ): boolean => {
-      const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
+      const encoding =
+        typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
       writeDesktopStreamChunk(streamName, chunk, encoding);
       if (typeof encodingOrCallback === "function") {
         return originalWrite(chunk, encodingOrCallback);
@@ -644,9 +730,13 @@ function initializePackagedLogging(): void {
 }
 
 function captureBackendOutput(child: ChildProcess.ChildProcess): void {
-  const attachStream = (stream: NodeJS.ReadableStream | null | undefined): void => {
+  const attachStream = (
+    stream: NodeJS.ReadableStream | null | undefined,
+  ): void => {
     stream?.on("data", (chunk: unknown) => {
-      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
+      const buffer = Buffer.isBuffer(chunk)
+        ? chunk
+        : Buffer.from(String(chunk), "utf8");
       backendLogSink?.write(buffer);
       backendListeningDetector?.push(buffer);
     });
@@ -831,7 +921,10 @@ function resolveDesktopStaticDir(): string | null {
   return null;
 }
 
-function resolveDesktopStaticPath(staticRoot: string, requestUrl: string): string {
+function resolveDesktopStaticPath(
+  staticRoot: string,
+  requestUrl: string,
+): string {
   const url = new URL(requestUrl);
   const rawPath = decodeURIComponent(url.pathname);
   const normalizedPath = Path.posix.normalize(rawPath).replace(/^\/+/, "");
@@ -839,7 +932,8 @@ function resolveDesktopStaticPath(staticRoot: string, requestUrl: string): strin
     return Path.join(staticRoot, "index.html");
   }
 
-  const requestedPath = normalizedPath.length > 0 ? normalizedPath : "index.html";
+  const requestedPath =
+    normalizedPath.length > 0 ? normalizedPath : "index.html";
   const resolvedPath = Path.join(staticRoot, requestedPath);
 
   if (Path.extname(resolvedPath)) {
@@ -866,12 +960,19 @@ function isStaticAssetRequest(requestUrl: string): boolean {
 function handleFatalStartupError(stage: string, error: unknown): void {
   const message = formatErrorMessage(error);
   const detail =
-    error instanceof Error && typeof error.stack === "string" ? `\n${error.stack}` : "";
-  writeDesktopLogHeader(`fatal startup error stage=${stage} message=${message}`);
+    error instanceof Error && typeof error.stack === "string"
+      ? `\n${error.stack}`
+      : "";
+  writeDesktopLogHeader(
+    `fatal startup error stage=${stage} message=${message}`,
+  );
   console.error(`[desktop] fatal startup error (${stage})`, error);
   if (!isQuitting) {
     isQuitting = true;
-    dialog.showErrorBox("T3 Code failed to start", `Stage: ${stage}\n${message}${detail}`);
+    dialog.showErrorBox(
+      "T3 Code failed to start",
+      `Stage: ${stage}\n${message}${detail}`,
+    );
   }
   stopBackend();
   restoreStdIoCapture?.();
@@ -894,10 +995,14 @@ function registerDesktopProtocol(): void {
 
   protocol.registerFileProtocol(DESKTOP_SCHEME, (request, callback) => {
     try {
-      const candidate = resolveDesktopStaticPath(staticRootResolved, request.url);
+      const candidate = resolveDesktopStaticPath(
+        staticRootResolved,
+        request.url,
+      );
       const resolvedCandidate = Path.resolve(candidate);
       const isInRoot =
-        resolvedCandidate === fallbackIndex || resolvedCandidate.startsWith(staticRootPrefix);
+        resolvedCandidate === fallbackIndex ||
+        resolvedCandidate.startsWith(staticRootPrefix);
       const isAssetRequest = isStaticAssetRequest(request.url);
 
       if (!isInRoot || !FS.existsSync(resolvedCandidate)) {
@@ -920,7 +1025,9 @@ function registerDesktopProtocol(): void {
 
 function dispatchMenuAction(action: string): void {
   const existingWindow =
-    BrowserWindow.getFocusedWindow() ?? mainWindow ?? BrowserWindow.getAllWindows()[0];
+    BrowserWindow.getFocusedWindow() ??
+    mainWindow ??
+    BrowserWindow.getAllWindows()[0];
   const targetWindow = existingWindow ?? createWindow();
   if (!existingWindow) {
     mainWindow = targetWindow;
@@ -942,7 +1049,8 @@ function dispatchMenuAction(action: string): void {
 
 function handleCheckForUpdatesMenuClick(): void {
   const hasUpdateFeedConfig =
-    readAppUpdateYml() !== null || Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
+    readAppUpdateYml() !== null ||
+    Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
   const disabledReason = getAutoUpdateDisabledReason({
     isDevelopment,
     isPackaged: app.isPackaged,
@@ -952,7 +1060,9 @@ function handleCheckForUpdatesMenuClick(): void {
     hasUpdateFeedConfig,
   });
   if (disabledReason) {
-    console.info("[desktop-updater] Manual update check requested, but updates are disabled.");
+    console.info(
+      "[desktop-updater] Manual update check requested, but updates are disabled.",
+    );
     void dialog.showMessageBox({
       type: "info",
       title: "Updates unavailable",
@@ -984,7 +1094,9 @@ async function checkForUpdatesFromMenu(): Promise<void> {
       type: "warning",
       title: "Update check failed",
       message: "Could not check for updates.",
-      detail: updateState.message ?? "An unknown error occurred. Please try again later.",
+      detail:
+        updateState.message ??
+        "An unknown error occurred. Please try again later.",
       buttons: ["OK"],
     });
   }
@@ -1202,7 +1314,11 @@ function createBaseUpdateState(
   enabled: boolean,
 ): DesktopUpdateState {
   return {
-    ...createInitialDesktopUpdateState(app.getVersion(), desktopRuntimeInfo, channel),
+    ...createInitialDesktopUpdateState(
+      app.getVersion(),
+      desktopRuntimeInfo,
+      channel,
+    ),
     enabled,
     status: enabled ? "idle" : "disabled",
   };
@@ -1219,7 +1335,8 @@ function applyAutoUpdaterChannel(channel: DesktopUpdateChannel): void {
 
 function shouldEnableAutoUpdates(): boolean {
   const hasUpdateFeedConfig =
-    readAppUpdateYml() !== null || Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
+    readAppUpdateYml() !== null ||
+    Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
   return (
     getAutoUpdateDisabledReason({
       isDevelopment,
@@ -1234,14 +1351,19 @@ function shouldEnableAutoUpdates(): boolean {
 
 async function checkForUpdates(reason: string): Promise<boolean> {
   if (isQuitting || !updaterConfigured || updateCheckInFlight) return false;
-  if (updateState.status === "downloading" || updateState.status === "downloaded") {
+  if (
+    updateState.status === "downloading" ||
+    updateState.status === "downloaded"
+  ) {
     console.info(
       `[desktop-updater] Skipping update check (${reason}) while status=${updateState.status}.`,
     );
     return false;
   }
   updateCheckInFlight = true;
-  setUpdateState(reduceDesktopUpdateStateOnCheckStart(updateState, new Date().toISOString()));
+  setUpdateState(
+    reduceDesktopUpdateStateOnCheckStart(updateState, new Date().toISOString()),
+  );
   console.info(`[desktop-updater] Checking for updates (${reason})...`);
 
   try {
@@ -1250,7 +1372,11 @@ async function checkForUpdates(reason: string): Promise<boolean> {
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
     setUpdateState(
-      reduceDesktopUpdateStateOnCheckFailure(updateState, message, new Date().toISOString()),
+      reduceDesktopUpdateStateOnCheckFailure(
+        updateState,
+        message,
+        new Date().toISOString(),
+      ),
     );
     console.error(`[desktop-updater] Failed to check for updates: ${message}`);
     return true;
@@ -1263,12 +1389,17 @@ async function downloadAvailableUpdate(): Promise<{
   accepted: boolean;
   completed: boolean;
 }> {
-  if (!updaterConfigured || updateDownloadInFlight || updateState.status !== "available") {
+  if (
+    !updaterConfigured ||
+    updateDownloadInFlight ||
+    updateState.status !== "available"
+  ) {
     return { accepted: false, completed: false };
   }
   updateDownloadInFlight = true;
   setUpdateState(reduceDesktopUpdateStateOnDownloadStart(updateState));
-  autoUpdater.disableDifferentialDownload = isArm64HostRunningIntelBuild(desktopRuntimeInfo);
+  autoUpdater.disableDifferentialDownload =
+    isArm64HostRunningIntelBuild(desktopRuntimeInfo);
   console.info("[desktop-updater] Downloading update...");
 
   try {
@@ -1276,7 +1407,9 @@ async function downloadAvailableUpdate(): Promise<{
     return { accepted: true, completed: true };
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
-    setUpdateState(reduceDesktopUpdateStateOnDownloadFailure(updateState, message));
+    setUpdateState(
+      reduceDesktopUpdateStateOnDownloadFailure(updateState, message),
+    );
     console.error(`[desktop-updater] Failed to download update: ${message}`);
     return { accepted: true, completed: false };
   } finally {
@@ -1310,7 +1443,9 @@ async function installDownloadedUpdate(): Promise<{
     const message = formatErrorMessage(error);
     updateInstallInFlight = false;
     isQuitting = false;
-    setUpdateState(reduceDesktopUpdateStateOnInstallFailure(updateState, message));
+    setUpdateState(
+      reduceDesktopUpdateStateOnInstallFailure(updateState, message),
+    );
     console.error(`[desktop-updater] Failed to install update: ${message}`);
     return { accepted: true, completed: false };
   }
@@ -1318,7 +1453,9 @@ async function installDownloadedUpdate(): Promise<{
 
 function configureAutoUpdater(): void {
   const githubToken =
-    process.env.T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim() || "";
+    process.env.T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN?.trim() ||
+    process.env.GH_TOKEN?.trim() ||
+    "";
   if (githubToken) {
     // When a token is provided, re-configure the feed with `private: true` so
     // electron-updater uses the GitHub API (api.github.com) instead of the
@@ -1351,7 +1488,8 @@ function configureAutoUpdater(): void {
   autoUpdater.autoDownload = false;
   autoUpdater.autoInstallOnAppQuit = false;
   applyAutoUpdaterChannel(desktopSettings.updateChannel);
-  autoUpdater.disableDifferentialDownload = isArm64HostRunningIntelBuild(desktopRuntimeInfo);
+  autoUpdater.disableDifferentialDownload =
+    isArm64HostRunningIntelBuild(desktopRuntimeInfo);
   let lastLoggedDownloadMilestone = -1;
 
   if (isArm64HostRunningIntelBuild(desktopRuntimeInfo)) {
@@ -1364,11 +1502,18 @@ function configureAutoUpdater(): void {
     console.info("[desktop-updater] Looking for updates...");
   });
   autoUpdater.on("update-available", (info) => {
-    if (!doesVersionMatchDesktopUpdateChannel(info.version, updateState.channel)) {
+    if (
+      !doesVersionMatchDesktopUpdateChannel(info.version, updateState.channel)
+    ) {
       console.info(
         `[desktop-updater] Ignoring ${info.version} because it does not match the selected '${updateState.channel}' channel.`,
       );
-      setUpdateState(reduceDesktopUpdateStateOnNoUpdate(updateState, new Date().toISOString()));
+      setUpdateState(
+        reduceDesktopUpdateStateOnNoUpdate(
+          updateState,
+          new Date().toISOString(),
+        ),
+      );
       lastLoggedDownloadMilestone = -1;
       return;
     }
@@ -1384,7 +1529,9 @@ function configureAutoUpdater(): void {
     console.info(`[desktop-updater] Update available: ${info.version}`);
   });
   autoUpdater.on("update-not-available", () => {
-    setUpdateState(reduceDesktopUpdateStateOnNoUpdate(updateState, new Date().toISOString()));
+    setUpdateState(
+      reduceDesktopUpdateStateOnNoUpdate(updateState, new Date().toISOString()),
+    );
     lastLoggedDownloadMilestone = -1;
     console.info("[desktop-updater] No updates available.");
   });
@@ -1393,7 +1540,9 @@ function configureAutoUpdater(): void {
     if (updateInstallInFlight) {
       updateInstallInFlight = false;
       isQuitting = false;
-      setUpdateState(reduceDesktopUpdateStateOnInstallFailure(updateState, message));
+      setUpdateState(
+        reduceDesktopUpdateStateOnInstallFailure(updateState, message),
+      );
       console.error(`[desktop-updater] Updater error: ${message}`);
       return;
     }
@@ -1404,7 +1553,9 @@ function configureAutoUpdater(): void {
         checkedAt: new Date().toISOString(),
         downloadPercent: null,
         errorContext: resolveUpdaterErrorContext(),
-        canRetry: updateState.availableVersion !== null || updateState.downloadedVersion !== null,
+        canRetry:
+          updateState.availableVersion !== null ||
+          updateState.downloadedVersion !== null,
       });
     }
     console.error(`[desktop-updater] Updater error: ${message}`);
@@ -1415,7 +1566,12 @@ function configureAutoUpdater(): void {
       shouldBroadcastDownloadProgress(updateState, progress.percent) ||
       updateState.message !== null
     ) {
-      setUpdateState(reduceDesktopUpdateStateOnDownloadProgress(updateState, progress.percent));
+      setUpdateState(
+        reduceDesktopUpdateStateOnDownloadProgress(
+          updateState,
+          progress.percent,
+        ),
+      );
     }
     const milestone = percent - (percent % 10);
     if (milestone > lastLoggedDownloadMilestone) {
@@ -1424,7 +1580,9 @@ function configureAutoUpdater(): void {
     }
   });
   autoUpdater.on("update-downloaded", (info) => {
-    setUpdateState(reduceDesktopUpdateStateOnDownloadComplete(updateState, info.version));
+    setUpdateState(
+      reduceDesktopUpdateStateOnDownloadComplete(updateState, info.version),
+    );
     console.info(`[desktop-updater] Update downloaded: ${info.version}`);
   });
 
@@ -1446,7 +1604,9 @@ function scheduleBackendRestart(reason: string): void {
 
   const delayMs = Math.min(500 * 2 ** restartAttempt, 10_000);
   restartAttempt += 1;
-  console.error(`[desktop] backend exited unexpectedly (${reason}); restarting in ${delayMs}ms`);
+  console.error(
+    `[desktop] backend exited unexpectedly (${reason}); restarting in ${delayMs}ms`,
+  );
 
   restartTimer = setTimeout(() => {
     restartTimer = null;
@@ -1465,18 +1625,22 @@ function startBackend(): void {
   }
 
   const captureBackendLogs = !isDevelopment;
-  const child = ChildProcess.spawn(process.execPath, [backendEntry, "--bootstrap-fd", "3"], {
-    cwd: resolveBackendCwd(),
-    // In Electron main, process.execPath points to the Electron binary.
-    // Run the child in Node mode so this backend process does not become a GUI app instance.
-    env: {
-      ...backendChildEnv(),
-      ELECTRON_RUN_AS_NODE: "1",
+  const child = ChildProcess.spawn(
+    process.execPath,
+    [backendEntry, "--bootstrap-fd", "3"],
+    {
+      cwd: resolveBackendCwd(),
+      // In Electron main, process.execPath points to the Electron binary.
+      // Run the child in Node mode so this backend process does not become a GUI app instance.
+      env: {
+        ...backendChildEnv(),
+        ELECTRON_RUN_AS_NODE: "1",
+      },
+      stdio: captureBackendLogs
+        ? ["ignore", "pipe", "pipe", "pipe"]
+        : ["ignore", "inherit", "inherit", "pipe"],
     },
-    stdio: captureBackendLogs
-      ? ["ignore", "pipe", "pipe", "pipe"]
-      : ["ignore", "inherit", "inherit", "pipe"],
-  });
+  );
   const bootstrapStream = child.stdio[3];
   if (bootstrapStream && "write" in bootstrapStream) {
     bootstrapStream.write(
@@ -1596,7 +1760,8 @@ async function stopBackendAndWaitForExit(timeoutMs = 5_000): Promise<void> {
   backendProcess = null;
   if (!child) return;
   const backendChild = child;
-  if (backendChild.exitCode !== null || backendChild.signalCode !== null) return;
+  if (backendChild.exitCode !== null || backendChild.signalCode !== null)
+    return;
   expectedBackendExitChildren.add(backendChild);
 
   await new Promise<void>((resolve) => {
@@ -1655,16 +1820,21 @@ function registerIpcHandlers(): void {
   });
 
   ipcMain.removeHandler(GET_CLIENT_SETTINGS_CHANNEL);
-  ipcMain.handle(GET_CLIENT_SETTINGS_CHANNEL, async () => readClientSettings(CLIENT_SETTINGS_PATH));
+  ipcMain.handle(GET_CLIENT_SETTINGS_CHANNEL, async () =>
+    readClientSettings(CLIENT_SETTINGS_PATH),
+  );
 
   ipcMain.removeHandler(SET_CLIENT_SETTINGS_CHANNEL);
-  ipcMain.handle(SET_CLIENT_SETTINGS_CHANNEL, async (_event, rawSettings: unknown) => {
-    if (typeof rawSettings !== "object" || rawSettings === null) {
-      throw new Error("Invalid client settings payload.");
-    }
+  ipcMain.handle(
+    SET_CLIENT_SETTINGS_CHANNEL,
+    async (_event, rawSettings: unknown) => {
+      if (typeof rawSettings !== "object" || rawSettings === null) {
+        throw new Error("Invalid client settings payload.");
+      }
 
-    writeClientSettings(CLIENT_SETTINGS_PATH, rawSettings as ClientSettings);
-  });
+      writeClientSettings(CLIENT_SETTINGS_PATH, rawSettings as ClientSettings);
+    },
+  );
 
   ipcMain.removeHandler(GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL);
   ipcMain.handle(GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL, async () =>
@@ -1672,22 +1842,28 @@ function registerIpcHandlers(): void {
   );
 
   ipcMain.removeHandler(SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL);
-  ipcMain.handle(SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL, async (_event, rawRecords: unknown) => {
-    if (!Array.isArray(rawRecords)) {
-      throw new Error("Invalid saved environment registry payload.");
-    }
+  ipcMain.handle(
+    SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL,
+    async (_event, rawRecords: unknown) => {
+      if (!Array.isArray(rawRecords)) {
+        throw new Error("Invalid saved environment registry payload.");
+      }
 
-    writeSavedEnvironmentRegistry(
-      SAVED_ENVIRONMENT_REGISTRY_PATH,
-      rawRecords as readonly PersistedSavedEnvironmentRecord[],
-    );
-  });
+      writeSavedEnvironmentRegistry(
+        SAVED_ENVIRONMENT_REGISTRY_PATH,
+        rawRecords as readonly PersistedSavedEnvironmentRecord[],
+      );
+    },
+  );
 
   ipcMain.removeHandler(GET_SAVED_ENVIRONMENT_SECRET_CHANNEL);
   ipcMain.handle(
     GET_SAVED_ENVIRONMENT_SECRET_CHANNEL,
     async (_event, rawEnvironmentId: unknown) => {
-      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
+      if (
+        typeof rawEnvironmentId !== "string" ||
+        rawEnvironmentId.trim().length === 0
+      ) {
         return null;
       }
 
@@ -1703,7 +1879,10 @@ function registerIpcHandlers(): void {
   ipcMain.handle(
     SET_SAVED_ENVIRONMENT_SECRET_CHANNEL,
     async (_event, rawEnvironmentId: unknown, rawSecret: unknown) => {
-      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
+      if (
+        typeof rawEnvironmentId !== "string" ||
+        rawEnvironmentId.trim().length === 0
+      ) {
         throw new Error("Invalid saved environment id.");
       }
       if (typeof rawSecret !== "string" || rawSecret.trim().length === 0) {
@@ -1723,7 +1902,10 @@ function registerIpcHandlers(): void {
   ipcMain.handle(
     REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL,
     async (_event, rawEnvironmentId: unknown) => {
-      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
+      if (
+        typeof rawEnvironmentId !== "string" ||
+        rawEnvironmentId.trim().length === 0
+      ) {
         return;
       }
 
@@ -1737,51 +1919,61 @@ function registerIpcHandlers(): void {
   desktopSshEnvironmentBridge.registerIpcHandlers(ipcMain);
 
   ipcMain.removeHandler(GET_SERVER_EXPOSURE_STATE_CHANNEL);
-  ipcMain.handle(GET_SERVER_EXPOSURE_STATE_CHANNEL, async () => getDesktopServerExposureState());
+  ipcMain.handle(GET_SERVER_EXPOSURE_STATE_CHANNEL, async () =>
+    getDesktopServerExposureState(),
+  );
 
   ipcMain.removeHandler(SET_SERVER_EXPOSURE_MODE_CHANNEL);
-  ipcMain.handle(SET_SERVER_EXPOSURE_MODE_CHANNEL, async (_event, rawMode: unknown) => {
-    if (rawMode !== "local-only" && rawMode !== "network-accessible") {
-      throw new Error("Invalid desktop server exposure input.");
-    }
+  ipcMain.handle(
+    SET_SERVER_EXPOSURE_MODE_CHANNEL,
+    async (_event, rawMode: unknown) => {
+      if (rawMode !== "local-only" && rawMode !== "network-accessible") {
+        throw new Error("Invalid desktop server exposure input.");
+      }
 
-    const nextMode = rawMode as DesktopServerExposureMode;
-    if (nextMode === desktopServerExposureMode) {
-      return getDesktopServerExposureState();
-    }
+      const nextMode = rawMode as DesktopServerExposureMode;
+      if (nextMode === desktopServerExposureMode) {
+        return getDesktopServerExposureState();
+      }
 
-    const nextState = await applyDesktopServerExposureMode(nextMode, {
-      persist: true,
-      rejectIfUnavailable: true,
-    });
-    relaunchDesktopApp(`serverExposureMode=${nextMode}`);
-    return nextState;
-  });
+      const nextState = await applyDesktopServerExposureMode(nextMode, {
+        persist: true,
+        rejectIfUnavailable: true,
+      });
+      relaunchDesktopApp(`serverExposureMode=${nextMode}`);
+      return nextState;
+    },
+  );
 
   ipcMain.removeHandler(SET_TAILSCALE_SERVE_ENABLED_CHANNEL);
-  ipcMain.handle(SET_TAILSCALE_SERVE_ENABLED_CHANNEL, async (_event, rawInput: unknown) => {
-    if (typeof rawInput !== "object" || rawInput === null) {
-      throw new Error("Invalid Tailscale Serve input.");
-    }
-    const input = rawInput as {
-      readonly enabled?: unknown;
-      readonly port?: unknown;
-    };
-    if (typeof input.enabled !== "boolean") {
-      throw new Error("Invalid Tailscale Serve input.");
-    }
-    const nextSettings = setDesktopTailscaleServePreference(desktopSettings, {
-      enabled: input.enabled,
-      ...(typeof input.port === "number" ? { port: input.port } : {}),
-    });
-    if (nextSettings === desktopSettings) {
-      return getDesktopServerExposureState();
-    }
-    return applyDesktopTailscaleServeEnabled(nextSettings);
-  });
+  ipcMain.handle(
+    SET_TAILSCALE_SERVE_ENABLED_CHANNEL,
+    async (_event, rawInput: unknown) => {
+      if (typeof rawInput !== "object" || rawInput === null) {
+        throw new Error("Invalid Tailscale Serve input.");
+      }
+      const input = rawInput as {
+        readonly enabled?: unknown;
+        readonly port?: unknown;
+      };
+      if (typeof input.enabled !== "boolean") {
+        throw new Error("Invalid Tailscale Serve input.");
+      }
+      const nextSettings = setDesktopTailscaleServePreference(desktopSettings, {
+        enabled: input.enabled,
+        ...(typeof input.port === "number" ? { port: input.port } : {}),
+      });
+      if (nextSettings === desktopSettings) {
+        return getDesktopServerExposureState();
+      }
+      return applyDesktopTailscaleServeEnabled(nextSettings);
+    },
+  );
 
   ipcMain.removeHandler(GET_ADVERTISED_ENDPOINTS_CHANNEL);
-  ipcMain.handle(GET_ADVERTISED_ENDPOINTS_CHANNEL, async () => getDesktopAdvertisedEndpoints());
+  ipcMain.handle(GET_ADVERTISED_ENDPOINTS_CHANNEL, async () =>
+    getDesktopAdvertisedEndpoints(),
+  );
 
   ipcMain.removeHandler(PICK_FOLDER_CHANNEL);
   ipcMain.handle(PICK_FOLDER_CHANNEL, async (_event, rawOptions: unknown) => {
@@ -1821,7 +2013,11 @@ function registerIpcHandlers(): void {
   ipcMain.removeHandler(CONTEXT_MENU_CHANNEL);
   ipcMain.handle(
     CONTEXT_MENU_CHANNEL,
-    async (_event, items: ContextMenuItem[], position?: { x: number; y: number }) => {
+    async (
+      _event,
+      items: ContextMenuItem[],
+      position?: { x: number; y: number },
+    ) => {
       const normalizedItems = normalizeContextMenuItems(items);
       if (normalizedItems.length === 0) {
         return null;
@@ -1849,7 +2045,11 @@ function registerIpcHandlers(): void {
           const template: MenuItemConstructorOptions[] = [];
           let hasInsertedDestructiveSeparator = false;
           for (const item of entries) {
-            if (item.destructive && !hasInsertedDestructiveSeparator && template.length > 0) {
+            if (
+              item.destructive &&
+              !hasInsertedDestructiveSeparator &&
+              template.length > 0
+            ) {
               template.push({ type: "separator" });
               hasInsertedDestructiveSeparator = true;
             }
@@ -1862,7 +2062,10 @@ function registerIpcHandlers(): void {
             } else {
               itemOption.click = () => resolve(item.id);
             }
-            if (item.destructive && (!item.children || item.children.length === 0)) {
+            if (
+              item.destructive &&
+              (!item.children || item.children.length === 0)
+            ) {
               const destructiveIcon = getDestructiveMenuIcon();
               if (destructiveIcon) {
                 itemOption.icon = destructiveIcon;
@@ -1902,41 +2105,53 @@ function registerIpcHandlers(): void {
   ipcMain.handle(UPDATE_GET_STATE_CHANNEL, async () => updateState);
 
   ipcMain.removeHandler(UPDATE_SET_CHANNEL_CHANNEL);
-  ipcMain.handle(UPDATE_SET_CHANNEL_CHANNEL, async (_event, rawChannel: unknown) => {
-    if (rawChannel !== "latest" && rawChannel !== "nightly") {
-      throw new Error("Invalid desktop update channel input.");
-    }
-    if (updateCheckInFlight || updateDownloadInFlight || updateInstallInFlight) {
-      throw new Error("Cannot change update tracks while an update action is in progress.");
-    }
+  ipcMain.handle(
+    UPDATE_SET_CHANNEL_CHANNEL,
+    async (_event, rawChannel: unknown) => {
+      if (rawChannel !== "latest" && rawChannel !== "nightly") {
+        throw new Error("Invalid desktop update channel input.");
+      }
+      if (
+        updateCheckInFlight ||
+        updateDownloadInFlight ||
+        updateInstallInFlight
+      ) {
+        throw new Error(
+          "Cannot change update tracks while an update action is in progress.",
+        );
+      }
 
-    const nextChannel = rawChannel as DesktopUpdateChannel;
+      const nextChannel = rawChannel as DesktopUpdateChannel;
 
-    desktopSettings = setDesktopUpdateChannelPreference(desktopSettings, nextChannel);
-    writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
+      desktopSettings = setDesktopUpdateChannelPreference(
+        desktopSettings,
+        nextChannel,
+      );
+      writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
 
-    if (nextChannel === updateState.channel) {
-      return updateState;
-    }
+      if (nextChannel === updateState.channel) {
+        return updateState;
+      }
 
-    const enabled = shouldEnableAutoUpdates();
-    setUpdateState(createBaseUpdateState(nextChannel, enabled));
+      const enabled = shouldEnableAutoUpdates();
+      setUpdateState(createBaseUpdateState(nextChannel, enabled));
 
-    if (!enabled || !updaterConfigured) {
-      return updateState;
-    }
+      if (!enabled || !updaterConfigured) {
+        return updateState;
+      }
 
-    applyAutoUpdaterChannel(nextChannel);
-    const allowDowngrade = autoUpdater.allowDowngrade;
-    // An explicit channel switch should allow the immediate nightly->stable rollback path.
-    autoUpdater.allowDowngrade = true;
-    try {
-      await checkForUpdates("channel-change");
-    } finally {
-      autoUpdater.allowDowngrade = allowDowngrade;
-    }
-    return updateState;
-  });
+      applyAutoUpdaterChannel(nextChannel);
+      const allowDowngrade = autoUpdater.allowDowngrade;
+      // An explicit channel switch should allow the immediate nightly->stable rollback path.
+      autoUpdater.allowDowngrade = true;
+      try {
+        await checkForUpdates("channel-change");
+      } finally {
+        autoUpdater.allowDowngrade = allowDowngrade;
+      }
+      return updateState;
+    },
+  );
 
   ipcMain.removeHandler(UPDATE_DOWNLOAD_CHANNEL);
   ipcMain.handle(UPDATE_DOWNLOAD_CHANNEL, async () => {
@@ -2122,9 +2337,13 @@ function createWindow(): BrowserWindow {
   // fallback so the window still surfaces once the renderer has loaded
   // the page. Other platforms keep the no-flash `ready-to-show` path,
   // since `did-finish-load` typically fires before the first paint there.
-  const revealSubscribers: RevealSubscription[] = [(fire) => window.once("ready-to-show", fire)];
+  const revealSubscribers: RevealSubscription[] = [
+    (fire) => window.once("ready-to-show", fire),
+  ];
   if (process.platform === "linux") {
-    revealSubscribers.push((fire) => window.webContents.once("did-finish-load", fire));
+    revealSubscribers.push((fire) =>
+      window.webContents.once("did-finish-load", fire),
+    );
   }
   bindFirstRevealTrigger(revealSubscribers, () => revealWindow(window));
 
@@ -2156,7 +2375,9 @@ configureAppIdentity();
 
 async function bootstrap(): Promise<void> {
   writeDesktopLogHeader("bootstrap start");
-  const configuredBackendPort = resolveConfiguredDesktopBackendPort(process.env.T3CODE_PORT);
+  const configuredBackendPort = resolveConfiguredDesktopBackendPort(
+    process.env.T3CODE_PORT,
+  );
   if (isDevelopment && configuredBackendPort === undefined) {
     throw new Error("T3CODE_PORT is required in desktop development.");
   }
@@ -2174,7 +2395,10 @@ async function bootstrap(): Promise<void> {
       : `using configured backend port port=${backendPort}`,
   );
   backendBootstrapToken = Crypto.randomBytes(24).toString("hex");
-  if (desktopSettings.serverExposureMode !== DEFAULT_DESKTOP_SETTINGS.serverExposureMode) {
+  if (
+    desktopSettings.serverExposureMode !==
+    DEFAULT_DESKTOP_SETTINGS.serverExposureMode
+  ) {
     writeDesktopLogHeader(
       `bootstrap restoring persisted server exposure mode mode=${desktopSettings.serverExposureMode}`,
     );
@@ -2182,10 +2406,14 @@ async function bootstrap(): Promise<void> {
   const serverExposureState = await applyDesktopServerExposureMode(
     desktopSettings.serverExposureMode,
     {
-      persist: desktopSettings.serverExposureMode !== DEFAULT_DESKTOP_SETTINGS.serverExposureMode,
+      persist:
+        desktopSettings.serverExposureMode !==
+        DEFAULT_DESKTOP_SETTINGS.serverExposureMode,
     },
   );
-  writeDesktopLogHeader(`bootstrap resolved backend endpoint baseUrl=${backendHttpUrl}`);
+  writeDesktopLogHeader(
+    `bootstrap resolved backend endpoint baseUrl=${backendHttpUrl}`,
+  );
   if (serverExposureState.endpointUrl) {
     writeDesktopLogHeader(
       `bootstrap enabled network access endpointUrl=${serverExposureState.endpointUrl}`,
@@ -2215,7 +2443,10 @@ async function bootstrap(): Promise<void> {
         writeDesktopLogHeader(
           `bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
         );
-        console.warn("[desktop] backend readiness check timed out during dev bootstrap", error);
+        console.warn(
+          "[desktop] backend readiness check timed out during dev bootstrap",
+          error,
+        );
       });
     return;
   }

From cbd4398119ac51f9aada98f417765323d094e0a9 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 21:03:56 -0700
Subject: [PATCH 55/74] Improve SSH bootstrap diagnostics

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/web/src/environments/runtime/service.ts | 28 ++++++++++++++++++--
 packages/contracts/src/ipc.ts                |  2 ++
 packages/ssh/src/tunnel.ts                   | 25 +++++++++++++----
 3 files changed, 48 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 71d03c32103..d1e83a5d455 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -660,9 +660,11 @@ async function prepareSavedEnvironmentRecordForConnection(
 ): Promise<{
   readonly record: SavedEnvironmentRecord;
   readonly pairingToken: string | null;
+  readonly remotePort: number | null;
+  readonly remoteServerKind: "external" | "managed" | null;
 }> {
   if (!record.desktopSsh) {
-    return { record, pairingToken: null };
+    return { record, pairingToken: null, remotePort: null, remoteServerKind: null };
   }
 
   const bootstrap = await resolveDesktopSshEnvironmentBootstrap(record.desktopSsh, options);
@@ -685,6 +687,8 @@ async function prepareSavedEnvironmentRecordForConnection(
   return {
     record: nextRecord,
     pairingToken: bootstrap.pairingToken,
+    remotePort: bootstrap.remotePort ?? null,
+    remoteServerKind: bootstrap.remoteServerKind ?? null,
   };
 }
 
@@ -704,7 +708,17 @@ async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Pro
   const bearerSession = await bootstrapDesktopSshBearerSession(
     prepared.record.httpBaseUrl,
     prepared.pairingToken,
-  );
+  ).catch((error) => {
+    const detail = [
+      `local ${prepared.record.httpBaseUrl}`,
+      `remote port ${prepared.remotePort ?? "unknown"}`,
+      prepared.remoteServerKind ? `remote server ${prepared.remoteServerKind}` : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${message} (${detail})`);
+  });
   const didPersistBearerToken = await writeSavedEnvironmentBearerToken(
     prepared.record.environmentId,
     bearerSession.sessionToken,
@@ -1555,6 +1569,16 @@ export async function connectDesktopSshEnvironment(
     host: bootstrap.httpBaseUrl,
     pairingCode: bootstrap.pairingToken,
     desktopSsh: bootstrap.target,
+  }).catch((error) => {
+    const detail = [
+      `local ${bootstrap.httpBaseUrl}`,
+      `remote port ${bootstrap.remotePort ?? "unknown"}`,
+      bootstrap.remoteServerKind ? `remote server ${bootstrap.remoteServerKind}` : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${message} (${detail})`);
   });
 }
 
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 538f36227c4..85e1e8f3349 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -153,6 +153,8 @@ export interface DesktopSshEnvironmentBootstrap {
   httpBaseUrl: string;
   wsBaseUrl: string;
   pairingToken: string | null;
+  remotePort?: number;
+  remoteServerKind?: "external" | "managed";
 }
 
 export interface DesktopSshPasswordPromptRequest {
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index e54faba2fd8..7197b18618d 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -71,6 +71,7 @@ interface SshTunnelEntry {
   readonly key: string;
   readonly target: DesktopSshEnvironmentTarget;
   readonly remotePort: number;
+  readonly remoteServerKind: "external" | "managed" | null;
   readonly localPort: number;
   readonly httpBaseUrl: string;
   readonly wsBaseUrl: string;
@@ -152,6 +153,7 @@ export interface SshEnvironmentManagerShape {
 
 const RemoteLaunchResult = Schema.Struct({
   remotePort: Schema.Number,
+  serverKind: Schema.optional(Schema.Literals(["external", "managed"])),
 });
 
 const RemotePairingResult = Schema.Struct({
@@ -451,7 +453,7 @@ if [ -z "$REMOTE_PID" ] || [ -z "$REMOTE_PORT" ]; then
     exit 1
   fi
 fi
-printf '{"remotePort":%s}\\n' "$REMOTE_PORT"
+printf '{"remotePort":%s,"serverKind":"%s"}\\n' "$REMOTE_PORT" "\${REMOTE_MANAGED:-managed}"
 `;
 
 export const REMOTE_PAIRING_SCRIPT = `set -eu
@@ -551,7 +553,7 @@ export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemo
     input?: SshAuthOptions,
     runner?: RemoteT3RunnerOptions,
   ): Effect.fn.Return<
-    number,
+    { readonly remotePort: number; readonly remoteServerKind: "external" | "managed" | null },
     SshCommandError | SshInvalidTargetError | SshLaunchError,
     ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
   > {
@@ -592,9 +594,13 @@ export const launchOrReuseRemoteServer = Effect.fn("ssh/tunnel.launchOrReuseRemo
     yield* Effect.logInfo("ssh.remoteServer.launch.ready", {
       ...sshTargetLogFields(target),
       remotePort: parsed.remotePort,
+      remoteServerKind: parsed.serverKind ?? null,
       stateKey: remoteStateKey(target),
     });
-    return parsed.remotePort;
+    return {
+      remotePort: parsed.remotePort,
+      remoteServerKind: parsed.serverKind ?? null,
+    };
   },
 );
 
@@ -887,7 +893,7 @@ export const fetchLoopbackSshJson = Effect.fn("ssh/tunnel.fetchLoopbackSshJson")
         : text || `SSH forwarded request failed (${response.status}).`;
     return yield* new SshHttpBridgeError({
       status: response.status,
-      message: `[ssh_http:${response.status}] ${message}`,
+      message: `[ssh_http:${response.status}] ${message} (${input.method ?? "GET"} ${requestUrl.toString()})`,
     });
   }
   return (yield* response.json.pipe(
@@ -914,6 +920,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
   readonly httpBaseUrl: string;
   readonly wsBaseUrl: string;
   readonly authOptions: SshAuthOptions;
+  readonly remoteServerKind: "external" | "managed" | null;
 }): Effect.fn.Return<
   SshTunnelEntry,
   SshCommandError | SshInvalidTargetError | SshReadinessError,
@@ -968,6 +975,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     command: tunnelCommand,
     localPort: input.localPort,
     remotePort: input.remotePort,
+    remoteServerKind: input.remoteServerKind,
     httpBaseUrl: input.httpBaseUrl,
   });
   const child = yield* spawner
@@ -1008,6 +1016,7 @@ const startSshTunnel = Effect.fn("ssh/tunnel.startSshTunnel")(function* (input:
     key: input.key,
     target: input.resolvedTarget,
     remotePort: input.remotePort,
+    remoteServerKind: input.remoteServerKind,
     localPort: input.localPort,
     httpBaseUrl: input.httpBaseUrl,
     wsBaseUrl: input.wsBaseUrl,
@@ -1284,16 +1293,18 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       ...sshRunnerLogFields(input.runner),
       key: input.key,
     });
-    const remotePort = yield* runWithSshAuth({
+    const remoteLaunch = yield* runWithSshAuth({
       key: input.key,
       target: input.resolvedTarget,
       operation: (authOptions) =>
         launchOrReuseRemoteServer(input.resolvedTarget, authOptions, input.runner),
     });
+    const remotePort = remoteLaunch.remotePort;
     yield* Effect.logDebug("ssh.environment.remotePort.ready", {
       ...sshTargetLogFields(input.resolvedTarget),
       key: input.key,
       remotePort,
+      remoteServerKind: remoteLaunch.remoteServerKind,
     });
     const localPort = yield* reserveLocalTunnelPort();
     const httpBaseUrl = `http://127.0.0.1:${localPort}/`;
@@ -1317,6 +1328,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
           httpBaseUrl,
           wsBaseUrl,
           authOptions,
+          remoteServerKind: remoteLaunch.remoteServerKind,
         }).pipe(Effect.provideService(Scope.Scope, entryScope)),
     }).pipe(
       Effect.onExit((exit) =>
@@ -1501,6 +1513,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       key,
       localPort: entry.localPort,
       remotePort: entry.remotePort,
+      remoteServerKind: entry.remoteServerKind,
       issuedPairingToken: pairingToken !== null,
     });
     return {
@@ -1508,6 +1521,8 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       httpBaseUrl: entry.httpBaseUrl,
       wsBaseUrl: entry.wsBaseUrl,
       pairingToken,
+      remotePort: entry.remotePort,
+      ...(entry.remoteServerKind ? { remoteServerKind: entry.remoteServerKind } : {}),
     };
   });
 

From 50bd5a1514ff22f3fdd5e77ce153e406c0a9608e Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 21:18:51 -0700
Subject: [PATCH 56/74] Add chat header coverage for hosted pairing UI

- Update desktop main formatting
- Add and adjust ChatHeader tests for pairing state
---
 apps/desktop/src/main.ts                      | 587 ++++++------------
 .../src/components/chat/ChatHeader.test.ts    |  48 ++
 apps/web/src/components/chat/ChatHeader.tsx   |  21 +-
 3 files changed, 244 insertions(+), 412 deletions(-)
 create mode 100644 apps/web/src/components/chat/ChatHeader.test.ts

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 920453756fe..13bae998c8e 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -37,10 +37,7 @@ import type { ContextMenuItem } from "@t3tools/contracts";
 import { RotatingFileSink } from "@t3tools/shared/logging";
 import { parsePersistedServerObservabilitySettings } from "@t3tools/shared/serverSettings";
 import type { RemoteT3RunnerOptions } from "@t3tools/ssh/tunnel";
-import {
-  DEFAULT_DESKTOP_BACKEND_PORT,
-  resolveDesktopBackendPort,
-} from "./backendPort.ts";
+import { DEFAULT_DESKTOP_BACKEND_PORT, resolveDesktopBackendPort } from "./backendPort.ts";
 import {
   type DesktopSettings,
   DEFAULT_DESKTOP_SETTINGS,
@@ -59,25 +56,16 @@ import {
   writeSavedEnvironmentRegistry,
   writeSavedEnvironmentSecret,
 } from "./clientPersistence.ts";
-import {
-  isBackendReadinessAborted,
-  waitForHttpReady,
-} from "./backendReadiness.ts";
+import { isBackendReadinessAborted, waitForHttpReady } from "./backendReadiness.ts";
 import { showDesktopConfirmDialog } from "./confirmDialog.ts";
 import {
   resolveDesktopCoreAdvertisedEndpoints,
   resolveDesktopServerExposure,
 } from "./serverExposure.ts";
-import {
-  DesktopSshEnvironmentBridge,
-  resolveRemoteT3CliPackageSpec,
-} from "./sshEnvironment.ts";
+import { DesktopSshEnvironmentBridge, resolveRemoteT3CliPackageSpec } from "./sshEnvironment.ts";
 import { syncShellEnvironment } from "./syncShellEnvironment.ts";
 import { waitForBackendStartupReady } from "./backendStartupReadiness.ts";
-import {
-  getAutoUpdateDisabledReason,
-  shouldBroadcastDownloadProgress,
-} from "./updateState.ts";
+import { getAutoUpdateDisabledReason, shouldBroadcastDownloadProgress } from "./updateState.ts";
 import { doesVersionMatchDesktopUpdateChannel } from "./updateChannels.ts";
 import { ServerListeningDetector } from "./serverListeningDetector.ts";
 import {
@@ -92,15 +80,9 @@ import {
   reduceDesktopUpdateStateOnNoUpdate,
   reduceDesktopUpdateStateOnUpdateAvailable,
 } from "./updateMachine.ts";
-import {
-  isArm64HostRunningIntelBuild,
-  resolveDesktopRuntimeInfo,
-} from "./runtimeArch.ts";
+import { isArm64HostRunningIntelBuild, resolveDesktopRuntimeInfo } from "./runtimeArch.ts";
 import { resolveDesktopAppBranding } from "./appBranding.ts";
-import {
-  bindFirstRevealTrigger,
-  type RevealSubscription,
-} from "./windowReveal.ts";
+import { bindFirstRevealTrigger, type RevealSubscription } from "./windowReveal.ts";
 import { resolveTailscaleAdvertisedEndpoints } from "./tailscaleEndpointProvider.ts";
 
 syncShellEnvironment();
@@ -118,59 +100,41 @@ const UPDATE_DOWNLOAD_CHANNEL = "desktop:update-download";
 const UPDATE_INSTALL_CHANNEL = "desktop:update-install";
 const UPDATE_CHECK_CHANNEL = "desktop:update-check";
 const GET_APP_BRANDING_CHANNEL = "desktop:get-app-branding";
-const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL =
-  "desktop:get-local-environment-bootstrap";
+const GET_LOCAL_ENVIRONMENT_BOOTSTRAP_CHANNEL = "desktop:get-local-environment-bootstrap";
 const GET_CLIENT_SETTINGS_CHANNEL = "desktop:get-client-settings";
 const SET_CLIENT_SETTINGS_CHANNEL = "desktop:set-client-settings";
-const GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL =
-  "desktop:get-saved-environment-registry";
-const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL =
-  "desktop:set-saved-environment-registry";
-const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL =
-  "desktop:get-saved-environment-secret";
-const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL =
-  "desktop:set-saved-environment-secret";
-const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL =
-  "desktop:remove-saved-environment-secret";
+const GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:get-saved-environment-registry";
+const SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL = "desktop:set-saved-environment-registry";
+const GET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:get-saved-environment-secret";
+const SET_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:set-saved-environment-secret";
+const REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL = "desktop:remove-saved-environment-secret";
 const GET_SERVER_EXPOSURE_STATE_CHANNEL = "desktop:get-server-exposure-state";
 const SET_SERVER_EXPOSURE_MODE_CHANNEL = "desktop:set-server-exposure-mode";
-const SET_TAILSCALE_SERVE_ENABLED_CHANNEL =
-  "desktop:set-tailscale-serve-enabled";
+const SET_TAILSCALE_SERVE_ENABLED_CHANNEL = "desktop:set-tailscale-serve-enabled";
 const GET_ADVERTISED_ENDPOINTS_CHANNEL = "desktop:get-advertised-endpoints";
-const BASE_DIR =
-  process.env.T3CODE_HOME?.trim() || Path.join(OS.homedir(), ".t3");
+const BASE_DIR = process.env.T3CODE_HOME?.trim() || Path.join(OS.homedir(), ".t3");
 const STATE_DIR = Path.join(BASE_DIR, "userdata");
 const DESKTOP_SETTINGS_PATH = Path.join(STATE_DIR, "desktop-settings.json");
 const CLIENT_SETTINGS_PATH = Path.join(STATE_DIR, "client-settings.json");
-const SAVED_ENVIRONMENT_REGISTRY_PATH = Path.join(
-  STATE_DIR,
-  "saved-environments.json",
-);
+const SAVED_ENVIRONMENT_REGISTRY_PATH = Path.join(STATE_DIR, "saved-environments.json");
 const DESKTOP_SCHEME = "t3";
 const ROOT_DIR = Path.resolve(__dirname, "../../..");
 const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
 // Dev-only SSH launcher override. Set this to an absolute path on the SSH host
 // for a built server entry, for example:
 // "/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs"
-const DEV_REMOTE_T3_SERVER_ENTRY_PATH =
-  "/Users/julius/Developer/t3code/apps/server/dist/bin.mjs";
+const DEV_REMOTE_T3_SERVER_ENTRY_PATH = "/Users/julius/Developer/t3code/apps/server/dist/bin.mjs";
 process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ?? "";
 const desktopAppBranding: DesktopAppBranding = resolveDesktopAppBranding({
   isDevelopment,
   appVersion: app.getVersion(),
 });
 const APP_DISPLAY_NAME = desktopAppBranding.displayName;
-const APP_USER_MODEL_ID = isDevelopment
-  ? "com.t3tools.t3code.dev"
-  : "com.t3tools.t3code";
-const LINUX_DESKTOP_ENTRY_NAME = isDevelopment
-  ? "t3code-dev.desktop"
-  : "t3code.desktop";
+const APP_USER_MODEL_ID = isDevelopment ? "com.t3tools.t3code.dev" : "com.t3tools.t3code";
+const LINUX_DESKTOP_ENTRY_NAME = isDevelopment ? "t3code-dev.desktop" : "t3code.desktop";
 const LINUX_WM_CLASS = isDevelopment ? "t3code-dev" : "t3code";
 const USER_DATA_DIR_NAME = isDevelopment ? "t3code-dev" : "t3code";
-const LEGACY_USER_DATA_DIR_NAME = isDevelopment
-  ? "T3 Code (Dev)"
-  : "T3 Code (Alpha)";
+const LEGACY_USER_DATA_DIR_NAME = isDevelopment ? "T3 Code (Dev)" : "T3 Code (Alpha)";
 const COMMIT_HASH_PATTERN = /^[0-9a-f]{7,40}$/i;
 const COMMIT_HASH_DISPLAY_LENGTH = 12;
 const LOG_DIR = Path.join(STATE_DIR, "logs");
@@ -213,16 +177,11 @@ const TITLEBAR_COLOR = "#01000000"; // #00000000 does not work correctly on Linu
 const TITLEBAR_LIGHT_SYMBOL_COLOR = "#1f2937";
 const TITLEBAR_DARK_SYMBOL_COLOR = "#f8fafc";
 
-function normalizeContextMenuItems(
-  source: readonly ContextMenuItem[],
-): ContextMenuItem[] {
+function normalizeContextMenuItems(source: readonly ContextMenuItem[]): ContextMenuItem[] {
   const normalizedItems: ContextMenuItem[] = [];
 
   for (const sourceItem of source) {
-    if (
-      typeof sourceItem.id !== "string" ||
-      typeof sourceItem.label !== "string"
-    ) {
+    if (typeof sourceItem.id !== "string" || typeof sourceItem.label !== "string") {
       continue;
     }
 
@@ -278,12 +237,8 @@ let desktopLogSink: RotatingFileSink | null = null;
 let backendLogSink: RotatingFileSink | null = null;
 let restoreStdIoCapture: (() => void) | null = null;
 let backendObservabilitySettings = readPersistedBackendObservabilitySettings();
-let desktopSettings = readDesktopSettings(
-  DESKTOP_SETTINGS_PATH,
-  app.getVersion(),
-);
-let desktopServerExposureMode: DesktopServerExposureMode =
-  desktopSettings.serverExposureMode;
+let desktopSettings = readDesktopSettings(DESKTOP_SETTINGS_PATH, app.getVersion());
+let desktopServerExposureMode: DesktopServerExposureMode = desktopSettings.serverExposureMode;
 
 let destructiveMenuIconCache: Electron.NativeImage | null | undefined;
 const expectedBackendExitChildren = new WeakSet<ChildProcess.ChildProcess>();
@@ -319,21 +274,14 @@ function readPersistedBackendObservabilitySettings(): {
     if (!FS.existsSync(SERVER_SETTINGS_PATH)) {
       return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
     }
-    return parsePersistedServerObservabilitySettings(
-      FS.readFileSync(SERVER_SETTINGS_PATH, "utf8"),
-    );
+    return parsePersistedServerObservabilitySettings(FS.readFileSync(SERVER_SETTINGS_PATH, "utf8"));
   } catch (error) {
-    console.warn(
-      "[desktop] failed to read persisted backend observability settings",
-      error,
-    );
+    console.warn("[desktop] failed to read persisted backend observability settings", error);
     return { otlpTracesUrl: undefined, otlpMetricsUrl: undefined };
   }
 }
 
-function resolveConfiguredDesktopBackendPort(
-  rawPort: string | undefined,
-): number | undefined {
+function resolveConfiguredDesktopBackendPort(rawPort: string | undefined): number | undefined {
   if (!rawPort) {
     return undefined;
   }
@@ -385,9 +333,7 @@ async function getDesktopAdvertisedEndpoints() {
     mode: desktopServerExposureMode,
     port: backendPort,
     networkInterfaces: OS.networkInterfaces(),
-    ...(backendAdvertisedHost
-      ? { advertisedHostOverride: backendAdvertisedHost }
-      : {}),
+    ...(backendAdvertisedHost ? { advertisedHostOverride: backendAdvertisedHost } : {}),
   });
   const coreEndpoints = resolveDesktopCoreAdvertisedEndpoints({
     port: backendPort,
@@ -441,9 +387,7 @@ async function applyDesktopServerExposureMode(
 
   if (requestedMode === "network-accessible" && exposure.endpointUrl === null) {
     if (options?.rejectIfUnavailable) {
-      throw new Error(
-        "No reachable network address is available for this desktop right now.",
-      );
+      throw new Error("No reachable network address is available for this desktop right now.");
     }
     exposure = resolveDesktopServerExposure({
       mode: "local-only",
@@ -454,10 +398,7 @@ async function applyDesktopServerExposureMode(
   }
 
   desktopServerExposureMode = exposure.mode;
-  desktopSettings = setDesktopServerExposurePreference(
-    desktopSettings,
-    requestedMode,
-  );
+  desktopSettings = setDesktopServerExposurePreference(desktopSettings, requestedMode);
   backendBindHost = exposure.bindHost;
   backendHttpUrl = exposure.localHttpUrl;
   backendWsUrl = exposure.localWsUrl;
@@ -477,9 +418,7 @@ async function applyDesktopTailscaleServeEnabled(
   desktopSettings = nextSettings;
   writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
   relaunchDesktopApp(
-    desktopSettings.tailscaleServeEnabled
-      ? "tailscale-serve-enabled"
-      : "tailscale-serve-disabled",
+    desktopSettings.tailscaleServeEnabled ? "tailscale-serve-enabled" : "tailscale-serve-disabled",
   );
   return getDesktopServerExposureState();
 }
@@ -514,15 +453,10 @@ function relaunchDesktopApp(reason: string): void {
 
 function writeDesktopLogHeader(message: string): void {
   if (!desktopLogSink) return;
-  desktopLogSink.write(
-    `[${logTimestamp()}] [${logScope("desktop")}] ${message}\n`,
-  );
+  desktopLogSink.write(`[${logTimestamp()}] [${logScope("desktop")}] ${message}\n`);
 }
 
-function writeBackendSessionBoundary(
-  phase: "START" | "END",
-  details: string,
-): void {
+function writeBackendSessionBoundary(phase: "START" | "END", details: string): void {
   if (!backendLogSink) return;
   const normalizedDetails = sanitizeLogValue(details);
   backendLogSink.write(
@@ -589,9 +523,7 @@ function cancelBackendReadinessWait(): void {
   backendReadinessAbortController = null;
 }
 
-async function waitForBackendWindowReady(
-  baseUrl: string,
-): Promise<"listening" | "http"> {
+async function waitForBackendWindowReady(baseUrl: string): Promise<"listening" | "http"> {
   return await waitForBackendStartupReady({
     listeningPromise: backendListeningDetector?.promise ?? null,
     waitForHttpReady: () =>
@@ -604,11 +536,7 @@ async function waitForBackendWindowReady(
 
 function ensureInitialBackendWindowOpen(): void {
   const existingWindow = mainWindow ?? BrowserWindow.getAllWindows()[0] ?? null;
-  if (
-    isDevelopment ||
-    existingWindow !== null ||
-    backendInitialWindowOpenInFlight !== null
-  ) {
+  if (isDevelopment || existingWindow !== null || backendInitialWindowOpenInFlight !== null) {
     return;
   }
 
@@ -628,10 +556,7 @@ function ensureInitialBackendWindowOpen(): void {
       writeDesktopLogHeader(
         `bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
       );
-      console.warn(
-        "[desktop] backend readiness check timed out during packaged bootstrap",
-        error,
-      );
+      console.warn("[desktop] backend readiness check timed out during packaged bootstrap", error);
     })
     .finally(() => {
       if (backendInitialWindowOpenInFlight === nextOpen) {
@@ -650,10 +575,7 @@ function writeDesktopStreamChunk(
   if (!desktopLogSink) return;
   const buffer = Buffer.isBuffer(chunk)
     ? chunk
-    : Buffer.from(
-        String(chunk),
-        typeof chunk === "string" ? encoding : undefined,
-      );
+    : Buffer.from(String(chunk), typeof chunk === "string" ? encoding : undefined);
   desktopLogSink.write(`[${logTimestamp()}] [${logScope(streamName)}] `);
   desktopLogSink.write(buffer);
   if (buffer.length === 0 || buffer[buffer.length - 1] !== 0x0a) {
@@ -662,11 +584,7 @@ function writeDesktopStreamChunk(
 }
 
 function installStdIoCapture(): void {
-  if (
-    !app.isPackaged ||
-    desktopLogSink === null ||
-    restoreStdIoCapture !== null
-  ) {
+  if (!app.isPackaged || desktopLogSink === null || restoreStdIoCapture !== null) {
     return;
   }
 
@@ -674,17 +592,13 @@ function installStdIoCapture(): void {
   const originalStderrWrite = process.stderr.write.bind(process.stderr);
 
   const patchWrite =
-    (
-      streamName: "stdout" | "stderr",
-      originalWrite: typeof process.stdout.write,
-    ) =>
+    (streamName: "stdout" | "stderr", originalWrite: typeof process.stdout.write) =>
     (
       chunk: string | Uint8Array,
       encodingOrCallback?: BufferEncoding | ((error?: Error | null) => void),
       callback?: (error?: Error | null) => void,
     ): boolean => {
-      const encoding =
-        typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
+      const encoding = typeof encodingOrCallback === "string" ? encodingOrCallback : undefined;
       writeDesktopStreamChunk(streamName, chunk, encoding);
       if (typeof encodingOrCallback === "function") {
         return originalWrite(chunk, encodingOrCallback);
@@ -730,13 +644,9 @@ function initializePackagedLogging(): void {
 }
 
 function captureBackendOutput(child: ChildProcess.ChildProcess): void {
-  const attachStream = (
-    stream: NodeJS.ReadableStream | null | undefined,
-  ): void => {
+  const attachStream = (stream: NodeJS.ReadableStream | null | undefined): void => {
     stream?.on("data", (chunk: unknown) => {
-      const buffer = Buffer.isBuffer(chunk)
-        ? chunk
-        : Buffer.from(String(chunk), "utf8");
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk), "utf8");
       backendLogSink?.write(buffer);
       backendListeningDetector?.push(buffer);
     });
@@ -921,10 +831,7 @@ function resolveDesktopStaticDir(): string | null {
   return null;
 }
 
-function resolveDesktopStaticPath(
-  staticRoot: string,
-  requestUrl: string,
-): string {
+function resolveDesktopStaticPath(staticRoot: string, requestUrl: string): string {
   const url = new URL(requestUrl);
   const rawPath = decodeURIComponent(url.pathname);
   const normalizedPath = Path.posix.normalize(rawPath).replace(/^\/+/, "");
@@ -932,8 +839,7 @@ function resolveDesktopStaticPath(
     return Path.join(staticRoot, "index.html");
   }
 
-  const requestedPath =
-    normalizedPath.length > 0 ? normalizedPath : "index.html";
+  const requestedPath = normalizedPath.length > 0 ? normalizedPath : "index.html";
   const resolvedPath = Path.join(staticRoot, requestedPath);
 
   if (Path.extname(resolvedPath)) {
@@ -960,19 +866,12 @@ function isStaticAssetRequest(requestUrl: string): boolean {
 function handleFatalStartupError(stage: string, error: unknown): void {
   const message = formatErrorMessage(error);
   const detail =
-    error instanceof Error && typeof error.stack === "string"
-      ? `\n${error.stack}`
-      : "";
-  writeDesktopLogHeader(
-    `fatal startup error stage=${stage} message=${message}`,
-  );
+    error instanceof Error && typeof error.stack === "string" ? `\n${error.stack}` : "";
+  writeDesktopLogHeader(`fatal startup error stage=${stage} message=${message}`);
   console.error(`[desktop] fatal startup error (${stage})`, error);
   if (!isQuitting) {
     isQuitting = true;
-    dialog.showErrorBox(
-      "T3 Code failed to start",
-      `Stage: ${stage}\n${message}${detail}`,
-    );
+    dialog.showErrorBox("T3 Code failed to start", `Stage: ${stage}\n${message}${detail}`);
   }
   stopBackend();
   restoreStdIoCapture?.();
@@ -995,14 +894,10 @@ function registerDesktopProtocol(): void {
 
   protocol.registerFileProtocol(DESKTOP_SCHEME, (request, callback) => {
     try {
-      const candidate = resolveDesktopStaticPath(
-        staticRootResolved,
-        request.url,
-      );
+      const candidate = resolveDesktopStaticPath(staticRootResolved, request.url);
       const resolvedCandidate = Path.resolve(candidate);
       const isInRoot =
-        resolvedCandidate === fallbackIndex ||
-        resolvedCandidate.startsWith(staticRootPrefix);
+        resolvedCandidate === fallbackIndex || resolvedCandidate.startsWith(staticRootPrefix);
       const isAssetRequest = isStaticAssetRequest(request.url);
 
       if (!isInRoot || !FS.existsSync(resolvedCandidate)) {
@@ -1025,9 +920,7 @@ function registerDesktopProtocol(): void {
 
 function dispatchMenuAction(action: string): void {
   const existingWindow =
-    BrowserWindow.getFocusedWindow() ??
-    mainWindow ??
-    BrowserWindow.getAllWindows()[0];
+    BrowserWindow.getFocusedWindow() ?? mainWindow ?? BrowserWindow.getAllWindows()[0];
   const targetWindow = existingWindow ?? createWindow();
   if (!existingWindow) {
     mainWindow = targetWindow;
@@ -1049,8 +942,7 @@ function dispatchMenuAction(action: string): void {
 
 function handleCheckForUpdatesMenuClick(): void {
   const hasUpdateFeedConfig =
-    readAppUpdateYml() !== null ||
-    Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
+    readAppUpdateYml() !== null || Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
   const disabledReason = getAutoUpdateDisabledReason({
     isDevelopment,
     isPackaged: app.isPackaged,
@@ -1060,9 +952,7 @@ function handleCheckForUpdatesMenuClick(): void {
     hasUpdateFeedConfig,
   });
   if (disabledReason) {
-    console.info(
-      "[desktop-updater] Manual update check requested, but updates are disabled.",
-    );
+    console.info("[desktop-updater] Manual update check requested, but updates are disabled.");
     void dialog.showMessageBox({
       type: "info",
       title: "Updates unavailable",
@@ -1094,9 +984,7 @@ async function checkForUpdatesFromMenu(): Promise<void> {
       type: "warning",
       title: "Update check failed",
       message: "Could not check for updates.",
-      detail:
-        updateState.message ??
-        "An unknown error occurred. Please try again later.",
+      detail: updateState.message ?? "An unknown error occurred. Please try again later.",
       buttons: ["OK"],
     });
   }
@@ -1314,11 +1202,7 @@ function createBaseUpdateState(
   enabled: boolean,
 ): DesktopUpdateState {
   return {
-    ...createInitialDesktopUpdateState(
-      app.getVersion(),
-      desktopRuntimeInfo,
-      channel,
-    ),
+    ...createInitialDesktopUpdateState(app.getVersion(), desktopRuntimeInfo, channel),
     enabled,
     status: enabled ? "idle" : "disabled",
   };
@@ -1335,8 +1219,7 @@ function applyAutoUpdaterChannel(channel: DesktopUpdateChannel): void {
 
 function shouldEnableAutoUpdates(): boolean {
   const hasUpdateFeedConfig =
-    readAppUpdateYml() !== null ||
-    Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
+    readAppUpdateYml() !== null || Boolean(process.env.T3CODE_DESKTOP_MOCK_UPDATES);
   return (
     getAutoUpdateDisabledReason({
       isDevelopment,
@@ -1351,19 +1234,14 @@ function shouldEnableAutoUpdates(): boolean {
 
 async function checkForUpdates(reason: string): Promise<boolean> {
   if (isQuitting || !updaterConfigured || updateCheckInFlight) return false;
-  if (
-    updateState.status === "downloading" ||
-    updateState.status === "downloaded"
-  ) {
+  if (updateState.status === "downloading" || updateState.status === "downloaded") {
     console.info(
       `[desktop-updater] Skipping update check (${reason}) while status=${updateState.status}.`,
     );
     return false;
   }
   updateCheckInFlight = true;
-  setUpdateState(
-    reduceDesktopUpdateStateOnCheckStart(updateState, new Date().toISOString()),
-  );
+  setUpdateState(reduceDesktopUpdateStateOnCheckStart(updateState, new Date().toISOString()));
   console.info(`[desktop-updater] Checking for updates (${reason})...`);
 
   try {
@@ -1372,11 +1250,7 @@ async function checkForUpdates(reason: string): Promise<boolean> {
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
     setUpdateState(
-      reduceDesktopUpdateStateOnCheckFailure(
-        updateState,
-        message,
-        new Date().toISOString(),
-      ),
+      reduceDesktopUpdateStateOnCheckFailure(updateState, message, new Date().toISOString()),
     );
     console.error(`[desktop-updater] Failed to check for updates: ${message}`);
     return true;
@@ -1389,17 +1263,12 @@ async function downloadAvailableUpdate(): Promise<{
   accepted: boolean;
   completed: boolean;
 }> {
-  if (
-    !updaterConfigured ||
-    updateDownloadInFlight ||
-    updateState.status !== "available"
-  ) {
+  if (!updaterConfigured || updateDownloadInFlight || updateState.status !== "available") {
     return { accepted: false, completed: false };
   }
   updateDownloadInFlight = true;
   setUpdateState(reduceDesktopUpdateStateOnDownloadStart(updateState));
-  autoUpdater.disableDifferentialDownload =
-    isArm64HostRunningIntelBuild(desktopRuntimeInfo);
+  autoUpdater.disableDifferentialDownload = isArm64HostRunningIntelBuild(desktopRuntimeInfo);
   console.info("[desktop-updater] Downloading update...");
 
   try {
@@ -1407,9 +1276,7 @@ async function downloadAvailableUpdate(): Promise<{
     return { accepted: true, completed: true };
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);
-    setUpdateState(
-      reduceDesktopUpdateStateOnDownloadFailure(updateState, message),
-    );
+    setUpdateState(reduceDesktopUpdateStateOnDownloadFailure(updateState, message));
     console.error(`[desktop-updater] Failed to download update: ${message}`);
     return { accepted: true, completed: false };
   } finally {
@@ -1443,9 +1310,7 @@ async function installDownloadedUpdate(): Promise<{
     const message = formatErrorMessage(error);
     updateInstallInFlight = false;
     isQuitting = false;
-    setUpdateState(
-      reduceDesktopUpdateStateOnInstallFailure(updateState, message),
-    );
+    setUpdateState(reduceDesktopUpdateStateOnInstallFailure(updateState, message));
     console.error(`[desktop-updater] Failed to install update: ${message}`);
     return { accepted: true, completed: false };
   }
@@ -1453,9 +1318,7 @@ async function installDownloadedUpdate(): Promise<{
 
 function configureAutoUpdater(): void {
   const githubToken =
-    process.env.T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN?.trim() ||
-    process.env.GH_TOKEN?.trim() ||
-    "";
+    process.env.T3CODE_DESKTOP_UPDATE_GITHUB_TOKEN?.trim() || process.env.GH_TOKEN?.trim() || "";
   if (githubToken) {
     // When a token is provided, re-configure the feed with `private: true` so
     // electron-updater uses the GitHub API (api.github.com) instead of the
@@ -1488,8 +1351,7 @@ function configureAutoUpdater(): void {
   autoUpdater.autoDownload = false;
   autoUpdater.autoInstallOnAppQuit = false;
   applyAutoUpdaterChannel(desktopSettings.updateChannel);
-  autoUpdater.disableDifferentialDownload =
-    isArm64HostRunningIntelBuild(desktopRuntimeInfo);
+  autoUpdater.disableDifferentialDownload = isArm64HostRunningIntelBuild(desktopRuntimeInfo);
   let lastLoggedDownloadMilestone = -1;
 
   if (isArm64HostRunningIntelBuild(desktopRuntimeInfo)) {
@@ -1502,18 +1364,11 @@ function configureAutoUpdater(): void {
     console.info("[desktop-updater] Looking for updates...");
   });
   autoUpdater.on("update-available", (info) => {
-    if (
-      !doesVersionMatchDesktopUpdateChannel(info.version, updateState.channel)
-    ) {
+    if (!doesVersionMatchDesktopUpdateChannel(info.version, updateState.channel)) {
       console.info(
         `[desktop-updater] Ignoring ${info.version} because it does not match the selected '${updateState.channel}' channel.`,
       );
-      setUpdateState(
-        reduceDesktopUpdateStateOnNoUpdate(
-          updateState,
-          new Date().toISOString(),
-        ),
-      );
+      setUpdateState(reduceDesktopUpdateStateOnNoUpdate(updateState, new Date().toISOString()));
       lastLoggedDownloadMilestone = -1;
       return;
     }
@@ -1529,9 +1384,7 @@ function configureAutoUpdater(): void {
     console.info(`[desktop-updater] Update available: ${info.version}`);
   });
   autoUpdater.on("update-not-available", () => {
-    setUpdateState(
-      reduceDesktopUpdateStateOnNoUpdate(updateState, new Date().toISOString()),
-    );
+    setUpdateState(reduceDesktopUpdateStateOnNoUpdate(updateState, new Date().toISOString()));
     lastLoggedDownloadMilestone = -1;
     console.info("[desktop-updater] No updates available.");
   });
@@ -1540,9 +1393,7 @@ function configureAutoUpdater(): void {
     if (updateInstallInFlight) {
       updateInstallInFlight = false;
       isQuitting = false;
-      setUpdateState(
-        reduceDesktopUpdateStateOnInstallFailure(updateState, message),
-      );
+      setUpdateState(reduceDesktopUpdateStateOnInstallFailure(updateState, message));
       console.error(`[desktop-updater] Updater error: ${message}`);
       return;
     }
@@ -1553,9 +1404,7 @@ function configureAutoUpdater(): void {
         checkedAt: new Date().toISOString(),
         downloadPercent: null,
         errorContext: resolveUpdaterErrorContext(),
-        canRetry:
-          updateState.availableVersion !== null ||
-          updateState.downloadedVersion !== null,
+        canRetry: updateState.availableVersion !== null || updateState.downloadedVersion !== null,
       });
     }
     console.error(`[desktop-updater] Updater error: ${message}`);
@@ -1566,12 +1415,7 @@ function configureAutoUpdater(): void {
       shouldBroadcastDownloadProgress(updateState, progress.percent) ||
       updateState.message !== null
     ) {
-      setUpdateState(
-        reduceDesktopUpdateStateOnDownloadProgress(
-          updateState,
-          progress.percent,
-        ),
-      );
+      setUpdateState(reduceDesktopUpdateStateOnDownloadProgress(updateState, progress.percent));
     }
     const milestone = percent - (percent % 10);
     if (milestone > lastLoggedDownloadMilestone) {
@@ -1580,9 +1424,7 @@ function configureAutoUpdater(): void {
     }
   });
   autoUpdater.on("update-downloaded", (info) => {
-    setUpdateState(
-      reduceDesktopUpdateStateOnDownloadComplete(updateState, info.version),
-    );
+    setUpdateState(reduceDesktopUpdateStateOnDownloadComplete(updateState, info.version));
     console.info(`[desktop-updater] Update downloaded: ${info.version}`);
   });
 
@@ -1604,9 +1446,7 @@ function scheduleBackendRestart(reason: string): void {
 
   const delayMs = Math.min(500 * 2 ** restartAttempt, 10_000);
   restartAttempt += 1;
-  console.error(
-    `[desktop] backend exited unexpectedly (${reason}); restarting in ${delayMs}ms`,
-  );
+  console.error(`[desktop] backend exited unexpectedly (${reason}); restarting in ${delayMs}ms`);
 
   restartTimer = setTimeout(() => {
     restartTimer = null;
@@ -1625,22 +1465,18 @@ function startBackend(): void {
   }
 
   const captureBackendLogs = !isDevelopment;
-  const child = ChildProcess.spawn(
-    process.execPath,
-    [backendEntry, "--bootstrap-fd", "3"],
-    {
-      cwd: resolveBackendCwd(),
-      // In Electron main, process.execPath points to the Electron binary.
-      // Run the child in Node mode so this backend process does not become a GUI app instance.
-      env: {
-        ...backendChildEnv(),
-        ELECTRON_RUN_AS_NODE: "1",
-      },
-      stdio: captureBackendLogs
-        ? ["ignore", "pipe", "pipe", "pipe"]
-        : ["ignore", "inherit", "inherit", "pipe"],
+  const child = ChildProcess.spawn(process.execPath, [backendEntry, "--bootstrap-fd", "3"], {
+    cwd: resolveBackendCwd(),
+    // In Electron main, process.execPath points to the Electron binary.
+    // Run the child in Node mode so this backend process does not become a GUI app instance.
+    env: {
+      ...backendChildEnv(),
+      ELECTRON_RUN_AS_NODE: "1",
     },
-  );
+    stdio: captureBackendLogs
+      ? ["ignore", "pipe", "pipe", "pipe"]
+      : ["ignore", "inherit", "inherit", "pipe"],
+  });
   const bootstrapStream = child.stdio[3];
   if (bootstrapStream && "write" in bootstrapStream) {
     bootstrapStream.write(
@@ -1760,8 +1596,7 @@ async function stopBackendAndWaitForExit(timeoutMs = 5_000): Promise<void> {
   backendProcess = null;
   if (!child) return;
   const backendChild = child;
-  if (backendChild.exitCode !== null || backendChild.signalCode !== null)
-    return;
+  if (backendChild.exitCode !== null || backendChild.signalCode !== null) return;
   expectedBackendExitChildren.add(backendChild);
 
   await new Promise<void>((resolve) => {
@@ -1820,21 +1655,16 @@ function registerIpcHandlers(): void {
   });
 
   ipcMain.removeHandler(GET_CLIENT_SETTINGS_CHANNEL);
-  ipcMain.handle(GET_CLIENT_SETTINGS_CHANNEL, async () =>
-    readClientSettings(CLIENT_SETTINGS_PATH),
-  );
+  ipcMain.handle(GET_CLIENT_SETTINGS_CHANNEL, async () => readClientSettings(CLIENT_SETTINGS_PATH));
 
   ipcMain.removeHandler(SET_CLIENT_SETTINGS_CHANNEL);
-  ipcMain.handle(
-    SET_CLIENT_SETTINGS_CHANNEL,
-    async (_event, rawSettings: unknown) => {
-      if (typeof rawSettings !== "object" || rawSettings === null) {
-        throw new Error("Invalid client settings payload.");
-      }
+  ipcMain.handle(SET_CLIENT_SETTINGS_CHANNEL, async (_event, rawSettings: unknown) => {
+    if (typeof rawSettings !== "object" || rawSettings === null) {
+      throw new Error("Invalid client settings payload.");
+    }
 
-      writeClientSettings(CLIENT_SETTINGS_PATH, rawSettings as ClientSettings);
-    },
-  );
+    writeClientSettings(CLIENT_SETTINGS_PATH, rawSettings as ClientSettings);
+  });
 
   ipcMain.removeHandler(GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL);
   ipcMain.handle(GET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL, async () =>
@@ -1842,28 +1672,22 @@ function registerIpcHandlers(): void {
   );
 
   ipcMain.removeHandler(SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL);
-  ipcMain.handle(
-    SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL,
-    async (_event, rawRecords: unknown) => {
-      if (!Array.isArray(rawRecords)) {
-        throw new Error("Invalid saved environment registry payload.");
-      }
+  ipcMain.handle(SET_SAVED_ENVIRONMENT_REGISTRY_CHANNEL, async (_event, rawRecords: unknown) => {
+    if (!Array.isArray(rawRecords)) {
+      throw new Error("Invalid saved environment registry payload.");
+    }
 
-      writeSavedEnvironmentRegistry(
-        SAVED_ENVIRONMENT_REGISTRY_PATH,
-        rawRecords as readonly PersistedSavedEnvironmentRecord[],
-      );
-    },
-  );
+    writeSavedEnvironmentRegistry(
+      SAVED_ENVIRONMENT_REGISTRY_PATH,
+      rawRecords as readonly PersistedSavedEnvironmentRecord[],
+    );
+  });
 
   ipcMain.removeHandler(GET_SAVED_ENVIRONMENT_SECRET_CHANNEL);
   ipcMain.handle(
     GET_SAVED_ENVIRONMENT_SECRET_CHANNEL,
     async (_event, rawEnvironmentId: unknown) => {
-      if (
-        typeof rawEnvironmentId !== "string" ||
-        rawEnvironmentId.trim().length === 0
-      ) {
+      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
         return null;
       }
 
@@ -1879,10 +1703,7 @@ function registerIpcHandlers(): void {
   ipcMain.handle(
     SET_SAVED_ENVIRONMENT_SECRET_CHANNEL,
     async (_event, rawEnvironmentId: unknown, rawSecret: unknown) => {
-      if (
-        typeof rawEnvironmentId !== "string" ||
-        rawEnvironmentId.trim().length === 0
-      ) {
+      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
         throw new Error("Invalid saved environment id.");
       }
       if (typeof rawSecret !== "string" || rawSecret.trim().length === 0) {
@@ -1902,10 +1723,7 @@ function registerIpcHandlers(): void {
   ipcMain.handle(
     REMOVE_SAVED_ENVIRONMENT_SECRET_CHANNEL,
     async (_event, rawEnvironmentId: unknown) => {
-      if (
-        typeof rawEnvironmentId !== "string" ||
-        rawEnvironmentId.trim().length === 0
-      ) {
+      if (typeof rawEnvironmentId !== "string" || rawEnvironmentId.trim().length === 0) {
         return;
       }
 
@@ -1919,61 +1737,51 @@ function registerIpcHandlers(): void {
   desktopSshEnvironmentBridge.registerIpcHandlers(ipcMain);
 
   ipcMain.removeHandler(GET_SERVER_EXPOSURE_STATE_CHANNEL);
-  ipcMain.handle(GET_SERVER_EXPOSURE_STATE_CHANNEL, async () =>
-    getDesktopServerExposureState(),
-  );
+  ipcMain.handle(GET_SERVER_EXPOSURE_STATE_CHANNEL, async () => getDesktopServerExposureState());
 
   ipcMain.removeHandler(SET_SERVER_EXPOSURE_MODE_CHANNEL);
-  ipcMain.handle(
-    SET_SERVER_EXPOSURE_MODE_CHANNEL,
-    async (_event, rawMode: unknown) => {
-      if (rawMode !== "local-only" && rawMode !== "network-accessible") {
-        throw new Error("Invalid desktop server exposure input.");
-      }
+  ipcMain.handle(SET_SERVER_EXPOSURE_MODE_CHANNEL, async (_event, rawMode: unknown) => {
+    if (rawMode !== "local-only" && rawMode !== "network-accessible") {
+      throw new Error("Invalid desktop server exposure input.");
+    }
 
-      const nextMode = rawMode as DesktopServerExposureMode;
-      if (nextMode === desktopServerExposureMode) {
-        return getDesktopServerExposureState();
-      }
+    const nextMode = rawMode as DesktopServerExposureMode;
+    if (nextMode === desktopServerExposureMode) {
+      return getDesktopServerExposureState();
+    }
 
-      const nextState = await applyDesktopServerExposureMode(nextMode, {
-        persist: true,
-        rejectIfUnavailable: true,
-      });
-      relaunchDesktopApp(`serverExposureMode=${nextMode}`);
-      return nextState;
-    },
-  );
+    const nextState = await applyDesktopServerExposureMode(nextMode, {
+      persist: true,
+      rejectIfUnavailable: true,
+    });
+    relaunchDesktopApp(`serverExposureMode=${nextMode}`);
+    return nextState;
+  });
 
   ipcMain.removeHandler(SET_TAILSCALE_SERVE_ENABLED_CHANNEL);
-  ipcMain.handle(
-    SET_TAILSCALE_SERVE_ENABLED_CHANNEL,
-    async (_event, rawInput: unknown) => {
-      if (typeof rawInput !== "object" || rawInput === null) {
-        throw new Error("Invalid Tailscale Serve input.");
-      }
-      const input = rawInput as {
-        readonly enabled?: unknown;
-        readonly port?: unknown;
-      };
-      if (typeof input.enabled !== "boolean") {
-        throw new Error("Invalid Tailscale Serve input.");
-      }
-      const nextSettings = setDesktopTailscaleServePreference(desktopSettings, {
-        enabled: input.enabled,
-        ...(typeof input.port === "number" ? { port: input.port } : {}),
-      });
-      if (nextSettings === desktopSettings) {
-        return getDesktopServerExposureState();
-      }
-      return applyDesktopTailscaleServeEnabled(nextSettings);
-    },
-  );
+  ipcMain.handle(SET_TAILSCALE_SERVE_ENABLED_CHANNEL, async (_event, rawInput: unknown) => {
+    if (typeof rawInput !== "object" || rawInput === null) {
+      throw new Error("Invalid Tailscale Serve input.");
+    }
+    const input = rawInput as {
+      readonly enabled?: unknown;
+      readonly port?: unknown;
+    };
+    if (typeof input.enabled !== "boolean") {
+      throw new Error("Invalid Tailscale Serve input.");
+    }
+    const nextSettings = setDesktopTailscaleServePreference(desktopSettings, {
+      enabled: input.enabled,
+      ...(typeof input.port === "number" ? { port: input.port } : {}),
+    });
+    if (nextSettings === desktopSettings) {
+      return getDesktopServerExposureState();
+    }
+    return applyDesktopTailscaleServeEnabled(nextSettings);
+  });
 
   ipcMain.removeHandler(GET_ADVERTISED_ENDPOINTS_CHANNEL);
-  ipcMain.handle(GET_ADVERTISED_ENDPOINTS_CHANNEL, async () =>
-    getDesktopAdvertisedEndpoints(),
-  );
+  ipcMain.handle(GET_ADVERTISED_ENDPOINTS_CHANNEL, async () => getDesktopAdvertisedEndpoints());
 
   ipcMain.removeHandler(PICK_FOLDER_CHANNEL);
   ipcMain.handle(PICK_FOLDER_CHANNEL, async (_event, rawOptions: unknown) => {
@@ -2013,11 +1821,7 @@ function registerIpcHandlers(): void {
   ipcMain.removeHandler(CONTEXT_MENU_CHANNEL);
   ipcMain.handle(
     CONTEXT_MENU_CHANNEL,
-    async (
-      _event,
-      items: ContextMenuItem[],
-      position?: { x: number; y: number },
-    ) => {
+    async (_event, items: ContextMenuItem[], position?: { x: number; y: number }) => {
       const normalizedItems = normalizeContextMenuItems(items);
       if (normalizedItems.length === 0) {
         return null;
@@ -2045,11 +1849,7 @@ function registerIpcHandlers(): void {
           const template: MenuItemConstructorOptions[] = [];
           let hasInsertedDestructiveSeparator = false;
           for (const item of entries) {
-            if (
-              item.destructive &&
-              !hasInsertedDestructiveSeparator &&
-              template.length > 0
-            ) {
+            if (item.destructive && !hasInsertedDestructiveSeparator && template.length > 0) {
               template.push({ type: "separator" });
               hasInsertedDestructiveSeparator = true;
             }
@@ -2062,10 +1862,7 @@ function registerIpcHandlers(): void {
             } else {
               itemOption.click = () => resolve(item.id);
             }
-            if (
-              item.destructive &&
-              (!item.children || item.children.length === 0)
-            ) {
+            if (item.destructive && (!item.children || item.children.length === 0)) {
               const destructiveIcon = getDestructiveMenuIcon();
               if (destructiveIcon) {
                 itemOption.icon = destructiveIcon;
@@ -2105,53 +1902,41 @@ function registerIpcHandlers(): void {
   ipcMain.handle(UPDATE_GET_STATE_CHANNEL, async () => updateState);
 
   ipcMain.removeHandler(UPDATE_SET_CHANNEL_CHANNEL);
-  ipcMain.handle(
-    UPDATE_SET_CHANNEL_CHANNEL,
-    async (_event, rawChannel: unknown) => {
-      if (rawChannel !== "latest" && rawChannel !== "nightly") {
-        throw new Error("Invalid desktop update channel input.");
-      }
-      if (
-        updateCheckInFlight ||
-        updateDownloadInFlight ||
-        updateInstallInFlight
-      ) {
-        throw new Error(
-          "Cannot change update tracks while an update action is in progress.",
-        );
-      }
-
-      const nextChannel = rawChannel as DesktopUpdateChannel;
+  ipcMain.handle(UPDATE_SET_CHANNEL_CHANNEL, async (_event, rawChannel: unknown) => {
+    if (rawChannel !== "latest" && rawChannel !== "nightly") {
+      throw new Error("Invalid desktop update channel input.");
+    }
+    if (updateCheckInFlight || updateDownloadInFlight || updateInstallInFlight) {
+      throw new Error("Cannot change update tracks while an update action is in progress.");
+    }
 
-      desktopSettings = setDesktopUpdateChannelPreference(
-        desktopSettings,
-        nextChannel,
-      );
-      writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
+    const nextChannel = rawChannel as DesktopUpdateChannel;
 
-      if (nextChannel === updateState.channel) {
-        return updateState;
-      }
+    desktopSettings = setDesktopUpdateChannelPreference(desktopSettings, nextChannel);
+    writeDesktopSettings(DESKTOP_SETTINGS_PATH, desktopSettings);
 
-      const enabled = shouldEnableAutoUpdates();
-      setUpdateState(createBaseUpdateState(nextChannel, enabled));
+    if (nextChannel === updateState.channel) {
+      return updateState;
+    }
 
-      if (!enabled || !updaterConfigured) {
-        return updateState;
-      }
+    const enabled = shouldEnableAutoUpdates();
+    setUpdateState(createBaseUpdateState(nextChannel, enabled));
 
-      applyAutoUpdaterChannel(nextChannel);
-      const allowDowngrade = autoUpdater.allowDowngrade;
-      // An explicit channel switch should allow the immediate nightly->stable rollback path.
-      autoUpdater.allowDowngrade = true;
-      try {
-        await checkForUpdates("channel-change");
-      } finally {
-        autoUpdater.allowDowngrade = allowDowngrade;
-      }
+    if (!enabled || !updaterConfigured) {
       return updateState;
-    },
-  );
+    }
+
+    applyAutoUpdaterChannel(nextChannel);
+    const allowDowngrade = autoUpdater.allowDowngrade;
+    // An explicit channel switch should allow the immediate nightly->stable rollback path.
+    autoUpdater.allowDowngrade = true;
+    try {
+      await checkForUpdates("channel-change");
+    } finally {
+      autoUpdater.allowDowngrade = allowDowngrade;
+    }
+    return updateState;
+  });
 
   ipcMain.removeHandler(UPDATE_DOWNLOAD_CHANNEL);
   ipcMain.handle(UPDATE_DOWNLOAD_CHANNEL, async () => {
@@ -2337,13 +2122,9 @@ function createWindow(): BrowserWindow {
   // fallback so the window still surfaces once the renderer has loaded
   // the page. Other platforms keep the no-flash `ready-to-show` path,
   // since `did-finish-load` typically fires before the first paint there.
-  const revealSubscribers: RevealSubscription[] = [
-    (fire) => window.once("ready-to-show", fire),
-  ];
+  const revealSubscribers: RevealSubscription[] = [(fire) => window.once("ready-to-show", fire)];
   if (process.platform === "linux") {
-    revealSubscribers.push((fire) =>
-      window.webContents.once("did-finish-load", fire),
-    );
+    revealSubscribers.push((fire) => window.webContents.once("did-finish-load", fire));
   }
   bindFirstRevealTrigger(revealSubscribers, () => revealWindow(window));
 
@@ -2375,9 +2156,7 @@ configureAppIdentity();
 
 async function bootstrap(): Promise<void> {
   writeDesktopLogHeader("bootstrap start");
-  const configuredBackendPort = resolveConfiguredDesktopBackendPort(
-    process.env.T3CODE_PORT,
-  );
+  const configuredBackendPort = resolveConfiguredDesktopBackendPort(process.env.T3CODE_PORT);
   if (isDevelopment && configuredBackendPort === undefined) {
     throw new Error("T3CODE_PORT is required in desktop development.");
   }
@@ -2395,10 +2174,7 @@ async function bootstrap(): Promise<void> {
       : `using configured backend port port=${backendPort}`,
   );
   backendBootstrapToken = Crypto.randomBytes(24).toString("hex");
-  if (
-    desktopSettings.serverExposureMode !==
-    DEFAULT_DESKTOP_SETTINGS.serverExposureMode
-  ) {
+  if (desktopSettings.serverExposureMode !== DEFAULT_DESKTOP_SETTINGS.serverExposureMode) {
     writeDesktopLogHeader(
       `bootstrap restoring persisted server exposure mode mode=${desktopSettings.serverExposureMode}`,
     );
@@ -2406,14 +2182,10 @@ async function bootstrap(): Promise<void> {
   const serverExposureState = await applyDesktopServerExposureMode(
     desktopSettings.serverExposureMode,
     {
-      persist:
-        desktopSettings.serverExposureMode !==
-        DEFAULT_DESKTOP_SETTINGS.serverExposureMode,
+      persist: desktopSettings.serverExposureMode !== DEFAULT_DESKTOP_SETTINGS.serverExposureMode,
     },
   );
-  writeDesktopLogHeader(
-    `bootstrap resolved backend endpoint baseUrl=${backendHttpUrl}`,
-  );
+  writeDesktopLogHeader(`bootstrap resolved backend endpoint baseUrl=${backendHttpUrl}`);
   if (serverExposureState.endpointUrl) {
     writeDesktopLogHeader(
       `bootstrap enabled network access endpointUrl=${serverExposureState.endpointUrl}`,
@@ -2443,10 +2215,7 @@ async function bootstrap(): Promise<void> {
         writeDesktopLogHeader(
           `bootstrap backend readiness warning message=${formatErrorMessage(error)}`,
         );
-        console.warn(
-          "[desktop] backend readiness check timed out during dev bootstrap",
-          error,
-        );
+        console.warn("[desktop] backend readiness check timed out during dev bootstrap", error);
       });
     return;
   }
diff --git a/apps/web/src/components/chat/ChatHeader.test.ts b/apps/web/src/components/chat/ChatHeader.test.ts
new file mode 100644
index 00000000000..1b7b219bdb4
--- /dev/null
+++ b/apps/web/src/components/chat/ChatHeader.test.ts
@@ -0,0 +1,48 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { describe, expect, it } from "vitest";
+
+import { shouldShowOpenInPicker } from "./ChatHeader";
+
+describe("shouldShowOpenInPicker", () => {
+  const primaryEnvironmentId = EnvironmentId.make("environment-primary");
+
+  it("shows the picker for projects in the primary environment", () => {
+    expect(
+      shouldShowOpenInPicker({
+        activeProjectName: "codething-mvp",
+        activeThreadEnvironmentId: primaryEnvironmentId,
+        primaryEnvironmentId,
+      }),
+    ).toBe(true);
+  });
+
+  it("hides the picker when hosted static mode has no primary environment", () => {
+    expect(
+      shouldShowOpenInPicker({
+        activeProjectName: "codething-mvp",
+        activeThreadEnvironmentId: EnvironmentId.make("environment-remote"),
+        primaryEnvironmentId: null,
+      }),
+    ).toBe(false);
+  });
+
+  it("hides the picker for remote environments", () => {
+    expect(
+      shouldShowOpenInPicker({
+        activeProjectName: "codething-mvp",
+        activeThreadEnvironmentId: EnvironmentId.make("environment-remote"),
+        primaryEnvironmentId,
+      }),
+    ).toBe(false);
+  });
+
+  it("hides the picker when there is no active project", () => {
+    expect(
+      shouldShowOpenInPicker({
+        activeProjectName: undefined,
+        activeThreadEnvironmentId: primaryEnvironmentId,
+        primaryEnvironmentId,
+      }),
+    ).toBe(false);
+  });
+});
diff --git a/apps/web/src/components/chat/ChatHeader.tsx b/apps/web/src/components/chat/ChatHeader.tsx
index 5d7c9292474..3cd4576ab88 100644
--- a/apps/web/src/components/chat/ChatHeader.tsx
+++ b/apps/web/src/components/chat/ChatHeader.tsx
@@ -44,6 +44,18 @@ interface ChatHeaderProps {
   onToggleDiff: () => void;
 }
 
+export function shouldShowOpenInPicker(input: {
+  readonly activeProjectName: string | undefined;
+  readonly activeThreadEnvironmentId: EnvironmentId;
+  readonly primaryEnvironmentId: EnvironmentId | null;
+}): boolean {
+  return (
+    Boolean(input.activeProjectName) &&
+    input.primaryEnvironmentId !== null &&
+    input.activeThreadEnvironmentId === input.primaryEnvironmentId
+  );
+}
+
 export const ChatHeader = memo(function ChatHeader({
   activeThreadEnvironmentId,
   activeThreadId,
@@ -70,8 +82,11 @@ export const ChatHeader = memo(function ChatHeader({
   onToggleDiff,
 }: ChatHeaderProps) {
   const primaryEnvironmentId = usePrimaryEnvironmentId();
-  const isRemoteEnvironment =
-    primaryEnvironmentId !== null && activeThreadEnvironmentId !== primaryEnvironmentId;
+  const showOpenInPicker = shouldShowOpenInPicker({
+    activeProjectName,
+    activeThreadEnvironmentId,
+    primaryEnvironmentId,
+  });
 
   return (
     <div className="@container/header-actions flex min-w-0 flex-1 items-center gap-2">
@@ -106,7 +121,7 @@ export const ChatHeader = memo(function ChatHeader({
             onDeleteScript={onDeleteProjectScript}
           />
         )}
-        {activeProjectName && !isRemoteEnvironment && (
+        {showOpenInPicker && (
           <OpenInPicker
             keybindings={keybindings}
             availableEditors={availableEditors}

From 4e4497330f1a0013160d10f884ad9754db69b77c Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 21:55:07 -0700
Subject: [PATCH 57/74] Bootstrap SSH auth through live server

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/sshEnvironment.ts    |  2 +-
 apps/server/src/auth/http.ts          | 61 ++++++++++++++++++++
 apps/server/src/server.test.ts        | 81 +++++++++++++++++++++++++++
 apps/server/src/server.ts             |  2 +
 apps/server/src/serverRuntimeState.ts | 14 ++++-
 packages/ssh/src/tunnel.test.ts       |  8 ++-
 packages/ssh/src/tunnel.ts            | 30 ++++++----
 7 files changed, 181 insertions(+), 17 deletions(-)

diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index c4c288aade1..9a8129f01ee 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -293,7 +293,7 @@ export class DesktopSshEnvironmentBridge {
         sshRuntime.runPromise(
           fetchLoopbackSshJson<AuthBearerBootstrapResult>({
             httpBaseUrl: rawHttpBaseUrl,
-            pathname: "/api/auth/bootstrap/bearer",
+            pathname: "/api/auth/bootstrap/ssh-bearer",
             method: "POST",
             body: { credential: rawCredential },
           }),
diff --git a/apps/server/src/auth/http.ts b/apps/server/src/auth/http.ts
index 76c14646e98..10dca18b50c 100644
--- a/apps/server/src/auth/http.ts
+++ b/apps/server/src/auth/http.ts
@@ -12,6 +12,8 @@ import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstab
 import { AuthError, ServerAuth } from "./Services/ServerAuth.ts";
 import { SessionCredentialService } from "./Services/SessionCredentialService.ts";
 import { deriveAuthClientMetadata } from "./utils.ts";
+import { ServerConfig } from "../config.ts";
+import { readPersistedServerRuntimeState } from "../serverRuntimeState.ts";
 
 export const respondToAuthError = (error: AuthError) =>
   Effect.gen(function* () {
@@ -116,6 +118,65 @@ export const authBearerBootstrapRouteLayer = HttpRouter.add(
   }).pipe(Effect.catchTag("AuthError", (error) => respondToAuthError(error))),
 );
 
+export const authSshBearerBootstrapRouteLayer = HttpRouter.add(
+  "POST",
+  "/api/auth/bootstrap/ssh-bearer",
+  Effect.gen(function* () {
+    const request = yield* HttpServerRequest.HttpServerRequest;
+    const config = yield* ServerConfig;
+    const sessions = yield* SessionCredentialService;
+    const payload = yield* HttpServerRequest.schemaBodyJson(AuthBootstrapInput).pipe(
+      Effect.mapError(
+        (cause) =>
+          new AuthError({
+            message: "Invalid bootstrap payload.",
+            status: 400,
+            cause,
+          }),
+      ),
+    );
+    const runtimeState = yield* readPersistedServerRuntimeState(config.serverRuntimeStatePath);
+    if (
+      runtimeState._tag !== "Some" ||
+      !runtimeState.value.sshBootstrapCredential ||
+      payload.credential !== runtimeState.value.sshBootstrapCredential
+    ) {
+      return yield* new AuthError({
+        message: "Invalid SSH bootstrap credential.",
+        status: 401,
+      });
+    }
+
+    const issued = yield* sessions
+      .issue({
+        method: "bearer-session-token",
+        subject: "ssh-bootstrap",
+        role: "client",
+        client: deriveAuthClientMetadata({ request }),
+      })
+      .pipe(
+        Effect.mapError(
+          (cause) =>
+            new AuthError({
+              message: "Failed to issue authenticated session.",
+              status: 500,
+              cause,
+            }),
+        ),
+      );
+    return HttpServerResponse.jsonUnsafe(
+      {
+        authenticated: true,
+        role: issued.role,
+        sessionMethod: "bearer-session-token",
+        expiresAt: DateTime.toUtc(issued.expiresAt),
+        sessionToken: issued.token,
+      } satisfies AuthBearerBootstrapResult,
+      { status: 200 },
+    );
+  }).pipe(Effect.catchTag("AuthError", (error) => respondToAuthError(error))),
+);
+
 export const authWebSocketTokenRouteLayer = HttpRouter.add(
   "POST",
   "/api/auth/ws-token",
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index dc5ff915b6b..61f239469f6 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -57,6 +57,7 @@ const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
 import type { ServerConfigShape } from "./config.ts";
 import { deriveServerPaths, ServerConfig } from "./config.ts";
 import { makeRoutesLayer } from "./server.ts";
+import { persistServerRuntimeState } from "./serverRuntimeState.ts";
 import { resolveAttachmentRelativePath } from "./attachmentPaths.ts";
 import {
   CheckpointDiffQuery,
@@ -768,6 +769,32 @@ const bootstrapBearerSession = (credential = defaultDesktopBootstrapToken) =>
     };
   });
 
+const bootstrapSshBearerSession = (credential: string) =>
+  Effect.gen(function* () {
+    const bootstrapUrl = yield* getHttpServerUrl("/api/auth/bootstrap/ssh-bearer");
+    const response = yield* Effect.promise(() =>
+      fetch(bootstrapUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify({
+          credential,
+        }),
+      }),
+    );
+    const body = (yield* Effect.promise(() => response.json())) as {
+      readonly authenticated?: boolean;
+      readonly sessionMethod?: string;
+      readonly sessionToken?: string;
+      readonly error?: string;
+    };
+    return {
+      response,
+      body,
+    };
+  });
+
 const getAuthenticatedSessionCookieHeader = (credential = defaultDesktopBootstrapToken) =>
   Effect.gen(function* () {
     const { response, cookie } = yield* bootstrapBrowserSession(credential);
@@ -1420,6 +1447,60 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
+  it.effect("bootstraps an SSH bearer session from the live server runtime credential", () =>
+    Effect.gen(function* () {
+      const config = yield* buildAppUnderTest();
+      const serverUrl = yield* getHttpServerUrl();
+      const server = yield* HttpServer.HttpServer;
+      const address = server.address as HttpServer.TcpAddress;
+      yield* persistServerRuntimeState({
+        path: config.serverRuntimeStatePath,
+        state: {
+          version: 1,
+          pid: process.pid,
+          host: "127.0.0.1",
+          port: address.port,
+          origin: serverUrl,
+          startedAt: new Date().toISOString(),
+          sshBootstrapCredential: "ssh-runtime-bootstrap",
+        },
+      });
+
+      const bootstrapped = yield* bootstrapSshBearerSession("ssh-runtime-bootstrap");
+
+      assert.equal(bootstrapped.response.status, 200);
+      assert.equal(bootstrapped.body.authenticated, true);
+      assert.equal(bootstrapped.body.sessionMethod, "bearer-session-token");
+      assert.isString(bootstrapped.body.sessionToken);
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
+  it.effect("rejects invalid SSH runtime bootstrap credentials", () =>
+    Effect.gen(function* () {
+      const config = yield* buildAppUnderTest();
+      const serverUrl = yield* getHttpServerUrl();
+      const server = yield* HttpServer.HttpServer;
+      const address = server.address as HttpServer.TcpAddress;
+      yield* persistServerRuntimeState({
+        path: config.serverRuntimeStatePath,
+        state: {
+          version: 1,
+          pid: process.pid,
+          host: "127.0.0.1",
+          port: address.port,
+          origin: serverUrl,
+          startedAt: new Date().toISOString(),
+          sshBootstrapCredential: "ssh-runtime-bootstrap",
+        },
+      });
+
+      const bootstrapped = yield* bootstrapSshBearerSession("wrong");
+
+      assert.equal(bootstrapped.response.status, 401);
+      assert.equal(bootstrapped.body.error, "Invalid SSH bootstrap credential.");
+    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
+  );
+
   it.effect(
     "does not accept session tokens via query parameters on authenticated HTTP routes",
     () =>
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index cebb334bfb4..fa074d60e05 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -66,6 +66,7 @@ import {
   authPairingLinksRouteLayer,
   authPairingCredentialRouteLayer,
   authSessionRouteLayer,
+  authSshBearerBootstrapRouteLayer,
   authWebSocketTokenRouteLayer,
 } from "./auth/http.ts";
 import { ServerSecretStoreLive } from "./auth/Layers/ServerSecretStore.ts";
@@ -282,6 +283,7 @@ export const makeRoutesLayer = Layer.mergeAll(
   authPairingLinksRouteLayer,
   authPairingCredentialRouteLayer,
   authSessionRouteLayer,
+  authSshBearerBootstrapRouteLayer,
   authWebSocketTokenRouteLayer,
   attachmentsRouteLayer,
   orchestrationDispatchRouteLayer,
diff --git a/apps/server/src/serverRuntimeState.ts b/apps/server/src/serverRuntimeState.ts
index 4b300f29c2c..e076e9190a4 100644
--- a/apps/server/src/serverRuntimeState.ts
+++ b/apps/server/src/serverRuntimeState.ts
@@ -1,3 +1,5 @@
+import * as Crypto from "node:crypto";
+
 import { Effect, FileSystem, Option, Schema } from "effect";
 
 import { writeFileStringAtomically } from "./atomicWrite.ts";
@@ -11,6 +13,7 @@ export const PersistedServerRuntimeState = Schema.Struct({
   port: Schema.Int,
   origin: Schema.String,
   startedAt: Schema.String,
+  sshBootstrapCredential: Schema.optional(Schema.String),
 });
 export type PersistedServerRuntimeState = typeof PersistedServerRuntimeState.Type;
 
@@ -37,15 +40,20 @@ export const makePersistedServerRuntimeState = (input: {
   port: input.port,
   origin: runtimeOriginForConfig(input.config, input.port),
   startedAt: new Date().toISOString(),
+  sshBootstrapCredential: Crypto.randomBytes(32).toString("base64url"),
 });
 
 export const persistServerRuntimeState = (input: {
   readonly path: string;
   readonly state: PersistedServerRuntimeState;
 }) =>
-  writeFileStringAtomically({
-    filePath: input.path,
-    contents: `${JSON.stringify(input.state)}\n`,
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    yield* writeFileStringAtomically({
+      filePath: input.path,
+      contents: `${JSON.stringify(input.state)}\n`,
+    });
+    yield* fs.chmod(input.path, 0o600).pipe(Effect.ignore);
   });
 
 export const clearPersistedServerRuntimeState = (path: string) =>
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 03d980fccb0..2cb0f294672 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -131,10 +131,14 @@ describe("ssh tunnel scripts", () => {
     assert.include(buildRemoteLaunchScript({ packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
       buildRemotePairingScript(target),
-      '"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json',
+      'RUNTIME_FILE="$PAIRING_BASE_DIR/userdata/server-runtime.json"',
     );
+    assert.include(buildRemotePairingScript(target), "sshBootstrapCredential");
     assert.include(buildRemotePairingScript(target), 'BASE_DIR_FILE="$STATE_DIR/base-dir"');
-    assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
+    assert.notInclude(
+      buildRemotePairingScript(target, { packageSpec: "t3@nightly" }),
+      "t3@nightly",
+    );
     assert.include(
       buildRemoteStopScript(target),
       'if [ "$REMOTE_MANAGED" != "external" ] && [ -n "$REMOTE_PID" ]',
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 7197b18618d..df9a5e119e4 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -458,19 +458,28 @@ printf '{"remotePort":%s,"serverKind":"%s"}\\n' "$REMOTE_PORT" "\${REMOTE_MANAGE
 
 export const REMOTE_PAIRING_SCRIPT = `set -eu
 STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
-SERVER_HOME="$STATE_DIR/server-home"
 BASE_DIR_FILE="$STATE_DIR/base-dir"
-RUNNER_FILE="$STATE_DIR/run-t3.sh"
-mkdir -p "$STATE_DIR" "$SERVER_HOME"
-cat >"$RUNNER_FILE" <<'SH'
-@@T3_RUNNER_SCRIPT@@
-SH
-chmod 700 "$RUNNER_FILE"
 PAIRING_BASE_DIR="$(cat "$BASE_DIR_FILE" 2>/dev/null || true)"
 if [ -z "$PAIRING_BASE_DIR" ]; then
-  PAIRING_BASE_DIR="$SERVER_HOME"
+  PAIRING_BASE_DIR="$STATE_DIR/server-home"
 fi
-"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json
+RUNTIME_FILE="$PAIRING_BASE_DIR/userdata/server-runtime.json"
+node - "$RUNTIME_FILE" <<'NODE'
+const fs = require("node:fs");
+const runtimePath = process.argv[2] ?? "";
+try {
+  const runtime = JSON.parse(fs.readFileSync(runtimePath, "utf8"));
+  const credential = String(runtime.sshBootstrapCredential ?? "").trim();
+  if (credential.length === 0) {
+    console.error("Remote T3 server runtime does not expose an SSH bootstrap credential.");
+    process.exit(1);
+  }
+  process.stdout.write(JSON.stringify({ credential }) + "\\n");
+} catch (error) {
+  console.error("Failed to read remote T3 server runtime state.");
+  process.exit(1);
+}
+NODE
 `;
 
 export const REMOTE_STOP_SCRIPT = `set -eu
@@ -527,11 +536,10 @@ export function buildRemoteLaunchScript(input?: RemoteT3RunnerOptions): string {
 
 export function buildRemotePairingScript(
   target: DesktopSshEnvironmentTarget,
-  input?: RemoteT3RunnerOptions,
+  _input?: RemoteT3RunnerOptions,
 ): string {
   return applyScriptPlaceholders(REMOTE_PAIRING_SCRIPT, {
     T3_STATE_KEY: remoteStateKey(target),
-    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
   });
 }
 

From d4712be76a0b906e6c7737b3972a68813f10bd9d Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 21:58:34 -0700
Subject: [PATCH 58/74] Revert "Bootstrap SSH auth through live server"

This reverts commit 5a2070c5afb6dffe2f9ba31e3d38006642843d82.
---
 apps/desktop/src/sshEnvironment.ts    |  2 +-
 apps/server/src/auth/http.ts          | 61 --------------------
 apps/server/src/server.test.ts        | 81 ---------------------------
 apps/server/src/server.ts             |  2 -
 apps/server/src/serverRuntimeState.ts | 14 +----
 packages/ssh/src/tunnel.test.ts       |  8 +--
 packages/ssh/src/tunnel.ts            | 30 ++++------
 7 files changed, 17 insertions(+), 181 deletions(-)

diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index 9a8129f01ee..c4c288aade1 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -293,7 +293,7 @@ export class DesktopSshEnvironmentBridge {
         sshRuntime.runPromise(
           fetchLoopbackSshJson<AuthBearerBootstrapResult>({
             httpBaseUrl: rawHttpBaseUrl,
-            pathname: "/api/auth/bootstrap/ssh-bearer",
+            pathname: "/api/auth/bootstrap/bearer",
             method: "POST",
             body: { credential: rawCredential },
           }),
diff --git a/apps/server/src/auth/http.ts b/apps/server/src/auth/http.ts
index 10dca18b50c..76c14646e98 100644
--- a/apps/server/src/auth/http.ts
+++ b/apps/server/src/auth/http.ts
@@ -12,8 +12,6 @@ import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/unstab
 import { AuthError, ServerAuth } from "./Services/ServerAuth.ts";
 import { SessionCredentialService } from "./Services/SessionCredentialService.ts";
 import { deriveAuthClientMetadata } from "./utils.ts";
-import { ServerConfig } from "../config.ts";
-import { readPersistedServerRuntimeState } from "../serverRuntimeState.ts";
 
 export const respondToAuthError = (error: AuthError) =>
   Effect.gen(function* () {
@@ -118,65 +116,6 @@ export const authBearerBootstrapRouteLayer = HttpRouter.add(
   }).pipe(Effect.catchTag("AuthError", (error) => respondToAuthError(error))),
 );
 
-export const authSshBearerBootstrapRouteLayer = HttpRouter.add(
-  "POST",
-  "/api/auth/bootstrap/ssh-bearer",
-  Effect.gen(function* () {
-    const request = yield* HttpServerRequest.HttpServerRequest;
-    const config = yield* ServerConfig;
-    const sessions = yield* SessionCredentialService;
-    const payload = yield* HttpServerRequest.schemaBodyJson(AuthBootstrapInput).pipe(
-      Effect.mapError(
-        (cause) =>
-          new AuthError({
-            message: "Invalid bootstrap payload.",
-            status: 400,
-            cause,
-          }),
-      ),
-    );
-    const runtimeState = yield* readPersistedServerRuntimeState(config.serverRuntimeStatePath);
-    if (
-      runtimeState._tag !== "Some" ||
-      !runtimeState.value.sshBootstrapCredential ||
-      payload.credential !== runtimeState.value.sshBootstrapCredential
-    ) {
-      return yield* new AuthError({
-        message: "Invalid SSH bootstrap credential.",
-        status: 401,
-      });
-    }
-
-    const issued = yield* sessions
-      .issue({
-        method: "bearer-session-token",
-        subject: "ssh-bootstrap",
-        role: "client",
-        client: deriveAuthClientMetadata({ request }),
-      })
-      .pipe(
-        Effect.mapError(
-          (cause) =>
-            new AuthError({
-              message: "Failed to issue authenticated session.",
-              status: 500,
-              cause,
-            }),
-        ),
-      );
-    return HttpServerResponse.jsonUnsafe(
-      {
-        authenticated: true,
-        role: issued.role,
-        sessionMethod: "bearer-session-token",
-        expiresAt: DateTime.toUtc(issued.expiresAt),
-        sessionToken: issued.token,
-      } satisfies AuthBearerBootstrapResult,
-      { status: 200 },
-    );
-  }).pipe(Effect.catchTag("AuthError", (error) => respondToAuthError(error))),
-);
-
 export const authWebSocketTokenRouteLayer = HttpRouter.add(
   "POST",
   "/api/auth/ws-token",
diff --git a/apps/server/src/server.test.ts b/apps/server/src/server.test.ts
index 61f239469f6..dc5ff915b6b 100644
--- a/apps/server/src/server.test.ts
+++ b/apps/server/src/server.test.ts
@@ -57,7 +57,6 @@ const TEST_EPOCH = DateTime.makeUnsafe("1970-01-01T00:00:00.000Z");
 import type { ServerConfigShape } from "./config.ts";
 import { deriveServerPaths, ServerConfig } from "./config.ts";
 import { makeRoutesLayer } from "./server.ts";
-import { persistServerRuntimeState } from "./serverRuntimeState.ts";
 import { resolveAttachmentRelativePath } from "./attachmentPaths.ts";
 import {
   CheckpointDiffQuery,
@@ -769,32 +768,6 @@ const bootstrapBearerSession = (credential = defaultDesktopBootstrapToken) =>
     };
   });
 
-const bootstrapSshBearerSession = (credential: string) =>
-  Effect.gen(function* () {
-    const bootstrapUrl = yield* getHttpServerUrl("/api/auth/bootstrap/ssh-bearer");
-    const response = yield* Effect.promise(() =>
-      fetch(bootstrapUrl, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-        },
-        body: JSON.stringify({
-          credential,
-        }),
-      }),
-    );
-    const body = (yield* Effect.promise(() => response.json())) as {
-      readonly authenticated?: boolean;
-      readonly sessionMethod?: string;
-      readonly sessionToken?: string;
-      readonly error?: string;
-    };
-    return {
-      response,
-      body,
-    };
-  });
-
 const getAuthenticatedSessionCookieHeader = (credential = defaultDesktopBootstrapToken) =>
   Effect.gen(function* () {
     const { response, cookie } = yield* bootstrapBrowserSession(credential);
@@ -1447,60 +1420,6 @@ it.layer(NodeServices.layer)("server router seam", (it) => {
     }).pipe(Effect.provide(NodeHttpServer.layerTest)),
   );
 
-  it.effect("bootstraps an SSH bearer session from the live server runtime credential", () =>
-    Effect.gen(function* () {
-      const config = yield* buildAppUnderTest();
-      const serverUrl = yield* getHttpServerUrl();
-      const server = yield* HttpServer.HttpServer;
-      const address = server.address as HttpServer.TcpAddress;
-      yield* persistServerRuntimeState({
-        path: config.serverRuntimeStatePath,
-        state: {
-          version: 1,
-          pid: process.pid,
-          host: "127.0.0.1",
-          port: address.port,
-          origin: serverUrl,
-          startedAt: new Date().toISOString(),
-          sshBootstrapCredential: "ssh-runtime-bootstrap",
-        },
-      });
-
-      const bootstrapped = yield* bootstrapSshBearerSession("ssh-runtime-bootstrap");
-
-      assert.equal(bootstrapped.response.status, 200);
-      assert.equal(bootstrapped.body.authenticated, true);
-      assert.equal(bootstrapped.body.sessionMethod, "bearer-session-token");
-      assert.isString(bootstrapped.body.sessionToken);
-    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
-  );
-
-  it.effect("rejects invalid SSH runtime bootstrap credentials", () =>
-    Effect.gen(function* () {
-      const config = yield* buildAppUnderTest();
-      const serverUrl = yield* getHttpServerUrl();
-      const server = yield* HttpServer.HttpServer;
-      const address = server.address as HttpServer.TcpAddress;
-      yield* persistServerRuntimeState({
-        path: config.serverRuntimeStatePath,
-        state: {
-          version: 1,
-          pid: process.pid,
-          host: "127.0.0.1",
-          port: address.port,
-          origin: serverUrl,
-          startedAt: new Date().toISOString(),
-          sshBootstrapCredential: "ssh-runtime-bootstrap",
-        },
-      });
-
-      const bootstrapped = yield* bootstrapSshBearerSession("wrong");
-
-      assert.equal(bootstrapped.response.status, 401);
-      assert.equal(bootstrapped.body.error, "Invalid SSH bootstrap credential.");
-    }).pipe(Effect.provide(NodeHttpServer.layerTest)),
-  );
-
   it.effect(
     "does not accept session tokens via query parameters on authenticated HTTP routes",
     () =>
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index fa074d60e05..cebb334bfb4 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -66,7 +66,6 @@ import {
   authPairingLinksRouteLayer,
   authPairingCredentialRouteLayer,
   authSessionRouteLayer,
-  authSshBearerBootstrapRouteLayer,
   authWebSocketTokenRouteLayer,
 } from "./auth/http.ts";
 import { ServerSecretStoreLive } from "./auth/Layers/ServerSecretStore.ts";
@@ -283,7 +282,6 @@ export const makeRoutesLayer = Layer.mergeAll(
   authPairingLinksRouteLayer,
   authPairingCredentialRouteLayer,
   authSessionRouteLayer,
-  authSshBearerBootstrapRouteLayer,
   authWebSocketTokenRouteLayer,
   attachmentsRouteLayer,
   orchestrationDispatchRouteLayer,
diff --git a/apps/server/src/serverRuntimeState.ts b/apps/server/src/serverRuntimeState.ts
index e076e9190a4..4b300f29c2c 100644
--- a/apps/server/src/serverRuntimeState.ts
+++ b/apps/server/src/serverRuntimeState.ts
@@ -1,5 +1,3 @@
-import * as Crypto from "node:crypto";
-
 import { Effect, FileSystem, Option, Schema } from "effect";
 
 import { writeFileStringAtomically } from "./atomicWrite.ts";
@@ -13,7 +11,6 @@ export const PersistedServerRuntimeState = Schema.Struct({
   port: Schema.Int,
   origin: Schema.String,
   startedAt: Schema.String,
-  sshBootstrapCredential: Schema.optional(Schema.String),
 });
 export type PersistedServerRuntimeState = typeof PersistedServerRuntimeState.Type;
 
@@ -40,20 +37,15 @@ export const makePersistedServerRuntimeState = (input: {
   port: input.port,
   origin: runtimeOriginForConfig(input.config, input.port),
   startedAt: new Date().toISOString(),
-  sshBootstrapCredential: Crypto.randomBytes(32).toString("base64url"),
 });
 
 export const persistServerRuntimeState = (input: {
   readonly path: string;
   readonly state: PersistedServerRuntimeState;
 }) =>
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    yield* writeFileStringAtomically({
-      filePath: input.path,
-      contents: `${JSON.stringify(input.state)}\n`,
-    });
-    yield* fs.chmod(input.path, 0o600).pipe(Effect.ignore);
+  writeFileStringAtomically({
+    filePath: input.path,
+    contents: `${JSON.stringify(input.state)}\n`,
   });
 
 export const clearPersistedServerRuntimeState = (path: string) =>
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 2cb0f294672..03d980fccb0 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -131,14 +131,10 @@ describe("ssh tunnel scripts", () => {
     assert.include(buildRemoteLaunchScript({ packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
       buildRemotePairingScript(target),
-      'RUNTIME_FILE="$PAIRING_BASE_DIR/userdata/server-runtime.json"',
+      '"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json',
     );
-    assert.include(buildRemotePairingScript(target), "sshBootstrapCredential");
     assert.include(buildRemotePairingScript(target), 'BASE_DIR_FILE="$STATE_DIR/base-dir"');
-    assert.notInclude(
-      buildRemotePairingScript(target, { packageSpec: "t3@nightly" }),
-      "t3@nightly",
-    );
+    assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
       buildRemoteStopScript(target),
       'if [ "$REMOTE_MANAGED" != "external" ] && [ -n "$REMOTE_PID" ]',
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index df9a5e119e4..7197b18618d 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -458,28 +458,19 @@ printf '{"remotePort":%s,"serverKind":"%s"}\\n' "$REMOTE_PORT" "\${REMOTE_MANAGE
 
 export const REMOTE_PAIRING_SCRIPT = `set -eu
 STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
+SERVER_HOME="$STATE_DIR/server-home"
 BASE_DIR_FILE="$STATE_DIR/base-dir"
+RUNNER_FILE="$STATE_DIR/run-t3.sh"
+mkdir -p "$STATE_DIR" "$SERVER_HOME"
+cat >"$RUNNER_FILE" <<'SH'
+@@T3_RUNNER_SCRIPT@@
+SH
+chmod 700 "$RUNNER_FILE"
 PAIRING_BASE_DIR="$(cat "$BASE_DIR_FILE" 2>/dev/null || true)"
 if [ -z "$PAIRING_BASE_DIR" ]; then
-  PAIRING_BASE_DIR="$STATE_DIR/server-home"
+  PAIRING_BASE_DIR="$SERVER_HOME"
 fi
-RUNTIME_FILE="$PAIRING_BASE_DIR/userdata/server-runtime.json"
-node - "$RUNTIME_FILE" <<'NODE'
-const fs = require("node:fs");
-const runtimePath = process.argv[2] ?? "";
-try {
-  const runtime = JSON.parse(fs.readFileSync(runtimePath, "utf8"));
-  const credential = String(runtime.sshBootstrapCredential ?? "").trim();
-  if (credential.length === 0) {
-    console.error("Remote T3 server runtime does not expose an SSH bootstrap credential.");
-    process.exit(1);
-  }
-  process.stdout.write(JSON.stringify({ credential }) + "\\n");
-} catch (error) {
-  console.error("Failed to read remote T3 server runtime state.");
-  process.exit(1);
-}
-NODE
+"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json
 `;
 
 export const REMOTE_STOP_SCRIPT = `set -eu
@@ -536,10 +527,11 @@ export function buildRemoteLaunchScript(input?: RemoteT3RunnerOptions): string {
 
 export function buildRemotePairingScript(
   target: DesktopSshEnvironmentTarget,
-  _input?: RemoteT3RunnerOptions,
+  input?: RemoteT3RunnerOptions,
 ): string {
   return applyScriptPlaceholders(REMOTE_PAIRING_SCRIPT, {
     T3_STATE_KEY: remoteStateKey(target),
+    T3_RUNNER_SCRIPT: stripTrailingNewlines(buildRemoteT3RunnerScript(input)),
   });
 }
 

From dad2a07633a4f9115cc3774efbb82613e5d4293f Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 22:06:44 -0700
Subject: [PATCH 59/74] Add SSH pairing diagnostics

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/web/src/environments/runtime/service.ts | 24 +++++++-
 packages/contracts/src/ipc.ts                |  9 +++
 packages/ssh/src/tunnel.test.ts              |  6 +-
 packages/ssh/src/tunnel.ts                   | 59 ++++++++++++++++++--
 4 files changed, 91 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index d1e83a5d455..40e12121c13 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -662,9 +662,16 @@ async function prepareSavedEnvironmentRecordForConnection(
   readonly pairingToken: string | null;
   readonly remotePort: number | null;
   readonly remoteServerKind: "external" | "managed" | null;
+  readonly pairingDiagnostics: DesktopSshEnvironmentBootstrap["pairingDiagnostics"] | null;
 }> {
   if (!record.desktopSsh) {
-    return { record, pairingToken: null, remotePort: null, remoteServerKind: null };
+    return {
+      record,
+      pairingToken: null,
+      remotePort: null,
+      remoteServerKind: null,
+      pairingDiagnostics: null,
+    };
   }
 
   const bootstrap = await resolveDesktopSshEnvironmentBootstrap(record.desktopSsh, options);
@@ -689,6 +696,7 @@ async function prepareSavedEnvironmentRecordForConnection(
     pairingToken: bootstrap.pairingToken,
     remotePort: bootstrap.remotePort ?? null,
     remoteServerKind: bootstrap.remoteServerKind ?? null,
+    pairingDiagnostics: bootstrap.pairingDiagnostics ?? null,
   };
 }
 
@@ -713,6 +721,13 @@ async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Pro
       `local ${prepared.record.httpBaseUrl}`,
       `remote port ${prepared.remotePort ?? "unknown"}`,
       prepared.remoteServerKind ? `remote server ${prepared.remoteServerKind}` : null,
+      prepared.pairingDiagnostics ? `pairing db ${prepared.pairingDiagnostics.dbPath}` : null,
+      prepared.pairingDiagnostics
+        ? `pairing runtime ${prepared.pairingDiagnostics.runtimePath}`
+        : null,
+      prepared.pairingDiagnostics
+        ? `pairing devUrl ${prepared.pairingDiagnostics.devUrl ?? "none"}`
+        : null,
     ]
       .filter(Boolean)
       .join(", ");
@@ -1574,6 +1589,13 @@ export async function connectDesktopSshEnvironment(
       `local ${bootstrap.httpBaseUrl}`,
       `remote port ${bootstrap.remotePort ?? "unknown"}`,
       bootstrap.remoteServerKind ? `remote server ${bootstrap.remoteServerKind}` : null,
+      bootstrap.pairingDiagnostics ? `pairing db ${bootstrap.pairingDiagnostics.dbPath}` : null,
+      bootstrap.pairingDiagnostics
+        ? `pairing runtime ${bootstrap.pairingDiagnostics.runtimePath}`
+        : null,
+      bootstrap.pairingDiagnostics
+        ? `pairing devUrl ${bootstrap.pairingDiagnostics.devUrl ?? "none"}`
+        : null,
     ]
       .filter(Boolean)
       .join(", ");
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 85e1e8f3349..be13302153a 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -155,6 +155,15 @@ export interface DesktopSshEnvironmentBootstrap {
   pairingToken: string | null;
   remotePort?: number;
   remoteServerKind?: "external" | "managed";
+  pairingDiagnostics?: {
+    baseDir: string;
+    stateDir: string;
+    dbPath: string;
+    runtimePath: string;
+    devUrl: string | null;
+    t3codeHome: string | null;
+    runnerPath: string;
+  };
 }
 
 export interface DesktopSshPasswordPromptRequest {
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 03d980fccb0..06badb86c43 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -133,6 +133,8 @@ describe("ssh tunnel scripts", () => {
       buildRemotePairingScript(target),
       '"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json',
     );
+    assert.include(buildRemotePairingScript(target), "diagnostics");
+    assert.include(buildRemotePairingScript(target), "VITE_DEV_SERVER_URL");
     assert.include(buildRemotePairingScript(target), 'BASE_DIR_FILE="$STATE_DIR/base-dir"');
     assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
@@ -210,8 +212,8 @@ describe("ssh tunnel scripts", () => {
     const spawnerLayer = Layer.succeed(ChildProcessSpawner.ChildProcessSpawner, spawner);
     const processLayer = Layer.merge(NodeServices.layer, spawnerLayer);
     return Effect.gen(function* () {
-      const credential = yield* issueRemotePairingToken(target);
-      assert.equal(credential, "LCL4R2TPHDKQ");
+      const result = yield* issueRemotePairingToken(target);
+      assert.equal(result.credential, "LCL4R2TPHDKQ");
     }).pipe(Effect.provide(processLayer));
   });
 
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 7197b18618d..5f3a4f8ea84 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -158,6 +158,17 @@ const RemoteLaunchResult = Schema.Struct({
 
 const RemotePairingResult = Schema.Struct({
   credential: Schema.String,
+  diagnostics: Schema.optional(
+    Schema.Struct({
+      baseDir: Schema.String,
+      stateDir: Schema.String,
+      dbPath: Schema.String,
+      runtimePath: Schema.String,
+      devUrl: Schema.NullOr(Schema.String),
+      t3codeHome: Schema.NullOr(Schema.String),
+      runnerPath: Schema.String,
+    }),
+  ),
 });
 
 const RemoteHttpError = Schema.Struct({
@@ -470,7 +481,38 @@ PAIRING_BASE_DIR="$(cat "$BASE_DIR_FILE" 2>/dev/null || true)"
 if [ -z "$PAIRING_BASE_DIR" ]; then
   PAIRING_BASE_DIR="$SERVER_HOME"
 fi
-"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json
+PAIRING_OUTPUT="$("$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json)"
+PAIRING_OUTPUT="$PAIRING_OUTPUT" node - "$PAIRING_BASE_DIR" "$RUNNER_FILE" <<'NODE'
+const path = require("node:path");
+const baseDir = process.argv[2] ?? "";
+const runnerPath = process.argv[3] ?? "";
+const raw = process.env.PAIRING_OUTPUT ?? "";
+const lines = raw
+  .split(/\\r?\\n/u)
+  .map((line) => line.trim())
+  .filter(Boolean);
+const lastLine = lines.at(-1);
+if (!lastLine) {
+  process.exit(1);
+}
+const result = JSON.parse(lastLine);
+const devUrl = process.env.VITE_DEV_SERVER_URL || null;
+const stateDir = path.join(baseDir, devUrl ? "dev" : "userdata");
+process.stdout.write(
+  JSON.stringify({
+    ...result,
+    diagnostics: {
+      baseDir,
+      stateDir,
+      dbPath: path.join(stateDir, "state.sqlite"),
+      runtimePath: path.join(stateDir, "server-runtime.json"),
+      devUrl,
+      t3codeHome: process.env.T3CODE_HOME || null,
+      runnerPath,
+    },
+  }) + "\\n",
+);
+NODE
 `;
 
 export const REMOTE_STOP_SCRIPT = `set -eu
@@ -609,7 +651,10 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
   input?: SshAuthOptions,
   runner?: RemoteT3RunnerOptions,
 ): Effect.fn.Return<
-  string,
+  {
+    readonly credential: string;
+    readonly diagnostics?: typeof RemotePairingResult.Type.diagnostics;
+  },
   SshCommandError | SshInvalidTargetError | SshPairingError,
   ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
 > {
@@ -649,8 +694,12 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
   yield* Effect.logDebug("ssh.remoteServer.pairingToken.created", {
     ...sshTargetLogFields(target),
     stateKey: remoteStateKey(target),
+    diagnostics: parsed.diagnostics ?? null,
   });
-  return parsed.credential;
+  return {
+    credential: parsed.credential,
+    ...(parsed.diagnostics ? { diagnostics: parsed.diagnostics } : {}),
+  };
 });
 
 export const stopRemoteServer = Effect.fn("ssh/tunnel.stopRemoteServer")(function* (
@@ -1500,13 +1549,14 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     });
     const entry = yield* ensureTunnelEntry(key, resolvedTarget, runner);
 
-    const pairingToken = requestOptions?.issuePairingToken
+    const pairingResult = requestOptions?.issuePairingToken
       ? yield* runWithSshAuth({
           key,
           target: entry.target,
           operation: (authOptions) => issueRemotePairingToken(entry.target, authOptions, runner),
         })
       : null;
+    const pairingToken = pairingResult?.credential ?? null;
 
     yield* Effect.logInfo("ssh.environment.ensure.succeeded", {
       ...sshTargetLogFields(entry.target),
@@ -1523,6 +1573,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       pairingToken,
       remotePort: entry.remotePort,
       ...(entry.remoteServerKind ? { remoteServerKind: entry.remoteServerKind } : {}),
+      ...(pairingResult?.diagnostics ? { pairingDiagnostics: pairingResult.diagnostics } : {}),
     };
   });
 

From 8710bdc049af04d9ba603770f9712a72142f5fac Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 22:12:50 -0700
Subject: [PATCH 60/74] Fix SSH pairing diagnostics JSON parsing

Co-authored-by: codex <codex@users.noreply.github.com>
---
 packages/ssh/src/tunnel.ts | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 5f3a4f8ea84..60f22fa7933 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -487,15 +487,21 @@ const path = require("node:path");
 const baseDir = process.argv[2] ?? "";
 const runnerPath = process.argv[3] ?? "";
 const raw = process.env.PAIRING_OUTPUT ?? "";
-const lines = raw
-  .split(/\\r?\\n/u)
-  .map((line) => line.trim())
-  .filter(Boolean);
-const lastLine = lines.at(-1);
-if (!lastLine) {
+const trimmed = raw.trim();
+if (!trimmed) {
   process.exit(1);
 }
-const result = JSON.parse(lastLine);
+let result;
+try {
+  result = JSON.parse(trimmed);
+} catch {
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start < 0 || end <= start) {
+    throw new Error("Unable to find JSON object in pairing command output.");
+  }
+  result = JSON.parse(trimmed.slice(start, end + 1));
+}
 const devUrl = process.env.VITE_DEV_SERVER_URL || null;
 const stateDir = path.join(baseDir, devUrl ? "dev" : "userdata");
 process.stdout.write(

From 973f0cbcce55f46ffb4d2f9f5f6aac7e268026dc Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 22:20:59 -0700
Subject: [PATCH 61/74] Use external SSH server auth store for pairing

Co-authored-by: codex <codex@users.noreply.github.com>
---
 packages/ssh/src/tunnel.test.ts |  3 +++
 packages/ssh/src/tunnel.ts      | 30 ++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 06badb86c43..2ca971bc846 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -136,6 +136,9 @@ describe("ssh tunnel scripts", () => {
     assert.include(buildRemotePairingScript(target), "diagnostics");
     assert.include(buildRemotePairingScript(target), "VITE_DEV_SERVER_URL");
     assert.include(buildRemotePairingScript(target), 'BASE_DIR_FILE="$STATE_DIR/base-dir"');
+    assert.include(buildRemotePairingScript(target), 'MANAGED_FILE="$STATE_DIR/managed"');
+    assert.include(buildRemotePairingScript(target), 'PAIRING_MANAGED="$(cat "$MANAGED_FILE"');
+    assert.include(buildRemotePairingScript(target), 'PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"');
     assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
       buildRemoteStopScript(target),
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 60f22fa7933..f05b2df8c2f 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -470,14 +470,44 @@ printf '{"remotePort":%s,"serverKind":"%s"}\\n' "$REMOTE_PORT" "\${REMOTE_MANAGE
 export const REMOTE_PAIRING_SCRIPT = `set -eu
 STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
 SERVER_HOME="$STATE_DIR/server-home"
+DEFAULT_SERVER_HOME="$HOME/.t3"
+DEFAULT_RUNTIME_FILE="$DEFAULT_SERVER_HOME/userdata/server-runtime.json"
 BASE_DIR_FILE="$STATE_DIR/base-dir"
+MANAGED_FILE="$STATE_DIR/managed"
 RUNNER_FILE="$STATE_DIR/run-t3.sh"
 mkdir -p "$STATE_DIR" "$SERVER_HOME"
 cat >"$RUNNER_FILE" <<'SH'
 @@T3_RUNNER_SCRIPT@@
 SH
 chmod 700 "$RUNNER_FILE"
+default_runtime_is_ready() {
+  node - "$DEFAULT_RUNTIME_FILE" <<'NODE'
+const fs = require("node:fs");
+const runtimePath = process.argv[2] ?? "";
+try {
+  const runtime = JSON.parse(fs.readFileSync(runtimePath, "utf8"));
+  const pid = Number(runtime.pid);
+  const port = Number(runtime.port);
+  if (!Number.isInteger(pid) || !Number.isInteger(port)) {
+    process.exit(1);
+  }
+  const origin = new URL(String(runtime.origin ?? ""));
+  if (origin.protocol !== "http:" || !["127.0.0.1", "localhost"].includes(origin.hostname)) {
+    process.exit(1);
+  }
+  process.kill(pid, 0);
+} catch {
+  process.exit(1);
+}
+NODE
+}
 PAIRING_BASE_DIR="$(cat "$BASE_DIR_FILE" 2>/dev/null || true)"
+PAIRING_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
+if [ "$PAIRING_MANAGED" = "external" ]; then
+  PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"
+elif [ -z "$PAIRING_BASE_DIR" ] && default_runtime_is_ready 2>/dev/null; then
+  PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"
+fi
 if [ -z "$PAIRING_BASE_DIR" ]; then
   PAIRING_BASE_DIR="$SERVER_HOME"
 fi

From fb760604dcd8e76d01f0f202a26dde772260778e Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 22:27:16 -0700
Subject: [PATCH 62/74] Use default T3 home for SSH-launched servers

Co-authored-by: codex <codex@users.noreply.github.com>
---
 packages/ssh/src/tunnel.test.ts | 11 +++----
 packages/ssh/src/tunnel.ts      | 51 ++++-----------------------------
 2 files changed, 10 insertions(+), 52 deletions(-)

diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 2ca971bc846..cbbcb6eb0e9 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -127,6 +127,8 @@ describe("ssh tunnel scripts", () => {
     assert.include(buildRemoteLaunchScript(), 'kill "$REMOTE_PID" 2>/dev/null || true');
     assert.include(buildRemoteLaunchScript(), "wait_ready");
     assert.include(buildRemoteLaunchScript(), '"$RUNNER_FILE" serve --host 127.0.0.1');
+    assert.include(buildRemoteLaunchScript(), '--base-dir "$DEFAULT_SERVER_HOME"');
+    assert.notInclude(buildRemoteLaunchScript(), "server-home");
     assert.include(buildRemoteLaunchScript(), "Remote T3 server did not become ready");
     assert.include(buildRemoteLaunchScript({ packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
@@ -135,20 +137,15 @@ describe("ssh tunnel scripts", () => {
     );
     assert.include(buildRemotePairingScript(target), "diagnostics");
     assert.include(buildRemotePairingScript(target), "VITE_DEV_SERVER_URL");
-    assert.include(buildRemotePairingScript(target), 'BASE_DIR_FILE="$STATE_DIR/base-dir"');
-    assert.include(buildRemotePairingScript(target), 'MANAGED_FILE="$STATE_DIR/managed"');
-    assert.include(buildRemotePairingScript(target), 'PAIRING_MANAGED="$(cat "$MANAGED_FILE"');
     assert.include(buildRemotePairingScript(target), 'PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"');
+    assert.notInclude(buildRemotePairingScript(target), "server-home");
     assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
     assert.include(
       buildRemoteStopScript(target),
       'if [ "$REMOTE_MANAGED" != "external" ] && [ -n "$REMOTE_PID" ]',
     );
     assert.include(buildRemoteStopScript(target), 'kill "$REMOTE_PID" 2>/dev/null || true');
-    assert.include(
-      buildRemoteStopScript(target),
-      'rm -f "$PID_FILE" "$PORT_FILE" "$BASE_DIR_FILE" "$MANAGED_FILE"',
-    );
+    assert.include(buildRemoteStopScript(target), 'rm -f "$PID_FILE" "$PORT_FILE" "$MANAGED_FILE"');
     assert.include(
       buildRemoteLaunchScript(),
       'DEFAULT_RUNTIME_FILE="$DEFAULT_SERVER_HOME/userdata/server-runtime.json"',
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index f05b2df8c2f..1b2f4eac2cf 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -336,17 +336,15 @@ exit 1
 export const REMOTE_LAUNCH_SCRIPT = `set -eu
 STATE_KEY="$1"
 STATE_DIR="$HOME/.t3/ssh-launch/$STATE_KEY"
-SERVER_HOME="$STATE_DIR/server-home"
 DEFAULT_SERVER_HOME="$HOME/.t3"
 DEFAULT_RUNTIME_FILE="$DEFAULT_SERVER_HOME/userdata/server-runtime.json"
 PORT_FILE="$STATE_DIR/port"
 PID_FILE="$STATE_DIR/pid"
-BASE_DIR_FILE="$STATE_DIR/base-dir"
 MANAGED_FILE="$STATE_DIR/managed"
 LOG_FILE="$STATE_DIR/server.log"
 RUNNER_FILE="$STATE_DIR/run-t3.sh"
 RUNNER_NEXT="$STATE_DIR/run-t3.next.$$"
-mkdir -p "$STATE_DIR" "$SERVER_HOME"
+mkdir -p "$STATE_DIR"
 cleanup_runner_next() {
   rm -f "$RUNNER_NEXT"
 }
@@ -408,7 +406,6 @@ if [ -n "$DEFAULT_REMOTE_PORT" ]; then
   REMOTE_PORT="$DEFAULT_REMOTE_PORT"
   if wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
     printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
-    printf '%s\\n' "$DEFAULT_SERVER_HOME" >"$BASE_DIR_FILE"
     printf 'external\\n' >"$MANAGED_FILE"
     REMOTE_PID=""
     REMOTE_MANAGED="external"
@@ -449,18 +446,17 @@ if [ -z "$REMOTE_PID" ] || [ -z "$REMOTE_PORT" ]; then
     printf 'Failed to find an available port on the remote host. Ensure node is available on PATH.\\n' >&2
     exit 1
   fi
-  nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
+  nohup env T3CODE_NO_BROWSER=1 "$RUNNER_FILE" serve --host 127.0.0.1 --port "$REMOTE_PORT" --base-dir "$DEFAULT_SERVER_HOME" >>"$LOG_FILE" 2>&1 < /dev/null &
   REMOTE_PID="$!"
   printf '%s\\n' "$REMOTE_PID" >"$PID_FILE"
   printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
-  printf '%s\\n' "$SERVER_HOME" >"$BASE_DIR_FILE"
   printf 'managed\\n' >"$MANAGED_FILE"
   if ! wait_ready "@@T3_READY_TIMEOUT_MS@@"; then
     printf 'Remote T3 server did not become ready on 127.0.0.1:%s.\\n' "$REMOTE_PORT" >&2
     tail -n 80 "$LOG_FILE" >&2 2>/dev/null || true
     kill "$REMOTE_PID" 2>/dev/null || true
     wait_for_pid_exit "$REMOTE_PID"
-    rm -f "$PID_FILE" "$PORT_FILE" "$BASE_DIR_FILE" "$MANAGED_FILE"
+    rm -f "$PID_FILE" "$PORT_FILE" "$MANAGED_FILE"
     exit 1
   fi
 fi
@@ -469,48 +465,14 @@ printf '{"remotePort":%s,"serverKind":"%s"}\\n' "$REMOTE_PORT" "\${REMOTE_MANAGE
 
 export const REMOTE_PAIRING_SCRIPT = `set -eu
 STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
-SERVER_HOME="$STATE_DIR/server-home"
 DEFAULT_SERVER_HOME="$HOME/.t3"
-DEFAULT_RUNTIME_FILE="$DEFAULT_SERVER_HOME/userdata/server-runtime.json"
-BASE_DIR_FILE="$STATE_DIR/base-dir"
-MANAGED_FILE="$STATE_DIR/managed"
 RUNNER_FILE="$STATE_DIR/run-t3.sh"
-mkdir -p "$STATE_DIR" "$SERVER_HOME"
+mkdir -p "$STATE_DIR"
 cat >"$RUNNER_FILE" <<'SH'
 @@T3_RUNNER_SCRIPT@@
 SH
 chmod 700 "$RUNNER_FILE"
-default_runtime_is_ready() {
-  node - "$DEFAULT_RUNTIME_FILE" <<'NODE'
-const fs = require("node:fs");
-const runtimePath = process.argv[2] ?? "";
-try {
-  const runtime = JSON.parse(fs.readFileSync(runtimePath, "utf8"));
-  const pid = Number(runtime.pid);
-  const port = Number(runtime.port);
-  if (!Number.isInteger(pid) || !Number.isInteger(port)) {
-    process.exit(1);
-  }
-  const origin = new URL(String(runtime.origin ?? ""));
-  if (origin.protocol !== "http:" || !["127.0.0.1", "localhost"].includes(origin.hostname)) {
-    process.exit(1);
-  }
-  process.kill(pid, 0);
-} catch {
-  process.exit(1);
-}
-NODE
-}
-PAIRING_BASE_DIR="$(cat "$BASE_DIR_FILE" 2>/dev/null || true)"
-PAIRING_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
-if [ "$PAIRING_MANAGED" = "external" ]; then
-  PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"
-elif [ -z "$PAIRING_BASE_DIR" ] && default_runtime_is_ready 2>/dev/null; then
-  PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"
-fi
-if [ -z "$PAIRING_BASE_DIR" ]; then
-  PAIRING_BASE_DIR="$SERVER_HOME"
-fi
+PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"
 PAIRING_OUTPUT="$("$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json)"
 PAIRING_OUTPUT="$PAIRING_OUTPUT" node - "$PAIRING_BASE_DIR" "$RUNNER_FILE" <<'NODE'
 const path = require("node:path");
@@ -555,7 +517,6 @@ export const REMOTE_STOP_SCRIPT = `set -eu
 STATE_DIR="$HOME/.t3/ssh-launch/@@T3_STATE_KEY@@"
 PID_FILE="$STATE_DIR/pid"
 PORT_FILE="$STATE_DIR/port"
-BASE_DIR_FILE="$STATE_DIR/base-dir"
 MANAGED_FILE="$STATE_DIR/managed"
 REMOTE_MANAGED="$(cat "$MANAGED_FILE" 2>/dev/null || true)"
 REMOTE_PID="$(cat "$PID_FILE" 2>/dev/null || true)"
@@ -567,7 +528,7 @@ if [ "$REMOTE_MANAGED" != "external" ] && [ -n "$REMOTE_PID" ] && kill -0 "$REMO
     sleep 0.1
   done
 fi
-rm -f "$PID_FILE" "$PORT_FILE" "$BASE_DIR_FILE" "$MANAGED_FILE"
+rm -f "$PID_FILE" "$PORT_FILE" "$MANAGED_FILE"
 printf '{"stopped":true}\\n'
 `;
 

From e30876e841c1fa62ba3f5e33492708c5c6a8174a Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 22:42:44 -0700
Subject: [PATCH 63/74] Trim SSH pairing diagnostics

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/web/src/environments/runtime/service.ts | 17 ------
 packages/contracts/src/ipc.ts                |  9 ----
 packages/ssh/src/tunnel.test.ts              |  2 -
 packages/ssh/src/tunnel.ts                   | 54 +-------------------
 4 files changed, 1 insertion(+), 81 deletions(-)

diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 40e12121c13..919c022b24d 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -662,7 +662,6 @@ async function prepareSavedEnvironmentRecordForConnection(
   readonly pairingToken: string | null;
   readonly remotePort: number | null;
   readonly remoteServerKind: "external" | "managed" | null;
-  readonly pairingDiagnostics: DesktopSshEnvironmentBootstrap["pairingDiagnostics"] | null;
 }> {
   if (!record.desktopSsh) {
     return {
@@ -670,7 +669,6 @@ async function prepareSavedEnvironmentRecordForConnection(
       pairingToken: null,
       remotePort: null,
       remoteServerKind: null,
-      pairingDiagnostics: null,
     };
   }
 
@@ -696,7 +694,6 @@ async function prepareSavedEnvironmentRecordForConnection(
     pairingToken: bootstrap.pairingToken,
     remotePort: bootstrap.remotePort ?? null,
     remoteServerKind: bootstrap.remoteServerKind ?? null,
-    pairingDiagnostics: bootstrap.pairingDiagnostics ?? null,
   };
 }
 
@@ -721,13 +718,6 @@ async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Pro
       `local ${prepared.record.httpBaseUrl}`,
       `remote port ${prepared.remotePort ?? "unknown"}`,
       prepared.remoteServerKind ? `remote server ${prepared.remoteServerKind}` : null,
-      prepared.pairingDiagnostics ? `pairing db ${prepared.pairingDiagnostics.dbPath}` : null,
-      prepared.pairingDiagnostics
-        ? `pairing runtime ${prepared.pairingDiagnostics.runtimePath}`
-        : null,
-      prepared.pairingDiagnostics
-        ? `pairing devUrl ${prepared.pairingDiagnostics.devUrl ?? "none"}`
-        : null,
     ]
       .filter(Boolean)
       .join(", ");
@@ -1589,13 +1579,6 @@ export async function connectDesktopSshEnvironment(
       `local ${bootstrap.httpBaseUrl}`,
       `remote port ${bootstrap.remotePort ?? "unknown"}`,
       bootstrap.remoteServerKind ? `remote server ${bootstrap.remoteServerKind}` : null,
-      bootstrap.pairingDiagnostics ? `pairing db ${bootstrap.pairingDiagnostics.dbPath}` : null,
-      bootstrap.pairingDiagnostics
-        ? `pairing runtime ${bootstrap.pairingDiagnostics.runtimePath}`
-        : null,
-      bootstrap.pairingDiagnostics
-        ? `pairing devUrl ${bootstrap.pairingDiagnostics.devUrl ?? "none"}`
-        : null,
     ]
       .filter(Boolean)
       .join(", ");
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index be13302153a..85e1e8f3349 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -155,15 +155,6 @@ export interface DesktopSshEnvironmentBootstrap {
   pairingToken: string | null;
   remotePort?: number;
   remoteServerKind?: "external" | "managed";
-  pairingDiagnostics?: {
-    baseDir: string;
-    stateDir: string;
-    dbPath: string;
-    runtimePath: string;
-    devUrl: string | null;
-    t3codeHome: string | null;
-    runnerPath: string;
-  };
 }
 
 export interface DesktopSshPasswordPromptRequest {
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index cbbcb6eb0e9..9d0191d05f0 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -135,8 +135,6 @@ describe("ssh tunnel scripts", () => {
       buildRemotePairingScript(target),
       '"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json',
     );
-    assert.include(buildRemotePairingScript(target), "diagnostics");
-    assert.include(buildRemotePairingScript(target), "VITE_DEV_SERVER_URL");
     assert.include(buildRemotePairingScript(target), 'PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"');
     assert.notInclude(buildRemotePairingScript(target), "server-home");
     assert.include(buildRemotePairingScript(target, { packageSpec: "t3@nightly" }), "t3@nightly");
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 1b2f4eac2cf..24bad01c47a 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -158,17 +158,6 @@ const RemoteLaunchResult = Schema.Struct({
 
 const RemotePairingResult = Schema.Struct({
   credential: Schema.String,
-  diagnostics: Schema.optional(
-    Schema.Struct({
-      baseDir: Schema.String,
-      stateDir: Schema.String,
-      dbPath: Schema.String,
-      runtimePath: Schema.String,
-      devUrl: Schema.NullOr(Schema.String),
-      t3codeHome: Schema.NullOr(Schema.String),
-      runnerPath: Schema.String,
-    }),
-  ),
 });
 
 const RemoteHttpError = Schema.Struct({
@@ -473,44 +462,7 @@ cat >"$RUNNER_FILE" <<'SH'
 SH
 chmod 700 "$RUNNER_FILE"
 PAIRING_BASE_DIR="$DEFAULT_SERVER_HOME"
-PAIRING_OUTPUT="$("$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json)"
-PAIRING_OUTPUT="$PAIRING_OUTPUT" node - "$PAIRING_BASE_DIR" "$RUNNER_FILE" <<'NODE'
-const path = require("node:path");
-const baseDir = process.argv[2] ?? "";
-const runnerPath = process.argv[3] ?? "";
-const raw = process.env.PAIRING_OUTPUT ?? "";
-const trimmed = raw.trim();
-if (!trimmed) {
-  process.exit(1);
-}
-let result;
-try {
-  result = JSON.parse(trimmed);
-} catch {
-  const start = trimmed.indexOf("{");
-  const end = trimmed.lastIndexOf("}");
-  if (start < 0 || end <= start) {
-    throw new Error("Unable to find JSON object in pairing command output.");
-  }
-  result = JSON.parse(trimmed.slice(start, end + 1));
-}
-const devUrl = process.env.VITE_DEV_SERVER_URL || null;
-const stateDir = path.join(baseDir, devUrl ? "dev" : "userdata");
-process.stdout.write(
-  JSON.stringify({
-    ...result,
-    diagnostics: {
-      baseDir,
-      stateDir,
-      dbPath: path.join(stateDir, "state.sqlite"),
-      runtimePath: path.join(stateDir, "server-runtime.json"),
-      devUrl,
-      t3codeHome: process.env.T3CODE_HOME || null,
-      runnerPath,
-    },
-  }) + "\\n",
-);
-NODE
+"$RUNNER_FILE" auth pairing create --base-dir "$PAIRING_BASE_DIR" --json
 `;
 
 export const REMOTE_STOP_SCRIPT = `set -eu
@@ -650,7 +602,6 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
 ): Effect.fn.Return<
   {
     readonly credential: string;
-    readonly diagnostics?: typeof RemotePairingResult.Type.diagnostics;
   },
   SshCommandError | SshInvalidTargetError | SshPairingError,
   ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path
@@ -691,11 +642,9 @@ export const issueRemotePairingToken = Effect.fn("ssh/tunnel.issueRemotePairingT
   yield* Effect.logDebug("ssh.remoteServer.pairingToken.created", {
     ...sshTargetLogFields(target),
     stateKey: remoteStateKey(target),
-    diagnostics: parsed.diagnostics ?? null,
   });
   return {
     credential: parsed.credential,
-    ...(parsed.diagnostics ? { diagnostics: parsed.diagnostics } : {}),
   };
 });
 
@@ -1570,7 +1519,6 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
       pairingToken,
       remotePort: entry.remotePort,
       ...(entry.remoteServerKind ? { remoteServerKind: entry.remoteServerKind } : {}),
-      ...(pairingResult?.diagnostics ? { pairingDiagnostics: pairingResult.diagnostics } : {}),
     };
   });
 

From 85f4df763b7b7f19ea0540f793f0f34d992cf9fc Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Thu, 30 Apr 2026 22:59:27 -0700
Subject: [PATCH 64/74] Address SSH and pairing review feedback

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/desktop/src/main.ts                      |  4 +--
 apps/desktop/src/sshEnvironment.test.ts       | 14 +++++++-
 apps/desktop/src/sshEnvironment.ts            | 36 +++++++++++++++----
 .../components/auth/PairingRouteSurface.tsx   |  7 +++-
 apps/web/src/environments/runtime/service.ts  |  3 +-
 packages/ssh/src/tunnel.test.ts               |  4 +++
 packages/ssh/src/tunnel.ts                    |  4 +++
 7 files changed, 61 insertions(+), 11 deletions(-)

diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 13bae998c8e..9c097fc9bd1 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -123,8 +123,8 @@ const isDevelopment = Boolean(process.env.VITE_DEV_SERVER_URL);
 // Dev-only SSH launcher override. Set this to an absolute path on the SSH host
 // for a built server entry, for example:
 // "/Users/julius/Development/Work/codething-mvp/apps/server/dist/bin.mjs"
-const DEV_REMOTE_T3_SERVER_ENTRY_PATH = "/Users/julius/Developer/t3code/apps/server/dist/bin.mjs";
-process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ?? "";
+const DEV_REMOTE_T3_SERVER_ENTRY_PATH =
+  process.env.T3CODE_DEV_REMOTE_T3_SERVER_ENTRY_PATH?.trim() ?? "";
 const desktopAppBranding: DesktopAppBranding = resolveDesktopAppBranding({
   isDevelopment,
   appVersion: app.getVersion(),
diff --git a/apps/desktop/src/sshEnvironment.test.ts b/apps/desktop/src/sshEnvironment.test.ts
index cb6281b9ccc..d22e09957d1 100644
--- a/apps/desktop/src/sshEnvironment.test.ts
+++ b/apps/desktop/src/sshEnvironment.test.ts
@@ -4,7 +4,9 @@ import * as Path from "node:path";
 
 import { afterEach, describe, expect, it } from "vitest";
 
-import { discoverDesktopSshHosts } from "./sshEnvironment.ts";
+import { SshPasswordPromptError } from "@t3tools/ssh/errors";
+
+import { discoverDesktopSshHosts, isSshPasswordPromptCancellation } from "./sshEnvironment.ts";
 
 const tempDirectories: string[] = [];
 
@@ -21,6 +23,16 @@ function makeTempHomeDir(): string {
 }
 
 describe("sshEnvironment", () => {
+  it("treats password prompt timeouts as cancellable authentication prompts", () => {
+    expect(
+      isSshPasswordPromptCancellation(
+        new SshPasswordPromptError({
+          message: "SSH authentication timed out for devbox.",
+        }),
+      ),
+    ).toBe(true);
+  });
+
   it("wires desktop host discovery through the ssh package runtime", async () => {
     const homeDir = makeTempHomeDir();
     const sshDir = Path.join(homeDir, ".ssh");
diff --git a/apps/desktop/src/sshEnvironment.ts b/apps/desktop/src/sshEnvironment.ts
index c4c288aade1..e847e07d498 100644
--- a/apps/desktop/src/sshEnvironment.ts
+++ b/apps/desktop/src/sshEnvironment.ts
@@ -203,9 +203,11 @@ interface PendingSshPasswordPrompt {
   readonly timeout: ReturnType<typeof setTimeout>;
 }
 
-function isSshPasswordPromptCancellation(error: unknown): error is SshPasswordPromptError {
+export function isSshPasswordPromptCancellation(error: unknown): error is SshPasswordPromptError {
+  const message = error instanceof SshPasswordPromptError ? error.message.toLowerCase() : "";
   return (
-    error instanceof SshPasswordPromptError && error.message.toLowerCase().includes("cancelled")
+    error instanceof SshPasswordPromptError &&
+    (message.includes("cancelled") || message.includes("timed out"))
   );
 }
 
@@ -378,6 +380,11 @@ export class DesktopSshEnvironmentBridge {
     };
 
     return await new Promise<string | null>((resolve, reject) => {
+      const rejectPrompt = (error: Error) => {
+        clearTimeout(timeout);
+        this.pendingPrompts.delete(request.requestId);
+        reject(error);
+      };
       const timeout = setTimeout(() => {
         this.pendingPrompts.delete(request.requestId);
         reject(new Error(`SSH authentication timed out for ${input.destination}.`));
@@ -386,11 +393,28 @@ export class DesktopSshEnvironmentBridge {
 
       this.pendingPrompts.set(request.requestId, { resolve, reject, timeout });
 
-      window.webContents.send(SSH_PASSWORD_PROMPT_CHANNEL, request);
-      if (window.isMinimized()) {
-        window.restore();
+      try {
+        if (window.isDestroyed()) {
+          throw new Error("T3 Code window is not available for SSH authentication.");
+        }
+        window.webContents.send(SSH_PASSWORD_PROMPT_CHANNEL, request);
+        if (window.isDestroyed()) {
+          throw new Error("T3 Code window is not available for SSH authentication.");
+        }
+        if (window.isMinimized()) {
+          window.restore();
+        }
+        if (window.isDestroyed()) {
+          throw new Error("T3 Code window is not available for SSH authentication.");
+        }
+        window.focus();
+      } catch (error) {
+        rejectPrompt(
+          error instanceof Error
+            ? error
+            : new Error("T3 Code window is not available for SSH authentication."),
+        );
       }
-      window.focus();
     });
   }
 }
diff --git a/apps/web/src/components/auth/PairingRouteSurface.tsx b/apps/web/src/components/auth/PairingRouteSurface.tsx
index 4ae7b6574c0..65e9c6dd8eb 100644
--- a/apps/web/src/components/auth/PairingRouteSurface.tsx
+++ b/apps/web/src/components/auth/PairingRouteSurface.tsx
@@ -171,6 +171,7 @@ export function HostedPairingRouteSurface() {
       ? "Connecting to this backend."
       : "This pairing link is missing its backend host or token.",
   );
+  const [canRetry, setCanRetry] = useState(false);
   const submitAttemptedRef = useRef(false);
   const tokenSubmittedRef = useRef(false);
 
@@ -180,17 +181,20 @@ export function HostedPairingRouteSurface() {
     if (!request) {
       setStatus("error");
       setMessage("This pairing link is missing its backend host or token.");
+      setCanRetry(false);
       return;
     }
 
     if (tokenSubmittedRef.current) {
       setStatus("error");
       setMessage("This one-time pairing token was already submitted. Request a new pairing link.");
+      setCanRetry(false);
       return;
     }
 
     setStatus("pairing");
     setMessage("Connecting to this backend.");
+    setCanRetry(false);
     tokenSubmittedRef.current = true;
 
     try {
@@ -204,6 +208,7 @@ export function HostedPairingRouteSurface() {
     } catch (error) {
       tokenSubmittedRef.current = false;
       setStatus("error");
+      setCanRetry(true);
       setMessage(
         `${errorMessageFromUnknown(error)} If the backend accepted this one-time token, request a new pairing link before retrying.`,
       );
@@ -261,7 +266,7 @@ export function HostedPairingRouteSurface() {
             <Button disabled size="sm">
               Pairing...
             </Button>
-          ) : !tokenSubmittedRef.current ? (
+          ) : canRetry ? (
             <Button size="sm" onClick={() => void submitHostedPairingRequest()}>
               Try again
             </Button>
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 919c022b24d..e5f74529806 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -713,7 +713,8 @@ async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Pro
   const bearerSession = await bootstrapDesktopSshBearerSession(
     prepared.record.httpBaseUrl,
     prepared.pairingToken,
-  ).catch((error) => {
+  ).catch(async (error) => {
+    await persistSavedEnvironmentRegistryRollback(registrySnapshot);
     const detail = [
       `local ${prepared.record.httpBaseUrl}`,
       `remote port ${prepared.remotePort ?? "unknown"}`,
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 9d0191d05f0..5a03ce25ac6 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -150,6 +150,10 @@ describe("ssh tunnel scripts", () => {
     );
     assert.include(buildRemoteLaunchScript(), "resolve_default_runtime_port()");
     assert.include(buildRemoteLaunchScript(), "printf 'external\\n' >\"$MANAGED_FILE\"");
+    assert.isBelow(
+      buildRemoteLaunchScript().indexOf('if [ "$REMOTE_MANAGED" = "managed" ]'),
+      buildRemoteLaunchScript().indexOf("printf 'external\\n' >\"$MANAGED_FILE\""),
+    );
     assert.isBelow(
       buildRemoteLaunchScript().indexOf('DEFAULT_REMOTE_PORT="$(resolve_default_runtime_port'),
       buildRemoteLaunchScript().indexOf('elif [ -n "$REMOTE_PID" ]'),
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 24bad01c47a..a5e103c2087 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -394,6 +394,10 @@ DEFAULT_REMOTE_PORT="$(resolve_default_runtime_port 2>/dev/null || true)"
 if [ -n "$DEFAULT_REMOTE_PORT" ]; then
   REMOTE_PORT="$DEFAULT_REMOTE_PORT"
   if wait_ready "@@T3_REUSE_READY_TIMEOUT_MS@@"; then
+    if [ "$REMOTE_MANAGED" = "managed" ] && [ -n "$REMOTE_PID" ] && kill -0 "$REMOTE_PID" 2>/dev/null; then
+      kill "$REMOTE_PID" 2>/dev/null || true
+      wait_for_pid_exit "$REMOTE_PID"
+    fi
     printf '%s\\n' "$REMOTE_PORT" >"$PORT_FILE"
     printf 'external\\n' >"$MANAGED_FILE"
     REMOTE_PID=""

From 2ab5de87bd64a7f55cddbf9685547eaa59c5606e Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 1 May 2026 13:55:00 -0700
Subject: [PATCH 65/74] Retain thread subscriptions across reconnects

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .../service.threadSubscriptions.test.ts       | 98 ++++++++++++++++++-
 apps/web/src/environments/runtime/service.ts  | 23 ++++-
 2 files changed, 117 insertions(+), 4 deletions(-)

diff --git a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
index 0025e710e63..b0b72f1e52a 100644
--- a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
+++ b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
@@ -15,8 +15,12 @@ const mockCreateEnvironmentConnection = vi.fn();
 const mockCreateWsRpcClient = vi.fn();
 const mockWaitForSavedEnvironmentRegistryHydration = vi.fn();
 const mockListSavedEnvironmentRecords = vi.fn();
+const mockGetSavedEnvironmentRecord = vi.fn();
+const mockReadSavedEnvironmentBearerToken = vi.fn();
 const mockSavedEnvironmentRegistrySubscribe = vi.fn();
 const mockGetPrimaryKnownEnvironment = vi.hoisted(() => vi.fn());
+const mockFetchRemoteSessionState = vi.fn();
+let savedEnvironmentRegistryListener: (() => void) | null = null;
 
 function MockWsTransport() {
   return undefined;
@@ -26,12 +30,20 @@ vi.mock("../primary", () => ({
   getPrimaryKnownEnvironment: mockGetPrimaryKnownEnvironment,
 }));
 
+vi.mock("../remote/api", () => ({
+  bootstrapRemoteBearerSession: vi.fn(),
+  fetchRemoteEnvironmentDescriptor: vi.fn(),
+  fetchRemoteSessionState: mockFetchRemoteSessionState,
+  isRemoteEnvironmentAuthHttpError: vi.fn(() => false),
+  resolveRemoteWebSocketConnectionUrl: vi.fn(async () => "ws://remote.example.test/ws"),
+}));
+
 vi.mock("./catalog", () => ({
-  getSavedEnvironmentRecord: vi.fn(),
+  getSavedEnvironmentRecord: mockGetSavedEnvironmentRecord,
   hasSavedEnvironmentRegistryHydrated: vi.fn(() => true),
   listSavedEnvironmentRecords: mockListSavedEnvironmentRecords,
   persistSavedEnvironmentRecord: vi.fn(),
-  readSavedEnvironmentBearerToken: vi.fn(),
+  readSavedEnvironmentBearerToken: mockReadSavedEnvironmentBearerToken,
   removeSavedEnvironmentBearerToken: vi.fn(),
   useSavedEnvironmentRegistryStore: {
     subscribe: mockSavedEnvironmentRegistrySubscribe,
@@ -152,6 +164,17 @@ describe("retainThreadDetailSubscription", () => {
     mockThreadUnsubscribe.mockImplementation(() => undefined);
     mockSubscribeThread.mockImplementation(() => mockThreadUnsubscribe);
     mockCreateWsRpcClient.mockReturnValue({
+      server: {
+        getConfig: vi.fn(async () => ({
+          environment: {
+            environmentId: EnvironmentId.make("env-remote"),
+            label: "Remote env",
+            platform: { os: "darwin", arch: "arm64" },
+            serverVersion: "0.0.0-test",
+            capabilities: { repositoryIdentity: true },
+          },
+        })),
+      },
       orchestration: {
         subscribeThread: mockSubscribeThread,
       },
@@ -165,9 +188,23 @@ describe("retainThreadDetailSubscription", () => {
       reconnect: vi.fn(async () => undefined),
       dispose: vi.fn(async () => undefined),
     }));
-    mockSavedEnvironmentRegistrySubscribe.mockReturnValue(() => undefined);
+    savedEnvironmentRegistryListener = null;
+    mockSavedEnvironmentRegistrySubscribe.mockImplementation((listener: () => void) => {
+      savedEnvironmentRegistryListener = listener;
+      return () => {
+        if (savedEnvironmentRegistryListener === listener) {
+          savedEnvironmentRegistryListener = null;
+        }
+      };
+    });
     mockWaitForSavedEnvironmentRegistryHydration.mockResolvedValue(undefined);
     mockListSavedEnvironmentRecords.mockReturnValue([]);
+    mockGetSavedEnvironmentRecord.mockReturnValue(null);
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockFetchRemoteSessionState.mockResolvedValue({
+      authenticated: true,
+      role: "client",
+    });
   });
 
   afterEach(async () => {
@@ -281,6 +318,61 @@ describe("retainThreadDetailSubscription", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("reattaches retained thread detail subscriptions after a saved environment reconnect replaces the client", async () => {
+    const environmentId = EnvironmentId.make("env-remote");
+    const threadId = ThreadId.make("thread-reconnect");
+    const record = {
+      environmentId,
+      label: "Remote env",
+      httpBaseUrl: "http://remote.example.test",
+      wsBaseUrl: "ws://remote.example.test",
+      createdAt: "2026-05-01T00:00:00.000Z",
+      lastConnectedAt: "2026-05-01T00:00:00.000Z",
+    };
+    mockListSavedEnvironmentRecords.mockReturnValue([record]);
+    mockGetSavedEnvironmentRecord.mockReturnValue(record);
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue("bearer-token");
+
+    const {
+      disconnectSavedEnvironment,
+      listEnvironmentConnections,
+      reconnectSavedEnvironment,
+      retainThreadDetailSubscription,
+      startEnvironmentConnectionService,
+      resetEnvironmentServiceForTests,
+    } = await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    savedEnvironmentRegistryListener?.();
+    await vi.waitFor(() => {
+      expect(mockCreateEnvironmentConnection).toHaveBeenCalledTimes(2);
+      expect(
+        listEnvironmentConnections().some(
+          (connection) => connection.environmentId === environmentId,
+        ),
+      ).toBe(true);
+    });
+
+    const release = retainThreadDetailSubscription(environmentId, threadId);
+    expect(mockSubscribeThread).toHaveBeenCalledTimes(1);
+
+    await disconnectSavedEnvironment(environmentId);
+    expect(mockThreadUnsubscribe).toHaveBeenCalledTimes(1);
+    expect(
+      listEnvironmentConnections().some((connection) => connection.environmentId === environmentId),
+    ).toBe(false);
+
+    await reconnectSavedEnvironment(environmentId);
+    await vi.waitFor(() => {
+      expect(mockCreateEnvironmentConnection).toHaveBeenCalledTimes(3);
+      expect(mockSubscribeThread).toHaveBeenCalledTimes(2);
+    });
+
+    release();
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
   it("allows a larger idle cache before capacity eviction starts", async () => {
     const {
       retainThreadDetailSubscription,
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index e5f74529806..86f4ac91782 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -357,6 +357,25 @@ function disposeThreadDetailSubscriptionsForEnvironment(environmentId: Environme
   }
 }
 
+function detachThreadDetailSubscriptionsForEnvironment(environmentId: EnvironmentId): void {
+  for (const entry of threadDetailSubscriptions.values()) {
+    if (entry.environmentId !== environmentId) {
+      continue;
+    }
+    entry.unsubscribe();
+    entry.unsubscribe = NOOP;
+    watchThreadDetailSubscriptionConnection(entry);
+  }
+}
+
+function attachThreadDetailSubscriptionsForEnvironment(environmentId: EnvironmentId): void {
+  for (const entry of threadDetailSubscriptions.values()) {
+    if (entry.environmentId === environmentId) {
+      attachThreadDetailSubscription(entry);
+    }
+  }
+}
+
 function reconcileThreadDetailSubscriptionsForEnvironment(
   environmentId: EnvironmentId,
   threadIds: ReadonlyArray<ThreadId>,
@@ -1166,6 +1185,7 @@ function registerConnection(connection: EnvironmentConnection): EnvironmentConne
     throw new Error(`Environment ${connection.environmentId} already has an active connection.`);
   }
   environmentConnections.set(connection.environmentId, connection);
+  attachThreadDetailSubscriptionsForEnvironment(connection.environmentId);
   emitEnvironmentConnectionRegistryChange();
   return connection;
 }
@@ -1176,10 +1196,10 @@ async function removeConnection(environmentId: EnvironmentId): Promise<boolean>
     return false;
   }
 
-  disposeThreadDetailSubscriptionsForEnvironment(environmentId);
   lastAppliedProjectionVersionByEnvironment.delete(environmentId);
   environmentConnections.delete(environmentId);
   emitEnvironmentConnectionRegistryChange();
+  detachThreadDetailSubscriptionsForEnvironment(environmentId);
   await connection.dispose();
   return true;
 }
@@ -1488,6 +1508,7 @@ export async function reconnectSavedEnvironment(environmentId: EnvironmentId): P
 
 export async function removeSavedEnvironment(environmentId: EnvironmentId): Promise<void> {
   await disconnectSavedEnvironment(environmentId);
+  disposeThreadDetailSubscriptionsForEnvironment(environmentId);
   useSavedEnvironmentRegistryStore.getState().remove(environmentId);
   useSavedEnvironmentRuntimeStore.getState().clear(environmentId);
   useStore.getState().removeEnvironmentState(environmentId);

From ae22e8b42979d26a3e60d2247c0838c52dd5e410 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 1 May 2026 14:05:33 -0700
Subject: [PATCH 66/74] Handle stale tunnel and SSH rollback paths

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .../service.addSavedEnvironment.test.ts       | 48 +++++++++++++++++++
 apps/web/src/environments/runtime/service.ts  |  1 +
 packages/ssh/src/tunnel.ts                    | 21 +++++---
 3 files changed, 63 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
index 3d9a51d833c..04aa11e86d1 100644
--- a/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
+++ b/apps/web/src/environments/runtime/service.addSavedEnvironment.test.ts
@@ -813,6 +813,54 @@ describe("addSavedEnvironment", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("rolls back ssh registry metadata when pairing token issuance fails", async () => {
+    const originalRecord = {
+      environmentId: EnvironmentId.make("environment-1"),
+      label: "Remote environment",
+      httpBaseUrl: "http://127.0.0.1:3773/",
+      wsBaseUrl: "ws://127.0.0.1:3773/",
+      createdAt: "2026-04-14T00:00:00.000Z",
+      lastConnectedAt: null,
+      desktopSsh: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+    };
+    mockSavedRecords = [originalRecord];
+    mockReadSavedEnvironmentBearerToken.mockResolvedValue(null);
+    mockEnsureSshEnvironment.mockResolvedValue({
+      target: {
+        alias: "devbox",
+        hostname: "devbox.example.com",
+        username: "julius",
+        port: 22,
+      },
+      httpBaseUrl: "http://127.0.0.1:3774/",
+      wsBaseUrl: "ws://127.0.0.1:3774/",
+      pairingToken: null,
+    });
+
+    const { reconnectSavedEnvironment, resetEnvironmentServiceForTests } =
+      await import("./service");
+
+    await expect(reconnectSavedEnvironment(EnvironmentId.make("environment-1"))).rejects.toThrow(
+      "Desktop SSH launch did not return a pairing token.",
+    );
+
+    expect(mockPersistSavedEnvironmentRecord).toHaveBeenCalledWith(
+      expect.objectContaining({
+        httpBaseUrl: "http://127.0.0.1:3774/",
+      }),
+    );
+    expect(mockSetSavedEnvironmentRegistry).toHaveBeenCalledWith([originalRecord]);
+    expect(mockSavedRecords).toEqual([originalRecord]);
+    expect(mockBootstrapSshBearerSession).not.toHaveBeenCalled();
+
+    await resetEnvironmentServiceForTests();
+  });
+
   it("surfaces desktop ssh bootstrap failures during saved ssh reconnect", async () => {
     mockSavedRecords = [
       {
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 86f4ac91782..7d5e8060465 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -726,6 +726,7 @@ async function issueDesktopSshBearerSession(record: SavedEnvironmentRecord): Pro
     issuePairingToken: true,
   });
   if (!prepared.pairingToken) {
+    await persistSavedEnvironmentRegistryRollback(registrySnapshot);
     throw new Error("Desktop SSH launch did not return a pairing token.");
   }
 
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index a5e103c2087..131b1612f8a 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -1161,6 +1161,18 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     });
   });
 
+  const cancelPendingTunnelEntry = Effect.fn("ssh/tunnel.cancelPendingTunnelEntry")(function* (
+    key: string,
+    target: DesktopSshEnvironmentTarget,
+  ) {
+    const pending = pendingTunnelEntries.get(key);
+    if (!pending) {
+      return;
+    }
+    pendingTunnelEntries.delete(key);
+    yield* Deferred.fail(pending, makeSshTunnelCancelledError(target)).pipe(Effect.ignore);
+  });
+
   yield* Scope.addFinalizer(
     managerScope,
     Effect.sync(() => [...tunnels.values()]).pipe(
@@ -1429,6 +1441,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
         cause: readinessExit.cause,
       });
       yield* closeTunnelEntry(entry);
+      yield* cancelPendingTunnelEntry(key, resolvedTarget);
       entry = null;
     }
 
@@ -1547,13 +1560,7 @@ const makeSshEnvironmentManager = Effect.fn("ssh/tunnel.SshEnvironmentManager.ma
     if (entry !== null) {
       yield* closeTunnelEntry(entry);
     }
-    const pending = pendingTunnelEntries.get(key);
-    if (pending) {
-      pendingTunnelEntries.delete(key);
-      yield* Deferred.fail(pending, makeSshTunnelCancelledError(resolvedTarget)).pipe(
-        Effect.ignore,
-      );
-    }
+    yield* cancelPendingTunnelEntry(key, resolvedTarget);
     if (entry === null) {
       yield* runWithSshAuth({
         key,

From 6bf71e2d4ee1b09b0cba4d631276aaf4934d24f2 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 1 May 2026 14:32:20 -0700
Subject: [PATCH 67/74] Reconnect streams after browser resume

Co-authored-by: codex <codex@users.noreply.github.com>
---
 .../service.threadSubscriptions.test.ts       | 59 ++++++++++++++++---
 apps/web/src/environments/runtime/service.ts  | 57 ++++++++++++++++++
 2 files changed, 107 insertions(+), 9 deletions(-)

diff --git a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
index b0b72f1e52a..ea96d6c3219 100644
--- a/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
+++ b/apps/web/src/environments/runtime/service.threadSubscriptions.test.ts
@@ -20,6 +20,7 @@ const mockReadSavedEnvironmentBearerToken = vi.fn();
 const mockSavedEnvironmentRegistrySubscribe = vi.fn();
 const mockGetPrimaryKnownEnvironment = vi.hoisted(() => vi.fn());
 const mockFetchRemoteSessionState = vi.fn();
+const mockConnectionReconnects: Array<ReturnType<typeof vi.fn>> = [];
 let savedEnvironmentRegistryListener: (() => void) | null = null;
 
 function MockWsTransport() {
@@ -179,15 +180,19 @@ describe("retainThreadDetailSubscription", () => {
         subscribeThread: mockSubscribeThread,
       },
     });
-    mockCreateEnvironmentConnection.mockImplementation((input) => ({
-      kind: input.kind,
-      environmentId: input.knownEnvironment.environmentId,
-      knownEnvironment: input.knownEnvironment,
-      client: input.client,
-      ensureBootstrapped: vi.fn(async () => undefined),
-      reconnect: vi.fn(async () => undefined),
-      dispose: vi.fn(async () => undefined),
-    }));
+    mockCreateEnvironmentConnection.mockImplementation((input) => {
+      const reconnect = vi.fn(async () => undefined);
+      mockConnectionReconnects.push(reconnect);
+      return {
+        kind: input.kind,
+        environmentId: input.knownEnvironment.environmentId,
+        knownEnvironment: input.knownEnvironment,
+        client: input.client,
+        ensureBootstrapped: vi.fn(async () => undefined),
+        reconnect,
+        dispose: vi.fn(async () => undefined),
+      };
+    });
     savedEnvironmentRegistryListener = null;
     mockSavedEnvironmentRegistrySubscribe.mockImplementation((listener: () => void) => {
       savedEnvironmentRegistryListener = listener;
@@ -205,11 +210,13 @@ describe("retainThreadDetailSubscription", () => {
       authenticated: true,
       role: "client",
     });
+    mockConnectionReconnects.length = 0;
   });
 
   afterEach(async () => {
     const { resetEnvironmentServiceForTests } = await import("./service");
     await resetEnvironmentServiceForTests();
+    vi.unstubAllGlobals();
     vi.useRealTimers();
   });
 
@@ -373,6 +380,40 @@ describe("retainThreadDetailSubscription", () => {
     await resetEnvironmentServiceForTests();
   });
 
+  it("reconnects environment streams when the browser resumes from the background", async () => {
+    let visibilityState: DocumentVisibilityState = "visible";
+    const documentTarget = new EventTarget();
+    const windowTarget = new EventTarget();
+    vi.stubGlobal("document", {
+      addEventListener: documentTarget.addEventListener.bind(documentTarget),
+      removeEventListener: documentTarget.removeEventListener.bind(documentTarget),
+      get visibilityState() {
+        return visibilityState;
+      },
+    });
+    vi.stubGlobal("window", {
+      addEventListener: windowTarget.addEventListener.bind(windowTarget),
+      removeEventListener: windowTarget.removeEventListener.bind(windowTarget),
+    });
+
+    const { resetEnvironmentServiceForTests, startEnvironmentConnectionService } =
+      await import("./service");
+
+    const stop = startEnvironmentConnectionService(new QueryClient());
+    expect(mockConnectionReconnects).toHaveLength(1);
+
+    visibilityState = "hidden";
+    documentTarget.dispatchEvent(new Event("visibilitychange"));
+    expect(mockConnectionReconnects[0]).not.toHaveBeenCalled();
+
+    visibilityState = "visible";
+    documentTarget.dispatchEvent(new Event("visibilitychange"));
+    expect(mockConnectionReconnects[0]).toHaveBeenCalledTimes(1);
+
+    stop();
+    await resetEnvironmentServiceForTests();
+  });
+
   it("allows a larger idle cache before capacity eviction starts", async () => {
     const {
       retainThreadDetailSubscription,
diff --git a/apps/web/src/environments/runtime/service.ts b/apps/web/src/environments/runtime/service.ts
index 7d5e8060465..14562e3c492 100644
--- a/apps/web/src/environments/runtime/service.ts
+++ b/apps/web/src/environments/runtime/service.ts
@@ -126,6 +126,8 @@ const lastAppliedProjectionVersionByEnvironment = new Map<
 
 let activeService: EnvironmentServiceState | null = null;
 let needsProviderInvalidation = false;
+let lastBrowserHiddenAt: number | null = null;
+let lastBrowserResumeReconnectAt = Number.NEGATIVE_INFINITY;
 
 // Thread detail subscription cache policy:
 // - Active consumers keep a subscription retained via refCount.
@@ -136,6 +138,7 @@ let needsProviderInvalidation = false;
 // - Capacity eviction only targets idle cached subscriptions.
 const THREAD_DETAIL_SUBSCRIPTION_IDLE_EVICTION_MS = 15 * 60 * 1000;
 const MAX_CACHED_THREAD_DETAIL_SUBSCRIPTIONS = 32;
+const BROWSER_RESUME_RECONNECT_COOLDOWN_MS = 2_000;
 const NOOP = () => undefined;
 const SSH_HTTP_STATUS_RE = /^\[ssh_http:(\d+)\]\s/u;
 
@@ -1406,6 +1409,55 @@ function stopActiveService() {
   activeService = null;
 }
 
+function reconnectEnvironmentConnectionsAfterBrowserResume(reason: string): void {
+  const now = Date.now();
+  if (now - lastBrowserResumeReconnectAt < BROWSER_RESUME_RECONNECT_COOLDOWN_MS) {
+    return;
+  }
+  lastBrowserResumeReconnectAt = now;
+
+  for (const connection of environmentConnections.values()) {
+    void connection.reconnect().catch((error) => {
+      console.warn("Environment reconnect after browser resume failed", {
+        environmentId: connection.environmentId,
+        reason,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+  }
+}
+
+function subscribeBrowserResumeReconnects(): () => void {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    return NOOP;
+  }
+
+  const handleVisibilityChange = () => {
+    if (document.visibilityState === "hidden") {
+      lastBrowserHiddenAt = Date.now();
+      return;
+    }
+    if (document.visibilityState === "visible" && lastBrowserHiddenAt !== null) {
+      lastBrowserHiddenAt = null;
+      reconnectEnvironmentConnectionsAfterBrowserResume("visibilitychange");
+    }
+  };
+
+  const handlePageShow = (event: PageTransitionEvent) => {
+    if (event.persisted || lastBrowserHiddenAt !== null) {
+      lastBrowserHiddenAt = null;
+      reconnectEnvironmentConnectionsAfterBrowserResume("pageshow");
+    }
+  };
+
+  document.addEventListener("visibilitychange", handleVisibilityChange);
+  window.addEventListener("pageshow", handlePageShow);
+  return () => {
+    document.removeEventListener("visibilitychange", handleVisibilityChange);
+    window.removeEventListener("pageshow", handlePageShow);
+  };
+}
+
 export function subscribeEnvironmentConnections(listener: () => void): () => void {
   environmentConnectionListeners.add(listener);
   return () => {
@@ -1661,12 +1713,15 @@ export function startEnvironmentConnectionService(queryClient: QueryClient): ()
     .then(() => syncSavedEnvironmentConnections(listSavedEnvironmentRecords()))
     .catch(() => undefined);
 
+  const unsubscribeBrowserResumeReconnects = subscribeBrowserResumeReconnects();
+
   activeService = {
     queryClient,
     queryInvalidationThrottler,
     refCount: 1,
     stop: () => {
       unsubscribeSavedEnvironments();
+      unsubscribeBrowserResumeReconnects();
       queryInvalidationThrottler.cancel();
     },
   };
@@ -1684,6 +1739,8 @@ export function startEnvironmentConnectionService(queryClient: QueryClient): ()
 
 export async function resetEnvironmentServiceForTests(): Promise<void> {
   stopActiveService();
+  lastBrowserHiddenAt = null;
+  lastBrowserResumeReconnectAt = Number.NEGATIVE_INFINITY;
   lastAppliedProjectionVersionByEnvironment.clear();
   pendingSavedEnvironmentConnections.clear();
   for (const key of Array.from(threadDetailSubscriptions.keys())) {

From 36c263184e710c0b9db01116d72fe289f50be928 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 1 May 2026 16:46:12 -0700
Subject: [PATCH 68/74] Add RPC request and heartbeat tracking

- Show locked mobile run context as static text
- Wire request start/chunk/exit and ping/pong hooks
- Upgrade Effect to beta.59 with patch
---
 apps/web/src/components/BranchToolbar.tsx    |  41 +--
 apps/web/src/components/ChatView.browser.tsx |  25 ++
 apps/web/src/components/ChatView.tsx         |   8 +-
 apps/web/src/rpc/protocol.ts                 | 116 +++++++-
 apps/web/src/rpc/wsRpcClient.ts              |  42 ++-
 apps/web/src/rpc/wsTransport.ts              |  74 ++++-
 bun.lock                                     |  47 ++--
 package.json                                 |  19 +-
 patches/effect@4.0.0-beta.59.patch           | 277 +++++++++++++++++++
 9 files changed, 555 insertions(+), 94 deletions(-)
 create mode 100644 patches/effect@4.0.0-beta.59.patch

diff --git a/apps/web/src/components/BranchToolbar.tsx b/apps/web/src/components/BranchToolbar.tsx
index 48c1d89218b..8fca370c61f 100644
--- a/apps/web/src/components/BranchToolbar.tsx
+++ b/apps/web/src/components/BranchToolbar.tsx
@@ -20,7 +20,6 @@ import {
   resolveCurrentWorkspaceLabel,
   resolveEnvModeLabel,
   resolveEffectiveEnvMode,
-  resolveLockedWorkspaceLabel,
 } from "./BranchToolbar.logic";
 import { BranchToolbarBranchSelector } from "./BranchToolbarBranchSelector";
 import { BranchToolbarEnvironmentSelector } from "./BranchToolbarEnvironmentSelector";
@@ -80,19 +79,33 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({
     () => availableEnvironments?.find((env) => env.environmentId === environmentId) ?? null,
     [availableEnvironments, environmentId],
   );
-  const environmentLabel = activeEnvironment?.label ?? "Run on";
-  const EnvironmentIcon = activeEnvironment?.isPrimary ? MonitorIcon : CloudIcon;
   const WorkspaceIcon =
     effectiveEnvMode === "worktree"
       ? FolderGit2Icon
       : activeWorktreePath
         ? FolderGitIcon
         : FolderIcon;
-  const workspaceLabel = envModeLocked
-    ? resolveLockedWorkspaceLabel(activeWorktreePath)
-    : effectiveEnvMode === "worktree"
-      ? resolveEnvModeLabel("worktree")
-      : resolveCurrentWorkspaceLabel(activeWorktreePath);
+  const isLocked = envLocked || envModeLocked;
+  const icon = (
+    <span className="relative size-3 shrink-0" aria-hidden="true">
+      <CloudIcon className="absolute inset-0 size-3" style={{ clipPath: "inset(0 50% 0 0)" }} />
+      <WorkspaceIcon className="absolute inset-0 size-3" style={{ clipPath: "inset(0 0 0 50%)" }} />
+    </span>
+  );
+  const triggerContent = (
+    <>
+      {icon}
+      <span className="min-w-0 truncate">{activeEnvironment?.label ?? "Run on"}</span>
+    </>
+  );
+
+  if (isLocked) {
+    return (
+      <span className="inline-flex min-w-0 max-w-[48%] flex-1 items-center justify-start gap-1 rounded-md border border-transparent px-[calc(--spacing(2)-1px)] text-sm font-medium text-muted-foreground/70 md:hidden">
+        {triggerContent}
+      </span>
+    );
+  }
 
   return (
     <Menu>
@@ -100,17 +113,7 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({
         render={<Button variant="ghost" size="xs" />}
         className="min-w-0 max-w-[48%] flex-1 justify-start text-muted-foreground/70 hover:text-foreground/80 md:hidden"
       >
-        {showEnvironmentPicker ? (
-          <>
-            <EnvironmentIcon className="size-3 shrink-0" />
-            <span className="min-w-0 truncate">{environmentLabel}</span>
-          </>
-        ) : (
-          <>
-            <WorkspaceIcon className="size-3 shrink-0" />
-            <span className="min-w-0 truncate">{workspaceLabel}</span>
-          </>
-        )}
+        {triggerContent}
         <ChevronDownIcon className="size-3 shrink-0 opacity-50" />
       </MenuTrigger>
       <MenuPopup align="start" side="top" className="w-64">
diff --git a/apps/web/src/components/ChatView.browser.tsx b/apps/web/src/components/ChatView.browser.tsx
index 2a1edb91813..1b8388e466d 100644
--- a/apps/web/src/components/ChatView.browser.tsx
+++ b/apps/web/src/components/ChatView.browser.tsx
@@ -1662,6 +1662,31 @@ describe("ChatView timeline estimator parity (full app)", () => {
     customWsRpcResolver = null;
     document.body.innerHTML = "";
   });
+
+  it("renders locked mobile run context as a static environment label", async () => {
+    const mounted = await mountChatView({
+      viewport: COMPACT_FOOTER_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-mobile-locked-workspace" as MessageId,
+        targetText: "locked mobile workspace",
+      }),
+    });
+
+    try {
+      await waitForElement(
+        () =>
+          Array.from(document.querySelectorAll<HTMLElement>("span")).find(
+            (element) => element.textContent?.trim() === "This device",
+          ) ?? null,
+        "Unable to find static mobile environment label.",
+      );
+
+      expect(findButtonByText("This device")).toBeNull();
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
   it("re-expands the bootstrap project using its logical key", async () => {
     useUiStateStore.setState({
       projectExpandedById: {
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 0760c356cbe..9ef221e262a 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -3695,12 +3695,8 @@ export default function ChatView(props: ChatViewProps) {
                 {...(canCheckoutPullRequestIntoThread
                   ? { onCheckoutPullRequestRequest: openPullRequestDialog }
                   : {})}
-                {...(hasMultipleEnvironments
-                  ? {
-                      availableEnvironments: logicalProjectEnvironments,
-                      onEnvironmentChange,
-                    }
-                  : {})}
+                {...(hasMultipleEnvironments ? { onEnvironmentChange } : {})}
+                availableEnvironments={logicalProjectEnvironments}
               />
             )}
           </div>
diff --git a/apps/web/src/rpc/protocol.ts b/apps/web/src/rpc/protocol.ts
index 28a6a29288b..3c52764a0aa 100644
--- a/apps/web/src/rpc/protocol.ts
+++ b/apps/web/src/rpc/protocol.ts
@@ -29,6 +29,25 @@ export interface WsProtocolLifecycleHandlers {
   readonly isActive?: () => boolean;
   readonly onAttempt?: (socketUrl: string) => void;
   readonly onOpen?: () => void;
+  readonly onHeartbeatPing?: () => void;
+  readonly onHeartbeatPong?: () => void;
+  readonly onHeartbeatTimeout?: () => void;
+  readonly onRequestStart?: (info: {
+    readonly id: string;
+    readonly tag: string;
+    readonly stream: boolean;
+  }) => void;
+  readonly onRequestChunk?: (info: {
+    readonly id: string;
+    readonly tag: string;
+    readonly chunkCount: number;
+  }) => void;
+  readonly onRequestExit?: (info: {
+    readonly id: string;
+    readonly tag: string;
+    readonly stream: boolean;
+  }) => void;
+  readonly onRequestInterrupt?: (info: { readonly id: string; readonly tag?: string }) => void;
   readonly onError?: (message: string) => void;
   readonly onClose?: (
     details: { readonly code: number; readonly reason: string },
@@ -208,22 +227,99 @@ export function createWsRpcProtocolLayer(
         ...protocol,
         run: (clientId, writeResponse) =>
           protocol.run(clientId, (response) => {
-            if (response._tag === "Chunk" || response._tag === "Exit") {
-              acknowledgeRpcRequest(response.requestId);
-            } else if (response._tag === "ClientProtocolError" || response._tag === "Defect") {
+            if (response._tag === "ClientProtocolError" || response._tag === "Defect") {
               clearAllTrackedRpcRequests();
             }
             return writeResponse(response);
           }),
-        send: (clientId, request, transferables) => {
-          if (request._tag === "Request") {
-            trackRpcRequestSent(request.id, request.tag);
-          }
-          return protocol.send(clientId, request, transferables);
-        },
       }),
     ),
   );
+  const requestHooksLayer = Layer.succeed(
+    RpcClient.RequestHooks,
+    RpcClient.RequestHooks.of({
+      onRequestStart: (info) =>
+        Effect.sync(() => {
+          if (!lifecycle.isActive()) {
+            return;
+          }
+          handlers?.onRequestStart?.({
+            id: String(info.id),
+            tag: info.tag,
+            stream: info.stream,
+          });
+          trackRpcRequestSent(String(info.id), info.tag);
+        }),
+      onRequestChunk: (info) =>
+        Effect.sync(() => {
+          if (!lifecycle.isActive()) {
+            return;
+          }
+          handlers?.onRequestChunk?.({
+            id: String(info.id),
+            tag: info.tag,
+            chunkCount: info.chunkCount,
+          });
+          acknowledgeRpcRequest(String(info.id));
+        }),
+      onRequestExit: (info) =>
+        Effect.sync(() => {
+          if (!lifecycle.isActive()) {
+            return;
+          }
+          handlers?.onRequestExit?.({
+            id: String(info.id),
+            tag: info.tag,
+            stream: info.stream,
+          });
+          acknowledgeRpcRequest(String(info.id));
+        }),
+      onRequestInterrupt: (info) =>
+        Effect.sync(() => {
+          if (!lifecycle.isActive()) {
+            return;
+          }
+          handlers?.onRequestInterrupt?.({
+            id: String(info.id),
+            ...(info.tag === undefined ? {} : { tag: info.tag }),
+          });
+          acknowledgeRpcRequest(String(info.id));
+        }),
+    }),
+  );
+  const connectionHooksLayer = Layer.succeed(
+    RpcClient.ConnectionHooks,
+    RpcClient.ConnectionHooks.of({
+      onConnect: Effect.void,
+      onDisconnect: Effect.void,
+      onPing: Effect.sync(() => {
+        if (lifecycle.isActive()) {
+          handlers?.onHeartbeatPing?.();
+        }
+      }),
+      onPong: Effect.sync(() => {
+        if (lifecycle.isActive()) {
+          handlers?.onHeartbeatPong?.();
+        }
+      }),
+      onPingTimeout: Effect.sync(() => {
+        if (lifecycle.isActive()) {
+          clearAllTrackedRpcRequests();
+          recordWsConnectionErrored(
+            "WebSocket heartbeat timed out.",
+            resolveConnectionMetadata(handlers),
+          );
+          handlers?.onHeartbeatTimeout?.();
+        }
+      }),
+    }),
+  );
 
-  return protocolLayer.pipe(Layer.provide(Layer.mergeAll(socketLayer, RpcSerialization.layerJson)));
+  return Layer.mergeAll(
+    protocolLayer.pipe(
+      Layer.provide(Layer.mergeAll(socketLayer, RpcSerialization.layerJson, connectionHooksLayer)),
+    ),
+    requestHooksLayer,
+    connectionHooksLayer,
+  );
 }
diff --git a/apps/web/src/rpc/wsRpcClient.ts b/apps/web/src/rpc/wsRpcClient.ts
index 39abcb2c09c..1efcb101aab 100644
--- a/apps/web/src/rpc/wsRpcClient.ts
+++ b/apps/web/src/rpc/wsRpcClient.ts
@@ -150,11 +150,10 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
       restart: (input) => transport.request((client) => client[WS_METHODS.terminalRestart](input)),
       close: (input) => transport.request((client) => client[WS_METHODS.terminalClose](input)),
       onEvent: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeTerminalEvents]({}),
-          listener,
-          options,
-        ),
+        transport.subscribe((client) => client[WS_METHODS.subscribeTerminalEvents]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeTerminalEvents,
+        }),
     },
     projects: {
       searchEntries: (input) =>
@@ -181,7 +180,7 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
             current = applyGitStatusStreamEvent(current, event);
             listener(current);
           },
-          options,
+          { ...options, tag: WS_METHODS.subscribeGitStatus },
         );
       },
       listRefs: (input) => transport.request((client) => client[WS_METHODS.vcsListRefs](input)),
@@ -230,23 +229,20 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
       discoverSourceControl: () =>
         transport.request((client) => client[WS_METHODS.serverDiscoverSourceControl]({})),
       subscribeConfig: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeServerConfig]({}),
-          listener,
-          options,
-        ),
+        transport.subscribe((client) => client[WS_METHODS.subscribeServerConfig]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeServerConfig,
+        }),
       subscribeLifecycle: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeServerLifecycle]({}),
-          listener,
-          options,
-        ),
+        transport.subscribe((client) => client[WS_METHODS.subscribeServerLifecycle]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeServerLifecycle,
+        }),
       subscribeAuthAccess: (listener, options) =>
-        transport.subscribe(
-          (client) => client[WS_METHODS.subscribeAuthAccess]({}),
-          listener,
-          options,
-        ),
+        transport.subscribe((client) => client[WS_METHODS.subscribeAuthAccess]({}), listener, {
+          ...options,
+          tag: WS_METHODS.subscribeAuthAccess,
+        }),
     },
     orchestration: {
       dispatchCommand: (input) =>
@@ -259,13 +255,13 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
         transport.subscribe(
           (client) => client[ORCHESTRATION_WS_METHODS.subscribeShell]({}),
           listener,
-          options,
+          { ...options, tag: ORCHESTRATION_WS_METHODS.subscribeShell },
         ),
       subscribeThread: (input, listener, options) =>
         transport.subscribe(
           (client) => client[ORCHESTRATION_WS_METHODS.subscribeThread](input),
           listener,
-          options,
+          { ...options, tag: ORCHESTRATION_WS_METHODS.subscribeThread },
         ),
     },
   };
diff --git a/apps/web/src/rpc/wsTransport.ts b/apps/web/src/rpc/wsTransport.ts
index 6d89be6afa5..ebdac483ac8 100644
--- a/apps/web/src/rpc/wsTransport.ts
+++ b/apps/web/src/rpc/wsTransport.ts
@@ -25,6 +25,7 @@ import { isTransportConnectionErrorMessage } from "./transportError";
 interface SubscribeOptions {
   readonly retryDelay?: Duration.Input;
   readonly onResubscribe?: () => void;
+  readonly tag?: string;
 }
 
 interface RequestOptions {
@@ -40,6 +41,12 @@ interface TransportSession {
   readonly runtime: ManagedRuntime.ManagedRuntime<RpcClient.Protocol, never>;
 }
 
+interface StreamRequestStartInfo {
+  readonly id: string;
+  readonly tag: string;
+  readonly stream: boolean;
+}
+
 function formatErrorMessage(error: unknown): string {
   if (error instanceof Error && error.message.trim().length > 0) {
     return error.message;
@@ -57,6 +64,8 @@ export class WsTransport {
   private nextSessionId = 0;
   private activeSessionId = 0;
   private session: TransportSession;
+  private lastHeartbeatPongAt = 0;
+  private readonly streamRequestStartListeners = new Set<(info: StreamRequestStartInfo) => void>();
 
   constructor(
     url: WsRpcProtocolSocketUrlProvider,
@@ -127,18 +136,24 @@ export class WsTransport {
 
         const session = this.session;
         try {
-          if (hasReceivedValue) {
-            try {
-              options?.onResubscribe?.();
-            } catch {
-              // Swallow reconnect hook errors so the stream can recover.
-            }
-          }
-
           const runningStream = this.runStreamOnSession(
             session,
             connect,
             listener,
+            {
+              ...(options?.tag === undefined ? {} : { tag: options.tag }),
+              ...(hasReceivedValue
+                ? {
+                    onStarted: () => {
+                      try {
+                        options?.onResubscribe?.();
+                      } catch {
+                        // Swallow reconnect hook errors so the stream can recover.
+                      }
+                    },
+                  }
+                : {}),
+            },
             () => active,
             () => {
               this.hasReportedTransportDisconnect = false;
@@ -194,6 +209,7 @@ export class WsTransport {
       }
 
       clearAllTrackedRpcRequests();
+      this.lastHeartbeatPongAt = 0;
       const previousSession = this.session;
       this.session = this.createSession();
       await this.closeSession(previousSession);
@@ -203,6 +219,10 @@ export class WsTransport {
     await reconnectOperation;
   }
 
+  isHeartbeatFresh(maxAgeMs = 15_000): boolean {
+    return this.lastHeartbeatPongAt > 0 && Date.now() - this.lastHeartbeatPongAt <= maxAgeMs;
+  }
+
   async dispose() {
     if (this.disposed) {
       return;
@@ -232,6 +252,19 @@ export class WsTransport {
             this.disposed ||
             this.intentionalCloseDepth > 0 ||
             this.lifecycleHandlers?.isCloseIntentional?.() === true,
+          onHeartbeatPong: () => {
+            this.lastHeartbeatPongAt = Date.now();
+            this.lifecycleHandlers?.onHeartbeatPong?.();
+          },
+          onRequestStart: (info) => {
+            this.lifecycleHandlers?.onRequestStart?.(info);
+            if (!info.stream) {
+              return;
+            }
+            for (const listener of this.streamRequestStartListeners) {
+              listener(info);
+            }
+          },
         }),
         ClientTracingLive,
       ),
@@ -248,6 +281,10 @@ export class WsTransport {
     session: TransportSession,
     connect: (client: WsRpcProtocolClient) => Stream.Stream<TValue, Error, never>,
     listener: (value: TValue) => void,
+    requestStart: {
+      readonly tag?: string;
+      readonly onStarted?: () => void;
+    },
     isActive: () => boolean,
     markValueReceived: () => void,
   ): {
@@ -260,6 +297,23 @@ export class WsTransport {
       resolveCompleted = resolve;
       rejectCompleted = reject;
     });
+    let requestStartListener: ((info: StreamRequestStartInfo) => void) | null = null;
+    if (requestStart.onStarted) {
+      requestStartListener = (info) => {
+        if (!isActive() || !info.stream) {
+          return;
+        }
+        if (requestStart.tag !== undefined && info.tag !== requestStart.tag) {
+          return;
+        }
+        requestStart.onStarted?.();
+        if (requestStartListener) {
+          this.streamRequestStartListeners.delete(requestStartListener);
+          requestStartListener = null;
+        }
+      };
+      this.streamRequestStartListeners.add(requestStartListener);
+    }
     const cancel = session.runtime.runCallback(
       Effect.promise(() => session.clientPromise).pipe(
         Effect.flatMap((client) =>
@@ -281,6 +335,10 @@ export class WsTransport {
       ),
       {
         onExit: (exit) => {
+          if (requestStartListener) {
+            this.streamRequestStartListeners.delete(requestStartListener);
+            requestStartListener = null;
+          }
           if (Exit.isSuccess(exit)) {
             resolveCompleted();
             return;
diff --git a/bun.lock b/bun.lock
index 899b275bbf5..ffbbc6ebe65 100644
--- a/bun.lock
+++ b/bun.lock
@@ -257,6 +257,9 @@
     "electron",
     "node-pty",
   ],
+  "patchedDependencies": {
+    "effect@4.0.0-beta.59": "patches/effect@4.0.0-beta.59.patch",
+  },
   "overrides": {
     "@effect/atom-react": "catalog:",
     "@effect/platform-bun": "catalog:",
@@ -268,17 +271,17 @@
     "vite": "^8.0.0",
   },
   "catalog": {
-    "@effect/atom-react": "4.0.0-beta.45",
+    "@effect/atom-react": "4.0.0-beta.59",
     "@effect/language-service": "0.84.2",
-    "@effect/openapi-generator": "4.0.0-beta.45",
-    "@effect/platform-bun": "4.0.0-beta.45",
-    "@effect/platform-node": "4.0.0-beta.45",
-    "@effect/platform-node-shared": "4.0.0-beta.45",
-    "@effect/sql-sqlite-bun": "4.0.0-beta.45",
-    "@effect/vitest": "4.0.0-beta.45",
+    "@effect/openapi-generator": "4.0.0-beta.59",
+    "@effect/platform-bun": "4.0.0-beta.59",
+    "@effect/platform-node": "4.0.0-beta.59",
+    "@effect/platform-node-shared": "4.0.0-beta.59",
+    "@effect/sql-sqlite-bun": "4.0.0-beta.59",
+    "@effect/vitest": "4.0.0-beta.59",
     "@types/bun": "^1.3.11",
     "@types/node": "^24.10.13",
-    "effect": "4.0.0-beta.45",
+    "effect": "4.0.0-beta.59",
     "tsdown": "^0.20.3",
     "typescript": "^5.7.3",
     "vitest": "^4.0.0",
@@ -366,21 +369,21 @@
 
     "@dnd-kit/utilities": ["@dnd-kit/utilities@3.2.2", "", { "dependencies": { "tslib": "^2.0.0" }, "peerDependencies": { "react": ">=16.8.0" } }, "sha512-+MKAJEOfaBe5SmV6t34p80MMKhjvUz0vRrvVJbPT0WElzaOJ/1xs+D+KDv+tD/NE5ujfrChEcshd4fLn0wpiqg=="],
 
-    "@effect/atom-react": ["@effect/atom-react@4.0.0-beta.45", "", { "peerDependencies": { "effect": "^4.0.0-beta.45", "react": "^19.2.4", "scheduler": "*" } }, "sha512-jCoiae9UNeis9Yoal1p5V/P4eJK9nX89wORom7X5LpR2Ok920SZJc8dIeYkRXRAp9BCYJ/yWcO8gGLf7do71vg=="],
+    "@effect/atom-react": ["@effect/atom-react@4.0.0-beta.59", "", { "peerDependencies": { "effect": "^4.0.0-beta.59", "react": "^19.2.4", "scheduler": "*" } }, "sha512-VkznQz5c+Z/BLxX+hQNPzPOyUnLQjnbppFSNP7tbPru7HKR4ihzCDC6Xjbx87156MOrZ+JOa6shTMbmvGT5W0w=="],
 
     "@effect/language-service": ["@effect/language-service@0.84.2", "", { "bin": { "effect-language-service": "cli.js" } }, "sha512-l04qNxpiA8rY5yXWckRPJ7Mk5MNerXuNymSFf+IdflfI5i8jgL1bpBNLuP6ijg7wgjdHc/KmTnCj2kT0SCntuA=="],
 
-    "@effect/openapi-generator": ["@effect/openapi-generator@4.0.0-beta.45", "", { "peerDependencies": { "@effect/platform-node": "^4.0.0-beta.45", "effect": "^4.0.0-beta.45" }, "bin": { "openapigen": "dist/bin.js" } }, "sha512-zT1UPzapV6mZebMuYhoDPQj/FKNn4R+oDgz1hEcQwazal4+lVDyEYGhRl0PgZroy6CP78fAOWNgW7TriGqSlOQ=="],
+    "@effect/openapi-generator": ["@effect/openapi-generator@4.0.0-beta.59", "", { "peerDependencies": { "@effect/platform-node": "^4.0.0-beta.59", "effect": "^4.0.0-beta.59" }, "bin": { "openapigen": "dist/bin.js" } }, "sha512-y1KF6mEb3pA5AdQsNGeWxV42Xi1uBt9Wzo5xMsp06j/WkOM2vWFmvSXw6xvwINAUi1HVjdOLo3xnTXtSv9YdRg=="],
 
-    "@effect/platform-bun": ["@effect/platform-bun@4.0.0-beta.45", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.45" }, "peerDependencies": { "effect": "^4.0.0-beta.45" } }, "sha512-dZsbkJ+o4JfKE1OIAlMq8YWhmEfXxtTYennYADK/M/XlOtkFLsc2jkZppDvMznVni6JpFxWc7wd5rUf8jBVP5g=="],
+    "@effect/platform-bun": ["@effect/platform-bun@4.0.0-beta.59", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.59" }, "peerDependencies": { "effect": "^4.0.0-beta.59" } }, "sha512-1jXCIx34X80ojiK9ACO9Q7RST9CXudRmlAbsP4kPqjUo6aqOuGSWXq9ueBO4LbaIZiioRxtTciom35U9ldfTkQ=="],
 
-    "@effect/platform-node": ["@effect/platform-node@4.0.0-beta.45", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.45", "mime": "^4.1.0", "undici": "^7.24.0" }, "peerDependencies": { "effect": "^4.0.0-beta.45", "ioredis": "^5.7.0" } }, "sha512-P07NMG4eoy62iLX9szak0hkr7hrwgq5+XMkm7URVug/3zqfZVxEG2kxn9JzVK1lF5WbaVrEKwjt3IkEJxzSPtg=="],
+    "@effect/platform-node": ["@effect/platform-node@4.0.0-beta.59", "", { "dependencies": { "@effect/platform-node-shared": "^4.0.0-beta.59", "mime": "^4.1.0", "undici": "^8.0.2" }, "peerDependencies": { "effect": "^4.0.0-beta.59", "ioredis": "^5.7.0" } }, "sha512-jHRW0l953FjYNhQHexr48jFiBu5iGEZH5nmKD6Ha+lPtm1MrKG2V4njfWA3Fv0nUmd3VN87eBJ557wU0twN1Hg=="],
 
-    "@effect/platform-node-shared": ["@effect/platform-node-shared@4.0.0-beta.45", "", { "dependencies": { "@types/ws": "^8.18.1", "ws": "^8.19.0" }, "peerDependencies": { "effect": "^4.0.0-beta.45" } }, "sha512-0T4RG18o+aCVUSlmPxA7uAjHJkyE3MS/uRrR5kCNSZQNG3X71wdIbu82wE/MnV6+6YSSPDx/6TVdZWYkJF0JWw=="],
+    "@effect/platform-node-shared": ["@effect/platform-node-shared@4.0.0-beta.59", "", { "dependencies": { "@types/ws": "^8.18.1", "ws": "^8.20.0" }, "peerDependencies": { "effect": "^4.0.0-beta.59" } }, "sha512-fGwFJuG0Te9U/ZeqeDZ2HcSKZBhX5wLjX2/Rxb5+yaOkvvFAN9MvIh05R0QQK5DCcERvnbhHSl1CjSIAN4aEwQ=="],
 
-    "@effect/sql-sqlite-bun": ["@effect/sql-sqlite-bun@4.0.0-beta.45", "", { "peerDependencies": { "effect": "^4.0.0-beta.45" } }, "sha512-sJBBztwI4YxjdjhdyjWelh3KKoZucmmZS2ONeNDIzYgqFlsrwEEUrhVkWf5ch9Io+kUUzeb6q7/SedFoLUWO7g=="],
+    "@effect/sql-sqlite-bun": ["@effect/sql-sqlite-bun@4.0.0-beta.59", "", { "peerDependencies": { "effect": "^4.0.0-beta.59" } }, "sha512-qZWt2HeLgSY8ygEfwbldK9lJ5xg/WP4lgCp1VLlyE8BImSB5g1h+UbhitXr+pOIf+ry4Xmc4ycp7YwTBOFH5/A=="],
 
-    "@effect/vitest": ["@effect/vitest@4.0.0-beta.45", "", { "peerDependencies": { "effect": "^4.0.0-beta.45", "vitest": "^3.0.0 || ^4.0.0" } }, "sha512-38JA5Z6c2FoEhpVKbl7rjTrMU8Al5T30Kwtb6N3B9kOkyr2SsmvNsP9T65bh03IBh3ak9U//acrkmjS3hLQwKA=="],
+    "@effect/vitest": ["@effect/vitest@4.0.0-beta.59", "", { "peerDependencies": { "effect": "^4.0.0-beta.59", "vitest": "^3.0.0 || ^4.0.0" } }, "sha512-jhpJbpDs1ED58SmFzcfmqLXxle84fiexaMEhV8SBl8WC2GM3FT5DW0WJYFjbZIH5/735brp3iGdjY5/uAxS7Bg=="],
 
     "@electron/get": ["@electron/get@2.0.3", "", { "dependencies": { "debug": "^4.1.1", "env-paths": "^2.2.0", "fs-extra": "^8.1.0", "got": "^11.8.5", "progress": "^2.0.3", "semver": "^6.2.0", "sumchecker": "^3.0.1" }, "optionalDependencies": { "global-agent": "^3.0.0" } }, "sha512-Qkzpg2s9GnVV2I2BjRksUi43U5e6+zaQMcjoJy0C+C5oxaKl+fmckGDQFtRpZpZV0NQekuZZ+tGz7EA9TVnQtQ=="],
 
@@ -1138,7 +1141,7 @@
 
     "ee-first": ["ee-first@1.1.1", "", {}, "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow=="],
 
-    "effect": ["effect@4.0.0-beta.45", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.5.3", "find-my-way-ts": "^0.1.6", "ini": "^6.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^1.11.8", "multipasta": "^0.2.7", "toml": "^3.0.0", "uuid": "^13.0.0", "yaml": "^2.8.2" } }, "sha512-vvNrUWqnzBIW1hRMa+zw0CLRW6HLgdu7hQ6K7PT/rS+UY/73Ma11O+Oi9oc9zwL8KcN37M47UDseAdlF0bGNWw=="],
+    "effect": ["effect@4.0.0-beta.59", "", { "dependencies": { "@standard-schema/spec": "^1.1.0", "fast-check": "^4.6.0", "find-my-way-ts": "^0.1.6", "ini": "^6.0.0", "kubernetes-types": "^1.30.0", "msgpackr": "^1.11.9", "multipasta": "^0.2.7", "toml": "^4.1.1", "uuid": "^13.0.0", "yaml": "^2.8.3" } }, "sha512-xyUDLeHSe8d6lWGOvR6Fgn2HL6gYeTZ/S4Jzk9uc4ZUxMPPsNZlNXrvk0C7/utQFzeX7uAWcVnG2BjbA0SRoAA=="],
 
     "effect-acp": ["effect-acp@workspace:packages/effect-acp"],
 
@@ -1896,7 +1899,7 @@
 
     "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
 
-    "toml": ["toml@3.0.0", "", {}, "sha512-y/mWCZinnvxjTKYhJ+pYxwD0mRLVvOtdS2Awbgxln6iEnt4rk0yBxeSBHkGJcPucRiG0e55mwWp+g/05rsrd6w=="],
+    "toml": ["toml@4.1.1", "", {}, "sha512-EBJnVBr3dTXdA89WVFoAIPUqkBjxPMwRqsfuo1r240tKFHXv3zgca4+NJib/h6TyvGF7vOawz0jGuryJCdNHrw=="],
 
     "totalist": ["totalist@3.0.1", "", {}, "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ=="],
 
@@ -1950,7 +1953,7 @@
 
     "uncrypto": ["uncrypto@0.1.3", "", {}, "sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q=="],
 
-    "undici": ["undici@7.24.4", "", {}, "sha512-BM/JzwwaRXxrLdElV2Uo6cTLEjhSb3WXboncJamZ15NgUURmvlXvxa6xkwIOILIjPNo9i8ku136ZvWV0Uly8+w=="],
+    "undici": ["undici@8.2.0", "", {}, "sha512-Z+4Hx9GE26Lh9Upwfnc8C7SsrpBPGaM/Gm6kMFtiG7c+5IvQKlXi/t+9x9DrrCh29cww5TSP9YdVaBcnLDs5fQ=="],
 
     "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
 
@@ -2058,7 +2061,7 @@
 
     "wrappy": ["wrappy@1.0.2", "", {}, "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="],
 
-    "ws": ["ws@8.19.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg=="],
+    "ws": ["ws@8.20.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA=="],
 
     "wsl-utils": ["wsl-utils@0.1.0", "", { "dependencies": { "is-wsl": "^3.1.0" } }, "sha512-h3Fbisa2nKGPxCpm89Hk33lBLsnaGBvctQopaBSOW/uIs6FTe1ATyAnKFJrzVs9vpGdsTe73WF3V4lIsk4Gacw=="],
 
@@ -2068,7 +2071,7 @@
 
     "yallist": ["yallist@3.1.1", "", {}, "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g=="],
 
-    "yaml": ["yaml@2.8.2", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A=="],
+    "yaml": ["yaml@2.8.3", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg=="],
 
     "yaml-language-server": ["yaml-language-server@1.20.0", "", { "dependencies": { "@vscode/l10n": "^0.0.18", "ajv": "^8.17.1", "ajv-draft-04": "^1.0.0", "prettier": "^3.5.0", "request-light": "^0.5.7", "vscode-json-languageservice": "4.1.8", "vscode-languageserver": "^9.0.0", "vscode-languageserver-textdocument": "^1.0.1", "vscode-languageserver-types": "^3.16.0", "vscode-uri": "^3.0.2", "yaml": "2.7.1" }, "bin": { "yaml-language-server": "bin/yaml-language-server" } }, "sha512-qhjK/bzSRZ6HtTvgeFvjNPJGWdZ0+x5NREV/9XZWFjIGezew2b4r5JPy66IfOhd5OA7KeFwk1JfmEbnTvev0cA=="],
 
@@ -2094,6 +2097,8 @@
 
     "@astrojs/language-server/@astrojs/compiler": ["@astrojs/compiler@2.13.1", "", {}, "sha512-f3FN83d2G/v32ipNClRKgYv30onQlMZX1vCeZMjPsMMPl1mDpmbl0+N5BYo4S/ofzqJyS5hvwacEo0CCVDn/Qg=="],
 
+    "@astrojs/yaml2ts/yaml": ["yaml@2.8.2", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A=="],
+
     "@babel/code-frame/@babel/helper-validator-identifier": ["@babel/helper-validator-identifier@7.28.5", "", {}, "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q=="],
 
     "@babel/core/@babel/generator": ["@babel/generator@7.29.1", "", { "dependencies": { "@babel/parser": "^7.29.0", "@babel/types": "^7.29.0", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" } }, "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw=="],
@@ -2158,6 +2163,8 @@
 
     "@tanstack/router-utils/@babel/generator": ["@babel/generator@7.29.1", "", { "dependencies": { "@babel/parser": "^7.29.0", "@babel/types": "^7.29.0", "@jridgewell/gen-mapping": "^0.3.12", "@jridgewell/trace-mapping": "^0.3.28", "jsesc": "^3.0.2" } }, "sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw=="],
 
+    "@vitest/browser/ws": ["ws@8.19.0", "", { "peerDependencies": { "bufferutil": "^4.0.1", "utf-8-validate": ">=5.0.2" }, "optionalPeers": ["bufferutil", "utf-8-validate"] }, "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg=="],
+
     "anymatch/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
 
     "ast-kit/@babel/parser": ["@babel/parser@8.0.0-rc.2", "", { "dependencies": { "@babel/types": "^8.0.0-rc.2" }, "bin": "./bin/babel-parser.js" }, "sha512-29AhEtcq4x8Dp3T72qvUMZHx0OMXCj4Jy/TEReQa+KWLln524Cj1fWb3QFi0l/xSpptQBR6y9RNEXuxpFvwiUQ=="],
diff --git a/package.json b/package.json
index 5ed5a808610..2d3b090ad7b 100644
--- a/package.json
+++ b/package.json
@@ -8,14 +8,14 @@
       "scripts"
     ],
     "catalog": {
-      "effect": "4.0.0-beta.45",
-      "@effect/atom-react": "4.0.0-beta.45",
-      "@effect/openapi-generator": "4.0.0-beta.45",
-      "@effect/platform-bun": "4.0.0-beta.45",
-      "@effect/platform-node": "4.0.0-beta.45",
-      "@effect/platform-node-shared": "4.0.0-beta.45",
-      "@effect/sql-sqlite-bun": "4.0.0-beta.45",
-      "@effect/vitest": "4.0.0-beta.45",
+      "effect": "4.0.0-beta.59",
+      "@effect/atom-react": "4.0.0-beta.59",
+      "@effect/openapi-generator": "4.0.0-beta.59",
+      "@effect/platform-bun": "4.0.0-beta.59",
+      "@effect/platform-node": "4.0.0-beta.59",
+      "@effect/platform-node-shared": "4.0.0-beta.59",
+      "@effect/sql-sqlite-bun": "4.0.0-beta.59",
+      "@effect/vitest": "4.0.0-beta.59",
       "@effect/language-service": "0.84.2",
       "@types/bun": "^1.3.11",
       "@types/node": "^24.10.13",
@@ -84,6 +84,9 @@
       "apps/web/public"
     ]
   },
+  "patchedDependencies": {
+    "effect@4.0.0-beta.59": "patches/effect@4.0.0-beta.59.patch"
+  },
   "trustedDependencies": [
     "node-pty",
     "electron"
diff --git a/patches/effect@4.0.0-beta.59.patch b/patches/effect@4.0.0-beta.59.patch
new file mode 100644
index 00000000000..479004acf33
--- /dev/null
+++ b/patches/effect@4.0.0-beta.59.patch
@@ -0,0 +1,277 @@
+diff --git a/dist/unstable/rpc/RpcClient.d.ts b/dist/unstable/rpc/RpcClient.d.ts
+index 7c5970042df67a25b4145df017960b3e6febed9c..7af3374632d53ad59f24e80835aa6741853b1f2b 100644
+--- a/dist/unstable/rpc/RpcClient.d.ts
++++ b/dist/unstable/rpc/RpcClient.d.ts
+@@ -2,6 +2,7 @@ import * as Cause from "../../Cause.ts";
+ import * as Context from "../../Context.ts";
+ import type * as Duration from "../../Duration.ts";
+ import * as Effect from "../../Effect.ts";
++import * as Exit from "../../Exit.ts";
+ import * as Layer from "../../Layer.ts";
+ import * as Queue from "../../Queue.ts";
+ import * as Schedule from "../../Schedule.ts";
+@@ -192,9 +193,40 @@ export declare const layerProtocolWorker: (options: {
+     readonly targetUtilization?: number | undefined;
+     readonly timeToLive: Duration.Input;
+ }) => Layer.Layer<Protocol, WorkerError, Worker.WorkerPlatform | Worker.Spawner>;
++declare const RequestHooks_base: Context.ServiceClass<RequestHooks, "effect/rpc/RpcClient/RequestHooks", {
++    readonly onRequestStart?: ((info: {
++        readonly id: RequestId;
++        readonly tag: string;
++        readonly stream: boolean;
++    }) => Effect.Effect<void>) | undefined;
++    readonly onRequestChunk?: ((info: {
++        readonly id: RequestId;
++        readonly tag: string;
++        readonly chunkCount: number;
++    }) => Effect.Effect<void>) | undefined;
++    readonly onRequestExit?: ((info: {
++        readonly id: RequestId;
++        readonly tag: string;
++        readonly stream: boolean;
++        readonly exit: Exit.Exit<unknown, unknown>;
++    }) => Effect.Effect<void>) | undefined;
++    readonly onRequestInterrupt?: ((info: {
++        readonly id: RequestId;
++        readonly tag?: string | undefined;
++    }) => Effect.Effect<void>) | undefined;
++}>;
++/**
++ * @since 4.0.0
++ * @category RequestHooks
++ */
++export declare class RequestHooks extends RequestHooks_base {
++}
+ declare const ConnectionHooks_base: Context.ServiceClass<ConnectionHooks, "effect/rpc/RpcClient/ConnectionHooks", {
+     readonly onConnect: Effect.Effect<void>;
+     readonly onDisconnect: Effect.Effect<void>;
++    readonly onPing?: Effect.Effect<void> | undefined;
++    readonly onPong?: Effect.Effect<void> | undefined;
++    readonly onPingTimeout?: Effect.Effect<void> | undefined;
+ }>;
+ /**
+  * @since 4.0.0
+diff --git a/dist/unstable/rpc/RpcClient.js b/dist/unstable/rpc/RpcClient.js
+index 951dfc2d667a9136cfa714dcd3195e6575917fde..599c0345873bedd72bc93afe80eab0c676319421 100644
+--- a/dist/unstable/rpc/RpcClient.js
++++ b/dist/unstable/rpc/RpcClient.js
+@@ -42,6 +42,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+   const services = yield* Effect.context();
+   const scope = Context.get(services, Scope.Scope);
+   const entries = new Map();
++  const hooks = yield* Effect.serviceOption(RequestHooks);
+   let isShutdown = false;
+   yield* Scope.addFinalizer(scope, Effect.withFiber(parent => {
+     isShutdown = true;
+@@ -79,6 +80,11 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+       return Effect.interrupt;
+     }
+     const id = generateRequestId();
++    const onStart = Option.isSome(hooks) && hooks.value.onRequestStart ? hooks.value.onRequestStart({
++      id,
++      tag: rpc._tag,
++      stream: false
++    }) : Effect.void;
+     const send = middleware(message => options.onFromClient({
+       message,
+       context,
+@@ -96,7 +102,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+       headers: Headers.merge(parentFiber.getRef(CurrentHeaders), headers)
+     });
+     if (discard) {
+-      return send;
++      return onStart.pipe(Effect.andThen(send));
+     }
+     let fiber;
+     return Effect.onInterrupt(Effect.callback(resume => {
+@@ -114,7 +120,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+         }
+       };
+       entries.set(id, entry);
+-      fiber = send.pipe(span ? Effect.withParentSpan(span, {
++      fiber = onStart.pipe(Effect.andThen(send), span ? Effect.withParentSpan(span, {
+         captureStackTrace: false
+       }) : identity, Effect.runForkWith(parentFiber.context));
+       fiber.addObserver(exit => {
+@@ -123,8 +129,9 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+         }
+       });
+     }), interruptors => {
++      const entry = entries.get(id);
+       entries.delete(id);
+-      return Effect.andThen(Fiber.interrupt(fiber), sendInterrupt(id, Array.from(interruptors), context));
++      return Effect.andThen(Fiber.interrupt(fiber), sendInterrupt(id, Array.from(interruptors), context, entry?.rpc._tag));
+     });
+   });
+   const onStreamRequest = Effect.fnUntraced(function* (rpc, middleware, payload, headers, streamBufferSize, context) {
+@@ -136,11 +143,17 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+     });
+     const fiber = Fiber.getCurrent();
+     const id = generateRequestId();
++    const onStart = Option.isSome(hooks) && hooks.value.onRequestStart ? hooks.value.onRequestStart({
++      id,
++      tag: rpc._tag,
++      stream: true
++    }) : Effect.void;
+     const scope = Context.getUnsafe(fiber.context, Scope.Scope);
+     yield* Scope.addFinalizerExit(scope, exit => {
+-      if (!entries.has(id)) return Effect.void;
++      const entry = entries.get(id);
++      if (!entry) return Effect.void;
+       entries.delete(id);
+-      return sendInterrupt(id, Exit.isFailure(exit) ? Array.from(Cause.interruptors(exit.cause)) : [], context);
++      return sendInterrupt(id, Exit.isFailure(exit) ? Array.from(Cause.interruptors(exit.cause)) : [], context, entry.rpc._tag);
+     });
+     const queue = yield* Queue.bounded(streamBufferSize);
+     entries.set(id, {
+@@ -148,9 +161,10 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+       rpc,
+       queue,
+       scope,
+-      context
++      context,
++      chunkCount: 0
+     });
+-    yield* middleware(message => options.onFromClient({
++    yield* onStart.pipe(Effect.andThen(middleware(message => options.onFromClient({
+       message,
+       context,
+       discard: false
+@@ -165,7 +179,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+         sampled: span.sampled
+       } : {}),
+       headers: Headers.merge(fiber.getRef(CurrentHeaders), headers)
+-    }).pipe(span ? Effect.withParentSpan(span, {
++    }))).pipe(span ? Effect.withParentSpan(span, {
+       captureStackTrace: false
+     }) : identity, Effect.catchCause(error => Queue.failCause(queue, error)), Effect.interruptible, Effect.forkIn(scope, {
+       startImmediately: true
+@@ -195,7 +209,10 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+       });
+     };
+   };
+-  const sendInterrupt = (requestId, interruptors, context) => Effect.callback(resume => {
++  const sendInterrupt = (requestId, interruptors, context, tag) => (Option.isSome(hooks) && hooks.value.onRequestInterrupt ? hooks.value.onRequestInterrupt({
++    id: requestId,
++    tag
++  }) : Effect.void).pipe(Effect.andThen(Effect.callback(resume => {
+     const parentFiber = Fiber.getCurrent();
+     const fiber = options.onFromClient({
+       message: {
+@@ -209,7 +226,7 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+     fiber.addObserver(() => {
+       resume(Effect.void);
+     });
+-  });
++  })));
+   const write = message => {
+     switch (message._tag) {
+       case "Chunk":
+@@ -217,7 +234,13 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+           const requestId = message.requestId;
+           const entry = entries.get(requestId);
+           if (!entry || entry._tag !== "Queue") return Effect.void;
+-          return Queue.offerAll(entry.queue, message.values).pipe(supportsAck ? Effect.flatMap(() => options.onFromClient({
++          const chunkCount = entry.chunkCount += message.values.length;
++          const onChunk = Option.isSome(hooks) && hooks.value.onRequestChunk ? hooks.value.onRequestChunk({
++            id: requestId,
++            tag: entry.rpc._tag,
++            chunkCount
++          }) : Effect.void;
++          return Queue.offerAll(entry.queue, message.values).pipe(Effect.andThen(onChunk), supportsAck ? Effect.flatMap(() => options.onFromClient({
+             message: {
+               _tag: "Ack",
+               requestId: message.requestId
+@@ -232,11 +255,18 @@ export const makeNoSerialization = /*#__PURE__*/Effect.fnUntraced(function* (gro
+           const entry = entries.get(requestId);
+           if (!entry) return Effect.void;
+           entries.delete(requestId);
++          const onExit = Option.isSome(hooks) && hooks.value.onRequestExit ? hooks.value.onRequestExit({
++            id: requestId,
++            tag: entry.rpc._tag,
++            stream: entry._tag === "Queue",
++            exit: message.exit
++          }) : Effect.void;
+           if (entry._tag === "Effect") {
+-            entry.resume(message.exit);
+-            return Effect.void;
++            return onExit.pipe(Effect.andThen(Effect.sync(() => {
++              entry.resume(message.exit);
++            })));
+           }
+-          return message.exit._tag === "Success" ? Queue.end(entry.queue) : Queue.failCause(entry.queue, message.exit.cause);
++          return onExit.pipe(Effect.andThen(message.exit._tag === "Success" ? Queue.end(entry.queue) : Queue.failCause(entry.queue, message.exit.cause)));
+         }
+       case "Defect":
+         {
+@@ -530,7 +560,7 @@ export const makeProtocolSocket = options => Protocol.make(Effect.fnUntraced(fun
+   const requestClientMap = new Map();
+   const write = yield* socket.writer;
+   let parser = serialization.makeUnsafe();
+-  const pinger = yield* makePinger(write(parser.encode(constPing)));
++  const pinger = yield* makePinger(write(parser.encode(constPing)), Option.isSome(hooks) ? hooks.value : undefined);
+   let currentError;
+   const onOpen = Effect.suspend(() => {
+     currentError = undefined;
+@@ -550,8 +580,7 @@ export const makeProtocolSocket = options => Protocol.make(Effect.fnUntraced(fun
+           body: () => {
+             const response = responses[i++];
+             if (response._tag === "Pong") {
+-              pinger.onPong();
+-              return Effect.void;
++              return pinger.onPong;
+             }
+             if ("requestId" in response) {
+               const clientId = requestClientMap.get(response.requestId);
+@@ -579,12 +608,12 @@ export const makeProtocolSocket = options => Protocol.make(Effect.fnUntraced(fun
+       }
+     }, {
+       onOpen
+-    }).pipe(Effect.raceFirst(Effect.flatMap(pinger.timeout, () => Effect.fail(new Socket.SocketError({
++    }).pipe(Effect.raceFirst(Effect.flatMap(pinger.timeout, () => (Option.isSome(hooks) && hooks.value.onPingTimeout ? hooks.value.onPingTimeout : Effect.void).pipe(Effect.andThen(Effect.fail(new Socket.SocketError({
+       reason: new Socket.SocketOpenError({
+         kind: "Timeout",
+         cause: new Error("ping timeout")
+       })
+-    })))));
++    })))))));
+   }).pipe(Effect.flatMap(() => Effect.fail(new Socket.SocketError({
+     reason: new Socket.SocketCloseError({
+       code: 1000
+@@ -626,20 +655,20 @@ export const makeProtocolSocket = options => Protocol.make(Effect.fnUntraced(fun
+   };
+ }));
+ const defaultRetryPolicy = /*#__PURE__*/Schedule.exponential(500, 1.5).pipe(/*#__PURE__*/Schedule.either(/*#__PURE__*/Schedule.spaced(5000)));
+-const makePinger = /*#__PURE__*/Effect.fnUntraced(function* (writePing) {
++const makePinger = /*#__PURE__*/Effect.fnUntraced(function* (writePing, hooks) {
+   let recievedPong = true;
+   const latch = Latch.makeUnsafe();
+   const reset = () => {
+     recievedPong = true;
+     latch.closeUnsafe();
+   };
+-  const onPong = () => {
++  const onPong = Effect.sync(() => {
+     recievedPong = true;
+-  };
++  }).pipe(Effect.andThen(hooks?.onPong ?? Effect.void));
+   yield* Effect.suspend(() => {
+     if (!recievedPong) return latch.open;
+     recievedPong = false;
+-    return writePing;
++    return (hooks?.onPing ?? Effect.void).pipe(Effect.andThen(writePing));
+   }).pipe(Effect.delay("5 seconds"), Effect.ignore, Effect.forever, Effect.interruptible, Effect.forkScoped);
+   return {
+     timeout: latch.await,
+@@ -773,6 +802,11 @@ export const makeProtocolWorker = options => Protocol.make(Effect.fnUntraced(fun
+  * @category protocol
+  */
+ export const layerProtocolWorker = /*#__PURE__*/flow(makeProtocolWorker, /*#__PURE__*/Layer.effect(Protocol));
++/**
++ * @since 4.0.0
++ * @category RequestHooks
++ */
++export class RequestHooks extends /*#__PURE__*/Context.Service()("effect/rpc/RpcClient/RequestHooks") {}
+ /**
+  * @since 4.0.0
+  * @category ConnectionHooks

From 74f7f0dd61f5b017d88c00c8bca1ca11ca020dd0 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 1 May 2026 17:12:25 -0700
Subject: [PATCH 69/74] Refine mobile run context and banner alignment

- Show static workspace labels for locked single-environment runs
- Keep dismiss-only composer banners aligned on mobile
- Update parity coverage for the new mobile behavior
---
 apps/web/src/components/BranchToolbar.tsx     | 47 ++++++++++++++---
 apps/web/src/components/ChatView.browser.tsx  | 51 +++++++++++++++++--
 .../components/chat/ComposerBannerStack.tsx   | 10 +++-
 3 files changed, 96 insertions(+), 12 deletions(-)

diff --git a/apps/web/src/components/BranchToolbar.tsx b/apps/web/src/components/BranchToolbar.tsx
index 8fca370c61f..4da06e042d9 100644
--- a/apps/web/src/components/BranchToolbar.tsx
+++ b/apps/web/src/components/BranchToolbar.tsx
@@ -8,7 +8,7 @@ import {
   FolderIcon,
   MonitorIcon,
 } from "lucide-react";
-import { memo, useMemo } from "react";
+import { Children, memo, useMemo, type ReactNode } from "react";
 
 import { useComposerDraftStore, type DraftId } from "../composerDraftStore";
 import { useIsMobile } from "../hooks/useMediaQuery";
@@ -20,6 +20,7 @@ import {
   resolveCurrentWorkspaceLabel,
   resolveEnvModeLabel,
   resolveEffectiveEnvMode,
+  resolveLockedWorkspaceLabel,
 } from "./BranchToolbar.logic";
 import { BranchToolbarBranchSelector } from "./BranchToolbarBranchSelector";
 import { BranchToolbarEnvironmentSelector } from "./BranchToolbarEnvironmentSelector";
@@ -64,6 +65,28 @@ interface MobileRunContextSelectorProps {
   onEnvModeChange: (mode: EnvMode) => void;
 }
 
+function SplitIcon({
+  children,
+  className,
+}: {
+  readonly children: ReactNode;
+  readonly className?: string;
+}) {
+  const [left, right] = Children.toArray(children);
+
+  return (
+    <span className={className} aria-hidden="true">
+      <span className="absolute inset-0 overflow-hidden [clip-path:polygon(0_0,70%_0,30%_100%,0_100%)] [&>svg]:size-full">
+        {left}
+      </span>
+      <span className="absolute inset-0 overflow-hidden [clip-path:polygon(70%_0,100%_0,100%_100%,30%_100%)] [&>svg]:size-full">
+        {right}
+      </span>
+      <span className="absolute left-1/2 top-1/2 h-[145%] w-0.5 -translate-x-1/2 -translate-y-1/2 rotate-45 rounded-full bg-current" />
+    </span>
+  );
+}
+
 const MobileRunContextSelector = memo(function MobileRunContextSelector({
   envLocked,
   envModeLocked,
@@ -85,17 +108,27 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({
       : activeWorktreePath
         ? FolderGitIcon
         : FolderIcon;
+  const workspaceLabel = envModeLocked
+    ? resolveLockedWorkspaceLabel(activeWorktreePath)
+    : effectiveEnvMode === "worktree"
+      ? resolveEnvModeLabel("worktree")
+      : resolveCurrentWorkspaceLabel(activeWorktreePath);
   const isLocked = envLocked || envModeLocked;
-  const icon = (
-    <span className="relative size-3 shrink-0" aria-hidden="true">
-      <CloudIcon className="absolute inset-0 size-3" style={{ clipPath: "inset(0 50% 0 0)" }} />
-      <WorkspaceIcon className="absolute inset-0 size-3" style={{ clipPath: "inset(0 0 0 50%)" }} />
-    </span>
+  const EnvironmentIcon = activeEnvironment?.isPrimary ? MonitorIcon : CloudIcon;
+  const icon = showEnvironmentPicker ? (
+    <SplitIcon className="relative size-3.5 shrink-0">
+      <EnvironmentIcon />
+      <WorkspaceIcon />
+    </SplitIcon>
+  ) : (
+    <WorkspaceIcon className="size-3 shrink-0" />
   );
   const triggerContent = (
     <>
       {icon}
-      <span className="min-w-0 truncate">{activeEnvironment?.label ?? "Run on"}</span>
+      <span className="min-w-0 truncate">
+        {showEnvironmentPicker ? (activeEnvironment?.label ?? "Run on") : workspaceLabel}
+      </span>
     </>
   );
 
diff --git a/apps/web/src/components/ChatView.browser.tsx b/apps/web/src/components/ChatView.browser.tsx
index 1b8388e466d..f5b491d061d 100644
--- a/apps/web/src/components/ChatView.browser.tsx
+++ b/apps/web/src/components/ChatView.browser.tsx
@@ -1663,7 +1663,7 @@ describe("ChatView timeline estimator parity (full app)", () => {
     document.body.innerHTML = "";
   });
 
-  it("renders locked mobile run context as a static environment label", async () => {
+  it("renders locked single-environment mobile run context as a static workspace label", async () => {
     const mounted = await mountChatView({
       viewport: COMPACT_FOOTER_VIEWPORT,
       snapshot: createSnapshotForTargetUser({
@@ -1676,12 +1676,55 @@ describe("ChatView timeline estimator parity (full app)", () => {
       await waitForElement(
         () =>
           Array.from(document.querySelectorAll<HTMLElement>("span")).find(
-            (element) => element.textContent?.trim() === "This device",
+            (element) => element.textContent?.trim() === "Local checkout",
           ) ?? null,
-        "Unable to find static mobile environment label.",
+        "Unable to find static mobile workspace label.",
       );
 
-      expect(findButtonByText("This device")).toBeNull();
+      expect(findButtonByText("Local checkout")).toBeNull();
+    } finally {
+      await mounted.cleanup();
+    }
+  });
+
+  it("keeps dismiss-only composer banners aligned on mobile", async () => {
+    const mounted = await mountChatView({
+      viewport: COMPACT_FOOTER_VIEWPORT,
+      snapshot: createSnapshotForTargetUser({
+        targetMessageId: "msg-user-mobile-version-banner" as MessageId,
+        targetText: "mobile version banner",
+      }),
+      configureFixture: (nextFixture) => {
+        nextFixture.serverConfig = {
+          ...nextFixture.serverConfig,
+          environment: {
+            ...nextFixture.serverConfig.environment,
+            serverVersion: "9.9.9",
+          },
+        };
+      },
+    });
+
+    try {
+      const banner = await waitForElement(
+        () =>
+          Array.from(document.querySelectorAll<HTMLElement>('[data-slot="alert"]')).find(
+            (element) => element.textContent?.includes("Client and server versions differ"),
+          ) ?? null,
+        "Unable to find version mismatch banner.",
+      );
+      const title = banner.querySelector<HTMLElement>('[data-slot="alert-title"]');
+      const description = banner.querySelector<HTMLElement>('[data-slot="alert-description"]');
+      const dismissButton = banner.querySelector<HTMLButtonElement>(
+        'button[aria-label="Dismiss version mismatch warning"]',
+      );
+
+      expect(title).toBeTruthy();
+      expect(description).toBeTruthy();
+      expect(dismissButton).toBeTruthy();
+      expect(dismissButton!.getBoundingClientRect().top).toBeLessThan(
+        description!.getBoundingClientRect().top,
+      );
     } finally {
       await mounted.cleanup();
     }
diff --git a/apps/web/src/components/chat/ComposerBannerStack.tsx b/apps/web/src/components/chat/ComposerBannerStack.tsx
index c59c251ab7c..9901237fdf0 100644
--- a/apps/web/src/components/chat/ComposerBannerStack.tsx
+++ b/apps/web/src/components/chat/ComposerBannerStack.tsx
@@ -161,13 +161,21 @@ function ComposerBannerStackAlert({
   readonly exiting: boolean;
   readonly onDismissRequest: () => void;
 }) {
+  const dismissOnly = item.onDismiss && !item.actions;
+
   return (
     <Alert variant={item.variant}>
       {item.icon}
       <AlertTitle>{item.title}</AlertTitle>
       {item.description ? <AlertDescription>{item.description}</AlertDescription> : null}
       {item.actions || item.onDismiss ? (
-        <AlertAction>
+        <AlertAction
+          className={
+            dismissOnly
+              ? "max-sm:col-start-3 max-sm:row-start-1 max-sm:mt-0 max-sm:self-start"
+              : undefined
+          }
+        >
           {item.actions}
           {item.onDismiss ? (
             <Button

From 43b0d6d8ac88c1b18982382d6ab3f552e520f54e Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 1 May 2026 22:38:28 -0700
Subject: [PATCH 70/74] Simplify mobile branch toolbar icon

- Replace the split stacked icon with a simpler inline icon pair in the mobile run context selector
- Remove the custom `SplitIcon` helper
---
 apps/web/src/components/BranchToolbar.tsx | 32 ++++-------------------
 1 file changed, 5 insertions(+), 27 deletions(-)

diff --git a/apps/web/src/components/BranchToolbar.tsx b/apps/web/src/components/BranchToolbar.tsx
index 4da06e042d9..44f48955745 100644
--- a/apps/web/src/components/BranchToolbar.tsx
+++ b/apps/web/src/components/BranchToolbar.tsx
@@ -8,7 +8,7 @@ import {
   FolderIcon,
   MonitorIcon,
 } from "lucide-react";
-import { Children, memo, useMemo, type ReactNode } from "react";
+import { memo, useMemo } from "react";
 
 import { useComposerDraftStore, type DraftId } from "../composerDraftStore";
 import { useIsMobile } from "../hooks/useMediaQuery";
@@ -65,28 +65,6 @@ interface MobileRunContextSelectorProps {
   onEnvModeChange: (mode: EnvMode) => void;
 }
 
-function SplitIcon({
-  children,
-  className,
-}: {
-  readonly children: ReactNode;
-  readonly className?: string;
-}) {
-  const [left, right] = Children.toArray(children);
-
-  return (
-    <span className={className} aria-hidden="true">
-      <span className="absolute inset-0 overflow-hidden [clip-path:polygon(0_0,70%_0,30%_100%,0_100%)] [&>svg]:size-full">
-        {left}
-      </span>
-      <span className="absolute inset-0 overflow-hidden [clip-path:polygon(70%_0,100%_0,100%_100%,30%_100%)] [&>svg]:size-full">
-        {right}
-      </span>
-      <span className="absolute left-1/2 top-1/2 h-[145%] w-0.5 -translate-x-1/2 -translate-y-1/2 rotate-45 rounded-full bg-current" />
-    </span>
-  );
-}
-
 const MobileRunContextSelector = memo(function MobileRunContextSelector({
   envLocked,
   envModeLocked,
@@ -116,10 +94,10 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({
   const isLocked = envLocked || envModeLocked;
   const EnvironmentIcon = activeEnvironment?.isPrimary ? MonitorIcon : CloudIcon;
   const icon = showEnvironmentPicker ? (
-    <SplitIcon className="relative size-3.5 shrink-0">
-      <EnvironmentIcon />
-      <WorkspaceIcon />
-    </SplitIcon>
+    <span className="inline-flex shrink-0 items-center gap-0.5">
+      <EnvironmentIcon className="size-3 shrink-0" />
+      <WorkspaceIcon className="size-3 shrink-0" />
+    </span>
   ) : (
     <WorkspaceIcon className="size-3 shrink-0" />
   );

From 99c054412142cc855cc4984e9d24f158066ee07b Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 1 May 2026 22:45:21 -0700
Subject: [PATCH 71/74] Fix mobile environment icon spacing

- Cancel button SVG margin override in the mobile run context selector
- Keep the environment/workspace icon gap visually at 2px when the picker is shown
---
 apps/web/src/components/BranchToolbar.tsx | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/apps/web/src/components/BranchToolbar.tsx b/apps/web/src/components/BranchToolbar.tsx
index 44f48955745..27c5c311c60 100644
--- a/apps/web/src/components/BranchToolbar.tsx
+++ b/apps/web/src/components/BranchToolbar.tsx
@@ -94,9 +94,11 @@ const MobileRunContextSelector = memo(function MobileRunContextSelector({
   const isLocked = envLocked || envModeLocked;
   const EnvironmentIcon = activeEnvironment?.isPrimary ? MonitorIcon : CloudIcon;
   const icon = showEnvironmentPicker ? (
+    // Button's base styles apply `-mx-0.5` to descendant SVGs, which eats 4px
+    // out of whatever gap we set. mx-0! cancels that so gap-0.5 reads as 2px.
     <span className="inline-flex shrink-0 items-center gap-0.5">
-      <EnvironmentIcon className="size-3 shrink-0" />
-      <WorkspaceIcon className="size-3 shrink-0" />
+      <EnvironmentIcon className="size-3 shrink-0 mx-0!" />
+      <WorkspaceIcon className="size-3 shrink-0 mx-0!" />
     </span>
   ) : (
     <WorkspaceIcon className="size-3 shrink-0" />

From 58277c6873983a733f508e9727c17ca10c014791 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Fri, 1 May 2026 22:49:28 -0700
Subject: [PATCH 72/74] Fix release smoke patched dependencies

Co-authored-by: codex <codex@users.noreply.github.com>
---
 scripts/release-smoke.ts | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/scripts/release-smoke.ts b/scripts/release-smoke.ts
index 27308134f1a..0bdf8b32afa 100644
--- a/scripts/release-smoke.ts
+++ b/scripts/release-smoke.ts
@@ -38,6 +38,17 @@ function copyWorkspaceManifestFixture(targetRoot: string): void {
     mkdirSync(dirname(destinationPath), { recursive: true });
     cpSync(sourcePath, destinationPath);
   }
+
+  const packageJson = JSON.parse(readFileSync(resolve(repoRoot, "package.json"), "utf8")) as {
+    readonly patchedDependencies?: Record<string, string>;
+  };
+
+  for (const relativePath of Object.values(packageJson.patchedDependencies ?? {})) {
+    const sourcePath = resolve(repoRoot, relativePath);
+    const destinationPath = resolve(targetRoot, relativePath);
+    mkdirSync(dirname(destinationPath), { recursive: true });
+    cpSync(sourcePath, destinationPath);
+  }
 }
 
 function writeMacManifestFixtures(targetRoot: string): { arm64Path: string; x64Path: string } {

From f5f81277fd5d19a833a8049da9b80516f4629943 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sat, 2 May 2026 16:18:30 -0700
Subject: [PATCH 73/74] Fix web API compatibility after rebase

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/web/src/localApi.ts        | 4 ++--
 apps/web/src/rpc/wsRpcClient.ts | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/apps/web/src/localApi.ts b/apps/web/src/localApi.ts
index 17fa75af675..c9120e53bb8 100644
--- a/apps/web/src/localApi.ts
+++ b/apps/web/src/localApi.ts
@@ -135,9 +135,9 @@ function createBrowserLocalApi(rpcClient?: WsRpcClient): LocalApi {
         rpcClient
           ? rpcClient.server.updateSettings(patch)
           : Promise.reject(unavailableLocalBackendError()),
-      discoverSourceControl: (input) =>
+      discoverSourceControl: () =>
         rpcClient
-          ? rpcClient.server.discoverSourceControl(input)
+          ? rpcClient.server.discoverSourceControl()
           : Promise.reject(unavailableLocalBackendError()),
     },
   };
diff --git a/apps/web/src/rpc/wsRpcClient.ts b/apps/web/src/rpc/wsRpcClient.ts
index 1efcb101aab..d30df9fc971 100644
--- a/apps/web/src/rpc/wsRpcClient.ts
+++ b/apps/web/src/rpc/wsRpcClient.ts
@@ -180,7 +180,7 @@ export function createWsRpcClient(transport: WsTransport): WsRpcClient {
             current = applyGitStatusStreamEvent(current, event);
             listener(current);
           },
-          { ...options, tag: WS_METHODS.subscribeGitStatus },
+          { ...options, tag: WS_METHODS.subscribeVcsStatus },
         );
       },
       listRefs: (input) => transport.request((client) => client[WS_METHODS.vcsListRefs](input)),

From 86e1b678e7dca7fb616eec30fdce888add47e52a Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Sun, 3 May 2026 20:40:13 -0700
Subject: [PATCH 74/74] Fix PR review comments

Co-authored-by: codex <codex@users.noreply.github.com>
---
 apps/web/src/rpc/wsTransport.test.ts | 10 +---------
 apps/web/src/rpc/wsTransport.ts      |  2 +-
 packages/ssh/src/config.test.ts      | 15 ++++++++++++++-
 packages/ssh/src/config.ts           |  1 +
 packages/ssh/src/tunnel.test.ts      | 18 ++++++++++++++++++
 packages/ssh/src/tunnel.ts           |  6 ++----
 6 files changed, 37 insertions(+), 15 deletions(-)

diff --git a/apps/web/src/rpc/wsTransport.test.ts b/apps/web/src/rpc/wsTransport.test.ts
index 4fe6ed254ed..84d886668fb 100644
--- a/apps/web/src/rpc/wsTransport.test.ts
+++ b/apps/web/src/rpc/wsTransport.test.ts
@@ -327,15 +327,7 @@ describe("WsTransport", () => {
 
     await transport.dispose();
 
-    expect(onClose).toHaveBeenCalledWith(
-      {
-        code: 1000,
-        reason: "",
-      },
-      {
-        intentional: true,
-      },
-    );
+    expect(onClose).not.toHaveBeenCalled();
     expect(getWsConnectionStatus()).toMatchObject({
       connectionLabel: "Remote Mac mini",
       phase: "connected",
diff --git a/apps/web/src/rpc/wsTransport.ts b/apps/web/src/rpc/wsTransport.ts
index ebdac483ac8..316be9db9ee 100644
--- a/apps/web/src/rpc/wsTransport.ts
+++ b/apps/web/src/rpc/wsTransport.ts
@@ -247,7 +247,7 @@ export class WsTransport {
       Layer.mergeAll(
         createWsRpcProtocolLayer(this.url, {
           ...this.lifecycleHandlers,
-          isActive: () => this.activeSessionId === sessionId,
+          isActive: () => !this.disposed && this.activeSessionId === sessionId,
           isCloseIntentional: () =>
             this.disposed ||
             this.intentionalCloseDepth > 0 ||
diff --git a/packages/ssh/src/config.test.ts b/packages/ssh/src/config.test.ts
index 91f8f62c070..0e2f5472ddf 100644
--- a/packages/ssh/src/config.test.ts
+++ b/packages/ssh/src/config.test.ts
@@ -25,7 +25,13 @@ describe("ssh config", () => {
       yield* fs.makeDirectory(path.join(sshDir, "config.d"), { recursive: true });
       yield* fs.writeFileString(
         path.join(sshDir, "config"),
-        ["Host devbox", "  HostName devbox.example.com", "Include config.d/*.conf", ""].join("\n"),
+        [
+          "Host devbox",
+          "  HostName devbox.example.com",
+          "Host=equalsbox",
+          "Include=config.d/*.conf",
+          "",
+        ].join("\n"),
       );
       yield* fs.writeFileString(
         path.join(sshDir, "config.d", "team.conf"),
@@ -63,6 +69,13 @@ describe("ssh config", () => {
           port: null,
           source: "ssh-config",
         },
+        {
+          alias: "equalsbox",
+          hostname: "equalsbox",
+          username: null,
+          port: null,
+          source: "ssh-config",
+        },
         {
           alias: "known.example.com",
           hostname: "known.example.com",
diff --git a/packages/ssh/src/config.ts b/packages/ssh/src/config.ts
index 24f29e745ac..b326f66a468 100644
--- a/packages/ssh/src/config.ts
+++ b/packages/ssh/src/config.ts
@@ -13,6 +13,7 @@ function stripInlineComment(line: string): string {
 
 function splitDirectiveArgs(value: string): ReadonlyArray<string> {
   return value
+    .replace(/=(?!=)/gu, " ")
     .trim()
     .split(/\s+/u)
     .map((entry) => entry.trim())
diff --git a/packages/ssh/src/tunnel.test.ts b/packages/ssh/src/tunnel.test.ts
index 5a03ce25ac6..f6c7598ef75 100644
--- a/packages/ssh/src/tunnel.test.ts
+++ b/packages/ssh/src/tunnel.test.ts
@@ -12,6 +12,7 @@ import {
   buildRemotePairingScript,
   buildRemoteStopScript,
   buildRemoteT3RunnerScript,
+  describeReadinessCause,
   issueRemotePairingToken,
   REMOTE_PICK_PORT_SCRIPT,
   SshEnvironmentManager,
@@ -192,6 +193,23 @@ describe("ssh tunnel scripts", () => {
     ),
   );
 
+  it("preserves primitive readiness reason values in diagnostic output", () => {
+    assert.deepEqual(
+      describeReadinessCause({
+        _tag: "HttpClientError",
+        message: "Backend readiness probe failed.",
+        reason: "authentication failed",
+        cause: "upstream closed",
+      }),
+      {
+        _tag: "HttpClientError",
+        message: "Backend readiness probe failed.",
+        reason: "authentication failed",
+        cause: "upstream closed",
+      },
+    );
+  });
+
   it.effect("accepts pretty-printed pairing JSON from the remote CLI", () => {
     const target = {
       alias: "devbox",
diff --git a/packages/ssh/src/tunnel.ts b/packages/ssh/src/tunnel.ts
index 131b1612f8a..302341d071e 100644
--- a/packages/ssh/src/tunnel.ts
+++ b/packages/ssh/src/tunnel.ts
@@ -192,7 +192,7 @@ function applyScriptPlaceholders(
   return result;
 }
 
-function describeReadinessCause(cause: unknown): unknown {
+export function describeReadinessCause(cause: unknown): unknown {
   if (cause instanceof SshReadinessError) {
     return {
       _tag: cause._tag,
@@ -215,9 +215,7 @@ function describeReadinessCause(cause: unknown): unknown {
   return {
     ...(typeof record._tag === "string" ? { _tag: record._tag } : {}),
     ...(typeof record.message === "string" ? { message: record.message } : {}),
-    ...(typeof record.reason === "object" && record.reason !== null
-      ? { reason: describeReadinessCause(record.reason) }
-      : {}),
+    ...(record.reason === undefined ? {} : { reason: describeReadinessCause(record.reason) }),
     ...(record.cause === undefined ? {} : { cause: describeReadinessCause(record.cause) }),
   };
 }